@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/tools/assessment-validation.js

@@ -1,473 +0,0 @@
-// Assessment-schema validators for agent tool calls (SKILL.md v2.10.0).
-//
-// The LLM's value is context-sensitive reasoning.  We don't want to gate
-// trading tools behind time floors (a thesis CAN legitimately invalidate
-// in 60 seconds).  We want to gate them behind PROOF that the reasoning
-// happened — a structured assessment the agent has to fill from real
-// scorecard data.  If it filled the fields, the reasoning happened.  If
-// it didn't, we reject.
-//
-// Used by:
-//   - close-position.ts   — requires `reason` + `assessment` on every call.
-//   - create-order.ts     — requires thesis + regime + confluence_score in
-//                           live mode.
-// Tested in: assessment-validation.test.ts.
-import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
-// ---- protective geometry (create_order, issue #200) ----
-/** Minimum pre-entry stop distance in basis points (the SKILL v2.10.0
- *  discipline floor's fixed component; the ATR component is enforced by the
- *  live bracket path where ATR is authoritative). */
-export const MIN_STOP_DISTANCE_BPS = 30;
-/** Validate stop / invalidation / target geometry against the entry side.
- *
- *  Before this existed the wrong-side check ran ONLY on the wave9 path
- *  (create-order.ts) — a generic short entered with its stop BELOW entry
- *  passed validation and was closed by the stop-watcher seconds later
- *  (7 sub-5-minute kills on the 2026-07 HL soak, issue #200). Returns an
- *  error string, or null when the geometry is sound. Fields left undefined
- *  are not judged (stop-required policy stays with the caller). */
-export function validateProtectiveGeometry(args) {
-    const { side, refPrice } = args;
-    if (!Number.isFinite(refPrice) || refPrice <= 0)
-        return null; // no reference — cannot judge
-    const dirWord = side === 'buy' ? 'long' : 'short';
-    if (args.stopPrice !== undefined) {
-        const stop = args.stopPrice;
-        if (!Number.isFinite(stop) || stop <= 0) {
-            return 'stopPrice must be a positive finite number.';
-        }
-        if ((side === 'buy' && stop >= refPrice) || (side === 'sell' && stop <= refPrice)) {
-            return (`stopPrice ${stop} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: a ${dirWord}'s ` +
-                `protective stop must be ${side === 'buy' ? 'below' : 'above'} entry. A wrong-side stop is ` +
-                `instantly "breached" and the stop-watcher closes the position seconds after entry.`);
-        }
-        const distanceBps = (Math.abs(refPrice - stop) / refPrice) * 10_000;
-        if (distanceBps < MIN_STOP_DISTANCE_BPS) {
-            return (`stopPrice ${stop} is only ${distanceBps.toFixed(1)}bps from entry ${refPrice} — below the ` +
-                `${MIN_STOP_DISTANCE_BPS}bps discipline floor. Place the stop at a structural level ` +
-                `(≥ max(0.3×ATR, ${MIN_STOP_DISTANCE_BPS}bps) from entry).`);
-        }
-    }
-    if (args.invalidationPrice !== undefined) {
-        const inv = args.invalidationPrice;
-        if (!Number.isFinite(inv) || inv <= 0) {
-            return 'invalidation_price must be a positive finite number.';
-        }
-        if ((side === 'buy' && inv >= refPrice) || (side === 'sell' && inv <= refPrice)) {
-            return (`invalidation_price ${inv} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
-                `invalidation must be ${side === 'buy' ? 'below' : 'above'} entry (it marks where the thesis ` +
-                `is WRONG, not where it profits). Fix the pinned plan before entering.`);
-        }
-    }
-    if (args.targetPrice !== undefined) {
-        const target = args.targetPrice;
-        if (!Number.isFinite(target) || target <= 0) {
-            return 'target_price must be a positive finite number.';
-        }
-        if ((side === 'buy' && target <= refPrice) || (side === 'sell' && target >= refPrice)) {
-            return (`target_price ${target} is on the WRONG SIDE of entry ${refPrice} for a ${dirWord}: ` +
-                `the profit target must be ${side === 'buy' ? 'above' : 'below'} entry.`);
-        }
-    }
-    return null;
-}
-// ---- close_position ----
-/** The five legitimate reasons to manually close an otherwise-bracketed
- *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other
- *  value is rejected. */
-export const CLOSE_REASONS = [
-    'regime_flip',
-    // 'scorecard_reversal' — DEPRECATED 2026-06-16 (exit-discipline #2): a lower re-scored
-    // confluence is anti-predictive of outcome and is NOT a valid exit trigger. Removed from
-    // the menu; validateClosePosition rejects it early with a redirect to objective reasons.
-    'risk_limit',
-    'bracket_integrity',
-    'operator_command',
-];
-function nonEmptyString(v) {
-    return typeof v === 'string' && v.trim().length > 0;
-}
-function isScore(v) {
-    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 10;
-}
-/** Validate a `close_position` call against the SKILL.md v2.10.0 contract.
- *  Returns {ok:true} to proceed or {ok:false, error} to reject the tool call.
- *
- *  Philosophy: force the agent to submit structured proof that a real
- *  reassessment happened.  No time gate — a 60-second close is legal if the
- *  assessment holds up.  But blank or inconsistent fields mean no reasoning,
- *  so we refuse.
- */
-export function validateClosePosition(args) {
-    if (!nonEmptyString(args.symbol)) {
-        return { ok: false, error: 'Symbol is required.' };
-    }
-    // `reason` is required.  Enum check first.
-    if (!args.reason) {
-        return {
-            ok: false,
-            error: `close_position requires a 'reason' param (one of: ${CLOSE_REASONS.join(', ')}). ` +
-                'See SKILL.md v2.10.0 Position Management Discipline.',
-        };
-    }
-    // scorecard_reversal DEPRECATED 2026-06-16 (exit-discipline #2). The entry scorecard is
-    // anti-predictive of MFE, so re-scoring an open position and exiting on a lower score cut
-    // undeveloped trades for no edge (108 such closes, 82% never developed). The exit gate
-    // already blocks premature exits by MFE/current_r regardless of reason; this closes the
-    // agent-facing menu. See docs/EXIT_DISCIPLINE_BUILD_PLAN.md Step 1 (#2).
-    if (args.reason === 'scorecard_reversal') {
-        return {
-            ok: false,
-            error: "close reason 'scorecard_reversal' is deprecated — a lower re-scored confluence is not a valid " +
-                'exit trigger (the entry score is anti-predictive of outcome). Exit on an objective trigger instead: ' +
-                "'regime_flip' (name the regime change + contradicting_metric), 'risk_limit', a pinned-invalidation hit, " +
-                "or 'operator_command'. If the thesis genuinely broke, use 'regime_flip' and name the signal that flipped.",
-        };
-    }
-    if (!CLOSE_REASONS.includes(args.reason)) {
-        return {
-            ok: false,
-            error: `Invalid close reason: '${args.reason}'. Must be one of: ${CLOSE_REASONS.join(', ')}.`,
-        };
-    }
-    const reason = args.reason;
-    // Operator commands bypass the assessment requirement — operator typing
-    // "close ADA now" via chat doesn't need structured justification.
-    if (reason === 'operator_command') {
-        return { ok: true };
-    }
-    // All other reasons need an assessment object.
-    const a = args.assessment;
-    if (!a || typeof a !== 'object') {
-        return {
-            ok: false,
-            error: `close_position with reason='${reason}' requires an 'assessment' object. ` +
-                'Include entry_score, current_score, entry_regime, current_regime, and contradicting_metric.',
-        };
-    }
-    // Reason-specific consistency checks.
-    switch (reason) {
-        // scorecard_reversal handled earlier by the deprecation reject — no case here.
-        case 'regime_flip': {
-            if (!nonEmptyString(a.entry_regime)) {
-                return { ok: false, error: 'regime_flip requires assessment.entry_regime.' };
-            }
-            if (!nonEmptyString(a.current_regime)) {
-                return { ok: false, error: 'regime_flip requires assessment.current_regime.' };
-            }
-            if (a.entry_regime === a.current_regime) {
-                return {
-                    ok: false,
-                    error: `regime_flip requires current_regime to differ from entry_regime. ` +
-                        `Got entry_regime=current_regime='${a.entry_regime}'. ` +
-                        'If regime is unchanged but you still want to close, this is probably "HOLD" per the decision matrix.',
-                };
-            }
-            if (!nonEmptyString(a.contradicting_metric)) {
-                return {
-                    ok: false,
-                    error: 'regime_flip requires assessment.contradicting_metric describing what changed ' +
-                        '(e.g., "multi-TF alignment flipped from RANGE_WIDE to TREND_DOWN with 4h MACD cross").',
-                };
-            }
-            return { ok: true };
-        }
-        case 'risk_limit': {
-            // Risk-limit triggers are time-sensitive; require a terse justification
-            // but not the full scorecard.
-            if (!nonEmptyString(a.contradicting_metric)) {
-                return {
-                    ok: false,
-                    error: 'risk_limit requires assessment.contradicting_metric naming the metric at threshold ' +
-                        '(e.g., "drawdown utilisation 82% — AMBER zone", "gross exposure 1.9x NAV").',
-                };
-            }
-            return { ok: true };
-        }
-        case 'bracket_integrity': {
-            // Bracket reconciliation edge cases — expect the operator to describe the
-            // condition (e.g., ledger_terminal_no_order + attach_brackets failed).
-            if (!nonEmptyString(a.contradicting_metric)) {
-                return {
-                    ok: false,
-                    error: 'bracket_integrity requires assessment.contradicting_metric with the audit output ' +
-                        '(e.g., "audit_bracket_protection has_stop=false + attach_brackets returned ledger_terminal_no_order after 3 retries").',
-                };
-            }
-            return { ok: true };
-        }
-    }
-    return { ok: true };
-}
-/** Validate a `create_order` call against the SKILL.md v2.10.0 contract.
- *  Only enforced in LIVE mode — paper mode is for exploration and allows
- *  missing metadata so the agent can probe without full reasoning.  Live
- *  mode = real money = must show your work.
- */
-export function validateCreateOrder(args, isLive) {
-    if (!isLive)
-        return { ok: true };
-    if (!nonEmptyString(args.thesis) || args.thesis.length < 20) {
-        return {
-            ok: false,
-            error: 'create_order in live mode requires a thesis of at least 20 characters. ' +
-                'Briefly describe setup, regime, and the signal driving the entry.',
-        };
-    }
-    if (!nonEmptyString(args.setup_type)) {
-        return {
-            ok: false,
-            error: "create_order in live mode requires setup_type (e.g., 'pullback_to_ema', 'vwap_reversion', 'breakout'). " +
-                'The SKILL.md decision matrix expects it at heartbeat reassessment time.',
-        };
-    }
-    if (!nonEmptyString(args.regime)) {
-        return {
-            ok: false,
-            error: 'create_order in live mode requires regime (e.g., RANGE_WIDE, TREND_UP). ' +
-                'Heartbeat reassessment needs this to detect regime flips.',
-        };
-    }
-    if (typeof args.regime_confidence !== 'number' ||
-        !Number.isFinite(args.regime_confidence) ||
-        args.regime_confidence < 0 ||
-        args.regime_confidence > 100) {
-        return {
-            ok: false,
-            error: 'create_order in live mode requires regime_confidence as a number in [0, 100].',
-        };
-    }
-    if (!isScore(args.confluence_score)) {
-        return {
-            ok: false,
-            error: 'create_order in live mode requires confluence_score as a number in [0, 10]. ' +
-                'Heartbeat reassessment needs this to detect scorecard reversal.',
-        };
-    }
-    const validVerdicts = new Set(['STRONG_GO', 'GO', 'MARGINAL', 'NO_GO']);
-    if (!nonEmptyString(args.scorecard_verdict) || !validVerdicts.has(args.scorecard_verdict)) {
-        return {
-            ok: false,
-            error: `create_order in live mode requires scorecard_verdict in ${[...validVerdicts].join('/')}. ` +
-                "If you don't have a clear verdict, you don't have the setup — skip the trade.",
-        };
-    }
-    // Pinned plan — validate-if-present only (NOT required yet; we add the
-    // capability + indication first, per the 2026-06-05 governing principle).
-    if (args.invalidation_price != null &&
-        (typeof args.invalidation_price !== 'number' ||
-            !Number.isFinite(args.invalidation_price) ||
-            args.invalidation_price <= 0)) {
-        return {
-            ok: false,
-            error: 'create_order: invalidation_price, if provided, must be a positive number — ' +
-                'the price at which the entry thesis is wrong (your pinned "I am wrong here" level).',
-        };
-    }
-    return { ok: true };
-}
-const REALIZATION_RULE_TYPES = new Set(['fixed_target', 'trail', 'scale', 'manual']);
-/** Coerce the agent-supplied `realization_rule` (snake_case from the tool
- *  schema) into a clean RealizationRule, dropping garbage. Permissive by
- *  design — this is the agent's stated PLAN (indication), not an enforced
- *  mechanic, so we keep whatever is well-formed and default an unknown `type`
- *  to 'manual' rather than rejecting. Returns undefined for non-objects. */
-export function sanitizeRealizationRule(raw) {
-    if (!raw || typeof raw !== 'object')
-        return undefined;
-    const r = raw;
-    const fin = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
-    const type = typeof r.type === 'string' && REALIZATION_RULE_TYPES.has(r.type)
-        ? r.type
-        : 'manual';
-    const out = { type };
-    const tp = fin(r.target_price);
-    if (tp != null && tp > 0)
-        out.targetPrice = tp;
-    const ta = fin(r.trail_after_r);
-    if (ta != null)
-        out.trailAfterR = ta;
-    const td = fin(r.trail_distance_r);
-    if (td != null && td > 0)
-        out.trailDistanceR = td;
-    if (Array.isArray(r.scale)) {
-        const rungs = [];
-        for (const s of r.scale) {
-            if (!s || typeof s !== 'object')
-                continue;
-            const o = s;
-            const atR = fin(o.at_r);
-            const fraction = fin(o.fraction);
-            if (atR == null || fraction == null || fraction <= 0 || fraction > 1)
-                continue;
-            rungs.push({ atR, fraction });
-            if (rungs.length >= 6)
-                break;
-        }
-        if (rungs.length > 0)
-            out.scale = rungs;
-    }
-    if (typeof r.note === 'string' && r.note.trim().length > 0) {
-        out.note = r.note.slice(0, 200);
-    }
-    return out;
-}
-// ---- record_position_reviews (Position Decision Journal) ----
-/** Verdicts the agent can file at heartbeat for an open position. `trim` is
- *  intentionally absent until `partial_close` exists as a real action — see
- *  POSITION_DECISION_JOURNAL_PLAN.md §3 redirect #4. */
-export const REVIEW_VERDICTS = ['hold', 'add_on', 'close_recommended'];
-export const THESIS_STATUSES = ['intact', 'weakening', 'invalidated', 'evolving'];
-/** Validate a `record_position_reviews` call. Per-review rules from
- *  POSITION_REVIEW_PLAN.md §7.2 plus a top-level superset rule when the caller
- *  passes the open-positions snapshot.
- *
- *  Returns either {ok:true} (proceed) or {ok:false, error} (reject the whole
- *  call — partial-success would corrupt the audit trail).
- */
-export function validatePositionReviews(args, ctx) {
-    if (!Array.isArray(args.reviews)) {
-        return { ok: false, error: 'reviews must be an array' };
-    }
-    if (args.reviews.length === 0) {
-        return { ok: false, error: 'reviews must contain at least one entry' };
-    }
-    const seen = new Set();
-    for (let i = 0; i < args.reviews.length; i++) {
-        const r = args.reviews[i];
-        const where = `reviews[${i}]`;
-        if (!nonEmptyString(r.symbol)) {
-            return { ok: false, error: `${where}: symbol required` };
-        }
-        const symbol = r.symbol;
-        if (seen.has(symbol)) {
-            return { ok: false, error: `${where}: duplicate symbol '${symbol}' — one review per position per call` };
-        }
-        seen.add(symbol);
-        if (typeof r.position_open_at !== 'number' || !Number.isFinite(r.position_open_at) || r.position_open_at <= 0) {
-            return { ok: false, error: `${where}: position_open_at required (positive epoch ms)` };
-        }
-        if (!REVIEW_VERDICTS.includes(r.verdict)) {
-            return {
-                ok: false,
-                error: `${where}: verdict must be one of: ${REVIEW_VERDICTS.join(', ')}`,
-            };
-        }
-        const verdict = r.verdict;
-        if (!THESIS_STATUSES.includes(r.thesis_status)) {
-            return {
-                ok: false,
-                error: `${where}: thesis_status must be one of: ${THESIS_STATUSES.join(', ')}`,
-            };
-        }
-        const thesisStatus = r.thesis_status;
-        // Rule 1 — verdict='hold' AND thesis_status='invalidated' is a logical contradiction.
-        if (verdict === 'hold' && thesisStatus === 'invalidated') {
-            return {
-                ok: false,
-                error: `${where}: verdict='hold' contradicts thesis_status='invalidated'. If thesis is invalidated, file verdict='close_recommended' or call close_position.`,
-            };
-        }
-        // Numeric required fields.
-        if (!isFiniteNumber(r.entry_score))
-            return { ok: false, error: `${where}: entry_score required (number)` };
-        if (!isFiniteNumber(r.current_score))
-            return { ok: false, error: `${where}: current_score required (number)` };
-        if (!isFiniteNumber(r.score_delta))
-            return { ok: false, error: `${where}: score_delta required (number)` };
-        // Rule 3 — internal consistency between scores and delta (float tolerance).
-        const computedDelta = r.current_score - r.entry_score;
-        if (Math.abs(computedDelta - r.score_delta) > 0.01) {
-            return {
-                ok: false,
-                error: `${where}: score_delta=${r.score_delta} inconsistent with current_score=${r.current_score} - entry_score=${r.entry_score} = ${computedDelta.toFixed(3)}`,
-            };
-        }
-        if (!isFiniteNumber(r.regime_confidence) || r.regime_confidence < 0 || r.regime_confidence > 1) {
-            return { ok: false, error: `${where}: regime_confidence required in [0, 1]` };
-        }
-        if (!isFiniteNumber(r.r_multiple))
-            return { ok: false, error: `${where}: r_multiple required` };
-        if (!isFiniteNumber(r.distance_to_stop_bps))
-            return { ok: false, error: `${where}: distance_to_stop_bps required` };
-        if (!isFiniteNumber(r.time_in_position_minutes) || r.time_in_position_minutes < 0) {
-            return { ok: false, error: `${where}: time_in_position_minutes required (non-negative)` };
-        }
-        if (!isFiniteNumber(r.mfe_r))
-            return { ok: false, error: `${where}: mfe_r required` };
-        if (!isFiniteNumber(r.give_back_pct))
-            return { ok: false, error: `${where}: give_back_pct required` };
-        // Rule 5 — r_multiple cannot exceed mfe_r (mfe_r is by definition the max
-        // favourable R seen since entry).
-        if (r.r_multiple > r.mfe_r + 0.01) {
-            return {
-                ok: false,
-                error: `${where}: r_multiple=${r.r_multiple} > mfe_r=${r.mfe_r} is impossible (MFE is the running max).`,
-            };
-        }
-        if (!nonEmptyString(r.regime_entry))
-            return { ok: false, error: `${where}: regime_entry required` };
-        if (!nonEmptyString(r.regime_current))
-            return { ok: false, error: `${where}: regime_current required` };
-        if (!r.confluence_components || typeof r.confluence_components !== 'object' || Array.isArray(r.confluence_components)) {
-            return {
-                ok: false,
-                error: `${where}: confluence_components required (named-boolean object). ` +
-                    `Example: {regime: true, structure: true, momentum: false, flow: true}. ` +
-                    `One key per scorecard gate firing or not firing NOW.`,
-            };
-        }
-        // Rule 4 — what_changed minimum length. Fuzzy-match-against-prior-reviews
-        // is a server-side concern (the validator doesn't have history); enforce
-        // length only here.
-        if (!nonEmptyString(r.what_changed) || r.what_changed.length < 20) {
-            return { ok: false, error: `${where}: what_changed required (≥20 chars describing what shifted since last review)` };
-        }
-        if (!nonEmptyString(r.invalidation_trigger)) {
-            return { ok: false, error: `${where}: invalidation_trigger required (the price/event/time that flips this to CLOSE)` };
-        }
-        // Rule 2 — verdict='add_on' requires +0.5R AND +1.5 score delta vs entry.
-        // Already-prose rule from SKILL.md v2.9; now mechanical.
-        if (verdict === 'add_on') {
-            const r1 = r.r_multiple;
-            const dScore = r.current_score - r.entry_score;
-            if (r1 < 0.5 || dScore < 1.5) {
-                return {
-                    ok: false,
-                    error: `${where}: verdict='add_on' requires r_multiple ≥ +0.5 AND score_delta ≥ +1.5. Got r_multiple=${r1.toFixed(2)}, score_delta=${dScore.toFixed(2)}. Either HOLD this position or wait for confirmation.`,
-                };
-            }
-        }
-    }
-    // Top-level superset rule — every open position must have a review when
-    // gate-mode is 'enforce'. Soft warning at lower modes happens at the call
-    // site, not here.
-    //
-    // Symbol form caveat: Binance live `getPositions()` returns settle-suffixed
-    // unified symbols ('SOL/USDT:USDT'), while the state-store + agent-side
-    // reviews use the canonical 'SOL/USDT'. Normalize BOTH sides — the call site
-    // normalizes openSymbols defensively too, but doing it here as well makes
-    // the validator robust against any caller that forwards raw forms.
-    if (ctx?.openSymbols && ctx.gateMode === 'enforce') {
-        const reviewedSymbols = new Set();
-        for (const r of args.reviews) {
-            if (typeof r.symbol === 'string')
-                reviewedSymbols.add(normalizeBracketSymbol(r.symbol));
-        }
-        const missing = [];
-        for (const s of ctx.openSymbols) {
-            if (!reviewedSymbols.has(normalizeBracketSymbol(s)))
-                missing.push(s);
-        }
-        if (missing.length > 0) {
-            return {
-                ok: false,
-                error: `record_position_reviews missing reviews for open positions: ${missing.join(', ')}. Pass one entry per open position.`,
-            };
-        }
-    }
-    return { ok: true };
-}
-function isFiniteNumber(v) {
-    return typeof v === 'number' && Number.isFinite(v);
-}

package/assets/plugin/tools/attach-brackets.d.ts

@@ -1,39 +0,0 @@
-import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
-import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
-interface AttachBracketsArgs {
-    symbol: string;
-    stop_price?: number;
-    target_price?: number;
-}
-interface AttachBracketsSuccess {
-    ok: true;
-    symbol: string;
-    bracket_id: string;
-    entry_side: 'buy' | 'sell';
-    stop_price?: number;
-    target_price?: number;
-    sl_cid?: string;
-    tp_cid?: string;
-    attach_latency_ms: number;
-    cancelled_stale_bracket_orders: number;
-    cleared_stale_ledger_row: boolean;
-    attempts: number;
-    /** True when the call short-circuited because the requested protection
-     *  is already live on the exchange with matching prices — no new orders
-     *  were placed. Set by the 2026-05-15 idempotency change so the agent's
-     *  defensive re-attach loop doesn't tear down and reattach a working
-     *  bracket pair, which is what produced the audit→reattach spiral.
-     */
-    idempotent_no_op?: boolean;
-    note?: string;
-}
-interface AttachBracketsDeps {
-    adapter: IExchangeAdapter;
-    operationLock?: TradingOperationLock;
-    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
-}
-export declare function attachBracketsTool(args: AttachBracketsArgs, deps: AttachBracketsDeps): Promise<AttachBracketsSuccess | {
-    error: string;
-}>;
-export {};