Metadata-Version: 2.5
Name: legion-platform-contracts
Version: 0.2.0
Summary: Legion platform authoritative shared cross-component contracts (schemas, storage SPI, token profile, TCK). Decided by farm-to-table ADR-0015; wire format pinned by ADR-0018.
Project-URL: Homepage, https://github.com/legion-os-dragons/farm-to-table-platform-contracts
Project-URL: Source, https://github.com/legion-os-dragons/farm-to-table-platform-contracts
Project-URL: Changelog, https://github.com/legion-os-dragons/farm-to-table-platform-contracts/blob/main/CHANGELOG.md
Author: Legion platform
License: proprietary
Keywords: conformance,contracts,json-schema,storage-spi,tck
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.6
Provides-Extra: codegen
Requires-Dist: datamodel-code-generator>=0.25; extra == 'codegen'
Provides-Extra: dragons
Requires-Dist: legion-foundation==0.1.1; extra == 'dragons'
Provides-Extra: tck
Requires-Dist: jsonschema>=4.20; extra == 'tck'
Requires-Dist: pytest>=8.0; extra == 'tck'
Description-Content-Type: text/markdown

# 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
```
