@reefclaw/connect 0.1.12 → 0.1.13

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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,236 @@
+// 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

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