@reefclaw/connect 0.1.0

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

@@ -0,0 +1,41 @@
+// 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/shared/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/assets/shared/signals/strategy-adapter.js

@@ -0,0 +1,117 @@
+// Strategy adapter — converts declarative StrategyConfig (JSON) to StrategyDefinition.
+// This bridges the DB-stored configs to the evaluate() interface the engines use.
+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/assets/shared/signals/types.d.ts

@@ -0,0 +1,187 @@
+export type Direction = 'LONG' | 'SHORT';
+export interface OhlcvBar {
+    time: Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+export interface TradeFlowBucket {
+    bucket: Date;
+    buyVolume: number;
+    sellVolume: number;
+    netDelta: number;
+    largeBuyVolume: number;
+    largeSellVolume: number;
+}
+/** Market-wide signals not tied to a single symbol. Computed once per tick
+ *  by the engine and attached to every per-symbol MarketContext. */
+export interface GlobalMarketContext {
+    /** RSI(14) of BTCUSDT on the 1d timeframe, latest closed bar. */
+    btcRsi14_1d?: number;
+    /** Timestamp of the latest 1d BTC bar used for the RSI calc. */
+    btcRsi14_1d_at?: Date;
+}
+/**
+ * Market data context shared across all strategy evaluations in a single tick.
+ * Fetched once per tick, shared across strategies to avoid duplicate queries.
+ */
+export interface MarketContext {
+    symbol: string;
+    timestamp: Date;
+    /** 1h OHLCV bars, oldest first */
+    ohlcv1h: OhlcvBar[];
+    /** 5m OHLCV bars, oldest first (for swing detection) */
+    ohlcv5m: OhlcvBar[];
+    /** Current price */
+    currentPrice: number;
+    /** Current ATR(14) on 1h */
+    atr14: number;
+    /** Order book imbalance ratio (0-1, 0.5 = balanced) */
+    obImbalance: number;
+    /** Funding rates, newest first */
+    fundingRates: number[];
+    /** Funding rate stats */
+    fundingMean: number;
+    fundingStd: number;
+    /** OI data points, newest first */
+    oiValues: number[];
+    /** Recent liquidation total USD near current price (within 1%) */
+    liqNearEntry: number;
+    /** Trade flow: net delta, buy/sell volumes for last 10 minutes */
+    tradeFlow: TradeFlowBucket[];
+    /** Current regime */
+    regime: string;
+    regimeConfidence: number;
+    /** When true, conditions using unavailable data (orderbook, liquidations) should auto-pass */
+    backtestMode?: boolean;
+    /** CVD (Cumulative Volume Delta) indicators — Phase 16a */
+    cvd?: {
+        cvd1h: number;
+        cvd4h: number;
+        cvdSlope5m: number;
+        cvdSlope1h: number;
+        cvdDivergence: 'bullish' | 'bearish' | null;
+        cvdDivergenceStrength: number;
+        cvdZScore: number;
+    };
+    /** 4h OHLCV bars, oldest first. Optional — populated for strategies that
+     *  need higher-timeframe confirmation. Live tick fills this; legacy
+     *  contexts may omit it. */
+    ohlcv4h?: OhlcvBar[];
+    /** 1d OHLCV bars, oldest first. Optional — populated for daily-primary
+     *  strategies. */
+    ohlcv1d?: OhlcvBar[];
+    /** Cross-symbol / portfolio-wide signals fetched once per tick and shared
+     *  across all per-symbol contexts. Used by skipIf clauses (e.g. block
+     *  longs when BTC daily RSI is overbought). */
+    globalContext?: GlobalMarketContext;
+    /** Cross-market liquidation pulse — sub-second classification over a
+     *  rolling 60 s window. Only present when microstructure.liquidationPulse
+     *  is on. See docs/MARKET_MICROSTRUCTURE_STREAMS.md §3. */
+    cascadePulse60s?: 'quiet' | 'elevated' | 'active_cascade';
+    /** Same classification but aggregated across the majors group
+     *  (BTC + ETH + BNB + SOL + XRP). Captures market-wide stress that
+     *  precedes correlated alt moves. */
+    majorsCascadePulse60s?: 'quiet' | 'elevated' | 'active_cascade';
+    /** Which side is being flushed in the 60 s window: 'long' = longs
+     *  liquidated (force SELL), 'short' = shorts liquidated (force BUY),
+     *  'balanced' = neither side dominant. */
+    cascadeDominantSide?: 'long' | 'short' | 'balanced';
+    /** Bid share of resting USD notional in the (mid, mid + 0.5%] band, 0-1.
+     *  0.5 = balanced. > 0.5 = more bids than asks (support). < 0.5 = more
+     *  asks than bids (overhead). Only present when bandedLiquidity flag on. */
+    restingBandImbalance05?: number;
+    /** Same ratio for the 1.0% band — wider lens, smoother signal. */
+    restingBandImbalance10?: number;
+    /** Symmetric depth coverage in % units. Mirrors order_book_snapshots
+     *  column. Below the band you're querying = data unreliable. */
+    restingCoveragePct?: number;
+    /** 30-day funding-rate percentile context. Only present when
+     *  FUNDING_OVERLAY=on (the helper returns enabled:false otherwise and
+     *  fetchMarketContext leaves this undefined). Used by the
+     *  funding_extreme_skip condition. */
+    fundingPercentile?: {
+        current: number;
+        p10: number;
+        p50: number;
+        p90: number;
+        /** 0..1 rank of `current` in the 30d distribution. */
+        percentileRank: number;
+        sampleSize: number;
+    };
+}
+/** One evaluated condition's result, as surfaced on a signal. */
+export interface SignalCondition {
+    name: string;
+    met: boolean;
+    currentValue: number;
+    threshold: number;
+    description: string;
+}
+/** Output of evaluating one strategy against a MarketContext. */
+export interface StrategyEvaluation {
+    direction: Direction | null;
+    conditions: SignalCondition[];
+    /** Provided when all conditions are met */
+    trade?: {
+        entryZone: {
+            low: number;
+            high: number;
+        };
+        stopLevel: number;
+        targets: number[];
+    };
+}
+/**
+ * A strategy definition: which regimes it operates in, minimum regime
+ * confidence, and a function that evaluates conditions against a MarketContext.
+ * Produced from a declarative StrategyConfig by adaptStrategy().
+ */
+export interface StrategyDefinition {
+    name: string;
+    regimeWhitelist: string[];
+    minConfidence: number;
+    evaluate: (ctx: MarketContext) => Promise<StrategyEvaluation>;
+}
+/** A fired signal — produced by the central engine and (facts-out) the plugin
+ *  evaluator. This is the shape the agent's get_signals tool surfaces. */
+export interface SignalEvent {
+    signalId: string;
+    timestamp: string;
+    symbol: string;
+    strategy: string;
+    direction: 'LONG' | 'SHORT';
+    regime: string;
+    regimeConfidence: number;
+    confluenceScore: number;
+    conditions: SignalCondition[];
+    entryZone: {
+        low: number;
+        high: number;
+    };
+    stopLevel: number;
+    targets: number[];
+}
+/** Per-strategy state for a symbol (whether or not it fired) — the
+ *  `activeStrategies` view in a SignalSnapshot. */
+export interface StrategyState {
+    strategy: string;
+    direction: 'LONG' | 'SHORT' | null;
+    regimeGated: boolean;
+    regimeRequired: string[];
+    currentRegime: string;
+    regimeConfidence: number;
+    confluenceScore: number;
+    conditions: SignalCondition[];
+}
+/** The full per-symbol signal snapshot the get_signals tool returns. */
+export interface SignalSnapshot {
+    activeStrategies: StrategyState[];
+    recentSignals: SignalEvent[];
+    timestamp: string;
+    /** 'user' = derived from per-user state, 'global' = system background tick,
+     *  'local' = produced by the plugin-side evaluator (facts-out). */
+    scope?: 'user' | 'global' | 'local';
+}

package/assets/shared/signals/types.js

@@ -0,0 +1,9 @@
+// Market-snapshot + direction types — the canonical source of truth shared by
+// the intel signal engine (intelligence/src/signals/types.ts re-exports these)
+// and, via facts-out, the plugin-side strategy evaluator.
+//
+// PURE TYPES ONLY — no runtime code. Type imports erase at compile time, so a
+// consumer importing these from @reefclaw/shared keeps a self-contained runtime
+// (no @reefclaw/shared dependency in the emitted JS). The condition registry
+// (runtime code) is shared separately via scripts/sync-shared-code.mjs.
+export {};

package/assets/shared/trading-mode.d.ts

@@ -0,0 +1,16 @@
+export type TradingMode = 'PAPER' | 'SHADOW' | 'MICRO_LIVE' | 'LIVE';
+export declare const VALID_TRADING_MODES: readonly TradingMode[];
+/** Type guard — narrows `unknown` to `TradingMode`. */
+export declare function isTradingMode(value: unknown): value is TradingMode;
+export interface ModeTransitionResult {
+    allowed: boolean;
+    reason?: string;
+}
+/** Check whether transitioning from `from` to `to` is allowed by the ladder.
+ *  - Same mode is a no-op (allowed).
+ *  - De-escalation (lower rank) is always allowed.
+ *  - Escalation must be exactly one rung.
+ */
+export declare function validateModeTransition(from: TradingMode, to: TradingMode): ModeTransitionResult;
+/** Whether the target mode requires real exchange credentials. */
+export declare function modeRequiresCredentials(mode: TradingMode): boolean;

package/assets/shared/trading-mode.js

@@ -0,0 +1,49 @@
+// Canonical TradingMode + mode-ladder rules, shared by plugin, skill, and webapp.
+//
+// Ladder: PAPER → MICRO_LIVE → LIVE. Escalation must be one rung at a time.
+// De-escalating (e.g. LIVE → PAPER) is always allowed.
+// SHADOW was removed (Apr 16 2026) — redundant with MICRO_LIVE, confused the agent.
+export const VALID_TRADING_MODES = ['PAPER', 'MICRO_LIVE', 'LIVE'];
+const VALID_SET = new Set([...VALID_TRADING_MODES, 'SHADOW']);
+/** Type guard — narrows `unknown` to `TradingMode`. */
+export function isTradingMode(value) {
+    return typeof value === 'string' && VALID_SET.has(value);
+}
+const RANK = {
+    PAPER: 0,
+    SHADOW: 0, // Treated as PAPER if somehow encountered
+    MICRO_LIVE: 1,
+    LIVE: 2,
+};
+/** Check whether transitioning from `from` to `to` is allowed by the ladder.
+ *  - Same mode is a no-op (allowed).
+ *  - De-escalation (lower rank) is always allowed.
+ *  - Escalation must be exactly one rung.
+ */
+export function validateModeTransition(from, to) {
+    if (from === to)
+        return { allowed: true };
+    const fromRank = RANK[from];
+    const toRank = RANK[to];
+    if (toRank < fromRank)
+        return { allowed: true };
+    if (toRank - fromRank === 1)
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `Cannot jump ${from} → ${to}: must progress one rung at a time (PAPER → MICRO_LIVE → LIVE). Transition to ${adjacentUp(from)} first.`,
+    };
+}
+/** The next rung up from `mode`, used in error messages. */
+function adjacentUp(mode) {
+    switch (mode) {
+        case 'PAPER': return 'MICRO_LIVE';
+        case 'SHADOW': return 'MICRO_LIVE'; // legacy — treated as PAPER
+        case 'MICRO_LIVE': return 'LIVE';
+        case 'LIVE': return 'LIVE';
+    }
+}
+/** Whether the target mode requires real exchange credentials. */
+export function modeRequiresCredentials(mode) {
+    return mode !== 'PAPER';
+}