dexbot 1.7.0 → 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 (105) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +3 -3
  3. package/analysis/README.md +33 -13
  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_liquidity.js +15 -4
  9. package/dist/analysis/bot_key_utils.d.ts +44 -1
  10. package/dist/analysis/bot_key_utils.js +76 -7
  11. package/dist/analysis/fills_cache.js +2 -1
  12. package/dist/analysis/grid_correction_check.d.ts +1 -19
  13. package/dist/analysis/grid_correction_check.js +12 -30
  14. package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
  15. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
  16. package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
  17. package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
  18. package/dist/analysis/liquidity/liquidity_view.js +11 -0
  19. package/dist/analysis/resolve_bot_accounts.js +7 -6
  20. package/dist/analysis/trade_profitability.js +2 -1
  21. package/dist/credential-daemon.js +13 -2
  22. package/dist/dexbot.js +4 -4
  23. package/dist/modules/account_bots.d.ts +11 -1
  24. package/dist/modules/account_orders.d.ts +12 -0
  25. package/dist/modules/account_orders.js +30 -0
  26. package/dist/modules/bitshares-native/transport.js +24 -6
  27. package/dist/modules/bitshares_client.d.ts +24 -6
  28. package/dist/modules/bitshares_client.js +44 -7
  29. package/dist/modules/bot_settings.d.ts +2 -0
  30. package/dist/modules/constants.d.ts +26 -3
  31. package/dist/modules/constants.js +63 -8
  32. package/dist/modules/dexbot_class.d.ts +1 -6
  33. package/dist/modules/dexbot_class.js +14 -0
  34. package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
  35. package/dist/modules/dexbot_cow_runtime.js +620 -132
  36. package/dist/modules/dexbot_fill_runtime.js +124 -35
  37. package/dist/modules/dexbot_maintenance_runtime.js +226 -73
  38. package/dist/modules/dexbot_startup_runtime.js +32 -20
  39. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  40. package/dist/modules/dexbot_state_recovery.js +167 -5
  41. package/dist/modules/node_connect_policy.d.ts +8 -1
  42. package/dist/modules/node_connect_policy.js +18 -2
  43. package/dist/modules/node_flap_score.d.ts +87 -0
  44. package/dist/modules/node_flap_score.js +124 -0
  45. package/dist/modules/node_health_cache.d.ts +40 -3
  46. package/dist/modules/node_health_cache.js +66 -20
  47. package/dist/modules/node_manager.d.ts +101 -19
  48. package/dist/modules/node_manager.js +255 -65
  49. package/dist/modules/order/accounting.js +56 -7
  50. package/dist/modules/order/format.d.ts +24 -10
  51. package/dist/modules/order/format.js +30 -10
  52. package/dist/modules/order/grid.js +82 -11
  53. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  54. package/dist/modules/order/grid_reconcile.js +333 -210
  55. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  56. package/dist/modules/order/grid_reconcile_internal.js +207 -87
  57. package/dist/modules/order/index.d.ts +4 -0
  58. package/dist/modules/order/lifecycle.d.ts +353 -0
  59. package/dist/modules/order/lifecycle.js +1109 -0
  60. package/dist/modules/order/manager.d.ts +271 -5
  61. package/dist/modules/order/manager.js +651 -48
  62. package/dist/modules/order/placement_lock.d.ts +102 -0
  63. package/dist/modules/order/placement_lock.js +222 -0
  64. package/dist/modules/order/strategy.js +13 -1
  65. package/dist/modules/order/sync_engine.d.ts +13 -1
  66. package/dist/modules/order/sync_engine.js +153 -53
  67. package/dist/modules/order/utils/math.d.ts +22 -1
  68. package/dist/modules/order/utils/math.js +54 -1
  69. package/dist/modules/order/utils/order.d.ts +75 -5
  70. package/dist/modules/order/utils/order.js +158 -9
  71. package/dist/modules/order/utils/system.d.ts +18 -0
  72. package/dist/modules/order/utils/system.js +84 -8
  73. package/dist/modules/order/utils/validate.d.ts +7 -1
  74. package/dist/modules/order/utils/validate.js +48 -2
  75. package/dist/modules/outcome.d.ts +54 -0
  76. package/dist/modules/outcome.js +51 -0
  77. package/dist/modules/settings_merge.d.ts +4 -0
  78. package/dist/modules/settings_merge.js +9 -0
  79. package/dist/modules/timing_policy.d.ts +82 -0
  80. package/dist/modules/timing_policy.js +244 -0
  81. package/dist/modules/types.d.ts +132 -0
  82. package/dist/scripts/analyze-credit.js +54 -17
  83. package/dist/scripts/analyze-orders.d.ts +4 -2
  84. package/dist/scripts/analyze-orders.js +113 -34
  85. package/dist/scripts/chart_targets.js +11 -15
  86. package/dist/scripts/test-credit-renewal.js +12 -5
  87. package/docs/COW_INVARIANTS.md +67 -8
  88. package/docs/DEXBOT_COMPARISON.md +6 -6
  89. package/docs/EVOLUTION.md +9 -8
  90. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  91. package/docs/GRID_PRICE_INVARIANT.md +1 -1
  92. package/docs/GRID_RECONCILE.md +17 -12
  93. package/docs/LOGGING.md +25 -1
  94. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +175 -26
  95. package/docs/README.md +23 -2
  96. package/docs/WORKFLOW.md +9 -3
  97. package/docs/architecture.md +42 -5
  98. package/docs/developer_guide.md +25 -8
  99. package/modules/README.md +3 -0
  100. package/package.json +1 -1
  101. package/scripts/README.md +16 -0
  102. package/scripts/pdev.sh +14 -1
  103. package/scripts/pmain.sh +23 -8
  104. package/scripts/ptest.sh +7 -0
  105. package/tests/README.md +30 -1
@@ -10,13 +10,16 @@
10
10
  * - Grid slot distribution (% near center) vs grid composition
11
11
  *
12
12
  * Usage:
13
- * node dist/scripts/analyze-orders.js # terminal output
14
- * node dist/scripts/analyze-orders.js --export # standalone HTML report
13
+ * node dist/scripts/analyze-orders.js # terminal output
14
+ * node dist/scripts/analyze-orders.js <bot|account> # one bot, or every bot on an account
15
+ * node dist/scripts/analyze-orders.js --export # standalone HTML report
15
16
  */
16
17
  import fs from 'node:fs';
17
18
  import path from 'node:path';
18
19
  import { formatCurrency, formatFundsValue } from '../modules/order/format.js';
19
20
  import { resolveConfiguredPriceBound } from '../modules/order/utils/order.js';
21
+ import { calculateGapSlots } from '../modules/order/utils/math.js';
22
+ import { parseSlotIndex } from '../modules/order/utils/slot.js';
20
23
  import { ORDER_TYPES, ORDER_STATES, MARKET_ADAPTER } from '../modules/constants.js';
21
24
  import { applyAsymmetricBounds } from '../market_adapter/core/asymmetric_bounds.js';
22
25
  import { PATHS } from '../modules/paths.js';
@@ -26,7 +29,10 @@ const { readJSON } = getStorage();
26
29
  import { getErrorMessage } from '../modules/utils/errors.js';
27
30
  import { toFileUrl } from '../analysis/chart_utils.js';
28
31
  import { CLI_TAGS, savedLine } from '../modules/cli_progress.js';
29
- import { isSameBotName, sanitizeKey } from '../modules/utils/sanitize_key.js';
32
+ import { isSameBotName } from '../modules/utils/sanitize_key.js';
33
+ // Bot keys and `<bot|account>` target matching are shared with the other
34
+ // analysis tools (analysis/bot_key_utils) so the commands cannot drift.
35
+ import { computeBotKey, matchBotAccountTarget, matchBotEntryTarget } from '../analysis/bot_key_utils.js';
30
36
  import { CLI_COLORS as colors } from '../modules/cli_colors.js';
31
37
  import { pathToFileURL } from 'node:url';
32
38
  const ORDERS_DIR = PATHS.ORDERS_DIR;
@@ -53,17 +59,6 @@ const HEADER_WIDTH = 11 + BAR_WIDTH;
53
59
  * Utility Functions
54
60
  * Helper functions for file I/O, formatting, and data retrieval
55
61
  */
56
- function createBotKey(bot, index) {
57
- if (bot && bot.name) {
58
- return sanitizeKey(String(bot.name));
59
- }
60
- const identifier = bot && bot.assetA && bot.assetB
61
- ? `${bot.assetA}/${bot.assetB}`
62
- : bot && bot.assetAId && bot.assetBId
63
- ? `${bot.assetAId}/${bot.assetBId}`
64
- : `bot-${index}`;
65
- return `${sanitizeKey(identifier)}-${index}`;
66
- }
67
62
  function hasOrderGrid(data) {
68
63
  if (!data || typeof data !== 'object' || Array.isArray(data))
69
64
  return false;
@@ -299,7 +294,9 @@ function getConfiguredBotConfig(botKey, botData) {
299
294
  return botsConfig.find((bot, index) => {
300
295
  if (!bot)
301
296
  return false;
302
- return createBotKey(bot, index) === botKey || (meta.name && isSameBotName(bot.name, meta.name));
297
+ // Same key generator the runtime writes with (analysis/bot_key_utils →
298
+ // modules/account_orders), so a renamed pair can never drift.
299
+ return computeBotKey(bot, index) === botKey || (meta.name && isSameBotName(bot.name, meta.name));
303
300
  }) || null;
304
301
  }
305
302
  function getOrderFileCandidate(fileName) {
@@ -395,12 +392,23 @@ function analyzeOrder(botData, config, botKey) {
395
392
  const hasBoundary = typeof botData.boundaryIdx === 'number' && Number.isFinite(botData.boundaryIdx);
396
393
  const boundaryIdx = hasBoundary ? botData.boundaryIdx : 0;
397
394
  const boundaryLess = !hasBoundary;
398
- const buySlots = boundaryLess
399
- ? grid.filter((s) => s.type === ORDER_TYPES.BUY)
400
- : grid.filter((s, i) => i <= boundaryIdx && s.type === ORDER_TYPES.BUY);
401
- const sellSlots = boundaryLess
402
- ? grid.filter((s) => s.type === ORDER_TYPES.SELL)
403
- : grid.filter((s, i) => i > boundaryIdx && s.type === ORDER_TYPES.SELL);
395
+ /** Slot identity: the parsed `slot-N` id wins over the array position (a re-sort invalidates position). */
396
+ const slotIndex = (s, i) => {
397
+ const parsed = parseSlotIndex(s?.id);
398
+ return parsed === null ? i : parsed;
399
+ };
400
+ // CLASSIFY BY SLOT TYPE, NOT BY ARRAY SLICE.
401
+ // The persisted boundary says where the rails SHOULD be; a live order can be
402
+ // stranded inside the spread band (a boundary commit moved away from it and
403
+ // GAP-EVAC has not evacuated it yet) and it keeps its rail type. Slicing by
404
+ // index (`i <= boundaryIdx`) dropped exactly those orders from every bucket:
405
+ // the report then summed to fewer slots than the grid holds AND measured the
406
+ // "real" spread from the geometry edge instead of the actual top of book
407
+ // (observed live: 2.02% reported vs 1.21% on chain, with two live buys hidden
408
+ // inside the band). Type buckets keep every order visible; the geometry
409
+ // disagreement is reported explicitly via `gapBand.inBandPlaced`.
410
+ const buySlots = grid.filter((s) => s.type === ORDER_TYPES.BUY);
411
+ const sellSlots = grid.filter((s) => s.type === ORDER_TYPES.SELL);
404
412
  const spreadSlots = grid.filter((s) => s.type === ORDER_TYPES.SPREAD);
405
413
  const activeBuySlots = buySlots.filter((s) => s.state === ORDER_STATES.ACTIVE || s.state === ORDER_STATES.PARTIAL);
406
414
  const virtualBuySlots = buySlots.filter((s) => s.state === ORDER_STATES.VIRTUAL);
@@ -425,8 +433,11 @@ function analyzeOrder(botData, config, botKey) {
425
433
  // design (a partially-placed grid IS partially masked); it is not a bug, but
426
434
  // the output should be read with that caveat in mind.
427
435
  const hasOrderId = (s) => !!(s && s.orderId);
428
- const railBuys = boundaryLess ? grid.filter((s) => s.type === ORDER_TYPES.BUY) : grid.slice(0, boundaryIdx + 1);
429
- const railSells = boundaryLess ? grid.filter((s) => s.type === ORDER_TYPES.SELL) : grid.slice(boundaryIdx + 1);
436
+ // Rail lists are type-based for the same reason as the buckets above: a
437
+ // stranded live order is still a live order on its side, and excluding it
438
+ // fabricates a tighter (geometry-edge) spread.
439
+ const railBuys = buySlots;
440
+ const railSells = sellSlots;
430
441
  const placedBuys = railBuys.filter((s) => s.type === ORDER_TYPES.BUY && hasOrderId(s));
431
442
  const placedSells = railSells.filter((s) => s.type === ORDER_TYPES.SELL && hasOrderId(s));
432
443
  const geoBuy = railBuys.filter((s) => s.type === ORDER_TYPES.BUY);
@@ -446,6 +457,45 @@ function analyzeOrder(botData, config, botKey) {
446
457
  const realSpread = bestBuySlot && bestSellSlot
447
458
  ? ((bestSellSlot.price - bestBuySlot.price) / bestBuySlot.price)
448
459
  : 0;
460
+ /**
461
+ * Gap-band occupancy: live rail orders resting strictly inside the band.
462
+ * These are the spread-collapse signature — they hold band slots that should
463
+ * be empty, so the top-of-book spread is narrower than the configured gap.
464
+ * Detection is geometry-only (slot index vs boundary/gap), matching the
465
+ * runtime's `detectGapEvacuationCandidates`. The band width comes from the
466
+ * snapshot's frozen genesis (the geometry the slots were built with), then
467
+ * the live config, then the count of SPREAD-typed slots.
468
+ */
469
+ const snapshotGapSlots = Number(botData.genesis?.gapSlots);
470
+ // Unknown geometry stays unknown: without a frozen genesis gap or a live
471
+ // config there is no band to judge, and guessing one (e.g. from the
472
+ // SPREAD-typed slot count, which includes empty rail holes) would fabricate
473
+ // an "occupied band" warning. Same absent-aware rule as the runtime.
474
+ const gapSlots = Number.isFinite(snapshotGapSlots) && snapshotGapSlots >= 0
475
+ ? Math.floor(snapshotGapSlots)
476
+ : (config
477
+ ? calculateGapSlots(config.incrementPercent, config.targetSpreadPercent, config.gridLimits)
478
+ : null);
479
+ const sellStartIdx = hasBoundary && gapSlots !== null ? boundaryIdx + 1 + gapSlots : null;
480
+ const inBandPlaced = [];
481
+ if (hasBoundary && gapSlots !== null && sellStartIdx !== null) {
482
+ grid.forEach((s, i) => {
483
+ if (!hasOrderId(s))
484
+ return;
485
+ const idx = slotIndex(s, i);
486
+ if (idx > boundaryIdx && idx < sellStartIdx) {
487
+ inBandPlaced.push({
488
+ // Real snapshots always carry a slot id; fall back to the chain order
489
+ // id (then the array position) so the report always names something
490
+ // an operator can act on.
491
+ id: String(s.id ?? s.orderId ?? `#${i}`),
492
+ type: String(s.type ?? '?'),
493
+ price: Number(s.price),
494
+ idx,
495
+ });
496
+ }
497
+ });
498
+ }
449
499
  let spreadDiff, targetSpread, incrementCheck;
450
500
  /**
451
501
  * Config-based Comparisons
@@ -527,6 +577,7 @@ function analyzeOrder(botData, config, botKey) {
527
577
  buy: buySlots.length,
528
578
  sell: sellSlots.length,
529
579
  spread: spreadSlots.length,
580
+ stranded: inBandPlaced.length,
530
581
  activeBuy: activeBuySlots.length,
531
582
  virtualBuy: virtualBuySlots.length,
532
583
  activeSell: activeSellSlots.length,
@@ -534,6 +585,11 @@ function analyzeOrder(botData, config, botKey) {
534
585
  partialBuy: buySlots.filter((s) => s.state === ORDER_STATES.PARTIAL).length,
535
586
  partialSell: sellSlots.filter((s) => s.state === ORDER_STATES.PARTIAL).length
536
587
  },
588
+ gapBand: {
589
+ gapSlots,
590
+ sellStartIdx,
591
+ inBandPlaced
592
+ },
537
593
  // Slot data for weight visualization
538
594
  slotData: {
539
595
  buy: buySlots,
@@ -1137,6 +1193,19 @@ function formatAnalysis(analysisInput) {
1137
1193
  else {
1138
1194
  lines.push(` Spread:${formatPercent(analysis.spread.real).padStart(6)} | Incr.:${formatPercent(analysis.increment.avg).padStart(6)}`);
1139
1195
  }
1196
+ // Spread-collapse warning: live rail orders sitting inside the gap band eat
1197
+ // the spread slots, so the reported spread is the REAL top-of-book gap (which
1198
+ // is narrower than the configured one). Naming the slots is what makes the
1199
+ // state actionable — they need a GAP-EVAC evacuation, not a config change.
1200
+ const inBandPlaced = analysis.gapBand?.inBandPlaced ?? [];
1201
+ if (inBandPlaced.length > 0) {
1202
+ const names = inBandPlaced
1203
+ .map((o) => `${o.id} ${o.type} @${formatCurrency(o.price)}`)
1204
+ .join(', ');
1205
+ lines.push(` ${colors.sell}⚠️ Spread band occupied:${colors.reset} ` +
1206
+ `${inBandPlaced.length} live order(s) inside the ${analysis.gapBand?.gapSlots ?? '?'}-slot band ` +
1207
+ `(${names}) — real spread is narrower than target; GAP-EVAC must evacuate them`);
1208
+ }
1140
1209
  // Active orders comparison
1141
1210
  if (analysis.hasConfig && analysis.coreOrdersTarget) {
1142
1211
  const buyTarget = analysis.coreOrdersTarget.buy;
@@ -1426,9 +1495,10 @@ function generateHtmlReport(analyses) {
1426
1495
  function main() {
1427
1496
  const rawArgs = process.argv.slice(2);
1428
1497
  const exportHtml = rawArgs.includes('--export');
1429
- // Positional (non-flag) args are treated as bot key filters. Example:
1430
- // node dist/scripts/analyze-orders.js <bot>
1431
- // node dist/scripts/analyze-orders.js <bot> --export
1498
+ // Positional (non-flag) args select the analysed grids: a bot name/key, or a
1499
+ // chain account (every bot trading it). Examples:
1500
+ // node dist/scripts/analyze-orders.js <bot|account>
1501
+ // node dist/scripts/analyze-orders.js <bot|account> --export
1432
1502
  const botKeyFilter = rawArgs.find((arg) => !arg.startsWith('-'))?.trim().toLowerCase() || null;
1433
1503
  if (!exportHtml) {
1434
1504
  const targetNote = botKeyFilter ? ` (filter: ${botKeyFilter})` : '';
@@ -1437,21 +1507,30 @@ function main() {
1437
1507
  }
1438
1508
  // Get all order files sorted by modification time (newest first)
1439
1509
  let { files, skippedCandidates } = getOrderFiles();
1440
- // Filter to a single bot when a bot key was requested. Also match the
1441
- // sanitized form of a bot name (e.g. "AAA-BBB" -> "aaa-bbb").
1510
+ // Filter to the requested bot or account. Target matching is the shared
1511
+ // `<bot|account>` rule set (analysis/bot_key_utils): bot key, bot name, or the
1512
+ // chain account the bot trades from (`preferredAccount` name / 1.2.x id).
1513
+ // The file's own key still matches when a snapshot has no bots.json entry.
1442
1514
  if (botKeyFilter) {
1443
- const sanitizedFilter = sanitizeKey(botKeyFilter);
1444
- const matched = files.filter((file) => String(file.botKey).toLowerCase() === botKeyFilter
1445
- || String(file.botKey).toLowerCase() === sanitizedFilter
1446
- || (file.config?.name && sanitizeKey(file.config.name) === sanitizedFilter));
1515
+ const matched = files.filter((file) => {
1516
+ const config = file.config ?? null;
1517
+ return matchBotEntryTarget(config, botKeyFilter, file.botKey) !== null
1518
+ || matchBotAccountTarget(config, botKeyFilter);
1519
+ });
1447
1520
  if (matched.length === 0) {
1448
1521
  if (exportHtml) {
1449
1522
  generateHtmlReport([]);
1450
1523
  }
1451
1524
  else {
1452
- console.log(`${colors.sell}No order grid found for bot key '${botKeyFilter}'.${colors.reset}`);
1525
+ console.log(`${colors.sell}No order grid found for '${botKeyFilter}'.${colors.reset}`);
1453
1526
  console.log('Available bots:');
1454
- files.forEach((file) => console.log(` - ${file.botKey}`));
1527
+ files.forEach((file) => {
1528
+ const config = file.config ?? null;
1529
+ const name = config?.name ? String(config.name) : '';
1530
+ const nameSuffix = name && name.toLowerCase() !== String(file.botKey).toLowerCase() ? ` (${name})` : '';
1531
+ const account = config?.preferredAccount ? ` (account: ${String(config.preferredAccount)})` : '';
1532
+ console.log(` - ${file.botKey}${nameSuffix}${account}`);
1533
+ });
1455
1534
  }
1456
1535
  process.exit(0);
1457
1536
  }
@@ -5,9 +5,8 @@
5
5
  * from drifting on which bots are recognised and how the "unknown target"
6
6
  * hint is rendered.
7
7
  */
8
- import { isSameBotName } from '../modules/utils/sanitize_key.js';
9
8
  import { isPoolIdRef, isPoolRefLike } from '../modules/liquidity_pool_ref.js';
10
- import { loadBotMeta, loadBotSettings, computeBotKey } from '../analysis/bot_key_utils.js';
9
+ import { computeBotKey, loadBotMeta, loadBotSettings, matchBotTargetIn } from '../analysis/bot_key_utils.js';
11
10
  /** Pool id targets (`133` / `1.19.x`) — delegates to the shared pool-ref rules. */
12
11
  function isPoolIdTarget(target) {
13
12
  return isPoolIdRef(target);
@@ -20,19 +19,16 @@ function isPoolTarget(target) {
20
19
  function findBotByTarget(target) {
21
20
  const settings = loadBotSettings();
22
21
  const entries = Array.isArray(settings?.bots) ? settings.bots : [];
23
- for (let i = 0; i < entries.length; i++) {
24
- const entry = entries[i];
25
- if (!entry)
26
- continue;
27
- if (isSameBotName(entry.name, target))
28
- return { botKey: computeBotKey(entry, i) ?? '', meta: entry };
29
- }
30
- const meta = loadBotMeta(target);
31
- if (meta) {
32
- const idx = entries.findIndex((entry) => isSameBotName(entry.name, meta.name));
33
- return { botKey: computeBotKey(meta, idx >= 0 ? idx : 0) ?? '', meta };
34
- }
35
- return null;
22
+ // Name/key matching is the shared `<bot|account>` rule set
23
+ // (analysis/bot_key_utils); these commands take bot targets only — an
24
+ // account can back several bots, so an account spelling would silently
25
+ // chart whichever entry came first.
26
+ const match = matchBotTargetIn(entries, target).find((m) => m.matchedBy !== 'account');
27
+ if (!match)
28
+ return null;
29
+ // loadBotMeta canonicalises the pair symbols (analysis-wide convention).
30
+ const meta = loadBotMeta(match.botKey) ?? match.meta;
31
+ return { botKey: match.botKey, meta };
36
32
  }
37
33
  /** Bot keys used in the unknown-target hint (first 8 shown by callers). */
38
34
  function knownBotKeys() {
@@ -10,9 +10,10 @@ const chainOrders = require('../modules/chain_orders');
10
10
  const { PATHS } = require('../modules/paths');
11
11
  const { getErrorMessage, getErrorName } = require('../modules/utils/errors');
12
12
  const { loadSettingsFile, normalizeBotEntries, resolveRawBotEntries } = require('../modules/bot_settings');
13
- const { getStoredBotAccountId, persistBotAccountId } = require('../analysis/bot_key_utils');
14
- const { isSameBotName } = require('../modules/utils/sanitize_key');
15
13
  const { blockchainToFloat } = require('../modules/order/utils/math');
14
+ // Typed ESM import (not `require`) so target matching and the accountId helpers
15
+ // stay checked here instead of degrading to `any`.
16
+ import { getStoredBotAccountId, matchBotTargetIn, persistBotAccountId } from '../analysis/bot_key_utils.js';
16
17
  const DEFAULT_BOT_NAME = 'AAA-BBB';
17
18
  const DEFAULT_THRESHOLD_HOURS = 24;
18
19
  const DEFAULT_MAX_FEE_RATE_PER_DAY = 0.05;
@@ -101,11 +102,14 @@ function loadBot(botName) {
101
102
  const botsPath = PATHS.PROFILES.BOTS_JSON;
102
103
  const { config } = loadSettingsFile(botsPath, { silent: false, exitOnError: false });
103
104
  const entries = normalizeBotEntries(resolveRawBotEntries(config));
104
- const bot = entries.find((entry) => isSameBotName(entry.name, botName));
105
- if (!bot) {
105
+ // Shared `<bot>` rule set (analysis/bot_key_utils): display name or bot key,
106
+ // case/separator-insensitive. Account spellings are rejected here — this
107
+ // flag selects a bot profile, not a chain account.
108
+ const match = matchBotTargetIn(entries, botName).find((m) => m.matchedBy !== 'account');
109
+ if (!match) {
106
110
  throw new Error(`Bot profile "${botName}" not found in ${botsPath}`);
107
111
  }
108
- return bot;
112
+ return match.meta;
109
113
  }
110
114
  function amountToFloat(amount, asset) {
111
115
  const value = Number(amount);
@@ -218,6 +222,9 @@ async function main() {
218
222
  maxFeeRatePerDay: args.maxFeeRatePerDay,
219
223
  autoReborrow: true,
220
224
  autoRepay: args.autoRepay,
225
+ // Widened on purpose: the block below adds fields to this item
226
+ // (`maxCollateralAmount`, `allowedOfferIds`) that this literal does not
227
+ // declare — without the annotation the assignment trips TS2561.
221
228
  },
222
229
  ],
223
230
  },
@@ -20,6 +20,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
20
20
  | `INV-COW` | COW pipeline |
21
21
  | `INV-PROJ` | Projection |
22
22
  | `INV-ID` | Order identity |
23
+ | `INV-LIFE` | Order lifecycle (chain existence) |
23
24
  | `INV-ACC` | Accounting / fund tracking |
24
25
  | `INV-SYNC` | Sync engine |
25
26
  | `INV-MAINT` | Maintenance runtime |
@@ -30,6 +31,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
30
31
  | `INV-REG` | Fund registry |
31
32
  | `INV-SUB` | Subscriptions |
32
33
  | `INV-BROADCAST` | Broadcast |
34
+ | `INV-TIME` | Timing windows |
33
35
 
34
36
  ---
35
37
 
@@ -57,12 +59,12 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
57
59
  - `_clearOrderCachesLogic` must bump `_gridVersion` so an in-flight COW plan (baseVersion from the pre-swap grid) is refused at commit instead of committing over a regenerated zero-slot grid.
58
60
 
59
61
  - `INV-COW-006` Boundary moves only on fills and same-batch spread promotion
60
- - Fund changes never move the boundary. Only boundary crawl (`deriveTargetBoundary`, `order/utils/order.ts`), spread promotion, and the fill-driven rail clamp move it, and promotion shifts it only onto orders placed in the same atomic batch (`prepareSpreadCorrectionOrders`).
62
+ - Fund changes never move the boundary. Only boundary crawl (`deriveTargetBoundary`, `order/utils/order.ts`), spread promotion, and the fill-driven rail clamp move it. Promotion shifts it onto orders placed in the same atomic batch **and may absorb a same-side order already placed inside the band** (that order is rail-typed by construction — a placed SPREAD slot is `ILLEGAL_SPREAD_STATE` in `validateOrder`, so "same-side" needs no extra resolution); it becomes a legal rail member once the boundary slides past it. Only the empty band slot is a CREATE target, and the absorption still counts against the reserve/stranding depth caps.
61
63
  - Funds drive order sizing/budget allocation only; `syncBoundaryToFunds`/`calculateFundDrivenBoundary` are deleted (1.5.3).
62
- - `deriveRailBoundary` (`dexbot_cow_runtime.ts`, pre-broadcast) clamps the committed boundary to the batch's resulting rails: `maxBuyIdx <= boundary <= minSellIdx - gapSlots - 1`. A fill's counter order is the rail fact, so it decides the boundary; an empty refill hole never outvotes it. Rail membership = the batch's own op destinations + master rail orders on their own side of the planned boundary (BUY at/below, SELL at/above the implied sellStart); a master order parked on the wrong side is a STRAY (refused-commit adoption, SPREAD-GUARD straggler, stranded hold) and is skipped, because clamping onto it would self-legalize the corrupt state (live: one stray sell clamped 138 → 115). Rail indices are the orders' LIVE chain price (`resolveLiveOrderLadderPosition`), not stale slot ids. A crossed/over-ceiling rail fails closed (`rail-crossed` / `rail-exceeds-grid`) and keeps the previous value instead of legalizing it; the result then passes the shared `validatePersistedBoundary` gate (with cancel/rotation sources allow-listed), so the rail clamp and the fill re-anchor end in one validator.
64
+ - `deriveRailBoundary` (`dexbot_cow_runtime.ts`, pre-broadcast) clamps the committed boundary to the batch's resulting rails: `maxBuyIdx <= boundary <= minSellIdx - gapSlots - 1`. A fill's counter order is the rail fact, so it decides the boundary; an empty refill hole never outvotes it. Rail membership = the batch's own op destinations + master rail orders on their own side of the planned boundary (BUY at/below, SELL at/above the implied sellStart); a master order parked on the wrong side is a STRAY (refused-commit adoption, SPREAD-GUARD straggler, stranded hold) and is skipped, because clamping onto it would self-legalize the corrupt state (live: one stray sell clamped 138 → 115). Rail indices are the orders' LIVE chain price (`resolveLiveOrderLadderPosition`), not stale slot ids. A crossed/over-ceiling rail fails closed (`rail-crossed` / `rail-exceeds-grid`) and keeps the previous value instead of legalizing it; the result then passes the shared `validatePersistedBoundary` gate (with cancel/rotation sources allow-listed), so the rail clamp and the fill re-anchor end in one validator. The gate accepts a **violation-reducing repair**: a candidate that strands strictly fewer placed orders than the committed boundary is allowed (the fill-driven retreat case), while an equal count stays refused. The comparison uses the validator's own in-band count (`countInBandPlacements` / `boundaryMoveReducesStrands`), never a second stranding predicate.
63
65
 
64
66
  - `INV-COW-007` Boundary hold on guard-skipped refills
65
- - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
67
+ - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits. The hold is scoped to the **promotion direction** (the move advances toward the band holes): a fill-driven retreat moves away from them, so its skipped refills must not pin the old boundary. `resolveRefillSide` supplies the plan's rail side; an unknown side keeps the legacy hold (fail safe).
66
68
  - Edge-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
67
69
  - The hold is intersected with `deriveRailBoundary`: when the batch actually placed a counter order above the committed boundary, the rail clamp advances the boundary (the hold becomes a no-op and the counter stays live). The hold still applies when nothing was placed on the promoted rail. `boundaryHeld` is `effectiveBoundary !== workingBoundary`, so crawl consumption follows the value actually committed.
68
70
  - The hold rides to the commit as `options.boundaryHeld`, which suppresses the pending-crawl clear.
@@ -73,7 +75,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
73
75
  - `INV-COW-008` Owed fill crawls survive unapplied commits
74
76
  - `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, edge slots, and window members — a window that reaches the grid edge is not an edge order, using the same window exclusion every placement picker and `countLiveEdgeOrders` apply.
75
77
  - `_commitWorkingGrid` clears them only when the plan's boundary was actually applied — a held boundary (`boundaryHeld`), a gate-rejected boundary, and a null boundary all leave them owed.
76
- - A window that lands BEHIND the newest real fill is repaired by `reanchorBoundaryFromLastFill` (called from `calculateTargetGrid` right after the derivation): the fill anchors the geometry — `SELL fill at f => boundary ≥ f − gapSlots`, `BUY fill at f => boundary ≤ f − 1` — because a ±1 crawl can never catch up. The anchor index is the current fill batch's EXTREMUM for the fill side (max slot for SELL, min slot for BUY), not the mutable last-processed pivot: a sweep processed in chunks overwrites the pivot per chunk (live: 1366 → 1349 → 1361), and anchoring on a non-extremum leaves the furthest fill's counter order in-band. Prices come from the fill record (the real execution price, `INV-COW-011`) with the slot id as a legacy fallback. Fail-closed preconditions: a pivot whose `lastFillPivotSource` is `fill` (a book seed never anchors; the bot-scoped last-market-fill row is the fallback), on-ladder price within one increment, a post-clamp target that actually puts the fill outside the window, and `validatePersistedBoundary` (a strand refuses the re-anchor). ELIGIBILITY matches the crawl: EDGE-pinned insurance fills never arm the pivot (`recordLastFilledPrices` skips them, shared classifier `collectEdgePinnedFillIds`) and so can never anchor — an edge order is static insurance, not market movement, and an absolute anchor at a rail-edge price would teleport the window there; PARTIAL fills still anchor (real trade) because the fill's OWN PARTIAL residual at the anchor slot is explicitly allow-listed (it is inside the band by construction). Startup/recovery load paths tolerate that pure in-band state (`tolerateTransientStranding`) so a restart does not rebuild the boundary before GAP-EVAC clears the residual. A successful re-anchor is absolute: it consumes the whole pending-crawl snapshot taken at plan time, so no older delta can be applied on top.
78
+ - A window that lands BEHIND the newest real fill is repaired by `reanchorBoundaryFromLastFill` (called from `calculateTargetGrid` right after the derivation): the fill anchors the geometry — `SELL fill at f => boundary ≥ f − gapSlots`, `BUY fill at f => boundary ≤ f − 1` — because a ±1 crawl can never catch up. The anchor index is the current fill batch's EXTREMUM for the fill side (max slot for SELL, min slot for BUY), not the mutable last-processed pivot: a sweep processed in chunks overwrites the pivot per chunk (live: 1366 → 1349 → 1361), and anchoring on a non-extremum leaves the furthest fill's counter order in-band. Prices come from the fill record (the real execution price, `INV-COW-011`) with the slot id as a legacy fallback. Fail-closed preconditions: a pivot whose `lastFillPivotSource` is `fill` (a book seed never anchors; the bot-scoped last-market-fill row is the fallback), on-ladder price within one increment, a post-clamp target that actually puts the fill outside the window, and `validatePersistedBoundary` — a strand refuses the re-anchor unless the candidate strands **strictly fewer** placed orders than the committed boundary (the violation-reducing repair, measured with the validator's own count; an equal count still refuses). ELIGIBILITY matches the crawl: EDGE-pinned insurance fills never arm the pivot (`recordLastFilledPrices` skips them, shared classifier `collectEdgePinnedFillIds`) and so can never anchor — an edge order is static insurance, not market movement, and an absolute anchor at a rail-edge price would teleport the window there; PARTIAL fills still anchor (real trade) because the fill's OWN PARTIAL residual at the anchor slot is explicitly allow-listed (it is inside the band by construction). Startup/recovery load paths tolerate that pure in-band state (`tolerateTransientStranding`) so a restart does not rebuild the boundary before GAP-EVAC clears the residual. A successful re-anchor is absolute: it consumes the whole pending-crawl snapshot taken at plan time, so no older delta can be applied on top.
77
79
  - Consumption is SCOPED to what the derivation applied: `deriveTargetBoundary` returns `consumedCrawlIds` (the owed records whose shift it folded, plus the records it deliberately never counts — current-batch slots, edge-classified slots, malformed records), the plan carries it (`buildSuccessResult` → `CowResult` → `_commitWorkingGrid` options), and `_consumePendingFillCrawls` drops exactly those, logging `Dropped N … kept=M`. A capped fold consumes only the entries it actually applied (same-side prefix up to the applied magnitude), so the remainder stays owed exactly once. `_clearPendingFillCrawls` remains the explicit allowed-loss path (rebuild, rejected snapshot, restart replay) and drops everything.
78
80
  - A commit **without** the wire consumes nothing (a create-only plan never derived a boundary): clearing it would be the old silent-loss bug (2026-10-25: 7 slots 147–153 swept, every record dropped, boundary ending 7 levels behind).
79
81
  - `consumePendingFillCrawls` applies them onto a restored finite boundary; `applyPersistedPendingCrawls` is the shared startup/recovery wrapper used before sync/reconcile; `_clearPendingFillCrawls` drops them when the boundary is re-anchored (grid rebuild via `initializeGrid`, rejected snapshot via `rejectCorruptedGridSnapshot`, persisted snapshot wipe via `AccountOrders.clearGrid`).
@@ -101,6 +103,8 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
101
103
  - A fill record carries the chain execution price (`sync_engine._computeFillTransitionResult` / pass-1 full-fill / pass-2 adoption), computed from paid/received amounts when only the history is available; the slot's generation price is a fallback, never the first choice. The queued-fill pivot refresh (`refreshLastFillPivotFromQueue`) likewise prefers fill economics over the slot price. The slot's identity price is NOT rewritten (`GRID-PRICE-INVARIANT`); only the transient fill/pivot fact uses the chain price.
102
104
  - Gap-evacuation geometry maps an on-chain order's LIVE price onto the genesis ladder (`resolveLiveOrderLadderPosition`) before falling back to `parseSlotIndex(slot.id)`. Detection (`detectGapEvacuationCandidates`), the drain-time validation (`_validatePriceCorrectionEntry`), and the teeth (`_processGapEvacuationTeeth`) all use it, so a refused-commit adoption that leaves an order keyed at an in-rail slot cannot hide an in-band order.
103
105
  - A price mismatch whose live chain price maps inside the gap band queues a cancel-only `gapEvacuation` correction and drops any opposite-kind (plain re-price) entry for the same chain order. Evacuation takes precedence over correcting the order back to a stale slot price.
106
+ - **Stale-stamp refusal vs. forced retreat.** A gap-evacuation rotation is B-stamped with its plan-build boundary/gap and re-proven against the LIVE geometry at execution (`isEvacuationStampStillValid`): a boundary commit landing mid-batch must not grant a bypass for a move that no longer makes grid sense (the 2026-10-30 bid-edge incident). That refusal assumes the live boundary survives the commit. When the live rails ALREADY conflict — `maxBuy > minSell − gap − 1`, i.e. no boundary can host both rails with the band (`liveRailsConflictWithGap`, reached through the single decision point `forcedRetreatJustifiesEvacuation`, which also refuses to override a stamp whose source/dest ids are unparseable — an unprovable stamp is never overridden) — the batch's retreat is forced, the plan's boundary is the only consistent geometry, and refusing the evacuation is what permanently strands the order inside the band (spread collapse: 4-slot band, real spread 1.21% vs 2.0% target). Both the build loop and the final pivot gate therefore keep the evacuation in that case.
107
+ - **Committed-geometry sweep.** Because the in-batch refusal is fail-closed by design, the writer of the stranding must repair it: after a commit, and on every maintenance tick, `scheduleGapEvacRepair` re-derives the in-band set against the COMMITTED geometry (pruning resolved ledger entries WITHOUT counting a new observation — `reconcileGrid` is the cycle's single tick, and counting twice armed the cancel-only teeth in the very cycle whose rotation evacuated the order), queues the cancel-only teeth past the threshold, and schedules a fill-less COW re-plan (rate-limited 60s per bot). A queued cancel-only evacuation whose chain order the SAME batch rotates is held out of the pre-batch correction drain (`splitEvacuationCancelsSupersededByRotations`): the rotation IS the evacuation, and cancelling first destroyed the batch's own source (live: `2 target(s) missing on chain` → structural resync + full grid reload instead of two in-place price updates). Plans are fill-driven, so without this a quiet market never heals a collapsed spread.
104
108
  - The crossing guard's candidate set (`buildCrossingCheckCandidates`) uses the live chain price for master and pending orders, so an emission cannot print onto a live opposite-side order that was adopted at a stale slot price.
105
109
 
106
110
  - `INV-PROJ-001` New projected orders remain virtual
@@ -136,6 +140,46 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
136
140
 
137
141
  ---
138
142
 
143
+ ## Order Lifecycle ([ORDER_LIFECYCLE.md](ORDER_LIFECYCLE.md))
144
+
145
+ Chain existence is answered by ONE record per slot (`modules/order/lifecycle.ts`),
146
+ not by the seven per-site structures that used to disagree
147
+ (`_pendingBroadcasts`, `createUncertain`, `_committedOrderIds`,
148
+ `_orderIdAssignedAt`, `_placedAt`, `_chainSizeAppliedFills`,
149
+ `_lastUnmatchedChainOrders`). Those now exist only as live views onto the record.
150
+
151
+ - `INV-LIFE-001` Unknown is never gone
152
+ - `phase === 'unknown'` (lost receipt, ambiguous read, unparseable chain entry) implies `mayExistOnChain === true` and `isConfirmedGone === false`.
153
+ - Only a chain-observed absence sets `phase === 'gone'`. A consumer must never coerce `unknown` into "absent" via a default.
154
+
155
+ - `INV-LIFE-002` One record per slot
156
+ - A slot is the identity across its order incarnations. A chain-id change (rotation, re-place, adoption) updates the existing record; it must not start a parallel one.
157
+ - Writers funnel through `_applyOrderUpdate` → `_syncLifecycleFromMutation`; no call site maintains its own chain-existence bookkeeping (that includes the stamps: `assignedAt`/`placedAt` are written by the funnel only).
158
+ - The one mutation that does not call `_applyOrderUpdate` is the COW whole-map commit (`_commitWorkingGrid`): it projects every slot of the committed map through the same funnel before swapping, so the primary placement path stamps `placedAt`/`assignedAt` too. Without it the surplus-cancel grace is inert for every COW-created order.
159
+
160
+ - `INV-LIFE-003` One definition per guard
161
+ - Absence decisions ("is this order's absence trustworthy yet?") use `isInFlight()`, read through the slot (`readSlotLifecycle`) so a persisted `createUncertain` marker participates.
162
+ - The committed-but-missing guard uses `isRecentlyCommitted()`.
163
+ - The fresh-id guard uses `isRecentlyAssigned()`.
164
+ - A read site must not re-derive a window from a raw map, and must not consult a subset of `isInFlight()`: that is how four sites ended up with four answers.
165
+
166
+ - `INV-LIFE-004` A LIVE unresolved record is never evicted or downgraded
167
+ - Registry pruning skips `unknown` and `broadcasting` while their uncertainty is inside the bound; past it no decision consults them, so they become evictable (the registry keeps a ceiling).
168
+ - `markIntentIfResolved` likewise refuses to downgrade a live uncertainty, and resolves one whose bound has expired instead of leaving an un-honoured suppression behind.
169
+ - A pending CREATE has two distinct exits: *resolved* (`deletePending` → `intent`) and *abandoned* (`_expirePendingBroadcast` → `unknown`). Collapsing them turns a lost receipt into a clean hole that gets re-CREATEd.
170
+
171
+ - `INV-LIFE-005` Unparseable chain entries make absence unknown, not absent
172
+ - A chain order that was returned but could not be decoded puts its slot's absence in the UNKNOWN bucket (`sync_engine` pass-1 guard 0, mirroring the accounting recovery sweep's `malformedOrderIds`); the slot is not virtualized.
173
+
174
+ - `INV-LIFE-006` Evidence is monotonic; clocks cannot be refreshed for free
175
+ - Within a phase the evidence rank may only rise (`local` < `broadcast-receipt` < `adoption` < `chain-snapshot` < `fill-history`), so a local write cannot overwrite what the chain said.
176
+ - `observedAt` advances only for chain-backed evidence.
177
+ - `recordedAt` (the anchor of the unresolved bound) advances only on a phase change or chain-backed evidence: re-asserting `unknown` is not new information.
178
+
179
+ - `INV-LIFE-007` The unresolved bound is measured from when the uncertainty was RECORDED
180
+ - `isInFlight()` is bounded (2× `PENDING_BROADCAST_TTL_MS`) from `recordedAt`, so a lagging node cannot park the grid and a bot that re-asserts `unknown` every cycle cannot extend its own suppression.
181
+ - An explicit decision (`markIntent`) or chain evidence resolves the phase sooner; age alone never extends it.
182
+
139
183
  ## Sync Engine
140
184
 
141
185
  - `INV-SYNC-001` Drift-refetch for partial fill correctness
@@ -153,8 +197,9 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
153
197
  - The sync engine must treat this as a chain-confirmed empty, not a connection failure.
154
198
 
155
199
  - `INV-SYNC-004` Orphan adoption rejects duplicate price levels
156
- - Pass-2 fallback adoption must check whether an active grid order of the same type already exists at the same price (within `calculatePriceTolerance` using `Math.max(size)`).
157
- - If a duplicate exists, the orphan is NOT adopted; it is pushed to `unmatchedChainOrders` for chain cancel.
200
+ - Pass-2 adoption must check whether an active grid order of the same type already maps to the same ladder level (`chainPriceOnSameLevel` → `pricesOnSameLevel`: the chain price and the grid level resolve to one slot, so equality is by level, not by a tuned band).
201
+ - `calculatePriceTolerance` is NOT the duplicate rule; it survives only inside helpers that need a representable-price tolerance, and the old `findMatchingGridOrderByOpenOrder` matcher is gone (see [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md#the-tolerance-matcher-is-gone)).
202
+ - If a duplicate exists, the orphan is NOT adopted; it is pushed to `unmatchedChainOrders` as `duplicate-price-level` for chain cancel.
158
203
  - Size is irrelevant — any duplicate violates the one-order-per-price-level invariant.
159
204
 
160
205
  - `INV-SYNC-005` Fill queue back-pressure
@@ -183,7 +228,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
183
228
 
184
229
  - `INV-MAINT-001` Pipeline in-flight defers maintenance
185
230
  - When `isPipelineEmpty` returns `isEmpty=false` (batch in-flight, recovery-in-flight, or broadcasting active), `checkSpreadCondition` and divergence corrections must be skipped.
186
- - Dust cancels broadcast directly to chain and are safe to call regardless of pipeline state.
231
+ - Dust cancels mutate the chain, so they take the **exclusive placement region** (`withPlacement('dust-cancel')`) and defer to the next cycle when it is busy or the bot is shutting down — they are NOT "safe regardless of pipeline state". The rotation batch that follows the cancels runs after the region is released and acquires its own lease.
187
232
  - Pipeline signals (`batchInFlight`, `recoveryInFlight`, `broadcasting`) must be passed to `isPipelineEmpty`.
188
233
 
189
234
  - `INV-MAINT-002` Illegal state abort
@@ -262,7 +307,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
262
307
  - SELL placements must use nearest available free slots first (ascending price).
263
308
 
264
309
  - `INV-RECON-006` Fresh-placement cancels are deferred for a grace window
265
- - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written by `recordOrderPlacement` into `manager._placedAt` and tested by `isFreshlyPlacedOrder`.
310
+ - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written by the lifecycle write funnel (and by `recordOrderPlacement` for manager-shaped callers) into `manager._placedAt`, and tested by `isFreshlyPlacedOrder`.
266
311
  - `COWRebalanceEngine.execute` drops the whole slot's action group for a deferred cancel (dropping only the CANCEL would let a paired CREATE fold back into an UPDATE and re-materialize the placement), then re-syncs the deferred slots from master via `workingGrid.syncFromMaster` so the commit does not virtualize a still-live order.
267
312
  - Divergence correction (`applyGridDivergenceCorrections`) applies the same guard after dropping any queued committed-size UPDATE for the not-desired/size-0 slot.
268
313
  - `grid-load`/`grid-init` load contexts are excluded so restarts do not suppress the sweep.
@@ -363,6 +408,20 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
363
408
  - A `get_full_accounts` window capped at the order limit omits the freshest orders (by_account index = seller,id ascending — fresh creates sort last), so absence on a truncated/empty read can never free slots/capital, confirm a cancel, discard a batch, or clear pending-broadcast protection.
364
409
  - All absence decisions use `readOpenOrdersWithMeta`; truncated/empty snapshots defer (keep protection + request structural resync) instead of acting.
365
410
 
411
+ - `INV-BROADCAST-005` One exclusive placement region; one lease-liveness predicate
412
+ - Every chain-mutating path (COW broadcast, reconcile Phase 1+2, correction drain, dust/residual cancel, pool swap) runs inside the exclusive placement region (`modules/order/placement_lock.ts`). The broadcast refcount only defers fills; it is not mutual exclusion.
413
+ - The region is NOT reentrant. Nested work receives the holder's lease and verifies it with `manager.isPlacementLeaseCurrent(lease)` — `isPlacementActive()` is true for ANY holder and must never stand in for ownership.
414
+ - Non-token holders must use `manager.withPlacement()` (single acquire/release contract, bounded wait, shutdown probe). `correctAllPriceMismatches` is the only nested consumer and takes the inherited lease explicitly.
415
+ - Pending-broadcast liveness has ONE policy (`getLivePendingBroadcasts`): TTL, or TTL + a sync completed after the record, or 2× TTL hard cap. Every reader (COW guard, reconcile CREATE, reconcile surplus sweep, crossing candidates, maintenance lightweight-sync gate) uses it.
416
+ - A PLACEMENT-BACKED hung region is torn down by ONE authority: `_clearStalePlacementRegion()` after `PLACEMENT_STALE_CLEAR_MS`, and it also clears that region's stale broadcast refcount atomically. The teardown's refcount clear is sound only because a refcount raised by a placement holder belongs to that same region; a refcount raised OUTSIDE any placement region (the spread-correction pre-broadcast hold in `order/grid.ts`) is not touched by it and is still cleared by its own watchdog. The broadcast watchdog refuses to act while a placement lease is held (so it only clears a refcount leaked without a lease), and the placement watchdog refuses a teardown while a bot-level pipeline counter younger than the bound proves progress.
417
+ - The owner of a region must re-verify its own lease (`isPlacementLeaseCurrent`) before it BROADCASTS a CREATE/UPDATE batch: a watchdog teardown turns the lease into a stale token, and a resumed holder must abort instead of broadcasting unprotected (COW body: `PLACEMENT_LEASE_LOST`; reconcile Phase 1+2: the plan is discarded and the cycle defers). Pure cancel paths are exempt — a cancel carries its own order id and cannot duplicate a CREATE.
418
+
419
+
420
+ - `INV-TIME-001` Every timing window is classified, and self-healing windows are removal targets
421
+ - `modules/timing_policy.ts` classifies every `TIMING` window as `external`, `bound`, `policy` or `self-healing`, each with a rationale; a `self-healing` window must also name the evidence that replaces it.
422
+ - `tests/test_timing_policy.ts` fails on an unclassified window, so the inventory can only shrink by decision.
423
+ - A wait that compensates for our own lost state is a bug with a timer attached; the fix is a lifecycle phase, not patience. See [TIMING_INVENTORY.md](TIMING_INVENTORY.md).
424
+
366
425
  ## Change Policy
367
426
 
368
427
  - Any intentional invariant change must:
@@ -1,7 +1,7 @@
1
1
  # DEXBot vs DEXBot2 — Detailed Comparison Report
2
2
 
3
3
  > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
4
- > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.0).
4
+ > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.1).
5
5
  > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@
36
36
 
37
37
  | Attribute | DEXBot (original) | DEXBot2 |
38
38
  |---|---|---|
39
- | **Release Track** | 1.0.0 | v1.7.0 |
39
+ | **Release Track** | 1.0.0 | v1.7.1 |
40
40
  | **Language** | Python 3.6+ | TypeScript 5.x |
41
41
  | **Status** | Released 1.0.0, unmaintained | Active development |
42
42
  | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -776,13 +776,13 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.7.0 |
779
+ | **Release Track** | 1.0.0 | v1.7.1 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
- | **Last Commit** | May 23, 2020 | 2026-11-02 |
782
- | **Total Commits** | 2281 | 2,468 (current HEAD, v1.7.0 line) |
781
+ | **Last Commit** | May 23, 2020 | 2026-11-04 |
782
+ | **Total Commits** | 2281 | 2,492 (current HEAD, v1.7.1 line) |
783
783
  | **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
784
784
  | **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
785
- | **Test Files** | 16 Python test files | 355 `test_*.ts` files (338 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
785
+ | **Test Files** | 16 Python test files | 367 `test_*.ts` files (350 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
786
786
  | **Documentation** | Sphinx docs + README | 60+ Markdown docs plus Claw skills/references |
787
787
  | **Strategies** | 3 + plugins | 1 |
788
788
  | **Max Concurrent Bots** | Many (one process) | Many (one monolithic process by default; per-bot via `--isolated`/PM2) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.0 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.1 release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,468 commits over ~9 active months
9
+ - **Growth Phase**: 2,492 commits over ~9 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
- - **Stability**: Progression from manual testing to a suite of 341 automated test files
12
- - **Releases**: 151 version entries in the changelog (v0.1.0 to v1.7.0)
11
+ - **Stability**: Progression from manual testing to a suite of 353 automated test files (14 live tests skipped)
12
+ - **Releases**: 152 version entries in the changelog (v0.1.0 to v1.7.1)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
149
149
 
150
150
  ## Version History
151
151
 
152
- Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-02). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,361 (`v0.1.0..HEAD`) and 2,468 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
152
+ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-04). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,385 (`v0.1.0..HEAD`) and 2,492 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
153
153
 
154
154
  | Era | Commits | Theme |
155
155
  |-----|--------:|-------|
@@ -177,11 +177,12 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
177
177
  | v1.6.16 → v1.6.17 | 11 | Last-fill direction guard, placeable-slot spread planning with named stalls, chain-truth funding + fill-anchored boundary re-anchor, owed-crawl consumption, restart auth-before-stop with cleared vault secret, pool-priced LP-share collateral, AMA slowPeriod/slope retune, BTS & per-token supply distribution analyzers |
178
178
  | v1.6.17 → v1.6.18 | 19 | Partial-fill re-anchor recovery (stale-evac skip, residual allow-list, crawl subsumption, rotation-only repair), rail-derived boundary + live fill/chain prices, edge-fill pivot exclusion, guard arity pinning with explicit re-arm, per-slot last-fill exclusion count, CLI `--flag=value` walker, `__test` seam guard, export-surface cleanup |
179
179
  | v1.6.18 → v1.7.0 | 11 | Liquidity depth chart + `dexbot liquid`/`liq`/`liqu`, `dexbot asset` supply distribution shortcut, pool id/pool-token chart targets + shared spawn runner, case-insensitive asset lookup, asset-report chain-request cuts, shared CLI terminal output, orphan-fill attribution + dark-level revive, stale-grid re-buy discipline, pivot clock provenance & read-time TTL |
180
+ | v1.7.0 → v1.7.1 | 22 | One existence record per slot (life-cycle registry, unknown-is-never-gone), typed three-valued broadcast outcome, timing-window policy inventory, reconciliation interleaving fuzzer, one writer per life-cycle clock, serialized placement region with lease re-verification, fill-marker idempotency, forced-retreat gap evacuation + committed-geometry sweep, unknown-gap-geometry fix, replay-safe stranded-boundary repair, stability-ranked node selection + flap scoring, chain-account `<bot>` targets for `credit`/`order`, fee-adjusted pool depth chart with both spreads, atomic branch promotion preflight |
180
181
 
181
182
  ---
182
183
 
183
184
  **Report Originally Generated**: February 19, 2026
184
- **Last Updated**: November 2, 2026
185
- **Total Commits**: 2,468
186
- **Date Range**: December 2, 2025 – November 2, 2026
185
+ **Last Updated**: November 4, 2026
186
+ **Total Commits**: 2,492
187
+ **Date Range**: December 2, 2025 – November 4, 2026
187
188
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -805,4 +805,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
805
805
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
806
806
 
807
807
  ---
808
- *Technical Reference for DEXBot2 v1.7.0 release*
808
+ *Technical Reference for DEXBot2 v1.7.1 release*
@@ -1,7 +1,7 @@
1
1
  # The Grid-Price Invariant
2
2
 
3
3
  Status: **implemented; the emission check is BLOCKING**
4
- Last code-reviewed against the v1.6.13 release baseline `1a1ae60c` (2026-10-11).
4
+ Last code-reviewed against the v1.7.0 release baseline `5644aa3a` (2026-11-02).
5
5
 
6
6
  ## The invariant
7
7