dexbot 1.7.1 → 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.
- package/CHANGELOG.md +52 -0
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/grid_correction_check.d.ts +60 -1
- package/dist/analysis/grid_correction_check.js +268 -18
- package/dist/analysis/pivot_timeline.d.ts +78 -0
- package/dist/analysis/pivot_timeline.js +360 -0
- package/dist/market_adapter/utils/file_lock.js +16 -4
- package/dist/modules/account_bots.d.ts +7 -0
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/bot_defaults.js +6 -1
- package/dist/modules/constants.d.ts +14 -0
- package/dist/modules/constants.js +82 -2
- package/dist/modules/dexbot_class.d.ts +39 -0
- package/dist/modules/dexbot_class.js +86 -1
- package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
- package/dist/modules/dexbot_cow_runtime.js +299 -75
- package/dist/modules/dexbot_maintenance_runtime.d.ts +32 -2
- package/dist/modules/dexbot_maintenance_runtime.js +196 -16
- package/dist/modules/dexbot_state_recovery.js +15 -1
- package/dist/modules/launcher/instance_lock.d.ts +27 -0
- package/dist/modules/launcher/instance_lock.js +131 -0
- package/dist/modules/node_flap_score.d.ts +6 -6
- package/dist/modules/node_flap_score.js +6 -6
- package/dist/modules/order/accounting.d.ts +9 -4
- package/dist/modules/order/accounting.js +89 -26
- package/dist/modules/order/async_lock.d.ts +7 -1
- package/dist/modules/order/async_lock.js +7 -1
- package/dist/modules/order/export.js +25 -18
- package/dist/modules/order/fill_ledger.d.ts +99 -0
- package/dist/modules/order/fill_ledger.js +103 -0
- package/dist/modules/order/grid.d.ts +94 -18
- package/dist/modules/order/grid.js +247 -75
- package/dist/modules/order/grid_reconcile_internal.js +16 -4
- package/dist/modules/order/index.d.ts +29 -6
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.js +3 -3
- package/dist/modules/order/manager.d.ts +36 -24
- package/dist/modules/order/manager.js +159 -39
- package/dist/modules/order/placement_lock.d.ts +30 -0
- package/dist/modules/order/placement_lock.js +48 -0
- package/dist/modules/order/sync_engine.d.ts +66 -118
- package/dist/modules/order/sync_engine.js +118 -162
- package/dist/modules/order/utils/math.d.ts +7 -3
- package/dist/modules/order/utils/math.js +7 -3
- package/dist/modules/order/utils/order.d.ts +79 -42
- package/dist/modules/order/utils/order.js +183 -86
- package/dist/modules/order/utils/system.d.ts +192 -8
- package/dist/modules/order/utils/system.js +534 -34
- package/dist/modules/paths.d.ts +1 -0
- package/dist/modules/paths.js +1 -0
- package/dist/modules/timing_policy.js +4 -2
- package/dist/modules/types.d.ts +49 -27
- package/dist/pm2.js +126 -0
- package/dist/unlock.js +26 -1
- package/docs/COW_INVARIANTS.md +5 -1
- package/docs/DEXBOT_COMPARISON.md +5 -5
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_RECONCILE.md +3 -3
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +192 -31
- package/docs/README.md +1 -1
- package/docs/architecture.md +26 -8
- package/modules/README.md +4 -0
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,58 @@
|
|
|
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
|
+
|
|
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
|
|
30
|
+
|
|
31
|
+
### 2026-11-04
|
|
32
|
+
|
|
33
|
+
- **Feat(order)**: give the fill pipeline one written contract and make its blocking decision fail-closed — the fill path's failures were not missing safeguards but one question answered in several places, so a "wait, then guess" was added wherever the answers disagreed. `docs/FILL_PIPELINE.md` now names the six stages (ingest, ledger, pivot, plan, lease, commit/observe), the four fill states, one owner per question and `INV-FILL-001..007`, with a ratchet test over the ten `_processFillsWithBatching` call sites, the two pivot writers, the three boundary-budget files and the nine dedupe references. `hasUnsettledFills()` peeked four raw fields and returned `{unsettled:false}` on ANY throw — a fail-OPEN answer in a fail-closed system, which is how a grid was updated from a stale master; `resolveGridUpdateBlockers()` now returns eight closed codes and `readFillPipelineState()` is the single field reader (reporting `ok:false`, i.e. unknown-blocker, instead of "settled"), so the prose reason and the codes cannot disagree. Broadcast liveness composes through `getLivePendingBroadcasts` (new read-only `gc:false` mode, so a predicate cannot GC the pending set), the region through `isPlacementActive`, the rebuild through the manager flag; only `unknown-blocker` escalates, after `GRID_BLOCKED_ESCALATE_CYCLES` consecutive attempts (a cycle counter, not a timing window). Behavioral change: the targeted-drift gate now defers on ANY blocker, not only the fill codes — it is a chain-mutating reconcile and the old condition could escalate on an unreadable probe and still reconcile in the same tick. Errors now surface as a stalled-but-bounded grid update rather than a grid built from stale state.
|
|
34
|
+
|
|
35
|
+
- **Feat(order)**: one fill identity — `modules/order/fill_ledger.ts` owns `fillKeyOf` (`buildFillKey` stays as an alias) and `resolveTradedSide`, and `isFillBooked` exposes the persisted store's membership without claiming it (booking still belongs to the store). It is wired into the three former copies of the pays-asset map (`_computeFillContext`, `attributeUnmatchedFillToGrid`, the queued pivot refresh), with the SPREAD price fallback left with the caller that owns the ladder. Docs: `INV-RECON-006` now records the chain-observed typeMismatch exemption, `INV-SYNC-008` records that the pays mapping has one implementation and that `slot.type` is the ACCOUNTING side, not rail identity.
|
|
36
|
+
|
|
37
|
+
- **Fix(order)**: claim the fill key at credit time and drop the duplicate amount channel — `processFillAccounting` wrote the store tracker only AFTER a successful persist flush, so in the window between "key queued" and "flush done" a second event with the same key passed the duplicate check (the only protection was the bot-level 5 s claim lease, absent in a bare manager); "credited" and "tracked" could disagree, which is the family that produced the double-released size and the phantom residual. The key is now claimed in the store tracker BEFORE `_applyBalanceAdjustments` and before the pass-1 marker is consumed, and released on every failure path, so "credited => tracked" and "not credited => no claim" hold; `_applyBalanceAdjustments` is ALL-OR-NOTHING (an applied prefix is reversed before the error propagates) so the released claim's retry cannot apply that prefix twice; `_isNewFillKey` asks the store first, so a booked key is refused at ingest even after its lease expired instead of after a `FILL DETECTED` log and queue work. The boolean half of the applied amount (`alreadyAppliedChainSize` / `__chainSizeAlreadyApplied` and its dead consume wrapper) is REMOVED rather than asserted: the aggregated path read it off the LAST group entry only, which is exactly the phantom-residual bug — one channel remains, the amount. `FILL_DEDUPE_WINDOW_MS` stays, re-documented as a CLAIM LEASE: claims restored from the crash snapshot are the one case where nobody knows whether the credit happened, and blocking them forever loses a fill. `docs/FILL_PIPELINE_PLAN.md` is folded into `docs/FILL_PIPELINE.md` and removed. Risk: a failure inside the credit now releases the claim and the fill is retried; the all-or-nothing rollback is what makes that retry safe. No order sizing, boundary or strategy behaviour changed.
|
|
38
|
+
|
|
39
|
+
- **Fix(order)**: make the fill claim a real single winner and delete the second grace-stamp writer — the pre-credit duplicate check ran before `persist()` awaited, so two concurrent `processFillAccounting` calls could both pass it and both credit (reproduced: 998 base / 100005 quote for one fill); the claim is now a synchronous check-and-set with no await in between, and the loser returns duplicate without discarding the queued write (keyed by fill key, it belongs to the winner) and without being counted as a booking. The claim, the duplicate gate and rollback now use ONE map (the store tracker when the store exists, the manager tracker otherwise); in a wired bot they are the same map, but a split fixture would otherwise claim a key the ingest check cannot see. `recordOrderPlacement` is deleted: it had no production caller, and its "writes through the same facade" comment was false — it wrote `_placedAt` directly, which `isFreshlyPlacedOrder` ignores whenever `getLifecycle` exists. The offline exporter now derives BUY/SELL through the ledger's `resolveTradedSide` instead of its own copy of the pays-asset mapping, keeping its stricter "both sides must be this pair" guard. Also corrects retention wording: a booked key is refused while retained regardless of age; `FILL_RECORD_RETENTION_MS` bounds retention, it is not an expiry that re-allows a credit.
|
|
40
|
+
|
|
41
|
+
- **Fix(order)**: release leaked broadcast regions and never park a chain-observed wrong-side cancel — the COW batch executor called `startBroadcasting()` before building ops, but only the inner broadcast `try/finally` released the refcount, so every early return in between (all CREATEs skipped by the last-fill/size guards, fund validation, stale-plan re-plan, single-flight/placement aborts) leaked the region and froze the fill consumer until the 120 s stale-flag watchdog; the delayed backlog was then replayed chunk by chunk against a stale boundary and the bot re-placed sells below levels it had already sold. The region is now tracked per frame and released from the inner finally, the catch and the outer finally (idempotently, so a second raw `stopBroadcasting()` cannot underflow another holder) and released before the best-effort cleanup, and a chain-observed typeMismatch is exempt from the 15-minute fresh-placement grace because a wrong-side order is known-wrong — letting it rest misclassifies its next fill (phantom zero-size fill, dust cancel, re-buy at the fill level); regular surplus cancels keep the grace. A `typeMismatch` the pre-batch drain did not resolve (deferred by an active region or failed) is no longer parked either, while a plan-shaped `reason='type-mismatch'` action still waits, because it only proves `master != target` — the stale-target lag the grace exists for.
|
|
42
|
+
|
|
43
|
+
- **Fix(order)**: derive the fill side from the paid asset — a slot can be retyped (BUY↔SELL) before its resting chain order is corrected, and `_computeFillContext()` trusted `matchedGridOrder.type`, so a real SELL fill on a BUY-typed slot converted the paid base amount with quote precision: `filledAmount` became 0, the slot was treated as partially filled and the bot re-bought at the fill level (2026-11-04 incident). The side is now resolved from the fill's paid asset for every slot type (pays quote = BUY, pays base = SELL), which also selects the correct size asset (BUY=quote, SELL=base) so `filledAmount`/precision stay dimensionally consistent with the order; SPREAD without a usable pays asset keeps the price-vs-`startPrice` fallback, non-SPREAD without one keeps the slot type, and the same undefined/undefined identity collision is guarded in the unmatched-fill attribution and the queued pivot refresh. `fillProcessing.COALESCE_BACKLOG_REPLAY` is rolled out for the configured bots (profile data, ignored by git); the code default stays OFF. Risk: a slot whose fill carries no pays asset id keeps the previous side inference.
|
|
44
|
+
|
|
45
|
+
- **Fix(order)**: repair a wrong-side slot on rail geometry, not on the stored label — a partial fill stores the traded side into the slot so `size` stays dimensionally consistent for accounting/`recalculateFunds`, which made a queued typeMismatch entry look "repaired" and dropped the residual cancel, leaving the order on the wrong rail. The correction validators now treat a level as repaired only when the stored type AND its rail geometry (index vs boundary, including the gap band) agree with the chain side; unknown geometry keeps the old stored-type check so a rail is never invented. Covered by the cancel-guard, geometry and fill-side edge-case suites (`test_fresh_placement_cancel_grace_paths`, `test_correction_queue_staleness`, `test_live_geometry_provenance`, `test_sync_fill_history_batch`), each mutation-checked.
|
|
46
|
+
|
|
47
|
+
- **Fix(grid)**: anchor a rebuilt or reloaded boundary to the last fill — a rebuild/reload derived the band from the live market center while the LAST-FILL-GUARD pivot survived; when the center sat ahead of the pivot, the startup picker skipped the top buy levels (at/through the fill), filled the same-side window lower and left the first ask at the old `sellStart`, so the realized spread was two grid steps wider than target with no fill reason for the extra width (a live market-pair bot: boundary 159 after a BUY at new-ladder slot 158, realized 2.12% vs the 1.5% target). The existing fill re-anchor now runs on both the rebuild and the load path (`BUY fill at f => boundary <= f - 1`, `SELL fill at f => boundary >= f - gapSlots`) after the pivot is re-armed/restored and before reconcile/re-type, and `applyRebuildFillAnchor()` re-types the rails atomically for the anchored boundary so the counter SELL at `f + gapSlots` is a rail order and the boundary published to runtime consumers matches the slot roles. `loadGrid` previously changed only a local boundary while the persisted value stayed in the manager — fixed. The free-fund spread correction did not run in the incident because no maintenance tick followed bootstrap; the reconcile now owns the first window.
|
|
48
|
+
|
|
49
|
+
- **Fix(spread)**: rotate into orphaned rail slots when funds are fully reserved — a fill-anchored boundary move can leave the two counter levels as orphaned VIRTUAL rail slots (e.g. the old sell window starts two levels above the new `sellStart`), and the spread correction's funding probe read `availableFund=0` because the virtual tail reserved exactly the whole free balance (the chain-truth budget deliberately treats virtual == chainFree equality as a real constraint). Only the no-new-commitment rotation path could repair that, but it was restricted to boundary-promoted gap slots — so a fully allocated rail stayed wide forever even though the far resting orders could have moved into the window edge without any new funds. The rotation source/destination pairing now covers every unfunded tightening candidate, while boundary derivation stays restricted to genuinely promoted destinations so an in-rail orphan rotation cannot invent a boundary move. Pinned by `PF-031` (SELL orphan rotation with virtual == free), `PF-032` (fund-selected BUY blocked by the last fill falls back to the SELL orphan rotation) and `PF-033` (BUY mirror).
|
|
50
|
+
|
|
51
|
+
- **Fix(order)**: make the grid-blocked escalation counter truly consecutive — `GRID_BLOCKED_ESCALATE_CYCLES` is documented as N *consecutive* unreadable cycles, but `noteGridUpdateBlockers` only cleared the counter on a healthy call, and its only caller (the targeted-drift gate) returns before evaluating the gate when `getTargetedSyncReason()` is null; a counter parked at the limit therefore survived an arbitrarily long trigger-less stretch and the first unreadable cycle afterwards fired a structural resync instead of waiting the full window. The trigger-less early return now clears the counter (guarded on the manager), the read-only/GC asymmetry in `getLivePendingBroadcasts` is documented and pinned (a `gc:false` probe keeps an entry the write path would drop — the intended fail-closed answer), and `_gridUpdateBlockedCycles` is declared on `OrderManager`/`OrderManagerLike` so the single writer/reader pair is typed.
|
|
52
|
+
|
|
53
|
+
- **Test(scripts)**: actually run the live suite and ship the cred stub fixture — `test:live` scoped `RUN_LIVE_BITSHARES_TESTS=1` to `npm run build` only (`VAR=x a && b` exports the variable to `a`, not `b`), so `run-tests.js` never saw it and silently skipped all 14 live files (`skippedLive 14`); the env now sits on the runner command (`skippedLive 0`, the live set really runs). `build:tests` also never copied `tests/helpers/foreign_cred_stub.js`, so `test_unlock_foreign_cred_daemon_live` always failed with `ENOENT`; it is copied with the other plain-JS helpers.
|
|
54
|
+
|
|
55
|
+
- **Docs**: consolidate the fill-pipeline documents and resync drifted module comments — `docs/FILL_PIPELINE.md` is now the single fill document (contract, P0–P2 status by commit, the P3–P5 remainder with gates and stop conditions, the accepted decision register D10–D12, regression canaries, implementation log), `ORDER_LIFECYCLE` records that it shipped in v1.7.1 and that the five legacy structures are facade views, `ORDER_ENGINE_POST_1.0_RETROSPECTIVE` marks the v1.7.1 commits released and adds the post-1.7.1 rows, and the fill-pipeline ratchet pins that the `typeMismatch` validator must keep deriving rail geometry rather than trusting `slot.type` (baseline `bc20d574`). A comment-only sweep of `modules/` fixed 10 orphaned/superseded JSDoc blocks, comments naming symbols that do not exist, descriptions contradicting the code (the sync-engine header still described the pre-genesis PASS 2), six drifted TOC inventories (math 78→80, system 43→52 plus a missing fill-pipeline/last-fill-guard section, order 76→82, grid 34 + 3, accounting 26→27, sync_engine 12→14), 30 JSDoc `import('./types')` references pointing at a non-existent file and a non-existent interface, and `@param` lines still using pre-underscore parameter names; `modules/README.md` gains `outcome.ts`, `timing_policy.ts` and the missing `order/` entries. Full suite: 358/358 files (`npm test`), `npm run test:live` 366 pass (5 diagnostics need a configured account); `typecheck`, `typecheck:analysis`, `check:any`, `verify:browser-bundle` (44/44) and the timing-policy audit clean.
|
|
56
|
+
|
|
5
57
|
## [1.7.1] - 2026-11-04 - One Existence Record per Slot, Placement-Region Hardening, Forced-Retreat Gap Evacuation, Fee-Adjusted Pool Depth, Stability-Ranked Nodes
|
|
6
58
|
|
|
7
59
|
### 2026-11-04
|
package/claw/package.json
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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));
|