dexbot 1.6.18 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +117 -5
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_dynamic_weight.js +2 -1
  9. package/dist/analysis/analyze_kalman.js +3 -2
  10. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  11. package/dist/analysis/analyze_liquidity.js +336 -0
  12. package/dist/analysis/analyze_regime.js +3 -2
  13. package/dist/analysis/analyze_regime_windows.js +3 -2
  14. package/dist/analysis/analyze_volatility.js +3 -2
  15. package/dist/analysis/bot_key_utils.d.ts +44 -1
  16. package/dist/analysis/bot_key_utils.js +76 -7
  17. package/dist/analysis/fills_cache.js +2 -1
  18. package/dist/analysis/grid_correction_check.d.ts +1 -19
  19. package/dist/analysis/grid_correction_check.js +12 -30
  20. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  21. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  22. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.js +693 -0
  24. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +166 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.js +258 -0
  26. package/dist/analysis/liquidity/liquidity_view.d.ts +53 -0
  27. package/dist/analysis/liquidity/liquidity_view.js +66 -0
  28. package/dist/analysis/resolve_bot_accounts.js +7 -6
  29. package/dist/analysis/trade_profitability.js +4 -2
  30. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  31. package/dist/credential-daemon.js +13 -2
  32. package/dist/dexbot.js +77 -172
  33. package/dist/modules/account_bots.d.ts +11 -1
  34. package/dist/modules/account_orders.d.ts +12 -0
  35. package/dist/modules/account_orders.js +30 -0
  36. package/dist/modules/asset_lookup.d.ts +25 -0
  37. package/dist/modules/asset_lookup.js +75 -0
  38. package/dist/modules/bitshares-native/transport.js +24 -6
  39. package/dist/modules/bitshares_client.d.ts +24 -6
  40. package/dist/modules/bitshares_client.js +44 -7
  41. package/dist/modules/bot_settings.d.ts +2 -0
  42. package/dist/modules/chain_scan.d.ts +64 -0
  43. package/dist/modules/chain_scan.js +80 -0
  44. package/dist/modules/cli_colors.d.ts +5 -0
  45. package/dist/modules/cli_colors.js +7 -0
  46. package/dist/modules/cli_progress.d.ts +51 -0
  47. package/dist/modules/cli_progress.js +113 -0
  48. package/dist/modules/constants.d.ts +26 -3
  49. package/dist/modules/constants.js +63 -8
  50. package/dist/modules/dexbot_class.d.ts +1 -6
  51. package/dist/modules/dexbot_class.js +14 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
  53. package/dist/modules/dexbot_cow_runtime.js +634 -136
  54. package/dist/modules/dexbot_fill_runtime.js +132 -23
  55. package/dist/modules/dexbot_maintenance_runtime.js +242 -74
  56. package/dist/modules/dexbot_startup_runtime.js +32 -20
  57. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  58. package/dist/modules/dexbot_state_recovery.js +167 -5
  59. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  60. package/dist/modules/launcher/runtime_entry.js +36 -1
  61. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  62. package/dist/modules/liquidity_pool_ref.js +116 -0
  63. package/dist/modules/node_connect_policy.d.ts +8 -1
  64. package/dist/modules/node_connect_policy.js +18 -2
  65. package/dist/modules/node_flap_score.d.ts +87 -0
  66. package/dist/modules/node_flap_score.js +124 -0
  67. package/dist/modules/node_health_cache.d.ts +40 -3
  68. package/dist/modules/node_health_cache.js +66 -20
  69. package/dist/modules/node_manager.d.ts +101 -19
  70. package/dist/modules/node_manager.js +255 -65
  71. package/dist/modules/order/accounting.js +56 -7
  72. package/dist/modules/order/format.d.ts +24 -10
  73. package/dist/modules/order/format.js +30 -10
  74. package/dist/modules/order/grid.js +91 -13
  75. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  76. package/dist/modules/order/grid_reconcile.js +333 -189
  77. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  78. package/dist/modules/order/grid_reconcile_internal.js +298 -100
  79. package/dist/modules/order/index.d.ts +19 -1
  80. package/dist/modules/order/lifecycle.d.ts +353 -0
  81. package/dist/modules/order/lifecycle.js +1109 -0
  82. package/dist/modules/order/manager.d.ts +273 -5
  83. package/dist/modules/order/manager.js +654 -48
  84. package/dist/modules/order/placement_lock.d.ts +102 -0
  85. package/dist/modules/order/placement_lock.js +222 -0
  86. package/dist/modules/order/strategy.js +13 -1
  87. package/dist/modules/order/sync_engine.d.ts +33 -1
  88. package/dist/modules/order/sync_engine.js +241 -73
  89. package/dist/modules/order/utils/math.d.ts +39 -1
  90. package/dist/modules/order/utils/math.js +83 -1
  91. package/dist/modules/order/utils/order.d.ts +181 -5
  92. package/dist/modules/order/utils/order.js +455 -9
  93. package/dist/modules/order/utils/system.d.ts +81 -1
  94. package/dist/modules/order/utils/system.js +331 -44
  95. package/dist/modules/order/utils/validate.d.ts +7 -1
  96. package/dist/modules/order/utils/validate.js +80 -3
  97. package/dist/modules/outcome.d.ts +54 -0
  98. package/dist/modules/outcome.js +51 -0
  99. package/dist/modules/settings_merge.d.ts +4 -0
  100. package/dist/modules/settings_merge.js +9 -0
  101. package/dist/modules/timing_policy.d.ts +82 -0
  102. package/dist/modules/timing_policy.js +244 -0
  103. package/dist/modules/types.d.ts +137 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  105. package/dist/modules/utils/asset_symbols.js +21 -2
  106. package/dist/scripts/analysis_runner.d.ts +10 -0
  107. package/dist/scripts/analysis_runner.js +33 -0
  108. package/dist/scripts/analyze-credit.js +54 -17
  109. package/dist/scripts/analyze-orders.d.ts +4 -2
  110. package/dist/scripts/analyze-orders.js +115 -35
  111. package/dist/scripts/asset.d.ts +26 -0
  112. package/dist/scripts/asset.js +165 -0
  113. package/dist/scripts/bts_distribution.d.ts +1 -0
  114. package/dist/scripts/bts_distribution.js +194 -142
  115. package/dist/scripts/chart_command.d.ts +1 -1
  116. package/dist/scripts/chart_command.js +60 -86
  117. package/dist/scripts/chart_targets.d.ts +18 -0
  118. package/dist/scripts/chart_targets.js +48 -0
  119. package/dist/scripts/dw.js +1 -1
  120. package/dist/scripts/liquid.d.ts +24 -0
  121. package/dist/scripts/liquid.js +134 -0
  122. package/dist/scripts/rich_list.js +12 -16
  123. package/dist/scripts/test-credit-renewal.js +12 -5
  124. package/dist/scripts/token_distribution.d.ts +2 -0
  125. package/dist/scripts/token_distribution.js +132 -108
  126. package/dist/scripts/tv.js +1 -1
  127. package/dist/scripts/verify-browser-bundle.js +18 -0
  128. package/docs/COW_INVARIANTS.md +69 -10
  129. package/docs/DEXBOT_COMPARISON.md +6 -6
  130. package/docs/EVOLUTION.md +10 -8
  131. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  132. package/docs/GRID_PRICE_INVARIANT.md +5 -2
  133. package/docs/GRID_RECONCILE.md +36 -11
  134. package/docs/LOGGING.md +50 -4
  135. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +177 -27
  136. package/docs/README.md +23 -2
  137. package/docs/WORKFLOW.md +12 -4
  138. package/docs/architecture.md +42 -5
  139. package/docs/developer_guide.md +25 -8
  140. package/modules/README.md +8 -1
  141. package/package.json +3 -1
  142. package/scripts/README.md +39 -7
  143. package/scripts/pdev.sh +14 -1
  144. package/scripts/pmain.sh +23 -8
  145. package/scripts/ptest.sh +7 -0
  146. package/tests/README.md +30 -1
@@ -1686,6 +1686,7 @@ function validateBoundaryCommit(proposedBoundary, orders, gapSlots, options = {}
1686
1686
  return {
1687
1687
  ok: false,
1688
1688
  reason: BOUNDARY_REJECT_PLACED_IN_BAND,
1689
+ inBandCount,
1689
1690
  detail: `boundary=${raw} gapSlots=${gapSlots} placed count=${inBandCount} first idx=${firstInBandIdx} price=${firstInBandPrice} ` +
1690
1691
  `sits strictly inside implied band (${raw}, ${sellStart})`
1691
1692
  };
@@ -1726,6 +1727,58 @@ function validatePersistedBoundary(proposedBoundary, orders, gapSlots, options =
1726
1727
  ...(options.allowInBandSlotIds ? { allowInBandSlotIds: options.allowInBandSlotIds } : {})
1727
1728
  });
1728
1729
  }
1730
+ /**
1731
+ * Count the placed orders a boundary would strand inside its implied band.
1732
+ *
1733
+ * Returns 0 for a clean boundary, the validator's own count for a pure
1734
+ * stranding rejection, and null for a STRUCTURAL refusal (crossed book, ceiling,
1735
+ * range, non-integer) — the two are not comparable, so callers must not treat a
1736
+ * structural refusal as "zero strands". Uses the same validator (and the same
1737
+ * allow-list) as the commit/restore paths: no second stranding predicate.
1738
+ *
1739
+ * @param proposedBoundary - Boundary to judge
1740
+ * @param orders - Placed-order slots
1741
+ * @param gapSlots - Gap band width
1742
+ * @param options - Optional in-band allow-list (a fill's own partial residual)
1743
+ * @returns Strand count, or null when the refusal is structural
1744
+ */
1745
+ function countInBandPlacements(proposedBoundary, orders, gapSlots, options = {}) {
1746
+ const check = validateBoundaryCommit(proposedBoundary, orders, gapSlots, {
1747
+ rejectInBandPlacements: true,
1748
+ ...(options.allowInBandSlotIds ? { allowInBandSlotIds: options.allowInBandSlotIds } : {})
1749
+ });
1750
+ if (check.ok)
1751
+ return 0;
1752
+ if (check.reason === BOUNDARY_REJECT_PLACED_IN_BAND) {
1753
+ // Unknown is NOT zero: a validator that cannot report the count must not
1754
+ // read as "strands nothing" (the Number(null)===0 trap this stack keeps
1755
+ // guarding). Fail closed instead.
1756
+ const count = Number(check.inBandCount);
1757
+ return Number.isFinite(count) ? count : null;
1758
+ }
1759
+ return null;
1760
+ }
1761
+ /**
1762
+ * Whether moving a boundary from `current` to `candidate` strands FEWER placed
1763
+ * orders (a violation-reducing repair). Strictly fewer — an equal count is not
1764
+ * a repair, and a structural refusal on either side is never a repair.
1765
+ *
1766
+ * This is the one rule behind the fill re-anchor and the rail clamp accepting a
1767
+ * move the strict validator would refuse only for transient stranding; both
1768
+ * bounds stay in force (fill-anchor direction at the caller, strand count here).
1769
+ *
1770
+ * @param currentBoundary - Boundary currently committed
1771
+ * @param candidateBoundary - Proposed boundary
1772
+ * @param orders - Placed-order slots
1773
+ * @param gapSlots - Gap band width
1774
+ * @param options - Optional in-band allow-list (a fill's own partial residual)
1775
+ * @returns True when the candidate strands strictly fewer placed orders
1776
+ */
1777
+ function boundaryMoveReducesStrands(currentBoundary, candidateBoundary, orders, gapSlots, options = {}) {
1778
+ const current = countInBandPlacements(currentBoundary, orders, gapSlots, options);
1779
+ const candidate = countInBandPlacements(candidateBoundary, orders, gapSlots, options);
1780
+ return current !== null && candidate !== null && candidate < current;
1781
+ }
1729
1782
  /**
1730
1783
  * Whether a persisted-boundary rejection is the TRANSIENT kind that must not
1731
1784
  * trigger a rebuild: stranding (`placed_order_in_band`) with no accompanying
@@ -2148,6 +2201,35 @@ function derivePriceLevels(startPrice, minPrice, maxPrice, incrementPercent) {
2148
2201
  }
2149
2202
  return deduped;
2150
2203
  }
2204
+ /**
2205
+ * True when two prices are the SAME grid step: within half an increment of
2206
+ * each other. Used to judge a placement against the price that just traded —
2207
+ * a fill's execution price and the slot level it filled at differ by rounding
2208
+ * (live: slot 1310.046339 filled at 1310.060435, i.e. ~1e-5), so a raw
2209
+ * `>=`/`<=` comparison lets a same-level re-place through.
2210
+ *
2211
+ * The half-step cap mirrors `pricesOnSameLevel`: it can never merge two
2212
+ * legitimately adjacent levels (a full increment apart). A missing/invalid
2213
+ * increment degrades to exact equality.
2214
+ *
2215
+ * @param {number} priceA - First price
2216
+ * @param {number} priceB - Second price
2217
+ * @param {number} incrementPercent - Grid step in percent (e.g. 0.3)
2218
+ * @returns {boolean} True when both prices sit on the same grid step
2219
+ */
2220
+ function pricesWithinHalfStep(priceA, priceB, incrementPercent) {
2221
+ const pa = Number(priceA);
2222
+ const pb = Number(priceB);
2223
+ if (!Number.isFinite(pa) || !Number.isFinite(pb))
2224
+ return false;
2225
+ const inc = Number(incrementPercent);
2226
+ if (!Number.isFinite(inc) || inc <= 0)
2227
+ return pa === pb;
2228
+ const level = Math.min(Math.abs(pa), Math.abs(pb));
2229
+ if (!Number.isFinite(level))
2230
+ return pa === pb;
2231
+ return Math.abs(pa - pb) <= level * (inc / 100) * 0.5;
2232
+ }
2151
2233
  function buildGenesisFromPriceLevels(startPrice, incrementPercent, gapSlots, priceLevels) {
2152
2234
  const hash = hashPriceLevels(priceLevels);
2153
2235
  return {
@@ -2159,7 +2241,7 @@ function buildGenesisFromPriceLevels(startPrice, incrementPercent, gapSlots, pri
2159
2241
  createdAt: Date.now()
2160
2242
  };
2161
2243
  }
2162
- export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, deriveChainTruthFundBudget, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
2244
+ export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, boundaryMoveReducesStrands, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, deriveChainTruthFundBudget, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, pricesWithinHalfStep, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
2163
2245
  /**
2164
2246
  * Round a value to a given factor.
2165
2247
  * @param {number} value - Value to round
@@ -113,6 +113,7 @@
113
113
  *
114
114
  * ===============================================================================
115
115
  */
116
+ import type { PlacementLease } from '../placement_lock.js';
116
117
  import type { OrderManagerLike, PendingPriceCorrection, ChainOrder, ParsedChainOrder, AssetPair, AssetInfo, OrderType, ManagedOrder, UnmatchedChainOrder, CowAction, ProjectedFunds } from '../../types.js';
117
118
  import type { GridGenesis } from './math.js';
118
119
  interface CorrectionAccountOrdersLike {
@@ -142,6 +143,24 @@ interface CorrectionAccountOrdersLike {
142
143
  * @returns {boolean} True if the message indicates the order is gone.
143
144
  */
144
145
  declare function isOrderGoneErrorMessage(message: string | null | undefined, orderId?: string | null): boolean;
146
+ /**
147
+ * Classify a working-grid staleness reason as a STRUCTURAL rebuild.
148
+ *
149
+ * `_syncWorkingGridFromMasterMutation` stamps reasons such as
150
+ * `master mutation during broadcasting (grid-init)` (a full grid rebuild) or
151
+ * `(fill-place)` (a fill landing during the plan). The two are NOT
152
+ * interchangeable: after a rebuild the fresh master no longer carries the live
153
+ * chain order IDs, so re-planning from it emits CREATEs for price levels the
154
+ * startup reconcile is concurrently re-pricing via UPDATE — both generations
155
+ * land and the loser becomes a duplicate-price orphan backlog.
156
+ *
157
+ * Single source of truth for every planner/guard that must treat a rebuild
158
+ * differently from a fill. Keep the pattern anchored to the context tokens
159
+ * emitted by manager._syncWorkingGridFromMasterMutation / structural paths.
160
+ * @param {unknown} reason - evaluateCommit refusal reason or staleness label.
161
+ * @returns {boolean} True when the master was structurally rebuilt.
162
+ */
163
+ declare function isStructuralRebuildStaleReason(reason: unknown): boolean;
145
164
  /**
146
165
  * Record a duplicate-orphan detection for an orderId.
147
166
  * First sighting stays quiet (count 1). A repeated sighting of the same
@@ -173,8 +192,15 @@ declare function duplicateOrphanLogInfo(orderId: string | null | undefined): {
173
192
  declare function _filterUnmatchedChainOrders(manager: OrderManagerLike, chainOrderId: string): void;
174
193
  /**
175
194
  * Record a fresh on-chain placement timestamp for surplus-cancel grace.
176
- * Called when a slot gains a chain orderId it did not have before (create,
177
- * adopt, rotation target). Powers isFreshlyPlacedOrder below.
195
+ * Powers isFreshlyPlacedOrder below.
196
+ *
197
+ * NOTE: in production the placement stamp is written by the lifecycle write
198
+ * funnel (`OrderManager._syncLifecycleFromMutation` -> `markPlaced`) for every
199
+ * mutation, including the COW whole-map commit. This helper remains for callers
200
+ * that hold only a manager-shaped object (tests, fixtures) and for the `_placedAt`
201
+ * retention bound; it writes through the same facade, so there is still one copy
202
+ * of the stamp.
203
+ *
178
204
  * @param {unknown} manager - OrderManager instance (owns `_placedAt`)
179
205
  * @param {string} chainOrderId - Chain order id that was just placed
180
206
  */
@@ -201,6 +227,112 @@ declare function isFreshlyPlacedOrder(manager: OrderManagerLike, chainOrderId: s
201
227
  * @returns {Object} The same entry, stamped
202
228
  */
203
229
  declare function _stampCorrectionProvenance(entry: PendingPriceCorrection, source: string): PendingPriceCorrection;
230
+ /**
231
+ * Resolve the EXECUTION price of a fill from its paid/received raw amounts
232
+ * (quote per base). This is the fill FACT the LAST-FILL-GUARD pivot and the
233
+ * boundary re-anchor need — the slot price is only a grid identity and may be
234
+ * stale after a refused-commit chain adoption or an off-ladder maker fill.
235
+ *
236
+ * Returns null when either side of the amounts is missing/unusable, so callers
237
+ * can fall back (a fill we cannot price must not move the pivot).
238
+ *
239
+ * @param {Object} assets - {assetA (base), assetB (quote)} with precisions
240
+ * @param {string|null} paysAssetId - Asset the account paid
241
+ * @param {number} paysAmountRaw - Raw (integer) amount paid
242
+ * @param {string|null} receivesAssetId - Asset the account received
243
+ * @param {number} receivesAmountRaw - Raw (integer) amount received
244
+ * @returns {number|null} Quote-per-base price, or null when unresolvable
245
+ */
246
+ declare function resolveExecutionPrice(assets: AssetPair | null | undefined, paysAssetId: string | null | undefined, paysAmountRaw: number | null | undefined, receivesAssetId: string | null | undefined, receivesAmountRaw: number | null | undefined): number | null;
247
+ /**
248
+ * Resolve the grid SLOT a fill belongs to when its chain order id no longer
249
+ * identifies one.
250
+ *
251
+ * Every virtualisation path (`virtualizeOrder` -> `convertToSpreadPlaceholder`
252
+ * / `toRailHolePlaceholder`) NULLS `orderId`, so after a phantom cleanup or a
253
+ * refused-commit adoption the master holds no slot keyed by the filled order:
254
+ * the id lookup misses exactly when the fill matters most. The genesis ladder
255
+ * is the authority for "which slot does this price belong to" (same rule pass 2
256
+ * uses for adoption), so the fill's own execution price identifies the level.
257
+ *
258
+ * Returns null for a price outside the frozen rail: a shelf/manual order or an
259
+ * off-ladder wick must never be mapped onto an edge slot (that would arm the
260
+ * pivot with a price the grid never traded at).
261
+ *
262
+ * @param {Object} manager - OrderManager instance (genesis ladder + assets)
263
+ * @param {number} price - Fill execution price
264
+ * @param {Object} [hints] - Optional {size, type} of the fill for edge-dust tolerance
265
+ * @returns {string|null} `slot-N` id, or null when unresolvable/out-of-grid
266
+ */
267
+ declare function resolveSlotIdForFillPrice(manager: OrderManagerLike, price: number, hints?: {
268
+ size?: number | null;
269
+ type?: string | null;
270
+ }): string | null;
271
+ /**
272
+ * REVIVE a virtualised slot whose chain order is still LIVE on chain.
273
+ *
274
+ * The state hole this closes: a slot can be virtualised (phantom cleanup on a
275
+ * truncated read, refused-commit adoption, rotation cleanup) while its order
276
+ * still rests on the chain. In that state the slot is invisible to window
277
+ * accounting (`_countActiveOnGrid` needs ACTIVE/PARTIAL) but its order is still
278
+ * counted in `chainCount`, so the reconcile reads a shortfall it can never
279
+ * repair — and the planner sees a free level, which is how a second order can be
280
+ * created at a price that already holds one.
281
+ *
282
+ * The revive is broadcast-free (master-only): the order is already on chain, so
283
+ * this only re-materialises the slot at its chain size/state. It refuses when
284
+ * the chain order does NOT rest at this slot's level: the slot then merely
285
+ * aliases the id (a rotation source whose cancel has not landed, a re-slotted
286
+ * order) and reviving it would resurrect a level the planner emptied on purpose.
287
+ *
288
+ * @param {Object} manager - OrderManager instance
289
+ * @param {Object} slot - Master slot (must NOT be placed)
290
+ * @param {Object} chainOrder - Parsed chain order (price/size/type/orderId)
291
+ * @param {unknown} rawOnChain - Raw chain object for the slot snapshot
292
+ * @param {string} context - Update context tag for logging/accounting
293
+ * @param {Object} [options] - {skipAccounting}
294
+ * @returns {Promise<Object|null>} The revived slot when applied, else null
295
+ */
296
+ declare function reviveVirtualSlotFromChain(manager: OrderManagerLike, slot: ManagedOrder, chainOrder: ParsedChainOrder | null | undefined, rawOnChain: unknown, context: string, options?: {
297
+ skipAccounting?: boolean;
298
+ }): Promise<ManagedOrder | null>;
299
+ /**
300
+ * ATTRIBUTE a fill to the grid when its chain order id identifies no live slot
301
+ * ("order not found in active grid").
302
+ *
303
+ * The failure this closes (live incident): a 120s stale broadcast region
304
+ * deferred the fill queue, a phantom cleanup then virtualised the filled slots
305
+ * (which NULLS their `orderId`), and the re-delivered fills were dropped AFTER
306
+ * their accounting had been booked. Neither the LAST-FILL-GUARD pivot nor the
307
+ * owed boundary crawl learned the execution price, so the pivot stayed on a
308
+ * stale, HIGHER value and the direction rule then allowed re-buys ABOVE the
309
+ * market (9 buy-lower violations, 23.5% of the window's BTS).
310
+ *
311
+ * Two identities, in order:
312
+ * 1. the slot that still owns the chain order id (any state — a virtualised
313
+ * slot can keep its id), or
314
+ * 2. the genesis ladder level the fill's own execution price maps to (the
315
+ * common case, because virtualisation clears the id).
316
+ *
317
+ * Only what the fill PROVES is recorded: the pivot, and — when the resolved
318
+ * slot is a hole — an owed boundary crawl. The slot and the already-booked
319
+ * accounting are never touched: the funds are the accountant's business, this
320
+ * only keeps the geometry honest. A price outside the frozen rail is refused,
321
+ * so a shelf/manual order can never arm the pivot at a level the grid does not
322
+ * trade.
323
+ *
324
+ * @param {Object} manager - OrderManager instance
325
+ * @param {Object} params - fill identity {orderId, pays/receives amount+asset, isPartial}
326
+ * @returns {boolean} true when the fill was attributed to the grid
327
+ */
328
+ declare function attributeUnmatchedFillToGrid(manager: OrderManagerLike, params: {
329
+ orderId?: string | null;
330
+ paysAssetId?: string | null;
331
+ paysAmountRaw?: number | null;
332
+ receivesAssetId?: string | null;
333
+ receivesAmountRaw?: number | null;
334
+ isPartial?: boolean;
335
+ }): boolean;
204
336
  /**
205
337
  * Find the live grid slot that currently owns a chain order.
206
338
  * When slotId is supplied, only that exact slot is considered; otherwise all
@@ -343,13 +475,23 @@ declare function correctOrderPriceOnChain(manager: OrderManagerLike, correctionI
343
475
  * Cancel-type corrections (duplicate orphans, surplus) are batched into
344
476
  * chunked multi-op transactions; price updates run sequentially.
345
477
  *
478
+ * Runs inside the exclusive placement region: every correction broadcasts a
479
+ * chain mutation, so it must never interleave with a COW batch, startup
480
+ * reconcile Phase 2 or a dust/residual cancel. A caller already holding the
481
+ * region (COW pre-batch drain) passes its lease so the nested call does not
482
+ * deadlock.
483
+ *
346
484
  * @param {Object} manager - OrderManager instance
347
485
  * @param {string} accountName - Account name for blockchain transactions
348
486
  * @param {string} privateKey - Private key for signing
349
487
  * @param {Object} accountOrders - AccountOrders accessor for blockchain ops
488
+ * @param {Object} [options] - placementLease (reuse) + timeoutMs (bounded wait)
350
489
  * @returns {Promise<Object>} Summary {corrected, failed, results}
351
490
  */
352
- declare function correctAllPriceMismatches(manager: OrderManagerLike, accountName: string, privateKey: string, accountOrders: CorrectionAccountOrdersLike): Promise<{
491
+ declare function correctAllPriceMismatches(manager: OrderManagerLike, accountName: string, privateKey: string, accountOrders: CorrectionAccountOrdersLike, options?: {
492
+ placementLease?: PlacementLease | null;
493
+ timeoutMs?: number;
494
+ }): Promise<{
353
495
  corrected: number;
354
496
  failed: number;
355
497
  results: (PendingPriceCorrection & {
@@ -567,9 +709,16 @@ declare function detectGapEvacuationCandidates(masterGrid: Map<string, ManagedOr
567
709
  * @param {Map} streakMap - Mutable Map slotId -> consecutive-cycle count
568
710
  * @param {Array} candidates - detectGapEvacuationCandidates output
569
711
  * @param {number} [threshold] - GRID_LIMITS.GAP_EVACUATION_STREAK_THRESHOLD default
712
+ * @param {Object} [options] - `increment: false` re-derives the ledger (prune
713
+ * resolved ids + report readiness) WITHOUT counting a new observation. The
714
+ * committed-geometry sweep uses it because the plan ticks the same ledger in
715
+ * the same cycle; counting twice would arm the cancel-only teeth in the very
716
+ * cycle whose rotation is about to evacuate the order.
570
717
  * @returns {{streaks: Object, ready: Array}}
571
718
  */
572
- declare function updateGapEvacuationStreaks(streakMap: Map<string, number>, candidates: unknown, threshold?: number | null): {
719
+ declare function updateGapEvacuationStreaks(streakMap: Map<string, number>, candidates: unknown, threshold?: number | null, options?: {
720
+ increment?: boolean;
721
+ }): {
573
722
  streaks: Record<string, number>;
574
723
  ready: Array<{
575
724
  id: string;
@@ -646,6 +795,33 @@ declare function crossingCandidateChainId(o: CrossingCandidate | null | undefine
646
795
  * @returns {boolean} True when the candidate participates in crossing checks
647
796
  */
648
797
  declare function isCrossingCheckCandidate(o: CrossingCandidate | null | undefined, excludeChainOrderId?: string | null, cancelOpIndexByOrderId?: Map<string, unknown> | null): boolean;
798
+ /**
799
+ * LIVE (unexpired) pending-broadcast entries — the SINGLE liveness authority.
800
+ *
801
+ * A pending entry protects a slot/price whose uncertain CREATE may already be
802
+ * live on chain but is not adopted yet. Three readers need that set (the COW
803
+ * pre-broadcast guard, the reconcile CREATE path, and the reconcile surplus
804
+ * sweep) and they used to disagree: two re-implemented the TTL by hand with
805
+ * different rules and one read the raw map with no TTL at all, so a reconcile
806
+ * could stay blocked by an entry the COW guard already considered dead.
807
+ *
808
+ * Liveness rule (unchanged from the COW guard, now the only one):
809
+ * - younger than `PENDING_BROADCAST_TTL_MS` → live;
810
+ * - older than the TTL but a successful open-orders sync completed AFTER it was
811
+ * recorded → expired (a caught-up read re-verifies the level);
812
+ * - older than 2× the TTL → expired regardless (a permanently lagging node must
813
+ * not park CREATEs forever);
814
+ * - no usable `recordedAt` → live (fail closed, never a silent unblock).
815
+ *
816
+ * Expired entries are DELETED here; callers get the live list.
817
+ *
818
+ * @param {Object} manager - OrderManager (`_pendingBroadcasts`, `_lastSyncAt`)
819
+ * @param {Object} [options] - `now` clock override (tests)
820
+ * @returns {Array} Live pending-broadcast entries
821
+ */
822
+ declare function getLivePendingBroadcasts(manager: OrderManagerLike | null | undefined, options?: {
823
+ now?: number;
824
+ }): unknown[];
649
825
  /**
650
826
  * Shared candidate set for crossing-placement checks: master orders plus
651
827
  * chain-side orders that may exist on chain but are not (yet) adopted into
@@ -1455,7 +1631,7 @@ declare function collectKnownOnChainOrderIds(mgr: OrderManagerLike, placedResult
1455
1631
  createIds: string[];
1456
1632
  all: string[];
1457
1633
  };
1458
- export { parseChainOrder, resolveLiveOrderLadderPosition, applyChainSizeToGridOrder, buildFillKey, correctOrderPriceOnChain, correctAllPriceMismatches, _validatePriceCorrectionEntry, _stampCorrectionProvenance, findLiveOrderOwnerByChainId, buildCreateOrderArgs, getOrderTypeFromUpdatedFlags, resolveConfiguredPriceBound, virtualizeOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, detectGapEvacuationCandidates, updateGapEvacuationStreaks, resolveSpreadOrderSide, chainOrderMatchesSlot, chainOrderMatchesSlotWithTolerance, crossingCandidateChainId, isCrossingCheckCandidate, buildCrossingCheckCandidates, filterOrdersByType, buildOutsideInPairGroups, extractBatchOperationResults, formatUnmatchedChainOrder, isNonBlockingUnmatchedOrder, isStrandedHoldOrder, isOrderOnChain, isOrderVirtual, hasOnChainId, isOrderPlaced, isPhantomOrder, isSlotAvailable, isEmptyGridSlot, isOrderHealthy, checkSizeThreshold, checkSizesBeforeMinimum, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, shouldFlagOutOfSpread, buildIndexes, validateIndexes, ordersEqual, buildDelta, deriveTargetBoundary, isShiftEligibleFill, resolveEdgeCount, resolveEdgeOrders, selectEdgeSlots, getCoreOrdersTotal, getSideBudget, calculateBudgetedSizes, buildCreateOpFingerprint, isOrderGoneErrorMessage, recordDuplicateOrphanDetection, clearDuplicateOrphanDetection, duplicateOrphanLogInfo, chainOrderUnchangedFromCache, detectCrossedBookPlan, collectKnownOnChainOrderIds, collectEdgePinnedFillIds, edgeOrderIdSet, liveWindowIdSet, checkGridPriceInvariant, reportGridPriceInvariant };
1634
+ export { parseChainOrder, resolveLiveOrderLadderPosition, applyChainSizeToGridOrder, resolveExecutionPrice, resolveSlotIdForFillPrice, reviveVirtualSlotFromChain, attributeUnmatchedFillToGrid, getLivePendingBroadcasts, buildFillKey, correctOrderPriceOnChain, correctAllPriceMismatches, _validatePriceCorrectionEntry, _stampCorrectionProvenance, findLiveOrderOwnerByChainId, buildCreateOrderArgs, getOrderTypeFromUpdatedFlags, resolveConfiguredPriceBound, virtualizeOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, detectGapEvacuationCandidates, updateGapEvacuationStreaks, resolveSpreadOrderSide, chainOrderMatchesSlot, chainOrderMatchesSlotWithTolerance, crossingCandidateChainId, isCrossingCheckCandidate, buildCrossingCheckCandidates, filterOrdersByType, buildOutsideInPairGroups, extractBatchOperationResults, formatUnmatchedChainOrder, isNonBlockingUnmatchedOrder, isStrandedHoldOrder, isOrderOnChain, isOrderVirtual, hasOnChainId, isOrderPlaced, isPhantomOrder, isSlotAvailable, isEmptyGridSlot, isOrderHealthy, checkSizeThreshold, checkSizesBeforeMinimum, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, shouldFlagOutOfSpread, buildIndexes, validateIndexes, ordersEqual, buildDelta, deriveTargetBoundary, isShiftEligibleFill, resolveEdgeCount, resolveEdgeOrders, selectEdgeSlots, getCoreOrdersTotal, getSideBudget, calculateBudgetedSizes, buildCreateOpFingerprint, isOrderGoneErrorMessage, isStructuralRebuildStaleReason, recordDuplicateOrphanDetection, clearDuplicateOrphanDetection, duplicateOrphanLogInfo, chainOrderUnchangedFromCache, detectCrossedBookPlan, collectKnownOnChainOrderIds, collectEdgePinnedFillIds, edgeOrderIdSet, liveWindowIdSet, checkGridPriceInvariant, reportGridPriceInvariant };
1459
1635
  export type { CrawlEntry };
1460
1636
  export { resolveEdgeAnchorPrice, resolveLiveEdgeAnchorPrice, compareEdge, collectRefillSlotIds, recordOrderPlacement, isFreshlyPlacedOrder, _filterUnmatchedChainOrders };
1461
1637
  //# sourceMappingURL=order.d.ts.map