From abe24ce26844f6b3858a3055b1b4a56373a8a69d Mon Sep 17 00:00:00 2001 From: Claude Bot Date: Mon, 27 Jul 2026 05:51:03 +0800 Subject: [PATCH] docs: point org-contract-map at wasmagent-protocol as canonical SSOT MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The contract map (self-described 'authoritative reference') was last updated 2026-07-21, before wasmagent-protocol was created (2026-07-23) as the canonical source of truth for all cross-repo schemas. It still listed wasmagent-js, agent-trust-infra, symkernel, and bscode as canonical schema owners and had no mention of wasmagent-protocol — so it was actively directing downstream repos to keep local schema copies, causing drift. Rewrite so that: - All cross-repo schemas are owned by wasmagent-protocol (single source), with the versions from its schemas/index.json. - The old 'owner' becomes 'Domain steward' (design ownership), which proposes changes through the protocol contract-change process; the JSON lives only in wasmagent-protocol. - Explicit repo-local schema table (single-consumer, intentionally not centralized). - Coupling rules updated: never copy/fork schema JSON; vendor verbatim + CI drift gate if a package is unavailable (symkernel make sync-schemas as reference); no local-only field extensions. --- docs/org-contract-map.md | 83 +++++++++++++++++++++++++++++++--------- 1 file changed, 64 insertions(+), 19 deletions(-) diff --git a/docs/org-contract-map.md b/docs/org-contract-map.md index 97d605e..2ac020e 100644 --- a/docs/org-contract-map.md +++ b/docs/org-contract-map.md @@ -4,33 +4,78 @@ Canonical ownership of all cross-repository schemas, protocols, and trust artifa Update this file when ownership changes. This is the authoritative reference — individual repo CLAUDE.md files should agree with this table. -Last updated: 2026-07-21 +Last updated: 2026-07-27 + +## Single source of truth + +**All cross-repository schemas are owned by [`WasmAgent/wasmagent-protocol`](https://github.com/WasmAgent/wasmagent-protocol).** +That repository is the canonical source; its `schemas/index.json` is the machine-readable +registry. Schemas are published as two versioned packages that downstream repos depend on: + +- npm: [`@wasmagent/protocol`](https://www.npmjs.com/package/@wasmagent/protocol) +- PyPI: [`wasmagent-protocol`](https://pypi.org/project/wasmagent-protocol/) + +**No repository may define, fork, or vendor a hand-edited copy of a cross-repo schema.** +Consumers depend on the package (or, in a language without one, `$ref` the canonical +`https://wasmagent.dev/schemas/...` URL and pin a version). A repository named in the +"Domain steward" column below owns the *design* of that schema — it proposes changes +through `wasmagent-protocol`'s [contract change process](https://github.com/WasmAgent/wasmagent-protocol/blob/main/docs/CONTRACT-CHANGE-PROCESS.md) — +but the schema JSON itself lives only in `wasmagent-protocol`. ## Schema ownership -| Schema / Artifact | Canonical owner | Version | Producers | Consumers | Compatibility tests | -|---|---|---|---|---|---| -| AEP record (`aep-record/v0.2`) | `wasmagent-js` (`@wasmagent/aep`) | v0.2 | `wasmagent-js`, `wasmagent-proxy`, `wasmagent-train-replay` | `open-agent-audit`, `trace-pipeline`, `bscode` | nightly parity check in `trace-pipeline` | -| AgentBOM specification | `agent-trust-infra` (`specs/agentbom/`) | v0.x | `agent-trust-infra` CLI | `open-agent-audit`, `wasmagent-js` | fixture tests in `agent-trust-infra` | -| MCP Posture specification | `agent-trust-infra` (`specs/mcp-posture/`) | v0.x | `agent-trust-infra` CLI | `open-agent-audit`, `wasmagent-proxy` | fixture tests in `agent-trust-infra` | -| Trust Passport specification + product | `open-agent-audit` (`@openagentaudit/passport`) | v0.1 | `open-agent-audit` | `wasmagent-js`, `agent-trust-infra` (frozen ref) | open-agent-audit issues #52–#54 | -| Audit report (`@openagentaudit/schema`) | `open-agent-audit` | published | `open-agent-audit` | `trace-pipeline`, `bscode` | open-agent-audit CI | -| Admission decision | `trace-pipeline` (`evomerge`) | v0.x | `trace-pipeline` | Golden Path | trace-pipeline CI | -| FAEP record (`faep-schema/v0.1`) | `fresharena` (`packages/faep-schema`) | v0.1 | `fresharena` | `open-agent-audit` (Phase 3 adapter) | fresharena CI | -| `ComplianceEvalRecord` | `wasmagent-js` (`@wasmagent/compliance`) | v0.x | `wasmagent-js`, `bscode` | `trace-pipeline` | nightly parity check | -| `EpochEvidenceBundle` | `wasmagent-train-replay` | v0.x | `wasmagent-train-replay` | `open-agent-audit`, `trace-pipeline` | wasmagent-train-replay CI | -| Criterion / ConstraintIR protocol | `symkernel` (HTTP API) | v1 | `symkernel` | `wasmagent-js` (`CelGoVerifier`, `Z3Verifier`) | symkernel integration test | -| bscode rollout record (`rollout-wire/v1`) | `bscode` | v1 | `bscode` | `trace-pipeline`, `open-agent-audit` | bscode CI | +| Schema / Artifact | Canonical source | Version | Domain steward | Consumers | +|---|---|---|---|---| +| AEP record (`aep-record`) | `wasmagent-protocol` | `aep/v0.2` | `wasmagent-js` | `wasmagent-js`, `wasmagent-proxy`, `trace-pipeline`, `wasmagent-train-replay`, `open-agent-audit` | +| Evidence envelope (`evidence-envelope`) | `wasmagent-protocol` | `aep/v0.1` | `wasmagent-js` | `wasmagent-js`, `wasmagent-proxy`, `trace-pipeline`, `open-agent-audit` | +| `ConstraintIR` (`constraint-ir`) | `wasmagent-protocol` | `compliance/v1` | `symkernel` | `wasmagent-js`, `symkernel`, `trace-pipeline` | +| `ConstraintViolation` (`constraint-violation`) | `wasmagent-protocol` | `compliance/v1` | `symkernel` | `wasmagent-js`, `symkernel`, `trace-pipeline` | +| `RepairTrace` (`repair-trace`) | `wasmagent-protocol` | `compliance/v1` | `wasmagent-js` | `wasmagent-js`, `trace-pipeline` | +| `TaskSpec` (`task-spec`) | `wasmagent-protocol` | `compliance/v1` | `wasmagent-js` | `wasmagent-js`, `trace-pipeline` | +| `ComplianceEvalRecord` (`compliance-eval-record`) | `wasmagent-protocol` | `compliance-eval-record/v1` | `wasmagent-js` | `wasmagent-js`, `trace-pipeline` | +| Rollout wire format (`rollout-wire`) | `wasmagent-protocol` | `rollout-wire/v1` | `wasmagent-js` | `wasmagent-js`, `trace-pipeline` | +| AgentBOM (`agentbom`) | `wasmagent-protocol` | `agentbom/v0.1` | `agent-trust-infra` | `agent-trust-infra`, `open-agent-audit` | +| MCP Posture (`mcp-posture`) | `wasmagent-protocol` | `mcp-posture/v0.1` | `agent-trust-infra` | `agent-trust-infra`, `open-agent-audit` | +| Trust Passport (`trust-passport`) | `wasmagent-protocol` | `trust-passport/v0.1` | `open-agent-audit` | `agent-trust-infra`, `open-agent-audit` | + +### Repo-local schemas (single consumer — intentionally NOT centralized) + +These are owned by a single repository and consumed only there, so per the +`wasmagent-protocol` scope rule ("a schema is admitted only when there is a demonstrated +second consumer") they stay local. Listed here so the boundary is explicit: + +| Schema / Artifact | Owner | Notes | +|---|---|---| +| `EpochEvidenceBundle` | `wasmagent-train-replay` | Wraps AEP records for replay; bundle envelope is replay-private | +| SFT/DPO/PPO training records | `trace-pipeline` | Training-pipeline-private; single owner | +| Audit report (`@openagentaudit/schema`) | `open-agent-audit` | Product schema, published independently | +| FAEP record (`faep-schema/v0.1`) | `fresharena` | Research artifact | +| bench-task (`bench-task.v1`) | `bscode` | Benchmark fixture format | +| Admission decision | `trace-pipeline` | evomerge-private | + +If any of these gains a second org consumer, it must be promoted into +`wasmagent-protocol` before the second consumer ships. ## Deprecation policy - Schema changes that remove or rename fields are **breaking** and require a major version bump. - Producers must support the previous minor version for at least one release cycle. -- Breaking changes must be announced in `.github` release ledger before merging. +- Breaking changes must be announced in the `.github` release ledger before merging. +- All changes flow through `wasmagent-protocol`'s + [contract change process](https://github.com/WasmAgent/wasmagent-protocol/blob/main/docs/CONTRACT-CHANGE-PROCESS.md). ## Cross-repo coupling rules -1. Downstream repos consume schemas via versioned npm/pip packages — never copy schema JSON locally. -2. If a schema is needed in a language without a package, use `$ref` to the canonical source URL. -3. Any new cross-repo schema requires an entry in this table before merge. -4. `agent-trust-infra` `specs/trust-passport/` is **frozen** — use `@openagentaudit/passport` instead. +1. Downstream repos consume schemas via the versioned `@wasmagent/protocol` (npm) or + `wasmagent-protocol` (PyPI) package — **never copy or fork schema JSON locally**. +2. If a schema is needed in a language without a package, `$ref` the canonical + `https://wasmagent.dev/schemas/...` URL and pin the version; if the schema must be + vendored (offline build, Go/Rust), vendor it **verbatim from the published package** + and add a CI drift gate against the pinned package version (see `symkernel`'s + `make sync-schemas` for the reference implementation). +3. A repo may not extend a canonical schema with local-only fields. If a field is needed, + propose it upstream in `wasmagent-protocol`. +4. Any new cross-repo schema requires promotion into `wasmagent-protocol` and an entry in + this table before the second consumer merges. +5. `agent-trust-infra` `specs/trust-passport/` is **frozen** — consume the canonical + `trust-passport` schema from `@wasmagent/protocol` instead.