Tighten commercial actor and payment grammar (#9)

Author: GsCommand

POLICY.md

@@ -24,3 +24,10 @@ Release-defining prose docs may govern interpretation and process, but they are
 
 - Schema fixes before publication require maintainer signoff.
 - New verbs or version lines require explicit steward approval.
+
+## Commercial language governance
+
+- Actor roles are governed repo-wide; new roles require explicit steward approval.
+- `payment_requirement`, `payment_session`, and `payment_proof` are the canonical payment-layer names for shared semantics.
+- `fulfillment_ref` denotes the merchant or provider controlled fulfillment artifact, not a generic external pointer.
+- Shipment receipts must remain commercially scoped and tied to an upstream checkout or purchase.

README.md

@@ -35,14 +35,45 @@ Protocol-Commercial is x402-first.
 
 That means the normative commercial assumption is that commercial execution is gated and proven through x402-compatible payment requirements, sessions, authorizations, and proofs. The schemas in this repository do not define a transport implementation, but they do make the commercial contract explicit enough for an x402-aware runtime to execute deterministically.
 
+## Commercial grammar decisions
+
+### Actor grammar
+
+Protocol-Commercial uses a compact actor model:
+
+- `payer`: the party funding or bearing the commercial obligation
+- `payee`: the settlement recipient when it differs from the merchant identity
+- `merchant`: the seller or commercial principal governing the offer, order, or fulfillment
+- `provider`: an optional facilitating runtime or service performing settlement or fulfillment work on the merchant
+- `carrier`: the shipment operator once physical fulfillment exists
+- `verifier`: an authority that validates commercial evidence
+
+Field names are normative. A `merchant` field MUST carry a `merchant` actor, a `payer` field MUST carry a `payer` actor, and so on. `payee` is used only for settlement destination semantics; if omitted, the merchant is implicitly the payee.
+
+### x402 / payment grammar
+
+Protocol-Commercial standardizes three payment layers across the verb family:
+
+- `payment_requirement`: pre-payment terms or authorization preconditions
+- `payment_session`: live x402 negotiation/session state
+- `payment_proof`: final payment evidence for authorization or captured settlement
+
+The verbs use those layers intentionally:
+
+- `authorize` centers on `payment_requirement` and may emit authorization-flavored `payment_proof`
+- `checkout` centers on `payment_session` and requires `payment_proof` when capture succeeds
+- `purchase` accepts direct `payment_input` and requires `payment_proof` when capture succeeds
+- `ship` links to upstream commercial settlement through `commercial_ref` and optional `payment_ref`, rather than restating the full payment flow
+- `verify` verifies `payment_proof`, settlement, fulfillment, and receipt evidence
+
 ## Verb set
 
 | Verb | Purpose |
 | --- | --- |
 | `authorize` | Reserve payment authority before capture or settlement |
 | `checkout` | Finalize an order and request commercial capture |
 | `purchase` | Complete a one-step paid commercial action |
-| `ship` | Attach fulfillment state to a commercial order or purchase |
+| `ship` | Advance commercial fulfillment state for a settled checkout or purchase |
 | `verify` | Verify a commercial receipt, settlement, payment, or shipment target |
 
 ## Repository layout
@@ -127,6 +158,7 @@ This repository does not define:
     "total": { "amount": "49.99", "currency": "USDC", "decimals": 2 }
   },
   "capture": "immediate",
+  "payee": { "role": "payee", "id": "merchant-settlement", "kind": "wallet" },
   "payment_session": {
     "scheme": "x402",
     "session_id": "x402-session-001",

SPEC.md

@@ -65,10 +65,33 @@ Commercial schemas SHOULD add stricter structure than Commons wherever value mov
 
 - explicit counterparties
 - typed monetary amounts
-- typed references to order, invoice, authorization, payment, settlement, or shipment artifacts
+- typed references to order, invoice, authorization, fulfillment, payment, settlement, or shipment artifacts
 - typed settlement status
 - typed verification outcomes
 
+### 5.1 Actor grammar
+
+Protocol-Commercial v1.1.0 uses a compact governed actor grammar:
+
+- `payer` = the party that funds or bears the payment obligation
+- `payee` = the settlement recipient when distinct from the merchant
+- `merchant` = the commercial principal offering, selling, or fulfilling the order
+- `provider` = an optional facilitator executing settlement or fulfillment work for the merchant
+- `carrier` = the shipment operator for physical fulfillment
+- `verifier` = the authority validating commercial evidence
+
+Actor field names are normative. A field named `merchant` MUST contain an actor whose role is `merchant`, and likewise for the other actor fields.
+
+### 5.2 Payment grammar
+
+Protocol-Commercial v1.1.0 uses one payment language across the family:
+
+- `payment_requirement` = pre-payment terms or authorization preconditions
+- `payment_session` = live x402 negotiation/session state
+- `payment_proof` = final authorization or settlement evidence
+
+Requests SHOULD carry the earliest payment layer the caller can truthfully provide. Receipts MUST carry the latest payment layer the verb has canonically established. Successful capture receipts for `checkout` and `purchase` MUST carry `payment_proof`. `ship` MUST link to the upstream commercial transaction and MAY carry payment evidence by reference rather than re-embedding settlement state.
+
 ## 6. x402 binding expectations
 
 Protocol-Commercial v1.1.0 is x402-first.

checksums.txt

@@ -1,21 +1,21 @@
 a63b196cdd5d050dcd12c7a01f15757ad1558afae8b7c81681e50da23149df44  examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json
 8b577f94216c6674dc7781a692715ccd814b253fa74fa807b695e8ea5c144748  examples/v1.1.0/commercial/authorize/invalid/900-authorize.receipt.invalid.json
 afbcee85906d0249ed0c60eecf40657832549ca8032a99154dd0e643b6d82884  examples/v1.1.0/commercial/authorize/valid/001-authorize.request.valid.json
-477d5b42eca56782145d60b167934fe6c038e0bdb9ed62b608987352ccb5229d  examples/v1.1.0/commercial/authorize/valid/900-authorize.receipt.valid.json
+c0ca42d7269f82c69cdcb24a0cd19d9bfc0a30cbf9b991e3f82b58c01ac16961  examples/v1.1.0/commercial/authorize/valid/900-authorize.receipt.valid.json
 4c3fe6aff5283da7b083e072d8f5a3c9362fbbf1a9614322a297a350cbfbea8d  examples/v1.1.0/commercial/checkout/invalid/001-checkout.request.invalid.json
 c87c1e944610020925d0ad5f78d9f5c3532c53494b824dca014537859f6ebed0  examples/v1.1.0/commercial/checkout/invalid/900-checkout.receipt.invalid.json
-ed17f81adaf17f338e56157f2b3ee54831d5eeb03f08c4da8ba5a088a4f6c587  examples/v1.1.0/commercial/checkout/valid/001-checkout.request.valid.json
-9341c26828d9d4f5ea15597a406face97b424f18a9a919dcac37b92b7bedb31f  examples/v1.1.0/commercial/checkout/valid/900-checkout.receipt.valid.json
-9ef6537f316094ede495337b869e85bd7231dc1dc62c12018ad193c81101bb0e  examples/v1.1.0/commercial/purchase/invalid/001-purchase.request.invalid.json
-02445b05f1baaff11508c7ea66e9fc83f46e348d8aa0d3dddd3a3a49673350cf  examples/v1.1.0/commercial/purchase/invalid/900-purchase.receipt.invalid.json
-db9b72f90c2cd85f43052b877a798e16023bce78c62a76c5ce004d0ea4ed11a6  examples/v1.1.0/commercial/purchase/valid/001-purchase.request.valid.json
-f6c68d52cfb7aff498ba4425a0e304806adf0d51fd0df74963184d978d598cec  examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json
-bdd3b549b13629af35cacc4a7a3a290de43a3218143e65918c9e38d8521ddbda  examples/v1.1.0/commercial/ship/invalid/001-ship.request.invalid.json
-3be92029cf79f92d299b995610073d0149c16e047165369533f5e660120bf621  examples/v1.1.0/commercial/ship/invalid/900-ship.receipt.invalid.json
-f70e948f963cf243b9d9a26e671bfee9941ec65f829bb900751e0436691f69de  examples/v1.1.0/commercial/ship/valid/001-ship.request.valid.json
-cef000ad2e5b6952ad9b31bb1b068a6e457a22ee3e3b21d1683bd92936d06ab0  examples/v1.1.0/commercial/ship/valid/900-ship.receipt.valid.json
+6607a0a6ceefd0ca978f7969cb1e6e326e9a8ceaedde17505d2be81a260b3c8c  examples/v1.1.0/commercial/checkout/valid/001-checkout.request.valid.json
+f8880c06f91c1d21a617fbe7f2b6a9d41d37db9f4fd5e9998689100c16f4000e  examples/v1.1.0/commercial/checkout/valid/900-checkout.receipt.valid.json
+b21abc778134f0cd712027b093b2e6fb213866fa399e5756c6bad9b7b68eba11  examples/v1.1.0/commercial/purchase/invalid/001-purchase.request.invalid.json
+1222a815c6cff7cfce737dd7b99c488d167055f8ee061cda191b631d546b62c6  examples/v1.1.0/commercial/purchase/invalid/900-purchase.receipt.invalid.json
+2b235a6d567127c54da9c6c3eacf915c79a5c5127197a9aadbfb50289b122957  examples/v1.1.0/commercial/purchase/valid/001-purchase.request.valid.json
+ec905c885a47aba6cf336666fc322bc40a45ab52647ca722965cafd1b0e5f55a  examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json
+a10046d83c5455867a21f7d6fc30dea3241a40f64a90c53b3d5fbc2d3bdff549  examples/v1.1.0/commercial/ship/invalid/001-ship.request.invalid.json
+6fbf8480ce1dc706be1d8efe33f4c9542c188b45f5a9ca18c38b74996d085c79  examples/v1.1.0/commercial/ship/invalid/900-ship.receipt.invalid.json
+576924f554079213ce078d4be6c54e5ffc58839bde4182d73d02ba3412e47f3b  examples/v1.1.0/commercial/ship/valid/001-ship.request.valid.json
+a004cb1385b1ca173b89df702e2b52d63f870521652f98f023359d30009b8df0  examples/v1.1.0/commercial/ship/valid/900-ship.receipt.valid.json
 b9bcdbcd34058ab229df851448925370a586e2bbedc77a8e28b535e1a9468c6e  examples/v1.1.0/commercial/verify/invalid/001-verify.request.invalid.json
-51fcf4b17443a780851dc563dd867d155d334d83cd44a44146197e270c1caae9  examples/v1.1.0/commercial/verify/invalid/900-verify.receipt.invalid.json
+e0016f3510bda6efcbdc3984bd077c37160a6a9db039dafa1d602806d8cf6e73  examples/v1.1.0/commercial/verify/invalid/900-verify.receipt.invalid.json
 56d02915471d62f7687e3f6258d75754c8e7a44ca717e4ca0906dd4bb6fc34fb  examples/v1.1.0/commercial/verify/valid/001-verify.request.valid.json
 440c964d06f48470e17110a4cd683085740cae97e937a2452c0e4d4eec2b8bb4  examples/v1.1.0/commercial/verify/valid/900-verify.receipt.valid.json
 dffbf20c692d46a3a8af047a2fa4647c33ec910e76c30dd5f948eac258668556  manifest.json

examples/v1.1.0/commercial/authorize/valid/900-authorize.receipt.valid.json

@@ -17,13 +17,18 @@
     "id": "merchant-settlement",
     "kind": "wallet"
   },
+  "merchant": {
+    "role": "merchant",
+    "id": "merchant.example",
+    "kind": "organization"
+  },
   "amount": {
     "amount": "49.99",
     "currency": "USDC",
     "decimals": 2
   },
   "approved_until": "2026-03-20T10:00:00Z",
-  "settlement_precondition_ref": {
+  "payment_requirement_ref": {
     "type": "payment_requirement",
     "id": "x402-auth-001"
   },

examples/v1.1.0/commercial/checkout/valid/001-checkout.request.valid.json

@@ -14,6 +14,11 @@
     "id": "merchant.example",
     "kind": "organization"
   },
+  "payee": {
+    "role": "payee",
+    "id": "merchant-settlement",
+    "kind": "wallet"
+  },
   "provider": {
     "role": "provider",
     "id": "runtime.commandlayer",

examples/v1.1.0/commercial/checkout/valid/900-checkout.receipt.valid.json

@@ -16,6 +16,11 @@
     "id": "merchant.example",
     "kind": "organization"
   },
+  "payee": {
+    "role": "payee",
+    "id": "merchant-settlement",
+    "kind": "wallet"
+  },
   "order_ref": {
     "type": "order",
     "id": "ord-1001"
@@ -48,7 +53,7 @@
     }
   },
   "fulfillment_ref": {
-    "type": "receipt",
+    "type": "fulfillment",
     "id": "fulfill-001",
     "uri": "https://merchant.example/fulfillment/fulfill-001"
   },

examples/v1.1.0/commercial/purchase/invalid/001-purchase.request.invalid.json

@@ -12,14 +12,26 @@
     "role": "merchant",
     "id": "merchant.example"
   },
-  "product": {
-    "product_id": "svc-analysis-pack",
-    "description": "One analysis execution bundle",
-    "quantity": 0
+  "items": [
+    {
+      "sku": "svc-analysis-pack",
+      "description": "One analysis execution bundle",
+      "quantity": 0,
+      "unit_price": {
+        "amount": "12.50",
+        "currency": "USDC"
+      }
+    }
+  ],
+  "amount_breakdown": {
+    "subtotal": {
+      "amount": "12.50",
+      "currency": "USDC"
+    },
+    "total": {
+      "amount": "12.50",
+      "currency": "USDC"
+    }
   },
-  "amount": {
-    "amount": "12.50",
-    "currency": "USDC"
-  },
-  "x402": {}
+  "payment_input": {}
 }

examples/v1.1.0/commercial/purchase/invalid/900-purchase.receipt.invalid.json

@@ -15,16 +15,22 @@
     "role": "merchant",
     "id": "merchant.example"
   },
-  "amount": {
-    "amount": "12.50",
-    "currency": "USDC"
+  "amount_breakdown": {
+    "subtotal": {
+      "amount": "15.00",
+      "currency": "USDC"
+    },
+    "total": {
+      "amount": "15.00",
+      "currency": "USDC"
+    }
   },
   "settlement": {
-    "status": "failed",
+    "status": "captured",
     "method": "x402",
     "settlement_ref": "settle-2001",
     "amount": {
-      "amount": "12.50",
+      "amount": "15.00",
       "currency": "USDC"
     }
   }

examples/v1.1.0/commercial/purchase/valid/001-purchase.request.valid.json

@@ -14,20 +14,49 @@
     "id": "merchant.example",
     "kind": "organization"
   },
+  "payee": {
+    "role": "payee",
+    "id": "merchant-settlement",
+    "kind": "wallet"
+  },
   "provider": {
     "role": "provider",
     "id": "runtime.commandlayer",
     "kind": "service"
   },
-  "product": {
-    "product_id": "svc-analysis-pack",
-    "description": "One analysis execution bundle",
-    "quantity": 1
-  },
-  "amount": {
-    "amount": "12.50",
-    "currency": "USDC",
-    "decimals": 2
+  "items": [
+    {
+      "sku": "svc-analysis-pack",
+      "description": "One analysis execution bundle",
+      "quantity": 1,
+      "unit_price": {
+        "amount": "12.50",
+        "currency": "USDC",
+        "decimals": 2
+      }
+    },
+    {
+      "sku": "svc-priority-routing",
+      "description": "Priority routing add-on",
+      "quantity": 1,
+      "unit_price": {
+        "amount": "2.50",
+        "currency": "USDC",
+        "decimals": 2
+      }
+    }
+  ],
+  "amount_breakdown": {
+    "subtotal": {
+      "amount": "15.00",
+      "currency": "USDC",
+      "decimals": 2
+    },
+    "total": {
+      "amount": "15.00",
+      "currency": "USDC",
+      "decimals": 2
+    }
   },
   "order_ref": {
     "type": "order",
@@ -37,7 +66,8 @@
     "type": "invoice",
     "id": "inv-2001"
   },
-  "x402": {
+  "merchant_reference": "instant-purchase-2001",
+  "payment_input": {
     "payment_requirement_ref": {
       "type": "payment_requirement",
       "id": "x402-req-2001"