@xochi/client 0.0.0-stage → 0.1.1

package/dist/esm/machine/machine.js

@@ -0,0 +1,1609 @@
+/**
+ * The quote -> sign -> execute -> status lifecycle as a pure state machine.
+ *
+ *     update(model, msg) -> [model, effects]
+ *
+ * `update` is the only place lifecycle state changes. Everything it cannot do
+ * itself -- an HTTP call, a wallet prompt, a timer, a log line -- it asks for as
+ * an `Effect`, which is plain JSON. A host (the React interpreter in the widget,
+ * or a headless integrator) performs the effect and feeds the outcome back as a
+ * `Msg`. Every `Msg` is stamped with the clock and tab visibility it was
+ * observed under, so a recorded msg log replays to the same models, effects and
+ * receipts with no mocks.
+ *
+ * The one exception to that clock is the fund-safety checks from
+ * `@xochi/signer` that run at quote ingest: they bound the intent deadline and
+ * the deposit window against the WALL clock, and take no `now` argument by
+ * design, since an injectable clock on a security assertion is a bypass.
+ *
+ * No DOM, no fetch, no React, no wagmi, no console: the machine compiles
+ * against `lib: ["ES2020"]` alone (tsconfig.machine.json).
+ */
+import { canTransitionTo, EXECUTE_RESEND_MARGIN_SECS, isChainId, MAX_EXECUTE_RESENDS, } from "../shared/index.js";
+import { buildQuoteRequest, buildResumedState, canSignQuote, computeRefreshDelayMs, executeDeadline, decideExecuteResend, decideExecuteResult, decideSignPreflight, failureMayHaveMoved, mapStatusUpdate, mergeSameStatusReceipt, notFoundDriftWarning, pollCeilingAttempts, normalizeTradeFields, quoteAccessDecision, shouldRefreshOnReturn, shouldRefreshQuote, shouldUpgradePreviewQuote, POLL_INFLIGHT_STATES, ALLOCATABLE_STATES, ENDED_STATES, unexecutedFinishAt, QUOTE_BUSY_STATES, STATUS_POLL_FLAT_CEILING_MS, STATUS_POLL_MS, WALLET_INTERRUPTIBLE_STATES, } from "./decisions.js";
+import { claimInfoError } from "./claimInfo.js";
+import { DEPOSIT_MIN_WINDOW_SECONDS } from "@xochi/signer";
+import { checkDepositQuote, recipientIsDestinationToken, } from "./deposit.js";
+import { checkSignableQuote } from "./quoteChecks.js";
+import { recipientEchoError } from "./recipientEcho.js";
+import { validatePayoutPin, validateSolverPin } from "./solverPin.js";
+import { INITIAL_INTENT_STATE } from "./state.js";
+import { applyStatusTransition } from "./transition.js";
+import { validateSwapParams } from "./validateRequest.js";
+import { decodeWireStatus, withheldSettlementConfirmed } from "./wire.js";
+// ============================================================
+// Configuration
+// ============================================================
+/** Amount edits settle for this long before a quote is requested. */
+export const QUOTE_DEBOUNCE_MS = 500;
+/**
+ * Refresh this long before expiry. Exported so the panel countdown pill can
+ * align "New price in Ns" with the actual refresh instant.
+ */
+export const QUOTE_REFRESH_BUFFER_MS = 5000;
+/**
+ * After this many polls in one phase without reaching a terminal state, flip the
+ * modal from an indefinite "Submitting" spinner to the reassuring "Still
+ * confirming" (safe-to-close) view. Reconciliation/webhooks still resolve it;
+ * this only fixes the feedback gap. ~90s at the shared cadence.
+ */
+export const RECONCILE_AFTER_ATTEMPTS = Math.ceil(90_000 / STATUS_POLL_MS);
+/**
+ * If a wallet signature prompt never resolves (a mobile deep-link that failed to
+ * re-open the wallet), stop waiting after this and surface a retry. Long enough
+ * for a real human to review + sign, short enough to recover from a dead prompt.
+ */
+export const SIGN_PROMPT_TIMEOUT_MS = 90_000;
+/** Quote requests ask for a one-hour signing deadline. */
+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 function init(config, ctx, hidden = false) {
+    return {
+        config,
+        ctx,
+        hidden,
+        intent: INITIAL_INTENT_STATE,
+        amount: "",
+        allocationKey: null,
+        awaitingPull: false,
+        isSigningPull: false,
+        pendingIntentSig: null,
+        quoteExpiresIn: null,
+        submittedAt: null,
+        clientFillMs: null,
+        notFoundReported: null,
+        seq: 0,
+        flights: [],
+        sign: null,
+        poll: null,
+        refresh: null,
+        quotedTrade: null,
+        seenDepositAddresses: {},
+        watched: { wallet: "", upgrade: "", expiry: null },
+    };
+}
+// ============================================================
+// update
+// ============================================================
+export function update(model, msg) {
+    const fx = [];
+    const stamped = model.hidden === msg.hidden ? model : { ...model, hidden: msg.hidden };
+    const stepped = step(stamped, msg, fx);
+    return [settle(stepped, msg.now, fx), fx];
+}
+function step(m, msg, fx) {
+    switch (msg.type) {
+        case "ContextChanged": {
+            const next = { ...m, ctx: msg.ctx };
+            if (m.flights.length === 0 || tradeKey(next.ctx) === tradeKey(m.ctx))
+                return next;
+            // The quotes in the air were built from the old trade; their answers
+            // describe a deal no longer on the form, so none of them may land.
+            if (m.intent.status === "quoting" && m.amount) {
+                // A visible quote was loading: ask again for the trade now on the form.
+                setTimer(fx, "debounce", QUOTE_DEBOUNCE_MS, false);
+            }
+            return supersedeFlights(next, fx);
+        }
+        case "QuoteRequested": {
+            clearTimer(fx, "debounce");
+            clearTimer(fx, "refresh");
+            // A quote still in the air for another amount answers a question nobody
+            // is asking any more; left in place it could land over the newer one.
+            const kept = msg.amount === m.amount ? m : supersedeFlights(m, fx);
+            const next = { ...kept, allocationKey: null, amount: msg.amount, refresh: null };
+            if (!msg.amount || msg.amount === "0") {
+                // "May have moved" holds until Reset, and "not sent yet" until the
+                // Worker ends the intent: clearing the amount is no way out of either.
+                if ((m.intent.status === "failed" && m.intent.mayHaveMoved) || m.intent.notSent) {
+                    return next;
+                }
+                // Including any half-finished two-step signing: the next quote must not
+                // inherit "Sign 2 of 2" or a held intent signature.
+                return abandonSign({ ...next, intent: INITIAL_INTENT_STATE }, fx);
+            }
+            setTimer(fx, "debounce", QUOTE_DEBOUNCE_MS, false);
+            return next;
+        }
+        case "AllocateRequested": {
+            // Only before execution: past quoting (a prompt open, a deposit awaited,
+            // a swap in flight) or once the trade has ended (completed, refunded,
+            // failed) a new quote has nothing to land on, and its failure would
+            // patch the finished trade back to `quoted` over its consumed route.
+            if (!m.amount ||
+                isChainId(m.ctx.fromChainId) ||
+                !m.ctx.wallet.address ||
+                !ALLOCATABLE_STATES.includes(m.intent.status)) {
+                emit(fx, { kind: "allocation", ref: msg.ref, ok: false });
+                return m;
+            }
+            const key = m.allocationKey ?? msg.key;
+            return startQuote({ ...m, allocationKey: key }, fx, msg.now, {
+                amount: m.amount,
+                silent: false,
+                forceRefresh: true,
+                allocate: { key, ref: msg.ref },
+            });
+        }
+        case "RefreshRequested":
+            if (QUOTE_BUSY_STATES.includes(m.intent.status)) {
+                log(fx, "debug", `${LOG} Ignoring quote request during`, m.intent.status);
+                return m;
+            }
+            return m.amount ? startQuote(m, fx, msg.now, quoteOpts(m.amount)) : m;
+        case "SignRequested":
+            return beginSign(m, fx, msg.now);
+        case "PullSignRequested":
+            return beginPullSign(m, fx, msg.now);
+        case "ResetRequested":
+            clearTimer(fx, "debounce");
+            clearTimer(fx, "refresh");
+            clearTimer(fx, "signPrompt");
+            if (awaitingResend(m))
+                clearTimer(fx, "execute");
+            fx.push({ type: "Wallet", call: { op: "resetApproval" } });
+            return {
+                ...supersedeFlights(m, fx),
+                intent: INITIAL_INTENT_STATE,
+                amount: "",
+                submittedAt: null,
+                clientFillMs: null,
+                awaitingPull: false,
+                isSigningPull: false,
+                pendingIntentSig: null,
+                allocationKey: null,
+                refresh: null,
+                quotedTrade: null,
+                sign: null,
+            };
+        case "ResumeRequested": {
+            const resumed = buildResumedState(m.intent, msg.intentId, msg.status, msg.owner, msg.depositDeadline);
+            if (resumed === m.intent)
+                return m;
+            // A stored failure is Retry only on the Worker's own nothing-moved marker:
+            // the reload cannot know whether this tab sent an execute for it.
+            const intent = resumed.status === "failed"
+                ? { ...resumed, mayHaveMoved: failureMayHaveMoved(msg.substatus) }
+                : resumed;
+            // The adopt supersedes any quote still queued for the form. The panel
+            // restores the record's amount before it adopts (the adopt waits on the
+            // stored deposit proof), and that amount change queues a debounced quote.
+            // Left armed, it fires once the arming poll has moved the intent to a
+            // terminal status, which QUOTE_BUSY_STATES does not cover, and the fresh
+            // quote replaces the receipt with a signable confirm for the same trade.
+            // A quote already in the air (a Tron allocation waiting on sign-in) would
+            // land over the resumed intent the same way, so it goes too.
+            clearTimer(fx, "debounce");
+            return { ...supersedeFlights(m, fx), intent };
+        }
+        case "VisibilityChanged": {
+            if (msg.hidden)
+                return m;
+            let next = m;
+            // A backgrounded tab stops refreshing quotes, so a returning user could be
+            // looking at a stale or expired price: pull one fresh quote now.
+            if (next.amount &&
+                shouldRefreshOnReturn({
+                    status: next.intent.status,
+                    paused: next.ctx.paused,
+                    hasAllocatedDeposit: !!next.intent.quote?.depositAddress,
+                })) {
+                next = startQuote(next, fx, msg.now, { ...quoteOpts(next.amount), forceRefresh: true });
+            }
+            // 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.
+            if (awaitingResend(next))
+                next = resendBackstop(next, fx, msg.now);
+            else if (next.poll && !next.poll.stopped)
+                next = pollTick(next, fx, false);
+            return next;
+        }
+        case "StreamStatus":
+            // The stream may still be relaying an intent this model has moved past
+            // (a reset, a fresh quote): its frames must not drive the current one.
+            if (msg.message.intentId !== m.intent.intentId) {
+                log(fx, "warn", `${LOG} Ignoring a status frame for another intent:`, {
+                    frame: msg.message.intentId,
+                    current: m.intent.intentId,
+                });
+                return m;
+            }
+            // Applied by the poll's rule (`applyStatusUpdate`): a `failed` frame
+            // after an execute ends "may have moved" unless it carries the marker.
+            return applyStatusUpdate(m, fx, msg.message, false);
+        case "TimerFired":
+            return onTimer(m, fx, msg.timer, msg.now);
+        case "SessionReplied":
+            return onSession(m, fx, msg.flight, msg.result, msg.now);
+        case "QuoteReplied":
+            return onQuote(m, fx, msg.flight, msg.result, msg.now);
+        case "SignReplied":
+            return onSigned(m, fx, msg.flow, msg.purpose, msg.result, msg.now);
+        case "ApprovalReplied":
+            return onApproval(m, fx, msg.flow, msg.result);
+        case "ExecuteReplied":
+            return onExecuted(m, fx, msg.flow, msg.result, msg.now);
+        case "StatusReplied":
+            return onStatus(m, fx, msg.gen, msg.attempt, msg.result, msg.now);
+    }
+}
+// ============================================================
+// Effect helpers
+// ============================================================
+function setTimer(fx, timer, ms, repeat) {
+    fx.push({ type: "Timer", call: { op: "set", timer, ms, repeat } });
+}
+function clearTimer(fx, timer) {
+    fx.push({ type: "Timer", call: { op: "clear", timer } });
+}
+function emit(fx, event) {
+    fx.push({ type: "Emit", event });
+}
+function log(fx, level, message, ...data) {
+    emit(fx, { kind: "log", level, message, data });
+}
+function nextId(m, prefix) {
+    const seq = m.seq + 1;
+    return [`${prefix}${seq}`, { ...m, seq }];
+}
+function patch(m, updates) {
+    return { ...m, intent: { ...m.intent, ...updates } };
+}
+/**
+ * A validated status move; an invalid one is logged and leaves the intent as
+ * it was. Leaving the ceremony (`signing`, or `executing` with its /execute
+ * reply outstanding) for anything but `signing -> executing` (a rejection, a
+ * refusal, a status update that got there first) ends it, so a late wallet or
+ * execute reply has nothing to act on. Entering a state past quoting drops
+ * every quote still in the air: its answer describes a trade that has moved on.
+ */
+function transition(m, fx, to, updates) {
+    const intent = applyStatusTransition(m.intent, to, canTransitionTo, updates);
+    if (intent === m.intent) {
+        log(fx, "warn", `${LOG} Invalid transition: ${m.intent.status} -> ${to}`);
+        return m;
+    }
+    const from = m.intent.status;
+    // "Not sent yet" describes an `executing` this client stopped resending.
+    let next = { ...m, intent: intent.notSent ? { ...intent, notSent: false } : intent };
+    if (QUOTE_BUSY_STATES.includes(to) && !QUOTE_BUSY_STATES.includes(from)) {
+        next = supersedeFlights(next, fx);
+    }
+    // `signing -> executing` keeps the ceremony only as the machine's own
+    // execute step (runExecute stages the flow first); a status update making
+    // the same move must not leave a pull prompt or "Sign 2 of 2" live.
+    const ownExecute = to === "executing" && next.sign?.stage === "execute";
+    const leftCeremony = from === "executing" || (from === "signing" && !ownExecute);
+    return leftCeremony ? abandonSign(next, fx) : next;
+}
+function quoteOpts(amount) {
+    return { amount, silent: false, forceRefresh: false, allocate: null };
+}
+function endAllocation(fx, flight, ok) {
+    if (flight.allocate)
+        emit(fx, { kind: "allocation", ref: flight.allocate.ref, ok });
+}
+function withoutFlight(m, id) {
+    return { ...m, flights: m.flights.filter((f) => f.id !== id) };
+}
+function putFlight(m, flight) {
+    return { ...m, flights: [...m.flights.filter((f) => f.id !== flight.id), flight] };
+}
+/** Drop every quote still in flight: a newer ask has made their answers moot. */
+function supersedeFlights(m, fx) {
+    if (m.flights.length === 0)
+        return m;
+    for (const flight of m.flights)
+        endAllocation(fx, flight, false);
+    return { ...m, flights: [] };
+}
+function startQuote(m, fx, now, opts) {
+    // "May have moved" holds until Reset: no quote lands over it and offers the
+    // trade again before the user has checked what the last order did.
+    if (m.intent.status === "failed" && m.intent.mayHaveMoved) {
+        log(fx, "debug", `${LOG} Ignoring quote request: the last order may have moved funds`);
+        endAllocation(fx, opts, false);
+        return m;
+    }
+    const ctx = m.ctx;
+    const address = ctx.wallet.address;
+    const depositOrigin = !isChainId(ctx.fromChainId);
+    const access = quoteAccessDecision({
+        connected: !!address,
+        settlementPreference: ctx.settlementPreference,
+        isDepositOrigin: depositOrigin,
+        allocateDepositRoute: !!opts.allocate,
+    });
+    if (access === "needs_wallet") {
+        endAllocation(fx, opts, false);
+        return patch(m, { error: "Connect a wallet to quote this route" });
+    }
+    const preview = access === "preview";
+    const [id, next] = nextId(m, "q");
+    const flight = {
+        id,
+        stage: "session",
+        amount: opts.amount,
+        silent: opts.silent,
+        forceRefresh: opts.forceRefresh,
+        allocate: opts.allocate,
+        ctx,
+        depositOrigin,
+        preview,
+        request: null,
+    };
+    // A Tron-origin executable quote allocates a durable solver route before any
+    // intent signature exists. Prove the EVM wallet first so the worker can bind
+    // and quota that allocation.
+    if (depositOrigin && !preview) {
+        if (opts.silent && !address)
+            return next;
+        fx.push({
+            type: "Wallet",
+            call: { op: "ensureSession", flight: id, interactive: !opts.silent },
+        });
+        return putFlight(next, flight);
+    }
+    return sendQuote(next, fx, flight, now);
+}
+function onSession(m, fx, id, result, now) {
+    const flight = m.flights.find((f) => f.id === id && f.stage === "session");
+    if (!flight)
+        return m;
+    // A session flight may start on a finished trade (a new Tron quote after a
+    // completed one), so only a ceremony or a swap in flight makes it stale.
+    if (QUOTE_BUSY_STATES.includes(m.intent.status))
+        return dropStaleFlight(m, fx, flight);
+    if (result === "ok")
+        return sendQuote(m, fx, flight, now);
+    const next = withoutFlight(m, id);
+    endAllocation(fx, flight, false);
+    if (flight.silent)
+        return next;
+    const error = "Wallet sign-in is required to allocate a Tron deposit route";
+    return flight.allocate
+        ? allocationFailed(next, error)
+        : patch(next, { status: "failed", error, quote: null });
+}
+/**
+ * A quote reply that finds the trade past quoting: the intent it would patch
+ * is no longer the one it was asked for. Logged and dropped, never applied.
+ */
+function dropStaleFlight(m, fx, flight) {
+    log(fx, "warn", `${LOG} Dropping a quote reply: intent is ${m.intent.status}`, flight.id);
+    endAllocation(fx, flight, false);
+    return withoutFlight(m, flight.id);
+}
+function sendQuote(m, fx, flight, now) {
+    const ctx = flight.ctx;
+    // Fail-closed on the stealth key precondition: the keys derive from a wallet
+    // signature and land a moment after `settlement` flips to stealth. Hold the
+    // request; the host re-quotes once they arrive. A visible hold also lets go of
+    // the quote on screen: it was served for another settlement, and leaving it
+    // `quoted` would keep it signable after the user asked for stealth.
+    if (ctx.settlementPreference === "stealth" && !ctx.stealthMetaAddress) {
+        endAllocation(fx, flight, false);
+        const next = withoutFlight(m, flight.id);
+        return flight.silent ? next : transition(next, fx, "quoting", { quote: null, error: null });
+    }
+    const request = buildQuoteRequest({
+        wallet: flight.preview ? undefined : (ctx.wallet.address ?? undefined),
+        preview: flight.preview,
+        allocationKey: flight.allocate?.key,
+        fromChainId: ctx.fromChainId,
+        toChainId: ctx.toChainId,
+        fromToken: ctx.fromToken,
+        toToken: ctx.toToken,
+        fromAmount: flight.amount,
+        deadline: Math.floor(now / 1000) + QUOTE_DEADLINE_SECS,
+        slippageBps: ctx.slippageBps,
+        trustScore: ctx.trustScore,
+        settlementPreference: ctx.settlementPreference,
+        recipientAddress: ctx.recipientAddress ?? undefined,
+        refundAddress: ctx.refundAddress ?? undefined,
+        stealthMetaAddress: ctx.stealthMetaAddress ?? undefined,
+    });
+    const validation = validateSwapParams(request, now);
+    if (!validation.isValid) {
+        // Logged before the silent bail: a refresh that stops validating is the
+        // first sign the panel and the request have drifted apart.
+        log(fx, "warn", `${LOG} Quote request failed validation:`, validation.errors);
+        endAllocation(fx, flight, false);
+        const next = withoutFlight(m, flight.id);
+        if (flight.silent)
+            return next;
+        return patch(next, {
+            status: "failed",
+            error: validation.errors[0] || "Invalid swap parameters",
+        });
+    }
+    const next = flight.silent ? m : transition(m, fx, "quoting");
+    fx.push({
+        type: "Api",
+        call: { op: "quote", flight: flight.id, request, forceRefresh: flight.forceRefresh },
+    });
+    return putFlight(next, { ...flight, stage: "api", request });
+}
+/** A quote the gates refused: logged always, applied only when not silent. */
+function refuseQuote(m, fx, flight, updates) {
+    endAllocation(fx, flight, false);
+    if (flight.silent)
+        return m;
+    return transition(m, fx, "failed", updates);
+}
+/** The request or the proof threw: keep the confirm surface intact when silent. */
+function quoteThrew(m, fx, flight, report) {
+    log(fx, "error", `${LOG} Quote error:`, report.detail);
+    endAllocation(fx, flight, false);
+    if (flight.silent)
+        return m;
+    const error = report.value ?? "Quote request failed";
+    return flight.allocate
+        ? allocationFailed(m, error)
+        : patch(m, { status: "failed", error, quote: null });
+}
+/**
+ * An allocation that did not land leaves the indicative price on screen. Only
+ * a trade still before execution returns to `quoted`; any other status is
+ * kept, so a failure never revives an ended trade over its consumed quote.
+ */
+function allocationFailed(m, error) {
+    return ALLOCATABLE_STATES.includes(m.intent.status)
+        ? patch(m, { status: "quoted", error })
+        : patch(m, { error });
+}
+function onQuote(model, fx, id, result, now) {
+    const flight = model.flights.find((f) => f.id === id && f.stage === "api");
+    if (!flight)
+        return model;
+    // The request moved the intent to `quoting` (or was silent over `quoted`):
+    // finding it at a prompt, a swap in flight, delivered or refunded means the
+    // trade went on without this answer, which may then neither fail it nor
+    // replace its quote.
+    const status = model.intent.status;
+    if (QUOTE_BUSY_STATES.includes(status) || ENDED_STATES.includes(status)) {
+        return dropStaleFlight(model, fx, flight);
+    }
+    const m = withoutFlight(model, id);
+    if (!result.ok)
+        return quoteThrew(m, fx, flight, result.error);
+    const quote = result.quote;
+    const ctx = flight.ctx;
+    const address = ctx.wallet.address;
+    if (!quote.success) {
+        log(fx, "warn", `${LOG} Quote request rejected:`, quote.error);
+        return refuseQuote(m, fx, flight, { error: quote.error || "Failed to get quote", quote: null });
+    }
+    if (!quote.canSolve) {
+        // Surface the solver's real reason; ErrorDisplay maps these codes to copy.
+        log(fx, "warn", `${LOG} Quote not solvable:`, quote.error);
+        return refuseQuote(m, fx, flight, {
+            error: quote.error || "No liquidity available for this route",
+            quote,
+        });
+    }
+    // Whether this is a preview is OUR question, not the server's answer: a
+    // wallet-bound request answered `preview: true` would otherwise skip the
+    // signer checks and still reach Confirm, and an executable answer to a
+    // preview request was never bound to a wallet.
+    if ((quote.preview === true) !== flight.preview) {
+        log(fx, "error", `${LOG} Refusing a quote that answers the wrong kind of request`, {
+            requestedPreview: flight.preview,
+            servedPreview: quote.preview === true,
+        });
+        return refuseQuote(m, fx, flight, {
+            error: "This quote did not match the requested trade, so it cannot be signed.",
+            quote: null,
+        });
+    }
+    // Non-EVM destination: the solvable quote must echo exactly the recipient we
+    // asked for, or the funds would route to an unconfirmed destination (#113).
+    const echoError = recipientEchoError(flight.request?.recipientAddress, quote.recipientAddress);
+    if (echoError) {
+        log(fx, "warn", `${LOG} Recipient echo rejected:`, echoError);
+        return refuseQuote(m, fx, flight, {
+            error: "Couldn't confirm the destination address for this route. Please try again.",
+            quote: null,
+        });
+    }
+    // Stealth: the served factory decides who owns the payout account (#302).
+    const claimError = claimInfoError(quote.claimInfo, ctx.toChainId);
+    if (claimError) {
+        log(fx, "error", `${LOG} Stealth claim info rejected:`, claimError.code, quote.claimInfo);
+        return refuseQuote(m, fx, flight, {
+            error: `${claimError.message}. Send this one public, or try again later.`,
+            quote: null,
+        });
+    }
+    // The RESOLVED payout address: the request's recipient, or the wallet.
+    const resolvedRecipient = ctx.recipientAddress?.trim() || address || "";
+    // Never pay the destination token contract (raxol#869). Runs on EVERY route.
+    if (recipientIsDestinationToken(resolvedRecipient, ctx.toToken)) {
+        log(fx, "error", `${LOG} Refusing a quote whose payout recipient is the destination token`, {
+            recipient: resolvedRecipient,
+            toToken: ctx.toToken,
+        });
+        return refuseQuote(m, fx, flight, {
+            error: "That destination address is the token's own contract. Funds sent there cannot be recovered.",
+            quote: null,
+        });
+    }
+    // What we know from the origin chain and what the server sent must agree on
+    // "is this a deposit route", or a substituted quote picks its own code path.
+    if ((quote.preview && !!quote.depositAddress) ||
+        (!quote.preview && flight.depositOrigin !== !!quote.depositAddress)) {
+        log(fx, "error", `${LOG} Deposit-route disagreement between origin chain and quote`, {
+            isDepositOrigin: flight.depositOrigin,
+            preview: quote.preview === true,
+            hasDepositAddress: !!quote.depositAddress,
+            fromChainId: ctx.fromChainId,
+        });
+        return refuseQuote(m, fx, flight, {
+            error: "This route is not available right now.",
+            quote: null,
+        });
+    }
+    const request = flight.request;
+    if (!quote.depositAddress) {
+        // A signable quote: hold the served intent to the request and the origin
+        // pull to the intent (`@xochi/signer`) before it can reach the wallet.
+        // Whatever else the quote claims: any intent it carries is checked, and a
+        // quote with no intent to sign is refused at Confirm ("No quote to sign").
+        if (quote.eip712Data) {
+            const check = request
+                ? checkSignableQuote(request, quote, m.config.pullRecipients)
+                : { ok: false, kind: "intent_mismatch", reason: "no request on record" };
+            if (!check.ok) {
+                log(fx, "error", `${LOG} Refusing a quote that does not match the request:`, check.kind, check.reason);
+                return refuseQuote(m, fx, flight, {
+                    error: "This quote did not match the requested trade, so it cannot be signed.",
+                    quote: null,
+                });
+            }
+        }
+        return acceptQuote(m, fx, flight, quote, null, now);
+    }
+    // Deposit route: the v3 attestation binds the whole deal, and is verified
+    // against the pinned signer before the address can ever be shown. The
+    // RESOLVED settlement type and a real wallet are required; a default would
+    // produce a binding that proves nothing.
+    const resolvedSettlement = quote.settlementType;
+    if (!resolvedSettlement || !request?.wallet) {
+        return attestationRejected(m, fx, flight, {
+            ok: false,
+            kind: "unavailable",
+            reason: !resolvedSettlement
+                ? "quote did not state a resolved settlement type (route.settlement_type)"
+                : "no connected wallet to bind the deposit attestation to",
+        });
+    }
+    // The signer rebuilds the signed message from the REQUEST, settlement
+    // preference included, so a quote served under another settlement type cannot
+    // verify. Refused here first, under its own reason: on a stealth request it is
+    // a privacy downgrade, and as a bare recovery failure it reads as tampering.
+    if (resolvedSettlement !== request.settlementPreference) {
+        return attestationRejected(m, fx, flight, {
+            ok: false,
+            kind: "unavailable",
+            reason: `quote resolved settlement type ${resolvedSettlement} but ${request.settlementPreference} was requested`,
+        });
+    }
+    const verdict = checkDepositQuote(request, quote, m.config.depositAttestationSigner, m.seenDepositAddresses);
+    if (!verdict.ok)
+        return attestationRejected(m, fx, flight, verdict);
+    return acceptQuote({ ...m, seenDepositAddresses: verdict.seen }, fx, flight, quote, verdict.stored, now);
+}
+function attestationRejected(m, fx, flight, verdict) {
+    log(fx, "warn", `${LOG} Deposit attestation rejected:`, verdict.kind, verdict.reason);
+    return refuseQuote(m, fx, flight, {
+        // `addressReuse` is the per-session tripwire, and a reload clears it.
+        error: verdict.kind === "addressReuse"
+            ? "We were given a deposit address that was already in use. Reload the page and try again."
+            : "This deposit route is not available right now.",
+        quote: null,
+    });
+}
+function acceptQuote(m, fx, flight, quote, attestedDeposit, now) {
+    const address = flight.ctx.wallet.address;
+    const quoteState = {
+        intentId: quote.intentId,
+        quoteId: quote.quoteId,
+        quote,
+        error: null,
+        // A fresh quote is a fresh attempt: whatever stopped the last Confirm no
+        // longer describes this one.
+        refusal: null,
+        refundReason: null,
+        quotedAddress: quote.preview ? null : address,
+        quotedChainId: flight.ctx.wallet.chainId,
+        quotedFromAmount: flight.amount,
+        quotedSettlement: flight.request?.settlementPreference ?? flight.ctx.settlementPreference,
+        depositDeadline: quote.depositAddress ? (quote.depositDeadline ?? null) : null,
+        attestedDeposit,
+    };
+    let next;
+    if (flight.silent) {
+        // Never overwrite the quote the user is signing.
+        if (m.intent.status !== "quoted")
+            return m;
+        next = patch(m, quoteState);
+    }
+    else if (m.intent.status === "quoted") {
+        // A deduplicated in-flight request answering twice: refresh in place
+        // rather than ask for an invalid quoted -> quoted edge.
+        next = patch(m, { ...quoteState, pollExhausted: false });
+    }
+    else {
+        // A fresh quote is a fresh poll budget.
+        next = transition(m, fx, "quoted", { ...quoteState, pollExhausted: false });
+    }
+    // Only if it landed: a refused move leaves the old quote, and its trade, held.
+    if (next.intent.quote === quote)
+        next = { ...next, quotedTrade: tradeKey(flight.ctx) };
+    const refreshMs = computeRefreshDelayMs(quote.expiry, now, QUOTE_REFRESH_BUFFER_MS);
+    if (refreshMs > 0) {
+        // Clear-before-arm is the set itself (one timer per name), so a refresh
+        // reached without requestQuote never forks a second refresh loop.
+        setTimer(fx, "refresh", refreshMs, false);
+        next = {
+            ...next,
+            refresh: { amount: flight.amount, hasAllocatedDeposit: !!quote.depositAddress },
+        };
+    }
+    endAllocation(fx, flight, true);
+    return next;
+}
+// ============================================================
+// Timers
+// ============================================================
+function onTimer(m, fx, timer, now) {
+    switch (timer) {
+        case "debounce":
+            if (QUOTE_BUSY_STATES.includes(m.intent.status)) {
+                log(fx, "debug", `${LOG} Ignoring quote request during`, m.intent.status);
+                return m;
+            }
+            return m.amount ? startQuote(m, fx, now, quoteOpts(m.amount)) : m;
+        case "refresh": {
+            const plan = m.refresh;
+            if (!plan)
+                return m;
+            const next = { ...m, refresh: null };
+            if (!shouldRefreshQuote({
+                status: next.intent.status,
+                hidden: next.hidden,
+                hasAllocatedDeposit: plan.hasAllocatedDeposit,
+            })) {
+                return next;
+            }
+            // Silent under an open confirm surface; forced so it replaces the
+            // expiring quote rather than re-serving it from cache.
+            return startQuote(next, fx, now, {
+                amount: plan.amount,
+                silent: next.ctx.paused,
+                forceRefresh: true,
+                allocate: null,
+            });
+        }
+        case "expiry":
+            return tickExpiry(m, fx, now);
+        case "poll":
+            if (awaitingResend(m))
+                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"
+                ? signFlowFailed(m, fx, {
+                    rejected: false,
+                    value: "wallet_prompt_timeout",
+                    detail: "wallet_prompt_timeout",
+                })
+                : m;
+        case "execute":
+            return resendExecute(m, fx, now);
+    }
+}
+function tickExpiry(m, fx, now) {
+    const expiry = m.intent.quote?.expiry;
+    if (!expiry)
+        return m;
+    const remaining = Math.max(0, Math.floor((new Date(expiry).getTime() - now) / 1000));
+    const next = { ...m, quoteExpiresIn: remaining };
+    return remaining === 0 ? transition(next, fx, "expired", { error: "Quote expired" }) : next;
+}
+// ============================================================
+// Sign & execute
+// ============================================================
+function signPreflight(m, now) {
+    const expiry = m.intent.quote?.expiry;
+    return decideSignPreflight({
+        hasDepositAddress: false,
+        hasEip712: true,
+        address: m.ctx.wallet.address ?? undefined,
+        quotedAddress: m.intent.quotedAddress,
+        quotedChainId: m.intent.quotedChainId,
+        chainId: m.ctx.wallet.chainId ?? undefined,
+        originChainId: m.ctx.fromChainId,
+        expiryMs: expiry ? new Date(expiry).getTime() : 0,
+        now,
+    });
+}
+function beginSign(m, fx, now) {
+    // Confirm acts on a held quote only. A second Confirm while the wallet is
+    // open (or after signature 1, awaiting the pull) is not a new attempt: it
+    // must neither raise a prompt nor end the live ceremony, whose late
+    // signature would otherwise still execute behind a refusal.
+    if (m.intent.status !== "quoted")
+        return m;
+    const quote = m.intent.quote;
+    // The same gate the receipt renders from: a preview or a declined quote is
+    // never signable, whatever it carries.
+    if (!quote || !canSignQuote(m.intent.status, quote))
+        return patch(m, { error: "No quote to sign" });
+    // Nor a quote for another trade: after an edit the held quote stays on
+    // screen (priced at its own amount) until its replacement lands, but the
+    // wallet must never be asked to sign, or a deposit address revealed, for a
+    // trade the form no longer describes.
+    if (!holdsCurrentQuote(m)) {
+        log(fx, "warn", `${LOG} Not signing a quote for a trade no longer on the form`, {
+            quotedFromAmount: m.intent.quotedFromAmount,
+            amount: m.amount,
+        });
+        return m;
+    }
+    // Deposit route: no signature, no /execute. Revealing the address drives
+    // the poll to a terminal state once the solver detects the deposit.
+    if (quote.depositAddress) {
+        // The deposit window was checked at ingest, but an allocated route is
+        // never refreshed or expired by the price countdown, so it can sit on the
+        // screen past its attested deadline. Revealing it then hands the user an
+        // address whose deposit is refunded rather than filled.
+        const deadline = m.intent.depositDeadline;
+        if (deadline === null || deadline - Math.floor(now / 1000) < DEPOSIT_MIN_WINDOW_SECONDS) {
+            log(fx, "warn", `${LOG} Not revealing a deposit address past its window`, {
+                depositDeadline: deadline,
+                now: Math.floor(now / 1000),
+            });
+            return transition(m, fx, "expired", { error: "Quote expired" });
+        }
+        return transition(m, fx, "awaiting_deposit");
+    }
+    if (!quote.eip712Data)
+        return patch(m, { error: "No quote to sign" });
+    const preflight = signPreflight(m, now);
+    if (preflight.kind === "reject") {
+        return preflight.to === "quoted"
+            ? patch(m, { refusal: preflight.refusal })
+            : transition(m, fx, preflight.to, { error: preflight.error });
+    }
+    // Bind the DESTINATION leg before the wallet is prompted: the signed
+    // `recipient` and `toAmount` must be what this client rendered.
+    const payoutPin = validatePayoutPin(quote.eip712Data, {
+        toAmount: quote.toAmount,
+        recipient: m.ctx.recipientAddress?.trim() || m.ctx.wallet.address || undefined,
+    });
+    if (!payoutPin.ok) {
+        log(fx, "error", `${LOG} Refusing to sign intent:`, payoutPin);
+        return patch(m, { refusal: { kind: "payout_mismatch" } });
+    }
+    const signing = transition(m, fx, "signing", { refusal: null });
+    if (signing.intent.status !== "signing")
+        return signing;
+    const [id, next] = nextId(signing, "s");
+    fx.push({
+        type: "Wallet",
+        call: {
+            op: "signTypedData",
+            flow: id,
+            purpose: "intent",
+            typedData: quote.eip712Data,
+            chainId: next.ctx.wallet.chainId,
+        },
+    });
+    return { ...next, sign: { id, origin: "sign", stage: "intent", intentSignature: null } };
+}
+function beginPullSign(m, fx, now) {
+    const signature = m.pendingIntentSig;
+    if (!signature || !m.intent.quote?.pullAuthorization || m.isSigningPull || m.sign)
+        return m;
+    const preflight = signPreflight(m, now);
+    if (preflight.kind === "reject") {
+        // Back to the quote, whatever the reason: `signing` has no edge to
+        // `expired`, and an expired quote landing on `quoted` is expired by the
+        // countdown in this same update.
+        return transition({ ...m, awaitingPull: false }, fx, "quoted", { error: preflight.error });
+    }
+    const [id, next] = nextId({ ...m, isSigningPull: true }, "s");
+    return completePull(next, fx, {
+        id,
+        origin: "pull",
+        stage: "approval",
+        intentSignature: signature,
+    });
+}
+/** Read a served base-units amount, or report it the way a thrown BigInt was. */
+function readAmount(raw) {
+    try {
+        return BigInt(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { rejected: false, value: detail, detail };
+    }
+}
+/** Origin-pull leg, step 1: the one-time approval (Permit2; ERC-3009 no-ops). */
+function completePull(m, fx, flow) {
+    const pull = m.intent.quote?.pullAuthorization;
+    const eip712 = m.intent.quote?.eip712Data;
+    if (!pull || !eip712)
+        return endSignFlow(m, flow);
+    const amount = readAmount(eip712.message?.fromAmount || m.intent.quotedFromAmount || "0");
+    if (typeof amount !== "bigint")
+        return signFlowFailed({ ...m, sign: flow }, fx, amount);
+    fx.push({
+        type: "Wallet",
+        call: { op: "ensureApproval", flow: flow.id, amount: amount.toString() },
+    });
+    return { ...m, sign: { ...flow, stage: "approval" } };
+}
+function onApproval(m, fx, flowId, result) {
+    const flow = m.sign;
+    if (!flow || flow.id !== flowId || flow.stage !== "approval")
+        return m;
+    if (!result.ok)
+        return signFlowFailed(m, fx, result.error);
+    if (!result.approved) {
+        return transition(m, fx, "quoted", {
+            error: "Token approval required to continue",
+            refusal: { kind: "approval_required" },
+        });
+    }
+    const pull = m.intent.quote?.pullAuthorization;
+    const eip712 = m.intent.quote?.eip712Data;
+    if (!pull || !eip712)
+        return endSignFlow(m, flow);
+    // Fail-closed solver pin (#333, #170): never sign a pull whose recipient is
+    // not the pinned solver, nor whose amount exceeds the intended input. The
+    // amount is anchored to the user's own quoted input (what the intent was
+    // requested and signed at), not a served field and not the live form.
+    const expected = readAmount(m.intent.quotedFromAmount || eip712.message?.fromAmount || "0");
+    if (typeof expected !== "bigint")
+        return signFlowFailed(m, fx, expected);
+    const pin = validateSolverPin(pull, m.config.solverPin, expected);
+    if (!pin.ok) {
+        log(fx, "error", `${LOG} Refusing to sign origin pull:`, pin);
+        return transition(m, fx, "quoted", {
+            error: `Refusing to sign origin pull: ${pin.reason}`,
+            refusal: { kind: "pull_unpinned" },
+        });
+    }
+    fx.push({
+        type: "Wallet",
+        call: {
+            op: "signTypedData",
+            flow: flow.id,
+            purpose: "pull",
+            typedData: pull,
+            chainId: m.ctx.wallet.chainId,
+        },
+    });
+    // Bound the prompt: a deep-link that never re-opens the wallet would
+    // otherwise wait forever.
+    setTimer(fx, "signPrompt", SIGN_PROMPT_TIMEOUT_MS, false);
+    return { ...m, sign: { ...flow, stage: "pull" } };
+}
+function onSigned(m, fx, flowId, purpose, result, now) {
+    const flow = m.sign;
+    if (!flow || flow.id !== flowId || flow.stage !== purpose)
+        return m;
+    // A status update can carry the intent past `signing` while a prompt is
+    // open; its signature then belongs to no ceremony.
+    if (m.intent.status !== "signing")
+        return abandonSign(m, fx);
+    if (purpose === "pull")
+        clearTimer(fx, "signPrompt");
+    if (!result.ok)
+        return signFlowFailed(m, fx, result.error);
+    if (purpose === "pull") {
+        return runExecute({ ...m, awaitingPull: false }, fx, flow, flow.intentSignature ?? "", result.signature, now);
+    }
+    const next = { ...m, pendingIntentSig: result.signature };
+    const signed = { ...flow, intentSignature: result.signature };
+    // No origin pull to authorize: execute on the single signature.
+    if (!next.intent.quote?.pullAuthorization) {
+        return runExecute(next, fx, signed, result.signature, undefined, now);
+    }
+    // A deep-link wallet will not re-open for a second back-to-back prompt, so
+    // the pull waits for an explicit tap ("Sign 2 of 2"). Injected wallets
+    // prompt fine in sequence and keep the single-gesture flow.
+    if (next.ctx.wallet.stepwise)
+        return { ...next, awaitingPull: true, sign: null };
+    return completePull(next, fx, signed);
+}
+/**
+ * Dispatch /execute with the collected signatures. Everything after this is
+ * POST-dispatch, so a failure is in doubt rather than terminal (#226), except
+ * the one the server proves accepted nothing (`onNotAccepted`).
+ */
+function runExecute(m, fx, flow, signature, pullSignature, now) {
+    // Only a live ceremony dispatches: a signature that lands after the intent
+    // left `signing` (refused, reset, re-quoted) must not execute.
+    if (m.intent.status !== "signing") {
+        log(fx, "warn", `${LOG} Dropping signature: intent is ${m.intent.status}, not signing`);
+        return abandonSign(m, fx);
+    }
+    const request = {
+        intentId: m.intent.intentId ?? "",
+        quoteId: m.intent.quoteId ?? "",
+        signature,
+        nonce: now,
+        pullSignature,
+    };
+    // The flow is marked `execute` before the move, so `transition` can tell
+    // this step from a status update that skipped the ceremony.
+    const staged = {
+        ...m,
+        sign: {
+            ...flow,
+            stage: "execute",
+            execute: { request, resends: 0, resendAt: null, error: null },
+        },
+    };
+    const executing = transition(staged, fx, "executing");
+    if (executing.intent.status !== "executing")
+        return abandonSign(m, fx);
+    // Fill clock starts here: the signed intent is now with the solver.
+    const next = { ...executing, submittedAt: now, clientFillMs: null };
+    fx.push({ type: "Api", call: { op: "execute", flow: flow.id, request } });
+    return next;
+}
+function onExecuted(m, fx, flowId, result, now) {
+    const flow = m.sign;
+    // While a resend is pending no request is in flight, so nothing answers.
+    if (!flow || flow.id !== flowId || flow.stage !== "execute" || awaitingResend(m))
+        return m;
+    const report = notAcceptedReport(result);
+    const handled = report ? onNotAccepted(m, fx, flow, report, now) : null;
+    if (handled)
+        return handled;
+    const next = endSignFlow({ ...m, pendingIntentSig: null }, flow);
+    // Every error here is POST-dispatch and therefore IN-DOUBT (the origin pull
+    // may have moved funds): flag reconciling and let the poll resolve it (#226).
+    // So is a reply that cannot be read as this intent's execute response.
+    const reply = executeResponseUnlessInDoubt(fx, result, next.intent.intentId);
+    if (!reply)
+        return patch(next, { reconciling: true });
+    // The Worker answers `quoted` for this intent when it ended its own claim
+    // and could not finish the intent (a fault while finishing an unexecuted
+    // claim): nothing is in flight, and the signed request stays executable
+    // until its deadline, exactly as after a give-up. "Not sent yet", no Retry;
+    // an intent that already reads in doubt stays so, as on a not-accepted
+    // refusal (`onNotAccepted`).
+    if (!reply.response.success &&
+        reply.response.status === "quoted" &&
+        next.intent.status === "executing" &&
+        !next.intent.reconciling) {
+        log(fx, "warn", `${LOG} Execute ended unclaimed (the intent reads quoted); not sent yet`);
+        return patch(next, {
+            notSent: true,
+            error: reply.response.error || "The order was not sent.",
+        });
+    }
+    const decision = decideExecuteResult(reply.response);
+    if (decision.kind === "failed") {
+        return transition(next, fx, "failed", {
+            error: decision.error,
+            mayHaveMoved: decision.mayHaveMoved,
+        });
+    }
+    // An unmapped status is applied as an in-flight bucket and shown in doubt,
+    // as an unmapped status poll is (`applyStatusUpdate`).
+    const updates = reply.unmapped ? { ...decision.updates, reconciling: true } : decision.updates;
+    // Inline fill: the execute round-trip bounds submit -> filled exactly.
+    const timed = decision.status === "completed" && next.submittedAt !== null
+        ? { ...next, clientFillMs: now - next.submittedAt }
+        : next;
+    const moved = transition(timed, fx, decision.status, updates);
+    // A refused move (the reply names the status the intent is already in, or
+    // one it cannot reach) must not drop an in-doubt verdict with it.
+    return updates.reconciling === true && moved.intent === timed.intent
+        ? patch(moved, { reconciling: true })
+        : moved;
+}
+/** A thrown execute's report carrying the not-accepted flag (`true`, nothing else), read defensively. */
+function notAcceptedReport(result) {
+    const reply = result;
+    return reply?.ok === false && reply.error?.notAccepted === true
+        ? reply.error
+        : null;
+}
+/**
+ * The server refused this execute before accepting anything: wait for the
+ * refusal's `retryAfter` and send the SAME request again (`resendExecute`)
+ * within `decideExecuteResend`'s bounds, else stop resending
+ * (`stopResending`). Null, leaving the reply in doubt like any other thrown
+ * execute, when the intent already reads in doubt (rules: README "Fund
+ * safety").
+ */
+function onNotAccepted(m, fx, flow, report, now) {
+    const attempt = flow.execute;
+    const intentId = m.intent.intentId;
+    if (!attempt ||
+        intentId === null ||
+        attempt.request.intentId !== intentId ||
+        m.intent.status !== "executing" ||
+        m.intent.reconciling) {
+        log(fx, "warn", `${LOG} Execute not accepted, but kept in doubt: the intent already is`);
+        return null;
+    }
+    const error = report.value ?? "The solver is busy. Try again.";
+    const decision = decideExecuteResend({
+        resends: attempt.resends,
+        retryAfter: typeof report.value === "object" ? report.value?.retryAfter : undefined,
+        deadline: executeDeadline(m.intent.quote),
+        now,
+    });
+    if (decision.kind === "give_up") {
+        log(fx, "warn", `${LOG} Execute not accepted; not resending (${decision.reason})`);
+        return stopResending({ ...m, pendingIntentSig: null }, flow, error);
+    }
+    log(fx, "warn", `${LOG} Execute not accepted (solver busy); resend ${attempt.resends + 1}/${MAX_EXECUTE_RESENDS} in ${decision.delayMs}ms`, report.detail);
+    setTimer(fx, "execute", decision.delayMs, false);
+    return {
+        ...m,
+        pendingIntentSig: null,
+        sign: { ...flow, execute: { ...attempt, resendAt: now + decision.delayMs, error } },
+    };
+}
+/**
+ * The not-accepted wait is over: send the held request again, unchanged, under
+ * a new flow id. A wait that ends past the deadline (a throttled background
+ * tab) stops resending instead (`stopResending`).
+ */
+function resendExecute(m, fx, now) {
+    const flow = m.sign;
+    const attempt = flow?.execute;
+    if (!flow || !attempt || !awaitingResend(m) || m.intent.status !== "executing")
+        return m;
+    const deadline = executeDeadline(m.intent.quote);
+    if (deadline === null || now > (deadline - EXECUTE_RESEND_MARGIN_SECS) * 1000) {
+        log(fx, "warn", `${LOG} Execute not accepted; the deadline passed before the resend`);
+        return stopResending(m, flow, attempt.error ?? "The solver is busy. Try again.");
+    }
+    const [id, next] = nextId(m, "s");
+    fx.push({ type: "Api", call: { op: "execute", flow: id, request: attempt.request } });
+    return {
+        ...next,
+        submittedAt: now,
+        sign: {
+            ...flow,
+            id,
+            execute: { ...attempt, resends: attempt.resends + 1, resendAt: null, error: null },
+        },
+    };
+}
+/**
+ * This client gives up resending a not-accepted execute. No Retry: the
+ * Worker un-claimed the intent, so it reads `quoted` and the signed request
+ * stays executable until its deadline (by anyone holding it). The intent
+ * stays `executing`, marked `notSent` ("not sent yet"), and the poll, re-armed
+ * off the resend wait, runs until the Worker ends the intent (README "Fund
+ * safety"): `failed` with `NOT_EXECUTED_SUBSTATUS`, or a 404 past its finish
+ * (`onStatus`), is Retry; any other read ends the mark (`applyStatusUpdate`).
+ */
+function stopResending(m, flow, error) {
+    return patch(endSignFlow(m, flow), { notSent: true, error });
+}
+/**
+ * A poll tick while a resend waits reads no status (the server holds nothing
+ * to report). The first tick (or returning tab) at or after `resendAt` with
+ * the resend still pending does the `execute` timer's work, in case the host
+ * never scheduled it: `resendExecute` resends, or past the deadline fails with
+ * the refusal. The poll interval bounds how late that is (`STATUS_POLL_MS`).
+ */
+function resendBackstop(m, fx, now) {
+    const resendAt = m.sign?.execute?.resendAt;
+    if (typeof resendAt !== "number" || now < resendAt)
+        return m;
+    log(fx, "warn", `${LOG} The resend is due and still pending; resending from the poll timer`);
+    clearTimer(fx, "execute");
+    return resendExecute(m, fx, now);
+}
+/** A not-accepted execute is waiting for its resend: no request is in flight. */
+function awaitingResend(m) {
+    return m.sign?.stage === "execute" && typeof m.sign.execute?.resendAt === "number";
+}
+/**
+ * The execute response a reply carries for `intentId`, its status decoded
+ * (`decodeWireStatus`), or null when the execute is in doubt: a reported
+ * failure, or a reply the machine cannot read as an execute response for this
+ * intent (malformed, or another intent's response; intent ids compare
+ * exactly). Checked here rather than trusted from the host: the verdict
+ * decides whether Retry is offered on a swap whose funds may have moved. A
+ * granular failure (`fill_failed`) decodes to `failed` with the granular
+ * status as its substatus, so it is never the Worker's nothing-moved marker.
+ * Read defensively, since a replayed or foreign message need not match its
+ * type.
+ */
+function executeResponseUnlessInDoubt(fx, result, intentId) {
+    const reply = result;
+    if (reply?.ok === false) {
+        log(fx, "warn", `${LOG} Execute in-doubt; polling to resolve:`, reply.error?.detail);
+        return null;
+    }
+    const response = reply?.ok === true ? reply.response : undefined;
+    if (!isRelayedExecuteReply(response)) {
+        log(fx, "error", `${LOG} Execute reply is not an execute response; in doubt, polling`);
+        return null;
+    }
+    if (response.intentId !== intentId) {
+        log(fx, "error", `${LOG} Execute reply names another intent; in doubt, polling`, {
+            reply: response.intentId,
+            current: intentId,
+        });
+        return null;
+    }
+    const { readToken, status, ...rest } = response;
+    if (readToken !== undefined) {
+        // Never read, stored or echoed: the host already put it in the message.
+        log(fx, "warn", `${LOG} Execute reply carried a readToken; keep it outside the machine`);
+    }
+    const decoded = decodeWireStatus(status);
+    const granularFailure = decoded.status === "failed" && status !== "failed";
+    return {
+        response: {
+            ...rest,
+            status: decoded.status,
+            ...(granularFailure ? { substatus: status } : {}),
+        },
+        unmapped: decoded.kind === "unmapped",
+    };
+}
+/** The fields `decideExecuteResult` reads, each of its wire type (`status` any string). */
+function isRelayedExecuteReply(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const r = value;
+    const optional = (v, type) => v === undefined || typeof v === type;
+    return (typeof r.success === "boolean" &&
+        typeof r.intentId === "string" &&
+        typeof r.status === "string" &&
+        optional(r.reconciling, "boolean") &&
+        optional(r.settlementChainId, "number") &&
+        optional(r.error, "string") &&
+        optional(r.txHash, "string") &&
+        optional(r.receivingTxHash, "string") &&
+        optional(r.settlementTxHash, "string") &&
+        optional(r.substatus, "string"));
+}
+function endSignFlow(m, flow) {
+    return { ...m, sign: null, isSigningPull: flow.origin === "pull" ? false : m.isSigningPull };
+}
+/**
+ * End the whole sign ceremony: no flow, no held intent signature, no step-2
+ * affordance, no prompt timer. Nothing signed so far can execute after this.
+ */
+function abandonSign(m, fx) {
+    if (m.sign?.stage === "pull")
+        clearTimer(fx, "signPrompt");
+    if (awaitingResend(m))
+        clearTimer(fx, "execute");
+    return { ...m, sign: null, pendingIntentSig: null, awaitingPull: false, isSigningPull: false };
+}
+/**
+ * A wallet step failed. From Confirm, a rejection returns to the confirm
+ * surface and anything else fails the intent. From the "Sign 2 of 2" tap, a
+ * rejection cancels back to confirm, and a dead or hung prompt KEEPS the step-2
+ * affordance so the user can retry with the held intent signature.
+ */
+function signFlowFailed(m, fx, report) {
+    const flow = m.sign;
+    if (!flow)
+        return m;
+    if (flow.stage === "pull")
+        clearTimer(fx, "signPrompt");
+    const next = endSignFlow(m, flow);
+    if (flow.origin === "sign") {
+        if (report.rejected)
+            return transition(next, fx, "quoted", { error: "Signature rejected" });
+        log(fx, "error", `${LOG} Sign error:`, report.detail);
+        return transition(next, fx, "failed", { error: report.value ?? "Signing failed" });
+    }
+    if (report.rejected) {
+        return transition({ ...next, awaitingPull: false }, fx, "quoted", {
+            error: "Signature rejected",
+        });
+    }
+    log(fx, "error", `${LOG} Pull sign error:`, report.detail);
+    return patch(next, {
+        error: "Couldn't reach the wallet. Tap to try the second signature again.",
+    });
+}
+// ============================================================
+// Status
+// ============================================================
+/**
+ * Apply one status update (poll or stream). A same-status update is not a
+ * transition -- the table has no self-edges, and routing it through one would
+ * discard the receipt hashes it carries (xochi#353) -- so its receipt fields
+ * merge directly. An UNMAPPED wire status (`decodeWireStatus`) never reads as
+ * progress: the intent shows "Still confirming" (reconciling), never success.
+ * A `failed` after an execute or a revealed deposit address (any
+ * `POLL_INFLIGHT_STATES`) is Retry only with the Worker's nothing-moved
+ * marker; any other ends "may have moved" (`failureMayHaveMoved`), and either
+ * way the poll stops. "Not sent yet" (`notSent`) holds only while the intent
+ * reads `quoted`: any other read means an execute reached it, shown in doubt.
+ */
+function applyStatusUpdate(m, fx, msg, unmapped) {
+    log(fx, "debug", `${LOG} Status update:`, msg);
+    const plan = mapStatusUpdate(msg);
+    let next;
+    if (plan.status === m.intent.status) {
+        const updates = mergeSameStatusReceipt(m.intent, msg);
+        next = updates ? patch(m, updates) : m;
+    }
+    else {
+        const updates = plan.status === "failed" && POLL_INFLIGHT_STATES.includes(m.intent.status)
+            ? { ...plan.updates, mayHaveMoved: failureMayHaveMoved(msg.substatus) }
+            : plan.updates;
+        next = transition(m, fx, plan.status, updates);
+    }
+    if (unmapped && POLL_INFLIGHT_STATES.includes(next.intent.status) && !next.intent.reconciling) {
+        next = patch(next, { reconciling: true });
+    }
+    if (next.intent.notSent && plan.status !== "quoted") {
+        next = patch(next, { notSent: false, reconciling: true });
+    }
+    return next;
+}
+function pollTick(m, fx, elapsedInterval) {
+    const poll = m.poll;
+    if (!poll)
+        return m;
+    const polls = poll.polls + 1;
+    const spent = elapsedInterval ? poll.spent + 1 : poll.spent;
+    fx.push({
+        type: "Api",
+        call: { op: "status", intentId: poll.intentId, gen: poll.gen, attempt: polls },
+    });
+    return { ...m, poll: { ...poll, polls, spent } };
+}
+function onStatus(m, fx, gen, attempt, result, now) {
+    const poll = m.poll;
+    // A reply from a disarmed poll (a phase change, a reset, a stop) is dropped.
+    if (!poll || poll.gen !== gen || poll.stopped)
+        return m;
+    const id = poll.intentId;
+    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 &&
+        result.ok &&
+        !!result.status &&
+        !("notFound" in result.status) &&
+        result.status.status === "quoted" &&
+        result.status.unmapped !== true &&
+        next.intent.intentId === id &&
+        next.intent.status === "executing" &&
+        next.intent.quote === 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`);
+        next = patch(next, { notSent: true });
+    }
+    // A slow execute escalates to "Still confirming"; one not sent (`notSent`)
+    // has nothing in flight to confirm.
+    if (attempt >= RECONCILE_AFTER_ATTEMPTS &&
+        next.intent.intentId === id &&
+        !next.intent.reconciling &&
+        !next.intent.notSent) {
+        next = patch(next, { reconciling: true });
+    }
+    let verdict;
+    if (!result.ok) {
+        // A throw is not a change: count the attempt and keep the ceiling armed.
+        log(fx, "error", `${LOG} status poll threw; counting the attempt`, result.error.detail);
+    }
+    else if (result.status && "notFound" in result.status) {
+        const finish = unexecutedFinishAt(next.intent.quote);
+        if (next.intent.notSent &&
+            next.intent.intentId === id &&
+            finish !== null &&
+            now > finish * 1000) {
+            // Not sent yet, gone, and past the Worker's finish: only the quote sweep
+            // deletes a row, only one nothing touched, 30 min after the quote, and
+            // past the finish the claim's compare-and-swap refuses on the database
+            // clock, so even a 404 from something else (a router, a proxy, a
+            // rollback) leaves nothing that can execute. Retry. Before the finish
+            // (or with it unknown: a resumed intent has no quote) the 404 proves
+            // nothing while the signed request can still be claimed: hold, below.
+            log(fx, "warn", `${LOG} A not-sent intent is gone (swept unexecuted); offering Retry`);
+            next = transition(next, fx, "failed", {
+                error: NOT_SENT_SWEPT_ERROR,
+                reconciling: false,
+                mayHaveMoved: false,
+            });
+            if (next.intent.status === "failed")
+                verdict = "stop";
+        }
+        else {
+            // A definitive 404 for a DISPATCHED intent is not proof of failure (#271,
+            // xochi#398), nor for a not-sent one before its finish: hold, and report
+            // it once per id.
+            const warning = notFoundDriftWarning(id, next.notFoundReported);
+            if (warning) {
+                log(fx, "warn", warning);
+                next = { ...next, notFoundReported: id };
+            }
+        }
+    }
+    else if (result.status) {
+        const s = result.status;
+        const previous = next.intent.status;
+        next = applyStatusUpdate(next, fx, {
+            type: "intent_status",
+            intentId: id,
+            status: s.status,
+            txHash: s.txHash ?? undefined,
+            receivingTxHash: s.receivingTxHash ?? undefined,
+            settlementTxHash: s.settlementTxHash ?? undefined,
+            settlementChainId: (s.settlementChainId ?? undefined),
+            // A confirmed fill whose receipt the server withheld (anonymous read,
+            // xochi#563) is delivered, exactly as a `filled` substatus, under the
+            // rule `withheldSettlementConfirmed` states. An unmapped status is only
+            // its in-flight bucket, so it never qualifies.
+            substatus: withheldSettlementConfirmed({
+                status: s.unmapped === true ? undefined : s.status,
+                legsWithheld: s.legsWithheld,
+                settlementConfirmed: s.settlementConfirmed,
+            })
+                ? "filled"
+                : (s.substatus ?? undefined),
+            error: s.error ?? undefined,
+            refundReason: s.refundReason ?? undefined,
+            timestamp: new Date(now).toISOString(),
+        }, s.unmapped === true);
+        // Each poll's own verdict: an anonymous read sets it, an owner read (no
+        // marker) clears it, so the host knows when to offer SIWE recovery.
+        const legsWithheld = s.legsWithheld === true;
+        if (next.intent.intentId === id && next.intent.legsWithheld !== legsWithheld) {
+            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.
+        verdict = s.terminal
+            ? "stop"
+            : next.intent.status !== previous || (resumedUnsent && next.intent.notSent)
+                ? "progress"
+                : undefined;
+    }
+    // Terminal beats the ceiling: a swap that settles on the ceiling tick is
+    // applied and stops quietly.
+    if (verdict === "stop") {
+        clearTimer(fx, "poll");
+        return { ...next, poll: { ...answered, stopped: true } };
+    }
+    if (verdict === "progress")
+        return { ...next, poll: { ...answered, spent: 0 } };
+    if (poll.spent < poll.max)
+        return { ...next, poll: answered };
+    // Never a silent stop: a stopped poll and a waiting one look identical.
+    clearTimer(fx, "poll");
+    log(fx, "warn", `${LOG} status poll stopped after ~${Math.round((poll.spent * STATUS_POLL_MS) / 1000)}s ` +
+        `with no observable change (${poll.spent} intervals, ${poll.polls} polls); leaving resolution to reconciliation/webhooks`);
+    next = { ...next, poll: { ...answered, stopped: true } };
+    return next.intent.intentId === id && !next.intent.pollExhausted
+        ? patch(next, { pollExhausted: true })
+        : next;
+}
+// ============================================================
+// Reactive rules (run after every step, until stable)
+// ============================================================
+/**
+ * Every context field the quote request is built from, in a fixed order (a
+ * host may rebuild the context with its keys in any order), read through the
+ * request's own normalisation so two forms that send one request are one
+ * trade. `paused` and `stepwise` shape the ceremony, not the trade.
+ */
+function tradeKey(c) {
+    const { recipientAddress, refundAddress, stealthMetaAddress } = normalizeTradeFields(c);
+    return JSON.stringify([
+        c.fromChainId,
+        c.toChainId,
+        c.fromToken,
+        c.toToken,
+        c.settlementPreference,
+        c.trustScore,
+        c.slippageBps,
+        recipientAddress ?? null,
+        refundAddress ?? null,
+        stealthMetaAddress?.spendingPubKey ?? null,
+        stealthMetaAddress?.viewingPubKey ?? null,
+        stealthMetaAddress?.chainId ?? null,
+        c.wallet.address,
+        c.wallet.chainId,
+    ]);
+}
+/**
+ * The held quote still describes the trade on the form: the amount and every
+ * request field it was quoted for. Confirm and the receipt's signing slot both
+ * read it, so neither offers to sign a quote for a trade the user has edited.
+ */
+export function holdsCurrentQuote(m) {
+    return m.intent.quotedFromAmount === m.amount && m.quotedTrade === tradeKey(m.ctx);
+}
+function settle(model, now, fx) {
+    let m = model;
+    // Each rule records the inputs it last ran on, so it fires once per change;
+    // a rule's own output can trigger another, hence the (bounded) loop.
+    for (let pass = 0; pass < 4; pass++) {
+        const before = m;
+        m = watchWallet(m, fx);
+        m = upgradePreview(m, fx, now);
+        m = armExpiry(m, fx, now);
+        m = armPoll(m, fx, now);
+        if (m === before)
+            break;
+    }
+    return m;
+}
+/**
+ * A quote is bound to the account and chain it was produced under. If either
+ * changes while a pre-execution quote is held, reset: the panel re-quotes for
+ * the new wallet. An in-flight settlement is never yanked out from under, and
+ * neither is a "may have moved" ending (it holds until Reset).
+ */
+function watchWallet(m, fx) {
+    const { address, chainId } = m.ctx.wallet;
+    const { quotedAddress, quotedChainId } = m.intent;
+    const key = JSON.stringify([address, chainId, quotedAddress, quotedChainId]);
+    if (key === m.watched.wallet)
+        return m;
+    const next = { ...m, watched: { ...m.watched, wallet: key } };
+    if (!quotedAddress)
+        return next;
+    const accountChanged = !address || address.toLowerCase() !== quotedAddress.toLowerCase();
+    const chainChanged = quotedChainId != null && chainId !== quotedChainId;
+    if (!accountChanged && !chainChanged)
+        return next;
+    if (!WALLET_INTERRUPTIBLE_STATES.includes(next.intent.status) || next.intent.mayHaveMoved) {
+        return next;
+    }
+    clearTimer(fx, "debounce");
+    clearTimer(fx, "refresh");
+    clearTimer(fx, "signPrompt");
+    // Including any half-finished two-step signing, so a wallet switch mid-sign
+    // cannot strand "Sign 2 of 2" or reuse a stale intent signature.
+    return {
+        ...next,
+        intent: INITIAL_INTENT_STATE,
+        refresh: null,
+        awaitingPull: false,
+        isSigningPull: false,
+        pendingIntentSig: null,
+        sign: null,
+    };
+}
+/**
+ * Replace a held preview with a wallet-bound executable quote once a wallet is
+ * present: silently (the price must not flash back to "quoting") and forced (a
+ * preview carries no signing material and must never be served from cache as
+ * the executable quote).
+ */
+function upgradePreview(m, fx, now) {
+    const isPreview = m.intent.quote?.preview === true;
+    const key = JSON.stringify([tradeKey(m.ctx), m.amount, isPreview, m.intent.status]);
+    if (key === m.watched.upgrade)
+        return m;
+    const next = { ...m, watched: { ...m.watched, upgrade: key } };
+    const upgrade = shouldUpgradePreviewQuote({
+        connected: !!next.ctx.wallet.address,
+        hasAmount: !!next.amount,
+        status: next.intent.status,
+        quoteIsPreview: isPreview,
+        isDepositOrigin: !isChainId(next.ctx.fromChainId),
+    });
+    if (!upgrade)
+        return next;
+    return startQuote(next, fx, now, {
+        amount: next.amount,
+        silent: true,
+        forceRefresh: true,
+        allocate: null,
+    });
+}
+/**
+ * The quote countdown, armed while a quote is held. An allocated deposit route
+ * is governed by its attested deposit deadline instead, never by the short
+ * price expiry.
+ */
+function armExpiry(m, fx, now) {
+    const quote = m.intent.quote;
+    const key = m.intent.status === "quoted" && quote?.expiry && !quote.depositAddress ? quote.expiry : null;
+    if (key === m.watched.expiry)
+        return m;
+    const next = { ...m, watched: { ...m.watched, expiry: key } };
+    if (m.watched.expiry !== null)
+        clearTimer(fx, "expiry");
+    if (key === null)
+        return { ...next, quoteExpiresIn: null };
+    setTimer(fx, "expiry", 1000, true);
+    return tickExpiry(next, fx, now);
+}
+/**
+ * The status poll: armed per (intent, phase) while in flight. Re-armed PER
+ * PHASE deliberately: the ceiling is sized from the phase being entered, and
+ * the reconcile escalation counts polls within one phase. While a not-accepted
+ * execute waits for its resend it is armed under its own key and reads no
+ * status (the server holds nothing to report): its ticks only back up the
+ * `execute` timer (`resendBackstop`), and the resend re-arms the real poll.
+ */
+function armPoll(m, fx, now) {
+    const { intentId, status } = m.intent;
+    const waiting = awaitingResend(m);
+    const key = POLL_INFLIGHT_STATES.includes(status) && intentId
+        ? `${intentId}:${status}${waiting ? ":resend" : ""}`
+        : null;
+    if (key === (m.poll?.key ?? null))
+        return m;
+    if (m.poll && !m.poll.stopped)
+        clearTimer(fx, "poll");
+    if (key === null || !intentId)
+        return { ...m, poll: null };
+    const [gen, next] = [m.seq + 1, { ...m, seq: m.seq + 1 }];
+    const poll = {
+        key,
+        intentId,
+        gen,
+        polls: 0,
+        answered: 0,
+        spent: 0,
+        // Read once at arm time: the deadlines are fixed for the life of a phase.
+        // The deposit deadline comes from the INTENT (a resumed swap has no
+        // quote); the Worker's finish of an unclaimed intent from the quote.
+        max: pollCeilingAttempts(status, m.intent.depositDeadline ?? undefined, now, STATUS_POLL_MS, STATUS_POLL_FLAT_CEILING_MS, unexecutedFinishAt(m.intent.quote) ?? undefined),
+        stopped: false,
+    };
+    setTimer(fx, "poll", STATUS_POLL_MS, true);
+    return waiting ? { ...next, poll } : pollTick({ ...next, poll }, fx, false);
+}