@reefclaw/openclaw-plugin 0.1.0

package/live/bracket-reconciler.d.ts

@@ -0,0 +1,95 @@
+import { EventEmitter } from 'node:events';
+import type { BracketLedger } from './bracket-ledger.js';
+import type { BracketApi, BracketManager } from './bracket-manager.js';
+import type { CcxtOrder, CcxtPosition } from '../types.js';
+import type { BracketLedgerEntry } from './bracket-types.js';
+/** Minimal exchange surface needed for reconciliation — narrowed so tests
+ *  don't have to mock an entire LiveAdapter. */
+export interface BracketReconcilerAdapter {
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /** Trustworthy positions read: returns `null` when the fetch FAILED
+     *  (429 / weight-paced / transient) vs `[]` only when the exchange
+     *  CONFIRMS flat. Optional so narrow test mocks still satisfy the
+     *  interface; runPass prefers it and falls back to getPositions(). */
+    getPositionsOrNull?(symbol?: string): Promise<CcxtPosition[] | null>;
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    /** Zero-weight, authoritative per-symbol bracket-leg liveness from the
+     *  trusted user-data WS `ALGO_UPDATE` map (the SAME signal
+     *  audit_bracket_protection uses). `{ trusted:false }` ⇒ the WS has no
+     *  usable opinion (untrusted/silent) — caller must NOT infer anything
+     *  from it. `liveCids` are cids POSITIVELY observed live (NEW/WORKING);
+     *  a cid's ABSENCE is NOT proof it is dead (never-recorded ≠ cancelled).
+     *  Optional so narrow test mocks still satisfy the interface. */
+    findTrustedLiveBracketCidsForSymbol?(symbol: string): {
+        trusted: boolean;
+        liveCids: string[];
+    };
+    /** Authoritative per-bracket-leg liveness — the SAME signal
+     *  classifyLedgerVsExchange uses (trusted-WS fast-path → weight-1 REST
+     *  /fapi/v1/algoOrder → 'unknown' floor). The Section-2 orphan sweep
+     *  consults this so a cancel is licensed ONLY by POSITIVE proof the legs
+     *  are dead — never by the ABSENCE of the symbol in a (possibly empty /
+     *  weight-paced / eventually-consistent) positions snapshot. A reduce-only
+     *  rc-* leg still live past the grace window is itself positive proof of
+     *  an open position (Binance auto-cancels reduce-only orphans within ~10s).
+     *  Optional so narrow test mocks still satisfy the interface; the real
+     *  LiveAdapter always implements it, so the production path is gated. */
+    resolveBracketLegLiveness?(cid: string): Promise<'live' | 'terminal' | 'unknown'>;
+}
+export type DriftKind = 'healthy' | 'position_unprotected' | 'stale_brackets' | 'unknown_orphan' | 'unknown_orphan_skip_live_position' | 'unknown_orphan_skip_ws_live' | 'unknown_orphan_grace_skip' | 'unknown_orphan_skip_legs_not_terminal' | 'terminal_clean' | 'untrusted_snapshot_skip';
+export interface DriftRecord {
+    kind: DriftKind;
+    symbol?: string;
+    bracketId?: string;
+    details?: string;
+    ts: string;
+}
+export interface ReconcilePassResult {
+    startedAt: string;
+    drifts: DriftRecord[];
+    positionsChecked: number;
+    ordersChecked: number;
+}
+export interface BracketReconcilerOpts {
+    intervalMs?: number;
+    now?: () => number;
+}
+export declare class BracketReconciler extends EventEmitter {
+    private readonly adapter;
+    private readonly ledger;
+    private readonly manager;
+    private readonly api;
+    private readonly baseIntervalMs;
+    private readonly now;
+    private handle;
+    /** Distinct from `handle` because we need to know "did stop() get called
+     *  while a pass was in flight" — at that moment `handle` is still the
+     *  in-flight setTimeout token but `started` has flipped to false. The
+     *  finally-block consults `started` (not `handle`) to decide whether to
+     *  schedule another tick. */
+    private started;
+    private running;
+    /** Current multiplier applied to baseIntervalMs. Doubles on each
+     *  transient-unavailable error, capped at MAX_BACKOFF_MULTIPLIER. Resets to
+     *  1 on a successful pass. Persisted across pass invocations as the
+     *  observed back-pressure state. */
+    private backoffMultiplier;
+    /** bracketId → epoch-ms the orphan sweep first observed it as an
+     *  unmatched (no-active-ledger-row) bracket. Drives the ORPHAN_GRACE_MS
+     *  youth guard: a bracket seen for the first time is, by construction,
+     *  ≤ one pass old from our side — never cancel it that pass. Pruned each
+     *  pass to bracketIds still unmatched on the exchange (bounded). */
+    private readonly firstSeenOrphanAt;
+    constructor(adapter: BracketReconcilerAdapter, ledger: BracketLedger, manager: BracketManager, api: BracketApi, opts?: BracketReconcilerOpts);
+    /** Begin periodic reconciliation. Safe to call if already started. */
+    start(): void;
+    stop(): void;
+    /** Self-rescheduling tick. Replaces the old `setInterval` because the
+     *  next interval is dynamic — we slow down under back-pressure, speed back
+     *  up after a clean pass. The old approach kept hitting Binance at full
+     *  60 s cadence during a 429 storm, amplifying it. */
+    private scheduleNextPass;
+    /** One reconciliation pass. Exposed for unit tests + startup recovery. */
+    runPass(): Promise<ReconcilePassResult>;
+}
+export { BracketLedgerEntry };