renor-engine 0.0.0-stage → 1.0.0

package/dist/eval/context700-candidate.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalSegment = exports.COMPILER_VERSION = exports.isHeaderOnly = void 0;
+exports.compileContext = compileContext;
+/**
+ * Context700 campaign — MUTABLE context compiler.
+ *
+ * Campaign contract (docs/agents/autoresearch/context700/program.md):
+ * - Target: <= 700 mean Renor memory-evidence tokens/query on LongMemEval-S full-500.
+ * - Frozen quality floor: >= 428/500, no category regression > 2.0 pp vs N22 (430/500).
+ * - ONLY this file is mutable after harness freeze.
+ *
+ * The compiler is gold-blind: it may use the question text/date, retrieval hits,
+ * and structured extraction tables. It may NOT use gold answers, benchmark
+ * question IDs (as decision keys), judge outputs, or correctness labels.
+ *
+ * v3 (structured-first + date-preserving compaction + recency raw fill):
+ *   Lesson from v1 (31/118 screen KILL): raw-first 55% budget + aggressive
+ *   compaction starved date-bearing stubs and chronicle breadth. v3:
+ *   1. Query-gated structured rows FIRST (facts cap 12, chronicle cap 10, prefs cap 6).
+ *   2. Raw excerpts: compact turn markers, PRESERVE Timestamp/date lines and
+ *      header stubs (they carry session dates), recency-ordered like N22.
+ *   3. Fill remaining budget by rank; no minimum raw count (tables win ties).
+ */
+const gpt_tokenizer_1 = require("gpt-tokenizer");
+const canonicalSegment = (notePath) => notePath.replace(/^Sessions\//, '').replace(/-occ\d+\.md$/, '.md').replace(/\.md$/, '');
+exports.canonicalSegment = canonicalSegment;
+const isHeaderOnly = (text) => !text.includes('### Turn') && text.trim().length < 250;
+exports.isHeaderOnly = isHeaderOnly;
+exports.COMPILER_VERSION = 'v3-struct-first-date-keeping';
+const CONTENT_STOP = new Set('the a an of to for and or in on my i with is are was be that this it at as by from have has had do does did not no you your me we our they their he she his her about into over under then than so if but'.split(' '));
+const contentWords = (s) => {
+    const out = new Set();
+    for (const w of s.toLowerCase().matchAll(/[a-z0-9]{3,}/g)) {
+        if (!CONTENT_STOP.has(w[0]))
+            out.add(w[0]);
+    }
+    return out;
+};
+/** Compact date: "2023/05/30 (Tue) 23:40" -> "2023/05/30". */
+const compactDate = (d) => d ? d.replace(/\s*\((?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\).*/, '') : '';
+/**
+ * v3 compaction: shorten turn markers to `[N-role]`, drop long session headers,
+ * but PRESERVE Timestamp lines (dates are load-bearing for temporal/multi-session).
+ */
+const compactText = (t) => t
+    .replace(/^### Turn (\d+) — (User|Assistant)\s*\|?\s*/gim, '[$1-$2] ')
+    .replace(/^Timestamp: (.*)$/gim, '@$1')
+    .replace(/^# Session .*\n?/gim, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+const gateRows = (rows, qWords, cap) => {
+    if (!rows || rows.length === 0)
+        return [];
+    const scored = [];
+    for (const row of rows) {
+        const text = Object.values(row).map(v => (typeof v === 'string' ? v : JSON.stringify(v) ?? '')).join(' ');
+        let overlap = 0;
+        for (const w of contentWords(text))
+            if (qWords.has(w))
+                overlap++;
+        if (overlap > 0)
+            scored.push({ score: overlap, row });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, cap);
+};
+function compileContext(args) {
+    const { question, hits, tables, dateMap, maxContextTokens } = args;
+    const qWords = contentWords(question.question);
+    const parts = { rawTokens: 0, factsTokens: 0, chronicleTokens: 0, prefsTokens: 0 };
+    const excerpts = [];
+    // --- Structured rows first (gated) ---
+    let tokens = 0;
+    let remaining = maxContextTokens;
+    const factScored = gateRows(tables.facts ?? [], qWords, 12);
+    if (factScored.length) {
+        const lines = factScored.map(({ row: f }) => {
+            const co = f.coexist ? ` (also: ${f.coexist})` : '';
+            return `- ${f.value} ${f.unit ?? ''} ${f.object ?? ''}${f.event ? ` — ${f.event}` : ''}${co}`.replace(/\s+/g, ' ').trim();
+        });
+        const block = `Numeric facts:\n${lines.join('\n')}\nCite only values present here; otherwise use excerpts.`;
+        const blockTokens = (0, gpt_tokenizer_1.encode)(block).length;
+        if (blockTokens <= remaining) {
+            excerpts.push({ text: block, date: null });
+            tokens += blockTokens;
+            parts.factsTokens = blockTokens;
+            remaining -= blockTokens;
+        }
+    }
+    const chronScored = gateRows(tables.chronicle ?? [], qWords, 10);
+    if (chronScored.length) {
+        const lines = chronScored.map(({ row: e }) => `- ${e.when ?? ''}: ${e.event ?? ''}`.replace(/\s+/g, ' ').trim());
+        const block = `Events:\n${lines.join('\n')}\nCite only events present here; otherwise use excerpts.`;
+        const blockTokens = (0, gpt_tokenizer_1.encode)(block).length;
+        if (blockTokens <= remaining) {
+            excerpts.push({ text: block, date: null });
+            tokens += blockTokens;
+            parts.chronicleTokens = blockTokens;
+            remaining -= blockTokens;
+        }
+    }
+    const prefScored = gateRows(tables.prefs ?? [], qWords, 6);
+    if (prefScored.length) {
+        const lines = prefScored.map(({ row: p }) => `- ${p.statement ?? ''}`.replace(/\s+/g, ' ').trim());
+        const block = `Standing preferences:\n${lines.join('\n')}\nApply matching entries; otherwise use excerpts.`;
+        const blockTokens = (0, gpt_tokenizer_1.encode)(block).length;
+        if (blockTokens <= remaining) {
+            excerpts.push({ text: block, date: null });
+            tokens += blockTokens;
+            parts.prefsTokens = blockTokens;
+            remaining -= blockTokens;
+        }
+    }
+    const raws = [];
+    const seen = new Set();
+    for (const hit of args.hits) {
+        const text = compactText((hit.text ?? '').trim());
+        if (!text || seen.has(hit.text ?? ''))
+            continue;
+        const sessionDate = dateMap?.get(canonicalSegment(hit.notePath)) ?? null;
+        seen.add(hit.text ?? '');
+        raws.push({ text, date: sessionDate });
+    }
+    // N22 recency ordering (newest-first) before selection.
+    if (args.recencyOrder) {
+        raws.sort((a, b) => (b.date ?? '').localeCompare(a.date ?? ''));
+    }
+    for (const raw of raws) {
+        const dateMark = raw.date ? `(${compactDate(raw.date)}) ` : '';
+        const candidate = `${dateMark}${raw.text}`;
+        const candidateTokens = (0, gpt_tokenizer_1.encode)(candidate).length;
+        if (tokens + candidateTokens > maxContextTokens)
+            break;
+        tokens += candidateTokens;
+        excerpts.push({ text: candidate, date: raw.date });
+    }
+    parts.rawTokens = tokens - parts.factsTokens - parts.chronicleTokens - parts.prefsTokens;
+    return {
+        context: excerpts.map(excerpt => excerpt.text).join('\n\n'),
+        tokens,
+        parts,
+        diagnostics: { compilerVersion: args.compilerVersion },
+    };
+}

package/dist/eval/evalCache.js

@@ -0,0 +1,525 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = exports.KeyPool = exports.EvalCache = exports.CACHE_SCHEMA_VERSION = void 0;
+exports.summarizeQaTokenUsage = summarizeQaTokenUsage;
+exports.runWithKeyPoolRetries = runWithKeyPoolRetries;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.resolveWorkerConcurrency = resolveWorkerConcurrency;
+exports.resolveCacheScope = resolveCacheScope;
+exports.resolveEvalCachePath = resolveEvalCachePath;
+exports.resolveJudgeKeys = resolveJudgeKeys;
+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"));
+/**
+ * Content-addressed eval cache for LongMemEval QA runs.
+ *
+ * Architecture: full-request hashing → raw-response replay.
+ *
+ * Key = sha256(CACHE_SCHEMA_VERSION + providerNamespace + JSON.stringify(requestBody)).
+ * No .trim(), no selected-field hashing. Any prompt edit, temperature change,
+ * or model swap automatically invalidates the cache because the full request
+ * body changes.
+ *
+ * Stores raw model responses (not parsed verdicts). Parsing happens at read
+ * time so future parser improvements don't require re-running models.
+ *
+ * The cache is "frozen replay": it stores the exact bytes a model returned for
+ * a given request. It does NOT assume LLM calls are deterministic — even at
+ * temperature 0, provider drift can produce different outputs for identical
+ * prompts. The cache replays the first-seen draw. Authoritative promotion
+ * runs should use --no-cache for a cold full-500.
+ *
+ * Design follows the existing embedding cache (src/embeddings/caching.ts):
+ * SQLite + WAL + busy_timeout=10000 + INSERT OR IGNORE.
+ */
+/**
+ * Bump this on any change to key computation or stored schema.
+ *
+ * v2 (2026-09-18): invalidated all v1 entries after the degraded shared-session
+ * incident.
+ *
+ * v3 (2026-09-19): adds an explicit cache scope to key computation. The QA
+ * runner passes the effective x-opencode-session as that scope, so a response
+ * produced by one routed backend session can never be replayed into another.
+ *
+ * v4 (2026-09-22 / integrity fix 2026-09-23): documents the campaign finding
+ * that cross-run replay needs a pinned cache scope + shared --cache-dir (and
+ * shared evidence cache for evidence arms) — NOT body rewriting. The
+ * path-variance diagnostic (scripts/eval/diagnose-evalcache-path-variance.ts)
+ * measured runner-assembly answer/judge bodies as ALREADY byte-identical across
+ * different per-case temp dirs (notePaths relativized; evidence tables emit
+ * item/action/amount/date only). A brief experiment that rewrote
+ * /tmp/renor-product-XXXXXX tokens inside the hashed JSON was rejected before
+ * merge: model-visible path-shaped strings must remain part of the key, or two
+ * different contexts can collide and replay the wrong answer.
+ *
+ * Key formula is unchanged from v3 aside from the version string: sha256 of
+ * CACHE_SCHEMA_VERSION \0 providerNamespace \0 cacheScope \0
+ * JSON.stringify(requestBody) with NO body mutation. Keeping the v4 label
+ * intentionally invalidates v3 rows: a brief pre-merge canonicalize experiment
+ * may have written experimental v4 keys on developer machines, and a clean
+ * version cut avoids mixed semantics (cheaper than subtle collisions between
+ * v3 and any experimental v4 rows). Scoring stays fail-closed on the schema
+ * recorded in the run manifest.
+ */
+exports.CACHE_SCHEMA_VERSION = 'evalcache-v4';
+function summarizeQaTokenUsage(records) {
+    return {
+        live: {
+            answerPrompt: records.reduce((n, c) => n + (!c.answer?.fromCache ? (c.answer?.usage?.promptTokens ?? 0) : 0), 0),
+            answerCompletion: records.reduce((n, c) => n + (!c.answer?.fromCache ? (c.answer?.usage?.completionTokens ?? 0) : 0), 0),
+            judgePrompt: records.reduce((n, c) => n + (!c.judge?.fromCache ? (c.judge?.usage?.promptTokens ?? 0) : 0), 0),
+            judgeCompletion: records.reduce((n, c) => n + (!c.judge?.fromCache ? (c.judge?.usage?.completionTokens ?? 0) : 0), 0),
+        },
+        avoided: {
+            answerPrompt: records.reduce((n, c) => n + (c.answer?.fromCache ? (c.answer?.usage?.promptTokens ?? 0) : 0), 0),
+            answerCompletion: records.reduce((n, c) => n + (c.answer?.fromCache ? (c.answer?.usage?.completionTokens ?? 0) : 0), 0),
+            judgePrompt: records.reduce((n, c) => n + (c.judge?.fromCache ? (c.judge?.usage?.promptTokens ?? 0) : 0), 0),
+            judgeCompletion: records.reduce((n, c) => n + (c.judge?.fromCache ? (c.judge?.usage?.completionTokens ?? 0) : 0), 0),
+        },
+    };
+}
+class EvalCache {
+    db;
+    stats = {
+        answerHits: 0, answerMisses: 0,
+        judgeHits: 0, judgeMisses: 0,
+        avoidedAnswerPromptTokens: 0, avoidedAnswerCompletionTokens: 0,
+        avoidedJudgePromptTokens: 0, avoidedJudgeCompletionTokens: 0,
+        liveAnswerPromptTokens: 0, liveAnswerCompletionTokens: 0,
+        liveJudgePromptTokens: 0, liveJudgeCompletionTokens: 0,
+        cacheLookupTotalMs: 0, cacheLookupCount: 0,
+    };
+    lookupStmt;
+    insertStmt;
+    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 eval_responses (
+        cache_key TEXT PRIMARY KEY,
+        cache_schema_version TEXT NOT NULL,
+        provider_namespace TEXT NOT NULL,
+        call_type TEXT NOT NULL,
+        question_id TEXT NOT NULL,
+        raw_content TEXT NOT NULL,
+        model_echo TEXT NOT NULL,
+        finish_reason TEXT NOT NULL,
+        prompt_tokens INTEGER NOT NULL DEFAULT 0,
+        completion_tokens INTEGER NOT NULL DEFAULT 0,
+        latency_ms INTEGER NOT NULL DEFAULT 0,
+        request_body_json TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_eval_responses_qid ON eval_responses(question_id)`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_eval_responses_type ON eval_responses(call_type)`);
+        this.lookupStmt = this.db.prepare('SELECT raw_content, model_echo, finish_reason, prompt_tokens, completion_tokens, latency_ms, provider_namespace FROM eval_responses WHERE cache_key = ?');
+        this.insertStmt = this.db.prepare(`INSERT OR IGNORE INTO eval_responses
+       (cache_key, cache_schema_version, provider_namespace, call_type, question_id,
+        raw_content, model_echo, finish_reason, prompt_tokens, completion_tokens,
+        latency_ms, request_body_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    }
+    /**
+     * Compute a content-addressed cache key from the full API request plus an
+     * optional routing scope.
+     *
+     * Key = sha256(CACHE_SCHEMA_VERSION \0 providerNamespace \0 cacheScope
+     *              \0 requestBodyJSON).
+     *
+     * The request body is hashed as-is (no path rewriting). Cross-run replay
+     * relies on pinned RENOR_QA_CACHE_SCOPE + shared --cache-dir, not on
+     * mutating model-visible text before the key (v4 integrity fix).
+     *
+     * The QA runner uses the effective x-opencode-session as cacheScope because
+     * that header has been empirically shown to affect backend routing/results.
+     * Callers that have no routing-sensitive context may leave the scope empty.
+     */
+    static computeKey(providerNamespace, requestBody, cacheScope = '') {
+        // Hash the raw request body. Never rewrite model-visible text — path-shaped
+        // tokens in context must produce distinct keys (integrity).
+        return node_crypto_1.default.createHash('sha256')
+            .update(`${exports.CACHE_SCHEMA_VERSION}\0${providerNamespace}\0${cacheScope}\0${JSON.stringify(requestBody)}`)
+            .digest('hex');
+    }
+    /**
+     * Look up a cached response. Returns null on miss.
+     */
+    get(cacheKey, callType) {
+        const started = Date.now();
+        const row = this.lookupStmt.get(cacheKey);
+        this.stats.cacheLookupTotalMs += Date.now() - started;
+        this.stats.cacheLookupCount++;
+        if (!row) {
+            if (callType === 'answer')
+                this.stats.answerMisses++;
+            else
+                this.stats.judgeMisses++;
+            return null;
+        }
+        if (callType === 'answer') {
+            this.stats.answerHits++;
+            this.stats.avoidedAnswerPromptTokens += row.prompt_tokens;
+            this.stats.avoidedAnswerCompletionTokens += row.completion_tokens;
+        }
+        else {
+            this.stats.judgeHits++;
+            this.stats.avoidedJudgePromptTokens += row.prompt_tokens;
+            this.stats.avoidedJudgeCompletionTokens += row.completion_tokens;
+        }
+        return {
+            rawContent: row.raw_content,
+            modelEcho: row.model_echo,
+            finishReason: row.finish_reason,
+            promptTokens: row.prompt_tokens,
+            completionTokens: row.completion_tokens,
+            latencyMs: row.latency_ms,
+            providerNamespace: row.provider_namespace,
+        };
+    }
+    insertEntry(params) {
+        const result = this.insertStmt.run(params.cacheKey, exports.CACHE_SCHEMA_VERSION, params.providerNamespace, params.callType, params.questionId, params.rawContent, params.modelEcho, params.finishReason, params.promptTokens, params.completionTokens, params.latencyMs, JSON.stringify(params.requestBody), new Date().toISOString());
+        return result.changes;
+    }
+    /**
+     * Store a live response in the cache. INSERT OR IGNORE preserves first-seen semantics.
+     */
+    put(params) {
+        this.insertEntry(params);
+        // Track live usage
+        if (params.callType === 'answer') {
+            this.stats.liveAnswerPromptTokens += params.promptTokens;
+            this.stats.liveAnswerCompletionTokens += params.completionTokens;
+        }
+        else {
+            this.stats.liveJudgePromptTokens += params.promptTokens;
+            this.stats.liveJudgeCompletionTokens += params.completionTokens;
+        }
+    }
+    /**
+     * Promote an already-observed response into another cache identity without
+     * counting it as a second live provider call. Returns true only when a new
+     * cache row was inserted.
+     */
+    promote(params) {
+        return this.insertEntry(params) > 0;
+    }
+    /**
+     * Invalidate recorded model calls. Filters combine (AND); an empty filter is
+     * refused unless `all` is explicit. Returns the number of rows removed.
+     */
+    invalidate(filter) {
+        const clauses = [];
+        const args = [];
+        if (filter.providerNamespace) {
+            clauses.push('provider_namespace = ?');
+            args.push(filter.providerNamespace);
+        }
+        if (filter.callType) {
+            clauses.push('call_type = ?');
+            args.push(filter.callType);
+        }
+        if (clauses.length === 0 && !filter.all)
+            throw new Error('EvalCache.invalidate: pass providerNamespace, callType, or all: true');
+        const where = clauses.length > 0 ? ` WHERE ${clauses.join(' AND ')}` : '';
+        return this.db.prepare(`DELETE FROM eval_responses${where}`).run(...args).changes;
+    }
+    /** Cached row count per provider namespace and call type. */
+    summary() {
+        return (this.db.prepare('SELECT provider_namespace AS providerNamespace, call_type AS callType, COUNT(*) AS rows FROM eval_responses GROUP BY provider_namespace, call_type ORDER BY provider_namespace, call_type').all());
+    }
+    /** Row count for diagnostics. */
+    rowCount() {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM eval_responses').get();
+        return row.cnt;
+    }
+    close() {
+        this.db.close();
+    }
+}
+exports.EvalCache = EvalCache;
+class KeyPool {
+    slots;
+    maxPerKey;
+    nextIndex = 0;
+    waiters = [];
+    constructor(apiKeys, maxPerKey = 1) {
+        if (apiKeys.length === 0)
+            throw new Error('KeyPool requires at least one API key');
+        this.slots = apiKeys.map((key, i) => ({
+            key,
+            inFlight: 0,
+            disabled: false,
+            cooldownUntil: 0,
+            label: `key-${i + 1}`,
+        }));
+        this.maxPerKey = maxPerKey;
+    }
+    get size() { return this.slots.filter(s => !s.disabled).length; }
+    get totalInFlight() { return this.slots.reduce((n, s) => n + s.inFlight, 0); }
+    findAvailable(now) {
+        for (let i = 0; i < this.slots.length; i++) {
+            const idx = (this.nextIndex + i) % this.slots.length;
+            const slot = this.slots[idx];
+            if (!slot.disabled && slot.inFlight < this.maxPerKey && now >= slot.cooldownUntil) {
+                this.nextIndex = (idx + 1) % this.slots.length;
+                return slot;
+            }
+        }
+        return undefined;
+    }
+    lease(slot) {
+        slot.inFlight++;
+        let released = false;
+        return {
+            key: slot.key,
+            label: slot.label,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                slot.inFlight = Math.max(0, slot.inFlight - 1);
+                this.drainWaiters();
+            },
+        };
+    }
+    /**
+     * Acquire a key slot. Returns { key, label, release }.
+     * release() is idempotent and should still be called in a finally block.
+     */
+    async acquire() {
+        if (this.size === 0) {
+            throw new Error('All API keys have been permanently disabled (401/403)');
+        }
+        const slot = this.findAvailable(Date.now());
+        if (slot)
+            return this.lease(slot);
+        // All usable keys are busy or cooling down. Queue and immediately drain so
+        // cooldown-only waits get a wake-up timer even when no in-flight request
+        // remains to call release().
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+            this.drainWaiters();
+        });
+    }
+    rejectAllWaiters(error) {
+        while (this.waiters.length > 0) {
+            this.waiters.shift()?.reject(error);
+        }
+    }
+    drainWaiters() {
+        if (this.waiters.length === 0)
+            return;
+        if (this.size === 0) {
+            this.rejectAllWaiters(new Error('All API keys have been permanently disabled (401/403)'));
+            return;
+        }
+        const now = Date.now();
+        const slot = this.findAvailable(now);
+        if (slot) {
+            const waiter = this.waiters.shift();
+            if (waiter)
+                waiter.resolve(this.lease(slot));
+            if (this.waiters.length > 0)
+                queueMicrotask(() => this.drainWaiters());
+            return;
+        }
+        // All usable keys are still busy or in cooldown. Busy keys will wake us on
+        // release; cooldown-only waits need a timer for the nearest expiry.
+        const nearestCooldown = this.slots
+            .filter(s => !s.disabled && s.inFlight < this.maxPerKey && s.cooldownUntil > now)
+            .reduce((min, s) => Math.min(min, s.cooldownUntil), Infinity);
+        if (nearestCooldown < Infinity) {
+            setTimeout(() => this.drainWaiters(), Math.max(0, nearestCooldown - now) + 10);
+        }
+    }
+    /**
+     * Report an HTTP error for a key. Handles cooldown and permanent disable.
+     * Call this BEFORE release() if the error warrants special handling.
+     */
+    reportError(label, statusCode, retryAfterMs) {
+        const slot = this.slots.find(s => s.label === label);
+        if (!slot)
+            return;
+        if (statusCode === 401 || statusCode === 403) {
+            slot.disabled = true;
+            process.stderr.write(`[KeyPool] ${label} permanently disabled (HTTP ${statusCode})\n`);
+            if (this.slots.every(s => s.disabled)) {
+                const error = new Error('All API keys have been permanently disabled (401/403)');
+                this.rejectAllWaiters(error);
+                throw error;
+            }
+        }
+        else if (statusCode === 429) {
+            const cooldown = retryAfterMs !== undefined && Number.isFinite(retryAfterMs) && retryAfterMs >= 0
+                ? retryAfterMs
+                : 60_000;
+            slot.cooldownUntil = Date.now() + cooldown;
+            process.stderr.write(`[KeyPool] ${label} rate-limited, cooldown ${cooldown}ms\n`);
+        }
+        this.drainWaiters();
+    }
+}
+exports.KeyPool = KeyPool;
+/**
+ * Run a pooled operation with a fresh key acquisition on every attempt.
+ * This is intentionally outside chatCall's internal retries so a 429/401 on
+ * one credential cannot pin all retries to the same bad key.
+ */
+async function runWithKeyPoolRetries(pool, maxAttempts, fn, backoffMs = attempt => Math.min(1000 * 2 ** attempt, 8000)) {
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error('maxAttempts must be an integer >= 1');
+    }
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const lease = await pool.acquire();
+        try {
+            const value = await fn({ key: lease.key, label: lease.label }, attempt);
+            return { value, attempts: attempt };
+        }
+        catch (error) {
+            lastError = error;
+        }
+        finally {
+            lease.release();
+        }
+        if (attempt < maxAttempts) {
+            const delay = backoffMs(attempt);
+            if (delay > 0)
+                await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Pooled API failed after ${maxAttempts} attempts: ${String(lastError ?? 'unknown')}`);
+}
+/** Parse Retry-After as either delta-seconds or an HTTP date. */
+function parseRetryAfterMs(value, nowMs = Date.now()) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const at = Date.parse(value);
+    if (!Number.isFinite(at))
+        return undefined;
+    return Math.max(0, at - nowMs);
+}
+/** Resolve runner concurrency, defaulting to usable judge-key capacity (capped at 3). */
+function resolveWorkerConcurrency(configured, activeJudgeKeys, defaultCap = 3) {
+    if (!Number.isInteger(activeJudgeKeys) || activeJudgeKeys < 1) {
+        throw new Error('activeJudgeKeys must be an integer >= 1');
+    }
+    if (configured === undefined || configured.trim() === '') {
+        return Math.min(defaultCap, activeJudgeKeys);
+    }
+    const parsed = Number(configured);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`--concurrency must be an integer >= 1 (got ${configured})`);
+    }
+    return parsed;
+}
+// ─── Bounded Worker Pool ───────────────────────────────────────────────────────
+/**
+ * Simple bounded worker pool. Runs up to `concurrency` tasks at once.
+ * Unlike p-limit, this is zero-dependency and supports our needs.
+ */
+class WorkerPool {
+    concurrency;
+    running = 0;
+    queue = [];
+    constructor(concurrency) {
+        if (concurrency < 1)
+            throw new Error('WorkerPool concurrency must be >= 1');
+        this.concurrency = concurrency;
+    }
+    /**
+     * Run a task when a slot is available.
+     * The returned promise resolves/rejects with the task's result.
+     */
+    async run(fn) {
+        if (this.running >= this.concurrency) {
+            await new Promise(resolve => this.queue.push(resolve));
+        }
+        this.running++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.running--;
+            const next = this.queue.shift();
+            if (next)
+                next();
+        }
+    }
+}
+exports.WorkerPool = WorkerPool;
+// ─── Cache Path Resolution ─────────────────────────────────────────────────────
+/**
+ * Resolve the cache scope that becomes part of the eval-cache key.
+ *
+ * Default: the effective routing session (`x-opencode-session:<session>`). The
+ * session header affects backend routing, so it is part of cache identity and a
+ * degraded routed session cannot poison later healthy runs (2026-09-18 incident).
+ *
+ * Benchmark runs that deliberately want cross-run reuse pin a canonical scope
+ * via RENOR_QA_CACHE_SCOPE. The canonical registry is maintained by the
+ * benchmark-infrastructure work (PR #67); the routing session stays unique for
+ * health even when cache identity is shared.
+ */
+function resolveCacheScope(args) {
+    const explicit = (args.explicit ?? '').trim();
+    return explicit ? `scope:${explicit}` : `x-opencode-session:${args.session}`;
+}
+/**
+ * Resolve the eval cache path from environment.
+ * RENOR_EVAL_CACHE=off → null (disabled).
+ * RENOR_EVAL_CACHE=on or unset → default path.
+ * RENOR_EVAL_CACHE=/path → explicit path.
+ */
+function resolveEvalCachePath(env = process.env) {
+    const raw = env.RENOR_EVAL_CACHE;
+    if (raw === 'off' || raw === '0')
+        return null;
+    if (!raw || raw === 'on') {
+        return node_path_1.default.join(env.HOME ?? '.', '.local', 'share', 'renor', 'eval-cache.db');
+    }
+    return node_path_1.default.resolve(raw);
+}
+/**
+ * Parse judge API keys from environment.
+ * Supports JUDGE_API_KEY_1, JUDGE_API_KEY_2, ... or falls back to single key.
+ */
+function resolveJudgeKeys(env, fallbackKeyEnv, prefixEnv) {
+    const keys = [];
+    const prefixes = [prefixEnv, fallbackKeyEnv, 'JUDGE_API_KEY', 'OLLAMA_MAX_KEY', 'OLLAMA_API_KEY'].filter(Boolean);
+    const seenPrefixes = new Set();
+    for (const prefix of prefixes) {
+        if (seenPrefixes.has(prefix))
+            continue;
+        seenPrefixes.add(prefix);
+        for (let i = 1; i <= 10; i++) {
+            const val = env[`${prefix}_${i}`];
+            if (val && val.trim())
+                keys.push(val.trim());
+        }
+        if (keys.length > 0)
+            return [...new Set(keys)];
+    }
+    // Check if prefixEnv or fallbackKeyEnv holds a comma-separated list or single key
+    const single = (prefixEnv && env[prefixEnv]) || env[fallbackKeyEnv];
+    if (single && single.trim()) {
+        const split = single.split(',').map(s => s.trim()).filter(Boolean);
+        if (split.length > 0)
+            return split;
+    }
+    return [];
+}