@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/simulator/fill-engine.d.ts

@@ -1,53 +0,0 @@
-import type { Order, Position, Wallet, Trade, OrderBookDepth, SimulationConfig, ExecutionQuality, PositionMetadata } from './types.js';
-/** Result of filling an order */
-export interface FillResult {
-    /** The filled order (status set to 'closed') */
-    order: Order;
-    /** Updated or new position (null if position was fully closed) */
-    position: Position | null;
-    /** Closed trade record (only when closing/reducing a position) */
-    trade: Trade | null;
-    /** Wallet balance changes: { currency: delta } */
-    walletDeltas: Record<string, number>;
-    /** Execution quality metrics (Phase 9a) */
-    executionQuality?: ExecutionQuality;
-}
-/**
- * Compute simulated slippage for a market order (legacy mode).
- * Returns basis points: random 0-2 bps, signed based on order side.
- * BUY: positive slippage (pay more), SELL: negative slippage (receive less).
- */
-export declare function computeSlippage(side: 'buy' | 'sell'): number;
-/**
- * Apply slippage to a price.
- * @param price Base price
- * @param slippageBps Slippage in basis points (signed)
- * @returns Adjusted price
- */
-export declare function applySlippage(price: number, slippageBps: number): number;
-/**
- * Parse the base and quote currencies from a symbol like "BTC/USDT".
- */
-export declare function parseSymbol(symbol: string): {
-    base: string;
-    quote: string;
-};
-/** Options for realistic market fills (Phase 9a). */
-export interface RealisticFillOptions {
-    orderbook?: OrderBookDepth | null;
-    config?: SimulationConfig;
-    volFactor?: number;
-    /** Position metadata to attach on new position creation. */
-    metadata?: PositionMetadata;
-}
-/**
- * Fill a market order immediately at the given price (plus slippage).
- * When realistic options are provided, uses book-aware VWAP + latency + maker/taker fees.
- * Otherwise falls back to legacy random slippage + flat fee.
- */
-export declare function fillMarketOrder(order: Order, currentPrice: number, wallet: Wallet, existingPosition: Position | null, realistic?: RealisticFillOptions): FillResult;
-/**
- * Fill a limit order (when price crosses the limit price).
- * Limit orders fill at the limit price. When config is provided, uses maker fee rate.
- */
-export declare function fillLimitOrder(order: Order, wallet: Wallet, existingPosition: Position | null, config?: SimulationConfig, decisionPrice?: number, metadata?: PositionMetadata): FillResult;

package/assets/plugin/simulator/fill-engine.js

@@ -1,280 +0,0 @@
-// Fill engine for simulated order execution (derivatives model).
-// All accounting in quote currency (USDT). Supports long and short positions.
-// Opening any direction: deduct notional + fee from USDT.
-// Closing: credit margin + PnL - fee to USDT.
-//
-// Phase 9a: Supports realistic fills (book-aware VWAP, latency, maker/taker fees)
-// when SimulationConfig and OrderBookDepth are provided. Falls back to legacy
-// behavior (0-2 bps random slippage, 0.1% flat fee) when not provided.
-import { FEE_RATE } from './types.js';
-import { computeRealisticMarketFill, computeLimitFillQuality, getFeeRate, } from './realistic-fills.js';
-/** On NEW-position creation only, freeze the at-fill stop into
- *  `originalStopPrice` and seed `mfePeakPrice` to the entry price. Component C
- *  uses these as immutable denominators / starting points for MFE tracking.
- *  Scale-ins and partial closes preserve whatever was set on the first fill —
- *  this helper is intentionally only called from the brand-new and flip code
- *  paths, never from the scale-in path. */
-function seedMfeMetadata(metadata, fillPrice) {
-    const seeded = { ...(metadata ?? {}) };
-    if (seeded.originalEntryPrice === undefined) {
-        seeded.originalEntryPrice = fillPrice; // frozen R/MFE entry reference
-    }
-    if (seeded.originalStopPrice === undefined && seeded.stopPrice !== undefined) {
-        seeded.originalStopPrice = seeded.stopPrice;
-    }
-    if (seeded.mfePeakPrice === undefined) {
-        seeded.mfePeakPrice = fillPrice;
-    }
-    return seeded;
-}
-/**
- * Compute simulated slippage for a market order (legacy mode).
- * Returns basis points: random 0-2 bps, signed based on order side.
- * BUY: positive slippage (pay more), SELL: negative slippage (receive less).
- */
-export function computeSlippage(side) {
-    const bps = Math.random() * 2; // 0 to 2 bps
-    return side === 'buy' ? bps : -bps;
-}
-/**
- * Apply slippage to a price.
- * @param price Base price
- * @param slippageBps Slippage in basis points (signed)
- * @returns Adjusted price
- */
-export function applySlippage(price, slippageBps) {
-    return price * (1 + slippageBps / 10_000);
-}
-/**
- * Parse the base and quote currencies from a symbol like "BTC/USDT".
- */
-export function parseSymbol(symbol) {
-    const parts = symbol.split('/');
-    if (parts.length !== 2) {
-        throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE`);
-    }
-    const [quote, settle, ...extra] = parts[1].split(':');
-    if (!quote || extra.length > 0 || (settle !== undefined && settle !== quote)) {
-        throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE or BASE/QUOTE:QUOTE`);
-    }
-    return { base: parts[0], quote };
-}
-/**
- * Ensure a currency exists in the wallet with at least zero balance.
- */
-function ensureCurrency(wallet, currency) {
-    if (!wallet[currency]) {
-        wallet[currency] = { total: 0, available: 0, locked: 0 };
-    }
-    return wallet[currency];
-}
-/**
- * Fill a market order immediately at the given price (plus slippage).
- * When realistic options are provided, uses book-aware VWAP + latency + maker/taker fees.
- * Otherwise falls back to legacy random slippage + flat fee.
- */
-export function fillMarketOrder(order, currentPrice, wallet, existingPosition, realistic) {
-    if (realistic?.config) {
-        // Phase 9a: Realistic fill path
-        const { fillPrice, executionQuality } = computeRealisticMarketFill(order.side, order.amount, currentPrice, realistic.orderbook ?? null, realistic.volFactor ?? 1.0, realistic.config);
-        const feeRate = getFeeRate('market', realistic.config);
-        return executeOrderFill(order, fillPrice, wallet, existingPosition, feeRate, executionQuality, realistic.metadata);
-    }
-    // Legacy path: random 0-2 bps slippage + flat 0.1% fee
-    const slippageBps = computeSlippage(order.side);
-    const fillPrice = applySlippage(currentPrice, slippageBps);
-    return executeOrderFill(order, fillPrice, wallet, existingPosition);
-}
-/**
- * Fill a limit order (when price crosses the limit price).
- * Limit orders fill at the limit price. When config is provided, uses maker fee rate.
- */
-export function fillLimitOrder(order, wallet, existingPosition, config, decisionPrice, metadata) {
-    if (order.price === null) {
-        throw new Error('Limit order must have a price');
-    }
-    const feeRate = config ? getFeeRate('limit', config) : undefined;
-    const executionQuality = config && decisionPrice !== undefined
-        ? computeLimitFillQuality(order.side, order.amount, order.price, decisionPrice, config)
-        : undefined;
-    return executeOrderFill(order, order.price, wallet, existingPosition, feeRate, executionQuality, metadata);
-}
-/**
- * Core fill logic (derivatives model).
- * All accounting in quote currency. Both longs and shorts use USDT as collateral.
- *
- * Opening: deduct notional + fee from quote balance.
- * Closing: credit (entry_notional + directional_PnL - fee) to quote balance.
- * Flip: close existing + open opposite, fees split proportionally.
- *
- * Trade PnL is directional only (no fee deduction) — fees are tracked separately
- * and already reflected in wallet balance changes.
- *
- * @param feeRateOverride When provided, overrides the legacy FEE_RATE (Phase 9a maker/taker)
- * @param executionQuality When provided, attached to the Trade record (Phase 9a)
- */
-function executeOrderFill(order, fillPrice, wallet, existingPosition, feeRateOverride, executionQuality, metadata) {
-    const { quote } = parseSymbol(order.symbol);
-    const activeFeeRate = feeRateOverride ?? FEE_RATE;
-    const notional = order.amount * fillPrice;
-    const fee = notional * activeFeeRate;
-    const now = new Date().toISOString();
-    const quoteBalance = ensureCurrency(wallet, quote);
-    let position = null;
-    let trade = null;
-    let totalWalletDelta = 0;
-    let totalFee = fee;
-    // Determine relationship to existing position
-    const isClosing = existingPosition && ((existingPosition.side === 'long' && order.side === 'sell') ||
-        (existingPosition.side === 'short' && order.side === 'buy'));
-    if (existingPosition && isClosing) {
-        // --- CLOSING / REDUCING / FLIPPING ---
-        const closeQty = Math.min(order.amount, existingPosition.quantity);
-        const closeNotional = closeQty * fillPrice;
-        const closeFee = closeNotional * activeFeeRate;
-        // Directional PnL (no fee — fee tracked separately in trade record)
-        const pnl = existingPosition.side === 'long'
-            ? (fillPrice - existingPosition.entryPrice) * closeQty
-            : (existingPosition.entryPrice - fillPrice) * closeQty;
-        // Open-side fee attributable to this close (proportional for partial closes).
-        // Older positions without `openFee` are treated as 0 (legacy roundtrip error).
-        const totalOpenFee = existingPosition.openFee ?? 0;
-        const openFeeShare = existingPosition.quantity > 0
-            ? totalOpenFee * (closeQty / existingPosition.quantity)
-            : 0;
-        // Credit: release original margin + PnL - close fee
-        const credit = existingPosition.entryPrice * closeQty + pnl - closeFee;
-        quoteBalance.available += credit;
-        quoteBalance.total += credit;
-        totalWalletDelta += credit;
-        trade = {
-            id: `trade-${order.id}`,
-            orderId: order.id,
-            symbol: order.symbol,
-            side: order.side,
-            entryPrice: existingPosition.entryPrice,
-            exitPrice: fillPrice,
-            quantity: closeQty,
-            realizedPnl: pnl,
-            fee: closeFee,
-            openFee: openFeeShare,
-            openedAt: existingPosition.openedAt,
-            closedAt: now,
-            executionQuality,
-            metadata: existingPosition.metadata,
-        };
-        const remaining = existingPosition.quantity - closeQty;
-        if (remaining > 0) {
-            // Partial close — position reduced, metadata preserved, remaining openFee proportional
-            position = {
-                ...existingPosition,
-                quantity: remaining,
-                openFee: totalOpenFee - openFeeShare,
-            };
-        }
-        else if (order.amount > existingPosition.quantity) {
-            // Flip: close existing + open opposite (must be atomic)
-            const flipQty = order.amount - existingPosition.quantity;
-            const flipNotional = flipQty * fillPrice;
-            const flipFee = flipNotional * activeFeeRate;
-            // Affordability check for the flip leg. The close credit was already
-            // applied to quoteBalance.available above, so `available` IS the true
-            // post-close figure — do NOT add `credit` again. Double-counting the
-            // released margin would pass an unaffordable flip and overdraw the
-            // wallet negative. On failure we roll the credit back below.
-            const projectedAvailable = quoteBalance.available;
-            if (projectedAvailable < flipNotional + flipFee) {
-                // Rollback the close credit already applied above
-                quoteBalance.available -= credit;
-                quoteBalance.total -= credit;
-                totalWalletDelta -= credit;
-                throw new Error(`Insufficient ${quote} balance for position flip. After closing, would have ${projectedAvailable.toFixed(2)} but need ${(flipNotional + flipFee).toFixed(2)}`);
-            }
-            quoteBalance.available -= flipNotional + flipFee;
-            quoteBalance.total -= flipNotional + flipFee;
-            totalWalletDelta -= flipNotional + flipFee;
-            // Accounting invariant: the affordability check above guarantees a
-            // non-negative balance. If this ever fires, the flip math regressed.
-            if (quoteBalance.available < -1e-6) {
-                throw new Error(`Wallet overdrawn during flip (available=${quoteBalance.available.toFixed(2)}) — accounting invariant violated`);
-            }
-            position = {
-                symbol: order.symbol,
-                side: order.side === 'buy' ? 'long' : 'short',
-                entryPrice: fillPrice,
-                quantity: flipQty,
-                openedAt: now,
-                metadata: seedMfeMetadata(metadata, fillPrice),
-                openFee: flipFee,
-            };
-            totalFee = closeFee + flipFee;
-        }
-        // else: fully closed, position remains null, totalFee = closeFee
-        else {
-            totalFee = closeFee;
-        }
-    }
-    else if (existingPosition && !isClosing) {
-        // --- ADDING TO EXISTING POSITION (same direction) ---
-        if (quoteBalance.available < notional + fee) {
-            throw new Error(`Insufficient ${quote} balance. Need ${(notional + fee).toFixed(2)}, have ${quoteBalance.available.toFixed(2)}`);
-        }
-        quoteBalance.available -= notional + fee;
-        quoteBalance.total -= notional + fee;
-        totalWalletDelta = -(notional + fee);
-        // Average entry price
-        const totalQty = existingPosition.quantity + order.amount;
-        const avgEntry = (existingPosition.entryPrice * existingPosition.quantity + fillPrice * order.amount) / totalQty;
-        // Scale-in: preserve frozen MFE state (originalStopPrice + the running
-        // peak) from the first fill, while letting the agent override mutable
-        // entry-context fields like updated stopPrice / thesis on this fill.
-        const baseMeta = existingPosition.metadata ?? {};
-        const incomingMeta = metadata ?? {};
-        const mergedMeta = {
-            ...baseMeta,
-            ...incomingMeta,
-            originalEntryPrice: baseMeta.originalEntryPrice ?? incomingMeta.originalEntryPrice,
-            originalStopPrice: baseMeta.originalStopPrice ?? incomingMeta.originalStopPrice,
-            mfePeakPrice: baseMeta.mfePeakPrice ?? incomingMeta.mfePeakPrice,
-        };
-        position = {
-            ...existingPosition,
-            entryPrice: avgEntry,
-            quantity: totalQty,
-            metadata: mergedMeta,
-            openFee: (existingPosition.openFee ?? 0) + fee,
-        };
-    }
-    else {
-        // --- NEW POSITION ---
-        if (quoteBalance.available < notional + fee) {
-            throw new Error(`Insufficient ${quote} balance. Need ${(notional + fee).toFixed(2)}, have ${quoteBalance.available.toFixed(2)}`);
-        }
-        quoteBalance.available -= notional + fee;
-        quoteBalance.total -= notional + fee;
-        totalWalletDelta = -(notional + fee);
-        position = {
-            symbol: order.symbol,
-            side: order.side === 'buy' ? 'long' : 'short',
-            entryPrice: fillPrice,
-            quantity: order.amount,
-            openedAt: now,
-            metadata: seedMfeMetadata(metadata, fillPrice),
-            openFee: fee,
-        };
-    }
-    // Build the filled order
-    const filledOrder = {
-        ...order,
-        status: 'closed',
-        filled: order.amount,
-        average: fillPrice,
-        cost: notional,
-        fee: { cost: totalFee, currency: quote },
-    };
-    const walletDeltas = {};
-    if (totalWalletDelta !== 0) {
-        walletDeltas[quote] = totalWalletDelta;
-    }
-    return { order: filledOrder, position, trade, walletDeltas, executionQuality };
-}

package/assets/plugin/simulator/paper-market-feed.d.ts

@@ -1,26 +0,0 @@
-import type { CcxtTicker } from '../types.js';
-import type { ExchangeSimulator } from './exchange-simulator.js';
-export declare const DEFAULT_FEED_INTERVAL_MS = 5000;
-export declare const MAX_SYMBOLS_PER_TICK = 30;
-/** Narrow ticker source — only the method the feed needs. Lets tests inject a
- *  fake without constructing a real CCXT client. */
-export interface TickerSource {
-    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
-}
-export declare class PaperMarketFeed {
-    private readonly tickerSource;
-    private readonly simulator;
-    private readonly intervalMs;
-    private interval;
-    private ticking;
-    constructor(tickerSource: TickerSource, simulator: ExchangeSimulator, intervalMs?: number);
-    /** Idempotent — a second start() while running is a no-op. */
-    start(): void;
-    stop(): void;
-    isRunning(): boolean;
-    /** One refresh cycle. Exposed for tests (no setInterval). Never throws —
-     *  a fetch failure on one symbol is logged and skipped; state self-heals on
-     *  the next tick. Overlapping ticks are suppressed (a slow fetch round can
-     *  outlast the interval). */
-    tick(): Promise<void>;
-}

package/assets/plugin/simulator/paper-market-feed.js

@@ -1,104 +0,0 @@
-// Paper-mode background market-data feed.
-//
-// WHY: in paper mode the simulator's per-symbol lastTicker map is the SOLE
-// source of mark price, unrealized PnL, NAV, MFE, the stop-watcher breach
-// check, AND the resting-limit fill trigger. Nothing else refreshes it on a
-// timer — updateTicker fires only when the agent happens to call a price tool.
-// The skill gateway poller refreshes only the ONE dashboard symbol, so every
-// other symbol the agent trades (routine — it scans/trades many pairs) had its
-// mark FROZEN at entry until the next heartbeat: the stop-watcher compared a
-// stale mark and never fired, NAV/uPnL went stale, and resting limits missed.
-//
-// This poller closes that gap: every `intervalMs` it collects the symbols with
-// an open position OR an open order and refreshes each via the simulator's
-// updateTicker (which also runs MFE + the pending-limit-fill check). It is
-// paper-only and skips entirely when the book is flat, so it adds zero Binance
-// weight when there is nothing to track.
-//
-// Weight: it reuses the single-symbol, ban-gated BinancePublicApi.fetchTicker
-// (Binance GET /fapi/v1/ticker/24hr with a symbol = weight 1) one symbol at a
-// time. For a realistic paper book (a handful of open symbols) this is lighter
-// than CCXT fetchTickers(), which hits the all-symbols endpoint (weight 40).
-import { logger, formatError } from '../logger.js';
-const TAG = 'paper-market-feed';
-// 5s: well inside the 10s stop-watcher interval (so a breach is seen with a
-// fresh mark on the next watcher tick) and trivial weight for a small book.
-export const DEFAULT_FEED_INTERVAL_MS = 5_000;
-// Defensive upper bound on symbols refreshed per tick, so a pathological book
-// can't issue an unbounded burst of reads. A real paper book is far smaller;
-// if we ever hit the cap we log it (no silent truncation).
-export const MAX_SYMBOLS_PER_TICK = 30;
-export class PaperMarketFeed {
-    tickerSource;
-    simulator;
-    intervalMs;
-    interval = null;
-    ticking = false;
-    constructor(tickerSource, simulator, intervalMs = DEFAULT_FEED_INTERVAL_MS) {
-        this.tickerSource = tickerSource;
-        this.simulator = simulator;
-        this.intervalMs = intervalMs;
-    }
-    /** Idempotent — a second start() while running is a no-op. */
-    start() {
-        if (this.interval)
-            return;
-        logger.info(TAG, `Starting paper market feed (interval: ${this.intervalMs}ms)`);
-        this.interval = setInterval(() => {
-            void this.tick();
-        }, this.intervalMs);
-    }
-    stop() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-    }
-    isRunning() {
-        return this.interval !== null;
-    }
-    /** One refresh cycle. Exposed for tests (no setInterval). Never throws —
-     *  a fetch failure on one symbol is logged and skipped; state self-heals on
-     *  the next tick. Overlapping ticks are suppressed (a slow fetch round can
-     *  outlast the interval). */
-    async tick() {
-        if (this.ticking)
-            return;
-        this.ticking = true;
-        try {
-            const state = this.simulator.getState();
-            const symbols = new Set();
-            for (const p of state.positions)
-                symbols.add(p.symbol);
-            for (const o of state.openOrders)
-                symbols.add(o.symbol);
-            if (symbols.size === 0)
-                return; // flat — no work, no Binance weight
-            let list = Array.from(symbols);
-            if (list.length > MAX_SYMBOLS_PER_TICK) {
-                logger.warn(TAG, `Open-symbol count ${list.length} exceeds per-tick cap ${MAX_SYMBOLS_PER_TICK} — refreshing the first ${MAX_SYMBOLS_PER_TICK}; the rest refresh next tick`);
-                list = list.slice(0, MAX_SYMBOLS_PER_TICK);
-            }
-            for (const symbol of list) {
-                let ticker;
-                try {
-                    ticker = await this.tickerSource.fetchTicker(symbol);
-                }
-                catch (err) {
-                    // fetchTicker already swallows + returns null, but guard the
-                    // weight-pacer throw path too so one symbol never aborts the loop.
-                    logger.warn(TAG, `fetchTicker(${symbol}) threw: ${formatError(err)}`);
-                    continue;
-                }
-                // Reject garbage marks (a null/0 last would poison NAV / open a
-                // 0-priced fill — mirrors the simulator's own mark > 0 guard).
-                if (ticker && Number.isFinite(ticker.last) && ticker.last > 0) {
-                    this.simulator.updateTicker(ticker);
-                }
-            }
-        }
-        finally {
-            this.ticking = false;
-        }
-    }
-}

package/assets/plugin/simulator/realistic-fills.d.ts

@@ -1,59 +0,0 @@
-import type { OrderBookDepth, SimulationConfig, ExecutionQuality } 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 declare function computeBookAwareFillPrice(side: 'buy' | 'sell', amount: number, orderbook: OrderBookDepth): {
-    vwap: number;
-    levelsConsumed: number;
-};
-/**
- * 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 declare function applyLatencyDrift(basePrice: number, side: 'buy' | 'sell', latencyMs: number, volFactor: number): {
-    adjustedPrice: number;
-    latencyImpactBps: number;
-};
-/**
- * Generate a random simulated latency within the configured range.
- */
-export declare function generateLatency(config: SimulationConfig): number;
-/**
- * Compute the fee rate based on order type (maker vs taker).
- * Market orders = taker. Limit orders = maker.
- */
-export declare function getFeeRate(orderType: 'market' | 'limit', config: SimulationConfig): number;
-/**
- * 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 declare function computeRealisticMarketFill(side: 'buy' | 'sell', amount: number, decisionPrice: number, orderbook: OrderBookDepth | null, volFactor: number, config?: SimulationConfig): {
-    fillPrice: number;
-    executionQuality: ExecutionQuality;
-};
-/**
- * Compute execution quality metrics for a limit order fill.
- * Limit orders fill at the limit price (maker) with no market impact.
- */
-export declare function computeLimitFillQuality(side: 'buy' | 'sell', amount: number, limitPrice: number, decisionPrice: number, config?: SimulationConfig): ExecutionQuality;