@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/ingest/position-auto-capture.js

@@ -1,411 +0,0 @@
-// Auto-capture helper for the Position Decision Journal.
-//
-// Wires create_order / close_position / fill events into the webapp ingest:
-//
-//   ENTRY  — onCreateOrderFilled() upserts the parent positions row, gets back
-//             the UUID, persists it locally for restart-survival, then posts the
-//             entry decision row.
-//   CLOSE  — onClosePositionFilled() looks up the cached position UUID and posts
-//             the close decision row. Local position-state is dropped after the
-//             dispatch so the symbol can re-enter cleanly.
-//
-// Auto-capture is mode-agnostic — it runs whenever the decisions client is
-// configured (env vars present), regardless of trading mode (PAPER vs LIVE) or
-// positionReview.mode. Fail-open: a network blip on a webapp POST does not
-// block the trading hot path.
-//
-// PR 1 scope: market orders (immediate fill detection from CcxtOrder.filled).
-// Limit-order fill capture and scale-in detection are deferred to a follow-up
-// that hooks into the WS-ingest pipeline (see POSITION_DECISION_JOURNAL_PLAN
-// §5.1 for the longer-term design).
-import { logger } from '../logger.js';
-import { isBracketCid } from '../live/bracket-id.js';
-const TAG = 'position-auto-capture';
-/** Flatness tolerance for remaining-contracts tracking. Reduce-only fills sum
- *  exactly to the position size on Binance, so any residual below this is noise
- *  / float rounding and means the position is flat. */
-const FLAT_EPSILON = 1e-6;
-/** 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 async function onCreateOrderFilled(ctx, inputs, order) {
-    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
-        return;
-    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
-        ? order.filled
-        : 0;
-    if (filledQty <= 0) {
-        // Limit order not yet filled — nothing to capture yet.
-        return;
-    }
-    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
-        ? order.average
-        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
-            ? order.price
-            : null;
-    if (fillPrice === null) {
-        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: missing fill price; skipping capture`);
-        return;
-    }
-    // Need v2.10.0 metadata to build a meaningful entry row. In paper mode the
-    // agent may omit them; we still capture an entry but mark missing fields.
-    const md = inputs.metadata;
-    if (!md) {
-        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: no metadata; skipping (paper without rationale)`);
-        return;
-    }
-    const positionSide = inputs.side === 'buy' ? 'long' : 'short';
-    const openedAtMs = Date.now();
-    // Skip if state-store already knows about this position (scale-in / partial
-    // fill of an existing entry). PR 1 deferral: don't record additional entries.
-    // The follow-up that hooks WS-ingest will detect scale-ins explicitly.
-    const existing = ctx.stateStore.get(inputs.symbol);
-    if (existing) {
-        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: existing position in state-store (openedAt=${existing.openedAt}); treating as scale-in (auto-capture deferred to v2)`);
-        return;
-    }
-    // Local state-store first — ensures restart-survival even if the webapp POST
-    // fails on the first attempt.
-    ctx.stateStore.upsert({
-        symbol: inputs.symbol,
-        openedAt: openedAtMs,
-        side: positionSide,
-        openedFromExchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
-    });
-    const upsert = {
-        symbol: inputs.symbol,
-        positionOpenAt: openedAtMs,
-        side: positionSide,
-        currentSize: filledQty,
-        avgEntryPrice: fillPrice,
-        mode: ctx.resolveMode?.(),
-        exchange: ctx.venue,
-    };
-    // postPosition is awaited — we need the UUID before posting the entry row.
-    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
-    if (!positionId) {
-        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: webapp position upsert returned no id; entry row will not be posted (will retry on next observation)`);
-        return;
-    }
-    ctx.stateStore.setWebappId(inputs.symbol, positionId);
-    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
-    ctx.stateStore.addOpenContracts(inputs.symbol, filledQty);
-    // Build entry decision payload from the v2.10.0 metadata.
-    // regime_confidence stored 0-100 in PositionMetadata (per validator), but the
-    // webapp schema expects 0-1. Normalize.
-    const regimeConfNormalized = typeof md.regimeConfidence === 'number'
-        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
-        : 0.5;
-    const entry = {
-        positionId,
-        entryAt: openedAtMs,
-        isScaleIn: false,
-        thesis: md.thesis ?? '(no thesis recorded)',
-        setupType: md.setupType ?? 'unknown',
-        regime: md.regime ?? 'unknown',
-        regimeConfidence: regimeConfNormalized,
-        scorecardVerdict: md.scorecardVerdict ?? 'GO',
-        confluenceScore: typeof md.confluenceScore === 'number' ? md.confluenceScore : 0,
-        fillPrice,
-        fillSize: filledQty,
-        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
-        metadata: buildEntryPlanMetadata(md),
-    };
-    ctx.decisionsClient.postEntry(ctx.userId, entry);
-    logger.info(TAG, `entry captured ${inputs.symbol} ${positionSide} ${filledQty} @ ${fillPrice} (positionId=${positionId.slice(0, 8)}…)`);
-}
-/** 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 async function onClosePositionFilled(ctx, inputs, order) {
-    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
-        return;
-    const stateEntry = ctx.stateStore.get(inputs.symbol);
-    if (!stateEntry || !stateEntry.webappPositionId) {
-        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: no cached webappPositionId; close row will not be posted (entry was not captured)`);
-        return;
-    }
-    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
-        ? order.filled
-        : 0;
-    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
-        ? order.average
-        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
-            ? order.price
-            : null;
-    if (filledQty <= 0 || fillPrice === null) {
-        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: missing fill quantity or price; skipping capture`);
-        return;
-    }
-    const closeAtMs = Date.now();
-    // Realized PnL + R-multiple require entry-side state we don't have here for
-    // PR 1. The skill-side computation already produces these for the webapp;
-    // this auto-capture just records what the close tool input told us. Default
-    // numeric fields to 0 — webapp accepts and the operator will see the close
-    // card with zeros until the v2 ws-ingest hook fills them properly.
-    const regimeConfNormalized = typeof inputs.regimeConfidence === 'number'
-        ? Math.max(0, Math.min(1, inputs.regimeConfidence / 100))
-        : 0.5;
-    const close = {
-        positionId: stateEntry.webappPositionId,
-        closeAt: closeAtMs,
-        closeReason: inputs.closeReason,
-        closeAssessment: inputs.closeAssessment,
-        scorecardVerdict: inputs.scorecardVerdict ?? 'NO_GO',
-        confluenceScore: typeof inputs.confluenceScore === 'number' ? inputs.confluenceScore : 0,
-        regime: inputs.regime ?? 'unknown',
-        regimeConfidence: regimeConfNormalized,
-        fillPrice,
-        fillSize: filledQty,
-        realizedPnl: 0, // populated by v2 ws-ingest hook
-        realizedR: 0,
-        mfeRAtClose: 0,
-        giveBackPctAtClose: 0,
-        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
-    };
-    ctx.decisionsClient.postClose(ctx.userId, close);
-    // Drop local state — symbol can re-enter as a new position.
-    ctx.stateStore.remove(inputs.symbol);
-    logger.info(TAG, `close captured ${inputs.symbol} reason=${inputs.closeReason} (positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
-}
-/** Look up the metadata create_order stashed for this fill. Primary key is
- *  the exchange orderId (post-REST-ack `promote()`); the clientOrderId
- *  fallback covers the routine market-order race where the WS fill arrives
- *  BEFORE the REST response, i.e. before the promote — the pre-submission
- *  stash is keyed by the cid, which the WS event carries (`o.c`). */
-function consumePendingEntry(ctx, fill) {
-    if (!ctx.pendingEntries)
-        return undefined;
-    return (ctx.pendingEntries.consume(fill.exchangeOrderId) ??
-        (fill.clientOrderId ? ctx.pendingEntries.consume(fill.clientOrderId) : undefined));
-}
-export async function onWsFillObserved(ctx, fill) {
-    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
-        return;
-    if (fill.fillPrice <= 0 || fill.fillSize <= 0)
-        return;
-    // Reduce-only fills are exit-side. close_position tool exits are journaled by
-    // onClosePositionFilled; bracket SL/TP fills and other reduce-only closes
-    // bypass that path entirely and used to leave the journal position open
-    // forever (close-bypass class). When closeOnReduceOnlyFill is enabled, detect
-    // the position going flat from the fill(s) and journal an exact close.
-    if (fill.reduceOnly) {
-        await handleReduceOnlyExit(ctx, fill);
-        return;
-    }
-    const stateEntry = ctx.stateStore.get(fill.symbol);
-    const fillSide = fill.side === 'buy' ? 'long' : 'short';
-    const ts = fill.exchangeTimeMs ?? Date.now();
-    if (stateEntry) {
-        // Dedup: if the synchronous create_order path already captured this
-        // exact order (orderId match), the WS event is the same fill — skip.
-        if (stateEntry.openedFromExchangeTradeId === fill.exchangeOrderId) {
-            return;
-        }
-        if (stateEntry.side !== fillSide) {
-            // Opposite-side fill on an existing position. Almost certainly a manual
-            // flatten that bypassed close_position. Don't journal here — the
-            // operator should use close_position with reason+assessment instead.
-            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: opposite-side fill on existing ${stateEntry.side} position; skipping (use close_position for rationale capture)`);
-            return;
-        }
-        // SCALE-IN: same symbol, same side, fresh fill.
-        if (!stateEntry.webappPositionId) {
-            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: scale-in observed but no webappPositionId yet — skipping (parent upsert may have failed; will retry next fill)`);
-            return;
-        }
-        const pending = consumePendingEntry(ctx, fill);
-        const entry = buildEntryPayload({
-            positionId: stateEntry.webappPositionId,
-            isScaleIn: true,
-            ts,
-            fillPrice: fill.fillPrice,
-            fillSize: fill.fillSize,
-            exchangeTradeId: fill.exchangeTradeId,
-            metadata: pending?.metadata,
-        });
-        ctx.decisionsClient.postEntry(ctx.userId, entry);
-        // Grow tracked size so a later reduce-only exit detects flat correctly.
-        ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
-        logger.info(TAG, `scale-in captured ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
-            `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
-        return;
-    }
-    // No state-store entry → NEW position via WS-driven fill. Replicates the
-    // synchronous-market-order path but pulls metadata from the pending cache
-    // (which create_order populated BEFORE submitting the order).
-    const pending = consumePendingEntry(ctx, fill);
-    ctx.stateStore.upsert({
-        symbol: fill.symbol,
-        openedAt: ts,
-        side: fillSide,
-        openedFromExchangeTradeId: fill.exchangeOrderId,
-    });
-    const upsert = {
-        symbol: fill.symbol,
-        positionOpenAt: ts,
-        side: fillSide,
-        currentSize: fill.fillSize,
-        avgEntryPrice: fill.fillPrice,
-        mode: ctx.resolveMode?.(),
-        exchange: ctx.venue,
-    };
-    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
-    if (!positionId) {
-        logger.warn(TAG, `onWsFillObserved ${fill.symbol}: webapp position upsert returned no id; entry row will not be posted`);
-        return;
-    }
-    ctx.stateStore.setWebappId(fill.symbol, positionId);
-    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
-    ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
-    const entry = buildEntryPayload({
-        positionId,
-        isScaleIn: false,
-        ts,
-        fillPrice: fill.fillPrice,
-        fillSize: fill.fillSize,
-        exchangeTradeId: fill.exchangeTradeId,
-        metadata: pending?.metadata,
-    });
-    ctx.decisionsClient.postEntry(ctx.userId, entry);
-    logger.info(TAG, `entry captured (ws) ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
-        `(positionId=${positionId.slice(0, 8)}…, metadata=${pending ? 'cached' : 'none'})`);
-}
-/** Reduce-only exit fill handler — the close-bypass fix. When enabled, sums the
- *  fill's realised PnL into the tracked position and, once remaining size hits
- *  flat, posts an exact close decision row (Binance-exact realised PnL, real
- *  exit price) and drops the local state entry. Idempotent at the webapp
- *  (position_closes UNIQUE on position_id); fail-open. */
-async function handleReduceOnlyExit(ctx, fill) {
-    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
-        return;
-    // Gated: when off, preserve the legacy behaviour (reduce-only fills ignored).
-    if (!ctx.closeOnReduceOnlyFill)
-        return;
-    const stateEntry = ctx.stateStore.get(fill.symbol);
-    // No tracked entry (already cleaned, or never journaled) → nothing to close.
-    if (!stateEntry || !stateEntry.webappPositionId)
-        return;
-    const updated = ctx.stateStore.applyExitContracts(fill.symbol, fill.fillSize, fill.realizedPnl ?? 0);
-    if (!updated) {
-        // Size unknown for this entry (opened before tracking existed and not yet
-        // seeded). Can't decide flatness from fills — leave the reconciler/ALGO
-        // close-bypass path as the backstop.
-        logger.info(TAG, `reduce-only fill ${fill.symbol}: size untracked; deferring close to reconciler/ALGO backstop`);
-        return;
-    }
-    const remaining = updated.remainingContracts ?? 0;
-    if (remaining > FLAT_EPSILON) {
-        logger.info(TAG, `partial exit ${fill.symbol}: ${fill.fillSize} reduce-only fill, ${remaining} contracts remaining`);
-        return; // not flat yet — keep accumulating
-    }
-    // FLAT. Auto-journal an exact close ONLY for exchange-native bracket fills
-    // (the cid is one of our bracket legs). Non-bracket reduce-only flats are
-    // either close_position's own order (its WS fill can race ahead of
-    // onClosePositionFilled) or a manual/external close — both are handled by
-    // their own paths (close_position's rich reason+assessment, or the reconciler
-    // backstop). Closing here would clobber the agent's close reasoning, so defer.
-    const isBracket = fill.clientOrderId ? isBracketCid(fill.clientOrderId) : false;
-    if (!isBracket) {
-        logger.info(TAG, `${fill.symbol} flat via non-bracket reduce-only fill (cid=${fill.clientOrderId ?? 'none'}) — ` +
-            `deferring close to close_position / reconciler backstop (no clobber)`);
-        return; // do NOT remove — onClosePositionFilled / backstop owns this close
-    }
-    const realizedPnl = updated.realizedPnlAccum ?? 0;
-    const close = {
-        positionId: stateEntry.webappPositionId,
-        closeAt: fill.exchangeTimeMs ?? Date.now(),
-        closeReason: 'bracket_fill',
-        closeAssessment: {
-            note: 'Position closed by an exchange-native bracket SL/TP fill (reduce-only). ' +
-                'Auto-journaled from the WS fill — no close_position call (close-bypass path).',
-            observedFrom: 'ws_reduce_only_fill',
-            clientOrderId: fill.clientOrderId,
-        },
-        scorecardVerdict: 'NO_GO',
-        confluenceScore: 0,
-        regime: 'unknown',
-        regimeConfidence: 0.5,
-        fillPrice: fill.fillPrice,
-        fillSize: Math.abs(fill.fillSize),
-        // realizedPnl is Binance-exact (summed across exit fills); the zeros below
-        // are filled in PER-METRIC by the webapp close route (price-based R from
-        // the pinned invalidation_price, mfe/give-back from the last review — see
-        // webapp lib/api/close-metrics.ts). The route's old all-four-zero gate
-        // meant this non-zero PnL used to suppress that fill-in entirely, persisting
-        // realized_r=0 on every bracket_fill close (the 2026-07-11 zero-hole).
-        realizedPnl,
-        realizedR: 0,
-        mfeRAtClose: 0,
-        giveBackPctAtClose: 0,
-        exchangeTradeId: fill.exchangeTradeId,
-    };
-    ctx.decisionsClient.postClose(ctx.userId, close);
-    ctx.stateStore.remove(fill.symbol);
-    logger.info(TAG, `close captured (ws bracket fill) ${fill.symbol} pnl=${realizedPnl.toFixed(4)} ` +
-        `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
-}
-/** Internal helper — builds the PositionEntryPayload from a fill, applying the
- *  same regimeConfidence normalisation (0-100 → 0-1) as the synchronous path. */
-function buildEntryPayload(args) {
-    const md = args.metadata;
-    const regimeConfNormalized = typeof md?.regimeConfidence === 'number'
-        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
-        : 0.5;
-    return {
-        positionId: args.positionId,
-        entryAt: args.ts,
-        isScaleIn: args.isScaleIn,
-        thesis: md?.thesis ?? '(no thesis recorded)',
-        setupType: md?.setupType ?? 'unknown',
-        regime: md?.regime ?? 'unknown',
-        regimeConfidence: regimeConfNormalized,
-        scorecardVerdict: md?.scorecardVerdict ?? 'GO',
-        confluenceScore: typeof md?.confluenceScore === 'number' ? md.confluenceScore : 0,
-        fillPrice: args.fillPrice,
-        fillSize: args.fillSize,
-        exchangeTradeId: args.exchangeTradeId,
-        metadata: buildEntryPlanMetadata(md),
-    };
-}
-/** 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 function buildEntryPlanMetadata(md) {
-    if (!md)
-        return undefined;
-    const out = {};
-    if (typeof md.invalidationPrice === 'number' && Number.isFinite(md.invalidationPrice)) {
-        out.invalidation_price = md.invalidationPrice;
-    }
-    // Pin the planned profit target too — it's the agent's stated target (and the
-    // bracket TP in live), surfaced on the dashboard pinned-plan view. Distinct
-    // from realization_rule (which is mostly omitted); without this the target is
-    // blank on the journal/Trade-card pinned-plan surfaces in the common case.
-    if (typeof md.targetPrice === 'number' && Number.isFinite(md.targetPrice)) {
-        out.target_price = md.targetPrice;
-    }
-    const rr = md.realizationRule;
-    if (rr) {
-        const j = { type: rr.type };
-        if (rr.targetPrice != null)
-            j.target_price = rr.targetPrice;
-        if (rr.trailAfterR != null)
-            j.trail_after_r = rr.trailAfterR;
-        if (rr.trailDistanceR != null)
-            j.trail_distance_r = rr.trailDistanceR;
-        if (rr.scale)
-            j.scale = rr.scale.map((s) => ({ at_r: s.atR, fraction: s.fraction }));
-        if (rr.note)
-            j.note = rr.note;
-        out.realization_rule = j;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}