182 lines
3.3 KiB
Markdown
182 lines
3.3 KiB
Markdown
# 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.
|