# Epic 10 — Orchestration Kernel (Lifecycle, Retry, Replay)

## completed deliverables

### 1. orchestration state and status model

implemented a strict state model for orchestration lifecycle tracking.

final structures:

* `OrchestrationStatus` (enum)
* `OrchestrationState`

key properties:

* immutable status transitions
* explicit lifecycle tracking (IDLE → RUNNING → PAUSED/COMPLETED/FAILED)
* retry count tracking
* pause reason tracking
* pending approval flag
* failure reason tracking

status values:

* IDLE — initial state, awaiting workflow start
* RUNNING — active stage execution
* PAUSED — awaiting approval or user action
* COMPLETED — successful workflow termination
* FAILED — workflow terminated due to error
* CANCELED — workflow terminated due to cancellation

---

### 2. workflow event model

introduced workflow lifecycle events as the orchestration backbone.

final structure:

* `WorkflowStartedEvent` — marks workflow initiation
* `WorkflowCompletedEvent` — marks successful completion
* `WorkflowFailedEvent` — marks failure with reason and retry context

properties:

* explicit lifecycle boundaries
* causality-safe event emission
* retry-exhausted tracking for failure events

---

### 3. orchestration pause/resume events

introduced explicit pause/resume semantics for approval workflows.

final structure:

* `OrchestrationPausedEvent` — marks pause with reason (APPROVAL_PENDING, USER_REQUESTED)
* `OrchestrationResumedEvent` — marks resumption after approval

properties:

* explicit pause reasons for auditability
* stage-aware pause tracking
* deterministic resume semantics

---

### 4. inference state management (read-only projection)

implemented inference state as a read-only projection for auditability.

final structures:

* `InferenceRecord` — immutable inference attempt snapshot
* `InferenceState` — collection of inference records
* `InferenceReducer` / `DefaultInferenceReducer`
* `InferenceProjector`
* `InferenceRepository`

key properties:

* append-only inference history
* per-request tracking (requestId, providerId, stageId)
* status tracking (started, completed, failed, timed out)
* token usage and latency recording
* failure reason persistence

---

### 5. retry coordination system

implemented deterministic retry logic with exponential backoff support.

final structures:

* `RetryPolicy` — configures maxAttempts and backoffMs
* `RetryCoordinator` / `DefaultRetryCoordinator`
* `RetryAttemptedEvent` — audit trail for retry attempts

key properties:

* attempt-based retry control
* configurable backoff delays
* event-emitted retry tracking
* failure reason preservation

---

### 6. replay orchestrator (deterministic execution)

implemented deterministic replay for testing and audit scenarios.

final structures:

* `ReplayOrchestrator` — concrete implementation of `SessionOrchestrator`
* `ReplayInferenceProvider` — artifact-based inference
* `ReplayArtifactMissingException` — replay failure signal
* `ReplayStrategy` — SkipInference, SkipValidation, Full

key properties:

* bypasses live inference, uses recorded artifacts
* deterministic output for testing
* strategy-configurable replay depth
* exception-based artifact missing detection

---

### 7. session orchestrator abstraction

implemented abstract base for orchestration implementations.

final structures:

* `SessionOrchestrator` (abstract) — base interface
* `DefaultSessionOrchestrator` — concrete implementation

key properties:

* unified stage execution model
* inference routing integration
* validation pipeline integration
* approval engine integration
* event emission abstraction
* cancellation support

---

### 8. stage execution and outcome model

implemented stage execution result types for orchestration decisions.

final structure:

* `StageOutcome` (sealed interface, renamed from StageExecutionResult)
  * `Success` — stage completed with artifact
  * `ValidationFailure` — validation failed, retryable flag
  * `InferenceFailure` — inference failed, retryable flag
  * `ApprovalRequired` — approval pending
  * `Cancelled` — stage cancelled

properties:

* outcome-based decision making
* retryability metadata
* artifact capture for replay

---

### 9. orchestration configuration

introduced configurable orchestration parameters.

final structure:

* `OrchestrationConfig`

key properties:

* `retryPolicy` — RetryPolicy instance
* `replayStrategy` — ReplayStrategy instance
* `stageTimeoutMs` — per-stage timeout configuration

---

### 10. serialization system (orchestration events)

registered all orchestration events in the serialization module.

components:

* `Serialization.kt` in `:core:events`
* 6 new orchestration events registered:
  * `WorkflowStartedEvent`
  * `WorkflowCompletedEvent`
  * `WorkflowFailedEvent`
  * `OrchestrationPausedEvent`
  * `OrchestrationResumedEvent`
  * `RetryAttemptedEvent`

* `InferenceStatus` — `TIMED_OUT` added

---

### 11. testing fixtures (extended)

extended test fixtures for comprehensive coverage.

components:

* `TransitionFixtures`
* `InferenceFixtures`
* `ContextFixtures`
* `ValidationFixtures`

---

# final architecture after Epic 10

```text id="e10"
Orchestration Kernel
├── SessionOrchestrator (abstract base)
│   ├── DefaultSessionOrchestrator
│   └── ReplayOrchestrator
│
├── State Management
│   ├── OrchestrationState
│   ├── InferenceState
│   └── Event Replayer
│
├── Retry System
│   ├── RetryPolicy
│   ├── RetryCoordinator
│   └── DefaultRetryCoordinator
│
└── Replay Support
    ├── ReplayStrategy
    ├── ReplayInferenceProvider
    └── ReplayArtifactMissingException
```

---

# major architectural outcomes

Epic 10 established:

* orchestration lifecycle management
* deterministic replay capability
* retry coordination with audit trail
* inference state projection
* stage outcome model
* orchestrator abstraction layer
* pause/resume semantics

---

# what Epic 10 intentionally does NOT include

not implemented:

* live inference providers (replay only)
* approval workflow execution (abstraction only)
* stage timeout enforcement (config only)
* context budget enforcement (TODO epic-11)
* risk model integration (TODO epic-11)

those are explicitly deferred to Epic 11+

---

# final state

Correx now has:

> a complete orchestration kernel with lifecycle management, retry coordination, deterministic replay, and inference state projection, enabling both live execution and reproducible test scenarios.