legion-platform-contracts 0.2.0__tar.gz

legion_platform_contracts-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Env / secrets
+.env
+*.local
+
+# OS / editor
+.DS_Store
+*.swp
+
+# Generated binding provenance artifact (regenerate via src/platform_contracts/_generate_models.py).
+# The curated, committed binding is src/platform_contracts/models.py; this raw generator output carries
+# a non-deterministic timestamp header, so it stays out of version control (ADR-0018 §3: schema is
+# authoritative, bindings are generated-from).
+src/platform_contracts/_generated_models.py
+
+# build artifacts (the published index artifact carries the canonical bytes)
+dist/

legion_platform_contracts-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+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
+```

legion_platform_contracts-0.2.0/README.md

@@ -0,0 +1,108 @@
+# 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
+```

legion_platform_contracts-0.2.0/contracts/entities/README.md

@@ -0,0 +1,119 @@
+# Canonical entity schemas (ADR-0030)
+
+- **Contract version:** tracks the `platform-contracts` git ref (ADR-0023 §2); the package-version pin
+  returns at phase exit.
+- **Source ADRs:** `farm-to-table` **ADR-0030** (*Canonical entity DTO schemas*, Accepted 2026-07-22 —
+  the foundational convergence cut; amends ADR-0016's prose boundary), **ADR-0031** (*Golden-record
+  derivation model — occurrence-derived, not event-injected*, Accepted 2026-07-22; amends ADR-0030),
+  **ADR-0018** (the canonical wire format these are emitted in), **ADR-0015 §2** (the amendment
+  return-seam any change rides).
+- **Cut:** A1 (2026-08-02), the first Phase A realization cut; `entity.schema.json` + its legs landed in
+  the A1 completion pass (2026-08-04).
+
+## What's here
+
+| Artifact | Pins | Source |
+|---|---|---|
+| `entity-id.schema.json` | The canonical **`EntityId`**: opaque string, `pattern: ^ent_[A-Za-z0-9_-]+$`, `maxLength: 64`. **Contractual:** pattern + length. **Not contractual:** the mint method. Only Compendium mints (ADR-0016). | ADR-0030 §1 |
+| `entity.schema.json` | The canonical **entity DTO** — **seam payloads ONLY**: `{ scope{account_id, project_id}, entity_id (referenced `EntityId`), cluster_state?, resolution_confidence? }`, `additionalProperties: false`. Carries identity + resolver-owned **entity/cluster-level** metadata and **no attribute values**. | ADR-0030 §2 + ADR-0031 §2 (SB-0/SB-6) |
+| `entity-provenance.schema.json` | **`provenance`-of-the-assertion**: `{ source, extractor_id?, extractor_version? }` — `source` required enum; extractor pair required iff `source == "extraction"`, forbidden otherwise; `additionalProperties: true` (additive-safe). | ADR-0030 §3 (SB-8) |
+
+### What the entity DTO deliberately does NOT carry
+
+- **No attribute values** (ADR-0031 §2). Gold is **occurrence-derived**: the store composes
+  golden-record attribute content from the occurrences it has ingested; a resolution event never
+  injects values. `additionalProperties: false` closes the door at the schema layer; the **fail-closed
+  hard reject** of a non-empty value injection is behavioral (ADR-0018 §2 — schema pins shapes, the TCK
+  pins behavior). Attribute **survivorship** across occurrences is Bodega's (ADR-0013, per ADR-0031
+  §2a) — this contract carries the association, never its resolution.
+- **No evidence associations.** Those ride the Seam B association event
+  (`../seams/seam-b-association-event.schema.json`, ADR-0032). The **stream mechanics** — delta shape,
+  snapshot/reconcile, merge/split transfer, the pending-ref bound, the `ref` namespace — are ADR-0031
+  §2b's forward-scoped deliverables (landed in A2/A3): **cited here, not re-opened.**
+- **No provenance envelope.** `provenance` (ADR-0030 §3) is provenance-of-the-**assertion** — a
+  property of the *event* that asserts, not of the entity identity, so it rides the assert body.
+  `InferenceProvenance` is **prohibited outright** (ADR-0025 AC-2: gold-spine content envelopes only —
+  never a Seam A/B/C payload, never an SPI DTO).
+- **Resolver-owned metadata is allowed, at the entity/cluster scope only** (ADR-0031 §2): overall
+  `resolution_confidence` + `cluster_state`. The bound is **influence, not authorship** — a consumer
+  may weight survivorship by confidence, but the metadata door is never a soft path to authoring a
+  value. **Edge**-scoped metadata (per-`(entity_id, ref)` match rationale) rides the association
+  event's `AddedRef`, not this DTO.
+
+## The boundary principle (ADR-0030 §2 — read this before adding a schema)
+
+A shape is platform-canonical **iff it crosses a platform seam** (judged on real exposure — public API,
+persisted interchange artifact, event payload, shared TCK fixture — not repo ownership). Canonical
+here: `EntityId`, the `provenance` sub-shape, and (in `contracts/seams/`) the lineage-event bodies.
+**Repo-internal, deliberately NOT schematized:** golden-record storage layouts, derivation substrates,
+projections, resolve-output shapes — per ADR-0030 §2/AC-3, the sweep's "no golden-record/projection/
+resolve-output schema" is **correct and intended**, with one escape hatch: if any such shape is ever
+exposed across a component boundary, it becomes a seam contract and is schematized **then** (via the
+ADR-0015 return-seam), never by accretion.
+
+## What this fixes (the sweep items closed)
+
+The signed-off convergence sweep (`BRIEF-seam-bc-entity-convergence-sweep`, ADR-0026 §2) found four
+items this directory discharges:
+
+- **SB-0 / B0 — no canonical entity DTO existed (ADR-0030 §2):** only the Seam B lineage event was
+  schematized, so entity shapes drifted freely across repos. `entity.schema.json` is now the canonical
+  seam-crossing entity shape. The same finding's *other* half is closed by **naming shapes out**: the
+  golden-record / projection / resolve-output shapes are **repo-internal, correct and intended, not a
+  gap to fill** (ADR-0030 §2/AC-3 — Option B rejected). See the boundary principle above.
+- **SB-3 / B1 — the id live break (ADR-0030 §1):** Compendium mints `ent_<uuid4hex>`; Bodega typed
+  `entity_id` as `uuid.UUID` and could not ingest a real id. The contract is now: validate against the
+  pattern at the boundary, **never parse structure**. (Bodega's migration — drop the cast and any
+  UUID-typed persisted key columns — rides the design tree's B1 pack.)
+- **SB-6 / SB-7 — the derivation inversion (ADR-0031 §2):** the two sides of Seam B held *opposite*
+  handling of the same field — the schema/Compendium read `attributes` as values **Bodega folds in**,
+  while Bodega (ADR-0005 D5, as built) **rejects** injected values and composes gold from ingested
+  occurrences. Settled on the principled side: **occurrence-derived**. `attributes` is redefined →
+  `evidence_refs` (associations, not values), and a non-empty value injection is a **fail-closed hard
+  reject** — ADR-0031 §2 disambiguates D5's "ignored"-vs-"rejected" prose to a hard reject, which **may
+  require a Bodega code change**; Bodega's current behavior is **not** ratified as conformant here, its
+  conformance is its own cycle's finding. The DTO's contribution is structural: it admits no
+  attribute-shaped field at all.
+- **SB-8 — provenance unschematized (ADR-0030 §3):** `entity_assert.provenance` was `type: object` with
+  no pinned shape; Compendium's actual carrier (`extractor_id`, `extractor_version`) is now typed and
+  conditionally scoped (required iff `source == "extraction"`, forbidden otherwise).
+
+And the enforcement that keeps them closed:
+
+- **Anti-drift (ADR-0030 AC-7):** seam schemas `$ref` the canonical `EntityId`, never re-declare
+  `type: string` inline — enforced mechanically by the lint in
+  `src/platform_contracts/tck/test_entities.py`, which is proven to *fire* on inline re-declarations in
+  every position one could hide (top-level, nested, inside `allOf`/`anyOf`/`oneOf`, inside an array's
+  `items`). The legacy exemption allowlist is **empty** and shrink-only (all seam re-cuts landed:
+  A2 association, A3 identity-op log, A4 Seam C).
+
+### What is deferred (scope discipline)
+
+- **Provenance-of-derivation-inputs is not on the wire at all.** Per ADR-0031 the event carries ID-only
+  pointers; occurrence-granularity inputs (span / offset / source-document) live in Bodega's ingested
+  occurrence substrate, which the store already holds.
+- **Stream mechanics** stay with the Seam B wire-shape/TCK work (ADR-0031 §2b, realized in A2/A3) —
+  cited, not re-opened here.
+- **`InferenceProvenance`** is prohibited on every shape in this directory (ADR-0025 AC-2: gold-spine
+  content envelopes only — enforced by the `$ref`-scoping lint in `test_egress.py`).
+
+## TCK
+
+`src/platform_contracts/tck/test_entities.py` (`pytest -m entities`):
+
+- **`EntityId`** — round-trip opacity (an `ent_`-prefixed non-UUID-parseable value round-trips; a
+  well-formed **bare UUID fails** — the Bodega bug class), pattern/length boundaries, non-string
+  rejection, and **mint-method agnosticism** (structurally unrelated suffixes all validate and the
+  schema declares no structure-pinning keyword — pinning the mint would collapse
+  validate-at-boundary into parse-structure).
+- **The entity DTO** — identity-only acceptance, full-tenancy requirement, id validation *through* the
+  canonical `$ref` (resolved offline), the **value-injection bar** (`attributes` / `name` /
+  `golden_record` / `canonical_values` / `evidence_refs` all inadmissible), and the two provenance
+  prohibitions (`inference_provenance`, and assertion `provenance` — an event property, not an entity
+  one).
+- **The §2 boundary tripwire** — no `entity-resolve-output` / `entity-projection` / `golden-record`
+  schema is shipped. Retiring that leg requires the ADR-0015 return-seam (the "becomes canonical if
+  exposed" hatch), not a local edit.
+- **Provenance** — the conditional-requirement matrix + additive-openness.
+- **AC-7** — the schema-reference lint plus its has-teeth fixture and the empty-allowlist freeze
+  tripwire.

legion_platform_contracts-0.2.0/contracts/entities/entity-id.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://legion.platform/contracts/entities/entity-id.schema.json",
+  "title": "EntityId — the canonical opaque platform entity identifier",
+  "$comment": "platform-contracts; canonical wire format JSON Schema draft 2020-12 (ADR-0018 §1). Source: farm-to-table ADR-0030 §1 (canonical entity-identity schema, Accepted 2026-07-22), amending ADR-0016's prose. Distributed by git ref during the pre-first-release iteration phase (ADR-0023 §2). CONTRACTUAL: the pattern (the ent_ prefix + the bounded character class) and the length bound — entity_id is a join key / PK across >=2 stores, so bounding it is free pre-prod. NOT CONTRACTUAL: the generation method (currently Compendium's uuid4().hex) — Compendium may change how it mints the suffix as long as the result still matches the pattern (ADR-0030 §1). MINT AUTHORITY (ADR-0016, unchanged): only Compendium mints an entity_id; external identifiers (LEI/CUSIP/...) are evidence, never the key. OPACITY (ADR-0030 §1): every consumer treats the value as an opaque string — never UUID-typed, never structurally interpreted; boundary pattern-validation is permitted (validate-at-boundary != parse-structure). REFERENCE RULE (ADR-0030 AC-7): Seam B and Seam C schemas $ref this type rather than re-declaring 'type: string' inline — enforced by the anti-drift lint in the TCK (test_entities.py).",
+  "type": "string",
+  "pattern": "^ent_[A-Za-z0-9_-]+$",
+  "maxLength": 64,
+  "description": "Opaque platform entity id. Validate against the pattern at the seam boundary; never parse or depend on the suffix structure. Examples: 'ent_surv_001', 'ent_9f3ab2c1d4e5f60718293a4b5c6d7e8f' (a uuid4 hex suffix — opaque, NOT UUID-typed)."
+}

legion_platform_contracts-0.2.0/contracts/entities/entity-provenance.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://legion.platform/contracts/entities/entity-provenance.schema.json",
+  "title": "EntityAssertionProvenance — provenance-of-the-assertion (source-discriminated)",
+  "$comment": "platform-contracts; canonical wire format JSON Schema draft 2020-12 (ADR-0018 §1). Source: farm-to-table ADR-0030 §3 (SB-8; Accepted 2026-07-22). Distributed by git ref (ADR-0023 §2). Pins provenance-OF-THE-ASSERTION (who/what produced this entity_assert event): 'source' is REQUIRED and enum-discriminated; the extractor pair is REQUIRED iff source == 'extraction' and FORBIDDEN otherwise (additive-safe: merge/split/curation/backfill/migration origins carry no extractor id, so no assert is forced to fabricate one). additionalProperties is TRUE (additive-open) per ADR-0030 §3. SCOPE BOUNDARY: provenance-of-the-derivation-inputs (occurrence-granularity refs — span / offset / source-document) is NOT here and NOT on the wire — per ADR-0031 the event carries ID-only pointers and those occurrence-granularity inputs live in Bodega's ingested occurrence substrate; the two are orthogonal (event origin vs. the evidence a consumer folds in). PROHIBITED here: InferenceProvenance (ADR-0025 AC-2 — $ref'd by the gold-spine content envelopes ONLY; never on Seam A/B/C event payloads or SPI DTOs).",
+  "type": "object",
+  "required": ["source"],
+  "additionalProperties": true,
+  "properties": {
+    "source": {
+      "enum": ["extraction", "merge", "split", "curation", "backfill", "migration"],
+      "description": "Origin of the assertion. Covers the merge/split and human/tooling origins that have no extractor identity."
+    },
+    "extractor_id": {
+      "type": "string",
+      "description": "Extractor identity — REQUIRED iff source == 'extraction'; FORBIDDEN otherwise."
+    },
+    "extractor_version": {
+      "type": "string",
+      "description": "Extractor version — REQUIRED iff source == 'extraction'; FORBIDDEN otherwise."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "source": { "const": "extraction" } },
+        "required": ["source"]
+      },
+      "then": { "required": ["extractor_id", "extractor_version"] },
+      "else": {
+        "not": {
+          "anyOf": [
+            { "required": ["extractor_id"] },
+            { "required": ["extractor_version"] }
+          ]
+        }
+      }
+    }
+  ]
+}

legion_platform_contracts-0.2.0/contracts/entities/entity.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://legion.platform/contracts/entities/entity.schema.json",
+  "title": "Entity — the canonical entity DTO (seam payloads ONLY)",
+  "$comment": "platform-contracts; canonical wire format JSON Schema draft 2020-12 (ADR-0018 §1). Source: farm-to-table ADR-0030 §2 (the entity-shape boundary, Accepted 2026-07-22; amends ADR-0016's prose) + ADR-0031 §2 (the occurrence-derived derivation model + the value-vs-metadata bar, Accepted 2026-07-22). Distributed by git ref during the pre-first-release iteration phase (ADR-0023 §2). Cut A1 (2026-08-02). SCOPE — SEAM PAYLOADS ONLY: a shape is platform-canonical iff it crosses a platform seam, judged on real exposure (public API / persisted interchange artifact / event payload / shared TCK fixture), never on repo ownership (ADR-0030 §2). This DTO is the seam-crossing entity: tenancy + the referenced canonical EntityId + resolver-owned entity/cluster-level metadata. NOT CANONICAL, deliberately NOT schematized here (ADR-0030 §2/AC-3 — the sweep's B0 is 'correct and intended, not a gap to fill'; schematizing them is Option B, REJECTED): Bodega's golden-record storage layout and its segment/occurrence derivation substrate, Compendium's entity_projection / redirect-graph internals, and Compendium's EntityResolveResult / resolve-output. TRIGGER (the narrow escape hatch): if any such repo-internal shape is ever exposed across a component boundary it BECOMES a seam contract and is schematized THEN, via the ADR-0015 §2 amendment return-seam — never by accretion here. NO ATTRIBUTE VALUES (ADR-0031 §2): gold is OCCURRENCE-DERIVED — the store composes golden-record attribute content from the occurrences it has ingested; a resolution event never injects attribute values. Anything Bodega would store as a golden-record ATTRIBUTE is a value and is barred; the schema layer closes the door with additionalProperties:false, and the fail-closed HARD REJECT of a non-empty value injection is behavioral (ADR-0018 §2 — schema pins shapes, the TCK pins behavior; ADR-0031 §2 disambiguates ADR-0005 D5's 'ignored' to a hard reject, which may require a Bodega code change — Bodega's conformance is its own cycle's finding, not ratified here). Attribute SURVIVORSHIP across occurrences is Bodega's (platform ADR-0013, per ADR-0031 §2a) — this contract carries the association, never its resolution. Evidence associations themselves ride the Seam B association event (contracts/seams/seam-b-association-event.schema.json, ADR-0032), not this DTO; the stream mechanics (delta shape, snapshot, merge/split transfer, pending bound, ref namespace) are ADR-0031 §2b's forward-scoped deliverables, cited here and NOT re-opened. RESOLVER-OWNED METADATA IS ALLOWED AT THE ENTITY/CLUSTER SCOPE (ADR-0031 §2): overall resolution confidence + cluster lifecycle state are legitimately the resolver's and are not attribute content — bound: metadata is influence, not authorship. EDGE-scoped metadata (per (entity_id, ref) match rationale) rides the association event's AddedRef, not this DTO. PROVENANCE: provenance-of-the-ASSERTION (ADR-0030 §3, entities/entity-provenance.schema.json) is a property of the EVENT that asserts, not of the entity identity — it rides the assert body, never this DTO. PROHIBITED: InferenceProvenance (ADR-0025 AC-2 — $ref'd by the gold-spine content envelopes ONLY, never a Seam A/B/C payload and never an SPI DTO; adding it FAILS the criterion) — mechanically enforced by the $ref-scoping lint in test_egress.py. REFERENCE RULE (ADR-0030 AC-7): entity_id $refs the canonical EntityId and is never re-declared as 'type: string' inline — enforced by the anti-drift lint in test_entities.py.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scope",
+    "entity_id"
+  ],
+  "properties": {
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "account_id",
+        "project_id"
+      ],
+      "properties": {
+        "account_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "project_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "description": "Nested tenancy — (account_id, project_id) scopes every artifact; tenancy IS identity and cross-tenant access is deny-by-default with existence-leak discipline (404, not 403) per ADR-0001. Matches the Seam A / Seam B / Seam C envelopes."
+    },
+    "entity_id": {
+      "$ref": "entity-id.schema.json"
+    },
+    "cluster_state": {
+      "enum": [
+        "active",
+        "merged",
+        "split"
+      ],
+      "description": "Resolver-owned entity/cluster-level metadata: the cluster's lifecycle state (ADR-0031 §2). Optional. Not attribute content. Where this DTO is composed into an event, the state is fixed as of that event's cut (ADR-0032 AC-1)."
+    },
+    "resolution_confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Resolver-owned entity/cluster-level metadata: overall confidence in the resolution of this cluster (ADR-0031 §2). Optional. Influence, not authorship — a consumer MAY weight survivorship by it (survivorship precedence is Bodega's, ADR-0013 / ADR-0031 §2a), but it is never a path to authoring an attribute value."
+    }
+  },
+  "examples": [
+    {
+      "scope": {
+        "account_id": "acct_7f21",
+        "project_id": "proj_ledger"
+      },
+      "entity_id": "ent_9f3ab2c1d4e5f60718293a4b5c6d7e8f"
+    },
+    {
+      "scope": {
+        "account_id": "acct_7f21",
+        "project_id": "proj_ledger"
+      },
+      "entity_id": "ent_surv_001",
+      "cluster_state": "merged",
+      "resolution_confidence": 0.94
+    }
+  ]
+}

legion_platform_contracts-0.2.0/contracts/provenance/inference-provenance.md

@@ -0,0 +1,51 @@
+# Inference-tier stamp + egress invariant — prose companion
+
+Contract tracking: git-ref iteration phase (farm-to-table **ADR-0023 §2**); not version-pinned.
+Authority: **ADR-0025** (the platform egress invariant). Schema wins on data-shape disagreement
+(ADR-0018 §1); this prose is the human companion to the two layers.
+
+## Two layers (ADR-0018)
+
+- **Layer (a) — data shape:** `contracts/provenance/inference-provenance.schema.json`, bound in Python
+  by `platform_contracts.provenance.InferenceProvenance`. The shared inference-tier stamp sub-object,
+  `$ref`'d by the **content-bearing gold-spine envelopes ONLY** — the Harvester clause-(A) gold-record
+  envelope and Bodega's stored-object envelope. **NOT** the Seam A/B/C event payloads, and **NOT**
+  the storage-adapter SPI DTOs. Spire's M3 pins **reserve / carry** the field (a stamped envelope is
+  not rejected) and implement no tier branching.
+- **Layer (b) — behavior:** `platform_contracts.egress` — the fail-closed **egress refusal predicate**
+  (`evaluate_egress`), its named `EgressViolation` taxonomy (`platform_contracts.errors`), and the
+  machine-checkable registries. This is the one shared **choke-point** every controlled-content
+  inference call site constructs its egress through (ADR-0025 §5).
+
+## The invariant (ADR-0025 §1)
+
+Any inference over controlled content MUST run on controlled infrastructure UNLESS the specific egress
+is permitted by the refusal predicate; every content-bearing gold-spine artifact carries a verifiable
+inference-tier stamp. Data flows forward; the stamp is forward-carried and immutable.
+
+## The refusal predicate (ADR-0025 §3) — PERMIT iff NO code fires; ambiguity ⇒ REFUSE
+
+`MissingTierStamp` · `UnboundDerivedPayload` · `LocalTierEgress` · `LicenseFloorViolation` ·
+`ModelHashUnpinned` · `MaskedEgressUnapproved` · `MissingEgressAttestation` · `UncarvedContentEgress`
+(the default-refuse over **all** controlled-derived off-infra content — not only raw bodies).
+Genesis extraction is the one deliberate `MissingTierStamp` exemption (it produces the stamp).
+
+## Ports (model/state-dependent; shapes pinned here, implementations downstream, ADR-0013 §2)
+
+`CouncilPayloadSchema`, `PiiScreen` (the whole-payload local screen; recall-floor CI-gated),
+`OptInStore`. Reference implementations live in the TCK (`tck/test_egress.py`). The concrete
+PII-screen model, per-tenant opt-in store, masking-profile store, attestation sink, and the guarded
+egress proxy are Compendium / Harvester / infra build details.
+
+## Council carve-out (ADR-0025 §6a) — decided; NOT live until its acceptance dependencies land
+
+Bounded, default-off, per-tenant opt-in egress of **non-person** reference names past the whole-payload
+PII screen, to a **vendor-control-registry**-admitted provider, per-call attested. Person-identifying
+egress is forbidden-by-default and routed to ADR-0017 §4. Going-live is gated on a pinned stratified
+benchmark + a per-activation DPIA-lite (see the ADR §6a / follow-on).
+
+## Conformance
+
+TCK §5 (`tck/test_egress.py`, `pytest -m egress`) drives every refusal code, the genesis exemption, the
+default-refuse, and the council / redacted-frontier PERMIT branches. Consumers wire the same leg as a CI
+gate with their own ports and MUST keep it green (ADR-0025 §5 / ADR-0015 AC#1).