dexbot 1.6.1 → 1.6.2

package/dist/modules/dexbot_cow_runtime.js

@@ -76,7 +76,7 @@ import * as FormatModule from './order/format.js';
 const Format = FormatModule;
 import * as workingGridModule from './order/working_grid.js';
 const { WorkingGrid } = workingGridModule;
-import { getErrorMessage } from './utils/errors.js';
+import { getErrorMessage, resolveSeamMs, resolveSeamMsOrNull } from './utils/errors.js';
 // Maximum number of times the pre-broadcast staleness guard may re-plan the
 // batch from a fresh master before proceeding anyway. Bounded so a master
 // grid that keeps mutating (fill bursts, sync loops) can never livelock the
@@ -1286,11 +1286,11 @@ function formatPartialBroadcastSummary(err) {
     return `${broadcast ?? '?'}/${total ?? '?'} groups broadcast`;
 }
 /**
- * Execute a batch with retry-on-uncertain semantics, enforcing a per-broadcast
- * operation cap (MAX_OPS_PER_BROADCAST). When the batch carries more
- * operations than the cap, it is split into sequential broadcast chunks of at
- * most `maxOps` operations each, so a single on-chain transaction never holds
- * more than the configured number of order operations (the original "N fills
+ * Execute a batch with retry-on-uncertain semantics, enforcing a gap-slot
+ * per-broadcast operation cap (_getGapSlotBatchSize). When the batch carries
+ * more operations than the cap, it is split into sequential broadcast chunks
+ * of at most `maxOps` operations each, so a single on-chain transaction never
+ * holds more than gapSlots order operations (the original "N fills
  * per broadcast" intent, applied at the op level rather than the fill level).
  *
  * Failure isolation — no swallowed orders: if one chunk's broadcast is
@@ -1316,12 +1316,11 @@ function formatPartialBroadcastSummary(err) {
  * @returns {Promise<{result: Object, opContexts: Array}>}
  */
 async function executeChunkedWithRetryOnUncertain(bot, operations, opContexts) {
-    const configuredMax = typeof bot._getMaxOpsPerBroadcast === 'function'
+    const fromAccessor = typeof bot._getMaxOpsPerBroadcast === 'function'
         ? bot._getMaxOpsPerBroadcast()
-        : COW_PERFORMANCE?.MAX_OPS_PER_BROADCAST;
-    const maxOps = Number.isFinite(configuredMax) && configuredMax >= 1
-        ? Math.floor(configuredMax)
-        : 1;
+        : (typeof bot._getGapSlotBatchSize === 'function' ? bot._getGapSlotBatchSize() : undefined);
+    const requested = Number(fromAccessor);
+    const maxOps = Number.isFinite(requested) && requested >= 1 ? Math.floor(requested) : 1;
     if (!Array.isArray(operations) || operations.length <= maxOps) {
         return await executeWithRetryOnUncertain(bot, operations, opContexts);
     }
@@ -1332,7 +1331,7 @@ async function executeChunkedWithRetryOnUncertain(bot, operations, opContexts) {
             opContexts: opContexts.slice(i, i + maxOps),
         });
     }
-    bot.manager.logger.log(`[COW] Splitting ${operations.length} operations into ${chunks.length} broadcast chunk(s) of at most ${maxOps} ops each (MAX_OPS_PER_BROADCAST).`, 'info');
+    bot.manager.logger.log(`[COW] Splitting ${operations.length} operations into ${chunks.length} broadcast chunk(s) of at most ${maxOps} ops each (gap-slot batch size).`, 'info');
     const mergedOperationResults = [];
     const mergedRawResults = [];
     const mergedContexts = [];
@@ -1609,6 +1608,192 @@ function resolveIdealSizeForValidation(_bot, orderLike, fallbackSize = null) {
 function validateOrderSizeForExecution(bot, size, type, orderLike = null, fallbackSize = null) {
     return validateOrderSize(size, type, bot.manager.assets, bot.config.gridLimits?.MIN_ORDER_SIZE_FACTOR, resolveIdealSizeForValidation(bot, orderLike, fallbackSize), bot.config.gridLimits?.PARTIAL_DUST_THRESHOLD_PERCENTAGE);
 }
+function checkGridPriceInvariant(slotId, price, genesis) {
+    return orderUtils.checkGridPriceInvariant(slotId, price, genesis);
+}
+/**
+ * Derive the authoritative price for a rotation destination slot.
+ *
+ * A rotation re-prices to the destination slot, so the destination's genesis
+ * level is the authoritative price — not `action.newPrice`, which the planner
+ * copies from the destination hole's `order.price` and which is therefore only
+ * as sound as whatever last wrote that object. Deriving the emitted price here
+ * means a planner bug cannot produce a mis-priced UPDATE on its own; the
+ * invariant check remains as the backstop for the no-genesis case.
+ *
+ * @returns {number} the destination's genesis level, or NaN when there is no
+ *   genesis ladder / no parseable destination index (caller falls back to the
+ *   planned price, which is the migration case the checker fails open on).
+ */
+function deriveRotationPrice(bot, newGridId) {
+    try {
+        const idx = parseSlotIndex(newGridId);
+        if (idx === null || idx === undefined || !Number.isFinite(idx))
+            return NaN;
+        const genesis = bot?.manager?._genesis;
+        if (!Array.isArray(genesis?.priceLevels) || genesis.priceLevels.length === 0)
+            return NaN;
+        const lvl = Number(math.priceForSlot(idx, genesis));
+        return (Number.isFinite(lvl) && lvl > 0) ? lvl : NaN;
+    }
+    catch {
+        return NaN;
+    }
+}
+/**
+ * Record one GRID-PRICE-INVARIANT check for an emitted order price.
+ *
+ * BLOCKING: returns false when the price is a genuine off-grid mismatch, so the
+ * caller must SKIP the emission. A price that is not a slot's genesis level is
+ * not a valid grid price, so placing it is the failure this guard exists to
+ * prevent — rejecting is the point, not a side effect.
+ *
+ * Fails OPEN on anything unjudgeable (no genesis, unparseable id, non-finite
+ * price, checker error): those are metadata problems, not off-grid prices, and
+ * blocking on them would halt legitimate trading. Only 'off-grid-price' blocks.
+ *
+ * A missing slotId is counted as unchecked rather than falling back to another
+ * id: for a rotation UPDATE the id must be the DESTINATION slot (newPrice is
+ * that slot's price), so substituting the source would flag every legitimate
+ * relocation. Callers pass the id they actually mean, or nothing.
+ *
+ * @returns {boolean} true when the caller MAY emit; false when it must skip
+ */
+function recordGridPriceInvariantCheck(bot, slotId, price, stats, site) {
+    try {
+        if (slotId == null || slotId === '') {
+            stats.unchecked++;
+            return true;
+        }
+        const inv = checkGridPriceInvariant(slotId, price, bot?.manager?._genesis);
+        if (inv.reason !== 'ok' && inv.reason !== 'off-grid-price') {
+            stats.unchecked++;
+            return true;
+        }
+        stats.checked++;
+        if (inv.ok) {
+            // A CLEAN check clears the run for this slot: escalation must mean
+            // "rejected N consecutive batches", not "rejected N times ever".
+            // Without this reset a slot rejected once an hour would accumulate
+            // to the threshold over a day and fire a resync it never earned.
+            const streakMap = getInvariantRejectStreak(bot);
+            if (streakMap.has(String(slotId)))
+                streakMap.delete(String(slotId));
+            return true;
+        }
+        stats.violated++;
+        orderUtils.reportGridPriceInvariant(bot?.manager, slotId, price, site);
+        considerGridPriceInvariantEscalation(bot, slotId, price, inv, site);
+        return false;
+    }
+    catch {
+        // A checker failure must never block a broadcast.
+        return true;
+    }
+}
+/**
+ * Per-slot count of CONSECUTIVE batches that rejected this slot's emission as
+ * off-grid, scoped to the BOT rather than the module.
+ *
+ * Scope matters because the monolithic runtime (`dexbot.ts`, the `dexbot` bin)
+ * constructs EVERY active bot in one process, so a module-level map would pool
+ * unrelated bots' rejections: one bot rejecting a slot twice would leave the
+ * next bot at the threshold on its FIRST rejection and fire a spurious
+ * structural resync (reload, possibly a full grid reset) on a healthy bot.
+ * Keeping it on the bot also keeps the count from outliving the resync that
+ * repairs the slot, and lets tests start from a clean slate.
+ *
+ * @param {any} bot
+ * @returns {Map<string, number>}
+ */
+function getInvariantRejectStreak(bot) {
+    if (!(bot?._gridPriceInvariantRejectStreak instanceof Map)) {
+        bot._gridPriceInvariantRejectStreak = new Map();
+    }
+    return bot._gridPriceInvariantRejectStreak;
+}
+/**
+ * Escalate a PERSISTENT off-grid rejection to a structural resync.
+ *
+ * A single rejection is handled correctly by skipping the emission and warning;
+ * the next cycle re-plans. But if the corruption lives in-process (the planner
+ * carries `candidate.price` straight from `manager.orders`), the next cycle
+ * re-plans from the SAME bad `slot.price`, is rejected identically, and warns
+ * again -- forever. The slot is dead while the bot looks healthy.
+ *
+ * After `GRID_PRICE_INVARIANT_RESYNC_THRESHOLD` consecutive rejecting batches
+ * for one slot, ask for the structural resync that repairs it (loadGrid derives
+ * slot prices from the genesis ladder). Fire-and-forget: the resync is already
+ * debounced (`_structuralGridResyncRunning`/`Timer`) and batch-in-flight aware,
+ * so repeats inside the cooldown are cheap and safe.
+ *
+ * @returns {number} the slot's current consecutive-rejection streak
+ */
+function considerGridPriceInvariantEscalation(bot, slotId, price, inv, site) {
+    const key = String(slotId);
+    const streakMap = getInvariantRejectStreak(bot);
+    const streak = (streakMap.get(key) || 0) + 1;
+    streakMap.set(key, streak);
+    const threshold = Number(constantsModule.TIMING?.GRID_PRICE_INVARIANT_RESYNC_THRESHOLD) > 0
+        ? Number(constantsModule.TIMING.GRID_PRICE_INVARIANT_RESYNC_THRESHOLD)
+        : 3;
+    if (streak < threshold)
+        return streak;
+    if (typeof bot?.manager?.requestStructuralGridResync !== 'function') {
+        bot?.manager?.logger?.log?.(`[GRID-PRICE-INVARIANT] ${slotId} rejected ${streak}x consecutively but ` +
+            `requestStructuralGridResync is unavailable; slot stays unhealed until restart`, 'error');
+        return streak;
+    }
+    // Dedicated cooldown key (NOT BOUNDARY_HOLD_RESYNC_COOLDOWN_MS: the watchdogs
+    // must tune independently). Once per cooldown window is enough -- the streak
+    // keeps counting so a later window escalates again if still unhealed.
+    const cooldownMs = Number(constantsModule.TIMING?.GRID_PRICE_INVARIANT_RESYNC_COOLDOWN_MS) > 0
+        ? Number(constantsModule.TIMING.GRID_PRICE_INVARIANT_RESYNC_COOLDOWN_MS)
+        : 15 * 60 * 1000;
+    const now = Date.now();
+    const lastAt = Number(bot?._lastGridPriceInvariantResyncAt) || 0;
+    if (now - lastAt < cooldownMs)
+        return streak;
+    bot._lastGridPriceInvariantResyncAt = now;
+    const expected = inv?.expected != null ? Number(inv.expected) : NaN;
+    const actual = Number(price);
+    bot?.manager?.logger?.log?.(`[GRID-PRICE-INVARIANT] ${slotId} (${site}) rejected ${streak} consecutive batch(es) at ` +
+        `${Number.isFinite(actual) ? Format.formatPrice6(actual) : 'n/a'} ` +
+        `(genesis ${Number.isFinite(expected) ? Format.formatPrice6(expected) : 'n/a'}); ` +
+        `requesting structural resync to repair the slot`, 'error');
+    try {
+        const res = bot.manager.requestStructuralGridResync('grid-price-invariant-violation', {
+            slotId: String(slotId),
+            expected: Number.isFinite(expected) ? expected : null,
+            actual: Number.isFinite(actual) ? actual : null,
+            site,
+            streak,
+        });
+        res?.catch?.((err) => {
+            bot.manager?.logger?.log?.(`[GRID-PRICE-INVARIANT] Structural resync request failed: ${getErrorMessage(err)}`, 'error');
+        });
+    }
+    catch (err) {
+        bot.manager?.logger?.log?.(`[GRID-PRICE-INVARIANT] Structural resync request failed: ${getErrorMessage(err)}`, 'error');
+    }
+    return streak;
+}
+/**
+ * Emit the per-batch GRID-PRICE-INVARIANT summary. Quiet when the batch had no
+ * checkable emission; warn when any off-grid emission was REJECTED, else info.
+ * A rejected emission is logged per-site by reportGridPriceInvariant; this is
+ * the aggregate so a batch that silently placed fewer orders than planned is
+ * explained without reading every line.
+ */
+function logGridPriceInvariantSummary(bot, stats, site) {
+    try {
+        if (!stats || stats.checked === 0)
+            return;
+        bot?.manager?.logger?.log?.(`[GRID-PRICE-INVARIANT] site=${site} checked=${stats.checked} ` +
+            `violated=${stats.violated} unchecked=${stats.unchecked}`, stats.violated > 0 ? 'warn' : 'info');
+    }
+    catch { /* summary is best-effort */ }
+}
 /**
  * LAST-FILL-GUARD helper — pivot ± halfIncrement (replaces price-tolerance).
  *  last fill @x with increment i: BUY < x*(1 - i/2/100), SELL > x*(1 + i/2/100)
@@ -1756,6 +1941,14 @@ function refreshLastFillPivotFromQueue(bot) {
  * Resolve the grid increment percent for the LAST-FILL guard in one place so
  * every check site and the batch summary use (and print) the same value.
  * Falls back to the default 0.5 when unset/invalid.
+ *
+ * CALL CONTRACT: this takes the BOT (`{ manager }`), not the increment or the
+ * manager. The lookup order below is `bot.manager.config` first, which works
+ * only because `OrderManager` exposes its own `config`. Callers that pass a
+ * bare manager instead of a bot get the `bot.config` / DEFAULT_CONFIG
+ * fallbacks and silently lose the manager's tuning, so pass the bot.
+ * (The manager-first order is deliberate: the guard must use the same
+ * increment the grid was built with, not whatever the bot-level config holds.)
  * @param {import('./dexbot_class.js').DEXBot} bot
  * @returns {number} Positive increment percent
  */
@@ -2074,11 +2267,20 @@ function applyRotationTransitionsToWorkingGrid(bot, workingGrid, executedContext
  * CANCELs modify existing orders and cannot be reliably distinguished from
  * "not yet visible" state by simple polling.
  *
+ * @param {Object} [options]
+ * @param {number} [options.maxPollRetries] - Poll attempts before reconciliation fallback
+ * @param {number} [options.pollIntervalMs] - Delay between polls; tests pass 0
+ *   to skip the production 1.5s pacing without changing the poll semantics
  * @returns {{ allConfirmed: boolean, confirmed: Array, unconfirmed: Array }}
  */
 async function pollChainForConfirmation(bot, opContexts, options = {}) {
     const maxPollRetries = options.maxPollRetries || 4;
-    const pollIntervalMs = options.pollIntervalMs || 1500;
+    // Test seam (see updateOrdersOnChainBatchCOW): bot._testPollIntervalMs
+    // overrides the production pacing when set by the tests. An explicit 0 is
+    // honored; null/undefined falls through to the production 1.5s default.
+    const explicitPollMs = options.pollIntervalMs;
+    const seamMs = bot?._testPollIntervalMs;
+    const pollIntervalMs = resolveSeamMs(explicitPollMs, resolveSeamMs(seamMs, 1500));
     // Only CREATE operations can be confirmed by polling (they appear as new orders on chain)
     const createContexts = opContexts.filter((ctx) => ctx && ctx.kind === 'create' && ctx.finalInts && ctx.order);
     if (createContexts.length === 0) {
@@ -2300,7 +2502,7 @@ function restoreSkippedUpdateSlotsInWorkingGrid(bot, workingGrid, skippedSlotIds
  *   skipped as already-consistent); handled=false when the caller must proceed
  *   with the original plan.
  */
-async function replanStaleBatch(bot, cowResult, replanDepth, preBroadcastGuard) {
+async function replanStaleBatch(bot, cowResult, replanDepth, preBroadcastGuard, seamPollIntervalMs) {
     const canReplan = replanDepth < STALE_PLAN_REPLAN_LIMIT
         && Array.isArray(cowResult.fills) && cowResult.fills.length > 0;
     if (!canReplan) {
@@ -2356,7 +2558,11 @@ async function replanStaleBatch(bot, cowResult, replanDepth, preBroadcastGuard)
             return {
                 handled: true,
                 result: await updateOrdersOnChainBatchCOW(bot, replanned, {
-                    replanDepth: replanDepth + 1
+                    replanDepth: replanDepth + 1,
+                    // Carry the seam through the recursion explicitly: the inner
+                    // frame re-sets and re-restores it, so it must not depend on
+                    // the outer frame's side-channel value surviving.
+                    ...(seamPollIntervalMs != null ? { pollIntervalMs: seamPollIntervalMs } : {})
                 }),
             };
         }
@@ -2710,8 +2916,58 @@ async function runPreBroadcastGuards(bot, cowResult) {
     }
     return { proceed: true, crossingCandidates, intraBatchCandidates };
 }
+function restoreTestPollIntervalSeam(bot, prev) {
+    try {
+        if (prev === undefined)
+            delete bot._testPollIntervalMs;
+        else
+            bot._testPollIntervalMs = prev;
+    }
+    catch { /* seam restore must never break the batch */ }
+}
 async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
     const replanDepth = Number.isFinite(Number(options?.replanDepth)) ? Number(options.replanDepth) : 0;
+    // Test seam: options.pollIntervalMs overrides the production 1.5s pacing
+    // in pollChainForConfirmation (missing-create path below) so tests do
+    // not sleep on wall-clock time. Held on the bot only for the duration of
+    // this call (see the wrapper's finally) so the inner missing-create
+    // branch and any re-plan recursion pick it up without changing the
+    // production call signature used by the runtime.
+    const seamPollIntervalMs = resolveSeamMsOrNull(options?.pollIntervalMs);
+    const prevSeamPollIntervalMs = bot?._testPollIntervalMs;
+    if (seamPollIntervalMs != null) {
+        bot._testPollIntervalMs = seamPollIntervalMs;
+    }
+    // Expose the resolved interval using the same precedence the missing-create
+    // poll path applies (explicit option > bot seam > production 1500ms).
+    // Recorded in the wrapper rather than in pollChainForConfirmation so it is
+    // observable on every batch exit, including the pre-broadcast guard
+    // refusals that never reach the poll (a `||`-vs-`??` regression here is
+    // otherwise invisible: the only effect is a slower poll).
+    bot._lastResolvedPollIntervalMs = resolveSeamMs(seamPollIntervalMs, resolveSeamMs(bot?._testPollIntervalMs, 1500));
+    // The seam override must not survive this call: every exit path (dry run,
+    // entry/pre-broadcast single-flight aborts, guard refusals, re-plan
+    // recursion, throws) funnels through the body() finally below, so no exit
+    // can leak bot._testPollIntervalMs onto the bot.
+    try {
+        return await updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seamPollIntervalMs ?? undefined);
+    }
+    finally {
+        // Restore only when this frame actually wrote a seam. The entry
+        // single-flight await (inside body()) lets a second, seam-less batch
+        // run concurrently: an unguarded restore would delete the seam owned
+        // by an in-flight sibling call (captured prev === undefined), and that
+        // sibling's pollChainForConfirmation — which reads the bot field only,
+        // since it takes no pollIntervalMs option at its call sites — would
+        // silently fall back to the production 1500ms pacing. Guarding keeps
+        // the write-ownership scoped to this call; the saved prev still makes
+        // the nested re-plan recursion LIFO-correct.
+        if (seamPollIntervalMs != null) {
+            restoreTestPollIntervalSeam(bot, prevSeamPollIntervalMs);
+        }
+    }
+}
+async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seamPollIntervalMs) {
     bot._currentCycleId = (Number.isFinite(Number(bot._currentCycleId)) ? Number(bot._currentCycleId) : 0) + 1;
     const { workingGrid, workingIndexes, workingBoundary, actions } = cowResult;
     // Boundary-hold value: computed pre-broadcast after the skip-restore and
@@ -2798,7 +3054,11 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
     // Per-batch LAST-FILL-GUARD disposition counters. Per-action pass lines
     // would spam big batches, so the guard emits one batch summary instead
     // (see the summary after the action loop below).
-    const lastFillGuardStats = { checked: 0, passed: 0, skipped: 0, bypassed: 0 };
+    const lastFillGuardStats = { checked: 0, passed: 0, skipped: 0, bypassed: 0, pivotOffGrid: 0 };
+    // Per-batch GRID-PRICE-INVARIANT counters (BLOCKING). Tracks emitted prices
+    // that are not the genesis level for their slot — such emissions are
+    // rejected, not placed. One batch summary.
+    const gridPriceInvariantStats = { checked: 0, violated: 0, unchecked: 0 };
     // Whether any guard check in this batch refreshed the pivot from
     // still-queued fills — reported in the batch summary so a pivot change
     // that altered a guard decision is visible at info, not just debug.
@@ -2810,7 +3070,7 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
     const clampedUpdateSlotIds = new Set();
     // orderId -> operations index of its cancel op. A crossing re-pricing
     // update is only safe when the crossed order's cancel was already queued
-    // at an earlier position: ops broadcast in MAX_OPS_PER_BROADCAST chunks,
+    // at an earlier position: ops broadcast in gap-slot-sized chunks,
     // so an earlier index means the cancel confirms on chain (same or earlier
     // chunk, applied sequentially) before the crossing order lands.
     const cancelOpIndexByOrderId = new Map();
@@ -2890,13 +3150,21 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                     const priceDrift = Number.isFinite(plannedPrice) && Number.isFinite(livePrice)
                         ? Math.abs(livePrice - plannedPrice)
                         : 0;
-                    const effectiveOrder = (priceDrift > 0)
-                        ? { ...order, price: livePrice, size: order.size, type: order.type }
-                        : order;
+                    // The planned price is emitted as-is. A pre-broadcast
+                    // substitution with liveSlot.price used to rewrite it here
+                    // at `debug` level, which meant a slot whose price had been
+                    // mutated off its genesis level got re-broadcast under a
+                    // different number than the plan validated (crossing,
+                    // collision and last-fill guards all ran on `createPrice`).
+                    // slot.price is derived from the genesis ladder, not
+                    // authoritative, so a divergence is a signal to report —
+                    // never a value to adopt. Reported at `warn`: a divergence
+                    // here is a writer bug, not routine freshness.
+                    const effectiveOrder = order;
                     if (priceDrift > 0) {
-                        bot.manager.logger.log(`[COW] Pre-broadcast price freshness: slot ${order.id} ` +
-                            `drifted from planned=${plannedPrice} to live=${livePrice} ` +
-                            `(diff=${priceDrift}); rebuilding CREATE op with live price.`, 'debug');
+                        bot.manager.logger.log(`[COW] Pre-broadcast price drift on slot ${order.id}: ` +
+                            `planned=${plannedPrice} live=${livePrice} (diff=${priceDrift}); ` +
+                            `emitting planned price (live slot price is derived from genesis and is not authoritative).`, 'warn');
                     }
                     const createPrice = effectiveOrder.price;
                     const precision = order.type === ORDER_TYPES.SELL ? bot.manager.assets.assetA.precision : bot.manager.assets.assetB.precision;
@@ -2912,13 +3180,14 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                     }
                     // CROSSING-PLACEMENT GUARD (create variant): the batch-level
                     // validators (validateCreateTargetSlots, detectCrossedBookPlan)
-                    // simulated the PLANNED price, but the pre-broadcast price
-                    // freshness rebuild above can move the op's price. Re-check
-                    // crossing on the FINAL price against live and chain-side
-                    // orders not already cancelled at an earlier op position —
-                    // an opposite-side order cancelled in a later chunk would
-                    // otherwise coexist with this create mid-broadcast and
-                    // self-trade (production incident class).
+                    // simulated the PLANNED price. That is now the price emitted
+                    // (the pre-broadcast substitution was removed), but the guard
+                    // is retained as defence-in-depth: it re-checks on the FINAL
+                    // price against live and chain-side orders not already
+                    // cancelled at an earlier op position — an opposite-side
+                    // order cancelled in a later chunk would otherwise coexist
+                    // with this create mid-broadcast and self-trade (production
+                    // incident class).
                     const createCrossed = findCrossedOrder(crossingCandidates, createPrice, order.type, bot.manager.assets, (o) => orderUtils.isCrossingCheckCandidate(o, null, cancelOpIndexByOrderId));
                     const intraBatchCrossed = createCrossed ? null : findCrossedOrder(intraBatchCandidates, createPrice, order.type, bot.manager.assets);
                     const effectiveCrossed = createCrossed || intraBatchCrossed;
@@ -2959,6 +3228,16 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                     }
                     catch (_e) { /* guard is best-effort */ }
                     const args = buildCreateOrderArgs(effectiveOrder, assetA, assetB);
+                    // GRID-PRICE-INVARIANT (blocking): the CREATE price must be
+                    // the genesis level for this slot. A mismatch means state
+                    // corruption upstream, so the emission is skipped rather
+                    // than placed — the next reconcile cycle re-plans. See
+                    // docs/GRID_PRICE_INVARIANT.md.
+                    if (!recordGridPriceInvariantCheck(bot, order.id, createPrice, gridPriceInvariantStats, 'CREATE')) {
+                        if (order.id)
+                            skippedCreateSlotIds.add(order.id);
+                        continue;
+                    }
                     const buildResult = await chainOrders.buildCreateOrderOp(bot.account, args.amountToSell, args.sellAssetId, args.minToReceive, args.receiveAssetId, null);
                     if (!buildResult) {
                         bot.manager.logger.log(`Skipping create op for ${action.id}: amounts would round to 0 on blockchain`, 'warn');
@@ -2985,9 +3264,29 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                     if (action.newGridId && action.newGridId !== action.id) {
                         const masterOrder = bot.manager.orders.get(action.id);
                         const orderType = action.order?.type || masterOrder?.type;
-                        const newPrice = Number.isFinite(Number(action.newPrice))
+                        // ROTATION PRICE IS THE DESTINATION'S GENESIS LEVEL.
+                        //
+                        // A rotation re-prices to the destination slot, so the
+                        // destination's level is the authoritative price — not
+                        // action.newPrice, which the planner copies from
+                        // hole.order.price and which is therefore only as sound
+                        // as whatever wrote that object. Deriving it here means a
+                        // planner bug cannot produce a mis-priced UPDATE even if
+                        // the invariant check below were bypassed; the check
+                        // stays as the backstop that catches a missing genesis
+                        // ladder (where it fails open) rather than the only
+                        // thing standing between a bad plan and a live order.
+                        const derivedNewPrice = deriveRotationPrice(bot, action.newGridId);
+                        const plannedNewPrice = Number.isFinite(Number(action.newPrice))
                             ? Number(action.newPrice)
                             : Number(action.order?.price);
+                        let newPrice = Number.isFinite(derivedNewPrice) ? derivedNewPrice : plannedNewPrice;
+                        if (Number.isFinite(derivedNewPrice) && Number.isFinite(plannedNewPrice)
+                            && Math.abs(derivedNewPrice - plannedNewPrice) > Math.max(1e-12, Math.abs(derivedNewPrice) * 1e-9)) {
+                            bot.manager.logger.log(`[GRID-PRICE-INVARIANT] Rotation ${action.id} -> ${action.newGridId}: planned price ${Format.formatPrice6(plannedNewPrice)} ` +
+                                `differs from the destination's genesis level ${Format.formatPrice6(derivedNewPrice)} — ` +
+                                `emitting the genesis level`, 'warn');
+                        }
                         const newSize = plannedUpdateSize(action);
                         if (!masterOrder || !action.orderId || !orderType || !Number.isFinite(newPrice) || newSize <= 0) {
                             continue;
@@ -3194,6 +3493,20 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                         }
                         catch (_e) { /* best-effort */ }
                         const { amountToSell, minToReceive } = buildCreateOrderArgs({ type: orderType, size: newSize, price: newPrice }, assetA, assetB);
+                        // GRID-PRICE-INVARIANT (blocking): the emitted price
+                        // is action.newPrice, which every planner derives from the
+                        // object named by action.newGridId (verified: grid.ts:1867,
+                        // utils/system.ts:1195, validate.ts:600/746). Pass the
+                        // destination id only — no source fallback, so a missing id
+                        // counts as unchecked instead of checking the wrong slot.
+                        if (!recordGridPriceInvariantCheck(bot, action.newGridId, newPrice, gridPriceInvariantStats, 'UPDATE')) {
+                            skippedUpdateCount++;
+                            if (action.id)
+                                skippedUpdateSlotIds.add(action.id);
+                            if (action.newGridId)
+                                skippedUpdateSlotIds.add(action.newGridId);
+                            continue;
+                        }
                         const buildResult = await chainOrders.buildUpdateOrderOp(bot.account, action.orderId, { amountToSell, minToReceive, newPrice, orderType }, masterOrder.rawOnChain || null);
                         if (!buildResult) {
                             skippedUpdateCount++;
@@ -3261,10 +3574,14 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                             const priceDrift = Number.isFinite(plannedPrice) && Number.isFinite(livePrice)
                                 ? Math.abs(livePrice - plannedPrice)
                                 : 0;
-                            const fbPrice = (priceDrift > 0) ? livePrice : plannedPrice;
+                            const fbPrice = plannedPrice;
                             if (priceDrift > 0) {
+                                // Same rationale as the primary CREATE path: emit
+                                // the planned price and report the divergence
+                                // rather than adopting a derived live price.
                                 bot.manager.logger.log(`[COW] CREATE fallback price drift for ${action.id} -> ${targetSlotId}: ` +
-                                    `planned=${plannedPrice} live=${livePrice} (diff=${priceDrift})`, 'debug');
+                                    `planned=${plannedPrice} live=${livePrice} (diff=${priceDrift}); ` +
+                                    `emitting planned price.`, 'warn');
                             }
                             const sizeCheck = validateOrderSizeForExecution(bot, fbSize, fbType, fbOrder, fbSize);
                             if (!sizeCheck.isValid) {
@@ -3321,6 +3638,10 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                                 }
                                 catch (_fbGuardErr) { /* guard is best-effort */ }
                                 const fbArgs = buildCreateOrderArgs({ type: fbType, size: fbSize, price: fbPrice }, assetA, assetB);
+                                // GRID-PRICE-INVARIANT (blocking): fallback CREATE.
+                                if (!recordGridPriceInvariantCheck(bot, targetSlotId, fbPrice, gridPriceInvariantStats, 'CREATE-FALLBACK')) {
+                                    continue;
+                                }
                                 const fbResult = await chainOrders.buildCreateOrderOp(bot.account, fbArgs.amountToSell, fbArgs.sellAssetId, fbArgs.minToReceive, fbArgs.receiveAssetId, null);
                                 if (fbResult) {
                                     operations.push(fbResult.op);
@@ -3376,13 +3697,35 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                             ? `active+bypassed(${batchOrigin || 'unknown'})`
                             : 'active');
                 const pivotStr = cold ? 'none' : `${Format.formatPrice6(Number(sumPivotRaw))}(${sumType})`;
-                bot.manager.logger.log(`[LAST-FILL-GUARD] mode=${mode} pivot=${pivotStr} inc=${sumInc}% ` +
+                // Report when the pivot used for this batch was NOT a ladder
+                // level: that is the precondition for a pivoted ratchet, and
+                // the value alone does not reveal it.
+                const batchPivot = cold ? null : resolveOnGridPivot(bot.manager, sumPivotRaw);
+                const pivotGridStr = cold
+                    ? ''
+                    : (batchPivot && batchPivot.idx != null
+                        ? ` pivotSlot=${batchPivot.idx}${batchPivot.snapped ? '(snapped)' : ''}`
+                        : ' pivotOffGrid=true');
+                bot.manager.logger.log(`[LAST-FILL-GUARD] mode=${mode} pivot=${pivotStr}${pivotGridStr} inc=${sumInc}% ` +
                     `pivotRefreshed=${lastFillGuardPivotRefreshed} ` +
                     `checked=${lastFillGuardStats.checked} passed=${lastFillGuardStats.passed} ` +
-                    `skipped=${lastFillGuardStats.skipped} bypassed=${lastFillGuardStats.bypassed}`, cold ? 'warn' : 'info');
+                    `skipped=${lastFillGuardStats.skipped} bypassed=${lastFillGuardStats.bypassed}` +
+                    // Per-action off-ladder count. The batch-level
+                    // `pivotOffGrid=true` flag above only says the pivot was
+                    // off-grid; this says HOW MANY guarded probes judged a
+                    // placement against an unsnapped pivot, which is the
+                    // quantity that grows during the ratchet this guard
+                    // exists to catch. Omitted (not `0`) when never set, so
+                    // "no off-grid probes" stays distinguishable from
+                    // "counter unavailable".
+                    (Number(lastFillGuardStats.pivotOffGrid) > 0
+                        ? ` pivotOffGrid=${lastFillGuardStats.pivotOffGrid}`
+                        : ''), cold || (batchPivot && batchPivot.idx == null) ? 'warn' : 'info');
             }
         }
         catch { /* summary is best-effort */ }
+        // Batch-level GRID-PRICE-INVARIANT summary (rejected emissions).
+        logGridPriceInvariantSummary(bot, gridPriceInvariantStats, 'COW');
         if (skippedUpdateCount > 0) {
             restoreSkippedUpdateSlotsInWorkingGrid(bot, workingGrid, skippedUpdateSlotIds, skippedUpdateCount);
         }
@@ -3466,7 +3809,7 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
         });
         if (!preBroadcastGuard.canCommit) {
             // Bounded re-plan + proceed — policy documented on replanStaleBatch.
-            const replan = await replanStaleBatch(bot, cowResult, replanDepth, preBroadcastGuard);
+            const replan = await replanStaleBatch(bot, cowResult, replanDepth, preBroadcastGuard, seamPollIntervalMs);
             if (replan.handled) {
                 return replan.result;
             }
@@ -3997,6 +4340,68 @@ async function recoverRefusedCommit(bot, chainOrders, logPrefix, adoptOpts, cont
     await persistGridAndClearPendingBroadcasts(bot, logPrefix);
     return successReturn ?? { executed: false, hadRotation: false, commitRefused: true, ...extraReturn };
 }
+/**
+ * Resolve the LAST-FILL guard pivot to an ON-GRID price.
+ *
+ * The pivot was a raw fill price, and nothing validated it. That made it a
+ * ratchet input: any bad pivot (a corrupt fill price, an adopted off-grid
+ * order) shifted every subsequent threshold, so an off-market buy could read
+ * as legitimate. A price is only meaningful relative to the ladder it trades
+ * on, so the pivot is converted to its nearest slot index and back to that
+ * slot's genesis price: the result is by construction a real grid level and
+ * cannot drift off the ladder.
+ *
+ * Falls back to the raw price when genesis is unavailable (pre-genesis
+ * startup), so the guard degrades to its previous behaviour rather than
+ * silently disabling. Never throws.
+ *
+ * @param {any} manager
+ * @param {number|null|undefined} rawPrice
+ * @returns {{price: number|null, snapped: boolean, idx: number|null, nearestDrift: number|null}}
+ */
+function resolveOnGridPivot(manager, rawPrice) {
+    const price = Number(rawPrice);
+    if (!Number.isFinite(price) || price <= 0)
+        return { price: null, snapped: false, idx: null, nearestDrift: null };
+    try {
+        const genesis = manager?._genesis;
+        const levels = genesis?.priceLevels;
+        if (!Array.isArray(levels) || levels.length === 0)
+            return { price, snapped: false, idx: null, nearestDrift: null };
+        const idx = math.slotIndexForPrice(price, genesis);
+        if (!Number.isFinite(idx))
+            return { price, snapped: false, idx: null, nearestDrift: null };
+        // Only accept a genuine ladder level and only a nearest match. A price
+        // that is wildly off-ladder (an adopted orphan far outside the grid)
+        // must NOT be silently rewritten onto an edge slot -- that would make a
+        // bad pivot look like a legitimate grid fill. Leave it snapped=false and
+        // let the caller decide.
+        const candidate = Number(math.priceForSlot(idx, genesis));
+        if (!Number.isFinite(candidate) || candidate <= 0)
+            return { price, snapped: false, idx: null, nearestDrift: null };
+        // Reject a snap that moves the pivot by more than one increment: any
+        // in-grid fill is within half an increment of its slot price, so a
+        // larger move means the pivot itself is not a real fill price.
+        const drift = Math.abs(candidate - price) / price;
+        // resolveLastFillGuardIncrement takes a BOT-shaped argument and reads
+        // `bot.manager.config` first. resolveOnGridPivot only ever has the
+        // manager (no bot in scope), so wrap it to satisfy that contract.
+        // Passing the manager directly would silently skip its own tuning and
+        // fall through to DEFAULT_CONFIG, making the snap tolerance wrong for
+        // any grid not built on the default increment.
+        const increment = resolveLastFillGuardIncrement({ manager }) / 100;
+        const maxDrift = Number.isFinite(increment) && increment > 0 ? increment : 0.005;
+        // nearestDrift is reported even when the snap is refused, so a caller
+        // can tell a near-miss (rounding, one increment out) from a price that
+        // is nowhere near the ladder (a genuinely corrupt pivot).
+        if (drift > maxDrift)
+            return { price, snapped: false, idx: null, nearestDrift: drift };
+        return { price: candidate, snapped: drift > 0, idx, nearestDrift: drift };
+    }
+    catch {
+        return { price, snapped: false, idx: null, nearestDrift: null };
+    }
+}
 /**
  * Run the last-fill guard probe: optionally refresh the pivot from
  * still-queued fills, read the durable pivot, and evaluate
@@ -4027,7 +4432,38 @@ function runLastFillGuardCheck(bot, price, size, type, stats, skipRefresh = fals
     const lastPrice = bot.manager?._lastFilledPrice;
     const lastType = bot.manager?._lastFilledType;
     const inc = resolveLastFillGuardIncrement(bot);
-    const check = isLastFillGuardBlocked(price, size, type, lastPrice, lastType, inc);
+    // Validate the pivot onto the ladder before use (see resolveOnGridPivot).
+    // Reported once per probe at warn when the raw pivot was NOT a grid level:
+    // that is the ratchet precondition, and it is otherwise invisible because
+    // the pivot is only ever logged by value.
+    const onGrid = resolveOnGridPivot(bot.manager, lastPrice);
+    if (lastPrice != null && onGrid.idx == null && Number.isFinite(Number(lastPrice))) {
+        try {
+            // A persistently off-ladder pivot is exactly the corruption case, so
+            // this branch would otherwise warn once per guarded action per batch
+            // on top of the batch summary (which already reports pivotOffGrid).
+            // Warn once per distinct pivot value per batch: repeated identical
+            // pivots are the same condition, and a CHANGED pivot still warns.
+            const warnedKey = `lastFillPivotWarned:${bot?._currentCycleId ?? 'na'}`;
+            const alreadyWarned = bot[warnedKey];
+            if (alreadyWarned !== Number(lastPrice)) {
+                bot[warnedKey] = Number(lastPrice);
+                // Distinguish "close to a level but too far to snap" from "nowhere
+                // near the ladder". The former is a rounding/drift artifact; the
+                // latter means the pivot itself is not a real fill price.
+                const far = onGrid.nearestDrift == null || onGrid.nearestDrift > 0.02;
+                const kind = far ? 'off-ladder' : 'near-ladder'
+                    + (onGrid.nearestDrift != null ? ` (${(onGrid.nearestDrift * 100).toFixed(4)}% from the nearest level)` : '');
+                bot.manager?.logger?.log?.(`[LAST-FILL-GUARD] Pivot ${Format.formatPrice6(Number(lastPrice))} is not a grid level ` +
+                    `(${kind}); using raw value. A non-grid pivot can ` +
+                    `misjudge which placements are off-market. ` +
+                    `(reported once per batch per pivot value)`, 'warn');
+            }
+        }
+        catch { /* logging is best-effort */ }
+        stats.pivotOffGrid = (stats.pivotOffGrid || 0) + 1;
+    }
+    const check = isLastFillGuardBlocked(price, size, type, onGrid.price, lastType, inc);
     stats.checked++;
     return { check, refreshed };
 }
@@ -4273,7 +4709,7 @@ async function processBatchResults(bot, result, opContexts) {
         updateOperationCount
     };
 }
-export { isLastFillGuardBlocked, refreshLastFillPivotFromQueue, buildOutsideInPairGroupsForOrders, buildOutsideInPairGroupsForCreateEntries, extractOperationResults, findMissingCreateResultContexts, markMissingCreateResultsAsStructuralBlocker, formatUnmatchedChainOrderForLog, recordPendingBroadcast, clearPendingBroadcasts, clearPendingBroadcastsForSlots, popPushedWorkingGrid, buildChainOrderFingerprint, normalizeChainOrderForPendingMatch, findChainOrderForSlot, reconcileAfterUncertainBroadcast, reconcileAfterUncertainBroadcastImpl, autoCancelOneUnmatchedOrphan, shouldExecuteCreatePairMode, executeWithRetryOnUncertain, executeChunkedWithRetryOnUncertain, formatPartialBroadcastSummary, executeOperationsWithStrategy, validateOperationFunds, resolveIdealSizeForValidation, validateOrderSizeForExecution, buildActionsFromPlan, buildCowResultFromPlan, restoreSkippedUpdateSlotsInWorkingGrid, applyRotationTransitionsToWorkingGrid, pollChainForConfirmation, updateOrdersOnChainBatchCOW, processBatchResults, adoptPlacedBatchFromChain, resolveRefillBoundaryHold, toRefillSlotIdSet, trackBoundaryHold };
+export { isLastFillGuardBlocked, resolveOnGridPivot, checkGridPriceInvariant, deriveRotationPrice, refreshLastFillPivotFromQueue, buildOutsideInPairGroupsForOrders, buildOutsideInPairGroupsForCreateEntries, extractOperationResults, findMissingCreateResultContexts, markMissingCreateResultsAsStructuralBlocker, formatUnmatchedChainOrderForLog, recordPendingBroadcast, clearPendingBroadcasts, clearPendingBroadcastsForSlots, popPushedWorkingGrid, buildChainOrderFingerprint, normalizeChainOrderForPendingMatch, findChainOrderForSlot, reconcileAfterUncertainBroadcast, reconcileAfterUncertainBroadcastImpl, autoCancelOneUnmatchedOrphan, shouldExecuteCreatePairMode, executeWithRetryOnUncertain, executeChunkedWithRetryOnUncertain, formatPartialBroadcastSummary, executeOperationsWithStrategy, validateOperationFunds, resolveIdealSizeForValidation, validateOrderSizeForExecution, buildActionsFromPlan, buildCowResultFromPlan, restoreSkippedUpdateSlotsInWorkingGrid, applyRotationTransitionsToWorkingGrid, pollChainForConfirmation, updateOrdersOnChainBatchCOW, processBatchResults, adoptPlacedBatchFromChain, resolveRefillBoundaryHold, toRefillSlotIdSet, trackBoundaryHold };
 // Exported for regression tests (issue #23 sibling): the uncertain-broadcast
 // discard path must never drop a placement silently when master lost the slot.
 export { restoreDiscardedCreates };