xytara 3.1.13 → 3.1.14

package/scripts/verify_execution_dedupe.js

@@ -1,189 +1,189 @@
-"use strict";
-
-// Verifies the deferred-x402 execution dedupe guard:
-//   - two CONCURRENT commands carrying the SAME signed authorization (same EIP-3009
-//     nonce) against a slow executor result in exactly ONE execution and ONE settle;
-//     the duplicate is rejected 409 payment_authorization_in_progress and not charged;
-//   - a later command with a DIFFERENT authorization is not blocked;
-//   - unit level: the guard is a no-op for non-deferred verifications, fails open when
-//     the store is missing, rejects an in-flight duplicate, frees the slot on release,
-//     and prunes entries past their TTL.
-//
-// No real network or chain is used.
-
-const assert = require("assert");
-const http = require("http");
-const { claimDeferredExecution, releaseDeferredExecution, deferredAuthorizationKey } = require("../lib/execution_dedupe");
-
-const ACCEPTS = [
-  {
-    scheme: "exact",
-    network: "eip155:84532",
-    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-    amount: "1000",
-    payTo: "0x7cd2E0Ed2721319B20FAac4109774d030833F84D",
-    extra: { name: "USDC", version: "2" },
-    maxTimeoutSeconds: 60
-  }
-];
-
-function startMockServer() {
-  const calls = { verify: 0, settle: 0, execSlow: 0 };
-  const server = http.createServer((req, res) => {
-    const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => {
-      let body = {};
-      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch (_) { body = {}; }
-      const reply = (payload, status) => {
-        const text = JSON.stringify(payload);
-        res.writeHead(status || 200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
-        res.end(text);
-      };
-      if (req.method === "POST" && req.url === "/verify") { calls.verify += 1; return reply({ isValid: true, payer: "0x1111111111111111111111111111111111111111" }); }
-      if (req.method === "POST" && req.url === "/settle") { calls.settle += 1; return reply({ success: true, transaction: "0xmocktx", network: "eip155:84532", payer: "0x1111111111111111111111111111111111111111" }); }
-      if (req.method === "POST" && req.url === "/exec-slow") {
-        calls.execSlow += 1;
-        return setTimeout(() => reply({ ok: true, status: "completed", output: { value: "slow-ok" } }), 350);
-      }
-      if (req.method === "POST" && req.url === "/exec-fail") {
-        calls.execFail = (calls.execFail || 0) + 1;
-        return reply({ ok: false, reason: "data_required" }, 502);
-      }
-      res.writeHead(404); res.end();
-    });
-  });
-  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, calls, port: server.address().port })));
-}
-
-function paymentHeader(nonceHex) {
-  const accepted = ACCEPTS[0];
-  return Buffer.from(JSON.stringify({
-    x402Version: 2,
-    accepted,
-    payload: {
-      signature: "ok",
-      authorization: {
-        from: "0x1111111111111111111111111111111111111111",
-        to: accepted.payTo,
-        value: accepted.amount,
-        validAfter: "0",
-        validBefore: String(Math.floor(Date.now() / 1000) + 600),
-        nonce: nonceHex
-      }
-    }
-  }), "utf8").toString("base64");
-}
-
-async function post(baseUrl, path, body, headers = {}) {
-  const res = await fetch(`${baseUrl}${path}`, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
-  let json = null;
-  try { json = await res.json(); } catch (_) { json = null; }
-  return { status: res.status, json, receipt: res.headers.get("payment-response") };
-}
-
-function runUnitChecks() {
-  // No-op for a non-deferred verification.
-  assert.deepStrictEqual(claimDeferredExecution({ inFlightPaymentAuthorizations: new Map() }, { ok: true }), { ok: true, key: null }, "non-deferred must be a no-op claim");
-  // Key derivation.
-  const verification = { deferred_settlement: { protocol: "x402_facilitator", authorization: { paymentPayload: { payload: { authorization: { from: "0xABC", nonce: "0xDEAD" } } } } } };
-  assert.strictEqual(deferredAuthorizationKey(verification), "x402:0xabc:0xdead", "key must be lowercased from:nonce");
-  // Fail open with no store.
-  assert.deepStrictEqual(claimDeferredExecution({}, verification), { ok: true, key: null }, "missing store must fail open");
-  // In-flight duplicate rejected, then freed on release.
-  const state = { inFlightPaymentAuthorizations: new Map() };
-  const first = claimDeferredExecution(state, verification);
-  assert.strictEqual(first.ok, true, "first claim must succeed");
-  const dup = claimDeferredExecution(state, verification);
-  assert.strictEqual(dup.ok, false, "second concurrent claim must be rejected");
-  assert.strictEqual(dup.status, 409, "duplicate must be 409");
-  assert.strictEqual(dup.reason, "payment_authorization_in_progress", "duplicate reason");
-  releaseDeferredExecution(state, first.key);
-  assert.strictEqual(claimDeferredExecution(state, verification).ok, true, "claim must succeed again after release");
-  // TTL prune: an expired entry is forgotten on the next claim.
-  const stale = { inFlightPaymentAuthorizations: new Map([["x402:0xabc:0xdead", { status: "in_flight", expires_at: Date.now() - 1 }]]) };
-  assert.strictEqual(claimDeferredExecution(stale, verification).ok, true, "an expired slot must be pruned and re-claimable");
-  console.log("  ok: unit checks (no-op, key, fail-open, duplicate, release, ttl-prune)");
-}
-
-async function main() {
-  runUnitChecks();
-
-  const mock = await startMockServer();
-  const mockBase = `http://127.0.0.1:${mock.port}`;
-  const prev = {
-    mode: process.env.XYTARA_PAYMENT_VERIFICATION_MODE,
-    accepts: process.env.XYTARA_X402_ACCEPTS_JSON,
-    facUrl: process.env.XYTARA_X402_FACILITATOR_URL,
-    targets: process.env.XYTARA_EXECUTION_TARGETS_JSON
-  };
-  process.env.XYTARA_PAYMENT_VERIFICATION_MODE = "x402_facilitator";
-  process.env.XYTARA_X402_ACCEPTS_JSON = JSON.stringify(ACCEPTS);
-  process.env.XYTARA_X402_FACILITATOR_URL = mockBase;
-  process.env.XYTARA_EXECUTION_TARGETS_JSON = JSON.stringify([
-    { target_id: "exec_slow", task_ref: "exec.slow", endpoint_url: `${mockBase}/exec-slow` },
-    { target_id: "exec_fail", task_ref: "exec.fail", endpoint_url: `${mockBase}/exec-fail` }
-  ]);
-
-  delete require.cache[require.resolve("../server")];
-  const { createServer } = require("../server");
-  const server = createServer();
-  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
-  const baseUrl = `http://127.0.0.1:${server.address().port}`;
-  const execBody = { account_id: "acct_dedupe", command: "slow exec", task_ref: "exec.slow", body: { subject_id: "s-1" } };
-
-  try {
-    // Two concurrent requests sharing ONE authorization (same nonce) -> one wins, one 409.
-    const sharedNonce = `0x${"ab".repeat(32)}`;
-    const [a, b] = await Promise.all([
-      post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(sharedNonce) }),
-      post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(sharedNonce) })
-    ]);
-    const statuses = [a.status, b.status].sort();
-    assert.deepStrictEqual(statuses, [200, 409], `exactly one must win and one must 409, got ${statuses}`);
-    const winner = a.status === 200 ? a : b;
-    const loser = a.status === 409 ? a : b;
-    assert.strictEqual(loser.json.reason, "payment_authorization_in_progress", "the duplicate must report in_progress");
-    assert.strictEqual(loser.json.payment_settled, false, "the rejected duplicate must not be charged");
-    assert.strictEqual(loser.receipt, null, "the rejected duplicate must carry no receipt");
-    assert.strictEqual(typeof winner.receipt, "string", "the winner must carry a settlement receipt");
-    assert.strictEqual(mock.calls.execSlow, 1, "the external target must have executed exactly once");
-    assert.strictEqual(mock.calls.settle, 1, "settlement must have happened exactly once");
-
-    // A different authorization (fresh nonce) is not blocked.
-    const other = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(`0x${"cd".repeat(32)}`) });
-    assert.strictEqual(other.status, 200, "a distinct authorization must not be blocked");
-    assert.strictEqual(mock.calls.execSlow, 2, "the distinct authorization must execute");
-
-    console.log("  ok: concurrent same-authorization -> one execution, one settle, duplicate 409");
-
-    // Slot is released on a FAILED call, so a legitimate retry (even reusing the same
-    // still-unspent nonce) is not wrongly 409'd. Two SEQUENTIAL same-nonce calls to a
-    // failing executor must BOTH reach execution and neither be charged.
-    const failNonce = `0x${"ef".repeat(32)}`;
-    const failBody = { account_id: "acct_dedupe", command: "failing exec", task_ref: "exec.fail", body: { subject_id: "s-2" } };
-    const f1 = await post(baseUrl, "/x402/commands/execute", failBody, { "payment-signature": paymentHeader(failNonce) });
-    const f2 = await post(baseUrl, "/x402/commands/execute", failBody, { "payment-signature": paymentHeader(failNonce) });
-    assert.strictEqual(f1.status, 502, "first failing call must 502 (not 409)");
-    assert.strictEqual(f2.status, 502, "retry after failure must reach execution, not be blocked as a duplicate");
-    assert.strictEqual(f1.json.payment_settled, false, "failed call must not be charged");
-    assert.strictEqual(f2.json.payment_settled, false, "retry must not be charged");
-    assert.strictEqual(mock.calls.execFail, 2, "both failing attempts must have executed (slot released each time)");
-    console.log("  ok: failed call releases the slot -> retry not blocked, nothing charged");
-
-    console.log("xytara verify:execution-dedupe passed");
-  } finally {
-    await new Promise((resolve) => server.close(resolve));
-    await new Promise((resolve) => mock.server.close(resolve));
-    const restore = (k, v) => { if (v === undefined) delete process.env[k]; else process.env[k] = v; };
-    restore("XYTARA_PAYMENT_VERIFICATION_MODE", prev.mode);
-    restore("XYTARA_X402_ACCEPTS_JSON", prev.accepts);
-    restore("XYTARA_X402_FACILITATOR_URL", prev.facUrl);
-    restore("XYTARA_EXECUTION_TARGETS_JSON", prev.targets);
-  }
-}
-
-main().catch((error) => {
-  console.error(error && error.message ? error.message : error);
-  process.exitCode = 1;
-});
+"use strict";
+
+// Verifies the deferred-x402 execution dedupe guard:
+//   - two CONCURRENT commands carrying the SAME signed authorization (same EIP-3009
+//     nonce) against a slow executor result in exactly ONE execution and ONE settle;
+//     the duplicate is rejected 409 payment_authorization_in_progress and not charged;
+//   - a later command with a DIFFERENT authorization is not blocked;
+//   - unit level: the guard is a no-op for non-deferred verifications, fails open when
+//     the store is missing, rejects an in-flight duplicate, frees the slot on release,
+//     and prunes entries past their TTL.
+//
+// No real network or chain is used.
+
+const assert = require("assert");
+const http = require("http");
+const { claimDeferredExecution, releaseDeferredExecution, deferredAuthorizationKey } = require("../lib/execution_dedupe");
+
+const ACCEPTS = [
+  {
+    scheme: "exact",
+    network: "eip155:84532",
+    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    amount: "1000",
+    payTo: "0x7cd2E0Ed2721319B20FAac4109774d030833F84D",
+    extra: { name: "USDC", version: "2" },
+    maxTimeoutSeconds: 60
+  }
+];
+
+function startMockServer() {
+  const calls = { verify: 0, settle: 0, execSlow: 0 };
+  const server = http.createServer((req, res) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      let body = {};
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch (_) { body = {}; }
+      const reply = (payload, status) => {
+        const text = JSON.stringify(payload);
+        res.writeHead(status || 200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
+        res.end(text);
+      };
+      if (req.method === "POST" && req.url === "/verify") { calls.verify += 1; return reply({ isValid: true, payer: "0x1111111111111111111111111111111111111111" }); }
+      if (req.method === "POST" && req.url === "/settle") { calls.settle += 1; return reply({ success: true, transaction: "0xmocktx", network: "eip155:84532", payer: "0x1111111111111111111111111111111111111111" }); }
+      if (req.method === "POST" && req.url === "/exec-slow") {
+        calls.execSlow += 1;
+        return setTimeout(() => reply({ ok: true, status: "completed", output: { value: "slow-ok" } }), 350);
+      }
+      if (req.method === "POST" && req.url === "/exec-fail") {
+        calls.execFail = (calls.execFail || 0) + 1;
+        return reply({ ok: false, reason: "data_required" }, 502);
+      }
+      res.writeHead(404); res.end();
+    });
+  });
+  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, calls, port: server.address().port })));
+}
+
+function paymentHeader(nonceHex) {
+  const accepted = ACCEPTS[0];
+  return Buffer.from(JSON.stringify({
+    x402Version: 2,
+    accepted,
+    payload: {
+      signature: "ok",
+      authorization: {
+        from: "0x1111111111111111111111111111111111111111",
+        to: accepted.payTo,
+        value: accepted.amount,
+        validAfter: "0",
+        validBefore: String(Math.floor(Date.now() / 1000) + 600),
+        nonce: nonceHex
+      }
+    }
+  }), "utf8").toString("base64");
+}
+
+async function post(baseUrl, path, body, headers = {}) {
+  const res = await fetch(`${baseUrl}${path}`, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
+  let json = null;
+  try { json = await res.json(); } catch (_) { json = null; }
+  return { status: res.status, json, receipt: res.headers.get("payment-response") };
+}
+
+function runUnitChecks() {
+  // No-op for a non-deferred verification.
+  assert.deepStrictEqual(claimDeferredExecution({ inFlightPaymentAuthorizations: new Map() }, { ok: true }), { ok: true, key: null }, "non-deferred must be a no-op claim");
+  // Key derivation.
+  const verification = { deferred_settlement: { protocol: "x402_facilitator", authorization: { paymentPayload: { payload: { authorization: { from: "0xABC", nonce: "0xDEAD" } } } } } };
+  assert.strictEqual(deferredAuthorizationKey(verification), "x402:0xabc:0xdead", "key must be lowercased from:nonce");
+  // Fail open with no store.
+  assert.deepStrictEqual(claimDeferredExecution({}, verification), { ok: true, key: null }, "missing store must fail open");
+  // In-flight duplicate rejected, then freed on release.
+  const state = { inFlightPaymentAuthorizations: new Map() };
+  const first = claimDeferredExecution(state, verification);
+  assert.strictEqual(first.ok, true, "first claim must succeed");
+  const dup = claimDeferredExecution(state, verification);
+  assert.strictEqual(dup.ok, false, "second concurrent claim must be rejected");
+  assert.strictEqual(dup.status, 409, "duplicate must be 409");
+  assert.strictEqual(dup.reason, "payment_authorization_in_progress", "duplicate reason");
+  releaseDeferredExecution(state, first.key);
+  assert.strictEqual(claimDeferredExecution(state, verification).ok, true, "claim must succeed again after release");
+  // TTL prune: an expired entry is forgotten on the next claim.
+  const stale = { inFlightPaymentAuthorizations: new Map([["x402:0xabc:0xdead", { status: "in_flight", expires_at: Date.now() - 1 }]]) };
+  assert.strictEqual(claimDeferredExecution(stale, verification).ok, true, "an expired slot must be pruned and re-claimable");
+  console.log("  ok: unit checks (no-op, key, fail-open, duplicate, release, ttl-prune)");
+}
+
+async function main() {
+  runUnitChecks();
+
+  const mock = await startMockServer();
+  const mockBase = `http://127.0.0.1:${mock.port}`;
+  const prev = {
+    mode: process.env.XYTARA_PAYMENT_VERIFICATION_MODE,
+    accepts: process.env.XYTARA_X402_ACCEPTS_JSON,
+    facUrl: process.env.XYTARA_X402_FACILITATOR_URL,
+    targets: process.env.XYTARA_EXECUTION_TARGETS_JSON
+  };
+  process.env.XYTARA_PAYMENT_VERIFICATION_MODE = "x402_facilitator";
+  process.env.XYTARA_X402_ACCEPTS_JSON = JSON.stringify(ACCEPTS);
+  process.env.XYTARA_X402_FACILITATOR_URL = mockBase;
+  process.env.XYTARA_EXECUTION_TARGETS_JSON = JSON.stringify([
+    { target_id: "exec_slow", task_ref: "exec.slow", endpoint_url: `${mockBase}/exec-slow` },
+    { target_id: "exec_fail", task_ref: "exec.fail", endpoint_url: `${mockBase}/exec-fail` }
+  ]);
+
+  delete require.cache[require.resolve("../server")];
+  const { createServer } = require("../server");
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const baseUrl = `http://127.0.0.1:${server.address().port}`;
+  const execBody = { account_id: "acct_dedupe", command: "slow exec", task_ref: "exec.slow", body: { subject_id: "s-1" } };
+
+  try {
+    // Two concurrent requests sharing ONE authorization (same nonce) -> one wins, one 409.
+    const sharedNonce = `0x${"ab".repeat(32)}`;
+    const [a, b] = await Promise.all([
+      post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(sharedNonce) }),
+      post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(sharedNonce) })
+    ]);
+    const statuses = [a.status, b.status].sort();
+    assert.deepStrictEqual(statuses, [200, 409], `exactly one must win and one must 409, got ${statuses}`);
+    const winner = a.status === 200 ? a : b;
+    const loser = a.status === 409 ? a : b;
+    assert.strictEqual(loser.json.reason, "payment_authorization_in_progress", "the duplicate must report in_progress");
+    assert.strictEqual(loser.json.payment_settled, false, "the rejected duplicate must not be charged");
+    assert.strictEqual(loser.receipt, null, "the rejected duplicate must carry no receipt");
+    assert.strictEqual(typeof winner.receipt, "string", "the winner must carry a settlement receipt");
+    assert.strictEqual(mock.calls.execSlow, 1, "the external target must have executed exactly once");
+    assert.strictEqual(mock.calls.settle, 1, "settlement must have happened exactly once");
+
+    // A different authorization (fresh nonce) is not blocked.
+    const other = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader(`0x${"cd".repeat(32)}`) });
+    assert.strictEqual(other.status, 200, "a distinct authorization must not be blocked");
+    assert.strictEqual(mock.calls.execSlow, 2, "the distinct authorization must execute");
+
+    console.log("  ok: concurrent same-authorization -> one execution, one settle, duplicate 409");
+
+    // Slot is released on a FAILED call, so a legitimate retry (even reusing the same
+    // still-unspent nonce) is not wrongly 409'd. Two SEQUENTIAL same-nonce calls to a
+    // failing executor must BOTH reach execution and neither be charged.
+    const failNonce = `0x${"ef".repeat(32)}`;
+    const failBody = { account_id: "acct_dedupe", command: "failing exec", task_ref: "exec.fail", body: { subject_id: "s-2" } };
+    const f1 = await post(baseUrl, "/x402/commands/execute", failBody, { "payment-signature": paymentHeader(failNonce) });
+    const f2 = await post(baseUrl, "/x402/commands/execute", failBody, { "payment-signature": paymentHeader(failNonce) });
+    assert.strictEqual(f1.status, 502, "first failing call must 502 (not 409)");
+    assert.strictEqual(f2.status, 502, "retry after failure must reach execution, not be blocked as a duplicate");
+    assert.strictEqual(f1.json.payment_settled, false, "failed call must not be charged");
+    assert.strictEqual(f2.json.payment_settled, false, "retry must not be charged");
+    assert.strictEqual(mock.calls.execFail, 2, "both failing attempts must have executed (slot released each time)");
+    console.log("  ok: failed call releases the slot -> retry not blocked, nothing charged");
+
+    console.log("xytara verify:execution-dedupe passed");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    await new Promise((resolve) => mock.server.close(resolve));
+    const restore = (k, v) => { if (v === undefined) delete process.env[k]; else process.env[k] = v; };
+    restore("XYTARA_PAYMENT_VERIFICATION_MODE", prev.mode);
+    restore("XYTARA_X402_ACCEPTS_JSON", prev.accepts);
+    restore("XYTARA_X402_FACILITATOR_URL", prev.facUrl);
+    restore("XYTARA_EXECUTION_TARGETS_JSON", prev.targets);
+  }
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : error);
+  process.exitCode = 1;
+});

package/scripts/verify_execution_surfacing.js

@@ -1,76 +1,76 @@
-"use strict";
-
-// Verifies that when a real execution target runs, its actual output is surfaced
-// into the buyer-facing artifacts (command.deliverables + execution.results_by_task_id)
-// — provider-agnostically across the target response shapes — and that the
-// synthetic ("simulated") path is unchanged when no target runs.
-
-const assert = require("assert");
-const { createCommandArtifacts } = require("../lib/commerce_artifacts");
-
-const basePayload = {
-  command: "command.execute",
-  tasks: [{ task_id: "t1", task_ref: "adapter.mcp.invoke" }],
-  body: { tool_name: "keccak256" }
-};
-const baseQuote = {
-  quote_id: "quote_test1",
-  account_id: "acct_test",
-  amount_minor: 5,
-  currency: "USD_CENTS",
-  settlement_mode: null,
-  integration_ids: [],
-  protocols: ["mcp"],
-  capabilities: [],
-  adapters: ["http"],
-  execution_integration_ids: [],
-  payment_scheme: "exact",
-  payment_protocol: "x402"
-};
-
-function run(label, opts, check) {
-  const out = createCommandArtifacts(basePayload, baseQuote, opts);
-  check({
-    out,
-    deliv: out.command.deliverables[0],
-    taskResult: out.transaction.execution.results_by_task_id.t1
-  });
-  console.log("  ok:", label);
-}
-
-// 1. Nested MCP-executor shape: { result: { output: <real> } }
-run("nested result.output (MCP executor shape)",
-  { externalExecution: { provider: "mcp", target_id: "tg1", target_response: { ok: true, result: { output: { digest: "0xdeadbeef", length: 8 } }, provider_status: "completed" } } },
-  ({ deliv, taskResult }) => {
-    assert.deepStrictEqual(deliv.output_payload, { digest: "0xdeadbeef", length: 8 }, "deliverable carries real output");
-    assert.strictEqual(deliv.invocation_status, "provider_completed");
-    assert.strictEqual(deliv.execution_provider, "mcp");
-    assert.deepStrictEqual(taskResult.output_payload, { digest: "0xdeadbeef", length: 8 }, "task result carries real output");
-    assert.strictEqual(taskResult.invocation_status, "provider_completed");
-  });
-
-// 2. Contract-conformant shape: { output_payload, output_ref, provider_status }
-run("conformant output_payload + output_ref",
-  { externalExecution: { provider: "p", target_id: "tg2", target_response: { output_payload: { answer: 42 }, output_ref: "ref_xyz", provider_status: "ok" } } },
-  ({ deliv, taskResult }) => {
-    assert.deepStrictEqual(deliv.output_payload, { answer: 42 });
-    assert.strictEqual(deliv.output_ref, "ref_xyz");
-    assert.strictEqual(deliv.provider_status, "ok");
-    assert.strictEqual(taskResult.output_ref, "ref_xyz");
-  });
-
-// 3. Bare output field
-run("bare output field",
-  { externalExecution: { provider: "p", target_id: "tg3", target_response: { output: "hello" } } },
-  ({ deliv }) => assert.strictEqual(deliv.output_payload, "hello"));
-
-// 4. No external target -> synthetic path unchanged
-run("no target -> simulated, no output_payload",
-  {},
-  ({ deliv, taskResult }) => {
-    assert.strictEqual(deliv.output_payload, undefined, "no payload when synthetic");
-    assert.strictEqual(taskResult.invocation_status, "simulated");
-    assert.ok(String(deliv.ref).startsWith("deliverable_"), "placeholder ref preserved");
-  });
-
-console.log("verify_execution_surfacing: all execution output-surfacing checks passed");
+"use strict";
+
+// Verifies that when a real execution target runs, its actual output is surfaced
+// into the buyer-facing artifacts (command.deliverables + execution.results_by_task_id)
+// — provider-agnostically across the target response shapes — and that the
+// synthetic ("simulated") path is unchanged when no target runs.
+
+const assert = require("assert");
+const { createCommandArtifacts } = require("../lib/commerce_artifacts");
+
+const basePayload = {
+  command: "command.execute",
+  tasks: [{ task_id: "t1", task_ref: "adapter.mcp.invoke" }],
+  body: { tool_name: "keccak256" }
+};
+const baseQuote = {
+  quote_id: "quote_test1",
+  account_id: "acct_test",
+  amount_minor: 5,
+  currency: "USD_CENTS",
+  settlement_mode: null,
+  integration_ids: [],
+  protocols: ["mcp"],
+  capabilities: [],
+  adapters: ["http"],
+  execution_integration_ids: [],
+  payment_scheme: "exact",
+  payment_protocol: "x402"
+};
+
+function run(label, opts, check) {
+  const out = createCommandArtifacts(basePayload, baseQuote, opts);
+  check({
+    out,
+    deliv: out.command.deliverables[0],
+    taskResult: out.transaction.execution.results_by_task_id.t1
+  });
+  console.log("  ok:", label);
+}
+
+// 1. Nested MCP-executor shape: { result: { output: <real> } }
+run("nested result.output (MCP executor shape)",
+  { externalExecution: { provider: "mcp", target_id: "tg1", target_response: { ok: true, result: { output: { digest: "0xdeadbeef", length: 8 } }, provider_status: "completed" } } },
+  ({ deliv, taskResult }) => {
+    assert.deepStrictEqual(deliv.output_payload, { digest: "0xdeadbeef", length: 8 }, "deliverable carries real output");
+    assert.strictEqual(deliv.invocation_status, "provider_completed");
+    assert.strictEqual(deliv.execution_provider, "mcp");
+    assert.deepStrictEqual(taskResult.output_payload, { digest: "0xdeadbeef", length: 8 }, "task result carries real output");
+    assert.strictEqual(taskResult.invocation_status, "provider_completed");
+  });
+
+// 2. Contract-conformant shape: { output_payload, output_ref, provider_status }
+run("conformant output_payload + output_ref",
+  { externalExecution: { provider: "p", target_id: "tg2", target_response: { output_payload: { answer: 42 }, output_ref: "ref_xyz", provider_status: "ok" } } },
+  ({ deliv, taskResult }) => {
+    assert.deepStrictEqual(deliv.output_payload, { answer: 42 });
+    assert.strictEqual(deliv.output_ref, "ref_xyz");
+    assert.strictEqual(deliv.provider_status, "ok");
+    assert.strictEqual(taskResult.output_ref, "ref_xyz");
+  });
+
+// 3. Bare output field
+run("bare output field",
+  { externalExecution: { provider: "p", target_id: "tg3", target_response: { output: "hello" } } },
+  ({ deliv }) => assert.strictEqual(deliv.output_payload, "hello"));
+
+// 4. No external target -> synthetic path unchanged
+run("no target -> simulated, no output_payload",
+  {},
+  ({ deliv, taskResult }) => {
+    assert.strictEqual(deliv.output_payload, undefined, "no payload when synthetic");
+    assert.strictEqual(taskResult.invocation_status, "simulated");
+    assert.ok(String(deliv.ref).startsWith("deliverable_"), "placeholder ref preserved");
+  });
+
+console.log("verify_execution_surfacing: all execution output-surfacing checks passed");