renor-engine 0.0.0-stage → 1.0.0

package/dist/digests/digests.js

@@ -0,0 +1,597 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEADING_SUMMARY_REASONS = exports.DIGEST_PRICE_OUT_DEFAULT = exports.DIGEST_PRICE_IN_DEFAULT = exports.DIGEST_MAX_USD_PER_DAY_DEFAULT = exports.DIGEST_HIT_PATH = exports.DIGEST_MAX_WINDOW_NOTES = exports.DIGEST_DEFAULT_TOKENS = exports.DIGEST_RETRIES_DEFAULT = exports.DIGEST_TIMEOUT_MS = exports.DIGEST_MAX_OUTPUT_TOKENS = exports.DIGEST_NOTE_MAX_CHARS = exports.DIGEST_ASSISTANT_TURN_MAX_CHARS = exports.DIGEST_USER_TURN_MAX_CHARS = exports.DIGEST_BATCH_MAX_CHARS = exports.DIGEST_BATCH_MAX_NOTES = exports.DIGEST_INPUT_VERSION = exports.DIGEST_PROMPT_TEMPLATE = void 0;
+exports.digestsEnabled = digestsEnabled;
+exports.resolveDigestProvider = resolveDigestProvider;
+exports.resolveDigestOptions = resolveDigestOptions;
+exports.digestInputOf = digestInputOf;
+exports.renderDigestPrompt = renderDigestPrompt;
+exports.parseDigestReply = parseDigestReply;
+exports.digestItemText = digestItemText;
+exports.buildNoteDigests = buildNoteDigests;
+exports.digestIndexedNotes = digestIndexedNotes;
+exports.digestTable = digestTable;
+exports.digestItemsToHit = digestItemsToHit;
+exports.attachDigest = attachDigest;
+exports.leadingSummaryHits = leadingSummaryHits;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const o200k_1 = require("../indexer/o200k");
+const parser_1 = require("../indexer/parser");
+const dailyEntries_1 = require("../indexer/dailyEntries");
+const ollamaChat_1 = require("../evidence/ollamaChat");
+const keyPool_1 = require("../evidence/keyPool");
+const secondPass_1 = require("../evidence/secondPass");
+const attach_1 = require("../evidence/attach");
+const space_1 = require("../embeddings/space");
+const sessionRouter_1 = require("../router/sessionRouter");
+const orchestrator_1 = require("../retrieval/orchestrator");
+const digestCache_1 = require("./digestCache");
+/**
+ * Write-time digests (RENOR_DIGESTS, default OFF): one model call when a note is indexed writes a query-independent
+ * list of what the user states in it, with its date and where it was said; search reads that list with no model call.
+ *
+ *   index (write time)  `renor index` / `renor rebuild` with the flag on: one model call per batch of up to
+ *                       DIGEST_BATCH_MAX_NOTES notes writes the digest of each note into the digest cache, keyed by
+ *                       the note's file hash, so an unchanged note is never paid for twice. Each item is then embedded
+ *                       once with the tenant's embedding provider and the vectors are stored beside it.
+ *   search (read time)  no model call. The digests of the notes the retrieval window already holds are scored by
+ *                       cosine to the query embedding, the best fit DIGEST_DEFAULT_TOKENS tokens, ordered by date,
+ *                       and prepended as one hit rendered like the evidence table.
+ *
+ * Retrieval, ranking and stored chunk text are never changed. Flag off: nothing here runs, no cache file is created,
+ * and `search --json` carries no `digest` field.
+ *
+ * Provenance: every item keeps the turn or section it was said in (`source`), and the search report lists, per
+ * rendered item, the note and that source. The statement itself stays in the note.
+ *
+ * The digest reads the user's own turns in full and clips the assistant's turns, since the list is of what the user
+ * states; a note with no turn structure is read whole (capped). Notes with nothing to say get an empty digest.
+ */
+exports.DIGEST_PROMPT_TEMPLATE = `You write a digest of a person's past conversations for their long-term memory. Below are {n} conversations between the person ("User") and an AI assistant. Each starts with an id and a date; turns are labelled [Turn N User] or [Turn N Assistant] (assistant turns may be shortened).
+
+TASK: For EACH conversation list EVERY distinct item, event, amount, preference or change of state that the User states about their own life or situation. Rules:
+- One entry per distinct item (e.g., each product, each trip, each device, each course, each amount, each plan, each preference).
+- "item" = what it is, specific enough to be understood without the conversation.
+- "action" = what happened or holds (bought / visited / completed / raised / inherited / prefers / plans / changed to / ...).
+- "amount" = numeric value + unit when stated (e.g., "3 days", "$120", "100 points"); else "".
+- "date" = the date the item happened or applies when the User gives one (resolve "yesterday", "last week" against the conversation's date); else the conversation's date.
+- "turn" = the label of the turn where the User stated it, e.g. "Turn 3".
+- Do NOT compute any totals. Do NOT merge different items. Include every candidate even if uncertain.
+- Skip general knowledge and advice given by the assistant. If the User states nothing about their own life or situation, return an empty list for that conversation.
+
+{conversations}
+
+Respond with ONLY minified JSON, no markdown, one entry per conversation using the ids given:
+{{"notes":[{{"id":"<id>","items":[{{"item":"...","action":"...","amount":"...","date":"...","turn":"..."}}]}}]}}`;
+/** Part of every digest's cache key: change how a note is shown to the model and every note is digested again. */
+exports.DIGEST_INPUT_VERSION = 'user-turns-v1';
+/** A digest call carries at most this many notes or characters of them. */
+exports.DIGEST_BATCH_MAX_NOTES = 6;
+exports.DIGEST_BATCH_MAX_CHARS = 40_000;
+/** The user's turn is shown up to this many characters, the assistant's turn up to the second number. */
+exports.DIGEST_USER_TURN_MAX_CHARS = 4_000;
+exports.DIGEST_ASSISTANT_TURN_MAX_CHARS = 300;
+/** A note is shown at most this long (its head, then its tail, when longer). */
+exports.DIGEST_NOTE_MAX_CHARS = 20_000;
+exports.DIGEST_MAX_OUTPUT_TOKENS = 8_000;
+exports.DIGEST_TIMEOUT_MS = 180_000;
+exports.DIGEST_RETRIES_DEFAULT = 3;
+const DIGEST_ATTEMPTS = 2;
+const DIGEST_MAX_ITEMS_PER_NOTE = 40;
+/** What the rendered table may weigh at search time, in gpt-tokenizer tokens (table header and footer included). */
+exports.DIGEST_DEFAULT_TOKENS = 600;
+/** At most this many of the retrieval window's notes are read, like the evidence pass's 20 sessions. */
+exports.DIGEST_MAX_WINDOW_NOTES = 20;
+exports.DIGEST_HIT_PATH = '_renor/digest';
+function digestsEnabled(env = process.env) {
+    const raw = (env.RENOR_DIGESTS ?? '').trim().toLowerCase();
+    if (raw === '' || raw === '0' || raw === 'off' || raw === 'false' || raw === 'no')
+        return false;
+    if (raw === '1' || raw === 'on' || raw === 'true' || raw === 'yes')
+        return true;
+    // A typo must not quietly measure the control arm twice.
+    throw new Error(`Invalid RENOR_DIGESTS "${raw}": must be on | off`);
+}
+exports.DIGEST_MAX_USD_PER_DAY_DEFAULT = 0.5;
+exports.DIGEST_PRICE_IN_DEFAULT = 0.225;
+exports.DIGEST_PRICE_OUT_DEFAULT = 0.75;
+function positiveNumber(raw, fallback, name) {
+    const text = (raw ?? '').trim();
+    if (text === '')
+        return fallback;
+    const value = Number(text);
+    // A typo must not quietly lift or remove a cost guard.
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`Invalid ${name} "${text}": must be a positive number`);
+    return value;
+}
+function boundedInt(raw, fallback, min, max) {
+    const value = Number((raw ?? '').trim());
+    if ((raw ?? '').trim() === '' || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/**
+ * The digest model's provider: the digest slot (RENOR_DIGEST_BASE_URL + RENOR_DIGEST_API_KEY(S)) and nothing else.
+ *
+ * A digest call sends the text of notes (clipped, see DIGEST_NOTE_MAX_CHARS), and the Privacy Policy, the LGPD page and
+ * the register of processing (ROPA P13) name one processor for it. So this never borrows the evidence provider's key or
+ * URL, the session router's, or an Ollama Cloud key, and the transport's default URL (Ollama Cloud) is never reached:
+ * with the slot unset no client is built and nothing is sent. Pointing the slot at a provider those pages do not name
+ * means updating them first.
+ */
+function resolveDigestProvider(env = process.env) {
+    const keys = [...(0, keyPool_1.splitKeyList)(env.RENOR_DIGEST_API_KEYS), ...(0, keyPool_1.splitKeyList)(env.RENOR_DIGEST_API_KEY)];
+    return { baseUrl: env.RENOR_DIGEST_BASE_URL?.trim() || undefined, keys };
+}
+/** Env -> options, or null when the flag is off. */
+function resolveDigestOptions(config, env = process.env) {
+    if (!digestsEnabled(env))
+        return null;
+    const effortRaw = (env.RENOR_DIGEST_REASONING_EFFORT ?? 'low').trim().toLowerCase();
+    if (!secondPass_1.EVIDENCE_REASONING_EFFORTS.includes(effortRaw)) {
+        throw new Error(`Invalid RENOR_DIGEST_REASONING_EFFORT "${effortRaw}": must be ${secondPass_1.EVIDENCE_REASONING_EFFORTS.join(' | ')}`);
+    }
+    const cacheOnlyRaw = (env.RENOR_DIGEST_CACHE_ONLY ?? '').trim().toLowerCase();
+    const cacheOnly = cacheOnlyRaw === '1' || cacheOnlyRaw === 'on' || cacheOnlyRaw === 'true' || cacheOnlyRaw === 'yes';
+    const retries = boundedInt(env.RENOR_DIGEST_RETRIES, exports.DIGEST_RETRIES_DEFAULT, 0, 8);
+    const { baseUrl, keys } = resolveDigestProvider(env);
+    return {
+        model: env.RENOR_DIGEST_MODEL?.trim() || env.RENOR_EVIDENCE_MODEL?.trim() || secondPass_1.EVIDENCE_MODEL_DEFAULT,
+        effort: effortRaw,
+        cachePath: env.RENOR_DIGEST_CACHE?.trim() || node_path_1.default.join(node_path_1.default.dirname(config.dbPath), 'digest-cache.db'),
+        cacheOnly,
+        tokens: boundedInt(env.RENOR_DIGEST_TOKENS, exports.DIGEST_DEFAULT_TOKENS, 100, 4_000),
+        retries,
+        maxUsdPerDay: positiveNumber(env.RENOR_DIGEST_MAX_USD_PER_DAY, exports.DIGEST_MAX_USD_PER_DAY_DEFAULT, 'RENOR_DIGEST_MAX_USD_PER_DAY'),
+        priceInPerM: positiveNumber(env.RENOR_DIGEST_PRICE_IN_PER_M, exports.DIGEST_PRICE_IN_DEFAULT, 'RENOR_DIGEST_PRICE_IN_PER_M'),
+        priceOutPerM: positiveNumber(env.RENOR_DIGEST_PRICE_OUT_PER_M, exports.DIGEST_PRICE_OUT_DEFAULT, 'RENOR_DIGEST_PRICE_OUT_PER_M'),
+        // A client needs the slot's key AND its URL: a key alone would send notes to the transport's default endpoint.
+        ...(keys.length > 0 && baseUrl && !cacheOnly ? { chat: (0, ollamaChat_1.createOllamaChat)({ baseUrl, keys, timeoutMs: exports.DIGEST_TIMEOUT_MS, maxRetries: retries }) } : {}),
+    };
+}
+// ─── What the model is shown ───
+const TURN_HEADING = /^### Turn (\d+) — ([^\n]*?)[ \t]*$/gm;
+/**
+ * The text a note is digested from. A note made of `### Turn N — Role` sections shows the user's turns whole (up to a
+ * cap) and the assistant's turns clipped; any other note is shown whole, or its head and tail when long.
+ */
+function digestInputOf(body) {
+    const matches = [...body.matchAll(TURN_HEADING)];
+    if (matches.length === 0)
+        return clipLong(body);
+    const parts = [];
+    matches.forEach((match, index) => {
+        const start = (match.index ?? 0) + match[0].length;
+        const end = index + 1 < matches.length ? (matches[index + 1].index ?? body.length) : body.length;
+        const text = body.slice(start, end).trim();
+        const role = match[2].trim();
+        const assistant = /^assistant$/i.test(role);
+        const cap = assistant ? exports.DIGEST_ASSISTANT_TURN_MAX_CHARS : exports.DIGEST_USER_TURN_MAX_CHARS;
+        const shown = text.length > cap ? `${text.slice(0, cap)} …` : text;
+        parts.push(`[Turn ${match[1]} ${role}]\n${shown}`);
+    });
+    return clipLong(parts.join('\n\n'));
+}
+function clipLong(text) {
+    if (text.length <= exports.DIGEST_NOTE_MAX_CHARS)
+        return text;
+    return `${text.slice(0, 14_000)}\n\n[... middle omitted ...]\n\n${text.slice(-6_000)}`;
+}
+function renderDigestPrompt(batch) {
+    const conversations = batch.map(item => `=== CONVERSATION id=${item.id} date=${item.date} ===\n${item.text}`).join('\n\n');
+    return exports.DIGEST_PROMPT_TEMPLATE.replace('{n}', () => String(batch.length)).replace('{conversations}', () => conversations);
+}
+const batchId = (id) => id.trim().toLowerCase().replace(/^c0*(\d+)$/, 'c$1');
+const clean = (value, max) => (typeof value === 'string' ? value : typeof value === 'number' ? String(value) : '').replace(/\s+/g, ' ').trim().slice(0, max);
+/**
+ * `{"notes":[{id, items:[{item, action, amount, date, turn}]}]}` -> id (normalised) -> items. An entry whose items
+ * list is missing is dropped (the note is asked again); an empty list is a real answer. An item without text is dropped.
+ */
+function parseDigestReply(text) {
+    const out = new Map();
+    const trimmed = text.trim().replace(/^```(?:json)?\s*|\s*```$/g, '');
+    let payload;
+    try {
+        payload = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/\{[\s\S]*\}/);
+        if (!match)
+            return out;
+        try {
+            payload = JSON.parse(match[0]);
+        }
+        catch {
+            return out;
+        }
+    }
+    const notes = payload && typeof payload === 'object' ? payload.notes : undefined;
+    if (!Array.isArray(notes))
+        return out;
+    for (const note of notes) {
+        if (!note || typeof note !== 'object' || Array.isArray(note))
+            continue;
+        const record = note;
+        const id = batchId(String(record.id ?? ''));
+        if (!id || !Array.isArray(record.items))
+            continue;
+        const items = [];
+        for (const raw of record.items) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                continue;
+            const r = raw;
+            const item = clean(r.item, 200);
+            if (!item)
+                continue;
+            items.push({
+                item,
+                action: clean(r.action, 60),
+                amount: clean(r.amount, 60),
+                date: clean(r.date, 40),
+                source: clean(r.turn ?? r.source, 30),
+            });
+            if (items.length >= DIGEST_MAX_ITEMS_PER_NOTE)
+                break;
+        }
+        out.set(id, items);
+    }
+    return out;
+}
+function batchesOf(items) {
+    const batches = [];
+    let current = [];
+    let chars = 0;
+    for (const item of items) {
+        if (current.length > 0 && (chars + item.text.length > exports.DIGEST_BATCH_MAX_CHARS || current.length >= exports.DIGEST_BATCH_MAX_NOTES)) {
+            batches.push(current);
+            current = [];
+            chars = 0;
+        }
+        current.push(item);
+        chars += item.text.length;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/** The text one item is embedded as: the row a reader would see, without the date. */
+function digestItemText(item) {
+    return [item.item, item.action, item.amount].filter(Boolean).join(' | ');
+}
+/**
+ * Give every note a digest, calling the model only for notes the cache does not hold, then give every digest the
+ * vectors of its items in the provider's embedding space. Batches run one after another.
+ */
+async function buildNoteDigests(args) {
+    const started = Date.now();
+    const { options, cache } = args;
+    const model = options.model;
+    const space = (0, space_1.embeddingSpace)(args.provider);
+    const all = (0, sessionRouter_1.listRouterNotes)(args.db, args.vaultPath, args.ledgerRelPath);
+    const notes = args.onlyPaths ? all.filter(note => args.onlyPaths.has(note.path)) : all;
+    const stats = {
+        model, notes: notes.length, cached: 0, digested: 0, skippedUncached: 0, failed: 0, gone: 0, calls: 0,
+        promptTokens: 0, completionTokens: 0, items: 0, embeddedTexts: 0, ms: 0,
+    };
+    const keyOf = (noteHash) => digestCache_1.DigestCache.digestKey(model, options.effort, exports.DIGEST_PROMPT_TEMPLATE, exports.DIGEST_INPUT_VERSION, noteHash);
+    const pending = [];
+    for (const note of notes) {
+        const key = keyOf(note.noteHash);
+        if (cache.getDigest(key)) {
+            stats.cached++;
+            continue;
+        }
+        if (options.cacheOnly) {
+            stats.skippedUncached++;
+            continue;
+        }
+        let raw;
+        try {
+            raw = await promises_1.default.readFile(note.file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                stats.gone++;
+                continue;
+            }
+            stats.failed++;
+            stats.error ??= `unreadable note: ${err instanceof Error ? err.message : String(err)}`.slice(0, 200);
+            continue;
+        }
+        if ((0, dailyEntries_1.noteContentHash)(note.file, raw) !== note.noteHash) {
+            // Edited after it was indexed: its digest must describe what search will find, so it waits for the next index.
+            stats.failed++;
+            stats.error ??= 'a note changed after it was indexed; index again';
+            continue;
+        }
+        const parsed = (0, parser_1.parseNote)(note.file, raw);
+        if (!parsed.body.trim()) {
+            cache.putDigest(key, note.noteHash, { items: [], model });
+            stats.digested++;
+            continue;
+        }
+        pending.push({ key, noteHash: note.noteHash, date: note.date ?? '', text: digestInputOf(parsed.body) });
+    }
+    if (pending.length > 0 && !options.chat) {
+        stats.failed += pending.length;
+        stats.error ??= 'no digest model configured';
+    }
+    else {
+        await digestPending(pending, options, cache, stats);
+    }
+    await embedDigests(notes, keyOf, cache, args.provider, space, stats);
+    stats.ms = Date.now() - started;
+    return stats;
+}
+async function digestPending(pending, options, cache, stats) {
+    const batches = batchesOf(pending);
+    for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+        const items = batches[batchIndex].map((entry, index) => ({ ...entry, id: `c${String(index + 1).padStart(2, '0')}` }));
+        let prompt = renderDigestPrompt(items);
+        const left = new Map(items.map(item => [batchId(item.id), item]));
+        let transportFailed = false;
+        for (let attempt = 0; attempt < DIGEST_ATTEMPTS && left.size > 0; attempt++) {
+            let content;
+            try {
+                const res = await options.chat({
+                    model: options.model,
+                    messages: [{ role: 'user', content: prompt }],
+                    temperature: 0,
+                    response_format: { type: 'json_object' },
+                    max_tokens: exports.DIGEST_MAX_OUTPUT_TOKENS,
+                    reasoning_effort: options.effort,
+                });
+                stats.calls++;
+                stats.promptTokens += res.promptTokens ?? 0;
+                stats.completionTokens += (0, sessionRouter_1.billedOutputTokens)(res);
+                content = res.content;
+            }
+            catch (err) {
+                stats.calls++;
+                stats.error ??= `digest call failed: ${err instanceof Error ? err.message : String(err)}`.slice(0, 200);
+                transportFailed = true;
+                break;
+            }
+            const parsed = parseDigestReply(content);
+            for (const [id, item] of [...left]) {
+                const found = parsed.get(id);
+                if (!found)
+                    continue;
+                const dated = found.map(it => (it.date ? it : { ...it, date: item.date }));
+                cache.putDigest(item.key, item.noteHash, { items: dated, model: options.model });
+                stats.digested++;
+                left.delete(id);
+            }
+            // A different request, so a provider-side cache cannot replay the incomplete answer.
+            prompt += '\n';
+        }
+        if (left.size > 0) {
+            stats.failed += left.size;
+            stats.error ??= 'the digest model left some notes without a digest';
+        }
+        if (transportFailed) {
+            // The transport already retried: a provider that is down or out of quota fails the next batch the same way.
+            for (const rest of batches.slice(batchIndex + 1))
+                stats.failed += rest.length;
+            break;
+        }
+    }
+}
+const EMBED_BATCH = 64;
+async function embedDigests(notes, keyOf, cache, provider, space, stats) {
+    if (space === null)
+        return;
+    const waiting = [];
+    for (const note of notes) {
+        const key = keyOf(note.noteHash);
+        const digest = cache.getDigest(key);
+        if (!digest || digest.items.length === 0)
+            continue;
+        stats.items += digest.items.length;
+        if (cache.getVectors(key, space, digest.items.length))
+            continue;
+        waiting.push({ key, texts: digest.items.map(digestItemText) });
+    }
+    for (let i = 0; i < waiting.length; i += EMBED_BATCH) {
+        const group = waiting.slice(i, i + EMBED_BATCH);
+        const texts = group.flatMap(entry => entry.texts);
+        let vectors;
+        try {
+            vectors = await provider.embed(texts);
+        }
+        catch (err) {
+            stats.failed += group.length;
+            stats.error ??= `digest embedding failed: ${err instanceof Error ? err.message : String(err)}`.slice(0, 200);
+            return;
+        }
+        stats.embeddedTexts += texts.length;
+        let at = 0;
+        for (const entry of group) {
+            cache.putVectors(entry.key, space, vectors.slice(at, at + entry.texts.length));
+            at += entry.texts.length;
+        }
+    }
+}
+/**
+ * `renor index` / `renor rebuild`: build the digests. The caller opens and closes nothing. Not under the daily cost guard
+ * (the background worker's, worker.ts): this is a command an operator runs, and the `[digests]` line it prints says what
+ * it spent. It must not be run from an unattended job with RENOR_DIGESTS on.
+ */
+async function digestIndexedNotes(args) {
+    const cache = new digestCache_1.DigestCache(args.options.cachePath);
+    try {
+        return await buildNoteDigests({
+            db: args.db,
+            vaultPath: args.config.vaultPath,
+            ledgerRelPath: args.config.memoryLedger,
+            options: args.options,
+            cache,
+            provider: args.provider,
+            onlyPaths: args.onlyPaths,
+        });
+    }
+    finally {
+        cache.close();
+    }
+}
+function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    return na === 0 || nb === 0 ? 0 : dot / Math.sqrt(na * nb);
+}
+function rowTokens(item) {
+    const action = item.action?.trim() ? ` | ${item.action.trim()}` : '';
+    const amount = item.amount?.trim() ? ` | ${item.amount.trim()}` : '';
+    const date = item.date?.trim() ? ` | ${item.date.trim()}` : '';
+    return (0, o200k_1.countO200kStrict)(`- ${item.item}${action}${amount}${date}\n`);
+}
+/**
+ * The table of digest items for one search, and nothing else: the digests of the window's notes (first
+ * DIGEST_MAX_WINDOW_NOTES distinct notes of `hits`, never the ledger or a synthetic hit), the best-fitting items by
+ * cosine to the query, as many as fit `options.tokens`, ordered oldest first. Reads the cache and the query
+ * embedding only.
+ */
+async function digestTable(args) {
+    const report = {
+        status: 'skipped', windowNotes: 0, notesWithDigest: 0, itemsConsidered: 0, itemsRendered: 0, tokens: 0, text: '', items: [],
+    };
+    const paths = [];
+    for (const hit of args.hits) {
+        if (!hit.notePath || hit.notePath.startsWith('_renor/') || paths.includes(hit.notePath))
+            continue;
+        if (args.isLedgerNote?.(hit.notePath))
+            continue;
+        paths.push(hit.notePath);
+        if (paths.length >= exports.DIGEST_MAX_WINDOW_NOTES)
+            break;
+    }
+    report.windowNotes = paths.length;
+    if (paths.length === 0)
+        return { items: [], report: { ...report, reason: 'no-notes' } };
+    const space = (0, space_1.embeddingSpace)(args.provider);
+    if (space === null)
+        return { items: [], report: { ...report, reason: 'no-embedding-space' } };
+    let cache;
+    try {
+        cache = new digestCache_1.DigestCache(args.options.cachePath, { readonly: true });
+    }
+    catch (err) {
+        // No cache file: nothing was ever digested here, which is the same as no digests.
+        return { items: [], report: { ...report, reason: 'no-digests', error: `digest cache unavailable: ${err instanceof Error ? err.message : String(err)}`.slice(0, 200) } };
+    }
+    try {
+        const noteRow = args.db.prepare('SELECT note_hash, frontmatter_json, modified_at FROM notes WHERE path = ?');
+        const candidates = [];
+        let missingVectors = 0;
+        paths.forEach((notePath, order) => {
+            const row = noteRow.get(notePath);
+            if (!row || !row.note_hash)
+                return;
+            const key = digestCache_1.DigestCache.digestKey(args.options.model, args.options.effort, exports.DIGEST_PROMPT_TEMPLATE, exports.DIGEST_INPUT_VERSION, row.note_hash);
+            const digest = cache.getDigest(key);
+            if (!digest)
+                return;
+            report.notesWithDigest++;
+            if (digest.items.length === 0)
+                return;
+            const vectors = cache.getVectors(key, space, digest.items.length);
+            if (!vectors) {
+                missingVectors++;
+                return;
+            }
+            const noteDate = (0, orchestrator_1.resolveSessionDate)(row.frontmatter_json, row.modified_at);
+            digest.items.forEach((item, index) => {
+                // A date the model wrote in words ("last Tuesday") does not order; the note's own date does.
+                const own = (0, orchestrator_1.sessionDateMs)(item.date);
+                const dateMs = own === Number.NEGATIVE_INFINITY ? (0, orchestrator_1.sessionDateMs)(noteDate) : own;
+                candidates.push({ notePath, order, index, item, vector: vectors[index], dateMs });
+            });
+        });
+        report.itemsConsidered = candidates.length;
+        if (candidates.length === 0) {
+            return { items: [], report: { ...report, reason: report.notesWithDigest === 0 ? 'no-digests' : missingVectors > 0 ? 'no-vectors' : 'no-digests' } };
+        }
+        const queryVector = args.queryVector
+            ?? (args.provider.embedQuery
+                ? await args.provider.embedQuery(args.query)
+                : (await args.provider.embed([args.query]))[0]);
+        const ranked = candidates
+            .map(candidate => ({ candidate, score: cosine(queryVector, candidate.vector) }))
+            .sort((a, b) => b.score - a.score || a.candidate.order - b.candidate.order || a.candidate.index - b.candidate.index);
+        const frame = (0, o200k_1.countO200kStrict)((0, attach_1.renderEvidenceTable)([]));
+        let used = frame;
+        const chosen = [];
+        for (const { candidate } of ranked) {
+            const cost = rowTokens(candidate.item);
+            if (used + cost > args.options.tokens)
+                break;
+            used += cost;
+            chosen.push(candidate);
+        }
+        chosen.sort((a, b) => (a.dateMs === b.dateMs ? 0 : a.dateMs < b.dateMs ? -1 : 1) || a.order - b.order || a.index - b.index);
+        const items = chosen.map(c => ({ item: c.item.item, action: c.item.action, amount: c.item.amount, date: c.item.date }));
+        report.status = items.length > 0 ? 'ok' : 'skipped';
+        report.itemsRendered = items.length;
+        report.text = items.length > 0 ? (0, attach_1.renderEvidenceTable)(items) : '';
+        report.tokens = items.length > 0 ? (0, o200k_1.countO200kStrict)(report.text) : 0;
+        report.items = chosen.map(c => ({ notePath: c.notePath, source: c.item.source, item: c.item.item }));
+        return { items, report };
+    }
+    finally {
+        cache.close();
+    }
+}
+/** The digest as one hit, rendered like the evidence table (the same rows the reader sees from the evidence pass). */
+function digestItemsToHit(items) {
+    return {
+        notePath: exports.DIGEST_HIT_PATH,
+        chunkId: -1,
+        headingPath: 'Digest',
+        text: (0, attach_1.renderEvidenceTable)(items),
+        score: 1,
+        reason: 'digest',
+    };
+}
+/** `renor search`: the hits with the digest hit placed after any synthetic hits already leading, and the report. */
+async function attachDigest(args) {
+    try {
+        const { items, report } = await digestTable(args);
+        if (items.length === 0)
+            return { hits: args.hits, report };
+        let at = 0;
+        while (at < args.hits.length && args.hits[at].notePath.startsWith('_renor/'))
+            at++;
+        return { hits: [...args.hits.slice(0, at), digestItemsToHit(items), ...args.hits.slice(at)], report };
+    }
+    catch (err) {
+        // Optional augmentation: a fault here must never take down the base search, and it is said, not left silent.
+        return {
+            hits: args.hits,
+            report: {
+                status: 'skipped', reason: 'digest-error', windowNotes: 0, notesWithDigest: 0, itemsConsidered: 0,
+                itemsRendered: 0, tokens: 0, text: '', items: [], error: (err instanceof Error ? err.message : String(err)).slice(0, 200),
+            },
+        };
+    }
+}
+/** The `reason` of the synthetic hits that lead a search page: the evidence table and the digest table. */
+exports.LEADING_SUMMARY_REASONS = ['evidence', 'digest'];
+/** How many hits at the head of a page are synthetic summary tables (they sit outside top_k and the ranking). */
+function leadingSummaryHits(hits) {
+    let n = 0;
+    while (n < hits.length && exports.LEADING_SUMMARY_REASONS.includes(hits[n].reason ?? ''))
+        n++;
+    return n;
+}