Engine Functionality

Overview of CaDEngine functionality and detailed documentation pages.

The Engine provides four core functional areas that work together to manage the complete lifecycle of package revisions:

Functional Areas

Lifecycle Management

Enforces package lifecycle state machine and business rules through:

State Transitions: Draft → Proposed → Published → DeletionProposed
State-Based Constraints: Different mutability rules per lifecycle state
Validation: Creation, update, transition, and resource update validation
Audit Tracking: PublishedBy, PublishedAt, tasks history, and resource versions

For detailed architecture and process flows, see Lifecycle Management.

Validation & Business Rules

Validates operations and enforces business rules to ensure correctness through:

Lifecycle Validation: Cannot create Published/DeletionProposed packages
Task Validation: Maximum one task during creation, defaults to init
Workspace Name Uniqueness: Prevents duplicate workspace names per package
Package Name Validation: Prevents invalid package names
Clone Validation: Clone can only create new packages, not new revisions
Upgrade Validation: Source revisions must be published
Package Path Overlap: Prevents nested package structures
Optimistic Locking: Resource version checking for concurrent modification prevention

For detailed architecture and process flows, see Validation & Business Rules.

Draft-Commit Workflow Orchestration

Orchestrates the draft-commit pattern for all package revision modifications through:

Draft Phase: Package revisions are mutable and changes are applied
Commit Phase: Draft closed to create immutable package revision
Rollback Mechanism: Automatic cleanup on errors to ensure atomicity
Atomicity: Either all changes succeed or all fail
Isolation: Draft changes don’t affect other revisions

For detailed architecture and process flows, see Draft-Commit Workflow Orchestration.

Task Coordination

Coordinates task execution by delegating to the Task Handler through:

ApplyTask: Execute task during package revision creation (init, clone, edit, upgrade)
DoPRMutations: Apply mutations during package revision update
DoPRResourceMutations: Apply resource mutations and execute render
Function Runtime Integration: Builtin and gRPC function execution
Error Handling: Task errors trigger rollback and cleanup

For detailed architecture and process flows, see Task Coordination.

How They Work Together

┌─────────────────────────────────────────────────────────┐
│                      Engine                             │
│                                                         │
│  ┌──────────────────┐      ┌──────────────────┐         │
│  │   Validation &   │      │   Lifecycle      │         │
│  │  Business Rules  │ ───> │   Management     │         │
│  │                  │      │                  │         │
│  │  • Lifecycle     │      │  • Transitions   │         │
│  │  • Tasks         │      │  • Constraints   │         │
│  │  • Workspace     │      │  • Enforcement   │         │
│  │  • Clone/Upgrade │      │                  │         │
│  │  • Path Overlap  │      │                  │         │
│  │  • Opt. Locking  │      │                  │         │
│  └──────────────────┘      └──────────────────┘         │
│           │                         │                   │
│           └────────┬────────────────┘                   │
│                    ↓                                    │
│  ┌──────────────────┐      ┌──────────────────┐         │
│  │  Draft-Commit    │      │      Task        │         │
│  │  Orchestration   │ ───> │  Coordination    │         │
│  │                  │      │                  │         │
│  │  • Open Draft    │      │  • ApplyTask     │         │
│  │  • Apply Changes │      │  • DoPRMutations │         │
│  │  • Close Draft   │      │  • DoPRResource  │         │
│  │  • Rollback      │      │    Mutations     │         │
│  └──────────────────┘      └──────────────────┘         │
└─────────────────────────────────────────────────────────┘

Integration flow:

Validation & Business Rules validate operations before execution
Lifecycle Management enforces state machine rules and constraints
Draft-Commit Orchestration manages the mutable draft workflow with rollback
Task Coordination delegates to task handler for package transformations

Each functional area is documented in detail on its own page with architecture diagrams, process flows, and implementation specifics.

What the Engine Does NOT Do

The Engine does not implement package/package revision CRUD operations - it delegates to repository adapters:

Delegation operations:

ListPackageRevisions: Opens repo through cache → delegates to repo.ListPackageRevisions
ListPackages: Opens repo through cache → delegates to repo.ListPackages
CreatePackage: Opens repo through cache → delegates to repo.CreatePackage
DeletePackage: Opens repo through cache → delegates to repo.DeletePackage
DeletePackageRevision: Opens repo through cache → delegates to repo.DeletePackageRevision

These are thin wrappers that open the repository through the cache and delegate to repository adapters. The actual storage operations (Git commits, tags, branches) are handled by repository adapters, not the Engine.

The Engine’s real work is orchestration, validation, lifecycle enforcement, and task coordination - not storage operations.