dexterm-cli 0.2.0 → 0.2.1

package/dist/packages/autotrade/src/strategy-stats.js

@@ -0,0 +1,344 @@
+// dexterm autotrade — STRATEGY STATS for the performance dashboard (task-1749). Read-only over the run ledgers
+// ($DEXTERM_HOME/autotrade/runs/*.jsonl): no network, no model, no key, never writes.
+//
+// The definitions are the challenge control's (launch/send-out/challenge-100x/control/report.mjs + mine.mjs, task-1697 /
+// task-1733), so the dashboard and the control report count the same things the same way:
+//   entries   each position once across restarts (its first fill or adoption), keyed per run FILE + engine id
+//   closed    `trade_closed` (deduped) + WRITE-OFFS: a position the engine marked `stuck` (no pool to sell into) with no
+//             sell for >= 30 min, or dropped stuck at a clean run end, closes at its REALIZABLE value: the sells it made
+//             are kept, the unsold remainder counts 0. Derived here; the engine's ledgers are never edited.
+//   abandoned still open when a run ended cleanly and not stuck: the engine does not carry it, its outcome never enters
+//             the closed sample
+//   rugs      a closed position at <= -80% on cost (a write-off is a rug only at <= -80%)
+//   mean      mean % on cost with a 95% seeded percentile bootstrap (4000 resamples, seed 7); a difference of two
+//             strategies is a bootstrap of independent groups (seed 11); rates use the Wilson 95% interval
+//   sample    under 20 closed is EXPLORATORY; the ETA to 20 closed = (20 - closed) / entries per day since the first event
+// One difference from report.mjs (a fix, test/strategy-stats-1749.test.ts): the engine's crash recovery names an adopted
+// position `<runId>/pN` while that run's own fills said `pN`; report.mjs keys `pN` and so counted an adopted position
+// two or three times. Here `<runId>/pN` maps onto the position `pN` of the file `<runId>.jsonl`.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const RUG_PCT = -80;
+export const MIN_CLOSED = 20;
+export const STUCK_WRITE_OFF_MIN = 30;
+const DAY = 86_400_000;
+/** mulberry32: the seeded generator of control/mine.mjs (same seed, same intervals). */
+export function rng(seed = 7) {
+    let a = seed >>> 0;
+    return () => { a = (a + 0x6d2b79f5) >>> 0; let t = a; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+const mean = (xs) => xs.reduce((s, x) => s + x, 0) / xs.length;
+const pctile = (xs, p) => { const s = [...xs].sort((a, b) => a - b); return s[Math.min(s.length - 1, Math.max(0, Math.floor(p * s.length)))]; };
+/** Mean with a 95% percentile-bootstrap interval (control/mine.mjs meanCi). */
+export function meanCi(xs, { B = 4000, seed = 7 } = {}) {
+    if (!xs.length)
+        return { n: 0, mean: null, lo: null, hi: null };
+    const r = rng(seed);
+    const ms = [];
+    for (let b = 0; b < B; b++) {
+        let s = 0;
+        for (let i = 0; i < xs.length; i++)
+            s += xs[Math.floor(r() * xs.length)];
+        ms.push(s / xs.length);
+    }
+    return { n: xs.length, mean: mean(xs), lo: pctile(ms, 0.025), hi: pctile(ms, 0.975) };
+}
+/** Difference of means (a - b), independent groups, bootstrap 95% (control/mine.mjs diffCi). */
+export function diffCi(a, b, { B = 4000, seed = 11 } = {}) {
+    if (!a.length || !b.length)
+        return { mean: null, lo: null, hi: null };
+    const r = rng(seed);
+    const ds = [];
+    for (let k = 0; k < B; k++) {
+        let sa = 0, sb = 0;
+        for (let i = 0; i < a.length; i++)
+            sa += a[Math.floor(r() * a.length)];
+        for (let i = 0; i < b.length; i++)
+            sb += b[Math.floor(r() * b.length)];
+        ds.push(sa / a.length - sb / b.length);
+    }
+    return { mean: mean(a) - mean(b), lo: pctile(ds, 0.025), hi: pctile(ds, 0.975) };
+}
+/** Wilson 95% interval for k of n, as fractions (control/mine.mjs wilson). */
+export function wilsonCi(k, n) {
+    if (!n)
+        return [null, null];
+    const z = 1.96, p = k / n, d = 1 + z * z / n, c = p + z * z / (2 * n), h = z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n));
+    return [Math.max(0, (c - h) / d), Math.min(1, (c + h) / d)];
+}
+/**
+ * Every strategy (fleet member) in one runs directory, its positions tracked across run files (control/report.mjs
+ * readMembers, rules in the header). `now` decides which stuck positions are already written off.
+ */
+export function readStrategyLedgers(runsDir, { now = Date.now(), writeOffMin = STUCK_WRITE_OFF_MIN } = {}) {
+    const M = {};
+    if (!existsSync(runsDir))
+        return M;
+    const symbols = new Map(); // mint -> symbol, from the candidate lines (fills carry no symbol)
+    const entryTick = new Map(); // mint -> the candidate tick that preceded the entry (pool age, liquidity, mcap)
+    const state = {};
+    const fin = (x) => typeof x === 'number' && Number.isFinite(x);
+    for (const f of readdirSync(runsDir).filter((x) => x.endsWith('.jsonl') && !/-fleet-/.test(x)).sort()) {
+        let member = null;
+        let text;
+        try {
+            text = readFileSync(join(runsDir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line)
+                continue;
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (e.kind === 'fleet_member' || e.kind === 'run_start') {
+                member ??= e.member ?? e.strategy ?? null;
+                if (member && !M[member]) {
+                    M[member] = { files: 0, entries: 0, closed: [], open: 0, stuckOpen: [], openPositions: [], abandoned: [], writtenOff: [], adopted: 0, lastClampT: null, firstT: null, lastT: null, candidates: 0, entryTimes: [], startUsd: null, mode: null, basedOn: null };
+                    state[member] = { pos: new Map(), openNow: new Set(), closedKeys: new Set(), local: new Map(), file: null, carry: new Set() };
+                }
+                if (member) {
+                    const m = M[member];
+                    if (fin(e.bankroll?.usd) && m.startUsd === null)
+                        m.startUsd = e.bankroll.usd;
+                    m.mode ??= e.mode ?? null;
+                    if (e.basedOn)
+                        m.basedOn = e.basedOn;
+                    if (state[member].file !== f) {
+                        state[member].file = f;
+                        state[member].local = new Map();
+                        state[member].carry = new Set(state[member].openNow);
+                        m.files++;
+                    }
+                }
+                continue;
+            }
+            if (!member)
+                continue;
+            const m = M[member];
+            const s = state[member];
+            if (typeof e.t === 'number') {
+                m.firstT = m.firstT === null ? e.t : Math.min(m.firstT, e.t);
+                m.lastT = m.lastT === null ? e.t : Math.max(m.lastT, e.t);
+            }
+            // a restart adopts what it carries at the head of its file; a position of the previous (crashed) file it did not
+            // adopt is gone from the engine's book: "abandoned", not open forever
+            if (s.carry.size && e.kind !== 'position_adopted') {
+                for (const key of s.carry) {
+                    const p = s.pos.get(key);
+                    s.openNow.delete(key);
+                    m.abandoned.push({ positionId: p.positionId, mint: p.mint, openedT: p.firstT, stoppedT: e.t, notCarried: true, _p: p });
+                }
+                s.carry.clear();
+            }
+            if (e.kind === 'clamp' && typeof e.t === 'number')
+                m.lastClampT = Math.max(m.lastClampT ?? 0, e.t);
+            if (e.kind === 'candidate') {
+                m.candidates++;
+                if (e.mint && e.symbol)
+                    symbols.set(e.mint, e.symbol);
+                if (e.mint && e.tick)
+                    entryTick.set(e.mint, e.tick);
+                continue;
+            }
+            // the open position of an earlier file this id + mint carries (an adoption), newest first; `<runId>/pN` names the
+            // position pN of the file <runId>.jsonl exactly
+            const carried = (id, mint) => {
+                const slash = id.lastIndexOf('/');
+                if (slash > 0) {
+                    const k = `${id.slice(0, slash)}.jsonl#${id.slice(slash + 1)}`;
+                    if (s.pos.has(k) && !s.closedKeys.has(k))
+                        return k;
+                }
+                return [...s.openNow].reverse().find((k) => { const p = s.pos.get(k); return p.positionId === id && (!mint || !p.mint || p.mint === mint); }) ?? null;
+            };
+            const open = (id, mint, t, profile = null) => {
+                const key = `${f}#${id}`;
+                s.pos.set(key, { key, positionId: id, mint: mint ?? null, symbol: null, firstT: t, costUsd: 0, proceedsUsd: 0, stuckSince: null, stuckWhy: null, lastSellT: null, profile });
+                s.openNow.add(key);
+                s.local.set(id, key);
+                m.entries++;
+                if (t !== null)
+                    m.entryTimes.push(t);
+                return key;
+            };
+            const keyOf = (id, mint, t, { create = true, profile = null } = {}) => {
+                if (s.local.has(id))
+                    return s.local.get(id);
+                const c = carried(id, mint);
+                if (c) {
+                    s.local.set(id, c);
+                    return c;
+                }
+                return create ? open(id, mint, t, profile) : null;
+            };
+            if (e.kind === 'position_adopted' && e.positionId) {
+                const c = carried(e.positionId, e.mint);
+                const key = c ?? open(e.positionId, e.mint, e.position?.openedAt ?? e.t); // its fills were in a file that is gone: it counts here
+                s.carry.delete(key);
+                s.local.set(e.positionId, key);
+                m.adopted++;
+                const p = s.pos.get(key);
+                const snap = e.position ?? {};
+                if (!c && fin(snap.costUsd))
+                    p.costUsd = snap.costUsd;
+                if (snap.stuck && p.stuckSince === null)
+                    p.stuckSince = e.t;
+                p.symbol ??= e.symbol ?? null;
+                continue;
+            }
+            if (e.kind === 'fill' && e.positionId) {
+                const key = keyOf(e.positionId, e.mint, e.t, { profile: e.profile ?? null });
+                if (s.closedKeys.has(key))
+                    continue;
+                const p = s.pos.get(key);
+                p.profile ??= e.profile ?? null;
+                if (e.side === 'sell') {
+                    p.proceedsUsd += fin(e.usd) ? e.usd : 0;
+                    p.lastSellT = e.t;
+                    p.stuckSince = null;
+                    p.stuckWhy = null;
+                } // a sale ends a stuck spell
+                else
+                    p.costUsd += fin(e.usd) ? e.usd : 0;
+                continue;
+            }
+            if (e.kind === 'stuck' && e.positionId) {
+                const key = keyOf(e.positionId, e.mint, e.t, { create: false });
+                const p = key && s.pos.get(key);
+                if (p && p.stuckSince === null) {
+                    p.stuckSince = e.t;
+                    p.stuckWhy = `${e.reason ?? 'stuck'} (${e.why ?? 'cannot sell'})`;
+                }
+                continue;
+            }
+            if (e.kind === 'wake' && e.positionId && e.event === 'mechanical_exit') { // the engine's own words for the stuck exit
+                const key = s.local.get(e.positionId);
+                const p = key && s.pos.get(key);
+                if (p && p.stuckSince === e.t && e.detail)
+                    p.stuckWhy = e.detail;
+                continue;
+            }
+            if (e.kind === 'trade_closed' && e.trade) {
+                const key = keyOf(e.trade.id, e.trade.mint, e.trade.openedAt ?? e.t);
+                if (s.closedKeys.has(key))
+                    continue;
+                s.closedKeys.add(key);
+                s.openNow.delete(key);
+                const p = s.pos.get(key);
+                const tick = e.trade.mint ? entryTick.get(e.trade.mint) : undefined;
+                m.closed.push({ t: e.trade.closedAt ?? e.t, openedAt: e.trade.openedAt ?? null, mint: e.trade.mint ?? null, symbol: e.trade.symbol ?? null, pnlPct: e.trade.pnlPct, pnlUsd: e.trade.pnlUsd ?? null,
+                    costUsd: fin(e.trade.costUsd) ? e.trade.costUsd : p?.costUsd ?? null, exitReason: e.trade.exitReason ?? null, stuck: !!e.trade.stuck, profile: e.trade.profileId ?? p?.profile ?? null,
+                    entryAgeMin: fin(tick?.ageMin) ? tick.ageMin : null, entryLiqUsd: fin(tick?.liq) ? tick.liq : null, entryMcap: fin(tick?.mcap) ? tick.mcap : null });
+                continue;
+            }
+            if (e.kind === 'run_end') {
+                for (const key of s.openNow) {
+                    const p = s.pos.get(key);
+                    m.abandoned.push({ positionId: p.positionId, mint: p.mint, openedT: p.firstT, stoppedT: e.t, _p: p });
+                }
+                s.openNow.clear();
+            }
+        }
+    }
+    const writeOff = (m, p, endT, how) => {
+        const pnlUsd = Math.round((p.proceedsUsd - p.costUsd) * 1e4) / 1e4;
+        const pnlPct = p.costUsd > 0 ? Math.round((pnlUsd / p.costUsd) * 1e4) / 100 : null;
+        const tick = p.mint ? entryTick.get(p.mint) : undefined;
+        const w = { t: p.stuckSince, openedAt: p.firstT, mint: p.mint, symbol: p.symbol ?? (p.mint ? symbols.get(p.mint) ?? null : null), pnlPct, pnlUsd, costUsd: Math.round(p.costUsd * 1e4) / 1e4, realizedUsd: Math.round(p.proceedsUsd * 1e4) / 1e4,
+            exitReason: 'written-off', stuck: true, writtenOff: true, held: how === 'still held', profile: p.profile,
+            reason: `${how}: stuck ${Math.round((endT - p.stuckSince) / 60_000)} min with no sell (${p.stuckWhy ?? 'illiquid'}); unsold remainder valued 0`, stuckSince: p.stuckSince,
+            entryAgeMin: typeof tick?.ageMin === 'number' ? tick.ageMin : null, entryLiqUsd: typeof tick?.liq === 'number' ? tick.liq : null, entryMcap: typeof tick?.mcap === 'number' ? tick.mcap : null };
+        m.writtenOff.push(w);
+        if (pnlPct !== null)
+            m.closed.push(w);
+    };
+    for (const [id, m] of Object.entries(M)) {
+        const s = state[id];
+        m.abandoned = m.abandoned.filter((a) => { const p = a._p; delete a._p; if (p.stuckSince === null)
+            return true; writeOff(m, p, a.stoppedT ?? now, a.notCarried ? 'dropped stuck (not carried over by the restart)' : 'dropped stuck at a clean run end'); return false; });
+        for (const key of s.openNow) {
+            const p = s.pos.get(key);
+            if (p.stuckSince !== null && now - p.stuckSince >= writeOffMin * 60_000)
+                writeOff(m, p, now, 'still held');
+            else {
+                m.open++;
+                m.openPositions.push({ positionId: p.positionId, mint: p.mint, symbol: p.symbol ?? (p.mint ? symbols.get(p.mint) ?? null : null), openedAt: p.firstT, costUsd: Math.round(p.costUsd * 1e4) / 1e4, realizedUsd: Math.round(p.proceedsUsd * 1e4) / 1e4, stuckSince: p.stuckSince, profile: p.profile });
+                if (p.stuckSince !== null)
+                    m.stuckOpen.push({ positionId: p.positionId, mint: p.mint, stuckSince: p.stuckSince });
+            }
+        }
+        for (const c of m.closed)
+            c.symbol ??= c.mint ? symbols.get(c.mint) ?? null : null;
+        m.closed.sort((a, b) => a.t - b.t);
+    }
+    return M;
+}
+/**
+ * REALIZABLE value of an open position (agent-v4/scoreboard.mjs): the engine's mark sold into the pool with the
+ * engine's cost model (constant-product impact on half the liquidity, fee + slippage bps, network fee). null = the
+ * pool's liquidity is unknown.
+ */
+export function realizableUsd(markUsd, liqUsd, ex = { feeBps: 30, slippageBps: 200, networkFeeUsd: 0.02 }) {
+    if (!Number.isFinite(markUsd) || typeof liqUsd !== 'number' || !Number.isFinite(liqUsd) || liqUsd <= 0)
+        return null;
+    const side = liqUsd / 2;
+    const impact = markUsd / (side + markUsd);
+    return Math.max(0, markUsd * (1 - impact) * (1 - (ex.feeBps + ex.slippageBps) / 10_000) - ex.networkFeeUsd);
+}
+/** The realized equity curve over the closed sample (start + cumulative P/L in close order) and its drawdown from the running peak. */
+export function equityCurve(closed, startUsd) {
+    const start = startUsd ?? 100;
+    let eq = start;
+    let peak = start;
+    let maxDd = 0;
+    const points = [];
+    for (const c of [...closed].sort((a, b) => a.t - b.t)) {
+        eq += typeof c.pnlUsd === 'number' && Number.isFinite(c.pnlUsd) ? c.pnlUsd : 0;
+        peak = Math.max(peak, eq);
+        const dd = peak > 0 ? (1 - eq / peak) * 100 : 0;
+        maxDd = Math.max(maxDd, dd);
+        points.push({ t: c.t, usd: Math.round(eq * 100) / 100, drawdownPct: Math.round(dd * 10) / 10 });
+    }
+    return { points, maxDrawdownPct: Math.round(maxDd * 10) / 10, start, end: Math.round(eq * 100) / 100 };
+}
+/** One strategy's row (control/report.mjs summarize: rugs, means, ETA), plus the exits breakdown and the sample badge. */
+export function strategyRow(id, m, { now = Date.now(), minClosed = MIN_CLOSED } = {}) {
+    const xs = m.closed.map((c) => c.pnlPct).filter((x) => typeof x === 'number' && Number.isFinite(x));
+    const rugs = m.closed.filter((c) => (c.pnlPct ?? 0) <= RUG_PCT || (c.stuck && !c.writtenOff)).length;
+    const days = m.firstT === null ? 0 : (now - m.firstT) / DAY;
+    const perDay = days > 0 ? m.entries / days : null;
+    const ci = meanCi(xs);
+    const by = new Map();
+    for (const c of m.closed) {
+        const r = c.writtenOff ? 'written-off' : c.exitReason ?? 'unknown';
+        if (!by.has(r))
+            by.set(r, []);
+        if (typeof c.pnlPct === 'number')
+            by.get(r).push(c.pnlPct);
+    }
+    const exits = [...by].map(([reason, v]) => ({ reason, n: v.length, meanPct: v.length ? Math.round(mean(v) * 10) / 10 : null, wins: v.filter((x) => x > 0).length })).sort((a, b) => b.n - a.n);
+    const sample = xs.length === 0 ? 'none' : xs.length < minClosed ? 'exploratory' : 'minimum';
+    return {
+        id, entries: m.entries, closed: xs.length, open: m.open, writtenOff: m.writtenOff.length, stuckOpen: m.stuckOpen.length, abandoned: m.abandoned.length, adopted: m.adopted,
+        wins: xs.filter((x) => x > 0).length, losses: xs.filter((x) => x <= 0).length, rugs, rugRate: xs.length ? rugs / xs.length : null, rugCi: wilsonCi(rugs, xs.length),
+        meanPct: ci.mean, lo: ci.lo, hi: ci.hi, days, entriesPerDay: perDay, etaDays: perDay ? Math.max(0, (minClosed - xs.length) / perDay) : null,
+        sample, sampleText: sample === 'none' ? 'no closed trades yet' : sample === 'exploratory' ? `exploratory: ${xs.length} closed, < ${minClosed}` : `${xs.length} closed (>= ${minClosed})`,
+        realizedUsd: Math.round(m.closed.reduce((s, c) => s + (typeof c.pnlUsd === 'number' ? c.pnlUsd : 0), 0) * 100) / 100, exits,
+    };
+}
+/** The decision rule the control applies to a variant (control/report.mjs DECISION_RULE, baseline named). */
+export const decisionRule = (base, minClosed = MIN_CLOSED) => `A filter or exit change is adopted only if it beats ${base} over >= ${minClosed} closed entries in BOTH strategies with the 95% interval of the difference in mean % per entry clear of zero (above 0). Until then nothing changes.`;
+/** A variant against the baseline (control/report.mjs verdicts). */
+export function compareToBase(id, a, base, b, minClosed = MIN_CLOSED) {
+    const d = diffCi(a, b);
+    const enough = a.length >= minClosed && b.length >= minClosed;
+    const verdict = !enough ? `not yet: ${a.length} / ${b.length} closed (needs ${minClosed} each)` : (d.lo ?? 0) > 0 ? 'passes the rule: beats the baseline' : (d.hi ?? 0) < 0 ? 'worse than the baseline' : 'no clear difference: keep running';
+    return { id, base, n: a.length, baseN: b.length, diff: d, enough, verdict };
+}

package/dist/packages/autotrade/src/strategy.js

@@ -72,6 +72,13 @@ export const SCHEMAS = {
                 youngVertical: nullable(obj({ maxAgeHours: num(0, 168), maxH1Pct: num(0, 100000) })),
                 unknownHolders: { type: 'string', enum: ['reject', 'allow'] },
                 larp: nullable(obj({ maxScore: num(0, 100), unknown: { type: 'string', enum: ['reject', 'allow'] } })),
+                rugproof: nullable(obj({
+                    minPoolAgeMin: num(0, 1440), requireSafePool: { type: 'boolean' }, maxHolderLpPct: num(0, 100), maxWithdraws: num(0, 100, true), withdrawScanTx: num(1, 100, true),
+                    liquidityRecheck: nullable(obj({ afterSec: num(5, 600), floorX: num(1, 100), maxDropPct: num(0, 90) })),
+                    routeX: nullable(num(1, 20)),
+                    youngPool: nullable(obj({ underMin: num(1, 1440), maxSizePct: num(1, 100) })),
+                    drainGuard: nullable(obj({ pollSec: num(2, 10), liqDropPct: num(5, 90), exitOnNoRoute: { type: 'boolean' }, minReserveSol: num(0, 1000) })),
+                })),
             }, ['maxTop10Pct', 'maxDevPct', 'requireNoMintAuthority', 'requireNoFreezeAuthority', 'maxMcapSplitX', 'youngVertical', 'unknownHolders']),
             triggers: { type: 'array', max: 8, items: 'trigger' },
             triggerMode: { type: 'string', enum: ['any', 'all'] },
@@ -103,7 +110,7 @@ export const SCHEMAS = {
             onTimeout: { type: 'string', enum: ['skip'] },
             respawnOnWake: { type: 'boolean' },
         }, ['model', 'maxSessions', 'budgetUsdPerSession', 'budgetUsdPerDay', 'maxTurns', 'deltaEverySec', 'decideWithinSec', 'sessionMaxMin', 'onTimeout']),
-        execution: obj({ slippageBps: num(0, 5000), feeBps: num(0, 1000), networkFeeUsd: num(0, 10), latencyMs: num(0, 120000), maxPriceImpactPct: num(0.1, 50), minExitLiquidityUsd: num(0, 1e7) }),
+        execution: obj({ slippageBps: num(0, 5000), feeBps: num(0, 1000), networkFeeUsd: num(0, 10), latencyMs: num(0, 120000), maxPriceImpactPct: num(0.1, 50), minExitLiquidityUsd: num(0, 1e7), stuckWriteOffMin: nullable(num(1, 10080)) }, ['slippageBps', 'feeBps', 'networkFeeUsd', 'latencyMs', 'maxPriceImpactPct', 'minExitLiquidityUsd']),
         notes: { type: 'array', max: 8, items: str(300) },
     }, ['kind', 'schema', 'id', 'name', 'version', 'description', 'mode', 'bankroll', 'entry', 'exits', 'sizing', 'risk', 'agent', 'execution']),
 };
@@ -200,6 +207,8 @@ export function validateStrategy(doc, library = builtinProfiles()) {
         errors.push({ path: '/risk/drawdown', msg: 'sizeDownAtPct must not exceed haltAtPct' });
     if (r.drawdown.recoverBelowPct >= r.drawdown.sizeDownAtPct)
         errors.push({ path: '/risk/drawdown/recoverBelowPct', msg: 'recoverBelowPct must be below sizeDownAtPct' });
+    if (s.execution.stuckWriteOffMin != null && s.mode !== 'paper')
+        errors.push({ path: '/execution/stuckWriteOffMin', msg: `the stuck write-off is paper only: in mode ${s.mode} the bag is still in your wallet and keeps its exit signals (remove it or set it to null)` });
     if (s.agent.budgetUsdPerSession > s.agent.budgetUsdPerDay)
         errors.push({ path: '/agent/budgetUsdPerSession', msg: 'a session budget above the daily budget' });
     if (s.entry.ageHours.max !== null && s.entry.ageHours.max < s.entry.ageHours.min)
@@ -211,6 +220,8 @@ export function validateStrategy(doc, library = builtinProfiles()) {
             warnings.push({ path: `/entry/triggers/${i}`, msg: `${t.kind} triggers need the live ${t.kind} feed; replays and backtests treat them as not firing` });
     if (s.bankroll.source === 'desk')
         warnings.push({ path: '/bankroll/source', msg: 'desk reads the paper desk book during a run; backtests use startUsd' });
+    if (s.entry.safety.rugproof)
+        warnings.push({ path: '/entry/safety/rugproof', msg: 'the rug-proof chain and route gates (pool structure, LP, withdraw history, sell route) and the drain poller need live data; a replay evaluates only the tick gates and the pump.fun-mint proxy' });
     if (s.entry.safety.larp)
         warnings.push({ path: '/entry/safety/larp', msg: 'the LARP gate needs the live web (live data runs only); replays and backtests do not evaluate it' });
     if (s.mode === 'real')

package/dist/packages/classifier/src/calibrate.js

@@ -0,0 +1,138 @@
+// Calibration + scoring metrics (task-1822). A decision model's own temperature is fitted on ITS training
+// distribution, not on memecoins, so dexterm can apply a local Platt map (p' = sigmoid(a * logit(p) + b)) fitted on
+// labelled rows of the user's / our own data. The fit is plain logistic regression on one feature (Newton steps,
+// a small ridge so a separable sample cannot run away). Metrics: AUROC (ties half), Brier, log-loss, ECE with
+// equal-width bins, reliability bins, precision at recall.
+const clamp = (p) => Math.min(1 - 1e-6, Math.max(1e-6, p));
+export const logit = (p) => { const q = clamp(p); return Math.log(q / (1 - q)); };
+export const sigmoid = (z) => 1 / (1 + Math.exp(-z));
+/** Fit p' = sigmoid(a * logit(p) + b) to binary labels. */
+export function fitPlatt(ps, ys, fittedOn, ridge = 1e-3) {
+    if (ps.length !== ys.length || ps.length < 2)
+        throw new Error('fitPlatt: need >= 2 paired rows');
+    let a = 1, b = 0;
+    const xs = ps.map(logit);
+    // Penalised negative log-likelihood (the ridge pulls a toward 1, i.e. toward "keep the model's own scale").
+    const nll = (a, b) => {
+        let s = (ridge / 2) * (a - 1) ** 2;
+        for (let i = 0; i < xs.length; i++) {
+            const z = a * xs[i] + b;
+            s += ys[i] ? Math.log1p(Math.exp(-z)) : Math.log1p(Math.exp(z));
+        }
+        return s;
+    };
+    let cur = nll(a, b);
+    for (let it = 0; it < 100; it++) {
+        let ga = ridge * (a - 1), gb = 0, haa = ridge, hab = 0, hbb = 1e-9;
+        for (let i = 0; i < xs.length; i++) {
+            const q = sigmoid(a * xs[i] + b), y = ys[i] ? 1 : 0, w = q * (1 - q);
+            ga += (q - y) * xs[i];
+            gb += q - y;
+            haa += w * xs[i] * xs[i];
+            hab += w * xs[i];
+            hbb += w;
+        }
+        const det = haa * hbb - hab * hab;
+        if (!(Math.abs(det) > 1e-12))
+            break;
+        const da = (hbb * ga - hab * gb) / det, db = (haa * gb - hab * ga) / det;
+        // Pure Newton can overshoot and diverge on logistic losses: halve the step until the loss goes down.
+        let t = 1, next = nll(a - da, b - db);
+        while (!(next <= cur) && t > 1e-6) {
+            t /= 2;
+            next = nll(a - t * da, b - t * db);
+        }
+        if (!(next <= cur))
+            break;
+        a -= t * da;
+        b -= t * db;
+        const gain = cur - next;
+        cur = next;
+        if (gain < 1e-12 || Math.abs(t * da) + Math.abs(t * db) < 1e-10)
+            break;
+    }
+    return { a, b, n: ps.length, fitted_on: fittedOn };
+}
+export function applyPlatt(p, m) { return sigmoid(m.a * logit(p) + m.b); }
+export function auroc(scores, ys) {
+    const idx = scores.map((s, i) => i).sort((i, j) => scores[i] - scores[j]);
+    let pos = 0, neg = 0, rankSum = 0;
+    // Average ranks over ties (Mann-Whitney U).
+    for (let i = 0; i < idx.length;) {
+        let j = i;
+        while (j + 1 < idx.length && scores[idx[j + 1]] === scores[idx[i]])
+            j++;
+        const r = (i + j) / 2 + 1;
+        for (let k = i; k <= j; k++)
+            if (ys[idx[k]])
+                rankSum += r;
+        i = j + 1;
+    }
+    for (const y of ys) {
+        if (y)
+            pos++;
+        else
+            neg++;
+    }
+    if (!pos || !neg)
+        return null;
+    return (rankSum - (pos * (pos + 1)) / 2) / (pos * neg);
+}
+export function brier(ps, ys) {
+    return ps.reduce((s, p, i) => s + (p - (ys[i] ? 1 : 0)) ** 2, 0) / ps.length;
+}
+export function logLoss(ps, ys) {
+    return -ps.reduce((s, p, i) => s + Math.log(ys[i] ? clamp(p) : 1 - clamp(p)), 0) / ps.length;
+}
+export function reliability(ps, ys, bins = 10) {
+    const out = [];
+    for (let b = 0; b < bins; b++) {
+        const lo = b / bins, hi = (b + 1) / bins;
+        let n = 0, sp = 0, sy = 0;
+        ps.forEach((p, i) => { if (p >= lo && (p < hi || (b === bins - 1 && p <= hi))) {
+            n++;
+            sp += p;
+            sy += ys[i] ? 1 : 0;
+        } });
+        out.push({ lo, hi, n, mean_p: n ? sp / n : NaN, rate: n ? sy / n : NaN });
+    }
+    return out;
+}
+export function ece(ps, ys, bins = 10) {
+    const N = ps.length;
+    return reliability(ps, ys, bins).reduce((s, b) => s + (b.n ? (b.n / N) * Math.abs(b.mean_p - b.rate) : 0), 0);
+}
+/** Best precision reachable at each recall target (threshold sweep over the scores). */
+export function precisionAtRecall(scores, ys, targets = [0.25, 0.5, 0.75, 0.9]) {
+    const order = scores.map((s, i) => i).sort((i, j) => scores[j] - scores[i]);
+    const P = ys.filter(Boolean).length;
+    const curve = [];
+    let tp = 0;
+    for (let k = 0; k < order.length; k++) {
+        if (ys[order[k]])
+            tp++;
+        if (k + 1 < order.length && scores[order[k + 1]] === scores[order[k]])
+            continue;
+        curve.push({ r: P ? tp / P : 0, p: tp / (k + 1), t: scores[order[k]] });
+    }
+    return targets.map((target) => {
+        const ok = curve.filter((c) => c.r >= target);
+        if (!ok.length)
+            return { recall: target, precision: null, threshold: null };
+        const best = ok.reduce((m, c) => (c.p > m.p ? c : m));
+        return { recall: target, precision: best.p, threshold: best.t };
+    });
+}
+/** F1 for one class given predicted labels. */
+export function f1(pred, truth, label) {
+    let tp = 0, fp = 0, fn = 0;
+    pred.forEach((p, i) => { if (p === label && truth[i] === label)
+        tp++;
+    else if (p === label)
+        fp++;
+    else if (truth[i] === label)
+        fn++; });
+    const precision = tp + fp ? tp / (tp + fp) : null, recall = tp + fn ? tp / (tp + fn) : null;
+    const f = precision !== null && recall !== null && precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : null;
+    return { precision, recall, f1: f, n: tp + fn };
+}

package/dist/packages/classifier/src/classify.js

@@ -0,0 +1,107 @@
+// The one entry point the app calls: firewall the dossier, ask the configured provider, apply a local calibration
+// map when one is configured for (model, question), fall back to the heuristic on failure, label the result.
+import { applyPlatt } from "./calibrate.js";
+import { prepareState } from "./dossier.js";
+import { heuristicProvider } from "./providers/heuristic.js";
+import { validateQuestionSet } from "./questions.js";
+import { finishAnswer } from "./systemone.js";
+import { ClassifierError } from "./types.js";
+export function calibrateAnswer(a, m) {
+    const mapped = {};
+    for (const [k, p] of Object.entries(a.probs))
+        mapped[k] = a.type === 'noul' && k === 'no' ? NaN : applyPlatt(p, m);
+    if (a.type === 'noul')
+        mapped.no = 1 - mapped.yes;
+    const out = finishAnswer(a.type, mapped);
+    return { ...out, raw_probs: a.probs };
+}
+export async function classify(provider, set, dossier, o = {}) {
+    validateQuestionSet(set);
+    const now = o.now ?? (() => performance.now());
+    const prepared = prepareState(dossier);
+    const t0 = now();
+    let used = provider;
+    let fallbackFrom;
+    let r;
+    try {
+        r = await provider.classify(set, prepared, { signal: o.signal });
+    }
+    catch (e) {
+        const fb = o.fallback === undefined ? heuristicProvider() : o.fallback;
+        if (!fb || fb.id === provider.id)
+            throw e;
+        fallbackFrom = { provider: provider.id, error: e instanceof ClassifierError ? `${e.code}: ${e.message}` : String(e.message ?? e) };
+        used = fb;
+        r = await fb.classify(set, prepared, { signal: o.signal });
+    }
+    const latency = now() - t0;
+    let calibration = r.calibration;
+    const answers = {};
+    for (const [qid, a] of Object.entries(r.answers)) {
+        const m = o.calibration?.[`${r.model}|${qid}`];
+        answers[qid] = m ? calibrateAnswer(a, m) : a;
+        if (m)
+            calibration = { kind: 'platt', note: `local Platt map fitted on ${m.fitted_on} (n ${m.n}); ${r.calibration.note}` };
+    }
+    return {
+        label: 'model-estimate',
+        provider: used.id,
+        model: r.model,
+        model_version: r.model_version,
+        question_set: set.id,
+        subject: dossier.subject,
+        answers,
+        latency_ms: Math.round(latency * 10) / 10,
+        usage: { input_tokens: r.input_tokens, cost_usd: r.cost_usd, cost_note: r.cost_note },
+        calibration,
+        injection_suspected: prepared.injection_suspected,
+        ...(fallbackFrom ? { fallback_from: fallbackFrom } : {}),
+    };
+}
+export async function classifyBatch(provider, set, dossiers, o = {}) {
+    const t0 = performance.now();
+    const results = new Array(dossiers.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < dossiers.length) {
+            const i = next++;
+            try {
+                results[i] = await classify(provider, set, dossiers[i], o);
+                o.onResult?.(results[i], i);
+            }
+            catch (e) {
+                results[i] = { subject: dossiers[i].subject, error: e.message };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(o.concurrency ?? 1, 16)) }, worker));
+    const out = { results, ms: Math.round(performance.now() - t0) };
+    if (o.triage) {
+        const t = { flag: [], pass: [], escalate: [] };
+        for (const r of results) {
+            if ('error' in r) {
+                t.escalate.push(r.subject);
+                continue;
+            }
+            const p = r.answers[o.triage.question]?.probs.yes;
+            if (p === undefined)
+                t.escalate.push(r.subject);
+            else if (p >= o.triage.hi)
+                t.flag.push(r.subject);
+            else if (p <= o.triage.lo)
+                t.pass.push(r.subject);
+            else
+                t.escalate.push(r.subject);
+        }
+        out.triage = t;
+    }
+    return out;
+}
+/** One-line human summary, always labelled an estimate with the model id. Never advice. */
+export function describeResult(r, question = 'drain_6h') {
+    const a = r.answers[question];
+    if (!a)
+        return `${r.model}: no answer for ${question}`;
+    const v = a.type === 'noul' ? `p(yes) ${a.probs.yes.toFixed(2)}` : `${a.top} ${a.probs[a.top].toFixed(2)}`;
+    return `model estimate (${r.provider} ${r.model}, ${r.calibration.kind === 'platt' ? 'locally calibrated' : 'not calibrated on memecoins'}): ${question} ${v}${r.fallback_from ? ` [fallback from ${r.fallback_from.provider}]` : ''}`;
+}