Clarify discovery roles, make dist-pin authoritative, and split checksum surfaces (Model A)

.gitignore

@@ -3,5 +3,3 @@ npm-debug.log*
 dist
 .DS_Store
 
-# local build/pin staging
-/dist-pin/

.well-known/agent-cards-v1.1.0.json

@@ -1,7 +1,7 @@
 {
   "id": "x402://commandlayer.eth/agent-cards/v1.1.0",
   "name": "CommandLayer Agent Cards Registry Descriptor (v1.1.0)",
-  "description": "Versioned discovery descriptor for CommandLayer Agent Cards v1.1.0.",
+  "description": "Frozen well-known discovery descriptor for the CommandLayer Agent Cards v1.1.0 release line.",
   "owner": "commandlayer.eth",
   "ens": "commandlayer.eth",
   "version": "1.1.0",
@@ -25,6 +25,8 @@
     "current_release": "v1.1.0",
     "legacy_release": "v1.0.0",
     "publish_state": "ready-to-pin",
-    "license": "Apache-2.0"
+    "license": "Apache-2.0",
+    "descriptor_role": "release-snapshot",
+    "frozen_release": "v1.1.0"
   }
 }

.well-known/agent.json

@@ -1,7 +1,7 @@
 {
   "id": "x402://commandlayer.eth/agent-cards/v1.1.0",
   "name": "CommandLayer Agent Cards Registry",
-  "description": "Well-known descriptor for the current CommandLayer Agent Cards v1.1.0 release line.",
+  "description": "Current well-known discovery descriptor for the recommended CommandLayer Agent Cards release line.",
   "owner": "commandlayer.eth",
   "ens": "commandlayer.eth",
   "version": "1.1.0",
@@ -25,6 +25,8 @@
     "current_release": "v1.1.0",
     "legacy_release": "v1.0.0",
     "publish_state": "ready-to-pin",
-    "license": "Apache-2.0"
+    "license": "Apache-2.0",
+    "descriptor_role": "current-pointer",
+    "current_pointer_target": "agent-cards-v1.1.0.json"
   }
 }

README.md

@@ -61,8 +61,9 @@ agent-cards/
 │       └── agent.descriptor.schema.json
 ├── meta/
 ├── .well-known/
-├── dist-pin/agent-cards/v1.1.0/
-└── checksums.txt
+├── dist-pin/
+├── checksums-v1.1.0.txt
+└── checksums-v1.0.0.txt
 ```
 
 ## Example Commons v1.1.0 card
@@ -124,12 +125,29 @@ Validation checks:
 - direct Commons and Commercial source URL patterns
 - direct `commandlayer.org` mirror URL patterns
 - entry URI correctness
-- checksum determinism across cards, schemas, meta, discovery, and dist-pin
+- current release checksum determinism across the canonical v1.1.0 line
+- archival checksum determinism for retained v1.0.0 compatibility assets
+- committed dist-pin bundle mirroring and bundle-local checksum determinism
 
-## Release artifacts
+## Discovery surfaces
+
+- `.well-known/agent.json` — current discovery pointer for the recommended release line
+- `.well-known/agent-cards-v1.1.0.json` — frozen v1.1.0 discovery snapshot
+- The two discovery descriptors are intentionally both present under **Model A: current pointer + versioned snapshot**.
+- Validation enforces that the files are identical except for the current-pointer fields in `agent.json`: `name`, `description`, `meta.descriptor_role`, and `meta.current_pointer_target`.
+- The versioned snapshot keeps the v1.1.0 release facts frozen and carries `meta.descriptor_role=release-snapshot` plus `meta.frozen_release=v1.1.0`.
+
+## Release artifacts and integrity surfaces
 
 - `meta/manifest.json` — authoritative release index
-- `.well-known/agent.json` — current discovery descriptor
-- `.well-known/agent-cards-v1.1.0.json` — versioned descriptor
-- `dist-pin/agent-cards/v1.1.0/` — publish bundle for repinning
-- `checksums.txt` — deterministic artifact digests
+- `checksums-v1.1.0.txt` — canonical checksum surface for the current v1.1.0 release line
+- `checksums-v1.0.0.txt` — archival checksum surface for retained v1.0.0 compatibility assets
+- `dist-pin/agent-cards/v1.1.0/` — committed authoritative publish bundle; it must exactly mirror the canonical v1.1.0 files in this repo
+- `dist-pin/agent-cards/v1.1.0/checksums.txt` — bundle-local checksums for the committed publish bundle
+- `dist-pin/agent-cards/v1.0.0/checksums.txt` — archival bundle-local checksums for the v1.0.0 publish bundle
+
+The clean-clone verification story is now split on purpose:
+
+- verify the current canonical release line with `npm run validate:checksums` or by inspecting `checksums-v1.1.0.txt`
+- verify the committed publish bundle independently with `dist-pin/agent-cards/v1.1.0/checksums.txt`
+- verify archival compatibility assets separately with `checksums-v1.0.0.txt`

checksums-v1.0.0.txt

@@ -0,0 +1,17 @@
+8cbbb8edf6b3ec2e65dc54ce5bdd467a63aaaad1d90bbd251a729b238ef56507  agents/v1.0.0/commercial/authorizeagent.eth.json
+bfad808d0e3b107df59887c9684303b87b4867d9887c9b1a035ca8b33b115cca  agents/v1.0.0/commercial/checkoutagent.eth.json
+0bbd1601794b3d18f63fc331b55888cb083e0f1a37d14c3c79679c237ec0414b  agents/v1.0.0/commercial/purchaseagent.eth.json
+15062e72b528e2f66e58a3d83ea617a4d9e699cb1eb25a0576cbf09f3808425d  agents/v1.0.0/commercial/shipagent.eth.json
+4079b22e3821dbfc141b1c9baaaf1cefb20b4c68af58725aacf8428e05d2e91a  agents/v1.0.0/commercial/verifyagent.eth.json
+2b14d78ad82435da6846e119bc9bf82f5b7661ccef53f4b7c25aaa50411d8812  agents/v1.0.0/commons/analyzeagent.eth.json
+acb40f650362582daedda35fd1dbd78b7d1b6866e26cb3ee8ca090e0d18331e1  agents/v1.0.0/commons/classifyagent.eth.json
+88943a385de72550bbd7454ddc8aabc6b4bc101449b571a1966e9e8c8266040e  agents/v1.0.0/commons/cleanagent.eth.json
+eb866bf8f0561590b823b1b04f4fed405fcae2f95b46f1a779cceb405efae05f  agents/v1.0.0/commons/convertagent.eth.json
+7f45a2abd1f542f37b0aaab639a5e02a15687235ec8704298fe9dfe39f5a5dbf  agents/v1.0.0/commons/describeagent.eth.json
+d8ae6333a4cc804361c0e427f0d82ee2d66b9129686fe85bcd97a3a9f1bf63f4  agents/v1.0.0/commons/explainagent.eth.json
+3035cae9244887cc1451f329d9e20a15232197b39fe003a16a27c04bc10d8ff2  agents/v1.0.0/commons/fetchagent.eth.json
+811465b0a47ee1b954802d97bfff3612e43914ed46c918936d3728a446175ce6  agents/v1.0.0/commons/formatagent.eth.json
+4e66f7a76a302ac2fdcd7a8581c7c4fe6059028f801e2c8d155f513225aec805  agents/v1.0.0/commons/parseagent.eth.json
+dc96aeffb629bec3c102771b8e5d99cd69d6b2bad7065d14b7c7ee2e8fc1eee2  agents/v1.0.0/commons/summarizeagent.eth.json
+ec6b2669daca50f99c9b8e04db7b8010169786788431cd74b68e547441216b8a  schemas/v1.0.0/_shared/agent.card.base.schema.json
+c22100701ae9ebad97cfc1cb468a0369e424a0cdcec2d62968b848ef5d14369c  schemas/v1.0.0/_shared/agent.descriptor.schema.json

checksums-v1.1.0.txt

@@ -0,0 +1,22 @@
+c849b110de7ae1f2519263fa6e366ac9ab5dd6461bb2eb2f48d044e5805340c3  .well-known/agent-cards-v1.1.0.json
+7565a19515cbb98ac272b9077be43378071102e98bdf23d43b6ce28cb5743399  .well-known/agent.json
+9f37939c58430df6efc118ec62e56d758a2c63ff6becc33b72056dff0abd01e4  agents/v1.1.0/commercial/authorizeagent.eth.json
+0c2fb22fe4d5028b3218edfbc6783fa928df09c33cac3e4ae19dd6b4fb3b1d25  agents/v1.1.0/commercial/checkoutagent.eth.json
+b92447ac389a28dd6d7bb9e48b62b4dcfe2d573db9e8e46769ff7f05b70c174c  agents/v1.1.0/commercial/purchaseagent.eth.json
+8845af9bfb06aae06fff06d7926417e532e417faf8b11e8d906b54769f180684  agents/v1.1.0/commercial/shipagent.eth.json
+0d6ee78a0a977601d2544feed5f483d193b2d5e0790417725d1665a0e6859538  agents/v1.1.0/commercial/verifyagent.eth.json
+e1b3893660ea726ff444392df7abb2eada8b7a0e89e3d18fa1da3247e2546ba9  agents/v1.1.0/commons/analyzeagent.eth.json
+66ae37ace0e04714b1965c7661237843dc699e3e2d1f68620cff45f1132fe81f  agents/v1.1.0/commons/classifyagent.eth.json
+1b56892f20d39d4780a49b8f96dd769fa7d2178f9cb04fe3c60f78d726c1889e  agents/v1.1.0/commons/cleanagent.eth.json
+eb575e806ce80fb473d771e667caa96e4e01806345292408882c92de54f2e059  agents/v1.1.0/commons/convertagent.eth.json
+0d25e3b86ca25c333a17a0cc4b9a1e0b5265dbe2bc13d88ab9da220eb5f1b613  agents/v1.1.0/commons/describeagent.eth.json
+6459519e39a9107e4294a8ad5bb46ba091933823145853aba50f38a283fbd167  agents/v1.1.0/commons/explainagent.eth.json
+60288c4c63ceb7936df2dc686b063c0b97f714afac3662f05a9f10da0b6043c4  agents/v1.1.0/commons/fetchagent.eth.json
+2c6a69e8e91d712c09994547a42bfb4043cd5abd14df2ac3f43f4d8837d2e433  agents/v1.1.0/commons/formatagent.eth.json
+7ff9756b5bcc1f989c0f36b76de8d0a8fa2d5287532dfe9717c9622eac5f6c64  agents/v1.1.0/commons/parseagent.eth.json
+1ee1a0b04cbc2488fea75458f34b0b271b7801d8e01533e4ba5dd91f2aa9ae15  agents/v1.1.0/commons/summarizeagent.eth.json
+d4aa942ad535e5e5fd9103bc21dc94f45a69e87df820bf78af2c3b6db583dcca  meta/commercial-agent.json
+56c4da1b3716d804495aa54244f71f995ee4b22438f125c85e6148f1e5c5cf4e  meta/commons-agent.json
+c6ae761d917aac0f7161648002cab2caf84bf7e7084f4b8d3bf35c943409b8f9  meta/manifest.json
+b7b573a464b3ba9f643958b716e72ce9eeb095a7c5b87bf2620eb53e7dc6afb3  schemas/v1.1.0/agent.card.schema.json
+410c3abb4140657426ae8338ee79fbd05632bf82490061773e303782a0370d70  schemas/v1.1.0/agent.descriptor.schema.json

dist-pin/agent-cards/v1.0.0/checksums.txt

@@ -1,21 +1,4 @@
 3204719c980ffc68f7a317a01b9df67ca8655d5314168c6026415e06dcd8b0f8  .well-known/agent.json
-8cbbb8edf6b3ec2e65dc54ce5bdd467a63aaaad1d90bbd251a729b238ef56507  agents/v1.0.0/commercial/authorizeagent.eth.json
-bfad808d0e3b107df59887c9684303b87b4867d9887c9b1a035ca8b33b115cca  agents/v1.0.0/commercial/checkoutagent.eth.json
-0bbd1601794b3d18f63fc331b55888cb083e0f1a37d14c3c79679c237ec0414b  agents/v1.0.0/commercial/purchaseagent.eth.json
-15062e72b528e2f66e58a3d83ea617a4d9e699cb1eb25a0576cbf09f3808425d  agents/v1.0.0/commercial/shipagent.eth.json
-4079b22e3821dbfc141b1c9baaaf1cefb20b4c68af58725aacf8428e05d2e91a  agents/v1.0.0/commercial/verifyagent.eth.json
-2b14d78ad82435da6846e119bc9bf82f5b7661ccef53f4b7c25aaa50411d8812  agents/v1.0.0/commons/analyzeagent.eth.json
-acb40f650362582daedda35fd1dbd78b7d1b6866e26cb3ee8ca090e0d18331e1  agents/v1.0.0/commons/classifyagent.eth.json
-88943a385de72550bbd7454ddc8aabc6b4bc101449b571a1966e9e8c8266040e  agents/v1.0.0/commons/cleanagent.eth.json
-eb866bf8f0561590b823b1b04f4fed405fcae2f95b46f1a779cceb405efae05f  agents/v1.0.0/commons/convertagent.eth.json
-7f45a2abd1f542f37b0aaab639a5e02a15687235ec8704298fe9dfe39f5a5dbf  agents/v1.0.0/commons/describeagent.eth.json
-d8ae6333a4cc804361c0e427f0d82ee2d66b9129686fe85bcd97a3a9f1bf63f4  agents/v1.0.0/commons/explainagent.eth.json
-3035cae9244887cc1451f329d9e20a15232197b39fe003a16a27c04bc10d8ff2  agents/v1.0.0/commons/fetchagent.eth.json
-811465b0a47ee1b954802d97bfff3612e43914ed46c918936d3728a446175ce6  agents/v1.0.0/commons/formatagent.eth.json
-4e66f7a76a302ac2fdcd7a8581c7c4fe6059028f801e2c8d155f513225aec805  agents/v1.0.0/commons/parseagent.eth.json
-dc96aeffb629bec3c102771b8e5d99cd69d6b2bad7065d14b7c7ee2e8fc1eee2  agents/v1.0.0/commons/summarizeagent.eth.json
 d3cde6eef58761fe5b88e3df5cb448002a289735df8f1c164fdc3b74193c61b9  meta/commercial-agent.json
 783178e57e9b754d939d90b9564740b45175fe0d360cfa4191716eb60e466c2e  meta/commons-agent.json
 10c6ca12542dbdb21ccb1816ba7c98704789729e016b8dafe5ee2361f8b0e75c  meta/manifest.json
-ec6b2669daca50f99c9b8e04db7b8010169786788431cd74b68e547441216b8a  schemas/v1.0.0/_shared/agent.card.base.schema.json
-c22100701ae9ebad97cfc1cb468a0369e424a0cdcec2d62968b848ef5d14369c  schemas/v1.0.0/_shared/agent.descriptor.schema.json

dist-pin/agent-cards/v1.1.0/.well-known/agent-cards-v1.1.0.json

@@ -1,7 +1,7 @@
 {
   "id": "x402://commandlayer.eth/agent-cards/v1.1.0",
   "name": "CommandLayer Agent Cards Registry Descriptor (v1.1.0)",
-  "description": "Versioned discovery descriptor for CommandLayer Agent Cards v1.1.0.",
+  "description": "Frozen well-known discovery descriptor for the CommandLayer Agent Cards v1.1.0 release line.",
   "owner": "commandlayer.eth",
   "ens": "commandlayer.eth",
   "version": "1.1.0",
@@ -25,6 +25,8 @@
     "current_release": "v1.1.0",
     "legacy_release": "v1.0.0",
     "publish_state": "ready-to-pin",
-    "license": "Apache-2.0"
+    "license": "Apache-2.0",
+    "descriptor_role": "release-snapshot",
+    "frozen_release": "v1.1.0"
   }
 }

dist-pin/agent-cards/v1.1.0/.well-known/agent.json

@@ -1,7 +1,7 @@
 {
   "id": "x402://commandlayer.eth/agent-cards/v1.1.0",
   "name": "CommandLayer Agent Cards Registry",
-  "description": "Well-known descriptor for the current CommandLayer Agent Cards v1.1.0 release line.",
+  "description": "Current well-known discovery descriptor for the recommended CommandLayer Agent Cards release line.",
   "owner": "commandlayer.eth",
   "ens": "commandlayer.eth",
   "version": "1.1.0",
@@ -25,6 +25,8 @@
     "current_release": "v1.1.0",
     "legacy_release": "v1.0.0",
     "publish_state": "ready-to-pin",
-    "license": "Apache-2.0"
+    "license": "Apache-2.0",
+    "descriptor_role": "current-pointer",
+    "current_pointer_target": "agent-cards-v1.1.0.json"
   }
 }