299 lines
8.0 KiB
Markdown
299 lines
8.0 KiB
Markdown
---
|
||
name: "Core Validation Submodule Spec"
|
||
description: "Specification for :core:validation – layered validation pipeline"
|
||
depth: 2
|
||
links: ["../index.md", "./core-module-spec.md", "./core-approvals-submodule-spec.md"]
|
||
---
|
||
|
||
# :core:validation module specification
|
||
|
||
version: 0.1-draft
|
||
status: foundational specification
|
||
|
||
---
|
||
|
||
# 1. purpose
|
||
|
||
`:core:validation` defines the layered validation pipeline responsible for determining whether an artifact may advance workflow state.
|
||
|
||
It is the authoritative subsystem for:
|
||
|
||
* validation pipeline composition
|
||
* routing validation semantics
|
||
* schema validation rules
|
||
* semantic validation contracts
|
||
* approval validation integration
|
||
* validation event ownership
|
||
* deterministic rejection rules
|
||
|
||
All artifacts produced by models or tools are considered untrusted proposals until they pass all configured validation layers.
|
||
|
||
---
|
||
|
||
# 2. responsibilities
|
||
|
||
`:core:validation` owns:
|
||
|
||
* validation pipeline contracts
|
||
* validation stage definitions
|
||
* validation outcome model
|
||
* layer composition rules
|
||
* validation event definitions
|
||
* rejection reason semantics
|
||
* pipeline execution ordering
|
||
* deterministic validation guarantees
|
||
* integration points for semantic validators
|
||
* validation telemetry hooks
|
||
|
||
---
|
||
|
||
# 3. non-responsibilities
|
||
|
||
`:core:validation` MUST NOT own:
|
||
|
||
* actual semantic validation implementations (those belong to configured plugins or infrastructure)
|
||
* model execution
|
||
* approval decisions
|
||
* artifact persistence
|
||
* transition execution
|
||
* context synthesis
|
||
* UI rendering
|
||
* policy enforcement (but it invokes policy checks)
|
||
|
||
---
|
||
|
||
# 4. architectural role
|
||
|
||
`:core:validation` acts as:
|
||
|
||
* hard gatekeeper for all workflow progression
|
||
* deterministic validation pipeline executor
|
||
* shared contract for all validation layers
|
||
|
||
No artifact may become active workflow state without passing through this subsystem.
|
||
|
||
---
|
||
|
||
# 5. design principles
|
||
|
||
## 5.1 validation is mandatory
|
||
|
||
Every artifact must be validated before it can trigger a transition.
|
||
|
||
## 5.2 validation is layered
|
||
|
||
Validation occurs in a fixed order:
|
||
|
||
1. routing validation
|
||
2. payload validation
|
||
3. semantic validation
|
||
4. approval validation
|
||
|
||
If any layer rejects, subsequent layers are skipped and the artifact is rejected.
|
||
|
||
## 5.3 validation is deterministic at the pipeline level
|
||
|
||
The pipeline itself (ordering, short-circuiting, rejection semantics) is deterministic and replay-safe. Individual semantic validators may be nondeterministic, but their outcomes are recorded as events, so the pipeline decision becomes deterministic from history.
|
||
|
||
## 5.4 validation failures are events
|
||
|
||
Every validation outcome (pass/reject/needs_approval) emits a corresponding event, enabling replay and audit.
|
||
|
||
---
|
||
|
||
# 6. validation pipeline model
|
||
|
||
The pipeline is defined as an ordered sequence of `ValidationStage` instances.
|
||
|
||
```
|
||
sealed interface ValidationStage {
|
||
val name: String
|
||
suspend fun evaluate(context: ValidationContext): ValidationOutcome
|
||
}
|
||
```
|
||
|
||
Pipeline execution:
|
||
|
||
1. Build `ValidationContext` containing artifact, session, policies, current projection, event stream cursor.
|
||
2. Execute each stage in order.
|
||
3. On first rejection, stop and emit `ArtifactRejected`.
|
||
4. If all pass, emit `ArtifactValidated`.
|
||
5. If any stage requires approval escalation, emit `ApprovalRequired` and pause.
|
||
|
||
---
|
||
|
||
# 7. validation context
|
||
|
||
```kotlin
|
||
data class ValidationContext(
|
||
val artifact: Artifact,
|
||
val sessionId: SessionId,
|
||
val stageId: StageId,
|
||
val currentProjection: ProjectionSnapshot,
|
||
val policies: ActivePolicies,
|
||
val eventHistory: Sequence<Event>,
|
||
val replayMode: Boolean = false
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
# 8. layer definitions
|
||
|
||
### routing validation
|
||
|
||
Checks:
|
||
|
||
* artifact belongs to a valid stage in the current workflow
|
||
* transition from current stage to subsequent stage is allowed
|
||
* required capabilities are available
|
||
* no policy routing violations
|
||
|
||
Owner: `:core:transitions` + `:core:validation` together; routing validation is implemented here but queries the transition graph.
|
||
|
||
### payload validation
|
||
|
||
Validates artifact structure against its declared schema using pydantic/kotlinx.serialization.
|
||
|
||
* field completeness
|
||
* type correctness
|
||
* version compatibility
|
||
|
||
Failure is always deterministic.
|
||
|
||
### semantic validation
|
||
|
||
Examines artifact content for consistency, safety, and correctness:
|
||
|
||
* hallucinated file paths
|
||
* contradictory claims
|
||
* unsafe commands
|
||
* policy violations beyond structure
|
||
|
||
Semantic validators are pluggable. They may use small deterministic checkers or even other models, but their outputs are captured as events and become part of the replayable judgment.
|
||
|
||
### approval validation
|
||
|
||
Checks:
|
||
|
||
* does the artifact fall under an auto-approved tier?
|
||
* does it require user approval?
|
||
* has the user already granted session-level auto-approve?
|
||
* are there escalate/deny policies?
|
||
|
||
If approval is required, the pipeline suspends and emits `ApprovalRequested`. Only after a positive approval decision does validation succeed.
|
||
|
||
---
|
||
|
||
# 9. validation outcomes
|
||
|
||
```kotlin
|
||
sealed interface ValidationOutcome {
|
||
data object Passed : ValidationOutcome
|
||
data class Rejected(val reasons: List<ValidationError>) : ValidationOutcome
|
||
data class NeedsApproval(val tier: ApprovalTier, val message: String) : ValidationOutcome
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 10. event ownership
|
||
|
||
`:core:validation` emits:
|
||
|
||
* `ArtifactValidationStarted`
|
||
* `ArtifactValidated`
|
||
* `ArtifactRejected`
|
||
* `ApprovalRequired` (delegated to approval subsystem, but emitted here)
|
||
|
||
All validation events carry causation from the artifact event.
|
||
|
||
---
|
||
|
||
# 11. consumed events
|
||
|
||
`:core:validation` consumes:
|
||
|
||
* `ArtifactProduced` (to start validation)
|
||
* `ApprovalDecision` (to resume from approval wait)
|
||
|
||
---
|
||
|
||
# 12. invariants
|
||
|
||
* Validation pipeline ordering is immutable for a given session config.
|
||
* Validation outcomes are idempotent given identical inputs.
|
||
* Rejected artifacts may never be used for state progression.
|
||
* All validation decisions are recorded as events before any transition.
|
||
|
||
---
|
||
|
||
# 13. replay semantics
|
||
|
||
During replay, validation outcomes are read from events, not re-executed, ensuring determinism.
|
||
|
||
If replay mode is `inference-skipping`, semantic validators are not invoked; instead, previously recorded outcomes are applied.
|
||
|
||
Validation events themselves must be replayable.
|
||
|
||
---
|
||
|
||
# 14. threading/concurrency
|
||
|
||
The validation pipeline runs within the orchestration coroutine scope of the current session. No concurrent validation of the same artifact is allowed. Pipeline execution must be cancellable.
|
||
|
||
---
|
||
|
||
# 15. failure semantics
|
||
|
||
If the pipeline itself fails (e.g., a bug in a validator), the artifact is rejected with a system error. The session enters a failed or recovery state. No partial acceptance is allowed.
|
||
|
||
---
|
||
|
||
# 16. observable requirements
|
||
|
||
Must expose:
|
||
|
||
* validation duration per layer
|
||
* rejection reasons
|
||
* approval wait times
|
||
* semantic validator invocations
|
||
* pipeline completions
|
||
|
||
---
|
||
|
||
# 17. security boundaries
|
||
|
||
Validation is a security boundary. Validators, especially semantic ones, may be untrusted plugins. They must not mutate state or access external services directly. They operate in a sandboxed context with read-only access to the artifact and a frozen projection.
|
||
|
||
---
|
||
|
||
# 18. extension model
|
||
|
||
Extensions may register custom semantic validators or even additional validation layers via the plugin system. Extensions must abide by the deterministic pipeline contract and produce `ValidationOutcome`.
|
||
|
||
---
|
||
|
||
# 19. forbidden patterns
|
||
|
||
* bypassing validation by direct artifact propagation
|
||
* validation that depends on mutable global state
|
||
* ordering inversion
|
||
* silent acceptance of invalid artifacts
|
||
* replay that re-executes approval decisions
|
||
|
||
---
|
||
|
||
# 20. testing requirements
|
||
|
||
* pipeline ordering determinism
|
||
* layer short-circuit behavior
|
||
* replay consistency (with and without inference)
|
||
* approval escalation/rejection paths
|
||
* integration with all artifact types
|
||
|
||
---
|
||
|
||
# 21. philosophy
|
||
|
||
Validation is the harness’s immune system. It does not trust any model output; it verifies structure, safety, and policy compliance before allowing state to advance. The pipeline turns probabilistic model suggestions into trustworthy workflow building blocks. |