xytara 3.1.16 → 3.2.0

package/lib/command_flow.js

@@ -1,911 +0,0 @@
-"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, loadExecutionTargetRegistry, resolveExecutionTarget } = require("./external_execution_runtime");
-const {
-  STATE_RESTORE_PENDING_RESPONSE,
-  creditSpendPolicyMode,
-  creditUnitPriceAtomic,
-  isStateRestorePending,
-  paidExecutionPolicyMode
-} = require("./buyer_safety_policy");
-const { externalExecutionBudgetMs } = require("./external_execution_policy");
-const { encodePaymentResponse } = require("./x402_facilitator");
-const {
-  authorizationRefFromVerification,
-  confirmAuthorizationUsed,
-  rememberReplay,
-  resolveReplay
-} = require("./x402_settlement_recovery");
-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: "/x402/credits/topup",
-            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
-  };
-}
-
-// The execution deadline: the configured budget, but never so late that the buyer's signed x402
-// authorization expires before we can settle it (keep 20 s for the settle call).
-function executionDeadlineMs(authorizationContext) {
-  const budgetDeadline = Date.now() + externalExecutionBudgetMs();
-  const deferred = authorizationContext && authorizationContext.deferred_settlement;
-  const signed = deferred && deferred.authorization && deferred.authorization.paymentPayload
-    && deferred.authorization.paymentPayload.payload && deferred.authorization.paymentPayload.payload.authorization;
-  const validBeforeSeconds = signed ? Number(signed.validBefore) : NaN;
-  if (!Number.isFinite(validBeforeSeconds) || validBeforeSeconds <= 0) return budgetDeadline;
-  return Math.min(budgetDeadline, validBeforeSeconds * 1000 - 20000);
-}
-
-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: executionDeadlineMs(authorizationContext) };
-  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" } };
-    }
-    // Defense in depth behind assessPaidExecutability: on a hosted deploy a call with no real
-    // execution target must never reach settlement with a synthetic result.
-    if (paidExecutionPolicyMode() === "strict") {
-      return { error: { ok: false, status: 501, reason: "capability_not_executable" } };
-    }
-    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;
-  // Credit spends accrue on what the consumed units were actually bought for (units x unit
-  // price; USDC 6 decimals -> cents), never on the catalog quote.
-  const creditPayload = (verification && verification.payment_payload) || {};
-  const creditUnits = Number(creditPayload.credit_units);
-  const unitPriceAtomic = Number(creditPayload.credit_unit_price_atomic);
-  if (Number.isFinite(creditUnits) && creditUnits > 0 && Number.isFinite(unitPriceAtomic) && unitPriceAtomic > 0) {
-    const settledCents = Math.floor((creditUnits * unitPriceAtomic) / 10000);
-    return { amount_minor: Math.min(quoted, settledCents), quoted_minor: quoted, settled_minor: settledCents, settlement_basis: "credits_unit_value_min_quote", reconciled: true };
-  }
-  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 */ }
-}
-
-// When a buyer is quoted for a routed task, wake the provider(s) that will serve it: the buyer
-// spends a few seconds signing the payment, which is usually enough for a sleeping free-tier host
-// to come up. Fire-and-forget, at most once a minute per provider, never blocks the response.
-const providerWarmedAt = new Map();
-function warmProvidersForCall(state, payload, quote) {
-  try {
-    const now = Date.now();
-    for (const target of resolveRegisteredTargets(state, payload, quote).slice(0, 3)) {
-      const last = providerWarmedAt.get(target.registered_provider_id) || 0;
-      if (now - last < 60000) continue;
-      providerWarmedAt.set(target.registered_provider_id, now);
-      const origin = new URL(target.endpoint_url).origin;
-      fetch(`${origin}/health`, { method: "GET", signal: AbortSignal.timeout(3000), redirect: "error" }).catch(() => {});
-    }
-  } catch (_) { /* best effort */ }
-}
-
-// Task refs that resolve to a real execution target right now: operator-pinned env targets plus
-// active open-network providers. This is the set a hosted deploy will accept payment for.
-function listExecutableTaskRefs(state) {
-  const refs = new Set();
-  try {
-    for (const target of loadExecutionTargetRegistry()) {
-      if (target && target.enabled && target.task_ref) refs.add(target.task_ref);
-    }
-  } catch (_) { /* a malformed env registry simply contributes nothing */ }
-  const registry = state && state.providerRegistry;
-  if (registry && typeof registry.values === "function") {
-    for (const provider of registry.values()) {
-      if (provider && provider.status === "active" && Array.isArray(provider.task_refs)) {
-        provider.task_refs.forEach((ref) => refs.add(ref));
-      }
-    }
-  }
-  return Array.from(refs).sort();
-}
-
-// Refuse BEFORE quoting/charging any task that nothing can actually execute (strict policy), so
-// a buyer never pays for a synthetic "completed" result. Permissive (local) keeps legacy behavior.
-function assessPaidExecutability(state, payload) {
-  if (paidExecutionPolicyMode() !== "strict") return { ok: true };
-  const body = payload && typeof payload === "object" ? payload : {};
-  const taskRefs = Array.isArray(body.tasks) && body.tasks.length > 0
-    ? body.tasks.map((task) => String((task && task.task_ref) || "").trim())
-    : [String(body.task_ref || "").trim()];
-  const executable = listExecutableTaskRefs(state);
-  if (taskRefs.some((ref) => !ref)) {
-    return {
-      ok: false,
-      status: 400,
-      payload: { ok: false, reason: "task_ref_required", detail: "Name the task to run in task_ref.", executable_task_refs: executable }
-    };
-  }
-  const probeQuote = { integration_ids: Array.isArray(body.integration_ids) ? body.integration_ids : [] };
-  const runnable = (ref) => {
-    const single = { ...body, task_ref: ref, tasks: undefined };
-    return Boolean(resolveExecutionTarget(single, probeQuote)) || hasActiveMatchingProvider(state, single, probeQuote);
-  };
-  const missing = taskRefs.filter((ref) => !runnable(ref));
-  if (missing.length > 0) {
-    return {
-      ok: false,
-      status: 501,
-      payload: {
-        ok: false,
-        reason: "capability_not_executable",
-        detail: "Nothing can execute " + missing.join(", ") + " right now, so no payment is requested. Choose one of executable_task_refs, or call the MCP tools directly at https://xytara-mcp-executor.onrender.com/mcp.",
-        task_refs: missing,
-        executable_task_refs: executable
-      }
-    };
-  }
-  return { ok: true };
-}
-
-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 executability = assessPaidExecutability(state, payload);
-  if (!executability.ok) {
-    return { status: executability.status, payload: executability.payload };
-  }
-  const prefersCredits = payload && payload.payment_preference === "credits_first";
-  if (prefersCredits && isStateRestorePending()) {
-    return { status: 503, payload: { ...STATE_RESTORE_PENDING_RESPONSE }, headers: { "Retry-After": "30" } };
-  }
-  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
-      };
-    }
-    if (prefersCredits && !delegatedSpend.ok && creditSpendPolicyMode() === "strict") {
-      return {
-        status: 401,
-        payload: {
-          ok: false,
-          reason: "credit_spend_credential_required",
-          detail: "Spending credits needs the account's spend credential: send it as `Authorization: Bearer xytara_spend_...`. A self-serve top-up (POST /x402/credits/topup) returns one for the paying address; or pay per call with x402 instead (omit payment_preference).",
-          credits_topup: "/x402/credits/topup"
-        }
-      };
-    }
-    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,
-            credit_units: requiredUnits,
-            credit_unit_price_atomic: creditUnitPriceAtomic()
-          }
-        };
-        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: "/x402/credits/topup",
-              direct_payment: "/v1/payment-quotes"
-            }
-          },
-          quote
-        }
-      };
-    }
-    warmProvidersForCall(state, payload, 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
-      }
-    };
-  }
-
-  // A resent x402 payment we already settled (or were still confirming) gets its stored result
-  // instead of a re-execution or a confusing "nonce already used" failure.
-  const requestDigest = hashCanonical({
-    task_ref: (payload && payload.task_ref) || null,
-    tasks: (payload && payload.tasks) || null,
-    body: (payload && payload.body) || null
-  });
-  if (requiredHeaders.includes("payment-signature")) {
-    const replay = await resolveReplay(state, headers || {}, { request_digest: requestDigest });
-    if (replay) return replay;
-  }
-
-  // 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);
-      const failureStatus = externalExecutionOptions.error.status || 502;
-      // A provider outage/timeout is not the buyer's input: say so, and say when to retry.
-      const providerUnavailable = failureStatus === 502 || failureStatus === 503 || failureStatus === 504;
-      const retryHint = providerUnavailable ? "the provider did not respond in time — retry in a few seconds" : "retry with corrected input";
-      return {
-        status: failureStatus,
-        ...(providerUnavailable ? { headers: { "Retry-After": "5" } } : {}),
-        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 — ${retryHint}`
-            : hasReceipt
-              ? `payment was accepted but execution failed; ${retryHint}, or request a refund with your payment proof`
-              : `execution failed; ${retryHint}`,
-          quote
-        },
-        ...(hasReceipt && paymentVerification.payment_response_base64
-          ? { paymentResponse: paymentVerification.payment_response_base64 }
-          : {})
-      };
-    }
-
-    // Execution succeeded — settle the deferred payment now (no-op for non-deferred).
-    const finalizePaid = (settleResult) => {
-      // 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 }
-          : {})
-      };
-    };
-
-    let settleResult = await settleDeferredPayment(paymentVerification);
-    const authorizationRef = settlementDeferred ? authorizationRefFromVerification(paymentVerification) : null;
-    if (!settleResult.ok && authorizationRef && settleResult.reason === "facilitator_unreachable") {
-      // The facilitator timed out / dropped: it may still have broadcast the transfer. Ask the chain.
-      const used = await confirmAuthorizationUsed(authorizationRef);
-      if (used === true) {
-        const settlement = { success: true, transaction: null, network: authorizationRef.network, payer: authorizationRef.authorizer, recovered_from: "authorization_state" };
-        settleResult = { ok: true, settlement, payment_response_base64: encodePaymentResponse(settlement) };
-      } else {
-        // Not confirmed (yet). Keep the finished result under this payment so resending the SAME
-        // signature delivers it once the transfer shows up on-chain — never ask for a new payment.
-        rememberReplay(state, authorizationRef, {
-          status: "unconfirmed",
-          request_digest: requestDigest,
-          finalize: async (settlement) => finalizePaid({ ok: true, settlement, payment_response_base64: encodePaymentResponse(settlement) })
-        });
-        return {
-          status: 502,
-          payload: {
-            ok: false,
-            reason: used === false ? "settlement_not_confirmed" : "settlement_outcome_unknown",
-            detail: "The payment processor did not answer in time. Your work is done and held for 15 minutes: if this payment shows up on-chain, resend the SAME payment signature to receive the result; if it never settles you are not charged. Do not sign a new payment for this request.",
-            payment_settled: used === false ? false : null,
-            money_moved: used !== false,
-            quote
-          }
-        };
-      }
-    }
-    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 the payment was declined at settlement; you were not charged — retry with a valid payment",
-          quote
-        }
-      };
-    }
-    const paidResponse = finalizePaid(settleResult);
-    if (authorizationRef) rememberReplay(state, authorizationRef, { status: "settled", request_digest: requestDigest, response: paidResponse });
-    return paidResponse;
-  } 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,
-  listExecutableTaskRefs,
-  assessPaidExecutability,
-  buildExternalExecutionOptions,
-  reconcileProviderSettlementAmount,
-  sanitizeAuthorizationContextForProvider
-};