dexterm-cli 0.1.6 → 0.2.0

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

@@ -0,0 +1,237 @@
+// dexterm history recorder: position-grade ticks for autotrade (task-1504, AUTOTRADE-SPEC §3 "Data today vs what
+// must be recorded"). The change-driven `token_snapshots` rows land every ~2 min at best and only on a ≥ 5 % move,
+// which hides the intrabar path a stop or a take-profit lives on. This lane samples the FEW coins that matter to a
+// position every 5–10 s and writes every sample:
+//
+//   focus      held > open > candidate > watch, one role per mint (the highest wins), at most `maxCoins`
+//              (default 60 = two calls). Sources are injected: the collector reads the watchlist and the paper
+//              wallet from the DB and the autotrade focus file (`focus.json`, written by the runner / the app).
+//   cadence    held + open coins every `fastEveryMs` (5 s), candidate + watch every `slowEveryMs` (10 s). A call
+//              that goes out anyway is topped up with coins not yet due (oldest sample first): a batch of 30
+//              costs the same one request.
+//   budget     DexScreener `tokens/v1` batches of 30 only (never a per-coin keyless Jupiter call), through the
+//              data layer's limiter and health gate; 'normal' priority when a held/open coin is in the call,
+//              'low' otherwise; skipped while the bucket is paused after a 429; a per-UTC-day call ceiling.
+//   candles    every sample with a price folds into `autotrade_candles_1m` (sampled OHLC: high/low are of the
+//              samples, not of every trade).
+//
+// No change detection and no raw JSON: a tick row is ~100 bytes. Retention (retention.ts) keeps ticks 14 days.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { withPriority, systemClock } from '../../data/src/index.js';
+/** Priority order: earlier roles are sampled first and faster. */
+export const FOCUS_ROLES = ['held', 'open', 'candidate', 'watch'];
+export const DEFAULT_TICKS = { fastEveryMs: 5_000, slowEveryMs: 10_000, maxCoins: 60, batch: 30, maxCallsPerDay: 36_000 };
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const MIN = 60_000;
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const isFast = (r) => r === 'held' || r === 'open';
+/** One role per mint (the highest-priority role wins), invalid mints dropped, in priority order. */
+export function mergeFocus(entries) {
+    const best = new Map();
+    for (const e of entries) {
+        if (!e || typeof e.mint !== 'string' || !BASE58.test(e.mint) || !FOCUS_ROLES.includes(e.role))
+            continue;
+        const cur = best.get(e.mint);
+        if (!cur || FOCUS_ROLES.indexOf(e.role) < FOCUS_ROLES.indexOf(cur))
+            best.set(e.mint, e.role);
+    }
+    return [...best].map(([mint, role]) => ({ mint, role })).sort((a, b) => FOCUS_ROLES.indexOf(a.role) - FOCUS_ROLES.indexOf(b.role));
+}
+/** The sampler. Owns no connection: it writes through the recorder's DB handle (same file, same thread). */
+export class TickLane {
+    policy;
+    db;
+    focus;
+    clock;
+    onLog;
+    /** mint -> time of its last sample this process took. */
+    last = new Map();
+    polling = false;
+    day = '';
+    dayCalls = 0;
+    counters = { polls: 0, calls: 0, written: 0 };
+    stmts;
+    constructor(db, opts) {
+        this.db = db;
+        this.focus = opts.focus;
+        this.policy = { ...DEFAULT_TICKS, ...opts.policy };
+        this.clock = opts.clock ?? systemClock;
+        this.onLog = opts.onLog;
+        this.stmts = {
+            tick: db.prepare(`INSERT OR IGNORE INTO autotrade_ticks (mint, t, role, price_usd, liquidity_usd, mcap, fdv, vol_m5, vol_h1, buys_m5, sells_m5, chg_m5, chg_h1, pair_address, pair_created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+            candle: db.prepare(`INSERT INTO autotrade_candles_1m (mint, t, o, h, l, c, liq_c, mcap_c, n) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1)
+        ON CONFLICT(mint, t) DO UPDATE SET h = MAX(h, excluded.h), l = MIN(l, excluded.l), c = excluded.c, liq_c = excluded.liq_c, mcap_c = excluded.mcap_c, n = n + 1`),
+            meta: db.prepare("INSERT OR REPLACE INTO recorder_meta (key, value) VALUES ('tick_calls', ?)"),
+        };
+    }
+    /** Tick calls issued in the current UTC day (persisted in recorder_meta, so a restart keeps the count). */
+    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 = 'tick_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;
+    }
+    /**
+     * Which coins this poll samples: every due coin in priority order up to `maxCoins`, then the last batch topped
+     * up with coins not yet due (oldest sample first). `overCap` counts focus coins past `maxCoins`.
+     */
+    plan(now = this.clock.now(), maxCalls = Math.ceil(this.policy.maxCoins / this.policy.batch)) {
+        const focus = mergeFocus(this.focus());
+        const cap = Math.min(this.policy.maxCoins, maxCalls * this.policy.batch);
+        const inCap = focus.slice(0, cap);
+        const overCap = focus.length - inCap.length;
+        const isDue = (e) => now - (this.last.get(e.mint) ?? -Infinity) >= (isFast(e.role) ? this.policy.fastEveryMs : this.policy.slowEveryMs);
+        const due = inCap.filter(isDue);
+        if (!due.length)
+            return { coins: [], due: 0, overCap, focus: focus.length };
+        const room = Math.ceil(due.length / this.policy.batch) * this.policy.batch - due.length;
+        const ride = inCap.filter((e) => !isDue(e)).sort((a, b) => (this.last.get(a.mint) ?? 0) - (this.last.get(b.mint) ?? 0)).slice(0, room);
+        return { coins: [...due, ...ride], due: due.length, overCap, focus: focus.length };
+    }
+    /** One poll. The host calls this every `fastEveryMs` (the collector's tick loop). Never throws. */
+    async poll(deps, now = this.clock.now()) {
+        const none = (skipped, overCap = 0) => ({ coins: 0, calls: 0, answered: 0, written: 0, overCap, skipped });
+        if (this.polling)
+            return none('in-flight');
+        let budget = this.policy.maxCallsPerDay - this.callsToday(now);
+        if (budget <= 0)
+            return none('day-cap');
+        let planned;
+        try {
+            planned = this.plan(now, Math.min(budget, Math.ceil(this.policy.maxCoins / this.policy.batch)));
+        }
+        catch (err) {
+            this.log(`focus failed: ${msg(err)}`);
+            return none('no-focus');
+        }
+        if (!planned.coins.length)
+            return none(planned.focus ? 'not-due' : 'no-focus', planned.overCap);
+        if (deps.limiter.bucket('dexscreener').stats().pausedUntil > now)
+            return none('paused', planned.overCap);
+        this.polling = true;
+        this.counters.polls++;
+        const res = { coins: planned.coins.length, calls: 0, answered: 0, written: 0, overCap: planned.overCap, skipped: null };
+        try {
+            for (let i = 0; i < planned.coins.length && budget > 0; i += this.policy.batch) {
+                const chunk = planned.coins.slice(i, i + this.policy.batch);
+                const priority = chunk.some((e) => isFast(e.role)) ? 'normal' : 'low';
+                res.calls++;
+                budget--;
+                this.dayCalls++;
+                this.stmts.meta.run(JSON.stringify({ day: this.day, calls: this.dayCalls }));
+                const views = await withPriority(priority, () => deps.dexscreener.tokens(chunk.map((e) => e.mint)));
+                const t = this.clock.now();
+                const w = this.write(chunk, views, t);
+                res.answered += w.answered;
+                res.written += w.written;
+            }
+        }
+        catch (err) {
+            res.error = msg(err);
+            this.log(`tick poll failed: ${res.error}`);
+        }
+        finally {
+            this.polling = false;
+            this.counters.calls += res.calls;
+            this.counters.written += res.written;
+        }
+        return res;
+    }
+    /** Write one answered batch (one transaction): a tick per coin (NULL price when no pair came back) + candles. */
+    write(chunk, views, t) {
+        let answered = 0, written = 0;
+        this.db.exec('BEGIN');
+        try {
+            for (const e of chunk) {
+                this.last.set(e.mint, t);
+                const p = views.get(e.mint)?.pair;
+                if (p)
+                    answered++;
+                const price = p ? fin(p.priceUsd) : null;
+                const liq = p ? fin(p.liquidityUsd) : null;
+                const mcap = p ? fin(p.mcap) : null;
+                const r = this.stmts.tick.run(e.mint, t, e.role, price, liq, mcap, p ? fin(p.fdv) : null, p ? fin(p.volume.m5) : null, p ? fin(p.volume.h1) : null, p ? fin(p.txns.m5?.buys) : null, p ? fin(p.txns.m5?.sells) : null, p ? fin(p.priceChange.m5) : null, p ? fin(p.priceChange.h1) : null, p?.pairAddress || null, p ? fin(p.createdAt) : null);
+                if (Number(r.changes) > 0)
+                    written++;
+                if (price !== null && price > 0 && Number(r.changes) > 0)
+                    this.stmts.candle.run(e.mint, Math.floor(t / MIN) * MIN, price, price, price, price, liq, mcap);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+        // Forget coins that left the focus long ago (bounded memory over a long run).
+        if (this.last.size > 4 * this.policy.maxCoins)
+            for (const [m, lt] of this.last)
+                if (t - lt > 3_600_000)
+                    this.last.delete(m);
+        return { answered, written };
+    }
+    log(line) {
+        this.onLog?.(`recorder: ${line}\n`);
+    }
+}
+// ---------------------------------------------------------------- focus sources
+/**
+ * Focus coins the app's own DB already knows: every watchlist mint ('watch') and every paper position with a
+ * token balance ('held'). Tables that do not exist yet (a fresh DB) contribute nothing.
+ */
+export function dbFocus(db) {
+    const has = (name) => !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+    const out = [];
+    if (has('watchlist'))
+        for (const r of db.prepare('SELECT mint FROM watchlist').all())
+            out.push({ mint: r.mint, role: 'watch' });
+    if (has('paper_positions'))
+        for (const r of db.prepare("SELECT mint FROM paper_positions WHERE tokens_raw NOT IN ('0', '')").all())
+            out.push({ mint: r.mint, role: 'held' });
+    return out;
+}
+/** The rendezvous file other processes (the autotrade runner, the app) publish focus coins in. */
+export const FOCUS_FILE_SCHEMA = 'dexterm-autotrade-focus/1';
+/** A focus file not rewritten for this long is ignored (a dead writer must not pin coins to the fast lane). */
+export const FOCUS_FILE_STALE_MS = 30 * MIN;
+/** `<dexterm home>/autotrade/focus.json`. */
+export const focusFilePath = (home) => join(home, 'autotrade', 'focus.json');
+/** Read a focus file: missing, garbled, stale or expired entries contribute nothing. Never throws. */
+export function readFocusFile(path, now) {
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!doc || doc.schema !== FOCUS_FILE_SCHEMA || !Array.isArray(doc.entries) || !(now - Number(doc.updatedAt) <= FOCUS_FILE_STALE_MS))
+        return [];
+    return mergeFocus(doc.entries.filter((e) => e && (e.until === undefined || Number(e.until) >= now)).map((e) => ({ mint: e.mint, role: e.role })));
+}
+/** Write a focus file atomically (tmp + rename, mode 0600). */
+export function writeFocusFile(path, entries, now) {
+    mkdirSync(dirname(path), { recursive: true });
+    const doc = { schema: FOCUS_FILE_SCHEMA, updatedAt: now, entries: [...entries] };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Sampled 1m candles for one mint, oldest first (read-only use). */
+export function candlesFromDb(db, mint, from = 0, to = Number.MAX_SAFE_INTEGER) {
+    return db.prepare('SELECT t, o, h, l, c, liq_c, mcap_c, n FROM autotrade_candles_1m WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t').all(mint, from, to)
+        .map((r) => ({ t: Number(r.t), o: Number(r.o), h: Number(r.h), l: Number(r.l), c: Number(r.c), liq: r.liq_c ?? null, mcap: r.mcap_c ?? null, n: Number(r.n) }));
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

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

@@ -7,6 +7,7 @@ export * from "./flush.js";
 export * from "./layout.js";
 export * from "./keymap.js";
 export * from "./widgets.js";
+export * from "./markers.js";
 export * from "./fx.js";
 export * from "./fx-trade.js";
 export * from "./sound.js";

package/dist/packages/tui/src/keymap.js

@@ -339,7 +339,6 @@ export const DEFAULT_KEYMAP = new Keymap([
     { keys: ['!'], action: 'plans.panic', label: 'PANIC', screen: 'plans' },
     { keys: ['M'], action: 'plans.popup', label: 'popup', screen: 'plans' },
     { keys: ['G'], action: 'plans.gate', label: 'hands-free gate', screen: 'plans' },
-    { keys: ['L'], action: 'plans.live', label: 'fire path paper/live', screen: 'plans' },
     // task-1360 copy trading. `U` opens the FOLLOWED WALLETS screen from anywhere (free capital: not B/S/P/W/V/X/T/L/C/F/Z/R/
     // K/M/N/D/O/G/I). On it: `i` types a wallet address (+ optional label) to follow, `d` unfollows the selected wallet,
     // `r` (global refresh) polls now. Nothing on this screen trades: a buy/sell alert is information only.
@@ -368,4 +367,32 @@ export const DEFAULT_KEYMAP = new Keymap([
     { keys: ['d'], action: 'rules.remove', label: 'delete rule', screen: 'rules' },
     { keys: ['tab'], action: 'rules.tab', label: 'rules ⇄ proposals', screen: 'rules' },
     { keys: ['x'], action: 'rules.dismiss', label: 'dismiss proposal', screen: 'rules' },
+    // task-1508 AUTOTRADE (paper). `Q` (free capital everywhere) opens the screen; tab cycles its five views (strategies,
+    // editor, compare, backtest, runner). The lowercase verbs below override the global w/b/x/p/i/s on this screen only.
+    // `!` soft-stops the paper runner, `p` pauses its new entries, `f` flattens after a y confirm. Edits only touch the
+    // user's own strategy files (validated, journaled); there is no key here for live mode, mandates or the signer.
+    { keys: ['Q'], action: 'screen.autotrade', label: 'autotrade (paper)' },
+    { keys: ['tab'], action: 'autotrade.view', label: 'next view', screen: 'autotrade' },
+    { keys: ['n'], action: 'autotrade.new', label: 'new from preset', screen: 'autotrade' },
+    { keys: ['d'], action: 'autotrade.dup', label: 'duplicate', screen: 'autotrade' },
+    { keys: ['e'], action: 'autotrade.edit', label: 'edit', screen: 'autotrade' },
+    { keys: ['c'], action: 'autotrade.compare', label: 'mark to compare', screen: 'autotrade' },
+    { keys: ['b'], action: 'autotrade.backtest', label: 'backtest', screen: 'autotrade' },
+    { keys: ['w'], action: 'autotrade.sweep', label: 'sweep (held-out)', screen: 'autotrade' },
+    { keys: ['x'], action: 'autotrade.export', label: 'export file', screen: 'autotrade' },
+    { keys: ['i'], action: 'autotrade.import', label: 'import file', screen: 'autotrade' },
+    { keys: ['r'], action: 'autotrade.run', label: 'runner', screen: 'autotrade' },
+    { keys: ['s'], action: 'autotrade.save', label: 'save (new version)', screen: 'autotrade' },
+    { keys: ['u'], action: 'autotrade.undo', label: 'undo', screen: 'autotrade' },
+    { keys: ['!'], action: 'autotrade.kill', label: 'kill (soft stop)', screen: 'autotrade' },
+    { keys: ['p'], action: 'autotrade.pause', label: 'pause new entries', screen: 'autotrade' },
+    { keys: ['f'], action: 'autotrade.flatten', label: 'flatten (confirm)', screen: 'autotrade' },
+    { keys: ['o'], action: 'autotrade.proposal', label: 'review chat proposal', screen: 'autotrade' },
+    // task-1647: a strategy's JOURNEY (draft → backtested → forward-tested → always-on → real). F starts a 24 h paper forward
+    // test (live data, the strategy's own bankroll), X stops it, A opens a pending always-on promotion (y applies). Real is
+    // never applied from a key: it needs the user's caps and a typed phrase on a terminal.
+    { keys: ['J'], action: 'autotrade.journey', label: 'journey (ladder)', screen: 'autotrade' },
+    { keys: ['F'], action: 'autotrade.forward', label: 'forward test (paper)', screen: 'autotrade' },
+    { keys: ['X'], action: 'autotrade.forwardstop', label: 'stop forward test', screen: 'autotrade' },
+    { keys: ['A'], action: 'autotrade.promote', label: 'review promotion', screen: 'autotrade' },
 ]);

package/dist/packages/tui/src/markers.js

@@ -0,0 +1,219 @@
+// @dexterm/tui — task-1483 BUY / SELL markers: the pure model every chart draws from (terminal candles, the agent
+// views' traces, and — mirrored in packages/popup/src/pages/chart-lib.js, parity-tested — the chart popup).
+//
+// Input: the fills the app already holds (the paper ledger's trades and the live ledger's confirmed swaps), never a
+// fetch. Output: one marker per (bar, side, source) for the bars on screen, the open position's average entry per
+// source, and the closed round trips. Display only: nothing here can arm, size, sign or confirm anything.
+//
+// Placement rules (the card's "never clamped to a wrong place"):
+//   - a fill belongs to the bar whose period contains its time (bar open = floor(t / period) · period);
+//   - a fill older than the first bar on screen, newer than the last bar, or in a period with no bar (a quiet coin
+//     can skip a minute) is OMITTED and counted, never moved onto a neighbouring bar;
+//   - the price is the fill's own USD price (token-weighted when one bar holds several fills of a side); with no
+//     known price the marker is drawn against the bar (below it for a buy, above it for a sell) and says so.
+// The axis never changes a marker's position: bars and markers are both laid out in USD price; an mcap axis only
+// relabels (price × the current supply, task-1366/1472).
+/** Bar periods by the app's timeframe names. */
+export const MARKER_PERIOD_MS = { '1m': 60e3, '5m': 300e3, '15m': 900e3, '1h': 3600e3, '4h': 14400e3, '1d': 86400e3 };
+/** The open time of the bar a time falls in. */
+export function bucketOf(t, periodMs) { return Math.floor(t / periodMs) * periodMs; }
+const fin = (n) => typeof n === 'number' && Number.isFinite(n);
+const EPS = 1e-9;
+/** Valid fills only (finite time, a side, a source, a positive token amount), oldest first; stable for equal times. */
+export function cleanFills(fills) {
+    const out = [];
+    for (const f of fills ?? []) {
+        if (!f || !fin(f.t) || (f.side !== 'buy' && f.side !== 'sell') || (f.source !== 'paper' && f.source !== 'live'))
+            continue;
+        if (!fin(f.tokens) || f.tokens <= 0)
+            continue;
+        out.push({ t: f.t, side: f.side, source: f.source, priceUsd: fin(f.priceUsd) && f.priceUsd > 0 ? f.priceUsd : null, tokens: f.tokens, sol: fin(f.sol) && f.sol >= 0 ? f.sol : null });
+    }
+    return out.map((f, i) => [f, i]).sort((a, b) => a[0].t - b[0].t || a[1] - b[1]).map(([f]) => f);
+}
+/**
+ * Replay the fills per source (oldest first) the way the ledgers book them: a buy adds tokens and cost, a sell
+ * removes tokens at the average cost. A sell bigger than what the replay holds (the history was truncated) is
+ * treated as closing. Returns every fill annotated, the open position's average entry, and the closed trips.
+ */
+export function replayFills(fills) {
+    const st = {
+        paper: { held: 0, cost: 0, costOk: true, trip: null },
+        live: { held: 0, cost: 0, costOk: true, trip: null },
+    };
+    const out = [];
+    const trips = [];
+    for (const f of cleanFills(fills)) {
+        const s = st[f.source];
+        const before = s.held;
+        if (f.side === 'buy') {
+            if (s.held <= EPS) {
+                s.held = 0;
+                s.cost = 0;
+                s.costOk = true;
+                s.trip = { openT: f.t, bTok: 0, bUsd: 0, bOk: true, sTok: 0, sUsd: 0, sOk: true };
+            }
+            s.held += f.tokens;
+            if (f.priceUsd === null)
+                s.costOk = false;
+            else
+                s.cost += f.tokens * f.priceUsd;
+            if (s.trip) {
+                s.trip.bTok += f.tokens;
+                if (f.priceUsd === null)
+                    s.trip.bOk = false;
+                else
+                    s.trip.bUsd += f.tokens * f.priceUsd;
+            }
+            out.push({ ...f, heldBefore: before, heldAfter: s.held, partial: before > EPS, closes: false });
+            continue;
+        }
+        const sold = Math.min(f.tokens, s.held);
+        const frac = s.held > EPS ? sold / s.held : 1;
+        s.cost -= s.cost * frac;
+        s.held = Math.max(0, s.held - f.tokens);
+        const closes = s.held <= f.tokens * 1e-9 || s.held <= EPS;
+        if (closes)
+            s.held = 0;
+        if (s.trip) {
+            s.trip.sTok += f.tokens;
+            if (f.priceUsd === null)
+                s.trip.sOk = false;
+            else
+                s.trip.sUsd += f.tokens * f.priceUsd;
+        }
+        out.push({ ...f, heldBefore: before, heldAfter: s.held, partial: !closes, closes });
+        if (closes) {
+            if (s.trip)
+                trips.push({ source: f.source, openT: s.trip.openT, closeT: f.t, entryUsd: s.trip.bOk && s.trip.bTok > 0 ? s.trip.bUsd / s.trip.bTok : null, exitUsd: s.trip.sOk && s.trip.sTok > 0 ? s.trip.sUsd / s.trip.sTok : null });
+            s.trip = null;
+            s.cost = 0;
+            s.costOk = true;
+        }
+    }
+    const avg = (src) => { const s = st[src]; return s.held > EPS && s.costOk && s.cost > 0 ? s.cost / s.held : null; };
+    return { fills: out, avgEntry: { paper: avg('paper'), live: avg('live') }, trips };
+}
+/** Index of `t` in an ascending list, or -1 (binary search). */
+function indexOf(times, t) {
+    let lo = 0, hi = times.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const v = times[mid];
+        if (v === t)
+            return mid;
+        if (v < t)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return -1;
+}
+/**
+ * The markers for a window of bars: one per (bar, side, source), oldest first; buys before sells within a bar.
+ * Fills outside the window (or in a period with no bar) are counted in before / after / gap, never placed.
+ */
+export function chartMarkers(fills, win) {
+    const rp = replayFills(fills);
+    const times = win.barTimes;
+    const empty = () => ({ markers: [], before: 0, after: 0, gap: 0, avgEntry: rp.avgEntry, trips: [] });
+    if (!(win.periodMs > 0) || !times.length) {
+        const e = empty();
+        e.before = rp.fills.length;
+        return e;
+    }
+    const first = times[0], last = times[times.length - 1];
+    const res = empty();
+    const by = new Map();
+    for (const f of rp.fills) {
+        const b = bucketOf(f.t, win.periodMs);
+        if (b < first) {
+            res.before++;
+            continue;
+        }
+        if (b > last) {
+            res.after++;
+            continue;
+        }
+        const index = indexOf(times, b);
+        if (index < 0) {
+            res.gap++;
+            continue;
+        }
+        const key = `${b}|${f.side}|${f.source}`;
+        let m = by.get(key);
+        if (!m) {
+            m = { side: f.side, source: f.source, bucket: b, index, t: f.t, tLast: f.t, priceUsd: null, tokens: 0, sol: 0, count: 0, partial: false, closes: false, pTok: 0, pUsd: 0, solOk: true };
+            by.set(key, m);
+        }
+        m.count++;
+        m.tLast = f.t;
+        m.tokens += f.tokens;
+        if (f.sol === null)
+            m.solOk = false;
+        else
+            m.sol = (m.sol ?? 0) + f.sol;
+        if (f.priceUsd !== null) {
+            m.pTok += f.tokens;
+            m.pUsd += f.tokens * f.priceUsd;
+        }
+        if (f.partial)
+            m.partial = true;
+        if (f.closes)
+            m.closes = true;
+    }
+    const order = (m) => (m.side === 'buy' ? 0 : 1) * 2 + (m.source === 'live' ? 1 : 0);
+    res.markers = [...by.values()].map(({ pTok, pUsd, solOk, ...m }) => ({ ...m, priceUsd: pTok > 0 ? pUsd / pTok : null, sol: solOk ? m.sol : null }))
+        .sort((a, b) => a.index - b.index || order(a) - order(b));
+    res.trips = rp.trips.filter((r) => bucketOf(r.closeT, win.periodMs) >= first && bucketOf(r.openT, win.periodMs) <= last);
+    return res;
+}
+/** The glyph for a marker: solid ▲ / ▼ for live fills, hollow △ / ▽ for paper. Reads without colour (NO_COLOR). */
+export function markerGlyph(side, source) {
+    if (source === 'paper')
+        return side === 'buy' ? '△' : '▽';
+    return side === 'buy' ? '▲' : '▼';
+}
+/** The letter for a marker (always shown with the glyph, so BUY / SELL never depends on colour). */
+export function markerLetter(side) { return side === 'buy' ? 'B' : 'S'; }
+/** "△ ▽ paper  ▲ ▼ live" — the legend for the sources actually on screen (empty when none). */
+export function markerLegend(markers, avgShown = false) {
+    const has = (s) => markers.some((m) => m.source === s);
+    const parts = [];
+    if (has('paper'))
+        parts.push('△B ▽S paper');
+    if (has('live'))
+        parts.push('▲B ▼S live');
+    if (avgShown)
+        parts.push('┄ avg entry');
+    return parts.join('  ');
+}
+/** "+2 fills off-chart (1 earlier, 1 newer than the last candle)" — what the window omitted, or ''. */
+export function omittedNote(s) {
+    const n = s.before + s.after + s.gap;
+    if (!n)
+        return '';
+    const why = [];
+    if (s.before)
+        why.push(`${s.before} earlier`);
+    if (s.after)
+        why.push(`${s.after} newer than the last candle`);
+    if (s.gap)
+        why.push(`${s.gap} in a period with no candle`);
+    return `+${n} fill${n === 1 ? '' : 's'} off-chart (${why.join(', ')})`;
+}
+/**
+ * The plot row of a price on a terminal chart laid out between `lo` and `hi` over `plotH` rows (row 0 = `hi`), the same
+ * mapping candleChart uses for candle bodies. Null when the price is outside the plotted range (omitted, not clamped).
+ */
+export function markerRow(priceUsd, lo, hi, plotH) {
+    if (!fin(priceUsd) || !(hi > lo) || plotH < 1)
+        return null;
+    const r = Math.floor(((hi - priceUsd) / (hi - lo)) * plotH);
+    return r >= 0 && r < plotH ? r : null;
+}
+/** "B 41.2k" / "S×2 0.0₄123": the compact terminal label (axis value = price × scale, formatted by the axis). */
+export function markerLabel(m, fmt, scale = 1) {
+    const head = `${markerLetter(m.side)}${m.count > 1 ? `×${m.count}` : ''}`;
+    return m.priceUsd === null ? head : `${head} ${fmt(m.priceUsd * (scale > 0 ? scale : 1))}`;
+}