diff --git a/README.md b/README.md index 0544b53..e87cad3 100644 --- a/README.md +++ b/README.md @@ -12,24 +12,14 @@ Commercial CommandLayer flows may reference payment proof or settlement artifact See the x402 protocol specification for the canonical definition: `https://docs.x402.org/`. -## Authority Model +## Release authority at a glance -- **Current release-candidate line:** `v1.1.0` -- **Canonical source of truth:** root artifacts in this repository for the `v1.1.0` line (`agents/`, `schemas/`, `meta/`, `.well-known/`, `checksums.txt`), pending release validation and external binding confirmation +- **Current line:** `v1.1.0` +- **Canonical current-line surfaces:** root `agents/v1.1.0/`, `schemas/v1.1.0/`, `meta/`, `.well-known/`, and `checksums.txt` - **Canonical registry index:** `meta/manifest.json` -- **Current discovery pointer:** `.well-known/agent.json` -- **Immutable versioned descriptor:** `.well-known/agent-cards-v1.1.0.json` -- **`dist-pin/` role:** committed derivative current-line bundle generated from the root canonical artifacts for pinning/repinning; it is reproducible from the repository root and not a second source of truth -- **Legacy line:** `v1.0.0` is retained for archival compatibility only. It is superseded by `v1.1.0` and is not the primary release line. - -## Quick verification - -- **Current Agent Cards line:** `v1.1.0` -- **Current Commons contract line:** `v1.1.0` -- **Current Commercial contract line:** `v1.1.0` -- **Legacy archival compatibility line:** `v1.0.0` - -See `SPEC.md` for the current card contract and `CHANGELOG.md` for line-to-line migration notes. +- **Derivative current-line bundle:** `dist-pin/agent-cards/v1.1.0/` is a committed reproducible copy of the root release surfaces for pinning/repinning; it is not authoritative +- **Discovery-only surfaces:** `.well-known/agent.json` and `.well-known/agent-cards-v1.1.0.json` point reviewers to the registry metadata; they do not replace the manifest or cards +- **Current authority model:** `v1.1.0` is the only current line in this repository. `v1.0.0` remains preserved for archival compatibility only and must not be treated as the current release ## Minimalism policy for v1.1.0 cards @@ -44,7 +34,7 @@ A current-line card is intentionally narrow. It exists to publish canonical bind v1.1.0 cards intentionally omit descriptive and editorial metadata such as display copy, capabilities summaries, tags, and extra links. If a detail is owned by the Commons or Commercial schema contract, the card links to that contract instead of restating it. -`v1.1.0` is the current release-candidate line. The repository's default validation path, derivative bundle, discovery descriptors, and checksum coverage are centered on `v1.1.0`, but the line must not be treated as fully published until `validate:release` and external bindings are confirmed. `v1.0.0` remains in-tree as an archival compatibility line only. +`v1.1.0` is the current release-candidate line. The repository centers validation, checksums, discovery descriptors, and the derivative dist-pin bundle on this line. The repository does **not** claim that publication is complete merely because those files exist; publication claims require successful release validation and external bindings where applicable. `v1.0.0` remains in-tree only as archival compatibility material. ## Design rule for v1.1.0 @@ -54,9 +44,9 @@ Agent Cards v1.1.0 is intentionally flat: - current schemas live under `schemas/v1.1.0/` - current cards use `schemas/v1.1.0/agent.card.schema.json` - current discovery files use `schemas/v1.1.0/agent.descriptor.schema.json` -- current cards bind **directly** to the intended Commons / Commercial schema URLs for release validation -- current cards bind **directly** to `commandlayer.org` mirror URLs -- current v1.1.0 uses **no `_shared`** +- current cards bind directly to the tagged Commons / Commercial schema source URLs +- current cards bind directly to the public `commandlayer.org` schema mirrors +- current v1.1.0 uses no `_shared` ## How card bindings work @@ -71,8 +61,26 @@ For `v1.1.0`: `https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons//.request.schema.json` +`https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons//.receipt.schema.json` + ### Commons mirror pattern +`https://commandlayer.org/schemas/v1.1.0/commons//.request.schema.json` + +`https://commandlayer.org/schemas/v1.1.0/commons//.receipt.schema.json` + +### Commercial source pattern + +`https://raw.githubusercontent.com/commandlayer/protocol-commercial/refs/tags/v1.1.0/schemas/v1.1.0/commercial//.request.schema.json` + +`https://raw.githubusercontent.com/commandlayer/protocol-commercial/refs/tags/v1.1.0/schemas/v1.1.0/commercial//.receipt.schema.json` + +### Commercial mirror pattern + +`https://commandlayer.org/schemas/v1.1.0/commercial//.request.schema.json` + +`https://commandlayer.org/schemas/v1.1.0/commercial//.receipt.schema.json` + ## Validation Run standard validation: @@ -85,11 +93,11 @@ Run release-level validation (URLs + bundle integrity): ```bash npm run validate:release -# After mirrors are live: +# After mirrors are expected to be live: npm run validate:release -- --require-mirrors ``` -`validate` checks local structure and checksums; `validate:release` adds external URL resolution and derivative-bundle reproducibility before publication claims should be made. +`validate` checks local structure and checksums. `validate:release` adds external URL resolution and derivative-bundle reproducibility. Until those checks pass, the repository should be read as a prepared current line rather than as proof that every external publication surface is already live. That trust path is the intended clean-clone review flow: @@ -97,17 +105,16 @@ That trust path is the intended clean-clone review flow: 2. `meta/manifest.json` is the authoritative registry index for the current line. 3. `agents/v1.1.0/` contains the canonical current cards. 4. `.well-known/` exposes discovery descriptors that point back to the manifest and tier registries. -5. `agents/v1.0.0/` is preserved only as archival legacy material. -6. `dist-pin/agent-cards/v1.1.0/` is the committed reproducible derivative bundle derived from the canonical root files and reproducible from the repository root. +5. `dist-pin/agent-cards/v1.1.0/` is the committed reproducible derivative bundle derived from the canonical root files. +6. `agents/v1.0.0/`, `schemas/v1.0.0/`, and `dist-pin/agent-cards/v1.0.0/` are archival-only legacy material. ## Authority model -- **Canonical source of truth:** root `agents/v1.1.0/`, `meta/`, `.well-known/`, and `schemas/v1.1.0/` +- **Canonical source of truth:** root `agents/v1.1.0/`, `meta/`, `.well-known/`, `schemas/v1.1.0/`, and `checksums.txt` - **Registry index:** `meta/manifest.json` -- **Discovery surface:** `.well-known/agent.json` and `.well-known/agent-cards-v1.1.0.json` -- **Integrity surface:** root `checksums.txt` -- **Legacy scope:** `agents/v1.0.0/` and `schemas/v1.0.0/` +- **Discovery surfaces:** `.well-known/agent.json` and `.well-known/agent-cards-v1.1.0.json` are pointers only - **Derivative bundle role:** `dist-pin/agent-cards/v1.1.0/` is committed, derivative, reproducible from the repository root, and never authoritative +- **Legacy scope:** `agents/v1.0.0/`, `schemas/v1.0.0/`, and `dist-pin/agent-cards/v1.0.0/` are archival compatibility surfaces only ```text agent-cards/ @@ -168,6 +175,8 @@ Routine CI runs `npm run validate` and `npm run validate:release`. Mirror resolu ## Release and publication model +The current release review checks: + - descriptor schema conformance - exact authoritative v1.1.0 card presence - version / path / `$schema` / `$id` alignment diff --git a/SPEC.md b/SPEC.md index fd46e85..080286c 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,8 +1,8 @@ # Specification — CommandLayer Agent Cards -## One-line model +## 1. One-line model -This repo maintains canonical CommandLayer Agent Cards for the current **v1.1.0** release-candidate line. Cards are minimal discovery and binding artifacts, `meta/manifest.json` is the registry index, `.well-known/` exposes discovery, root checksums verify integrity, legacy is archival, and `dist-pin/agent-cards/v1.1.0/` is a derivative current-line bundle reproduced from the canonical root files. +This repo maintains canonical CommandLayer Agent Cards for the current **v1.1.0** release-candidate line. Cards are minimal discovery and binding artifacts, `meta/manifest.json` is the registry index, `.well-known/` exposes discovery pointers, root checksums verify integrity, legacy material is archival only, and `dist-pin/agent-cards/v1.1.0/` is a derivative current-line bundle reproduced from the canonical root files. Agent Cards publish only canonical binding facts: @@ -22,21 +22,25 @@ They do not define semantic meaning, feature behavior, or implementation detail. - Root repository artifacts for `v1.1.0` are authoritative. - `meta/manifest.json` is the canonical registry index. - `.well-known/agent.json` is the current discovery pointer. -- `.well-known/agent-cards-v1.1.0.json` is the immutable versioned descriptor for the canonical line. +- `.well-known/agent-cards-v1.1.0.json` is the immutable versioned descriptor for the current line. +- `.well-known/` files are discovery surfaces only; they do not replace the manifest or card files as authority. - `dist-pin/agent-cards/v1.1.0/` is a derivative current-line bundle for pinning/repinning and is not an independent source of truth. -- `checksums.txt` covers both the authoritative root artifacts and the derived `dist-pin/` bundle so reviewers can verify source and release-candidate surfaces independently. -- `v1.0.0` is superseded and retained only for archival compatibility. Legacy `v1.0.0` references may still rely on IPFS-era addressing and should be read as archival compatibility material, not the current authority path. +- `checksums.txt` covers both the authoritative root artifacts and the derived `dist-pin/` bundle so reviewers can verify source and derivative release surfaces independently. +- `v1.0.0` is superseded and retained only for archival compatibility. Legacy `v1.0.0` references may still rely on IPFS-era addressing and must be read as archival material, not the current authority path. ## 3. Current schema files -These remain for archival compatibility only. They are not the current release line. +The current line uses exactly these repository-owned schema files: -## Card contract for v1.1.0 +- `schemas/v1.1.0/agent.card.schema.json` +- `schemas/v1.1.0/agent.descriptor.schema.json` -Every canonical v1.1.0 card MUST: +Legacy schema files under `schemas/v1.0.0/` remain in-tree only to preserve the archived `v1.0.0` line. They are not part of the current authority model. ## 4. Required card fields +Every canonical v1.1.0 card MUST satisfy the current schema and include the current-line publication fields. + The v1.1.0 JSON Schema requires 14 top-level fields. That count does not include `$schema` or `$id`, because neither field appears in the schema's top-level `required` array: - `id` diff --git a/checksums.txt b/checksums.txt index 574d5d9..cd3a396 100644 --- a/checksums.txt +++ b/checksums.txt @@ -32,9 +32,9 @@ f45b8bb7f745af38fce9a78c1d3a40d36a558e0c4716f59f8e70e561c89ae4e6 agents/v1.1.0/ 315eedad7b1bd8559efa8d3bdf8567c1af7b241be1c934e2ca1dfd90059d90c8 agents/v1.1.0/commons/summarizeagent.eth.json 2320ed25bb42f4dc6fab2249aa0df0665ccc00e29f7663fbd12caf316410feeb dist-pin/agent-cards/v1.0.0/.well-known/agent.json d9fbd6adc82e9b69f72507472a0dead801a245ae97b764a8e1f857ad22a0000c dist-pin/agent-cards/v1.0.0/ARCHIVE_NOTICE.md -9b0015b8d9342111771b77e32086726e434dc346a0b54b695a00dd85b17f504f dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json -d11d58d5c981bd542211f1d9f4109b5f542cf580a46670928b6d0bac0e581bb5 dist-pin/agent-cards/v1.0.0/meta/commons-agent.json -9f04639c33292d1c410805e79632c6d7c0a36ec9826597842c8c3e011e5b7e94 dist-pin/agent-cards/v1.0.0/meta/manifest.json +6cc84041df17bd0c2d43d1a65d3d10e605598638921bc22d47e24c29c612c550 dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json +abca8c9bb27e93c285df17848e1fdd65a3ba7c7002a9bc866799a78b46e7504a dist-pin/agent-cards/v1.0.0/meta/commons-agent.json +da6eb3c33dbc93060ef43194b4f3326fcf401f113e2b4e44b3a8a1e921452664 dist-pin/agent-cards/v1.0.0/meta/manifest.json 0e71d19605b66d56ef412d84e28cd97404d35b0aaa9819cf8f8eafda1679a203 dist-pin/agent-cards/v1.1.0/.well-known/agent-cards-v1.1.0.json 28fbc1f9f2c4640966498935d874d96c4e5d3041356901dc27314e44720d88dc dist-pin/agent-cards/v1.1.0/.well-known/agent.json d12610ea54b31b80758fbc68fcfaf8f20e5588097630f7d04a552bde1be458b1 dist-pin/agent-cards/v1.1.0/agents/v1.1.0/commercial/authorizeagent.eth.json diff --git a/dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json b/dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json index 5b4bc26..f08bd37 100644 --- a/dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json +++ b/dist-pin/agent-cards/v1.0.0/meta/commercial-agent.json @@ -1,7 +1,7 @@ { "id": "x402://commandlayer.eth/commercial-agent/v1", "name": "CommandLayer Commercial Agent", - "description": "Archival registry-level agent descriptor for the superseded CommandLayer Commercial Agent Cards v1.0.0 line.", + "description": "Archival-only registry descriptor for the superseded CommandLayer Commercial Agent Cards v1.0.0 line; preserved for historical compatibility and not authoritative for the current release.", "owner": "commandlayer.eth", "ens": "commandlayer.eth", "version": "1.0.0", @@ -11,7 +11,7 @@ ], "registry": { "card_registry": { - "http": "https://commandlayer.org/agent-cards/meta/manifest.json", + "http": "https://commandlayer.org/agent-cards/dist-pin/agent-cards/v1.0.0/meta/manifest.json", "ipfs": "ipfs://bafybeihwxbbslsmvdnt3qj6qg5e6uj44hokxgs4h6p43jdmjyghvzjz4l4/meta/manifest.json" } }, @@ -24,6 +24,8 @@ "agent_cards_cid": "", "license": "Apache-2.0", "archive_state": "archival_only_unverified_snapshot", + "superseded_by": "v1.1.0 root canonical release surfaces", + "authority_scope": "historical reference only; not part of the current-line trust path", "trust_notice": "integrity_manifest_removed_due_to_incomplete_bundle" } } diff --git a/dist-pin/agent-cards/v1.0.0/meta/commons-agent.json b/dist-pin/agent-cards/v1.0.0/meta/commons-agent.json index 951ea78..4ee0931 100644 --- a/dist-pin/agent-cards/v1.0.0/meta/commons-agent.json +++ b/dist-pin/agent-cards/v1.0.0/meta/commons-agent.json @@ -1,7 +1,7 @@ { "id": "x402://commandlayer.eth/commons-agent/v1", "name": "CommandLayer Commons Agent", - "description": "Archival registry-level agent descriptor for the superseded CommandLayer Commons Agent Cards v1.0.0 line.", + "description": "Archival-only registry descriptor for the superseded CommandLayer Commons Agent Cards v1.0.0 line; preserved for historical compatibility and not authoritative for the current release.", "owner": "commandlayer.eth", "ens": "commandlayer.eth", "version": "1.0.0", @@ -11,7 +11,7 @@ ], "registry": { "card_registry": { - "http": "https://commandlayer.org/agent-cards/meta/manifest.json", + "http": "https://commandlayer.org/agent-cards/dist-pin/agent-cards/v1.0.0/meta/manifest.json", "ipfs": "ipfs://bafybeihwxbbslsmvdnt3qj6qg5e6uj44hokxgs4h6p43jdmjyghvzjz4l4/meta/manifest.json" } }, @@ -24,6 +24,8 @@ "agent_cards_cid": "", "license": "Apache-2.0", "archive_state": "archival_only_unverified_snapshot", + "superseded_by": "v1.1.0 root canonical release surfaces", + "authority_scope": "historical reference only; not part of the current-line trust path", "trust_notice": "integrity_manifest_removed_due_to_incomplete_bundle" } } diff --git a/dist-pin/agent-cards/v1.0.0/meta/manifest.json b/dist-pin/agent-cards/v1.0.0/meta/manifest.json index 43c52e6..6cf7ad9 100644 --- a/dist-pin/agent-cards/v1.0.0/meta/manifest.json +++ b/dist-pin/agent-cards/v1.0.0/meta/manifest.json @@ -1,7 +1,7 @@ { "name": "@commandlayer/agent-cards", "version": "1.0.0", - "description": "Archival manifest snapshot for the superseded CommandLayer Agent Cards v1.0.0 line.", + "description": "Archival-only manifest snapshot for the superseded CommandLayer Agent Cards v1.0.0 line; preserved for historical compatibility and not authoritative for the current release.", "owner": "commandlayer.eth", "contact": "dev@commandlayer.org", "license": "Apache-2.0", @@ -191,6 +191,8 @@ ], "meta": { "archive_state": "archival_only_unverified_snapshot", + "superseded_by": "v1.1.0 root canonical release surfaces", + "authority_scope": "historical reference only; not part of the current-line trust path", "trust_notice": "integrity_manifest_removed_due_to_incomplete_bundle" } }