dexbot 1.6.1 → 1.6.2

package/docs/DEXBOT_COMPARISON.md

@@ -1,7 +1,7 @@
 # DEXBot vs DEXBot2 — Detailed Comparison Report
 
 > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
-> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.1).
+> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.2).
 > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
 
 ---
@@ -36,7 +36,7 @@
 
 | Attribute | DEXBot (original) | DEXBot2 |
 |---|---|---|
-| **Release Track** | 1.0.0 | v1.6.1 |
+| **Release Track** | 1.0.0 | v1.6.2 |
 | **Language** | Python 3.6+ | TypeScript 5.x |
 | **Status** | Released 1.0.0, unmaintained | Active development |
 | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -674,14 +674,10 @@ Where:
 | `docs/COW_INVARIANTS.md` | Non-negotiable COW behavioral invariants |
 | `docs/CREDENTIAL_SECURITY.md` | Credential daemon, key policy, and security model |
 | `docs/MPA_CREDIT_USAGE.md` | Credit runtime and MPA usage guidance |
-| `docs/BROWSER_COMPAT_PLAN.md` | Browser-safe surface plan and Node/browser split |
-| `docs/PLAN_MIN_BTS_VALUE.md` | Minimum BTS value / dust handling planning |
 | `claw/docs/AI_BOT_LIBRARY_API.md` | Claw API boundary and responsibility split |
 | `claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md` | Grid tuning reference |
 | `claw/docs/POSITION_HEALTH.md` | Position health monitoring guide |
 | `claw/docs/RUNTIME_COMPARISON.md` | Claw runtime comparison |
-| ~~`docs/TYPESCRIPT_MIGRATION_ANALYSIS.md`~~ | ~~Removed — migration complete~~ |
-| `docs/crash_report_jan_mar_2026.md` | Production incident analysis |
 | `docs/docker.md` | Docker deployment guide |
 | `docs/README.md` | Docs index |
 | `AGENTS.md` | AI development context |
@@ -780,7 +776,7 @@ Where:
 
 | Metric | DEXBot | DEXBot2 |
 |---|---|---|
-| **Release Track** | 1.0.0 | v1.6.1 |
+| **Release Track** | 1.0.0 | v1.6.2 |
 | **Active Since** | ~2018 | December 2025 |
 | **Last Commit** | May 23, 2020 | 2026-09-02 |
 | **Total Commits** | 2281 | 2,125 (v1.4.25) |

package/docs/EVOLUTION.md

@@ -2,14 +2,14 @@
 
 ## Executive Summary
 
-DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.1 stable release.
+DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.2 stable release.
 
 ### Key Milestones
 - **Project Inception**: December 2, 2025
- - **Growth Phase**: 2,215 commits over ~9 active months
+ - **Growth Phase**: 2,223 commits over ~9 active months
 - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
-- **Stability**: Progression from manual testing to a suite of 280 automated test files
-- **Releases**: 105 release entries (v0.1.0 to v1.6.1)
+- **Stability**: Progression from manual testing to a suite of 284 automated test files
+- **Releases**: 106 release entries (v0.1.0 to v1.6.2)
 
 ---
 
@@ -115,11 +115,12 @@ Compact, era-level view; per-release commit detail lives in [CHANGELOG.md](../CH
 | v1.5.2 → v1.5.3 | 6 | Boundary ownership hardening (fund-driven sync removal, guard-skipped refill hold), COW broadcast/reconcile dedup, TradingView bot-grid range highlight, createOrder unknown-id materialize-or-error, curve-comparison docs |
 | v1.5.3 → v1.6.0 | 37 | Node-failure strike ledger and broadcast-deferred fill rebalancing, trust-chain free-balance heal with deferred-drain tolerance, bidirectional grid-regeneration trigger, TradingView order overlay and chart pref namespacing, credit short-offer id display, live-config pickup (issue #27), reserve ladder anchored at resolved bounds + live-grid rail edges with single-source ordering and exact-size activation, owed-crawl persistence across refused broadcasts/restarts + hold-aware reload-safe lifecycle, fill-anchored boundary recovery + poisoned persisted-boundary erase, startup rail gate + static-center crawl fold, all `*-deferred` holds non-blocking + hold metrics surfaced, opt-in MPA price-feed charts + range-aware shared candle cache, range-band span parity on grid-less charts, orange range zone widened to 1.40x, docs reserve-ladder sweep, reserve-deficit targeted-sync trigger with window-exclusion counting, matched-surplus startup excess planning, shelf-order guards across reserve classification/placement/startup cancels/size recalc (issue #27 follow-ups), unified Kibana candle cache on runCachedWindows with fetch retry budgets, genuine-coverage LP window reuse, feed volume/AMA timeframe alignment, TradingView monthly candles/stat badges/rigid pan/volume toggle/feed affordance, credit full offer id + empty-pair Curr. CR hiding, live-config onboarding note |
 | v1.6.0 → v1.6.1 | 3 | Never-run-stale hardening (level-triggered deferred-fill retry, stale-totals fill parking, out-of-spread watchdog, region-end fan-out, one-sided spread honesty), whitelist range-scaling opt-in defaults, live-save vs reset vs reload docs + power-law paper restructure |
+| v1.6.1 → v1.6.2 | 6 | Grid-price invariant + resync escalation, gap-slot batch sizing, shard candle cache + chart fixes, recovery stranding tolerance, fill-counter hygiene, dead-node prune + trace single-sourcing, obsolete-doc removal |
 
 ---
 
 **Report Originally Generated**: February 19, 2026
-**Last Updated**: September 13, 2026
-**Total Commits**: 2,215
-**Date Range**: December 2, 2025 – September 13, 2026
+**Last Updated**: September 14, 2026
+**Total Commits**: 2,223
+**Date Range**: December 2, 2025 – September 14, 2026
 **Repository**: DEXBot2 (BitShares DEX Trading Bot)

package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md

@@ -110,18 +110,13 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
 
 ### 1.5 Fill Batch Processing & Timeline
 
-#### Fixed-Cap Batch Fill Processing
+#### Gap-Slot Batch Fill Processing
 
 **Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1438) once per chunk to run the full rebalance pipeline.
 
-**Batch Sizing Algorithm**: A single cap-based batch size (`FILL_PROCESSING.MAX_FILL_BATCH_SIZE`): a queue depth of 4 or fewer is processed as one unified batch; deeper queues are chunked into repeated batches of 4 (the last chunk may be smaller).
+**Batch Sizing Algorithm**: Batch size is derived from the grid gap-slot count (`DEXBot._getGapSlotBatchSize`): a queue depth at or below gapSlots is processed as one unified batch; deeper queues are chunked into repeated batches of gapSlots (the last chunk may be smaller). The same gap-slot size caps order operations per broadcast transaction (oversized op batches are split into sequential broadcasts).
 
-**Configuration** (`modules/constants.ts`):
-```javascript
-FILL_PROCESSING: {
-  MAX_FILL_BATCH_SIZE: 4            // Hard cap on batch size
-}
-```
+**Configuration**: no fixed constant — both `FILL_PROCESSING.MAX_FILL_BATCH_SIZE` and `COW_PERFORMANCE.MAX_OPS_PER_BROADCAST` were removed; batch sizing follows the grid gap-slot count.
 
 #### Fill Batch Processing Timeline
 
@@ -806,4 +801,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
 **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
 
 ---
-*Technical Reference for DEXBot2 v1.6.1 release*
+*Technical Reference for DEXBot2 v1.6.2 release*

package/docs/LIFECYCLE.md

@@ -105,7 +105,7 @@ sequenceDiagram
 ```
 
 Why it matters:
-- **Fixed-cap batching** (`MAX_FILL_BATCH_SIZE`, default 4) keeps bursts
+- **Gap-slot batching** (batch size = grid gap-slot count, `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).
@@ -179,7 +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" |
-| **Browser/Node split** | Heavy runtime is Node-only; never import it from a browser bundle. | `AGENTS.md` "Browser-Safe Surface", `docs/BROWSER_COMPAT_PLAN.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" |
 
 ---

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.1 (released).
+**Version context:** v1.6.2 (released).
 
 ---
 
@@ -162,6 +162,14 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **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

package/docs/architecture.md

@@ -377,13 +377,13 @@ The fill pipeline handles incoming filled orders efficiently through fixed-cap b
                       ↓
 ┌─────────────────────────────────────────────────────────────┐
 │             processFilledOrders() - Entry Point             │
-│    Use MAX_FILL_BATCH_SIZE cap for deterministic batching   │
-│        Rules: <=cap unified, >cap chunked at cap size       │
+│    Use gap-slot batch size for deterministic batching   │
+│      Rules: <=gapSlots unified, >gapSlots chunked      │
 └─────────────────────┬───────────────────────────────────────┘
                       ↓
 ┌─────────────────────────────────────────────────────────────┐
-│            Pop Batch (up to MAX_FILL_BATCH_SIZE)            │
-│           Takes N fills from queue head (N = 1-4)           │
+│            Pop Batch (up to gapSlots)                     │
+│        Takes N fills from queue head (N = 1..gapSlots)     │
 │   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
 
-- **Fixed-Cap Batch Sizing**: Batch size is deterministic with `MAX_FILL_BATCH_SIZE` (default 4)
-  - 1..4 awaiting: single unified batch (one rebalance/broadcast cycle)
-  - 5+ awaiting: repeated chunks of 4 (last chunk may be smaller)
+- **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)
 
 - **Single Rebalance Cycle**: All fills in batch processed in ONE rebalance
   - No "split across cycles" delays

package/docs/developer_guide.md

@@ -39,7 +39,7 @@ Follow this path through the codebase:
 ```
 
 **Additional Resources**:
-- `modules/constants.ts::FILL_PROCESSING` - Batch configuration (`MAX_FILL_BATCH_SIZE`)
+- `modules/constants.ts::FILL_PROCESSING` - Fill-event handling configuration (batch sizing is gap-slot derived, see `DEXBot._getGapSlotBatchSize`)
 - `modules/constants.ts::PIPELINE_TIMING` - Recovery configuration (RECOVERY_RETRY_INTERVAL_MS, MAX_RECOVERY_ATTEMPTS)
 - `modules/constants.ts::MARKET_ADAPTER` - AMA, dynamic weight, and regime detection defaults
 - `modules/constants.ts::REGIME_TABLE` - Hurst/PE regime signal-strength table
@@ -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#15-fill-batch-processing--timeline). |
+| **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). |
 | **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. Fixed-cap sizing: `<= MAX_FILL_BATCH_SIZE` unified, otherwise chunked at cap size (default max 4). |
-| **Fixed-Cap Batch Sizing** | Deterministic chunking model with hard upper bound per broadcast. 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` 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. |
 | **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/market_adapter/README.md

@@ -854,7 +854,7 @@ closed 1h candles.
 
 #### Shared Chunk Cache and Fetch Robustness
 
-Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): sibling chunk files load once, only missing buckets plus a bounded 48h tail refresh are queried, and chunk metas record the ranges actually queried (`meta.queriedRanges`). A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty. Partial windows merge into the run output but are never persisted, and orphan chunks are deleted after complete runs only. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
+Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded 48h tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned). A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty. Partial windows merge into the run output but are never persisted. Legacy run-relative `*.chunk_*` files are still read: overlapping ones are absorbed into the shards (buckets + coverage) and retired once every bucket provably lives in a shard, while disjoint ones are never loaded and never deleted — narrow runs cannot wipe older history by construction. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
 
 #### AMA Warmup Window — Why Candle Length Matters
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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": {