dexbot 1.6.17 → 1.6.18

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 (101) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/analysis/README.md +10 -9
  3. package/analysis/ama_fitting/README.md +2 -2
  4. package/analysis/bot_fitting/README.md +3 -3
  5. package/claw/package.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  8. package/dist/analysis/analyze_args.d.ts +2 -1
  9. package/dist/analysis/fills_source.d.ts +1 -8
  10. package/dist/analysis/fills_source.js +1 -1
  11. package/dist/analysis/grid_correction_check.d.ts +9 -6
  12. package/dist/analysis/grid_correction_check.js +56 -64
  13. package/dist/analysis/math_utils.d.ts +1 -1
  14. package/dist/analysis/trade_profitability.d.ts +1 -1
  15. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
  16. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  17. package/dist/market_adapter/cli_args.d.ts +6 -1
  18. package/dist/market_adapter/cli_args.js +16 -2
  19. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  20. package/dist/market_adapter/core/kibana_candles.js +3 -1
  21. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  22. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  23. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  24. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  25. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  26. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  27. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  28. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  29. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  30. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  31. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  32. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  33. package/dist/market_adapter/inputs/window_cache.js +14 -1
  34. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  35. package/dist/market_adapter/lp_chart_runner.js +3 -1
  36. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  37. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  38. package/dist/market_adapter/market_adapter.d.ts +10 -2
  39. package/dist/market_adapter/market_adapter.js +10 -11
  40. package/dist/market_adapter/utils/chain.d.ts +2 -3
  41. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  42. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  43. package/dist/market_adapter/utils/file_lock.js +1 -1
  44. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  45. package/dist/market_adapter/utils/native_history.js +3 -1
  46. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  47. package/dist/modules/bots_file_lock.d.ts +2 -2
  48. package/dist/modules/bots_file_lock.js +2 -2
  49. package/dist/modules/constants.js +6 -3
  50. package/dist/modules/dexbot_class.d.ts +8 -0
  51. package/dist/modules/dexbot_class.js +10 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
  53. package/dist/modules/dexbot_cow_runtime.js +461 -43
  54. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  55. package/dist/modules/dexbot_maintenance_runtime.js +56 -9
  56. package/dist/modules/dexbot_startup_runtime.js +7 -1
  57. package/dist/modules/graceful_shutdown.d.ts +2 -2
  58. package/dist/modules/graceful_shutdown.js +2 -2
  59. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  60. package/dist/modules/node_manager.d.ts +1 -1
  61. package/dist/modules/node_manager.js +1 -1
  62. package/dist/modules/order/accounting.js +2 -1
  63. package/dist/modules/order/export.d.ts +2 -2
  64. package/dist/modules/order/export.js +2 -2
  65. package/dist/modules/order/grid.d.ts +19 -14
  66. package/dist/modules/order/grid.js +262 -61
  67. package/dist/modules/order/grid_reconcile.js +5 -1
  68. package/dist/modules/order/grid_reconcile_internal.js +2 -1
  69. package/dist/modules/order/index.d.ts +9 -3
  70. package/dist/modules/order/manager.d.ts +10 -0
  71. package/dist/modules/order/manager.js +41 -11
  72. package/dist/modules/order/strategy.js +22 -2
  73. package/dist/modules/order/sync_engine.d.ts +12 -1
  74. package/dist/modules/order/sync_engine.js +135 -20
  75. package/dist/modules/order/utils/math.d.ts +8 -9
  76. package/dist/modules/order/utils/math.js +24 -13
  77. package/dist/modules/order/utils/order.d.ts +52 -11
  78. package/dist/modules/order/utils/order.js +137 -21
  79. package/dist/modules/order/utils/system.d.ts +73 -29
  80. package/dist/modules/order/utils/system.js +239 -48
  81. package/dist/modules/order/utils/validate.d.ts +1 -0
  82. package/dist/modules/order/utils/validate.js +4 -1
  83. package/dist/modules/storage/index.d.ts +3 -2
  84. package/dist/modules/storage/index.js +3 -2
  85. package/dist/modules/types.d.ts +9 -0
  86. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  87. package/docs/COW_INVARIANTS.md +20 -10
  88. package/docs/DEXBOT_COMPARISON.md +5 -5
  89. package/docs/EVOLUTION.md +9 -8
  90. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
  91. package/docs/GRID_PRICE_INVARIANT.md +24 -4
  92. package/docs/GRID_RECONCILE.md +5 -5
  93. package/docs/LIFECYCLE.md +11 -11
  94. package/docs/LOGGING.md +15 -2
  95. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +123 -36
  96. package/docs/README.md +1 -1
  97. package/docs/architecture.md +115 -13
  98. package/docs/developer_guide.md +12 -0
  99. package/market_adapter/README.md +9 -4
  100. package/modules/README.md +18 -14
  101. package/package.json +4 -3
@@ -25,6 +25,11 @@ interface CredentialClientOptions {
25
25
  */
26
26
  onNodeFailed?: (nodeUrl: string) => void;
27
27
  }
28
+ /**
29
+ * Typed daemon reply. Exported because downstream wrapper modules infer it as
30
+ * the return type of `executeOperationsViaCredentialDaemon`; declaration emit
31
+ * cannot name a module-private type there (TS4058).
32
+ */
28
33
  export interface CredentialDaemonResponse {
29
34
  success?: boolean;
30
35
  error?: string;
@@ -8,7 +8,7 @@ const require = createRequire(import.meta.url);
8
8
  import { lazyShim } from './lazy_shim.js';
9
9
  import fs from 'node:fs';
10
10
  import { spawn } from 'node:child_process';
11
- import { nowIso, fireStructuralResync } from './order/utils/system.js';
11
+ import { nowIso, fireStructuralResync, resolveLastFillGuardReference } from './order/utils/system.js';
12
12
  import { path } from './path_api.js';
13
13
  import * as chainOrders from './chain_orders.js';
14
14
  import * as grid from './order/grid.js';
@@ -72,7 +72,7 @@ function getCoreOrdersTotal(config) { return require('./order/utils/order').getC
72
72
  const correctAllPriceMismatches = lazyShim('./order/utils/order', 'correctAllPriceMismatches');
73
73
  const isOrderOnChain = lazyShim('./order/utils/order', 'isOrderOnChain');
74
74
  const parseChainOrder = lazyShim('./order/utils/order', 'parseChainOrder');
75
- const parseSlotIndex = lazyShim('./order/utils/order', 'parseSlotIndex');
75
+ const parseSlotIndex = lazyShim('./order/utils/slot', 'parseSlotIndex');
76
76
  const CODE_ROOT = path.join(__dirname, '..');
77
77
  const PROFILES_DIR = PATHS.PROFILES_DIR;
78
78
  const PROFILES_BOTS_FILE = PATHS.PROFILES.BOTS_JSON;
@@ -2516,6 +2516,19 @@ async function executeMaintenanceLogic(bot, context) {
2516
2516
  }
2517
2517
  }
2518
2518
  }
2519
+ /**
2520
+ * Clear the geometry-bind re-center memory (one re-center per fill pivot).
2521
+ * Called whenever the spread actually heals — a placement or a sustained
2522
+ * in-tolerance run — so a later geometry bind on a *different* pivot starts
2523
+ * with a fresh budget.
2524
+ * @param {Object} bot - DEXBot instance
2525
+ */
2526
+ function clearGeometryResyncMemory(bot) {
2527
+ if (!bot)
2528
+ return;
2529
+ bot._lastGeometryResyncPivotKey = '';
2530
+ bot._geometryResyncWarnedPivotKey = '';
2531
+ }
2519
2532
  /**
2520
2533
  * Out-of-spread persistence watchdog: the never-run-stale backstop.
2521
2534
  *
@@ -2547,6 +2560,7 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2547
2560
  bot._outOfSpreadStaleWarned = false;
2548
2561
  bot._outOfSpreadTransientCount = 0;
2549
2562
  bot._outOfSpreadToleranceSince = 0;
2563
+ clearGeometryResyncMemory(bot);
2550
2564
  try {
2551
2565
  bot.manager._spreadRailOversubscribed = null;
2552
2566
  }
@@ -2572,6 +2586,7 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2572
2586
  bot._outOfSpreadStaleWarned = false;
2573
2587
  bot._outOfSpreadTransientCount = 0;
2574
2588
  bot._outOfSpreadToleranceSince = 0;
2589
+ clearGeometryResyncMemory(bot);
2575
2590
  try {
2576
2591
  bot.manager._spreadRailOversubscribed = null;
2577
2592
  }
@@ -2623,19 +2638,49 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2623
2638
  ? Number(TIMING.SPREAD_STALE_FUND_ESCALATE_MS)
2624
2639
  : 5 * 60 * 1000;
2625
2640
  // The geometry bind has its own (longer than funds, shorter than structural)
2626
- // window: the sell window is behind the last sale, which only a re-center
2627
- // repairs.
2641
+ // window: the window is behind the last fill, which a re-center repairs by
2642
+ // re-deriving the center AROUND that same fill. Capped at ONE re-center per
2643
+ // pivot value: the re-center does not move the pivot, so a second attempt on
2644
+ // the same fill re-derives the same veto (the pivot can sit outside the new
2645
+ // grid's placeable side when the market has moved far away) and would only
2646
+ // cancel/re-place the new generation every cooldown. Until a fill refreshes
2647
+ // the pivot (or it expires), the honest repair is a fill — so report once
2648
+ // and stop.
2628
2649
  const geometryBlocked = bot._spreadCorrectionStall === 'last-fill-blocked';
2650
+ let geometryPivotKey = '';
2651
+ if (geometryBlocked) {
2652
+ try {
2653
+ const ref = resolveLastFillGuardReference(bot.manager);
2654
+ if (ref?.price != null && Number.isFinite(Number(ref.price)))
2655
+ geometryPivotKey = `${Number(ref.price)}|${String(ref.type ?? '')}`;
2656
+ }
2657
+ catch {
2658
+ geometryPivotKey = '';
2659
+ }
2660
+ }
2661
+ const geometryAlreadyRecentered = geometryBlocked && !!geometryPivotKey
2662
+ && bot._lastGeometryResyncPivotKey === geometryPivotKey;
2629
2663
  const geometryEscalateMs = Number(TIMING?.SPREAD_STALE_GEOMETRY_ESCALATE_MS) > 0
2630
2664
  ? Number(TIMING.SPREAD_STALE_GEOMETRY_ESCALATE_MS)
2631
2665
  : 10 * 60 * 1000;
2632
2666
  const escalateMs = oversubscribedFresh
2633
2667
  ? fundEscalateMs
2634
- : geometryBlocked
2635
- ? geometryEscalateMs
2636
- : (Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2637
- ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2638
- : 30 * 60 * 1000);
2668
+ : geometryAlreadyRecentered
2669
+ // Do not re-center again for the same fill. Out of the escalation
2670
+ // ladder entirely: a fill (or the pivot TTL) is the only heal.
2671
+ ? Number.POSITIVE_INFINITY
2672
+ : geometryBlocked
2673
+ ? geometryEscalateMs
2674
+ : (Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2675
+ ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2676
+ : 30 * 60 * 1000);
2677
+ if (geometryAlreadyRecentered && staleMs >= warnMs && bot._geometryResyncWarnedPivotKey !== geometryPivotKey) {
2678
+ bot._geometryResyncWarnedPivotKey = geometryPivotKey;
2679
+ bot._log(`[SPREAD-STALE] Still out of tolerance ${staleMin}min after re-centering on fill pivot ` +
2680
+ `${geometryPivotKey.split('|')[0]}: the pivot is outside this generation's placeable side, so a re-center ` +
2681
+ `cannot clear it. A fill (buy back below / sell above the pivot) or pivot expiry restores the side; ` +
2682
+ `no further re-center will be requested for this pivot.`, 'warn');
2683
+ }
2639
2684
  if (staleMs >= warnMs && !bot._outOfSpreadStaleWarned) {
2640
2685
  bot._outOfSpreadStaleWarned = true;
2641
2686
  const stall = bot._spreadCorrectionStall ? `, stall=${bot._spreadCorrectionStall}` : '';
@@ -2655,6 +2700,8 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2655
2700
  const lastAt = Number(bot._lastSpreadStaleResyncAt) || 0;
2656
2701
  if (now - lastAt >= cooldownMs) {
2657
2702
  bot._lastSpreadStaleResyncAt = now;
2703
+ if (geometryBlocked && geometryPivotKey)
2704
+ bot._lastGeometryResyncPivotKey = geometryPivotKey;
2658
2705
  bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min despite corrections` +
2659
2706
  `${oversubscribedFresh ? ' (rail oversubscribed — re-sizing from chain truth)' : ''}` +
2660
2707
  `${geometryBlocked ? ' (sell window behind the last fill — re-centering)' : ''}` +
@@ -616,7 +616,13 @@ async function finishStartupSequence(bot, startupState) {
616
616
  }
617
617
  else {
618
618
  bot._log('Found active session. Loading and syncing existing grid.');
619
- await botGridModule(bot).loadGrid(bot.manager, persistedGrid, persistedBoundaryIdx, persistedGenesis);
619
+ // Pure in-band stranding is the transient SPREAD-GUARD /
620
+ // partial-fill-anchor state, not snapshot poison: the
621
+ // re-anchor deliberately leaves the fill's own PARTIAL
622
+ // residual inside the band until GAP-EVAC clears it.
623
+ // Keep the persisted boundary (warn + load) exactly like
624
+ // the recovery path; a rebuild here would undo the repair.
625
+ await botGridModule(bot).loadGrid(bot.manager, persistedGrid, persistedBoundaryIdx, persistedGenesis, { tolerateTransientStranding: true });
620
626
  // Phase 3 restart resilience: restore persisted gap-evacuation
621
627
  // streaks (pruned to surviving slots) so an order stranded
622
628
  // in-band across frequent restarts still reaches the cancel
@@ -40,8 +40,8 @@
40
40
  * 6. Log shutdown status
41
41
  * 7. Exit process
42
42
  *
43
- * USAGE:
44
- * const { registerCleanup } = require('./modules/graceful_shutdown');
43
+ * USAGE (from the repo root):
44
+ * import { registerCleanup } from './modules/graceful_shutdown.js';
45
45
  *
46
46
  * // Register cleanups (executed in reverse order on shutdown)
47
47
  * registerCleanup('Database', async () => db.close());
@@ -40,8 +40,8 @@
40
40
  * 6. Log shutdown status
41
41
  * 7. Exit process
42
42
  *
43
- * USAGE:
44
- * const { registerCleanup } = require('./modules/graceful_shutdown');
43
+ * USAGE (from the repo root):
44
+ * import { registerCleanup } from './modules/graceful_shutdown.js';
45
45
  *
46
46
  * // Register cleanups (executed in reverse order on shutdown)
47
47
  * registerCleanup('Database', async () => db.close());
@@ -1,4 +1,4 @@
1
- export type RuntimeMode = 'monolithic' | 'isolated' | 'pm2' | 'none';
1
+ type RuntimeMode = 'monolithic' | 'isolated' | 'pm2' | 'none';
2
2
  export interface Pm2Proc {
3
3
  pid?: number | string;
4
4
  name?: string;
@@ -28,7 +28,7 @@ export interface RuntimeInfo {
28
28
  }
29
29
  /** True when `name` matches a configured bot (case-insensitive). */
30
30
  export declare function isConfiguredBotName(name: string): boolean;
31
- export interface StatusTargetCheck {
31
+ interface StatusTargetCheck {
32
32
  error: string | null;
33
33
  notice: string | null;
34
34
  }
@@ -38,7 +38,7 @@ export interface StatusTargetCheck {
38
38
  * one is rejected — the same contract the unlock control path applies.
39
39
  */
40
40
  export declare function checkStatusTarget(target?: string | null): StatusTargetCheck;
41
- export type StatusRoute = 'unlock' | 'pm2' | 'empty';
41
+ type StatusRoute = 'unlock' | 'pm2' | 'empty';
42
42
  /**
43
43
  * Which branch `dexbot status` takes. PM2 wins when PM2 bots are running (even
44
44
  * if a stray credential daemon lingers) so the report and the help banner name
@@ -76,4 +76,5 @@ export interface RuntimeHelpEntry {
76
76
  * so the reference is always complete before anything is running.
77
77
  */
78
78
  export declare function runtimeControlHelp(mode: RuntimeMode): RuntimeHelpEntry[];
79
+ export {};
79
80
  //# sourceMappingURL=runtime_mode.d.ts.map
@@ -30,7 +30,7 @@
30
30
  *
31
31
  * In bitshares_client.ts:
32
32
  *
33
- * const NodeManager = require('./node_manager').default;
33
+ * import NodeManager from './node_manager.js';
34
34
  * const nodeManager = new NodeManager(config);
35
35
  * await nodeManager.checkAllNodes();
36
36
  * const bestNode = nodeManager.getBestNode();
@@ -30,7 +30,7 @@
30
30
  *
31
31
  * In bitshares_client.ts:
32
32
  *
33
- * const NodeManager = require('./node_manager').default;
33
+ * import NodeManager from './node_manager.js';
34
34
  * const nodeManager = new NodeManager(config);
35
35
  * await nodeManager.checkAllNodes();
36
36
  * const bestNode = nodeManager.getBestNode();
@@ -88,7 +88,8 @@ import { createRequire } from 'node:module';
88
88
  const require = createRequire(import.meta.url);
89
89
  import { ORDER_TYPES, ORDER_STATES, PIPELINE_TIMING, TIMING, FEE_PARAMETERS, GRID_LIMITS } from '../constants.js';
90
90
  import { resolveAccountRef } from './utils/system.js';
91
- import { resolveSpreadOrderSide, parseSlotIndex, parseChainOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, resolveEdgeCount } from './utils/order.js';
91
+ import { resolveSpreadOrderSide, parseChainOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, resolveEdgeCount } from './utils/order.js';
92
+ import { parseSlotIndex } from './utils/slot.js';
92
93
  import { isSlotInRail, floatToBlockchainInt } from './utils/math.js';
93
94
  import * as Format from './format.js';
94
95
  import * as fundRegistry from '../fund_registry.js';
@@ -4,8 +4,8 @@
4
4
  * Trading history extraction and CSV export engine.
5
5
  * Parses PM2 log files to extract trading fills and exports to standardized format.
6
6
  *
7
- * Usage:
8
- * const exporter = require('./order/export');
7
+ * Usage (from the repo root):
8
+ * import * as exporter from './modules/order/export.js';
9
9
  * const result = await exporter.exportBotTrades(botKey, botConfig, outputDir);
10
10
  *
11
11
  * Output Format:
@@ -4,8 +4,8 @@
4
4
  * Trading history extraction and CSV export engine.
5
5
  * Parses PM2 log files to extract trading fills and exports to standardized format.
6
6
  *
7
- * Usage:
8
- * const exporter = require('./order/export');
7
+ * Usage (from the repo root):
8
+ * import * as exporter from './modules/order/export.js';
9
9
  * const result = await exporter.exportBotTrades(botKey, botConfig, outputDir);
10
10
  *
11
11
  * Output Format:
@@ -103,12 +103,22 @@
103
103
  *
104
104
  * ===============================================================================
105
105
  */
106
+ interface SpreadCorrectionRotation {
107
+ id: string;
108
+ orderId: string;
109
+ oldOrder: ManagedOrder;
110
+ newGridId: string;
111
+ newPrice: number;
112
+ newSize: number;
113
+ type: OrderType;
114
+ }
106
115
  interface SpreadCorrection {
107
116
  ordersToPlace: ManagedOrder[];
108
117
  ordersToUpdate: Array<{
109
118
  partialOrder: ManagedOrder;
110
119
  newSize: number;
111
120
  }>;
121
+ ordersToRotate?: SpreadCorrectionRotation[];
112
122
  plannedCount?: number;
113
123
  stallHint?: SpreadCorrectionStall;
114
124
  boundaryIdx?: number;
@@ -145,7 +155,7 @@ export declare const SPREAD_CORRECTION_REFUSAL: Readonly<{
145
155
  /** Unclassified non-execution (fallback). */
146
156
  readonly BATCH_NOT_EXECUTED: "batch-not-executed";
147
157
  }>;
148
- export type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
158
+ type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
149
159
  /**
150
160
  * Whether a refusal cause is retryable by the bounded spread-correction re-plan.
151
161
  * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
@@ -169,13 +179,6 @@ export declare function classifySpreadRefusalCause(batchResult: unknown): Spread
169
179
  * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
170
180
  */
171
181
  export declare function recordSpreadCorrectionRefusal(manager: OrderManagerLike, cause: SpreadCorrectionRefusalCause): void;
172
- /**
173
- * P5 observability: count a bounded spread-correction re-plan retry. Churn
174
- * signal — a rising retry rate means concurrent commits are repeatedly
175
- * invalidating corrections. Counter-only; never throws.
176
- * @param {Object} manager - OrderManager instance
177
- */
178
- export declare function recordSpreadCorrectionRetry(manager: OrderManagerLike): void;
179
182
  /**
180
183
  * P2 plan-time dedupe: which of a correction's planned CREATE destinations are
181
184
  * now occupied by a live (ACTIVE/PARTIAL) order with a chain id?
@@ -196,11 +199,12 @@ export declare function getOccupiedCorrectionSlots(manager: OrderManagerLike, co
196
199
  /**
197
200
  * P1/P3 shared re-plan: derive a spread correction from the CURRENT master
198
201
  * state (side chosen from fresh on-chain book, opposite-side starvation
199
- * fallback). Used both for the plan-time collision dedupe and the bounded
200
- * refusal retry. Read-only against the grid; no _gridLock needed (matches the
201
- * existing TOCTOU fund re-plan contract).
202
+ * fallback). A zero-free decision still tries the rotation-only fallback.
203
+ * Used both for the plan-time collision dedupe and the bounded refusal retry.
204
+ * Read-only against the grid; no _gridLock needed (matches the existing TOCTOU
205
+ * fund re-plan contract).
202
206
  * @param {Object} manager - OrderManager instance
203
- * @returns {Promise<Object|null>} A correction with at least one create, or null
207
+ * @returns {Promise<Object|null>} A correction with at least one executable action, or null
204
208
  */
205
209
  export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderManagerLike): Promise<SpreadCorrection | null>;
206
210
  /**
@@ -209,7 +213,7 @@ export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderMana
209
213
  * - 'replanned': a destination was taken and a fresh correction was derived.
210
214
  * - 'blocked': a destination was taken and no fresh correction exists — refuse.
211
215
  */
212
- export type OccupiedCorrectionResolution = {
216
+ type OccupiedCorrectionResolution = {
213
217
  action: 'broadcast';
214
218
  } | {
215
219
  action: 'replanned';
@@ -696,11 +700,12 @@ export declare function getDustOrders(manager: OrderManagerLike, partials: Manag
696
700
  * @param {import('./types').OrderManager} manager - The manager instance.
697
701
  * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
698
702
  * normalize sell-side funds into buy-side units for a fair cross-asset comparison.
699
- * @returns {{ side: import('./types').OrderType|null, reason: string }} The side to correct on, or null if insufficient funds.
703
+ * @returns {{ side: import('./types').OrderType|null, reason: string, code?: 'market-price-unavailable'|'no-free-funds' }} The side to correct on, or null with a structured cause.
700
704
  */
701
705
  export declare function determineOrderSideByFunds(manager: OrderManagerLike, currentMarketPrice: number): {
702
706
  side: OrderType | null;
703
707
  reason: string;
708
+ code?: 'market-price-unavailable' | 'no-free-funds';
704
709
  };
705
710
  /**
706
711
  * Prepares one or more orders to correct a wide spread.