dexbot 1.4.6 → 1.4.8

package/dist/modules/order/manager.js

@@ -51,7 +51,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrderManager = void 0;
+exports.COWRebalanceEngine = exports.OrderManager = void 0;
 // ===============================================================================
 // SECTION 1: EXTERNAL DEPENDENCIES
 // ===============================================================================
@@ -68,11 +68,77 @@ const Format = __importStar(require("./format"));
 const constants_1 = require("../constants");
 const math_1 = require("./utils/math");
 const validate_1 = require("./utils/validate");
+const order_1 = require("./utils/order");
 const errors_1 = require("../utils/errors");
 const { toFiniteNumber } = Format;
 // ===============================================================================
 // SECTION 2: COW REBALANCE ENGINE
 // ===============================================================================
+/**
+ * Parse a grid slot id ("slot-123") to its rail index. Slot ids are assigned
+ * in ascending price order at grid generation (grid.ts), so the index is
+ * strictly price-monotonic and can be compared exactly where float prices
+ * would risk rounding ambiguity (adjacent levels can round to the same
+ * price). Returns null when the id is not a grid slot id (e.g. orphan fills
+ * with chain-derived ids) so callers can fall back to price comparison.
+ */
+function parseSlotIndex(id) {
+    if (typeof id !== 'string')
+        return null;
+    const match = /^slot-(\d+)$/.exec(id);
+    if (!match)
+        return null;
+    const idx = parseInt(match[1], 10);
+    return Number.isFinite(idx) ? idx : null;
+}
+/**
+ * Stale-placement veto: whether a placement action crosses the plan's own
+ * boundary and would fill immediately on stale market data.
+ * - BUY create/update targeting a slot ABOVE the boundary is dropped; SELL
+ *   create/update targeting a slot BELOW the boundary is dropped. Strict
+ *   comparison: a placement AT the boundary is kept (the boundary slot is
+ *   the spread, which reconcile never targets).
+ * - The reference is the PLAN'S OWN targetBoundary — and ONLY that: the
+ *   plan's slots derive from the same target grid, so a stale plan's
+ *   placements cross its own boundary while legitimate re-placements never
+ *   do (the boundary is capped, the fills are not). Fill-based veto lines
+ *   are deliberately NOT used — after a burst the fills sit beyond the
+ *   plan's legitimate re-place levels (e.g. SELL fills 5,6,7 with cap=1
+ *   moves the boundary only to slot 6), so ANY fill comparison can veto
+ *   valid placements, including the strategy's own rotations (a partial
+ *   SELL rotated into a slot below the last BUY fill after the boundary
+ *   crawled left). The guard is therefore "inert" for boundary-consistent
+ *   engine output by construction.
+ * - Slot ids are compared within the plan's own grid generation
+ *   (targetBoundary and target slots are both from the current plan), so a
+ *   recenter between the fill capture and the plan cannot skew the
+ *   comparison. Both CREATE and UPDATE actions are guarded: the
+ *   cancel/create optimization can convert the same logical placement into
+ *   an UPDATE op (target slot = newGridId), which the CREATE-only check
+ *   would have missed.
+ * - When no plan boundary is available (hand-built plans), nothing is
+ *   vetoed — fill evidence is not a reliable veto line. Non-placement
+ *   actions and non-grid-slot targets are never vetoed.
+ * @param {Object} action - COW action
+ * @param {number} planBoundary - The plan's target boundary slot index
+ * @returns {string|null} Drop reason for the log, or null to keep the action
+ */
+function stalePlacementDropReason(action, planBoundary) {
+    const isPlacement = action?.type === constants_1.COW_ACTIONS.CREATE || action?.type === constants_1.COW_ACTIONS.UPDATE;
+    if (!isPlacement)
+        return null;
+    const targetSlot = parseSlotIndex(action?.newGridId ?? action?.id);
+    if (targetSlot === null)
+        return null;
+    const kindWord = action.type === constants_1.COW_ACTIONS.UPDATE ? 'update' : 'create';
+    if (action?.order?.type === constants_1.ORDER_TYPES.BUY && targetSlot > planBoundary) {
+        return `BUY ${kindWord} for slot ${action.id}: slot ${targetSlot} > plan boundary ${planBoundary}`;
+    }
+    if (action?.order?.type === constants_1.ORDER_TYPES.SELL && targetSlot < planBoundary) {
+        return `SELL ${kindWord} for slot ${action.id}: slot ${targetSlot} < plan boundary ${planBoundary}`;
+    }
+    return null;
+}
 //
 // COPY-ON-WRITE (COW) PATTERN FOR SAFE REBALANCING
 //
@@ -145,6 +211,28 @@ class COWRebalanceEngine {
             return (0, validate_1.buildAbortedResult)(reconcileResult.reason);
         }
         const optimizedActions = (0, validate_1.optimizeRebalanceActions)(reconcileResult.actions, masterGrid);
+        // Stale-placement guard: drop placements crossing the plan's own
+        // boundary (see stalePlacementDropReason) — defer them to the next
+        // cycle instead of filling immediately.
+        const planBoundary = (targetBoundary !== null && targetBoundary !== undefined && Number.isFinite(Number(targetBoundary)))
+            ? Number(targetBoundary)
+            : null;
+        if (planBoundary !== null) {
+            const before = optimizedActions.length;
+            const guarded = optimizedActions.filter((a) => {
+                const dropReason = stalePlacementDropReason(a, planBoundary);
+                if (dropReason) {
+                    this.logger?.log(`[COW] Dropping stale-slot ${dropReason}`, 'warn');
+                    return false;
+                }
+                return true;
+            });
+            if (guarded.length < before) {
+                this.logger?.log(`[COW] Stale-placement guard removed ${before - guarded.length} placement(s); ${guarded.length} action(s) remain`, 'warn');
+            }
+            optimizedActions.length = 0;
+            optimizedActions.push(...guarded);
+        }
         (0, validate_1.projectTargetToWorkingGrid)(workingGrid, targetGrid, { actions: optimizedActions });
         const precisions = {
             buyPrecision: this.assets?.assetB?.precision,
@@ -175,6 +263,7 @@ class COWRebalanceEngine {
         });
     }
 }
+exports.COWRebalanceEngine = COWRebalanceEngine;
 // ===============================================================================
 // SECTION 3: ORDER MANAGER CLASS
 // ===============================================================================
@@ -267,6 +356,7 @@ class OrderManager {
     _accountTotalsPromise;
     _accountTotalsResolve;
     _isFetchingTotals;
+    accountTotalsStale;
     ordersNeedingPriceCorrection;
     shadowOrderIds;
     processedFillTracker;
@@ -280,6 +370,7 @@ class OrderManager {
     _gridSidesUpdated;
     _pauseFundRecalc;
     _pauseFundRecalcWatchdog;
+    _fillBatchInFlight;
     _pauseRecalcLogging;
     _pauseRecalcLoggingWatchdog;
     _throwOnIllegalState;
@@ -291,6 +382,7 @@ class OrderManager {
     _pendingBroadcasts;
     _committedOrderIds;
     _committedOrderIdsBuiltAt;
+    _orderIdAssignedAt;
     _gapSlots;
     _gridDirtyAt;
     _orphanFillsCreditedAt;
@@ -338,7 +430,9 @@ class OrderManager {
             buy: { armed: true, lastTriggeredAt: 0 },
             sell: { armed: true, lastTriggeredAt: 0 }
         };
-        this.resetFunds();
+        // Sync reset — _fundLock is not created until later in the constructor,
+        // and no concurrent access exists during construction.
+        this.accountant.resetFunds();
         this.btsBalance = { free: 0, total: 0, locked: 0 };
         this.targetSpreadCount = 0;
         this.currentSpreadCount = 0;
@@ -347,6 +441,7 @@ class OrderManager {
         this._accountTotalsPromise = null;
         this._accountTotalsResolve = null;
         this._isFetchingTotals = false;
+        this.accountTotalsStale = false;
         this.ordersNeedingPriceCorrection = [];
         this.shadowOrderIds = new Map();
         this.processedFillTracker = new Map();
@@ -372,6 +467,13 @@ class OrderManager {
         this._gridSidesUpdated = new Set();
         this._pauseFundRecalc = 0;
         this._pauseFundRecalcWatchdog = null;
+        // Depth counter for fill batches currently mid-accounting. While non-zero,
+        // _verifyFundInvariants must not run: the batch's balance refresh already
+        // reflects the just-filled orders on-chain, but the grid still holds them
+        // as committed until the batch's grid mutation lands, so a check in that
+        // window would report a spurious Total != Free + Committed by exactly the
+        // fills' size. The check runs once the batch settles instead.
+        this._fillBatchInFlight = 0;
         this._pauseRecalcLogging = false;
         this._pauseRecalcLoggingWatchdog = null;
         this._throwOnIllegalState = false;
@@ -383,6 +485,7 @@ class OrderManager {
         this._pendingBroadcasts = new Map();
         this._committedOrderIds = new Set();
         this._committedOrderIdsBuiltAt = 0;
+        this._orderIdAssignedAt = new Map();
         this._gapSlots = 0;
         this._gridDirtyAt = null;
         this._orphanFillsCreditedAt = null;
@@ -420,6 +523,54 @@ class OrderManager {
             ? constants_1.REBALANCE_STATES.REBALANCING
             : constants_1.REBALANCE_STATES.NORMAL;
     }
+    /**
+     * Push a working grid onto the rebalance stack (LIFO), set the state to
+     * REBALANCING, and — when a result object is provided — mark it as pushed
+     * so pop sites can release exactly the entry this push created. This is
+     * the only place a grid may be pushed; all releases go through
+     * _popWorkingGridRef (marker-guarded, early-return sites) or
+     * _releaseWorkingGridRef (identity-checked, commit sites).
+     * @param {Object} workingGrid - The working grid to push
+     * @param {Object} [result] - Result object to carry the push marker on
+     */
+    _pushWorkingGridRef(workingGrid, result = null) {
+        this._currentWorkingGridStack.push(workingGrid);
+        this._rebalanceState = constants_1.REBALANCE_STATES.REBALANCING;
+        if (result) {
+            result._workingGridPushed = true;
+        }
+        return result;
+    }
+    /**
+     * Pop the stack entry owned by a result, exactly once (marker-guarded).
+     * Results that were never pushed (aborted plans, no-trigger
+     * processFilledOrders outputs, updateOrdersOnChainPlan cowResults,
+     * reconcileGridOrders null results) leave the stack untouched — an
+     * unmatched pop could steal a nested grid's entry. Clears the marker so
+     * a later throw in the same frame cannot pop a second time.
+     * @param {Object} [result] - Result object carrying the push marker
+     */
+    _popWorkingGridRef(result = null) {
+        if (result && result._workingGridPushed === true) {
+            this._clearWorkingGridRef();
+            result._workingGridPushed = false;
+        }
+    }
+    /**
+     * Release the stack entry for a grid after its commit settles, exactly
+     * once per commit invocation. Identity-checked: plan-path grids
+     * (updateOrdersOnChainPlan, local-only divergence commits) were never
+     * pushed, so popping unconditionally would steal a NESTED grid's stack
+     * entry. Pushed grids are always at the top at commit time (LIFO), so
+     * the check is a no-op for them.
+     * @param {Object} workingGrid - The committed working grid
+     */
+    _releaseWorkingGridRef(workingGrid) {
+        const stack = this._currentWorkingGridStack;
+        if (stack.length > 0 && stack[stack.length - 1] === workingGrid) {
+            this._clearWorkingGridRef();
+        }
+    }
     _setRebalanceState(state) {
         this._rebalanceState = state;
         this.logger?.log(`[COW] Rebalance state: ${state}`, 'debug');
@@ -536,20 +687,29 @@ class OrderManager {
         }
     }
     /**
-     * @returns {void}
+     * Reset funds structure to zeroed values. Acquires _fundLock so the
+     * wholesale funds replacement cannot race with concurrent fund mutations
+     * (deductBtsFees, tryDeductFromChainFree, updateOptimisticFreeBalance).
+     * @returns {Promise<void>}
      */
-    resetFunds() {
-        return this.accountant.resetFunds();
+    async resetFunds() {
+        return await this._fundLock.acquire(async () => {
+            return this.accountant.resetFunds();
+        });
     }
     async _deductFromChainFree(orderType, size, operation) {
         if (!this.accountant)
             return;
-        return await this.accountant.tryDeductFromChainFree(orderType, size, operation);
+        return await this._fundLock.acquire(async () => {
+            return await this.accountant.tryDeductFromChainFree(orderType, size, operation);
+        });
     }
     async _addToChainFree(orderType, size, operation) {
         if (!this.accountant)
             return;
-        return await this.accountant.addToChainFree(orderType, size, operation);
+        return await this._fundLock.acquire(async () => {
+            return await this.accountant.addToChainFree(orderType, size, operation);
+        });
     }
     _getGridTotal(side) {
         return (this.funds?.committed?.grid?.[side] || 0) + (this.funds?.virtual?.[side] || 0);
@@ -573,7 +733,7 @@ class OrderManager {
             const size = toFiniteNumber(order.size);
             if (size <= 0)
                 continue;
-            const isBuy = order.type === constants_1.ORDER_TYPES.BUY || (order.type === constants_1.ORDER_TYPES.SPREAD && order.price < this.config.startPrice);
+            const isBuy = order.type === constants_1.ORDER_TYPES.BUY || (order.type === constants_1.ORDER_TYPES.SPREAD && (0, order_1.resolveSpreadOrderSide)(order.price, this.config.startPrice) === constants_1.ORDER_TYPES.BUY);
             if (isBuy)
                 committedBuy += size;
             else
@@ -622,6 +782,66 @@ class OrderManager {
             this.accountId = accountId;
         await this._fetchAccountBalancesAndSetTotals();
     }
+    /**
+     * Refresh accountTotals from chain when the cached snapshot is stale.
+     *
+     * Optimistic deductions (tryDeductFromChainFree) refuse to operate on
+     * snapshots older than MAX_ACCOUNT_TOTALS_AGE_MS and schedule a recovery
+     * instead, leaving the order placed but unaccounted. By refreshing once
+     * up front, the caller's accounting batch runs against a fresh snapshot
+     * so deductions apply normally and no skip/recovery cycle is triggered.
+     *
+     * @returns {Promise<{ok: boolean, reason?: string}>} {ok: true} when the
+     * snapshot is (now) fresh; {ok: false, reason} when the refresh failed and
+     * the snapshot is still stale — the caller must not proceed with accounting.
+     */
+    async refreshAccountTotalsIfStale(options = {}) {
+        const force = options?.force === true;
+        const lastFetched = this.accountTotals?._lastFetchedAt || 0;
+        if (!force && Date.now() - lastFetched <= constants_1.TIMING.MAX_ACCOUNT_TOTALS_AGE_MS) {
+            return { ok: true };
+        }
+        const fetchedBefore = lastFetched;
+        // Apply the standard blockchain-op policy (30s timeout, 3 attempts, then
+        // node failover) so a transiently bad node does not force the caller to
+        // defer the whole fill batch to the next cycle. Only a genuinely
+        // unreachable chain leaves the snapshot stale.
+        try {
+            await (0, system_1.withBlockchainRetry)(() => this.fetchAccountTotals(this.accountId), 'refreshAccountTotalsIfStale', { logger: this.logger });
+        }
+        catch (err) {
+            this.logger?.log?.(`[SYNC] refreshAccountTotalsIfStale fetch failed: ${(0, errors_1.getErrorMessage)(err)}`, 'warn');
+        }
+        const fetchedAfter = this.accountTotals?._lastFetchedAt || 0;
+        if (fetchedAfter <= fetchedBefore) {
+            this.logger?.log?.(`[SYNC] refreshAccountTotalsIfStale: accountTotals still stale after refresh (age=${Math.max(0, Date.now() - fetchedAfter)}ms).`, 'warn');
+            return { ok: false, reason: 'refresh-failed' };
+        }
+        return { ok: true };
+    }
+    /**
+     * Re-anchor accountTotals to authoritative on-chain values after a fill
+     * batch has applied its optimistic accounting and grid mutation.
+     *
+     * A fill batch's up-front stale-totals refresh returns POST-fill balances
+     * (the fills already settled on-chain), then processFillAccounting applies
+     * the same pays/receives again — a double-count on the totals. Force-fetching
+     * here overwrites the optimistic values with the authoritative post-fill
+     * state so the batch ends exactly consistent with chain and the invariant
+     * holds at the final consolidated recalculation.
+     *
+     * @param {string} [label] - Context label for log messages
+     * @returns {Promise<boolean>} true when the re-anchor refreshed successfully
+     */
+    async reanchorAccountTotals(label = 'fill-batch') {
+        const result = await this.refreshAccountTotalsIfStale({ force: true });
+        if (!result.ok) {
+            this.logger?.log?.(`[ACCOUNTING] ${label}: accountTotals re-anchor failed (${result.reason}); marking totals stale.`, 'warn');
+            this.accountTotalsStale = true;
+            return false;
+        }
+        return true;
+    }
     async _fetchAccountBalancesAndSetTotals() {
         return await this.sync.fetchAccountBalancesAndSetTotals();
     }
@@ -637,7 +857,7 @@ class OrderManager {
     async _setAccountTotals(totals) {
         this.accountTotals = { ...(this.accountTotals || {}), ...totals, _lastFetchedAt: Date.now() };
         if (!this.funds)
-            this.resetFunds();
+            await this.resetFunds();
         await this._recalculateFunds();
         if ((0, math_1.hasValidAccountTotals)(this.accountTotals, true) && typeof this._accountTotalsResolve === 'function') {
             try {
@@ -733,7 +953,7 @@ class OrderManager {
                     this.logger?.log?.(`[MANAGER] pauseFundRecalc safety watchdog: resetting depth from ${this._pauseFundRecalc} to 0`, 'warn');
                     this._pauseFundRecalc = 0;
                     this._pauseFundRecalcWatchdog = null;
-                    this._recalculateFunds().catch((err) => {
+                    this.recalculateFunds().catch((err) => {
                         this.logger?.log?.(`[MANAGER] Watchdog recalc failed: ${(0, errors_1.getErrorMessage)(err)}`, 'error');
                     });
                 }
@@ -944,6 +1164,24 @@ class OrderManager {
         }
         const updatedOrder = (0, system_1.deepFreeze)({ ...nextOrder });
         const id = order.id;
+        // Track when an orderId is first assigned to a slot. A freshly assigned
+        // orderId (create/adopt broadcast still in flight, or not yet visible to
+        // a lagging/truncated chain read) must not be treated as "absent from
+        // chain" by phantom cleanup — that would virtualize a real live order
+        // and re-create a duplicate. Absence decisions defer while the stamp is
+        // younger than SYNC_LOCK_TIMEOUT_MS.
+        if (updatedOrder.orderId && (!oldOrder?.orderId || oldOrder.orderId !== updatedOrder.orderId)) {
+            // Prune stamps older than the guard window — they can never be
+            // consulted again (the consumer defers only while the stamp is
+            // younger than SYNC_LOCK_TIMEOUT_MS), so keeping them would leak one
+            // entry per orderId on a perpetual-turnover bot.
+            for (const [orderId, assignedAt] of this._orderIdAssignedAt) {
+                if (Date.now() - assignedAt >= constants_1.TIMING.SYNC_LOCK_TIMEOUT_MS) {
+                    this._orderIdAssignedAt.delete(orderId);
+                }
+            }
+            this._orderIdAssignedAt.set(updatedOrder.orderId, Date.now());
+        }
         const newMap = (0, system_1.cloneMap)(this.orders);
         newMap.set(id, updatedOrder);
         this.orders = Object.freeze(newMap);
@@ -1088,6 +1326,11 @@ class OrderManager {
         const shouldRebalance = triggerFills.length > 0;
         if (shouldRebalance) {
             const rebalanceResult = await this.performSafeRebalance(orders, excl);
+            // Carry the fill set + exclusions on the result so the COW batch
+            // executor can re-plan once from fresh master if the plan goes
+            // stale between planning and broadcast.
+            rebalanceResult.fills = orders;
+            rebalanceResult.excludeIds = excl || new Set();
             return rebalanceResult;
         }
         const workingGrid = new working_grid_1.WorkingGrid(this.orders, { baseVersion: this._gridVersion });
@@ -1349,10 +1592,13 @@ class OrderManager {
             excludeIds
         });
         if (result.aborted) {
-            this._clearWorkingGridRef();
+            // Nothing was pushed for an aborted result — the push below is
+            // skipped — so there is no working-grid ref to clear here. Popping
+            // would steal an unrelated stack entry (double-pop) when combined
+            // with the caller-side no-action handling in _executeBatchIfNeeded.
             return result;
         }
-        this._currentWorkingGridStack.push(result.workingGrid);
+        this._pushWorkingGridRef(result.workingGrid, result);
         return result;
     }
     _reconcileGridCOW(targetGrid, targetBoundary, workingGrid) {
@@ -1410,100 +1656,128 @@ class OrderManager {
         return (0, validate_1.buildAbortedResult)(reason);
     }
     async _commitWorkingGrid(workingGrid, _workingIndexes, workingBoundary, options = {}) {
-        const { skipRecalc } = this._normalizeCommitOptions(options);
         const startTime = Date.now();
-        const stats = workingGrid.getMemoryStats();
         let committed = false;
         let comparePrecisions;
+        let skipRecalc = false;
+        // Exactly-once stack-release contract: every settle path (return or
+        // throw) releases the working-grid stack entry exactly one time via
+        // _releaseWorkingGridRef (identity-checked, so plan-path grids that
+        // were never pushed leave the stack untouched). When the caller passes
+        // its result object (options.result), the push marker is cleared too —
+        // the batch executor's catch block then cannot pop a second time for
+        // the same grid.
+        let popped = false;
+        const releaseStackEntry = () => {
+            if (popped)
+                return;
+            popped = true;
+            this._releaseWorkingGridRef(workingGrid);
+            if (options?.result) {
+                options.result._workingGridPushed = false;
+            }
+        };
         try {
-            comparePrecisions = this._getCowComparePrecisions();
-        }
-        catch (precisionErr) {
-            this.logger.log(`[COW] ${(0, errors_1.getErrorMessage)(precisionErr)}`, 'error');
-            this._clearWorkingGridRef();
-            return false;
-        }
-        const preCommitGuard = (0, validate_1.evaluateCommit)(workingGrid, {
-            hasLock: false,
-            currentVersion: this._gridVersion,
-            masterGrid: this.orders,
-            comparePrecisions
-        });
-        if (!preCommitGuard.canCommit) {
-            this.logger.log(`[COW] ${preCommitGuard.reason}`, preCommitGuard.level || 'warn');
-            this._clearWorkingGridRef();
-            return false;
-        }
-        await this._gridLock.acquire(async () => {
-            const lockCommitGuard = (0, validate_1.evaluateCommit)(workingGrid, {
-                hasLock: true,
+            const { skipRecalc: skipRecalcOpt } = this._normalizeCommitOptions(options);
+            skipRecalc = skipRecalcOpt;
+            const stats = workingGrid.getMemoryStats();
+            try {
+                comparePrecisions = this._getCowComparePrecisions();
+            }
+            catch (precisionErr) {
+                this.logger.log(`[COW] ${(0, errors_1.getErrorMessage)(precisionErr)}`, 'error');
+                releaseStackEntry();
+                return false;
+            }
+            const preCommitGuard = (0, validate_1.evaluateCommit)(workingGrid, {
+                hasLock: false,
                 currentVersion: this._gridVersion,
                 masterGrid: this.orders,
                 comparePrecisions
             });
-            if (!lockCommitGuard.canCommit) {
-                this.logger.log(`[COW] ${lockCommitGuard.reason}`, lockCommitGuard.level || 'warn');
-                this._clearWorkingGridRef();
-                return;
+            if (!preCommitGuard.canCommit) {
+                this.logger.log(`[COW] ${preCommitGuard.reason}`, preCommitGuard.level || 'warn');
+                releaseStackEntry();
+                return false;
             }
-            this.logger.log(`[COW] Committing working grid: ${stats.size} orders, ${stats.modified} modified`, 'debug');
-            const finalMap = workingGrid.toMap();
-            // RC-4: Deep-freeze all modified orders before committing to master state
-            // Ensures COW immutability invariants are maintained for all grid entries.
-            for (const [, order] of finalMap.entries()) {
-                if (order && !Object.isFrozen(order)) {
-                    (0, system_1.deepFreeze)(order);
+            await this._gridLock.acquire(async () => {
+                const lockCommitGuard = (0, validate_1.evaluateCommit)(workingGrid, {
+                    hasLock: true,
+                    currentVersion: this._gridVersion,
+                    masterGrid: this.orders,
+                    comparePrecisions
+                });
+                if (!lockCommitGuard.canCommit) {
+                    this.logger.log(`[COW] ${lockCommitGuard.reason}`, lockCommitGuard.level || 'warn');
+                    // Working grid ref is cleared exactly once below via the
+                    // !committed path (the callback returns without committing).
+                    return;
                 }
+                this.logger.log(`[COW] Committing working grid: ${stats.size} orders, ${stats.modified} modified`, 'debug');
+                const finalMap = workingGrid.toMap();
+                // RC-4: Deep-freeze all modified orders before committing to master state
+                // Ensures COW immutability invariants are maintained for all grid entries.
+                for (const [, order] of finalMap.entries()) {
+                    if (order && !Object.isFrozen(order)) {
+                        (0, system_1.deepFreeze)(order);
+                    }
+                }
+                this.orders = Object.freeze(finalMap);
+                this._setBoundary(workingBoundary);
+                this._gridVersion++;
+                committed = true;
+                // Track orderIds from successful COW commits for recovery sync protection.
+                // Build a new set from the committed finalMap and atomically swap to
+                // avoid the intermediate empty state that clear() creates — a crash
+                // during clear()+repopulate would lose all committed IDs.
+                const newCommittedIds = new Set();
+                for (const [, order] of finalMap.entries()) {
+                    if (order.orderId)
+                        newCommittedIds.add(order.orderId);
+                }
+                this._committedOrderIds = newCommittedIds;
+                this._committedOrderIdsBuiltAt = Date.now();
+                // Index caches invalidated by _gridVersion bump above — lazy getters recompute from this.orders
+            });
+            if (!committed) {
+                releaseStackEntry();
+                return false;
             }
-            this.orders = Object.freeze(finalMap);
-            this._setBoundary(workingBoundary);
-            this._gridVersion++;
-            committed = true;
-            // Track orderIds from successful COW commits for recovery sync protection.
-            // Build a new set from the committed finalMap and atomically swap to
-            // avoid the intermediate empty state that clear() creates — a crash
-            // during clear()+repopulate would lose all committed IDs.
-            const newCommittedIds = new Set();
-            for (const [, order] of finalMap.entries()) {
-                if (order.orderId)
-                    newCommittedIds.add(order.orderId);
-            }
-            this._committedOrderIds = newCommittedIds;
-            this._committedOrderIdsBuiltAt = Date.now();
-            // Index caches invalidated by _gridVersion bump above — lazy getters recompute from this.orders
-        });
-        if (!committed) {
-            this._clearWorkingGridRef();
-            return false;
-        }
-        try {
-            if (!skipRecalc) {
-                // If the last accounting failure was due to stale accountTotals,
-                // the commit proceeded without locking funds. Refresh accountTotals
-                // before recalculateFunds() to avoid a false-positive drift recovery.
-                if (this._lastAccountingFailure?.reason === 'stale') {
-                    this.logger.log('[COW] Stale accountTotals during commit; refreshing before recalculateFunds to avoid false recovery', 'warn');
-                    await this.fetchAccountTotals(this.accountId);
+            try {
+                if (!skipRecalc) {
+                    // If the last accounting failure was due to stale accountTotals,
+                    // the commit proceeded without locking funds. Refresh accountTotals
+                    // before recalculateFunds() to avoid a false-positive drift recovery.
+                    if (this._lastAccountingFailure?.reason === 'stale') {
+                        this.logger.log('[COW] Stale accountTotals during commit; refreshing before recalculateFunds to avoid false recovery', 'warn');
+                        await this.fetchAccountTotals(this.accountId);
+                    }
+                    await this.recalculateFunds();
+                }
+                const duration = Date.now() - startTime;
+                this.logger.log(`[COW] Grid committed in ${duration}ms`, 'debug');
+                if (stats.size > constants_1.COW_PERFORMANCE.GRID_MEMORY_WARNING) {
+                    this.logger.log(`[COW] Warning: Large grid size (${stats.size} orders). Peak memory: ~${Math.round(stats.estimatedBytes / 1024)}KB`, 'warn');
                 }
-                await this.recalculateFunds();
             }
-            const duration = Date.now() - startTime;
-            this.logger.log(`[COW] Grid committed in ${duration}ms`, 'debug');
-            if (stats.size > constants_1.COW_PERFORMANCE.GRID_MEMORY_WARNING) {
-                this.logger.log(`[COW] Warning: Large grid size (${stats.size} orders). Peak memory: ~${Math.round(stats.estimatedBytes / 1024)}KB`, 'warn');
+            catch (recalcErr) {
+                this.logger.log(`[COW] Fund recalculation failed post-commit: ${(0, errors_1.getErrorMessage)(recalcErr)}`, 'error');
+                this._recoveryState = { ...this._recoveryState, lastFailureAt: Date.now() };
+                // Re-throw to signal callers that the commit is incomplete
+                // (grid state committed, but fund state is stale).
+                releaseStackEntry();
+                throw recalcErr;
             }
+            releaseStackEntry();
+            return true;
         }
-        catch (recalcErr) {
-            this.logger.log(`[COW] Fund recalculation failed post-commit: ${(0, errors_1.getErrorMessage)(recalcErr)}`, 'error');
-            this._recoveryState = { ...this._recoveryState, lastFailureAt: Date.now() };
-            // Re-throw to signal callers that the commit is incomplete
-            // (grid state committed, but fund state is stale).
-            throw recalcErr;
+        catch (err) {
+            // Unhandled commit failure (e.g. _gridLock acquisition timeout or
+            // an in-lock commit error): nothing was committed, but the stack
+            // entry must still be released exactly once.
+            releaseStackEntry();
+            throw err;
         }
-        finally {
-            this._clearWorkingGridRef();
-        }
-        return true;
     }
     /**
      * @param {Object} [options]
@@ -1544,7 +1818,7 @@ class OrderManager {
      *   swapping the live map and exposing it to concurrent readers.
      * @returns {Promise<import('./types').PersistenceValidationResult>}
      */
-    async persistGrid(snapshotOrders, recentFillKeys) {
+    async persistGrid(snapshotOrders, recentFillKeys, fundSnapshot) {
         if (this._gridPersistenceSuspendedReason) {
             this.logger.log(`[PERSISTENCE-GATE] Skipping grid persistence while suspended: ${this._gridPersistenceSuspendedReason}`, 'warn');
             return { isValid: true, skipped: true, suspended: true, reason: this._gridPersistenceSuspendedReason };
@@ -1554,7 +1828,20 @@ class OrderManager {
             this.logger.log(`[PERSISTENCE-GATE] Skipping persistence of corrupted state: ${validation.reason}`, 'warn');
             return validation;
         }
-        const persisted = await (0, system_1.persistGridSnapshot)(this, this.accountOrders, snapshotOrders, recentFillKeys);
+        // Capture fund state under _fundLock so the persisted snapshot is
+        // internally consistent even when fills/fee settlement mutate
+        // accountTotals concurrently (same TOCTOU fixed for recalculateGrid
+        // at grid.ts:~1047). An explicit fundSnapshot (recalculateGrid) is
+        // kept as an override — the caller captured it under the same lock
+        // right after resetFunds.
+        let effectiveFundSnapshot = fundSnapshot;
+        if (!effectiveFundSnapshot) {
+            effectiveFundSnapshot = await this._fundLock.acquire(async () => ({
+                btsFeesOwed: this.funds.btsFeesOwed,
+                accountTotals: this.accountTotals,
+            }));
+        }
+        const persisted = await (0, system_1.persistGridSnapshot)(this, this.accountOrders, snapshotOrders, recentFillKeys, effectiveFundSnapshot);
         if (persisted === false) {
             this.logger.log(`[PERSIST] Grid persistence FAILED (disk full / permissions / write error)`, 'error');
             // Keep the dirty flag set so the next flush retries.