@0xmonaco/react 1.0.51 → 1.0.53

package/dist/hooks/useUserOrders/useUserOrders.js

@@ -11,6 +11,20 @@ import { useMonacoSDK } from "../useMonaco";
  */
 /** Debounce for the REST re-read after an undescribable event, in milliseconds. */
 const RESYNC_DEBOUNCE_MS = 1000;
+/** Avoid a reconnect burst issuing one point read per resting order at once. */
+const ORDER_RESOLUTION_CONCURRENCY = 4;
+/** Release a queue slot even when the underlying client request never settles. */
+const ORDER_RESOLUTION_TIMEOUT_MS = 10_000;
+function withTimeout(request, timeoutMs) {
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error("Snapshot order resolution timed out")), timeoutMs);
+    });
+    return Promise.race([request, timeout]).finally(() => {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    });
+}
 export function useUserOrders(maxOrders = 50) {
     const { sdk } = useMonacoSDK();
     const [orders, setOrders] = useState([]);
@@ -18,6 +32,51 @@ export function useUserOrders(maxOrders = 50) {
     const [error, setError] = useState(null);
     const [subscribed, setSubscribed] = useState(false);
     const clearError = useCallback(() => setError(null), []);
+    /**
+     * Drop unresolved rows from a REST list read that spans a snapshot.
+     *
+     * Snapshot absence says a held resting row needs a targeted `getOrder`; it
+     * does not say what state the order reached. A list read that started before
+     * that snapshot cannot resolve the question, so its omitted resting rows are
+     * filtered while terminal rows and snapshot-present rows pass through.
+     */
+    const withoutSupersededRows = useCallback((rows, readEpoch) => {
+        if (snapshotEpoch.current === readEpoch)
+            return rows;
+        const resting = snapshotRestingIds.current;
+        return rows.filter((row) => !isRestingStatus(row.status) || resting.has(row.id));
+    }, []);
+    /** Apply a new list, reducing against the ref rather than through an updater. */
+    const applyOrders = useCallback((next) => {
+        const applied = typeof next === "function" ? next(ordersRef.current) : next;
+        ordersRef.current = applied;
+        setOrders(applied);
+    }, []);
+    /**
+     * The latest applied orders, readable synchronously from a WebSocket callback
+     * — which closes over the `orders` of the render that installed it.
+     *
+     * `applyOrders` reduces against this and `setOrders` only mirrors it for
+     * rendering, so no decision and no side effect depends on when React chooses
+     * to invoke a functional updater. Same arrangement as `useUserBalances`.
+     */
+    const ordersRef = useRef([]);
+    /**
+     * Bumped every time a snapshot is applied, with the resting ids that snapshot
+     * carried.
+     *
+     * A REST read that STARTED before a snapshot landed can still be in flight
+     * when it does, and its rows are older than the snapshot for the resting set.
+     * Applying them unfiltered can undo a targeted resolution: `mergeOrders`
+     * treats a row absent from the current list as REST-only and re-inserts it,
+     * even though the spanning read is older than the snapshot that prompted the
+     * single-order lookup.
+     *
+     * `readGeneration` does not cover this. It tracks the SDK/effect lifetime, and
+     * a reconnect resubscribes without tearing the effect down.
+     */
+    const snapshotEpoch = useRef(0);
+    const snapshotRestingIds = useRef(new Set());
     const resyncTimer = useRef(null);
     /**
      * Bumped by effect cleanup. Every REST read — the initial load and the resync
@@ -59,6 +118,7 @@ export function useUserOrders(maxOrders = 50) {
         if (!sdk?.trading)
             return;
         const generation = readGeneration.current;
+        const readEpoch = snapshotEpoch.current;
         // A read belonging to a previous client must not write ANY of this state:
         // not the rows, not the error, and not the loading flag. Clearing
         // `loading` from a stale request would mark the hook loaded while the new
@@ -70,7 +130,8 @@ export function useUserOrders(maxOrders = 50) {
         try {
             const rows = await readOrders();
             if (rows && current()) {
-                setOrders((prev) => (mode === "replace" ? rows : mergeOrders(prev, rows, maxOrders)));
+                const fresh = withoutSupersededRows(rows, readEpoch);
+                applyOrders((prev) => (mode === "replace" ? fresh : mergeOrders(prev, fresh, maxOrders)));
             }
         }
         catch (err) {
@@ -81,7 +142,7 @@ export function useUserOrders(maxOrders = 50) {
             if (current())
                 setLoading(false);
         }
-    }, [sdk?.trading, readOrders, maxOrders]);
+    }, [sdk?.trading, readOrders, maxOrders, applyOrders, withoutSupersededRows]);
     const fetchOrders = useCallback(() => load("replace"), [load]);
     /**
      * Manual refresh. Reconciles rather than replaces: unlike the initial load
@@ -108,8 +169,8 @@ export function useUserOrders(maxOrders = 50) {
      * spinner), and it must not replace the list wholesale (an event landing
      * while the request is in flight would be overwritten by an older snapshot —
      * the very race the initial load avoids by subscribing only after it
-     * completes). It merges instead, last-writer-wins by `updatedAt`, the same
-     * reconciliation the SDK documents for `onResync`.
+     * completes). It merges instead, ranking on `version` when either side has
+     * one and falling back to `updatedAt` only when neither does.
      *
      * Debounced and coalesced: a deploy that adds an order type produces a burst
      * of declines, and one REST read repairs the whole burst. A failure is
@@ -121,19 +182,22 @@ export function useUserOrders(maxOrders = 50) {
         const generation = readGeneration.current;
         resyncTimer.current = setTimeout(() => {
             resyncTimer.current = null;
+            // Captured where the READ starts, not where it was scheduled: a snapshot
+            // landing during the debounce is already reflected by the time this runs.
+            const readEpoch = snapshotEpoch.current;
             void readOrders()
                 .then((rows) => {
                 // Clearing the timer cannot cancel a read that already started, so
                 // the generation is what invalidates it.
                 if (rows && generation === readGeneration.current) {
-                    setOrders((prev) => mergeOrders(prev, rows, maxOrders));
+                    applyOrders((prev) => mergeOrders(prev, withoutSupersededRows(rows, readEpoch), maxOrders));
                 }
             })
                 .catch(() => {
                 // A repair that fails leaves the list exactly as it was.
             });
         }, RESYNC_DEBOUNCE_MS);
-    }, [readOrders, maxOrders]);
+    }, [readOrders, maxOrders, applyOrders, withoutSupersededRows]);
     useEffect(() => {
         if (!sdk?.ws || !sdk?.trading) {
             setSubscribed(false);
@@ -145,7 +209,7 @@ export function useUserOrders(maxOrders = 50) {
             setLoading(false);
             return;
         }
-        setOrders([]);
+        applyOrders([]);
         setError(null);
         setLoading(true);
         const limit = Number.isFinite(maxOrders) ? maxOrders : 50;
@@ -158,6 +222,80 @@ export function useUserOrders(maxOrders = 50) {
         // would never be removed.
         let cancelled = false;
         const generation = readGeneration.current;
+        // Generation-scoped queue for snapshot omissions. The set covers QUEUED
+        // and ACTIVE work, so another reconnect snapshot reuses the same request
+        // rather than launching a duplicate for that order.
+        const queuedOrActiveOrderReads = new Set();
+        const orderReadQueue = [];
+        let activeOrderReads = 0;
+        const enqueueOrderReads = (orderIds) => {
+            for (const orderId of orderIds) {
+                if (queuedOrActiveOrderReads.has(orderId))
+                    continue;
+                const started = ordersRef.current.find((row) => row.id === orderId);
+                if (!started)
+                    continue;
+                queuedOrActiveOrderReads.add(orderId);
+                orderReadQueue.push({ orderId, started });
+            }
+            drainOrderReads();
+        };
+        const runOrderRead = async (task) => {
+            let retry = false;
+            try {
+                const { order: resolved } = await withTimeout(sdk.trading.getOrder(task.orderId), ORDER_RESOLUTION_TIMEOUT_MS);
+                if (cancelled || generation !== readGeneration.current)
+                    return;
+                const current = ordersRef.current;
+                const held = current.find((row) => row.id === task.orderId);
+                if (held && held.version === undefined && resolved.version === undefined) {
+                    if (held === task.started) {
+                        // Neither side can be ranked, and the two REST surfaces use
+                        // different clocks. With no intervening local change, the point
+                        // read is the answer this omission explicitly requested, so take
+                        // it without consulting `updatedAt`.
+                        const withoutHeld = current.filter((row) => row.id !== task.orderId);
+                        applyOrders(mergeOrders(withoutHeld, [keepingPostOnly(resolved, held)], limit));
+                    }
+                    else {
+                        // An unversioned event or later snapshot changed this row while the
+                        // request was in flight. Preserve that change; if the latest
+                        // snapshot still omits a resting row, retry from the new baseline
+                        // once this in-flight slot is released.
+                        retry = isRestingStatus(held.status) && !snapshotRestingIds.current.has(task.orderId);
+                    }
+                }
+                else {
+                    // Versioned results are safe to merge even when state changed while
+                    // the request was in flight: the shared comparator picks the newer
+                    // state and gives a point-read final state the equal-version tie.
+                    applyOrders(mergeOrders(current, [resolved], limit));
+                }
+            }
+            catch {
+                // Absence or a failed point read is not proof of terminal state. Keep
+                // the local row; a later snapshot can enqueue another attempt.
+            }
+            finally {
+                activeOrderReads -= 1;
+                queuedOrActiveOrderReads.delete(task.orderId);
+                if (!cancelled && generation === readGeneration.current && retry) {
+                    enqueueOrderReads([task.orderId]);
+                }
+                else {
+                    drainOrderReads();
+                }
+            }
+        };
+        function drainOrderReads() {
+            while (!cancelled && generation === readGeneration.current && activeOrderReads < ORDER_RESOLUTION_CONCURRENCY) {
+                const task = orderReadQueue.shift();
+                if (!task)
+                    return;
+                activeOrderReads += 1;
+                void runOrderRead(task);
+            }
+        }
         fetchOrders()
             .then(() => {
             if (cancelled || generation !== readGeneration.current)
@@ -172,7 +310,7 @@ export function useUserOrders(maxOrders = 50) {
                     const placed = event.eventType === "OrderPlaced" ? orderFromEvent(event) : null;
                     if (event.eventType === "OrderPlaced" && !placed)
                         scheduleResync();
-                    setOrders((prev) => {
+                    applyOrders((prev) => {
                         const orderId = event.orderId;
                         // Check if this order already exists
                         const existingIndex = prev.findIndex((o) => o.id === orderId);
@@ -191,6 +329,43 @@ export function useUserOrders(maxOrders = 50) {
                         }
                         return prev;
                     });
+                }, 
+                // The subscribe-time snapshot repairs rows it carries without a
+                // REST round trip. It matters most after a reconnect: the
+                // resubscribe brings a fresh one, while a targeted read resolves
+                // each formerly-resting order it omits.
+                (items) => {
+                    // Read BEFORE the updater: whether a row was declined depends only
+                    // on the rows themselves, and an updater must stay free of side
+                    // effects because React may invoke it more than once. A row this
+                    // version cannot describe would otherwise be missing indefinitely
+                    // — the same repair a declined OrderPlaced gets.
+                    // Both decisions are made against the ref BEFORE anything is
+                    // applied, so neither depends on when React invokes an updater.
+                    const applied = applyOrderSnapshot(ordersRef.current, items, limit);
+                    // Recorded BEFORE the rows are applied, so a REST read that
+                    // resolves after this point can tell that it spans a snapshot and
+                    // filter resting rows whose absence needs targeted resolution.
+                    snapshotRestingIds.current = new Set(snapshotOrderRows(items).rows.map((row) => row.id));
+                    snapshotEpoch.current += 1;
+                    // A row this version cannot describe would otherwise be missing
+                    // indefinitely — the same repair a declined OrderPlaced gets.
+                    if (applied.hasUndescribableRow)
+                        scheduleResync();
+                    // A fill this connection never saw moves the fee aggregates the
+                    // snapshot cannot carry, and REST is the only source for them.
+                    if (applied.hasOfflineFill)
+                        scheduleResync();
+                    applyOrders(applied.orders);
+                    // Absence from the persisted resting snapshot is ambiguous: the
+                    // order may have gone terminal during the outage, or persistence
+                    // may lag a newer row retained from the previous connection.
+                    // Keep the row visible while a cache-first point read resolves
+                    // it. `mergeOrders` ranks the answer against any event or newer
+                    // snapshot that lands while these requests are in flight.
+                    if (applied.missingRestingOrderIds.length > 0) {
+                        enqueueOrderReads(applied.missingRestingOrderIds);
+                    }
                 });
                 setSubscribed(true);
             }
@@ -211,11 +386,13 @@ export function useUserOrders(maxOrders = 50) {
                 clearTimeout(resyncTimer.current);
                 resyncTimer.current = null;
             }
+            orderReadQueue.length = 0;
+            queuedOrActiveOrderReads.clear();
             // Invalidates any read already in flight; see `readGeneration`.
             readGeneration.current += 1;
             setSubscribed(false);
         };
-    }, [sdk?.ws, sdk?.trading, maxOrders, fetchOrders, scheduleResync]);
+    }, [sdk?.ws, sdk?.trading, maxOrders, fetchOrders, scheduleResync, applyOrders]);
     return { orders, loading, subscribed, error, clearError, refresh };
 }
 /**
@@ -266,6 +443,76 @@ function asKnown(known, value) {
 function asOrderStatus(value) {
     return asKnown(ORDER_STATUSES, value);
 }
+/**
+ * `live`, with every REST-only field taken from the fetched row.
+ *
+ * "REST-only" means no WebSocket frame carries it — neither a snapshot row nor
+ * an order event — so the live row's copy is whatever an older read left
+ * behind, and a snapshot-derived row has none at all. Each is assigned even
+ * when the response omits it: REST is the authority on these, so "not set
+ * there" is an answer rather than a gap.
+ *
+ * `postOnly` is deliberately NOT among them. The `OrderPlaced` acknowledgement
+ * carries it and is the authority on it, and REST omitting the key is the
+ * ordinary shape of a non-post-only order — so taking it from the response
+ * would clear a flag learned from the socket.
+ *
+ * Written out rather than looped over a key list so it type-checks without a
+ * cast: indexing `Order` by a union of keys loses the per-field value type.
+ */
+function withRestOnlyFields(live, fetched) {
+    return {
+        ...live,
+        expirationDate: fetched.expirationDate,
+        applicationTakerFee: fetched.applicationTakerFee,
+        monacoTakerFee: fetched.monacoTakerFee,
+        monacoMakerRebate: fetched.monacoMakerRebate,
+        totalTakerFees: fetched.totalTakerFees,
+        takerTotalPayment: fetched.takerTotalPayment,
+        makerTotalReceipt: fetched.makerTotalReceipt,
+        positionSide: fetched.positionSide,
+        terminalReason: fetched.terminalReason,
+    };
+}
+/**
+ * Whether an incoming row (a REST response or a snapshot) supersedes the one
+ * held locally.
+ *
+ * Ranked on `version` — the sequencer step every endpoint reports identically
+ * for the same order state (0XM-2440). `updatedAt` cannot do this job: order
+ * detail carries the matching-engine event clock and order lists the database
+ * commit clock, so a stale response can hold the LATER timestamp, and the
+ * column can move without the order changing at all.
+ *
+ * `>=`, not `>`. Equal means the same sequencer step, not identical state — one
+ * step emits an `OrderPlaced` and then its fills, and a batch shares one step
+ * across every item — and the incoming row is that step's FINAL state, so on a
+ * tie it is the authority over an intermediate event.
+ *
+ * Absent is unknown, never zero. When exactly one side has a version, that is
+ * the only rankable side: incoming-known wins and live-known stays. Falling
+ * back to timestamps in either asymmetric case would reintroduce the two-clock
+ * bug this counter exists to remove. Only when BOTH sides lack a version does
+ * the caller use its pre-0XM-2440 fallback.
+ */
+function supersedes(incoming, live) {
+    if (incoming.version === undefined)
+        return live.version === undefined ? "unranked" : false;
+    if (live.version === undefined)
+        return true;
+    return incoming.version >= live.version;
+}
+/**
+ * `incoming`, keeping a `postOnly` the incoming row cannot report.
+ *
+ * REST omitting the key is the ordinary shape of a non-post-only order, and a
+ * snapshot row carries no such field at all, so neither can distinguish "not
+ * post-only" from "unknown". Only a `true` learned from the `OrderPlaced`
+ * acknowledgement is carried forward, and only over an absence.
+ */
+function keepingPostOnly(incoming, live) {
+    return live.postOnly === true && incoming.postOnly === undefined ? { ...incoming, postOnly: true } : incoming;
+}
 /** Milliseconds since epoch for an order's `updatedAt`, or `NaN` if unparseable. */
 function updatedAtMs(order) {
     return Date.parse(order.updatedAt ?? "");
@@ -279,14 +526,242 @@ function createdAtMs(order) {
     return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
 }
 /**
- * Reconcile a REST read against live state, last-writer-wins by `updatedAt`.
+ * Map one `orders` snapshot row onto the REST `Order` model, or `null` when
+ * this SDK version cannot describe it.
+ *
+ * Same decline contract as {@link orderFromEvent}, for the same reason: the
+ * wire values are handed through unvalidated, and relabelling a future order
+ * type or side renders an order as something it is not. `status` joins the
+ * declining set here, unlike on an `OrderPlaced` — that event IS a submitted
+ * order whatever string it carries, whereas a snapshot row's status is the
+ * order's actual resting state and has no honest substitute.
+ *
+ * The row's optionals arrive as explicit `null` (Rust `Option`s serialized
+ * without `skip_serializing_if`), so they are normalized to absent: the REST
+ * model declares them `?:`, and leaking `null` past it would have consumers
+ * branching on a value the model says cannot occur.
+ */
+export function orderFromSnapshotItem(item) {
+    const orderType = asKnown(ORDER_TYPES, item.orderType);
+    const side = asKnown(ORDER_SIDES, item.side);
+    const tradingMode = asKnown(TRADING_MODES, item.tradingMode);
+    const status = asOrderStatus(item.status);
+    if (!orderType || !side || !tradingMode || !status)
+        return null;
+    return {
+        id: item.orderId,
+        tradingPairId: item.tradingPairId,
+        orderType,
+        side,
+        status,
+        price: item.price ?? undefined,
+        quantity: item.quantity,
+        filledQuantity: item.filledQuantity,
+        averageFillPrice: item.averageFillPrice ?? undefined,
+        tradingMode,
+        // Optional on the model, so an unrecognized value is simply absent — there
+        // is no honest default to invent, and no reason to lose the order over it.
+        timeInForce: asKnown(TIMES_IN_FORCE, item.timeInForce),
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt ?? undefined,
+        marginAccountId: item.marginAccountId ?? undefined,
+        positionId: item.positionId ?? undefined,
+        leverage: item.leverage ?? undefined,
+        reduceOnly: item.reduceOnly,
+        ...(item.clientOrderId === undefined ? {} : { clientOrderId: item.clientOrderId }),
+        // Carried, not dropped: it is what the merge ranks this row by, and a row
+        // whose state came from the snapshot while its version stayed at the held
+        // value would be internally inconsistent — reporting a step it does not
+        // describe. Absent stays absent; absent means unknown, never zero.
+        ...(item.version === undefined ? {} : { version: item.version }),
+    };
+}
+/**
+ * Apply a subscribe-time `orders` snapshot to the current list.
+ *
+ * The snapshot carries RESTING orders only, so — unlike the balances one — it
+ * is not the whole list this hook shows. Replacing wholesale would erase every
+ * filled or cancelled order the user just placed, so it reconciles through
+ * the same version-first ordering as {@link mergeOrders}, with its cap applied
+ * by age.
+ *
+ * It IS complete for the persisted resting set, so absence identifies rows that
+ * need resolution — but it is not itself a terminal-state tombstone. On a fast
+ * reconnect persistence may lag a newer resting event retained from the prior
+ * connection, while an order that really filled or was cancelled during the
+ * outage is absent for the same reason: it no longer rests. The pure merge
+ * therefore keeps omitted resting rows and reports their ids so the caller can
+ * issue the targeted `getOrder` required by the shared order contract. That
+ * point read is cache-first and returns the state/version that can be ranked.
+ * Terminal rows are kept exactly as before: the snapshot never carried them,
+ * so their absence says nothing.
+ *
+ * A snapshot row is ranked against the order already held on `version`. The
+ * snapshot wins when its version is equal or higher, because it is the final
+ * state for that sequencer step; a lower version loses. A versioned local row
+ * also wins over an unversioned snapshot: the latter cannot be ranked and may
+ * be persisted state lagging the previous connection's live stream. When both
+ * sides are unversioned, the pre-counter fallback keeps the snapshot's original
+ * precedence instead of comparing incompatible timestamps; that also permits a
+ * validly-null `updatedAt`.
+ *
+ * A snapshot row is LAYERED over the order it already knows rather than
+ * replacing it. `OrderSnapshotItem` is not a whole `Order`: it carries no
+ * `postOnly`, `expirationDate`, `positionSide`, `terminalReason` or fee
+ * aggregates. Substituting a winning snapshot row would otherwise erase every
+ * one of those — including `postOnly`, where absence is never evidence of
+ * `false`. Spreading the row over the existing order lets the snapshot own
+ * exactly the fields it describes and leaves the rest standing.
+ *
+ * The fee aggregates are the one part that can then go stale rather than
+ * missing: they accumulate with fills, and a fill this connection never saw
+ * moves them. So a snapshot row that reports MORE filled quantity than the row
+ * it supersedes schedules the debounced REST re-read, which is the only source
+ * for them. A snapshot that changes nothing about the fill state schedules
+ * nothing, so a quiet reconnect still costs no request.
+ *
+ * `hasUndescribableRow` reports rows this version declined, `hasOfflineFill`
+ * rows whose fills this connection never saw, and `missingRestingOrderIds`
+ * names snapshot omissions that need point reads. The first two let the caller
+ * schedule the debounced list re-read; the last must not use a list page because
+ * an old order can fall outside it.
+ *
+ * Pure, and called with the current list read from a ref rather than from
+ * inside a state updater — an updater must stay free of side effects, and its
+ * signals exist precisely to drive those reads.
+ */
+export function applyOrderSnapshot(current, items, limit) {
+    const { rows, hasUndescribableRow } = snapshotOrderRows(items);
+    const known = new Map(current.map((row) => [row.id, row]));
+    // Layered, not substituted: the row's own keys win, and every field it does
+    // not carry survives from the order already held.
+    //
+    // Ranked first, though. A reconnect does NOT recreate this hook's effect, so
+    // the list still holds state applied from the previous connection's live
+    // stream — while the snapshot is read from persisted state, which can lag
+    // that stream. An unconditional win would walk such a row backwards, which is
+    // exactly what the shared `version` counter exists to prevent.
+    const carried = rows.flatMap((row) => {
+        const existing = known.get(row.id);
+        if (!existing)
+            return [row];
+        const ranked = supersedes(row, existing);
+        // Unranked means neither side carries a version, which is the pre-0XM-2440
+        // world: the snapshot is still the authority on resting state there, so it
+        // keeps its original precedence.
+        if (ranked === false)
+            return [];
+        return [{ ...existing, ...row }];
+    });
+    // Core validates the frame and every order id before delivery. A row this
+    // hook cannot describe because it carries a future enum value is still known
+    // to be PRESENT, but it does not make the other absences ambiguous. Build the
+    // presence set from raw items so the declined row itself is not misclassified
+    // as missing, then resolve every distinct held resting row the frame omitted.
+    const snapshotIds = new Set(items.map((row) => row.orderId));
+    const missingRestingOrderIds = current.filter((row) => isRestingStatus(row.status) && !snapshotIds.has(row.id)).map((row) => row.id);
+    // Upsert, then apply the same recency cap `mergeOrders` uses, so a snapshot
+    // row and a live-only row compete for the cap on age rather than on origin.
+    const byId = new Map(current.map((row) => [row.id, row]));
+    for (const row of carried)
+        byId.set(row.id, row);
+    const orders = [...byId.values()].sort((a, b) => createdAtMs(b) - createdAtMs(a)).slice(0, limit);
+    return {
+        orders,
+        hasUndescribableRow,
+        hasOfflineFill: carried.some((row) => filledOffline(known.get(row.id), row)),
+        missingRestingOrderIds,
+    };
+}
+/**
+ * Whether a snapshot row reports fills the held order has not seen.
+ *
+ * The fee aggregates the snapshot cannot carry move with fills, so a changed
+ * fill total is the signal that they are now stale and need the REST read. A
+ * row whose fill state is unchanged leaves them accurate, and a new order the
+ * list did not hold has no aggregates to have gone stale.
+ *
+ * Called only for rows that won the version comparison. Compared as normalized
+ * decimal STRINGS, not as numbers. `filledQuantity` only ever grows for an
+ * accepted incoming row, so "differs" and "grew" are the same question, and
+ * answering it without `parseFloat` keeps it exact — a float comparison would
+ * be inexact past ~15 significant digits, and this repo does not do financial
+ * comparisons in floating point. Normalizing is what makes the string compare
+ * sound: the held row can come from REST and the incoming one from the wire,
+ * and the same value may be rendered `1` by one and `1.000` by the other.
+ *
+ * An unparseable quantity on either side is treated as no evidence rather than
+ * as a difference, so a malformed decimal cannot drive a read on every frame.
+ */
+function filledOffline(existing, incoming) {
+    if (!existing)
+        return false;
+    const before = normalizedDecimal(existing.filledQuantity);
+    const after = normalizedDecimal(incoming.filledQuantity);
+    return before !== null && after !== null && before !== after;
+}
+/**
+ * A decimal string in a single canonical form, or `null` if it is not one.
+ *
+ * Strips a leading `+`, redundant leading zeros and trailing fractional zeros,
+ * so two renderings of one value compare equal.
+ */
+function normalizedDecimal(value) {
+    const match = value.trim().match(/^([+-]?)(\d+)(?:\.(\d*))?$/);
+    if (!match)
+        return null;
+    // Read by index with a fallback rather than destructured: under
+    // `noUncheckedIndexedAccess` a capture group is `string | undefined`, even
+    // one the pattern makes mandatory.
+    const sign = match[1] ?? "";
+    const integer = (match[2] ?? "").replace(/^0+(?=\d)/, "");
+    const decimals = (match[3] ?? "").replace(/0+$/, "");
+    const magnitude = decimals ? `${integer}.${decimals}` : integer;
+    // `-0` and `0` are the same quantity.
+    return magnitude === "0" ? "0" : `${sign === "-" ? "-" : ""}${magnitude}`;
+}
+/**
+ * The statuses the subscribe-time snapshot treats as resting.
+ *
+ * Mirrors the server's own `SNAPSHOT_RESTING_ORDER_STATUSES` — an order in one
+ * of these is still working on the book, so the snapshot carries it and its
+ * absence therefore means it stopped resting. Every other status is terminal
+ * or post-trade, never carried, so absence says nothing about it.
+ *
+ * The two sets must not drift: a status the server started treating as resting
+ * but this one does not would put its orders back in the stale-forever case
+ * this drop exists to fix, and one this set claims but the server does not
+ * would delete rows on an absence that means nothing. Exported so
+ * `useUserOrders.test.ts` can pin it against the Rust constant directly.
+ *
+ * A `Record<..., true>` over a subset of `OrderStatus`, read through
+ * `Object.hasOwn`, for the same reasons as {@link asKnown}: no prototype walk,
+ * and the union's own membership is checked by the compiler.
+ */
+export const SNAPSHOT_RESTING_STATUSES = { SUBMITTED: true, PARTIALLY_FILLED: true };
+function isRestingStatus(status) {
+    return Object.hasOwn(SNAPSHOT_RESTING_STATUSES, status);
+}
+/**
+ * Map snapshot rows onto the REST model, reporting whether any was declined.
+ *
+ * Split out of {@link applyOrderSnapshot} because it needs no view of the
+ * current list, which makes the mapping — and the decline rule that governs it
+ * — testable on its own.
+ */
+export function snapshotOrderRows(items) {
+    const mapped = items.map(orderFromSnapshotItem);
+    return { rows: mapped.filter((row) => row !== null), hasUndescribableRow: mapped.some((row) => row === null) };
+}
+/**
+ * Reconcile a REST read against live state, ranking on `version` first.
  *
  * The resync runs with the subscription open, so `fetched` may already be stale
  * by the time it lands. Three cases:
  *
- * - In both: keep whichever `updatedAt` is later, so a fill that arrived over
- *   the socket mid-request is not rolled back by an older REST row. Ties keep
- *   the live row, which cannot be older than the response.
+ * - In both: when either row has `version`, the versioned side wins; when both
+ *   do, the incoming REST row wins on `>=` because it is that step's final
+ *   state. Only when neither has a version does `updatedAt` arbitrate.
  * - Live only: keep it. Either it was placed over the socket after the read
  *   started, or it is an older row the page no longer reaches — the two are
  *   indistinguishable here, which is why the cap is applied by age below
@@ -304,13 +779,30 @@ export function mergeOrders(current, fetched, limit) {
         const live = currentById.get(incoming.id);
         if (!live)
             return incoming;
+        // Version first: it is the only field that orders these two soundly.
+        const ranked = supersedes(incoming, live);
+        if (ranked !== "unranked")
+            return ranked ? keepingPostOnly(incoming, live) : live;
         const liveAt = updatedAtMs(live);
         const incomingAt = updatedAtMs(incoming);
         // An unparseable timestamp on either side is not evidence of staleness, so
         // prefer the live row rather than silently rolling it back.
         if (Number.isNaN(liveAt) || Number.isNaN(incomingAt))
             return live;
-        return liveAt >= incomingAt ? live : incoming;
+        if (liveAt > incomingAt)
+            return live;
+        if (liveAt < incomingAt)
+            return incoming;
+        // A TIE keeps the live row's own state — it cannot be older than the
+        // response, and at second resolution two genuinely different states can
+        // share a timestamp — but takes the REST-ONLY fields from the response.
+        // No WebSocket frame carries those, so the live row's copies are whatever
+        // an older read left behind, and a snapshot-derived row has none at all.
+        // Without this the post-snapshot repair could never land: a snapshot and a
+        // REST read of one order report the SAME `updated_at`, both projecting
+        // `orders.updated_at`, so the read returned the fee aggregates and the tie
+        // then discarded them.
+        return withRestOnlyFields(live, incoming);
     });
     const liveOnly = current.filter((order) => !fetchedIds.has(order.id));
     // Cap by RECENCY, not by side. Prepending every live-only row and slicing
@@ -371,6 +863,9 @@ export function orderFromEvent(event) {
         // post-only order most often produces and disagree with REST. Only a real
         // boolean is taken: anything else is not evidence the order was post-only.
         postOnly: typeof data.postOnly === "boolean" ? data.postOnly : undefined,
+        // The local revision the merge ranks against. Without it every REST
+        // response outranks live state by default and the stream can be undone.
+        version: typeof data.version === "number" ? data.version : undefined,
         createdAt: event.timestamp,
         updatedAt: event.timestamp,
     };
@@ -432,12 +927,78 @@ export function updateOrderFromEvent(order, event) {
     if ("quantity" in data && data.quantity) {
         quantity = data.quantity;
     }
-    return {
+    const updated = {
         ...order,
         status: newStatus,
         quantity,
         filledQuantity: filledQuantity,
         averageFillPrice: avgFillPrice,
         updatedAt: event.timestamp,
+        // Advanced only when the event reports one. Absent means unknown, never
+        // zero, so it must not erase a revision already known — spreading `order`
+        // above is what keeps that value when this event carries none.
+        ...(typeof data.version === "number" ? { version: data.version } : {}),
     };
+    return liveEventSupersedes(order, updated, typeof data.version === "number" ? data.version : undefined) ? updated : order;
+}
+/**
+ * Whether a live event can advance the row currently held.
+ *
+ * Snapshots and REST point reads can land before an older buffered event. A
+ * lower event version — or an absent one against known-version state — cannot
+ * overwrite that authoritative row. Equal versions need finer arbitration:
+ * one sequencer step can emit `OrderPlaced` and then one or more cumulative
+ * fill events, so a later same-step event is accepted only while the order is
+ * still resting and its cumulative fill/status does not move backwards.
+ */
+function liveEventSupersedes(current, incoming, incomingVersion) {
+    if (incomingVersion === undefined)
+        return current.version === undefined;
+    if (current.version === undefined)
+        return true;
+    if (incomingVersion !== current.version)
+        return incomingVersion > current.version;
+    // A REST/snapshot terminal row is the step's final state. No event from the
+    // same step can advance it, but an intermediate event could roll it back.
+    if (!isRestingStatus(current.status))
+        return false;
+    const fillOrder = compareDecimalValues(incoming.filledQuantity, current.filledQuantity);
+    if (fillOrder === null) {
+        // Different unreadable values provide no evidence of forward progress.
+        if (incoming.filledQuantity !== current.filledQuantity)
+            return false;
+    }
+    else if (fillOrder !== 0) {
+        return fillOrder > 0;
+    }
+    // With an unchanged cumulative fill, SUBMITTED is the only resting state
+    // behind PARTIALLY_FILLED. Terminal events remain valid forward progress.
+    return current.status !== "PARTIALLY_FILLED" || incoming.status !== "SUBMITTED";
+}
+/** Exact decimal ordering without floating-point loss. */
+function compareDecimalValues(left, right) {
+    const normalizedLeft = normalizedDecimal(left);
+    const normalizedRight = normalizedDecimal(right);
+    if (normalizedLeft === null || normalizedRight === null)
+        return null;
+    if (normalizedLeft === normalizedRight)
+        return 0;
+    const leftNegative = normalizedLeft.startsWith("-");
+    const rightNegative = normalizedRight.startsWith("-");
+    if (leftNegative !== rightNegative)
+        return leftNegative ? -1 : 1;
+    const [leftInteger = "", leftFraction = ""] = (leftNegative ? normalizedLeft.slice(1) : normalizedLeft).split(".");
+    const [rightInteger = "", rightFraction = ""] = (rightNegative ? normalizedRight.slice(1) : normalizedRight).split(".");
+    let magnitudeOrder;
+    if (leftInteger.length !== rightInteger.length) {
+        magnitudeOrder = leftInteger.length < rightInteger.length ? -1 : 1;
+    }
+    else if (leftInteger !== rightInteger) {
+        magnitudeOrder = leftInteger < rightInteger ? -1 : 1;
+    }
+    else {
+        const scale = Math.max(leftFraction.length, rightFraction.length);
+        magnitudeOrder = leftFraction.padEnd(scale, "0") < rightFraction.padEnd(scale, "0") ? -1 : 1;
+    }
+    return leftNegative ? (magnitudeOrder === -1 ? 1 : -1) : magnitudeOrder;
 }