dexbot 1.5.3 → 1.6.0

package/dist/modules/order/utils/order.js

@@ -60,10 +60,14 @@
  *   - buildDelta(masterGrid, workingGrid) - Build delta actions between grids
  *   - getOrderSize(order) - Extract order size with fallback
  *
- * SECTION 10: STRATEGY CALCULATIONS (3 functions)
- *   - deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, config, gapSlots, crossChunkBudget) - Derive boundary from fills (returns { boundaryIdx, remainingBudget })
- *   - getSideBudget(side, funds, config, totalTarget) - Calculate side budget after fees
- *   - calculateBudgetedSizes(slots, side, budget, weightDist, incrementPercent, assets) - Calculate budgeted sizes
+ * SECTION 10: STRATEGY CALCULATIONS (7 functions)
+ *   - resolveReserveCount(config, side) - Clamped per-side reserve count (>=0 int, 0 disables)
+ *   - resolveReserveOrders(config) - Total reserves buy+sell (fee/count totals)
+ *   - resolveLiveReserveEdgeAnchorPrice(manager, side) - Live-grid edge anchor (ladder/rail extreme first, config bound last; null when unresolved)
+ *   - resolveReserveEdgeAnchorPrice(config, side) - Config-bound anchor fallback (buy→minPrice, sell→maxPrice; null when unresolvable)
+ *   - compareReserveEdge(a, b, edge, anchorPrice) - Shared anchored edge comparator (single ordering source)
+ *   - reserveEdgeIdSet(allSlots, config, orderType, anchorPrice?) - Edge reserve id set (config count; shares the picker ordering)
+ *   - selectReserveEdgeSlots(sortedAsc, count, excludeIds, edge, anchorPrice?) - Shared position picker (both edges anchor toward their bound)
  *
  * ===============================================================================
  */
@@ -1245,6 +1249,26 @@ function formatUnmatchedChainOrder(order) {
         parts.push(`candidates=${order.candidateDiagnostics}`);
     return parts.join(' ');
 }
+/**
+ * Whether an unmatched chain-order entry is a deliberate hold that must NOT
+ * block CREATEs or snapshot recovery.
+ *
+ * Deferred entries (`reason` suffixed `-deferred`) are permanently
+ * non-adoptable and non-cancellable: an out-of-grid hold sits outside the
+ * frozen rail, and a boundary-unknown hold is re-evaluated once the boundary
+ * commits. Treating one as a blocker freezes the whole grid (a single
+ * dip-protection hold would stop every CREATE) and forces a full reset on
+ * recovery. Classification is by the shared `-deferred` suffix, not an exact
+ * reason string, so a new defer reason cannot silently regress into a
+ * permanent blocker.
+ *
+ * @param {Object} order - Unmatched chain order entry.
+ * @returns {boolean} True when the entry is a non-blocking deferred hold.
+ */
+function isNonBlockingUnmatchedOrder(order) {
+    const reason = order?.reason;
+    return typeof reason === 'string' && reason.endsWith('-deferred');
+}
 /**
  * Check if order is on blockchain (ACTIVE or PARTIAL state).
  *
@@ -1416,6 +1440,13 @@ function checkSizesBeforeMinimum(sizes, minSize, precision) {
  * Calculate ideal grid boundary based on reference price.
  * Places boundary near reference price with gap spacing in mind.
  *
+ * A non-numeric reference (e.g. the unresolved "pool"/"book" mode strings)
+ * makes every `price >= reference` comparison false, which used to resolve
+ * `splitIdx` to `allSlots.length` and fabricate a top-of-rail boundary —
+ * the degenerate all-buy geometry behind the 02:03 slot-77→slot-192 (+58%)
+ * teleport plan. Fail toward rail-center instead; callers with a real
+ * anchor (genesis startPrice, live center) override before calling.
+ *
  * @param {Array<Object>} allSlots - All grid slots sorted by price
  * @param {number} referencePrice - Reference/anchor price
  * @param {number} gapSlots - Number of gap slots between buy and sell
@@ -1424,6 +1455,10 @@ function checkSizesBeforeMinimum(sizes, minSize, precision) {
 function calculateIdealBoundary(allSlots, referencePrice, gapSlots) {
     if (!allSlots || allSlots.length === 0)
         return -1;
+    if (!Number.isFinite(Number(referencePrice))) {
+        const gap = Number.isFinite(Number(gapSlots)) && Number(gapSlots) >= 0 ? Math.floor(Number(gapSlots)) : 0;
+        return Math.max(0, Math.floor((allSlots.length - 1 - gap) / 2));
+    }
     let splitIdx = allSlots.findIndex((s) => s.price >= referencePrice);
     if (splitIdx === -1)
         splitIdx = allSlots.length;
@@ -1755,23 +1790,156 @@ function buildDelta(masterGrid, workingGrid, options = {}) {
 function isShiftEligibleFill(fill) {
     return fill?.isPartial !== true || fill?.isDelayedRotationTrigger === true;
 }
-function deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, config, gapSlots, crossChunkBudget) {
+function deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, config, gapSlots, crossChunkBudget, pendingCrawls, edgeAnchors) {
     let newBoundaryIdx = currentBoundaryIdx;
-    // Initial recovery if boundary is undefined
+    // Recovery when the committed boundary is unknown (GRID-LOAD rejected a
+    // poisoned snapshot, re-derivation failed, and no fill has re-anchored
+    // since). Anchor tiers are position signals, weakest last. What must
+    // never happen is fabricating a rail-edge boundary from an unresolved
+    // config mode string: startPrice "pool" NaN-matches every price
+    // comparison, resolving to the rail top (Sep-10: base 213, ceiling 211,
+    // then 209 after 4 buy crawls — teleporting the buy rail 113 slots).
+    let recovered = false;
+    let anchoredFromFills = false;
     if (newBoundaryIdx === undefined || newBoundaryIdx === null) {
-        const referencePrice = config.startPrice;
+        // Tier 1 — live fills: gap-side extreme (highest buy / lowest sell,
+        // midpoint when both sides filled). Any fill price, eligible or
+        // dust, is real market position and beats every config guess.
+        let topBuy = -Infinity;
+        let botSell = Infinity;
+        for (const fill of fills ?? []) {
+            const p = Number(fill?.price);
+            if (!Number.isFinite(p))
+                continue;
+            if (fill?.type === ORDER_TYPES.BUY && p > topBuy)
+                topBuy = p;
+            if (fill?.type === ORDER_TYPES.SELL && p < botSell)
+                botSell = p;
+        }
+        let referencePrice = null;
+        if (topBuy > -Infinity && botSell < Infinity) {
+            referencePrice = (topBuy + botSell) / 2;
+            anchoredFromFills = true;
+        }
+        else if (topBuy > -Infinity) {
+            referencePrice = topBuy;
+            anchoredFromFills = true;
+        }
+        else if (botSell < Infinity) {
+            referencePrice = botSell;
+            anchoredFromFills = true;
+        }
+        // Tier 2 — explicit numeric config center.
+        if (referencePrice === null) {
+            const direct = Number(config?.startPrice);
+            if (Number.isFinite(direct))
+                referencePrice = direct;
+        }
+        // Tier 3 — frozen genesis center (forwarded by the strategy when
+        // config.startPrice is an unresolved mode string).
+        if (referencePrice === null) {
+            const genesis = Number(config?.genesisStartPrice);
+            if (Number.isFinite(genesis))
+                referencePrice = genesis;
+        }
+        // Stale-center guard: a Tier-2 numeric config center or a Tier-3
+        // genesis center that falls outside the live rail would clamp
+        // calculateIdealBoundary onto an edge slot — the same rail-edge
+        // fabrication the mode-string fix prevents, just from a stale numeric
+        // value. Drop such a reference so the bounded Tier-4 rail center is
+        // used instead. Tier-1 fill anchors are exempt: a real (possibly
+        // out-of-grid) fill price is live market position and wins everywhere.
+        if (!anchoredFromFills && referencePrice !== null && Array.isArray(allSlots) && allSlots.length > 0) {
+            let railMin = Infinity;
+            let railMax = -Infinity;
+            for (const s of allSlots) {
+                const p = Number(s?.price);
+                if (!Number.isFinite(p))
+                    continue;
+                if (p < railMin)
+                    railMin = p;
+                if (p > railMax)
+                    railMax = p;
+            }
+            if ((Number.isFinite(railMin) && referencePrice < railMin)
+                || (Number.isFinite(railMax) && referencePrice > railMax)) {
+                orderLogger.debug(`deriveTargetBoundary: recovery center ${referencePrice} outside live rail ` +
+                    `[${railMin}, ${railMax}]; using bounded rail center instead of pinning an edge`);
+                referencePrice = null;
+            }
+        }
+        // Tier 4 — rail center: bounded and wrong by at most half the rail,
+        // never a rail-edge fabrication. The next fill batch re-anchors
+        // from live prices via Tier 1.
+        if (referencePrice === null && Array.isArray(allSlots) && allSlots.length > 0) {
+            const gap = Number.isFinite(Number(gapSlots)) && Number(gapSlots) >= 0 ? Math.floor(Number(gapSlots)) : 0;
+            const centerIdx = Math.max(0, Math.floor((allSlots.length - 1 - gap) / 2));
+            const centerPrice = Number(allSlots[centerIdx]?.price);
+            if (Number.isFinite(centerPrice))
+                referencePrice = centerPrice;
+        }
+        if (referencePrice === null) {
+            const fallbackCap = Math.max(Math.floor((config?.activeOrders?.sell ?? 1) / 2), Math.floor((config?.activeOrders?.buy ?? 1) / 2), 1);
+            const effectiveBudget = crossChunkBudget ?? fallbackCap;
+            return { boundaryIdx: null, remainingBudget: effectiveBudget };
+        }
         newBoundaryIdx = calculateIdealBoundary(allSlots, referencePrice, gapSlots);
+        if (!Number.isFinite(newBoundaryIdx) || newBoundaryIdx < 0) {
+            // Empty slot list with a Tier 1-3 reference: no honest index
+            // exists (calculateIdealBoundary returns -1). Stay null rather
+            // than letting the clamp below fabricate a slot-0 boundary.
+            const fallbackCap = Math.max(Math.floor((config?.activeOrders?.sell ?? 1) / 2), Math.floor((config?.activeOrders?.buy ?? 1) / 2), 1);
+            return { boundaryIdx: null, remainingBudget: crossChunkBudget ?? fallbackCap };
+        }
+        recovered = true;
     }
-    // Apply shift from fills with rate-limiting
+    // Apply shift from fills with rate-limiting (reserve fills excluded: static insurance).
     let netShift = 0;
+    // Reserve ladder: fills from edge-pinned reserve slots never crawl the
+    // boundary — they are static fat-finger insurance, not market movement.
+    // `edgeAnchors` (resolveLiveReserveEdgeAnchorPrice) is the same anchor the
+    // placement sites use; without it the classification falls back to the
+    // config-bound anchor, which can disagree with the slots actually placed.
+    const reserveBuyIds = reserveEdgeIdSet(allSlots, config, ORDER_TYPES.BUY, edgeAnchors?.buy ?? null);
+    const reserveSellIds = reserveEdgeIdSet(allSlots, config, ORDER_TYPES.SELL, edgeAnchors?.sell ?? null);
+    // Pending crawls: fills recorded by earlier batches whose derivation
+    // never committed (refused broadcast, P4 abort, or pre-restart loss —
+    // the Sep-10 case: 4 fills consumed under a null boundary, crawl lost,
+    // restart refilled the holes same-side). Entries for slots in the
+    // CURRENT batch are excluded — those fills crawl below as usual;
+    // anything older is still owed and shifts here. Reserve-slot entries
+    // never crawl (static insurance), same as live fills.
+    const currentSlotIds = new Set((fills ?? []).map((f) => f?.id).filter((id) => typeof id === 'string' && id.length > 0));
+    const owedPending = (pendingCrawls ?? []).filter((e) => e
+        && typeof e.slotId === 'string' && e.slotId.length > 0
+        && !currentSlotIds.has(e.slotId)
+        && (e.side === ORDER_TYPES.BUY || e.side === ORDER_TYPES.SELL)
+        && !(e.side === ORDER_TYPES.BUY && reserveBuyIds && reserveBuyIds.has(e.slotId))
+        && !(e.side === ORDER_TYPES.SELL && reserveSellIds && reserveSellIds.has(e.slotId)));
     for (const fill of fills) {
         if (!isShiftEligibleFill(fill))
             continue;
+        if (fill && fill.type === ORDER_TYPES.BUY && reserveBuyIds && reserveBuyIds.has(fill.id))
+            continue;
+        if (fill && fill.type === ORDER_TYPES.SELL && reserveSellIds && reserveSellIds.has(fill.id))
+            continue;
         if (fill.type === ORDER_TYPES.SELL)
             netShift++;
         else if (fill.type === ORDER_TYPES.BUY)
             netShift--;
     }
+    if (!anchoredFromFills) {
+        // Owed deltas from earlier uncommitted batches shift on top of the
+        // current fills. Skipped under an absolute fill anchor: the anchor
+        // positions from live market prices, which already reflect all
+        // consumed fills — shifting again would double-count.
+        for (const e of owedPending) {
+            if (e.side === ORDER_TYPES.SELL)
+                netShift++;
+            else
+                netShift--;
+        }
+    }
     // Cap cumulative shift to prevent overreaction from burst fills.
     // Uses a cross-chunk budget managed by the caller — each chunk
     // consumes from the same pool so the total across all chunks
@@ -1780,6 +1948,16 @@ function deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, config, gapSl
     const fallbackCap = Math.max(Math.floor((config.activeOrders?.sell ?? 1) / 2), Math.floor((config.activeOrders?.buy ?? 1) / 2), 1);
     const effectiveBudget = crossChunkBudget ?? fallbackCap;
     const cap = Math.min(Math.abs(effectiveBudget), fallbackCap);
+    if (recovered && anchoredFromFills) {
+        // The anchor already contains this batch's fill information —
+        // crawling would double-count the same fills (Sep-10 batch 1:
+        // dust-sell anchor 97 plus a +1 crawl would have moved it to 98).
+        // The next batch crawls normally from the anchored boundary.
+        return {
+            boundaryIdx: Math.max(0, Math.min((allSlots.length - gapSlots - 1) >= 0 ? (allSlots.length - gapSlots - 1) : (allSlots.length - 1), newBoundaryIdx)),
+            remainingBudget: effectiveBudget,
+        };
+    }
     if (Math.abs(netShift) > cap) {
         netShift = Math.sign(netShift) * cap;
     }
@@ -1799,16 +1977,488 @@ function deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, config, gapSl
         remainingBudget,
     };
 }
+/**
+ * Apply recorded-but-uncommitted fill crawls to the committed boundary.
+ * Fills are recorded at intake (strategy) and consumed by derivation on
+ * commit — but a refused broadcast, a plan abort, or a restart in between
+ * leaves their crawl owed and the boundary stale. The next derivation
+ * incorporates them in-run (pendingCrawls param); this consumes them onto
+ * a restored boundary at startup, before reconcile refills holes.
+ *
+ * Safety: entries are relative deltas, so they apply only onto a FINITE
+ * restored boundary (a null boundary is re-anchored absolutely from live
+ * fill prices instead — subsuming every owed delta). The candidate is
+ * validated placed-order-aware like GRID-LOAD; on failure the entries are
+ * dropped rather than stranding live orders. Commits clear the record, so
+ * entries present here predate every commit since recording — always owed.
+ *
+ * @param {any} manager - OrderManager (boundaryIdx, orders, config restored)
+ * @returns {{applied: boolean, from?: number, to?: number, count?: number, reason?: string}}
+ */
+export function consumePendingFillCrawls(manager) {
+    const pending = Array.isArray(manager?._pendingFillCrawls) ? manager._pendingFillCrawls : [];
+    if (pending.length === 0)
+        return { applied: false };
+    // Clearing marks the grid dirty so the cleared record reaches disk on
+    // the next flush — including drop paths (unsafe/null/no-op), whose
+    // decisions re-derive identically but whose stale disk entries would
+    // otherwise linger until an unrelated write.
+    const clear = () => {
+        manager._pendingFillCrawls = [];
+        if (typeof manager?._markGridDirty === 'function') {
+            try {
+                manager._markGridDirty();
+            }
+            catch { /* best-effort */ }
+        }
+    };
+    // NB: Number(null) === 0 — check null/undefined explicitly, or a
+    // boundary-less manager would "apply" onto slot 0.
+    if (manager?.boundaryIdx === null || manager?.boundaryIdx === undefined) {
+        clear();
+        return { applied: false, reason: 'null-boundary' };
+    }
+    const boundary = Number(manager?.boundaryIdx);
+    if (!Number.isFinite(boundary)) {
+        clear();
+        return { applied: false, reason: 'null-boundary' };
+    }
+    const config = manager?.config ?? {};
+    const slots = Array.from(manager?.orders instanceof Map ? manager.orders.values() : []);
+    // Classify with the SAME live anchors the strategy derivation uses, or the
+    // two disagree: the config-bound fallback is null for mode-string/relative
+    // bounds, so a restart would rank a stale below-rail slot as a reserve and
+    // silently drop a crawl the live run recorded as ordinary market movement.
+    const reserveBuyIds = reserveEdgeIdSet(slots, config, ORDER_TYPES.BUY, resolveLiveReserveEdgeAnchorPrice(manager, 'buy'));
+    const reserveSellIds = reserveEdgeIdSet(slots, config, ORDER_TYPES.SELL, resolveLiveReserveEdgeAnchorPrice(manager, 'sell'));
+    let netShift = 0;
+    let count = 0;
+    for (const e of pending) {
+        if (!e || typeof e.slotId !== 'string' || e.slotId.length === 0)
+            continue;
+        if (e.side !== ORDER_TYPES.BUY && e.side !== ORDER_TYPES.SELL)
+            continue;
+        if (e.side === ORDER_TYPES.BUY && reserveBuyIds && reserveBuyIds.has(e.slotId))
+            continue;
+        if (e.side === ORDER_TYPES.SELL && reserveSellIds && reserveSellIds.has(e.slotId))
+            continue;
+        netShift += e.side === ORDER_TYPES.SELL ? 1 : -1;
+        count++;
+    }
+    if (count === 0) {
+        clear();
+        return { applied: false, reason: 'nothing-owed' };
+    }
+    const fallbackCap = Math.max(Math.floor((config?.activeOrders?.sell ?? 1) / 2), Math.floor((config?.activeOrders?.buy ?? 1) / 2), 1);
+    if (Math.abs(netShift) > fallbackCap)
+        netShift = Math.sign(netShift) * fallbackCap;
+    let gapSlots = Number(manager?._gapSlots);
+    if (!Number.isFinite(gapSlots)) {
+        try {
+            gapSlots = MathUtils.calculateGapSlots(config?.incrementPercent, config?.targetSpreadPercent, config?.gridLimits);
+        }
+        catch {
+            gapSlots = 0;
+        }
+    }
+    const ceiling = (slots.length - gapSlots - 1) >= 0 ? (slots.length - gapSlots - 1) : (slots.length - 1);
+    const candidate = Math.max(0, Math.min(ceiling, boundary + netShift));
+    if (candidate === boundary) {
+        clear();
+        return { applied: false, reason: 'no-op' };
+    }
+    let check = { ok: true };
+    try {
+        check = MathUtils.validatePersistedBoundary(candidate, slots, gapSlots);
+    }
+    catch (err) {
+        check = { ok: false, reason: 'validator-threw', detail: String(err?.message ?? err) };
+    }
+    if (!check || check.ok !== true) {
+        clear();
+        return { applied: false, reason: `unsafe: ${check?.reason ?? 'unknown'}${check?.detail ? ` ${check.detail}` : ''}` };
+    }
+    try {
+        manager._restoreBoundary(candidate);
+    }
+    catch {
+        return { applied: false, reason: 'restore-failed' };
+    }
+    clear();
+    return { applied: true, from: boundary, to: candidate, count };
+}
+/**
+ * Per-side reserve count (edge-pinned fat-finger insurance orders).
+ * Buy reserves pin at the grid floor, sell reserves at the grid ceiling.
+ * Non-finite/non-integer/negative values disable (0).
+ *
+ * @param {Object} config - Bot configuration
+ * @param {string} side - 'buy' or 'sell'
+ * @returns {number} Reserve count for the side (>= 0 integer)
+ */
+function resolveReserveCount(config, side) {
+    const key = side === 'sell' ? 'sell' : 'buy';
+    const raw = Number(config?.reserveOrders?.[key] ?? 0);
+    if (!Number.isInteger(raw) || raw < 0)
+        return 0;
+    return raw;
+}
+/**
+ * Total reserve count across both sides (fee/count totals).
+ *
+ * @param {Object} config - Bot configuration
+ * @returns {number} Total reserves (buy + sell)
+ */
+function resolveReserveOrders(config) {
+    return resolveReserveCount(config, 'buy') + resolveReserveCount(config, 'sell');
+}
+/**
+ * Edge-pinned reserve id set for one side, or null when disabled.
+ * Type/price-filtered, then ordered by the SAME edge order the placement
+ * pickers use (compareReserveEdge via selectReserveEdgeSlots) — single source
+ * of truth, so the no-crawl classification can never drift from placement.
+ * Anchor: explicit live-grid edge when supplied, otherwise the config-bound
+ * fallback (unresolved -> plain rank). Shelf/manual ids (non-slot-N, e.g.
+ * fork-kept deep-* orders below the rail) are never reserves: they would
+ * otherwise win the cheapest-first rank and poison the deficit check while
+ * the shelf is live (issue #27 follow-up). No-op upstream (grids only mint
+ * slot-N).
+ *
+ * @param {Array<Object>} allSlots - All grid slots (need id/price/type)
+ * @param {Object} config - Bot configuration (reserve count source)
+ * @param {string} orderType - ORDER_TYPES.BUY (floor) or SELL (ceiling)
+ * @param {number|null} [anchorPrice] - Explicit edge anchor (live grid edge);
+ *   callers that picked slots must pass the SAME anchor so no-crawl
+ *   classification matches placement. NB: null/undefined falls back to the
+ *   config-bound anchor (unresolved -> plain rank) — unlike
+ *   selectReserveEdgeSlots, where null alone means plain rank.
+ * @param {Set<string>|null} [excludeIds] - Windowed ids to skip (same set the
+ *   placement pickers exclude). Window + edge are additive in every target
+ *   (order counts, fees, hold-back), so a window that reaches the grid edge
+ *   (e.g. a keep-low window sitting on the floor) must not let the edge pick
+ *   land on window members — otherwise counting reads N/N with zero
+ *   dedicated reserves and the deficit never fires (issue #27 follow-up).
+ * @returns {Set<string>|null} Edge slot ids, or null when side disabled
+ */
+function reserveEdgeIdSet(allSlots, config, orderType, anchorPrice = null, excludeIds = null) {
+    const isSell = orderType === ORDER_TYPES.SELL;
+    const side = isSell ? 'sell' : 'buy';
+    // Filter by the canonical side type, not the caller's token: the previous
+    // per-side resolvers did the same, so a non-canonical token keeps the
+    // floor behavior instead of silently matching nothing.
+    const type = isSell ? ORDER_TYPES.SELL : ORDER_TYPES.BUY;
+    const n = resolveReserveCount(config, side);
+    if (n <= 0)
+        return null;
+    const ids = new Set();
+    if (!Array.isArray(allSlots))
+        return ids;
+    // NB: Number(null) === 0 is finite — null/undefined must mean "no anchor".
+    const anchor = anchorPrice == null ? resolveReserveEdgeAnchorPrice(config, side) : Number(anchorPrice);
+    const ascending = allSlots
+        .filter((s) => s && s.id != null && s.price != null && s.type === type && parseSlotIndex(s.id) !== null)
+        .sort((a, b) => Number(a.price) - Number(b.price));
+    for (const s of selectReserveEdgeSlots(ascending, n, excludeIds, isSell ? 'ceiling' : 'floor', anchor)) {
+        ids.add(s.id);
+    }
+    return ids;
+}
+/**
+ * Window member ids for one side, mirroring the window every placement
+ * picker excludes from its reserve pick: in-rail slots of the side (geometry
+ * via resolveGapBand/isSlotInRail — the same source the reconcile pickers
+ * use), ordered closest to market first (buys: highest price first; sells:
+ * lowest first), sliced to the configured activeOrders count. The slice runs
+ * over the FULL master rail, not just live orders — window membership is
+ * geometric (a virtual hole inside the window still blocks the reserve pick
+ * there), so live-only slices would misclassify live reserves as window
+ * members whenever the window itself is under-filled.
+ *
+ * Returns null when the boundary geometry is unknown: the pickers cannot
+ * place reserves without it either, so callers fail open (no exclusion)
+ * and keep their previous classification instead of guessing.
+ *
+ * @param {any} manager - OrderManager (orders Map, config, boundaryIdx)
+ * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+ * @returns {Set<string>|null} Window slot ids, or null when geometry unknown
+ */
+function liveWindowIdSet(manager, orderType) {
+    try {
+        const isSell = orderType === ORDER_TYPES.SELL;
+        const type = isSell ? ORDER_TYPES.SELL : ORDER_TYPES.BUY;
+        const side = isSell ? 'sell' : 'buy';
+        const count = Math.max(0, Math.floor(Number(manager?.config?.activeOrders?.[side])) || 0);
+        if (!(count > 0) || !manager?.orders || typeof manager.orders.values !== 'function')
+            return new Set();
+        const resolved = MathUtils.resolveGapBand(manager);
+        if (resolved?.boundaryIdx == null || resolved?.sellStartIdx == null)
+            return null;
+        const inRail = (o) => MathUtils.isSlotInRail(resolved.boundaryIdx, resolved.gapSlots, type, o);
+        // Same type filter as the window pickers with known geometry: the
+        // side's concrete type plus SPREAD placeholders (normalized empties
+        // sitting in this side's rail).
+        const typeFilter = (o) => o && o.id != null && o.price != null && (o.type === type || o.type === ORDER_TYPES.SPREAD);
+        const ids = Array.from(manager.orders.values())
+            .filter(typeFilter)
+            .filter(inRail)
+            .sort((a, b) => isSell ? Number(a.price) - Number(b.price) : Number(b.price) - Number(a.price))
+            .slice(0, count)
+            .map((o) => String(o.id));
+        return new Set(ids);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Refill-slot wire for the COW boundary hold (single source for both plan
+ * producers: the fill-driven COW engine and the divergence fold).
+ *
+ * The hold keeps the committed boundary when a listed refill is guard-skipped
+ * at broadcast — the refill is what justified the plan's boundary shift, so
+ * committing the shift without it would strand an empty rail slot past the
+ * new boundary. The wire must therefore list only placements that justify the
+ * shift:
+ *
+ *   - CREATE ids of the plan (the slots a fold did not convert into an
+ *     UPDATE), minus
+ *   - reserve-ladder ids. Reserves are static edge insurance; their fills
+ *     never crawl (deriveTargetBoundary filters them), so a guard-skipped
+ *     reserve must not pin geometry either. Without this exclusion a reserve
+ *     CREATE skipped at the wrong moment (e.g. a floor BUY above the last-fill
+ *     pivot while the market dumps below the grid) would hold the boundary for
+ *     a cycle although nothing was stranded.
+ *
+ * Absent/disabled reserves or an empty action list yield the plain CREATE ids,
+ * so callers that never configured reserves keep the previous behavior.
+ *
+ * @param {Array<Object>} actions - Optimized COW actions
+ * @param {Object} [options]
+ * @param {Object} [options.config] - Bot configuration (reserve count source)
+ * @param {Iterable<Object>} [options.slots] - Master slots (reserve classification)
+ * @param {{buy?: number|null, sell?: number|null}} [options.edgeAnchors] - Live
+ *   edge anchors (same pair the strategy classifies reserve fills against)
+ * @returns {string[]} Refill slot ids (CREATE ids minus reserve edge ids)
+ */
+function collectRefillSlotIds(actions, options = {}) {
+    const { config = null, slots = null, edgeAnchors = null } = options;
+    const out = [];
+    if (!Array.isArray(actions))
+        return out;
+    const createIds = actions
+        .filter((a) => a?.type === COW_ACTIONS.CREATE && typeof a?.id === 'string' && a.id.length > 0)
+        .map((a) => a.id);
+    if (createIds.length === 0)
+        return out;
+    let reserveIds = null;
+    if (slots && config) {
+        try {
+            // Accept a Map (master grid), an array of slots, or any iterable of
+            // slot objects. Map entries are [id, slot] pairs, so `.values()` is
+            // required — Array.from(map) would hand reserveEdgeIdSet pairs.
+            const allSlots = Array.isArray(slots)
+                ? slots
+                : (typeof slots?.values === 'function'
+                    ? Array.from(slots.values())
+                    : Array.from(slots));
+            const buyIds = reserveEdgeIdSet(allSlots, config, ORDER_TYPES.BUY, edgeAnchors?.buy ?? null);
+            const sellIds = reserveEdgeIdSet(allSlots, config, ORDER_TYPES.SELL, edgeAnchors?.sell ?? null);
+            if (buyIds || sellIds)
+                reserveIds = new Set([...(buyIds ?? []), ...(sellIds ?? [])]);
+        }
+        catch {
+            reserveIds = null;
+        }
+    }
+    for (const id of createIds) {
+        // Fail-open on classification errors: an id we cannot prove is a reserve
+        // stays in the wire, so the hold keeps its previous (conservative) reach.
+        if (reserveIds && reserveIds.has(id))
+            continue;
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Resolved bound anchor for reserve edges from CONFIG alone.
+ * BUY floor anchors toward minPrice (dip-insurance end), SELL ceiling toward
+ * maxPrice (spike-insurance end). Resolves numeric and "Nx" relative forms
+ * via resolveConfiguredPriceBound (startPrice-referenced); falls back to the
+ * raw numeric bound. Returns null when unresolvable.
+ *
+ * Known limit: this is the statically resolved config bound, not the
+ * gridPrice/AMA-referenced live rail bound. Placement call sites should use
+ * resolveLiveReserveEdgeAnchorPrice(manager, side), which prefers the live
+ * grid geometry and only falls back to this function.
+ *
+ * @param {Object} config - Bot configuration
+ * @param {string} side - 'buy' or 'sell'
+ * @returns {number|null} Finite anchor price, or null
+ */
+function resolveReserveEdgeAnchorPrice(config, side) {
+    const isSell = side === 'sell';
+    const bound = isSell ? config?.maxPrice : config?.minPrice;
+    const mode = isSell ? 'max' : 'min';
+    try {
+        const anchor = resolveConfiguredPriceBound(bound, Number.NaN, Number(config?.startPrice), mode);
+        if (Number.isFinite(anchor))
+            return anchor;
+    }
+    catch (e) { /* fall through to raw bound */ }
+    const raw = Number(bound);
+    return Number.isFinite(raw) ? raw : null;
+}
+/**
+ * Live-grid reserve edge anchor (single source for edge placement).
+ *
+ * The anchor must come from the geometry the bot is actually trading, never
+ * from a config value that can be a mode string ("pool"/"book"), a relative
+ * multiplier, or a stale bound. Tiers, strongest first:
+ *
+ *   1. Genesis ladder extreme — `_genesis.priceLevels` is the exact ladder the
+ *      loaded grid was built from: sorted ascending, index-aligned with
+ *      `slot-<idx>` (assertSlotPriceInvariant), refreshed by initializeGrid,
+ *      persisted with the grid, and unaffected by the raw-profile re-merge a
+ *      resync performs. Slot 0 is always on the buy rail and the last level
+ *      always on the sell rail, so the ladder extremes are the live rail
+ *      bounds.
+ *   2. Live in-rail extreme of the master grid — geometry-only rail
+ *      membership (resolveGapBand + isSlotInRail, the same predicate the
+ *      selectors use) for snapshots without a genesis.
+ *   3. Config bound (resolveReserveEdgeAnchorPrice) — the previous behavior,
+ *      kept as the last resolved tier.
+ *   4. null — callers keep the legacy rank-based selection.
+ *
+ * @param {Object} manager - OrderManager (needs _genesis, orders, boundary)
+ * @param {string} side - 'buy' or 'sell'
+ * @returns {number|null} Finite anchor price, or null
+ */
+function resolveLiveReserveEdgeAnchorPrice(manager, side) {
+    const isSell = side === 'sell';
+    // Tier 1 — the ladder the loaded grid was generated from.
+    const levels = manager?._genesis?.priceLevels;
+    if (Array.isArray(levels) && levels.length > 0) {
+        const extreme = Number(isSell ? levels[levels.length - 1] : levels[0]);
+        if (Number.isFinite(extreme) && extreme > 0)
+            return extreme;
+    }
+    // Tier 2 — live in-rail extreme of the master grid.
+    const sideType = isSell ? ORDER_TYPES.SELL : ORDER_TYPES.BUY;
+    if (manager?.orders && typeof manager.orders.values === 'function') {
+        let best = null;
+        try {
+            const band = MathUtils.resolveGapBand(manager);
+            for (const entry of manager.orders.values()) {
+                if (!entry || typeof entry !== 'object')
+                    continue;
+                if (!('type' in entry) || !('price' in entry))
+                    continue;
+                if (entry.type !== sideType)
+                    continue;
+                // Shelf/manual ids (e.g. fork-kept deep-* orders below the rail)
+                // are never rail geometry: isSlotInRail is fail-open for
+                // unparseable ids, so without this gate a cheap shelf order drags
+                // the anchor down to itself and then qualifies as the reserve edge
+                // (issue #27 follow-up). No-op upstream (grids only mint slot-N).
+                if (parseSlotIndex(entry?.id) === null)
+                    continue;
+                if (!MathUtils.isSlotInRail(band.boundaryIdx, band.gapSlots, sideType, entry))
+                    continue;
+                const price = Number(entry.price);
+                if (!Number.isFinite(price) || price <= 0)
+                    continue;
+                if (best === null || (isSell ? price > best : price < best))
+                    best = price;
+            }
+        }
+        catch (e) {
+            best = null;
+        }
+        if (best !== null)
+            return best;
+    }
+    // Tier 3 — configured/resolved bound.
+    return resolveReserveEdgeAnchorPrice(manager?.config, side);
+}
+/**
+ * Shared anchored edge comparator for reserve selection (single source).
+ * With a finite anchor: in-bound slots first, nearest the anchor first
+ * (floor ascending, ceiling descending); stale out-of-bound slots last,
+ * still nearest the anchor first. Without one: plain rank fallback
+ * (floor rank-lowest, ceiling rank-highest).
+ *
+ * @param {Object} a - Slot/order (needs price)
+ * @param {Object} b - Slot/order (needs price)
+ * @param {string} edge - 'floor' or 'ceiling'
+ * @param {number|null} anchorPrice - Resolved bound anchor (null = rank fallback)
+ * @returns {number} Comparator result for Array.prototype.sort
+ */
+function compareReserveEdge(a, b, edge, anchorPrice) {
+    const ceil = edge === 'ceiling';
+    // NB: Number(null) === 0 is finite — null/undefined must mean "no anchor".
+    const anchor = anchorPrice == null ? Number.NaN : Number(anchorPrice);
+    if (!Number.isFinite(anchor)) {
+        return ceil ? Number(b.price) - Number(a.price) : Number(a.price) - Number(b.price);
+    }
+    const pa = Number(a?.price);
+    const pb = Number(b?.price);
+    const aIn = ceil ? pa <= anchor : pa >= anchor;
+    const bIn = ceil ? pb <= anchor : pb >= anchor;
+    if (aIn !== bIn)
+        return aIn ? -1 : 1;
+    if (aIn)
+        return ceil ? pb - pa : pa - pb;
+    return ceil ? pa - pb : pb - pa;
+}
+/**
+ * Central edge selector: take reserve slots from a price-ascending list,
+ * skipping already-windowed ids. Both edges anchor at the live grid's own
+ * edge (resolveLiveReserveEdgeAnchorPrice) when finite — floor: nearest
+ * at/above the live floor first, slots below it rank last; ceiling: nearest
+ * at/below the live ceiling first, slots above it rank last. Anchoring to the
+ * live edge keeps the reserve on genuine live-rail slots when the grid still
+ * carries leftovers from an older bound or the configured bound disagrees
+ * with the geometry being traded. Callers pre-filter rail/type and apply
+ * their own size gates; this only picks positions. A null anchor degrades to
+ * plain rank (floor: lowest first; ceiling: highest first).
+ *
+ * @param {Array<Object>} sortedAsc - Slots sorted by price ascending
+ * @param {number} count - Reserve count
+ * @param {Set<string>|null} excludeIds - Windowed ids to skip
+ * @param {string} edge - 'floor' or 'ceiling'
+ * @param {number|null} [anchorPrice] - Live edge anchor for the side (null = rank-based)
+ * @returns {Array<Object>} Reserve slots (ascending for floor, descending for ceiling)
+ */
+function selectReserveEdgeSlots(sortedAsc, count, excludeIds, edge, anchorPrice = null) {
+    const n = Math.max(0, Math.floor(Number(count) || 0));
+    if (n <= 0 || !Array.isArray(sortedAsc))
+        return [];
+    const avail = sortedAsc.filter((s) => s && s.id != null && (!excludeIds || !excludeIds.has(s.id)));
+    // NB: Number(null) === 0 is finite — null/undefined must mean "no anchor".
+    const anchor = anchorPrice == null ? Number.NaN : Number(anchorPrice);
+    if (!Number.isFinite(anchor)) {
+        // No anchor: plain rank fallback (avail arrives ascending) —
+        // floor rank-lowest, ceiling rank-highest.
+        return edge === 'ceiling' ? avail.slice(-n).reverse() : avail.slice(0, n);
+    }
+    // Anchored: shared comparator — in-bound slots nearest the bound first,
+    // stale out-of-bound slots last.
+    return avail
+        .sort((x, y) => compareReserveEdge(x, y, edge, anchor))
+        .slice(0, n);
+}
 /**
  * Total target order count across both sides (used for BTS fee calculation).
  * Single source of truth so every budget derivation sizes identically.
+ * Includes per-side reserves: they rest live on-chain and pay creation fees.
  *
  * @param {Object} config - Bot configuration
  * @returns {number} Total target order count
  */
 function getActiveOrdersTotal(config) {
     return Math.max(0, config?.activeOrders?.buy ?? 1) +
-        Math.max(0, config?.activeOrders?.sell ?? 1);
+        Math.max(0, config?.activeOrders?.sell ?? 1) +
+        resolveReserveOrders(config);
 }
 /**
  * Calculate side budget after BTS fee deduction.
@@ -2035,7 +2685,7 @@ function collectKnownOnChainOrderIds(mgr, placedResults, placedContexts, extraCr
         }
     }
     // Existing chain ids referenced by non-create op contexts (cancel /
-    // rotation / size-update). Pre-existing orders whose absence is expected
+    // rotation / size-update) are already live: they belong to the master set
     // (cancels/fills in this batch), so they join the by-id set but never
     // the lagging-create guard.
     if (Array.isArray(placedContexts)) {
@@ -2058,6 +2708,6 @@ function collectKnownOnChainOrderIds(mgr, placedResults, placedContexts, extraCr
     const all = new Set([...masterIds, ...createIds]);
     return { masterIds: [...masterIds], createIds: [...createIds], all: [...all] };
 }
-// ================================================================================
-export { parseChainOrder, findMatchingGridOrderByOpenOrder, applyChainSizeToGridOrder, buildFillKey, correctOrderPriceOnChain, correctAllPriceMismatches, buildCreateOrderArgs, getOrderTypeFromUpdatedFlags, resolveConfiguredPriceBound, virtualizeOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, detectGapEvacuationCandidates, updateGapEvacuationStreaks, resolveSpreadOrderSide, chainOrderMatchesSlot, chainOrderMatchesSlotWithTolerance, crossingCandidateChainId, isCrossingCheckCandidate, buildCrossingCheckCandidates, parseSlotIndex, filterOrdersByType, buildOutsideInPairGroups, extractBatchOperationResults, formatUnmatchedChainOrder, isOrderOnChain, isOrderVirtual, hasOnChainId, isOrderPlaced, isPhantomOrder, isSlotAvailable, isEmptyGridSlot, isOrderHealthy, checkSizeThreshold, checkSizesBeforeMinimum, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, shouldFlagOutOfSpread, buildIndexes, validateIndexes, ordersEqual, buildDelta, getOrderSize, deriveTargetBoundary, isShiftEligibleFill, getActiveOrdersTotal, getSideBudget, calculateBudgetedSizes, buildCreateOpFingerprint, isOrderGoneErrorMessage, recordDuplicateOrphanDetection, clearDuplicateOrphanDetection, duplicateOrphanLogInfo, chainOrderUnchangedFromCache, detectCrossedBookPlan, collectKnownOnChainOrderIds };
+export { parseChainOrder, findMatchingGridOrderByOpenOrder, applyChainSizeToGridOrder, buildFillKey, correctOrderPriceOnChain, correctAllPriceMismatches, buildCreateOrderArgs, getOrderTypeFromUpdatedFlags, resolveConfiguredPriceBound, virtualizeOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, detectGapEvacuationCandidates, updateGapEvacuationStreaks, resolveSpreadOrderSide, chainOrderMatchesSlot, chainOrderMatchesSlotWithTolerance, crossingCandidateChainId, isCrossingCheckCandidate, buildCrossingCheckCandidates, parseSlotIndex, filterOrdersByType, buildOutsideInPairGroups, extractBatchOperationResults, formatUnmatchedChainOrder, isNonBlockingUnmatchedOrder, isOrderOnChain, isOrderVirtual, hasOnChainId, isOrderPlaced, isPhantomOrder, isSlotAvailable, isEmptyGridSlot, isOrderHealthy, checkSizeThreshold, checkSizesBeforeMinimum, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, shouldFlagOutOfSpread, buildIndexes, validateIndexes, ordersEqual, buildDelta, deriveTargetBoundary, isShiftEligibleFill, resolveReserveCount, resolveReserveOrders, selectReserveEdgeSlots, getActiveOrdersTotal, getSideBudget, calculateBudgetedSizes, buildCreateOpFingerprint, isOrderGoneErrorMessage, recordDuplicateOrphanDetection, clearDuplicateOrphanDetection, duplicateOrphanLogInfo, chainOrderUnchangedFromCache, detectCrossedBookPlan, collectKnownOnChainOrderIds, reserveEdgeIdSet, liveWindowIdSet };
+export { resolveReserveEdgeAnchorPrice, resolveLiveReserveEdgeAnchorPrice, compareReserveEdge, collectRefillSlotIds };
 //# sourceMappingURL=order.js.map