llm-relay 0.62.0 → 0.63.0

package/dist/refusal-interpretation.js

@@ -6,7 +6,6 @@ import { tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { WriteBehindTimer } from "./write-behind.js";
 import { FACT_KINDS } from "./target-facts.js";
-/** Turn a stored template into the concrete scope for the request that matched it. */
 export function materializeScope(template, provider, credentialId, model) {
     switch (template.kind) {
         case "attempt":
@@ -20,8 +19,6 @@ export function materializeScope(template, provider, credentialId, model) {
         case "model":
             return { kind: "model", model };
         case "group":
-            // The triggering model is always included: it demonstrably exhibits the fact, and a group
-            // verdict that excluded its own evidence would be incoherent.
             return {
                 kind: "group",
                 provider,
@@ -30,31 +27,18 @@ export function materializeScope(template, provider, credentialId, model) {
             };
     }
 }
-/**
- * How long a rejection is honoured. Long, because "this message is noise" is a slow-moving fact —
- * but not forever, so a mistaken reject heals on its own rather than needing a file edited by hand.
- */
 export const IGNORED_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-/**
- * The longest reset any of these providers publishes. Beyond it a value is a parse artifact or a
- * mistaken assertion, and believing it would strand a deployment far past any real window.
- */
 const MAX_RESET_MS = 7 * 24 * 60 * 60 * 1000;
 let _store = null;
 let _path = null;
-// The stat token the currently-memoized `_store` was loaded from (or null when `_store` is null).
-// Keyed by normalized path so two syntactic aliases of one file coalesce, exactly like `keystore.ts`.
 let _token = null;
 const writer = new WriteBehindTimer();
-// Vitest workers can reuse a PID across separate runs. Keep the test store in a fresh,
-// process-local namespace so a prior run can never make a new suite observe stale verdicts.
 const testPath = process.env.VITEST === undefined
     ? null
     : join(tmpdir(), `llm-relay-test-interpretations-${process.pid}-${randomUUID()}.json`);
 if (testPath !== null) {
     process.once("exit", () => rmSync(testPath, { force: true }));
 }
-/** Cap on retained unknown signatures — a misbehaving backend must not grow this without bound. */
 const MAX_UNKNOWN = 200;
 function defaultPath() {
     if (process.env.VITEST !== undefined) {
@@ -62,39 +46,10 @@ function defaultPath() {
     }
     return relayStatePath("config", ["refusal-interpretations.json"]);
 }
-/**
- * Reduce a refusal message to its invariant shape.
- *
- * Everything that varies between two occurrences of the SAME refusal has to go, or the table gets
- * one entry per request: uuids and account ids (NIM names both), numbers (credit balances, token
- * counts) and urls (upgrade links carry per-request refs).
- *
- * ⚠ **The message text itself must survive.** An earlier version also replaced every quoted string
- * with a placeholder, on the theory that quoted model names are noise. Against a live pool that
- * erased the entire payload: the Anthropic front hands this the relay's own wrapper —
- * `openai backend HTTP 402: {"error":"You have depleted your monthly included credits…"}` — whose
- * message is *inside* quotes, so all 15 members of a real `pool/xhigh` normalized to
- * `openai backend http <n>: {<name>:<name>}` and nothing could ever match. Quoted model names are
- * harmless: the model is already part of the key.
- *
- * ⚠ For the same reason the JSON hunt digs through a WRAPPER. A body is not always JSON at the top
- * level — the relay's own error envelope prefixes it with prose — so a failed parse falls back to
- * the first embedded object rather than giving up.
- *
- * The result is kept as readable TEXT rather than a hash: a human or an agent has to read these to
- * research them, and a hex digest would make the store unreviewable for no benefit.
- */
 export function normalizeRefusalMessage(body) {
     if (typeof body !== "string")
         return "";
     let text = body.length > 4096 ? body.slice(0, 4096) : body;
-    // Unwrap to a FIXPOINT, because a refusal often arrives as an envelope around an envelope: the
-    // walk lane hands this the relay's own anthropic error JSON, whose `error.message` is the
-    // relay's `openai backend HTTP <n>: …` wrapper, whose tail is the provider's (possibly
-    // truncated) payload. One extraction round used to stop at the wrapper, so the SAME provider
-    // condition normalized differently per lane and needed two accepts — the lane-split defect
-    // (docs/eligibility-triage-2026-08-29.md finding 1). Three real layers exist; the bound is a
-    // formality against a pathological body.
     for (let round = 0; round < 4; round++) {
         const next = stripRelayWrapper(extractMessage(text) ?? text);
         if (next === text)
@@ -111,21 +66,12 @@ export function normalizeRefusalMessage(body) {
         .trim()
         .slice(0, 240);
 }
-/**
- * The relay's OWN error wrapper — `backend.ts` synthesizes `openai backend HTTP <status><hint>: `
- * in front of a provider body it forwards. Stripping it is parsing our own fixed grammar, never
- * provider prose. The pattern accepts both the raw form (digits, uppercase HTTP) and the
- * historical STORED form (already lowercased and redacted to `<n>`), because the store migration
- * re-normalizes old rows through this same function.
- */
 const RELAY_WRAPPER_PREFIX = /^openai backend http (?:\d{3}|<n>)(?: — model "[^"]{0,256}" is not served by provider "[^"]{0,128}" \([^)]{0,200}\))?:\s*/i;
 function stripRelayWrapper(text) {
     return text.replace(RELAY_WRAPPER_PREFIX, "");
 }
-/** The human-readable message inside a body, whether it is JSON, wrapped JSON, or neither. */
 function extractMessage(text) {
     const candidates = [text];
-    // A wrapper: prose, then the real payload. Take from the first brace or bracket.
     const brace = text.search(/[[{]/);
     if (brace > 0)
         candidates.push(text.slice(brace));
@@ -136,20 +82,10 @@ function extractMessage(text) {
                 return found;
         }
         catch {
-            // Not parseable — try the next candidate.
         }
     }
     return fieldFromUnparseable(text);
 }
-/**
- * Deterministic last resort for text whose JSON payload does NOT parse. The relay's wrapper caps
- * the embedded provider body at 300 chars, so a long body arrives cut mid-string and the parse
- * path above learns nothing — which left the whole wrapper as the signature on the walk lane
- * while the direct lane extracted the bare message (the lane-split defect). Field priority
- * mirrors `findMessage`. A value cut at end-of-text (no closing quote) is accepted, because that
- * is exactly what truncation produces; the signature's own 240-char cap then makes both lanes
- * converge on the same prefix.
- */
 function fieldFromUnparseable(text) {
     for (const field of ["message", "detail", "error", "title"]) {
         const re = new RegExp(`"${field}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)(?:"|$)`);
@@ -159,14 +95,12 @@ function fieldFromUnparseable(text) {
     }
     return null;
 }
-/** JSON string-escape decoding, so the truncated lane matches what `JSON.parse` yields. */
 function unescapeJsonString(value) {
     const simple = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
     return value
         .replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
         .replace(/\\(.)/g, (_, ch) => simple[ch] ?? ch);
 }
-/** Depth-first hunt for the message field an OpenAI-shaped error envelope carries. */
 function findMessage(v, depth = 0) {
     if (depth > 6)
         return null;
@@ -194,31 +128,13 @@ function findMessage(v, depth = 0) {
     }
     return null;
 }
-/**
- * A reset the refusal BODY stated, in ms — or null.
- *
- * `Retry-After` is a header, and several providers put the same fact in the body instead: Google's
- * `google.rpc.RetryInfo` carries `"retryDelay": "3600s"` inside the error details, which is the
- * only place Gemini says when a spent quota comes back. Without this the relay falls back to a
- * kind's default TTL and re-probes on a schedule it invented, which for a 5-hourly or weekly quota
- * means hours of pointless attempts.
- *
- * ⚠ Same rule as `parseStatedContextLimit`: only an EXPLICIT statement counts. Nothing is derived
- * from how long a request took, how many failed, or what a window "usually" is — a store whose
- * value is that it holds measurements must not accept a guess. If nothing parses, the kind's TTL
- * applies and the relay simply re-checks sooner than it strictly needed to, which is the safe
- * direction.
- */
 export function parseStatedResetMs(body) {
     if (typeof body !== "string" || body.length === 0)
         return null;
     const text = body.length > 8192 ? body.slice(0, 8192) : body;
     const patterns = [
-        // google.rpc.RetryInfo — "retryDelay": "27s" / "1.5s" / "3600s"
         { re: /"retry[_-]?delay"\s*:\s*"?(\d+(?:\.\d+)?)s"?/i, scale: 1000 },
-        // Common JSON spellings of the Retry-After header's seconds form.
         { re: /"retry[_-]?after(?:[_-]?seconds)?"\s*:\s*"?(\d+(?:\.\d+)?)"?/i, scale: 1000 },
-        // Prose, as a last resort: "try again in 45 seconds" / "retry in 5 minutes".
         { re: /(?:try|retry)\s+again\s+in\s+(\d+(?:\.\d+)?)\s*(?:seconds?|secs?|s)\b/i, scale: 1000 },
         { re: /(?:try|retry)\s+again\s+in\s+(\d+(?:\.\d+)?)\s*(?:minutes?|mins?)\b/i, scale: 60_000 },
         { re: /(?:try|retry)\s+again\s+in\s+(\d+(?:\.\d+)?)\s*(?:hours?|hrs?)\b/i, scale: 3_600_000 },
@@ -228,20 +144,11 @@ export function parseStatedResetMs(body) {
         if (!m?.[1])
             continue;
         const ms = Number(m[1]) * scale;
-        // A week is the longest window any of these providers publish; beyond that it is a parse
-        // artifact, and believing it would strand a deployment far past any real reset.
         if (Number.isFinite(ms) && ms > 0 && ms <= MAX_RESET_MS)
             return Math.round(ms);
     }
     return null;
 }
-/**
- * Apply a reviewed reset rule to one response body.
- *
- * Ranked below anything the response itself states — see `resolveReset` in `server.ts`. A
- * `field` rule reads THIS response, so it is still a measurement; a `fixed` rule is the reviewer's
- * knowledge of a window and is the last word before falling back to the kind's TTL.
- */
 export function applyResetRule(rule, body) {
     if (!rule)
         return null;
@@ -250,8 +157,6 @@ export function applyResetRule(rule, body) {
     const raw = findField(body, rule.field);
     if (raw === null)
         return null;
-    // Providers write durations as "3600s", "3600", or a number. Seconds is the universal unit here
-    // (Retry-After, RetryInfo, every JSON spelling seen), so anything without a unit is seconds.
     const m = /(\d+(?:\.\d+)?)\s*(ms|s|m|h)?/i.exec(String(raw));
     if (!m?.[1])
         return null;
@@ -259,7 +164,6 @@ export function applyResetRule(rule, body) {
     const ms = Number(m[1]) * scale;
     return Number.isFinite(ms) && ms > 0 && ms <= MAX_RESET_MS ? Math.round(ms) : null;
 }
-/** Deep lookup of a JSON key by NAME, wrapper-tolerant. Returns the first scalar found. */
 function findField(body, field) {
     const parse = (text) => {
         try {
@@ -291,105 +195,33 @@ function findField(body, field) {
     };
     return walk(parse(body.length > 8192 ? body.slice(0, 8192) : body));
 }
-/**
- * Meaning read from a SELF-DESCRIBING error payload, rather than from prose.
- *
- * Some providers publish the fact in a structured, versioned envelope that names its own schema.
- * Google's is the one in use here: a 429 carries `google.rpc.QuotaFailure` whose `quotaId` states
- * both the window and what the limit is counted against —
- * `GenerateRequestsPerDayPerProjectPerModel-FreeTier` says, unambiguously, that this is a *daily*
- * allowance counted *per model* on the *free tier*. No wording to interpret.
- *
- * ⚠ This is NOT a per-provider switch, which this project refuses elsewhere (`catalog.ts` uses a
- * generic field-alias list; `authEnv.ts` refuses to guess). The dispatch key is the payload's own
- * `@type` URL — the message declares which schema it is speaking, and we read only schemas we
- * understand. A provider adopting `google.rpc` gets this for free; one that does not is unaffected.
- *
- * Ranked ABOVE the prose seeds and BELOW an accepted human verdict: structured evidence beats a
- * pattern guess, and an operator's explicit decision beats both.
- */
 function interpretStructured(status, body) {
     if (!/google\.rpc\.QuotaFailure/.test(body))
         return null;
-    // The quotaId is the load-bearing field; read it without trusting the surrounding shape, because
-    // a partial or wrapped body must degrade to "learned nothing" rather than throwing.
     const m = /"quotaId"\s*:\s*"([^"]{1,200})"/.exec(body);
     const quotaId = m?.[1];
     if (!quotaId)
         return null;
-    // WINDOW → which fact this is. Per-minute/second is throughput; per-hour and longer is an
-    // allowance. This is the rate-limit-vs-quota distinction read off a field instead of inferred
-    // from wording, which is exactly where reading wording got it wrong before.
     const perShort = /Per(?:Second|Minute)/i.test(quotaId);
     const perLong = /Per(?:Hour|Day|Week|Month)/i.test(quotaId);
     if (!perShort && !perLong)
         return null;
     const kind = perShort ? "rate-limited" : "allowance-exhausted";
-    // SCOPE → what the limit is counted against. A model dimension is always attempt-local. A
-    // recognized credential dimension is credential-wide; an unfamiliar dimension stays narrow.
     const scope = /PerModel/i.test(quotaId)
         ? { kind: "attempt" }
         : /Per(?:Project|User|Client|Key)/i.test(quotaId)
             ? { kind: "credential" }
             : { kind: "attempt" };
-    // A 429 is the only status this shape is published on; anything else naming QuotaFailure is not
-    // something we have seen and should not be guessed at.
     return status === 429 || status === 403 ? { class: kind, scope } : null;
 }
-/** The lookup key. Per (provider, model, normalized message) — see the header for why all three. */
 export function refusalSignature(provider, model, status, body) {
     return `${provider}|${model ?? "-"}|${status}|${normalizeRefusalMessage(body)}`;
 }
-/**
- * A short, stable digest of a signature — the address `llm-relay eligibility` prints beside each
- * pending item and `--sig` resolves against.
- *
- * The queue is addressed by list POSITION for typing convenience, but positions SHIFT between
- * invocations: the sort is count-then-recency, so any new refusal arriving between `propose` and
- * `accept` can silently move item N onto a different signature — which landed a verdict on the
- * wrong refusal twice (owner decision 2026-08-28: accept takes a digest beside the index). The
- * digest names the signature itself, so it survives any reordering. Ten hex characters of SHA-256:
- * far beyond collision range for a queue capped at MAX_UNKNOWN entries, and short enough to retype.
- */
 export function signatureDigest(signature) {
     return createHash("sha256").update(signature, "utf8").digest("hex").slice(0, 10);
 }
-/**
- * Interpretations shipped with the relay, each derived from a refusal observed first-party against
- * a real account (probed 2026-08-08). These bind without review: they are deterministic code in
- * version control, and an operator who disagrees can override the entry.
- *
- * ⚠ **This list is a BOOTSTRAP, not the mechanism.** Reaching for a new seed every time an
- * unfamiliar message appears means the relay's author learned something and the relay did not —
- * and it is the reflex this two-tier design exists to replace. A researched interpretation carries
- * the same information, is reviewed the same way, and a future session inherits it without a
- * release. Add a seed only for a message shape common enough that every install should start
- * knowing it.
- *
- * ⚠ These are matched as PATTERNS against the normalized message, not as exact signatures, because
- * a seed has to cover a provider it has never been run against. That is a deliberate exception to
- * the per-model keying rule above and the only one — a seed is reviewed source, whereas a
- * researched verdict is a model's opinion and gets the conservative key.
- *
- * ⚠ **`allowance-exhausted` is not a cost verdict.** See `target-facts.ts` — it means the
- * deployment is free and currently spent, and it must never evict anything from a free pool.
- */
 export const SEED_INTERPRETATIONS = [
     {
-        // ⚠ **A quota is not a rate limit, and the two must not share a cooldown.** FIRST in this list
-        // on purpose — first match wins, and the rate-limit seed below must never see quota wording.
-        //
-        // A rate limit is throughput (requests per minute) and resets in seconds to minutes, which is
-        // why `rate-limited` carries a 2-minute TTL. A quota is an ALLOWANCE over a long window: a
-        // 5-hourly or weekly grant on a free tier, or a monthly credit balance. Classifying one as the
-        // other means re-probing a spent weekly quota every two minutes for days. The rate-limit
-        // pattern below matched the word "quota" in 0.28.0 and did exactly that.
-        //
-        // Resolves to `allowance-exhausted`, the same kind HuggingFace's credit balance uses and for
-        // the same reason: the deployment is still FREE, it is simply spent until the window rolls
-        // over. Gemini's wording — "you exceeded your current quota, please check your plan and
-        // billing details" — names the plan, not the model, so it is the project's allowance and every
-        // deployment behind that key is equally spent.
         status: (s) => s === 429 || s === 403,
         pattern: /exceeded\s+your\s+current\s+quota|quota\s+exceeded[^.]{0,40}\b(?:plan|billing|project)|check\s+your\s+plan\s+and\s+billing|\b(?:daily|weekly|monthly|hourly)\s+quota\s+(?:exceeded|exhausted|reached)|out\s+of\s+quota/,
         class: "allowance-exhausted",
@@ -397,8 +229,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated QUOTA exhaustion (long window); free but spent until the allowance refreshes",
     },
     {
-        // HuggingFace: "You have depleted your monthly included credits. Purchase pre-paid credits…"
-        // A BALANCE — the account's, so it covers every model behind that key.
         status: (s) => s === 402,
         pattern: /deplet\w*\s+your\s+(?:monthly\s+)?(?:included\s+)?credits|insufficient\s+credits|purchase\s+(?:pre-?paid\s+)?credits|out\s+of\s+credits/,
         class: "allowance-exhausted",
@@ -406,9 +236,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated credit balance; free but spent until it refreshes",
     },
     {
-        // Ollama Cloud: "this model requires a subscription, upgrade for access" / "requires both a
-        // Pro, Max, or Team plan and extra usage". About THAT MODEL under a working credential, so it
-        // must not block the provider's other models.
         status: (s) => s === 403,
         pattern: /requires?\s+(?:both\s+)?an?\s+[\w, ]*\bsubscription\b|requires?\s+(?:both\s+)?an?\s+[\w, ]*\bplan\b|upgrade\s+for\s+access/,
         class: "subscription-required",
@@ -416,9 +243,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated plan gating on one model; the credential itself is fine",
     },
     {
-        // HuggingFace: "The requested model 'x' does not exist." / OpenAI-compatible model_not_found.
-        // NIM: "Function '<uuid>': Not found for account '<id>'" — the serving function is gone. It
-        // names an account but is a fact about the deployment, not the credential.
         status: (s) => s === 400 || s === 404,
         pattern: /not\s+found\s+for\s+account/,
         class: "not-servable",
@@ -433,12 +257,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated non-existence; catalog rot",
     },
     {
-        // NVIDIA NIM retires models with HTTP 410 and end-of-life wording (observed on this machine
-        // 2026-08-07: deepseek-v4-pro/-flash). Status and wording must AGREE the model is gone: a bare
-        // 410 stays uninterpreted and queues for research, and this wording on a non-410 status must
-        // not retire a live model (an advisory notice or status-page quote MENTIONING a retirement is
-        // still just text). Phrase set fork-validated in freellmapi's retirement classifier — on a 410
-        // even the softer "no longer available" wording is status-agreed gone.
         status: (s) => s === 410,
         pattern: /end[\s-]of[\s-]life|has\s+been\s+(?:retired|decommissioned|sunset|removed|discontinued|deprecated)|no\s+longer\s+(?:available|offered|supported)|is\s+deprecated|was\s+removed/,
         class: "not-servable",
@@ -446,14 +264,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated end-of-life on a gone-shaped status; the deployment is permanently retired",
     },
     {
-        // A credential the provider says is bad — "invalid api key", "authentication failed". A fact
-        // about the KEY, so it covers every deployment behind it: without this, each model on that
-        // provider independently discovers the same 401 and expires on its own clock.
-        //
-        // ⚠ Requires the message to state it. A BARE 401/403 stays on the breaker's credential axis and
-        // produces no fact at all, because it is equally an entitlement wall on one model under a
-        // perfectly good key — the false accusation `key-checker.ts` exists to avoid. This seed fires
-        // on wording about the credential, never on the status alone.
         status: (s) => s === 401 || s === 403,
         pattern: /invalid\s+(?:api\s+)?(?:key|token|credentials?)|authentication\s+failed|incorrect\s+api\s+key|api\s+key\s+(?:not\s+valid|is\s+invalid|expired|revoked)|unauthorized:\s*invalid/,
         class: "credential-invalid",
@@ -461,13 +271,6 @@ export const SEED_INTERPRETATIONS = [
         note: "stated bad credential; covers every deployment behind that key",
     },
     {
-        // A 429 that names the ACCOUNT, ORGANIZATION or KEY rather than the model — every sibling
-        // behind that credential is equally throttled, so discovering it once per model is the waste.
-        //
-        // ⚠ Narrow on purpose. An ordinary 429 is one deployment's back-pressure and must stay on the
-        // breaker's per-target cooldown, which handles it well; only wording that states an
-        // account-level limit belongs here. Matching plain "rate limit exceeded" would demote whole
-        // providers on routine throttling — worse than the problem.
         status: (s) => s === 429,
         pattern: /(?:account|organization|organisation|project|api\s+key|workspace)[^.]{0,40}\b(?:rate\s*limit|requests?\s+per)|\brate\s*limit[^.]{0,24}\bfor\s+(?:your|this)\s+(?:account|organization|organisation|project|key)/,
         class: "rate-limited",
@@ -610,8 +413,6 @@ function migrateV1(parsed) {
             if (!validV1Unknown(entry) || !unknownMatchesSignature(signature, entry))
                 continue;
             const migrated = { ...entry };
-            // An old provider proposal could otherwise be accepted later and silently acquire the old,
-            // over-broad meaning. It must be researched again under v2's explicit scopes.
             if (migrated.proposed?.scope?.kind === "provider")
                 delete migrated.proposed;
             else if (migrated.proposed?.scope?.kind === "group") {
@@ -629,8 +430,6 @@ function migrateV1(parsed) {
             if (!signatureParts(signature) || !validV1Interpretation(entry))
                 continue;
             if (entry.scope.kind === "provider") {
-                // v1 provider meant “the credential”, but it did not name the credential. Requeue rather
-                // than guessing a v2 scope or letting it keep binding.
                 const pending = entry.acceptedAt === undefined ? null : asPending(signature, entry);
                 if (pending)
                     unknown[signature] = pending;
@@ -673,30 +472,7 @@ function observeInterpretationStore(path) {
         return code === undefined ? { kind: "error" } : { kind: "error", errno: code };
     }
 }
-/** The one empty store. Absent, unreadable and corrupt all resolve to it. */
 const emptyStore = () => ({ version: 2, confirmed: {}, unknown: {}, ignored: {} });
-/**
- * Re-key every stored signature through the CURRENT normalizer.
- *
- * The signature embeds the normalized message, so any improvement to `normalizeRefusalMessage`
- * silently orphans every row keyed under the old form: fresh traffic produces the new form,
- * nothing matches, and an operator's accepted verdicts stop binding — exactly what the lane-split
- * fix would have done to the 192 verdicts accepted on 2026-08-29. This re-normalizes each key's
- * message part (the stored form is the normalizer's own output, which the normalizer converges on
- * idempotently) and re-keys the row.
- *
- * Merge rules on collision (two historical forms of one condition converging):
- * - confirmed: the LATER acceptance wins — both are operator-declared, the newer is the operator's
- *   most recent word. Seeds carry no acceptedAt and rank as 0.
- * - unknown: counts sum, the window spans both, the fresher sample wins — `mergeStores`' rule.
- *   A row converging onto a confirmed signature is RESOLVED (dropped), and one converging onto an
- *   ignored signature stays suppressed — mirroring what `recordUnknownRefusal` would do.
- * - ignored: latest `at` wins.
- *
- * Runs inside `readStoreFile`, so BOTH readers (`load`, and the lost-update re-read in `persist`)
- * see migrated keys and a merge can never resurrect an old-keyed row. Idempotent: a migrated
- * store re-keys to itself.
- */
 function migrateSignatures(store) {
     const rekey = (sig) => {
         const parts = signatureParts(sig);
@@ -729,14 +505,11 @@ function migrateSignatures(store) {
         const parts = signatureParts(next);
         if (!parts)
             continue;
-        // `unknownMatchesSignature` requires the row's normalized text to equal the key's message
-        // part, so a re-keyed row must carry the re-normalized form or the NEXT read drops it.
         const renormed = next === sig ? entry : { ...entry, normalized: parts.sample, sample: parts.sample };
         unknown[next] = mergeUnknownPair(renormed, unknown[next]);
     }
     return { version: 2, confirmed, unknown, ignored };
 }
-/** Two queue rows for one signature — counts sum, the window spans both, the fresher sample wins. */
 function mergeUnknownPair(incoming, existing) {
     if (!existing)
         return incoming;
@@ -747,11 +520,6 @@ function mergeUnknownPair(incoming, existing) {
         lastSeen: Math.max(incoming.lastSeen, existing.lastSeen),
     };
 }
-/**
- * Parse a store file. The ONE parser: `load` reads through it, and so does the lost-update
- * re-read inside `persist` — two copies of the acceptance rules is how one process comes to
- * admit a row the other silently drops.
- */
 function readStoreFile(normalizedPath) {
     try {
         const parsed = JSON.parse(readFileSync(normalizedPath, "utf8"));
@@ -792,65 +560,33 @@ function readStoreFile(normalizedPath) {
 function load(path) {
     const normalizedPath = resolve(path);
     const observation = observeInterpretationStore(normalizedPath);
-    // If we have a memoized store for this path:
-    // - If _token is null (file didn't exist when we loaded), we can only return the memoized
-    //   store if the file is STILL absent. If the file now exists externally, we must re-read.
-    // - If _token matches the current file's token, return the memoized store.
     if (_store !== null &&
         _path === normalizedPath &&
         ((_token === null && observation.kind === "absent") ||
             (observation.kind === "present" && observation.token === _token))) {
         return _store;
     }
-    // Need to (re)load. Absent, unreadable and corrupt all degrade to an empty store: unlike a
-    // keystore row, every interpretation here is re-learnable and the SEEDS live in source, so
-    // nothing binding is lost. `persist` re-reads through the same parser, so the two paths cannot
-    // come to disagree about what a stored file means.
     const result = observation.kind === "present" ? readStoreFile(normalizedPath) : emptyStore();
-    // Memoize the loaded store and its stat token.
     _store = result;
     _path = normalizedPath;
     _token = observation.kind === "present" ? observation.token : null;
     return _store;
 }
-/**
- * Merge an externally-modified file into the in-memory store before overwriting.
- *
- * Merge rules (justified by provenance):
- * - A `confirmed` row is an OPERATOR-DECLARED acceptance and must never be dropped by
- *   another process's stale snapshot. We always take the union of confirmed signatures,
- *   and for a signature present in both, the disk version wins (the operator explicitly
- *   accepted it in another process).
- * - `unknown` rows are queue entries and may be unioned. We keep the entry with the
- *   higher `lastSeen` (fresher sample wins), and merge counts if the signature appears
- *   in both.
- * - A signature that moved from `unknown` to `confirmed` on disk must not be resurrected
- *   into `unknown` by an in-memory writer that still had it pending. We handle this by
- *   always preferring `confirmed` over `unknown` for the same signature.
- * - `ignored` entries are unioned by signature, keeping the latest `at` timestamp.
- */
 function mergeStores(disk, memory) {
-    // Start with disk's confirmed (operator-declared wins)
     const confirmed = { ...disk.confirmed };
-    // Then layer memory's confirmed — but disk's wins on conflicts
     for (const [sig, entry] of Object.entries(memory.confirmed)) {
         if (!(sig in confirmed))
             confirmed[sig] = entry;
     }
-    // Unknown: union, preferring confirmed over unknown for same signature
     const unknown = { ...disk.unknown };
     for (const [sig, memEntry] of Object.entries(memory.unknown)) {
         if (sig in confirmed)
-            continue; // confirmed wins — don't resurrect into unknown
+            continue;
         const diskEntry = unknown[sig];
         if (!diskEntry) {
             unknown[sig] = memEntry;
         }
         else {
-            // Fresher sample wins the body; the window and the count span both observers.
-            // ⚠ COPY, never mutate in place: the chosen entry belongs to `_store` (or to the disk
-            // store we just parsed), and writing the summed count back into it would inflate the
-            // count again on the next persist that follows another external write.
             const fresher = memEntry.lastSeen >= diskEntry.lastSeen ? memEntry : diskEntry;
             unknown[sig] = {
                 ...fresher,
@@ -860,7 +596,6 @@ function mergeStores(disk, memory) {
             };
         }
     }
-    // Ignored: union, keep latest `at`
     const ignored = { ...disk.ignored };
     for (const [sig, memEntry] of Object.entries(memory.ignored ?? {})) {
         const diskEntry = ignored[sig];
@@ -875,14 +610,9 @@ function persist(path) {
     const normalizedPath = resolve(path);
     let tmp = null;
     try {
-        // Before writing, check if the file has changed since we loaded it.
-        // If so, re-read and merge to avoid lost updates.
         const observation = observeInterpretationStore(normalizedPath);
         let storeToWrite = _store;
         if (observation.kind === "present" && observation.token !== _token) {
-            // The file moved under us — another process (usually `llm-relay eligibility accept`, which
-            // runs as its own CLI process) wrote it after we loaded. Re-read through the SAME parser and
-            // merge, so this write cannot serialize a stale snapshot over an operator's acceptance.
             const diskStore = readStoreFile(normalizedPath);
             storeToWrite = mergeStores(diskStore, _store);
         }
@@ -891,44 +621,31 @@ function persist(path) {
         writeFileSync(tmp, JSON.stringify(storeToWrite, null, 2) + "\n", "utf8");
         renameSync(tmp, normalizedPath);
         tmp = null;
-        // Update memoized token to the newly-written file's stat.
         const newObservation = observeInterpretationStore(normalizedPath);
         _token = newObservation.kind === "present" ? newObservation.token : null;
     }
     catch {
-        /* storage problem, never a request failure — same contract as every other store here */
     }
     finally {
         if (tmp !== null) {
             try {
                 unlinkSync(tmp);
             }
-            catch { /* best effort cleanup */ }
+            catch { }
         }
     }
 }
-/**
- * What this refusal means, or null when nothing confirmed covers it.
- *
- * Order: the operator-visible table first (so an override beats a seed), then the seeds. A miss
- * returns null and the caller must learn nothing — that is the whole fail-safe.
- */
 export function interpretRefusal(provider, model, status, body, opts = {}) {
     const store = load(opts.path ?? defaultPath());
     const hit = store.confirmed[refusalSignature(provider, model, status, body)];
-    // A researched entry binds only once accepted; an unaccepted one is still sitting in review.
     if (hit && (hit.source === "seed" || hit.acceptedAt !== undefined))
         return hit;
-    // Structured evidence beats prose: the payload states its own schema and its own dimensions,
-    // where a seed only pattern-matches wording. Below an accepted human verdict, above the seeds.
     const structured = interpretStructured(status, body);
     if (structured) {
         return {
             class: structured.class,
             scope: structured.scope,
             source: "seed",
-            // The same envelope carries `google.rpc.RetryInfo`, so the reset is read from the response
-            // itself rather than falling back to the kind's default TTL.
             reset: { kind: "field", field: "retryDelay" },
         };
     }
@@ -941,15 +658,6 @@ export function interpretRefusal(provider, model, status, body, opts = {}) {
     }
     return null;
 }
-/**
- * Hold an uninterpretable refusal for the research tier.
- *
- * Deliberately cheap and lossy: one normalized sample per signature and a count. The queue exists to
- * tell a researcher "this message happens, here is what it looks like", not to be a log — the
- * metadata logger already covers the traffic, and it is metadata-only precisely so bodies do not
- * land on disk. Normalization runs before both the signature and the stored sample, stripping
- * variable ids, key-shaped strings and URLs while leaving the provider's readable refusal text.
- */
 export function recordUnknownRefusal(provider, model, status, body, opts = {}) {
     const normalized = normalizeRefusalMessage(body);
     if (!normalized)
@@ -960,8 +668,6 @@ export function recordUnknownRefusal(provider, model, status, body, opts = {}) {
     if (store.confirmed[sig])
         return;
     const now = opts.now ?? Date.now();
-    // Already judged to mean nothing. Re-queuing it would bury the signatures worth reading under
-    // the ones a human has explicitly finished with — which is what routine throttling does.
     const ignoredAt = store.ignored?.[sig]?.at;
     if (typeof ignoredAt === "number" && now - ignoredAt < IGNORED_TTL_MS)
         return;
@@ -972,8 +678,6 @@ export function recordUnknownRefusal(provider, model, status, body, opts = {}) {
     }
     else {
         if (Object.keys(store.unknown).length >= MAX_UNKNOWN) {
-            // Evict the least-recently-seen: a signature nobody has hit in a long time is the one least
-            // worth researching, and an unbounded file would be its own defect.
             let oldestKey = null;
             let oldestAt = Infinity;
             for (const [k, v] of Object.entries(store.unknown)) {
@@ -990,8 +694,6 @@ export function recordUnknownRefusal(provider, model, status, body, opts = {}) {
             model: typeof model === "string" ? model : null,
             status,
             normalized,
-            // The seed recheck in `pendingRefusals()` normalizes this again. The same normalizer is
-            // intentionally idempotent, so redacting what lands on disk cannot break retroactive seeds.
             sample: normalized,
             count: 1,
             firstSeen: now,
@@ -1000,13 +702,9 @@ export function recordUnknownRefusal(provider, model, status, body, opts = {}) {
     }
     writer.touch(() => persist(path));
 }
-/** Unseen refusals, most-frequent first — the research tier's work list. */
 export function pendingRefusals(opts = {}) {
     const path = opts.path ?? defaultPath();
     const store = load(path);
-    // A signature queued before a seed existed for it is no longer pending — shipping a seed should
-    // RETROACTIVELY clear the queue, or every release that teaches the relay something leaves behind
-    // items asking a human to explain what the relay already knows.
     let resolved = false;
     for (const [signature, entry] of Object.entries(store.unknown)) {
         if (entry.model === null)
@@ -1022,7 +720,6 @@ export function pendingRefusals(opts = {}) {
         .map(([signature, v]) => ({ ...v, signature }))
         .sort((a, b) => b.count - a.count || b.lastSeen - a.lastSeen);
 }
-/** Attach a researched verdict to a pending signature. It does NOT bind until accepted. */
 export function proposeInterpretation(signature, proposal, opts = {}) {
     const path = opts.path ?? defaultPath();
     const store = load(path);
@@ -1033,13 +730,6 @@ export function proposeInterpretation(signature, proposal, opts = {}) {
     writer.touch(() => persist(path));
     return true;
 }
-/**
- * Accept an interpretation, which is the moment it starts affecting routing.
- *
- * Separate from `propose` on purpose: this is the review gate that keeps a researched verdict —
- * a model's opinion — out of the request path until a person (or an agent acting explicitly for
- * one) has looked at it.
- */
 export function acceptInterpretation(signature, opts = {}) {
     const path = opts.path ?? defaultPath();
     const store = load(path);
@@ -1049,13 +739,7 @@ export function acceptInterpretation(signature, opts = {}) {
         : null);
     if (!verdict)
         return false;
-    // The reset travels with the verdict: accepting an interpretation commits everything known about
-    // that message shape — what it means, who it covers, and when it clears — not just a label.
     const reset = verdict.reset ?? pending?.proposed?.reset;
-    // So does the cost filter. This literal used to copy six named fields and silently DROP
-    // `costClasses` (the parameter type did not declare it, and a spread into `override` defeats
-    // the excess-property check), so `--cost-class paid` accepted cleanly and persisted nothing —
-    // the verdict then covered EVERY class, the exact over-demotion the flag exists to prevent.
     const costClasses = verdict.costClasses ?? pending?.proposed?.costClasses;
     store.confirmed[signature] = {
         class: verdict.class,
@@ -1070,13 +754,6 @@ export function acceptInterpretation(signature, opts = {}) {
     writer.touch(() => persist(path));
     return true;
 }
-/**
- * "This means nothing durable" — a real verdict, and therefore remembered.
- *
- * Routine throttling, a policy refusal, a transient fault: none of them should teach the router
- * anything, and none of them should keep asking. Recording the rejection is what makes the queue
- * converge instead of refilling with messages already judged uninteresting.
- */
 export function rejectInterpretation(signature, opts = {}) {
     const path = opts.path ?? defaultPath();
     const store = load(path);
@@ -1087,14 +764,12 @@ export function rejectInterpretation(signature, opts = {}) {
     writer.touch(() => persist(path));
     return true;
 }
-/** Flush pending writes. Called on shutdown, like the other write-behind stores. */
 export function flushInterpretations(opts = {}) {
     if (!writer.dirty)
         return;
     writer.clear();
     persist(opts.path ?? defaultPath());
 }
-/** Test seam: drop the in-memory store so a suite can point at a fresh path. */
 export function resetInterpretations() {
     _store = null;
     _path = null;