platform-contracts

platform-contracts is the Legion platform's authoritative, design-tree-owned home for the shared cross-component contracts — the artifacts that bind across two or more of the platform's repositories and are therefore owned by no single component. It holds the inter-component seam schemas (Seams A, B, C), the Bodega↔Spire storage-adapter SPI, the platform capability-token (dragons) capability-token profile + issuer contract, and the conformance TCK spec every consumer's adapter must pass.

This package was decided by farm-to-table ADR-0015 ("Cross-repo coordination — the platform-contracts package and the amendment return-seam", Accepted 2026-06-29). It is the resolution of ADR-0012 §3's open question — where the shared storage-adapter SPI + TCK should live — in favor of a dedicated, neutral, versioned package that both consumers pin.

It was stood up on 2026-06-30 from the Legion platform design tree (../farm-to-table).

The one thing to understand first: this repo is design-tree-owned, not downstream-owned

This is the load-bearing distinction, and it differs from the Bodega / Spire / Kitchen build-repo seeds (which say "you author your own build ADRs here"). Here:

• The contract SHAPES are authoritative in this repo. contracts/ holds the platform-owned, versioned truth for each seam schema, the storage SPI, the token profile, and the TCK. Consumers read these; they do not fork them.
• Contract CHANGES do not originate here. They come from ../farm-to-table ADRs. A downstream repo that discovers, at build time, that a contract must change proposes the change via the amendment return-seam (ADR-0015 §2): it drops a contract-amendment-proposal into the design tree's bionic/inbox/. The design tree disposes — authoring a council-gated amending ADR, or declining with a recorded rationale. No downstream repo ever edits a contract in this repo directly. See inbox/README.md (this repo's copy of the return-seam target) and VERSIONING.md.
• The per-repo IMPLEMENTATIONS live in the consuming repos, not here. Bodega and Spire each implement the storage-adapter SPI behind the port; the Harvester implements the Seam A producer; the Compendium implements the Seam B/C producer; Bodega implements the Seam B/C consumer. This repo is the contract + the conformance TCK, never the implementations (ADR-0015 §1; ADR-0013 §2).

If you want to change a contract, you are in the wrong repo — go to ../farm-to-table and file an amendment proposal. If you want to conform to or read a contract, you are in the right place.

What this package homes (ADR-0015 §1, ADR-0016, ADR-0017)

contracts/
  seams/
    seam-a-harvester-compendium.md   # Harvester → Compendium reference contract (ADR-0016 §2 Seam A)
    seam-b-compendium-bodega.md      # Compendium → Bodega association-event stream (ADR-0032)
    seam-c-erasure-propagation.md    # erasure propagation (ADR-0017 Seam C)
  storage/
    storage-adapter-spi.md           # the Bodega↔Spire storage-adapter SPI (ADR-0012 §3, ADR-0015 §1)
  tokens/
    dragons-capability-token-profile.md    # the platform dragons capability-token profile (ADR-0021; dev-draft per ADR-0023)
    token-issuer-contract.md         # the platform capability-token issuer contract (ADR-0015 §1, ADR-0012 §3)
  tck/
    README.md                        # the conformance TCK spec (ADR-0012 §2/§3, ADR-0015 §3, ADR-0016, ADR-0017)

Everything in contracts/ is versioned as one artifact on the package's semver line (VERSIONING.md) and derived from the ADRs copied into seed/adrs/ for provenance.

Semver + version-pinning + the return-seam, in one paragraph

platform-contracts is semver-versioned (starting at 0.1.0 — see CHANGELOG.md). Every consumer repo version-pins it (an exact pin, opted into per release — ADR-0015 §1). The TCK version travels with the contract version — one artifact, one version (ADR-0012 §3; ADR-0015 acceptance criterion 5), so pinning a platform-contracts version pins both the contract shapes and the conformance tests against them. A consumer that needs a contract to change does not edit it here — it files a contract-amendment-proposal back to the design tree (the amendment return-seam, ADR-0015 §2); the design tree authors the amending ADR (council-gated) and cuts a new platform-contracts release, which the consumer then re-pins. Full mechanics: VERSIONING.md.

How a consumer pins and conforms (the consumer's-eye view)

1. Pin a version of platform-contracts (exact, per VERSIONING.md).
2. Implement your side of each relevant contract in your own repo, behind the port — no backend type leaks through the SPI (ADR-0012 §1; ADR-0009 §1).
3. Wire the shared TCK as a CI gate (contracts/tck/README.md) — Bodega and Spire both run the same storage TCK; Seam B/C consumers run the ordering/idempotency/equivalence-class tests.
4. To change the contract: file a contract-amendment-proposal to ../farm-to-table/bionic/inbox/ (never edit contracts/ here). Re-pin when the amending release ships.

Where to start

1. AGENTS.md — orientation for anyone (human or agent) turning these specs into a real versioned package: the design-tree-owned nuance, the invariants, the recommended stack, and the build cycle. Read first.
2. VERSIONING.md — the semver policy, breaking-vs-additive rules, the amendment return-seam mechanics, and how consumers pin.
3. contracts/ — the authoritative contract specs themselves.
4. seed/adrs/ — provenance copies of the founding binding ADRs (the source of truth lives in ../farm-to-table/bionic/adrs/; these are provenance copies).

The wire format is pinned

farm-to-table ADR-0018 (Accepted 2026-06-30) pins the canonical wire format to JSON Schema (draft 2020-12): the schema wins on any data-shape disagreement; behavior (cross-field rules, refusal predicates) lives in the executable TCK. The specs in contracts/ pair each prose contract with its .schema.json; new surfaces follow the same pattern (see AGENTS.md §build cycle).

Layout

README.md            What it is, why (ADR-0015), the discipline, how consumers pin
AGENTS.md            Orientation + the design-tree-owned nuance + invariants + stack + build cycle + open decisions
VERSIONING.md        Semver policy + amendment return-seam mechanics + consumer pinning
CHANGELOG.md         Starts at 0.1.0 (initial contract set)
contracts/           The authoritative, versioned contract artifacts (seams, storage SPI, tokens, TCK)
seed/adrs/           Provenance copies of the founding binding ADRs (source of truth is ../farm-to-table/bionic)
inbox/               The return-seam target: downstream contract-amendment-proposals land here