dexbot 1.6.2 → 1.6.4

package/CHANGELOG.md

@@ -2,11 +2,59 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.6.4] - 2026-09-22 - Fund-Driven Spread Correction, GapSlots+1 Batch Cap, Analysis Shared Modules
+
+### 2026-09-21
+
+- **Fix(grid)**: include VIRTUAL orders in RMS structural divergence — `compareGrids()` filtered each side's RMS metric to ACTIVE orders only, so persisted-vs-ideal drift in VIRTUAL slots was invisible. VIRTUAL slots carry the planned reservation for unplaced rail slots (`funds.virtual`), and Available = ChainFree − Virtual − fees, so an over-reserved or stale virtual pins spending power without ever tripping a structural check. `filterForRms` now covers ACTIVE + VIRTUAL (PARTIAL/SPREAD stay excluded); ideal sizing already covers every slot of the side, so no other logic changes. A side whose only divergence is in VIRTUAL reservations now yields an RMS metric and can trigger the `rms_structural_grid_resync` full resync; the 14.3% threshold is unchanged. Docs: divergence-filter wording corrected in `docs/architecture.md` and `docs/GRID_RECALCULATION.md` (`modules/order/grid.ts`, `tests/test_grid_comparison.ts`; full suite 291 pass / 0 fail).
+
+- **Feat(spread)**: make spread correction purely fund-driven with a balance refresh fallback — `prepareSpreadCorrectionOrders` / `determineOrderSideByFunds` shrank resting orders to manufacture budget (self-funded tail recycling plus a generic redistribution donor loop). Those paths moved inventory within a rail and were gamed by stale-size snapshots: a donor's "current" size could lag a fill, so the recovered budget was phantom and the grid churned instead of healing. All shrink paths removed: corrections are funded only by free available/chainFree; when no side has funds the check returns `fundsExhausted` and the maintenance runtime refreshes account totals + open orders on the next tick via `getTargetedSyncReason` (a stale zero balance is re-read, not met with inventory recycling). New `tests/test_spread_pure_fund_driven.ts` (zero free → no side/create/shrink; funded → spend ≤ free and top-up only); SGP-6 now expects a skip (`modules/order/grid.ts`, `modules/dexbot_maintenance_runtime.ts`, `tests/test_targeted_drift_reconcile.ts`).
+
+- **Fix(sync)**: stop false sync-lock "disappeared" logs and correct shadow-lock metric — `_doSyncFromOpenOrders` collected slot ids and chain order ids into `orderIdsToLock`, then re-verified each with `mgr.orders.has(id)`. `mgr.orders` is keyed by slot id only, so every placed order's chain id failed the check and was logged as "disappeared between collection and locking" (~40 lines per sync, 3,461 in one production log) — phantom lines once mistaken for a COW race during a fill-storm investigation, and chain ids were silently dropped from the lock set. Collection and locking are synchronous, so the re-verification guarded an impossible window; the full collected set is now locked. `shadowOrderIds` aliases one order under two keys, so `size` double-counted live orders; new `OrderManager.getActiveShadowLockCount()` feeds the `shadowLocks` / `shadowLocksActive` metrics. New `tests/test_sync_lock_id_verification.ts` (`modules/order/sync_engine.ts`, `modules/order/manager.ts`, `modules/dexbot_maintenance_runtime.ts`).
+
+- **Feat(batch)**: raise fill/broadcast batch cap to gapSlots + 1 — `_getGapSlotBatchSize()`, the single source of truth for the fill-batch chunk size and the per-broadcast op cap, now returns the resolved gap-slot count + 1 instead of the count itself, giving one slot of headroom so a queue or operation set that previously spilled into an extra sequential broadcast chunk completes in a single cycle/transaction (1..gapSlots+1 fills → one unified batch; the non-finite/non-positive fallback still returns 1). Docs, constants/cow-runtime comments, and the batch-sizing tests updated to the new contract (`modules/dexbot_class.ts`, `modules/constants.ts`, `modules/dexbot_cow_runtime.ts`, `tests/test_cow_ops_per_broadcast.ts`, `tests/test_fill_batch_chunking.ts`, `tests/sim_batching.ts`).
+
+### 2026-09-20
+
+- **Docs(invariant)**: make grid-price invariant doc a fully present-tense contract — drops the mixed-state "What is still open" section (the blocking check has seen live traffic: 75 judgeable checks, 0 violations across four live bot logs), folds each item into its owning section, documents `runFinalPivotGate` as the seventh gate, adds a key-constants table, and cross-links the doc from `LIFECYCLE.md`, `COW_INVARIANTS.md` (INV-GRID-004), `GRID_RECONCILE.md`, `tests/README.md`, and `docs/README.md`; repoints dead `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md` references in `CHANGELOG.md` to the retrospective. Docs-only, no code or test behavior (`docs/GRID_PRICE_INVARIANT.md`, `docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md`).
+
+- **Refactor(code)**: purge dead code and internal-only exports across modules — drops the unreachable `processed_transaction` serializer chain in `bitshares-native/serial/operations.ts` (export list 98 → 17 names), the unused `CliColors` type, the never-read `_recentlyRotatedOrderIds` field, plus 56 internal-only exports across account/launcher/order/credential/crypto modules. Symbol visibility only, no behavioral impact (`npx tsc --noEmit` clean; `npm test` 290 pass, 0 fail).
+
+- **Docs(engine)**: consolidate order-engine docs and move legacy narrative to the history hubs — replaces `docs/CONSOLIDATED_ORPHAN_FIX_SUMMARY.md` with the synthesis hub `docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md` (§0–§8 numbering preserved: code comments and tests cite it), folds the grid-price-invariant history into retrospective Appendix A, and refreshes drifted refs/symbols across `COW_INVARIANTS.md`, `GRID_RECONCILE.md`, `LIFECYCLE.md`, `FUND_MOVEMENT_AND_ACCOUNTING.md`, and `architecture.md`. History (COW three-era/build-step narrative, memory-only tracking) moves into `docs/EVOLUTION.md`; docs/comment-only change, no runtime behavior.
+
+### 2026-09-18
+
+- **Fix(range)**: restore suizidal range threshold to 1.45x — reverts the 1.40 widening so sub-1.45x ranges flag red (suizidal) again and the tight orange zone is 1.45x–1.55x; single-sourced via `RANGE_QUALITY`, bot-editor legend and live range coloring only (`modules/constants.ts`). Trivial: TradingView toolbar tag shortened to `Offset` (tooltip keeps full name).
+
+### 2026-09-16
+
+- **Docs(onboarding)**: first-run troubleshooting — npm 12 install-script blocking + manual-build fallback, `dexbot` unknown-command diagnosis (failed link vs stale shell cache), `npm link` EACCES recovery, and pacman `-Syu` for Arch-derivative installs (`docs/BITSHARES_ONBOARDING.md`, `README.md`, `scripts/git-viewer.sh`). Docs-only.
+
+- **Refactor(analysis)**: centralize account/node handling, drop `--node` flags — new `analysis/chain_pool.ts` (single read-only chain entry point), `analysis/account_resolver.ts` (single preferredAccount/override decision tree), and `analysis/fills_source.ts` (shared asset-precision table + paginated fill fetch); `trade_profitability.ts` and `grid_correction_check.ts` use the shared modules. Name → accountId resolution always goes through the full built-in pool; breaks anyone passing the undocumented `--node` flag; no production runtime path touched. New `tests/test_analysis_account_resolver.ts`; full suite 290 pass, 0 fail, 15 live skipped.
+
+- **Feat(analysis)**: window-aware annualisation of profitability metrics — Sharpe/Sortino now bin the queried window into whole periods (daily for ≥3-day windows, else hourly), zero-filled so flat periods count as 0 PnL, with sample (n−1) variance and √periods-per-year scaling; Sharpe prints with Lo-2002 estimation error, Sortino returns Infinity with no losing periods; new "Projected net PnL" (scored net / scored days × 365); trailing partial periods excluded from ratios, projection, and activity rates via one shared predicate (`analysis/trade_profitability.ts`, `tests/test_trade_profitability_fees.ts`, `analysis/README.md`).
+
+- **Feat(charts)**: inline vendored uPlot into generated chart HTML — every generated chart embeds the vendored uPlot JS+CSS via `uplotInlineTags()`, so each export is a single self-contained document rendering anywhere with no CDN, install, or sibling-dir dependency (~53KB per chart; tests assert the banner is present and no `../uplot/` reference remains).
+
+- **Fix(update)**: don't fake pm2 process list or claim restarts that failed — when `pm2 jlist` fails the selective restart step no longer substitutes config-active bots for the process list, and `restarted` is set only when at least one `pm2 restart` succeeds, so the monolithic auto-start fallback and the manual-start notice fire correctly on installs without pm2 (`scripts/update.ts`).
+
+## [1.6.3] - 2026-09-14 - Correction-Queue Staleness Guard, Grid-Checker Price Epochs, Final Pivot Gate
+
+### 2026-09-15
+
+- **Fix(guard)**: final pre-broadcast pivot gate — a fill queued AFTER the batch-start pivot freeze but BEFORE broadcast passed every per-action LAST-FILL-GUARD check on a stale pivot (live incident on a market-pair bot: freeze at .745, sell fill queued at .765, batch of 4 broadcast at .910 against a buy pivot; the violating sell rotation filled 6s later, 0.6% below the true sell threshold, and tripped the fund invariant on drain). New `runFinalPivotGate()` re-checks BUILT ops against a re-refreshed pivot after the op-building loop and before the batch summary, fund validation, and single-flight claim: unchanged pivot is a pure no-op (arrays untouched, no extra probes); a moved/armed pivot re-runs the guard on each op's final price with the build loop's bypass rules (spread-correction CREATEs incl. batch-origin fallback, stamped gap-evacuations; unstamped evacuations guarded normally, same-slot UPDATEs resolve via source-id fallback) and drops violators into the existing skipped-slot restore paths (rotations restore source+dest from master, creates feed the refill-hold intersect, dropped CREATE pending entries removed by slot). Fail-open throughout: unresolvable price/type, cold pivot, and refresh throws all KEEP the op; cancels and size-updates are never gated. Pair-mode/chunk grouping is computed lazily at broadcast from the filtered opContexts (no stored indexes go stale); `cancelOpIndexByOrderId` (no live readers past op-building) is rebuilt from kept contexts as defence-in-depth. Pending-index hygiene: the gate's compaction REMAPS this batch's kept pending-broadcast entries' stored opIndex/ctxIndex to the compacted positions (lockstep keeps the two arrays aligned with each other but does not rewrite indexes stored inside pending entries — an unremapped ctxIndex would resolve to a shifted context after the first drop, letting the uncertain-broadcast reconcile adopt a matched chain order into the wrong slot); entries are identified by the fingerprints collected at record time (`recordPendingBroadcast` now returns its fingerprint; `entry.batchId` is always null in production and cannot discriminate), and entries whose referenced op was dropped are removed. Gate stats are kept separate from the build loop's counters (own `finalGateStats` object; reported as `gateChecked/gatePassed/gateSkipped/gateBypassed` fields on the batch summary, omitted when the gate did not re-check) so the summary's checked/passed/skipped totals stay the build loop's verdicts. The frozen pivot is captured AFTER the batch-start refresh (the refresh is part of the freeze) so batches whose freeze picked up a pre-freeze queued fill no longer trigger a spurious "pivot moved" warn + redundant re-check. Observability: always-on `Final gate: queue a->b pivot x->y` at debug, pivot-moved line at warn with freeze-queue depth + drop count, per-drop lines at warn. New `tests/test_final_pivot_gate.ts` (FG-1..FG-11, incl. incident replay dropping both violating rotations, the same-slot fallback, and pending-index remap identity checks); neighbor suites green (`modules/dexbot_cow_runtime.ts`).
+
+### 2026-09-14
+
+- **Fix(correction-queue)**: validate queued price corrections against the live slot before broadcast — corrections are queued as snapshots (expected price/size at detect time), but a geometry-changing resync re-slots/re-prices orders without invalidating the queue, so the maintenance pre-gate drain replayed stale snapshots and broadcast UPDATEs that reverted resync placements back onto occupied levels. Entries are now validated pre-broadcast against the live slot (ownership, price via slot predicates, size via integer quantum); stale entries are dropped and self-heal via the next sync re-queue. Zero-delta `updateOrder` returns `{success:true, skipped:true}` so routine no-ops no longer count as permanent failures; queue removal/dedupe is keyed on `(chainOrderId, isSurplus)` so sibling entries sharing a chain id survive; `queuedAt`/`queuedBy` provenance is stamped at queue time (sync detectors + gap-evacuation); drain summaries report `staleDropped` to keep failure WARN a true signal. New `tests/test_correction_queue_staleness.ts` (11 cases); 10 neighbor suites green (`modules/order/utils/order.ts`, `modules/order/sync_engine.ts`, `modules/dexbot_cow_runtime.ts`, `modules/dexbot_maintenance_runtime.ts`, `modules/order/manager.ts`).
+
+- **Fix(checker)**: split grid-correction checker fills into price epochs across repriced order lifetimes — the checker combined fills from different lifetimes of one order id after native repricing (limit-order update) operations and reported a false monotonicity violation. It now queries limit-order update operations and splits fills into chronological price epochs, preserving weighted aggregation for partial fills within one unchanged epoch (`analysis/grid_correction_check.ts`, `analysis/README.md`; TypeScript build passes, historical checker run clean).
+
 ## [1.6.2] - 2026-09-14 - Grid-Price Invariant, Gap-Slot Batch Sizing, Candle Shard Cache, Recovery Tolerance, Fill Counter Hygiene, Node List Cleanup
 
 ### 2026-09-14
 
-- **Fix(grid)**: enforce grid-price invariant at emission sites + escalate persistent corruption and stranded holds — the engine had two sources of truth for a slot's price — the genesis ladder (`priceForSlot(idx, genesis)`) and the mutable `slot.price` field — and every violation was the second winning over the first. Five mechanisms fed it: orphan adoption overwrote the slot's identity price (S1), a pre-broadcast "freshness" step re-substituted that corrupted price at debug level (S2), guards checked range membership but never grid membership (S3), the fill-guard pivot was written from unvalidated fill prices (S4), and guard bypasses skipped even that (S5). New `checkGridPriceInvariant` / `reportGridPriceInvariant` (`modules/order/utils/order.ts`) require the emitted price for a slot to equal its genesis level (fail-open on everything unjudgeable: no genesis, unparseable id, out-of-ladder index, non-finite price, checker error), enforced blocking at all six emission sites: CREATE, UPDATE (rotation), CREATE-FALLBACK (`modules/dexbot_cow_runtime.ts`); RECONCILE-CREATE, RECONCILE-UPDATE, STARTUP-CREATE (`modules/order/grid_reconcile_internal.ts`). Rotation UPDATE derives the emitted price from the destination slot's genesis level (`deriveRotationPrice`) instead of trusting the planner's carried `newPrice`; both pre-broadcast price substitutions removed (drift reported at warn, never adopted); legacy orphan adoption no longer writes `chainOrder.price` into `slot.price` and gains a rail guard; materialize path derives slot price (and side) from the ladder; `loadGrid` repairs a mismatched slot price from the genesis ladder in both validation modes; fill-guard pivot validated onto the ladder (`resolveOnGridPivot`: near-ladder pivots snap, far off-ladder fail open and are counted as `pivotOffGrid`). Persistent invariant rejection escalates after `GRID_PRICE_INVARIANT_RESYNC_THRESHOLD` consecutive rejecting batches per slot (bot-scoped streak, reset on clean check, 15m cooldown) to `requestStructuralGridResync('grid-price-invariant-violation')`. Out-of-bounds policy: hold and surface — grid geometry is not invalidated by the market leaving it (the removed 5% placement gate is documented as a design deadlock, not a tuning problem). New `docs/GRID_PRICE_INVARIANT.md` plus `docs/README.md` index entry and `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md` status refresh. Tests: new `tests/test_grid_price_invariant_guard.ts` (GPI-001..015) and `tests/test_grid_price_invariant_wiring.ts` (GPI-WIRE-001..008) plus `tests/test_startup_and_guard_log_hygiene.ts` (GPI-LOG-001); every behavioral fix mutation-tested (11 escalation/guard mutations verified); audited over 1,153 slots across five geometries with zero rejections; full suite 282/282 pass (`modules/order/utils/order.ts`, `modules/dexbot_cow_runtime.ts`, `modules/order/grid_reconcile_internal.ts`, `modules/order/grid.ts`).
+- **Fix(grid)**: enforce grid-price invariant at emission sites + escalate persistent corruption and stranded holds — the engine had two sources of truth for a slot's price — the genesis ladder (`priceForSlot(idx, genesis)`) and the mutable `slot.price` field — and every violation was the second winning over the first. Five mechanisms fed it: orphan adoption overwrote the slot's identity price (S1), a pre-broadcast "freshness" step re-substituted that corrupted price at debug level (S2), guards checked range membership but never grid membership (S3), the fill-guard pivot was written from unvalidated fill prices (S4), and guard bypasses skipped even that (S5). New `checkGridPriceInvariant` / `reportGridPriceInvariant` (`modules/order/utils/order.ts`) require the emitted price for a slot to equal its genesis level (fail-open on everything unjudgeable: no genesis, unparseable id, out-of-ladder index, non-finite price, checker error), enforced blocking at all six emission sites: CREATE, UPDATE (rotation), CREATE-FALLBACK (`modules/dexbot_cow_runtime.ts`); RECONCILE-CREATE, RECONCILE-UPDATE, STARTUP-CREATE (`modules/order/grid_reconcile_internal.ts`). Rotation UPDATE derives the emitted price from the destination slot's genesis level (`deriveRotationPrice`) instead of trusting the planner's carried `newPrice`; both pre-broadcast price substitutions removed (drift reported at warn, never adopted); legacy orphan adoption no longer writes `chainOrder.price` into `slot.price` and gains a rail guard; materialize path derives slot price (and side) from the ladder; `loadGrid` repairs a mismatched slot price from the genesis ladder in both validation modes; fill-guard pivot validated onto the ladder (`resolveOnGridPivot`: near-ladder pivots snap, far off-ladder fail open and are counted as `pivotOffGrid`). Persistent invariant rejection escalates after `GRID_PRICE_INVARIANT_RESYNC_THRESHOLD` consecutive rejecting batches per slot (bot-scoped streak, reset on clean check, 15m cooldown) to `requestStructuralGridResync('grid-price-invariant-violation')`. Out-of-bounds policy: hold and surface — grid geometry is not invalidated by the market leaving it (the removed 5% placement gate is documented as a design deadlock, not a tuning problem). New `docs/GRID_PRICE_INVARIANT.md` plus `docs/README.md` index entry and a `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md` status refresh (now absorbed into `docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md`). Tests: new `tests/test_grid_price_invariant_guard.ts` (GPI-001..015) and `tests/test_grid_price_invariant_wiring.ts` (GPI-WIRE-001..008) plus `tests/test_startup_and_guard_log_hygiene.ts` (GPI-LOG-001); every behavioral fix mutation-tested (11 escalation/guard mutations verified); audited over 1,153 slots across five geometries with zero rejections; full suite 282/282 pass (`modules/order/utils/order.ts`, `modules/dexbot_cow_runtime.ts`, `modules/order/grid_reconcile_internal.ts`, `modules/order/grid.ts`).
 
 - **Fix(fill)**: retire deferred-retry counter on queue settle + pin COW finally drain — the fill-consumer deferral counter (`_deferredFillRetryWaits`) only retired when a pending retry timer fired against an already-empty queue, so a queue drained by any other path left the counter elevated and the deferral log cadence stuck at warn (every 12th defer) after the backlog cleared. The counter now retires in `consumeFillQueue` at both settle points (top-of-run empty early-return and tail-after-drain); `_deferredFillRetryTimer` declared/initialized on the bot class and cleared on shutdown so the unref'd timer cannot leak across lifecycle restarts. New RETRY-007 pins the counter reset on a clean drain (7 → 0 on settle); RETRY-006 pins the COW batch finally (injected `_ensureCredentialDaemonWritable` throw after `_batchInFlight++` / `_cowBroadcastInFlight` asserts the finally releases both and reschedules the fill consumer exactly once; the COW layer converts the throw into a handled `{executed:false}` abort via `_handleBatchHardAbort`) (`modules/dexbot_fill_runtime.ts`, `modules/dexbot_class.ts`, `tests/test_fill_defer_retry.ts`; neighbors green, `tsc --noEmit` clean).
 
@@ -14,17 +62,19 @@ All notable changes to this project will be documented in this file.
 
 - **Fix(nodes)**: prune dead default nodes and single-source the connection-trace node list — `NODE_MANAGEMENT.DEFAULT_NODES` drops three dead endpoints, leaving seven live defaults; `tests/test_connection_trace.ts` no longer carries its own hardcoded copy — it reads `NODE_MANAGEMENT.DEFAULT_NODES` with an optional `BITSHARES_TRACE_NODE` override for single-node tracing, and the transport login probe uses `NODES[0]` instead of a hardcoded URL, so future node-list changes propagate automatically (`modules/constants.ts`, `tests/test_connection_trace.ts`).
 
+- **Test(seams)**: eliminate wall-clock sleeps and live-chain hangs from offline tests — offline unit tests slept on production pacing delays and opened real WebSocket connections (suite past 125s, several files over 5s each). New production test seams with defaults unchanged: `createSubscriptionManager` accepts `overrides.noticeCoalesceMs` (page-timeout watchdog unref'd), COW `options.pollIntervalMs` for the 1.5s missing-create poll (set/restored via try/finally across every batch exit path incl. re-plan recursion), `scheduleDeferredFillRetry`/`parkFillsForTotalsRetry` `retryDelayMs`, credit-split `settleDelayMs` plus overridable collateral-balance fetch, sync-engine targeted-refetch fns plus `_skipEmptyReadConfirmDelay`, and `disconnectClient` stopping node health monitoring on teardown. New `resolveSeamMs()`/`resolveSeamMsOrNull()` (`modules/utils/errors.ts`) consolidate seam resolution (explicit 0 disables the delay; null/undefined falls through to the default — fixes `retryDelayMs` `> 0` silently dropping explicit 0 and `Number(null) === 0` selecting 0); each caller records its resolved delay so tests assert resolution instead of wall-clock timing (write-only in production). New `tests/test_seam_resolve.ts` plus COW-COMMIT-012 (seam restore on the guard-refusal path, precedence explicit > bot > default, explicit 0 honored) and RETRY-003b / TOTALS-004 (0 resolves to 0 — the only discriminating input for `||`-vs-`??` regressions, verified by fault injection); two stale pre-eager-gap-recovery mock expectations corrected, dead CJS override removed. Suite 287 passed, 0 failed, 15 live skipped, ~85s (was ~126s); `tsc` main + tests clean (`modules/bitshares-native/subscriptions.ts`, `modules/bitshares_client.ts`, `modules/credit_runtime.ts`, `modules/dexbot_cow_runtime.ts`, `modules/dexbot_fill_runtime.ts`, `modules/dexbot_startup_runtime.ts`, `modules/order/sync_engine.ts`, `modules/utils/errors.ts`).
+
 ### 2026-09-13
 
 - **Feat(batch)**: derive fill/broadcast batch sizing from gap-slot count — two independent fixed caps (`FILL_PROCESSING.MAX_FILL_BATCH_SIZE` and `COW_PERFORMANCE.MAX_OPS_PER_BROADCAST`, both 4) bounded fill batching and per-broadcast order operations with no relationship to actual grid geometry. New `_getGapSlotBatchSize()` resolves via `resolveGapSlots()` (`manager._gapSlots`, else `calculateGapSlots(config)`, ≥1 floor, falls back to 1 on failure); legacy `_getMaxFillBatchSize()` / `_getMaxOpsPerBroadcast()` kept as thin aliases; dead `config._gapSlots` fallback operand removed; both constants removed from `modules/constants.ts` (remaining COW_PERFORMANCE keys unchanged). `executeChunkedWithRetryOnUncertain` prefers the gap-slot size with its own ≥1 guard. Docs across `architecture.md`, `LIFECYCLE.md`, `FUND_MOVEMENT_AND_ACCOUNTING.md`, `developer_guide.md` use gap-slot batch sizing terminology (stale FILL_PROCESSING snippet removed); `COPY_ON_WRITE_MASTER_PLAN.md` marks `MAX_OPS_PER_BROADCAST` removed with a pointer. Completed/obsolete legacy docs removed (not describing anything still in the code): `BROWSER_COMPAT_PLAN.md` (superseded by the package.json browser field + AGENTS.md), `GRID_PRICE_SLOT_DETERMINISM_PLAN.md` (implemented), `PLAN_FILL_STALE_RESTORE_MAIN.md` (implemented), `PLAN_MIN_BTS_VALUE.md` (completed plan), `crash_report_jan_mar_2026.md` (historical incident). Batch size now scales with grid size by construction (larger-gap grids produce larger fill batches and larger single broadcast transactions than the old fixed cap of 4 — intended); removed keys simply drop out of the runtime-settings override merge, no remaining consumers (`modules/dexbot_class.ts`, `modules/constants.ts`, `modules/dexbot_cow_runtime.ts`; `tests/test_cow_ops_per_broadcast.ts` mirrors via `manager._gapSlots` with strict `calculateGapSlots` equality, chunking/death-spiral expectations updated, `tests/sim_batching.ts` uses the GAP_SLOTS constant; full `npm test` exit 0).
 
-- **Fix(cache)**: store Kibana candle cache in stable calendar-month shards — run-relative chunk files (`chunk_<index>_<dates>`) shifted names on every run because windows anchor at floored-now, forcing a full rewrite plus an orphan-deletion pass each invocation; the deletion destroyed cached history (fully-disjoint files wiped by narrow runs, boundary-straddling files losing out-of-window buckets). Storage is now fixed UTC calendar-month shards (`<base>.shard_YYYY-MM.json`) decoupled from querying: runs load only overlapping shards, fetch only genuinely missing buckets, and rewrite solely shards that gained buckets (higher-volume-wins) or query coverage (monotonically unioned `queriedRanges`); pure-reuse runs do zero writes/deletes. Legacy `*.chunk_*` files are absorbed (buckets + clipped coverage folded into shards) and retired only when every bucket provably lives in a shard; disjoint legacy is never loaded or deleted. Removed `cleanupOrphanCacheChunks`, `chunkPathFor`, `siblingChunkFiles`, `priorQueriedInWindow`; preserved immutable-gap pruning, 48h tail refresh, partial-window withholding, fetch retry budget. Windows are now fetch-planning splits only (`{index, gte, lte}`); the LP orphan-cleanup wrapper/export is dropped. Preceded by the narrower prune-scope fix (run passes its active coverage; orphans whose `meta.timeRange` does not overlap it are kept) plus the chart fixes it was validated against: update-marker div reuse (`um-wrap` class) and log-scale vertical-pan/wheel-zoom bbox offset correction (`market_adapter/inputs/window_cache.ts`, `market_adapter/inputs/fetch_lp_data.ts`, `market_adapter/README.md`, `analysis/tradingview/tradingview_uplot_chart_generator.ts`; `tests/test_window_cache.ts` rewritten with shard mapping, coverage set ops, scoped-load, and end-to-end integrations; LP/book assertions target `.shard_` files; full suite exit 0; live-verified: repeated feed chart runs show pure reuse, a wider run refetched one genuinely-lost span and left 7 stable shards).
+- **Fix(cache)**: store Kibana candle cache in stable calendar-month shards — run-relative chunk files (`chunk_<index>_<dates>`) shifted names on every run because windows anchor at floored-now, forcing a full rewrite plus an orphan-deletion pass each invocation; the deletion destroyed cached history (fully-disjoint files wiped by narrow runs, boundary-straddling files losing out-of-window buckets). Storage is now fixed UTC calendar-month shards (`<base>.shard_YYYY-MM.json`) decoupled from querying: runs load only overlapping shards, fetch only genuinely missing buckets, and rewrite solely shards that gained buckets (higher-volume-wins) or query coverage (monotonically unioned `queriedRanges`); pure-reuse runs do zero writes/deletes. Legacy `*.chunk_*` files are absorbed (buckets + clipped coverage folded into shards) and retired only when every bucket provably lives in a shard; disjoint legacy is never loaded or deleted. Removed `cleanupOrphanCacheChunks`, `chunkPathFor`, `siblingChunkFiles`, `priorQueriedInWindow`; preserved immutable-gap pruning, 48h tail refresh, partial-window withholding, fetch retry budget. Windows are now fetch-planning splits only (`{index, gte, lte}`); the LP orphan-cleanup wrapper/export is dropped. Preceded by the narrower prune-scope fix (run passes its active coverage; orphans whose `meta.timeRange` does not overlap it are kept) plus the chart fixes it was validated against (issues #29/#30): update-marker div reuse (`um-wrap` class) and log-scale vertical-pan/wheel-zoom bbox offset correction (`market_adapter/inputs/window_cache.ts`, `market_adapter/inputs/fetch_lp_data.ts`, `market_adapter/README.md`, `analysis/tradingview/tradingview_uplot_chart_generator.ts`; `tests/test_window_cache.ts` rewritten with shard mapping, coverage set ops, scoped-load, and end-to-end integrations; LP/book assertions target `.shard_` files; full suite exit 0; live-verified: repeated feed chart runs show pure reuse, a wider run refetched one genuinely-lost span and left 7 stable shards).
 
 ## [1.6.1] - 2026-09-13 - Never-Run-Stale Hardening, Whitelist Range-Scaling Opt-In, Live-Save Docs, Shelf-Count Hardening
 
 ### 2026-09-13
 
-- **Fix(recovery)**: give the GRID-PRICE-INVARIANT guard and the deferred-hold policy a self-healing exit — both had the same shape (state the guard refuses to emit, but nothing repairs it) and both now escalate to the existing structural resync rather than running forever. A slot rejected as off-grid is skipped and warned, which is correct for a one-off, but the recurring planner carries the slot's price straight from `manager.orders`, so an in-process corruption is re-planned, re-rejected and re-warned every cycle with nothing able to heal it short of a restart — the slot is dead while the bot looks healthy, and the repeated warns train operators to ignore them. The guard now counts **consecutive** rejecting batches per slot (bot-scoped — the monolithic runtime (`dexbot.ts`, the `dexbot` bin) builds EVERY active bot in one process, so a module-level streak would let one bot's rejections push another to the threshold on its FIRST rejection and fire a spurious resync on a healthy bot, and the count also must not outlive a repair; GPI-WIRE-009 pins the cross-bot case) and at `TIMING.GRID_PRICE_INVARIANT_RESYNC_THRESHOLD` (3) fires `requestStructuralGridResync('grid-price-invariant-violation', {slotId, expected, actual, site, streak})`; a clean check clears the streak so escalation means "rejected N consecutive batches", not "N times ever", and `GRID_PRICE_INVARIANT_RESYNC_COOLDOWN_MS` (15m) bounds repeats. Healing in place at rejection time is deliberately NOT done — silently rewriting `slot.price` would erase the diagnostic signal distinguishing the four corruption sources. Separately, out-of-rail orphans hold locked funds and are never auto-cancelled per cycle (correct: cancelling on ambiguous evidence is irreversible), but "held indefinitely" had no exit; a hold whose signature is unchanged for `DEFERRED_HOLD_ESCALATE_MS` (24h) now escalates at `error` to `requestStructuralGridResync('deferred-hold-stale')`, which is safe because the full reset's reconcile is update-first (unmatched orders are price-updated onto rail slots, only true surplus cancelled), so funds are released without inventing a new cancellation policy. Hold age is tracked **per stranded order** (bot-scoped map keyed `id@price/size:reason`), because two simpler clocks were wrong: `manager._lastUnmatchedChainOrdersAt` is unconditionally refreshed on every sync observing any unmatched order, so it records "when we last looked" and an age gate on it could never fire (HOLD-007 pins this); and the whole-held-set signature clock looked correct but was **reset by unrelated churn** — the signature includes every entry's reason, so an unrelated hold flapping in and out restarted the clock every cycle and starved a genuinely stranded order of escalation forever (HOLD-010 pins this; a 6-hourly flap was simulated reporting a clock reset on every tick). A third defect sat in the same path: the signature-change branch `return`ed before the escalation call, so any churn skipped escalation entirely — escalation now runs on both branches, since a signature change is a reason to re-log, not to stop evaluating age. Escalation triggers only on genuinely **stranded** reasons via a narrow allow-list (`isStrandedHoldOrder`: `out-of-rail-deferred`, `out-of-grid-deferred`) rather than the broad `-deferred` non-blocking filter, because a resync cannot end a broadcast region or re-evaluate an uncommitted boundary; `broadcast-active-deferred`, `boundary-hold-trailing-market`, `boundary-unknown-deferred` and `held-plan-unchanged-deferred` are excluded (HOLD-011 pins this), and the allow-list fails closed so a future transient reason is excluded by default. Both escalations reuse the existing debounced, batch-in-flight-aware resync path; a second repair mechanism would duplicate tested machinery. New GPI-WIRE-006..009 (`tests/test_grid_price_invariant_wiring.ts`) and HOLD-006..011 (`tests/test_hold_and_center_guards.ts`); mutation-verified that removing the escalation call, removing the streak reset, disabling the cooldown, removing the hold escalation, re-gating escalation behind the signature early return, reading the hold age from the whole-set clock, and replacing the stranded allow-list with the broad `-deferred` filter are each caught (`modules/constants.ts`, `modules/dexbot_cow_runtime.ts`, `modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`, `docs/CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`).
+- **Fix(recovery)**: give the GRID-PRICE-INVARIANT guard and the deferred-hold policy a self-healing exit — both had the same shape (state the guard refuses to emit, but nothing repairs it) and both now escalate to the existing structural resync rather than running forever. A slot rejected as off-grid is skipped and warned, which is correct for a one-off, but the recurring planner carries the slot's price straight from `manager.orders`, so an in-process corruption is re-planned, re-rejected and re-warned every cycle with nothing able to heal it short of a restart — the slot is dead while the bot looks healthy, and the repeated warns train operators to ignore them. The guard now counts **consecutive** rejecting batches per slot (bot-scoped — the monolithic runtime (`dexbot.ts`, the `dexbot` bin) builds EVERY active bot in one process, so a module-level streak would let one bot's rejections push another to the threshold on its FIRST rejection and fire a spurious resync on a healthy bot, and the count also must not outlive a repair; GPI-WIRE-009 pins the cross-bot case) and at `TIMING.GRID_PRICE_INVARIANT_RESYNC_THRESHOLD` (3) fires `requestStructuralGridResync('grid-price-invariant-violation', {slotId, expected, actual, site, streak})`; a clean check clears the streak so escalation means "rejected N consecutive batches", not "N times ever", and `GRID_PRICE_INVARIANT_RESYNC_COOLDOWN_MS` (15m) bounds repeats. Healing in place at rejection time is deliberately NOT done — silently rewriting `slot.price` would erase the diagnostic signal distinguishing the four corruption sources. Separately, out-of-rail orphans hold locked funds and are never auto-cancelled per cycle (correct: cancelling on ambiguous evidence is irreversible), but "held indefinitely" had no exit; a hold whose signature is unchanged for `DEFERRED_HOLD_ESCALATE_MS` (24h) now escalates at `error` to `requestStructuralGridResync('deferred-hold-stale')`, which is safe because the full reset's reconcile is update-first (unmatched orders are price-updated onto rail slots, only true surplus cancelled), so funds are released without inventing a new cancellation policy. Hold age is tracked **per stranded order** (bot-scoped map keyed `id@price/size:reason`), because two simpler clocks were wrong: `manager._lastUnmatchedChainOrdersAt` is unconditionally refreshed on every sync observing any unmatched order, so it records "when we last looked" and an age gate on it could never fire (HOLD-007 pins this); and the whole-held-set signature clock looked correct but was **reset by unrelated churn** — the signature includes every entry's reason, so an unrelated hold flapping in and out restarted the clock every cycle and starved a genuinely stranded order of escalation forever (HOLD-010 pins this; a 6-hourly flap was simulated reporting a clock reset on every tick). A third defect sat in the same path: the signature-change branch `return`ed before the escalation call, so any churn skipped escalation entirely — escalation now runs on both branches, since a signature change is a reason to re-log, not to stop evaluating age. Escalation triggers only on genuinely **stranded** reasons via a narrow allow-list (`isStrandedHoldOrder`: `out-of-rail-deferred`, `out-of-grid-deferred`) rather than the broad `-deferred` non-blocking filter, because a resync cannot end a broadcast region or re-evaluate an uncommitted boundary; `broadcast-active-deferred`, `boundary-hold-trailing-market`, `boundary-unknown-deferred` and `held-plan-unchanged-deferred` are excluded (HOLD-011 pins this), and the allow-list fails closed so a future transient reason is excluded by default. Both escalations reuse the existing debounced, batch-in-flight-aware resync path; a second repair mechanism would duplicate tested machinery. New GPI-WIRE-006..009 (`tests/test_grid_price_invariant_wiring.ts`) and HOLD-006..011 (`tests/test_hold_and_center_guards.ts`); mutation-verified that removing the escalation call, removing the streak reset, disabling the cooldown, removing the hold escalation, re-gating escalation behind the signature early return, reading the hold age from the whole-set clock, and replacing the stranded allow-list with the broad `-deferred` filter are each caught (`modules/constants.ts`, `modules/dexbot_cow_runtime.ts`, `modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`, `docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md` — successor of the then-cited `docs/CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`).
 
 - **Fix(shelf)**: exclude shelf orders from every grid count (issue #27 follow-up) — the four shelf follow-ups gated `reserveEdgeIdSet`, `matchedExcess`, and the geometric size recalc to `parseSlotIndex(id) !== null`, but three counters feeding the same decisions never got the gate, so a live fork-kept shelf (non-slot-N id, `ACTIVE` + `orderId`) still poisoned them via the fail-open `isSlotInRail` geometry. `_countActiveOnGrid` inflated `matchedOnGrid` (suppressing `neededSlots`/creates), `chainCount` in `_reconcileStartupSide` counted shelf-bound chain orders (fabricating a `chain - target` surplus that cancelled real window orders), `countLiveGridOrders` masked window shortfalls in targeted sync, and `_getOnChainOrders` plus the spread `buyCount`/`sellCount` masked `oneSideEmpty`. All now apply the same slot-N gate (no-op on grids that only mint slot-N ids); shelf stays in the geometric-recalc denominator by design (conservative sizing direction). `_pickVirtualSlotsToActivate` and the `getInitialOrdersToActivate` window picks are gated too so a `VIRTUAL` shelf can never consume window activation budget (`modules/order/grid_reconcile_internal.ts`, `modules/dexbot_maintenance_runtime.ts`, `modules/order/grid.ts`, `modules/order/manager.ts`; `tests/test_reserve_orders.ts` shelf expectations corrected to the fixed behavior — chain 12 grid vs target 8 plans 4 rail cancels, grid count converges to 8 with 3 shelf surviving alongside — plus a new block pinning `_countActiveOnGrid`, startup create non-suppression, targeted-sync `buy 5/8` firing through shelf, and slot-N-only activation picks; `tests/test_startup_decision.ts`, `tests/test_resync_balance_fix.ts`, `tests/test_resync_duplicate_race.ts` fixtures migrated from ad-hoc ids to `slot-N` ids per the production invariant; full suite exit 0, zero failures).
 

package/README.md

@@ -65,8 +65,8 @@ Install Git:
 sudo apt-get update
 sudo apt-get install git
 
-# Arch/Manjaro
-sudo pacman -S git
+# Arch/Manjaro/CachyOS
+sudo pacman -Syu git
 
 # Fedora/RHEL
 sudo dnf install git
@@ -122,6 +122,10 @@ npm install
 npm link
 ```
 
+If `npm link` fails with `EACCES` or `dexbot` isn't found afterwards, see the
+[first-run troubleshooting](docs/BITSHARES_ONBOARDING.md#troubleshooting-first-run-mistakes)
+section in the onboarding guide.
+
 ### Where your data lives
 
 Both installs use the same CLI and store all user state — keys, `bots.json`, logs — in `~/.config/dexbot2/profiles` (Windows: `%USERPROFILE%\.config\dexbot2\profiles`). State lives outside the repo/package tree, so it survives reinstalls and `npm update -g`. A source checkout that already contains a populated `profiles/` directory keeps using it. Override the location with `DEXBOT_PROFILE_ROOT` (see the [developer guide](docs/developer_guide.md)).
@@ -271,7 +275,7 @@ dexbot clear               # Clear log files
 dexbot default             # Reset settings to defaults
 ```
 
-## 🎯 PM2 Process Management
+## ⚙️ PM2 Process Management
 
 PM2 is optional — `dexbot start` is the native solution.
 
@@ -313,12 +317,12 @@ Logs are written to `logs/` in the profiles directory in all modes: the monolith
 - **[Docs Index](docs/README.md)** - Main documentation hub
 - **[Architecture](docs/architecture.md)** - System design, fill processing pipeline, and testing strategy
 - **[Lifecycle](docs/LIFECYCLE.md)** - End-to-end walkthrough: startup, fill-driven, and AMA-driven flows with diagrams
-- **[Evolution Report](docs/EVOLUTION.md)** - Project timeline, architecture phases, and release history
-- **[Developer Guide](docs/developer_guide.md)** - Development guide, environment variables, examples, and glossary
-- **[Workflow](docs/WORKFLOW.md)** - Project workflow and contribution guide
-- **[Fund Movement & Accounting](docs/FUND_MOVEMENT_AND_ACCOUNTING.md)** - Fund accounting, grid topology, and rotation mechanics
 - **[Copy-on-Write Plan](docs/COPY_ON_WRITE_MASTER_PLAN.md)** - Copy-on-Write grid architecture
+- **[Fund Movement & Accounting](docs/FUND_MOVEMENT_AND_ACCOUNTING.md)** - Fund accounting, grid topology, and rotation mechanics
 - **[Claw API Boundary](claw/docs/AI_BOT_LIBRARY_API.md)** - Responsibility split between the AI layer and the DEXBot2 execution layer
+- **[Developer Guide](docs/developer_guide.md)** - Development guide, environment variables, examples, and glossary
+- **[Workflow](docs/WORKFLOW.md)** - Project workflow and contribution guide
+- **[Evolution Report](docs/EVOLUTION.md)** - Project timeline, architecture phases, and release history
 
 ## 🤝 Contributing
 

package/analysis/README.md

@@ -134,6 +134,8 @@ Fetches `fill_order` operations for a BitShares account from Kibana within a spe
 
 **Pipeline:** Kibana fill query → on-chain asset precision resolution → buy/sell classification → chronological matching (sequential LIFO by default) → per-pair summary + optional per-match detail.
 
+**Account resolution:** an account name (or a bare `1.2.x` ID) is resolved through the shared `account_resolver.ts` helper. When the name matches a bot in `profiles/bots.json`, the resolved ID is stamped onto that entry as `accountId`, so later runs resolve offline; `--refresh-account` forces a fresh lookup.
+
 ```bash
 # Account by ID, last 7 days (default)
 node dist/analysis/trade_profitability.js 1.2.123456
@@ -164,7 +166,6 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 | `--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` |
-| `--node <url>` | first healthy from built-in pool (10 nodes) | BitShares node for account + asset resolution |
 | `--csv <file>` | — | Export chronologically sorted trade list |
 | `--json <file>` | — | Export full analysis with per-pair PnL data |
 | `--match-mode <mode>` | `sequential` | Matching mode: `sequential` (LIFO, default) or `fifo` |
@@ -177,8 +178,8 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 **Asset precision handling:**
 
 1. Assets listed in the static `ASSETS` table (BTS, TWENTIX, XBTSX.*, HONEST.*, IOB.*, etc.) resolve instantly.
-2. Unknown assets are resolved on-chain via `get_assets` when `--node` is provided, with results cached at runtime.
-3. If no `--node` is given and an asset is unknown, the fill is **skipped** with a warning (no abort).
+2. Unknown assets are resolved on-chain via `get_assets` against the built-in node pool, with results cached at runtime.
+3. If resolution fails or an asset is not found on chain, the affected fills are **skipped** with a warning (no abort).
 
 **PnL methodology:**
 
@@ -206,9 +207,10 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 | `Expectancy (gross)` | How much one trade is expected to earn before fees. Positive = edge exists. The `R` version normalises this by the average loss size (reports in R-multiples instead of BTS). The `net` version subtracts fees. |
 | `Median R` | The middle R-multiple value (half of trades are above, half below). `>1R` / `>2R` = % of trades that earned more than 1× or 2× the average loss. `<-1R` = % that lost more than 1× the average loss. |
 | `PnL distribution` | Median, P25, P75, Best, Worst — the centre, spread, and extremes of per-trade return %. Not annualised, just per cycle. |
-| `Sharpe (ann)` | How consistent your daily net PnL is per unit of volatility. Dimensionful (based on absolute daily PnL, not % returns) — use for ranking your own runs, not comparing across account sizes. |
-| `Sortino (ann)` | Same method but only penalises days where you lost money (downside volatility). Higher than the Sharpe is normal; a big gap means most volatility came from winning days. |
-| `Max Drawdown` | Largest peak-to-trough equity decline as a % of the peak. How bad things got. |
+| `Sharpe (ann)` | The window's net PnL per unit of volatility, annualised (`mean/std × √periods-per-year`). Binned daily for ≥ 3-day windows, hourly below; every period counts, flat ones as 0 PnL. Shown as `value ± estimation error [bin, n, confidence]` — short windows are low confidence, and only same-bin runs are comparable. Dimensionful (absolute PnL, not % returns). |
+| `Sortino (ann)` | As Sharpe, but only losing periods feed the downside deviation. `∞` means the window had no losing periods. |
+| `Projected net PnL` | Scored-window net PnL scaled linearly to a year (`÷ scored days × 365`) — same whole-period basis as Sharpe/Sortino, so a trailing partial period is excluded from both. A projection, not a forecast. |
+| `Max Drawdown` | Largest peak-to-trough decline of the realised-PnL curve, in quote units (with the same decline as a % of peak cumulative profit). Realised only — open inventory isn't marked. |
 | `Max Recovery Time` | Longest time (in days) from the deepest point of a drawdown back to a new equity high. |
 | `Max Consecutive W/L` | Longest streak of winning or losing round-trips. Grouped by sell order, so one order covering multiple buy lots counts as one result. Grid bots naturally cluster wins during trends — streaks of 100-200 are not alarming. |
 | `Avg hold time` | Average time (hours) between buying an asset and selling it. |
@@ -216,16 +218,16 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 | `Sell orders filled` | Number of distinct sell orders that were filled in the period. |
 | `Partial fills/order` | How many buy lots each sell order consumed (mean, median, max). For a grid bot: 2.0 median means half the orders clear 2 grid levels; 18 max means one big sweep. |
 | `One-shot orders` | % of orders that matched exactly 1 buy lot. Low % = your grid is thick enough that orders routinely cover multiple levels. |
-| `Fills/day` | Average matched lots per calendar day. Raw activity speed. |
-| `Avg vol/day` | Average daily trading volume in the quote asset. |
+| `Fills/day` | Average matched lots per scored day, on the same whole-period basis as the ratios above. Raw activity speed. |
+| `Avg vol/day` | Average daily trading volume in the quote asset over that same scored window. |
 
 </details>
 
 ### Grid Correction 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/CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`.
+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`.
 
-**Pipeline:** Kibana `fill_order` query (paginated `search_after`) → on-chain asset precision resolution → buy/sell classification → chronological sort → per-order aggregation (multi-fill orders collapsed to weighted-avg price by default) → 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 same-direction pair comparison → violation report with daily histogram.
 
 ```bash
 # Per-order aggregated check (default), last 7 days
@@ -253,7 +255,6 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
 | `--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 |
-| `--node <url>` | first built-in node | Node for account/asset resolution |
 | `--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 |
@@ -263,7 +264,7 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
 
 </details>
 
-**Notes:** strict sat-level comparison is the ground truth (`--tolerance` only forgives small inversions); multi-fill orders are collapsed to a weighted-average price for the default per-order mode, so a single order's partial fills at identical prices never count as inversions.
+**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.
 
 ## Charts & Visualization
 
@@ -485,7 +486,12 @@ Details: [bot_fitting/README.md](bot_fitting/README.md)
 | `price_sources.ts` | Unified candle source abstraction (`json`, `market_adapter`) |
 | `chart_utils.ts` | Shared chart rendering utilities |
 | `math_utils.ts` | Shared math utilities |
-| `bot_key_utils.ts` | Bot-key resolution and candle file lookup |
+| `bot_key_utils.ts` | Bot-key resolution, candle file lookup, `accountId` persistence (`persistBotAccountId`) |
+| `account_resolver.ts` | Account resolution for all tools: `preferredAccount` / `--account` → `1.2.x`, stamping the result into `profiles/bots.json` |
+| `chain_pool.ts` | Ephemeral read-only chain client over the built-in node pool (account + asset lookups) |
+| `fills_source.ts` | Shared `fill_order` Kibana fetch/query and the static asset-precision table + on-chain cache |
+
+On-chain account and asset lookups in the fill-based tools go through `account_resolver.ts` / `fills_source.ts` (both built on `chain_pool.ts`): tool scripts must not open their own read-only clients or carry their own node list. The batch backfill `resolve_bot_accounts.ts` is the exception — it reuses the production chain client over one connection.
 
 ## npm Script Shortcuts
 
@@ -519,5 +525,5 @@ npm run ama:chart:lp-local -- --data market_adapter/data/lp/<pair>/lp_pool_<id>_
 ## Related Docs
 
 - [Market Adapter](../market_adapter/README.md) — live AMA pricing, grid triggers, dynamic weights, and recalc triggers
-- [Consolidated Orphan-Fix Summary](../docs/CONSOLIDATED_ORPHAN_FIX_SUMMARY.md) — orphan/gap-band root-cause plans; `grid_correction_check` is their regression gate
+- [Order Engine Retrospective](../docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md) — orphan/gap-band root-cause plans; `grid_correction_check` is their regression gate
 - [DEXBot2 Tuning Cheat Sheet](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md) — grid tuning reference for live bots

package/analysis/account_resolver.ts

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * SHARED ACCOUNT RESOLUTION (analysis)
+ *
+ * Central implementation of "preferredAccount / bare account reference →
+ * 1.2.x accountId" for every analysis tool, including stamping the resolved ID
+ * back into profiles/bots.json so later runs skip the chain lookup.
+ *
+ * trade_profitability.ts and grid_correction_check.ts used to each carry a
+ * private copy of this decision tree, of the chain lookup and of the node
+ * handling — all of it lives here now.
+ */
+
+import { findBotKeyByAccountRef, loadBotMeta, persistBotAccountId } from './bot_key_utils.js';
+import { withReadOnlyClient } from './chain_pool.js';
+
+const ACCOUNT_ID_RE = /^1\.2\.\d+$/;
+
+/** Chain lookup seam: batch tools can reuse one connection across lookups. */
+type NameLookup = (name: string) => Promise<string | null>;
+
+/** Default lookup: ephemeral read-only client over the built-in node pool. */
+async function lookupNameOnChain(name: string): Promise<string | null> {
+    try {
+        return await withReadOnlyClient(async (client) => {
+            const accounts = await client.db('lookup_account_names', [[name]]);
+            return Array.isArray(accounts) && accounts[0]?.id ? String(accounts[0].id) : null;
+        });
+    } catch (e: any) {
+        console.warn(`  [warn] Account resolution failed: ${e.message}`);
+        return null;
+    }
+}
+
+type ResolveSource = 'typed-id' | 'override-id' | 'override-resolved' | 'preferred-id' | 'stored' | 'resolved';
+type ResolveFailure = 'bot-not-found' | 'no-preferred-account' | 'override-unresolved' | 'name-unresolved';
+
+interface ResolveOptions {
+    /** Explicit override (--account). Wins over the bot entry and is never persisted. */
+    overrideAccount?: string | null;
+    /** Ignore a stored accountId and re-resolve on chain (--refresh-account). */
+    refresh?: boolean;
+    /** Suppress informational output; failures are reported via `reason`. */
+    quiet?: boolean;
+    /** Chain lookup override (batch tools reuse one connection, tests stub it). */
+    lookup?: NameLookup;
+    /** Override profiles/bots.json (tests use a temp file). */
+    botsFile?: string;
+}
+
+interface ResolvedAccount {
+    accountId: string | null;
+    botKey: string | null;
+    botMeta: any | null;
+    source: ResolveSource | null;
+    reason: ResolveFailure | null;
+}
+
+/**
+ * Persist a resolved ID onto the bot entry (no-op when it already matches) and
+ * report the outcome. `previous` is the stored value the write replaces, if any.
+ */
+function persistResolvedAccountId(botKey: string, accountId: string, previous: string | null, quiet: boolean, botsFile?: string): boolean {
+    const wrote = persistBotAccountId(botKey, accountId, botsFile);
+    if (quiet) return wrote;
+    if (wrote) {
+        console.log(previous && previous !== accountId
+            ? `  Updated stored accountId ${previous} → ${accountId} in profiles/bots.json for '${botKey}'`
+            : `  Stored accountId ${accountId} in profiles/bots.json for '${botKey}'`);
+    } else if (previous === accountId) {
+        console.log(`  Stored accountId ${accountId} confirmed up to date`);
+    } else {
+        console.warn(`  [warn] Could not store accountId ${accountId} in profiles/bots.json for '${botKey}'`);
+    }
+    return wrote;
+}
+
+/**
+ * Resolve the chain account for a bot entry:
+ *   explicit override > typed 1.2.x preferredAccount > stored accountId >
+ *   fresh chain lookup of the name.
+ * The resolved ID is persisted onto the entry whenever it differs from the
+ * stored one (an explicit override is never persisted — it is not the bot's
+ * preferredAccount).
+ */
+async function resolveBotAccount(botKey: string, options: ResolveOptions = {}): Promise<ResolvedAccount> {
+    const { overrideAccount = null, refresh = false, quiet = false, lookup = lookupNameOnChain, botsFile } = options;
+    const botMeta = botKey ? loadBotMeta(botKey, botsFile) : null;
+
+    // An explicit override always wins and is never persisted.
+    const override = overrideAccount != null ? String(overrideAccount).trim() : '';
+    if (override) {
+        if (ACCOUNT_ID_RE.test(override)) {
+            return { accountId: override, botKey, botMeta, source: 'override-id', reason: null };
+        }
+        if (!quiet) console.log(`  Resolving account name '${override}'...`);
+        const id = await lookup(override);
+        if (!id) return { accountId: null, botKey, botMeta, source: null, reason: 'override-unresolved' };
+        if (!quiet) console.log(`  → ${id}`);
+        return { accountId: String(id), botKey, botMeta, source: 'override-resolved', reason: null };
+    }
+
+    if (!botMeta) return { accountId: null, botKey, botMeta: null, source: null, reason: 'bot-not-found' };
+
+    const prefRaw = botMeta.preferredAccount != null ? String(botMeta.preferredAccount).trim() : '';
+    if (!prefRaw) return { accountId: null, botKey, botMeta, source: null, reason: 'no-preferred-account' };
+
+    const stored = ACCOUNT_ID_RE.test(String(botMeta.accountId ?? '')) ? String(botMeta.accountId) : null;
+
+    // A typed 1.2.x preferredAccount is authoritative — the stored accountId is
+    // a derived cache and must never override it. Self-heal the cache.
+    if (ACCOUNT_ID_RE.test(prefRaw)) {
+        if (stored !== prefRaw) persistResolvedAccountId(botKey, prefRaw, stored, quiet, botsFile);
+        return { accountId: prefRaw, botKey, botMeta, source: 'preferred-id', reason: null };
+    }
+
+    // Name + fresh-enough cache + no refresh requested: offline-friendly fast path.
+    if (stored && !refresh) {
+        if (!quiet) console.log(`  Using stored accountId ${stored} from profiles/bots.json (no lookup needed; pass --refresh-account to re-verify)`);
+        return { accountId: stored, botKey, botMeta, source: 'stored', reason: null };
+    }
+
+    if (!quiet) console.log(`  Resolving account name '${prefRaw}'...`);
+    const id = await lookup(prefRaw);
+    if (!id) return { accountId: null, botKey, botMeta, source: null, reason: 'name-unresolved' };
+    if (!quiet) console.log(`  → ${id}`);
+    persistResolvedAccountId(botKey, String(id), stored, quiet, botsFile);
+    return { accountId: String(id), botKey, botMeta, source: 'resolved', reason: null };
+}
+
+/**
+ * Resolve a bare account reference (1.2.x ID or name) to a chain account ID.
+ * When a bot in profiles/bots.json claims the name, the resolved ID is
+ * persisted onto that entry via resolveBotAccount.
+ */
+async function resolveAccountRef(accountRef: string, options: ResolveOptions = {}): Promise<ResolvedAccount> {
+    const ref = String(accountRef ?? '').trim();
+    if (ACCOUNT_ID_RE.test(ref)) {
+        return { accountId: ref, botKey: null, botMeta: null, source: 'typed-id', reason: null };
+    }
+
+    // A bot claiming this name is the persist target; its preferredAccount is
+    // the same name, so resolveBotAccount owns the whole decision tree.
+    let match: { botKey: string; meta: any } | null = null;
+    try {
+        match = findBotKeyByAccountRef(ref, options.botsFile);
+    } catch (_) {
+        // bots.json issues must never break resolution; fall through to chain.
+    }
+    if (match) return resolveBotAccount(match.botKey, options);
+
+    const lookup = options.lookup ?? lookupNameOnChain;
+    if (!options.quiet) console.log(`  Resolving account name '${ref}'...`);
+    const id = await lookup(ref);
+    if (!id) return { accountId: null, botKey: null, botMeta: null, source: null, reason: 'name-unresolved' };
+    if (!options.quiet) console.log(`  → ${id}`);
+    return { accountId: String(id), botKey: null, botMeta: null, source: 'resolved', reason: null };
+}
+
+export {
+    ACCOUNT_ID_RE,
+    lookupNameOnChain,
+    resolveBotAccount,
+    resolveAccountRef,
+    ResolveOptions,
+    ResolvedAccount,
+    ResolveSource,
+    ResolveFailure,
+    NameLookup,
+};

package/analysis/ama_fitting/analyze_lambda_vs_slow.ts

@@ -10,6 +10,7 @@ import { ensureDir } from '../../modules/order/utils/system.js';
 import { PATHS } from '../../modules/paths.js';
 import { MARKET_ADAPTER } from '../../modules/constants.js';
 import { getErrorMessage } from '../../modules/utils/errors.js';
+import { uplotInlineTags } from '../chart_utils.js';
 
 /**
  * LAMBDA vs SLOW ANALYSIS
@@ -186,9 +187,6 @@ function generateChartHtml(results: any, metricCache: any, fixEr: any, fixFast:
     const cacheSlow = metricCache.map((m: any) => m.slow);
     const cacheMove = metricCache.map((m: any) => m.movement);
 
-    const uplotCode = fs.readFileSync(path.join(PATHS.ANALYSIS.ASSETS_DIR, 'uPlot.iife.min.js'), 'utf8');
-    const uplotCSS = fs.readFileSync(path.join(PATHS.ANALYSIS.ASSETS_DIR, 'uPlot.min.css'), 'utf8');
-
     const amaAnnotations = [
         { label: 'AMA1', lambda: 0.0031, slow: 62.1, color: '#ef5350' },
         { label: 'AMA2', lambda: 0.0025, slow: 72.0, color: '#fb8c00' },
@@ -203,7 +201,6 @@ function generateChartHtml(results: any, metricCache: any, fixEr: any, fixFast:
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>λ → Slow — ER=${fixEr} Fast=${fixFast}</title>
 <style>
-  ${uplotCSS}
   body { font-family: system-ui, sans-serif; margin: 20px; background: #1e1e2e; color: #cdd6f4; }
   h1 { font-size: 16px; margin: 0 0 2px 0; }
   .subtitle { color: #a6adc8; font-size: 12px; margin-bottom: 12px; }
@@ -231,7 +228,7 @@ function generateChartHtml(results: any, metricCache: any, fixEr: any, fixFast:
 ${amaAnnotations.map(a => `<span class="legend-item"><span class="legend-dot" style="background:${a.color}"></span> ${a.label}</span>`).join('\n')}
   </div>
 </div>
-<script>${uplotCode}</script>
+${uplotInlineTags()}
 <script>
 (function() {
   const xs = ${JSON.stringify(xs)};

package/analysis/ama_fitting/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ama_fitting",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Tools for fitting AMA parameters to market data",
   "main": "../../dist/analysis/ama_fitting/optimizer_high_resolution.js",
   "scripts": {

package/analysis/bot_usage/discover_bot_accounts.ts

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 'use strict';
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-
-
 import { getStorage } from '../../modules/storage/index.js';
+import { withReadOnlyClient } from '../chain_pool.js';
 const { writeJSON } = getStorage();
 
 /**
@@ -58,7 +55,6 @@ import {
     buildTopUpdaterAccountsQuery,
     DEFAULT_CONFIG,
 } from './kibana_bot_queries.js';
-import { NODE_MANAGEMENT } from '../../modules/constants.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -283,33 +279,30 @@ function dexScore(creates: number, fills: number, _cancels: number, gridScore: n
 // ─── Account resolution ───────────────────────────────────────────────────────
 
 async function resolveNames(ids: string[]): Promise<Record<string, string>> {
-    const { createReadOnlyClient } = require('../../modules/bitshares-native');
-    const client = createReadOnlyClient({ nodes: NODE_MANAGEMENT.DEFAULT_NODES });
-
     const map: Record<string, any> = {};
     try {
-        await client.connect();
-        // BitShares db.get_objects accepts an array of IDs
-        const objects = await client.db('get_objects', [ids]);
-        for (const obj of (objects ?? [])) {
-            if (obj?.id && obj?.name) map[obj.id] = obj.name;
-        }
+        // Ephemeral read-only client over the built-in node pool (shared helper).
+        await withReadOnlyClient(async (client) => {
+            // BitShares db.get_objects accepts an array of IDs
+            const objects = await client.db('get_objects', [ids]);
+            for (const obj of (objects ?? [])) {
+                if (obj?.id && obj?.name) map[obj.id] = obj.name;
+            }
 
-        // Resolve extra asset precisions while connected
-        const toCheck = ['IOB.XRP', 'HONEST.MONEY', 'XBTSX.XRP', 'XBTSX.USDT', 'USD', 'CNY'];
-        for (const sym of toCheck) {
-            try {
-                const assets = await client.db('lookup_asset_symbols', [[sym]]);
-                const a = Array.isArray(assets) ? assets[0] : null;
-                if (a?.id && !(a.id in ASSET_PRECISION)) {
-                    (ASSET_PRECISION as Record<string, any>)[a.id] = a.precision;
-                }
-            } catch (_) {}
-        }
+            // Resolve extra asset precisions while connected
+            const toCheck = ['IOB.XRP', 'HONEST.MONEY', 'XBTSX.XRP', 'XBTSX.USDT', 'USD', 'CNY'];
+            for (const sym of toCheck) {
+                try {
+                    const assets = await client.db('lookup_asset_symbols', [[sym]]);
+                    const a = Array.isArray(assets) ? assets[0] : null;
+                    if (a?.id && !(a.id in ASSET_PRECISION)) {
+                        (ASSET_PRECISION as Record<string, any>)[a.id] = a.precision;
+                    }
+                } catch (_) {}
+            }
+        });
     } catch (e: any) {
         console.warn(`  [warn] Name resolution failed: ${e.message}`);
-    } finally {
-        try { client.disconnect(); } catch (_) {}
     }
     return map;
 }