dexbot 1.6.3 → 1.6.4

package/docs/GRID_RECONCILE.md

@@ -13,7 +13,7 @@ Reconciliation aligns the bot's model with on-chain reality. It runs at startup
 
 ### Why Not Cancel Everything
 
-- No atomic cancel+create on BitShares — `cancel_order` cancels the full order; there is no partial size reduction
+- No atomic cancel+create on BitShares — `limit_order_cancel` cancels the full order; there is no partial size reduction
 - A full teardown leaves the bot unable to trade during the rebuild window
 
 ---
@@ -132,8 +132,8 @@ If Phase 2 partially succeeds (some cancels, some creates fail), there is no rol
 ### Timeouts and Read Coverage
 
 - **No per-attempt race** around the reconcile itself — the 1.4.8 change removed it to avoid orphaning mid-batch broadcasts (see the [`recalculateGrid`](../modules/order/grid.ts) call site in `modules/order/grid.ts`).
-- The whole resync is bounded by a **10-minute total timeout** (`PIPELINE_TIMING.TIMEOUT_MS * 2` at `grid.ts:1184`), applied via `Promise.race` at `grid.ts:1279`.
-- Every internal chain read goes through `readOpenOrdersGuarded` (`chain_orders.ts:610`) with the 30s / 3-retry / node-failover standard, and empty/truncated reads are treated as **ambiguous** — never as authoritative absence.
+- The whole resync is bounded by a **10-minute total timeout** (`PIPELINE_TIMING.TIMEOUT_MS * 2` at `grid.ts:1511`), applied via `Promise.race` at `grid.ts:1617`.
+- Every internal chain read goes through `readOpenOrdersGuarded` (`chain_orders.ts:608`) with the 30s / 3-retry / node-failover standard, and empty/truncated reads are treated as **ambiguous** — never as authoritative absence.
 
 ---
 
@@ -141,7 +141,7 @@ If Phase 2 partially succeeds (some cancels, some creates fail), there is no rol
 
 ### Fresh Grid Guard (`matchedOnGrid > 0`)
 
-**`grid_reconcile_internal.ts:1600`**
+**`grid_reconcile_internal.ts:1738`**
 
 When a brand-new grid is generated, every slot is VIRTUAL — `matchedOnGrid = 0`. Without a guard, every on-chain order appears "unmatched" and would be cancelled as excess:
 
@@ -155,27 +155,27 @@ When `matchedOnGrid === 0` AND scaling up (`neededSlots > 0`), excess cancellati
 
 ### Grid-Edge Lock
 
-**`grid_reconcile_internal.ts:244`** — `_isGridEdgeFullyActive` detects when the grid boundary is fully active (all slots on-chain) before cancelling excess orders.
+**`grid_reconcile_internal.ts:355`** — `_isGridEdgeFullyActive` detects when the grid boundary is fully active (all slots on-chain) before cancelling excess orders.
 
-When all outermost orders of a side are ACTIVE with `orderId`, all balance is committed to the edges. Cancel the **largest** order among the update candidates (`_cancelLargestOrder`, line 314) to free maximum funds with minimum operations, since the DEX does not expose partial-reduce in one operation. The cancelled slot gets a replacement create.
+When all outermost orders of a side are ACTIVE with `orderId`, all balance is committed to the edges. Cancel the **largest** order among the update candidates (`_cancelLargestOrder`, line 425) to free maximum funds with minimum operations, since the DEX does not expose partial-reduce in one operation. The cancelled slot gets a replacement create.
 
-Detection (`_isGridEdgeFullyActive`, line 244): sort orders by price (BUY descending, SELL ascending), and check the outermost ones are all `isOrderPlaced()`.
+Detection (`_isGridEdgeFullyActive`, line 355): sort orders by price (BUY descending, SELL ascending), and check the outermost ones are all `isOrderPlaced()`.
 
-### Duplicate Tolerance (5× Multiplier)
+### Duplicate Cancellation
 
-**`grid_reconcile.ts:246-311`**
+**`grid_reconcile.ts:278`**
 
-`SUSPECTED_DUPLICATE_TOLERANCE_MULTIPLIER = 5`. An unmatched chain order within 5× price tolerance of an active same-type grid slot is a suspected duplicate → queued for Phase 2 cancellation (not cancelled under lock). The base tolerance comes from `calculatePriceTolerance`, which estimates the maximum acceptable price deviation for the order's size and the grid's price step.
+An unmatched chain order whose price equals an active same-type grid slot's price — exact slot-price equality via `priceSlotEqual` at the asset precision — is a **suspected duplicate** → queued for Phase 2 cancellation (not cancelled under lock). Non-equal neighbours are only logged with nearest-same-side diagnostics, never cancelled here. The earlier fuzzy `SUSPECTED_DUPLICATE_TOLERANCE_MULTIPLIER` (5× `calculatePriceTolerance`) was removed.
 
 ### Batch Update Failure Recovery
 
-**`grid_reconcile.ts:393-465`**
+**`grid_reconcile.ts:436`**
 
 Up to 3 batch attempts. Each failure triggers a recovery sync + plan refresh. If all plans are empty → resolved early. After 3× → sequential fallback with per-plan recovery (each individual failure triggers a recovery sync + queue refresh).
 
 ### Phantom Orders via Reconcile
 
-**`grid_reconcile.ts:211-244`** — 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 freshly-assigned deferral protects in-flight broadcasts, 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.
+**`grid_reconcile.ts:227-253`** — 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 freshly-assigned deferral protects in-flight broadcasts, 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.
 
 ### Shelf Orders (Fork-Kept Manual Orders)
 
@@ -189,13 +189,17 @@ Live on-chain orders with non-slot-N ids below the rail (e.g. `deep-*` manuals k
 
 Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen master Map. The working grid is not involved — reconcile is a startup operation that runs before the COW pipeline is active. See [`COPY_ON_WRITE_MASTER_PLAN.md`](COPY_ON_WRITE_MASTER_PLAN.md#safety-guardrails) and [`COW_INVARIANTS.md`](COW_INVARIANTS.md#reconcile-grid_reconcilemd) for COW rules.
 
+### Slot-Price Invariant at the Reconcile Emission Sites
+
+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.
+
 ### Truncated-Read Ambiguity (since 1.4.8)
 
-Every chain read feeding an absence/surplus decision goes through `readOpenOrdersGuarded` (`chain_orders.ts:610`) and treats an empty or truncated snapshot as **unreadable** — never as "nothing landed" or "nothing to cancel":
+Every chain read feeding an absence/surplus decision goes through `readOpenOrdersGuarded` (`chain_orders.ts:608`) and treats an empty or truncated snapshot as **unreadable** — never as "nothing landed" or "nothing to cancel":
 
-- `_recoverSyncFromChain` (`grid_reconcile_internal.ts:592`) — plus its three recovery sites in `_createOrderFromGrid` / `_cancelChainOrder` — defers on empty/truncated reads (`deferEmpty: true`). A pass-1 phantom cleanup would otherwise virtualize live slots from a partial window.
-- `_adoptPossiblyLandedCreate` (`grid_reconcile_internal.ts:932`) defers to an uncertain outcome on truncated reads, and the startup group batch uncertain verification follows the same rule.
-- Phase 3 final refresh (`grid_reconcile.ts:512`) skips adoption/surplus-cancel on a truncated read, keeping the pre-phase-2 counts for the summary log.
+- `_recoverSyncFromChain` (`grid_reconcile_internal.ts:726`) — plus its three recovery sites in `_createOrderFromGrid` / `_cancelChainOrder` — defers on empty/truncated reads (`deferEmpty: true`). A pass-1 phantom cleanup would otherwise virtualize live slots from a partial window.
+- `_adoptPossiblyLandedCreate` (`grid_reconcile_internal.ts:1112`) defers to an uncertain outcome on truncated reads, and the startup group batch uncertain verification follows the same rule.
+- Phase 3 final refresh (`grid_reconcile.ts:533`) skips adoption/surplus-cancel on a truncated read, keeping the pre-phase-2 counts for the summary log.
 - Adoption paths (`_adoptPossiblyLandedCreate`, grouping path, reconcile adoption loop) apply the create-fee deduction via `_applySync` for accounting parity.
 
 The underlying rule is `INV-BROADCAST-004`: a capped `get_full_accounts` window omits the freshest orders (fresh creates sort last), so absence can never be authoritative on a truncated read.
@@ -204,7 +208,7 @@ The underlying rule is `INV-BROADCAST-004`: a capped `get_full_accounts` window
 
 ## Lock Hierarchy
 
-**`manager.ts:474-489`** — canonical reference in [`developer_guide.md`](developer_guide.md#lock-ordering-for-deadlock-prevention).
+**`manager.ts:593-597`** — canonical reference in [`developer_guide.md`](developer_guide.md#lock-ordering-for-deadlock-prevention).
 
 ```
 Level 0: _fillProcessingLock    Level 1: _divergenceLock
@@ -230,11 +234,10 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
 
 | Constant | Value | File | Role |
 |----------|-------|------|------|
-| `SUSPECTED_DUPLICATE_TOLERANCE_MULTIPLIER` | `5` | `grid_reconcile.ts:20` | Amplifies base tolerance for duplicate detection |
-| `maxBatchAttempts` | `3` | `grid_reconcile.ts:415` | Update-batch retry limit |
-| `PRICE_TOLERANCE_MAX_PERCENT` | `0.01` (1%) | `constants.ts:452` | Cap on price tolerance |
-| `PRICE_TOLERANCE_MIN_ABSOLUTE` | `0.0001` | `constants.ts:456` | Floor for price tolerance |
-| `PIPELINE_TIMING.TIMEOUT_MS` | `300000` (5min) | `constants.ts:800` | Base pipeline timing; resync uses 2× (10 min) |
+| `maxBatchAttempts` | `3` | `grid_reconcile.ts:436` | Update-batch retry limit |
+| `PRICE_TOLERANCE_MAX_PERCENT` | `0.01` (1%) | `constants.ts:566` | Cap on price tolerance |
+| `PRICE_TOLERANCE_MIN_ABSOLUTE` | `0.0001` | `constants.ts:570` | Floor for price tolerance |
+| `PIPELINE_TIMING.TIMEOUT_MS` | `300000` (5min) | `constants.ts:973` | Base pipeline timing; resync uses 2× (10 min) |
 
 ---
 
@@ -260,10 +263,10 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
 
 | File | Role |
 |------|------|
-| `modules/order/grid_reconcile.ts` | Public API + 3-phase orchestrator (642 lines) |
-| `modules/order/grid_reconcile_internal.ts` | Internal helpers — `_reconcileStartupSide`, grid detection, recovery, uncertainty (1675 lines) |
+| `modules/order/grid_reconcile.ts` | Public API + 3-phase orchestrator (670 lines) |
+| `modules/order/grid_reconcile_internal.ts` | Internal helpers — `_reconcileStartupSide`, grid detection, recovery, uncertainty (2132 lines) |
 | `modules/order/manager.ts` | Lock hierarchy definition, `_applyOrderUpdate`, phantom guard, `reconcileGrid` entry, COW integration |
-| `modules/order/async_lock.ts` | AsyncLock engine with ALS re-entrancy (424 lines) |
+| `modules/order/async_lock.ts` | AsyncLock engine with ALS re-entrancy (435 lines) |
 | `modules/order/sync_engine.ts` | Blockchain sync pipeline |
 | `modules/order/grid.ts` | Grid creation, `recalculateGrid` (full resync) calls reconcile |
 | `modules/chain_orders.ts` | `readOpenOrdersGuarded` / guarded read infrastructure |

package/docs/LIFECYCLE.md

@@ -90,7 +90,7 @@ sequenceDiagram
     participant CO as chain_orders (broadcast)
     participant STORE as Storage
 
-    CH->>Q: enqueue fill(s)  (dexbot_fill_runtime.ts:325)
+    CH->>Q: enqueue fill(s)  (dexbot_fill_runtime.ts:414)
     FR->>FR: drain queue -> _processFillsWithBatching
     FR->>OM: processFilledOrders()  (manager.ts)
     OM->>AC: processFillAccounting()  (single call, batch)
@@ -105,7 +105,7 @@ sequenceDiagram
 ```
 
 Why it matters:
-- **Gap-slot batching** (batch size = grid gap-slot count, `DEXBot._getGapSlotBatchSize`) keeps bursts
+- **Gap-slot batching** (batch size = grid gap-slot count + 1, `DEXBot._getGapSlotBatchSize`) keeps bursts
   deterministic — see `docs/architecture.md` §"Fill Processing Pipeline".
 - **Single rebalance cycle**: all fills in a batch share one broadcast, so proceeds
   are immediately available for replacement sizing (no split-across-cycles delay).
@@ -134,10 +134,10 @@ sequenceDiagram
     participant STORE as Storage
 
     MA->>CL: AMA center snapshot updated
-    CL->>CL: _performPeriodicGridChecks()  (dexbot_class.ts:1694)
-    CL->>RT: performPeriodicGridChecks()  (dexbot_maintenance_runtime.ts:1043)
-    RT->>RT: runGridMaintenance(bot,'periodic')  (dexbot_maintenance_runtime.ts:1845)
-    RT->>RT: executeMaintenanceLogic()  (dexbot_maintenance_runtime.ts:1452)
+    CL->>CL: _performPeriodicGridChecks()  (dexbot_class.ts:1673)
+    CL->>RT: performPeriodicGridChecks()  (dexbot_maintenance_runtime.ts:1554)
+    RT->>RT: runGridMaintenance(bot,'periodic')  (dexbot_maintenance_runtime.ts:2770)
+    RT->>RT: executeMaintenanceLogic()  (dexbot_maintenance_runtime.ts:2270)
     RT->>AC: recalculate funds from balances
     RT->>GD: promote AMA center -> grid center
     RT->>GD: recalculateGrid()  (grid.ts)
@@ -157,12 +157,12 @@ The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` an
 the parameters.
 
 > Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
-> runtime (`modules/credit_runtime.ts:3041`, reached via
-> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1794`). The grid maintenance
+> runtime (`modules/credit_runtime.ts:3019`, reached via
+> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1790`). The grid maintenance
 > chain above is the one that matters for order/price upkeep.
 
-References: `modules/dexbot_class.ts:1694` (`_performPeriodicGridChecks`) →
-`modules/dexbot_maintenance_runtime.ts:1043` (`performPeriodicGridChecks`) →
+References: `modules/dexbot_class.ts:1673` (`_performPeriodicGridChecks`) →
+`modules/dexbot_maintenance_runtime.ts:1554` (`performPeriodicGridChecks`) →
 `:1845` (`runGridMaintenance`) → `:1452` (`executeMaintenanceLogic`),
 `docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
 
@@ -179,6 +179,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
 | **Fund SSOT** | `Accounting` owns every fund number. Nothing else computes available funds. | `docs/architecture.md` §"Fund Flow Architecture" |
 | **Replay-safe fills** | A fill is credited exactly once via processed-fill keys; retries are idempotent. | `modules/dexbot_fill_runtime.ts` |
 | **Single broadcast per cycle** | One `updateOrdersOnChainBatch` per rebalance — never scatter writes. | `docs/architecture.md` §"Fill Processing Pipeline" |
+| **Slot price = genesis level** | Every emitted order's price must equal `priceForSlot(idx, genesis)` for its slot — range guards cannot substitute for grid membership; off-grid emissions are blocked. | `docs/GRID_PRICE_INVARIANT.md` |
 | **Browser/Node split** | Heavy runtime is Node-only; never import it from a browser bundle. | `AGENTS.md` "Browser-Safe Surface", `package.json` "browser" field |
 | **Lock ordering** | Fill drain and maintenance must not run a rebalance concurrently. | `docs/developer_guide.md` §"Startup Sequence & Lock Ordering" |
 
@@ -191,7 +192,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
 | How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
 | Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
 | Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
-| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1694` |
+| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1673` |
 | Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
 | Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
 | Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |

package/docs/README.md

@@ -2,7 +2,7 @@
 
 This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
 
-**Version context:** v1.6.3 (released).
+**Version context:** v1.6.4 (released).
 
 ---
 
@@ -116,6 +116,38 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Lifecycle B (Maintenance / AMA-Driven)**: Periodic path from `_performPeriodicGridChecks` → `executeMaintenanceLogic`.
 - **Cross-Cutting Invariants**: COW boundary, fund SSOT, replay-safe fills, lock ordering.
 
+### 🧩 [Copy-on-Write Master Plan](COPY_ON_WRITE_MASTER_PLAN.md)
+*COW design, phases, and state machine details.*
+- **Architecture**: Master-grid projection model and rebalance flow
+- **Lifecycle**: Implementation phases, commit boundaries, and test coverage
+- **Safety**: Invariants and guardrails for concurrent updates
+
+### 🔒 [COW Invariants](COW_INVARIANTS.md)
+*Stable theory contract for COW pipeline.*
+- **Non-negotiable invariants**: Master immutability, commit atomicity, projection rules, accounting separation
+- **Test mapping**: Links each invariant to regression tests
+- **Review checklist**: Quick-use verification for COW/accounting changes
+
+### 📐 [Grid-Price Invariant](GRID_PRICE_INVARIANT.md)
+*Why a slot's emitted price must equal its genesis level — and how that failed.*
+- **The invariant**: `order.price === priceForSlot(idx, genesis)`, and why range guards cannot substitute for it
+- **Failure mechanism**: Chain price overwriting slot identity, pre-broadcast substitution, untrusted fill-guard pivot
+- **Enforcement**: The six emission sites, the blocking rejection of off-grid emissions, the final pre-broadcast pivot gate, and the fail-open policy on unjudgeable inputs
+- **Out-of-bounds policy**: Hold and surface; refill in-grid slots at their genesis price
+- **Status**: Landed enforcement map, key constants, and why the removed 5% sanity gate must not be naively re-landed
+
+### 💰 [Fund Movement & Accounting](FUND_MOVEMENT_AND_ACCOUNTING.md)
+*The most critical part of the bot: safe capital management.*
+- **Single Source of Truth**: How the bot avoids double-spending and out-of-sync balances.
+- **Optimistic ChainFree**: The mechanism that allows the bot to trade with fill proceeds before they are finalized on-chain.
+- **Fill Batch Processing**: Fixed-cap batching for efficient fill processing (`<=4` unified, `>4` chunked)
+- **Partial Order Consolidation**: Simplified, direct consolidation through grid rebuilding (no merge/split mechanics)
+- **Dust Detection & Management**: Partials below the dust threshold are cancelled on-chain immediately on detection (no delay, no timer)
+- **BTS Fee Object Structure**: `netProceeds` field for accounting precision
+- **BUY Side Sizing & Fee Accounting**: Correct fee application by order side
+- **Mixed Order Fund Validation**: Separate validation for BUY vs SELL order fund checks
+- **Fee Management**: Detailed logic for BTS fee reservations and market fee deductions.
+
 ### 📖 [Developer Guide](developer_guide.md)
 *Your daily companion for coding.*
 - **Quick Start**: How to get the development environment running.
@@ -136,57 +168,31 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Branching Strategy**: Explanation of the `test` → `dev` → `main` lifecycle.
 - **CI/CD Patterns**: Standards for merging and ensuring code quality across branches.
 
-### 🧮 [DEXBot vs DEXBot2 Comparison](DEXBOT_COMPARISON.md)
-*Architectural, functional, and operational comparison with the original Python DEXBot.*
-- **Scope**: Full side-by-side of technology stack, architecture, trading strategies, order management, configuration, blockchain integration, fund accounting, and concurrency safety
-- **Audience**: Developers and operators evaluating or migrating between the two projects
+### 🧪 [Test Suite](../tests/README.md)
+*Test organization, categories, and key architectural patterns tested.*
+- **Test Layout**: Directory structure, helpers, and quick-start commands
+- **Categories**: Core infrastructure, order management, COW rebalancing, fees/accounting, integration, edge cases, and more
+- **Architectural Patterns**: COW rebalancing, RMS divergence, and fund invariants with doc cross-references
 
 ### 🧭 [Evolution Report](EVOLUTION.md)
 *Project timeline and major architecture phases.*
 - **Coverage**: Historical milestones from bootstrap through the current stable release; per-release detail lives in [CHANGELOG.md](../CHANGELOG.md)
 - **Focus**: Architecture evolution, release history, and test growth
 
+### ⏪ [Order Engine Retrospective](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md)
+*Why the post-1.0.0 order engine kept misbehaving — synthesis plus the incident/fix ledger.*
+- **Part I — Synthesis**: root cause (uncertain broadcast), recurring bug families, meta-patterns, what actually fixed it, lessons
+- **Part II — Incident & Fix Ledger**: preserved gap-band / ladder-recenter / orphan-fill / price-first plans with `LANDED`/`REVERTED`/`SUPERSEDED` status and commit hashes
+- **Regression gate**: `npm run analysis:grid-check` (see [analysis/README.md](../analysis/README.md))
+
 ### 🗒️ [Changelog](../CHANGELOG.md)
 *Release notes and documentation history.*
 - **Scope**: Versioned notes per release
 
-### 🧩 [Copy-on-Write Master Plan](COPY_ON_WRITE_MASTER_PLAN.md)
-*COW design, phases, and state machine details.*
-- **Architecture**: Master-grid projection model and rebalance flow
-- **Lifecycle**: Implementation phases, commit boundaries, and test coverage
-- **Safety**: Invariants and guardrails for concurrent updates
-
-### 🔒 [COW Invariants](COW_INVARIANTS.md)
-*Stable theory contract for COW pipeline.*
-- **Non-negotiable invariants**: Master immutability, commit atomicity, projection rules, accounting separation
-- **Test mapping**: Links each invariant to regression tests
-- **Review checklist**: Quick-use verification for COW/accounting changes
-
-### 📐 [Grid-Price Invariant](GRID_PRICE_INVARIANT.md)
-*Why a slot's emitted price must equal its genesis level — and how that failed.*
-- **The invariant**: `order.price === priceForSlot(idx, genesis)`, and why range guards cannot substitute for it
-- **Failure mechanism**: Chain price overwriting slot identity, pre-broadcast substitution, untrusted fill-guard pivot
-- **Enforcement**: The six emission sites, the blocking rejection of off-grid emissions, and the fail-open policy on unjudgeable inputs
-- **Out-of-bounds policy**: Hold and surface; refill in-grid slots at their genesis price
-- **Status**: What is landed, what remains open, and why the removed 5% sanity gate must not be naively re-landed
-
-### 🧪 [Test Suite](../tests/README.md)
-*Test organization, categories, and key architectural patterns tested.*
-- **Test Layout**: Directory structure, helpers, and quick-start commands
-- **Categories**: Core infrastructure, order management, COW rebalancing, fees/accounting, integration, edge cases, and more
-- **Architectural Patterns**: COW rebalancing, RMS divergence, and fund invariants with doc cross-references
-
-### 💰 [Fund Movement & Accounting](FUND_MOVEMENT_AND_ACCOUNTING.md)
-*The most critical part of the bot: safe capital management.*
-- **Single Source of Truth**: How the bot avoids double-spending and out-of-sync balances.
-- **Optimistic ChainFree**: The mechanism that allows the bot to trade with fill proceeds before they are finalized on-chain.
-- **Fill Batch Processing**: Fixed-cap batching for efficient fill processing (`<=4` unified, `>4` chunked)
-- **Partial Order Consolidation**: Simplified, direct consolidation through grid rebuilding (no merge/split mechanics)
-- **Dust Detection & Management**: Partials below the dust threshold are cancelled on-chain immediately on detection (no delay, no timer)
-- **BTS Fee Object Structure**: `netProceeds` field for accounting precision
-- **BUY Side Sizing & Fee Accounting**: Correct fee application by order side
-- **Mixed Order Fund Validation**: Separate validation for BUY vs SELL order fund checks
-- **Fee Management**: Detailed logic for BTS fee reservations and market fee deductions.
+### 🧮 [DEXBot vs DEXBot2 Comparison](DEXBOT_COMPARISON.md)
+*Architectural, functional, and operational comparison with the original Python DEXBot.*
+- **Scope**: Full side-by-side of technology stack, architecture, trading strategies, order management, configuration, blockchain integration, fund accounting, and concurrency safety
+- **Audience**: Developers and operators evaluating or migrating between the two projects
 
 ---
 

package/docs/architecture.md

@@ -377,13 +377,13 @@ The fill pipeline handles incoming filled orders efficiently through fixed-cap b
                       ↓
 ┌─────────────────────────────────────────────────────────────┐
 │             processFilledOrders() - Entry Point             │
-│    Use gap-slot batch size for deterministic batching   │
-│      Rules: <=gapSlots unified, >gapSlots chunked      │
+│    Use gap-slot batch size (gapSlots+1) for deterministic batching   │
+│      Rules: <=gapSlots+1 unified, >gapSlots+1 chunked      │
 └─────────────────────┬───────────────────────────────────────┘
                       ↓
 ┌─────────────────────────────────────────────────────────────┐
-│            Pop Batch (up to gapSlots)                     │
-│        Takes N fills from queue head (N = 1..gapSlots)     │
+│            Pop Batch (up to gapSlots+1)                     │
+│        Takes N fills from queue head (N = 1..gapSlots+1)     │
 │   Example: pops [fill1, fill2, fill3] for batch processing  │
 └─────────────────────┬───────────────────────────────────────┘
                       ↓
@@ -418,9 +418,9 @@ The fill pipeline handles incoming filled orders efficiently through fixed-cap b
 
 ### Key Properties
 
-- **Gap-Slot Batch Sizing**: Batch size is deterministic, derived from the grid gap-slot count (`DEXBot._getGapSlotBatchSize`)
-  - 1..gapSlots awaiting: single unified batch (one rebalance/broadcast cycle)
-  - more than gapSlots awaiting: repeated chunks of gapSlots (last chunk may be smaller)
+- **Gap-Slot Batch Sizing**: Batch size is deterministic, derived from the grid gap-slot count + 1 (`DEXBot._getGapSlotBatchSize`)
+  - 1..gapSlots+1 awaiting: single unified batch (one rebalance/broadcast cycle)
+  - more than gapSlots+1 awaiting: repeated chunks of gapSlots+1 (last chunk may be smaller)
 
 - **Single Rebalance Cycle**: All fills in batch processed in ONE rebalance
   - No "split across cycles" delays
@@ -916,7 +916,7 @@ graph TB
     START[Grid Update Triggered] --> CALC[Calculate Ideal Grid<br/>Based on current funds]
     CALC --> RELOAD[Force Reload Persisted Grid<br/>Ensure fresh blockchain state]
     RELOAD --> COMPARE[Compare to Persisted Grid]
-    COMPARE --> RMS[Calculate RMS Divergence<br/>For PARTIAL orders only]
+    COMPARE --> RMS[Calculate RMS Divergence<br/>ACTIVE + VIRTUAL orders per side]
 
     RMS --> CHECK{RMS > Threshold?}
     CHECK -->|Yes| UPDATE[Update Grid Sizes<br/>Trigger rebalance]
@@ -1043,28 +1043,17 @@ graph LR
 
 The system has been optimized to use a "memory-driven" model for order updates, eliminating redundant blockchain API calls during normal operation.
 
-### Key Changes
-
-**1. Raw Order Cache (`rawOnChain`)**
-- Grid slots now store exact blockchain order representations (integers/satoshis) in a `rawOnChain` cache
-- **Birth**: Cache populated immediately after successful order placement using broadcasted arguments
-- **Partial Fills**: Cache updated in-place via integer subtraction (subtracting filled satoshis from `for_sale`)
-- **Updates/Rotations**: Cache refreshed with adjusted integers returned by build process
-
-**2. Eliminated Redundant API Calls**
-- Removed all `readOpenOrders()` calls from `_buildSizeUpdateOps()` and `_buildRotationOps()`
-- Removed `computeVirtualOpenOrders()` logic that was redundantly fetching entire account state
-- The bot now trusts its internal state, backed by real-time fill listener, to build transactions
-
-**3. Refactored `buildUpdateOrderOp()`**
-- Updated to support optional `cachedOrder` parameter
-- Allows callers to bypass blockchain queries if they have raw state in memory
-- Returns `finalInts` along with operation data for local tracking
-
-**4. Self-Healing Resilience**
-- Maintains "State Recovery Sync" fallback
-- If a memory-driven transaction fails, bot catches error and performs a full refresh
-- Ensures internal ledger stays synchronized with BitShares blockchain
+### How it works
+
+- **Raw order cache (`rawOnChain`):** each grid slot stores the exact blockchain order integers
+  (satoshis) — seeded from broadcast arguments on placement, updated in place on partial fills,
+  and refreshed on updates/rotations.
+- **Chain-free planning:** size updates and rotations build their operations from the cache;
+  only placements and recovery syncs query the blockchain.
+- **`buildUpdateOrderOp(cachedOrder?)`:** accepts an optional cached order and returns
+  `finalInts` alongside the operation for local tracking.
+- **Self-healing:** a failed memory-driven transaction triggers a full state-recovery sync so the
+  internal ledger stays consistent with the chain.
 
 ### Benefits
 - **Faster reaction time**: No waiting for blockchain queries during order updates

package/docs/developer_guide.md

@@ -79,7 +79,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
 
 | Term | Meaning |
 |------|---------|
-| **Gap-Slot Batch Fill Processing** | Groups fills using the grid gap-slot count as batch size (`DEXBot._getGapSlotBatchSize`): `<= gapSlots` uses one unified batch; `> gapSlots` chunks at gapSlots. In the documented 29-fill Feb 7 crash scenario, this reduces the estimated divergence window from ~90s to ~24s; see [`FUND_MOVEMENT_AND_ACCOUNTING.md`](FUND_MOVEMENT_AND_ACCOUNTING.md#15-fill-batch-processing--timeline). |
+| **Gap-Slot Batch Fill Processing** | Groups fills using the grid gap-slot count + 1 as batch size (`DEXBot._getGapSlotBatchSize`): `<= gapSlots + 1` uses one unified batch; `> gapSlots + 1` chunks at `gapSlots + 1`. In the documented 29-fill Feb 7 crash scenario, this reduces the estimated divergence window from ~90s to ~24s; see [`FUND_MOVEMENT_AND_ACCOUNTING.md`](FUND_MOVEMENT_AND_ACCOUNTING.md#15-fill-batch-processing--timeline). |
 | **Recovery Retry System** | Count+time-based retry mechanism with periodic reset. Replaces one-shot `_recoveryAttempted` flag. Max 5 attempts per episode with 60s minimum interval between retries. |
 | **Orphan-Fill Deduplication** | Map+TTL-based tracking of stale-cleaned order IDs to prevent double-crediting. Delayed orphan fill events are still blocked by checking `_staleCleanedOrderIds`. |
 
@@ -171,8 +171,8 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
 | **Atomic Check-and-Deduct** | Verify funds + deduct in single operation |
 | **Divergence Detection** | Comparing ideal grid vs. persisted grid |
 | **Invariant Verification** | Checking fund accounting consistency |
-| **Batch Processing** | Grouping multiple fills into a single rebalance cycle instead of one-at-a-time. Gap-slot sizing: `<= gapSlots` unified, otherwise chunked at gapSlots. |
-| **Gap-Slot Batch Sizing** | Deterministic chunking model with the grid gap-slot count as the per-broadcast bound. Keeps throughput high while avoiding tier-lookup complexity. |
+| **Batch Processing** | Grouping multiple fills into a single rebalance cycle instead of one-at-a-time. Gap-slot sizing: `<= gapSlots + 1` unified, otherwise chunked at `gapSlots + 1`. |
+| **Gap-Slot Batch Sizing** | Deterministic chunking model with the grid gap-slot count + 1 as the per-broadcast bound. Keeps throughput high while avoiding tier-lookup complexity. |
 | **Stale-Order Recovery** | Fast-path recovery for single-operation batches that encounter stale orders on-chain. Executes cleanup without full state sync. |
 | **Orphan-Fill Prevention** | Deduplication mechanism that prevents double-crediting fills from stale-cleaned orders using timestamp-based ID tracking (TTL pruning). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
   "main": "dist/modules/dexbot_class.js",
   "exports": {

package/scripts/git-viewer.sh

@@ -44,7 +44,7 @@ check_dependencies() {
         elif command -v dnf &> /dev/null; then
             sudo dnf install -y "${missing_packages[@]}"
         elif command -v pacman &> /dev/null; then
-            sudo pacman -S --noconfirm "${missing_packages[@]}"
+            sudo pacman -Syu --noconfirm "${missing_packages[@]}"
         else
             echo "Warning: Could not detect package manager. Please install manually: ${missing_packages[@]}"
             echo "  apt-get: sudo apt-get install ${missing_packages[*]}"

package/tests/README.md

@@ -88,7 +88,7 @@ Interactive tools and performance benchmarks (not part of CI).
 
 ### Edge Cases & Regression
 Tests targeting specific bugs, race conditions, and failure modes.
-*Examples:* `test_critical_bug_fixes.ts`, `test_race_condition_fixes_batch1.ts`, `test_patch17_invariants.ts`, `test_shutdown_reentrancy.ts`, `test_multifill_opposite_partial.ts`
+*Examples:* `test_critical_bug_fixes.ts`, `test_race_condition_fixes_batch1.ts`, `test_patch17_invariants.ts`, `test_shutdown_reentrancy.ts`, `test_multifill_opposite_partial.ts`, `test_correction_queue_staleness.ts`, `test_spread_pure_fund_driven.ts`, `test_sync_lock_id_verification.ts`
 
 ### Utilities & Helpers
 Shared utility functions, precision handling, chain helpers.
@@ -120,6 +120,15 @@ Shared utility functions, precision handling, chain helpers.
 
 **Reference:** [docs/FUND_MOVEMENT_AND_ACCOUNTING.md](../docs/FUND_MOVEMENT_AND_ACCOUNTING.md)
 
+### Grid-Price Invariant & Hold Guards
+- Every emitted order's price must equal its slot's genesis level (`priceForSlot(idx, genesis)`); off-grid emissions are blocked, not counted
+- The guard itself plus the live batch wiring, escalation thresholds, and per-order stranded-hold clocks are each pinned and mutation-tested
+- Adoption keeps the slot's own level; `loadGrid` repairs a pre-existing off-grid slot price
+
+**Reference:** [docs/GRID_PRICE_INVARIANT.md](../docs/GRID_PRICE_INVARIANT.md)
+
+**Examples:** `test_grid_price_invariant_guard.ts`, `test_grid_price_invariant_wiring.ts`, `test_grid_price_slot_invariant.ts`, `test_final_pivot_gate.ts`, `test_hold_and_center_guards.ts`, `test_sync_out_of_grid_defer.ts`
+
 ---
 
 ## Documentation References