xytara 3.1.14 → 3.1.15

package/.env.example

@@ -10,9 +10,36 @@ XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
 XYTARA_X402_FACILITATOR_HEADERS_JSON={}
 XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
 XYTARA_X402_SETTLE=true
-# credit units a single self-serve /x402/credits/topup grants (default 1000);
-# an accepts entry may override per-payment via its extra.credits
-XYTARA_X402_TOPUP_UNITS=1000
+# self-serve /x402/credits/topup: priced at this multiple of the per-call accepts amount
+# (default 100: $0.01 -> $1.00); credits = amount paid / XYTARA_CREDIT_UNIT_PRICE_ATOMIC
+# (USDC base units per credit; default 2500 = $0.0025). An accepts entry's extra.credits may
+# lower the grant, never raise it. Testnet networks cannot buy credits unless this is 1:
+XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER=100
+XYTARA_CREDIT_UNIT_PRICE_ATOMIC=2500
+XYTARA_X402_TESTNET_TOPUP=0
+# floor for the advertised maxTimeoutSeconds (buyers sign validBefore = now + this)
+XYTARA_X402_MIN_TIMEOUT_SECONDS=300
+# money-safety policies: "strict" by default on a hosted deploy (RENDER set), "permissive" locally.
+#  paid execution: only tasks with a real execution target can be quoted/charged
+#  credit spend:   spending credits needs the account's spend credential (xytara_spend_...)
+#  ledger reads:   ledger/quote-list/receipts/operations/revenue GETs are operator-only
+XYTARA_PAID_EXECUTION_POLICY=
+XYTARA_CREDIT_SPEND_POLICY=
+XYTARA_LEDGER_READ_POLICY=
+# provider calls: per-attempt timeout floor for registered providers (default 25000 on Render)
+XYTARA_PROVIDER_MIN_TIMEOUT_MS=
+# chain RPC used to check whether an x402 authorization settled after a facilitator timeout
+XYTARA_RPC_URL_EIP155_8453=https://mainnet.base.org
+XYTARA_RPC_URL_EIP155_84532=https://sepolia.base.org
+# buyer event log: ring size, payer-hash salt, and the token the MCP executor uses to forward
+# its events to POST /v1/operator/buyer-events/ingest
+XYTARA_BUYER_EVENT_LOG_MAX=500
+XYTARA_BUYER_EVENT_SALT=
+XYTARA_EVENT_INGEST_TOKEN=
+# Supabase request timeout (ms) for state restore/flush
+XYTARA_SUPABASE_TIMEOUT_MS=10000
+# public base URL advertised in OpenAPI/AsyncAPI
+XYTARA_PUBLIC_BASE_URL=https://xytara.onrender.com
 # Coinbase CDP auth for the CDP-hosted facilitator (Base mainnet); Ed25519 Secret API Key.
 # The runtime mints a fresh CDP Bearer JWT per request when both are set.
 CDP_API_KEY_ID=

package/REAL_PAYMENT_SETUP.md

@@ -50,17 +50,24 @@ runtime takes a command-execute body rather than an MCP JSON-RPC call.
 Beyond paying per call, a buyer can convert a single x402 payment into spendable
 runtime credits with no operator grant, via `POST /x402/credits/topup`:
 
-- without a `PAYMENT-SIGNATURE`, it returns `402` advertising the same `accepts` plus
-  `credits_per_topup` (how many credit units one payment buys)
+- without a `PAYMENT-SIGNATURE`, it returns `402` advertising the top-up `accepts` (each
+  per-call amount x `XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER`, default 100: $0.01 -> $1.00),
+  `credits_per_topup` and a `topup_options` list (network, amount, credits)
 - with a valid payment, the facilitator settles it on-chain and the runtime mints the
-  credits to the account, returning the grant, the new balance, and a `PAYMENT-RESPONSE`
-  settlement receipt
-- credits land on `account_id` from the body, falling back to the paying wallet address
+  credits to the account, returning the grant, the new balance, a `PAYMENT-RESPONSE`
+  settlement receipt and — when the credits went to the paying address — a
+  `spend_credential` (`Bearer xytara_spend_...`, shown once) for spending them
+- credits land on the paying wallet address by default; credits sent to another `account_id`
+  are a gift and carry no spend credential
 - replays are idempotent: the payment nonce keys the grant, so re-sending the same settled
   payment never mints twice
 
-Each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched
-`accepts` entry sets its own `extra.credits`. The route is live only in `x402_facilitator`
+Credits are derived from what was paid: amount / `XYTARA_CREDIT_UNIT_PRICE_ATOMIC` (default
+2500 base units = $0.0025 per credit, so $1.00 buys 400 credits; a task costs 1–8 credits by
+tier). A matched `accepts` entry's `extra.credits` may lower that, never raise it. Testnet
+networks (Base Sepolia) cannot buy credits unless `XYTARA_X402_TESTNET_TOPUP=1`. Spend them with
+`payment_preference: "credits_first"` and the spend credential as the bearer — on a hosted
+deploy a bare `account_id` is never authority. The route is live only in `x402_facilitator`
 mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime state
 persistence (`XYTARA_SUPABASE_*` or `XYTARA_STATE_FILE`) is configured. A runnable buyer is in
 `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`.

package/RELEASE_NOTES.md

@@ -1,7 +1,10 @@
-`xytara` 3.1.14 makes runtime state durable under backend failures, writes it more lightly, and backs it up off-site.
+`xytara` 3.1.15 makes the buyer path safe end to end: a buyer is never charged for a result that was not produced, every failed attempt is visible to the operator, and standard x402 MCP clients can pay the MCP server directly.
 
-- **Write guard** — if the boot-time restore of durable state fails (e.g. the state backend times out), the runtime never writes: writing would overwrite the good snapshot with near-empty state. It retries the restore in the background, merges the snapshot under anything that happened since boot, and only then resumes writes. Proven in production during a state-backend outage: the full snapshot was restored with nothing lost.
-- **Lighter writes** — the snapshot is written only when its content changed (identical rewrites are skipped and counted), the default check interval is 15s, and expired never-paid quotes are pruned after 7 days (`XYTARA_QUOTE_RETENTION_MS`).
-- **Rolling history** — in Supabase mode the snapshot is also kept in rotating hourly history rows (24 by default), so a bad write can be rolled back.
-- **Off-site encrypted backups** — `scripts/state_backup_offsite.js` (gzip + AES-256-GCM; refuses a near-empty snapshot so a failed scheduled run is an alert; decrypt and guarded restore modes) with a daily workflow.
+- **Pay only for real work** — on a hosted deploy a task is quoted and charged only when it resolves to a real execution target (an operator-pinned target or an active open-network provider). Anything else is refused up front with `501 capability_not_executable` and the list of executable tasks; no payment is requested. The catalog marks every task with `purchase.executable_now` and its per-call price. Post-quantum proof verification (`adapter.xoonya.invoke`) is now a catalog task.
+- **Verify, execute, then settle — everywhere** — paid A2A calls now settle only after the skill succeeds, like the HTTP routes. If the facilitator times out at settlement, the runtime checks the EIP-3009 `authorizationState` on-chain: a used authorization is a settled payment and the result is delivered; otherwise the finished result is held and returned when the buyer resends the same payment (bound to the original request). A resent settled payment returns its stored result instead of failing. The execution deadline stays inside the signed authorization's `validBefore`, and the advertised `maxTimeoutSeconds` has a floor of 300.
+- **Credits are safe and priced from what was paid** — spending credits requires the account's spend credential; a bare `account_id` is never authority. A self-serve top-up is priced at 100x the per-call amount, is mainnet-only by default, grants credits derived from the amount paid (default $0.0025 per credit), and returns a spend credential to the paying address. Provider revenue on credit spends accrues on the credits' purchase value, never on the catalog quote. Credit routes answer `503` with `Retry-After` while durable state is still being restored.
+- **Buyer event log** — every failed buyer attempt is recorded with its stage, reason, fault (ours, upstream, buyer) and a request id the buyer also receives (`X-Request-Id`), with per-day counters for challenges issued and paid calls served. No signatures, request bodies, tokens or full addresses are stored. Operator-only `GET /v1/operator/buyer-events` and `/summary`; the MCP server forwards its events to `POST /v1/operator/buyer-events/ingest`; a daily report job flags money that moved without a delivered result.
+- **MCP server** — speaks the x402 MCP transport natively (payment-required tool result; payment in `_meta["x402/payment"]`, `PAYMENT-SIGNATURE` or `X-PAYMENT`; settlement in `_meta["x402/payment-response"]`), with `/mcp/http402` for fetch-wrapper clients. Bad arguments and unknown tools are rejected before any payment, `GET /mcp` is no longer a paid route, and CORS is enabled. Every paid tool was corrected so that an empty, invalid or unverifiable answer is an error and never charged; `json.validate` validates against a JSON Schema subset, `x402.verify-receipt` confirms only a matching USDC transfer, ABI tools are strict, and hostile inputs are bounded.
+- **Request-bound agent signatures** — the credit lifecycle routes (reserve, release, reverse) honour the agent's signed binding to the exact account, amount and task.
+- **Robustness and privacy** — malformed JSON is a `400` (oversize `413`), internal errors are logged under the request id without leaking details, state-store calls time out, registered providers get a cold-start timeout floor and are woken when a buyer is quoted, and ledger, quote-list, receipt, operations and revenue reads are operator-only on a hosted deploy. x402 challenges show the price actually charged; OpenAPI and AsyncAPI point at the hosted runtime.
 - Published through npm trusted publishing (GitHub OIDC) — no npm token involved.

package/fixtures/catalog.js

@@ -779,6 +779,28 @@ const tasks = [
     capabilities: ["adapter.mcp.invoke"],
     adapters: ["mcp"]
   }),
+  makeTask({
+    task_ref: "internal.adapter.xoonya.invoke",
+    public_task_ref: "adapter.xoonya.invoke",
+    public_category: "adapter",
+    public_title: "Post-quantum proof verification (xoonya)",
+    execution_mode: "direct_http",
+    pricing_band: "decision_support",
+    public_launch_price: { amount_minor: 1, currency: "USD_CENTS" },
+    latency_class: "near_real_time",
+    failure_posture: "retry_bounded",
+    input_schema: {
+      type: "object",
+      required: ["tool_name"],
+      properties: {
+        tool_name: { type: "string", enum: ["proof.verify-signature", "proof.verify-bundle"] },
+        arguments: { type: "object" }
+      },
+      additionalProperties: false
+    },
+    capabilities: ["adapter.xoonya.invoke"],
+    adapters: ["xoonya"]
+  }),
   makeTask({
     task_ref: "internal.adapter.mcp.catalog",
     public_task_ref: "adapter.mcp.catalog",

package/lib/a2a_rpc.js

@@ -156,6 +156,22 @@ async function handleMessageSend(rpc, ctx) {
   const contextId = message.contextId || message.taskId || uuid();
   const { skillTaskRef, body } = resolveSkill(message);
 
+  // Never ask for (or take) payment for a skill nothing can execute.
+  const taskPayloadDraft = ctx.deps.buildNamedTaskPayload(skillTaskRef, body, skillTaskRef);
+  const executability = typeof ctx.deps.assessExecutability === "function" ? ctx.deps.assessExecutability(taskPayloadDraft) : { ok: true };
+  if (!executability.ok) {
+    const refusal = executability.payload || {};
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({
+        taskId,
+        contextId,
+        paymentStatus: "not-required",
+        error: `${refusal.reason || "capability_not_executable"}: ${refusal.detail || "this skill cannot run here"}${Array.isArray(refusal.executable_task_refs) ? ` Executable: ${refusal.executable_task_refs.join(", ")}.` : ""}`
+      }))
+    };
+  }
+
   const payload = meta[META_PAYLOAD];
   if (!payload) {
     // In-band 402: Task(input-required) carrying the x402 requirements.
@@ -188,14 +204,6 @@ async function handleMessageSend(rpc, ctx) {
     };
   }
 
-  const settled = await ctx.deps.settleX402Payment({ authorization: auth.authorization, facilitator, settle: x402.settle });
-  if (!settled.ok) {
-    return {
-      http: 200,
-      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "payment-failed", error: settled.detail || settled.reason }))
-    };
-  }
-
   const requirements = (auth.authorization && auth.authorization.paymentRequirements) || {};
   const requestPayload = {
     ...ctx.deps.buildNamedTaskPayload(skillTaskRef, body, skillTaskRef),
@@ -212,36 +220,35 @@ async function handleMessageSend(rpc, ctx) {
     }
   };
 
+  // Verify -> execute -> settle: the payment is only settled once the skill has produced its
+  // result, so a failed skill never charges the paying agent.
   const exec = await ctx.deps.executeAuthorized(ctx.deps.state, requestPayload, authorizationContext);
-  const receipt = ctx.deps.encodeReceipt(settled.settlement);
   const execOk = Boolean(exec) && exec.status === 200 && (!exec.payload || exec.payload.ok !== false);
   if (!execOk) {
-    // The payment settled (money moved) but the skill did not execute. Report
-    // that honestly as a failed task while still carrying the settlement receipt,
-    // so the paying agent knows it paid and can pursue a refund/retry.
-    const failed = {
-      id: taskId,
-      contextId,
-      kind: "task",
-      status: {
-        state: "failed",
-        message: agentMessage("Payment settled, but the requested skill failed to execute.", {
-          [META_STATUS]: "payment-completed",
-          [META_RECEIPTS]: [settled.settlement],
-          execution_error: (exec && exec.payload) || "execution_failed",
-          execution_status: exec && exec.status
-        }),
-        timestamp: new Date().toISOString()
-      },
-      artifacts: [],
-      history: []
+    const reason = (exec && exec.payload && exec.payload.reason) || "execution_failed";
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "not-charged", error: `${reason}: the skill did not run, so the payment was not settled — retry` }))
     };
+  }
+
+  let settled = await ctx.deps.settleX402Payment({ authorization: auth.authorization, facilitator, settle: x402.settle });
+  if (!settled.ok && settled.reason === "facilitator_unreachable" && typeof ctx.deps.confirmAuthorizationUsed === "function") {
+    // The facilitator may have broadcast before timing out: if the authorization is used on-chain, it settled.
+    const signed = auth.authorization && auth.authorization.paymentPayload && auth.authorization.paymentPayload.payload
+      && auth.authorization.paymentPayload.payload.authorization;
+    const used = signed ? await ctx.deps.confirmAuthorizationUsed({ network: requirements.network, asset: requirements.asset, authorizer: signed.from, nonce: signed.nonce }) : null;
+    if (used === true) {
+      settled = { ok: true, settlement: { success: true, transaction: null, network: requirements.network, payer: signed.from, recovered_from: "authorization_state" } };
+    }
+  }
+  if (!settled.ok) {
     return {
       http: 200,
-      headers: { "PAYMENT-RESPONSE": receipt, "Cache-Control": "no-store" },
-      body: jsonrpcResult(id, failed)
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "payment-failed", error: `${settled.detail || settled.reason} (the result was withheld; if this payment later shows as settled on-chain, contact us with the payment nonce)` }))
     };
   }
+  const receipt = ctx.deps.encodeReceipt(settled.settlement);
   const task = completedTask({ taskId, contextId, resultPayload: exec.payload, settlement: settled.settlement });
   return {
     http: 200,

package/lib/account_auth.js

@@ -498,11 +498,11 @@ function resolveSpendCredential(state, bearerToken, proof, requestBinding) {
   // proof of control of the agent key — the bearer token alone is not enough.
   if (credential.agent_public_key) {
     // Bind the proof to the actual request (account/amount/task) when the caller supplies a
-    // request binding. `require` is set BY THE CALLER (requestBinding.require) so strict mode
-    // applies only where a binding is actually supplied — the execute path. The reserve/
-    // release/reverse lifecycle paths pass no binding, so they are unaffected by strict mode
-    // (and remain capped by the authority-binding bounds). Default keeps back-compat: an
-    // unbound proof still authorizes.
+    // request binding: a request-bound signature then verifies only for that exact request.
+    // `require` is set BY THE CALLER (requestBinding.require), so strict mode applies only to the
+    // execute path. The reserve/release/reverse lifecycle paths supply a binding WITHOUT
+    // `require`: bound signatures are checked against the request, unbound ones still authorize
+    // (back-compat), and both remain capped by the authority-binding bounds.
     const requireBinding = Boolean(requestBinding && requestBinding.require);
     const verdict = verifySpendAuthProof(credential.agent_public_key, credential.credential_id, proof || {}, {
       requestBinding: requestBinding || null,

package/lib/asyncapi_contract.js

@@ -13,9 +13,9 @@ function buildAsyncApiDocument() {
     },
     servers: {
       httpRuntime: {
-        host: "127.0.0.1:4320",
-        protocol: "http",
-        description: "Local xytara HTTP event and handoff entrypoint"
+        host: String(process.env.XYTARA_PUBLIC_BASE_URL || "https://xytara.onrender.com").trim().replace(/^https?:\/\//, "").replace(/\/+$/, ""),
+        protocol: "https",
+        description: "Hosted xytara HTTP event and handoff entrypoint"
       }
     },
     channels: {

package/lib/buyer_event_log.js

@@ -0,0 +1,215 @@
+"use strict";
+
+const crypto = require("crypto");
+
+// Buyer-journey event log: every failed buyer attempt (ours, upstream, or the buyer's) is recorded
+// so the operator can see who tried to use the system and why it did not work — plus counters for
+// the normal steps (402 challenges issued, paid calls served) as denominators.
+//
+// Privacy: events never carry payment signatures/headers, request bodies, tokens, IP addresses or
+// full wallet addresses. Payer addresses are reduced to a salted hash prefix; detail text is
+// truncated and stripped of long hex/base64 runs.
+//
+// Storage: state.buyerEventLog (bounded ring, newest last) and state.buyerEventDaily (per-day
+// counters, 30 days) are ordinary runtime state, so they persist with the Supabase snapshot and the
+// daily off-site backup. The MCP executor forwards its own events to POST /v1/operator/buyer-events/ingest.
+
+const DAILY_RETENTION_DAYS = 30;
+
+function maxEvents() {
+  const value = Number(process.env.XYTARA_BUYER_EVENT_LOG_MAX || 500);
+  return Number.isFinite(value) && value >= 10 ? Math.min(5000, Math.floor(value)) : 500;
+}
+
+function ensureBuyerEventCollections(state) {
+  if (!Array.isArray(state.buyerEventLog)) state.buyerEventLog = [];
+  if (!(state.buyerEventDaily instanceof Map)) state.buyerEventDaily = new Map();
+}
+
+function cleanText(value, max) {
+  if (value === null || value === undefined) return null;
+  const text = String(value)
+    .replace(/0x[0-9a-fA-F]{40,}/g, "0x…")
+    .replace(/[A-Za-z0-9+/=_-]{40,}/g, "…")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text ? text.slice(0, max) : null;
+}
+
+function payerHash(address) {
+  const value = String(address || "").trim().toLowerCase();
+  if (!value) return null;
+  const salt = String(process.env.XYTARA_BUYER_EVENT_SALT || "naxytra-buyer-events");
+  return crypto.createHash("sha256").update(`${salt}:${value}`).digest("hex").slice(0, 12);
+}
+
+// Path template without ids: segments that look like identifiers become ":id".
+function routeTemplate(pathname) {
+  return String(pathname || "/")
+    .split("/")
+    .map((segment) => (/(^0x[0-9a-f]{6,})|([0-9a-f]{12,})|(_[0-9a-z]{6,}$)|(^\d{3,}$)/i.test(segment) ? ":id" : segment))
+    .join("/")
+    .slice(0, 120);
+}
+
+// reason -> [stage, fault]. fault: "ours" (our bug/infra), "upstream" (facilitator, RPC, provider),
+// "buyer" (bad input / bad payment), "none" (expected protocol step).
+const REASON_RULES = [
+  [/^(capability_not_executable|task_ref_required|task_not_found|unknown_tool)/, "route", "buyer"],
+  [/^(body_must_be_valid_json|invalid_json|request_body_too_large)/, "parse", "buyer"],
+  [/^payment_(signature_invalid|requirements_mismatch|header)/, "payment_match", "buyer"],
+  [/^payment_authorization_in_progress/, "payment_verify", "buyer"],
+  [/^payment_verification_failed|^invalid_exact/, "payment_verify", "buyer"],
+  [/^facilitator_|_unreachable$/, "payment_verify", "upstream"],
+  [/^(payment_settlement_failed|settlement_failed|settle_)/, "payment_settle", "upstream"],
+  [/^(external_execution|no_healthy_provider|provider_)/, "provider", "upstream"],
+  [/^(insufficient_credits|credit_spend_|delegated_)/, "credit", "buyer"],
+  [/^agent_signature|^spend_credential|_bearer|^unauthorized|^forbidden/, "auth", "buyer"],
+  [/^rate_limit/, "rate_limit", "buyer"],
+  [/^(state_restore_pending|runtime_state)/, "state", "ours"],
+  [/^quote_(expired|already_used)/, "quote", "buyer"]
+];
+
+function classify(reason, httpStatus) {
+  const text = String(reason || "");
+  for (const [pattern, stage, fault] of REASON_RULES) {
+    if (pattern.test(text)) return { stage, fault };
+  }
+  if (httpStatus >= 500) return { stage: "internal", fault: "ours" };
+  if (httpStatus === 404) return { stage: "route", fault: "buyer" };
+  return { stage: "other", fault: httpStatus >= 400 && httpStatus < 500 ? "buyer" : "ours" };
+}
+
+function dayKey(iso) {
+  return String(iso).slice(0, 10);
+}
+
+function bumpDaily(state, iso, service, key) {
+  const day = dayKey(iso);
+  let bucket = state.buyerEventDaily.get(day);
+  if (!bucket) {
+    bucket = {};
+    state.buyerEventDaily.set(day, bucket);
+    // Drop days beyond retention (keys are ISO dates, so lexical order is chronological).
+    const days = Array.from(state.buyerEventDaily.keys()).sort();
+    while (days.length > DAILY_RETENTION_DAYS) state.buyerEventDaily.delete(days.shift());
+  }
+  const counterKey = `${service}|${key}`;
+  bucket[counterKey] = (Number(bucket[counterKey]) || 0) + 1;
+}
+
+// Count a normal step without logging an event (challenge issued, paid call served, ...).
+function countBuyerStep(state, step, options = {}) {
+  try {
+    ensureBuyerEventCollections(state);
+    bumpDaily(state, new Date().toISOString(), options.service || "runtime", `step:${step}|${routeTemplate(options.route)}`);
+  } catch (_) { /* observability must never break a buyer response */ }
+}
+
+function recordBuyerEvent(state, input) {
+  try {
+    ensureBuyerEventCollections(state);
+    const at = typeof input.at_iso === "string" && !Number.isNaN(Date.parse(input.at_iso)) ? new Date(input.at_iso).toISOString() : new Date().toISOString();
+    const httpStatus = Number.isFinite(Number(input.http_status)) ? Number(input.http_status) : null;
+    const reason = cleanText(input.reason, 80) || (httpStatus ? `http_${httpStatus}` : "unknown");
+    const classified = classify(reason, httpStatus || 0);
+    const event = {
+      id: `bev_${crypto.randomBytes(6).toString("hex")}`,
+      at_iso: at,
+      service: cleanText(input.service, 40) || "runtime",
+      request_id: cleanText(input.request_id, 40),
+      stage: cleanText(input.stage, 30) || classified.stage,
+      reason,
+      fault: cleanText(input.fault, 10) || classified.fault,
+      http_status: httpStatus,
+      route: input.route ? routeTemplate(input.route) : null,
+      method: cleanText(input.method, 8),
+      task_or_tool: cleanText(input.task_or_tool, 80),
+      rail: cleanText(input.rail, 20),
+      network: cleanText(input.network, 30),
+      amount_atomic: /^\d{1,30}$/.test(String(input.amount_atomic || "")) ? String(input.amount_atomic) : null,
+      payer_hash: input.payer_hash ? cleanText(input.payer_hash, 16) : payerHash(input.payer),
+      money_moved: input.money_moved === true,
+      latency_ms: Number.isFinite(Number(input.latency_ms)) ? Math.round(Number(input.latency_ms)) : null,
+      detail: cleanText(input.detail, 160),
+      ua: cleanText(String(input.ua || "").split(/[\s/]/)[0], 32)
+    };
+    state.buyerEventLog.push(event);
+    const cap = maxEvents();
+    if (state.buyerEventLog.length > cap) state.buyerEventLog.splice(0, state.buyerEventLog.length - cap);
+    bumpDaily(state, at, event.service, `fail:${event.stage}:${event.reason}:${event.fault}`);
+    if (event.money_moved) bumpDaily(state, at, event.service, "money_moved");
+    return event;
+  } catch (_) {
+    return null;
+  }
+}
+
+function listBuyerEvents(state, query = {}) {
+  ensureBuyerEventCollections(state);
+  const since = query.since && !Number.isNaN(Date.parse(query.since)) ? Date.parse(query.since) : null;
+  const limit = Math.max(1, Math.min(500, Number(query.limit) || 100));
+  const matches = state.buyerEventLog.filter((event) => {
+    if (since !== null && Date.parse(event.at_iso) < since) return false;
+    if (query.service && event.service !== query.service) return false;
+    if (query.stage && event.stage !== query.stage) return false;
+    if (query.fault && event.fault !== query.fault) return false;
+    if (query.money_moved === "true" && !event.money_moved) return false;
+    return true;
+  });
+  return { count: matches.length, events: matches.slice(-limit).reverse() };
+}
+
+function summarizeBuyerEvents(state, days = 7) {
+  ensureBuyerEventCollections(state);
+  const window = Math.max(1, Math.min(DAILY_RETENTION_DAYS, Number(days) || 7));
+  const keys = Array.from(state.buyerEventDaily.keys()).sort().slice(-window);
+  const totals = { failures: 0, ours: 0, upstream: 0, buyer: 0, money_moved: 0, challenges_issued: 0, paid_ok: 0 };
+  const byReason = {};
+  const perDay = keys.map((day) => {
+    const bucket = state.buyerEventDaily.get(day) || {};
+    const dayTotals = { day, failures: 0, ours: 0, upstream: 0, money_moved: 0, challenges_issued: 0, paid_ok: 0 };
+    for (const [key, count] of Object.entries(bucket)) {
+      const [service, rest] = [key.slice(0, key.indexOf("|")), key.slice(key.indexOf("|") + 1)];
+      if (rest === "money_moved") { dayTotals.money_moved += count; totals.money_moved += count; continue; }
+      if (rest.startsWith("step:challenge_issued")) { dayTotals.challenges_issued += count; totals.challenges_issued += count; continue; }
+      if (rest.startsWith("step:paid_ok")) { dayTotals.paid_ok += count; totals.paid_ok += count; continue; }
+      if (!rest.startsWith("fail:")) continue;
+      const [, stage, reason, fault] = rest.split(":");
+      dayTotals.failures += count;
+      totals.failures += count;
+      if (fault === "ours") { dayTotals.ours += count; totals.ours += count; }
+      if (fault === "upstream") { dayTotals.upstream += count; totals.upstream += count; }
+      if (fault === "buyer") totals.buyer += count;
+      const reasonKey = `${service}:${stage}:${reason}:${fault}`;
+      byReason[reasonKey] = (byReason[reasonKey] || 0) + count;
+    }
+    return dayTotals;
+  });
+  const topReasons = Object.entries(byReason)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 25)
+    .map(([key, count]) => {
+      const [service, stage, reason, fault] = key.split(":");
+      return { service, stage, reason, fault, count };
+    });
+  return {
+    window_days: window,
+    totals,
+    // Needs attention: money moved without a delivered result, or failures that are our fault.
+    attention: totals.money_moved > 0 || totals.ours > 0,
+    per_day: perDay,
+    top_reasons: topReasons,
+    generated_at_iso: new Date().toISOString()
+  };
+}
+
+module.exports = {
+  countBuyerStep,
+  ensureBuyerEventCollections,
+  listBuyerEvents,
+  payerHash,
+  recordBuyerEvent,
+  routeTemplate,
+  summarizeBuyerEvents
+};

package/lib/buyer_safety_policy.js

@@ -0,0 +1,132 @@
+"use strict";
+
+// Money-safety policy for the buyer path. Like the provider endpoint policy, each rule is
+// "strict" by default on a hosted deploy (RENDER is set) and "permissive" locally, so the local
+// verification suites (which exercise catalog tasks without a live execution target) keep working.
+//
+//  - Paid execution: only a task that resolves to a REAL execution target (an operator-pinned
+//    env target or an active open-network provider) may be quoted for payment. Anything else is
+//    refused up front with capability_not_executable, so a buyer is never charged for a
+//    synthetic result. (XYTARA_PAID_EXECUTION_POLICY=strict|permissive)
+//  - Credit spend: spending an account's credits requires a spend credential (xytara_spend_…
+//    bearer) bound to that account. A bare account_id is never authority — payer addresses are
+//    public on-chain. (XYTARA_CREDIT_SPEND_POLICY=strict|permissive)
+
+function policyMode(envName) {
+  const raw = String(process.env[envName] || "").trim().toLowerCase();
+  if (raw === "strict" || raw === "permissive") return raw;
+  return process.env.RENDER ? "strict" : "permissive";
+}
+
+function paidExecutionPolicyMode() {
+  return policyMode("XYTARA_PAID_EXECUTION_POLICY");
+}
+
+function creditSpendPolicyMode() {
+  return policyMode("XYTARA_CREDIT_SPEND_POLICY");
+}
+
+// Ledger/business reads (payer addresses, every quote, receipts, operations, revenue metrics) are
+// operator-only on a hosted deploy. (XYTARA_LEDGER_READ_POLICY=strict|permissive)
+function ledgerReadPolicyMode() {
+  return policyMode("XYTARA_LEDGER_READ_POLICY");
+}
+
+const PRIVATE_READ_PREFIXES = [
+  "/v1/payment-ledger",
+  "/v1/operator-export-pack",
+  "/v1/receipts",
+  "/v1/operations/",
+  "/v1/economics/accounts/",
+  "/v1/pricing-optimization/",
+  "/v1/revenue-signal",
+  "/v1/activity-ledger"
+];
+
+// Whether a GET is a private ledger read. A single quote by id stays public (its holder needs it).
+function isPrivateLedgerRead(method, pathname) {
+  if (String(method || "").toUpperCase() !== "GET") return false;
+  if (pathname === "/v1/payment-quotes") return true;
+  return PRIVATE_READ_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`) || pathname.startsWith(`${prefix}-`));
+}
+
+// Test networks: their USDC is free from faucets, so by default it cannot buy credits that are
+// spendable on real (mainnet-paid-out) provider work. Pay-per-call on a testnet is unaffected.
+const TESTNET_NETWORKS = new Set(["eip155:84532", "eip155:11155111"]);
+
+function isTestnetNetwork(network) {
+  return TESTNET_NETWORKS.has(String(network || "").trim().toLowerCase());
+}
+
+// What one credit unit costs, in the payment asset's base units (USDC: 6 decimals). Default
+// 2500 = $0.0025, so a decision-support call (3 units) costs $0.0075 — never more than the flat
+// pay-per-call price for the executable lanes.
+function creditUnitPriceAtomic() {
+  const value = Number(process.env.XYTARA_CREDIT_UNIT_PRICE_ATOMIC || 2500);
+  return Number.isFinite(value) && value >= 1 ? Math.floor(value) : 2500;
+}
+
+// A top-up is priced as a multiple of the per-call accepts amount (default 100x: $0.01 -> $1.00).
+function topupAmountMultiplier() {
+  const value = Number(process.env.XYTARA_X402_TOPUP_AMOUNT_MULTIPLIER || 100);
+  return Number.isFinite(value) && value >= 1 ? Math.floor(value) : 100;
+}
+
+// The accepts a credit top-up is paid with: mainnet-only unless testnet top-ups are explicitly
+// enabled, each amount scaled to the top-up price.
+function buildTopupAccepts(accepts) {
+  const allowTestnet = String(process.env.XYTARA_X402_TESTNET_TOPUP || "").trim() === "1";
+  const multiplier = BigInt(topupAmountMultiplier());
+  return (Array.isArray(accepts) ? accepts : [])
+    .filter((accept) => accept && (allowTestnet || !isTestnetNetwork(accept.network)))
+    .filter((accept) => /^\d{1,30}$/.test(String(accept.amount)))
+    .map((accept) => ({ ...accept, amount: (BigInt(String(accept.amount)) * multiplier).toString() }));
+}
+
+// Credits granted for a settled top-up: always derived from what was actually paid, so a unit is
+// never worth less than creditUnitPriceAtomic(). An accepts entry's own extra.credits may lower
+// that, never raise it.
+function topupUnitsForAccept(accept) {
+  const amount = accept && /^\d{1,30}$/.test(String(accept.amount)) ? Number(accept.amount) : 0;
+  const derived = Math.floor(amount / creditUnitPriceAtomic());
+  const explicit = accept && accept.extra ? Number(accept.extra.credits) : NaN;
+  return Number.isFinite(explicit) && explicit > 0 ? Math.min(Math.floor(explicit), derived) : derived;
+}
+
+// While the durable state has not been restored yet (boot, or a Supabase outage), balances read
+// as empty: a credit spend would wrongly say "insufficient credits" and a top-up could be lost if
+// the process died before the restore merged. Those routes answer 503 + Retry-After instead.
+let stateRestorePendingProbe = () => false;
+
+function setStateRestorePendingProbe(probe) {
+  stateRestorePendingProbe = typeof probe === "function" ? probe : () => false;
+}
+
+function isStateRestorePending() {
+  try {
+    return stateRestorePendingProbe() === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+const STATE_RESTORE_PENDING_RESPONSE = Object.freeze({
+  ok: false,
+  reason: "state_restore_pending",
+  detail: "Account balances are being restored after a restart. Retry in about 30 seconds; nothing was charged. Pay-per-call x402 (without payment_preference) works meanwhile."
+});
+
+module.exports = {
+  STATE_RESTORE_PENDING_RESPONSE,
+  isPrivateLedgerRead,
+  ledgerReadPolicyMode,
+  isStateRestorePending,
+  setStateRestorePendingProbe,
+  paidExecutionPolicyMode,
+  creditSpendPolicyMode,
+  isTestnetNetwork,
+  creditUnitPriceAtomic,
+  topupAmountMultiplier,
+  buildTopupAccepts,
+  topupUnitsForAccept
+};