dexbot 1.4.21 → 1.4.22

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.21 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.22 stable release.
 
 ### Key Milestones
 - **Project Inception**: December 2, 2025
-- **Growth Phase**: 2,068 commits over ~9 active months
+- **Growth Phase**: 2,073 commits over ~9 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 252 automated test files
-- **Releases**: 98 release entries (v0.1.0 to v1.4.21)
+- **Stability**: Progression from manual testing to a suite of 238 automated test files
+- **Releases**: 99 release entries (v0.1.0 to v1.4.22)
 
 ---
 
@@ -45,7 +45,7 @@ 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 (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.
+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.
 
 ### Phase 6: Production Hardening & Iterative Refinement (June – July 2026)
 
@@ -53,21 +53,15 @@ Post-stable work focused on reliability: subscription watchdogs, broadcast deadl
 
 ### Phase 7: COW Concurrency & Uncertain-Broadcast Hardening (Late July 2026)
 
-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.
+After the CJS→ESM migration completed the module transition, the early v1.4.x releases corrected the COW concurrency model — centralized `withBlockchainRetry` with node failover, duplicate-CREATE guards, lock-hierarchy fixes, and fund-accounting race hardening — eliminating stale 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 (retries only after verifying chain inclusion), and truncate-ambiguous reads defer cancel/discard decisions instead of freeing slots or capital for possibly-live orders.
 
 ### Phase 8: Native ESM Runtime, Broadcast Serialization & Onboarding (August 2026)
 
-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.
+v1.4.12 completed the module transition to native ES modules (root + claw `"type": "module"`, Node >= 22 native WebSocket), removed the remaining legacy-compat shims, and pruned dead code. v1.4.13 followed with a single-flight guard that serializes overlapping COW broadcasts (preventing orphan fills), fill-lock bypass closures, `dexbot start` as the canonical launch command, and a BitShares onboarding tutorial.
 
 ### Phase 9: Post-ESM Cleanup, Consolidation & Hardening (August 2026)
 
-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. v1.4.20 hardened spread-correction boundary promotion with a MIN_SPREAD_ORDERS reserve floor and commit-time validation, gated persisted-boundary restore against self-legalizing overrun poison, aligned dynamic-weight clip parity between the live service and the research chart, centralized chart slider ranges, and moved all analysis outputs onto the central path resolver. v1.4.21 fixed silent-failure runtime defects surfaced by a modules-wide audit (NaN fund-invariant tolerance, always-flush fill store, double-decremented fill guard, config num() defaults), aligned the two boundary writers on a shared sell-rail ceiling enforced at commit and restore time, deduplicated claw shared logic while hardening error paths (secret redaction, EPIPE guards, spawn-error surfacing), corrected launcher supervisor/runtime lifecycle bugs, made the browser storage adapter persist deletions and flush debounced, extended editor green/red live color feedback to funds and price inputs, stopped docs/error messages from hardcoding repo-relative profile paths, and pruned dead code across analysis/market_adapter/claw/logging.
-
----
-
-## Development Statistics
-
-The project has accumulated 252 automated test files across 98 release entries. See the **Version History** below for a per-release commit breakdown.
+The post-ESM releases consolidated state, code, and tooling while hardening the grid engine. **State & packaging** (v1.4.14–v1.4.17): all user/runtime state centralized on a resolver-derived profiles dir (`~/.config/dexbot2/profiles`) safe from re-clones, read-only prefixes, and npm wipes; divergence surplus/hole pairs became in-place order rotations; npm auto-update shipped; duplicated EC-crypto/settings/asset-resolution code collapsed; dead exports purged; analysis tooling moved under strict TypeScript. **Grid hardening** (v1.4.19–v1.4.21): COW broadcasts capped at `MAX_OPS_PER_BROADCAST` (4) with chunked retry-on-uncertain; boundary promotion and persisted-boundary restore gated against gap-floor overrun poison behind a shared sell-rail ceiling enforced at commit and restore time; spread-collapse fixed via the shared `isSlotInRail` filter; silent-failure runtime defects from a modules-wide audit fixed (NaN fund-invariant tolerance, always-flush fill store, double-decremented fill guard). **Tooling & UX** (v1.4.20–v1.4.22): live/research clip parity with centralized chart sliders and analysis outputs on the central path resolver; claw logic deduplicated with hardened error paths; browser storage adapter persists deletions; editor green/red input feedback extended to funds and prices; compile-first runtime completed — tsx removed entirely, every entry point and the test suite running compiled dist under plain node through frozen-ESM-safe seams, plus exact AMA cold-start bootstrap sizing and research tools unified onto production slope/bounds math. Post-v1.4.22 work followed the same themes: bot-fitting backtests re-modeled on the production grid lifecycle (slot rotation with realized-only scoring), analysis tooling consolidated onto market_adapter sources with folder-audit bug fixes, a Kibana client hardened against proxy connection resets, and TradingView-style price-axis interaction added to the chart exporter.
 
 ---
 
@@ -86,37 +80,15 @@ The project has accumulated 252 automated test files across 98 release entries.
 
 ## Documentation & Testing
 
-Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+ JSDoc coverage, AGENTS.md). Testing matured from manual blockchain trials → Jest → lightweight Node.js assert across a 252-file suite covering unit, integration, simulation, and COW architectural guard tests.
+Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+ JSDoc coverage, AGENTS.md). Testing matured from manual blockchain trials → Jest → lightweight Node.js assert across the current suite covering unit, integration, simulation, and COW architectural guard tests.
 
 ---
 
-## Conclusion
-
-DEXBot2 has matured from a basic grid bot into a signal-intelligent, production-ready trading system.
-
----
-
-## Post-1.0.0: Completed
-
-- **Browser Compatibility**: Portable abstractions, pure-JS crypto, 140+ file refactor for browser-safe surface
-- **Credit/MPA Runtime**: Multi-asset collateral support, stale reborrow fixes, oversize deal splitting with per-operation caps
-- **I/O Centralization**: Full pipeline routed through storage adapter, shared atomic utilities across 20+ files
-- **Self-Healing**: Structural resync, subscription watchdog, broadcast deadlock recovery at both bot and daemon level
-- **Performance Analytics**: Kibana-driven FIFO/sequential trade PnL with 16 metrics
-- **AMA Refits**: Multi-round parameter optimization with per-market weights and distance scaling
-- **System Invariants**: Comprehensive documented invariants across all subsystems (COW, sync, grid, reconciliation)
-- **Bot Identity**: Unique name enforcement with migration support
-- **Credit-Only Mode**: Runtime-only operation for MPA/credit workflows without grid trading infrastructure
-- **Docker Support**: Container build, release images, and secure container startup guidance
-- **npm Package**: Published as npm package with versioned releases, lockfile sync, and dependency management
-- **Grid Order Engine Hardening**: COW pipeline, zero-amount order prevention, fill batching, dust detection, spread correction, and deadlock recovery
+## Post-1.0.0 Status
 
-## Post-1.0.0: Planned
+**Completed**: browser-safe core (140+ files, portable abstractions, pure-JS crypto); credit/MPA runtime (multi-asset collateral, oversize deal splitting); storage-adapter I/O centralization; self-healing (structural resync, subscription watchdog, bot/daemon broadcast-deadlock recovery); Kibana-driven trade PnL analytics; multi-round AMA refits; documented subsystem invariants; bot identity enforcement; credit-only mode; Docker support; npm package with lockfile sync; hardened grid order engine (COW pipeline, zero-amount prevention, fill batching, dust detection, spread correction).
 
-- **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 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.
+**Planned**: backtesting engine (historical candle replay via exchange abstraction); injectable interfaces at call boundaries; SQLite persistence + Zod validation at the blockchain boundary; Telegram bot (**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 (`TELEGRAM` block + `DEXBOT_TELEGRAM_TOKEN` env).
 
 ## Version History
 
@@ -133,11 +105,12 @@ Compact, era-level view; per-release commit detail lives in [CHANGELOG.md](../CH
 | v1.4.13 → v1.4.19 | 36 | Profile-state centralization, code consolidation, per-broadcast op cap |
 | v1.4.19 → v1.4.20 | 5 | Grid boundary promotion hardening, recovery poison gate, analysis output centralization |
 | v1.4.20 → v1.4.21 | 15 | Runtime audit fixes, claw dedup hardening, boundary ceiling alignment, editor color feedback |
+| v1.4.21 → v1.4.22 | 4 | tsx removal completion (dist-only runtime + tests), exact AMA bootstrap sizing, research-tool production parity |
 
 ---
 
 **Report Originally Generated**: February 19, 2026
-**Last Updated**: August 24, 2026 (v1.4.21)
-**Total Commits**: 2,068
-**Date Range**: December 2, 2025 – August 24, 2026
+**Last Updated**: August 26, 2026
+**Total Commits**: 2,084
+**Date Range**: December 2, 2025 – August 26, 2026
 **Repository**: DEXBot2 (BitShares DEX Trading Bot)

package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md

@@ -792,4 +792,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
 **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
 
 ---
-*Technical Reference for DEXBot2 v1.4.21 release*
+*Technical Reference for DEXBot2 v1.4.22 release*

package/docs/README.md

@@ -144,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.21 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.22 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/architecture.md

@@ -1239,15 +1239,15 @@ graph LR
 npm test
 
 # Specific logic area
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Signal tests
-tsx tests/test_market_adapter_signal_gates.ts
-tsx tests/test_dynamic_weight_override_wiring.ts
+node dist/tests/test_market_adapter_signal_gates.js
+node dist/tests/test_dynamic_weight_override_wiring.js
 
 # Credit/debt tests
-tsx tests/test_cr_planner.ts
-tsx tests/test_dexbot_credit_wiring.ts
+node dist/tests/test_cr_planner.js
+node dist/tests/test_dexbot_credit_wiring.js
 ```
 
 ### Test Quality Metrics

package/docs/developer_guide.md

@@ -1627,10 +1627,10 @@ The test suite validates the following fund-related behaviors:
 npm test
 
 # Specific logic area
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Specific integration test
-tsx tests/test_fills.ts
+node dist/tests/test_fills.js
 ```
 
 ### Understanding Test Structure
@@ -1797,13 +1797,13 @@ The test suite provides comprehensive coverage of fund calculations and rebalanc
 **Running Tests**:
 ```bash
 # Test strategy rebalancing
-tsx tests/test_strategy_logic.ts
+node dist/tests/test_strategy_logic.js
 
 # Test grid divergence
-tsx tests/test_grid_logic.ts
+node dist/tests/test_grid_logic.js
 
 # Test accounting precision
-tsx tests/test_accounting_logic.ts
+node dist/tests/test_accounting_logic.js
 
 # Run full suite
 npm test
@@ -1858,7 +1858,7 @@ A: Check if it's locked (`isOrderLocked()`), in exclusion list, or below dust th
 A: Follow the "How to Add New Features" section above.
 
 **Q: Where are the tests?**  
-A: All tests are in the `tests/` directory. Run `npm test` for the full suite, or `tsx tests/<file>.ts` for individual test files.
+A: All tests are in the `tests/` directory. Run `npm test` for the full suite, or `npm run build:tests && node dist/tests/<file>.js` for individual test files.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot",
-  "version": "1.4.21",
+  "version": "1.4.22",
   "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": {
@@ -89,25 +89,27 @@
     "ama:chart:lp-local": "npm run build && node dist/analysis/ama_fitting/generate_unified_comparison_chart.js",
     "analysis:derivatives": "npm run build && node dist/analysis/analyze_derivatives.js",
     "analysis:trade-pnl": "npm run build && node dist/analysis/trade_profitability.js",
-    "native:release-gates": "npm run build && node dist/scripts/native_release_gates.js",
-    "native:serial-snapshots": "tsx tests/test_native_serial_ops.ts",
-    "native:ecc-invariants": "tsx tests/test_native_ecc.ts",
+    "native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
+    "native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
+    "native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",
     "native:corpus": "npm run build && node dist/scripts/generate_mainnet_corpus_report.js",
     "test:credit-renewal": "npm run build && node dist/scripts/test-credit-renewal.js",
     "version:sync": "npm run build && node dist/scripts/sync-version.js",
     "version:check": "npm run build && node dist/scripts/sync-version.js --check",
     "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
-    "pretest": "tsc --noEmit",
-    "test": "node --import tsx scripts/run-tests.ts",
-    "test:live": "RUN_LIVE_BITSHARES_TESTS=1 node --import tsx scripts/run-tests.ts",
+    "test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
+    "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
     "clean": "node scripts/clean-dist.js",
-    "build": "npm run clean && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
+    "build": "tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
+    "build:clean": "npm run clean && npm run build",
+    "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs dist/tests/helpers/",
     "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json --noEmit",
     "build:watch": "tsc --watch",
-    "version": "npm run version:sync && npm run build",
-    "postversion": "npm run build",
-    "prepack": "npm run build",
-    "prepare": "npm run build",
+    "version": "npm run version:sync && npm run build:clean",
+    "postversion": "npm run build:clean",
+    "prepack": "npm run build:clean",
+    "prepare": "npm run build:clean",
     "postinstall": "node scripts/postinstall.js"
   },
   "repository": {
@@ -168,7 +170,14 @@
     "./dist/modules/order/utils/system.js": false,
     "./dist/market_adapter/market_adapter.js": false,
     "./dist/market_adapter/lp_chart_runner.js": false,
-    "./dist/market_adapter/ama_signal_runner.js": false
+    "./dist/market_adapter/ama_signal_runner.js": false,
+    "./dist/modules/runtime_settings.js": false,
+    "./dist/modules/bitshares-native/transport.js": false,
+    "./dist/modules/bitshares-native/signing_client.js": false,
+    "./dist/modules/bitshares-native/subscriptions.js": false,
+    "./dist/modules/bitshares-native/tx/builder.js": false,
+    "./dist/modules/bitshares-native/tx/tx_cache.js": false,
+    "./dist/market_adapter/utils/chain.js": false
   },
   "bugs": {
     "url": "https://github.com/froooze/DEXBot2/issues"
@@ -177,7 +186,6 @@
   "dependencies": {},
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "tsx": "^4.22.3",
     "typescript": "^6.0.3"
   }
 }

package/scripts/README.md

@@ -7,7 +7,7 @@ This guide provides a terminal-focused reference for the maintenance and diagnos
 ## 🛠️ CORE MAINTENANCE
 
 ### Update DEXBot2
-**File:** `update.ts`
+**File:** `update.ts` (shim: `update.js`)
 **Purpose:** Perform a safe, production-ready update.
 ```bash
 # Pull latest code, install deps, and restart PM2
@@ -174,6 +174,18 @@ LIVE_BOT_NAME=my-bot CALC_CYCLES=10 CALC_DELAY_MS=1000 node dist/scripts/runner.
 Useful for verifying config produces the expected grid, testing price derivation, and debugging fund allocation.
 Requires a live BitShares connection (asset metadata lookups and price derivation are on-chain).
 
+### Native Release Gates
+**File:** `native_release_gates.ts` (+ `generate_mainnet_corpus_report.ts`)
+**Purpose:** Prove the native serialization layer matches the chain byte-for-byte before release.
+```bash
+# Generate the mainnet corpus report (needs a live node + 50+ blocks)
+npm run native:corpus
+
+# Run serializer snapshots + ECC invariants and assert the corpus report
+npm run native:release-gates
+```
+The corpus report lands in `<profiles>/native_validation/mainnet_corpus_report.json`. The gates fail unless the report has `passed=true` and `transactionCount>=50`.
+
 ---
 
 ## 🔍 GIT & DEVELOPMENT WORKFLOW
@@ -209,7 +221,10 @@ Inside file viewer: `f` full file, `d` diff view, `q` back to search, `b` main m
 ## 💻 DEVELOPMENT UTILITIES
 
 ### Test Suite Setup
-Tests run with native Node `assert` — no test framework needed. See [tests/README.md](../tests/README.md) for details.
+Tests use native Node `assert` — no test framework needed. Sources compile to
+`dist/tests/` via `npm run build:tests`, and `npm test` runs them sequentially
+through `dist/scripts/run-tests.js` (with a per-test watchdog and diagnostics
+summary). See [tests/README.md](../tests/README.md) for details.
 
 ### Repository Statistics Analyzer
 **File:** `analyze-git.ts`
@@ -298,8 +313,8 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
 | `scripts/bots` | `dexbot bots` | `./scripts/bots` |
 | `scripts/keys` | `dexbot keys` | `./scripts/keys` |
 | `scripts/dexbot` | `dexbot` | `./scripts/dexbot <cmd>` |
-| `scripts/unlock` | `unlock.ts` / `dist/unlock.js` | `./scripts/unlock` |
-| `scripts/pm2` | `pm2.ts` / `dist/pm2.js` | `./scripts/pm2` |
+| `scripts/unlock` | `dist/unlock.js` | `./scripts/unlock` |
+| `scripts/pm2` | `dist/pm2.js` | `./scripts/pm2` |
 
 ---
 
@@ -308,12 +323,15 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
 ### Build & Test
 | Command | Purpose |
 |:---|:---|
-| `npm run build` | Clean + compile TypeScript |
+| `npm run build` | Compile TypeScript to `dist/` (plain node — no tsx) |
+| `npm run build:clean` | Remove stale `dist/` + tsbuildinfo caches, then build |
+| `npm run build:tests` | Compile `tests/` to `dist/tests/` (required by `npm test` and `native:*`) |
 | `npm run clean` | Remove compiled `dist/` output |
 | `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
+| `npm run typecheck:tests` | Type check the test suite (`tsc -p tsconfig.tests.json --noEmit`) |
 | `npm run build:watch` | TypeScript incremental build watcher |
-| `npm test` | Run full test suite (excludes live-chain tests) |
-| `npm run test:live` | Run full test suite including live-chain tests |
+| `npm test` | Build + compile tests + run full suite (excludes live-chain tests) |
+| `npm run test:live` | Build + compile tests + run full suite including live-chain tests |
 
 ### Runtime
 | Command | Purpose |
@@ -351,6 +369,14 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
 | `npm run test:credit-renewal` | Test credit offer renewal for a specific bot |
 | `npm run verify:browser-bundle` | Verify browser-safe surface bundles correctly |
 
+### Native Release Gates
+| Command | Purpose |
+|:---|:---|
+| `npm run native:corpus` | Build mainnet corpus report proving byte-for-byte native serialization parity |
+| `npm run native:serial-snapshots` | Run native serializer snapshot tests |
+| `npm run native:ecc-invariants` | Run native ECC key/sign/verify invariant tests |
+| `npm run native:release-gates` | Run serial + ECC gates and assert a valid mainnet corpus report |
+
 ---
 
 ## 📈 CHART GENERATION

package/scripts/clean-dist.js

@@ -4,6 +4,14 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const distDir = join(__dirname, '..', 'dist');
+const rootDir = join(__dirname, '..');
+const distDir = join(rootDir, 'dist');
+const tscCacheDir = join(rootDir, 'node_modules', '.cache');
 
-rmSync(distDir, { recursive: true, force: true });
+rmSync(distDir, { recursive: true, force: true });
+
+// Incremental tsbuildinfo files live outside dist/, so a stale cache would
+// make the next `tsc` believe everything is up to date and emit nothing.
+for (const info of ['tsc-prod.tsbuildinfo', 'tsc-tests.tsbuildinfo', 'tsc-claw.tsbuildinfo']) {
+    rmSync(join(tscCacheDir, info), { force: true });
+}

package/tests/README.md

@@ -1,15 +1,16 @@
 # DEXBot2 Test Suite
 
-Tests live as standalone `.ts` files in this directory. Each file is runnable directly via `tsx`. The suite uses Node's native `assert` — no test framework dependency.
+Tests live as standalone `.ts` files in this directory. They are compiled to `dist/tests/` by the build and run from there with plain `node` — no test framework, no TypeScript loader. The suite uses Node's native `assert`.
 
 ## Quick Start
 
 ```bash
-# Run all tests
+# Run all tests (builds production code + tests first)
 npm test
 
 # Run a single test file
-node --import tsx tests/<file>.ts
+npm run build:tests
+node dist/tests/<file>.js
 ```
 
 ## Directory Layout