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
  * Price derivation, persistence, grid correction, and UI/interactive utilities.
5
5
  *
6
6
  * ===============================================================================
7
- * TABLE OF CONTENTS (43 exported functions + 11 structural view types)
7
+ * TABLE OF CONTENTS (52 exported functions + 12 structural view types)
8
8
  * ===============================================================================
9
9
  *
10
10
  * SECTION 1: PRICE DERIVATION (9 functions + 1 internal)
@@ -50,7 +50,18 @@
50
50
  * - resetLastFillPivot(manager) - Clear the pivot to cold state
51
51
  * - restoreLastFillPivot(manager) - Restore the persisted pivot into the manager
52
52
  *
53
- * SECTION 7: UI & INTERACTIVE UTILITIES (6 functions)
53
+ * SECTION 7: FILL PIPELINE & LAST-FILL GUARD (9 functions)
54
+ * - reanchorBoundaryFromLastFill(manager, ...) - Re-anchor a rebuilt boundary to the last fill
55
+ * - rearmLastFillPivotFromMarketFill(manager) - Re-arm the pivot from the last market fill
56
+ * - isLastFillGuardBlocked(price, type, lastPrice, lastType) - LAST-FILL-GUARD predicate
57
+ * - isLastFillPlacementBlocked(manager, price, type) - Placement-side LAST-FILL-GUARD wrapper
58
+ * - readFillPipelineState(source) - Projection of the fill-pipeline state
59
+ * - resolveGridUpdateBlockers(source, options) - Blockers that forbid a grid update right now
60
+ * - noteGridUpdateBlockers(...) - Log/record the blockers for one decision
61
+ * - hasUnsettledFills(source) - Whether any fill is still unsettled (with a reason)
62
+ * - getPipelineInFlightAgeMs(source, nowMs) - Age of the oldest in-flight pipeline work
63
+ *
64
+ * SECTION 8: UI & INTERACTIVE UTILITIES (6 functions)
54
65
  * - ensureProfilesDirectory(profilesDir) - Ensure profiles directory exists
55
66
  * - sleep(ms) - Pause execution for specified duration
56
67
  * - readInput(prompt, options) - Read user input from stdin
@@ -59,7 +70,7 @@
59
70
  * - withBlockchainRetry(fn, label, options) - Blockchain op with timeout + retry + node failover
60
71
  * (withTimeout lives in ./timeout)
61
72
  *
62
- * SECTION 8: GENERAL UTILITIES (7 functions)
73
+ * SECTION 9: GENERAL UTILITIES (7 functions)
63
74
  * - resolveAccountRef(manager, account) - Resolve best account reference
64
75
  * - deepFreeze(obj) - Recursively freeze object for immutability
65
76
  * - cloneMap(map) - Create shallow clone of Map
@@ -70,8 +81,8 @@
70
81
  *
71
82
  * STRUCTURAL VIEW TYPES:
72
83
  * AssetMeta, PoolReserve, PoolEntry, BitSharesClient, AmaCenterSnapshot,
73
- * FeeCacheEntryData, SpreadCorrectionRefusalReason, SpreadCorrectionReadiness,
74
- * UnmatchedChainOrderLike, GridResizeResult, CowResult
84
+ * FeeCacheEntryData, SpreadCorrectionReadiness, GridUpdateBlockerCode,
85
+ * GridUpdateBlocker, FillPipelineState, GridResizeResult, CowResult
75
86
  *
76
87
  * ===============================================================================
77
88
  */
@@ -624,9 +635,73 @@ export declare function isLastFillPlacementBlocked(manager: OrderManagerLike | n
624
635
  pivot: number | null;
625
636
  reason?: 'direction' | 'same-level';
626
637
  };
638
+ /**
639
+ * Why a grid update was refused this cycle.
640
+ *
641
+ * These are the ONLY reasons `resolveGridUpdateBlockers` may report. The list
642
+ * is closed on purpose: a new reason must be added here (and to
643
+ * `tests/test_grid_update_blockers.ts`), so "the grid did not update" can never
644
+ * be explained by an unprintable string again.
645
+ */
646
+ export type GridUpdateBlockerCode = 'fill-queued' | 'fill-deferred' | 'fill-in-flight' | 'crawl-owed' | 'broadcast-pending' | 'placement-held' | 'rebuild-active' | 'unknown-blocker';
647
+ export interface GridUpdateBlocker {
648
+ code: GridUpdateBlockerCode;
649
+ detail: string;
650
+ }
651
+ /** Pipeline state the fill blockers are derived from. `ok: false` means UNREADABLE, not settled. */
652
+ export interface FillPipelineState {
653
+ ok: boolean;
654
+ queued: number;
655
+ deferred: boolean;
656
+ inFlight: number;
657
+ owed: number;
658
+ error?: string;
659
+ }
660
+ /**
661
+ * Read the fill-pipeline counters ONCE, from a bot or a bare manager.
662
+ *
663
+ * This is the only place that peeks these fields. The previous projection
664
+ * (`hasUnsettledFills`) swallowed every read error and returned "settled",
665
+ * which is a fail-OPEN answer in a fail-closed system: an unreadable queue
666
+ * looked like an idle one and the grid was updated from a stale master.
667
+ * Unreadable is now a first-class state (`ok: false`), surfaced as
668
+ * `unknown-blocker`.
669
+ *
670
+ * These counters are pipeline bookkeeping, not lifecycle evidence: absence
671
+ * decisions still use the lifecycle registry (INV-LIFE-003), so this reader
672
+ * cannot become a second evidence set.
673
+ */
674
+ export declare function readFillPipelineState(source: unknown): FillPipelineState;
675
+ export declare function resolveGridUpdateBlockers(source: unknown, options?: {
676
+ now?: number;
677
+ }): GridUpdateBlocker[];
678
+ /**
679
+ * Count consecutive blocked cycles and decide whether the state is STUCK.
680
+ *
681
+ * Escalation is deliberately narrow: only `unknown-blocker` (unreadable
682
+ * pipeline state) escalates. A busy pipeline (`fill-in-flight`,
683
+ * `broadcast-pending`, a held region) is normal work and must not trigger a
684
+ * structural resync — the placement/broadcast watchdogs own those bounds. The
685
+ * counter is a cycle count, not a timing window: it is NOT a `TIMING` entry and
686
+ * must not be classified in `modules/timing_policy.ts`.
687
+ *
688
+ * @returns `{ cycles, escalate }`; `escalate` is true exactly when the state
689
+ * stayed unreadable for `FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES`
690
+ * consecutive attempts.
691
+ */
692
+ export declare function noteGridUpdateBlockers(source: unknown, blockers: GridUpdateBlocker[] | null | undefined, options?: {
693
+ limit?: number;
694
+ }): {
695
+ cycles: number;
696
+ escalate: boolean;
697
+ };
627
698
  /**
628
699
  * Are fills still UNSETTLED (arrived but not yet absorbed by the grid)?
629
700
  *
701
+ * Projection over `resolveGridUpdateBlockers` so the prose reason and the code
702
+ * cannot disagree. Kept as a boolean for its existing callers; new callers
703
+ * should ask for the codes.
704
+ *
630
705
  * While this returns true the master grid still holds filled slots as ACTIVE
631
706
  * and the boundary has not crawled for them, so any geometry-derived plan
632
707
  * (window top-up, startup-style reconcile) is built on the PREVIOUS book. The
@@ -644,6 +719,24 @@ export declare function hasUnsettledFills(source: unknown): {
644
719
  unsettled: boolean;
645
720
  reason: string | null;
646
721
  };
722
+ /**
723
+ * Age of the most recent bot-level pipeline raise.
724
+ *
725
+ * The two counters (`_batchInFlight`, `_recoverySyncInFlight`) each carry a
726
+ * `*StartedAt` stamp maintained by their raise site; a nested raise (a COW
727
+ * re-plan, a second recovery frame) refreshes it, so this reports how long ago
728
+ * the pipeline LAST showed activity, not how long the oldest frame has been
729
+ * open. That is the question a stale-region watchdog needs: a recent raise is
730
+ * evidence of progress. Lives here (next to
731
+ * `hasUnsettledFills`, the same bot/manager field-peeking contract) so the
732
+ * maintenance tick and the fill consumer cannot disagree about it.
733
+ *
734
+ * @param {Object} source - DEXBot-like (or OrderManager-like) instance
735
+ * @param {number} [nowMs] - Clock override (tests)
736
+ * @returns {number} Milliseconds since the most recent raise, 0 when nothing
737
+ * is in flight or the stamp is missing
738
+ */
739
+ export declare function getPipelineInFlightAgeMs(source: unknown, nowMs?: number): number;
647
740
  /**
648
741
  * Restore the persisted bot-scoped last-market-fill reference into the
649
742
  * manager. Deliberately independent of the boundary and the genesis: this is
@@ -833,7 +926,7 @@ export declare function retryPersistenceIfNeeded(manager: OrderManagerLike): Pro
833
926
  *
834
927
  * @param {Object} manager - OrderManager instance
835
928
  * @param {Object} accountOrders - AccountOrders data accessor
836
- * @param {string} botKey - Bot identifier for persistence
929
+ * @param {string} _botKey - Unused; persistence is keyed off the manager.
837
930
  * @param {Function} updateOrdersOnChainBatchFn - Batch update function for blockchain operations
838
931
  * @param {Function} updateGridFromBlockchainSnapshotFn - Grid resize function (injected to avoid circular dependency with grid.ts)
839
932
  * @returns {Promise<void>}
@@ -4,7 +4,7 @@
4
4
  * Price derivation, persistence, grid correction, and UI/interactive utilities.
5
5
  *
6
6
  * ===============================================================================
7
- * TABLE OF CONTENTS (43 exported functions + 11 structural view types)
7
+ * TABLE OF CONTENTS (52 exported functions + 12 structural view types)
8
8
  * ===============================================================================
9
9
  *
10
10
  * SECTION 1: PRICE DERIVATION (9 functions + 1 internal)
@@ -50,7 +50,18 @@
50
50
  * - resetLastFillPivot(manager) - Clear the pivot to cold state
51
51
  * - restoreLastFillPivot(manager) - Restore the persisted pivot into the manager
52
52
  *
53
- * SECTION 7: UI & INTERACTIVE UTILITIES (6 functions)
53
+ * SECTION 7: FILL PIPELINE & LAST-FILL GUARD (9 functions)
54
+ * - reanchorBoundaryFromLastFill(manager, ...) - Re-anchor a rebuilt boundary to the last fill
55
+ * - rearmLastFillPivotFromMarketFill(manager) - Re-arm the pivot from the last market fill
56
+ * - isLastFillGuardBlocked(price, type, lastPrice, lastType) - LAST-FILL-GUARD predicate
57
+ * - isLastFillPlacementBlocked(manager, price, type) - Placement-side LAST-FILL-GUARD wrapper
58
+ * - readFillPipelineState(source) - Projection of the fill-pipeline state
59
+ * - resolveGridUpdateBlockers(source, options) - Blockers that forbid a grid update right now
60
+ * - noteGridUpdateBlockers(...) - Log/record the blockers for one decision
61
+ * - hasUnsettledFills(source) - Whether any fill is still unsettled (with a reason)
62
+ * - getPipelineInFlightAgeMs(source, nowMs) - Age of the oldest in-flight pipeline work
63
+ *
64
+ * SECTION 8: UI & INTERACTIVE UTILITIES (6 functions)
54
65
  * - ensureProfilesDirectory(profilesDir) - Ensure profiles directory exists
55
66
  * - sleep(ms) - Pause execution for specified duration
56
67
  * - readInput(prompt, options) - Read user input from stdin
@@ -59,7 +70,7 @@
59
70
  * - withBlockchainRetry(fn, label, options) - Blockchain op with timeout + retry + node failover
60
71
  * (withTimeout lives in ./timeout)
61
72
  *
62
- * SECTION 8: GENERAL UTILITIES (7 functions)
73
+ * SECTION 9: GENERAL UTILITIES (7 functions)
63
74
  * - resolveAccountRef(manager, account) - Resolve best account reference
64
75
  * - deepFreeze(obj) - Recursively freeze object for immutability
65
76
  * - cloneMap(map) - Create shallow clone of Map
@@ -70,8 +81,8 @@
70
81
  *
71
82
  * STRUCTURAL VIEW TYPES:
72
83
  * AssetMeta, PoolReserve, PoolEntry, BitSharesClient, AmaCenterSnapshot,
73
- * FeeCacheEntryData, SpreadCorrectionRefusalReason, SpreadCorrectionReadiness,
74
- * UnmatchedChainOrderLike, GridResizeResult, CowResult
84
+ * FeeCacheEntryData, SpreadCorrectionReadiness, GridUpdateBlockerCode,
85
+ * GridUpdateBlocker, FillPipelineState, GridResizeResult, CowResult
75
86
  *
76
87
  * ===============================================================================
77
88
  */
@@ -80,7 +91,7 @@ const require = createRequire(import.meta.url);
80
91
  import { path } from '../../path_api.js';
81
92
  import { getStorage } from '../../storage/index.js';
82
93
  const storage = getStorage();
83
- import { API_LIMITS, ORDER_TYPES, ORDER_STATES, COW_ACTIONS, FEE_PARAMETERS, BTS_PRECISION, PIPELINE_TIMING, NATIVE_CLIENT, GRID_LIMITS, TIMING } from '../../constants.js';
94
+ import { API_LIMITS, ORDER_TYPES, ORDER_STATES, COW_ACTIONS, FEE_PARAMETERS, BTS_PRECISION, PIPELINE_TIMING, NATIVE_CLIENT, GRID_LIMITS, TIMING, FILL_PROCESSING } from '../../constants.js';
84
95
  import { PATHS } from '../../paths.js';
85
96
  import { toFiniteNumber, isValidNumber, toKnownNumber } from '../format.js';
86
97
  import * as MathUtils from './math.js';
@@ -863,6 +874,9 @@ export async function initializeFeeCache(botsConfig, BitShares) {
863
874
  (hasDiskFallback ? '. Using previously cached value from disk.' : '.'));
864
875
  }
865
876
  }
877
+ // The math-side fee-cache entry is a narrower structural view of the same
878
+ // row this module persists. Cast through the setter's own parameter type
879
+ // instead of naming a type that is not exported from utils/math.ts.
866
880
  MathUtils._setFeeCache(cache);
867
881
  _saveFeeCacheToDisk(cache);
868
882
  return cache;
@@ -934,11 +948,20 @@ export async function persistGridSnapshot(manager, accountOrders, snapshotOrders
934
948
  // Bot-scoped market-fill reference: survives grid regeneration, used
935
949
  // by spread correction as the price it must not trade through.
936
950
  const lastMarketFill = buildLastMarketFillPayload(manager);
951
+ // Restart durability for the pass-1 "size already applied" markers.
952
+ // They live on the manager only, so a crash between pass 1 and the
953
+ // fill-history batch would lose the evidence and replay the fill as a
954
+ // second shrink. Persisted in the existing free-form debugInputs blob
955
+ // (no schema change to the order rows).
956
+ const chainSizeAppliedFills = typeof manager.snapshotChainSizeAppliedFills === 'function'
957
+ ? manager.snapshotChainSizeAppliedFills()
958
+ : undefined;
937
959
  await accountOrders.storeMasterGrid(orders, btsFeesOwed, manager.boundaryIdx, manager.assets || null, {
938
960
  persistedAt: nowIso(),
939
961
  config: debugConfig,
940
962
  accountTotals,
941
- btsBalance
963
+ btsBalance,
964
+ ...(chainSizeAppliedFills !== undefined ? { chainSizeAppliedFills } : {})
942
965
  }, fillKeys, genesis, gapEvacStreaks, pendingFillCrawls, lastFillPivot, lastMarketFill);
943
966
  return true;
944
967
  }
@@ -1374,7 +1397,9 @@ export function reanchorBoundaryFromLastFill(manager, boundaryIdx, slots, gapSlo
1374
1397
  // leaves the remainder at the fill slot, and any boundary that puts the
1375
1398
  // fill outside its window necessarily puts that slot inside the implied
1376
1399
  // band. Allow exactly that residual (PARTIAL, same side, same ladder
1377
- // level); every other in-band order still refuses the re-anchor.
1400
+ // level); every other in-band order still refuses the re-anchor UNLESS the
1401
+ // move strands strictly fewer placed orders than the committed boundary
1402
+ // (the violation-reducing repair below).
1378
1403
  //
1379
1404
  // ANCHOR-AWARE: the residual sits at the slot the re-anchor is derived
1380
1405
  // from (`anchorIdx`), which is the batch EXTREMUM, not necessarily the
@@ -1408,7 +1433,23 @@ export function reanchorBoundaryFromLastFill(manager, boundaryIdx, slots, gapSlo
1408
1433
  check = { ok: false, reason: getErrorMessage(err) };
1409
1434
  }
1410
1435
  if (!check || check.ok !== true) {
1411
- return { boundaryIdx: boundary, reanchored: false, reason: `unsafe: ${check?.reason ?? 'unknown'}` };
1436
+ // VIOLATION-REDUCING REPAIR: a fill-derived re-anchor may legitimately
1437
+ // land while older strands are still waiting for GAP-EVAC. Refusing it
1438
+ // keeps the window behind the fill (the counter order stays in-band);
1439
+ // accepting it is safe only when the move strands STRICTLY FEWER placed
1440
+ // orders than the committed boundary already does — the same bound the
1441
+ // strict validator applies, measured instead of assumed. Structural
1442
+ // refusals (crossed book, ceiling, range) are never a repair.
1443
+ const repairsStrands = check?.reason === MathUtils.BOUNDARY_REJECT_PLACED_IN_BAND
1444
+ && MathUtils.boundaryMoveReducesStrands(boundary, candidate, slots ?? [], gap, allowedInBandSlotIds.length > 0 ? { allowInBandSlotIds: allowedInBandSlotIds } : undefined);
1445
+ if (!repairsStrands) {
1446
+ return { boundaryIdx: boundary, reanchored: false, reason: `unsafe: ${check?.reason ?? 'unknown'}` };
1447
+ }
1448
+ try {
1449
+ manager.logger?.log?.(`[BOUNDARY] Re-anchor accepted as a violation-reducing repair: boundary ${boundary} -> ` +
1450
+ `${candidate} strands fewer placed orders than the committed geometry (${check?.reason})`, 'warn');
1451
+ }
1452
+ catch { /* logging is best-effort */ }
1412
1453
  }
1413
1454
  try {
1414
1455
  manager.logger?.log?.(`[BOUNDARY] Re-anchored from the last fill: ${side} filled at slot ${anchorIdx} ` +
@@ -1742,9 +1783,148 @@ export function isLastFillPlacementBlocked(manager, price, type) {
1742
1783
  return { blocked: true, pivot, reason: 'direction' };
1743
1784
  return { blocked: false, pivot };
1744
1785
  }
1786
+ /**
1787
+ * Read the fill-pipeline counters ONCE, from a bot or a bare manager.
1788
+ *
1789
+ * This is the only place that peeks these fields. The previous projection
1790
+ * (`hasUnsettledFills`) swallowed every read error and returned "settled",
1791
+ * which is a fail-OPEN answer in a fail-closed system: an unreadable queue
1792
+ * looked like an idle one and the grid was updated from a stale master.
1793
+ * Unreadable is now a first-class state (`ok: false`), surfaced as
1794
+ * `unknown-blocker`.
1795
+ *
1796
+ * These counters are pipeline bookkeeping, not lifecycle evidence: absence
1797
+ * decisions still use the lifecycle registry (INV-LIFE-003), so this reader
1798
+ * cannot become a second evidence set.
1799
+ */
1800
+ export function readFillPipelineState(source) {
1801
+ const settled = { ok: true, queued: 0, deferred: false, inFlight: 0, owed: 0 };
1802
+ if (!source || typeof source !== 'object')
1803
+ return settled;
1804
+ try {
1805
+ const outer = source;
1806
+ const mgr = (outer.manager && typeof outer.manager === 'object'
1807
+ ? outer.manager
1808
+ : outer);
1809
+ const queue = outer._incomingFillQueue;
1810
+ if (queue !== undefined && queue !== null && !Array.isArray(queue)) {
1811
+ return { ...settled, ok: false, error: '_incomingFillQueue is not an array' };
1812
+ }
1813
+ const crawls = mgr._pendingFillCrawls;
1814
+ if (crawls !== undefined && crawls !== null && !Array.isArray(crawls)) {
1815
+ return { ...settled, ok: false, error: '_pendingFillCrawls is not an array' };
1816
+ }
1817
+ const inFlightRaw = mgr._fillBatchInFlight;
1818
+ const inFlight = Number(inFlightRaw);
1819
+ if (inFlightRaw !== undefined && inFlightRaw !== null && !Number.isFinite(inFlight)) {
1820
+ return { ...settled, ok: false, error: '_fillBatchInFlight is not a number' };
1821
+ }
1822
+ return {
1823
+ ok: true,
1824
+ queued: Array.isArray(queue) ? queue.length : 0,
1825
+ deferred: outer._deferredFillsPending === true,
1826
+ inFlight: Number.isFinite(inFlight) && inFlight > 0 ? inFlight : 0,
1827
+ owed: Array.isArray(crawls) ? crawls.length : 0,
1828
+ };
1829
+ }
1830
+ catch (err) {
1831
+ return { ok: false, queued: 0, deferred: false, inFlight: 0, owed: 0, error: getErrorMessage(err) };
1832
+ }
1833
+ }
1834
+ /**
1835
+ * Every reason the grid must NOT be mutated this cycle, as codes.
1836
+ *
1837
+ * Composition only — no new evidence: the fill counters come from
1838
+ * `readFillPipelineState`, the broadcast policy from `getLivePendingBroadcasts`
1839
+ * (INV-BROADCAST-005), the region from `isPlacementActive`, the rebuild flag
1840
+ * from the manager. A grid blocker (may the grid mutate?) is deliberately NOT
1841
+ * the per-action fresh-placement grace and NOT a known-wrong-side fact; those
1842
+ * stay with the planner and the correction queue (INV-RECON-006).
1843
+ */
1844
+ function fillStateBlockers(state) {
1845
+ if (!state.ok) {
1846
+ return [{ code: 'unknown-blocker', detail: state.error || 'fill pipeline state unreadable' }];
1847
+ }
1848
+ const blockers = [];
1849
+ if (state.queued > 0)
1850
+ blockers.push({ code: 'fill-queued', detail: `${state.queued} fill(s) queued for processing` });
1851
+ if (state.deferred)
1852
+ blockers.push({ code: 'fill-deferred', detail: 'deferred fill drain pending' });
1853
+ if (state.inFlight > 0)
1854
+ blockers.push({ code: 'fill-in-flight', detail: 'fill batch in flight' });
1855
+ if (state.owed > 0)
1856
+ blockers.push({ code: 'crawl-owed', detail: `${state.owed} owed boundary crawl(s)` });
1857
+ return blockers;
1858
+ }
1859
+ export function resolveGridUpdateBlockers(source, options = {}) {
1860
+ const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now();
1861
+ const blockers = fillStateBlockers(readFillPipelineState(source));
1862
+ if (!source || typeof source !== 'object')
1863
+ return blockers;
1864
+ const outer = source;
1865
+ const mgr = (outer.manager && typeof outer.manager === 'object' ? outer.manager : source);
1866
+ try {
1867
+ if (typeof mgr.isPlacementActive === 'function' && mgr.isPlacementActive() === true) {
1868
+ const kind = typeof mgr.placementKind === 'function' ? mgr.placementKind() : '';
1869
+ blockers.push({ code: 'placement-held', detail: `placement region held by ${kind || 'unknown'}` });
1870
+ }
1871
+ if (typeof mgr.isStructuralRebuildInProgress === 'function' && mgr.isStructuralRebuildInProgress() === true) {
1872
+ blockers.push({ code: 'rebuild-active', detail: 'structural rebuild in progress' });
1873
+ }
1874
+ // Read-only: a predicate must not GC the pending set or emit log lines.
1875
+ const pending = OrderUtils.getLivePendingBroadcasts(mgr, { now, gc: false });
1876
+ const pendingCount = Array.isArray(pending) ? pending.length : 0;
1877
+ if (pendingCount > 0) {
1878
+ blockers.push({ code: 'broadcast-pending', detail: `${pendingCount} unresolved broadcast(s)` });
1879
+ }
1880
+ }
1881
+ catch (err) {
1882
+ if (!blockers.some((b) => b.code === 'unknown-blocker')) {
1883
+ blockers.push({ code: 'unknown-blocker', detail: `blocker probe failed: ${getErrorMessage(err)}` });
1884
+ }
1885
+ }
1886
+ return blockers;
1887
+ }
1888
+ /**
1889
+ * Count consecutive blocked cycles and decide whether the state is STUCK.
1890
+ *
1891
+ * Escalation is deliberately narrow: only `unknown-blocker` (unreadable
1892
+ * pipeline state) escalates. A busy pipeline (`fill-in-flight`,
1893
+ * `broadcast-pending`, a held region) is normal work and must not trigger a
1894
+ * structural resync — the placement/broadcast watchdogs own those bounds. The
1895
+ * counter is a cycle count, not a timing window: it is NOT a `TIMING` entry and
1896
+ * must not be classified in `modules/timing_policy.ts`.
1897
+ *
1898
+ * @returns `{ cycles, escalate }`; `escalate` is true exactly when the state
1899
+ * stayed unreadable for `FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES`
1900
+ * consecutive attempts.
1901
+ */
1902
+ export function noteGridUpdateBlockers(source, blockers, options = {}) {
1903
+ if (!source || typeof source !== 'object')
1904
+ return { cycles: 0, escalate: false };
1905
+ const holder = source.manager && typeof source.manager === 'object'
1906
+ ? source.manager
1907
+ : source;
1908
+ const list = Array.isArray(blockers) ? blockers : [];
1909
+ const unreadable = list.some((b) => b && b.code === 'unknown-blocker');
1910
+ if (list.length === 0 || !unreadable) {
1911
+ holder._gridUpdateBlockedCycles = 0;
1912
+ return { cycles: 0, escalate: false };
1913
+ }
1914
+ const prev = Number(holder._gridUpdateBlockedCycles);
1915
+ const cycles = (Number.isFinite(prev) && prev > 0 ? prev : 0) + 1;
1916
+ holder._gridUpdateBlockedCycles = cycles;
1917
+ const rawLimit = Number(options.limit ?? FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES);
1918
+ const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : 12;
1919
+ return { cycles, escalate: cycles >= limit };
1920
+ }
1745
1921
  /**
1746
1922
  * Are fills still UNSETTLED (arrived but not yet absorbed by the grid)?
1747
1923
  *
1924
+ * Projection over `resolveGridUpdateBlockers` so the prose reason and the code
1925
+ * cannot disagree. Kept as a boolean for its existing callers; new callers
1926
+ * should ask for the codes.
1927
+ *
1748
1928
  * While this returns true the master grid still holds filled slots as ACTIVE
1749
1929
  * and the boundary has not crawled for them, so any geometry-derived plan
1750
1930
  * (window top-up, startup-style reconcile) is built on the PREVIOUS book. The
@@ -1759,29 +1939,56 @@ export function isLastFillPlacementBlocked(manager, price, type) {
1759
1939
  * @returns {{unsettled: boolean, reason: string|null}}
1760
1940
  */
1761
1941
  export function hasUnsettledFills(source) {
1762
- if (!source || typeof source !== 'object')
1942
+ // Fill state only: this predicate answers "have the fills settled?", not
1943
+ // "is the host busy?" (placement/broadcast/rebuild are the full resolver's
1944
+ // business). A projection that pulled the host codes in would report fills
1945
+ // unsettled whenever, say, a placement probe threw.
1946
+ const fill = fillStateBlockers(readFillPipelineState(source))[0];
1947
+ if (!fill)
1763
1948
  return { unsettled: false, reason: null };
1949
+ return { unsettled: true, reason: fill.detail };
1950
+ }
1951
+ /**
1952
+ * Age of the most recent bot-level pipeline raise.
1953
+ *
1954
+ * The two counters (`_batchInFlight`, `_recoverySyncInFlight`) each carry a
1955
+ * `*StartedAt` stamp maintained by their raise site; a nested raise (a COW
1956
+ * re-plan, a second recovery frame) refreshes it, so this reports how long ago
1957
+ * the pipeline LAST showed activity, not how long the oldest frame has been
1958
+ * open. That is the question a stale-region watchdog needs: a recent raise is
1959
+ * evidence of progress. Lives here (next to
1960
+ * `hasUnsettledFills`, the same bot/manager field-peeking contract) so the
1961
+ * maintenance tick and the fill consumer cannot disagree about it.
1962
+ *
1963
+ * @param {Object} source - DEXBot-like (or OrderManager-like) instance
1964
+ * @param {number} [nowMs] - Clock override (tests)
1965
+ * @returns {number} Milliseconds since the most recent raise, 0 when nothing
1966
+ * is in flight or the stamp is missing
1967
+ */
1968
+ export function getPipelineInFlightAgeMs(source, nowMs) {
1969
+ if (!source || typeof source !== 'object')
1970
+ return 0;
1764
1971
  const outer = source;
1765
- const mgr = (outer.manager && typeof outer.manager === 'object'
1766
- ? outer.manager
1767
- : outer);
1768
- try {
1769
- const queued = Array.isArray(outer._incomingFillQueue) ? outer._incomingFillQueue.length : 0;
1770
- if (queued > 0)
1771
- return { unsettled: true, reason: `${queued} fill(s) queued for processing` };
1772
- if (outer._deferredFillsPending === true)
1773
- return { unsettled: true, reason: 'deferred fill drain pending' };
1774
- const inFlight = Number(mgr._fillBatchInFlight);
1775
- if (Number.isFinite(inFlight) && inFlight > 0)
1776
- return { unsettled: true, reason: 'fill batch in flight' };
1777
- const owed = Array.isArray(mgr._pendingFillCrawls) ? mgr._pendingFillCrawls.length : 0;
1778
- if (owed > 0)
1779
- return { unsettled: true, reason: `${owed} owed boundary crawl(s)` };
1780
- }
1781
- catch {
1782
- return { unsettled: false, reason: null };
1972
+ const bot = (outer.manager && typeof outer.manager === 'object') ? outer : source;
1973
+ const fields = bot;
1974
+ const now = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
1975
+ const pairs = [
1976
+ ['_batchInFlight', '_batchInFlightStartedAt'],
1977
+ ['_recoverySyncInFlight', '_recoverySyncInFlightStartedAt'],
1978
+ ];
1979
+ let oldest = -1;
1980
+ for (const [countKey, startedKey] of pairs) {
1981
+ const count = Number(fields[countKey]) || 0;
1982
+ if (count <= 0)
1983
+ continue;
1984
+ const startedAt = Number(fields[startedKey]) || 0;
1985
+ if (!startedAt)
1986
+ continue;
1987
+ const age = Math.max(0, now - startedAt);
1988
+ if (age > oldest)
1989
+ oldest = age;
1783
1990
  }
1784
- return { unsettled: false, reason: null };
1991
+ return oldest > 0 ? oldest : 0;
1785
1992
  }
1786
1993
  /**
1787
1994
  * Restore the persisted bot-scoped last-market-fill reference into the
@@ -2136,7 +2343,7 @@ export async function retryPersistenceIfNeeded(manager) {
2136
2343
  *
2137
2344
  * @param {Object} manager - OrderManager instance
2138
2345
  * @param {Object} accountOrders - AccountOrders data accessor
2139
- * @param {string} botKey - Bot identifier for persistence
2346
+ * @param {string} _botKey - Unused; persistence is keyed off the manager.
2140
2347
  * @param {Function} updateOrdersOnChainBatchFn - Batch update function for blockchain operations
2141
2348
  * @param {Function} updateGridFromBlockchainSnapshotFn - Grid resize function (injected to avoid circular dependency with grid.ts)
2142
2349
  * @returns {Promise<void>}
@@ -2726,11 +2933,16 @@ export async function withBlockchainRetry(fn, label, options) {
2726
2933
  }
2727
2934
  catch (err) {
2728
2935
  lastError = err;
2729
- // Report node failure so NodeManager can blacklist and trigger failover
2936
+ // Report node failure so NodeManager can blacklist and trigger failover.
2937
+ // Attribute it to the node that actually served the attempt —
2938
+ // getBestNode() is the top *candidate*, which is frequently a
2939
+ // different node than the connected one, so using it punished an
2940
+ // innocent node and left the failing one in place.
2730
2941
  try {
2731
- const { getNodeManager } = require('../../bitshares_client');
2942
+ const { getNodeManager, getActiveNodeUrl } = require('../../bitshares_client');
2732
2943
  const nodeManager = getNodeManager?.();
2733
- const nodeUrl = nodeManager?.getBestNode?.();
2944
+ const nodeUrl = (typeof getActiveNodeUrl === 'function' ? getActiveNodeUrl() : null)
2945
+ || nodeManager?.getBestNode?.();
2734
2946
  if (nodeUrl && typeof nodeManager.reportNodeFailure === 'function') {
2735
2947
  nodeManager.reportNodeFailure(nodeUrl, getErrorMessage(err), 'blockchain-op');
2736
2948
  }
@@ -2744,9 +2956,11 @@ export async function withBlockchainRetry(fn, label, options) {
2744
2956
  }
2745
2957
  // All retries exhausted — force-switch to a different node and retry once more
2746
2958
  try {
2747
- const { getNodeManager, reconnectForCycle } = require('../../bitshares_client');
2959
+ const { getNodeManager, reconnectForCycle, getActiveNodeUrl } = require('../../bitshares_client');
2748
2960
  const nodeManager = getNodeManager?.();
2749
- const failedNode = nodeManager?.getBestNode?.();
2961
+ // Blacklist the node the operation ran on, not the best candidate.
2962
+ const failedNode = (typeof getActiveNodeUrl === 'function' ? getActiveNodeUrl() : null)
2963
+ || nodeManager?.getBestNode?.();
2750
2964
  if (failedNode && typeof nodeManager.blacklistNode === 'function') {
2751
2965
  nodeManager.blacklistNode(failedNode);
2752
2966
  logger?.log?.(`${label}: blacklisted node ${failedNode.substring(0, 40)}... after ${maxRetries} failed attempts. Switching nodes...`, 'warn');
@@ -224,7 +224,13 @@ declare function hasExecutableActions(rebalanceResult: unknown): boolean;
224
224
  * with {chainOrderId, price, size, type} to check beyond the grid
225
225
  * @returns {{isValid: boolean, violations: Array<Object>, violatingTargetIds: Set<string>}} Validation result
226
226
  */
227
- declare function validateCreateTargetSlots(actions: CowAction[], orders: Map<string, ManagedOrder>, _assets?: AssetPair | null, chainOrderCandidates?: UnmatchedChainOrder[], incrementPercent?: number | null): {
227
+ declare function validateCreateTargetSlots(actions: CowAction[], orders: Map<string, ManagedOrder>, _assets?: AssetPair | null, chainOrderCandidates?: UnmatchedChainOrder[], incrementPercent?: number | null, pendingBroadcasts?: Array<{
228
+ slotId?: unknown;
229
+ price?: unknown;
230
+ size?: unknown;
231
+ type?: unknown;
232
+ fingerprint?: unknown;
233
+ }>): {
228
234
  isValid: boolean;
229
235
  violations: CreateTargetViolation[];
230
236
  violatingTargetIds: Set<string>;
@@ -40,6 +40,7 @@ import * as Format from '../format.js';
40
40
  import { ORDER_STATES, ORDER_TYPES, COW_ACTIONS, COW_ORIGINS, GRID_LIMITS } from '../../constants.js';
41
41
  import { floatToBlockchainInt, blockchainToFloat, getPrecisionSlack, getPrecisionByOrderType, getDoubleDustThreshold, getSellStartIdx, isSlotIndexInGapBand, isEvacuationRotationAllowed, clamp, pricesOnSameLevel, sameGridPrice } from './math.js';
42
42
  import { parseSlotIndex } from './slot.js';
43
+ import { isSlotCreateUncertain } from '../lifecycle.js';
43
44
  import { isOrderOnChain, isPhantomOrder, convertToSpreadPlaceholder, detectGapEvacuationCandidates, updateGapEvacuationStreaks, isNonBlockingUnmatchedOrder } from './order.js';
44
45
  const { isValidNumber, toFiniteNumber } = Format;
45
46
  // Pre-computed valid sets
@@ -751,7 +752,7 @@ function hasExecutableActions(rebalanceResult) {
751
752
  * with {chainOrderId, price, size, type} to check beyond the grid
752
753
  * @returns {{isValid: boolean, violations: Array<Object>, violatingTargetIds: Set<string>}} Validation result
753
754
  */
754
- function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCandidates = [], incrementPercent = null) {
755
+ function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCandidates = [], incrementPercent = null, pendingBroadcasts = []) {
755
756
  const safeActions = Array.isArray(actions) ? actions : [];
756
757
  const orderMap = orders instanceof Map ? orders : new Map();
757
758
  const releasedSlotIds = new Set();
@@ -785,7 +786,9 @@ function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCa
785
786
  // sync pass 1 (`sync-clear-stale-id`), which turns the slot back into a
786
787
  // plain hole on the next cycle — so this gate cannot strand a level.
787
788
  const currentOwnsChainId = Boolean(current?.orderId);
788
- const currentCreateUncertain = current?.createUncertain === true;
789
+ // Single definition of the durable "CREATE result lost" marker
790
+ // (modules/order/lifecycle.ts) — this site used to read the raw flag.
791
+ const currentCreateUncertain = isSlotCreateUncertain(current);
789
792
  if (current && (isOrderOnChain(current) || currentOwnsChainId)) {
790
793
  violations.push({
791
794
  targetId,
@@ -866,6 +869,49 @@ function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCa
866
869
  }
867
870
  }
868
871
  }
872
+ // Pending-broadcast collisions: an uncertain CREATE from an earlier
873
+ // batch already targets this slot/price. Its orderId is not visible yet
874
+ // (the broadcast outcome is unknown), so the chain-orphan layers above
875
+ // cannot see it. Landing a second CREATE at the same level duplicates
876
+ // the order. Check BOTH the exact slot id and the price level, because
877
+ // a rebuilt grid can re-map a price onto a different slot id.
878
+ if (pendingBroadcasts.length > 0) {
879
+ const pendingSlotIds = new Set();
880
+ for (const p of pendingBroadcasts) {
881
+ if (p?.slotId != null && String(p.slotId).length > 0)
882
+ pendingSlotIds.add(String(p.slotId));
883
+ }
884
+ for (const entry of createEntries) {
885
+ if (pendingSlotIds.has(entry.targetId)) {
886
+ violations.push({
887
+ targetId: entry.targetId,
888
+ currentOrderId: `pending:${entry.targetId}`,
889
+ currentType: entry.type,
890
+ currentState: 'PENDING_BROADCAST',
891
+ reason: 'pending_broadcast_collision'
892
+ });
893
+ continue;
894
+ }
895
+ if (!_assets)
896
+ continue;
897
+ for (const p of pendingBroadcasts) {
898
+ if (p?.price == null)
899
+ continue;
900
+ if (p.type && entry.type && p.type !== entry.type)
901
+ continue;
902
+ if (pricesOnSameLevel(Number(p.price), Number(p.size) || 0, p.type, Number(entry.price), Number(entry.size) || 0, entry.type, _assets, incrementPercent)) {
903
+ violations.push({
904
+ targetId: entry.targetId,
905
+ currentOrderId: `pending:${String(p.fingerprint ?? p.slotId ?? 'unknown')}`,
906
+ currentType: entry.type,
907
+ currentState: 'PENDING_BROADCAST',
908
+ reason: 'pending_broadcast_collision'
909
+ });
910
+ break;
911
+ }
912
+ }
913
+ }
914
+ }
869
915
  // Same-batch duplicate slot
870
916
  const seen = new Set();
871
917
  for (const entry of createEntries) {