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,315 @@
+# Epic 4: Validation Pipeline (Deterministic Analysis + Cross-Layer Consistency Engine)
+
+**status:** completed
+**date:** 09.05.2026 (May)
+**scope:** `:core:validation` (depends on `:core:events`, `:core:sessions`, `:core:transitions`, Epic 3 analysis outputs)
+
+---
+
+## context
+
+With deterministic event sourcing (Epic 1), session projection (Epic 2), and workflow transition semantics (Epic 3) in place, Correx now has a complete execution and reconstruction model.
+
+However, there is no formal layer that ensures:
+
+* graph integrity
+* transition consistency
+* session projection correctness
+* configuration validity (cycle policies, semantic rules)
+* cross-layer coherence under replay
+
+Without a validation layer:
+
+* invalid workflow graphs can still be constructed
+* inconsistent transitions can pass unnoticed
+* session projections can diverge semantically from graph structure
+* cycle governance (policy binding) is not enforceably checked
+* system correctness is only implicitly trusted, not verified
+
+Epic 4 introduces a deterministic validation system to close this gap.
+
+---
+
+## goal
+
+Introduce a **deterministic, replay-safe validation pipeline**:
+
+> a pure analysis engine that validates workflow structure, execution projections, and configuration consistency without influencing execution behavior
+
+The system must remain:
+
+* deterministic
+* stateless
+* replay-safe
+* non-executing
+* side-effect free
+
+It is NOT an orchestration engine and does NOT participate in runtime control flow.
+
+---
+
+## scope (what IS included)
+
+---
+
+### 1. validation model layer
+
+Define unified validation representation:
+
+* `ValidationReport`
+* `ValidationSection`
+* `ValidationIssue`
+* `ValidationSeverity`
+* `ValidationContext`
+
+Validation context is a full system snapshot:
+
+* `WorkflowGraph`
+* `DetectedCycle` (Epic 3 output)
+* `CyclePolicyBinding`
+* `SessionState`
+
+Properties:
+
+* immutable
+* replay-safe
+* fully deterministic input contract
+
+---
+
+### 2. graph validation
+
+Validate structural correctness of workflow topology.
+
+Checks:
+
+* start node existence
+* dangling transitions (invalid stage references)
+* structural consistency of graph definition
+* cycle presence reporting (pass-through only)
+
+Important:
+
+* cycles are allowed by design (Epic 3)
+* cycle detection is informational only
+* no enforcement or interpretation of cycles occurs here
+
+---
+
+### 3. transition validation
+
+Validate deterministic consistency of transition engine inputs.
+
+Checks:
+
+* transition endpoints exist in graph
+* condition presence and structural validity
+* deterministic ordering correctness per source node
+* ambiguity detection in transition resolution ordering
+
+Important:
+
+* transition conditions are NOT executed
+* no resolution logic is invoked
+* no runtime decisioning occurs
+
+---
+
+### 4. session validation
+
+Validate projection consistency against event-derived state.
+
+Checks:
+
+* temporal consistency (`createdAt ≤ updatedAt`)
+* session state sanity (invalid transition counts)
+* consistency between session state and graph structure
+* lightweight anomaly detection over projection output
+
+Important:
+
+* no event replay is performed
+* no projection recomputation occurs
+* session state is treated as immutable derived artifact
+
+---
+
+### 5. semantic validation layer
+
+Validate configuration and cross-domain consistency rules.
+
+Includes:
+
+* cycle-policy binding completeness (mode-dependent enforcement)
+* configuration consistency checks
+* cross-layer structural coherence rules
+
+Cycle semantics:
+
+* `CycleSignature` derived from normalized node sets
+* edges are not part of identity
+* policy binding is evaluated against cycle signatures only
+
+Important:
+
+* cycles remain structurally valid (Epic 3 rule preserved)
+* semantic layer does NOT enforce execution behavior
+* policies are treated as configuration constraints, not runtime logic
+
+---
+
+### 6. validation pipeline executor
+
+Define deterministic orchestration of validation layers.
+
+Pipeline behavior:
+
+* strictly ordered execution
+* no hidden parallelism
+* fully deterministic evaluation order
+* stateless execution model
+
+Execution flow:
+
+```text
+Graph → Transition → Session → Semantic → ValidationReport
+```
+
+Important:
+
+* pipeline aggregates results only
+* no control flow decisions beyond aggregation
+* no mutation of input context
+
+---
+
+### 7. approval trigger integration point
+
+Introduce boundary layer between validation and external decision systems.
+
+Responsibilities:
+
+* evaluate `ValidationReport`
+* compute risk summary
+* decide whether approval request is required
+* emit `ApprovalRequest` artifact
+
+Important constraints:
+
+* no execution coupling
+* no workflow control logic
+* no system orchestration responsibility
+* strictly output transformation layer
+
+Output artifacts:
+
+* `ApprovalRequest`
+* `RiskSummary`
+
+Behavior:
+
+* errors or missing cycle-policy bindings trigger approval requirement
+* acts as deterministic gating boundary, not execution controller
+
+---
+
+### 8. deterministic testing requirements
+
+Validation system must be fully testable under replay constraints.
+
+Coverage includes:
+
+* graph validation determinism
+* transition validation consistency
+* session projection sanity validation
+* semantic rule enforcement consistency
+* pipeline ordering determinism
+* approval trigger stability
+* full system replay equivalence
+
+Invariant:
+
+> identical input context must always produce identical ValidationReport and ApprovalRequest outcome
+
+---
+
+## explicit exclusions
+
+Epic 4 does NOT include:
+
+* workflow execution
+* transition evaluation or resolution
+* scheduling or orchestration
+* runtime policy enforcement
+* execution retry logic
+* system control flow decisions
+* async or distributed validation execution
+* event mutation or emission
+
+Those belong to future runtime/orchestration layers.
+
+---
+
+## consequences
+
+### positive
+
+* introduces explicit correctness boundary for entire system
+* makes workflow + session consistency verifiable
+* decouples analysis from execution
+* enables safe pre-execution validation gating
+* formalizes configuration governance (cycle policies)
+* improves replay debugging and system observability
+
+---
+
+### negative
+
+* adds another full abstraction layer over already complex system
+* increases conceptual separation between “valid structure” and “valid execution”
+* introduces potential duplication of logic if misused outside boundary
+* requires strict discipline to avoid leaking execution semantics into validation
+* makes system reasoning more layered (analysis vs execution vs policy)
+
+---
+
+## rationale
+
+Epic 4 exists because deterministic execution alone is insufficient.
+
+Even with:
+
+* event sourcing (Epic 1)
+* projection layer (Epic 2)
+* workflow engine (Epic 3)
+
+the system still lacks:
+
+> a formal correctness boundary over structure, configuration, and derived state
+
+This epic ensures:
+
+* workflows are structurally valid before execution
+* session state remains consistent with graph semantics
+* configuration constraints (cycle policies) are explicitly governed
+* system behavior remains fully replay-verifiable
+
+It completes the shift from:
+
+* “deterministic execution system”
+  to
+* “deterministic + verifiable workflow system”
+
+---
+
+## status
+
+Epic 4 is considered complete once:
+
+* validation model is defined ✔
+* graph/transition/session/semantic validators exist ✔
+* pipeline executor is deterministic ✔
+* approval trigger boundary is implemented ✔
+* replay tests confirm stability ✔
+
+It is the final analysis layer before runtime orchestration and execution-control systems are introduced in future epics.