correx/docs/modules/core-orchestration-submodule-spec.md

name, description, depth, links

name	description	depth	links
Core Kernel Submodule Spec	Specification for :core:kernel – execution kernel	2	../index.md ./core-module-spec.md ./core-sessions-submodule-spec.md ./core-transitions-submodule-spec.md

:core:kernel module specification

version: 0.2 status: implemented (SessionOrchestrator + ReplayOrchestrator)

---

1. purpose

:core:kernel 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:kernel 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:kernel 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:kernel 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:kernel emits high‑level events:

• WorkflowStarted
• WorkflowCompleted
• WorkflowFailed
• OrchestrationPaused
• OrchestrationResumed
• RetryAttempted

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 / ArtifactRejected
• ApprovalGranted
• 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.