@reefclaw/openclaw-plugin 0.1.0

package/signals/conditions/types.d.ts

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

package/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/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/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/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/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/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/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/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/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/signals/strategy-adapter.d.ts

@@ -0,0 +1,14 @@
+import type { StrategyDefinition } from './types.js';
+import type { StrategyConfig } from './conditions/types.js';
+export declare function clearStrategyGatingState(): void;
+/**
+ * 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/signals/strategy-adapter.js

@@ -0,0 +1,122 @@
+// ⚠️ 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';
+/**
+ * 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;
+}
+/** 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);
+            // ─── 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, ctx, null);
+                if (skipResults.some(c => c.met))
+                    return SKIPPED;
+            }
+            // Pass 1: evaluate conditions with direction = null
+            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ctx, null);
+            // Determine direction
+            const direction = resolveDirection(config.directionRule, ctx, condCtx);
+            // Pass 2: re-evaluate direction-sensitive conditions now that we know direction
+            // (orderbook_imbalance and funding_contrarian behave differently per direction)
+            const directionSensitive = new Set(['orderbook_imbalance', 'funding_contrarian', 'funding_extreme_skip', 'funding_position_ok', 'return_momentum']);
+            const hasDirSensitive = config.conditions.some(c => directionSensitive.has(c.type));
+            let finalConditions = pass1;
+            if (direction && hasDirSensitive) {
+                const { conditions: pass2 } = evaluateConditions(config.conditions, ctx, direction);
+                // Merge: use pass2 results for direction-sensitive, pass1 for others
+                finalConditions = pass1.map((c, i) => directionSensitive.has(config.conditions[i].type) ? pass2[i] : c);
+            }
+            const allMet = finalConditions.every(c => c.met);
+            let trade;
+            if (allMet && direction) {
+                const entryZone = computeEntry(config.entryRule, ctx, direction, condCtx);
+                const stopLevel = computeStop(config.stopRule, ctx, direction, condCtx);
+                const risk = direction === 'LONG'
+                    ? ctx.currentPrice - stopLevel
+                    : stopLevel - ctx.currentPrice;
+                const targets = config.targetRMultiples.map(rm => direction === 'LONG'
+                    ? ctx.currentPrice + risk * rm
+                    : ctx.currentPrice - risk * rm);
+                trade = { entryZone, stopLevel, targets };
+            }
+            return { direction, conditions: finalConditions, trade };
+        },
+    };
+}

package/signals/types.d.ts

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

package/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/simulator/exchange-simulator.d.ts

@@ -0,0 +1,93 @@
+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;
+    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;
+}