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
@@ -5,10 +5,10 @@
5
5
  * Includes grid indexing, order comparison, delta building, and strategy calculations.
6
6
  *
7
7
  * ===============================================================================
8
- * TABLE OF CONTENTS (76 exported functions)
8
+ * TABLE OF CONTENTS (82 exported functions)
9
9
  * ===============================================================================
10
10
  *
11
- * SECTION 1: CHAIN ORDER MATCHING & RECONCILIATION (7 functions)
11
+ * SECTION 1: CHAIN ORDER MATCHING & RECONCILIATION (11 functions)
12
12
  * - parseChainOrder(chainOrder, assets) - Parse blockchain order to grid format
13
13
  * - applyChainSizeToGridOrder(manager, gridOrder, chainSize) - Apply chain size to grid
14
14
  * - correctOrderPriceOnChain(manager, correctionInfo, ...) - Correct order price on chain
@@ -16,6 +16,10 @@
16
16
  * - _validatePriceCorrectionEntry(...) - Drain-time staleness check for a queued correction
17
17
  * - _stampCorrectionProvenance(...) - Stamp queue provenance on a correction entry
18
18
  * - findLiveOrderOwnerByChainId(...) - Find the live grid slot that owns a chain order
19
+ * - resolveLiveOrderLadderPosition(...) - Ladder position of a live chain order
20
+ * - resolveExecutionPrice(...) - Execution price from the paid/received amounts
21
+ * - resolveSlotIdForFillPrice(...) - Slot a fill price belongs to under the genesis ladder
22
+ * - attributeUnmatchedFillToGrid(...) - Attribute a fill whose slot was already virtualised
19
23
  *
20
24
  * SECTION 2: CROSSING-PLACEMENT GUARDS (8 functions)
21
25
  * - chainOrderMatchesSlot(...) - Exact chain-order/grid-slot match
@@ -31,11 +35,12 @@
31
35
  * - buildCreateOrderArgs(order, assetA, assetB) - Build create order arguments
32
36
  * - getOrderTypeFromUpdatedFlags(buyUpdated, sellUpdated) - Get type from update flags
33
37
  * - resolveConfiguredPriceBound(value, fallback, startPrice, mode) - Resolve price bounds
34
- * - buildFillKey(fillOrParts) - Build a stable fill dedupe key
38
+ * - buildFillKey(fillOrParts) - Stable fill dedupe key (delegates to order/fill_ledger.ts)
35
39
  * - buildCreateOpFingerprint(params) - Build fingerprint for create operations
36
40
  *
37
- * SECTION 4: STATE TRANSITIONS & PLACEHOLDERS (6 functions)
41
+ * SECTION 4: STATE TRANSITIONS & PLACEHOLDERS (7 functions)
38
42
  * - virtualizeOrder(order) - Convert order to VIRTUAL state
43
+ * - reviveVirtualSlotFromChain(...) - Re-materialise a virtualised slot from its chain order
39
44
  * - convertToSpreadPlaceholder(order) - Convert order to SPREAD placeholder
40
45
  * - toRailHolePlaceholder(order) - Convert to a rail-typed hole placeholder
41
46
  * - geometryTypeForSlotIndex(...) - BUY/SELL type for a slot index
@@ -47,8 +52,9 @@
47
52
  * - updateGapEvacuationStreaks(...) - Tick per-slot gap-evacuation streak counter
48
53
  * - collectRefillSlotIds(...) - Refill-slot wire for the COW boundary hold
49
54
  *
50
- * SECTION 6: FILTERING & DRIFT DIAGNOSTICS (11 functions)
55
+ * SECTION 6: FILTERING & DRIFT DIAGNOSTICS (12 functions)
51
56
  * - filterOrdersByType(orders, orderType) - Filter orders by type
57
+ * - isStructuralRebuildStaleReason(reason) - Whether a refusal label means a structural rebuild
52
58
  * - buildOutsideInPairGroups(items, accessors) - Outside->center pair grouping
53
59
  * - extractBatchOperationResults(result) - Extract operation_results from chain batch result
54
60
  * - formatUnmatchedChainOrder(order) - Format structural drift diagnostics
@@ -106,10 +112,14 @@
106
112
  * - checkGridPriceInvariant(...) - The price emitted for a slot must equal its genesis price
107
113
  * - reportGridPriceInvariant(...) - Report one GRID-PRICE-INVARIANT check
108
114
  *
109
- * SECTION 14: PERSISTED CRAWL & PLACEMENT GRACE (3 functions)
115
+ * SECTION 14: PERSISTED CRAWL & PLACEMENT GRACE (2 functions + the CrawlEntry type)
110
116
  * - consumePendingFillCrawls(...) - Apply recorded-but-uncommitted fill crawls to the boundary
111
- * - recordOrderPlacement(...) - Record a fresh on-chain placement timestamp
112
117
  * - isFreshlyPlacedOrder(...) - Chain order placed within the surplus-cancel grace
118
+ * (the stamp itself is written only by the lifecycle funnel)
119
+ *
120
+ * SECTION 15: LIVE BROADCAST & EDGE PROJECTIONS (2 functions)
121
+ * - getLivePendingBroadcasts(manager, options?) - Live pending-broadcast list (expired entries deleted)
122
+ * - collectEdgePinnedFillIds(manager, fills) - Fill ids pinned to the configured/live edge
113
123
  *
114
124
  * ===============================================================================
115
125
  */
@@ -121,6 +131,8 @@ import { sleep } from './system.js';
121
131
  import { getErrorMessage, getErrorCode, getErrorName } from '../../utils/errors.js';
122
132
  import { hasGenesisLadder } from '../genesis_policy.js';
123
133
  import { parseSlotIndex } from './slot.js';
134
+ import { fillKeyOf, resolveTradedSide } from '../fill_ledger.js';
135
+ import { pendingBroadcastTtlMs } from '../lifecycle.js';
124
136
  const { isValidNumber, toFiniteNumber } = Format;
125
137
  const { blockchainToFloat, floatToBlockchainInt, quantizeFloat, slotIndexForPrice, priceSlotEqual } = MathUtils;
126
138
  const orderLogger = new Logger('Order');
@@ -162,6 +174,28 @@ function isOrderGoneErrorMessage(message, orderId) {
162
174
  return true;
163
175
  return false;
164
176
  }
177
+ /**
178
+ * Classify a working-grid staleness reason as a STRUCTURAL rebuild.
179
+ *
180
+ * `_syncWorkingGridFromMasterMutation` stamps reasons such as
181
+ * `master mutation during broadcasting (grid-init)` (a full grid rebuild) or
182
+ * `(fill-place)` (a fill landing during the plan). The two are NOT
183
+ * interchangeable: after a rebuild the fresh master no longer carries the live
184
+ * chain order IDs, so re-planning from it emits CREATEs for price levels the
185
+ * startup reconcile is concurrently re-pricing via UPDATE — both generations
186
+ * land and the loser becomes a duplicate-price orphan backlog.
187
+ *
188
+ * Single source of truth for every planner/guard that must treat a rebuild
189
+ * differently from a fill. Keep the pattern anchored to the context tokens
190
+ * emitted by manager._syncWorkingGridFromMasterMutation / structural paths.
191
+ * @param {unknown} reason - evaluateCommit refusal reason or staleness label.
192
+ * @returns {boolean} True when the master was structurally rebuilt.
193
+ */
194
+ function isStructuralRebuildStaleReason(reason) {
195
+ if (typeof reason !== 'string' || reason.length === 0)
196
+ return false;
197
+ return /\bgrid-init\b|\brebuild\b|\bresync\b|\bregenerated grid\b|\bstructural rebuild\b/i.test(reason);
198
+ }
165
199
  // ---------------------------------------------------------------------------
166
200
  // Persistent duplicate-orphan detection escalation. A duplicate-price-level
167
201
  // orphan is expected self-healing (fully filled order leaves a sub-dust
@@ -241,31 +275,6 @@ function _filterUnmatchedChainOrders(manager, chainOrderId) {
241
275
  manager._lastUnmatchedChainOrders = manager._lastUnmatchedChainOrders.filter((u) => (u?.id || u?.orderId || u?.chainOrderId) !== chainOrderId);
242
276
  }
243
277
  }
244
- /**
245
- * Record a fresh on-chain placement timestamp for surplus-cancel grace.
246
- * Called when a slot gains a chain orderId it did not have before (create,
247
- * adopt, rotation target). Powers isFreshlyPlacedOrder below.
248
- * @param {unknown} manager - OrderManager instance (owns `_placedAt`)
249
- * @param {string} chainOrderId - Chain order id that was just placed
250
- */
251
- function recordOrderPlacement(manager, chainOrderId) {
252
- try {
253
- if (!manager || chainOrderId == null || String(chainOrderId).length === 0)
254
- return;
255
- if (!(manager._placedAt instanceof Map))
256
- manager._placedAt = new Map();
257
- manager._placedAt.set(String(chainOrderId), Date.now());
258
- // Lazy GC: placement timestamps only matter inside the grace window.
259
- if (manager._placedAt.size > 500) {
260
- const cutoff = Date.now() - TIMING.SURPLUS_CANCEL_GRACE_MS * 2;
261
- for (const [id, ts] of manager._placedAt) {
262
- if (Number(ts) < cutoff)
263
- manager._placedAt.delete(id);
264
- }
265
- }
266
- }
267
- catch { /* bookkeeping must never break placement */ }
268
- }
269
278
  /**
270
279
  * True when the chain order was placed within the surplus-cancel grace
271
280
  * window. Surplus sweeps must skip such orders: a fill landing between two
@@ -280,6 +289,11 @@ function isFreshlyPlacedOrder(manager, chainOrderId, graceMs) {
280
289
  try {
281
290
  if (chainOrderId == null || String(chainOrderId).length === 0)
282
291
  return false;
292
+ // Single definition of the grace window lives on the lifecycle view.
293
+ const lifecycle = manager?.getLifecycle;
294
+ if (typeof lifecycle === 'function') {
295
+ return lifecycle.call(manager, String(chainOrderId)).isFreshlyPlaced(graceMs);
296
+ }
283
297
  const placedAt = manager?._placedAt instanceof Map
284
298
  ? manager._placedAt.get(String(chainOrderId))
285
299
  : null;
@@ -294,6 +308,30 @@ function isFreshlyPlacedOrder(manager, chainOrderId, graceMs) {
294
308
  return false;
295
309
  }
296
310
  }
311
+ /**
312
+ * Whether a cancel-class correction must be held back by the fresh-placement
313
+ * grace window.
314
+ *
315
+ * Type mismatches are deliberately EXEMPT. The grace exists so a fill landing
316
+ * between two controllers' count snapshots cannot get a seconds-old placement
317
+ * cancelled (surplus/duplicate churn). A live order on the WRONG side is not
318
+ * that race: it is a known-wrong order, and the next fill is classified from
319
+ * the slot's (wrong) side — a sell on a slot retyped BUY produced a
320
+ * `filledAmount=0` phantom fill, a dust cancel and a re-buy at the fill level
321
+ * (2026-11-04 live incident). The 15-minute SURPLUS_CANCEL_GRACE_MS is correct
322
+ * for surplus churn, not for a side that can corrupt fill accounting; the
323
+ * entry's own `_validatePriceCorrectionEntry` gate already drops it once the
324
+ * slot no longer owns the order or the side was repaired.
325
+ *
326
+ * @param {Object} manager - OrderManager instance
327
+ * @param {Object} entry - Queued correction entry
328
+ * @returns {boolean} True when the cancel should stay queued for this cycle
329
+ */
330
+ function shouldDeferFreshCancel(manager, entry) {
331
+ if (!entry || entry.typeMismatch === true)
332
+ return false;
333
+ return isFreshlyPlacedOrder(manager, entry.chainOrderId);
334
+ }
297
335
  /**
298
336
  * Remove a single correction entry by its full queue key
299
337
  * (chainOrderId + surplus flag). The queue's upsert key is
@@ -539,19 +577,11 @@ function attributeUnmatchedFillToGrid(manager, params) {
539
577
  }
540
578
  }
541
579
  }
542
- // Side from the asset that was PAID: paying the quote (assetB) buys the
543
- // base, paying the base sells it. Independent of any slot type. When the
544
- // fill event carries no pays asset (malformed/degraded), fall back to the
545
- // matched slot's rail type — the side must never be guessed from the price.
546
- let type = null;
547
- if (input.paysAssetId === assets.assetB.id)
548
- type = ORDER_TYPES.BUY;
549
- else if (input.paysAssetId === assets.assetA.id)
550
- type = ORDER_TYPES.SELL;
551
- if (type !== ORDER_TYPES.BUY && type !== ORDER_TYPES.SELL && slot
552
- && (slot.type === ORDER_TYPES.BUY || slot.type === ORDER_TYPES.SELL)) {
553
- type = slot.type;
554
- }
580
+ // Side from the asset that was PAID (order/fill_ledger.ts): paying the
581
+ // quote buys the base, paying the base sells it. Independent of the slot
582
+ // type; a malformed fill with no pays asset falls back to the slot's type
583
+ // and the side is never guessed from the price.
584
+ const type = resolveTradedSide(input.paysAssetId, assets, slot?.type);
555
585
  if (type !== ORDER_TYPES.BUY && type !== ORDER_TYPES.SELL)
556
586
  return false;
557
587
  const execPrice = resolveExecutionPrice(assets, input.paysAssetId, input.paysAmountRaw, input.receivesAssetId, input.receivesAmountRaw);
@@ -668,11 +698,17 @@ function findLiveOrderOwnerByChainId(manager, chainOrderId, slotId) {
668
698
  * replayed cancel would then destroy the freshly updated in-place order.
669
699
  *
670
700
  * Type-mismatch and gap-evacuation surplus decisions have their own source-
671
- * specific checks. A type mismatch is actionable only while the same live
672
- * slot still owns the id and still has the mismatched type. A gap evacuation
673
- * is actionable only while the same live slot remains in the current gap
674
- * band. Both otherwise use the old cancellation branch, so allowing either
675
- * decision to replay would recreate the same stale-replay regression.
701
+ * specific checks. A type mismatch is actionable while the same live slot
702
+ * still owns the id AND (its stored type OR its rail geometry — index vs
703
+ * boundary, including the gap band) still disagrees with the chain side. A
704
+ * stored type that a fill (or another in-place writer) retagged to the chain
705
+ * side is NOT a repair on its own: an order can carry the chain's side while
706
+ * sitting on the opposite rail or inside the band, and dropping the cancel
707
+ * there would let the residual rest on the wrong side (2026-11-04 incident).
708
+ * A gap evacuation is actionable only while the same live slot remains in the
709
+ * current gap band. Both otherwise use the old cancellation branch, so
710
+ * allowing either decision to replay would recreate the same stale-replay
711
+ * regression.
676
712
  *
677
713
  * @param {Object} manager - OrderManager instance (live grid + assets)
678
714
  * @param {Object} entry - Queued correction entry
@@ -698,10 +734,20 @@ function _validatePriceCorrectionEntry(manager, entry) {
698
734
  if (!slot) {
699
735
  return { valid: false, reason: `type-mismatch target ${slotId || '?'} no longer owns ${entry.chainOrderId}` };
700
736
  }
701
- if (!targetType || slot.type === targetType) {
702
- return { valid: false, reason: `type-mismatch for ${entry.chainOrderId} was repaired (${slot.type} now matches ${targetType || 'chain type'})` };
703
- }
704
- return { valid: true, reason: 'type-mismatch-still-live' };
737
+ // The stored type alone is not proof of a repair: a fill (or another
738
+ // in-place writer) may have retagged the slot to the CHAIN side while
739
+ // the level still belongs to the opposite rail. Only a level whose
740
+ // rail geometry also matches the chain side is genuinely repaired.
741
+ // A resolved SPREAD geometry (gap band) also contradicts a rail side:
742
+ // no order should rest there, so the cancel must survive. Geometry is
743
+ // index-vs-boundary, so an unknown boundary falls back to the
744
+ // stored-type check (fail-safe: never invent a rail).
745
+ const geometryType = geometryTypeForSlotIndex(parseSlotIndex(slot.id), manager?.boundaryIdx, manager?._gapSlots);
746
+ const geometryContradicts = geometryType !== null && geometryType !== targetType;
747
+ if (!targetType || (slot.type === targetType && !geometryContradicts)) {
748
+ return { valid: false, reason: `type-mismatch for ${entry.chainOrderId} was repaired (${slot.type} now matches ${targetType || 'chain type'} on the ${geometryType || 'unknown'} rail)` };
749
+ }
750
+ return { valid: true, reason: geometryContradicts ? 'type-mismatch-still-live-geometry' : 'type-mismatch-still-live' };
705
751
  }
706
752
  if (entry.gapEvacuation === true) {
707
753
  const slotId = entry?.gridOrder?.id;
@@ -867,23 +913,18 @@ async function applyChainSizeToGridOrder(manager, gridOrder, chainSize) {
867
913
  return updatedOrder;
868
914
  }
869
915
  /**
870
- * Build a stable fill dedupe key.
871
- * Accepts either a fill-history entry or explicit parts.
872
- * Returns null if required fields are missing — callers should
873
- * skip dedup rather than operate on a degraded key.
916
+ * Build a stable fill dedupe key: `orderId:blockNum:historyId`.
917
+ *
918
+ * Delegates to `order/fill_ledger.ts` — the single owner of fill identity.
919
+ * Kept exported under this name because `dexbot_fill_runtime` resolves it
920
+ * through a lazy shim and the orphan path reuses it. Returns null when a
921
+ * required field is missing: callers skip dedup rather than operate on a
922
+ * degraded key.
874
923
  *
875
924
  * @param {Object} fillOrParts - Fill entry ({ op, block_num, id }) or { orderId, blockNum, historyId }
876
- * @returns {string|null} Stable key in order:block:history form, or null if fields are missing
877
- */
878
- function buildFillKey(fillOrParts) {
879
- const fillOp = fillOrParts?.op?.[1];
880
- const orderId = fillOp?.order_id ?? fillOrParts?.orderId;
881
- const blockNum = fillOrParts?.block_num ?? fillOrParts?.blockNum;
882
- const historyId = fillOrParts?.id ?? fillOrParts?.historyId;
883
- if (!orderId || blockNum == null || !historyId)
884
- return null;
885
- return `${orderId}:${blockNum}:${historyId}`;
886
- }
925
+ * @returns {string|null} Stable key, or null if fields are missing
926
+ */
927
+ const buildFillKey = fillKeyOf;
887
928
  function _currentCorrectionGridOrder(manager, correctionInfo) {
888
929
  const slotId = correctionInfo?.gridOrder?.id;
889
930
  if (!slotId || !(manager?.orders instanceof Map))
@@ -921,8 +962,10 @@ async function correctOrderPriceOnChain(manager, correctionInfo, accountName, pr
921
962
  if (cancelOnly) {
922
963
  // Surplus-cancel grace: a fill landing between two controllers' count
923
964
  // snapshots must not get a seconds-old placement cancelled. Skip
924
- // quietly; the entry stays queued and re-evaluates next cycle.
925
- if (isFreshlyPlacedOrder(manager, chainOrderId)) {
965
+ // quietly; the entry stays queued and re-evaluates next cycle. A
966
+ // type mismatch is exempt (see shouldDeferFreshCancel): a wrong-side
967
+ // order cannot wait out the grace, its next fill is misclassified.
968
+ if (shouldDeferFreshCancel(manager, correctionInfo)) {
926
969
  manager.logger?.log?.(`[CORRECTION] Skipping cancel-only for freshly placed ${chainOrderId} — inside grace window`, 'info');
927
970
  return { success: true, skipped: true };
928
971
  }
@@ -953,7 +996,10 @@ async function correctOrderPriceOnChain(manager, correctionInfo, accountName, pr
953
996
  }
954
997
  // Surplus/type-mismatch entries need cancellation, not a price update
955
998
  if (isSurplus) {
956
- if (isFreshlyPlacedOrder(manager, chainOrderId)) {
999
+ // Type mismatches bypass the fresh-placement grace (see
1000
+ // shouldDeferFreshCancel): their fill would be booked against the
1001
+ // wrong slot side if the order is allowed to rest.
1002
+ if (shouldDeferFreshCancel(manager, correctionInfo)) {
957
1003
  manager.logger?.log?.(`[CORRECTION] Skipping surplus cancel for freshly placed ${chainOrderId} — inside grace window`, 'info');
958
1004
  return { success: true, skipped: true };
959
1005
  }
@@ -1290,13 +1336,56 @@ function resolveCorrectionWarnRateLimitMs(manager) {
1290
1336
  * Cancel-type corrections (duplicate orphans, surplus) are batched into
1291
1337
  * chunked multi-op transactions; price updates run sequentially.
1292
1338
  *
1339
+ * Runs inside the exclusive placement region: every correction broadcasts a
1340
+ * chain mutation, so it must never interleave with a COW batch, startup
1341
+ * reconcile Phase 2 or a dust/residual cancel. A caller already holding the
1342
+ * region (COW pre-batch drain) passes its lease so the nested call does not
1343
+ * deadlock.
1344
+ *
1293
1345
  * @param {Object} manager - OrderManager instance
1294
1346
  * @param {string} accountName - Account name for blockchain transactions
1295
1347
  * @param {string} privateKey - Private key for signing
1296
1348
  * @param {Object} accountOrders - AccountOrders accessor for blockchain ops
1349
+ * @param {Object} [options] - placementLease (reuse) + timeoutMs (bounded wait)
1297
1350
  * @returns {Promise<Object>} Summary {corrected, failed, results}
1298
1351
  */
1299
- async function correctAllPriceMismatches(manager, accountName, privateKey, accountOrders) {
1352
+ async function correctAllPriceMismatches(manager, accountName, privateKey, accountOrders, options = {}) {
1353
+ if (!manager || !manager._gridLock)
1354
+ return { corrected: 0, failed: 0, results: [] };
1355
+ const run = () => _correctAllPriceMismatchesLocked(manager, accountName, privateKey, accountOrders);
1356
+ // NESTED CALLER (COW pre-batch drain): the caller already owns the region.
1357
+ // Reuse the inherited lease only while it STILL owns it — `isPlacementActive()`
1358
+ // would also be true for a different holder (e.g. the watchdog force-released
1359
+ // this lease and another path took the region), which would run the drain
1360
+ // unprotected and re-open the duplicate window.
1361
+ if (options.placementLease) {
1362
+ const inherited = options.placementLease;
1363
+ const stillCurrent = typeof manager.isPlacementLeaseCurrent === 'function'
1364
+ ? manager.isPlacementLeaseCurrent(inherited)
1365
+ : true;
1366
+ if (stillCurrent)
1367
+ return await run();
1368
+ }
1369
+ const timeoutMs = Math.max(1, Number.isFinite(Number(options.timeoutMs)) ? Number(options.timeoutMs) : 5000);
1370
+ const deferredResult = { corrected: 0, failed: 0, results: [], staleDropped: 0, deferred: true, reason: 'placement-active' };
1371
+ // Single acquire/release contract (placement_lock.withPlacement).
1372
+ if (typeof manager.withPlacement === 'function') {
1373
+ const placed = await manager.withPlacement('correction-drain', async () => run(), { timeoutMs });
1374
+ return placed ?? deferredResult;
1375
+ }
1376
+ if (typeof manager.acquirePlacement !== 'function')
1377
+ return await run();
1378
+ const lease = await manager.acquirePlacement('correction-drain', { timeoutMs });
1379
+ if (!lease)
1380
+ return deferredResult;
1381
+ try {
1382
+ return await run();
1383
+ }
1384
+ finally {
1385
+ lease.release();
1386
+ }
1387
+ }
1388
+ async function _correctAllPriceMismatchesLocked(manager, accountName, privateKey, accountOrders) {
1300
1389
  if (!manager || !manager._gridLock)
1301
1390
  return { corrected: 0, failed: 0, results: [] };
1302
1391
  // 6b: backlog alarm (rate-limited). Emitted even when the drain defers
@@ -1382,10 +1471,12 @@ async function correctAllPriceMismatches(manager, accountName, privateKey, accou
1382
1471
  // correctOrderPriceOnChain cannot protect the batch path, which
1383
1472
  // bypasses it. Held-back entries are simply left in
1384
1473
  // ordersNeedingPriceCorrection (never removed) and re-drain next cycle.
1474
+ // Type mismatches are exempt from the hold (shouldDeferFreshCancel):
1475
+ // letting a wrong-side order rest corrupts the next fill's accounting.
1385
1476
  const cancelEntries = liveEntries.filter((c) => {
1386
1477
  if (!(c.cancelOnly === true || c.isSurplus === true))
1387
1478
  return false;
1388
- if (isFreshlyPlacedOrder(manager, c.chainOrderId)) {
1479
+ if (shouldDeferFreshCancel(manager, c)) {
1389
1480
  manager?.logger?.log?.(`[CORRECTION] Deferring cancel of freshly placed ${c.chainOrderId} — inside grace window`, 'info');
1390
1481
  return false;
1391
1482
  }
@@ -1761,9 +1852,15 @@ function detectGapEvacuationCandidates(masterGrid, boundaryIdx, gapSlots, option
1761
1852
  * @param {Map} streakMap - Mutable Map slotId -> consecutive-cycle count
1762
1853
  * @param {Array} candidates - detectGapEvacuationCandidates output
1763
1854
  * @param {number} [threshold] - GRID_LIMITS.GAP_EVACUATION_STREAK_THRESHOLD default
1855
+ * @param {Object} [options] - `increment: false` re-derives the ledger (prune
1856
+ * resolved ids + report readiness) WITHOUT counting a new observation. The
1857
+ * committed-geometry sweep uses it because the plan ticks the same ledger in
1858
+ * the same cycle; counting twice would arm the cancel-only teeth in the very
1859
+ * cycle whose rotation is about to evacuate the order.
1764
1860
  * @returns {{streaks: Object, ready: Array}}
1765
1861
  */
1766
- function updateGapEvacuationStreaks(streakMap, candidates, threshold = null) {
1862
+ function updateGapEvacuationStreaks(streakMap, candidates, threshold = null, options = {}) {
1863
+ const increment = options?.increment !== false;
1767
1864
  const thrRaw = threshold !== null && threshold !== undefined ? Number(threshold) : Number(GRID_LIMITS?.GAP_EVACUATION_STREAK_THRESHOLD);
1768
1865
  const thr = Number.isFinite(thrRaw) && thrRaw > 0 ? Math.floor(thrRaw) : 2;
1769
1866
  const seen = new Set();
@@ -1773,7 +1870,7 @@ function updateGapEvacuationStreaks(streakMap, candidates, threshold = null) {
1773
1870
  continue;
1774
1871
  seen.add(c.id);
1775
1872
  if (streakMap instanceof Map) {
1776
- streakMap.set(c.id, Number(streakMap.get(c.id) || 0) + 1);
1873
+ streakMap.set(c.id, increment ? Number(streakMap.get(c.id) || 0) + 1 : Number(streakMap.get(c.id) || 0));
1777
1874
  }
1778
1875
  }
1779
1876
  if (streakMap instanceof Map) {
@@ -1941,6 +2038,83 @@ function isCrossingCheckCandidate(o, excludeChainOrderId = null, cancelOpIndexBy
1941
2038
  return false;
1942
2039
  return true;
1943
2040
  }
2041
+ /**
2042
+ * LIVE (unexpired) pending-broadcast entries — the SINGLE liveness authority.
2043
+ *
2044
+ * A pending entry protects a slot/price whose uncertain CREATE may already be
2045
+ * live on chain but is not adopted yet. Three readers need that set (the COW
2046
+ * pre-broadcast guard, the reconcile CREATE path, and the reconcile surplus
2047
+ * sweep) and they used to disagree: two re-implemented the TTL by hand with
2048
+ * different rules and one read the raw map with no TTL at all, so a reconcile
2049
+ * could stay blocked by an entry the COW guard already considered dead.
2050
+ *
2051
+ * Liveness rule (unchanged from the COW guard, now the only one):
2052
+ * - younger than `PENDING_BROADCAST_TTL_MS` → live;
2053
+ * - older than the TTL but a successful open-orders sync completed AFTER it was
2054
+ * recorded → expired (a caught-up read re-verifies the level);
2055
+ * - older than 2× the TTL → expired regardless (a permanently lagging node must
2056
+ * not park CREATEs forever);
2057
+ * - no usable `recordedAt` → live (fail closed, never a silent unblock).
2058
+ *
2059
+ * Expired entries are DELETED here; callers get the live list.
2060
+ *
2061
+ * @param {Object} manager - OrderManager (`_pendingBroadcasts`, `_lastSyncAt`)
2062
+ * @param {Object} [options] - `now` clock override (tests)
2063
+ * @returns {Array} Live pending-broadcast entries
2064
+ */
2065
+ function getLivePendingBroadcasts(manager, options = {}) {
2066
+ const map = manager?._pendingBroadcasts;
2067
+ if (!(map instanceof Map))
2068
+ return [];
2069
+ // READ-ONLY mode for predicates: the blocker resolver asks "is anything
2070
+ // unresolved?" from a gate that must not mutate state or emit GC log lines.
2071
+ const gc = options?.gc !== false;
2072
+ // Single definition of the TTL and its fixture fallback (lifecycle.ts).
2073
+ const ttl = pendingBroadcastTtlMs();
2074
+ const now = Number.isFinite(Number(options?.now)) ? Number(options.now) : Date.now();
2075
+ const lastSyncAt = Number(manager?._lastSyncAt) || 0;
2076
+ const log = manager?.logger?.log;
2077
+ for (const [fingerprint, rawEntry] of map) {
2078
+ const entry = rawEntry;
2079
+ const recordedAt = Number(entry?.recordedAt) || 0;
2080
+ if (!(recordedAt > 0))
2081
+ continue;
2082
+ const age = now - recordedAt;
2083
+ if (age <= ttl)
2084
+ continue;
2085
+ const syncedSinceRecord = lastSyncAt > recordedAt;
2086
+ if (!syncedSinceRecord && age <= ttl * 2) {
2087
+ if (gc) {
2088
+ log?.(`[COW] Pending-broadcast entry ${String(fingerprint)} is ${Math.round(age / 1000)}s old but no sync has completed since it was recorded; keeping it (fail-closed) until a caught-up read`, 'debug');
2089
+ }
2090
+ continue;
2091
+ }
2092
+ // READ-ONLY CALLERS KEEP THE ENTRY. This branch is reached for an entry
2093
+ // the write path would GC: either a caught-up sync has completed since
2094
+ // it was recorded (age > ttl), or it is past the hard 2x cap. The
2095
+ // grid-blocker predicate must not mutate the map to expire it, and
2096
+ // "unknown" is never "gone" (INV-LIFE-001), so the entry stays a
2097
+ // `broadcast-pending` blocker until a write-path GC retires it through
2098
+ // the lifecycle. Deliberate fail-closed; do not turn this into a
2099
+ // pass-through without replacing the evidence (docs/FILL_PIPELINE.md B3).
2100
+ if (!gc)
2101
+ continue;
2102
+ map.delete(fingerprint);
2103
+ // Abandoned, not resolved: the order may be live. Route through the
2104
+ // lifecycle so the slot records `unknown` instead of becoming a clean
2105
+ // hole the next cycle re-CREATEs.
2106
+ try {
2107
+ const expire = manager
2108
+ ?._expirePendingBroadcast;
2109
+ if (typeof expire === 'function')
2110
+ expire.call(manager, String(fingerprint), entry);
2111
+ }
2112
+ catch { /* bookkeeping only */ }
2113
+ log?.(`[COW] Dropped expired pending-broadcast entry ${String(fingerprint)} (slot ${entry?.slotId ?? '?'}, age ${Math.round(age / 1000)}s, ` +
2114
+ `${syncedSinceRecord ? 'sync completed since record' : 'hard TTL cap'})`, 'warn');
2115
+ }
2116
+ return Array.from(map.values());
2117
+ }
1944
2118
  /**
1945
2119
  * Shared candidate set for crossing-placement checks: master orders plus
1946
2120
  * chain-side orders that may exist on chain but are not (yet) adopted into
@@ -1976,9 +2150,10 @@ function buildCrossingCheckCandidates(manager) {
1976
2150
  ? [...manager.orders.values()].map(withLivePrice)
1977
2151
  : [];
1978
2152
  if (manager._pendingBroadcasts instanceof Map) {
1979
- for (const entry of manager._pendingBroadcasts.values()) {
1980
- if (entry && entry.slotId && entry.order)
1981
- candidates.push(withLivePrice(entry));
2153
+ for (const entry of getLivePendingBroadcasts(manager)) {
2154
+ const wrapper = entry;
2155
+ if (wrapper && wrapper.slotId && wrapper.order)
2156
+ candidates.push(withLivePrice(wrapper));
1982
2157
  }
1983
2158
  }
1984
2159
  if (Array.isArray(manager._lastUnmatchedChainOrders)) {
@@ -3808,6 +3983,6 @@ function collectKnownOnChainOrderIds(mgr, placedResults, placedContexts, extraCr
3808
3983
  const all = new Set([...masterIds, ...createIds]);
3809
3984
  return { masterIds: [...masterIds], createIds: [...createIds], all: [...all] };
3810
3985
  }
3811
- export { parseChainOrder, resolveLiveOrderLadderPosition, applyChainSizeToGridOrder, resolveExecutionPrice, resolveSlotIdForFillPrice, reviveVirtualSlotFromChain, attributeUnmatchedFillToGrid, 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 };
3812
- export { resolveEdgeAnchorPrice, resolveLiveEdgeAnchorPrice, compareEdge, collectRefillSlotIds, recordOrderPlacement, isFreshlyPlacedOrder, _filterUnmatchedChainOrders };
3986
+ 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 };
3987
+ export { resolveEdgeAnchorPrice, resolveLiveEdgeAnchorPrice, compareEdge, collectRefillSlotIds, isFreshlyPlacedOrder, _filterUnmatchedChainOrders };
3813
3988
  //# sourceMappingURL=order.js.map