@reefclaw/openclaw-plugin 0.1.0

package/live/user-data-stream-controller.js

@@ -0,0 +1,579 @@
+// UserDataStreamController — owns the WS + store + snapshot lifecycle
+// behind the `userDataStream.mode` feature flag.
+//
+// Responsibility separation (Phase 1/2):
+//   - `start()` mints a listenKey, opens the WS, takes a REST snapshot, seeds
+//     the store, and routes WS events into the store.
+//   - In `shadow` mode, a periodic 60s REST truth-check runs; diffs are logged
+//     but REST remains authoritative for `LiveAdapter` reads.
+//   - In `observe` / `enforce` (Phase 2–3, not yet activated on prod), the
+//     store becomes authoritative — but the wiring in LiveAdapter is what
+//     flips the read path. The controller just keeps the store fresh.
+//
+// The controller deliberately keeps NO business logic — it orchestrates the
+// store + stream + REST client. Policy (when to auto-pause on repeated drift,
+// when to alert) lives one level up in LiveAdapter + dashboards.
+import { EventEmitter } from 'node:events';
+import { UserDataStream } from './user-data-stream.js';
+import { LiveStateStore } from './live-state-store.js';
+import { defaultWebSocketFactory, userDataWsBaseUrl } from './user-data-stream-ws.js';
+import { logger, formatError } from '../logger.js';
+import { WsIngest } from '../ingest/ws-ingest.js';
+import { RestGapFiller } from '../ingest/rest-gap-filler.js';
+import { UserDataActiveProbe } from './user-data-active-probe.js';
+/**
+ * Rewrite `balance.total[asset]` from CCXT's marginBalance-equivalent (wallet
+ * + unrealizedProfit for Binance Futures) to raw walletBalance only, so the
+ * REST snapshot aligns with what the WS ACCOUNT_UPDATE frames deliver. The
+ * raw walletBalance field lives under `balance.info.assets[i].walletBalance`
+ * — an array of per-asset records Binance Futures always returns alongside
+ * the top-level totals. Exported for unit testing.
+ *
+ * Falls back to the unmodified balance if `info.assets` is missing or
+ * malformed (e.g. mock responses in unit tests without the info envelope).
+ * Only `total` is rewritten; `free` and `used` are left untouched because
+ * the WS store computes them separately from position-lock state.
+ */
+export function normalizeBinanceFuturesBalance(balance) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const assets = balance?.info?.assets;
+    if (!Array.isArray(assets))
+        return balance;
+    const walletByAsset = {};
+    for (const a of assets) {
+        if (!a || typeof a.asset !== 'string')
+            continue;
+        const wb = parseFloat(String(a.walletBalance));
+        if (Number.isFinite(wb))
+            walletByAsset[a.asset] = wb;
+    }
+    if (Object.keys(walletByAsset).length === 0)
+        return balance;
+    const newTotal = { ...(balance.total ?? {}) };
+    for (const [asset, wb] of Object.entries(walletByAsset)) {
+        newTotal[asset] = wb;
+    }
+    return { ...balance, total: newTotal };
+}
+const TAG = 'user-data-stream-ctl';
+/**
+ * Thrown by `buildSnapshot` when ANY of the three REST fetches returned
+ * `null` — i.e. the fetch FAILED (Binance 429 / weight-paced / transient
+ * network), state is UNKNOWN. It does NOT mean "the account is flat / has no
+ * orders". `LiveStateStore.applySnapshot` replaces positions + orders +
+ * balances WHOLESALE, so applying a snapshot built from a failed fetch would
+ * wipe still-live positions and bracket SL/TP from the store — which is the
+ * AUTHORITATIVE read path in observe/enforce mode — blinding the agent into
+ * the documented phantom-naked spiral.
+ *
+ * Subclass of `Error` so the existing `.catch()` sites absorb it unchanged;
+ * callers detect the type to skip the apply, leave the store intact, and let
+ * WS deltas + the next reconnect/resync repair state. Same null≠empty rule as
+ * `getOpenOrders` / `getPositions` / `closePosition` / the bracket reconciler.
+ */
+export class UntrustedSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UntrustedSnapshotError';
+    }
+}
+const REAL_CTL_TIMERS = {
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (h) => clearInterval(h),
+    now: () => Date.now(),
+};
+export class UserDataStreamController extends EventEmitter {
+    mode;
+    api;
+    stream;
+    store;
+    truthCheckIntervalMs;
+    staleStoreThresholdMs;
+    timers;
+    truthCheckTimer = null;
+    algoRefreshTimer = null;
+    reconnectRateTimer = null;
+    algoRefreshMs;
+    wsIngest;
+    restGapFiller;
+    activeProbe;
+    /** Count of stale-forced + other reconnects in the current hourly window.
+     *  Checked every hour; a spike above RECONNECT_RATE_ALERT_THRESHOLD logs
+     *  a WARN so operator can spot Binance-side trouble or network flaps. */
+    reconnectCountThisHour = 0;
+    running = false;
+    snapshotInFlight = false;
+    /** Serialises snapshot applies so WS events don't race with a snapshot
+     *  we're in the middle of fetching. WS events that arrive during a
+     *  snapshot are buffered here and drained after apply. */
+    bufferedDuringSnapshot = [];
+    consecutiveMajorDrifts = 0;
+    constructor(api, options) {
+        super();
+        this.api = api;
+        this.mode = options.mode;
+        this.store = options.store ?? new LiveStateStore();
+        this.truthCheckIntervalMs = options.truthCheckIntervalMs ?? 60_000;
+        this.algoRefreshMs = options.tunables.algoRefreshMs;
+        // Reuse the dead-socket watchdog's calibrated threshold as the
+        // store-staleness bound for isStoreTrusted() — see that method.
+        this.staleStoreThresholdMs = options.tunables.staleEventWatchdogMs;
+        this.timers = {
+            setInterval: options.timers?.setInterval ?? REAL_CTL_TIMERS.setInterval,
+            clearInterval: options.timers?.clearInterval ?? REAL_CTL_TIMERS.clearInterval,
+            now: options.timers?.now ?? REAL_CTL_TIMERS.now,
+        };
+        this.stream = options.stream ?? new UserDataStream(api, this.buildStreamOptions(options));
+        this.attachStreamHandlers();
+        // Active probe — proactive REST check that catches "WS silently stopped
+        // delivering" before the staleness watchdog. Disabled when intervalMs=0.
+        // Construction is side-effect-free; subscription happens in start().
+        const probeIntervalMs = options.tunables.activeProbeIntervalMs;
+        this.activeProbe = probeIntervalMs > 0
+            ? new UserDataActiveProbe({
+                api: this.api,
+                stream: this.stream,
+                store: this.store,
+                intervalMs: probeIntervalMs,
+            })
+            : null;
+        // WsIngest is constructed eagerly when a tradeIngest config is supplied,
+        // but only start()-ed inside the controller's start() — and only when
+        // mode≠'off'.  Construction is side-effect-free; subscription happens on
+        // start().  See TRADE_AUDIT_TRAIL_PLAN.md Phase 1.
+        this.wsIngest = options.tradeIngest
+            ? new WsIngest({
+                stream: this.stream,
+                client: options.tradeIngest.client,
+                userId: options.tradeIngest.userId,
+                exchange: options.tradeIngest.exchange,
+                autoCapture: options.autoCapture,
+            })
+            : null;
+        // REST gap-filler — Phase 2 of TRADE_AUDIT_TRAIL_PLAN. Runs alongside
+        // WsIngest whenever dbWrite is active. On every reconnect (stale-forced
+        // or otherwise), queries /fapi/v1/userTrades for every known symbol
+        // and POSTs any missing fills with source='rest_reconcile'. The webapp
+        // ingest endpoint dedupes on (exchange, exchangeTradeId), so WS-already-
+        // delivered fills stay recorded as source='ws' (ON CONFLICT DO NOTHING,
+        // not last-writer-wins — see shared/src/fills.ts). Required for mode
+        // advancement to observe/enforce: in those modes WS is authoritative
+        // for the audit trail, and fills during reconnect blind windows (5-20s)
+        // would otherwise be silently missing from the trades table.
+        this.restGapFiller = options.tradeIngest
+            ? new RestGapFiller({
+                api: this.api,
+                stream: this.stream,
+                store: this.store,
+                client: options.tradeIngest.client,
+                userId: options.tradeIngest.userId,
+                exchange: options.tradeIngest.exchange,
+                touchedSymbolsStore: options.tradeIngest.touchedSymbolsStore,
+                now: () => this.timers.now(),
+            })
+            : null;
+    }
+    getStore() {
+        return this.store;
+    }
+    getStream() {
+        return this.stream;
+    }
+    /** True when the in-memory store is safe to serve as the authoritative
+     *  source for positions/orders reads. Two independent conditions, BOTH
+     *  required — each guards a distinct failure in the null≠empty class
+     *  (same class as the getOpenOrders / getPositions / closePosition /
+     *  bracket-reconciler / UntrustedSnapshotError rules):
+     *
+     *  (1) **Seeded.** A trusted REST snapshot has run at least once
+     *      (`lastSnapshotAt !== null`). False during startup before the
+     *      `connected` handler's initial snapshot lands and the gap after
+     *      `reset()`. An unseeded `[]` is indistinguishable from "no
+     *      positions/orders" and would trip naked-bracket / orphan-cancel
+     *      paths against real exchange state.
+     *
+     *  (2) **Fresh.** We've received SOME incoming frame within
+     *      `staleStoreThresholdMs` — the SAME calibrated threshold
+     *      (`staleEventWatchdogMs`, default 6 min) and the SAME signal
+     *      (`lastFrameAt`, any frame incl. Binance's 3-min server pings) the
+     *      dead-socket watchdog itself uses to declare the socket dead.
+     *      Beyond it the watchdog is already forcing a reconnect; serving a
+     *      seeded-but-stale store as authoritative there would present stale
+     *      state as truth on a destructive-action-gating read — the residual
+     *      a reviewer flagged. Deliberately NOT a bare `isConnected()` check:
+     *      a brief reconnect (listenKey rotation ~25 min, 1 s→60 s backoff)
+     *      keeps `lastFrameAt` recent, so the common case is NOT pushed onto
+     *      the weight-heavy / rate-limit-poisoned REST path — that would just
+     *      trade one failure in this class for another. When the reconnect +
+     *      resync completes, `lastFrameAt` refreshes and the store is trusted
+     *      again. `lastFrameAt === null` (seeded but never a frame — an odd
+     *      state) is conservatively treated as untrusted. */
+    isStoreTrusted() {
+        if (this.store.getHealth().lastSnapshotAt === null)
+            return false;
+        const { lastFrameAt } = this.stream.getHealth();
+        if (lastFrameAt === null)
+            return false;
+        return this.timers.now() - lastFrameAt <= this.staleStoreThresholdMs;
+    }
+    /** Start the stream + run the initial REST snapshot + seed the store.
+     *  No-op if mode is 'off'. Throws if already running. */
+    async start() {
+        if (this.mode === 'off') {
+            logger.info(TAG, 'mode=off — controller not started');
+            return;
+        }
+        if (this.running) {
+            logger.warn(TAG, 'start() called while already running — ignored');
+            return;
+        }
+        this.running = true;
+        logger.info(TAG, `starting in mode=${this.mode}${this.wsIngest ? ' + dbWrite=on' : ''}`);
+        await this.stream.start();
+        // 'connected' handler will run the initial snapshot + seed.
+        if (this.mode === 'shadow' || this.mode === 'observe' || this.mode === 'enforce') {
+            this.startTruthCheckLoop();
+            this.startAlgoRefreshLoop();
+            this.startReconnectRateMonitor();
+        }
+        // Audit-trail WS ingest — opt-in via tradeIngest config.  Subscribes to
+        // the stream's orderUpdate event, which is already wired for store apply.
+        // Both listeners coexist; the ingest one is filter+forward only, no
+        // mutation of the store.
+        if (this.wsIngest) {
+            this.wsIngest.start();
+        }
+        // REST gap-filler — closes the audit-trail hole opened by every WS
+        // reconnect blind window. Also opt-in via tradeIngest (same gate as
+        // WsIngest — either both run or neither, since they write to the same
+        // audit table with complementary provenance).
+        if (this.restGapFiller) {
+            this.restGapFiller.start();
+        }
+        // Active probe — proactive REST detector for silent-stream events. Runs in
+        // every mode that the stream itself runs in (shadow, observe, enforce);
+        // there is no audit-trail dependency. Independent of dbWrite.
+        if (this.activeProbe) {
+            this.activeProbe.start();
+        }
+    }
+    /** Graceful shutdown. */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.stopTruthCheckLoop();
+        this.stopAlgoRefreshLoop();
+        this.stopReconnectRateMonitor();
+        if (this.wsIngest)
+            this.wsIngest.stop();
+        if (this.restGapFiller)
+            this.restGapFiller.stop();
+        if (this.activeProbe)
+            this.activeProbe.stop();
+        try {
+            await this.stream.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `stream.stop failed: ${formatError(err)}`);
+        }
+        logger.info(TAG, 'stopped');
+    }
+    /** Force a full snapshot + re-seed. Used by operator tools for manual resync. */
+    async forceResync(cause) {
+        logger.warn(TAG, `forced resync: ${cause}`);
+        await this.takeAndApplySnapshot();
+        this.emit('forcedResync', cause);
+    }
+    // ---- Internal ----
+    buildStreamOptions(options) {
+        return {
+            wsBaseUrl: userDataWsBaseUrl(options.testnet),
+            webSocketFactory: defaultWebSocketFactory,
+            listenKey: {
+                refreshIntervalMs: options.tunables.listenKeyRefreshMs,
+            },
+            reconnectBaseMs: options.tunables.reconnectBaseMs,
+            reconnectCapMs: options.tunables.reconnectCapMs,
+            // Single watchdog threshold — the per-position "active" specialisation
+            // was removed in 2026-04-25's ping-aware refactor. Empirical false-positive
+            // rate was 99% (203 fires/day vs 2 true positives) because the 90s active
+            // threshold was below Binance's 180s server-ping interval, and the
+            // watchdog only counted message frames as liveness. The active REST probe
+            // (60s `fetchMyTrades` per open-position symbol) is the canonical
+            // "events stopped arriving on a position" detector — it fires within ~60s
+            // of any missed fill and was already running alongside the broken watchdog.
+            staleEventWatchdogMs: options.tunables.staleEventWatchdogMs,
+        };
+    }
+    attachStreamHandlers() {
+        this.stream.on('connected', () => {
+            void this.takeAndApplySnapshot().catch((err) => {
+                if (err instanceof UntrustedSnapshotError) {
+                    logger.warn(TAG, `initial snapshot skipped (store intact): ${err.message}`);
+                }
+                else {
+                    logger.error(TAG, `initial snapshot failed: ${formatError(err)}`);
+                }
+            });
+        });
+        this.stream.on('resyncRequired', (cause) => {
+            void this.takeAndApplySnapshot().then(() => {
+                this.emit('forcedResync', cause);
+            }).catch((err) => {
+                if (err instanceof UntrustedSnapshotError) {
+                    // Did NOT resync — do not emit forcedResync. WS deltas keep the
+                    // store fresh; the next reconnect/resync retries.
+                    logger.warn(TAG, `resync snapshot skipped (store intact, will retry): ${err.message}`);
+                }
+                else {
+                    logger.error(TAG, `resync snapshot failed: ${formatError(err)}`);
+                }
+            });
+        });
+        this.stream.on('accountUpdate', (ev) => {
+            if (this.snapshotInFlight) {
+                this.bufferedDuringSnapshot.push(() => this.store.applyAccountUpdate(ev));
+                return;
+            }
+            this.store.applyAccountUpdate(ev);
+        });
+        this.stream.on('orderUpdate', (ev) => {
+            if (this.snapshotInFlight) {
+                this.bufferedDuringSnapshot.push(() => this.store.applyOrderUpdate(ev));
+                return;
+            }
+            this.store.applyOrderUpdate(ev);
+        });
+        this.stream.on('marginCall', (ev) => this.emit('marginCall', ev));
+        // ALGO_UPDATE pass-through. NOT buffered through snapshot apply: it is a
+        // terminal/lifecycle signal for conditional orders, not store state the
+        // snapshot would clobber, and acting on EXPIRED/TRIGGERED promptly is the
+        // whole point (it's how we learn a position closed without REST polling).
+        this.stream.on('algoUpdate', (ev) => this.emit('algoUpdate', ev));
+        this.stream.on('reconnecting', (attempt, delay) => this.emit('reconnecting', attempt, delay));
+        this.stream.on('disconnected', (reason, willReconnect) => {
+            logger.warn(TAG, `stream disconnected: ${reason} (willReconnect=${willReconnect})`);
+        });
+        this.stream.on('staleForcedReconnect', (idleMs) => {
+            logger.warn(TAG, `stream stale watchdog fired after ${idleMs}ms idle`);
+        });
+        // Every reconnect attempt bumps the hourly counter; the monitor below
+        // checks the counter each hour and WARNs if it exceeds the alert
+        // threshold. Expected baseline on a quiet account is ~3-4/hour
+        // (worst case listenKey rotation every 25 min + a few stale
+        // reconnects). Sustained 10+/hour means Binance-side trouble,
+        // network flap, or a regression — worth an operator look.
+        this.stream.on('reconnecting', () => {
+            this.reconnectCountThisHour++;
+        });
+    }
+    /** Fetch REST positions/balance/orders and normalise symbols so the store
+     *  keys match WS events regardless of which write path landed first.
+     *  CCXT returns `BTC/USDT:USDT`; our WS parser produces `BTC/USDT`. */
+    async buildSnapshot() {
+        const [positions, balance, openOrders] = await Promise.all([
+            this.api.fetchPositions(),
+            this.api.fetchBalance(),
+            this.api.fetchOpenOrders(),
+        ]);
+        // null = the underlying fetch FAILED (429 / weight-paced / transient),
+        // NOT "flat / no orders". applySnapshot() wipes positions+orders+balances
+        // wholesale, so a snapshot built from any failed fetch would strip live
+        // positions + bracket SL/TP from the (authoritative in observe/enforce)
+        // store. A WS reconnect storm correlates with rate-limit pressure, so this
+        // path is hot, not theoretical. Refuse to build an untrusted snapshot; the
+        // caller skips the apply and the store survives for WS deltas + the next
+        // reconnect/resync to repair. All three are treated as one trust unit
+        // because applySnapshot clears all three sections (a null balance would
+        // zero NAV/equity in enforce — KPI-must-equal-Binance).
+        if (positions === null || openOrders === null || balance === null) {
+            throw new UntrustedSnapshotError(`REST snapshot fetch failed (positions=${positions === null ? 'null' : 'ok'} ` +
+                `balance=${balance === null ? 'null' : 'ok'} ` +
+                `openOrders=${openOrders === null ? 'null' : 'ok'}) — refusing to apply a ` +
+                `store-wiping snapshot; store left intact, will retry next cycle`);
+        }
+        const normSymbol = (s) => s.replace(/:[A-Z]+$/, '');
+        return {
+            timestamp: this.timers.now(),
+            positions: positions.map(p => ({ ...p, symbol: normSymbol(p.symbol) })),
+            // Normalize REST balance.total from CCXT's marginBalance (= wallet + uPnl)
+            // to walletBalance-only, matching what WS ACCOUNT_UPDATE.B[].wb stores.
+            // Without this, any open position with accruing unrealized PnL causes
+            // persistent drift on the margin asset (BNFCR on prod as of 2026-04-21)
+            // — just above the 10 bps minor threshold, forcing resync every 3 cycles
+            // in shadow mode. See live-state-store.ts:336 for the WS-side wallet
+            // store that this normalisation aligns against.
+            balance: normalizeBinanceFuturesBalance(balance),
+            openOrders: openOrders.map(o => ({ ...o, symbol: normSymbol(o.symbol) })),
+        };
+    }
+    async takeAndApplySnapshot() {
+        if (this.snapshotInFlight) {
+            logger.info(TAG, 'snapshot already in flight — skipping');
+            return;
+        }
+        this.snapshotInFlight = true;
+        try {
+            const snap = await this.buildSnapshot();
+            this.store.applySnapshot(snap);
+            logger.info(TAG, `snapshot applied: ${snap.positions.length} positions, ${snap.openOrders.length} orders, balance=${snap.balance ? 'ok' : 'null'}`);
+            this.emit('snapshotApplied', snap);
+        }
+        finally {
+            this.snapshotInFlight = false;
+            // Drain any WS events that arrived during snapshot apply.
+            const buffered = this.bufferedDuringSnapshot;
+            this.bufferedDuringSnapshot = [];
+            for (const fn of buffered) {
+                try {
+                    fn();
+                }
+                catch (err) {
+                    logger.warn(TAG, `buffered event apply failed: ${formatError(err)}`);
+                }
+            }
+        }
+    }
+    startTruthCheckLoop() {
+        this.stopTruthCheckLoop();
+        this.truthCheckTimer = this.timers.setInterval(() => {
+            if (!this.running)
+                return;
+            void this.runTruthCheck().catch((err) => {
+                logger.warn(TAG, `truth check failed (will retry): ${formatError(err)}`);
+            });
+        }, this.truthCheckIntervalMs);
+        logger.info(TAG, `truth-check loop started (every ${this.truthCheckIntervalMs / 1000}s)`);
+    }
+    stopTruthCheckLoop() {
+        if (this.truthCheckTimer) {
+            this.timers.clearInterval(this.truthCheckTimer);
+            this.truthCheckTimer = null;
+        }
+    }
+    /** Start the algo-order refresh loop — REST-polls open orders and replaces
+     *  the algo (bracket SL/TP) subset in the store. Fills the gap left by
+     *  Binance's WS not emitting ORDER_TRADE_UPDATE for algo orders until they
+     *  trigger. Disabled when algoRefreshMs === 0. */
+    startAlgoRefreshLoop() {
+        this.stopAlgoRefreshLoop();
+        if (this.algoRefreshMs <= 0) {
+            logger.info(TAG, 'algo-refresh loop disabled (algoRefreshMs=0)');
+            return;
+        }
+        this.algoRefreshTimer = this.timers.setInterval(() => {
+            if (!this.running)
+                return;
+            void this.runAlgoRefresh().catch((err) => {
+                logger.warn(TAG, `algo-refresh failed (will retry): ${formatError(err)}`);
+            });
+        }, this.algoRefreshMs);
+        logger.info(TAG, `algo-refresh loop started (every ${this.algoRefreshMs / 1000}s)`);
+    }
+    stopAlgoRefreshLoop() {
+        if (this.algoRefreshTimer) {
+            this.timers.clearInterval(this.algoRefreshTimer);
+            this.algoRefreshTimer = null;
+        }
+    }
+    /** Alert threshold — hourly reconnect count that logs a WARN. Set at
+     *  10/hour because the natural baseline on a quiet account (listenKey
+     *  rotation every 25 min + occasional stale-watchdog firing) is
+     *  3-4/hour; anything consistently above that is unexpected. Does NOT
+     *  auto-pause or take action — operator investigates when they see
+     *  the log line land. */
+    static RECONNECT_RATE_ALERT_THRESHOLD = 10;
+    static RECONNECT_RATE_WINDOW_MS = 60 * 60_000;
+    /** Start the reconnect-rate monitor. Runs hourly; resets the counter
+     *  after each check whether or not it alerted. */
+    startReconnectRateMonitor() {
+        this.stopReconnectRateMonitor();
+        this.reconnectRateTimer = this.timers.setInterval(() => {
+            if (!this.running)
+                return;
+            const count = this.reconnectCountThisHour;
+            this.reconnectCountThisHour = 0;
+            if (count >= UserDataStreamController.RECONNECT_RATE_ALERT_THRESHOLD) {
+                logger.warn(TAG, `HIGH reconnect rate: ${count} reconnects in the last hour ` +
+                    `(threshold=${UserDataStreamController.RECONNECT_RATE_ALERT_THRESHOLD}). ` +
+                    `Check Binance API status + network health; listenKey rotation is 25-min, ` +
+                    `stale-watchdog is 15-min — baseline should be 3-4/hr.`);
+            }
+            else {
+                logger.info(TAG, `reconnect-rate OK: ${count}/hr`);
+            }
+        }, UserDataStreamController.RECONNECT_RATE_WINDOW_MS);
+        logger.info(TAG, 'reconnect-rate monitor started (hourly window)');
+    }
+    stopReconnectRateMonitor() {
+        if (this.reconnectRateTimer) {
+            this.timers.clearInterval(this.reconnectRateTimer);
+            this.reconnectRateTimer = null;
+        }
+    }
+    /** One pass of algo-order refresh: fetch open orders (merges regular + algo
+     *  via BinancePrivateApi), filter to algo-bracket cids, and hand them to the
+     *  store's replaceAlgoOrders. No mutation if WS isn't connected (we'd be
+     *  polluting state the reconnect snapshot is about to replace anyway). */
+    async runAlgoRefresh() {
+        if (!this.stream.isConnected())
+            return;
+        if (this.snapshotInFlight)
+            return;
+        const open = await this.api.fetchOpenOrders();
+        if (open === null) {
+            // Fetch FAILED (429 / weight-paced / transient) — NOT "no open orders".
+            // replaceAlgoOrders([]) would strip EVERY live bracket SL/TP from the
+            // authoritative store until the next successful poll (≤algoRefreshMs
+            // naked window). Keep the existing algo orders; a trustworthy refresh
+            // replaces them. Same null≠empty rule as buildSnapshot above.
+            logger.warn(TAG, 'algo-refresh: fetchOpenOrders returned null (REST unavailable) — keeping existing algo orders, will retry');
+            return;
+        }
+        this.store.replaceAlgoOrders(open);
+    }
+    async runTruthCheck() {
+        if (!this.stream.isConnected()) {
+            // WS isn't up — skip; snapshot will happen on reconnect anyway.
+            return;
+        }
+        const snap = await this.buildSnapshot();
+        const drift = this.store.diffAgainstSnapshot(snap);
+        if (drift.severity === 'none') {
+            this.consecutiveMajorDrifts = 0;
+            // Spend the REST read we already paid for on a uPnl/mark refresh rather
+            // than discarding it. ACCOUNT_UPDATE is event-driven and carries no
+            // per-tick mark price, so without this the store's unrealizedPnl is
+            // frozen between fills/funding while the Binance app moves every tick
+            // (2026-05-16 "Unrealized lags/frozen"). Bounded, non-structural — see
+            // LiveStateStore.refreshDerivedMarkFields. Only on severity 'none':
+            // 'minor'/'major' mean structure is in question, so leave those to the
+            // existing paths (major already applies the full fresh snapshot).
+            this.store.refreshDerivedMarkFields(snap.positions);
+            logger.info(TAG, `truth-check OK (mode=${this.mode})`);
+            return;
+        }
+        this.emit('drift', drift);
+        if (drift.severity === 'minor') {
+            this.consecutiveMajorDrifts = 0;
+            logger.warn(TAG, `minor drift: ${drift.summary}`);
+            return;
+        }
+        // major
+        this.consecutiveMajorDrifts += 1;
+        logger.error(TAG, `MAJOR drift (#${this.consecutiveMajorDrifts}): ${drift.summary}`);
+        // In shadow mode: never mutate store from truth-check — REST is authoritative
+        // for reads anyway, so a drift is a signal that the WS pipeline is wrong.
+        // In observe/enforce: apply the snapshot so reads are correct. On 3rd
+        // consecutive major drift in any mode, force resync and emit the event.
+        if (this.mode !== 'shadow') {
+            this.store.applySnapshot(snap);
+        }
+        if (this.consecutiveMajorDrifts >= 3) {
+            logger.error(TAG, `${this.consecutiveMajorDrifts} consecutive major drifts — emitting forcedResync`);
+            this.emit('forcedResync', 'consecutive_major_drifts');
+            this.consecutiveMajorDrifts = 0;
+        }
+    }
+}

package/live/user-data-stream-ws.d.ts

@@ -0,0 +1,22 @@
+import WebSocket from 'ws';
+import type { StreamWebSocket, WebSocketFactory } from './user-data-stream.js';
+/** Default mainnet user-data WS base URL. Append `/<listenKey>` to connect.
+ *  Binance decommissioned the legacy `wss://fstream.binance.com/ws` URL on
+ *  2026-04-23 (per developers.binance.com changelog 2026-04-02). The legacy
+ *  URL still accepts WS connections and even sends server pings, but no
+ *  longer routes ACCOUNT_UPDATE / ORDER_TRADE_UPDATE / ACCOUNT_CONFIG_UPDATE
+ *  events. Migration was silent: events stopped arriving for this account on
+ *  2026-04-27 10:35 UTC. New URL adds the `/private` path segment per the
+ *  current user-data-streams docs page. Verified via A/B test — set leverage
+ *  fires ACCOUNT_CONFIG_UPDATE on /private/ws but NOT on /ws. */
+export declare const MAINNET_USER_DATA_WS = "wss://fstream.binance.com/private/ws";
+/** Testnet user-data WS base URL. Matches CCXT's testnet futures endpoint. */
+export declare const TESTNET_USER_DATA_WS = "wss://stream.binancefuture.com/ws";
+/** Build the user-data WS base URL for a given environment. */
+export declare function userDataWsBaseUrl(testnet: boolean): string;
+/** Adapter from the node `ws` library to our minimal StreamWebSocket shape. */
+export declare function wrapWsClient(ws: WebSocket): StreamWebSocket;
+/** Default factory. Opens a real WS using the `ws` library.
+ *  perMessageDeflate=false matches Binance's recommendation for user-data streams —
+ *  frames are tiny and JSON, compression adds latency without meaningful savings. */
+export declare const defaultWebSocketFactory: WebSocketFactory;

package/live/user-data-stream-ws.js

@@ -0,0 +1,63 @@
+// Default WebSocketFactory wrapping the `ws` library.
+//
+// Split out from user-data-stream.ts so that:
+//   1. Unit tests import UserDataStream without loading the `ws` native addon.
+//   2. The `ws`-specific glue (buffer handling, ping/pong) stays in one place.
+//   3. Alternative factories (native WebSocket, debug proxies) can swap in.
+import WebSocket from 'ws';
+/** Default mainnet user-data WS base URL. Append `/<listenKey>` to connect.
+ *  Binance decommissioned the legacy `wss://fstream.binance.com/ws` URL on
+ *  2026-04-23 (per developers.binance.com changelog 2026-04-02). The legacy
+ *  URL still accepts WS connections and even sends server pings, but no
+ *  longer routes ACCOUNT_UPDATE / ORDER_TRADE_UPDATE / ACCOUNT_CONFIG_UPDATE
+ *  events. Migration was silent: events stopped arriving for this account on
+ *  2026-04-27 10:35 UTC. New URL adds the `/private` path segment per the
+ *  current user-data-streams docs page. Verified via A/B test — set leverage
+ *  fires ACCOUNT_CONFIG_UPDATE on /private/ws but NOT on /ws. */
+export const MAINNET_USER_DATA_WS = 'wss://fstream.binance.com/private/ws';
+/** Testnet user-data WS base URL. Matches CCXT's testnet futures endpoint. */
+export const TESTNET_USER_DATA_WS = 'wss://stream.binancefuture.com/ws';
+/** Build the user-data WS base URL for a given environment. */
+export function userDataWsBaseUrl(testnet) {
+    return testnet ? TESTNET_USER_DATA_WS : MAINNET_USER_DATA_WS;
+}
+/** Adapter from the node `ws` library to our minimal StreamWebSocket shape. */
+export function wrapWsClient(ws) {
+    const adapter = {
+        on(event, cb) {
+            // `ws` and StreamWebSocket agree on event names; just forward.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ws.on(event, cb);
+        },
+        close(code, reason) {
+            try {
+                ws.close(code, reason);
+            }
+            catch { /* already closed */ }
+        },
+        pong(data) {
+            try {
+                ws.pong(data);
+            }
+            catch { /* not connected */ }
+        },
+        terminate() {
+            try {
+                ws.terminate();
+            }
+            catch { /* already closed */ }
+        },
+    };
+    return adapter;
+}
+/** Default factory. Opens a real WS using the `ws` library.
+ *  perMessageDeflate=false matches Binance's recommendation for user-data streams —
+ *  frames are tiny and JSON, compression adds latency without meaningful savings. */
+export const defaultWebSocketFactory = (url) => {
+    const ws = new WebSocket(url, {
+        perMessageDeflate: false,
+        // Binance is strict about the Origin header; wss clients default to empty.
+        handshakeTimeout: 15_000,
+    });
+    return wrapWsClient(ws);
+};