dexterm-cli 0.2.0 → 0.2.2

package/dist/packages/narratives/src/normalize.js

@@ -0,0 +1,179 @@
+// dexterm narratives (task-1818): text normalisation for meme coins. A coin needs no real project to run, so the
+// signal is the THEME its name/ticker carries: ticker puns, leetspeak, glued words, copy-cat affixes ("BABY X",
+// "X 2.0", "X INU"), emoji. Everything here is UNTRUSTED token text: it is firewalled (control/bidi/zero-width
+// stripped, length-capped) before use, only ever matched and hashed, and never interpreted as instructions.
+import { clean, classify, loadDefaultLexicon } from '../../packs/src/index.js';
+/** Copy-cat / filler affixes: kept as weak tokens (they say "spawn of X", not what X is). */
+export const AFFIXES = new Set([
+    'baby', 'mini', 'mega', 'super', 'giga', 'ultra', 'little', 'lil', 'big', 'real', 'official', 'og', 'the', 'of', 'a', 'an',
+    'on', 'in', 'and', 'my', 'your', 'coin', 'token', 'sol', 'solana', 'classic', 'ceo', 'dao', 'v2', 'v3', 'new', 'x', 'mr',
+    'mrs', 'king', 'queen', 'lord', 'sir', 'is', 'it', 'to', 'for', 'with', 'wif', 'inu', 'pump', 'fun', 'meme', 'memecoin',
+    'ai', 'gpt', 'bot', 'agent', 'jr', 'junior', 'pro', 'max', 'plus', 'black', 'white', 'red', 'blue', 'green', 'gold', 'golden',
+]);
+/** Affixes stripped from glued tickers without a vocabulary (longest first). */
+const PREFIX_AFFIXES = ['official', 'little', 'super', 'baby', 'mini', 'mega', 'giga', 'real', 'lil', 'the', 'mr', 'og'];
+const SUFFIX_AFFIXES = ['coin', 'inu']; // not ai / sol: they end real words (bonsai, consol)
+/** Tokens that carry no theme at all (dropped). */
+const STOP = new Set(['', 'de', 'la', 'le', 'el', 'by', 'at', 'or', 'no', 'so', 'be', 'we', 'us', 'me', 'he', 'she']);
+const EMOJI = [
+    [/[🐸]/gu, ' frog '], [/[🐶🐕🦮🐩]/gu, ' dog '], [/[🐱🐈😺😸]/gu, ' cat '], [/[🐧]/gu, ' penguin '], [/[🦛]/gu, ' hippo '],
+    [/[🤖]/gu, ' robot '], [/[🧠]/gu, ' brain '], [/[🎃]/gu, ' pumpkin '], [/[👻]/gu, ' ghost '], [/[🚀]/gu, ' rocket '],
+    [/[🐒🐵🦍]/gu, ' monkey '], [/[🐿]/gu, ' squirrel '], [/[🦈]/gu, ' shark '], [/[🐋🐳]/gu, ' whale '], [/[🍌]/gu, ' banana '],
+    [/[🐂🐮🐄]/gu, ' cow '], [/[🐷🐖]/gu, ' pig '], [/[🦆]/gu, ' duck '], [/[🐻]/gu, ' bear '], [/[🔥]/gu, ' fire '],
+    [/[💎]/gu, ' diamond '], [/[🌙🌕]/gu, ' moon '], [/[🇺🇸]/gu, ' usa '], [/[🎄🎅]/gu, ' christmas '], [/[🐉🐲]/gu, ' dragon '],
+];
+const LEET = { '0': 'o', '1': 'i', '3': 'e', '4': 'a', '5': 's', '7': 't', '8': 'b' };
+/** A base vocabulary used to split glued tickers ("MOODENG" -> moo deng); grows from names seen (learnWords). */
+const BASE_VOCAB = [
+    'dog', 'cat', 'frog', 'pepe', 'doge', 'shib', 'moo', 'deng', 'pnut', 'nut', 'peanut', 'hat', 'wif', 'trump', 'elon', 'musk',
+    'moon', 'sun', 'pump', 'chill', 'guy', 'girl', 'boy', 'man', 'king', 'cash', 'gold', 'baby', 'ai', 'agent', 'bot', 'brain',
+    'rot', 'gork', 'grok', 'pig', 'cow', 'ape', 'monkey', 'penguin', 'hippo', 'bear', 'bull', 'duck', 'goat', 'fish', 'shark',
+    'whale', 'banana', 'pizza', 'coffee', 'beer', 'fire', 'water', 'god', 'jesus', 'devil', 'ghost', 'pumpkin', 'santa', 'pop',
+    'jelly', 'fart', 'butt', 'coin', 'stonk', 'rich', 'poor', 'happy', 'sad', 'mad', 'cute', 'tiny', 'fat', 'big', 'lil',
+    'bonk', 'wojak', 'chad', 'sigma', 'giga', 'troll', 'meme', 'tard', 'retard', 'degen', 'ser', 'gm', 'based', 'usa', 'china',
+    'japan', 'neko', 'inu', 'kitty', 'puppy', 'mew', 'meow', 'woof', 'bark', 'quack', 'quantum', 'robot', 'cyber', 'dark',
+];
+/** Collapse every run of a repeated letter to one ("doggg" -> "dog", "moodeng" -> "modeng"): the fuzzy key form. */
+export const squash = (s) => s.replace(/(.)\1+/gu, '$1');
+function deLeet(w) {
+    if (!/\p{L}/u.test(w) || !/\d/.test(w))
+        return w; // pure words and pure numbers stay
+    return w.replace(/[0134578]/g, (d) => LEET[d] ?? d);
+}
+function splitCamel(s) {
+    // DogWifHat -> Dog Wif Hat, but leave ALLCAPS and lowercase runs alone
+    return s.replace(/(\p{Ll})(\p{Lu})/gu, '$1 $2').replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, '$1 $2');
+}
+/** Words of a firewalled string: emoji mapped to words, camelCase split, lowercased, leet decoded, runs of 3+ cut to 2. */
+export function words(raw) {
+    let s = raw;
+    for (const [re, w] of EMOJI)
+        s = s.replace(re, w);
+    // apostrophes join ("don't" -> dont, not "don" + "t": the audit's "Don't Nut" joined a "don" narrative)
+    s = splitCamel(s).normalize('NFKC').toLowerCase().replace(/^\$+/, '').replace(/\$/g, ' ').replace(/(\p{L})['’](\p{L})/gu, '$1$2');
+    return s.split(/[^\p{L}\p{N}]+/u).map(deLeet).map((w) => w.replace(/(.)\1{2,}/gu, '$1$1')).filter((w) => !STOP.has(w));
+}
+/** Learned vocabulary (words seen standalone in >= 2 coin names) + the base list; used to split glued tickers. */
+export class Vocab {
+    seen = new Map();
+    words = new Set(BASE_VOCAB);
+    constructor(extra = []) { for (const w of extra)
+        if (w.length >= 3 && /^\p{L}+$/u.test(w))
+            this.words.add(w); }
+    learn(ws) {
+        for (const w of new Set(ws)) {
+            if (w.length < 3 || w.length > 12 || !/^\p{L}+$/u.test(w) || AFFIXES.has(w))
+                continue;
+            const n = (this.seen.get(w) ?? 0) + 1;
+            this.seen.set(w, n);
+            if (n === 2)
+                this.words.add(w);
+        }
+    }
+    has(w) { return this.words.has(w) || AFFIXES.has(w); }
+    get size() { return this.words.size; }
+    /** Split a glued word into <= 3 known pieces (each >= 2 chars, at least one >= 3), longest-first DP; null if none.
+     *  Fallback with no vocabulary: a leading or trailing copy-cat affix ("BABYFROGGO" -> baby + froggo, "FROGINU"
+     *  -> frog + inu) even when the meme word has not been seen standalone yet (a copy can launch before the vocab knows it). */
+    segment(w) {
+        if (w.length < 5 || w.length > 24 || this.words.has(w))
+            return null;
+        const dp = this.segmentDp(w);
+        if (dp)
+            return dp;
+        for (const p of PREFIX_AFFIXES)
+            if (w.startsWith(p) && w.length - p.length >= 3)
+                return [p, w.slice(p.length)];
+        for (const x of SUFFIX_AFFIXES)
+            if (w.endsWith(x) && w.length - x.length >= 3)
+                return [w.slice(0, -x.length), x];
+        return null;
+    }
+    segmentDp(w) {
+        const n = w.length;
+        const best = new Array(n + 1).fill(null);
+        best[0] = [];
+        for (let i = 0; i < n; i++) {
+            const cur = best[i];
+            if (!cur || cur.length >= 3)
+                continue;
+            for (let j = Math.min(n, i + 12); j >= i + 2; j--) {
+                const piece = w.slice(i, j);
+                if (!(piece.length >= 3 ? this.has(piece) : piece === 'ai' || piece === 'gm' || piece === 'og'))
+                    continue;
+                const cand = [...cur, piece];
+                const prev = best[j];
+                if (!prev || cand.length < prev.length)
+                    best[j] = cand;
+            }
+        }
+        const r = best[n];
+        return r && r.length >= 2 && r.some((p) => p.length >= 3) ? r : null;
+    }
+}
+const lexicon = () => loadDefaultLexicon();
+/**
+ * Normalise one coin's text. `description` is optional (most launches carry none in the recorder).
+ * Weights: ticker 1.2, name 1.0, description 0.4, glued-word pieces 0.7; affixes x0.25.
+ */
+export function normalize(input, vocab) {
+    const symbol = clean(input.symbol, 16);
+    const name = clean(input.name, 64);
+    const desc = clean(input.description, 512);
+    const out = [];
+    const seen = new Map();
+    const add = (t, w, from) => {
+        if (!t || t.length > 24 || /^\d+$/.test(t) && t.length > 4)
+            return;
+        const affix = AFFIXES.has(t) || /^\d+$/.test(t);
+        const ww = affix ? w * 0.25 : w;
+        const e = seen.get(t);
+        if (e) {
+            e.w = Math.max(e.w, ww);
+            return;
+        }
+        const tok = { t, w: ww, affix, from };
+        seen.set(t, tok);
+        out.push(tok);
+    };
+    const fields = [[symbol, 1.2, 'symbol'], [name, 1.0, 'name'], [desc, 0.4, 'description']];
+    for (const [text, w, from] of fields) {
+        if (!text)
+            continue;
+        const ws = from === 'description' ? words(text).slice(0, 40) : words(text);
+        // glued words are split only where gluing is the norm: the ticker, or a name that is one word ("#BOYCOTTPUMPFUN");
+        // splitting ordinary name words pulled strangers in ("HEY EVERYONE" via "ever")
+        const glued = from === 'symbol' || (from === 'name' && ws.length === 1);
+        for (const x of ws) {
+            add(x, w, from);
+            if (vocab && glued) {
+                const seg = vocab.segment(x);
+                if (seg) {
+                    for (const p of seg)
+                        add(p, 0.7, 'split');
+                    // "babymoodeng" -> also "moodeng" at full weight: the copy-cat affix is not part of the meme
+                    const rest = seg.filter((p) => !AFFIXES.has(p));
+                    if (rest.length && rest.length < seg.length)
+                        add(rest.join(''), w, from);
+                }
+            }
+        }
+    }
+    const strong = out.filter((t) => !t.affix && t.from !== 'description' && t.t.length >= 2);
+    // the core meme word: a ticker word also in the name; else the ticker (a glued "BABYPNUT" -> its non-affix piece);
+    // else the longest name word
+    const nameWords = words(name);
+    const symWords = symbol ? words(symbol) : [];
+    const inBoth = strong.find((t) => t.from === 'symbol' && nameWords.includes(t.t));
+    let core = inBoth?.t ?? null;
+    if (!core && symWords.length === 1 && symWords[0].length >= 3 && !AFFIXES.has(symWords[0])) {
+        const seg = vocab?.segment(symWords[0]);
+        const piece = seg?.some((p) => AFFIXES.has(p)) ? seg.filter((p) => !AFFIXES.has(p)).join('') || undefined : undefined;
+        core = piece ?? symWords[0];
+    }
+    if (!core)
+        core = [...strong].filter((t) => t.from === 'name').sort((a, b) => b.t.length - a.t.length || b.w - a.w)[0]?.t ?? strong[0]?.t ?? null;
+    const keys = [...new Set(strong.map((t) => squash(t.t)).filter((k) => k.length >= 3))];
+    const cls = classify({ mint: '', symbol, name, description: desc || null }, lexicon());
+    return { tokens: out, keys, core, themes: cls.labels.map((l) => l.theme), symbol, name };
+}

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

@@ -0,0 +1,93 @@
+import { NarrativeTracker } from "./tracker.js";
+const SQL = `SELECT mint, t, kind, symbol, name, price_usd, mcap, liquidity_usd, vol_m5, vol_h1, vol_h6, vol_h24,
+  num_traders_h1, net_buyers_h1, holder_count FROM token_snapshots WHERE t > ? AND t <= ? ORDER BY t`;
+const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+export function rowToSample(r) {
+    return { mint: String(r.mint), t: Number(r.t), price: n(r.price_usd), mcap: n(r.mcap), liq: n(r.liquidity_usd), vol5m: n(r.vol_m5), vol1h: n(r.vol_h1), vol6h: n(r.vol_h6), vol24h: n(r.vol_h24), traders1h: n(r.num_traders_h1), netBuyers1h: n(r.net_buyers_h1), holders: n(r.holder_count) };
+}
+/** Replay [from, to] through a tracker (created if not given). Returns it after the last tick. */
+export async function replayRecorder(db, opts, hooks = {}) {
+    const tickMs = opts.tickMs ?? 300_000;
+    const tr = opts.tracker ?? new NarrativeTracker({ ...opts, tickMs });
+    const stmt = db.prepare(SQL);
+    let t = opts.from;
+    let slice = performance.now();
+    while (t < opts.to) {
+        if (opts.yieldMs && performance.now() - slice >= opts.yieldMs) {
+            await new Promise((r) => setImmediate(r));
+            slice = performance.now();
+        }
+        const end = Math.min(opts.to, t + tickMs);
+        const rows = stmt.all(t, end).filter((r) => !opts.liveOnly || r.kind === 'live');
+        const fresh = [];
+        const seen = new Set();
+        for (const r of rows) {
+            const m = String(r.mint);
+            if (tr.coins.has(m) || seen.has(m))
+                continue;
+            seen.add(m);
+            fresh.push({ mint: m, t: Number(r.t), symbol: r.symbol ?? null, name: r.name ?? null });
+        }
+        if (hooks.beforeInterval)
+            await hooks.beforeInterval(t, end, tr, fresh);
+        await tr.addCoins(fresh);
+        if (hooks.afterCoins)
+            await hooks.afterCoins(t, end, tr, fresh);
+        for (const r of rows)
+            tr.addSample(rowToSample(r));
+        tr.tick(end, true);
+        if (hooks.afterTick)
+            await hooks.afterTick(end, tr);
+        t = end;
+    }
+    return tr;
+}
+/** The live board: replay the last `lookbackMs` (default 26 h) of the recorder into a fresh tracker. */
+export async function trackerFromRecorder(db, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const from = now - (opts.lookbackMs ?? 26 * 3_600_000);
+    const fine = opts.tickMs ?? 300_000;
+    // older history at 15-min ticks (lifecycle only needs "an hour ago" and the 24 h max), the last 2 h at the fine tick
+    const split = Math.max(from, now - 2 * 3_600_000);
+    const tracker = opts.tracker ?? new NarrativeTracker({ ...opts, tickMs: fine });
+    if (split > from)
+        await replayRecorder(db, { ...opts, from, to: split, tickMs: Math.max(fine, 900_000), tracker });
+    return replayRecorder(db, { ...opts, from: split, to: now, tickMs: fine, tracker });
+}
+/**
+ * A cached tracker over a recorder DB for the app surfaces (TUI panel, MCP tools, coin pane, watch rules).
+ * The first refresh replays the last `lookbackMs` (26 h); later refreshes replay only the rows since the last
+ * tick onto the same tracker, so ids stay stable for the life of the process and a refresh costs one interval.
+ */
+export class RecorderNarratives {
+    tr = null;
+    lastT = 0;
+    busy = null;
+    db;
+    opts;
+    constructor(db, opts = {}) { this.db = db; this.opts = opts; }
+    get tracker() { return this.tr; }
+    async refresh(now = Date.now()) {
+        if (this.busy)
+            return this.busy;
+        if (this.tr && now - this.lastT < (this.opts.minRefreshMs ?? 60_000))
+            return this.tr;
+        this.busy = (async () => {
+            const from = this.tr ? this.lastT : now - (this.opts.lookbackMs ?? 26 * 3_600_000);
+            const tickMs = this.opts.tickMs ?? 300_000;
+            // replay whole ticks, then one partial tick up to now
+            const yieldMs = this.opts.yieldMs ?? 40; // keep the app's render loop alive during the first 26 h build
+            this.tr = this.tr
+                ? await replayRecorder(this.db, { ...this.opts, from, to: now, tickMs, tracker: this.tr, yieldMs })
+                : await trackerFromRecorder(this.db, { ...this.opts, now, lookbackMs: this.opts.lookbackMs, tickMs, yieldMs });
+            this.lastT = now;
+            return this.tr;
+        })();
+        try {
+            return await this.busy;
+        }
+        finally {
+            this.busy = null;
+        }
+    }
+}

package/dist/packages/narratives/src/tracker.js

@@ -0,0 +1,328 @@
+// dexterm narratives (task-1818): the tracker. Coins come in (first sighting: name/ticker/description), market
+// samples come in (price, liquidity, rolling volume, traders), and on each tick it recomputes, per narrative and
+// per window (5m / 1h / 6h / 24h): coin count, new-coin rate, volume share, unique-trader growth, the top runner
+// and its drawdown, a lifecycle state, a copy-cat saturation flag and a memetic traction score.
+//
+// Everything is MEASURED HEAT from recorded/live market data, never advice. Point-in-time by construction: a tick
+// at `now` only reads samples with t <= now that were already ingested (the replay feeds rows in time order).
+// Lifecycle rules (LIFECYCLE_RULES below, also in the docs page) are evaluated in order; the first match wins.
+import { Clusterer, clusterLabel } from "./cluster.js";
+import { LexicalEmbedder } from "./embed.js";
+import { normalize, Vocab } from "./normalize.js";
+export const WINDOWS = { '5m': 300_000, '1h': 3_600_000, '6h': 21_600_000, '24h': 86_400_000 };
+/** Thresholds of the lifecycle and saturation rules (owner: maintainers; changing one changes the docs page). */
+export const RULES = {
+    deadVol1h: 1_000, // narrative 1 h volume under this and no new coin in 6 h -> dead
+    sparkAgeMs: 3_600_000, // a narrative younger than 1 h is a spark
+    ignitionVol1h: 5_000, // ignition needs at least this much 1 h volume ...
+    ignitionGrowth: 2, // ... at least 2x its 1 h volume an hour ago (floored at deadVol1h) ...
+    ignitionTraders: 0.5, // ... and a new coin in the last hour OR +50% unique traders (1 h)
+    fadeFromMax: 0.4, // 1 h volume <= 40% of its 24 h max -> fading
+    fadeGrowth: 0.6, // or <= 60% of an hour ago
+    saturationMembers: 5, // copy-cat saturation: >= 5 coins,
+    saturationNew6h: 3, // >= 3 of them new in 6 h,
+    saturationCopyShare: 0.25, // and the coins after the 3 oldest hold < 25% of the 1 h volume
+    runnerMinLiq: 10_000, // a top runner must have a sellable pool
+    staleMs: 6 * 3_600_000, // a coin sample older than this does not count as live volume
+};
+export const LIFECYCLE_RULES = [
+    ['dead', 'no member sampled in 6 h, or 1 h volume < $1k with no new coin in 6 h'],
+    ['spark', 'first coin < 1 h ago (just formed)'],
+    ['ignition', '1 h volume >= $5k and >= 2x the 1 h volume an hour ago, with a new coin in the hour or unique traders (1 h) +50%'],
+    ['fading', '1 h volume <= 40% of its 24 h max, or <= 60% of an hour ago'],
+    ['peak', 'otherwise: hot, near its 24 h high, growth under 2x'],
+];
+const clip01 = (x) => (Number.isFinite(x) ? Math.max(0, Math.min(1, x)) : 0);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+export class NarrativeTracker {
+    clusterer;
+    embedder;
+    vocab = new Vocab();
+    coins = new Map();
+    hist = new Map();
+    snap = new Map();
+    lastTick = -Infinity;
+    tickMs;
+    listeners = [];
+    recent = new Set(); // coins sampled in the last 24 h
+    stats = { coins: 0, samples: 0, ticks: 0, embedMs: 0, tickMs: 0 };
+    constructor(opts = {}) {
+        this.embedder = opts.embedder ?? new LexicalEmbedder();
+        // the lexical embedder only links coins that share a word, so the "hot clusters" candidate set is wasted work there
+        this.clusterer = new Clusterer({ ...opts, hotMax: opts.hotMax ?? (this.embedder.id.startsWith('lexical') ? 0 : 300) });
+        this.tickMs = opts.tickMs ?? 60_000;
+    }
+    onTransition(fn) { this.listeners.push(fn); return () => { this.listeners = this.listeners.filter((f) => f !== fn); }; }
+    /** First sightings, in time order. Social links are used only as extra theme words (their handle), never fetched. */
+    async addCoins(inputs) {
+        const fresh = inputs.filter((c) => !this.coins.has(c.mint));
+        if (!fresh.length)
+            return;
+        const norms = fresh.map((c) => {
+            const handle = c.socials ? Object.values(c.socials).filter(Boolean).map((u) => String(u).split(/[/?#@]/).filter(Boolean).pop() ?? '').join(' ') : '';
+            const desc = [c.description ?? '', handle].filter(Boolean).join(' ') || null;
+            const n = normalize({ symbol: c.symbol, name: c.name, description: desc }, this.vocab);
+            this.vocab.learn(n.tokens.filter((t) => t.from === 'name' || t.from === 'symbol').map((t) => t.t));
+            return n;
+        });
+        const t0 = performance.now();
+        const vecs = await this.embedder.embed(norms);
+        this.stats.embedMs += performance.now() - t0;
+        fresh.forEach((c, i) => {
+            if (this.coins.has(c.mint))
+                return;
+            const a = this.clusterer.assign(c.mint, c.t, norms[i], vecs[i]);
+            this.coins.set(c.mint, { mint: c.mint, firstT: c.t, narrative: a.id, spawn: a.spawn, symbol: norms[i].symbol, name: norms[i].name, core: norms[i].core, last: null, firstLiqPrice: null, peakPrice: null, lastT: c.t });
+            this.stats.coins++;
+        });
+    }
+    /** A market sample for a known coin (unknown mints are ignored: call addCoins first). */
+    addSample(s) {
+        const c = this.coins.get(s.mint);
+        if (!c)
+            return;
+        this.stats.samples++;
+        c.last = s;
+        c.lastT = s.t;
+        this.recent.add(s.mint);
+        const p = s.price ?? null;
+        if (p != null && p > 0 && num(s.liq) >= RULES.runnerMinLiq) {
+            if (c.firstLiqPrice == null)
+                c.firstLiqPrice = p;
+            c.peakPrice = Math.max(c.peakPrice ?? 0, p);
+        }
+    }
+    /** Recompute every narrative's metrics if at least tickMs passed (or force). Returns true when it ran. */
+    tick(now, force = false) {
+        if (!force && now - this.lastTick < this.tickMs)
+            return false;
+        const t0 = performance.now();
+        this.lastTick = now;
+        this.stats.ticks++;
+        const acc = new Map();
+        const tot = { '5m': 0, '1h': 0, '6h': 0, '24h': 0 };
+        const vkey = { '5m': 'vol5m', '1h': 'vol1h', '6h': 'vol6h', '24h': 'vol24h' };
+        const get = (id) => {
+            let a = acc.get(id);
+            if (!a)
+                acc.set(id, (a = { w: { '5m': { coins: 0, newCoins: 0, volume: 0 }, '1h': { coins: 0, newCoins: 0, volume: 0 }, '6h': { coins: 0, newCoins: 0, volume: 0 }, '24h': { coins: 0, newCoins: 0, volume: 0 } }, traders: 0, vol1hByMember: [], runner: null, runnerX: 0, repeated: 0, liveMembers: 0, newest6h: 0 }));
+            return a;
+        };
+        for (const mint of this.recent) {
+            const c = this.coins.get(mint);
+            if (now - c.lastT > WINDOWS['24h']) {
+                this.recent.delete(mint);
+                continue;
+            }
+            const s = c.last;
+            const a = get(c.narrative);
+            const age = now - s.t;
+            const live = age <= RULES.staleMs;
+            if (live)
+                a.liveMembers++;
+            for (const k of Object.keys(WINDOWS)) {
+                if (age <= Math.max(WINDOWS[k], 900_000))
+                    a.w[k].coins++;
+                if (live) {
+                    const v = num(s[vkey[k]]);
+                    a.w[k].volume += v;
+                    tot[k] += v;
+                }
+            }
+            if (live) {
+                a.traders += num(s.traders1h);
+                a.vol1hByMember.push([c, num(s.vol1h)]);
+            }
+            if (live && c.firstLiqPrice && s.price && num(s.liq) >= RULES.runnerMinLiq) {
+                const x = s.price / c.firstLiqPrice;
+                if (x > a.runnerX) {
+                    a.runnerX = x;
+                    a.runner = c;
+                }
+            }
+        }
+        // new-coin counts and repeated-name velocity come from the member lists (first sightings), not samples
+        for (const [id, a] of acc) {
+            const cl = this.clusterer.clusters.get(id);
+            const main = mainCore(cl);
+            for (let i = cl.members.length - 1; i >= 0; i--) {
+                const m = cl.members[i];
+                const age = now - m.t;
+                if (age < 0)
+                    continue;
+                if (age > WINDOWS['24h'])
+                    break;
+                for (const k of Object.keys(WINDOWS))
+                    if (age <= WINDOWS[k])
+                        a.w[k].newCoins++;
+                if (age <= WINDOWS['1h'] && main && m.core && squashEq(m.core, main))
+                    a.repeated++;
+                if (age <= WINDOWS['6h'])
+                    a.newest6h++;
+            }
+        }
+        const next = new Map();
+        const ranked = [];
+        const newCoinVol1h = [...this.recent].reduce((s, m) => { const c = this.coins.get(m); return s + (now - c.firstT <= WINDOWS['24h'] && now - c.lastT <= RULES.staleMs ? num(c.last?.vol1h) : 0); }, 0);
+        for (const [id, a] of acc) {
+            const cl = this.clusterer.clusters.get(id);
+            // history only for real narratives (>= 2 coins): a singleton's 24 h history was 2/3 of the replay's memory
+            const h = cl.members.length > 1 ? this.pushHist(id, now, a.w['1h'].volume, a.traders) : [];
+            const ago = histAt(h, now - WINDOWS['1h']);
+            const max24 = h.reduce((m, x) => (now - x.t <= WINDOWS['24h'] ? Math.max(m, x.vol1h) : m), 0);
+            const V1 = a.w['1h'].volume;
+            const windows = {};
+            for (const k of Object.keys(WINDOWS)) {
+                const tr = histAt(h, now - WINDOWS[k]);
+                // history points are 15 min apart, so a 5-min trader growth would really be ~15-20 min: null there, never mislabelled
+                windows[k] = { coins: a.w[k].coins, newCoins: a.w[k].newCoins, newPerHour: a.w[k].newCoins / (WINDOWS[k] / 3_600_000), volume: a.w[k].volume, volumeShare: tot[k] > 0 ? a.w[k].volume / tot[k] : null, traders: a.traders, tradersGrowth: k !== '5m' && tr && tr.traders > 0 ? a.traders / tr.traders - 1 : null };
+            }
+            const growth = ago ? V1 / Math.max(ago.vol1h, RULES.deadVol1h) : null;
+            const age = now - cl.firstT;
+            let lc, rule;
+            if (a.liveMembers === 0 || (V1 < RULES.deadVol1h && a.newest6h === 0))
+                [lc, rule] = LIFECYCLE_RULES[0];
+            else if (age < RULES.sparkAgeMs)
+                [lc, rule] = LIFECYCLE_RULES[1];
+            else if (V1 >= RULES.ignitionVol1h && growth != null && growth >= RULES.ignitionGrowth && (windows['1h'].newCoins >= 1 || (windows['1h'].tradersGrowth ?? 0) >= RULES.ignitionTraders))
+                [lc, rule] = LIFECYCLE_RULES[2];
+            else if ((max24 > 0 && V1 <= RULES.fadeFromMax * max24) || (growth != null && growth <= RULES.fadeGrowth))
+                [lc, rule] = LIFECYCLE_RULES[3];
+            else
+                [lc, rule] = LIFECYCLE_RULES[4];
+            // copy-cat saturation: many recent spawns, and the spawns after the first three are not getting the volume
+            const byAge = [...a.vol1hByMember].sort((x, y) => x[0].spawn - y[0].spawn);
+            const copyVol = byAge.slice(3).reduce((s, x) => s + x[1], 0);
+            const saturated = cl.members.length >= RULES.saturationMembers && a.newest6h >= RULES.saturationNew6h && V1 > 0 && copyVol / V1 < RULES.saturationCopyShare;
+            const comp = {
+                growth: growth == null ? null : clip01(Math.log2(Math.max(growth, 1e-6)) / 2 + 0.5),
+                spawnRate: clip01(windows['1h'].newCoins / 5),
+                nameVelocity: clip01(a.repeated / 5),
+                newCoinVolumeShare: newCoinVol1h > 0 ? clip01((V1 / newCoinVol1h) * 10) : null,
+                breadth: clip01(a.vol1hByMember.filter(([c]) => num(c.last?.liq) >= RULES.runnerMinLiq).length / 5),
+                holderOverlap: null,
+            };
+            const W = { growth: 0.3, spawnRate: 0.2, nameVelocity: 0.15, newCoinVolumeShare: 0.25, breadth: 0.1, holderOverlap: 0.1 };
+            let sw = 0, sv = 0;
+            for (const [k, v] of Object.entries(comp))
+                if (v != null) {
+                    sw += W[k];
+                    sv += W[k] * v;
+                }
+            const score = lc === 'dead' ? 0 : Math.round((sw > 0 ? sv / sw : 0) * 100);
+            const r = a.runner;
+            const snap = {
+                id, label: cl.members.length > 1 ? clusterLabel(cl) : (cl.members[0].symbol || cl.seedCore || '?'), modelLabel: cl.modelLabel ?? null, theme: this.clusterer.topTheme(cl), members: cl.members.length, firstT: cl.firstT,
+                ageMin: Math.round(age / 60_000), lifecycle: lc, lifecycleRule: rule, saturated, score, components: comp, rank: null, windows,
+                vol1hAgo: ago ? ago.vol1h : null, vol1hMax24h: max24 || null,
+                topRunner: r && r.last?.price && r.peakPrice ? { mint: r.mint, symbol: r.symbol, x: a.runnerX, drawdownPct: (r.last.price / r.peakPrice - 1) * 100, liq: num(r.last.liq) } : null,
+                repeatedName1h: a.repeated, holderOverlap: null,
+            };
+            next.set(id, snap);
+            if (cl.members.length >= 2 && lc !== 'dead')
+                ranked.push(snap);
+        }
+        ranked.sort((x, y) => y.score - x.score || y.windows['1h'].volume - x.windows['1h'].volume || (x.id < y.id ? -1 : 1));
+        ranked.forEach((s, i) => { s.rank = i + 1; });
+        for (const [id, s] of next) {
+            const prev = this.snap.get(id)?.lifecycle ?? null;
+            if (prev !== s.lifecycle && s.members >= 2)
+                for (const fn of this.listeners)
+                    fn({ id, label: s.label, from: prev, to: s.lifecycle, t: now, rank: s.rank, members: s.members });
+        }
+        // narratives with no recent member keep their last state as dead
+        for (const [id, s] of this.snap)
+            if (!next.has(id) && s.lifecycle !== 'dead')
+                next.set(id, { ...s, lifecycle: 'dead', lifecycleRule: LIFECYCLE_RULES[0][1], rank: null, score: 0 });
+            else if (!next.has(id))
+                next.set(id, s);
+        this.snap = next;
+        if (this.stats.ticks % 12 === 0)
+            for (const [id, h] of this.hist)
+                if (!h.length || now - h[h.length - 1].t > WINDOWS['24h'] + 3_600_000)
+                    this.hist.delete(id);
+        this.stats.tickMs += performance.now() - t0;
+        return true;
+    }
+    pushHist(id, t, vol1h, traders) {
+        let h = this.hist.get(id);
+        if (!h)
+            this.hist.set(id, (h = []));
+        // one point per 15 min is enough for "an hour ago" and the 24 h max (the newest point is overwritten in between)
+        const last = h[h.length - 1];
+        if (last && h.length > 1 && t - h[h.length - 2].t < 900_000) {
+            last.t = t;
+            last.vol1h = vol1h;
+            last.traders = traders;
+        }
+        else
+            h.push({ t, vol1h, traders });
+        while (h.length && t - h[0].t > WINDOWS['24h'] + 3_600_000)
+            h.shift();
+        return h;
+    }
+    /** Narratives by rank (ranked first, then by 1 h volume). */
+    top(limit = 20, opts = {}) {
+        const min = opts.minMembers ?? 2;
+        return [...this.snap.values()].filter((s) => s.members >= min && (opts.includeDead || s.lifecycle !== 'dead'))
+            .sort((a, b) => (a.rank ?? 1e9) - (b.rank ?? 1e9) || b.windows['1h'].volume - a.windows['1h'].volume).slice(0, limit);
+    }
+    detail(id) {
+        const cl = this.clusterer.clusters.get(id);
+        if (!cl)
+            return null;
+        const s = this.snap.get(id) ?? this.emptySnap(cl);
+        const memberList = cl.members.map((m) => {
+            const c = this.coins.get(m.mint);
+            const p = c.last?.price ?? null;
+            return { mint: m.mint, symbol: m.symbol, name: m.name, spawn: m.spawn, firstT: m.t, price: p, liq: c.last?.liq ?? null, vol1h: c.last?.vol1h ?? null, x: p && c.firstLiqPrice ? p / c.firstLiqPrice : null };
+        });
+        return { ...s, memberList };
+    }
+    /** Narrative of one coin at the last tick (point-in-time in a replay). */
+    narrativeOf(mint) {
+        const c = this.coins.get(mint);
+        if (!c)
+            return null;
+        const cl = this.clusterer.clusters.get(c.narrative);
+        const s = this.snap.get(c.narrative) ?? null;
+        return {
+            mint, narrative: c.narrative, label: s?.label ?? clusterLabel(cl), theme: this.clusterer.topTheme(cl), spawn: c.spawn,
+            members: cl.members.filter((m) => m.t <= this.lastTick || this.lastTick === -Infinity).length,
+            lifecycle: s?.lifecycle ?? null, rank: s?.rank ?? null, score: s?.score ?? null, saturated: s?.saturated ?? false,
+            isTopRunner: s?.topRunner?.mint === mint, vol1hShare: s?.windows['1h'].volumeShare ?? null, newPerHour1h: s?.windows['1h'].newPerHour ?? null,
+            growth1h: s && s.vol1hAgo != null ? s.windows['1h'].volume / Math.max(s.vol1hAgo, RULES.deadVol1h) : null,
+        };
+    }
+    setModelLabel(id, label) { const c = this.clusterer.clusters.get(id); if (c)
+        c.modelLabel = label; }
+    get lastTickAt() { return Number.isFinite(this.lastTick) ? this.lastTick : null; }
+    emptySnap(cl) {
+        const z = () => ({ coins: 0, newCoins: 0, newPerHour: 0, volume: 0, volumeShare: null, traders: 0, tradersGrowth: null });
+        return { id: cl.id, label: clusterLabel(cl), modelLabel: cl.modelLabel ?? null, theme: this.clusterer.topTheme(cl), members: cl.members.length, firstT: cl.firstT, ageMin: 0, lifecycle: 'spark', lifecycleRule: LIFECYCLE_RULES[1][1], saturated: false, score: 0, components: {}, rank: null, windows: { '5m': z(), '1h': z(), '6h': z(), '24h': z() }, vol1hAgo: null, vol1hMax24h: null, topRunner: null, repeatedName1h: 0, holderOverlap: null };
+    }
+}
+function mainCore(c) {
+    let best = null, n = 0;
+    for (const [k, v] of c.cores)
+        if (v > n) {
+            best = k;
+            n = v;
+        }
+    return best;
+}
+const squashEq = (a, b) => a.replace(/(.)\1+/gu, '$1') === b;
+/** The newest history point at or before t (null if none within 2 ticks' tolerance of the window start). */
+function histAt(h, t) {
+    let lo = 0, hi = h.length - 1, r = null;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (h[mid].t <= t) {
+            r = h[mid];
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return r;
+}

package/dist/packages/packs/src/skill-care.js

@@ -19,6 +19,14 @@ export const SKILL_CARE_SCHEMA = 'dexterm/packs/skill-care/1';
 export const DEFAULT_MIN_NEW_COINS = 150;
 /** Tolerance (absolute MCC) for calling the frozen canary "regressed" or "held". */
 export const DEFAULT_CANARY_NOISE = 0.05;
+/**
+ * A split cutoff as ISO time for the split_rule text (task-1982). An empty split leaves the MAX_SAFE_INTEGER
+ * sentinel, which is outside the Date range: `toISOString()` would throw RangeError, so it reads as "none" instead.
+ */
+export function cutoffIso(cutoff) {
+    const d = new Date(cutoff);
+    return Number.isNaN(d.getTime()) ? 'none (empty test split)' : d.toISOString();
+}
 /**
  * Re-split an eval set so the NEWEST coins are a held-out TEST window the tuning never sees. By default (and
  * whenever `windowDays` is not given) the newest `testFrac` of coins by t0 are TEST (count-based, so TRAIN stays
@@ -31,14 +39,14 @@ export function rollingSplit(set, opts = {}) {
     if (opts.windowDays !== undefined) {
         const anchor = opts.anchor ?? set.rows.reduce((m, r) => Math.max(m, r.t0), 0);
         cutoff = anchor - opts.windowDays * 86_400_000;
-        rule = `rolling window: coins with t0 in the newest ${opts.windowDays} day(s) (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST window; never tuned on`;
+        rule = `rolling window: coins with t0 in the newest ${opts.windowDays} day(s) (t0 ≥ ${cutoffIso(cutoff)}) are the held-out TEST window; never tuned on`;
     }
     else {
         const frac = opts.testFrac ?? 0.3;
         const sorted = [...set.rows].sort((a, b) => a.t0 - b.t0);
         const idx = Math.min(sorted.length, Math.floor(sorted.length * (1 - frac)));
         cutoff = sorted[idx]?.t0 ?? Number.MAX_SAFE_INTEGER;
-        rule = `rolling window: the newest ${Math.round(frac * 100)}% of coins by t0 (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST window; never tuned on`;
+        rule = `rolling window: the newest ${Math.round(frac * 100)}% of coins by t0 (t0 ≥ ${cutoffIso(cutoff)}) are the held-out TEST window; never tuned on`;
     }
     const rows = set.rows.map((r) => ({ ...r, split: r.t0 >= cutoff ? 'test' : 'train' }));
     const train = rows.filter((r) => r.split === 'train');