@reefclaw/openclaw-plugin 0.1.0

package/live/proposal-manager.js

@@ -0,0 +1,140 @@
+// ProposalManager — posts agent-emitted trade proposals to the webapp.
+//
+// Phase A scope: propose-only. Plugin generates `proposal_uuid` (v4)
+// client-side and POSTs the proposal to /api/internal/proposed_orders.
+// Fire-and-forget under the hood (same shape as TradeStoreClient) — the agent
+// turn doesn't block on this. Idempotency: the webapp upserts on
+// `proposal_uuid` so retries collapse to no-op.
+//
+// Phase B will add: ProposalDecisionListener (background relay subscriber)
+// that consumes proposed_order_decision events and fires the order via the
+// same backend path toggle-off mode uses.
+//
+// See docs/APPROVAL_MODE_DESIGN.md §2 (Architecture) + §6 (DB schema)
+// + Locked Decisions #16 (fire-and-listen) and #17 (idempotency).
+import { randomUUID } from 'node:crypto';
+import { logger, formatError } from '../logger.js';
+import { setupBucketFor, HARD_EXPIRY_MS } from './setup-buckets.js';
+const TAG = 'proposal-manager';
+export class ProposalManager {
+    opts;
+    inFlight = new Set();
+    totalPosted = 0;
+    totalSucceeded = 0;
+    totalDroppedTerminal = 0;
+    totalDroppedRetriesExhausted = 0;
+    constructor(options) {
+        this.opts = {
+            baseUrl: options.baseUrl.replace(/\/+$/, ''),
+            ingestToken: options.ingestToken,
+            fetchImpl: options.fetchImpl ?? fetch,
+            requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+            maxAttempts: options.maxAttempts ?? 4,
+            baseBackoffMs: options.baseBackoffMs ?? 250,
+            backoffCapMs: options.backoffCapMs ?? 5_000,
+            now: options.now ?? (() => new Date()),
+            uuid: options.uuid ?? (() => randomUUID()),
+        };
+    }
+    /** Submit a proposal. Generates the proposal_uuid + computes the bucket
+     *  + hard expiry synchronously; the actual POST runs in the background.
+     *  Caller may correlate via the returned proposalUuid before the post lands. */
+    propose(userId, req) {
+        const proposalUuid = this.opts.uuid();
+        const setupBucket = setupBucketFor(req.setupType);
+        const hardExpiresAt = new Date(this.opts.now().getTime() + HARD_EXPIRY_MS[setupBucket]);
+        this.totalPosted++;
+        const promise = this.run(userId, proposalUuid, setupBucket, hardExpiresAt, req).finally(() => {
+            this.inFlight.delete(promise);
+        });
+        this.inFlight.add(promise);
+        return { proposalUuid, setupBucket, hardExpiresAt };
+    }
+    /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
+    async drain() {
+        if (this.inFlight.size === 0)
+            return;
+        logger.info(TAG, `Draining ${this.inFlight.size} in-flight proposal post(s)...`);
+        await Promise.allSettled(Array.from(this.inFlight));
+    }
+    getHealth() {
+        return {
+            inFlight: this.inFlight.size,
+            totalPosted: this.totalPosted,
+            totalSucceeded: this.totalSucceeded,
+            totalDroppedTerminal: this.totalDroppedTerminal,
+            totalDroppedRetriesExhausted: this.totalDroppedRetriesExhausted,
+        };
+    }
+    // ---- Internals ----
+    async run(userId, proposalUuid, setupBucket, hardExpiresAt, req) {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders`;
+        const body = JSON.stringify({
+            proposalUuid,
+            hardExpiresAt: hardExpiresAt.toISOString(),
+            symbol: req.symbol,
+            side: req.side,
+            orderType: req.orderType,
+            size: req.size,
+            proposedEntry: req.proposedEntry,
+            stopPrice: req.stopPrice,
+            targetPrice: req.targetPrice,
+            riskUsd: req.riskUsd,
+            thesis: req.thesis,
+            setupType: req.setupType,
+            setupBucket,
+            regime: req.regime,
+            regimeConfidence: req.regimeConfidence,
+            scorecardVerdict: req.scorecardVerdict,
+            confluenceScore: req.confluenceScore,
+            ...(req.supersedesId ? { supersedesId: req.supersedesId } : {}),
+            ...(req.origin ? { origin: req.origin } : {}),
+        });
+        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+            try {
+                const ac = new AbortController();
+                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                let res;
+                try {
+                    res = await this.opts.fetchImpl(url, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${this.opts.ingestToken}`,
+                            'x-user-id': userId,
+                        },
+                        body,
+                        signal: ac.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(tid);
+                }
+                if (res.status >= 200 && res.status < 300) {
+                    this.totalSucceeded++;
+                    return;
+                }
+                if (res.status >= 400 && res.status < 500) {
+                    this.totalDroppedTerminal++;
+                    logger.warn(TAG, `POST ${url} → ${res.status} (terminal, dropped). userId=${userId} proposalUuid=${proposalUuid}`);
+                    return;
+                }
+                logger.warn(TAG, `POST ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+            }
+            catch (err) {
+                logger.warn(TAG, `POST ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+            }
+            if (attempt < this.opts.maxAttempts) {
+                await this.sleepBackoff(attempt);
+            }
+        }
+        this.totalDroppedRetriesExhausted++;
+        logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId} proposalUuid=${proposalUuid}.`);
+    }
+    async sleepBackoff(attempt) {
+        const exp = Math.min(this.opts.baseBackoffMs * 2 ** (attempt - 1), this.opts.backoffCapMs);
+        const jitter = exp * 0.2 * (Math.random() * 2 - 1);
+        const delay = Math.max(0, Math.round(exp + jitter));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}

package/live/rate-limiter.d.ts

@@ -0,0 +1,47 @@
+/** Endpoint weight map (approximate, from Binance docs). */
+export declare const ENDPOINT_WEIGHTS: Record<string, number>;
+export interface RateLimitCheck {
+    allowed: boolean;
+    retryAfterMs?: number;
+    reason?: string;
+}
+export declare class BinanceRateLimiter {
+    private ipWeights;
+    private readonly ipWeightCap;
+    private orderCounts10s;
+    private readonly orderCount10sCap;
+    private orderCounts1m;
+    private readonly orderCount1mCap;
+    constructor(opts?: {
+        ipWeightCap?: number;
+        orderCount10sCap?: number;
+        orderCount1mCap?: number;
+    });
+    /** Check all buckets before submitting a request. */
+    canSubmitOrder(weight: number): RateLimitCheck;
+    /** Check if a non-order request (query) is allowed. Only checks IP weight. */
+    canSubmitQuery(weight: number): RateLimitCheck;
+    /** Record an order request. Called after submission. */
+    recordOrder(weight: number): void;
+    /** Record a non-order request (e.g., fetchBalance). */
+    recordQuery(weight: number): void;
+    /**
+     * Sync from Binance response headers (more accurate than local estimates).
+     * Replaces local counters with exchange-reported values.
+     * Call after every CCXT request.
+     */
+    syncFromHeaders(headers: Record<string, string>): void;
+    /** Get current utilization stats. */
+    getStats(): {
+        ipWeight: number;
+        ipWeightCap: number;
+        orders10s: number;
+        orders10sCap: number;
+        orders1m: number;
+        orders1mCap: number;
+    };
+    private prune;
+    private oldestExpiry;
+    private oldestExpiry10s;
+    private oldestExpiry1m;
+}

package/live/rate-limiter.js

@@ -0,0 +1,159 @@
+// Binance rate limiter — tracks three rate limit buckets to prevent 429 bans.
+// Uses local estimation + header-based sync after each request.
+import { logger } from '../logger.js';
+const TAG = 'rate-limiter';
+/** Endpoint weight map (approximate, from Binance docs). */
+export const ENDPOINT_WEIGHTS = {
+    'createOrder': 1,
+    'cancelOrder': 1,
+    'cancelAllOrders': 1,
+    'fetchOrder': 1,
+    'fetchBalance': 5,
+    'fetchPositions': 5,
+    // BinancePrivateApi.fetchOpenOrders merges regular + algo endpoints, each
+    // 1 scoped / 40 unscoped (doc-verified 2026-05-15) → combined 2 / 80.
+    'fetchOpenOrders': 2, // regular(1) + algo(1), with symbol
+    'fetchOpenOrdersAll': 80, // regular(40) + algo(40), without symbol
+    'fetchTicker': 1,
+    'fetchOrderBook': 5,
+    'loadMarkets': 40,
+};
+export class BinanceRateLimiter {
+    // IP weight tracking (1-minute window, cap 2400, safety margin at 2000)
+    ipWeights = [];
+    ipWeightCap;
+    // Order count tracking (10-second window, cap 300, safety margin at 200)
+    orderCounts10s = []; // timestamps
+    orderCount10sCap;
+    // Order count tracking (1-minute window, cap 1200, safety margin at 1000)
+    orderCounts1m = []; // timestamps
+    orderCount1mCap;
+    constructor(opts) {
+        this.ipWeightCap = opts?.ipWeightCap ?? 2000;
+        this.orderCount10sCap = opts?.orderCount10sCap ?? 200;
+        this.orderCount1mCap = opts?.orderCount1mCap ?? 1000;
+    }
+    /** Check all buckets before submitting a request. */
+    canSubmitOrder(weight) {
+        const now = Date.now();
+        this.prune(now);
+        // Check IP weight (1-minute window)
+        const currentWeight = this.ipWeights.reduce((s, e) => s + e.w, 0);
+        if (currentWeight + weight > this.ipWeightCap) {
+            const retryAfterMs = this.oldestExpiry(this.ipWeights, 60_000, now);
+            logger.warn(TAG, `IP weight limit approaching: ${currentWeight}/${this.ipWeightCap}`);
+            return { allowed: false, retryAfterMs, reason: `IP weight ${currentWeight + weight} would exceed cap ${this.ipWeightCap}` };
+        }
+        // Check order count (10-second window)
+        if (this.orderCounts10s.length >= this.orderCount10sCap) {
+            const retryAfterMs = this.oldestExpiry10s(now);
+            logger.warn(TAG, `Order/10s limit approaching: ${this.orderCounts10s.length}/${this.orderCount10sCap}`);
+            return { allowed: false, retryAfterMs, reason: `Order count/10s ${this.orderCounts10s.length} at cap ${this.orderCount10sCap}` };
+        }
+        // Check order count (1-minute window)
+        if (this.orderCounts1m.length >= this.orderCount1mCap) {
+            const retryAfterMs = this.oldestExpiry1m(now);
+            logger.warn(TAG, `Order/1m limit approaching: ${this.orderCounts1m.length}/${this.orderCount1mCap}`);
+            return { allowed: false, retryAfterMs, reason: `Order count/1m ${this.orderCounts1m.length} at cap ${this.orderCount1mCap}` };
+        }
+        return { allowed: true };
+    }
+    /** Check if a non-order request (query) is allowed. Only checks IP weight. */
+    canSubmitQuery(weight) {
+        const now = Date.now();
+        this.prune(now);
+        const currentWeight = this.ipWeights.reduce((s, e) => s + e.w, 0);
+        if (currentWeight + weight > this.ipWeightCap) {
+            const retryAfterMs = this.oldestExpiry(this.ipWeights, 60_000, now);
+            return { allowed: false, retryAfterMs, reason: `IP weight ${currentWeight + weight} would exceed cap ${this.ipWeightCap}` };
+        }
+        return { allowed: true };
+    }
+    /** Record an order request. Called after submission. */
+    recordOrder(weight) {
+        const now = Date.now();
+        this.ipWeights.push({ ts: now, w: weight });
+        this.orderCounts10s.push(now);
+        this.orderCounts1m.push(now);
+    }
+    /** Record a non-order request (e.g., fetchBalance). */
+    recordQuery(weight) {
+        this.ipWeights.push({ ts: Date.now(), w: weight });
+    }
+    /**
+     * Sync from Binance response headers (more accurate than local estimates).
+     * Replaces local counters with exchange-reported values.
+     * Call after every CCXT request.
+     */
+    syncFromHeaders(headers) {
+        const now = Date.now();
+        // Sync IP weight — replace local estimate with exchange's actual counter
+        const usedWeight = headers['x-mbx-used-weight-1m'];
+        if (usedWeight) {
+            const actual = parseInt(usedWeight, 10);
+            if (!isNaN(actual) && actual >= 0) {
+                const local = this.ipWeights.reduce((s, e) => s + e.w, 0);
+                if (actual !== local) {
+                    // Replace all local weight entries with one entry matching exchange truth
+                    this.ipWeights = [{ ts: now, w: actual }];
+                    if (Math.abs(actual - local) > 50) {
+                        logger.info(TAG, `IP weight sync: local=${local} → actual=${actual}`);
+                    }
+                }
+            }
+        }
+        // Sync 10s order count
+        const orderCount10s = headers['x-mbx-order-count-10s'];
+        if (orderCount10s) {
+            const actual = parseInt(orderCount10s, 10);
+            if (!isNaN(actual) && actual >= 0) {
+                // Adjust local count to match. Overwrite timestamps with current time.
+                this.orderCounts10s = Array(actual).fill(now);
+            }
+        }
+        // Sync 1m order count
+        const orderCount1m = headers['x-mbx-order-count-1m'];
+        if (orderCount1m) {
+            const actual = parseInt(orderCount1m, 10);
+            if (!isNaN(actual) && actual >= 0) {
+                this.orderCounts1m = Array(actual).fill(now);
+            }
+        }
+    }
+    /** Get current utilization stats. */
+    getStats() {
+        this.prune(Date.now());
+        return {
+            ipWeight: this.ipWeights.reduce((s, e) => s + e.w, 0),
+            ipWeightCap: this.ipWeightCap,
+            orders10s: this.orderCounts10s.length,
+            orders10sCap: this.orderCount10sCap,
+            orders1m: this.orderCounts1m.length,
+            orders1mCap: this.orderCount1mCap,
+        };
+    }
+    // ---- Internal ----
+    prune(now) {
+        const oneMinAgo = now - 60_000;
+        const tenSecAgo = now - 10_000;
+        this.ipWeights = this.ipWeights.filter(e => e.ts > oneMinAgo);
+        this.orderCounts10s = this.orderCounts10s.filter(ts => ts > tenSecAgo);
+        this.orderCounts1m = this.orderCounts1m.filter(ts => ts > oneMinAgo);
+    }
+    oldestExpiry(entries, windowMs, now) {
+        if (entries.length === 0)
+            return 0;
+        const oldest = entries[0].ts;
+        return Math.max(0, oldest + windowMs - now);
+    }
+    oldestExpiry10s(now) {
+        if (this.orderCounts10s.length === 0)
+            return 0;
+        return Math.max(0, this.orderCounts10s[0] + 10_000 - now);
+    }
+    oldestExpiry1m(now) {
+        if (this.orderCounts1m.length === 0)
+            return 0;
+        return Math.max(0, this.orderCounts1m[0] + 60_000 - now);
+    }
+}

package/live/reconciler.d.ts

@@ -0,0 +1,39 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtPosition, CcxtBalance, CcxtOrder } from '../types.js';
+export interface PositionDrift {
+    symbol: string;
+    localSide: string | null;
+    exchangeSide: string | null;
+    localContracts: number;
+    exchangeContracts: number;
+    type: 'new' | 'closed' | 'size_changed' | 'side_changed';
+}
+export interface ReconciliationResult {
+    timestamp: string;
+    drifts: PositionDrift[];
+    hasDrift: boolean;
+    exchangePositions: CcxtPosition[];
+    exchangeBalance: CcxtBalance | null;
+    exchangeOpenOrders: CcxtOrder[];
+}
+export declare class PositionReconciler extends EventEmitter {
+    private adapter;
+    private interval;
+    private intervalMs;
+    private lastExchangePositions;
+    private lastReconciliation;
+    constructor(adapter: IExchangeAdapter, intervalMs?: number);
+    /** Run initial reconciliation (startup). Returns result for caller to act on. */
+    reconcileOnce(): Promise<ReconciliationResult>;
+    /** Start periodic reconciliation. */
+    start(): void;
+    /** Stop periodic reconciliation. */
+    stop(): void;
+    /** Get the last known exchange positions. */
+    getLastExchangePositions(): CcxtPosition[];
+    /** Get the timestamp of the last reconciliation. */
+    getLastReconciliationTime(): string | null;
+    /** Detect drifts between local (last known) and exchange (current) positions. */
+    private detectDrifts;
+}

package/live/reconciler.js

@@ -0,0 +1,175 @@
+// Position reconciler — periodically compares local state with exchange state.
+// In live mode, the EXCHANGE is the source of truth.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../logger.js';
+const TAG = 'reconciler';
+const DEFAULT_RECONCILE_INTERVAL_MS = 60_000; // 60 seconds
+export class PositionReconciler extends EventEmitter {
+    adapter;
+    interval = null;
+    intervalMs;
+    // Last known state from exchange
+    lastExchangePositions = [];
+    lastReconciliation = null;
+    constructor(adapter, intervalMs = DEFAULT_RECONCILE_INTERVAL_MS) {
+        super();
+        this.adapter = adapter;
+        this.intervalMs = intervalMs;
+    }
+    /** Run initial reconciliation (startup). Returns result for caller to act on. */
+    async reconcileOnce() {
+        try {
+            // NOTE: this reconciler intentionally does NOT fetch open orders.
+            // `detectDrifts` compares positions only, and NO `drift_detected`
+            // consumer reads `ReconciliationResult.exchangeOpenOrders` (verified:
+            // index.ts uses result.drifts; reconciler-cleanup.ts never references
+            // it). The old unscoped `getOpenOrders()` here was pure dead weight —
+            // 80 Binance weight (40 regular + 40 algo, symbol omitted) every 60s,
+            // ~80/min permanent, on an IP weight budget already pinned at the
+            // pacer ceiling 24/7. The bracket reconciler keeps the authoritative
+            // unscoped orphan/naked sweep; this poller has no need for it.
+            // Removing it provably changes no behaviour. See 2026-05-16 RCA.
+            const [positions, balance] = await Promise.all([
+                this.adapter.getPositionsOrNull(),
+                this.adapter.getBalance(),
+            ]);
+            const openOrders = [];
+            // null = positions fetch FAILED (429 / weight-paced / transient).
+            // Pre-fix getPositions() collapsed null→[]; detectDrifts() then saw
+            // every still-open local position as "disappeared from exchange" →
+            // emitted a `closed`/disappeared drift → reconciler-cleanup posted a
+            // SYNTHETIC CLOSE and wiped the state-store, mis-classifying the next
+            // entry as a scale-in (phantom-close class). positions + openOrders
+            // have INDEPENDENT rate-limit windows, so positions can 429 while the
+            // parallel getOpenOrders() succeeds (it throws on its own null) —
+            // i.e. this is reachable. Skip the cycle untrusted, leave
+            // lastExchangePositions intact, re-evaluate next pass. Same
+            // untrusted-snapshot-skip contract as the bracket reconciler.
+            if (positions === null) {
+                logger.warn(TAG, 'Reconcile skipped — position fetch unavailable (exchange data ' +
+                    'unavailable / 429); NOT treating as flat. Re-evaluating next cycle.');
+                return {
+                    timestamp: new Date().toISOString(),
+                    drifts: [],
+                    hasDrift: false,
+                    exchangePositions: this.lastExchangePositions,
+                    exchangeBalance: balance,
+                    exchangeOpenOrders: openOrders,
+                };
+            }
+            const drifts = this.detectDrifts(this.lastExchangePositions, positions);
+            this.lastExchangePositions = positions;
+            this.lastReconciliation = new Date().toISOString();
+            const result = {
+                timestamp: this.lastReconciliation,
+                drifts,
+                hasDrift: drifts.length > 0,
+                exchangePositions: positions,
+                exchangeBalance: balance,
+                exchangeOpenOrders: openOrders,
+            };
+            if (drifts.length > 0) {
+                logger.warn(TAG, `Position drift detected: ${drifts.length} discrepancies`);
+                for (const d of drifts) {
+                    logger.warn(TAG, `  ${d.symbol}: ${d.type} (local: ${d.localContracts} ${d.localSide ?? 'none'}, exchange: ${d.exchangeContracts} ${d.exchangeSide ?? 'none'})`);
+                }
+                this.emit('drift_detected', result);
+            }
+            else {
+                logger.info(TAG, `Reconciliation OK: ${positions.length} positions`);
+            }
+            return result;
+        }
+        catch (err) {
+            logger.error(TAG, `Reconciliation failed: ${formatError(err)}`);
+            throw err;
+        }
+    }
+    /** Start periodic reconciliation. */
+    start() {
+        if (this.interval) {
+            logger.warn(TAG, 'Reconciler already running');
+            return;
+        }
+        logger.info(TAG, `Starting periodic reconciliation every ${this.intervalMs / 1000}s`);
+        this.interval = setInterval(async () => {
+            try {
+                await this.reconcileOnce();
+            }
+            catch (err) {
+                logger.error(TAG, `Periodic reconciliation error: ${formatError(err)}`);
+            }
+        }, this.intervalMs);
+    }
+    /** Stop periodic reconciliation. */
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+            logger.info(TAG, 'Reconciler stopped');
+        }
+    }
+    /** Get the last known exchange positions. */
+    getLastExchangePositions() {
+        return this.lastExchangePositions;
+    }
+    /** Get the timestamp of the last reconciliation. */
+    getLastReconciliationTime() {
+        return this.lastReconciliation;
+    }
+    // ---- Internal ----
+    /** Detect drifts between local (last known) and exchange (current) positions. */
+    detectDrifts(local, exchange) {
+        const drifts = [];
+        const localMap = new Map(local.map(p => [p.symbol, p]));
+        const exchangeMap = new Map(exchange.map(p => [p.symbol, p]));
+        // Check for new positions on exchange (not in local)
+        for (const [symbol, ep] of exchangeMap) {
+            const lp = localMap.get(symbol);
+            if (!lp) {
+                drifts.push({
+                    symbol,
+                    localSide: null,
+                    exchangeSide: ep.side,
+                    localContracts: 0,
+                    exchangeContracts: ep.contracts,
+                    type: 'new',
+                });
+            }
+            else if (lp.side !== ep.side) {
+                drifts.push({
+                    symbol,
+                    localSide: lp.side,
+                    exchangeSide: ep.side,
+                    localContracts: lp.contracts,
+                    exchangeContracts: ep.contracts,
+                    type: 'side_changed',
+                });
+            }
+            else if (Math.abs(lp.contracts - ep.contracts) > 1e-10) {
+                drifts.push({
+                    symbol,
+                    localSide: lp.side,
+                    exchangeSide: ep.side,
+                    localContracts: lp.contracts,
+                    exchangeContracts: ep.contracts,
+                    type: 'size_changed',
+                });
+            }
+        }
+        // Check for closed positions (in local but not on exchange)
+        for (const [symbol, lp] of localMap) {
+            if (!exchangeMap.has(symbol)) {
+                drifts.push({
+                    symbol,
+                    localSide: lp.side,
+                    exchangeSide: null,
+                    localContracts: lp.contracts,
+                    exchangeContracts: 0,
+                    type: 'closed',
+                });
+            }
+        }
+        return drifts;
+    }
+}

package/live/setup-buckets.d.ts

@@ -0,0 +1,7 @@
+export type SetupBucket = 'momentum' | 'mean_reversion';
+/** Classify a setup_type into the appropriate hard-expiry bucket.
+ *  Unknown / empty / non-string inputs → 'mean_reversion' (the safer default). */
+export declare function setupBucketFor(setupType: string | undefined | null): SetupBucket;
+/** Hard-expiry duration in milliseconds for each bucket. Matches the defaults
+ *  in approval.hardExpiry from docs/APPROVAL_MODE_DESIGN.md §4. */
+export declare const HARD_EXPIRY_MS: Record<SetupBucket, number>;

package/live/setup-buckets.js

@@ -0,0 +1,33 @@
+// Setup-type → expiry bucket mapping for approval-mode proposals.
+//
+// Hardcoded per Locked Decision #18 in docs/APPROVAL_MODE_DESIGN.md §1:
+//   momentum        — fast-decaying signals; proposal hard-expires at 90 sec
+//   mean_reversion  — slower-decaying; proposal hard-expires at 4 min
+//
+// New setup_type strings default to mean_reversion. Add them explicitly to
+// MOMENTUM_SETUPS when a new momentum strategy lands.
+//
+// Why hardcoded here rather than on each strategy config: setup_type strings
+// are produced by the agent at proposal time and aren't tied to a single
+// strategy file — multiple strategies may emit the same setup_type. A single
+// source of truth keeps the bucket assignment auditable and easy to change.
+/** Setup types whose signal value decays fast. Hard expiry = 90 sec. */
+const MOMENTUM_SETUPS = new Set([
+    'breakout',
+    'trend_continuation',
+    'triple_top_breakdown',
+]);
+/** Classify a setup_type into the appropriate hard-expiry bucket.
+ *  Unknown / empty / non-string inputs → 'mean_reversion' (the safer default). */
+export function setupBucketFor(setupType) {
+    if (typeof setupType !== 'string' || setupType.length === 0) {
+        return 'mean_reversion';
+    }
+    return MOMENTUM_SETUPS.has(setupType) ? 'momentum' : 'mean_reversion';
+}
+/** Hard-expiry duration in milliseconds for each bucket. Matches the defaults
+ *  in approval.hardExpiry from docs/APPROVAL_MODE_DESIGN.md §4. */
+export const HARD_EXPIRY_MS = {
+    momentum: 90_000,
+    mean_reversion: 240_000,
+};

package/live/slippage-tracker.d.ts

@@ -0,0 +1,45 @@
+export interface SlippageRecord {
+    orderId: string;
+    clientOrderId?: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    expectedPrice: number;
+    actualPrice: number;
+    slippageBps: number;
+    amount: number;
+    cost: number;
+    fee: number;
+    timestamp: number;
+}
+export declare class SlippageTracker {
+    private records;
+    private readonly maxRecords;
+    constructor(maxRecords?: number);
+    /** Record a fill with slippage measurement. */
+    recordFill(params: {
+        orderId: string;
+        clientOrderId?: string;
+        symbol: string;
+        side: 'buy' | 'sell';
+        expectedPrice: number;
+        actualPrice: number;
+        amount: number;
+        cost: number;
+        fee: number;
+    }): SlippageRecord;
+    /** Get average slippage in bps for a symbol. */
+    getAverageSlippage(symbol?: string): number;
+    /** Get slippage stats summary. */
+    getStats(symbol?: string): {
+        count: number;
+        avgBps: number;
+        maxBps: number;
+        minBps: number;
+        p95Bps: number;
+        totalCost: number;
+    };
+    /** Get recent records (last N). */
+    getRecent(count?: number): SlippageRecord[];
+    /** Get all records for a symbol. */
+    getRecordsForSymbol(symbol: string): SlippageRecord[];
+}