@reefclaw/openclaw-plugin 0.1.0

package/persistence/state-manager.js

@@ -0,0 +1,164 @@
+// State persistence manager for the paper trading simulator.
+// Saves/loads state to ~/.openclaw/plugins/reefclaw-paper-trading/state.json
+// Uses atomic writes (temp file + rename) to prevent corruption.
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../logger.js';
+import { createDefaultState } from '../simulator/types.js';
+const TAG = 'state-manager';
+export class StateManager {
+    statePath;
+    saveTimer = null;
+    pendingState = null;
+    constructor(pluginId, baseDir) {
+        const base = baseDir ?? join(homedir(), '.openclaw', 'plugins', pluginId);
+        this.statePath = join(base, 'state.json');
+    }
+    getStatePath() {
+        return this.statePath;
+    }
+    /** Quarantine a state file that exists but won't parse, instead of letting
+     *  the caller silently overwrite it with a fresh default (which would wipe
+     *  the positions/orders/realized-PnL ledger). The corrupt bytes are renamed
+     *  to `<state>.corrupt-<ts>` so an operator can recover them. Returns true if
+     *  a corrupt file was quarantined. */
+    quarantineCorruptSync() {
+        if (!existsSync(this.statePath))
+            return false;
+        const dest = `${this.statePath}.corrupt-${Date.now()}`;
+        try {
+            renameSync(this.statePath, dest);
+            logger.error(TAG, `State file at ${this.statePath} is unreadable/corrupt — quarantined to ${dest}. NOT resetting silently; a fresh default will be used. Investigate before trading.`);
+        }
+        catch (err) {
+            logger.error(TAG, `State file at ${this.statePath} is corrupt AND could not be quarantined: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return true;
+    }
+    /** Load state from disk. Returns null when the file is MISSING (fresh start)
+     *  OR when it exists-but-is-unreadable (in which case the corrupt bytes are
+     *  quarantined first — never silently discarded). The two cases are
+     *  distinguished in the log; both yield null so the caller seeds a default,
+     *  but a corrupt file is preserved as `<state>.corrupt-<ts>`. */
+    async load() {
+        if (!existsSync(this.statePath)) {
+            logger.info(TAG, `No state file found at ${this.statePath}`);
+            return null;
+        }
+        try {
+            const raw = await readFile(this.statePath, 'utf-8');
+            const state = JSON.parse(raw);
+            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
+            return state;
+        }
+        catch {
+            // Exists but unreadable/corrupt — preserve, don't silently reset.
+            this.quarantineCorruptSync();
+            return null;
+        }
+    }
+    /** Save state atomically (write to a UNIQUE temp, rename to final). A unique
+     *  temp name (pid + uuid) is essential under the two-process model: both the
+     *  agent and gateway processes wire stateChanged→save, and a shared
+     *  `<state>.tmp` let their concurrent writes interleave into a torn file that
+     *  then parses as garbage on next boot. With a per-write temp, the worst case
+     *  degrades to a harmless last-writer-wins rename of two COMPLETE files. */
+    async save(state) {
+        const tmpPath = `${this.statePath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            const dir = dirname(this.statePath);
+            if (!existsSync(dir)) {
+                await mkdir(dir, { recursive: true });
+            }
+            await writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+            await rename(tmpPath, this.statePath);
+            logger.debug(TAG, 'State saved');
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to save state: ${err instanceof Error ? err.message : String(err)}`);
+            // Best-effort cleanup of the orphaned temp so they don't accumulate.
+            await unlink(tmpPath).catch(() => { });
+        }
+    }
+    /**
+     * Debounced save — coalesces rapid mutations into one write per second.
+     * Call this on every state change; it will save at most once per second.
+     */
+    debouncedSave(state) {
+        this.pendingState = state;
+        if (this.saveTimer)
+            return; // Already scheduled
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            if (this.pendingState) {
+                const s = this.pendingState;
+                this.pendingState = null;
+                this.save(s).catch(() => { });
+            }
+        }, 1000);
+    }
+    /** Flush any pending debounced save immediately. */
+    async flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.pendingState) {
+            const s = this.pendingState;
+            this.pendingState = null;
+            await this.save(s);
+        }
+    }
+    /** Load state or create default if not found. */
+    async loadOrDefault(startingBalance, quoteCurrency) {
+        const loaded = await this.load();
+        if (loaded)
+            return loaded;
+        const state = createDefaultState(startingBalance, quoteCurrency);
+        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
+        await this.save(state);
+        return state;
+    }
+    /** Synchronous load — for use in synchronous plugin register(). Same
+     *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
+     *  (preserved), never silently overwritten by the default the caller seeds. */
+    loadSync() {
+        if (!existsSync(this.statePath)) {
+            logger.info(TAG, `No state file found at ${this.statePath}`);
+            return null;
+        }
+        try {
+            const raw = readFileSync(this.statePath, 'utf-8');
+            const state = JSON.parse(raw);
+            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
+            return state;
+        }
+        catch {
+            this.quarantineCorruptSync();
+            return null;
+        }
+    }
+    /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
+    loadOrDefaultSync(startingBalance, quoteCurrency) {
+        const loaded = this.loadSync();
+        if (loaded)
+            return loaded;
+        const state = createDefaultState(startingBalance, quoteCurrency);
+        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
+        // Save synchronously so state persists immediately
+        try {
+            const dir = dirname(this.statePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to save initial state: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return state;
+    }
+}

package/pinned-plan.d.ts

@@ -0,0 +1,9 @@
+/** Has the agent's pinned invalidation price been reached at the current mark?
+ *
+ *  Long: invalidated when mark <= invalidationPrice.
+ *  Short: invalidated when mark >= invalidationPrice.
+ *
+ *  Returns undefined when there is nothing to check — no pinned invalidation,
+ *  or no usable mark — so a missing plan reads as "unknown", never a false
+ *  "not hit". Pure. */
+export declare function computeInvalidationHit(side: 'long' | 'short', markPrice: number | undefined, invalidationPrice: number | undefined): boolean | undefined;

package/pinned-plan.js

@@ -0,0 +1,23 @@
+// Pinned trade plan — derived indication helpers (Slice 1, Task 5).
+//
+// Pure functions surfaced to the agent at heartbeat (via fetch_positions →
+// CcxtPosition) so it can hold to its OWN plan instead of re-litigating the
+// entry every cycle. Indication only — nothing here enforces anything; the
+// only forced thing on the position is that a protective stop exists.
+/** Has the agent's pinned invalidation price been reached at the current mark?
+ *
+ *  Long: invalidated when mark <= invalidationPrice.
+ *  Short: invalidated when mark >= invalidationPrice.
+ *
+ *  Returns undefined when there is nothing to check — no pinned invalidation,
+ *  or no usable mark — so a missing plan reads as "unknown", never a false
+ *  "not hit". Pure. */
+export function computeInvalidationHit(side, markPrice, invalidationPrice) {
+    if (invalidationPrice == null ||
+        !Number.isFinite(invalidationPrice) ||
+        markPrice == null ||
+        !Number.isFinite(markPrice)) {
+        return undefined;
+    }
+    return side === 'long' ? markPrice <= invalidationPrice : markPrice >= invalidationPrice;
+}

package/risk/pre-trade-check.d.ts

@@ -0,0 +1,38 @@
+import type { DrawdownZone, PreTradeRiskLimits, PreTradeResult, ProposedOrder, PortfolioSnapshot, PreTradeOptions } from './pre-trade-types.js';
+export declare function getDefaultPreTradeLimits(): PreTradeRiskLimits;
+/** @deprecated Use getDefaultPreTradeLimits() for dynamic values */
+export declare const DEFAULT_PRE_TRADE_LIMITS: PreTradeRiskLimits;
+export declare function getDrawdownThresholds(): {
+    YELLOW: number;
+    ORANGE: number;
+    RED: number;
+};
+export declare const DRAWDOWN_ZONE_THRESHOLDS: {
+    readonly YELLOW: -0.01;
+    readonly ORANGE: -0.02;
+    readonly RED: -0.025;
+};
+/** Determine drawdown zone from drawdown ratio (e.g. -0.015 = -1.5%). */
+export declare function getDrawdownZone(drawdownRatio: number): DrawdownZone;
+/** Compute volatility factor from current ATR vs baseline. Clamped [0.5, 3.0]. */
+export declare function computeVolFactor(currentAtr: number, baselineAtr: number): number;
+/** Adjust a limit value by volatility factor. Higher vol = tighter limit. */
+export declare function adjustLimitByVol(defaultLimit: number, volFactor: number): number;
+/** Check if an order is closing an existing position (partial or full). */
+export declare function isClosingOrder(order: ProposedOrder, positions: PortfolioSnapshot['positions']): boolean;
+export declare const EQUITY_FLOOR: {
+    /** Max single-position notional as a fraction of equity.
+     *  Raised 0.25 → 0.40 on 2026-04-20 so small live accounts ($186) can fit
+     *  BTC's ~$75 min-lot. Still protects against all-in entries. Tracked for
+     *  promotion to operator-configurable trading param in the next session. */
+    readonly MAX_POSITION_PCT: 0.4;
+    /** Max per-trade risk (expected loss) as a fraction of equity. */
+    readonly MAX_PER_TRADE_LOSS_PCT: 0.02;
+    /** Presumed adverse move when an order has no explicit stopPrice. */
+    readonly NO_STOP_ASSUMED_ADVERSE: 0.05;
+};
+export declare function preTradeRiskCheck(order: ProposedOrder, portfolio: PortfolioSnapshot, limits?: PreTradeRiskLimits, options?: PreTradeOptions): PreTradeResult;
+/** Count consecutive losses from the end of a trade history array. */
+export declare function computeConsecutiveLosses(trades: Array<{
+    realizedPnl: number;
+}>): number;

package/risk/pre-trade-check.js

@@ -0,0 +1,345 @@
+// Pre-trade risk gate — pure function.
+// Validates a proposed order against portfolio limits, drawdown zones, and volatility.
+// Lives in the plugin (synchronous access to simulator state).
+import { getCachedTradingParams } from '../trading-params-cache.js';
+// ---- Default pre-trade limits (now read from trading params cache) ----
+export function getDefaultPreTradeLimits() {
+    const tp = getCachedTradingParams();
+    return {
+        maxPositionSize: tp.maxPositionSize,
+        maxOpenPositions: tp.maxOpenPositions,
+        maxGrossExposure: tp.maxGrossExposure,
+        maxPerTradeLoss: tp.maxPerTradeLoss,
+    };
+}
+/** @deprecated Use getDefaultPreTradeLimits() for dynamic values */
+export const DEFAULT_PRE_TRADE_LIMITS = {
+    maxPositionSize: 10_000,
+    maxOpenPositions: 5,
+    maxGrossExposure: 1.5,
+    maxPerTradeLoss: 500,
+};
+// ---- Drawdown zone thresholds (now read from trading params cache) ----
+export function getDrawdownThresholds() {
+    const tp = getCachedTradingParams();
+    return {
+        YELLOW: tp.drawdownYellow,
+        ORANGE: tp.drawdownOrange,
+        RED: tp.drawdownRed,
+    };
+}
+export const DRAWDOWN_ZONE_THRESHOLDS = {
+    YELLOW: -0.01, // -1%
+    ORANGE: -0.02, // -2%
+    RED: -0.025, // -2.5%
+};
+// ---- Pure helpers ----
+/** Determine drawdown zone from drawdown ratio (e.g. -0.015 = -1.5%). */
+export function getDrawdownZone(drawdownRatio) {
+    const thresholds = getDrawdownThresholds();
+    if (drawdownRatio <= thresholds.RED)
+        return 'RED';
+    if (drawdownRatio <= thresholds.ORANGE)
+        return 'ORANGE';
+    if (drawdownRatio <= thresholds.YELLOW)
+        return 'YELLOW';
+    return 'GREEN';
+}
+/** Compute volatility factor from current ATR vs baseline. Clamped [0.5, 3.0]. */
+export function computeVolFactor(currentAtr, baselineAtr) {
+    if (baselineAtr <= 0 || currentAtr <= 0)
+        return 1.0;
+    return Math.max(0.5, Math.min(3.0, currentAtr / baselineAtr));
+}
+/** Adjust a limit value by volatility factor. Higher vol = tighter limit. */
+export function adjustLimitByVol(defaultLimit, volFactor) {
+    if (volFactor <= 1.0)
+        return defaultLimit;
+    return defaultLimit / volFactor;
+}
+/** Check if an order is closing an existing position (partial or full). */
+export function isClosingOrder(order, positions) {
+    const pos = positions.find(p => p.symbol === order.symbol);
+    if (!pos)
+        return false;
+    // Sell against a long = closing; buy against a short = closing
+    return (pos.side === 'long' && order.side === 'sell') ||
+        (pos.side === 'short' && order.side === 'buy');
+}
+// ---- Main pre-trade gate ----
+// ---- Equity-proportional floors (safety net for tiny accounts) ----
+// These are independent of the configurable trading params and exist so that
+// a $10,000 static `maxPositionSize` default can't allow a $289 account to
+// open an $8,000 position. They shrink the effective caps relative to current
+// equity; the tighter of (absolute limit, equity-proportional floor) wins.
+export const EQUITY_FLOOR = {
+    /** Max single-position notional as a fraction of equity.
+     *  Raised 0.25 → 0.40 on 2026-04-20 so small live accounts ($186) can fit
+     *  BTC's ~$75 min-lot. Still protects against all-in entries. Tracked for
+     *  promotion to operator-configurable trading param in the next session. */
+    MAX_POSITION_PCT: 0.40,
+    /** Max per-trade risk (expected loss) as a fraction of equity. */
+    MAX_PER_TRADE_LOSS_PCT: 0.02,
+    /** Presumed adverse move when an order has no explicit stopPrice. */
+    NO_STOP_ASSUMED_ADVERSE: 0.05,
+};
+export function preTradeRiskCheck(order, portfolio, limits = DEFAULT_PRE_TRADE_LIMITS, options = {}) {
+    const violations = [];
+    const volFactor = options.volFactor ?? 1.0;
+    // Caller-provided equity is authoritative; fall back to local compute for
+    // legacy test callers that don't supply it.
+    const currentEquity = portfolio.equity ?? computePortfolioEquity(portfolio);
+    // Drawdown anchor: prefer sessionStartNav, fall back to current equity.
+    const nav = portfolio.sessionStartNav > 0 ? portfolio.sessionStartNav : currentEquity;
+    const drawdownRatio = nav > 0 ? (currentEquity - nav) / nav : 0;
+    const zone = getDrawdownZone(drawdownRatio);
+    // Classify the order against any same-symbol position BEFORE the zone gates:
+    //   - pure reduce / full close  → "closing": exempt from entry gates (exits
+    //     must always work, even in RED/ORANGE).
+    //   - flip (over-close)         → closes the old leg AND opens a NEW opposite
+    //     leg; the NEW leg must clear every entry gate (drawdown zone, size,
+    //     gross, per-trade-loss, bracket requirement). Previously a flip took the
+    //     exit exemption and opened unchecked, possibly oversized, stop-less
+    //     exposure — even in the RED zone (M6).
+    //   - same-direction add (scale-in) / fresh entry → full entry checks (M5).
+    // Emergency flatten bypasses this function entirely (EmergencyControls → adapter.createOrder).
+    const closingPos = portfolio.positions.find(p => p.symbol === order.symbol &&
+        ((p.side === 'long' && order.side === 'sell') || (p.side === 'short' && order.side === 'buy')));
+    const flipAmount = closingPos ? order.amount - closingPos.quantity : 0;
+    const isFlip = closingPos != null && flipAmount > 1e-9 * Math.max(closingPos.quantity, 1);
+    const closing = closingPos != null && !isFlip; // reduce/close, opens no new exposure
+    // The leg that opens new exposure and must clear the entry gates. For a flip
+    // it's ONLY the excess beyond the closed position; otherwise the whole order.
+    // stopPrice/targetPrice carry over so the per-trade-loss and live
+    // bracket-requirement gates evaluate against the new leg's real stop.
+    const entryOrder = isFlip ? { ...order, amount: flipAmount } : order;
+    // Bracket requirement gates — only apply to entries (not closes) when the
+    // caller explicitly passes `bracketEnforcement`. Closes are exempt so
+    // operators can always exit, even if the entry broke the policy.
+    if (!closing && options.bracketEnforcement) {
+        const { requireStopLoss, requireTakeProfit } = options.bracketEnforcement;
+        if (requireStopLoss && (order.stopPrice === undefined || !(order.stopPrice > 0))) {
+            violations.push({
+                rule: 'requireStopLoss',
+                message: 'Live trades require a stopPrice. Disable requireStopLoss in Trading Parameters to override (not recommended).',
+                current: 0,
+                limit: 1,
+            });
+        }
+        if (requireTakeProfit && (order.targetPrice === undefined || !(order.targetPrice > 0))) {
+            violations.push({
+                rule: 'requireTakeProfit',
+                message: 'Live trades require a target_price. Disable requireTakeProfit in Trading Parameters to override.',
+                current: 0,
+                limit: 1,
+            });
+        }
+        if (violations.length > 0) {
+            return {
+                allowed: false,
+                violations,
+                drawdownZone: zone,
+                effectiveMaxPositionSize: 0,
+            };
+        }
+    }
+    // Exits are always allowed regardless of drawdown zone
+    if (closing) {
+        const effectiveMax = computeEffectivePositionSize(limits.maxPositionSize, volFactor, zone);
+        return {
+            allowed: true,
+            violations: [],
+            drawdownZone: zone,
+            effectiveMaxPositionSize: effectiveMax,
+        };
+    }
+    // RED zone: reject new entries (exits already handled above)
+    if (zone === 'RED') {
+        violations.push({
+            rule: 'drawdownZone',
+            message: `RED zone (${(drawdownRatio * 100).toFixed(2)}% drawdown) — new entries rejected`,
+            current: drawdownRatio,
+            limit: DRAWDOWN_ZONE_THRESHOLDS.RED,
+        });
+        return {
+            allowed: false,
+            violations,
+            drawdownZone: zone,
+            effectiveMaxPositionSize: 0,
+        };
+    }
+    // ORANGE zone: only exits allowed (already handled above)
+    if (zone === 'ORANGE') {
+        violations.push({
+            rule: 'drawdownZone',
+            message: `ORANGE zone (${(drawdownRatio * 100).toFixed(2)}% drawdown) — new entries blocked, exits only`,
+            current: drawdownRatio,
+            limit: DRAWDOWN_ZONE_THRESHOLDS.ORANGE,
+        });
+        return {
+            allowed: false,
+            violations,
+            drawdownZone: zone,
+            effectiveMaxPositionSize: 0,
+        };
+    }
+    // ---- Entry checks (GREEN/YELLOW) ----
+    const streak = options.consecutiveLosses ?? 0;
+    const tp = getCachedTradingParams();
+    // Equity-proportional floor — shrinks the static cap on small accounts.
+    // A $10k default `maxPositionSize` is useless on a $289 account; cap to
+    // `EQUITY_FLOOR.MAX_POSITION_PCT` of current equity. The tighter of the two wins.
+    const equityPositionCap = currentEquity > 0
+        ? currentEquity * EQUITY_FLOOR.MAX_POSITION_PCT
+        : limits.maxPositionSize;
+    const scaledMaxPositionSize = Math.min(limits.maxPositionSize, equityPositionCap);
+    let effectiveMaxPositionSize = computeEffectivePositionSize(scaledMaxPositionSize, volFactor, zone);
+    // Graduated size reduction on loss streaks (never a hard block — that creates deadlocks)
+    // Ensure correct ordering: the harsher reduction (0.25x) needs the higher threshold
+    const quarterThreshold = Math.max(tp.lossStreakQuarterSize, tp.lossStreakHalfSize);
+    const halfThreshold = Math.min(tp.lossStreakQuarterSize, tp.lossStreakHalfSize);
+    if (streak >= quarterThreshold) {
+        effectiveMaxPositionSize *= 0.25;
+    }
+    else if (streak >= halfThreshold) {
+        effectiveMaxPositionSize *= 0.5;
+    }
+    // 1. Position size check — against the RESULTING position notional, not just
+    //    this order's increment. A same-direction scale-in must include the
+    //    existing leg, or repeated small adds each pass individually yet build a
+    //    position far beyond the per-symbol cap (M5). A flip's resulting position
+    //    is only the new opposite leg (the old leg is closed), so the existing
+    //    notional is NOT added there.
+    const entryNotional = entryOrder.amount * order.price;
+    const sameSymbolPos = portfolio.positions.find(p => p.symbol === order.symbol);
+    const isScaleIn = sameSymbolPos != null &&
+        ((sameSymbolPos.side === 'long' && order.side === 'buy') ||
+            (sameSymbolPos.side === 'short' && order.side === 'sell'));
+    const existingNotional = isScaleIn && sameSymbolPos
+        ? sameSymbolPos.quantity * (sameSymbolPos.markPrice ?? sameSymbolPos.entryPrice)
+        : 0;
+    const resultingNotional = existingNotional + entryNotional;
+    if (resultingNotional > effectiveMaxPositionSize) {
+        violations.push({
+            rule: 'positionSize',
+            message: `Resulting position notional $${resultingNotional.toFixed(2)} (existing $${existingNotional.toFixed(2)} + order $${entryNotional.toFixed(2)}) exceeds effective max $${effectiveMaxPositionSize.toFixed(2)} (equity $${currentEquity.toFixed(2)}, cap ${(EQUITY_FLOOR.MAX_POSITION_PCT * 100).toFixed(0)}% of equity)`,
+            current: resultingNotional,
+            limit: effectiveMaxPositionSize,
+        });
+    }
+    // 2. Open positions count (would a new symbol exceed limit?)
+    const existingSymbols = new Set(portfolio.positions.map(p => p.symbol));
+    if (!existingSymbols.has(order.symbol)) {
+        const newCount = existingSymbols.size + 1;
+        if (newCount > limits.maxOpenPositions) {
+            violations.push({
+                rule: 'openPositions',
+                message: `New position would bring count to ${newCount}, max is ${limits.maxOpenPositions}`,
+                current: newCount,
+                limit: limits.maxOpenPositions,
+            });
+        }
+    }
+    // 3. Projected gross exposure. On a flip the closed leg leaves the book, so
+    //    net it out — otherwise the projection double-counts the position we close.
+    if (nav > 0) {
+        const currentGross = computeGrossExposure(portfolio);
+        const closedLegNotional = isFlip && closingPos
+            ? closingPos.quantity * (closingPos.markPrice ?? closingPos.entryPrice)
+            : 0;
+        const projectedGross = currentGross - closedLegNotional + entryNotional;
+        const projectedRatio = projectedGross / nav;
+        const effectiveMaxGross = adjustLimitByVol(limits.maxGrossExposure, volFactor);
+        if (projectedRatio > effectiveMaxGross) {
+            violations.push({
+                rule: 'grossExposure',
+                message: `Projected gross exposure ${projectedRatio.toFixed(2)}x exceeds limit ${effectiveMaxGross.toFixed(2)}x`,
+                current: projectedRatio,
+                limit: effectiveMaxGross,
+            });
+        }
+    }
+    // 4. Per-trade loss check — MANDATORY (was previously opt-in on stopPrice).
+    // Without a stop, we presume a 5% adverse move as the worst-case loss. This
+    // prevents the gate from waving through stopless entries on thin accounts.
+    if (!closing) {
+        // Use the opening leg's amount/notional (the flip's new leg, or the whole
+        // order for a fresh entry/scale-in) so the flip's new exposure is gated.
+        const expectedLoss = order.stopPrice != null
+            ? Math.abs(order.price - order.stopPrice) * entryOrder.amount
+            : entryNotional * EQUITY_FLOOR.NO_STOP_ASSUMED_ADVERSE;
+        const equityLossCap = currentEquity > 0
+            ? currentEquity * EQUITY_FLOOR.MAX_PER_TRADE_LOSS_PCT
+            : limits.maxPerTradeLoss;
+        const scaledPerTradeLoss = Math.min(limits.maxPerTradeLoss, equityLossCap);
+        if (expectedLoss > scaledPerTradeLoss) {
+            const stopNote = order.stopPrice != null
+                ? `stop @ ${order.stopPrice}`
+                : `no stop — assumed ${(EQUITY_FLOOR.NO_STOP_ASSUMED_ADVERSE * 100).toFixed(0)}% adverse move`;
+            violations.push({
+                rule: 'perTradeLoss',
+                message: `Expected loss $${expectedLoss.toFixed(2)} (${stopNote}) exceeds per-trade limit $${scaledPerTradeLoss.toFixed(2)} (${(EQUITY_FLOOR.MAX_PER_TRADE_LOSS_PCT * 100).toFixed(0)}% of equity $${currentEquity.toFixed(2)})`,
+                current: expectedLoss,
+                limit: scaledPerTradeLoss,
+            });
+        }
+    }
+    return {
+        allowed: violations.length === 0,
+        violations,
+        drawdownZone: zone,
+        effectiveMaxPositionSize,
+    };
+}
+// ---- Exported helpers ----
+/** Count consecutive losses from the end of a trade history array. */
+export function computeConsecutiveLosses(trades) {
+    let streak = 0;
+    for (let i = trades.length - 1; i >= 0; i--) {
+        if (trades[i].realizedPnl < 0) {
+            streak++;
+        }
+        else {
+            break;
+        }
+    }
+    return streak;
+}
+// ---- Internal helpers ----
+function computeEffectivePositionSize(baseMax, volFactor, zone) {
+    let effective = adjustLimitByVol(baseMax, volFactor);
+    if (zone === 'YELLOW') {
+        effective *= 0.5; // YELLOW halves position sizes
+    }
+    return effective;
+}
+function computePortfolioEquity(portfolio) {
+    let equity = portfolio.walletTotal;
+    for (const pos of portfolio.positions) {
+        const mark = pos.markPrice ?? pos.entryPrice;
+        const pnl = pos.side === 'long'
+            ? (mark - pos.entryPrice) * pos.quantity
+            : (pos.entryPrice - mark) * pos.quantity;
+        if (portfolio.isLive) {
+            // Live Binance: wallet already includes margin — add only unrealized P&L.
+            equity += pnl;
+        }
+        else {
+            // Paper simulator (SPOT-collateral model): the full entry notional was
+            // deducted from wallet at open and is released on close, so we must add
+            // it back here. Same formula for longs and shorts — the previous
+            // `-qty*mark` short branch was arithmetically wrong and underrepresented
+            // equity by 2*entry*qty whenever the account held a short.
+            equity += pos.entryPrice * pos.quantity + pnl;
+        }
+    }
+    return equity;
+}
+function computeGrossExposure(portfolio) {
+    let gross = 0;
+    for (const pos of portfolio.positions) {
+        const price = pos.markPrice ?? pos.entryPrice;
+        gross += Math.abs(pos.quantity * price);
+    }
+    return gross;
+}

package/risk/pre-trade-types.d.ts

@@ -0,0 +1,60 @@
+export type DrawdownZone = 'GREEN' | 'YELLOW' | 'ORANGE' | 'RED';
+export interface PreTradeRiskLimits {
+    maxPositionSize: number;
+    maxOpenPositions: number;
+    maxGrossExposure: number;
+    maxPerTradeLoss: number;
+}
+export interface ProposedOrder {
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit';
+    amount: number;
+    price: number;
+    stopPrice?: number;
+    targetPrice?: number;
+}
+export interface PortfolioSnapshot {
+    positions: Array<{
+        symbol: string;
+        side: 'long' | 'short';
+        quantity: number;
+        entryPrice: number;
+        markPrice?: number;
+    }>;
+    walletTotal: number;
+    walletAvailable: number;
+    sessionStartNav: number;
+    /** Mark-to-market total account value. If provided, takes precedence over
+     *  the gate's own equity computation — the caller's value is authoritative
+     *  because it has access to the real simulator/exchange state. When absent
+     *  (legacy test callers), the gate falls back to an internal computation. */
+    equity?: number;
+    /** Paper simulator deducts notional from wallet at entry — equity = wallet + position value.
+     *  Live Binance wallet already includes margin — equity = wallet + unrealized PnL only. */
+    isLive?: boolean;
+}
+export interface PreTradeViolation {
+    rule: string;
+    message: string;
+    current: number;
+    limit: number;
+}
+export interface PreTradeResult {
+    allowed: boolean;
+    violations: PreTradeViolation[];
+    drawdownZone: DrawdownZone;
+    effectiveMaxPositionSize: number;
+}
+export interface PreTradeOptions {
+    volFactor?: number;
+    consecutiveLosses?: number;
+    /** When true, the gate rejects entries without a stopPrice and/or targetPrice
+     *  based on the flags below. Only meaningful in live mode with bracket orders
+     *  enabled — in paper/off mode the stop-watcher handles protection and these
+     *  flags don't apply (gate ignores them). */
+    bracketEnforcement?: {
+        requireStopLoss: boolean;
+        requireTakeProfit: boolean;
+    };
+}

package/risk/pre-trade-types.js

@@ -0,0 +1,3 @@
+// Pre-trade risk gate types.
+// Used by preTradeRiskCheck() to validate orders before they reach the simulator.
+export {};