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,181 @@
+# Epic 4 — Validation Pipeline (summary)
+
+## goal
+
+deterministic, replay-safe validation layer over workflow execution model (graph + transitions + sessions + events), producing a structured report and optional approval request, without influencing execution.
+
+---
+
+## core idea
+
+Epic 4 is a **pure analysis layer**:
+
+* consumes: `ValidationContext` (graph + detected cycles + policies + session state)
+* produces:
+
+  * `ValidationReport` (deterministic, hierarchical)
+  * optional `ApprovalRequest` (boundary artifact)
+
+it never:
+
+* executes workflows
+* modifies state
+* triggers transitions
+* enforces runtime behavior
+
+---
+
+## module structure
+
+```text
+core/validation
+├── model
+├── graph
+├── transition
+├── session
+├── semantic
+├── pipeline
+└── approval
+```
+
+---
+
+## 1. model layer
+
+defines shared validation contract:
+
+* `ValidationReport` (sections-based hierarchy)
+* `ValidationSection`
+* `ValidationIssue`
+* `ValidationSeverity`
+* `ValidationContext`
+
+context is a full snapshot:
+
+* `WorkflowGraph`
+* `DetectedCycle` (from Epic 3)
+* `CyclePolicyBinding`
+* `SessionState`
+
+---
+
+## 2. graph validation
+
+checks structural correctness only:
+
+* start node existence
+* dangling transitions (invalid stage references)
+* cycle reporting (passed-through from Epic 3, no interpretation)
+
+cycles are:
+
+* allowed
+* informational only
+
+---
+
+## 3. transition validation
+
+validates engine consistency:
+
+* transition endpoints exist in graph
+* condition presence / sanity
+* deterministic ordering correctness per source node
+
+no evaluation or execution of conditions.
+
+---
+
+## 4. session validation
+
+validates projection consistency:
+
+* temporal consistency (`createdAt <= updatedAt`)
+* session state sanity (`invalidTransitions >= 0`)
+* light consistency checks against graph context
+
+no replay execution or event mutation logic.
+
+---
+
+## 5. semantic validation
+
+configuration-level validation layer:
+
+* cycle-policy binding completeness (mode B: required only in execution-capable mode)
+* cross-layer consistency rules
+* extension point for future domain rules
+
+cycle identity is based on:
+
+* `CycleSignature(nodes only, normalized)`
+
+---
+
+## 6. pipeline executor
+
+deterministic orchestration:
+
+* executes validators in fixed order
+* aggregates `ValidationSection`
+* fully replayable and stateless
+
+```text
+Graph → Transition → Session → Semantic → Report
+```
+
+no branching logic, no execution semantics.
+
+---
+
+## 7. approval trigger
+
+boundary component:
+
+* consumes `ValidationReport`
+* computes `RiskSummary`
+* produces optional `ApprovalRequest`
+
+rules:
+
+* errors or missing cycle policies trigger approval requirement
+* does not execute or control workflow system
+
+---
+
+## final outputs
+
+### validation output
+
+```text
+ValidationReport
+ ├── graph
+ ├── transition
+ ├── session
+ └── semantic
+```
+
+### approval output
+
+```text
+ApprovalRequest? (optional)
+```
+
+---
+
+## key invariants enforced
+
+* deterministic execution (same input → same report)
+* replay-safe evaluation
+* no state mutation
+* no execution coupling
+* cycles allowed structurally
+* policies required only as semantic governance, not structural correctness
+
+---
+
+## architectural position
+
+Epic 4 is the **boundary correctness layer**:
+
+> it ensures the system is internally consistent and safely configurable, without deciding how it runs.