Standardize Commons v1.1.0: receipt-first contract, remove legacy x402 entry, and make TS tests package-local

DEPLOYMENT_GUIDE.md

@@ -14,7 +14,7 @@ Current release line:
 Before cutting a release:
 - confirm both SDK packages are on the same version,
 - confirm docs reference the same protocol version and receipt model,
-- confirm shared test vectors still represent the current signed receipt truth,
+- confirm shared test vectors still represent the current signed receipt truth and do not reintroduce x402-first positioning,
 - decide whether the release is docs-only or publishable.
 
 ## 2. Local quality gates
@@ -108,8 +108,8 @@ If the public docs site references installation or verification examples, update
 ## 7. CI expectations
 
 CI should stay green for:
-- TypeScript typecheck/build/tests,
+- TypeScript typecheck/build/package-local tests,
 - Python lint/typecheck/tests,
-- cross-SDK runtime fixture checks.
+- optional cross-SDK runtime fixture checks.
 
 Do not publish if any of those lanes are red.

DEVELOPER_EXPERIENCE.md

@@ -23,7 +23,7 @@ This document is for maintainers and advanced integrators. Start with `README.md
 
 The signed payload includes:
 - `status`,
-- `x402` verb metadata,
+- the protocol metadata block at `x402` (Commons verb/version metadata; not a commercial SDK claim),
 - `result` or `error`,
 - `metadata.receipt_id`, and
 - `metadata.proof` with `alg`, `canonical`, `signer_id`, `hash_sha256`, and `signature_b64`.
@@ -84,5 +84,5 @@ When protocol versions change:
 1. update package versions and protocol constants,
 2. update root docs and per-package READMEs,
 3. regenerate or update shared fixtures,
-4. run both SDK test suites plus `runtime/tests`,
+4. run both SDK test suites plus the optional cross-SDK `runtime/tests` lane,
 5. confirm release instructions in `DEPLOYMENT_GUIDE.md` still match reality.

EXAMPLES.md

@@ -1,6 +1,6 @@
 # CommandLayer SDK Examples
 
-Canonical examples for the CommandLayer SDK repo.
+Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story receipt-first: `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object is protocol metadata rather than a commercial SDK surface.
 
 All examples in this file target:
 - Protocol-Commons v1.1.0,
@@ -16,7 +16,6 @@ All examples in this file target:
     "x402": {
       "verb": "summarize",
       "version": "1.1.0",
-      "entry": "x402://summarizeagent.eth/summarize/v1.1.0"
     },
     "result": {
       "summary": "..."

MAINTAINER_GUIDE.md

@@ -1,3 +1,3 @@
 # Maintainer Guide
 
-See `DEVELOPER_EXPERIENCE.md` for maintainer-facing architecture notes and `DEPLOYMENT_GUIDE.md` for release execution details.
+Use `DEVELOPER_EXPERIENCE.md` for maintainer-facing architecture notes and contributor workflow. Use `RELEASE_GUIDE.md` for the release sequence and `DEPLOYMENT_GUIDE.md` for the detailed packaging/publish checklist.

QUICKSTART.md

@@ -83,7 +83,7 @@ Both SDKs return the same shape:
 }
 ```
 
-Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context.
+Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata and is not a commercial feature signal.
 
 ## 4. Verify the receipt
 
@@ -153,4 +153,5 @@ Not claimed as first-class SDK support here:
 - More recipes: `EXAMPLES.md`
 - Package docs: `typescript-sdk/README.md`, `python-sdk/README.md`
 - Maintainer notes: `DEVELOPER_EXPERIENCE.md`
-- Release flow: `DEPLOYMENT_GUIDE.md`
+- Release guide: `RELEASE_GUIDE.md`
+- Deployment checklist: `DEPLOYMENT_GUIDE.md`

README.md

@@ -27,7 +27,7 @@ This repo is aligned to the current CommandLayer v1.1.0 surface:
 - canonical signed receipts as the verification contract payload, and
 - optional `runtime_metadata` as unsigned execution context.
 
-Protocol-Commercial / x402 payment flows are not a first-class SDK surface in this repo today. The SDK is Commons-first; if commercial support expands, it should be added explicitly rather than implied.
+Protocol-Commercial / x402 payment flows are not a first-class SDK surface in this repo today. The retained `receipt.x402` metadata block is part of the Commons protocol schema here; it should not be read as commercial feature coverage.
 
 ## Install
 
@@ -103,7 +103,6 @@ Client methods now return a command response envelope:
     "x402": {
       "verb": "summarize",
       "version": "1.1.0",
-      "entry": "x402://summarizeagent.eth/summarize/v1.1.0"
     },
     "result": {
       "summary": "..."
@@ -129,7 +128,7 @@ Client methods now return a command response envelope:
 
 The canonical signed object is `receipt`. `runtime_metadata` is optional and unsigned. Verification, persistence, and downstream audit should use the canonical `receipt` object.
 
-The SDK still normalizes older blended runtime responses for compatibility, but the repo now documents the v1.1.0 envelope as the single current truth.
+The SDK still normalizes older blended runtime responses for compatibility, but that normalization is legacy-only. The repo documents the v1.1.0 envelope as the single canonical public contract.
 
 ## Verification
 
@@ -175,7 +174,8 @@ The CLI is intended for demos, CI smoke tests, debugging, and reproducing SDK fl
 - Fast onboarding: `QUICKSTART.md`
 - Cookbook examples: `EXAMPLES.md`
 - Maintainer / architecture notes: `DEVELOPER_EXPERIENCE.md`
-- Build, release, and publish flow: `DEPLOYMENT_GUIDE.md`
+- Release guide: `RELEASE_GUIDE.md`
+- Deployment checklist: `DEPLOYMENT_GUIDE.md`
 - Changelog: `CHANGELOG.md`
 - TypeScript package docs: `typescript-sdk/README.md`
 - Python package docs: `python-sdk/README.md`

RELEASE_GUIDE.md

@@ -1,3 +1,9 @@
 # Release Guide
 
-See `DEPLOYMENT_GUIDE.md` for the current build, release, and publish workflow.
+Use this document as the release entrypoint for the SDK repo.
+
+- Release story and quality gates: `DEPLOYMENT_GUIDE.md`
+- Maintainer architecture/context: `DEVELOPER_EXPERIENCE.md`
+- Public changelog for v1.1.0: `CHANGELOG.md`
+
+The repo should present one release story: Protocol-Commons v1.1.0, the canonical `{ receipt, runtime_metadata? }` response envelope, and self-contained package-local tests before any optional cross-SDK validation.

python-sdk/README.md

@@ -8,6 +8,8 @@ The Python package mirrors the TypeScript SDK's protocol model:
 - `runtime_metadata` is optional execution context, and
 - verification can use an explicit Ed25519 key or ENS discovery.
 
+The retained `response["receipt"]["x402"]` block is Commons protocol metadata, not a commercial SDK surface in this repository.
+
 ## Install
 
 ```bash

python-sdk/commandlayer/client.py

@@ -278,7 +278,6 @@ def _build_payload(self, verb: str, body: dict[str, Any]) -> dict[str, Any]:
             "x402": {
                 "verb": verb,
                 "version": COMMONS_VERSION,
-                "entry": f"x402://{verb}agent.eth/{verb}/v{COMMONS_VERSION}",
             },
             "actor": body.get("actor", self.actor),
             **body,

python-sdk/tests/test_verify.py

@@ -27,7 +27,6 @@ def _signed_receipt() -> tuple[dict[str, object], str]:
         "x402": {
             "verb": "summarize",
             "version": "1.1.0",
-            "entry": "x402://summarizeagent.eth/summarize/v1.1.0",
         },
         "metadata": {
             "proof": {

test_vectors/README.md

@@ -1,6 +1,6 @@
 # Test vectors
 
-This directory contains shared receipt fixtures used by both SDKs and the parity check.
+This directory contains shared receipt fixtures used by both SDKs and the parity check. The fixtures model the current Commons v1.1.0 receipt contract: `receipt` is canonical, `runtime_metadata` is unsigned, and the `x402` object is retained only as protocol metadata.
 
 ## Files
 

test_vectors/expected_hash.txt

@@ -1 +1 @@
-915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1
+509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196

test_vectors/public_key_base64.txt

@@ -1 +1 @@
-jgkIXxvTfIC0U08Xp181TaltbLtMbSq/yJ9JRPS8wNE=
+A6EHv/POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg=

test_vectors/receipt_invalid_sig.json

@@ -3,8 +3,7 @@
   "status": "success",
   "x402": {
     "verb": "summarize",
-    "version": "1.1.0",
-    "entry": "x402://parseagent.eth/summarize/v1.1.0"
+    "version": "1.1.0"
   },
   "result": {
     "summary": "fixture"
@@ -14,9 +13,9 @@
       "alg": "ed25519-sha256",
       "canonical": "cl-stable-json-v1",
       "signer_id": "runtime.commandlayer.eth",
-      "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1",
+      "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196",
       "signature_b64": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=="
     },
-    "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1"
+    "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196"
   }
 }

test_vectors/receipt_malformed_pubkey.json

@@ -3,8 +3,7 @@
   "status": "success",
   "x402": {
     "verb": "summarize",
-    "version": "1.1.0",
-    "entry": "x402://parseagent.eth/summarize/v1.1.0"
+    "version": "1.1.0"
   },
   "result": {
     "summary": "fixture"
@@ -14,9 +13,9 @@
       "alg": "ed25519-sha256",
       "canonical": "cl-stable-json-v1",
       "signer_id": "runtime.commandlayer.eth",
-      "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1",
-      "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg=="
+      "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196",
+      "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw=="
     },
-    "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1"
+    "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196"
   }
 }

test_vectors/receipt_valid.json

@@ -3,8 +3,7 @@
   "status": "success",
   "x402": {
     "verb": "summarize",
-    "version": "1.1.0",
-    "entry": "x402://parseagent.eth/summarize/v1.1.0"
+    "version": "1.1.0"
   },
   "result": {
     "summary": "fixture"
@@ -14,9 +13,9 @@
       "alg": "ed25519-sha256",
       "canonical": "cl-stable-json-v1",
       "signer_id": "runtime.commandlayer.eth",
-      "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1",
-      "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg=="
+      "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196",
+      "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw=="
     },
-    "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1"
+    "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196"
   }
 }

test_vectors/receipt_valid_v1.json

@@ -3,8 +3,7 @@
   "status": "success",
   "x402": {
     "verb": "summarize",
-    "version": "1.1.0",
-    "entry": "x402://parseagent.eth/summarize/v1.1.0"
+    "version": "1.1.0"
   },
   "result": {
     "summary": "fixture"
@@ -14,9 +13,9 @@
       "alg": "ed25519-sha256",
       "canonical": "cl-stable-json-v1",
       "signer_id": "runtime.commandlayer.eth",
-      "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1",
-      "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg=="
+      "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196",
+      "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw=="
     },
-    "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1"
+    "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196"
   }
 }

test_vectors/receipt_wrong_kid.json

@@ -3,8 +3,7 @@
   "status": "success",
   "x402": {
     "verb": "summarize",
-    "version": "1.1.0",
-    "entry": "x402://parseagent.eth/summarize/v1.1.0"
+    "version": "1.1.0"
   },
   "result": {
     "summary": "fixture"
@@ -14,9 +13,9 @@
       "alg": "ed25519-sha256",
       "canonical": "cl-stable-json-v1",
       "signer_id": "runtime.commandlayer.eth",
-      "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1",
-      "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg=="
+      "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196",
+      "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw=="
     },
-    "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1"
+    "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196"
   }
 }

typescript-sdk/README.md

@@ -4,8 +4,8 @@ Official TypeScript/JavaScript SDK for CommandLayer Commons v1.1.0.
 
 Use this package to:
 - call CommandLayer Commons verbs,
-- receive a canonical signed receipt,
-- capture optional runtime metadata separately,
+- receive the canonical signed `receipt`,
+- capture optional unsigned `runtime_metadata` separately,
 - verify receipts offline or through ENS, and
 - reproduce calls from the CLI.
 
@@ -72,7 +72,7 @@ Client methods return:
 }
 ```
 
-`verifyReceipt()` accepts the canonical `receipt` object. The SDK also accepts a whole response envelope for legacy compatibility, but new integrations should pass `response.receipt` explicitly.
+`verifyReceipt()` accepts the canonical `receipt` object. The retained `receipt.x402` block is Commons protocol metadata, not a commercial SDK surface. The SDK also accepts a whole response envelope for legacy compatibility, but new integrations should pass `response.receipt` explicitly.
 
 ## Verification modes
 
@@ -111,9 +111,12 @@ commandlayer verify --file receipt.json --public-key "ed25519:BASE64_PUBLIC_KEY"
 
 ## Development
 
+`npm test` is package-local and reproducible from this repo alone. The optional protocol integration lane remains available as `npm run test:integration`.
+
 ```bash
 cd typescript-sdk
 npm ci
 npm run typecheck
 npm test
+npm run test:integration
 ```

typescript-sdk/package.json

@@ -30,7 +30,8 @@
     "prepack": "npm run build",
     "test:cli-smoke": "node scripts/cli-smoke.mjs",
     "test:unit": "npm run build && node scripts/unit-tests.mjs && npm run test:template",
-    "test": "npm run test:unit && npm run test:cli-smoke && node --test ../runtime/tests/*.mjs",
+    "test": "npm run test:unit && npm run test:cli-smoke",
+    "test:integration": "node --test ../runtime/tests/*.mjs",
     "test:template": "node scripts/template-tests.mjs"
   },
   "dependencies": {

typescript-sdk/scripts/unit-tests.mjs

@@ -196,7 +196,7 @@ await assertRejects(
 
 const receipt = {
   status: "success",
-  x402: { verb: "summarize", version: "1.1.0", entry: "x402://summarizeagent.eth/summarize/v1.1.0" },
+  x402: { verb: "summarize", version: "1.1.0" },
   result: { summary: "test" },
   metadata: {
     proof: {

typescript-sdk/src/index.ts

@@ -537,7 +537,7 @@ export class CommandLayerClient {
     this.ensureVerifyConfigIfEnabled();
 
     const payload = {
-      x402: { verb, version: commonsVersion, entry: `x402://${verb}agent.eth/${verb}/v${commonsVersion}` },
+      x402: { verb, version: commonsVersion },
       ...(body.actor ? { actor: body.actor } : { actor: this.actor }),
       ...body
     };