@reefclaw/connect 0.1.12 → 0.1.14

package/assets/plugin/persistence/state-manager.d.ts

@@ -0,0 +1,66 @@
+import type { SimulatorState } from '../simulator/types.js';
+export declare class StateManager {
+    private readonly statePath;
+    private saveTimer;
+    private pendingState;
+    constructor(pluginId: string, baseDir?: string);
+    getStatePath(): string;
+    /** Quarantine a state file that exists but won't parse, instead of letting
+     *  the caller silently overwrite it with a fresh default (which would wipe
+     *  the positions/orders/realized-PnL ledger). The corrupt bytes are renamed
+     *  to `<state>.corrupt-<ts>` so an operator can recover them. Returns true if
+     *  a corrupt file was quarantined. */
+    private quarantineCorruptSync;
+    /** Load state from disk. Returns null when the file is MISSING (fresh start)
+     *  OR when it exists-but-is-unreadable (in which case the corrupt bytes are
+     *  quarantined first — never silently discarded). The two cases are
+     *  distinguished in the log; both yield null so the caller seeds a default,
+     *  but a corrupt file is preserved as `<state>.corrupt-<ts>`. */
+    load(): Promise<SimulatorState | null>;
+    /** Save state atomically (write to a UNIQUE temp, rename to final). A unique
+     *  temp name (pid + uuid) is essential under the two-process model: both the
+     *  agent and gateway processes wire stateChanged→save, and a shared
+     *  `<state>.tmp` let their concurrent writes interleave into a torn file that
+     *  then parses as garbage on next boot. With a per-write temp, the worst case
+     *  degrades to a harmless last-writer-wins rename of two COMPLETE files. */
+    save(state: SimulatorState): Promise<void>;
+    /**
+     * Debounced save — coalesces rapid mutations into one write per second.
+     * Call this on every state change; it will save at most once per second.
+     */
+    debouncedSave(state: SimulatorState): void;
+    /** Flush any pending debounced save immediately. */
+    flush(): Promise<void>;
+    /** Load state or create default if not found. */
+    loadOrDefault(startingBalance: number, quoteCurrency: string): Promise<SimulatorState>;
+    /** Synchronous load — for use in synchronous plugin register(). Same
+     *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
+     *  (preserved), never silently overwritten by the default the caller seeds. */
+    loadSync(): SimulatorState | null;
+    /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
+    loadOrDefaultSync(startingBalance: number, quoteCurrency: string): SimulatorState;
+    private saveSyncSafe;
+}
+export interface PaperQuoteMigrationResult {
+    state: SimulatorState;
+    migrated: boolean;
+    fromQuote: string;
+    releasedPositions: number;
+    droppedOrders: number;
+}
+/** Migrate a persisted paper state whose quote currency no longer matches the
+ *  configured venue's (issue #174 — e.g. a USDT wallet after switching to the
+ *  USDC-quoted hyperliquid venue). Pure; returns the input untouched when the
+ *  quotes already match.
+ *
+ *  Semantics (equity-preserving):
+ *  - Open positions are released at their entry price: opening deducted the
+ *    full entry notional from the wallet (spot-collateral model), so that
+ *    notional is credited back before the position rows — which reference the
+ *    OLD venue's symbols and are unpriceable on the new one — are dropped.
+ *  - Unfilled open orders never debited the wallet (fills do) — just dropped.
+ *  - Balances carry 1:1 (USDT↔USDC are both dollar stables; paper precision),
+ *    merging into any existing balance under the new quote.
+ *  - Trade history is kept (display-only). savedAt is bumped so the other
+ *    process's replaceState() staleness guard accepts the migrated snapshot. */
+export declare function migratePaperQuoteCurrency(state: SimulatorState, expectedQuote: string): PaperQuoteMigrationResult;

package/assets/plugin/persistence/state-manager.js

@@ -0,0 +1,222 @@
+// State persistence manager for the paper trading simulator.
+// Saves/loads state to ~/.openclaw/plugins/reefclaw-paper-trading/state.json
+// Uses atomic writes (temp file + rename) to prevent corruption.
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../logger.js';
+import { createDefaultState } from '../simulator/types.js';
+const TAG = 'state-manager';
+export class StateManager {
+    statePath;
+    saveTimer = null;
+    pendingState = null;
+    constructor(pluginId, baseDir) {
+        const base = baseDir ?? join(homedir(), '.openclaw', 'plugins', pluginId);
+        this.statePath = join(base, 'state.json');
+    }
+    getStatePath() {
+        return this.statePath;
+    }
+    /** Quarantine a state file that exists but won't parse, instead of letting
+     *  the caller silently overwrite it with a fresh default (which would wipe
+     *  the positions/orders/realized-PnL ledger). The corrupt bytes are renamed
+     *  to `<state>.corrupt-<ts>` so an operator can recover them. Returns true if
+     *  a corrupt file was quarantined. */
+    quarantineCorruptSync() {
+        if (!existsSync(this.statePath))
+            return false;
+        const dest = `${this.statePath}.corrupt-${Date.now()}`;
+        try {
+            renameSync(this.statePath, dest);
+            logger.error(TAG, `State file at ${this.statePath} is unreadable/corrupt — quarantined to ${dest}. NOT resetting silently; a fresh default will be used. Investigate before trading.`);
+        }
+        catch (err) {
+            logger.error(TAG, `State file at ${this.statePath} is corrupt AND could not be quarantined: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return true;
+    }
+    /** Load state from disk. Returns null when the file is MISSING (fresh start)
+     *  OR when it exists-but-is-unreadable (in which case the corrupt bytes are
+     *  quarantined first — never silently discarded). The two cases are
+     *  distinguished in the log; both yield null so the caller seeds a default,
+     *  but a corrupt file is preserved as `<state>.corrupt-<ts>`. */
+    async load() {
+        if (!existsSync(this.statePath)) {
+            logger.info(TAG, `No state file found at ${this.statePath}`);
+            return null;
+        }
+        try {
+            const raw = await readFile(this.statePath, 'utf-8');
+            const state = JSON.parse(raw);
+            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
+            return state;
+        }
+        catch {
+            // Exists but unreadable/corrupt — preserve, don't silently reset.
+            this.quarantineCorruptSync();
+            return null;
+        }
+    }
+    /** Save state atomically (write to a UNIQUE temp, rename to final). A unique
+     *  temp name (pid + uuid) is essential under the two-process model: both the
+     *  agent and gateway processes wire stateChanged→save, and a shared
+     *  `<state>.tmp` let their concurrent writes interleave into a torn file that
+     *  then parses as garbage on next boot. With a per-write temp, the worst case
+     *  degrades to a harmless last-writer-wins rename of two COMPLETE files. */
+    async save(state) {
+        const tmpPath = `${this.statePath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            const dir = dirname(this.statePath);
+            if (!existsSync(dir)) {
+                await mkdir(dir, { recursive: true });
+            }
+            await writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+            await rename(tmpPath, this.statePath);
+            logger.debug(TAG, 'State saved');
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to save state: ${err instanceof Error ? err.message : String(err)}`);
+            // Best-effort cleanup of the orphaned temp so they don't accumulate.
+            await unlink(tmpPath).catch(() => { });
+        }
+    }
+    /**
+     * Debounced save — coalesces rapid mutations into one write per second.
+     * Call this on every state change; it will save at most once per second.
+     */
+    debouncedSave(state) {
+        this.pendingState = state;
+        if (this.saveTimer)
+            return; // Already scheduled
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            if (this.pendingState) {
+                const s = this.pendingState;
+                this.pendingState = null;
+                this.save(s).catch(() => { });
+            }
+        }, 1000);
+    }
+    /** Flush any pending debounced save immediately. */
+    async flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.pendingState) {
+            const s = this.pendingState;
+            this.pendingState = null;
+            await this.save(s);
+        }
+    }
+    /** Load state or create default if not found. */
+    async loadOrDefault(startingBalance, quoteCurrency) {
+        const loaded = await this.load();
+        if (loaded)
+            return loaded;
+        const state = createDefaultState(startingBalance, quoteCurrency);
+        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
+        await this.save(state);
+        return state;
+    }
+    /** Synchronous load — for use in synchronous plugin register(). Same
+     *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
+     *  (preserved), never silently overwritten by the default the caller seeds. */
+    loadSync() {
+        if (!existsSync(this.statePath)) {
+            logger.info(TAG, `No state file found at ${this.statePath}`);
+            return null;
+        }
+        try {
+            const raw = readFileSync(this.statePath, 'utf-8');
+            const state = JSON.parse(raw);
+            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
+            return state;
+        }
+        catch {
+            this.quarantineCorruptSync();
+            return null;
+        }
+    }
+    /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
+    loadOrDefaultSync(startingBalance, quoteCurrency) {
+        const loaded = this.loadSync();
+        if (loaded) {
+            // Venue switch heal (issue #174): a persisted wallet quoted in the OLD
+            // venue's currency reads as $0 equity on the new venue. Migrate 1:1
+            // (USDT↔USDC), preserving total equity exactly.
+            const mig = migratePaperQuoteCurrency(loaded, quoteCurrency);
+            if (mig.migrated) {
+                logger.info(TAG, `Paper wallet quote migrated ${mig.fromQuote} → ${quoteCurrency} (venue switch): ` +
+                    `released ${mig.releasedPositions} open position(s) at entry price, ` +
+                    `dropped ${mig.droppedOrders} unfilled order(s), balances carried 1:1`);
+                this.saveSyncSafe(mig.state, 'migrated');
+            }
+            return mig.state;
+        }
+        const state = createDefaultState(startingBalance, quoteCurrency);
+        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
+        // Save synchronously so state persists immediately
+        this.saveSyncSafe(state, 'initial');
+        return state;
+    }
+    saveSyncSafe(state, label) {
+        try {
+            const dir = dirname(this.statePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to save ${label} state: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/** Migrate a persisted paper state whose quote currency no longer matches the
+ *  configured venue's (issue #174 — e.g. a USDT wallet after switching to the
+ *  USDC-quoted hyperliquid venue). Pure; returns the input untouched when the
+ *  quotes already match.
+ *
+ *  Semantics (equity-preserving):
+ *  - Open positions are released at their entry price: opening deducted the
+ *    full entry notional from the wallet (spot-collateral model), so that
+ *    notional is credited back before the position rows — which reference the
+ *    OLD venue's symbols and are unpriceable on the new one — are dropped.
+ *  - Unfilled open orders never debited the wallet (fills do) — just dropped.
+ *  - Balances carry 1:1 (USDT↔USDC are both dollar stables; paper precision),
+ *    merging into any existing balance under the new quote.
+ *  - Trade history is kept (display-only). savedAt is bumped so the other
+ *    process's replaceState() staleness guard accepts the migrated snapshot. */
+export function migratePaperQuoteCurrency(state, expectedQuote) {
+    const fromQuote = state.config?.quoteCurrency ?? 'USDT';
+    if (fromQuote === expectedQuote) {
+        return { state, migrated: false, fromQuote, releasedPositions: 0, droppedOrders: 0 };
+    }
+    const next = JSON.parse(JSON.stringify(state));
+    next.config = { ...next.config, quoteCurrency: expectedQuote };
+    const old = next.wallet[fromQuote] ?? { total: 0, available: 0, locked: 0 };
+    let releasedPositions = 0;
+    for (const pos of next.positions ?? []) {
+        const notional = pos.entryPrice * pos.quantity;
+        if (Number.isFinite(notional) && notional > 0) {
+            old.total += notional;
+            old.available += notional;
+        }
+        releasedPositions++;
+    }
+    const droppedOrders = (next.openOrders ?? []).length;
+    next.positions = [];
+    next.openOrders = [];
+    const target = next.wallet[expectedQuote] ?? { total: 0, available: 0, locked: 0 };
+    target.total += old.total;
+    target.available += old.available;
+    target.locked += old.locked;
+    next.wallet[expectedQuote] = target;
+    delete next.wallet[fromQuote];
+    next.savedAt = Date.now();
+    return { state: next, migrated: true, fromQuote, releasedPositions, droppedOrders };
+}

package/assets/plugin/pinned-plan.d.ts

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

package/assets/plugin/pinned-plan.js

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

package/assets/plugin/portfolio/reentry-tracker.d.ts

@@ -0,0 +1,36 @@
+export interface ReentryExitRecord {
+    /** Canonical symbol (no settle suffix). */
+    symbol: string;
+    /** setup_type / strategy name from the entry metadata, when known. */
+    setupType?: string;
+    side: 'long' | 'short';
+    /** Whether the closed trade realized a loss (drives the stronger caution). */
+    wasLoss?: boolean;
+    closedAtMs: number;
+}
+/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
+ *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
+ *  shapes default to 60min so short-TF strategies are never over-warned. */
+export declare function strategyBarMinutes(name: string | undefined): number;
+export declare class ReentryTracker {
+    private records;
+    private readonly filePath;
+    private readonly dir;
+    constructor(pluginId?: string, opts?: {
+        basePath?: string;
+    });
+    /** Record a position exit. Never throws (best-effort persistence). */
+    recordExit(record: Omit<ReentryExitRecord, 'symbol'> & {
+        symbol: string;
+    }): void;
+    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
+     *  a symbol-only match so multi-strategy books get precise cautions. */
+    lastExit(symbol: string, setupType?: string): ReentryExitRecord | undefined;
+    /** Structured caution when (symbol, strategy) was already traded within the
+     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
+     *  the agent decides; nothing here blocks an order. */
+    cautionFor(symbol: string, strategy: string | undefined, nowMs?: number): string | undefined;
+    /** Test seam. */
+    getRecords(): readonly ReentryExitRecord[];
+    private persist;
+}

package/assets/plugin/portfolio/reentry-tracker.js

@@ -0,0 +1,127 @@
+// Re-entry tracker — records recent position exits per (symbol, setup) so the
+// entry funnel (scan_pairs / get_signals) can flag setups the agent already
+// traded within the current signal bar (issue #204).
+//
+// WHY: the validated backtests for the 4h/1d templates have one-trade-per-
+// signal semantics — a signal bar produces at most one trade. Live, the 4h
+// condition stays true for hours, so after every exit the next heartbeat
+// re-entered the same setup: measured 19× the backtest cadence with 79-minute
+// median holds, including 22 same-direction re-entries within one bar of a
+// LOSING close (2026-07-14 → 07-20 HL soak). Per the tools-not-mandates
+// doctrine this ships as STRUCTURED INDICATION — the annotation tells the
+// agent the setup was already traded this bar; it never blocks the order.
+//
+// Persistence: small JSON in the plugins base dir (same pattern as
+// position-state-store) so restarts don't blind the indication. Best-effort —
+// a persistence failure degrades to in-memory-only, never throws into the
+// trading path.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'reentry-tracker';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const STATE_FILENAME = 'reentry-log.json';
+const MAX_RECORDS = 300;
+/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
+ *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
+ *  shapes default to 60min so short-TF strategies are never over-warned. */
+export function strategyBarMinutes(name) {
+    if (!name)
+        return 60;
+    const lower = name.toLowerCase();
+    const hourMatch = lower.match(/_(\d{1,2})h\b|_(\d{1,2})h_|_(\d{1,2})h$/);
+    if (hourMatch) {
+        const h = Number(hourMatch[1] ?? hourMatch[2] ?? hourMatch[3]);
+        if (Number.isFinite(h) && h > 0)
+            return h * 60;
+    }
+    if (/_1d\b|_1d_|_1d$|daily/.test(lower))
+        return 1440;
+    return 60;
+}
+export class ReentryTracker {
+    records = [];
+    filePath;
+    dir;
+    constructor(pluginId, opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        this.dir = join(base, pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, STATE_FILENAME);
+        try {
+            if (!existsSync(this.dir))
+                mkdirSync(this.dir, { recursive: true });
+            if (existsSync(this.filePath)) {
+                const parsed = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+                if (Array.isArray(parsed?.records)) {
+                    this.records = parsed.records.filter((r) => typeof r?.symbol === 'string' && Number.isFinite(r?.closedAtMs));
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `load failed (${formatError(err)}) — starting empty`);
+            this.records = [];
+        }
+    }
+    /** Record a position exit. Never throws (best-effort persistence). */
+    recordExit(record) {
+        try {
+            this.records.push({ ...record, symbol: normalizeBracketSymbol(record.symbol) });
+            if (this.records.length > MAX_RECORDS) {
+                this.records = this.records.slice(-MAX_RECORDS);
+            }
+            this.persist();
+        }
+        catch (err) {
+            logger.warn(TAG, `recordExit failed: ${formatError(err)}`);
+        }
+    }
+    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
+     *  a symbol-only match so multi-strategy books get precise cautions. */
+    lastExit(symbol, setupType) {
+        const key = normalizeBracketSymbol(symbol);
+        let bySetup;
+        let bySymbol;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.symbol !== key)
+                continue;
+            if (!bySymbol)
+                bySymbol = r;
+            if (setupType && r.setupType === setupType) {
+                bySetup = r;
+                break;
+            }
+            if (!setupType)
+                break;
+        }
+        return bySetup ?? bySymbol;
+    }
+    /** Structured caution when (symbol, strategy) was already traded within the
+     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
+     *  the agent decides; nothing here blocks an order. */
+    cautionFor(symbol, strategy, nowMs = Date.now()) {
+        const last = this.lastExit(symbol, strategy);
+        if (!last)
+            return undefined;
+        const barMin = strategyBarMinutes(strategy ?? last.setupType);
+        const agoMin = Math.round((nowMs - last.closedAtMs) / 60_000);
+        if (agoMin < 0 || agoMin > barMin)
+            return undefined;
+        const lossNote = last.wasLoss ? ' at a LOSS' : '';
+        return (`already traded this signal bar: exited a ${last.side} on this setup ${agoMin}m ago${lossNote} ` +
+            `(bar=${barMin}m). The validated backtest takes ONE trade per signal bar — re-enter only if ` +
+            `you can name what NEW information arrived since that exit.`);
+    }
+    /** Test seam. */
+    getRecords() {
+        return this.records;
+    }
+    persist() {
+        const payload = { schemaVersion: 1, records: this.records };
+        const tmp = `${this.filePath}.tmp`;
+        writeFileSync(tmp, JSON.stringify(payload), 'utf-8');
+        renameSync(tmp, this.filePath);
+    }
+}

package/assets/plugin/portfolio/wave9-admission.d.ts

@@ -0,0 +1,67 @@
+import type { Direction } from '../signals/types.js';
+import { type Wave9StrategyName } from './wave9-policy.js';
+export interface Wave9AdmissionPolicy {
+    riskPct: number;
+    maxPositions: number;
+    maxOpenRiskPct: number;
+    maxGrossExposureMultiple: number;
+    maxPositionUsd: number;
+    feeBps: number;
+    slippageBps: number;
+    capEnforcement: 'admission_only_no_forced_deleveraging';
+    riskMeasure: 'fixed_initial_stop_risk_usd';
+}
+export declare const WAVE9_ADMISSION_POLICY: Readonly<Wave9AdmissionPolicy>;
+export interface Wave9AdmissionPosition {
+    candidateId: string;
+    symbol: string;
+    strategy: Wave9StrategyName;
+    direction: Direction;
+    entryPrice: number;
+    quantity: number;
+    markPrice: number;
+    initialStop: number;
+    dollarRiskUsd: number;
+    accruedFundingUsd: number;
+}
+export interface Wave9AdmissionState {
+    cashEquityUsd: number;
+    positions: Wave9AdmissionPosition[];
+}
+export interface Wave9AdmissionCandidate {
+    id: string;
+    eventTime: string;
+    symbol: string;
+    strategy: Wave9StrategyName;
+    direction: Direction;
+    referencePrice: number;
+    stopPrice: number;
+}
+export type Wave9AdmissionReason = 'accepted' | 'invalidGeometry' | 'symbolAlreadyOpen' | 'maxPositions' | 'maxGrossExposure' | 'maxOpenRisk' | 'invalidSizing';
+export interface Wave9AdmissionLedgerRow extends Wave9AdmissionPosition {
+    estimatedExitCostUsd: number;
+}
+export interface Wave9AdmissionDecision extends Wave9AdmissionCandidate {
+    accepted: boolean;
+    reason: Wave9AdmissionReason;
+    entryPrice?: number;
+    quantity?: number;
+    notionalUsd?: number;
+    riskUsd?: number;
+    projectedCashEquityUsd?: number;
+    projectedLiquidationEquityUsd?: number;
+    projectedGrossExposureUsd?: number;
+    projectedOpenRiskUsd?: number;
+    projectedOpenPositions?: number;
+    projectedPositionLedger?: Wave9AdmissionLedgerRow[];
+}
+export interface Wave9AdmissionBatchResult {
+    decisions: Wave9AdmissionDecision[];
+    state: Wave9AdmissionState;
+}
+/**
+ * Apply a same-event candidate batch in the exact frozen priority. The caller
+ * must release stops and completed-daily reversals before invoking this
+ * function, just as the chronological research engine does.
+ */
+export declare function applyWave9AdmissionBatch(inputState: Wave9AdmissionState, rawCandidates: readonly Wave9AdmissionCandidate[], policy?: Readonly<Wave9AdmissionPolicy>): Wave9AdmissionBatchResult;