278 lines
6.5 KiB
Markdown
278 lines
6.5 KiB
Markdown
# 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.
|