dexbot 1.7.2 → 1.7.3

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 (45) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/analysis/grid_correction_check.d.ts +60 -1
  6. package/dist/analysis/grid_correction_check.js +268 -18
  7. package/dist/analysis/pivot_timeline.d.ts +78 -0
  8. package/dist/analysis/pivot_timeline.js +360 -0
  9. package/dist/market_adapter/utils/file_lock.js +16 -4
  10. package/dist/modules/account_bots.d.ts +6 -0
  11. package/dist/modules/bot_defaults.js +6 -1
  12. package/dist/modules/constants.d.ts +12 -0
  13. package/dist/modules/constants.js +66 -0
  14. package/dist/modules/dexbot_class.d.ts +17 -0
  15. package/dist/modules/dexbot_class.js +56 -1
  16. package/dist/modules/dexbot_cow_runtime.js +231 -19
  17. package/dist/modules/dexbot_maintenance_runtime.d.ts +31 -1
  18. package/dist/modules/dexbot_maintenance_runtime.js +164 -11
  19. package/dist/modules/dexbot_state_recovery.js +15 -1
  20. package/dist/modules/launcher/instance_lock.d.ts +27 -0
  21. package/dist/modules/launcher/instance_lock.js +131 -0
  22. package/dist/modules/order/grid.d.ts +19 -0
  23. package/dist/modules/order/grid.js +40 -14
  24. package/dist/modules/order/index.d.ts +15 -1
  25. package/dist/modules/order/manager.d.ts +21 -0
  26. package/dist/modules/order/manager.js +119 -12
  27. package/dist/modules/order/placement_lock.d.ts +30 -0
  28. package/dist/modules/order/placement_lock.js +48 -0
  29. package/dist/modules/order/utils/order.d.ts +39 -1
  30. package/dist/modules/order/utils/order.js +73 -2
  31. package/dist/modules/order/utils/system.d.ts +112 -3
  32. package/dist/modules/order/utils/system.js +368 -6
  33. package/dist/modules/paths.d.ts +1 -0
  34. package/dist/modules/paths.js +1 -0
  35. package/dist/modules/timing_policy.js +2 -0
  36. package/dist/modules/types.d.ts +27 -0
  37. package/dist/pm2.js +126 -0
  38. package/dist/unlock.js +26 -1
  39. package/docs/DEXBOT_COMPARISON.md +5 -5
  40. package/docs/EVOLUTION.md +10 -9
  41. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  42. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +155 -2
  43. package/docs/README.md +1 -1
  44. package/modules/README.md +1 -0
  45. package/package.json +2 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,30 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.7.3] - 2026-11-17 - Plan-Region Serialization, Single-Controller Launcher Lock, Market-Bounded Pivot & Same-Level Refill Guard, In-Place Missing-Target Repair, Settled-Pipeline Resync Gate
6
+
7
+ ### 2026-11-17
8
+
9
+ - **Feat(launcher)**: per-account single-controller lock and cross-runtime start guards — two controllers running simultaneously on one account corrupt each other's state (independent in-memory grids, mutual "duplicate orphan" cancellations, and split fill attributions). `modules/launcher/instance_lock.ts` introduces an account-keyed advisory lock under `profiles/instance-locks/`, acquired during `DEXBot._runStartupSequence` and released upon shutdown; dead holders are detected and cleaned up via `/proc` liveness and process start time (safe against PID recycling), while a live holder causes an immediate failure with PID, bot name, and start time. `acquireFileLockSync` in `market_adapter/utils/file_lock.ts` now supports custom payload builders and predicates. Cross-runtime protections: `dexbot pm2` refuses fleet startup when a monolithic `dexbot start` instance is active and warns about orphaned PM2 bots not listed in `bots.json`; `dexbot start` detects and refuses to launch bots already managed by PM2, pointing operators to `dexbot pm2 stop`.
10
+
11
+ - **Fix(cow)**: serialize plan→broadcast, drop fill-less stale plans, skip clamped no-ops — closes concurrency and churn gaps identified during a 30-day live log review. (1) *Plan region serialization*: `performSafeRebalance` now claims the exclusive placement region BEFORE planning when the caller executes the result (the fill path and post-recovery rebalances) and passes the lease through `PLAN_LEASE_RESULT_KEY` to the executor, closing the plan→claim race window where concurrent planners built from the same master and caused duplicate placements. (2) *Fill-less stale plans dropped*: stale pre-broadcast events without fill context (e.g., triggered by snapshot reloads mutating the master mid-plan) are discarded instead of shipping pre-mutation operations, deferring rebalance to region-end re-derivation. (3) *Clamped PARTIAL updates skipped*: PARTIAL-growth size updates clamped to zero net delta skip redundant chain reads and op construction. (4) Added P2 churn counters (`stalePlanDroppedCount`, `stalePlanProceedCount`, `clampedNoopUpdateCount`, `chunkAbortedOpCount`, `reloadReplacedRailCount`).
12
+
13
+ - **Fix(cow)**: repair a missing UPDATE target in place instead of reloading the snapshot — when an UPDATE target is missing on chain (e.g., consumed by an un-indexed fill or external cancel), triggering a structural resync reloads the on-disk snapshot which often still contains the stale order ID, resulting in a recurring resync loop. The engine now invokes `_targetedOrderRepair` in place: releasing the dead commitment, virtualizing the slot into an empty hole, dropping the failed batch, and scheduling a single lazy re-plan without a snapshot reload or structural resync. Escalation to structural resync remains the fallback if targeted repair fails.
14
+
15
+ - **Fix(recovery)**: don't reload a stale snapshot over an unsettled fill pipeline — an on-disk snapshot lags the in-memory grid during active fills because slot sizes update immediately while disk flush is deferred. A structural resync triggered during this window rolled back applied fills, causing subsequent fills for the same order to calculate residuals against pre-fill baselines and leave phantom resting orders inside the gap band. Resync requests now defer via `hasUnsettledFills` (250 ms retry, 30 s max deferral) until queued, deferred, and in-flight fills have settled before executing the snapshot reload.
16
+
17
+ - **Fix(lifecycle)**: stop a snapshot load renewing the absence grace — `_syncLifecycleFromMutation` stamped `assignedAt` whenever a slot's chain ID changed. Because recovery reloads clear the master map, reloaded slots appeared as brand-new assignments, granting each order ID a fresh `SYNC_LOCK_TIMEOUT_MS` window that prevented chain sync from treating genuine absences as real. Re-loads (`grid-load`/`grid-init`) now bypass the `assignedAt` stamp when the lifecycle registry already recognizes the order ID, preventing infinite absence-grace renewals and allowing gap-band evacuation to proceed.
18
+
19
+ - **Fix(cow)**: bound the last-fill pivot to the live market — a fill on the wrong side of the market (e.g. a crossed-book artifact swept by an external taker) previously armed the LAST-FILL-GUARD direction pivot and froze all near-market counter-side placements for the 24-hour TTL. `setLastFillPivot` now validates fill-provenance writes against the live mid (`LAST_FILL_PIVOT_WRONG_SIDE_TOLERANCE_STEPS`, 1 grid step) and skips off-market writes; `restoreLastFillPivot` discards off-market persisted rows upon restart; and `filterMarketCrossingActions` filters out CREATE/UPDATE actions priced across the live mid prior to broadcast (`MARKET_CROSSING_FILTERED`), preventing swept premium crosses while preserving valid cancels.
20
+
21
+ - **Fix(spread)**: expire a deadlocked last-fill pivot after the one re-center — once the single geometry re-center per pivot had fired, the out-of-spread watchdog had no further escalation path, leaving the bot out of spread for up to 24 hours if the pivot sat off-market. Registered `SPREAD_STALE_PIVOT_EXPIRE_MS` (20 minutes, 0 = legacy never-expire) in timing policy; upon expiration, `expireLastFillGuardReferences()` clears both the in-memory and persisted pivot and last-market-fill references, resetting the stale clock and allowing spread correction to resume quoting around the live market.
22
+
23
+ - **Fix(order)**: unblock spread repair after filled-order geometry drift — applies the revised order-engine priority hierarchy across COW placement, fill pivoting, rotation projection, and stale-spread maintenance. Market crossing is observed rather than vetoed, only current-window fills arm the direction pivot, band counter-orders retain safe territory, and rotation sources preserve their genesis levels. The spread watchdog requires measurable progress and owns a level-triggered retry, preventing wide spreads from stalling indefinitely while waiting for an external fill.
24
+
25
+ - **Fix(order)**: close the same-level re-fill gap when a pivot-arm is refused — when a fill is refused by pivot-arming policy (e.g. wrong-side or premium sweep), the direction pivot is not armed, which inadvertently bypassed the same-level re-fill block that keyed exclusively off the armed pivot. A spread-correction slot could then be repeatedly re-placed at the exact same level and refilled in a loop. Refused fills now record an in-memory marker (`_lastRefusedFillPrice/_Type/_At`) with a 30-minute TTL (`LAST_FILL_REFUSED_LEVEL_TTL_MS`); `evaluateLastFillGuard` and `isLastFillPlacementBlocked` refuse same-side placement within half a step (`pricesWithinHalfStep`) of the refused level (`refused-level`); `resetLastFillPivot` clears the marker on grid reset.
26
+
27
+ - **Fix(analysis)**: policy-aware LAST-FILL-GUARD audit mirror — the offline direction checker previously judged order re-quotes against an all-fills pivot baseline, reporting false violations when the runtime had legitimately refused to arm off-market or sweep fills. Added `analysis/pivot_timeline.ts` to reconstruct the runtime's actual pivot timeline from log lines (`FILL-PIVOT`, `mode=`, `Final-gate`, allowances/refusals) and classify candidates into policy divergences, violations, or unverifiable events. `grid_correction_check.ts` runs in policy-aware mode by default (retaining `--strict` for legacy analysis) and hardens log parsing (operation suffix normalization, UTC timestamps, non-observation queue-refresh lines, price-matched anchors).
28
+
5
29
  ## [1.7.2] - 2026-11-04 - One Fill Contract with Fail-Closed Grid Blockers, Single Fill Identity, Broadcast-Region Leak Repair, Fill-Anchored Rebuild Boundary, Spread Rotation Into Orphaned Rails
6
30
 
7
31
  ### 2026-11-04
package/claw/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot2-claw",
3
- "version": "1.7.2",
3
+ "version": "1.7.3",
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.7.2",
5
+ "version": "1.7.3",
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.7.2",
4
+ "version": "1.7.3",
5
5
  "type": "module",
6
6
  "main": "index.js"
7
7
  }
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { isLastFillGuardBlocked } from '../modules/order/utils/system.js';
3
3
  import { FillRecord } from './fills_source.js';
4
+ import { RuntimeLogIndex } from './pivot_timeline.js';
4
5
  interface TradeFill {
5
6
  time: string;
6
7
  orderId: string;
@@ -27,10 +28,68 @@ interface Violation {
27
28
  halfInc: number;
28
29
  /** The pivot itself (BUY must be below / SELL above it). */
29
30
  threshold: number;
31
+ /**
32
+ * Same-level re-fill (§0 "equal is a violation — a re-place at the
33
+ * just-filled level"; §9.12/P2): the transition stayed within half a grid
34
+ * step of the previous same-side fill (the runtime's own same-level test,
35
+ * pricesWithinHalfStep). Realized fill prices of one re-placed level differ
36
+ * by sub-sat rounding dust, so a float-exact compare passes such a loop.
37
+ * Present on the violation regardless of which rule caught it.
38
+ */
39
+ sameLevel?: boolean;
30
40
  }
41
+ interface AggregatedOrder {
42
+ orderId: string;
43
+ direction: 'buy' | 'sell';
44
+ baseAsset: string;
45
+ quoteAsset: string;
46
+ baseAmount: number;
47
+ quoteAmount: number;
48
+ price: number;
49
+ time: string;
50
+ sequence: number;
51
+ fillCount: number;
52
+ isMaker: boolean;
53
+ }
54
+ /** A strict candidate the runtime's own gate would have passed (policy-aware mode). */
55
+ interface PolicyDivergence {
56
+ index: number;
57
+ pair: string;
58
+ direction: 'buy' | 'sell';
59
+ prev: TradeFill;
60
+ curr: TradeFill;
61
+ pivot: {
62
+ price: number;
63
+ type: string;
64
+ t: number;
65
+ } | null;
66
+ reason: string;
67
+ refusalsInRange: number;
68
+ priceDeltaPct: number;
69
+ /** True when the candidate is a same-level re-fill (within half a grid step of the previous same-side fill). */
70
+ sameLevel?: boolean;
71
+ }
72
+ /**
73
+ * Policy-aware mirror: re-judge every strict violation against the pivot the
74
+ * runtime held when the filled order was last priced (parsed from the bot log
75
+ * by pivot_timeline.ts). Candidates the runtime's OWN pivot would have passed
76
+ * become policy divergences — expected under the pivot-arming policy, not gate
77
+ * failures — and are dropped from the FAIL count. Anything unprovable stays a
78
+ * violation (fail toward reporting). A missing log falls back to strict mode.
79
+ */
80
+ declare function applyRuntimeMirror(violations: Violation[], logPath: string, incrementPercent: number): {
81
+ kept: Violation[];
82
+ divergences: PolicyDivergence[];
83
+ index: RuntimeLogIndex | null;
84
+ logError: string | null;
85
+ };
31
86
  declare function classifyFills(fills: FillRecord[]): {
32
87
  trades: TradeFill[];
33
88
  skipped: number;
34
89
  };
35
- export { isLastFillGuardBlocked, classifyFills, TradeFill, Violation };
90
+ declare function detectViolations(items: (TradeFill | AggregatedOrder)[], includeCrossPair: boolean, incrementPercent: number): {
91
+ violations: Violation[];
92
+ checkedTransitions: number;
93
+ };
94
+ export { isLastFillGuardBlocked, detectViolations, applyRuntimeMirror, classifyFills, TradeFill, AggregatedOrder, Violation, PolicyDivergence };
36
95
  //# sourceMappingURL=grid_correction_check.d.ts.map
@@ -15,17 +15,39 @@
15
15
  * cost — i.e. it reported the tightening placements the current engine
16
16
  * legitimately makes as violations. Do not reintroduce an increment term here.
17
17
  *
18
+ * MODES — the strict check above is available as `--strict`. The DEFAULT is
19
+ * policy-aware: it additionally reconstructs the pivot the runtime ACTUALLY
20
+ * held when each filled order was last priced (from the bot log's own pivot
21
+ * bookkeeping — FILL-PIVOT / mode= / Final-gate / refusal lines, parsed by
22
+ * `analysis/pivot_timeline.ts`) and re-judges every strict candidate against
23
+ * that pivot:
24
+ * - violation the runtime's OWN pivot would have blocked the
25
+ * placement — a real gate failure.
26
+ * - policy-divergence the runtime pivot would have passed it — expected
27
+ * under the pivot-arming policy (see gaps below);
28
+ * reported in its own section, not counted as FAIL.
29
+ * - unverifiable no placement event / pivot observation near the gate
30
+ * — kept as a violation (fail toward reporting).
31
+ *
18
32
  * Intentional offline gaps (documented, acceptable):
19
33
  * - Runtime pivots on _lastFilledPrice/_lastFilledType at decision time; tool
20
34
  * checks consecutive fill pairs. For batch-placed orders (multiple orders
21
35
  * guarded against the same pivot in one COW batch) this diverges — inherent
22
36
  * offline approximation.
23
37
  * - Spread-correction bypass (cowResult.origin === 'spread-correction') is
24
- * not simulated — every consecutive pair is checked.
38
+ * not simulated — every consecutive pair is checked (correction placements
39
+ * do appear in the runtime log's Plan/Placed lines, so the policy-aware
40
+ * mirror can still excuse them when the pivot passes them).
25
41
  * - EDGE-pinned insurance fills no longer arm the runtime pivot
26
42
  * (recordLastFilledPrices skips them); this reconstruction has no slot
27
43
  * identity for a fill, so it cannot classify edge fills and will still
28
44
  * judge the pair after one. Expect rare false positives on wick fills.
45
+ * - PIVOT-ARMING REFUSALS (66667052 / bc7b5232, retrospective §9.12/P1): a
46
+ * fill refused from arming the pivot (wrong-side, too-far premium sweep,
47
+ * gap-band stranded residual) leaves the pivot behind the true last fill,
48
+ * and a re-quote the gate passes is NOT a discipline breach. The strict
49
+ * mode flags these; policy-aware mode classifies them as divergences.
50
+ * Without a usable runtime log the tool falls back to strict and says so.
29
51
  *
30
52
  * Uses the runtime's own predicate (`modules/order/utils/system.ts:`
31
53
  * `isLastFillGuardBlocked`); the checker never re-implements it.
@@ -44,6 +66,7 @@
44
66
  */
45
67
  import { getErrorMessage, getErrorField } from '../modules/utils/errors.js';
46
68
  import { isLastFillGuardBlocked } from '../modules/order/utils/system.js';
69
+ import { pricesWithinHalfStep } from '../modules/order/utils/math.js';
47
70
  import fs from 'node:fs';
48
71
  import { pathToFileURL } from 'node:url';
49
72
  import * as KC from '../market_adapter/core/kibana_client.js';
@@ -51,8 +74,100 @@ import * as C from '../modules/constants.js';
51
74
  import { loadBotSettings, computeBotKey } from './bot_key_utils.js';
52
75
  import { resolveBotAccount } from './account_resolver.js';
53
76
  import { classifyFill, assetSymbol, fetchAllFills, resolveAssetPrecisions, } from './fills_source.js';
77
+ import { parseRuntimeLog, classifyTransition, } from './pivot_timeline.js';
78
+ import path from 'node:path';
54
79
  const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
55
80
  const OP_LIMIT_ORDER_UPDATE = 77;
81
+ /**
82
+ * SAME-LEVEL REFUSAL MARKER (§9.12/P2 amended): did the runtime refuse the
83
+ * pivot-arm of the just-filled level shortly before this same-level re-fill?
84
+ * The amended runtime writes a same-level re-fill block when it refuses a
85
+ * pivot arm, so a same-level fill that the log shows SHOULD have been blocked
86
+ * is a gate failure — a violation even in policy-aware mode — not a policy
87
+ * divergence. Fail-open: no log, no matching refusal => normal mirror verdict.
88
+ */
89
+ function sameLevelRefusalMarker(index, v, incrementPercent) {
90
+ if (!index)
91
+ return false;
92
+ const prevT = Date.parse(v.prev.time + (/[Zz]|[+-]\d\d:?(\d\d)?$/.test(v.prev.time) ? '' : 'Z'));
93
+ const currT = Date.parse(v.curr.time + (/[Zz]|[+-]\d\d:?(\d\d)?$/.test(v.curr.time) ? '' : 'Z'));
94
+ if (!Number.isFinite(prevT) || !Number.isFinite(currT))
95
+ return false;
96
+ const ttl = Number(C.GRID_LIMITS?.LAST_FILL_REFUSED_LEVEL_TTL_MS ?? 0);
97
+ if (!(ttl > 0))
98
+ return false;
99
+ for (const r of index.refusals) {
100
+ if (r.type !== v.direction)
101
+ continue;
102
+ if (r.t > currT)
103
+ continue;
104
+ if (currT - r.t > ttl)
105
+ continue;
106
+ // The marker must postdate the just-filled trade itself (5s slack for
107
+ // block-time vs log-clock skew), else it describes an older level.
108
+ if (r.t < prevT - 5000)
109
+ continue;
110
+ if (pricesWithinHalfStep(r.price, v.prev.price, incrementPercent))
111
+ return true;
112
+ }
113
+ return false;
114
+ }
115
+ /**
116
+ * Policy-aware mirror: re-judge every strict violation against the pivot the
117
+ * runtime held when the filled order was last priced (parsed from the bot log
118
+ * by pivot_timeline.ts). Candidates the runtime's OWN pivot would have passed
119
+ * become policy divergences — expected under the pivot-arming policy, not gate
120
+ * failures — and are dropped from the FAIL count. Anything unprovable stays a
121
+ * violation (fail toward reporting). A missing log falls back to strict mode.
122
+ */
123
+ function applyRuntimeMirror(violations, logPath, incrementPercent) {
124
+ let text;
125
+ try {
126
+ text = fs.readFileSync(logPath, 'utf-8');
127
+ }
128
+ catch (e) {
129
+ return { kept: violations, divergences: [], index: null, logError: getErrorMessage(e) };
130
+ }
131
+ const index = parseRuntimeLog(text);
132
+ const kept = [];
133
+ const divergences = [];
134
+ for (const v of violations) {
135
+ // Same-level re-fill whose just-filled level carries a fresh refusal
136
+ // marker in the log: the amended §9.12/P2 gate would have blocked the
137
+ // re-placement — it filled anyway => gate failure, keep as violation.
138
+ if (v.sameLevel && sameLevelRefusalMarker(index, v, incrementPercent)) {
139
+ kept.push(v);
140
+ continue;
141
+ }
142
+ const cand = {
143
+ prevTime: v.prev.time,
144
+ currTime: v.curr.time,
145
+ prevPrice: v.prev.price,
146
+ currPrice: v.curr.price,
147
+ direction: v.direction,
148
+ currOrderId: v.curr.orderId,
149
+ };
150
+ const verdict = classifyTransition(cand, index);
151
+ if (verdict.verdict === 'policy-divergence') {
152
+ divergences.push({
153
+ index: v.index,
154
+ pair: v.pair,
155
+ direction: v.direction,
156
+ prev: v.prev,
157
+ curr: v.curr,
158
+ pivot: verdict.pivot,
159
+ reason: verdict.reason,
160
+ refusalsInRange: verdict.refusalsInRange,
161
+ priceDeltaPct: v.priceDeltaPct,
162
+ sameLevel: v.sameLevel,
163
+ });
164
+ }
165
+ else {
166
+ kept.push(v);
167
+ }
168
+ }
169
+ return { kept, divergences, index, logError: null };
170
+ }
56
171
  // ─── LAST-FILL-GUARD (the runtime's own predicate) ──────────────────────────────
57
172
  //
58
173
  // `isLastFillGuardBlocked` is IMPORTED from modules/order/utils/system.ts, not
@@ -78,7 +193,9 @@ Usage: node dist/analysis/grid_correction_check.js --bot-key <key> [options]
78
193
 
79
194
  Validates LAST-FILL-GUARD discipline (DIRECTION ONLY relative to the last fill):
80
195
  BUY must be < last fill price, SELL must be > last fill price.
81
- Equal price counts as blocked (a re-place at the just-filled level).
196
+ Equal price counts as blocked (a re-place at the just-filled level); so does
197
+ a same-level re-fill within half a grid step of the just-filled level
198
+ (the runtime's own pricesWithinHalfStep test, §9.12/P2).
82
199
  Uses the runtime's own predicate (isLastFillGuardBlocked); not a copy.
83
200
  Cold start (no previous fill) is disabled.
84
201
 
@@ -98,6 +215,11 @@ Options:
98
215
  --increment <pct> Grid increment percent, informational only — the
99
216
  direction-only guard does not use a band
100
217
  (default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
218
+ --runtime-log <path> Bot log for the policy-aware mirror (default:
219
+ profiles/logs/<bot name>.log when it exists)
220
+ --strict Skip the runtime-pivot mirror; report every
221
+ consecutive-fill descent as a violation (legacy
222
+ behaviour — false positives on pivot-arm refusals)
101
223
  --per-fill Check at fill granularity (default: per-order aggregated)
102
224
  --include-cross-pair Check consecutive fills across different pairs (default: same pair only)
103
225
  --json <file> Export violations as JSON
@@ -145,6 +267,8 @@ function parseArgs() {
145
267
  json: null,
146
268
  csv: null,
147
269
  verbose: false,
270
+ runtimeLog: null,
271
+ strict: false,
148
272
  };
149
273
  for (let i = 0; i < args.length; i++) {
150
274
  switch (args[i]) {
@@ -175,6 +299,12 @@ function parseArgs() {
175
299
  case '--increment':
176
300
  opts.incrementPercent = parseFloat(args[++i]);
177
301
  break;
302
+ case '--runtime-log':
303
+ opts.runtimeLog = args[++i];
304
+ break;
305
+ case '--strict':
306
+ opts.strict = true;
307
+ break;
178
308
  case '--json':
179
309
  opts.json = args[++i];
180
310
  break;
@@ -391,7 +521,7 @@ function aggregateByOrder(trades, updates = []) {
391
521
  return orders.sort((a, b) => a.sequence - b.sequence);
392
522
  }
393
523
  // ─── Violation detection (LAST-FILL-GUARD 1:1) ────────────────────────────────
394
- function detectViolations(items, includeCrossPair) {
524
+ function detectViolations(items, includeCrossPair, incrementPercent) {
395
525
  const violations = [];
396
526
  let checkedTransitions = 0;
397
527
  // Helper for a single chronological sequence (already filtered to one pair or global)
@@ -404,7 +534,17 @@ function detectViolations(items, includeCrossPair) {
404
534
  continue;
405
535
  checkedTransitions++;
406
536
  const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction);
407
- if (check.blocked) {
537
+ // SAME-LEVEL RE-FILL (§9.12/P2): judged with the runtime's OWN
538
+ // same-level predicate (pricesWithinHalfStep, exactly what
539
+ // isLastFillPlacementBlocked applies) — never a copy of it. Same
540
+ // direction only: the counter-side is governed by the direction
541
+ // rule above. A re-placed level's realized fill prices differ by
542
+ // sub-sat rounding dust, so a float-exact compare would pass a
543
+ // loop that re-placed at the IDENTICAL level (live 2026-11-16:
544
+ // one premium spread slot, 5 full fills in 2.5 minutes).
545
+ const sameLevel = prev.direction === curr.direction
546
+ && pricesWithinHalfStep(curr.price, prev.price, incrementPercent);
547
+ if (check.blocked || sameLevel) {
408
548
  const delta = curr.price - prev.price;
409
549
  const deltaPct = prev.price !== 0 ? (delta / prev.price) * 100 : 0;
410
550
  const isSell = curr.direction === 'sell';
@@ -412,14 +552,17 @@ function detectViolations(items, includeCrossPair) {
412
552
  index: i,
413
553
  pair: `${curr.baseAsset}:${curr.quoteAsset}`,
414
554
  direction: curr.direction,
415
- expected: isSell ? `> ${check.threshold?.toFixed(6)} (last fill ${check.pivot})` : `< ${check.threshold?.toFixed(6)} (last fill ${check.pivot})`,
555
+ expected: check.blocked
556
+ ? (isSell ? `> ${check.threshold?.toFixed(6)} (last fill ${check.pivot})` : `< ${check.threshold?.toFixed(6)} (last fill ${check.pivot})`)
557
+ : `different level (> half a step of ${prev.price.toFixed(6)} — same-level re-fill, §9.12/P2)`,
416
558
  prev: prev,
417
559
  curr: curr,
418
560
  priceDelta: delta,
419
561
  priceDeltaPct: deltaPct,
420
- pivot: check.pivot,
562
+ pivot: (check.pivot ?? prev.price),
421
563
  halfInc: 0,
422
- threshold: check.threshold,
564
+ threshold: (check.threshold ?? prev.price),
565
+ sameLevel: sameLevel || undefined,
423
566
  });
424
567
  }
425
568
  }
@@ -453,7 +596,7 @@ function fmt(n, d = 4) {
453
596
  return 'NaN';
454
597
  return n.toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d });
455
598
  }
456
- function printReport(trades, orders, violations, checkedTransitions, skipped, rangeLabel, botKey, accountId, botMeta, perFill, includeCrossPair, incrementPercent, gte, _lte) {
599
+ function printReport(trades, orders, violations, checkedTransitions, skipped, rangeLabel, botKey, accountId, botMeta, perFill, includeCrossPair, incrementPercent, gte, _lte, divergences, mirrorMode, runtimeLogPath, logError, strictCandidates) {
457
600
  const pairGroups = new Map();
458
601
  for (const t of trades) {
459
602
  const k = `${assetSymbol(t.baseAsset)}/${assetSymbol(t.quoteAsset)}`;
@@ -473,8 +616,13 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
473
616
  console.log(` Account: ${accountId}`);
474
617
  console.log(` Range: ${rangeLabel}`);
475
618
  console.log(` Mode: ${perFill ? 'per-fill' : 'per-order (aggregated)'}${includeCrossPair ? ', cross-pair enabled' : ', same-pair only'}`);
619
+ console.log(` Mirror: ${mirrorMode === 'policy-aware' ? `policy-aware (runtime pivot from ${runtimeLogPath})` : 'strict (all consecutive fills)'}`);
620
+ if (mirrorMode === 'strict' && runtimeLogPath) {
621
+ console.log(` (strict fallback${logError ? `: ${logError}` : ' — --strict requested'})`);
622
+ }
476
623
  console.log(` Increment: ${incrementPercent}% (informational — the guard is direction-only)`);
477
624
  console.log(' Guard: BUY < last fill / SELL > last fill — both sides, global pivot');
625
+ console.log(' (+ same-level re-fill: within half a step of the just-filled level, §9.12/P2)');
478
626
  console.log('');
479
627
  const buyCount = trades.filter(t => t.direction === 'buy').length;
480
628
  const sellCount = trades.filter(t => t.direction === 'sell').length;
@@ -485,16 +633,30 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
485
633
  if (skipped > 0)
486
634
  console.log(` Skipped (precision): ${skipped}`);
487
635
  console.log(` Transitions checked: ${checkedTransitions} consecutive fill/order transitions`);
488
- console.log(` Violations: ${violations.length}${checkedTransitions > 0 ? ` (${((violations.length / checkedTransitions) * 100).toFixed(2)}%)` : ''}`);
636
+ if (mirrorMode === 'policy-aware') {
637
+ console.log(` Strict candidates: ${strictCandidates}`);
638
+ console.log(` Policy divergences: ${divergences.length} (runtime gate would have passed them)`);
639
+ }
640
+ console.log(` Violations: ${violations.length}${strictCandidates > 0 ? ` (${((violations.length / strictCandidates) * 100).toFixed(2)}% of strict candidates)` : ''}`);
641
+ const sameLevelViolations = violations.filter(v => v.sameLevel).length;
642
+ const sameLevelDivergences = divergences.filter(d => d.sameLevel).length;
643
+ if (sameLevelViolations + sameLevelDivergences > 0) {
644
+ console.log(` Same-level re-fills: ${sameLevelViolations + sameLevelDivergences} (within half a grid step of the just-filled level, §9.12/P2 — ${sameLevelViolations} violation(s), ${sameLevelDivergences} divergence(s))`);
645
+ }
489
646
  console.log('');
490
647
  if (violations.length === 0) {
491
- console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < last fill, all SELL > last fill).');
648
+ console.log(' ✅ PASS — no LAST-FILL-GUARD gate failures detected (all BUY < pivot, all SELL > pivot).');
649
+ if (mirrorMode === 'policy-aware') {
650
+ console.log(' The runtime\'s own pivot was the reference for every transition that reached the gate.');
651
+ }
492
652
  console.log('');
493
653
  if (checkedTransitions === 0) {
494
654
  console.log(' Note: no consecutive transitions in range to check.');
495
655
  console.log(' (Need at least two fills/orders to form a transition.)');
656
+ console.log('');
496
657
  }
497
- console.log('');
658
+ if (divergences.length > 0)
659
+ printDivergences(divergences);
498
660
  return;
499
661
  }
500
662
  console.log(` ❌ FAIL — ${violations.length} violation(s) detected:`);
@@ -550,19 +712,74 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
550
712
  const cTime = (v.curr.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
551
713
  const pOrd = (v.prev.orderId || '-').slice(0, 16).padEnd(16);
552
714
  const cOrd = (v.curr.orderId || '-').slice(0, 16).padEnd(16);
553
- const marker = v.direction === 'sell' ? `SELL < ${fmt(v.threshold, 4)}` : `BUY > ${fmt(v.threshold, 4)}`;
715
+ const marker = v.sameLevel
716
+ ? `SAME-LEVEL (≤ half step of ${fmt(v.threshold, 4)})`
717
+ : v.direction === 'sell' ? `SELL < ${fmt(v.threshold, 4)}` : `BUY > ${fmt(v.threshold, 4)}`;
554
718
  console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
555
719
  }
556
720
  console.log('');
557
- console.log(' Guard: BUY must be < the last fill price, SELL > it (equal price blocked) — mirrors bot.');
721
+ console.log(' Guard: BUY must be < the last fill price, SELL > it; the just-filled level itself');
722
+ console.log(' (equal price, or within half a grid step — the runtime\'s same-level test) is a');
723
+ console.log(' same-level re-fill and blocked/violation too (§9.12/P2).');
558
724
  console.log(` No band: the grid increment (${incrementPercent}%) is reported for context only.`);
559
725
  console.log('');
726
+ if (divergences.length > 0)
727
+ printDivergences(divergences);
560
728
  }
561
- function exportJson(filePath, violations, trades, rangeLabel, botKey, accountId, incrementPercent) {
729
+ /**
730
+ * Report the strict candidates the runtime's own gate would have passed.
731
+ * These are NOT discipline breaches: the pivot-arming policy (§9.12/P1)
732
+ * deliberately excludes wrong-side / too-far premium-sweep / gap-band fills
733
+ * from arming the pivot, so a re-quote below such a fill is expected.
734
+ * Listing them keeps the policy auditable instead of silently hidden.
735
+ */
736
+ function printDivergences(divergences) {
737
+ console.log(' ── Policy divergences (strict candidate vs the runtime pivot at the gate) ──');
738
+ console.log(' The runtime pivot at placement excluded the strict last fill from arming');
739
+ console.log(' (window-trade policy: wrong-side / premium-sweep / gap-band refusals).');
740
+ console.log('');
741
+ const hdr = ' # Pair Dir Prev Price Curr Price Runtime Pivot Δ% Prev Time Curr Time Curr Order Refusals Reason';
742
+ console.log(hdr);
743
+ console.log(' ' + '─'.repeat(hdr.length - 2));
744
+ for (let i = 0; i < divergences.length; i++) {
745
+ const d = divergences[i];
746
+ const pairLabel = `${assetSymbol(d.prev.baseAsset)}/${assetSymbol(d.prev.quoteAsset)}`.padEnd(12);
747
+ const dir = d.direction.padEnd(4);
748
+ const pPrice = fmt(d.prev.price, 6).padStart(12);
749
+ const cPrice = fmt(d.curr.price, 6).padStart(12);
750
+ const piv = d.pivot ? `${fmt(d.pivot.price, 4)}(${d.pivot.type[0]})` : '-';
751
+ const pivStr = piv.padStart(14);
752
+ const delta = (d.priceDeltaPct >= 0 ? '+' : '') + d.priceDeltaPct.toFixed(4) + '%';
753
+ const deltaStr = delta.padStart(9);
754
+ const pTime = (d.prev.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
755
+ const cTime = (d.curr.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
756
+ const cOrd = (d.curr.orderId || '-').slice(0, 16).padEnd(16);
757
+ const ref = String(d.refusalsInRange).padStart(8);
758
+ const reason = d.sameLevel
759
+ ? `SAME-LEVEL re-fill (${d.pivot ? 'pivot-arm refused in window' : 'no refusal evidence'})`
760
+ : d.pivot
761
+ ? (d.refusalsInRange > 0 ? 'pivot-arm refusal(s) in window' : 'pivot older than strict last fill')
762
+ : 'unverifiable pivot';
763
+ console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${pivStr} ${deltaStr} ${pTime} ${cTime} ${cOrd} ${ref} ${reason}`);
764
+ }
765
+ console.log('');
766
+ }
767
+ function exportJson(filePath, violations, trades, rangeLabel, botKey, accountId, incrementPercent, divergences = [], mirrorMode = 'strict', runtimeLogPath = null) {
562
768
  const payload = {
563
769
  botKey, accountId, range: rangeLabel,
564
770
  incrementPercent,
565
771
  totalFills: trades.length,
772
+ mirror: { mode: mirrorMode, runtimeLog: runtimeLogPath },
773
+ policyDivergences: divergences.map(d => ({
774
+ pair: `${assetSymbol(d.prev.baseAsset)}/${assetSymbol(d.prev.quoteAsset)}`,
775
+ direction: d.direction,
776
+ reason: d.reason,
777
+ prev: { time: d.prev.time, orderId: d.prev.orderId, price: d.prev.price },
778
+ curr: { time: d.curr.time, orderId: d.curr.orderId, price: d.curr.price },
779
+ runtimePivot: d.pivot,
780
+ refusalsInRange: d.refusalsInRange,
781
+ priceDeltaPct: d.priceDeltaPct,
782
+ })),
566
783
  violations: violations.map(v => ({
567
784
  pair: `${assetSymbol(v.prev.baseAsset)}/${assetSymbol(v.prev.quoteAsset)}`,
568
785
  pairIds: { base: v.prev.baseAsset, quote: v.prev.quoteAsset },
@@ -651,16 +868,49 @@ async function main() {
651
868
  console.log(` Aggregated into ${orders.length} order epoch(s) (partial fills collapsed; repriced orders kept separate)`);
652
869
  items = orders;
653
870
  }
654
- const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair);
871
+ const { violations: strictCandidatesList, checkedTransitions } = detectViolations(items, opts.includeCrossPair, incrementPercent);
872
+ // Policy-aware mirror: re-judge strict candidates against the pivot the
873
+ // runtime held at each order's gate. Default on; --strict skips it.
874
+ let violations = strictCandidatesList;
875
+ let divergences = [];
876
+ let mirrorMode = 'strict';
877
+ let runtimeLogPath = null;
878
+ let logError = null;
879
+ if (!opts.strict) {
880
+ const defaultLog = botMeta && typeof botMeta.name === 'string' && botMeta.name
881
+ ? path.resolve('profiles/logs', `${botMeta.name}.log`)
882
+ : null;
883
+ runtimeLogPath = opts.runtimeLog ?? defaultLog;
884
+ if (runtimeLogPath) {
885
+ if (fs.existsSync(runtimeLogPath)) {
886
+ const mirror = applyRuntimeMirror(strictCandidatesList, runtimeLogPath, incrementPercent);
887
+ violations = mirror.kept;
888
+ divergences = mirror.divergences;
889
+ logError = mirror.logError;
890
+ if (mirror.index) {
891
+ mirrorMode = 'policy-aware';
892
+ console.log(` Runtime mirror: ${mirror.index.observations.length} pivot observation(s), ${mirror.index.refusals.length} refusal(s), ${mirror.index.allowances.length} allowance(s) from ${runtimeLogPath}`);
893
+ }
894
+ else {
895
+ console.log(` Runtime mirror unavailable (${logError}) — falling back to the strict all-fills check`);
896
+ runtimeLogPath = null;
897
+ }
898
+ }
899
+ else {
900
+ console.log(` Runtime mirror unavailable (log not found: ${runtimeLogPath}) — falling back to the strict all-fills check`);
901
+ runtimeLogPath = null;
902
+ }
903
+ }
904
+ }
655
905
  const ordersForReport = opts.perFill ? null : items;
656
- printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, String(opts.botKey), accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
906
+ printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, String(opts.botKey), accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte, divergences, mirrorMode, runtimeLogPath, logError, strictCandidatesList.length);
657
907
  if (opts.json)
658
- exportJson(opts.json, violations, trades, label, String(opts.botKey), accountId, incrementPercent);
908
+ exportJson(opts.json, violations, trades, label, String(opts.botKey), accountId, incrementPercent, divergences, mirrorMode, runtimeLogPath);
659
909
  if (opts.csv)
660
910
  exportCsv(opts.csv, violations);
661
911
  process.exit(violations.length > 0 ? 2 : 0);
662
912
  }
663
- export { isLastFillGuardBlocked, classifyFills };
913
+ export { isLastFillGuardBlocked, detectViolations, applyRuntimeMirror, classifyFills };
664
914
  if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
665
915
  main().catch(e => {
666
916
  console.error('\n[fatal]', getErrorMessage(e));
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env node
2
+ export interface PivotObservation {
3
+ t: number;
4
+ price: number;
5
+ type: string;
6
+ src: 'fill-pivot' | 'mode' | 'final-gate' | 'rearm';
7
+ }
8
+ export interface RefusalEvent {
9
+ t: number;
10
+ price: number;
11
+ type: string;
12
+ }
13
+ export interface PlacementEvent {
14
+ t: number;
15
+ orderId: string;
16
+ price: number;
17
+ kind: 'placed' | 'plan-action';
18
+ }
19
+ export interface AllowanceEvent {
20
+ t: number;
21
+ direction: string;
22
+ price: number;
23
+ }
24
+ export interface RuntimeLogIndex {
25
+ observations: PivotObservation[];
26
+ refusals: RefusalEvent[];
27
+ placements: Map<string, PlacementEvent[]>;
28
+ allowances: AllowanceEvent[];
29
+ }
30
+ export interface TransitionCandidate {
31
+ prevTime: string;
32
+ currTime: string;
33
+ prevPrice: number;
34
+ currPrice: number;
35
+ direction: 'buy' | 'sell';
36
+ currOrderId: string;
37
+ }
38
+ export interface TransitionVerdict {
39
+ verdict: 'policy-divergence' | 'violation' | 'unverifiable';
40
+ reason: string;
41
+ /** The runtime pivot used at the gate (null when unverifiable). */
42
+ pivot: {
43
+ price: number;
44
+ type: string;
45
+ t: number;
46
+ } | null;
47
+ /** Refusals logged between the two fills (sweep-policy context). */
48
+ refusalsInRange: number;
49
+ }
50
+ /** How far after a placement event the judging gate may log its pivot. */
51
+ export declare const PIVOT_LOOKAHEAD_MS = 120000;
52
+ /** How wide an allowance match may drift around the gate pivot. */
53
+ export declare const ALLOWANCE_WINDOW_MS = 120000;
54
+ /**
55
+ * Kibana truncates fill timestamps to the second while the runtime logs the
56
+ * order's Placed/Plan-action line a few hundred ms later, so a naive
57
+ * `placement.t <= fill.t` test can miss the anchor. An order cannot fill
58
+ * before it exists, so placements slightly AFTER the (truncated) fill
59
+ * timestamp are still valid anchors.
60
+ */
61
+ export declare const PLACEMENT_AFTER_FILL_MS = 5000;
62
+ /**
63
+ * Parse a bot log into the runtime pivot index. Unknown lines are skipped;
64
+ * the parser is deliberately tolerant of level/tag variation because it must
65
+ * work on rotated and filtered logs too.
66
+ */
67
+ export declare function parseRuntimeLog(text: string): RuntimeLogIndex;
68
+ /** Latest pivot observation at or before `t` (binary search), or null. */
69
+ export declare function pivotAtOrBefore(observations: PivotObservation[], t: number): PivotObservation | null;
70
+ /** First pivot observation at or after `t`, or null when none within the window. */
71
+ export declare function pivotAtOrAfter(observations: PivotObservation[], t: number, windowMs?: number): PivotObservation | null;
72
+ /**
73
+ * Classify one strict-mode candidate transition against the pivot the runtime
74
+ * held when `currOrderId` was last priced. Verdicts and the fail direction are
75
+ * documented in the module header: anything unprovable stays a violation.
76
+ */
77
+ export declare function classifyTransition(cand: TransitionCandidate, index: RuntimeLogIndex): TransitionVerdict;
78
+ //# sourceMappingURL=pivot_timeline.d.ts.map