dexbot 1.6.13 → 1.6.15

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 (114) hide show
  1. package/CHANGELOG.md +66 -4
  2. package/README.md +2 -2
  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/AI_BOT_LIBRARY_API.md +1 -1
  7. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  8. package/claw/modules/claw_catalog.ts +8 -4
  9. package/claw/modules/dexbot_profiles.ts +59 -15
  10. package/claw/modules/types.ts +2 -1
  11. package/claw/package.json +1 -1
  12. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  13. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  14. package/claw/skills/margin-trading/SKILL.md +1 -1
  15. package/claw/skills/margin-trading/references/position-management.md +1 -1
  16. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +105 -31
  17. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +36 -2
  18. package/dist/dexbot.js +23 -3
  19. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  20. package/dist/modules/account_bots.d.ts +10 -6
  21. package/dist/modules/account_bots.js +13 -10
  22. package/dist/modules/account_orders.d.ts +36 -4
  23. package/dist/modules/account_orders.js +76 -5
  24. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  25. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  26. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  27. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  28. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  29. package/dist/modules/bot_defaults.d.ts +29 -4
  30. package/dist/modules/bot_defaults.js +65 -10
  31. package/dist/modules/bot_settings.d.ts +4 -0
  32. package/dist/modules/bot_settings.js +58 -21
  33. package/dist/modules/config.js +6 -1
  34. package/dist/modules/constants.d.ts +13 -5
  35. package/dist/modules/constants.js +36 -5
  36. package/dist/modules/credit_runtime.d.ts +35 -5
  37. package/dist/modules/credit_runtime.js +219 -38
  38. package/dist/modules/dexbot_class.d.ts +23 -0
  39. package/dist/modules/dexbot_class.js +60 -17
  40. package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
  41. package/dist/modules/dexbot_cow_runtime.js +350 -64
  42. package/dist/modules/dexbot_credential_client.d.ts +1 -16
  43. package/dist/modules/dexbot_credential_client.js +1 -1
  44. package/dist/modules/dexbot_fill_runtime.d.ts +2 -2
  45. package/dist/modules/dexbot_fill_runtime.js +16 -8
  46. package/dist/modules/dexbot_maintenance_runtime.d.ts +24 -81
  47. package/dist/modules/dexbot_maintenance_runtime.js +104 -70
  48. package/dist/modules/dexbot_startup_runtime.js +15 -2
  49. package/dist/modules/dexbot_state_recovery.js +17 -1
  50. package/dist/modules/key_store.d.ts +0 -5
  51. package/dist/modules/key_store.js +1 -1
  52. package/dist/modules/order/accounting.js +11 -11
  53. package/dist/modules/order/export.js +4 -4
  54. package/dist/modules/order/format.d.ts +15 -1
  55. package/dist/modules/order/format.js +19 -1
  56. package/dist/modules/order/genesis_policy.d.ts +1 -1
  57. package/dist/modules/order/genesis_policy.js +1 -1
  58. package/dist/modules/order/grid.d.ts +141 -12
  59. package/dist/modules/order/grid.js +666 -92
  60. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  61. package/dist/modules/order/grid_reconcile.js +9 -8
  62. package/dist/modules/order/grid_reconcile_internal.js +61 -58
  63. package/dist/modules/order/index.d.ts +37 -9
  64. package/dist/modules/order/logger.js +2 -2
  65. package/dist/modules/order/manager.d.ts +10 -2
  66. package/dist/modules/order/manager.js +56 -31
  67. package/dist/modules/order/strategy.d.ts +2 -2
  68. package/dist/modules/order/strategy.js +51 -21
  69. package/dist/modules/order/sync_engine.js +22 -9
  70. package/dist/modules/order/utils/math.d.ts +101 -29
  71. package/dist/modules/order/utils/math.js +215 -84
  72. package/dist/modules/order/utils/order.d.ts +58 -58
  73. package/dist/modules/order/utils/order.js +135 -106
  74. package/dist/modules/order/utils/system.d.ts +193 -6
  75. package/dist/modules/order/utils/system.js +394 -31
  76. package/dist/modules/order/utils/validate.d.ts +1 -1
  77. package/dist/modules/order/utils/validate.js +71 -59
  78. package/dist/modules/runtime_settings.d.ts +1 -1
  79. package/dist/modules/runtime_settings.js +3 -3
  80. package/dist/modules/types.d.ts +55 -4
  81. package/dist/scripts/analyze-credit.js +44 -27
  82. package/dist/scripts/analyze-orders.d.ts +1 -1
  83. package/dist/scripts/analyze-orders.js +4 -4
  84. package/dist/scripts/diagnose-pool-history.js +35 -30
  85. package/dist/scripts/divergence-calc.js +6 -6
  86. package/dist/scripts/pnl.js +1 -1
  87. package/dist/scripts/rich_list.d.ts +18 -0
  88. package/dist/scripts/rich_list.js +461 -0
  89. package/dist/scripts/run-tests.js +80 -4
  90. package/dist/scripts/validate_bots.d.ts +1 -1
  91. package/dist/scripts/validate_bots.js +3 -3
  92. package/dist/unlock.d.ts +2 -1
  93. package/dist/unlock.js +11 -5
  94. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
  95. package/docs/COW_INVARIANTS.md +12 -6
  96. package/docs/DEXBOT_COMPARISON.md +7 -7
  97. package/docs/EVOLUTION.md +10 -8
  98. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  99. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  100. package/docs/GRID_RECALCULATION.md +4 -1
  101. package/docs/GRID_RECONCILE.md +4 -4
  102. package/docs/LIFECYCLE.md +11 -11
  103. package/docs/LOGGING.md +30 -1
  104. package/docs/MPA_CREDIT_USAGE.md +11 -6
  105. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +170 -12
  106. package/docs/README.md +3 -3
  107. package/docs/WORKFLOW.md +1 -0
  108. package/docs/architecture.md +62 -8
  109. package/docs/developer_guide.md +12 -3
  110. package/market_adapter/README.md +4 -4
  111. package/modules/README.md +1 -1
  112. package/package.json +2 -1
  113. package/scripts/README.md +59 -32
  114. package/tests/README.md +12 -3
@@ -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
  ---
@@ -72,10 +75,10 @@ local state.
72
75
  | **Infinite loops** | grid-bloat → resync → bloat; plan→skip→restore holes; `NO_FEASIBLE_BOUNDARY` freeze | Cooldowns, grace windows, minimal cancel ladders |
73
76
  | **Silent hangs** | Retries that depended on a future event that never came | Level-triggered scheduling with time-based watchdogs |
74
77
  | **Stale queues** | Queued price corrections replayed onto a resynced grid, reverting good placements | Pre-broadcast validation against the live slot |
75
- | **Shelf / reserve orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
78
+ | **Shelf / edge orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
76
79
 
77
80
  Families **not** detailed in Part II: silent hangs and stale correction queues are covered in
78
- `CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/reserve orders in issue #27 and the v1.6.x
81
+ `CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/edge orders in issue #27 and the v1.6.x
79
82
  notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md).
80
83
 
81
84
  ### R3. Meta-patterns (the actual "madness")
@@ -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
 
@@ -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
 
@@ -295,7 +305,7 @@ Debug line: `[BOUNDARY] boundary=123 sellStart=128 spread=4 anchorProjected=138
295
305
  **#7 Sync-lock/maintenance observability — LANDED.**
296
306
  Throttle `Structural resync defer` to first/last per cap window (was 120/30s); log/retry `[MAINT] n/m failed` with orderId/reason.
297
307
 
298
- **Mode C hardening — OPEN.** (a) COW pre-broadcast gap-band reject; (b) order-existence check off slot→orderId map. Note: the GAP-P1 same-batch cancel that covered commit-time in-gap placement was reverted `e2898e51`; **P3 gate removed `e7231534`** — commit-time in-gap placement is currently covered by `LAST-FILL-GUARD` + adoption (no chain-evidence veto).
308
+ **Mode C hardening — PARTIAL (2026-10-11).** (b) **LANDED** pre-broadcast UPDATE-target existence check off the slot→orderId map: `runPreBroadcastGuards` re-reads every UPDATE action's `orderId` via `chainOrders.batchReadOrders` and refuses the whole batch (`UPDATE_TARGET_MISSING`) + requests a structural resync when a tracked target is gone on chain, instead of letting a `limit_order_update` abort the chunk mid-broadcast. Fails open on a non-Map/errored read (chain rejection remains the backstop), and re-verifies each candidate missing id with a single `readSingleOrder` before declaring it gone so a node lagging behind a just-created order does not false-refuse. **Residual risk (accepted, safe direction):** if that second read also lags/returns null, the batch is refused — a skipped cycle + structural resync, never a half-applied grid. Unexplained `UPDATE_TARGET_MISSING` churn on a slow node is this mechanism. (No dedicated counter on this path, consistent with the other uncounted pre-broadcast refusals; it shows up in error logs.) (a) **SHADOW ONLY** gap-band placement check: non-spread-correction CREATE/UPDATE destinations inside the plan's gap band are counted (`_metrics.gapBandPlacementShadowCount`) and warned, never blocked — enforcement is deliberately withheld because spread correction legitimately places INTO the band and a hard reject would re-open the reverted P1/e2898e51 regression class. Note: the GAP-P1 same-batch cancel that covered commit-time in-gap placement was reverted `e2898e51`; **P3 gate removed `e7231534`** — commit-time in-gap placement is currently covered by `LAST-FILL-GUARD` + adoption (no chain-evidence veto).
299
309
 
300
310
  #### 2.7 Relation to PRICE_FIRST draft
301
311
 
@@ -355,7 +365,20 @@ order of escalation forever — HOLD-010) and **not** from
355
365
  `_lastUnmatchedChainOrdersAt` — the latter refreshes on every observing sync
356
366
  and would make an age gate unfirable (HOLD-007).
357
367
 
358
- Still open: drift logging/alert >active window, re-stamp BUY above anchor metric, refused-commit and orphan-fill counters. Deferred-hold observability is no longer open — the `[HOLD]` summary now names side/price/size/reason/off-grid distance and slow-re-warns on an unchanged hold (`modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`).
368
+ Still open: none of the listed counters — all four landed 2026-10-11 (see below). Deferred-hold observability is no longer open — the `[HOLD]` summary now names side/price/size/reason/off-grid distance and slow-re-warns on an unchanged hold (`modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`).
369
+
370
+ P2 additions (2026-10-11, counter-only — none gated behavior):
371
+ - `refusedCommitCount` — incremented once in `recoverRefusedCommit` (the single funnel for all refused/uncertain commit paths), and only for genuine refusals: the poll-confirmed **success** path also routes through this funnel (adoption + fee deduction) and passes `refusedCommit: false`, so it is not counted.
372
+ - `orphanFillCreditedCount` — incremented in `applyReplaySafeOrphanFillAccounting` on an `applied` result (a real proceeds credit; not `duplicate`/`error`/`missing_key`).
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.
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.
375
+ - `gapBandPlacementShadowCount` — the Mode C(a) shadow above.
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.
359
382
 
360
383
  #### 3.4 Key code references (from source table)
361
384
 
@@ -436,7 +459,7 @@ Goal (Phase 2): I1–I6 property pass, full suite green, harness random, 48h per
436
459
  4. **LADDER #2/#3** identity + update-first hardening. — *done (`4838bcb0`).*
437
460
  5. **LADDER #5 / ORPHAN P0 recovery-by-ID** persistence (long freeze). — *done (`4838bcb0`, extended `a54863ca`; recovery-by-ID `1b27f6eb`).*
438
461
  6. **ORPHAN P0 ID-based adoption** + **P1 atomicity** (stale-plan race). — *P0 done (`1b27f6eb`, retry `d808c052`); atomicity partial.*
439
- 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.*
440
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.*
441
464
 
442
465
  ---
@@ -466,7 +489,7 @@ Pairs-checked base excludes cross-pair unless flagged; strict sat-level detectio
466
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`.
467
490
  - Boundary re-derivation persists: bot-A `00:28–07:00` must not repeat `[BOUNDARY-EVIDENCE]` for unchanged chain.
468
491
  - `NO_FEASIBLE_BOUNDARY` bot-C `04:27:48` resumes on next sync tick (bounded, not hours) with WARN.
469
- - 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.)*
470
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.)*
471
494
  - Aug 28 burst `17:09–17:16` (3 regs/6m, sells 1110–1176) → `0` orphans, `0` sells below asks.
472
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`.
@@ -482,7 +505,142 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
482
505
  - [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
483
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.
484
507
 
485
- *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.
486
644
 
487
645
  ---
488
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.13 (released).
5
+ **Version context:** v1.6.15 (released).
6
6
 
7
7
  ---
8
8
 
@@ -45,7 +45,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
45
45
  - **API Boundary**: Responsibility split between the AI decision layer and the DEXBot2 execution substrate ([AI_BOT_LIBRARY_API.md](../claw/docs/AI_BOT_LIBRARY_API.md))
46
46
  - **Tuning Reference**: Practical grid-tuning baselines ([DEXBOT2_TUNING_CHEAT_SHEET.md](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md))
47
47
  - **Position Management**: Short-position tracking, position health monitoring (3-zone CR model), and shared CR planning via `cr_planner.ts`
48
- - **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, and shared references
48
+ - **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, memu-memory, trend-detection, and shared references
49
49
 
50
50
  ## Operational & Security
51
51
 
@@ -58,7 +58,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
58
58
 
59
59
  ### 📊 [Grid Recalculation](GRID_RECALCULATION.md)
60
60
  *When and why the grid resets.*
61
- - **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and fund regeneration
61
+ - **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and available-funds resize
62
62
  - **Configuration**: Per-source thresholds, whitelist requirements, and defaults
63
63
  - **Trigger Execution**: How `profiles/recalculate.<botKey>.trigger` is consumed under the fill-processing lock
64
64
 
package/docs/WORKFLOW.md CHANGED
@@ -252,6 +252,7 @@ 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 |
@@ -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
@@ -620,12 +674,12 @@ mgr.outOfSpread = 3; // three slots beyond the target spread
620
674
  ### Calculation
621
675
 
622
676
  ```javascript
623
- // Calculate how many steps beyond target
624
- const currentSpreadSteps = calculateCurrentSpreadGap();
625
- const targetSpreadSteps = calculateTargetSpread();
626
- const outOfSpreadDistance = Math.max(0, currentSpreadSteps - targetSpreadSteps);
627
-
628
- mgr.outOfSpread = outOfSpreadDistance; // 0 = in spread, 3+ = out
677
+ // Requested extra slots, derived from the live spread vs the target tolerance:
678
+ // calculateCurrentSpread(mgr) -> shouldFlagOutOfSpread(...) returns the slot count.
679
+ mgr.outOfSpread = shouldFlagOutOfSpread(
680
+ calculateCurrentSpread(mgr), nominalSpread, toleranceSteps, buyCount, sellCount, incrementPercent
681
+ );
682
+ // 0 = in spread, 3+ = out
629
683
  ```
630
684
 
631
685
  ---
@@ -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. |
@@ -141,7 +141,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
141
141
  | **Crawl Candidate** | Furthest active order eligible for rotation |
142
142
  | **Shortage** | Empty slot in the active window that needs an order |
143
143
  | **Surplus** | Order outside the active window that can be rotated |
144
- | **Hard Surplus** | Order beyond the configured window + reserve (`activeOrders` + `reserveOrders`) count |
144
+ | **Hard Surplus** | Order beyond the configured window + reserve (`coreOrders` + `edgeOrders`) count |
145
145
  | **Reserve** | Edge-pinned live order outside the active window (buys at grid floor, sells at grid ceiling); never moves the boundary |
146
146
  | **Dust** | Partial order < 5% of ideal size |
147
147
  | **Dust Cancel** | Immediate on-chain cancel of dust partials on detection (no delay, no timer). Slot freed for a fresh counter-order. |
@@ -779,9 +779,18 @@ createOrderGrid(config)
779
779
  // Initialize with blockchain balances
780
780
  initializeGrid(manager)
781
781
 
782
- // Detect divergence and trigger updates
782
+ // Complete fund trigger: available-funds ratio + over-allocation + the
783
+ // on-chain committed-drift leg (closes the virtual-reservation blind spot)
783
784
  checkAndUpdateGridIfNeeded(manager)
784
785
 
786
+ // Drift-only async accessor (refreshes funds first); its core is folded into
787
+ // checkAndUpdateGridIfNeeded above
788
+ checkCommittedSizeDrift(manager)
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
+
785
794
  // Compare ideal vs. persisted grid
786
795
  compareGrids(calculatedGrid, persistedGrid, manager)
787
796
  ```
@@ -489,7 +489,7 @@ Per cycle, per processed bot, the adapter can produce:
489
489
 
490
490
  ### Files
491
491
 
492
- <details><summary>Config and state files (click to expand)</summary>
492
+ <details><summary><mark>Config and state files (click to expand)</mark></summary>
493
493
 
494
494
  | File | Purpose |
495
495
  |------|---------|
@@ -574,7 +574,7 @@ Typical fields:
574
574
 
575
575
  ### Module Map
576
576
 
577
- <details><summary>Directory layout (click to expand)</summary>
577
+ <details><summary><mark>Directory layout (click to expand)</mark></summary>
578
578
 
579
579
  ```text
580
580
  market_adapter/
@@ -798,7 +798,7 @@ snapshot.
798
798
 
799
799
  Main override knobs live in `profiles/market_adapter_settings.json`:
800
800
 
801
- <details><summary>Full settings table (click to expand)</summary>
801
+ <details><summary><mark>Full settings table (click to expand)</mark></summary>
802
802
 
803
803
  | Setting | Meaning |
804
804
  |---------|---------|
@@ -987,7 +987,7 @@ removed manually.
987
987
 
988
988
  Important fields in `market_adapter/state/market_adapter_state.json`:
989
989
 
990
- <details><summary>Field reference (click to expand)</summary>
990
+ <details><summary><mark>Field reference (click to expand)</mark></summary>
991
991
 
992
992
  | Field | Meaning |
993
993
  |-------|---------|
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.13",
3
+ "version": "1.6.15",
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",
package/scripts/README.md CHANGED
@@ -111,27 +111,9 @@ bash scripts/reset-settings.sh
111
111
 
112
112
  ## 📊 DIAGNOSTICS & VALIDATION
113
113
 
114
- ### Configuration Audit
115
- **File:** `validate_bots.ts`
116
- **Purpose:** Check `bots.json` for schema errors or missing required fields.
117
- ```bash
118
- # Validate the live bot configuration
119
- node dist/scripts/validate_bots.js
120
- ```
121
-
122
- ### Grid Divergence Audit
123
- **File:** `divergence-calc.ts`
124
- **Purpose:** Measure the "drift" between in-memory grid and disk state using RMS divergence metric.
125
- ```bash
126
- # Calculates RMS Error (hardcoded threshold: 1 promille ≈ 3.2% avg error)
127
- # RMS quadratically penalizes large errors - see docs/GRID_RECALCULATION.md
128
- node dist/scripts/divergence-calc.js
129
- ```
130
- **Reference:** RMS threshold interpretation in [Grid Recalculation docs](../docs/GRID_RECALCULATION.md)
131
-
132
- ### Grid Trading Analysis
133
- **File:** `analyze-orders.ts`
134
- **Purpose:** Analyze grid trading metrics and order distribution patterns.
114
+ ### Grid Order Analysis
115
+ **File:** `analyze-orders.ts` (CLI: `dexbot order`)
116
+ **Purpose:** Analyze grid order metrics and order distribution patterns.
135
117
  ```bash
136
118
  # Analyzes spread accuracy, geometric consistency, and fund distribution
137
119
  node dist/scripts/analyze-orders.js
@@ -155,24 +137,49 @@ node dist/scripts/analyze-credit.js <bot>
155
137
  ```
156
138
  Credit deals report per-pair and average CR, but only for pairs whitelisted in `bots.json` (`debtPolicy.lending`) and listed on the current credit offer; everything else is shown as ignored/unpriced and excluded from the average. A borrow-now preview per configured pair shows today's rate.
157
139
 
158
- ### Pool History Diagnostics
159
- **File:** `diagnose-pool-history.ts`
160
- **Purpose:** Inspect raw BitShares pool history API responses.
140
+ ### Asset Rich List / Top Holder
141
+ **File:** `rich_list.ts` (CLI: `dexbot rich`, npm: `npm run richlist`)
142
+ **Purpose:** Report the top holder(s) per asset using the chain's `asset_api`
143
+ (`get_asset_holders`). Holders come back balance-descending, so this is a live
144
+ rich list. Nodes must expose `asset_api` to anonymous logins; the script tries
145
+ `dex.iobanker.com` / `api.dex.trading` first and falls back through
146
+ `DEFAULT_NODES`.
161
147
  ```bash
162
- # Inspect pool history (default pool 1.19.133)
163
- node dist/scripts/diagnose-pool-history.js
148
+ # Rich list for one asset (default: node holder limit, usually 100)
149
+ dexbot rich <asset>
164
150
 
165
- # Custom pool, limit, and time range
166
- node dist/scripts/diagnose-pool-history.js --pool 1.19.x --limit 100 --hours 48 --maxPages 5
151
+ # Top 10 for several assets
152
+ dexbot rich <asset-a> <asset-b> <asset-c> --top 10
153
+
154
+ # Machine-readable
155
+ dexbot rich <asset-a> <asset-b> --json > rich.json
167
156
  ```
157
+ Balances reflect only liquid account balances, so they do not sum to total supply.
158
+ `--top` is clamped to the node's reported `api_limit_get_asset_holders` (shown
159
+ as a note when clamped). Legacy `bit*` MPA names were renamed on-chain without
160
+ the `bit` prefix; the script retries an unresolved `bit*` name stripped and notes
161
+ the rename. Note:
162
+ `get_asset_holders_count` is reported by the node as `distance(range) - 1`, so
163
+ the `holders=` figure can be off by one.
168
164
 
169
- ### Print Grid Sample
170
- **File:** `print_grid.ts`
171
- **Purpose:** Demonstrate the grid structure — shows consecutive price levels with percentage differences between adjacent slots.
165
+ ### Configuration Audit
166
+ **File:** `validate_bots.ts`
167
+ **Purpose:** Check `bots.json` for schema errors or missing required fields.
172
168
  ```bash
173
- node dist/scripts/print_grid.js
169
+ # Validate the live bot configuration
170
+ node dist/scripts/validate_bots.js
174
171
  ```
175
172
 
173
+ ### Grid Divergence Audit
174
+ **File:** `divergence-calc.ts`
175
+ **Purpose:** Measure the "drift" between in-memory grid and disk state using RMS divergence metric.
176
+ ```bash
177
+ # Calculates RMS Error (hardcoded threshold: 1 promille ≈ 3.2% avg error)
178
+ # RMS quadratically penalizes large errors - see docs/GRID_RECALCULATION.md
179
+ node dist/scripts/divergence-calc.js
180
+ ```
181
+ **Reference:** RMS threshold interpretation in [Grid Recalculation docs](../docs/GRID_RECALCULATION.md)
182
+
176
183
  ### Grid Calculation Runner
177
184
  **File:** `runner.ts`
178
185
  **Purpose:** Standalone order grid calculation debugger — loads a bot config, initializes the grid, and simulates sync cycles.
@@ -186,6 +193,25 @@ LIVE_BOT_NAME=my-bot CALC_CYCLES=10 CALC_DELAY_MS=1000 node dist/scripts/runner.
186
193
  Useful for verifying config produces the expected grid, testing price derivation, and debugging fund allocation.
187
194
  Requires a live BitShares connection (asset metadata lookups and price derivation are on-chain).
188
195
 
196
+ ### Print Grid Sample
197
+ **File:** `print_grid.ts`
198
+ **Purpose:** Demonstrate the grid structure — shows consecutive price levels with percentage differences between adjacent slots.
199
+ ```bash
200
+ node dist/scripts/print_grid.js
201
+ ```
202
+
203
+ ### Pool History Diagnostics
204
+ **File:** `diagnose-pool-history.ts`
205
+ **Purpose:** Inspect raw BitShares pool history API responses.
206
+ ```bash
207
+ # Inspect pool history (default pool 1.19.133)
208
+ node dist/scripts/diagnose-pool-history.js
209
+
210
+ # Custom pool, limit, and time range
211
+ node dist/scripts/diagnose-pool-history.js --pool 1.19.133 --limit 100 --hours 48 --maxPages 5
212
+ ```
213
+ `--pool` must be a concrete numeric liquidity-pool object ID (`1.19.N`). Placeholders such as `1.19.x` are rejected up front, because the node parses the instance part as a `uint64` and otherwise fails with `Parse Error: Couldn't parse uint64_t`.
214
+
189
215
  ### Native Release Gates
190
216
  **File:** `native_release_gates.ts` (+ `generate_mainnet_corpus_report.ts`)
191
217
  **Purpose:** Prove the native serialization layer matches the chain byte-for-byte before release.
@@ -374,6 +400,7 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
374
400
  | `npm run analysis:trade-pnl` | Trade PnL analysis from fill data |
375
401
  | `npm run analysis:grid-check` | Last-fill-guard check (`grid_correction_check.ts`) |
376
402
  | `npm run analysis:resolve-accounts` | Batch-resolve on-chain bot accounts (`resolve_bot_accounts.ts`) |
403
+ | `npm run richlist` | Per-asset rich list / top holder (`rich_list.ts`) |
377
404
  | `npm run ama:chart:lp-local` | Generate local LP comparison chart |
378
405
  | `npm run lp:chart` | Generate uPlot LP chart |
379
406
  | `npm run test:credit-renewal` | Test credit offer renewal for a specific bot |