epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,277 @@
+# 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.