This repository is the canonical home for shared contracts and contract-level research across the evidence-to-decision pipeline.
The maintained architecture is intentionally asymmetric. A contract exists only where producer/consumer evidence supports one; research candidates do not become canonical because they are convenient to draw as a pipeline.
Contract A — upstream work object → Evidence Bundler
Contract A 2.0.0 is the canonical production upstream declaration/source-representation contract after its promotion gate completes. It carries exact producer/work/root proposition identity, explicit decomposition state and declared all_of lineage where present, exact supplied UTF-8 source representations, and whole-object integrity without importing support, trust, retrieval, CAL, Decision, or Authorization semantics.
Specification: contract-a-v2.0.0.md
The 2.0.0 public compatibility version deliberately retains the exact frozen RC2 integrity-bound wire token and machine semantics. The byte-identical wire authority lives under schema/contract-a/2.0.0/; validators/contract_a.py is the canonical production entry point.
Legacy Contract A 1.0.0 remains immutable historical authority at handoff-contract-v1.0.0.md. The change is major-class; legacy objects are not silently reinterpreted as 2.0.0.
The production/version decision and bounded Contract E pre-promotion evidence are recorded in EDR-004 / issue #60 and terminal research PRs #57 and #61.
Contract B — Evidence Bundler → Claim Audit Lab
Contract B 1.2.0 is the canonical production handoff from Evidence Bundler to Claim Audit Lab. Its additive factual-context/history extension carries provenance-bound evidence-world facts, explicit history and aperture observations, and preserved nomination/admission state without converting those fields into proposition-specific semantic judgments.
Specification: contract-b-factual-context-extension-v1.2.0.md
The production/version decision and exact cross-repository evidence are recorded in EDR-001, GitHub issue #14.
The immutable public release is tagged contract-b-v1.2.0. Its release record binds the original production-lock commit, exact Evidence Bundler and Claim Audit Lab identities, the decisive acceptance/post-merge lock runs, and a machine-readable release-identity receipt.
Contract C 1.0.0 is the first canonical CAL result contract. Producer: Claim Audit Lab. Downstream decision consumer: Decision Engine. It is decision-agnostic: it exports CAL-attributable epistemic state, exact Contract-B binding, producer/policy identity, retained contribution state, explicit unknown/failure state, and deterministic object identity without granting operational authorization.
Specification: contract-c-v1.0.0.md
The immutable public release is tagged contract-c-v1.0.0. Its release record contains the exact promotion, producer, clean-consumer, and release-lock lineage.
Contract D 1.0.0 is the first canonical production Decision contract. It binds exact upstream authority, Decision policy, target/content identity, evaluation state, and a typed requested effect while stopping at outcomes such as candidate_for_authorization, hold, evaluation_failed, not_applicable, or cannot_establish.
Specification: contract-d-v1.0.0.md
The immutable public release is tagged contract-d-v1.0.0. Its post-merge release lock reruns the exact Decision Engine producer, frozen independent consumer, frozen adversarial apparatus, and full conformance before publication.
A Decision is not automatic permission to execute an effect.
Contract E is research-only, and the current question is deliberately broader than "what should the next serialized contract look like?" Research is testing standing authority state, typed jurisdiction, authority-basis binding, delegation/currentness, participant declarations, transient authorization receipts, and local enforcement as potentially cross-cutting machinery.
No canonical Contract E schema or production authority control plane is established here. Contract A 2.0.0 does not absorb the known unresolved Contract E qualification or surplus-record semantics.
Repository-wide architectural invariant: every apparatus is built, tested, and reasoned about from its governing contract, not from the incidental output shape of the current neighboring apparatus. Producer implementation, contract authority, and consumer implementation remain separate. The full rule and its apparatus-by-apparatus application are normative repository governance in APPARATUS-CONTRACT-SEPARATION.md.
A current output object is a concrete contract instance, not the definition of the contract. Unused contract states do not disappear because today's producer does not populate them, and producer-private behavior does not become downstream authority merely because today's consumer can observe it.
The contracts preserve several pipeline invariants:
- evidence-world facts do not silently become semantic conclusions;
- CAL epistemic conclusions do not silently become Decision Engine policy;
- a valid Decision does not automatically become execution permission;
- missing or unestablished state remains explicit rather than being filled with a convenient default;
- exact upstream identity is preserved where substitution could change authority;
- research candidates, validators, and harnesses remain distinguishable from canonical contract authority;
- producer conformance, contract sufficiency, and consumer conformance/recoverability are tested as distinct claims.
The repository contains five different kinds of material. They should not be conflated:
- Canonical authority: maintained specifications, schemas, validators, fixtures, and release records.
- Candidate authority: explicitly non-canonical contract candidates awaiting evidence.
- Research: preregistrations, attacks, reproductions, results, and preserved failures.
- Research infrastructure: evaluators, validators, harnesses, hidden fixtures, and workflows used to test claims.
- Historical authority: superseded or legacy contract objects retained for reconstruction and compatibility.
Important top-level surfaces include:
APPARATUS-CONTRACT-SEPARATION.md repository-wide boundary governance
handoff-contract-v1.0.0.md legacy Contract A / original A+B authority
contract-a-v2.0.0.md canonical Contract A 2.0.0 authority
contract-b-factual-context-extension-v1.2.0.md
contract-c-v1.0.0.md
contract-d-v1.0.0.md
schema/ canonical machine-readable contract material
validators/ contract validators
fixtures/ canonical/public fixtures where applicable
docs/research/ research records and frozen candidates
DECISIONS.md durable contract decision history
CHANGELOG.md maintained contract history
Start from the contract that owns the boundary you are changing, then follow its exact schema/validator/fixture and decision lineage. Do not start from a current producer output and infer that its populated subset defines the contract. See APPARATUS-CONTRACT-SEPARATION.md.
For cross-repository work, pin the producer, contract authority, and consumer identities. A passing test in only one repository is not evidence that the shared boundary works.
Research branches may contain newer-looking schemas or richer objects. They are not canonical unless a separate promotion decision establishes that status.
The repository's verifier and acceptance workflows protect structural, vocabulary, identity, integrity, and cross-repository conformance properties appropriate to each maintained contract.
Contract A 2.0.0 promotion additionally proves byte identity to the frozen RC2 wire authority, reruns the immutable prereveal independent implementation, compares independent and production behavior on all public fixtures, and consumes the exact real-pilot subject with the production validator.
These checks are intentionally narrower than semantic truth. Structural validation does not establish source legitimacy, retrieval completeness, CAL semantic correctness, Decision policy correctness, or execution authorization.
When a contract claim depends on independent recoverability, the independent implementation is executed in a separate fresh context and frozen before reference reveal. Failed or disagreeing reproductions remain part of the research record.
Shared contract changes require evidence at the real producer/consumer boundary. Version changes follow compatibility consequences rather than milestone aesthetics.
For a canonical change:
- identify the exact producer/consumer need;
- establish the smallest authority that must cross the boundary;
- test missing/hostile/unknown state and compatibility where relevant;
- preserve failed candidates and deviations;
- make a separate promotion decision;
- update canonical specification/schema/validator/fixtures coherently;
- publish a release only when an immutable named checkpoint is justified.
Changing an apparatus does not itself change its contract. Changing a contract requires a separate evidence and promotion decision.
A research result does not become production behavior merely because its branch is green.
Contract A 2.0.0 is a breaking successor to legacy Contract A 1.0.0. Current strict legacy consumers may require a separate compatibility carrier. Contract A does not establish decomposition semantic correctness or downstream authority.
Contract B 1.2.0 is canonical, production-locked, and released. Its release does not establish universal independent interoperability, source legitimacy, retrieval completeness, or correctness of CAL's semantic judgments.
Contract C 1.0.0 is canonical and released, but that does not establish correctness of CAL's semantic judgments.
Contract D 1.0.0 is canonical and released, but it deliberately stops before operational Authorization or execution and does not establish correctness of upstream epistemic judgments or Decision policy outside the tested domain.
Contract E remains a research program. Its frozen candidates, attack harnesses, clean-room reproductions, interpretation audits, and failures are evidence, not production authority.