dexbot 1.6.3 → 1.6.5

package/docs/GRID_RECALCULATION.md

@@ -25,7 +25,7 @@ rebuild around that snapshot.
 | **Initial AMA Snapshot** | Market adapter | Bot has no accepted AMA `gridCenterPrice` yet | Write `dynamicgrid.json`, then write a trigger file | Full grid resync around the first accepted AMA center |
 | **AMA Center Move** | Market adapter | Current AMA center moves past the configured delta threshold | Write `dynamicgrid.json`, then write a trigger file | Full grid resync around the new accepted AMA center |
 | **AMA Slope Range Move** | Market adapter | Range-scaling bot's accepted AMA-slope baseline moves past threshold | Write range-scaling fields to `dynamicgrid.json`, then write a trigger file | Full grid resync with updated asymmetric range/offset data |
-| **RMS Structural Divergence** | Bot runtime maintenance | Current grid shape diverges from persisted/on-chain grid by RMS threshold | Refresh `gridCenterPrice` from latest `amaCenterPrice`, then run full grid resync | Full grid resync from latest market-adapter snapshot |
+| **RMS Structural Divergence** | Bot runtime maintenance | Current grid shape diverges from persisted grid (ACTIVE + VIRTUAL) by RMS threshold | Refresh `gridCenterPrice` from latest `amaCenterPrice`, then run full grid resync | Full grid resync from latest market-adapter snapshot |
 | **Available-Funds Resize** | Bot runtime maintenance | Filled-order proceeds exceed `GRID_REGENERATION_PERCENTAGE` (grow), or grid-tracked size exceeds allocation by that threshold after fund removal (shrink) | Recalculate affected side/order sizes through maintenance logic | Order-size/grid maintenance update, not an AMA recenter trigger |
 
 Each source is evaluated independently. Market-adapter full-resync requests are
@@ -260,27 +260,10 @@ need a reset to move to the new asymmetric range and offset placement price.
 ### Configuration
 
 Range scaling is enabled by the whitelist's `asymmetricBounds: true` flag.
-Generate or update the AMA whitelist with:
-
-```bash
-dexbot white
-```
-
-This writes `profiles/market_adapter_whitelist.json`. The default generation
-enables AMA live writes for new AMA bots, while leaving dynamic weights and
-range scaling disabled.
-
-To opt new AMA entries into range scaling:
-
-```bash
-dexbot white --asymmetric-bounds
-```
-
-To overwrite one existing bot (otherwise preserved):
-
-```bash
-dexbot white --asymmetric-bounds --bot <botKey>
-```
+Set it per bot in the editor: `dexbot bot` → `2) Modify bot` → pick the bot →
+`6) Adapter` → **Range** = yes. The flag is stored in
+`profiles/market_adapter_whitelist.json` next to **Price** (AMA pricing) and
+**Weight** (dynamic weights); all three default to off until enabled.
 
 The snapshot fields involved are:
 
@@ -290,6 +273,14 @@ The snapshot fields involved are:
 - `amaSlopeDeltaPercent`: distance from the accepted baseline
 - `amaSlopeThresholdPercent`: threshold required to trigger the reset
 
+**Trigger threshold.** By default the reset fires when the slope delta crosses
+`AMA_SLOPE_DELTA_THRESHOLD_PERCENT`, a percentage of the AMA max slope
+(`(value/100) × maxSlopePct`) — default `8%`, stored under `MARKET_ADAPTER` in
+`profiles/general.settings.json` and editable via `dexbot bot` → `1) Grid
+Health` (`AMA-Slope Δ`). An explicit `amaSlopeDeltaThresholdPercent` in
+`profiles/market_adapter_settings.json` bypasses the factor and is used
+directly as an average percent-per-bar threshold.
+
 AMA slope values are stored and compared as average percent per bar. Older
 settings that used cumulative percent over the full lookback can either be
 divided by `amaSlope.lookbackBars`, or marked with
@@ -313,17 +304,25 @@ so the adapter converts them when loading overrides. New settings should use
 
 ### What It Does
 Compares the **calculated grid** currently held by the bot with the
-**persisted/on-chain grid state**. When structural divergence exceeds the
-threshold, the bot performs a full grid resync.
+**persisted grid state** (ACTIVE on-chain orders plus VIRTUAL planned
+reservations). When structural divergence exceeds the threshold, the bot
+performs a full grid resync.
+
+**Scope (per side):** the metric covers **ACTIVE + VIRTUAL** orders. PARTIAL
+orders are excluded (expected to deviate mid-fill) and SPREAD placeholders are
+excluded (size-0). VIRTUAL slots carry the planned reservation for unplaced
+rail slots (`funds.virtual`), so a persisted-vs-ideal drift there moves
+`Available = ChainFree − Virtual − fees` and is treated as structural.
 
 **Why it matters:** Order fills, rotations, and fee deductions can make the
-active grid shape drift away from the stored/on-chain picture. RMS divergence
+grid shape drift away from the stored picture. RMS divergence
 detects that structural drift. Once it crosses the threshold, DEXBot rebuilds
 from the latest market-adapter snapshot instead of trying to keep patching the
 old shape.
 
 The RMS calculation compares the runtime grid (calculated from the bot's
-config and live dynamic weights) against the persisted/on-chain grid state.
+config and live dynamic weights) against the persisted grid state
+(ACTIVE + VIRTUAL).
 Crossing the threshold only changes the follow-up action: the bot refreshes
 `gridCenterPrice` from the latest `amaCenterPrice` in `dynamicgrid.json`,
 then runs the full resync path.
@@ -336,7 +335,7 @@ code paths and log differently:
 
 | Path | Fires from | Trigger | Log signature |
 |------|-----------|---------|---------------|
-| **Periodic divergence** | `dexbot_maintenance_runtime.ts` periodic sync loop | `Grid.monitorDivergence()` reports `buy.rms` or `sell.rms` above threshold | `Grid update triggered by structural divergence during periodic: buy=..., sell=...` |
+| **Periodic divergence** | `dexbot_maintenance_runtime.ts` periodic sync loop | `Grid.monitorDivergence()` reports `buy.rms` or `sell.rms` above threshold | `[RMS] Grid update triggered by structural divergence during periodic: buy=...% sell=...% (threshold=...%) sides=... → TRIGGER-RESYNC (rms_structural_grid_resync)` |
 | **Structural recovery (COW guard)** | `dexbot_class.ts` `_wireStructuralGridResyncRequest()` | Order manager detects unmatched chain orders during copy-on-write placement | `[RECOVERY] Running structural full grid resync for <reason> (N unmatched chain order(s))` |
 
 The structural-recovery path is debounced through `_structuralGridResyncTimer`
@@ -376,7 +375,7 @@ and dedupes while one resync is already pending or running.
 ### How It Works
 
 1. **Grid Engine** (`modules/order/grid.ts`) calculates the ideal grid state
-2. Compares with the actual blockchain grid state after fills/rotations
+2. Compares with the persisted grid state — ACTIVE on-chain orders plus VIRTUAL planned reservations — after fills/rotations
 3. Computes RMS divergence metric:
    ```
    RMS = √(mean of ((calculated - persisted) / persisted)²)
@@ -558,11 +557,16 @@ market_adapter_ama_slope_delta_threshold
 
 **RMS Divergence Trigger:**
 ```
-Grid update triggered by structural divergence during periodic: buy=..., sell=...
+[RMS] Grid update triggered by structural divergence during periodic: buy=16.20% sell=2.10% (threshold=14.3%) sides=buy → TRIGGER-RESYNC (rms_structural_grid_resync)
 Grid regeneration triggered. Performing full grid resync...
 Recorded grid reset metadata for dynamic grid state.
 ```
 
+At `debug` level each tick also emits the per-side check detail (mirroring the `[DIVERGENCE]` ratio-check line):
+```
+[RMS] BUY check: metric=...% (threshold=14.3%) → TRIGGER-RESYNC/no trigger | SELL check: metric=...% (threshold=14.3%) → TRIGGER-RESYNC/no trigger
+```
+
 **Available-Funds Resize Trigger:**
 ```
 Grid update triggered by funds during periodic (buy: ..., sell: ...)
@@ -613,6 +617,6 @@ Removed trigger file.
 - `modules/dexbot_class.ts` — `_performGridResync()`, `requestGridReset()`, and COW-guard structural recovery wiring
 - `modules/order/grid.ts` — RMS divergence check and grid comparison
 - `modules/order/manager.ts` — Available-funds resize threshold logic
-- `modules/market_adapter_whitelist.ts` / `scripts/generate_market_adapter_whitelist.ts` — Whitelist generation backing `dexbot white`
+- `modules/market_adapter_whitelist.ts` — Whitelist storage/read helpers (the bot editor's `6) Adapter` reads and writes the same file)
 - `profiles/general.settings.json` — User-editable configuration
 - `profiles/bots.json` — Per-bot configuration including AMA

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
 
 ---
@@ -38,7 +38,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
 │  • Sanitize phantom orders (ACTIVE/PARTIAL with  │
 │    orderId absent on-chain → VIRTUAL, skip);     │
 │    defer freshly-assigned orderIds, ghost pass   │
-│  • Detect suspected duplicates (within 5× tol) → │
+│  • Detect suspected duplicates (exact price) →   │
 │    queue for Phase 2 cancel                      │
 │  • Match unmatched chain orders to virtual slots │
 │    → plan updates                                │
@@ -85,7 +85,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
    - **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 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.
+2. **Duplicate detection** (lines 258-331): 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.
 
 3. **Per-side reconciliation** via `_reconcileStartupSide(planOnly=true)` (lines 343-372):
    - Count `matchedOnGrid` (active grid orders with `orderId`)
@@ -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/LOGGING.md

@@ -243,6 +243,7 @@ Prefix tags used in log messages to help operators identify event types. To find
 | `[SPREAD-CORRECTION]` | `order/grid.ts` | Partial order spread correction |
 | `[STRATEGY]` | `order/strategy.ts` | Fee event cache and strategy decisions |
 | `[RECONCILE]` | `order/utils/validate.ts` | Grid reconciliation ([GRID_RECONCILE.md](GRID_RECONCILE.md)) |
+| `[RMS]` | `order/grid.ts`, `dexbot_maintenance_runtime.ts` | RMS structural-divergence checks: per-side `metric vs threshold → TRIGGER-RESYNC/no trigger` at `debug` (plus a `checks disabled` variant when the threshold is 0), reset line with threshold + breaching sides at `info` |
 | `[GAP-EVAC]` | `order/utils/validate.ts`, `order/manager.ts`, `dexbot_startup_runtime.ts`, `dexbot_state_recovery.ts` | Stuck in-band (gap-band) order streak warnings, cancel-only evacuation teeth, persisted-streak restore counts |
 | `[GRID-TYPE-CORRECT]` | `order/grid.ts` | One-time backfill retype of legacy empty slots to rail-typed holes on load |
 | `[LAST-FILL-GUARD]` | `dexbot_cow_runtime.ts` | Last-fill-guard blocks plus gap-evacuation bypass allows/stale-stamp downgrades |

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.5 (released).
 
 ---
 
@@ -17,7 +17,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 
 ### 📡 [Market Adapter](../market_adapter/README.md)
 *Live AMA pricing, dynamic weights, and recalc trigger orchestration.*
-- **Quick Start**: Enable AMA, generate the whitelist, and start DEXBot2
+- **Quick Start**: Enable AMA, set the per-bot adapter flags in `dexbot bot`, and start DEXBot2
 - **Settings**: Global, pair, and bot-specific adapter overrides
 - **Dynamic Weights**: How adapter signals write live weight snapshots
 - **Troubleshooting**: Common adapter startup and trigger issues
@@ -44,7 +44,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Purpose**: Exposes BitShares capabilities and DEXBot2 infrastructure through JSON/CLI bridges, MCP, and runtime-native skill packaging for OpenClaw and compatible runtimes (see [claw/README.md](../claw/README.md) for the full list).
 - **API Boundary**: Responsibility split between the AI decision layer and the DEXBot2 execution substrate ([AI_BOT_LIBRARY_API.md](../claw/docs/AI_BOT_LIBRARY_API.md))
 - **Tuning Reference**: Practical grid-tuning baselines ([DEXBOT2_TUNING_CHEAT_SHEET.md](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md))
-- **Position Management**: Health monitoring, margin planner, and dynamic weight policy
+- **Position Management**: Short-position tracking, position health monitoring (3-zone CR model), and shared CR planning via `cr_planner.ts`
 - **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, and shared references
 
 ## Operational & Security
@@ -65,19 +65,19 @@ This directory contains the comprehensive technical documentation for the DEXBot
 ### 🔁 [Grid Reconciliation](GRID_RECONCILE.md)
 *How the bot re-aligns its intended grid with on-chain reality at startup.*
 - **3-Phase Plan-then-Execute**: Phase 1 pure in-memory planning under `_gridLock`, Phase 2 blockchain execution outside the lock, Phase 3 fresh re-read and stale surplus cleanup
-- **Safety Guardrails**: Fresh-grid `matchedOnGrid > 0` guard, 5× duplicate tolerance, freshly-assigned deferral, and truncated-read ambiguity handling
+- **Safety Guardrails**: Fresh-grid `matchedOnGrid > 0` guard, exact slot-price duplicate cancel, freshly-assigned deferral, and truncated-read ambiguity handling
 - **Partial Failure State**: No rollback on partial Phase 2 success; remaining mismatches caught by the next maintenance or startup cycle
 - **Lock Hierarchy**: Canonical `_syncLock`/`_gridLock` level reference and the 1.4.6 ABBA deadlock correction
 
 ### 📝 [Logging System](LOGGING.md)
 *Configuration reference for log levels, rotation, JSON output, and categories.*
 - **5 Severity Levels**: `debug`, `info`, `warn`, `error`, `critical`.
-- **Rotation**: Size-based (1GB default), auto-prune (5 files).
+- **Rotation**: Size-based (1.1GB total budget default), auto-prune (10 rotated files).
 - **JSON Output**: Structured lines for log aggregators (opt-in).
 - **Categories**: 6 independently enablable category groups.
 - **Change Detection**: Skips redundant logs (40-50% reduction).
 - **Batch Processing Logs**: Fill batching, recovery retry, and orphan-fill deduplication messages.
-- **Fill History Scans**: The `Subscriptions` logger emits `fetchFillHistoryEntries: maxPages (X) reached` at `info` level when the history scan hits its page cap — normal on busy accounts; see LOGGING.md for the `--partial-operations` diagnostic.
+- **Fill History Scans**: The `Subscriptions` logger emits `fetchFillHistoryEntries: maxPages (X) reached` at `debug` level when the history scan hits its page cap — normal on busy accounts; see LOGGING.md for the `--partial-operations` diagnostic.
 
 ### 🐳 [Docker](docker.md)
 *Container build, release images, and secure startup.*
@@ -88,8 +88,8 @@ This directory contains the comprehensive technical documentation for the DEXBot
 ### 🛠️ [Scripts](../scripts/README.md)
 *CLI maintenance and diagnostic utilities.*
 - **Update**: Safe production update via `dexbot update`
-- **Reset & Cleanup**: Log wiping, setting resets, PM2 ecosystem regeneration
-- **Analysis Helpers**: Diagnostic connection tests and health probes
+- **Reset & Cleanup**: Log/order wipes, settings resets, and market-adapter/claw state cleanup
+- **Diagnostics**: Configuration audit, grid divergence/trading analysis, and candle/pool history checks
 
 ## Reference Docs
 
@@ -97,9 +97,9 @@ This directory contains the comprehensive technical documentation for the DEXBot
 *The blueprint of the system.*
 - **Design Philosophy**: Simplicity, constant spread, minimal blockchain interaction, and closed-loop market dynamics.
 - **System Design**: High-level overview of how the bot components interact.
-- **Module Responsibilities**: Detailed breakdown of the **Manager**, **Accountant**, **Strategy**, **Grid**, **FillRuntime**, and **MaintenanceRuntime** modules.
+- **Module Responsibilities**: Detailed breakdown of the **Manager**, **Accountant**, **Strategy**, **SyncEngine**, **Grid**, **FillRuntime**, and **MaintenanceRuntime** modules.
 - **Copy-on-Write Pattern**: Safe concurrent rebalancing with isolated working grids (see [COPY_ON_WRITE_MASTER_PLAN.md](COPY_ON_WRITE_MASTER_PLAN.md))
-- **Fill Processing Pipeline**: Fixed-cap batch fill processing (1-4 fills per broadcast; documented Feb 7 29-fill scenario: ~24s)
+- **Fill Processing Pipeline**: Fixed-cap batch fill processing (`gapSlots+1` fills per broadcast; documented Feb 7 29-fill scenario: ~24s)
 - **Spread Correction**: Conservative, fund-aware maintenance of constant spread width
 - **Periodic Market Price Refresh**: Background 4-hour price updates
 - **Pipeline Safety & Diagnostics**: 5-minute timeout safeguard and health monitoring
@@ -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**: State machine, rebalance/fill data flows, fill handling strategy, and operational rules
+- **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
+- **Subsystem Scope**: 13 `INV-*` prefix groups mapping each invariant to its runtime subsystem
+- **Change Policy**: Required steps for an intentional invariant change — same-PR doc update, rationale, and regression tests
+
+### 📐 [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 (`1..gapSlots+1` unified, deeper queues chunked at `gapSlots+1`)
+- **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.
@@ -128,7 +160,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Order State Helper Functions**: Centralized predicate functions for state checking
 - **Signal Concepts**: Dynamic weights, regime detection, derivative signals, and market adapter integration
 - **Debt Policy**: Native MPA and credit offer configuration and runtime rules
-- **Common Tasks**: Practical "how-to" guides for adding features or fixing bugs.
+- **Practical How-Tos**: Adding features step by step, common pitfalls to avoid, and useful debugging commands.
 - **Glossary**: Definitions of project-specific terminology (e.g., "Virtual Orders", "Rotation", "Pipeline Safety", "WorkingGrid", "COW Commit", "Dynamic Weight", "Regime Detection").
 
 ### 🔄 [Workflow](WORKFLOW.md)
@@ -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, fund invariants, and the grid-price invariant 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/WORKFLOW.md

@@ -238,7 +238,7 @@ the canonical name is preferred in scripts and docs.
 
 | Command (canonical) | Aliases | Purpose |
 |---------|---------|---------|
-| `dexbot test <bot>` | — | Test-run a single bot (one-shot, live trading) |
+| `dexbot test <bot>` | — | Run a single bot in live mode (one-shot; not a dry run) |
 | `dexbot drystart <bot>` | — | Same as `test` but forces dry-run execution |
 | `dexbot reset <bot>` | — | Trigger a grid reset (applies live or on next start) |
 | `dexbot default` | `defaults` | Reset settings to defaults (deletes generated settings files) |
@@ -258,7 +258,6 @@ the canonical name is preferred in scripts and docs.
 | `dexbot reload` | `reloadall` | Reload the monolithic runtime without touching the credential daemon (unlock mode) |
 | `dexbot restart` | `restartall` | Restart the monolithic runtime (unlock mode, re-unlocks credential daemon) |
 | `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 the logs directory (`<profiles>/logs`) |
 
 ## NPM Scripts for Branch Synchronization