@bananapus/nana-sdk-core 2.34.1 → 2.36.0

package/dist/cjs/review/writeHold.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteHoldBusyError = exports.WriteHoldNonceError = exports.WriteHeldError = void 0;
+exports.WriteHoldBusyError = exports.WriteHoldStaleReviewError = exports.WriteHoldNonceError = exports.WriteHeldError = void 0;
 exports.createWriteHold = createWriteHold;
 const viem_1 = require("viem");
 const safeService_js_1 = require("../safeService.js");
@@ -8,6 +8,18 @@ const messages_js_1 = require("./messages.js");
 const writeRecovery_js_1 = require("./writeRecovery.js");
 const untrusted_js_1 = require("../untrusted.js");
 const relayr_js_1 = require("./relayr.js");
+const tabState_js_1 = require("./tabState.js");
+/** `sent` is the transaction at `hash`, exactly `record`'s call, from its account, on its chain. */
+function sentIsCall(sent, hash, record) {
+    return (sent.hash?.toLowerCase() === hash.toLowerCase() &&
+        sent.from?.toLowerCase() === record.account &&
+        (sent.chainId === undefined || sent.chainId === record.chainId) &&
+        sent.to?.toLowerCase() === record.call.to &&
+        sent.input?.toLowerCase() === record.call.data &&
+        BigInt(sent.value) === BigInt(record.call.value));
+}
+/** The stop of every controller with a follower or tab listener running, for the test-only reset. */
+const liveHolds = (0, tabState_js_1.tabShared)(tabState_js_1.TAB.holds, () => new Set());
 /**
  * A state read without the chain (peek, a replay, another tab's change, a
  * send's progress): its status and line, never the exit. Only the gate in
@@ -36,6 +48,19 @@ class WriteHoldNonceError extends Error {
     }
 }
 exports.WriteHoldNonceError = WriteHoldNonceError;
+/**
+ * The review went stale: another window's attempt of the same write was
+ * reserved, and maybe settled (`settled`), while it was open. Review again;
+ * the next review sends normally.
+ */
+class WriteHoldStaleReviewError extends Error {
+    constructor(settled) {
+        super(messages_js_1.WRITE_HOLD_STALE_REVIEW_LINE);
+        this.settled = settled;
+        this.name = "WriteHoldStaleReviewError";
+    }
+}
+exports.WriteHoldStaleReviewError = WriteHoldStaleReviewError;
 /** The exact call is already being sent from another flow or tab. */
 class WriteHoldBusyError extends Error {
     constructor() {
@@ -45,6 +70,8 @@ class WriteHoldBusyError extends Error {
 }
 exports.WriteHoldBusyError = WriteHoldBusyError;
 const SETTLE_POLL_MS = 15_000;
+/** How long a reservation retries a lock another writer briefly holds. */
+const RESERVE_RETRY_MS = 2_000;
 /** A Safe's execution events, in its 1.3 and 1.4 layouts alike. */
 const SAFE_EXECUTION_TOPICS = [
     (0, viem_1.toEventSelector)("ExecutionSuccess(bytes32,uint256)"),
@@ -52,6 +79,8 @@ const SAFE_EXECUTION_TOPICS = [
 ];
 /** A hash the network still hasn't seen this long after the wallet returned it was almost certainly never broadcast. */
 const UNSEEN_HASH_MS = 30 * 60_000;
+/** The longest one request to Safe's service may take inside the hold. */
+const SAFE_SERVICE_READ_MS = 8_000;
 /** The 30 minutes have passed since the wallet returned the hash, or since it was first read. A clock that couldn't be saved (NaN) never runs out. */
 function unseenTooLong(record) {
     return (Date.now() - Number(record.submittedAt ?? record.firstSeenAt) >=
@@ -99,8 +128,12 @@ function unchecked(record) {
 }
 /** About an hour of polls; a later state() looks again. */
 const SETTLE_POLL_ATTEMPTS = 240;
-function clear(settled) {
-    return settled ? { status: "clear", settled } : { status: "clear" };
+function clear(settled, reservation) {
+    return {
+        status: "clear",
+        ...(settled ? { settled } : {}),
+        ...(reservation === undefined ? {} : { reservation }),
+    };
 }
 function ranExecuted(record, executionHash = record.executionHash, result) {
     return {
@@ -164,12 +197,47 @@ function classify(record) {
  */
 function createWriteHold(options = {}) {
     const storage = options.storage ?? (0, writeRecovery_js_1.createHeldWriteStorage)();
+    /**
+     * Safe's service, every request and its body bounded together to
+     * {@link SAFE_SERVICE_READ_MS} whatever its fetch does with the signal: a read that times out is
+     * unknown, which never releases or settles, so a hung service can't hold
+     * a send or the call's lock.
+     */
+    const service = {
+        ...options.safeService,
+        fetch: (url, init) => {
+            const request = options.safeService?.fetch ?? globalThis.fetch;
+            let timer;
+            return Promise.race([
+                // The whole read, its body included, under the one deadline.
+                request(url, init).then(async (response) => new Response(await response.arrayBuffer(), {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                })),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("Safe's service did not answer in time.")), SAFE_SERVICE_READ_MS);
+                }),
+            ]).finally(() => clearTimeout(timer));
+        },
+    };
     const interval = options.settle?.intervalMs ?? SETTLE_POLL_MS;
     const attempts = options.settle?.attempts ?? SETTLE_POLL_ATTEMPTS;
     const listeners = new Map();
     const peekers = new Map();
     const timers = new Map();
     let onStorage;
+    /**
+     * The one decorator every state leaves through for its storage notice:
+     * while holds last in this tab alone, a held state carries
+     * {@link WRITE_HOLD_IN_TAB_LINE}; otherwise none.
+     */
+    function noticed(state) {
+        const { notice: _, ...rest } = state;
+        return state.status !== "clear" && !storage.durable()
+            ? { ...rest, notice: messages_js_1.WRITE_HOLD_IN_TAB_LINE }
+            : rest;
+    }
     /** The latest state emitted for each call, replayed to a late subscriber. */
     const latest = new Map();
     function emit(key, state) {
@@ -182,7 +250,9 @@ function createWriteHold(options = {}) {
         if (onStorage || typeof globalThis.addEventListener !== "function")
             return;
         onStorage = (event) => {
-            if (event.key && !event.key.startsWith("nana-sdk:reviewed-write"))
+            if (event.key &&
+                (!event.key.startsWith("nana-sdk:reviewed-write") ||
+                    event.key === "nana-sdk:reviewed-write:probe"))
                 return;
             for (const [key, peek] of peekers) {
                 try {
@@ -194,11 +264,25 @@ function createWriteHold(options = {}) {
             }
         };
         globalThis.addEventListener("storage", onStorage);
+        liveHolds.add(dispose);
     }
-    function open(call) {
+    /** Stop every settle poll and the tab listener. */
+    function dispose() {
+        for (const timer of timers.values())
+            clearTimeout(timer);
+        timers.clear();
+        if (onStorage)
+            globalThis.removeEventListener?.("storage", onStorage);
+        onStorage = undefined;
+        liveHolds.delete(dispose);
+    }
+    function openOne(call, hooks = {}, 
+    /** The key a found write was saved under, when it isn't its call's own. */
+    at) {
         const recovery = (0, writeRecovery_js_1.createBrowserWriteRecovery)(call, {
             storage,
             locks: options.locks,
+            at,
         });
         // The canonical recovery scope: a namespace and an exact call never share it.
         const key = recovery.scopeKey;
@@ -206,11 +290,26 @@ function createWriteHold(options = {}) {
         let lastEffect;
         /** Nothing held: how the call's last write settled, if saved. */
         const cleared = () => clear(recovery.settled());
+        /** Every state leaves with the reservation it belongs to. */
+        const tagged = (state) => {
+            const reservation = state.reservation ??
+                (state.status === "clear"
+                    ? recovery.latestReservation()
+                    : state.record.id);
+            return noticed({
+                ...state,
+                ...(reservation === undefined ? {} : { reservation }),
+            });
+        };
         const peek = () => {
             const record = recovery.read();
-            return record ? ungated(classify(record)) : cleared();
+            return tagged(record ? ungated(classify(record)) : cleared());
+        };
+        const shown = (state) => {
+            const out = tagged(state);
+            emit(key, out);
+            return out;
         };
-        const shown = (state) => (emit(key, state), state);
         async function locked(work, wait) {
             let entered = false;
             try {
@@ -240,6 +339,7 @@ function createWriteHold(options = {}) {
         function follow(client, id, left = attempts) {
             if (timers.has(id) || left <= 0)
                 return;
+            liveHolds.add(dispose);
             timers.set(id, setTimeout(() => {
                 void state(client)
                     .catch(() => null)
@@ -259,7 +359,7 @@ function createWriteHold(options = {}) {
                 };
                 // Kept for any later reader: another tab, a reload, a follow timer.
                 recovery.markSettled(record, settled);
-                return clear(settled);
+                return clear(settled, record.id);
             }
             if (!record.safe &&
                 receipt.status === "reverted" &&
@@ -281,10 +381,37 @@ function createWriteHold(options = {}) {
                 follow(client, record.id);
             return classify(recovery.read());
         }
+        /**
+         * Whether a previous deploy's `hash` may be this call's: a valid hash
+         * read on the call's chain that isn't shown to be another write. A
+         * transaction must be the exact call from the account; a Safe proposal,
+         * exactly this call. One that can't be read is unknown, not refused.
+         */
+        async function adoptable(hash, client) {
+            if (!(0, untrusted_js_1.isBytes32)(hash) ||
+                !client ||
+                (await client.getChainId().catch(() => null)) !== call.chainId)
+                return false;
+            const reviewed = {
+                account: call.account.toLowerCase(),
+                chainId: call.chainId,
+                call: {
+                    to: call.call.to.toLowerCase(),
+                    data: call.call.data.toLowerCase(),
+                    value: String(call.call.value ?? 0),
+                },
+            };
+            if (call.safe) {
+                const proposal = await (0, safeService_js_1.readSafeTransaction)(call.chainId, call.account, hash, service).catch(() => null);
+                return !proposal || (0, writeRecovery_js_1.safeProposalIsHeldCall)(proposal, call);
+            }
+            const sent = await client.getTransaction({ hash }).catch(() => null);
+            return !sent || sentIsCall(sent, hash, reviewed);
+        }
         /** The authenticated nonce of a Safe proposal, from Safe's service. */
         async function proposalNonceOf(record) {
             try {
-                const proposal = await (0, safeService_js_1.readSafeTransaction)(record.chainId, record.account, record.hash, options.safeService);
+                const proposal = await (0, safeService_js_1.readSafeTransaction)(record.chainId, record.account, record.hash, service);
                 return (0, safeService_js_1.safeTransactionMessage)(proposal).nonce;
             }
             catch {
@@ -351,8 +478,22 @@ function createWriteHold(options = {}) {
             // Only positive pending evidence stops the clock; a read that fails
             // keeps the one saved.
             if (look === "pending")
-                return { ...state, record: recovery.mined(state.record, false) };
+                return {
+                    ...state,
+                    record: recovery.seenPending(recovery.mined(state.record, false)),
+                };
             const record = look === "mined" ? recovery.mined(state.record, true) : state.record;
+            // Unknown or not found is not pending: with no read showing it pending
+            // or mined for 30 minutes (since it was last seen pending, or else
+            // submitted), the warned explicit exit, never a release on its own. A
+            // Safe proposal's hash isn't a transaction to read.
+            if ((look === "unknown" || look === null) &&
+                !record.safe &&
+                record.minedAt === undefined &&
+                Date.now() -
+                    Number(record.pendingSeenAt ?? record.submittedAt ?? record.firstSeenAt) >=
+                    UNSEEN_HASH_MS)
+                return unchecked(record);
             if (record.minedAt === undefined)
                 return state;
             if (Date.now() - Number(record.minedAt) >= UNSEEN_HASH_MS)
@@ -361,7 +502,9 @@ function createWriteHold(options = {}) {
         }
         /** What the node shows of `hash`: positive pending or mined metadata, or nothing it can say. */
         async function lookAt(hash, client) {
-            const sent = await client.getTransaction({ hash }).catch(() => null);
+            const sent = await client.getTransaction({ hash }).then((tx) => tx, (error) => error?.name === "TransactionNotFoundError" ? null : undefined);
+            if (sent === undefined)
+                return "unknown";
             if (sent?.hash?.toLowerCase() !== hash)
                 return null;
             return sent.blockNumber === null ? "pending" : "mined";
@@ -382,7 +525,8 @@ function createWriteHold(options = {}) {
             for (const hash of seen) {
                 const own = hash === record.hash;
                 const look = await lookAt(hash, client);
-                if (look !== null)
+                // Unknown changes nothing: only positive metadata moves a clock.
+                if (look === "pending" || look === "mined")
                     record = own
                         ? recovery.mined(record, look === "mined")
                         : recovery.candidateMined(record, hash, look === "mined");
@@ -472,15 +616,15 @@ function createWriteHold(options = {}) {
             }
             const end = (record.safeNonce !== undefined &&
                 (await (0, safeService_js_1.provenSafeProposalEnd)(client, record.account, hash, BigInt(record.safeNonce)))) ||
-                (await (0, safeService_js_1.lookAtSafeProposalEnd)(client, record.chainId, record.account, hash, options.safeService));
+                (await (0, safeService_js_1.lookAtSafeProposalEnd)(client, record.chainId, record.account, hash, service));
             // Another Safe transaction took its nonce, even after a saved execution
             // was reorganized away. It may have run the call too: the exit, never a release.
             if (end.look === "replaced")
                 return safeReplaced(recovery.replacedOnChain(record));
             if (end.look === "expired" && !record.executed) {
-                const expired = await (0, writeRecovery_js_1.verifyReviewedWriteExpiry)(client, record, options.safeService).catch(() => false);
+                const expired = await (0, writeRecovery_js_1.verifyReviewedWriteExpiry)(client, record, service).catch(() => false);
                 if (expired && release(record))
-                    return clear({ result: "expired" });
+                    return clear({ result: "expired" }, record.id);
             }
             if (end.look === "executed") {
                 if (!record.executed ||
@@ -502,7 +646,7 @@ function createWriteHold(options = {}) {
                         hash: end.execution.executionHash,
                     };
                     recovery.markSettled(record, settled);
-                    return clear(settled);
+                    return clear(settled, record.id);
                 }
             }
             if (!record.executed &&
@@ -543,6 +687,9 @@ function createWriteHold(options = {}) {
             let record = recovery.read();
             if (!record)
                 return cleared();
+            // A mirror carries no evidence of its own: its source attempt does.
+            if (record.mirrorOf)
+                return classify(record);
             // No evidence from another chain.
             if ((await client.getChainId().catch(() => null)) !== record.chainId)
                 return classify(record);
@@ -606,9 +753,7 @@ function createWriteHold(options = {}) {
             }
             if (record.hash &&
                 record.sentNonce === undefined &&
-                (record.nonce === undefined ||
-                    record.fromBlock === undefined ||
-                    unseenTooLong(record)) &&
+                unseenTooLong(record) &&
                 (await client.getTransaction({ hash: record.hash }).then(() => false, (error) => error?.name === "TransactionNotFoundError")))
                 return unchecked(record);
             return classify(record);
@@ -620,7 +765,7 @@ function createWriteHold(options = {}) {
         async function state(client, checks = {}) {
             lastEffect = checks.effect;
             const result = await locked(() => inspect(client, checks.effect), false);
-            return shown(result ? result.value : peek());
+            return { ...shown(result ? result.value : peek()), checked: !!result };
         }
         return {
             state,
@@ -644,8 +789,11 @@ function createWriteHold(options = {}) {
                 if (last) {
                     const now = peek();
                     // A clear is compared by its settlement's identity, a hold by its record.
-                    const identity = (state) => JSON.stringify(state.status === "clear" ? (state.settled ?? null) : state.record);
-                    listener(ungated(identity(now) === identity(last) ? last : now));
+                    const identity = (state) => JSON.stringify([
+                        state.reservation ?? null,
+                        state.status === "clear" ? (state.settled ?? null) : state.record,
+                    ]);
+                    listener(noticed(ungated(identity(now) === identity(last) ? last : now)));
                 }
                 return () => {
                     set.delete(listener);
@@ -664,6 +812,10 @@ function createWriteHold(options = {}) {
              */
             async send(client, run) {
                 let attempt;
+                let ended;
+                const until = new Promise((resolve) => (ended = resolve));
+                let released;
+                let reviewed = "";
                 const gate = {
                     async beforeSend(actualCall) {
                         let evidence;
@@ -677,12 +829,31 @@ function createWriteHold(options = {}) {
                                 throw new WriteHoldNonceError(cause);
                             }
                         }
-                        try {
+                        const reserve = () => {
                             attempt = recovery.reserve(actualCall, evidence);
+                        };
+                        try {
+                            if (hooks.across)
+                                ({ released } = await hooks.across((work) => recovery.withLock(work), reserve, () => {
+                                    recovery.rejected();
+                                    attempt = undefined;
+                                }, until, reviewed));
+                            else
+                                reserve();
                         }
                         catch (error) {
-                            const now = await finish(classify(recovery.read()), client);
-                            shown(now);
+                            if (error instanceof WriteHeldError ||
+                                error instanceof WriteHoldBusyError ||
+                                error instanceof WriteHoldStaleReviewError)
+                                throw error;
+                            if (hooks.across) {
+                                // No lock is held here: what the saved record says.
+                                const now = shown(peek());
+                                if (now.status !== "clear")
+                                    throw new WriteHeldError(now);
+                                throw error;
+                            }
+                            const now = shown(await finish(classify(recovery.read()), client));
                             if (now.status !== "clear")
                                 throw new WriteHeldError(now);
                             throw error;
@@ -717,6 +888,25 @@ function createWriteHold(options = {}) {
                         shown(peek());
                     },
                 };
+                if (hooks.across) {
+                    // Checked under this key's lock, which is then let go: the final
+                    // check and reservation take every lock again, in order.
+                    const checked = await locked(async () => shown(await inspect(client)), false);
+                    if (!checked)
+                        throw new WriteHoldBusyError();
+                    if (checked.value.status !== "clear")
+                        throw new WriteHeldError(checked.value);
+                    // Given with `across`: the generations the review is checked against.
+                    reviewed = hooks.generations();
+                    try {
+                        return await run(gate);
+                    }
+                    finally {
+                        // The send ends: every lock it reserved under is let go first.
+                        ended();
+                        await released;
+                    }
+                }
                 const result = await locked(async () => {
                     const now = shown(await inspect(client));
                     if (now.status !== "clear")
@@ -753,11 +943,18 @@ function createWriteHold(options = {}) {
                             state: await finish(classify(recovery.read()), client),
                         };
                     }
-                    return { released: true, state: clear() };
-                }, true);
+                    return {
+                        released: true,
+                        state: clear(undefined, snapshot.record.id),
+                    };
+                    // Never waits behind another send's wallet prompt: on contention,
+                    // what the saved record says, with no exit.
+                }, false);
                 const ended = result?.value ?? { released: false, state: peek() };
-                shown(ended.state);
-                return ended;
+                return {
+                    ...ended,
+                    state: { ...shown(ended.state), checked: !!result },
+                };
             },
             /**
              * A receipt for the held write: an ordinary write's own hash, or a Safe
@@ -768,6 +965,7 @@ function createWriteHold(options = {}) {
                 const result = await locked(async () => {
                     const record = recovery.read();
                     if (!record ||
+                        record.mirrorOf ||
                         (!record.safe &&
                             record.hash !== receipt?.transactionHash?.toLowerCase()))
                         return finish(classify(record), client);
@@ -800,23 +998,108 @@ function createWriteHold(options = {}) {
              * one lock, without releasing it. The hold then follows that hash: no
              * exit while it is pending, and its receipt settles it.
              */
+            /**
+             * Move a write a previous deploy kept (outside these holds) into this
+             * hold. `snapshot` is the state the app read before deciding. Under
+             * the call's lock, it reserves a held record with `evidence` (the
+             * account's next nonce, or the nonce it was sent at, with the block it
+             * was read at; when it was sent; and its `hash`, or for a Safe write
+             * `safe.safeTxHash`) only while nothing is held and no reservation
+             * came since `snapshot`: another tab's hold or settlement wins, and
+             * the current state is returned unchanged. A hash is checked first
+             * with `client`: a transaction that is another call, from another
+             * account or on another chain (or a Safe proposal of another call) is
+             * refused, adopting nothing. One the chain can't show is held, with
+             * the warned exit 30 minutes after it was sent (or adopted). Then the
+             * gate reads it: a mined one settles on its verified receipt. It never
+             * sends or releases; adopting twice holds once.
+             */
+            async adopt(snapshot, evidence = {}, client) {
+                const nonce = evidence.nonce ?? evidence.sentNonce;
+                const hash = (call.safe ? evidence.safe?.safeTxHash : evidence.hash)?.toLowerCase();
+                /** Nothing held, and no reservation since the app's read. */
+                const free = () => snapshot.status === "clear" &&
+                    !recovery.read() &&
+                    recovery.latestReservation() === snapshot.reservation;
+                const reserve = () => recovery.reserve(undefined, nonce !== undefined && evidence.fromBlock !== undefined
+                    ? { nonce, blockNumber: evidence.fromBlock }
+                    : undefined, {
+                    hash,
+                    submittedAt: evidence.submittedAt === undefined
+                        ? undefined
+                        : String(evidence.submittedAt),
+                });
+                if (hooks.across) {
+                    // Under an intent: the same atomic reserve as a send, under every
+                    // legacy key's lock, mirrored at each so older versions see it.
+                    if (!free() ||
+                        (hash !== undefined && !(await adoptable(hash, client))))
+                        return shown(peek());
+                    let adopted = false;
+                    try {
+                        const { released } = await hooks.across((work) => recovery.withLock(work), () => {
+                            if (!free())
+                                throw new Error("Held since the app's read.");
+                            reserve();
+                            adopted = true;
+                        }, recovery.rejected, Promise.resolve(), hooks.generations());
+                        await released;
+                    }
+                    catch {
+                        /* Held elsewhere, busy, or no longer free: nothing adopted. */
+                    }
+                    // A mined hash settles on its verified receipt, through the gate.
+                    return adopted && hash && client ? state(client) : shown(peek());
+                }
+                const result = await locked(async () => {
+                    if (!free())
+                        return peek();
+                    if (hash !== undefined && !(await adoptable(hash, client)))
+                        return peek();
+                    reserve();
+                    return hash && client ? inspect(client) : peek();
+                }, true);
+                return shown(result?.value ?? peek());
+            },
+            /**
+             * Save the Safe nonce of a held Safe proposal adopted before it was
+             * known, so a replacement can be proven later. Under the call's lock,
+             * only while the held proposal is `safeTxHash` with no nonce yet, and
+             * only when the call's proposal at `nonce` hashes to it: the hash is
+             * the proof. Then the gate reads it. Never sends or releases.
+             */
+            async attachSafeNonce(client, { safeTxHash, nonce }) {
+                const result = await locked(async () => {
+                    const record = recovery.read();
+                    if (record?.safe &&
+                        !record.mirrorOf &&
+                        record.safeNonce === undefined &&
+                        record.hash === safeTxHash.toLowerCase())
+                        try {
+                            (0, safeService_js_1.canonicalSafeTxHash)(call.chainId, call.account, (0, writeRecovery_js_1.heldSafeProposal)(call, nonce), safeTxHash);
+                            recovery.proposalNonce(record, BigInt(nonce));
+                        }
+                        catch {
+                            /* Not this proposal at that nonce: nothing saved. */
+                        }
+                    return inspect(client);
+                }, true);
+                return shown(result?.value ?? peek());
+            },
             async attachHash(client, hash) {
                 const result = await locked(async () => {
                     const record = recovery.read();
                     if (record &&
                         !record.safe &&
                         !record.hash &&
+                        !record.mirrorOf &&
                         (0, untrusted_js_1.isBytes32)(hash) &&
                         (await client.getChainId().catch(() => null)) === record.chainId) {
                         const sent = await client
                             .getTransaction({ hash })
                             .catch(() => null);
-                        if (sent?.hash?.toLowerCase() === hash.toLowerCase() &&
-                            sent.from?.toLowerCase() === record.account &&
-                            (sent.chainId === undefined || sent.chainId === record.chainId) &&
-                            sent.to?.toLowerCase() === record.call.to &&
-                            sent.input?.toLowerCase() === record.call.data &&
-                            BigInt(sent.value) === BigInt(record.call.value) &&
+                        if (sent &&
+                            sentIsCall(sent, hash, record) &&
                             // This attempt, not an earlier identical call: never below the
                             // account's next nonce or mined before it was reserved.
                             // With no such evidence, an identical earlier call can't be
@@ -869,6 +1152,338 @@ function createWriteHold(options = {}) {
             },
         };
     }
+    /**
+     * `legacy`: for a write held under an intent namespace, the keys an earlier
+     * version held it under (an old namespace, or `{ call }` for an exact
+     * call); the current exact call is always checked. `{ match: { to,
+     * selector } }` finds them instead: every exact-call write this account
+     * saved on this chain to `to` with that 4-byte selector, for a hold saved
+     * before the intent key existed under calldata the retry can't rebuild (an
+     * old minimum, expiration or deadline). Pass one only for a write whose
+     * calldata is volatile: it holds every such call. It is found when the
+     * handle opens, and again right before a send reserves. While any of them holds
+     * an unresolved write, the intent handle *is* that hold: its state, its
+     * refusal and its own exit, in place. Each is checked alone, under its own
+     * lock only, never two at once. Only when all are clear does the intent's
+     * own record apply, and only then can a send reserve; they are checked
+     * again right before it does.
+     */
+    function open(call, { legacy = [], } = {}) {
+        if (call.namespace === undefined)
+            return openExact(call);
+        const matches = legacy.flatMap((source) => typeof source === "object" && "match" in source ? [source.match] : []);
+        /** Every exact-call write the matches find in storage now. */
+        const matched = () => matches.flatMap((match) => (0, writeRecovery_js_1.findReviewedWrites)({ chainId: call.chainId, account: call.account, ...match }, { storage }));
+        const namespace = call.namespace;
+        const own = openOne(call, {
+            across: reserveAcross,
+            generations: () => generations(),
+        });
+        const ownJournal = (0, writeRecovery_js_1.createBrowserWriteRecovery)(call, { storage });
+        /** Every involved key's latest reservation id, its generation. */
+        const generations = () => JSON.stringify([ownJournal, ...journals].map((journal) => journal.latestReservation()));
+        const { namespace: _, ...exact } = call;
+        const scopeOf = (input) => (0, writeRecovery_js_1.createBrowserWriteRecovery)(input, { storage }).scopeKey;
+        const scopes = new Set([scopeOf(call)]);
+        // Mirror-aware: evidence and exits always act on the source attempt.
+        const delegates = [];
+        const journals = [];
+        /** Hold `inputs` too, each once, in one canonical order by scope for every writer's locks. */
+        function include(inputs) {
+            const added = inputs.filter(({ input, at }) => {
+                const scope = at ?? scopeOf(input);
+                return !scopes.has(scope) && !!scopes.add(scope);
+            });
+            if (!added.length)
+                return;
+            const keyed = [
+                ...delegates.map((delegate, index) => ({
+                    delegate,
+                    journal: journals[index],
+                })),
+                ...added.map(({ input, at }) => ({
+                    delegate: openExact(input, at),
+                    journal: (0, writeRecovery_js_1.createBrowserWriteRecovery)(input, {
+                        storage,
+                        locks: options.locks,
+                        at,
+                    }),
+                })),
+            ].sort((a, b) => Number(a.journal.scopeKey > b.journal.scopeKey) -
+                Number(a.journal.scopeKey < b.journal.scopeKey));
+            delegates.splice(0, delegates.length, ...keyed.map((k) => k.delegate));
+            journals.splice(0, journals.length, ...keyed.map((k) => k.journal));
+        }
+        /**
+         * Look for matching writes again (on every state(), send() and exit());
+         * those found since are held too, each at the exact key it was found
+         * under, with its own Safe flag. Returns the ones that are new.
+         */
+        function rescan() {
+            const found = matched().filter(({ key }) => !scopes.has(key));
+            include(found.map(({ key, record }) => ({
+                input: { ...exact, safe: record.safe, call: record.call },
+                at: key,
+            })));
+            return found.map(({ record }) => record);
+        }
+        include([{ call: call.call }, ...legacy].flatMap((source) => typeof source === "string"
+            ? [{ input: { ...call, namespace: source } }]
+            : "call" in source
+                ? [{ input: { ...exact, call: source.call } }]
+                : []));
+        rescan();
+        /** A legacy key holding anything but this intent's own mirror. */
+        const foreign = (index) => journals[index].read()?.mirrorOf !== namespace &&
+            delegates[index].peek().status !== "clear";
+        /** The legacy hold the intent stands for right now, from storage alone. */
+        const active = () => delegates.find((_, index) => foreign(index));
+        /** The first legacy key holding an unresolved write, through its own gate. */
+        async function delegated(client) {
+            rescan();
+            for (const [index, handle] of delegates.entries()) {
+                if (!foreign(index))
+                    continue;
+                const state = await handle.state(client);
+                if (state.status !== "clear")
+                    return state;
+            }
+            return null;
+        }
+        /**
+         * The final check and reservation, under every legacy key's lock taken
+         * in one sorted order (the intent's own is held by its send), each
+         * without waiting: a key another writer holds refuses as busy. A legacy
+         * hold refuses; otherwise the intent reserves, and mirrors itself at each
+         * legacy key so its readers, older versions included, see it held.
+         */
+        async function reserveAcross(ownLock, reserve, unreserve, until, reviewed) {
+            const locks = [
+                { scope: scopeOf(call), take: ownLock },
+                ...journals.map((journal) => ({
+                    scope: journal.scopeKey,
+                    take: (work) => journal.withLock(work),
+                })),
+            ].sort((a, b) => Number(a.scope > b.scope) - Number(a.scope < b.scope));
+            const deadline = Date.now() + RESERVE_RETRY_MS;
+            for (;;) {
+                let entered = 0;
+                let reserved;
+                const done = new Promise((resolve) => (reserved = resolve));
+                const acquire = async (index) => {
+                    if (index < locks.length)
+                        return locks[index].take(async () => {
+                            entered += 1;
+                            return acquire(index + 1);
+                        });
+                    const refuse = (held) => new WriteHeldError(noticed({
+                        ...ungated(classify(held)),
+                        reservation: held.id,
+                    }));
+                    for (const journal of journals) {
+                        const held = journal.read();
+                        if (held && held.mirrorOf !== namespace)
+                            throw refuse(held);
+                    }
+                    // A matching write saved since the last look holds it too, and
+                    // its own state() and exit() are reached from now on.
+                    const [late] = rescan();
+                    if (late)
+                        throw refuse(late);
+                    // Another attempt since this review opened: review it again.
+                    if (generations() !== reviewed)
+                        throw new WriteHoldStaleReviewError(ownJournal.settled());
+                    reserve();
+                    const record = own.peek().record;
+                    // Every mirror is saved, in the store the hold itself uses (its
+                    // memory fallback included), before the wallet opens; otherwise
+                    // this unsent reservation and its partial mirrors are undone.
+                    const mirrors = [];
+                    try {
+                        for (const journal of journals)
+                            mirrors.push([journal, journal.mirror(record, namespace)]);
+                    }
+                    catch (error) {
+                        for (const [journal, mirror] of mirrors)
+                            try {
+                                journal.clear(mirror);
+                            }
+                            catch {
+                                /* Held for old readers until their explicit exit. */
+                            }
+                        try {
+                            unreserve();
+                        }
+                        catch {
+                            /* Unsent, it stays held with its explicit exit. */
+                        }
+                        throw error;
+                    }
+                    // Reserved: every lock is kept until the send ends.
+                    reserved();
+                    await until;
+                };
+                const holding = acquire(0);
+                const failed = await Promise.race([
+                    done.then(() => null),
+                    holding.then(() => null, (error) => ({ error })),
+                ]);
+                if (!failed)
+                    return { released: holding.catch(() => { }) };
+                // Not reserved: every lock, its own included, is let go before any
+                // retry; the checks run again each time.
+                const { error } = failed;
+                if (entered === locks.length ||
+                    error instanceof WriteHeldError ||
+                    error instanceof WriteHoldStaleReviewError)
+                    throw error;
+                if (Date.now() >= deadline)
+                    throw new WriteHoldBusyError();
+                await new Promise((resolve) => setTimeout(resolve, 25 + Math.random() * 75));
+            }
+        }
+        /** Remove this intent's mirrors of the reservation that ended, by its id only. */
+        async function clearMirrors(ended) {
+            for (const journal of journals) {
+                if (journal.read()?.id !== ended)
+                    continue;
+                await journal
+                    .withLock(async () => {
+                    const current = journal.read();
+                    if (current?.mirrorOf === namespace && current.id === ended)
+                        journal.clear(current);
+                })
+                    .catch(() => {
+                    /* Kept for old readers until their explicit exit. */
+                });
+            }
+        }
+        /** After a call that ended this intent's reservation, its mirrors go. */
+        const after = async (value) => {
+            if (value.status === "clear" && value.reservation)
+                await clearMirrors(value.reservation);
+            return value;
+        };
+        return {
+            ...own,
+            peek: () => active()?.peek() ?? own.peek(),
+            async state(client, checks) {
+                return ((await delegated(client)) ?? after(await own.state(client, checks)));
+            },
+            async send(client, run) {
+                const held = await delegated(client);
+                if (held)
+                    throw new WriteHeldError(held);
+                return own.send(client, run);
+            },
+            async exit(snapshot, acknowledgement, client) {
+                rescan();
+                const owner = snapshot.status === "clear"
+                    ? undefined
+                    : delegates.find((handle, index) => {
+                        const now = handle.peek();
+                        return (foreign(index) &&
+                            now.status !== "clear" &&
+                            now.record.id === snapshot.record.id);
+                    });
+                if (owner)
+                    return owner.exit(snapshot, acknowledgement, client);
+                const held = await delegated(client);
+                if (held)
+                    return { released: false, state: held };
+                const ended = await own.exit(snapshot, acknowledgement, client);
+                await after(ended.state);
+                return ended;
+            },
+            onReceipt: async (...args) => active()?.onReceipt(...args) ?? after(await own.onReceipt(...args)),
+            onUnproven: async (...args) => active()?.onUnproven(...args) ?? after(await own.onUnproven(...args)),
+            onExecuted: async (...args) => active()?.onExecuted(...args) ?? after(await own.onExecuted(...args)),
+            attachHash: async (...args) => active()?.attachHash(...args) ?? after(await own.attachHash(...args)),
+            attachSafeNonce: async (...args) => active()?.attachSafeNonce(...args) ??
+                after(await own.attachSafeNonce(...args)),
+            // A legacy hold already holds it: nothing is adopted.
+            adopt: async (...args) => active()?.peek() ?? after(await own.adopt(...args)),
+        };
+    }
+    /**
+     * An exact-call handle. When its key holds a mirror of an intent's write,
+     * it is that intent's hold: it never sends or releases on its own, and its
+     * exit is the intent's. A mirror left after the intent ended is removed.
+     */
+    function openExact(call, at) {
+        const own = openOne(call, {}, at);
+        const journal = (0, writeRecovery_js_1.createBrowserWriteRecovery)(call, {
+            storage,
+            locks: options.locks,
+            at,
+        });
+        /** The intent this key mirrors, from storage alone. */
+        const mirrored = () => {
+            const record = journal.read();
+            return record?.mirrorOf
+                ? { record, intent: openOne({ ...call, namespace: record.mirrorOf }) }
+                : undefined;
+        };
+        /** Remove a mirror whose intent holds nothing any more. */
+        async function clearStale(found) {
+            await journal
+                .withLock(async () => {
+                const current = journal.read();
+                if (current?.id === found.record.id)
+                    journal.clear(current);
+            })
+                .catch(() => {
+                /* The stale mirror still holds; its intent is clear. */
+            });
+        }
+        /** The intent's state while it holds anything: this key is its mirror. */
+        async function intentState(client) {
+            const found = mirrored();
+            if (!found)
+                return null;
+            const state = await found.intent.state(client);
+            if (state.status !== "clear")
+                return state;
+            await clearStale(found);
+            return null;
+        }
+        /** The intent in charge, from storage alone. */
+        const route = () => {
+            const found = mirrored();
+            return found && found.intent.peek().status !== "clear"
+                ? found.intent
+                : undefined;
+        };
+        return {
+            ...own,
+            peek: () => route()?.peek() ?? own.peek(),
+            async state(client, checks) {
+                return (await intentState(client)) ?? own.state(client, checks);
+            },
+            async send(client, run) {
+                const held = await intentState(client);
+                if (held)
+                    throw new WriteHeldError(held);
+                return own.send(client, run);
+            },
+            async exit(snapshot, acknowledgement, client) {
+                const found = mirrored();
+                if (!found || found.intent.peek().status === "clear")
+                    return own.exit(snapshot, acknowledgement, client);
+                const ended = await found.intent.exit(snapshot, acknowledgement, client);
+                if (ended.released)
+                    await clearStale(found);
+                return ended;
+            },
+            onReceipt: (...args) => (route() ?? own).onReceipt(...args),
+            onUnproven: (...args) => (route() ?? own).onUnproven(...args),
+            onExecuted: (...args) => (route() ?? own).onExecuted(...args),
+            attachHash: (...args) => (route() ?? own).attachHash(...args),
+            attachSafeNonce: (...args) => (route() ?? own).attachSafeNonce(...args),
+            // An intent's mirror already holds it: nothing is adopted.
+            adopt: async (...args) => route()?.peek() ?? own.adopt(...args),
+        };
+    }
     return {
         open,
         /** Whether holds outlive this tab right now. */
@@ -876,14 +1491,7 @@ function createWriteHold(options = {}) {
         /** The review's line while holds last only in this tab, or null. */
         reviewLine: () => (storage.durable() ? null : messages_js_1.WRITE_HOLD_IN_TAB_LINE),
         /** Stop every settle poll and the tab listener (tests, teardown). */
-        dispose() {
-            for (const timer of timers.values())
-                clearTimeout(timer);
-            timers.clear();
-            if (onStorage)
-                globalThis.removeEventListener?.("storage", onStorage);
-            onStorage = undefined;
-        },
+        dispose,
     };
 }
 //# sourceMappingURL=writeHold.js.map