Harden v1.1.0 commercial schema validation (#12)

GsCommand · web-flow · commit 41252ca6a61f · 2026-03-19T19:33:40.000-04:00
diff --git a/POLICY.md b/POLICY.md
@@ -32,3 +32,4 @@ Release-defining prose docs may govern interpretation and process, but they are
 - `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.
+- `requester` is the governed field for the initiator of a `verify.request`; `verifier` is reserved for the authority that issues or attests the verification receipt.
diff --git a/README.md b/README.md
@@ -62,7 +62,8 @@ Protocol-Commercial uses a compact actor model:
 - `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
+- `requester`: the party initiating a verification request
+- `verifier`: the authority performing or attesting the verification result
 
 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.
 
diff --git a/SPEC.md b/SPEC.md
@@ -86,7 +86,8 @@ Protocol-Commercial v1.1.0 uses a compact governed actor grammar:
 - `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
+- `requester` = the party initiating a verification request
+- `verifier` = the authority performing or attesting the verification result
 
 Actor field names are normative. A field named `merchant` MUST contain an actor whose role is `merchant`, and likewise for the other actor fields.
 
diff --git a/checksums.txt b/checksums.txt
@@ -1,32 +1,32 @@
-41d9ee1becadafca63c9df7fc7fb73520aa732f933cba24de22bf8736ad68d68  examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json
+930cbbb3992d01385c1e5a64a4a04de5bac7c68a8b59a25a6c0e5507a1cea33f  examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json
 235de6956c2ef4b7b42176767ee34c7b913a6e5385ac11bf4ed6050179a430f4  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
 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
+dec8708eda1a9da3d3f54731146b2b3cbd292ab718fcc6a763062d83014b4390  examples/v1.1.0/commercial/checkout/invalid/001-checkout.request.invalid.json
+a6fbf133ce4629ce3831d9a2929bcc5eef1844d5edf97428d20ce897d77e031e  examples/v1.1.0/commercial/checkout/invalid/900-checkout.receipt.invalid.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
+1216c111a1c65a5ff80dbbba6394a5062e09aa8c8a6456bd4052109fce392b99  examples/v1.1.0/commercial/purchase/invalid/001-purchase.request.invalid.json
+e70a205a9d6a4ec729161508a02b3d36d69b801408eec5cf54573ddfbbdfd44d  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
+3dd86d4ca05f8d3488ec1203d451a2f263b8e8eca388a0001850d7867314a187  examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json
+24e1b4a8d3bb23f2d28c302cce7f20adc94b4561dd7e4bd9e4f28d17ea6657eb  examples/v1.1.0/commercial/ship/invalid/001-ship.request.invalid.json
+6f8a95a74285969d7ee7170539c9dd050585f13869ad7b1b0579c6fd2b8783cb  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
+a2a5e61fa04e12786a848e03bbabbc3f9d066ca55a6f48cb1ae1140f6373bf94  examples/v1.1.0/commercial/verify/invalid/001-verify.request.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
-ee1f2a87bdb06533b565c66b8fe07752355552deafc2df3545d697c2e0d15b7d  schemas/v1.1.0/commercial/authorize/authorize.receipt.schema.json
-11fc5cb599ee08ba242cf099f5283a3e46d24ccbd68d21c64b494a9f60180f78  schemas/v1.1.0/commercial/authorize/authorize.request.schema.json
-c32d8dd62a5bf9b63c1e1bd6c75fdc619abd2336239eabdaaffb1c4ced07c221  schemas/v1.1.0/commercial/checkout/checkout.receipt.schema.json
-2a070e49dcf8a42d6d7de151792c794f3d4561e0d6022f07d2a4d0d8f26231cb  schemas/v1.1.0/commercial/checkout/checkout.request.schema.json
-f9b8e134d57c719014cc35ce391a9bf56a381659d4dcc1ef9eeb40c55e63d3bf  schemas/v1.1.0/commercial/purchase/purchase.receipt.schema.json
-0c8af1923ed96ccbcaf634ebff0d3a9e0deb9c887ac036263958dfbcf9f66a3d  schemas/v1.1.0/commercial/purchase/purchase.request.schema.json
-1e9b04775e147f657ca17ab84b51f6fa89eb50e9afc5245ff00a7f8234af6063  schemas/v1.1.0/commercial/ship/ship.receipt.schema.json
-7155c14f8985ae375511b579620c17d40d0af05a91ea1a2b1d43e707bc4c7f8a  schemas/v1.1.0/commercial/ship/ship.request.schema.json
-9b1ac12cb98d3974f1be299c64342c4858418c4351856a4b9c1d32e792565fbd  schemas/v1.1.0/commercial/verify/verify.receipt.schema.json
-af08ddc3d0fdaa923148419cfeba42a100de90604176de593d62de908aafe7ba  schemas/v1.1.0/commercial/verify/verify.request.schema.json
+50874f3eea69a51ac132873b05e39318e4c2241078ca5e258e466934935ec945  examples/v1.1.0/commercial/verify/valid/900-verify.receipt.valid.json
+80fa9124c1560d0e55b83554d83581dabf72505cc4d9c1354157f51fddd9686a  manifest.json
+85070516cccc4f735ca2561c7ea1e7949efee4d7fed10e5ba40abb585c962292  schemas/v1.1.0/commercial/authorize/authorize.receipt.schema.json
+ef5da55ba5acdd43e8d2715204938762a63819dd370ebc8dfedad014617259c3  schemas/v1.1.0/commercial/authorize/authorize.request.schema.json
+66e39d85a503ec2fa096d789b5b3136a451387186fa33424c4bcb07ce9aea49b  schemas/v1.1.0/commercial/checkout/checkout.receipt.schema.json
+c4ca52ae4c5054a151c099d6108af57b17025ed7d86a99889c2cf7ffc9a341fa  schemas/v1.1.0/commercial/checkout/checkout.request.schema.json
+79b8f2fb15567b7b4ef87697ddcbc852df52852aa93d59e0aa44dbae230b5248  schemas/v1.1.0/commercial/purchase/purchase.receipt.schema.json
+e9b62cf29d5f58fed922e9bc77c8d3e13e6f7ed04785baad7a7e4fc600ab44b8  schemas/v1.1.0/commercial/purchase/purchase.request.schema.json
+209f3449f0c580f919a5d9d93cf863b37b70cdcf873a49fbbb57241c361034dd  schemas/v1.1.0/commercial/ship/ship.receipt.schema.json
+b876f8ffbfd87e5554374de114414f9e4091ba09c80d07b9b99a40ff1befd7c5  schemas/v1.1.0/commercial/ship/ship.request.schema.json
+5edde96068c144b3684ae36354c0cd97a26b4d5bf7fcf0da9a4847deead6ffc7  schemas/v1.1.0/commercial/verify/verify.receipt.schema.json
+06061bbb301a9d60fed64c0eea137dfa9d39c459e30079e6ba91c903a96e1ed5  schemas/v1.1.0/commercial/verify/verify.request.schema.json
 1431008b047fc5eb8fe2e0647a7a9d5e27e731ad89b97866c259a5e9937cc549  schemas/v1.1.0/index.json
diff --git a/examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json b/examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json
@@ -21,5 +21,10 @@
   },
   "authorization_scope": {
     "capture_mode": "manual"
+  },
+  "merchant": {
+    "role": "merchant",
+    "id": "merchant.example",
+    "kind": "organization"
   }
 }
diff --git a/examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json b/examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json
@@ -58,10 +58,6 @@
       "decimals": 2
     }
   },
-  "payment_ref": {
-    "type": "payment",
-    "id": "pay-2001"
-  },
   "payment_proof": {
     "scheme": "x402",
     "proof_type": "payment-proof",
diff --git a/schemas/v1.1.0/commercial/authorize/authorize.receipt.schema.json b/schemas/v1.1.0/commercial/authorize/authorize.receipt.schema.json
@@ -349,7 +349,6 @@
     "issued_at",
     "request_id",
     "status",
-    "authorization_id",
     "payer",
     "payee",
     "amount"
@@ -365,6 +364,7 @@
       },
       "then": {
         "required": [
+          "authorization_id",
           "approved_until"
         ],
         "properties": {
@@ -377,6 +377,11 @@
           },
           "payment_proof": {
             "$ref": "#/$defs/payment_proof"
+          },
+          "authorization_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
           }
         },
         "anyOf": [
@@ -407,10 +412,7 @@
       "if": {
         "properties": {
           "status": {
-            "enum": [
-              "denied",
-              "pending"
-            ]
+            "const": "denied"
           }
         }
       },
diff --git a/schemas/v1.1.0/commercial/authorize/authorize.request.schema.json b/schemas/v1.1.0/commercial/authorize/authorize.request.schema.json
@@ -355,6 +355,7 @@
     "requested_at",
     "payer",
     "payee",
+    "merchant",
     "amount",
     "authorization_scope"
   ]
diff --git a/schemas/v1.1.0/commercial/verify/verify.receipt.schema.json b/schemas/v1.1.0/commercial/verify/verify.receipt.schema.json
@@ -238,7 +238,7 @@
     "verifier": {
       "allOf": [
         {
-          "$ref": "#/$defs/actor"
+          "$ref": "#/$defs/actor_identity"
         },
         {
           "type": "object",
diff --git a/schemas/v1.1.0/commercial/verify/verify.request.schema.json b/schemas/v1.1.0/commercial/verify/verify.request.schema.json
@@ -252,10 +252,12 @@
       "format": "date-time"
     },
     "requester": {
-      "$ref": "#/$defs/actor_identity"
+      "$ref": "#/$defs/actor_identity",
+      "description": "The party initiating the verification request."
     },
     "verifier": {
-      "$ref": "#/$defs/verifier_actor"
+      "$ref": "#/$defs/verifier_actor",
+      "description": "The authority expected to perform or attest the verification result, when designated in advance."
     },
     "target": {
       "$ref": "#/$defs/target"
diff --git a/scripts/validate-all.mjs b/scripts/validate-all.mjs
@@ -10,6 +10,18 @@ const CURRENT_VERSION = "1.1.0";
 const SCHEMAS_ROOT = path.join(ROOT_DIR, "schemas", `v${CURRENT_VERSION}`);
 const EXAMPLES_ROOT = path.join(ROOT_DIR, "examples", `v${CURRENT_VERSION}`, "commercial");
 const EXPECTED_VERBS = ["authorize", "checkout", "purchase", "ship", "verify"];
+const CANONICAL_DEF_NAMES = [
+  "actor_identity",
+  "payer_actor",
+  "payee_actor",
+  "merchant_actor",
+  "provider_actor",
+  "carrier_actor",
+  "verifier_actor",
+  "reference",
+  "money",
+  "payment_proof"
+];
 
 async function collectJsonFiles(dir) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -39,6 +51,34 @@ function expectedVerbEntry(verb) {
   };
 }
 
+function normalizeJson(value) {
+  if (Array.isArray(value)) return value.map(normalizeJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, normalizeJson(value[key])])
+    );
+  }
+  return value;
+}
+
+function deepEqualJson(left, right) {
+  return JSON.stringify(normalizeJson(left)) === JSON.stringify(normalizeJson(right));
+}
+
+async function loadCurrentSchemas() {
+  const schemaFiles = (await collectJsonFiles(SCHEMAS_ROOT))
+    .filter((file) => file.endsWith(".schema.json"))
+    .sort();
+
+  return Promise.all(schemaFiles.map(async (file) => ({
+    file,
+    rel: path.relative(ROOT_DIR, file).replace(/\\/g, "/"),
+    schema: await loadJson(file)
+  })));
+}
+
 async function validateManifest() {
   const manifest = await loadJson(path.join(ROOT_DIR, "manifest.json"));
   assert(!("$schema" in manifest), "manifest.json must not carry a decorative $schema field");
@@ -59,21 +99,38 @@ async function validatePackage() {
 }
 
 async function validateSchemaTree() {
-  const schemaFiles = (await collectJsonFiles(SCHEMAS_ROOT)).filter((file) => file.endsWith(".schema.json"));
-  assert(schemaFiles.length === 10, "expected 10 current-line schema files");
+  const currentSchemas = await loadCurrentSchemas();
+  assert(currentSchemas.length === 10, "expected 10 current-line schema files");
   const ajv = new Ajv2020({ strict: true, allErrors: true, allowUnionTypes: false });
   addFormats(ajv);
   ajvErrors(ajv);
-  for (const file of schemaFiles) {
-    const schema = await loadJson(file);
-    const rel = path.relative(ROOT_DIR, file).replace(/\\/g, "/");
+  for (const { rel, schema } of currentSchemas) {
     const expectedId = `https://commandlayer.org/${rel}`;
     assert(schema.$schema === "https://json-schema.org/draft/2020-12/schema", `${rel} has unexpected $schema`);
     assert(schema.$id === expectedId, `${rel} has mismatched $id`);
     assert(!rel.includes("/_shared/"), "v1.1.0 current line must not use _shared");
     assert(!rel.includes("/requests/") && !rel.includes("/receipts/"), "v1.1.0 current line must not use nested request/receipt directories");
     ajv.compile(schema);
   }
+  return currentSchemas;
+}
+
+async function validateSchemaConsistency(currentSchemas) {
+  for (const defName of CANONICAL_DEF_NAMES) {
+    const holders = currentSchemas
+      .filter(({ schema }) => schema.$defs && defName in schema.$defs)
+      .map(({ rel, schema }) => ({ rel, def: schema.$defs[defName] }));
+
+    if (holders.length < 2) continue;
+
+    const baseline = holders[0];
+    for (const holder of holders.slice(1)) {
+      assert(
+        deepEqualJson(baseline.def, holder.def),
+        `canonical $defs drift for '${defName}': ${holder.rel} differs from ${baseline.rel}`
+      );
+    }
+  }
 }
 
 async function validateIndex() {
@@ -106,9 +163,10 @@ async function main() {
   await validateManifest();
   await validatePackage();
   await validateLayout();
-  await validateSchemaTree();
+  const currentSchemas = await validateSchemaTree();
+  await validateSchemaConsistency(currentSchemas);
   await validateIndex();
-  console.log("✅ Current release metadata, paths, and schemas validated.");
+  console.log("✅ Current release metadata, paths, schemas, and canonical $defs validated.");
 }
 
 main().catch((error) => {

Original file line number	Diff line number	Diff line change
`@@ -21,5 +21,10 @@`
`21`	`21`	`},`
`22`	`22`	`"authorization_scope": {`
`23`	`23`	`"capture_mode": "manual"`
	`24`	`+ },`
	`25`	`+ "merchant": {`
	`26`	`+ "role": "merchant",`
	`27`	`+ "id": "merchant.example",`
	`28`	`+ "kind": "organization"`
`24`	`29`	`}`
`25`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -355,6 +355,7 @@`
`355`	`355`	`"requested_at",`
`356`	`356`	`"payer",`
`357`	`357`	`"payee",`
	`358`	`+ "merchant",`
`358`	`359`	`"amount",`
`359`	`360`	`"authorization_scope"`
`360`	`361`	`]`
Original file line number	Diff line number	Diff line change
`@@ -238,7 +238,7 @@`
`238`	`238`	`"verifier": {`
`239`	`239`	`"allOf": [`
`240`	`240`	`{`
`241`		`- "$ref": "#/$defs/actor"`
	`241`	`+ "$ref": "#/$defs/actor_identity"`
`242`	`242`	`},`
`243`	`243`	`{`
`244`	`244`	`"type": "object",`