@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/live/listen-key-manager.js

@@ -1,169 +0,0 @@
-// ListenKeyManager — owns the Binance Futures user-data listenKey lifecycle.
-//
-// Flow:
-//   1. `start()` — POST /fapi/v1/listenKey → emit 'keyMinted' with the listenKey.
-//   2. Schedule PUT /fapi/v1/listenKey every `refreshIntervalMs` (default 25 min).
-//      Binance expires idle keys at 60 min; 25 min gives a 2x safety margin.
-//   3. On failed keep-alive, re-mint (POST) a fresh key and emit 'keyRotated'.
-//      Binance returns the SAME listenKey for repeat POSTs from the same API
-//      key, so "re-mint" is effectively a probe that the key is still valid.
-//      If the probe succeeds, we accept its answer; if it fails, we emit
-//      'keyKeepAliveFailed' and stop — the parent UserDataStream schedules
-//      a reconnect that re-enters `start()`.
-//   4. `stop()` — clear timer + DELETE /fapi/v1/listenKey (best-effort).
-//
-// Why this is a separate component:
-//   - Testable in isolation with fake timers + a mock API.
-//   - UserDataStream can stay focused on frame parsing + reconnect logic.
-//   - Graduated alert thresholds live here (3 failed refreshes = WARN,
-//     10 = ERROR) rather than being spread through the WS state machine.
-import { EventEmitter } from 'node:events';
-import { logger, formatError } from '../logger.js';
-const TAG = 'listen-key-manager';
-const REAL_TIMER_DEPS = {
-    setTimeout: (fn, ms) => setTimeout(fn, ms),
-    clearTimeout: (h) => clearTimeout(h),
-    now: () => Date.now(),
-};
-/** Lightweight typed emitter — EventEmitter with a phantom type. */
-export class ListenKeyManager extends EventEmitter {
-    api;
-    refreshIntervalMs;
-    maxConsecutiveFailures;
-    timers;
-    currentKey = null;
-    keyMintedAt = null;
-    refreshTimer = null;
-    consecutiveFailures = 0;
-    running = false;
-    constructor(api, options = {}) {
-        super();
-        this.api = api;
-        this.refreshIntervalMs = options.refreshIntervalMs ?? 25 * 60_000;
-        this.maxConsecutiveFailures = options.maxConsecutiveFailures ?? 3;
-        this.timers = {
-            setTimeout: options.timers?.setTimeout ?? REAL_TIMER_DEPS.setTimeout,
-            clearTimeout: options.timers?.clearTimeout ?? REAL_TIMER_DEPS.clearTimeout,
-            now: options.timers?.now ?? REAL_TIMER_DEPS.now,
-        };
-    }
-    /** Mint a listenKey and start the refresh loop. Returns the minted key.
-     *  Throws if the first POST fails — caller decides how to back off. */
-    async start() {
-        if (this.running) {
-            throw new Error('ListenKeyManager already started');
-        }
-        const key = await this.api.createListenKey();
-        this.currentKey = key;
-        this.keyMintedAt = this.timers.now();
-        this.consecutiveFailures = 0;
-        this.running = true;
-        this.emit('keyMinted', key);
-        this.scheduleRefresh();
-        logger.info(TAG, `listenKey minted (hash=${hashKey(key)}), refresh every ${this.refreshIntervalMs / 1000}s`);
-        return key;
-    }
-    /** Stop the refresh loop and best-effort close the key. Idempotent.
-     *  For GRACEFUL shutdown only — a reconnect-driven teardown must use
-     *  `stopKeepAlive()` instead (see below). */
-    async stop() {
-        if (!this.running)
-            return;
-        this.running = false;
-        if (this.refreshTimer) {
-            this.timers.clearTimeout(this.refreshTimer);
-            this.refreshTimer = null;
-        }
-        if (this.currentKey) {
-            try {
-                await this.api.closeListenKey();
-            }
-            catch (err) {
-                // Not worth retrying on shutdown — Binance expires idle keys anyway.
-                logger.warn(TAG, `closeListenKey failed on stop (non-fatal): ${formatError(err)}`);
-            }
-            this.currentKey = null;
-            this.keyMintedAt = null;
-        }
-    }
-    /** Stop the refresh loop WITHOUT the DELETE — for reconnect-driven closes.
-     *  Binance returns the SAME active listenKey on a re-POST and merely
-     *  extends its validity (doc-verified 2026-07-02: "Doing a POST on an
-     *  account with an active listenKey will return the currently active
-     *  listenKey and extend its validity for 60 minutes"), so an in-flight
-     *  DELETE racing the reconnect's POST can land AFTER it and invalidate the
-     *  key the fresh socket just authenticated with — a silent dead stream.
-     *  Skipping the DELETE is safe: an unused key expires on its own after
-     *  60 min of no keep-alive. Synchronous + idempotent. */
-    stopKeepAlive() {
-        if (!this.running)
-            return;
-        this.running = false;
-        if (this.refreshTimer) {
-            this.timers.clearTimeout(this.refreshTimer);
-            this.refreshTimer = null;
-        }
-        this.currentKey = null;
-        this.keyMintedAt = null;
-    }
-    /** Current listenKey, or null if stopped. */
-    getKey() {
-        return this.currentKey;
-    }
-    /** Age in ms since the key was last minted. Null if stopped. Useful for
-     *  observability dashboards — a key far beyond refreshIntervalMs but still
-     *  alive means Binance is tolerating us past the nominal window. */
-    getKeyAge() {
-        if (this.keyMintedAt == null)
-            return null;
-        return this.timers.now() - this.keyMintedAt;
-    }
-    /** Number of consecutive failed keep-alive probes. Exposed for diagnostics. */
-    getConsecutiveFailures() {
-        return this.consecutiveFailures;
-    }
-    // ---- Internal ----
-    scheduleRefresh() {
-        if (!this.running)
-            return;
-        this.refreshTimer = this.timers.setTimeout(() => {
-            this.refreshTimer = null;
-            void this.refresh();
-        }, this.refreshIntervalMs);
-    }
-    async refresh() {
-        if (!this.running)
-            return;
-        try {
-            await this.api.keepAliveListenKey();
-            this.consecutiveFailures = 0;
-            this.emit('keyRefreshed');
-            logger.info(TAG, `listenKey refreshed (age=${Math.round((this.getKeyAge() ?? 0) / 1000)}s)`);
-            this.scheduleRefresh();
-        }
-        catch (err) {
-            this.consecutiveFailures += 1;
-            const reason = formatError(err);
-            if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
-                // Stream is dead. Don't reschedule — parent will restart us.
-                logger.error(TAG, `listenKey keep-alive failed ${this.consecutiveFailures} times (last: ${reason}) — giving up`);
-                this.running = false;
-                if (this.refreshTimer) {
-                    this.timers.clearTimeout(this.refreshTimer);
-                    this.refreshTimer = null;
-                }
-                this.emit('keyKeepAliveFailed', reason);
-                return;
-            }
-            // Transient — log and retry on the normal cadence. We deliberately do
-            // NOT shrink the interval on failure; the keep-alive window is 60 min
-            // so we can afford up to 2 more tries before the key expires.
-            logger.warn(TAG, `listenKey keep-alive failed (${this.consecutiveFailures}/${this.maxConsecutiveFailures}): ${reason}`);
-            this.scheduleRefresh();
-        }
-    }
-}
-/** First 8 chars of a listenKey for log correlation without leaking the key. */
-function hashKey(key) {
-    return key.length > 8 ? key.slice(0, 8) : '(short)';
-}

package/assets/plugin/live/live-adapter.d.ts

@@ -1,287 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { IExchangeAdapter, AdapterReadiness, ClientOrderResolution, OrderOptions } from '../exchange-adapter.js';
-import { BinancePrivateApi } from '../ccxt/binance-private.js';
-import type { BinanceAlgoOrderProof } from '../ccxt/binance-private.js';
-import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode, ExchangeConfig } from '../types.js';
-import type { PositionMetadata, CloseReason } from '../simulator/types.js';
-import { ExchangeInfoCache } from './exchange-info-cache.js';
-import { BinanceRateLimiter } from './rate-limiter.js';
-import { IntentJournal } from './intent-journal.js';
-import { OrderPoller } from './order-poller.js';
-import { SlippageTracker } from './slippage-tracker.js';
-import { PositionReconciler } from './reconciler.js';
-import { LiveBalanceEnricher } from './live-balance-enricher.js';
-import { DepositTracker } from './deposit-tracker.js';
-import { BracketLedger } from './bracket-ledger.js';
-import { BracketManager } from './bracket-manager.js';
-import { type BracketMode } from '../config/brackets-config.js';
-import { type UserDataStreamMode, type UserDataStreamTunables } from '../config/user-data-stream-config.js';
-import { UserDataStreamController } from './user-data-stream-controller.js';
-import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
-import type { TradeStoreClient } from '../ingest/trade-store-client.js';
-/** Optional audit-trail wiring (TRADE_AUDIT_TRAIL_PLAN Phase 1).  Caller
- *  passes this only when userDataStream.dbWrite='on' AND the WEBAPP_INGEST_TOKEN
- *  + REEFCLAW_USER_ID env vars are present.  Forwarded into the controller
- *  which spins up a WsIngest alongside the existing read path. */
-export interface TradeIngestWiring {
-    client: TradeStoreClient;
-    userId: string;
-    exchange?: string;
-}
-export interface Wave9ProtectionLossEvent {
-    source: 'algo_canceled' | 'algo_rejected' | 'reconciler_missing';
-    symbol: string;
-    bracketId: string;
-    entryClientOrderId: string;
-    entrySide: 'buy' | 'sell';
-    stopClientOrderId?: string;
-    detail: string;
-}
-export type Wave9ProtectionLossHandler = (event: Wave9ProtectionLossEvent) => Promise<void> | void;
-/**
- * Backfill `balance.free[cur] = total[cur]` for currencies where Binance's CCXT
- * response left the per-currency `free` and `used` at zero despite a non-zero
- * total. Only safe when `used` is zero — otherwise the exchange really is
- * reserving margin and we must not inflate availability.
- */
-export declare function repairFreeFromTotal(balance: CcxtBalance): void;
-export declare class LiveAdapter extends EventEmitter implements IExchangeAdapter {
-    readonly mode: TradingMode;
-    readonly isLive = true;
-    private api;
-    private sizeCapMultiplier;
-    private maxPositionUSDT;
-    private exchangeInfo;
-    private isHedgeMode;
-    private getOpenOrdersUnavailableUntil;
-    private static readonly OPEN_ORDERS_RL_COOLDOWN_MS;
-    private rateLimiter;
-    private intentJournal;
-    private orderPoller;
-    private slippageTracker;
-    private reconciler;
-    private enricher;
-    private depositTracker;
-    private readonly bracketMode;
-    private bracketLedger;
-    private bracketManager;
-    private bracketReconciler;
-    private wave9ProtectionLossHandler?;
-    private readonly wave9ProtectionLossInFlight;
-    private readonly pendingWave9ProtectionLossBySymbol;
-    private static readonly PENDING_WAVE9_PROTECTION_LOSS_CAP;
-    private readonly userDataStreamMode;
-    private userDataStream;
-    private readonly wsAlgoStatusByCid;
-    private static readonly WS_ALGO_STATUS_CAP;
-    private static readonly WS_LIVE_LEG_MAX_AGE_MS;
-    private _sessionStartNav;
-    private lastIncomeRefreshMs;
-    private incomeAnchorUtcDay;
-    private liveMetadata;
-    private _readiness;
-    get readiness(): AdapterReadiness;
-    /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
-    getSessionStartNav(): number | null;
-    constructor(config: ExchangeConfig, mode: 'MICRO_LIVE' | 'LIVE', microLiveConfig?: {
-        sizeCapPercent?: number;
-        maxPositionUSDT?: number;
-    }, bracketMode?: BracketMode, userDataStreamMode?: UserDataStreamMode, userDataStreamTunables?: UserDataStreamTunables, 
-    /** TRADE_AUDIT_TRAIL_PLAN Phase 1 — optional audit-trail wiring.  Wired
-     *  through to UserDataStreamController.  Absent today on every existing
-     *  call site (default off); operator-driven once activation is approved. */
-    tradeIngest?: TradeIngestWiring, 
-    /** Position-decision auto-capture wiring. When provided alongside
-     *  tradeIngest, ws-ingest also routes every TRADE event through
-     *  `onWsFillObserved` to capture limit-order entries + scale-ins
-     *  (PR1 deferral resolution, 2026-05-03). Optional for back-compat. */
-    autoCapture?: AutoCaptureContext);
-    /** Get the underlying BinancePrivateApi (for advanced queries like fetchTicker). */
-    getApi(): BinancePrivateApi;
-    /** Get the exchange info cache (for symbol rules). */
-    getExchangeInfo(): ExchangeInfoCache;
-    /** Whether the account is in hedge mode. */
-    getIsHedgeMode(): boolean;
-    /** Get safety modules for external access (dashboard, tools, etc.). */
-    getRateLimiter(): BinanceRateLimiter;
-    getIntentJournal(): IntentJournal;
-    getOrderPoller(): OrderPoller;
-    getSlippageTracker(): SlippageTracker;
-    getReconciler(): PositionReconciler;
-    getEnricher(): LiveBalanceEnricher;
-    getDepositTracker(): DepositTracker;
-    /** Active user-data-stream mode. `'off'` when the feature flag is disabled. */
-    getUserDataStreamMode(): UserDataStreamMode;
-    /** User-data stream controller, or null if mode='off'. Used by dashboards
-     *  and diagnostic tools to read the live-state store + health. */
-    getUserDataStream(): UserDataStreamController | null;
-    /**
-     * Post-registration async initialization.
-     * Must complete before create_order is allowed (readiness gate).
-     * Emergency controls (cancel, close) work regardless of readiness.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Acknowledge existing positions on startup.
-     * Transitions DEGRADED → READY. Exchange info + position mode are already loaded
-     * (they're loaded before the position check in initialize()).
-     */
-    acknowledgePositions(): Promise<void>;
-    /**
-     * Tear down background loops so the adapter can be replaced at runtime
-     * (e.g. when the operator changes credentials or trading mode from the
-     * dashboard). Must be called before discarding the LiveAdapter reference
-     * or the poller + reconciler timers will keep firing against stale state.
-     *
-     * Idempotent — safe to call multiple times.
-     */
-    shutdown(): void;
-    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
-    /**
-     * Attach brackets in the background. Auto-flattens on failure per locked
-     * decision #2. Never throws — errors are surfaced via emitted events and
-     * the subsequent flatten.
-     */
-    private attachBracketsAsync;
-    /** Install the Wave 9-only autonomous recovery bridge. With no handler,
-     *  every generic bracket lifecycle remains byte-for-byte behaviorally
-     *  unchanged. Runtime reapplies this setter after adapter reconnects. */
-    setWave9ProtectionLossHandler(handler?: Wave9ProtectionLossHandler): void;
-    private notifyWave9ProtectionLoss;
-    /**
-     * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
-     *
-     * Why this exists (2026-05-15 RCA, doc-verified): pre-fix the plugin
-     * learned bracket state by REST-polling `audit_bracket_protection` /
-     * `fetchOpenOrders` and *guessing* — under a 429 storm that produced the
-     * audit→re-attach→cancel spiral that flushed live positions. Binance
-     * already PUSHES authoritative conditional-order lifecycle. Doc-exact
-     * status semantics (developers.binance.com → Event Algo Order Update):
-     *
-     *   EXPIRED   = SYSTEM cancel. The canonical trigger is "GTE_GTC
-     *               conditional + position closed → Binance auto-cancels the
-     *               surviving sibling". So EXPIRED on our bracket cid ⇒ the
-     *               position just closed by a non-close_position path (bracket
-     *               fill, manual, opposite-side). EXPECTED — not a fault.
-     *   TRIGGERED / FINISHED = the bracket fired (SL/TP hit) → position closed.
-     *   CANCELED  = MANUAL cancel (an explicit cancelOrder from us). Post the
-     *               bracket-reconciler fix we should NOT be doing this while a
-     *               position is open; if we see it, it's the canary that some
-     *               *other* path still strips protection — WARN loudly.
-     *
-     * For EXPIRED/TRIGGERED/FINISHED we (a) mark the ledger terminal so the
-     * attach-brackets re-attach loop STOPS chasing a bracket Binance already
-     * removed, and (b) emit the SAME `drift_detected` shape the position
-     * reconciler emits, so the existing, tested close-bypass cleanup
-     * (`onReconcilerObservedClose` in index.ts) runs immediately instead of
-     * up to 60 s later — which is what clears the stale state-store entry and
-     * stops the NEXT entry on the symbol being mis-classified as a scale-in
-     * (the bug that left fresh positions naked). No auto-flatten here: that
-     * stays deferred until this signal has soaked.
-     */
-    private onAlgoUpdate;
-    /** Expose the bracket manager for agent-facing tools (modify_stop, etc.).
-     *  Returns null when bracket mode is 'off'. */
-    getBracketManager(): BracketManager | null;
-    /** Expose the bracket ledger for reconciliation + admin queries. */
-    getBracketLedger(): BracketLedger | null;
-    /** Is the user-data WS store currently trusted (seeded + fresh + no gap)?
-     *  The Tier-1 gate for resolveBracketLegLiveness — when false the WS
-     *  per-cid signal is NOT consulted (a stale/gapped stream that missed a
-     *  CANCELED would otherwise yield a false 'live' on a naked leg — the exact
-     *  flaw the layered design exists to prevent). Null stream (mode=off) ⇒
-     *  never trusted ⇒ always the REST authority. */
-    isUserDataStoreTrusted(): boolean;
-    /** Authoritative per-bracket-leg liveness — the Phase 2 disambiguator that
-     *  replaces inferring presence/absence from a broad openOrders snapshot
-     *  (the SOL/INJ spiral root: a *successful* empty /fapi/v1/openAlgoOrders
-     *  is NOT proof a leg is gone).
-     *
-     *  Precedence (the agreed layering):
-     *   1. WS fast-path — ONLY behind isUserDataStoreTrusted(): the real
-     *      per-cid ALGO_UPDATE status (incl. CANCELED, which the ledger does
-     *      NOT record). Zero weight, sub-second. No record for the cid ⇒ no
-     *      WS opinion ⇒ fall through (never infer from absence).
-     *   2. REST authority — queryAlgoOrderStatus(cid): a DIRECT weight-1
-     *      question about that exact order id. Used when WS is untrusted or
-     *      silent on the cid.
-     *   3. 'unknown' — both unavailable. The d59e51b safe floor: callers MUST
-     *      refuse destructive action and retry; NEVER treat 'unknown' as
-     *      'terminal'/'stale'.
-     *
-     *  'live'     = leg is on the exchange (do NOT reattach/clobber).
-     *  'terminal' = positively confirmed gone (CANCELED/EXPIRED/REJECTED) or
-     *               fired (TRIGGERED/FINISHED) — only this licenses repair.
-     *  'unknown'  = could not get an answer — safe-wait. */
-    resolveBracketLegLiveness(cid: string): Promise<'live' | 'terminal' | 'unknown'>;
-    /** Immediate full-shape proof for one exact native conditional order. */
-    resolveBracketLegProof(cid: string): Promise<BinanceAlgoOrderProof | null>;
-    /** Symbol-scoped generalization of the trusted-WS fast-path — the
-     *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
-     *
-     *  `resolveBracketLegLiveness(cid)` answers about ONE cid. The spiral is:
-     *  a prior `attach_brackets` reattach placed a FRESH bracket that is live
-     *  on the exchange under a NEW cid, while the ledger row still holds the
-     *  PREVIOUS, genuinely-terminal cids. Classifying only the ledger's cids
-     *  yields a false 'stale' → clear+reattach cancels the live fresh bracket
-     *  → naked → audit unprotected → attach → spiral (prod: INJ/USDT cancelled
-     *  every ~15-40s for hours). This asks the question the ledger cids can't:
-     *  "is ANY rc-* bracket leg for this symbol live RIGHT NOW, under any cid?"
-     *
-     *  Trust model (identical to resolveBracketLegLiveness Tier-1): the WS map
-     *  is consulted ONLY when `isUserDataStoreTrusted()` (seeded + fresh +
-     *  no-gap — the property that guarantees no missed CANCELED, so a record
-     *  reading 'live' really is live). When the store is NOT trusted this
-     *  returns `{ trusted:false, liveCids:[] }` and the caller must NOT infer
-     *  "no live leg" from it — it falls back to the per-leg REST authority and,
-     *  failing that, refuses the destructive action (the d59e51b safe floor).
-     *  A record older than WS_LIVE_LEG_MAX_AGE_MS is ignored (caller falls back
-     *  too) so a stale 'live' can never suppress a genuine repair forever. */
-    findTrustedLiveBracketCidsForSymbol(symbol: string): {
-        trusted: boolean;
-        liveCids: string[];
-    };
-    /** Cancel every bracket-tagged (SL or TP) open order for a symbol. Used by
-     *  the `attach_brackets` recovery tool to clear stale bracket orders before
-     *  re-attaching a fresh pair. Does not touch non-bracket orders. Returns
-     *  the number successfully cancelled. Errors are logged + swallowed —
-     *  "already gone" is treated as success by the underlying cancel path. */
-    cancelSymbolBracketOrders(symbol: string): Promise<number>;
-    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
-    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
-    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
-    /** Re-arm protection on a position whose closePosition flow cancelled the
-     *  brackets and then failed every market-close attempt. Reuses the normal
-     *  attach machinery: re-register the ledger row (terminal row → fresh
-     *  pending_entry with the SAME stop/target levels) and run the standard
-     *  3-retry attach. Never throws — this runs on the already-failing close
-     *  path; on any failure it emits the reconciler's `position_unprotected`
-     *  drift shape (re-emitted upstream as `bracket_drift`) plus a loud log so
-     *  the operator knows re-protection is required. */
-    private reattachBracketsAfterFailedClose;
-    getBalance(): Promise<CcxtBalance>;
-    /** Re-anchor the realized-today seed + sessionStartNav from /fapi/v1/income.
-     *  Throttled to {@link INCOME_REFRESH_MIN_INTERVAL_MS}; UTC date rollover
-     *  forces an immediate refresh. Best-effort — failures are logged and
-     *  swallowed so a transient income-endpoint blip never blocks a balance
-     *  read. Called from getBalance() with the fresh quote wallet so we don't
-     *  fetch balance twice.
-     */
-    private refreshIncomeAnchor;
-    getPositions(symbol?: string): Promise<CcxtPosition[]>;
-    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
-    /** Merge agent-supplied entry metadata + ratchet MFE state into the raw
-     *  CCXT position list. Side effect: drops metadata for symbols no longer
-     *  in the open-positions snapshot (only when called without a symbol filter
-     *  — symbol-scoped calls skip cleanup so we don't lose context for other
-     *  open positions). */
-    private decoratePositionsWithMetadata;
-    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
-    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
-    resolveOrderByClientId(clientOrderId: string, symbol: string): Promise<ClientOrderResolution>;
-    getLastPrice(symbol: string): Promise<number | null>;
-    /** Sync rate limiter from exchange response headers after every private API call. */
-    private syncRateLimits;
-    private loadExchangeInfo;
-    private detectPositionMode;
-}