@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/live/user-data-stream-controller.d.ts

@@ -1,200 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { BinancePrivateApi } from '../ccxt/binance-private.js';
-import { UserDataStream } from './user-data-stream.js';
-import type { ParsedAlgoUpdate } from './user-data-stream.js';
-import { LiveStateStore } from './live-state-store.js';
-import type { RestSnapshot, StateDrift } from './live-state-store.js';
-import type { UserDataStreamMode, UserDataStreamTunables } from '../config/user-data-stream-config.js';
-import type { CcxtBalance } from '../types.js';
-import type { TradeStoreClient } from '../ingest/trade-store-client.js';
-import type { TouchedSymbolsStore } from '../ingest/touched-symbols-store.js';
-import type { AutoCaptureContext } from '../ingest/position-auto-capture.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 declare function normalizeBinanceFuturesBalance(balance: CcxtBalance): CcxtBalance;
-/**
- * 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 declare class UntrustedSnapshotError extends Error {
-    constructor(message: string);
-}
-export interface ControllerTimerDeps {
-    setInterval: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
-    clearInterval: (handle: ReturnType<typeof setInterval>) => void;
-    now: () => number;
-}
-export interface UserDataStreamControllerOptions {
-    mode: UserDataStreamMode;
-    testnet: boolean;
-    tunables: UserDataStreamTunables;
-    /** If absent, a real WS stream is built from `defaultWebSocketFactory`.
-     *  Tests inject a prebuilt stream to avoid touching the network. */
-    stream?: UserDataStream;
-    /** If absent, a fresh LiveStateStore is constructed. */
-    store?: LiveStateStore;
-    /** 60_000 by default. Shorter values allowed for post-drift tightening. */
-    truthCheckIntervalMs?: number;
-    /** Timer injection for unit tests. */
-    timers?: Partial<ControllerTimerDeps>;
-    /** Audit-trail ingest path (TRADE_AUDIT_TRAIL_PLAN Phase 1).  When present
-     *  AND mode≠'off', the controller starts a WsIngest alongside the stream
-     *  that POSTs every TRADE event to the webapp's /api/internal/trades.
-     *  Caller decides whether to pass this in based on userDataStream.dbWrite. */
-    tradeIngest?: {
-        client: TradeStoreClient;
-        userId: string;
-        exchange?: string;
-        /** Optional override for the gap-filler's persistent touched-symbols
-         *  store. Pass `null` to disable cross-restart persistence (tests).
-         *  Production callers leave this undefined to get the file-backed
-         *  default under ~/.reefclaw/touched-symbols-<userId>.json. */
-        touchedSymbolsStore?: TouchedSymbolsStore | null;
-    };
-    /** Position-decision auto-capture context. When provided alongside
-     *  tradeIngest, the controller passes it to WsIngest so every TRADE event
-     *  is also routed through `onWsFillObserved` (limit-order entries +
-     *  scale-ins). When omitted, ws-ingest only records to the audit trail
-     *  (the legacy PR1 behaviour). */
-    autoCapture?: AutoCaptureContext;
-}
-export type ControllerEvents = {
-    /** Emitted after every REST snapshot has been applied. */
-    snapshotApplied: (snap: RestSnapshot) => void;
-    /** Emitted when the 60s drift check finds anything (minor or major). */
-    drift: (drift: StateDrift) => void;
-    /** Emitted when a major drift triggered a forced resync. */
-    forcedResync: (cause: string) => void;
-    /** Emitted when the stream reports a reconnect — observability. */
-    reconnecting: (attempt: number, delayMs: number) => void;
-    /** Pass-through of advisory events from the stream. */
-    marginCall: (ev: unknown) => void;
-    /** Pass-through of ALGO_UPDATE (conditional/bracket order lifecycle).
-     *  LiveAdapter consumes this as the AUTHORITATIVE bracket-state signal —
-     *  Binance pushes EXPIRED when it auto-cancels a sibling on position
-     *  close, CANCELED only on an explicit cancel, TRIGGERED/FINISHED on
-     *  fire. Replaces REST-audit guessing. */
-    algoUpdate: (ev: ParsedAlgoUpdate) => void;
-};
-export declare class UserDataStreamController extends EventEmitter {
-    readonly mode: UserDataStreamMode;
-    private readonly api;
-    private readonly stream;
-    private readonly store;
-    private readonly truthCheckIntervalMs;
-    private readonly staleStoreThresholdMs;
-    private readonly timers;
-    private truthCheckTimer;
-    private algoRefreshTimer;
-    private reconnectRateTimer;
-    private readonly algoRefreshMs;
-    private readonly wsIngest;
-    private readonly restGapFiller;
-    private readonly 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. */
-    private reconnectCountThisHour;
-    private running;
-    private snapshotInFlight;
-    /** 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. */
-    private bufferedDuringSnapshot;
-    private consecutiveMajorDrifts;
-    constructor(api: BinancePrivateApi, options: UserDataStreamControllerOptions);
-    getStore(): LiveStateStore;
-    getStream(): UserDataStream;
-    /** 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(): boolean;
-    /** Start the stream + run the initial REST snapshot + seed the store.
-     *  No-op if mode is 'off'. Throws if already running. */
-    start(): Promise<void>;
-    /** Graceful shutdown. */
-    stop(): Promise<void>;
-    /** Force a full snapshot + re-seed. Used by operator tools for manual resync. */
-    forceResync(cause: string): Promise<void>;
-    private buildStreamOptions;
-    private attachStreamHandlers;
-    /** 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`. */
-    private buildSnapshot;
-    private takeAndApplySnapshot;
-    private startTruthCheckLoop;
-    private stopTruthCheckLoop;
-    /** 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. */
-    private startAlgoRefreshLoop;
-    private stopAlgoRefreshLoop;
-    /** 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. */
-    private static readonly RECONNECT_RATE_ALERT_THRESHOLD;
-    private static readonly RECONNECT_RATE_WINDOW_MS;
-    /** Start the reconnect-rate monitor. Runs hourly; resets the counter
-     *  after each check whether or not it alerted. */
-    private startReconnectRateMonitor;
-    private stopReconnectRateMonitor;
-    /** 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). */
-    private runAlgoRefresh;
-    private runTruthCheck;
-}