@0xmonaco/react 1.0.50 → 1.0.53

package/dist/hooks/useUserOrders/useUserOrders.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useMonacoSDK } from "../useMonaco";
 /**
  * Hook for subscribing to real-time user order events via WebSocket (authenticated)
@@ -9,6 +9,22 @@ import { useMonacoSDK } from "../useMonaco";
  *
  * @param maxOrders - Maximum number of orders to keep in state (default: 50)
  */
+/** 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([]);
@@ -16,57 +32,285 @@ export function useUserOrders(maxOrders = 50) {
     const [error, setError] = useState(null);
     const [subscribed, setSubscribed] = useState(false);
     const clearError = useCallback(() => setError(null), []);
-    const fetchOrders = useCallback(async () => {
+    /**
+     * 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
+     * alike — captures this when it starts and drops its result if it no longer
+     * matches, so a response still in flight when the SDK changed or the
+     * component unmounted cannot write rows belonging to the previous client.
+     */
+    const readGeneration = useRef(0);
+    /** Read the newest page of orders. Shared by the initial load and the resync. */
+    const readOrders = useCallback(async () => {
+        if (!sdk?.trading)
+            return null;
+        // Cursor mode (pageToken "") reads the newest rows first, which is all
+        // this hook needs; legacy page-number mode is deprecated.
+        const response = await sdk.trading.getPaginatedOrders({
+            pageSize: maxOrders,
+            pageToken: "",
+        });
+        // Deduplicate the paginated orders by id, keeping the first occurrence.
+        const seenIds = new Set();
+        const dedupedOrders = [];
+        for (const order of response.orders) {
+            if (!seenIds.has(order.id)) {
+                seenIds.add(order.id);
+                dedupedOrders.push(order);
+            }
+        }
+        return dedupedOrders.slice(0, maxOrders);
+    }, [sdk?.trading, maxOrders]);
+    /**
+     * Read the list and apply it, either owning it outright or reconciling.
+     *
+     * `replace` is only correct BEFORE the subscription opens: the initial load
+     * runs first by design, so nothing newer can exist to lose. Every other
+     * caller runs with the socket live and must `reconcile`, or an event arriving
+     * while the request is in flight is overwritten by an older snapshot.
+     */
+    const load = useCallback(async (mode) => {
         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
+        // client's read is still running — showing an empty list as though it
+        // were the answer — and a stale rejection would leave `error` set after
+        // the new load had already succeeded.
+        const current = () => generation === readGeneration.current;
         setLoading(true);
         try {
-            // Cursor mode (pageToken "") reads the newest rows first, which is all
-            // this hook needs; legacy page-number mode is deprecated.
-            const response = await sdk.trading.getPaginatedOrders({
-                pageSize: maxOrders,
-                pageToken: "",
-            });
-            // Deduplicate the paginated orders by id, keeping the first occurrence.
-            const seenIds = new Set();
-            const dedupedOrders = [];
-            for (const order of response.orders) {
-                if (!seenIds.has(order.id)) {
-                    seenIds.add(order.id);
-                    dedupedOrders.push(order);
-                }
+            const rows = await readOrders();
+            if (rows && current()) {
+                const fresh = withoutSupersededRows(rows, readEpoch);
+                applyOrders((prev) => (mode === "replace" ? fresh : mergeOrders(prev, fresh, maxOrders)));
             }
-            setOrders(dedupedOrders.slice(0, maxOrders));
         }
         catch (err) {
-            setError(err instanceof Error ? err : new Error(String(err)));
+            if (current())
+                setError(err instanceof Error ? err : new Error(String(err)));
         }
         finally {
-            setLoading(false);
+            if (current())
+                setLoading(false);
         }
-    }, [sdk?.trading, maxOrders]);
-    // Manual refresh function
+    }, [sdk?.trading, readOrders, maxOrders, applyOrders, withoutSupersededRows]);
+    const fetchOrders = useCallback(() => load("replace"), [load]);
+    /**
+     * Manual refresh. Reconciles rather than replaces: unlike the initial load
+     * this is public and can be called at any time, including with the
+     * subscription open, so a fill arriving mid-request must not be rolled back
+     * by the older snapshot the request returns.
+     */
     const refresh = useCallback(async () => {
-        await fetchOrders();
-    }, [fetchOrders]);
+        await load("reconcile");
+    }, [load]);
+    /**
+     * Re-read the list from REST after an event this SDK version cannot describe.
+     *
+     * `orderFromEvent` declines an `OrderPlaced` whose `orderType`, `side` or
+     * `tradingMode` is a value this version does not know, rather than
+     * relabelling it. Without this the order would then be missing from the list
+     * indefinitely — it exists on the server, and no later event adds it, because
+     * every subsequent event for it takes the "update an existing order" path and
+     * finds nothing to update.
+     *
+     * Deliberately NOT `fetchOrders`. This runs while the subscription is live,
+     * so unlike the initial load it cannot own the list: it must not raise
+     * `loading` (consumers read that as the initial load and would flash a
+     * 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, 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
+     * swallowed rather than surfaced through `error`, which describes the load.
+     */
+    const scheduleResync = useCallback(() => {
+        if (resyncTimer.current)
+            return;
+        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) {
+                    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, applyOrders, withoutSupersededRows]);
     useEffect(() => {
         if (!sdk?.ws || !sdk?.trading) {
             setSubscribed(false);
+            // The previous effect's cleanup has already bumped `readGeneration`, so
+            // any read still in flight will now decline to write — including its
+            // `setLoading(false)`. With no client left to start a replacement read,
+            // nothing would ever clear the flag, and the hook would report loading
+            // forever. Clear it here instead.
+            setLoading(false);
             return;
         }
-        setOrders([]);
+        applyOrders([]);
         setError(null);
         setLoading(true);
         const limit = Number.isFinite(maxOrders) ? maxOrders : 50;
         // Fetch initial orders via REST API, then subscribe to WebSocket updates
         let unsubscribe;
+        // Cleanup cannot cancel a fetch already in flight. Without this, a slow
+        // initial read could resolve after the SDK changed or the component
+        // unmounted and then install a subscription on the OLD client — after
+        // cleanup had already run with `unsubscribe` still unset, so that handler
+        // 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)
+                return;
             // Subscribe to WebSocket order updates after initial data is loaded
             // This prevents race conditions where WS events could be overwritten by REST response
             try {
                 unsubscribe = sdk.ws.userOrders((event) => {
-                    setOrders((prev) => {
+                    // Built OUTSIDE the state updater: an updater must stay pure, and
+                    // React may invoke it more than once. `null` here means the event
+                    // is an `OrderPlaced` this version cannot describe.
+                    const placed = event.eventType === "OrderPlaced" ? orderFromEvent(event) : null;
+                    if (event.eventType === "OrderPlaced" && !placed)
+                        scheduleResync();
+                    applyOrders((prev) => {
                         const orderId = event.orderId;
                         // Check if this order already exists
                         const existingIndex = prev.findIndex((o) => o.id === orderId);
@@ -80,14 +324,48 @@ export function useUserOrders(maxOrders = 50) {
                             return newOrders;
                         }
                         // New order - add to the beginning if it's an OrderPlaced event
-                        if (event.eventType === "OrderPlaced") {
-                            const newOrder = orderFromEvent(event);
-                            if (newOrder) {
-                                return [newOrder, ...prev].slice(0, limit);
-                            }
+                        if (placed) {
+                            return [placed, ...prev].slice(0, limit);
                         }
                         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);
             }
@@ -102,34 +380,492 @@ export function useUserOrders(maxOrders = 50) {
             setLoading(false);
         });
         return () => {
+            cancelled = true;
             unsubscribe?.();
+            if (resyncTimer.current) {
+                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]);
+    }, [sdk?.ws, sdk?.trading, maxOrders, fetchOrders, scheduleResync, applyOrders]);
     return { orders, loading, subscribed, error, clearError, refresh };
 }
+/**
+ * Runtime membership test for the closed `OrderStatus` union.
+ *
+ * `@0xmonaco/core` never validates the order-event `status` against a value
+ * list — it hands the wire string through, so an unfamiliar value cannot drop
+ * the whole frame (0XM-2627/0XM-2628). The REST `Order` model this hook builds
+ * has a closed `OrderStatus`, so an unrecognized value has to be recognized as
+ * such here rather than cast in, where it would corrupt the model for every
+ * consumer that branches on `order.status`.
+ *
+ * A `Record<OrderStatus, true>` rather than an array: adding a variant to
+ * `OrderStatus` is a compile error here until it is listed, so this cannot
+ * fall behind the union it mirrors.
+ */
+const ORDER_STATUSES = {
+    SUBMITTED: true,
+    PARTIALLY_FILLED: true,
+    FILLED: true,
+    SETTLED_ON_CHAIN: true,
+    SETTLED: true,
+    CANCELLED: true,
+    REJECTED: true,
+    EXPIRED: true,
+};
+/**
+ * The other closed unions this hook converts into the REST `Order`. Same
+ * contract as `ORDER_STATUSES`: every one of these arrives on the same
+ * unvalidated WebSocket payload, so an unrecognized value in any of them would
+ * corrupt the model just as an unknown status would. `Record<T, true>` again,
+ * so adding a variant to any union is a compile error here until it is listed.
+ */
+const ORDER_TYPES = { LIMIT: true, MARKET: true };
+const ORDER_SIDES = { BUY: true, SELL: true };
+const TRADING_MODES = { SPOT: true, MARGIN: true };
+const TIMES_IN_FORCE = { GTC: true, IOC: true, FOK: true, GTD: true };
+/**
+ * Narrow a widened WebSocket value back to its closed union, or `undefined`.
+ *
+ * `Object.hasOwn`, not `in`: `in` walks the prototype chain, so a wire value of
+ * "toString" / "constructor" / "valueOf" would test true and be cast into the
+ * closed union — the corruption these helpers exist to prevent.
+ */
+function asKnown(known, value) {
+    return typeof value === "string" && Object.hasOwn(known, value) ? value : undefined;
+}
+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 ?? "");
+}
+/**
+ * Sort key for the list's newest-first order. An unparseable or absent
+ * `createdAt` sorts oldest rather than jumping to the top.
+ */
+function createdAtMs(order) {
+    const parsed = Date.parse(order.createdAt ?? "");
+    return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+}
+/**
+ * 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: 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
+ *   rather than by which side a row came from.
+ * - REST only: take it. This is the order the resync exists to recover.
+ *
+ * The union is then sorted newest-first by `createdAt` and truncated to
+ * `limit`, so the row dropped at the cap is the genuinely oldest one. A missing
+ * or unparseable `createdAt` sorts last rather than to the top.
+ */
+export function mergeOrders(current, fetched, limit) {
+    const fetchedIds = new Set(fetched.map((order) => order.id));
+    const currentById = new Map(current.map((order) => [order.id, order]));
+    const reconciled = fetched.map((incoming) => {
+        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;
+        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
+    // evicted the tail of the REST page, and a live-only row is not always the
+    // newer one: once the list is at `limit`, a row REST no longer returns is the
+    // OLDEST held, so the recovered order this resync exists to insert was
+    // precisely the row being dropped — at `limit` 1 it never landed at all.
+    // Sorting newest-first keeps a genuinely new socket row ahead of the page and
+    // lets a genuinely old one fall off, which is what the cap means.
+    return [...liveOnly, ...reconciled].sort((a, b) => createdAtMs(b) - createdAtMs(a)).slice(0, limit);
+}
 /**
  * Create an Order object from an OrderPlaced event
  */
-function orderFromEvent(event) {
+export function orderFromEvent(event) {
     if (event.eventType !== "OrderPlaced")
         return null;
     const { data } = event;
     const tradingPairId = data.tradingPairId || data.tradingPair;
     if (!tradingPairId)
         return null;
+    // The closed REST unions this event must supply for the order to be
+    // describable at all. `@0xmonaco/core` passes an unrecognized value straight
+    // through during version skew, and there is no honest default for any of
+    // these: defaulting a future `STOP` to `LIMIT`, or an unknown side to `BUY`,
+    // renders an order as something it is not — the worst outcome in a trading
+    // UI, and worse than not rendering it. So the order is declined here the same
+    // way one with no trading pair is. Declining alone would leave the order
+    // missing indefinitely, so `useUserOrders` schedules a debounced REST re-read
+    // when this happens and picks the order up from there.
+    const orderType = asKnown(ORDER_TYPES, data.orderType);
+    const side = asKnown(ORDER_SIDES, data.side);
+    const tradingMode = asKnown(TRADING_MODES, data.tradingMode);
+    if (!orderType || !side || !tradingMode)
+        return null;
     return {
         id: event.orderId,
         tradingPairId: tradingPairId,
-        orderType: (data.orderType || "LIMIT"),
-        side: (data.side || "BUY"),
+        orderType,
+        side,
         price: data.price,
         quantity: data.quantity || "0",
         filledQuantity: "0",
         averageFillPrice: undefined,
-        status: data.status,
-        tradingMode: (data.tradingMode || "SPOT"),
-        timeInForce: data.timeInForce,
+        // Not an invented value: an `OrderPlaced` event IS a submitted order by
+        // construction, whatever status string it carries.
+        status: asOrderStatus(data.status) ?? "SUBMITTED",
+        tradingMode,
+        // Optional on the model, so an unrecognized value is simply absent —
+        // there is no honest default to invent for it.
+        timeInForce: asKnown(TIMES_IN_FORCE, data.timeInForce),
+        // Read from the ACKNOWLEDGEMENT only, and then left alone:
+        // `updateOrderFromEvent` spreads the existing order and never rewrites this
+        // field, so the value learned here survives every later event. That is
+        // load-bearing rather than incidental — the maker fill does not carry
+        // `postOnly`, and a post-only order rests and therefore fills as a maker,
+        // so re-deriving the field per event would clear it on the one event a
+        // 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,
     };
@@ -137,12 +873,16 @@ function orderFromEvent(event) {
 /**
  * Update an existing Order with data from a WebSocket event
  */
-function updateOrderFromEvent(order, event) {
+export function updateOrderFromEvent(order, event) {
     const data = event.data;
-    // Prefer status from event data when available, fall back to event-type-based mapping
+    // Prefer a RECOGNIZED status from the event data, else fall back to the
+    // event-type mapping. An unrecognized status falls through rather than being
+    // cast in: the event type still says what happened, which is a better answer
+    // for the UI than a string no consumer can branch on.
     let newStatus = order.status;
-    if ("status" in data && data.status) {
-        newStatus = data.status;
+    const reportedStatus = "status" in data ? asOrderStatus(data.status) : undefined;
+    if (reportedStatus) {
+        newStatus = reportedStatus;
     }
     else {
         switch (event.eventType) {
@@ -187,12 +927,78 @@ 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;
 }