Skip to content

adr-schema-enforced-domain-contracts

Decision

Adopt Schema-Enforced Domain Contracts as a foundational architectural standard across all CAS pipeline boundaries and agent outputs.

Context

  • Source: governance-flow
  • Pattern: schema-enforced-domain-contracts
  • Promotion Recommendation: recommendation-schema-enforced-domain-contracts
  • Scope Classification: global
  • Scope Classification Artifact: pattern-scope-classification

Schema-Enforced Domain Contracts establish strict data boundaries between non-deterministic actors (such as LLMs and autonomous agents) and core business state. By enforcing rigid Pydantic and JSON Schema validation prior to persistence or downstream propagation, the architecture guarantees system integrity, prevents state corruption, and enables deterministic pipeline execution.

Scope

Applicability: Mandatory for all agent task outputs, pipeline step boundaries, and persisted knowledge layer entities.

Enforces fail-fast validation before persistence across all CAS workflows.

Consequences

Governance

Guarantees system boundary and state integrity by strictly validating all agent and LLM outputs against rigid Pydantic schemas before persistence. Eliminates hallucinated attributes and structural payload corruption across pipeline stages.

Execution

Sub-millisecond validation overhead with Rust-backed Pydantic v2. Provides structured field-level diagnostics lowering MTTR during schema regressions.

System Behaviour

Guarantees that downstream workflow steps consume verified, strongly-typed domain entities without defensive null/type checks.

Evidence Summary

Promotion Evidence

  • Concrete AST symbols implemented in src/cas_runner/governance/models.py and src/cas_runner/steering/models.py
  • Enforced by build validation workflow gates and the ComplianceEngine
  • Validated across forensic diagnostic, AEM generator, and AID generation flows

Promotion Criteria

Significance, reusability, recurrence, evidence quality, governance maturity, and strategic alignment are fully met.

Governance Risks

Schema evolution friction across versioned artifacts; mitigated by explicit schema versioning and migration testing.

Traceability

Pattern Proposal

schema-enforced-domain-contracts

Scope Classification

Artifact: pattern-scope-classification

Classification: global

Promotion Recommendation

recommendation-schema-enforced-domain-contracts

Promotion Decision

promotion-decision-schema-enforced-domain-contracts

Next Step

  • Enforce Pydantic schema validation at every step boundary.
  • Institutionalize global pattern under knowledge/global/patterns/schema-enforced-domain-contracts.md.