dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/data/src/trade/ledger/sources.js

@@ -0,0 +1,307 @@
+// task-1530 — read-only IMPORTERS: every trade journal dexterm already keeps, as unified ledger drafts.
+//
+// Nothing here writes to a source. The existing journals stay exactly as they are (and keep being written the way
+// they always were), so the unified ledger is fully backward compatible: an old journal with none of the new fields
+// imports with those fields null, and the "migration" of an existing install is one `dexterm ledger sync`.
+//
+//   desk     $DEXTERM_HOME/paper-agent.journal: the agent paper desk (MCP paper tools, the autotrade desk executor).
+//            agent.paper.fill events, their structured tag (task-1530), the exit rule journaled just before a monitor
+//            sell (agent.paper.exit.<rule>), and late PROFILE / REPROFILE / EXIT declarations (agent.paper.tag).
+//            The journal's own hash chain is verified and its head recorded in the import event. An autotrade run on
+//            the desk (note.by "autotrade") is imported here too, with its strategy / profile source / model from
+//            the run ledger (`RunHint`).
+//   paper    the paper wallet's paper_trades table (the TUI ticket). Rows the desk booked are joined to the desk
+//            fills (fees, impact, slippage, the book before the fill) and not imported twice.
+// task-1571: there is no live source. dexterm holds no key and places no live order, so it keeps no live fills.
+// Autotrade run ledgers are imported by @dexterm/autotrade (`importRunLedgers`), which owns that format.
+//
+// A round trip is every fill on one mint from a buy while flat until the position is empty again (the source's own
+// token count). Its key is the ref of its first fill, so re-importing never re-keys a trade.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { eventHash } from "../plans/journal.js";
+import { buildFillTag, buildLateTag, tagCode } from "./tags.js";
+import { cleanCode, cleanLedgerText, finite } from "./schema.js";
+const LAMPORTS = 1e9;
+const num = (x) => { const n = typeof x === 'string' && x.trim() !== '' ? Number(x) : x; return finite(n); };
+const big = (x) => { try {
+    return typeof x === 'bigint' ? x : typeof x === 'string' && /^-?\d+$/.test(x) ? BigInt(x) : typeof x === 'number' && Number.isInteger(x) ? BigInt(x) : null;
+}
+catch {
+    return null;
+} };
+const absBig = (b) => (b < 0n ? -b : b);
+const solOf = (l) => (l === null ? null : Number(l) / LAMPORTS);
+const mintOk = (x) => typeof x === 'string' && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(x);
+const sigOk = (x) => (typeof x === 'string' && /^[1-9A-HJ-NP-Za-km-z]{64,90}$/.test(x) ? x : null);
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+/** Track the token count per key; flags the fill that empties the position. */
+class RoundTrips {
+    held = new Map();
+    /** The trade key for this fill, and whether the position is flat after it. A sell while flat has no trade (null). */
+    step(scope, side, tokenDeltaAbs, ref) {
+        const cur = this.held.get(scope);
+        if (side === 'buy') {
+            if (!cur || cur.tokens <= 0n) {
+                this.held.set(scope, { tokens: tokenDeltaAbs, key: ref });
+                return { tradeKey: ref, closes: false };
+            }
+            cur.tokens += tokenDeltaAbs;
+            return { tradeKey: cur.key, closes: false };
+        }
+        if (!cur || cur.tokens <= 0n)
+            return { tradeKey: null, closes: false };
+        cur.tokens -= tokenDeltaAbs;
+        const closes = cur.tokens <= 0n;
+        if (closes)
+            this.held.delete(scope);
+        return { tradeKey: cur.key, closes };
+    }
+}
+/** pump.fun mints every coin with 6 decimals and a fixed 1,000,000,000 supply (the PnL card's rule, task-1518). */
+export const PUMP_FUN_DECIMALS = 6;
+export const PUMP_FUN_SUPPLY_TOKENS = 1_000_000_000;
+const isPumpFun = (mint) => mint.endsWith('pump');
+function fillDraft(p) {
+    const d = {
+        kind: 'fill', decimals: null, sol: null, usd: null, tokens: null, priceSol: null, priceUsd: null, supply: null, feeSol: null,
+        impactPct: null, slippageBps: null, realizedSol: null, realizedUsd: null, bookSol: null, bookUsd: null, closes: null, txSig: null,
+        runId: null, agent: null, strategy: null, sessionId: null, model: null, tag: null, ...p,
+    };
+    // a source that recorded no supply: a pump.fun coin's is fixed, so its market cap is price × 1B; any other stays null
+    if (!d.supply && isPumpFun(d.mint))
+        d.supply = { tokens: PUMP_FUN_SUPPLY_TOKENS, source: 'pump.fun fixed supply' };
+    return d;
+}
+function importDraft(source, label, head, verified, events, t, note) {
+    return { kind: 'import', t, ref: `import:${source}:${label}:${head ?? `n${events}`}`, source, label, sourceHead: head, sourceVerified: verified, events, ...(note ? { note } : {}) };
+}
+function openRo(path) {
+    if (!path || path === ':memory:' || !existsSync(path))
+        return null;
+    try {
+        return new DatabaseSync(path, { readOnly: true });
+    }
+    catch {
+        return null;
+    }
+}
+const hasTable = (db, name) => Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name));
+function readWallet(path) {
+    const db = openRo(path);
+    if (!db)
+        return null;
+    try {
+        if (!hasTable(db, 'paper_trades'))
+            return null;
+        const w = hasTable(db, 'paper_wallet') ? db.prepare('SELECT start_lamports, created_at FROM paper_wallet WHERE id = 1').get() : undefined;
+        const rows = db.prepare('SELECT * FROM paper_trades ORDER BY id ASC').all().map((r) => ({
+            id: Number(r.id), t: Number(r.t), mint: String(r.mint), symbol: String(r.symbol), side: r.side === 'sell' ? 'sell' : 'buy', decimals: Number(r.decimals),
+            solDelta: big(r.sol_delta) ?? 0n, tokenDelta: big(r.token_delta) ?? 0n, fee: big(r.fee_lamports) ?? 0n, priceSol: Number(r.price_sol),
+            priceUsd: r.price_usd === null ? null : Number(r.price_usd), impact: r.price_impact_pct === null ? null : Number(r.price_impact_pct),
+            slippage: Number(r.slippage_bps), realized: big(r.realized_lamports) ?? 0n,
+        }));
+        return { rows, startLamports: w ? big(w.start_lamports) : null, createdAt: w ? Number(w.created_at) : null };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/** Per wallet row: the book (cash + open cost) just BEFORE it, replayed from the wallet's start balance. */
+function walletFacts(w) {
+    const out = new Map();
+    let cash = w.startLamports;
+    const cost = new Map();
+    for (const r of w.rows) {
+        const openCost = [...cost.values()].reduce((s, c) => s + c.cost, 0n);
+        out.set(r.id, { decimals: r.decimals, feeSol: Number(r.fee) / LAMPORTS, impactPct: r.impact, slippageBps: Number.isFinite(r.slippage) ? r.slippage : null, bookSolBefore: cash === null ? null : Number(cash + openCost) / LAMPORTS, priceUsd: r.priceUsd });
+        if (cash !== null)
+            cash += r.solDelta;
+        const c = cost.get(r.mint) ?? { tokens: 0n, cost: 0n };
+        if (r.side === 'buy') {
+            c.tokens += absBig(r.tokenDelta);
+            c.cost += absBig(r.solDelta);
+        }
+        else if (c.tokens > 0n) {
+            const sold = absBig(r.tokenDelta) > c.tokens ? c.tokens : absBig(r.tokenDelta);
+            c.cost -= (c.cost * sold) / c.tokens;
+            c.tokens -= sold;
+        }
+        if (c.tokens <= 0n)
+            cost.delete(r.mint);
+        else
+            cost.set(r.mint, c);
+    }
+    return out;
+}
+function verifyDeskChain(events) {
+    let prev = 'genesis';
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.seq !== i + 1 || e.prev !== prev)
+            return { ok: false, at: i + 1 };
+        const { hash, ...rest } = e;
+        if (eventHash(rest) !== hash)
+            return { ok: false, at: i + 1 };
+        prev = hash;
+    }
+    return { ok: true, at: null };
+}
+export function importDeskJournal(path, o = {}) {
+    const label = 'paper-agent.journal';
+    const res = { label, source: 'desk', drafts: [], events: 0, note: null, problem: null, fillIds: new Set() };
+    if (!existsSync(path))
+        return res;
+    const events = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            res.problem = `a line of ${label} is not JSON; imported the ${events.length} events before it`;
+            break;
+        }
+    }
+    res.events = events.length;
+    const chain = verifyDeskChain(events);
+    const head = events.length ? events[events.length - 1].hash : null;
+    const wallet = o.walletDb ? readWallet(o.walletDb) : null;
+    const facts = wallet ? walletFacts(wallet) : new Map();
+    const trips = new RoundTrips();
+    const lastExitRule = new Map();
+    const tradeOfMint = new Map();
+    for (const e of events) {
+        const d = (e.data ?? {});
+        const ref = `desk:${e.seq}:${String(e.hash).slice(0, 12)}`;
+        if (e.type.startsWith('agent.paper.exit.') && e.type !== 'agent.paper.exit.plan' && e.type !== 'agent.paper.exit.done' && mintOk(d.mint)) {
+            lastExitRule.set(d.mint, { rule: e.type.slice('agent.paper.exit.'.length), detail: cleanLedgerText(d.detail, 200), t: e.ts });
+            continue;
+        }
+        if (e.type === 'agent.paper.tag' && mintOk(d.mint)) {
+            const g = buildLateTag({ kind: d.tagKind, profile: d.profile, from: d.from, to: d.to, exitReason: d.exitReason, reason: d.reason, line: d.line });
+            if (!g.ok)
+                continue;
+            res.drafts.push({
+                kind: 'tag', t: e.ts, ref, tradeKey: tradeOfMint.get(d.mint) ?? null, source: 'desk', mint: d.mint, tagKind: g.tagKind,
+                profile: g.tagKind === 'profile' ? g.profile : null, from: g.tagKind === 'reprofile' ? g.from : null, to: g.tagKind === 'reprofile' ? g.to : null,
+                exitReason: g.tagKind === 'exit' ? g.exitReason : null, reason: g.reason, line: g.line, tagSource: g.tagKind === 'reprofile' ? 'structured' : 'late',
+            });
+            continue;
+        }
+        if (e.type !== 'agent.paper.fill' || !mintOk(d.mint))
+            continue;
+        const side = d.side === 'sell' ? 'sell' : 'buy';
+        const solDelta = big(d.solDelta);
+        const tokenDelta = big(d.tokenDelta);
+        if (solDelta === null || tokenDelta === null)
+            continue;
+        const fillId = num(d.fillId);
+        if (fillId !== null)
+            res.fillIds.add(fillId);
+        const note = (d.note && typeof d.note === 'object' ? d.note : {});
+        const runId = typeof note.runId === 'string' ? cleanCode(note.runId, 80) : null;
+        const byRun = note.by === 'autotrade';
+        const hint = byRun && runId ? o.runs?.get(runId) ?? null : null;
+        const trip = trips.step(d.mint, side, absBig(tokenDelta), ref);
+        if (trip.tradeKey)
+            tradeOfMint.set(d.mint, trip.tradeKey);
+        if (!trip.tradeKey)
+            continue;
+        const f = fillId !== null ? facts.get(fillId) : undefined;
+        // journals before task-1530 carry no decimals: a pump.fun coin's are fixed; any other mint stays unknown (no tokens)
+        const decimals = num(d.decimals) ?? f?.decimals ?? (isPumpFun(d.mint) ? PUMP_FUN_DECIMALS : null);
+        const tokens = decimals !== null ? Number(absBig(tokenDelta)) / 10 ** decimals : null;
+        const sol = Number(absBig(solDelta)) / LAMPORTS;
+        const priceSol = num(d.priceSol);
+        const priceUsd = num(d.priceUsd) ?? f?.priceUsd ?? null;
+        const solUsd = priceSol && priceUsd ? priceUsd / priceSol : null;
+        // an autotrade run's session ids are per run (s1, s2, …): scope them so two runs never share one
+        const rawSid = typeof d.sessionId === 'string' ? d.sessionId : typeof note.sessionId === 'string' ? note.sessionId : null;
+        const sessionId = cleanCode(byRun && runId && rawSid ? `${runId}:${rawSid}` : rawSid, 80);
+        // the tag: the structured one the desk now persists; else what an autotrade note carries; else the monitor exit
+        // rule journaled just before the sell
+        let tag = d.tag && typeof d.tag === 'object' ? sanitizeStoredTag(side, d.tag) : null;
+        if (side === 'buy' && !tag && typeof note.profile === 'string') {
+            const reason = cleanLedgerText(note.reason, 200);
+            const named = sessionId !== null && (hint?.declared.has(sessionId) ?? false);
+            tag = { profile: tagCode(note.profile), reason, exitReason: null, line: null, source: named ? 'structured' : 'default', ...(reason && !named ? { reasonSource: 'structured' } : {}) };
+        }
+        const exitNote = typeof note.exit === 'string' ? tagCode(note.exit) : null;
+        const seen = lastExitRule.get(d.mint);
+        const rule = side === 'sell' ? (exitNote ? { rule: exitNote, detail: null } : seen && e.ts - seen.t < 600_000 ? seen : null) : null;
+        if (side === 'sell' && rule && !(tag && tag.exitReason)) {
+            const code = tagCode(rule.rule);
+            const agentWords = cleanLedgerText(note.agentReason, 200);
+            tag = { profile: null, reason: tag?.reason ?? agentWords ?? rule.detail ?? null, exitReason: code, line: tag?.line ?? null, source: code === 'agent-exit' || code === 'agent-trim' ? 'structured' : 'rule' };
+        }
+        if (side === 'sell')
+            lastExitRule.delete(d.mint);
+        const noteStrategy = byRun && typeof note.strategy === 'string' ? { id: cleanCode(note.strategy, 32) ?? 'unknown', version: null, hash: cleanCode(note.strategyHash, 64) } : null;
+        res.drafts.push(fillDraft({
+            ref, tradeKey: trip.tradeKey, t: e.ts, source: 'desk', walletMode: 'paper', side, mint: d.mint, symbol: cleanLedgerText(d.symbol, 24) ?? '?', decimals,
+            sol, usd: solUsd ? sol * solUsd : null, tokens, priceSol, priceUsd,
+            feeSol: num(d.feeLamports) !== null ? num(d.feeLamports) / LAMPORTS : f?.feeSol ?? null,
+            impactPct: num(d.impactPct) ?? f?.impactPct ?? null, slippageBps: num(d.slippageBps) ?? f?.slippageBps ?? null,
+            realizedSol: side === 'sell' ? solOf(big(d.realizedLamports)) : null,
+            bookSol: num(d.bookLamports) !== null ? num(d.bookLamports) / LAMPORTS : f?.bookSolBefore ?? null,
+            bookUsd: null, closes: trip.closes, runId, agent: cleanLedgerText(d.agent, 40),
+            strategy: hint?.strategy ?? noteStrategy, sessionId,
+            model: cleanLedgerText(d.model, 40) ?? (sessionId ? hint?.models.get(sessionId) ?? null : null), tag,
+        }));
+    }
+    if (events.length)
+        res.drafts.unshift(importDraft('desk', label, head, chain.ok, events.length, events[events.length - 1].ts, chain.ok ? undefined : `the journal's chain breaks at event ${chain.at}`));
+    if (!chain.ok)
+        res.problem = `${label}: its hash chain breaks at event ${chain.at} (imported as found; \`dexterm ledger verify\` shows the import)`;
+    return res;
+}
+/** A tag read back from a journal: re-cleaned (the journal is a file; never trust what it holds). */
+function sanitizeStoredTag(side, g) {
+    const t = buildFillTag(side, { profile: g.profile, reason: g.reason, exitReason: g.exitReason, line: g.line });
+    if (!t)
+        return null;
+    const src = g.source;
+    const known = src === 'structured' || src === 'tag-line' || src === 'rule' || src === 'late' || src === 'default';
+    return { ...t, source: known ? src : t.source };
+}
+// ───────────────────────────── paper wallet (the TUI ticket) ─────────────────────────────
+export function importPaperWallet(dbPath, deskFillIds = new Set()) {
+    const label = 'paper-wallet';
+    const res = { label, source: 'paper', drafts: [], events: 0, note: null, problem: null };
+    const w = readWallet(dbPath);
+    if (!w)
+        return res;
+    res.events = w.rows.length;
+    const facts = walletFacts(w);
+    const trips = new RoundTrips();
+    const scope = `w${w.createdAt ?? 0}`;
+    let n = 0;
+    for (const r of w.rows) {
+        const ref = `paper:${scope}:${r.id}`;
+        const trip = trips.step(r.mint, r.side, absBig(r.tokenDelta), ref);
+        if (deskFillIds.has(r.id) || !trip.tradeKey || !mintOk(r.mint))
+            continue; // the desk's fills come from its journal
+        const f = facts.get(r.id);
+        const sol = Number(absBig(r.solDelta)) / LAMPORTS;
+        const solUsd = r.priceUsd && r.priceSol ? r.priceUsd / r.priceSol : null;
+        res.drafts.push(fillDraft({
+            ref, tradeKey: trip.tradeKey, t: r.t, source: 'paper', walletMode: 'paper', side: r.side, mint: r.mint, symbol: cleanLedgerText(r.symbol, 24) ?? '?',
+            decimals: r.decimals, sol, usd: solUsd ? sol * solUsd : null, tokens: Number(absBig(r.tokenDelta)) / 10 ** r.decimals, priceSol: r.priceSol, priceUsd: r.priceUsd,
+            feeSol: f.feeSol, impactPct: r.impact, slippageBps: r.slippage, realizedSol: r.side === 'sell' ? Number(r.realized) / LAMPORTS : null,
+            bookSol: f.bookSolBefore, closes: trip.closes,
+        }));
+        n++;
+    }
+    if (w.rows.length)
+        res.drafts.unshift(importDraft('paper', label, `${scope}:${w.rows[w.rows.length - 1].id}`, null, w.rows.length, w.rows[w.rows.length - 1].t, n ? undefined : 'no fills outside the agent desk'));
+    return res;
+}

package/dist/packages/data/src/trade/ledger/stats.js

@@ -0,0 +1,123 @@
+// task-1530 — ledger statistics: filters, the summary (win rate, P/L, drawdown, rug rate, breakdowns by profile,
+// exit reason, strategy, source and wallet mode), the equity curve and the per-strategy comparison.
+//
+// Money is summed in ONE unit per report: SOL when every closed trade has a SOL figure, else USD (an autotrade run
+// books in USD). The report names its unit. Paper, devnet and live are never blended silently: `modes` lists what
+// is in the set, and the CLI says so when there is more than one.
+/** `strategy` matches `id`, `id@version` or `id@hash-prefix`. */
+export function matchStrategy(t, q) {
+    const s = t.strategy;
+    if (!s)
+        return q === 'none' || q === 'manual';
+    const [id, at] = q.split('@');
+    if (s.id !== id)
+        return false;
+    return !at || s.version === at || (s.hash ?? '').startsWith(at);
+}
+export function filterTrades(rows, f = {}) {
+    return rows.filter((t) => (!f.source || t.source === f.source) && (!f.mode || t.walletMode === f.mode) && (!f.status || t.status === f.status)
+        && (!f.strategy || matchStrategy(t, f.strategy)) && (!f.profile || (t.profile.id ?? 'undeclared') === f.profile)
+        && (!f.exitReason || (t.exitReason.code ?? 'untagged') === f.exitReason) && (!f.mint || t.mint === f.mint)
+        && (!f.runId || t.runId === f.runId) && (!f.account || t.account === f.account) && (f.since === undefined || t.openedAt >= f.since) && (f.until === undefined || t.openedAt < f.until));
+}
+export function unitFor(rows) {
+    const closed = rows.filter((t) => t.status === 'closed');
+    return closed.length && closed.every((t) => t.pnlSol !== null) ? 'SOL' : closed.some((t) => t.pnlUsd !== null) ? 'USD' : 'SOL';
+}
+const pnlIn = (t, u) => (u === 'SOL' ? t.pnlSol : t.pnlUsd);
+const r = (x, p = 6) => (x === null || !Number.isFinite(x) ? null : Number(x.toPrecision(p)));
+/** Wilson 95 % interval for k wins in n trades. */
+export function wilson(k, n) {
+    if (!n)
+        return null;
+    const z = 1.96, p = k / n, d = 1 + (z * z) / n;
+    const c = (p + (z * z) / (2 * n)) / d, h = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / d;
+    return { value: r(p, 4), lo: r(Math.max(0, c - h), 4), hi: r(Math.min(1, c + h), 4) };
+}
+/** Cumulative realized P/L by close time. Drawdown is from the running peak; its % is of (starting book + peak). */
+export function equityCurve(rows, unit = unitFor(rows)) {
+    const closed = rows.filter((t) => t.status === 'closed' && pnlIn(t, unit) !== null).sort((a, b) => (a.closedAt ?? 0) - (b.closedAt ?? 0) || a.tradeId.localeCompare(b.tradeId));
+    const firstBook = rows.map((t) => (unit === 'SOL' ? t.bookSol : t.bookUsd)).find((x) => x !== null && x > 0) ?? null;
+    let cum = 0, peak = 0, maxDd = 0, maxDdPct = firstBook ? 0 : null;
+    const points = [];
+    for (const t of closed) {
+        const p = pnlIn(t, unit);
+        cum += p;
+        peak = Math.max(peak, cum);
+        const dd = peak - cum;
+        maxDd = Math.max(maxDd, dd);
+        if (firstBook)
+            maxDdPct = Math.max(maxDdPct ?? 0, (dd / (firstBook + peak)) * 100);
+        points.push({ t: t.closedAt ?? t.openedAt, tradeId: t.tradeId, symbol: t.symbol, pnl: r(p), cum: r(cum), peak: r(peak), drawdown: r(dd) });
+    }
+    return { unit, start: firstBook, points, maxDrawdown: r(maxDd), maxDrawdownPct: maxDdPct === null ? null : r(maxDdPct, 4), final: r(cum) };
+}
+function group(rows, key, unit) {
+    const m = new Map();
+    for (const t of rows) {
+        const k = key(t);
+        m.set(k, [...(m.get(k) ?? []), t]);
+    }
+    return [...m.entries()].map(([k, ts]) => {
+        const c = ts.filter((t) => t.status === 'closed');
+        const wins = c.filter((t) => (pnlIn(t, unit) ?? 0) > 0).length;
+        const pcts = c.map((t) => t.pnlPct).filter((x) => x !== null);
+        const rugs = c.filter((t) => t.rug).length;
+        return {
+            key: k, trades: c.length, open: ts.length - c.length, wins, losses: c.length - wins, winRate: c.length ? r(wins / c.length, 4) : null,
+            pnl: r(c.reduce((s, t) => s + (pnlIn(t, unit) ?? 0), 0)), avgPnlPct: pcts.length ? r(pcts.reduce((a, b) => a + b, 0) / pcts.length, 4) : null,
+            rugs, rugRate: c.length ? r(rugs / c.length, 4) : null,
+        };
+    }).sort((a, b) => b.trades - a.trades || a.key.localeCompare(b.key));
+}
+export const strategyKey = (t) => (t.strategy ? `${t.strategy.id}@${t.strategy.version ?? (t.strategy.hash ?? '').slice(0, 8)}` : 'manual');
+const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+export function summarize(rows, unit = unitFor(rows)) {
+    const closed = rows.filter((t) => t.status === 'closed');
+    const pnls = closed.map((t) => pnlIn(t, unit) ?? 0);
+    const wins = pnls.filter((p) => p > 0).length;
+    const pcts = closed.map((t) => t.pnlPct).filter((x) => x !== null).sort((a, b) => a - b);
+    const gain = pnls.filter((p) => p > 0).reduce((a, b) => a + b, 0);
+    const loss = -pnls.filter((p) => p < 0).reduce((a, b) => a + b, 0);
+    const curve = equityCurve(rows, unit);
+    const rugs = closed.filter((t) => t.rug).length;
+    const sumOf = (f) => { const xs = closed.map(f).filter((x) => x !== null); return xs.length ? r(xs.reduce((a, b) => a + b, 0)) : null; };
+    const declared = (f, set) => (set.length ? r(set.filter(f).length / set.length, 4) : null);
+    const good = (s) => s !== 'missing' && s !== 'default';
+    return {
+        unit, modes: [...new Set(rows.map((t) => t.walletMode))],
+        trades: closed.length, open: rows.length - closed.length, wins, losses: closed.length - wins,
+        winRate: wilson(wins, closed.length),
+        pnl: r(pnls.reduce((a, b) => a + b, 0)), pnlSol: sumOf((t) => t.pnlSol), pnlUsd: sumOf((t) => t.pnlUsd),
+        avgPnlPct: r(mean(pcts), 4), medianPnlPct: pcts.length ? r(pcts.length % 2 ? pcts[(pcts.length - 1) / 2] : (pcts[pcts.length / 2 - 1] + pcts[pcts.length / 2]) / 2, 4) : null,
+        bestPct: pcts.length ? r(pcts[pcts.length - 1], 4) : null, worstPct: pcts.length ? r(pcts[0], 4) : null,
+        profitFactor: loss > 0 ? r(gain / loss, 4) : null,
+        maxDrawdown: curve.maxDrawdown, maxDrawdownPct: curve.maxDrawdownPct,
+        rugs, rugRate: closed.length ? r(rugs / closed.length, 4) : null,
+        avgHoldSec: closed.length ? Math.round(mean(closed.map((t) => t.holdSec))) : null,
+        avgMfePct: r(mean(closed.map((t) => t.mfePct).filter((x) => x !== null)), 4),
+        avgMaePct: r(mean(closed.map((t) => t.maePct).filter((x) => x !== null)), 4),
+        feesSol: sumOf((t) => t.feesSol), modelCostUsd: (() => { const xs = rows.map((t) => t.model.costUsd).filter((x) => x !== null); return xs.length ? r(xs.reduce((a, b) => a + b, 0)) : null; })(),
+        tagCoverage: { profileDeclared: declared((t) => good(t.profile.source), rows), exitDeclared: declared((t) => good(t.exitReason.source), closed) },
+        byProfile: group(rows, (t) => t.profile.id ?? 'undeclared', unit),
+        byExitReason: group(closed, (t) => t.exitReason.code ?? 'untagged', unit),
+        byStrategy: group(rows, strategyKey, unit),
+        bySource: group(rows, (t) => t.source, unit),
+        byMode: group(rows, (t) => t.walletMode, unit),
+    };
+}
+/** One row per strategy version (a run of the same id at another version is another row): the forward-test table. */
+export function compareStrategies(rows, unit = unitFor(rows)) {
+    const m = new Map();
+    for (const t of rows) {
+        const k = strategyKey(t);
+        m.set(k, [...(m.get(k) ?? []), t]);
+    }
+    return {
+        unit,
+        rows: [...m.entries()].map(([key, ts]) => {
+            const s = summarize(ts, unit);
+            return { key, strategy: ts[0].strategy, modes: s.modes, trades: s.trades, open: s.open, winRate: s.winRate, pnl: s.pnl, avgPnlPct: s.avgPnlPct, maxDrawdown: s.maxDrawdown, rugRate: s.rugRate, avgHoldSec: s.avgHoldSec, avgMfePct: s.avgMfePct, avgMaePct: s.avgMaePct, modelCostUsd: s.modelCostUsd };
+        }).sort((a, b) => b.pnl - a.pnl || a.key.localeCompare(b.key)),
+    };
+}

package/dist/packages/data/src/trade/ledger/tags.js

@@ -0,0 +1,116 @@
+// task-1530 — the agent's PROFILE / REPROFILE / EXIT declarations as STRUCTURED fields.
+//
+// Before this card the only record of "why this entry, under which exit profile" and "why this exit" was the
+// agent's free text, scraped afterwards by whoever read the transcript (a challenge driver read thinking blocks
+// that the CLI streams as a paraphrase, so every fill of two sessions came out "undeclared profile / untagged
+// exit" although the agent had written both lines). Now the trade tools take the declaration as typed arguments
+// and the desk persists it on the fill itself (`agent.paper.fill` data.tag), so nothing is ever recovered from
+// text again:
+//
+//   paper_confirm  profile, reason        (and/or tag_line: the verbatim PROFILE line, parsed here)
+//   paper_close    exit_reason, reason    (and/or tag_line: the verbatim EXIT line)
+//   paper_tag      a REPROFILE, or a PROFILE / EXIT line that was not passed with its fill (journaled as late)
+//
+// A typed field always wins over a parsed line; a line that does not parse is kept verbatim (capped) with source
+// 'tag-line' only when it yields a profile or reason. Nothing here is an instruction: every string is one line,
+// capped, control characters out, key-shaped runs redacted.
+import { cleanCode, cleanLedgerText } from "./schema.js";
+const B58 = '[1-9A-HJ-NP-Za-km-z]';
+const stripMd = (s) => s.replace(/^[\s>*_`#-]+/, '').replace(/[*_`]+/g, '').trim();
+const symKey = (s) => s.replace(/^\$/, '').replace(/[.,;:]+$/, '').toUpperCase();
+/**
+ * Parse the tagged lines in a block of agent text (the format the exit-profile skills teach):
+ *   PROFILE <profile> for <SYMBOL> (<first 4>…<last 4>): <why> · size <x> SOL (<p>% of bankroll)
+ *   REPROFILE <SYMBOL> <from> -> <to>: <why>
+ *   EXIT <SYMBOL> <reason>: <why>
+ */
+export function parseTagLines(text) {
+    const out = [];
+    if (typeof text !== 'string')
+        return out;
+    for (const raw of text.slice(0, 4000).split('\n')) {
+        const line = stripMd(raw);
+        let m;
+        if ((m = line.match(/^PROFILE\s+([a-z][a-z0-9-]*)\s+for\s+(\S+?)\s*(?:\(([^)]*)\))?\s*:\s*(.+)$/i))) {
+            const hint = (m[3] ?? '').match(new RegExp(`^(${B58}{3,8})\\s*(?:…|\\.\\.\\.)\\s*(${B58}{3,8})$`));
+            const size = m[4].match(/size\s+([0-9]*\.?[0-9]+)\s*SOL/i);
+            out.push({ kind: 'profile', profile: m[1].toLowerCase(), symbol: symKey(m[2]), mintHead: hint?.[1] ?? null, mintTail: hint?.[2] ?? null, why: m[4].trim(), sizeSol: size ? Number(size[1]) : null, line });
+        }
+        else if ((m = line.match(/^REPROFILE\s+(\S+)\s+([a-z][a-z0-9-]*)\s*(?:->|→)\s*([a-z][a-z0-9-]*)\s*:\s*(.+)$/i))) {
+            out.push({ kind: 'reprofile', symbol: symKey(m[1]), from: m[2].toLowerCase(), to: m[3].toLowerCase(), why: m[4].trim(), line });
+        }
+        else if ((m = line.match(/^EXIT\s+(\S+)\s+([a-z0-9-]+)\s*:\s*(.+)$/i))) {
+            out.push({ kind: 'exit', symbol: symKey(m[1]), reason: m[2].toLowerCase(), why: m[3].trim(), line });
+        }
+    }
+    return out;
+}
+/** The profile / exit-reason alphabet: the strategy id rule (`^[a-z][a-z0-9-]{1,31}$`). Anything else is dropped. */
+export function tagCode(x) {
+    const c = cleanCode(x, 32);
+    return c && /^[a-z][a-z0-9-]{0,31}$/.test(c) ? c : null;
+}
+/**
+ * The structured tag a fill carries, or null when the agent declared nothing. Typed fields win; a `line` fills
+ * whatever the typed fields left empty (source 'tag-line' when the line supplied the profile / reason code).
+ */
+export function buildFillTag(side, input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    let profile = side === 'buy' ? tagCode(input.profile) : null;
+    let exitReason = side === 'sell' ? tagCode(input.exitReason) : null;
+    let reason = cleanLedgerText(input.reason, 200);
+    const line = cleanLedgerText(input.line, 300);
+    const structured = side === 'buy' ? profile !== null : exitReason !== null;
+    let fromLine = false;
+    if (line) {
+        const tags = parseTagLines(line);
+        const p = side === 'buy' ? tags.find((g) => g.kind === 'profile') : tags.find((g) => g.kind === 'exit');
+        if (p && p.kind === 'profile') {
+            if (!profile) {
+                profile = tagCode(p.profile);
+                fromLine = profile !== null;
+            }
+            if (!reason)
+                reason = cleanLedgerText(p.why, 200);
+        }
+        if (p && p.kind === 'exit') {
+            if (!exitReason) {
+                exitReason = tagCode(p.reason);
+                fromLine = exitReason !== null;
+            }
+            if (!reason)
+                reason = cleanLedgerText(p.why, 200);
+        }
+    }
+    if (!profile && !exitReason && !reason && !line)
+        return null;
+    const source = structured ? 'structured' : fromLine ? 'tag-line' : 'missing';
+    return { profile, reason, exitReason, line, source };
+}
+export function buildLateTag(input) {
+    const line = cleanLedgerText(input.line, 300);
+    const reason = cleanLedgerText(input.reason, 200);
+    const kind = input.kind;
+    const parsed = line ? parseTagLines(line)[0] ?? null : null;
+    const k = kind === 'profile' || kind === 'reprofile' || kind === 'exit' ? kind : parsed?.kind ?? null;
+    if (!k)
+        return { ok: false, why: 'say what this declares: kind profile | reprofile | exit, or a PROFILE / REPROFILE / EXIT line' };
+    if (k === 'profile') {
+        const profile = tagCode(input.profile) ?? (parsed?.kind === 'profile' ? tagCode(parsed.profile) : null);
+        if (!profile)
+            return { ok: false, why: 'a profile tag needs a profile id (or a PROFILE line that names one)' };
+        return { ok: true, tagKind: 'profile', profile, reason: reason ?? (parsed?.kind === 'profile' ? cleanLedgerText(parsed.why, 200) : null), line };
+    }
+    if (k === 'reprofile') {
+        const to = tagCode(input.to) ?? (parsed?.kind === 'reprofile' ? tagCode(parsed.to) : null);
+        if (!to)
+            return { ok: false, why: 'a reprofile tag needs `to` (or a REPROFILE line)' };
+        const from = tagCode(input.from) ?? (parsed?.kind === 'reprofile' ? tagCode(parsed.from) : null);
+        return { ok: true, tagKind: 'reprofile', from, to, reason: reason ?? (parsed?.kind === 'reprofile' ? cleanLedgerText(parsed.why, 200) : null), line };
+    }
+    const exitReason = tagCode(input.exitReason) ?? (parsed?.kind === 'exit' ? tagCode(parsed.reason) : null);
+    if (!exitReason)
+        return { ok: false, why: 'an exit tag needs an exit reason code (or an EXIT line)' };
+    return { ok: true, tagKind: 'exit', exitReason, reason: reason ?? (parsed?.kind === 'exit' ? cleanLedgerText(parsed.why, 200) : null), line };
+}

package/dist/packages/data/src/trade/ledger/view.js

@@ -0,0 +1,51 @@
+// task-1530 — the ledger VIEW: what the file holds plus what the sources hold that it does not have yet.
+//
+// Reads (`dexterm ledger trades|summary|export`, the MCP ledger tools, the PnL card) never wait for a sync and
+// never write: they fold the file's events together with fresh drafts from the sources, in memory. Only
+// `dexterm ledger sync` appends those drafts to the file (and so gives them a place in the hash chain).
+import { join } from 'node:path';
+import { paperAgentJournalPath } from "../agent/rendezvous.js";
+import { dextermHomeDir, readTradeLedger, tradeLedgerPath } from "./file.js";
+import { foldTrades } from "./fold.js";
+import { importDeskJournal, importPaperWallet } from "./sources.js";
+import { LEDGER_VERSION } from "./schema.js";
+export function defaultSourcePaths(env = process.env, walletDb = null) {
+    return {
+        deskJournal: paperAgentJournalPath(env),
+        walletDb,
+    };
+}
+/** Drafts from every data-layer source (run ledgers are added by the caller that can read them). */
+export function collectDataSources(p, o = {}) {
+    const desk = importDeskJournal(p.deskJournal, { walletDb: p.walletDb, ...(o.runs ? { runs: o.runs } : {}) });
+    const out = [desk];
+    if (p.walletDb)
+        out.push(importPaperWallet(p.walletDb, desk.fillIds));
+    return out;
+}
+/** Fold the file plus the pending drafts. A file that fails its check still folds (the view says so). */
+export function buildLedgerView(path, sources, now = Date.now()) {
+    const file = readTradeLedger(path);
+    const have = new Set();
+    for (const e of file.events)
+        if ('ref' in e && typeof e.ref === 'string')
+            have.add(e.ref);
+    const pending = [];
+    const meta = [];
+    for (const s of sources) {
+        let n = 0;
+        for (const d of s.drafts) {
+            const ref = d.ref;
+            if (!ref || have.has(ref))
+                continue;
+            have.add(ref);
+            pending.push(d);
+            n++;
+        }
+        meta.push({ label: s.label, source: s.source, events: s.events, pending: n, note: s.note, problem: s.problem });
+    }
+    let seq = file.events.length;
+    const events = [...file.events, ...pending.map((d) => ({ ...d, seq: ++seq, v: LEDGER_VERSION, prev: 'pending', hash: 'pending' }))];
+    return { path, file, pending, sources: meta, events, trades: foldTrades(events, { now }) };
+}
+export { tradeLedgerPath };

package/dist/packages/data/src/trade/plans/engine.js

@@ -268,6 +268,8 @@ export class PlanEngine {
     authorizeCopy(mandateId, proof, wallet) {
         if (!this.gate.handsFreeAllowed())
             throw new PolicyRefusal('gate-on', 'copy automation needs the less-safe opt-in');
+        if (this.mandates.get(mandateId)?.m.paperOnly)
+            throw new PolicyRefusal('paper-only-mandate', 'a paper-only mandate is for the agent paper desk; copy automation cannot use it');
         this.armMandate(mandateId, proof);
         return (input, supply, ref) => {
             const check = () => {
@@ -315,6 +317,9 @@ export class PlanEngine {
         const alive = mandateAlive(x.m, this.clock.now());
         if (!alive.ok)
             refuse(alive.reason, 'mandate is not alive');
+        // task-1469: a paper-only mandate (PAPER_HARD ceilings) feeds the agent paper desk only; no plan arms into it.
+        if (x.m.paperOnly)
+            refuse('paper-only-mandate', 'a paper-only mandate is for the agent paper desk; plans cannot arm into it');
         if (TIERS[tier].rank > TIERS[x.m.maxTier].rank)
             refuse('tier-not-allowed', `this mandate accepts up to ${x.m.maxTier}; ${tier} is weaker`);
         const v = this.admit(r, x, tier);
@@ -599,6 +604,8 @@ export class PlanEngine {
         const alive = mandateAlive(m, now);
         if (!alive.ok)
             return no(alive.reason, 'mandate not alive');
+        if (m.paperOnly)
+            return no('paper-only-mandate', 'a paper-only mandate never fires a plan');
         if (now > p.expiresAt)
             return no('plan-expired', 'plan expired');
         if (!m.allowed.actions.includes(side))

package/dist/packages/data/src/trade/plans/index.js

@@ -7,6 +7,5 @@ export { HOLD_MS, CHALLENGE_TTL_MS, ECHO_GUARD_MS, RISK_ACCEPT_TTL_MS, ConfirmEr
 export { Journal, redact, eventHash } from "./journal.js";
 export { RpcOutage } from "./executor.js";
 export { PaperPlanExecutor } from "./executor-paper.js";
-export { LivePlanExecutor, LIVE_BUILD_TTL_MS } from "./executor-live.js";
 export { PlanEngine, PolicyRefusal, TERMINAL } from "./engine.js";
 export { PlanService, parseAmount, parseTrigger, parseExit, planStatusLabel, defaultPlansJournalPath } from "./service.js";