@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/live/live-state-store.js

@@ -1,450 +0,0 @@
-// 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/assets/plugin/live/local-signal-service.d.ts

@@ -1,57 +0,0 @@
-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/assets/plugin/live/local-signal-service.js

@@ -1,151 +0,0 @@
-// 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;
-function isDeclarativeConfig(config) {
-    return config.executionModel === undefined || config.executionModel === 'declarative';
-}
-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());
-            if (!Array.isArray(body.strategies))
-                return;
-            const configs = body.strategies
-                .map((r) => r.config)
-                .filter((c) => !!c && isDeclarativeConfig(c));
-            // A valid empty list means all generic strategies are off (or only a
-            // dedicated portfolio bundle is active), so clear stale generic rows.
-            this.strategies = configs;
-        }
-        catch {
-            /* keep last-known strategies — fail-open */
-        }
-    }
-    /** Test seam — set strategies without an HTTP fetch. */
-    __setStrategiesForTest(s) {
-        this.strategies = s.filter((config) => isDeclarativeConfig(config));
-    }
-    /** Test seam — feed a raw SSE chunk to the subscriber. */
-    __ingestForTest(chunk) {
-        this.subscriber.ingest(chunk);
-    }
-}