dexbot 1.6.5 → 1.6.6

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.6.6] - 2026-09-25 - Stale Cancellation Guard Hardening
+
+### 2026-09-25
+
+- **Fix(update)**: make the dist freshness check honor the build's `tsconfig.json` exclude — the updater derived expected `dist/` outputs by walking every `.ts` under the compiled roots, so the archived `analysis/legacy/tests` (compiled only by `tsconfig.tests.json`) was read as a missing production output and the post-build check aborted with `Build left dist/ incomplete or stale (is missing dist/analysis/legacy/tests/test_derivative_chart.js)` after a successful build, blocking the restart. `collectCompiledSources` now reads the root `tsconfig.json` `exclude` directory prefixes and skips them, mirroring the compiler; regression in `tests/test_update_dist_freshness.ts` (`scripts/update_dist_freshness.ts`, `tests/test_update_dist_freshness.ts`).
+
+- **Refactor(analysis)**: archive the legacy SMA/MACD/RSI derivative analyzer — the classic-indicator tool (superseded by the live Kalman/Hurst/PE stack, with no production importer since `modules/` and `market_adapter/core/` hold none of its symbols) moves to `analysis/legacy/` with a local README. It loses its `analysis:derivatives` npm script, is scrubbed from the centralized docs (`analysis/README.md`, `analysis/trend_detection/README.md`, `scripts/README.md`, `docs/README.md`, `docs/architecture.md`, `docs/developer_guide.md`, `docs/DEXBOT_COMPARISON.md`), and is excluded from the published npm package (`!analysis/legacy` + `!dist/analysis/legacy`). Its four regression tests move under `analysis/legacy/tests/` out of the default `npm test` glob, with a new opt-in `npm run test:legacy`; the production build excludes that path while `tsconfig.tests.json` still typechecks it. Full suite 296/296 pass (`analysis/legacy/`, `package.json`, `tsconfig.json`, `tsconfig.tests.json`, docs).
+
+- **Refactor(cache)**: drop legacy run-relative candle-cache migration — stable calendar-month shards are now the only supported format: `*.chunk_*` files are ignored (never loaded, never deleted) instead of being absorbed into shards, and the `*.fetch_manifest.json` identity fallback is removed. The LP fetcher's progress output reads `Window N/M` (was `Chunk N/M`) and its match predicate is renamed `isLpShardMatch`. Refresh/retry/tail semantics are unchanged. Behavioral impact: installs holding only legacy chunks re-fetch once on next run, and the stale files remain inert on disk. Full suite 292/292 pass (`market_adapter/inputs/window_cache.ts`, `market_adapter/inputs/fetch_lp_data.ts`, `tests/test_window_cache.ts`, `market_adapter/README.md`).
+
+### 2026-09-24
+
+- **Fix(order-engine)**: close stale-cancellation replays across the correction queue, COW orphan maintenance, and startup reconciliation. Drain-time validation now rechecks live ownership and source-specific geometry for cancel-only, type-mismatch, and gap-evacuation decisions; COW auto-cancel skips adopted orders; startup Phase 2 validates each plan against its own unchanged chain order and live slot/geometry instead of requiring whole-book snapshot equality. Surplus settlement uses only the current live owner and skips stale snapshot fallback. Centralized live-owner lookup across the guards and added regression coverage for truncated/failed pre-cancel reads, per-plan snapshot independence, and stale settlement (`modules/order/utils/order.ts`, `modules/order/grid_reconcile.ts`, `modules/order/grid_reconcile_internal.ts`, `modules/dexbot_cow_runtime.ts`, `tests/test_correction_queue_staleness.ts`, `tests/test_grid_reconcile_regressions.ts`, `tests/test_uncertain_broadcast.ts`).
+
+### 2026-09-23
+
+- **Refactor(bot-editor)**: unify the configurator menu labels — abbreviated aliases give way to full names so the same term reads identically in the editor and the docs: `HealthChk` → `Health Check`, `PrefNode` → `Preferred Node`, `Incr` → `Increment`, and `Log lvl` → `Log Level`. The run-together `GridPrice`, `MarketOrder`, and `EdgeOrder` labels keep their casing. Display-only — stored keys, defaults, and validation are unchanged; the `README.md` configurator reference aliases and the `4) Log Level` heading are updated to match (`modules/account_bots.ts`, `README.md`).
+
+- **Feat(bot-editor)**: render `5) List bots` as a `Name / Account / Pair` table — the flat `N: name A / B` line gains a bold header and columns derived from the longest value in each field, with palette colors (grey index, green name, orange account, cyan pair) replacing the unlabeled white text, and the pair now reads `A/B` with no spaces around the slash. The `[inactive]`/`(dryRun)` suffixes are colored red/yellow so they stand out. Readability only (`modules/account_bots.ts`).
+
+- **Refactor(settings)**: regroup the General Settings menu by concern — `1) Grid Health` → `1) Grid Drift`, `2) Order Recovery` → `2) Order Maint.` (which now also edits the Health Check Interval, moved out of Node Config, so the `Health Check` value reads next to the dust threshold it schedules), and `3) Node Config` narrows to `Nodes` + `Preferred Node`; all five rows are padded to a shared value column. Display/prompt grouping only — stored keys, defaults, and validation are unchanged. Docs: the `README.md` global-settings reference is regrouped to mirror the editor, and `docs/GRID_RECALCULATION.md`'s menu reference now reads `1) Grid Drift` (`modules/account_bots.ts`, `README.md`, `docs/GRID_RECALCULATION.md`).
+
+- **Refactor(bot-editor)**: align the per-bot editor with the `bots.json`/runtime vocabulary — the `5) Funding` section is now `5) Inventory` with `Orders` → `MarketOrder` (active window, counted from the market) and `Reserve` → `EdgeOrder` (edge-pinned insurance orders); the `Preferred account` prompts read `Blockchain account`; and `startPrice (pool, book or A/B)` reads `startPrice (pool, book or price)`. `poolRef` is now prompted only when `startPrice` is `pool`: a dormant pin is preserved rather than cleared when switching to `book`/numeric, and the `3) Price` summary renders a dormant pin as grey `ignored` instead of a value that no longer applies. Reserve order counts accept `0`–`100` per side (was `0`–`20`), matching the active-order cap, and the `1)`–`6)` summary rows are column-aligned. Display/validation only — stored keys and defaults are unchanged. New `formatPoolRefLabel` dormant-pin case in `tests/test_account_bots_adapter.ts` (`modules/account_bots.ts`).
+
+- **Refactor(cli)**: rebuild `dexbot help` as grouped sections — `printCLIUsage` replaces the hand-padded flat list (which had drifted: duplicate `order` rows, missing `dw`/`export`/`clear-orders`/`clear-market-adapter`/`clear-all`) with five groups (Runtime, Trading, Config, Analysis, Files) plus a Help & options block, deriving the command-column width from the longest entry so alignment cannot drift again. Same commands and aliases; output-only (`dexbot.ts`).
+
+- **Docs**: regroup the README configurator reference to mirror the editor — the per-bot parameter tables are split into `1) Pair` … `6) Adapter` and the global-settings tables into `1) Grid Drift` … `5) Updater`, with the previously-undocumented edge-`reserveOrders` semantics and adapter-flag storage (`market_adapter_whitelist.json`, not `bots.json`) called out; the CLI examples gain `export` and the `clear-*` variants. `docs/WORKFLOW.md`'s command table is synced (aliases `keys`/`bots`/`stats`, `dw`, the three `clear-*` commands, `help`), `docs/DEXBOT_COMPARISON.md` now credits the interactive `dexbot bot` editor instead of "manual JSON only", and `market_adapter/README.md` + `scripts/reset-settings.sh` spell the full path `dexbot bot` → `2) Modify bot` → `6) Adapter` (`README.md`, `docs/WORKFLOW.md`, `docs/DEXBOT_COMPARISON.md`, `market_adapter/README.md`, `scripts/reset-settings.sh`).
+
+- **Fix(bot-editor)**: accept the pool label's own vocabulary in the `poolRef` prompt — the `3) Price` summary reads green `Pool: default` when the runtime auto-selects the pair's pool, but the pin prompt showed `[none]` and rejected `default`/`pool`/`auto` as invalid, so a user typing what the summary displayed hit an error. `askPoolRef` now treats `default`/`pool`/`auto` as clear aliases (same as `none`/`clear`/`off`/`no`), and when `startPrice` is `pool` the unpinned prompt renders `[default]` instead of `[none]`, matching the summary, and the now-redundant `(none to clear)` hint is dropped from the prompt. New `isPoolStartPrice`/`isPoolRefClearInput` helpers. Display/parsing only — a pin is still either a concrete `1.19.x` ID or absent, and `withPoolRef` is unchanged. Tests: `tests/test_account_bots_adapter.ts` (`modules/account_bots.ts`).
+
+- **Fix(grid)**: make `startPrice` the master price source over a pinned `poolRef` — `initializeGrid` passed `manager.config.priceMode || 'auto'`, and `priceMode` is never populated in the bot runtime path, so `startPrice: "book"` was derived as `"auto"` and a pinned `poolRef` won over the order book. New `resolveStartPriceMode()` (`modules/order/utils/withPoolRef.ts`) derives the mode from `startPrice` itself, so `"book"` ignores the pin while `"pool"`/`"auto"` still consult it. Behavioral impact: a bot with `startPrice: "book"` + a pinned pool prices from the order book as documented (previously the pool); numeric startPrice is unchanged. Tests: `tests/test_pool_ref_price.ts` (book mode never fetches the pinned pool; mode resolution) (`modules/order/grid.ts`, `modules/order/utils/withPoolRef.ts`).
+
 ## [1.6.5] - 2026-09-23 - Editor-Managed Whitelist Flags, GridPrice Normalization, Pool/Health Cues, Log-Symmetric Range Tilt, Centralized Bot Defaults, Dynamic-Weight CLI, Update Self-Heal
 
 ### 2026-09-23
@@ -20,7 +52,7 @@ All notable changes to this project will be documented in this file.
 
 - **Fix(update)**: rebuild when source is current but `dist/` is stale — the git update flow exited before `npm run build` when there were no incoming commits, and tsc's incremental cache will not re-emit an output it believes is current (it will not even recreate a deleted file), so a `dist/` that lagged its source stayed stale while every later run reported "already up to date"; the old guard only checked the `dist/modules/dexbot_class.js` mtime, so a stale `dist/dexbot.js` (holding the CLI alias table) went unnoticed. New `scripts/update_dist_freshness.ts` detects missing/stale outputs without invoking the compiler over exactly the root tsconfig include roots; `scripts/update.ts` self-heals on the no-op path (force a full rebuild, then restart), re-checks and force-emits on the normal path, and `assertDistBundleFresh()` replaces the single-marker guard with a full-bundle check. New `tests/test_update_dist_freshness.ts` covers missing entries, missing/stale counterparts, root-level entry points, and non-compiled files.
 
-- **Feat(defaults)**: centralize bot defaults, settings-doc building, and whitelist flags — seven scattered producers applied `DEFAULT_CONFIG` and whitelist defaults independently and had already drifted. New `modules/bot_defaults.ts` (`seedBotDraft`/`seedBotEntry`/`seedBotRuntimeConfig` with classified key sets, `normalizeBotDraft`/`normalizeBotEntry`) now backs the editor draft, `bot_settings` + claw, and the `OrderManager` constructor. `buildDefaultGeneralSettings()` (`modules/constants.ts`) and `buildNodesView()` (`modules/settings_merge.ts`) give the first-run generator, the editor fallback (`account_bots.loadGeneralSettings`), and the local-overrides merge one shared document (`loadGeneralSettings`/`saveGeneralSettings` now exported). `DEFAULT_WHITELIST_FLAGS`/`AMA_ONLY`/`ALL_ENABLED` constants replace every inline flag literal. Behavioral impact: a draft's `gridPrice` follows a `DEFAULT_CONFIG.gridPrice` override (default stays null here); a missing `bot.active` sources `DEFAULT_CONFIG.active` (was hardcoded true) and claw no longer coerces present null/0, unifying on `active !== false`; `OrderManager` clones absent defaults so config mutations cannot leak into the global default; brand-new first-run settings files gain `NODE_MANAGEMENT`, drop `ANCHOR:{}`, and match the editor key order. Existing `bots.json`/`general.settings.json` are not rewritten (merge output verified byte-identical to a pre-refactor baseline). Tests: 295/295 files passed; new `tests/test_bot_defaults_characterization.ts`, `tests/test_bot_defaults_parity.ts`, and a claw delegation test.
+- **Feat(defaults)**: centralize bot defaults, settings-doc building, and whitelist flags — seven scattered producers applied `DEFAULT_CONFIG` and whitelist defaults independently and had already drifted. New `modules/bot_defaults.ts` (`seedBotDraft`/`seedBotEntry`/`seedBotRuntimeConfig` with classified key sets, `normalizeBotDraft`/`normalizeBotEntry`) now backs the editor draft, `bot_settings` + claw, and the `OrderManager` constructor. `buildDefaultGeneralSettings()` (`modules/constants.ts`) and `buildNodesView()` (`modules/settings_merge.ts`) give the first-run generator, the editor fallback (`account_bots.loadGeneralSettings`), and the local-overrides merge one shared document (`loadGeneralSettings`/`saveGeneralSettings` now exported). `DEFAULT_WHITELIST_FLAGS`/`AMA_ONLY`/`ALL_ENABLED` constants replace every inline flag literal. Behavioral impact: a draft's `gridPrice` follows a `DEFAULT_CONFIG.gridPrice` override (the default was still null at this stage of the refactor; a subsequent change in the same release set it to `ama3`); a missing `bot.active` sources `DEFAULT_CONFIG.active` (was hardcoded true) and claw no longer coerces present null/0, unifying on `active !== false`; `OrderManager` clones absent defaults so config mutations cannot leak into the global default; brand-new first-run settings files gain `NODE_MANAGEMENT`, drop `ANCHOR:{}`, and match the editor key order. Existing `bots.json`/`general.settings.json` are not rewritten (merge output verified byte-identical to a pre-refactor baseline). Tests: 295/295 files passed; new `tests/test_bot_defaults_characterization.ts`, `tests/test_bot_defaults_parity.ts`, and a claw delegation test.
 
 - **Feat(bot-editor)**: manage market-adapter whitelist flags from the editor — the per-bot Price/Weight/Range flags (`ama`/`dynamicWeight`/`asymmetricBounds`) previously required running the `dexbot white` script with the correct `botKey`; a wrong key silently wrote a useless entry and the script remained the only way to flip a single flag. New `6) Adapter` section in `modules/account_bots.ts` stages the three flags and commits them only after `bots.json` saved (migrating the entry on rename); `parseBooleanInput` fixes `askBoolean` parsing `'true'` as false and accepting any garbage (`y`/`yes`/`true`, `n`/`no`/`false`, Enter keeps current). `modules/market_adapter_whitelist.ts` gains `setWhitelistFlags()`/`renameWhitelistEntry()` read-modify-write helpers — an occupied key refuses the rename, a malformed file aborts instead of clobbering, legacy array-form entries are preserved, and keys are written sorted. Docs now point to `dexbot bot` -> `6) Adapter`. New `tests/test_account_bots_adapter.ts` (boolean parsing, flag writes, rename/collision, legacy and malformed-file coverage); `npm test` 293 passed / 0 failed, `verify:browser-bundle` 39/39, `tsc --noEmit` clean. Risk: writes touch the same file `dexbot white` owned; unchanged flags are never rewritten.
 
@@ -763,10 +795,10 @@ All notable changes to this project will be documented in this file.
 - **Fix**: prevent bot hangs via centralized timeout + node failover — after exhausting 3-attempt retry budget, `withBlockchainRetry` force-blacklists the stuck node and reconnects to a healthy one. All blockchain ops (fetchAccountTotals, readOpenOrders, syncFromOpenOrders, reconcileGridOrders) get automatic failover. Default `_fillProcessingLock` acquisition timeout (20s) prevents indefinite waits. `recalculateGrid` wrapped in 10-minute `Promise.race` ceiling (`modules/order/utils/system.ts`, `modules/order/manager.ts`, `modules/order/grid.ts`).
 - **Refactor**: centralize `withBlockchainRetry` into shared utility in `system.ts` — replaces local copy in `grid.ts` and inline `Promise.race` in `dexbot_startup_runtime.ts`, giving the startup path retries + node failover too (`modules/order/utils/system.ts`, `modules/order/grid.ts`, `modules/dexbot_startup_runtime.ts`).
 - **Fix**: prevent duplicate grid-level CREATEs via 4-layer validator guard — `validateCreateTargetSlots` extended with slot occupancy, master grid price collision, chain orphan collision, and same-batch duplicate detection. Also hardens `checkSpreadCondition` against TOCTOU between lock release and broadcast (`modules/order/utils/validate.ts`, `modules/order/grid.ts`, `modules/dexbot_cow_runtime.ts`).
-- **Fix**: prevent false-positive excess cancellation on fresh grid — guard `_reconcileStartupSide` cancelCount with `matchedOnGrid > 0` to avoid destroying legitimate orders when no grid slot yet assigned ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#fresh-grid-guard)). Fix reconcile timeout death spiral by overriding timeout to 300s so Phase 2 batch creates finish in one shot (`modules/order/grid.ts`, `modules/order/grid_reconcile_internal.ts`).
+- **Fix**: prevent false-positive excess cancellation on fresh grid — guard `_reconcileStartupSide` cancelCount with `matchedOnGrid > 0` to avoid destroying legitimate orders when no grid slot yet assigned ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#fresh-grid-guard-matchedongrid--0)). Fix reconcile timeout death spiral by overriding timeout to 300s so Phase 2 batch creates finish in one shot (`modules/order/grid.ts`, `modules/order/grid_reconcile_internal.ts`).
 - **Fix**: prevent cross-side spread correction via boundary-correct type filter — hoist boundary computation before both candidate pools and filter `typedSpreadCandidates` by `getSlotCorrectType(o) === railType` to prevent activating a SPREAD slot on the wrong rail after fill-induced boundary shifts (`modules/order/grid.ts`).
 - **Fix**: remove dead PARTIAL filter in `recalculateGrid` (raw chain `limit_order` objects never have a `state` property) and fix `withBlockchainRetry` logger arg — pass `manager.logger` directly instead of `{ logger: manager.logger }` (`modules/order/grid.ts`).
-- **Fix**: cancel stale surplus orders after Phase 2 settles in reconcileGridOrders — new Phase 3 pass re-fetches chain orders and cancels any exceeding per-side target that are not tracked by any grid slot's `orderId` ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#phase-3--stale-surplus-cleanup)). Catches orphan orders whose ID was lost when the grid reinitialized mid-resync.
+- **Fix**: cancel stale surplus orders after Phase 2 settles in reconcileGridOrders — new Phase 3 pass re-fetches chain orders and cancels any exceeding per-side target that are not tracked by any grid slot's `orderId` ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#phase-3--fresh-re-read-adoption-stale-surplus-cleanup)). Catches orphan orders whose ID was lost when the grid reinitialized mid-resync.
 - **Test**: new `testNoExcessCancelWhenMatchedOnGridIsZero` regression test — fresh grid with `matchedOnGrid=0`, non-zero chainCount+targetCount asserts zero cancel calls (`tests/test_grid_reconcile_regressions.ts`).
 - **Test**: `testPhase3CancelsStaleSurplusUntrackedByGrid` — 7 chain sells, target 5, all-VIRTUAL grid with matchedOnGrid=0, verifies Phase 3 cancels exactly 2 untracked surplus and does NOT cancel any tracked order (`tests/test_grid_reconcile_regressions.ts`).
 - **Test**: 9 scenarios in `test_validate_create_target_slots.ts` covering all four guard layers, released slots, malformed chain candidates, and no-assets fallback (`tests/test_validate_create_target_slots.ts`).
@@ -1314,7 +1346,7 @@ All notable changes to this project will be documented in this file.
 
 ### 2026-07-01
 
-- **Fix**: prevent stale dust duplicates at the same price level — sync engine rejects orphan adoption when an active order already occupies that price. Reconcile unconditionally cancels duplicate chain orders on chain via `_cancelChainOrder` with `releaseUntrackedFunds: true` ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#duplicate-tolerance-5%C3%97-multiplier)). Dust detection expanded to interior partials sharing a price level with an active sibling.
+- **Fix**: prevent stale dust duplicates at the same price level — sync engine rejects orphan adoption when an active order already occupies that price. Reconcile unconditionally cancels duplicate chain orders on chain via `_cancelChainOrder` with `releaseUntrackedFunds: true` ([GRID_RECONCILE.md](docs/GRID_RECONCILE.md#duplicate-cancellation)). Dust detection expanded to interior partials sharing a price level with an active sibling.
 - **Chore**: version bumped to 1.0.5 across all manifests.
 - **Docs**: updated `CHANGELOG.md`, `docs/EVOLUTION.md`, `docs/README.md`, `docs/DEXBOT_COMPARISON.md`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md`.
 

package/README.md

@@ -169,26 +169,28 @@ Keep the default settings first, and tune these:
    (super-mountain); the default `{ "sell": 1.0, "buy": 1.0 }` suits most
    setups.
 
-4. **Set `gridPrice` to `"ama"`** — so the market adapter can center the grid
-   on AMA. Pick a specific preset if desired: `"ama1"` is the fastest,
-   `"ama4"` the slowest, and `"ama"` uses the pair's default preset.
+4. **Enable AMA** — new bots anchor on `gridPrice: "ama3"`, but the market
+   adapter only goes live once its per-bot `Price` flag is on. Open
+   `dexbot bot` → `2) Modify bot` → pick the bot → `6) Adapter` and set the
+   flags:
 
-5. **Set the adapter flags** — `dexbot bot` → `2) Modify bot` → pick the bot
-   → `6) Adapter`:
-
-   - `Price` — AMA pricing and live adapter writes (turn **on** for AMA bots;
-     without it the adapter only dry-runs)
+   - `Price` — **on for AMA bots**; without it the adapter only dry-runs
    - `Weight` — dynamic buy/sell weights (opt-in)
    - `Range` — AMA-slope range scaling (opt-in)
 
+   To change how closely the grid center tracks the market, set `gridPrice`
+   in `3) Price` to `"ama1"`–`"ama4"`: `"ama1"` reacts fastest, `"ama4"`
+   slowest and steadiest (higher numbers smooth more), or `"ama"` for the
+   pair's default preset.
+
    The flags are stored per bot in `market_adapter_whitelist.json` in the
    profiles directory and can be changed any time from the same editor
    section. Boolean prompts accept `y`/`yes`/`true` and `n`/`no`/`false`;
    Enter keeps the current value.
 
-6. **Start DEXBot2** with `dexbot start`.
+5. **Start DEXBot2** with `dexbot start`.
 
-7. **Tune `minPrice` / `maxPrice`** around the market's volatility range. Once
+6. **Tune `minPrice` / `maxPrice`** around the market's volatility range. Once
    AMA is active, tighten them around the maximum expected market volatility
    instead of using an unnecessarily wide range.
 
@@ -200,39 +202,106 @@ Configuration options from `dexbot bot`, stored in `bots.json` in the profiles d
 
 <details><summary><mark>Full parameter reference (click to expand)</mark></summary>
 
+Grouped exactly as the bot editor shows them (`dexbot bot` → `2) Modify bot` → pick the bot):
+
+**`1) Pair`**
+
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
 | **`assetA`** | string | Base asset |
 | **`assetB`** | string | Quote asset |
+
+**`2) Identity`**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
 | **`name`** | string | Friendly name for logging and CLI selection |
-| **`active`** | boolean | `false` to keep config without running |
-| **`dryRun`** | boolean | Simulate orders without broadcasting |
 | **`preferredAccount`** | string | BitShares account name for trading |
-| **`startPrice`** | num \| str | Initial price and adapter source. Default `"pool"` uses the liquidity-pool price; `"book"` uses the live order book mid price (best bid/ask); a number uses a fixed anchor. |
-| **`poolRef`** | string \| null | Optional pinned pool ID for `startPrice: "pool"`. Overrides pool discovery with a direct fetch (e.g. `"1.19.48"` or `"48"`). Useful when the trading pair has no native pool. Default `null`. |
-| **`minPrice`** | num \| str | Lower bound. Default `"2x"` means `gridPrice / 2` when AMA is active, otherwise `startPrice / 2`. |
-| **`maxPrice`** | num \| str | Upper bound. Default `"2x"` means `gridPrice * 2` when AMA is active, otherwise `startPrice * 2`. |
-| **`gridPrice`** | num \| str \| null | Grid reference. Use `"ama"` for the recommended AMA center (`"ama"` picks the pair's default preset; `"ama1"`–`"ama4"` pin fastest to slowest); `null` falls back to `startPrice`; numeric values use that fixed value. |
-| **`incrementPercent`** | number | Geometric step between orders. Default `0.5` = 0.5%. |
-| **`targetSpreadPercent`** | number | Width of the empty spread zone between buy and sell orders. Default `2` = 2%. Profit per completed cycle ≈ `spread - increment - fees`. |
-| **`weightDistribution`** | object | Advanced sizing control per side. Range `-1` to `2`: `-1` = super-valley, `0` = valley, `0.5` = neutral, `1` = mountain (default), `2` = super-mountain. Higher weight = more funds in orders near the market price; lower weight = more funds shifted toward the grid edge. Default `{ Sell: 1.0, Buy: 1.0 }`; leave unchanged for normal setup. |
-| **`botFunds`** | object | Capital: `{ Sell: "100%", Buy: 100% }`. Numbers or percentage strings |
-| **`activeOrders`** | object | Target active orders per side: `{ S: 20, B: 20 }` |
-| **`reserveOrders`** | object | Edge-pinned insurance orders resting live outside the active window, to catch fat fingers: `{ S: 0, B: 0 }` |
+| **`active`** | boolean | Default `true`. `false` keeps the config without running it |
+| **`dryRun`** | boolean | Default `false`. Simulate orders without broadcasting |
+
+**`3) Price`**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| **`minPrice`** | num \| str | `Range` lower bound. Default `"2x"` means `gridPrice / 2` when AMA is active, otherwise `startPrice / 2` |
+| **`maxPrice`** | num \| str | `Range` upper bound. Default `"2x"` means `gridPrice * 2` when AMA is active, otherwise `startPrice * 2` |
+| **`startPrice`** | num \| str | `Start` — initial price and adapter source. Default `"pool"` uses the liquidity-pool price; `"book"` uses the live order book mid price (best bid/ask); a number uses a fixed anchor |
+| **`poolRef`** | string \| null | `Pool` — optional pinned pool ID for `startPrice: "pool"`. Overrides pool discovery with a direct fetch (e.g. `"1.19.48"` or `"48"`). Useful when the trading pair has no native pool. Ignored when `startPrice` is `"book"` or a number — `startPrice` is the master source. Default `null`; in the editor, `none`/`clear` (or the aliases `default`/`pool`/`auto`) clears the pin |
+| **`gridPrice`** | num \| str \| null | `GridPrice` — grid reference for the x-factor bounds. Use `"ama"` for the recommended AMA center (`"ama"` picks the pair's default preset; `"ama1"`–`"ama4"` pin fastest to slowest; default `"ama3"`); `null` falls back to `startPrice`; numeric values use that fixed value |
+
+**`4) Grid`**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| **`weightDistribution`** | object | `Weights` — advanced sizing control per side. Range `-1` to `2`: `-1` = super-valley, `0` = valley, `0.5` = neutral, `1` = mountain (default), `2` = super-mountain. Higher weight = more funds in orders near the market price; lower weight = more funds shifted toward the grid edge. Default `{ sell: 1, buy: 1 }`; leave unchanged for normal setup |
+| **`incrementPercent`** | number | `Increment` — geometric step between orders. Default `0.5` = 0.5% |
+| **`targetSpreadPercent`** | number | `Spread` — width of the empty spread zone between buy and sell orders. Default `2` = 2%.<br>Profit per completed cycle ≈ `spread - increment - fees`. Must be at least 2.1 × `incrementPercent` |
+
+**`5) Inventory`**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| **`botFunds`** | object | `Sell`/`Buy` — capital allocation: `{ sell: "100%", buy: "100%" }`. Numbers or percentage strings |
+| **`activeOrders`** | object | `MarketOrder` — target active orders per side, counted closest to the market: `{ sell: 20, buy: 20 }` |
+| **`reserveOrders`** | object | `EdgeOrder` — edge-pinned insurance orders resting live outside the active window, to catch fat fingers: `{ buy: 0, sell: 0 }` (`buy` pins the grid floor, `sell` the grid ceiling; `0` disables per side) |
+
+**`6) Adapter`**
+
+These three booleans are stored per bot in `market_adapter_whitelist.json`, **not** in `bots.json`:
+
+| Flag | Description |
+| :--- | :--- |
+| `ama` (Price) | AMA pricing and live adapter writes. Turn on for AMA bots; without it the adapter only dry-runs |
+| `dynamicWeight` (Weight) | Dynamic buy/sell weights (opt-in; only takes effect while Price is on) |
+| `asymmetricBounds` (Range) | AMA-slope range scaling (opt-in; only takes effect while Price is on) |
 
 </details>
 
-### General Options (Global)
+### General Settings (Global)
+
+General settings via `dexbot bot`, stored in `general.settings.json` in the profiles directory:
 
-Global settings via `dexbot bot`, stored in `general.settings.json` in the profiles directory:
+<details><summary><mark>General settings reference (click to expand)</mark></summary>
 
-<details><summary><mark>Global settings reference (click to expand)</mark></summary>
+Grouped exactly as `dexbot bot` → `6) General settings` shows them:
 
-- **Grid Health**: Grid Funds Regeneration % (default `3%`), RMS Divergence Threshold % (default `14.3%`), AMA Δ Threshold % (default `1%`, AMA center move that triggers a grid reset), AMA-Slope Δ Threshold % (default `8%`, slope-delta trigger as a percentage of max AMA slope)
-- **Order Recovery**: Partial Dust Threshold % (default `5%`), Dust Cancel Delay (default `30s`, `-1` = off, `0` = instant)
-- **Node Configuration**: Node List (10 default public BitShares nodes), Health Check Interval (default `240 min`), Preferred Node (default `none`)
-- **Log Level**: `debug`, `info`, `warn`, `error`, `critical`. Fine-grained category control via `LOGGING_CONFIG` (see [Logging](docs/LOGGING.md))
-- **Updater**: Active (default `OFF`), Branch (`auto`/`main`/`dev`/`test`), Interval (default `1 day`), Time (default `00:00`)
+**`1) Grid Drift`**
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| Grid Funds Regeneration % | `3` | `Funds` — recalculates grid size when spare funds reach this % of a side's allocation (or the tracked grid overshoots allocation by this %) |
+| RMS Divergence Threshold % | `14.3` | `RMS` — triggers a grid reset when the calculated grid diverges from on-chain state; `0` disables (JSON only) |
+| AMA Δ Threshold % | `1` | `AMA Δ` — % move in the AMA center price that triggers a grid reset |
+| AMA-Slope Δ Threshold % | `8` | `AMA-Slope Δ` — slope-delta trigger as a percentage of max AMA slope |
+
+**`2) Order Maint.`**
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| Partial Dust Threshold % | `5` | `Dust Threshold` — orders below this % of their ideal size are treated as dust and rotated (cancelled and re-placed at proper size) to keep the grid symmetric |
+| Health Check Interval (min) | `240` | `Health Check` — how often nodes are health-checked (stored as milliseconds) |
+
+**`3) Node Config`**
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| Node List | 7 public BitShares nodes | `Nodes` — sub-editor: `A` add, `R` remove (at least one must remain), `D` done |
+| Preferred Node | `none` | Pin one node URL; empty = automatic latency-based selection with failover |
+
+**`4) Log Level`**
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| Log Level | `info` | `debug`, `info`, `warn`, `error`. `critical` is only accepted by editing `general.settings.json` directly. Fine-grained category control via `LOGGING_CONFIG` (see [Logging](docs/LOGGING.md)) |
+
+**`5) Updater`**
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| Active | `OFF` | Enables the automated updater (editor shows `[ON/OFF]`) |
+| Branch | `auto` | `main`, `dev`, `test`, or `auto` (detected current branch) |
+| Schedule | `1` at `00:00` | Cron schedule (`Interval` days, `Time` HH:mm, 24h) |
 
 </details>
 
@@ -258,20 +327,20 @@ First-run details and common mistakes are covered in the [BitShares Onboarding T
 
 ```bash
 dexbot key                 # Master password/keyring
-dexbot bot                 # Interactive bot configurator (adapter Price/Weight/Range flags: 6) Adapter)
+dexbot bot                 # Interactive bot configurator (adapter flags: 2) Modify bot → 6) Adapter)
 
 dexbot reset {all|<bot>}   # Regenerate grid
 dexbot disable {all|<bot>} # Disable bot in config
 dexbot enable {all|<bot>}  # Enable bot in config
 
 dexbot stat                # Runtime status (unlock or PM2)
-dexbot order [<bot>]       # Analyze order grids
-dexbot order --export      # Export as HTML to analysis/charts/
+dexbot order [<bot>]       # Analyze order grids (--export → HTML to analysis/charts/)
 dexbot tv <bot|pool|A/B>   # TradingView 1h chart with AMA overlay (default: 3 months)
 dexbot credit [<bot>]      # Live summed MPA + borrowed-credit positions per asset per bot
+dexbot export <bot>        # Export trades + settings (CSV/JSON) for analysis/
 
 dexbot update              # Update DEXBot2
-dexbot clear               # Clear log files
+dexbot clear               # Clear log files (also clear-orders, clear-market-adapter, clear-all)
 dexbot default             # Reset settings to defaults
 ```
 

package/analysis/README.md

@@ -21,7 +21,7 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
 | Tool | Ask this when… | One-line command |
 |------|----------------|------------------|
 | [`trade_profitability.ts`](#trade-profitability-analyzer-trade_profitabilityts) | "Is my bot making money?" — PnL, R-multiples, drawdown | `npm run analysis:trade-pnl -- <account-id>` |
-| [`grid_correction_check.ts`](#grid-correction-check-grid_correction_checkts) | "Is my grid placing orders monotonically?" — sell/buy price inversion detector | `npm run analysis:grid-check -- --bot-key <bot-key>` |
+| [`grid_correction_check.ts`](#last-fill-guard-check-grid_correction_checkts) | "Are fills respecting the pivot ± half-increment guard?" | `npm run analysis:grid-check -- --bot-key <bot-key>` |
 | [`analyze_risk_profile.ts`](#risk-profile-analyzer-analyze_risk_profilets) | "How wide should my Safe Range clamps be?" | `node dist/analysis/analyze_risk_profile.js --bot-key <bot-key>` |
 | [`analyze_trade_heatmap.ts`](#trade-heatmap-analyze_trade_heatmapts) | "Where did trade volume cluster vs the AMA?" | `node dist/analysis/analyze_trade_heatmap.js --bot-key <bot-key>` |
 | [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `dexbot tv <bot-key>` |
@@ -32,8 +32,6 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
 | [`ama_fitting/`](#ama-fitting) | "Which AMA preset fits this market?" | `node dist/analysis/ama_fitting/optimizer_high_resolution.js --data <lp-file>` |
 | [`bot_fitting/`](#bot-fitting) | "What spread / increment / ratio for my grid?" | `node dist/analysis/bot_fitting/backtest_ama_sweep.js --data <lp-file>` |
 
-> `analyze_derivatives.ts` (SMA / MACD / RSI derivative layer, uses `derivative_chart_generator.ts`) is a legacy tool surfaced via `npm run analysis:derivatives` — kept for reference.
-
 > `<account-id>` = a BitShares `1.2.x` account ID or name. `<bot-key>` = a key from `profiles/bots.json`. `<lp-file>` = a JSON file under `market_adapter/data/lp/<pair>/lp_pool_<id>_<interval>.json`.
 
 ## Key Terms
@@ -164,7 +162,6 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 | `--end <iso>` | — | End time |
 | `--hours <n>` | `168` (7d) | Lookback hours (alternative to start/end) |
 | `--asset <id>` | all | Filter to one base asset ID |
-| `--lookup` | off | Legacy (no-op): account names always resolve automatically |
 | `--refresh-account` | off | Force re-resolution and update the stored `accountId` |
 | `--csv <file>` | — | Export chronologically sorted trade list |
 | `--json <file>` | — | Export full analysis with per-pair PnL data |
@@ -223,11 +220,11 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 
 </details>
 
-### Grid Correction Check (`grid_correction_check.ts`)
+### LAST-FILL-GUARD Check (`grid_correction_check.ts`)
 
-Validates grid discipline from the same Kibana fill pipeline as `trade_profitability.ts`: two consecutive same-direction fills on a pair must be monotonic — sell prices rising, buy prices falling (equal is OK). An inversion means the bot placed an order below its own previous sell (or above its own previous buy), e.g. an orphaned order filling outside grid accounting. Used as the external regression gate for the orphan-fix plans in `docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md`.
+Validates LAST-FILL-GUARD discipline from the same Kibana fill pipeline as `trade_profitability.ts`. For a previous fill at price `x` and grid increment `i`, the next order must satisfy `BUY < x × (1 − i/2/100)` and `SELL > x × (1 + i/2/100)`, regardless of the previous fill's side. A violation is a buy or sell fill inside the prohibited half-increment band around its pivot.
 
-**Pipeline:** Kibana `fill_order` query (paginated `search_after`) → on-chain asset precision resolution → buy/sell classification → chronological sort → per-order/price-epoch aggregation (partial fills at one price collapsed to weighted-average; repriced order lifetimes kept separate) → consecutive same-direction pair comparison → violation report with daily histogram.
+**Pipeline:** Kibana `fill_order` query (paginated `search_after`) → on-chain asset precision resolution → buy/sell classification → chronological sort → per-order/price-epoch aggregation (partial fills at one price collapsed to weighted-average; repriced order lifetimes kept separate) → consecutive pivot-band comparison → violation report with daily histogram.
 
 ```bash
 # Per-order aggregated check (default), last 7 days
@@ -239,8 +236,8 @@ npm run analysis:grid-check -- --bot-key <bot-key> --hours 720 --json out.json -
 # Raw fill granularity instead of per-order aggregation
 npm run analysis:grid-check -- --bot-key <bot-key> --per-fill --hours 168
 
-# Forgive small adverse moves within 0.1%
-npm run analysis:grid-check -- --bot-key <bot-key> --hours 168 --tolerance 0.1
+# Override the bot's configured grid increment
+npm run analysis:grid-check -- --bot-key <bot-key> --hours 168 --increment 0.5
 ```
 
 Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolve via `profiles/bots.json` (`--list-bots` to enumerate); the account defaults to the bot's stored `accountId` when present (no chain lookup — the ID is auto-saved next to `preferredAccount` after the first successful name resolution, re-verified with `--refresh-account`), otherwise `preferredAccount` is resolved on-chain, and can be overridden with `--account <1.2.x|name>`.
@@ -253,18 +250,18 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
 | `--hours <n>` | `168` | Lookback hours from now |
 | `--start <iso>` / `--end <iso>` | — | Absolute time window |
 | `--account <id>` | bot `preferredAccount` | Override account ID or name |
-| `--lookup` | off | Legacy (no-op): account names always resolve via BitShares node when no stored ID exists |
 | `--refresh-account` | off | Force re-resolution of `preferredAccount` and update the stored `accountId` when it changed |
+| `--increment <pct>` | bot config / `0.5` | Grid increment used to derive the half-increment guard band |
 | `--per-fill` | off | Check at fill granularity instead of per-order aggregated |
 | `--include-cross-pair` | off | Also check consecutive fills across different pairs |
-| `--tolerance <pct>` | `0` | Adverse price move (%) forgiven before flagging |
+| `--tolerance <pct>` | — | Deprecated compatibility alias for `--increment`; its value is doubled and a warning is emitted |
 | `--json <file>` / `--csv <file>` | — | Export violations |
-| `--verbose` | off | Print the full trade sequence |
+| `--verbose` | off | Print the fetched trade sequence before checking |
 | `--list-bots` | — | List available bot keys and exit |
 
 </details>
 
-**Notes:** strict sat-level comparison is the ground truth (`--tolerance` only forgives small inversions); partial fills at one price are collapsed to a weighted-average price in the default mode, but fills after a native order repricing are kept in separate price epochs so updated orders are not mixed together.
+**Notes:** this is an offline approximation of decision-time placement. Batch-placed orders can share an earlier pivot, and the tool does not model the runtime spread-correction bypass. In the default mode, partial fills at one price are collapsed to a weighted average while fills from separate native order repricing epochs remain independent.
 
 ## Charts & Visualization
 
@@ -395,7 +392,6 @@ Shared analyzers and chart renderers for the dynamic-weight signal path. Core en
 **Research docs:**
 - [README.md](trend_detection/README.md) — directory overview and module index
 - [DYNAMIC_WEIGHT_RESEARCH.md](trend_detection/DYNAMIC_WEIGHT_RESEARCH.md) — AMA+Kalman blend with Hurst/PE regime gating, formula reference, knob guide
-- [SIGNAL_DOCUMENTATION.md](trend_detection/SIGNAL_DOCUMENTATION.md) — legacy SMA/MACD/RSI derivative signal layer
 
 <details><summary>Modules (click to expand)</summary>
 
@@ -509,7 +505,6 @@ These npm scripts wrap common analysis runners:
 | `npm run analysis:tradingview` | `node dist/analysis/tradingview/analyze_tradingview.js` |
 | `npm run analysis:trade-pnl` | `node dist/analysis/trade_profitability.js` |
 | `npm run analysis:grid-check` | `node dist/analysis/grid_correction_check.js` |
-| `npm run analysis:derivatives` | `node dist/analysis/analyze_derivatives.js` (legacy SMA/MACD/RSI layer, reference only) |
 | `npm run ama:chart:lp-local` | `node dist/analysis/ama_fitting/generate_unified_comparison_chart.js` (chart also auto-generated by optimizer) |
 
 All accept `--` forwarded flags.
@@ -521,7 +516,7 @@ npm run analysis:tradingview -- --source market_adapter --bot-key <bot-key>
 # Trade PnL
 npm run analysis:trade-pnl -- 1.2.123456 --hours 720
 
-# Grid correction check (monotonicity regression gate)
+# LAST-FILL-GUARD check
 npm run analysis:grid-check -- --bot-key <bot-key> --hours 168
 
 # File-based

package/analysis/account_resolver.ts

@@ -158,14 +158,4 @@ async function resolveAccountRef(accountRef: string, options: ResolveOptions = {
     return { accountId: String(id), botKey: null, botMeta: null, source: 'resolved', reason: null };
 }
 
-export {
-    ACCOUNT_ID_RE,
-    lookupNameOnChain,
-    resolveBotAccount,
-    resolveAccountRef,
-    ResolveOptions,
-    ResolvedAccount,
-    ResolveSource,
-    ResolveFailure,
-    NameLookup,
-};
+export { resolveBotAccount, resolveAccountRef };

package/analysis/bot_usage/kibana_bot_queries.ts

@@ -207,5 +207,5 @@ function buildTopUpdaterAccountsQuery(lookbackHours: number, topN: number = 200,
 
 // ─── Exports ──────────────────────────────────────────────────────────────────
 
-export { DEFAULT_CONFIG, kibanaSearch, buildOrderPriceQuery, buildTopSellerAccountsQuery, buildTopCancellerAccountsQuery, buildTopFilledAccountsQuery, buildTopUpdaterAccountsQuery, OP_LIMIT_ORDER_UPDATE }
+export { DEFAULT_CONFIG, kibanaSearch, buildOrderPriceQuery, buildTopSellerAccountsQuery, buildTopCancellerAccountsQuery, buildTopFilledAccountsQuery, buildTopUpdaterAccountsQuery }
 

package/analysis/chain_pool.ts

@@ -44,4 +44,4 @@ async function withReadOnlyClient<T>(fn: (client: any) => Promise<T>): Promise<T
     }
 }
 
-export { defaultNodePool, withReadOnlyClient };
+export { withReadOnlyClient };

package/analysis/fills_source.ts

@@ -219,16 +219,10 @@ async function fetchAllFills(config: any, accountId: string, gte: string, lte: s
 
 export {
     BTS_ID,
-    OP_FILL_ORDER,
-    ASSETS,
-    resolvedPrecisions,
     assetSymbol,
     assetPrec,
     toReal,
     resolveAssetPrecisions,
-    buildFillQuery,
     fetchAllFills,
-    AssetInfo,
-    AssetAmount,
     FillRecord,
 };

package/analysis/grid_correction_check.ts

@@ -2,9 +2,9 @@
 'use strict';
 
 /**
- * GRID CORRECTION CHECK
+ * LAST-FILL-GUARD CHECK
  *
- * Validates LAST-FILL-GUARD discipline (ceb53819): pivot ± halfIncrement
+ * Validates LAST-FILL-GUARD discipline: pivot ± halfIncrement
  *   Last fill @x with increment i (half=i/2) gates BOTH sides regardless of
  *   last side — BUY must be < x*(1-half/100), SELL > x*(1+half/100).
  *   e.g. x=1000, i=0.5% => BUY < 997.5 / SELL > 1002.5.
@@ -21,7 +21,7 @@
  * modules/constants.ts:DEFAULT_CONFIG.incrementPercent fallback (0.5).
  *
  * Fetches fill_order operations from Kibana (same pipeline as
- * trade_profitability.ts) and checks for price-order violations.
+ * trade_profitability.ts) and checks for last-fill guard violations.
  *
  * Usage:
  *   node dist/analysis/grid_correction_check.js --bot-key <bot-key> --hours 168
@@ -166,7 +166,6 @@ Time range (one of):
 
 Options:
   --account <id>         Override account ID (default: from bot preferredAccount)
-  --lookup               Legacy: account names always resolve via BitShares node
   --refresh-account      Force re-resolution of preferredAccount and update the
                          stored accountId when it changed (default: reuse the
                          stored accountId with no chain lookup)
@@ -176,7 +175,7 @@ Options:
   --include-cross-pair   Check consecutive fills across different pairs (default: same pair only)
   --json <file>          Export violations as JSON
   --csv <file>           Export violations as CSV
-  --verbose              Show all consecutive pairs, not just violations
+  --verbose              Print the fetched trade sequence before checking
   --list-bots            List available bot keys and exit
   --help, -h             Show this help
 
@@ -208,7 +207,6 @@ function parseArgs() {
         start: null,
         end: null,
         account: null,
-        lookup: false,
         refreshAccount: false,
         perFill: false,
         includeCrossPair: false,
@@ -225,7 +223,6 @@ function parseArgs() {
             case '--start': opts.start = args[++i]; break;
             case '--end': opts.end = args[++i]; break;
             case '--account': opts.account = args[++i]; break;
-            case '--lookup': opts.lookup = true; break;
             case '--refresh-account': opts.refreshAccount = true; break;
             case '--per-fill': opts.perFill = true; break;
             case '--include-cross-pair': opts.includeCrossPair = true; break;
@@ -472,10 +469,9 @@ function detectViolations(
     items: (TradeFill | AggregatedOrder)[],
     includeCrossPair: boolean,
     incrementPercent: number,
-): { violations: Violation[]; checkedPairs: number; sameDirectionPairs: number } {
+): { violations: Violation[]; checkedTransitions: number } {
     const violations: Violation[] = [];
-    let checkedPairs = 0;
-    let sameDirectionPairs = 0;
+    let checkedTransitions = 0;
 
     // Helper for a single chronological sequence (already filtered to one pair or global)
     function checkSequence(seq: (TradeFill | AggregatedOrder)[]) {
@@ -484,8 +480,7 @@ function detectViolations(
             const curr = seq[i] as any;
             // Skip same orderId (multi-fill split of one order) — aggregated mode already collapsed, but per-fill may split
             if (prev.orderId && prev.orderId === curr.orderId) continue;
-            checkedPairs++;
-            if (prev.direction === curr.direction) sameDirectionPairs++;
+            checkedTransitions++;
 
             const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction, incrementPercent);
             if (check.blocked) {
@@ -528,7 +523,7 @@ function detectViolations(
     }
     // Sort violations chronologically for reporting
     violations.sort((a, b) => new Date(a.curr.time).getTime() - new Date(b.curr.time).getTime());
-    return { violations, checkedPairs, sameDirectionPairs };
+    return { violations, checkedTransitions };
 }
 
 // ─── Reporting ────────────────────────────────────────────────────────────────
@@ -541,8 +536,7 @@ function printReport(
     trades: TradeFill[],
     orders: AggregatedOrder[] | null,
     violations: Violation[],
-    checkedPairs: number,
-    sameDirectionPairs: number,
+    checkedTransitions: number,
     skipped: number,
     rangeLabel: string,
     botKey: string,
@@ -565,7 +559,7 @@ function printReport(
 
     console.log('');
     console.log('═══════════════════════════════════════════════════════════════════');
-    console.log('  GRID CORRECTION CHECK — LAST-FILL-GUARD (pivot ± halfIncrement)');
+    console.log('  LAST-FILL-GUARD CHECK (pivot ± halfIncrement)');
     console.log('═══════════════════════════════════════════════════════════════════');
     console.log(`  Bot key:      ${botKey}${botMeta?.name ? `  (name: ${botMeta.name})` : ''}`);
     if (botMeta) console.log(`  Pair:         ${botMeta.assetA ?? '?'} / ${botMeta.assetB ?? '?'}`);
@@ -582,16 +576,16 @@ function printReport(
     if (orders) console.log(`  Orders (aggregated):  ${orders.length}  (from ${trades.length} fills)`);
     console.log(`  Pairs observed:       ${[...pairGroups.keys()].join(', ') || '-'}`);
     if (skipped > 0) console.log(`  Skipped (precision):  ${skipped}`);
-    console.log(`  Pairs checked:        ${checkedPairs} consecutive pairs (same-direction pairs: ${sameDirectionPairs})`);
-    console.log(`  Violations:           ${violations.length}${checkedPairs > 0 ? `  (${((violations.length / checkedPairs) * 100).toFixed(2)}%)` : ''}`);
+    console.log(`  Transitions checked:  ${checkedTransitions} consecutive fill/order transitions`);
+    console.log(`  Violations:           ${violations.length}${checkedTransitions > 0 ? `  (${((violations.length / checkedTransitions) * 100).toFixed(2)}%)` : ''}`);
     console.log('');
 
     if (violations.length === 0) {
-        console.log('  ✅  PASS — no grid inversions detected (all BUY < pivot-half, SELL > pivot+half).');
+        console.log('  ✅  PASS — no LAST-FILL-GUARD violations detected (all BUY < pivot-half, SELL > pivot+half).');
         console.log('');
-        if (checkedPairs === 0) {
-            console.log('  Note: no consecutive pairs in range to check.');
-            console.log('  (Need at least two fills/orders on the same pair.)');
+        if (checkedTransitions === 0) {
+            console.log('  Note: no consecutive transitions in range to check.');
+            console.log('  (Need at least two fills/orders to form a transition.)');
         }
         console.log('');
         return;
@@ -709,7 +703,7 @@ async function main() {
     const opts = parseArgs();
     const { gte, lte, label } = resolveTimeRange(opts);
 
-    console.log(`\nGrid correction check — bot-key: ${opts.botKey}`);
+    console.log(`\nLast-fill guard check — bot-key: ${opts.botKey}`);
     console.log(`Range: ${label}`);
 
     const resolvedAccount = await resolveBotAccount(opts.botKey, {
@@ -770,10 +764,10 @@ async function main() {
         items = orders;
     }
 
-    const { violations, checkedPairs, sameDirectionPairs } = detectViolations(items, opts.includeCrossPair, incrementPercent);
+    const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair, incrementPercent);
 
     const ordersForReport = opts.perFill ? null : (items as AggregatedOrder[]);
-    printReport(trades, ordersForReport, violations, checkedPairs, sameDirectionPairs, skipped, label, opts.botKey, accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
+    printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, opts.botKey, accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
 
     if (opts.json) exportJson(opts.json, violations, trades, label, opts.botKey, accountId, incrementPercent);
     if (opts.csv) exportCsv(opts.csv, violations);
@@ -781,7 +775,7 @@ async function main() {
     process.exit(violations.length > 0 ? 2 : 0);
 }
 
-export { isLastFillGuardBlocked, classifyFills, aggregateByOrder, detectViolations, TradeFill, FillRecord, Violation, AggregatedOrder };
+export { isLastFillGuardBlocked, classifyFills, aggregateByOrder, detectViolations, TradeFill, Violation, AggregatedOrder };
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     main().catch(e => {

package/analysis/resolve_source.ts

@@ -96,4 +96,4 @@ function resolveSource(config: SourceConfig, options: { quiet?: boolean } = {}):
 }
 
 export { resolveSource, listAvailableBots }
-export type { SourceConfig, SourceResolution }
+export type { SourceConfig }