setspec 0.3.0__tar.gz → 0.5.0__tar.gz

{setspec-0.3.0 → setspec-0.5.0}/CHANGELOG.md

@@ -7,6 +7,105 @@ packaging and release standards §3.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-09-02
+
+### Added
+
+- **`capability.evidence` `1.1`** (Phase 6, ADR-0058): an optional `adapter` field naming the
+  adapter axis a measurement was taken under. Absent — and byte-for-byte identical to `1.0` — on
+  every record measured on the bare base; a `@model_serializer` drops the field from the dump
+  entirely when unset, rather than emitting `"adapter": null`, so a non-adapter record written
+  through the new model is indistinguishable from what `0.4.0` writes (LA0 exit condition I15).
+  Lives on a new sibling class, `CapabilityEvidenceV1_1Fields`
+  (`CapabilityEvidenceV1_1Out`/`CapabilityEvidenceV1_1In`), rather than an edit to the existing
+  `CapabilityEvidenceFields`/`CapabilityEvidenceOut`/`CapabilityEvidenceIn`, which keep meaning
+  `1.0`: `benchmark.evidence_bundle` nests the `capability.evidence` shape by reference, so an
+  edit in place would have silently moved that schema's own committed `1.0` snapshot too. The
+  mechanism and the naming rule it implies — a bare exported name keeps the version it was frozen
+  at, so adopting `1.1` is an explicit import of `CapabilityEvidenceV1_1Out`/`In` and never
+  something a dependency upgrade delivers — are ADR-0068.
+- **`model.adapter_manifest` `1.0`** (Phase 6, ADR-0061): the operator-reviewed record behind one
+  adapter — `name`, `artifact_file`, `artifact_sha256`, optional `source_sha256`, `base` (a
+  provider model name plus an optional artifact digest, at `digest`-or-`name_only` confidence),
+  `declared_capabilities`, `data_classification`, `format`, `created_at`, `notes`. `name` and the
+  two digest fields are validated by reconstructing a `baseaicore.AdapterIdentity`, reusing that
+  type's own name-pattern and digest-normalization rules rather than a second implementation.
+  **`data_classification` is required, with no schema default** (ADR-0065 rule 1): a manifest that
+  omits it is invalid, never silently defaulted closed.
+- **`governance.egress_decision` `1.0`** (Phase 6, ADR-0051 §4, ADR-0054): one recorded egress
+  verdict — `decision_id`, an embedded request (`run_id`, `source_ref`, `data_classification`,
+  `target{name, remote, max_data_classification, provider_kind}`, `requested_at`), `verdict`
+  (`approved`/`denied`/`violation`), `reason`, `policy_name`, `policy_version`, `decided_at`.
+  SetSpec's first payload under a root other than `benchmark`/`capability`/`machine`/`model` —
+  added because the shape has a named second reader (IdeaPress's S4 egress badge reads decisions
+  PromptCadence exported, with SpotCheck not installed). Two nullable fields, both one level down.
+  `target.max_data_classification` is deliberate: "remote with no declared ceiling" is the
+  fail-closed case a policy must be able to deny and record. `request.requested_at` mirrors
+  SpotCheck spec §7's own `None` default and is on the wire so that its §11 contract 4 —
+  `from_payload(to_payload(d))` preserves **every** field — is keepable: a value-object field with
+  nowhere to land makes that round trip silently lossy. It is not a second record timestamp;
+  `decided_at` is the record's, and it stays required. SpotCheck does not exist as code yet;
+  nothing here imports it.
+- JSON Schema and goldens for all three: `capability.evidence/1.1.json` (`minimal`, `full`,
+  `unsupported`), `model.adapter_manifest/1.0.json` (`minimal`, `full`, `name_only`),
+  `governance.egress_decision/1.0.json` (`minimal`, `full`, `denied_no_ceiling`, `violation`).
+  The `capability.evidence/1.0` and `benchmark.evidence_bundle/1.0` schemas and goldens are
+  byte-for-byte unchanged — asserted by a dedicated contract test (I15) rather than by inspection.
+
+### Changed
+
+- **`baseaicore>=0.4.1,<0.5`** (was `>=0.4,<0.5`). `setspec.governance.v1` and
+  `setspec.model.v1` import `DataClassification` and the adapter value objects at module scope,
+  and neither name exists in `baseaicore 0.4.0` — the old floor permitted an install that raises
+  `ImportError` on import. The same floor is what makes the snapshots below reproducible.
+- Five already-committed `1.0` JSON Schema snapshots (`model.identity`, `benchmark.result`,
+  `benchmark.run_summary`, `capability.evidence`, `benchmark.evidence_bundle`) were regenerated to
+  pick up two `baseaicore 0.4.1` enum docstring edits (`IdentityConfidence`,
+  `ModelCapabilityFlag`) that the raised floor above surfaces in their nested `$defs`
+  descriptions. **Structurally identical** — no property, type or required-field changed,
+  confirmed by a description-stripped diff before committing; the regeneration is a byproduct of
+  the dependency bump, not a payload change (`docs/schemas.md` §5).
+- Bumped to 0.5.0 for the `capability.evidence` `1.1` addition and the two new payload types
+  (packaging standards §3: additive, non-breaking).
+
+## [0.4.0] — 2026-08-29
+
+### Added
+
+- **`setspec.prompts`** (Phase 5): prompt records and prompt packs, moved from
+  `freeweight.services.prompts` — `PromptRecord`, `PromptLibrary`, `load_record()`, `load_pack()`,
+  `build_manifest()`/`write_manifest()`, and the pack's three hashes
+  (`prompt_record_hash`/`prompt_subset_hash`/`pack_hash`, ADR-0028). Rendering runs through a
+  sandboxed, loader-less Jinja2 `Environment` with `StrictUndefined` (prompt-management-standards
+  §2.1): a referenced-but-unsupplied variable is an error, a template cannot reach the filesystem,
+  and dunder attribute access is refused. `load_pack()`'s `root` parameter is required — the
+  package carries no opinion about an application's pack layout; an application wanting a default
+  location supplies its own thin wrapper (FreeWeight's `freeweight.services.prompts.load_pack`
+  keeps its old default this way).
+
+  FreeWeight's own prompt pack adopts this module in the same change (pulling its P12 forward):
+  `freeweight.services.prompts` is now a re-export shim over `setspec.prompts`, verified to
+  produce a byte-identical `pack_hash` and per-record hash for every shipped prompt before and
+  after the move, with FreeWeight's own gate green afterwards. Two applications reading the same
+  pack format from two processes is the scenario ADR-0028's hashes exist for; the FreeWeight move
+  is the first proof of it.
+
+- **JSON Schema for `prompt.record` and `prompt.manifest`**, committed as package data under
+  `setspec/schemas/prompt.record/1.0.json` and `setspec/schemas/prompt.manifest/1.0.json`, with
+  golden examples under `setspec/goldens/prompt.{record,manifest}/1.0/{full,minimal}.json`. Both
+  are hand-authored rather than generated: `PromptRecord` is a plain dataclass, not a pydantic
+  envelope payload — a prompt record is a pack file on disk, never wrapped in a `SchemaEnvelope` —
+  so neither schema is registered in `PUBLISHED_SCHEMAS`/reachable through `json_schema_for()`,
+  and the goldens are illustrative examples rather than inputs to the envelope contract-test
+  matrix in `tests/contract/test_goldens.py`. Every golden round-trips through the real
+  `load_pack()` loader (not just schema validation) and its `pack_sha256` is the module's own
+  computed hash, not a hand-typed value.
+
+### Changed
+
+- Bumped to 0.4.0 for the `setspec.prompts` addition (packaging standards §3: additive,
+  non-breaking).
+
 ## [0.3.0] — 2026-08-28
 
 ### Added

{setspec-0.3.0 → setspec-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: setspec
-Version: 0.3.0
+Version: 0.5.0
 Summary: Every versioned data contract that crosses an application boundary: benchmark results, capability evidence, event/error envelopes, prompt records.
 Project-URL: Homepage, https://github.com/JPKell/SetSpec
 Project-URL: Documentation, https://github.com/JPKell/SetSpec/tree/main/docs
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: baseaicore<0.5,>=0.4
+Requires-Dist: baseaicore<0.5,>=0.4.1
 Requires-Dist: jinja2<4,>=3.1
 Requires-Dist: pydantic<3,>=2.9
 Provides-Extra: dev
@@ -35,18 +35,29 @@ Description-Content-Type: text/markdown
 
 Every versioned data contract that crosses an application boundary: benchmark results, capability evidence, event/error envelopes, prompt records.
 
-**Status:** `0.3.0` — Phases 1–2, 3A and 4 complete, and **the v1.0 contracts are frozen.** Eight
-payload types are published at `1.0` — `model.identity`, `machine.profile`, `benchmark.result`,
-`benchmark.run_summary`, `capability.evidence`, `benchmark.evidence_bundle`,
-`benchmark.goal_pack` and `benchmark.calibration_report` — each with generated JSON Schema and at
-least three golden payloads shipped as package data. `setspec.DRAFT_SCHEMAS` is empty, which is
-where the freeze is readable at runtime rather than only stated here; from now on a new optional
-field is a minor bump and anything else is a major, enforced by a snapshot diff in CI.
+**Status:** `0.5.0` — Phases 1–2, 3A, 4, 5 and 6 complete, and **the v1.0 contracts are frozen**,
+with the first additive minor now published on top of that freeze. Eight payload types remain
+frozen at `1.0` — `model.identity`, `machine.profile`, `benchmark.result`,
+`benchmark.run_summary`, `benchmark.evidence_bundle`,
+`benchmark.goal_pack` and `benchmark.calibration_report`, plus `capability.evidence` itself — each
+with generated JSON Schema and at least three golden payloads shipped as package data.
+`setspec.DRAFT_SCHEMAS` is empty, which is where the freeze is readable at runtime rather than only
+stated here; from now on a new optional field is a minor bump and anything else is a major,
+enforced by a snapshot diff in CI.
+
+Phase 6 (the adapter arc's LA0 checkpoint) adds three things without touching any of the above:
+`capability.evidence` gains an additive `1.1` (an optional `adapter` field, absent — and
+byte-identical to `1.0` — on every record with no adapter); `model.adapter_manifest` `1.0`
+publishes the operator-reviewed record behind one adapter; and `governance.egress_decision` `1.0`
+is the package's first payload under a root other than `benchmark`/`capability`/`machine`/`model`,
+carrying a recorded egress verdict for a reader that has SpotCheck installed or not.
 
 The [schema catalogue](docs/schemas.md) lists every payload type, its artifacts, and the
-cross-field rules the JSON Schema cannot express. Event and error envelopes (Phase 3) and prompt
-records (Phase 5) are not yet written and are therefore not part of the freeze. See the
-[development plan](docs/packages/setspec/development-plan.md) for what each phase adds.
+cross-field rules the JSON Schema cannot express. Event and error envelopes (Phase 3) are not yet
+written and are therefore not part of the freeze. Prompt records (`setspec.prompts`, Phase 5,
+added in 0.4.0) are shipped: prompt packs with their three content hashes and sandboxed
+rendering; they carry their own record schema version rather than joining the frozen payload types.
+See the [development plan](docs/packages/setspec/development-plan.md) for what each phase adds.
 
 Part of the **Local AI Suite**.
 

{setspec-0.3.0 → setspec-0.5.0}/README.md

@@ -2,18 +2,29 @@
 
 Every versioned data contract that crosses an application boundary: benchmark results, capability evidence, event/error envelopes, prompt records.
 
-**Status:** `0.3.0` — Phases 1–2, 3A and 4 complete, and **the v1.0 contracts are frozen.** Eight
-payload types are published at `1.0` — `model.identity`, `machine.profile`, `benchmark.result`,
-`benchmark.run_summary`, `capability.evidence`, `benchmark.evidence_bundle`,
-`benchmark.goal_pack` and `benchmark.calibration_report` — each with generated JSON Schema and at
-least three golden payloads shipped as package data. `setspec.DRAFT_SCHEMAS` is empty, which is
-where the freeze is readable at runtime rather than only stated here; from now on a new optional
-field is a minor bump and anything else is a major, enforced by a snapshot diff in CI.
+**Status:** `0.5.0` — Phases 1–2, 3A, 4, 5 and 6 complete, and **the v1.0 contracts are frozen**,
+with the first additive minor now published on top of that freeze. Eight payload types remain
+frozen at `1.0` — `model.identity`, `machine.profile`, `benchmark.result`,
+`benchmark.run_summary`, `benchmark.evidence_bundle`,
+`benchmark.goal_pack` and `benchmark.calibration_report`, plus `capability.evidence` itself — each
+with generated JSON Schema and at least three golden payloads shipped as package data.
+`setspec.DRAFT_SCHEMAS` is empty, which is where the freeze is readable at runtime rather than only
+stated here; from now on a new optional field is a minor bump and anything else is a major,
+enforced by a snapshot diff in CI.
+
+Phase 6 (the adapter arc's LA0 checkpoint) adds three things without touching any of the above:
+`capability.evidence` gains an additive `1.1` (an optional `adapter` field, absent — and
+byte-identical to `1.0` — on every record with no adapter); `model.adapter_manifest` `1.0`
+publishes the operator-reviewed record behind one adapter; and `governance.egress_decision` `1.0`
+is the package's first payload under a root other than `benchmark`/`capability`/`machine`/`model`,
+carrying a recorded egress verdict for a reader that has SpotCheck installed or not.
 
 The [schema catalogue](docs/schemas.md) lists every payload type, its artifacts, and the
-cross-field rules the JSON Schema cannot express. Event and error envelopes (Phase 3) and prompt
-records (Phase 5) are not yet written and are therefore not part of the freeze. See the
-[development plan](docs/packages/setspec/development-plan.md) for what each phase adds.
+cross-field rules the JSON Schema cannot express. Event and error envelopes (Phase 3) are not yet
+written and are therefore not part of the freeze. Prompt records (`setspec.prompts`, Phase 5,
+added in 0.4.0) are shipped: prompt packs with their three content hashes and sandboxed
+rendering; they carry their own record schema version rather than joining the frozen payload types.
+See the [development plan](docs/packages/setspec/development-plan.md) for what each phase adds.
 
 Part of the **Local AI Suite**.
 

{setspec-0.3.0 → setspec-0.5.0}/docs/packages/setspec/development-plan.md

@@ -2,7 +2,7 @@
 
 **Sequence position:** second component. Depends on BaseAiCore Phase 4.
 **Target:** `setspec 0.3.0` by the end of Phase 4; `0.4.0` adds `setspec.prompts` during LoadCoach P4
-(ADR-0028).
+([ADR-0028](../../adr/0028-prompt-pack-granularity.md)).
 
 Note on ordering: SetSpec's *benchmark* payloads cannot be finalized before FreeWeight knows what a
 result contains. This plan therefore ships the envelope and negotiation machinery first (Phase 1),
@@ -20,7 +20,7 @@ correctly when its major version is unsupported — demonstrated with a trivial
 **Prerequisites:** `baseaicore>=0.4,<0.5`.
 
 **Work**
-* Repository skeleton (as per Packaging Standards).
+* Repository skeleton (as per [Packaging Standards](../../standards/packaging-and-release-standards.md)).
 * `envelope.py`: `SchemaEnvelope`, `GeneratorInfo`, `SchemaVersion`, `SUPPORTED_SCHEMAS`,
   `load_envelope`, `dump_envelope`, `SchemaVersionUnsupported`.
 * `serialization.py`: canonical JSON dump, `Unsupported` codec, RFC 3339 codec, depth/size guards.
@@ -28,7 +28,7 @@ correctly when its major version is unsupported — demonstrated with a trivial
   `PreservingPayload` (`extra="allow"`, for inbound), plus the generator that produces an `Out` and an
   `In` class from one payload definition. The round-trip contract is asserted **per class**: an `In`
   model preserves unknown keys through load → dump, an `Out` model rejects them
-  (ADR-0009 rule 4).
+  ([ADR-0009 rule 4](../../adr/0009-setspec-schema-strategy.md)).
 * `MetricValue` model (value | `"unsupported"`, unit, aggregation, `higher_is_better`, sample count,
   dispersion).
 
@@ -72,7 +72,7 @@ fields.
   (model identity, runtime profile, machine, suite, dataset hashes, prompt pack, effective
   parameters, reproducibility fingerprint).
 * `capability/v1.py`: `CapabilityEvidence` with the full normative field set from
-  ADR-0022 §1 — including `measured_at`
+  [ADR-0022 §1](../../adr/0022-capability-evidence-record-contract.md) — including `measured_at`
   **and** `computed_at` as distinct fields, `vocabulary_version`, `dataset_hashes` and
   `prompt_subset_hashes` — and `EvidenceBundle` with its `complete` flag.
 * `machine/v1.py`: `MachineProfilePayload`; `model/v1.py`: `ModelIdentityPayload`.
@@ -90,7 +90,7 @@ tests/unit/test_vocabulary.py
 **Tests**
 * Round-trip for every model with all-optional and all-populated variants.
 * Provenance completeness: a result missing any required provenance field is rejected, with the field
-  named (Machine Identity §6).
+  named ([Machine Identity §6](../../architecture/machine-identity-and-reproducibility.md)).
 * Score/confidence range validation; negative sample counts rejected.
 * A `CapabilityEvidence` missing `measured_at`, `policy_version` or `vocabulary_version` is rejected
   with the field named; `measured_at` later than `computed_at` is rejected as incoherent.
@@ -121,7 +121,7 @@ constrained models that accept results with missing provenance.
 * `event/v1.py`: the event **payload** (`event_id`, `sequence`, `type`, `entity`, `timestamp`,
   `message`, `progress`, `data`), carried inside the standard envelope whose `generator` identifies
   the producing application — so the payload has no separate `source` field
-  (ADR-0025 §3). Event-type naming enforced by validation.
+  ([ADR-0025 §3](../../adr/0025-envelope-boundaries.md)). Event-type naming enforced by validation.
 * `error/v1.py`: `ErrorEnvelope` (`code`, `message`, `details`, `request_id`, `timestamp`) — the
   object inside `{"error": {…}}`, transported **unwrapped**; a test asserts it is never emitted inside
   a SetSpec envelope.
@@ -139,11 +139,11 @@ tests/unit/{test_events,test_errors}.py
 * Error envelope: `code` is `SCREAMING_SNAKE_CASE`; `details` never contains a secret-shaped key
   (asserted by a redaction test).
 * Serialization matches the examples in
-  API Standards §4 and §8 exactly.
+  [API Standards §4 and §8](../../standards/api-and-contract-standards.md) exactly.
 
 **Acceptance criteria**
-1. The documented example payloads in API Standards §4 and §8
-   and Observability §4.1 validate against these models
+1. The documented example payloads in [API Standards §4 and §8](../../standards/api-and-contract-standards.md)
+   and [Observability §4.1](../../standards/observability-standards.md) validate against these models
    verbatim — the check that keeps the three documents from drifting into three wire formats again.
 2. A secret-shaped key in `details` fails the test suite.
 
@@ -161,14 +161,14 @@ per application and testing the registry.
 the "where do user-defined capabilities live" question permanently.
 
 **Prerequisites:** P2. Independent of P3.
-**Driven by:** ADR-0031,
-ADR-0032.
+**Driven by:** [ADR-0031](../../adr/0031-user-defined-goal-benchmarks.md),
+[ADR-0032](../../adr/0032-judge-validity-and-user-capability-namespace.md).
 **Ships in `setspec 0.3.0`** alongside Phase 4 — no separate release. FreeWeight already pins
 `setspec>=0.3,<0.4` and its P11 already requires SetSpec P4, so the existing prerequisite chain
 delivers vocabulary 1.1 before the M3 contract freeze without any change to either pin. The
 package version is **not** bumped when this phase lands: the work accumulates under
 `## [Unreleased]` and `CAPABILITY_VOCABULARY_VERSION` moves on its own axis
-(Packaging Standards §3.1 — distribution,
+([Packaging Standards §3.1](../../standards/packaging-and-release-standards.md) — distribution,
 HTTP API and schema versions are independent, and the vocabulary is a fourth).
 
 **Note for the 0.3.0 release.** This phase narrows forward-compatibility leniency: a payload
@@ -187,7 +187,7 @@ appear in the changelog rather than passing as an implementation detail.
 * `setspec.goal.v1`: `benchmark.goal_pack` and `benchmark.calibration_report`, registered in
   `SUPPORTED_SCHEMAS` and listed in `DRAFT_SCHEMAS`.
 * The goal-sourced field group on `capability.evidence`, every field optional, with the coherence
-  validators from ADR-0032 §5.
+  validators from [ADR-0032 §5](../../adr/0032-judge-validity-and-user-capability-namespace.md).
 
 **Tests**
 * `user.anything_at_all` validates; bare `user` is refused with the reserved roots named.
@@ -258,7 +258,7 @@ serialization; documented and enforced version rules.
 **Deferred:** `routing.decision` export payload; compression; generated non-Python types.
 **Not created:** `production.feedback` — `POST /jobs/{id}/feedback` is an ordinary body of LoadCoach's
 own `/api/v1`, versioned by its path and contracted through the committed OpenAPI snapshot
-(ADR-0025 §5). Recorded as a deliberate rejection.
+([ADR-0025 §5](../../adr/0025-envelope-boundaries.md)). Recorded as a deliberate rejection.
 
 ---
 
@@ -289,5 +289,139 @@ needing the same.
 2. FreeWeight P12 adopts it with no hash change.
 
 **Known risks:** Jinja2 entering SetSpec's dependency set. Accepted in
-ADR-0028; the alternative was three implementations of a
+[ADR-0028](../../adr/0028-prompt-pack-granularity.md); the alternative was three implementations of a
 determinism contract.
+
+---
+
+## Phase 6 — The adapter axis's contracts (LA0, joint with PromptCadence Phase 0)
+
+**Goal:** the adapter arc has a wire form before any component serves, routes on, or benchmarks an
+adapter — contracts precede consumers, the standing rule the adapter roadmap states outright for
+LA0. A `setspec`-only reader can validate a manifest and an adapter-bearing evidence record, and
+today's evidence records are provably unmoved.
+
+**Prerequisites:** Phase 4 (the `1.0` freeze this phase's additive minor builds on); `baseaicore
+0.4.1` published, carrying `AdapterIdentity`, `DataClassification` and `normalize_digest`
+([ADR-0058](../../adr/0058-the-execution-subject-gains-an-adapter-axis.md)).
+
+**Work**
+* `capability.evidence` `1.1`: one optional field, `adapter: AdapterIdentityFields | None`, on a
+  **new sibling class** (`CapabilityEvidenceV1_1Fields`) rather than an edit to the frozen
+  `CapabilityEvidenceFields` — the latter is nested by reference inside `EvidenceBundleFields`, so
+  editing it in place would have silently moved `benchmark.evidence_bundle`'s own committed `1.0`
+  schema. `benchmark.evidence_bundle` is untouched by this phase; it keeps nesting the `1.0` shape,
+  and gaining the adapter field there is FreeWeight 1.1's work (LA3), not LA0's. A
+  `@model_serializer` drops `adapter` from the dump entirely when absent, so a non-adapter record
+  written through the `1.1` model is byte-identical to what `1.0` writes — not merely
+  structurally compatible, literally the same bytes.
+* `AdapterIdentityFields` (`setspec.model.v1`): the nested exchange form of
+  `baseaicore.AdapterIdentity` — `name`, `artifact_digest`, optional `source_digest`,
+  `canonical_suffix` (materialized and checked, like `model.identity`'s `canonical_id`).
+* `model.adapter_manifest` `1.0` (`setspec.model.v1`): `AdapterManifestFields` per
+  [ADR-0061](../../adr/0061-the-adapter-registry-is-a-directory-and-a-manifest.md) rule 1 —
+  `name`, `artifact_file`, `artifact_sha256`, optional `source_sha256`, `base`
+  (`AdapterManifestBaseFields`: provider model name, optional artifact digest, checked identity
+  confidence), `declared_capabilities` (validated strictly against the current vocabulary, no
+  forward-compatibility exception), `data_classification` (**required, no schema default** —
+  [ADR-0065](../../adr/0065-an-adapter-is-classified-and-local-only.md) rule 1), `format`
+  (fixed `"gguf"`), `created_at`, `notes`. `name`/`artifact_sha256`/`source_sha256` are validated
+  by reconstructing a `baseaicore.AdapterIdentity`, reusing its name-pattern and
+  digest-normalization rules instead of a second implementation.
+* `governance.egress_decision` `1.0` (new module, `setspec.governance.v1`): SetSpec's fifth owned
+  root, per [ADR-0051](../../adr/0051-plans-stay-internal-and-one-payload-travels.md) §4 —
+  `decision_id`, `request` (`run_id`, `source_ref`, `data_classification`, `target{name, remote,
+  max_data_classification, provider_kind}`, `requested_at`), `verdict`
+  (`approved`/`denied`/`violation`, a local `EgressVerdict` `StrEnum` — SetSpec cannot import
+  SpotCheck, which does not exist as code yet), `reason`, `policy_name`, `policy_version`,
+  `decided_at`. Two nullable fields, both one level down. `target.max_data_classification` carries
+  the fail-closed "remote with no declared ceiling" case
+  ([ADR-0054](../../adr/0054-spotcheck-records-egress-it-does-not-enforce-it.md) rule 3), which
+  must be representable rather than schema-refused. `request.requested_at` mirrors SpotCheck spec
+  §7's own `None` default and exists so that its §11 contract 4 — `from_payload(to_payload(d))`
+  preserves **every** field — can be kept: a value object field with no wire field would make that
+  round trip silently lossy. It is not a second record timestamp; `decided_at` remains the
+  required one, and the two answer different questions (when the caller built the request, when
+  the policy answered it). No cross-field "approved implies a ceiling" validator was added: that is
+  `OrderedClassificationPolicy`'s behaviour, and a caller running a different, legitimate policy
+  must not have its decisions rejected by the wire shape.
+* Register all three in `SUPPORTED_SCHEMAS` (`capability.evidence` → highest known minor `1.1`;
+  the two new schemas → `1.0`) and in `artifacts._REGISTRY`/`PUBLISHED_SCHEMAS`. JSON Schema and
+  ≥ 3 goldens each: `capability.evidence/1.1` (`minimal`, `full` — adapter-bearing, `unsupported`),
+  `model.adapter_manifest/1.0` (`minimal` — name-only base, `full` — digest-verified base,
+  `name_only` — a second name-only example with lineage and multiple declared capabilities),
+  `governance.egress_decision/1.0` (`minimal`, `full`, `denied_no_ceiling`, `violation`).
+
+**Files/subsystems**
+```text
+src/setspec/model/v1.py            # + AdapterIdentityFields, AdapterManifestBaseFields,
+                                    #   AdapterManifestFields, AdapterManifestOut/In
+src/setspec/capability/v1.py       # + CapabilityEvidenceV1_1Fields, …V1_1Out/In
+src/setspec/governance/v1.py       # new module
+src/setspec/envelope.py            # SUPPORTED_SCHEMAS entries
+src/setspec/artifacts.py           # _REGISTRY entries
+src/setspec/schemas/{capability.evidence/1.1,model.adapter_manifest/1.0,
+                      governance.egress_decision/1.0}.json
+src/setspec/goldens/{capability.evidence/1.1,model.adapter_manifest/1.0,
+                      governance.egress_decision/1.0}/*.json
+tests/unit/{test_payloads_capability.py (extended), test_payloads_governance.py (new)}
+tests/contract/test_adapter_axis_i15.py     # the exit condition, spelled out explicitly
+```
+
+**Tests**
+* Round-trip for every new/extended model, including the adapter-absent and adapter-present cases.
+* `test_adapter_axis_i15.py`: every committed `capability.evidence/1.0` golden dumps
+  byte-identically whether validated through the `1.0` model or the `1.1` model; a manifest golden
+  and an adapter-bearing evidence golden validate through `setspec` alone.
+* `AdapterManifestFields`: digest-verified base and name-only base both validate; a missing
+  `data_classification` is refused and names the field; a bare reserved capability root is
+  refused; a malformed name or digest is refused via the underlying `AdapterIdentity` check.
+* `GovernanceEgressDecisionFields`: all three verdicts validate; a remote target with no declared
+  ceiling validates (the fail-closed case is representable); an unknown verdict is refused;
+  `request.requested_at` may be omitted, may be null, normalizes to UTC, refuses a naive datetime,
+  and survives the canonical round trip — the last one is the assertion that justifies the field
+  existing at all (SpotCheck spec §11 contract 4), and `decided_at` stays required beside it.
+* Updated cross-cutting contract tests: the schema-snapshot suite's "everything is frozen at 1.0"
+  assertion is split into "no major has ever moved" (permanent) and "every pre-Phase-6 schema is
+  still exactly 1.0" (an explicit, named exception for `capability.evidence`); the
+  minimal-vs-full golden-size check compares serialized bytes rather than top-level key count,
+  since `governance.egress_decision` has no optional top-level field for "minimal" to omit.
+
+**Acceptance criteria**
+1. I15 (adapter-roadmap §7): a `setspec`-only reader validates the manifest and adapter-evidence
+   goldens, and today's evidence records round-trip byte-identically — proven by a dedicated test
+   over the *existing* committed `1.0` goldens, not by argument.
+2. `capability.evidence/1.0.json` and every `benchmark.evidence_bundle` artifact are unchanged
+   (modulo the unrelated `baseaicore 0.4.1` docstring refresh described below).
+3. Every §20 criterion in the [spec](spec.md) continues to hold, including for the two new schemas.
+4. Full gate green: `ruff format --check`, `ruff check`, `mypy --strict`, `lint-imports`,
+   `pytest -m "not live and not performance"`, coverage ≥ 95 %.
+
+**Known risks:** a dependency-version bump rippling into a frozen schema's committed snapshot
+through no fault of this phase's own field changes — realized during this phase, not merely
+anticipated: `baseaicore 0.4.1` changed two enum docstrings
+(`IdentityConfidence`, `ModelCapabilityFlag`), and pydantic embeds an enum's docstring as its JSON
+Schema `description`. Five already-frozen snapshots
+(`model.identity`, `benchmark.result`, `benchmark.run_summary`, `capability.evidence/1.0`,
+`benchmark.evidence_bundle`) therefore needed regenerating — confirmed, before committing, to be
+identical once `description` fields are stripped from the comparison, i.e. no property, type or
+required-field moved. This is not a payload shape change and not a version bump trigger; it is
+recorded here because "the committed snapshot didn't match the model" is exactly the failure this
+phase's own machinery is built to catch, and the reason mattered enough to state rather than to
+silently regenerate past.
+**Likely failure modes:** editing `CapabilityEvidenceFields` in place instead of subclassing it
+(silently moves `benchmark.evidence_bundle`'s frozen schema); a schema default on
+`data_classification` (reintroduces the fail-open gap ADR-0065 rule 1 closes); validating
+`declared_capabilities` with the forward-compatibility exception (the manifest carries no
+`vocabulary_version` to justify it); a cross-field "approved requires a ceiling" validator on
+`governance.egress_decision` (rejects a legitimate document from a caller's own, non-shipped
+policy — SetSpec carries the shape, not SpotCheck's opinion of it).
+**Gold standards:** additive means byte-identical where nothing changed, not merely
+schema-compatible; a payload's shape says only what every legitimate producer could write, never
+one policy's opinion of what a valid decision looks like.
+**Deferred:** `benchmark.evidence_bundle` gaining the adapter field — its own minor, by the
+same sibling-class mechanism ([ADR-0068](../../adr/0068-a-post-freeze-minor-is-a-sibling-class.md)
+rule 5), scheduled as **Phase 7 / `0.6.0`** (row B5 of
+[outstanding-work §1](../../roadmap/outstanding-work.md)) and required before FreeWeight 1.1 can
+export adapter evidence bundled; SpotCheck
+itself, which this phase publishes the shape for but does not implement.

{setspec-0.3.0 → setspec-0.5.0}/docs/packages/setspec/spec.md

@@ -1,7 +1,7 @@
 # SetSpec — Specification
 
 **Type:** Python package · **Import/distribution name:** `setspec` · **Layer:** 2 (contract package)
-**Status:** Specified, not implemented. **Decision record:** ADR-0009.
+**Status:** Specified, not implemented. **Decision record:** [ADR-0009](../../adr/0009-setspec-schema-strategy.md).
 
 ---
 
@@ -48,7 +48,7 @@ applications can exchange data without sharing code or a database.
 
 `baseaicore`, `pydantic>=2.9,<3`, `jinja2>=3.1,<4`. Nothing else.
 
-Jinja2 arrives with `setspec.prompts` (ADR-0028): prompt
+Jinja2 arrives with `setspec.prompts` ([ADR-0028](../../adr/0028-prompt-pack-granularity.md)): prompt
 records are versioned, hash-bearing documents whose hashes appear in cross-application evidence, so
 they belong with the other contracts rather than being implemented three times. Consumers that want
 schemas without a template engine are served by making it an extra if that need ever appears; today
@@ -99,6 +99,11 @@ CapabilityEvidence       # normative field set in ADR-0022: identity triple + ca
                          #   measurement), goal_hash, goal_pack_version, score_method_mix,
                          #   judge_set, calibration, uncalibrated (refused as True: the gate
                          #   withholds the record rather than discounting it)
+                         # `1.1` (ADR-0058, Phase 6) adds one further optional field on a sibling
+                         #   class, CapabilityEvidenceV1_1 (…V1_1Out/…V1_1In): adapter, the
+                         #   optional adapter axis (AdapterIdentity below), absent — and
+                         #   byte-identical to `1.0` — on a bare-base record. The bare
+                         #   CapabilityEvidence name keeps meaning `1.0`.
 GoalPack                 # benchmark.goal_pack — a user-authored goal, portable and hash-pinned
                          # (ADR-0031 §6): slug, goal_hash, criteria with their ladder rung and
                          # weight, tasks, judge_set. The author's grades do NOT travel with it.
@@ -109,6 +114,21 @@ PromptRecord             # the prompt record schema (ADR-0028)
 PromptManifest           # pack manifest, prompt_subset_hash helper
 MachineProfilePayload    # exchange form of baseaicore.MachineProfile
 ModelIdentityPayload     # exchange form of baseaicore.ModelIdentity + descriptor snapshot
+AdapterIdentity          # model.identity's adapter-axis sibling (ADR-0058): the nested exchange
+                         # form of baseaicore.AdapterIdentity — name, artifact_digest,
+                         # source_digest, canonical_suffix (materialized and checked, like
+                         # ModelIdentity's canonical_id). Embedded on CapabilityEvidence `1.1`.
+AdapterManifest          # model.adapter_manifest (ADR-0061 rule 1, Phase 6): name, artifact_file,
+                         # artifact_sha256, source_sha256, base (provider model name + optional
+                         # artifact digest, at digest-or-name_only confidence),
+                         # declared_capabilities, data_classification (required, no default —
+                         # ADR-0065 rule 1), format (fixed "gguf"), created_at, notes
+GovernanceEgressDecision # governance.egress_decision (ADR-0051 §4, ADR-0054, Phase 6): decision_id,
+                         # request (run_id, source_ref, data_classification, target{name, remote,
+                         # max_data_classification, provider_kind}, requested_at), verdict
+                         # (approved | denied | violation), reason, policy_name, policy_version,
+                         # decided_at. SetSpec's first payload outside the
+                         # benchmark/capability/machine/model roots.
 EventEnvelope            # SSE and job/run event payloads
 ErrorEnvelope            # the object inside {"error": {…}} — a shape, transported UNWRAPPED
                          # (ADR-0025 §4); never itself put in a SetSpec envelope
@@ -166,13 +186,28 @@ Owns the **schemas**, not the data. It never persists anything.
 7a. A prompt record's `sha256`, a rendering's `rendered_sha256` and a `prompt_subset_hash` are
    byte-stable across platforms, Python versions and installed `setspec` versions within a major —
    they appear in evidence that another application reads, so they are contract-grade, golden-tested
-   determinism (ADR-0028 §3).
+   determinism ([ADR-0028 §3](../../adr/0028-prompt-pack-granularity.md)).
 8. The capability vocabulary is versioned: additions are minor, removals/redefinitions are major.
    At **1.1** the reserved root `user` was added, whose specializations (`user.<slug>`) carry
    FreeWeight's user-authored goal evidence. It is the only root a user's own measurement ever
    needs: the existing open-ended specialization rule accepts every future goal without a
    further vocabulary change, and no shipped benchmark maps onto it
-   (ADR-0032 §1).
+   ([ADR-0032 §1](../../adr/0032-judge-validity-and-user-capability-namespace.md)).
+9. An additive minor on an **already-published** payload is byte-identical on every document that
+   does not use the new field, proved by golden — not merely structurally compatible. Since
+   [Phase 4](development-plan.md)'s freeze, this is implemented as a sibling field-definition
+   class in the same module (`CapabilityEvidenceV1_1Fields`, subclassing the untouched
+   `CapabilityEvidenceFields`), never as an edit to the published class in place: a definition
+   nested by reference inside another payload (`capability.evidence` inside
+   `benchmark.evidence_bundle`) must not have its shape move when the *other* schema is untouched.
+   Where the new field's own default is not itself a wire value the old version could produce
+   (`None` meaning "absent," not "present and null"), the model suppresses it from the dump rather
+   than emitting it — first exercised at `capability.evidence` `1.1` (ADR-0058). The mechanism and
+   its naming rule are [ADR-0068](../../adr/0068-a-post-freeze-minor-is-a-sibling-class.md): the
+   bare `CapabilityEvidenceOut`/`In` keep meaning `1.0` permanently, and adopting a minor is an
+   explicit import of the version-qualified name, never something a dependency upgrade delivers.
+   Carrying a nested payload's new minor into the payload that nests it is that outer payload's
+   own minor, versioned separately (rule 5).
 
 ## 12. Configuration
 
@@ -246,7 +281,19 @@ Coverage floor: **95 %**.
 * A schema change without a version bump fails CI (snapshot diff).
 * Coexisting majors live in versioned modules (`setspec.benchmark.v1`, `.v2`) and both are exported
   for at least one minor release of every consumer.
+* Coexisting **minors** of an already-published payload live as sibling classes in the *same*
+  module (`CapabilityEvidenceFields` for `1.0`, `CapabilityEvidenceV1_1Fields` for `1.1`), the
+  older one left untouched, and the bare exported name keeps the version it was frozen at
+  ([ADR-0068](../../adr/0068-a-post-freeze-minor-is-a-sibling-class.md)). First exercised at
+  [Phase 6](development-plan.md): `capability.evidence` went from a single published version to two
+  (`1.0` and `1.1`) without either's committed JSON Schema or goldens moving.
 * The schema compatibility job validates every published version against its goldens on every CI run.
+* A dependency version bump can change a generated schema's `description` text without changing any
+  payload's shape, when that text is drawn from the dependency's own docstrings (pydantic embeds an
+  enum's `__doc__` in its JSON Schema). This is not a schema version bump trigger — the committed
+  snapshot is still regenerated and re-committed, and the change is verified structurally identical
+  (same properties, types and required fields) before it is. Observed at Phase 6 against
+  `baseaicore 0.4.1`.
 
 ## 20. Acceptance criteria
 
@@ -264,7 +311,7 @@ Coverage floor: **95 %**.
 
 * ~~`production.feedback` payload~~ — **not created.** `POST /jobs/{id}/feedback` is an ordinary body
   of LoadCoach's own `/api/v1`, versioned by its path and contracted through the committed OpenAPI
-  snapshot (ADR-0025 §5). Recorded as a deliberate rejection
+  snapshot ([ADR-0025 §5](../../adr/0025-envelope-boundaries.md)). Recorded as a deliberate rejection
   rather than an oversight.
 * `routing.decision` export payload for sharing routing explanations between tools.
 * `benchmark.suite_manifest` as a shareable payload so suites can be exchanged.