@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/live/local-strategy-evaluator.d.ts

@@ -1,62 +0,0 @@
-import type { MarketContext, StrategyConfig, SignalCondition, Direction, SignalEvent, StrategyState } from '@reefclaw/shared';
-/** A locally-evaluated signal — the same shape the agent gets from the central engine. */
-export interface LocalSignal {
-    symbol: string;
-    strategy: string;
-    direction: Direction;
-    regime: string;
-    regimeConfidence: number;
-    /** Fraction of conditions met, 0..1. */
-    confluenceScore: number;
-    conditions: SignalCondition[];
-    entryZone: {
-        low: number;
-        high: number;
-    };
-    stopLevel: number;
-    targets: number[];
-    /** ms epoch the signal fired. */
-    firedAt: number;
-}
-export interface EvaluatorParams {
-    /** Min fraction of conditions met to fire (intel default 1.0). */
-    confluenceThreshold: number;
-    /** Floor applied to each strategy's minConfidence (intel: per-user trading param). */
-    regimeConfidenceFloor: number;
-    /** Min ms between identical (strategy, symbol, direction) signals. */
-    cooldownMs: number;
-}
-export declare const DEFAULT_EVALUATOR_PARAMS: EvaluatorParams;
-/**
- * Evaluates the user's strategies locally against incoming fact-contexts.
- *
- * Single-tenant (one plugin == one user), so cooldown state is keyed
- * `strategy:symbol:direction` — there is no user dimension, unlike the central
- * engine. Higher-timeframe tick gating lives inside the shared strategy-adapter
- * (module-level), so a strategy only re-evaluates once per closed primary-tf bar.
- */
-export declare class LocalStrategyEvaluator {
-    /** `strategy:symbol:direction` → last fired ms. */
-    private readonly cooldowns;
-    /**
-     * Full per-symbol snapshot — every strategy's state (whether or not it fired)
-     * plus the signals that fired this evaluation. A faithful mirror of
-     * intelligence/src/signals/engine.ts:evaluateSymbol (regime gate → state;
-     * evaluate → confluence → state; confluence + cooldown → SignalEvent), minus
-     * the intel-only side effects (DB persist, mission create, degradation gate).
-     *
-     * `now` is injected for determinism/testability — pass `Date.now()` live.
-     */
-    evaluateSnapshot(ctx: MarketContext, strategies: StrategyConfig[], now: number, params?: EvaluatorParams): Promise<{
-        states: StrategyState[];
-        signals: SignalEvent[];
-    }>;
-    /**
-     * Convenience wrapper that returns only the fired signals as LocalSignal[].
-     * Thin layer over evaluateSnapshot so there is a single source of evaluation
-     * logic.
-     */
-    evaluate(ctx: MarketContext, strategies: StrategyConfig[], now: number, params?: EvaluatorParams): Promise<LocalSignal[]>;
-    /** Clear cooldown state (e.g. when the strategy set changes). */
-    reset(): void;
-}

package/assets/plugin/live/local-strategy-evaluator.js

@@ -1,131 +0,0 @@
-// Plugin-side strategy evaluator — facts-out (docs/FACTS_OUT_ARCHITECTURE.md) step 3b.
-//
-// Runs strategy evaluation LOCALLY in the plugin instead of calling the central
-// intel signal engine. It runs the SAME shared evaluation core (adaptStrategy →
-// conditions + direction/entry/stop rules; PRs #42–44) that intel runs, then
-// applies the engine's thin orchestration — regime gate → confluence → cooldown
-// — to produce the same signal shape the agent receives today. This is a
-// faithful mirror of intelligence/src/signals/engine.ts:evaluateSymbol, minus
-// the intel-only concerns (DB persistence, mission creation, per-user passes,
-// degradation gate).
-//
-// NOT wired into the heartbeat yet — the SSE fact stream (step 4) feeds it.
-// Built + tested standalone; rollout will be shadow (compare vs the central
-// engine) → enforce.
-import { adaptStrategy } from '../signals/strategy-adapter.js';
-export const DEFAULT_EVALUATOR_PARAMS = {
-    confluenceThreshold: 1.0,
-    regimeConfidenceFloor: 0,
-    cooldownMs: 300_000,
-};
-/**
- * Evaluates the user's strategies locally against incoming fact-contexts.
- *
- * Single-tenant (one plugin == one user), so cooldown state is keyed
- * `strategy:symbol:direction` — there is no user dimension, unlike the central
- * engine. Higher-timeframe tick gating lives inside the shared strategy-adapter
- * (module-level), so a strategy only re-evaluates once per closed primary-tf bar.
- */
-export class LocalStrategyEvaluator {
-    /** `strategy:symbol:direction` → last fired ms. */
-    cooldowns = new Map();
-    /**
-     * Full per-symbol snapshot — every strategy's state (whether or not it fired)
-     * plus the signals that fired this evaluation. A faithful mirror of
-     * intelligence/src/signals/engine.ts:evaluateSymbol (regime gate → state;
-     * evaluate → confluence → state; confluence + cooldown → SignalEvent), minus
-     * the intel-only side effects (DB persist, mission create, degradation gate).
-     *
-     * `now` is injected for determinism/testability — pass `Date.now()` live.
-     */
-    async evaluateSnapshot(ctx, strategies, now, params = DEFAULT_EVALUATOR_PARAMS) {
-        const states = [];
-        const signals = [];
-        for (const config of strategies) {
-            const executionModel = config.executionModel;
-            if (executionModel !== undefined && executionModel !== 'declarative') {
-                continue;
-            }
-            const def = adaptStrategy(config);
-            // Regime gate (engine.ts): effective floor is the LOWER of the strategy's
-            // own minConfidence and the user's regimeConfidenceFloor.
-            const effectiveMinConf = Math.min(def.minConfidence, params.regimeConfidenceFloor || def.minConfidence);
-            if (!def.regimeWhitelist.includes(ctx.regime) || ctx.regimeConfidence < effectiveMinConf) {
-                states.push({
-                    strategy: config.name,
-                    direction: null,
-                    regimeGated: true,
-                    regimeRequired: def.regimeWhitelist,
-                    currentRegime: ctx.regime,
-                    regimeConfidence: ctx.regimeConfidence,
-                    confluenceScore: 0,
-                    conditions: [],
-                });
-                continue;
-            }
-            const evaluation = await def.evaluate(ctx);
-            const metCount = evaluation.conditions.filter((c) => c.met).length;
-            const confluenceScore = evaluation.conditions.length > 0
-                ? metCount / evaluation.conditions.length
-                : 0;
-            states.push({
-                strategy: config.name,
-                direction: evaluation.direction,
-                regimeGated: false,
-                regimeRequired: def.regimeWhitelist,
-                currentRegime: ctx.regime,
-                regimeConfidence: ctx.regimeConfidence,
-                confluenceScore,
-                conditions: evaluation.conditions,
-            });
-            // Confluence gate (engine.ts:339) + cooldown (engine.ts:342-346).
-            if (confluenceScore >= params.confluenceThreshold && evaluation.direction && evaluation.trade) {
-                const cooldownKey = `${config.name}:${ctx.symbol}:${evaluation.direction}`;
-                const lastFired = this.cooldowns.get(cooldownKey) ?? 0;
-                if (now - lastFired > params.cooldownMs) {
-                    this.cooldowns.set(cooldownKey, now);
-                    signals.push({
-                        signalId: `local-${ctx.symbol}-${config.name}-${now}`,
-                        timestamp: new Date(now).toISOString(),
-                        symbol: ctx.symbol,
-                        strategy: config.name,
-                        direction: evaluation.direction,
-                        regime: ctx.regime,
-                        regimeConfidence: ctx.regimeConfidence,
-                        confluenceScore,
-                        conditions: evaluation.conditions,
-                        entryZone: evaluation.trade.entryZone,
-                        stopLevel: evaluation.trade.stopLevel,
-                        targets: evaluation.trade.targets,
-                    });
-                }
-            }
-        }
-        return { states, signals };
-    }
-    /**
-     * Convenience wrapper that returns only the fired signals as LocalSignal[].
-     * Thin layer over evaluateSnapshot so there is a single source of evaluation
-     * logic.
-     */
-    async evaluate(ctx, strategies, now, params = DEFAULT_EVALUATOR_PARAMS) {
-        const { signals } = await this.evaluateSnapshot(ctx, strategies, now, params);
-        return signals.map((s) => ({
-            symbol: s.symbol,
-            strategy: s.strategy,
-            direction: s.direction,
-            regime: s.regime,
-            regimeConfidence: s.regimeConfidence,
-            confluenceScore: s.confluenceScore,
-            conditions: s.conditions,
-            entryZone: s.entryZone,
-            stopLevel: s.stopLevel,
-            targets: s.targets,
-            firedAt: now,
-        }));
-    }
-    /** Clear cooldown state (e.g. when the strategy set changes). */
-    reset() {
-        this.cooldowns.clear();
-    }
-}

package/assets/plugin/live/microstructure-assembler.d.ts

@@ -1,54 +0,0 @@
-import { type IntelApiDeps } from '../tools/intel-api.js';
-export interface MicrostructureBlock {
-    symbol: string;
-    /** Smoothed (not yet — placeholder for v2) band imbalance at ±0.5 %.
-     *  Computed as bid_usd / (bid_usd + ask_usd) ∈ [0, 1]. 0.5 = balanced;
-     *  > 0.5 leans bid (more support); < 0.5 leans ask (more resistance). */
-    restingBandImbalance05?: number;
-    /** Reserved for v2 — true when imbalance held its sign for ≥ 3 samples.
-     *  Always false until the EMA layer lands. */
-    persisted?: boolean;
-    /** Rolling-60 s cross-symbol cascade classification. */
-    cascadePulse60s?: 'quiet' | 'elevated' | 'active_cascade';
-    /** Coverage in basis-points-of-percent ×100 (e.g. 150 = 1.5 %).
-     *  The webapp persists `coveragePctAtReview` as percent units, so the
-     *  ingest layer divides this by 100. */
-    coverageBpc?: number;
-    /** Net dominant-side reading from the pulse stream. */
-    dominantSide?: 'long' | 'short' | 'balanced';
-    /** Epoch ms of the source intel reading. */
-    updatedAt?: number;
-}
-export interface MicrostructureAssembler {
-    /** Returns null when the heartbeatPush flag is off or both upstream calls
-     *  failed. Partial results (one endpoint succeeded) yield a partial block. */
-    forSymbol(symbol: string): Promise<MicrostructureBlock | null>;
-    /** Returns a Map<symbol, block> for a set of symbols. Null entries are
-     *  omitted from the map. */
-    forSymbols(symbols: string[]): Promise<Map<string, MicrostructureBlock>>;
-}
-/** No-op fallback used when no intel deps are wired. Kept for tests + as a
- *  safety net during the activation ladder. */
-export declare class StubMicrostructureAssembler implements MicrostructureAssembler {
-    forSymbol(_symbol: string): Promise<MicrostructureBlock | null>;
-    forSymbols(_symbols: string[]): Promise<Map<string, MicrostructureBlock>>;
-}
-export interface IntelMicrostructureAssemblerOptions {
-    intelDeps: IntelApiDeps;
-    /** Override the cache TTL — tests use 0 to disable. */
-    cacheTtlMs?: number;
-    /** Test seam — the heartbeatPush flag reader. Defaults to the live config. */
-    flagReader?: () => 'off' | 'on';
-    /** Test seam — Date.now(). */
-    now?: () => number;
-}
-export declare class IntelMicrostructureAssembler implements MicrostructureAssembler {
-    private readonly intelDeps;
-    private readonly cacheTtlMs;
-    private readonly flagReader;
-    private readonly now;
-    private readonly cache;
-    constructor(options: IntelMicrostructureAssemblerOptions);
-    forSymbol(symbol: string): Promise<MicrostructureBlock | null>;
-    forSymbols(symbols: string[]): Promise<Map<string, MicrostructureBlock>>;
-}

package/assets/plugin/live/microstructure-assembler.js

@@ -1,148 +0,0 @@
-// Microstructure heartbeat-push assembler.
-//
-// Builds a per-symbol microstructure context block (resting band imbalance,
-// cascade pulse, banded coverage) that the `record_position_reviews` tool
-// auto-attaches to each review row when `microstructure.heartbeatPush='on'`.
-// Without this, the agent must explicitly pass the orderbook fields (or the
-// review row's restingBandImbalance05 / cascadePulseAtReview / coveragePctAtReview
-// columns stay NULL).
-//
-// Sources both feeds from the intelligence VPS in parallel:
-//   - GET /api/resting-liquidity/<symbol>      → bands + coverage_pct
-//   - GET /api/liquidation-pulse?symbol=<sym>  → classification + dominant side
-//
-// Returns `null` for a symbol when:
-//   - the heartbeatPush flag is off (legacy behaviour)
-//   - intel responds with `enabled: false` on BOTH endpoints (no upstream data)
-//   - both fetches fail (network error / timeout)
-// A partial result (one endpoint succeeded) yields a partial block — fields
-// from the failed call stay `undefined` rather than dropping the whole entry.
-//
-// Caching: per-symbol 30 s TTL. Heartbeats fire ~30 min apart, so the cache
-// almost never serves a hit during normal operation; its purpose is to dedupe
-// within-heartbeat repeat calls (e.g. an operator triggering a manual review
-// while a scheduled heartbeat is mid-flight).
-//
-// See docs/MARKET_MICROSTRUCTURE_STREAMS.md (intel-side) and
-// docs/POSITION_DECISION_JOURNAL_PLAN.md §11 (PR1 deferral #3).
-import { logger, formatError } from '../logger.js';
-import { loadMicrostructureHeartbeatPush } from '../config/position-review-config.js';
-import { fetchIntelApi, enc } from '../tools/intel-api.js';
-const TAG = 'microstructure-assembler';
-const DEFAULT_CACHE_TTL_MS = 30_000;
-/** Per-symbol concurrency cap to keep heartbeat round-trips bounded even on
- *  many-symbol portfolios. 8 in-flight at once is well under the intel HTTP
- *  pool budget; remaining symbols queue. */
-const MAX_PARALLEL = 8;
-/** No-op fallback used when no intel deps are wired. Kept for tests + as a
- *  safety net during the activation ladder. */
-export class StubMicrostructureAssembler {
-    async forSymbol(_symbol) {
-        return null;
-    }
-    async forSymbols(_symbols) {
-        return new Map();
-    }
-}
-export class IntelMicrostructureAssembler {
-    intelDeps;
-    cacheTtlMs;
-    flagReader;
-    now;
-    cache = new Map();
-    constructor(options) {
-        this.intelDeps = options.intelDeps;
-        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
-        this.flagReader = options.flagReader ?? loadMicrostructureHeartbeatPush;
-        this.now = options.now ?? (() => Date.now());
-    }
-    async forSymbol(symbol) {
-        if (this.flagReader() === 'off')
-            return null;
-        const ts = this.now();
-        const canonical = canonicalSymbol(symbol);
-        const cached = this.cache.get(canonical);
-        if (cached && cached.expiresAt > ts)
-            return cached.block;
-        // Map canonical "BTC/USDT" → intel "BTCUSDT".
-        const intelSymbol = canonical.replace('/', '');
-        const [restingResult, pulseResult] = await Promise.allSettled([
-            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps),
-            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps),
-        ]);
-        const block = { symbol: canonical, updatedAt: ts };
-        let anySignal = false;
-        if (restingResult.status === 'fulfilled') {
-            const r = restingResult.value;
-            if (!isErr(r) && r.enabled === true) {
-                const bands = r.bands;
-                const band05 = bands?.['0.5'];
-                if (band05) {
-                    const total = (Number(band05.bid_usd) || 0) + (Number(band05.ask_usd) || 0);
-                    if (total > 0) {
-                        block.restingBandImbalance05 = (Number(band05.bid_usd) || 0) / total;
-                        anySignal = true;
-                    }
-                }
-                if (typeof r.coverage_pct === 'number' && Number.isFinite(r.coverage_pct)) {
-                    // Intel returns percent units (e.g. 1.5 for 1.5 %); we store as
-                    // basis-points-of-percent ×100 to preserve the assembler convention.
-                    block.coverageBpc = r.coverage_pct * 100;
-                    anySignal = true;
-                }
-            }
-        }
-        else {
-            logger.warn(TAG, `resting-liquidity fetch failed for ${canonical}: ${formatError(restingResult.reason)}`);
-        }
-        if (pulseResult.status === 'fulfilled') {
-            const p = pulseResult.value;
-            if (!isErr(p) && p.enabled === true) {
-                const cls = p.classification;
-                if (cls === 'quiet' || cls === 'elevated' || cls === 'active_cascade') {
-                    block.cascadePulse60s = cls;
-                    anySignal = true;
-                }
-                const dom = p.dominantSide;
-                if (dom === 'long' || dom === 'short' || dom === 'balanced') {
-                    block.dominantSide = dom;
-                    anySignal = true;
-                }
-            }
-        }
-        else {
-            logger.warn(TAG, `liquidation-pulse fetch failed for ${canonical}: ${formatError(pulseResult.reason)}`);
-        }
-        block.persisted = false;
-        if (!anySignal)
-            return null;
-        if (this.cacheTtlMs > 0) {
-            this.cache.set(canonical, { block, expiresAt: ts + this.cacheTtlMs });
-        }
-        return block;
-    }
-    async forSymbols(symbols) {
-        if (this.flagReader() === 'off' || symbols.length === 0) {
-            return new Map();
-        }
-        const out = new Map();
-        // Bounded parallelism — chunked Promise.all with cap MAX_PARALLEL.
-        for (let i = 0; i < symbols.length; i += MAX_PARALLEL) {
-            const chunk = symbols.slice(i, i + MAX_PARALLEL);
-            const results = await Promise.all(chunk.map((s) => this.forSymbol(s)));
-            for (let j = 0; j < chunk.length; j++) {
-                const block = results[j];
-                if (block)
-                    out.set(canonicalSymbol(chunk[j]), block);
-            }
-        }
-        return out;
-    }
-}
-function canonicalSymbol(s) {
-    // Strip the Binance settle suffix (`BTC/USDT:USDT` → `BTC/USDT`).
-    return s.replace(/:[A-Z]+$/, '');
-}
-function isErr(v) {
-    return typeof v.error === 'string';
-}

package/assets/plugin/live/order-poller.d.ts

@@ -1,29 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { CcxtOrder } from '../types.js';
-export interface OrderPollEvent {
-    orderId: string;
-    symbol: string;
-    type: 'filled' | 'partial_fill' | 'canceled' | 'expired';
-    order: CcxtOrder;
-    previousFilled?: number;
-}
-export declare class OrderPoller extends EventEmitter {
-    private polling;
-    private safetyTimeouts;
-    private adapter;
-    private pollIntervalMs;
-    private lastKnownFilled;
-    constructor(adapter: IExchangeAdapter, pollIntervalMs?: number);
-    /** Start polling for an order. */
-    startPolling(orderId: string, symbol: string): void;
-    /** Stop polling for an order. */
-    stopPolling(orderId: string): void;
-    /** Stop all polling. */
-    stopAll(): void;
-    /** Get all actively polled order IDs. */
-    getPollingOrders(): string[];
-    /** Number of orders being polled. */
-    get activeCount(): number;
-    private processOrderUpdate;
-}

package/assets/plugin/live/order-poller.js

@@ -1,125 +0,0 @@
-// Order poller — polls exchange for order status on live limit orders.
-// Detects fills, partial fills, and cancellations.
-import { EventEmitter } from 'node:events';
-import { logger, formatError } from '../logger.js';
-const TAG = 'order-poller';
-const DEFAULT_POLL_INTERVAL_MS = 5_000; // 5 seconds
-const MAX_POLL_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours safety timeout
-export class OrderPoller extends EventEmitter {
-    polling = new Map();
-    safetyTimeouts = new Map();
-    adapter;
-    pollIntervalMs;
-    // Track previous fill amounts for partial fill detection
-    lastKnownFilled = new Map();
-    constructor(adapter, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS) {
-        super();
-        this.adapter = adapter;
-        this.pollIntervalMs = pollIntervalMs;
-    }
-    /** Start polling for an order. */
-    startPolling(orderId, symbol) {
-        if (this.polling.has(orderId)) {
-            logger.warn(TAG, `Already polling order ${orderId}`);
-            return;
-        }
-        logger.info(TAG, `Start polling order ${orderId} (${symbol})`);
-        this.lastKnownFilled.set(orderId, 0);
-        const interval = setInterval(async () => {
-            try {
-                const order = await this.adapter.fetchOrder(orderId, symbol);
-                if (!order)
-                    return; // API error — skip this cycle
-                this.processOrderUpdate(orderId, order);
-            }
-            catch (err) {
-                logger.warn(TAG, `Poll error for ${orderId}: ${formatError(err)}`);
-            }
-        }, this.pollIntervalMs);
-        this.polling.set(orderId, interval);
-        // Safety timeout: stop polling after 24h
-        const safetyTimeout = setTimeout(() => {
-            logger.warn(TAG, `Safety timeout reached for order ${orderId} — stopping poll`);
-            this.stopPolling(orderId);
-        }, MAX_POLL_DURATION_MS);
-        this.safetyTimeouts.set(orderId, safetyTimeout);
-    }
-    /** Stop polling for an order. */
-    stopPolling(orderId) {
-        const interval = this.polling.get(orderId);
-        if (interval) {
-            clearInterval(interval);
-            this.polling.delete(orderId);
-        }
-        const timeout = this.safetyTimeouts.get(orderId);
-        if (timeout) {
-            clearTimeout(timeout);
-            this.safetyTimeouts.delete(orderId);
-        }
-        this.lastKnownFilled.delete(orderId);
-    }
-    /** Stop all polling. */
-    stopAll() {
-        for (const orderId of this.polling.keys()) {
-            this.stopPolling(orderId);
-        }
-    }
-    /** Get all actively polled order IDs. */
-    getPollingOrders() {
-        return Array.from(this.polling.keys());
-    }
-    /** Number of orders being polled. */
-    get activeCount() {
-        return this.polling.size;
-    }
-    // ---- Internal ----
-    processOrderUpdate(orderId, order) {
-        const previousFilled = this.lastKnownFilled.get(orderId) ?? 0;
-        // CCXT's runtime status set is wider than CcxtOrder's compile-time union:
-        // Binance EXPIRED / EXPIRED_IN_MATCH surface as 'expired' (and 'rejected'
-        // exists on other venues). Compare on the runtime string so an unmodelled
-        // terminal status can never leave the poller running for the full 24h
-        // safety timeout with no terminal event ever emitted.
-        const status = String(order.status);
-        if (status === 'closed') {
-            // Fully filled
-            this.emit('order_event', {
-                orderId,
-                symbol: order.symbol,
-                type: 'filled',
-                order,
-                previousFilled,
-            });
-            this.stopPolling(orderId);
-            logger.info(TAG, `Order ${orderId} FILLED: ${order.filled} @ ${order.average}`);
-        }
-        else if (status !== 'open') {
-            // canceled / expired / rejected / any future non-open status — the
-            // order can never fill further; emit the matching terminal event and
-            // stop. Only a literal 'open' keeps the poll alive.
-            const type = status === 'expired' ? 'expired' : 'canceled';
-            this.emit('order_event', {
-                orderId,
-                symbol: order.symbol,
-                type,
-                order,
-                previousFilled,
-            });
-            this.stopPolling(orderId);
-            logger.info(TAG, `Order ${orderId} ${status.toUpperCase()} (filled: ${order.filled})`);
-        }
-        else if (order.filled > previousFilled) {
-            // Partial fill — still open but more filled
-            this.lastKnownFilled.set(orderId, order.filled);
-            this.emit('order_event', {
-                orderId,
-                symbol: order.symbol,
-                type: 'partial_fill',
-                order,
-                previousFilled,
-            });
-            logger.info(TAG, `Order ${orderId} PARTIAL FILL: ${previousFilled} → ${order.filled}`);
-        }
-        // else: no change, keep polling
-    }
-}

package/assets/plugin/live/position-state-store.d.ts

@@ -1,83 +0,0 @@
-export interface PositionStateEntry {
-    /** Canonical symbol form (no settle suffix). */
-    symbol: string;
-    /** Authoritative position-open timestamp (epoch ms). Used as the webapp's
-     *  natural-key column alongside (userId, symbol). */
-    openedAt: number;
-    side: 'long' | 'short';
-    /** UUID returned from POST /api/internal/positions. May be undefined briefly
-     *  between local detection and the first successful upsert. */
-    webappPositionId?: string;
-    /** exchangeTradeId of the opening fill (audit trail). */
-    openedFromExchangeTradeId?: string;
-    /** Last record_position_reviews call timestamp (epoch ms). Drives stale-gate. */
-    lastReviewAt?: number;
-    lastVerdict?: 'hold' | 'add_on' | 'close_recommended';
-    /** Last thesis_status from the most recent review. Drives the exit-gate's
-     *  review-override check (see docs/EXIT_GATE_DESIGN.md §3). */
-    lastThesisStatus?: 'intact' | 'weakening' | 'invalidated' | 'evolving';
-    /** Remaining open contracts, tracked from opening fills (+) and reduce-only
-     *  exit fills (−). Lets the auto-capture pipeline detect when a position goes
-     *  flat via a bracket SL/TP or other reduce-only fill — the close-bypass path
-     *  that otherwise never reaches close_position — and journal an exact close.
-     *  Optional: entries opened before this field existed (or before a restart)
-     *  are seeded from exchange truth at boot (seedRemainingContracts). When
-     *  undefined we can't decide flatness from fills alone and defer to the
-     *  reconciler/ALGO close-bypass backstop. */
-    remainingContracts?: number;
-    /** Cumulative Binance-exact realised PnL summed across the reduce-only exit
-     *  fills since open, so the auto-journaled close carries the real PnL rather
-     *  than a server-side estimate. */
-    realizedPnlAccum?: number;
-    createdAt: number;
-    updatedAt: number;
-}
-/** Test seam — lets tests override the clock for deterministic timestamps. */
-export type NowFn = () => number;
-export declare class PositionStateStore {
-    private readonly filePath;
-    private readonly dir;
-    private readonly now;
-    private entries;
-    constructor(pluginId?: string, opts?: {
-        now?: NowFn;
-        basePath?: string;
-    });
-    /** Insert or update a position. Caller is responsible for deciding when
-     *  to call this — typically on first observation of a new position. */
-    upsert(entry: Omit<PositionStateEntry, 'createdAt' | 'updatedAt'> & {
-        createdAt?: number;
-        updatedAt?: number;
-    }): PositionStateEntry;
-    /** Set the webapp positionId after the upsert returns. Idempotent. */
-    setWebappId(symbol: string, webappPositionId: string): void;
-    /** Update review tracking after a successful record_position_reviews call.
-     *  thesisStatus is optional for backwards compatibility — older callers that
-     *  predate the exit-gate work pass only verdict; the gate falls back to
-     *  PASS('inputs_unavailable_thesis_status') when the field isn't cached. */
-    recordReview(symbol: string, verdict: 'hold' | 'add_on' | 'close_recommended', reviewAt?: number, thesisStatus?: 'intact' | 'weakening' | 'invalidated' | 'evolving'): void;
-    /** Add opening contracts to the running size (first opening fill or a
-     *  scale-in). Initialises the realised-PnL accumulator on first open. No-op
-     *  if the entry doesn't exist yet (caller upserts the entry first). */
-    addOpenContracts(symbol: string, qty: number): void;
-    /** Seed remaining contracts from exchange truth at startup. Only sets when
-     *  the size is currently unknown — never clobbers live fill-tracked state. */
-    seedRemainingContracts(symbol: string, qty: number): void;
-    /** Apply a reduce-only exit fill: decrement remaining contracts and sum the
-     *  fill's realised PnL. Returns the updated entry so the caller can journal a
-     *  close when the position is flat, or null when there's no tracked entry or
-     *  the size is unknown (can't decide flatness — defer to the backstop). */
-    applyExitContracts(symbol: string, qty: number, realizedPnl: number): PositionStateEntry | null;
-    get(symbol: string): PositionStateEntry | undefined;
-    /** Returns all entries — used by the stale-gate to enumerate open positions. */
-    getAll(): PositionStateEntry[];
-    /** Drop an entry — called when the auto-capture pipeline observes the
-     *  position has closed (size dropped to zero on the exchange). */
-    remove(symbol: string): boolean;
-    size(): number;
-    getFilePath(): string;
-    private loadOrInit;
-    private persist;
-    private validateFile;
-    private validateEntry;
-}