@reefclaw/openclaw-plugin 0.1.0

package/live/live-state-store.js

@@ -0,0 +1,450 @@
+// LiveStateStore — in-memory account state fed by the user-data WebSocket.
+//
+// Design notes:
+//   - Pure state machine. No IO. No timers. No network calls. All testable
+//     with synchronous unit tests + snapshot assertions.
+//   - Writes come from two sources:
+//       1. `applySnapshot(snap)` — authoritative REST snapshot taken on
+//          connect + reconnect + forced resync. Replaces state wholesale.
+//       2. `applyAccountUpdate(ev)` / `applyOrderUpdate(ev)` — WS deltas that
+//          mutate state per-symbol / per-asset / per-orderId.
+//   - Reads (`getPositions` / `getBalance` / `getOpenOrders`) return
+//     STRUCTURAL CLONES. Consumers can't mutate the store by accident.
+//   - `diffAgainstSnapshot(rest)` compares local state vs a REST truth-check.
+//     Drifts are classified minor/major; parent decides whether to force resync.
+//   - Idempotent snapshot apply — a snapshot replaces rather than appends, so
+//     a duplicate snapshot doesn't double-count.
+//   - No hedge-mode support — v1 is one-way only. If a position event with
+//     positionSide=LONG/SHORT (not BOTH) arrives, we log a warning and apply
+//     by symbol (first-write-wins). Parent refuses to enable observe/enforce
+//     on hedge-mode accounts at a higher layer.
+//
+// Binance event shapes (user-data stream, Futures):
+//   ACCOUNT_UPDATE.a.P[i] = { s: symbol, ps: 'LONG'|'SHORT'|'BOTH',
+//                              pa: positionAmt, ep: entryPrice,
+//                              up: unrealizedPnl, mt: 'cross'|'isolated',
+//                              cr: cumulativeRealized (optional) }
+//   ACCOUNT_UPDATE.a.B[i] = { a: asset, wb: walletBalance, cw: crossWallet,
+//                              bc: balanceChange }
+//   ORDER_TRADE_UPDATE.o = { s: symbol, i: orderId, c: clientOrderId,
+//                             S: 'BUY'|'SELL', o: orderType, f: timeInForce,
+//                             q: origQty, p: origPrice, ap: avgPrice,
+//                             x: execType ('NEW'|'TRADE'|'CANCELED'|'EXPIRED'|'REJECTED'|...),
+//                             X: orderStatus ('NEW'|'PARTIALLY_FILLED'|'FILLED'|...),
+//                             l: lastFilledQty, z: cumFilledQty, L: lastFillPrice,
+//                             n: commission, N: commissionAsset, T: transactTime }
+//
+// We translate into our narrower domain types (CcxtPosition, CcxtBalance,
+// CcxtOrder) at apply time so the rest of the plugin sees one shape only.
+import { EventEmitter } from 'node:events';
+import { parseBracketCid } from './bracket-id.js';
+import { logger } from '../logger.js';
+const TAG = 'live-state-store';
+const DEFAULT_THRESHOLDS = {
+    balanceMinorBps: 10, // 0.1%
+    positionMinorContracts: 1e-6, // essentially any nonzero is major
+};
+export class LiveStateStore extends EventEmitter {
+    // Positions keyed by symbol (one-way mode: one position per symbol).
+    positions = new Map();
+    // Balance keyed by currency.
+    balances = new Map();
+    // Open orders keyed by exchange orderId.
+    orders = new Map();
+    // Last-apply timestamps for observability.
+    lastSnapshotAt = null;
+    lastAccountUpdateAt = null;
+    lastOrderUpdateAt = null;
+    thresholds;
+    constructor(thresholds = {}) {
+        super();
+        this.thresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
+    }
+    // ---- Reads (synchronous, safe) ----
+    /** Get positions, optionally filtered by symbol. Returns clones. */
+    getPositions(symbol) {
+        if (symbol) {
+            const p = this.positions.get(symbol);
+            return p ? [clonePosition(p)] : [];
+        }
+        return Array.from(this.positions.values()).map(clonePosition);
+    }
+    /** Get the current balance view. Matches the CCXT shape. */
+    getBalance() {
+        const free = {};
+        const used = {};
+        const total = {};
+        const result = { free, used, total };
+        for (const [cur, b] of this.balances) {
+            free[cur] = b.free;
+            used[cur] = b.used;
+            total[cur] = b.total;
+            result[cur] = { ...b };
+        }
+        return result;
+    }
+    /** Get open orders, optionally filtered by symbol. Returns clones. */
+    getOpenOrders(symbol) {
+        const all = Array.from(this.orders.values());
+        const filtered = symbol ? all.filter(o => o.symbol === symbol) : all;
+        return filtered.map(cloneOrder);
+    }
+    /** Observability — last-apply timestamps for each write path. */
+    getHealth() {
+        return {
+            lastSnapshotAt: this.lastSnapshotAt,
+            lastAccountUpdateAt: this.lastAccountUpdateAt,
+            lastOrderUpdateAt: this.lastOrderUpdateAt,
+            positionCount: this.positions.size,
+            orderCount: this.orders.size,
+            balanceAssetCount: this.balances.size,
+        };
+    }
+    // ---- Writes ----
+    /** Replace state with a REST snapshot. Called on connect + reconnect + forced resync.
+     *  Idempotent: a duplicate snapshot produces identical state. */
+    applySnapshot(snap) {
+        this.positions.clear();
+        for (const p of snap.positions) {
+            if (p.contracts > 0) {
+                this.positions.set(p.symbol, clonePosition(p));
+            }
+        }
+        this.balances.clear();
+        if (snap.balance) {
+            for (const cur of Object.keys(snap.balance.total ?? {})) {
+                const total = snap.balance.total[cur] ?? 0;
+                const free = snap.balance.free[cur] ?? 0;
+                const used = snap.balance.used[cur] ?? 0;
+                if (total > 0 || free > 0 || used > 0) {
+                    this.balances.set(cur, { free, used, total });
+                }
+            }
+        }
+        this.orders.clear();
+        for (const o of snap.openOrders) {
+            if (o.status === 'open' && o.id) {
+                this.orders.set(o.id, cloneOrder(o));
+            }
+        }
+        this.lastSnapshotAt = snap.timestamp;
+        this.emit('stateChanged', 'snapshot');
+    }
+    /** Replace the algo-order subset of the store with a fresh REST list.
+     *
+     *  Binance's user-data WS does NOT emit ORDER_TRADE_UPDATE for algo orders
+     *  (STOP_MARKET / TAKE_PROFIT_MARKET) until they trigger — only the resulting
+     *  regular order fires the event. As a result, the store cannot observe algo
+     *  add/cancel/modify events via WS alone and diverges from REST whenever
+     *  brackets are touched.
+     *
+     *  This method closes that gap: callers (the controller's refresh loop) hand
+     *  it the current REST view of algo orders, and we swap them in wholesale
+     *  while leaving regular orders (WS-tracked) untouched. An order is classed
+     *  as "algo" iff its clientOrderId parses as a reefclaw bracket cid with
+     *  role stop or target. External algo orders (manual STOP_MARKET placed via
+     *  Binance UI with no rc- prefix) are NOT tracked by this path — the 60s
+     *  reconciler snapshot still covers them. */
+    replaceAlgoOrders(freshAlgoOrders) {
+        let removedStale = 0;
+        for (const [id, order] of this.orders) {
+            if (isAlgoBracketOrder(order)) {
+                this.orders.delete(id);
+                removedStale++;
+            }
+        }
+        let addedFresh = 0;
+        for (const o of freshAlgoOrders) {
+            if (!o.id || o.status !== 'open')
+                continue;
+            if (!isAlgoBracketOrder(o))
+                continue;
+            this.orders.set(o.id, cloneOrder(o));
+            addedFresh++;
+        }
+        if (removedStale !== addedFresh) {
+            logger.info('live-state-store', `replaceAlgoOrders: ${removedStale} removed, ${addedFresh} added`);
+        }
+        this.emit('stateChanged', 'algo_refresh');
+    }
+    /** Refresh ONLY the mark-derived soft fields (markPrice + unrealizedPnl) of
+     *  positions that already exist in the store, from a fresh REST snapshot.
+     *
+     *  Why this exists: Binance's user-data `ACCOUNT_UPDATE` is event-driven
+     *  (fills / funding / transfers) and carries NO per-tick mark price, so a
+     *  quiet open position's `unrealizedPnl` in this store is FROZEN at the last
+     *  event's value while the Binance app recomputes uPnl every mark tick. In
+     *  enforce/observe mode this store is the authoritative read path, so the
+     *  dashboard's Unrealized cell froze between events ("close but lags/frozen"
+     *  — 2026-05-16). The controller's 60s truth-check already fetches a fresh
+     *  REST snapshot (with live uPnl + mark) but DISCARDS it unless position
+     *  structure drifts (diffPositions ignores uPnl entirely). This method lets
+     *  the truth-check spend that already-paid REST read on a uPnl refresh
+     *  instead of throwing it away — bounding uPnl staleness to the 60s interval
+     *  rather than "until the next trade/funding event".
+     *
+     *  Strictly bounded — this is NOT applySnapshot:
+     *   - only mutates positions present in BOTH the store and the fresh REST
+     *     list with the SAME symbol AND side (structural changes are the
+     *     truth-check's job, not this method's);
+     *   - never adds, never removes, never touches balance or orders;
+     *   - so it cannot reintroduce the null≠empty / stale-as-truth collapse
+     *     class (callers only reach here with a non-null REST snapshot anyway —
+     *     buildSnapshot throws UntrustedSnapshotError on a failed fetch). */
+    refreshDerivedMarkFields(restPositions) {
+        let refreshed = 0;
+        for (const rp of restPositions) {
+            if (rp.contracts <= 0)
+                continue;
+            const lp = this.positions.get(rp.symbol);
+            if (!lp || lp.side !== rp.side)
+                continue; // structural change → leave for truth-check
+            if (lp.markPrice === rp.markPrice && lp.unrealizedPnl === rp.unrealizedPnl)
+                continue;
+            this.positions.set(rp.symbol, {
+                ...lp,
+                markPrice: rp.markPrice,
+                unrealizedPnl: rp.unrealizedPnl,
+            });
+            refreshed++;
+        }
+        if (refreshed > 0) {
+            this.emit('stateChanged', 'mark_refresh');
+        }
+    }
+    /** Apply an ACCOUNT_UPDATE event (positions + balance deltas). */
+    applyAccountUpdate(ev) {
+        for (const pos of ev.positions) {
+            // Refuse hedge-mode position events — v1 is one-way. `BOTH` is one-way;
+            // `LONG`/`SHORT` on a one-way account shouldn't happen but if it does
+            // we warn and still apply by symbol.
+            if (pos.positionSide === 'LONG' || pos.positionSide === 'SHORT') {
+                logger.warn(TAG, `Hedge-mode position event received for ${pos.symbol} (positionSide=${pos.positionSide}) — v1 is one-way only`);
+                this.emit('applyError', 'hedge_mode_position', `${pos.symbol} positionSide=${pos.positionSide}`);
+                // Fall through: still apply per symbol. Reconciler will catch drift.
+            }
+            if (pos.side === 'flat' || pos.quantity <= 0) {
+                this.positions.delete(pos.symbol);
+            }
+            else {
+                const existing = this.positions.get(pos.symbol);
+                // Preserve metadata fields we don't receive via WS (setupType, thesis,
+                // stopPrice, etc). They're set at open time by the plugin itself, not
+                // by Binance. WS updates carry the numeric state; metadata carries over.
+                const merged = {
+                    symbol: pos.symbol,
+                    side: pos.side,
+                    contracts: pos.quantity,
+                    contractSize: existing?.contractSize ?? 1,
+                    entryPrice: pos.entryPrice,
+                    markPrice: existing?.markPrice ?? pos.entryPrice,
+                    notional: pos.quantity * pos.entryPrice,
+                    unrealizedPnl: pos.unrealizedPnl,
+                    percentage: existing?.percentage ?? 0,
+                    timestamp: ev.eventTime,
+                    datetime: new Date(ev.eventTime).toISOString(),
+                    // Carry-over metadata
+                    setupType: existing?.setupType,
+                    thesis: existing?.thesis,
+                    stopPrice: existing?.stopPrice,
+                    targetPrice: existing?.targetPrice,
+                    regime: existing?.regime,
+                    regimeConfidence: existing?.regimeConfidence,
+                    scorecardVerdict: existing?.scorecardVerdict,
+                    confluenceScore: existing?.confluenceScore,
+                };
+                this.positions.set(pos.symbol, merged);
+            }
+        }
+        for (const bal of ev.balances) {
+            if (bal.walletBalance <= 0 && (this.balances.get(bal.asset)?.used ?? 0) <= 0) {
+                // Zero wallet and no reserved margin: drop the asset so getBalance()
+                // doesn't return a forest of empty entries.
+                this.balances.delete(bal.asset);
+            }
+            else {
+                const prev = this.balances.get(bal.asset);
+                const used = prev?.used ?? 0;
+                // `free` is derived — Binance's WS balance-change doesn't include
+                // free/used split. We keep whatever `used` we already had (margin
+                // lockup changes through position events, not balance events) and
+                // compute `free = total - used`.
+                const total = bal.walletBalance;
+                const free = Math.max(0, total - used);
+                this.balances.set(bal.asset, { free, used, total });
+            }
+        }
+        this.lastAccountUpdateAt = ev.eventTime;
+        this.emit('stateChanged', 'account_update');
+    }
+    /** Apply an ORDER_TRADE_UPDATE event (single order state transition). */
+    applyOrderUpdate(ev) {
+        const key = ev.orderId;
+        if (ev.status === 'closed' || ev.status === 'canceled') {
+            // Terminal — remove from open-orders view.
+            this.orders.delete(key);
+        }
+        else {
+            // open (NEW or PARTIALLY_FILLED)
+            const existing = this.orders.get(key);
+            const cctxType = ev.type === 'limit' ? 'limit' : 'market';
+            const merged = {
+                id: ev.orderId,
+                symbol: ev.symbol,
+                side: ev.side,
+                type: cctxType,
+                status: 'open',
+                amount: ev.origQuantity,
+                filled: ev.cumulativeFilled,
+                remaining: Math.max(0, ev.origQuantity - ev.cumulativeFilled),
+                average: ev.avgPrice,
+                price: ev.origPrice,
+                cost: ev.cumulativeFilled * (ev.avgPrice ?? 0),
+                fee: existing?.fee ?? { cost: ev.commission, currency: ev.commissionAsset },
+                timestamp: ev.transactionTime,
+                datetime: new Date(ev.transactionTime).toISOString(),
+                timeInForce: ev.timeInForce,
+                clientOrderId: ev.clientOrderId,
+            };
+            this.orders.set(key, merged);
+        }
+        this.lastOrderUpdateAt = ev.eventTime;
+        this.emit('stateChanged', 'order_update');
+    }
+    /** Clear all state. Used on shutdown/reset. */
+    reset() {
+        this.positions.clear();
+        this.balances.clear();
+        this.orders.clear();
+        this.lastSnapshotAt = null;
+        this.lastAccountUpdateAt = null;
+        this.lastOrderUpdateAt = null;
+    }
+    // ---- Drift detection (60s truth-check) ----
+    /** Diff local state vs a fresh REST snapshot. Classifies drifts by severity
+     *  so the parent reconciler can decide: log-only (minor) vs forced resync (major). */
+    diffAgainstSnapshot(rest) {
+        const positions = this.diffPositions(rest.positions);
+        const balance = this.diffBalance(rest.balance);
+        const orders = this.diffOrders(rest.openOrders);
+        // Severity rollup
+        const hasMajorPosition = positions.some(p => p.kind === 'new' || p.kind === 'closed' || p.kind === 'side_changed' ||
+            Math.abs(p.localContracts - p.restContracts) > this.thresholds.positionMinorContracts);
+        const hasMajorBalance = balance.some(b => Math.abs(b.deltaBps) >= this.thresholds.balanceMinorBps);
+        const hasMajorOrder = orders.length > 0; // any order mismatch is major — small-N
+        let severity = 'none';
+        if (hasMajorPosition || hasMajorBalance || hasMajorOrder) {
+            severity = 'major';
+        }
+        else if (positions.length > 0 || balance.length > 0) {
+            severity = 'minor';
+        }
+        const summary = severity === 'none'
+            ? 'no drift'
+            : `${positions.length} position / ${balance.length} balance / ${orders.length} order diffs`;
+        return { severity, positions, balance, orders, summary };
+    }
+    diffPositions(rest) {
+        const drifts = [];
+        const restMap = new Map(rest.filter(p => p.contracts > 0).map(p => [p.symbol, p]));
+        for (const [symbol, rp] of restMap) {
+            const lp = this.positions.get(symbol);
+            if (!lp) {
+                drifts.push({
+                    symbol,
+                    localContracts: 0, restContracts: rp.contracts,
+                    localSide: null, restSide: rp.side,
+                    kind: 'new',
+                });
+            }
+            else if (lp.side !== rp.side) {
+                drifts.push({
+                    symbol,
+                    localContracts: lp.contracts, restContracts: rp.contracts,
+                    localSide: lp.side, restSide: rp.side,
+                    kind: 'side_changed',
+                });
+            }
+            else if (Math.abs(lp.contracts - rp.contracts) > this.thresholds.positionMinorContracts) {
+                drifts.push({
+                    symbol,
+                    localContracts: lp.contracts, restContracts: rp.contracts,
+                    localSide: lp.side, restSide: rp.side,
+                    kind: 'size_changed',
+                });
+            }
+        }
+        for (const [symbol, lp] of this.positions) {
+            if (!restMap.has(symbol)) {
+                drifts.push({
+                    symbol,
+                    localContracts: lp.contracts, restContracts: 0,
+                    localSide: lp.side, restSide: null,
+                    kind: 'closed',
+                });
+            }
+        }
+        return drifts;
+    }
+    diffBalance(rest) {
+        const drifts = [];
+        if (!rest)
+            return drifts;
+        const restTotals = rest.total ?? {};
+        const seen = new Set();
+        for (const asset of Object.keys(restTotals)) {
+            seen.add(asset);
+            const restTotal = restTotals[asset] ?? 0;
+            const local = this.balances.get(asset);
+            const localTotal = local?.total ?? 0;
+            if (Math.abs(localTotal - restTotal) < 1e-10)
+                continue;
+            const denom = Math.abs(restTotal) > 1e-10 ? Math.abs(restTotal) : 1;
+            const deltaBps = ((localTotal - restTotal) / denom) * 10_000;
+            drifts.push({ asset, localTotal, restTotal, deltaBps });
+        }
+        for (const [asset, b] of this.balances) {
+            if (seen.has(asset))
+                continue;
+            // Asset present locally but absent from REST
+            if (b.total > 1e-10) {
+                drifts.push({
+                    asset, localTotal: b.total, restTotal: 0,
+                    deltaBps: 10_000, // effectively infinite divergence
+                });
+            }
+        }
+        return drifts;
+    }
+    diffOrders(rest) {
+        const drifts = [];
+        const restMap = new Map(rest.filter(o => o.status === 'open' && o.id).map(o => [o.id, o]));
+        for (const [id, ro] of restMap) {
+            if (!this.orders.has(id)) {
+                drifts.push({ orderId: id, symbol: ro.symbol, kind: 'missing_locally' });
+            }
+        }
+        for (const [id, lo] of this.orders) {
+            if (!restMap.has(id)) {
+                drifts.push({ orderId: id, symbol: lo.symbol, kind: 'missing_on_rest' });
+            }
+        }
+        return drifts;
+    }
+}
+// ---- Clone helpers ----
+function clonePosition(p) {
+    return { ...p };
+}
+function cloneOrder(o) {
+    return { ...o, fee: { ...o.fee } };
+}
+/** True iff an order is a reefclaw-managed bracket SL/TP (i.e. an algo order
+ *  we track). Regular entries with bracket-cid role 'entry' are NOT algo;
+ *  they fire normal ORDER_TRADE_UPDATE events and stay in the store via WS. */
+function isAlgoBracketOrder(o) {
+    if (!o.clientOrderId)
+        return false;
+    const parsed = parseBracketCid(o.clientOrderId);
+    return parsed !== null && (parsed.role === 'stop' || parsed.role === 'target');
+}

package/live/local-signal-service.d.ts

@@ -0,0 +1,57 @@
+import { FactSubscriber } from './fact-subscriber.js';
+import { type EvaluatorParams } from './local-strategy-evaluator.js';
+import type { StrategyConfig, SignalSnapshot } from '@reefclaw/shared';
+export interface LocalSignalServiceOptions {
+    intelligenceUrl: string;
+    connectionToken: string;
+    /** Symbols to stream + evaluate locally. */
+    symbols: string[];
+    params?: EvaluatorParams;
+    /** Strategy mirror refresh cadence (default 10 min). */
+    strategyRefreshMs?: number;
+    /** Local evaluation cadence (default 5s — matches the central engine). */
+    evalIntervalMs?: number;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests. */
+    now?: () => number;
+    /** Max age of a symbol's streamed fact before getSnapshot refuses to serve
+     *  it (default 60s = 12× the broadcaster's 5s cadence). A stale fact means
+     *  the stream is stalled/down — enforce-mode get_signals must fall back to
+     *  central rather than serve signals computed from old market data. */
+    factStalenessMs?: number;
+}
+export declare class LocalSignalService {
+    private readonly opts;
+    private readonly subscriber;
+    private readonly evaluator;
+    private readonly params;
+    private readonly doFetch;
+    private readonly now;
+    private strategies;
+    private readonly statesCache;
+    private readonly recent;
+    private strategyTimer;
+    private evalTimer;
+    constructor(opts: LocalSignalServiceOptions);
+    private factIsFresh;
+    start(): Promise<void>;
+    stop(): void;
+    /** Latest locally-computed snapshot for a symbol, or null if no fact +
+     *  evaluation has happened yet OR the symbol's streamed fact has gone
+     *  stale (caller should fall back to central in both cases). */
+    getSnapshot(symbol: string): SignalSnapshot | null;
+    hasSnapshot(symbol: string): boolean;
+    getStats(): {
+        strategies: number;
+        symbolsEvaluated: number;
+        subscriber: ReturnType<FactSubscriber['getStats']>;
+    };
+    /** One evaluation cycle across all streamed symbols (mirrors the engine tick). */
+    evalAll(): Promise<void>;
+    private refreshStrategies;
+    /** Test seam — set strategies without an HTTP fetch. */
+    __setStrategiesForTest(s: StrategyConfig[]): void;
+    /** Test seam — feed a raw SSE chunk to the subscriber. */
+    __ingestForTest(chunk: string): void;
+}

package/live/local-signal-service.js

@@ -0,0 +1,146 @@
+// Local signal service — facts-out (docs/FACTS_OUT_ARCHITECTURE.md) step 5.
+//
+// Runs the central signal engine's job LOCALLY in the plugin: subscribes to the
+// intel fact stream, mirrors the user's strategy configs (GET /api/strategies),
+// and evaluates them every ~5s with the shared LocalStrategyEvaluator — caching
+// per-symbol states + a recent-signals ring exactly like the central engine.
+// getSnapshot(symbol) returns the same SignalSnapshot shape get_signals serves.
+//
+// Gated by plugin-config `signals.evaluator` (central | shadow | enforce):
+//   central (default) — service never created; get_signals calls intel as today.
+//   shadow            — service runs; get_signals still returns central but logs
+//                       the local snapshot for comparison. Zero behaviour change.
+//   enforce           — get_signals returns the local snapshot (falling back to
+//                       central when no fact has arrived for that symbol yet).
+import { FactSubscriber } from './fact-subscriber.js';
+import { LocalStrategyEvaluator, DEFAULT_EVALUATOR_PARAMS } from './local-strategy-evaluator.js';
+const RECENT_RING = 50;
+const DEFAULT_FACT_STALENESS_MS = 60_000;
+export class LocalSignalService {
+    opts;
+    subscriber;
+    evaluator = new LocalStrategyEvaluator();
+    params;
+    doFetch;
+    now;
+    strategies = [];
+    statesCache = new Map();
+    recent = new Map();
+    strategyTimer = null;
+    evalTimer = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.params = opts.params ?? DEFAULT_EVALUATOR_PARAMS;
+        this.doFetch = opts.fetchImpl ?? fetch;
+        this.now = opts.now ?? Date.now;
+        this.subscriber = new FactSubscriber({
+            baseUrl: opts.intelligenceUrl,
+            token: opts.connectionToken,
+            symbols: opts.symbols,
+            fetchImpl: opts.fetchImpl,
+            now: opts.now,
+        });
+    }
+    factIsFresh(symbol) {
+        const at = this.subscriber.getLatestFactAt(symbol);
+        if (at === null)
+            return false;
+        return this.now() - at <= (this.opts.factStalenessMs ?? DEFAULT_FACT_STALENESS_MS);
+    }
+    async start() {
+        await this.refreshStrategies();
+        this.strategyTimer = setInterval(() => void this.refreshStrategies(), this.opts.strategyRefreshMs ?? 600_000);
+        this.evalTimer = setInterval(() => void this.evalAll(), this.opts.evalIntervalMs ?? 5_000);
+        // Don't let the background timers hold the process open during shutdown.
+        this.strategyTimer.unref?.();
+        this.evalTimer.unref?.();
+        this.subscriber.start();
+    }
+    stop() {
+        if (this.strategyTimer) {
+            clearInterval(this.strategyTimer);
+            this.strategyTimer = null;
+        }
+        if (this.evalTimer) {
+            clearInterval(this.evalTimer);
+            this.evalTimer = null;
+        }
+        this.subscriber.stop();
+    }
+    /** Latest locally-computed snapshot for a symbol, or null if no fact +
+     *  evaluation has happened yet OR the symbol's streamed fact has gone
+     *  stale (caller should fall back to central in both cases). */
+    getSnapshot(symbol) {
+        const states = this.statesCache.get(symbol);
+        if (!states)
+            return null;
+        if (!this.factIsFresh(symbol))
+            return null;
+        return {
+            activeStrategies: states,
+            recentSignals: this.recent.get(symbol) ?? [],
+            timestamp: new Date(this.now()).toISOString(),
+            scope: 'local',
+        };
+    }
+    hasSnapshot(symbol) {
+        return this.statesCache.has(symbol);
+    }
+    getStats() {
+        return {
+            strategies: this.strategies.length,
+            symbolsEvaluated: this.statesCache.size,
+            subscriber: this.subscriber.getStats(),
+        };
+    }
+    /** One evaluation cycle across all streamed symbols (mirrors the engine tick). */
+    async evalAll() {
+        if (this.strategies.length === 0)
+            return;
+        const now = this.now();
+        for (const symbol of this.opts.symbols) {
+            const ctx = this.subscriber.getLatest(symbol);
+            if (!ctx)
+                continue;
+            // Don't re-evaluate stale contexts — getSnapshot refuses them anyway.
+            if (!this.factIsFresh(symbol))
+                continue;
+            const { states, signals } = await this.evaluator.evaluateSnapshot(ctx, this.strategies, now, this.params);
+            this.statesCache.set(symbol, states);
+            if (signals.length > 0) {
+                const ring = this.recent.get(symbol) ?? [];
+                ring.unshift(...signals);
+                if (ring.length > RECENT_RING)
+                    ring.length = RECENT_RING;
+                this.recent.set(symbol, ring);
+            }
+        }
+    }
+    async refreshStrategies() {
+        try {
+            const resp = await this.doFetch(`${this.opts.intelligenceUrl}/api/strategies?active=true`, {
+                headers: { Authorization: `Bearer ${this.opts.connectionToken}` },
+            });
+            if (!resp.ok)
+                return;
+            const body = (await resp.json());
+            const configs = (body.strategies ?? [])
+                .map((r) => r.config)
+                .filter((c) => !!c);
+            // Keep last-known strategies if the fetch returned an empty/garbage set.
+            if (configs.length > 0)
+                this.strategies = configs;
+        }
+        catch {
+            /* keep last-known strategies — fail-open */
+        }
+    }
+    /** Test seam — set strategies without an HTTP fetch. */
+    __setStrategiesForTest(s) {
+        this.strategies = s;
+    }
+    /** Test seam — feed a raw SSE chunk to the subscriber. */
+    __ingestForTest(chunk) {
+        this.subscriber.ingest(chunk);
+    }
+}