dexterm-cli 0.1.6 → 0.2.0

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

@@ -0,0 +1,330 @@
+// dexterm autotrade — trade-fire receipts, drift and the read-only wallet reconcile (task-1645, 0.2.0 card A).
+//
+// The user's executor reports what it did with a signal, as DATA only: `dexterm autotrade receipt …`, or by
+// appending a `dexterm-trade-receipt/1` line to $DEXTERM_HOME/autotrade/real/receipts.jsonl itself.
+//   status executed | rejected | failed, optional fill {priceUsd, sizeSol, tokens, txSig}, a short reason
+// A receipt never makes dexterm do anything: it only moves a real-mode position from `unconfirmed` to
+// executed / rejected / failed in the ledger, the Q screen and `autotrade audit`, and measures the drift between
+// what was signalled and what was filled. Exits keep firing on the monitor's own (paper-model) view regardless.
+//
+// The wallet reconcile reads a PUBLIC address the user supplies (SOL balance and token holdings, two read-only RPC
+// methods on an allowlist) and lists the mints dexterm thinks are held that the wallet does not show, and back.
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { realDir } from "./outbox.js";
+import { ACCOUNT_ID_RE } from "./signal.js";
+export const RECEIPT_SCHEMA = 'dexterm-trade-receipt/1';
+export const RECEIPT_STATUSES = ['executed', 'rejected', 'failed'];
+export const receiptsPath = (home) => join(realDir(home), 'receipts.jsonl');
+const TX_SIG = /^[1-9A-HJ-NP-Za-km-z]{64,90}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const pos = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null);
+/** Free text from an executor is data: printable ASCII only, 120 chars. */
+const text = (v, max) => { if (typeof v !== 'string')
+    return null; const t = v.replace(/[^\x20-\x7e]/g, '').trim().slice(0, max); return t || null; };
+export function validateReceipt(x) {
+    const r = x;
+    if (!r || typeof r !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (r.schema !== RECEIPT_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (typeof r.signalId !== 'string' || !HEX32.test(r.signalId))
+        return { ok: false, error: 'signalId' };
+    if (!Number.isSafeInteger(r.nonce) || r.nonce < 1)
+        return { ok: false, error: 'nonce' };
+    if (typeof r.accountId !== 'string' || !ACCOUNT_ID_RE.test(r.accountId))
+        return { ok: false, error: 'accountId' };
+    if (!RECEIPT_STATUSES.includes(r.status))
+        return { ok: false, error: 'status' };
+    if (typeof r.at !== 'number' || !Number.isFinite(r.at))
+        return { ok: false, error: 'at' };
+    let fill = null;
+    if (r.fill !== undefined && r.fill !== null) {
+        const f = r.fill;
+        if (typeof f !== 'object')
+            return { ok: false, error: 'fill' };
+        if (f.txSig !== undefined && f.txSig !== null && (typeof f.txSig !== 'string' || !TX_SIG.test(f.txSig)))
+            return { ok: false, error: 'fill.txSig is not a base58 signature' };
+        for (const k of ['priceUsd', 'sizeSol', 'tokens'])
+            if (f[k] !== undefined && f[k] !== null && pos(f[k]) === null)
+                return { ok: false, error: `fill.${k}` };
+        fill = { priceUsd: pos(f.priceUsd), sizeSol: pos(f.sizeSol), tokens: pos(f.tokens), txSig: typeof f.txSig === 'string' ? f.txSig : null };
+    }
+    if (r.status !== 'executed' && fill && (fill.sizeSol || fill.tokens))
+        return { ok: false, error: 'only an executed receipt carries a fill size' };
+    return { ok: true, receipt: { schema: RECEIPT_SCHEMA, signalId: r.signalId, nonce: r.nonce, accountId: r.accountId, status: r.status, at: r.at, fill, reason: text(r.reason, 120), executor: text(r.executor, 32) } };
+}
+export function appendReceipt(home, r) {
+    const v = validateReceipt(r);
+    if (!v.ok)
+        throw new Error(`receipt: ${v.error}`);
+    mkdirSync(realDir(home), { recursive: true, mode: 0o700 });
+    const fd = openSync(receiptsPath(home), 'a', 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(v.receipt)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Why a receipt does not belong to a known signal (or null): unknown nonce, another account, an id mismatch. */
+export function receiptMismatch(r, s) {
+    if (!s)
+        return 'unknown-signal';
+    if (s.id !== r.signalId)
+        return 'signal-id-mismatch';
+    if (s.accountId !== r.accountId)
+        return 'wrong-account';
+    // task-1654: a receipt for a `signal test` proves the round trip (signal test reports it); it is not an orphan.
+    if (s.type === 'test')
+        return 'test-signal';
+    if (s.type !== 'trade')
+        return 'not-a-trade-signal';
+    return null;
+}
+/**
+ * Reads receipts.jsonl incrementally (byte offset). Every valid receipt for a known signal is returned once; the
+ * rest are counted (`invalid`, `orphan`) and never acted on. A partial last line waits for its newline.
+ */
+export class ReceiptsTail {
+    offset = 0;
+    carry = '';
+    invalid = 0;
+    orphan = 0;
+    path;
+    lookup;
+    constructor(home, lookup) { this.path = receiptsPath(home); this.lookup = lookup; }
+    poll() {
+        if (!existsSync(this.path))
+            return [];
+        const size = statSync(this.path).size;
+        if (size < this.offset) {
+            this.offset = 0;
+            this.carry = '';
+        } // truncated: read again
+        if (size === this.offset)
+            return [];
+        const fd = openSync(this.path, 'r');
+        const buf = Buffer.alloc(Math.min(size - this.offset, 4 << 20));
+        let n = 0;
+        try {
+            n = readSync(fd, buf, 0, buf.length, this.offset);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.offset += n;
+        const chunk = this.carry + buf.subarray(0, n).toString('utf8');
+        const lines = chunk.split('\n');
+        this.carry = lines.pop() ?? '';
+        const out = [];
+        for (const l of lines) {
+            if (!l.trim())
+                continue;
+            let raw;
+            try {
+                raw = JSON.parse(l);
+            }
+            catch {
+                this.invalid++;
+                continue;
+            }
+            const v = validateReceipt(raw);
+            if (!v.ok) {
+                this.invalid++;
+                continue;
+            }
+            const mm = receiptMismatch(v.receipt, this.lookup(v.receipt.nonce));
+            if (mm === 'test-signal')
+                continue;
+            if (mm) {
+                this.orphan++;
+                continue;
+            }
+            out.push(v.receipt);
+        }
+        return out;
+    }
+}
+export function readReceipts(home) {
+    const p = receiptsPath(home);
+    if (!existsSync(p))
+        return { receipts: [], invalid: 0 };
+    const out = [];
+    let invalid = 0;
+    for (const l of readFileSync(p, 'utf8').split('\n')) {
+        if (!l.trim())
+            continue;
+        try {
+            const v = validateReceipt(JSON.parse(l));
+            if (v.ok)
+                out.push(v.receipt);
+            else
+                invalid++;
+        }
+        catch {
+            invalid++;
+        }
+    }
+    return { receipts: out, invalid };
+}
+const r1 = (v) => Math.round(v * 10) / 10;
+/** Signals vs receipts: one row per trade signal. */
+export function driftReport(signals, receipts, now, tolPct = 5) {
+    const trades = signals.filter((s) => s.type === 'trade');
+    const byNonce = new Map();
+    let orphanReceipts = 0;
+    const known = new Map(trades.map((s) => [s.nonce, s]));
+    const tests = new Set(signals.filter((s) => s.type === 'test').map((s) => s.nonce));
+    for (const r of receipts) {
+        if (tests.has(r.nonce))
+            continue;
+        if (receiptMismatch(r, known.get(r.nonce))) {
+            orphanReceipts++;
+            continue;
+        }
+        const l = byNonce.get(r.nonce) ?? [];
+        l.push(r);
+        byNonce.set(r.nonce, l);
+    }
+    const counts = { unconfirmed: 0, executed: 0, rejected: 0, failed: 0, 'expired-unconfirmed': 0 };
+    let sizeDrift = 0;
+    const rows = trades.map((s) => {
+        const rs = (byNonce.get(s.nonce) ?? []).sort((a, b) => a.at - b.at);
+        const last = rs[rs.length - 1];
+        const state = last ? last.status : now > s.expiresAt ? 'expired-unconfirmed' : 'unconfirmed';
+        counts[state]++;
+        const filled = last?.status === 'executed' ? last.fill?.sizeSol ?? null : null;
+        const sizeDriftPct = filled !== null && s.sizeSol > 0 ? r1(((filled - s.sizeSol) / s.sizeSol) * 100) : null;
+        const px = last?.status === 'executed' ? last.fill?.priceUsd ?? null : null;
+        const priceDriftPct = px !== null && s.price.usd ? r1(((px - s.price.usd) / s.price.usd) * 100) : null;
+        if (sizeDriftPct !== null && Math.abs(sizeDriftPct) > tolPct)
+            sizeDrift++;
+        return {
+            nonce: s.nonce, id: s.id, runId: s.runId, side: s.side, mint: s.mint, symbol: s.symbol, issuedAt: s.issuedAt, state, signalSol: s.sizeSol, filledSol: filled, sizeDriftPct, priceDriftPct,
+            txSig: last?.fill?.txSig ?? null, conflict: new Set(rs.map((r) => r.status)).size > 1, reason: last?.reason ?? null,
+        };
+    });
+    return { rows, counts, unconfirmed: counts.unconfirmed + counts['expired-unconfirmed'], sizeDrift, orphanReceipts };
+}
+const r2 = (v) => Math.round(v * 100) / 100;
+/** One receipt against its trade signal (null for anything that is not a known trade signal). */
+export function divergenceOf(s, r) {
+    if (!s || s.type !== 'trade' || receiptMismatch(r, s))
+        return null;
+    const f = r.status === 'executed' ? r.fill : null;
+    const px = f?.priceUsd ?? (f?.sizeSol && f.tokens ? (f.sizeSol * s.price.solUsd) / f.tokens : null);
+    const adverse = (ref) => (px && ref && ref > 0 ? r2(((s.side === 'buy' ? px - ref : ref - px) / ref) * 100) : null);
+    const modelTokens = s.model?.tokens ?? null;
+    const fillRatio = !f ? null : s.side === 'buy' ? (f.sizeSol && s.sizeSol > 0 ? Math.round((f.sizeSol / s.sizeSol) * 1000) / 1000 : null) : (f.tokens && modelTokens ? Math.round((f.tokens / modelTokens) * 1000) / 1000 : null);
+    return {
+        nonce: s.nonce, side: s.side, status: r.status, slippageVsPaperPct: adverse(s.model?.priceUsd ?? null), slippageVsQuotePct: adverse(s.price.usd),
+        latencyMs: Math.max(0, r.at - s.issuedAt), fillRatio, partial: fillRatio !== null && fillRatio < 0.95, reason: r.reason,
+    };
+}
+const quantile = (xs, q) => { if (!xs.length)
+    return null; const a = [...xs].sort((x, y) => x - y); return a[Math.min(a.length - 1, Math.floor(q * a.length))]; };
+/** Every trade signal's newest receipt, summarized. */
+export function divergenceReport(signals, receipts) {
+    const bySig = new Map(signals.filter((s) => s.type === 'trade').map((s) => [s.nonce, s]));
+    const newest = new Map();
+    for (const r of receipts) {
+        const s = bySig.get(r.nonce);
+        if (!s || receiptMismatch(r, s))
+            continue;
+        const p = newest.get(r.nonce);
+        if (!p || r.at >= p.at)
+            newest.set(r.nonce, r);
+    }
+    const rows = [...newest.values()].map((r) => divergenceOf(bySig.get(r.nonce), r)).filter((d) => !!d).sort((a, b) => a.nonce - b.nonce);
+    const ex = rows.filter((d) => d.status === 'executed');
+    const sl = ex.map((d) => d.slippageVsPaperPct ?? d.slippageVsQuotePct).filter((v) => v !== null);
+    const lat = rows.map((d) => d.latencyMs);
+    const reasons = {};
+    for (const d of rows)
+        if (d.status !== 'executed') {
+            const k = `${d.status}: ${(d.reason ?? 'no reason').slice(0, 40)}`;
+            reasons[k] = (reasons[k] ?? 0) + 1;
+        }
+    const n = ex.length;
+    return {
+        rows, trades: bySig.size, receipted: rows.length, executed: n, rejected: rows.filter((d) => d.status === 'rejected').length, failed: rows.filter((d) => d.status === 'failed').length, partial: rows.filter((d) => d.partial).length,
+        slippage: { n: sl.length, medianPct: quantile(sl, 0.5), p90Pct: quantile(sl, 0.9), meanPct: sl.length ? r2(sl.reduce((a, b) => a + b, 0) / sl.length) : null },
+        latency: { n: lat.length, medianMs: quantile(lat, 0.5), p90Ms: quantile(lat, 0.9) },
+        reasons,
+        note: n === 0 ? 'no executed receipt yet: nothing to compare paper with' : n < 30 ? `only ${n} executed fill(s): too few to calibrate paper fills with confidence` : `${n} executed fills`,
+    };
+}
+export function divergenceLines(d) {
+    const out = [`paper vs real: ${d.receipted}/${d.trades} trade signals have a receipt · executed ${d.executed} · rejected ${d.rejected} · failed ${d.failed} · partial ${d.partial}`];
+    if (d.slippage.n)
+        out.push(`  slippage vs paper fill: median ${d.slippage.medianPct}% · p90 ${d.slippage.p90Pct}% · mean ${d.slippage.meanPct}% (positive = the real fill was worse than paper)`);
+    if (d.latency.n)
+        out.push(`  latency signal -> receipt: median ${Math.round((d.latency.medianMs ?? 0) / 100) / 10} s · p90 ${Math.round((d.latency.p90Ms ?? 0) / 100) / 10} s`);
+    for (const [k, v] of Object.entries(d.reasons).slice(0, 5))
+        out.push(`  ${v}× ${k}`);
+    out.push(`  ${d.note}`);
+    return out;
+}
+// ───────────────────────────── read-only wallet reconcile ─────────────────────────────
+/** The only RPC methods the reconcile may call. Anything else is refused before it leaves the process. */
+export const RECONCILE_RPC_METHODS = ['getBalance', 'getTokenAccountsByOwner'];
+const TOKEN_PROGRAMS = ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'];
+const PUBKEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** Read a public wallet (balance + token holdings) and compare with the mints the real-mode book holds / closed. */
+export async function reconcileWallet(wallet, rpc, book) {
+    if (!PUBKEY.test(wallet))
+        throw new Error('reconcile: the wallet is a public base58 address (never a key)');
+    const call = (m, p) => { if (!RECONCILE_RPC_METHODS.includes(m))
+        return Promise.reject(new Error(`rpc method ${m} is not on the read-only allowlist`)); return rpc(m, p); };
+    const errors = [];
+    let sol = null;
+    try {
+        const b = (await call('getBalance', [wallet, { commitment: 'confirmed' }]));
+        sol = typeof b?.value === 'number' ? b.value / 1e9 : null;
+    }
+    catch (e) {
+        errors.push(`getBalance: ${e.message.slice(0, 120)}`);
+    }
+    const holdings = {};
+    for (const programId of TOKEN_PROGRAMS) {
+        try {
+            const r = (await call('getTokenAccountsByOwner', [wallet, { programId }, { encoding: 'jsonParsed', commitment: 'confirmed' }]));
+            for (const a of r?.value ?? []) {
+                const info = a.account?.data?.parsed?.info;
+                if (!info?.mint || !PUBKEY.test(info.mint))
+                    continue;
+                holdings[info.mint] = (holdings[info.mint] ?? 0) + (Number(info.tokenAmount?.uiAmount) || 0);
+            }
+        }
+        catch (e) {
+            errors.push(`getTokenAccountsByOwner: ${e.message.slice(0, 120)}`);
+        }
+    }
+    const ok = errors.length === 0;
+    return {
+        wallet, sol, holdings,
+        missing: ok ? book.held.filter((m) => !(holdings[m] > 0)) : [],
+        stillHeld: ok ? book.closed.filter((m) => holdings[m] > 0 && !book.held.includes(m)) : [],
+        errors,
+    };
+}
+/** From the trade signals alone (nonce order): the mints a real-mode book holds, and those it closed. */
+export function heldFromSignals(signals) {
+    const held = new Set();
+    const closed = new Set();
+    for (const s of [...signals].sort((a, b) => a.nonce - b.nonce)) {
+        if (s.type !== 'trade')
+            continue;
+        if (s.side === 'buy') {
+            held.add(s.mint);
+            closed.delete(s.mint);
+        }
+        else if ((s.sellFraction ?? 1) >= 0.999) {
+            held.delete(s.mint);
+            closed.add(s.mint);
+        }
+    }
+    return { held: [...held], closed: [...closed] };
+}

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

@@ -0,0 +1,198 @@
+// dexterm autotrade — the replay tape (task-1498 spike, AUTOTRADE-SPEC §3).
+//
+// A tape is recorded market history in time order: one row per (mint, t) taken from the recorder's
+// `token_snapshots` (the app's own SQLite file, read-only). The same MarketTick type feeds the live screener
+// daemon, the paper runner, the monitor and the backtester, so a backtest replays exactly what a live run
+// would have seen. `tapeFromDb` extracts one; `saveTape` / `loadTape` keep a compact committed fixture.
+//
+// Honest limits of the recorded data (written into every report): rows are written on material change
+// (≥ 5 % price/liquidity) or every 30 min, at the app's ~2-minute refresh cadence, and only while a coin is on
+// a screen, plus sweep re-observations at 1 h…72 h. A gap therefore means "moved less than ~5 %" while the coin
+// was listed, and "unknown" after it left. There are no trades or holder lists in the history.
+//
+// task-1504: where the recorder's tick lane ran (`autotrade_ticks`: a sample every 5–10 s for watchlist / open /
+// candidate / held coins), `tapeFromDb` merges those samples in tape order (t, a snapshot row before a tick at the
+// same t). A tick carries price, liquidity, mcap and the 5 m / 1 h windows; the slower fields (24 h windows, holders,
+// top-10, dev, authorities, organic score) are carried forward from the mint's latest earlier snapshot, never from a
+// later one, and the resolved mcap is scaled by the price move. Coins without ticks replay exactly as before.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { deriveFlags } from "../../cli/src/screener/rows.js";
+export const TAPE_SCHEMA = 'dexterm-autotrade-tape/1';
+/** Column order of a committed tape row (compact arrays keep fixtures small). */
+export const TAPE_COLUMNS = [
+    't', 'kind', 'price', 'mcap', 'mcapResolved', 'mcapFlagged', 'liq', 'vol5m', 'vol1h', 'vol24', 'buys5m', 'sells5m', 'buys24', 'sells24',
+    'chg5m', 'chg1h', 'chg6h', 'chg24h', 'holders', 'top10', 'dev', 'mintAuth', 'freezeAuth', 'org',
+];
+const SIG = 6;
+const sig = (x) => (x === null || !Number.isFinite(x) ? null : Number(x.toPrecision(SIG)));
+const bool = (x) => (x === null || x === undefined ? null : Boolean(x));
+const numOrNull = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const SNAP_COLS = `t, kind, symbol, launchpad, created_at, pair_created_at, price_usd, mcap, mcap_resolved, mcap_flagged, liquidity_usd,
+            vol_m5, vol_h1, vol_h24, buys_m5, sells_m5, buys_h24, sells_h24, chg_m5, chg_h1, chg_h6, chg_h24,
+            holder_count, top_holders_pct, dev_pct, mint_auth_enabled, freeze_auth_enabled, organic_score`;
+function hasTicks(db, since, until) {
+    const t = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'autotrade_ticks'").get();
+    return !!t && !!db.prepare('SELECT 1 FROM autotrade_ticks WHERE t >= ? AND t <= ? LIMIT 1').get(since, until);
+}
+/**
+ * Merge a mint's snapshot rows (time order) with its tick rows (time order) into snapshot-shaped rows: a tick takes
+ * its own price / liquidity / mcap / 5 m + 1 h windows and carries the rest forward from the latest snapshot at or
+ * before it (null before the first one).
+ */
+function mergeTicks(snaps, ticks) {
+    const out = [];
+    let i = 0;
+    let base = null;
+    for (const k of ticks) {
+        while (i < snaps.length && snaps[i].t <= k.t) {
+            base = snaps[i];
+            out.push(snaps[i++]);
+        }
+        const price = numOrNull(k.price_usd);
+        const basePrice = base ? numOrNull(base.price_usd) : null;
+        const baseResolved = base ? numOrNull(base.mcap_resolved) : null;
+        out.push({
+            t: k.t, kind: 'live',
+            symbol: base?.symbol ?? null, launchpad: base?.launchpad ?? null, created_at: base?.created_at ?? null, pair_created_at: k.pair_created_at ?? base?.pair_created_at ?? null,
+            price_usd: price, mcap: numOrNull(k.mcap),
+            mcap_resolved: baseResolved !== null && basePrice && price !== null ? baseResolved * (price / basePrice) : null,
+            mcap_flagged: base?.mcap_flagged ?? 0, liquidity_usd: numOrNull(k.liquidity_usd),
+            vol_m5: k.vol_m5, vol_h1: k.vol_h1, vol_h24: base?.vol_h24 ?? null, buys_m5: k.buys_m5, sells_m5: k.sells_m5, buys_h24: base?.buys_h24 ?? null, sells_h24: base?.sells_h24 ?? null,
+            chg_m5: k.chg_m5, chg_h1: k.chg_h1, chg_h6: base?.chg_h6 ?? null, chg_h24: base?.chg_h24 ?? null,
+            holder_count: base?.holder_count ?? null, top_holders_pct: base?.top_holders_pct ?? null, dev_pct: base?.dev_pct ?? null,
+            mint_auth_enabled: base?.mint_auth_enabled ?? null, freeze_auth_enabled: base?.freeze_auth_enabled ?? null, organic_score: base?.organic_score ?? null,
+        });
+    }
+    while (i < snaps.length)
+        out.push(snaps[i++]);
+    return out;
+}
+/**
+ * Extract a tape from the recorder tables (read-only handle from `openHistoryReadOnly`): `token_snapshots` and, where
+ * the tick lane ran, `autotrade_ticks` (task-1504), in tape order. A mint qualifies on its live rows of either kind.
+ */
+export function tapeFromDb(db, opts = {}) {
+    const since = opts.since ?? 0;
+    const until = opts.until ?? Number.MAX_SAFE_INTEGER;
+    const minLive = opts.minLiveRows ?? 20;
+    const minPeak = opts.minPeakLiqUsd ?? 20_000;
+    const span = (opts.spanHours ?? 24) * 3600e3;
+    const withTicks = opts.ticks !== false && hasTicks(db, since, until);
+    // Without ticks in the window the pick is the exact pre-1504 query, so earlier backtests reproduce bit for bit.
+    const picked = opts.mints ?? db.prepare(withTicks
+        ? `SELECT mint, SUM(n) AS n, MAX(peak) AS peak, MIN(first) AS first FROM (
+         SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM token_snapshots
+           WHERE kind = 'live' AND t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+         UNION ALL
+         SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM autotrade_ticks
+           WHERE t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+       ) GROUP BY mint HAVING n >= ? AND peak >= ? ORDER BY first, mint LIMIT ?`
+        : `SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM token_snapshots
+       WHERE kind = 'live' AND t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+       HAVING n >= ? AND peak >= ? ORDER BY first LIMIT ?`).all(...(withTicks ? [since, until, since, until] : [since, until]), minLive, minPeak, opts.maxMints ?? 100_000).map((r) => r.mint);
+    const rowsQ = db.prepare(`SELECT ${SNAP_COLS} FROM token_snapshots WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t, snap_id`);
+    const ticksQ = withTicks ? db.prepare(`SELECT t, price_usd, liquidity_usd, mcap, vol_m5, vol_h1, buys_m5, sells_m5, chg_m5, chg_h1, pair_created_at
+       FROM autotrade_ticks WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t`) : null;
+    // The carry-forward base may sit before `since`: the mint's latest snapshot at or before the window start.
+    const baseQ = withTicks ? db.prepare(`SELECT ${SNAP_COLS} FROM token_snapshots WHERE mint = ? AND t < ? ORDER BY t DESC, snap_id DESC LIMIT 1`) : null;
+    const mints = [];
+    let from = Number.MAX_SAFE_INTEGER, to = 0;
+    for (const mint of picked) {
+        let rs = rowsQ.all(mint, since, until);
+        if (ticksQ) {
+            const ks = ticksQ.all(mint, since, until);
+            if (ks.length) {
+                const prior = baseQ.get(mint, since);
+                rs = mergeTicks(prior ? [prior, ...rs] : rs, ks);
+                if (prior)
+                    rs = rs.filter((r) => r !== prior);
+            }
+        }
+        const first = rs.find((r) => r.kind === 'live');
+        if (!first)
+            continue;
+        const t0 = first.t;
+        const kept = rs.filter((r) => r.t >= t0 && r.t <= t0 + span && numOrNull(r.price_usd) !== null);
+        if (!kept.length)
+            continue;
+        // Identity from the first row that has one (a mint seen by ticks before any snapshot has none on its first row).
+        const named = rs.find((r) => r.symbol !== null && r.symbol !== undefined) ?? first;
+        const created = numOrNull(named.created_at) ?? numOrNull(first.created_at) ?? numOrNull(first.pair_created_at);
+        mints.push({
+            mint,
+            symbol: String(named.symbol ?? '?').slice(0, 16),
+            launchpad: String(named.launchpad ?? 'unknown'),
+            createdAt: created,
+            rows: kept.map((r) => [
+                r.t, r.kind, sig(numOrNull(r.price_usd)), sig(numOrNull(r.mcap)), sig(numOrNull(r.mcap_resolved)), r.mcap_flagged ? 1 : 0, sig(numOrNull(r.liquidity_usd)),
+                sig(numOrNull(r.vol_m5)), sig(numOrNull(r.vol_h1)), sig(numOrNull(r.vol_h24)), numOrNull(r.buys_m5), numOrNull(r.sells_m5), numOrNull(r.buys_h24), numOrNull(r.sells_h24),
+                sig(numOrNull(r.chg_m5)), sig(numOrNull(r.chg_h1)), sig(numOrNull(r.chg_h6)), sig(numOrNull(r.chg_h24)),
+                numOrNull(r.holder_count), sig(numOrNull(r.top_holders_pct)), sig(numOrNull(r.dev_pct)),
+                r.mint_auth_enabled === null ? null : r.mint_auth_enabled ? 1 : 0, r.freeze_auth_enabled === null ? null : r.freeze_auth_enabled ? 1 : 0, sig(numOrNull(r.organic_score)),
+            ]),
+        });
+        from = Math.min(from, kept[0].t);
+        to = Math.max(to, kept[kept.length - 1].t);
+    }
+    return {
+        schema: TAPE_SCHEMA,
+        source: withTicks ? 'recorder token_snapshots + autotrade_ticks (read-only)' : 'recorder token_snapshots (read-only)',
+        extractedAt: new Date().toISOString(),
+        window: { from: mints.length ? from : 0, to },
+        note: withTicks
+            ? 'Change-driven rows while listed, sweep re-observations, and 5-10 s tick samples for focus coins (slow fields carried forward). No trades.'
+            : 'Change-driven rows at the app refresh cadence while listed, plus sweep re-observations. No candles or trades.',
+        columns: TAPE_COLUMNS,
+        mints,
+    };
+}
+export function saveTape(path, doc) {
+    // One mint row array per line: diffable and still small.
+    const head = { ...doc, mints: undefined };
+    const lines = doc.mints.map((m) => `    ${JSON.stringify(m)}`).join(',\n');
+    const json = JSON.stringify(head, null, 2).replace(/\n}$/, `,\n  "mints": [\n${lines}\n  ]\n}\n`);
+    writeFileSync(path, json);
+}
+export function readTapeDoc(path) {
+    const doc = JSON.parse(readFileSync(path, 'utf8'));
+    if (doc.schema !== TAPE_SCHEMA)
+        throw new Error(`not a ${TAPE_SCHEMA} file`);
+    return doc;
+}
+/** Expand a tape document into ticks in deterministic time order (t, then mint). */
+export function tapeFromDoc(doc) {
+    const col = new Map(doc.columns.map((c, i) => [c, i]));
+    const at = (r, k) => r[col.get(k) ?? -1];
+    const ticks = [];
+    for (const m of doc.mints) {
+        for (const r of m.rows) {
+            ticks.push({
+                mint: m.mint, t: at(r, 't'), kind: at(r, 'kind') === 'sweep' ? 'sweep' : 'live',
+                symbol: m.symbol, launchpad: m.launchpad, createdAt: m.createdAt,
+                price: numOrNull(at(r, 'price')), mcap: numOrNull(at(r, 'mcap')), mcapResolved: numOrNull(at(r, 'mcapResolved')), mcapFlagged: Boolean(at(r, 'mcapFlagged')),
+                liq: numOrNull(at(r, 'liq')), vol5m: numOrNull(at(r, 'vol5m')), vol1h: numOrNull(at(r, 'vol1h')), vol24: numOrNull(at(r, 'vol24')),
+                buys5m: numOrNull(at(r, 'buys5m')), sells5m: numOrNull(at(r, 'sells5m')), buys24: numOrNull(at(r, 'buys24')), sells24: numOrNull(at(r, 'sells24')),
+                chg5m: numOrNull(at(r, 'chg5m')), chg1h: numOrNull(at(r, 'chg1h')), chg6h: numOrNull(at(r, 'chg6h')), chg24h: numOrNull(at(r, 'chg24h')),
+                holders: numOrNull(at(r, 'holders')), top10: numOrNull(at(r, 'top10')), dev: numOrNull(at(r, 'dev')),
+                mintAuth: bool(at(r, 'mintAuth')), freezeAuth: bool(at(r, 'freezeAuth')), org: numOrNull(at(r, 'org')),
+            });
+        }
+    }
+    ticks.sort((a, b) => a.t - b.t || (a.mint < b.mint ? -1 : a.mint > b.mint ? 1 : 0));
+    return { source: doc.source, ticks, mints: doc.mints.map((m) => m.mint) };
+}
+export const loadTape = (path) => tapeFromDoc(readTapeDoc(path));
+/** The screener's row shape for a tick, so strategies reuse the exact filter grammar of the screen. */
+export function tickRow(k) {
+    const base = { mintAuth: k.mintAuth, freezeAuth: k.freezeAuth, top10: k.top10, dev: k.dev, bundled: null, lpLocked: k.launchpad === 'pump.fun' ? 100 : null };
+    return {
+        mint: k.mint, symbol: k.symbol, name: '', launchpad: k.launchpad,
+        price: k.price, mcap: k.mcap, mcapFlagged: k.mcapFlagged, fdv: null, liq: k.liq,
+        vol24: k.vol24, vol6h: null, vol1h: k.vol1h, vol5m: k.vol5m,
+        ageMin: k.createdAt ? Math.max(0, (k.t - k.createdAt) / 60000) : null,
+        holders: k.holders, holders24: null, holdersChgPct: null,
+        chg: { m5: k.chg5m, h1: k.chg1h, h6: k.chg6h, h24: k.chg24h }, spark: undefined,
+        buys: k.buys24, sells: k.sells24, org: k.org, ...base, snipers: null, flags: deriveFlags(base),
+        verified: false, sus: false, bonding: null, pair: null, sources: [], stale: k.kind === 'sweep', fetchedAt: k.t, aiNote: null, image: null,
+    };
+}