@reefclaw/openclaw-plugin 0.1.0

package/logger.d.ts

@@ -0,0 +1,2 @@
+export type { LogLevel } from '@reefclaw/shared';
+export { logger, setLogLevel, formatError } from '@reefclaw/shared';

package/logger.js

@@ -0,0 +1,2 @@
+// Re-export from @reefclaw/shared (canonical source of truth).
+export { logger, setLogLevel, formatError } from '@reefclaw/shared';

package/mfe.d.ts

@@ -0,0 +1,21 @@
+export interface MfeInputs {
+    side: 'long' | 'short';
+    entryPrice: number;
+    /** Stop at fill, frozen. If undefined, MFE-in-R is undefined. */
+    originalStopPrice?: number;
+    /** Latest mark observation. */
+    markPrice: number;
+    /** Prior peak from the last update (undefined on first call). */
+    priorPeakPrice?: number;
+}
+export interface MfeOutputs {
+    /** New peak price after observing this mark. */
+    mfePeakPrice: number;
+    /** Peak in R-multiples. Undefined if originalStopPrice missing. */
+    mfeR?: number;
+    /** Give-back ratio in [0, 1+]. Undefined if peak is not favourable yet. */
+    giveBackRatio?: number;
+}
+/** One-shot update: given current state + new mark, return the new peak,
+ *  R-multiple, and give-back. Pure function — caller persists the result. */
+export declare function updateMfe(input: MfeInputs): MfeOutputs;

package/mfe.js

@@ -0,0 +1,68 @@
+// MFE (Max Favourable Excursion) tracking — pure math, no I/O.
+//
+// Component C of POSITION_MANAGEMENT_PLAN.md. The agent today has no felt
+// sense of "I am leaking edge" because the heartbeat snapshot doesn't carry
+// MFE or give-back. These helpers compute both from the entry-time stop and
+// the running peak, and are wired into the paper simulator's mark-tick path
+// and the live adapter's getPositions decoration.
+//
+// Conventions (confirmed with operator 2026-04-27):
+//  - 1R is denominated against the ORIGINAL stop at fill, frozen for the life
+//    of the position. Ratcheting the live stopPrice does not change R.
+//  - Without an originalStopPrice (e.g. paper position opened without a stop),
+//    `mfeR` and `giveBackRatio` are reported as `undefined` rather than
+//    fabricated from a default risk unit.
+//  - Sign is always favourable: long positions track the highest mark seen,
+//    short positions track the lowest. `mfeR` is non-negative.
+//
+// Edge cases handled:
+//  - Pre-entry tick (entry price not yet observed): caller should not invoke.
+//  - Adverse-only excursion (MFE never positive): `giveBackRatio` is left
+//    `undefined` because the ratio is meaningless when peak <= 0.
+//  - Tied peak (mark equals prior peak): treated as the peak; give-back stays 0.
+/** Compute the favourable distance (always >= 0) between mark and entry. */
+function favourableDelta(side, entry, mark) {
+    return side === 'long' ? mark - entry : entry - mark;
+}
+/** True if `candidate` is at least as favourable as `incumbent` for this side. */
+function atLeastAsFavourable(side, candidate, incumbent) {
+    return side === 'long' ? candidate >= incumbent : candidate <= incumbent;
+}
+/** One-shot update: given current state + new mark, return the new peak,
+ *  R-multiple, and give-back. Pure function — caller persists the result. */
+export function updateMfe(input) {
+    const { side, entryPrice, originalStopPrice, markPrice, priorPeakPrice } = input;
+    if (!Number.isFinite(markPrice) || !Number.isFinite(entryPrice)) {
+        // Caller error — return prior peak unchanged.
+        return {
+            mfePeakPrice: priorPeakPrice ?? entryPrice,
+            mfeR: undefined,
+            giveBackRatio: undefined,
+        };
+    }
+    // Seed peak to entry on first observation, then ratchet only in the
+    // favourable direction.
+    const seedPeak = priorPeakPrice ?? entryPrice;
+    const newPeak = atLeastAsFavourable(side, markPrice, seedPeak) ? markPrice : seedPeak;
+    // Compute R if we have an original stop. R denominator is the at-fill
+    // distance from entry to stop; undefined or non-positive denominator means
+    // we can't report R.
+    const rDenominator = originalStopPrice !== undefined && Number.isFinite(originalStopPrice)
+        ? Math.abs(entryPrice - originalStopPrice)
+        : 0;
+    if (rDenominator <= 0) {
+        return { mfePeakPrice: newPeak, mfeR: undefined, giveBackRatio: undefined };
+    }
+    const peakFavourableDelta = favourableDelta(side, entryPrice, newPeak);
+    const currentFavourableDelta = favourableDelta(side, entryPrice, markPrice);
+    // mfeR is always non-negative — clamp adverse-only positions to 0.
+    const mfeR = Math.max(0, peakFavourableDelta / rDenominator);
+    // Give-back is only meaningful once peak has actually moved into profit.
+    // Negative peak (price went the wrong way and never recovered) → undefined.
+    let giveBackRatio;
+    if (peakFavourableDelta > 0) {
+        const givenBack = peakFavourableDelta - currentFavourableDelta;
+        giveBackRatio = Math.max(0, givenBack / peakFavourableDelta);
+    }
+    return { mfePeakPrice: newPeak, mfeR, giveBackRatio };
+}

package/onboarding/mode-ladder.d.ts

@@ -0,0 +1 @@
+export { validateModeTransition, modeRequiresCredentials, type ModeTransitionResult, } from '@reefclaw/shared';

package/onboarding/mode-ladder.js

@@ -0,0 +1,3 @@
+// Mode ladder — re-exported from @reefclaw/shared so plugin + skill + webapp
+// all use the same source of truth. See shared/src/trading-mode.ts.
+export { validateModeTransition, modeRequiresCredentials, } from '@reefclaw/shared';

package/onboarding/runtime.d.ts

@@ -0,0 +1,71 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { ExchangeConfig, TradingMode } from '../types.js';
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { PaperMarketFeed } from '../simulator/paper-market-feed.js';
+import { PositionWatcher } from '../live/stop-watcher.js';
+export interface MicroLiveConfig {
+    sizeCapPercent?: number;
+    maxPositionUSDT?: number;
+}
+export interface BuildAdapterInput {
+    mode: TradingMode;
+    exchange: ExchangeConfig | null;
+    microLive?: MicroLiveConfig;
+    simulator: ExchangeSimulator;
+}
+/** Pure-ish factory: builds an adapter for the requested mode.
+ *  Falls back to PaperAdapter if a live mode is requested without credentials —
+ *  callers should pre-validate via `modeRequiresCredentials`, but this
+ *  defense-in-depth prevents a crash if validation is bypassed. */
+export declare function buildAdapter(input: BuildAdapterInput): IExchangeAdapter;
+/**
+ * Mutable runtime holder. Held once per plugin registration.
+ *
+ * `adapterBox.adapter` is the indirection point: tool closures read it at
+ * execute time so a swap is visible without re-registering tools.
+ */
+export declare class PluginRuntime {
+    /** Box object so existing `const adapterDeps = { adapter }` patterns still
+     *  work via `adapterDeps.adapter = runtime.adapterBox.adapter`. In practice
+     *  we pass the runtime itself and read `runtime.adapter` at call sites. */
+    private _adapter;
+    private _mode;
+    private _stopWatcher;
+    private readonly simulator;
+    /** Paper-only background market-data feed (refreshes simulator marks so
+     *  stops fire and NAV/uPnL stay live for non-dashboard symbols). Lives for
+     *  the runtime's lifetime; started in paper, stopped in live. */
+    private readonly _marketFeed;
+    /** Reconnect is serialized — a second caller waits for the first to finish
+     *  so we never tear down an adapter that's mid-rebuild. */
+    private reconnectInFlight;
+    constructor(initial: {
+        adapter: IExchangeAdapter;
+        mode: TradingMode;
+        simulator: ExchangeSimulator;
+        stopWatcher?: PositionWatcher | null;
+        marketFeed?: PaperMarketFeed | null;
+    });
+    get adapter(): IExchangeAdapter;
+    get mode(): TradingMode;
+    get stopWatcher(): PositionWatcher | null;
+    get marketFeed(): PaperMarketFeed | null;
+    /**
+     * Swap the current adapter for a new one built from `next`. The old
+     * adapter's background loops are stopped before the new one is wired in.
+     *
+     * `deps.adapterDeps` is the tool-dependency object used by trading tools —
+     * its `.adapter` reference is updated in place so tools see the new adapter
+     * without needing re-registration.
+     */
+    reconnect(next: {
+        mode: TradingMode;
+        exchange: ExchangeConfig | null;
+        microLive?: MicroLiveConfig;
+    }, deps: {
+        adapterDeps: {
+            adapter: IExchangeAdapter;
+        };
+    }): Promise<void>;
+    private doReconnect;
+}

package/onboarding/runtime.js

@@ -0,0 +1,153 @@
+// Plugin runtime holder — the mutable state that survives across a
+// credential/mode swap. The rest of index.ts closes over this object
+// instead of over `let` bindings, so a reconnect can atomically:
+//
+//   1. Stop the live adapter's background loops (order poller + reconciler)
+//   2. Stop the stop-watcher
+//   3. Build a new adapter from updated config
+//   4. Swap `runtime.adapter` in place (closures see the new value)
+//   5. Start a new stop-watcher pointed at the new adapter
+//
+// Doing this without dropping tool registrations or rebuilding the whole
+// plugin is what makes the dashboard "Reconnect Exchange" button feel
+// instant — no gateway restart required.
+import { PaperAdapter } from '../paper-adapter.js';
+import { LiveAdapter } from '../live/live-adapter.js';
+import { PositionWatcher } from '../live/stop-watcher.js';
+import { loadBracketMode } from '../config/brackets-config.js';
+import { logger, formatError } from '../logger.js';
+const TAG = 'plugin-runtime';
+/** Pure-ish factory: builds an adapter for the requested mode.
+ *  Falls back to PaperAdapter if a live mode is requested without credentials —
+ *  callers should pre-validate via `modeRequiresCredentials`, but this
+ *  defense-in-depth prevents a crash if validation is bypassed. */
+export function buildAdapter(input) {
+    const { mode, exchange, microLive, simulator } = input;
+    if (mode === 'PAPER' || mode === 'SHADOW') {
+        // Shadow mode uses a paper adapter for execution; the separate
+        // ShadowTracker wraps a BinancePrivateApi for real-balance comparison.
+        return new PaperAdapter(simulator);
+    }
+    if (!exchange) {
+        logger.warn(TAG, `${mode} requested without credentials — falling back to PAPER`);
+        return new PaperAdapter(simulator);
+    }
+    // Read bracket-mode from plugin-config at adapter build time so a config
+    // flip + "Reconnect Exchange" pattern picks up the new mode on the next swap.
+    const bracketMode = loadBracketMode();
+    return new LiveAdapter(exchange, mode, microLive, bracketMode);
+}
+/**
+ * Mutable runtime holder. Held once per plugin registration.
+ *
+ * `adapterBox.adapter` is the indirection point: tool closures read it at
+ * execute time so a swap is visible without re-registering tools.
+ */
+export class PluginRuntime {
+    /** Box object so existing `const adapterDeps = { adapter }` patterns still
+     *  work via `adapterDeps.adapter = runtime.adapterBox.adapter`. In practice
+     *  we pass the runtime itself and read `runtime.adapter` at call sites. */
+    _adapter;
+    _mode;
+    _stopWatcher = null;
+    simulator;
+    /** Paper-only background market-data feed (refreshes simulator marks so
+     *  stops fire and NAV/uPnL stay live for non-dashboard symbols). Lives for
+     *  the runtime's lifetime; started in paper, stopped in live. */
+    _marketFeed;
+    /** Reconnect is serialized — a second caller waits for the first to finish
+     *  so we never tear down an adapter that's mid-rebuild. */
+    reconnectInFlight = null;
+    constructor(initial) {
+        this._adapter = initial.adapter;
+        this._mode = initial.mode;
+        this.simulator = initial.simulator;
+        this._stopWatcher = initial.stopWatcher ?? null;
+        this._marketFeed = initial.marketFeed ?? null;
+    }
+    get adapter() { return this._adapter; }
+    get mode() { return this._mode; }
+    get stopWatcher() { return this._stopWatcher; }
+    get marketFeed() { return this._marketFeed; }
+    /**
+     * Swap the current adapter for a new one built from `next`. The old
+     * adapter's background loops are stopped before the new one is wired in.
+     *
+     * `deps.adapterDeps` is the tool-dependency object used by trading tools —
+     * its `.adapter` reference is updated in place so tools see the new adapter
+     * without needing re-registration.
+     */
+    async reconnect(next, deps) {
+        // Serialize concurrent reconnects.
+        if (this.reconnectInFlight) {
+            await this.reconnectInFlight;
+        }
+        const run = this.doReconnect(next, deps);
+        this.reconnectInFlight = run.finally(() => {
+            this.reconnectInFlight = null;
+        });
+        await run;
+    }
+    async doReconnect(next, deps) {
+        logger.info(TAG, `Reconnect: ${this._mode} → ${next.mode}`);
+        // 1. Stop old stop-watcher.
+        if (this._stopWatcher) {
+            try {
+                this._stopWatcher.stop();
+            }
+            catch (err) {
+                logger.warn(TAG, `stopWatcher.stop failed: ${formatError(err)}`);
+            }
+            this._stopWatcher = null;
+        }
+        // 2. Tear down old live adapter background loops.
+        const old = this._adapter;
+        if (old instanceof LiveAdapter) {
+            try {
+                old.shutdown();
+            }
+            catch (err) {
+                logger.warn(TAG, `old adapter shutdown failed: ${formatError(err)}`);
+            }
+        }
+        // 3. Build the new adapter.
+        const fresh = buildAdapter({
+            mode: next.mode,
+            exchange: next.exchange,
+            microLive: next.microLive,
+            simulator: this.simulator,
+        });
+        // 4. Fire async init for live adapters (non-blocking — readiness flips
+        //    INIT_PENDING → READY/DEGRADED/BLOCKED on its own).
+        if (fresh instanceof LiveAdapter) {
+            fresh.initialize().catch(err => {
+                logger.error(TAG, `New adapter init failed: ${formatError(err)}`);
+            });
+        }
+        // 5. Atomically publish the new adapter.
+        //    Note: `next.mode` is the operator's intent (e.g. SHADOW), which is
+        //    not always the same as `fresh.mode` — PaperAdapter is used for both
+        //    PAPER and SHADOW execution, and reports its mode as 'PAPER'. The
+        //    runtime tracks the user-facing mode separately so tools that branch
+        //    on SHADOW (e.g. risk summary) keep working.
+        this._adapter = fresh;
+        this._mode = next.mode;
+        deps.adapterDeps.adapter = fresh;
+        // 6. Start a new stop-watcher bound to the new adapter.
+        const watcher = new PositionWatcher(fresh);
+        watcher.start();
+        this._stopWatcher = watcher;
+        // 7. Paper market feed follows the mode: run it when the new adapter is
+        //    paper (so marks/stops/NAV stay live), stop it in live (the live
+        //    adapter sources marks from Binance directly). Idempotent both ways.
+        if (this._marketFeed) {
+            if (fresh.isLive) {
+                this._marketFeed.stop();
+            }
+            else {
+                this._marketFeed.start();
+            }
+        }
+        logger.info(TAG, `Reconnect complete: now in ${this._mode} mode (readiness=${fresh.readiness})`);
+    }
+}

package/openclaw.plugin.json

@@ -0,0 +1,94 @@
+{
+  "id": "reefclaw-paper-trading",
+  "name": "ReefClaw Paper Trading",
+  "version": "0.1.0",
+  "description": "Paper trading plugin with real Binance market data and simulated execution. No API keys required.",
+  "author": "ReefClaw",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "fetch_ticker",
+      "fetch_ohlcv",
+      "fetch_balance",
+      "fetch_positions",
+      "fetch_open_orders",
+      "create_order",
+      "cancel_order",
+      "cancel_all_orders",
+      "close_position",
+      "modify_stop",
+      "modify_target",
+      "attach_brackets",
+      "audit_bracket_protection",
+      "record_position_reviews",
+      "get_my_recent_reviews",
+      "get_relevant_learnings",
+      "get_my_mined_patterns",
+      "get_my_proposed_learnings",
+      "propose_learning",
+      "query_review_outcomes",
+      "get_market_structure",
+      "get_crypto_metrics",
+      "get_volume_analysis",
+      "get_risk_summary",
+      "get_market_intel",
+      "get_regime",
+      "get_signals",
+      "get_analytics",
+      "get_orderbook",
+      "get_volume_profile",
+      "get_liquidation_levels",
+      "get_trade_feedback",
+      "get_trade_flow",
+      "score_setup",
+      "get_sizing",
+      "check_position_health",
+      "get_risk_scenario",
+      "get_session_review",
+      "get_backtest",
+      "get_pattern_scan",
+      "save_strategy",
+      "list_strategies",
+      "toggle_strategy",
+      "scan_pairs",
+      "get_setup_detail",
+      "query_trades",
+      "get_agent_profile",
+      "get_cvd",
+      "get_market_breadth",
+      "get_basis",
+      "get_cascade_risk",
+      "get_sentiment",
+      "get_divergences",
+      "get_liquidation_pulse",
+      "get_resting_liquidity",
+      "get_funding_context",
+      "set_exchange_credentials",
+      "set_trading_mode",
+      "test_exchange_credentials",
+      "clear_exchange_credentials",
+      "get_bracket_config",
+      "set_bracket_requirement"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "startingBalance": {
+        "type": "number",
+        "default": 10000,
+        "description": "Starting USDT balance for paper trading"
+      },
+      "symbol": {
+        "type": "string",
+        "default": "BTC/USDT",
+        "description": "Default trading symbol"
+      }
+    }
+  },
+  "skills": [
+    "./skills"
+  ]
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@reefclaw/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "ReefClaw trading plugin for OpenClaw — paper trading with real Binance market data, plus the ReefClaw dashboard connector (supervised by OpenClaw, no service manager needed). Install: /plugins install npm:@reefclaw/openclaw-plugin",
+  "type": "module",
+  "main": "index.js",
+  "openclaw": {
+    "extensions": ["./index.js"]
+  },
+  "files": [
+    "**/*"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@reefclaw/shared": "0.1.0",
+    "ccxt": "4.5.37",
+    "json5": "2.2.3",
+    "ws": "8.19.0"
+  },
+  "scripts": {
+    "build": "node scripts/assemble.mjs"
+  },
+  "license": "MIT",
+  "homepage": "https://reefclaw.com"
+}

package/paper-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from './exchange-adapter.js';
+import type { ExchangeSimulator } from './simulator/exchange-simulator.js';
+import type { CcxtOrder, CcxtBalance, CcxtPosition } from './types.js';
+import type { PositionMetadata, CloseReason } from './simulator/types.js';
+export declare class PaperAdapter implements IExchangeAdapter {
+    private simulator;
+    readonly mode: "PAPER";
+    readonly isLive = false;
+    readonly readiness: AdapterReadiness;
+    constructor(simulator: ExchangeSimulator);
+    /** Get the underlying simulator (for paper-only operations like ATR, orderbook, state). */
+    getSimulator(): ExchangeSimulator;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, _options?: OrderOptions): Promise<CcxtOrder>;
+    cancelOrder(orderId: string, _symbol?: string): Promise<CcxtOrder>;
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+    getBalance(): Promise<CcxtBalance>;
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /** Paper has no exchange fetch to fail — position state is always known. */
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, _symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+}

package/paper-adapter.js

@@ -0,0 +1,91 @@
+// PaperAdapter — wraps ExchangeSimulator to implement IExchangeAdapter.
+// No behavioral changes — just a thin async wrapper for uniform interface.
+export class PaperAdapter {
+    simulator;
+    mode = 'PAPER';
+    isLive = false;
+    readiness = 'READY'; // Paper is always ready
+    constructor(simulator) {
+        this.simulator = simulator;
+    }
+    /** Get the underlying simulator (for paper-only operations like ATR, orderbook, state). */
+    getSimulator() {
+        return this.simulator;
+    }
+    async createOrder(symbol, side, type, amount, price, metadata, _options) {
+        // Paper mode ignores OrderOptions (clientOrderId, reduceOnly, positionSide)
+        return this.simulator.createOrder(symbol, side, type, amount, price, metadata);
+    }
+    async cancelOrder(orderId, _symbol) {
+        return this.simulator.cancelOrder(orderId);
+    }
+    async cancelAllOrders(symbol) {
+        return this.simulator.cancelAllOrders(symbol);
+    }
+    async closePosition(symbol, closeReason) {
+        return this.simulator.closePosition(symbol, closeReason);
+    }
+    async getBalance() {
+        return this.simulator.getBalance();
+    }
+    async getPositions(symbol) {
+        return this.simulator.getPositions(symbol);
+    }
+    /** Paper has no exchange fetch to fail — position state is always known. */
+    async getPositionsOrNull(symbol) {
+        return this.simulator.getPositions(symbol);
+    }
+    async getOpenOrders(symbol) {
+        return this.simulator.getOpenOrders(symbol);
+    }
+    async fetchOrder(orderId, _symbol) {
+        // Search open orders, then trade history for filled/canceled orders
+        const state = this.simulator.getState();
+        const openOrder = state.openOrders.find(o => o.id === orderId);
+        if (openOrder) {
+            return {
+                id: openOrder.id,
+                symbol: openOrder.symbol,
+                side: openOrder.side,
+                type: openOrder.type,
+                status: openOrder.status,
+                amount: openOrder.amount,
+                filled: openOrder.filled,
+                remaining: openOrder.amount - openOrder.filled,
+                average: openOrder.average,
+                price: openOrder.price,
+                cost: openOrder.cost,
+                fee: openOrder.fee,
+                timestamp: new Date(openOrder.createdAt).getTime(),
+                datetime: openOrder.createdAt,
+                timeInForce: 'GTC',
+            };
+        }
+        // Check trade history for filled orders
+        const trade = state.tradeHistory.find(t => t.orderId === orderId);
+        if (trade) {
+            return {
+                id: trade.orderId,
+                symbol: trade.symbol,
+                side: trade.side,
+                type: 'market', // Trades don't store order type; market is the common close path
+                status: 'closed',
+                amount: trade.quantity,
+                filled: trade.quantity,
+                remaining: 0,
+                average: trade.exitPrice,
+                price: trade.exitPrice,
+                cost: trade.exitPrice * trade.quantity,
+                fee: { cost: trade.fee, currency: 'USDT' },
+                timestamp: new Date(trade.closedAt).getTime(),
+                datetime: trade.closedAt,
+                timeInForce: 'GTC',
+            };
+        }
+        return null;
+    }
+    async getLastPrice(symbol) {
+        const ticker = this.simulator.getLastTicker(symbol);
+        return ticker?.last ?? null;
+    }
+}

package/persistence/state-manager.d.ts

@@ -0,0 +1,42 @@
+import type { SimulatorState } from '../simulator/types.js';
+export declare class StateManager {
+    private readonly statePath;
+    private saveTimer;
+    private pendingState;
+    constructor(pluginId: string, baseDir?: string);
+    getStatePath(): string;
+    /** Quarantine a state file that exists but won't parse, instead of letting
+     *  the caller silently overwrite it with a fresh default (which would wipe
+     *  the positions/orders/realized-PnL ledger). The corrupt bytes are renamed
+     *  to `<state>.corrupt-<ts>` so an operator can recover them. Returns true if
+     *  a corrupt file was quarantined. */
+    private quarantineCorruptSync;
+    /** Load state from disk. Returns null when the file is MISSING (fresh start)
+     *  OR when it exists-but-is-unreadable (in which case the corrupt bytes are
+     *  quarantined first — never silently discarded). The two cases are
+     *  distinguished in the log; both yield null so the caller seeds a default,
+     *  but a corrupt file is preserved as `<state>.corrupt-<ts>`. */
+    load(): Promise<SimulatorState | null>;
+    /** Save state atomically (write to a UNIQUE temp, rename to final). A unique
+     *  temp name (pid + uuid) is essential under the two-process model: both the
+     *  agent and gateway processes wire stateChanged→save, and a shared
+     *  `<state>.tmp` let their concurrent writes interleave into a torn file that
+     *  then parses as garbage on next boot. With a per-write temp, the worst case
+     *  degrades to a harmless last-writer-wins rename of two COMPLETE files. */
+    save(state: SimulatorState): Promise<void>;
+    /**
+     * Debounced save — coalesces rapid mutations into one write per second.
+     * Call this on every state change; it will save at most once per second.
+     */
+    debouncedSave(state: SimulatorState): void;
+    /** Flush any pending debounced save immediately. */
+    flush(): Promise<void>;
+    /** Load state or create default if not found. */
+    loadOrDefault(startingBalance: number, quoteCurrency: string): Promise<SimulatorState>;
+    /** Synchronous load — for use in synchronous plugin register(). Same
+     *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
+     *  (preserved), never silently overwritten by the default the caller seeds. */
+    loadSync(): SimulatorState | null;
+    /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
+    loadOrDefaultSync(startingBalance: number, quoteCurrency: string): SimulatorState;
+}