dexbot 1.4.18 → 1.4.19

package/docs/EVOLUTION.md

@@ -2,14 +2,14 @@
 
 ## Executive Summary
 
-DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.4.18 stable release.
+DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.4.19 stable release.
 
 ### Key Milestones
 - **Project Inception**: December 2, 2025
 - **Growth Phase**: 2,024 commits over ~8 active months
 - **Code Maturity**: Evolution from basic utilities to a ~70,000+ LoC intelligent TypeScript system
 - **Stability**: Progression from manual testing to a suite of 249 automated test files
-- **Releases**: 95 release entries (v0.1.0 to v1.4.18)
+- **Releases**: 96 release entries (v0.1.0 to v1.4.19)
 
 ---
 
@@ -45,41 +45,29 @@ Consolidated the market adapter with split data sources, AMA-derived grid center
 
 ### Phase 5: Signal Intelligence, Stable Release & Browser Compatibility (March – June 2026)
 
-The project entered its most transformative phase: a derivative signal engine (dynamic trend-weighting, volatility scaling, regime classification) and a credit/debt MPA runtime were added, the codebase shed all external runtime dependencies while migrating fully to TypeScript, and a security audit of the unlock/daemon stack culminated in the first stable release — v1.0.0 on Jun 16, introducing profile validation, a shared-account fund registry with cross-bot invariants, and proportional collateral allocation. A browser-compatibility transformation followed — portable abstractions, pure-JS crypto, and storage-adapter I/O centralization made 140+ files browser-safe. This produced the multi-layered runtime that still shapes the project: COW order core, signal pipeline, credit/debt MPA runtime, and a browser-compatible core.
+The project entered its most transformative phase: a derivative signal engine (dynamic trend-weighting, volatility scaling, regime classification) and a credit/debt MPA runtime were added, the codebase shed all external runtime dependencies while migrating fully to TypeScript, and a security audit of the unlock/daemon stack culminated in the first stable release — v1.0.0 on Jun 16 (profile validation, shared-account fund registry, proportional collateral). A browser-compatibility pass (portable abstractions, pure-JS crypto, storage-adapter I/O) made 140+ files browser-safe. This produced the multi-layered runtime that still shapes the project: COW order core, signal pipeline, credit/debt MPA runtime, and a browser-compatible core.
 
 ### Phase 6: Production Hardening & Iterative Refinement (June – July 2026)
 
-Post-stable work focused on reliability: subscription health watchdogs, broadcast deadlock recovery at bot and daemon level, and documented system invariants. Iterative releases (v1.0.1–v1.3.3) delivered multi-round AMA refits, oversize credit deal splitting, COW broadcast recovery hardening, centralized node-fallback for BROADCAST_DEADLINE, credit-only mode, credential daemon memory fixes, and runtime extraction (COW, fill, state recovery) — an incremental-hardening phase that layered new subsystems (active fill polling, chart controls, HTML order export) onto the existing COW core without altering the core concurrency model.
+Post-stable work focused on reliability: subscription watchdogs, broadcast deadlock recovery at bot and daemon level, and documented system invariants. Iterative releases (v1.0.1–v1.3.3) delivered multi-round AMA refits, oversize credit deal splitting, COW recovery hardening, centralized node-fallback, credit-only mode, and runtime extraction (COW, fill, state recovery) — an incremental-hardening phase that layered new subsystems onto the existing COW core without altering its concurrency model.
 
-### Phase 7: Concurrency Model Correction (Late July 2026)
+### Phase 7: COW Concurrency & Uncertain-Broadcast Hardening (Late July 2026)
 
-CJS→ESM migration and strict-mode zero-errors across all source files completed the module transition. The v1.4.x releases that followed corrected the concurrency model — centralized `withBlockchainRetry` with node failover, a 4-layer duplicate CREATE guard, reordered lock hierarchy (`_syncLock`/`_gridLock` swap, refcount/stack nesting safety), AsyncLock forceRelease safety, and fund-accounting race hardening — fixing stale COW fund snapshots, phantom-order fund inflation, and the create-cancel loop.
+After the CJS→ESM migration and strict-mode zero-errors completed the module transition, the v1.4.x releases corrected the COW concurrency model — centralized `withBlockchainRetry` with node failover, a 4-layer duplicate CREATE guard, lock-hierarchy reorder, AsyncLock forceRelease safety, and fund-accounting race hardening — fixing stale COW fund snapshots, phantom-order inflation, and the create-cancel loop. v1.4.8 then closed the uncertain-broadcast and truncated-read ambiguity classes: broadcasts are never blindly re-signed (the credential daemon retries only provably-untransmitted failures), uncertain outcomes surface as typed errors so the COW runtime verifies chain inclusion before re-broadcasting, and truncate-ambiguous `get_full_accounts` reads defer cancel/discard decisions instead of freeing slots or capital for possibly-live orders.
 
-### Phase 8: Uncertain-Broadcast Safety & Truncated-Read Ambiguity (Late July 2026)
+### Phase 8: Native ESM Runtime, Broadcast Serialization & Onboarding (August 2026)
 
-v1.4.8 closed the duplicate-order and ambiguity classes found in an order-engine audit of test vs main. Broadcasts are never blindly re-signed — the credential daemon retries only provably-untransmitted failures (per-node pin + rotation + blacklist), and uncertain outcomes surface as typed errors so the COW runtime verifies chain inclusion before re-broadcasting. Truncated `get_full_accounts` reads are treated as ambiguous in every absence decision, so cancel/discard/recovery paths defer instead of freeing slots or capital for possibly-live orders. The COW pipeline also gained bounded stale-plan re-planning and exactly-once working-grid stack discipline.
+v1.4.12 completed the module transition to native ES modules (root + claw `"type": "module"`, Node >= 22 native WebSocket, dist-first ESM entry shims), removed the remaining legacy-compat shims, and pruned dead code — followed by fixes for the migration's rough edges (Node 22.14 require-cycle boot deadlock, phantom residuals, stranded dust, duplicate-orphan double-cancel). v1.4.13 added a single-flight guard that serializes overlapping COW broadcasts (preventing orphan fills), closed fill-lock bypasses, hardened the no-ALS AsyncLock fallback and ESM packaging gaps, promoted `dexbot start` to the canonical launch command, and added a BitShares onboarding tutorial.
 
-### Phase 9: Native ESM Runtime & Legacy-Compat Removal (August 2026)
+### Phase 9: Post-ESM Cleanup, Consolidation & Hardening (August 2026)
 
-v1.4.12 completed the module transition to native ES modules (root + claw flip to `"type": "module"`, Node >= 22 native WebSocket, dist-first ESM entry shims), removed the remaining one-time upgrade shims and backward-compat paths, and pruned dead constants/helpers. Post-release hardening smoothed the migration's rough edges: a Node 22.14 require-cycle boot deadlock, a fill-runtime require-binding stall, phantom residuals from un-batched same-order fills, stranded chain dust after sub-dust fills, and duplicate-orphan self-healing that double-cancelled or stranded funds.
-
-### Phase 10: Broadcast Serialization, Start Canonicalization & Onboarding (August 2026)
-
-v1.4.13 added a single-flight guard that serializes overlapping COW broadcasts (preventing orphan fills), closed fill-lock bypasses, hardened the no-ALS AsyncLock fallback, fixed ESM packaging gaps (engines `>=22.12.0`, `exports` map, browser classification), promoted `dexbot start` to the canonical launch command, stripped residual TUI-dashboard references, and added a BitShares onboarding tutorial for new users.
-
-### Phase 11: Unified Profile-State Resolution, In-Place Order Rotations & npm Auto-Update (August 2026)
-
-v1.4.16 centralized all user/runtime state onto a single resolver-derived profiles dir (`~/.config/dexbot2/profiles` for every install) so state survives re-clones and npm updates and never lands in a read-only package dir, with the credential runtime and shell-path mirror following the same resolution. Divergence corrections turn same-side surplus-cancel + hole-create pairs into single in-place `limit_order_update` rotations (fewer ops, order ids preserved), auto-update gained an npm-registry flow for global installs, and `chainKeys.authenticate()` no longer prompts for a master password when no vault exists.
-
-### Phase 12: Duplicate-Code Consolidation & Dead Export Purge (August 2026)
-
-v1.4.17 completed an audit-driven cleanup of `modules/`: the two EC math implementations and their Base58Check/hex/byte helpers were folded into the shared `pure_secp256k1` and `base58check` modules, settings merges and bots.json loaders were unified on one `deepMerge`/`loadSettingsFile`, asset resolution converged on a single `resolveAssetByRef`, and shared `nowIso`/`clamp`/`quantumForPrecision`/percentage helpers replaced inline copies. `modules/types.ts` shrank from 875 lines of unused interfaces to the Order union, the vendored serial layer and launcher modules dropped their dead exports, the `modules/logger.ts` and `math_utils.ts` re-export shims were deleted with ~30 importers repointed, and the analysis tooling gained a centralized source resolver plus shared chart CSS/browser-JS helpers under strict TypeScript.
+v1.4.16 centralized all user/runtime state onto a single resolver-derived profiles dir (`~/.config/dexbot2/profiles`) so it survives re-clones and npm updates and never lands in a read-only package dir, turned divergence surplus-cancel + hole-create pairs into in-place order rotations, and added an npm auto-update flow. v1.4.17 consolidated duplicate code (EC math, Base58Check, settings merge, asset resolution), trimmed `modules/types.ts` from 875 lines to the Order union, purged dead exports, and centralized the analysis tooling under strict TypeScript. v1.4.19 capped COW broadcasts at `MAX_OPS_PER_BROADCAST` (4) with chunked retry-on-uncertain broadcasting, fixed a spread-collapse regression via the shared `isSlotInRail` helper, lowered the AMA slope grid-reset threshold to 8, and added editor price feedback plus a `docs/LIFECYCLE.md` onboarding walkthrough.
 
 ---
 
 ## Development Statistics
 
-The project has accumulated 249 automated test files across 94 release entries. See the **Version History** below for a per-release commit breakdown.
+The project has accumulated 249 automated test files across 95 release entries. See the **Version History** below for a per-release commit breakdown.
 
 ---
 
@@ -128,84 +116,26 @@ DEXBot2 has matured from a basic grid bot into a signal-intelligent, production-
 - **Backtesting Engine**: Historical candle replay through the trading engine via exchange abstraction
 - **Injectable Interfaces**: Dependency inversion at call boundaries for improved testability
 - **Database + Validation**: SQLite persistence with Zod schema validation at the blockchain boundary
-- **Telegram Bot**: planned but **not yet implemented** — owner-gated Telegram control surface (design doc only). Monitoring (`/status`, `/orders`, `/grid`, `/balance`, alerts) is owner-gated; control (`/start`, `/stop`, `/pause`, `/set`) requires an explicit opt-in plus a confirm step; DEXBot is the only writer and private keys never reach the module. Config via `TELEGRAM` block + `DEXBOT_TELEGRAM_TOKEN` env.
+- **Telegram Bot**: planned but **not yet implemented** — owner-gated monitoring (`/status`, `/orders`, `/grid`, `/balance`) and opt-in+confirm gated control (`/start`, `/stop`, `/pause`); DEXBot is the only writer, private keys never reach the module. Config via a `TELEGRAM` block + `DEXBOT_TELEGRAM_TOKEN` env.
 
 ## Version History
 
-Compact view; per-commit detail lives in [CHANGELOG.md](../CHANGELOG.md).
-
-| Release | Commits | Theme |
-|---------|--------:|-------|
-| v0.1.0 → v0.2.0 | 29 | Core order/fund management, docs, tooling |
-| v0.2.0 → v0.3.0 | 155 | Fund mgmt & BTS fees, grid divergence, persistence, race conditions |
-| v0.3.0 → v0.4.0 | 18 | Fund consolidation, grid sizing/quantization, partial orders |
-| v0.4.0 → v0.5.0 | 92 | AsyncLock race prevention, fill dedup, dust recovery, spread correction |
-| v0.5.0 → v0.6.0 | 598 | COW architecture, strategy/sync engine, credential daemon, AMA prototype |
-| v0.6.0 → v0.7.0 | 325 | AMA market adapter, credit/MPA debt runtime, analysis suite |
-| v0.7.0 → v0.7.4 | 12 | AMA/Kalman stability, Docker launcher, docs refresh |
-| v0.7.4 → v0.7.5 | 93 | Zero-dependency & TS migration, native BitShares, fill detection overhaul |
-| v0.7.5 → v0.7.8 | 18 | Unlock/launcher hardening, background daemon, MPA `debtOnly` |
-| v0.7.8 → v0.7.11 | 33 | Runtime self-healing, COW integrity, foreign-daemon defense, CLI polish |
-| v0.7.11 → v0.7.15 | 31 | CLI/terminal polish, TradingView, CEX seeding, pipeline hardening |
-| v0.7.15 → v0.7.18 | 19 | Build/dir centralization, `@ts-nocheck` removal, timeout hardening, DRY |
-| v0.7.18 → v1.0.0 | 103 | First stable: profile validation, logging, credential security, browser compat |
-| v1.0.0 → v1.0.4 | 15 | Auto-update hardening, candle gap repair, update-script fixes |
-| v1.0.4 → v1.0.7 | 13 | Grid "one order per price" invariant, subscription watchdog, broadcast deadlock fix |
-| v1.0.7 → v1.0.9 | 9 | Pending-broadcast deadlock, log dedup, trade PnL analysis tool |
-| v1.0.9 → v1.0.11 | 20 | PnL metrics overhaul, live `bots.json`, BitShares market fee model |
-| v1.0.11 → v1.0.13 | 17 | Whitelist normalization, grid persistence safety net, dust pipeline fix, net inventory lots |
-| v1.0.13 → v1.0.14 | 4 | Per-bot runtime settings override pipeline, doc alignment & chart fix |
-| v1.0.14 → v1.1.0 | 7 | Unique bot names, stable ID removal, migration script, duplicate name enforcement |
-| v1.1.0 → v1.1.1 | 1 | Auto-startup migration, error handling, JSON-key tracking, cleanup |
-| v1.1.1 → v1.1.2 | 1 | AMA refit (λ=0.0022/step=0.0002), optimizer chart output, constant tuning, doc sync |
-| v1.1.2 → v1.1.3 | 4 | AMA refit (λ=0.0025/step=0.0003), per-AMA distance weights, tsx-CJS export fix, amaS% retune 0.085→0.08, doc sync |
-| v1.1.3 → v1.1.4 | 3 | AMA4 slow correction 107.4→102.4, optimizer range 50-200→40-160, post-tag doc sync |
-| v1.1.4 → v1.1.5 | 2 | AMA refit (per-AMA λ weights, SMA-warmup optimizer, slow 62.1/71.7/82.7/95.5), `maxBorrowAmountPerOperation` + oversized-deal splitter |
-| v1.1.5 → v1.1.6 | 1 | amaS% revert 0.08→0.085 |
-| v1.1.6 → v1.1.7 | 4 | Dust cancel hardening, bootstrap lifecycle fixes, lock reduction, order analysis AMA key, doc cleanup |
-| v1.1.7 → v1.1.8 | 6 | HTML order export, chart controls, lambda-vs-slow script, doc cleanup |
-| v1.1.8 → v1.1.9 | 6 | Immediate dust cancel, duplicate price guard, stale-cleaned simplification, dedup/lock cleanup, order analyzer formatting |
-| v1.1.9 → v1.1.10 | 4 | Asymmetric bounds/dynamic-weight flag decoupling, propagation fixes, `stats` CLI alias, range/weight indicators in status output |
-| v1.1.10 → v1.1.11 | 3 | npm publish prep, README install options, `.npmrc` ignore, sync log clarity |
-| v1.1.11 → v1.1.12 | 5 | Committed order protection, ghost order cleanup, price correction queue, AMA config centralization, XRP-BTS default removal |
-| v1.1.12 → v1.1.13 | 7 | COW recovery hardening (UPDATE→CREATE fallback, fresh-snapshot recovery, persisted-grid reload), fee cache persistence, node fallback, orphan-fill death spiral fix, duplicate order prevention, committed-order protection extension |
-| v1.1.13 → v1.1.14 | 5 | Node-failure blacklist sync, async-lock forceRelease safety, six gap regression fixes, browser-compat classification, bin path cleanup |
-| v1.1.14 → v1.2.0 | 11 | Credit-only mode, boundary shift recovery, order system hardening (stale broadcast flag, orphan-fill tolerance, grid-bloat resync, AsyncLock re-entrancy), parallel node connect, subscription re-entrancy guards, fund accounting stale-fetch guard, credit runtime TTL caching, transaction builder LRU fee cache, COW auto-cancel test coverage |
-| v1.2.0 → v1.2.1 | 8 | Adopt-boundary shift fix, stale accountTotals no-harden-abort, credential daemon memory leak, order correction reliability (dedup orphan cancels, retry on transient errors, skip redundant fallback), StateManager inline refactor, SyncResult type unification, code-review fixes (timer leaks, dead args, orphaned mutations, false recovery, side-effect impure getter) |
-| v1.2.1 → v1.2.2 | 4 | Invariant sabotage vector prevention (ghost-order, TOCTOU, fee over-credit), regression hardening (skipAccounting, committed-order escapes, stale fee fallback), code-review cleanup |
-| v1.2.2 → v1.2.3 | 5 | Uncertain-broadcast grid corruption fix (discarded CREATE slot recovery), unmatched-order adoption via `syncFromOpenOrders`, grid-bloat loop fix (full-rail false-positive, stale SPREAD type, empty-side correction, boundary-at-rail-edge), budget-dilution fix (virtual-slot exclusion), budget-cap regression fix, COW structural-resync safeguard, test updates |
-| v1.2.3 → v1.2.4 | 1 | Credential daemon memory — signing client cache (30-min TTL, fingerprint-based key rotation, dispose-then-delete contract), session purge interval, shallow policy copy, audit-log microtask reduction |
-| v1.2.4 → v1.2.5 | 3 | Redundant open-orders sync fix, supervisor updater override, waitForStableStartup event-loop hang fix, unref credit/dust intervals, base58 deduplication, key_store delegation cleanup, launch_modes clawOnly fix, test alignment |
-| v1.2.5 → v1.2.6 | 4 | Batch fill sync, crash-durable dedup, ghost batch cancel, config overrides, code-review fixes, EVOLUTION.md doc fix |
-| v1.2.6 → v1.2.7 | 1 | `node dexbot` → `dexbot` across all docs/CLI text, `npm i -g dexbot`, ALS re-entrancy test fix |
-| v1.2.7 → v1.3.0 | 1 | `dexbot unlock`/`dexbot pm2` rebranding, docstring sweep across 53 files, browser-field `market_adapter.js` exclusion, stale `typeof __filename` guard removal |
-| v1.3.0 → v1.3.1 | 6 | Repo-root symlinks (`./dexbot`/`./pm2`/`./unlock`), CLI canonical naming `keys`/`bots`→`key`/`bot`, browser exclusion completeness (logger, paths, system), README `npm link` fix + Quick Start dedup |
-| v1.3.1 → v1.3.2 | 6 | Startup dust health check, lightweight sync RMS/chain-filter fixes, dust-handling lock-safe cancel, `dexbot stat` CLI fix, capital allocation docs, README polish |
-| v1.3.2 → v1.3.3 | 12 | Runtime extraction (COW, fill, state recovery), dead-import cleanup, profile resolution fix, credential daemon hardening, pretest hook, EVOLUTION.md refresh |
-| v1.3.3 → v1.4.0 | 13 | CJS→ESM migration completion, strict-mode zero-errors, daemon-signing node failover, ghost-order cancellation, subscription keepalive fix, price-collision guard centralization, review-concerns dedup & runtime keys export, active fill polling |
-| v1.4.0 → v1.4.1 | 8 | withBlockchainRetry centralization + node failover, 4-layer duplicate CREATE guard, fresh-grid excess cancel fix, timeout death spiral fix, spread correction type filter, dead PARTIAL filter cleanup, Phase 3 stale surplus cancellation |
-| v1.4.1 → v1.4.2 | 3 | Spread correction direction bias removal, precision-based price collision guard, stale-node defense completion |
-| v1.4.2 → v1.4.3 | 5 | Boundary-shift state preservation across failed COW commits, SPREAD→BUY crosser handling, per-batch tolerance violation filter (no full abort), precision-0 tolerance overflow fix, poolRef pinned-pool price derivation, withTimeout utility extraction + circular dep fix |
-| v1.4.3 → v1.4.4 | 4 | COW invariant enforcement (retry on failed boundary-shift commit, no master patching), COW pipeline code review fixes, grid engine consolidation (deduplication, dead code removal, export cleanup), UNC-016 recovery test mock fix |
-| v1.4.4 → v1.4.5 | 2 | Code-review hardening: AsyncLock forceRelease safety, grid update fatal error guard, persist write failure handling, TOCTOU stale price fix, re-entrancy deadlock removal, circular dependency breakage, uncommitted boundary classification fix, dead code cleanup |
-| v1.4.5 → v1.4.6 | 8 | AsyncLock re-entrancy fix, grid type reassignment on load, refcount/stack hardening of state fields, lock hierarchy correction, stale COW fund snapshot fix, gapSlots persistence, phantom fund inflation fix, boundary shift cap |
-| v1.4.6 → v1.4.7 | 5 | Fund accounting race hardening, phantom-order startup inflation fix, create-cancel loop fix, negative free balance ordering, GRID_RECONCILE.md |
-| v1.4.7 → v1.4.8 | 26 | Uncertain-broadcast duplicate-order safety (verify-before-retry, per-node retry pin + blacklist), truncated-read ambiguity deferral (readOpenOrdersWithMeta), COW stale-plan replan + working-grid stack discipline, fill-authoritative rework, sell-rail re-anchor, orphan auto-cancel wiring, fill-batch fund-invariant deferral |
-| v1.4.8 → v1.4.9 | 2 | LP-collateral credit conversion rate via AMM (pool-derived source), flat CLI aliases (dexbot stop/restart/delete) for monolithic unlock controls |
-| v1.4.9 → v1.4.10 | 10 | Empty-slot normalization and spread boundary promotion, LP pool-share supply pricing fix, spread check independent of divergence, boundary-slot reconcile re-derivation, validation/broadcast dedup refactor, credit-unlock background daemon, test-suite runtime cut |
-| v1.4.10 → v1.4.11 | 8 | Minimum-slots guard for grid range scaling, monolithic restart restarts credential daemon, dexbot start→unlock alias + runtime-layout-aware unlock spawn fix, dead COW/diagnostic code prune, GRID_RECONCILE.md exposure, Telegram docs, CLI test retargeting to `dexbot test`, `dexbot status` reporting a surviving credential daemon after `stop` |
-| v1.4.11 → v1.4.12 | 21 | Full ESM migration (root + claw `"type": "module"`, dist-first entry shims, Node >= 22 native WebSocket, `ws` dep removal), legacy-compat removal (fs_utils shim, migrate_bot_keys, legacy daemon protocol, pre-1.1.0 wrapper migration, price-source/debtPolicy aliases), dead-code prune + re-entrancy guard restore, claw build aligned with root, 80 test typecheck errors fixed, ESM-cycle boot fix for Node 22.14, fill-runtime require-binding restore, same-order fill batching restore, residual-dust cancel, duplicate-orphan self-heal dedup + ORDER_GONE fund release, ESM direct-run guards + editor tsconfig coverage |
-| v1.4.12 → v1.4.13 | 4 | COW broadcast serialization, fill-lock bypass guards, no-ALS AsyncLock hardening, ESM packaging gaps, `dexbot start` canonicalization, TUI-dashboard reference removal, BitShares onboarding tutorial, npm claw coverage |
-| v1.4.13 → v1.4.14 | 13 | BitShares onboarding P2P-credit clarification, market-adapter math canonicalization (ATR/volatility/regime/Kalman embedded into chart sources), dead-code purge (market-adapter barrel + claw stale code, launcher PM2 crash fix), raw `npm start`/`pm2 start` launcher guard, `dexbot order <bot>` filter, HTML chart export readability, nvm Linux install, docs refresh (Telegram plan rename), claw strict-mode test annotations, AMA optimizer `_w` naming, CES power-law curve proposal |
-| v1.4.14 → v1.4.15 | 2 | Global npm install path handling (profiles, market-adapter, and claw data/state relocation under `~/.config/dexbot2/profiles`, `DEXBOT_MARKET_ADAPTER_DATA_DIR`/`STATE_DIR` and `DEXBOT_CLAW_DATA_DIR` env overrides, shared `scripts/lib/dexbot-paths.sh` for the clear/reset shell scripts, `clear-all` now wipes claw data), test alignment with sig-digit formatting |
-| v1.4.15 → v1.4.16 | 4 | Unified profile-state resolution (single resolver-derived profiles dir for all installs, credential-runtime `root` removal, shell-path mirror), divergence surplus/hole pairs → in-place rotations, npm auto-update flow for global installs, no master-password prompt when no vault exists |
-| v1.4.16 → v1.4.17 | 10 | Analysis source resolution centralization (`resolve_source.ts`) + strict TypeScript, shared chart CSS/browser-JS helpers, audit-driven duplicate-code consolidation (EC math, Base58Check, settings merge, asset resolution, nowIso/clamp/quantum helpers), dead export purge (`types.ts` trim, serial/launcher/formats, shim deletions), claw `createBotKey` dedup + runtime edge-case hardening, test/daemon regression fixes, full analysis toolset shipped in npm package, scripts README refresh |
-| v1.4.17 → v1.4.18 | 1 | tsx runtime dependency removal — compiled `node dist/...` workflow for all shims, npm scripts, and research tools (analysis toolset now ships compiled in the tarball), every doc/skill/usage string converted from `tsx ...ts` |
+Compact, era-level view; per-release commit detail lives in [CHANGELOG.md](../CHANGELOG.md).
+
+| Era | Commits | Theme |
+|-----|--------:|-------|
+| v0.1.0 → v0.6.0 | 1,217 | Foundation → COW architecture, strategy/sync engine, credential daemon, AMA prototype, credit/MPA runtime |
+| v0.6.0 → v1.0.0 | 309 | Zero-dependency & TS migration, native BitShares, fill detection overhaul, first stable release |
+| v1.0.0 → v1.1.0 | 85 | Post-stable hardening, PnL analytics, auto-update, broadcast deadlock fixes |
+| v1.1.0 → v1.3.3 | 114 | AMA refits, credit-only mode, COW recovery hardening, runtime extraction |
+| v1.3.3 → v1.4.8 | 74 | CJS→ESM completion, concurrency correction, uncertain-broadcast safety, truncated-read ambiguity |
+| v1.4.8 → v1.4.13 | 45 | Native ESM runtime, broadcast serialization, onboarding |
+| v1.4.13 → v1.4.19 | 36 | Profile-state centralization, code consolidation, per-broadcast op cap |
 
 ---
 
 **Report Originally Generated**: February 19, 2026
-**Last Updated**: August 19, 2026 (v1.4.18)
-**Total Commits**: 2,025
-**Date Range**: December 2, 2025 – August 19, 2026
+**Last Updated**: August 21, 2026 (v1.4.19)
+**Total Commits**: 2,044
+**Date Range**: December 2, 2025 – August 21, 2026
 **Repository**: DEXBot2 (BitShares DEX Trading Bot)

package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md

@@ -848,4 +848,4 @@ Two additional accounting hardening measures added in v1.2.1:
 **TOCTOU in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders`, but the order lock was acquired after accounting ran. Fixed by acquiring the lock first, then running `processFillAccounting` under the lock. This fix was also ported to POST-RESET and BOOTSTRAP tracked-fill accounting paths.
 
 ---
-*Technical Reference for DEXBot2 v1.4.18 release*
+*Technical Reference for DEXBot2 v1.4.19 release*

package/docs/LIFECYCLE.md

@@ -0,0 +1,207 @@
+# DEXBot2 Lifecycle — End-to-End Walkthrough
+
+This is the **one-page map** for newcomers. It stitches together the flows that are
+otherwise spread across `architecture.md` and `developer_guide.md` into two concrete
+lifecycles (fill-driven and maintenance-driven) plus the startup sequence. Read this
+first; follow the file/function references into the deeper docs.
+
+> All code references use `file:line` so you can jump straight to the source.
+
+---
+
+## 1. System Context
+
+Who talks to what. DEXBot2 is a long-running Node process that both *reads* the
+BitShares chain/market and *writes* limit orders back to it.
+
+```mermaid
+graph TB
+    OP[Operator<br/>CLI / PM2 / unlock.ts]
+    CHAIN[(BitShares Chain<br/>fills, open orders, balances)]
+    MKT[Market Data<br/>LP pools / order book / AMA feed]
+    STORE[(Local Storage<br/>profiles/orders/*.json<br/>profiles/bots.json)]
+    BOT[DEXBot2 Process<br/>dexbot_class.ts]
+
+    OP -->|configure / start| BOT
+    CHAIN -->|fill events op-4| BOT
+    CHAIN -->|open-order poll| BOT
+    MKT -->|price / AMA center| BOT
+    BOT -->|CREATE / UPDATE / CANCEL| CHAIN
+    BOT -->|grid snapshot| STORE
+    STORE -->|restore grid| BOT
+```
+
+Three inputs drive everything: **fill events** (reactive), **market/AMA price**
+(periodic), and **config/storage** (startup + recovery).
+
+---
+
+## 2. Startup / Bootstrap Sequence
+
+Runs once per bot launch. Goal: decrypt keys, load metadata, rebuild the master
+grid from either config or the persisted snapshot, then hand off to the runtime
+loops.
+
+```mermaid
+sequenceDiagram
+    participant OP as Operator
+    participant CL as dexbot_class.ts
+    participant CD as Credential Daemon
+    participant AM as Asset Metadata
+    participant OM as OrderManager
+    participant CH as Chain (open orders)
+    participant ST as Storage
+
+    OP->>CL: start(botKey)
+    CL->>CD: decrypt private key (AES, interactive/one-shot)
+    CD-->>CL: unlocked key
+    CL->>AM: load precision, fees, asset IDs
+    CL->>ST: load persisted grid snapshot (if present)
+    ST-->>CL: orders/botKey.json
+    CL->>OM: init Master Grid (config OR snapshot)
+    CL->>CH: SyncEngine 2-pass (grid<->chain match)
+    CH-->>OM: detect partials / stale / phantom
+    CL->>CL: start maintenance loop + market adapter (if AMA)
+    CL-->>OP: bot live, awaiting fills / ticks
+```
+
+Key references:
+- Credential unlock: `modules/credential_runtime.ts`, `CREDENTIAL_SECURITY.md`
+- Master Grid init + COW: `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern"
+- SyncEngine 2-pass: `modules/order/sync_engine.ts`, `docs/GRID_RECONCILE.md`
+
+---
+
+## 3. Lifecycle A — Fill-Driven (Reactive)
+
+This is the hot path. A limit order gets filled on-chain and the bot must rebuild
+grid symmetry, credit proceeds, and broadcast replacement orders — all inside a
+single Copy-on-Write rebalance cycle.
+
+```mermaid
+sequenceDiagram
+    participant CH as Chain (op-4 fill)
+    participant Q as _incomingFillQueue
+    participant FR as dexbot_fill_runtime
+    participant OM as OrderManager
+    participant WG as WorkingGrid (COW)
+    participant AC as Accounting (SSOT)
+    participant ST as Strategy (calculateTargetGrid)
+    participant CO as chain_orders (broadcast)
+    participant STORE as Storage
+
+    CH->>Q: enqueue fill(s)  (dexbot_fill_runtime.ts:325)
+    FR->>FR: drain queue -> _processFillsWithBatching
+    FR->>OM: processFilledOrders()  (manager.ts)
+    OM->>AC: processFillAccounting()  (single call, batch)
+    AC-->>WG: chainFree += combined proceeds
+    OM->>ST: calculateTargetGrid()  (rotations + boundary shift)
+    ST-->>WG: mutated WorkingGrid only
+    OM->>CO: updateOrdersOnChainBatch()  (atomic broadcast)
+    CO-->>CH: CREATE / CANCEL orders
+    CO-->>OM: confirm
+    OM->>WG: commit WorkingGrid -> Master Grid
+    OM->>STORE: persistGrid()  (snapshot after confirm)
+```
+
+Why it matters:
+- **Fixed-cap batching** (`MAX_FILL_BATCH_SIZE`, default 4) keeps bursts
+  deterministic — see `docs/architecture.md` §"Fill Processing Pipeline".
+- **Single rebalance cycle**: all fills in a batch share one broadcast, so proceeds
+  are immediately available for replacement sizing (no split-across-cycles delay).
+- **Replay-safe accounting**: processed-fill keys prevent double-credit on retries
+  (`modules/dexbot_fill_runtime.ts`, `PROCESSED_FILL_PERSISTENCE_MODES`).
+
+References: `modules/dexbot_fill_runtime.ts`, `modules/order/manager.ts`,
+`docs/FUND_MOVEMENT_AND_ACCOUNTING.md`.
+
+---
+
+## 4. Lifecycle B — Maintenance / AMA Signal-Driven (Periodic)
+
+Runs on a timer (and on AMA center updates). The grid is *not* rebuilt from fills
+here; instead funds are re-synced, the AMA center is promoted to the grid center,
+and the grid is recalculated against the latest market view.
+
+```mermaid
+sequenceDiagram
+    participant MA as Market Adapter (AMA)
+    participant CL as dexbot_class.ts
+    participant RT as maintenance_runtime
+    participant AC as Accounting
+    participant GD as Grid (recalculateGrid)
+    participant CO as chain_orders
+    participant STORE as Storage
+
+    MA->>CL: AMA center snapshot updated
+    CL->>CL: _performPeriodicGridChecks()  (dexbot_class.ts:1664)
+    CL->>RT: performPeriodicGridChecks()  (dexbot_maintenance_runtime.ts:1043)
+    RT->>RT: runGridMaintenance(bot,'periodic')  (dexbot_maintenance_runtime.ts:1845)
+    RT->>RT: executeMaintenanceLogic()  (dexbot_maintenance_runtime.ts:1452)
+    RT->>AC: recalculate funds from balances
+    RT->>GD: promote AMA center -> grid center
+    RT->>GD: recalculateGrid()  (grid.ts)
+    GD->>GD: rebuild levels via WorkingGrid (COW)
+    RT->>CO: broadcast adjustments (if any)
+    RT->>STORE: persistGrid()
+```
+
+Two triggers feed this loop:
+1. **Timer** — periodic fund sync + grid checks (`_performPeriodicGridChecks`).
+2. **AMA center change** — `market_adapter` recomputes the adaptive moving average;
+   when the center moves enough it promotes to the grid center and forces a recalc
+   (`modules/dexbot_maintenance_runtime.ts`, `market_adapter/market_adapter.ts`).
+
+The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` and
+*consumed* here at runtime — see `analysis/README.md` for the tooling that produces
+the parameters.
+
+> Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
+> runtime (`modules/credit_runtime.ts:3041`, reached via
+> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1769`). The grid maintenance
+> chain above is the one that matters for order/price upkeep.
+
+References: `modules/dexbot_class.ts:1664` (`_performPeriodicGridChecks`) →
+`modules/dexbot_maintenance_runtime.ts:1043` (`performPeriodicGridChecks`) →
+`:1845` (`runGridMaintenance`) → `:1452` (`executeMaintenanceLogic`),
+`docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
+
+---
+
+## 5. Cross-Cutting Invariants (read before touching anything)
+
+These are the rules that make the two lifecycles safe. They are *convention-
+enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
+
+| Invariant | Rule | Reference |
+|---|---|---|
+| **COW boundary** | All grid mutations happen on the WorkingGrid; Master Grid is frozen and only committed after chain confirmation. | `docs/developer_guide.md` §"Copy-on-Write (COW) Development Rules" |
+| **Fund SSOT** | `Accounting` owns every fund number. Nothing else computes available funds. | `docs/architecture.md` §"Fund Flow Architecture" |
+| **Replay-safe fills** | A fill is credited exactly once via processed-fill keys; retries are idempotent. | `modules/dexbot_fill_runtime.ts` |
+| **Single broadcast per cycle** | One `updateOrdersOnChainBatch` per rebalance — never scatter writes. | `docs/architecture.md` §"Fill Processing Pipeline" |
+| **Browser/Node split** | Heavy runtime is Node-only; never import it from a browser bundle. | `AGENTS.md` "Browser-Safe Surface", `docs/BROWSER_COMPAT_PLAN.md` |
+| **Lock ordering** | Fill drain and maintenance must not run a rebalance concurrently. | `docs/developer_guide.md` §"Startup Sequence & Lock Ordering" |
+
+---
+
+## 6. File Map (where to go next)
+
+| You want to understand… | Start here |
+|---|---|
+| How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
+| Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
+| Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
+| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1664` |
+| Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
+| Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
+| Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |
+
+---
+
+### TL;DR mental model
+
+> Blockchain fill (or AMA tick) → enqueue → drain in fixed-cap batches →
+> credit proceeds to Accounting (SSOT) → mutate **WorkingGrid** only →
+> calculate target grid → **single** atomic broadcast → commit WorkingGrid to
+> Master → persist snapshot. Master Grid is immutable; everything else is a
+> disposable copy until the chain confirms.

package/docs/README.md

@@ -109,6 +109,14 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Market Adapter Signal Pipeline**: AMA center, dynamic weights, regime detection, and collateral advisories
 - **Credit/Debt Runtime**: Native MPA and credit offer workflows with CR planning and grid reset coupling; `creditOnly` mode for runtime-only operation without grid trading
 
+### 🔁 [Lifecycle](LIFECYCLE.md)
+*The end-to-end walkthrough (start here for the big picture).*
+- **System Context**: What DEXBot2 talks to (chain, market data, storage, operator).
+- **Startup / Bootstrap**: Decrypt keys → load metadata → rebuild master grid → sync → runtime loops.
+- **Lifecycle A (Fill-Driven)**: Reactive path from an on-chain fill to a single atomic rebalance + broadcast.
+- **Lifecycle B (Maintenance / AMA-Driven)**: Periodic path from `_performPeriodicGridChecks` → `executeMaintenanceLogic`.
+- **Cross-Cutting Invariants**: COW boundary, fund SSOT, replay-safe fills, lock ordering.
+
 ### 📖 [Developer Guide](developer_guide.md)
 *Your daily companion for coding.*
 - **Quick Start**: How to get the development environment running.
@@ -136,7 +144,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 
 ### 🧭 [Evolution Report](EVOLUTION.md)
 *Project timeline and major architecture phases.*
-- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.4.18 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
+- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.4.19 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
 - **Focus**: Architecture evolution, release history, test growth, and documentation changes
 
 ### 🗒️ [Changelog](../CHANGELOG.md)

package/docs/developer_guide.md

@@ -11,8 +11,9 @@ Welcome to DEXBot2! This guide will help you understand the codebase, navigate k
 ### 1. **Start Here** (5 minutes)
 Read these files in order to get oriented:
 1. [README](../README.md) - User documentation and setup
-2. [architecture.md](architecture.md) - System architecture and module relationships
-3. [FUND_MOVEMENT_AND_ACCOUNTING.md](FUND_MOVEMENT_AND_ACCOUNTING.md) - Core algorithms and formulas
+2. [LIFECYCLE.md](LIFECYCLE.md) - **End-to-end walkthrough** (startup, fill-driven, and AMA-driven flows with diagrams) — read this first for the big picture
+3. [architecture.md](architecture.md) - System architecture and module relationships
+4. [FUND_MOVEMENT_AND_ACCOUNTING.md](FUND_MOVEMENT_AND_ACCOUNTING.md) - Core algorithms and formulas
 
 ### 2. **Core Concepts** (15 minutes)
 Understand these fundamental concepts before diving into code:
@@ -130,7 +131,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
 | **Asymmetric Offset** | Directional weight shift (buy-heavy or sell-heavy) driven by AMA/Kalman trend |
 | **Derivative Signal** | SMA/MACD/RSI-based entry bias and momentum gate for optional strategy filtering |
 | **Momentum Gate** | N-bar commitment tracking that confirms derivative signals before acting |
-| **Grid Price** | Price anchor for grid math; can be numeric, `"pool"`, `"book"`, or AMA keyword (`"ama"`, `"ama1"`–`"ama4"`) |
+| **GridPrice** | Price anchor for grid math; can be numeric, `"pool"`, `"book"`, or AMA keyword (`"ama"`, `"ama1"`–`"ama4"`) |
 
 ### Grid Concepts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot",
-  "version": "1.4.18",
+  "version": "1.4.19",
   "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
   "main": "dist/modules/dexbot_class.js",
   "exports": {
@@ -52,6 +52,7 @@
     "docs/WORKFLOW.md",
     "docs/architecture.md",
     "docs/developer_guide.md",
+    "docs/LIFECYCLE.md",
     "docs/docker.md",
     "market_adapter/README.md",
     "modules/README.md",