dexbot 1.6.16 → 1.6.17

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 (60) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/analysis/tradingview/README.md +2 -2
  3. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  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/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  8. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  9. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +4 -4
  10. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  11. package/dist/modules/account_bots.d.ts +3 -0
  12. package/dist/modules/chain_keys.d.ts +1 -1
  13. package/dist/modules/constants.d.ts +6 -0
  14. package/dist/modules/constants.js +34 -6
  15. package/dist/modules/credit_pricing.d.ts +20 -1
  16. package/dist/modules/credit_pricing.js +23 -1
  17. package/dist/modules/credit_runtime.js +33 -16
  18. package/dist/modules/dexbot_class.d.ts +3 -1
  19. package/dist/modules/dexbot_class.js +5 -2
  20. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  21. package/dist/modules/dexbot_cow_runtime.js +47 -66
  22. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  23. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  24. package/dist/modules/launcher/credential_daemon.js +60 -26
  25. package/dist/modules/order/grid.d.ts +7 -0
  26. package/dist/modules/order/grid.js +157 -15
  27. package/dist/modules/order/index.d.ts +15 -0
  28. package/dist/modules/order/manager.d.ts +30 -7
  29. package/dist/modules/order/manager.js +108 -12
  30. package/dist/modules/order/strategy.d.ts +5 -0
  31. package/dist/modules/order/strategy.js +23 -2
  32. package/dist/modules/order/utils/math.d.ts +41 -1
  33. package/dist/modules/order/utils/math.js +47 -1
  34. package/dist/modules/order/utils/order.d.ts +13 -0
  35. package/dist/modules/order/utils/order.js +61 -7
  36. package/dist/modules/order/utils/system.d.ts +66 -0
  37. package/dist/modules/order/utils/system.js +135 -0
  38. package/dist/modules/order/utils/validate.d.ts +3 -1
  39. package/dist/modules/order/utils/validate.js +5 -1
  40. package/dist/modules/types.d.ts +35 -2
  41. package/dist/scripts/analyze-credit.js +64 -23
  42. package/dist/scripts/bts_distribution.d.ts +66 -0
  43. package/dist/scripts/bts_distribution.js +2102 -0
  44. package/dist/scripts/token_distribution.d.ts +45 -0
  45. package/dist/scripts/token_distribution.js +1870 -0
  46. package/dist/unlock.js +42 -24
  47. package/docs/COW_INVARIANTS.md +6 -0
  48. package/docs/DEXBOT_COMPARISON.md +5 -5
  49. package/docs/EVOLUTION.md +9 -8
  50. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -1
  51. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  52. package/docs/GRID_RECALCULATION.md +3 -3
  53. package/docs/LOGGING.md +9 -0
  54. package/docs/MPA_CREDIT_USAGE.md +3 -2
  55. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +117 -0
  56. package/docs/README.md +1 -1
  57. package/docs/architecture.md +98 -1
  58. package/market_adapter/README.md +2 -2
  59. package/package.json +3 -1
  60. package/scripts/README.md +85 -148
@@ -128,12 +128,36 @@ function classifySpreadStall(c) {
128
128
  // the precedence is explicit so a future hint can never mask 'unfunded').
129
129
  if (Number(c?.plannedCount || 0) > 0 || hint === 'unfunded')
130
130
  return 'unfunded';
131
- // Preserve the readiness-gate causes verbatim; they are operationally
132
- // distinct and the targeted-sync reason states them literally.
133
- if (hint === 'cold-book' || hint === 'unmatched-orders' || hint === 'readiness-gate')
131
+ // Preserve the named causes verbatim; they are operationally distinct (one
132
+ // wants a sync, one wants a re-center) and the watchdog keys its escalation
133
+ // window off them.
134
+ if (hint === 'cold-book' || hint === 'unmatched-orders' || hint === 'readiness-gate'
135
+ || hint === 'last-fill-blocked')
134
136
  return hint;
135
137
  return 'no-candidates';
136
138
  }
139
+ /**
140
+ * Merge two side stalls so the starvation fallback cannot mask a named cause.
141
+ * 'unfunded' stays top (a refresh may repair it); 'unmatched-orders' next (a
142
+ * sync repairs it); then the geometry bind; readiness causes; 'no-candidates'
143
+ * is the floor. Exported for tests.
144
+ */
145
+ export function mergeSpreadStalls(a, b) {
146
+ const rank = {
147
+ 'unfunded': 5,
148
+ 'no-free-funds': 5,
149
+ 'unmatched-orders': 4,
150
+ 'last-fill-blocked': 3,
151
+ 'cold-book': 2,
152
+ 'readiness-gate': 2,
153
+ 'no-candidates': 1,
154
+ 'batch-not-executed': 1,
155
+ 'apply-error': 1
156
+ };
157
+ const ra = rank[String(a)] ?? 0;
158
+ const rb = rank[String(b)] ?? 0;
159
+ return (rb > ra ? String(b) : String(a));
160
+ }
137
161
  /**
138
162
  * Spread-correction refusal causes — the single vocabulary shared by
139
163
  * classifySpreadRefusalCause, the retry/transience decision and the
@@ -343,7 +367,7 @@ function _snapshotFundState(manager) {
343
367
  }
344
368
  import { floatToBlockchainInt, getPrecisionByOrderType, getPrecisionsForManager, calculateOrderCreationFees, calculateOrderSizes, calculateRotationOrderSizes, calculateAvailableFundsValue, calculateGridSideDivergenceMetric, getPrecisionSlack, getMinOrderSize, getSingleDustThreshold, getGridBestPrices, calculateSpreadFromOrders, allocateFundsByWeights, calculateGapSlots as _mathGapSlots, pricesOnSameLevel, sameGridLevel, getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, validatePersistedBoundary, isTransientInBandRejection, adjustBudgetForBtsFees, clamp, derivePriceLevels, buildGenesisFromPriceLevels, assertSlotPriceInvariant, priceForSlot, hashPriceLevels, } from './utils/math.js';
345
369
  import { filterOrdersByType, checkSizesBeforeMinimum, checkSizeThreshold, resolveConfiguredPriceBound, shouldFlagOutOfSpread, isOrderHealthy, isPhantomOrder, isSlotAvailable, isOrderOnChain, isOrderPlaced, hasOnChainId, isEmptyGridSlot, parseSlotIndex, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, resolveEdgeCount, edgeOrderIdSet, resolveLiveEdgeAnchorPrice, liveWindowIdSet, getOrderTypeFromUpdatedFlags } from './utils/order.js';
346
- import { loadAmaCenterPrice, loadAmaCenterSnapshot, withBlockchainRetry, restoreLastFillPivot, resetLastFillPivot, evaluateSpreadCorrectionReadiness, maybeRefreshLiveMarketPrice } from './utils/system.js';
370
+ import { loadAmaCenterPrice, loadAmaCenterSnapshot, withBlockchainRetry, restoreLastFillPivot, resetLastFillPivot, evaluateSpreadCorrectionReadiness, maybeRefreshLiveMarketPrice, resolveLastFillGuardReference, isLastFillGuardBlocked } from './utils/system.js';
347
371
  import * as MathUtils from './utils/math.js';
348
372
  import { derivePriceWithPoolRef, resolveStartPriceMode } from './utils/withPoolRef.js';
349
373
  import { getWhitelistFlags } from '../market_adapter_whitelist.js';
@@ -2562,9 +2586,10 @@ export async function checkSpreadCondition(manager, _BitShares, updateOrdersOnCh
2562
2586
  correction = oppositeCorrection;
2563
2587
  placeCount = oppositeCorrection.ordersToPlace?.length || 0;
2564
2588
  const oppositeStall = classifySpreadStall(oppositeCorrection);
2565
- sideStall = (sideStall === 'unfunded' || oppositeStall === 'unfunded')
2566
- ? 'unfunded'
2567
- : 'no-candidates';
2589
+ // Precedence merge (never overwrite): 'unfunded' > sync-repairable
2590
+ // > geometry bind > readiness > 'no-candidates'. The old collapse
2591
+ // to 'unfunded'/'no-candidates' dropped every named cause.
2592
+ sideStall = mergeSpreadStalls(sideStall, oppositeStall);
2568
2593
  }
2569
2594
  }
2570
2595
  // Capture fund snapshot under lock for pre-flight verification before broadcast
@@ -3106,6 +3131,41 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3106
3131
  : 'no-candidates';
3107
3132
  const railType = preferredSide;
3108
3133
  const sideName = railType === ORDER_TYPES.BUY ? 'buy' : 'sell';
3134
+ // LAST-FILL FILTER (planner-side, same predicate as the broadcast guard).
3135
+ //
3136
+ // The guard drops any create at/through the last fill price, so a plan
3137
+ // built from such candidates can only end as "batch prepared but not
3138
+ // executed" (observed live: the only funded candidate was a SELL below
3139
+ // the 0.447640 fill, both attempts were dropped, and the correction
3140
+ // burned its cycle on a refusal). Filter here instead: the quota is then
3141
+ // filled from candidates the guard can accept, and an empty pool is an
3142
+ // honest "nothing to place" rather than a vetoed batch.
3143
+ //
3144
+ // Uses resolveLastFillGuardReference (the SAME effective pivot the guard
3145
+ // probes, including the persisted fallback that survives a rebuild) so
3146
+ // planner and guard cannot drift apart.
3147
+ const lastFillRef = resolveLastFillGuardReference(manager);
3148
+ const lastFillPivot = lastFillRef.price != null && Number.isFinite(Number(lastFillRef.price))
3149
+ ? Number(lastFillRef.price)
3150
+ : null;
3151
+ const lastFillSide = lastFillRef.type;
3152
+ const lastFillBlocks = (c) => {
3153
+ if (lastFillPivot == null || lastFillSide == null)
3154
+ return false;
3155
+ if (c?.price == null || !Number.isFinite(Number(c.price)))
3156
+ return false;
3157
+ return isLastFillGuardBlocked(Number(c.price), Number(c.size) || 0, railType, lastFillPivot, lastFillSide, manager.config?.incrementPercent).blocked === true;
3158
+ };
3159
+ let lastFillExcluded = 0;
3160
+ const passesLastFill = (c) => {
3161
+ if (!lastFillBlocks(c))
3162
+ return true;
3163
+ lastFillExcluded++;
3164
+ return false;
3165
+ };
3166
+ const lastFillRuleText = lastFillPivot == null
3167
+ ? ''
3168
+ : `${railType === ORDER_TYPES.BUY ? 'BUY must be below' : 'SELL must be above'} the last fill ${Format.formatPrice6(lastFillPivot)}`;
3109
3169
  const configuredMissingSlots = Number(outOfSpread || 0);
3110
3170
  const missingSlots = configuredMissingSlots > 0
3111
3171
  ? Math.floor(configuredMissingSlots)
@@ -3292,6 +3352,7 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3292
3352
  .filter((o) => o.type === ORDER_TYPES.SPREAD
3293
3353
  && isSlotAvailable(o)
3294
3354
  && getSlotCorrectType(o) === railType)
3355
+ .filter(passesLastFill)
3295
3356
  .filter(tightensSpread)
3296
3357
  .filter(doesNotCrossMarket)
3297
3358
  .filter(doesNotCollideUnmatched)
@@ -3336,6 +3397,7 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3336
3397
  && o.state === ORDER_STATES.VIRTUAL
3337
3398
  && !o.orderId
3338
3399
  && getSlotCorrectType(o) === railType)
3400
+ .filter(passesLastFill)
3339
3401
  .filter(tightensSpread)
3340
3402
  .filter(doesNotCrossMarket)
3341
3403
  .filter(doesNotCollideUnmatched)
@@ -3432,10 +3494,14 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3432
3494
  // consume the whole quota without ever entering the gap.
3433
3495
  const remainingQuota = Math.max(0, missingSlots - orphanedVirtualCandidates.length);
3434
3496
  let spreadCandidates = [
3435
- ...promotedCandidates,
3497
+ ...promotedCandidates.filter(passesLastFill),
3436
3498
  ...typedSpreadCandidates.slice(0, remainingQuota),
3437
3499
  ...orphanedVirtualCandidates
3438
3500
  ];
3501
+ if (lastFillExcluded > 0) {
3502
+ manager.logger?.log?.(`[SPREAD-CORRECTION] Excluded ${lastFillExcluded} candidate(s) from ${sideName} planning: ` +
3503
+ `${lastFillRuleText} (the broadcast guard would drop them)`, 'debug');
3504
+ }
3439
3505
  // Dedupe by slot id: an empty in-rail slot typed SPREAD (normalized) now
3440
3506
  // qualifies for BOTH orphanedVirtualCandidates and typedSpreadCandidates
3441
3507
  // (both accept SPREAD type + rail geometry), so a single slot can be
@@ -3483,10 +3549,57 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3483
3549
  manager.logger?.log?.(`[SPREAD-CORRECTION] Identified ${spreadCandidates.length}/${missingSlots} slot(s) for activation on ${sideName} (orphaned=${orphanedVirtualCandidates.length}, spread=${spreadCandidates.length - orphanedVirtualCandidates.length})`, 'debug');
3484
3550
  }
3485
3551
  if (spreadCandidates.length === 0) {
3486
- manager.logger?.log?.(bestLiveOnRail == null
3487
- ? `[SPREAD-CORRECTION] No orphaned virtual slots or spread slots found. Skipping.`
3488
- : `[SPREAD-CORRECTION] No spread-tightening slot on ${sideName} (best live ${bestLiveOnRail}); every remaining empty slot sits beyond the live window and cannot narrow the spread. Skipping.`, 'warn');
3489
- return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: refusalStallHint, origin: COW_ORIGINS.SPREAD_CORRECTION };
3552
+ manager.logger?.log?.(lastFillExcluded > 0 && lastFillPivot != null
3553
+ ? `[SPREAD-CORRECTION] No placeable ${sideName} slot: every tightening slot is at/through the last fill ` +
3554
+ `${Format.formatPrice6(lastFillPivot)} (${lastFillRuleText}). The spread cannot be tightened on this ` +
3555
+ `side; a boundary move or a fill must restore headroom.`
3556
+ : bestLiveOnRail == null
3557
+ ? `[SPREAD-CORRECTION] No orphaned virtual slots or spread slots found. Skipping.`
3558
+ : `[SPREAD-CORRECTION] No spread-tightening slot on ${sideName} (best live ${bestLiveOnRail}); every remaining empty slot sits beyond the live window and cannot narrow the spread. Skipping.`, 'warn');
3559
+ // Name the geometry bind: the window itself is wrong (a sell slot
3560
+ // below the last sale means the boundary/crawl is behind the fill),
3561
+ // so placement cannot repair the side and a re-center can.
3562
+ const emptyStall = (lastFillExcluded > 0 && lastFillPivot != null)
3563
+ ? 'last-fill-blocked'
3564
+ : refusalStallHint;
3565
+ return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: emptyStall, origin: COW_ORIGINS.SPREAD_CORRECTION };
3566
+ }
3567
+ // RAIL-OVERSUBSCRIBED: availableFund is chainFree − virtualReservation, so
3568
+ // it reads 0 whenever the empty rail already reserves more than the free
3569
+ // balance (observed live: free 454560.80 vs virtual 456046.21, a 1485 base
3570
+ // short, "planned 3, placing 0" every cycle for 84 minutes). That is not
3571
+ // "wait for a fill": the rail must be re-sized from chain truth, which a
3572
+ // re-center does. Detect it BEFORE the sizing-context gate (a zero budget
3573
+ // is the very symptom) and flag it so the persistence watchdog escalates
3574
+ // on its short fund window instead of the 30-minute structural one.
3575
+ {
3576
+ const sideChainFree = Math.max(0, Number(sideName === 'buy'
3577
+ ? manager.accountTotals?.buyFree
3578
+ : manager.accountTotals?.sellFree) || 0);
3579
+ const sideVirtual = Math.max(0, Number(sideName === 'buy'
3580
+ ? manager.funds?.virtual?.buy
3581
+ : manager.funds?.virtual?.sell) || 0);
3582
+ const sideAvailable = Math.max(0, Math.min(Number(manager.funds?.available?.[sideName] || 0), sideChainFree));
3583
+ const epsilon = 1e-8;
3584
+ if (sideAvailable <= epsilon && (sideVirtual - sideChainFree) > epsilon) {
3585
+ try {
3586
+ manager._spreadRailOversubscribed = {
3587
+ side: sideName, virtual: sideVirtual, free: sideChainFree, at: Date.now()
3588
+ };
3589
+ }
3590
+ catch { /* best-effort */ }
3591
+ manager.logger?.log?.(`[SPREAD-CORRECTION] ${sideName} rail is OVERSUBSCRIBED: virtual reservation ` +
3592
+ `${Format.formatAmount8(sideVirtual)} exceeds chain free ${Format.formatAmount8(sideChainFree)} ` +
3593
+ `by ${Format.formatAmount8(sideVirtual - sideChainFree)} — the projection is stale, so the ` +
3594
+ `correction funds what the chain actually holds free; a rail re-size (structural re-center) ` +
3595
+ `is still the durable repair`, 'warn');
3596
+ }
3597
+ else if (sideAvailable > epsilon) {
3598
+ try {
3599
+ manager._spreadRailOversubscribed = null;
3600
+ }
3601
+ catch { /* best-effort */ }
3602
+ }
3490
3603
  }
3491
3604
  const orphanedIds = new Set(orphanedVirtualCandidates.map((o) => o.id));
3492
3605
  const sideSlots = allOrders
@@ -3544,15 +3657,44 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3544
3657
  if (prioritizedTargets.length === 0) {
3545
3658
  return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: 'no-candidates', origin: COW_ORIGINS.SPREAD_CORRECTION };
3546
3659
  }
3547
- let remainingBudget = availableFund;
3660
+ // Chain-truth budget (see deriveChainTruthFundBudget): `availableFund`
3661
+ // already had the virtual reservation subtracted, and that reservation
3662
+ // is the projection of THESE candidates — subtracting it from the
3663
+ // budget that funds them is circular. When the projection exceeds what
3664
+ // the chain holds free it reads 0 forever, so the holes can never be
3665
+ // filled and the projection can never shrink (live: `planned 3,
3666
+ // placing 0` for 84 minutes). Re-derive from chain truth, capped by
3667
+ // what the candidates need and by the real free balance.
3668
+ const candidateIdeals = prioritizedTargets.reduce((sum, t) => sum + Math.max(0, Number(t.ideal) || 0), 0);
3669
+ const chainFreeForSide = Math.max(0, Number(sideName === 'buy'
3670
+ ? manager.accountTotals?.buyFree
3671
+ : manager.accountTotals?.sellFree) || 0);
3672
+ const virtualIntentForSide = Math.max(0, Number(sideName === 'buy'
3673
+ ? manager.funds?.virtual?.buy
3674
+ : manager.funds?.virtual?.sell) || 0);
3675
+ const fundBudget = MathUtils.deriveChainTruthFundBudget({
3676
+ availableFund,
3677
+ virtualIntent: virtualIntentForSide,
3678
+ chainFree: chainFreeForSide,
3679
+ candidateIdeals,
3680
+ });
3681
+ if (fundBudget.eroded) {
3682
+ manager.logger?.log?.(`[SPREAD-CORRECTION] ${sideName} projection exceeds chain free by ` +
3683
+ `${Format.formatAmount8(fundBudget.oversubscribed)}; funding the candidates from chain truth ` +
3684
+ `(${Format.formatAmount8(fundBudget.budget)} for ${Format.formatAmount8(candidateIdeals)} of ideal ` +
3685
+ `size) instead of placing nothing`, 'warn');
3686
+ }
3687
+ let remainingBudget = fundBudget.budget;
3548
3688
  // FUNDING PROBE (diagnostic): one line per correction cycle showing the
3549
3689
  // quantities that decide whether candidates can be funded. availableFund
3550
3690
  // is min(funds.available[side], accountTotals[side]Free); when the
3551
3691
  // virtual rail has already reserved the free balance this reads ~0 even
3552
- // though the side still holds inventory — the state that makes the loop
3553
- // below place fewer orders than the plan's candidates.
3692
+ // though the side still holds inventory. `spendable` is what the loop
3693
+ // actually spends (chain truth when the projection is oversubscribed),
3694
+ // so the two never have to be inferred from each other.
3554
3695
  manager.logger?.log?.(`[SPREAD-CORRECTION] Funding probe side=${sideName}: ` +
3555
3696
  `availableFund=${Format.formatAmount8(availableFund)} ` +
3697
+ `spendable=${Format.formatAmount8(fundBudget.budget)} ` +
3556
3698
  `budget=${Format.formatAmount8(Number(ctx.budget || 0))} ` +
3557
3699
  `virtual=${Format.formatAmount8(Number(sideName === 'buy' ? manager.funds?.virtual?.buy : manager.funds?.virtual?.sell) || 0)} ` +
3558
3700
  `free=${Format.formatAmount8(Number(sideName === 'buy' ? manager.accountTotals?.buyFree : manager.accountTotals?.sellFree) || 0)} ` +
@@ -86,10 +86,24 @@ declare const utils: {
86
86
  } | null;
87
87
  }): system.SpreadCorrectionReadiness;
88
88
  resolveSpreadMarketReference(manager: import("../types.js").OrderManagerLike): number | null;
89
+ reanchorBoundaryFromLastFill(manager: import("../types.js").OrderManagerLike, boundaryIdx: number | null | undefined, slots: import("../types.js").ManagedOrder[] | null | undefined, gapSlots: number): {
90
+ boundaryIdx: number | null;
91
+ reanchored: boolean;
92
+ from?: number | null;
93
+ to?: number;
94
+ side?: string;
95
+ fillSlot?: number;
96
+ reason?: string;
97
+ };
89
98
  resolveLastFillGuardReference(manager: import("../types.js").OrderManagerLike): {
90
99
  price: number | null;
91
100
  type: string | null;
92
101
  };
102
+ isLastFillGuardBlocked(price: number, _size: number, type: unknown, lastPrice: number | null, lastType: string | null, _incrementPercent?: number): {
103
+ blocked: boolean;
104
+ pivot: number | null;
105
+ threshold?: number | null;
106
+ };
93
107
  restoreLastMarketFill(manager: import("../types.js").OrderManagerLike, persisted: unknown, options?: {
94
108
  now?: number;
95
109
  }): boolean;
@@ -278,6 +292,7 @@ declare const utils: {
278
292
  getPrecision: typeof math.getPrecision;
279
293
  computeChainFundTotals: typeof math.computeChainFundTotals;
280
294
  calculateAvailableFundsValue: typeof math.calculateAvailableFundsValue;
295
+ deriveChainTruthFundBudget: typeof math.deriveChainTruthFundBudget;
281
296
  adjustBudgetForBtsFees: typeof math.adjustBudgetForBtsFees;
282
297
  getGridBestPrices: typeof math.getGridBestPrices;
283
298
  calculateSpreadFromOrders: typeof math.calculateSpreadFromOrders;
@@ -672,7 +672,30 @@ declare class OrderManager implements OrderManagerLike {
672
672
  *
673
673
  * @param {string} reason - Log/debug label for the drop
674
674
  */
675
- _clearPendingFillCrawls(reason?: string): void;
675
+ /**
676
+ * Drop ALL owed fill-crawl records.
677
+ *
678
+ * This is the explicit allowed-loss path: the grid generation is being
679
+ * discarded (rebuild, rejected snapshot, restart replay), so the relative
680
+ * deltas no longer have a geometry to apply onto.
681
+ */
682
+ _clearPendingFillCrawls(reason?: string, detail?: string): void;
683
+ /**
684
+ * Consume the owed fill-crawl records a derivation actually folded.
685
+ *
686
+ * A boundary commit must never clear a record it could not apply: a
687
+ * truncated cross-chunk shift, an edge-classified slot of an older
688
+ * generation, or a record re-written for the same slot after the
689
+ * derivation ran. Clearing all of them was the last way a fill's crawl
690
+ * could be lost silently (2026-10-25: 7 fills swept slots 147-153, the
691
+ * commits dropped every record and the boundary ended 7 levels behind).
692
+ *
693
+ * `consumed` is the derivation's `consumedCrawlIds`; absent/not-an-array
694
+ * means the plan never derived a boundary (e.g. a create-only correction),
695
+ * so NOTHING is consumed. Records are matched by `slotId` + `ts`, so a
696
+ * newer record for the same slot survives a stale consumption.
697
+ */
698
+ _consumePendingFillCrawls(consumed: unknown, reason?: string, detail?: string): void;
676
699
  /**
677
700
  * Observability (fix #4, docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md §2): emit the live
678
701
  * boundary whenever roles are (re)assigned, so a silent boundary crawl that
@@ -730,12 +753,12 @@ declare class OrderManager implements OrderManagerLike {
730
753
  _resetLastFillPivot(reason?: string): boolean;
731
754
  /**
732
755
  * Record last filled price for the single-pivot guard: when armed, BOTH
733
- * sides are gated against the most recent fill price (BUY blocked above
734
- * pivot*(1-halfInc), SELL blocked below pivot*(1+halfInc); see
735
- * isLastFillGuardBlocked). Spread-correction bypasses. _lastFilledType is
736
- * purely the cold/armed discriminator (null => disabled). The per-side
737
- * fields are not read by the guard itself; they feed the book-seed
738
- * cold-check and per-side seeding in seedLastFilledPricesFromBook.
756
+ * sides are gated by the direction rule against the most recent fill price
757
+ * (BUY blocked at/above the pivot, SELL blocked at/below it; see
758
+ * isLastFillGuardBlocked). _lastFilledType is purely the cold/armed
759
+ * discriminator (null => disabled). The per-side fields are not read by the
760
+ * guard itself; they feed the book-seed cold-check and per-side seeding in
761
+ * seedLastFilledPricesFromBook.
739
762
  * @param {Array} fills
740
763
  */
741
764
  recordLastFilledPrices(fills: COWFillLike[]): void;
@@ -111,7 +111,7 @@ class COWRebalanceEngine {
111
111
  fills,
112
112
  currentBoundaryIdx: boundaryIdx
113
113
  };
114
- const { targetGrid, boundaryIdx: targetBoundary } = this.strategy.calculateTargetGrid(strategyParams);
114
+ const { targetGrid, boundaryIdx: targetBoundary, consumedCrawlIds } = this.strategy.calculateTargetGrid(strategyParams);
115
115
  // P4 / unanchored plan: the strategy returns a null boundary paired
116
116
  // with an EMPTY target grid only when no numeric center exists to
117
117
  // recover from (e.g. GRID-LOAD rejected the persisted boundary AND
@@ -297,7 +297,8 @@ class COWRebalanceEngine {
297
297
  workingGrid,
298
298
  workingBoundary: targetBoundary,
299
299
  planningDuration: duration,
300
- refillSlotIds
300
+ refillSlotIds,
301
+ consumedCrawlIds
301
302
  }),
302
303
  evacReady
303
304
  };
@@ -1712,13 +1713,100 @@ class OrderManager {
1712
1713
  *
1713
1714
  * @param {string} reason - Log/debug label for the drop
1714
1715
  */
1715
- _clearPendingFillCrawls(reason = 'unspecified') {
1716
+ /**
1717
+ * Drop ALL owed fill-crawl records.
1718
+ *
1719
+ * This is the explicit allowed-loss path: the grid generation is being
1720
+ * discarded (rebuild, rejected snapshot, restart replay), so the relative
1721
+ * deltas no longer have a geometry to apply onto.
1722
+ */
1723
+ _clearPendingFillCrawls(reason = 'unspecified', detail = '') {
1716
1724
  if (!Array.isArray(this._pendingFillCrawls) || this._pendingFillCrawls.length === 0)
1717
1725
  return;
1718
- const count = this._pendingFillCrawls.length;
1726
+ const dropped = this._pendingFillCrawls;
1727
+ const count = dropped.length;
1728
+ // Side split + age are the two facts needed to tell "the derivation
1729
+ // folded and applied this crawl" from "the commit cleared a crawl the
1730
+ // derivation never consumed" after the fact: a same-sign, same-age run
1731
+ // that did NOT move the boundary accordingly is the second case (the
1732
+ // 2026-10-25 sweep: 7 fills, boundary 148 -> 146, 7 crawls dropped).
1733
+ let buys = 0;
1734
+ let sells = 0;
1735
+ let oldestTs = 0;
1736
+ for (const e of dropped) {
1737
+ if (!e)
1738
+ continue;
1739
+ if (e.side === ORDER_TYPES.BUY)
1740
+ buys++;
1741
+ else if (e.side === ORDER_TYPES.SELL)
1742
+ sells++;
1743
+ const ts = Number(e.ts);
1744
+ if (Number.isFinite(ts) && ts > 0 && (oldestTs === 0 || ts < oldestTs))
1745
+ oldestTs = ts;
1746
+ }
1747
+ const oldestAgeS = oldestTs > 0 ? Math.max(0, Math.round((Date.now() - oldestTs) / 1000)) : null;
1719
1748
  this._pendingFillCrawls = [];
1720
1749
  this._markGridDirty();
1721
- this.logger?.log?.(`[BOUNDARY] Dropped ${count} owed fill crawl(s) (${reason})`, 'debug');
1750
+ this.logger?.log?.(`[BOUNDARY] Dropped ${count} owed fill crawl(s) (${reason}): ` +
1751
+ `buy=${buys} sell=${sells} net=${sells - buys}` +
1752
+ `${oldestAgeS == null ? '' : ` oldest=${oldestAgeS}s`}` +
1753
+ `${detail ? ` ${detail}` : ''}`, 'debug');
1754
+ }
1755
+ /**
1756
+ * Consume the owed fill-crawl records a derivation actually folded.
1757
+ *
1758
+ * A boundary commit must never clear a record it could not apply: a
1759
+ * truncated cross-chunk shift, an edge-classified slot of an older
1760
+ * generation, or a record re-written for the same slot after the
1761
+ * derivation ran. Clearing all of them was the last way a fill's crawl
1762
+ * could be lost silently (2026-10-25: 7 fills swept slots 147-153, the
1763
+ * commits dropped every record and the boundary ended 7 levels behind).
1764
+ *
1765
+ * `consumed` is the derivation's `consumedCrawlIds`; absent/not-an-array
1766
+ * means the plan never derived a boundary (e.g. a create-only correction),
1767
+ * so NOTHING is consumed. Records are matched by `slotId` + `ts`, so a
1768
+ * newer record for the same slot survives a stale consumption.
1769
+ */
1770
+ _consumePendingFillCrawls(consumed, reason = 'boundary commit', detail = '') {
1771
+ if (!Array.isArray(this._pendingFillCrawls) || this._pendingFillCrawls.length === 0)
1772
+ return;
1773
+ const before = this._pendingFillCrawls;
1774
+ if (!Array.isArray(consumed)) {
1775
+ this.logger?.log?.(`[BOUNDARY] Kept ${before.length} owed fill crawl(s) unconsumed (${reason})` +
1776
+ `${detail ? `: ${detail}` : ''} — a later derivation still owes them`, 'debug');
1777
+ return;
1778
+ }
1779
+ const key = (e) => {
1780
+ const ts = Number(e?.ts);
1781
+ return `${String(e?.slotId ?? '')}|${Number.isFinite(ts) ? ts : '*'}`;
1782
+ };
1783
+ const consumedKeys = new Set(consumed
1784
+ .filter((e) => !!e
1785
+ && typeof e.slotId === 'string'
1786
+ && (e.slotId).length > 0)
1787
+ .map(key));
1788
+ const dropped = before.filter((e) => consumedKeys.has(key(e)));
1789
+ if (dropped.length === 0) {
1790
+ this.logger?.log?.(`[BOUNDARY] Kept ${before.length} owed fill crawl(s) unconsumed (${reason})` +
1791
+ `${detail ? `: ${detail}` : ''} — a later derivation still owes them`, 'debug');
1792
+ return;
1793
+ }
1794
+ const kept = before.filter((e) => !consumedKeys.has(key(e)));
1795
+ const buys = dropped.filter((e) => e?.side === ORDER_TYPES.BUY).length;
1796
+ const sells = dropped.filter((e) => e?.side === ORDER_TYPES.SELL).length;
1797
+ let oldestTs = 0;
1798
+ for (const e of dropped) {
1799
+ const ts = Number(e?.ts);
1800
+ if (Number.isFinite(ts) && ts > 0 && (oldestTs === 0 || ts < oldestTs))
1801
+ oldestTs = ts;
1802
+ }
1803
+ const oldestAgeS = oldestTs > 0 ? Math.max(0, Math.round((Date.now() - oldestTs) / 1000)) : null;
1804
+ this._pendingFillCrawls = kept;
1805
+ this._markGridDirty();
1806
+ this.logger?.log?.(`[BOUNDARY] Dropped ${dropped.length} owed fill crawl(s) (${reason}): ` +
1807
+ `buy=${buys} sell=${sells} net=${sells - buys}` +
1808
+ `${oldestAgeS == null ? '' : ` oldest=${oldestAgeS}s`} kept=${kept.length}` +
1809
+ `${detail ? ` ${detail}` : ''}`, 'debug');
1722
1810
  }
1723
1811
  /**
1724
1812
  * Observability (fix #4, docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md §2): emit the live
@@ -1803,12 +1891,12 @@ class OrderManager {
1803
1891
  }
1804
1892
  /**
1805
1893
  * Record last filled price for the single-pivot guard: when armed, BOTH
1806
- * sides are gated against the most recent fill price (BUY blocked above
1807
- * pivot*(1-halfInc), SELL blocked below pivot*(1+halfInc); see
1808
- * isLastFillGuardBlocked). Spread-correction bypasses. _lastFilledType is
1809
- * purely the cold/armed discriminator (null => disabled). The per-side
1810
- * fields are not read by the guard itself; they feed the book-seed
1811
- * cold-check and per-side seeding in seedLastFilledPricesFromBook.
1894
+ * sides are gated by the direction rule against the most recent fill price
1895
+ * (BUY blocked at/above the pivot, SELL blocked at/below it; see
1896
+ * isLastFillGuardBlocked). _lastFilledType is purely the cold/armed
1897
+ * discriminator (null => disabled). The per-side fields are not read by the
1898
+ * guard itself; they feed the book-seed cold-check and per-side seeding in
1899
+ * seedLastFilledPricesFromBook.
1812
1900
  * @param {Array} fills
1813
1901
  */
1814
1902
  recordLastFilledPrices(fills) {
@@ -2432,7 +2520,15 @@ class OrderManager {
2432
2520
  // left for the next derivation, holes refilled same-side).
2433
2521
  if (boundaryCheck.ok && commitBoundary !== null && commitBoundary !== undefined
2434
2522
  && boundaryHeld !== true) {
2435
- this._clearPendingFillCrawls('boundary commit');
2523
+ // Carry the boundary delta into the drop log: a crawl whose
2524
+ // net direction the commit did NOT honor is the ledger-leak
2525
+ // signature (see _clearPendingFillCrawls). Observability
2526
+ // only — the clear itself is unchanged pending that evidence.
2527
+ const prevBoundary = this.boundaryIdx;
2528
+ // Scope the drop to what the plan's derivation folded: a
2529
+ // record it could not apply (truncated shift, edge slot,
2530
+ // re-recorded slot) stays owed for the next derivation.
2531
+ this._consumePendingFillCrawls(options?.consumedCrawlIds, 'boundary commit', `boundary ${prevBoundary ?? 'null'} -> ${commitBoundary}`);
2436
2532
  }
2437
2533
  this._gridVersion++;
2438
2534
  committed = true;
@@ -156,6 +156,11 @@ declare class StrategyEngine {
156
156
  }): {
157
157
  targetGrid: Map<any, any>;
158
158
  boundaryIdx: number | null;
159
+ consumedCrawlIds?: undefined;
160
+ } | {
161
+ targetGrid: Map<string, ManagedOrder>;
162
+ boundaryIdx: number;
163
+ consumedCrawlIds: import("./utils/order.js").CrawlEntry[];
159
164
  };
160
165
  }
161
166
  export default StrategyEngine;
@@ -50,6 +50,7 @@ import { ORDER_TYPES, ORDER_STATES } from '../constants.js';
50
50
  import { calculateGapSlots } from './grid.js';
51
51
  import { isSlotInRail } from './utils/math.js';
52
52
  import { deriveTargetBoundary, getSideBudget, calculateBudgetedSizes, getCoreOrdersTotal, resolveEdgeCount, resolveLiveEdgeAnchorPrice, selectEdgeSlots, isShiftEligibleFill } from './utils/order.js';
53
+ import { reanchorBoundaryFromLastFill } from './utils/system.js';
53
54
  import { assignGridRoles } from './utils/order.js';
54
55
  import { convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, parseSlotIndex, hasOnChainId, isOrderPlaced } from "./utils/order.js";
55
56
  class StrategyEngine {
@@ -259,10 +260,25 @@ class StrategyEngine {
259
260
  buy: resolveLiveEdgeAnchorPrice(this.manager, 'buy'),
260
261
  sell: resolveLiveEdgeAnchorPrice(this.manager, 'sell'),
261
262
  };
262
- const { boundaryIdx: newBoundaryIdx, remainingBudget } = deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, boundaryConfig, gapSlots, crossChunkBudget, this.manager._pendingFillCrawls, edgeAnchors);
263
+ let { boundaryIdx: newBoundaryIdx, remainingBudget, consumedCrawlIds } = deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, boundaryConfig, gapSlots, crossChunkBudget, this.manager._pendingFillCrawls, edgeAnchors);
263
264
  if (crossChunkBudget != null) {
264
265
  this.manager._boundaryShiftBudget = remainingBudget;
265
266
  }
267
+ // GEOMETRY RE-ANCHOR: the crawl is +-1 slot per committed fill, so a
268
+ // window that ended up BEHIND the newest real fill can never catch up —
269
+ // every tightening slot on that side is then at/through the fill and the
270
+ // last-fill guard refuses all of them while the funds sit in the resting
271
+ // inventory. The fill is the anchor: place it outside its own window.
272
+ // Validated like a boundary commit (strands no live in-band order), and
273
+ // only for an on-ladder fill price.
274
+ const reanchor = reanchorBoundaryFromLastFill(this.manager, newBoundaryIdx, allSlots, gapSlots);
275
+ if (reanchor.reanchored) {
276
+ newBoundaryIdx = reanchor.boundaryIdx;
277
+ try {
278
+ this.manager._markGridDirty?.();
279
+ }
280
+ catch { /* best-effort */ }
281
+ }
266
282
  // Unanchorable (null boundary, no numeric center anywhere): refuse to
267
283
  // plan rotations on fabricated geometry. The COW engine routes this
268
284
  // to a structural resync instead.
@@ -417,7 +433,12 @@ class StrategyEngine {
417
433
  });
418
434
  return {
419
435
  targetGrid: targetGrid,
420
- boundaryIdx: newBoundaryIdx
436
+ boundaryIdx: newBoundaryIdx,
437
+ // Records whose shift this derivation actually folded. The commit
438
+ // clears ONLY these, so a record it could not apply (truncated
439
+ // shift, edge classification, a newer record for the same slot)
440
+ // stays owed instead of vanishing with the commit.
441
+ consumedCrawlIds
421
442
  };
422
443
  }
423
444
  }
@@ -442,6 +442,46 @@ declare function getAssetFeesSafe(assetSymbol: string, assetAmount?: number | nu
442
442
  feeAmount?: undefined;
443
443
  feePercent?: undefined;
444
444
  } | null;
445
+ /**
446
+ * Fund budget for placing a KNOWN set of pending slots (spread correction).
447
+ *
448
+ * `calculateAvailableFundsValue` computes `chainFree - virtual - fees`, where
449
+ * `virtual` is the projection of the side's not-yet-placed (VIRTUAL) slots.
450
+ * That is the right number for "how much room is left beyond the projected
451
+ * rail", but it is CIRCULAR when the caller is funding exactly those projected
452
+ * slots: if the projection is larger than the account holds free (a rail sized
453
+ * from a bigger balance, from inventory locked in resting orders, or from
454
+ * optimistic proceeds), `available` reads 0 while the chain clearly holds free
455
+ * funds, and the projection can never shrink because nothing gets placed.
456
+ * Live symptom: `planned 3, placing 0` every cycle for 84 minutes
457
+ * (`free 454560.80` vs `virtual 456046.21`).
458
+ *
459
+ * So for a known candidate set, re-derive the budget from chain truth: add the
460
+ * projection back, but never more than the candidates themselves need and never
461
+ * more than the chain actually holds free. The chain remains the final arbiter
462
+ * (an over-commit is rejected at broadcast), and the fee reservation stays
463
+ * inside `availableFund` for every healthy cycle.
464
+ *
465
+ * Only an OVERSUBSCRIPTION (projection > chain free) triggers the fallback. A
466
+ * zero caused by the fee reservation or by a genuinely empty balance is a real
467
+ * constraint: the projection fits, so honour it (and its fees) and place
468
+ * nothing.
469
+ *
470
+ * @param {{availableFund?: number, virtualIntent?: number, chainFree?: number, candidateIdeals?: number}} args
471
+ * @returns {{budget: number, oversubscribed: number, eroded: boolean}} budget to
472
+ * place with; projection excess over chain free (0 = healthy); whether the
473
+ * chain-truth re-derivation was needed
474
+ */
475
+ declare function deriveChainTruthFundBudget(args: {
476
+ availableFund?: number;
477
+ virtualIntent?: number;
478
+ chainFree?: number;
479
+ candidateIdeals?: number;
480
+ } | null | undefined): {
481
+ budget: number;
482
+ oversubscribed: number;
483
+ eroded: boolean;
484
+ };
445
485
  /**
446
486
  * Calculate available funds for a specific side (buy or sell).
447
487
  * Deducts virtual reservations, BTS fees owed, and BTS fee reservation from chain-free balance.
@@ -1216,7 +1256,7 @@ declare function priceSlotEqual(a: number, b: number, precision: number): boolea
1216
1256
  declare function derivePriceLevels(startPrice: number, minPrice: number, maxPrice: number, incrementPercent: number): number[];
1217
1257
  declare function buildGenesisFromPriceLevels(startPrice: number, incrementPercent: number, gapSlots: number, priceLevels: number[]): GridGenesis;
1218
1258
  export type { FeeCacheEntry };
1219
- export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
1259
+ export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, deriveChainTruthFundBudget, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
1220
1260
  /**
1221
1261
  * Round a value to a given factor.
1222
1262
  * @param {number} value - Value to round