dexbot 1.6.14 → 1.6.16

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 (134) hide show
  1. package/CHANGELOG.md +60 -4
  2. package/README.md +4 -4
  3. package/analysis/README.md +6 -6
  4. package/analysis/tradingview/README.md +2 -1
  5. package/claw/README.md +7 -7
  6. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
  7. package/claw/modules/chain_queries.ts +3 -3
  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/dist/analysis/ama_fitting/fetch_lp_candles.js +8 -1
  12. package/dist/analysis/ama_fitting/optimizer_high_resolution.d.ts +50 -1
  13. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +33 -7
  14. package/dist/analysis/bot_fitting/backtest_bot_fitting.d.ts +8 -6
  15. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +8 -10
  16. package/dist/analysis/bot_key_utils.js +9 -7
  17. package/dist/analysis/chart_utils.d.ts +9 -2
  18. package/dist/analysis/chart_utils.js +51 -1
  19. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
  20. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +99 -11
  21. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +57 -4
  22. package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
  23. package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
  24. package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
  25. package/dist/dexbot.js +112 -141
  26. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  27. package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
  28. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
  29. package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
  30. package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
  31. package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
  32. package/dist/market_adapter/inputs/window_cache.js +53 -17
  33. package/dist/market_adapter/lp_chart_core.js +1 -0
  34. package/dist/market_adapter/utils/chain.js +4 -3
  35. package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
  36. package/dist/market_adapter/utils/pair_orientation.js +142 -0
  37. package/dist/modules/account_bots.d.ts +40 -3
  38. package/dist/modules/account_bots.js +80 -37
  39. package/dist/modules/account_orders.d.ts +4 -1
  40. package/dist/modules/account_orders.js +4 -1
  41. package/dist/modules/bitshares-native/resolvers.js +3 -3
  42. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  43. package/dist/modules/bitshares_client.d.ts +12 -10
  44. package/dist/modules/bitshares_client.js +12 -10
  45. package/dist/modules/bot_defaults.d.ts +13 -2
  46. package/dist/modules/bot_defaults.js +31 -2
  47. package/dist/modules/bot_settings.js +6 -3
  48. package/dist/modules/chain_keys.d.ts +5 -1
  49. package/dist/modules/chain_keys.js +5 -1
  50. package/dist/modules/chain_orders.d.ts +6 -2
  51. package/dist/modules/chain_orders.js +6 -2
  52. package/dist/modules/constants.d.ts +11 -0
  53. package/dist/modules/constants.js +31 -1
  54. package/dist/modules/credit_runtime.d.ts +35 -5
  55. package/dist/modules/credit_runtime.js +219 -38
  56. package/dist/modules/dexbot_class.d.ts +22 -2
  57. package/dist/modules/dexbot_class.js +61 -21
  58. package/dist/modules/dexbot_cow_runtime.js +19 -18
  59. package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
  60. package/dist/modules/dexbot_fill_runtime.js +4 -7
  61. package/dist/modules/dexbot_maintenance_runtime.d.ts +7 -2
  62. package/dist/modules/dexbot_maintenance_runtime.js +52 -7
  63. package/dist/modules/dexbot_startup_runtime.js +3 -2
  64. package/dist/modules/dexbot_state_recovery.js +1 -1
  65. package/dist/modules/graceful_shutdown.d.ts +6 -2
  66. package/dist/modules/graceful_shutdown.js +6 -2
  67. package/dist/modules/launcher/bot_supervisor.js +4 -0
  68. package/dist/modules/launcher/launch_modes.js +6 -3
  69. package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
  70. package/dist/modules/launcher/monolithic_runtime.js +60 -1
  71. package/dist/modules/launcher/runtime_mode.d.ts +79 -0
  72. package/dist/modules/launcher/runtime_mode.js +223 -0
  73. package/dist/modules/market_adapter_whitelist.d.ts +8 -0
  74. package/dist/modules/market_adapter_whitelist.js +8 -0
  75. package/dist/modules/order/accounting.d.ts +15 -1
  76. package/dist/modules/order/accounting.js +15 -1
  77. package/dist/modules/order/async_lock.d.ts +9 -3
  78. package/dist/modules/order/async_lock.js +9 -3
  79. package/dist/modules/order/export.d.ts +0 -5
  80. package/dist/modules/order/export.js +2 -7
  81. package/dist/modules/order/format.d.ts +6 -4
  82. package/dist/modules/order/format.js +6 -4
  83. package/dist/modules/order/grid.d.ts +147 -19
  84. package/dist/modules/order/grid.js +321 -68
  85. package/dist/modules/order/grid_reconcile.js +4 -3
  86. package/dist/modules/order/grid_reconcile_internal.js +13 -18
  87. package/dist/modules/order/index.d.ts +4 -2
  88. package/dist/modules/order/index.js +1 -1
  89. package/dist/modules/order/logger_state.d.ts +1 -1
  90. package/dist/modules/order/logger_state.js +1 -1
  91. package/dist/modules/order/manager.d.ts +1 -0
  92. package/dist/modules/order/manager.js +5 -14
  93. package/dist/modules/order/sync_engine.d.ts +26 -11
  94. package/dist/modules/order/sync_engine.js +44 -20
  95. package/dist/modules/order/utils/math.d.ts +157 -47
  96. package/dist/modules/order/utils/math.js +236 -78
  97. package/dist/modules/order/utils/order.d.ts +64 -20
  98. package/dist/modules/order/utils/order.js +80 -24
  99. package/dist/modules/order/utils/system.d.ts +41 -11
  100. package/dist/modules/order/utils/system.js +43 -13
  101. package/dist/modules/order/utils/validate.d.ts +6 -3
  102. package/dist/modules/order/utils/validate.js +53 -60
  103. package/dist/modules/types.d.ts +7 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +5 -5
  105. package/dist/modules/utils/asset_symbols.js +5 -5
  106. package/dist/modules/utils/errors.d.ts +2 -1
  107. package/dist/modules/utils/errors.js +2 -1
  108. package/dist/scripts/analyze-credit.js +44 -27
  109. package/dist/scripts/diagnose-pool-history.js +35 -30
  110. package/dist/scripts/pnl.js +1 -1
  111. package/dist/scripts/rich_list.d.ts +50 -0
  112. package/dist/scripts/rich_list.js +469 -0
  113. package/dist/scripts/run-tests.js +80 -4
  114. package/dist/unlock.d.ts +2 -1
  115. package/dist/unlock.js +53 -21
  116. package/docs/BITSHARES_ONBOARDING.md +7 -0
  117. package/docs/COW_INVARIANTS.md +7 -1
  118. package/docs/DEXBOT_COMPARISON.md +6 -6
  119. package/docs/EVOLUTION.md +11 -9
  120. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -3
  121. package/docs/GRID_RECALCULATION.md +18 -6
  122. package/docs/LIFECYCLE.md +8 -8
  123. package/docs/LOGGING.md +16 -1
  124. package/docs/MPA_CREDIT_USAGE.md +10 -5
  125. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +163 -13
  126. package/docs/README.md +1 -1
  127. package/docs/WORKFLOW.md +6 -5
  128. package/docs/architecture.md +56 -2
  129. package/docs/developer_guide.md +5 -1
  130. package/market_adapter/README.md +14 -7
  131. package/modules/README.md +1 -1
  132. package/package.json +4 -1
  133. package/scripts/README.md +59 -32
  134. package/tests/README.md +40 -2
@@ -4,14 +4,16 @@
4
4
  > misbehaving (Part I) and the preserved **incident & fix ledger** (Part II), formerly
5
5
  > `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`.
6
6
  >
7
- > **Sources:** `CHANGELOG.md` v1.0.0 → v1.6.3; `docs/GRID_PRICE_INVARIANT.md`;
7
+ > **Sources:** `CHANGELOG.md` v1.0.0 → v1.6.14; `docs/GRID_PRICE_INVARIANT.md`;
8
8
  > `docs/COW_INVARIANTS.md`. Generic terms only — no live markets, accounts, or order ids.
9
9
  >
10
- > **Scope / snapshot:** v1.0.0 → v1.6.3.
10
+ > **Scope / snapshot:** v1.0.0 → v1.6.14 (`f6c0df32`, 2026-10-12); the v1.6.4 → v1.6.14 arc
11
+ > is the §9 addendum below.
11
12
  >
12
13
  > **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
13
- > source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`). Part I uses
14
- > `R1`–`R5` so the two never collide. The closing appendix is unnumbered (`A`) so the cited `§` range stays fixed.
14
+ > source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`); §9 is a
15
+ > later addendum (v1.6.4 → v1.6.14) that extends, and does not renumber, that range. Part I
16
+ > uses `R1`–`R5` so the two never collide. The closing appendix is unnumbered (`A`).
15
17
  >
16
18
  > **How to read:** start with **Part I** for the explanation; drop into **Part II** when you need
17
19
  > the per-incident evidence, commit hashes, and verification targets.
@@ -41,6 +43,7 @@
41
43
  - 6. Consolidated invariants
42
44
  - 7. Consolidated verification — grid-correction check as regression gate
43
45
  - 8. Provenance & supersession record
46
+ - 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.14) — addendum
44
47
  - A. Grid-Price Invariant — former failure trace (appendix)
45
48
 
46
49
  ---
@@ -102,6 +105,11 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
102
105
  config, one authoritative set of counters.
103
106
  - **Global last-fill guard + final pre-broadcast gate:** one pivot rule, enforced at the
104
107
  last moment before broadcast, with fail-open semantics for unjudgeable ops.
108
+ - **Non-destructive recovery (v1.6.13+):** uncertain broadcasts and credential outages
109
+ *defer* instead of rebuilding the grid, so a reset stops being the reflex response to
110
+ ambiguity — see §9.1.
111
+ - **Fail-closed geometry (v1.6.14+):** an unknown boundary/gap is no longer coerced to a
112
+ valid-looking `0` — see §9.1.
105
113
 
106
114
  The winning strategy was **removing writers and sources of truth**, not adding handlers.
107
115
 
@@ -115,6 +123,8 @@ The winning strategy was **removing writers and sources of truth**, not adding h
115
123
  beats fail-closed alone.
116
124
  5. Make deferred work **level-triggered** — never let a retry depend on a future event.
117
125
  6. If a fix class keeps returning, the model is wrong, not the fix.
126
+ 7. Treat **ambiguity as deferral, not destruction** — a reset that clears guard state is
127
+ another writer, and `Number(null) === 0` is how "unknown" becomes a confident `0`.
118
128
 
119
129
  ---
120
130
 
@@ -147,7 +157,7 @@ plans, `LANDED`/`REVERTED`/`SUPERSEDED` statuses, commit hashes, and verificatio
147
157
 
148
158
  ### 1. Gap-Band Orphan — Prevention Plan (P1–P6)
149
159
 
150
- > **Source:** `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
160
+ > **Source:** former `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
151
161
 
152
162
  **Landing map (corrected 2026-08-31):**
153
163
  - **P1** — landed `f94d6ec4` (same-batch CANCEL injection in `COWRebalanceEngine.execute` + `_assertGapBandIntactPostCommit` cancelOnly). **REVERTED `e2898e51`** ("remove placement guards that interfered with normal operation") — both sites removed; stranding is now handled by `calculateIdealBoundary` + `LAST-FILL-GUARD` + adoption path (P3 gate removed `e7231534`).
@@ -216,7 +226,7 @@ Sequence `Restored boundary index: 131` *then* `[SNAPSHOT-REJECT] Deleting corru
216
226
 
217
227
  ### 2. Ladder Recenter Orphan — Root Cause (Aug 26–30 2026)
218
228
 
219
- > **Source:** `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` · **Status:** fixes #1–#7 landed 2026-08-30.
229
+ > **Source:** former `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` (deleted 2026-08-31; merged here) · **Status:** fixes #1–#7 landed 2026-08-30.
220
230
 
221
231
  #### 2.1 Symptom
222
232
 
@@ -243,7 +253,7 @@ Falling market Aug 28 after ~17:00 UTC: bot **placed new SELLs below own live se
243
253
 
244
254
  **Mode B — lag (stale boundary).** Aug 29 09:32 swept up through sell rail slots 147–158 → then `09:32:21 Placed sell slot-129 -> <order-1>` filled 250 ms later, `09:32:33 slot-131`, `09:32:42 slot-132` — 15–25 levels below rail; `ANCHOR-DIVERGENCE projected=138 bookkept=123 drift=15`. Boundary crawled down with falling-market buys, re-rolled slots 129–132 as SELL into rising market. One instant fill set `maxFilledSellPrice=1044.79`, guard caught later attempts `15:47` (1 slot below) and `17:27` (4+8 below 1099.37/1112.62). **What PRICE_FIRST Phase 2 fixes.**
245
255
 
246
- **Mode C — COW commit geometry (separate).** Attribution corrected: `Batch transaction failed: Execution error: Order does not exist … cannot update` confirmed post-commit on bot-B: `<order-4>` `00:28:51 chunk1/3`, `<order-5>` `06:43:09 chunk5/9`, `<order-6>` `00:29:30` (`limit_order_update delta=-2341206 targets missing`). Broadcast refs missing orderId, aborts partial grid. `GAP-BAND VIOLATION after commit` = 0 in post-commit bot-A/B/C logs (evidence is bot-D `4` + D2 `11` dated Aug 26/28/29). Need: (a) COW rejects placement inside gap pre-broadcast; (b) pre-broadcast existence check off slot→orderId map. Gap case hardening independent.
256
+ **Mode C — COW commit geometry (separate).** Attribution corrected: `Batch transaction failed: Execution error: Order does not exist … cannot update` confirmed post-commit on bot-B: `<order-4>` `00:28:51 chunk1/3`, `<order-5>` `06:43:09 chunk5/9`, `<order-6>` `00:29:30` (`limit_order_update delta=-2341206 targets missing`). Broadcast refs missing orderId, aborts partial grid. `GAP-BAND VIOLATION after commit` = 0 in post-commit bot-A/B/C logs (evidence is bot-D `4` + D2 `11` dated Aug 26/28/29). Need: (a) COW rejects placement inside gap pre-broadcast; (b) pre-broadcast existence check off slot→orderId map. Gap case hardening independent. **Status: (b) LANDED `552b3ed7` (v1.6.14) as `UPDATE_TARGET_MISSING`; (a) deliberately shipped as a non-gating shadow (`gapBandPlacementShadowCount`) — see §9.2.**
247
257
 
248
258
  **Mode D — boundary-evidence re-derivation not persisted (freeze).** `grid_reconcile.ts:359-502` re-derives corrected boundary via `manager._restoreBoundary (:380)` but didn't survive next resync; bot-A re-derived at *every* hourly resync: `117→118 (00:28:48)`, `118→119 (01:00)`, `118→115 (02:00)`, `118→114 (03:00,04:00)`, `118→115 (04:30,05:00)`, `122→119 (07:00)` — 8× identical `ERROR` in ~7h. Bot-C `NO_FEASIBLE_BOUNDARY` → adoption-only at `00:27:17, 00:31:12, 04:27:48`; after `04:27:48` placed **zero orders 04:27:48→07:15:27 (~2h48m)** — only fills + `[ORPHAN-FILL]`. Earlier freeze `00:31→00:54`. Resumed only via fill-driven rotation `07:15`. → Fix #5 (LANDED).
249
259
 
@@ -307,7 +317,7 @@ Throttle `Structural resync defer` to first/last per cap window (was 120/30s); l
307
317
 
308
318
  ### 3. Orphan-Fill & Fund-Invariant — Root Cause & Fix Plan
309
319
 
310
- > **Source:** `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
320
+ > **Source:** former `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` (deleted 2026-08-31; merged here) · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
311
321
  > **Scope:** `dexbot_cow_runtime.ts`, `sync_engine.ts`, `chain_orders.ts`, `dexbot_state_recovery.ts`, `dexbot_maintenance_runtime.ts`, `strategy.ts`, `constants.ts` · **Evidence:** `profiles/logs/<bot>.log` Aug 28 17:40–17:57, Aug 29 15:13–15:19.
312
322
 
313
323
  #### 3.1 TL;DR — one cascade
@@ -363,7 +373,12 @@ P2 additions (2026-10-11, counter-only — none gated behavior):
363
373
  - `restampBuyAboveAnchorCount` — `recordRestampBuyAboveAnchor` counts a BUY emitted at/above the last filled BUY pivot (guard bypass or unjudgeable pivot), warned once per batch; it never blocks.
364
374
  - `boundaryDriftExceedsWindowCount` — `calculateTargetGrid` counts a derived boundary that jumps more than the active window in one plan (the detached-boundary signal the removed ANCHOR-DIVERGENCE telemetry used to carry), rate-limited warn.
365
375
  - `gapBandPlacementShadowCount` — the Mode C(a) shadow above.
366
- All five surface through `getMetrics()`; four via the existing `...bot._metrics` spread, and `boundaryDriftExceedsWindowCount` via an explicit overlay of `manager._metrics` (`getMetrics()`), because `calculateTargetGrid` writes it on the manager's metrics object and has no bot reference.
376
+
377
+ Spread-correction additions (counter-only, written on `manager._metrics` by `order/grid.ts` because the planner has no bot reference):
378
+ - `spreadCorrectionRefusedCount` / `spreadCorrectionRefusalCauses` — every spread-correction batch that failed to land, plus the per-`SPREAD_CORRECTION_REFUSAL`-cause breakdown.
379
+ - `spreadCorrectionRetryCount` — bounded fresh-master re-plan retries after a transient refusal.
380
+
381
+ All eight surface through `getMetrics()`; the five baseline counters via the existing `...bot._metrics` spread, and the manager-owned set (`boundaryDriftExceedsWindowCount` plus the three spread counters) via the `managerOwnedCounters()` overlay in `dexbot_maintenance_runtime.ts`, because those engines write on the manager's metrics object and have no bot reference.
367
382
 
368
383
  #### 3.4 Key code references (from source table)
369
384
 
@@ -373,7 +388,7 @@ All five surface through `getMetrics()`; four via the existing `...bot._metrics`
373
388
 
374
389
  ### 4. Price-First Alignment Plan
375
390
 
376
- > **Source:** `PRICE_FIRST_ALIGNMENT_PLAN.md` · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
391
+ > **Source:** former `PRICE_FIRST_ALIGNMENT_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
377
392
  > **Scope:** grid boundary state `modules/order/` · **Related:** three-layer crawl/anchor/guard fix.
378
393
 
379
394
  #### 4.1 Goal
@@ -444,7 +459,7 @@ Goal (Phase 2): I1–I6 property pass, full suite green, harness random, 48h per
444
459
  4. **LADDER #2/#3** identity + update-first hardening. — *done (`4838bcb0`).*
445
460
  5. **LADDER #5 / ORPHAN P0 recovery-by-ID** persistence (long freeze). — *done (`4838bcb0`, extended `a54863ca`; recovery-by-ID `1b27f6eb`).*
446
461
  6. **ORPHAN P0 ID-based adoption** + **P1 atomicity** (stale-plan race). — *P0 done (`1b27f6eb`, retry `d808c052`); atomicity partial.*
447
- 7. **ORPHAN P1 rotation + P1 duplicate + GAP P3/P5 + Mode C guards + P2 guardrails** fast-follow. — *rotation + GAP P5 done; GAP P3 reverted `e7231534` (`validateBoundaryAgainstChainEvidence`/`placementsAllowed` removed); duplicate-cancel hard-error, Mode C guards and P2 counters open.*
462
+ 7. **ORPHAN P1 rotation + P1 duplicate + GAP P3/P5 + Mode C guards + P2 guardrails** fast-follow. — *rotation + GAP P5 done; GAP P3 reverted `e7231534` (`validateBoundaryAgainstChainEvidence`/`placementsAllowed` removed); Mode C pre-broadcast UPDATE guard and P2 counters LANDED `552b3ed7` (§9.2); the in-gap reject ships as a shadow, not a block.*
448
463
  8. **PRICE Phase 3/4** only after evidence (`grid_correction_check` see §7). If soak never clean, stop at Phase 2. — *Phase 3 moot; Phase 4 golden tests landed.*
449
464
 
450
465
  ---
@@ -474,7 +489,7 @@ Pairs-checked base excludes cross-pair unless flagged; strict sat-level detectio
474
489
  - Shifted center → every live order adopted or immediate cancel (no silent unmanaged); startup reconcile replays: bot-A `<order-8>` 07:00 and `<order-9>` 6× loop must stay managed, no `ORPHAN-FILL`.
475
490
  - Boundary re-derivation persists: bot-A `00:28–07:00` must not repeat `[BOUNDARY-EVIDENCE]` for unchanged chain.
476
491
  - `NO_FEASIBLE_BOUNDARY` bot-C `04:27:48` resumes on next sync tick (bounded, not hours) with WARN.
477
- - Post-broadcast read-back retry: bot-B `06:43` no `14` piled / forced resync mid-broadcast.
492
+ - Post-broadcast read-back retry: bot-B `06:43` no `14` piled / forced resync mid-broadcast. *(Addressed v1.6.13–1.6.14 by the resync-cascade break (`7eb65c8e`) and the fresh-placement cancel grace (`85a7e7f0`); see §9.)*
478
493
  - COW commit never places inside gap; pre-broadcast existence check: bot-B `<order-4/5>` + bot-D/D2 `GAP-BAND` fixtures → `0`. *(Amended: the commit-time in-gap cancel sweep was reverted `e2898e51` — current expectation is adoption-after-chain-evidence-correction; `0` unmanaged in-gap orders remains the target.)*
479
494
  - Aug 28 burst `17:09–17:16` (3 regs/6m, sells 1110–1176) → `0` orphans, `0` sells below asks.
480
495
  - **Orphan regression over ~7h post-`cd690000` on bot-A/B/C:** distinct `Unmatched` `58/60/91 → ~0` (full `229/107/172 → ~0`), `Fund invariant violation` `0` (was `3077.07→3184.93` etc.), `ORPHAN-FILL` `0` (was `7/33/22`), repeated `[BOUNDARY-EVIDENCE]` `0`, deferred minutes `0`, `[MAINT] n/m failed` `0`.
@@ -490,7 +505,142 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
490
505
  - [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
491
506
  - [x] Stale `*.md` filename references in code comments/tests updated to the consolidated doc (9 module files, 6 test files), then re-pointed to this hub when it absorbed the summary.
492
507
 
493
- *Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
508
+ *Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13) and extended through v1.6.14 at `f6c0df32` (2026-10-12; see §9). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
509
+
510
+ ---
511
+
512
+ ### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.14)
513
+
514
+ > **Source:** `CHANGELOG.md` v1.6.4 → v1.6.14 · **Snapshot:** `f6c0df32` (2026-10-12).
515
+ > Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
516
+
517
+ Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
518
+ proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
519
+ **stop the engine from destroying good state**, and **fail closed when geometry is unknown**.
520
+
521
+ #### 9.1 The synthesis: avoid the destructive resync
522
+
523
+ R4's fixes (genesis determinism, one writer, the last-fill guard) closed the *orphan* family.
524
+ The remaining harm was self-inflicted: **structural resyncs fired on evidence that did not
525
+ justify them**, and each reset clears the LAST-FILL-GUARD pivot and any gap-evacuation streak.
526
+ The engine now treats uncertainty as *defer, never rebuild*:
527
+
528
+ - **Uncertain-broadcast reconciliation is master-aware** (`7eb65c8e`, v1.6.13):
529
+ `resyncIfUnreconciled` treats a chain order as reconciled if master already tracks it
530
+ (`collectKnownOnChainOrderIds`), not merely if it appears in this batch's adopted set.
531
+ Before, a populated grid (`W` chain orders − `A` adopted ≫ 0) forced a full rebuild — and a
532
+ LAST-FILL pivot wipe — after *every* uncertain broadcast.
533
+ - **A suspended persistence is a deferral, not divergence** (`7eb65c8e`): a credential-daemon
534
+ outage (`persistGrid()` → `{skipped, suspended}`) marks the committed grid dirty for the
535
+ end-of-tick flush instead of escalating to a resync. The daemon watchdog also sets the
536
+ recovery flag that actually re-runs `resumeGridPersistence()` — previously a transient ping
537
+ timeout suspended persistence for hours and cascade-resynced the grid many times in one window.
538
+ - **Unknown geometry fails closed** (`5003b8ef`, `750386ac`, `dc87ce01`, `249016e4`, v1.6.14):
539
+ `Number(null) === 0` and `Number('') === 0` had made an unknown boundary/gap read as the
540
+ *valid* value `0`, casting real geometry around slot 0. `Format.toKnownNumber` keeps
541
+ `null`/`undefined`/`''` unknown (a genuine `0` stays `0`) across the gap-evacuation
542
+ candidates, `geometryTypeForSlotIndex`, evac stamping, `optimizeRebalanceActions`,
543
+ `planVacatedRailRefill`, `buildCowResultFromPlan`, the gap-band shadow and the guard
544
+ fallback; `validateBoundaryCommit` rejects every other non-numeric value (`'abc'`, `NaN`,
545
+ `Infinity`) as `non_integer_boundary` again (the 1.6.13 absent-aware rewrite had widened
546
+ "garbage" to "no proposal").
547
+ - **The LAST-FILL reference survives regeneration** (`09dbaad7`, `f1c331bd`, v1.6.14): a
548
+ bot-scoped last-market-fill row (price/type/fillsAt) is restored at startup under a 24h TTL,
549
+ so a `clearGrid()`/regeneration no longer wipes the anti-through-trade pivot.
550
+ `evaluateSpreadCorrectionReadiness()` is the single verdict (cold book = hard refuse; stale
551
+ snapshot/unmatched orders = plan-but-withhold-the-bypass), with the NEWER of a live
552
+ order-book/ticker read and the fill anchor as the crossing floor;
553
+ `SPREAD_CORRECTION_SYNC_FRESH_MS` is the one trust window.
554
+
555
+ #### 9.2 Pre-broadcast atomicity — Mode C now guarded (`552b3ed7`, v1.6.14)
556
+
557
+ Mode C (§2.3) is the `Order does not exist … cannot update` abort that leaves a partially
558
+ applied grid. Its pre-broadcast existence check — the second of Mode C's two "Need"s — is now
559
+ implemented in `runPreBroadcastGuards`: every UPDATE action's tracked `orderId` is re-read
560
+ (`batchReadOrders`), fail-open on a non-Map/errored read, then re-verified one by one
561
+ (`readSingleOrder`) so a lagging node cannot manufacture an absence. Any target still missing
562
+ aborts the whole batch (`UPDATE_TARGET_MISSING`), pops the working grid and requests a
563
+ structural resync — the divergence is refused *before* the wire, never half-applied.
564
+
565
+ Mode C's first "Need" (reject placement inside the gap band pre-broadcast) was deliberately
566
+ **not** implemented as a block: spread correction legitimately places into the band (that is
567
+ what the LAST-FILL-GUARD bypass is for), and a hard reject re-opens the P1 regression class.
568
+ It ships as an observability **shadow** (`gapBandPlacementShadowCount`, warned, never gating).
569
+ `COW_ORIGINS` (`eca90ce6`, v1.6.13) makes the bypass's `origin` keys a single frozen constant,
570
+ so a typo can no longer silently disable the spread-correction / gap-evacuation bypass.
571
+
572
+ #### 9.3 Don't churn orders the pipeline just placed
573
+
574
+ - **Fresh-placement cancel grace** (`85a7e7f0`, v1.6.12): `SURPLUS_CANCEL_GRACE_MS` (15 min)
575
+ timestamps placements (`_placedAt`) and surplus/cancel-only sweeps skip orders inside the
576
+ window (covering the batched and serial paths; `grid-load`/`grid-init` excluded so restarts
577
+ still sweep).
578
+ - **Spread correction repairs what it places** (`cd82cd8a`, v1.6.12): create-only, funded from
579
+ available balance; a distance-sorted windowed-rail ordering bridges contiguously from the
580
+ live window instead of leaving an interior hole. It tightens the spread rather than walking
581
+ to the rail edge (`67377d58`, v1.6.9) and is fund-driven (`589cb30e`, v1.6.4).
582
+ - **Committed-size drift resize** (`16308f72`, `d8a97f76`, v1.6.14): an external
583
+ deposit/withdrawal shifting a side's budget ≥3% resizes all of that side's on-chain orders
584
+ on the next pipeline-empty tick; the trigger is unified in `checkAndUpdateGridIfNeeded` so the
585
+ ratio legs cannot be consumed in isolation.
586
+ - **Orphan double-count pruned** (`1f272cee` v1.6.11, `073cceca` v1.6.12): slotless chain
587
+ orders are counted as committed funds, so adopting one *into* a slot must remove the stale
588
+ `_lastUnmatchedChainOrders` record; both success exits and the `createOrder` materialize
589
+ branch prune it by chain id.
590
+
591
+ #### 9.4 Removing writers — the genesis cleanup (`b2f4a65f`, v1.6.8)
592
+
593
+ Appendix A's writer chain is closed at the source: a persisted grid with no usable price
594
+ ladder is **refused** at load (`MissingGenesisError` before any mutation;
595
+ `MISSING_GENESIS_POLICY` `rebuild`/`halt`) instead of loading ladder-less and degrading every
596
+ slot-price consumer to a tolerance matcher. The legacy tolerance matcher,
597
+ `findMatchingGridOrderByOpenOrder`, the `price-drift-orphan` auto-cancel and the pass-1
598
+ price-equality / duplicate-swap tolerance fallbacks are deleted, and `syncFromOpenOrders` is
599
+ fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and sources of
600
+ truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
601
+ required is no longer reachable at runtime.
602
+
603
+ #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.6.14)
604
+
605
+ | Commit | Release | Change |
606
+ |---|---|---|
607
+ | `589cb30e` | 1.6.4 | Spread correction purely fund-driven with a balance refresh fallback |
608
+ | `1f2fd7ae` | 1.6.4 | Fill/broadcast batch cap raised to `gapSlots + 1` |
609
+ | `f90c4b6c` | 1.6.4 | Include VIRTUAL orders in RMS structural divergence |
610
+ | `224f92ee` | 1.6.6 | Harden stale cancellation guards |
611
+ | `b14a1fc8` | 1.6.7 | Persist/restore the LAST-FILL-GUARD pivot with the grid snapshot |
612
+ | `cd6c15fb` | 1.6.7 | Fill-channel watchdog recovery and accounting |
613
+ | `8c4baa69` | 1.6.7 | Recover dead-but-open sessions; stop stale COW re-broadcasts |
614
+ | `b2f4a65f` | 1.6.8 | Refuse persisted grids with no usable price ladder (genesis policy) |
615
+ | `dbd86cc8` | 1.6.8 | Bound the correction drain by wall-clock; surface long grid-lock holds |
616
+ | `67377d58` | 1.6.9 | Spread correction tightens the spread instead of walking to the rail edge |
617
+ | `1f272cee` | 1.6.11 | Five order-engine/lifecycle fixes (orphan accounting, double-count, grace, …) |
618
+ | `85a7e7f0` | 1.6.12 | Defer cancels of freshly placed orders in COW reconcile/divergence |
619
+ | `073cceca` | 1.6.12 | Prune the deferred-orphan record when createOrder linkage binds the slot |
620
+ | `cd82cd8a` | 1.6.12 | Keep spread correction funded by repairing what it places |
621
+ | `7eb65c8e` | 1.6.13 | Break resync cascades; suspended persistence is a deferral |
622
+ | `edb53176` | 1.6.13 | Report spread-correction stall causes |
623
+ | `6480923c` | 1.6.13 | Sync with the chain on every spread-correction stall |
624
+ | `eca90ce6` | 1.6.13 | Centralize COW plan-origin labels in `COW_ORIGINS` |
625
+ | `09dbaad7` | 1.6.14 | Never let spread correction trade through the last real fill |
626
+ | `f1c331bd` | 1.6.14 | Single readiness gate + live market floor |
627
+ | `16308f72` | 1.6.14 | Resize the full side when a deposit slips past the fund ratio |
628
+ | `d8a97f76` | 1.6.14 | Harden committed-size drift; unify the fund trigger |
629
+ | `552b3ed7` | 1.6.14 | COW pre-broadcast UPDATE-target guard + P2 counters |
630
+ | `5003b8ef` | 1.6.14 | Guard unknown boundary/gap across gap-evacuation and COW shadow paths |
631
+ | `750386ac` | 1.6.14 | Guard unknown boundary in the gap-band shadow |
632
+ | `dc87ce01` | 1.6.14 | Close missed 1.6.13 regressions in absent geometry and the rebuild guard |
633
+ | `249016e4` | 1.6.14 | Keep `validateBoundaryCommit` fail-closed for garbage boundaries |
634
+
635
+ #### 9.6 Invariants added
636
+
637
+ - **Uncertainty defers, it does not rebuild:** a resync requires a chain order unknown to
638
+ master, a non-suspension persist divergence, or a proven pre-broadcast UPDATE-target gap.
639
+ - **Unknown geometry is unknown:** no code path may coerce absent boundary/gap to `0`.
640
+ - **Atomic-or-refused:** a COW batch either applies wholly on chain or is refused before the
641
+ wire; no `limit_order_update` may abort a chunk.
642
+ - **Placed is not surplus:** an order inside `SURPLUS_CANCEL_GRACE_MS` is never cancelled by a
643
+ sweep running on a stale snapshot.
494
644
 
495
645
  ---
496
646
 
package/docs/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
4
4
 
5
- **Version context:** v1.6.14 (released).
5
+ **Version context:** v1.6.16 (released).
6
6
 
7
7
  ---
8
8
 
package/docs/WORKFLOW.md CHANGED
@@ -252,16 +252,17 @@ the canonical name is preferred in scripts and docs.
252
252
  | `dexbot order` | `orders` | Analyze persisted order grids (spread, increment, funds); `--export` for HTML |
253
253
  | `dexbot order [<bot>]` | — | Analyze only the specified bot's order grid |
254
254
  | `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot>]`) |
255
+ | `dexbot rich <asset...>` | — | Top holder(s) per asset via the chain asset-holders API (`--top N`, `--json`/`--csv`) |
255
256
  | `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool-id|AssetA/AssetB>` over `--month N` (default 3) |
256
257
  | `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
257
258
  | `dexbot pnl <account>` | — | HTML PnL report for a bot/account over `--month N`, optional `--pair BASE/QUOTE` filter |
258
259
  | `dexbot git` | — | Analyze repository git history and write an added/deleted-lines HTML chart (`repo-stats.html`; source checkouts only) |
259
- | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots |
260
+ | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots. Whole-runtime: an optional bot name is validated, then ignored |
260
261
  | `dexbot start` | `unlock` | Run credential daemon + bot (equivalent to running the `unlock` runtime, `dist/unlock.js`) |
261
- | `dexbot stop` | `stp`, `stopall` | Stop the monolithic runtime (unlock mode) |
262
- | `dexbot reload` | `reloadall` | Reload the monolithic runtime without touching the credential daemon (unlock mode) |
263
- | `dexbot restart` | `restartall` | Restart the monolithic runtime (unlock mode, re-unlocks credential daemon) |
264
- | `dexbot delete` | — | Shut down and clean up the monolithic runtime (unlock mode) |
262
+ | `dexbot stop [<bot>]` | `stp`, `stopall` | Stop the runtime. Monolithic: whole runtime (a bot argument folds into it with a notice); `--isolated`: just that bot |
263
+ | `dexbot reload [<bot>]` | `reloadall` | Reload without touching the credential daemon. Same per-bot target rules as `stop` |
264
+ | `dexbot restart [<bot>]` | `restartall` | Restart and re-unlock the credential daemon. Same per-bot target rules as `stop` |
265
+ | `dexbot delete` | — | Shut down and clean up the monolithic runtime. Whole-runtime only; rejects a bot argument |
265
266
  | `dexbot clear` | — | Delete `*.log`, rotated `*.log.*` and `*.jsonl*` from the logs directory (`<profiles>/logs`) |
266
267
  | `dexbot clear-orders` | — | Delete all persisted order files (`<profiles>/orders`); grids regenerate on next start |
267
268
  | `dexbot clear-market-adapter` | — | Delete market adapter data, state (incl. `market_adapter.lock`), and adapter logs |
@@ -487,8 +487,9 @@ The correction path is fund-only and never manufactures budget by shrinking a re
487
487
  5. If free funds cannot cover every target, place the affordable prefix, stop
488
488
  without shrinking inventory, and log the fund-constrained remainder.
489
489
  6. If neither side places an effective order, `checkSpreadCondition` reports a
490
- `stall` cause (`no-free-funds` / `unfunded` / `no-candidates` /
491
- `batch-not-executed` / `apply-error`). Every cause arms the targeted
490
+ `stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
491
+ `unmatched-orders` / `readiness-gate` / `batch-not-executed` / `apply-error`).
492
+ Every cause arms the targeted
492
493
  balances + open-orders refresh: the local snapshot the check reasoned over
493
494
  may be stale (`no-candidates` can mean a missed fill left an ACTIVE slot
494
495
  occupying the window edge, so no tightening slot appears to exist), and only
@@ -525,6 +526,59 @@ const availableFund = Math.max(0, Math.min(
525
526
  - ✅ Funds always respected (no forced allocation)
526
527
  - ✅ Natural smoothing over multiple rebalance cycles
527
528
 
529
+ ### Resilience: Atomic Broadcast, Plan-Time Dedupe, Bounded Re-Plan
530
+
531
+ A correction is planned under `_gridLock` but broadcast *after* the lock is
532
+ released, so a concurrent fill rebalance can invalidate it in that window. Left
533
+ alone, the batch is refused fail-closed and the grid waits for a fill it cannot
534
+ produce (an out-of-spread grid generates no fill) — the stale-grid pathology.
535
+ `checkSpreadCondition` wraps the plan/broadcast in a bounded, region-held
536
+ attempt loop so a stale plan heals in place:
537
+
538
+ 1. **Region hold (atomicity).** The refcounted broadcast region
539
+ (`startBroadcasting` / `stopBroadcasting`, released in `finally`) is held for
540
+ the whole attempt loop, so a fill rebalance defers instead of committing a
541
+ master-version bump between the plan and its broadcast. This narrows the
542
+ race; the COW commit guard remains the backstop.
543
+ 2. **Plan-time CREATE dedupe.** Before broadcasting, `getOccupiedCorrectionSlots`
544
+ checks whether a planned destination became a live order since planning, and
545
+ `resolveOccupiedCorrection` re-derives from fresh master or withholds the
546
+ colliding batch. A known-taken slot is never shipped (the COW build layer is
547
+ still authoritative against a false positive).
548
+ 3. **Bounded fresh-master re-plan.** On a **transient** refusal (stale plan /
549
+ duplicate CREATE / unclassified non-execution) the cycle re-plans once from
550
+ fresh master (`replanSpreadCorrectionFromFreshMaster`) and retries —
551
+ `TIMING.SPREAD_CORRECTION_MAX_ATTEMPTS` (default 2 = initial + one retry).
552
+ A **non-transient** refusal (commit-refused, update-target-missing, unmatched
553
+ chain orders, shutdown) is not retried and counts toward grid staleness.
554
+ 4. **Observability.** `spreadCorrectionRefusedCount`, per-cause
555
+ `spreadCorrectionRefusalCauses` (vocabulary `SPREAD_CORRECTION_REFUSAL`), and
556
+ `spreadCorrectionRetryCount`, surfaced through `getMetrics()` and the shutdown
557
+ line separately from the generic `refusedCommitCount`.
558
+
559
+ **Retry invariant:** an `uncertain: true` COW result is retry-safe only while the
560
+ COW layer adopts-or-defers-with-guard into master before returning. The
561
+ adopt/discard path persists first; the ambiguous-read path keeps pending-broadcast
562
+ protection (the existing orderId build guard is the fail-safe, not fail-fast).
563
+
564
+ ### Out-of-Spread Watchdog
565
+
566
+ Independent of the in-cycle retry, the maintenance watchdog (`trackOutOfSpreadStaleness`)
567
+ tracks how long the grid has been continuously out of tolerance **without an
568
+ effective correction**:
569
+
570
+ - warns once past `TIMING.SPREAD_STALE_WARN_MS`;
571
+ - escalates to a structural re-center past `TIMING.SPREAD_STALE_ESCALATE_MS`
572
+ (cooldown `TIMING.SPREAD_STALE_RESYNC_COOLDOWN_MS`);
573
+ - tolerates up to `TIMING.SPREAD_STALE_TRANSIENT_GRACE` consecutive **transient**
574
+ refusals (which reset the stale clock) before they count toward escalation, so a
575
+ retryable refusal is not mistaken for a structural dead end — a persistent one
576
+ still re-centers.
577
+
578
+ These spread knobs (with `SPREAD_CORRECTION_SYNC_FRESH_MS`) are global `TIMING`
579
+ keys, overridable under `TIMING` in `profiles/general.settings.json`; they are not
580
+ per-bot settings.
581
+
528
582
  ---
529
583
 
530
584
  ## Periodic Market Price Refresh
@@ -111,7 +111,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
111
111
  | **WorkingGrid** | Mutable clone of the master grid used during planning. Created by `new WorkingGrid(masterGrid)`. Discarded on failure; committed on success. Lives in `modules/order/working_grid.ts`. |
112
112
  | **COW Rebalance** | The full plan→broadcast→commit cycle: `_applySafeRebalanceCOW()` → `_updateOrdersOnChainBatchCOW()` → `_commitWorkingGrid()` |
113
113
  | **Atomic Commit** | `_commitWorkingGrid(workingGrid, indexes, boundary, options = {})` swaps master to the working copy in a single operation, then increments `_gridVersion`. |
114
- | **Staleness / Version Mismatch** | If a fill mutates the master grid while a rebalance is in progress, the working grid is marked stale. The commit guard rejects stale or version-mismatched working grids. |
114
+ | **Staleness / Version Mismatch** | If a fill mutates the master grid while a rebalance is in progress, the working grid is marked stale. The commit guard rejects stale or version-mismatched working grids. Spread correction additionally holds the broadcast region across a bounded fresh-master re-plan ([architecture.md](architecture.md) → Spread Correction → Resilience). |
115
115
  | **`_gridVersion`** | Integer counter incremented on every master-grid mutation. Used by commit guards to detect concurrent master changes. |
116
116
  | **`_gridLock`** | `AsyncLock` that serializes all master-grid mutations to prevent races. |
117
117
  | **`syncFromMaster()`** | WorkingGrid method that selectively syncs one order from the master into the working copy during fills, avoiding a full abort. |
@@ -787,6 +787,10 @@ checkAndUpdateGridIfNeeded(manager)
787
787
  // checkAndUpdateGridIfNeeded above
788
788
  checkCommittedSizeDrift(manager)
789
789
 
790
+ // Spread correction: plan-time dedupe + bounded fresh-master re-plan retry,
791
+ // wrapped in a held broadcast region (see architecture.md → Resilience)
792
+ checkSpreadCondition(manager, BitShares, batchCb)
793
+
790
794
  // Compare ideal vs. persisted grid
791
795
  compareGrids(calculatedGrid, persistedGrid, manager)
792
796
  ```
@@ -240,13 +240,18 @@ Pair-specific AMA profiles live in `profiles/market_profiles.json`:
240
240
  "intervalSeconds": 3600,
241
241
  "defaultAma": "AMA1",
242
242
  "amas": {
243
- "AMA1": { "erPeriod": 200, "fastPeriod": 3, "slowPeriod": 80 },
244
- "AMA2": { "erPeriod": 500, "fastPeriod": 5, "slowPeriod": 120 }
243
+ "AMA1": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 62.1 },
244
+ "AMA2": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 72.0 }
245
245
  }
246
246
  }]
247
247
  }
248
248
  ```
249
249
 
250
+ > The `amas` periods above are the fitted built-in presets (`MARKET_ADAPTER.AMAS`),
251
+ > shown here only to make the shape concrete. A real pair profile needs just the
252
+ > fields it changes — e.g. `"AMA3": { "slowPeriod": 90 }` keeps the built-in
253
+ > `erPeriod`/`fastPeriod` and overrides only `slowPeriod`.
254
+
250
255
  `profiles/market_adapter_settings.json` layers:
251
256
 
252
257
  ```json
@@ -489,7 +494,7 @@ Per cycle, per processed bot, the adapter can produce:
489
494
 
490
495
  ### Files
491
496
 
492
- <details><summary>Config and state files (click to expand)</summary>
497
+ <details><summary><mark>Config and state files (click to expand)</mark></summary>
493
498
 
494
499
  | File | Purpose |
495
500
  |------|---------|
@@ -574,12 +579,13 @@ Typical fields:
574
579
 
575
580
  ### Module Map
576
581
 
577
- <details><summary>Directory layout (click to expand)</summary>
582
+ <details><summary><mark>Directory layout (click to expand)</mark></summary>
578
583
 
579
584
  ```text
580
585
  market_adapter/
581
586
  |-- market_adapter.ts main adapter daemon
582
587
  |-- ama_signal_runner.ts one-cycle JSON signal CLI
588
+ |-- cli_args.ts shared CLI argument walker
583
589
  |-- candle_utils.ts candle transforms, gap detection, pruning
584
590
  |-- interval_utils.ts shared interval label + chain-time helpers
585
591
  |-- lp_chart_core.ts chart HTML renderer
@@ -623,6 +629,7 @@ market_adapter/
623
629
  | |-- file_lock.ts single-instance file lock
624
630
  | |-- file_json_cache.ts write-through JSON read cache
625
631
  | |-- month_shards.ts calendar-month shard naming + coverage-span primitives (shared by candle and fills caches)
632
+ | |-- pair_orientation.ts canonical pair orientation + reciprocal inversion helpers
626
633
  | |-- data_discovery.ts data directory auto-discovery + shard-family assembly
627
634
  | |-- atomic_write.ts atomic file write utility
628
635
  | |-- dynamic_grid_snapshot.ts dynamic grid snapshot helpers
@@ -798,7 +805,7 @@ snapshot.
798
805
 
799
806
  Main override knobs live in `profiles/market_adapter_settings.json`:
800
807
 
801
- <details><summary>Full settings table (click to expand)</summary>
808
+ <details><summary><mark>Full settings table (click to expand)</mark></summary>
802
809
 
803
810
  | Setting | Meaning |
804
811
  |---------|---------|
@@ -863,7 +870,7 @@ closed 1h candles.
863
870
 
864
871
  #### Shared Month-Shard Cache and Fetch Robustness
865
872
 
866
- Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
873
+ Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Pair orientation is canonicalized (the lower asset id is always leg A on disk), so `bts/iob.xrp` and `iob.xrp/bts` share one shard family: the fetch queries the canonical side and the result is inverted back for the requested side (inverse volume uses the same base×close approximation as the TV chart's inverse view). A legacy inverse-orientation family is read once as a migration source and folded into the canonical shards instead of being re-fetched. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
867
874
 
868
875
  #### AMA Warmup Window — Why Candle Length Matters
869
876
 
@@ -987,7 +994,7 @@ removed manually.
987
994
 
988
995
  Important fields in `market_adapter/state/market_adapter_state.json`:
989
996
 
990
- <details><summary>Field reference (click to expand)</summary>
997
+ <details><summary><mark>Field reference (click to expand)</mark></summary>
991
998
 
992
999
  | Field | Meaning |
993
1000
  |-------|---------|
package/modules/README.md CHANGED
@@ -88,7 +88,7 @@ modules/
88
88
  │
89
89
  ├── order/ order lifecycle and grid management
90
90
  │ ├── manager.ts OrderManager — central controller, COW rebalance
91
- │ ├── grid.ts grid generation, sizing, health
91
+ │ ├── grid.ts grid generation, sizing, spread correction, health
92
92
  │ ├── working_grid.ts COW grid wrapper for safe mutations
93
93
  │ ├── strategy.ts grid rebalancing, consolidation, rotation
94
94
  │ ├── accounting.ts fund tracking, fee accounting
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.14",
3
+ "version": "1.6.16",
4
4
  "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
5
5
  "main": "dist/modules/dexbot_class.js",
6
6
  "exports": {
@@ -98,6 +98,7 @@
98
98
  "analysis:trade-pnl": "npm run build && node dist/analysis/trade_profitability.js",
99
99
  "analysis:grid-check": "npm run build && node dist/analysis/grid_correction_check.js",
100
100
  "analysis:resolve-accounts": "npm run build && node dist/analysis/resolve_bot_accounts.js",
101
+ "richlist": "npm run build && node dist/scripts/rich_list.js",
101
102
  "native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
102
103
  "native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
103
104
  "native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",
@@ -108,6 +109,7 @@
108
109
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
109
110
  "test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
110
111
  "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
112
+ "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
111
113
  "clean": "node scripts/clean-dist.js",
112
114
  "build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
113
115
  "build:clean": "npm run clean && npm run build",
@@ -156,6 +158,7 @@
156
158
  "./dist/modules/launcher/status_reporting.js": false,
157
159
  "./dist/modules/launcher/supervisor_control.js": false,
158
160
  "./dist/modules/launcher/monolithic_runtime.js": false,
161
+ "./dist/modules/launcher/runtime_mode.js": false,
159
162
  "./dist/modules/launcher/market_adapter_runtime.js": false,
160
163
  "./dist/modules/launcher/market_adapter_watchdog.js": false,
161
164
  "./dist/modules/launcher/foreign_cred_daemon.js": false,