dexbot 1.6.1 → 1.6.3

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.3 (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.3",
   "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": {