@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/signals/conditions/types.d.ts

@@ -0,0 +1 @@
+export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, EntryRuleConfig, StopRuleConfig, DirectionRule, PrimaryTimeframe, StrategyConfig, } from '@reefclaw/shared';

package/assets/plugin/signals/conditions/types.js

@@ -0,0 +1,4 @@
+// Re-export shim — see ../types.ts. The condition + strategy-config contracts
+// the generated registry/rules import from `./types.js`. Canonical definitions
+// live in @reefclaw/shared (type-only → erased at runtime).
+export {};

package/assets/plugin/signals/direction-rules.d.ts

@@ -0,0 +1,3 @@
+import type { MarketContext, Direction } from './types.js';
+import type { ConditionContext, DirectionRule } from './conditions/types.js';
+export declare function resolveDirection(rule: DirectionRule, ctx: MarketContext, condCtx: ConditionContext): Direction | null;

package/assets/plugin/signals/direction-rules.js

@@ -0,0 +1,24 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/direction-rules.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+export function resolveDirection(rule, ctx, condCtx) {
+    switch (rule) {
+        case 'from_regime':
+            return ctx.regime === 'TREND_UP' ? 'LONG' : ctx.regime === 'TREND_DOWN' ? 'SHORT' : null;
+        case 'from_sweep':
+            return condCtx.sweptDirection ?? null;
+        case 'from_funding':
+            // funding_extreme condition sets sweptDirection to the contra direction
+            return condCtx.sweptDirection ?? null;
+        case 'fixed_long':
+            return 'LONG';
+        case 'fixed_short':
+            return 'SHORT';
+        default:
+            return null;
+    }
+}

package/assets/plugin/signals/entry-rules.d.ts

@@ -0,0 +1,6 @@
+import type { MarketContext, Direction } from './types.js';
+import type { EntryRuleConfig, ConditionContext } from './conditions/types.js';
+export declare function computeEntry(rule: EntryRuleConfig, ctx: MarketContext, direction: Direction, condCtx: ConditionContext): {
+    low: number;
+    high: number;
+};

package/assets/plugin/signals/entry-rules.js

@@ -0,0 +1,33 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/entry-rules.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+// Entry zone calculation for declarative strategies.
+import { computeEMA } from '../shared/indicators.js';
+export function computeEntry(rule, ctx, direction, condCtx) {
+    switch (rule.type) {
+        case 'ema_offset': {
+            const period = rule.params.period ?? 21;
+            const atrFraction = (rule.params.atrFraction ?? 0.3) * ctx.atr14;
+            const ema = condCtx.ema21 && period === 21
+                ? condCtx.ema21
+                : computeEMA(ctx.ohlcv1h.map(b => b.close), period);
+            return { low: ema - atrFraction, high: ema + atrFraction };
+        }
+        case 'sweep_range': {
+            const sweepLevel = condCtx.sweepLevel ?? ctx.currentPrice;
+            return direction === 'LONG'
+                ? { low: sweepLevel, high: ctx.currentPrice }
+                : { low: ctx.currentPrice, high: sweepLevel };
+        }
+        case 'atr_offset': {
+            const atrFraction = (rule.params.atrFraction ?? 0.2) * ctx.atr14;
+            return { low: ctx.currentPrice - atrFraction, high: ctx.currentPrice + atrFraction };
+        }
+        default:
+            return { low: ctx.currentPrice - ctx.atr14 * 0.3, high: ctx.currentPrice + ctx.atr14 * 0.3 };
+    }
+}

package/assets/plugin/signals/serialize-context.d.ts

@@ -0,0 +1,4 @@
+import type { MarketContext } from './types.js';
+export declare function serializeContext(ctx: MarketContext): string;
+/** Parse a streamed context and rehydrate every Date field. Throws on bad JSON. */
+export declare function deserializeContext(raw: string): MarketContext;

package/assets/plugin/signals/serialize-context.js

@@ -0,0 +1,39 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/serialize-context.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+export function serializeContext(ctx) {
+    return JSON.stringify(ctx);
+}
+function reviveBars(bars) {
+    if (!Array.isArray(bars))
+        return undefined;
+    return bars.map((b) => ({ ...b, time: new Date(b.time) }));
+}
+/** Parse a streamed context and rehydrate every Date field. Throws on bad JSON. */
+export function deserializeContext(raw) {
+    const o = JSON.parse(raw);
+    o.timestamp = new Date(o.timestamp);
+    const oh1 = reviveBars(o.ohlcv1h);
+    if (oh1)
+        o.ohlcv1h = oh1;
+    const oh5 = reviveBars(o.ohlcv5m);
+    if (oh5)
+        o.ohlcv5m = oh5;
+    const oh4 = reviveBars(o.ohlcv4h);
+    if (oh4)
+        o.ohlcv4h = oh4;
+    const oh1d = reviveBars(o.ohlcv1d);
+    if (oh1d)
+        o.ohlcv1d = oh1d;
+    if (Array.isArray(o.tradeFlow)) {
+        o.tradeFlow = o.tradeFlow.map((t) => ({ ...t, bucket: new Date(t.bucket) }));
+    }
+    if (o.globalContext?.btcRsi14_1d_at) {
+        o.globalContext.btcRsi14_1d_at = new Date(o.globalContext.btcRsi14_1d_at);
+    }
+    return o;
+}

package/assets/plugin/signals/stop-rules.d.ts

@@ -0,0 +1,3 @@
+import type { MarketContext, Direction } from './types.js';
+import type { StopRuleConfig, ConditionContext } from './conditions/types.js';
+export declare function computeStop(rule: StopRuleConfig, ctx: MarketContext, direction: Direction, condCtx: ConditionContext): number;

package/assets/plugin/signals/stop-rules.js

@@ -0,0 +1,48 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/stop-rules.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+// Stop level calculation for declarative strategies.
+import { findSwingPoints } from '../shared/indicators.js';
+export function computeStop(rule, ctx, direction, condCtx) {
+    switch (rule.type) {
+        case 'swing_atr': {
+            const swingCount = rule.params.swingCount ?? 3;
+            const atrFraction = (rule.params.atrFraction ?? 0.3) * ctx.atr14;
+            const fallbackAtrMult = rule.params.fallbackAtrMultiple ?? 2;
+            const swings = findSwingPoints(ctx.ohlcv1h.slice(-48), 3);
+            if (direction === 'LONG') {
+                return swings.lows.length > 0
+                    ? Math.min(...swings.lows.slice(-swingCount)) - atrFraction
+                    : ctx.currentPrice - ctx.atr14 * fallbackAtrMult;
+            }
+            else {
+                return swings.highs.length > 0
+                    ? Math.max(...swings.highs.slice(-swingCount)) + atrFraction
+                    : ctx.currentPrice + ctx.atr14 * fallbackAtrMult;
+            }
+        }
+        case 'recent_extreme_atr': {
+            const atrFraction = (rule.params.atrFraction ?? 0.5) * ctx.atr14;
+            if (direction === 'LONG') {
+                return (condCtx.recentLow ?? ctx.currentPrice - ctx.atr14) - atrFraction;
+            }
+            else {
+                return (condCtx.recentHigh ?? ctx.currentPrice + ctx.atr14) + atrFraction;
+            }
+        }
+        case 'fixed_atr': {
+            const atrMultiple = rule.params.atrMultiple ?? 1.5;
+            return direction === 'LONG'
+                ? ctx.currentPrice - ctx.atr14 * atrMultiple
+                : ctx.currentPrice + ctx.atr14 * atrMultiple;
+        }
+        default:
+            return direction === 'LONG'
+                ? ctx.currentPrice - ctx.atr14 * 2
+                : ctx.currentPrice + ctx.atr14 * 2;
+    }
+}

package/assets/plugin/signals/strategy-adapter.d.ts

@@ -0,0 +1,47 @@
+import type { StrategyDefinition, MarketContext, OhlcvBar } from './types.js';
+import type { StrategyConfig, PrimaryTimeframe } from './conditions/types.js';
+export declare function clearStrategyGatingState(): void;
+/**
+ * Live parity for higher-timeframe strategies (the tfHours-aware-stops fix,
+ * 2026-07 — see docs/STRATEGY_RESEARCH_2026-07.md §6.4 / CLAUDE.md ★).
+ *
+ * Every implicit bar read in this engine — stop rules
+ * (`findSwingPoints(ctx.ohlcv1h.slice(-48))`), entry rules
+ * (`computeEMA(ctx.ohlcv1h…)`), conditions without a `tfHours` param
+ * (ema_proximity, stoch_rsi_extreme, adx_*, …) and `ctx.atr14` — targets the
+ * `ohlcv1h` slot. The backtest engine feeds MAIN-timeframe bars into that
+ * slot (and computes atr14 from them), so a 4h/1d strategy backtests against
+ * primary-timeframe geometry. LIVE contexts put real 1h bars there, so the
+ * same strategy would compute stops/EMAs/ATR from 1h data — a 1d ATR is ~8×
+ * the 1h ATR, so live stops came out ~8× too tight. This helper gives the
+ * evaluation the exact context shape the backtest validated: primary bars in
+ * the `ohlcv1h` slot, atr14 recomputed from them (same computeATR the
+ * backtest and live context builders use).
+ *
+ * Detection, not configuration: when the `ohlcv1h` slot already carries
+ * primary-cadence bars (median spacing ≥ 90% of the primary bar duration —
+ * i.e. a backtest context), the context is returned UNTOUCHED, so backtest
+ * behaviour is byte-identical by construction (including warm-up: the
+ * backtest engine already refuses to build a context below 50 main bars).
+ * A live 1h series can only look primary-spaced through a data gap, in
+ * which case we fall back to the untouched context (pre-fix behaviour)
+ * rather than guessing.
+ *
+ * Returns null for a LIVE context whose primary-timeframe history is below
+ * the backtest's 50-bar warm-up — the caller skips evaluation, mirroring
+ * the backtest's null-context warm-up window.
+ *
+ * Exported for tests.
+ */
+export declare function resolvePrimaryContext(ctx: MarketContext, tf: PrimaryTimeframe, tfBars: OhlcvBar[]): MarketContext | null;
+/**
+ * Convert a declarative StrategyConfig into a StrategyDefinition
+ * that the signal engine and backtest engine can evaluate.
+ *
+ * `gateNamespace` scopes the module-global HTF tick-gate to the calling tenant
+ * (pass the strategy-cache key — `global` for the background pass, the user key
+ * for a per-user pass). Omit it for single-tenant callers (backtests, the
+ * plugin's local evaluator) — they keep the original un-namespaced gate key,
+ * so their behaviour is byte-identical.
+ */
+export declare function adaptStrategy(config: StrategyConfig, gateNamespace?: string): StrategyDefinition;

package/assets/plugin/signals/strategy-adapter.js

@@ -0,0 +1,209 @@
+// ⚠️ GENERATED FILE — DO NOT EDIT.
+// Canonical source of truth: shared/src/signals/strategy-adapter.ts
+// Regenerate: node scripts/sync-shared-code.mjs  (enforced by shared-code-sync.test.ts)
+//
+// This copy exists because this package builds with tsc and deploys as a
+// self-contained tree that strips workspace deps, so it cannot import
+// @reefclaw/shared runtime code across the deploy boundary.
+import { evaluateConditions } from './conditions/registry.js';
+import { resolveDirection } from './direction-rules.js';
+import { computeEntry } from './entry-rules.js';
+import { computeStop } from './stop-rules.js';
+import { computeATR } from '../shared/indicators.js';
+/**
+ * Higher-timeframe tick gating state, keyed by
+ * `${gateNamespace}\x1f${strategyName}:${symbol}`.
+ *
+ * Lives at module scope because the strategy cache (strategy-store.ts) builds
+ * a fresh adapter every 60s, so closure-based state would reset constantly
+ * and 1d-primary strategies would re-evaluate on every tick instead of once
+ * per closed bar. Module-level state survives the cache refresh.
+ *
+ * ★ Multi-tenant: because the map is module-global, the key MUST carry a
+ * per-tenant `gateNamespace` (the caller's strategy-cache key — `global` vs a
+ * per-user key). Without it, two tenants running same-named strategies on the
+ * same symbol shared ONE gate: whichever evaluated first marked the bar
+ * consumed and the other tenant's strategy was silently SKIPPED until the next
+ * primary-timeframe bar closed (a full day for a 1d strategy). A `\x1f` (unit
+ * separator, never present in a UUID / strategy name / symbol) joins the
+ * namespace so distinct tenants can never collide.
+ *
+ * Backtests should call `clearStrategyGatingState()` between runs to avoid
+ * leakage across tests / sequential backtests.
+ */
+const lastEvaluatedBarTime = new Map();
+export function clearStrategyGatingState() {
+    lastEvaluatedBarTime.clear();
+}
+function pickTimeframeBars(ctx, tf) {
+    if (tf === '1d')
+        return ctx.ohlcv1d ?? [];
+    if (tf === '4h')
+        return ctx.ohlcv4h ?? [];
+    return ctx.ohlcv1h;
+}
+const TF_MS = {
+    '1h': 3_600_000,
+    '4h': 4 * 3_600_000,
+    '1d': 24 * 3_600_000,
+};
+/** Median spacing of the last few bars — robust bar-cadence probe. */
+function barSpacingMs(bars) {
+    const n = bars.length;
+    if (n < 2)
+        return 0;
+    const deltas = [];
+    for (let i = Math.max(1, n - 4); i < n; i++) {
+        deltas.push(bars[i].time.getTime() - bars[i - 1].time.getTime());
+    }
+    deltas.sort((a, b) => a - b);
+    return deltas[Math.floor(deltas.length / 2)];
+}
+/**
+ * Live parity for higher-timeframe strategies (the tfHours-aware-stops fix,
+ * 2026-07 — see docs/STRATEGY_RESEARCH_2026-07.md §6.4 / CLAUDE.md ★).
+ *
+ * Every implicit bar read in this engine — stop rules
+ * (`findSwingPoints(ctx.ohlcv1h.slice(-48))`), entry rules
+ * (`computeEMA(ctx.ohlcv1h…)`), conditions without a `tfHours` param
+ * (ema_proximity, stoch_rsi_extreme, adx_*, …) and `ctx.atr14` — targets the
+ * `ohlcv1h` slot. The backtest engine feeds MAIN-timeframe bars into that
+ * slot (and computes atr14 from them), so a 4h/1d strategy backtests against
+ * primary-timeframe geometry. LIVE contexts put real 1h bars there, so the
+ * same strategy would compute stops/EMAs/ATR from 1h data — a 1d ATR is ~8×
+ * the 1h ATR, so live stops came out ~8× too tight. This helper gives the
+ * evaluation the exact context shape the backtest validated: primary bars in
+ * the `ohlcv1h` slot, atr14 recomputed from them (same computeATR the
+ * backtest and live context builders use).
+ *
+ * Detection, not configuration: when the `ohlcv1h` slot already carries
+ * primary-cadence bars (median spacing ≥ 90% of the primary bar duration —
+ * i.e. a backtest context), the context is returned UNTOUCHED, so backtest
+ * behaviour is byte-identical by construction (including warm-up: the
+ * backtest engine already refuses to build a context below 50 main bars).
+ * A live 1h series can only look primary-spaced through a data gap, in
+ * which case we fall back to the untouched context (pre-fix behaviour)
+ * rather than guessing.
+ *
+ * Returns null for a LIVE context whose primary-timeframe history is below
+ * the backtest's 50-bar warm-up — the caller skips evaluation, mirroring
+ * the backtest's null-context warm-up window.
+ *
+ * Exported for tests.
+ */
+export function resolvePrimaryContext(ctx, tf, tfBars) {
+    if (tf === '1h')
+        return ctx;
+    const spacing = barSpacingMs(ctx.ohlcv1h);
+    if (spacing === 0 || spacing >= TF_MS[tf] * 0.9)
+        return ctx; // already primary (backtest) or undecidable
+    if (tfBars.length < 50)
+        return null; // live warm-up parity with the backtest engine
+    const highs = tfBars.map(b => b.high);
+    const lows = tfBars.map(b => b.low);
+    const closes = tfBars.map(b => b.close);
+    const atr14 = computeATR(highs, lows, closes, 14);
+    return {
+        ...ctx,
+        ohlcv1h: tfBars,
+        atr14: Number.isFinite(atr14) && atr14 > 0 ? atr14 : ctx.atr14,
+    };
+}
+/** Empty no-signal evaluation — used when gating skips a strategy. */
+const SKIPPED = { direction: null, conditions: [], trade: undefined };
+/**
+ * Convert a declarative StrategyConfig into a StrategyDefinition
+ * that the signal engine and backtest engine can evaluate.
+ *
+ * `gateNamespace` scopes the module-global HTF tick-gate to the calling tenant
+ * (pass the strategy-cache key — `global` for the background pass, the user key
+ * for a per-user pass). Omit it for single-tenant callers (backtests, the
+ * plugin's local evaluator) — they keep the original un-namespaced gate key,
+ * so their behaviour is byte-identical.
+ */
+export function adaptStrategy(config, gateNamespace) {
+    return {
+        name: config.name,
+        regimeWhitelist: config.regimeWhitelist,
+        minConfidence: config.minConfidence,
+        async evaluate(ctx) {
+            // ─── Tick gating ───────────────────────────────────────────────
+            // Only re-evaluate when a new bar of the strategy's primary
+            // timeframe has closed since the last evaluation for this
+            // strategy/symbol pair. Defaults to '1h' so existing strategies
+            // are unaffected.
+            const tf = config.primaryTimeframe ?? '1h';
+            const tfBars = pickTimeframeBars(ctx, tf);
+            if (tfBars.length === 0)
+                return SKIPPED;
+            const latestBarTime = tfBars[tfBars.length - 1].time.getTime();
+            // Namespaced per tenant (see lastEvaluatedBarTime doc) so same-named
+            // strategies across tenants never share a gate. Un-namespaced when
+            // gateNamespace is omitted — byte-identical to the original key.
+            const gateKey = gateNamespace
+                ? `${gateNamespace}\x1f${config.name}:${ctx.symbol}`
+                : `${config.name}:${ctx.symbol}`;
+            const lastBarTime = lastEvaluatedBarTime.get(gateKey);
+            if (lastBarTime !== undefined && latestBarTime === lastBarTime) {
+                return SKIPPED;
+            }
+            lastEvaluatedBarTime.set(gateKey, latestBarTime);
+            // ─── Higher-timeframe live parity ──────────────────────────────
+            // Evaluate against a context whose implicit-1h slot carries
+            // primary-timeframe bars — see resolvePrimaryContext. Backtest
+            // contexts pass through untouched; only live contexts for 4h/1d
+            // strategies are adapted, and a live context below the backtest's
+            // 50-bar warm-up resolves to null → skip.
+            const ectx = resolvePrimaryContext(ctx, tf, tfBars);
+            if (ectx === null)
+                return SKIPPED;
+            // ─── SkipIf gates ──────────────────────────────────────────────
+            // Portfolio-wide / cross-symbol filters. If any are met the
+            // strategy is skipped this tick. Evaluated before main conditions
+            // so the bulk of the work is short-circuited.
+            if (config.skipIf && config.skipIf.length > 0) {
+                const { conditions: skipResults } = evaluateConditions(config.skipIf, ectx, null);
+                if (skipResults.some(c => c.met))
+                    return SKIPPED;
+            }
+            // Pass 1: evaluate conditions with direction = null
+            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ectx, null);
+            // Determine direction
+            const direction = resolveDirection(config.directionRule, ectx, condCtx);
+            // Pass 2: once the direction is known, re-evaluate the FULL condition
+            // array with it. Many registry conditions branch on `direction`
+            // (orderbook_imbalance, funding_contrarian, macd_crossover,
+            // bollinger_breakout, vwap_position, stoch_rsi_extreme, ichimoku_cloud,
+            // supertrend_direction, …) and their pass-1 result was computed against
+            // direction=null — typically the permissive either-side branch. A
+            // hand-curated allowlist here (the pre-fix 5-type set) silently drifted
+            // out of sync with the registry, so non-listed direction-dependent
+            // conditions kept their permissive pass-1 result forever (e.g. a
+            // fixed_long strategy's macd_crossover accepted a BEARISH crossover).
+            // Pass 2 always evaluated the whole array anyway — use it wholesale.
+            // Direction-insensitive conditions are pure functions of (ctx, params)
+            // and return identical results in both passes; entry/stop computation
+            // below deliberately keeps pass 1's condCtx (setter values don't depend
+            // on direction).
+            let finalConditions = pass1;
+            if (direction) {
+                const { conditions: pass2 } = evaluateConditions(config.conditions, ectx, direction);
+                finalConditions = pass2;
+            }
+            const allMet = finalConditions.every(c => c.met);
+            let trade;
+            if (allMet && direction) {
+                const entryZone = computeEntry(config.entryRule, ectx, direction, condCtx);
+                const stopLevel = computeStop(config.stopRule, ectx, direction, condCtx);
+                const risk = direction === 'LONG'
+                    ? ectx.currentPrice - stopLevel
+                    : stopLevel - ectx.currentPrice;
+                const targets = config.targetRMultiples.map(rm => direction === 'LONG'
+                    ? ectx.currentPrice + risk * rm
+                    : ectx.currentPrice - risk * rm);
+                trade = { entryZone, stopLevel, targets };
+            }
+            return { direction, conditions: finalConditions, trade };
+        },
+    };
+}

package/assets/plugin/signals/types.d.ts

@@ -0,0 +1 @@
+export type { Direction, OhlcvBar, TradeFlowBucket, GlobalMarketContext, MarketContext, SignalCondition, StrategyEvaluation, StrategyDefinition, SignalEvent, StrategyState, SignalSnapshot, } from '@reefclaw/shared';

package/assets/plugin/signals/types.js

@@ -0,0 +1,8 @@
+// Re-export shim for the plugin-side strategy evaluator (facts-out).
+//
+// The generated eval-core copies (registry, strategy-adapter, direction/entry/
+// stop-rules) import their types from `./types.js`. The canonical definitions
+// live in @reefclaw/shared (type-only → erased at runtime), so this shim makes
+// those relative imports resolve inside the plugin tree without pulling any
+// runtime dependency into the emitted JS. See docs/FACTS_OUT_ARCHITECTURE.md.
+export {};

package/assets/plugin/simulator/exchange-simulator.d.ts

@@ -0,0 +1,105 @@
+import { EventEmitter } from 'node:events';
+import type { SimulatorState, OrderBookDepth, SimulationConfig, ExecutionStats, PositionMetadata, CloseReason } from './types.js';
+import type { CcxtOrder, CcxtBalance, CcxtPosition, CcxtTicker } from '../types.js';
+export declare class ExchangeSimulator extends EventEmitter {
+    private state;
+    private lastTicker;
+    private lastOrderBook;
+    private simulationConfig;
+    /** Metadata for pending limit orders, keyed by order ID. Cleaned up on fill/cancel. */
+    private pendingOrderMetadata;
+    private cachedVolFactor;
+    private baselineAtr;
+    private atrSampleCount;
+    private readonly startupTime;
+    private readonly hadPositionsAtStartup;
+    private static readonly STARTUP_LOCKOUT_MS;
+    constructor(initialState: SimulatorState, config?: SimulationConfig);
+    getSimulationConfig(): SimulationConfig;
+    setVolFactor(factor: number): void;
+    getVolFactor(): number;
+    /** Update baseline ATR using exponential moving average of samples. */
+    updateBaselineAtr(atr14: number): void;
+    getBaselineAtr(): number;
+    /**
+     * 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(): number;
+    setSessionStartNav(nav: number): void;
+    /** 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. */
+    private ensureSessionAnchor;
+    /** 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(): number;
+    private getQuoteCurrency;
+    getBalance(): CcxtBalance;
+    getPositions(symbol?: string): CcxtPosition[];
+    getOpenOrders(symbol?: string): CcxtOrder[];
+    /** Get cumulative execution quality stats. */
+    getExecutionStats(): ExecutionStats | undefined;
+    /** Cache the latest order book snapshot for a symbol. */
+    updateOrderBook(symbol: string, orderbook: OrderBookDepth): void;
+    getLastOrderBook(symbol: string): OrderBookDepth | undefined;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata): CcxtOrder;
+    cancelOrder(orderId: string): CcxtOrder;
+    cancelAllOrders(symbol?: string): CcxtOrder[];
+    closePosition(symbol: string, closeReason?: CloseReason): CcxtOrder;
+    /** 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: string, patch: {
+        stopPrice?: number;
+        targetPrice?: number;
+    }): void;
+    updateTicker(ticker: CcxtTicker): void;
+    getLastTicker(symbol: string): CcxtTicker | undefined;
+    /** 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). */
+    private refreshMfeForSymbol;
+    /** 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: SimulatorState): void;
+    getState(): SimulatorState;
+    /** 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 readonly DEFAULT_MAX_QUOTE_AGE_MS = 45000;
+    private maxQuoteAgeMs;
+    /** Quote age from the ticker's own timestamp. A missing/invalid timestamp
+     *  reads as age 0 (fail-open — the guard cannot fire on it). */
+    private quoteAgeMs;
+    /** 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. */
+    private assertQuoteFresh;
+    private shouldFillLimit;
+    private executeMarketFill;
+    private executeLimitFill;
+    /** Apply a fill result: update positions, record trade, track stats, emit state change. */
+    private applyFillResult;
+    private updatePosition;
+    private addTrade;
+    /** Update cumulative execution stats from a fill's execution quality. */
+    private updateExecutionStats;
+    private emitStateChanged;
+    private toCcxtOrder;
+}