@xochi/client 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@xochi/client` are documented here. Format follows [Keep
 
 ## [Unreleased]
 
+### Fixed
+
+- **Transport**: a valid server-directed `Retry-After` is honored up to the existing 600-second safety ceiling instead of being shortened to `retry.maxDelayMs`; the fallback exponential-backoff cap applies only when no valid integer delta-seconds interval is supplied (zero included). Pending quote deduplication now lasts for the whole request, including long server-directed retry waits.
+
+## [0.1.3] - 2026-10-29
+
+### Fixed
+
+- A live execute whose later status read returns `quoted` now enters the `not-sent` phase instead of remaining at "Still confirming". The first status read waits for the execute reply, so a pre-acceptance `quoted` row cannot produce that verdict. Status replies older than the latest answered attempt are ignored, preventing them from undoing a newer not-sent verdict.
+- Returning to a visible tab restarts an exhausted in-flight status poll with a fresh budget. A live not-sent poll remains bounded by its original ceiling; only a resumed intent without a quote refills its budget on each `quoted` read.
+
+### Added
+
+- Exported `NOT_SENT_SWEPT_ERROR` for hosts that need to identify the machine's expired-without-send Retry result.
+
+### Changed
+
+- **BREAKING: `IntentState.legsWithheld` is `boolean | null`** (was `boolean`): `null` means no status reply has established whether the current view is anonymous or owner-authorized. Migration: test `legsWithheld === true` before offering SIWE recovery; do not interpret `null` as an owner read.
+
+## [0.1.2] - 2026-10-27
+
+### Added
+
+- Typed wire shapes and a zod decoder for Riddler's shielded terms preview (`POST /xochi/shielded/preview`, Riddler#1296): `ShieldedPreviewResponseSchema`, `ShieldedPreviewSchema`, `ShieldedFeeBreakdownSchema`, `ShieldedNetworkIdentitySchema`, `ShieldedCorridorSchema`, the `ShieldedPreviewRequestWire` / `ShieldedPreviewResponseWire` types and `decodeShieldedPreview(body)`, which also refuses a fee breakdown whose totals do not add up. Shapes only, with no transport method: the preview needs a `quote`-scoped Riddler credential, and the Xochi Worker proxy route that would expose it is a follow-up owned by xochi#635. A test holds the schemas' members to the vendored `wire/openapi.json`.
+
+### Fixed
+
+- A wallet signature prompt can be cancelled immediately, and every prompt now times out after 90 seconds. A dismissed WalletConnect request previously left consumers in `signing` forever with no retry action; `CancelSignRequested` returns the unchanged quote to its confirm surface, timeout returns to retry or quote refresh as its expiry allows, and any late signature is ignored.
+
 ## [0.1.1] - 2026-10-26
 
 ### Added

package/README.md

@@ -48,7 +48,7 @@ const quote = await xochi.getQuote(request);
 
   Not covered: an echo of a token no read-token key in the prefix names, and that is not a base64url run or a joinable split of one (its hex, its standard base64, its raw bytes as `\xNN`, a split piece under 8 characters or reading as a word, pieces that all read as names with no other piece in their chain, or pieces split by any other separator or by more than one character, such as `, `, `:` or a nested JSON string's `\\n`); and a piece of under 16 characters with other base64url text on both sides, or left at a cut. A 16-character window is 96 random bits, so what stays readable of a token is a piece shorter than that.
 
-- Once xochi#565 is deployed (above), a stealth intent read without the token (or an owner SIWE session) is the server's status-only view, and so is any read of a shielded intent without an owner SIWE session, token or not (SPEC.md §5.1, above); the status-only view carries `substatus` only when it is `not_executed`. `getIntentStatus` then carries `legsWithheld: true` and `settlementConfirmed` (the machine shows a confirmed fill as delivered, `substatus: "filled"`, without changing `status` or `terminal`, and sets `IntentState.legsWithheld` until an owner read clears it; when the flag counts is `withheldSettlementConfirmed`'s rule); `getIntent` returns a `WithheldIntentRecord` (`legsWithheld: true`, its status decoded like a status poll's, no tokens, amounts, fees or timestamps) rather than an `IntentRecord`. Recovery: the token (stealth only), else wallet SIWE (above).
+- Once xochi#565 is deployed (above), a stealth intent read without the token (or an owner SIWE session) is the server's status-only view, and so is any read of a shielded intent without an owner SIWE session, token or not (SPEC.md §5.1, above); the status-only view carries `substatus` only when it is `not_executed`. `getIntentStatus` then carries `legsWithheld: true` and `settlementConfirmed` (the machine shows a confirmed fill as delivered, `substatus: "filled"`, without changing `status` or `terminal`, and sets `IntentState.legsWithheld` until an owner read clears it; the state is `null` before the first status reply, so hosts must test `legsWithheld === true` before offering recovery; when the flag counts is `withheldSettlementConfirmed`'s rule); `getIntent` returns a `WithheldIntentRecord` (`legsWithheld: true`, its status decoded like a status poll's, no tokens, amounts, fees or timestamps) rather than an `IntentRecord`. Recovery: the token (stealth only), else wallet SIWE (above).
 - 429/503 raise `ApiError` with `retryAfter` (absolute unix seconds, capped at 600 s, `MAX_RETRY_WAIT_SEC`), read from the `Retry-After` header (delta), else `X-RateLimit-Reset` (absolute), else a JSON body's camelCase `retryAfter` (absolute). The not-accepted answer below is the one exception.
 - `ApiError.notAccepted` is `true` only on the Worker's not-accepted answer to `execute`: a 503 whose body is a JSON object with `success` the boolean `false`, `status` `"quoted"`, `accepted` the boolean `false`, `intent_id` equal to the executed intent, and `retry_after` a positive finite number (delta seconds), and that is not in doubt (`ApiError.inDoubt`, below; the two are never both `true`). The Worker sends it only after undoing its own claim, on a solver refusal that provably ran before the intent was claimed or any pull sent, so the intent is `quoted` again and the same request may be sent again. Anything else is `false` and is never resent, classified exactly as without the marker: another status (429, 500, 502, 409, ...), a missing, string or non-boolean marker, any other `success` or `status` (the Worker's lost-race answer `status: "executing", reconciling: true` included), another intent's id, a missing, zero, negative or non-numeric `retry_after`, a body that is not a JSON object or is cut by the 8 KiB read. Its `retryAfter` is the wait the body's `retry_after` names (the Worker's choice, jitter included), counted from when the answer is read and rounded up to the next whole second so it never ends early; a readable numeric `Retry-After` header moves it only later, never earlier; `X-RateLimit-Reset` and a body `retryAfter` are not read for it; capped at 600 s. Pass the flag into the machine as `ErrorReport.notAccepted` and let the machine resend; `execute` itself never retries.
 - `ApiError.inDoubt` is `true` on a failed `execute` whose answer cannot vouch that nothing moved for the executed intent. It is `false` only on the three Worker answers that speak for the intent, not just for this request: the not-accepted 503 above (it undid its own claim, and the intent is `quoted` again); its 502 with `success: false`, `status: "failed"` and `substatus: "not_executed"` for the executed intent (it ended the intent with nothing moved; the marker's sources: `NOT_EXECUTED_SUBSTATUS`); and its 409 with `error_category: "promo_unavailable"` (the promo redemption is keyed by intent and idempotent, and every claim follows one, so a refused redemption means no request has claimed the intent). Every other answer refuses this request only, while another request for the same intent (another tab, a replayed request) may hold its claim, so it is in doubt: every 400, 401, 403, 404 and 422, from the Worker or from anything in front of it (the Worker answers its parse 400 and its 403 `api_key_intent_mismatch` before it reads the intent's status, and its other 400s and 401s, the signed-deadline 400 included, from a row it read before, which another request can claim in between; an edge never reads the intent); the 400 for an intent no longer `quoted` and any other 409 (another request holds or held the intent); every 429 (the Worker's plain 429 also answers an intent another request holds; its resendable rate limit is the not-accepted 503); any other 5xx, JSON or not (the Worker's catch-all 500 can follow its call to the solver); and an unmarked 502 `failed` (a solver failure nothing vouches for). No error text is read, so a reworded Worker message can only leave an answer in doubt. Any body carrying a `read_token` or `reconciling: true` is in doubt, whatever its status. A failed `execute` that is not an `ApiError` (a timeout or abort, a reset connection, a `RedirectRefused`, `Invalid response format`) is in doubt too. `false` says nothing had moved when the Worker answered, not that the order is over: unless the answer is the marked 502, the intent is still `quoted` and its signed request executable until it expires. Word an input error (a bad signature, an expired quote) from `code` and the message, not from this flag, which is for the host's own copy and logs; the machine does not take it, since it polls every thrown execute and only the poll's `failed` with `not_executed` (or, while "not sent yet", a 404) offers Retry ([Fund safety](#fund-safety)).
@@ -83,6 +83,7 @@ Lifecycle rules the machine enforces, beyond the signer checks under [Fund safet
 - Confirm is gated on `canSignQuote` and `holdsCurrentQuote`: a held quote is signable (and a deposit address revealable) only while its quoted amount and trade match the form. The trade key is built from the same normalised fields as the quote request (`normalizeTradeFields`), so an edit that leaves the request unchanged keeps the quote.
 - A new amount, a trade/wallet context change, Reset, a resume, or entering `signing` / `awaiting_deposit` / `executing` drops in-flight quote flights. Refresh is ignored past `quoting`, Allocate outside `ALLOCATABLE_STATES` (idle / pending / quoting / quoted), and a quote reply that finds the trade past `quoting` or ended is dropped; a failed allocation never reopens a trade as `quoted`.
 - The sign ceremony survives `signing -> executing` only for the machine's own execute step (`sign.stage === "execute"`); a status-driven move abandons it, and a signature reply outside `signing` is ignored.
+- Every wallet prompt arms the one-shot `signPrompt` timer for `SIGN_PROMPT_TIMEOUT_MS` (90 s). Schedule it like the other timers. A host should expose `CancelSignRequested` while `view(model).phase === "awaiting-wallet"`; cancellation returns to the unchanged quote, clears the live ceremony and ignores a late signature. A timeout does the same, then normal quote expiry may move the receipt to its refresh surface.
 - `StreamStatus` frames for another intent are ignored. Read stream frames with `mapStatusFrame`: it passes in-flight frames only, so every terminal arrives by the poll with its receipt and reason. A `failed` frame a host dispatches itself follows the poll's rule ([Fund safety](#fund-safety)).
 - An execute reported `notAccepted` (below) waits with no status read and resends from the `execute` timer under a new flow id; a status move off `executing`, Reset, or any end of the ceremony drops the pending resend (`clear:execute`). **Hosts must schedule the `execute` timer** like the others and render the `busy` signing slot. A host that drops the timer is slowed, not stranded: the poll timer stays armed through the wait, and the first poll tick (every `STATUS_POLL_MS`, 4 s) or returning tab (`VisibilityChanged`) at or after the resend time does the timer's work, so the resend goes up to 4 s late. The deadline check still decides: a resend that late can fall inside `EXECUTE_RESEND_MARGIN_SECS`, and then the machine stops resending ("not sent yet", [Fund safety](#fund-safety)) instead.
 
@@ -94,9 +95,9 @@ The machine checks every quote against the request (via `@xochi/signer`), the pu
 - **Quotes with an `escrow` envelope are refused.**
 - **A deposit address is never revealed with under 60 s of its attested window left.**
 - **On resume, run stored deposits through `verifyStoredDeposit`** and render and re-persist `result.stored`, not your input.
-- **The machine never sees a read token, and judges every execute reply itself.** `ExecuteReplied` carries the response without the token (`ExecuteReply`): `const { readToken, ...response } = await xochi.execute(request)`, retain `readToken` outside replayable state keyed by the intent id, and dispatch `{ ok: true, response }` (or a token-free `ErrorReport`); pass the retained token to `getIntentStatus` when performing a `status` effect. A thrown execute (whatever `ApiError.inDoubt` says), a reply it cannot read as an execute response for this intent (intent ids compare exactly), a status it does not model, and any reply with reconciling on (`reconciling` is the server's flag when it sends one, else on whenever success was withheld) leave the intent in flight, shown in doubt ("Still confirming"), and polled until it ends or the poll's ceiling stops it (`IntentState.pollExhausted`): `STATUS_POLL_FLAT_CEILING_ATTEMPTS` (150) intervals of 4 s with no status change, a read the intent cannot move to (`quoted` after an execute) included; in `executing` at least until the Worker's finish of an intent no execute claimed (`unexecutedFinishAt`: the later of the quote's `expiry` and the signed intent's `deadline`, plus `QUOTED_EXPIRY_GRACE_SECS`, 60 s) and one more poll, in `awaiting_deposit` until 10 minutes past the deposit deadline; never past 2 hours. An execute that never reached the Worker (a refused redirect, a timeout before any answer) reads `quoted` until that finish, then `failed` with `not_executed`: Retry.
+- **The machine never sees a read token, and judges every execute reply itself.** `ExecuteReplied` carries the response without the token (`ExecuteReply`): `const { readToken, ...response } = await xochi.execute(request)`, retain `readToken` outside replayable state keyed by the intent id, and dispatch `{ ok: true, response }` (or a token-free `ErrorReport`); pass the retained token to `getIntentStatus` when performing a `status` effect. The first status read waits until that execute reply (success or failure), so a pre-acceptance `quoted` row cannot win a race with the execute response. A thrown execute (whatever `ApiError.inDoubt` says), a reply it cannot read as an execute response for this intent (intent ids compare exactly), a status it does not model, and any reply with reconciling on (`reconciling` is the server's flag when it sends one, else on whenever success was withheld) leave the intent in flight, shown in doubt ("Still confirming"), and polled until it ends or the poll's ceiling stops it (`IntentState.pollExhausted`): `STATUS_POLL_FLAT_CEILING_ATTEMPTS` (150) intervals of 4 s with no status change, in `executing` at least until the Worker's finish of an intent no execute claimed (`unexecutedFinishAt`: the later of the quote's `expiry` and the signed intent's `deadline`, plus `QUOTED_EXPIRY_GRACE_SECS`, 60 s) and one more poll, in `awaiting_deposit` until 10 minutes past the deposit deadline; never past 2 hours. Returning the tab to visible restarts an exhausted in-flight poll with a fresh budget. An execute that never reached the Worker (a refused redirect, a timeout before any answer) reads `quoted` as "not sent yet" until that finish, then `failed` with `not_executed`: Retry.
 - **After an execute, only the Worker's `not_executed` offers Retry.** A `failed` read after an execute or a revealed deposit address (any in-flight status: `executing`, `bridging`, `settling`, `awaiting_deposit`, where a deposit may have been sent unseen), from the poll, a `StreamStatus` frame or a final execute reply (`failed` with `success: false` and `reconciling` off), is the Retry view (phase `failed`) only when it carries `substatus: "not_executed"`: the Worker's mark on a `failed` where nothing moved (every source it has: `NOT_EXECUTED_SUBSTATUS`; xochi#686). Every other `failed`, bare or granular (`fill_failed`, `pull_failed`, `refund_failed`, ...), in doubt or not, ends at once in the terminal "may have moved" view: `IntentState.mayHaveMoved`, phase `may-have-moved`, the poll stopped, no Retry, and no quote, wallet reset, Refresh or cleared amount leaves it until Reset, which starts a new trade. Suggested copy, which promises no refund (a `refund_failed` ends here too): "This order did not complete. Funds may have moved. Check Activity before trading again." Against a Worker that does not send the marker (before xochi#686), every `failed` after an execute ends there. On a reload, read the record with `getIntent` and pass its `substatus` (`IntentRecord.substatus`) as `ResumeRequested.substatus`, never a stored copy: a resumed `failed` is Retry only with the marker, and the machine trusts it as it trusts every reply the host relays. A failure before any execute or revealed address (a wallet or quote failure) is the Retry view as before; the machine's own not-accepted give-up is not (below).
-- **Only an explicit not-accepted refusal is retried, and only the same signed request.** Build the thrown execute's `ErrorReport` with `notAccepted: error instanceof ApiError && error.notAccepted` and `value` the usual `StructuredError` (`code`, `retryAfter`); never set it from anything else. It is the only flag the machine reads from a thrown execute. `value.retryAfter` is the `ApiError`'s absolute `retryAfter`, never the body's delta `retry_after`: one more than a minute before `now` is no target (`stale_retry_after`), and the machine stops resending rather than resend at once. Exactly `true` makes the failure not in doubt (no reconciling): the receipt's signing slot reads `{ kind: "busy", retryAt, resend, of }` (phase `submitting`; suggested copy, which makes no funds claim since the signed request stays executable during the wait: "Solver busy. Resending in Ns (retry r of n)." and "Keep this tab open. If it closes, this tab will not resend the order."), and when the wait ends ([State machine](#state-machine)) the machine dispatches the identical `ExecuteRequest` (same signatures, same nonce). At most `MAX_EXECUTE_RESENDS` (3) resends, each only with a `retryAfter` and only if it lands at least `EXECUTE_RESEND_MARGIN_SECS` (5 s) before the earliest of the quote's `expiry`, the signed intent's `deadline` and the pull authorization's `validBefore` / `deadline` (`decideExecuteResend`, `executeDeadline`). Otherwise (a 4th refusal, which need not be the Worker's budget: its wallet rate limit counts none; no or a stale `retryAfter`; a resend past the deadline) the machine stops resending and shows "not sent yet": `IntentState.notSent`, phase `not-sent`, the refusal as its error, no Retry, since the Worker un-claimed the intent and its signed request stays executable until it expires. The Worker's execute answer `200 { success: false, status: "quoted", reconciling: true }` (it ended its own claim but could not finish the intent) is "not sent yet" the same way. Either is read in doubt instead, polled like any thrown execute, when the intent already reads in doubt (reconciling). The poll runs on (no "Still confirming" escalation) until the Worker ends the intent. Usually its quote sweep does, first: nearly every give-up follows an un-claim, and an intent the Worker claimed and un-claimed is finished `failed` with `not_executed` by the sweep's first run (every 5 minutes) past the quote's creation plus 90 s (its 30 s TTL plus 60 s), so 90 s to about 6.5 min after the quote. Otherwise (no request ever claimed it, as when only the Worker's own rate limit refused it) the first read past the signed deadline plus `QUOTED_EXPIRY_GRACE_SECS` (60 s) finishes it, about 6 min after the quote. `failed` with `not_executed` is Retry, and so is a 404 read past the Worker's finish (`now` later than `unexecutedFinishAt(quote)`, in ms): the sweep deletes an intent nothing ever claimed 30 minutes after its quote, so a tab that read nothing until then (asleep or frozen) finds it gone, and past the finish nothing can claim it, so nothing moved. Before the finish a 404 holds like any other (it may be a router's, a proxy's or a rollback's while the signed request is still claimable), and so does every 404 of an intent with no quote to compute it from (a resumed one: 404s then count against the poll ceiling, which ends in `pollExhausted` with Reset, never Retry). Only "not sent yet" reads a 404 so: anywhere else after an execute a 404 holds, since that execute may have been claimed. A resumed `executing` intent (no quote and no sign flow in this tab) that reads `quoted` is rebuilt as "not sent yet" (an intent already in doubt stays so), but only from a reply at least as new as every reply answered so far: status reads can answer out of order (a timer read and a returning tab's read in flight together), and a late `quoted` after a newer `executing` is no rebuild. With no quote to size the poll ceiling by, each `quoted` read refills it until the Worker ends the intent. Any other read ends "not sent yet" (`executing` or later: another execute reached it, shown in doubt; an unmarked `failed`: may have moved). Clearing the amount does not leave it; Reset does, and offering it is the host's call: the dropped intent's signed request stays executable until it expires, so a host that can replay it (a relay, a retry queue) and lets the user sign a new order may execute both. Such a host should not offer Reset here (xochi-widget does not). Suggested copy: "Not sent yet. The solver was busy. You can try again once this order expires." Those deadlines are the server's, compared with the host's clock (`now` on each message): a clock running fast gives up early ("not sent yet" while the Worker could still take the resend), one running slow resends into a refusal the Worker answers with its budget finish. The Worker keeps the same budget server-side and, past it, finishes the intent `failed` with `not_executed` and answers a 502: thrown like any execute, it reads "Still confirming" until the poll reads that `failed`, then Retry. If the tab closes during the wait, this tab does not resend the order; the signed request stays executable until it expires.
+- **Only an explicit not-accepted refusal is retried, and only the same signed request.** Build the thrown execute's `ErrorReport` with `notAccepted: error instanceof ApiError && error.notAccepted` and `value` the usual `StructuredError` (`code`, `retryAfter`); never set it from anything else. It is the only flag the machine reads from a thrown execute. `value.retryAfter` is the `ApiError`'s absolute `retryAfter`, never the body's delta `retry_after`: one more than a minute before `now` is no target (`stale_retry_after`), and the machine stops resending rather than resend at once. Exactly `true` makes the failure not in doubt (no reconciling): the receipt's signing slot reads `{ kind: "busy", retryAt, resend, of }` (phase `submitting`; suggested copy, which makes no funds claim since the signed request stays executable during the wait: "Solver busy. Resending in Ns (retry r of n)." and "Keep this tab open. If it closes, this tab will not resend the order."), and when the wait ends ([State machine](#state-machine)) the machine dispatches the identical `ExecuteRequest` (same signatures, same nonce). At most `MAX_EXECUTE_RESENDS` (3) resends, each only with a `retryAfter` and only if it lands at least `EXECUTE_RESEND_MARGIN_SECS` (5 s) before the earliest of the quote's `expiry`, the signed intent's `deadline` and the pull authorization's `validBefore` / `deadline` (`decideExecuteResend`, `executeDeadline`). Otherwise (a 4th refusal, which need not be the Worker's budget: its wallet rate limit counts none; no or a stale `retryAfter`; a resend past the deadline) the machine stops resending and shows "not sent yet": `IntentState.notSent`, phase `not-sent`, the refusal as its error, no Retry, since the Worker un-claimed the intent and its signed request stays executable until it expires. The Worker's execute answer `200 { success: false, status: "quoted", reconciling: true }`, or a later status read of `quoted` after any execute reply, is "not sent yet" the same way unless the intent already reads in doubt. The poll runs on (no "Still confirming" escalation) until the Worker ends the intent. Usually its quote sweep does, first: nearly every give-up follows an un-claim, and an intent the Worker claimed and un-claimed is finished `failed` with `not_executed` by the sweep's first run (every 5 minutes) past the quote's creation plus 90 s (its 30 s TTL plus 60 s), so 90 s to about 6.5 min after the quote. Otherwise (no request ever claimed it, as when only the Worker's own rate limit refused it) the first read past the signed deadline plus `QUOTED_EXPIRY_GRACE_SECS` (60 s) finishes it, about 6 min after the quote. `failed` with `not_executed` is Retry, and so is a 404 read past the Worker's finish (`now` later than `unexecutedFinishAt(quote)`, in ms): the sweep deletes an intent nothing ever claimed 30 minutes after its quote, so a tab that read nothing until then (asleep or frozen) finds it gone, and past the finish nothing can claim it, so nothing moved. Before the finish a 404 holds like any other (it may be a router's, a proxy's or a rollback's while the signed request is still claimable), and so does every 404 of an intent with no quote to compute it from (a resumed one: 404s then count against the poll ceiling, which ends in `pollExhausted` with Reset, never Retry). Only "not sent yet" reads a 404 so: anywhere else after an execute a 404 holds, since that execute may have been claimed. A resumed `executing` intent that reads `quoted` follows the same verdict, but only from a reply at least as new as every reply answered so far: status reads can answer out of order, and a late `quoted` after a newer `executing` is no rebuild. With no quote to size the poll ceiling by, each `quoted` read refills it until the Worker ends the intent. Any other read ends "not sent yet" (`executing` or later: another execute reached it, shown in doubt; an unmarked `failed`: may have moved). Clearing the amount does not leave it; Reset does, and offering it is the host's call: the dropped intent's signed request stays executable until it expires, so a host that can replay it (a relay, a retry queue) and lets the user sign a new order may execute both. Such a host should not offer Reset here (xochi-widget does not). Suggested copy: "Not sent yet. The solver was busy. You can try again once this order expires." `NOT_SENT_SWEPT_ERROR` identifies the machine's expired-without-send Retry result. Those deadlines are the server's, compared with the host's clock (`now` on each message): a clock running fast gives up early ("not sent yet" while the Worker could still take the resend), one running slow resends into a refusal the Worker answers with its budget finish. The Worker keeps the same budget server-side and, past it, finishes the intent `failed` with `not_executed` and answers a 502: thrown like any execute, it reads "Still confirming" until the poll reads that `failed`, then Retry. If the tab closes during the wait, this tab does not resend the order; the signed request stays executable until it expires.
 
 ## Fee reference
 

package/dist/cjs/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/cjs/machine/index.js

@@ -23,7 +23,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateSwapParams = exports.applyStatusTransition = exports.phaseFromStatus = exports.settlementDisclosure = exports.costOf = exports.payoutOf = exports.view = exports.SIGN_PROMPT_TIMEOUT_MS = exports.RECONCILE_AFTER_ATTEMPTS = exports.QUOTE_REFRESH_BUFFER_MS = exports.QUOTE_DEBOUNCE_MS = exports.update = exports.init = void 0;
+exports.validateSwapParams = exports.applyStatusTransition = exports.phaseFromStatus = exports.settlementDisclosure = exports.costOf = exports.payoutOf = exports.view = exports.NOT_SENT_SWEPT_ERROR = exports.SIGN_PROMPT_TIMEOUT_MS = exports.RECONCILE_AFTER_ATTEMPTS = exports.QUOTE_REFRESH_BUFFER_MS = exports.QUOTE_DEBOUNCE_MS = exports.update = exports.init = void 0;
 var machine_js_1 = require("./machine.js");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return machine_js_1.init; } });
 Object.defineProperty(exports, "update", { enumerable: true, get: function () { return machine_js_1.update; } });
@@ -31,6 +31,7 @@ Object.defineProperty(exports, "QUOTE_DEBOUNCE_MS", { enumerable: true, get: fun
 Object.defineProperty(exports, "QUOTE_REFRESH_BUFFER_MS", { enumerable: true, get: function () { return machine_js_1.QUOTE_REFRESH_BUFFER_MS; } });
 Object.defineProperty(exports, "RECONCILE_AFTER_ATTEMPTS", { enumerable: true, get: function () { return machine_js_1.RECONCILE_AFTER_ATTEMPTS; } });
 Object.defineProperty(exports, "SIGN_PROMPT_TIMEOUT_MS", { enumerable: true, get: function () { return machine_js_1.SIGN_PROMPT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "NOT_SENT_SWEPT_ERROR", { enumerable: true, get: function () { return machine_js_1.NOT_SENT_SWEPT_ERROR; } });
 var view_js_1 = require("./view.js");
 Object.defineProperty(exports, "view", { enumerable: true, get: function () { return view_js_1.view; } });
 var receipt_js_1 = require("./receipt.js");

package/dist/cjs/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/cjs/machine/machine.js

@@ -21,7 +21,7 @@
  * against `lib: ["ES2020"]` alone (tsconfig.machine.json).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SIGN_PROMPT_TIMEOUT_MS = exports.RECONCILE_AFTER_ATTEMPTS = exports.QUOTE_REFRESH_BUFFER_MS = exports.QUOTE_DEBOUNCE_MS = void 0;
+exports.NOT_SENT_SWEPT_ERROR = exports.SIGN_PROMPT_TIMEOUT_MS = exports.RECONCILE_AFTER_ATTEMPTS = exports.QUOTE_REFRESH_BUFFER_MS = exports.QUOTE_DEBOUNCE_MS = void 0;
 exports.init = init;
 exports.update = update;
 exports.holdsCurrentQuote = holdsCurrentQuote;
@@ -65,7 +65,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.";
+exports.NOT_SENT_SWEPT_ERROR = "This order expired without being sent. Nothing moved.";
 function init(config, ctx, hidden = false) {
     return {
         config,
@@ -162,6 +162,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":
@@ -222,10 +226,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;
         }
@@ -723,8 +732,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",
@@ -832,6 +842,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", exports.SIGN_PROMPT_TIMEOUT_MS, false);
     return { ...next, sign: { id, origin: "sign", stage: "intent", intentSignature: null } };
 }
 function beginPullSign(m, fx, now) {
@@ -932,8 +946,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") {
@@ -1216,7 +1229,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");
@@ -1232,12 +1245,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" });
     }
@@ -1306,15 +1323,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) &&
@@ -1322,14 +1344,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`)
@@ -1360,7 +1382,7 @@ function onStatus(m, fx, gen, attempt, result, now) {
             // 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,
+                error: exports.NOT_SENT_SWEPT_ERROR,
                 reconciling: false,
                 mayHaveMoved: false,
             });
@@ -1411,15 +1433,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;
     }
@@ -1587,7 +1609,11 @@ function armExpiry(m, fx, now) {
 function armPoll(m, fx, now) {
     const { intentId, status } = m.intent;
     const waiting = awaitingResend(m);
-    const key = decisions_js_1.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 && decisions_js_1.POLL_INFLIGHT_STATES.includes(status) && intentId
         ? `${intentId}:${status}${waiting ? ":resend" : ""}`
         : null;
     if (key === (m.poll?.key ?? null))

package/dist/cjs/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/cjs/machine/state.js

@@ -15,7 +15,7 @@ exports.INITIAL_INTENT_STATE = {
     settlementTxHash: null,
     settlementChainId: null,
     substatus: null,
-    legsWithheld: false,
+    legsWithheld: null,
     reconciling: false,
     refundReason: null,
     quotedAddress: null,

package/dist/cjs/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/cjs/shared/index.js

@@ -29,3 +29,4 @@ __exportStar(require("./validators.js"), exports);
 __exportStar(require("./schemas.js"), exports);
 __exportStar(require("./api.js"), exports);
 __exportStar(require("./intentStream.js"), exports);
+__exportStar(require("./shieldedPreview.js"), exports);

package/dist/cjs/shared/schemas.js

@@ -391,9 +391,9 @@ exports.QuoteResponseSchema = zod_1.z
     // Optional: the POST omits it, and the GET omits it too on a pull-less route.
     nonce: zod_1.z.number().int().min(0).optional(),
     error: zod_1.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.
@@ -408,7 +408,7 @@ exports.QuoteResponseSchema = zod_1.z
     error_category: zod_1.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: zod_1.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