316 lines
7.4 KiB
Markdown
316 lines
7.4 KiB
Markdown
# 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.
|