dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,135 @@
+// dexterm history recorder: schema (lane R-01, AI-SUITE-DESIGN §4.1; prototyped in
+// dexterm/research/task-1287/recorder/schema.sql). Lives in the app's SQLite file (the one `--db`
+// controls, next to the cache / watchlist / paper wallet tables) on node:sqlite, WAL mode.
+//
+// Differences from the prototype, all on purpose:
+//   - no `runs` table: the app has no sweep runs, it observes rows as the data layer normalises them.
+//     `sweeps` records the outcome re-observation calls instead (the request ledger the budget needs).
+//   - token_snapshots gains `kind` ('live' = observed from the app's own rows, 'sweep' = an outcome
+//     re-observation that cost a request), `hash` (change detection), `is_t0` (a labelling anchor),
+//     `horizons_done` (bitmask of horizons already labelled for a t0 row) and `focus` (the row was a
+//     watchlist / open-token row when written: the only rows that keep raw JSON).
+//   - `mints` is a per-mint summary the sweep scheduler reads instead of scanning snapshots.
+//   - feed_members is keyed on (t, feed, rank): the refresh tick is the run.
+//   - chain_events and verdicts are created here (one schema owner) but written by R-02 / L-01.
+export const SCHEMA_VERSION = 1;
+export const HORIZONS_SEC = [3600, 7200, 21600, 86400, 259200];
+/** Every horizon labelled: the bitmask value of `horizons_done` for a finished t0 row. */
+export const ALL_HORIZONS_MASK = (1 << HORIZONS_SEC.length) - 1;
+export const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS recorder_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS feed_members (
+  t     INTEGER NOT NULL,                  -- refresh tick (unix ms) the list was observed at
+  feed  TEXT NOT NULL,                     -- the data layer's discovery sub-feed id (jup:toptrending-1h, ds:boosts-top, ...)
+  rank  INTEGER NOT NULL,
+  mint  TEXT NOT NULL,
+  PRIMARY KEY (t, feed, rank)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS feed_members_mint_t ON feed_members (mint, t);
+
+CREATE TABLE IF NOT EXISTS token_snapshots (
+  snap_id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  mint               TEXT NOT NULL,
+  t                  INTEGER NOT NULL,     -- unix ms when the record was fetched (the newest part's fetchedAt)
+  kind               TEXT NOT NULL,        -- 'live' | 'sweep'
+  hash               TEXT NOT NULL,        -- change-detection hash of the normalised columns
+  is_t0              INTEGER NOT NULL DEFAULT 0,
+  horizons_done      INTEGER NOT NULL DEFAULT 0,
+  next_due_t         INTEGER NOT NULL DEFAULT 0, -- t0 rows: when the labeler should look at this row next
+  focus              INTEGER NOT NULL DEFAULT 0,
+  symbol             TEXT, name TEXT,      -- stored FIREWALLED: control/bidi/zero-width stripped, length-capped
+  launchpad          TEXT,
+  created_at         INTEGER,
+  age_sec            INTEGER,
+  price_usd          REAL, mcap REAL, mcap_resolved REAL, mcap_flagged INTEGER, fdv REAL, liquidity_usd REAL,
+  vol_m5 REAL, vol_h1 REAL, vol_h6 REAL, vol_h24 REAL,
+  buys_m5 INTEGER, sells_m5 INTEGER, buys_h1 INTEGER, sells_h1 INTEGER, buys_h24 INTEGER, sells_h24 INTEGER,
+  chg_m5 REAL, chg_h1 REAL, chg_h6 REAL, chg_h24 REAL,
+  pair_address       TEXT, dex TEXT, pair_created_at INTEGER,
+  src_market         TEXT NOT NULL,        -- 'dexscreener' | 'jupiter-tokens' | 'none'
+  holder_count       INTEGER, holders_chg_pct REAL,
+  top_holders_pct    REAL, dev_pct REAL, dev_mints INTEGER,
+  organic_score      REAL,
+  num_traders_h1     INTEGER, net_buyers_h1 INTEGER,
+  buy_vol_h1 REAL, sell_vol_h1 REAL,
+  mint_auth_enabled  INTEGER, freeze_auth_enabled INTEGER,
+  is_verified INTEGER, is_sus INTEGER,
+  src_audit          TEXT,
+  rug_score REAL, lp_locked_pct REAL, src_risk TEXT,
+  sources            TEXT NOT NULL,        -- JSON array of SourceId that contributed
+  raw_json           TEXT                  -- normalised Token+Pair+Stats+Audit record; focus rows only; pruned after 7 d
+);
+CREATE INDEX IF NOT EXISTS token_snapshots_mint_t ON token_snapshots (mint, t);
+CREATE INDEX IF NOT EXISTS token_snapshots_t ON token_snapshots (t);
+CREATE INDEX IF NOT EXISTS token_snapshots_t0_pending ON token_snapshots (next_due_t) WHERE is_t0 = 1 AND horizons_done < ${ALL_HORIZONS_MASK};
+
+CREATE TABLE IF NOT EXISTS mints (
+  mint        TEXT PRIMARY KEY,
+  first_t     INTEGER NOT NULL,
+  last_live_t INTEGER NOT NULL,            -- newest 'live' snapshot
+  last_any_t  INTEGER NOT NULL,            -- newest snapshot of any kind
+  last_t0_t   INTEGER NOT NULL,            -- newest is_t0 anchor
+  last_hash   TEXT NOT NULL,
+  snapshots   INTEGER NOT NULL DEFAULT 0
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS mints_last_live ON mints (last_live_t);
+
+CREATE TABLE IF NOT EXISTS sweeps (
+  sweep_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+  started_at  INTEGER NOT NULL,
+  finished_at INTEGER,
+  mints       INTEGER NOT NULL,            -- mints re-observed
+  calls       INTEGER NOT NULL,            -- DexScreener token-batch calls issued (30 mints each)
+  answered    INTEGER NOT NULL DEFAULT 0,  -- mints DexScreener returned a pair for
+  error       TEXT
+);
+
+CREATE TABLE IF NOT EXISTS chain_events (
+  mint      TEXT NOT NULL,
+  t         INTEGER NOT NULL,
+  slot      INTEGER,
+  signature TEXT NOT NULL,
+  kind      TEXT NOT NULL,
+  actor     TEXT,
+  amount    REAL,
+  evidence  TEXT NOT NULL,
+  PRIMARY KEY (signature, kind)
+);
+CREATE INDEX IF NOT EXISTS chain_events_mint_t ON chain_events (mint, t);
+
+CREATE TABLE IF NOT EXISTS outcomes (
+  mint         TEXT NOT NULL,
+  t0           INTEGER NOT NULL,
+  horizon_sec  INTEGER NOT NULL,
+  t1           INTEGER,                    -- the observation used (first at/after t0+horizon, within 2x); NULL when unobserved
+  label        TEXT NOT NULL,              -- 'rug' | 'dead' | 'fade' | 'flat' | 'runner' | 'unobserved'
+  label_tier   TEXT NOT NULL,              -- 'keyless-proxy' | 'chain-verified'
+  mcap_ratio   REAL, liq_ratio REAL, price_ratio REAL,
+  max_mcap_ratio REAL,
+  evidence     TEXT NOT NULL,              -- JSON: the numbers and the rule that fired
+  labeler_version TEXT NOT NULL,
+  PRIMARY KEY (mint, t0, horizon_sec)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS outcomes_label ON outcomes (label, horizon_sec);
+
+CREATE TABLE IF NOT EXISTS verdicts (
+  verdict_id   INTEGER PRIMARY KEY AUTOINCREMENT,
+  mint         TEXT NOT NULL,
+  t            INTEGER NOT NULL,
+  pack         TEXT NOT NULL,
+  pack_version TEXT NOT NULL,
+  model        TEXT,
+  verdict      TEXT,
+  rug_p        REAL,
+  confidence   REAL,
+  score        REAL,
+  cost_usd     REAL, wall_ms INTEGER,
+  input_hash   TEXT NOT NULL,
+  run_file     TEXT
+);
+CREATE INDEX IF NOT EXISTS verdicts_mint_t ON verdicts (mint, t);
+`;

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

@@ -0,0 +1,191 @@
+// Normalised record -> snapshot columns. Pure functions over the data layer's `EnrichedRow` (the
+// screener's normalised Token+Pair+Stats+Audit record, AI-SUITE-DESIGN §4.1 "hook on the data layer's
+// normaliser") and over a bare `DsTokenView` (what an outcome sweep gets back). The change-detection
+// hash covers every stored column except the ones derived from the clock (t, age_sec), so a refresh
+// that returns the same numbers writes nothing.
+import { createHash } from 'node:crypto';
+/** Max stored length of a symbol / name (firewalled strings, SPEC §5.3). */
+export const SYMBOL_MAX = 16;
+export const NAME_MAX = 64;
+/**
+ * Terminal/model safety for stored strings: drop control, bidi, zero-width and BOM code points,
+ * collapse whitespace, cap the length. Same intent as the prototype's `clean()`; names are never
+ * fed to a model raw (they go through the Analyst firewall when they are).
+ */
+export function cleanText(s, max) {
+    if (s === null || s === undefined)
+        return null;
+    let out = '';
+    for (const ch of String(s).normalize('NFC')) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20 || (cp >= 0x7f && cp <= 0x9f))
+            continue;
+        if (cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0x2060 || cp === 0xfeff)
+            continue;
+        if ((cp >= 0x200e && cp <= 0x200f) || (cp >= 0x202a && cp <= 0x202e) || (cp >= 0x2066 && cp <= 0x2069))
+            continue;
+        out += ch;
+    }
+    out = out.replace(/\s+/g, ' ').trim();
+    return out.length > max ? out.slice(0, max) + '…' : out;
+}
+const fin = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const bool = (v) => (v === null || v === undefined ? null : v ? 1 : 0);
+/** Snapshot columns from the screener's normalised row; `hash` is the exact-record hash (identity, not the change rule). */
+export function fromEnrichedRow(r) {
+    const { token, pair, stats, audit } = r;
+    const h1 = stats?.perWindow.h1 ?? null;
+    const src = pair.source === 'dexscreener' ? 'dexscreener' : pair.source === 'jupiter-tokens' ? 'jupiter-tokens' : 'none';
+    const columns = {
+        mint: r.mint,
+        symbol: cleanText(token.symbol, SYMBOL_MAX),
+        name: cleanText(token.name, NAME_MAX),
+        launchpad: token.launchpad ?? null,
+        created_at: fin(token.createdAt ?? pair.createdAt),
+        price_usd: fin(pair.priceUsd),
+        mcap: fin(pair.mcap),
+        mcap_resolved: fin(r.mcap?.value),
+        mcap_flagged: r.mcap ? (r.mcap.flagged ? 1 : 0) : null,
+        fdv: fin(pair.fdv),
+        liquidity_usd: fin(pair.liquidityUsd),
+        vol_m5: fin(pair.volume.m5), vol_h1: fin(pair.volume.h1), vol_h6: fin(pair.volume.h6), vol_h24: fin(pair.volume.h24),
+        buys_m5: fin(pair.txns.m5?.buys), sells_m5: fin(pair.txns.m5?.sells),
+        buys_h1: fin(pair.txns.h1?.buys), sells_h1: fin(pair.txns.h1?.sells),
+        buys_h24: fin(pair.txns.h24?.buys), sells_h24: fin(pair.txns.h24?.sells),
+        chg_m5: fin(pair.priceChange.m5), chg_h1: fin(pair.priceChange.h1), chg_h6: fin(pair.priceChange.h6), chg_h24: fin(pair.priceChange.h24),
+        pair_address: pair.pairAddress || null,
+        dex: pair.dex && pair.dex !== 'unknown' ? pair.dex : null,
+        pair_created_at: src === 'dexscreener' ? fin(pair.createdAt) : null,
+        src_market: src,
+        holder_count: fin(stats?.holderCount),
+        holders_chg_pct: fin(stats?.holders24hDelta),
+        top_holders_pct: fin(audit?.top10Pct),
+        dev_pct: fin(audit?.devPct),
+        dev_mints: fin(audit?.devMints),
+        organic_score: fin(stats?.organicScore),
+        num_traders_h1: fin(h1?.numTraders),
+        net_buyers_h1: fin(h1?.numNetBuyers),
+        buy_vol_h1: fin(h1?.buyVol),
+        sell_vol_h1: fin(h1?.sellVol),
+        mint_auth_enabled: bool(audit?.mintAuthority),
+        freeze_auth_enabled: bool(audit?.freezeAuthority),
+        is_verified: bool(token.verified),
+        is_sus: bool(token.sus),
+        src_audit: audit?.source ?? null,
+        rug_score: fin(audit?.rugScore),
+        lp_locked_pct: fin(audit?.lpLockedPct),
+        src_risk: null,
+        sources: [...r.sources],
+    };
+    const t = Math.max(token.fetchedAt || 0, pair.fetchedAt || 0, stats?.fetchedAt ?? 0, audit?.fetchedAt ?? 0);
+    return { columns, t, hash: hashColumns(columns), raw: { token, pair, stats: stats ?? null, audit: audit ?? null, mcap: r.mcap ?? null } };
+}
+/**
+ * Snapshot columns from a DexScreener pair view (an outcome sweep). Identity fields the pair does not
+ * carry (launchpad, created_at from Jupiter) are taken from `base`, the mint's last stored row.
+ */
+export function fromDsView(mint, view, base, fetchedAt) {
+    const empty = {
+        mint, symbol: base?.symbol ?? null, name: base?.name ?? null, launchpad: base?.launchpad ?? null, created_at: base?.created_at ?? null,
+        price_usd: null, mcap: null, mcap_resolved: null, mcap_flagged: null, fdv: null, liquidity_usd: null,
+        vol_m5: null, vol_h1: null, vol_h6: null, vol_h24: null, buys_m5: null, sells_m5: null, buys_h1: null, sells_h1: null, buys_h24: null, sells_h24: null,
+        chg_m5: null, chg_h1: null, chg_h6: null, chg_h24: null, pair_address: null, dex: null, pair_created_at: null, src_market: 'none',
+        holder_count: null, holders_chg_pct: null, top_holders_pct: null, dev_pct: null, dev_mints: null, organic_score: null,
+        num_traders_h1: null, net_buyers_h1: null, buy_vol_h1: null, sell_vol_h1: null, mint_auth_enabled: null, freeze_auth_enabled: null,
+        is_verified: null, is_sus: null, src_audit: null, rug_score: null, lp_locked_pct: null, src_risk: null, sources: [],
+    };
+    if (!view)
+        return { columns: empty, t: fetchedAt, hash: hashColumns(empty), raw: { note: 'no DexScreener pair returned' } };
+    const { pair, token } = view;
+    const columns = {
+        ...empty,
+        symbol: empty.symbol ?? cleanText(token.symbol, SYMBOL_MAX),
+        name: empty.name ?? cleanText(token.name, NAME_MAX),
+        launchpad: empty.launchpad ?? token.launchpad ?? null,
+        created_at: empty.created_at ?? fin(pair.createdAt),
+        price_usd: fin(pair.priceUsd), mcap: fin(pair.mcap), fdv: fin(pair.fdv), liquidity_usd: fin(pair.liquidityUsd),
+        vol_m5: fin(pair.volume.m5), vol_h1: fin(pair.volume.h1), vol_h6: fin(pair.volume.h6), vol_h24: fin(pair.volume.h24),
+        buys_m5: fin(pair.txns.m5?.buys), sells_m5: fin(pair.txns.m5?.sells), buys_h1: fin(pair.txns.h1?.buys), sells_h1: fin(pair.txns.h1?.sells),
+        buys_h24: fin(pair.txns.h24?.buys), sells_h24: fin(pair.txns.h24?.sells),
+        chg_m5: fin(pair.priceChange.m5), chg_h1: fin(pair.priceChange.h1), chg_h6: fin(pair.priceChange.h6), chg_h24: fin(pair.priceChange.h24),
+        pair_address: pair.pairAddress || null, dex: pair.dex || null, pair_created_at: fin(pair.createdAt),
+        src_market: 'dexscreener', sources: ['dexscreener'],
+    };
+    return { columns, t: pair.fetchedAt || fetchedAt, hash: hashColumns(columns), raw: { token, pair } };
+}
+/** Stable hash of the columns (key order fixed by the interface literal above). */
+export function hashColumns(c) {
+    return createHash('sha256').update(JSON.stringify(c)).digest('base64url').slice(0, 22);
+}
+/**
+ * Material change (task-1329 measurements). The live app holds a ~500-row pool that is re-enriched about
+ * once a minute and almost every memecoin price moves a little every time: "hash of the exact record"
+ * wrote ~4 rows/s (≈ 120 MB per 8 h day, columns only) and 1 % thresholds + a 5 min heartbeat still
+ * ≈ 120 MB/day, against the design's 10 MB estimate for 60 rows. A snapshot is worth a row when
+ * something MATERIAL moved against the LAST WRITTEN row (hysteresis: a slow drift is written once it adds
+ * up, a value sitting on a threshold never flaps): price / market cap / liquidity by ≥ 5 %, holders by
+ * ≥ 10 %, volumes by ≥ 20 %, trade counts by ≥ 25 %, a percentage-change field by ≥ 5 points, a share /
+ * score by ≥ 2 points, or any identity / authority / source field at all. The labels work on ratios of
+ * 0.5× and 2×, so 5 % resolution loses nothing they can see; the hourly t0 anchor and the heartbeat
+ * (30 min) bound how stale a stored row can be.
+ */
+export const MATERIAL = {
+    rel5: ['price_usd', 'mcap', 'mcap_resolved', 'fdv', 'liquidity_usd'],
+    rel10: ['holder_count'],
+    rel20: ['vol_m5', 'vol_h1', 'vol_h6', 'vol_h24', 'buy_vol_h1', 'sell_vol_h1'],
+    rel25: ['buys_m5', 'sells_m5', 'buys_h1', 'sells_h1', 'buys_h24', 'sells_h24', 'num_traders_h1', 'net_buyers_h1'],
+    abs5: ['chg_m5', 'chg_h1', 'chg_h6', 'chg_h24', 'holders_chg_pct'],
+    abs2: ['top_holders_pct', 'dev_pct', 'organic_score', 'rug_score', 'lp_locked_pct'],
+};
+const NUMERIC = new Set([...MATERIAL.rel5, ...MATERIAL.rel10, ...MATERIAL.rel20, ...MATERIAL.rel25, ...MATERIAL.abs5, ...MATERIAL.abs2]);
+/** Relative to the previous (written) value: 100 → 110 is a 10 % move, 0 → anything is a move. */
+function relMoved(a, b, frac) {
+    if (a === null || b === null)
+        return a !== b;
+    if (a === b)
+        return false;
+    if (a === 0)
+        return true;
+    return Math.abs(a - b) / Math.abs(a) >= frac;
+}
+function absMoved(a, b, unit) {
+    if (a === null || b === null)
+        return a !== b;
+    return Math.abs(a - b) >= unit;
+}
+/** True when `next` differs materially from `prev` (the last written row of the same mint). */
+export function isMaterialChange(prev, next) {
+    for (const k of MATERIAL.rel5)
+        if (relMoved(prev[k], next[k], 0.05))
+            return true;
+    for (const k of MATERIAL.rel10)
+        if (relMoved(prev[k], next[k], 0.10))
+            return true;
+    for (const k of MATERIAL.rel20)
+        if (relMoved(prev[k], next[k], 0.20))
+            return true;
+    for (const k of MATERIAL.rel25)
+        if (relMoved(prev[k], next[k], 0.25))
+            return true;
+    for (const k of MATERIAL.abs5)
+        if (absMoved(prev[k], next[k], 5))
+            return true;
+    for (const k of MATERIAL.abs2)
+        if (absMoved(prev[k], next[k], 2))
+            return true;
+    for (const k of COLUMN_NAMES) {
+        if (NUMERIC.has(k))
+            continue;
+        if (prev[k] !== next[k])
+            return true;
+    }
+    return prev.sources.join() !== next.sources.join();
+}
+/** Column names in insert order (everything in SnapshotColumns except `sources`, which is JSON). */
+export const COLUMN_NAMES = [
+    'mint', 'symbol', 'name', 'launchpad', 'created_at', 'price_usd', 'mcap', 'mcap_resolved', 'mcap_flagged', 'fdv', 'liquidity_usd',
+    'vol_m5', 'vol_h1', 'vol_h6', 'vol_h24', 'buys_m5', 'sells_m5', 'buys_h1', 'sells_h1', 'buys_h24', 'sells_h24',
+    'chg_m5', 'chg_h1', 'chg_h6', 'chg_h24', 'pair_address', 'dex', 'pair_created_at', 'src_market',
+    'holder_count', 'holders_chg_pct', 'top_holders_pct', 'dev_pct', 'dev_mints', 'organic_score', 'num_traders_h1', 'net_buyers_h1',
+    'buy_vol_h1', 'sell_vol_h1', 'mint_auth_enabled', 'freeze_auth_enabled', 'is_verified', 'is_sus', 'src_audit', 'rug_score', 'lp_locked_pct', 'src_risk',
+];

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

@@ -0,0 +1,52 @@
+// Outcome-sweep scheduling (AI-SUITE-DESIGN §4.1 "outcome": re-observe every recorded mint at the
+// horizons 1 h, 2 h, 6 h, 24 h, 72 h). Pure functions over the per-mint summary so the rule is testable
+// without a database.
+//
+// The rule. The app observes a token continuously while it is on screen (every refresh writes a row
+// when something changed, and a heartbeat row otherwise), so a horizon measured from any t0 while the
+// token stayed visible is already covered by the live rows. A re-observation is only needed once the
+// token has LEFT the screen: with L = the newest live observation of a mint and A = its newest
+// observation of any kind, horizon h is due iff
+//     h <= now - L < 2h      (the window [L+h, L+2h] is open; labels.md: first observation at or after
+//                             t0+h within 2x)
+//     A < L + h              (nothing, live or sweep, has been seen since the window opened)
+// One sweep row at `now` then serves every t0 of that mint whose window contains `now` — including the
+// earlier t0s (first sighting F): if the token was visible for less than h, L+h lands inside
+// [F+h, F+2h]; if it was visible longer, the live rows already covered F's horizon h.
+// Because a sweep row is `kind = 'sweep'`, it moves A but not L, so the same horizon is never re-swept
+// and the next horizon comes due relative to the same L: five re-observations per departure, no more.
+import { HORIZONS_SEC } from "./schema.js";
+/** Horizons due for one mint at `now`, smallest first. */
+export function dueHorizons(m, now, horizons = HORIZONS_SEC) {
+    const out = [];
+    const age = now - m.last_live_t;
+    for (const h of horizons) {
+        const ms = h * 1000;
+        if (age >= ms && age < 2 * ms && m.last_any_t < m.last_live_t + ms)
+            out.push(h);
+    }
+    return out;
+}
+/**
+ * The mints to re-observe now, at most `max`, soonest-closing window first. A mint with several horizons
+ * due at once (it left the screen hours ago and the app was closed) is listed once: one observation
+ * serves all of them.
+ */
+export function selectDue(rows, now, max, horizons = HORIZONS_SEC) {
+    const due = [];
+    for (const m of rows) {
+        const hs = dueHorizons(m, now, horizons);
+        if (!hs.length)
+            continue;
+        const h = hs[0];
+        due.push({ mint: m.mint, horizon_sec: h, closes_at: m.last_live_t + 2 * h * 1000 });
+    }
+    due.sort((a, b) => a.closes_at - b.closes_at || a.mint.localeCompare(b.mint));
+    return due.slice(0, max);
+}
+/** Bounds on `last_live_t` outside which no horizon can be due: [now - 2*maxH, now - minH]. */
+export function dueBounds(now, horizons = HORIZONS_SEC) {
+    const min = Math.min(...horizons) * 1000;
+    const max = Math.max(...horizons) * 1000;
+    return { from: now - 2 * max, to: now - min };
+}

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

@@ -0,0 +1,52 @@
+// LARP verdict join (task-1359): the app writes the LARP detector's settled product verdicts into the recorder's
+// `verdicts` table (pack `larp-check`, via @dexterm/packs recordVerdict) and the LARP eval reads them back here,
+// joined to the outcome labels. The prototype DB (research/task-1287/recorder/history.sqlite) has the same
+// `verdicts` + `outcomes` columns, so the join runs on both. Reads never throw on a missing table.
+import { isPositive } from "./labels.js";
+/** The pack name a LARP-detector verdict is stored under. */
+export const LARP_PACK = 'larp-check';
+/** The product-assessment verdicts the analyst may return (analyst/session.ts). */
+export const LARP_VERDICTS = ['REAL_PRODUCT', 'EARLY_BUT_REAL', 'LARP', 'UNVERIFIABLE'];
+const hasTable = (db, name) => {
+    try {
+        return !!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Join every recorded LARP verdict to an outcome label: the latest t0 anchor of the same mint at or before the
+ * verdict, no more than `slackSec` earlier (default 10 % of the horizon). The label then describes what the coin
+ * did from (just before) the verdict to the horizon; an anchor long before the verdict would let the verdict see
+ * most of the outcome window, so it is not matched. `unobserved` labels count as unmatched.
+ */
+export function readLarpJoin(db, horizonSec, slackSec = Math.round(horizonSec * 0.1)) {
+    const out = { horizon_sec: horizonSec, slack_sec: slackSec, verdicts_recorded: 0, rows: [], outcomes_at_horizon: 0, outcome_counts: {}, unobserved_at_horizon: 0 };
+    if (hasTable(db, 'outcomes')) {
+        const counts = db.prepare('SELECT label, COUNT(*) AS n FROM outcomes WHERE horizon_sec = ? GROUP BY label').all(horizonSec);
+        for (const c of counts) {
+            if (c.label === 'unobserved') {
+                out.unobserved_at_horizon += c.n;
+                continue;
+            }
+            out.outcome_counts[c.label] = c.n;
+            out.outcomes_at_horizon += c.n;
+        }
+    }
+    if (!hasTable(db, 'verdicts'))
+        return out;
+    const verdicts = db.prepare('SELECT mint, t, verdict, confidence FROM verdicts WHERE pack = ? AND verdict IS NOT NULL ORDER BY t').all(LARP_PACK);
+    out.verdicts_recorded = verdicts.length;
+    const canJoin = hasTable(db, 'outcomes');
+    const q = canJoin ? db.prepare('SELECT t0, label, label_tier FROM outcomes WHERE mint = ? AND horizon_sec = ? AND t0 <= ? AND t0 >= ? ORDER BY t0 DESC LIMIT 1') : null;
+    for (const v of verdicts) {
+        const o = q?.get(v.mint, horizonSec, v.t, v.t - slackSec * 1000);
+        const observed = o && o.label !== 'unobserved' ? o : null;
+        out.rows.push({
+            mint: v.mint, t: v.t, verdict: v.verdict, confidence: typeof v.confidence === 'number' ? v.confidence : null,
+            label: observed?.label ?? null, tier: observed?.label_tier ?? null, positive: observed ? isPositive(observed.label, observed.label_tier) : null, t0: observed?.t0 ?? null,
+        });
+    }
+    return out;
+}