dexterm-cli 0.2.0 → 0.2.1

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/recorder/src/exit-probes.js

@@ -0,0 +1,215 @@
+// dexterm history recorder: exit probes (task-1786, research/winner-recall-2026-10/DATA-GAPS.md item 2). DexScreener's
+// `liquidity.usd` says a pool is there; it does not say the coin can be sold (the control's $NOTHING ran, sold TP1, then
+// sat at liquidity $0 with no route). This lane asks Jupiter, once a minute per HELD focus coin, for a keyless sell
+// quote of a fixed USD size (default $50 at the last tick price) into SOL and writes what came back: the SOL out, the
+// price impact and the hop count, or the error ("no route" is the drain). Quotes only: nothing is built, signed or sent.
+//
+//   who       focus coins with role 'held' (the tick lane's focus: the collector's DB, focus files, the focus module)
+//   cadence   one quote per coin per `everyMs` (60 s), at most `maxPerPoll` (1) per poll and `maxPerMinute` (4) in any
+//             60 s whatever the number of held coins (the IP's keyless Jupiter budget is shared with the feed and with
+//             any process that sells); a per-UTC-day ceiling on top
+//   budget    the data layer's shared keyless `jupiter` bucket at 'high' priority: the feed's own Jupiter calls keep
+//             that bucket's queue minutes long, so a 'low' or 'normal' probe times out behind them (task-1786 smoke);
+//             'high' only jumps the queue, the bucket's 60 s ceiling is unchanged. Skipped while it is paused (429)
+//             A quote may wait up to 75 s (one full window) for a slot; the host runs it detached from the ticks.
+//   sizing    tokens = usd / the coin's last tick price, in base units (decimals from the cached mint info)
+//
+// Retention: rows go with the ticks (14 days) and the cap may evict them (retention.ts).
+import { HttpError, withPriority, systemClock } from '../../data/src/index.js';
+import { mergeFocus } from "./ticks.js";
+export const WSOL_MINT = 'So11111111111111111111111111111111111111112';
+export const DEFAULT_EXIT_PROBES = { everyMs: 60_000, maxPerPoll: 1, maxPerMinute: 4, usd: 50, slippageBps: 500, maxCallsPerDay: 8_000 };
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const msg = (err) => (err instanceof Error ? err.message : String(err));
+/** Message-text fallback for errors that carry no status (a dropped socket, DNS, our own limiter). Never applied to
+ *  an `HttpError`: its message embeds the quote URL (`slippageBps=500`, the amount), so a digit pattern matches every
+ *  answer (verify-1791). URLs are stripped before the test either way. */
+export const TRANSIENT_PROBE_ERROR = /rate.?limit|abort|timed? ?out|timeout|ECONN|ENOTFOUND|EAI_AGAIN|fetch failed|network|unavailable|paused/i;
+const URL_RE = /https?:\/\/\S+/g;
+/** The error text for a row: query strings dropped (the mint and amount are columns already), cut to 200 chars. */
+export const probeErrorText = (err) => msg(err).replace(URL_RE, (u) => u.replace(/[?#][^\s)]*/, '')).slice(0, 200);
+/** A miss that says nothing about the coin, so no row is written and the coin is retried next minute: a 429 or 5xx,
+ *  a 401/403/408, a non-JSON answer, our own limiter or health gate, a timeout or abort, the network. Anything else (any other
+ *  4xx, or a 2xx carrying an `error` such as "No routes found") means Jupiter answered and had no quote for this
+ *  sell, which is the drain signal: an `error` row. Classified on the error's type and status, not its text. */
+export function isTransientProbeError(err) {
+    if (err instanceof HttpError || (err instanceof Error && err.name === 'HttpError')) {
+        const status = Number(err.status);
+        // 401/403: a keyless refusal of this IP (the hosts already failed over); 408: the server's timeout. Not the coin.
+        if (status === 401 || status === 403 || status === 408 || status === 429 || (status >= 500 && status <= 599) || !(status > 0))
+            return true;
+        return /^invalid JSON from /.test(err.message);
+    }
+    if (!(err instanceof Error))
+        return TRANSIENT_PROBE_ERROR.test(String(err).replace(URL_RE, ''));
+    if (['AbortError', 'TimeoutError', 'JupiterRateLimitedError', 'SourceUnavailableError', 'RateDeferredError'].includes(err.name))
+        return true;
+    if (err instanceof TypeError)
+        return true; // undici's `fetch failed` (DNS, reset, refused)
+    const code = err.code;
+    if (typeof code === 'string' && /^(ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EPIPE|UND_ERR)/.test(code))
+        return true;
+    return TRANSIENT_PROBE_ERROR.test(err.message.replace(URL_RE, ''));
+}
+/**
+ * The lane's deps over a live data layer (the collector's `record run --exit-probes`).
+ *
+ * A no-route answer (a 4xx such as 400 COULD_NOT_FIND_ANY_ROUTE, or a 200 carrying an `error`) is a real answer from
+ * Jupiter about ONE coin, but the HTTP client records it as a `jupiter-swap` health failure. Three in a row (or one
+ * while probing) degrade the source, and the gate then refuses every later quote as `JupiterRateLimitedError(0)`: the
+ * drain signal muted the lane and every healthy held coin with it (verify-1795). So after an answer like that, the
+ * adapter records the source as answering (`ok`). A 429, 5xx, timeout or network miss is left alone, so the gate
+ * still backs off on real rate limits.
+ * Collector-only: in that process nothing else quotes on `jupiter-swap`, and the shared data layer's behaviour is
+ * unchanged for every other caller (the challenge, the TUI).
+ */
+export function exitProbeDeps(dl) {
+    return {
+        async quote(req, signal) {
+            try {
+                const q = await dl.jupiterSwap.quote(req, signal);
+                return { outAmount: q.outAmount, priceImpactPct: q.priceImpactPct, routeHops: q.route.length };
+            }
+            catch (err) {
+                if (err instanceof HttpError && !isTransientProbeError(err))
+                    dl.health.record('jupiter-swap', { ok: true });
+                throw err;
+            }
+        },
+        decimals: async (mint) => (await dl.detail.mintInfo(mint)).value.decimals,
+        limiter: dl.limiter,
+    };
+}
+export class ExitProbeLane {
+    policy;
+    db;
+    focus;
+    clock;
+    onLog;
+    last = new Map();
+    dec = new Map();
+    polling = false;
+    /** Times of the quotes sent in the last minute (the `maxPerMinute` window). */
+    recent = [];
+    day = '';
+    dayCalls = 0;
+    counters = { probes: 0, ok: 0, failed: 0 };
+    stmts;
+    constructor(db, opts) {
+        this.db = db;
+        this.focus = opts.focus;
+        this.policy = { ...DEFAULT_EXIT_PROBES, ...opts.policy };
+        this.clock = opts.clock ?? systemClock;
+        this.onLog = opts.onLog;
+        this.stmts = {
+            insert: db.prepare(`INSERT OR IGNORE INTO exit_probes (mint, t, role, usd_in, price_usd, liquidity_usd, tokens_in, sol_out, price_impact_pct, route_hops, error)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+            price: db.prepare('SELECT price_usd, liquidity_usd FROM autotrade_ticks WHERE mint = ? AND price_usd IS NOT NULL ORDER BY t DESC LIMIT 1'),
+            meta: db.prepare("INSERT OR REPLACE INTO recorder_meta (key, value) VALUES ('exit_probe_calls', ?)"),
+        };
+    }
+    callsToday(now = this.clock.now()) {
+        const day = new Date(now).toISOString().slice(0, 10);
+        if (day !== this.day) {
+            this.day = day;
+            this.dayCalls = 0;
+            const r = this.db.prepare("SELECT value FROM recorder_meta WHERE key = 'exit_probe_calls'").get();
+            try {
+                const v = r ? JSON.parse(r.value) : null;
+                if (v && v.day === day)
+                    this.dayCalls = Number(v.calls) || 0;
+            }
+            catch { /* reset */ }
+        }
+        return this.dayCalls;
+    }
+    /** Held coins due a probe, the longest-unprobed first. */
+    due(now = this.clock.now()) {
+        return mergeFocus(this.focus()).filter((e) => e.role === 'held' && e.mint !== WSOL_MINT && now - (this.last.get(e.mint) ?? -Infinity) >= this.policy.everyMs)
+            .sort((a, b) => (this.last.get(a.mint) ?? 0) - (this.last.get(b.mint) ?? 0));
+    }
+    /** One poll (the collector's tick loop calls it right after the tick poll). Never throws. */
+    async poll(deps, now = this.clock.now()) {
+        const none = (skipped) => ({ probed: 0, ok: 0, failed: 0, skipped });
+        if (this.polling)
+            return none('in-flight');
+        let due;
+        try {
+            due = this.due(now);
+        }
+        catch (err) {
+            this.log(`exit probe focus failed: ${msg(err)}`);
+            return none('no-held');
+        }
+        if (!due.length)
+            return none(mergeFocus(this.focus()).some((e) => e.role === 'held') ? 'not-due' : 'no-held');
+        if (this.callsToday(now) >= this.policy.maxCallsPerDay)
+            return none('day-cap');
+        this.recent = this.recent.filter((t) => now - t < 60_000);
+        if (this.recent.length >= this.policy.maxPerMinute)
+            return none('minute-cap');
+        if (deps.limiter.bucket('jupiter').stats().pausedUntil > now)
+            return none('paused');
+        this.polling = true;
+        const res = { probed: 0, ok: 0, failed: 0, skipped: null };
+        try {
+            for (const e of due.slice(0, Math.min(this.policy.maxPerPoll, this.policy.maxPerMinute - this.recent.length))) {
+                this.last.set(e.mint, now);
+                const px = this.stmts.price.get(e.mint);
+                if (!px || !(px.price_usd > 0))
+                    continue; // no tick price yet: nothing to size the probe with
+                let tokens = null, solOut = null, impact = null, hops = null, error = null;
+                // Decimals come from the mint-info source, not Jupiter: a failure there says nothing about selling, so defer.
+                let d = this.dec.get(e.mint);
+                if (d === undefined) {
+                    try {
+                        d = await deps.decimals(e.mint);
+                        this.dec.set(e.mint, d);
+                    }
+                    catch {
+                        res.deferred = (res.deferred ?? 0) + 1;
+                        continue;
+                    }
+                }
+                try {
+                    tokens = BigInt(Math.max(1, Math.round((this.policy.usd / px.price_usd) * 10 ** d)));
+                    this.dayCalls++;
+                    this.recent.push(now);
+                    this.stmts.meta.run(JSON.stringify({ day: this.day, calls: this.dayCalls }));
+                    const q = await withPriority('high', () => deps.quote({ inputMint: e.mint, outputMint: WSOL_MINT, amount: tokens, slippageBps: this.policy.slippageBps }, AbortSignal.timeout(75_000)));
+                    solOut = Number(q.outAmount) / 1e9;
+                    impact = fin(q.priceImpactPct ?? null);
+                    hops = fin(q.routeHops ?? null);
+                    res.ok++;
+                }
+                catch (err) {
+                    if (isTransientProbeError(err)) {
+                        res.deferred = (res.deferred ?? 0) + 1;
+                        continue;
+                    }
+                    error = probeErrorText(err);
+                    res.failed++;
+                }
+                res.probed++;
+                this.stmts.insert.run(e.mint, this.clock.now(), e.role, this.policy.usd, px.price_usd, fin(px.liquidity_usd), tokens === null ? null : tokens.toString(), solOut, impact, hops, error);
+            }
+        }
+        catch (err) {
+            this.log(`exit probe failed: ${msg(err)}`);
+        }
+        finally {
+            this.polling = false;
+            this.counters.probes += res.probed;
+            this.counters.ok += res.ok;
+            this.counters.failed += res.failed;
+        }
+        if (this.last.size > 500)
+            for (const [m, lt] of this.last)
+                if (now - lt > 3_600_000)
+                    this.last.delete(m);
+        return res;
+    }
+    log(line) {
+        this.onLog?.(`recorder: ${line}\n`);
+    }
+}

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

@@ -10,6 +10,7 @@ export * from "./verdicts.js";
 export * from "./schedule.js";
 export * from "./dev-history.js";
 export * from "./ticks.js";
+export * from "./exit-probes.js";
 export * from "./retention.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. */

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

@@ -22,6 +22,7 @@ import { COLUMN_NAMES, fromDsView, fromEnrichedRow, isMaterialChange } from "./s
 import { LABELER_VERSION, labelAtHorizon } from "./labels.js";
 import { dueBounds, selectDue } from "./sweep.js";
 import { TickLane } from "./ticks.js";
+import { ExitProbeLane } from "./exit-probes.js";
 import { DEFAULT_AGE, enforceCap, pruneTicksByAge } from "./retention.js";
 export const DEFAULT_SWEEP = { everyMs: 60_000, maxCallsPerSweep: 6, maxCallsPerDay: 1500, batch: 30 };
 export const DEFAULT_RETENTION = { rawDays: 7, columnsDays: 90, downsampleAfterHours: 24, everyMs: 3_600_000, ...DEFAULT_AGE };
@@ -50,6 +51,8 @@ export class Recorder {
     retention;
     /** task-1504: the tick lane (null when not configured) and the cap policy (null = no cap). */
     tickLane;
+    /** task-1786: the exit-probe lane (null when not configured). */
+    exitProbeLane;
     cap;
     onLog;
     /**
@@ -101,6 +104,7 @@ export class Recorder {
             insertCreator: this.db.prepare('INSERT OR IGNORE INTO creators (mint, creator, source, first_t, created_at) VALUES (?, ?, ?, ?, ?)'),
         };
         this.tickLane = opts.ticks ? new TickLane(this.db, { focus: opts.ticks.focus, policy: opts.ticks.policy, clock: this.clock, onLog: this.onLog }) : null;
+        this.exitProbeLane = opts.ticks && opts.exitProbes ? new ExitProbeLane(this.db, { focus: opts.ticks.focus, policy: opts.exitProbes.policy, clock: this.clock, onLog: this.onLog }) : null;
         this.cap = opts.cap && opts.cap.maxBytes ? opts.cap : null;
     }
     /** Attach as the data layer's store listener (and detach any previous one). */
@@ -325,6 +329,12 @@ export class Recorder {
             return { coins: 0, calls: 0, answered: 0, written: 0, overCap: 0, skipped: 'disabled' };
         return this.tickLane.poll(deps, now);
     }
+    /** task-1786: one exit-probe poll (exit-probes.ts); the host calls it after each tick poll. */
+    async probeExits(deps, now = this.clock.now()) {
+        if (!this.enabled || this.closed || !this.exitProbeLane)
+            return null;
+        return this.exitProbeLane.poll(deps, now);
+    }
     /**
      * task-1504: keep the DB under the configured cap by evicting the oldest history (retention.ts). A no-op without
      * a cap or below its high-water mark. Observation never pauses; the collector calls this before each pass.
@@ -555,7 +565,7 @@ export class Recorder {
             const d = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending')");
             if (d.b !== null && Number(s.n) > 0)
                 bytesPerSnapshot = Number(d.b) / Number(s.n);
-            const all = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('recorder_meta', 'feed_members', 'feed_members_mint_t', 'token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending', 'mints', 'mints_last_live', 'sweeps', 'chain_events', 'chain_events_mint_t', 'outcomes', 'outcomes_label', 'verdicts', 'verdicts_mint_t', 'creators', 'creators_creator', 'autotrade_ticks', 'autotrade_ticks_t', 'autotrade_candles_1m', 'autotrade_candles_1m_t')");
+            const all = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('recorder_meta', 'feed_members', 'feed_members_mint_t', 'token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending', 'mints', 'mints_last_live', 'sweeps', 'chain_events', 'chain_events_mint_t', 'outcomes', 'outcomes_label', 'verdicts', 'verdicts_mint_t', 'creators', 'creators_creator', 'autotrade_ticks', 'autotrade_ticks_t', 'autotrade_candles_1m', 'autotrade_candles_1m_t', 'exit_probes', 'exit_probes_t')");
             recorderBytes = all.b === null ? null : Number(all.b);
         }
         catch {

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

@@ -27,6 +27,7 @@ export const DEFAULT_CAP_BYTES = 3_000_000_000;
 const EVICTABLE = [
     { table: 'autotrade_ticks', col: 't' },
     { table: 'autotrade_candles_1m', col: 't' },
+    { table: 'exit_probes', col: 't' },
     { table: 'token_snapshots', col: 't' },
     { table: 'feed_members', col: 't' },
 ];
@@ -95,6 +96,9 @@ export function pruneTicksByAge(db, policy, now) {
     const p = { ...DEFAULT_AGE, ...policy };
     const day = 86_400_000;
     const ticks = Number(db.prepare('DELETE FROM autotrade_ticks WHERE t < ?').run(now - p.ticksDays * day).changes);
+    // task-1786: exit probes age out with the ticks they were sized on.
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'exit_probes'").get())
+        db.prepare('DELETE FROM exit_probes WHERE t < ?').run(now - p.ticksDays * day);
     const candles = Number(db.prepare('DELETE FROM autotrade_candles_1m WHERE t < ?').run(now - p.candlesDays * day).changes);
     return { ticks, candles };
 }

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

@@ -16,7 +16,9 @@
 // v2 (task-1504, AUTOTRADE-SPEC §3): `autotrade_ticks` (position-grade samples every 5–10 s for the few coins
 // that are watched, open, a candidate or held; written by the tick lane in ticks.ts) and `autotrade_candles_1m`
 // (1-minute OHLC built from those samples). Both are additive: a v1 file gains the two tables on open.
-export const SCHEMA_VERSION = 2;
+// v3 (task-1786, winner-recall DATA-GAPS item 2): `exit_probes` (a keyless Jupiter sell quote for each held focus coin
+// once a minute, written by exit-probes.ts). Additive: an older file gains the table on open.
+export const SCHEMA_VERSION = 3;
 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;
@@ -176,4 +178,21 @@ CREATE TABLE IF NOT EXISTS autotrade_candles_1m (
   PRIMARY KEY (mint, t)
 ) WITHOUT ROWID;
 CREATE INDEX IF NOT EXISTS autotrade_candles_1m_t ON autotrade_candles_1m (t);
+
+-- task-1786: can a held coin be sold, and for what. One row per probe: a fixed-USD sell quote into SOL at the coin's
+-- last tick price. sol_out NULL + error = no quote (error 'no route' style = the drain); price_impact_pct is a percent.
+CREATE TABLE IF NOT EXISTS exit_probes (
+  mint             TEXT NOT NULL,
+  t                INTEGER NOT NULL,          -- unix ms the answer came back
+  role             TEXT NOT NULL,             -- 'held'
+  usd_in           REAL NOT NULL,             -- probe size in USD at price_usd
+  price_usd        REAL, liquidity_usd REAL,  -- the last tick's DexScreener price / liquidity the probe was sized on
+  tokens_in        TEXT,                      -- base units sold (decimal string)
+  sol_out          REAL,                      -- SOL the route returns (NULL = no quote)
+  price_impact_pct REAL,
+  route_hops       INTEGER,
+  error            TEXT,
+  PRIMARY KEY (mint, t)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS exit_probes_t ON exit_probes (t);
 `;