dexbot 1.4.20 → 1.4.22

package/docs/GRID_RECONCILE.md

@@ -78,16 +78,16 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
 
 ### Phase 1 — Pure Planning Under `_gridLock`
 
-**`grid_reconcile.ts:205-356`**
+**`grid_reconcile.ts:208-375`**
 
-1. **Phantom order sanitization** (lines 211-244): 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:
-   - **Freshly-assigned deferral** (lines 215-233): an `orderId` assigned within `TIMING.SYNC_LOCK_TIMEOUT_MS` (via `manager._orderIdAssignedAt`) 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.
-   - **Ghost heuristic** (line 225): an order with `size <= 0` && `PARTIAL` (a known filled ghost) still passes through so known fills get cleaned up.
+1. **Phantom order sanitization** (lines 216-245): 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:
+   - **Freshly-assigned deferral** (lines 226-235): an `orderId` assigned within `TIMING.SYNC_LOCK_TIMEOUT_MS` (via `manager._orderIdAssignedAt`) 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.
+   - **Ghost heuristic** (line 229): an order with `size <= 0` && `PARTIAL` (a known filled ghost) still passes through so known fills get cleaned up.
    - Virtualization always uses `{ skipAccounting: true }` so startup cleanup never inflates `ChainFree`.
 
-2. **Duplicate detection** (lines 246-311): For each unmatched chain order, find the nearest active same-side grid order. If `priceDiff ≤ tolerance × 5`, flag it as a suspected duplicate and queue for a Phase 2 cancel (never cancelled under lock). Tolerance is computed from price impact via `calculatePriceTolerance`: capped at `PRICE_TOLERANCE_MAX_PERCENT` (1%) with a `PRICE_TOLERANCE_MIN_ABSOLUTE` (0.0001) floor. Duplicate IDs are removed from the unmatched set so they aren't also paired for updates/creates.
+2. **Duplicate detection** (lines 258-331): For each unmatched chain order, find the nearest active same-side grid order. If `priceDiff ≤ tolerance × 5`, flag it as a suspected duplicate and queue for a Phase 2 cancel (never cancelled under lock). Tolerance is computed from price impact via `calculatePriceTolerance`: capped at `PRICE_TOLERANCE_MAX_PERCENT` (1%) with a `PRICE_TOLERANCE_MIN_ABSOLUTE` (0.0001) floor. Duplicate IDs are removed from the unmatched set so they aren't also paired for updates/creates.
 
-3. **Per-side reconciliation** via `_reconcileStartupSide(planOnly=true)` (lines 323-353):
+3. **Per-side reconciliation** via `_reconcileStartupSide(planOnly=true)` (lines 343-372):
    - Count `matchedOnGrid` (active grid orders with `orderId`)
    - `neededSlots = targetCount - matchedOnGrid`; pick virtual slots to activate
    - Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
@@ -99,29 +99,29 @@ Returns `{ plannedCreates, plannedUpdates, plannedCancels, chainSellCount, chain
 
 ### Phase 2 — Blockchain Execution Outside Lock
 
-**`grid_reconcile.ts:358-480`**
+**`grid_reconcile.ts:376-500`**
 
 Each sub-phase releases `_gridLock` before starting and re-acquires it per operation (through `synchronizeWithChain` in individual helpers). No single long-held lock blocks fills, sync, or divergence checks — but each operation still runs under the lock for consistency.
 
-**Cancellations** (lines 366-391): Execute `plannedCancels`. Each `_cancelChainOrder` acquires `_gridLock` internally. This covers duplicate cancels, edge-release cancels, and excess-order cancels.
+**Cancellations** (lines 384-411): Execute `plannedCancels`. Each `_cancelChainOrder` acquires `_gridLock` internally. This covers duplicate cancels, edge-release cancels, and excess-order cancels.
 
-**Updates** (lines 393-465):
+**Updates** (lines 413-485):
 - Batch via `_executeStartupUpdateBatch` when `supportsBatchUpdate` is available
 - Retry up to 3× (`maxBatchAttempts = 3`)
 - On each failure: `_recoverStartupSyncFailure()` re-fetches open orders from chain (guarded read) and re-syncs `manager` state via `manager.syncFromOpenOrders()`, then `_refreshStartupUpdatePlans()` rebuilds plans against the fresh chain state
 - If retries exhausted or batch helpers are unavailable → `_executeStartupSequentialUpdateFallback()` one-by-one with per-failure recovery
 
-**Creates** (lines 467-480): `_executePlannedStartupCreates` runs with the outside-in pair grouping — grouped from the outermost grid slots toward the center, BUY descending / SELL ascending, so the most price-critical orders are placed first. BitShares DEX batch-create operations are used where supported. Every created chain ID is captured into `phase2CreatedOrderIds` so Phase 3 cannot later cancel the freshly-created orders.
+**Creates** (lines 487-500): `_executePlannedStartupCreates` runs with the outside-in pair grouping — grouped from the outermost grid slots toward the center, BUY descending / SELL ascending, so the most price-critical orders are placed first. BitShares DEX batch-create operations are used where supported. Every created chain ID is captured into `phase2CreatedOrderIds` so Phase 3 cannot later cancel the freshly-created orders.
 
 ### Phase 3 — Fresh Re-read, Adoption, Stale Surplus Cleanup
 
-**`grid_reconcile.ts:502-631`** (guarded by `if (!dryRun)` at line 504)
+**`grid_reconcile.ts:502-641`** (guarded by `if (!dryRun)` at line 504)
 
 1. **Guarded fresh re-read** (lines 512-516): `readOpenOrdersGuarded` re-fetches all open orders. On a truncated/empty read it returns early (defers), keeping the pre-Phase-2 counts for the summary log — a capped window omits exactly the freshest Phase-2 creates.
 
 2. **Adopt uncertain-landed creates** (lines 533-578): For any fresh chain order not matching a grid `orderId` and not created by a slot, it attempts targeted slot adoption — matching a VIRTUAL slot by type+price+size (within tolerance) and registering it via `_applySync(..., 'createOrder')` with the create-fee deduction. Full `syncFromOpenOrders` is deliberately **not** used here (its pass-1 virtualizes ACTIVE slots missing from the snapshot, and a lagging read right after the Phase-2 broadcast would destroy the confirmed grid). If adoption fails, the ID is still protected from surplus-cancel; the next sync loop's orphan adoption registers it.
 
-3. **Stale surplus cancellation** (lines 579-599): Per side, count orders exceeding `targetCount` that no grid slot holds via `orderId` (including the phase-2 created IDs). Cancel only these untracked surplus orders, sorted by chain ID for determinism. This catches orphans lost during grid reinitialization — on-chain orders with no corresponding grid slot.
+3. **Stale surplus cancellation** (lines 579-625): Per side, count orders exceeding `targetCount` that no grid slot holds via `orderId` (including the phase-2 created IDs). Cancel only these untracked surplus orders, sorted by chain ID for determinism. This catches orphans lost during grid reinitialization — on-chain orders with no corresponding grid slot.
 
 ### Partial Failure State
 
@@ -130,8 +130,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:1122`), applied via `Promise.race` at `grid.ts:1217`.
-- Every internal chain read goes through `readOpenOrdersGuarded` (`chain_orders.ts:611`) 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: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.
 
 ---
 
@@ -139,7 +139,7 @@ If Phase 2 partially succeeds (some cancels, some creates fail), there is no rol
 
 ### Fresh Grid Guard (`matchedOnGrid > 0`)
 
-**`grid_reconcile_internal.ts:1604-1616`**
+**`grid_reconcile_internal.ts:1600`**
 
 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:
 
@@ -153,11 +153,11 @@ When `matchedOnGrid === 0` AND scaling up (`neededSlots > 0`), excess cancellati
 
 ### Grid-Edge Lock
 
-**`grid_reconcile_internal.ts:259`** — `_isGridEdgeFullyActive` detects when the grid boundary is fully active (all slots on-chain) before cancelling excess orders.
+**`grid_reconcile_internal.ts:244`** — `_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 329) 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 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.
 
-Detection (`_isGridEdgeFullyActive`, line 259): sort orders by price (BUY descending, SELL ascending), and check the outermost ones are all `isOrderPlaced()`.
+Detection (`_isGridEdgeFullyActive`, line 244): sort orders by price (BUY descending, SELL ascending), and check the outermost ones are all `isOrderPlaced()`.
 
 ### Duplicate Tolerance (5× Multiplier)
 
@@ -181,10 +181,10 @@ Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen mast
 
 ### Truncated-Read Ambiguity (since 1.4.8)
 
-Every chain read feeding an absence/surplus decision goes through `readOpenOrdersGuarded` (`chain_orders.ts:611`) 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:610`) and treats an empty or truncated snapshot as **unreadable** — never as "nothing landed" or "nothing to cancel":
 
-- `_recoverSyncFromChain` (`grid_reconcile_internal.ts:607`) — 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:947`) defers to an uncertain outcome on truncated reads, and the startup group batch uncertain verification follows the same rule.
+- `_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.
 - Adoption paths (`_adoptPossiblyLandedCreate`, grouping path, reconcile adoption loop) apply the create-fee deduction via `_applySync` for accounting parity.
 
@@ -194,7 +194,7 @@ The underlying rule is `INV-BROADCAST-004`: a capped `get_full_accounts` window
 
 ## Lock Hierarchy
 
-**`manager.ts:471-486`** — canonical reference in [`developer_guide.md`](developer_guide.md#lock-ordering-for-deadlock-prevention).
+**`manager.ts:474-489`** — canonical reference in [`developer_guide.md`](developer_guide.md#lock-ordering-for-deadlock-prevention).
 
 ```
 Level 0: _fillProcessingLock    Level 1: _divergenceLock
@@ -224,7 +224,7 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
 | `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:805` | Base pipeline timing; resync uses 2× (10 min) |
+| `PIPELINE_TIMING.TIMEOUT_MS` | `300000` (5min) | `constants.ts:800` | Base pipeline timing; resync uses 2× (10 min) |
 
 ---
 
@@ -250,7 +250,7 @@ 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 (1690 lines) |
+| `modules/order/grid_reconcile_internal.ts` | Internal helpers — `_reconcileStartupSide`, grid detection, recovery, uncertainty (1675 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/sync_engine.ts` | Blockchain sync pipeline |

package/docs/LIFECYCLE.md

@@ -134,7 +134,7 @@ sequenceDiagram
     participant STORE as Storage
 
     MA->>CL: AMA center snapshot updated
-    CL->>CL: _performPeriodicGridChecks()  (dexbot_class.ts:1664)
+    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)
@@ -158,10 +158,10 @@ 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:1769`). The grid maintenance
+> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1794`). The grid maintenance
 > chain above is the one that matters for order/price upkeep.
 
-References: `modules/dexbot_class.ts:1664` (`_performPeriodicGridChecks`) →
+References: `modules/dexbot_class.ts:1694` (`_performPeriodicGridChecks`) →
 `modules/dexbot_maintenance_runtime.ts:1043` (`performPeriodicGridChecks`) →
 `:1845` (`runGridMaintenance`) → `:1452` (`executeMaintenanceLogic`),
 `docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
@@ -191,7 +191,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:1664` |
+| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1694` |
 | 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/LOGGING.md

@@ -309,7 +309,7 @@ Yes — each bot entry in `profiles/bots.json` accepts an optional `logging` fie
 }
 ```
 
-The per-bot `logging` is deep-merged on top of the global config from `general.settings.json`. See `modules/types.ts` (`BotLoggingOverrides`), `modules/runtime_settings.ts`, and `modules/order/manager.ts` for the wiring.
+The per-bot `logging` is deep-merged on top of the global config from `general.settings.json`. See `modules/runtime_settings.ts` for the merge logic and `modules/order/manager.ts` for where the merged config reaches the logger.
 
 **Q: What about PM2?**
 The logger auto-detects PM2 and suppresses file writes (PM2 captures stdout/stderr). File rotation is also suppressed under PM2.

package/docs/MPA_CREDIT_USAGE.md

@@ -233,7 +233,7 @@ When `maxBorrowAmountPerOperation` is set, each credit-maintenance cycle runs `_
 
 - Discovers deals whose `debtAmount` exceeds `maxBorrowAmountPerOperation`.
 - Splits each oversized deal into `ceil(debt / maxPerOp)` equal pieces via atomic repay+reborrow transactions. Total debt across the new deals is preserved; only deal granularity changes.
-- Skips a deal if any piece would fall below the offer's `min_deal_amount` (the offer is cached for the runtime lifetime, so on-chain `min_deal_amount` changes mid-split are not re-read).
+- Skips a deal if any piece would fall below the offer's `min_deal_amount` (offers are cached with a 10-minute TTL — `TIMING.OFFER_CACHE_TTL_MS` — so on-chain `min_deal_amount` changes are picked up on the next re-fetch).
 - Pauses `BLOCKCHAIN_SETTLE_DELAY_MS` between pieces; aborts on shutdown.
 - Stops once `CREDIT_DEAL_SPLIT_MAX_PIECES` pieces have been emitted in the current cycle. Remaining oversized deals are deferred to the next maintenance cycle.
 - Uses an in-process `_splitInFlight` guard so `runMaintenance` and `runCreditWatchdog` cannot start overlapping splits.
@@ -342,12 +342,12 @@ Treat this file as runtime state, not primary configuration. The source of truth
 
 - `modules/credit_runtime.ts`: debt workflow executor (Phase 0 oversized-deal splitter lives here)
 - `modules/cr_planner.ts`: MPA debt-first planner; clamps `debtDelta` by `maxBorrowAmountPerOperation`
-- `modules/types.ts`: `LendingEntryBase` — shared `mpa` / `creditOffer` type including `maxBorrowAmountPerOperation`
+- `modules/cr_planner.ts`: `DebtFirstCrPlanOptions` — planner options carrying `maxBorrowAmountPerOperation`; lending-item shapes are validated inline in `bot_settings.ts`
 - `modules/dexbot_class.ts`: runtime startup and watchdog lifecycle
 - `modules/bot_settings.ts`: `debtPolicy` validation
 - `market_adapter/README.md`: AMA pricing, grid triggers, and dynamic-weight runtime
 - `modules/credential_policy.ts`: signing constraints for credit and call-order operations
-- `tests/test_credit_runtime.ts`: credit runtime behavior coverage (including 6 oversized-deal splitter tests)
+- `tests/test_credit_runtime.ts`: credit runtime behavior coverage (including 3 oversized-deal splitter tests)
 - `tests/test_multi_asset_distribution.ts`: collateral distribution and multi-asset state coverage
 
 </details>

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.4.17 (released).
+**Version context:** v1.4.21 (released).
 
 ---
 
@@ -144,7 +144,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 
 ### 🧭 [Evolution Report](EVOLUTION.md)
 *Project timeline and major architecture phases.*
-- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.4.20 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
+- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.4.22 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
 - **Focus**: Architecture evolution, release history, test growth, and documentation changes
 
 ### 🗒️ [Changelog](../CHANGELOG.md)

package/docs/WORKFLOW.md

@@ -211,7 +211,7 @@ recommended mode:
 - **Single process** — no PM2, no separate credential daemon management
 - **Auto-update** — detects new releases, builds, and restarts cleanly
 - **Crash restart** — background mode re-spawns on failure
-- **Per-bot log files** — each bot logs to `profiles/logs/<bot>.log`
+- **Per-bot log files** — each bot logs to `<profiles>/logs/<bot>.log` (`~/.config/dexbot2/profiles/logs` by default)
 - **Built-in daemon** — the credential daemon is managed internally
 
 Legacy PM2 mode (`npm run pm2:unlock`) is de-emphasized but still available.
@@ -257,7 +257,7 @@ the canonical name is preferred in scripts and docs.
 | `dexbot restart` | `restartall` | Restart the monolithic runtime (unlock mode) |
 | `dexbot delete` | — | Shut down and clean up the monolithic runtime (unlock mode) |
 | `dexbot whitelist` | `white` | Generate market adapter whitelist from AMA bot configs |
-| `dexbot clear` | — | Remove all log files from `profiles/logs/` |
+| `dexbot clear` | — | Remove all log files from the logs directory (`<profiles>/logs`) |
 
 ## NPM Scripts for Branch Synchronization
 

package/docs/architecture.md

@@ -548,12 +548,11 @@ The simplified approach prioritizes fund availability over aggressive correction
 Spread corrections respect these hard limits:
 
 ```javascript
-// In modules/constants.ts
-SPREAD_LIMITS: {
-    MIN_SPREAD_ORDERS: 2,           // Always maintain minimum gap
-    TARGET_SPREAD_PERCENT: (user-configured),  // Fixed width, no inflation
-    MAX_REPLACEMENT_SLOTS: 5,       // Conservative correction cap
-}
+// In modules/constants.ts (GRID_LIMITS)
+MIN_SPREAD_ORDERS: 2,           // Always maintain minimum gap
+
+// Spread width itself stays user-configured (`targetSpreadPercent`) — fixed, no inflation.
+// Correction count has no separate slot cap; it is bounded by the funds check below.
 
 // Each correction order must be healthy
 const minHealthySize = calculateMinOrderSize(side);
@@ -590,28 +589,31 @@ BLOCKCHAIN_FETCH_INTERVAL_MIN: 240,  // 4 hours = 240 minutes
 
 ### Implementation Flow
 
+**1. Interval startup** — `setupBlockchainFetchInterval()` in
+`modules/dexbot_maintenance_runtime.ts` starts the interval during bot initialization:
+
 ```javascript
-// 1. Timer started during bot initialization
-this.periodicRefreshTimer = setInterval(
-    () => this._performPeriodicRefresh(),
-    BLOCKCHAIN_FETCH_INTERVAL_MIN * 60 * 1000
-);
-
-// 2. When timer fires:
-async _performPeriodicRefresh() {
-    // Fetch latest market price
-    const latestPrice = await derivePrice('book');  // Or 'pool'
-
-    // Update internal anchor if using dynamic pricing
-    if (config.startPrice === 'book' || config.startPrice === 'pool') {
-        this.manager.startPrice = latestPrice;
-    }
-
-    // Grid remains un-affected (fund-driven during normal ops)
-    // Only used for valuation calculations and divergence checks
-}
+bot._blockchainFetchInterval = setInterval(tick, BLOCKCHAIN_FETCH_INTERVAL_MIN * 60 * 1000);
 ```
 
+**2. Tick guards** *(no lock held)*
+- Skip if shutdown has begun or a previous tick is still in flight
+- Sync market adapter watchdog config
+
+**3. Periodic work** *(under the fill-processing lock)*
+- Reset accountant recovery state
+- Refresh dynamic weight distribution
+- `fetchAccountTotals(accountId)` — refreshes balances and the valuation anchor
+- Read open orders via guarded read — truncated/empty reads defer the sync; fills are still caught by subscriptions and the next cycle
+- `synchronizeWithChain(...)` — re-aligns the grid with on-chain reality; detected fills run through the normal batched rebalance pipeline and the grid is persisted, unmatched chain orders log as surplus/divergence
+- `performPeriodicGridChecks(bot)` — maintenance checks (see [Lifecycle](LIFECYCLE.md))
+
+Grid placement remains fund-driven during normal operation; the periodic tick keeps
+balances, valuations, and open-order state fresh rather than directly moving prices.
+A per-instance override (`_blockchainFetchIntervalMin`, e.g. for shared accounts from
+the fund registry) can shorten or lengthen the interval; setting a non-positive value
+disables the loop entirely.
+
 ### When `startPrice` is Numeric
 
 If user set `startPrice: 105.5` in bots.json:
@@ -780,10 +782,10 @@ stateDiagram-v2
 
 A **phantom order** is an illegal state where an order exists as ACTIVE/PARTIAL without a corresponding blockchain `orderId`. This corrupts fund tracking and causes "doubled funds" warnings.
 
-**Why Phantoms Occur**:
-1. **Grid Resize Bug**: `Grid._updateOrdersForSide()` could force VIRTUAL → ACTIVE without blockchain confirmation
-2. **Sync Gap**: Orders without orderId could remain ACTIVE indefinitely if sync logic skipped them
-3. **No Validation**: No centralized check prevented invalid state assignments
+**Risks the Three-Layer Defense Guards Against**:
+1. **Resize State Forcing**: Grid resize forcing VIRTUAL → ACTIVE without blockchain confirmation
+2. **Sync Gaps**: Orders without `orderId` remaining ACTIVE if sync logic skips them
+3. **Unvalidated Assignment**: Invalid state assignments without a centralized check
 
 **Prevention System** (Three-Layer Defense):
 
@@ -983,7 +985,7 @@ graph TB
     SKIP --> DONE
 ```
 
-**Key Improvement (v1.0.0)**: Force reload mechanism now ensures fresh persisted grid data before comparison, preventing stale cache from causing false divergence detections.
+The force reload mechanism loads fresh persisted grid data before comparison, preventing stale cache from causing false divergence detections.
 
 ---
 
@@ -1150,9 +1152,12 @@ The system continuously monitors three mathematical invariants:
 
 ### Index Consistency
 
-- **Validation**: `validateIndices()` checks Map ↔ Set consistency
-- **Repair**: `_repairIndices()` rebuilds indices if corruption detected
-- **Defensive**: Called after critical operations
+- **Grid versioning**: `_gridVersion` is bumped on every grid mutation; the
+  `_ordersByType` / `_ordersByState` index caches invalidate automatically when the
+  version changes (no manual rebuild step)
+- **Structural checks**: tests use `assertOrdersStructurallySound()`
+  (`tests/helpers/order_test_helpers.ts`) to verify every order in the Map is non-null
+  with valid `state` and `type`
 
 ---
 
@@ -1234,15 +1239,15 @@ graph LR
 npm test
 
 # Specific logic area
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Signal tests
-tsx tests/test_market_adapter_signal_gates.ts
-tsx tests/test_dynamic_weight_override_wiring.ts
+node dist/tests/test_market_adapter_signal_gates.js
+node dist/tests/test_dynamic_weight_override_wiring.js
 
 # Credit/debt tests
-tsx tests/test_cr_planner.ts
-tsx tests/test_dexbot_credit_wiring.ts
+node dist/tests/test_cr_planner.js
+node dist/tests/test_dexbot_credit_wiring.js
 ```
 
 ### Test Quality Metrics
@@ -1278,7 +1283,7 @@ tsx tests/test_dexbot_credit_wiring.ts
 
 3. **Verify invariants**
    ```javascript
-   expect(manager.validateIndices()).toBe(true);
+   assertOrdersStructurallySound(manager);  // Order Map structurally valid
    expect(chainTotal === chainFree + chainCommitted).toBe(true);
    ```
 
@@ -1382,7 +1387,7 @@ The strategy engine has been significantly strengthened with improvements to fun
 - Before executing batch order placements, available funds are validated
 - Prevents insufficient fund errors during large rotation cycles
 - Uses atomic check-and-deduct pattern for safety
-- Located in: `modules/order/strategy.ts` - `rebalanceSideRobust()`
+- Located in: `modules/dexbot_cow_runtime.ts` - `validateOperationFunds()`
 
 **2. Dust Partial Handling**
 - Improved dust detection algorithm prevents false positives
@@ -1408,9 +1413,9 @@ The strategy engine has been significantly strengthened with improvements to fun
 - Located in: `modules/order/manager.ts` - `processFilledOrders()`
 
 **6. Precision Spread Management (Logarithmic Logic)**
-- **Discrete Step Tracking**: Replaced the legacy linear multiplier (`SPREAD_WIDENING_MULTIPLIER`) with a discrete 1-slot logarithmic buffer. This ensures correction triggers exactly when the market moves by one full increment.
-- **Center-Gap Awareness**: Refined the grid initialization math to account for the "Center Gap" naturally created during symmetric centering. This reduces the initial spread by ~0.5% (one full increment) compared to the previous version.
-- **Collision-Free Safety**: Increased `MIN_SPREAD_FACTOR` to 2.1 to ensure that the security minimum (2 spread orders) never conflicts with the spread correction threshold, even at micro-spread configurations.
+- **Discrete Step Tracking**: A discrete 1-slot logarithmic buffer ensures correction triggers exactly when the market moves by one full increment.
+- **Center-Gap Awareness**: Grid initialization math accounts for the "Center Gap" naturally created during symmetric centering, reducing the initial spread by ~0.5% (one full increment).
+- **Collision-Free Safety**: `MIN_SPREAD_FACTOR` of 2.1 ensures that the security minimum (2 spread orders) never conflicts with the spread correction threshold, even at micro-spread configurations.
 
 ### Related Documentation
 

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 |
 |------|---------|
-| **Fixed-Cap Batch Fill Processing** | Groups fills with a hard cap using `MAX_FILL_BATCH_SIZE` (default 4): `<= cap` uses one unified batch; `> cap` chunks at cap size. 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#14-fill-batch-processing--cache-fund-timeline). |
+| **Fixed-Cap Batch Fill Processing** | Groups fills with a hard cap using `MAX_FILL_BATCH_SIZE` (default 4): `<= cap` uses one unified batch; `> cap` chunks at cap size. 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`. |
 
@@ -226,9 +226,7 @@ If you see prices like `0.000795` when expecting `1350`:
 
 ## Precision & Quantization Best Practices
 
-**Problem**: Floating-point arithmetic accumulates rounding errors over many calculations. After repeated price derivations, fund allocations, and order sizing, float values drift from their true blockchain precision.
-
-**Solution**: Use centralized quantization utilities from `modules/order/utils/math.ts` to eliminate accumulation.
+Floating-point arithmetic accumulates rounding errors across repeated price derivations, fund allocations, and order sizing. Always use the centralized quantization utilities in `modules/order/utils/math.ts` to eliminate accumulation.
 
 ### When to Quantize
 
@@ -304,7 +302,7 @@ _updateOrder(order, context, { skipAccounting, fee })
 // COW rebalance pipeline
 performSafeRebalance(fills, excludeIds)       // Entry point; delegates to COW
 _applySafeRebalanceCOW(fills, excludeIds)     // Creates WorkingGrid, runs planning
-_reconcileGridCOW(targetGrid, boundary, wg)   // Computes delta against working copy
+_workingGrid.buildDelta(masterGrid)          // Computes actions vs master (utils/order.ts buildDelta)
 _commitWorkingGrid(workingGrid, indexes, boundary, { skipRecalc }) // Atomic swap: working → master
 
 // COW state tracking
@@ -630,8 +628,9 @@ if (isOrderHealthy(order, minHealthySize)) {
 #### `getPrecisionSlack(precision, factor)`
 ```javascript
 // Calculate float comparison tolerance for given precision
-// Returns: 10^(-precision) * factor (typically factor = 0.001 = 0.1%)
-const slack = getPrecisionSlack(5, 0.001);  // Returns 0.00001 * 0.001 = 0.00000001
+// Location: modules/order/utils/math.ts
+// Returns: factor * quantumForPrecision(precision) (factor defaults to 2)
+const slack = getPrecisionSlack(5);  // Returns 2 * 10^-5 = 0.00002
 
 // Use case: Floating-point safe comparisons
 if (Math.abs(order.size - expected) <= slack) {
@@ -907,7 +906,7 @@ convention marker — AsyncLock does not enforce it at runtime.
 - Divergence checks (Level 1) nest inside fill processing
 - Sync operations (Level 2) are acquired before grid mutations — the timeout-protected lock is inner, so a stuck sync releases the outer lock
 - Grid mutations (Level 3) and fund operations (Level 4) are innermost
-- All paths follow the same order — the historical `gridLockAlreadyHeld` workaround flag has been eliminated
+- All paths follow the same order
 
 **`adjustTotalBalance` Locking Contract** (v1.4.7):
 
@@ -1240,11 +1239,9 @@ manager.accountant._verifyFundInvariants(
 
 **2. Index Consistency Check**
 ```javascript
-// Periodically
-const isValid = manager.validateIndices();
-if (!isValid) {
-    manager._repairIndices();
-}
+// Index caches invalidate automatically via _gridVersion bumps — no manual
+// validation/repair API exists. For structural checks (e.g. in tests):
+assertOrdersStructurallySound(manager);  // tests/helpers/order_test_helpers.ts
 ```
 
 **3. Grid Diagnostics**
@@ -1499,9 +1496,10 @@ manager.logger.logFundsStatus(manager, 'CONTEXT');
 console.log(manager.getMetrics());
 ```
 
-### Validate Indices
+### Check Order Map Integrity
 ```javascript
-const isValid = manager.validateIndices();
+// Structural check (tests); index caches self-invalidate via _gridVersion
+assertOrdersStructurallySound(manager);
 ```
 
 ### Check Specific Order
@@ -1629,10 +1627,10 @@ The test suite validates the following fund-related behaviors:
 npm test
 
 # Specific logic area
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Specific integration test
-tsx tests/test_fills.ts
+node dist/tests/test_fills.js
 ```
 
 ### Understanding Test Structure
@@ -1705,7 +1703,7 @@ console.log(' - Testing [action] updates [fund pool]...');
     // Assert
     const finalFunds = manager.funds[poolName][side];
     assert.strictEqual(finalFunds, expectedValue);
-    assert.strictEqual(manager.validateIndices(), true);  // Indices OK?
+    assertOrdersStructurallySound(manager);  // Order Map structurally sound?
 }
 ```
 
@@ -1774,7 +1772,7 @@ try {
     // Perform operation
     await fundDependentOperation();
     // Check state consistency
-    assert.strictEqual(manager.validateIndices(), true);
+    assertOrdersStructurallySound(manager);
 } finally {
     manager.unlockOrders(['order-1']);
 }
@@ -1799,13 +1797,13 @@ The test suite provides comprehensive coverage of fund calculations and rebalanc
 **Running Tests**:
 ```bash
 # Test strategy rebalancing
-tsx tests/test_strategy_logic.ts
+node dist/tests/test_strategy_logic.js
 
 # Test grid divergence
-tsx tests/test_grid_logic.ts
+node dist/tests/test_grid_logic.js
 
 # Test accounting precision
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Run full suite
 npm test
@@ -1833,7 +1831,7 @@ manager.orders.forEach(order => {
 });
 
 // 4. Check index consistency
-console.log('Indices valid?', manager.validateIndices());
+assertOrdersStructurallySound(manager);  // throws if any order entry is corrupt
 
 // 5. Examine specific fund pool
 console.log('Virtual buy:', manager.funds.virtual.buy);
@@ -1860,7 +1858,7 @@ A: Check if it's locked (`isOrderLocked()`), in exclusion list, or below dust th
 A: Follow the "How to Add New Features" section above.
 
 **Q: Where are the tests?**  
-A: All tests are in the `tests/` directory. Run `npm test` for the full suite, or `tsx tests/<file>.ts` for individual test files.
+A: All tests are in the `tests/` directory. Run `npm test` for the full suite, or `npm run build:tests && node dist/tests/<file>.js` for individual test files.
 
 ---
 

package/market_adapter/README.md

@@ -573,7 +573,6 @@ market_adapter/
 |-- ama_signal_runner.ts           one-cycle JSON signal CLI
 |-- candle_utils.ts                candle transforms, gap detection, pruning
 |-- interval_utils.ts              shared interval label helpers
-|-- merge_lp_data.ts               candle export merge utility
 |-- lp_chart_core.ts               chart HTML renderer
 |-- lp_chart_strategy_loader.ts    AMA strategy/profile resolver for charts
 |-- lp_chart_runner.ts             LP chart orchestration
@@ -612,7 +611,6 @@ market_adapter/
 |   |-- data_discovery.ts          data directory auto-discovery
 |   |-- atomic_write.ts            atomic file write utility
 |   |-- dynamic_grid_snapshot.ts   dynamic grid snapshot helpers
-|   `-- paths.ts                   path resolution helpers
 |-- data/                          runtime candle caches and exports
 `-- state/                         runtime state, centers, and lock file
 ```

package/modules/README.md

@@ -127,7 +127,8 @@ modules/
 └── utils/
     ├── base58check.ts             Base58Check encoding
     ├── build_dir.ts               BUILD_DIR constant helper
-    └── errors.ts                  getErrorMessage helper
+    ├── errors.ts                  getErrorMessage helper
+    └── sanitize_key.ts            shared sanitizeKey helper
 ```
 
 ## Key Relationships