@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/simulator/exchange-simulator.js

@@ -1,759 +0,0 @@
-// In-memory exchange simulator.
-// Maintains wallet, positions, open orders, and trade history.
-// Emits 'stateChanged' event for persistence.
-//
-// Phase 9a: Supports realistic fills (book-aware VWAP, latency, maker/taker fees)
-// via SimulationConfig and OrderBookDepth.
-import { EventEmitter } from 'node:events';
-import { randomUUID } from 'node:crypto';
-import { logger } from '../logger.js';
-import { MAX_TRADE_HISTORY, DEFAULT_SIMULATION_CONFIG } from './types.js';
-import { fillMarketOrder, fillLimitOrder, parseSymbol } from './fill-engine.js';
-import { updateMfe } from '../mfe.js';
-import { computeInvalidationHit } from '../pinned-plan.js';
-const TAG = 'simulator';
-export class ExchangeSimulator extends EventEmitter {
-    state;
-    lastTicker = new Map();
-    lastOrderBook = new Map();
-    simulationConfig;
-    /** Metadata for pending limit orders, keyed by order ID. Cleaned up on fill/cancel. */
-    pendingOrderMetadata = new Map();
-    // ---- Volatility caching (set by plugin after market structure fetch) ----
-    cachedVolFactor = 1.0;
-    baselineAtr = 0;
-    atrSampleCount = 0;
-    // ---- Startup trade lockout ----
-    // Prevents stale agent sessions from executing trades during gateway restart.
-    // Without this, the agent resumes mid-action and sells positions it doesn't remember.
-    startupTime = Date.now();
-    hadPositionsAtStartup;
-    static STARTUP_LOCKOUT_MS = 15_000; // 15 seconds
-    constructor(initialState, config) {
-        super();
-        this.state = initialState;
-        this.simulationConfig = config ?? DEFAULT_SIMULATION_CONFIG;
-        this.hadPositionsAtStartup = initialState.positions.length > 0;
-        if (this.hadPositionsAtStartup) {
-            logger.info(TAG, `Startup lockout ACTIVE for 15s — ${initialState.positions.length} existing position(s) protected`);
-        }
-        logger.info(TAG, `Simulator initialized: ${this.state.positions.length} positions, ${this.state.openOrders.length} open orders (realistic fills enabled)`);
-    }
-    // ---- Simulation config ----
-    getSimulationConfig() {
-        return this.simulationConfig;
-    }
-    // ---- Volatility factor accessors ----
-    setVolFactor(factor) {
-        this.cachedVolFactor = factor;
-    }
-    getVolFactor() {
-        return this.cachedVolFactor;
-    }
-    /** Update baseline ATR using exponential moving average of samples. */
-    updateBaselineAtr(atr14) {
-        if (atr14 <= 0)
-            return;
-        this.atrSampleCount++;
-        if (this.baselineAtr === 0) {
-            this.baselineAtr = atr14;
-        }
-        else {
-            // EMA with alpha = 2/(n+1), capped at 20 samples for stability
-            const n = Math.min(this.atrSampleCount, 20);
-            const alpha = 2 / (n + 1);
-            this.baselineAtr = alpha * atr14 + (1 - alpha) * this.baselineAtr;
-        }
-    }
-    getBaselineAtr() {
-        return this.baselineAtr;
-    }
-    // ---- Session start NAV ----
-    /**
-     * Returns today's session-start NAV, lazily seeding it from current equity
-     * if unset or stale (different UTC day). This is the plugin-side anchor used
-     * by the pre-trade risk gate; a stale/missing anchor silently disables the
-     * drawdown zones, so callers must never see a zero.
-     */
-    getSessionStartNav() {
-        this.ensureSessionAnchor();
-        return this.state.sessionStartNav ?? 0;
-    }
-    setSessionStartNav(nav) {
-        const today = new Date().toISOString().slice(0, 10);
-        if (this.state.sessionDate !== today || this.state.sessionStartNav === undefined) {
-            this.state.sessionStartNav = nav;
-            this.state.sessionDate = today;
-            this.emitStateChanged();
-        }
-    }
-    /** Seed sessionStartNav from current equity on the first check of each UTC day.
-     *  Safe to call repeatedly — no-op once the anchor matches today's date. */
-    ensureSessionAnchor() {
-        const today = new Date().toISOString().slice(0, 10);
-        if (this.state.sessionDate === today && this.state.sessionStartNav !== undefined) {
-            return;
-        }
-        const equity = this.computeEquity();
-        this.state.sessionStartNav = equity;
-        this.state.sessionDate = today;
-        logger.info(TAG, `Session NAV anchored: $${equity.toFixed(2)} for ${today} (was: date=${this.state.sessionDate ?? 'none'}, nav=${this.state.sessionStartNav ?? 'none'})`);
-        this.emitStateChanged();
-    }
-    /** Mark-to-market equity = walletTotal + for each open position, the
-     *  collateral locked at entry + current unrealized P&L. Paper simulator is
-     *  SPOT-collateral style: the full entry notional was deducted from wallet
-     *  on open and is released on close, so we must add it back here. */
-    computeEquity() {
-        const quote = this.getQuoteCurrency();
-        const walletTotal = this.state.wallet[quote]?.total ?? 0;
-        let positionEquity = 0;
-        for (const pos of this.state.positions) {
-            const ticker = this.lastTicker.get(pos.symbol);
-            const mark = ticker?.last ?? pos.entryPrice;
-            const entryNotional = pos.entryPrice * pos.quantity;
-            const unrealized = pos.side === 'long'
-                ? (mark - pos.entryPrice) * pos.quantity
-                : (pos.entryPrice - mark) * pos.quantity;
-            positionEquity += entryNotional + unrealized;
-        }
-        return walletTotal + positionEquity;
-    }
-    getQuoteCurrency() {
-        return this.state.config?.quoteCurrency ?? 'USDT';
-    }
-    // ---- Read operations (for tools) ----
-    getBalance() {
-        const free = {};
-        const used = {};
-        const total = {};
-        const result = { free, used, total };
-        // Derivatives model: only quote currency (USDT) in wallet
-        for (const [currency, bal] of Object.entries(this.state.wallet)) {
-            free[currency] = bal.available;
-            used[currency] = bal.locked;
-            total[currency] = bal.total;
-            result[currency] = {
-                free: bal.available,
-                used: bal.locked,
-                total: bal.total,
-            };
-        }
-        // All-time realized P&L from trade history (restart-proof).
-        // Includes BOTH open-side and close-side fees — prior versions omitted the
-        // open-side fee and under-reported fee drag by ~50%.
-        let realizedPnlAllTime = 0;
-        let totalRoundtripFees = 0;
-        const today = new Date().toISOString().slice(0, 10);
-        let realizedPnlToday = 0;
-        for (const t of this.state.tradeHistory) {
-            const roundtripFee = t.fee + (t.openFee ?? 0);
-            const net = t.realizedPnl - roundtripFee;
-            realizedPnlAllTime += net;
-            totalRoundtripFees += roundtripFee;
-            if (typeof t.closedAt === 'string' && t.closedAt.slice(0, 10) === today) {
-                realizedPnlToday += net;
-            }
-        }
-        const round4 = (n) => +n.toFixed(4);
-        result.realizedPnlAllTime = round4(realizedPnlAllTime);
-        result.realizedPnlToday = round4(realizedPnlToday);
-        result.totalRoundtripFees = round4(totalRoundtripFees);
-        // Session execution-quality costs (since boot) for the dashboard cost cells
-        // (M1). These are the SAME fees/slippage already baked into equity/NAV —
-        // surfaced so the "Fees" / "Avg Slip" breakdown cells don't read $0 while
-        // the headline PnL clearly shows the drag.
-        const execStats = this.state.executionStats;
-        result.sessionFeesPaid = round4(execStats?.totalFeesPaid ?? 0);
-        result.sessionAvgSlippageBps = round4(execStats?.avgSlippageBps ?? 0);
-        // Equity = mark-to-market total account value. Use this (NOT walletTotal)
-        // for heat / leverage / exposure math — walletTotal drops as notional is
-        // locked into open positions, but that collateral is released on close.
-        const equity = this.computeEquity();
-        result.equity = round4(equity);
-        // Session anchor (for drawdown zone calculation). Side-effect: seeds on
-        // first read each UTC day if stale/missing.
-        const sessionNav = this.getSessionStartNav();
-        result.sessionStartNav = round4(sessionNav);
-        return result;
-    }
-    getPositions(symbol) {
-        const positions = symbol
-            ? this.state.positions.filter(p => p.symbol === symbol)
-            : this.state.positions;
-        return positions.map(p => {
-            const ticker = this.lastTicker.get(p.symbol);
-            const markPrice = ticker?.last ?? p.entryPrice;
-            const notional = p.quantity * markPrice;
-            const pnlMultiplier = p.side === 'long' ? 1 : -1;
-            const unrealizedPnl = (markPrice - p.entryPrice) * p.quantity * pnlMultiplier;
-            const percentage = p.entryPrice > 0
-                ? ((markPrice - p.entryPrice) / p.entryPrice) * 100 * pnlMultiplier
-                : 0;
-            return {
-                symbol: p.symbol,
-                side: p.side,
-                contracts: p.quantity,
-                contractSize: 1,
-                entryPrice: p.entryPrice,
-                markPrice,
-                notional,
-                unrealizedPnl,
-                percentage,
-                timestamp: Date.now(),
-                datetime: new Date().toISOString(),
-                // Surface entry metadata (if available)
-                ...(p.metadata && {
-                    setupType: p.metadata.setupType,
-                    missionId: p.metadata.missionId,
-                    candidateId: p.metadata.candidateId,
-                    strategy: p.metadata.strategy,
-                    accruedFundingUsd: p.metadata.accruedFundingUsd,
-                    fundingThroughTime: p.metadata.fundingThroughTime,
-                    thesis: p.metadata.thesis,
-                    stopPrice: p.metadata.stopPrice,
-                    targetPrice: p.metadata.targetPrice,
-                    regime: p.metadata.regime,
-                    regimeConfidence: p.metadata.regimeConfidence,
-                    scorecardVerdict: p.metadata.scorecardVerdict,
-                    confluenceScore: p.metadata.confluenceScore,
-                    originalStopPrice: p.metadata.originalStopPrice,
-                    mfePeakPrice: p.metadata.mfePeakPrice,
-                    mfeR: p.metadata.mfeR,
-                    giveBackRatio: p.metadata.giveBackRatio,
-                    invalidationPrice: p.metadata.invalidationPrice,
-                    realizationRule: p.metadata.realizationRule,
-                    invalidationHit: computeInvalidationHit(p.side, markPrice, p.metadata.invalidationPrice),
-                }),
-            };
-        });
-    }
-    getOpenOrders(symbol) {
-        const orders = symbol
-            ? this.state.openOrders.filter(o => o.symbol === symbol)
-            : this.state.openOrders;
-        return orders.map(o => this.toCcxtOrder(o));
-    }
-    /** Get cumulative execution quality stats. */
-    getExecutionStats() {
-        return this.state.executionStats;
-    }
-    // ---- Order book ----
-    /** Cache the latest order book snapshot for a symbol. */
-    updateOrderBook(symbol, orderbook) {
-        this.lastOrderBook.set(symbol, orderbook);
-    }
-    getLastOrderBook(symbol) {
-        return this.lastOrderBook.get(symbol);
-    }
-    // ---- Write operations (for tools) ----
-    createOrder(symbol, side, type, amount, price, metadata) {
-        // ---- Startup trade lockout ----
-        // Block trades during the first 15s after gateway restart IF there were
-        // existing positions at startup. This prevents stale agent sessions from
-        // selling positions before the session is cleared and the agent re-reads SKILL.md.
-        // Only activates when positions exist (nothing to protect if starting empty).
-        const elapsed = Date.now() - this.startupTime;
-        if (this.hadPositionsAtStartup && elapsed < ExchangeSimulator.STARTUP_LOCKOUT_MS) {
-            const remaining = Math.ceil((ExchangeSimulator.STARTUP_LOCKOUT_MS - elapsed) / 1000);
-            logger.warn(TAG, `STARTUP LOCKOUT: Blocked ${side} ${amount} ${symbol} — ${remaining}s remaining. This prevents stale session trades during restart.`);
-            throw new Error(`Trade blocked: startup lockout (${remaining}s remaining). The gateway just restarted — wait for the agent to re-read its instructions and check positions before trading.`);
-        }
-        if (amount <= 0) {
-            throw new Error('Order amount must be positive');
-        }
-        if (type === 'limit' && (price === undefined || price <= 0)) {
-            throw new Error('Limit orders require a positive price');
-        }
-        const now = new Date().toISOString();
-        const order = {
-            id: randomUUID(),
-            symbol,
-            side,
-            type,
-            status: 'open',
-            amount,
-            price: type === 'limit' ? price : null,
-            filled: 0,
-            average: null,
-            cost: 0,
-            fee: { cost: 0, currency: parseSymbol(symbol).quote },
-            createdAt: now,
-        };
-        if (type === 'market') {
-            // Market orders fill immediately at current price
-            const ticker = this.lastTicker.get(symbol);
-            if (!ticker) {
-                throw new Error(`No ticker data for ${symbol}. Call updateTicker() first.`);
-            }
-            // Stale-quote guard (issue #202): a market fill priced off an aged quote
-            // books phantom P&L the moment a fresh price arrives (measured up to
-            // ~0.6% off on the HL paper book — a real −$22.99 in 4 seconds). Reject
-            // instead; the agent refreshes via fetch_ticker and retries.
-            this.assertQuoteFresh(symbol, ticker);
-            return this.executeMarketFill(order, ticker.last, metadata);
-        }
-        // Limit order — check if it crosses the current price. A stale quote must
-        // not price an immediate cross-fill (same hazard as market fills); the
-        // order RESTS instead and fills on the next fresh tick via updateTicker.
-        const ticker = this.lastTicker.get(symbol);
-        if (ticker && this.quoteAgeMs(ticker) <= this.maxQuoteAgeMs() && this.shouldFillLimit(order, ticker.last)) {
-            return this.executeLimitFill(order, ticker.last, metadata);
-        }
-        // Limit order doesn't cross — add to open orders. Pin the entry metadata
-        // ONTO the order itself (durable home, persisted in state.json) AND in the
-        // in-memory cache (fast path). order.metadata is the one that survives a
-        // restart / two-process reload, so a resting limit never fills naked.
-        if (metadata) {
-            order.metadata = metadata;
-            this.pendingOrderMetadata.set(order.id, metadata);
-        }
-        this.state.openOrders.push(order);
-        this.emitStateChanged();
-        logger.info(TAG, `Limit order created: ${side} ${amount} ${symbol} @ ${price}`);
-        return this.toCcxtOrder(order);
-    }
-    cancelOrder(orderId) {
-        const idx = this.state.openOrders.findIndex(o => o.id === orderId);
-        if (idx === -1) {
-            throw new Error(`Order not found: ${orderId}`);
-        }
-        const order = this.state.openOrders.splice(idx, 1)[0];
-        order.status = 'canceled';
-        this.pendingOrderMetadata.delete(orderId);
-        this.emitStateChanged();
-        logger.info(TAG, `Order cancelled: ${orderId}`);
-        return this.toCcxtOrder(order);
-    }
-    cancelAllOrders(symbol) {
-        const cancelled = [];
-        const remaining = [];
-        for (const order of this.state.openOrders) {
-            if (!symbol || order.symbol === symbol) {
-                order.status = 'canceled';
-                cancelled.push(order);
-                this.pendingOrderMetadata.delete(order.id);
-            }
-            else {
-                remaining.push(order);
-            }
-        }
-        this.state.openOrders = remaining;
-        if (cancelled.length > 0) {
-            this.emitStateChanged();
-            logger.info(TAG, `Cancelled ${cancelled.length} orders${symbol ? ` for ${symbol}` : ''}`);
-        }
-        return cancelled.map(o => this.toCcxtOrder(o));
-    }
-    closePosition(symbol, closeReason) {
-        const position = this.state.positions.find(p => p.symbol === symbol);
-        if (!position) {
-            throw new Error(`No open position for ${symbol}`);
-        }
-        // Tag the position's metadata with the close reason BEFORE firing the close
-        // order. The closing Trade record copies `existingPosition.metadata` in
-        // fill-engine.executeOrderFill, so this is what makes the reason reach
-        // the trade history (and therefore the agent on its next heartbeat).
-        if (closeReason) {
-            position.metadata = { ...(position.metadata ?? {}), closeReason };
-        }
-        // Create opposing market order to close the position
-        const closeSide = position.side === 'long' ? 'sell' : 'buy';
-        return this.createOrder(symbol, closeSide, 'market', position.quantity);
-    }
-    /** Paper-only: move an open position's MUTABLE protective levels (stopPrice /
-     *  targetPrice) in place and persist, WITHOUT the close+reopen round-trip
-     *  (which pays an extra taker fee and resets the R/MFE denominators). The
-     *  frozen originalStopPrice / originalEntryPrice are intentionally left
-     *  untouched so R-multiples stay anchored at entry. The paper stop-watcher
-     *  and getPositions both read metadata.stopPrice, so a moved stop takes
-     *  effect on the next watcher tick. Throws if there is no open position. (M9) */
-    updatePositionMetadata(symbol, patch) {
-        const pos = this.state.positions.find(p => p.symbol === symbol);
-        if (!pos) {
-            throw new Error(`No open position for ${symbol}`);
-        }
-        const meta = { ...(pos.metadata ?? {}) };
-        if (patch.stopPrice !== undefined)
-            meta.stopPrice = patch.stopPrice;
-        if (patch.targetPrice !== undefined)
-            meta.targetPrice = patch.targetPrice;
-        pos.metadata = meta;
-        this.emitStateChanged();
-    }
-    // ---- Ticker updates (checks pending limit fills) ----
-    updateTicker(ticker) {
-        this.lastTicker.set(ticker.symbol, ticker);
-        this.refreshMfeForSymbol(ticker.symbol, ticker.last);
-        // Check if any pending limit orders should fill
-        const toFill = [];
-        const remaining = [];
-        for (const order of this.state.openOrders) {
-            if (order.symbol === ticker.symbol && this.shouldFillLimit(order, ticker.last)) {
-                toFill.push(order);
-            }
-            else {
-                remaining.push(order);
-            }
-        }
-        if (toFill.length > 0) {
-            this.state.openOrders = remaining;
-            for (const order of toFill) {
-                // Prefer the durable metadata pinned on the order (survives restart);
-                // fall back to the in-memory cache for any legacy in-flight order.
-                const meta = order.metadata ?? this.pendingOrderMetadata.get(order.id);
-                try {
-                    this.executeLimitFill(order, ticker.last, meta);
-                    // Clear the cache only AFTER a successful fill so a throw-then-retry
-                    // (e.g. transient insufficient balance) keeps the metadata for the
-                    // next tick instead of filling naked.
-                    this.pendingOrderMetadata.delete(order.id);
-                }
-                catch (err) {
-                    // Fill failed (e.g. insufficient balance) — restore order to open
-                    // list. order.metadata stays intact, so the retry is not naked.
-                    order.status = 'open';
-                    this.state.openOrders.push(order);
-                    const message = err instanceof Error ? err.message : String(err);
-                    logger.warn(TAG, `Limit fill failed for ${order.id}, order restored: ${message}`);
-                    this.emit('fillError', {
-                        orderId: order.id,
-                        symbol: order.symbol,
-                        error: message,
-                        timestamp: new Date().toISOString(),
-                    });
-                }
-            }
-        }
-    }
-    getLastTicker(symbol) {
-        return this.lastTicker.get(symbol);
-    }
-    /** Walk every position for `symbol` and refresh MFE / give-back from the
-     *  latest mark. Idempotent — pure update of `metadata.mfePeakPrice` (only
-     *  ratchets favourably) plus derived `mfeR` and `giveBackRatio`. Safe to
-     *  call before any positions exist (no-op). */
-    refreshMfeForSymbol(symbol, mark) {
-        if (!Number.isFinite(mark) || mark <= 0)
-            return;
-        let peakAdvanced = false;
-        for (const p of this.state.positions) {
-            if (p.symbol !== symbol)
-                continue;
-            const meta = { ...(p.metadata ?? {}) };
-            const priorPeak = meta.mfePeakPrice;
-            const out = updateMfe({
-                side: p.side,
-                // R/MFE are denominated against the FROZEN original entry (and stop),
-                // never the running averaged entryPrice — otherwise a scale-in
-                // retroactively shrinks an already-achieved excursion (M4).
-                entryPrice: meta.originalEntryPrice ?? p.entryPrice,
-                originalStopPrice: meta.originalStopPrice,
-                markPrice: mark,
-                priorPeakPrice: meta.mfePeakPrice,
-            });
-            if (out.mfePeakPrice !== priorPeak)
-                peakAdvanced = true;
-            meta.mfePeakPrice = out.mfePeakPrice;
-            meta.mfeR = out.mfeR;
-            meta.giveBackRatio = out.giveBackRatio;
-            p.metadata = meta;
-        }
-        // Persist ONLY when a peak strictly advances (M3). The monotone peak moves
-        // less and less over time and debouncedSave coalesces to <=1/s, so this
-        // does not flood — and it is what makes the MFE ratchet survive a restart
-        // and a reloadState() (which previously discarded the unpersisted peak,
-        // feeding a stale/zeroed mfeR to the agent and the exit gate). mfeR /
-        // giveBackRatio are recomputed from the persisted peak on read, so they
-        // don't need a per-tick write.
-        if (peakAdvanced) {
-            this.emitStateChanged();
-        }
-    }
-    // ---- State management ----
-    /** Replace internal state with a fresh copy from disk.
-     *  Used by the gateway process to pick up state saved by the agent process.
-     *
-     *  Non-destructive for the MFE ratchet (M3): the disk copy can lag the live
-     *  peak (refreshMfeForSymbol ratchets every tick; persistence coalesces), so
-     *  a wholesale swap would discard it. For each position present in BOTH
-     *  snapshots (same symbol+side+openedAt) we carry over the MORE-favourable
-     *  monotone peak and recompute mfeR/giveBackRatio from the current mark, so a
-     *  reload never regresses the agent's give-back signal. */
-    replaceState(newState) {
-        // M8: refuse a disk snapshot OLDER than what we already hold in memory.
-        // reloadState() reads disk that lags memory by the debounce window; without
-        // this guard a reload fired within ~1s of a local mutation would revert it
-        // (and a second mutation could then re-persist the reverted state, dropping
-        // a position + its realized PnL). A genuinely newer cross-process write
-        // (savedAt >= ours) still installs. Equal stamps install (idempotent).
-        const incomingAt = newState.savedAt ?? 0;
-        const currentAt = this.state.savedAt ?? 0;
-        if (incomingAt < currentAt) {
-            logger.debug(TAG, `Ignoring stale state reload (disk savedAt=${incomingAt} < memory savedAt=${currentAt})`);
-            return;
-        }
-        const priorPeakByKey = new Map();
-        for (const p of this.state.positions) {
-            if (p.metadata?.mfePeakPrice !== undefined) {
-                priorPeakByKey.set(`${p.symbol}|${p.side}|${p.openedAt}`, p.metadata.mfePeakPrice);
-            }
-        }
-        this.state = newState;
-        for (const p of this.state.positions) {
-            const priorPeak = priorPeakByKey.get(`${p.symbol}|${p.side}|${p.openedAt}`);
-            if (priorPeak === undefined)
-                continue;
-            const meta = { ...(p.metadata ?? {}) };
-            const diskPeak = meta.mfePeakPrice;
-            // Monotone: keep the better of disk vs in-memory (max for long, min short).
-            const keptPeak = diskPeak === undefined
-                ? priorPeak
-                : (p.side === 'long' ? Math.max(priorPeak, diskPeak) : Math.min(priorPeak, diskPeak));
-            const mark = this.lastTicker.get(p.symbol)?.last ?? meta.originalEntryPrice ?? p.entryPrice;
-            const out = updateMfe({
-                side: p.side,
-                entryPrice: meta.originalEntryPrice ?? p.entryPrice,
-                originalStopPrice: meta.originalStopPrice,
-                markPrice: mark,
-                priorPeakPrice: keptPeak,
-            });
-            meta.mfePeakPrice = out.mfePeakPrice;
-            meta.mfeR = out.mfeR;
-            meta.giveBackRatio = out.giveBackRatio;
-            p.metadata = meta;
-        }
-        logger.debug(TAG, `State replaced: ${newState.positions.length} positions, ${newState.openOrders.length} orders`);
-    }
-    getState() {
-        // Spread each element + deep-copy ONLY the nested objects that need
-        // isolation (metadata — which holds the nested realizationRule.scale array
-        // — plus executionQuality and fee). This keeps a consumer mutating the
-        // snapshot, or the JSON-persisted copy, from corrupting live state, while
-        // staying cheap on the hot persistence path: elements without metadata
-        // (the common case) pay only a shallow spread, never a full structuredClone.
-        return {
-            ...this.state,
-            wallet: Object.fromEntries(Object.entries(this.state.wallet).map(([k, v]) => [k, { ...v }])),
-            // Positions + open orders ARE mutated in place (updatePositionMetadata,
-            // refreshMfeForSymbol, scale-in, limit metadata), so deep-copy their
-            // nested metadata to keep a snapshot consumer from corrupting live state.
-            positions: this.state.positions.map(p => ({
-                ...p,
-                metadata: p.metadata ? structuredClone(p.metadata) : undefined,
-            })),
-            openOrders: this.state.openOrders.map(o => ({
-                ...o,
-                fee: { ...o.fee },
-                metadata: o.metadata ? structuredClone(o.metadata) : undefined,
-            })),
-            // Trade records are append-only + immutable after close, so a shallow copy
-            // is safe and keeps getState() O(n)-cheap on the hot persistence path even
-            // with a full 1000-entry history (JSON persistence still deep-serializes).
-            tradeHistory: this.state.tradeHistory.map(t => ({ ...t })),
-            executionStats: this.state.executionStats ? { ...this.state.executionStats } : undefined,
-        };
-    }
-    // ---- Private helpers ----
-    /** Default max quote age a NEW-exposure fill may price against (issue #202).
-     *  Generous vs the 5s paper feed cadence; env RC_PAPER_MAX_QUOTE_AGE_MS
-     *  overrides. */
-    static DEFAULT_MAX_QUOTE_AGE_MS = 45_000;
-    maxQuoteAgeMs() {
-        const raw = Number(process.env.RC_PAPER_MAX_QUOTE_AGE_MS);
-        return Number.isFinite(raw) && raw > 0 ? raw : ExchangeSimulator.DEFAULT_MAX_QUOTE_AGE_MS;
-    }
-    /** Quote age from the ticker's own timestamp. A missing/invalid timestamp
-     *  reads as age 0 (fail-open — the guard cannot fire on it). */
-    quoteAgeMs(ticker) {
-        const ts = ticker.timestamp;
-        if (!Number.isFinite(ts) || ts <= 0)
-            return 0;
-        return Math.max(0, Date.now() - ts);
-    }
-    /** Reject fills that would OPEN or GROW exposure on a stale quote. Risk-
-     *  reducing fills (closes/partials against an existing position) are always
-     *  allowed — blocking a close on a broken feed compounds the risk. */
-    assertQuoteFresh(symbol, ticker) {
-        const age = this.quoteAgeMs(ticker);
-        const max = this.maxQuoteAgeMs();
-        if (age <= max)
-            return;
-        const pos = this.state.positions.find(p => p.symbol === symbol);
-        // The order side reaching here is the one being filled — derive reduce vs
-        // grow from the position side at the call site instead? The market path
-        // calls this before fill with the order side unavailable; use position
-        // presence: any existing position keeps closes flowing, and a stale-quote
-        // scale-in on an open position is bounded by the feed refreshing open
-        // symbols every 5s (only NEW symbols go minutes without a tick).
-        if (pos) {
-            logger.warn(TAG, `Stale quote for ${symbol} (${Math.round(age / 1000)}s old) — allowing fill because an open ` +
-                `position exists (risk-reducing paths are never blocked)`);
-            return;
-        }
-        throw new Error(`Order rejected: market data for ${symbol} is stale (${Math.round(age / 1000)}s old, ` +
-            `max ${Math.round(max / 1000)}s). Refresh the price (fetch_ticker) and retry.`);
-    }
-    shouldFillLimit(order, currentPrice) {
-        if (order.price === null)
-            return false;
-        // BUY limit fills when price <= limit price
-        // SELL limit fills when price >= limit price
-        return order.side === 'buy'
-            ? currentPrice <= order.price
-            : currentPrice >= order.price;
-    }
-    executeMarketFill(order, currentPrice, metadata) {
-        const position = this.state.positions.find(p => p.symbol === order.symbol) ?? null;
-        const orderbook = this.lastOrderBook.get(order.symbol) ?? null;
-        const realistic = {
-            orderbook,
-            config: this.simulationConfig,
-            volFactor: this.cachedVolFactor,
-            metadata,
-        };
-        const result = fillMarketOrder(order, currentPrice, this.state.wallet, position, realistic);
-        // Observability for issue #202: stamp the quote's age onto the fill's
-        // execution-quality record so staleness is visible in trade history.
-        const tickerAtFill = this.lastTicker.get(order.symbol);
-        if (result.executionQuality && tickerAtFill) {
-            result.executionQuality.quoteAgeMs = this.quoteAgeMs(tickerAtFill);
-        }
-        const ccxtOrder = this.applyFillResult(result);
-        const eq = result.executionQuality;
-        if (eq) {
-            logger.info(TAG, `Market order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}` +
-                ` (decision: ${eq.decisionPrice.toFixed(2)}, slippage: ${eq.slippageBps.toFixed(2)}bps` +
-                `, latency: ${eq.latencyMs.toFixed(0)}ms, fee: ${eq.feeRate * 100}%` +
-                `, book: ${eq.bookDepthAvailable ? `${eq.bookLevelsConsumed} levels` : 'unavailable'})`);
-        }
-        else {
-            logger.info(TAG, `Market order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}`);
-        }
-        return ccxtOrder;
-    }
-    executeLimitFill(order, decisionPrice, metadata) {
-        const position = this.state.positions.find(p => p.symbol === order.symbol) ?? null;
-        const result = fillLimitOrder(order, this.state.wallet, position, this.simulationConfig, decisionPrice, metadata);
-        const ccxtOrder = this.applyFillResult(result);
-        const eq = result.executionQuality;
-        if (eq) {
-            logger.info(TAG, `Limit order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}` +
-                ` (maker fee: ${eq.feeRate * 100}%)`);
-        }
-        else {
-            logger.info(TAG, `Limit order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}`);
-        }
-        return ccxtOrder;
-    }
-    /** Apply a fill result: update positions, record trade, track stats, emit state change. */
-    applyFillResult(result) {
-        this.updatePosition(result.order.symbol, result.position);
-        if (result.trade)
-            this.addTrade(result.trade);
-        if (result.executionQuality)
-            this.updateExecutionStats(result.executionQuality);
-        this.emitStateChanged();
-        // Emit fill event for shadow tracker (Phase 9b)
-        this.emit('fill', {
-            trade: result.trade,
-            orderId: result.order.id,
-            symbol: result.order.symbol,
-            side: result.order.side,
-            type: result.order.type,
-            amount: result.order.amount,
-            fillPrice: result.order.average ?? 0,
-            fee: result.order.fee.cost,
-        });
-        const ccxtOrder = this.toCcxtOrder(result.order);
-        // Reducing fills carry a Trade record — attach its engine-exact economics
-        // (net-of-fee P&L + both fee legs) so the journal close capture records
-        // NET, matching the live book's convention (issue #201). The wallet/NAV
-        // was already net; only the journal was blind to fees.
-        if (result.trade) {
-            const t = result.trade;
-            ccxtOrder.info = {
-                ...(ccxtOrder.info ?? {}),
-                paperTrade: {
-                    grossRealizedPnl: t.realizedPnl,
-                    netRealizedPnl: t.realizedPnl - (t.fee + (t.openFee ?? 0)),
-                    openFee: t.openFee ?? 0,
-                    closeFee: t.fee,
-                    ...(typeof t.metadata?.setupType === 'string' ? { setupType: t.metadata.setupType } : {}),
-                },
-            };
-        }
-        return ccxtOrder;
-    }
-    updatePosition(symbol, newPosition) {
-        const idx = this.state.positions.findIndex(p => p.symbol === symbol);
-        if (newPosition) {
-            if (idx >= 0) {
-                this.state.positions[idx] = newPosition;
-            }
-            else {
-                this.state.positions.push(newPosition);
-            }
-        }
-        else if (idx >= 0) {
-            this.state.positions.splice(idx, 1);
-        }
-    }
-    addTrade(trade) {
-        this.state.tradeHistory.push(trade);
-        // Keep only the last MAX_TRADE_HISTORY trades
-        if (this.state.tradeHistory.length > MAX_TRADE_HISTORY) {
-            this.state.tradeHistory = this.state.tradeHistory.slice(-MAX_TRADE_HISTORY);
-        }
-    }
-    /** Update cumulative execution stats from a fill's execution quality. */
-    updateExecutionStats(eq) {
-        if (!this.state.executionStats) {
-            this.state.executionStats = {
-                totalTrades: 0,
-                totalSlippageBps: 0,
-                totalFeesPaid: 0,
-                worstSlippageBps: 0,
-                avgSlippageBps: 0,
-                avgLatencyMs: 0,
-            };
-        }
-        const stats = this.state.executionStats;
-        stats.totalTrades++;
-        const absSlippage = Math.abs(eq.slippageBps);
-        stats.totalSlippageBps += absSlippage;
-        stats.totalFeesPaid += eq.feePaid;
-        if (absSlippage > stats.worstSlippageBps) {
-            stats.worstSlippageBps = absSlippage;
-        }
-        stats.avgSlippageBps = stats.totalSlippageBps / stats.totalTrades;
-        stats.avgLatencyMs =
-            (stats.avgLatencyMs * (stats.totalTrades - 1) + eq.latencyMs) / stats.totalTrades;
-    }
-    emitStateChanged() {
-        // Stamp the mutation time so a stale-disk reloadState() can be detected and
-        // dropped (M8). Must be set BEFORE getState() snapshots the state.
-        this.state.savedAt = Date.now();
-        this.emit('stateChanged', this.getState());
-    }
-    toCcxtOrder(order) {
-        const ts = new Date(order.createdAt).getTime();
-        return {
-            id: order.id,
-            symbol: order.symbol,
-            side: order.side,
-            type: order.type,
-            status: order.status,
-            amount: order.amount,
-            filled: order.filled,
-            remaining: order.amount - order.filled,
-            average: order.average,
-            price: order.price,
-            cost: order.cost,
-            fee: order.fee,
-            timestamp: ts,
-            datetime: order.createdAt,
-            timeInForce: 'GTC',
-        };
-    }
-}