correx/docs/modules/core-validation-submodule-spec.md

name, description, depth, links

name	description	depth	links
Core Validation Submodule Spec	Specification for :core:validation – layered validation pipeline	2	../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

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

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.