dexterm-cli 0.2.0 → 0.2.2

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

@@ -13,6 +13,7 @@ import { readFileSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { validate } from '../../custom/src/index.js';
 import { parseFilter } from "../../cli/src/screener/filter.js";
+import { TIER_TABLE_IDS, TIERS_VERDICT, tierTable, tierTableLines } from "./tiers.js";
 export const STRATEGY_SCHEMA = 'dexterm-strategy/1';
 export const EXIT_PROFILE_VERSION = '1.2.0';
 // ───────────────────────────── schema ─────────────────────────────
@@ -72,6 +73,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'] },
@@ -85,6 +93,7 @@ export const SCHEMAS = {
             confidence: obj({ minPct: num(0.1, 25), maxPct: num(0.1, 25), default: num(0, 1) }),
             ladder: { type: 'array', max: 4, items: obj({ frac: num(0.05, 1), atPct: num(-90, 1000), withinMin: num(1, 1440) }) },
             maxPctOfBankroll: num(0.1, 25), maxUsd: num(1, 1e6), minUsd: num(0.01, 1e6),
+            tiers: nullable(obj({ table: { type: 'string', enum: TIER_TABLE_IDS }, experimental: { type: 'string', enum: ['paper-only'] }, oneOpen: { type: 'boolean' } }, ['table', 'experimental'])),
         }, ['mode', 'maxPctOfBankroll', 'maxUsd', 'minUsd']),
         risk: obj({
             perTrade: obj({ maxLossPctOfBankroll: num(0.1, 25), assumedLossPctNoStop: num(10, 100) }),
@@ -103,7 +112,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 +209,23 @@ 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 (z.tiers) {
+        // 0.2.2: EXPERIMENTAL confidence tiers are PAPER ONLY (the runner and the engine refuse them outside paper too).
+        if (s.mode !== 'paper')
+            errors.push({ path: '/sizing/tiers', msg: `confidence tiers are EXPERIMENTAL and PAPER ONLY: refused in mode ${s.mode} (remove sizing.tiers or set it to null)` });
+        const tt = tierTable(z.tiers.table);
+        const rp = s.entry.safety.rugproof;
+        if (!rp || rp.minPoolAgeMin < tt.gates.minPoolAgeMin)
+            errors.push({ path: '/entry/safety/rugproof', msg: `confidence tiers need the rug-proof block with minPoolAgeMin ${tt.gates.minPoolAgeMin} or more (the pool age gate of table ${tt.id}; the tick alone cannot tell a pool's age)` });
+        warnings.push({ path: '/sizing/tiers', msg: TIERS_VERDICT });
+        for (const line of tierTableLines(tt).slice(1))
+            warnings.push({ path: '/sizing/tiers', msg: line });
+        warnings.push({ path: '/sizing/tiers', msg: `the tier's size replaces the size of sizing mode ${z.mode}; every limit still applies and the stricter wins (sizing.maxPctOfBankroll ${z.maxPctOfBankroll}%, maxUsd $${z.maxUsd}, the profile's max %, per-trade loss, exposure, cash, price impact, drawdown size-down)${z.tiers.oneOpen === false ? '' : '; one open position at a time'}; tier gates: liquidity >= $${tt.gates.minLiqUsd}, pool age >= ${tt.gates.minPoolAgeMin} min, not young and vertical` });
+        if (z.ladder)
+            warnings.push({ path: '/sizing/ladder', msg: 'with confidence tiers the ladder splits the tier size into tranches (the first fills at entry)' });
+    }
     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 +237,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/autotrade/src/tiers.js

@@ -0,0 +1,194 @@
+// dexterm autotrade — confidence-tiered sizing, EXPERIMENTAL, UNPROVEN and PAPER ONLY (0.2.2, from the rules v4 research).
+//
+// A strategy opts in with `sizing.tiers` (strategy.ts). The ENGINE (clampEntry) then scores every candidate tick on
+// two measured points, maps the score to a tier and the tier to a size in % of the book. Nothing here reads the
+// agent's own confidence: the research found no held-out signal in it. The rules, all enforced in the engine:
+//   - T0 (score 0, or a failed tier gate) is a skip: no entry.
+//   - No tier runs above 25% of the book (TIERS_HARD_CAP_PCT). The cap is code: the table's evidence or cap fields,
+//     the strategy file and the agent cannot lift it, and the engine applies it again on the dollar size and on every
+//     ladder add. No tier is proven, so a tier configured above 25% is recorded as capped.
+//   - The tick must be fresh and listed: a sweep row, a tick time that is not a number, or a tick older than 5 min at
+//     decision time (the bs5m window) is T0.
+//   - The tier's size is the strategy's pick; every existing ceiling (strategy and profile max %, max $, per-trade loss,
+//     exposure, cash, price impact, drawdown size-down, a young-pool cap) still applies, and the stricter one wins.
+//   - One open position at a time unless the block says otherwise.
+// Refused outside paper: validateStrategy (mode real / live), the runner (a real-signal run) and the engine itself.
+//
+// The verdict, shown on every TIER line and in validation: unproven; on the held-out data no tier made money, and no
+// dexterm strategy has shown an edge (strategy synthesis, 2026-11).
+//
+// Pure: no I/O.
+export const TIER_TABLE_IDS = ['v4-1785'];
+/** The one verdict line. Printed by validation and on every TIER line. */
+export const TIERS_VERDICT = 'EXPERIMENTAL, UNPROVEN, PAPER ONLY: on our held-out data no tier made money and no dexterm strategy has shown an edge; every tier runs at 25% of the book at most.';
+/** The engine's ceiling for any tier, in % of the book. Code, not data: nothing a strategy file or table says lifts it. */
+export const TIERS_HARD_CAP_PCT = 25;
+/** A tick older than this at decision time is T0: bs5m describes a 5 min window that has moved on. */
+export const TIER_TICK_MAX_AGE_MS = 5 * 60_000;
+const freeze = (x) => {
+    if (x && typeof x === 'object') {
+        for (const v of Object.values(x))
+            freeze(v);
+        Object.freeze(x);
+    }
+    return x;
+};
+/**
+ * The frozen v4 table (schema dexterm-challenge-tiers/1, version 4.0.0), as data. The points were fitted on TRAIN only;
+ * the held-out set was scored once. Changing a number here is a new table id, never an edit.
+ */
+export const CONFIDENCE_TIERS_V4 = freeze({
+    id: 'v4-1785',
+    provenance: 'task-1785 rules v4 research (family strict): frozen 2026-10-28T03:17:49Z, held-out scored once 2026-10-28T03:18:28Z',
+    unprovenCapPct: 25,
+    reservePct: 2,
+    points: [
+        { id: 'turnover1h-max', signal: 'turnover1h', op: '<=', value: 9.878, what: '1 h volume / liquidity' },
+        { id: 'bs5m-min', signal: 'bs5m', op: '>=', value: 3.714, what: 'buys / sells, 5 min' },
+    ],
+    tiers: [
+        { id: 'T0', minScore: 0, sizePct: 0, evidence: 'skip', heldOut: { n: 19, meanPct: -17.0, loPct: -35.7, hiPct: 3.4, wins: 5, rugs: 2 } },
+        { id: 'T1', minScore: 1, sizePct: 15, evidence: 'n/a', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+        { id: 'T2', minScore: 1, sizePct: 50, evidence: 'unproven', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+        { id: 'T3', minScore: 1, sizePct: 75, evidence: 'unproven', heldOut: { n: 17, meanPct: -7.6, loPct: -31.8, hiPct: 16.8, wins: 5, rugs: 1 } },
+        { id: 'T4', minScore: 2, sizePct: 100, evidence: 'unproven', heldOut: { n: 0, meanPct: null, loPct: null, hiPct: null, wins: null, rugs: null } },
+    ],
+    gates: { minPoolAgeMin: 10, minLiqUsd: 30_000, youngVertical: { maxAgeHours: 2, maxH1Pct: 150 } },
+});
+export function tierTable(id) {
+    if (id === 'v4-1785')
+        return CONFIDENCE_TIERS_V4;
+    throw new Error(`unknown tier table ${String(id)}`);
+}
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+/** Liquidity, volume and trade counts are never negative: a negative or non-finite figure is unknown. */
+const nonneg = (x) => { const v = fin(x); return v !== null && v >= 0 ? v : null; };
+/**
+ * The research's feature definitions, on one tick:
+ *   turnover1h = vol1h / liquidity (unknown when liquidity is not > 0 or vol1h is unknown)
+ *   bs5m       = buys5m / sells5m; no sells with buys = 99 (all buys); no buys and no sells = 0
+ * One difference, on the safe side: the research tape counted a missing sells figure as 0 (so buys alone gave 99);
+ * here a missing buys or sells figure makes bs5m unknown, and an unknown signal never scores its point. A negative or
+ * non-finite figure (NaN, Infinity) is unknown too.
+ */
+export function tierSignals(k) {
+    const liq = nonneg(k.liq);
+    const vol1h = nonneg(k.vol1h);
+    const b = nonneg(k.buys5m);
+    const s = nonneg(k.sells5m);
+    const turnover1h = liq !== null && liq > 0 && vol1h !== null ? vol1h / liq : null;
+    const bs5m = b === null || s === null ? null : s > 0 ? b / s : b > 0 ? 99 : 0;
+    return { liq, vol1h, turnover1h, buys5m: b, sells5m: s, bs5m };
+}
+/**
+ * The tier gates on the tick. Pool age: the tick carries the token's creation time only, and a pool is never older
+ * than its token, so a token younger than minPoolAgeMin (or of unknown age) fails here; the pair's own age is the
+ * rug-proof pool-age gate's job (validateStrategy requires it at minPoolAgeMin or more with tiers on).
+ * The tick itself: a sweep row (the coin had left the screen), a tick time that is not a number, a tick older than
+ * TIER_TICK_MAX_AGE_MS at `nowMs` or stamped after it fails. `nowMs` defaults to the tick's own time (a replay row).
+ */
+export function tierGateFailures(k, g, nowMs = k.t) {
+    const out = [];
+    const t = fin(k.t);
+    const now = fin(nowMs);
+    if (k.kind !== 'live')
+        out.push(`tick not live (${String(k.kind)})`);
+    if (t === null || now === null)
+        out.push('tick time unknown');
+    else if (now - t > TIER_TICK_MAX_AGE_MS)
+        out.push(`tick stale (${Math.ceil((now - t) / 1000)} s old > ${TIER_TICK_MAX_AGE_MS / 1000} s)`);
+    else if (t > now)
+        out.push('tick time after the decision time');
+    const created = fin(k.createdAt) !== null && k.createdAt > 0 ? k.createdAt : null;
+    const ageMin = t !== null && created !== null ? (t - created) / 60e3 : null;
+    if (ageMin === null)
+        out.push(`pool age unknown (no token creation time) < ${g.minPoolAgeMin} min`);
+    else if (ageMin < g.minPoolAgeMin)
+        out.push(`pool age < ${g.minPoolAgeMin} min (token ${ageMin.toFixed(0)} min old)`);
+    const liq = fin(k.liq);
+    if (liq === null || liq < g.minLiqUsd)
+        out.push(`liquidity ${liq === null ? 'unknown' : `$${Math.round(liq)}`} < $${g.minLiqUsd}`);
+    // A young coin with no 1 h change figure cannot be cleared of "vertical": it fails (the research tape had the figure).
+    const h1 = fin(k.chg1h);
+    if (ageMin !== null && ageMin / 60 < g.youngVertical.maxAgeHours) {
+        if (h1 === null)
+            out.push(`young and h1 unknown (at ${(ageMin / 60).toFixed(1)} h)`);
+        else if (h1 >= g.youngVertical.maxH1Pct)
+            out.push(`young and vertical (h1 ${h1}% at ${(ageMin / 60).toFixed(1)} h)`);
+    }
+    return out;
+}
+/**
+ * The size a tier runs at: never above TIERS_HARD_CAP_PCT (or the table's own cap when lower), whatever its evidence
+ * says (0.2.2 has no proven tier and no path that lifts the cap), never above 100 - reservePct. A non-finite or
+ * negative configured size runs at 0.
+ */
+export function tierRunsAtPct(t, table) {
+    const cfg = Number.isFinite(t.sizePct) && t.sizePct > 0 ? t.sizePct : 0;
+    const tableCap = Number.isFinite(table.unprovenCapPct) && table.unprovenCapPct >= 0 ? table.unprovenCapPct : 0;
+    const capPct = Math.min(TIERS_HARD_CAP_PCT, tableCap);
+    let pct = cfg;
+    let capped = false;
+    if (pct > capPct) {
+        pct = capPct;
+        capped = true;
+    }
+    if (pct > 100 - table.reservePct)
+        pct = 100 - table.reservePct;
+    return { pct, capped };
+}
+/** Score the tick (one point per rule that holds; an unknown signal never passes), then the highest tier met wins. */
+export function selectConfidenceTier(k, table = CONFIDENCE_TIERS_V4, nowMs = k.t) {
+    const sig = tierSignals(k);
+    const points = table.points.map((p) => {
+        const actual = sig[p.signal];
+        const pass = actual !== null && (p.op === '>=' ? actual >= p.value : actual <= p.value);
+        return { id: p.id, signal: p.signal, op: p.op, value: p.value, actual: actual === null ? null : Math.round(actual * 1000) / 1000, pass };
+    });
+    const score = points.filter((p) => p.pass).length;
+    const gates = tierGateFailures(k, table.gates, nowMs);
+    let row = table.tiers[0];
+    if (!gates.length)
+        for (const t of table.tiers)
+            if (score >= t.minScore)
+                row = t;
+    const run = row.id === 'T0' ? { pct: 0, capped: false } : tierRunsAtPct(row, table);
+    return { table: table.id, tier: row.id, score, of: points.length, points, gates, configuredPct: row.sizePct, effectivePct: run.pct, evidence: row.evidence, capped: run.capped, heldOut: row.heldOut };
+}
+// ───────────────────────────── text ─────────────────────────────
+const sgn = (x) => `${x > 0 ? '+' : ''}${x.toFixed(1)}`;
+/**
+ * "unproven: held-out n 17, mean -7.6% per entry, lower bound -31.8% (upper +16.8%), rug 1/17". The text carries the
+ * mean and its interval, never a win count or rate (a small-sample win rate reads as a claim the data does not make).
+ */
+export function tierEvidenceText(evidence, h) {
+    const head = evidence === 'n/a' ? 'n/a (at or under the 25% cap)' : evidence;
+    if (h.n === 0 || h.meanPct === null)
+        return `${head}: held-out n 0 (too small to say)`;
+    return `${head}: held-out n ${h.n}, mean ${h.meanPct.toFixed(1)}% per entry, lower bound ${h.loPct === null ? '?' : `${h.loPct.toFixed(1)}%`}${h.hiPct === null ? '' : ` (upper ${sgn(h.hiPct)}%)`}${h.rugs === null ? '' : `, rug ${h.rugs}/${h.n}`}`;
+}
+const short = (m) => (m.length > 10 ? `${m.slice(0, 4)}…${m.slice(-4)}` : m);
+/** The run log's TIER line: tier, score, size, evidence status and the verdict. `afterUsd` = the size after every limit. */
+export function confidenceTierLine(p, k, afterUsd) {
+    const head = `TIER ${p.tier} for ${k.symbol} (${short(k.mint)}): score ${p.score}/${p.of}`;
+    const ev = tierEvidenceText(p.evidence, p.heldOut);
+    if (p.tier === 'T0')
+        return `${head} · SKIP (size 0)${p.gates.length ? ` · gate: ${p.gates.join('; ')}` : ''} · ${ev} · ${TIERS_VERDICT}`;
+    const pts = p.points.filter((x) => x.pass).map((x) => x.id).join(', ') || 'none';
+    const size = p.capped ? `configured ${p.configuredPct}%, runs at ${p.effectivePct}% of the book (unproven: capped)` : `runs at ${p.effectivePct}% of the book`;
+    return `${head} (${pts}) · ${size}${afterUsd !== undefined ? ` · $${afterUsd} after the strategy's limits` : ''} · ${ev} · ${TIERS_VERDICT}`;
+}
+/** Validation / docs text: one line per tier, the verdict first. */
+export function tierTableLines(table = CONFIDENCE_TIERS_V4) {
+    const rows = table.tiers.map((t, i) => {
+        const run = t.id === 'T0' ? { pct: 0, capped: false } : tierRunsAtPct(t, table);
+        const unreachable = i > 0 && table.tiers.slice(i + 1).some((u) => u.minScore === t.minScore);
+        const size = t.id === 'T0' ? 'skip (size 0)' : run.capped ? `configured ${t.sizePct}%, runs at ${run.pct}% (unproven: capped)` : `runs at ${run.pct}%`;
+        return `${t.id} score >= ${t.minScore}: ${size} · ${tierEvidenceText(t.evidence, t.heldOut)}${unreachable ? ` · never selected (a higher tier has the same score ${t.minScore})` : ''}`;
+    });
+    return [TIERS_VERDICT, ...rows, `table ${table.id}: ${table.provenance}`];
+}
+/** A compact record of the pick for the ledger. */
+export function tierRecord(p) {
+    return { table: p.table, tier: p.tier, score: p.score, of: p.of, points: p.points.map((x) => ({ id: x.id, actual: x.actual, pass: x.pass })), gates: p.gates, configuredPct: p.configuredPct, runsAtPct: p.effectivePct, capped: p.capped, evidence: tierEvidenceText(p.evidence, p.heldOut) };
+}