dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/analyst-actions.js

@@ -0,0 +1,133 @@
+// @dexterm/data — analyst UI-action channel (task-1313 part C).
+//
+// The analyst (a local `claude -p` run) can drive non-financial app navigation through a small,
+// strictly-validated action set. The MCP server (the only thing claude can call) validates an action
+// against the screen context it was given and, on success, appends one line to a local, token-
+// authenticated channel file. The running TUI tails that file and RE-validates every action against
+// its *current* state before applying it, then shows "analyst did X".
+//
+// Trust model: all token-derived text (symbols, names, descriptions) is untrusted. An injected
+// instruction that convinces the model to call `open_token EVILMINT` cannot act, because a mint is
+// only accepted when it is already in the caller-supplied allow-list (what is on screen / watched).
+// Nothing here can sign, send, size, or confirm a trade: `open_ticket` only *opens* the PAPER ticket.
+//
+// This module is pure and zero-dependency so both the MCP server and the CLI import the same
+// validator and the same channel format.
+export const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** Env var the MCP server reads for the channel file path; set by the CLI when it spawns claude. */
+export const ACTION_FILE_ENV = 'DEXTERM_ACTION_FILE';
+/** Env var carrying the per-run random token that authenticates channel lines. */
+export const ACTION_TOKEN_ENV = 'DEXTERM_ACTION_TOKEN';
+/** The five non-financial UI actions the analyst may request. */
+export const ANALYST_ACTION_TYPES = ['open_token', 'show_in_screener', 'add_to_watchlist', 'switch_feed', 'open_ticket'];
+/** Max actions the consumer should apply per rolling window, and the window length. Advisory shared constants. */
+export const ACTION_RATE = { max: 6, windowMs: 10_000 };
+const FILTER_MAX = 120;
+// A conservative charset for a screener filter string; the consumer re-parses it with the real grammar.
+// `!` is included so tag negation (`!flag:mint`, `!launchpad:pump`) — a documented part of the grammar —
+// survives the boundary instead of being rejected as malformed (task-1313 part E).
+const FILTER_SAFE_RE = /^[\w\s<>=:.%$,+!\-|()]*$/;
+function isObj(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+/**
+ * Validate one requested action against `allow`. Strict: unknown types/fields, out-of-allow-list
+ * mints/feeds/sorts, and malformed values are all rejected. Pure — no I/O, no state.
+ */
+export function validateAnalystAction(raw, allow) {
+    if (!isObj(raw))
+        return { ok: false, error: 'action must be an object' };
+    const type = raw.type;
+    if (typeof type !== 'string' || !ANALYST_ACTION_TYPES.includes(type)) {
+        return { ok: false, error: `unknown action type ${JSON.stringify(type)}` };
+    }
+    if (allow.types && !allow.types.includes(type)) {
+        return { ok: false, error: `${type}: not allowed in this session (allowed: ${allow.types.join(', ') || 'none — observe-only'})` };
+    }
+    const mintOk = (m) => typeof m === 'string' && BASE58_RE.test(m) && allow.mints.includes(m);
+    const short = (m) => m.slice(0, 4) + '…' + m.slice(-4);
+    switch (type) {
+        case 'open_token': {
+            if (!mintOk(raw.mint))
+                return { ok: false, error: 'open_token: mint not among the tokens currently on screen' };
+            return { ok: true, action: { type, mint: raw.mint }, label: `opened ${short(raw.mint)}` };
+        }
+        case 'add_to_watchlist': {
+            if (!mintOk(raw.mint))
+                return { ok: false, error: 'add_to_watchlist: mint not among the tokens currently on screen' };
+            return { ok: true, action: { type, mint: raw.mint }, label: `watchlisted ${short(raw.mint)}` };
+        }
+        case 'open_ticket': {
+            if (!mintOk(raw.mint))
+                return { ok: false, error: 'open_ticket: mint not among the tokens currently on screen' };
+            if (raw.side !== 'buy' && raw.side !== 'sell')
+                return { ok: false, error: 'open_ticket: side must be "buy" or "sell"' };
+            return { ok: true, action: { type, mint: raw.mint, side: raw.side }, label: `opened a PAPER ${raw.side} ticket for ${short(raw.mint)}` };
+        }
+        case 'switch_feed': {
+            if (typeof raw.feed !== 'string' || !allow.feeds.includes(raw.feed)) {
+                return { ok: false, error: `switch_feed: feed must be one of ${allow.feeds.join(', ') || '(none)'}` };
+            }
+            return { ok: true, action: { type, feed: raw.feed }, label: `switched the screener to "${raw.feed}"` };
+        }
+        case 'show_in_screener': {
+            const out = { type };
+            const bits = [];
+            if (raw.filter !== undefined && raw.filter !== null && raw.filter !== '') {
+                if (typeof raw.filter !== 'string' || raw.filter.length > FILTER_MAX || !FILTER_SAFE_RE.test(raw.filter)) {
+                    return { ok: false, error: 'show_in_screener: filter is malformed or too long' };
+                }
+                out.filter = raw.filter.trim();
+                bits.push(`filter ${out.filter}`);
+            }
+            if (raw.sort !== undefined && raw.sort !== null) {
+                if (!isObj(raw.sort) || typeof raw.sort.key !== 'string' || !allow.sortKeys.includes(raw.sort.key)) {
+                    return { ok: false, error: `show_in_screener: sort.key must be one of ${allow.sortKeys.join(', ')}` };
+                }
+                const dir = raw.sort.dir === 'asc' ? 'asc' : 'desc';
+                out.sort = { key: raw.sort.key, dir };
+                bits.push(`sort ${out.sort.key} ${dir}`);
+            }
+            if (raw.highlight !== undefined && raw.highlight !== null && raw.highlight !== '') {
+                if (!mintOk(raw.highlight))
+                    return { ok: false, error: 'show_in_screener: highlight mint not among the tokens currently on screen' };
+                out.highlight = raw.highlight;
+                bits.push(`highlight ${short(raw.highlight)}`);
+            }
+            if (!bits.length)
+                return { ok: false, error: 'show_in_screener: nothing to do (give filter, sort, or highlight)' };
+            return { ok: true, action: out, label: `showed the screener (${bits.join(', ')})` };
+        }
+        default:
+            return { ok: false, error: `unknown action type ${type}` };
+    }
+}
+/** Serialize a channel line (newline-terminated). */
+export function serializeActionLine(token, seq, action) {
+    const line = { v: 1, token, seq, ts: Date.now(), action };
+    return JSON.stringify(line) + '\n';
+}
+/**
+ * Parse and authenticate one channel line. Returns the (still unvalidated) requested action only when
+ * the line is well-formed and its token matches `expectedToken`; otherwise null. Validation against an
+ * allow-list is a separate step (`validateAnalystAction`) the consumer must still run.
+ */
+export function parseActionLine(line, expectedToken) {
+    const s = line.trim();
+    if (!s)
+        return null;
+    let msg;
+    try {
+        msg = JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+    if (!isObj(msg) || msg.v !== 1)
+        return null;
+    if (typeof msg.token !== 'string' || msg.token !== expectedToken)
+        return null;
+    if (typeof msg.seq !== 'number' || !isObj(msg.action))
+        return null;
+    return { seq: msg.seq, action: msg.action };
+}

package/dist/packages/data/src/budget.js

@@ -0,0 +1,88 @@
+// Per-source request budget meter (task-1309). Every free data source gives each user their own
+// per-IP quota (that is why a local client scales: there is no shared server quota). This meter
+// counts the requests dexterm sends to each source — this session and today (persisted in the SQLite
+// cache, so restarts keep counting) — and exposes a snapshot + header label so the budget is visible.
+// Optional soft daily caps let a cautious user bound a source; passing no cap means "unlimited, just
+// count" (the limiter already paces to the documented rpm). The meter never sees or stores any key.
+import { systemClock } from "./clock.js";
+const NS = 'meter';
+const DAY_TTL_MS = 2 * 86_400_000;
+export const BUDGET_WARN_PCT = 0.8;
+/** Counts requests per source for a visible budget meter; soft daily caps are advisory, not enforced here. */
+export class BudgetMeter {
+    clock;
+    cache;
+    dayCaps;
+    warnPct;
+    session = new Map();
+    dayTotals = new Map();
+    dayKey = '';
+    constructor(opts = {}) {
+        this.clock = opts.clock ?? systemClock;
+        this.cache = opts.cache;
+        this.dayCaps = { ...opts.dayCaps };
+        this.warnPct = opts.warnPct ?? BUDGET_WARN_PCT;
+        this.roll();
+    }
+    static dayKeyFor(ms) {
+        return new Date(ms).toISOString().slice(0, 10);
+    }
+    roll() {
+        const key = BudgetMeter.dayKeyFor(this.clock.now());
+        if (key === this.dayKey)
+            return;
+        this.dayKey = key;
+        this.dayTotals.clear();
+    }
+    dayTotal(source) {
+        const cached = this.dayTotals.get(source);
+        if (cached !== undefined)
+            return cached;
+        const hit = this.cache?.get(NS, `req:${this.dayKey}:${source}`);
+        const n = hit && typeof hit.value === 'number' ? hit.value : 0;
+        this.dayTotals.set(source, n);
+        return n;
+    }
+    /** Record one request to `source`. */
+    charge(source) {
+        this.roll();
+        this.session.set(source, (this.session.get(source) ?? 0) + 1);
+        const day = this.dayTotal(source) + 1;
+        this.dayTotals.set(source, day);
+        this.cache?.set(NS, `req:${this.dayKey}:${source}`, day, { ttlMs: DAY_TTL_MS, source });
+    }
+    /** True while another request to `source` is within its soft cap (always true when uncapped). */
+    allow(source) {
+        this.roll();
+        const cap = this.dayCaps[source];
+        if (cap === undefined)
+            return true;
+        return this.dayTotal(source) < cap;
+    }
+    status(source) {
+        this.roll();
+        const cap = this.dayCaps[source] ?? null;
+        const day = this.dayTotal(source);
+        return {
+            source,
+            session: this.session.get(source) ?? 0,
+            day,
+            dayCap: cap,
+            dayPct: cap && cap > 0 ? day / cap : null,
+            over: cap !== null && day >= cap,
+        };
+    }
+    /** Every source seen this run (plus any with a cap), busiest first. */
+    snapshot() {
+        this.roll();
+        const sources = new Set([...this.session.keys(), ...Object.keys(this.dayCaps)]);
+        return [...sources].map((s) => this.status(s)).sort((a, b) => b.session - a.session);
+    }
+    /** Header-sized summary of the busiest sources, e.g. `req: dexscreener 42 · jupiter 11`. */
+    label(max = 3) {
+        const top = this.snapshot().filter((s) => s.session > 0).slice(0, max);
+        if (top.length === 0)
+            return 'req: 0';
+        return `req: ${top.map((s) => `${s.source} ${s.session}${s.dayCap ? `/${s.dayCap}` : ''}`).join(' · ')}`;
+    }
+}

package/dist/packages/data/src/cache.js

@@ -0,0 +1,142 @@
+// SQLite cache (SPEC §3.4) on Node's built-in `node:sqlite`.
+//
+// Why node:sqlite over better-sqlite3: it ships with Node >= 22.5 (verified on
+// 24.20), so there is no native addon to compile per platform/ABI, which keeps
+// `npx dexterm` and the Homebrew formula dependency-free. The API is synchronous
+// like better-sqlite3, which suits a cache. Trade-offs: it is still flagged
+// experimental in Node 24 and `bun build --compile` binaries would need a
+// bun:sqlite shim behind this same class (D-22).
+//
+// One table, namespaced: (ns, key) -> json, fetched_at, ttl_ms, source.
+// fetch() layers in-flight coalescing and stale-while-revalidate on top.
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { systemClock } from "./clock.js";
+/** TTLs from SPEC §3.4 (ms). `lists` (boosts/trending/recent feeds) is ours: they refresh at 15-30 s. */
+export const TTL = {
+    pairs: 10_000,
+    enrichment: 60_000,
+    price: 30_000,
+    candlesOpen: 30_000,
+    candlesClosed: 3_600_000,
+    holders: 60_000,
+    audit: 600_000,
+    rugcheck: 600_000,
+    socials: 3_600_000,
+    devHistory: 86_400_000,
+    lists: 15_000,
+};
+/** XDG data path for the cache DB (SPEC §2.2). Pure: does not create anything. */
+export function defaultDbPath(env = process.env) {
+    if (process.platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, 'dexterm', 'dexterm.db');
+    const base = env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+    return join(base, 'dexterm', 'dexterm.db');
+}
+export class Cache {
+    db;
+    clock;
+    inflight = new Map();
+    constructor(opts = {}) {
+        const path = opts.path ?? ':memory:';
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.clock = opts.clock ?? systemClock;
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA busy_timeout = 3000;
+      CREATE TABLE IF NOT EXISTS cache (
+        ns TEXT NOT NULL,
+        key TEXT NOT NULL,
+        json TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL,
+        ttl_ms INTEGER NOT NULL,
+        source TEXT,
+        PRIMARY KEY (ns, key)
+      ) WITHOUT ROWID;
+    `);
+    }
+    get(ns, key) {
+        const row = this.db
+            .prepare('SELECT json, fetched_at, ttl_ms, source FROM cache WHERE ns = ? AND key = ?')
+            .get(ns, key);
+        if (!row)
+            return undefined;
+        const ageMs = this.clock.now() - row.fetched_at;
+        return {
+            value: JSON.parse(row.json),
+            fetchedAt: row.fetched_at,
+            ttlMs: row.ttl_ms,
+            source: row.source,
+            ageMs,
+            stale: ageMs >= row.ttl_ms,
+        };
+    }
+    set(ns, key, value, opts) {
+        this.db
+            .prepare('INSERT OR REPLACE INTO cache (ns, key, json, fetched_at, ttl_ms, source) VALUES (?, ?, ?, ?, ?, ?)')
+            .run(ns, key, JSON.stringify(value), opts.fetchedAt ?? this.clock.now(), opts.ttlMs, opts.source ?? null);
+    }
+    delete(ns, key) {
+        this.db.prepare('DELETE FROM cache WHERE ns = ? AND key = ?').run(ns, key);
+    }
+    /** Drop entries older than ttl + `graceMs` (stale data is still useful for degraded mode). */
+    prune(graceMs = 86_400_000) {
+        const res = this.db.prepare('DELETE FROM cache WHERE fetched_at + ttl_ms + ? < ?').run(graceMs, this.clock.now());
+        return Number(res.changes);
+    }
+    count(ns) {
+        const row = (ns === undefined
+            ? this.db.prepare('SELECT COUNT(*) AS n FROM cache').get()
+            : this.db.prepare('SELECT COUNT(*) AS n FROM cache WHERE ns = ?').get(ns));
+        return Number(row.n);
+    }
+    /**
+     * Cached load with coalescing (identical concurrent loads share one promise)
+     * and stale-while-revalidate. On loader failure a stale value is served with
+     * `error` set; with nothing cached the error propagates.
+     */
+    async fetch(ns, key, loader, opts) {
+        const hit = this.get(ns, key);
+        if (hit && !hit.stale) {
+            return { value: hit.value, fetchedAt: hit.fetchedAt, source: hit.source, fromCache: true, stale: false };
+        }
+        if (hit && (opts.swr ?? true)) {
+            const refreshing = this.load(ns, key, loader, opts).then(() => undefined, () => undefined);
+            return { value: hit.value, fetchedAt: hit.fetchedAt, source: hit.source, fromCache: true, stale: true, refreshing };
+        }
+        try {
+            const value = await this.load(ns, key, loader, opts);
+            return { value, fetchedAt: this.clock.now(), source: opts.source ?? null, fromCache: false, stale: false };
+        }
+        catch (err) {
+            if (!hit)
+                throw err;
+            return { value: hit.value, fetchedAt: hit.fetchedAt, source: hit.source, fromCache: true, stale: true, error: err };
+        }
+    }
+    close() {
+        this.db.close();
+    }
+    load(ns, key, loader, opts) {
+        const id = `${ns}\u0000${key}`;
+        const existing = this.inflight.get(id);
+        if (existing)
+            return existing;
+        const p = (async () => {
+            try {
+                const value = await loader();
+                this.set(ns, key, value, { ttlMs: opts.ttlMs, source: opts.source });
+                return value;
+            }
+            finally {
+                this.inflight.delete(id);
+            }
+        })();
+        this.inflight.set(id, p);
+        return p;
+    }
+}

package/dist/packages/data/src/candles.js

@@ -0,0 +1,168 @@
+// Candle store (SPEC §3.4): GeckoTerminal OHLCV with closed-bar caching.
+//
+// Two cache rows per (pool, interval, token):
+//   candles:closed  bars whose period has ended. They do not change, so they are
+//                   kept for TTL.candlesClosed (1 h) and only re-verified by a full
+//                   fetch after that.
+//   candles:view    the last served series (closed + the open bar), TTL.candlesOpen
+//                   (30 s). Within that window a request costs nothing.
+// When the view expires, a refresh asks GeckoTerminal only for the bars missing
+// since the last closed bar plus the open one (usually limit=2), merges them into
+// the closed set and re-splits on the clock. Every request goes through the
+// HttpClient, so the geckoterminal bucket (10 rpm x 0.7) is never exceeded and
+// identical concurrent loads share one request.
+import { TTL } from "./cache.js";
+import { CANDLE_TIMEFRAMES, GT_MAX_LIMIT } from "./sources/geckoterminal.js";
+import { currentPriority, withPriority } from "./http.js";
+import { PriorityRef } from "./limiter.js";
+const NS_CLOSED = 'candles:closed';
+const NS_VIEW = 'candles:view';
+/** Closed bars kept per series (GeckoTerminal's max page). */
+export const MAX_KEPT_BARS = GT_MAX_LIMIT;
+/** Default bars per series: enough for the widest chart (SPEC §5.2 caps the AI tool at 300). */
+export const DEFAULT_CANDLE_LIMIT = 300;
+/**
+ * task-1314: the coarser timeframes derive exactly from a finer base, so two network fetches (1m, 1h)
+ * cover all six tabs and a timeframe switch paints instantly from local aggregation. Each target period
+ * is an integer multiple of its base and every dexterm period divides the epoch evenly (minute/hour/day
+ * all start at a UTC boundary = floor(t/period)*period), so the derived buckets line up with the bars
+ * GeckoTerminal would return natively. 1m and 1h are the base intervals (not derivable).
+ */
+export const CANDLE_BASE = {
+    '5m': '1m',
+    '15m': '1m',
+    '4h': '1h',
+    '1d': '1h',
+};
+/** Base intervals that must be fetched from the network; every other tab derives from one of these. */
+export const CANDLE_BASE_INTERVALS = ['1m', '1h'];
+/**
+ * Aggregate oldest-first base candles into a coarser interval by exact period multiple. Returns `[]`
+ * when `toPeriodMs` is not a positive integer multiple of `fromPeriodMs` (the caller then fetches
+ * natively). Buckets align to `floor(t/toPeriodMs)*toPeriodMs`; gaps (GeckoTerminal omits empty bars)
+ * stay gaps. open = first sub-bar's open, close = last sub-bar's close, high/low = extremes, v = sum.
+ */
+export function aggregateCandles(base, fromPeriodMs, toPeriodMs) {
+    if (fromPeriodMs <= 0 || toPeriodMs <= fromPeriodMs || toPeriodMs % fromPeriodMs !== 0)
+        return [];
+    if (base.length === 0)
+        return [];
+    const sorted = base.every((b, i) => i === 0 || b.t >= base[i - 1].t) ? base : [...base].sort((a, b) => a.t - b.t);
+    const buckets = new Map();
+    for (const b of sorted) {
+        const t = Math.floor(b.t / toPeriodMs) * toPeriodMs;
+        const cur = buckets.get(t);
+        if (!cur) {
+            buckets.set(t, { t, o: b.o, h: b.h, l: b.l, c: b.c, v: b.v });
+        }
+        else {
+            cur.h = Math.max(cur.h, b.h);
+            cur.l = Math.min(cur.l, b.l);
+            cur.c = b.c; // sorted oldest-first: the last write is the latest close
+            cur.v += b.v;
+        }
+    }
+    return [...buckets.values()].sort((a, b) => a.t - b.t);
+}
+export class CandleStore {
+    cache;
+    gecko;
+    clock;
+    inflight = new Map();
+    constructor(deps) {
+        this.cache = deps.cache;
+        this.gecko = deps.gecko;
+        this.clock = deps.clock;
+    }
+    async get(pool, interval, req = {}) {
+        const limit = Math.max(1, Math.min(MAX_KEPT_BARS, Math.floor(req.limit ?? DEFAULT_CANDLE_LIMIT)));
+        const key = `${pool}:${interval}:${req.token ?? ''}`;
+        const hit = this.cache.get(NS_VIEW, key);
+        const usable = hit && hit.value.limit >= limit ? hit : undefined;
+        const series = (v, fetchedAt, extra) => ({
+            pool,
+            interval,
+            candles: v.candles.slice(-limit),
+            openBarT: v.openBarT,
+            source: 'geckoterminal',
+            fetchedAt,
+            fromCache: false,
+            stale: false,
+            ...extra,
+        });
+        if (usable && !usable.stale)
+            return series(usable.value, usable.fetchedAt, { fromCache: true });
+        if (usable && (req.swr ?? true)) {
+            // The caller already has something to paint: the revalidation is background work (task-1323),
+            // so it never takes the bucket's foreground reserve away from a chart that is actually empty.
+            const refreshing = withPriority('low', () => this.load(key, pool, interval, limit, req.token)).then(() => undefined, () => undefined);
+            return series(usable.value, usable.fetchedAt, { fromCache: true, stale: true, refreshing });
+        }
+        try {
+            const v = await this.load(key, pool, interval, limit, req.token);
+            return series(v, this.clock.now(), {});
+        }
+        catch (err) {
+            if (!usable)
+                throw err;
+            return series(usable.value, usable.fetchedAt, { fromCache: true, stale: true, error: err });
+        }
+    }
+    /**
+     * Coalesced refresh: identical concurrent loads share one request. Each load runs under its own
+     * priority ref (task-1323); a more urgent caller joining a queued background load raises it, so a
+     * prefetch already waiting in the GeckoTerminal bucket cannot hold a foreground chart back.
+     */
+    load(key, pool, interval, limit, token) {
+        const caller = currentPriority();
+        const existing = this.inflight.get(key);
+        if (existing) {
+            if (caller)
+                existing.ref.raise(caller.level);
+            return existing.p;
+        }
+        const ref = new PriorityRef(caller?.level ?? 'normal');
+        const p = withPriority(ref, () => this.refresh(key, pool, interval, limit, token)).finally(() => this.inflight.delete(key));
+        this.inflight.set(key, { p, ref });
+        return p;
+    }
+    /** True when a usable series for (pool, interval, token) is cached (fresh or stale) at >= `limit` bars. */
+    has(pool, interval, req = {}) {
+        const limit = Math.max(1, Math.min(MAX_KEPT_BARS, Math.floor(req.limit ?? DEFAULT_CANDLE_LIMIT)));
+        const hit = this.cache.get(NS_VIEW, `${pool}:${interval}:${req.token ?? ''}`);
+        return !!hit && hit.value.limit >= limit && hit.value.candles.length > 0;
+    }
+    async refresh(key, pool, interval, limit, token) {
+        const { periodMs } = CANDLE_TIMEFRAMES[interval];
+        const closed = this.cache.get(NS_CLOSED, key);
+        const reuse = closed && !closed.stale && closed.value.length > 0 ? closed : undefined;
+        let fetchLimit = limit;
+        if (reuse) {
+            const last = reuse.value[reuse.value.length - 1].t;
+            // Bars that can have appeared since the last closed one, plus the open bar.
+            const missing = Math.ceil((this.clock.now() - last) / periodMs) + 1;
+            const have = reuse.value.length;
+            // Incremental only if the kept history already covers the requested depth.
+            if (have + missing >= limit || have >= MAX_KEPT_BARS)
+                fetchLimit = Math.min(limit, Math.max(2, missing));
+        }
+        const res = await this.gecko.ohlcv(pool, interval, { limit: fetchLimit, token });
+        const now = this.clock.now();
+        const merged = new Map();
+        if (reuse && fetchLimit < limit)
+            for (const b of reuse.value)
+                merged.set(b.t, b);
+        for (const b of res.candles)
+            merged.set(b.t, b);
+        const bars = [...merged.values()].sort((a, b) => a.t - b.t);
+        const closedBars = bars.filter((b) => b.t + periodMs <= now).slice(-MAX_KEPT_BARS);
+        const open = bars.find((b) => b.t + periodMs > now) ?? null;
+        // An incremental merge keeps the original fetchedAt, so closed bars are still
+        // fully re-verified once an hour (GeckoTerminal occasionally revises late trades).
+        const closedFetchedAt = reuse && fetchLimit < limit ? reuse.fetchedAt : now;
+        this.cache.set(NS_CLOSED, key, closedBars, { ttlMs: TTL.candlesClosed, source: 'geckoterminal', fetchedAt: closedFetchedAt });
+        const view = { candles: open ? [...closedBars, open] : closedBars, openBarT: open?.t ?? null, limit };
+        this.cache.set(NS_VIEW, key, view, { ttlMs: TTL.candlesOpen, source: 'geckoterminal' });
+        return view;
+    }
+}

package/dist/packages/data/src/clock.js

@@ -0,0 +1,64 @@
+// Injectable clock so the limiter, health registry and cache can be tested
+// deterministically with a fake clock (no real timers in tests).
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => {
+        if (signal?.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const t = setTimeout(done, Math.max(0, ms));
+            function done() { signal?.removeEventListener('abort', done); clearTimeout(t); resolve(); }
+            signal?.addEventListener('abort', done, { once: true });
+        });
+    },
+};
+/** Manual clock: time only moves when the test calls advance()/runUntil(). */
+export class FakeClock {
+    t;
+    seq = 0;
+    timers = [];
+    constructor(start = 1_700_000_000_000) {
+        this.t = start;
+    }
+    now() {
+        return this.t;
+    }
+    sleep(ms, signal) {
+        if (signal?.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = { at: this.t + Math.max(0, ms), seq: this.seq++, resolve };
+            this.timers.push(timer);
+            // Cancellation resolves the wait at once and drops the pending timer, matching systemClock.
+            signal?.addEventListener('abort', () => {
+                const i = this.timers.indexOf(timer);
+                if (i >= 0)
+                    this.timers.splice(i, 1);
+                resolve();
+            }, { once: true });
+        });
+    }
+    get pendingTimers() {
+        return this.timers.length;
+    }
+    /** Advance time by `ms`, firing due timers in order and letting their continuations run. */
+    async advance(ms) {
+        const target = this.t + ms;
+        for (;;) {
+            await flushMicrotasks();
+            this.timers.sort((a, b) => a.at - b.at || a.seq - b.seq);
+            const next = this.timers[0];
+            if (!next || next.at > target)
+                break;
+            this.timers.shift();
+            this.t = Math.max(this.t, next.at);
+            next.resolve();
+        }
+        this.t = target;
+        await flushMicrotasks();
+    }
+}
+/** Let every queued microtask (and their follow-ups) run before returning. */
+export function flushMicrotasks() {
+    return new Promise((resolve) => setImmediate(resolve));
+}