renor-engine 0.0.0-stage → 1.0.0

package/dist/digests/worker.js

@@ -0,0 +1,348 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DigestWorker = exports.DigestBudgetError = exports.DIGEST_MAX_FAILED_SWEEPS = exports.DIGEST_RETRY_MAX_MS = exports.DIGEST_RETRY_BASE_MS = exports.DIGEST_MIN_INTERVAL_MS = exports.DIGEST_DEBOUNCE_MS = void 0;
+exports.guardedDigestChat = guardedDigestChat;
+const node_fs_1 = __importDefault(require("node:fs"));
+const sessionRouter_1 = require("../router/sessionRouter");
+const digestCache_1 = require("./digestCache");
+const digests_1 = require("./digests");
+/**
+ * The production path of write-time digests (RENOR_DIGESTS, see digests.ts): a background worker that writes the
+ * digest of every note that has none, after a save, without ever being on the save's path.
+ *
+ *   - `notify()` (called after a save's index pass) only sets a timer and returns: a save never waits for a model.
+ *   - Saves are batched: the sweep runs DIGEST_DEBOUNCE_MS after the last save, and no sooner than
+ *     DIGEST_MIN_INTERVAL_MS after the previous sweep ended, so a burst of saves, or one note appended to all day, is
+ *     digested once per interval and not once per save. One sweep runs at a time.
+ *   - A sweep that left notes undigested because the provider failed is tried again after a wait that doubles from
+ *     DIGEST_RETRY_BASE_MS to DIGEST_RETRY_MAX_MS (with jitter), up to DIGEST_MAX_FAILED_SWEEPS in a row; then the
+ *     worker stops until the next start (a save tries once more) rather than calling a provider that keeps refusing.
+ *     The transport inside a call retries on its own too (createOllamaChat, RENOR_DIGEST_RETRIES).
+ *   - Cost guard, per workspace: every call is counted at the list price in the workspace's own digest cache
+ *     (`digest_spend`), a call that could take the UTC day past RENOR_DIGEST_MAX_USD_PER_DAY is not made (its worst case
+ *     is counted: the prompt plus the whole output allowance), and the worker is `paused-budget` until the day after the
+ *     one that refused the call (a sweep that ends past midnight does not move that). Notes without a digest wait; nothing
+ *     is lost and search reads the digests that exist. Only this worker is held to the guard: `renor index` and
+ *     `renor rebuild` are commands someone runs and are not capped (README, "Cost guard").
+ *   - A digest of text a note no longer holds (edited, forgotten, file gone) is removed at the start of every sweep. A note
+ *     is edited once the index has seen it (a save, an import, `renor index`): a file changed behind the index's back keeps
+ *     its digest, as search keeps its old chunks, until then.
+ *   - The only provider is the digest slot (RENOR_DIGEST_BASE_URL + RENOR_DIGEST_API_KEY). With it unset the worker is
+ *     `stopped` and nothing is sent: it never falls back to the evidence provider, which the privacy copy does not name.
+ *   - The sweep is held in the on-demand idle monitor while it runs, so a workspace does not exit in the middle of a call.
+ *     Waits for a retry are not held: the workspace may sleep, and its next start sweeps again.
+ *
+ * Nothing here runs unless RENOR_DIGESTS is on, and it is off by default.
+ */
+exports.DIGEST_DEBOUNCE_MS = 15_000;
+exports.DIGEST_MIN_INTERVAL_MS = 60_000;
+exports.DIGEST_RETRY_BASE_MS = 30_000;
+exports.DIGEST_RETRY_MAX_MS = 300_000;
+exports.DIGEST_MAX_FAILED_SWEEPS = 8;
+/** How many days of spend rows are kept. */
+const SPEND_DAYS_KEPT = 14;
+/** Raised, inside the model client, when a call would take the day past its budget. */
+class DigestBudgetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DigestBudgetError';
+    }
+}
+exports.DigestBudgetError = DigestBudgetError;
+const utcDay = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** Roughly three characters a token for the prompt: the worst case a guard must hold, not a measurement. */
+function promptTokensOf(request) {
+    return Math.ceil(request.messages.reduce((sum, m) => sum + m.content.length, 0) / 3);
+}
+/**
+ * The cost guard around the digest model client: refuses a call whose worst case would take the day past the budget, and
+ * records what each call cost. A call that threw is counted at its prompt alone (what is known to have been sent).
+ */
+function guardedDigestChat(args) {
+    const { chat, cache, options } = args;
+    const usd = (promptTokens, outputTokens) => (promptTokens * options.priceInPerM + outputTokens * options.priceOutPerM) / 1e6;
+    return async (request) => {
+        const day = args.day();
+        const promptEstimate = promptTokensOf(request);
+        const worst = usd(promptEstimate, request.max_tokens ?? 8_000);
+        if (cache.spentUsd(day) + worst > options.maxUsdPerDay) {
+            args.onBudget(day);
+            throw new DigestBudgetError(`the digest budget for ${day} (${options.maxUsdPerDay} USD) would be passed`);
+        }
+        let response;
+        try {
+            response = await chat(request);
+        }
+        catch (err) {
+            cache.addSpend(day, promptEstimate, 0, usd(promptEstimate, 0));
+            throw err;
+        }
+        const prompt = response.promptTokens ?? promptEstimate;
+        const output = (0, sessionRouter_1.billedOutputTokens)(response);
+        cache.addSpend(day, prompt, output, usd(prompt, output));
+        return response;
+    };
+}
+class DigestWorker {
+    deps;
+    now;
+    setTimer;
+    clearTimer;
+    random;
+    log;
+    state = 'idle';
+    reason;
+    timer = null;
+    timerAt = 0;
+    running = null;
+    dirty = false;
+    closed = false;
+    failures = 0;
+    lastEnd = 0;
+    budgetHit = false;
+    /** The UTC day whose budget refused a call in the sweep in flight: the pause is counted from it, not from when the sweep ends. */
+    budgetDay;
+    last;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => {
+            const handle = setTimeout(fn, ms);
+            handle.unref();
+            return handle;
+        });
+        this.clearTimer = deps.clearTimer ?? (handle => clearTimeout(handle));
+        this.random = deps.random ?? Math.random;
+        this.log = deps.log ?? (line => console.log(line));
+    }
+    /** Boot: digest what earlier saves, an import, or a workspace that slept left without a digest. */
+    start() {
+        this.failures = 0;
+        if (!this.runnable())
+            return;
+        this.schedule(exports.DIGEST_DEBOUNCE_MS);
+    }
+    /** After a save has been indexed. Never throws, never waits: it sets a timer. */
+    notify() {
+        if (this.closed || !this.runnable())
+            return;
+        if (this.running) {
+            this.dirty = true;
+            return;
+        }
+        // A retry already waiting keeps its (longer) wait: a save does not shorten a backoff. A stopped worker tries once.
+        if (this.state === 'retrying' || this.state === 'paused-budget')
+            return;
+        this.schedule(exports.DIGEST_DEBOUNCE_MS);
+    }
+    status() {
+        const cache = this.openCache();
+        let spent = 0;
+        try {
+            spent = cache?.spentUsd(utcDay(this.now())) ?? 0;
+        }
+        finally {
+            cache?.close();
+        }
+        return {
+            state: this.state,
+            ...(this.reason ? { reason: this.reason } : {}),
+            consecutiveFailures: this.failures,
+            spentTodayUsd: Math.round(spent * 1e6) / 1e6,
+            maxUsdPerDay: this.deps.options.maxUsdPerDay,
+            ...(this.last ? { lastSweep: this.last } : {}),
+        };
+    }
+    /** Resolves when the sweep in flight, if any, has ended (shutdown, tests). Waits for no timer. */
+    async whenSwept() {
+        while (this.running)
+            await this.running;
+    }
+    /** Run a sweep now (no debounce, no interval) and wait for it: boot-time catch-up, tests. */
+    async sweepNow() {
+        if (this.closed || !this.runnable())
+            return;
+        this.cancelTimer();
+        if (this.running)
+            await this.running;
+        this.launch();
+        await this.running;
+    }
+    /** Stop timers and wait for the sweep in flight; after this the worker does nothing. */
+    async close() {
+        this.closed = true;
+        this.cancelTimer();
+        if (this.running)
+            await this.running;
+    }
+    runnable() {
+        if (!this.deps.provider) {
+            this.stop('no embedding provider: digests are read by meaning, so they are not written');
+            return false;
+        }
+        if (!this.deps.options.chat) {
+            // The digest slot is the only provider digests use: another provider's key is never borrowed (see resolveDigestProvider).
+            this.stop('no digest model is configured: digests need RENOR_DIGEST_BASE_URL and RENOR_DIGEST_API_KEY, and never use the evidence or Ollama provider instead, so nothing is sent');
+            return false;
+        }
+        return true;
+    }
+    stop(reason) {
+        if (this.state === 'stopped' && this.reason === reason)
+            return;
+        this.state = 'stopped';
+        this.reason = reason;
+        this.log(`[digests] worker stopped: ${reason}`);
+    }
+    cancelTimer() {
+        if (this.timer !== null)
+            this.clearTimer(this.timer);
+        this.timer = null;
+    }
+    schedule(wait, state = 'scheduled') {
+        if (this.closed)
+            return;
+        const earliest = this.lastEnd + exports.DIGEST_MIN_INTERVAL_MS - this.now();
+        const delay = Math.max(wait, state === 'scheduled' ? earliest : 0);
+        const at = this.now() + delay;
+        // One timer: a nearer request replaces a later one, a later request leaves the nearer one alone.
+        if (this.timer !== null && this.timerAt <= at && this.state === state)
+            return;
+        this.cancelTimer();
+        this.state = state;
+        if (state === 'scheduled')
+            this.reason = undefined;
+        this.timerAt = at;
+        this.timer = this.setTimer(() => {
+            this.timer = null;
+            this.launch();
+        }, delay);
+    }
+    launch() {
+        if (this.closed || this.running)
+            return;
+        const track = this.deps.track ?? (work => work());
+        this.state = 'running';
+        const run = this.sweep().catch((err) => {
+            // A sweep that threw (the database closed under it, a disk error) is a failed sweep, said once and retried like any.
+            this.failures++;
+            this.reason = `sweep failed: ${String(err instanceof Error ? err.message : err).replace(/\s+/g, ' ').slice(0, 160)}`;
+            this.log(`[digests] ${this.reason}`);
+        }).then(() => this.afterSweep());
+        this.running = run.finally(() => { this.running = null; });
+        void track(() => this.running).catch(() => undefined);
+    }
+    afterSweep() {
+        this.lastEnd = this.now();
+        if (this.closed)
+            return;
+        if (this.budgetHit) {
+            this.budgetHit = false;
+            // The day that is spent is the one that refused the call, whenever the sweep ended: one that runs past UTC midnight
+            // after the refusal must not push the resume out a whole day further. A resume time already past waits one second.
+            const refusedOn = this.budgetDay ?? utcDay(this.now());
+            this.budgetDay = undefined;
+            const resume = Date.parse(`${refusedOn}T00:00:00Z`) + 86_400_000 + 60_000;
+            this.state = 'paused-budget';
+            this.reason = `the daily digest budget (${this.deps.options.maxUsdPerDay} USD) is spent; notes without a digest wait until the next UTC day`;
+            this.log(`[digests] ${this.reason}`);
+            this.dirty = false;
+            this.cancelTimer();
+            this.timerAt = resume;
+            this.timer = this.setTimer(() => {
+                this.timer = null;
+                this.state = 'idle';
+                this.schedule(0);
+            }, Math.max(1_000, resume - this.now()));
+            return;
+        }
+        if (this.failures > 0) {
+            if (this.failures >= exports.DIGEST_MAX_FAILED_SWEEPS) {
+                this.dirty = false;
+                this.stop(`the digest model failed ${this.failures} sweeps in a row (${this.reason ?? 'no detail'}); it is tried again at the next start or save`);
+                return;
+            }
+            const wait = Math.min(exports.DIGEST_RETRY_MAX_MS, exports.DIGEST_RETRY_BASE_MS * 2 ** (this.failures - 1)) * (0.8 + 0.4 * this.random());
+            this.dirty = false;
+            this.log(`[digests] ${this.reason ?? 'a sweep failed'}; trying again in ${Math.round(wait / 1000)} s`);
+            this.schedule(wait, 'retrying');
+            return;
+        }
+        this.state = 'idle';
+        this.reason = undefined;
+        if (this.dirty) {
+            this.dirty = false;
+            this.schedule(exports.DIGEST_DEBOUNCE_MS);
+        }
+    }
+    openCache() {
+        try {
+            return new digestCache_1.DigestCache(this.deps.options.cachePath);
+        }
+        catch (err) {
+            this.log(`[digests] the digest cache cannot be opened: ${String(err instanceof Error ? err.message : err).slice(0, 160)}`);
+            return null;
+        }
+    }
+    async sweep() {
+        const { db, config, options, provider } = this.deps;
+        const cache = this.openCache();
+        if (!cache)
+            throw new Error('the digest cache cannot be opened');
+        try {
+            const ledger = config.ledgerRelPath;
+            // What search can still reach: notes whose file exists, by the hash the INDEX holds. A digest of any other text is
+            // removed. A file edited behind the index's back keeps its index hash, so it keeps its digest, as search keeps its
+            // old chunks, until the index sees the change (a save, an import, `renor index`).
+            const live = (0, sessionRouter_1.listRouterNotes)(db, config.memoryDir, ledger).filter(note => node_fs_1.default.existsSync(note.file));
+            const pruned = cache.retainOnly(new Set(live.map(note => note.noteHash)));
+            cache.pruneSpend(SPEND_DAYS_KEPT);
+            this.budgetHit = false;
+            this.budgetDay = undefined;
+            const guarded = {
+                ...options,
+                chat: guardedDigestChat({
+                    chat: options.chat,
+                    cache,
+                    day: () => utcDay(this.now()),
+                    options,
+                    onBudget: (day) => { this.budgetHit = true; this.budgetDay = day; },
+                }),
+            };
+            const stats = await (0, digests_1.buildNoteDigests)({
+                db,
+                vaultPath: config.memoryDir,
+                ledgerRelPath: ledger,
+                options: guarded,
+                cache,
+                provider: provider,
+            });
+            if (stats.failed > 0 && !this.budgetHit) {
+                this.failures++;
+                this.reason = (stats.error ?? 'the digest model left notes without a digest').replace(/\s+/g, ' ').slice(0, 160);
+            }
+            else if (stats.failed === 0) {
+                this.failures = 0;
+                this.reason = undefined;
+            }
+            this.last = {
+                endedAt: new Date(this.now()).toISOString(),
+                digested: stats.digested,
+                failed: stats.failed,
+                gone: stats.gone,
+                calls: stats.calls,
+                pruned,
+            };
+            if (stats.digested > 0 || stats.failed > 0 || pruned > 0) {
+                this.log(`[digests] swept: ${stats.digested} digested, ${stats.failed} failed, ${stats.cached} already had one, ${pruned} removed, ${stats.calls} call(s)`);
+            }
+        }
+        finally {
+            cache.close();
+        }
+    }
+}
+exports.DigestWorker = DigestWorker;

package/dist/embeddings/caching.js

@@ -0,0 +1,337 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheOnlyVertex = exports.CountingEmbeddingProvider = exports.CachingEmbeddingProvider = void 0;
+exports.embeddingCallStats = embeddingCallStats;
+exports.resolveEmbeddingCachePath = resolveEmbeddingCachePath;
+exports.describeEmbeddingCache = describeEmbeddingCache;
+exports.invalidateEmbeddingCache = invalidateEmbeddingCache;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const IDENTITY_KIND = /^[\w.-]{1,32}$/;
+const IDENTITY_MODEL = /^[\w./:-]{1,80}$/;
+function resolveIdentity(inner, stated) {
+    const declared = inner.identity;
+    const identity = stated ?? declared;
+    if (!identity)
+        throw new Error('Embedding cache needs the identity of the provider and model: declare `identity` on the provider or pass options.identity');
+    if (!IDENTITY_KIND.test(identity.kind) || !IDENTITY_MODEL.test(identity.model))
+        throw new Error('Invalid embedding identity');
+    if (stated && declared && (stated.kind !== declared.kind || stated.model !== declared.model)) {
+        throw new Error(`Embedding cache identity ${stated.kind}/${stated.model} contradicts the wrapped provider, which declares ${declared.kind}/${declared.model}`);
+    }
+    return identity;
+}
+const TASK_QUERY = 'RETRIEVAL_QUERY';
+const TASK_DOCUMENT = 'RETRIEVAL_DOCUMENT';
+class CachingEmbeddingProvider {
+    dimensions;
+    identity;
+    /** Lookups: one hit or miss per input occurrence. What the provider received is `sent`. */
+    stats = { hits: 0, misses: 0 };
+    sent = { texts: 0, calls: 0 };
+    inner;
+    db;
+    namespace;
+    insert;
+    lookup;
+    oldest;
+    remove;
+    maxEntries;
+    maxBytes;
+    serving;
+    /** Rows and vector bytes held, kept in step with the file so a write does not scan it. */
+    entries = 0;
+    bytes = 0;
+    /** Serving mode only: set by the first cache fault, after which every call goes straight to the provider. */
+    disabled = false;
+    constructor(inner, options) {
+        if ('namespace' in options) {
+            throw new Error('CachingEmbeddingProvider no longer takes a namespace: the identity of the provider and model pins the cache (declare `identity` on the provider, or pass options.identity)');
+        }
+        this.inner = inner;
+        this.dimensions = inner.dimensions;
+        this.identity = resolveIdentity(inner, options.identity);
+        if (options.scope !== undefined && !/^[\w.-]{1,32}$/.test(options.scope))
+            throw new Error('Invalid cache scope');
+        this.namespace = `${this.identity.kind}/${this.identity.model}/${inner.dimensions}${options.scope ? `/${options.scope}` : ''}`;
+        if (!/^[\w./:-]{4,120}$/.test(this.namespace))
+            throw new Error('Invalid cache namespace');
+        for (const [name, limit] of [['maxEntries', options.maxEntries], ['maxBytes', options.maxBytes]]) {
+            if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+                throw new Error(`${name} must be a positive integer`);
+        }
+        this.maxEntries = options.maxEntries ?? Infinity;
+        this.maxBytes = options.maxBytes ?? Infinity;
+        this.serving = options.serving === true;
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(options.cachePath), { recursive: true });
+        this.db = new better_sqlite3_1.default(options.cachePath);
+        this.db.pragma('journal_mode = WAL');
+        // A serving read waits a moment for a lock, not ten seconds: past that the provider is the faster answer.
+        this.db.pragma(`busy_timeout = ${this.serving ? 100 : 10000}`);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS embeddings (
+         key TEXT PRIMARY KEY,
+         dims INTEGER NOT NULL,
+         vec BLOB NOT NULL,
+         namespace TEXT NOT NULL,
+         created_at TEXT NOT NULL
+       )`);
+        this.lookup = this.db.prepare('SELECT vec, dims FROM embeddings WHERE key = ? AND namespace = ?');
+        this.insert = this.db.prepare('INSERT OR IGNORE INTO embeddings (key, dims, vec, namespace, created_at) VALUES (?, ?, ?, ?, ?)');
+        // rowid is insertion order (nothing but the oldest row is ever deleted), so eviction is deterministic.
+        this.oldest = this.db.prepare('SELECT rowid AS id, LENGTH(vec) AS n FROM embeddings ORDER BY rowid LIMIT 32');
+        this.remove = this.db.prepare('DELETE FROM embeddings WHERE rowid = ?');
+        if (this.bounded) {
+            const held = this.db.prepare('SELECT COUNT(*) AS entries, COALESCE(SUM(LENGTH(vec)), 0) AS bytes FROM embeddings').get();
+            this.entries = held.entries;
+            this.bytes = held.bytes;
+            this.evict();
+        }
+    }
+    get bounded() {
+        return this.maxEntries !== Infinity || this.maxBytes !== Infinity;
+    }
+    evict() {
+        while (this.entries > this.maxEntries || this.bytes > this.maxBytes) {
+            const rows = this.oldest.all();
+            if (rows.length === 0) {
+                this.entries = 0;
+                this.bytes = 0;
+                return;
+            }
+            for (const row of rows) {
+                if (this.entries <= this.maxEntries && this.bytes <= this.maxBytes)
+                    return;
+                this.remove.run(row.id);
+                this.entries -= 1;
+                this.bytes -= row.n;
+            }
+        }
+    }
+    /** Serving mode: a cache fault ends the cache for this process and the call carries on without it. */
+    guard(work, fallback) {
+        if (!this.serving)
+            return work();
+        if (this.disabled)
+            return fallback;
+        try {
+            return work();
+        }
+        catch {
+            this.disabled = true;
+            try {
+                this.db.close();
+            }
+            catch { /* already unusable */ }
+            return fallback;
+        }
+    }
+    key(text, taskType) {
+        // A serving entry holds float64, a benchmark entry float32: they never share a key.
+        return node_crypto_1.default.createHash('sha256')
+            .update(`${this.namespace}\0${taskType}\0${this.dimensions}\0${text}${this.serving ? '\0f64' : ''}`)
+            .digest('hex');
+    }
+    read(text, taskType) {
+        const row = this.lookup.get(this.key(text, taskType), this.namespace);
+        if (!row)
+            return null;
+        if (row.dims !== this.dimensions)
+            return null; // impossible unless the store was corrupted
+        const width = this.serving ? 8 : 4;
+        if (row.vec.byteLength !== this.dimensions * width)
+            return null;
+        // Copied out first: a Buffer from the driver is not guaranteed to start on an aligned boundary.
+        const bytes = row.vec.buffer.slice(row.vec.byteOffset, row.vec.byteOffset + row.vec.byteLength);
+        return Array.from(this.serving ? new Float64Array(bytes) : new Float32Array(bytes));
+    }
+    write(text, taskType, vector) {
+        if (vector.length !== this.dimensions)
+            throw new Error('Cached vector has wrong dimensionality');
+        const buf = Buffer.from((this.serving ? new Float64Array(vector) : new Float32Array(vector)).buffer);
+        const { changes } = this.insert.run(this.key(text, taskType), this.dimensions, buf, this.namespace, new Date().toISOString());
+        if (changes > 0 && this.bounded) {
+            this.entries += 1;
+            this.bytes += buf.length;
+            this.evict();
+        }
+    }
+    async embed(texts, options) {
+        if (texts.length === 0)
+            return [];
+        if (this.serving)
+            return this.inner.embed(texts, options); // documents are not cached on the read path
+        const out = [];
+        const misses = new Map();
+        texts.forEach((text, index) => {
+            const cached = this.read(text, TASK_DOCUMENT);
+            if (cached) {
+                this.stats.hits += 1;
+                out[index] = cached;
+            }
+            else {
+                this.stats.misses += 1;
+                const indexes = misses.get(text);
+                if (indexes)
+                    indexes.push(index);
+                else
+                    misses.set(text, [index]);
+            }
+        });
+        if (misses.size > 0) {
+            const uniqueTexts = [...misses.keys()];
+            this.sent.calls += 1;
+            this.sent.texts += uniqueTexts.length;
+            const fresh = await this.inner.embed(uniqueTexts, options);
+            if (fresh.length !== uniqueTexts.length)
+                throw new Error('Inner provider returned wrong vector count');
+            uniqueTexts.forEach((text, i) => {
+                this.write(text, TASK_DOCUMENT, fresh[i]);
+                for (const index of misses.get(text))
+                    out[index] = fresh[i];
+            });
+        }
+        return out;
+    }
+    async embedQuery(text, options) {
+        const cached = this.guard(() => this.read(text, TASK_QUERY), null);
+        if (cached) {
+            this.stats.hits += 1;
+            return cached;
+        }
+        this.stats.misses += 1;
+        this.sent.calls += 1;
+        this.sent.texts += 1;
+        // Providers without a query task type (OpenAI-compatible, hash) are queried
+        // through embed(), exactly as retrieval/semantic.ts does when uncached.
+        const vector = this.inner.embedQuery
+            ? await this.inner.embedQuery(text, options)
+            : (await this.inner.embed([text], options))[0];
+        if (!this.serving)
+            this.write(text, TASK_QUERY, vector);
+        else
+            this.guard(() => this.write(text, TASK_QUERY, vector), undefined);
+        return vector;
+    }
+    get callStats() {
+        return { hits: this.stats.hits, misses: this.stats.misses, cached: true, sent: { ...this.sent } };
+    }
+    close() {
+        if (this.db.open)
+            this.db.close();
+    }
+    describe() {
+        const inner = this.inner.describe?.() ?? {};
+        return { ...inner, cache: { namespace: this.namespace, hits: this.stats.hits, misses: this.stats.misses } };
+    }
+}
+exports.CachingEmbeddingProvider = CachingEmbeddingProvider;
+/**
+ * Stands in for the cache when it is off, so the texts a run sends to its provider are
+ * still counted: an uncached run must not be reported as free.
+ */
+class CountingEmbeddingProvider {
+    dimensions;
+    identity;
+    sent = { texts: 0, calls: 0 };
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+        this.dimensions = inner.dimensions;
+        this.identity = inner.identity;
+    }
+    async embed(texts, options) {
+        // An empty batch is no provider call, exactly as in CachingEmbeddingProvider.embed: the counter and the real
+        // call boundary agree (every shipped provider already returns [] for it without a request).
+        if (texts.length === 0)
+            return [];
+        this.sent.calls += 1;
+        this.sent.texts += texts.length;
+        return this.inner.embed(texts, options);
+    }
+    async embedQuery(text, options) {
+        this.sent.calls += 1;
+        this.sent.texts += 1;
+        // Providers without a query task type are queried through embed(), exactly as retrieval/semantic.ts does.
+        return this.inner.embedQuery ? this.inner.embedQuery(text, options) : (await this.inner.embed([text], options))[0];
+    }
+    /** Nothing is looked up, so every text sent is a miss and none is a hit. */
+    get callStats() {
+        return { hits: 0, misses: this.sent.texts, cached: false, sent: { ...this.sent } };
+    }
+}
+exports.CountingEmbeddingProvider = CountingEmbeddingProvider;
+/** A run's embedding figures for the cache report: cache counters, or the count of texts sent when no cache stood in front. */
+function embeddingCallStats(provider) {
+    return provider instanceof CachingEmbeddingProvider || provider instanceof CountingEmbeddingProvider ? provider.callStats : undefined;
+}
+/** Resolve the cache setting from the environment. Returns null when disabled. */
+function resolveEmbeddingCachePath(env = process.env) {
+    const raw = env.RENOR_EVAL_EMBED_CACHE;
+    if (raw === 'off' || raw === '0')
+        return null;
+    if (!raw || raw === 'on') {
+        return node_path_1.default.join(process.env.HOME ?? '.', '.local', 'share', 'renor', 'embed-cache.db');
+    }
+    return node_path_1.default.resolve(raw);
+}
+/** Cached row count per namespace (a missing DB is an empty cache). */
+function describeEmbeddingCache(cachePath) {
+    if (!node_fs_1.default.existsSync(cachePath))
+        return [];
+    const db = new better_sqlite3_1.default(cachePath, { readonly: true });
+    try {
+        return db.prepare('SELECT namespace, COUNT(*) AS rows FROM embeddings GROUP BY namespace ORDER BY namespace').all();
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Invalidate cached vectors by namespace (kind/model/dims), or everything with
+ * an explicit `all`. An empty filter is refused so a typo never wipes a paid cache.
+ */
+function invalidateEmbeddingCache(cachePath, filter) {
+    if (!filter.namespace && !filter.all)
+        throw new Error('invalidateEmbeddingCache: pass a namespace or all: true');
+    if (!node_fs_1.default.existsSync(cachePath))
+        return 0;
+    const db = new better_sqlite3_1.default(cachePath);
+    try {
+        db.pragma('busy_timeout = 10000');
+        return filter.namespace
+            ? db.prepare('DELETE FROM embeddings WHERE namespace = ?').run(filter.namespace).changes
+            : db.prepare('DELETE FROM embeddings').run().changes;
+    }
+    finally {
+        db.close();
+    }
+}
+/** Read existing benchmark Vertex vectors without creating a cache or supplying an upstream. */
+class CacheOnlyVertex {
+    dimensions = 768;
+    identity = { kind: 'vertex', model: 'gemini-embedding-001' };
+    stats = { hits: 0, misses: 0, upstreamTexts: 0 };
+    db;
+    constructor(file) { this.db = new better_sqlite3_1.default(file, { readonly: true, fileMustExist: true }); }
+    read(text, task) {
+        const namespace = 'vertex/gemini-embedding-001/768';
+        const key = node_crypto_1.default.createHash('sha256').update(`${namespace}\0${task}\0${this.dimensions}\0${text}`).digest('hex');
+        const row = this.db.prepare('SELECT vec, dims FROM embeddings WHERE key = ? AND namespace = ?').get(key, namespace);
+        if (!row || row.dims !== 768 || row.vec.length !== 768 * 4) {
+            this.stats.misses++;
+            throw new Error(`cache-only Vertex miss: task=${task} textSHA256=${node_crypto_1.default.createHash('sha256').update(text).digest('hex')}`);
+        }
+        this.stats.hits++;
+        const bytes = row.vec.buffer.slice(row.vec.byteOffset, row.vec.byteOffset + row.vec.byteLength);
+        return Array.from(new Float32Array(bytes));
+    }
+    async embed(texts) { return texts.map(text => this.read(text, 'RETRIEVAL_DOCUMENT')); }
+    async embedQuery(text) { return this.read(text, 'RETRIEVAL_QUERY'); }
+    close() { this.db.close(); }
+}
+exports.CacheOnlyVertex = CacheOnlyVertex;