@reefclaw/openclaw-plugin 0.1.0

package/simulator/exchange-simulator.js

@@ -0,0 +1,684 @@
+// 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,
+                    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.`);
+            }
+            return this.executeMarketFill(order, ticker.last, metadata);
+        }
+        // Limit order — check if it crosses the current price
+        const ticker = this.lastTicker.get(symbol);
+        if (ticker && 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 ----
+    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);
+        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,
+        });
+        return this.toCcxtOrder(result.order);
+    }
+    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',
+        };
+    }
+}