docs: align receipt verb and verification contract language

Author: GsCommand

EXAMPLES.md

@@ -13,6 +13,7 @@ All examples in this file target:
 {
   "receipt": {
     "status": "success",
+    "verb": "summarize",
     "result": {
       "summary": "..."
     },

QUICKSTART.md

@@ -47,6 +47,7 @@ Both SDKs return the same shape:
 {
   "receipt": {
     "status": "success",
+    "verb": "summarize",
     "result": { "summary": "..." },
     "metadata": {
       "proof": {
@@ -86,4 +87,4 @@ verify_receipt(response["receipt"], public_key="ed25519:BASE64_PUBLIC_KEY")
 - Persist `response.receipt`.
 - Treat `response.runtime_metadata` as optional unsigned context.
 - Treat `receipt.metadata.receipt_id` as the receipt hash identifier.
-- Read the verb from `receipt.x402.verb`.
+- Read the verb from `receipt.verb`. Legacy/commercial payloads may expose `receipt.x402.verb` as a fallback.

README.md

@@ -29,11 +29,11 @@ console.log(result.valid);
 
 ## What this repo now treats as canonical
 
-- **Requests**: Commons requests are built around one explicit envelope: top-level `x402.verb`, `x402.version`, `actor`, and the verb body.
+- **Requests**: Commons requests are built with an explicit verb + payload envelope, and receipts surface that canonical verb at top-level `receipt.verb`.
 - **Responses**: the signed artifact is always `response.receipt`.
 - **Unsigned runtime context**: optional execution details live in `response.runtime_metadata`.
-- **Verification**: verification recomputes the receipt hash from the unsigned receipt, checks `metadata.receipt_id === metadata.proof.hash_sha256`, then verifies the Ed25519 signature over the UTF-8 hash string.
-- **Verb semantics**: the verb is read from `receipt.x402.verb`.
+- **Verification**: verification recomputes the receipt hash from the unsigned receipt, checks it against `metadata.proof.hash_sha256`, and verifies the Ed25519 signature over the UTF-8 hash string. `metadata.receipt_id` is optional compatibility metadata; when present it should match the proof hash.
+- **Verb semantics**: the canonical verb is read from `receipt.verb`; `receipt.x402.verb` is legacy / commercial fallback only.
 
 This repo no longer presents legacy blended envelopes as the primary contract. Legacy normalization remains only to accept older runtime responses that inlined `trace` beside the receipt.
 
@@ -84,10 +84,7 @@ pip install commandlayer
 {
   "receipt": {
     "status": "success",
-    "x402": {
-      "verb": "summarize",
-      "version": "1.1.0"
-    },
+    "verb": "summarize",
     "result": {
       "summary": "..."
     },
@@ -97,7 +94,7 @@ pip install commandlayer
         "alg": "ed25519-sha256",
         "canonical": "cl-stable-json-v1",
         "signer_id": "runtime.commandlayer.eth",
-        "hash_sha256": "same-value-as-receipt_id",
+        "hash_sha256": "sha256-of-unsigned-receipt",
         "signature_b64": "..."
       }
     }
@@ -160,6 +157,7 @@ Client methods now return a command response envelope:
 {
   "receipt": {
     "status": "success",
+    "verb": "summarize",
     "result": {
       "summary": "..."
     },
@@ -207,8 +205,9 @@ Verification reads exactly the current receipt contract:
 2. remove `metadata.receipt_id` and the signed hash/signature fields,
 3. canonicalize with `cl-stable-json-v1`,
 4. recompute `sha256`,
-5. require `metadata.receipt_id === metadata.proof.hash_sha256`,
-6. verify the Ed25519 signature.
+5. compare the recomputed hash to `metadata.proof.hash_sha256`,
+6. if `metadata.receipt_id` is present, treat equality to the proof hash as a compatibility / diagnostic check,
+7. verify the Ed25519 signature.
 
 ## Legacy handling retained
 

python-sdk/docs/verification.md

@@ -8,8 +8,9 @@ The verification helper validates the current receipt contract directly.
 2. Remove `metadata.receipt_id` and the signed hash/signature fields.
 3. Canonicalize with `cl-stable-json-v1`.
 4. Recompute `sha256`.
-5. Require `metadata.receipt_id == metadata.proof.hash_sha256`.
-6. Verify the Ed25519 signature over the UTF-8 hash string.
+5. Compare the recomputed hash to `metadata.proof.hash_sha256`.
+6. If `metadata.receipt_id` is present, treat equality to the proof hash as a compatibility / diagnostic check (not a hard requirement for `ok`).
+7. Verify the Ed25519 signature over the UTF-8 hash string.
 
 ## Helpers
 

typescript-sdk/README.md

@@ -6,8 +6,9 @@ Current-line TypeScript SDK for the CommandLayer Commons receipt contract (`1.1.
 
 - `response.receipt` is the signed receipt.
 - `response.runtime_metadata` is optional unsigned execution context.
-- `receipt.metadata.receipt_id` is the receipt hash identifier and must match `receipt.metadata.proof.hash_sha256`.
-- The verb lives at `receipt.x402.verb`.
+- `receipt.metadata.proof.hash_sha256` is the signed/recomputed receipt proof hash.
+- The canonical verb lives at `receipt.verb`; `receipt.x402.verb` is legacy / commercial fallback only.
+- `receipt.metadata.receipt_id`, when present, should match the proof hash but is not required for verification `ok`.
 
 ## Install
 
@@ -44,6 +45,7 @@ Client methods return:
 {
   "receipt": {
     "status": "success",
+    "verb": "summarize",
     "result": {},
     "metadata": {
       "proof": {
@@ -117,5 +119,5 @@ npm run test:integration
 - `receipt.verb` is the canonical verb field returned by the runtime.
 - `receipt.metadata.receipt_id` is an identifier for the receipt instance.
 - `receipt.metadata.proof.hash_sha256` is the SHA-256 hash over the unsigned canonical receipt payload.
-- `verifyReceipt()` succeeds when the declared algorithm/canonicalization match, the recomputed payload hash matches `hash_sha256`, and the Ed25519 signature validates over that hash.
+- `verifyReceipt()` succeeds when the declared algorithm/canonicalization match, the recomputed payload hash matches `hash_sha256`, and the Ed25519 signature validates over that hash. Any `receipt_id_matches` output is compatibility/diagnostic metadata and is not required for `ok`.
 - Legacy receipts that still place the verb under `receipt.x402.verb` continue to parse, but that path is fallback-only.