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
@@ -9,8 +9,8 @@
9
9
  * ===============================================================================
10
10
  *
11
11
  * SECTION 1: EXTERNAL DEPENDENCIES
12
- * SECTION 2: COW REBALANCE ENGINE
13
- * SECTION 3: ORDER MANAGER CLASS
12
+ * SECTION 2: COW REBALANCE ENGINE - COWRebalanceEngine class (exported)
13
+ * SECTION 3: ORDER MANAGER CLASS - OrderManager class (exported)
14
14
  * ===============================================================================
15
15
  */
16
16
  import { WorkingGrid } from './working_grid.js';
@@ -18,6 +18,10 @@ import Logger from './logger.js';
18
18
  import Accountant from './accounting.js';
19
19
  import StrategyEngine from './strategy.js';
20
20
  import SyncEngine from './sync_engine.js';
21
+ import { LifecycleRegistry } from './lifecycle.js';
22
+ import type { LifecycleView } from './lifecycle.js';
23
+ import PlacementLock from './placement_lock.js';
24
+ import type { PlacementLease } from './placement_lock.js';
21
25
  import type { GridGenesis } from './utils/math.js';
22
26
  import type { OrderManagerLike, ManagedOrder, GridConfig, AssetPair, AccountTotals, ManagerFunds, PendingPriceCorrection, ProcessedFillStoreLike, PendingBroadcast, ManagerLock, IllegalStateSignal, AccountingFailureSignal, BotMetrics, AccountOrdersLike, CowAction, RebalanceResult, ProjectedFunds, SyncResult, FillHistorySyncResult, FundDriftCheck, ChainFundsSnapshot, OrderType, OrderState, UnknownRecord } from '../types.js';
23
27
  /**
@@ -107,6 +111,10 @@ declare class OrderManager implements OrderManagerLike {
107
111
  sync: SyncEngine;
108
112
  _rebalanceState: string;
109
113
  _bootstrapping: number;
114
+ _structuralRebuildDepth: number;
115
+ _structuralRebuildStartedAt: number;
116
+ _structuralRebuildDeferWarnAt: number;
117
+ _structuralRebuildReason: string | null;
110
118
  _endOfBootstrapValidationDone: boolean;
111
119
  _broadcastingFlag: number;
112
120
  _broadcastingStartedAt: number;
@@ -157,6 +165,13 @@ declare class OrderManager implements OrderManagerLike {
157
165
  private _getOrderIdIndex;
158
166
  initialSpreadCount: number;
159
167
  currentSpreadCount: number;
168
+ /**
169
+ * True once a grid has been loaded/created and the spread metric measured.
170
+ * Before that both counters are 0, which is indistinguishable from a
171
+ * genuinely empty band — telemetry must print "unknown" instead of "0"
172
+ * (the restore line otherwise claims the spread band is gone).
173
+ */
174
+ _spreadCountKnown: boolean;
160
175
  outOfSpread: number;
161
176
  assets: AssetPair;
162
177
  accountId: string | null;
@@ -172,6 +187,7 @@ declare class OrderManager implements OrderManagerLike {
172
187
  processedFillStore: ProcessedFillStoreLike | null;
173
188
  _syncLock: ManagerLock;
174
189
  _fillProcessingLock: ManagerLock;
190
+ _placementLock: PlacementLock;
175
191
  _divergenceLock: ManagerLock;
176
192
  _gridLock: ManagerLock;
177
193
  _fundLock: ManagerLock;
@@ -179,6 +195,7 @@ declare class OrderManager implements OrderManagerLike {
179
195
  _pauseFundRecalc: number;
180
196
  _pauseFundRecalcWatchdog: ReturnType<typeof setTimeout> | null;
181
197
  _fillBatchInFlight: number;
198
+ _gridUpdateBlockedCycles: number;
182
199
  _pauseRecalcLogging: boolean;
183
200
  _pauseRecalcLoggingWatchdog: ReturnType<typeof setTimeout> | null;
184
201
  _throwOnIllegalState: boolean;
@@ -187,11 +204,22 @@ declare class OrderManager implements OrderManagerLike {
187
204
  _syncGeneration: number;
188
205
  _gridVersion: number;
189
206
  _gridPersistenceSuspendedReason: string | null;
190
- _pendingBroadcasts: Map<string, PendingBroadcast>;
191
- _committedOrderIds: Set<string>;
192
- _committedOrderIdsBuiltAt: number;
193
- _orderIdAssignedAt: Map<string, number>;
194
- _placedAt: Map<string, number>;
207
+ /**
208
+ * Single owner of "does this order exist on chain, and how sure are we".
209
+ * The legacy maps below are live views onto it — see modules/order/lifecycle.ts.
210
+ */
211
+ readonly _lifecycle: LifecycleRegistry;
212
+ /** Live view onto `_lifecycle`. Assigned as a whole by the COW commit path. */
213
+ get _committedOrderIds(): Set<string>;
214
+ set _committedOrderIds(value: Iterable<string>);
215
+ get _committedOrderIdsBuiltAt(): number;
216
+ set _committedOrderIdsBuiltAt(value: number);
217
+ get _orderIdAssignedAt(): Map<string, number>;
218
+ set _orderIdAssignedAt(value: Map<string, number>);
219
+ get _placedAt(): Map<string, number>;
220
+ set _placedAt(value: Map<string, number>);
221
+ get _pendingBroadcasts(): Map<string, PendingBroadcast>;
222
+ set _pendingBroadcasts(value: Map<string, PendingBroadcast>);
195
223
  _gapSlots: number;
196
224
  _genesis: GridGenesis | null;
197
225
  _missingGenesis: unknown;
@@ -213,6 +241,20 @@ declare class OrderManager implements OrderManagerLike {
213
241
  side: string;
214
242
  ts: number;
215
243
  }[];
244
+ /**
245
+ * Chain-size resizes already absorbed by sync pass 1 (partial fill seen in
246
+ * an open-orders snapshot). The fill-history batch that follows the same
247
+ * fill must not subtract / credit the same amount a second time.
248
+ * Live view onto `_lifecycle`; key = chain orderId.
249
+ */
250
+ get _chainSizeAppliedFills(): Map<string, {
251
+ filledInt: number;
252
+ at: number;
253
+ }>;
254
+ set _chainSizeAppliedFills(value: Map<string, {
255
+ filledInt: number;
256
+ at: number;
257
+ }>);
216
258
  _recentFillKeysSnapshot: Record<string, number> | null;
217
259
  _lastFilledBuyPrice: number | null;
218
260
  _lastFilledSellPrice: number | null;
@@ -296,16 +338,180 @@ declare class OrderManager implements OrderManagerLike {
296
338
  * @returns {boolean}
297
339
  */
298
340
  isBootstrapping(): boolean;
341
+ /**
342
+ * Mark a structural grid rebuild (trigger-file resync, startup regenerate)
343
+ * as in progress. While active, fill-driven COW rebalances DEFER: they would
344
+ * otherwise re-plan against the freshly rebuilt, order-id-less master and
345
+ * emit a create-only batch while the reconcile re-prices the live orders
346
+ * onto the same levels (duplicate-price orphan incident 2026-11-03).
347
+ * This is deliberately narrower than isBootstrapping(): the constructor's
348
+ * initial bootstrap is not a rebuild and fills may still rebalance there.
349
+ * @param {string} reason - Diagnostic label (e.g. 'trigger-file resync')
350
+ */
351
+ beginStructuralRebuild(reason?: string): void;
352
+ /** End a structural rebuild region (balanced with beginStructuralRebuild). */
353
+ endStructuralRebuild(): void;
354
+ /** Whether a structural rebuild currently owns placement. */
355
+ isStructuralRebuildInProgress(): boolean;
356
+ /** Diagnostic label of the active structural rebuild, or null. */
357
+ structuralRebuildReason(): string | null;
358
+ /**
359
+ * Run a chain-mutating placement path inside the exclusive region.
360
+ *
361
+ * SINGLE SOURCE OF TRUTH: every caller that can broadcast (COW, startup
362
+ * reconcile Phase 2, correction drain, dust/residual cancels, pool swaps)
363
+ * must go through this helper. It is NOT reentrant: a nested caller must not
364
+ * call it again — the COW body hands its lease to the pre-batch drain
365
+ * (`correctAllPriceMismatches({ placementLease })`), which verifies it with
366
+ * `isPlacementLeaseCurrent()` before mutating.
367
+ *
368
+ * Lock hierarchy: acquire placement BEFORE `_gridLock`; never acquire it
369
+ * while holding `_gridLock` (Level 0.5 — see the constructor's canonical
370
+ * lock-hierarchy block in this file).
371
+ *
372
+ * @returns `null` when the region could not be acquired; the caller must
373
+ * defer/abort its broadcast.
374
+ */
375
+ withPlacement<T>(kind: string, fn: (lease: PlacementLease) => Promise<T>, options?: {
376
+ timeoutMs?: number;
377
+ isShuttingDown?: () => boolean;
378
+ }): Promise<T | null>;
379
+ /**
380
+ * Acquire the exclusive placement region (see placement_lock.ts).
381
+ * Callers MUST release the lease in a finally block before returning.
382
+ * @param {string} kind - Owner label for diagnostics (e.g. 'cow-broadcast')
383
+ * @param {Object} [options] - Wait bound + shutdown probe
384
+ * @returns {Promise<Object|null>} Lease, or null on timeout/shutdown
385
+ */
386
+ acquirePlacement(kind: string, options?: {
387
+ timeoutMs?: number;
388
+ isShuttingDown?: () => boolean;
389
+ }): Promise<PlacementLease | null>;
390
+ /**
391
+ * Non-blocking placement acquire for paths that must defer rather than queue.
392
+ * @param {string} kind - Owner label
393
+ * @returns {Object|null} Lease when free, otherwise null
394
+ */
395
+ tryAcquirePlacement(kind: string): PlacementLease | null;
396
+ /** Whether another placement path currently holds the exclusive region. */
397
+ isPlacementActive(): boolean;
398
+ /**
399
+ * Whether the given lease is STILL the one that owns the region.
400
+ *
401
+ * The authoritative nesting predicate: a nested caller (the COW pre-batch
402
+ * drain) must verify its inherited lease with this before mutating.
403
+ * `isPlacementActive()` cannot answer it — it is true for any holder, so a
404
+ * lease invalidated by `forceRelease()` would still read as "live".
405
+ * @param {Object|null|undefined} lease - Lease to verify
406
+ * @returns {boolean}
407
+ */
408
+ isPlacementLeaseCurrent(lease: PlacementLease | null | undefined): boolean;
409
+ /** Owner label of the active placement region, or null. */
410
+ placementKind(): string | null;
411
+ /** Milliseconds the current placement region has been held (0 when free). */
412
+ placementHeldForMs(): number;
413
+ /**
414
+ * True when the given staleness reason means the master grid was
415
+ * structurally rebuilt while a plan was in flight. Such a plan must NOT be
416
+ * re-planned from the fresh (order-id-less) master: a create-only re-plan
417
+ * duplicates every live chain order the reconcile is about to update.
418
+ */
419
+ isStructuralRebuildStale(reason: unknown): boolean;
299
420
  /**
300
421
  * Whether a broadcast is currently active (no side-effects).
301
422
  * @returns {boolean}
302
423
  */
303
424
  isBroadcastingActive(): boolean;
425
+ /**
426
+ * Record that sync pass 1 already applied a chain-size reduction (a
427
+ * partial fill) for this order. The following fill-history batch checks it
428
+ * to stay idempotent: subtracting/crediting the same fill again shrinks the
429
+ * order twice and over-credits free balance (2026-11-03 log: 3.6604 ->
430
+ * 3.3046 by pass 1, then 3.3046 -> 2.9488 by the fill batch).
431
+ *
432
+ * Markers ACCUMULATE: two pass-1 detections before the fill queue drains
433
+ * (or one aggregated fill-history entry covering both) must add up, not
434
+ * overwrite — an overwritten marker makes the batch total unmatchable and
435
+ * re-opens the double-shrink. The map is mirrored into the persisted grid
436
+ * snapshot (debugInputs) so a restart between pass 1 and fill processing
437
+ * does not lose the evidence.
438
+ * @param {string} orderId - Chain order id
439
+ * @param {number} filledInt - Base-amount delta in chain integer units
440
+ * @returns {void}
441
+ */
442
+ noteChainSizeAppliedFill(orderId: string, filledInt: number, maxAgeMs?: number): void;
443
+ /**
444
+ * Consume a pass-1 chain-size marker for a fill without requiring an exact
445
+ * total match. Returns the number of chain-size units this fill may treat
446
+ * as ALREADY reflected in `rawOnChain` (0 when there is no marker).
447
+ *
448
+ * Partial consumption is the split-batch case: pass 1 absorbed A+B, the
449
+ * fill queue drains A first (marker keeps B), then B. The old all-or-nothing
450
+ * match rejected both and double-shrunk the slot twice.
451
+ * @param {string} orderId - Chain order id
452
+ * @param {number} filledInt - Base-amount delta in chain integer units
453
+ * @param {number} [maxAgeMs] - Marker freshness bound
454
+ * @returns {number} Applied (already-in-snapshot) amount, 0..filledInt
455
+ */
456
+ consumeChainSizeAppliedFillAmount(orderId: string, filledInt: number, maxAgeMs?: number): number;
457
+ /**
458
+ * Merge persisted pass-1 markers into the in-memory set (recovery reload).
459
+ * Live markers win on conflict: they may already be partially consumed,
460
+ * and replacing them with the older persisted total would double-count.
461
+ * Entries are sanitized and the clock is freshened (see below).
462
+ * @param {unknown} payload - `{ [orderId]: { filledInt, at } }`
463
+ * @returns {void}
464
+ */
465
+ restoreChainSizeAppliedFills(payload: unknown): void;
466
+ /** Snapshot the live pass-1 markers for persistence (empty when none). */
467
+ snapshotChainSizeAppliedFills(): Record<string, {
468
+ filledInt: number;
469
+ at: number;
470
+ }>;
471
+ /**
472
+ * Wake the tasks that deferred on isPlacementActive() when the region ends.
473
+ * The broadcast-region-end listener reschedules a deferred rebalance and
474
+ * drains queued fills; without this a fill deferred because a correction
475
+ * drain/COW held placement would only retry on the next unrelated event.
476
+ * Skipped while a broadcast region is still active (stopBroadcasting will
477
+ * fire the same listeners when it ends).
478
+ * @returns {void}
479
+ */
480
+ _handlePlacementRegionEnd(): void;
304
481
  /**
305
482
  * @param {boolean} value
306
483
  * @returns {void}
307
484
  */
308
485
  setShuttingDown(value: boolean): void;
486
+ /**
487
+ * Auto-clears a stale placement region after
488
+ * TIMING.PLACEMENT_STALE_CLEAR_MS so a hung chain call / missed release
489
+ * cannot park fills and rebalances forever. The holder's lease becomes a
490
+ * no-op on release (token guard), so a late finally cannot release a
491
+ * successor.
492
+ *
493
+ * TWO GUARDS, ONE TEARDOWN:
494
+ * - A bot-level batch/recovery still in flight and YOUNGER than the bound is
495
+ * evidence of progress, so the region is not torn down (a long create-group
496
+ * reconcile must survive). Only a batch older than the same bound is
497
+ * treated as part of the hung region.
498
+ * - When the teardown does happen it also clears a broadcast refcount that
499
+ * is itself past its bound, atomically. A refcount raised by a placement
500
+ * holder belongs to the same region (the COW body and the reconcile call
501
+ * startBroadcasting() INSIDE it), so clearing both in one place stops the
502
+ * maintenance tick from tearing down placement first and the refcount
503
+ * second (two authorities, one hung region). A refcount raised OUTSIDE any
504
+ * region (the spread-correction pre-broadcast hold in `order/grid.ts`) is
505
+ * not this region's and is left to `_clearStaleBroadcastFlag`, which still
506
+ * refuses to act on its own while a placement lease is held.
507
+ * @param {number} [maxAgeMs] - Override for tests
508
+ * @param {Object} [options] - `batchInFlightMs`: age of the LAST raised
509
+ * bot-level pipeline counter (0/undefined when none).
510
+ * @returns {boolean} true when a stale region was force-released
511
+ */
512
+ _clearStalePlacementRegion(maxAgeMs?: number, options?: {
513
+ batchInFlightMs?: number;
514
+ }): boolean;
309
515
  /**
310
516
  * Auto-clears a stale broadcast flag after 120s so a hung
311
517
  * broadcast cannot permanently block rebalancing.
@@ -497,7 +703,7 @@ declare class OrderManager implements OrderManagerLike {
497
703
  */
498
704
  resumeRecalcLogging(): void;
499
705
  /**
500
- * @param {Array<import('./types').Order>} orders
706
+ * @param {Array<import('../types.js').Order>} orders
501
707
  * @param {Object} info
502
708
  * @returns {Promise<any>}
503
709
  */
@@ -547,6 +753,32 @@ declare class OrderManager implements OrderManagerLike {
547
753
  */
548
754
  getActiveShadowLockCount(): number;
549
755
  _cleanExpiredLocks(): void;
756
+ /**
757
+ * The single answer to "does this order exist on chain, and how sure are we".
758
+ *
759
+ * Every consumer that used to infer this from one of the legacy maps must
760
+ * read it here instead — that is the whole point of the lifecycle registry:
761
+ * four sites consulting four different structures is how the engine ended up
762
+ * with four different answers for the same order.
763
+ *
764
+ * A `createUncertain` slot flag (persisted across restarts) is folded into
765
+ * `phase === 'unknown'` here, so no caller has to remember to check it.
766
+ *
767
+ * @param identity - Slot id, chain order id, or pending-broadcast fingerprint
768
+ * @returns {LifecycleView} Unified read surface (never null)
769
+ */
770
+ getLifecycle(identity: string | null | undefined): LifecycleView;
771
+ /**
772
+ * Lifecycle view for a slot, folding in the slot's own persisted flags.
773
+ * Prefer this over `getLifecycle(slotId)` wherever a slot object is at hand.
774
+ * @param slot - Grid slot (ManagedOrder) or null
775
+ * @returns {LifecycleView}
776
+ */
777
+ getSlotLifecycle(slot: {
778
+ id?: string;
779
+ orderId?: string | null;
780
+ createUncertain?: boolean;
781
+ } | null | undefined): LifecycleView;
550
782
  _normalizeOrderUpdateOptions(options?: UnknownRecord): {
551
783
  skipAccounting: boolean;
552
784
  fee: number;
@@ -557,10 +789,38 @@ declare class OrderManager implements OrderManagerLike {
557
789
  };
558
790
  _updateOrder(order: ManagedOrder, context?: string, options?: UnknownRecord): Promise<boolean>;
559
791
  _applyOrderUpdate(order: ManagedOrder, context?: string, options?: UnknownRecord): Promise<boolean>;
792
+ /**
793
+ * Project one order mutation into the lifecycle registry.
794
+ *
795
+ * This is the single write funnel for chain existence: every mutation goes
796
+ * through `_applyOrderUpdate`, so no call site has to remember which of the
797
+ * seven legacy structures to touch. A slot is the record's identity, so a
798
+ * chain-id change (rotation / re-place) updates the same record instead of
799
+ * starting a parallel one.
800
+ *
801
+ * @param previous - Slot before the mutation (absent on create)
802
+ * @param next - Slot after the mutation
803
+ * @param context - Mutation context label
804
+ * @returns {void}
805
+ */
806
+ _syncLifecycleFromMutation(previous: ManagedOrder | null | undefined, next: ManagedOrder, context: string): void;
807
+ /**
808
+ * Abandon an unresolved pending CREATE (TTL sweep / give-up).
809
+ *
810
+ * Distinct from `_pendingBroadcasts.delete()`: dropping an entry because the
811
+ * create RESOLVED leaves the slot free, while dropping it because we ran out
812
+ * of patience means the order may still be live. Collapsing both into one
813
+ * delete is how a lost receipt turned into a clean hole that got re-CREATEd.
814
+ *
815
+ * @param fingerprint - Pending-broadcast fingerprint being abandoned
816
+ * @param entry - The abandoned entry (carries the slot id)
817
+ * @returns {void}
818
+ */
819
+ _expirePendingBroadcast(fingerprint: string, entry: PendingBroadcast | null | undefined): void;
560
820
  _peekWorkingGrid(): WorkingGrid | null;
561
821
  _syncWorkingGridFromMasterMutation(orderId: string, context: string): void;
562
822
  /**
563
- * @param {Array<import('./types').Order>} updates - Order updates to apply
823
+ * @param {Array<import('../types.js').Order>} updates - Order updates to apply
564
824
  * @param {string} [context] - Update context label
565
825
  * @param {unknown} [options]
566
826
  * @returns {Promise<boolean>}
@@ -617,14 +877,14 @@ declare class OrderManager implements OrderManagerLike {
617
877
  reason: string;
618
878
  }>;
619
879
  /**
620
- * @param {Array<import('./types').Order>} orders - Filled orders
880
+ * @param {Array<import('../types.js').Order>} orders - Filled orders
621
881
  * @param {Set<string>} [excl] - Order IDs to exclude
622
882
  * @param {Object} [options]
623
883
  * @returns {Promise<any>}
624
884
  */
625
885
  processFilledOrders(orders: COWFillLike[], excl: Set<string>, options?: UnknownRecord): Promise<RebalanceResult>;
626
886
  /**
627
- * @returns {Array<import('./types').Order>}
887
+ * @returns {Array<import('../types.js').Order>}
628
888
  */
629
889
  getInitialOrdersToActivate(): ManagedOrder[];
630
890
  /**
@@ -667,19 +927,16 @@ declare class OrderManager implements OrderManagerLike {
667
927
  * Also used when the boundary is (re)anchored outside the fill path (grid
668
928
  * reset / recenter / rejected-snapshot rebuild): those records belong to
669
929
  * the previous generation, and applying their relative deltas onto a fresh
670
- * anchor would double-count movement the anchor already contains.
930
+ * anchor would double-count movement the anchor already contains. That is
931
+ * the explicit allowed-loss path: the grid generation is being discarded
932
+ * (rebuild, rejected snapshot, restart replay), so the relative deltas no
933
+ * longer have a geometry to apply onto.
671
934
  *
672
935
  * Marks the grid dirty so the cleared array reaches disk even on paths
673
936
  * that do not otherwise persist.
674
937
  *
675
938
  * @param {string} reason - Log/debug label for the drop
676
- */
677
- /**
678
- * Drop ALL owed fill-crawl records.
679
- *
680
- * This is the explicit allowed-loss path: the grid generation is being
681
- * discarded (rebuild, rejected snapshot, restart replay), so the relative
682
- * deltas no longer have a geometry to apply onto.
939
+ * @param {string} detail - Extra context appended to the drop log line
683
940
  */
684
941
  _clearPendingFillCrawls(reason?: string, detail?: string): void;
685
942
  /**
@@ -855,7 +1112,7 @@ declare class OrderManager implements OrderManagerLike {
855
1112
  */
856
1113
  clearStalePipelineOperations(): boolean;
857
1114
  /**
858
- * @param {Map<string, import('./types').Order>} targetGrid
1115
+ * @param {Map<string, import('../types.js').Order>} targetGrid
859
1116
  * @param {number} targetBoundary
860
1117
  * @returns {Object}
861
1118
  */