correx/docs/epics/epic-10-resolution.md

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

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.