dexbot 1.6.12 → 1.6.14

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 (213) hide show
  1. package/CHANGELOG.md +65 -1
  2. package/README.md +2 -2
  3. package/analysis/README.md +9 -11
  4. package/analysis/ama_fitting/README.md +5 -3
  5. package/claw/README.md +1 -0
  6. package/claw/docs/AI_BOT_LIBRARY_API.md +3 -1
  7. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  8. package/claw/modules/claw_bridge.ts +0 -3
  9. package/claw/modules/claw_catalog.ts +8 -4
  10. package/claw/modules/claw_skill_md.ts +1 -0
  11. package/claw/modules/dexbot_profiles.ts +59 -15
  12. package/claw/modules/types.ts +2 -1
  13. package/claw/package.json +3 -3
  14. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  15. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  16. package/claw/skills/margin-trading/SKILL.md +1 -1
  17. package/claw/skills/margin-trading/references/position-management.md +1 -1
  18. package/claw/tsconfig.json +2 -2
  19. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +1 -14
  20. package/dist/analysis/ama_fitting/fetch_lp_candles.js +51 -41
  21. package/dist/analysis/ama_fitting/generate_unified_comparison_chart.d.ts +1 -24
  22. package/dist/analysis/ama_fitting/generate_unified_comparison_chart.js +36 -18
  23. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +18 -66
  24. package/dist/analysis/analyze_args.d.ts +12 -0
  25. package/dist/analysis/analyze_args.js +20 -0
  26. package/dist/analysis/bot_fitting/backtest_ama_sweep.d.ts +1 -16
  27. package/dist/analysis/bot_fitting/backtest_ama_sweep.js +20 -101
  28. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +26 -92
  29. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.js +19 -34
  30. package/dist/analysis/bot_fitting/shared_utils.d.ts +71 -3
  31. package/dist/analysis/bot_fitting/shared_utils.js +124 -8
  32. package/dist/analysis/chart_ui.d.ts +30 -1
  33. package/dist/analysis/chart_ui.js +37 -1
  34. package/dist/analysis/fills_cache.d.ts +3 -23
  35. package/dist/analysis/fills_cache.js +3 -84
  36. package/dist/analysis/fills_source.d.ts +31 -1
  37. package/dist/analysis/fills_source.js +69 -1
  38. package/dist/analysis/grid_correction_check.d.ts +1 -23
  39. package/dist/analysis/grid_correction_check.js +15 -58
  40. package/dist/analysis/math_utils.d.ts +85 -1
  41. package/dist/analysis/math_utils.js +116 -1
  42. package/dist/analysis/price_sources.d.ts +22 -1
  43. package/dist/analysis/price_sources.js +23 -0
  44. package/dist/analysis/resolve_source.js +31 -10
  45. package/dist/analysis/trade_profitability.d.ts +6 -0
  46. package/dist/analysis/trade_profitability.js +23 -97
  47. package/dist/analysis/tradingview/analyze_tradingview.d.ts +1 -17
  48. package/dist/analysis/tradingview/analyze_tradingview.js +1 -1
  49. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +27 -40
  50. package/dist/analysis/trend_detection/backtest_ama_slope_huber.d.ts +1 -101
  51. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +22 -80
  52. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +11 -37
  53. package/dist/analysis/trend_detection/volatility_chart_generator.js +9 -10
  54. package/dist/analysis/worker_pool.d.ts +38 -0
  55. package/dist/analysis/worker_pool.js +67 -0
  56. package/dist/dexbot.js +67 -48
  57. package/dist/market_adapter/ama_signal_runner.js +21 -54
  58. package/dist/market_adapter/candle_utils.d.ts +7 -1
  59. package/dist/market_adapter/candle_utils.js +11 -1
  60. package/dist/market_adapter/cli_args.d.ts +22 -0
  61. package/dist/market_adapter/cli_args.js +30 -0
  62. package/dist/market_adapter/core/config_normalizers.js +11 -6
  63. package/dist/market_adapter/core/kibana_candles.d.ts +3 -1
  64. package/dist/market_adapter/core/kibana_candles.js +3 -2
  65. package/dist/market_adapter/core/market_adapter_service.d.ts +85 -85
  66. package/dist/market_adapter/core/market_adapter_service.js +93 -158
  67. package/dist/market_adapter/core/signals/hurst_analyzer.d.ts +1 -6
  68. package/dist/market_adapter/core/signals/hurst_analyzer.js +1 -1
  69. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.d.ts +1 -11
  70. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.js +1 -1
  71. package/dist/market_adapter/inputs/fetch_book_data.js +0 -1
  72. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +63 -107
  73. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +8 -1
  74. package/dist/market_adapter/inputs/fetch_lp_data.js +25 -7
  75. package/dist/market_adapter/inputs/kibana_feed_source.js +4 -26
  76. package/dist/market_adapter/inputs/window_cache.d.ts +4 -72
  77. package/dist/market_adapter/inputs/window_cache.js +52 -177
  78. package/dist/market_adapter/interval_utils.d.ts +11 -1
  79. package/dist/market_adapter/interval_utils.js +16 -1
  80. package/dist/market_adapter/lp_chart_runner.d.ts +3 -0
  81. package/dist/market_adapter/lp_chart_runner.js +37 -19
  82. package/dist/market_adapter/market_adapter.js +27 -72
  83. package/dist/market_adapter/utils/data_discovery.d.ts +45 -1
  84. package/dist/market_adapter/utils/data_discovery.js +220 -27
  85. package/dist/market_adapter/utils/month_shards.d.ts +84 -0
  86. package/dist/market_adapter/utils/month_shards.js +237 -0
  87. package/dist/modules/account_bots.d.ts +8 -6
  88. package/dist/modules/account_bots.js +112 -131
  89. package/dist/modules/account_orders.d.ts +49 -4
  90. package/dist/modules/account_orders.js +114 -49
  91. package/dist/modules/bitshares-native/chain_client.d.ts +1 -1
  92. package/dist/modules/bitshares-native/chain_client.js +14 -13
  93. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  94. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  95. package/dist/modules/bitshares-native/resolvers.js +22 -25
  96. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  97. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  98. package/dist/modules/bitshares-native/serial/types.js +22 -50
  99. package/dist/modules/bitshares-native/signing_client.d.ts +1 -1
  100. package/dist/modules/bot_defaults.d.ts +18 -3
  101. package/dist/modules/bot_defaults.js +34 -8
  102. package/dist/modules/bot_settings.d.ts +5 -1
  103. package/dist/modules/bot_settings.js +55 -21
  104. package/dist/modules/broadcast_failure.d.ts +2 -1
  105. package/dist/modules/chain_orders.d.ts +1 -1
  106. package/dist/modules/chain_orders.js +51 -96
  107. package/dist/modules/cli_start_onboarding.d.ts +2 -1
  108. package/dist/modules/config.js +6 -1
  109. package/dist/modules/constants.d.ts +14 -6
  110. package/dist/modules/constants.js +32 -6
  111. package/dist/modules/cr_planner.d.ts +1 -1
  112. package/dist/modules/cr_planner.js +1 -5
  113. package/dist/modules/credit_pricing.d.ts +2 -1
  114. package/dist/modules/credit_pricing.js +36 -40
  115. package/dist/modules/credit_runtime.d.ts +7 -0
  116. package/dist/modules/credit_runtime.js +45 -73
  117. package/dist/modules/daemon_node_health.d.ts +4 -3
  118. package/dist/modules/dexbot_class.d.ts +33 -17
  119. package/dist/modules/dexbot_class.js +113 -61
  120. package/dist/modules/dexbot_cow_runtime.d.ts +62 -181
  121. package/dist/modules/dexbot_cow_runtime.js +380 -69
  122. package/dist/modules/dexbot_credential_client.d.ts +1 -23
  123. package/dist/modules/dexbot_credential_client.js +2 -3
  124. package/dist/modules/dexbot_fill_runtime.d.ts +2 -3
  125. package/dist/modules/dexbot_fill_runtime.js +17 -7
  126. package/dist/modules/dexbot_maintenance_runtime.d.ts +36 -81
  127. package/dist/modules/dexbot_maintenance_runtime.js +137 -133
  128. package/dist/modules/dexbot_startup_runtime.d.ts +0 -1
  129. package/dist/modules/dexbot_startup_runtime.js +25 -14
  130. package/dist/modules/dexbot_state_recovery.js +16 -0
  131. package/dist/modules/general_settings.d.ts +1 -1
  132. package/dist/modules/graceful_shutdown.js +17 -11
  133. package/dist/modules/key_store.d.ts +0 -5
  134. package/dist/modules/key_store.js +1 -2
  135. package/dist/modules/lazy_shim.d.ts +11 -0
  136. package/dist/modules/lazy_shim.js +16 -0
  137. package/dist/modules/node_connect_policy.d.ts +3 -2
  138. package/dist/modules/node_failure_ledger.d.ts +6 -5
  139. package/dist/modules/order/accounting.js +11 -11
  140. package/dist/modules/order/export.js +2 -2
  141. package/dist/modules/order/format.d.ts +26 -3
  142. package/dist/modules/order/format.js +33 -3
  143. package/dist/modules/order/genesis_policy.d.ts +4 -4
  144. package/dist/modules/order/genesis_policy.js +6 -3
  145. package/dist/modules/order/grid.d.ts +26 -12
  146. package/dist/modules/order/grid.js +468 -80
  147. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  148. package/dist/modules/order/grid_reconcile.js +5 -5
  149. package/dist/modules/order/grid_reconcile_internal.js +48 -40
  150. package/dist/modules/order/index.d.ts +35 -8
  151. package/dist/modules/order/logger.d.ts +1 -8
  152. package/dist/modules/order/logger.js +2 -11
  153. package/dist/modules/order/manager.d.ts +18 -15
  154. package/dist/modules/order/manager.js +91 -74
  155. package/dist/modules/order/strategy.d.ts +2 -2
  156. package/dist/modules/order/strategy.js +51 -21
  157. package/dist/modules/order/sync_engine.js +4 -0
  158. package/dist/modules/order/utils/math.d.ts +3 -3
  159. package/dist/modules/order/utils/math.js +38 -27
  160. package/dist/modules/order/utils/order.d.ts +58 -58
  161. package/dist/modules/order/utils/order.js +158 -137
  162. package/dist/modules/order/utils/system.d.ts +202 -35
  163. package/dist/modules/order/utils/system.js +409 -31
  164. package/dist/modules/order/utils/validate.js +28 -6
  165. package/dist/modules/order/utils/withPoolRef.d.ts +2 -1
  166. package/dist/modules/paths.js +32 -34
  167. package/dist/modules/runtime_settings.d.ts +3 -5
  168. package/dist/modules/runtime_settings.js +3 -3
  169. package/dist/modules/settings_merge.d.ts +2 -2
  170. package/dist/modules/socket_json_client.d.ts +2 -1
  171. package/dist/modules/types.d.ts +89 -30
  172. package/dist/modules/utils/errors.js +1 -3
  173. package/dist/modules/version_notice.d.ts +11 -10
  174. package/dist/pm2.d.ts +0 -1
  175. package/dist/pm2.js +56 -35
  176. package/dist/scripts/analyze-git.js +2 -15
  177. package/dist/scripts/analyze-orders.d.ts +1 -1
  178. package/dist/scripts/analyze-orders.js +4 -4
  179. package/dist/scripts/chart_command.js +2 -2
  180. package/dist/scripts/check_any.d.ts +4 -0
  181. package/dist/scripts/check_any.js +53 -21
  182. package/dist/scripts/diagnose-pool-history.js +1 -6
  183. package/dist/scripts/divergence-calc.js +6 -6
  184. package/dist/scripts/run-tests.js +0 -1
  185. package/dist/scripts/sync-version.js +0 -10
  186. package/dist/scripts/validate_bots.d.ts +1 -1
  187. package/dist/scripts/validate_bots.js +3 -3
  188. package/dist/unlock.js +7 -2
  189. package/docs/BITSHARES_ONBOARDING.md +8 -12
  190. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +2 -3
  191. package/docs/COW_INVARIANTS.md +6 -6
  192. package/docs/DEXBOT_COMPARISON.md +7 -7
  193. package/docs/EVOLUTION.md +10 -8
  194. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  195. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  196. package/docs/GRID_RECALCULATION.md +4 -1
  197. package/docs/GRID_RECONCILE.md +4 -4
  198. package/docs/LIFECYCLE.md +11 -11
  199. package/docs/LOGGING.md +14 -0
  200. package/docs/MPA_CREDIT_USAGE.md +1 -1
  201. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +12 -4
  202. package/docs/README.md +3 -3
  203. package/docs/WORKFLOW.md +1 -0
  204. package/docs/architecture.md +25 -16
  205. package/docs/developer_guide.md +7 -2
  206. package/market_adapter/README.md +6 -4
  207. package/package.json +6 -9
  208. package/scripts/README.md +43 -38
  209. package/tests/README.md +26 -11
  210. package/dist/scripts/diagnose-kibana-candles.d.ts +0 -3
  211. package/dist/scripts/diagnose-kibana-candles.js +0 -82
  212. package/scripts/git-viewer.sh +0 -489
  213. package/scripts/postinstall.js +0 -16
@@ -72,7 +72,7 @@ export interface PoolEntry {
72
72
  reserves?: PoolReserve[];
73
73
  [key: string]: unknown;
74
74
  }
75
- export interface BitSharesDb {
75
+ interface BitSharesDb {
76
76
  lookup_asset_symbols?: (refs: string[]) => Promise<unknown[]>;
77
77
  get_assets?: (refs: string[]) => Promise<unknown[]>;
78
78
  get_objects?: (ids: string[]) => Promise<unknown[]>;
@@ -96,7 +96,7 @@ export interface BitSharesDb {
96
96
  call?: (method: string, args: unknown[]) => Promise<unknown>;
97
97
  [key: string]: unknown;
98
98
  }
99
- export interface BitSharesAssets {
99
+ interface BitSharesAssets {
100
100
  [symbol: string]: Promise<unknown> | unknown;
101
101
  }
102
102
  export interface BitSharesClient {
@@ -189,15 +189,6 @@ export declare function derivePriceWithBridges(BitShares: BitSharesClient, symA:
189
189
  rate: number;
190
190
  path: string;
191
191
  } | null>;
192
- export interface ExtendedAssetMeta extends AssetMeta {
193
- current_supply?: number | string | {
194
- amount?: number;
195
- value?: number;
196
- };
197
- dynamic_asset_data_id?: string;
198
- dynamicDataId?: string;
199
- dynamic_data_id?: string;
200
- }
201
192
  /**
202
193
  * Derive the value of a liquidity pool share token in a denomination asset.
203
194
  * Resolves the pool, fetches reserves and supply, then prices both pool assets
@@ -252,12 +243,6 @@ export declare function loadAmaCenterSnapshot(botKey: string): AmaCenterSnapshot
252
243
  * @returns {number|null} Grid center price in B/A format, or null if file absent/invalid
253
244
  */
254
245
  export declare function loadAmaCenterPrice(botKey: string): number | null;
255
- export interface AssetOptions {
256
- flags?: number | string;
257
- market_fee_percent?: number;
258
- taker_fee_percent?: number;
259
- max_market_fee?: number | string;
260
- }
261
246
  export interface FeeCacheEntryData {
262
247
  assetId?: string;
263
248
  symbol?: string;
@@ -290,18 +275,6 @@ export interface FeeCacheEntryData {
290
275
  };
291
276
  makerFeeDiscountPercent?: number;
292
277
  }
293
- export interface GlobalProps {
294
- parameters?: {
295
- current_fees?: {
296
- parameters?: Array<[number, {
297
- fee?: number | string;
298
- }]>;
299
- };
300
- extensions?: {
301
- maker_fee_discount_percent?: number;
302
- };
303
- };
304
- }
305
278
  /**
306
279
  * Initialize fee cache from blockchain.
307
280
  * Fetches BTS operation fees and asset market fees for all unique assets in config.
@@ -342,16 +315,186 @@ export declare function persistGridSnapshot(manager: OrderManagerLike, accountOr
342
315
  * @returns {number} Number of streak entries restored
343
316
  */
344
317
  export declare function restoreGapEvacStreaks(manager: OrderManagerLike, persisted: unknown): number;
318
+ /** Why spread correction is degraded or refused for a cycle. */
319
+ export type SpreadCorrectionRefusalReason = 'cold-book' | 'stale-snapshot' | 'unmatched-orders';
320
+ export interface SpreadCorrectionReadiness {
321
+ /** False => hard refusal (cold book): the planner must not act this cycle. */
322
+ ok: boolean;
323
+ /** Degraded cause ('stale-snapshot'/'unmatched-orders') or hard cause ('cold-book'). */
324
+ reason: SpreadCorrectionRefusalReason | null;
325
+ /**
326
+ * Crossing floor for the planner's filter: the freshest live market read
327
+ * when available, else the fill-derived reference. null => no floor
328
+ * (fail-open). Not a refusal premise.
329
+ */
330
+ marketRef: number | null;
331
+ /** Fill-derived reference only (live pivot or persisted row); gates the COW bypass. */
332
+ fillMarketRef: number | null;
333
+ /** False => the local snapshot cannot license the LAST-FILL-GUARD bypass. */
334
+ snapshotTrusted: boolean;
335
+ /** Known-unmatched chain orders from the last sync (price-level collision filter input). */
336
+ unmatched: UnmatchedChainOrderLike[];
337
+ }
338
+ /** Narrowed read-only view of an unmatched chain order used by the readiness gate. */
339
+ export interface UnmatchedChainOrderLike extends Record<string, unknown> {
340
+ price?: number;
341
+ orderId?: string;
342
+ chainOrderId?: string;
343
+ }
344
+ /**
345
+ * The single freshness window shared by the spread-correction trust decisions
346
+ * that are time-based: snapshot staleness (and therefore the COW bypass) and
347
+ * the live-market-price refresh pacing. Resolved once so a per-bot
348
+ * `config.timing` override cannot make one check trust what another rejects.
349
+ * The crossing floor itself does NOT use a time window — it picks the newer
350
+ * of the live read and the fill.
351
+ *
352
+ * 0 (constant unset) => no time bound: staleness never triggers and the
353
+ * live-price refresh is never forced, so the crossing floor stays on the fill
354
+ * anchor. Fail-open, matching the never-synced first-tick behavior.
355
+ *
356
+ * @param {Object} manager - OrderManager instance
357
+ * @returns {number} Freshness window in ms (0 => no bound => fail-open)
358
+ */
359
+ export declare function resolveSpreadFreshnessMs(manager: OrderManagerLike): number;
360
+ /**
361
+ * Resolve the crossing floor spread correction must not trade through.
362
+ *
363
+ * Two pieces of real market evidence can supply the floor: an externally
364
+ * observed live price (order book/ticker) and the fill-derived reference
365
+ * (last account trade). Neither is judged by a threshold — the NEWER one wins.
366
+ * A live read older than the last fill loses to the fill (an executed trade is
367
+ * fresher market truth); a live read at least as new wins; with no live read
368
+ * at all the fill is used; with neither the floor is null (fail-open).
369
+ *
370
+ * This is what lets us drop the arbitrary "how far is too far" distance cap:
371
+ * we keep the floor fresh and compare evidence by recency, rather than guessing
372
+ * when an old floor went stale.
373
+ *
374
+ * @param {Object} manager - OrderManager instance
375
+ * @returns {number|null} Crossing floor or null (fail-open)
376
+ */
377
+ export declare function resolveSpreadCrossingFloor(manager: OrderManagerLike): number | null;
378
+ /**
379
+ * Refresh the cached live market price from the order book/ticker.
380
+ * Best-effort; caches only a finite positive price. Returns the new price or
381
+ * null. Call through maybeRefreshLiveMarketPrice to respect the pacing bound.
382
+ *
383
+ * @param {Object} manager - OrderManager instance
384
+ * @param {unknown} BitShares - BitShares client
385
+ * @returns {Promise<number|null>} New price or null
386
+ */
387
+ export declare function refreshLiveMarketPrice(manager: OrderManagerLike, BitShares: unknown): Promise<number | null>;
388
+ /**
389
+ * Refresh the live market price if none is fresh, pacing attempts to one per
390
+ * freshness window so a chain that keeps failing cannot turn the spread check
391
+ * into an RPC loop. The spread path stays RPC-free while the cache is fresh.
392
+ *
393
+ * @param {Object} manager - OrderManager instance
394
+ * @param {unknown} BitShares - BitShares client
395
+ * @param {Object} [options]
396
+ * @param {number} [options.now] - Injectable clock (tests)
397
+ * @returns {Promise<number|null>} Cached/new price or null
398
+ */
399
+ export declare function maybeRefreshLiveMarketPrice(manager: OrderManagerLike, BitShares: unknown, options?: {
400
+ now?: number;
401
+ }): Promise<number | null>;
402
+ /**
403
+ * Evaluate whether spread correction may act on the current local snapshot,
404
+ * in ONE place. Pure: reads manager state, returns a verdict, no side effects;
405
+ * the caller maps the reason to a stall and the existing wiring arms the
406
+ * targeted sync.
407
+ *
408
+ * Premises:
409
+ * - P-A cold book (no live order on either side): `ok=false` — hard refusal,
410
+ * there is no realized spread to repair and only the reconcile path owns
411
+ * the first window. Requires `options.onChainOrders`; skipped otherwise.
412
+ * - P-B stale snapshot (a completed sync is older than the freshness window):
413
+ * degraded-ok — the planner may still act, but `snapshotTrusted=false` so
414
+ * the LAST-FILL-GUARD bypass is withheld. Never-synced is treated as fresh
415
+ * (historical fail-open for the first tick).
416
+ * - P-C known-unmatched chain orders: degraded-ok — plan, but the collision
417
+ * filter drops their price levels and `snapshotTrusted=false`.
418
+ *
419
+ * The market anchor is deliberately NOT a refusal premise — it is returned for
420
+ * the crossing filter, and a real fill denies the bypass via `fillMarketRef`.
421
+ *
422
+ * @param {Object} manager - OrderManager instance
423
+ * @param {Object} [options]
424
+ * @param {number} [options.now] - Injectable clock (tests)
425
+ * @param {Object|null} [options.onChainOrders] - Live local window view; enables P-A
426
+ * @returns {SpreadCorrectionReadiness} Readiness verdict
427
+ */
428
+ export declare function evaluateSpreadCorrectionReadiness(manager: OrderManagerLike, options?: {
429
+ now?: number;
430
+ onChainOrders?: {
431
+ buys: unknown[];
432
+ sells: unknown[];
433
+ } | null;
434
+ }): SpreadCorrectionReadiness;
435
+ /**
436
+ * Resolve the last real FILL price — the fill-derived market reference.
437
+ * Returns null (fail-open) when no real fill is known.
438
+ *
439
+ * The bot's grid anchor (AMA/startPrice) and its own book mid are NOT market
440
+ * references — they are grid geometry or the bot's own quotes — so they are
441
+ * deliberately not used here. Only a real fill price qualifies: the live
442
+ * LAST-FILL-GUARD pivot when it is fill-provenanced, else the bot-scoped
443
+ * persisted reference that survives grid regeneration.
444
+ *
445
+ * Feeds the COW bypass gate (via the readiness verdict's `fillMarketRef`) and
446
+ * is the fallback crossing floor when no fresh live market read exists.
447
+ *
448
+ * @param {Object} manager - OrderManager instance
449
+ * @returns {number|null} Reference price or null
450
+ */
451
+ export declare function resolveSpreadMarketReference(manager: OrderManagerLike): number | null;
452
+ /**
453
+ * Resolve the reference the generic LAST-FILL-GUARD judges against.
454
+ *
455
+ * Prefers the live armed pivot. When that is cold (a grid regeneration
456
+ * cleared it, or a rejected-snapshot reset ran) it falls back to the
457
+ * bot-scoped last-market-fill row — the same market truth spread correction
458
+ * already uses. This is what stops a rebuild from silently un-arming the
459
+ * guard until the next fill: the price the account last traded at is known,
460
+ * so a CREATE/rotation must still not cross it.
461
+ *
462
+ * Read-time fallback only: it does NOT mutate the pivot or persist an
463
+ * old-generation value, so the genesis-bound pivot/persist contract is
464
+ * unchanged. The guard still validates the value onto the CURRENT ladder via
465
+ * resolveOnGridPivot at the call site (off-ladder → raw value + warn), so a
466
+ * regenerated geometry stays the authority on which placements are off-grid.
467
+ *
468
+ * @param {Object} manager - OrderManager instance
469
+ * @returns {{price: number|null, type: string|null}} Effective pivot (both null when cold)
470
+ */
471
+ export declare function resolveLastFillGuardReference(manager: OrderManagerLike): {
472
+ price: number | null;
473
+ type: string | null;
474
+ };
475
+ /**
476
+ * Restore the persisted bot-scoped last-market-fill reference into the
477
+ * manager. Deliberately independent of the boundary and the genesis: this is
478
+ * the anchor spread correction uses to avoid trading through the last real
479
+ * fill price, and it must survive a grid regeneration (the genesis-bound
480
+ * LAST-FILL-GUARD pivot does not). TTL-expired rows are erased from disk,
481
+ * mirroring restoreLastFillPivot's dead-row hygiene.
482
+ *
483
+ * @param {Object} manager - OrderManager instance
484
+ * @param {unknown} persisted - {price, type, fillsAt} from loadLastMarketFill
485
+ * @param {Object} [options]
486
+ * @param {number} [options.now] - Injectable clock (tests)
487
+ * @returns {boolean} True when the reference was restored
488
+ */
489
+ export declare function restoreLastMarketFill(manager: OrderManagerLike, persisted: unknown, options?: {
490
+ now?: number;
491
+ }): boolean;
345
492
  /**
346
493
  * Normalize a persisted LAST-FILL-GUARD pivot row (shared by the
347
494
  * AccountOrders sanitizer/loader and the payload builder's row contract).
348
495
  *
349
- * Returns the row normalized to {price:number, type, fillsAt:number,
350
- * genesisHash} when every field passes its gate, null otherwise:
351
- * - finite price > 0
352
- * - type is ORDER_TYPES.BUY or ORDER_TYPES.SELL
353
- * - finite fillsAt > 0
354
- * - non-empty string genesisHash
496
+ * The shared normalizeFillRow gate plus a non-empty string genesisHash (the
497
+ * pivot is bound to the grid generation; the market row deliberately is not).
355
498
  *
356
499
  * @param {unknown} row - Raw candidate row
357
500
  * @returns {Object|null} Normalized row or null
@@ -362,6 +505,23 @@ export declare function normalizeLastFillPivot(row: unknown): {
362
505
  fillsAt: number;
363
506
  genesisHash: string;
364
507
  } | null;
508
+ /**
509
+ * Normalize a persisted bot-scoped last-market-fill row.
510
+ *
511
+ * Same normalizeFillRow contract as normalizeLastFillPivot but deliberately
512
+ * WITHOUT the genesisHash binding: this row is market truth about the account
513
+ * (the last price it traded at), not grid geometry, so it must survive a grid
514
+ * regeneration/rejection. It is used only as a market reference by spread
515
+ * correction, never as the COW LAST-FILL-GUARD pivot.
516
+ *
517
+ * @param {unknown} row - Raw candidate row
518
+ * @returns {{price:number,type:string,fillsAt:number}|null} Normalized row or null
519
+ */
520
+ export declare function normalizeLastMarketFill(row: unknown): {
521
+ price: number;
522
+ type: string;
523
+ fillsAt: number;
524
+ } | null;
365
525
  /**
366
526
  * Write the LAST-FILL-GUARD pivot scalar family in one place (free
367
527
  * implementation shared by the manager method, cow_runtime's queued-fill
@@ -601,6 +761,13 @@ export declare function deepFreeze<T>(obj: T): T;
601
761
  * @returns {Map}
602
762
  */
603
763
  export declare function cloneMap<K, V>(map: Map<K, V>): Map<K, V>;
764
+ /**
765
+ * Fire-and-forget structural grid resync. Invokes the manager's handler and
766
+ * logs both a synchronous throw and an async rejection through the manager
767
+ * logger, so escalation sites share one error-handling footer. No-op when the
768
+ * manager has no handler.
769
+ */
770
+ export declare function fireStructuralResync(bot: BotLike, reason: string, details: Record<string, unknown>, errorLabel: string, level?: string): void;
604
771
  /**
605
772
  * Parses JSON content that may contain comments (/* or //).
606
773
  * Strips block comments then line comments before parsing.