dexterm-cli 0.1.6 → 0.1.7

package/dist/packages/autotrade/src/monitor.js

@@ -0,0 +1,190 @@
+// dexterm autotrade — the position monitor (task-1498 spike, AUTOTRADE-SPEC §5).
+//
+// No LLM in this loop. On every tick of a held coin it applies the exit profile's mechanical rules at once
+// (rug / liquidity pull, thesis breaks, hard stop, take-profit ladder, trailing stop, time stop, ladder adds)
+// and only then raises WAKE events for the judgement calls the profile hands to the position's agent session
+// (a TP filled, a time review, a drawdown alert, an early thesis warning, a mechanical exit that already
+// happened). The session can answer within bounds (hold / exit / tighten / re-profile); it can never block
+// or undo a mechanical exit, and if it does not answer the mechanical rules simply keep running.
+import { splitX } from "./engine.js";
+export const pnlPct = (p, price) => ((price - p.entryPrice) / p.entryPrice) * 100;
+/** The data layer's agreement ratio (@dexterm/data MCAP_AGREE_RATIO; equal by test, kept local so the engine stays pure). */
+export const SOURCES_AGREE_X = 5;
+/**
+ * Why a thesis-split fired, naming the trigger that did fire (task-1518). On a row the data layer flagged, the resolved
+ * cap IS DexScreener's (resolveMcap keeps it when the sources disagree), so the two numbers on the tick are equal and
+ * the computed ratio reads 1.0x: say that the sources' supplies were flagged instead of printing "1.0x apart".
+ */
+export function splitDetail(k, maxX) {
+    const x = splitX(k);
+    if (x > maxX)
+        return `market-cap sources ${x.toFixed(1)}x apart (limit ${maxX}x)`;
+    return `the data layer flagged the two market-cap sources: their supplies are more than ${SOURCES_AGREE_X}x apart`;
+}
+const pct = (x) => `${x >= 0 ? '+' : ''}${x.toFixed(1)}%`;
+/**
+ * One tick for one open position. Mutates the position's tracking fields (peak, windows, TP count, armed
+ * trail, wake flags) and returns the actions in the order they must be executed. A full exit ends the list.
+ */
+export function monitorTick(p, prof, k, o) {
+    const out = [];
+    p.lastTick = k;
+    const wake = (event, detail, allowed = ['hold', 'exit', 'tighten']) => {
+        out.push({ kind: 'wake', wake: { event, positionId: p.id, mint: p.mint, t: k.t, detail, allowed } });
+    };
+    const exitAll = (reason, detail) => {
+        out.push({ kind: 'sell', tokens: p.tokens, all: true, reason, detail });
+        out.push({ kind: 'wake', wake: { event: 'mechanical_exit', positionId: p.id, mint: p.mint, t: k.t, detail: `${reason}: ${detail}`, allowed: ['hold'] } });
+        return out;
+    };
+    // A stuck bag (no pool to sell into) is retried on every tick; nothing else applies until it sells.
+    if (p.stuck) {
+        if ((k.liq ?? 0) >= o.minExitLiquidityUsd && k.price)
+            return exitAll('rug-liquidity', 'liquidity came back, selling the stuck bag');
+        return out;
+    }
+    if (k.price === null || k.price <= 0)
+        return out;
+    const liq = k.liq ?? 0;
+    // 1. Rug / liquidity pull: the pool is gone or below the exit floor.
+    if (liq < o.minExitLiquidityUsd)
+        return exitAll('rug-liquidity', `liquidity $${Math.round(liq)} is below the $${o.minExitLiquidityUsd} exit floor`);
+    // 2. Thesis breaks on the coin's own reads.
+    const tb = prof.thesisBreak;
+    const winMs = tb.liquidityWindowMin * 60e3;
+    p.liqWindow.push({ t: k.t, liq });
+    // Keep the window plus the newest read before it: on a ~2-minute tape a 5-minute window still has a reference.
+    while (p.liqWindow.length > 2 && p.liqWindow[1].t < k.t - winMs)
+        p.liqWindow.shift();
+    const liqHigh = Math.max(...p.liqWindow.map((w) => w.liq));
+    const liqDrop = liqHigh > 0 ? ((liqHigh - liq) / liqHigh) * 100 : 0;
+    if (liqDrop >= tb.liquidityDropPct)
+        return exitAll('thesis-liquidity', `liquidity down ${liqDrop.toFixed(0)}% from its ${tb.liquidityWindowMin}-min high`);
+    if (tb.mcapDivergenceX !== null && (k.mcapFlagged || splitX(k) > tb.mcapDivergenceX))
+        return exitAll('thesis-split', splitDetail(k, tb.mcapDivergenceX));
+    if (tb.volumeDeath) {
+        const trades = (k.buys5m ?? 0) + (k.sells5m ?? 0);
+        if (k.buys5m !== null && trades < tb.volumeDeath.m5TradesBelow)
+            p.lowTapeSince ??= k.t;
+        else
+            p.lowTapeSince = null;
+        if (p.lowTapeSince !== null && k.t - p.lowTapeSince >= tb.volumeDeath.forMinutes * 60e3)
+            return exitAll('thesis-volume', `under ${tb.volumeDeath.m5TradesBelow} trades per 5 min for ${tb.volumeDeath.forMinutes} min`);
+    }
+    // (devSell needs chain events; the recorded history has none, so a replay cannot fire it.)
+    const gain = pnlPct(p, k.price);
+    p.peakPrice = Math.max(p.peakPrice, k.price);
+    p.troughPrice = Math.min(p.troughPrice ?? p.entryPrice, k.price);
+    const peakGain = pnlPct(p, p.peakPrice);
+    // 3. Hard stop (opt-in per profile), then the holding cap (the position's own dead-man).
+    if (prof.maxHoldMinutes != null && k.t - p.openedAt >= prof.maxHoldMinutes * 60e3)
+        return exitAll('max-hold', `held ${prof.maxHoldMinutes} min (the profile's holding cap) at ${pct(gain)}`);
+    if (prof.hardStop.enabled && prof.hardStop.atPct !== null && gain <= prof.hardStop.atPct)
+        return exitAll('stop', `${pct(gain)} hit the ${prof.hardStop.atPct}% hard stop`);
+    // 3b. Cost recovery (exit profile 1.2.0): sell what pays back the net cost, once; the rest rides as a free bag.
+    // Proceeds come from the runner's own fill model (every cost a sell pays), and the sell is capped at
+    // maxSellFrac of the bag, so a thin pool recovers less rather than selling everything.
+    const cr = prof.costRecovery;
+    if (cr && !p.costRecovered && gain >= cr.atPct) {
+        const owed = p.costUsd - p.realizedUsd;
+        const price = k.price;
+        const sellUsd = o.sellUsd ?? ((tok) => tok * price);
+        const cap = p.tokens * cr.maxSellFrac;
+        let tokens = cap;
+        if (sellUsd(cap) > owed) { // smallest bag slice that nets the cost (proceeds rise with size)
+            let lo = 0, hi = cap;
+            for (let i = 0; i < 40; i++) {
+                const mid = (lo + hi) / 2;
+                if (sellUsd(mid) >= owed)
+                    hi = mid;
+                else
+                    lo = mid;
+            }
+            tokens = hi;
+        }
+        p.costRecovered = true;
+        if (owed > 0 && tokens > 0) {
+            out.push({ kind: 'sell', tokens, all: false, reason: 'cost-recovery', detail: `${pct(gain)} ≥ +${cr.atPct}%: sell ${Math.round((tokens / p.tokens) * 100)}% of the bag to take the $${owed.toFixed(2)} cost back` });
+            if (prof.wake?.onCostRecovered)
+                wake('cost_recovered', `cost taken back at ${pct(gain)}; ${Math.round(((p.tokens - tokens) / p.origTokens) * 100)}% of the original size rides as a free bag`, ['hold', 'exit', 'tighten']);
+        }
+    }
+    const held = p.tokens - out.reduce((a, x) => a + (x.kind === 'sell' ? x.tokens : 0), 0);
+    // 4. Take-profit ladder (fractions of the ORIGINAL size; several steps may fill on one gap).
+    let left = held;
+    while (p.tpFilled < prof.tpLadder.length && gain >= prof.tpLadder[p.tpFilled].atPct) {
+        const step = prof.tpLadder[p.tpFilled];
+        const tokens = Math.min(left, p.origTokens * step.sellFrac);
+        p.tpFilled++;
+        if (tokens <= 0)
+            continue;
+        left -= tokens;
+        out.push({ kind: 'sell', tokens, all: left <= p.origTokens * 1e-6, reason: `tp${p.tpFilled}`, detail: `${pct(gain)} ≥ +${step.atPct}%: sell ${Math.round(step.sellFrac * 100)}% of the original size` });
+        if (prof.wake?.onTpFilled)
+            wake('tp_filled', `TP${p.tpFilled} filled at ${pct(gain)}; ${Math.round((left / p.origTokens) * 100)}% of the original size left`, ['hold', 'exit', 'tighten', 'reprofile']);
+    }
+    if (left <= p.origTokens * 1e-6)
+        return out;
+    // 5a. Bag trail (exit profile 1.2.0): armed by the cost-recovery sell (and, with armAtPct, a higher peak),
+    // measured off the peak since entry.
+    if (prof.bagTrail && p.costRecovered && peakGain >= (prof.bagTrail.armAtPct ?? 0)) {
+        const off = ((p.peakPrice - k.price) / p.peakPrice) * 100;
+        const trail = p.bagTrailPct ?? prof.bagTrail.trailPct;
+        if (off >= trail) {
+            out.push({ kind: 'sell', tokens: left, all: true, reason: 'bag-trail', detail: `the bag is ${off.toFixed(0)}% off its peak (${pct(peakGain)}), bag trail ${trail}%` });
+            out.push({ kind: 'wake', wake: { event: 'mechanical_exit', positionId: p.id, mint: p.mint, t: k.t, detail: `bag-trail: ${off.toFixed(0)}% off the peak`, allowed: ['hold'] } });
+            return out;
+        }
+    }
+    // 5. Trailing stop.
+    const ts = prof.trailingStop;
+    if (ts) {
+        if (!p.trailArmed && peakGain >= ts.armAtPct)
+            p.trailArmed = true;
+        const off = ((p.peakPrice - k.price) / p.peakPrice) * 100;
+        if (p.trailArmed && off >= ts.trailPct) {
+            out.push({ kind: 'sell', tokens: left, all: true, reason: 'trail', detail: `${off.toFixed(0)}% off the peak (${pct(peakGain)}), trail ${ts.trailPct}%` });
+            out.push({ kind: 'wake', wake: { event: 'mechanical_exit', positionId: p.id, mint: p.mint, t: k.t, detail: `trail: ${off.toFixed(0)}% off the peak`, allowed: ['hold'] } });
+            return out;
+        }
+    }
+    // 6. Time stop.
+    const tm = prof.timeStop;
+    if (tm && k.t - p.openedAt >= tm.minutes * 60e3 && gain < tm.ifBelowPct) {
+        if (tm.action === 'exit') {
+            out.push({ kind: 'sell', tokens: left, all: true, reason: 'time', detail: `${tm.minutes} min in at ${pct(gain)} (needed +${tm.ifBelowPct}%)` });
+            out.push({ kind: 'wake', wake: { event: 'mechanical_exit', positionId: p.id, mint: p.mint, t: k.t, detail: `time: ${tm.minutes} min at ${pct(gain)}`, allowed: ['hold'] } });
+            return out;
+        }
+        if (!p.wakeSent.time && (prof.wake?.onTimeReview ?? true)) {
+            p.wakeSent.time = true;
+            wake(tm.action === 'review' ? 'time_review' : 'time_tighten', `${tm.minutes} min in at ${pct(gain)}, below the +${tm.ifBelowPct}% the profile wanted by now`);
+        }
+    }
+    // 7. Judgement wakes (once each).
+    const w = prof.wake;
+    if (w?.drawdownPct != null && gain <= w.drawdownPct && !p.wakeSent.drawdown) {
+        p.wakeSent.drawdown = true;
+        wake('drawdown', `position at ${pct(gain)}; no hard stop in this profile`);
+    }
+    if (w?.thesisWarnFrac != null && liqDrop >= tb.liquidityDropPct * w.thesisWarnFrac && !p.wakeSent.thesis) {
+        p.wakeSent.thesis = true;
+        wake('thesis_warning', `liquidity down ${liqDrop.toFixed(0)}% from its window high (exit at ${tb.liquidityDropPct}%)`);
+    }
+    // 8. Ladder adds (scale-in tranches), each still clamped by the runner.
+    p.ladder.forEach((tr, i) => {
+        if (tr.usd <= 0)
+            return;
+        if (k.t > tr.deadline) {
+            tr.usd = 0;
+            return;
+        }
+        const first = p.fills[0].price;
+        const move = ((k.price - first) / first) * 100;
+        if (tr.atPct < 0 ? move <= tr.atPct : move >= tr.atPct) {
+            out.push({ kind: 'add', index: i, usd: tr.usd, detail: `tranche ${i + 1}: ${pct(move)} from the first fill (trigger ${tr.atPct}%)` });
+            tr.usd = 0;
+        }
+    });
+    return out;
+}

package/dist/packages/autotrade/src/ollama-sessions.js

@@ -0,0 +1,137 @@
+// dexterm autotrade — candidate and position sessions on a LOCAL model (task-1543, Ollama).
+//
+// The same protocol as the claude sessions (sessions.ts, AUTOTRADE-SPEC §4): one conversation per coin, the
+// DOSSIER first, then DELTA / ENGINE / EVENT messages, and every reply ends in one `DECISION {json}` line that
+// session.ts parses against the closed schema and the engine clamps. What differs is only who answers:
+//
+//   * the session is TOOL-LESS by construction: no `tools` are ever sent to /api/chat (the test asserts the
+//     request body), so the model can only answer;
+//   * the reply is constrained with Ollama structured output ({ comment, decision }) and rendered back into the
+//     exact text form the claude path produces, so parseDecision, the clamp, the caps and the ledger are shared;
+//   * a reply later than decideWithinSec aborts the request and resolves as no answer (no late result exists);
+//   * cost is $0 (the user's own machine); the day turn / session caps of the SessionGate still apply.
+//
+// The restriction profile is checked when the factory is built: autotrade on a local engine needs `paper`
+// (`full` for anything live). Nothing here sees a key, a wallet or the signer.
+import { OllamaError, atLeast, requiredLevel, stripThink } from '../../mcp/src/engine/index.js';
+import { ACTIONS, parseDecision } from "./session.js";
+/** The structured-output schema of one reply: a short comment and the decision object (the closed §4 shape). */
+export const OLLAMA_DECISION_FORMAT = {
+    type: 'object',
+    properties: {
+        comment: { type: 'string' },
+        decision: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: [...ACTIONS] },
+                profile: { type: 'string' },
+                sizePct: { type: 'number' },
+                confidence: { type: 'number' },
+                fraction: { type: 'number' },
+                reason: { type: 'string' },
+            },
+            required: ['action', 'reason'],
+        },
+    },
+    required: ['comment', 'decision'],
+};
+/** Render a structured reply as the claude-path text: comment lines, then one DECISION line. Raw text is kept as is. */
+export function renderOllamaReply(content) {
+    const s = stripThink(content).trim();
+    let v;
+    try {
+        v = JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return s;
+    const o = v;
+    if (!o.decision || typeof o.decision !== 'object')
+        return s;
+    // Drop keys the model set to null (optional fields), keep everything else for the closed-schema check to judge.
+    const d = Object.fromEntries(Object.entries(o.decision).filter(([, x]) => x !== null));
+    const comment = typeof o.comment === 'string' ? o.comment.replace(/\n+/g, ' ').trim().slice(0, 400) : '';
+    return `${comment}\nDECISION ${JSON.stringify(d)}`.trim();
+}
+class OllamaSession {
+    id;
+    kind = 'ollama';
+    model;
+    o;
+    messages;
+    turns = 0;
+    closed = false;
+    why = null;
+    inflight = null;
+    constructor(id, o) {
+        this.id = id;
+        this.o = o;
+        this.model = o.model;
+        this.messages = [{ role: 'system', content: o.systemPrompt }];
+    }
+    costUsd() { return 0; }
+    endReason() { return this.why; }
+    turnsUsed() { return this.turns; }
+    async send(text) {
+        if (this.closed || this.why)
+            return null;
+        if (this.turns >= this.o.maxTurns)
+            return null;
+        this.turns++;
+        const t0 = Date.now();
+        this.messages.push({ role: 'user', content: text });
+        const ac = new AbortController();
+        this.inflight = ac;
+        const timer = setTimeout(() => ac.abort(), this.o.decideWithinMs);
+        timer.unref?.();
+        try {
+            // Tool-less: the request never carries `tools`.
+            const r = await this.o.client.chat({ model: this.o.model, messages: this.messages, format: OLLAMA_DECISION_FORMAT, options: { num_ctx: this.o.numCtx } }, { signal: ac.signal, timeoutMs: this.o.decideWithinMs + 1000 });
+            this.o.onRaw?.(JSON.stringify({ engine: 'ollama', model: r.model ?? this.o.model, content: r.content.slice(0, 4000), promptTokens: r.promptTokens, evalTokens: r.evalTokens }));
+            const reply = renderOllamaReply(r.content);
+            this.messages.push({ role: 'assistant', content: reply });
+            return { text: reply, decision: parseDecision(reply), costUsd: 0, ms: Date.now() - t0 };
+        }
+        catch (e) {
+            // No answer in time (or the server went away): the turn resolves as no answer, never as a late decision.
+            this.messages.push({ role: 'assistant', content: '(no answer in time)' });
+            if (e instanceof OllamaError && (e.kind === 'unreachable' || e.kind === 'model-missing'))
+                this.why = e.kind === 'unreachable' ? 'ollama-unreachable' : 'model-missing';
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+            if (this.inflight === ac)
+                this.inflight = null;
+        }
+    }
+    async close(reason) {
+        this.closed = true;
+        try {
+            this.inflight?.abort();
+        }
+        catch { /* ignore */ }
+        this.why ??= reason;
+        return { turns: this.turns, costUsd: 0, reason };
+    }
+}
+/** Throws when the profile does not allow autotrade on a local engine (the run refuses to start). */
+export function assertAutotradeAllowed(restriction, live = false) {
+    const need = requiredLevel('autotrade', { live });
+    if (!atLeast(restriction, need))
+        throw new Error(`the local engine's restriction profile is ${restriction}; ${live ? 'a live' : 'an autotrade'} run needs ${need} (dexterm ai restrictions ${need}${need === 'full' ? ', or dexterm ai engine ollama --full' : ''})`);
+}
+/** The runner's session factory on the user's local Ollama: same signature and protocol as claudeSessionFactory. */
+export function ollamaSessionFactory(f) {
+    assertAutotradeAllowed(f.restriction, f.live);
+    return (id, s, ctx) => {
+        f.log('session_init', { sessionId: id, sessionKind: ctx.kind, engine: 'ollama', model: f.model, host: f.client.host.local ? 'local' : 'remote', tools: 0, mcpServers: 0, restriction: f.restriction, costUsd: 0, ok: true });
+        return new OllamaSession(id, {
+            client: f.client, model: f.model, numCtx: f.numCtx, systemPrompt: f.systemPrompt(s),
+            maxTurns: s.agent.maxTurns, decideWithinMs: s.agent.decideWithinSec * 1000,
+            onRaw: f.onRaw ? (line) => f.onRaw(id, line) : undefined,
+        });
+    };
+}

package/dist/packages/autotrade/src/paper-accounts.js

@@ -0,0 +1,72 @@
+// dexterm autotrade — paper ACCOUNTS: several strategies trading from one simulated wallet (task-1538). PAPER only.
+//
+// Without an account every strategy of a parallel run owns its bankroll (its own SimBook, its own cash). A paper
+// account is one shared pool of simulated cash that any number of strategies trade from, the way several bots would
+// share one real wallet:
+//
+//   account "main" ($1000) ── strategy moon  (own positions, loss streak, per-coin rules, entries/day)
+//                          └─ strategy scalp (own positions, …)
+//   account "yolo" (1 SOL) ── strategy scalp again (the same rules, another account: its own member, ledger and book)
+//
+// What is shared: the cash (a fill spends from, and a sale pays into, the account), the equity every strategy sizes
+// from (cash + every open cost basis on the account, so "5% of the bankroll" means 5% of the wallet), and the
+// drawdown / day-start figures each strategy's breaker reads (the wallet's drawdown halts each strategy at its own
+// threshold). What stays per strategy: positions, exposure (its own footprint against the wallet), loss streak,
+// cooldowns, per-coin limits, entry counts, its session caps and its P/L.
+//
+// Nothing here holds a key or touches a wallet: an account is a number in memory for the length of one run.
+/** How many paper accounts one parallel run holds at most. */
+export const MAX_PAPER_ACCOUNTS = 8;
+const r2 = (v) => Math.round(v * 100) / 100;
+export class PaperAccount {
+    id;
+    startUsd;
+    sol;
+    solUsd;
+    cashUsd;
+    books = [];
+    constructor(id, startUsd, o = {}) {
+        if (!(startUsd > 0) || !Number.isFinite(startUsd))
+            throw new Error(`paper account ${id}: the starting balance must be a positive number`);
+        this.id = id;
+        this.startUsd = startUsd;
+        this.cashUsd = startUsd;
+        if (o.sol !== undefined) {
+            this.sol = o.sol;
+            this.solUsd = o.solUsd;
+        }
+    }
+    /** Cash held for fills in flight (an executor is async: the debit lands after it answers). */
+    held = 0;
+    /** Hold `usd` of the cash for one fill; false when the cash (less what other fills hold) is not there. */
+    hold(usd) {
+        if (!(usd >= 0) || usd > this.cashUsd - this.held + 1e-9)
+            return false;
+        this.held += usd;
+        return true;
+    }
+    /** Release a hold (the fill was booked, synchronously after the executor answered, or refused). */
+    release(usd) { this.held = Math.max(0, this.held - usd); }
+    /** A strategy's book joins the account (SimBook's constructor calls this). A book never leaves: a stopped strategy's bags stay on the account. */
+    join(book, member = book.strategy.id) { this.books.push({ member, book }); }
+    /** Cash + every open cost basis (unrealized gains do not count for sizing). */
+    bookEquity() { let e = this.cashUsd; for (const b of this.books)
+        e += b.book.openCostUsd(); return e; }
+    /** Cash + every open bag marked at what it would sell for now. */
+    markedEquity() { let e = this.cashUsd; for (const b of this.books)
+        e += b.book.openMarkUsd(); return e; }
+    view() {
+        const eq = this.markedEquity();
+        const pnl = r2(eq - this.startUsd);
+        let open = 0, positions = 0;
+        for (const b of this.books) {
+            open += b.book.openCostUsd();
+            positions += b.book.open.size;
+        }
+        return {
+            id: this.id, startUsd: r2(this.startUsd), cashUsd: r2(this.cashUsd), equityUsd: r2(eq), pnlUsd: pnl, pnlPct: Math.round((pnl / this.startUsd) * 1000) / 10,
+            openCostUsd: r2(open), positions, strategies: [...new Set(this.books.map((b) => b.member))],
+            ...(this.sol !== undefined ? { sol: this.sol, solUsd: this.solUsd } : {}),
+        };
+    }
+}

package/dist/packages/autotrade/src/replay.js

@@ -0,0 +1,198 @@
+// dexterm autotrade — the replay tape (task-1498 spike, AUTOTRADE-SPEC §3).
+//
+// A tape is recorded market history in time order: one row per (mint, t) taken from the recorder's
+// `token_snapshots` (the app's own SQLite file, read-only). The same MarketTick type feeds the live screener
+// daemon, the paper runner, the monitor and the backtester, so a backtest replays exactly what a live run
+// would have seen. `tapeFromDb` extracts one; `saveTape` / `loadTape` keep a compact committed fixture.
+//
+// Honest limits of the recorded data (written into every report): rows are written on material change
+// (≥ 5 % price/liquidity) or every 30 min, at the app's ~2-minute refresh cadence, and only while a coin is on
+// a screen, plus sweep re-observations at 1 h…72 h. A gap therefore means "moved less than ~5 %" while the coin
+// was listed, and "unknown" after it left. There are no trades or holder lists in the history.
+//
+// task-1504: where the recorder's tick lane ran (`autotrade_ticks`: a sample every 5–10 s for watchlist / open /
+// candidate / held coins), `tapeFromDb` merges those samples in tape order (t, a snapshot row before a tick at the
+// same t). A tick carries price, liquidity, mcap and the 5 m / 1 h windows; the slower fields (24 h windows, holders,
+// top-10, dev, authorities, organic score) are carried forward from the mint's latest earlier snapshot, never from a
+// later one, and the resolved mcap is scaled by the price move. Coins without ticks replay exactly as before.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { deriveFlags } from "../../cli/src/screener/rows.js";
+export const TAPE_SCHEMA = 'dexterm-autotrade-tape/1';
+/** Column order of a committed tape row (compact arrays keep fixtures small). */
+export const TAPE_COLUMNS = [
+    't', 'kind', 'price', 'mcap', 'mcapResolved', 'mcapFlagged', 'liq', 'vol5m', 'vol1h', 'vol24', 'buys5m', 'sells5m', 'buys24', 'sells24',
+    'chg5m', 'chg1h', 'chg6h', 'chg24h', 'holders', 'top10', 'dev', 'mintAuth', 'freezeAuth', 'org',
+];
+const SIG = 6;
+const sig = (x) => (x === null || !Number.isFinite(x) ? null : Number(x.toPrecision(SIG)));
+const bool = (x) => (x === null || x === undefined ? null : Boolean(x));
+const numOrNull = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const SNAP_COLS = `t, kind, symbol, launchpad, created_at, pair_created_at, price_usd, mcap, mcap_resolved, mcap_flagged, liquidity_usd,
+            vol_m5, vol_h1, vol_h24, buys_m5, sells_m5, buys_h24, sells_h24, chg_m5, chg_h1, chg_h6, chg_h24,
+            holder_count, top_holders_pct, dev_pct, mint_auth_enabled, freeze_auth_enabled, organic_score`;
+function hasTicks(db, since, until) {
+    const t = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'autotrade_ticks'").get();
+    return !!t && !!db.prepare('SELECT 1 FROM autotrade_ticks WHERE t >= ? AND t <= ? LIMIT 1').get(since, until);
+}
+/**
+ * Merge a mint's snapshot rows (time order) with its tick rows (time order) into snapshot-shaped rows: a tick takes
+ * its own price / liquidity / mcap / 5 m + 1 h windows and carries the rest forward from the latest snapshot at or
+ * before it (null before the first one).
+ */
+function mergeTicks(snaps, ticks) {
+    const out = [];
+    let i = 0;
+    let base = null;
+    for (const k of ticks) {
+        while (i < snaps.length && snaps[i].t <= k.t) {
+            base = snaps[i];
+            out.push(snaps[i++]);
+        }
+        const price = numOrNull(k.price_usd);
+        const basePrice = base ? numOrNull(base.price_usd) : null;
+        const baseResolved = base ? numOrNull(base.mcap_resolved) : null;
+        out.push({
+            t: k.t, kind: 'live',
+            symbol: base?.symbol ?? null, launchpad: base?.launchpad ?? null, created_at: base?.created_at ?? null, pair_created_at: k.pair_created_at ?? base?.pair_created_at ?? null,
+            price_usd: price, mcap: numOrNull(k.mcap),
+            mcap_resolved: baseResolved !== null && basePrice && price !== null ? baseResolved * (price / basePrice) : null,
+            mcap_flagged: base?.mcap_flagged ?? 0, liquidity_usd: numOrNull(k.liquidity_usd),
+            vol_m5: k.vol_m5, vol_h1: k.vol_h1, vol_h24: base?.vol_h24 ?? null, buys_m5: k.buys_m5, sells_m5: k.sells_m5, buys_h24: base?.buys_h24 ?? null, sells_h24: base?.sells_h24 ?? null,
+            chg_m5: k.chg_m5, chg_h1: k.chg_h1, chg_h6: base?.chg_h6 ?? null, chg_h24: base?.chg_h24 ?? null,
+            holder_count: base?.holder_count ?? null, top_holders_pct: base?.top_holders_pct ?? null, dev_pct: base?.dev_pct ?? null,
+            mint_auth_enabled: base?.mint_auth_enabled ?? null, freeze_auth_enabled: base?.freeze_auth_enabled ?? null, organic_score: base?.organic_score ?? null,
+        });
+    }
+    while (i < snaps.length)
+        out.push(snaps[i++]);
+    return out;
+}
+/**
+ * Extract a tape from the recorder tables (read-only handle from `openHistoryReadOnly`): `token_snapshots` and, where
+ * the tick lane ran, `autotrade_ticks` (task-1504), in tape order. A mint qualifies on its live rows of either kind.
+ */
+export function tapeFromDb(db, opts = {}) {
+    const since = opts.since ?? 0;
+    const until = opts.until ?? Number.MAX_SAFE_INTEGER;
+    const minLive = opts.minLiveRows ?? 20;
+    const minPeak = opts.minPeakLiqUsd ?? 20_000;
+    const span = (opts.spanHours ?? 24) * 3600e3;
+    const withTicks = opts.ticks !== false && hasTicks(db, since, until);
+    // Without ticks in the window the pick is the exact pre-1504 query, so earlier backtests reproduce bit for bit.
+    const picked = opts.mints ?? db.prepare(withTicks
+        ? `SELECT mint, SUM(n) AS n, MAX(peak) AS peak, MIN(first) AS first FROM (
+         SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM token_snapshots
+           WHERE kind = 'live' AND t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+         UNION ALL
+         SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM autotrade_ticks
+           WHERE t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+       ) GROUP BY mint HAVING n >= ? AND peak >= ? ORDER BY first, mint LIMIT ?`
+        : `SELECT mint, COUNT(*) AS n, MAX(liquidity_usd) AS peak, MIN(t) AS first FROM token_snapshots
+       WHERE kind = 'live' AND t >= ? AND t <= ? AND price_usd > 0 GROUP BY mint
+       HAVING n >= ? AND peak >= ? ORDER BY first LIMIT ?`).all(...(withTicks ? [since, until, since, until] : [since, until]), minLive, minPeak, opts.maxMints ?? 100_000).map((r) => r.mint);
+    const rowsQ = db.prepare(`SELECT ${SNAP_COLS} FROM token_snapshots WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t, snap_id`);
+    const ticksQ = withTicks ? db.prepare(`SELECT t, price_usd, liquidity_usd, mcap, vol_m5, vol_h1, buys_m5, sells_m5, chg_m5, chg_h1, pair_created_at
+       FROM autotrade_ticks WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t`) : null;
+    // The carry-forward base may sit before `since`: the mint's latest snapshot at or before the window start.
+    const baseQ = withTicks ? db.prepare(`SELECT ${SNAP_COLS} FROM token_snapshots WHERE mint = ? AND t < ? ORDER BY t DESC, snap_id DESC LIMIT 1`) : null;
+    const mints = [];
+    let from = Number.MAX_SAFE_INTEGER, to = 0;
+    for (const mint of picked) {
+        let rs = rowsQ.all(mint, since, until);
+        if (ticksQ) {
+            const ks = ticksQ.all(mint, since, until);
+            if (ks.length) {
+                const prior = baseQ.get(mint, since);
+                rs = mergeTicks(prior ? [prior, ...rs] : rs, ks);
+                if (prior)
+                    rs = rs.filter((r) => r !== prior);
+            }
+        }
+        const first = rs.find((r) => r.kind === 'live');
+        if (!first)
+            continue;
+        const t0 = first.t;
+        const kept = rs.filter((r) => r.t >= t0 && r.t <= t0 + span && numOrNull(r.price_usd) !== null);
+        if (!kept.length)
+            continue;
+        // Identity from the first row that has one (a mint seen by ticks before any snapshot has none on its first row).
+        const named = rs.find((r) => r.symbol !== null && r.symbol !== undefined) ?? first;
+        const created = numOrNull(named.created_at) ?? numOrNull(first.created_at) ?? numOrNull(first.pair_created_at);
+        mints.push({
+            mint,
+            symbol: String(named.symbol ?? '?').slice(0, 16),
+            launchpad: String(named.launchpad ?? 'unknown'),
+            createdAt: created,
+            rows: kept.map((r) => [
+                r.t, r.kind, sig(numOrNull(r.price_usd)), sig(numOrNull(r.mcap)), sig(numOrNull(r.mcap_resolved)), r.mcap_flagged ? 1 : 0, sig(numOrNull(r.liquidity_usd)),
+                sig(numOrNull(r.vol_m5)), sig(numOrNull(r.vol_h1)), sig(numOrNull(r.vol_h24)), numOrNull(r.buys_m5), numOrNull(r.sells_m5), numOrNull(r.buys_h24), numOrNull(r.sells_h24),
+                sig(numOrNull(r.chg_m5)), sig(numOrNull(r.chg_h1)), sig(numOrNull(r.chg_h6)), sig(numOrNull(r.chg_h24)),
+                numOrNull(r.holder_count), sig(numOrNull(r.top_holders_pct)), sig(numOrNull(r.dev_pct)),
+                r.mint_auth_enabled === null ? null : r.mint_auth_enabled ? 1 : 0, r.freeze_auth_enabled === null ? null : r.freeze_auth_enabled ? 1 : 0, sig(numOrNull(r.organic_score)),
+            ]),
+        });
+        from = Math.min(from, kept[0].t);
+        to = Math.max(to, kept[kept.length - 1].t);
+    }
+    return {
+        schema: TAPE_SCHEMA,
+        source: withTicks ? 'recorder token_snapshots + autotrade_ticks (read-only)' : 'recorder token_snapshots (read-only)',
+        extractedAt: new Date().toISOString(),
+        window: { from: mints.length ? from : 0, to },
+        note: withTicks
+            ? 'Change-driven rows while listed, sweep re-observations, and 5-10 s tick samples for focus coins (slow fields carried forward). No trades.'
+            : 'Change-driven rows at the app refresh cadence while listed, plus sweep re-observations. No candles or trades.',
+        columns: TAPE_COLUMNS,
+        mints,
+    };
+}
+export function saveTape(path, doc) {
+    // One mint row array per line: diffable and still small.
+    const head = { ...doc, mints: undefined };
+    const lines = doc.mints.map((m) => `    ${JSON.stringify(m)}`).join(',\n');
+    const json = JSON.stringify(head, null, 2).replace(/\n}$/, `,\n  "mints": [\n${lines}\n  ]\n}\n`);
+    writeFileSync(path, json);
+}
+export function readTapeDoc(path) {
+    const doc = JSON.parse(readFileSync(path, 'utf8'));
+    if (doc.schema !== TAPE_SCHEMA)
+        throw new Error(`not a ${TAPE_SCHEMA} file`);
+    return doc;
+}
+/** Expand a tape document into ticks in deterministic time order (t, then mint). */
+export function tapeFromDoc(doc) {
+    const col = new Map(doc.columns.map((c, i) => [c, i]));
+    const at = (r, k) => r[col.get(k) ?? -1];
+    const ticks = [];
+    for (const m of doc.mints) {
+        for (const r of m.rows) {
+            ticks.push({
+                mint: m.mint, t: at(r, 't'), kind: at(r, 'kind') === 'sweep' ? 'sweep' : 'live',
+                symbol: m.symbol, launchpad: m.launchpad, createdAt: m.createdAt,
+                price: numOrNull(at(r, 'price')), mcap: numOrNull(at(r, 'mcap')), mcapResolved: numOrNull(at(r, 'mcapResolved')), mcapFlagged: Boolean(at(r, 'mcapFlagged')),
+                liq: numOrNull(at(r, 'liq')), vol5m: numOrNull(at(r, 'vol5m')), vol1h: numOrNull(at(r, 'vol1h')), vol24: numOrNull(at(r, 'vol24')),
+                buys5m: numOrNull(at(r, 'buys5m')), sells5m: numOrNull(at(r, 'sells5m')), buys24: numOrNull(at(r, 'buys24')), sells24: numOrNull(at(r, 'sells24')),
+                chg5m: numOrNull(at(r, 'chg5m')), chg1h: numOrNull(at(r, 'chg1h')), chg6h: numOrNull(at(r, 'chg6h')), chg24h: numOrNull(at(r, 'chg24h')),
+                holders: numOrNull(at(r, 'holders')), top10: numOrNull(at(r, 'top10')), dev: numOrNull(at(r, 'dev')),
+                mintAuth: bool(at(r, 'mintAuth')), freezeAuth: bool(at(r, 'freezeAuth')), org: numOrNull(at(r, 'org')),
+            });
+        }
+    }
+    ticks.sort((a, b) => a.t - b.t || (a.mint < b.mint ? -1 : a.mint > b.mint ? 1 : 0));
+    return { source: doc.source, ticks, mints: doc.mints.map((m) => m.mint) };
+}
+export const loadTape = (path) => tapeFromDoc(readTapeDoc(path));
+/** The screener's row shape for a tick, so strategies reuse the exact filter grammar of the screen. */
+export function tickRow(k) {
+    const base = { mintAuth: k.mintAuth, freezeAuth: k.freezeAuth, top10: k.top10, dev: k.dev, bundled: null, lpLocked: k.launchpad === 'pump.fun' ? 100 : null };
+    return {
+        mint: k.mint, symbol: k.symbol, name: '', launchpad: k.launchpad,
+        price: k.price, mcap: k.mcap, mcapFlagged: k.mcapFlagged, fdv: null, liq: k.liq,
+        vol24: k.vol24, vol6h: null, vol1h: k.vol1h, vol5m: k.vol5m,
+        ageMin: k.createdAt ? Math.max(0, (k.t - k.createdAt) / 60000) : null,
+        holders: k.holders, holders24: null, holdersChgPct: null,
+        chg: { m5: k.chg5m, h1: k.chg1h, h6: k.chg6h, h24: k.chg24h }, spark: undefined,
+        buys: k.buys24, sells: k.sells24, org: k.org, ...base, snipers: null, flags: deriveFlags(base),
+        verified: false, sus: false, bonding: null, pair: null, sources: [], stale: k.kind === 'sweep', fetchedAt: k.t, aiNote: null, image: null,
+    };
+}