Contract Production Readiness Roadmap

This roadmap turns the word contract into a production-audited term across

0x0. A contract is allowed only when the repository can prove the promised

boundary through implementation, tests, diagnostics, documentation, release

evidence, compatibility policy, and ownership.

This work exists because contract appears in ABI, API, package, runtime,

library, and release surfaces. That is acceptable only when each use means a

checked guarantee. It is not acceptable when it means future intent, an

interface-only library, a planned API, or a test fixture presented as production

behavior.

Production Closure Rule

This roadmap is complete only when every public or release-relevant contract has

all of the following:

• a classified contract kind;
• an implementation path;
• valid examples;
• invalid examples;
• negative diagnostics;
• runtime, codegen, or resolver behavior where applicable;
• compatibility and versioning rules;
• release evidence;
• a maintenance owner;
• public documentation;
• a passing make contract-integrity-check gate.

Until that gate exists and passes, 0x0 must not treat contract integrity as a

closed production surface.

Contract Taxonomy

The accepted contract kinds are:

The machine-readable taxonomy is docs/contract-taxonomy.tsv.

The following are forbidden in production or development paths:

• contract-first libraries without implemented behavior;
• public APIs that only construct data and imply runtime behavior they do not

perform;

• test fixtures, adapters, or deterministic doubles exposed as production

behavior;

• contract names that only mean an idea, roadmap, or unsupported future surface;
• release evidence that points to tests without proving the production path.

Milestone 0: Contract Meaning Baseline

Status: done.

Goal: make contract terminology precise before changing code.

Submilestones:

• 0.1 Add a concise contract terminology section to the style guide,

documentation standard, and governance review docs.

• 0.2 Define the taxonomy in a machine-readable source file such as

docs/contract-taxonomy.tsv.

• 0.3 Add a policy that contract in beginner docs should be written as

guarantee, checked boundary, or a domain-specific term unless the page

links to the formal taxonomy.

• 0.4 Document that No contract-first libraries from SKILLS.html means every

public contract requires implementation and release evidence.

• 0.5 Add ADR/RFC records for terminology, gate shape, and compatibility impact.

Acceptance:

• The taxonomy is public, machine-readable, and linked from site/reference.html.
• docs/style-guide.html, docs/documentation.html, and docs/governance-review.html

explain when contract is allowed.

• Beginner-oriented docs avoid unexplained contract terminology.

Completion evidence:

• docs/contract-taxonomy.tsv defines the accepted contract kinds.
• docs/style-guide.html, docs/documentation.html, and

docs/governance-review.html define the allowed use of contract.

• site/reference.html links the taxonomy and this roadmap.
• Beginner pages use rules, guarantee, checked boundary, or

domain-specific wording unless they link to the formal taxonomy.

Milestone 1: Contract Inventory And Ownership

Status: done.

Goal: inventory every active contract use and assign evidence ownership.

Submilestones:

• 1.1 Generate release/contract-inventory.tsv from active source, docs, runtime

tables, release metadata, packages, and app surfaces.

• 1.2 Classify each row as one of the accepted contract kinds.
• 1.3 Record source path, implementation path, tests, docs, examples, failure

behavior, release evidence, owner, stability, and compatibility policy.

• 1.4 Mark allowed test fixtures as test-fixture-contract and require their

paths to live under test-only directories.

• 1.5 Mark ambiguous names as rename-required, evidence-required, or

remove-required.

• 1.6 Add a migration ledger for public names that must change, including

compatibility aliases and removal timing.

Acceptance:

• Every active contract use is represented exactly once in

release/contract-inventory.tsv.

• No inventory row may be unclassified, ownerless, or evidence-free.
• Test fixture contracts cannot satisfy production contract evidence.

Completion evidence:

• tools/contract-inventory-generate.py scans active repository source,

documentation, runtime tables, release metadata, package metadata, tests,

tools, and public site source.

• release/contract-inventory.tsv records every active contract occurrence

with kind, disposition, source location, implementation path, tests, docs,

examples, failure behavior, release evidence, owner, stability, and

compatibility policy.

• release/contract-rename-ledger.tsv records occurrence-level ambiguous names

marked rename-required, including recommended names, compatibility plan,

owner, target milestone, and status.

• Test fixture contracts are classified as test-fixture-contract and must live

under test-scoped paths.

• The generated inventory has no empty fields, no unknown kinds, and no

fixture-scope violations.

Milestone 2: Contract Integrity Gate

Status: done.

Goal: add the bounded gate that prevents contract drift.

Submilestones:

• 2.1 Implement tools/contract-integrity-check.py.
• 2.2 Add tests/contract-integrity.sh.
• 2.3 Add make contract-integrity-check.
• 2.4 Wire the gate into release helper inventory and final release discipline.
• 2.5 Fail on any public contract row missing implementation, tests, docs,

examples, owner, stability, compatibility policy, or release evidence.

• 2.6 Fail when a production row points to a test fixture as its only behavior.
• 2.7 Fail when source/docs contain contract outside the taxonomy and

inventory.

• 2.8 Fail when new staged changes introduce a contract without an ADR/RFC and

documentation impact review.

Acceptance:

• make contract-integrity-check passes on the current repository.
• The gate has negative tests for missing implementation, missing tests, missing

docs, fixture-as-production, unknown taxonomy kind, duplicate rows, and

unowned rows.

• The gate is resource-safe and does not run heavy compilers or remote

deployment.

Completion evidence:

• tools/contract-integrity-check.py validates taxonomy kinds, inventory

fields, duplicate rows, source locations, evidence paths, owner/stability

fields, fixture scope, rename ledger coverage, generated inventory drift, and

staged ADR/RFC documentation-impact requirements for new contract terms.

• tests/contract-integrity.sh runs the gate and negative cases for missing

implementation, missing tests, missing docs, fixture-as-production, unknown

taxonomy kind, duplicate rows, unowned rows, and missing generated inventory

coverage.

• make contract-integrity-check is resource-safe and does not run heavy

compilers or remote deployment.

• release/test-helpers.txt, tests/release-helper-list.sh,

release/final-discipline.tsv, and

tools/final-release-discipline-check.py include contract integrity as a

release input.

Milestone 3: ABI Contract Hardening

Status: done.

Goal: make ABI contracts prove binary compatibility and runtime layout behavior.

Submilestones:

• 3.1 Inventory ABI layout, value representation, symbol, relocation, ownership,

and calling-convention contracts.

• 3.2 Add layout golden tests for primitive values, lists, strings, tagged

values, errors, options, results, bytes, maps, closures, and host buffers.

• 3.3 Add cross-backend ABI tests for direct ELF, object, archive, linker, native

codegen, and compatibility paths.

• 3.4 Add backward/forward compatibility tests for ABI versioned values.
• 3.5 Add diagnostics for ABI mismatch, unsupported layout, missing symbol,

duplicate symbol, and incompatible runtime value.

• 3.6 Publish ABI compatibility policy and release evidence.

Acceptance:

• Every abi-contract row has layout tests, compatibility tests, docs, and

release evidence.

• ABI compatibility failures produce stable diagnostics.
• Final release discipline includes ABI contract integrity evidence.

Completion evidence:

• abi/contract-inventory.tsv inventories ABI marker, payload/tag registers,

stack discipline, primitive layouts, tagged value layouts, runtime descriptor

layouts, symbol resolution, relocation handling, archive linking,

compatibility readers, and failure diagnostics.

• abi/layout-goldens.tsv records layout goldens for primitive values, text,

lists, tagged values, errors, options, results, bytes, maps, closures, and

host buffers, and make abi-contract-hardening-check validates it against

abi/value-layouts.tsv.

• abi/backend-contract-matrix.tsv covers direct ELF, object, archive, linker,

native codegen, and compatibility paths.

• abi/diagnostic-contracts.tsv records stable ABI contract diagnostics for

marker mismatch, unsupported layout, missing symbol, duplicate symbol,

incompatible runtime value, unsupported relocation, and malformed markers.

• release/abi-contract-evidence.tsv, release/final-discipline.tsv,

release/test-helpers.txt, and tools/final-release-discipline-check.py

make ABI contract hardening a required bounded-source release input.

• tools/contract-inventory-generate.py no longer classifies app/library API

rows as ABI contracts because of unrelated ABI wording in the same line.

Milestone 4: API Contract Hardening

Status: done.

Goal: make API contracts enforce real request, response, route, and callable

surface behavior.

Submilestones:

• 4.1 Inventory public API contracts in core libraries, framework libraries,

Index, Kukulkan, generated API docs, and package pages.

• 4.2 Add explicit validators for request schemas, response schemas, route

parameters, domain invariants, and versioned wire values.

• 4.3 Add round-trip encoder/decoder tests.
• 4.4 Add negative diagnostics for missing fields, invalid variants, bad types,

invalid capability use, and unsupported version.

• 4.5 Add public examples for each API family.
• 4.6 Split pure schema constructors from runtime operations in docs and source.

Acceptance:

• Every api-contract row has validators, round-trip tests, negative tests,

examples, and docs.

• API contracts cannot be satisfied by constructors alone.
• Generated API docs identify stability and compatibility behavior.

Completion evidence:

• api/contract-inventory.tsv inventories public API contracts in core

libraries, framework libraries, Index, Kukulkan, generated API docs, and

package pages.

• api/validator-matrix.tsv records validators for callable signatures, route

schemas, request schemas, response schemas, domain invariants, generated API

docs, and package pages.

• api/roundtrip-matrix.tsv records encoder/decoder round-trip evidence for

every API contract family.

• api/runtime-boundary-matrix.tsv separates pure schema constructors from

runtime operations and rejects constructor-only production evidence.

• api/diagnostic-contracts.tsv records stable API contract diagnostics for

missing fields, invalid variants, bad types, denied capabilities,

unsupported versions, constructor-only evidence, route mismatches, and

round-trip failures.

• release/api-contract-evidence.tsv, release/final-discipline.tsv,

release/test-helpers.txt, and tools/final-release-discipline-check.py

make API contract hardening a required bounded-source release input.

• tools/contract-inventory-generate.py assigns API and route contract terms

under app package paths to API contract evidence instead of package metadata

evidence.

Milestone 5: Package Contract Hardening

Status: done.

Goal: make package contracts prove resolver, registry, publication, and rollback

behavior.

Submilestones:

• 5.1 Inventory package metadata, lockfile, resolver, registry, publish,

install, cache, offline, checksum, signature, yanking, deprecation, alias, and

rollback contracts.

• 5.2 Add resolver tests for version ranges, conflicts, yanks, pre-releases,

namespace ownership, and offline mode.

• 5.3 Add registry integrity tests for checksums, signatures, provenance,

bundle shape, package pages, and index metadata.

• 5.4 Add publish workflow tests for validation, signing, promotion,

deprecation, rollback, and failure recovery.

• 5.5 Add diagnostics for incompatible lockfiles, missing packages, bad

signatures, checksum mismatch, yanked versions, and namespace violations.

• 5.6 Update package docs to distinguish package contracts from package

descriptions.

Acceptance:

• Every package-contract row has resolver or registry tests, integrity

evidence, failure diagnostics, docs, and release evidence.

• Package contracts cover rollback and provenance, not only installation.
• Registry pages show stability and deprecation state from source metadata.

Completion evidence:

• package/contract-inventory.tsv inventories package metadata, lockfile,

local registry, remote resolver, SemVer, install/cache, checksum/signature,

publish, yank/tombstone/advisory, alias/deprecation, rollback/provenance, and

registry-page contract surfaces.

• package/resolver-matrix.tsv records resolver evidence for version ranges,

conflicts, yanks, prereleases, namespace ownership, offline mode, lockfile

generation, cache reuse, and missing-package failures.

• package/registry-integrity-matrix.tsv records checksum, signature,

provenance, bundle-shape, package-page, index-metadata, alias, deprecation,

and tombstone integrity evidence.

• package/publish-workflow-matrix.tsv records validation, signing, promotion,

deprecation, rollback, failure-recovery, ownership, and advisory workflow

evidence.

• package/diagnostic-contracts.tsv records stable package contract

diagnostics for lockfile incompatibility, missing packages, bad signatures,

checksum mismatch, yanked versions, namespace violations, missing rollback,

and missing provenance.

• release/package-contract-evidence.tsv, release/final-discipline.tsv,

release/test-helpers.txt, and tools/final-release-discipline-check.py

make package contract hardening a required bounded-source release input.

• docs/package-registry.html, docs/package-system.html, and docs/packages.html

distinguish package contracts from package descriptions.

Milestone 6: Runtime Contract Hardening

Status: done.

Goal: make runtime contracts prove host behavior, capability enforcement, and

failure semantics.

Submilestones:

• 6.1 Inventory memory, IO, file, process, socket, browser, HTTP, web, service,

actor, distributed, embedded, and hardware runtime contracts.

• 6.2 Add runtime tests for successful behavior and failure behavior.
• 6.3 Add negative security tests for denied capabilities, path traversal,

network misuse, process injection, descriptor leaks, sandbox escapes, and

invalid runtime roots.

• 6.4 Add observability evidence for runtime failures.
• 6.5 Ensure deterministic test fixtures remain under test-only paths and are

never release evidence for production runtime behavior.

• 6.6 Add operator docs for runtime contracts that affect deployment,

credentials, state, or external services.

Acceptance:

• Every runtime-contract row has production runtime tests, negative security

tests, docs, and release evidence.

• Runtime contracts cannot be satisfied by test fixtures alone.
• Failure semantics are documented and stable.

Completion evidence:

• runtime/contract-inventory.tsv inventories memory, streaming IO, file,

process, socket, browser, HTTP, web, service, actor, distributed, embedded,

hardware, Live, and assurance runtime contract surfaces.

• runtime/security-negative-matrix.tsv records denied capability, path

traversal, network misuse, process injection, descriptor leak, sandbox

escape, and invalid runtime root security cases.

• runtime/failure-semantics.tsv records stable failure behavior for runtime

memory, streaming IO, file, process, socket, browser, HTTP, web, service,

actor, distributed, embedded, hardware, Live, and assurance surfaces.

• runtime/observability-matrix.tsv records report, status, trace, hash, and

operator-visible runtime failure evidence.

• runtime/fixture-scope-matrix.tsv marks deterministic runtime fixtures as

test-only and forbids their use as production runtime evidence.

• runtime/diagnostic-contracts.tsv records stable runtime contract

diagnostics for capability denial, path escape, network misuse, process

injection, descriptor leaks, sandbox escape, invalid runtime roots, fixture

evidence misuse, and missing observability.

• release/runtime-contract-evidence.tsv, release/final-discipline.tsv,

release/test-helpers.txt, and tools/final-release-discipline-check.py

make runtime contract hardening a required bounded-source release input.

• docs/runtime-contracts.html, docs/runtime-production-capabilities.html,

docs/runtime-reliability.html, and docs/security-program.html link runtime

contracts to operator-facing docs and release evidence.

Milestone 7: Source And Tooling Contract Hardening

Status: done.

Goal: make source-level and tooling contracts prove compiler and toolchain

behavior.

Submilestones:

• 7.1 Inventory syntax, type, effect, parser, compiler phase, IR, lowering,

optimizer, diagnostics, formatter, docs, lint, release, and registry tooling

contracts.

• 7.2 Add parser/checker/lowering tests for every source contract.
• 7.3 Add invalid examples and stable diagnostics for every rejected source

contract.

• 7.4 Add source-owned tooling tests for contract inventory generation,

formatting, docs, lint, release helpers, and registry metadata.

• 7.5 Add performance budgets for contract checks so they remain safe for normal

development.

• 7.6 Document source contract stability and edition behavior.

Acceptance:

• Every source-contract and tooling-contract row has tests, diagnostics,

docs, and owner evidence.

• Contract gates are bounded and do not trigger session-breaking heavy commands.
• Source contract changes require ADR/RFC records.

Completion evidence:

• source/contract-inventory.tsv inventories syntax, parser, typed parameter,

ADT, effect, type/effect, import, compiler phase, IR, lowering, optimizer,

diagnostics, and template source-kind contracts.

• source/parser-checker-lowering-matrix.tsv,

source/invalid-diagnostics.tsv, and source/edition-stability.tsv record

parser/checker/lowering evidence, invalid examples, stable diagnostics, and

current-edition compatibility policy.

• tooling/contract-inventory.tsv and

source/tooling-performance-budgets.tsv record formatter, docs, lint,

resolver, registry, release helper, contract inventory, source-owned tooling,

docs coverage, final release, and registry metadata evidence with bounded

budgets.

• release/source-tooling-contract-evidence.tsv,

make source-tooling-contract-hardening-check, release helper metadata, and

final release discipline wire the source/tooling contract gate into release

evidence.

• docs/adrs/ADR-0086-source-tooling-contract-hardening.html and

docs/rfcs/RFC-0086-source-tooling-contract-hardening.html record the accepted

design and documentation impact review.

Milestone 8: Library Naming And Domain Model Cleanup

Status: done.

Goal: remove ambiguous *-contract names where the value is a domain model,

schema, profile, policy, descriptor, or specification instead of a checked

compatibility boundary.

Submilestones:

• 8.1 Generate a list of library functions, constructors, accessors, docs, and

tests that include contract.

• 8.2 Rename domain values to precise names such as profile, schema,

policy, descriptor, spec, layout, invariant, or boundary.

• 8.3 Keep compatibility aliases only when a public package needs a versioned

transition.

• 8.4 Add deprecation metadata, release notes, and migration examples for public

renames.

• 8.5 Update generated API docs, package README files, registry pages, and

examples in the same change.

• 8.6 Add lint coverage to prevent new ambiguous contract names.

Acceptance:

• Remaining *-contract names are justified by contract inventory rows.
• Domain-model names use precise vocabulary.
• Public renames have compatibility aliases, tests, docs, and release notes.

Completion evidence:

• release/library-contract-name-inventory.tsv records every old library

source token using contract, its replacement, source path, surface, and

rename kind.

• libs/*/src/lib.0x0 now uses schema vocabulary for the rewritten library

domain-model symbols.

• release/library-contract-rename-ledger.tsv, libs/symbol-aliases.tsv, and

libs/symbol-deprecations.tsv record public symbol aliases, deprecation

metadata, and removal timing.

• make library-contract-naming-check validates that ambiguous library source

names do not return, that replacements exist, and that public renames have

compatibility metadata.

• docs/adrs/ADR-0087-library-contract-name-cleanup.html and

docs/rfcs/RFC-0087-library-contract-name-cleanup.html record the accepted

design and documentation impact review.

Milestone 9: Public Documentation And Learning Cleanup

Status: done.

Goal: make contract terminology understandable for beginners without weakening

technical reference docs.

Submilestones:

• 9.1 Add docs/contract-integrity.html as the exact reference.
• 9.2 Add a beginner-friendly explanation to learning docs that uses

guarantee and checked boundary before introducing contract.

• 9.3 Update cookbook and examples to avoid unexplained contract language.
• 9.4 Update API, ABI, runtime, package, and release docs to link to the

contract taxonomy where relevant.

• 9.5 Add docs coverage rows after the gate exists.
• 9.6 Regenerate public site metadata and search index.

Acceptance:

• Beginner docs explain the idea without unexplained jargon.
• Reference docs define contract terminology precisely.
• make docs-coverage-check passes with contract integrity documentation

included.

Completion evidence:

• docs/contract-integrity.html defines beginner wording, formal taxonomy,

evidence files, gate behavior, and forbidden uses.

• site/learn-0x0/14-release-and-governance.html and site/cookbook.html

introduce guarantees and checked boundaries before the formal term.

• API, ABI, runtime, package, and release reference docs link to

docs/contract-taxonomy.tsv and docs/contract-integrity.html.

• docs/docs-coverage.tsv and tools/docs-coverage-check.py require the

contract-integrity coverage class.

• site/metadata.tsv, site/search-index.json, site/sitemap.xml, and

site/libs/sitemap.xml were regenerated with the new reference page.

Milestone 10: Release Integration And Production Closure

Status: done.

Goal: make contract integrity part of the release decision.

Submilestones:

• 10.1 Add make contract-integrity-check to final release discipline.
• 10.2 Add contract inventory and integrity reports to release artifacts.
• 10.3 Add contract integrity status to feature support and production readiness

matrices.

• 10.4 Add upgrade/downgrade and compatibility notes for contract renames and

stability changes.

• 10.5 Add a release note section for contract integrity.
• 10.6 Run the bounded contract gate, docs gate, package gate, runtime gates,

ABI gates, and final release discipline gate.

Acceptance:

• make contract-integrity-check passes.
• make final-release-discipline-check includes contract integrity as a

required release input.

• Public docs and generated site pages are current.
• The release notes identify contract integrity as closed for the covered

release.

Completion evidence:

• release/contract-integrity-artifacts.tsv records the release artifact set

for taxonomy, inventory, surface evidence, compatibility metadata, closure

reports, and final release discipline.

• release/contract-integrity-closure.tsv records closure status for taxonomy,

inventory, ownership, fixture scope, renames, surface hardening, public docs,

release artifacts, and release decision wiring.

• release/contract-compatibility.tsv records upgrade, downgrade, and

compatibility notes for taxonomy, inventory, library renames, surface

evidence, and release-decision changes.

• make contract-integrity-check validates the release reports in addition to

taxonomy, inventory, ledger, drift, fixture-scope, and staged ADR/RFC

documentation-impact checks.

• docs/feature-support-matrix.html, docs/production-readiness-matrix.html, and

docs/production-readiness-matrix.tsv mark contract integrity implemented.

• docs/release-notes.html identifies contract integrity as closed for the

covered release.

Final Completion Signal

This roadmap is complete when:

• all milestones above are closed by implementation, not wording alone;
• all public contract uses are classified, implemented, tested, documented, and

owned;

• ambiguous contract names have been renamed or justified by inventory evidence;
• production paths do not use test fixtures as contract evidence;
• make contract-integrity-check passes;
• final release discipline includes and passes contract integrity;
• public documentation explains the terminology for beginners and defines it

exactly for maintainers.