@xochi/client 0.1.1 → 0.1.3

package/dist/cjs/shared/shieldedPreview.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Riddler's shielded terms preview wire (`POST /xochi/shielded/preview`,
+ * Riddler#1296): the typed request and response shapes and a decoder.
+ *
+ * There is NO transport method: the preview needs a `quote`-scoped Riddler
+ * credential, so only the Xochi Worker calls it, and the Worker proxy route is
+ * a follow-up owned by xochi#635. These shapes exist so that proxy and its
+ * consumers decode the solver's answer with the same schema the solver
+ * publishes (`packages/spec/wire/openapi.json`, `ShieldedPreviewResponse`).
+ *
+ * The preview is NOT a signing payload: `preview_digest` is the EIP-712 digest
+ * of `ShieldedPreviewV1` under the `Xochi Shielded Preview` domain, which no
+ * `ShieldedTermsV1` signature verifies against (`@xochi/spec`
+ * `conformance/shielded-terms.json`, PROPOSED). `executable` is always false.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldedPreviewResponseSchema = exports.ShieldedPreviewSchema = exports.ShieldedFeeBreakdownSchema = exports.ShieldedCorridorSchema = exports.ShieldedNetworkIdentitySchema = exports.aztecValue = void 0;
+exports.decodeShieldedPreview = decodeShieldedPreview;
+const zod_1 = require("zod");
+const schemas_js_1 = require("./schemas.js");
+/** 32-byte hex (`0x` + 64). */
+const bytes32 = zod_1.z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+/**
+ * A 32-byte Aztec address or field element. The decoder checks the shape only;
+ * the solver has already refused zero and values at or above the BN254 modulus.
+ * A 20-byte EVM address never fits.
+ */
+exports.aztecValue = bytes32;
+/** Canonical unsigned decimal string (uint256 members). */
+const uintString = zod_1.z.string().regex(/^(0|[1-9][0-9]*)$/);
+/** Canonical positive base-unit amount. */
+const baseUnits = zod_1.z.string().regex(/^[1-9][0-9]*$/);
+exports.ShieldedNetworkIdentitySchema = zod_1.z.object({
+    aztec_chain_id: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    protocol_version: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    rollup_address: schemas_js_1.ethAddress,
+    l1_chain_id: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    genesis_or_network_digest: bytes32,
+});
+exports.ShieldedCorridorSchema = zod_1.z.object({
+    corridor_id: bytes32,
+    revision: zod_1.z.number().int().min(1).max(4294967295),
+    manifest_digest: bytes32,
+});
+exports.ShieldedFeeBreakdownSchema = zod_1.z.object({
+    gas_floor: uintString,
+    solver_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    solver_fee: uintString,
+    price_impact_bps: zod_1.z.number().int().min(0).max(10000),
+    price_impact: uintString,
+    venue_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    venue_fee: uintString,
+    routing_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    routing_fee: uintString,
+    total_bps: zod_1.z.number().int().min(0).max(40000),
+    total_fee: uintString,
+});
+/** `ShieldedPreviewV1` in snake_case: the terms minus the per-execution members. */
+exports.ShieldedPreviewSchema = zod_1.z.object({
+    protocol_version: zod_1.z.literal("xochi.shielded.preview.v1"),
+    environment: zod_1.z.string().min(1),
+    source: zod_1.z.object({
+        chain_id: zod_1.z.number().int().positive(),
+        token_address: schemas_js_1.ethAddress,
+        wallet: schemas_js_1.ethAddress,
+        collector: schemas_js_1.ethAddress,
+        amount: baseUnits,
+    }),
+    destination: zod_1.z.object({
+        settlement_type: zod_1.z.literal("shielded"),
+        privacy_level: zod_1.z.literal("private"),
+        disclosure_profile: zod_1.z.literal("recipient-private-public-amount-v1"),
+        rail: zod_1.z.literal("a_tracer"),
+        network: exports.ShieldedNetworkIdentitySchema,
+        corridor: exports.ShieldedCorridorSchema,
+        asset_id: zod_1.z.string().min(1),
+        token_address: exports.aztecValue,
+        recipient_binding_id: zod_1.z.string().min(1),
+        recipient_descriptor_digest: bytes32,
+        recipient_address: exports.aztecValue,
+        amount: baseUnits,
+        fee_payer: exports.aztecValue,
+    }),
+    fee_breakdown: exports.ShieldedFeeBreakdownSchema,
+    refund_address: schemas_js_1.ethAddress,
+    refund_amount: baseUnits,
+    collect_before: zod_1.z.number().int().nonnegative(),
+    settlement_service_deadline: zod_1.z.number().int().nonnegative(),
+    recipient_binding_digest: bytes32,
+    policy_revision: zod_1.z.number().int().nonnegative(),
+});
+exports.ShieldedPreviewResponseSchema = zod_1.z.object({
+    executable: zod_1.z.literal(false),
+    preview_version: zod_1.z.literal("xochi.shielded.preview.v1"),
+    preview_digest: bytes32,
+    recipient_binding_digest: bytes32,
+    domain: zod_1.z.object({
+        name: zod_1.z.literal("Xochi Shielded Preview"),
+        version: zod_1.z.literal("1"),
+        chain_id: zod_1.z.number().int().positive(),
+        salt: bytes32,
+    }),
+    preview: exports.ShieldedPreviewSchema,
+    manifest: zod_1.z.object({
+        manifest_digest: bytes32,
+        aztec_sdk_version: zod_1.z.string().min(1),
+        recipient_account_class_id: exports.aztecValue,
+    }),
+});
+/**
+ * Decode a preview response. Throws (zod) on any shape the solver does not
+ * publish, including an executable or terms-shaped answer, and on a fee
+ * breakdown whose totals disagree: `total_fee` must be `max(gas_floor, layers)` (the gas
+ * floor is a minimum fee, as in FeePolicy) and `total_bps` the four rates.
+ */
+function decodeShieldedPreview(body) {
+    const decoded = exports.ShieldedPreviewResponseSchema.parse(body);
+    const f = decoded.preview.fee_breakdown;
+    const layers = BigInt(f.solver_fee) + BigInt(f.price_impact) + BigInt(f.venue_fee) + BigInt(f.routing_fee);
+    const gasFloor = BigInt(f.gas_floor);
+    const totalFee = layers > gasFloor ? layers : gasFloor;
+    const totalBps = f.solver_fee_bps + f.price_impact_bps + f.venue_fee_bps + f.routing_fee_bps;
+    if (BigInt(f.total_fee) !== totalFee || f.total_bps !== totalBps) {
+        throw new Error("shielded preview fee_breakdown totals disagree with max(gas_floor, layers)");
+    }
+    return decoded;
+}

package/dist/cjs/transport/client.d.ts

@@ -38,7 +38,7 @@ export interface RetryPolicy {
     maxAttempts: number;
     /** First exponential backoff step. */
     baseDelayMs: number;
-    /** Clamp on a server-supplied `Retry-After` used for internal pacing. */
+    /** Clamp on client-generated exponential backoff delays. */
     maxDelayMs: number;
 }
 export declare const DEFAULT_TIMEOUTS: TransportTimeouts;
@@ -119,8 +119,9 @@ export declare function takeApiErrorReadToken(error: unknown): string | undefine
 /**
  * Parse a Retry-After header (our API sends integer seconds) into milliseconds,
  * clamped to [0, maxDelayMs] so a malformed or hostile value can't stall the
- * client. Returns null when absent/unparseable so the caller falls back to its
- * own exponential backoff.
+ * client. The default safety ceiling preserves server-directed waits up to
+ * MAX_RETRY_WAIT_SEC; a custom ceiling can narrow them. Returns null when
+ * absent/unparseable so the caller falls back to its own exponential backoff.
  */
 export declare function parseRetryAfterMs(headerValue: string | null, maxDelayMs?: number): number | null;
 /**

package/dist/cjs/transport/client.js

@@ -138,11 +138,19 @@ function isNotAcceptedExecuteBody(status, body, intentId) {
  * MAX_RETRY_WAIT_SEC.
  */
 function notAcceptedRetryAt(headers, retryAfter) {
-    const header = headers.get("Retry-After");
-    const headerDelta = header === null || header.trim() === "" ? NaN : Number(header);
-    const wait = Number.isFinite(headerDelta) && headerDelta > retryAfter ? headerDelta : retryAfter;
+    const headerDelta = retryAfterDeltaSeconds(headers.get("Retry-After"));
+    const wait = headerDelta !== null && headerDelta > retryAfter ? headerDelta : retryAfter;
     return Math.ceil((Date.now() + Math.min(wait, exports.MAX_RETRY_WAIT_SEC) * 1000) / 1000);
 }
+/** Retry-After's delta-seconds grammar: optional HTTP whitespace around 1*DIGIT. */
+function retryAfterDeltaSeconds(headerValue) {
+    const value = headerValue?.trim();
+    if (!value || !/^\d+$/.test(value))
+        return null;
+    const seconds = Number(value);
+    // Syntactically valid integers beyond Number's range still take the 600 s cap.
+    return Number.isFinite(seconds) ? seconds : Number.MAX_SAFE_INTEGER;
+}
 /**
  * Read tokens held for the errors `execute` rejected with, keyed by the error
  * so the token is never reachable from the error itself (a crash reporter or a
@@ -647,14 +655,13 @@ function readTokenFromPrefix(prefix, intentId) {
 /**
  * Parse a Retry-After header (our API sends integer seconds) into milliseconds,
  * clamped to [0, maxDelayMs] so a malformed or hostile value can't stall the
- * client. Returns null when absent/unparseable so the caller falls back to its
- * own exponential backoff.
+ * client. The default safety ceiling preserves server-directed waits up to
+ * MAX_RETRY_WAIT_SEC; a custom ceiling can narrow them. Returns null when
+ * absent/unparseable so the caller falls back to its own exponential backoff.
  */
-function parseRetryAfterMs(headerValue, maxDelayMs = exports.DEFAULT_RETRY.maxDelayMs) {
-    if (!headerValue)
-        return null;
-    const seconds = Number(headerValue);
-    if (!Number.isFinite(seconds) || seconds < 0)
+function parseRetryAfterMs(headerValue, maxDelayMs = exports.MAX_RETRY_WAIT_SEC * 1000) {
+    const seconds = retryAfterDeltaSeconds(headerValue);
+    if (seconds === null)
         return null;
     return Math.min(seconds * 1000, maxDelayMs);
 }
@@ -702,12 +709,9 @@ function resolveRetryAfterSeconds(headers, body) {
     return Math.min(target, nowSec + exports.MAX_RETRY_WAIT_SEC);
 }
 function deriveRetryTarget(headers, body, nowSec) {
-    const retryAfterHeader = headers.get("Retry-After");
-    if (retryAfterHeader !== null) {
-        const delta = Number(retryAfterHeader);
-        if (Number.isFinite(delta) && delta >= 0)
-            return nowSec + delta;
-    }
+    const delta = retryAfterDeltaSeconds(headers.get("Retry-After"));
+    if (delta !== null)
+        return nowSec + delta;
     const reset = headers.get("X-RateLimit-Reset");
     if (reset !== null) {
         const abs = Number(reset);
@@ -1015,7 +1019,7 @@ function createXochiClient(options) {
                         // A 503 is a transient solver blip (saturation / gas-oracle
                         // unavailable); pace the retry off the server's Retry-After.
                         if (response.status === 503) {
-                            retryAfterMs = parseRetryAfterMs(response.headers.get("Retry-After"), retry.maxDelayMs);
+                            retryAfterMs = parseRetryAfterMs(response.headers.get("Retry-After"));
                         }
                         // A cut body does not parse, so it never carries the marker.
                         const record = truncated ? undefined : parseJsonObject(errorBody);
@@ -1071,7 +1075,7 @@ function createXochiClient(options) {
                 if (lastError.name === "AbortError")
                     break;
                 if (attempt < maxAttempts - 1) {
-                    const delay = retryAfterMs ?? retry.baseDelayMs * Math.pow(2, attempt);
+                    const delay = retryAfterMs ?? Math.min(retry.baseDelayMs * Math.pow(2, attempt), retry.maxDelayMs);
                     // A retry means the request already failed once: that is the context
                     // for the error below if the retries run out.
                     log("warn", `[xochi-client] Retry ${attempt + 1}/${maxAttempts} in ${delay}ms`);
@@ -1172,12 +1176,12 @@ function createXochiClient(options) {
                 return cached.quote;
             }
             const pending = pendingQuotes.get(requestHash);
-            if (pending && Date.now() - pending.timestamp < timeouts.requestTimeoutMs) {
+            if (pending) {
                 log("debug", "[xochi-client] Deduplicating quote request");
-                return pending.promise;
+                return pending;
             }
             const promise = fetchQuote(request);
-            pendingQuotes.set(requestHash, { promise, timestamp: Date.now() });
+            pendingQuotes.set(requestHash, promise);
             try {
                 const quote = await promise;
                 // Cache successful quotes -- EXCEPT pull-bearing ones. A quote carrying a
@@ -1190,7 +1194,8 @@ function createXochiClient(options) {
                 return quote;
             }
             finally {
-                pendingQuotes.delete(requestHash);
+                if (pendingQuotes.get(requestHash) === promise)
+                    pendingQuotes.delete(requestHash);
             }
         },
         invalidateQuote(request) {

package/dist/esm/machine/index.d.ts

@@ -7,7 +7,7 @@
  * Plus the wire decoders and the fund-safety gates the machine runs, exported
  * so the widget and headless integrators share one implementation of each.
  */
-export { init, update, QUOTE_DEBOUNCE_MS, QUOTE_REFRESH_BUFFER_MS, RECONCILE_AFTER_ATTEMPTS, SIGN_PROMPT_TIMEOUT_MS, type Model, type Msg, type MsgBody, type Effect, type ApiCall, type WalletCall, type TimerCall, type TimerName, type MachineEvent, type ErrorReport, type Context, type WalletContext, type Outcome, type StealthMetaAddress, type MachineConfig, type QuoteFlight, type SignFlow, type PollState, type ExecuteAttempt, } from "./machine.js";
+export { init, update, QUOTE_DEBOUNCE_MS, QUOTE_REFRESH_BUFFER_MS, RECONCILE_AFTER_ATTEMPTS, SIGN_PROMPT_TIMEOUT_MS, NOT_SENT_SWEPT_ERROR, type Model, type Msg, type MsgBody, type Effect, type ApiCall, type WalletCall, type TimerCall, type TimerName, type MachineEvent, type ErrorReport, type Context, type WalletContext, type Outcome, type StealthMetaAddress, type MachineConfig, type QuoteFlight, type SignFlow, type PollState, type ExecuteAttempt, } from "./machine.js";
 export { view } from "./view.js";
 export { payoutOf, costOf, settlementDisclosure, type Receipt, type Served, type PayoutSlot, type CostSlot, type QuoteSlot, type SigningSlot, type SettlementDisclosure, } from "./receipt.js";
 export { phaseFromStatus, type SwapPhase } from "./phase.js";

package/dist/esm/machine/index.js

@@ -7,7 +7,7 @@
  * Plus the wire decoders and the fund-safety gates the machine runs, exported
  * so the widget and headless integrators share one implementation of each.
  */
-export { init, update, QUOTE_DEBOUNCE_MS, QUOTE_REFRESH_BUFFER_MS, RECONCILE_AFTER_ATTEMPTS, SIGN_PROMPT_TIMEOUT_MS, } from "./machine.js";
+export { init, update, QUOTE_DEBOUNCE_MS, QUOTE_REFRESH_BUFFER_MS, RECONCILE_AFTER_ATTEMPTS, SIGN_PROMPT_TIMEOUT_MS, NOT_SENT_SWEPT_ERROR, } from "./machine.js";
 export { view } from "./view.js";
 export { payoutOf, costOf, settlementDisclosure, } from "./receipt.js";
 export { phaseFromStatus } from "./phase.js";

package/dist/esm/machine/machine.d.ts

@@ -44,6 +44,8 @@ export declare const RECONCILE_AFTER_ATTEMPTS: number;
  * for a real human to review + sign, short enough to recover from a dead prompt.
  */
 export declare const SIGN_PROMPT_TIMEOUT_MS = 90000;
+/** The error of a not-sent intent the poll finds gone (`onStatus`): the Retry view. */
+export declare const NOT_SENT_SWEPT_ERROR = "This order expired without being sent. Nothing moved.";
 export interface StealthMetaAddress {
     spendingPubKey: string;
     viewingPubKey: string;
@@ -219,6 +221,8 @@ export type MsgBody = {
     type: "SignRequested";
 } | {
     type: "PullSignRequested";
+} | {
+    type: "CancelSignRequested";
 } | {
     type: "ResetRequested";
 } | {

package/dist/esm/machine/machine.js

@@ -59,7 +59,7 @@ const QUOTE_DEADLINE_SECS = 3600;
 /** Log prefix. The host hook is still `useIntent`, and its logs are grepped for it. */
 const LOG = "[useIntent]";
 /** The error of a not-sent intent the poll finds gone (`onStatus`): the Retry view. */
-const NOT_SENT_SWEPT_ERROR = "This order expired without being sent. Nothing moved.";
+export const NOT_SENT_SWEPT_ERROR = "This order expired without being sent. Nothing moved.";
 export function init(config, ctx, hidden = false) {
     return {
         config,
@@ -156,6 +156,10 @@ function step(m, msg, fx) {
             return m.amount ? startQuote(m, fx, msg.now, quoteOpts(m.amount)) : m;
         case "SignRequested":
             return beginSign(m, fx, msg.now);
+        case "CancelSignRequested":
+            if (m.intent.status !== "signing" || !m.sign)
+                return m;
+            return transition(abandonSign(m, fx), fx, "quoted", { error: "Signature cancelled" });
         case "PullSignRequested":
             return beginPullSign(m, fx, msg.now);
         case "ResetRequested":
@@ -216,10 +220,15 @@ function step(m, msg, fx) {
             // Mobile throttles timers while backgrounded (a wallet deep-link
             // round-trip), so snap the in-flight phase forward rather than wait out
             // the interval. Off-interval: it spends no give-up budget. A pending
-            // resend reads no status; a return long past its time resends now.
+            // resend reads no status; a return long past its time resends now. A
+            // poll that exhausted its budget gets a fresh budget when the user
+            // returns instead of leaving a permanently stale receipt.
             if (awaitingResend(next))
                 next = resendBackstop(next, fx, msg.now);
-            else if (next.poll && !next.poll.stopped)
+            else if (next.poll?.stopped) {
+                next = { ...patch(next, { pollExhausted: false }), poll: null };
+            }
+            else if (next.poll)
                 next = pollTick(next, fx, false);
             return next;
         }
@@ -717,8 +726,9 @@ function onTimer(m, fx, timer, now) {
                 return resendBackstop(m, fx, now);
             return m.poll && !m.poll.stopped ? pollTick(m, fx, true) : m;
         case "signPrompt":
-            // A deep-link prompt that never re-opened the wallet.
-            return m.sign?.stage === "pull"
+            // A wallet prompt that never resolved. The flow still owns the prompt;
+            // `signFlowFailed` makes any reply arriving after this timer inert.
+            return m.sign
                 ? signFlowFailed(m, fx, {
                     rejected: false,
                     value: "wallet_prompt_timeout",
@@ -826,6 +836,10 @@ function beginSign(m, fx, now) {
             chainId: next.ctx.wallet.chainId,
         },
     });
+    // A wallet request can be dismissed without rejecting (mobile deep links in
+    // particular). Bound every prompt, including signature 1, so the ceremony
+    // always returns to an actionable surface.
+    setTimer(fx, "signPrompt", SIGN_PROMPT_TIMEOUT_MS, false);
     return { ...next, sign: { id, origin: "sign", stage: "intent", intentSignature: null } };
 }
 function beginPullSign(m, fx, now) {
@@ -926,8 +940,7 @@ function onSigned(m, fx, flowId, purpose, result, now) {
     // open; its signature then belongs to no ceremony.
     if (m.intent.status !== "signing")
         return abandonSign(m, fx);
-    if (purpose === "pull")
-        clearTimer(fx, "signPrompt");
+    clearTimer(fx, "signPrompt");
     if (!result.ok)
         return signFlowFailed(m, fx, result.error);
     if (purpose === "pull") {
@@ -1210,7 +1223,7 @@ function endSignFlow(m, flow) {
  * affordance, no prompt timer. Nothing signed so far can execute after this.
  */
 function abandonSign(m, fx) {
-    if (m.sign?.stage === "pull")
+    if (m.sign)
         clearTimer(fx, "signPrompt");
     if (awaitingResend(m))
         clearTimer(fx, "execute");
@@ -1226,12 +1239,16 @@ function signFlowFailed(m, fx, report) {
     const flow = m.sign;
     if (!flow)
         return m;
-    if (flow.stage === "pull")
-        clearTimer(fx, "signPrompt");
+    clearTimer(fx, "signPrompt");
     const next = endSignFlow(m, flow);
     if (flow.origin === "sign") {
         if (report.rejected)
             return transition(next, fx, "quoted", { error: "Signature rejected" });
+        if (report.value === "wallet_prompt_timeout") {
+            return transition(next, fx, "quoted", {
+                error: "Couldn't reach the wallet. Press Confirm to try again.",
+            });
+        }
         log(fx, "error", `${LOG} Sign error:`, report.detail);
         return transition(next, fx, "failed", { error: report.value ?? "Signing failed" });
     }
@@ -1300,15 +1317,20 @@ function onStatus(m, fx, gen, attempt, result, now) {
     if (!poll || poll.gen !== gen || poll.stopped)
         return m;
     const id = poll.intentId;
+    // Replies can race (an interval read and a visibility read). Once a newer
+    // reply has answered, an older one cannot regress lifecycle or receipt
+    // fields, including clearing a newer not-sent verdict.
+    if (result.ok && attempt < poll.answered)
+        return m;
     let next = m;
-    // A resumed `executing` intent (a reload: no quote in this tab, so no sign
-    // flow and no execute from it can be in flight or answer late) that reads
-    // `quoted`: the Worker's row is unclaimed and the signed request, held
-    // elsewhere, executes until its deadline. Not sent yet, as after a give-up,
-    // never "Still confirming" (whose Close invites a second signature). An
-    // intent in doubt stays so, and so does one a newer reply already answered:
-    // a late `quoted` is no answer after a newer `executing`.
-    const resumedUnsent = attempt >= poll.answered &&
+    // An `executing` intent that reads `quoted` after /execute has answered is
+    // unclaimed. Its signed request remains executable until the deadline, so
+    // this is "not sent yet", never "Still confirming" (whose Close invites a
+    // second signature). Do not use a status read while /execute is outstanding:
+    // `armPoll` delays the first read until that reply, preventing a stale
+    // pre-acceptance `quoted` answer from winning. An intent already in doubt
+    // stays so, as does one whose newer status reply already answered.
+    const unsentRead = attempt >= poll.answered &&
         result.ok &&
         !!result.status &&
         !("notFound" in result.status) &&
@@ -1316,14 +1338,14 @@ function onStatus(m, fx, gen, attempt, result, now) {
         result.status.unmapped !== true &&
         next.intent.intentId === id &&
         next.intent.status === "executing" &&
-        next.intent.quote === null &&
+        next.sign === null &&
         !next.intent.reconciling;
     // A throw answers nothing, so only a reply (a 404 included) moves it.
     const answered = result.ok
         ? { ...poll, answered: Math.max(poll.answered, attempt) }
         : poll;
-    if (resumedUnsent && !next.intent.notSent) {
-        log(fx, "warn", `${LOG} Resumed intent ${id} reads quoted: not sent yet`);
+    if (unsentRead && !next.intent.notSent) {
+        log(fx, "warn", `${LOG} Intent ${id} reads quoted after execute: not sent yet`);
         next = patch(next, { notSent: true });
     }
     // A slow execute escalates to "Still confirming"; one not sent (`notSent`)
@@ -1405,15 +1427,15 @@ function onStatus(m, fx, gen, attempt, result, now) {
             next = patch(next, { legsWithheld });
         }
         // The server owns the active-polling decision; a phase change refills the
-        // give-up budget, so the ceiling bounds a swap that is not moving. A read
-        // the intent cannot move to (`quoted` after an execute) is no change: the
-        // ceiling, sized past the Worker's finish (`pollCeilingAttempts`), holds.
-        // A resumed not-sent intent has no quote to size it by, so each `quoted`
-        // read refills it: the Worker's read finish ends the row past its
-        // deadline, which this poll's own reads trigger.
+        // give-up budget, so the ceiling bounds a swap that is not moving. A
+        // resumed not-sent intent has no quote from which to size the Worker's
+        // finish, so each `quoted` read refills its budget until the Worker ends
+        // the row. A live intent has a quote and remains bounded by its fixed
+        // ceiling even after it enters not-sent.
+        const resumedNotSent = unsentRead && next.intent.notSent && next.intent.quote === null;
         verdict = s.terminal
             ? "stop"
-            : next.intent.status !== previous || (resumedUnsent && next.intent.notSent)
+            : next.intent.status !== previous || resumedNotSent
                 ? "progress"
                 : undefined;
     }
@@ -1581,7 +1603,11 @@ function armExpiry(m, fx, now) {
 function armPoll(m, fx, now) {
     const { intentId, status } = m.intent;
     const waiting = awaitingResend(m);
-    const key = POLL_INFLIGHT_STATES.includes(status) && intentId
+    // The execute reply establishes whether the request was accepted. Reading
+    // status before it answers can return the pre-acceptance `quoted` row and
+    // falsely decide "not sent"; the reply (including a timeout) arms the poll.
+    const executePending = m.sign?.stage === "execute" && !waiting;
+    const key = !executePending && POLL_INFLIGHT_STATES.includes(status) && intentId
         ? `${intentId}:${status}${waiting ? ":resend" : ""}`
         : null;
     if (key === (m.poll?.key ?? null))

package/dist/esm/machine/state.d.ts

@@ -66,10 +66,11 @@ export interface IntentState {
     /**
      * True while the latest status poll was the server's anonymous view of a
      * stealth or shielded intent (xochi#563): its on-chain legs were withheld, so
-     * null hashes mean "not shown", not "not there". The host offers wallet SIWE
-     * recovery on it; a later owner read (no marker) clears it. Never a token.
+     * null hashes mean "not shown", not "not there". False after an owner read.
+     * Null until the first status reply, so the host does not render an owner
+     * verdict before it has read one. Never a token.
      */
-    legsWithheld: boolean;
+    legsWithheld: boolean | null;
     reconciling: boolean;
     /** Plain-language refund explanation; set only on a `refunded` status. */
     refundReason: string | null;

package/dist/esm/machine/state.js

@@ -12,7 +12,7 @@ export const INITIAL_INTENT_STATE = {
     settlementTxHash: null,
     settlementChainId: null,
     substatus: null,
-    legsWithheld: false,
+    legsWithheld: null,
     reconciling: false,
     refundReason: null,
     quotedAddress: null,

package/dist/esm/shared/index.d.ts

@@ -13,3 +13,4 @@ export * from "./validators.js";
 export * from "./schemas.js";
 export * from "./api.js";
 export * from "./intentStream.js";
+export * from "./shieldedPreview.js";

package/dist/esm/shared/index.js

@@ -13,3 +13,4 @@ export * from "./validators.js";
 export * from "./schemas.js";
 export * from "./api.js";
 export * from "./intentStream.js";
+export * from "./shieldedPreview.js";

package/dist/esm/shared/schemas.js

@@ -388,9 +388,9 @@ export const QuoteResponseSchema = z
     // Optional: the POST omits it, and the GET omits it too on a pull-less route.
     nonce: z.number().int().min(0).optional(),
     error: z.string().optional(),
-    // Present on the unsolvable-200 branch: `error_category` is a stable machine
-    // key for the reject class, `detail` the solver's raw reason. Absent on
-    // solvable quotes.
+    // Present on declined quotes: `error_category` is a stable machine key for
+    // the reject class, `detail` the solver's raw reason. Absent on solvable
+    // quotes.
     //
     // Enumerated so the generated spec documents the vocabulary agents branch on,
     // and so adding a category without declaring it fails the contract tests.
@@ -405,7 +405,7 @@ export const QuoteResponseSchema = z
     error_category: z
         .string()
         .optional()
-        .describe("Stable machine key for a declined quote. Branch on this rather than on `error`, whose prose may change. Known values: gas_floor_unpriced (transient, retry), origin_pull_amount_mismatch, served_payout_mismatch, settlement_type_unavailable, stealth_factory_untrusted, refund_address_invalid, amount_too_large, amount_too_small, no_liquidity, route_unsupported, invalid_request (the request shape was rejected, not the route -- see `detail` for the offending field), auth, unknown. Treat an unrecognized value as a non-retryable decline."),
+        .describe("Stable machine key for a declined quote. Branch on this rather than on `error`, whose prose may change. Known values: gas_floor_unpriced (transient, retry), conversion_unavailable (transient price verification, retry), inventory_unverified (transient, retry), quote_holds_exhausted (transient, retry), idempotency_key_in_flight (transient, retry with the same key), idempotency_unavailable (transient, retry with the same key), origin_pull_amount_mismatch, served_payout_mismatch, settlement_type_unavailable, stealth_factory_untrusted, refund_address_invalid, amount_too_large, amount_too_small, no_liquidity, route_unsupported, invalid_request (the request shape was rejected, not the route -- see `detail` for the offending field), auth, unknown. Treat an unrecognized value as a non-retryable decline."),
     detail: z.string().optional(),
     // Present when `error_category` is `amount_too_small` because the route's
     // FIXED settlement cost consumed too much of the order: the smallest order