dexbot 1.6.13 → 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 (93) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +2 -2
  3. package/claw/docs/AI_BOT_LIBRARY_API.md +1 -1
  4. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  5. package/claw/modules/claw_catalog.ts +8 -4
  6. package/claw/modules/dexbot_profiles.ts +59 -15
  7. package/claw/modules/types.ts +2 -1
  8. package/claw/package.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  10. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  11. package/claw/skills/margin-trading/SKILL.md +1 -1
  12. package/claw/skills/margin-trading/references/position-management.md +1 -1
  13. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +25 -25
  14. package/dist/modules/account_bots.d.ts +7 -6
  15. package/dist/modules/account_bots.js +10 -10
  16. package/dist/modules/account_orders.d.ts +36 -4
  17. package/dist/modules/account_orders.js +76 -5
  18. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  19. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  20. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  21. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  22. package/dist/modules/bot_defaults.d.ts +16 -2
  23. package/dist/modules/bot_defaults.js +34 -8
  24. package/dist/modules/bot_settings.d.ts +4 -0
  25. package/dist/modules/bot_settings.js +55 -21
  26. package/dist/modules/config.js +6 -1
  27. package/dist/modules/constants.d.ts +7 -5
  28. package/dist/modules/constants.js +12 -5
  29. package/dist/modules/dexbot_class.d.ts +5 -0
  30. package/dist/modules/dexbot_class.js +8 -3
  31. package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
  32. package/dist/modules/dexbot_cow_runtime.js +331 -46
  33. package/dist/modules/dexbot_credential_client.d.ts +1 -16
  34. package/dist/modules/dexbot_credential_client.js +1 -1
  35. package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
  36. package/dist/modules/dexbot_fill_runtime.js +12 -1
  37. package/dist/modules/dexbot_maintenance_runtime.d.ts +18 -80
  38. package/dist/modules/dexbot_maintenance_runtime.js +57 -68
  39. package/dist/modules/dexbot_startup_runtime.js +12 -0
  40. package/dist/modules/dexbot_state_recovery.js +16 -0
  41. package/dist/modules/key_store.d.ts +0 -5
  42. package/dist/modules/key_store.js +1 -1
  43. package/dist/modules/order/accounting.js +11 -11
  44. package/dist/modules/order/export.js +2 -2
  45. package/dist/modules/order/format.d.ts +15 -1
  46. package/dist/modules/order/format.js +19 -1
  47. package/dist/modules/order/genesis_policy.d.ts +1 -1
  48. package/dist/modules/order/genesis_policy.js +1 -1
  49. package/dist/modules/order/grid.d.ts +23 -11
  50. package/dist/modules/order/grid.js +383 -51
  51. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  52. package/dist/modules/order/grid_reconcile.js +5 -5
  53. package/dist/modules/order/grid_reconcile_internal.js +48 -40
  54. package/dist/modules/order/index.d.ts +34 -8
  55. package/dist/modules/order/logger.js +2 -2
  56. package/dist/modules/order/manager.d.ts +9 -2
  57. package/dist/modules/order/manager.js +58 -24
  58. package/dist/modules/order/strategy.d.ts +2 -2
  59. package/dist/modules/order/strategy.js +51 -21
  60. package/dist/modules/order/sync_engine.js +4 -0
  61. package/dist/modules/order/utils/math.d.ts +3 -3
  62. package/dist/modules/order/utils/math.js +38 -27
  63. package/dist/modules/order/utils/order.d.ts +58 -58
  64. package/dist/modules/order/utils/order.js +119 -102
  65. package/dist/modules/order/utils/system.d.ts +193 -6
  66. package/dist/modules/order/utils/system.js +392 -29
  67. package/dist/modules/order/utils/validate.js +26 -4
  68. package/dist/modules/runtime_settings.d.ts +1 -1
  69. package/dist/modules/runtime_settings.js +3 -3
  70. package/dist/modules/types.d.ts +48 -4
  71. package/dist/scripts/analyze-orders.d.ts +1 -1
  72. package/dist/scripts/analyze-orders.js +4 -4
  73. package/dist/scripts/divergence-calc.js +6 -6
  74. package/dist/scripts/validate_bots.d.ts +1 -1
  75. package/dist/scripts/validate_bots.js +3 -3
  76. package/dist/unlock.js +7 -2
  77. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
  78. package/docs/COW_INVARIANTS.md +6 -6
  79. package/docs/DEXBOT_COMPARISON.md +5 -5
  80. package/docs/EVOLUTION.md +8 -7
  81. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  82. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  83. package/docs/GRID_RECALCULATION.md +4 -1
  84. package/docs/GRID_RECONCILE.md +4 -4
  85. package/docs/LIFECYCLE.md +11 -11
  86. package/docs/LOGGING.md +14 -0
  87. package/docs/MPA_CREDIT_USAGE.md +1 -1
  88. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +12 -4
  89. package/docs/README.md +3 -3
  90. package/docs/architecture.md +6 -6
  91. package/docs/developer_guide.md +7 -2
  92. package/package.json +1 -1
  93. package/tests/README.md +1 -1
@@ -23,10 +23,22 @@ export type OrderState = 'virtual' | 'active' | 'partial';
23
23
  * behind it). Only a chain sync can tell the two apart,
24
24
  * so it arms the refresh too; the out-of-spread staleness
25
25
  * watchdog remains the backstop if the sync heals nothing.
26
+ * cold-book — no live order on either side (readiness P-A): there is
27
+ * no realized spread to repair. The reconcile path owns
28
+ * the first window; a targeted sync is armed.
29
+ * unmatched-orders — readiness P-C: the only tightening candidates collided
30
+ * with known-unmatched chain orders, so planning skipped
31
+ * them and let the sync adopt them first.
32
+ * readiness-gate — the readiness gate itself failed (threw), so the cycle
33
+ * was refused correct-by-refusal. A fault to triage, not
34
+ * a structural candidate condition.
26
35
  * batch-not-executed— a plan was prepared but the COW batch did not run.
27
36
  * apply-error — the broadcast threw.
37
+ *
38
+ * ('stale-snapshot' is degraded-ok, not a stall: the planner still acts, it
39
+ * only withholds the LAST-FILL-GUARD bypass.)
28
40
  */
29
- export type SpreadCorrectionStall = 'no-free-funds' | 'unfunded' | 'no-candidates' | 'batch-not-executed' | 'apply-error';
41
+ export type SpreadCorrectionStall = 'no-free-funds' | 'unfunded' | 'no-candidates' | 'cold-book' | 'unmatched-orders' | 'readiness-gate' | 'batch-not-executed' | 'apply-error';
30
42
  /**
31
43
  * Dict with unknown values. The canonical replacement for
32
44
  * `Record<string, any>`; callers must narrow a value before using it.
@@ -484,6 +496,16 @@ export interface BotMetrics extends UnknownRecord {
484
496
  maxQueueDepth: number;
485
497
  gridLockContention: number;
486
498
  fundRecalcCount: number;
499
+ /** Genuine post-broadcast commit refusals (working grid rejected). Excludes a poll-confirmed success that merely reuses the recovery funnel for adoption. */
500
+ refusedCommitCount: number;
501
+ /** Orphan fills whose proceeds were credited outside slot accounting. */
502
+ orphanFillCreditedCount: number;
503
+ /** BUY emissions at/above the last filled BUY pivot (guard bypass / leak). */
504
+ restampBuyAboveAnchorCount: number;
505
+ /** Derived boundary moved more than the active window in one plan. */
506
+ boundaryDriftExceedsWindowCount: number;
507
+ /** Non-spread-correction CREATE/UPDATE destinations inside the gap band (shadow). */
508
+ gapBandPlacementShadowCount: number;
487
509
  }
488
510
  /** An unmatched chain order surfaced by a sync pass. */
489
511
  export interface UnmatchedChainOrder extends UnknownRecord {
@@ -562,8 +584,8 @@ export interface ManagedOrder {
562
584
  sideHint?: string;
563
585
  [key: string]: unknown;
564
586
  }
565
- /** Active-order target counts. */
566
- export interface ActiveOrdersConfig extends UnknownRecord {
587
+ /** Market-order target counts (core-order window). */
588
+ export interface CoreOrdersConfig extends UnknownRecord {
567
589
  buy?: number;
568
590
  sell?: number;
569
591
  }
@@ -598,7 +620,7 @@ export interface GridConfig extends UnknownRecord {
598
620
  [key: string]: unknown;
599
621
  };
600
622
  targetSpreadPercent?: number;
601
- activeOrders?: ActiveOrdersConfig;
623
+ coreOrders?: CoreOrdersConfig;
602
624
  assetA?: string;
603
625
  assetB?: string;
604
626
  botKey?: string;
@@ -649,6 +671,16 @@ interface TimingConfig extends UnknownRecord {
649
671
  BLOCKCHAIN_FETCH_INTERVAL_MIN?: number;
650
672
  BOTS_CONFIG_POLL_INTERVAL_MS?: number;
651
673
  BTS_ACQUIRE_COOLDOWN_MIN?: number;
674
+ /**
675
+ * Spread-correction trust window (ms). How old the last completed
676
+ * open-orders sync may be before the local snapshot is treated as stale
677
+ * (the planner still acts but loses the LAST-FILL-GUARD bypass), and how
678
+ * often the live market price is re-read for the crossing floor. Defaults to
679
+ * `TIMING.SPREAD_CORRECTION_SYNC_FRESH_MS` (10 min); a non-positive value
680
+ * disables the time bound entirely (snapshot is never stale and the live
681
+ * price is never force-refreshed, so the floor stays on the fill anchor).
682
+ */
683
+ SPREAD_CORRECTION_SYNC_FRESH_MS?: number;
652
684
  }
653
685
  /** `config.fillProcessing` knobs read by the fill consumer. */
654
686
  interface FillProcessingConfig extends UnknownRecord {
@@ -821,6 +853,7 @@ export interface AccountOrdersLike {
821
853
  loadGenesis(forceReload?: boolean): unknown;
822
854
  loadGapEvacStreaks(forceReload?: boolean): unknown;
823
855
  loadLastFillPivot?(forceReload?: boolean): unknown;
856
+ loadLastMarketFill?(forceReload?: boolean): unknown;
824
857
  loadPendingFillCrawls(forceReload?: boolean): unknown[];
825
858
  loadRecentFillKeys(forceReload?: boolean): unknown;
826
859
  loadPersistedAssets(forceReload?: boolean): {
@@ -832,6 +865,8 @@ export interface AccountOrdersLike {
832
865
  clearGrid(): Promise<unknown>;
833
866
  clearPersistedBoundary(...args: unknown[]): Promise<unknown>;
834
867
  clearPersistedLastFillPivot(...args: unknown[]): Promise<unknown>;
868
+ clearPersistedLastMarketFill?(...args: unknown[]): Promise<unknown>;
869
+ backupSnapshot?(reason?: string): Promise<string | null>;
835
870
  loadProcessedFills(options?: boolean | {
836
871
  forceReload?: boolean;
837
872
  minTimestamp?: number | null;
@@ -999,6 +1034,8 @@ export interface OrderManagerLike {
999
1034
  createdAt?: number;
1000
1035
  } | null;
1001
1036
  _missingGenesis?: unknown;
1037
+ _metrics?: BotMetrics;
1038
+ _lastBoundaryDriftWarnAt?: number;
1002
1039
  _genesisInvariantViolations?: number;
1003
1040
  _genesisInvariantLoggedAt?: number;
1004
1041
  _fundDriftLedger?: {
@@ -1014,6 +1051,13 @@ export interface OrderManagerLike {
1014
1051
  _lastFilledType: string | null;
1015
1052
  _lastFilledAt: number | null;
1016
1053
  lastFillPivotSource: 'fill' | 'book' | null;
1054
+ _lastMarketFillPrice?: number | null;
1055
+ _lastMarketFillType?: string | null;
1056
+ _lastMarketFillAt?: number | null;
1057
+ _liveMarketPrice?: number | null;
1058
+ _liveMarketPriceAt?: number | null;
1059
+ _liveMarketPriceAttemptedAt?: number | null;
1060
+ _lastSyncAt?: number;
1017
1061
  _lastUnmatchedChainOrders?: UnmatchedChainOrder[];
1018
1062
  _lastUnmatchedChainOrdersAt?: number;
1019
1063
  _lastAccountingFailure?: unknown;
@@ -63,7 +63,7 @@ interface BotConfig {
63
63
  targetSpreadPercent?: unknown;
64
64
  incrementPercent?: unknown;
65
65
  gridPrice?: unknown;
66
- activeOrders?: unknown;
66
+ coreOrders?: unknown;
67
67
  botFunds?: JsonObj;
68
68
  weightDistribution?: JsonObj;
69
69
  [key: string]: unknown;
@@ -539,7 +539,7 @@ function analyzeOrder(botData, config, botKey) {
539
539
  sell: sellSlots
540
540
  },
541
541
  // Target active orders from config
542
- activeOrdersTarget: config ? config.activeOrders : null,
542
+ coreOrdersTarget: config ? config.coreOrders : null,
543
543
  // Bot fund allocation settings from config (normalized to strings for
544
544
  // the display paths; bots.json allows percentage strings or numbers)
545
545
  botFunds: config && config.botFunds
@@ -1137,9 +1137,9 @@ function formatAnalysis(analysisInput) {
1137
1137
  lines.push(` Spread:${formatPercent(analysis.spread.real).padStart(6)} | Incr.:${formatPercent(analysis.increment.avg).padStart(6)}`);
1138
1138
  }
1139
1139
  // Active orders comparison
1140
- if (analysis.hasConfig && analysis.activeOrdersTarget) {
1141
- const buyTarget = analysis.activeOrdersTarget.buy;
1142
- const sellTarget = analysis.activeOrdersTarget.sell;
1140
+ if (analysis.hasConfig && analysis.coreOrdersTarget) {
1141
+ const buyTarget = analysis.coreOrdersTarget.buy;
1142
+ const sellTarget = analysis.coreOrdersTarget.sell;
1143
1143
  const buyActual = analysis.slots.activeBuy;
1144
1144
  const sellActual = analysis.slots.activeSell;
1145
1145
  // Collect raw buy/sell values across Active, Weight, Funds for column alignment
@@ -73,21 +73,21 @@ lines.forEach((line) => {
73
73
  // Filter out partial orders from divergence calculation
74
74
  // Include: 'active' and 'virtual' orders - these represent the intended grid structure
75
75
  // Exclude: 'partial' orders - these are temporarily filled and in transition
76
- const activeOrders = orders.filter((o) => o.state !== 'partial');
77
- const partialOrdersCount = orders.length - activeOrders.length;
76
+ const nonPartialOrders = orders.filter((o) => o.state !== 'partial');
77
+ const partialOrdersCount = orders.length - nonPartialOrders.length;
78
78
  // Calculate divergence metric: sum of ((calculated - persisted) / persisted)^2 / count
79
79
  let sumSquaredDiff = 0;
80
- activeOrders.forEach((order) => {
80
+ nonPartialOrders.forEach((order) => {
81
81
  const relativeError = (order.calculated - order.persisted) / order.persisted;
82
82
  sumSquaredDiff += relativeError * relativeError;
83
83
  });
84
- const normalizedMetric = activeOrders.length > 0 ? sumSquaredDiff / activeOrders.length : 0;
84
+ const normalizedMetric = nonPartialOrders.length > 0 ? sumSquaredDiff / nonPartialOrders.length : 0;
85
85
  const promille = normalizedMetric * 1000;
86
86
  // Calculate real error as √(promille / 1000)
87
87
  const realErrorPercent = Math.sqrt(promille / 1000) * 100;
88
88
  console.log('=== QUADRATIC DIVERGENCE ANALYSIS ===\n');
89
89
  console.log(`Total orders in input: ${orders.length}`);
90
- console.log(`Orders analyzed: ${activeOrders.length}`);
90
+ console.log(`Orders analyzed: ${nonPartialOrders.length}`);
91
91
  if (partialOrdersCount > 0) {
92
92
  console.log(`Partial orders excluded: ${partialOrdersCount}`);
93
93
  }
@@ -102,7 +102,7 @@ console.log(` Status: ${promille <= 1 ? '✓ WITHIN THRESHOLD' : '✗ EXCEEDS T
102
102
  // Show min/max errors
103
103
  let minError = Infinity, maxError = -Infinity;
104
104
  let minErrorOrder = null, maxErrorOrder = null;
105
- activeOrders.forEach((order, idx) => {
105
+ nonPartialOrders.forEach((order, idx) => {
106
106
  const absError = Math.abs((order.calculated - order.persisted) / order.persisted);
107
107
  if (absError < minError) {
108
108
  minError = absError;
@@ -6,7 +6,7 @@
6
6
  * for each bot entry. This is a health check to ensure configurations are
7
7
  * valid before being used by the system.
8
8
  *
9
- * Required fields for each bot: assetA, assetB, activeOrders, botFunds
9
+ * Required fields for each bot: assetA, assetB, coreOrders, botFunds
10
10
  * Optional field: gridPrice (number | null | "ama"/"ama1".."ama4")
11
11
  *
12
12
  * Usage: node dist/scripts/validate_bots.js
@@ -6,7 +6,7 @@
6
6
  * for each bot entry. This is a health check to ensure configurations are
7
7
  * valid before being used by the system.
8
8
  *
9
- * Required fields for each bot: assetA, assetB, activeOrders, botFunds
9
+ * Required fields for each bot: assetA, assetB, coreOrders, botFunds
10
10
  * Optional field: gridPrice (number | null | "ama"/"ama1".."ama4")
11
11
  *
12
12
  * Usage: node dist/scripts/validate_bots.js
@@ -27,7 +27,7 @@ const livePath = PATHS.PROFILES.BOTS_JSON;
27
27
  * Required fields:
28
28
  * - assetA: Base currency symbol (e.g., 'XRP')
29
29
  * - assetB: Quote currency symbol (e.g., 'BTS')
30
- * - activeOrders: Number of orders in the grid
30
+ * - coreOrders: Number of orders in the grid
31
31
  * - botFunds: Amount of funds allocated to the bot
32
32
  *
33
33
  * Output:
@@ -44,7 +44,7 @@ function checkConfig(obj, src) {
44
44
  const bots = Array.isArray(o.bots) && o.bots.length ? o.bots : [o];
45
45
  console.log(`\n== Checking ${src}: found ${bots.length} bot entries`);
46
46
  // List of required fields that every bot must have
47
- const required = ['assetA', 'assetB', 'activeOrders', 'botFunds'];
47
+ const required = ['assetA', 'assetB', 'coreOrders', 'botFunds'];
48
48
  let anyMissing = false;
49
49
  let anyGridPriceWarnings = false;
50
50
  // Validate each bot entry
package/dist/unlock.js CHANGED
@@ -56,8 +56,6 @@ import { buildRuntimeScriptArgs } from './modules/launcher/runtime_entry.js';
56
56
  import { sendControlCommand } from './modules/launcher/supervisor_control.js';
57
57
  import { registerCleanup, setupGracefulShutdown } from './modules/graceful_shutdown.js';
58
58
  import { normalizeBotEntry, resolveRawBotEntries, loadSettingsFile } from './modules/bot_settings.js';
59
- import { main as runBotEditor } from './modules/account_bots.js';
60
- import { setSuppressConnectionLog, disconnectClient } from './modules/bitshares_client.js';
61
59
  import { selectStartOnboardingCommand } from './modules/cli_start_onboarding.js';
62
60
  import * as chainKeys from './modules/chain_keys.js';
63
61
  import * as credentialPolicy from './modules/credential_policy.js';
@@ -421,6 +419,13 @@ async function runStartOnboardingIfNeeded({ allowInteractive = true, nonInteract
421
419
  await chainKeys.main();
422
420
  return true;
423
421
  }
422
+ // The interactive bot editor drags in the heavyweight native chain client
423
+ // (~80 ms of module graph). It is only needed on this onboarding path, so
424
+ // load it lazily instead of eagerly on every `unlock`/`start` invocation.
425
+ const [{ main: runBotEditor }, { setSuppressConnectionLog, disconnectClient }] = await Promise.all([
426
+ import('./modules/account_bots.js'),
427
+ import('./modules/bitshares_client.js'),
428
+ ]);
424
429
  setSuppressConnectionLog(true);
425
430
  try {
426
431
  await runBotEditor();
@@ -95,7 +95,6 @@ boundary position and slot BUY/SELL roles during blockchain execution.
95
95
  ├─> Create WorkingGrid (clone master)
96
96
  ├─> Calculate target grid (from strategy)
97
97
  ├─> Reconcile against working copy
98
- ├─> Validate working grid funds
99
98
  └─> Return { workingGrid, actions, ... }
100
99
 
101
100
  2. updateOrdersOnChainBatch(result)
@@ -265,7 +264,7 @@ During Rebalance**.
265
264
 
266
265
  ## Safety Guardrails
267
266
 
268
- 1. **Accountant Dry-Run:** `Accountant.validateTargetGrid(targetMap)` verifies that the entire proposed grid fits within `Liquid + CurrentOrderValue` *before* broadcasting.
267
+ 1. **Planning-time budget feasibility:** order sizes are derived from `funds.allocated` via `getSideBudget` / `_getSizingContext`, so a proposed grid cannot exceed the side budget by construction. (The historical `Accountant.validateTargetGrid` dry-run was removed — it had no production caller.)
269
268
  2. **Atomic Transaction Semantics:** Large boundary shifts (>5 slots) are inherently safe because the COW pattern only commits after successful blockchain confirmation. If market volatility causes rapid shifts during planning, the plan is caught by the **pre-broadcast staleness guard** (`evaluateCommit` against `_gridVersion`): it re-plans ONCE from the fresh master with the same fills (`replanStaleBatch`, bounded by `STALE_PLAN_REPLAN_LIMIT`), then proceeds + structural resync if still stale — never a silent discard that drops the fill set. If the master changes *during* broadcast, the commit-time guard refuses the commit and the placed orders are adopted from chain so on-chain state never runs ahead of the grid.
270
269
  3. **Resync on Error:** If any blockchain action fails (e.g., "Insufficient funds"), the bot discards the working grid and triggers `grid_reconcile.ts` for a fresh blockchain sync ([GRID_RECONCILE.md](GRID_RECONCILE.md)).
271
270
 
@@ -61,15 +61,15 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
61
61
  - Funds drive order sizing/budget allocation only; `syncBoundaryToFunds`/`calculateFundDrivenBoundary` are deleted (1.5.3).
62
62
 
63
63
  - `INV-COW-007` Boundary hold on guard-skipped refills
64
- - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus reserve-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
65
- - Reserve-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
64
+ - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
65
+ - Edge-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
66
66
  - The hold rides to the commit as `options.boundaryHeld`, which suppresses the pending-crawl clear.
67
67
  - `trackBoundaryHold` counts consecutive hold batches (`manager._consecutiveBoundaryHolds`, cleared on the first clean batch) with a last-hold snapshot (`manager._lastBoundaryHoldInfo`); runs of 3+ escalate visibly. It also records a hold signature (`manager._lastHeldPlanSignature`: committed boundary + guard pivot + `_lastFilledAt` + held wire) so a fill-less re-plan of an unchanged state defers instead of re-broadcasting the identical vetoed plan.
68
68
  - Fill-driven rebalances never sleep on `_broadcastingFlag` inside `_fillProcessingLock`: `performSafeRebalance({deferIfBroadcasting:true})` returns a `deferred` result and the region-end hook schedules one no-fill rebalance (`schedulePostRecoveryRebalance`). This prevents the 20s lock-acquisition-timeout cascade when a broadcast region outlives the 30s `_awaitBroadcastIdle` wait. The stale-flag watchdog (`_clearStaleBroadcastFlag`, 120s) fires the same region-end hook when it hard-clears a leaked flag, so deferred fills are woken even when the region never ends through `stopBroadcasting()`.
69
69
  - A hold run carrying fresh fills (>= `TIMING.BOUNDARY_HOLD_RESYNC_THRESHOLD`) requests a guard-aware structural re-center (`requestStructuralGridResync`, cooldown `TIMING.BOUNDARY_HOLD_RESYNC_COOLDOWN_MS`) instead of holding forever — the heal path when the grid is trailing the market.
70
70
 
71
71
  - `INV-COW-008` Owed fill crawls survive unapplied commits
72
- - `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, reserve slots, and window members — a window that reaches the grid edge is not a reserve, using the same window exclusion every placement picker and `countLiveReserveOrders` apply.
72
+ - `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, edge slots, and window members — a window that reaches the grid edge is not an edge order, using the same window exclusion every placement picker and `countLiveEdgeOrders` apply.
73
73
  - `_commitWorkingGrid` clears them only when the plan's boundary was actually applied — a held boundary (`boundaryHeld`), a gate-rejected boundary, and a null boundary all leave them owed.
74
74
  - `consumePendingFillCrawls` applies them onto a restored finite boundary; `applyPersistedPendingCrawls` is the shared startup/recovery wrapper used before sync/reconcile; `_clearPendingFillCrawls` drops them when the boundary is re-anchored (grid rebuild via `initializeGrid`, rejected snapshot via `rejectCorruptedGridSnapshot`, persisted snapshot wipe via `AccountOrders.clearGrid`).
75
75
 
@@ -87,11 +87,11 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
87
87
  - `INV-PROJ-002` Preserve on-chain PARTIAL size in projection
88
88
  - If identity is retained (`keepOrderId=true`) and current state is `PARTIAL`, projected size must preserve current on-chain remaining size.
89
89
  - It must not be overwritten by ideal geometric `targetSize`.
90
- - Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:1158`).
90
+ - Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:1187`).
91
91
  - Preserve-path size must be normalized to finite, non-negative value.
92
92
 
93
93
  - `INV-PROJ-003` ACTIVE on-chain projection preserves current size (same as PARTIAL)
94
- - If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:1158`).
94
+ - If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:1187`).
95
95
  - An explicit UPDATE action targeting the `orderId` is required to apply `targetSize`.
96
96
 
97
97
  - `INV-ID-001` Order identity retention rule
@@ -191,7 +191,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
191
191
  - `INV-GRID-001` One-to-one order mapping
192
192
  - One grid slot = at most one on-chain order. No two chain orders may map to the same grid slot.
193
193
  - Sync engine tracks `matchedGridOrderIds` through both sync passes and skips already-matched slots.
194
- - Surplus orders (matched count above the per-side `activeOrders` + `reserveOrders` targets) are flagged for cancellation.
194
+ - Surplus orders (matched count above the per-side `coreOrders` + `edgeOrders` targets) are flagged for cancellation.
195
195
 
196
196
  - `INV-GRID-002` One order per price level
197
197
  - The active grid must have at most one on-chain order per (type, price) pair.
@@ -1,7 +1,7 @@
1
1
  # DEXBot vs DEXBot2 — Detailed Comparison Report
2
2
 
3
3
  > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
4
- > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.13).
4
+ > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.14).
5
5
  > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@
36
36
 
37
37
  | Attribute | DEXBot (original) | DEXBot2 |
38
38
  |---|---|---|
39
- | **Release Track** | 1.0.0 | v1.6.13 |
39
+ | **Release Track** | 1.0.0 | v1.6.14 |
40
40
  | **Language** | Python 3.6+ | TypeScript 5.x |
41
41
  | **Status** | Released 1.0.0, unmaintained | Active development |
42
42
  | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -347,7 +347,7 @@ workers:
347
347
  "targetSpreadPercent": 4,
348
348
  "weightDistribution": { "sell": 1, "buy": 1 },
349
349
  "botFunds": { "sell": "100%", "buy": "100%" },
350
- "activeOrders": { "sell": 5, "buy": 5 },
350
+ "coreOrders": { "sell": 5, "buy": 5 },
351
351
  "poolRef": "1.19.133" // optional: pin a specific pool for price derivation
352
352
  }
353
353
  ```
@@ -776,10 +776,10 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.6.13 |
779
+ | **Release Track** | 1.0.0 | v1.6.14 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
781
  | **Last Commit** | May 23, 2020 | 2026-10-10 |
782
- | **Total Commits** | 2281 | 2,372 (current HEAD, v1.6.13 line) |
782
+ | **Total Commits** | 2281 | 2,390 (current HEAD, v1.6.14 line) |
783
783
  | **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
784
784
  | **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
785
785
  | **Test Files** | 16 Python test files | 324 `test_*.ts` files (307 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.13 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.14 release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,372 commits over ~9 active months
9
+ - **Growth Phase**: 2,390 commits over ~9 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
11
  - **Stability**: Progression from manual testing to a suite of 307 automated test files
12
- - **Releases**: 145 version entries in the changelog (v0.1.0 to v1.6.13)
12
+ - **Releases**: 146 version entries in the changelog (v0.1.0 to v1.6.14)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
149
149
 
150
150
  ## Version History
151
151
 
152
- Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-10), so the column sums to 2,265 — the 107 commits up to and including the `v0.1.0` tag are not attributed to an era (2,265 + 107 = 2,372). Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
152
+ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-12). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,283 (`v0.1.0..HEAD`) and 2,390 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
153
153
 
154
154
  | Era | Commits | Theme |
155
155
  |-----|--------:|-------|
@@ -171,11 +171,12 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
171
171
  | v1.6.10 → v1.6.11 | 6 | AMA-slope 3-bar persistence gate + 16h Huber lookback, EMA-smoothing removal, PnL HTML report + month-shard fill cache, five order-engine/lifecycle safety fixes |
172
172
  | v1.6.11 → v1.6.12 | 27 | Explicit-`any` elimination + ratchet, shared ECC core & Firefox-safe pure-JS scrypt, worker-drain and fresh-placement cancel-grace safety fixes, funded spread correction, partial credit renewal, update install-layout classifier, AMA persistence-override fixes, test-suite speedup, dynamic-weight knob retune |
173
173
  | v1.6.12 → v1.6.13 | 21 | Spread-stall cause reporting + chain sync on every stall, resync-cascade guards (uncertain broadcast / suspended persistence), month-shard candle cache, dedup & dead-code purge, npm 12 install & PM2 fixes |
174
+ | v1.6.13 → v1.6.14 | 17 | Last-fill guard + live market floor for spread correction, committed-size drift resize, COW pre-broadcast guards & P2 counters, fail-closed unknown geometry, order-key rename, worker-thread test runner |
174
175
 
175
176
  ---
176
177
 
177
178
  **Report Originally Generated**: February 19, 2026
178
- **Last Updated**: October 10, 2026
179
- **Total Commits**: 2,372
180
- **Date Range**: December 2, 2025 – October 10, 2026
179
+ **Last Updated**: October 12, 2026
180
+ **Total Commits**: 2,390
181
+ **Date Range**: December 2, 2025 – October 12, 2026
181
182
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -52,7 +52,7 @@ funds.allocated → _getSizingContext() (budget for spread correction)
52
52
  **Key points:**
53
53
  - `botFunds` percentage applies to **total** capital (free + locked in orders), not just free. A bot at `"50%"` gets half of everything, not half of what's currently idle.
54
54
  - `funds.allocated` is the ceiling for each side. Existing orders already consume part of it; the remaining free portion is available for new placements.
55
- - The downstream `applyBotFundsAllocation()` (`manager.ts:1277`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
55
+ - The downstream `applyBotFundsAllocation()` (`manager.ts:1296`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
56
56
 
57
57
  ---
58
58
 
@@ -112,7 +112,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
112
112
 
113
113
  #### Gap-Slot Batch Fill Processing
114
114
 
115
- **Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1438) once per chunk to run the full rebalance pipeline.
115
+ **Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1811) once per chunk to run the full rebalance pipeline.
116
116
 
117
117
  **Batch Sizing Algorithm**: Batch size is derived from the grid gap-slot count + 1 (`DEXBot._getGapSlotBatchSize`): a queue depth at or below gapSlots+1 is processed as one unified batch; deeper queues are chunked into repeated batches of gapSlots+1 (the last chunk may be smaller). The same gapSlots+1 size caps order operations per broadcast transaction (oversized op batches are split into sequential broadcasts).
118
118
 
@@ -123,7 +123,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
123
123
  **Per-Batch Execution**:
124
124
 
125
125
  1. **Peek & Pop**: Check `_incomingFillQueue`, pop up to N fills (batch size)
126
- 2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:305`)
126
+ 2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:303`)
127
127
  - Proceeds credited directly to `chainFree` (via `adjustTotalBalance`)
128
128
  - Same-order fill batching (sync_engine Phase 6 cumulative transition) aggregates multiple fill transitions on one order before a single rebalance
129
129
  - All proceeds immediately available to next rebalance cycle (not split across cycles)
@@ -137,7 +137,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
137
137
 
138
138
  **Result**: 29 fills now processed in ~8 broadcasts (~24s) instead of 29 broadcasts (~90s).
139
139
 
140
- **Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:193`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
140
+ **Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:191`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
141
141
 
142
142
  #### Grid Regeneration Trigger (Available Funds Ratio — bidirectional)
143
143
 
@@ -156,6 +156,8 @@ SHRINK: overAlloc = (gridTracked - allocatedCapital) / allocatedCapital * 100
156
156
 
157
157
  Deliberately no per-side chain-total-drop leg: a normal fill moves value across sides (pays one asset, receives the other — see `processFillAccounting`), so one side's total routinely drops ≥3% on ordinary fills, and the fill pipeline already re-sizes from the post-fill budget.
158
158
 
159
+ **Committed-Size Drift leg**: the available-funds ratio above is measured as `chainFree − virtual`. The fill/rotation sizing pipeline re-derives VIRTUAL slot sizes from the live budget, so an external deposit (or withdrawal) is folded into the virtual reservation on the first rotation after it lands — `chainFree` and `virtual` move together, the ratio stays pinned at the unallocated remainder, and the on-chain (ACTIVE/PARTIAL) orders can stay at their pre-deposit sizes with no trigger. The committed-drift leg (folded into `checkAndUpdateGridIfNeeded`, exposed drift-only as `checkCommittedSizeDrift`) closes that gap: it computes the geometric ideal for each side from the current budget and compares it against the sizes actually committed on-chain (replaying the resize path's free-balance growth cap). A side whose committed orders would change by ≥ `GRID_REGENERATION_PERCENTAGE` of its **committed size** is flagged on the same ratio leg, so the full side is resized rather than only the fill-generated replacement orders. The denominator is the committed total, not the whole allocation: the on-chain window is a small slice of the plan (the far rail holds most of it), so an allocation-relative fraction would understate a genuine full-side undersize.
160
+
159
161
  **How It Works (grow)**:
160
162
  1. Fill occurs → proceeds added to `chainFree`
161
163
  2. `calculateAvailableFundsValue()` computes true spending power (chainFree minus reservations)
@@ -525,7 +527,7 @@ BitShares charges fees for `limit_order_create` and `limit_order_cancel`.
525
527
 
526
528
  - **Reservation** (`BTS_RESERVATION_MULTIPLIER` in `constants.ts::FEE_PARAMETERS`):
527
529
  $$Reserve = N_{active} \times BTS\_RESERVATION\_MULTIPLIER$$
528
- *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `reserveOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
530
+ *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `edgeOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
529
531
 
530
532
  - **Settlement (`deductBtsFees`):**
531
533
  1. Check `Funds.btsFeesOwed`.
@@ -801,4 +803,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
801
803
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
802
804
 
803
805
  ---
804
- *Technical Reference for DEXBot2 v1.6.13 release*
806
+ *Technical Reference for DEXBot2 v1.6.14 release*
@@ -1,7 +1,7 @@
1
1
  # The Grid-Price Invariant
2
2
 
3
3
  Status: **implemented; the emission check is BLOCKING**
4
- Last code-reviewed against the v1.6.7 release baseline `d4e0ce0b` (2026-09-26).
4
+ Last code-reviewed against the v1.6.13 release baseline `1a1ae60c` (2026-10-11).
5
5
 
6
6
  ## The invariant
7
7
 
@@ -413,7 +413,7 @@ is divergence telemetry built on `calculateGridSideDivergenceMetric`.
413
413
  **A grid with no price ladder is not a degraded grid — it is an undefined one.**
414
414
  Every consumer of the invariant reads `priceForSlot(idx, genesis)`, and each one
415
415
  silently degrades without it: nearest-slot adoption, `computeOutOfToleranceDriftTag`,
416
- the materialize descriptor-price fallback, `resolveLiveReserveEdgeAnchorPrice`
416
+ the materialize descriptor-price fallback, `resolveLiveEdgeAnchorPrice`
417
417
  tiers 3/4, and the `isSlotInRail` fail-open. That degradation is the tolerance
418
418
  matcher, which is exactly the path on which an off-grid price becomes grid
419
419
  evidence. So the ladder is treated as a **required** part of a snapshot, not a
@@ -489,7 +489,7 @@ degrade *into*:
489
489
  | correction-queue staleness matched by tolerance | `priceSlotEqual` against the slot's own level, and a ladder-less entry is dropped |
490
490
  | `computeOutOfToleranceDriftTag` + `price-drift-orphan` auto-cancel (`PRICE_DRIFT_TOLERANCE_MULTIPLIER`) | removed — an off-grid order is HELD (`out-of-grid-deferred`) and resolved structurally, never cancelled off a fuzzy price diff |
491
491
  | `findMatchingGridOrderByOpenOrder` | removed (its last production caller was the pass-2 legacy block; the cancelOrder linkage matches by `orderId`) |
492
- | `resolveLiveReserveEdgeAnchorPrice` tiers 2/3 (live slot extreme, config bound) | ladder extreme only; a ladder-less manager returns `null` (the live resolver no longer computes a config bound — consumers that want one, e.g. `reserveEdgeIdSet`, resolve it themselves) |
492
+ | `resolveLiveEdgeAnchorPrice` tiers 2/3 (live slot extreme, config bound) | ladder extreme only; a ladder-less manager returns `null` (the live resolver no longer computes a config bound — consumers that want one, e.g. `edgeOrderIdSet`, resolve it themselves) |
493
493
  | materialize descriptor-price fallback for a `slot-N` id | kept only for an unparseable id; a `slot-N` id with no ladder logs `error` and requests a structural resync |
494
494
 
495
495
  **E2 is fail-closed.** `syncFromOpenOrders` calls `_assertGenesisInvariant`
@@ -457,16 +457,19 @@ GRID_LIMITS: {
457
457
  **Parameters:**
458
458
  - `GRID_REGENERATION_PERCENTAGE`: Bidirectional threshold for size recalculation (default: `3%`)
459
459
  - Grow: free funds accumulate to ≥3% of allocated capital (e.g. availableFunds ≥ 60 BTS on a 2000 BTS grid)
460
+ - Grow (committed drift): the on-chain (ACTIVE/PARTIAL) orders lag their geometric ideal by ≥3% of the committed size — catches an external deposit that the fill/rotation pipeline already folded into `virtual`, which blinds the `availableFunds = chainFree − virtual` ratio
460
461
  - Shrink: grid-tracked size (ACTIVE + PARTIAL + VIRTUAL) exceeds allocation by ≥3% (external fund removal resizes affected orders down; per-side chain totals are not used — fills move value across sides)
462
+ - Shrink (committed drift): the on-chain orders exceed their geometric ideal by ≥3% of the committed size (external withdrawal)
461
463
 
462
464
  ### How It Works
463
465
 
464
466
  1. **OrderManager** tracks available funds per side (BUY and SELL separately)
465
467
  2. Allocated capital = number of active orders × size per order
466
- 3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE`:
468
+ 3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE`, OR the committed-drift leg flags the side (on-chain orders ≥threshold off their geometric ideal):
467
469
  - Triggers `Grid.recalculateGrid()` on that side only
468
470
  - Recalculates order sizes to incorporate freed capital
469
471
  - Maintains asymmetric fills (BUY fills don't trigger SELL resize)
472
+ - The committed-drift leg is what keeps a deposit that was absorbed into the VIRTUAL reservation from silently leaving the on-chain side un-resized
470
473
  4. After the resize, available funds are re-allocated into active orders
471
474
  5. Mirror (shrink): when `(gridTracked - allocated) / allocated × 100 >= threshold` (external fund removal), the same path resizes affected orders down
472
475
 
@@ -26,7 +26,7 @@ Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 ex
26
26
 
27
27
  Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations are attempted — plans are logged but not executed.
28
28
 
29
- `targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`activeOrders` window plus `reserveOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
29
+ `targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`coreOrders` window plus `edgeOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
30
30
 
31
31
  ```
32
32
  Grid generated
@@ -93,7 +93,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
93
93
  - Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
94
94
  - Detect grid-edge lock and plan a largest-order cancel
95
95
  - Plan creates for remaining slots
96
- - Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, reserve edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
96
+ - Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
97
97
  - Fork-kept **shelf orders** (live non-slot-N ids below the rail, e.g. `deep-*`) are never cancel candidates or reserve members — see [Shelf Orders](#shelf-orders-fork-kept-manual-orders)
98
98
  - **Vacated-rail refill**: each PROCEEDING update whose vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side queues a refill CREATE in the same plan (`source startupVacatedRailRefill`) — skipped updates, ghost prices (lattice moved), in-band slots, and already-desired slots never refill; refill targets require VIRTUAL state with no `orderId`
99
99
 
@@ -213,7 +213,7 @@ Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL ord
213
213
 
214
214
  Live on-chain orders with non-slot-N ids below the rail (e.g. `deep-*` manuals kept across a fork) are **shelf orders**: they sit outside the grid contract and must survive every startup path untouched. Three gates enforce this (all no-ops on grids that only mint slot-N ids):
215
215
 
216
- - **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `reserveEdgeIdSet`, the Tier-2 live-anchor scan, `_pickEdgeReserveSlots`, and `pickEdgeReserves` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the reserve edge (which would mask a real reserve deficit) nor be activated as a reserve it would never be counted as. The live-reserve count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated reserves.
216
+ - **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `edgeOrderIdSet`, the Tier-2 live-anchor scan, `_pickEdgeSlots`, and `pickEdgeSlots` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the edge (which would mask a real edge deficit) nor be activated as an edge order it would never be counted as. The live-edge count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated edge orders.
217
217
  - **Startup excess cancels** (`grid_reconcile_internal.ts`): the matched-excess selection filters to slot-N ids in both planOnly and execute branches — the cheapest-first sort would otherwise wipe the shelf on the next boot.
218
218
  - **Geometric size recalc** (`grid.ts`): `_recalculateGridOrderSizesFromBlockchain` skips non-slot-N slots in the per-slot loop, so divergence-triggered resizing never overwrites manual shelf sizes on-chain (the shelf stays in the budget denominator, so allocation math is unchanged).
219
219
 
@@ -286,7 +286,7 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
286
286
  | `tests/test_race_condition_fixes_batch1.ts` | ABBA deadlock (RC-1B) |
287
287
  | `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
288
288
  | `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
289
- | `tests/test_reserve_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
289
+ | `tests/test_edge_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
290
290
  | `tests/repro_phantom_orders.ts` | Phantom order prevention |
291
291
 
292
292
  ---
package/docs/LIFECYCLE.md CHANGED
@@ -90,7 +90,7 @@ sequenceDiagram
90
90
  participant CO as chain_orders (broadcast)
91
91
  participant STORE as Storage
92
92
 
93
- CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:458)
93
+ CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:466)
94
94
  FR->>FR: drain queue -> _processFillsWithBatching
95
95
  FR->>OM: processFilledOrders() (manager.ts)
96
96
  OM->>AC: processFillAccounting() (single call, batch)
@@ -134,10 +134,10 @@ sequenceDiagram
134
134
  participant STORE as Storage
135
135
 
136
136
  MA->>CL: AMA center snapshot updated
137
- CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:1685)
138
- CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:1645)
139
- RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:2944)
140
- RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:2443)
137
+ CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:1720)
138
+ CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:1677)
139
+ RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:2953)
140
+ RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:2462)
141
141
  RT->>AC: recalculate funds from balances
142
142
  RT->>GD: promote AMA center -> grid center
143
143
  RT->>GD: recalculateGrid() (grid.ts)
@@ -157,13 +157,13 @@ The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` an
157
157
  the parameters.
158
158
 
159
159
  > Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
160
- > runtime (`modules/credit_runtime.ts:3468`, reached via
161
- > `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1802`). The grid maintenance
160
+ > runtime (`modules/credit_runtime.ts:3441`, reached via
161
+ > `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1837`). The grid maintenance
162
162
  > chain above is the one that matters for order/price upkeep.
163
163
 
164
- References: `modules/dexbot_class.ts:1685` (`_performPeriodicGridChecks`) →
165
- `modules/dexbot_maintenance_runtime.ts:1645` (`performPeriodicGridChecks`) →
166
- `:2944` (`runGridMaintenance`) → `:2443` (`executeMaintenanceLogic`),
164
+ References: `modules/dexbot_class.ts:1720` (`_performPeriodicGridChecks`) →
165
+ `modules/dexbot_maintenance_runtime.ts:1677` (`performPeriodicGridChecks`) →
166
+ `:2953` (`runGridMaintenance`) → `:2462` (`executeMaintenanceLogic`),
167
167
  `docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
168
168
 
169
169
  ---
@@ -192,7 +192,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
192
192
  | How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
193
193
  | Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
194
194
  | Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
195
- | Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1685` |
195
+ | Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1720` |
196
196
  | Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
197
197
  | Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
198
198
  | Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |