dexbot 1.6.18 → 1.7.1

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 (146) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +117 -5
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_dynamic_weight.js +2 -1
  9. package/dist/analysis/analyze_kalman.js +3 -2
  10. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  11. package/dist/analysis/analyze_liquidity.js +336 -0
  12. package/dist/analysis/analyze_regime.js +3 -2
  13. package/dist/analysis/analyze_regime_windows.js +3 -2
  14. package/dist/analysis/analyze_volatility.js +3 -2
  15. package/dist/analysis/bot_key_utils.d.ts +44 -1
  16. package/dist/analysis/bot_key_utils.js +76 -7
  17. package/dist/analysis/fills_cache.js +2 -1
  18. package/dist/analysis/grid_correction_check.d.ts +1 -19
  19. package/dist/analysis/grid_correction_check.js +12 -30
  20. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  21. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  22. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.js +693 -0
  24. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +166 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.js +258 -0
  26. package/dist/analysis/liquidity/liquidity_view.d.ts +53 -0
  27. package/dist/analysis/liquidity/liquidity_view.js +66 -0
  28. package/dist/analysis/resolve_bot_accounts.js +7 -6
  29. package/dist/analysis/trade_profitability.js +4 -2
  30. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  31. package/dist/credential-daemon.js +13 -2
  32. package/dist/dexbot.js +77 -172
  33. package/dist/modules/account_bots.d.ts +11 -1
  34. package/dist/modules/account_orders.d.ts +12 -0
  35. package/dist/modules/account_orders.js +30 -0
  36. package/dist/modules/asset_lookup.d.ts +25 -0
  37. package/dist/modules/asset_lookup.js +75 -0
  38. package/dist/modules/bitshares-native/transport.js +24 -6
  39. package/dist/modules/bitshares_client.d.ts +24 -6
  40. package/dist/modules/bitshares_client.js +44 -7
  41. package/dist/modules/bot_settings.d.ts +2 -0
  42. package/dist/modules/chain_scan.d.ts +64 -0
  43. package/dist/modules/chain_scan.js +80 -0
  44. package/dist/modules/cli_colors.d.ts +5 -0
  45. package/dist/modules/cli_colors.js +7 -0
  46. package/dist/modules/cli_progress.d.ts +51 -0
  47. package/dist/modules/cli_progress.js +113 -0
  48. package/dist/modules/constants.d.ts +26 -3
  49. package/dist/modules/constants.js +63 -8
  50. package/dist/modules/dexbot_class.d.ts +1 -6
  51. package/dist/modules/dexbot_class.js +14 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
  53. package/dist/modules/dexbot_cow_runtime.js +634 -136
  54. package/dist/modules/dexbot_fill_runtime.js +132 -23
  55. package/dist/modules/dexbot_maintenance_runtime.js +242 -74
  56. package/dist/modules/dexbot_startup_runtime.js +32 -20
  57. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  58. package/dist/modules/dexbot_state_recovery.js +167 -5
  59. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  60. package/dist/modules/launcher/runtime_entry.js +36 -1
  61. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  62. package/dist/modules/liquidity_pool_ref.js +116 -0
  63. package/dist/modules/node_connect_policy.d.ts +8 -1
  64. package/dist/modules/node_connect_policy.js +18 -2
  65. package/dist/modules/node_flap_score.d.ts +87 -0
  66. package/dist/modules/node_flap_score.js +124 -0
  67. package/dist/modules/node_health_cache.d.ts +40 -3
  68. package/dist/modules/node_health_cache.js +66 -20
  69. package/dist/modules/node_manager.d.ts +101 -19
  70. package/dist/modules/node_manager.js +255 -65
  71. package/dist/modules/order/accounting.js +56 -7
  72. package/dist/modules/order/format.d.ts +24 -10
  73. package/dist/modules/order/format.js +30 -10
  74. package/dist/modules/order/grid.js +91 -13
  75. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  76. package/dist/modules/order/grid_reconcile.js +333 -189
  77. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  78. package/dist/modules/order/grid_reconcile_internal.js +298 -100
  79. package/dist/modules/order/index.d.ts +19 -1
  80. package/dist/modules/order/lifecycle.d.ts +353 -0
  81. package/dist/modules/order/lifecycle.js +1109 -0
  82. package/dist/modules/order/manager.d.ts +273 -5
  83. package/dist/modules/order/manager.js +654 -48
  84. package/dist/modules/order/placement_lock.d.ts +102 -0
  85. package/dist/modules/order/placement_lock.js +222 -0
  86. package/dist/modules/order/strategy.js +13 -1
  87. package/dist/modules/order/sync_engine.d.ts +33 -1
  88. package/dist/modules/order/sync_engine.js +241 -73
  89. package/dist/modules/order/utils/math.d.ts +39 -1
  90. package/dist/modules/order/utils/math.js +83 -1
  91. package/dist/modules/order/utils/order.d.ts +181 -5
  92. package/dist/modules/order/utils/order.js +455 -9
  93. package/dist/modules/order/utils/system.d.ts +81 -1
  94. package/dist/modules/order/utils/system.js +331 -44
  95. package/dist/modules/order/utils/validate.d.ts +7 -1
  96. package/dist/modules/order/utils/validate.js +80 -3
  97. package/dist/modules/outcome.d.ts +54 -0
  98. package/dist/modules/outcome.js +51 -0
  99. package/dist/modules/settings_merge.d.ts +4 -0
  100. package/dist/modules/settings_merge.js +9 -0
  101. package/dist/modules/timing_policy.d.ts +82 -0
  102. package/dist/modules/timing_policy.js +244 -0
  103. package/dist/modules/types.d.ts +137 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  105. package/dist/modules/utils/asset_symbols.js +21 -2
  106. package/dist/scripts/analysis_runner.d.ts +10 -0
  107. package/dist/scripts/analysis_runner.js +33 -0
  108. package/dist/scripts/analyze-credit.js +54 -17
  109. package/dist/scripts/analyze-orders.d.ts +4 -2
  110. package/dist/scripts/analyze-orders.js +115 -35
  111. package/dist/scripts/asset.d.ts +26 -0
  112. package/dist/scripts/asset.js +165 -0
  113. package/dist/scripts/bts_distribution.d.ts +1 -0
  114. package/dist/scripts/bts_distribution.js +194 -142
  115. package/dist/scripts/chart_command.d.ts +1 -1
  116. package/dist/scripts/chart_command.js +60 -86
  117. package/dist/scripts/chart_targets.d.ts +18 -0
  118. package/dist/scripts/chart_targets.js +48 -0
  119. package/dist/scripts/dw.js +1 -1
  120. package/dist/scripts/liquid.d.ts +24 -0
  121. package/dist/scripts/liquid.js +134 -0
  122. package/dist/scripts/rich_list.js +12 -16
  123. package/dist/scripts/test-credit-renewal.js +12 -5
  124. package/dist/scripts/token_distribution.d.ts +2 -0
  125. package/dist/scripts/token_distribution.js +132 -108
  126. package/dist/scripts/tv.js +1 -1
  127. package/dist/scripts/verify-browser-bundle.js +18 -0
  128. package/docs/COW_INVARIANTS.md +69 -10
  129. package/docs/DEXBOT_COMPARISON.md +6 -6
  130. package/docs/EVOLUTION.md +10 -8
  131. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  132. package/docs/GRID_PRICE_INVARIANT.md +5 -2
  133. package/docs/GRID_RECONCILE.md +36 -11
  134. package/docs/LOGGING.md +50 -4
  135. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +177 -27
  136. package/docs/README.md +23 -2
  137. package/docs/WORKFLOW.md +12 -4
  138. package/docs/architecture.md +42 -5
  139. package/docs/developer_guide.md +25 -8
  140. package/modules/README.md +8 -1
  141. package/package.json +3 -1
  142. package/scripts/README.md +39 -7
  143. package/scripts/pdev.sh +14 -1
  144. package/scripts/pmain.sh +23 -8
  145. package/scripts/ptest.sh +7 -0
  146. package/tests/README.md +30 -1
@@ -4,23 +4,27 @@
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.14; `docs/GRID_PRICE_INVARIANT.md`;
8
- > `docs/COW_INVARIANTS.md`. Generic terms only — no live markets, accounts, or order ids.
7
+ > **Sources:** `CHANGELOG.md` v1.0.0 → v1.7.0 (plus the unreleased post-1.7.0 arc);
8
+ > `docs/GRID_PRICE_INVARIANT.md`; `docs/COW_INVARIANTS.md`; `docs/ORDER_LIFECYCLE.md`.
9
+ > Generic terms only — no live markets, accounts, or order ids.
9
10
  >
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
+ > **Scope / snapshot:** v1.0.0 → v1.7.0 (`5644aa3a`, 2026-11-02), extended through the
12
+ > unreleased post-1.7.0 work at `84b935d9` (2026-11-04). §9 is the v1.6.4 → v1.6.17
13
+ > addendum; §9.10 closes the v1.6.18 review pass and §9.11 carries v1.6.18 → unreleased.
12
14
  >
13
15
  > **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
14
16
  > 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`).
17
+ > later addendum (v1.6.4 → v1.6.17, with §9.10/§9.11 extending it) that adds to, and does not
18
+ > renumber, that range. Part I uses `R1`–`R5` so the two never collide. The closing appendix
19
+ > is unnumbered (`A`).
17
20
  >
18
21
  > **How to read:** start with **Part I** for the explanation; drop into **Part II** when you need
19
22
  > the per-incident evidence, commit hashes, and verification targets.
20
23
  >
21
24
  > **See also:** [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md) ·
22
25
  > [COW_INVARIANTS.md](COW_INVARIANTS.md) · [GRID_RECONCILE.md](GRID_RECONCILE.md) ·
23
- > [EVOLUTION.md](EVOLUTION.md) · [CHANGELOG.md](../CHANGELOG.md).
26
+ > [ORDER_LIFECYCLE.md](ORDER_LIFECYCLE.md) · [EVOLUTION.md](EVOLUTION.md) ·
27
+ > [CHANGELOG.md](../CHANGELOG.md).
24
28
 
25
29
  ---
26
30
 
@@ -44,7 +48,8 @@
44
48
  - 7. Consolidated verification — grid-correction check as regression gate
45
49
  - 8. Provenance & supersession record
46
50
  - 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17) — addendum
47
- - 9.10 Review pass over v1.6.12 → v1.6.17 (findings P1–P5)
51
+ - 9.10 Review pass over v1.6.12 → v1.6.17 (findings P1–P5), released in v1.6.18
52
+ - 9.11 v1.6.18 → unreleased: fill identity, absence and the geometry budget
48
53
  - A. Grid-Price Invariant — former failure trace (appendix)
49
54
 
50
55
  ---
@@ -77,6 +82,9 @@ local state.
77
82
  | **Silent hangs** | Retries that depended on a future event that never came | Level-triggered scheduling with time-based watchdogs |
78
83
  | **Stale queues** | Queued price corrections replayed onto a resynced grid, reverting good placements | Pre-broadcast validation against the live slot |
79
84
  | **Shelf / edge orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
85
+ | **Stale window after a fill** | A fill is queued but not yet absorbed; the master still counts the filled slot ACTIVE, so a window top-up re-creates the expensive end of the rail and re-buys into a stale pivot | `hasUnsettledFills` defers the targeted reconcile and the window top-up (1:1 repairs still run) + attribution of the real execution price (§9.11.1) |
86
+ | **Fill identity by chain id** | `virtualizeOrder` nulls `orderId`, so a real fill matched no ACTIVE slot and was dropped *after* its accounting was booked; pivot and owed crawl stayed on a stale, higher price | `attributeUnmatchedFillToGrid` falls back to the genesis level of the execution price, refuses prices outside the frozen rail, and owes a crawl only for a hole the grid owns (§9.11.1) |
87
+ | **Chain-existence bookkeeping** | Seven structures with seven clocks; four read sites consulted four subsets and could give four answers for one order | `modules/order/lifecycle.ts`: one record per slot, `unknown` is a real phase, every absence decision asks the same time-bounded `isInFlight()` (§9.11.3) |
80
88
 
81
89
  Families **not** detailed in Part II: silent hangs and stale correction queues are covered in
82
90
  `CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/edge orders in issue #27 and the v1.6.x
@@ -100,13 +108,16 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
100
108
  the runtime guard, the spread-correction planner, the rail clamp and the offline checker.
101
109
  Every copy drifted on its own schedule: the planner used the crossing floor, the checker
102
110
  kept the old band, the rail clamp kept the old slot ids (§9.7, §9.10). The fix that
103
- sticks is one exported predicate and callers that re-implement nothing.
111
+ sticks is one exported predicate and callers that re-implement nothing. The same shape
112
+ produced the existence bugs: seven local structures were seven policies for "does this
113
+ order exist?", and the first disagreement was the incident (§9.11.3).
104
114
 
105
115
  ### R4. What actually fixed it
106
116
 
107
117
  - **Genesis-frozen price-slot determinism** (v1.4.25+): `slot-N` → exact ladder price
108
- becomes the single source of truth, replacing tolerance-based price matching. Killed a
109
- whole family of orphan/duplicate bugs.
118
+ becomes the single source of truth. Grid-vs-grid identity is now exact; a CHAIN price is
119
+ compared by which ladder level it maps to (`pricesOnSameLevel`, bounded by asset precision),
120
+ never by a tuned band. Killed a whole family of orphan/duplicate bugs.
110
121
  - **Single ownership:** one writer for the boundary, one owner for the adapter/market
111
122
  config, one authoritative set of counters.
112
123
  - **Global last-fill guard + final pre-broadcast gate:** one pivot rule, enforced at the
@@ -124,6 +135,16 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
124
135
  each path carrying its own idea of "stranded".
125
136
  - **Live identity over local keys (§9.10, `531edeb4`):** every rail/geometry decision maps the
126
137
  order's LIVE chain price onto the ladder; a slot id is a hint, never the fact.
138
+ - **An id is not an identity (§9.11.1, `8705381b`):** a fill whose chain id was nulled by
139
+ virtualisation is resolved to the genesis level of its execution price, so attribution
140
+ cannot go blind exactly when the order is most interesting.
141
+ - **An unabsorbed fill blocks the geometry (§9.11.1, `a93f7eef`):** while fills are queued,
142
+ draining, in flight or owed a crawl, the targeted reconcile and the window top-up defer.
143
+ - **Repairs must reduce the violation (§9.11.3, `c493a604`):** a boundary move is accepted
144
+ only when it strands *strictly fewer* placed orders than the committed value, measured by
145
+ the validator's own count — never a second predicate.
146
+ - **One existence record (§9.11.3, `826d84a3`/`84b935d9`):** seven per-site structures
147
+ collapsed into `lifecycle.ts`; `unknown` is a phase, not an absence.
127
148
  - **Observability instead of a veto (§9.10/P4):** where a hard guard would re-create a
128
149
  deadlock (a counter order crossing the floor by construction), log it once and let the
129
150
  chain price it as a taker fill.
@@ -157,6 +178,15 @@ The winning strategy was **removing writers and sources of truth**, not adding h
157
178
  repair that can cite one stray order is not a repair.
158
179
  11. **When a veto would deadlock, ship the observation.** A taker-fee risk earns a log line,
159
180
  not a rule that re-creates the deadlock the previous fix removed (§9.10/P4).
181
+ 12. **An id is not an identity.** Virtualising an order clears its chain id, so anything that
182
+ matches fills, occupancy or rails by id alone goes blind exactly when the order is most
183
+ interesting. Match the ladder level of the live price; keep the id as a hint (§9.11.1).
184
+ 13. **A fill the geometry has not absorbed must block the geometry.** Deferring a repair for
185
+ one cycle is cheaper than a top-up built from a stale master, because a repair path that
186
+ runs on un-absorbed state is a way to re-create that state (§9.11.1).
187
+ 14. **Absence needs one definition, one clock and one owner.** Seven local counters are seven
188
+ policies; if two sites can disagree about whether an order exists, the disagreement is
189
+ the bug, not either answer (§9.11.3).
160
190
 
161
191
  ---
162
192
 
@@ -183,7 +213,7 @@ plans, `LANDED`/`REVERTED`/`SUPERSEDED` statuses, commit hashes, and verificatio
183
213
 
184
214
  **Grid terms:** `boundary` = discrete sell/buy split index; `gap band` = `SPREAD/virtual` slots around boundary; `sellStartIdx = splitIdx - floor(gap/2) - 1`; center-priced ladder `createOrderGrid` = `startPrice × step^(k+½)` (`modules/order/grid.ts`); `MarketAnchor` = fill-derived `lastFillPrice/maxFilledSellPrice/minFilledBuyPrice/lastFillSide`; tolerance helpers `calculatePriceTolerance = (1/satsA+1/satsB)×price` (`modules/order/utils/math.ts`), `GRID_LIMITS.PRICE_TOLERANCE_MAX_PERCENT 0.01` (`modules/constants.ts`).
185
215
 
186
- **Validation tool:** `analysis/grid_correction_check.ts` (test-only, mirrors `analysis/trade_profitability.ts` Kibana path `https://kibana.bitshares.dev`, `bitshares-*`, `operation_type:4` `fill_order` only; `buildFillQuery`, paginated `search_after`, `_source` `block_data` fields). **Invariants:** `sell→sell` with no `buy` between must rise (`curr > prev`, **equal is a violation** — a re-place at the just-filled level), `buy→buy` must fall (`curr < prev`); `per-order` aggregated default (weighted avg collapses multi-fill `1.7.x`), `--per-fill` raw. Resolution via `bot_key_utils.ts` `loadBotMeta/computeBotKey`. Reports violations, `%`, daily histogram, time/range, table with price/Δ%/times/orderIds; `--json/--csv` export; exit `0` pass / `2` fail. Strict sat-level is ground truth — the verdict is **direction only** (equal price is a violation); `--increment` is **informational only** (the band the removed `--tolerance` flag used to express is gone, §9.10/P5). Used as regression gate below; pre-fix per-account baselines are intentionally omitted here — §7 states the targets (`0` violations).
216
+ **Validation tool:** `analysis/grid_correction_check.ts` (offline Node tool — it imports the runtime's own `isLastFillGuardBlocked`, so the verdict cannot drift; its Kibana query mirrors `analysis/trade_profitability.ts` (`https://kibana.bitshares.dev`, `bitshares-*`, `operation_type:4` `fill_order` only; `buildFillQuery`, paginated `search_after`, `_source` `block_data` fields). **Invariants:** `sell→sell` with no `buy` between must rise (`curr > prev`, **equal is a violation** — a re-place at the just-filled level), `buy→buy` must fall (`curr < prev`); `per-order` aggregated default (weighted avg collapses multi-fill `1.7.x`), `--per-fill` raw. Resolution via `bot_key_utils.ts` `loadBotMeta/computeBotKey`. Reports violations, `%`, daily histogram, time/range, table with price/Δ%/times/orderIds; `--json/--csv` export; exit `0` pass / `2` fail. Strict sat-level is ground truth — the verdict is **direction only** (equal price is a violation); `--increment` is **informational only** (the band the removed `--tolerance` flag used to express is gone, §9.10/P5). Used as regression gate below; pre-fix per-account baselines are intentionally omitted here — §7 states the targets (`0` violations).
187
217
 
188
218
  ---
189
219
 
@@ -538,15 +568,17 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
538
568
  - [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
539
569
  - [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.
540
570
 
541
- *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), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`, and then through the post-1.6.17 review pass (`§9.10`: `f4d6da8c`, `a2bf6ba5`, `56481b16`, `3d16f9e4`). 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`.*
571
+ *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), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`, through the v1.6.18 review pass (`§9.10`: `f4d6da8c`, `a2bf6ba5`, `56481b16`, `3d16f9e4`), and through v1.7.0 + the unreleased post-1.7.0 arc (`§9.11`, HEAD `84b935d9`). 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`.*
542
572
 
543
573
  ---
544
574
 
545
575
  ### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17)
546
576
 
547
- > **Source:** `CHANGELOG.md` v1.6.4 → v1.6.17 · **Snapshot:** `78ccbb8e` (v1.6.17 tag).
577
+ > **Source:** `CHANGELOG.md` v1.6.4 → v1.6.17 · **Snapshot:** `78ccbb8e` (v1.6.17 tag);
578
+ > §9.10 and §9.11 extend past it — §9.10 released in v1.6.18, §9.11 unreleased to HEAD
579
+ > `84b935d9`.
548
580
  > Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
549
- > `§9.10` and the last two ledger rows cover the **post-1.6.17** work, which is unreleased.
581
+ > The ledger labels each row with its release; `unreleased` means "in no tag yet".
550
582
 
551
583
  Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
552
584
  proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
@@ -636,7 +668,7 @@ fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and
636
668
  truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
637
669
  required is no longer reachable at runtime.
638
670
 
639
- #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.6.17 + unreleased)
671
+ #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.0 + unreleased)
640
672
 
641
673
  | Commit | Release | Change |
642
674
  |---|---|---|
@@ -672,11 +704,27 @@ required is no longer reachable at runtime.
672
704
  | `62312e60` | 1.6.17 | Plan only placeable tightening slots; name the stall causes |
673
705
  | `276cd504` | 1.6.17 | Fund from chain truth and re-anchor the boundary from the fill (§9.9) |
674
706
  | `2e618197` | 1.6.17 | Consume only the owed fill crawls a derivation applied (§9.8) |
675
- | `d99b8685` | post-1.6.17 | Harden partial-fill re-anchor and recovery (residual allow-list, tolerant load) |
676
- | `531edeb4` | post-1.6.17 | Keep the boundary on the placed rails; use live fill prices for geometry |
677
- | `f4d6da8c` | post-1.6.17 | Edge-pinned fills never arm the pivot or the anchor (§9.10/P1) |
678
- | `a2bf6ba5` | post-1.6.17 | Guard arity, explicit pivot re-arm, stray-aware rail clamp, crossing observation (§9.10/P2-P4) |
679
- | `56481b16` | post-1.6.17 | Offline checker judges by the same direction-only predicate (§9.10/P5) |
707
+ | `d99b8685` | 1.6.18 | Harden partial-fill re-anchor and recovery (residual allow-list, tolerant load) |
708
+ | `531edeb4` | 1.6.18 | Keep the boundary on the placed rails; use live fill prices for geometry |
709
+ | `f4d6da8c` | 1.6.18 | Edge-pinned fills never arm the pivot or the anchor (§9.10/P1) |
710
+ | `a2bf6ba5` | 1.6.18 | Guard arity, explicit pivot re-arm, stray-aware rail clamp, crossing observation (§9.10/P2-P4) |
711
+ | `56481b16` | 1.6.18 | Offline checker judges by the same direction-only predicate (§9.10/P5) |
712
+ | `ddc4b4a3` | 1.6.18 | Count last-fill-excluded candidates per slot, not per pool visit |
713
+ | `a93f7eef` | 1.7.0 | Stale-grid re-buys: unsettled-fill gate, attribution, same-level refusal (§9.11.1) |
714
+ | `8705381b` | 1.7.0 | Orphan-fill attribution by price; dark-level revive (§9.11.1) |
715
+ | `8aff50bb` | 1.7.0 | Anchor-aware residual allow-list, pivot clock provenance, read-time TTL (§9.11.2) |
716
+ | `c493a604` | unreleased | Stranded-boundary repair without re-arming on replays (§9.11.3) |
717
+ | `ed52f9ef` | unreleased | Exclusive placement region; no create-only re-plan after a rebuild (§9.11.3) |
718
+ | `970fedfd` | unreleased | Remaining placement races; fill-accounting double-apply |
719
+ | `ad081e3d` | unreleased | Placement lifecycle + fill-marker idempotency |
720
+ | `7a3571a4` | unreleased | Follow-up gaps: one teardown, one lease check, one pending-broadcast policy |
721
+ | `94223d19` | unreleased | Re-verify the placement lease before a region holder broadcasts |
722
+ | `8bab9881` | unreleased | Unknown gap geometry is not gap 0 |
723
+ | `4d5e3d81` | unreleased | Forced retreats evacuate, then re-plan the committed band |
724
+ | `7618f299` | unreleased | Cancel teeth may not destroy the rotation that evacuates |
725
+ | `826d84a3` | unreleased | Chain existence unified behind the lifecycle registry (§9.11.3) |
726
+ | `7252d7d3` | unreleased | Broadcast uncertainty as a typed three-valued outcome (§9.11.3) |
727
+ | `84b935d9` | unreleased | One writer per life-cycle clock, one guard per absence decision (§9.11.3) |
680
728
 
681
729
  #### 9.6 Invariants added
682
730
 
@@ -695,10 +743,21 @@ required is no longer reachable at runtime.
695
743
  - **A rail clamp only cites its own evidence:** the batch's op destinations and the master
696
744
  orders on their own side of the planned boundary; strays are ignored and named (§9.10/P3).
697
745
  - **The pivot has a lifetime:** re-armed explicitly after a rebuild from the last real fill,
698
- bounded by the same 24h TTL, and a re-center is requested at most once per pivot because a
746
+ bounded by the same 24h TTL (enforced at restore and at read time, so a stale row can neither
747
+ arm the guard nor be re-armed), and a re-center is requested at most once per pivot because a
699
748
  re-center cannot move it (§9.10/P2).
700
-
701
- #### 9.7 The guard was a band, not an economic rule (`c86b4b0e`)
749
+ - **An unabsorbed fill blocks the geometry:** while fills are queued, draining, in flight or
750
+ owed a crawl, the targeted reconcile and the window top-up defer (1:1 repairs still run),
751
+ and a fill is attributed by the ladder level of its execution price, not by a chain id that
752
+ virtualisation has already nulled (§9.11.1).
753
+ - **A repair must reduce the violation:** a boundary move is accepted only when it strands
754
+ strictly fewer placed orders than the committed value, counted by `validatePersistedBoundary`
755
+ itself; an equal count is refused (§9.11.3).
756
+ - **Existence is a record, not a lookup:** one per-slot lifecycle record owns the phase, the
757
+ evidence rank and every clock; `unknown` is a phase that never reads as "gone", and every
758
+ absence decision asks the same time-bounded guard (§9.11.3).
759
+
760
+ #### 9.7 The guard was a band, not an economic rule (`8e5e1a3c`)
702
761
 
703
762
  **Observed (2026-10-24/25, a live market-pair bot).** A dump swept the grid and the
704
763
  market then held. Spread correction planned, the broadcast guard dropped the creates,
@@ -819,7 +878,7 @@ must stay fund-driven from the side pool: a SELL fill returns quote while the
819
878
  same-side repair needs base, so no fill can ever fund its own side, and pairing
820
879
  would hide that asymmetry instead of resolving it.
821
880
 
822
- #### 9.10 Review pass over v1.6.12 → v1.6.17 (unreleased)
881
+ #### 9.10 Review pass over v1.6.12 → v1.6.17 (released in v1.6.18)
823
882
 
824
883
  A code review of the whole 1.6.12→1.6.17 order-engine arc (90 commits) against
825
884
  the three stated goals — buy-low/sell-high counter orders, never trading through
@@ -843,8 +902,99 @@ extremum extracted as `resolveFillAnchorIndex` (pure, batch-only).
843
902
 
844
903
  **Commits:** `f4d6da8c` (P1) · `a2bf6ba5` (P2–P4 plus the arity and the anchor
845
904
  extraction) · `56481b16` (P5) · `3d16f9e4` (this document, the doc-level invariants
846
- and the log rows it cites). **Unreleased:** no version bump and no `CHANGELOG.md`
847
- entry — both belong to the release step, not to this pass.
905
+ and the log rows it cites). **Released in v1.6.18:** the review pass itself carried no
906
+ version bump, but every commit above is an ancestor of the `v1.6.18` tag (2026-11-01).
907
+
908
+ #### 9.11 v1.6.18 → unreleased: fill identity, absence and the geometry budget
909
+
910
+ The post-1.6.17 work stopped asking "which guard is missing?" and started asking
911
+ "which *identity* is the code using?". Three answers landed: a fill is identified
912
+ by its ladder level, existence by one lifecycle record, and a repair by the
913
+ amount of violation it removes.
914
+
915
+ ##### 9.11.1 A fill the grid could not name (v1.7.0, `a93f7eef`/`8705381b`)
916
+
917
+ **Observed (2026-11-02, a live market-pair bot).** A multi-minute stale broadcast
918
+ region deferred the fill queue; the post-fill targeted reconcile then derived its
919
+ window from a master that still held the filled slots as ACTIVE and re-created
920
+ same-side orders at the top of the un-crawled rail. They filled within seconds:
921
+ 9 buy-lower violations, 23.5% of the window's BTS.
922
+
923
+ **The root cause sat upstream of the reconcile.** A fill whose order id no longer
924
+ sat on an ACTIVE/PARTIAL slot was dropped ("order not found in active grid")
925
+ *after* its accounting was booked, so neither the pivot nor the owed crawl
926
+ learned the real execution price and every downstream gate compared against a
927
+ stale, higher price. `virtualizeOrder` nulls `orderId`, so the very fills the
928
+ attribution was written for could never match by id.
929
+
930
+ **Four gates, one direction:**
931
+
932
+ - `hasUnsettledFills` defers the targeted reconcile and the window top-up while
933
+ fills are queued, draining, in flight or owed a crawl. 1:1 repairs
934
+ (cancelled-slot replacement, vacated-rail refill) still run, so a rail is never
935
+ left un-repaired.
936
+ - `attributeUnmatchedFillToGrid` resolves the slot by chain id when a virtualised
937
+ slot still owns it, else by the **genesis level of the execution price**,
938
+ records pivot + owed crawl, and refuses a price outside the frozen rail so a
939
+ shelf/manual order can never arm the geometry.
940
+ - `isLastFillPlacementBlocked` (direction **plus** same grid level) gates every
941
+ reconcile placement, and `_pickVirtualSlotsToActivate` uses the same predicate,
942
+ so the pick budget rolls to the next level instead of being spent on a level
943
+ the create would refuse.
944
+ - A slot virtualised while its order stayed live on chain is revived in place
945
+ (`reviveVirtualSlotFromChain`, level-gated, master-only), a genuinely stale id
946
+ on a non-placed slot is cleared without booking a fill, and CREATE occupancy is
947
+ keyed on the id alone (any state) rather than on `isOrderOnChain()`.
948
+
949
+ ##### 9.11.2 The pivot is a row, not a price (v1.6.18/v1.7.0, `d99b8685`/`8aff50bb`)
950
+
951
+ Three defects of the same shape:
952
+
953
+ - The in-band residual allow-list that lets a fill's own PARTIAL survive a re-anchor was
954
+ keyed on the last-processed pivot instead of the batch **extremum**, so for every chunked
955
+ sweep whose furthest fill was not the pivot the re-anchor was refused as
956
+ `unsafe: placed_order_in_band` — the exact shape the extremum resolution exists for.
957
+ - A market-row price could inherit a book-seed timestamp and then re-stamp it, refreshing the
958
+ 24h lifetime on every rebuild until the row never expired.
959
+ - The TTL existed only at restore, so a long-lived process kept an expired pivot vetoing one
960
+ side forever while the geometry watchdog claimed a fill or the TTL would restore it.
961
+
962
+ Price, side and clock now travel as one row, and the TTL is enforced where the reference
963
+ is **read**; an unknown age never expires.
964
+
965
+ ##### 9.11.3 Absence gets one record; repairs must reduce the violation (unreleased)
966
+
967
+ Chain existence used to be answered by seven structures with seven clocks
968
+ (`_pendingBroadcasts`, `createUncertain`, `_committedOrderIds`,
969
+ `_orderIdAssignedAt`, `_placedAt`, `_chainSizeAppliedFills`,
970
+ `_lastUnmatchedChainOrders`). Four read sites consulted four subsets and could
971
+ return four different answers for the same order, so each fix closed one site and
972
+ the bug reappeared at the next.
973
+
974
+ `modules/order/lifecycle.ts` (`826d84a3`, `7252d7d3`, `84b935d9`) now owns one
975
+ record per slot: a six-phase vocabulary in which `unknown` is a real state (a
976
+ lost receipt is *not* an absence), a monotonic evidence rank, and every clock
977
+ recorded once. The legacy maps survive as live views, so no call site had to be
978
+ rewritten to get one truth. Three rules fall out of it: one absence guard
979
+ (`isInFlight()`, time-bounded), one teardown authority for a hung region
980
+ (`_clearStalePlacementRegion`, `7a3571a4`), and one pending-broadcast liveness
981
+ policy (`getLivePendingBroadcasts`).
982
+
983
+ Geometry gained the matching rule. A boundary writer may move the boundary only
984
+ when the move strands **strictly fewer** placed orders than the committed value
985
+ (`boundaryMoveReducesStrands`, counted by `validatePersistedBoundary` itself); an
986
+ equal count stays refused, and a replayed fill no longer re-arms the pivot
987
+ (`c493a604`). The same arc put every chain-mutating path inside one exclusive
988
+ placement region (`modules/order/placement_lock.ts`, `ed52f9ef`/`970fedfd`) after
989
+ a trigger-file rebuild and a fill-driven rebalance interleaved into 25
990
+ duplicate-price orders; made a forced gap-evacuation retreat evacuate before
991
+ re-planning instead of letting its cancel teeth destroy the rotation (`7618f299`,
992
+ `4d5e3d81`); and stopped an absent gap band from reading as a valid `0`
993
+ (`8bab9881`).
994
+
995
+ **Why it belongs in this document:** R3.5's "one rule, several implementations"
996
+ is not a style complaint. Every family above is that pattern applied to a
997
+ different noun — price, fill, existence.
848
998
 
849
999
  ---
850
1000
 
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.18 (released).
5
+ **Version context:** v1.7.1 (released).
6
6
 
7
7
  ---
8
8
 
@@ -131,9 +131,22 @@ This directory contains the comprehensive technical documentation for the DEXBot
131
131
  ### 🔒 [COW Invariants](COW_INVARIANTS.md)
132
132
  *Stable theory contract for COW pipeline.*
133
133
  - **Non-negotiable invariants**: Master immutability, commit atomicity, projection rules, accounting separation
134
- - **Subsystem Scope**: 13 `INV-*` prefix groups mapping each invariant to its runtime subsystem
134
+ - **Subsystem Scope**: 15 `INV-*` prefix groups mapping each invariant to its runtime subsystem
135
135
  - **Change Policy**: Required steps for an intentional invariant change — same-PR doc update, rationale, and regression tests
136
136
 
137
+ ### 🧭 [Order Lifecycle Registry](ORDER_LIFECYCLE.md)
138
+ *How the engine answers one question from one record: does this order exist on chain, and how sure are we?*
139
+ - **The problem**: seven structures with seven clocks, four read sites consulting four different subsets of them
140
+ - **The model**: one record per slot, six phases, `unknown` as a real state that never reads as "gone"
141
+ - **The wiring**: legacy maps are live views onto the record; every mutation funnels through `_applyOrderUpdate`
142
+ - **Invariants**: `INV-LIFE-001…007` in [COW_INVARIANTS.md](COW_INVARIANTS.md#order-lifecycle-order_lifecyclemd)
143
+
144
+ ### ⏱ [Timing Window Inventory](TIMING_INVENTORY.md)
145
+ *Every timing knob classified, with the self-healing ones marked as removal targets.*
146
+ - **The audit**: `external` / `bound` / `policy` / `self-healing`, each with a rationale
147
+ - **The gate**: `tests/test_timing_policy.ts` fails on an unclassified window, so the inventory can only shrink by decision
148
+ - **Removal targets**: the six windows that compensate for our own lost state, and the evidence that replaces each
149
+
137
150
  ### 📐 [Grid-Price Invariant](GRID_PRICE_INVARIANT.md)
138
151
  *Why a slot's emitted price must equal its genesis level — and how that failed.*
139
152
  - **The invariant**: `order.price === priceForSlot(idx, genesis)`, and why range guards cannot substitute for it
@@ -169,6 +182,14 @@ This directory contains the comprehensive technical documentation for the DEXBot
169
182
  - **Practical How-Tos**: Adding features step by step, common pitfalls to avoid, and useful debugging commands.
170
183
  - **Glossary**: Definitions of project-specific terminology (e.g., "VIRTUAL order state", "Rotation", "Pipeline Safety", "WorkingGrid", "Atomic Commit", "Dynamic Weight", "Regime Detection").
171
184
 
185
+ ### 🌉 [Liquidity Mirror Design](LIQUIDITY_MIRROR_DESIGN.md)
186
+ *Design paper for a cross-venue liquidity mirror running alongside DEXBot2.*
187
+ - **Roles**: Chain host (TS, DEXBot2) owns identity, pool reads, and hedging; a separate venue daemon owns CEX credentials, the order book, and the rate-limit budget
188
+ - **Contract**: Intent-level, HMAC-authenticated NDJSON over a unix socket — desired book in, fills and positions out; no message whose retry can duplicate an order
189
+ - **Change surface**: Four new modules under `modules/venues/`, a `cex_mirror/` tree, and five mechanical edits; the grid, sync engine, accounting, and strategy engine are untouched
190
+ - **Guardrails**: Spread floor from pool fee plus impact, hedge batching trade-off, deadman cancellation, divergence breaker, and a split inventory-cap model
191
+ - **Rollout**: Milestones M0–M5 with acceptance gates, from protocol conformance vectors to capped live hedging
192
+
172
193
  ### 🔄 [Workflow](WORKFLOW.md)
173
194
  *How we build and release.*
174
195
  - **Branching Strategy**: Explanation of the `test` → `dev` → `main` lifecycle.
package/docs/WORKFLOW.md CHANGED
@@ -250,12 +250,14 @@ the canonical name is preferred in scripts and docs.
250
250
  | `dexbot update` | — | Update DEXBot2 from the repository and restart active bots |
251
251
  | `dexbot export <bot>` | — | Export bot trades/settings to CSV/JSON for local analysis/ |
252
252
  | `dexbot order` | `orders` | Analyze persisted order grids (spread, increment, funds); `--export` for HTML |
253
- | `dexbot order [<bot>]` | — | Analyze only the specified bot's order grid |
254
- | `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot>]`) |
253
+ | `dexbot order [<bot|account>]` | — | Analyze only the specified bot's order grid — or every grid on that account (`<bot|account>`) |
254
+ | `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot|account>]` — a bot name/key, or the account the bot trades from, name or `1.2.x` id) |
255
255
  | `dexbot rich <asset...>` | — | Top holder(s) per asset via the chain asset-holders API (`--top N`, `--json`/`--csv`) |
256
- | `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool-id|AssetA/AssetB>` over `--month N` (default 3) |
256
+ | `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool|AssetA/AssetB>` over `--month N` (default 3); pool = id (133 / 1.19.133) or pool token (LP share-asset symbol) |
257
257
  | `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
258
+ | `dexbot liquid <target>` | `liq` (default shorthand), `liqu`, `liquidity` | Blended order-book + AMM pool liquidity depth chart for `<bot|pool|AssetA/AssetB>` (`--range`, `--depth`, `--steps`); a pool target (id or pool token) derives both legs |
258
259
  | `dexbot pnl <account>` | — | HTML PnL report for a bot/account over `--month N`, optional `--pair BASE/QUOTE` filter |
260
+ | `dexbot asset <bts\|symbol\|1.3.x>` | `a` | Supply distribution: `bts` for the core asset (collateral, pools, locks, residual), a bare symbol/id for an issued asset; `--json`, `--html`/`--no-html`, `--detail`, `--holders` |
259
261
  | `dexbot git` | — | Analyze repository git history and write an added/deleted-lines HTML chart (`repo-stats.html`; source checkouts only) |
260
262
  | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots. Whole-runtime: an optional bot name is validated, then ignored |
261
263
  | `dexbot start` | `unlock` | Run credential daemon + bot (equivalent to running the `unlock` runtime, `dist/unlock.js`) |
@@ -311,7 +313,13 @@ npm run pmain
311
313
  |--------|---------|-------------|-----------|
312
314
  | `npm run ptest` | Push test to origin | Checks out `test` (if not on it) and pushes local commits to `origin/test`. Does **not** touch `dev`/`main`. | Daily development; ensures `origin/test` is up-to-date |
313
315
  | `npm run pdev` | Mirror test onto dev | Pushes `origin/test`, then `git push origin test:dev --force` and updates the local `dev` pointer. No merge commit. | When test is stable and you want `dev` to exactly equal `test` |
314
- | `npm run pmain` | Mirror test onto dev and main | Pushes `origin/test`, then force-pushes `test` to both `dev` and `main` and updates local pointers. **No tagging.** | Full release where `test == dev == main` is intended. Tag manually afterward (see step 5) |
316
+ | `npm run pmain` | Mirror test onto dev and main | Pushes `origin/test`, then force-pushes `test` to both `dev` and `main` in one `--atomic` push and updates local pointers. **No tagging.** | Full release where `test == dev == main` is intended. Tag manually afterward (see step 5) |
317
+
318
+ All three scripts run a shared preflight before touching anything
319
+ (`scripts/lib/git_preflight.sh`): a read-only `git ls-remote` against `origin`.
320
+ An unreachable remote or a rejected SSH key now fails up front instead of
321
+ mid-script, and `pmain`'s `--atomic` push keeps `dev`/`main` together — a
322
+ refusal moves neither. Bypass the check with `DEXBOT_SKIP_GIT_PREFLIGHT=1`.
315
323
 
316
324
  Note: `pmain` does **not** create a release tag. Run `git tag -a v0.X.Y -m "..."` manually after `pmain` if you need a tagged release point.
317
325
 
@@ -275,8 +275,33 @@ The master grid (`this.orders`) is **immutable** - it can only be replaced atomi
275
275
  | `deepFreeze()` | `manager.ts` | Individual order objects are deep-frozen |
276
276
  | `_gridVersion` | `manager.ts` | Version counter for staleness detection |
277
277
  | `_gridLock` | `manager.ts` | AsyncLock serializes grid mutations |
278
+ | `_placementLock` | `manager.ts` / `placement_lock.ts` | Exclusive placement region: serializes every chain-mutating path (COW broadcast, reconcile Phase 1+2, correction drain, dust/residual cancel, pool swap) |
278
279
  | Encapsulation | `manager.ts` | Index Sets are private; mutations only via `_applyOrderUpdate()` |
279
280
 
281
+ ### Exclusive Placement Region
282
+
283
+ `_gridVersion` protects the MASTER from a stale plan; it does not stop two paths
284
+ from broadcasting at the same time. That is the placement region
285
+ (`modules/order/placement_lock.ts`): a non-reentrant FIFO lease claimed once per
286
+ chain-mutating operation.
287
+
288
+ - Non-token holders use `manager.withPlacement(kind, fn)`, which owns the bounded
289
+ wait, the shutdown probe and the release. The two token-level holders are the
290
+ COW batch body and startup reconcile (they hold the lease across plan →
291
+ broadcast → commit).
292
+ - Nested work must NOT acquire again: it receives the holder's lease and verifies
293
+ it with `manager.isPlacementLeaseCurrent(lease)` — `isPlacementActive()` is true
294
+ for ANY holder, so it cannot prove ownership (a lease invalidated by
295
+ `forceRelease()` would still read as live).
296
+ - Anything that cannot get the region aborts or defers its batch instead of
297
+ broadcasting unprotected (`[PLACEMENT]`/`[DUST]`/`[RESIDUAL]`/`[MAINT]` deferral
298
+ lines).
299
+ - Leak protection: `_clearStalePlacementRegion()` force-releases a region held past
300
+ `TIMING.PLACEMENT_STALE_CLEAR_MS`, refuses while a bot-level pipeline counter
301
+ younger than that bound proves progress, and clears the hung region's stale
302
+ broadcast refcount in the same step. The broadcast-refcount watchdog mirrors the
303
+ rule in reverse (it refuses while a placement lease is held).
304
+
280
305
  ### Master Grid Update Pattern
281
306
 
282
307
  All master grid updates follow clone-and-replace semantics:
@@ -483,7 +508,10 @@ The correction path is fund-only and never manufactures budget by shrinking a re
483
508
  is never a correction target: a top-up grows an order at its current price, so
484
509
  it cannot move bestBuy/bestSell and cannot narrow the spread.
485
510
  4. Contiguous gap-slot promotion may extend the window while preserving
486
- MIN_SPREAD_ORDERS and the opposite placed rail.
511
+ MIN_SPREAD_ORDERS and the opposite placed rail. A same-side order already
512
+ **placed inside the band** is absorbed by the slide (it becomes a legal rail
513
+ member); the walk steps over it and promotes only the next empty slot, so a
514
+ placed edge never becomes a duplicate CREATE target.
487
515
  5. If free funds cannot cover every target, place the affordable prefix, then
488
516
  **rotate a resting same-side order** into each unfunded promoted gap slot
489
517
  (same booked size, never a new commitment). A fully allocated rail has ~0
@@ -605,9 +633,15 @@ rail-edge price would teleport the window to that edge (observed: boundary 29
605
633
  anchor — a partial at a far slot is still a real trade, and its residual is the
606
634
  allow-listed case below.
607
635
 
608
- A live order inside the re-typed band still refuses the re-anchor
609
- (`unsafe: placed_order_in_band`) with one deliberate exception: the fill's
610
- **own PARTIAL residual** at the anchor slot (same side, same ladder level) is
636
+ A move that strands **strictly fewer** placed orders than the committed boundary
637
+ is accepted as a violation-reducing repair; an equal count still refuses
638
+ (canonical statement: `INV-COW-006` in
639
+ [COW_INVARIANTS.md](COW_INVARIANTS.md#cow-pipeline) — this section is
640
+ its rationale, not a second definition). The
641
+ comparison uses `validatePersistedBoundary`'s own in-band count
642
+ (`boundaryMoveReducesStrands`), so the fill re-anchor and the rail clamp cannot
643
+ disagree about what "stranded" means. Within that bound, the fill's **own
644
+ PARTIAL residual** at the anchor slot (same side, same ladder level) is
611
645
  allow-listed, because any boundary that puts the fill outside its window
612
646
  necessarily puts that remainder inside the band. A partial fill therefore no
613
647
  longer deadlocks the geometry; GAP-EVAC cleans the residual afterwards.
@@ -668,7 +702,10 @@ GAP-EVAC / the next plan owns the offending order. The result is then passed
668
702
  through the shared `validatePersistedBoundary` gate (skipped only for a sparse
669
703
  ladder, whose array-length ceiling would reject everything), with the slots the
670
704
  batch cancels or rotates away allow-listed — so the rail clamp and the re-anchor
671
- cannot disagree about what "stranded in the band" means.
705
+ cannot disagree about what "stranded in the band" means. The gate accepts a
706
+ candidate that strands **strictly fewer** placed orders than the committed
707
+ boundary (the same violation-reducing rule the re-anchor uses), which is what
708
+ lets a fill-derived retreat land while GAP-EVAC is still draining older strands.
672
709
 
673
710
  ### Live-Price Provenance (fill, gap, crossing)
674
711
 
@@ -907,18 +907,32 @@ _finishStartupSequence()
907
907
 
908
908
  **Critical Rule: Always acquire locks in ascending level order**
909
909
 
910
- The canonical 5-level hierarchy (defined at `manager.ts`):
910
+ The canonical hierarchy (defined at `manager.ts`):
911
911
 
912
912
  ```
913
- Level 0: _fillProcessingLock (fill processing — outermost)
914
- Level 1: _divergenceLock (divergence checks)
915
- Level 2: _syncLock (sync operations — timeout-protected)
916
- Level 3: _gridLock (grid mutations)
917
- Level 4: _fundLock (fund operations — innermost)
913
+ Level 0: _fillProcessingLock (fill processing — outermost)
914
+ Level 0.5: placement region (exclusive chain-mutation mutex — PlacementLock)
915
+ Level 1: _divergenceLock (divergence checks)
916
+ Level 2: _syncLock (sync operations — timeout-protected)
917
+ Level 3: _gridLock (grid mutations)
918
+ Level 4: _fundLock (fund operations — innermost)
918
919
  ```
919
920
 
920
- All five locks live on the `OrderManager` instance. The `level` property is a
921
- convention marker — AsyncLock does not enforce it at runtime.
921
+ All levels live on the `OrderManager` instance (the placement region is
922
+ `_placementLock`, see `modules/order/placement_lock.ts`). The `level` property
923
+ is a convention marker — AsyncLock does not enforce it at runtime, and
924
+ `PlacementLock` is not an AsyncLock (it is a FIFO, non-reentrant lease).
925
+
926
+ **Placement region (Level 0.5)** serializes every chain-mutating path: COW
927
+ broadcasts, reconcile Phase 1+2, correction drains, dust/residual cancels and
928
+ pool swaps. It is acquired **before** `_gridLock` and never while holding it,
929
+ and it is `NOT` reentrant — nested work receives the holder's lease instead of
930
+ acquiring again, and verifies it with `manager.isPlacementLeaseCurrent(lease)`
931
+ (`isPlacementActive()` is true for ANY holder and must not be used for that).
932
+ The canonical region order is:
933
+ `startBroadcasting → placement → gridLock → fundLock → release placement → stopBroadcasting`.
934
+ A leaked region is force-released by `_clearStalePlacementRegion()`, which also
935
+ drops the hung region's stale broadcast refcount in the same step.
922
936
 
923
937
  **Why This Order?**
924
938
 
@@ -926,6 +940,9 @@ convention marker — AsyncLock does not enforce it at runtime.
926
940
  - Divergence checks (Level 1) nest inside fill processing
927
941
  - Sync operations (Level 2) are acquired before grid mutations — the timeout-protected lock is inner, so a stuck sync releases the outer lock
928
942
  - Grid mutations (Level 3) and fund operations (Level 4) are innermost
943
+ - The placement region (Level 0.5) sits between fill processing and the grid
944
+ locks: it is broader than one grid mutation (it spans plan → broadcast →
945
+ commit) but must never be taken while a grid lock is held
929
946
  - All paths follow the same order
930
947
 
931
948
  **`adjustTotalBalance` Locking Contract** (v1.4.7):
package/modules/README.md CHANGED
@@ -37,7 +37,11 @@ modules/
37
37
  ├── version_notice.ts passive npm-registry version check + status line
38
38
  ├── cli_start_onboarding.ts first-run setup routing for `dexbot start`
39
39
  ├── cli_start_output.ts launcher notice formatting
40
- ├── cli_colors.ts shared CLI color helpers
40
+ ├── cli_colors.ts shared CLI color palette + `colorize()`
41
+ ├── cli_progress.ts shared `[Tag]` lines: progress, section, warnings, summary, saved link
42
+ ├── liquidity_pool_ref.ts pool id / pool token resolution (shared by liq/tv/dw)
43
+ ├── chain_scan.ts batched object-id walk for list-less types (1.13/1.15)
44
+ ├── asset_lookup.ts case-insensitive asset refs (symbol/id) for every CLI
41
45
  ├── credential_runtime.ts daemon socket/path helpers + private-path security
42
46
  ├── credential_policy.ts signing policy validation
43
47
  ├── credential_session_cache.ts encrypted session cache
@@ -66,6 +70,7 @@ modules/
66
70
  ├── chain_keys.ts master-password vault + signing-key retrieval
67
71
  ├── daemon_node_health.ts daemon-side node failure ledger (shared rules)
68
72
  ├── node_failure_ledger.ts node failure counting shared by bot + daemon
73
+ ├── node_flap_score.ts time-decayed connection-churn score used for node ranking
69
74
  ├── node_health_cache.ts shared node-health cache file I/O + ordering
70
75
  ├── socket_json_client.ts newline-delimited JSON Unix-socket client
71
76
  ├── market_adapter_whitelist.ts adapter whitelist I/O
@@ -94,9 +99,11 @@ modules/
94
99
  │ ├── strategy.ts grid rebalancing, consolidation, rotation
95
100
  │ ├── accounting.ts fund tracking, fee accounting
96
101
  │ ├── sync_engine.ts blockchain sync, fill detection, reconciliation
102
+ │ ├── lifecycle.ts one record per slot: chain existence, phase, evidence, clocks (docs/ORDER_LIFECYCLE.md)
97
103
  │ ├── genesis_policy.ts missing-ladder refusal + rebuild policy (docs/GRID_PRICE_INVARIANT.md)
98
104
  │ ├── grid_reconcile.ts startup grid reconciliation (docs/GRID_RECONCILE.md)
99
105
  │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
106
+ │ ├── placement_lock.ts exclusive chain-mutating region: FIFO lease, non-reentrant, bounded wait
100
107
  │ ├── index.ts barrel export
101
108
  │ ├── logger.ts order-scoped logging
102
109
  │ ├── logger_state.ts logger state management
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.18",
3
+ "version": "1.7.1",
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": {
@@ -97,10 +97,12 @@
97
97
  "ama:chart:lp-local": "npm run build && node dist/analysis/ama_fitting/generate_unified_comparison_chart.js",
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
+ "analysis:liquidity": "npm run build && node dist/analysis/analyze_liquidity.js",
100
101
  "analysis:resolve-accounts": "npm run build && node dist/analysis/resolve_bot_accounts.js",
101
102
  "richlist": "npm run build && node dist/scripts/rich_list.js",
102
103
  "distribution": "npm run build && node dist/scripts/bts_distribution.js",
103
104
  "token-distribution": "npm run build && node dist/scripts/token_distribution.js",
105
+ "asset": "npm run build && node dist/scripts/asset.js",
104
106
  "native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
105
107
  "native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
106
108
  "native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",