renor-engine 0.0.0-stage → 1.0.0

package/dist/evidence/attach.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVIDENCE_HIT_PATH = void 0;
+exports.searchEvidenceEnabled = searchEvidenceEnabled;
+exports.productEvidenceReport = productEvidenceReport;
+exports.collectEvidence = collectEvidence;
+exports.evidenceItemsToFactRows = evidenceItemsToFactRows;
+exports.renderEvidenceTable = renderEvidenceTable;
+exports.evidenceItemsToHit = evidenceItemsToHit;
+exports.prependEvidenceHit = prependEvidenceHit;
+exports.attachSearchEvidence = attachSearchEvidence;
+const gate_1 = require("./gate");
+const secondPass_1 = require("./secondPass");
+const background_1 = require("./background");
+const optin_1 = require("./optin");
+/**
+ * Attach H10-v4 second-pass evidence onto the default product search path.
+ *
+ * Kill switch: RENOR_SEARCH_EVIDENCE (default ON since the 2026-09-22 owner
+ * ship decision — the evidence second pass measured +28 net on LongMemEval-S
+ * product runs: 389/500 evidence vs 361/500 baseline, p≈1e-8, official clean
+ * re-validation; the kill switch RENOR_SEARCH_EVIDENCE=0 restores the pre-ship
+ * behavior byte-for-byte). When off, search returns
+ * the same hits array as before this change. When on, the default search /
+ * get_context / search_memory path runs the same extractor as the dedicated
+ * `evidence` tool (full source-note hydration, 20-note backfill, 6k cap,
+ * content-addressed cache) and, on a successful extraction, prepends one
+ * synthetic hit so array-only clients still see the table.
+ *
+ * Retrieval ranking and stored chunk text are never rewritten.
+ */
+exports.EVIDENCE_HIT_PATH = '_renor/evidence';
+function searchEvidenceEnabled(env = process.env) {
+    const raw = (env.RENOR_SEARCH_EVIDENCE ?? '').trim().toLowerCase();
+    if (raw === '0' || raw === 'false' || raw === 'no' || raw === 'off')
+        return false;
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on' || raw === '';
+}
+/**
+ * One sentence per skip reason, saying whether anything is actually missing. The reader is the
+ * user's agent, which can change no setting: the variable or key behind a state stays in `reason`
+ * and the engine's docs, not in the sentence.
+ */
+const EVIDENCE_NOTES = {
+    'flag-off': 'Evidence second pass is switched off for this deployment. Nothing is missing: the hits below are the whole result.',
+    'mode-off': 'Evidence second pass is switched off for this deployment. Nothing is missing: the hits below are the whole result.',
+    'extractor-unavailable': 'This deployment has no evidence model configured, so no dated item table is prepended. Nothing is broken and nothing is missing: the hits below are the whole result.',
+    'intent': 'The evidence gate did not select this query, so no dated item table was prepended. Nothing is missing: the hits below are the whole result.',
+    'no-sessions': 'The ranked hits carried no dated source session to extract items from. Nothing is missing: the hits below are the whole result.',
+    'extractor-parse-error': 'The evidence model answered in a shape the parser rejects, so no dated item table was prepended. Retrieval is unaffected: the hits below are the whole result.',
+    'extractor-error': 'The evidence model call failed, so no dated item table was prepended. Retrieval is unaffected: the hits below are the whole result.',
+    // The two below exist only with bounded-wait evidence on (RENOR_EVIDENCE_ASYNC): the table is missing from this
+    // response, not from the product. get_context quotes them too, so they name no position in the payload.
+    'pending': 'The evidence model did not finish within the time this deployment waits for it, so this response has no dated item table. Retrieval is unaffected. The extraction continues in the background; when it succeeds its table is cached, and the same request over the same notes returns it.',
+    'queue-full': 'The evidence model already has as many extractions waiting as this deployment allows, so none was started for this request and this response has no dated item table. Retrieval is unaffected. The same request starts one once the queue drains.',
+    // Only a workspace that opted in to the Ollama extractor has a daily allowance of model calls.
+    'daily-cap': 'This workspace has used its daily allowance of evidence-model calls, so this response has no dated item table. Retrieval is unaffected: the hits below are the whole result. The allowance starts again at 00:00 UTC.',
+};
+const EVIDENCE_NOTE_DEFAULT = 'The evidence second pass ran and extracted no items. Nothing is missing: the hits below are the whole result.';
+const EVIDENCE_NOTE_OK = 'The evidence second pass extracted items; the dated item table is prepended as the first hit above.';
+function evidenceState(evidence) {
+    if (evidence.status === 'ok')
+        return 'ok';
+    if (evidence.reason === 'flag-off' || evidence.reason === 'mode-off')
+        return 'off';
+    if (evidence.reason === 'extractor-unavailable')
+        return 'unavailable';
+    if (evidence.reason === 'extractor-parse-error' || evidence.reason === 'extractor-error')
+        return 'failed';
+    if (evidence.reason === 'pending')
+        return 'pending';
+    if (evidence.reason === 'queue-full')
+        return 'busy';
+    if (evidence.reason === 'daily-cap')
+        return 'capped';
+    return 'not-applied';
+}
+/**
+ * The same attachment, plus `state` and `note`. Nothing existing is renamed,
+ * dropped or revalued — only the two fields a reader needs to tell an intended
+ * configuration from a fault.
+ */
+function productEvidenceReport(evidence) {
+    return {
+        ...evidence,
+        state: evidenceState(evidence),
+        note: evidence.status === 'ok'
+            ? EVIDENCE_NOTE_OK
+            : ((evidence.reason !== undefined ? EVIDENCE_NOTES[evidence.reason] : undefined) ?? EVIDENCE_NOTE_DEFAULT),
+    };
+}
+async function collectEvidence(args) {
+    const decision = (0, gate_1.evidenceGate)(args.options.mode, args.query, args.force === true);
+    if (!decision.run) {
+        return { status: 'skipped', reason: decision.reason };
+    }
+    const sessions = await (0, secondPass_1.loadEvidenceSessionsFromVault)(args.hits, args.vaultPath, {
+        transformBody: args.transformBody,
+        maxSessions: args.options.maxSessions,
+        charCap: args.options.charCap,
+        // Body-relevance selection input (RENOR_EVIDENCE_BODY_RANK); ignored when
+        // the flag is off.
+        query: args.query,
+    });
+    if (sessions.length === 0) {
+        return { status: 'skipped', reason: 'no-sessions' };
+    }
+    if (!args.extractor) {
+        return { status: 'skipped', reason: 'extractor-unavailable' };
+    }
+    const extractor = args.extractor;
+    // The cached table at once, else the failure this very request met within EVIDENCE_FAILURE_TTL_MS: it is said again
+    // (fromCache) instead of being paid for again. A table wins over a failure remembered for the same key.
+    const key = extractor.cacheKey(args.query, sessions);
+    const cached = extractor.replay(key);
+    if (cached)
+        return evidenceOk(decision.reason, cached);
+    const failed = extractor.replayFailure(key);
+    if (failed)
+        return { status: 'skipped', reason: 'extractor-parse-error', fromCache: true, model: failed.model, error: failed.error };
+    const extract = () => extractEvidence(extractor, key, args.query, sessions, decision.reason, args.parseRetries);
+    const background = args.options.background;
+    if (!background)
+        return extract();
+    // Bounded wait (RENOR_EVIDENCE_ASYNC): this prompt's one extraction, waited for at most background.waitMs. The
+    // flight is keyed by cache file too, so it always fills the cache this search reads.
+    const flight = background.flights.join(`${args.options.cachePath ?? ''}\0${key}`, extract);
+    if (!flight)
+        return { status: 'skipped', reason: 'queue-full' };
+    background.hold?.(flight);
+    const settled = await (0, background_1.waitAtMost)(flight, background.waitMs);
+    if (!settled)
+        return { status: 'skipped', reason: 'pending' };
+    // A joined flight may have been started by a search whose gate gave another reason.
+    return settled.value.status === 'ok' ? { ...settled.value, reason: decision.reason } : settled.value;
+}
+function evidenceOk(reason, result) {
+    return {
+        status: 'ok',
+        reason,
+        fromCache: result.fromCache,
+        model: result.model,
+        items: result.items,
+        sessions: result.sessions,
+        usage: result.usage,
+        latencyMs: result.latencyMs,
+    };
+}
+/**
+ * One extraction, retried on a reply the parser rejects; any other failure is thrown. When the last attempt, too, was
+ * answered with a reply that is not a table, that failure is remembered under `key`; an error before any reply never is.
+ */
+async function extractEvidence(extractor, key, query, sessions, reason, parseRetries) {
+    const maxAttempts = Math.max(1, parseRetries ?? 3);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return evidenceOk(reason, await extractor.extract(query, sessions));
+        }
+        catch (err) {
+            // The workspace's daily allowance is spent: no call was made, and the search goes on without the table.
+            if (err instanceof optin_1.EvidenceCapError)
+                return { status: 'skipped', reason: 'daily-cap', model: extractor.model };
+            lastError = err instanceof Error ? err : new Error(String(err));
+            const parseFailure = /JSON|items list|non-empty item|must be an object/i.test(lastError.message);
+            if (!parseFailure || attempt === maxAttempts)
+                break;
+        }
+    }
+    const parseFailure = lastError && /JSON|items list|non-empty item|must be an object/i.test(lastError.message);
+    if (parseFailure && lastError) {
+        const error = lastError.message.slice(0, 200);
+        if (lastError instanceof secondPass_1.EvidenceReplyError)
+            extractor.rememberFailure(key, error);
+        return {
+            status: 'skipped',
+            reason: 'extractor-parse-error',
+            model: extractor.model,
+            error,
+        };
+    }
+    throw lastError ?? new Error('evidence extraction failed');
+}
+/** H10-v4 fact-row mapping used by the frozen QA facts-table renderer. */
+function evidenceItemsToFactRows(items, event = 'second-pass-v4') {
+    return items.map(item => {
+        const amount = String(item.amount ?? '').trim();
+        const match = amount.match(/^\$?([\d,]+(?:\.\d+)?)\s*(.*)$/);
+        let value = 1;
+        let unit = amount;
+        if (amount && match) {
+            value = match[1].replace(/,/g, '');
+            unit = match[2] ?? '';
+        }
+        return {
+            value,
+            unit,
+            verb: item.action ?? '',
+            object: item.item ?? '',
+            event,
+            confirm: 1,
+            dates: [item.date ?? ''],
+        };
+    });
+}
+function renderEvidenceTable(items) {
+    const lines = items.map(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 `- ${item.item}${action}${amount}${date}`;
+    });
+    return [
+        'User-asserted items extracted from full source notes (with dates):',
+        ...lines,
+        'Use this table when relevant; cite only values present here. If the table does not contain the value needed to answer, use the excerpts instead.',
+    ].join('\n');
+}
+function evidenceItemsToHit(items) {
+    return {
+        notePath: exports.EVIDENCE_HIT_PATH,
+        chunkId: -1,
+        headingPath: 'Evidence',
+        text: renderEvidenceTable(items),
+        score: 1,
+        reason: 'evidence',
+    };
+}
+function prependEvidenceHit(hits, attachment) {
+    if (attachment.status !== 'ok' || !attachment.items?.length)
+        return hits;
+    if (hits.some(hit => hit.notePath === exports.EVIDENCE_HIT_PATH && hit.reason === 'evidence'))
+        return hits;
+    return [evidenceItemsToHit(attachment.items), ...hits];
+}
+async function attachSearchEvidence(args) {
+    if (!(args.enabled ?? searchEvidenceEnabled())) {
+        return { hits: args.hits, evidence: { status: 'skipped', reason: 'flag-off' } };
+    }
+    try {
+        const evidence = await collectEvidence({
+            transformBody: args.transformBody,
+            query: args.query,
+            hits: args.hits,
+            vaultPath: args.vaultPath,
+            options: args.options,
+            extractor: args.extractor,
+            force: args.force,
+        });
+        return { hits: prependEvidenceHit(args.hits, evidence), evidence };
+    }
+    catch (err) {
+        // Evidence is optional augmentation. Provider/network/cache failures must
+        // never take down the base search path, but they are said, with the
+        // extractor that failed, never left as a silently missing table (#222).
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            hits: args.hits,
+            evidence: {
+                status: 'skipped',
+                reason: 'extractor-error',
+                ...(args.extractor ? { model: args.extractor.model } : {}),
+                error: message.slice(0, 200),
+            },
+        };
+    }
+}

package/dist/evidence/background.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceFlights = exports.EVIDENCE_BACKGROUND_QUEUE = exports.EVIDENCE_BACKGROUND_CONCURRENCY = exports.EVIDENCE_WAIT_MS_MAX = exports.EVIDENCE_WAIT_MS_DEFAULT = void 0;
+exports.evidenceAsyncEnabled = evidenceAsyncEnabled;
+exports.resolveEvidenceWaitMs = resolveEvidenceWaitMs;
+exports.resolveEvidenceBackground = resolveEvidenceBackground;
+exports.sharedEvidenceFlights = sharedEvidenceFlights;
+exports.waitAtMost = waitAtMost;
+/**
+ * Bounded-wait evidence for get_context and search_memory (RENOR_EVIDENCE_ASYNC, default OFF).
+ *
+ * The evidence second pass runs inside the read tools, so a search waits for the extractor: about 1-4 s with today's
+ * model, 5-27 s on average with the better ones measured on 2026-10-03 (p95 up to 76 s). With this flag off nothing
+ * here runs and every search waits, as before. With it on, a search waits at most RENOR_EVIDENCE_WAIT_MS:
+ *
+ *   - a table already in the evidence cache (keyed on model + exact prompt) is returned at once;
+ *   - otherwise the extraction starts, and if it does not finish within the wait the response has no table and says
+ *     so (`state: "pending"`); the extraction carries on in the background and its table lands in the cache, so the
+ *     same query over the same notes returns it;
+ *   - one extraction per prompt (single-flight): a search for a prompt already being extracted joins that extraction;
+ *   - at most EVIDENCE_BACKGROUND_CONCURRENCY extractions run and EVIDENCE_BACKGROUND_QUEUE wait; a search past that
+ *     starts nothing and says so (`state: "busy"`).
+ *
+ * Only the MVP read tools read the flag (resolveEngineEvidence). The CLI, which is the benchmark's entry point, the
+ * HTTP API and the stdio MCP server never do, so no benchmark run can change behaviour because of it.
+ */
+exports.EVIDENCE_WAIT_MS_DEFAULT = 2_000;
+exports.EVIDENCE_WAIT_MS_MAX = 60_000;
+/** Extractions running at once, per process (one process serves one workspace). */
+exports.EVIDENCE_BACKGROUND_CONCURRENCY = 2;
+/** Extractions waiting for a free slot, per process. */
+exports.EVIDENCE_BACKGROUND_QUEUE = 16;
+/** RENOR_EVIDENCE_ASYNC: on only for 1 / true / yes / on; unset and anything else is off. */
+function evidenceAsyncEnabled(env = process.env) {
+    const raw = (env.RENOR_EVIDENCE_ASYNC ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+/** RENOR_EVIDENCE_WAIT_MS: whole milliseconds, 0 to 60,000; unset or unreadable is the default. */
+function resolveEvidenceWaitMs(env = process.env) {
+    const raw = (env.RENOR_EVIDENCE_WAIT_MS ?? '').trim();
+    const ms = raw === '' ? Number.NaN : Number(raw);
+    if (!Number.isFinite(ms) || ms < 0)
+        return exports.EVIDENCE_WAIT_MS_DEFAULT;
+    return Math.min(Math.floor(ms), exports.EVIDENCE_WAIT_MS_MAX);
+}
+/** The bounded-wait settings when the flag is on, else undefined: a search then waits for the extractor, as before. */
+function resolveEvidenceBackground(env = process.env) {
+    if (!evidenceAsyncEnabled(env))
+        return undefined;
+    return { waitMs: resolveEvidenceWaitMs(env), flights: sharedEvidenceFlights() };
+}
+/**
+ * The extractions in the air, one per key, with at most `concurrency` running and `queue` waiting.
+ *
+ * Every search of a process must share one of these: the MVP server builds a fresh tool set (and extractor) for each
+ * SSE session, so flights kept per extractor would neither join a second session's identical search nor bound the
+ * process's spend.
+ */
+class EvidenceFlights {
+    concurrency;
+    queue;
+    inFlight = new Map();
+    waiting = [];
+    running = 0;
+    /**
+     * started: extractions begun; joined: searches that shared one; refused: searches turned away by a full queue;
+     * failed: extractions that ended without a table.
+     */
+    counts = { started: 0, joined: 0, refused: 0, failed: 0 };
+    constructor(limits = {}) {
+        this.concurrency = Math.max(1, limits.concurrency ?? exports.EVIDENCE_BACKGROUND_CONCURRENCY);
+        this.queue = Math.max(0, limits.queue ?? exports.EVIDENCE_BACKGROUND_QUEUE);
+    }
+    /**
+     * The one extraction of `key`: the flight already in the air, or a new one that `run` performs now or once a slot is
+     * free. Null when the queue is full, and then nothing is started. The key is deleted when the flight ends, after
+     * `run` has written the cache, so a later search finds the table there instead of starting again.
+     */
+    join(key, run) {
+        const current = this.inFlight.get(key);
+        if (current) {
+            this.counts.joined += 1;
+            return current;
+        }
+        if (this.running >= this.concurrency && this.waiting.length >= this.queue) {
+            this.counts.refused += 1;
+            return null;
+        }
+        const slot = new Promise(resolve => {
+            if (this.running < this.concurrency) {
+                this.running += 1;
+                resolve();
+            }
+            else {
+                this.waiting.push(() => {
+                    this.running += 1;
+                    resolve();
+                });
+            }
+        });
+        const flight = slot.then(run).finally(() => {
+            this.inFlight.delete(key);
+            this.running -= 1;
+            this.waiting.shift()?.();
+        });
+        // A flight outlives the searches that started it, so its end is observed here: when it fails after they stopped
+        // waiting nobody else holds the promise, and a rejection must never surface as an unhandled one; and an operator
+        // reading the log is the only one left to learn that it failed. The reason code only: never the query or the
+        // provider's message, which may quote the user's notes.
+        flight.then(outcome => {
+            if (outcome.status !== 'ok')
+                this.ended(outcome.reason ?? 'skipped');
+        }, () => this.ended('extractor-error'));
+        this.inFlight.set(key, flight);
+        this.counts.started += 1;
+        return flight;
+    }
+    ended(reason) {
+        this.counts.failed += 1;
+        process.stderr.write(`[evidence] a background extraction ended without a table (${reason})\n`);
+    }
+    /** Resolves once nothing is running or waiting (tests, benchmarks). */
+    async idle() {
+        while (this.inFlight.size > 0)
+            await Promise.allSettled([...this.inFlight.values()]);
+    }
+}
+exports.EvidenceFlights = EvidenceFlights;
+let shared;
+/** The process's flights, created on first use. */
+function sharedEvidenceFlights() {
+    shared ??= new EvidenceFlights();
+    return shared;
+}
+/** `promise`'s value if it settles within `ms`, else undefined. A later rejection is not this caller's to handle. */
+function waitAtMost(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        promise.then(value => {
+            clearTimeout(timer);
+            resolve({ value });
+        }, err => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/evidence/evidenceCache.js

@@ -0,0 +1,182 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCache = exports.EVIDENCE_FAILURE_TTL_MS = exports.EVIDENCE_SCHEMA_VERSION = void 0;
+exports.dropEvidenceForStems = dropEvidenceForStems;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_path_1 = __importDefault(require("node:path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+/**
+ * Content-addressed cache for the H10 second-pass evidence extraction.
+ *
+ * Key = sha256(EVIDENCE_SCHEMA_VERSION \0 model \0 prompt), where prompt is the
+ * exact rendered extractor prompt; a `bounds:` segment precedes the prompt only
+ * when RENOR_EVIDENCE_MAX_TOKENS or RENOR_EVIDENCE_REASONING_EFFORT is set. Any
+ * question, session-text, selection, or prompt-template change invalidates only
+ * the affected entries. The same question over unchanged session content
+ * replays for zero model cost.
+ *
+ * Stores parsed items (the extractor's JSON must parse before an entry is
+ * written — fail-fast extraction never caches a malformed response). A failed
+ * extraction is remembered apart from the tables, under the same key, for
+ * EVIDENCE_FAILURE_TTL_MS (table evidence_failures).
+ *
+ * Design follows the eval cache (src/eval/evalCache.ts): SQLite + WAL +
+ * busy_timeout=10000 + INSERT OR IGNORE.
+ */
+exports.EVIDENCE_SCHEMA_VERSION = 'evidence-v1';
+/**
+ * How long a failed extraction is remembered: 24 hours.
+ *
+ * Measured 2026-10-03 (GLM-5.3-Flash on Nebius, dev100): 39% of extraction
+ * spend went to replies that reasoned to the provider's 8,192-token cap and
+ * returned no content. Only tables were cached, so every repeat of such a
+ * search paid for its three attempts again, and waited minutes for them.
+ *
+ * Only a reply is remembered: the model answered the last attempt, and its
+ * answer is not a table (secondPass.ts EvidenceReplyError). An error before any
+ * reply (a 429, a 5xx, a timeout, a refused request, no connection) says
+ * nothing about the request and is never remembered: the next search asks
+ * again. The key is the table's (model, bounds, exact prompt), so anything that
+ * could change the outcome by itself (other notes, another question, model or
+ * bound) is a new key and is asked at once. What a day gives up is luck, the
+ * same request answered better next time, for at most one paid failure per
+ * request per day. DELETE FROM evidence_failures forgets them all at once.
+ */
+exports.EVIDENCE_FAILURE_TTL_MS = 24 * 60 * 60 * 1000;
+class EvidenceCache {
+    db;
+    lookupStmt;
+    insertStmt;
+    touchStmt;
+    failureLookupStmt;
+    failureTouchStmt;
+    failureSweepStmt;
+    failurePutStmt;
+    constructor(dbPath) {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
+        this.db = new better_sqlite3_1.default(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 10000');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS evidence_cache (
+        cache_key TEXT PRIMARY KEY,
+        schema_version TEXT NOT NULL,
+        model TEXT NOT NULL,
+        question TEXT NOT NULL,
+        sessions_json TEXT NOT NULL,
+        items_json TEXT NOT NULL,
+        prompt_tokens INTEGER NOT NULL DEFAULT 0,
+        completion_tokens INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        last_used_at TEXT,
+        hits INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        // Cache lookups are content-addressed by the cache_key primary key. Older
+        // evidence-v1 databases created a secondary question index that no runtime
+        // query uses; remove it so inserts do not maintain a redundant B-tree.
+        this.db.exec('DROP INDEX IF EXISTS idx_evidence_cache_question');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS evidence_failures (
+        cache_key TEXT PRIMARY KEY,
+        model TEXT NOT NULL,
+        error TEXT NOT NULL,
+        failed_at_ms INTEGER NOT NULL,
+        hits INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        this.lookupStmt = this.db.prepare('SELECT items_json, sessions_json, model, question, prompt_tokens, completion_tokens, created_at, hits FROM evidence_cache WHERE cache_key = ?');
+        this.insertStmt = this.db.prepare(`INSERT OR IGNORE INTO evidence_cache
+       (cache_key, schema_version, model, question, sessions_json, items_json,
+        prompt_tokens, completion_tokens, created_at, last_used_at, hits)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)`);
+        this.touchStmt = this.db.prepare('UPDATE evidence_cache SET hits = hits + 1, last_used_at = ? WHERE cache_key = ?');
+        this.failureLookupStmt = this.db.prepare('SELECT model, error, failed_at_ms FROM evidence_failures WHERE cache_key = ? AND failed_at_ms > ?');
+        this.failureTouchStmt = this.db.prepare('UPDATE evidence_failures SET hits = hits + 1 WHERE cache_key = ?');
+        this.failureSweepStmt = this.db.prepare('DELETE FROM evidence_failures WHERE failed_at_ms <= ?');
+        this.failurePutStmt = this.db.prepare('INSERT OR REPLACE INTO evidence_failures (cache_key, model, error, failed_at_ms, hits) VALUES (?, ?, ?, ?, 0)');
+    }
+    /**
+     * SHA-256 key over schema version, model, any request bounds, and the exact
+     * rendered prompt. With no bound set it is the legacy key, so every existing
+     * entry still replays; a bound adds one segment, so a bounded arm and an
+     * unbounded arm never share an entry.
+     */
+    static computeKey(model, prompt, bounds = {}) {
+        const bound = [
+            ...(bounds.maxTokens !== undefined ? [`max_tokens=${bounds.maxTokens}`] : []),
+            ...(bounds.reasoningEffort !== undefined ? [`reasoning_effort=${bounds.reasoningEffort}`] : []),
+        ].join(';');
+        return node_crypto_1.default.createHash('sha256')
+            .update(`${exports.EVIDENCE_SCHEMA_VERSION}\0${model}\0${bound ? `bounds:${bound}\0` : ''}${prompt}`)
+            .digest('hex');
+    }
+    /** Lookup. Returns null on miss. Touches hit counters on a hit. */
+    get(cacheKey) {
+        const row = this.lookupStmt.get(cacheKey);
+        if (!row)
+            return null;
+        this.touchStmt.run(new Date().toISOString(), cacheKey);
+        return {
+            items: JSON.parse(row.items_json),
+            sessions: JSON.parse(row.sessions_json),
+            model: row.model,
+            question: row.question,
+            promptTokens: row.prompt_tokens,
+            completionTokens: row.completion_tokens,
+            createdAt: row.created_at,
+        };
+    }
+    /** Store a freshly extracted, already-parsed entry. Existing keys are never overwritten. */
+    put(cacheKey, entry) {
+        this.insertStmt.run(cacheKey, exports.EVIDENCE_SCHEMA_VERSION, entry.model, entry.question, JSON.stringify(entry.sessions), JSON.stringify(entry.items), entry.promptTokens, entry.completionTokens, entry.createdAt, entry.createdAt);
+    }
+    /** The failure remembered under `cacheKey` less than EVIDENCE_FAILURE_TTL_MS ago, or null. Touches its hit counter. */
+    getFailure(cacheKey) {
+        const row = this.failureLookupStmt.get(cacheKey, Date.now() - exports.EVIDENCE_FAILURE_TTL_MS);
+        if (!row)
+            return null;
+        this.failureTouchStmt.run(cacheKey);
+        return { model: row.model, error: row.error, failedAt: row.failed_at_ms };
+    }
+    /** Remember a failed extraction, replacing any earlier one under the key; expired failures are dropped. */
+    putFailure(cacheKey, entry) {
+        this.failureSweepStmt.run(entry.failedAt - exports.EVIDENCE_FAILURE_TTL_MS);
+        this.failurePutStmt.run(cacheKey, entry.model, entry.error, entry.failedAt);
+    }
+    stats() {
+        const row = this.db.prepare('SELECT COUNT(*) as entries, COALESCE(SUM(hits), 0) as hits, COALESCE(SUM(prompt_tokens), 0) as promptTokens, COALESCE(SUM(completion_tokens), 0) as completionTokens FROM evidence_cache').get();
+        return row;
+    }
+    close() {
+        this.db.close();
+    }
+}
+exports.EvidenceCache = EvidenceCache;
+/**
+ * Drop every cached extraction that read one of `stems` (note paths): a permanent deletion takes the text these rows
+ * extracted from a deleted memory (memorymap/memoryMap.ts, purgeRetired). Nothing to do when the cache file or its table
+ * does not exist. The cache is keyed by the exact prompt, so a dropped row is only asked again when a later search reads
+ * the same files.
+ */
+function dropEvidenceForStems(cachePath, stems) {
+    if (stems.length === 0 || !node_fs_1.default.existsSync(cachePath))
+        return;
+    const db = new better_sqlite3_1.default(cachePath);
+    try {
+        db.pragma('busy_timeout = 10000');
+        if (!db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'evidence_cache'`).get())
+            return;
+        const drop = db.prepare(`DELETE FROM evidence_cache WHERE json_valid(sessions_json) AND EXISTS (
+         SELECT 1 FROM json_each(sessions_json) s WHERE json_extract(s.value, '$.stem') = ?)`);
+        db.transaction(() => { for (const stem of stems)
+            drop.run(stem); })();
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/evidence/gate.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVIDENCE_INTENT = void 0;
+exports.resolveEvidenceMode = resolveEvidenceMode;
+exports.hasEvidenceIntent = hasEvidenceIntent;
+exports.evidenceGate = evidenceGate;
+function resolveEvidenceMode(env = process.env) {
+    const raw = (env.RENOR_EVIDENCE_MODE ?? '').trim().toLowerCase();
+    if (raw === '')
+        return 'off';
+    if (raw === 'off' || raw === 'false' || raw === '0' || raw === 'no')
+        return 'off';
+    if (raw === 'always' || raw === 'on' || raw === '1' || raw === 'yes' || raw === 'all')
+        return 'always';
+    if (raw === 'auto')
+        return 'auto';
+    throw new Error(`Invalid RENOR_EVIDENCE_MODE "${raw}": must be off | auto | always`);
+}
+/**
+ * Gold-blind aggregation/enumeration intent. Copied from the eval runner's
+ * AGGREGATE_INTENT and widened with count/list cues; never fixture-specific.
+ */
+exports.EVIDENCE_INTENT = /\b(how many|how much|in total|total|altogether|combined|all of the|all the|count|number of|list|enumerate|every)\b/i;
+function hasEvidenceIntent(query) {
+    return exports.EVIDENCE_INTENT.test(query);
+}
+function evidenceGate(mode, query, force = false) {
+    if (mode === 'off')
+        return { run: false, reason: 'mode-off' };
+    if (force)
+        return { run: true, reason: 'forced' };
+    if (mode === 'always')
+        return { run: true, reason: 'mode-always' };
+    if (hasEvidenceIntent(query))
+        return { run: true, reason: 'intent' };
+    return { run: false, reason: 'intent' };
+}