@reefclaw/openclaw-plugin 0.1.0

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

@@ -0,0 +1,62 @@
+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/live/local-strategy-evaluator.js

@@ -0,0 +1,127 @@
+// 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 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/live/microstructure-assembler.d.ts

@@ -0,0 +1,54 @@
+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/live/microstructure-assembler.js

@@ -0,0 +1,148 @@
+// 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/live/order-poller.d.ts

@@ -0,0 +1,29 @@
+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/live/order-poller.js

@@ -0,0 +1,125 @@
+// 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/live/position-state-store.d.ts

@@ -0,0 +1,83 @@
+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;
+}