dexbot 1.7.0 → 1.7.2

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 (115) hide show
  1. package/CHANGELOG.md +70 -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 +12 -1
  24. package/dist/modules/account_bots.js +7 -5
  25. package/dist/modules/account_orders.d.ts +12 -0
  26. package/dist/modules/account_orders.js +30 -0
  27. package/dist/modules/bitshares-native/transport.js +24 -6
  28. package/dist/modules/bitshares_client.d.ts +24 -6
  29. package/dist/modules/bitshares_client.js +44 -7
  30. package/dist/modules/bot_settings.d.ts +2 -0
  31. package/dist/modules/constants.d.ts +28 -3
  32. package/dist/modules/constants.js +79 -10
  33. package/dist/modules/dexbot_class.d.ts +23 -6
  34. package/dist/modules/dexbot_class.js +44 -0
  35. package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
  36. package/dist/modules/dexbot_cow_runtime.js +688 -188
  37. package/dist/modules/dexbot_fill_runtime.js +124 -35
  38. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  39. package/dist/modules/dexbot_maintenance_runtime.js +259 -79
  40. package/dist/modules/dexbot_startup_runtime.js +32 -20
  41. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  42. package/dist/modules/dexbot_state_recovery.js +167 -5
  43. package/dist/modules/node_connect_policy.d.ts +8 -1
  44. package/dist/modules/node_connect_policy.js +18 -2
  45. package/dist/modules/node_flap_score.d.ts +87 -0
  46. package/dist/modules/node_flap_score.js +124 -0
  47. package/dist/modules/node_health_cache.d.ts +40 -3
  48. package/dist/modules/node_health_cache.js +66 -20
  49. package/dist/modules/node_manager.d.ts +101 -19
  50. package/dist/modules/node_manager.js +255 -65
  51. package/dist/modules/order/accounting.d.ts +9 -4
  52. package/dist/modules/order/accounting.js +131 -19
  53. package/dist/modules/order/async_lock.d.ts +7 -1
  54. package/dist/modules/order/async_lock.js +7 -1
  55. package/dist/modules/order/export.js +25 -18
  56. package/dist/modules/order/fill_ledger.d.ts +99 -0
  57. package/dist/modules/order/fill_ledger.js +103 -0
  58. package/dist/modules/order/format.d.ts +24 -10
  59. package/dist/modules/order/format.js +30 -10
  60. package/dist/modules/order/grid.d.ts +75 -18
  61. package/dist/modules/order/grid.js +289 -72
  62. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  63. package/dist/modules/order/grid_reconcile.js +333 -210
  64. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  65. package/dist/modules/order/grid_reconcile_internal.js +223 -91
  66. package/dist/modules/order/index.d.ts +18 -5
  67. package/dist/modules/order/index.js +5 -5
  68. package/dist/modules/order/lifecycle.d.ts +353 -0
  69. package/dist/modules/order/lifecycle.js +1109 -0
  70. package/dist/modules/order/manager.d.ts +277 -20
  71. package/dist/modules/order/manager.js +680 -64
  72. package/dist/modules/order/placement_lock.d.ts +102 -0
  73. package/dist/modules/order/placement_lock.js +222 -0
  74. package/dist/modules/order/strategy.js +13 -1
  75. package/dist/modules/order/sync_engine.d.ts +74 -114
  76. package/dist/modules/order/sync_engine.js +254 -198
  77. package/dist/modules/order/utils/math.d.ts +29 -4
  78. package/dist/modules/order/utils/math.js +61 -4
  79. package/dist/modules/order/utils/order.d.ts +106 -37
  80. package/dist/modules/order/utils/order.js +256 -81
  81. package/dist/modules/order/utils/system.d.ts +99 -6
  82. package/dist/modules/order/utils/system.js +249 -35
  83. package/dist/modules/order/utils/validate.d.ts +7 -1
  84. package/dist/modules/order/utils/validate.js +48 -2
  85. package/dist/modules/outcome.d.ts +54 -0
  86. package/dist/modules/outcome.js +51 -0
  87. package/dist/modules/settings_merge.d.ts +4 -0
  88. package/dist/modules/settings_merge.js +9 -0
  89. package/dist/modules/timing_policy.d.ts +82 -0
  90. package/dist/modules/timing_policy.js +244 -0
  91. package/dist/modules/types.d.ts +149 -22
  92. package/dist/scripts/analyze-credit.js +54 -17
  93. package/dist/scripts/analyze-orders.d.ts +4 -2
  94. package/dist/scripts/analyze-orders.js +113 -34
  95. package/dist/scripts/chart_targets.js +11 -15
  96. package/dist/scripts/test-credit-renewal.js +12 -5
  97. package/docs/COW_INVARIANTS.md +71 -8
  98. package/docs/DEXBOT_COMPARISON.md +6 -6
  99. package/docs/EVOLUTION.md +10 -8
  100. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  101. package/docs/GRID_PRICE_INVARIANT.md +1 -1
  102. package/docs/GRID_RECONCILE.md +18 -13
  103. package/docs/LOGGING.md +25 -1
  104. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
  105. package/docs/README.md +23 -2
  106. package/docs/WORKFLOW.md +9 -3
  107. package/docs/architecture.md +68 -13
  108. package/docs/developer_guide.md +25 -8
  109. package/modules/README.md +6 -0
  110. package/package.json +3 -3
  111. package/scripts/README.md +16 -0
  112. package/scripts/pdev.sh +14 -1
  113. package/scripts/pmain.sh +23 -8
  114. package/scripts/ptest.sh +7 -0
  115. package/tests/README.md +30 -1
@@ -4,7 +4,7 @@
4
4
  * Extracted from grid_reconcile.ts for file-size management.
5
5
  * All helpers are prefixed with _ and are NOT part of the public API.
6
6
  */
7
- import type { OrderManagerLike, ManagedOrder, ChainOrder, ParsedChainOrder, ChainOrdersLike, LoggerLike, UnknownRecord, StartupCreatePlan, StartupUpdatePlan, StartupCancelPlan, OrderType } from '../types.js';
7
+ import type { OrderManagerLike, ManagedOrder, ChainOrder, ParsedChainOrder, ChainOrdersLike, AssetPair, LoggerLike, UnknownRecord, StartupCreatePlan, StartupUpdatePlan, StartupCancelPlan, OrderType } from '../types.js';
8
8
  interface PreparedStartupUpdate {
9
9
  plan: StartupUpdatePlan;
10
10
  chainOrderId: string;
@@ -149,6 +149,42 @@ declare function _executePlannedStartupCreates({ createPlans, chainOrders, accou
149
149
  manager: OrderManagerLike;
150
150
  dryRun: boolean;
151
151
  }): Promise<Set<string>>;
152
+ /**
153
+ * Partition the unmatched chain orders of one side into an UPDATE pool and a
154
+ * dust-surplus CANCEL pool.
155
+ *
156
+ * Policy (single implementation used by the startup reconcile):
157
+ * - dust = size below the per-slot single-dust threshold (same definition the
158
+ * partial-dust health check uses);
159
+ * - when the NON-dust orders alone can cover every slot this side needs, dust
160
+ * orders are surplus -> CANCEL only. They are never grown into a full slot
161
+ * and no replacement is created for them (there are already enough real
162
+ * orders to cover the target);
163
+ * - otherwise dust stays eligible to fill the remaining slots.
164
+ *
165
+ * Extracted so the policy is unit-testable and cannot drift between the
166
+ * startup reconcile and any future caller.
167
+ * @param {Object} input
168
+ * @param {Array} input.sortedUnmatched - Unmatched chain orders, pre-sorted by price
169
+ * @param {Array} input.desiredSlots - Target slots this side wants to activate
170
+ * @param {Object} input.assets - Asset metadata (precisions)
171
+ * @param {number} [input.dustThresholdPercent] - Dust threshold percentage
172
+ * @returns {Object} { updatePool, dustSurplus, nonDustCount, dustCount, referenceIdeal, dustThreshold, enoughNonDust }
173
+ */
174
+ declare function _classifyStartupOrderReuse({ sortedUnmatched, desiredSlots, assets, dustThresholdPercent, }: {
175
+ sortedUnmatched: ChainOrder[];
176
+ desiredSlots: ManagedOrder[];
177
+ assets: AssetPair;
178
+ dustThresholdPercent?: number;
179
+ }): {
180
+ updatePool: ChainOrder[];
181
+ dustSurplus: ChainOrder[];
182
+ nonDustCount: number;
183
+ dustCount: number;
184
+ referenceIdeal: number;
185
+ dustThreshold: number;
186
+ enoughNonDust: boolean;
187
+ };
152
188
  declare function _reconcileStartupSide({ orderType, targetCount, chainSideOrders, unmatchedSideOrders, manager, chainOrders, account, privateKey, dryRun, plannedCreates, plannedUpdates, plannedCancels, planOnly, }: {
153
189
  orderType: OrderType;
154
190
  targetCount: number;
@@ -166,5 +202,5 @@ declare function _reconcileStartupSide({ orderType, targetCount, chainSideOrders
166
202
  }): Promise<{
167
203
  chainCount: number;
168
204
  }>;
169
- export { _countActiveOnGrid, _pickVirtualSlotsToActivate, _createOrderFromGrid, _prepareStartupUpdatePlan, _cancelChainOrder, _recoverStartupSyncFailure, _refreshStartupUpdatePlans, _executeStartupUpdateBatch, _executeStartupSequentialUpdateFallback, _executeStartupCreateGroupBatch, _createStartupOrderWithHandling, _executePlannedStartupCreates, _reconcileStartupSide };
205
+ export { _countActiveOnGrid, _pickVirtualSlotsToActivate, _createOrderFromGrid, _prepareStartupUpdatePlan, _cancelChainOrder, _recoverStartupSyncFailure, _refreshStartupUpdatePlans, _executeStartupUpdateBatch, _executeStartupSequentialUpdateFallback, _executeStartupCreateGroupBatch, _createStartupOrderWithHandling, _executePlannedStartupCreates, _reconcileStartupSide, _classifyStartupOrderReuse };
170
206
  //# sourceMappingURL=grid_reconcile_internal.d.ts.map
@@ -6,8 +6,8 @@
6
6
  */
7
7
  import { ORDER_TYPES, ORDER_STATES, TIMING, BTS_PRECISION } from '../constants.js';
8
8
  import { readOpenOrdersGuarded } from '../chain_orders.js';
9
- import { getMinOrderSize, getAssetFees, getAssetFeesSafe, blockchainToFloat, findCrossedOrder, resolveGapBand, isSlotInRail, pricesOnSameLevel, pricesWithinHalfStep, sameGridLevel } from './utils/math.js';
10
- import { isOrderPlaced, parseChainOrder, buildCreateOrderArgs, buildOutsideInPairGroups, extractBatchOperationResults, chainOrderMatchesSlotWithTolerance, buildCrossingCheckCandidates, isCrossingCheckCandidate, getSideBudget, calculateBudgetedSizes, getCoreOrdersTotal, convertToSpreadPlaceholder, isOrderGoneErrorMessage, clearDuplicateOrphanDetection, resolveEdgeCount, resolveLiveEdgeAnchorPrice, edgeOrderIdSet, compareEdge, reportGridPriceInvariant, liveWindowIdSet } from './utils/order.js';
9
+ import { getMinOrderSize, getSingleDustThreshold, getAssetFees, getAssetFeesSafe, blockchainToFloat, findCrossedOrder, resolveGapBand, resolveGapSlots, isSlotInRail, pricesOnSameLevel, pricesWithinHalfStep, sameGridLevel } from './utils/math.js';
10
+ import { isOrderPlaced, parseChainOrder, buildCreateOrderArgs, buildOutsideInPairGroups, extractBatchOperationResults, chainOrderMatchesSlotWithTolerance, buildCrossingCheckCandidates, isCrossingCheckCandidate, getSideBudget, calculateBudgetedSizes, getCoreOrdersTotal, convertToSpreadPlaceholder, isOrderGoneErrorMessage, clearDuplicateOrphanDetection, resolveEdgeCount, resolveLiveEdgeAnchorPrice, edgeOrderIdSet, compareEdge, reportGridPriceInvariant, liveWindowIdSet, getLivePendingBroadcasts } from './utils/order.js';
11
11
  import { parseSlotIndex } from './utils/slot.js';
12
12
  import { resolveAccountRef, isLastFillPlacementBlocked, hasUnsettledFills } from './utils/system.js';
13
13
  import * as Format from './format.js';
@@ -490,6 +490,45 @@ async function _createOrderFromGrid({ chainOrders, account, privateKey, manager,
490
490
  manager.logger?.log?.(`[_createOrderFromGrid] SKIP: Slot ${gridOrder.id} already has orderId ${currentSlot.orderId}`, 'warn');
491
491
  return null;
492
492
  }
493
+ // PENDING-BROADCAST GUARD: an earlier uncertain CREATE for this slot may
494
+ // already be live on chain but not yet adopted. The COW pre-broadcast guard
495
+ // blocks the whole CREATE batch for this case; the reconcile/startup path
496
+ // must not re-create the same slot OR the same price level either (same
497
+ // duplicate class).
498
+ //
499
+ // Liveness comes from the shared authority (`getLivePendingBroadcasts`), so
500
+ // this path cannot disagree with the COW guard about what is expired. It
501
+ // checks BOTH the slot id and the price level: a rebuild re-maps a price
502
+ // onto a different slot id, and reconcile is exactly the rebuild path — so
503
+ // a slot-id-only check would miss the entry the COW guard was written to
504
+ // catch. Placement is held and the chain snapshot was just re-read, so a
505
+ // live entry here is authoritative.
506
+ {
507
+ const pendingEntries = getLivePendingBroadcasts(manager);
508
+ for (const pending of pendingEntries) {
509
+ const slotId = pending?.slotId ?? pending?.orderId ?? pending?.order?.id;
510
+ if (slotId == null || String(slotId) !== String(gridOrder.id))
511
+ continue;
512
+ manager.logger?.log?.(`[_createOrderFromGrid] SKIP (PENDING-BROADCAST): Create for ${gridOrder.id} at ` +
513
+ `${Format.formatPrice6(Number(gridOrder.price))} may already be live from an uncertain broadcast; ` +
514
+ `waiting for recovery/adoption instead of duplicating it`, 'warn');
515
+ return null;
516
+ }
517
+ for (const pending of pendingEntries) {
518
+ const pendingPrice = Number(pending?.order?.price);
519
+ if (!Number.isFinite(pendingPrice) || pendingPrice <= 0)
520
+ continue;
521
+ const pendingType = pending?.orderType ?? pending?.order?.type;
522
+ if (pendingType && gridOrder.type && pendingType !== gridOrder.type)
523
+ continue;
524
+ if (!pricesOnSameLevel(pendingPrice, Number(pending?.order?.size) || 0, pendingType, Number(gridOrder.price), Number(gridOrder.size) || 0, gridOrder.type, manager.assets, manager.config?.incrementPercent))
525
+ continue;
526
+ manager.logger?.log?.(`[_createOrderFromGrid] SKIP (PENDING-BROADCAST): Create for ${gridOrder.id} at ` +
527
+ `${Format.formatPrice6(Number(gridOrder.price))} would duplicate the price level of an uncertain ` +
528
+ `CREATE for slot ${String(pending?.slotId ?? '?')}; waiting for recovery/adoption`, 'warn');
529
+ return null;
530
+ }
531
+ }
493
532
  const createPrice = gridOrder.price;
494
533
  // CROSSING-PLACEMENT GUARD: a create must not cross an opposite-side
495
534
  // live order (master, unmatched orphan, or pending broadcast) — see computePlacementCrossing.
@@ -1462,6 +1501,53 @@ async function _executePlannedStartupCreates({ createPlans, chainOrders, account
1462
1501
  `across ${groups.length} group(s)${failedCount > 0 ? `, ${failedCount} failed/skipped (see error logs)` : ''}`, failedCount > 0 ? 'warn' : 'info');
1463
1502
  return createdOrderIds;
1464
1503
  }
1504
+ /**
1505
+ * Partition the unmatched chain orders of one side into an UPDATE pool and a
1506
+ * dust-surplus CANCEL pool.
1507
+ *
1508
+ * Policy (single implementation used by the startup reconcile):
1509
+ * - dust = size below the per-slot single-dust threshold (same definition the
1510
+ * partial-dust health check uses);
1511
+ * - when the NON-dust orders alone can cover every slot this side needs, dust
1512
+ * orders are surplus -> CANCEL only. They are never grown into a full slot
1513
+ * and no replacement is created for them (there are already enough real
1514
+ * orders to cover the target);
1515
+ * - otherwise dust stays eligible to fill the remaining slots.
1516
+ *
1517
+ * Extracted so the policy is unit-testable and cannot drift between the
1518
+ * startup reconcile and any future caller.
1519
+ * @param {Object} input
1520
+ * @param {Array} input.sortedUnmatched - Unmatched chain orders, pre-sorted by price
1521
+ * @param {Array} input.desiredSlots - Target slots this side wants to activate
1522
+ * @param {Object} input.assets - Asset metadata (precisions)
1523
+ * @param {number} [input.dustThresholdPercent] - Dust threshold percentage
1524
+ * @returns {Object} { updatePool, dustSurplus, nonDustCount, dustCount, referenceIdeal, dustThreshold, enoughNonDust }
1525
+ */
1526
+ function _classifyStartupOrderReuse({ sortedUnmatched, desiredSlots, assets, dustThresholdPercent, }) {
1527
+ const referenceIdeal = desiredSlots.length > 0
1528
+ ? desiredSlots.reduce((sum, slot) => sum + (Number(slot?.size) || 0), 0) / desiredSlots.length
1529
+ : 0;
1530
+ const dustThreshold = getSingleDustThreshold(referenceIdeal, dustThresholdPercent);
1531
+ const isDustOrder = (chainOrder) => {
1532
+ if (!(dustThreshold > 0))
1533
+ return false;
1534
+ const parsed = parseChainOrder(chainOrder, assets);
1535
+ const size = Number(parsed?.size ?? 0);
1536
+ return size > 0 && size < dustThreshold;
1537
+ };
1538
+ const nonDustUnmatched = sortedUnmatched.filter((chainOrder) => !isDustOrder(chainOrder));
1539
+ const dustUnmatched = sortedUnmatched.filter((chainOrder) => isDustOrder(chainOrder));
1540
+ const enoughNonDust = desiredSlots.length > 0 && nonDustUnmatched.length >= desiredSlots.length;
1541
+ return {
1542
+ updatePool: enoughNonDust ? nonDustUnmatched : sortedUnmatched,
1543
+ dustSurplus: enoughNonDust ? dustUnmatched : [],
1544
+ nonDustCount: nonDustUnmatched.length,
1545
+ dustCount: dustUnmatched.length,
1546
+ referenceIdeal,
1547
+ dustThreshold,
1548
+ enoughNonDust,
1549
+ };
1550
+ }
1465
1551
  async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders, unmatchedSideOrders, manager, chainOrders, account, privateKey, dryRun, plannedCreates, plannedUpdates, plannedCancels, planOnly = false, }) {
1466
1552
  const logger = manager?.logger;
1467
1553
  const sideUpper = orderType === ORDER_TYPES.SELL ? 'SELL' : 'BUY';
@@ -1501,7 +1587,19 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1501
1587
  desiredSlots = [...desiredSlots.slice(0, keepCount), ...freshEdge];
1502
1588
  }
1503
1589
  const sortedUnmatched = unmatchedSideOrders.slice(0).sort(sortUpdateComparator);
1504
- const updateCount = Math.min(sortedUnmatched.length, desiredSlots.length);
1590
+ const classifiedReuse = _classifyStartupOrderReuse({
1591
+ sortedUnmatched,
1592
+ desiredSlots,
1593
+ assets: manager.assets,
1594
+ dustThresholdPercent: manager.config?.gridLimits?.PARTIAL_DUST_THRESHOLD_PERCENTAGE,
1595
+ });
1596
+ // Only the Phase-1 (planOnly) caller can execute cancels. A non-planOnly
1597
+ // caller must keep every order eligible for update rather than silently
1598
+ // dropping dust from both the update pool and the cancel queue.
1599
+ const updatePool = planOnly ? classifiedReuse.updatePool : sortedUnmatched;
1600
+ const dustSurplus = planOnly ? classifiedReuse.dustSurplus : [];
1601
+ const nonDustCount = classifiedReuse.nonDustCount;
1602
+ const updateCount = Math.min(updatePool.length, desiredSlots.length);
1505
1603
  let cancelledIndex = null;
1506
1604
  let projectedSideBalance = Number(manager.accountTotals?.[balanceKey] || 0);
1507
1605
  // Vacated-rail-slot tracking (Phase 4, vacate+create atomic): a re-map
@@ -1518,16 +1616,17 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1518
1616
  const refillCandidates = [];
1519
1617
  const planVacatedRailRefill = (chainOrder, parsedChain) => {
1520
1618
  const boundary = manager.boundaryIdx;
1521
- const gapSlots = manager._gapSlots;
1619
+ // Geometry comes from the single source of truth (resolveGapSlots:
1620
+ // `_gapSlots` when published, config-derived otherwise). Reading the raw
1621
+ // field here made an unpublished `_gapSlots` silently disable the refill
1622
+ // while every other classify site derived a valid band.
1623
+ const gapSlots = resolveGapSlots(manager);
1522
1624
  // Explicit null/undefined/'' guard BEFORE Number(): Number(null) === 0
1523
1625
  // is finite and would defeat this bail-out, running the refill scan on
1524
- // a bogus boundary 0 (and a null gapSlots would default to 0 through
1525
- // getSellStartIdx).
1626
+ // a bogus boundary 0.
1526
1627
  if (boundary === null || boundary === undefined || boundary === '')
1527
1628
  return;
1528
- if (gapSlots === null || gapSlots === undefined || gapSlots === '')
1529
- return;
1530
- if (!Number.isFinite(Number(boundary)) || !Number.isFinite(Number(gapSlots)))
1629
+ if (!Number.isFinite(Number(boundary)))
1531
1630
  return;
1532
1631
  const chainPrice = parsedChain?.price;
1533
1632
  if (!Number.isFinite(Number(chainPrice)))
@@ -1573,7 +1672,7 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1573
1672
  account,
1574
1673
  privateKey,
1575
1674
  manager,
1576
- unmatchedOrders: sortedUnmatched,
1675
+ unmatchedOrders: updatePool,
1577
1676
  updateCount,
1578
1677
  orderType,
1579
1678
  dryRun,
@@ -1588,7 +1687,7 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1588
1687
  releaseUntrackedFunds: true,
1589
1688
  orderType,
1590
1689
  boundaryIdx: manager?.boundaryIdx,
1591
- gapSlots: manager?._gapSlots,
1690
+ gapSlots: resolveGapSlots(manager),
1592
1691
  });
1593
1692
  }
1594
1693
  }
@@ -1596,7 +1695,7 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1596
1695
  for (let i = 0; i < updateCount; i++) {
1597
1696
  if (cancelledIndex !== null && i === cancelledIndex)
1598
1697
  continue;
1599
- const chainOrder = sortedUnmatched[i];
1698
+ const chainOrder = updatePool[i];
1600
1699
  const gridOrder = desiredSlots[i];
1601
1700
  const gridSize = Number(gridOrder.size) || 0;
1602
1701
  const parsedChain = parseChainOrder(chainOrder, manager.assets);
@@ -1652,7 +1751,29 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1652
1751
  },
1653
1752
  });
1654
1753
  }
1655
- const processedUnmatched = sortedUnmatched.slice(updateCount);
1754
+ const processedUnmatched = updatePool.slice(updateCount);
1755
+ // Queue the dust-surplus cancels after the update plans. Phase 2 always runs
1756
+ // cancels before creates/updates, so these can never be paired into a slot.
1757
+ // planOnly is the Phase-1 contract; the actual broadcast happens in Phase 2.
1758
+ let dustCancelledCount = 0;
1759
+ if (planOnly && dustSurplus.length > 0) {
1760
+ const alreadyPlanned = new Set(plannedCancels.map((plan) => String(plan.chainOrderId)));
1761
+ for (const dustOrder of dustSurplus) {
1762
+ if (alreadyPlanned.has(String(dustOrder.id)))
1763
+ continue;
1764
+ plannedCancels.push({
1765
+ chainOrderId: dustOrder.id,
1766
+ chainOrderObj: dustOrder,
1767
+ releaseUntrackedFunds: true,
1768
+ orderType,
1769
+ boundaryIdx: manager?.boundaryIdx,
1770
+ gapSlots: resolveGapSlots(manager),
1771
+ });
1772
+ dustCancelledCount++;
1773
+ logger?.log?.(`Startup: Cancelling ${sideUpper} dust order ${dustOrder.id} ` +
1774
+ `(${nonDustCount} non-dust order(s) already cover ${desiredSlots.length} needed slot(s); not pricing it into a full-size slot)`, 'info');
1775
+ }
1776
+ }
1656
1777
  // Slot-N gated chain count: fork-kept shelf/manual orders (non-slot-N
1657
1778
  // grid ids, e.g. deep-*) sit outside window accounting — same gate as
1658
1779
  // _countActiveOnGrid and matched-excess candidates (issue #27 follow-up).
@@ -1671,15 +1792,35 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1671
1792
  }
1672
1793
  }
1673
1794
  catch { /* fail-open: keep unfiltered count */ }
1795
+ // Dust-surplus cancels are already queued above, so the remaining chain
1796
+ // count must exclude them. Use the ACTUALLY queued count, not
1797
+ // dustSurplus.length: the alreadyPlanned guard can skip a dust order that
1798
+ // is already in plannedCancels, and subtracting it twice would fabricate
1799
+ // a shortfall (or over-cancel a healthy matched order). Without this
1800
+ // adjustment `createCount` would over-count (no create for the freed level)
1801
+ // and `cancelCount` would double-count the dust as excess.
1802
+ chainCount = Math.max(0, chainCount - dustCancelledCount);
1674
1803
  const createCount = Math.max(0, targetCount - chainCount);
1675
1804
  const remainingSlots = desiredSlots.slice(updateCount);
1676
- // UNSETTLED-FILL GATE: while fills are queued, draining, in flight, or
1677
- // owed a crawl, the master still treats filled slots as ACTIVE and the
1678
- // boundary has not crawled for them. Any window top-up derived from that
1679
- // geometry refills the EXPENSIVE end of the rail — the live incident
1805
+ // UNSETTLED-FILL GATE: while fills are draining, in flight, or owed a
1806
+ // crawl, the master still treats filled slots as ACTIVE and the boundary
1807
+ // has not crawled for them. Any window top-up derived from that geometry
1808
+ // refills the EXPENSIVE end of the rail — the live incident
1680
1809
  // (12s of buys at 1282.78 -> 1310.04 while the market was ~1280). Defer
1681
1810
  // the top-up to the cycle after the fills (and their crawl) are committed;
1682
1811
  // 1:1 repairs (cancelled-slot replacement, vacated-rail refill) still run.
1812
+ //
1813
+ // SCOPE: a bare manager exposes only MANAGER-level state here
1814
+ // (`_pendingFillCrawls`, `_fillBatchInFlight`). The bot-level queue
1815
+ // (`_incomingFillQueue`) and the deferred-drain flag
1816
+ // (`_deferredFillsPending`) are invisible from this source, so "queued" is
1817
+ // covered by the CALLER's gate, not by this one. The startup and
1818
+ // targeted-sync callers drain fills before they reconcile (the bootstrap
1819
+ // consumer / _syncOpenOrdersAndProcessFills); the rebuild caller
1820
+ // (recalculateGrid) has no bot and relies on the structural-rebuild
1821
+ // bracket. That leaves only a fill arriving during this reconcile's chain
1822
+ // read. Widening it belongs at a caller that owns the bot
1823
+ // (docs/FILL_PIPELINE.md B2) — not a second counter here.
1683
1824
  const unsettled = hasUnsettledFills(manager);
1684
1825
  if (unsettled.unsettled && createCount > 0) {
1685
1826
  logger?.log?.(`Startup: Deferring ${Math.min(createCount, remainingSlots.length)} ${sideUpper} window top-up create(s): ` +
@@ -1766,94 +1907,85 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1766
1907
  return fa - fb;
1767
1908
  });
1768
1909
  }
1910
+ // ONE SELECTION, TWO SINKS. The planOnly and inline branches used to walk
1911
+ // the same two ordered lists with duplicated (and drifting) conditions —
1912
+ // the "plan/execute parity" bug class. Selection happens once here; a
1913
+ // planOnly call records the list for Phase 2, an inline call executes it.
1914
+ // Priority is identical either way: unmatched orphans first (untracked
1915
+ // funds), then matched surplus (funds stay tracked on the grid slot), and
1916
+ // edge order slots last (static insurance, already sorted above).
1917
+ const excessGapSlots = resolveGapSlots(manager);
1918
+ const excessPlans = [];
1919
+ for (const x of parsedUnmatched) {
1920
+ if (excessPlans.length >= cancelCount)
1921
+ break;
1922
+ excessPlans.push({
1923
+ chainOrderId: x.chain.id,
1924
+ chainOrderObj: x.chain,
1925
+ releaseUntrackedFunds: true,
1926
+ orderType,
1927
+ boundaryIdx: manager?.boundaryIdx,
1928
+ gapSlots: excessGapSlots,
1929
+ });
1930
+ }
1931
+ // Matched excess must be PLANNED too, not only executed (issue #27
1932
+ // follow-up): startup reconcile always runs planOnly, and on a
1933
+ // fully-placed grid every chain order is matched — parsedUnmatched is
1934
+ // empty, so the surplus lived entirely on matched slots and was silently
1935
+ // dropped while the inline branch kept cancelling it. Nothing ever
1936
+ // created the vacancy, and a fully-placed grid could never converge to
1937
+ // its additive window+edge target (live 12 vs target 8 across restarts).
1938
+ for (const o of matchedExcess) {
1939
+ if (excessPlans.length >= cancelCount)
1940
+ break;
1941
+ if (!o.orderId)
1942
+ continue;
1943
+ excessPlans.push({
1944
+ chainOrderId: o.orderId,
1945
+ chainOrderObj: o,
1946
+ gridOrderId: o.id,
1947
+ gridOrder: { ...o },
1948
+ orderType,
1949
+ boundaryIdx: manager?.boundaryIdx,
1950
+ gapSlots: excessGapSlots,
1951
+ // Matched-slot funds are tracked on the grid slot; only unmatched
1952
+ // orphans release untracked funds.
1953
+ });
1954
+ }
1769
1955
  if (planOnly) {
1770
- // In planOnly mode, record the cancellations for Phase 2 execution.
1771
- // This prevents blockchain I/O inside _gridLock (Level 3).
1772
- if (cancelCount > 0) {
1773
- logger?.log?.(`Startup: ${sideUpper} excess ${cancelCount} order(s) queued for cancellation (Phase 2)`, 'info');
1774
- for (const x of parsedUnmatched) {
1775
- if (cancelCount <= 0)
1776
- break;
1777
- plannedCancels.push({
1778
- chainOrderId: x.chain.id,
1779
- chainOrderObj: x.chain,
1780
- releaseUntrackedFunds: true,
1781
- orderType,
1782
- boundaryIdx: manager?.boundaryIdx,
1783
- gapSlots: manager?._gapSlots,
1784
- });
1785
- cancelCount--;
1786
- }
1956
+ // Phase-1 contract: record the cancellations for Phase 2 execution so
1957
+ // no blockchain I/O runs inside _gridLock (Level 3).
1958
+ if (excessPlans.length > 0) {
1959
+ logger?.log?.(`Startup: ${sideUpper} excess ${excessPlans.length} order(s) queued for cancellation (Phase 2)`, 'info');
1787
1960
  }
1788
- // Matched excess must be PLANNED too, not only executed (issue #27
1789
- // follow-up): startup reconcile always runs planOnly, and on a
1790
- // fully-placed grid every chain order is matched — parsedUnmatched
1791
- // is empty, so the surplus lived entirely on matched slots and was
1792
- // silently dropped here while the execute branch kept cancelling
1793
- // it. Nothing ever created the vacancy, and a fully-placed grid
1794
- // could never converge to its additive window+edge target (live
1795
- // 12 vs target 8 sat static across every restart). Same priority
1796
- // as the execute branch: unmatched first (above), matched after,
1797
- // edge order last (matchedExcess ordering).
1798
- for (const o of matchedExcess) {
1799
- if (cancelCount <= 0)
1800
- break;
1801
- if (!o.orderId)
1802
- continue;
1803
- logger?.log?.(`Startup: ${sideUpper} excess matched ${o.orderId} (grid ${o.id}) queued for cancellation (Phase 2)`, 'warn');
1804
- plannedCancels.push({
1805
- chainOrderId: o.orderId,
1806
- chainOrderObj: o,
1807
- gridOrderId: o.id,
1808
- gridOrder: { ...o },
1809
- orderType,
1810
- boundaryIdx: manager?.boundaryIdx,
1811
- gapSlots: manager?._gapSlots,
1812
- // Matched-slot funds are tracked on the grid slot; only
1813
- // unmatched orphans release untracked funds (mirrors the
1814
- // execute branch, which passes no release flag here).
1815
- });
1816
- cancelCount--;
1961
+ for (const plan of excessPlans) {
1962
+ if (plan.gridOrderId) {
1963
+ logger?.log?.(`Startup: ${sideUpper} excess matched ${plan.chainOrderId} (grid ${plan.gridOrderId}) queued for cancellation (Phase 2)`, 'warn');
1964
+ }
1965
+ plannedCancels.push(plan);
1817
1966
  }
1818
1967
  }
1819
1968
  else {
1820
- for (const x of parsedUnmatched) {
1821
- if (cancelCount <= 0)
1822
- break;
1823
- logger?.log?.(`Startup: Cancelling excess ${sideUpper} chain order ${x.chain.id}`, 'info');
1969
+ for (const plan of excessPlans) {
1970
+ const label = plan.gridOrderId
1971
+ ? `excess matched ${sideUpper} ${plan.chainOrderId} (grid ${plan.gridOrderId})`
1972
+ : `excess ${sideUpper} chain order ${plan.chainOrderId}`;
1973
+ logger?.log?.(`Startup: Cancelling ${label}`, plan.gridOrderId ? 'warn' : 'info');
1824
1974
  try {
1825
1975
  await _cancelChainOrder({
1826
1976
  chainOrders,
1827
1977
  account,
1828
1978
  privateKey,
1829
1979
  manager,
1830
- chainOrderId: x.chain.id,
1831
- chainOrderObj: x.chain,
1832
- releaseUntrackedFunds: true,
1980
+ chainOrderId: plan.chainOrderId,
1981
+ chainOrderObj: plan.chainOrderObj,
1982
+ releaseUntrackedFunds: plan.releaseUntrackedFunds === true,
1833
1983
  dryRun,
1834
1984
  });
1835
- logger?.log?.(`Startup: Successfully cancelled excess ${sideUpper} order ${x.chain.id}`, 'info');
1836
- cancelCount--;
1985
+ logger?.log?.(`Startup: Successfully cancelled ${label}`, 'info');
1837
1986
  }
1838
1987
  catch (err) {
1839
- logger?.log?.(`Startup: Failed to cancel ${sideUpper} ${x.chain.id}: ${getErrorMessage(err)}`, 'error');
1840
- }
1841
- }
1842
- if (cancelCount > 0) {
1843
- for (const o of matchedExcess) {
1844
- if (cancelCount <= 0)
1845
- break;
1846
- if (!o.orderId)
1847
- continue;
1848
- logger?.log?.(`Startup: Cancelling excess matched ${sideUpper} ${o.orderId} (grid ${o.id})`, 'warn');
1849
- try {
1850
- await _cancelChainOrder({ chainOrders, account, privateKey, manager, chainOrderId: o.orderId, dryRun, chainOrderObj: null });
1851
- logger?.log?.(`Startup: Successfully cancelled excess matched ${sideUpper} order ${o.orderId} (grid ${o.id})`, 'info');
1852
- cancelCount--;
1853
- }
1854
- catch (err) {
1855
- logger?.log?.(`Startup: Failed to cancel matched ${sideUpper} ${o.orderId}: ${getErrorMessage(err)}`, 'error');
1856
- }
1988
+ logger?.log?.(`Startup: Failed to cancel ${label}: ${getErrorMessage(err)}`, 'error');
1857
1989
  }
1858
1990
  }
1859
1991
  }
@@ -1862,5 +1994,5 @@ async function _reconcileStartupSide({ orderType, targetCount, chainSideOrders,
1862
1994
  chainCount,
1863
1995
  };
1864
1996
  }
1865
- export { _countActiveOnGrid, _pickVirtualSlotsToActivate, _createOrderFromGrid, _prepareStartupUpdatePlan, _cancelChainOrder, _recoverStartupSyncFailure, _refreshStartupUpdatePlans, _executeStartupUpdateBatch, _executeStartupSequentialUpdateFallback, _executeStartupCreateGroupBatch, _createStartupOrderWithHandling, _executePlannedStartupCreates, _reconcileStartupSide };
1997
+ export { _countActiveOnGrid, _pickVirtualSlotsToActivate, _createOrderFromGrid, _prepareStartupUpdatePlan, _cancelChainOrder, _recoverStartupSyncFailure, _refreshStartupUpdatePlans, _executeStartupUpdateBatch, _executeStartupSequentialUpdateFallback, _executeStartupCreateGroupBatch, _createStartupOrderWithHandling, _executePlannedStartupCreates, _reconcileStartupSide, _classifyStartupOrderReuse };
1866
1998
  //# sourceMappingURL=grid_reconcile_internal.js.map
@@ -31,16 +31,16 @@
31
31
  *
32
32
  * SUBSYSTEM MODULES:
33
33
  * 1. manager.ts - OrderManager class (order lifecycle, fund tracking)
34
- * 2. grid.ts - Grid class (grid creation, synchronization, health)
34
+ * 2. grid.ts - Grid engine (grid creation, synchronization, health)
35
35
  * 3. utils/math.ts, utils/order.ts, utils/system.ts - Helper functions by concern
36
- * 4. format.ts - Numeric formatting (17 functions for consistent display)
36
+ * 4. format.ts - Numeric formatting (18 functions for consistent display)
37
37
  * 5. accounting.ts - Accountant class (fund calculations and reconciliation)
38
38
  * 6. logger.ts - Logger class (structured, color-coded output)
39
39
  * 7. async_lock.ts - AsyncLock class (race condition prevention)
40
40
  * 8. working_grid.ts - WorkingGrid class (copy-on-write grid state)
41
41
  * 9. export.ts - Trade history extraction and CSV export
42
42
  * 10. grid_reconcile.ts - Grid reconciliation against chain (startup + maintenance)
43
- * 11. strategy.ts - Strategy configuration and parsing
43
+ * 11. strategy.ts - StrategyEngine class (boundary-crawl rebalancing, target grid)
44
44
  * 12. sync_engine.ts - Real-time blockchain synchronization
45
45
  *
46
46
  * ===============================================================================
@@ -113,10 +113,21 @@ declare const utils: {
113
113
  pivot: number | null;
114
114
  reason?: "direction" | "same-level";
115
115
  };
116
+ readFillPipelineState(source: unknown): system.FillPipelineState;
117
+ resolveGridUpdateBlockers(source: unknown, options?: {
118
+ now?: number;
119
+ }): system.GridUpdateBlocker[];
120
+ noteGridUpdateBlockers(source: unknown, blockers: system.GridUpdateBlocker[] | null | undefined, options?: {
121
+ limit?: number;
122
+ }): {
123
+ cycles: number;
124
+ escalate: boolean;
125
+ };
116
126
  hasUnsettledFills(source: unknown): {
117
127
  unsettled: boolean;
118
128
  reason: string | null;
119
129
  };
130
+ getPipelineInFlightAgeMs(source: unknown, nowMs?: number): number;
120
131
  restoreLastMarketFill(manager: import("../types.js").OrderManagerLike, persisted: unknown, options?: {
121
132
  now?: number;
122
133
  }): boolean;
@@ -211,7 +222,8 @@ declare const utils: {
211
222
  resolveSlotIdForFillPrice: typeof order.resolveSlotIdForFillPrice;
212
223
  reviveVirtualSlotFromChain: typeof order.reviveVirtualSlotFromChain;
213
224
  attributeUnmatchedFillToGrid: typeof order.attributeUnmatchedFillToGrid;
214
- buildFillKey: typeof order.buildFillKey;
225
+ getLivePendingBroadcasts: typeof order.getLivePendingBroadcasts;
226
+ buildFillKey: typeof import("./fill_ledger.js").fillKeyOf;
215
227
  correctOrderPriceOnChain: typeof order.correctOrderPriceOnChain;
216
228
  correctAllPriceMismatches: typeof order.correctAllPriceMismatches;
217
229
  _validatePriceCorrectionEntry: typeof order._validatePriceCorrectionEntry;
@@ -266,6 +278,7 @@ declare const utils: {
266
278
  calculateBudgetedSizes: typeof order.calculateBudgetedSizes;
267
279
  buildCreateOpFingerprint: typeof order.buildCreateOpFingerprint;
268
280
  isOrderGoneErrorMessage: typeof order.isOrderGoneErrorMessage;
281
+ isStructuralRebuildStaleReason: typeof order.isStructuralRebuildStaleReason;
269
282
  recordDuplicateOrphanDetection: typeof order.recordDuplicateOrphanDetection;
270
283
  clearDuplicateOrphanDetection: typeof order.clearDuplicateOrphanDetection;
271
284
  duplicateOrphanLogInfo: typeof order.duplicateOrphanLogInfo;
@@ -281,7 +294,6 @@ declare const utils: {
281
294
  resolveLiveEdgeAnchorPrice: typeof order.resolveLiveEdgeAnchorPrice;
282
295
  compareEdge: typeof order.compareEdge;
283
296
  collectRefillSlotIds: typeof order.collectRefillSlotIds;
284
- recordOrderPlacement: typeof order.recordOrderPlacement;
285
297
  isFreshlyPlacedOrder: typeof order.isFreshlyPlacedOrder;
286
298
  _filterUnmatchedChainOrders: typeof order._filterUnmatchedChainOrders;
287
299
  getBtsSide: typeof math.getBtsSide;
@@ -295,6 +307,7 @@ declare const utils: {
295
307
  isEvacuationSizeStillValid: typeof math.isEvacuationSizeStillValid;
296
308
  validateBoundaryCommit: typeof math.validateBoundaryCommit;
297
309
  validatePersistedBoundary: typeof math.validatePersistedBoundary;
310
+ boundaryMoveReducesStrands: typeof math.boundaryMoveReducesStrands;
298
311
  isTransientInBandRejection: typeof math.isTransientInBandRejection;
299
312
  BOUNDARY_REJECT_PLACED_IN_BAND: "placed_order_in_band";
300
313
  resolveGapSlots: typeof math.resolveGapSlots;
@@ -31,22 +31,22 @@
31
31
  *
32
32
  * SUBSYSTEM MODULES:
33
33
  * 1. manager.ts - OrderManager class (order lifecycle, fund tracking)
34
- * 2. grid.ts - Grid class (grid creation, synchronization, health)
34
+ * 2. grid.ts - Grid engine (grid creation, synchronization, health)
35
35
  * 3. utils/math.ts, utils/order.ts, utils/system.ts - Helper functions by concern
36
- * 4. format.ts - Numeric formatting (17 functions for consistent display)
36
+ * 4. format.ts - Numeric formatting (18 functions for consistent display)
37
37
  * 5. accounting.ts - Accountant class (fund calculations and reconciliation)
38
38
  * 6. logger.ts - Logger class (structured, color-coded output)
39
39
  * 7. async_lock.ts - AsyncLock class (race condition prevention)
40
40
  * 8. working_grid.ts - WorkingGrid class (copy-on-write grid state)
41
41
  * 9. export.ts - Trade history extraction and CSV export
42
42
  * 10. grid_reconcile.ts - Grid reconciliation against chain (startup + maintenance)
43
- * 11. strategy.ts - Strategy configuration and parsing
43
+ * 11. strategy.ts - StrategyEngine class (boundary-crawl rebalancing, target grid)
44
44
  * 12. sync_engine.ts - Real-time blockchain synchronization
45
45
  *
46
46
  * ===============================================================================
47
47
  */
48
- // Runner may contain I/O and larger logic; require lazily to avoid loading it
49
- // during small unit tests. Expose a lazy accessor instead.
48
+ // The logger is required lazily: it pulls in console/formatting setup that small
49
+ // unit tests do not need, and `logger` is exposed as a lazy getter below.
50
50
  import { createRequire } from 'node:module';
51
51
  const require = createRequire(import.meta.url);
52
52
  import { OrderManager } from './manager.js';