dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/recorder/src/cli.js

@@ -0,0 +1,113 @@
+// `dexterm recorder <cmd>` / `dexterm-recorder <cmd>`: stats, label, prune, export. No network.
+import { writeFileSync } from 'node:fs';
+import { defaultDbPath } from '../../data/src/index.js';
+import { Recorder } from "./recorder.js";
+import { exportRecorded } from "./export.js";
+export const RECORDER_HELP = `dexterm recorder: the history recorder's tables (snapshots, feed membership, outcomes)
+
+  dexterm recorder stats  [--db PATH]                     rows, labels, bytes per snapshot, DB size
+  dexterm recorder label  [--db PATH]                     label every due t0 anchor now (code only, no model)
+  dexterm recorder prune  [--db PATH]                     run retention now (raw 7 d, 1/min after 24 h, columns 90 d)
+  dexterm recorder export [--db PATH] [--out FILE] [--since T] [--until T] [--labelled-only] [--limit N]
+                                                          eval export (T = ISO date or unix ms); stdout without --out
+
+  --db defaults to DEXTERM_DB_PATH, else ~/.local/share/dexterm/dexterm.db. The recorder itself runs
+  inside the live app; switch it off with --no-recorder or DEXTERM_RECORDER=0.`;
+function parse(argv) {
+    const opts = {};
+    let cmd = '';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const k = a.slice(2);
+            const v = argv[i + 1];
+            if (v !== undefined && !v.startsWith('--') && k !== 'labelled-only') {
+                opts[k] = v;
+                i++;
+            }
+            else
+                opts[k] = true;
+        }
+        else if (!cmd)
+            cmd = a;
+    }
+    return { cmd, opts };
+}
+function time(v) {
+    if (v === undefined || v === true)
+        return undefined;
+    const n = Number(v);
+    if (Number.isFinite(n))
+        return n;
+    const t = Date.parse(v);
+    if (!Number.isFinite(t))
+        throw new Error(`bad time ${JSON.stringify(v)} (ISO date or unix ms)`);
+    return t;
+}
+export async function recorderCli(argv, io) {
+    const { cmd, opts } = parse(argv);
+    if (!cmd || cmd === 'help' || opts.help || opts.h) {
+        io.stdout.write(RECORDER_HELP + '\n');
+        return cmd ? 0 : 2;
+    }
+    const path = typeof opts.db === 'string' ? opts.db : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    if (path === ':memory:') {
+        io.stderr.write('dexterm recorder: an in-memory DB has no history\n');
+        return 2;
+    }
+    let rec = null;
+    try {
+        rec = new Recorder({ path });
+        if (cmd === 'stats') {
+            const s = rec.stats();
+            const mb = (b) => (b === null ? '—' : `${(b / 1e6).toFixed(1)} MB`);
+            const when = (t) => (t === null ? '—' : new Date(t).toISOString());
+            io.stdout.write([
+                `db              ${path} (${mb(s.dbBytes)}, every table)`,
+                `recorder bytes  ${s.recorderBytes === null ? '—' : s.recorderBytes} (${mb(s.recorderBytes)}, its own tables + indexes)`,
+                `schema          v${s.schemaVersion} · labeler ${s.labelerVersion}`,
+                `snapshots       ${s.snapshots} (live ${s.live}, sweep ${s.sweep}, t0 anchors ${s.t0}, with raw JSON ${s.withRaw})`,
+                `bytes/snapshot  ${s.bytesPerSnapshot === null ? '—' : s.bytesPerSnapshot.toFixed(0)}`,
+                `mints           ${s.mints}`,
+                `feed_members    ${s.feedMembers}`,
+                `outcomes        ${s.outcomes}${s.outcomes ? ' (' + Object.entries(s.outcomesByLabel).map(([k, v]) => `${k} ${v}`).join(', ') + ')' : ''}`,
+                `sweeps          ${s.sweeps} runs · ${s.sweepCallsToday} DexScreener calls today`,
+                `span            ${when(s.oldestT)} → ${when(s.newestT)}`,
+            ].join('\n') + '\n');
+            return 0;
+        }
+        if (cmd === 'label') {
+            const r = rec.labelPending(Date.now(), 1_000_000);
+            io.stdout.write(`labelled ${r.labelled} (${Object.entries(r.counts).map(([k, v]) => `${k} ${v}`).join(', ') || 'nothing due'}); ${r.pending} t0 rows still open\n`);
+            return 0;
+        }
+        if (cmd === 'prune') {
+            const r = rec.prune();
+            io.stdout.write(`raw cleared ${r.rawCleared} · downsampled ${r.downsampled} · expired ${r.expired} snapshots, ${r.membersExpired} feed rows\n`);
+            return 0;
+        }
+        if (cmd === 'export') {
+            const doc = exportRecorded(rec.database, {
+                since: time(opts.since), until: time(opts.until), labelledOnly: opts['labelled-only'] === true,
+                limit: typeof opts.limit === 'string' ? Number(opts.limit) : undefined,
+            });
+            const text = JSON.stringify(doc, null, 1);
+            if (typeof opts.out === 'string') {
+                writeFileSync(opts.out, text);
+                io.stderr.write(`wrote ${opts.out}: ${doc.counts.records} records, ${doc.counts.with_any_outcome} with outcomes\n`);
+            }
+            else
+                io.stdout.write(text + '\n');
+            return 0;
+        }
+        io.stderr.write(`dexterm recorder: unknown command ${cmd}\n${RECORDER_HELP}\n`);
+        return 2;
+    }
+    catch (err) {
+        io.stderr.write(`dexterm recorder: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    finally {
+        rec?.close();
+    }
+}

package/dist/packages/recorder/src/export.js

@@ -0,0 +1,71 @@
+// Export for the eval / backtest harness (AI-SUITE-DESIGN §4.1 "export": `eval/recorded.json`). One
+// record per t0 anchor: the t0 features exactly as the user would have seen them (no later column),
+// the feeds that surfaced the mint in the hour before t0, and the outcome per horizon. Leakage rule
+// printed in the document: features are from t0 only; labels are after t0.
+import { HORIZONS_SEC } from "./schema.js";
+import { COLUMN_NAMES } from "./snapshot.js";
+import { LABELER_VERSION, isPositive } from "./labels.js";
+export const EXPORT_SCHEMA = 'dexterm-recorder-export/1';
+const FEATURES = COLUMN_NAMES.filter((c) => c !== 'mint');
+export function exportRecorded(db, opts = {}, now = Date.now()) {
+    const where = ['is_t0 = 1'];
+    const args = [];
+    if (opts.since !== undefined) {
+        where.push('t >= ?');
+        args.push(opts.since);
+    }
+    if (opts.until !== undefined) {
+        where.push('t < ?');
+        args.push(opts.until);
+    }
+    const limit = opts.limit !== undefined ? ` LIMIT ${Math.max(0, Math.floor(opts.limit))}` : '';
+    const order = opts.limit !== undefined ? 'DESC' : 'ASC';
+    const t0s = db.prepare(`SELECT snap_id, t, ${COLUMN_NAMES.join(', ')} FROM token_snapshots WHERE ${where.join(' AND ')} ORDER BY t ${order}${limit}`).all(...args);
+    const feedsStmt = db.prepare('SELECT DISTINCT feed FROM feed_members WHERE mint = ? AND t > ? AND t <= ? ORDER BY feed');
+    const firstStmt = db.prepare('SELECT first_t FROM mints WHERE mint = ?');
+    const outStmt = db.prepare('SELECT horizon_sec, t1, label, label_tier, mcap_ratio, liq_ratio, price_ratio, max_mcap_ratio FROM outcomes WHERE mint = ? AND t0 = ?');
+    const records = [];
+    const byLabel = {};
+    let withAny = 0;
+    for (const r of t0s) {
+        const mint = String(r.mint);
+        const t0 = Number(r.t);
+        const outcomes = {};
+        const rows = outStmt.all(mint, t0);
+        for (const o of rows) {
+            outcomes[`${Number(o.horizon_sec)}`] = {
+                label: o.label, tier: o.label_tier, t1: o.t1 === null ? null : Number(o.t1),
+                mcap_ratio: o.mcap_ratio, liq_ratio: o.liq_ratio, price_ratio: o.price_ratio, max_mcap_ratio: o.max_mcap_ratio,
+                positive: isPositive(o.label, o.label_tier),
+            };
+            byLabel[o.label] = (byLabel[o.label] ?? 0) + 1;
+        }
+        if (rows.length)
+            withAny++;
+        else if (opts.labelledOnly)
+            continue;
+        const features = {};
+        for (const c of FEATURES)
+            features[c] = r[c] ?? null;
+        const first = firstStmt.get(mint);
+        records.push({
+            mint, t0,
+            known_sec: first ? Math.max(0, Math.round((t0 - Number(first.first_t)) / 1000)) : 0,
+            feeds: feedsStmt.all(mint, t0 - 3_600_000, t0).map((f) => f.feed),
+            features,
+            outcomes,
+        });
+    }
+    if (order === 'DESC')
+        records.reverse();
+    return {
+        schema: EXPORT_SCHEMA,
+        exported_at: new Date(now).toISOString(),
+        labeler_version: LABELER_VERSION,
+        data_tier: 'keyless-proxy',
+        leakage_rule: 'features are the t0 row only (the row the user saw); every outcome is computed from observations strictly after t0; the universe at t is every mint recorded at or before t, dead ones included',
+        horizons_sec: [...HORIZONS_SEC],
+        counts: { records: records.length, with_any_outcome: withAny, by_label: byLabel },
+        records,
+    };
+}

package/dist/packages/recorder/src/index.js

@@ -0,0 +1,20 @@
+// @dexterm/recorder public surface (lane R-01).
+export * from "./schema.js";
+export * from "./snapshot.js";
+export * from "./labels.js";
+export * from "./sweep.js";
+export * from "./recorder.js";
+export * from "./export.js";
+export * from "./open.js";
+export * from "./verdicts.js";
+export * from "./schedule.js";
+export { recorderCli, RECORDER_HELP } from "./cli.js";
+/** `--no-recorder` / `DEXTERM_RECORDER=0` resolution: the recorder is on in live mode unless either says no. */
+export function recorderEnabled(env, flagOff) {
+    if (flagOff)
+        return false;
+    const v = env.DEXTERM_RECORDER;
+    if (v === undefined || v === '')
+        return true;
+    return !(v === '0' || v.toLowerCase() === 'off' || v.toLowerCase() === 'false' || v.toLowerCase() === 'no');
+}

package/dist/packages/recorder/src/labels.js

@@ -0,0 +1,151 @@
+// Outcome labeler (lane R-01): a port of dexterm/research/task-1287/recorder/labels.mjs. Deterministic,
+// code only, never a model (CLAUDE-LAYER §7 circularity rule). Rules: research/task-1287/recorder/labels.md
+// (v0.1) plus the two v0.2 additions BACKTEST.md §3/§4 proposed after the t1 sweep:
+//   D2 curve-dead  a bonding-curve launch whose t1 shows liquidity <= $100 and vol_h1 < $100 is `dead`
+//                  regardless of market source and mcap ratio (a never-traded curve keeps its mcap pinned
+//                  at the floor, so no ratio rule can see it);
+//   source rule    t0 without a pair (market source = Jupiter) and t1 with a DexScreener pair is no
+//                  longer `unobserved`: ratios are computed across sources but the evidence says so
+//                  (`cross_source: true`). Non-curve tokens keep the strict same-source rule.
+// `version: '0.1'` reproduces the prototype byte for byte (the test replays its 178 labels).
+export const LABELER_VERSION = '0.2.0';
+export const HORIZONS = [3600, 7200, 21600, 86400, 259200];
+/**
+ * Launchpads (the data layer's normalised `Launchpad`) whose tokens start on a bonding curve with no
+ * pool until migration: pump.fun, bonk (letsbonk), Meteora DBC, and Raydium LaunchLab (`raydium`).
+ */
+export const CURVE_LAUNCHPADS = new Set(['pump.fun', 'bonk', 'dbc', 'raydium']);
+/** Thresholds (labels.md). */
+export const RULES = {
+    rugMinLiqT0: 5000,
+    rugLiqRatio: 0.10,
+    rugPriceRatio: 0.50,
+    deadMcapRatio: 0.20,
+    deadVolH1: 500,
+    fadeMcapRatio: 0.50,
+    runnerRatio: 2.0,
+    curveDeadLiq: 100,
+    curveDeadVolH1: 100,
+};
+const ratio = (a, b) => (a === null || b === null || !b ? null : a / b);
+/**
+ * Label one (t0, observations) pair. `obs` are the observations after t0 for the same mint, ascending
+ * by t; the LAST one is t1 (the caller picks the window). Returns null for an empty `obs`.
+ * This is the prototype's `label()` with the horizon bucketed from Δt (for the replay test); the app
+ * calls `labelAtHorizon` which fixes the horizon and passes the right window.
+ */
+export function label(t0, obs, opts = {}) {
+    if (!obs.length)
+        return null;
+    const t1 = obs[obs.length - 1];
+    const dt = Math.round((t1.t - t0.t) / 1000);
+    const horizon = [...HORIZONS].reverse().find((h) => dt >= h) ?? null;
+    const minDt = opts.minDtSec ?? 3000;
+    if (horizon === null || dt < minDt)
+        return classify(t0, obs, 0, opts, 'below-min-horizon');
+    return classify(t0, obs, horizon, opts);
+}
+const isJup = (s) => !!s && s.startsWith('jupiter');
+/**
+ * Label a t0 row at a fixed horizon: `obs` = observations in (t0, t1] with t1 the first observation at or
+ * after t0 + horizon (the caller enforces the ≤ 2x window). An empty `obs` means the window closed with
+ * nothing seen → `unobserved` with t1 = null.
+ */
+export function labelAtHorizon(t0, obs, horizonSec, opts = {}) {
+    if (!obs.length)
+        return outcome(t0, null, horizonSec, 'unobserved', null, null, null, null, { reason: 'no-observation-in-window' }, opts);
+    return classify(t0, obs, horizonSec, opts);
+}
+function classify(t0, obs, horizon, opts, forceUnobserved) {
+    const rules = opts.rules ?? '0.2';
+    const t1 = obs[obs.length - 1];
+    const dt = Math.round((t1.t - t0.t) / 1000);
+    const vanished = t0.pair_address !== null && t1.pair_address === null;
+    const r_mcap = vanished ? 0 : ratio(t1.mcap, t0.mcap);
+    const r_liq = vanished ? 0 : ratio(t1.liquidity_usd, t0.liquidity_usd);
+    const r_price = vanished ? 0 : ratio(t1.price_usd, t0.price_usd);
+    const max_r = Math.max(...obs.map((o) => ratio(o.mcap, t0.mcap) ?? 0), r_mcap ?? 0);
+    const ev = {
+        dt_sec: dt, r_mcap, r_liq, r_price, max_mcap_ratio: max_r, vanished,
+        t0: { mcap: t0.mcap, liq: t0.liquidity_usd, price: t0.price_usd, vol_h1: t0.vol_h1, src: t0.src_market },
+        t1: { mcap: t1.mcap, liq: t1.liquidity_usd, price: t1.price_usd, vol_h1: t1.vol_h1, src: t1.src_market },
+    };
+    const curve = CURVE_LAUNCHPADS.has(t0.launchpad ?? '');
+    const sourceMismatch = t0.src_market !== t1.src_market && !vanished;
+    let lab;
+    let tier = 'keyless-proxy';
+    const chain = chainVerified(opts.chainEvents);
+    if (forceUnobserved) {
+        lab = 'unobserved';
+        ev.reason = forceUnobserved;
+    }
+    else if (chain) {
+        lab = chain.label;
+        tier = 'chain-verified';
+        ev.rule = chain.rule;
+    }
+    else if (rules === '0.2' && curve && (t1.liquidity_usd ?? 0) <= RULES.curveDeadLiq && (t1.vol_h1 ?? 0) < RULES.curveDeadVolH1 && t1.src_market !== null && t1.src_market !== 'none') {
+        // D2 (v0.2): a bonding-curve launch with no pool and no trades at t1 is dead, whatever the ratios say.
+        lab = 'dead';
+        ev.rule = 'D2 curve-dead: liq<=100 & vol_h1<100';
+        if (sourceMismatch)
+            ev.cross_source = true;
+    }
+    else if (sourceMismatch && !(rules === '0.2' && curve && isJup(t0.src_market) && t1.src_market === 'dexscreener')) {
+        lab = 'unobserved';
+        ev.reason = 'source-mismatch';
+    }
+    else if (t0.mcap === null || t0.mcap === 0) {
+        lab = 'unobserved';
+        ev.reason = 'no-mcap-at-t0';
+    }
+    else {
+        if (sourceMismatch)
+            ev.cross_source = true;
+        if ((t0.liquidity_usd ?? 0) >= RULES.rugMinLiqT0 && r_liq !== null && r_liq <= RULES.rugLiqRatio && r_price !== null && r_price <= RULES.rugPriceRatio) {
+            lab = 'rug';
+            ev.rule = 'R1 liq<=10% & price<=50%';
+        }
+        else if (r_mcap !== null && r_mcap <= RULES.deadMcapRatio && (t1.vol_h1 ?? 0) < RULES.deadVolH1) {
+            lab = 'dead';
+            ev.rule = 'D1 mcap<=20% & vol_h1<500';
+        }
+        else if (r_mcap !== null && r_mcap <= RULES.fadeMcapRatio) {
+            lab = 'fade';
+            ev.rule = 'F1 mcap<=50%';
+        }
+        else if (max_r >= RULES.runnerRatio) {
+            lab = 'runner';
+            ev.rule = 'U1 max mcap>=2x';
+        }
+        else
+            lab = 'flat';
+    }
+    return outcome(t0, t1, horizon, lab, r_mcap, r_liq, r_price, max_r, ev, opts, tier);
+}
+/** Tier-1 override (labels.md): LP withdraw / freeze / dev sell ≥ 20 % between t0 and t1 is a chain-verified rug. */
+function chainVerified(events) {
+    if (!events || !events.length)
+        return null;
+    for (const e of events) {
+        if (e.kind === 'lp_withdraw')
+            return { label: 'rug', rule: 'C1 lp_withdraw' };
+        if (e.kind === 'freeze')
+            return { label: 'rug', rule: 'C2 freeze' };
+        if (e.kind === 'dev_sell' && (e.amount ?? 0) >= 20)
+            return { label: 'rug', rule: 'C3 dev_sell>=20%' };
+    }
+    return null;
+}
+function outcome(t0, t1, horizon, lab, r_mcap, r_liq, r_price, max_r, ev, opts, tier = 'keyless-proxy') {
+    const rules = opts.rules ?? '0.2';
+    return {
+        mint: t0.mint, t0: t0.t, horizon_sec: horizon, t1: t1 ? t1.t : null, label: lab, label_tier: tier,
+        mcap_ratio: r_mcap, liq_ratio: r_liq, price_ratio: r_price, max_mcap_ratio: max_r,
+        evidence: JSON.stringify(ev), labeler_version: rules === '0.1' ? '0.1.0' : LABELER_VERSION,
+    };
+}
+/** Positive class for the rug model on keyless data (labels.md): rug ∪ dead. */
+export function isPositive(l, tier = 'keyless-proxy') {
+    return l === 'rug' || (tier === 'keyless-proxy' && l === 'dead');
+}

package/dist/packages/recorder/src/open.js

@@ -0,0 +1,29 @@
+// Shared read-only open for the recorder tables. Three consumers (the MCP `historyDb()`, `dexterm
+// narrative`, and now `dexterm backtest` / the `rug_backtest` MCP tool) each opened a read-only
+// DatabaseSync and inline-checked that `token_snapshots` exists before querying; this is that one check.
+//
+// It never creates the schema (read-only; the live Recorder owns writes) and returns null when the file
+// has no recorder history yet, so a caller can say "no history recorded" instead of throwing.
+import { DatabaseSync } from 'node:sqlite';
+/**
+ * Open the app DB read-only and confirm the recorder schema exists. Returns null (and closes the handle)
+ * when `token_snapshots` is absent — i.e. nothing has been recorded into this file yet. `:memory:` has no
+ * on-disk history, so it returns null too. Throws only on a genuine open error (missing file, locked).
+ */
+export function openHistoryReadOnly(path) {
+    if (path === ':memory:')
+        return null;
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        const t = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='token_snapshots'").get();
+        if (!t) {
+            db.close();
+            return null;
+        }
+        return db;
+    }
+    catch (e) {
+        db.close();
+        throw e;
+    }
+}