dexbot 1.6.17 → 1.6.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/analysis/README.md +10 -9
  3. package/analysis/ama_fitting/README.md +2 -2
  4. package/analysis/bot_fitting/README.md +3 -3
  5. package/claw/package.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  8. package/dist/analysis/analyze_args.d.ts +2 -1
  9. package/dist/analysis/fills_source.d.ts +1 -8
  10. package/dist/analysis/fills_source.js +1 -1
  11. package/dist/analysis/grid_correction_check.d.ts +9 -6
  12. package/dist/analysis/grid_correction_check.js +56 -64
  13. package/dist/analysis/math_utils.d.ts +1 -1
  14. package/dist/analysis/trade_profitability.d.ts +1 -1
  15. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
  16. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  17. package/dist/market_adapter/cli_args.d.ts +6 -1
  18. package/dist/market_adapter/cli_args.js +16 -2
  19. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  20. package/dist/market_adapter/core/kibana_candles.js +3 -1
  21. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  22. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  23. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  24. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  25. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  26. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  27. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  28. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  29. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  30. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  31. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  32. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  33. package/dist/market_adapter/inputs/window_cache.js +14 -1
  34. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  35. package/dist/market_adapter/lp_chart_runner.js +3 -1
  36. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  37. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  38. package/dist/market_adapter/market_adapter.d.ts +10 -2
  39. package/dist/market_adapter/market_adapter.js +10 -11
  40. package/dist/market_adapter/utils/chain.d.ts +2 -3
  41. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  42. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  43. package/dist/market_adapter/utils/file_lock.js +1 -1
  44. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  45. package/dist/market_adapter/utils/native_history.js +3 -1
  46. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  47. package/dist/modules/bots_file_lock.d.ts +2 -2
  48. package/dist/modules/bots_file_lock.js +2 -2
  49. package/dist/modules/constants.js +6 -3
  50. package/dist/modules/dexbot_class.d.ts +8 -0
  51. package/dist/modules/dexbot_class.js +10 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
  53. package/dist/modules/dexbot_cow_runtime.js +461 -43
  54. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  55. package/dist/modules/dexbot_maintenance_runtime.js +56 -9
  56. package/dist/modules/dexbot_startup_runtime.js +7 -1
  57. package/dist/modules/graceful_shutdown.d.ts +2 -2
  58. package/dist/modules/graceful_shutdown.js +2 -2
  59. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  60. package/dist/modules/node_manager.d.ts +1 -1
  61. package/dist/modules/node_manager.js +1 -1
  62. package/dist/modules/order/accounting.js +2 -1
  63. package/dist/modules/order/export.d.ts +2 -2
  64. package/dist/modules/order/export.js +2 -2
  65. package/dist/modules/order/grid.d.ts +19 -14
  66. package/dist/modules/order/grid.js +262 -61
  67. package/dist/modules/order/grid_reconcile.js +5 -1
  68. package/dist/modules/order/grid_reconcile_internal.js +2 -1
  69. package/dist/modules/order/index.d.ts +9 -3
  70. package/dist/modules/order/manager.d.ts +10 -0
  71. package/dist/modules/order/manager.js +41 -11
  72. package/dist/modules/order/strategy.js +22 -2
  73. package/dist/modules/order/sync_engine.d.ts +12 -1
  74. package/dist/modules/order/sync_engine.js +135 -20
  75. package/dist/modules/order/utils/math.d.ts +8 -9
  76. package/dist/modules/order/utils/math.js +24 -13
  77. package/dist/modules/order/utils/order.d.ts +52 -11
  78. package/dist/modules/order/utils/order.js +137 -21
  79. package/dist/modules/order/utils/system.d.ts +73 -29
  80. package/dist/modules/order/utils/system.js +239 -48
  81. package/dist/modules/order/utils/validate.d.ts +1 -0
  82. package/dist/modules/order/utils/validate.js +4 -1
  83. package/dist/modules/storage/index.d.ts +3 -2
  84. package/dist/modules/storage/index.js +3 -2
  85. package/dist/modules/types.d.ts +9 -0
  86. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  87. package/docs/COW_INVARIANTS.md +20 -10
  88. package/docs/DEXBOT_COMPARISON.md +5 -5
  89. package/docs/EVOLUTION.md +9 -8
  90. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
  91. package/docs/GRID_PRICE_INVARIANT.md +24 -4
  92. package/docs/GRID_RECONCILE.md +5 -5
  93. package/docs/LIFECYCLE.md +11 -11
  94. package/docs/LOGGING.md +15 -2
  95. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +123 -36
  96. package/docs/README.md +1 -1
  97. package/docs/architecture.md +115 -13
  98. package/docs/developer_guide.md +12 -0
  99. package/market_adapter/README.md +9 -4
  100. package/modules/README.md +18 -14
  101. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,38 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.6.18] - 2026-11-01 - Partial-Fill Re-Anchor Recovery, Rail-Derived Boundary & Live Fill Prices, Edge-Fill Pivot Exclusion, Guard Arity Pinning, CLI `--flag=value`, Export-Surface Cleanup
6
+
7
+ ### 2026-11-01
8
+
9
+ - **Fix(spread)**: harden partial-fill re-anchor and recovery — a live market-pair bot stayed out of spread after a sell sweep even though the correction loop ran; four independent gaps combined. (1) A gap-evacuation plan built against an older boundary executed as a normal update once its live-geometry stamp went stale, moving valid in-rail buys off the bid edge and re-opening the spread: the build loop now skips a stale evacuation instead of falling through to the direction-only last-fill guard, and the final pre-broadcast gate drops a stamp whose live geometry went stale after op-building, including when the fill pivot itself did not change. (2) The fill anchor could not repair a window left behind a PARTIAL fill — the residual at the fill slot is inside the implied band by construction, so `validatePersistedBoundary` refused every re-anchor; the fill's own PARTIAL residual is now explicitly allow-listed (same side, same ladder level, exact anchor slot) while ACTIVE/foreign in-band orders still refuse, plus a post-clamp check that fails closed when the grid ceiling prevents the fill from leaving its window. (3) A re-anchor is absolute, but its plan carried only the derivation's consumed-crawl subset, so older owed deltas could be applied on top of the new boundary later: a successful re-anchor now snapshots and consumes the whole plan-time crawl ledger, and records recorded after plan build survive. (4) Create-only repair cannot close a fully allocated rail (free funds read 0 forever): when free funds cannot fund every promoted gap slot, a resting same-side ACTIVE order is rotated into the unfunded slot at its booked size (no new commitment, no growth/shrink; edge and PARTIAL sources excluded, crossing/last-fill/grid-price guards unchanged), rotation destinations come from the post-dedupe/post-duplicate-price candidate list so an already-occupied price cannot receive one, and rotation-only plans count as executable. Review hardening: startup and resume/reconcile load paths pass `tolerateTransientStranding` (the re-anchor deliberately leaves the fill's own PARTIAL residual in-band, so a strict load would rebuild the boundary away on the first restart); `reanchorBoundaryFromLastFill` requires `lastFillPivotSource === 'fill'`, because a one-sided book seed is a pricing hint for the guard, never an absolute geometry anchor (the bot-scoped last-market-fill row is the fallback); exactly-zero free funds now reach the rotation-only repair on the initial check, the TOCTOU re-plan and the fresh-master re-plan when the side decision carries the structured `no-free-funds` code (an unavailable market price stays a hard skip); and `plannedCount` includes rotation candidates so `checkSpreadCondition` reports the post-guard executed count rather than the plan count. Files: `order/grid_reconcile.ts`, `order/utils/system.ts`, `order/utils/math.ts`, `order/strategy.ts`, `order/grid.ts`, `dexbot_cow_runtime.ts`, `dexbot_startup_runtime.ts`; covered by `tests/test_stale_evac_build_skip.ts` and extended re-anchor, restore-validation, crawl-ledger, final-pivot-gate, spread-correction and pure-fund-driven tests.
10
+
11
+ - **Fix(order)**: keep the boundary on the placed rails and judge geometry by live fill prices — a sell sweep places counter BUYs on the promoted rail, but the refill hold kept the old committed boundary when the opposite-side refills were guard-skipped, so the next plan reclassified those counters as in-band and rotated SELLs onto their price, collapsing a 1.5% band to 0.3%; separately, a refused-commit adoption can leave a master slot keyed at an old generation price while its chain order trades elsewhere, and the fill pivot, GAP-EVAC and the crossing guard all trusted that stale price. `deriveRailBoundary` now clamps the committed boundary to the batch's resulting rails (`maxBuy <= boundary <= minSell-gap-1`, live master + kept op destinations) so counter orders win over empty refill holes, crossed or over-ceiling rails fail closed instead of self-legalizing, and `boundaryHeld` follows the value actually committed. Fill records now carry the chain execution price (history pays/receives, pass-1 chain price, pass-2 adoption, phantom cleanup) and the queued-fill pivot refresh prefers fill economics over the slot price without rewriting slot identity prices (GRID-PRICE-INVARIANT); `reanchorBoundaryFromLastFill` anchors on the fill batch's extremum for that side (max SELL/min BUY) rather than the mutable last-processed pivot, so a chunked sweep cannot leave its furthest counter in-band; new `resolveLiveOrderLadderPosition` maps the live chain price onto the ladder before falling back to the slot id for detection, drain-time validation and the eviction teeth, and a price mismatch whose live price is in-band queues a cancel-only `gapEvacuation` and drops any plain re-price for that chain order; the crossing candidate set uses the live chain price so an emission cannot print onto an opposite-side order adopted at a stale slot price. Risk: transient decisions follow the chain price while the grid slot identity stays frozen, and rail cross/ceiling failures keep the previous boundary and defer to GAP-EVAC. Covered by new `tests/test_rail_derived_boundary.ts` and `tests/test_live_geometry_provenance.ts` plus batch-extremum cases in `test_boundary_fill_reanchor`.
12
+
13
+ - **Fix(order)**: never arm the last-fill pivot from an edge-pinned fill — an edge order (grid floor/ceiling) is static fat-finger insurance, not market movement, yet `recordLastFilledPrices` armed the pivot on every fill and the pivot doubles as the absolute geometry anchor for `reanchorBoundaryFromLastFill`, so a wick that triggered a floor insurance BUY moved the window onto the grid edge (observed: boundary 29 -> 0 on a 60-slot ladder; mirrored at the ceiling). Eligibility now lives at the single pivot writer: fill ids are classified with `collectEdgePinnedFillIds` (`modules/order/utils/order.ts`), the same window/edge classifier the placement pickers use, so "edge" cannot mean two things; PARTIAL fills still arm the pivot (a partial at a far slot is a real trade and its residual is already allow-listed by the re-anchor). Behavioural impact: an edge fill no longer vetoes its own side of the book and can no longer drive an absolute boundary move — the guard and the anchor stay on the last WINDOW trade, so that side stays vetoed relative to it until a window fill or the 24h pivot TTL (the pre-fix alternative moved the whole window). The skip is logged (`[FILL-PIVOT] ... edge-skipped=K` plus a dedicated edge-only-batch line). Covered by new `tests/test_edge_fill_pivot.ts` and REANCHOR-18/19.
14
+
15
+ - **Fix(guard)**: pin the direction-only guard arity, re-arm the pivot explicitly, and stop self-legalizing the rail clamp — review follow-ups on the v1.6.12 -> v1.6.17 order-engine arc. `isLastFillGuardBlocked` still carried two dead parameters (`size`, `increment`) left over from the removed `pivot +/- increment/2` band, and keeping them made a band-rule reintroduction a compile-time non-event: the signature is now `(price, type, lastPrice, lastType)` at every call site (COW CREATE/rotation/fallback gates, planner predicate), and LFG-5 pins `.length === 4` plus "trailing arguments cannot resurrect a band". `initializeGrid` cleared the generation-bound pivot while its comment claimed the guard re-arms on the first real fill, and the read-time fallback silently kept an old-generation value, so after a rebuild in a market that had moved away one side read `last-fill-blocked` forever while the geometry clock rebuilt the generation every cooldown with no way to succeed: `rearmLastFillPivotFromMarketFill` now writes the re-arm explicitly through the one pivot writer (provenance `fill`, original fill timestamp, logged), and the geometry-bind escalation re-centers at most ONCE per pivot value (`_lastGeometryResyncPivotKey`) before reporting that only a fill or the 24h pivot TTL restores the side. `deriveRailBoundary` clamped onto EVERY live rail order, so one stray (refused-commit adoption, stranded hold, guard straggler) 18 slots off pulled the boundary 138 -> 115 and re-typed the whole window: rail membership is now the batch's own op destinations plus master orders on their own side of the planned boundary, strays are skipped and named in the log, rail indices come from the live chain price (`resolveLiveOrderLadderPosition`) instead of a possibly stale slot id, and the result passes the shared `validatePersistedBoundary` gate (cancel/rotation sources allow-listed, skipped on a sparse ladder whose array-derived ceiling would reject everything). Crossing CREATEs are observed rather than vetoed — a hard veto would re-open the counter-order deadlock after a gap — via `warnCrossingCreate`, logged once per batch from already-cached evidence (no chain call). Same pass: one pivot resolver (two verbatim copies merged), one boundary validator shared by the re-anchor and the rail clamp, and the batch-extremum logic extracted as the pure `resolveFillAnchorIndex`. Files: `order/utils/system.ts`, `order/utils/order.ts`, `order/grid.ts`, `order/grid_reconcile*.ts`, `dexbot_cow_runtime.ts`; covered by new `tests/test_last_fill_pivot_rearm.ts` plus RAIL-10..14, SLF-11/12 and arity updates in LFG-5, FG-9, GPI-WIRE-003 and SGP-1/4.
16
+
17
+ - **Fix(spread)**: count last-fill-excluded candidates per slot — the planner's "Excluded N candidate(s)" line counted pool visits, and a slot can legitimately appear in more than one candidate pool (an empty in-rail slot normalized to SPREAD satisfies both the SPREAD pool and the orphan pool, which the merge already dedupes), so every vetoed slot was reported twice and the over-count was worst exactly when the pools overlapped most. That number decides the `last-fill-blocked` stall and is the only signal for how much of a side the pivot blocked, so inflating it overstated the geometry bind. The counter now de-duplicates by slot id (an unidentified candidate still counts, since it cannot be matched); the plan itself is unchanged, the filter being a predicate and not a side effect. SLF-13 pins the overlap (`Excluded 2`, not `4`) and was verified failing on the pre-fix tree.
18
+
19
+ - **Refactor(analysis)**: judge fills by the direction-only guard — `analysis/grid_correction_check.ts` still implemented the old `pivot +/- increment/2` band while claiming to mirror `isLastFillGuardBlocked` 1:1, so it reported exactly the tightening placements the live guard allows. The predicate now matches the runtime rule (BUY < last fill, SELL > last fill, equal price blocked) with the same four arguments; the band fields are gone from the report header, violation table and JSON payload (per-row `halfInc` stays 0 so existing consumers keep their shape); `--increment` is documented as informational (default and configured value still reported); and the guard section of `analysis/README.md` documents the offline limits — edge-pinned fills cannot be reconstructed from the fill stream, so wick/insurance fills can appear as violations, and the spread-correction bypass is invisible per fill. Offline report only: no live behaviour change.
20
+
21
+ - **Feat(analysis)**: step SMA/VWMA period controls by 10 — the chart toolbar's period steppers moved one unit per click, making broad sweeps (e.g. 500 -> 600) tedious and hold-to-repeat slow. SMA and VWMA up/down buttons now step by 10 per click and per hold tick, the SMA arrow floor rises from 1 to 10 to match the 10-unit step, and the VWMA lower clamp/arrow floor drops from 24 to 10 so the 10-step sequence is reachable across the whole allowed range (manual entry unaffected apart from the lower clamp). AMA controls and chart rendering are unchanged.
22
+
23
+ - **Refactor(market_adapter)**: remove dead paths and narrow the test surface — the adapter still carried a native-history fallback that could never run (adapter_client exposes only db/history proxies, so `history.getMarketHistory` is always present and `BitShares.tradeHistory` never existed on the client shape), the CEX seeder's `typeof`/`||` guards re-checked helpers destructured from a `require` that would already have thrown, and seven types were exported although only used inside their defining modules. 41 test-only named exports became one explicit `__test` object per module: production callers keep the same public surface, tests still reach the internal seams, and future dead-export scans no longer need to special-case white-box helpers. The LP exporter CLI drift is fixed by routing it through the shared `walkCliArgs` walker (with `--help`, unknown flags rejected instead of silently ignored, and `--chunkMonths`, `--apiKey`, `--out` documented), the README no longer claims the adapter only handles 1h candles, and the file-lock default payload no longer writes an owner UUID into `pid` — it records `runtime.pid` while keeping the unique ownerId for release checks.
24
+
25
+ - **Fix(market_adapter)**: accept `--flag=value` and validate the LP export CLI — `walkCliArgs` rejected any value token starting with `--`, so a path or API key beginning with `--` could not be passed at all, and the LP exporter had drifted onto bare `parseInt`, silently storing `NaN` for `--chunkMonths abc`. The walker now understands `--flag=value` (the escape hatch for flag-shaped values), refuses an inline value on a flag/help that takes none, and reports an unknown token exactly as typed; the exporter routes its options through validating helpers (`--chunkMonths` an integer >= 1, `--precA`/`--precB` integers >= 0 with an empty inline value no longer read as 0, `--apiKey`/`--out` non-empty) and `--help` documents the `=` form. Behavioral impact for `fetch_lp_data`: unknown flags still fail, invalid numbers now fail naming the flag instead of producing `NaN`, and a flag-shaped value must use `--flag=value`. Covered by new `tests/test_cli_args_walker.ts` and extended `tests/test_fetch_lp_data_logic.ts`.
26
+
27
+ - **Fix(build)**: export the credential response type and pin the backtest slope test — the claw credential wrapper infers `Promise<CredentialDaemonResponse>` from the imported client, but declaration emit cannot name a module-private interface there, so `npm run build --prefix claw` failed with TS4058; the type is exported again (compile-time surface only, with a comment explaining why it must stay exported). `test_backtest_bot_fitting_logic` still hardcoded the old 0.09 AMA max-slope default and failed once the canonical constant moved to 0.1, so the full/half/sub-strength inputs are derived from `MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_MAX_SLOPE_PCT` and track the production knob instead of drifting on the next tune. Both restore a green `npm test` (331/331 files, 14 live tests skipped) and `build --prefix claw` on this branch.
28
+
29
+ - **Test(guards)**: enforce the `__test` seam and run the analysis typecheck in `npm test` — the `__test` convention replaced 41 named exports with one seam object per module, but nothing prevented production code from importing that object, so a future caller could quietly build on a test-only surface; and the standalone analysis tsconfig (stricter: `noUnusedLocals`/`noUnusedParameters`) was reachable only through `npm run typecheck:analysis`, so it could rot unnoticed. `tests/test_public_surface_guard.ts` scans every production `.ts` file (modules, market_adapter, analysis, scripts, claw and the root entrypoints) and fails if `__test` is referenced without defining a seam or if a seam is touched more than once inside its defining module, and `npm test` / `npm run test:live` now run `typecheck:analysis` before the suite.
30
+
31
+ - **Refactor(analysis)**: drop dead exports and correct stale docs — the analysis surface is aligned with its real callers and output locations: the README states that shared chart/bot-key helpers are imported by the production market adapter and that `--source market_adapter` prefers the bot candle cache before the centers file; the AMA optimizer/backtest docs point at `analysis/results/` (`PATHS.ANALYSIS.RESULTS_DIR`), not `analysis/ama_fitting/`; zero-consumer exports are narrowed back to internal types; the inert `analysis/.npmignore` is removed (the package `files` allowlist already ships only the analysis READMEs plus uplot); and `analysis/tsconfig.json` is wired into `typecheck:analysis` so the standalone config is actually used. **Removed CLI surface**: the deprecated `--tolerance` alias of `grid_correction_check` is gone — its band no longer exists and `--increment` already carries the report label.
32
+
33
+ - **Refactor(modules)**: remove dead exports, params and the slot-helper shim — an audit of `modules/` found no unreachable files or unused locals, but a layer of vestigial surface: ten symbols are de-exported (the remaining over-export candidates stay exported because declaration emit needs them named across modules, TS4023/TS4058), the `parseSlotIndex` forwarding wrapper and re-export in `order/utils/order.ts` are dropped so all callers import the canonical helper from `order/utils/slot.ts` and the two copies cannot drift again, the `calculateOrderCreationFees` JSDoc is corrected, and `lazy_shim.ts` / `launcher/runtime_mode.ts` are documented in `modules/README.md`. **Breaking for out-of-tree `dist/` consumers**: `allocateFundsByWeights`, `calculateOrderSizes` and `calculateRotationOrderSizes` lose their unused trailing `minSize`/`minSellSize`/`minBuySize` parameters (every in-repo caller passed 0, so behaviour is unchanged); in-tree call sites and tests are updated positionally.
34
+
35
+ - **Docs**: symbol-name citations and export-surface rules replace drifted line numbers, and the module map is corrected — 36 of 64 `file.ts:LINE` references in `docs/` no longer pointed at the code they described, so every one is now a symbol name plus filename, which also removed three outright-wrong claims (a deleted `computeOutOfToleranceDriftTag` listed as a live `priceForSlot` consumer, a non-existent `ANCHOR.PROJECTION_ENABLED` asserted dead three times, and a misnamed maintenance entry point); two documented symbols were corrected and deliberately removed ones keep only the filename. `modules/README.md` moves `runtime_mode.ts` into the `launcher/` block (it was the only tree entry resolving to nothing), fixes descriptions that sent readers to the wrong subsystem (`chain_keys` as the master-password vault plus signing-key retrieval, `credential_runtime` as socket/path helpers, `daemon_node_health` as a failure ledger with no health checking, `socket_json_client` as newline-delimited JSON rather than JSON-RPC, `storage/browser_adapter` as an IndexedDB-persisted Map), unwraps two markdown links that sat inside a fenced tree, names the real crypto split and fill wiring in the principles, and re-aligns three one-column-off rows; module-header usage snippets that used CommonJS `require()` in a `"type": "module"` package now use static imports with `.js` specifiers. `developer_guide` gains an "Export Surface & Test Seams" section (declaration emit is a real consumer, shipped `dist/` is a public API, test-only helpers live in one `__test` object enforced by `tests/test_public_surface_guard.ts`), and `ORDER_ENGINE_POST_1.0_RETROSPECTIVE` is reconciled with the code: §0/§6/§7 described the offline checker with old band semantics, §9.1/§9.7/§9.9 carried pre-fix statements, the header/TOC/snapshot/footer said v1.6.14, the §9.5 ledger gained rows for the whole 1.6.15/1.6.17 arc and the post-1.6.17 work, §9.6 gained four invariants (only a window trade may become the pivot, one boundary validator, a rail clamp cites only its own evidence, the pivot has a lifetime), and R2-R5 record the "one rule, several implementations" meta-pattern plus lessons 8-11. `COW_INVARIANTS`, `architecture`, `GRID_PRICE_INVARIANT` and `LOGGING` document the new rail-clamp membership, re-anchor eligibility, explicit re-arm, once-per-pivot re-center, `[COW-CROSS-GUARD]` line, capped re-center warning and the per-slot "Excluded N" count. Docs/comments only; `npm test` 331/331.
36
+
5
37
  ## [1.6.17] - 2026-10-30 - Last-Fill Direction Guard, Spread-Correction Stall Naming & Chain-Truth Funding, Owed-Crawl Consumption, Restart Auth-Before-Stop, Pool-Priced LP Collateral, Supply Distribution Analyzers
6
38
 
7
39
  ### 2026-10-30
@@ -1,6 +1,6 @@
1
1
  # Analysis
2
2
 
3
- Tools that inspect DEXBot trading behavior and the market data it operates on. Output is interactive HTML charts written to `charts/` (regenerated on each run, not committed); none of this runs in production.
3
+ Tools that inspect DEXBot trading behavior and the market data it operates on. Output is mostly interactive HTML charts written to `charts/` (regenerated on each run, not committed) and JSON results under `results/`; the trade analyzers can also export CSV/JSON to a caller-supplied path. The runners are research-only, but their shared chart and bot-key helpers are imported by the production market adapter.
4
4
 
5
5
  ## Contents
6
6
 
@@ -22,7 +22,7 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
22
22
  |------|----------------|------------------|
23
23
  | [`trade_profitability.ts`](#trade-profitability-analyzer-trade_profitabilityts) | "Is my bot making money?" — PnL, R-multiples, drawdown | `npm run analysis:trade-pnl -- <account-id>` |
24
24
  | [`dexbot pnl`](#pnl-html-report-dexbot-pnl) | "Give me a readable PnL report" — self-contained HTML with a lot table | `dexbot pnl <bot\|account> --month 3` |
25
- | [`grid_correction_check.ts`](#last-fill-guard-check-grid_correction_checkts) | "Are fills respecting the pivot ± half-increment guard?" | `npm run analysis:grid-check -- --bot-key <bot-key>` |
25
+ | [`grid_correction_check.ts`](#last-fill-guard-check-grid_correction_checkts) | "Are fills respecting the direction-only last-fill guard?" | `npm run analysis:grid-check -- --bot-key <bot-key>` |
26
26
  | [`analyze_risk_profile.ts`](#risk-profile-analyzer-analyze_risk_profilets) | "How wide should my Safe Range clamps be?" | `node dist/analysis/analyze_risk_profile.js --bot-key <bot-key>` |
27
27
  | [`analyze_trade_heatmap.ts`](#trade-heatmap-analyze_trade_heatmapts) | "Where did trade volume cluster vs the AMA?" | `node dist/analysis/analyze_trade_heatmap.js --bot-key <bot-key>` |
28
28
  | [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `dexbot tv <bot-key>` |
@@ -76,14 +76,14 @@ node dist/analysis/analyze_dynamic_weight.js --bot-key <bot-key>
76
76
  npm run analysis:trade-pnl -- 1.2.123456 --hours 168
77
77
  ```
78
78
 
79
- > The market adapter source reads from `market_adapter/state/market_adapter_centers.json` — run the bot first to populate state.
79
+ > The market adapter source prefers the bot's cached candle file and falls back to `market_adapter/state/market_adapter_centers.json` — run the bot first to populate state.
80
80
  > Prefer the `npm run analysis:*` shortcuts; they wrap the compiled runners with the same flags (see [npm Script Shortcuts](#npm-script-shortcuts) for the full mapping).
81
81
 
82
82
  ## Data Prerequisites
83
83
 
84
84
  Most runners expect candle data. Two paths to get it:
85
85
 
86
- **Market adapter source** (default for most runners) — reads from `market_adapter/state/market_adapter_centers.json`. No setup needed; just run the bot first to populate state.
86
+ **Market adapter source** (default for most runners) — resolves the bot's cached candle file first, then falls back to `market_adapter/state/market_adapter_centers.json`. No setup needed; just run the bot first to populate state.
87
87
 
88
88
  **LP candle files** — for deeper analysis with full OHLC data:
89
89
 
@@ -258,9 +258,11 @@ All amounts use the shared 4-significant-figure formatter (compact `K`/`M`, sign
258
258
 
259
259
  ### LAST-FILL-GUARD Check (`grid_correction_check.ts`)
260
260
 
261
- Validates LAST-FILL-GUARD discipline from the same Kibana fill pipeline as `trade_profitability.ts`. For a previous fill at price `x` and grid increment `i`, the next order must satisfy `BUY < x × (1 − i/2/100)` and `SELL > x × (1 + i/2/100)`, regardless of the previous fill's side. A violation is a buy or sell fill inside the prohibited half-increment band around its pivot.
261
+ Validates LAST-FILL-GUARD discipline from the same Kibana fill pipeline as `trade_profitability.ts`. The rule is **direction only** (v1.6.16+): with the previous fill at price `p`, the next order must satisfy `BUY < p` and `SELL > p` (equal price is blocked — a re-place at the just-filled level). There is no increment band: the older `pivot ± i/2` rule blocked a BUY below a SELL fill and a SELL one tick above our cost, i.e. it flagged the tightening placements the engine legitimately makes. A violation is a buy fill at/above its pivot or a sell fill at/below it.
262
262
 
263
- **Pipeline:** Kibana `fill_order` query (paginated `search_after`) → on-chain asset precision resolution → buy/sell classification → chronological sort → per-order/price-epoch aggregation (partial fills at one price collapsed to weighted-average; repriced order lifetimes kept separate) → consecutive pivot-band comparison → violation report with daily histogram.
263
+ **Offline limits:** the tool reconstructs pivots from consecutive fills, so it cannot see the runtime's edge-pinned-fill exclusion (no slot identity per fill) nor the spread-correction bypass — expect rare false positives on wick/insurance fills.
264
+
265
+ **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 direction comparison → violation report with daily histogram.
264
266
 
265
267
  ```bash
266
268
  # Per-order aggregated check (default), last 7 days
@@ -272,7 +274,7 @@ npm run analysis:grid-check -- --bot-key <bot-key> --hours 720 --json out.json -
272
274
  # Raw fill granularity instead of per-order aggregation
273
275
  npm run analysis:grid-check -- --bot-key <bot-key> --per-fill --hours 168
274
276
 
275
- # Override the bot's configured grid increment
277
+ # Override the bot's configured grid increment (informational: the guard has no band)
276
278
  npm run analysis:grid-check -- --bot-key <bot-key> --hours 168 --increment 0.5
277
279
  ```
278
280
 
@@ -287,10 +289,9 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
287
289
  | `--start <iso>` / `--end <iso>` | — | Absolute time window |
288
290
  | `--account <id>` | bot `preferredAccount` | Override account ID or name |
289
291
  | `--refresh-account` | off | Force re-resolution of `preferredAccount` and update the stored `accountId` when it changed |
290
- | `--increment <pct>` | bot config / `0.5` | Grid increment used to derive the half-increment guard band |
292
+ | `--increment <pct>` | bot config / `0.5` | Grid increment (informational only — the guard is direction-only and uses no band) |
291
293
  | `--per-fill` | off | Check at fill granularity instead of per-order aggregated |
292
294
  | `--include-cross-pair` | off | Also check consecutive fills across different pairs |
293
- | `--tolerance <pct>` | — | Deprecated compatibility alias for `--increment`; its value is doubled and a warning is emitted |
294
295
  | `--json <file>` / `--csv <file>` | — | Export violations |
295
296
  | `--verbose` | off | Print the fetched trade sequence before checking |
296
297
  | `--list-bots` | — | List available bot keys and exit |
@@ -10,7 +10,7 @@ parameters into `profiles/market_profiles.json` for the market adapter.
10
10
 
11
11
  ```
12
12
  1. fetch_lp_candles.ts → market_adapter/data/lp/<pairFolder>/lp_pool_<poolShort>_<interval>.json
13
- 2. optimizer_high_resolution.ts → optimization_results_*.json
13
+ 2. optimizer_high_resolution.ts → analysis/results/optimization_results_*.json
14
14
  → profiles/market_profiles.json (only with --write-profiles)
15
15
  3. scripts/generate_lp_chart.ts → market chart + comparison chart (visual review)
16
16
  - LP chart: `npm run lp:chart -- --data <lp-export.json>`
@@ -156,7 +156,7 @@ Source: pool 133 `IOB.XRP/BTS`, 1h candles, 2023-04-12 00:00 UTC through
156
156
  2026-04-11 23:00 UTC (the working-tree dataset `analysis/ama_fitting/data/lp_pool_133_iob.xrp_bts_1h.json`, regenerated by a local `fetch_lp_candles.ts` run).
157
157
 
158
158
  **Outputs:**
159
- - `analysis/ama_fitting/optimization_results_<datafile>_w<λ1>_<λ2>_<λ3>_<λ4>.json` — full results (e.g. `_w0_0031_0_0025_0_00185_0_0013`)
159
+ - `analysis/results/optimization_results_<datafile>_w<λ1>_<λ2>_<λ3>_<λ4>.json` — full results (e.g. `_w0_0031_0_0025_0_00185_0_0013`)
160
160
  - `analysis/charts/optimization_chart_<datafile>_w<λ1>_<λ2>_<λ3>_<λ4>.html` — interactive AMA overlay chart (auto-generated)
161
161
  - `profiles/market_profiles.json` — updated with new AMA parameters per pair only when `--write-profiles` is used
162
162
 
@@ -1,6 +1,6 @@
1
1
  ## Bot Fitting Backtest
2
2
 
3
- This folder contains parameter sweep backtests that simulate grid fills for the four AMA winners from `analysis/ama_fitting`.
3
+ This folder contains parameter sweep backtests that simulate grid fills for the four AMA winners produced by the optimizer in `analysis/ama_fitting/` (results land in `analysis/results/`).
4
4
 
5
5
  ### What it optimizes
6
6
 
@@ -74,7 +74,7 @@ microstructure, and no consolidation/dust-cancel/COW/collision mechanics.
74
74
  Both scripts require:
75
75
 
76
76
  - **LP candles JSON** (recommended 1h), from `market_adapter/data/lp/` — pass via `--data`
77
- - **AMA optimization winners JSON**, from `analysis/ama_fitting/` — for `backtest_ama_sweep.ts`, pass via `--results`
77
+ - **AMA optimization winners JSON**, from `analysis/results/` — for `backtest_ama_sweep.ts`, pass via `--results`
78
78
 
79
79
  ### Run
80
80
 
@@ -99,7 +99,7 @@ node dist/analysis/bot_fitting/backtest_lookback_drawdown.js \
99
99
  > builds on it and reports the paired per-lookback deltas.
100
100
 
101
101
  > `backtest_bot_fitting.ts` auto-derives `--results` from the `--data` filename
102
- > (`analysis/ama_fitting/optimization_results_<base>_w<λ1>_<λ2>_<λ3>_<λ4>.json`,
102
+ > (`analysis/results/optimization_results_<base>_w<λ1>_<λ2>_<λ3>_<λ4>.json`,
103
103
  > newest `_w*` file matching the base name; falls back to the legacy
104
104
  > `optimization_results_<base>.json`) when omitted.
105
105
  > `backtest_ama_sweep.ts` requires `--results` explicitly.
package/claw/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot2-claw",
3
- "version": "1.6.17",
3
+ "version": "1.6.18",
4
4
  "private": true,
5
5
  "description": "Claw bridge and runtime integration layer for BitShares and DEXBot2.",
6
6
  "type": "module",
@@ -2,7 +2,7 @@
2
2
  "id": "bitshares-claw",
3
3
  "name": "BitShares Claw",
4
4
  "description": "Native BitShares and DEXBot2 tools from the DEXBot2 claw integration",
5
- "version": "1.6.17",
5
+ "version": "1.6.18",
6
6
  "skills": [
7
7
  "skills"
8
8
  ],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "bitshares-claw-openclaw-plugin",
3
3
  "private": true,
4
- "version": "1.6.17",
4
+ "version": "1.6.18",
5
5
  "type": "module",
6
6
  "main": "index.js"
7
7
  }
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import type { SourceConfig } from './resolve_source.js';
10
10
  /** Fields every analysis CLI config shares. */
11
- export interface AnalysisBaseConfig {
11
+ interface AnalysisBaseConfig {
12
12
  source: {
13
13
  type: string;
14
14
  config: SourceConfig;
@@ -40,4 +40,5 @@ export declare function printHelpHeader(title: string, usagePath: string): void;
40
40
  * `width` is per-tool so adopting this helper keeps the original column.
41
41
  */
42
42
  export declare function helpRow(flag: string, description: string, width: number): string;
43
+ export {};
43
44
  //# sourceMappingURL=analyze_args.d.ts.map
@@ -17,13 +17,6 @@ interface FillRecord {
17
17
  }
18
18
  declare function assetSymbol(id: string): string;
19
19
  declare function assetPrec(id: string): number | undefined;
20
- declare function toReal(amount: number, assetId: string): number;
21
- /**
22
- * A fill needs strictly positive, finite amounts on both legs. A zero base
23
- * amount would produce an infinite price (quoteAmount / 0) that poisons
24
- * downstream inventory lots and PnL aggregates.
25
- */
26
- declare function isValidFillAmounts(baseAmount: number, quoteAmount: number): boolean;
27
20
  /** Match a user-supplied pair leg against a chain asset id or its symbol. */
28
21
  declare function matchesAssetRef(ref: string, assetId: string): boolean;
29
22
  interface ClassifiedFill {
@@ -55,5 +48,5 @@ declare function classifyFill(f: FillRecord): ClassifiedFill | null;
55
48
  declare function resolveAssetPrecisions(fills: FillRecord[]): Promise<void>;
56
49
  /** Fetch every fill_order for an account in [gte, lte], paginated via search_after. */
57
50
  declare function fetchAllFills(config: Record<string, unknown>, accountId: string, gte: string, lte: string): Promise<FillRecord[]>;
58
- export { BTS_ID, assetSymbol, assetPrec, toReal, isValidFillAmounts, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, FillRecord, ClassifiedFill, };
51
+ export { BTS_ID, assetSymbol, assetPrec, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, FillRecord, };
59
52
  //# sourceMappingURL=fills_source.d.ts.map
@@ -255,5 +255,5 @@ async function fetchAllFills(config, accountId, gte, lte) {
255
255
  }
256
256
  return fills;
257
257
  }
258
- export { BTS_ID, assetSymbol, assetPrec, toReal, isValidFillAmounts, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, };
258
+ export { BTS_ID, assetSymbol, assetPrec, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, };
259
259
  //# sourceMappingURL=fills_source.js.map
@@ -22,22 +22,25 @@ interface Violation {
22
22
  priceDelta: number;
23
23
  priceDeltaPct: number;
24
24
  pivot: number;
25
+ /** Direction-only rule has no band; kept at 0 so the JSON/CSV shape is stable. */
25
26
  halfInc: number;
27
+ /** The pivot itself (BUY must be below / SELL above it). */
26
28
  threshold: number;
27
29
  }
28
30
  /**
29
- * LAST-FILL-GUARD helper — pivot ± halfIncrement (replaces price-tolerance).
30
- * last fill @x with increment i: BUY < x*(1 - i/2/100), SELL > x*(1 + i/2/100)
31
- * e.g. x=1000, i=0.5% => BUY < 997.5, SELL > 1002.5
32
- * Cold (pivot null or lastType null) => disabled.
31
+ * LAST-FILL-GUARD helper — DIRECTION ONLY relative to the last fill price.
32
+ * BUY blocked if price >= pivot
33
+ * SELL blocked if price <= pivot
34
+ * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000
35
+ * Cold (pivot null or lastType null) => disabled. Equal price stays blocked
36
+ * (a re-place at the just-filled level).
33
37
  * @param {number} price - Target order price
34
38
  * @param {string} type - buy/sell
35
39
  * @param {number|null} lastPrice - Most recent fill price
36
40
  * @param {string|null} lastType - Most recent fill side (buy/sell)
37
- * @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If not finite/<=0 falls back to DEFAULT_CONFIG.
38
41
  * @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
39
42
  */
40
- declare function isLastFillGuardBlocked(price: unknown, type: unknown, lastPrice: unknown, lastType: unknown, incrementPercent: unknown): {
43
+ declare function isLastFillGuardBlocked(price: unknown, type: unknown, lastPrice: unknown, lastType: unknown): {
41
44
  blocked: boolean;
42
45
  pivot: number | null;
43
46
  halfInc?: number;
@@ -3,21 +3,31 @@
3
3
  /**
4
4
  * LAST-FILL-GUARD CHECK
5
5
  *
6
- * Validates LAST-FILL-GUARD discipline: pivot ± halfIncrement
7
- * Last fill @x with increment i (half=i/2) gates BOTH sides regardless of
8
- * last side — BUY must be < x*(1-half/100), SELL > x*(1+half/100).
9
- * e.g. x=1000, i=0.5% => BUY < 997.5 / SELL > 1002.5.
6
+ * Validates LAST-FILL-GUARD discipline — DIRECTION ONLY, relative to the last
7
+ * fill price (v1.6.16+, retrospective §9.7):
8
+ * BUY blocked if price >= pivot
9
+ * SELL blocked if price <= pivot
10
+ * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000.
10
11
  * Cold start (no previous fill) is disabled.
11
- * Intentional offline gaps (documented, acceptable):
12
+ *
13
+ * The older rule judged against `pivot ± increment/2` and ignored the fill
14
+ * side, which blocked a BUY below a SELL fill and a SELL one tick above our
15
+ * cost — i.e. it reported the tightening placements the current engine
16
+ * legitimately makes as violations. Do not reintroduce an increment term here.
17
+ *
18
+ * Intentional offline gaps (documented, acceptable):
12
19
  * - Runtime pivots on _lastFilledPrice/_lastFilledType at decision time; tool
13
20
  * checks consecutive fill pairs. For batch-placed orders (multiple orders
14
21
  * guarded against the same pivot in one COW batch) this diverges — inherent
15
22
  * offline approximation.
16
23
  * - Spread-correction bypass (cowResult.origin === 'spread-correction') is
17
24
  * not simulated — every consecutive pair is checked.
25
+ * - EDGE-pinned insurance fills no longer arm the runtime pivot
26
+ * (recordLastFilledPrices skips them); this reconstruction has no slot
27
+ * identity for a fill, so it cannot classify edge fills and will still
28
+ * judge the pair after one. Expect rare false positives on wick fills.
18
29
  *
19
- * Mirrors modules/dexbot_cow_runtime.ts:isLastFillGuardBlocked 1:1 and
20
- * modules/constants.ts:DEFAULT_CONFIG.incrementPercent fallback (0.5).
30
+ * Mirrors modules/order/utils/system.ts:isLastFillGuardBlocked 1:1.
21
31
  *
22
32
  * Fetches fill_order operations from Kibana (same pipeline as
23
33
  * trade_profitability.ts) and checks for last-fill guard violations.
@@ -41,41 +51,32 @@ import { resolveBotAccount } from './account_resolver.js';
41
51
  import { classifyFill, assetSymbol, fetchAllFills, resolveAssetPrecisions, } from './fills_source.js';
42
52
  const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
43
53
  const OP_LIMIT_ORDER_UPDATE = 77;
44
- // ─── LAST-FILL-GUARD helper (1:1 with dexbot_cow_runtime.ts) ─────────────────
54
+ // ─── LAST-FILL-GUARD helper (1:1 with modules/order/utils/system.ts) ────────────
45
55
  /**
46
- * LAST-FILL-GUARD helper — pivot ± halfIncrement (replaces price-tolerance).
47
- * last fill @x with increment i: BUY < x*(1 - i/2/100), SELL > x*(1 + i/2/100)
48
- * e.g. x=1000, i=0.5% => BUY < 997.5, SELL > 1002.5
49
- * Cold (pivot null or lastType null) => disabled.
56
+ * LAST-FILL-GUARD helper — DIRECTION ONLY relative to the last fill price.
57
+ * BUY blocked if price >= pivot
58
+ * SELL blocked if price <= pivot
59
+ * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000
60
+ * Cold (pivot null or lastType null) => disabled. Equal price stays blocked
61
+ * (a re-place at the just-filled level).
50
62
  * @param {number} price - Target order price
51
63
  * @param {string} type - buy/sell
52
64
  * @param {number|null} lastPrice - Most recent fill price
53
65
  * @param {string|null} lastType - Most recent fill side (buy/sell)
54
- * @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If not finite/<=0 falls back to DEFAULT_CONFIG.
55
66
  * @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
56
67
  */
57
- function isLastFillGuardBlocked(price, type, lastPrice, lastType, incrementPercent) {
68
+ function isLastFillGuardBlocked(price, type, lastPrice, lastType) {
58
69
  const numPrice = Number(price);
59
70
  if (!Number.isFinite(numPrice))
60
71
  return { blocked: false, pivot: null };
61
72
  if (lastPrice == null || !Number.isFinite(Number(lastPrice)) || lastType == null)
62
73
  return { blocked: false, pivot: null };
63
74
  const pivot = Number(lastPrice);
64
- let inc = Number(incrementPercent);
65
- if (!Number.isFinite(inc) || inc <= 0) {
66
- inc = Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5);
67
- }
68
- if (!Number.isFinite(inc) || inc <= 0)
69
- return { blocked: false, pivot: null };
70
- const halfInc = inc / 2;
71
- const halfPct = halfInc / 100;
72
- const buyThreshold = pivot * (1 - halfPct);
73
- const sellThreshold = pivot * (1 + halfPct);
74
- if (type === 'buy' && numPrice > buyThreshold)
75
- return { blocked: true, pivot, halfInc, threshold: buyThreshold };
76
- if (type === 'sell' && numPrice < sellThreshold)
77
- return { blocked: true, pivot, halfInc, threshold: sellThreshold };
78
- return { blocked: false, pivot: null, halfInc, threshold: null };
75
+ if (type === 'buy' && numPrice >= pivot)
76
+ return { blocked: true, pivot, halfInc: 0, threshold: pivot };
77
+ if (type === 'sell' && numPrice <= pivot)
78
+ return { blocked: true, pivot, halfInc: 0, threshold: pivot };
79
+ return { blocked: false, pivot: null, halfInc: 0, threshold: null };
79
80
  }
80
81
  function resolveIncrementPercent(botMeta, override) {
81
82
  if (override != null && Number.isFinite(override) && override > 0)
@@ -93,11 +94,11 @@ function printHelp() {
93
94
  console.log(`\
94
95
  Usage: node dist/analysis/grid_correction_check.js --bot-key <key> [options]
95
96
 
96
- Validates LAST-FILL-GUARD discipline (pivot ± halfIncrement):
97
- last fill @x with increment i (half=i/2) gates both sides —
98
- BUY must be < x*(1-half/100), SELL > x*(1+half/100).
99
- e.g. x=1000, i=0.5% => BUY < 997.5 / SELL > 1002.5.
100
- Mirrors dexbot_cow_runtime:isLastFillGuardBlocked 1:1.
97
+ Validates LAST-FILL-GUARD discipline (DIRECTION ONLY relative to the last fill):
98
+ BUY must be < last fill price, SELL must be > last fill price.
99
+ Equal price counts as blocked (a re-place at the just-filled level).
100
+ Mirrors modules/order/utils/system:isLastFillGuardBlocked 1:1.
101
+ Cold start (no previous fill) is disabled.
101
102
 
102
103
  Required:
103
104
  --bot-key <key> Bot key (e.g. my-grid-bot) or bot name (use --list-bots)
@@ -112,8 +113,9 @@ Options:
112
113
  --refresh-account Force re-resolution of preferredAccount and update the
113
114
  stored accountId when it changed (default: reuse the
114
115
  stored accountId with no chain lookup)
115
- --increment <pct> Grid increment percent (default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
116
- --tolerance <pct> Deprecated alias for --increment (kept for compat, prefer --increment)
116
+ --increment <pct> Grid increment percent, informational only — the
117
+ direction-only guard does not use a band
118
+ (default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
117
119
  --per-fill Check at fill granularity (default: per-order aggregated)
118
120
  --include-cross-pair Check consecutive fills across different pairs (default: same pair only)
119
121
  --json <file> Export violations as JSON
@@ -191,15 +193,6 @@ function parseArgs() {
191
193
  case '--increment':
192
194
  opts.incrementPercent = parseFloat(args[++i]);
193
195
  break;
194
- case '--tolerance': {
195
- const v = parseFloat(args[++i]);
196
- // Back-compat: old --tolerance was adverse pct before flagging; now map to increment if user still passes it
197
- // Prefer explicit --increment; don't overwrite if already set
198
- if (opts.incrementPercent == null)
199
- opts.incrementPercent = v > 0 ? v * 2 : null; // heuristic: old tolerance ~ halfInc, so inc ~ 2*tolerance
200
- console.warn(`[warn] --tolerance is deprecated, use --increment <pct> (e.g. --increment ${v > 0 ? (v * 2) : 0.5})`);
201
- break;
202
- }
203
196
  case '--json':
204
197
  opts.json = args[++i];
205
198
  break;
@@ -416,7 +409,7 @@ function aggregateByOrder(trades, updates = []) {
416
409
  return orders.sort((a, b) => a.sequence - b.sequence);
417
410
  }
418
411
  // ─── Violation detection (LAST-FILL-GUARD 1:1) ────────────────────────────────
419
- function detectViolations(items, includeCrossPair, incrementPercent) {
412
+ function detectViolations(items, includeCrossPair) {
420
413
  const violations = [];
421
414
  let checkedTransitions = 0;
422
415
  // Helper for a single chronological sequence (already filtered to one pair or global)
@@ -428,7 +421,7 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
428
421
  if (prev.orderId && prev.orderId === curr.orderId)
429
422
  continue;
430
423
  checkedTransitions++;
431
- const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction, incrementPercent);
424
+ const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction);
432
425
  if (check.blocked) {
433
426
  const delta = curr.price - prev.price;
434
427
  const deltaPct = prev.price !== 0 ? (delta / prev.price) * 100 : 0;
@@ -437,13 +430,13 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
437
430
  index: i,
438
431
  pair: `${curr.baseAsset}:${curr.quoteAsset}`,
439
432
  direction: curr.direction,
440
- expected: isSell ? `> ${check.threshold?.toFixed(6)} (pivot ${check.pivot} +${check.halfInc}%)` : `< ${check.threshold?.toFixed(6)} (pivot ${check.pivot} -${check.halfInc}%)`,
433
+ expected: isSell ? `> ${check.threshold?.toFixed(6)} (last fill ${check.pivot})` : `< ${check.threshold?.toFixed(6)} (last fill ${check.pivot})`,
441
434
  prev: prev,
442
435
  curr: curr,
443
436
  priceDelta: delta,
444
437
  priceDeltaPct: deltaPct,
445
438
  pivot: check.pivot,
446
- halfInc: check.halfInc,
439
+ halfInc: 0,
447
440
  threshold: check.threshold,
448
441
  });
449
442
  }
@@ -486,10 +479,11 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
486
479
  pairGroups.set(k, []);
487
480
  pairGroups.get(k).push(t);
488
481
  }
489
- const halfInc = incrementPercent / 2;
482
+ // Direction-only guard: no band. The Violation row keeps halfInc = 0 so the
483
+ // JSON/CSV shape stays stable for existing consumers.
490
484
  console.log('');
491
485
  console.log('═══════════════════════════════════════════════════════════════════');
492
- console.log(' LAST-FILL-GUARD CHECK (pivot ± halfIncrement)');
486
+ console.log(' LAST-FILL-GUARD CHECK (direction only)');
493
487
  console.log('═══════════════════════════════════════════════════════════════════');
494
488
  console.log(` Bot key: ${botKey}${botMeta?.name ? ` (name: ${botMeta.name})` : ''}`);
495
489
  if (botMeta)
@@ -497,8 +491,8 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
497
491
  console.log(` Account: ${accountId}`);
498
492
  console.log(` Range: ${rangeLabel}`);
499
493
  console.log(` Mode: ${perFill ? 'per-fill' : 'per-order (aggregated)'}${includeCrossPair ? ', cross-pair enabled' : ', same-pair only'}`);
500
- console.log(` Increment: ${incrementPercent}% (halfInc ${halfInc}%)`);
501
- console.log(` Guard: BUY < pivot*(1-${halfInc}%) / SELL > pivot*(1+${halfInc}%) — both sides, global pivot`);
494
+ console.log(` Increment: ${incrementPercent}% (informational — the guard is direction-only)`);
495
+ console.log(' Guard: BUY < last fill / SELL > last fill — both sides, global pivot');
502
496
  console.log('');
503
497
  const buyCount = trades.filter(t => t.direction === 'buy').length;
504
498
  const sellCount = trades.filter(t => t.direction === 'sell').length;
@@ -512,7 +506,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
512
506
  console.log(` Violations: ${violations.length}${checkedTransitions > 0 ? ` (${((violations.length / checkedTransitions) * 100).toFixed(2)}%)` : ''}`);
513
507
  console.log('');
514
508
  if (violations.length === 0) {
515
- console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < pivot-half, SELL > pivot+half).');
509
+ console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < last fill, all SELL > last fill).');
516
510
  console.log('');
517
511
  if (checkedTransitions === 0) {
518
512
  console.log(' Note: no consecutive transitions in range to check.');
@@ -526,7 +520,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
526
520
  // Per-direction breakdown (blocked side = curr direction)
527
521
  const buyV = violations.filter(v => v.direction === 'buy').length;
528
522
  const sellV = violations.filter(v => v.direction === 'sell').length;
529
- console.log(` Breakdown: sell violations: ${sellV} (SELL < pivot+half), buy violations: ${buyV} (BUY > pivot-half)`);
523
+ console.log(` Breakdown: sell violations: ${sellV} (SELL <= last fill), buy violations: ${buyV} (BUY >= last fill)`);
530
524
  console.log('');
531
525
  // Timeline clustering by day
532
526
  const dayBuckets = new Map();
@@ -556,9 +550,9 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
556
550
  }
557
551
  console.log('');
558
552
  // Detailed violation table
559
- console.log(' ── Violations (pivot ± halfIncrement) ──');
553
+ console.log(' ── Violations (direction only) ──');
560
554
  console.log('');
561
- const hdr = ' # Pair Dir Prev Price Curr Price Thr Δ% Half% Prev Time Curr Time Prev Order Curr Order';
555
+ const hdr = ' # Pair Dir Prev Price Curr Price Last Fill Δ% Prev Time Curr Time Prev Order Curr Order';
562
556
  console.log(hdr);
563
557
  console.log(' ' + '─'.repeat(hdr.length - 2));
564
558
  for (let i = 0; i < violations.length; i++) {
@@ -570,24 +564,22 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
570
564
  const thr = fmt(v.threshold, 6).padStart(12);
571
565
  const delta = (v.priceDeltaPct >= 0 ? '+' : '') + v.priceDeltaPct.toFixed(4) + '%';
572
566
  const deltaStr = delta.padStart(9);
573
- const halfStr = (v.halfInc.toFixed(3) + '%').padStart(6);
574
567
  const pTime = (v.prev.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
575
568
  const cTime = (v.curr.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
576
569
  const pOrd = (v.prev.orderId || '-').slice(0, 16).padEnd(16);
577
570
  const cOrd = (v.curr.orderId || '-').slice(0, 16).padEnd(16);
578
571
  const marker = v.direction === 'sell' ? `SELL < ${fmt(v.threshold, 4)}` : `BUY > ${fmt(v.threshold, 4)}`;
579
- console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${halfStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
572
+ console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
580
573
  }
581
574
  console.log('');
582
- console.log(` Guard: BUY must be < pivot*(1-${halfInc}%), SELL > pivot*(1+${halfInc}%) — blocked if violated (mirrors bot).`);
583
- console.log(` Increment ${incrementPercent}% => halfInc ${halfInc}% — e.g. pivot 1000 => BUY thr ${(1000 * (1 - halfInc / 100)).toFixed(4)}, SELL thr ${(1000 * (1 + halfInc / 100)).toFixed(4)}`);
575
+ console.log(' Guard: BUY must be < the last fill price, SELL > it (equal price blocked) — mirrors bot.');
576
+ console.log(` No band: the grid increment (${incrementPercent}%) is reported for context only.`);
584
577
  console.log('');
585
578
  }
586
579
  function exportJson(filePath, violations, trades, rangeLabel, botKey, accountId, incrementPercent) {
587
580
  const payload = {
588
581
  botKey, accountId, range: rangeLabel,
589
582
  incrementPercent,
590
- halfIncrement: incrementPercent / 2,
591
583
  totalFills: trades.length,
592
584
  violations: violations.map(v => ({
593
585
  pair: `${assetSymbol(v.prev.baseAsset)}/${assetSymbol(v.prev.quoteAsset)}`,
@@ -638,7 +630,7 @@ async function main() {
638
630
  const botMeta = resolvedAccount.botMeta;
639
631
  console.log(`Account: ${accountId}${botMeta ? ` (${botMeta.assetA}/${botMeta.assetB})` : ''}`);
640
632
  const incrementPercent = resolveIncrementPercent(botMeta, opts.incrementPercent);
641
- console.log(`Increment: ${incrementPercent}% (halfInc ${incrementPercent / 2}%)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);
633
+ console.log(`Increment: ${incrementPercent}% (informational; the guard is direction-only)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);
642
634
  console.log(`\nFetching fills and order updates from Kibana...`);
643
635
  const [fills, orderUpdates] = await Promise.all([
644
636
  fetchAllFills({}, accountId, gte, lte),
@@ -677,7 +669,7 @@ async function main() {
677
669
  console.log(` Aggregated into ${orders.length} order epoch(s) (partial fills collapsed; repriced orders kept separate)`);
678
670
  items = orders;
679
671
  }
680
- const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair, incrementPercent);
672
+ const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair);
681
673
  const ordersForReport = opts.perFill ? null : items;
682
674
  printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, String(opts.botKey), accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
683
675
  if (opts.json)
@@ -72,7 +72,7 @@ declare function geometricRange(min: number, max: number, count: number, { decim
72
72
  * Parse a candle JSON file with format detection:
73
73
  * flat array → {candles: [...]} → {data: [...]}
74
74
  */
75
- export interface CandleFile {
75
+ interface CandleFile {
76
76
  candles: Record<string, unknown>[];
77
77
  meta: Record<string, unknown> | null;
78
78
  }
@@ -146,5 +146,5 @@ declare function computeMetrics(pair: PairAnalysis, window?: WindowRange): Tradi
146
146
  /** Auto-named report file: bot/account + pair filter + requested range. */
147
147
  declare function reportFileName(opts: TradeProfitabilityOptions, accountRef: string, botName: string | null): string;
148
148
  declare function run(argv?: string[]): Promise<void>;
149
- export { analyzePair, classifyFills, computeMetrics, parseArgs, run, reportFileName, TradeFill, FillRecord, RealizedPnl, PairAnalysis, TradingMetrics, WindowRange };
149
+ export { analyzePair, classifyFills, computeMetrics, parseArgs, run, reportFileName, TradeFill, FillRecord, PairAnalysis, TradingMetrics };
150
150
  //# sourceMappingURL=trade_profitability.d.ts.map