dexbot 1.7.1 → 1.7.3

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 (66) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/analysis/grid_correction_check.d.ts +60 -1
  6. package/dist/analysis/grid_correction_check.js +268 -18
  7. package/dist/analysis/pivot_timeline.d.ts +78 -0
  8. package/dist/analysis/pivot_timeline.js +360 -0
  9. package/dist/market_adapter/utils/file_lock.js +16 -4
  10. package/dist/modules/account_bots.d.ts +7 -0
  11. package/dist/modules/account_bots.js +7 -5
  12. package/dist/modules/bot_defaults.js +6 -1
  13. package/dist/modules/constants.d.ts +14 -0
  14. package/dist/modules/constants.js +82 -2
  15. package/dist/modules/dexbot_class.d.ts +39 -0
  16. package/dist/modules/dexbot_class.js +86 -1
  17. package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
  18. package/dist/modules/dexbot_cow_runtime.js +299 -75
  19. package/dist/modules/dexbot_maintenance_runtime.d.ts +32 -2
  20. package/dist/modules/dexbot_maintenance_runtime.js +196 -16
  21. package/dist/modules/dexbot_state_recovery.js +15 -1
  22. package/dist/modules/launcher/instance_lock.d.ts +27 -0
  23. package/dist/modules/launcher/instance_lock.js +131 -0
  24. package/dist/modules/node_flap_score.d.ts +6 -6
  25. package/dist/modules/node_flap_score.js +6 -6
  26. package/dist/modules/order/accounting.d.ts +9 -4
  27. package/dist/modules/order/accounting.js +89 -26
  28. package/dist/modules/order/async_lock.d.ts +7 -1
  29. package/dist/modules/order/async_lock.js +7 -1
  30. package/dist/modules/order/export.js +25 -18
  31. package/dist/modules/order/fill_ledger.d.ts +99 -0
  32. package/dist/modules/order/fill_ledger.js +103 -0
  33. package/dist/modules/order/grid.d.ts +94 -18
  34. package/dist/modules/order/grid.js +247 -75
  35. package/dist/modules/order/grid_reconcile_internal.js +16 -4
  36. package/dist/modules/order/index.d.ts +29 -6
  37. package/dist/modules/order/index.js +5 -5
  38. package/dist/modules/order/lifecycle.js +3 -3
  39. package/dist/modules/order/manager.d.ts +36 -24
  40. package/dist/modules/order/manager.js +159 -39
  41. package/dist/modules/order/placement_lock.d.ts +30 -0
  42. package/dist/modules/order/placement_lock.js +48 -0
  43. package/dist/modules/order/sync_engine.d.ts +66 -118
  44. package/dist/modules/order/sync_engine.js +118 -162
  45. package/dist/modules/order/utils/math.d.ts +7 -3
  46. package/dist/modules/order/utils/math.js +7 -3
  47. package/dist/modules/order/utils/order.d.ts +79 -42
  48. package/dist/modules/order/utils/order.js +183 -86
  49. package/dist/modules/order/utils/system.d.ts +192 -8
  50. package/dist/modules/order/utils/system.js +534 -34
  51. package/dist/modules/paths.d.ts +1 -0
  52. package/dist/modules/paths.js +1 -0
  53. package/dist/modules/timing_policy.js +4 -2
  54. package/dist/modules/types.d.ts +49 -27
  55. package/dist/pm2.js +126 -0
  56. package/dist/unlock.js +26 -1
  57. package/docs/COW_INVARIANTS.md +5 -1
  58. package/docs/DEXBOT_COMPARISON.md +5 -5
  59. package/docs/EVOLUTION.md +10 -8
  60. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  61. package/docs/GRID_RECONCILE.md +3 -3
  62. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +192 -31
  63. package/docs/README.md +1 -1
  64. package/docs/architecture.md +26 -8
  65. package/modules/README.md +4 -0
  66. package/package.json +4 -3
@@ -4,17 +4,18 @@
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.7.0 (plus the unreleased post-1.7.0 arc);
7
+ > **Sources:** `CHANGELOG.md` v1.0.0 → v1.7.1 (plus the post-1.7.1 arc);
8
8
  > `docs/GRID_PRICE_INVARIANT.md`; `docs/COW_INVARIANTS.md`; `docs/ORDER_LIFECYCLE.md`.
9
9
  > Generic terms only — no live markets, accounts, or order ids.
10
10
  >
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.
11
+ > **Scope / snapshot:** v1.0.0 → v1.7.1 (`2a85a501`, 2026-11-04), extended through the
12
+ > post-1.7.1 work at `bc20d574` (2026-11-04). §9 is the v1.6.4 → v1.6.17
13
+ > addendum; §9.10 closes the v1.6.18 review pass, §9.11 carries v1.6.18 → v1.7.1,
14
+ > and §9.12 records the subsequent revised-priority review.
14
15
  >
15
16
  > **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
16
17
  > source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`); §9 is a
17
- > later addendum (v1.6.4 → v1.6.17, with §9.10/§9.11 extending it) that adds to, and does not
18
+ > later addendum (v1.6.4 → v1.6.17, with §9.10–§9.12 extending it) that adds to, and does not
18
19
  > renumber, that range. Part I uses `R1`–`R5` so the two never collide. The closing appendix
19
20
  > is unnumbered (`A`).
20
21
  >
@@ -49,7 +50,8 @@
49
50
  - 8. Provenance & supersession record
50
51
  - 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17) — addendum
51
52
  - 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
53
+ - 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
54
+ - 9.12 Revised priority list: counter-orders, pivot evidence and level-triggered repair
53
55
  - A. Grid-Price Invariant — former failure trace (appendix)
54
56
 
55
57
  ---
@@ -568,17 +570,17 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
568
570
  - [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
569
571
  - [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.
570
572
 
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`.*
573
+ *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.1 at `2a85a501` plus the post-1.7.1 arc (`§9.11`, HEAD `bc20d574`). 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`.*
572
574
 
573
575
  ---
574
576
 
575
577
  ### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17)
576
578
 
577
579
  > **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`.
580
+ > §9.10 and §9.11 extend past it — §9.10 released in v1.6.18; §9.11 released in v1.7.1,
581
+ > with the post-1.7.1 additions at HEAD `bc20d574`.
580
582
  > Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
581
- > The ledger labels each row with its release; `unreleased` means "in no tag yet".
583
+ > The ledger labels each row with its release; `post-1.7.1` means after the v1.7.1 tag.
582
584
 
583
585
  Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
584
586
  proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
@@ -668,7 +670,7 @@ fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and
668
670
  truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
669
671
  required is no longer reachable at runtime.
670
672
 
671
- #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.0 + unreleased)
673
+ #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.1 + post-1.7.1)
672
674
 
673
675
  | Commit | Release | Change |
674
676
  |---|---|---|
@@ -713,18 +715,24 @@ required is no longer reachable at runtime.
713
715
  | `a93f7eef` | 1.7.0 | Stale-grid re-buys: unsettled-fill gate, attribution, same-level refusal (§9.11.1) |
714
716
  | `8705381b` | 1.7.0 | Orphan-fill attribution by price; dark-level revive (§9.11.1) |
715
717
  | `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) |
718
+ | `c493a604` | 1.7.1 | Stranded-boundary repair without re-arming on replays (§9.11.3) |
719
+ | `ed52f9ef` | 1.7.1 | Exclusive placement region; no create-only re-plan after a rebuild (§9.11.3) |
720
+ | `970fedfd` | 1.7.1 | Remaining placement races; fill-accounting double-apply |
721
+ | `ad081e3d` | 1.7.1 | Placement lifecycle + fill-marker idempotency |
722
+ | `7a3571a4` | 1.7.1 | Follow-up gaps: one teardown, one lease check, one pending-broadcast policy |
723
+ | `94223d19` | 1.7.1 | Re-verify the placement lease before a region holder broadcasts |
724
+ | `8bab9881` | 1.7.1 | Unknown gap geometry is not gap 0 |
725
+ | `4d5e3d81` | 1.7.1 | Forced retreats evacuate, then re-plan the committed band |
726
+ | `7618f299` | 1.7.1 | Cancel teeth may not destroy the rotation that evacuates |
727
+ | `826d84a3` | 1.7.1 | Chain existence unified behind the lifecycle registry (§9.11.3) |
728
+ | `7252d7d3` | 1.7.1 | Broadcast uncertainty as a typed three-valued outcome (§9.11.3) |
729
+ | `84b935d9` | 1.7.1 | One writer per life-cycle clock, one guard per absence decision (§9.11.3) |
730
+ | `3edf8cb3` | post-1.7.1 | Release leaked broadcast regions; cancel wrong-side fills |
731
+ | `6afa0c4b` | post-1.7.1 | Fill side from the paid asset at every call site; backlog coalescing |
732
+ | `cb1041b6` | post-1.7.1 | Never park a chain-observed wrong-side cancel; the repair proof checks rail geometry |
733
+ | `b2f43d8a` | post-1.7.1 | One fill contract, fail-closed grid blockers, one fill identity (P0–P2) |
734
+ | `39675d8a` | post-1.7.1 | Claim the fill key at credit time; drop the duplicate amount channel (P2 tail) |
735
+ | `bc20d574` | post-1.7.1 | One grace-stamp writer, ledger side in export, single-winner fill claim |
728
736
 
729
737
  #### 9.6 Invariants added
730
738
 
@@ -905,7 +913,7 @@ extraction) · `56481b16` (P5) · `3d16f9e4` (this document, the doc-level invar
905
913
  and the log rows it cites). **Released in v1.6.18:** the review pass itself carried no
906
914
  version bump, but every commit above is an ancestor of the `v1.6.18` tag (2026-11-01).
907
915
 
908
- #### 9.11 v1.6.18 → unreleased: fill identity, absence and the geometry budget
916
+ #### 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
909
917
 
910
918
  The post-1.6.17 work stopped asking "which guard is missing?" and started asking
911
919
  "which *identity* is the code using?". Three answers landed: a fill is identified
@@ -962,7 +970,7 @@ Three defects of the same shape:
962
970
  Price, side and clock now travel as one row, and the TTL is enforced where the reference
963
971
  is **read**; an unknown age never expires.
964
972
 
965
- ##### 9.11.3 Absence gets one record; repairs must reduce the violation (unreleased)
973
+ ##### 9.11.3 Absence gets one record; repairs must reduce the violation (v1.7.1)
966
974
 
967
975
  Chain existence used to be answered by seven structures with seven clocks
968
976
  (`_pendingBroadcasts`, `createUncertain`, `_committedOrderIds`,
@@ -973,12 +981,14 @@ the bug reappeared at the next.
973
981
 
974
982
  `modules/order/lifecycle.ts` (`826d84a3`, `7252d7d3`, `84b935d9`) now owns one
975
983
  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`).
984
+ lost receipt is *not* an absence), a monotonic evidence rank, and every existence
985
+ clock recorded once. The legacy maps survive as live views, so no call site had
986
+ to be rewritten to get one truth. The persisted `createUncertain` flag is still
987
+ read as evidence; `_lastUnmatchedChainOrders` remains a chain-diff cache for
988
+ orphan diagnostics, not an existence answer. Three rules fall out of it: one
989
+ absence guard (`isInFlight()`, time-bounded), one teardown authority for a hung
990
+ region (`_clearStalePlacementRegion`, `7a3571a4`), and one pending-broadcast
991
+ liveness policy (`getLivePendingBroadcasts`).
982
992
 
983
993
  Geometry gained the matching rule. A boundary writer may move the boundary only
984
994
  when the move strands **strictly fewer** placed orders than the committed value
@@ -996,6 +1006,157 @@ re-planning instead of letting its cancel teeth destroy the rotation (`7618f299`
996
1006
  is not a style complaint. Every family above is that pattern applied to a
997
1007
  different noun — price, fill, existence.
998
1008
 
1009
+ ##### 9.12 Revised priority list: counter-orders, pivot evidence and level-triggered repair
1010
+
1011
+ This review followed the live out-of-spread incident in priority order. The ordering
1012
+ matters: a later watchdog cannot repair a counter-order that an earlier hard veto
1013
+ removed, and a pivot policy cannot be trusted if rotation has already corrupted the
1014
+ ladder it anchors.
1015
+
1016
+ **P0 — keep the counter-order executable.** `describeMarketCrossingActions` uses the
1017
+ single recency-aware `resolveSpreadCrossingFloor` only for an observation. It reports
1018
+ CREATE/UPDATE actions across the floor but never removes them. The internal crossed-book
1019
+ assertion remains blocking: BUY-versus-SELL collisions inside the bot's own simulated
1020
+ book are a different invariant. A stale bot-mid must not provide a second floor or veto
1021
+ the only action that can narrow a gap.
1022
+
1023
+ **P1 — only current-window evidence may arm the pivot.** Fill provenance now has two
1024
+ market-bound checks while the cached market read is fresh: wrong-side fills are refused,
1025
+ and fills more than `GRID_LIMITS.LAST_FILL_PIVOT_MAX_MID_DISTANCE_STEPS` ladder steps
1026
+ from the market are refused symmetrically. The check fails open when the read is absent
1027
+ or stale. Separately, `OrderManager.recordLastFilledPrices` skips fills whose current
1028
+ slot is in the gap band: those are stranded residuals, not window trades. Edge-pinned
1029
+ fills remain excluded by the existing shared classifier. A rail/window fill is still
1030
+ recorded once, by the existing pivot writer.
1031
+
1032
+ **P2 — the pivot may not veto its own counter-order territory.** The shared
1033
+ `evaluateLastFillGuard` verdict is used by both COW placement checks and the final
1034
+ pre-broadcast gate. A SELL strictly below a SELL pivot, inside the band that the fill
1035
+ anchor itself derives, is allowed only when `boundary >= pivotIdx - gapSlots`; this is
1036
+ geometry evidence that the crawl is not behind the fill. The exact pivot level remains
1037
+ blocked as a same-level re-fill, and the BUY mirror remains blocked. Unknown geometry,
1038
+ off-ladder prices and book-seeded pivots fail closed for the exemption.
1039
+
1040
+ **P3 — a rotation moves ownership, not ladder identity.** In
1041
+ `buildCowResultFromPlan`, a rotation UPDATE has two effects: the source becomes a hole
1042
+ at its own genesis price, while the destination receives the planned price/size. The
1043
+ source is never re-priced to the destination. The invariant is checked before apply and
1044
+ again by the post-commit transition; non-rotation partial UPDATEs remain in-place size
1045
+ updates.
1046
+
1047
+ **P4 — a repair must reduce the measured violation.** The entry and post-placement
1048
+ readings share `measureSpreadExcess`, including the same slot-N live-window filter and
1049
+ one-sided handling. `trackOutOfSpreadStaleness` clears its clock after a placement only
1050
+ when `excessAfter < excessBefore`; an unchanged placement is logged and remains stale.
1051
+ If a caller cannot measure the post-placement value, the compatibility fail-open path
1052
+ preserves the established behavior rather than inventing a negative result.
1053
+
1054
+ **P5 — every stale level owns its retry.** While out of tolerance, the watchdog arms one
1055
+ shutdown-safe, deduplicated `SPREAD_STALE_RECHECK_MS` timer. It is not dependent on a
1056
+ future fill or the four-hour blockchain-fetch cadence, so the 5/10/20/30-minute stale
1057
+ windows can actually run. The timer re-enters the normal maintenance pipeline and is
1058
+ cancelled with the bot. A healthy reading must hold for the configured in-tolerance
1059
+ reset window before clearing stale geometry memory.
1060
+
1061
+ **P6 — fill ownership was audited, not duplicated.** The fill history path and orphan
1062
+ fill path both book accounting first and delegate unmatched attribution to the shared
1063
+ `attributeUnmatchedFillToGrid` owner. Replay keys make the pivot/crawl mutation once per
1064
+ fill. No second fill writer was introduced; the regression coverage documents this
1065
+ contract instead of changing working attribution code.
1066
+
1067
+ **Regression gates added/updated:** `test_last_fill_pivot_market_bound` (distance leg
1068
+ and observation/floor recency), `test_pivot_geometry_eligibility` (in-band pivot
1069
+ eligibility and veto territory), `test_rotation_source_level` (source/destination
1070
+ ladder identity), `test_incident_replay` (end-to-end band evacuation), and
1071
+ `test_stale_grid_hardening` (no-progress watchdog and level-triggered recheck). The
1072
+ production build, test build and these incident suites must all pass before promotion.
1073
+
1074
+ **Addendum (2026-11-16, offline audit reconciliation): the checker must audit the gate
1075
+ the runtime actually ran.** During a fast sweep of the bot's own premium rail on a live
1076
+ market-pair bot, the offline direction checker (`analysis/grid_correction_check.ts`)
1077
+ flagged six SELL re-quotes as discipline breaches while the runtime had passed every one
1078
+ of them through its own final gate. The two sides disagreed because they used different
1079
+ pivots:
1080
+
1081
+ - The runtime pivots on `_lastFilledPrice` at decision time, and since P1 above a fill
1082
+ refused from arming (wrong-side, too-far premium sweep, gap-band stranded residual)
1083
+ leaves the pivot behind the true last fill — by up to ~15 grid steps during the sweep.
1084
+ - The strict checker fed true consecutive fills into the same predicate
1085
+ (`isLastFillGuardBlocked`), so it judged each re-quote against a pivot the runtime
1086
+ never held at that gate.
1087
+
1088
+ The runtime did not breach its own rule: its `mode=`/Final-gate lines show
1089
+ `checked/passed` counts consistent with the pivots it held, and every flagged re-quote
1090
+ priced above the runtime's (older, lower) pivot, so no sell landed below realized cost.
1091
+ The refusal policy is deliberate — reverting it would re-introduce the unquoted-side
1092
+ deadlock P1 was written against — so the fix is on the audit side:
1093
+
1094
+ - `analysis/pivot_timeline.ts` reconstructs the runtime's pivot timeline from the bot
1095
+ log's own bookkeeping (`[FILL-PIVOT]`, `mode=`, Final-gate, refusal and allowance
1096
+ lines). "Pivot refreshed from N pending queued fill(s)" is deliberately not an
1097
+ observation: it logs queue content that may be exactly the fill the arming policy just
1098
+ refused.
1099
+ - The checker's default mode is now policy-aware: each strict candidate is re-judged
1100
+ against the pivot the runtime held when the filled order was last priced. Verdicts:
1101
+ `violation` (the runtime's own pivot would have blocked it — a real gate failure),
1102
+ `policy-divergence` (expected under the P1 arming policy; reported in its own section,
1103
+ not counted as FAIL), `unverifiable` (no placement event / pivot observation near the
1104
+ gate — kept as a violation, failing toward reporting). `--strict` preserves the legacy
1105
+ all-fills behaviour; a missing log falls back to strict with a notice.
1106
+ - Order-id joins normalize the Kibana operation suffix (`1.7.x:…` vs the log's plain
1107
+ `1.7.x`), naive Kibana timestamps are read as UTC, and the placement anchor is the
1108
+ order event whose price matches the fill (a post-fill rotation to another level must
1109
+ not become the anchor, or the fill is judged against the pivot it armed itself).
1110
+
1111
+ Lesson: an offline checker that re-implements gate inputs drifts from the gate it
1112
+ audits; it must reconstruct the gate's actual state, and every reconciliation shortcut
1113
+ (timestamps, ids, anchors) is a potential false verdict in either direction.
1114
+
1115
+ **Addendum 2 (2026-11-16, same-level re-fill loop): the P1 refusal silently suspended
1116
+ the P2 same-level block.** The sweep window that produced the six policy divergences
1117
+ above also produced a second, previously invisible pattern: one premium
1118
+ spread-correction slot was re-armed by the correction loop at the identical level and
1119
+ refilled five times in ~2.5 minutes (each cycle: full fill → slot orphaned → next
1120
+ correction cycle re-activates the same slot at the same grid price → immediate fill).
1121
+ Economically benign — every fill priced well above the day's cost basis and the taker
1122
+ kept paying a ~2.9% premium — but a real rule gap:
1123
+
1124
+ - §9.12/P2 blocks the exact pivot level as a same-level re-fill; that block keys off
1125
+ the ARMED pivot. §9.12/P1 refuses off-market (premium-sweep) fills from arming.
1126
+ Together: exactly while a sweep runs, the same-level re-fill protection is
1127
+ suspended — the one window it is needed most.
1128
+ - The offline checker passed the loop: realized fill prices of the re-placed level
1129
+ differ by sub-sat rounding dust, so the strict "sell→sell must rise" float compare
1130
+ saw a rise at every cycle. §0's ground truth ("equal is a violation") is about the
1131
+ LEVEL, not the float.
1132
+
1133
+ Amended policy (both sides of the audit line):
1134
+
1135
+ 1. Runtime (`modules/order/utils/system.ts`): a refused fill writes an in-memory,
1136
+ TTL-bounded (`GRID_LIMITS.LAST_FILL_REFUSED_LEVEL_TTL_MS`, 30 min) refused-level
1137
+ marker; `evaluateLastFillGuard` (the shared verdict) and
1138
+ `isLastFillPlacementBlocked` refuse a same-side placement within half a grid step
1139
+ (`pricesWithinHalfStep`) of the marked level, surfaced as `refusedLevel` /
1140
+ reason `refused-level` at every skip site. It vetoes exactly one level and nothing
1141
+ else — the counter-side stays governed by the older direction pivot and spread
1142
+ correction keeps trading around the live market, so the unquoted-side deadlock P1
1143
+ was written against cannot re-open through it. Deliberately NOT a cooldown or
1144
+ backoff on the correction loop (R4/§9.10/P4 "observability instead of a veto";
1145
+ §9.12/P5 owns stale-level retries; a hard pause would have left the sell side
1146
+ unquoted mid-sweep — the marked slot was the only placeable one at the time).
1147
+ 2. Checker (`analysis/grid_correction_check.ts`): same-level transitions (same
1148
+ direction, different orders) are detected with the runtime's OWN
1149
+ `pricesWithinHalfStep` and become strict candidates. In policy-aware mode a
1150
+ same-level candidate whose just-filled level carries a fresh refusal marker in the
1151
+ runtime log is a VIOLATION (the amended gate would have blocked the re-placement;
1152
+ it filled anyway); without marker evidence it is a policy divergence tagged
1153
+ `sameLevel`. `--strict` counts every same-level candidate as a violation.
1154
+
1155
+ Pinned by `tests/test_refused_level_refill_block.ts` (REFUSED-1..9) and
1156
+ `tests/test_same_level_refill_check.ts` (SL-1..10). With the amendment applied, the
1157
+ 2026-11-16 audit baseline reads: 10 strict candidates = 4 same-level violations (the
1158
+ loop) + 6 policy divergences (the sweep re-quotes, unchanged).
1159
+
999
1160
  ---
1000
1161
 
1001
1162
  ### A. Grid-Price Invariant — former failure trace
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.7.1 (released).
5
+ **Version context:** v1.7.3 (released).
6
6
 
7
7
  ---
8
8
 
@@ -513,14 +513,18 @@ The correction path is fund-only and never manufactures budget by shrinking a re
513
513
  member); the walk steps over it and promotes only the next empty slot, so a
514
514
  placed edge never becomes a duplicate CREATE target.
515
515
  5. If free funds cannot cover every target, place the affordable prefix, then
516
- **rotate a resting same-side order** into each unfunded promoted gap slot
517
- (same booked size, never a new commitment). A fully allocated rail has ~0
518
- free forever, so create-only repair can never close the spread; the rotation
519
- is the repair path and is bounded by the same promotion, crossing, last-fill,
520
- dedupe/duplicate-price and edge-order guards as a create. It never shrinks or
521
- grows the moved order. Exactly-zero free on both sides is covered by a
522
- rotation-only fallback around side selection (an unavailable market price is
523
- still a hard skip: cross-asset comparison is unsafe).
516
+ **rotate a resting same-side order** into each unfunded tightening slot —
517
+ whether it is a promoted gap slot or an orphaned rail slot left by a
518
+ fill-anchored boundary move (same booked size, never a new commitment). A
519
+ fully allocated rail has ~0 free forever, so create-only repair can never
520
+ close the spread. A virtual tail that reserves the whole free balance is not
521
+ a hard stop: moving a far resting order into the window edge frees no new
522
+ inventory but tightens the spread. The rotation is bounded by the same
523
+ promotion, crossing, last-fill, dedupe/duplicate-price and edge-order guards
524
+ as a create. It never shrinks or grows the moved order. Exactly-zero free on
525
+ both sides is covered by a rotation-only fallback around side selection (an
526
+ unavailable market price is still a hard skip: cross-asset comparison is
527
+ unsafe).
524
528
  6. If neither side places an effective order, `checkSpreadCondition` reports a
525
529
  `stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
526
530
  `unmatched-orders` / `readiness-gate` / `last-fill-blocked` /
@@ -664,6 +668,20 @@ anchoring on it leaves the furthest fill's counter order inside the implied
664
668
  band. `calculateTargetGrid` passes the batch into
665
669
  `reanchorBoundaryFromLastFill`.
666
670
 
671
+ **Rebuild and load apply the same anchor.** A fresh generation derives its band
672
+ from the current market center, but the last fill is still geometry fact. If
673
+ that center puts the pivot inside the band, the startup picker correctly skips
674
+ the levels at/through the fill (LAST-FILL-GUARD), fills the same-side window
675
+ lower, and the first ask stays at the old `sellStart` — a realized spread two
676
+ steps wider than target with no fill reason for the extra width (live
677
+ 2026‑11‑04: boundary 159 after a BUY at new-ladder slot 158, realized 2.123% vs
678
+ the 1.5% target). `initializeGrid` and `loadGrid` therefore call
679
+ `anchorRebuildBoundaryToLastFill` after the pivot is re-armed/restored and
680
+ before reconcile/re-type; `applyRebuildFillAnchor` moves the boundary and
681
+ re-types the rails atomically (`BUY fill at 158 => boundary 157`, counter SELL
682
+ at 162). A cold/off-ladder/unsafe fill keeps the derived boundary, so this is a
683
+ no-op on a healthy restart.
684
+
667
685
  ### Rail-Derived Commit Boundary (counter orders are the fact)
668
686
 
669
687
  A plan built at a re-anchored boundary places **counter orders** on the promoted
package/modules/README.md CHANGED
@@ -74,6 +74,8 @@ modules/
74
74
  ├── node_health_cache.ts shared node-health cache file I/O + ordering
75
75
  ├── socket_json_client.ts newline-delimited JSON Unix-socket client
76
76
  ├── market_adapter_whitelist.ts adapter whitelist I/O
77
+ ├── outcome.ts three-valued Outcome construction (applied/rejected/unknown)
78
+ ├── timing_policy.ts timing-window audit: EXTERNAL/BOUND/POLICY/SELF_HEALING classification
77
79
  ├── types.ts shared type definitions
78
80
  │
79
81
  ├── crypto/ cross-environment crypto providers
@@ -100,6 +102,7 @@ modules/
100
102
  │ ├── accounting.ts fund tracking, fee accounting
101
103
  │ ├── sync_engine.ts blockchain sync, fill detection, reconciliation
102
104
  │ ├── lifecycle.ts one record per slot: chain existence, phase, evidence, clocks (docs/ORDER_LIFECYCLE.md)
105
+ │ ├── fill_ledger.ts fill identity, traded-side resolution, booked membership (docs/FILL_PIPELINE.md)
103
106
  │ ├── genesis_policy.ts missing-ladder refusal + rebuild policy (docs/GRID_PRICE_INVARIANT.md)
104
107
  │ ├── grid_reconcile.ts startup grid reconciliation (docs/GRID_RECONCILE.md)
105
108
  │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
@@ -129,6 +132,7 @@ modules/
129
132
  │ ├── credential_secret.ts secret management
130
133
  │ ├── foreign_cred_daemon.ts external daemon client
131
134
  │ ├── headless_password.ts headless password storage
135
+ │ ├── instance_lock.ts per-account single-controller lock
132
136
  │ ├── launch_modes.ts monolithic vs isolated routing
133
137
  │ ├── market_adapter_runtime.ts adapter process lifecycle
134
138
  │ ├── market_adapter_watchdog.ts adapter process watchdog
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.7.1",
3
+ "version": "1.7.3",
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": {
@@ -112,12 +112,12 @@
112
112
  "version:check": "npm run build && node dist/scripts/sync-version.js --check",
113
113
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
114
114
  "test": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
115
- "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
115
+ "test:live": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && RUN_LIVE_BITSHARES_TESTS=1 node dist/scripts/run-tests.js",
116
116
  "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
117
117
  "clean": "node scripts/clean-dist.js",
118
118
  "build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
119
119
  "build:clean": "npm run clean && npm run build",
120
- "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs dist/tests/helpers/",
120
+ "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs tests/helpers/foreign_cred_stub.js dist/tests/helpers/",
121
121
  "typecheck": "tsc --noEmit",
122
122
  "typecheck:analysis": "tsc -p analysis/tsconfig.json",
123
123
  "check:any": "npm run build && node dist/scripts/check_any.js",
@@ -163,6 +163,7 @@
163
163
  "./dist/modules/launcher/status_reporting.js": false,
164
164
  "./dist/modules/launcher/supervisor_control.js": false,
165
165
  "./dist/modules/launcher/monolithic_runtime.js": false,
166
+ "./dist/modules/launcher/instance_lock.js": false,
166
167
  "./dist/modules/launcher/runtime_mode.js": false,
167
168
  "./dist/modules/launcher/market_adapter_runtime.js": false,
168
169
  "./dist/modules/launcher/market_adapter_watchdog.js": false,