@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/ingest/pending-entry-metadata.d.ts

@@ -1,74 +0,0 @@
-import type { PositionMetadata } from '../simulator/types.js';
-export interface PendingEntry {
-    /** Primary lookup key. Initially the client order id (the stash happens
-     *  BEFORE submission, when no exchange orderId exists yet); promote()
-     *  re-keys it to the exchange-issued orderId once the REST ack returns. */
-    orderId: string;
-    /** Client order id (idempotency key) — secondary lookup key. The WS
-     *  ORDER_TRADE_UPDATE carries it (`o.c`), so a fill that arrives BEFORE
-     *  the REST response (routine for market orders) still finds the stash. */
-    clientOrderId?: string;
-    /** Canonical (un-suffixed) symbol. */
-    symbol: string;
-    /** Side the agent intended at create_order time. */
-    side: 'buy' | 'sell';
-    metadata: PositionMetadata;
-    createdAt: number;
-    /** Epoch ms after which this entry is dropped. */
-    expiresAt: number;
-}
-export type NowFn = () => number;
-export interface PendingEntryStoreOptions {
-    pluginId?: string;
-    basePath?: string;
-    now?: NowFn;
-    ttlMs?: number;
-}
-export declare class PendingEntryStore {
-    private readonly filePath;
-    private readonly dir;
-    private readonly now;
-    private readonly ttlMs;
-    private entries;
-    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
-     *  REST ack (no exchange orderId known yet) find the stash by cid. */
-    private cidIndex;
-    constructor(opts?: PendingEntryStoreOptions);
-    /** Stash metadata until the WS fill for this order arrives. Keyed by
-     *  `orderId`; when `clientOrderId` is provided the entry is also findable
-     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
-    put(input: {
-        orderId: string;
-        clientOrderId?: string;
-        symbol: string;
-        side: 'buy' | 'sell';
-        metadata: PositionMetadata;
-    }): void;
-    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
-     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
-     *  working. No-op when the entry is gone (already consumed by a WS fill
-     *  that beat the REST response, or expired). */
-    promote(fromKey: string, exchangeOrderId: string): void;
-    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
-     *  Does NOT remove the entry — callers should call `consume(orderId)` to
-     *  remove on first match, since multiple partial fills on the same limit
-     *  order all share one orderId and the FIRST fill is the entry; subsequent
-     *  are scale-ins of an already-registered position (state-store branch
-     *  handles those). */
-    get(orderId: string): PendingEntry | undefined;
-    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
-     *  you've already consumed the metadata to post an entry row and don't
-     *  want it picked up again. */
-    consume(orderId: string): PendingEntry | undefined;
-    /** Remove an entry without retrieval (e.g. on cancel). */
-    drop(orderId: string): boolean;
-    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
-    private resolveKey;
-    private deleteEntry;
-    size(): number;
-    getFilePath(): string;
-    private pruneExpired;
-    private loadOrInit;
-    private persist;
-    private validateFile;
-}

package/assets/plugin/ingest/pending-entry-metadata.js

@@ -1,236 +0,0 @@
-// Pending-entry metadata cache.
-//
-// When the agent calls create_order with v2.10.0 metadata (thesis, setup_type,
-// regime, scorecard_verdict, confluence_score, etc.) for a LIMIT order that
-// doesn't fill immediately, the metadata is stashed here keyed by the
-// exchange's orderId. When the WS-driven fill arrives later (could be seconds
-// or hours), `onWsFillObserved` looks up the metadata and posts the entry /
-// scale-in decision row with the original rationale intact.
-//
-// Without this cache, limit-order entries land in `position_entries` with
-// thesis='(no thesis recorded)' / setupType='unknown' — useless for Phase 2
-// outcome attribution and Phase 3 mining.
-//
-// Persistence: same atomic-rename pattern as bracket-ledger / position-state-
-// store. File at ~/.openclaw/plugins/<pluginId>/pending-entry-metadata.json.
-//
-// TTL: entries auto-expire 24 hours after creation (limit orders rarely live
-// longer; expired entries are pruned on every load + every write to keep the
-// file bounded).
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
-import { logger, formatError } from '../logger.js';
-const TAG = 'pending-entry-metadata';
-const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
-const STATE_FILENAME = 'pending-entry-metadata.json';
-const SCHEMA_VERSION = 1;
-const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
-const defaultNow = () => Date.now();
-export class PendingEntryStore {
-    filePath;
-    dir;
-    now;
-    ttlMs;
-    entries = new Map();
-    /** clientOrderId → primary key in `entries`. Lets WS fills that beat the
-     *  REST ack (no exchange orderId known yet) find the stash by cid. */
-    cidIndex = new Map();
-    constructor(opts) {
-        const base = resolvePluginsBaseDir(opts?.basePath);
-        this.dir = join(base, opts?.pluginId ?? DEFAULT_PLUGIN_ID);
-        this.filePath = join(this.dir, STATE_FILENAME);
-        this.now = opts?.now ?? defaultNow;
-        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-        if (!existsSync(this.dir))
-            mkdirSync(this.dir, { recursive: true });
-        this.loadOrInit();
-    }
-    /** Stash metadata until the WS fill for this order arrives. Keyed by
-     *  `orderId`; when `clientOrderId` is provided the entry is also findable
-     *  by it (pre-submission stashes pass the cid as BOTH — see create_order). */
-    put(input) {
-        const ts = this.now();
-        this.entries.set(input.orderId, {
-            orderId: input.orderId,
-            ...(input.clientOrderId ? { clientOrderId: input.clientOrderId } : {}),
-            symbol: input.symbol,
-            side: input.side,
-            metadata: input.metadata,
-            createdAt: ts,
-            expiresAt: ts + this.ttlMs,
-        });
-        if (input.clientOrderId)
-            this.cidIndex.set(input.clientOrderId, input.orderId);
-        this.persist();
-    }
-    /** Re-key a pre-submission stash (keyed by clientOrderId) to the
-     *  exchange-issued orderId once the REST ack returns. The cid alias keeps
-     *  working. No-op when the entry is gone (already consumed by a WS fill
-     *  that beat the REST response, or expired). */
-    promote(fromKey, exchangeOrderId) {
-        const key = this.resolveKey(fromKey);
-        if (key === undefined || key === exchangeOrderId)
-            return;
-        const entry = this.entries.get(key);
-        if (!entry)
-            return;
-        this.entries.delete(key);
-        entry.orderId = exchangeOrderId;
-        this.entries.set(exchangeOrderId, entry);
-        if (entry.clientOrderId)
-            this.cidIndex.set(entry.clientOrderId, exchangeOrderId);
-        this.persist();
-    }
-    /** Retrieve metadata stashed for an orderId (or clientOrderId alias).
-     *  Does NOT remove the entry — callers should call `consume(orderId)` to
-     *  remove on first match, since multiple partial fills on the same limit
-     *  order all share one orderId and the FIRST fill is the entry; subsequent
-     *  are scale-ins of an already-registered position (state-store branch
-     *  handles those). */
-    get(orderId) {
-        this.pruneExpired();
-        const key = this.resolveKey(orderId);
-        return key === undefined ? undefined : this.entries.get(key);
-    }
-    /** Atomic get + remove (accepts orderId or clientOrderId). Use this when
-     *  you've already consumed the metadata to post an entry row and don't
-     *  want it picked up again. */
-    consume(orderId) {
-        this.pruneExpired();
-        const key = this.resolveKey(orderId);
-        if (key === undefined)
-            return undefined;
-        const entry = this.entries.get(key);
-        if (!entry)
-            return undefined;
-        this.deleteEntry(key, entry);
-        this.persist();
-        return entry;
-    }
-    /** Remove an entry without retrieval (e.g. on cancel). */
-    drop(orderId) {
-        const key = this.resolveKey(orderId);
-        if (key === undefined)
-            return false;
-        const entry = this.entries.get(key);
-        if (!entry)
-            return false;
-        this.deleteEntry(key, entry);
-        this.persist();
-        return true;
-    }
-    /** Resolve a lookup key that may be an orderId or a clientOrderId alias. */
-    resolveKey(k) {
-        if (this.entries.has(k))
-            return k;
-        const viaCid = this.cidIndex.get(k);
-        return viaCid !== undefined && this.entries.has(viaCid) ? viaCid : undefined;
-    }
-    deleteEntry(key, entry) {
-        this.entries.delete(key);
-        if (entry.clientOrderId)
-            this.cidIndex.delete(entry.clientOrderId);
-    }
-    size() {
-        return this.entries.size;
-    }
-    getFilePath() {
-        return this.filePath;
-    }
-    // ---- Internals ----
-    pruneExpired() {
-        const ts = this.now();
-        let pruned = false;
-        for (const [orderId, entry] of this.entries) {
-            if (entry.expiresAt <= ts) {
-                this.deleteEntry(orderId, entry);
-                pruned = true;
-            }
-        }
-        if (pruned)
-            this.persist();
-    }
-    loadOrInit() {
-        if (!existsSync(this.filePath)) {
-            logger.info(TAG, `No state file at ${this.filePath}; starting empty`);
-            return;
-        }
-        let raw;
-        try {
-            raw = readFileSync(this.filePath, 'utf8');
-        }
-        catch (err) {
-            throw new Error(`pending-entry-metadata: failed to read ${this.filePath}: ${formatError(err)}`);
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch (err) {
-            throw new Error(`pending-entry-metadata: ${this.filePath} is not valid JSON: ${formatError(err)}`);
-        }
-        const file = this.validateFile(parsed);
-        const ts = this.now();
-        let kept = 0;
-        let dropped = 0;
-        for (const entry of file.entries) {
-            if (entry.expiresAt > ts) {
-                this.entries.set(entry.orderId, entry);
-                if (entry.clientOrderId)
-                    this.cidIndex.set(entry.clientOrderId, entry.orderId);
-                kept++;
-            }
-            else {
-                dropped++;
-            }
-        }
-        logger.info(TAG, `Loaded ${kept} pending entries from ${this.filePath}` +
-            (dropped > 0 ? ` (pruned ${dropped} expired)` : ''));
-        if (dropped > 0)
-            this.persist();
-    }
-    persist() {
-        const file = {
-            schemaVersion: SCHEMA_VERSION,
-            entries: Array.from(this.entries.values()),
-        };
-        const tempPath = `${this.filePath}.tmp`;
-        writeFileSync(tempPath, JSON.stringify(file, null, 2));
-        renameSync(tempPath, this.filePath);
-    }
-    validateFile(raw) {
-        if (!isRecord(raw))
-            throw new Error('pending-entry-metadata: file root is not an object');
-        if (raw.schemaVersion !== SCHEMA_VERSION) {
-            throw new Error(`pending-entry-metadata: unsupported schemaVersion ${String(raw.schemaVersion)} (expected ${SCHEMA_VERSION})`);
-        }
-        if (!Array.isArray(raw.entries))
-            throw new Error('pending-entry-metadata: entries is not an array');
-        const entries = [];
-        for (const e of raw.entries) {
-            if (!isRecord(e))
-                throw new Error('pending-entry-metadata: entry is not an object');
-            if (typeof e.orderId !== 'string' || e.orderId.length === 0) {
-                throw new Error('pending-entry-metadata: entry missing orderId');
-            }
-            if (e.clientOrderId !== undefined && (typeof e.clientOrderId !== 'string' || e.clientOrderId.length === 0)) {
-                throw new Error('pending-entry-metadata: invalid clientOrderId');
-            }
-            if (typeof e.symbol !== 'string' || e.symbol.length === 0) {
-                throw new Error('pending-entry-metadata: entry missing symbol');
-            }
-            if (e.side !== 'buy' && e.side !== 'sell') {
-                throw new Error(`pending-entry-metadata: bad side ${String(e.side)}`);
-            }
-            if (typeof e.expiresAt !== 'number' || !Number.isFinite(e.expiresAt)) {
-                throw new Error('pending-entry-metadata: missing/invalid expiresAt');
-            }
-            entries.push(e);
-        }
-        return { schemaVersion: SCHEMA_VERSION, entries };
-    }
-}
-function isRecord(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}

package/assets/plugin/ingest/position-auto-capture.d.ts

@@ -1,171 +0,0 @@
-import type { PositionDecisionsClient } from './position-decisions-client.js';
-import type { PositionStateStore } from '../live/position-state-store.js';
-import type { CcxtOrder } from '../types.js';
-import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { PositionMetadata } from '../simulator/types.js';
-import type { PendingEntryStore } from './pending-entry-metadata.js';
-import type { ReentryTracker } from '../portfolio/reentry-tracker.js';
-export interface AutoCaptureContext {
-    decisionsClient?: PositionDecisionsClient;
-    stateStore?: PositionStateStore;
-    /** Stash for create_order metadata that arrives BEFORE the fill (limit
-     *  orders that don't fill immediately). Looked up by exchangeOrderId when
-     *  the WS fill arrives via `onWsFillObserved`. */
-    pendingEntries?: PendingEntryStore;
-    userId?: string;
-    /** When true, a reduce-only fill that takes a journaled position flat is
-     *  auto-captured as an exact close (bracket SL/TP fill or other close that
-     *  bypassed close_position). Default behaviour when unset is the legacy
-     *  no-op (reduce-only fills ignored). Env kill-switch: RC_JOURNAL_CLOSE_ON_FILL
-     *  (set 'off' to disable). See docs/CLAUDE/position-journal.md (close-bypass). */
-    closeOnReduceOnlyFill?: boolean;
-    /** Resolve the active trading book ('paper' | 'live') at capture time, read
-     *  from the current adapter (so it follows a runtime reconnect). Tags the
-     *  journal position row so paper and live entries can be segregated. */
-    resolveMode?: () => 'paper' | 'live';
-    /** Venue this gateway trades ('binance' | 'hyperliquid'). Static per process
-     *  — changing venue requires a config edit + restart (plan §5.2), so unlike
-     *  `resolveMode` this is a plain value, not a resolver. Tags journal rows
-     *  (positions.exchange, migration 0058). */
-    venue?: 'binance' | 'hyperliquid';
-    /** Resolve the ACTIVE adapter at capture time (follows a runtime reconnect,
-     *  same deferred-closure pattern as resolveMode). Used by the stale-state
-     *  defense in onCreateOrderFilled: when the state-store claims an open
-     *  position but the exchange position is exactly the just-filled quantity,
-     *  the prior exposure was closed outside the journal (watcher/manual) and
-     *  the mapping is STALE — stitching onto it fabricates P&L (issue #199). */
-    resolveAdapter?: () => IExchangeAdapter | undefined;
-    /** Re-entry tracker (issue #204) — every close path records the exit so
-     *  scan_pairs can flag setups already traded within the current signal bar. */
-    reentryTracker?: ReentryTracker;
-}
-/** Engine-exact paper fill economics attached by the simulator to close-order
- *  results (`order.info.paperTrade`, issue #201). All numbers are quote-ccy. */
-export interface PaperTradeInfo {
-    grossRealizedPnl: number;
-    netRealizedPnl: number;
-    openFee: number;
-    closeFee: number;
-    setupType?: string;
-}
-/** Extract the simulator's engine-exact trade economics from a close order,
- *  with strict numeric guards (absent on live orders → undefined). */
-export declare function extractPaperTrade(order: CcxtOrder | undefined): PaperTradeInfo | undefined;
-export interface CreateOrderInputs {
-    symbol: string;
-    side: 'buy' | 'sell';
-    metadata?: PositionMetadata;
-}
-/** Called after a successful adapter.createOrder().
- *
- *  For PR 1, we treat any non-zero `filled` quantity as an entry event and
- *  upsert the parent position + post the entry decision row. Limit orders that
- *  haven't filled yet are skipped (caller can call us again from the WS-ingest
- *  pipeline once they fill — that wiring is the follow-up).
- *
- *  Always-fail-open: webapp errors are logged but never thrown.
- */
-export declare function onCreateOrderFilled(ctx: AutoCaptureContext, inputs: CreateOrderInputs, order: CcxtOrder): Promise<void>;
-export interface ClosePositionInputs {
-    symbol: string;
-    closeReason: string;
-    closeAssessment: Record<string, unknown>;
-    /** Optional v2.10.0 inputs the agent may have passed alongside reason+assessment. */
-    scorecardVerdict?: string;
-    confluenceScore?: number;
-    regime?: string;
-    regimeConfidence?: number;
-}
-/** Called after a successful adapter.closePosition() with the v2.10.0 reason +
- *  assessment from close_position.ts. Looks up the cached position UUID, posts
- *  the close decision row, and drops the local state entry. */
-export declare function onClosePositionFilled(ctx: AutoCaptureContext, inputs: ClosePositionInputs, order: CcxtOrder): Promise<void>;
-export interface AutoFlattenCloseInputs {
-    symbol: string;
-    /** Actual average fill price of the flatten close (resolved, never a limit). */
-    fillPrice: number;
-    fillSize: number;
-    exchangeTradeId?: string;
-    observedAtMs?: number;
-}
-/** Journal the close produced by an adapter-internal auto-flatten
- *  (`bracket_attach_failed`). Those flattens call `adapter.closePosition`
- *  directly, bypassing the close_position tool, so `onClosePositionFilled`
- *  never runs and the position row orphaned as status='open' (issue #196:
- *  LTC 2026-07-14, TAO 2026-07-15 — both showed 1 exchange position vs 2 in the
- *  journal). Polls briefly for the entry journal's webappPositionId (the
- *  entry's WS fill can arrive just after the flatten), then posts an idempotent
- *  close row (UNIQUE on position_id) and drops the state-store entry. Fail-open;
- *  the boot DB reconcile sweep is the backstop if the entry never journals. */
-export declare function onAutoFlattenClose(ctx: AutoCaptureContext, inputs: AutoFlattenCloseInputs, lookup?: {
-    attempts: number;
-    intervalMs: number;
-}): Promise<void>;
-export interface StopWatcherCloseInputs {
-    symbol: string;
-    stopPrice: number;
-    markPrice: number;
-    /** The executed close order from adapter.closePosition (may be absent if the
-     *  close resolved through a path that didn't surface it). */
-    order?: CcxtOrder;
-}
-/** Journal a stop-watcher auto-close (issue #199).
- *
- *  The watcher calls `adapter.closePosition(symbol, 'stop_watcher')` directly —
- *  it never goes through the close_position tool, and paper has no WS fill
- *  stream, so before this hook every watcher close left the journal position
- *  (and the state-store mapping) alive: the next trade on the symbol was then
- *  silently dropped or stitched onto the stale position, fabricating P&L
- *  (measured 14/69 corrupted closes on the 2026-07 HL soak; worst single
- *  fabrication −$117.86 vs a real −$10.63).
- *
- *  Contract: the engine exposure is DEFINITIVELY gone when this runs (the
- *  watcher's close resolved), so the state-store entry is always dropped —
- *  even when we can't post a close row (the periodic DB sweep then heals the
- *  orphaned DB row instead of a later close being mis-stitched). Fail-open. */
-export declare function onStopWatcherClose(ctx: AutoCaptureContext, inputs: StopWatcherCloseInputs): Promise<void>;
-/** WS-driven fill observed. Resolves the PR1 deferral that limit-order fills
- *  + scale-ins were silently dropped. Branches on three cases:
- *
- *    - reduceOnly fill   →  ignored here (close path runs from close_position
- *                            tool with v2.10.0 reason+assessment; bracket SL/TP
- *                            fills also reduce-only and the legacy bracket
- *                            handler covers those).
- *    - new-symbol entry  →  no state-store row → register the position +
- *                            post entry decision row (uses pending metadata
- *                            from the cache, or '(no thesis recorded)' fallback).
- *    - same-side fill on  →  state-store row exists with same side → SCALE-IN.
- *      existing position    Posts a position_entries row with is_scale_in=true.
- *                            Does NOT create a new positions row (single parent
- *                            per open exposure).
- *    - opposite-side fill →  state-store has same symbol but opposite side.
- *      on existing position  Treated as a manual flatten that bypassed the
- *                            close_position tool — skip (cleaner to require
- *                            close_position for proper rationale capture).
- *
- *  Dedup: when create_order's market-order path already captured an entry
- *  synchronously, the state-store entry's `openedFromExchangeTradeId` matches
- *  this fill's orderId. We detect that and skip to avoid double-posting. */
-export interface WsFillInputs {
-    symbol: string;
-    side: 'buy' | 'sell';
-    exchangeOrderId: string;
-    exchangeTradeId: string;
-    fillPrice: number;
-    fillSize: number;
-    reduceOnly: boolean;
-    /** Binance-exact realised PnL on this specific fill (`o.rp`). Used to sum the
-     *  position's realised PnL when a reduce-only fill takes it flat. */
-    realizedPnl?: number;
-    /** Client order id of the fill. Lets the reduce-only close handler tag a
-     *  bracket SL/TP fill (cid is a bracket cid) vs an external reduce-only close. */
-    clientOrderId?: string;
-    /** Timestamp from the exchange. Falls back to Date.now() if not provided. */
-    exchangeTimeMs?: number;
-}
-export declare function onWsFillObserved(ctx: AutoCaptureContext, fill: WsFillInputs): Promise<void>;
-/** Pinned-plan subset persisted to position_entries.metadata (free-form JSONB).
- *  Keys are snake_case per the canonical-JSONB-key rule (CLAUDE.md learning-loop:
- *  a camelCase mismatch previously broke learning matching). Returns undefined
- *  when neither field is present so we never write an empty object. */
-export declare function buildEntryPlanMetadata(md: PositionMetadata | undefined): Record<string, unknown> | undefined;