xytara 3.1.13 → 3.1.14

package/lib/command_flow.js

@@ -1,722 +1,722 @@
-"use strict";
-
-const {
-  createCommandResult,
-  createQuote,
-  hydrateQuoteStates
-} = require("./commerce_runtime");
-const { consumeAccountCredits, buildUsageMeterPreview, previewCreditSpend } = require("./commerce_economics");
-const { resolveSpendCredential, evaluateAuthorityBindingAction } = require("./account_auth");
-const { validateIntegrationSelection } = require("../integrations/dispatch");
-const { markPaymentAccepted, settleDeferredPayment, verifyPaymentAcceptance } = require("./payment_verification");
-const { executeExternalTarget, resolveExecutionTarget } = require("./external_execution_runtime");
-const { externalExecutionBudgetMs } = require("./external_execution_policy");
-const { hashCanonical, issueDeliveryReceipt, loadDeliveryReceiptSigners } = require("./delivery_receipt");
-
-const DELIVERY_RECEIPT_ISSUER = "xytara-runtime";
-const DELIVERY_RECEIPT_RETENTION = 5000;
-
-// The payment leg of a delivery receipt: on-chain facts for x402, the spend record for credits,
-// and the verification mode for any other lane. Never the buyer's signature or secrets.
-function deliveryReceiptPayment(verification, quote) {
-  const v = verification && typeof verification === "object" ? verification : {};
-  const paymentPayload = v.payment_payload && typeof v.payment_payload === "object" ? v.payment_payload : {};
-  if (v.verification_mode === "x402_facilitator") {
-    const settlement = v.settlement && typeof v.settlement === "object" ? v.settlement : null;
-    return {
-      protocol: "x402",
-      scheme: "exact",
-      network: paymentPayload.x402_network || (settlement && settlement.network) || null,
-      asset: paymentPayload.x402_asset || null,
-      amount: paymentPayload.x402_amount !== undefined && paymentPayload.x402_amount !== null ? String(paymentPayload.x402_amount) : null,
-      payer: paymentPayload.x402_payer || (settlement && settlement.payer) || null,
-      pay_to: paymentPayload.x402_pay_to || null,
-      settlement_tx: settlement ? (settlement.transaction || settlement.txid || null) : null,
-      settled: Boolean(settlement && settlement.success !== false && (settlement.transaction || settlement.txid))
-    };
-  }
-  if (v.verification_mode === "account_credits" || paymentPayload.credit_spend_id) {
-    return {
-      protocol: "account_credits",
-      credit_spend_id: paymentPayload.credit_spend_id || null,
-      quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
-      currency: (quote && quote.currency) || null
-    };
-  }
-  return {
-    protocol: v.verification_mode || "unspecified",
-    quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
-    currency: (quote && quote.currency) || null
-  };
-}
-
-// Issues the signed delivery receipt for a completed paid call, attaches it to the response, and
-// keeps it retrievable by id (bounded). Fail-safe: a receipt problem never breaks a completed call.
-function attachDeliveryReceipt(state, result, payload, quote, verification, externalExecutionOptions) {
-  try {
-    if (!result || !result.receipt) return;
-    const execution = externalExecutionOptions && externalExecutionOptions.externalExecution
-      ? externalExecutionOptions.externalExecution
-      : null;
-    const deliverables = result.command && Array.isArray(result.command.deliverables) ? result.command.deliverables : [];
-    const outputs = deliverables.map((deliverable) => (deliverable && deliverable.output_payload !== undefined ? deliverable.output_payload : null));
-    const body = payload && payload.body && typeof payload.body === "object" && !Array.isArray(payload.body) ? payload.body : {};
-    const taskRef = (payload && payload.task_ref)
-      || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
-      || null;
-    const { signers } = loadDeliveryReceiptSigners("XYTARA_DELIVERY_RECEIPT");
-    const deliveryReceipt = issueDeliveryReceipt({
-      receipt_id: `drcpt_${result.receipt.receipt_id.replace(/^rcpt_/, "")}`,
-      issuer: DELIVERY_RECEIPT_ISSUER,
-      call: {
-        quote_id: quote && quote.quote_id ? quote.quote_id : null,
-        transaction_id: result.transaction ? result.transaction.transaction_id : null,
-        runtime_receipt_id: result.receipt.receipt_id,
-        task_ref: taskRef,
-        tool_name: typeof body.tool_name === "string" ? body.tool_name : null
-      },
-      payment: deliveryReceiptPayment(verification, quote),
-      delivery: {
-        status: "completed",
-        provider_id: execution && execution.registered_provider_id ? execution.registered_provider_id : null,
-        routing: execution
-          ? (execution.registered_provider_id ? "open_provider_registry" : "operator_env_target")
-          : "runtime_native",
-        execution_target_id: execution && execution.target_id ? execution.target_id : null,
-        request_sha256: hashCanonical(body),
-        request_hash_input: "the request `body` object (e.g. { tool_name, arguments })",
-        output_sha256: hashCanonical(outputs.length === 1 ? outputs[0] : outputs),
-        output_hash_input: outputs.length === 1
-          ? "command.deliverables[0].output_payload (null when the task returns no payload)"
-          : "the array of command.deliverables[*].output_payload",
-        completed_at: (result.receipt.timing && result.receipt.timing.completed_at_iso) || result.receipt.created_at_iso || null
-      }
-    }, signers);
-    result.delivery_receipt = deliveryReceipt;
-    if (!(state.deliveryReceipts instanceof Map)) state.deliveryReceipts = new Map();
-    state.deliveryReceipts.set(deliveryReceipt.receipt_id, deliveryReceipt);
-    while (state.deliveryReceipts.size > DELIVERY_RECEIPT_RETENTION) {
-      state.deliveryReceipts.delete(state.deliveryReceipts.keys().next().value);
-    }
-  } catch (_) { /* non-fatal: never break a completed, possibly settled call */ }
-}
-const { resolveRegisteredTargets, hasActiveMatchingProvider, recordProviderHealth, recordProviderRouting, recordProviderSettlement } = require("./provider_registry");
-const { claimDeferredExecution, releaseDeferredExecution } = require("./execution_dedupe");
-
-function hasPaymentHeaders(headers, requiredHeaders) {
-  return requiredHeaders.every((headerName) => headers[headerName]);
-}
-
-function parseBearerToken(headers) {
-  const authorization = headers && typeof headers.authorization === "string"
-    ? headers.authorization.trim()
-    : "";
-  const match = authorization.match(/^Bearer\s+(.+)$/i);
-  return match ? match[1].trim() : null;
-}
-
-// Extract an agent-identity proof (for key-bound spend credentials) from request
-// headers: X-Agent-Signature (base64 ed25519 sig) + X-Agent-Timestamp (ms).
-function extractAgentProof(headers) {
-  const h = headers || {};
-  return {
-    signature: typeof h["x-agent-signature"] === "string" ? h["x-agent-signature"] : null,
-    timestamp: typeof h["x-agent-timestamp"] === "string" ? h["x-agent-timestamp"] : null
-  };
-}
-
-function buildCreditCommitPayload(payload, quote, requiredUnits) {
-  return {
-    account_id: quote.account_id,
-    agent_id: payload.agent_id || null,
-    budget_id: payload.budget_id || null,
-    pack_id: payload.pack_id || null,
-    entitlement_id: payload.entitlement_id || null,
-    quote_id: quote.quote_id,
-    task_ref: payload.task_ref || null,
-    workflow_ref: payload.workflow_ref || null,
-    units: requiredUnits,
-    reason: "credit_first_execution"
-  };
-}
-
-function buildCreditRejectionResponse(creditDecision, quote) {
-  const failureReason = creditDecision && creditDecision.credit_spend_preview
-    ? creditDecision.credit_spend_preview.failure_reason
-    : null;
-  const reason = failureReason
-    || (creditDecision && creditDecision.policy_guard && creditDecision.policy_guard.reason)
-    || (creditDecision && creditDecision.entitlement_guard && creditDecision.entitlement_guard.reason)
-    || (creditDecision && creditDecision.reason)
-    || "credit_spend_not_allowed";
-
-  if (reason === "insufficient_credits") {
-    const preview = creditDecision && creditDecision.credit_spend_preview ? creditDecision.credit_spend_preview : {};
-    return {
-      status: 402,
-      payload: {
-        ok: false,
-        reason: "insufficient_credits",
-        insufficient_credits: {
-          account_id: quote.account_id,
-          required_units: preview.required_units,
-          available_units: preview.available_units,
-          recommended_next_surfaces: {
-            credits_topup: "/v1/checkout/purchase-intents",
-            direct_payment: "/v1/payment-quotes"
-          }
-        },
-        quote
-      }
-    };
-  }
-
-  return {
-    status: 403,
-    payload: {
-      ok: false,
-      reason,
-      account_id: quote.account_id,
-      policy_guard: creditDecision && creditDecision.policy_guard ? creditDecision.policy_guard : null,
-      entitlement_guard: creditDecision && creditDecision.entitlement_guard ? creditDecision.entitlement_guard : null,
-      quote
-    }
-  };
-}
-
-// What a provider is allowed to see of the buyer's payment context: the verification outcome and
-// scalar payment facts only. NEVER the signed x402 authorization / deferred-settlement material
-// (that would hand a third-party provider the buyer's signature before settlement), and never
-// signature-, secret- or raw-looking keys or nested objects from any lane's payload.
-const SENSITIVE_CONTEXT_KEY = /signature|secret|private|authorization|raw|base64|header|token/i;
-function sanitizeAuthorizationContextForProvider(context) {
-  if (!context || typeof context !== "object") return null;
-  const payload = context.payment_payload && typeof context.payment_payload === "object" ? context.payment_payload : null;
-  const safePayload = payload
-    ? Object.fromEntries(Object.entries(payload).filter(([key, value]) => !SENSITIVE_CONTEXT_KEY.test(key) && (value === null || typeof value !== "object")))
-    : null;
-  return {
-    ok: context.ok === true,
-    verification_mode: context.verification_mode || null,
-    wallet_id: context.wallet_id || null,
-    age_seconds: Number.isFinite(Number(context.age_seconds)) ? Number(context.age_seconds) : null,
-    payment_payload: safePayload
-  };
-}
-
-async function buildExternalExecutionOptions(state, payload, quote, authorizationContext) {
-  // One wall-clock budget for the whole call (every retry of every candidate), inside the x402
-  // authorization window — see external_execution_policy.js.
-  const executionOptions = { deadline_ms: Date.now() + externalExecutionBudgetMs() };
-  const forwardedContext = sanitizeAuthorizationContextForProvider(authorizationContext);
-  // Operator-pinned env target resolves first and is used as-is (an explicit single target,
-  // no failover). Empty env + empty registry -> {} (unchanged behavior).
-  const envTarget = resolveExecutionTarget(payload, quote);
-  if (envTarget) {
-    const execution = await executeExternalTarget(envTarget, payload, quote, forwardedContext, executionOptions);
-    if (!execution || !execution.ok) {
-      return { error: execution || { ok: false, status: 502, reason: "external_execution_failed" } };
-    }
-    return { externalExecution: execution };
-  }
-
-  // Open-network path: try health-ranked registered providers (healthy first, then half-open)
-  // in order, FAILING OVER to the next when one is down — so a single unhealthy/throttled
-  // provider doesn't fail the buyer when another serves the same capability. Each attempt
-  // updates the provider's health; accounting is wrapped so it can never break execution.
-  const candidates = resolveRegisteredTargets(state, payload, quote);
-  if (candidates.length < 1) {
-    // No HEALTHY candidate. If providers DO serve this capability but are all in cooldown,
-    // fail closed (503) so the buyer is NOT charged for undelivered work — rather than falling
-    // through to the synthetic no-op. If nothing serves it, keep the legacy local path ({}).
-    if (hasActiveMatchingProvider(state, payload, quote)) {
-      return { error: { ok: false, status: 503, reason: "no_healthy_provider" } };
-    }
-    return {};
-  }
-  let lastError = null;
-  for (const target of candidates) {
-    if (Date.now() >= executionOptions.deadline_ms) {
-      // Budget spent on earlier candidates: stop here rather than start a call that cannot settle.
-      lastError = lastError || { ok: false, status: 504, reason: "external_execution_budget_exhausted" };
-      break;
-    }
-    const execution = await executeExternalTarget(target, payload, quote, forwardedContext, executionOptions);
-    try { recordProviderRouting(state, target.registered_provider_id); } catch (_) { /* non-fatal */ }
-    if (execution && execution.ok) {
-      try { recordProviderHealth(state, target.registered_provider_id, { ok: true }); } catch (_) { /* non-fatal */ }
-      execution.registered_provider_id = target.registered_provider_id;
-      return { externalExecution: execution };
-    }
-    try { recordProviderHealth(state, target.registered_provider_id, { ok: false }); } catch (_) { /* non-fatal */ }
-    lastError = execution || { ok: false, status: 502, reason: "external_execution_failed" };
-    // Fail over to the NEXT provider ONLY when this one provably did NOT process the request
-    // (rejected / unreachable). Never on an ambiguous failure (timeout, reset, 5xx) — that
-    // could make a side-effectful provider execute twice. Health still marks the failure.
-    if (!(execution && execution.failover_safe)) break;
-  }
-  return { error: lastError };
-}
-
-// Assets the x402 lane can settle in, with their on-chain decimals (needed to turn settled base
-// units into the ledger's cents). Anything else cannot be reconciled and must not accrue on the quote.
-const X402_ASSET_DECIMALS = new Map([
-  ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", 6], // USDC, Base mainnet (eip155:8453)
-  ["0x036cbd53842c5426634e7929541ec2318f3dcf7e", 6]  // USDC, Base Sepolia (eip155:84532)
-]);
-
-// The amount a provider's revenue share is computed from. The quote is what we ASKED for; on the
-// x402 lane the facilitator settles exactly the advertised `accepts` amount, which may differ from
-// the catalog quote — so accrue on min(quote, settled) and never on money that was not collected.
-// Other lanes bind the paid amount to the quote at verification time (local_signed) or charge the
-// quote directly (credits / hosted checkout), so the quote is the settled amount there.
-function reconcileProviderSettlementAmount(quote, verification) {
-  const quoted = quote && Number.isFinite(Number(quote.amount_minor)) ? Math.max(0, Math.round(Number(quote.amount_minor))) : 0;
-  const mode = verification && typeof verification.verification_mode === "string" ? verification.verification_mode : null;
-  if (mode !== "x402_facilitator") {
-    return { amount_minor: quoted, quoted_minor: quoted, settled_minor: null, settlement_basis: mode ? `${mode}_quote` : "quote", reconciled: true };
-  }
-  const paymentPayload = (verification && verification.payment_payload) || {};
-  const decimals = X402_ASSET_DECIMALS.get(String(paymentPayload.x402_asset || "").toLowerCase());
-  const baseUnits = /^\d{1,30}$/.test(String(paymentPayload.x402_amount)) ? Number(paymentPayload.x402_amount) : NaN;
-  const centsCurrency = /^USD(_CENTS)?$/i.test(String((quote && quote.currency) || "USD_CENTS"));
-  if (decimals === undefined || !Number.isFinite(baseUnits) || !centsCurrency) {
-    return { amount_minor: 0, quoted_minor: quoted, settled_minor: null, settlement_basis: "x402_unreconciled_asset", reconciled: false };
-  }
-  const settledCents = Math.floor(baseUnits / Math.pow(10, decimals - 2));
-  return { amount_minor: Math.min(quoted, settledCents), quoted_minor: quoted, settled_minor: settledCents, settlement_basis: "x402_settled_min_quote", reconciled: true };
-}
-
-// Records the provider revenue-share split for a settled call routed to a registered
-// provider. Fail-safe: metering must NEVER break or reverse a settled/charged response.
-function attributeProviderSettlement(state, externalExecutionOptions, payload, quote, extra, verification) {
-  const execution = externalExecutionOptions && externalExecutionOptions.externalExecution;
-  const providerId = execution && execution.registered_provider_id;
-  if (!providerId) return;
-  try {
-    const taskRef = (payload && payload.task_ref)
-      || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
-      || null;
-    const reconciled = reconcileProviderSettlementAmount(quote, verification);
-    recordProviderSettlement(state, {
-      provider_id: providerId,
-      amount_minor: reconciled.amount_minor,
-      quoted_minor: reconciled.quoted_minor,
-      settled_minor: reconciled.settled_minor,
-      settlement_basis: reconciled.settlement_basis,
-      reconciled: reconciled.reconciled,
-      currency: quote && quote.currency ? quote.currency : null,
-      transaction_id: (extra && extra.transaction_id) || (quote && quote.quote_id) || null,
-      settlement_ref: (extra && extra.settlement_ref) || null,
-      task_ref: taskRef
-    });
-  } catch (_) { /* non-fatal: a settled call is never undone by an accounting error */ }
-}
-
-async function executeCommandRequest(state, payload, headers, options) {
-  const opts = options || {};
-  const requiredHeaders = Array.isArray(opts.requiredHeaders) && opts.requiredHeaders.length > 0
-    ? opts.requiredHeaders
-    : ["x-wallet-id", "x-payment", "x-payment-signature"];
-  const challengePayload = typeof opts.challengePayload === "function"
-    ? opts.challengePayload
-    : (quote) => ({ ok: false, quote });
-
-  hydrateQuoteStates(state);
-  const validation = validateIntegrationSelection(payload);
-  if (!validation.ok) {
-    return {
-      status: 400,
-      payload: {
-        ok: false,
-        reason: validation.reason,
-        errors: validation.errors,
-        selection: validation.selection
-      }
-    };
-  }
-  const prefersCredits = payload && payload.payment_preference === "credits_first";
-  if (!hasPaymentHeaders(headers || {}, requiredHeaders)) {
-    const bearerToken = parseBearerToken(headers);
-    const delegatedSpendRequested = typeof bearerToken === "string" && bearerToken.startsWith("xytara_spend_");
-    const delegatedSpend = delegatedSpendRequested
-      ? resolveSpendCredential(state, bearerToken, extractAgentProof(headers), {
-          account_id: payload && payload.account_id,
-          task_ref: payload && payload.task_ref,
-          units: payload && payload.quoted_units,
-          // Strict binding is scoped to this execute path (where a binding is supplied); the
-          // lifecycle paths pass no binding and are intentionally unaffected.
-          require: String(process.env.XYTARA_REQUIRE_SPEND_PROOF_BINDING || "").trim() === "1"
-        })
-      : { ok: false, reason: "spend_credential_not_requested" };
-    if (delegatedSpendRequested && !delegatedSpend.ok) {
-      return {
-        status: 403,
-        payload: {
-          ok: false,
-          reason: delegatedSpend.reason
-        }
-      };
-    }
-    if (delegatedSpend.ok) {
-      // Pin the command to the credential's own account — a delegated spend token must
-      // never be aimed at another account by supplying a different account_id.
-      if (payload && typeof payload.account_id === "string" && payload.account_id && payload.account_id !== delegatedSpend.credential.account_id) {
-        return { status: 403, payload: { ok: false, reason: "delegated_account_mismatch" } };
-      }
-      payload = {
-        ...payload,
-        account_id: delegatedSpend.credential.account_id,
-        agent_id: payload && payload.agent_id ? payload.agent_id : delegatedSpend.credential.agent_id,
-        budget_id: payload && payload.budget_id ? payload.budget_id : delegatedSpend.credential.budget_id,
-        pack_id: delegatedSpend.credential.pack_id || (payload && payload.pack_id) || null,
-        entitlement_id: delegatedSpend.credential.entitlement_id || (payload && payload.entitlement_id) || null
-      };
-    }
-    const quote = createQuote(state, payload);
-    if (prefersCredits) {
-      const creditPayload = {
-        ...payload,
-        account_id: quote.account_id,
-        quoted_units: Number.isFinite(Number(payload.quoted_units)) ? Number(payload.quoted_units) : undefined
-      };
-      const meteringPreview = buildUsageMeterPreview(state, creditPayload);
-      const requiredUnits = meteringPreview.usage_units;
-      if (delegatedSpend.ok && delegatedSpend.binding) {
-        const authorityDecision = evaluateAuthorityBindingAction(delegatedSpend.binding, "delegated_credit_spend", requiredUnits);
-        if (!authorityDecision.ok) {
-          return {
-            status: 403,
-            payload: {
-              ok: false,
-              reason: authorityDecision.reason,
-              binding_id: authorityDecision.binding_id || null,
-              required_scope: authorityDecision.required_scope || null,
-              authority_scope: authorityDecision.authority_scope || [],
-              required_consequence_family: authorityDecision.required_consequence_family || null,
-              allowed_consequence_families: authorityDecision.allowed_consequence_families || [],
-              max_units: authorityDecision.max_units || null,
-              attempted_units: authorityDecision.attempted_units || requiredUnits
-            }
-          };
-        }
-      }
-
-      const creditDecision = previewCreditSpend(state, creditPayload);
-      if (!creditDecision.ok || !creditDecision.credit_spend_preview || creditDecision.credit_spend_preview.executable_now !== true) {
-        return buildCreditRejectionResponse(creditDecision, quote);
-      }
-
-      const preCommitAuthorizationContext = delegatedSpend.ok
-        ? delegatedSpend.authorization_context
-        : {
-            ok: true,
-            verification_mode: "account_credits",
-            wallet_id: quote.account_id,
-            age_seconds: 0,
-            payment_payload: {
-              credit_spend_status: "precommit"
-            }
-          };
-      const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, preCommitAuthorizationContext);
-      if (externalExecutionOptions.error) {
-        return {
-          status: externalExecutionOptions.error.status || 502,
-          payload: {
-            ok: false,
-            reason: externalExecutionOptions.error.reason || "external_execution_failed",
-            details: externalExecutionOptions.error.details || null,
-            credit_spend_status: "not_committed",
-            credit_spend_preview: creditDecision.credit_spend_preview,
-            quote
-          }
-        };
-      }
-
-      const creditSpend = consumeAccountCredits(state, buildCreditCommitPayload(payload, quote, requiredUnits));
-      if (creditSpend.ok) {
-        const paymentVerification = {
-          ...(delegatedSpend.ok
-            ? delegatedSpend.authorization_context
-            : {
-                ok: true,
-                verification_mode: "account_credits",
-                wallet_id: quote.account_id,
-                age_seconds: 0,
-                payment_payload: {}
-              }),
-          payment_payload: {
-            ...((delegatedSpend.ok && delegatedSpend.authorization_context && delegatedSpend.authorization_context.payment_payload) || {}),
-            credit_spend_id: creditSpend.credit_spend.credit_spend_id
-          }
-        };
-        attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
-          transaction_id: creditSpend.credit_spend.credit_spend_id
-        }, paymentVerification);
-        const creditResult = createCommandResult(state, {
-          ...payload,
-          payment_preference: "credits_first"
-        }, quote, {
-          paymentVerification,
-          creditSpend: creditSpend.credit_spend,
-          skipPaymentLedger: true,
-          externalExecution: externalExecutionOptions.externalExecution || null
-        });
-        attachDeliveryReceipt(state, creditResult, payload, quote, paymentVerification, externalExecutionOptions);
-        return {
-          status: 200,
-          payload: creditResult
-        };
-      }
-      if (creditSpend.reason !== "insufficient_credits") {
-        return {
-          status: 403,
-          payload: {
-            ok: false,
-            reason: creditSpend.reason,
-            account_id: quote.account_id,
-            provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
-            policy_guard: {
-              agent_id: creditSpend.agent_id || null,
-              budget_id: creditSpend.budget_id || null,
-              task_domain: creditSpend.task_domain || null,
-              policy_ref: creditSpend.policy_ref || null,
-              max_reserve_units: creditSpend.max_reserve_units || null,
-              allowed_job_domains: creditSpend.allowed_job_domains || null,
-              budget_status: creditSpend.budget_status || null,
-              agent_status: creditSpend.agent_status || null
-            },
-            quote
-          }
-        };
-      }
-      return {
-        status: 402,
-        payload: {
-          ok: false,
-          reason: "insufficient_credits",
-          provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
-          insufficient_credits: {
-            account_id: quote.account_id,
-            required_units: creditSpend.required_units,
-            available_units: creditSpend.available_units,
-            recommended_next_surfaces: {
-              credits_topup: "/v1/checkout/purchase-intents",
-              direct_payment: "/v1/payment-quotes"
-            }
-          },
-          quote
-        }
-      };
-    }
-    return {
-      status: 402,
-      payload: await challengePayload(quote)
-    };
-  }
-
-  const quote = payload.quote_id && state.quotes.get(payload.quote_id)
-    ? state.quotes.get(payload.quote_id)
-    : createQuote(state, payload);
-
-  if (quote && quote.status === "expired") {
-    return {
-      status: 409,
-      payload: {
-        ok: false,
-        reason: "quote_expired",
-        quote
-      }
-    };
-  }
-
-  if (quote && (quote.status === "executed" || quote.status === "accepted")) {
-    return {
-      status: 409,
-      payload: {
-        ok: false,
-        reason: "quote_already_used",
-        quote
-      }
-    };
-  }
-
-  // Verify-execute-settle: for the x402 facilitator path, settlement is DEFERRED
-  // until execution succeeds, so a failed call never settles/charges. Other paths
-  // (native/credits, and the external rails L402/BOLT/MPP whose funds already moved
-  // before the proof) have nothing to defer and are unaffected.
-  const paymentVerification = await verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote, {
-    payment_protocol: opts.paymentProtocol || (payload && payload.payment_protocol) || null,
-    authorization_scheme: opts.authorizationScheme || null,
-    resource_url: opts.resourceUrl || null,
-    deferSettlement: true
-  });
-  if (!paymentVerification.ok) {
-    return {
-      status: paymentVerification.status || 403,
-      payload: {
-        ok: false,
-        reason: paymentVerification.reason,
-        ...(paymentVerification.detail ? { detail: paymentVerification.detail } : {}),
-        quote
-      }
-    };
-  }
-
-  markPaymentAccepted(state, paymentVerification);
-  const settlementDeferred = Boolean(paymentVerification.deferred_settlement);
-
-  // Reserve an execution slot so the same signed x402 authorization cannot execute
-  // twice concurrently (the deferred settle no longer fronts the on-chain nonce as an
-  // implicit pre-execution guard). No-op for non-deferred lanes; fails open if the
-  // store is unavailable. The slot is released in the finally below, whatever happens.
-  const executionClaim = claimDeferredExecution(state, paymentVerification);
-  if (!executionClaim.ok) {
-    return {
-      status: executionClaim.status || 409,
-      payload: {
-        ok: false,
-        reason: executionClaim.reason || "payment_authorization_in_progress",
-        ...(executionClaim.detail ? { detail: executionClaim.detail } : {}),
-        payment_settled: false,
-        quote
-      }
-    };
-  }
-
-  try {
-    const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, paymentVerification);
-    if (externalExecutionOptions.error) {
-      // Execution failed. Report the money state by what actually happened, not by lane:
-      //  - deferred x402: we never settled, so the caller is NOT charged.
-      //  - a concrete receipt is in hand (an x402 settlement already captured): the caller
-      //    WAS charged, so surface the receipt and a refund path.
-      //  - everything else (native/local_signed, presence, and the access-token rails
-      //    whose proof we only validated): no receipt was produced on this request, so we
-      //    do not claim a charge — a bare retry hint, never a false refund pointer.
-      const hasReceipt = Boolean(paymentVerification.settlement || paymentVerification.payment_response_base64);
-      return {
-        status: externalExecutionOptions.error.status || 502,
-        payload: {
-          ok: false,
-          reason: externalExecutionOptions.error.reason || "external_execution_failed",
-          details: externalExecutionOptions.error.details || null,
-          payment_settled: hasReceipt,
-          ...(paymentVerification.settlement ? { settlement: paymentVerification.settlement } : {}),
-          remediation: settlementDeferred
-            ? "execution failed before settlement; you were not charged — retry with corrected input"
-            : hasReceipt
-              ? "payment was accepted but execution failed; retry with corrected input or request a refund with your payment proof"
-              : "execution failed; retry with corrected input",
-          quote
-        },
-        ...(hasReceipt && paymentVerification.payment_response_base64
-          ? { paymentResponse: paymentVerification.payment_response_base64 }
-          : {})
-      };
-    }
-
-    // Execution succeeded — settle the deferred payment now (no-op for non-deferred).
-    const settleResult = await settleDeferredPayment(paymentVerification);
-    if (!settleResult.ok) {
-      return {
-        status: settleResult.status || 402,
-        payload: {
-          ok: false,
-          reason: settleResult.reason || "settlement_failed",
-          ...(settleResult.detail ? { detail: settleResult.detail } : {}),
-          payment_settled: false,
-          remediation: "the work executed but settlement failed; you were not charged — retry",
-          quote
-        }
-      };
-    }
-    // settleDeferredPayment is a no-op for non-deferred paths (returns {ok:true} with no
-    // settlement) — in that case keep the verification untouched; only when a deferred
-    // x402 settlement actually ran do we fold its receipt in and drop the deferred marker.
-    const settlementOccurred = Boolean(settleResult.settlement || settleResult.payment_response_base64);
-    const settledVerification = settlementOccurred
-      ? { ...paymentVerification, settlement: settleResult.settlement, payment_response_base64: settleResult.payment_response_base64, deferred_settlement: undefined }
-      : paymentVerification;
-
-    attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
-      settlement_ref: (settledVerification.settlement && (settledVerification.settlement.transaction || settledVerification.settlement.txid)) || null
-    }, settledVerification);
-    const paidResult = createCommandResult(state, payload, quote, {
-      paymentVerification: settledVerification,
-      externalExecution: externalExecutionOptions.externalExecution || null
-    });
-    attachDeliveryReceipt(state, paidResult, payload, quote, settledVerification, externalExecutionOptions);
-    return {
-      status: 200,
-      payload: paidResult,
-      ...(settledVerification.payment_response_base64
-        ? { paymentResponse: settledVerification.payment_response_base64 }
-        : {})
-    };
-  } finally {
-    releaseDeferredExecution(state, executionClaim.key);
-  }
-}
-
-async function executeAuthorizedCommandRequest(state, payload, authorizationContext) {
-  const validation = validateIntegrationSelection(payload);
-  if (!validation.ok) {
-    return {
-      status: 400,
-      payload: {
-        ok: false,
-        reason: validation.reason,
-        errors: validation.errors,
-        selection: validation.selection
-      }
-    };
-  }
-
-  hydrateQuoteStates(state);
-
-  const quote = createQuote(state, payload);
-  const paymentVerification = {
-    ok: true,
-    verification_mode: authorizationContext && authorizationContext.verification_mode
-      ? authorizationContext.verification_mode
-      : "hosted_checkout",
-    wallet_id: authorizationContext && authorizationContext.wallet_id
-      ? authorizationContext.wallet_id
-      : "hosted_checkout",
-    age_seconds: 0,
-    payment_payload: authorizationContext && authorizationContext.payment_payload
-      ? authorizationContext.payment_payload
-      : null
-  };
-  const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, paymentVerification);
-  if (externalExecutionOptions.error) {
-    return {
-      status: externalExecutionOptions.error.status || 502,
-      payload: {
-        ok: false,
-        reason: externalExecutionOptions.error.reason || "external_execution_failed",
-        details: externalExecutionOptions.error.details || null
-      }
-    };
-  }
-
-  attributeProviderSettlement(state, externalExecutionOptions, payload, quote, undefined, paymentVerification);
-  const authorizedResult = createCommandResult(state, payload, quote, {
-    paymentVerification,
-    externalExecution: externalExecutionOptions.externalExecution || null
-  });
-  attachDeliveryReceipt(state, authorizedResult, payload, quote, paymentVerification, externalExecutionOptions);
-  return {
-    status: 200,
-    payload: authorizedResult
-  };
-}
-
-module.exports = {
-  executeAuthorizedCommandRequest,
-  executeCommandRequest,
-  buildExternalExecutionOptions,
-  reconcileProviderSettlementAmount,
-  sanitizeAuthorizationContextForProvider
-};
+"use strict";
+
+const {
+  createCommandResult,
+  createQuote,
+  hydrateQuoteStates
+} = require("./commerce_runtime");
+const { consumeAccountCredits, buildUsageMeterPreview, previewCreditSpend } = require("./commerce_economics");
+const { resolveSpendCredential, evaluateAuthorityBindingAction } = require("./account_auth");
+const { validateIntegrationSelection } = require("../integrations/dispatch");
+const { markPaymentAccepted, settleDeferredPayment, verifyPaymentAcceptance } = require("./payment_verification");
+const { executeExternalTarget, resolveExecutionTarget } = require("./external_execution_runtime");
+const { externalExecutionBudgetMs } = require("./external_execution_policy");
+const { hashCanonical, issueDeliveryReceipt, loadDeliveryReceiptSigners } = require("./delivery_receipt");
+
+const DELIVERY_RECEIPT_ISSUER = "xytara-runtime";
+const DELIVERY_RECEIPT_RETENTION = 5000;
+
+// The payment leg of a delivery receipt: on-chain facts for x402, the spend record for credits,
+// and the verification mode for any other lane. Never the buyer's signature or secrets.
+function deliveryReceiptPayment(verification, quote) {
+  const v = verification && typeof verification === "object" ? verification : {};
+  const paymentPayload = v.payment_payload && typeof v.payment_payload === "object" ? v.payment_payload : {};
+  if (v.verification_mode === "x402_facilitator") {
+    const settlement = v.settlement && typeof v.settlement === "object" ? v.settlement : null;
+    return {
+      protocol: "x402",
+      scheme: "exact",
+      network: paymentPayload.x402_network || (settlement && settlement.network) || null,
+      asset: paymentPayload.x402_asset || null,
+      amount: paymentPayload.x402_amount !== undefined && paymentPayload.x402_amount !== null ? String(paymentPayload.x402_amount) : null,
+      payer: paymentPayload.x402_payer || (settlement && settlement.payer) || null,
+      pay_to: paymentPayload.x402_pay_to || null,
+      settlement_tx: settlement ? (settlement.transaction || settlement.txid || null) : null,
+      settled: Boolean(settlement && settlement.success !== false && (settlement.transaction || settlement.txid))
+    };
+  }
+  if (v.verification_mode === "account_credits" || paymentPayload.credit_spend_id) {
+    return {
+      protocol: "account_credits",
+      credit_spend_id: paymentPayload.credit_spend_id || null,
+      quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
+      currency: (quote && quote.currency) || null
+    };
+  }
+  return {
+    protocol: v.verification_mode || "unspecified",
+    quoted_amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : null,
+    currency: (quote && quote.currency) || null
+  };
+}
+
+// Issues the signed delivery receipt for a completed paid call, attaches it to the response, and
+// keeps it retrievable by id (bounded). Fail-safe: a receipt problem never breaks a completed call.
+function attachDeliveryReceipt(state, result, payload, quote, verification, externalExecutionOptions) {
+  try {
+    if (!result || !result.receipt) return;
+    const execution = externalExecutionOptions && externalExecutionOptions.externalExecution
+      ? externalExecutionOptions.externalExecution
+      : null;
+    const deliverables = result.command && Array.isArray(result.command.deliverables) ? result.command.deliverables : [];
+    const outputs = deliverables.map((deliverable) => (deliverable && deliverable.output_payload !== undefined ? deliverable.output_payload : null));
+    const body = payload && payload.body && typeof payload.body === "object" && !Array.isArray(payload.body) ? payload.body : {};
+    const taskRef = (payload && payload.task_ref)
+      || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
+      || null;
+    const { signers } = loadDeliveryReceiptSigners("XYTARA_DELIVERY_RECEIPT");
+    const deliveryReceipt = issueDeliveryReceipt({
+      receipt_id: `drcpt_${result.receipt.receipt_id.replace(/^rcpt_/, "")}`,
+      issuer: DELIVERY_RECEIPT_ISSUER,
+      call: {
+        quote_id: quote && quote.quote_id ? quote.quote_id : null,
+        transaction_id: result.transaction ? result.transaction.transaction_id : null,
+        runtime_receipt_id: result.receipt.receipt_id,
+        task_ref: taskRef,
+        tool_name: typeof body.tool_name === "string" ? body.tool_name : null
+      },
+      payment: deliveryReceiptPayment(verification, quote),
+      delivery: {
+        status: "completed",
+        provider_id: execution && execution.registered_provider_id ? execution.registered_provider_id : null,
+        routing: execution
+          ? (execution.registered_provider_id ? "open_provider_registry" : "operator_env_target")
+          : "runtime_native",
+        execution_target_id: execution && execution.target_id ? execution.target_id : null,
+        request_sha256: hashCanonical(body),
+        request_hash_input: "the request `body` object (e.g. { tool_name, arguments })",
+        output_sha256: hashCanonical(outputs.length === 1 ? outputs[0] : outputs),
+        output_hash_input: outputs.length === 1
+          ? "command.deliverables[0].output_payload (null when the task returns no payload)"
+          : "the array of command.deliverables[*].output_payload",
+        completed_at: (result.receipt.timing && result.receipt.timing.completed_at_iso) || result.receipt.created_at_iso || null
+      }
+    }, signers);
+    result.delivery_receipt = deliveryReceipt;
+    if (!(state.deliveryReceipts instanceof Map)) state.deliveryReceipts = new Map();
+    state.deliveryReceipts.set(deliveryReceipt.receipt_id, deliveryReceipt);
+    while (state.deliveryReceipts.size > DELIVERY_RECEIPT_RETENTION) {
+      state.deliveryReceipts.delete(state.deliveryReceipts.keys().next().value);
+    }
+  } catch (_) { /* non-fatal: never break a completed, possibly settled call */ }
+}
+const { resolveRegisteredTargets, hasActiveMatchingProvider, recordProviderHealth, recordProviderRouting, recordProviderSettlement } = require("./provider_registry");
+const { claimDeferredExecution, releaseDeferredExecution } = require("./execution_dedupe");
+
+function hasPaymentHeaders(headers, requiredHeaders) {
+  return requiredHeaders.every((headerName) => headers[headerName]);
+}
+
+function parseBearerToken(headers) {
+  const authorization = headers && typeof headers.authorization === "string"
+    ? headers.authorization.trim()
+    : "";
+  const match = authorization.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : null;
+}
+
+// Extract an agent-identity proof (for key-bound spend credentials) from request
+// headers: X-Agent-Signature (base64 ed25519 sig) + X-Agent-Timestamp (ms).
+function extractAgentProof(headers) {
+  const h = headers || {};
+  return {
+    signature: typeof h["x-agent-signature"] === "string" ? h["x-agent-signature"] : null,
+    timestamp: typeof h["x-agent-timestamp"] === "string" ? h["x-agent-timestamp"] : null
+  };
+}
+
+function buildCreditCommitPayload(payload, quote, requiredUnits) {
+  return {
+    account_id: quote.account_id,
+    agent_id: payload.agent_id || null,
+    budget_id: payload.budget_id || null,
+    pack_id: payload.pack_id || null,
+    entitlement_id: payload.entitlement_id || null,
+    quote_id: quote.quote_id,
+    task_ref: payload.task_ref || null,
+    workflow_ref: payload.workflow_ref || null,
+    units: requiredUnits,
+    reason: "credit_first_execution"
+  };
+}
+
+function buildCreditRejectionResponse(creditDecision, quote) {
+  const failureReason = creditDecision && creditDecision.credit_spend_preview
+    ? creditDecision.credit_spend_preview.failure_reason
+    : null;
+  const reason = failureReason
+    || (creditDecision && creditDecision.policy_guard && creditDecision.policy_guard.reason)
+    || (creditDecision && creditDecision.entitlement_guard && creditDecision.entitlement_guard.reason)
+    || (creditDecision && creditDecision.reason)
+    || "credit_spend_not_allowed";
+
+  if (reason === "insufficient_credits") {
+    const preview = creditDecision && creditDecision.credit_spend_preview ? creditDecision.credit_spend_preview : {};
+    return {
+      status: 402,
+      payload: {
+        ok: false,
+        reason: "insufficient_credits",
+        insufficient_credits: {
+          account_id: quote.account_id,
+          required_units: preview.required_units,
+          available_units: preview.available_units,
+          recommended_next_surfaces: {
+            credits_topup: "/v1/checkout/purchase-intents",
+            direct_payment: "/v1/payment-quotes"
+          }
+        },
+        quote
+      }
+    };
+  }
+
+  return {
+    status: 403,
+    payload: {
+      ok: false,
+      reason,
+      account_id: quote.account_id,
+      policy_guard: creditDecision && creditDecision.policy_guard ? creditDecision.policy_guard : null,
+      entitlement_guard: creditDecision && creditDecision.entitlement_guard ? creditDecision.entitlement_guard : null,
+      quote
+    }
+  };
+}
+
+// What a provider is allowed to see of the buyer's payment context: the verification outcome and
+// scalar payment facts only. NEVER the signed x402 authorization / deferred-settlement material
+// (that would hand a third-party provider the buyer's signature before settlement), and never
+// signature-, secret- or raw-looking keys or nested objects from any lane's payload.
+const SENSITIVE_CONTEXT_KEY = /signature|secret|private|authorization|raw|base64|header|token/i;
+function sanitizeAuthorizationContextForProvider(context) {
+  if (!context || typeof context !== "object") return null;
+  const payload = context.payment_payload && typeof context.payment_payload === "object" ? context.payment_payload : null;
+  const safePayload = payload
+    ? Object.fromEntries(Object.entries(payload).filter(([key, value]) => !SENSITIVE_CONTEXT_KEY.test(key) && (value === null || typeof value !== "object")))
+    : null;
+  return {
+    ok: context.ok === true,
+    verification_mode: context.verification_mode || null,
+    wallet_id: context.wallet_id || null,
+    age_seconds: Number.isFinite(Number(context.age_seconds)) ? Number(context.age_seconds) : null,
+    payment_payload: safePayload
+  };
+}
+
+async function buildExternalExecutionOptions(state, payload, quote, authorizationContext) {
+  // One wall-clock budget for the whole call (every retry of every candidate), inside the x402
+  // authorization window — see external_execution_policy.js.
+  const executionOptions = { deadline_ms: Date.now() + externalExecutionBudgetMs() };
+  const forwardedContext = sanitizeAuthorizationContextForProvider(authorizationContext);
+  // Operator-pinned env target resolves first and is used as-is (an explicit single target,
+  // no failover). Empty env + empty registry -> {} (unchanged behavior).
+  const envTarget = resolveExecutionTarget(payload, quote);
+  if (envTarget) {
+    const execution = await executeExternalTarget(envTarget, payload, quote, forwardedContext, executionOptions);
+    if (!execution || !execution.ok) {
+      return { error: execution || { ok: false, status: 502, reason: "external_execution_failed" } };
+    }
+    return { externalExecution: execution };
+  }
+
+  // Open-network path: try health-ranked registered providers (healthy first, then half-open)
+  // in order, FAILING OVER to the next when one is down — so a single unhealthy/throttled
+  // provider doesn't fail the buyer when another serves the same capability. Each attempt
+  // updates the provider's health; accounting is wrapped so it can never break execution.
+  const candidates = resolveRegisteredTargets(state, payload, quote);
+  if (candidates.length < 1) {
+    // No HEALTHY candidate. If providers DO serve this capability but are all in cooldown,
+    // fail closed (503) so the buyer is NOT charged for undelivered work — rather than falling
+    // through to the synthetic no-op. If nothing serves it, keep the legacy local path ({}).
+    if (hasActiveMatchingProvider(state, payload, quote)) {
+      return { error: { ok: false, status: 503, reason: "no_healthy_provider" } };
+    }
+    return {};
+  }
+  let lastError = null;
+  for (const target of candidates) {
+    if (Date.now() >= executionOptions.deadline_ms) {
+      // Budget spent on earlier candidates: stop here rather than start a call that cannot settle.
+      lastError = lastError || { ok: false, status: 504, reason: "external_execution_budget_exhausted" };
+      break;
+    }
+    const execution = await executeExternalTarget(target, payload, quote, forwardedContext, executionOptions);
+    try { recordProviderRouting(state, target.registered_provider_id); } catch (_) { /* non-fatal */ }
+    if (execution && execution.ok) {
+      try { recordProviderHealth(state, target.registered_provider_id, { ok: true }); } catch (_) { /* non-fatal */ }
+      execution.registered_provider_id = target.registered_provider_id;
+      return { externalExecution: execution };
+    }
+    try { recordProviderHealth(state, target.registered_provider_id, { ok: false }); } catch (_) { /* non-fatal */ }
+    lastError = execution || { ok: false, status: 502, reason: "external_execution_failed" };
+    // Fail over to the NEXT provider ONLY when this one provably did NOT process the request
+    // (rejected / unreachable). Never on an ambiguous failure (timeout, reset, 5xx) — that
+    // could make a side-effectful provider execute twice. Health still marks the failure.
+    if (!(execution && execution.failover_safe)) break;
+  }
+  return { error: lastError };
+}
+
+// Assets the x402 lane can settle in, with their on-chain decimals (needed to turn settled base
+// units into the ledger's cents). Anything else cannot be reconciled and must not accrue on the quote.
+const X402_ASSET_DECIMALS = new Map([
+  ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", 6], // USDC, Base mainnet (eip155:8453)
+  ["0x036cbd53842c5426634e7929541ec2318f3dcf7e", 6]  // USDC, Base Sepolia (eip155:84532)
+]);
+
+// The amount a provider's revenue share is computed from. The quote is what we ASKED for; on the
+// x402 lane the facilitator settles exactly the advertised `accepts` amount, which may differ from
+// the catalog quote — so accrue on min(quote, settled) and never on money that was not collected.
+// Other lanes bind the paid amount to the quote at verification time (local_signed) or charge the
+// quote directly (credits / hosted checkout), so the quote is the settled amount there.
+function reconcileProviderSettlementAmount(quote, verification) {
+  const quoted = quote && Number.isFinite(Number(quote.amount_minor)) ? Math.max(0, Math.round(Number(quote.amount_minor))) : 0;
+  const mode = verification && typeof verification.verification_mode === "string" ? verification.verification_mode : null;
+  if (mode !== "x402_facilitator") {
+    return { amount_minor: quoted, quoted_minor: quoted, settled_minor: null, settlement_basis: mode ? `${mode}_quote` : "quote", reconciled: true };
+  }
+  const paymentPayload = (verification && verification.payment_payload) || {};
+  const decimals = X402_ASSET_DECIMALS.get(String(paymentPayload.x402_asset || "").toLowerCase());
+  const baseUnits = /^\d{1,30}$/.test(String(paymentPayload.x402_amount)) ? Number(paymentPayload.x402_amount) : NaN;
+  const centsCurrency = /^USD(_CENTS)?$/i.test(String((quote && quote.currency) || "USD_CENTS"));
+  if (decimals === undefined || !Number.isFinite(baseUnits) || !centsCurrency) {
+    return { amount_minor: 0, quoted_minor: quoted, settled_minor: null, settlement_basis: "x402_unreconciled_asset", reconciled: false };
+  }
+  const settledCents = Math.floor(baseUnits / Math.pow(10, decimals - 2));
+  return { amount_minor: Math.min(quoted, settledCents), quoted_minor: quoted, settled_minor: settledCents, settlement_basis: "x402_settled_min_quote", reconciled: true };
+}
+
+// Records the provider revenue-share split for a settled call routed to a registered
+// provider. Fail-safe: metering must NEVER break or reverse a settled/charged response.
+function attributeProviderSettlement(state, externalExecutionOptions, payload, quote, extra, verification) {
+  const execution = externalExecutionOptions && externalExecutionOptions.externalExecution;
+  const providerId = execution && execution.registered_provider_id;
+  if (!providerId) return;
+  try {
+    const taskRef = (payload && payload.task_ref)
+      || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
+      || null;
+    const reconciled = reconcileProviderSettlementAmount(quote, verification);
+    recordProviderSettlement(state, {
+      provider_id: providerId,
+      amount_minor: reconciled.amount_minor,
+      quoted_minor: reconciled.quoted_minor,
+      settled_minor: reconciled.settled_minor,
+      settlement_basis: reconciled.settlement_basis,
+      reconciled: reconciled.reconciled,
+      currency: quote && quote.currency ? quote.currency : null,
+      transaction_id: (extra && extra.transaction_id) || (quote && quote.quote_id) || null,
+      settlement_ref: (extra && extra.settlement_ref) || null,
+      task_ref: taskRef
+    });
+  } catch (_) { /* non-fatal: a settled call is never undone by an accounting error */ }
+}
+
+async function executeCommandRequest(state, payload, headers, options) {
+  const opts = options || {};
+  const requiredHeaders = Array.isArray(opts.requiredHeaders) && opts.requiredHeaders.length > 0
+    ? opts.requiredHeaders
+    : ["x-wallet-id", "x-payment", "x-payment-signature"];
+  const challengePayload = typeof opts.challengePayload === "function"
+    ? opts.challengePayload
+    : (quote) => ({ ok: false, quote });
+
+  hydrateQuoteStates(state);
+  const validation = validateIntegrationSelection(payload);
+  if (!validation.ok) {
+    return {
+      status: 400,
+      payload: {
+        ok: false,
+        reason: validation.reason,
+        errors: validation.errors,
+        selection: validation.selection
+      }
+    };
+  }
+  const prefersCredits = payload && payload.payment_preference === "credits_first";
+  if (!hasPaymentHeaders(headers || {}, requiredHeaders)) {
+    const bearerToken = parseBearerToken(headers);
+    const delegatedSpendRequested = typeof bearerToken === "string" && bearerToken.startsWith("xytara_spend_");
+    const delegatedSpend = delegatedSpendRequested
+      ? resolveSpendCredential(state, bearerToken, extractAgentProof(headers), {
+          account_id: payload && payload.account_id,
+          task_ref: payload && payload.task_ref,
+          units: payload && payload.quoted_units,
+          // Strict binding is scoped to this execute path (where a binding is supplied); the
+          // lifecycle paths pass no binding and are intentionally unaffected.
+          require: String(process.env.XYTARA_REQUIRE_SPEND_PROOF_BINDING || "").trim() === "1"
+        })
+      : { ok: false, reason: "spend_credential_not_requested" };
+    if (delegatedSpendRequested && !delegatedSpend.ok) {
+      return {
+        status: 403,
+        payload: {
+          ok: false,
+          reason: delegatedSpend.reason
+        }
+      };
+    }
+    if (delegatedSpend.ok) {
+      // Pin the command to the credential's own account — a delegated spend token must
+      // never be aimed at another account by supplying a different account_id.
+      if (payload && typeof payload.account_id === "string" && payload.account_id && payload.account_id !== delegatedSpend.credential.account_id) {
+        return { status: 403, payload: { ok: false, reason: "delegated_account_mismatch" } };
+      }
+      payload = {
+        ...payload,
+        account_id: delegatedSpend.credential.account_id,
+        agent_id: payload && payload.agent_id ? payload.agent_id : delegatedSpend.credential.agent_id,
+        budget_id: payload && payload.budget_id ? payload.budget_id : delegatedSpend.credential.budget_id,
+        pack_id: delegatedSpend.credential.pack_id || (payload && payload.pack_id) || null,
+        entitlement_id: delegatedSpend.credential.entitlement_id || (payload && payload.entitlement_id) || null
+      };
+    }
+    const quote = createQuote(state, payload);
+    if (prefersCredits) {
+      const creditPayload = {
+        ...payload,
+        account_id: quote.account_id,
+        quoted_units: Number.isFinite(Number(payload.quoted_units)) ? Number(payload.quoted_units) : undefined
+      };
+      const meteringPreview = buildUsageMeterPreview(state, creditPayload);
+      const requiredUnits = meteringPreview.usage_units;
+      if (delegatedSpend.ok && delegatedSpend.binding) {
+        const authorityDecision = evaluateAuthorityBindingAction(delegatedSpend.binding, "delegated_credit_spend", requiredUnits);
+        if (!authorityDecision.ok) {
+          return {
+            status: 403,
+            payload: {
+              ok: false,
+              reason: authorityDecision.reason,
+              binding_id: authorityDecision.binding_id || null,
+              required_scope: authorityDecision.required_scope || null,
+              authority_scope: authorityDecision.authority_scope || [],
+              required_consequence_family: authorityDecision.required_consequence_family || null,
+              allowed_consequence_families: authorityDecision.allowed_consequence_families || [],
+              max_units: authorityDecision.max_units || null,
+              attempted_units: authorityDecision.attempted_units || requiredUnits
+            }
+          };
+        }
+      }
+
+      const creditDecision = previewCreditSpend(state, creditPayload);
+      if (!creditDecision.ok || !creditDecision.credit_spend_preview || creditDecision.credit_spend_preview.executable_now !== true) {
+        return buildCreditRejectionResponse(creditDecision, quote);
+      }
+
+      const preCommitAuthorizationContext = delegatedSpend.ok
+        ? delegatedSpend.authorization_context
+        : {
+            ok: true,
+            verification_mode: "account_credits",
+            wallet_id: quote.account_id,
+            age_seconds: 0,
+            payment_payload: {
+              credit_spend_status: "precommit"
+            }
+          };
+      const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, preCommitAuthorizationContext);
+      if (externalExecutionOptions.error) {
+        return {
+          status: externalExecutionOptions.error.status || 502,
+          payload: {
+            ok: false,
+            reason: externalExecutionOptions.error.reason || "external_execution_failed",
+            details: externalExecutionOptions.error.details || null,
+            credit_spend_status: "not_committed",
+            credit_spend_preview: creditDecision.credit_spend_preview,
+            quote
+          }
+        };
+      }
+
+      const creditSpend = consumeAccountCredits(state, buildCreditCommitPayload(payload, quote, requiredUnits));
+      if (creditSpend.ok) {
+        const paymentVerification = {
+          ...(delegatedSpend.ok
+            ? delegatedSpend.authorization_context
+            : {
+                ok: true,
+                verification_mode: "account_credits",
+                wallet_id: quote.account_id,
+                age_seconds: 0,
+                payment_payload: {}
+              }),
+          payment_payload: {
+            ...((delegatedSpend.ok && delegatedSpend.authorization_context && delegatedSpend.authorization_context.payment_payload) || {}),
+            credit_spend_id: creditSpend.credit_spend.credit_spend_id
+          }
+        };
+        attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
+          transaction_id: creditSpend.credit_spend.credit_spend_id
+        }, paymentVerification);
+        const creditResult = createCommandResult(state, {
+          ...payload,
+          payment_preference: "credits_first"
+        }, quote, {
+          paymentVerification,
+          creditSpend: creditSpend.credit_spend,
+          skipPaymentLedger: true,
+          externalExecution: externalExecutionOptions.externalExecution || null
+        });
+        attachDeliveryReceipt(state, creditResult, payload, quote, paymentVerification, externalExecutionOptions);
+        return {
+          status: 200,
+          payload: creditResult
+        };
+      }
+      if (creditSpend.reason !== "insufficient_credits") {
+        return {
+          status: 403,
+          payload: {
+            ok: false,
+            reason: creditSpend.reason,
+            account_id: quote.account_id,
+            provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
+            policy_guard: {
+              agent_id: creditSpend.agent_id || null,
+              budget_id: creditSpend.budget_id || null,
+              task_domain: creditSpend.task_domain || null,
+              policy_ref: creditSpend.policy_ref || null,
+              max_reserve_units: creditSpend.max_reserve_units || null,
+              allowed_job_domains: creditSpend.allowed_job_domains || null,
+              budget_status: creditSpend.budget_status || null,
+              agent_status: creditSpend.agent_status || null
+            },
+            quote
+          }
+        };
+      }
+      return {
+        status: 402,
+        payload: {
+          ok: false,
+          reason: "insufficient_credits",
+          provider_execution_completed_but_credit_commit_failed: Boolean(externalExecutionOptions.externalExecution),
+          insufficient_credits: {
+            account_id: quote.account_id,
+            required_units: creditSpend.required_units,
+            available_units: creditSpend.available_units,
+            recommended_next_surfaces: {
+              credits_topup: "/v1/checkout/purchase-intents",
+              direct_payment: "/v1/payment-quotes"
+            }
+          },
+          quote
+        }
+      };
+    }
+    return {
+      status: 402,
+      payload: await challengePayload(quote)
+    };
+  }
+
+  const quote = payload.quote_id && state.quotes.get(payload.quote_id)
+    ? state.quotes.get(payload.quote_id)
+    : createQuote(state, payload);
+
+  if (quote && quote.status === "expired") {
+    return {
+      status: 409,
+      payload: {
+        ok: false,
+        reason: "quote_expired",
+        quote
+      }
+    };
+  }
+
+  if (quote && (quote.status === "executed" || quote.status === "accepted")) {
+    return {
+      status: 409,
+      payload: {
+        ok: false,
+        reason: "quote_already_used",
+        quote
+      }
+    };
+  }
+
+  // Verify-execute-settle: for the x402 facilitator path, settlement is DEFERRED
+  // until execution succeeds, so a failed call never settles/charges. Other paths
+  // (native/credits, and the external rails L402/BOLT/MPP whose funds already moved
+  // before the proof) have nothing to defer and are unaffected.
+  const paymentVerification = await verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote, {
+    payment_protocol: opts.paymentProtocol || (payload && payload.payment_protocol) || null,
+    authorization_scheme: opts.authorizationScheme || null,
+    resource_url: opts.resourceUrl || null,
+    deferSettlement: true
+  });
+  if (!paymentVerification.ok) {
+    return {
+      status: paymentVerification.status || 403,
+      payload: {
+        ok: false,
+        reason: paymentVerification.reason,
+        ...(paymentVerification.detail ? { detail: paymentVerification.detail } : {}),
+        quote
+      }
+    };
+  }
+
+  markPaymentAccepted(state, paymentVerification);
+  const settlementDeferred = Boolean(paymentVerification.deferred_settlement);
+
+  // Reserve an execution slot so the same signed x402 authorization cannot execute
+  // twice concurrently (the deferred settle no longer fronts the on-chain nonce as an
+  // implicit pre-execution guard). No-op for non-deferred lanes; fails open if the
+  // store is unavailable. The slot is released in the finally below, whatever happens.
+  const executionClaim = claimDeferredExecution(state, paymentVerification);
+  if (!executionClaim.ok) {
+    return {
+      status: executionClaim.status || 409,
+      payload: {
+        ok: false,
+        reason: executionClaim.reason || "payment_authorization_in_progress",
+        ...(executionClaim.detail ? { detail: executionClaim.detail } : {}),
+        payment_settled: false,
+        quote
+      }
+    };
+  }
+
+  try {
+    const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, paymentVerification);
+    if (externalExecutionOptions.error) {
+      // Execution failed. Report the money state by what actually happened, not by lane:
+      //  - deferred x402: we never settled, so the caller is NOT charged.
+      //  - a concrete receipt is in hand (an x402 settlement already captured): the caller
+      //    WAS charged, so surface the receipt and a refund path.
+      //  - everything else (native/local_signed, presence, and the access-token rails
+      //    whose proof we only validated): no receipt was produced on this request, so we
+      //    do not claim a charge — a bare retry hint, never a false refund pointer.
+      const hasReceipt = Boolean(paymentVerification.settlement || paymentVerification.payment_response_base64);
+      return {
+        status: externalExecutionOptions.error.status || 502,
+        payload: {
+          ok: false,
+          reason: externalExecutionOptions.error.reason || "external_execution_failed",
+          details: externalExecutionOptions.error.details || null,
+          payment_settled: hasReceipt,
+          ...(paymentVerification.settlement ? { settlement: paymentVerification.settlement } : {}),
+          remediation: settlementDeferred
+            ? "execution failed before settlement; you were not charged — retry with corrected input"
+            : hasReceipt
+              ? "payment was accepted but execution failed; retry with corrected input or request a refund with your payment proof"
+              : "execution failed; retry with corrected input",
+          quote
+        },
+        ...(hasReceipt && paymentVerification.payment_response_base64
+          ? { paymentResponse: paymentVerification.payment_response_base64 }
+          : {})
+      };
+    }
+
+    // Execution succeeded — settle the deferred payment now (no-op for non-deferred).
+    const settleResult = await settleDeferredPayment(paymentVerification);
+    if (!settleResult.ok) {
+      return {
+        status: settleResult.status || 402,
+        payload: {
+          ok: false,
+          reason: settleResult.reason || "settlement_failed",
+          ...(settleResult.detail ? { detail: settleResult.detail } : {}),
+          payment_settled: false,
+          remediation: "the work executed but settlement failed; you were not charged — retry",
+          quote
+        }
+      };
+    }
+    // settleDeferredPayment is a no-op for non-deferred paths (returns {ok:true} with no
+    // settlement) — in that case keep the verification untouched; only when a deferred
+    // x402 settlement actually ran do we fold its receipt in and drop the deferred marker.
+    const settlementOccurred = Boolean(settleResult.settlement || settleResult.payment_response_base64);
+    const settledVerification = settlementOccurred
+      ? { ...paymentVerification, settlement: settleResult.settlement, payment_response_base64: settleResult.payment_response_base64, deferred_settlement: undefined }
+      : paymentVerification;
+
+    attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
+      settlement_ref: (settledVerification.settlement && (settledVerification.settlement.transaction || settledVerification.settlement.txid)) || null
+    }, settledVerification);
+    const paidResult = createCommandResult(state, payload, quote, {
+      paymentVerification: settledVerification,
+      externalExecution: externalExecutionOptions.externalExecution || null
+    });
+    attachDeliveryReceipt(state, paidResult, payload, quote, settledVerification, externalExecutionOptions);
+    return {
+      status: 200,
+      payload: paidResult,
+      ...(settledVerification.payment_response_base64
+        ? { paymentResponse: settledVerification.payment_response_base64 }
+        : {})
+    };
+  } finally {
+    releaseDeferredExecution(state, executionClaim.key);
+  }
+}
+
+async function executeAuthorizedCommandRequest(state, payload, authorizationContext) {
+  const validation = validateIntegrationSelection(payload);
+  if (!validation.ok) {
+    return {
+      status: 400,
+      payload: {
+        ok: false,
+        reason: validation.reason,
+        errors: validation.errors,
+        selection: validation.selection
+      }
+    };
+  }
+
+  hydrateQuoteStates(state);
+
+  const quote = createQuote(state, payload);
+  const paymentVerification = {
+    ok: true,
+    verification_mode: authorizationContext && authorizationContext.verification_mode
+      ? authorizationContext.verification_mode
+      : "hosted_checkout",
+    wallet_id: authorizationContext && authorizationContext.wallet_id
+      ? authorizationContext.wallet_id
+      : "hosted_checkout",
+    age_seconds: 0,
+    payment_payload: authorizationContext && authorizationContext.payment_payload
+      ? authorizationContext.payment_payload
+      : null
+  };
+  const externalExecutionOptions = await buildExternalExecutionOptions(state, payload, quote, paymentVerification);
+  if (externalExecutionOptions.error) {
+    return {
+      status: externalExecutionOptions.error.status || 502,
+      payload: {
+        ok: false,
+        reason: externalExecutionOptions.error.reason || "external_execution_failed",
+        details: externalExecutionOptions.error.details || null
+      }
+    };
+  }
+
+  attributeProviderSettlement(state, externalExecutionOptions, payload, quote, undefined, paymentVerification);
+  const authorizedResult = createCommandResult(state, payload, quote, {
+    paymentVerification,
+    externalExecution: externalExecutionOptions.externalExecution || null
+  });
+  attachDeliveryReceipt(state, authorizedResult, payload, quote, paymentVerification, externalExecutionOptions);
+  return {
+    status: 200,
+    payload: authorizedResult
+  };
+}
+
+module.exports = {
+  executeAuthorizedCommandRequest,
+  executeCommandRequest,
+  buildExternalExecutionOptions,
+  reconcileProviderSettlementAmount,
+  sanitizeAuthorizationContextForProvider
+};