dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/kb-skill-cmd.js

@@ -0,0 +1,240 @@
+// `dexterm kb …` / `dexterm skill …` (task-1377): the user's overlay of the knowledge base and the analyst
+// skills, under ~/.dexterm/kb/entries/<id>.md and ~/.dexterm/skills/<name>.md (DEXTERM_HOME overrides).
+// A user file with a bundled id overrides it, a new id is added, bundled files are never edited in place.
+//   list              bundled + user entries with their origin; skipped files with the reason
+//   show <id>         print the file in effect (origin and path on stderr)
+//   new <id>          write a starter file (refuses a bundled id: use edit), open $EDITOR, check it
+//   edit <id>         copy the bundled file into the overlay if needed, open $EDITOR, check it
+//   check [id|file]   validate (frontmatter, size, KB live-token rule, skill read-tools only); exit 1 on an error
+//   reset <id>        move the user file to <dir>/.reset/ (the bundled entry is back in effect)
+//   path [id]         the overlay directory, or the file in effect for <id>
+// The MCP server, the analyst and Jarvis re-read the merged set on the next call: no restart. No network, no model.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { OverlayStore, checkKb, checkSkill, dextermHome, userDir, writeOverlayFile, resetOverlayFile, templateFor, journalContent, READ_ONLY_TOOLS, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR, KB_ID, SKILL_NAME, KB_RULE, } from '../../mcp/src/index.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** The analyst plugin's skills (the copies `/dexterm:<skill>` runs) come first; the MCP server's own copies fill any gap. */
+export const SKILL_SOURCES = [
+    { dir: path.resolve(HERE, '..', 'assets', 'claude', 'plugin', 'skills'), layout: 'nested' },
+    { dir: BUNDLED_SKILLS_DIR, layout: 'flat' },
+];
+export const KB_SOURCES = [{ dir: BUNDLED_KB_DIR, layout: 'flat' }];
+const stores = new Map();
+function storeFor(kind, env) {
+    const home = dextermHome(env);
+    const key = `${kind}\n${home}`;
+    let s = stores.get(key);
+    if (!s) {
+        s = new OverlayStore({ kind, bundled: kind === 'kb' ? KB_SOURCES : SKILL_SOURCES, readTools: READ_ONLY_TOOLS, home: () => home });
+        stores.set(key, s);
+    }
+    return s;
+}
+/** The hot-reloading merged KB for a DEXTERM_HOME (doctor, the CLI). */
+export const kbStore = (env = process.env) => storeFor('kb', env);
+/** The hot-reloading merged skills for a DEXTERM_HOME (the analyst's per-turn plugin dir, doctor, the CLI). */
+export const skillStore = (env = process.env) => storeFor('skill', env);
+const NOUN = { kb: 'KB entry', skill: 'skill' };
+export function usage(kind) {
+    return kind === 'kb'
+        ? `usage: dexterm kb list | show <id> | new <id> | edit <id> | check [<id>|<file>] | reset <id> | path [<id>]
+  files: ~/.dexterm/kb/entries/<id>.md (DEXTERM_HOME overrides): same id as a bundled entry overrides it, a new id adds one.
+  The MCP server, the analyst and Jarvis read the merged set on their next call (no restart). ${KB_RULE}`
+        : `usage: dexterm skill list | show <name> | new <name> | edit <name> | check [<name>|<file>] | reset <name> | path [<name>]
+  files: ~/.dexterm/skills/<name>.md (DEXTERM_HOME overrides): same name as a bundled skill overrides it, a new name adds one.
+  A skill is read-only guidance: \`tools:\` may name only read tools and nothing may name a trade/sign/arm/ticket tool.`;
+}
+function check(kind, raw, stem, file) {
+    return kind === 'kb' ? checkKb(raw, stem, 'user', file) : checkSkill(raw, stem, READ_ONLY_TOOLS, 'user', file);
+}
+/** Print one check result; returns true when the file passes. The KB rule line is printed once by the caller. */
+function report(io, file, res) {
+    const ok = res.errors.length === 0;
+    io.stdout.write(`${ok ? '✓' : '✗'} ${file}\n`);
+    for (const e of res.errors)
+        io.stdout.write(`    error: ${e}\n`);
+    for (const w of res.warnings)
+        if (!w.startsWith('rule: '))
+            io.stdout.write(`    warn:  ${w}\n`);
+    return ok;
+}
+function openEditor(io, file) {
+    if (io.editor)
+        return io.editor(file) === 0 ? 'edited' : 'failed';
+    const ed = (io.env.VISUAL || io.env.EDITOR || '').trim();
+    if (!ed || io.isTTY === false)
+        return 'no-editor';
+    // `sh -c '$EDITOR "$1"'` so an EDITOR with arguments ("code -w") works; the path is passed as $1, never interpolated.
+    const r = spawnSync('/bin/sh', ['-c', `${ed} "$1"`, 'sh', file], { stdio: 'inherit', env: io.env });
+    return r.status === 0 ? 'edited' : 'failed';
+}
+function readOr(file) { try {
+    return fs.readFileSync(file, 'utf8');
+}
+catch {
+    return '';
+} }
+/** After new/edit: open the editor, journal the change, check the file, say what the loader will do. */
+function editAndCheck(kind, io, home, id, file, before, action) {
+    const ed = openEditor(io, file);
+    if (ed === 'no-editor')
+        io.stdout.write(`no $EDITOR (or not a terminal): edit ${file} with any editor; \`dexterm ${kind} check ${id}\` validates it\n`);
+    if (ed === 'failed')
+        io.stderr.write(`dexterm ${kind}: the editor exited with an error; the file is kept as it is\n`);
+    const after = readOr(file);
+    if (after !== before)
+        journalContent(home, { kind, action, id, before, after });
+    const res = check(kind, after, id, file);
+    const ok = report(io, file, res);
+    if (kind === 'kb')
+        io.stdout.write(`  rule: ${KB_RULE}\n`);
+    if (!ok) {
+        io.stdout.write(`  the loader skips this file until it passes (the bundled ${NOUN[kind]} stays in effect); fix it, or \`dexterm ${kind} reset ${id}\`\n`);
+        return 1;
+    }
+    io.stdout.write(`  in effect on the next MCP/analyst/Jarvis call (no restart)\n`);
+    return 0;
+}
+function listMerged(kind, io, m) {
+    io.stdout.write(`${m.dir}  (${m.bundled} bundled · ${m.user} user: ${m.overridden} override${m.overridden === 1 ? '' : 's'}, ${m.added} new · ${m.skipped.length} skipped)\n`);
+    for (const e of m.entries) {
+        const tag = e.origin === 'bundled' ? 'bundled' : e.overrides ? 'user (overrides bundled)' : 'user (new)';
+        const what = String((kind === 'kb' ? e.meta.title : e.meta.description) ?? '').slice(0, 90);
+        io.stdout.write(`  ${e.id.padEnd(32)} ${tag.padEnd(25)} ${what}\n`);
+    }
+    for (const s of m.skipped)
+        io.stdout.write(`! ${s.id.padEnd(32)} skipped: ${s.reason}\n`);
+}
+export async function kbSkillCommand(kind, argv, io) {
+    const home = dextermHome(io.env);
+    const store = storeFor(kind, io.env);
+    const dir = userDir(kind, home);
+    const [cmd, arg] = argv;
+    const bad = (s) => { io.stderr.write(`dexterm ${kind}: ${s}\n${usage(kind)}\n`); return 2; };
+    const idOk = (id) => !!id && (kind === 'kb' ? KB_ID : SKILL_NAME).test(id);
+    const userFile = (id) => path.join(dir, `${id}.md`);
+    const bundledOf = (id) => store.bundled().find((e) => e.id === id) ?? null;
+    switch (cmd) {
+        case undefined:
+        case 'list': {
+            listMerged(kind, io, store.get());
+            return 0;
+        }
+        case 'show': {
+            if (!arg)
+                return bad('show needs an id');
+            const e = store.get().entries.find((x) => x.id === arg);
+            if (!e) {
+                io.stderr.write(`dexterm ${kind}: no ${NOUN[kind]} "${arg}" (see: dexterm ${kind} list)\n`);
+                return 1;
+            }
+            io.stderr.write(`# ${e.origin}${e.overrides ? ' (overrides bundled)' : ''} · ${e.file}\n`);
+            io.stdout.write(readOr(e.file));
+            return 0;
+        }
+        case 'path': {
+            if (!arg) {
+                io.stdout.write(`${dir}\n`);
+                return 0;
+            }
+            const e = store.get().entries.find((x) => x.id === arg);
+            if (!e) {
+                io.stderr.write(`dexterm ${kind}: no ${NOUN[kind]} "${arg}"\n`);
+                return 1;
+            }
+            io.stdout.write(`${e.file}\n`);
+            return 0;
+        }
+        case 'new': {
+            if (!idOk(arg))
+                return bad(`new needs a ${kind === 'kb' ? 'KB id' : 'skill name'} (lowercase letters, digits, dashes)`);
+            if (bundledOf(arg)) {
+                io.stderr.write(`dexterm ${kind}: "${arg}" is bundled; \`dexterm ${kind} edit ${arg}\` makes an editable copy that overrides it\n`);
+                return 1;
+            }
+            if (fs.existsSync(userFile(arg))) {
+                io.stderr.write(`dexterm ${kind}: ${userFile(arg)} already exists; \`dexterm ${kind} edit ${arg}\`\n`);
+                return 1;
+            }
+            const file = writeOverlayFile(kind, home, arg, templateFor(kind, arg));
+            io.stdout.write(`wrote ${file}\n`);
+            return editAndCheck(kind, io, home, arg, file, '', 'new');
+        }
+        case 'edit': {
+            if (!idOk(arg))
+                return bad('edit needs an id');
+            let file = userFile(arg);
+            let before = readOr(file);
+            if (!fs.existsSync(file)) {
+                const b = bundledOf(arg);
+                if (!b) {
+                    io.stderr.write(`dexterm ${kind}: no ${NOUN[kind]} "${arg}" to edit; \`dexterm ${kind} new ${arg}\` starts one\n`);
+                    return 1;
+                }
+                // A copy of the bundled file, byte for byte; the bundled asset itself is never touched.
+                file = writeOverlayFile(kind, home, arg, readOr(b.file));
+                before = '';
+                io.stdout.write(`copied the bundled ${NOUN[kind]} to ${file} (it now overrides the bundled one; \`dexterm ${kind} reset ${arg}\` undoes it)\n`);
+            }
+            return editAndCheck(kind, io, home, arg, file, before, 'edit');
+        }
+        case 'check': {
+            let targets;
+            if (arg && (arg.includes('/') || arg.endsWith('.md')))
+                targets = [{ file: path.resolve(arg), stem: path.basename(arg) === 'SKILL.md' ? path.basename(path.dirname(path.resolve(arg))) : path.basename(arg, '.md') }];
+            else if (arg) {
+                const f = fs.existsSync(userFile(arg)) ? userFile(arg) : bundledOf(arg)?.file;
+                if (!f) {
+                    io.stderr.write(`dexterm ${kind}: no ${NOUN[kind]} "${arg}"\n`);
+                    return 1;
+                }
+                targets = [{ file: f, stem: arg }];
+            }
+            else {
+                let names = [];
+                try {
+                    names = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).sort();
+                }
+                catch { /* no overlay yet */ }
+                targets = names.map((n) => ({ file: path.join(dir, n), stem: n.slice(0, -3) }));
+                if (!targets.length) {
+                    io.stdout.write(`no user ${kind === 'kb' ? 'KB entries' : 'skills'} in ${dir} (the ${store.bundled().length} bundled are in use)\n`);
+                    return 0;
+                }
+            }
+            let failed = 0;
+            for (const t of targets) {
+                let st = null;
+                try {
+                    st = fs.lstatSync(t.file);
+                }
+                catch { /* missing */ }
+                if (!st || !st.isFile()) {
+                    io.stdout.write(`✗ ${t.file}\n    error: ${st?.isSymbolicLink() ? 'a symlink: overlay files must be regular files' : 'not a regular file'}\n`);
+                    failed++;
+                    continue;
+                }
+                if (!report(io, t.file, check(kind, readOr(t.file), t.stem, t.file)))
+                    failed++;
+            }
+            if (kind === 'kb')
+                io.stdout.write(`rule: ${KB_RULE}\n`);
+            io.stdout.write(failed ? `${failed} of ${targets.length} refused (the loader skips them; bundled entries stay in effect)\n` : `${targets.length} ok\n`);
+            return failed ? 1 : 0;
+        }
+        case 'reset': {
+            if (!idOk(arg))
+                return bad('reset needs an id');
+            const bak = resetOverlayFile(kind, home, arg);
+            if (!bak) {
+                io.stdout.write(`no user ${NOUN[kind]} "${arg}" in ${dir}; nothing to reset\n`);
+                return 0;
+            }
+            io.stdout.write(`moved your ${NOUN[kind]} to ${bak}\n  ${bundledOf(arg) ? `the bundled "${arg}" is back in effect` : `"${arg}" is no longer offered`} on the next call\n`);
+            return 0;
+        }
+        default: return bad(`unknown subcommand "${cmd}"`);
+    }
+}

package/dist/packages/cli/src/larp-record.js

@@ -0,0 +1,21 @@
+// task-1359: persist a settled LARP-detector verdict into the recorder's `verdicts` table (pack `larp-check`) so
+// `dexterm backtest --subject larp` can later score it against the outcome labels. Before this, verdicts lived
+// only in memory (state.larpByMint) and no accuracy could ever be measured. Best-effort: no recorder, no table
+// or a failed write is a silent no-op — the analyst turn never depends on it.
+import { createHash } from 'node:crypto';
+import { recordVerdict } from '../../packs/src/index.js';
+import { LARP_PACK, LARP_VERDICTS } from '../../recorder/src/index.js';
+/** Returns true when a row was written. Unknown verdict strings are refused (the eval only scores the four classes). */
+export function recordLarpVerdict(db, v) {
+    if (!db || !LARP_VERDICTS.includes(v.verdict))
+        return false;
+    try {
+        // input_hash is a row key (the turn's tool inputs are not retained), not a cache key over the inputs
+        const hash = createHash('sha256').update(`${LARP_PACK}|${v.mint}|${v.t}|${v.verdict}`).digest('hex');
+        recordVerdict(db, { mint: v.mint, t: v.t, pack: LARP_PACK, pack_version: `task-1315/${v.skill}`, model: v.model, verdict: v.verdict, rug_p: null, confidence: v.confidence, score: null, cost_usd: null, wall_ms: null, input_hash: hash, run_file: null });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/packages/cli/src/live/copy.js

@@ -0,0 +1,80 @@
+// dexterm — live binding for COPY TRADING Tier 1 (task-1360): the follow store + wallet tracker for this run.
+// Live mode polls Helius history for every followed wallet (10 credits a call, through the data layer's limiter
+// and credit meter) and queues alerts the loop turns into toasts; fixtures / replay / keyless get the same store
+// with an honestly UNAVAILABLE tracker. Read-only: nothing here trades, signs or proposes.
+import { HeliusHistory, systemClock } from '../../../data/src/index.js';
+import { FollowStore, WalletTracker, defaultFollowsPath } from '../../../data/src/trade/copy/index.js';
+export class CopyLive {
+    store;
+    tracker;
+    pending = [];
+    /** Tier 3: the auto-mirror service, attached by the app once the plan service exists (null = no auto path at all). */
+    auto = null;
+    dl;
+    clock;
+    constructor(dl, opts = {}) {
+        const clock = opts.clock ?? dl?.clock ?? systemClock;
+        this.dl = dl;
+        this.clock = clock;
+        this.store = new FollowStore({ path: opts.followsPath === undefined ? defaultFollowsPath(opts.env) : opts.followsPath, clock });
+        const url = dl?.rpcPool.heliusUrl ?? null;
+        const history = opts.history !== undefined ? opts.history : (dl && url ? new HeliusHistory(dl.http, url) : null);
+        this.tracker = new WalletTracker({
+            follows: this.store, history, clock, solUsd: opts.solUsd, pollMs: opts.pollMs,
+            onAlert: (a) => { this.pending.push(a); if (this.pending.length > 20)
+                this.pending.splice(0, this.pending.length - 20); if (this.auto)
+                void this.auto.onAlert(a); },
+            onChange: () => { this.auto?.tick(); opts.onChange?.('copy'); },
+            available: () => (!dl || dl.health.isAvailable('helius') ? { ok: true } : { ok: false, why: `Helius is ${dl.health.state('helius')}; wallet polling paused` }),
+        });
+    }
+    follows() { return this.store.list(); }
+    status() { return this.tracker.status(); }
+    stats(addr) { return this.tracker.stats(addr); }
+    trades(addr) { return this.tracker.trades(addr); }
+    alerts(limit = 50) { return this.tracker.alerts(limit); }
+    /** Alerts raised since the last call (the loop toasts them). */
+    takeAlerts() { const a = this.pending; this.pending = []; return a; }
+    now() { return this.clock.now(); }
+    /**
+     * Tier 2: what the mirror checks need for a mint. The screen's numbers come first (the hint); the data layer
+     * fills the gaps: decimals from RPC mint info, price / liquidity / age from DexScreener when nothing on screen
+     * has them. Never throws; what cannot be learned stays null and the mirror shows it as unknown.
+     */
+    async mirrorMarket(mint, hint = {}) {
+        const m = { symbol: hint.symbol ?? null, decimals: hint.decimals ?? null, priceUsd: hint.priceUsd ?? null, priceAt: hint.priceAt ?? null, liqUsd: hint.liqUsd ?? null, mcapUsd: hint.mcapUsd ?? null, ageMs: hint.ageMs ?? null };
+        if (!this.dl)
+            return m;
+        if (m.decimals === null) {
+            try {
+                m.decimals = (await this.dl.rpc.mintInfo(mint)).decimals;
+            }
+            catch { /* stays unknown */ }
+        }
+        if (m.priceUsd === null || m.liqUsd === null || m.ageMs === null || m.decimals === null) {
+            try {
+                const v = (await this.dl.dexscreener.tokens([mint])).get(mint);
+                if (v) {
+                    if (m.priceUsd === null && v.pair.priceUsd > 0) {
+                        m.priceUsd = v.pair.priceUsd;
+                        m.priceAt = v.pair.fetchedAt;
+                    }
+                    if (m.liqUsd === null)
+                        m.liqUsd = v.pair.liquidityUsd;
+                    if (m.mcapUsd === null)
+                        m.mcapUsd = v.pair.mcap ?? v.pair.fdv;
+                    if (m.ageMs === null && v.pair.createdAt)
+                        m.ageMs = Math.max(0, this.clock.now() - v.pair.createdAt);
+                    if (m.symbol === null)
+                        m.symbol = v.token.symbol;
+                    if (m.decimals === null && v.token.decimals !== null)
+                        m.decimals = v.token.decimals;
+                }
+            }
+            catch { /* stays unknown */ }
+        }
+        return m;
+    }
+    start() { this.tracker.start(); }
+    stop() { this.tracker.stop(); }
+}

package/dist/packages/cli/src/live/flow.js

@@ -0,0 +1,233 @@
+/** Cache namespace `Store.enrich` writes DexScreener token views under (store.ts `NS.ds`). A test pins it. */
+export const DS_TOKEN_CACHE_NS = 'ds:token';
+/** TokenLive keeps the newest 60 tape trades (live/token.ts `slice(0, 60)`); a full tape may not reach back a whole minute. */
+export const TAPE_CAP = 60;
+/** A buy-share move smaller than this (percentage points) is "flat". */
+export const FLAT_PTS = 2;
+/** A previous-window sample may be off by this fraction of the window length. */
+export const PREV_TOLERANCE = 0.25;
+/** Minimum spacing between ring samples; older samples thin out to ~2 % of their age. */
+export const MIN_SAMPLE_GAP_MS = 5_000;
+const THIN_FRACTION = 0.02;
+const MAX_AGE_MS = 25 * 3_600_000;
+const MAX_SAMPLES = 1_000;
+/** The panel's timeframes, shortest first. `ds: null` = derived from the trade tape. */
+export const FLOW_WINDOWS = [
+    { label: '1m', ms: 60_000, ds: null },
+    { label: '5m', ms: 300_000, ds: 'm5' },
+    { label: '1h', ms: 3_600_000, ds: 'h1' },
+    { label: '6h', ms: 21_600_000, ds: 'h6' },
+    { label: '24h', ms: 86_400_000, ds: 'h24' },
+];
+/** Buy share of a window (0..1), null when nothing traded. */
+export function buyShare(c) {
+    if (!c)
+        return null;
+    const n = c.buys + c.sells;
+    return n > 0 ? c.buys / n : null;
+}
+/** Trend of the current window vs the previous one: buy-share change in percentage points. */
+export function trendCell(cur, prev, flatPts = FLAT_PTS) {
+    const a = buyShare(cur);
+    const b = buyShare(prev);
+    if (a === null || b === null)
+        return { na: 'no trades' };
+    const deltaPts = Math.round((a - b) * 100);
+    if (Math.abs((a - b) * 100) < flatPts)
+        return { dir: 0, deltaPts };
+    return { dir: a > b ? 1 : -1, deltaPts };
+}
+/** `45s` · `3m` · `2h` · `23h` (rounded up: never says 0 while still waiting). */
+export function fmtWait(ms) {
+    const s = Math.max(1, Math.ceil(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.ceil(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    return `${Math.ceil(m / 60)}h`;
+}
+/**
+ * Count trades with `from < t <= to` by side and sum their USD. The tape holds only the newest `cap`
+ * trades, so a full tape whose oldest trade is younger than `from` under-counts: `complete` is false.
+ */
+export function tapeWindow(trades, from, to, cap = TAPE_CAP) {
+    let buys = 0, sells = 0, buyUsd = 0, sellUsd = 0;
+    let oldest = Infinity;
+    for (const tr of trades) {
+        if (tr.t < oldest)
+            oldest = tr.t;
+        if (tr.t <= from || tr.t > to)
+            continue;
+        const usd = Number.isFinite(tr.usd) ? tr.usd : 0;
+        if (tr.side === 'buy') {
+            buys += 1;
+            buyUsd += usd;
+        }
+        else {
+            sells += 1;
+            sellUsd += usd;
+        }
+    }
+    const complete = trades.length < cap || oldest <= from;
+    return { buys, sells, buyUsd, sellUsd, complete };
+}
+/**
+ * The ring sample to compare against for a window of `ms`: the one closest to `latestT - ms` within
+ * ±PREV_TOLERANCE·ms. When none qualifies, `waitMs` is how long until the next sample becomes old enough.
+ */
+export function prevSample(samples, latestT, ms) {
+    const target = latestT - ms;
+    const tol = ms * PREV_TOLERANCE;
+    let best = null;
+    let bestD = Infinity;
+    let youngestTooNew = -Infinity; // the oldest sample still younger than (1 - tol) * ms
+    for (const s of samples) {
+        const d = Math.abs(s.t - target);
+        if (d <= tol && d < bestD) {
+            best = s;
+            bestD = d;
+        }
+        const age = latestT - s.t;
+        if (age < ms - tol && age > youngestTooNew)
+            youngestTooNew = age;
+    }
+    if (best)
+        return { sample: best };
+    const age = youngestTooNew === -Infinity ? 0 : youngestTooNew;
+    return { waitMs: Math.max(1, ms - tol - age) };
+}
+/** Thin a ring (oldest first): keep the newest; older samples need spacing ≥ max(5 s, 2 % of their age). */
+export function thinSamples(samples) {
+    if (samples.length <= 1)
+        return samples.slice();
+    const latest = samples[samples.length - 1].t;
+    const out = [samples[samples.length - 1]];
+    let lastKept = latest;
+    for (let i = samples.length - 2; i >= 0; i--) {
+        const s = samples[i];
+        const age = latest - s.t;
+        if (age > MAX_AGE_MS)
+            break;
+        if (lastKept - s.t >= Math.max(MIN_SAMPLE_GAP_MS, age * THIN_FRACTION)) {
+            out.push(s);
+            lastKept = s.t;
+        }
+    }
+    out.reverse();
+    return out.length > MAX_SAMPLES ? out.slice(out.length - MAX_SAMPLES) : out;
+}
+/** Per-mint ring of DexScreener flow samples plus the row builder for the panel. In-memory only. */
+export class FlowTracker {
+    rings = new Map();
+    lastRead = new Map();
+    clock;
+    minReadMs;
+    maxMints;
+    constructor(opts = {}) {
+        this.clock = opts.clock ?? (() => Date.now());
+        this.minReadMs = opts.minReadMs ?? 1_000;
+        this.maxMints = opts.maxMints ?? 24;
+    }
+    /** Add a DexScreener observation. Same-or-older `t` than the newest sample is ignored (cache re-reads). */
+    observe(mint, s) {
+        const ring = this.rings.get(mint) ?? [];
+        const last = ring[ring.length - 1];
+        if (last && s.t <= last.t)
+            return;
+        ring.push(s);
+        this.rings.delete(mint); // bump recency
+        this.rings.set(mint, thinSamples(ring));
+        while (this.rings.size > this.maxMints) {
+            const oldest = this.rings.keys().next().value;
+            this.rings.delete(oldest);
+            this.lastRead.delete(oldest);
+        }
+    }
+    samples(mint) {
+        return this.rings.get(mint) ?? [];
+    }
+    /**
+     * Pull the DexScreener pair `Store.enrich` cached for this mint (no network) into the ring. Throttled
+     * per mint; a cache miss or a pair without txns is a no-op.
+     */
+    syncFromCache(cache, mint) {
+        const now = this.clock();
+        const last = this.lastRead.get(mint);
+        if (last !== undefined && now - last < this.minReadMs)
+            return;
+        this.lastRead.set(mint, now);
+        let hit;
+        try {
+            hit = cache.get(DS_TOKEN_CACHE_NS, mint);
+        }
+        catch {
+            return;
+        }
+        const pair = hit?.value?.pair;
+        if (!hit || !pair || !pair.txns || !pair.volume)
+            return;
+        this.observe(mint, { t: pair.fetchedAt || hit.fetchedAt, txns: pair.txns, volume: pair.volume });
+    }
+    /**
+     * The panel rows: 1m from the tape, then the DexScreener windows. `tape` is the token view's trades
+     * and its panel status (the 1m window is anchored at the tape's fetch time, not the wall clock).
+     */
+    rows(mint, tape, now) {
+        const out = [];
+        const ring = this.samples(mint);
+        const latest = ring[ring.length - 1] ?? null;
+        for (const w of FLOW_WINDOWS) {
+            if (w.ds === null) {
+                out.push(tapeRow(w, tape, now));
+                continue;
+            }
+            if (!latest) {
+                out.push({ label: w.label, buys: null, sells: null, buyUsd: null, sellUsd: null, volUsd: null, trend: { na: '—' }, note: 'no dexscreener pair yet' });
+                continue;
+            }
+            const cur = latest.txns[w.ds] ?? null;
+            const prev = prevSample(ring, latest.t, w.ms);
+            out.push({
+                label: w.label,
+                buys: cur ? cur.buys : null,
+                sells: cur ? cur.sells : null,
+                buyUsd: null,
+                sellUsd: null,
+                volUsd: latest.volume[w.ds] ?? null,
+                trend: 'sample' in prev ? trendCell(cur, prev.sample.txns[w.ds] ?? null) : { wait: fmtWait(prev.waitMs) },
+            });
+        }
+        return out;
+    }
+    /** `dexscreener 8s · 1m from tape` — the panel caption (age of the newest DexScreener sample). */
+    caption(mint, now) {
+        const ring = this.samples(mint);
+        const latest = ring[ring.length - 1];
+        const ds = latest ? `dexscreener ${Math.max(0, Math.round((now - latest.t) / 1000))}s` : 'dexscreener —';
+        return `${ds} · 1m from tape`;
+    }
+}
+function tapeRow(w, tape, now) {
+    const p = tape.panel;
+    const empty = { label: w.label, buys: null, sells: null, buyUsd: null, sellUsd: null, volUsd: null, trend: { na: '—' } };
+    if (p.fetchedAt === null && (p.state === 'loading' || p.state === 'idle'))
+        return { ...empty, note: 'loading tape…' };
+    if (p.fetchedAt === null)
+        return { ...empty, note: `tape unavailable${p.reason ? `: ${p.reason}` : ''}` };
+    const anchor = p.fetchedAt ?? now;
+    const cur = tapeWindow(tape.trades, anchor - w.ms, Infinity);
+    const prev = tapeWindow(tape.trades, anchor - 2 * w.ms, anchor - w.ms);
+    return {
+        label: w.label,
+        buys: cur.buys,
+        sells: cur.sells,
+        buyUsd: cur.complete ? cur.buyUsd : null,
+        sellUsd: cur.complete ? cur.sellUsd : null,
+        volUsd: cur.buyUsd + cur.sellUsd,
+        partial: !cur.complete,
+        // A full tape that does not reach back far enough cannot give the window (counts get a `+`) or the
+        // previous minute honestly: say which, never compare against a truncated count.
+        trend: !cur.complete ? { na: 'partial' } : !prev.complete ? { na: 'prev n/a' } : trendCell(cur, prev),
+    };
+}