dexbot 1.6.17 → 1.7.0
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 +58 -0
- package/README.md +24 -18
- package/analysis/README.md +105 -12
- package/analysis/ama_fitting/README.md +2 -2
- package/analysis/bot_fitting/README.md +3 -3
- 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/analyze_args.d.ts +2 -1
- 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 +325 -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/fills_source.d.ts +1 -8
- package/dist/analysis/fills_source.js +1 -1
- package/dist/analysis/grid_correction_check.d.ts +9 -6
- package/dist/analysis/grid_correction_check.js +56 -64
- 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 +523 -0
- package/dist/analysis/liquidity/liquidity_depth_model.d.ts +141 -0
- package/dist/analysis/liquidity/liquidity_depth_model.js +230 -0
- package/dist/analysis/liquidity/liquidity_view.d.ts +38 -0
- package/dist/analysis/liquidity/liquidity_view.js +55 -0
- package/dist/analysis/math_utils.d.ts +1 -1
- package/dist/analysis/trade_profitability.d.ts +1 -1
- package/dist/analysis/trade_profitability.js +2 -1
- package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
- package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
- package/dist/dexbot.js +74 -169
- package/dist/market_adapter/cli_args.d.ts +6 -1
- package/dist/market_adapter/cli_args.js +16 -2
- package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
- package/dist/market_adapter/core/kibana_candles.js +3 -1
- package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
- package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
- package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
- package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
- package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
- package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
- package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
- package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
- package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
- package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
- package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
- package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
- package/dist/market_adapter/inputs/window_cache.js +14 -1
- package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
- package/dist/market_adapter/lp_chart_runner.js +3 -1
- package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
- package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
- package/dist/market_adapter/market_adapter.d.ts +10 -2
- package/dist/market_adapter/market_adapter.js +10 -11
- package/dist/market_adapter/utils/chain.d.ts +2 -3
- package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
- package/dist/market_adapter/utils/file_json_cache.js +3 -1
- package/dist/market_adapter/utils/file_lock.js +1 -1
- package/dist/market_adapter/utils/native_history.d.ts +7 -3
- package/dist/market_adapter/utils/native_history.js +3 -1
- package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
- package/dist/modules/asset_lookup.d.ts +25 -0
- package/dist/modules/asset_lookup.js +75 -0
- package/dist/modules/bots_file_lock.d.ts +2 -2
- package/dist/modules/bots_file_lock.js +2 -2
- 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.js +6 -3
- package/dist/modules/dexbot_class.d.ts +8 -0
- package/dist/modules/dexbot_class.js +10 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
- package/dist/modules/dexbot_cow_runtime.js +475 -47
- package/dist/modules/dexbot_credential_client.d.ts +5 -0
- package/dist/modules/dexbot_fill_runtime.js +20 -0
- package/dist/modules/dexbot_maintenance_runtime.js +71 -9
- package/dist/modules/dexbot_startup_runtime.js +7 -1
- package/dist/modules/graceful_shutdown.d.ts +2 -2
- package/dist/modules/graceful_shutdown.js +2 -2
- package/dist/modules/launcher/runtime_entry.d.ts +21 -1
- package/dist/modules/launcher/runtime_entry.js +36 -1
- package/dist/modules/launcher/runtime_mode.d.ts +4 -3
- package/dist/modules/liquidity_pool_ref.d.ts +32 -0
- package/dist/modules/liquidity_pool_ref.js +116 -0
- package/dist/modules/node_manager.d.ts +1 -1
- package/dist/modules/node_manager.js +1 -1
- package/dist/modules/order/accounting.js +2 -1
- package/dist/modules/order/export.d.ts +2 -2
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/grid.d.ts +19 -14
- package/dist/modules/order/grid.js +269 -61
- package/dist/modules/order/grid_reconcile.js +27 -2
- package/dist/modules/order/grid_reconcile_internal.js +94 -15
- package/dist/modules/order/index.d.ts +24 -4
- package/dist/modules/order/manager.d.ts +12 -0
- package/dist/modules/order/manager.js +44 -11
- package/dist/modules/order/strategy.js +22 -2
- package/dist/modules/order/sync_engine.d.ts +32 -1
- package/dist/modules/order/sync_engine.js +209 -26
- package/dist/modules/order/utils/math.d.ts +26 -10
- package/dist/modules/order/utils/math.js +54 -14
- package/dist/modules/order/utils/order.d.ts +158 -11
- package/dist/modules/order/utils/order.js +434 -21
- package/dist/modules/order/utils/system.d.ts +136 -30
- package/dist/modules/order/utils/system.js +465 -63
- package/dist/modules/order/utils/validate.d.ts +1 -0
- package/dist/modules/order/utils/validate.js +37 -3
- package/dist/modules/storage/index.d.ts +3 -2
- package/dist/modules/storage/index.js +3 -2
- package/dist/modules/types.d.ts +14 -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-orders.js +2 -1
- 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 +52 -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/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/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
- package/docs/COW_INVARIANTS.md +21 -11
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
- package/docs/GRID_PRICE_INVARIANT.md +28 -5
- package/docs/GRID_RECONCILE.md +25 -5
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +37 -2
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +124 -36
- package/docs/README.md +1 -1
- package/docs/WORKFLOW.md +3 -1
- package/docs/architecture.md +115 -13
- package/docs/developer_guide.md +12 -0
- package/market_adapter/README.md +9 -4
- package/modules/README.md +23 -15
- package/package.json +6 -3
- package/scripts/README.md +23 -7
|
@@ -27,7 +27,7 @@ $$Available = \max(0, \text{ChainFree} - \text{Virtual} - \text{FeesOwed} - \tex
|
|
|
27
27
|
**Critical Invariants:**
|
|
28
28
|
1. **Virtual represents Plan.** Orders remain in `Virtual` only while they are truly uncommitted. As soon as they move to `ACTIVE`, they move to `Committed` (Chain), even if the blockchain transaction is still in flight. This maintains the `Total = Free + Committed` invariant.
|
|
29
29
|
2. **Available Funds = True Spending Power.** This formula is the single source of truth for how much capital can be deployed immediately.
|
|
30
|
-
3. **Non-BTS pair reservation.** When neither asset is BTS, the formula adds an extra proportional deduction: any BTS fee-budget deficit (formula budget minus `funds.btsBalance.free`) is split across `buyFree` + `sellFree` proportional to each side's free balance, and the side's share is subtracted from `Available`. See `calculateAvailableFundsValue()` in `modules/order/utils/math.ts
|
|
30
|
+
3. **Non-BTS pair reservation.** When neither asset is BTS, the formula adds an extra proportional deduction: any BTS fee-budget deficit (formula budget minus `funds.btsBalance.free`) is split across `buyFree` + `sellFree` proportional to each side's free balance, and the side's share is subtracted from `Available`. See `calculateAvailableFundsValue()` in `modules/order/utils/math.ts`.
|
|
31
31
|
|
|
32
32
|
### 1.3 Capital Allocation Pipeline
|
|
33
33
|
|
|
@@ -52,7 +52,7 @@ funds.allocated → _getSizingContext() (budget for spread correction)
|
|
|
52
52
|
**Key points:**
|
|
53
53
|
- `botFunds` percentage applies to **total** capital (free + locked in orders), not just free. A bot at `"50%"` gets half of everything, not half of what's currently idle.
|
|
54
54
|
- `funds.allocated` is the ceiling for each side. Existing orders already consume part of it; the remaining free portion is available for new placements.
|
|
55
|
-
- The downstream `applyBotFundsAllocation()` (`manager.ts
|
|
55
|
+
- The downstream `applyBotFundsAllocation()` (`order/manager.ts`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
|
|
56
56
|
- `funds.available[side] = max(0, chainFree − virtualReservation − fees)`. When the empty rail already reserves more than the chain holds, this reads 0 while the side still holds inventory — the **rail oversubscribed** state. Spread correction names it in the log, flags it on the manager, and the out-of-spread watchdog escalates it on `TIMING.SPREAD_STALE_FUND_ESCALATE_MS`: the durable repair is re-sizing the rail from chain truth (structural re-center).
|
|
57
57
|
- For a KNOWN candidate set the reservation must not veto the placement it describes: `deriveChainTruthFundBudget` (`utils/math.ts`) re-derives `min(chainFree, min(virtualReservation, Σ candidate ideals))` when `available` reads 0, so an over-sized projection cannot deadlock placement. The chain rejects an over-commit at broadcast, so this cannot spend more than exists.
|
|
58
58
|
|
|
@@ -69,7 +69,7 @@ Mixed BUY/SELL batches are validated per asset using a signed-delta **peak** run
|
|
|
69
69
|
|
|
70
70
|
#### Implementation Location
|
|
71
71
|
|
|
72
|
-
File: `modules/dexbot_cow_runtime.ts` — `validateOperationFunds()
|
|
72
|
+
File: `modules/dexbot_cow_runtime.ts` — `validateOperationFunds()`, called from the COW batch broadcast path.
|
|
73
73
|
|
|
74
74
|
```javascript
|
|
75
75
|
// Per-asset peak requirement vs. quantized chain-free snapshot.
|
|
@@ -114,7 +114,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
114
114
|
|
|
115
115
|
#### Gap-Slot Batch Fill Processing
|
|
116
116
|
|
|
117
|
-
**Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders`
|
|
117
|
+
**Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` once per chunk to run the full rebalance pipeline.
|
|
118
118
|
|
|
119
119
|
**Batch Sizing Algorithm**: Batch size is derived from the grid gap-slot count + 1 (`DEXBot._getGapSlotBatchSize`): a queue depth at or below gapSlots+1 is processed as one unified batch; deeper queues are chunked into repeated batches of gapSlots+1 (the last chunk may be smaller). The same gapSlots+1 size caps order operations per broadcast transaction (oversized op batches are split into sequential broadcasts).
|
|
120
120
|
|
|
@@ -125,7 +125,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
125
125
|
**Per-Batch Execution**:
|
|
126
126
|
|
|
127
127
|
1. **Peek & Pop**: Check `_incomingFillQueue`, pop up to N fills (batch size)
|
|
128
|
-
2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts
|
|
128
|
+
2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts`)
|
|
129
129
|
- Proceeds credited directly to `chainFree` (via `adjustTotalBalance`)
|
|
130
130
|
- Same-order fill batching (sync_engine Phase 6 cumulative transition) aggregates multiple fill transitions on one order before a single rebalance
|
|
131
131
|
- All proceeds immediately available to next rebalance cycle (not split across cycles)
|
|
@@ -139,7 +139,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
139
139
|
|
|
140
140
|
**Result**: 29 fills now processed in ~8 broadcasts (~24s) instead of 29 broadcasts (~90s).
|
|
141
141
|
|
|
142
|
-
**Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts
|
|
142
|
+
**Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
|
|
143
143
|
|
|
144
144
|
#### Grid Regeneration Trigger (Available Funds Ratio — bidirectional)
|
|
145
145
|
|
|
@@ -401,7 +401,7 @@ targetSlot.orderId = newOrderId;
|
|
|
401
401
|
|
|
402
402
|
### 3.6 Orphan-Fill Deduplication & Double-Credit Prevention
|
|
403
403
|
|
|
404
|
-
**Location**: `modules/dexbot_class.ts` — constructor, `_recoverExplicitStaleOrders()
|
|
404
|
+
**Location**: `modules/dexbot_class.ts` — constructor, `_recoverExplicitStaleOrders()`; orphan-fill guard in the fill drain loop and pruning pass after each cycle now live in `modules/dexbot_fill_runtime.ts` (the orphan-fill guard and the post-cycle pruning pass).
|
|
405
405
|
|
|
406
406
|
#### Stale-Cleaned Order ID Tracking with TTL + Recycled-Slot Guard
|
|
407
407
|
|
|
@@ -558,7 +558,7 @@ These are deducted from the *proceeds* of a fill.
|
|
|
558
558
|
|
|
559
559
|
For BTS fees, the system returns a structured object (not a simple number) with multiple fields for accounting precision.
|
|
560
560
|
|
|
561
|
-
**Location**: `modules/order/utils/math.ts::getAssetFees()
|
|
561
|
+
**Location**: `modules/order/utils/math.ts::getAssetFees()`. The fee cache itself is populated by `modules/order/utils/system.ts::initializeFeeCache()`.
|
|
562
562
|
|
|
563
563
|
#### BTS Fee Object (Always Object)
|
|
564
564
|
|
|
@@ -672,7 +672,7 @@ Floating-point arithmetic drifts from true blockchain integer representations ov
|
|
|
672
672
|
|
|
673
673
|
#### 5.5.1 Core Quantization Functions
|
|
674
674
|
|
|
675
|
-
**Location**: `modules/order/utils/math.ts` (
|
|
675
|
+
**Location**: `modules/order/utils/math.ts` (`quantizeFloat`)
|
|
676
676
|
|
|
677
677
|
##### `quantizeFloat(value, precision)` - Eliminate Accumulation Errors
|
|
678
678
|
|
|
@@ -774,7 +774,7 @@ This prevents the bug where `available = chainFree + required` created a tautolo
|
|
|
774
774
|
|
|
775
775
|
## 6. Safety & Invariants
|
|
776
776
|
|
|
777
|
-
The `Accountant` enforces strict mathematical invariants to detect bugs or manual interference. Invariants are checked by `_verifyFundInvariants()` (`modules/order/accounting.ts`
|
|
777
|
+
The `Accountant` enforces strict mathematical invariants to detect bugs or manual interference. Invariants are checked by `_verifyFundInvariants()` (`modules/order/accounting.ts`) after every blockchain sync cycle. The verification reads from a snapshot captured under `_fundLock` — `actualBuy`/`actualSell` are captured at snapshot time, not read live outside the lock, closing a TOCTOU window. When a violation is detected, the system logs a `CRITICAL` error and attempts automatic recovery via `manager.accountant.recalculateFunds()` (`modules/order/accounting.ts`, delegated from `modules/order/manager.ts`) — resetting internal state to match on-chain reality. If the grid lock is held (mid-rebalance), recovery is deferred until the lock is released. The bot continues operating throughout; it does **not** halt on invariant violations.
|
|
778
778
|
|
|
779
779
|
### 6.1 The Equality Invariant
|
|
780
780
|
Total funds on chain must equal free plus committed.
|
|
@@ -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.0 release*
|
|
@@ -120,7 +120,26 @@ The per-action LAST-FILL-GUARD rule is direction-only relative to that pivot —
|
|
|
120
120
|
a BUY is blocked at/above it, a SELL at/below it (equal price is a re-place at
|
|
121
121
|
the just-filled level). The spread-correction planner applies the SAME predicate
|
|
122
122
|
to its candidates before planning, so a correction batch never contains an op
|
|
123
|
-
the guard would drop.
|
|
123
|
+
the guard would drop. The predicate takes exactly `(price, type, lastPrice,
|
|
124
|
+
lastType)`: there is no size or increment argument, because the old
|
|
125
|
+
`pivot ± increment/2` band was what blocked profitable placements.
|
|
126
|
+
|
|
127
|
+
**What may become the pivot.** Only a real WINDOW trade. EDGE-pinned insurance
|
|
128
|
+
fills (grid floor/ceiling) are skipped by `recordLastFilledPrices` via the
|
|
129
|
+
shared classifier `collectEdgePinnedFillIds`, matching the crawl's own edge
|
|
130
|
+
exclusion: an edge order is static fat-finger insurance, not market movement,
|
|
131
|
+
and the pivot is also the absolute geometry anchor for
|
|
132
|
+
`reanchorBoundaryFromLastFill` — a rail-edge pivot would teleport the window to
|
|
133
|
+
that edge. PARTIAL fills do arm it (a real trade at a real price). The pivot
|
|
134
|
+
then survives a grid rebuild: `_resetLastFillPivot` clears it with the
|
|
135
|
+
old generation and `rearmLastFillPivotFromMarketFill` re-arms it immediately
|
|
136
|
+
from the bot-scoped last-market-fill row, provenance `'fill'`.
|
|
137
|
+
|
|
138
|
+
*Operational consequence (deliberate):* after an edge fill the affected side
|
|
139
|
+
stays vetoed relative to the last WINDOW trade until a window fill (or the 24h
|
|
140
|
+
pivot TTL) re-arms it — e.g. a floor insurance BUY does not license selling that
|
|
141
|
+
inventory below the last window sale. Moving the geometry to the edge instead
|
|
142
|
+
(the pre-fix behaviour) re-typed and cancelled the whole window on a wick.
|
|
124
143
|
|
|
125
144
|
The per-action LAST-FILL-GUARD checks run against the pivot frozen at batch
|
|
126
145
|
start. A fill queued between that freeze and the broadcast passes every
|
|
@@ -183,7 +202,10 @@ Rules that keep the mirror honest:
|
|
|
183
202
|
genesis-mismatch verdicts erase the row through one shared drop path
|
|
184
203
|
(`AccountOrders.clearPersistedLastFillPivot`); an off-ladder row is a no-op
|
|
185
204
|
that falls back to the book seed. The snapped ladder level is restored, never
|
|
186
|
-
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.
|
|
187
209
|
- **The generation wipes the pivot.** `initializeGrid` and
|
|
188
210
|
`rejectCorruptedGridSnapshot` call `resetLastFillPivot`, which clears the
|
|
189
211
|
full scalar family including the per-side mirrors (so the book seed's cold
|
|
@@ -418,9 +440,10 @@ is divergence telemetry built on `calculateGridSideDivergenceMetric`.
|
|
|
418
440
|
|
|
419
441
|
**A grid with no price ladder is not a degraded grid — it is an undefined one.**
|
|
420
442
|
Every consumer of the invariant reads `priceForSlot(idx, genesis)`, and each one
|
|
421
|
-
silently degrades without it: nearest-slot adoption,
|
|
422
|
-
|
|
423
|
-
|
|
443
|
+
silently degrades without it: nearest-slot adoption (`sync_engine.ts`), the
|
|
444
|
+
materialize descriptor-price fallback (`sync_engine.ts`), edge anchoring via
|
|
445
|
+
`resolveLiveEdgeAnchorPrice` (`order/utils/order.ts`), and the `isSlotInRail`
|
|
446
|
+
fail-open (`order/utils/math.ts`). That degradation is the tolerance
|
|
424
447
|
matcher, which is exactly the path on which an off-grid price becomes grid
|
|
425
448
|
evidence. So the ladder is treated as a **required** part of a snapshot, not a
|
|
426
449
|
nice-to-have.
|
package/docs/GRID_RECONCILE.md
CHANGED
|
@@ -80,14 +80,14 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
|
|
|
80
80
|
|
|
81
81
|
**Source:** `reconcileGridOrders()` Phase 1 in `grid_reconcile.ts`.
|
|
82
82
|
|
|
83
|
-
1. **Phantom order sanitization** (
|
|
84
|
-
- **Freshly-assigned deferral** (
|
|
85
|
-
- **Ghost heuristic** (
|
|
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. Two absence-decision guards make this safe:
|
|
84
|
+
- **Freshly-assigned deferral** (the `_orderIdAssignedAt` freshness guard): an `orderId` assigned within `TIMING.SYNC_LOCK_TIMEOUT_MS` may be an in-flight create/adopt whose broadcast has not landed or is not yet visible to 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.
|
|
85
|
+
- **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
86
|
- Virtualization always uses `{ skipAccounting: true }` so startup cleanup never inflates `ChainFree`.
|
|
87
87
|
|
|
88
|
-
2. **Duplicate detection** (
|
|
88
|
+
2. **Duplicate detection** (the unmatched-order duplicate pass): For each unmatched chain order, find the nearest active same-side grid order. If its price equals that grid order's slot price exactly (`priceSlotEqual` at the asset precision), flag it as a suspected duplicate and queue for a Phase 2 cancel (never cancelled under lock). Non-equal neighbours are only logged with nearest-same-side diagnostics and continue into per-side reconciliation. Duplicate IDs are removed from the unmatched set so they aren't also paired for updates/creates.
|
|
89
89
|
|
|
90
|
-
3. **Per-side reconciliation** via `_reconcileStartupSide(planOnly=true)` (
|
|
90
|
+
3. **Per-side reconciliation** via `_reconcileStartupSide(planOnly=true)` (`grid_reconcile_internal.ts`):
|
|
91
91
|
- Count `matchedOnGrid` (active grid orders with `orderId`)
|
|
92
92
|
- `neededSlots = targetCount - matchedOnGrid`; pick virtual slots to activate
|
|
93
93
|
- Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
|
|
@@ -225,6 +225,23 @@ Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen mast
|
|
|
225
225
|
|
|
226
226
|
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
227
|
|
|
228
|
+
### Fill Discipline (unsettled fills + last-fill placement)
|
|
229
|
+
|
|
230
|
+
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):
|
|
231
|
+
|
|
232
|
+
- **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.
|
|
233
|
+
- **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).
|
|
234
|
+
|
|
235
|
+
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.
|
|
236
|
+
|
|
237
|
+
**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:
|
|
238
|
+
|
|
239
|
+
- `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.
|
|
240
|
+
- 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.
|
|
241
|
+
- `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.
|
|
242
|
+
|
|
243
|
+
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).
|
|
244
|
+
|
|
228
245
|
### Truncated-Read Ambiguity (since 1.4.8)
|
|
229
246
|
|
|
230
247
|
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:
|
|
@@ -287,6 +304,9 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
|
|
|
287
304
|
| `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
|
|
288
305
|
| `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
|
|
289
306
|
| `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 |
|
|
307
|
+
| `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 |
|
|
308
|
+
| `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) |
|
|
309
|
+
| `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
310
|
| `tests/repro_phantom_orders.ts` | Phantom order prevention |
|
|
291
311
|
|
|
292
312
|
---
|
package/docs/LIFECYCLE.md
CHANGED
|
@@ -90,7 +90,7 @@ sequenceDiagram
|
|
|
90
90
|
participant CO as chain_orders (broadcast)
|
|
91
91
|
participant STORE as Storage
|
|
92
92
|
|
|
93
|
-
CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts
|
|
93
|
+
CH->>Q: enqueue fill(s) (createFillCallback, dexbot_fill_runtime.ts)
|
|
94
94
|
FR->>FR: drain queue -> _processFillsWithBatching
|
|
95
95
|
FR->>OM: processFilledOrders() (manager.ts)
|
|
96
96
|
OM->>AC: processFillAccounting() (single call, batch)
|
|
@@ -134,10 +134,10 @@ sequenceDiagram
|
|
|
134
134
|
participant STORE as Storage
|
|
135
135
|
|
|
136
136
|
MA->>CL: AMA center snapshot updated
|
|
137
|
-
CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts
|
|
138
|
-
CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts
|
|
139
|
-
RT->>RT:
|
|
140
|
-
RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts
|
|
137
|
+
CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts)
|
|
138
|
+
CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts)
|
|
139
|
+
RT->>RT: _runGridMaintenance('periodic') (dexbot_class.ts, called from maintenance)
|
|
140
|
+
RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts)
|
|
141
141
|
RT->>AC: recalculate funds from balances
|
|
142
142
|
RT->>GD: promote AMA center -> grid center
|
|
143
143
|
RT->>GD: recalculateGrid() (grid.ts)
|
|
@@ -157,13 +157,13 @@ The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` an
|
|
|
157
157
|
the parameters.
|
|
158
158
|
|
|
159
159
|
> Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
|
|
160
|
-
> runtime (`modules/credit_runtime.ts
|
|
161
|
-
> `_runCreditRuntimeMaintenance`
|
|
160
|
+
> runtime (`modules/credit_runtime.ts`, `runMaintenance()`), reached via
|
|
161
|
+
> `_runCreditRuntimeMaintenance` (`dexbot_class.ts`). The grid maintenance
|
|
162
162
|
> chain above is the one that matters for order/price upkeep.
|
|
163
163
|
|
|
164
|
-
References: `modules/dexbot_class.ts
|
|
165
|
-
`modules/dexbot_maintenance_runtime.ts
|
|
166
|
-
|
|
164
|
+
References: `modules/dexbot_class.ts` (`_performPeriodicGridChecks` →
|
|
165
|
+
`_runGridMaintenance`) → `modules/dexbot_maintenance_runtime.ts`
|
|
166
|
+
(`performPeriodicGridChecks` → `executeMaintenanceLogic`),
|
|
167
167
|
`docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
|
|
168
168
|
|
|
169
169
|
---
|
|
@@ -192,7 +192,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
|
|
|
192
192
|
| How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
|
|
193
193
|
| Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
|
|
194
194
|
| Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
|
|
195
|
-
| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts
|
|
195
|
+
| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts` (`_performPeriodicGridChecks`, `_runGridMaintenance`) |
|
|
196
196
|
| Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
|
|
197
197
|
| Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
|
|
198
198
|
| Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |
|
package/docs/LOGGING.md
CHANGED
|
@@ -307,12 +307,26 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
307
307
|
| `[SPREAD-CORRECTION] Plan-time dedupe: N planned slot(s) occupied since planning (...); re-planning from fresh master` | A planned CREATE destination was taken after planning; the plan is re-derived from fresh master |
|
|
308
308
|
| `[SPREAD-CORRECTION] Plan-time dedupe: ...; no re-plan candidate — refusing this cycle` | Collision detected but no fresh candidate exists; the colliding plan is withheld (never broadcast) |
|
|
309
309
|
| `[SPREAD-CORRECTION] Batch refused (cause); re-planning from fresh master (attempt 2/2)` | Transient refusal; the bounded fresh-master re-plan is in progress |
|
|
310
|
-
| `[SPREAD-CORRECTION] Excluded N candidate(s) from <side> planning: SELL must be above / BUY must be below the last fill ... (the broadcast guard would drop them)` | The planner dropped tightening-edge candidates that the LAST-FILL-GUARD would veto. They were never planned, so no batch is wasted on a guaranteed refusal |
|
|
310
|
+
| `[SPREAD-CORRECTION] Excluded N candidate(s) from <side> planning: SELL must be above / BUY must be below the last fill ... (the broadcast guard would drop them)` | The planner dropped tightening-edge candidates that the LAST-FILL-GUARD would veto. They were never planned, so no batch is wasted on a guaranteed refusal. `N` counts candidate SLOTS, not pool visits — an empty in-rail slot qualifies for both the SPREAD pool and the orphan pool, and counting visits reported every vetoed slot twice (SLF-13) |
|
|
311
311
|
| `[SPREAD-CORRECTION] No placeable <side> slot: every tightening slot is at/through the last fill ...` | Honest no-op: the side cannot be tightened against the last fill (a boundary move or a new fill must restore headroom). Not a batch refusal |
|
|
312
|
+
| `[SPREAD-CORRECTION] Fund-constrained promotion on <side>: rotating N resting order(s) into the gap (...)` | Free funds could not fund every promoted gap slot; same-side ACTIVE orders are moved into the unfunded slots at their booked size (no new commitment). The action is a COW UPDATE rotation, never a CREATE. Destinations come from the post-dedupe/post-duplicate-price candidate list |
|
|
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
|
+
| `[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
|
+
| `[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 |
|
|
312
316
|
| `[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 |
|
|
313
317
|
| `[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 |
|
|
314
318
|
| `[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 |
|
|
315
|
-
| `[
|
|
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 read-time 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 at the ANCHOR slot is allow-listed, so a partial fill does not deadlock the repair |
|
|
321
|
+
| `[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
|
+
| `[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, taken from the SAME row that supplied the price (a book-seeded live pivot never lends its clock) |
|
|
324
|
+
| `[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 |
|
|
325
|
+
| `[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) |
|
|
326
|
+
| `[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 |
|
|
327
|
+
| `[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) |
|
|
328
|
+
| `[COW] Boundary rail-derived: unusable (unsafe: placed_order_in_band ...); keeping Z` | The shared `validatePersistedBoundary` gate refused the clamped value (it would strand a placed order in the implied band). Same validator as the restore/commit paths and the fill re-anchor; the only get-out is the batch vacating the slot |
|
|
329
|
+
| `[SYNC] Gap-evacuation queued for <orderId> (slot <slot>): live price P maps inside the gap band (boundary B, gap G) — cancelling instead of re-pricing` | A chain price mismatch is actually an in-band placement: the live price maps between the boundary and sellStart. Queued as a cancel-only evacuation, and any plain re-price entry for the same chain order is dropped so the two cannot race |
|
|
316
330
|
| `[SPREAD-CORRECTION] sell projection exceeds chain free by 1485.41092974; funding the candidates from chain truth (2171.2 for 2171.2 of ideal size) instead of placing nothing` | The virtual reservation is the projection of these very candidates and is larger than the chain free balance; the correction funds what the chain actually holds instead of deadlocking on a circular budget |
|
|
317
331
|
| `[BOUNDARY] Dropped N owed fill crawl(s) (boundary commit): buy=B sell=S net=N±M oldest=Ns kept=M boundary X -> Y` | The commit consumed the records the derivation folded (`kept=M` = records that stayed owed — a capped fold or a re-recorded slot) |
|
|
318
332
|
| `[BOUNDARY] Kept N owed fill crawl(s) unconsumed (boundary commit)` | The commit arrived without a consumed-set (a plan that never derived a boundary) or folded nothing it could apply; the records stay owed for the next derivation |
|
|
@@ -321,6 +335,27 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
321
335
|
|
|
322
336
|
---
|
|
323
337
|
|
|
338
|
+
## Fill discipline at the reconcile / placement sites
|
|
339
|
+
|
|
340
|
+
Added with the buy-higher fix (2026-11-02: 9 buy-lower violations, 23.5% of the
|
|
341
|
+
window's BTS). See `docs/GRID_RECONCILE.md#fill-discipline-unsettled-fills--last-fill-placement`.
|
|
342
|
+
|
|
343
|
+
| Message | Meaning |
|
|
344
|
+
|---------|---------|
|
|
345
|
+
| `[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 |
|
|
346
|
+
| `[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 |
|
|
347
|
+
| `[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 |
|
|
348
|
+
| `[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 |
|
|
349
|
+
| (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) |
|
|
350
|
+
| `[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 |
|
|
351
|
+
| `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 |
|
|
352
|
+
| `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 |
|
|
353
|
+
| `[_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) |
|
|
354
|
+
| `Startup: Skip create <label> (LAST-FILL-GUARD) - price P ...` | Same refusal in the batch create path |
|
|
355
|
+
| `[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 |
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
324
359
|
## Fill History Scan Profiling
|
|
325
360
|
|
|
326
361
|
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.
|