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.
- package/CHANGELOG.md +68 -0
- package/README.md +24 -18
- package/analysis/README.md +117 -5
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/account_resolver.js +5 -6
- package/dist/analysis/analyze_dynamic_weight.js +2 -1
- package/dist/analysis/analyze_kalman.js +3 -2
- package/dist/analysis/analyze_liquidity.d.ts +17 -0
- package/dist/analysis/analyze_liquidity.js +336 -0
- package/dist/analysis/analyze_regime.js +3 -2
- package/dist/analysis/analyze_regime_windows.js +3 -2
- package/dist/analysis/analyze_volatility.js +3 -2
- package/dist/analysis/bot_key_utils.d.ts +44 -1
- package/dist/analysis/bot_key_utils.js +76 -7
- package/dist/analysis/fills_cache.js +2 -1
- package/dist/analysis/grid_correction_check.d.ts +1 -19
- package/dist/analysis/grid_correction_check.js +12 -30
- package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
- package/dist/analysis/liquidity/liquidity_chain.js +178 -0
- package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
- package/dist/analysis/liquidity/liquidity_chart_generator.js +693 -0
- package/dist/analysis/liquidity/liquidity_depth_model.d.ts +166 -0
- package/dist/analysis/liquidity/liquidity_depth_model.js +258 -0
- package/dist/analysis/liquidity/liquidity_view.d.ts +53 -0
- package/dist/analysis/liquidity/liquidity_view.js +66 -0
- package/dist/analysis/resolve_bot_accounts.js +7 -6
- package/dist/analysis/trade_profitability.js +4 -2
- package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
- package/dist/credential-daemon.js +13 -2
- package/dist/dexbot.js +77 -172
- package/dist/modules/account_bots.d.ts +11 -1
- package/dist/modules/account_orders.d.ts +12 -0
- package/dist/modules/account_orders.js +30 -0
- package/dist/modules/asset_lookup.d.ts +25 -0
- package/dist/modules/asset_lookup.js +75 -0
- package/dist/modules/bitshares-native/transport.js +24 -6
- package/dist/modules/bitshares_client.d.ts +24 -6
- package/dist/modules/bitshares_client.js +44 -7
- package/dist/modules/bot_settings.d.ts +2 -0
- package/dist/modules/chain_scan.d.ts +64 -0
- package/dist/modules/chain_scan.js +80 -0
- package/dist/modules/cli_colors.d.ts +5 -0
- package/dist/modules/cli_colors.js +7 -0
- package/dist/modules/cli_progress.d.ts +51 -0
- package/dist/modules/cli_progress.js +113 -0
- package/dist/modules/constants.d.ts +26 -3
- package/dist/modules/constants.js +63 -8
- package/dist/modules/dexbot_class.d.ts +1 -6
- package/dist/modules/dexbot_class.js +14 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
- package/dist/modules/dexbot_cow_runtime.js +634 -136
- package/dist/modules/dexbot_fill_runtime.js +132 -23
- package/dist/modules/dexbot_maintenance_runtime.js +242 -74
- package/dist/modules/dexbot_startup_runtime.js +32 -20
- package/dist/modules/dexbot_state_recovery.d.ts +33 -1
- package/dist/modules/dexbot_state_recovery.js +167 -5
- package/dist/modules/launcher/runtime_entry.d.ts +21 -1
- package/dist/modules/launcher/runtime_entry.js +36 -1
- package/dist/modules/liquidity_pool_ref.d.ts +32 -0
- package/dist/modules/liquidity_pool_ref.js +116 -0
- package/dist/modules/node_connect_policy.d.ts +8 -1
- package/dist/modules/node_connect_policy.js +18 -2
- package/dist/modules/node_flap_score.d.ts +87 -0
- package/dist/modules/node_flap_score.js +124 -0
- package/dist/modules/node_health_cache.d.ts +40 -3
- package/dist/modules/node_health_cache.js +66 -20
- package/dist/modules/node_manager.d.ts +101 -19
- package/dist/modules/node_manager.js +255 -65
- package/dist/modules/order/accounting.js +56 -7
- package/dist/modules/order/format.d.ts +24 -10
- package/dist/modules/order/format.js +30 -10
- package/dist/modules/order/grid.js +91 -13
- package/dist/modules/order/grid_reconcile.d.ts +5 -1
- package/dist/modules/order/grid_reconcile.js +333 -189
- package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
- package/dist/modules/order/grid_reconcile_internal.js +298 -100
- package/dist/modules/order/index.d.ts +19 -1
- package/dist/modules/order/lifecycle.d.ts +353 -0
- package/dist/modules/order/lifecycle.js +1109 -0
- package/dist/modules/order/manager.d.ts +273 -5
- package/dist/modules/order/manager.js +654 -48
- package/dist/modules/order/placement_lock.d.ts +102 -0
- package/dist/modules/order/placement_lock.js +222 -0
- package/dist/modules/order/strategy.js +13 -1
- package/dist/modules/order/sync_engine.d.ts +33 -1
- package/dist/modules/order/sync_engine.js +241 -73
- package/dist/modules/order/utils/math.d.ts +39 -1
- package/dist/modules/order/utils/math.js +83 -1
- package/dist/modules/order/utils/order.d.ts +181 -5
- package/dist/modules/order/utils/order.js +455 -9
- package/dist/modules/order/utils/system.d.ts +81 -1
- package/dist/modules/order/utils/system.js +331 -44
- package/dist/modules/order/utils/validate.d.ts +7 -1
- package/dist/modules/order/utils/validate.js +80 -3
- package/dist/modules/outcome.d.ts +54 -0
- package/dist/modules/outcome.js +51 -0
- package/dist/modules/settings_merge.d.ts +4 -0
- package/dist/modules/settings_merge.js +9 -0
- package/dist/modules/timing_policy.d.ts +82 -0
- package/dist/modules/timing_policy.js +244 -0
- package/dist/modules/types.d.ts +137 -0
- package/dist/modules/utils/asset_symbols.d.ts +13 -2
- package/dist/modules/utils/asset_symbols.js +21 -2
- package/dist/scripts/analysis_runner.d.ts +10 -0
- package/dist/scripts/analysis_runner.js +33 -0
- package/dist/scripts/analyze-credit.js +54 -17
- package/dist/scripts/analyze-orders.d.ts +4 -2
- package/dist/scripts/analyze-orders.js +115 -35
- package/dist/scripts/asset.d.ts +26 -0
- package/dist/scripts/asset.js +165 -0
- package/dist/scripts/bts_distribution.d.ts +1 -0
- package/dist/scripts/bts_distribution.js +194 -142
- package/dist/scripts/chart_command.d.ts +1 -1
- package/dist/scripts/chart_command.js +60 -86
- package/dist/scripts/chart_targets.d.ts +18 -0
- package/dist/scripts/chart_targets.js +48 -0
- package/dist/scripts/dw.js +1 -1
- package/dist/scripts/liquid.d.ts +24 -0
- package/dist/scripts/liquid.js +134 -0
- package/dist/scripts/rich_list.js +12 -16
- package/dist/scripts/test-credit-renewal.js +12 -5
- package/dist/scripts/token_distribution.d.ts +2 -0
- package/dist/scripts/token_distribution.js +132 -108
- package/dist/scripts/tv.js +1 -1
- package/dist/scripts/verify-browser-bundle.js +18 -0
- package/docs/COW_INVARIANTS.md +69 -10
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_PRICE_INVARIANT.md +5 -2
- package/docs/GRID_RECONCILE.md +36 -11
- package/docs/LOGGING.md +50 -4
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +177 -27
- package/docs/README.md +23 -2
- package/docs/WORKFLOW.md +12 -4
- package/docs/architecture.md +42 -5
- package/docs/developer_guide.md +25 -8
- package/modules/README.md +8 -1
- package/package.json +3 -1
- package/scripts/README.md +39 -7
- package/scripts/pdev.sh +14 -1
- package/scripts/pmain.sh +23 -8
- package/scripts/ptest.sh +7 -0
- package/tests/README.md +30 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# DEXBot vs DEXBot2 — Detailed Comparison Report
|
|
2
2
|
|
|
3
3
|
> **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
|
|
4
|
-
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.
|
|
4
|
+
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.1).
|
|
5
5
|
> **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
|
|
6
6
|
|
|
7
7
|
---
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
|
|
37
37
|
| Attribute | DEXBot (original) | DEXBot2 |
|
|
38
38
|
|---|---|---|
|
|
39
|
-
| **Release Track** | 1.0.0 | v1.
|
|
39
|
+
| **Release Track** | 1.0.0 | v1.7.1 |
|
|
40
40
|
| **Language** | Python 3.6+ | TypeScript 5.x |
|
|
41
41
|
| **Status** | Released 1.0.0, unmaintained | Active development |
|
|
42
42
|
| **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
|
|
@@ -776,13 +776,13 @@ Where:
|
|
|
776
776
|
|
|
777
777
|
| Metric | DEXBot | DEXBot2 |
|
|
778
778
|
|---|---|---|
|
|
779
|
-
| **Release Track** | 1.0.0 | v1.
|
|
779
|
+
| **Release Track** | 1.0.0 | v1.7.1 |
|
|
780
780
|
| **Active Since** | ~2018 | December 2025 |
|
|
781
|
-
| **Last Commit** | May 23, 2020 | 2026-11-
|
|
782
|
-
| **Total Commits** | 2281 | 2,
|
|
781
|
+
| **Last Commit** | May 23, 2020 | 2026-11-04 |
|
|
782
|
+
| **Total Commits** | 2281 | 2,492 (current HEAD, v1.7.1 line) |
|
|
783
783
|
| **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
|
|
784
784
|
| **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
|
|
785
|
-
| **Test Files** | 16 Python test files |
|
|
785
|
+
| **Test Files** | 16 Python test files | 367 `test_*.ts` files (350 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
|
|
786
786
|
| **Documentation** | Sphinx docs + README | 60+ Markdown docs plus Claw skills/references |
|
|
787
787
|
| **Strategies** | 3 + plugins | 1 |
|
|
788
788
|
| **Max Concurrent Bots** | Many (one process) | Many (one monolithic process by default; per-bot via `--isolated`/PM2) |
|
package/docs/EVOLUTION.md
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Executive Summary
|
|
4
4
|
|
|
5
|
-
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.
|
|
5
|
+
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.1 release.
|
|
6
6
|
|
|
7
7
|
### Key Milestones
|
|
8
8
|
- **Project Inception**: December 2, 2025
|
|
9
|
-
- **Growth Phase**: 2,
|
|
9
|
+
- **Growth Phase**: 2,492 commits over ~9 active months
|
|
10
10
|
- **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
|
|
11
|
-
- **Stability**: Progression from manual testing to a suite of
|
|
12
|
-
- **Releases**:
|
|
11
|
+
- **Stability**: Progression from manual testing to a suite of 353 automated test files (14 live tests skipped)
|
|
12
|
+
- **Releases**: 152 version entries in the changelog (v0.1.0 to v1.7.1)
|
|
13
13
|
|
|
14
14
|
> **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
|
|
15
15
|
> bug families, and lessons — lives in
|
|
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
|
|
|
149
149
|
|
|
150
150
|
## Version History
|
|
151
151
|
|
|
152
|
-
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-
|
|
152
|
+
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-04). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,385 (`v0.1.0..HEAD`) and 2,492 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
|
|
153
153
|
|
|
154
154
|
| Era | Commits | Theme |
|
|
155
155
|
|-----|--------:|-------|
|
|
@@ -176,11 +176,13 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
|
|
|
176
176
|
| v1.6.15 → v1.6.16 | 14 | Monolithic per-bot control routing, orientation-shared candle cache, market-profile orientation tolerance, chart log-axis hang fix + viewport-clipped draw hooks, Firefox Playwright chart suite, adapter-whitelist rename/copy sync, `dexbot rich` symbol canonicalization, doc reconciliation |
|
|
177
177
|
| v1.6.16 → v1.6.17 | 11 | Last-fill direction guard, placeable-slot spread planning with named stalls, chain-truth funding + fill-anchored boundary re-anchor, owed-crawl consumption, restart auth-before-stop with cleared vault secret, pool-priced LP-share collateral, AMA slowPeriod/slope retune, BTS & per-token supply distribution analyzers |
|
|
178
178
|
| v1.6.17 → v1.6.18 | 19 | Partial-fill re-anchor recovery (stale-evac skip, residual allow-list, crawl subsumption, rotation-only repair), rail-derived boundary + live fill/chain prices, edge-fill pivot exclusion, guard arity pinning with explicit re-arm, per-slot last-fill exclusion count, CLI `--flag=value` walker, `__test` seam guard, export-surface cleanup |
|
|
179
|
+
| v1.6.18 → v1.7.0 | 11 | Liquidity depth chart + `dexbot liquid`/`liq`/`liqu`, `dexbot asset` supply distribution shortcut, pool id/pool-token chart targets + shared spawn runner, case-insensitive asset lookup, asset-report chain-request cuts, shared CLI terminal output, orphan-fill attribution + dark-level revive, stale-grid re-buy discipline, pivot clock provenance & read-time TTL |
|
|
180
|
+
| v1.7.0 → v1.7.1 | 22 | One existence record per slot (life-cycle registry, unknown-is-never-gone), typed three-valued broadcast outcome, timing-window policy inventory, reconciliation interleaving fuzzer, one writer per life-cycle clock, serialized placement region with lease re-verification, fill-marker idempotency, forced-retreat gap evacuation + committed-geometry sweep, unknown-gap-geometry fix, replay-safe stranded-boundary repair, stability-ranked node selection + flap scoring, chain-account `<bot>` targets for `credit`/`order`, fee-adjusted pool depth chart with both spreads, atomic branch promotion preflight |
|
|
179
181
|
|
|
180
182
|
---
|
|
181
183
|
|
|
182
184
|
**Report Originally Generated**: February 19, 2026
|
|
183
|
-
**Last Updated**: November
|
|
184
|
-
**Total Commits**: 2,
|
|
185
|
-
**Date Range**: December 2, 2025 – November
|
|
185
|
+
**Last Updated**: November 4, 2026
|
|
186
|
+
**Total Commits**: 2,492
|
|
187
|
+
**Date Range**: December 2, 2025 – November 4, 2026
|
|
186
188
|
**Repository**: DEXBot2 (BitShares DEX Trading Bot)
|
|
@@ -805,4 +805,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
|
|
|
805
805
|
**TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
|
|
806
806
|
|
|
807
807
|
---
|
|
808
|
-
*Technical Reference for DEXBot2 v1.
|
|
808
|
+
*Technical Reference for DEXBot2 v1.7.1 release*
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# The Grid-Price Invariant
|
|
2
2
|
|
|
3
3
|
Status: **implemented; the emission check is BLOCKING**
|
|
4
|
-
Last code-reviewed against the v1.
|
|
4
|
+
Last code-reviewed against the v1.7.0 release baseline `5644aa3a` (2026-11-02).
|
|
5
5
|
|
|
6
6
|
## The invariant
|
|
7
7
|
|
|
@@ -202,7 +202,10 @@ Rules that keep the mirror honest:
|
|
|
202
202
|
genesis-mismatch verdicts erase the row through one shared drop path
|
|
203
203
|
(`AccountOrders.clearPersistedLastFillPivot`); an off-ladder row is a no-op
|
|
204
204
|
that falls back to the book seed. The snapped ladder level is restored, never
|
|
205
|
-
the raw float.
|
|
205
|
+
the raw float. The same TTL bounds the in-memory reference at READ time
|
|
206
|
+
(`resolveLastFillGuardReference` / `resolveFillProvenancedRow`), so the
|
|
207
|
+
geometry-bind "a fill or the TTL restores the side" contract does not need a
|
|
208
|
+
restart; a reference with no timestamp has an unknown age and never expires.
|
|
206
209
|
- **The generation wipes the pivot.** `initializeGrid` and
|
|
207
210
|
`rejectCorruptedGridSnapshot` call `resetLastFillPivot`, which clears the
|
|
208
211
|
full scalar family including the per-side mirrors (so the book seed's cold
|
package/docs/GRID_RECONCILE.md
CHANGED
|
@@ -22,7 +22,9 @@ Reconciliation aligns the bot's model with on-chain reality. It runs at startup
|
|
|
22
22
|
|
|
23
23
|
The reconcile runs from [`recalculateGrid`](../modules/order/grid.ts) during startup full-resync. **There is no per-attempt wall-clock race around the reconcile itself** — an outer timeout would fire mid-batch and orphan in-flight broadcasts (the duplicate-accumulation death spiral). The reconcile is bounded only by the 10-minute total resync safety net, and every internal chain read follows the shared guarded-read standard.
|
|
24
24
|
|
|
25
|
-
Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 execute outside that planning lock — holding it across RPC calls would block fills, sync, and divergence checks. Phase 2 holds the broadcasting single-flight marker, while the sync/apply paths it invokes follow the canonical lock hierarchy. No planning-phase grid lock spans a network operation.
|
|
25
|
+
Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 execute outside that planning lock — holding it across RPC calls would block fills, sync, and divergence checks. **Both phases run inside the exclusive placement region** (`manager.acquirePlacement('startup-reconcile')`, acquired before the chain snapshot is trusted and released after `stopBroadcasting`), so no other chain-mutating path can broadcast between Phase 1's plan and Phase 2's execution. Phase 2 additionally holds the broadcasting single-flight marker (which only defers fills), while the sync/apply paths it invokes follow the canonical lock hierarchy. No planning-phase grid lock spans a network operation.
|
|
26
|
+
|
|
27
|
+
The reconcile is not purely time-unbounded: besides the 10-minute total resync safety net it also waits up to 120 s for the placement region and re-reads the open-orders snapshot after acquiring it (planning from a snapshot older than the region is exactly the duplicate class). A reconcile that cannot get the region returns `null` and defers to the next sync cycle.
|
|
26
28
|
|
|
27
29
|
Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations are attempted — plans are logged but not executed.
|
|
28
30
|
|
|
@@ -80,8 +82,8 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
|
|
|
80
82
|
|
|
81
83
|
**Source:** `reconcileGridOrders()` Phase 1 in `grid_reconcile.ts`.
|
|
82
84
|
|
|
83
|
-
1. **Phantom order sanitization** (the `isOrderPlaced()` absence pass in `reconcileGridOrders()`): For each `isOrderPlaced()` order whose `orderId` is not in the chain snapshot, reset it to VIRTUAL with `skipAccounting` to prevent fund inflation.
|
|
84
|
-
- **
|
|
85
|
+
1. **Phantom order sanitization** (the `isOrderPlaced()` absence pass in `reconcileGridOrders()`): For each `isOrderPlaced()` order whose `orderId` is not in the chain snapshot, reset it to VIRTUAL with `skipAccounting` to prevent fund inflation. One absence-decision guard makes this safe:
|
|
86
|
+
- **In-flight deferral** (`LifecycleView.isInFlight()`, read through the slot with `readSlotLifecycle`): an order whose chain id was assigned/committed within the guard window, or whose lifecycle phase is still unresolved (`unknown`/`broadcasting` — a lost CREATE receipt, an ambiguous or unparseable read), may be live and merely missing from a lagging/truncated read — virtualizing it and re-creating would duplicate a real live order (the reconcile-timeout death-spiral root cause). It is skipped (deferred) rather than virtualized. The same predicate is the only absence guard in the sync pass-1 phantom cleanup and the fund recalibration sweep; asking a per-site subset is the bug class [ORDER_LIFECYCLE.md](ORDER_LIFECYCLE.md) exists to remove.
|
|
85
87
|
- **Ghost heuristic** (same absence pass): an order with `size <= 0` && `PARTIAL` (a known filled ghost) still passes through so known fills get cleaned up.
|
|
86
88
|
- Virtualization always uses `{ skipAccounting: true }` so startup cleanup never inflates `ChainFree`.
|
|
87
89
|
|
|
@@ -93,7 +95,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
|
|
|
93
95
|
- Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
|
|
94
96
|
- Detect grid-edge lock and plan a largest-order cancel
|
|
95
97
|
- Plan creates for remaining slots
|
|
96
|
-
- Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, edge slots last) —
|
|
98
|
+
- Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, edge slots last) — ONE selection feeds both the planOnly and the inline sink (the `excessPlans` list), so planning can never drift from execution; matched slots omit `releaseUntrackedFunds` (their funds are tracked on the grid slot). Every plan stamps the gap geometry from `resolveGapSlots` (never the raw `_gapSlots` field), which is also what the Phase-2 plan validator compares against
|
|
97
99
|
- Fork-kept **shelf orders** (live non-slot-N ids below the rail, e.g. `deep-*`) are never cancel candidates or reserve members — see [Shelf Orders](#shelf-orders-fork-kept-manual-orders)
|
|
98
100
|
- **Vacated-rail refill**: each PROCEEDING update whose vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side queues a refill CREATE in the same plan (`source startupVacatedRailRefill`) — skipped updates, ghost prices (lattice moved), in-band slots, and already-desired slots never refill; refill targets require VIRTUAL state with no `orderId`
|
|
99
101
|
|
|
@@ -115,7 +117,9 @@ snapshots. For every plan, `_startupCancelPlanStillCurrent()` requires:
|
|
|
115
117
|
|
|
116
118
|
- the target chain order still exists with its exact Phase-1 signature;
|
|
117
119
|
- a matched plan still owns the same chain order in the same live grid slot;
|
|
118
|
-
- planned type, slot price, boundary, and gap geometry still match
|
|
120
|
+
- planned type, slot price, boundary, and gap geometry still match (both sides
|
|
121
|
+
read the geometry through `resolveGapSlots`, so an unpublished `_gapSlots`
|
|
122
|
+
field cannot make every plan look stale); and
|
|
119
123
|
- an originally unmatched surplus is still not owned by any live slot.
|
|
120
124
|
|
|
121
125
|
Validation is per-plan: an earlier cancellation or unrelated order change does
|
|
@@ -127,7 +131,8 @@ remain unchanged.
|
|
|
127
131
|
|
|
128
132
|
**Fresh-placement grace (`TIMING.SURPLUS_CANCEL_GRACE_MS`, 15 min):** surplus
|
|
129
133
|
and cancel-only cancellations also skip any order whose `orderId` was placed
|
|
130
|
-
inside the grace window. The timestamp is written by
|
|
134
|
+
inside the grace window. The timestamp is written by the lifecycle write funnel
|
|
135
|
+
(and by `recordOrderPlacement` for manager-shaped callers) into
|
|
131
136
|
`manager._placedAt` and tested with `isFreshlyPlacedOrder`; the reconciler's CANCEL
|
|
132
137
|
actions are filtered by `COWRebalanceEngine.execute`, which drops the whole slot's
|
|
133
138
|
action group (a paired CANCEL+CREATE must not lose only its CANCEL, or the CREATE
|
|
@@ -207,7 +212,7 @@ Up to 3 batch attempts (`maxBatchAttempts = 3`). Each failure triggers a recover
|
|
|
207
212
|
|
|
208
213
|
### Phantom Orders via Reconcile
|
|
209
214
|
|
|
210
|
-
Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL order whose `orderId` is not found on-chain is reset to VIRTUAL with `skipAccounting`. The
|
|
215
|
+
Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL order whose `orderId` is not found on-chain is reset to VIRTUAL with `skipAccounting`. The in-flight deferral (`LifecycleView.isInFlight()`) protects in-flight broadcasts and unresolved receipts, and the ghost heuristic lets known fills pass. See [`developer_guide.md`](developer_guide.md#phantom-orders-prevention-defense-in-depth) for the full 3-layer defense.
|
|
211
216
|
|
|
212
217
|
### Shelf Orders (Fork-Kept Manual Orders)
|
|
213
218
|
|
|
@@ -225,6 +230,23 @@ Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen mast
|
|
|
225
230
|
|
|
226
231
|
Three of the six guarded emission sites are reconcile sites (`RECONCILE-CREATE`, `RECONCILE-UPDATE`, `STARTUP-CREATE` in `grid_reconcile_internal.ts`): every op reconcile emits is checked against the slot's genesis level and an off-grid emission is skipped, not broadcast — see [`GRID_PRICE_INVARIANT.md`](GRID_PRICE_INVARIANT.md). The coupling is bidirectional: the invariant guard's persistent-rejection escalation and the deferred-hold escalation both exit through the same structural resync (debounced reload → full reset) described here, and a full reset's update-first reconcile emits the rail's genesis level, so the guard does not block its own resolution.
|
|
227
232
|
|
|
233
|
+
### Fill Discipline (unsettled fills + last-fill placement)
|
|
234
|
+
|
|
235
|
+
Reconcile derives its window from the **master grid**, which is only as fresh as the last applied fill. Two gates keep a top-up from being derived from geometry that has not absorbed the latest trades (both added after the 2026-11-02 buy-higher incident: 9 buy-lower violations, 23.5% of the window's BTS):
|
|
236
|
+
|
|
237
|
+
- **Unsettled-fill gate** (`hasUnsettledFills`, `utils/system.ts`): while fills are queued (`_incomingFillQueue`), draining (`_deferredFillsPending`), in flight (`_fillBatchInFlight`) or owed a crawl (`_pendingFillCrawls`), `maybeRunTargetedDriftReconciliation` defers the targeted reconcile entirely and `_reconcileStartupSide` defers only the **window top-up** creates (1:1 repairs — cancelled-slot replacement, vacated-rail refill — still run). The master still counts filled slots as ACTIVE in that window, so a top-up would restore the expensive end of the rail.
|
|
238
|
+
- **Last-fill placement guard** (`isLastFillPlacementBlocked`, `utils/system.ts`): every reconcile placement (create in `_createOrderFromGrid` and the batch create path, plus the re-pricing relocation in `_prepareStartupUpdatePlan`) is refused when it sits on the wrong side of the last fill **or on the same grid level** (within half an increment — a slot level and its execution price differ by rounding). A same-price relocation is an adoption, not a placement, and is exempt. `_pickVirtualSlotsToActivate` applies the same predicate so the pick budget rolls to the next level down/up instead of being spent on a level the create would refuse — the filled level is never re-stamped same-side (the "rotate to bottom BUY / counter SELL" behaviour).
|
|
239
|
+
|
|
240
|
+
A fill whose order id no longer sits on an ACTIVE/PARTIAL slot is no longer dropped: `attributeUnmatchedFillToGrid` (shared by `SyncEngine._absorbUnmatchedFill` and the orphan-credit sweep in `dexbot_fill_runtime.ts`) records the **pivot + owed crawl from the real execution price**. It resolves the slot two ways — the chain id when a virtualised slot still owns it, otherwise the **genesis ladder level of the execution price** (the common case, because `virtualizeOrder` NULLS `orderId`; this is what the incident actually hit). A crawl is only owed by a HOLE, and a price outside the frozen rail is refused so a shelf order cannot arm the pivot. Without this the pivot stays on a stale, higher fill and the direction rule then permits re-buys above the market. The sweep is **replay-safe**: the processed-fill ledger is the authority, so attribution runs only when the accounting is not a `duplicate`. A replay already armed the pivot/crawl on its first delivery; re-attributing it re-records an old execution price (live: a 12-minute-old replay re-recorded four crawls and moved the boundary 165 → 169).
|
|
241
|
+
|
|
242
|
+
**The dark level it leaves behind is repaired too.** A slot virtualised while its order stayed live on chain reads as *not active* (`_countActiveOnGrid` needs ACTIVE/PARTIAL) while its order still counts in `chainCount`, so the side reports a shortfall it can never repair — and the planner sees a free level that already holds an order. Three pieces close that:
|
|
243
|
+
|
|
244
|
+
- `reviveVirtualSlotFromChain` re-materialises the slot **in place** (master-only, no broadcast) when the chain order is still live *and* rests at that slot's level. Wired into sync pass 1 (`sync-pass1-revive`) and reconcile Phase 1 (`startup-revive`). A rotation alias (chain order at another level) is never resurrected.
|
|
245
|
+
- Sync pass 1 also clears a **stale** id on a non-placed slot (`sync-clear-stale-id`) without booking a fill, so the level becomes a normal hole again.
|
|
246
|
+
- `validateCreateTargetSlots` treats *any* slot that still owns an `orderId` (any state) as `slot_occupied` (hard: the batch aborts), and a slot with a possibly-landed CREATE as the softer `slot_create_uncertain` (only that CREATE is withheld — an unknown outcome is not proof of a live order). `reconcileGrid` no longer treats a virtualised slot that owns an id as a hole. Together with the stale-id cleanup this blocks a **duplicate CREATE at a price that already holds an order** without stranding a level whose id was merely stale.
|
|
247
|
+
|
|
248
|
+
The spread-correction planner judges candidates with the same predicate as the placement guards (direction **plus same grid level**), so it no longer plans a create the broadcast guard will refuse; an unplaceable side reports the `last-fill-blocked` stall instead of burning a cycle. The COW build loop reaches the same verdict without a band term: it snaps the fill reference onto the ladder first (`resolveOnGridPivot`, tolerance one increment) and then applies the direction rule, so a target on the just-filled level equals the snapped pivot and is refused. A reference too far off-ladder to snap is judged raw (fail-open with a warning) rather than rewritten onto the grid — which is why the raw placement predicate is deliberately **not** wired into that lane (pinned by `tests/test_last_fill_guard.ts` PIVOT-004).
|
|
249
|
+
|
|
228
250
|
### Truncated-Read Ambiguity (since 1.4.8)
|
|
229
251
|
|
|
230
252
|
Every chain read feeding an absence/surplus decision goes through `readOpenOrdersGuarded`. A truncated snapshot is always unreadable. An empty snapshot is also unreadable at callers that set `deferEmpty: true`; the Phase-2 cancellation pre-read intentionally accepts a complete empty result, executes no plan, and leaves all remaining state for the normal reconcile paths:
|
|
@@ -243,12 +265,12 @@ The underlying rule is `INV-BROADCAST-004`: a capped `get_full_accounts` window
|
|
|
243
265
|
**`manager.ts` lock declaration** — canonical reference in [`developer_guide.md`](developer_guide.md#lock-ordering-for-deadlock-prevention).
|
|
244
266
|
|
|
245
267
|
```
|
|
246
|
-
Level 0:
|
|
247
|
-
Level
|
|
248
|
-
Level 4:
|
|
268
|
+
Level 0: _fillProcessingLock Level 0.5: placement region
|
|
269
|
+
Level 1: _divergenceLock Level 2: _syncLock
|
|
270
|
+
Level 3: _gridLock Level 4: _fundLock
|
|
249
271
|
```
|
|
250
272
|
|
|
251
|
-
Acquire in ascending level order only. AsyncLock is re-entrant (nested `acquire()` run directly, not queued).
|
|
273
|
+
Acquire in ascending level order only. AsyncLock is re-entrant (nested `acquire()` run directly, not queued); the placement region (`modules/order/placement_lock.ts`) is NOT re-entrant — it is a FIFO lease, and nested work must reuse the holder's lease (verified with `manager.isPlacementLeaseCurrent()`).
|
|
252
274
|
|
|
253
275
|
### Historical Correction (1.4.6)
|
|
254
276
|
|
|
@@ -287,6 +309,9 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
|
|
|
287
309
|
| `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
|
|
288
310
|
| `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
|
|
289
311
|
| `tests/test_edge_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
|
|
312
|
+
| `tests/test_grid_fill_discipline.ts` | Placement predicate (direction + same grid level), picker fall-through on both sides, create refusal before broadcast, window top-up deferral while fills are unsettled, slot revive (ACTIVE/PARTIAL + all refusals), CREATE occupancy gate, dark-level hole gate, spread planner/guard parity, orphan-sweep attribution |
|
|
313
|
+
| `tests/test_last_fill_pivot_rearm.ts` + `tests/test_last_fill_pivot_persistence.ts` | Re-arm on a new generation, timestamp provenance (the row that supplied the price also supplies the clock), and the pivot lifetime enforced at read time as well as at restore (expired rows neither arm nor re-arm; unknown age never expires) |
|
|
314
|
+
| `tests/test_fill_attribution_virtual_slot.ts` | Fill absorbed into a virtualised slot: pivot + owed crawl from the execution price (chain-id **and** ladder identity), unknown-order/no-stacking/dryRun cases, occupied-level and out-of-grid refusals, incident ladder refusals, `hasUnsettledFills` states |
|
|
290
315
|
| `tests/repro_phantom_orders.ts` | Phantom order prevention |
|
|
291
316
|
|
|
292
317
|
---
|
package/docs/LOGGING.md
CHANGED
|
@@ -252,7 +252,7 @@ Prefix tags used in log messages to help operators identify event types. To find
|
|
|
252
252
|
| `[STRATEGY]` | `order/strategy.ts` | Fee event cache and strategy decisions |
|
|
253
253
|
| `[RECONCILE]` | `order/utils/validate.ts` | Grid reconciliation ([GRID_RECONCILE.md](GRID_RECONCILE.md)) |
|
|
254
254
|
| `[RMS]` | `order/grid.ts`, `dexbot_maintenance_runtime.ts` | RMS structural-divergence checks: per-side `metric vs threshold → TRIGGER-RESYNC/no trigger` at `debug` (plus a `checks disabled` variant when the threshold is 0), reset line with threshold + breaching sides at `info` |
|
|
255
|
-
| `[GAP-EVAC]` | `order/utils/validate.ts`, `order/manager.ts`, `dexbot_startup_runtime.ts`, `dexbot_state_recovery.ts` | Stuck in-band (gap-band) order streak warnings, cancel-only evacuation teeth, persisted-streak restore counts |
|
|
255
|
+
| `[GAP-EVAC]` | `order/utils/validate.ts`, `order/manager.ts`, `dexbot_startup_runtime.ts`, `dexbot_state_recovery.ts`, `dexbot_maintenance_runtime.ts` | Stuck in-band (gap-band) order streak warnings, cancel-only evacuation teeth, persisted-streak restore counts, and the committed-geometry stranding sweep (post-commit + maintenance tick) |
|
|
256
256
|
| `[GRID-TYPE-CORRECT]` | `order/grid.ts` | One-time backfill retype of legacy empty slots to rail-typed holes on load |
|
|
257
257
|
| `[LAST-FILL-GUARD]` | `dexbot_cow_runtime.ts` | Last-fill-guard blocks plus gap-evacuation bypass allows/stale-stamp downgrades |
|
|
258
258
|
| `[RESTAMP-BUY]` | `dexbot_cow_runtime.ts` | BUY emitted at/above the last filled BUY pivot (guard bypass / unjudgeable pivot), counted not blocked (P2) |
|
|
@@ -313,14 +313,39 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
313
313
|
| `[SPREAD] No fundable side, but a rotation-only repair is available on <side>; using resting inventory (no new commitment).` | Both sides read zero free (or side selection returned no fundable side), but a promoted gap slot can be filled by rotating a resting order. Cross-asset side selection was not overridden when the market price itself was unavailable |
|
|
314
314
|
| `[LAST-FILL-GUARD] Skipping <type> UPDATE for <src> -> <dst>: stale gap-evacuation (...) — next plan re-evaluates` | A plan-build gap-evacuation stamp no longer matches the LIVE boundary/gap (or the live probe is not violation-reducing). The op is dropped instead of falling through to the direction-only last-fill guard; the next plan/reconcile owns the move |
|
|
315
315
|
| `[LAST-FILL-GUARD] Final gate dropping stale gap-evacuation ...` | The final pre-broadcast pivot gate also refuses a stamp whose live geometry went stale after op-building, even when the destination price itself is direction-legal |
|
|
316
|
+
| `[LAST-FILL-GUARD] Stamped evacuation for <src> -> <dst> is stale under live boundary B/gap G, but the live rails already conflict (maxBuy=X > minSell-gap-1=Y) — the retreat this batch commits is forced, so the evacuation proceeds` | Forced-retreat allowance (`liveRailsConflictWithGap`). The stale-stamp refusal assumes the live boundary survives the commit; when the live rails already overlap, NO boundary can host both rails with the gap band, so the batch's retreat is the only consistent geometry and refusing the evacuation is what permanently strands the order in the band (spread collapse). The same allowance is applied by the build loop and by the final pivot gate |
|
|
317
|
+
| `[LAST-FILL-GUARD] Final gate keeping gap-evacuation ... despite live boundary B/gap G: the live rails already conflict ...` | The final-gate mirror of the forced-retreat allowance above (keeping the op is violation-reducing, not a guard bypass) |
|
|
318
|
+
| `[GAP-EVAC] N live order(s) stranded inside the spread band (boundary B, gap G): <slot(side), ...> — scheduling a fill-less re-plan to evacuate (<context>)` | Post-commit / maintenance sweep: live rail orders are resting inside the committed band, so the real top-of-book spread is narrower than the configured one. A fill-less COW re-plan runs against the committed geometry (where the evacuation stamp validates) — plans are fill-driven, so a quiet market would otherwise never heal. Rate-limited (60s) per bot; repeats inside the window log at `debug` |
|
|
319
|
+
| `[GAP-EVAC] ... repair cooldown active (Ns left); teeth queued=N` | The sweep found the same stranding again inside the repair cooldown window; the cancel-only teeth remain the last resort |
|
|
320
|
+
| `[COW] Holding N gap-evacuation cancel(s) back from the pre-batch drain: this batch rotates the same chain order (the rotation IS the evacuation)` | A cancel-only evacuation queued for a chain order the current batch rotates. Draining it first would cancel the batch's own rotation source and the UPDATE batch would be rejected pre-broadcast (`target(s) missing on chain` → structural resync). The entry is restored after the drain and dropped as stale once the slot no longer owns the order |
|
|
321
|
+
| `[GAP-EVAC] Spread band clean: cleared N resolved in-band streak(s)` | The sweep found no live order inside the committed band and dropped N resolved ledger entries, so a future return to the band re-arms instead of inheriting a stale cycle count. Logged only when something was actually cleared |
|
|
322
|
+
| `[GAP-EVAC] ... unknown geometry` (silent) | With no committed boundary (or no known band width) the sweep returns without touching the ledger or the pipeline: absent geometry is not health, it is unknown |
|
|
323
|
+
| `[GAP-EVAC] ... no fill-less re-plan available on this path; teeth queued=N` | The stranding is real but this bot shape cannot run a fill-less rebalance (no `performSafeRebalance`/`updateOrdersOnChainBatch`); the cancel-only teeth own the repair |
|
|
324
|
+
| `[BOUNDARY] restore boundary=B sellStart=S gapSlots=G spreadCount=N\|? activeBuy=... activeSell=...` | Boundary restore telemetry. `gapSlots` is the resolved geometry (`_gapSlots ?? config-derived`) — never `0` for an unpublished band — and `spreadCount=?` means the grid has not been loaded/created yet, so no spread metric exists. A literal `gapSlots=0 sellStart=B+1` now always means a genuinely 0-wide band, not an initialization window |
|
|
316
325
|
| `[SPREAD-CORRECTION] <side> rail is OVERSUBSCRIBED: virtual reservation X exceeds chain free Y by Z — no correction can be funded until the rail is re-sized ...` | `availableFund` is `free − virtual`, so an oversubscribed rail reads 0 while the side still holds inventory. The watchdog escalates this on its short fund window |
|
|
317
326
|
| `[SPREAD-STALE] Spread out of tolerance for Nmin ... (outOfSpread=..., stall=...)` | Persistence warn with the last stall cause; the clock survives single in-tolerance readings and the terminal cases escalate early: `stall=last-fill-blocked` (sell window behind the last fill) on the 10-minute geometry window, a rail oversubscription on the 5-minute fund window |
|
|
318
327
|
| `[SPREAD-STALE] ... (sell window behind the last fill — re-centering)` | The `last-fill-blocked` geometry bind is escalating; placement cannot repair it, a re-center can |
|
|
319
|
-
| `[SPREAD-STALE] Still out of tolerance Nmin after re-centering on fill pivot P: the pivot is outside this generation's placeable side, so a re-center cannot clear it. A fill ... or pivot expiry restores the side; no further re-center will be requested for this pivot.` | Churn cap: a re-center does not move the pivot, so the same fill gets ONE re-center (`_lastGeometryResyncPivotKey`). Logged once per pivot; the same-side rail stays blocked until a fill or the 24h pivot TTL, by design |
|
|
320
|
-
| `[BOUNDARY] Re-anchored from the last fill: SELL filled at slot 153 (0.447640); boundary 146 -> 149 so the fill sits outside its own window` | The window was behind the fill and a ±1 crawl cannot catch up; the fill now anchors the geometry. The anchor is the current fill batch's extremum for that side (max SELL / min BUY), not the last-processed pivot. Refusals stay silent (cold/off-ladder/ceiling-clamped/unsafe preconditions); the fill's own PARTIAL residual is allow-listed, so a partial fill does not deadlock the repair |
|
|
328
|
+
| `[SPREAD-STALE] Still out of tolerance Nmin after re-centering on fill pivot P: the pivot is outside this generation's placeable side, so a re-center cannot clear it. A fill ... or pivot expiry restores the side; no further re-center will be requested for this pivot.` | Churn cap: a re-center does not move the pivot, so the same fill gets ONE re-center (`_lastGeometryResyncPivotKey`). Logged once per pivot; the same-side rail stays blocked until a fill or the read-time 24h pivot TTL, by design |
|
|
329
|
+
| `[BOUNDARY] Re-anchored from the last fill: SELL filled at slot 153 (0.447640); boundary 146 -> 149 so the fill sits outside its own window` | The window was behind the fill and a ±1 crawl cannot catch up; the fill now anchors the geometry. The anchor is the current fill batch's extremum for that side (max SELL / min BUY), not the last-processed pivot. Refusals stay silent (cold/off-ladder/ceiling-clamped/unsafe preconditions); the fill's own PARTIAL residual at the ANCHOR slot is allow-listed, so a partial fill does not deadlock the repair |
|
|
330
|
+
| `[BOUNDARY] Re-anchor accepted as a violation-reducing repair: boundary X -> Y strands fewer placed orders than the committed geometry (placed_order_in_band)` | The strict gate refused the candidate only because older GAP-EVAC strands are still in band; the move strands STRICTLY FEWER than the committed boundary, so it is accepted. Equal counts and structural refusals (crossed book/ceiling) stay closed. The rule lives in ONE helper (`boundaryMoveReducesStrands`) shared with the rail clamp — see `[COW] Boundary rail-derived` below. The promotion-side counterpart is the in-band absorption logged as `[SPREAD-CORRECTION] N gap slot(s) available for boundary promotion` |
|
|
331
|
+
| `[PLACEMENT] Force-releasing stale placement region held by <kind> for Ns (watchdog Ms); fills/rebalances must not stay parked` | The exclusive placement region outlived `TIMING.PLACEMENT_STALE_CLEAR_MS` (generous: above the longest observed reconcile), so the lease is force-released; the holder's later `release()` becomes a no-op (token guard). This watchdog is the ONE authority that tears a hung region down — when the region also still holds a stale broadcast refcount, it clears that too (`[PLACEMENT] Also clearing the stale broadcast region ...; one teardown for one hung region`) |
|
|
332
|
+
| `[COW] Placement lease was force-released while this batch was in flight (stale-region watchdog); aborting this batch instead of broadcasting without the region.` | The owner re-verifies its own lease with `isPlacementLeaseCurrent()` before broadcasting — the mirror of the nested drain's check. Aborting is the fail-closed answer: another path may own the region by now, and broadcasting anyway re-opens the duplicate window the teardown existed to avoid |
|
|
333
|
+
| `Startup reconcile: placement lease was force-released after planning (stale-region watchdog); discarding the plan instead of broadcasting without the region.` | The reconcile's own lease-liveness gate before Phase 2 (the mirror of `[COW] Placement lease was force-released ...`). Phase 1 touched only the master, so the plan is dropped with no chain effect; the next cycle re-reads the chain after re-acquiring the region |
|
|
334
|
+
| `[PLACEMENT] Watchdog skipped: region held by <kind> for Ns, but the pipeline is still making progress (in flight Ms)` | A bot-level batch/recovery counter younger than the placement bound proves the region is live (e.g. a long create-group reconcile), so nothing is torn down. Only a counter past the same bound is treated as part of the hung region |
|
|
335
|
+
| `[COW] <stage>: exclusive placement region unavailable (timeout/shutdown); aborting this batch instead of overlapping another placement path.` | Another chain-mutating path owns the region and the bounded wait expired. The batch is aborted (never broadcast unprotected) and retried on the next cycle |
|
|
336
|
+
| `Startup reconcile: exclusive placement region unavailable (timeout/shutdown); deferring to the next sync cycle.` | The reconcile could not serialize with a live placement path; it returns without mutating anything |
|
|
337
|
+
| `[DUST] Deferring dust cancels: exclusive placement region busy or shutting down` | Dust cancels mutate the chain, so they need the region. Deferral (not a bypass) is the contract; the next fill batch / maintenance tick retries |
|
|
338
|
+
| `[RESIDUAL] Deferring N residual cancel(s): exclusive placement region busy or shutting down` | Sub-dust residual cancels after a full fill are deferred to the next sync/reconcile instead of racing a live batch |
|
|
339
|
+
| `[MAINT] Deferring price-correction drain: exclusive placement region busy or shutting down` / `[FILL-QUEUE] Deferring price-correction drain: ...` / `[COW] Draining N pending correction(s) before batch` | The correction drain runs inside the region (nested callers pass the holder's lease, verified with `isPlacementLeaseCurrent`). A deferred drain keeps its queued entries for the next tick; the fill consumer and the maintenance tick report the same deferral under their own tags |
|
|
340
|
+
| `[BROADCAST] Stale-flag watchdog skipped: placement region still held by <kind> for Ns` | The refcount watchdog refuses to clear a broadcast region a live placement lease still owns — the mirror rule of the placement watchdog's pipeline-progress check |
|
|
341
|
+
| `[REBUILD] Structural rebuild started (<reason>); fill-driven rebalances deferred` | A trigger-file/startup rebuild owns placement and update-first repair; fill-driven COW rebalances defer instead of re-planning against the order-id-less master |
|
|
342
|
+
| `[SAFE-REBALANCE] Deferred: placement region held by <kind>; rebalance retries after it ends` | A fill-driven rebalance found the region held (reconcile/drain/dust/cancel/swap). The owed fill crawls stay recorded and the region-end hook reschedules the no-fill rebalance |
|
|
343
|
+
| `[FILL-DEDUP] Fill <key>: N/M base units already absorbed by sync pass 1; the transition will not shrink them again` | The open-orders pass resized the slot from the same post-fill snapshot. The explicit applied amount (never the legacy boolean) drives the remainder, so the trade's pays/receives are still booked while the size is released exactly once |
|
|
344
|
+
| `[COW] Pending-broadcast entry <fp> is Ns old but no sync has completed since it was recorded; keeping it (fail-closed) until a caught-up read` / `[COW] Dropped expired pending-broadcast entry ...` | The single pending-broadcast liveness authority (`getLivePendingBroadcasts`): TTL, or TTL + a successful sync after the record, or the 2× hard cap. Every reader (COW guard, reconcile CREATE, reconcile surplus sweep, crossing candidates) obeys it |
|
|
321
345
|
| `[FILL-PIVOT] pivot=... buy=... sell=... n=N src=full/direct` (+ `edge-skipped=K` when present) | One line per fill batch: the LAST-FILL-GUARD pivot after the batch. `edge-skipped=K` means K edge-pinned insurance fills were ignored — they never arm the pivot, so they can never drive the re-anchor |
|
|
322
346
|
| `[FILL-PIVOT] K edge-pinned fill(s) ignored — the guard pivot and the boundary anchor stay on the last window trade` | Edge-only batch: nothing armed, which is the point |
|
|
323
|
-
| `[LAST-FILL-GUARD] Re-armed on the new generation: 0.447640(SELL) from the last real fill (age Ns) — the guard survives a rebuild by design` | A grid rebuild dropped the generation-bound pivot and re-armed it explicitly from the bot-scoped last-market-fill row (`rearmLastFillPivotFromMarketFill`). Provenance stays `fill`; the timestamp is the original fill's |
|
|
347
|
+
| `[LAST-FILL-GUARD] Re-armed on the new generation: 0.447640(SELL) from the last real fill (age Ns) — the guard survives a rebuild by design` | A grid rebuild dropped the generation-bound pivot and re-armed it explicitly from the bot-scoped last-market-fill row (`rearmLastFillPivotFromMarketFill`). Provenance stays `fill`; the timestamp is the original fill's, taken from the SAME row that supplied the price (a book-seeded live pivot never lends its clock) |
|
|
348
|
+
| `[LAST-FILL-GUARD] Pivot expired (age Ns > TTL Ms) — guard re-arms on the next fill` | Read-time pivot lifetime: a fill reference older than `GRID_LIMITS.LAST_FILL_PIVOT_TTL_MS` no longer arms the guard, with or without a restart. Logged once per expired value, so the geometry-bind re-center cap cannot silently park a side forever |
|
|
324
349
|
| `[COW-CROSS-GUARD] CREATE SELL for slot-N at P sits on the crossing side of the floor F (the planner refuses these; a generic refill does not) — it executes at the best available price, so this is a taker-fee observation, not a veto. Once per batch.` | Planner/execution asymmetry made visible: `doesNotCrossMarket` is planner-only, so a reconcile/re-fill CREATE can be a taker fill. Never blocking by design (a hard veto would re-open the counter-order deadlock) |
|
|
325
350
|
| `[COW] Boundary rail-derived: planned X, held Y -> Z (maxBuy=..., minSell=...) — keeping placed counter orders on their rails` | The batch's own rails disagree with the boundary a refill hold would commit. `deriveRailBoundary` clamps to `maxBuy <= boundary <= minSell-gap-1`, so a fill's counter order carries the boundary instead of being stranded in the band. The refill hold still applies when nothing was placed above the committed boundary. The reason suffix `(N stray rail order(s) ignored)` names master orders parked on the wrong side (refused-commit adoption / stranded hold), and `window=K` reports the grid's claimed window size |
|
|
326
351
|
| `[COW] Boundary rail-derived: unusable (rail-crossed ... / rail-exceeds-grid ...); keeping Z` | The live/placed rails already overlap or cannot fit the gap band. Fail closed: keep the previous boundary and let GAP-EVAC / the next plan resolve the offending order (never self-legalize a crossed rail) |
|
|
@@ -334,6 +359,27 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
334
359
|
|
|
335
360
|
---
|
|
336
361
|
|
|
362
|
+
## Fill discipline at the reconcile / placement sites
|
|
363
|
+
|
|
364
|
+
Added with the buy-higher fix (2026-11-02: 9 buy-lower violations, 23.5% of the
|
|
365
|
+
window's BTS). See `docs/GRID_RECONCILE.md#fill-discipline-unsettled-fills--last-fill-placement`.
|
|
366
|
+
|
|
367
|
+
| Message | Meaning |
|
|
368
|
+
|---------|---------|
|
|
369
|
+
| `[SYNC] Fill for order <id> attributed to <slot> via chain-id\|ladder (<side> @ P): pivot recorded + owed boundary crawl` (suffix `(slot still holds a live order: no crawl)` when applicable) | The fill's order id identified no ACTIVE/PARTIAL slot. `via=chain-id` means a virtualised slot still owned the id; `via=ladder` means the id was already cleared (every virtualisation NULLS it) and the **execution price** resolved the level through the genesis ladder. The pivot moves to that price unless the writer skips the fill as edge-pinned (a wick on the static floor/ceiling must never arm the guard — the line then reads `pivot NOT armed`); the crawl is only owed by a HOLE the grid owns, because an occupied level cannot be re-placed. A price outside the frozen rail is refused here, so a shelf/manual order can never arm the pivot. Previously this was a silent `ignored: order not found in active grid` at `debug` — the stale pivot it left behind is what let the reconciler re-buy above the market |
|
|
370
|
+
| `[SYNC] Revived virtualised slot <slot>: its chain order <id> is still live (<side> @ P, size S) while the slot was VIRTUAL — re-materialised in place (no broadcast), so window accounting counts it again` | The dark-level repair: a slot virtualised while its order stayed on chain (phantom cleanup on a truncated read, refused-commit adoption) is invisible to window accounting while its order still counts in `chainCount`. Master-only revive, only when the chain order rests at that slot's level — a rotation alias (different level) is never resurrected |
|
|
371
|
+
| `[SYNC] Revive of virtualised slot <slot> rejected — slot keeps its VIRTUAL state` | `_applyOrderUpdate` refused the revive; nothing is booked and the next sync re-detects |
|
|
372
|
+
| `[SYNC] Cleared stale chain id <id> on <slot> (slot was VIRTUAL): the order is gone from the chain read, so the level is a normal hole again — no fill booked` | A non-placed slot carried an id whose order is absent from a trusted read. The id is dropped WITHOUT booking a fill (inventing one would arm the pivot and crawl for a trade that never happened). This is what keeps the CREATE occupancy gate from stranding a level |
|
|
373
|
+
| (same `[SYNC] Revived virtualised slot ...` line) | Emitted by BOTH call sites: sync pass 1 (`sync-pass1-revive`) and reconcile Phase 1 (`startup-revive`, before the plan is derived so the side no longer reads a phantom shortfall) |
|
|
374
|
+
| `[TARGETED-SYNC] Deferring <context> reconciliation: <reason> — the rail must absorb the fills before it is topped up` | A targeted reconcile was requested while fills are queued/draining/in flight/owed a crawl. No cooldown is stamped, so it retries as soon as they settle |
|
|
375
|
+
| `Startup: Deferring N <side> window top-up create(s): <reason> — the rail must absorb the fills before it is refilled` | Same gate on the reconcile side. 1:1 repairs (cancelled-slot replacement, vacated-rail refill) are still planned; only the window top-up waits |
|
|
376
|
+
| `Startup: <side> pick skipped N slot(s) on the wrong side of the last fill (pivot P); picked X/Y` | The activation picker refused candidates the placement guard would block, so the pick rolls to the next level down (BUY) / up (SELL). `picked X/Y` below target means the rail had no legal level left this cycle |
|
|
377
|
+
| `[_createOrderFromGrid] SKIP (LAST-FILL-GUARD): Create for <slot> at P on the wrong side of the last fill F (<reason>); the rail must crawl before this level is refilled` | A reconcile create was refused before any broadcast. `reason` is `direction` (wrong side) or `same-level` (within half a grid step — a slot level and its execution price differ by rounding) |
|
|
378
|
+
| `Startup: Skip create <label> (LAST-FILL-GUARD) - price P ...` | Same refusal in the batch create path |
|
|
379
|
+
| `[STARTUP-LAST-FILL-GUARD] Skipping relocation update <orderId> -> <slot>: target ... is on the wrong side of the last fill F (<reason>); re-align on the next reconcile cycle` | A re-pricing relocation is a placement too. Same-price relocations are adoptions and are exempt |
|
|
380
|
+
|
|
381
|
+
---
|
|
382
|
+
|
|
337
383
|
## Fill History Scan Profiling
|
|
338
384
|
|
|
339
385
|
The `Subscriptions` logger emits `fetchFillHistoryEntries: maxPages (X) reached` at `debug` level when the fill-history scan reaches its configured page cap. On a busy account this is **normal** — the scan simply catches up over multiple polling cycles rather than in a single pass.
|