@reefclaw/openclaw-plugin 0.1.0

package/simulator/realistic-fills.js

@@ -0,0 +1,175 @@
+// Phase 9a: Realistic fill simulation.
+// Order book-aware VWAP fills, latency modeling, maker/taker fees.
+import { DEFAULT_SIMULATION_CONFIG, priceToBps } from './types.js';
+/**
+ * Walk the order book to compute a volume-weighted average fill price.
+ *
+ * For BUY: walks asks (sellers) from best ask upward.
+ * For SELL: walks bids (buyers) from best bid downward.
+ *
+ * If the order exceeds available depth, the remainder fills at the worst
+ * available price + 10 bps penalty (simulating thin-book impact).
+ *
+ * @returns { vwap, levelsConsumed, fillRatio } where fillRatio < 1 only
+ * if we want to model partial fills (currently always fills completely).
+ */
+export function computeBookAwareFillPrice(side, amount, orderbook) {
+    const levels = side === 'buy' ? orderbook.asks : orderbook.bids;
+    if (levels.length === 0) {
+        // No book data — caller should fall back to random slippage
+        return { vwap: 0, levelsConsumed: 0 };
+    }
+    let remaining = amount;
+    let totalCost = 0;
+    let levelsConsumed = 0;
+    for (const [price, quantity] of levels) {
+        if (remaining <= 0)
+            break;
+        const fillQty = Math.min(remaining, quantity);
+        totalCost += fillQty * price;
+        remaining -= fillQty;
+        levelsConsumed++;
+    }
+    if (remaining > 0) {
+        // Order exceeds available depth — fill remainder at worst price + penalty
+        const worstPrice = levels[levels.length - 1][0];
+        const penaltyMultiplier = side === 'buy' ? 1.001 : 0.999; // 10 bps penalty
+        totalCost += remaining * worstPrice * penaltyMultiplier;
+        remaining = 0;
+    }
+    const vwap = totalCost / amount;
+    return { vwap, levelsConsumed };
+}
+/**
+ * Simulate latency-induced price drift.
+ *
+ * During the latency window, the price can move against the trader.
+ * The drift is proportional to latency duration and current volatility.
+ *
+ * @param basePrice The VWAP price before latency adjustment
+ * @param side Order side (buy drift is positive, sell drift is negative)
+ * @param latencyMs Simulated latency in milliseconds
+ * @param volFactor Current volatility factor (1.0 = normal, >1 = elevated)
+ * @returns { adjustedPrice, latencyImpactBps }
+ */
+export function applyLatencyDrift(basePrice, side, latencyMs, volFactor) {
+    if (latencyMs <= 0) {
+        return { adjustedPrice: basePrice, latencyImpactBps: 0 };
+    }
+    // Base drift: up to 1 bps for 200ms latency, scaled by volatility
+    // Uses a random factor for direction — 70% of the time price moves against trader
+    const maxLatencyMs = 200;
+    const maxDriftBps = 1.0;
+    const latencyRatio = Math.min(latencyMs / maxLatencyMs, 1.0);
+    const randomFactor = Math.random();
+    // 70% adverse, 30% favorable (market more often moves against you in the latency window)
+    const adverseProb = 0.7;
+    const driftDirection = randomFactor < adverseProb ? 1 : -1;
+    const driftMagnitude = latencyRatio * maxDriftBps * volFactor * Math.random();
+    const driftBps = driftMagnitude * driftDirection;
+    // BUY: adverse = price goes UP (pay more)
+    // SELL: adverse = price goes DOWN (receive less)
+    const signedDriftBps = side === 'buy' ? driftBps : -driftBps;
+    const adjustedPrice = basePrice * (1 + signedDriftBps / 10_000);
+    return { adjustedPrice, latencyImpactBps: signedDriftBps };
+}
+/**
+ * Generate a random simulated latency within the configured range.
+ */
+export function generateLatency(config) {
+    const { minMs, maxMs } = config.latency;
+    return minMs + Math.random() * (maxMs - minMs);
+}
+/**
+ * Compute the fee rate based on order type (maker vs taker).
+ * Market orders = taker. Limit orders = maker.
+ */
+export function getFeeRate(orderType, config) {
+    return orderType === 'market' ? config.fees.takerRate : config.fees.makerRate;
+}
+/**
+ * Compute a complete realistic fill for a market order.
+ *
+ * Combines: orderbook VWAP + latency drift + appropriate fee rate.
+ * Falls back to simple random slippage if no orderbook is available.
+ *
+ * @returns fillPrice and ExecutionQuality metrics
+ */
+export function computeRealisticMarketFill(side, amount, decisionPrice, orderbook, volFactor, config = DEFAULT_SIMULATION_CONFIG) {
+    const latencyMs = generateLatency(config);
+    const feeRate = getFeeRate('market', config);
+    let fillPrice;
+    let marketImpactBps;
+    let latencyImpactBps;
+    let bookLevelsConsumed;
+    let bookDepthAvailable;
+    if (orderbook && orderbook.asks.length > 0 && orderbook.bids.length > 0) {
+        // Book-aware VWAP fill
+        const { vwap, levelsConsumed } = computeBookAwareFillPrice(side, amount, orderbook);
+        bookLevelsConsumed = levelsConsumed;
+        bookDepthAvailable = true;
+        // Market impact: VWAP vs mid-price
+        const midPrice = (orderbook.bids[0][0] + orderbook.asks[0][0]) / 2;
+        marketImpactBps = priceToBps(vwap, midPrice);
+        // For sells, impact is negative (received less), so take absolute for the metric
+        // but keep signed for the actual price
+        // Apply latency drift on top of VWAP
+        const latencyResult = applyLatencyDrift(vwap, side, latencyMs, volFactor);
+        fillPrice = latencyResult.adjustedPrice;
+        latencyImpactBps = latencyResult.latencyImpactBps;
+    }
+    else {
+        // Fallback: random slippage (same as old behavior but with latency)
+        bookLevelsConsumed = 0;
+        bookDepthAvailable = false;
+        // Random 0-2 bps base slippage + latency drift
+        const baseBps = Math.random() * 2;
+        const signedBps = side === 'buy' ? baseBps : -baseBps;
+        const basePrice = decisionPrice * (1 + signedBps / 10_000);
+        marketImpactBps = signedBps;
+        const latencyResult = applyLatencyDrift(basePrice, side, latencyMs, volFactor);
+        fillPrice = latencyResult.adjustedPrice;
+        latencyImpactBps = latencyResult.latencyImpactBps;
+    }
+    // Total slippage vs decision price
+    const slippageBps = priceToBps(fillPrice, decisionPrice);
+    const notional = amount * fillPrice;
+    const feePaid = notional * feeRate;
+    const executionQuality = {
+        decisionPrice,
+        fillPrice,
+        slippageBps,
+        marketImpactBps,
+        latencyMs,
+        latencyImpactBps,
+        fillRatio: 1.0, // Market orders always fill completely
+        feeRate,
+        feePaid,
+        bookLevelsConsumed,
+        bookDepthAvailable,
+    };
+    return { fillPrice, executionQuality };
+}
+/**
+ * Compute execution quality metrics for a limit order fill.
+ * Limit orders fill at the limit price (maker) with no market impact.
+ */
+export function computeLimitFillQuality(side, amount, limitPrice, decisionPrice, config = DEFAULT_SIMULATION_CONFIG) {
+    const feeRate = getFeeRate('limit', config);
+    const notional = amount * limitPrice;
+    const feePaid = notional * feeRate;
+    const slippageBps = priceToBps(limitPrice, decisionPrice);
+    return {
+        decisionPrice,
+        fillPrice: limitPrice,
+        slippageBps,
+        marketImpactBps: 0, // Limit orders provide liquidity, no market impact
+        latencyMs: 0,
+        latencyImpactBps: 0,
+        fillRatio: 1.0,
+        feeRate,
+        feePaid,
+        bookLevelsConsumed: 0,
+        bookDepthAvailable: false, // N/A for limits
+    };
+}

package/simulator/types.d.ts

@@ -0,0 +1,219 @@
+export interface FillError {
+    orderId: string;
+    symbol: string;
+    error: string;
+    timestamp: string;
+}
+/** Simulation configuration for realistic fills. */
+export interface SimulationConfig {
+    fees: {
+        makerRate: number;
+        takerRate: number;
+    };
+    latency: {
+        minMs: number;
+        maxMs: number;
+    };
+    partialFills: {
+        enabled: boolean;
+    };
+}
+export declare const DEFAULT_SIMULATION_CONFIG: SimulationConfig;
+/** Order book depth snapshot for realistic fill simulation. */
+export interface OrderBookDepth {
+    bids: [number, number][];
+    asks: [number, number][];
+    timestamp: number;
+}
+/** Per-fill execution quality metrics (attached to Trade records). */
+export interface ExecutionQuality {
+    decisionPrice: number;
+    fillPrice: number;
+    slippageBps: number;
+    marketImpactBps: number;
+    latencyMs: number;
+    latencyImpactBps: number;
+    fillRatio: number;
+    feeRate: number;
+    feePaid: number;
+    bookLevelsConsumed: number;
+    bookDepthAvailable: boolean;
+}
+export interface SimulatorState {
+    version: string;
+    config: {
+        startingBalance: number;
+        quoteCurrency: string;
+    };
+    wallet: Wallet;
+    positions: Position[];
+    openOrders: Order[];
+    tradeHistory: Trade[];
+    sessionStartNav?: number;
+    sessionDate?: string;
+    /** Cumulative execution quality stats for the session. */
+    executionStats?: ExecutionStats;
+    /** Epoch-ms stamp of the last in-memory mutation. Set on every
+     *  emitStateChanged and persisted. Used by replaceState() to refuse a disk
+     *  snapshot OLDER than the live in-memory state (which would revert a
+     *  just-applied, not-yet-flushed mutation). Same host clock across both
+     *  processes, so it is cross-process comparable. */
+    savedAt?: number;
+}
+/** Cumulative execution quality stats across all trades in a session. */
+export interface ExecutionStats {
+    totalTrades: number;
+    totalSlippageBps: number;
+    totalFeesPaid: number;
+    worstSlippageBps: number;
+    avgSlippageBps: number;
+    avgLatencyMs: number;
+}
+export interface Wallet {
+    [currency: string]: CurrencyBalance;
+}
+export interface CurrencyBalance {
+    total: number;
+    available: number;
+    locked: number;
+}
+/** Who initiated a position close. Default (undefined) = 'agent'.
+ *  - `stop_watcher`: paper-mode watcher fired the stop
+ *  - `bracket_attach_failed`: LiveAdapter auto-flattened when bracket submission exhausted retries
+ *  - `exchange_stop` / `exchange_target`: exchange-native STOP_MARKET / TAKE_PROFIT_MARKET triggered on Binance
+ *  - `cancelled_auto`: bracket reconciler cleaned up after detecting the position closed externally
+ *  - `operator` / `agent` / `emergency`: explicit initiator */
+export type CloseReason = 'agent' | 'stop_watcher' | 'emergency' | 'operator' | 'bracket_attach_failed' | 'exchange_stop' | 'exchange_target' | 'cancelled_auto';
+/** The agent's stated profit-realization plan, pinned at entry. PURE DATA /
+ *  indication — the plugin does NOT enforce it; it is surfaced back so the agent
+ *  can hold to its own plan instead of re-litigating. The agent fills the parts
+ *  relevant to its plan; `note` is always allowed as a free-text summary. See
+ *  the 2026-06-05 governing principle in docs/POSITION_MANAGEMENT_PLAN.md
+ *  (tools + indication + learning; force only the safety floor). */
+export interface RealizationRule {
+    type: 'fixed_target' | 'trail' | 'scale' | 'manual';
+    targetPrice?: number;
+    trailAfterR?: number;
+    trailDistanceR?: number;
+    scale?: Array<{
+        atR: number;
+        fraction: number;
+    }>;
+    note?: string;
+}
+/** Optional metadata attached at entry time — persisted in state.json.
+ *  Most fields are immutable after entry. The MFE block + closeReason are the
+ *  exceptions: MFE updates on every mark-price tick; closeReason is set at the
+ *  moment of close. */
+export interface PositionMetadata {
+    setupType?: string;
+    thesis?: string;
+    stopPrice?: number;
+    targetPrice?: number;
+    regime?: string;
+    regimeConfidence?: number;
+    scorecardVerdict?: 'STRONG_GO' | 'GO' | 'MARGINAL' | 'NO_GO';
+    confluenceScore?: number;
+    closeReason?: CloseReason;
+    /** Price at which the entry thesis is INVALIDATED — the agent's pinned "I am
+     *  wrong here" level (distinct from the protective stopPrice). Surfaced back
+     *  as indication each heartbeat so the agent holds to its own plan instead of
+     *  re-litigating. NOT enforced — the only forced thing is that a protective
+     *  stop exists. */
+    invalidationPrice?: number;
+    /** The agent's stated profit-realization plan, pinned at entry (indication,
+     *  not an enforced mechanic). */
+    realizationRule?: RealizationRule;
+    /** Entry price as it was at the moment of the FIRST fill, frozen. MFE-in-R is
+     *  denominated against this (and originalStopPrice), never against the
+     *  position's running averaged entryPrice — otherwise a scale-in would
+     *  retroactively shrink an already-achieved excursion. Seeded on the new/flip
+     *  fill; preserved through scale-ins. */
+    originalEntryPrice?: number;
+    /** Stop price as it was at the moment of fill, frozen. R-multiples are
+     *  always denominated against this value, never against current stopPrice
+     *  (which can ratchet). If the position opened without a stop, this is
+     *  undefined and `mfeR` stays undefined. */
+    originalStopPrice?: number;
+    /** Highest favourable mark price seen since entry. For longs: max(mark);
+     *  for shorts: min(mark). Updated on every mark-price tick. Seeded to
+     *  entryPrice on first observation. */
+    mfePeakPrice?: number;
+    /** Maximum favourable excursion expressed in R-multiples, where
+     *  R = |entryPrice − originalStopPrice|. Undefined if originalStopPrice
+     *  is undefined. Always non-negative; recedes only via give-back semantics
+     *  in `giveBackRatio`, never directly. */
+    mfeR?: number;
+    /** Fraction of MFE peak relative to current mark, in [0, 1+]. Defined as
+     *  `(mfePeakPriceR - currentR) / mfePeakPriceR`, only meaningful when
+     *  `mfePeakPriceR > 0`. Undefined when MFE has never been favourable. */
+    giveBackRatio?: number;
+}
+export interface Position {
+    symbol: string;
+    side: 'long' | 'short';
+    entryPrice: number;
+    quantity: number;
+    openedAt: string;
+    metadata?: PositionMetadata;
+    /** Cumulative open-side fees paid to establish (and add to) this position,
+     *  in quote currency. Carried through to Trade records on close so realized
+     *  P&L can include BOTH sides of the roundtrip. Older records without this
+     *  field are treated as 0 at read time. */
+    openFee?: number;
+}
+export interface Order {
+    id: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit';
+    status: 'open' | 'closed' | 'canceled';
+    amount: number;
+    price: number | null;
+    filled: number;
+    average: number | null;
+    cost: number;
+    fee: {
+        cost: number;
+        currency: string;
+    };
+    createdAt: string;
+    /** Entry metadata pinned to a RESTING limit order (stopPrice, thesis,
+     *  invalidation, realizationRule, …). Lives on the Order — NOT only in the
+     *  in-memory pendingOrderMetadata cache — so it is serialized in state.json
+     *  and survives a restart / two-process reload. Without this, a resting limit
+     *  that fills after a restart opened a position with no protective stop. */
+    metadata?: PositionMetadata;
+}
+export interface Trade {
+    id: string;
+    orderId: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    entryPrice: number;
+    exitPrice: number;
+    quantity: number;
+    realizedPnl: number;
+    /** CLOSE-side fee only. For backward compatibility. */
+    fee: number;
+    /** OPEN-side fee share attributable to the closed quantity (proportional for
+     *  partial closes). Added Apr 2026 — older records will be undefined and must
+     *  be treated as 0 by readers. Total roundtrip fee = `fee + (openFee ?? 0)`. */
+    openFee?: number;
+    openedAt: string;
+    closedAt: string;
+    executionQuality?: ExecutionQuality;
+    /** Entry metadata carried from the closing position. */
+    metadata?: PositionMetadata;
+}
+/** Max trades to keep in history (circular buffer) */
+export declare const MAX_TRADE_HISTORY = 1000;
+/** Fee rate for simulated trades (0.1% = Binance default) */
+export declare const FEE_RATE = 0.001;
+/**
+ * Convert a price difference to basis points.
+ * Positive = actual > reference (paid more / received more).
+ */
+export declare function priceToBps(actual: number, reference: number): number;
+/** Default state for a fresh plugin */
+export declare function createDefaultState(startingBalance: number, quoteCurrency: string): SimulatorState;

package/simulator/types.js

@@ -0,0 +1,43 @@
+// Internal simulator state types.
+// These are persisted to state.json — must be JSON-serializable.
+export const DEFAULT_SIMULATION_CONFIG = {
+    fees: {
+        makerRate: 0.0002, // 0.02% Binance Futures maker
+        takerRate: 0.0004, // 0.04% Binance Futures taker
+    },
+    latency: {
+        minMs: 50,
+        maxMs: 200,
+    },
+    partialFills: {
+        enabled: true,
+    },
+};
+/** Max trades to keep in history (circular buffer) */
+export const MAX_TRADE_HISTORY = 1000;
+/** Fee rate for simulated trades (0.1% = Binance default) */
+export const FEE_RATE = 0.001;
+/**
+ * Convert a price difference to basis points.
+ * Positive = actual > reference (paid more / received more).
+ */
+export function priceToBps(actual, reference) {
+    return ((actual - reference) / reference) * 10_000;
+}
+/** Default state for a fresh plugin */
+export function createDefaultState(startingBalance, quoteCurrency) {
+    return {
+        version: '1',
+        config: { startingBalance, quoteCurrency },
+        wallet: {
+            [quoteCurrency]: {
+                total: startingBalance,
+                available: startingBalance,
+                locked: 0,
+            },
+        },
+        positions: [],
+        openOrders: [],
+        tradeHistory: [],
+    };
+}

package/skills/reefclaw/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: reefclaw
+version: 0.0.3
+description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
+author: ReefClaw
+homepage: https://reefclaw.com
+repository: https://github.com/reefclaw/reefclaw
+license: MIT
+runtime: node
+entry: dist/index.js
+config:
+  token:
+    type: string
+    required: true
+    description: Your ReefClaw connection token (starts with rc_)
+    secret: true
+  userId:
+    type: string
+    required: false
+    description: Your ReefClaw user ID — a UUID, NOT a secret. Required to reach the relay (the room URL is keyed by it). Comes in the connect message from reefclaw.com/onboarding.
+  relayUrl:
+    type: string
+    required: false
+    description: ReefClaw relay WebSocket URL. Defaults to the production relay when omitted.
+---
+
+<!-- BOOTSTRAP SKILL.md — this is the thin installer copy shipped in the
+     @reefclaw/connect npm package. It carries ONLY the config schema and the
+     connect instructions. The FULL trading instructions (versioned 2.x.y) are
+     delivered automatically by the ReefClaw connector minutes after the first
+     successful connect, over the authenticated update channel — they replace
+     this file in place (a 0.0.x version always loses the semver comparison).
+     The "Connecting (first run)" section below MUST stay in sync with the
+     same section in skill/SKILL.md. -->
+
+# ReefClaw — Connect Your Agent (Bootstrap)
+
+You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. This bootstrap file only covers **connecting**; your full trading instructions arrive automatically a few minutes after the connection succeeds.
+
+**Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
+
+## Connecting (first run) — saving the connect message
+
+The onboarding page at [reefclaw.com/onboarding](https://reefclaw.com/onboarding) gives the user a single **connect message** that carries THREE fields:
+
+```
+Connect my agent to ReefClaw. Save these to my "reefclaw" skill config:
+token: rc_...
+userId: <a UUID>
+relayUrl: wss://...
+```
+
+When a user gives you this message (or just a bare `Here's my ReefClaw token: rc_...`):
+
+- **Save every field present to the `reefclaw` skill config**: `token` (required), `userId`, and `relayUrl`. All three nest under `skills.entries.reefclaw.config` in `~/.openclaw/openclaw.json`:
+
+  ```json
+  "skills": { "entries": { "reefclaw": { "config": {
+    "token": "rc_...", "userId": "<uuid>", "relayUrl": "wss://..."
+  } } } }
+  ```
+
+  **Do NOT put the fields directly on the `reefclaw` entry** — OpenClaw's config schema only allows `{enabled, apiKey, env, config}` there; a flat entry fails config validation and **prevents the whole gateway from starting**.
+- **`userId` is mandatory to connect** — the relay room URL is keyed by it. A token-only config **cannot reach the relay** and the connector will exit with "No user ID found". If the user pasted only a token, ask them for the full connect message from [reefclaw.com/onboarding](https://reefclaw.com/onboarding) (it includes the userId).
+- `userId` is a UUID and is **not** a secret; `relayUrl` is optional (defaults to the production relay). Only `token` is secret.
+- After saving, the connector picks the config up within seconds (it restarts until a token appears). The user does not need to run any command.
+- If you cannot write the config yourself (e.g. exec or file access is restricted in this session), show the user this exact JSON snippet and where it goes, and offer to verify it after they save it.
+
+## Installing without any terminal (preferred)
+
+OpenClaw can install the ReefClaw plugin through its own owner chat command — no exec, no terminal:
+
+1. In `~/.openclaw/openclaw.json` set `commands.plugins: true` and add the user's **sender id** (visible in this session) to `commands.ownerAllowFrom`.
+2. Tell the user to type `/restart` in this chat.
+3. Then the user types: `/plugins install npm:@reefclaw/openclaw-plugin` — the install restarts OpenClaw automatically; the bundled connector starts by itself and the dashboard flips to Connected.
+
+Only fall back to `npx @reefclaw/connect` (below) when the chat install is unavailable.
+
+## If you cannot run the installer (elevated exec disabled)
+
+Fresh OpenClaw installs deny elevated (host) exec from chat sessions. If `npx @reefclaw/connect` is blocked, do NOT dead-end — offer the user this choice:
+
+1. **Self-service (no terminal)**:
+   - Add the user's **sender id** (visible in this session's context) to `tools.elevated.allowFrom.<this channel>` in `~/.openclaw/openclaw.json`. This is an **array of sender ids per provider** — e.g. `"tools": { "elevated": { "allowFrom": { "telegram": ["12345678"] } } }` — NOT a boolean.
+   - Tell the user to type `/restart` in this chat (OpenClaw's built-in in-process restart).
+   - Then the user types `/elevated full` — elevated exec is **per-session and off until the user activates it**; OpenClaw confirms with "Elevated mode set to full". If it replies that the sender is not on the allowlist, re-check the allowFrom shape.
+   - **RETRY the install command — do not assume it is still blocked.**
+   - After the install succeeds: the user types `/elevated off` and you remove the allowFrom entry (the installed system never needs elevated exec — only the install did).
+2. **Manual (last resort)**: the user runs `npx @reefclaw/connect` themselves in a terminal on this machine — one command, nothing else.
+
+Either way, **save the connection config regardless** — the connector picks it up automatically the moment the install completes.
+
+## After connecting
+
+- The ReefClaw dashboard flips to **Connected** on its own — no manual verification step.
+- Your full trading instructions (SKILL.md version 2.x) are delivered automatically over the authenticated connection and replace this file. You will be notified in chat when that happens.
+- If more than ~10 minutes pass after a successful connect and this file is still a 0.0.x bootstrap version, tell the user to check the dashboard connection status.

package/strategy/builtin-strategies.d.ts

@@ -0,0 +1,2 @@
+import type { StrategyConfig } from './evaluator.js';
+export declare const BUILTIN_STRATEGIES: StrategyConfig[];

package/strategy/builtin-strategies.js

@@ -0,0 +1,109 @@
+// 6 built-in strategy definitions for the Strategy Box.
+// Seeded into the strategies table on first run with is_builtin: true.
+// Users can toggle them on/off but cannot delete or modify them.
+export const BUILTIN_STRATEGIES = [
+    {
+        name: 'trend_continuation',
+        description: 'Pullback entry in an established trend. Waits for price to pull back to EMA20, with MACD confirming direction, ADX showing trend strength, VWAP alignment, and non-crowded funding.',
+        version: 4,
+        regimeWhitelist: ['TREND_UP', 'TREND_DOWN'],
+        minConfidence: 0.50,
+        directionRule: 'from_regime',
+        conditions: [
+            { type: 'ema_proximity', params: { period: 20, maxDistPct: 0.01 } },
+            { type: 'macd_crossover', params: {} },
+            { type: 'adx_trending', params: { minAdx: 25 } },
+            { type: 'vwap_position', params: {} },
+            { type: 'funding_not_crowded', params: { maxZScore: 2 } },
+            { type: 'oi_slope', params: { lookbackSlots: 16, minSlope: 0 } },
+        ],
+        entryRule: { type: 'ema_offset', params: { period: 20, atrFraction: 0.3 } },
+        stopRule: { type: 'swing_atr', params: { swingCount: 3, atrFraction: 0.5 } },
+        targetRMultiples: [1.5, 2.5, 3.5],
+    },
+    {
+        name: 'mean_reversion',
+        description: 'Snap-back trade from extreme in a range-bound market. StochRSI at extreme, Bollinger breakout (overextended), contrarian funding, and elevated open interest show the setup is crowded and due to revert.',
+        version: 4,
+        regimeWhitelist: ['RANGE_TIGHT'],
+        minConfidence: 0.45,
+        directionRule: 'from_funding',
+        conditions: [
+            { type: 'stoch_rsi_extreme', params: { oversold: 20, overbought: 80 } },
+            { type: 'bollinger_breakout', params: {} },
+            { type: 'funding_contrarian', params: { maxZScore: 1.5 } },
+            { type: 'oi_elevated', params: { elevationRatio: 1.1 } },
+        ],
+        entryRule: { type: 'atr_offset', params: { atrFraction: 0.2 } },
+        stopRule: { type: 'fixed_atr', params: { atrMultiple: 1.5 } },
+        targetRMultiples: [1.5, 2.5],
+    },
+    {
+        name: 'breakout',
+        description: 'Volatility compression followed by expansion. Bollinger squeeze (tight bandwidth), ADX confirming trend building, Supertrend aligned, volume supporting the move.',
+        version: 4,
+        regimeWhitelist: ['RANGE_TIGHT', 'TREND_UP', 'TREND_DOWN', 'VOLATILITY_EXPANSION'],
+        minConfidence: 0.45,
+        directionRule: 'from_regime',
+        conditions: [
+            { type: 'bollinger_squeeze', params: { maxBandwidth: 3.0 } },
+            { type: 'adx_trending', params: { minAdx: 20 } },
+            { type: 'supertrend_direction', params: {} },
+            { type: 'vwap_position', params: {} },
+        ],
+        entryRule: { type: 'atr_offset', params: { atrFraction: 0.15 } },
+        stopRule: { type: 'swing_atr', params: { swingCount: 3, atrFraction: 0.5 } },
+        targetRMultiples: [1.5, 2.5],
+    },
+    {
+        name: 'sweep_reversal',
+        description: 'Liquidity grab reversal in a wide range. Price sweeps a key level, order flow shows absorption, OBV diverges (smart money accumulating), and funding is contrarian.',
+        version: 4,
+        regimeWhitelist: ['RANGE_WIDE'],
+        minConfidence: 0.40,
+        directionRule: 'from_sweep',
+        conditions: [
+            { type: 'price_sweep', params: { swingLookback: 5, recentBars: 10 } },
+            { type: 'order_flow_absorption', params: { maxRatio: 0.3 } },
+            { type: 'funding_contrarian', params: { maxZScore: 1.5 } },
+            { type: 'obv_divergence', params: {} },
+        ],
+        entryRule: { type: 'sweep_range', params: {} },
+        stopRule: { type: 'recent_extreme_atr', params: { atrFraction: 0.3 } },
+        targetRMultiples: [1.5, 2.5],
+    },
+    {
+        name: 'funding_reversion',
+        description: 'Mean reversion when funding hits extreme levels. Extreme funding (>2σ) indicates a crowded trade, elevated OI confirms positioning, price near a level adds confluence.',
+        version: 4,
+        regimeWhitelist: ['RANGE_TIGHT', 'RANGE_WIDE', 'TREND_UP', 'TREND_DOWN', 'VOLATILITY_EXPANSION'],
+        minConfidence: 0.40,
+        directionRule: 'from_funding',
+        conditions: [
+            { type: 'funding_extreme', params: { minZScore: 2 } },
+            { type: 'oi_elevated', params: { elevationRatio: 1.1 } },
+            { type: 'price_at_level', params: { maxDistPct: 0.005 } },
+            { type: 'stoch_rsi_extreme', params: { oversold: 20, overbought: 80 } },
+        ],
+        entryRule: { type: 'atr_offset', params: { atrFraction: 0.2 } },
+        stopRule: { type: 'fixed_atr', params: { atrMultiple: 1.5 } },
+        targetRMultiples: [1.5, 2.5],
+    },
+    {
+        name: 'momentum_divergence',
+        description: 'Trend exhaustion trade. MACD divergence (price vs momentum), OBV divergence (volume vs price), Ichimoku weakening, RSI not extreme. Catches the end of a trend before it reverses.',
+        version: 4,
+        regimeWhitelist: ['TREND_UP', 'TREND_DOWN'],
+        minConfidence: 0.42,
+        directionRule: 'from_regime',
+        conditions: [
+            { type: 'macd_divergence', params: {} },
+            { type: 'obv_divergence', params: {} },
+            { type: 'ichimoku_cloud', params: {} },
+            { type: 'stoch_rsi_extreme', params: { oversold: 30, overbought: 70 } },
+        ],
+        entryRule: { type: 'atr_offset', params: { atrFraction: 0.3 } },
+        stopRule: { type: 'swing_atr', params: { swingCount: 3, atrFraction: 0.5 } },
+        targetRMultiples: [1.5, 2.5, 3.5],
+    },
+];

package/strategy/condition-registry.d.ts

@@ -0,0 +1,3 @@
+import type { SymbolFact, ConditionEvalResult } from './evaluator.js';
+export type ConditionEvalFn = (fact: SymbolFact, params: Record<string, number>) => ConditionEvalResult;
+export declare const CONDITION_EVALUATORS: Map<string, ConditionEvalFn>;