kami
d26f20c316
Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
# core/validation — AGENTS.md
|
|
|
|
## Purpose
|
|
|
|
Layered validation pipeline: validates workflow graphs (structure, cycles, reachability), session state, semantic rules, JSON schema conformance, and artifact payloads before any state-mutating operation proceeds.
|
|
|
|
## Ownership
|
|
|
|
CORREX kernel team. Hard Invariant #7 applies here: LLM outputs are untrusted until this pipeline approves them.
|
|
|
|
## Local Contracts
|
|
|
|
- `ValidationPipeline` — top-level entry point; runs all registered validators in sequence and collects `ValidationReport`.
|
|
- `Validator` — interface for a single validator. Returns `ValidationOutcome` (pass/warn/fail) with `ValidationIssue` list.
|
|
- Built-in validators:
|
|
- `GraphValidator` — validates `WorkflowGraph`: reachability, cycle detection (via `core:transitions` `CycleExtractor`), missing tool references.
|
|
- `SemanticValidator` — applies `SemanticRule`s to workflow/stage definitions.
|
|
- `SessionValidator` — validates session preconditions before launch.
|
|
- `TransitionValidator` — validates transition edge definitions.
|
|
- `ArtifactPayloadValidator` — validates artifact payloads against `JsonSchema`.
|
|
- `JsonSchemaValidator` — JSON schema conformance check.
|
|
- `SceneValidator` — validates scene definitions.
|
|
- `ValidationReport` / `ValidationIssue` / `ValidationOutcome` / `ValidationSeverity` / `ValidationSection` / `ValidationLocation` — report structure types.
|
|
- `ValidationContext` — context passed to all validators (session, graph, config).
|
|
- `ValidationRiskStats` — risk statistics derived from validation results, consumed by `core:risk`.
|
|
- `ApprovalRequest` / `ApprovalTrigger` — approval-related types used during validation-triggered approval flows.
|
|
- `CyclePolicy` / `CyclePolicyBinding` / `CycleSignature` / `CycleSignatureFactory` / `CycleExitRule` — cycle policy enforcement: detects recurring cycle patterns and applies policy (warn/fail/allow).
|
|
- `RiskSummary` — local re-export of risk summary type used in validation output.
|
|
- `MissingToolRule` / `SemanticRule` — built-in semantic rule implementations.
|
|
|
|
## Work Guidance
|
|
|
|
- Add new validators by implementing `Validator` and registering in `ValidationPipeline`. Do not add validation logic directly to `SessionOrchestrator` or other callers.
|
|
- `ValidationPipeline` must be run before any inference call processes its output (Hard Invariant #7).
|
|
- `CyclePolicy` is the mechanism for allowing controlled cycles in workflows; do not bypass it.
|
|
- `GraphValidator` calls `CycleExtractor` from `core:transitions` — this is the one legitimate cross-core reference; it is structural, not domain logic.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
./gradlew :core:validation:test --rerun-tasks
|
|
```
|
|
|
|
Tests in `testing/deterministic/` (GraphValidatorTest) and `testing/contracts/` (ContextSnapshotTest).
|
|
|
|
## Child DOX Index
|
|
|
|
No child AGENTS.md (leaf module).
|