dexbot 1.6.18 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +117 -5
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_dynamic_weight.js +2 -1
  9. package/dist/analysis/analyze_kalman.js +3 -2
  10. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  11. package/dist/analysis/analyze_liquidity.js +336 -0
  12. package/dist/analysis/analyze_regime.js +3 -2
  13. package/dist/analysis/analyze_regime_windows.js +3 -2
  14. package/dist/analysis/analyze_volatility.js +3 -2
  15. package/dist/analysis/bot_key_utils.d.ts +44 -1
  16. package/dist/analysis/bot_key_utils.js +76 -7
  17. package/dist/analysis/fills_cache.js +2 -1
  18. package/dist/analysis/grid_correction_check.d.ts +1 -19
  19. package/dist/analysis/grid_correction_check.js +12 -30
  20. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  21. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  22. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.js +693 -0
  24. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +166 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.js +258 -0
  26. package/dist/analysis/liquidity/liquidity_view.d.ts +53 -0
  27. package/dist/analysis/liquidity/liquidity_view.js +66 -0
  28. package/dist/analysis/resolve_bot_accounts.js +7 -6
  29. package/dist/analysis/trade_profitability.js +4 -2
  30. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  31. package/dist/credential-daemon.js +13 -2
  32. package/dist/dexbot.js +77 -172
  33. package/dist/modules/account_bots.d.ts +11 -1
  34. package/dist/modules/account_orders.d.ts +12 -0
  35. package/dist/modules/account_orders.js +30 -0
  36. package/dist/modules/asset_lookup.d.ts +25 -0
  37. package/dist/modules/asset_lookup.js +75 -0
  38. package/dist/modules/bitshares-native/transport.js +24 -6
  39. package/dist/modules/bitshares_client.d.ts +24 -6
  40. package/dist/modules/bitshares_client.js +44 -7
  41. package/dist/modules/bot_settings.d.ts +2 -0
  42. package/dist/modules/chain_scan.d.ts +64 -0
  43. package/dist/modules/chain_scan.js +80 -0
  44. package/dist/modules/cli_colors.d.ts +5 -0
  45. package/dist/modules/cli_colors.js +7 -0
  46. package/dist/modules/cli_progress.d.ts +51 -0
  47. package/dist/modules/cli_progress.js +113 -0
  48. package/dist/modules/constants.d.ts +26 -3
  49. package/dist/modules/constants.js +63 -8
  50. package/dist/modules/dexbot_class.d.ts +1 -6
  51. package/dist/modules/dexbot_class.js +14 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
  53. package/dist/modules/dexbot_cow_runtime.js +634 -136
  54. package/dist/modules/dexbot_fill_runtime.js +132 -23
  55. package/dist/modules/dexbot_maintenance_runtime.js +242 -74
  56. package/dist/modules/dexbot_startup_runtime.js +32 -20
  57. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  58. package/dist/modules/dexbot_state_recovery.js +167 -5
  59. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  60. package/dist/modules/launcher/runtime_entry.js +36 -1
  61. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  62. package/dist/modules/liquidity_pool_ref.js +116 -0
  63. package/dist/modules/node_connect_policy.d.ts +8 -1
  64. package/dist/modules/node_connect_policy.js +18 -2
  65. package/dist/modules/node_flap_score.d.ts +87 -0
  66. package/dist/modules/node_flap_score.js +124 -0
  67. package/dist/modules/node_health_cache.d.ts +40 -3
  68. package/dist/modules/node_health_cache.js +66 -20
  69. package/dist/modules/node_manager.d.ts +101 -19
  70. package/dist/modules/node_manager.js +255 -65
  71. package/dist/modules/order/accounting.js +56 -7
  72. package/dist/modules/order/format.d.ts +24 -10
  73. package/dist/modules/order/format.js +30 -10
  74. package/dist/modules/order/grid.js +91 -13
  75. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  76. package/dist/modules/order/grid_reconcile.js +333 -189
  77. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  78. package/dist/modules/order/grid_reconcile_internal.js +298 -100
  79. package/dist/modules/order/index.d.ts +19 -1
  80. package/dist/modules/order/lifecycle.d.ts +353 -0
  81. package/dist/modules/order/lifecycle.js +1109 -0
  82. package/dist/modules/order/manager.d.ts +273 -5
  83. package/dist/modules/order/manager.js +654 -48
  84. package/dist/modules/order/placement_lock.d.ts +102 -0
  85. package/dist/modules/order/placement_lock.js +222 -0
  86. package/dist/modules/order/strategy.js +13 -1
  87. package/dist/modules/order/sync_engine.d.ts +33 -1
  88. package/dist/modules/order/sync_engine.js +241 -73
  89. package/dist/modules/order/utils/math.d.ts +39 -1
  90. package/dist/modules/order/utils/math.js +83 -1
  91. package/dist/modules/order/utils/order.d.ts +181 -5
  92. package/dist/modules/order/utils/order.js +455 -9
  93. package/dist/modules/order/utils/system.d.ts +81 -1
  94. package/dist/modules/order/utils/system.js +331 -44
  95. package/dist/modules/order/utils/validate.d.ts +7 -1
  96. package/dist/modules/order/utils/validate.js +80 -3
  97. package/dist/modules/outcome.d.ts +54 -0
  98. package/dist/modules/outcome.js +51 -0
  99. package/dist/modules/settings_merge.d.ts +4 -0
  100. package/dist/modules/settings_merge.js +9 -0
  101. package/dist/modules/timing_policy.d.ts +82 -0
  102. package/dist/modules/timing_policy.js +244 -0
  103. package/dist/modules/types.d.ts +137 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  105. package/dist/modules/utils/asset_symbols.js +21 -2
  106. package/dist/scripts/analysis_runner.d.ts +10 -0
  107. package/dist/scripts/analysis_runner.js +33 -0
  108. package/dist/scripts/analyze-credit.js +54 -17
  109. package/dist/scripts/analyze-orders.d.ts +4 -2
  110. package/dist/scripts/analyze-orders.js +115 -35
  111. package/dist/scripts/asset.d.ts +26 -0
  112. package/dist/scripts/asset.js +165 -0
  113. package/dist/scripts/bts_distribution.d.ts +1 -0
  114. package/dist/scripts/bts_distribution.js +194 -142
  115. package/dist/scripts/chart_command.d.ts +1 -1
  116. package/dist/scripts/chart_command.js +60 -86
  117. package/dist/scripts/chart_targets.d.ts +18 -0
  118. package/dist/scripts/chart_targets.js +48 -0
  119. package/dist/scripts/dw.js +1 -1
  120. package/dist/scripts/liquid.d.ts +24 -0
  121. package/dist/scripts/liquid.js +134 -0
  122. package/dist/scripts/rich_list.js +12 -16
  123. package/dist/scripts/test-credit-renewal.js +12 -5
  124. package/dist/scripts/token_distribution.d.ts +2 -0
  125. package/dist/scripts/token_distribution.js +132 -108
  126. package/dist/scripts/tv.js +1 -1
  127. package/dist/scripts/verify-browser-bundle.js +18 -0
  128. package/docs/COW_INVARIANTS.md +69 -10
  129. package/docs/DEXBOT_COMPARISON.md +6 -6
  130. package/docs/EVOLUTION.md +10 -8
  131. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  132. package/docs/GRID_PRICE_INVARIANT.md +5 -2
  133. package/docs/GRID_RECONCILE.md +36 -11
  134. package/docs/LOGGING.md +50 -4
  135. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +177 -27
  136. package/docs/README.md +23 -2
  137. package/docs/WORKFLOW.md +12 -4
  138. package/docs/architecture.md +42 -5
  139. package/docs/developer_guide.md +25 -8
  140. package/modules/README.md +8 -1
  141. package/package.json +3 -1
  142. package/scripts/README.md +39 -7
  143. package/scripts/pdev.sh +14 -1
  144. package/scripts/pmain.sh +23 -8
  145. package/scripts/ptest.sh +7 -0
  146. package/tests/README.md +30 -1
@@ -8,7 +8,8 @@ const require = createRequire(import.meta.url);
8
8
  import { lazyShim } from './lazy_shim.js';
9
9
  import fs from 'node:fs';
10
10
  import { spawn } from 'node:child_process';
11
- import { nowIso, fireStructuralResync, resolveLastFillGuardReference } from './order/utils/system.js';
11
+ import { nowIso, fireStructuralResync, resolveLastFillGuardReference, hasUnsettledFills } from './order/utils/system.js';
12
+ import { withPlacement } from './order/placement_lock.js';
12
13
  import { path } from './path_api.js';
13
14
  import * as chainOrders from './chain_orders.js';
14
15
  import * as grid from './order/grid.js';
@@ -29,6 +30,11 @@ import { BroadcastUncertainError } from './dexbot_credential_client.js';
29
30
  import * as configModule from './config.js';
30
31
  const { Config } = configModule;
31
32
  import { getErrorMessage } from './utils/errors.js';
33
+ /**
34
+ * Gap-evac stranding sweep (lazy import: the recovery module pulls the
35
+ * bitshares client into the graph, which this runtime loads on demand already).
36
+ */
37
+ const scheduleGapEvacRepair = lazyShim('./dexbot_state_recovery', 'scheduleGapEvacRepair');
32
38
  import { isSameBotName } from './utils/sanitize_key.js';
33
39
  import { usesAmaGridPrice } from './grid_price_source.js';
34
40
  const hasOpenOrdersSyncLoopMsSet = lazyShim('./config', 'hasOpenOrdersSyncLoopMsSet');
@@ -42,6 +48,7 @@ const applyGridDivergenceCorrections = lazyShim('./order/utils/system', 'applyGr
42
48
  const updateGridFromBlockchainSnapshot = lazyShim('./order/grid', 'updateGridFromBlockchainSnapshot');
43
49
  const loadAmaCenterSnapshot = lazyShim('./order/utils/system', 'loadAmaCenterSnapshot');
44
50
  const sleep = lazyShim('./order/utils/system', 'sleep');
51
+ const getPipelineInFlightAgeMs = lazyShim('./order/utils/system', 'getPipelineInFlightAgeMs');
45
52
  const parseJsonWithComments = lazyShim('./order/utils/system', 'parseJsonWithComments');
46
53
  const isPm2Runtime = lazyShim('./order/logger', 'isPm2Runtime');
47
54
  const isWrapperAdapterOwner = lazyShim('./launcher/adapter_requirement', 'isWrapperAdapterOwner');
@@ -70,6 +77,7 @@ const isStrandedHoldOrder = lazyShim('./order/utils/order', 'isStrandedHoldOrder
70
77
  const getSideBudget = lazyShim('./order/utils/order', 'getSideBudget');
71
78
  function getCoreOrdersTotal(config) { return require('./order/utils/order').getCoreOrdersTotal(config); }
72
79
  const correctAllPriceMismatches = lazyShim('./order/utils/order', 'correctAllPriceMismatches');
80
+ const getLivePendingBroadcasts = lazyShim('./order/utils/order', 'getLivePendingBroadcasts');
73
81
  const isOrderOnChain = lazyShim('./order/utils/order', 'isOrderOnChain');
74
82
  const parseChainOrder = lazyShim('./order/utils/order', 'parseChainOrder');
75
83
  const parseSlotIndex = lazyShim('./order/utils/slot', 'parseSlotIndex');
@@ -734,6 +742,21 @@ async function maybeRunTargetedDriftReconciliation(bot, context) {
734
742
  const trigger = getTargetedSyncReason(bot);
735
743
  if (!trigger)
736
744
  return false;
745
+ // UNSETTLED-FILL GATE: a startup-style reconcile derives its window from the
746
+ // master grid. While fills are still queued / draining / in flight / owed a
747
+ // crawl, that master still holds the filled slots as ACTIVE and the boundary
748
+ // has not crawled — the top-up would restore the EXPENSIVE end of the rail
749
+ // (live incident: 8 BUYs at 1282.78 -> 1310.04 re-created from a stale
750
+ // "buy 12/20" shortfall and filled within seconds). Defer to the next tick:
751
+ // the crawl commits in the same fill cycle, after which the same shortfall
752
+ // resolves against the crawled rail. No cooldown stamp, so the retry is
753
+ // immediate once the fills settle.
754
+ const unsettled = hasUnsettledFills(bot);
755
+ if (unsettled.unsettled) {
756
+ bot._log(`[TARGETED-SYNC] Deferring ${context} reconciliation: ${unsettled.reason} — ` +
757
+ `the rail must absorb the fills before it is topped up`, 'debug');
758
+ return false;
759
+ }
737
760
  const now = Date.now();
738
761
  const cooldownMs = Number.isFinite(Number(bot._targetedDriftSyncCooldownMs))
739
762
  ? Number(bot._targetedDriftSyncCooldownMs)
@@ -1300,6 +1323,10 @@ function performGridResync(bot, options = {}) {
1300
1323
  return Promise.resolve(false);
1301
1324
  }
1302
1325
  self.manager.startBootstrap();
1326
+ // Set BEFORE the async work so a fill-driven COW that starts while the
1327
+ // resync reloads config/re-derives the centre already sees the rebuild and
1328
+ // defers. recalculateGrid adds a second (balanced) level for its own body.
1329
+ self.manager.beginStructuralRebuild?.('trigger-file resync');
1303
1330
  self._log('Grid regeneration triggered. Performing full grid resync...');
1304
1331
  return (async () => {
1305
1332
  try {
@@ -1421,6 +1448,7 @@ function performGridResync(bot, options = {}) {
1421
1448
  }
1422
1449
  finally {
1423
1450
  self.manager.finishBootstrap();
1451
+ self.manager.endStructuralRebuild?.();
1424
1452
  }
1425
1453
  return success;
1426
1454
  })();
@@ -2250,6 +2278,77 @@ function scheduleDeferredGridResync(ctx, options = {}) {
2250
2278
  });
2251
2279
  }, delayMs);
2252
2280
  }
2281
+ /**
2282
+ * Raise/lower the recovery-sync in-flight counter as a pair that also
2283
+ * maintains `_recoverySyncInFlightStartedAt`. The leak watchdog keys off the
2284
+ * timestamp: incrementing without it makes the watchdog skip the window (or
2285
+ * use a stale timestamp and force-clear a live recovery).
2286
+ * @param {import('./dexbot_class.js').DEXBot} bot
2287
+ */
2288
+ function raiseRecoveryInFlight(bot) {
2289
+ bot._recoverySyncInFlight = (bot._recoverySyncInFlight || 0) + 1;
2290
+ bot._recoverySyncInFlightStartedAt = Date.now();
2291
+ }
2292
+ /** @param {import('./dexbot_class.js').DEXBot} bot */
2293
+ function lowerRecoveryInFlight(bot) {
2294
+ bot._recoverySyncInFlight = Math.max(0, (bot._recoverySyncInFlight || 0) - 1);
2295
+ if ((bot._recoverySyncInFlight || 0) === 0) {
2296
+ bot._recoverySyncInFlightStartedAt = 0;
2297
+ drainFillQueueAfterPipelineClear(bot);
2298
+ }
2299
+ }
2300
+ /**
2301
+ * Leak watchdog for the bot-level pipeline counters. A missed decrement parks
2302
+ * the fill queue indefinitely; there is no stale-clear equivalent for
2303
+ * _batchInFlight / _recoverySyncInFlight. Surface the age every tick, and only
2304
+ * force-clear when nothing actually holds the placement region (a live batch
2305
+ * owns it, so resetting there would allow a second concurrent broadcast).
2306
+ * @param {import('./dexbot_class.js').DEXBot} bot
2307
+ */
2308
+ function checkPipelineInFlightWatchdogs(bot) {
2309
+ const now = Date.now();
2310
+ const placementHeld = typeof bot.manager?.isPlacementActive === 'function'
2311
+ && bot.manager.isPlacementActive() === true;
2312
+ const checks = [
2313
+ {
2314
+ countKey: '_batchInFlight',
2315
+ startedKey: '_batchInFlightStartedAt',
2316
+ label: 'batch',
2317
+ staleMs: Number(TIMING.BATCH_INFLIGHT_STALE_MS) > 0 ? Number(TIMING.BATCH_INFLIGHT_STALE_MS) : 10 * 60 * 1000,
2318
+ },
2319
+ {
2320
+ countKey: '_recoverySyncInFlight',
2321
+ startedKey: '_recoverySyncInFlightStartedAt',
2322
+ label: 'recovery sync',
2323
+ staleMs: Number(TIMING.RECOVERY_INFLIGHT_STALE_MS) > 0 ? Number(TIMING.RECOVERY_INFLIGHT_STALE_MS) : 10 * 60 * 1000,
2324
+ },
2325
+ ];
2326
+ const botAny = bot;
2327
+ for (const check of checks) {
2328
+ const count = Number(botAny[check.countKey]) || 0;
2329
+ if (count <= 0)
2330
+ continue;
2331
+ const startedAt = Number(botAny[check.startedKey]) || 0;
2332
+ if (!startedAt)
2333
+ continue;
2334
+ const ageMs = now - startedAt;
2335
+ if (ageMs < check.staleMs)
2336
+ continue;
2337
+ if (placementHeld) {
2338
+ bot._warn(`[WATCHDOG] ${check.label} counter (${count}) has been in flight for ${Math.round(ageMs / 1000)}s ` +
2339
+ `but the placement region is still held by ${bot.manager.placementKind?.() || 'unknown'}; not force-clearing`);
2340
+ continue;
2341
+ }
2342
+ bot._warn(`[WATCHDOG] Force-clearing leaked ${check.label} counter (${count}) after ${Math.round(ageMs / 1000)}s ` +
2343
+ `with no placement holder; the pipeline must not stay parked`);
2344
+ botAny[check.countKey] = 0;
2345
+ botAny[check.startedKey] = 0;
2346
+ // Wake the fill consumer: the deferred branch gates on this counter
2347
+ // without rescheduling, so a force-clear that does not drain would
2348
+ // leave the queue parked until an unrelated event.
2349
+ drainFillQueueAfterPipelineClear(bot);
2350
+ }
2351
+ }
2253
2352
  /**
2254
2353
  * Execute the core maintenance logic: recalculate funds, check pipeline,
2255
2354
  * refresh dynamic weights, check grid health, cancel dust orders,
@@ -2262,10 +2361,21 @@ async function executeMaintenanceLogic(bot, context) {
2262
2361
  // Surface any over-long _gridLock hold first — observational only, and it
2263
2362
  // must run even when the rest of the tick defers on a broadcast region.
2264
2363
  checkGridLockHoldDuration(bot);
2265
- // Clear stale broadcast flag first so any downstream gating on
2266
- // isBroadcastingActive() (e.g. recalculateFunds, BTS balance check)
2267
- // sees the freshest state rather than a hung flag.
2364
+ // Placement leak watchdog first: it is the authoritative mutex and the one
2365
+ // authority that may tear a hung region down (it also drops that region's
2366
+ // stale broadcast refcount atomically). A live pipeline counter younger than
2367
+ // the bound keeps the region alive, so a slow create-group reconcile is not
2368
+ // cut out from under its own leases.
2369
+ try {
2370
+ bot.manager?._clearStalePlacementRegion?.(undefined, {
2371
+ batchInFlightMs: getPipelineInFlightAgeMs(bot),
2372
+ });
2373
+ }
2374
+ catch { /* observational */ }
2375
+ // Broadcast-flag watchdog: it refuses to act while a placement lease is
2376
+ // held, so it only clears regions that never took the exclusive region.
2268
2377
  bot.manager._clearStaleBroadcastFlag();
2378
+ checkPipelineInFlightWatchdogs(bot);
2269
2379
  await bot.manager.recalculateFunds();
2270
2380
  await checkBtsBalanceAndAcquire(bot);
2271
2381
  bot.manager.clearStalePipelineOperations();
@@ -2311,9 +2421,19 @@ async function executeMaintenanceLogic(bot, context) {
2311
2421
  // with batch broadcasts — transient mismatches are expected during a COW cycle.
2312
2422
  // Also skip while a structural recovery reload is in flight (it runs without
2313
2423
  // the fill lock, so this check must gate on the recovery flag explicitly).
2424
+ // Liveness count from the single authority; a test double that does not
2425
+ // model it falls back to the raw map size (a COUNT only — never a second
2426
+ // TTL policy), so a partial mock cannot make the gate throw.
2427
+ let pendingBroadcastCount = 0;
2428
+ try {
2429
+ pendingBroadcastCount = Number(getLivePendingBroadcasts(bot.manager)?.length) || 0;
2430
+ }
2431
+ catch {
2432
+ pendingBroadcastCount = Number(bot.manager?._pendingBroadcasts?.size) || 0;
2433
+ }
2314
2434
  if (!bot._recoverySyncInFlight &&
2315
2435
  !bot._batchInFlight &&
2316
- !(bot.manager?._pendingBroadcasts?.size > 0) &&
2436
+ pendingBroadcastCount === 0 &&
2317
2437
  (bot._lightweightSyncCheckAt == null || Date.now() - bot._lightweightSyncCheckAt >= TIMING.LIGHTWEIGHT_SYNC_CHECK_INTERVAL_MS)) {
2318
2438
  bot._lightweightSyncCheckAt = Date.now();
2319
2439
  try {
@@ -2353,6 +2473,22 @@ async function executeMaintenanceLogic(bot, context) {
2353
2473
  bot._log(`[LIGHTWEIGHT-SYNC] Check failed: ${getErrorMessage(e)}`, 'debug');
2354
2474
  }
2355
2475
  }
2476
+ // GAP-EVAC stranding sweep: a boundary commit that moved away from a live
2477
+ // order strands it inside the spread band, and plans are fill-driven — so a
2478
+ // quiet market never heals it (the band keeps live orders and the real
2479
+ // spread stays collapsed). The sweep re-derives the streak ledger against
2480
+ // the COMMITTED geometry, queues the cancel-only teeth for anything past
2481
+ // the threshold, and schedules a fill-less re-plan (the preferred repair:
2482
+ // one in-place price update). It early-returns on a healthy band, so it is
2483
+ // cheap enough to run every tick, and it also covers commits made by paths
2484
+ // that hold no bot reference (divergence/sync) plus a restart that loads an
2485
+ // already-stranded snapshot.
2486
+ try {
2487
+ scheduleGapEvacRepair(bot, `maintenance ${context}`);
2488
+ }
2489
+ catch (gapEvacErr) {
2490
+ bot._log(`[GAP-EVAC] Stranding sweep failed (non-fatal): ${getErrorMessage(gapEvacErr)}`, 'debug');
2491
+ }
2356
2492
  // Process any price corrections queued by prior sync operations before
2357
2493
  // the pipeline gate. Pending corrections block isPipelineEmpty, and no
2358
2494
  // other code path clears them outside of _consumeFillQueue (which only
@@ -2360,20 +2496,34 @@ async function executeMaintenanceLogic(bot, context) {
2360
2496
  // during startup or periodic sync can stall the pipeline indefinitely.
2361
2497
  const pendingCorrections = bot.manager.ordersNeedingPriceCorrection?.length || 0;
2362
2498
  if (pendingCorrections > 0) {
2363
- const correctionResult = await correctAllPriceMismatches(bot.manager, bot.account, bot.privateKey, chainOrders);
2364
- if (correctionResult.failed > 0) {
2365
- const failedDetails = (correctionResult.results || [])
2366
- .filter((r) => !(r.result && r.result.success))
2367
- .slice(0, 3)
2368
- .map((r) => `${r.chainOrderId ?? '?'}: ${r.result?.error ?? 'unknown'}`)
2369
- .join(' | ');
2370
- bot._warn(`[MAINT] ${correctionResult.failed}/${pendingCorrections} price correction(s) failed` +
2371
- (failedDetails ? ` — ${failedDetails}` : '') +
2372
- (correctionResult.staleDropped > 0 ? ` (${correctionResult.staleDropped} stale dropped)` : ''));
2373
- }
2374
- else if (correctionResult.staleDropped > 0) {
2375
- bot._log(`[MAINT] ${correctionResult.corrected}/${pendingCorrections} price correction(s) resolved, ` +
2376
- `${correctionResult.staleDropped} stale dropped (resync moved the slot; re-queued by next sync if still off-target)`, 'info');
2499
+ // The drain cancels/updates chain orders directly, so it must own the
2500
+ // exclusive placement region. `correctAllPriceMismatches` acquires it
2501
+ // internally (single entry point); this call uses a short bound because
2502
+ // this is a background repair and must not block the maintenance tick
2503
+ // behind a long broadcast. A busy region leaves the queue for the next
2504
+ // tick (or the region-end wake-up).
2505
+ try {
2506
+ const correctionResult = await correctAllPriceMismatches(bot.manager, bot.account, bot.privateKey, chainOrders, { timeoutMs: 250 });
2507
+ if (correctionResult?.deferred === true) {
2508
+ bot._log('[MAINT] Deferring price-correction drain: exclusive placement region busy or shutting down', 'info');
2509
+ }
2510
+ else if (correctionResult.failed > 0) {
2511
+ const failedDetails = (correctionResult.results || [])
2512
+ .filter((r) => !(r.result && r.result.success))
2513
+ .slice(0, 3)
2514
+ .map((r) => `${r.chainOrderId ?? '?'}: ${r.result?.error ?? 'unknown'}`)
2515
+ .join(' | ');
2516
+ bot._warn(`[MAINT] ${correctionResult.failed}/${pendingCorrections} price correction(s) failed` +
2517
+ (failedDetails ? ` — ${failedDetails}` : '') +
2518
+ (correctionResult.staleDropped > 0 ? ` (${correctionResult.staleDropped} stale dropped)` : ''));
2519
+ }
2520
+ else if (correctionResult.staleDropped > 0) {
2521
+ bot._log(`[MAINT] ${correctionResult.corrected}/${pendingCorrections} price correction(s) resolved, ` +
2522
+ `${correctionResult.staleDropped} stale dropped (resync moved the slot; re-queued by next sync if still off-target)`, 'info');
2523
+ }
2524
+ }
2525
+ catch (correctionErr) {
2526
+ bot._warn(`[MAINT] Price-correction drain failed: ${getErrorMessage(correctionErr)}`);
2377
2527
  }
2378
2528
  }
2379
2529
  // Dust detection runs before the pipeline gate. Cancellation is immediate
@@ -2749,6 +2899,14 @@ async function cancelOrderDeferredOnUncertain(bot, order) {
2749
2899
  throw err;
2750
2900
  }
2751
2901
  }
2902
+ async function runWithPlacement(bot, kind, fn, options = {}) {
2903
+ // Bot-first adapter over the ONE acquire/release contract
2904
+ // (modules/order/placement_lock.ts): it owns the bounded wait, the shutdown
2905
+ // probe, the NOOP fallback for manager-less fakes and the release. Do not
2906
+ // re-implement that here — a local copy already drifted once (it could not
2907
+ // take a lease and skipped the lease-liveness check).
2908
+ return await withPlacement(bot.manager, kind, fn, options);
2909
+ }
2752
2910
  /**
2753
2911
  * Cancel dust orders immediately — no delay, no timer, no maps.
2754
2912
  * Each dust order is cancelled on chain and its slot is rotated through
@@ -2765,52 +2923,63 @@ async function cancelDustOrders(bot, { buy: buyDust = [], sell: sellDust = [] }
2765
2923
  if (allDust.length === 0)
2766
2924
  return { cancelledCount: 0, batchResult: null };
2767
2925
  const syntheticFills = [];
2768
- for (const order of allDust) {
2769
- if (!order.orderId)
2770
- continue;
2771
- try {
2772
- const cancelResult = await cancelOrderDeferredOnUncertain(bot, order);
2926
+ // Hold the exclusive placement region across the whole cancel pass: each
2927
+ // cancel mutates the chain and the following synchronizeWithChain mutates
2928
+ // the master. A COW batch / reconcile must not interleave between them.
2929
+ // The rotation batch below runs after release (it acquires its own lease).
2930
+ const placementOk = await runWithPlacement(bot, 'dust-cancel', async () => {
2931
+ for (const order of allDust) {
2932
+ if (!order.orderId)
2933
+ continue;
2773
2934
  try {
2774
- if (cancelResult?.verifiedAfterFailure) {
2775
- const accountRef = bot.accountId || bot.account;
2776
- // The cancel was verified absent on an authoritative
2777
- // (non-empty, non-truncated) read inside cancelOrder, so an
2778
- // ambiguous refetch must not run the full sync: the snapshot
2779
- // omits the freshest orders and pass-1 phantom cleanup could
2780
- // virtualize live slots. Fall back to the local cancel sync.
2781
- const freshOrders = await readOpenOrdersGuarded(chainOrders, accountRef, {
2782
- log: (message) => bot._warn(message),
2783
- label: 'DUST',
2784
- deferEmpty: true,
2785
- skipMessage: (kind) => `[DUST] Chain refetch after verified cancel is ${kind}; applying local cancel sync for ${order.id}`,
2786
- });
2787
- if (freshOrders === null) {
2788
- await bot.manager.synchronizeWithChain({ orderId: order.orderId, clearSize: true }, 'cancelOrder');
2935
+ const cancelResult = await cancelOrderDeferredOnUncertain(bot, order);
2936
+ try {
2937
+ if (cancelResult?.verifiedAfterFailure) {
2938
+ const accountRef = bot.accountId || bot.account;
2939
+ // The cancel was verified absent on an authoritative
2940
+ // (non-empty, non-truncated) read inside cancelOrder, so an
2941
+ // ambiguous refetch must not run the full sync: the snapshot
2942
+ // omits the freshest orders and pass-1 phantom cleanup could
2943
+ // virtualize live slots. Fall back to the local cancel sync.
2944
+ const freshOrders = await readOpenOrdersGuarded(chainOrders, accountRef, {
2945
+ log: (message) => bot._warn(message),
2946
+ label: 'DUST',
2947
+ deferEmpty: true,
2948
+ skipMessage: (kind) => `[DUST] Chain refetch after verified cancel is ${kind}; applying local cancel sync for ${order.id}`,
2949
+ });
2950
+ if (freshOrders === null) {
2951
+ await bot.manager.synchronizeWithChain({ orderId: order.orderId, clearSize: true }, 'cancelOrder');
2952
+ }
2953
+ else {
2954
+ await bot.manager.synchronizeWithChain(freshOrders, 'readOpenOrders');
2955
+ }
2789
2956
  }
2790
2957
  else {
2791
- await bot.manager.synchronizeWithChain(freshOrders, 'readOpenOrders');
2958
+ await bot.manager.synchronizeWithChain({ orderId: order.orderId, clearSize: true }, 'cancelOrder');
2792
2959
  }
2793
2960
  }
2794
- else {
2795
- await bot.manager.synchronizeWithChain({ orderId: order.orderId, clearSize: true }, 'cancelOrder');
2961
+ catch (refetchErr) {
2962
+ bot._warn(`[DUST] Cancel succeeded but refetch failed for ${order.id} (${order.orderId}): ${getErrorMessage(refetchErr)}`);
2796
2963
  }
2797
- }
2798
- catch (refetchErr) {
2799
- bot._warn(`[DUST] Cancel succeeded but refetch failed for ${order.id} (${order.orderId}): ${getErrorMessage(refetchErr)}`);
2800
- }
2801
- syntheticFills.push({ ...order, isPartial: true, isDelayedRotationTrigger: true });
2802
- bot._log(`[DUST] Cancelled ${order.id} (${order.orderId}) size=${order.size}`, 'debug');
2803
- }
2804
- catch (err) {
2805
- const errMsg = getErrorMessage(err) || '';
2806
- if (isOrderDoesNotExistError(errMsg, order.orderId)) {
2807
2964
  syntheticFills.push({ ...order, isPartial: true, isDelayedRotationTrigger: true });
2808
- bot._log(`[DUST] Order ${order.id} (${order.orderId}) already gone from chain`, 'debug');
2965
+ bot._log(`[DUST] Cancelled ${order.id} (${order.orderId}) size=${order.size}`, 'debug');
2809
2966
  }
2810
- else {
2811
- bot._warn(`[DUST] Failed to cancel ${order.id} (${order.orderId}): ${errMsg}`);
2967
+ catch (err) {
2968
+ const errMsg = getErrorMessage(err) || '';
2969
+ if (isOrderDoesNotExistError(errMsg, order.orderId)) {
2970
+ syntheticFills.push({ ...order, isPartial: true, isDelayedRotationTrigger: true });
2971
+ bot._log(`[DUST] Order ${order.id} (${order.orderId}) already gone from chain`, 'debug');
2972
+ }
2973
+ else {
2974
+ bot._warn(`[DUST] Failed to cancel ${order.id} (${order.orderId}): ${errMsg}`);
2975
+ }
2812
2976
  }
2813
2977
  }
2978
+ return true;
2979
+ }, { timeoutMs: 10000, isShuttingDown: () => bot._shuttingDown === true });
2980
+ if (placementOk !== true) {
2981
+ bot._log('[DUST] Deferring dust cancels: exclusive placement region busy or shutting down', 'info');
2982
+ return { cancelledCount: 0, batchResult: null };
2814
2983
  }
2815
2984
  if (syntheticFills.length === 0)
2816
2985
  return { cancelledCount: 0, batchResult: null };
@@ -2976,19 +3145,22 @@ async function acquireBts(bot, deficit) {
2976
3145
  const sellInt = floatToBlockchainInt(best.sellAmount, best.asset.precision);
2977
3146
  const minReceiveInt = floatToBlockchainInt(minReceive, BTS_PRECISION);
2978
3147
  const op = chainOrders.buildLiquidityPoolExchangeOp(bot.accountId, best.poolId, sellInt, best.asset.id, minReceiveInt, coreAssetId);
2979
- try {
2980
- if (bot.privateKey) {
3148
+ const swapOk = await runWithPlacement(bot, 'bts-acquisition-swap', async () => {
3149
+ try {
3150
+ if (!bot.privateKey) {
3151
+ bot._log('[BTS-ACQ] CRITICAL: No signing method available', 'error');
3152
+ return false;
3153
+ }
2981
3154
  await chainOrders.executeBatch(bot.account, bot.privateKey, [op]);
3155
+ return true;
2982
3156
  }
2983
- else {
2984
- bot._log('[BTS-ACQ] CRITICAL: No signing method available', 'error');
2985
- return;
3157
+ catch (err) {
3158
+ bot._log(`[BTS-ACQ] Swap broadcast failed: ${getErrorMessage(err)}`, 'error');
3159
+ return false;
2986
3160
  }
2987
- }
2988
- catch (err) {
2989
- bot._log(`[BTS-ACQ] Swap broadcast failed: ${getErrorMessage(err)}`, 'error');
3161
+ }, { timeoutMs: 10000, isShuttingDown: () => bot._shuttingDown === true });
3162
+ if (swapOk !== true)
2990
3163
  return;
2991
- }
2992
3164
  const orderType = (best.asset.id === bot.assets?.assetA?.id) ? 'sell' : 'buy';
2993
3165
  if (bot.manager.accountant) {
2994
3166
  await bot.manager.accountant.adjustTotalBalance(orderType, -best.sellAmount, 'bts-acquisition-swap-sell');
@@ -3113,14 +3285,12 @@ async function requestGridReset(bot, reason = 'structural change', options = {})
3113
3285
  // entirely (no concurrent mutation race) instead of racing them behind a
3114
3286
  // lock.
3115
3287
  if (options.skipFillLock === true || !bot.manager._fillProcessingLock || bot.manager._fillProcessingLock.isReentrant()) {
3116
- bot._recoverySyncInFlight = (bot._recoverySyncInFlight || 0) + 1;
3288
+ raiseRecoveryInFlight(bot);
3117
3289
  try {
3118
3290
  return await performGridResync(bot, resetOptions);
3119
3291
  }
3120
3292
  finally {
3121
- bot._recoverySyncInFlight = Math.max(0, (bot._recoverySyncInFlight || 0) - 1);
3122
- if ((bot._recoverySyncInFlight || 0) === 0)
3123
- drainFillQueueAfterPipelineClear(bot);
3293
+ lowerRecoveryInFlight(bot);
3124
3294
  }
3125
3295
  }
3126
3296
  return bot.manager._fillProcessingLock.acquire(async () => performGridResync(bot, resetOptions));
@@ -3199,13 +3369,13 @@ function wireStructuralGridResyncRequest(bot) {
3199
3369
  // prevents a fill arriving mid-reload from starting a new COW
3200
3370
  // batch whose broadcast would overlap the reload and force an
3201
3371
  // avoidable commit refusal + re-adoption cycle.
3202
- bot._recoverySyncInFlight = (bot._recoverySyncInFlight || 0) + 1;
3372
+ raiseRecoveryInFlight(bot);
3203
3373
  let persistedResult;
3204
3374
  try {
3205
3375
  persistedResult = await bot._recoverFromPersistedGrid();
3206
3376
  }
3207
3377
  finally {
3208
- bot._recoverySyncInFlight = Math.max(0, (bot._recoverySyncInFlight || 0) - 1);
3378
+ lowerRecoveryInFlight(bot);
3209
3379
  }
3210
3380
  if (persistedResult.success) {
3211
3381
  if (bot.manager?._recoveryState) {
@@ -3230,7 +3400,7 @@ function wireStructuralGridResyncRequest(bot) {
3230
3400
  // generation orphans). _recoverFromPersistedGrid already
3231
3401
  // incremented and released the counter; increment again
3232
3402
  // for the full-resync branch.
3233
- bot._recoverySyncInFlight = (bot._recoverySyncInFlight || 0) + 1;
3403
+ raiseRecoveryInFlight(bot);
3234
3404
  let resetResult;
3235
3405
  try {
3236
3406
  resetResult = await (bot.requestGridReset('rms_structural_grid_resync', {
@@ -3243,9 +3413,7 @@ function wireStructuralGridResyncRequest(bot) {
3243
3413
  }));
3244
3414
  }
3245
3415
  finally {
3246
- bot._recoverySyncInFlight = Math.max(0, (bot._recoverySyncInFlight || 0) - 1);
3247
- if ((bot._recoverySyncInFlight || 0) === 0)
3248
- drainFillQueueAfterPipelineClear(bot);
3416
+ lowerRecoveryInFlight(bot);
3249
3417
  }
3250
3418
  if (resetResult && bot.manager?._recoveryState) {
3251
3419
  bot.manager._recoveryState = { ...bot.manager._recoveryState, attemptCount: 0, lastAttemptAt: 0, lastFailureAt: 0 };
@@ -579,27 +579,39 @@ async function finishStartupSequence(bot, startupState) {
579
579
  if (shouldRegenerate) {
580
580
  if (!chainReadTruncated && Array.isArray(chainOpenOrders) && chainOpenOrders.length > 0) {
581
581
  bot._log('Generating new grid and syncing with existing on-chain orders...');
582
- await botGridModule(bot).initializeGrid(bot.manager);
583
- await bot.manager.syncFromOpenOrders(chainOpenOrders, { skipAccounting: true });
584
- // Drain queued fills BEFORE re-placement (P3 ordering): fills
585
- // replayed from history reference the PRE-restart order ids.
586
- // Processing them now (freshly synced grid) keeps their slot
587
- // provenance; processing them after reconcile re-placement
588
- // finds no grid order and falls back to orphan proceeds
589
- // credits, which drift the fund bookkeeping.
590
- if (bot._incomingFillQueue.length > 0) {
591
- bot._log(`[STARTUP] Processing ${bot._incomingFillQueue.length} queued fill(s) before re-placement (order provenance intact)`, 'info');
592
- await bot._processFillsWithBootstrapMode(chainOrders);
582
+ // Rebuild owns placement until reconcile finishes: a fill-driven
583
+ // COW that starts inside this window must defer instead of
584
+ // re-planning against the order-id-less master.
585
+ bot.manager.beginStructuralRebuild?.('startup regenerate');
586
+ try {
587
+ await botGridModule(bot).initializeGrid(bot.manager);
588
+ await bot.manager.syncFromOpenOrders(chainOpenOrders, { skipAccounting: true });
589
+ // Drain queued fills BEFORE re-placement (P3 ordering): fills
590
+ // replayed from history reference the PRE-restart order ids.
591
+ // Processing them now (freshly synced grid) keeps their slot
592
+ // provenance; processing them after reconcile re-placement
593
+ // finds no grid order and falls back to orphan proceeds
594
+ // credits, which drift the fund bookkeeping.
595
+ if (bot._incomingFillQueue.length > 0) {
596
+ bot._log(`[STARTUP] Processing ${bot._incomingFillQueue.length} queued fill(s) before re-placement (order provenance intact)`, 'info');
597
+ await bot._processFillsWithBootstrapMode(chainOrders);
598
+ }
599
+ const rebalanceResult = await reconcileMod.reconcileGridOrders({
600
+ manager: bot.manager,
601
+ config: bot.config,
602
+ account: bot.account,
603
+ privateKey: bot.privateKey,
604
+ chainOrders,
605
+ chainOpenOrders,
606
+ // This path IS the rebuild: it owns update-first
607
+ // placement and must not defer on its own flag.
608
+ options: { allowDuringRebuild: true },
609
+ });
610
+ await bot._executeBatchIfNeeded(rebalanceResult, 'startup reconcile (regenerated grid)');
611
+ }
612
+ finally {
613
+ bot.manager.endStructuralRebuild?.();
593
614
  }
594
- const rebalanceResult = await reconcileMod.reconcileGridOrders({
595
- manager: bot.manager,
596
- config: bot.config,
597
- account: bot.account,
598
- privateKey: bot.privateKey,
599
- chainOrders,
600
- chainOpenOrders,
601
- });
602
- await bot._executeBatchIfNeeded(rebalanceResult, 'startup reconcile (regenerated grid)');
603
615
  }
604
616
  else if (!chainReadTruncated) {
605
617
  bot._log('Generating new grid and placing initial orders on-chain...');
@@ -98,6 +98,38 @@ declare function recoverFromPersistedGrid(bot: BotLike): Promise<{
98
98
  reason: string;
99
99
  halt: boolean;
100
100
  }>;
101
+ /**
102
+ * Detect live orders resting INSIDE the committed gap band and schedule the
103
+ * repair (fill-less COW re-plan + cancel-only teeth as last resort).
104
+ *
105
+ * Why this exists: a boundary commit that moves the boundary away from a live
106
+ * order strands it inside the spread band. The plan normally evacuates it with
107
+ * a rotation in the SAME batch, but the LAST-FILL-GUARD re-proves an evacuation
108
+ * against the PRE-COMMIT geometry and refuses it as stale when the plan's own
109
+ * crawl is what created the stranding (fail-closed by design — see the
110
+ * 2026-10-30 bid-edge incident). The batch then commits the new boundary with
111
+ * the stranded order still live, and because plans are fill-driven the state
112
+ * never heals while the market is quiet: the 4-slot spread band keeps two live
113
+ * buys and the real spread collapses (observed: 1.21% against a 2.0% target).
114
+ *
115
+ * Re-planning AFTER the commit is safe where the in-batch rotation is not: the
116
+ * committed geometry is now the LIVE geometry, so the evacuation stamp passes
117
+ * `isEvacuationStampStillValid` and the rotation executes as one price update.
118
+ *
119
+ * Cheap when healthy: one `detectGapEvacuationCandidates` scan (O(grid)) and an
120
+ * early return. Callers run it on commit (writer of the stranding) and on the
121
+ * maintenance tick (covers restarts and commits from paths without a bot
122
+ * reference).
123
+ *
124
+ * @param {import('./dexbot_class.js').DEXBot} bot
125
+ * @param {string} context - Label for logging/telemetry
126
+ * @returns `{ stranded, scheduled }` — stranded slot ids found, whether a
127
+ * re-plan was scheduled.
128
+ */
129
+ declare function scheduleGapEvacRepair(bot: BotLike, context?: string): {
130
+ stranded: string[];
131
+ scheduled: boolean;
132
+ };
101
133
  /**
102
134
  * Schedule a best-effort target-grid rebalance after a recovery sync.
103
135
  *
@@ -126,5 +158,5 @@ declare function rejectCorruptedGridSnapshot(bot: BotLike, context: string): Pro
126
158
  * @returns {Promise<boolean>}
127
159
  */
128
160
  declare function targetedOrderRepair(bot: BotLike, orderIds: string[]): Promise<boolean>;
129
- export { persistAndRecoverIfNeeded, getRecentFillKeysSnapshot, triggerStateRecoverySync, abortFlowIfIllegalState, handleBatchHardAbort, applyRecoverableGridUpdates, recoverExplicitStaleOrders, recoverBatchSizeDrift, recoverFromPersistedGrid, rejectCorruptedGridSnapshot, targetedOrderRepair, _schedulePostRecoveryRebalance as schedulePostRecoveryRebalance };
161
+ export { persistAndRecoverIfNeeded, getRecentFillKeysSnapshot, triggerStateRecoverySync, abortFlowIfIllegalState, handleBatchHardAbort, applyRecoverableGridUpdates, recoverExplicitStaleOrders, recoverBatchSizeDrift, recoverFromPersistedGrid, rejectCorruptedGridSnapshot, targetedOrderRepair, scheduleGapEvacRepair, _schedulePostRecoveryRebalance as schedulePostRecoveryRebalance };
130
162
  //# sourceMappingURL=dexbot_state_recovery.d.ts.map