5.8 KiB
name, description, depth, links
| name | description | depth | links | ||||
|---|---|---|---|---|---|---|---|
| Core Orchestration Submodule Spec | Specification for :core:orchestration – execution kernel | 2 |
|
:core:orchestration module specification
version: 0.1-draft status: foundational specification
1. purpose
:core:orchestration is the execution kernel of correx. It coordinates the entire workflow lifecycle by composing:
- session management
- stage scheduling
- context building
- inference execution
- validation
- approvals
- transitions
It is the "brain" that wires together all other core modules and ensures work progresses deterministically according to the configured graph.
2. responsibilities
:core:orchestration owns:
- workflow execution loop
- stage scheduling and sequencing
- orchestration state machine (separate from session state)
- retry coordination
- cancellation propagation
- concurrency control within a session
- orchestration event aggregation (orchestration-level events)
- replay orchestration (decides which components to re-invoke)
- service‑level observability (the "big picture" metrics)
3. non-responsibilities
:core:orchestration MUST NOT own:
- domain logic (that’s in events, transitions, validation, etc.)
- persistence
- inference provider implementation
- user interaction (router handles that)
- plugin execution
- UI updates
It coordinates; it does not implement low‑level mechanics.
4. architectural role
:core:orchestration acts as:
- the top‑level orchestrator
- the only component that directly calls other core modules in a defined sequence
- the guardian of workflow integrity
It is the closest thing to a “main loop” of the harness.
5. design principles
5.1 stateless orchestration
The orchestrator itself holds no persistent state. All state lives in events and projections. The orchestrator loads current projection at start, executes steps, emits events, and exits.
5.2 deterministic coordination
Given the same initial projection and the same event history, the orchestration sequence (which stage to run next, when to retry) is fully deterministic.
5.3 explicit composition
Every step (context, inference, validation, transition) is called explicitly and synchronously within a coroutine scope. No hidden side‑effects.
5.4 cancellation ownership
The orchestrator owns the cancellation token for a session and ensures it propagates to all child jobs (inference, tools, etc.).
6. execution loop
while session is active:
determine next stage (from transition engine + current projection)
build context pack
schedule inference
wait for artifact
validate artifact
if approval needed: wait for decision
evaluate transition rules
emit TransitionExecuted event
update projection
Each iteration is a transaction in the event stream.
7. orchestration events
:core:orchestration emits high‑level events:
WorkflowStartedWorkflowCompletedWorkflowFailedOrchestrationPausedOrchestrationResumedRetryAttempted
It does not own domain events but links them via correlation.
8. consumed events
Orchestration listens to all domain events through a projection, but specifically reacts to:
SessionCreated(trigger start)UserInput(steering, approvals)ArtifactValidated/ArtifactRejectedApprovalGranted- system events for health/timeouts
9. state model
The orchestration loop tracks an ephemeral OrchestrationState (in‑memory during execution) that holds:
- current stage
- retry count
- pause reason
- pending approval flag
This state is never persisted directly; it is rebuilt from events.
10. retry coordination
Orchestration evaluates retry policies after failures (validation, inference). It may:
- re‑execute the same stage with adjusted context (failure reason injected)
- branch to a recovery stage
- terminate
Retries are bounded and emit RetryAttempted.
11. replay mode support
During replay, the orchestrator runs the same loop but can skip inference (using recorded artifacts) or skip validation (trusting recorded outcomes). It follows a replay strategy configured per session.
12. concurrency model
All orchestration for a session runs in a single coroutine scope. No parallel stage execution (v1). Concurrency is limited to inference and tool calls within a stage being asynchronous but serialized from the orchestrator’s viewpoint.
13. failure semantics
If orchestration encounters an unrecoverable error, it emits WorkflowFailed and terminates the session safely. Partial state is preserved via events.
14. observable requirements
Must expose:
- workflow duration
- stage‑level timing
- retry frequency
- bottlenecks (idle time in approval)
- cancellation triggers
15. security boundaries
Orchestration does not directly access external resources. It receives validated data only. It enforces no security beyond coordination: all gates are handled by validation/approvals/policies.
16. extension model
Orchestration logic is not pluggable in v1 (to preserve determinism), but hook points for custom stage scheduling strategies may be added later.
17. forbidden patterns
- direct manipulation of projections
- skipping validation steps
- hidden retry loops
- mutable orchestration state persisted outside events
18. testing requirements
- full workflow simulation with mock inference
- retry path coverage
- replay consistency
- cancellation during each phase
19. philosophy
Orchestration is the conductor, not the musician. It knows the score, calls in each section at the right time, and ensures the performance follows the plan—even when the musicians occasionally improvise.