correx/docs/epics/epic-4.md

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:

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.