lynkr 9.7.3 → 9.9.1

package/src/routing/telemetry.js

@@ -32,6 +32,15 @@ let db = null;
 /** @type {boolean} */
 let initialised = false;
 
+/**
+ * Test-only escape hatches. Production code should never touch these — the
+ * DB path is hardcoded to `<cwd>/.lynkr/telemetry.db`. Tests call these
+ * before the first `record()` to isolate their state.
+ * @type {string|null}
+ */
+let _testDbPath = null;
+let _testDbDisabled = false;
+
 /** Default retention: 30 days */
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
@@ -49,16 +58,17 @@ function init() {
   }
 
   try {
-    // Allow tests to redirect telemetry to an isolated DB so unit/integration
-    // runs never pollute the production .lynkr/telemetry.db that build-knn-index.js
-    // reads from. Empty string disables telemetry entirely.
-    const override = process.env.LYNKR_TELEMETRY_DB_PATH;
+    // Path is hardcoded to <cwd>/.lynkr/telemetry.db in production. The
+    // pre-B `LYNKR_TELEMETRY_DB_PATH` env override was removed so operators
+    // can't accidentally divert telemetry to a stale path. Tests still need
+    // to isolate their DB — see `_setDbPathForTests` / `_disableForTests`
+    // below (module-scoped setters called before the first `record()`).
     let dbPath;
-    if (override === "") {
-      logger.debug("Telemetry: LYNKR_TELEMETRY_DB_PATH is empty, telemetry disabled");
+    if (_testDbDisabled) {
+      logger.debug("Telemetry: disabled for tests");
       return false;
-    } else if (override) {
-      dbPath = path.resolve(override);
+    } else if (_testDbPath) {
+      dbPath = path.resolve(_testDbPath);
       const overrideDir = path.dirname(dbPath);
       if (!fs.existsSync(overrideDir)) {
         fs.mkdirSync(overrideDir, { recursive: true });
@@ -111,7 +121,13 @@ function init() {
         tokens_per_second REAL,
         cost_efficiency REAL,
         request_text    TEXT,
-        response_text   TEXT
+        response_text   TEXT,
+        base_tier         TEXT,
+        escalation_source TEXT,
+        propensity        REAL,
+        candidates        TEXT,
+        pinned            INTEGER DEFAULT 0,
+        switch_reason     TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_telemetry_provider
@@ -125,14 +141,34 @@ function init() {
 
       CREATE INDEX IF NOT EXISTS idx_telemetry_session_id
         ON routing_telemetry(session_id, timestamp);
+
+      CREATE TABLE IF NOT EXISTS savings_events (
+        id           INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp    INTEGER NOT NULL,
+        category     TEXT NOT NULL,
+        tokens_saved INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_savings_timestamp
+        ON savings_events(timestamp);
     `);
 
     // Migration: add columns to pre-existing tables (CREATE TABLE IF NOT EXISTS
     // won't add them to a DB created before these columns existed).
     const existingCols = new Set(db.prepare("PRAGMA table_info(routing_telemetry)").all().map((c) => c.name));
-    for (const col of ["request_text", "response_text"]) {
+    const additiveCols = [
+      ["request_text", "TEXT"],
+      ["response_text", "TEXT"],
+      ["base_tier", "TEXT"],
+      ["escalation_source", "TEXT"],
+      ["propensity", "REAL"],
+      ["candidates", "TEXT"],
+      ["pinned", "INTEGER DEFAULT 0"],
+      ["switch_reason", "TEXT"],
+    ];
+    for (const [col, type] of additiveCols) {
       if (!existingCols.has(col)) {
-        db.exec(`ALTER TABLE routing_telemetry ADD COLUMN ${col} TEXT`);
+        db.exec(`ALTER TABLE routing_telemetry ADD COLUMN ${col} ${type}`);
       }
     }
 
@@ -189,18 +225,27 @@ function record(data) {
           provider, model, routing_method, was_fallback, output_tokens,
           latency_ms, status_code, error_type, cost_usd, tool_calls_made,
           retry_count, circuit_breaker_state, quality_score, tokens_per_second,
-          cost_efficiency, request_text, response_text
+          cost_efficiency, request_text, response_text,
+          base_tier, escalation_source, propensity, candidates, pinned, switch_reason
         ) VALUES (
           @request_id, @session_id, @timestamp, @complexity_score, @tier,
           @agentic_type, @tool_count, @input_tokens, @message_count, @request_type,
           @provider, @model, @routing_method, @was_fallback, @output_tokens,
           @latency_ms, @status_code, @error_type, @cost_usd, @tool_calls_made,
           @retry_count, @circuit_breaker_state, @quality_score, @tokens_per_second,
-          @cost_efficiency, @request_text, @response_text
+          @cost_efficiency, @request_text, @response_text,
+          @base_tier, @escalation_source, @propensity, @candidates, @pinned, @switch_reason
         )`
       );
       if (!insert) return;
 
+      let candidatesJson = null;
+      if (data.candidates != null) {
+        candidatesJson = typeof data.candidates === "string"
+          ? data.candidates
+          : JSON.stringify(data.candidates);
+      }
+
       insert.run({
         request_id: data.request_id ?? null,
         session_id: data.session_id ?? null,
@@ -229,6 +274,12 @@ function record(data) {
         cost_efficiency: data.cost_efficiency ?? null,
         request_text: data.request_text ?? null,
         response_text: data.response_text ?? null,
+        base_tier: data.base_tier ?? null,
+        escalation_source: data.escalation_source ?? null,
+        propensity: data.propensity ?? null,
+        candidates: candidatesJson,
+        pinned: data.pinned ? 1 : 0,
+        switch_reason: data.switch_reason ?? null,
       });
     } catch (err) {
       logger.debug({ err: err.message }, "Telemetry record failed");
@@ -466,6 +517,121 @@ function getRoutingAccuracy(timeRange = {}) {
   }
 }
 
+/**
+ * Aggregate escalation statistics.
+ *
+ * For every row where `escalation_source` is not null, returns a per-source
+ * breakdown: request count, total cost_usd, and total input_tokens (so
+ * callers can approximate a base-tier-vs-served-tier cost delta by
+ * combining with cost-optimizer.estimateCost for the two tiers).
+ *
+ * @param {Object} [timeRange]
+ * @param {number} [timeRange.since]
+ * @param {number} [timeRange.until]
+ * @returns {Object|null} { totalRequests, totalEscalated, escalatedPct, bySource: {source: {count, costUsd, inputTokens, avgQuality}} }
+ */
+function getEscalationStats(timeRange = {}) {
+  if (!init()) return null;
+
+  const since = timeRange.since ?? Date.now() - 24 * 60 * 60 * 1000;
+  const until = timeRange.until ?? Date.now();
+
+  try {
+    const total = db
+      .prepare("SELECT COUNT(*) as cnt FROM routing_telemetry WHERE timestamp BETWEEN ? AND ?")
+      .get(since, until);
+    if (!total || total.cnt === 0) return null;
+
+    const rows = db
+      .prepare(
+        `SELECT
+           escalation_source as source,
+           COUNT(*) as cnt,
+           SUM(COALESCE(cost_usd, 0)) as cost_usd,
+           SUM(COALESCE(input_tokens, 0)) as input_tokens,
+           AVG(quality_score) as avg_quality
+         FROM routing_telemetry
+         WHERE timestamp BETWEEN ? AND ?
+           AND escalation_source IS NOT NULL
+         GROUP BY escalation_source`
+      )
+      .all(since, until);
+
+    const bySource = {};
+    let totalEscalated = 0;
+    for (const r of rows) {
+      bySource[r.source] = {
+        count: r.cnt,
+        costUsd: Math.round((r.cost_usd || 0) * 10000) / 10000,
+        inputTokens: r.input_tokens || 0,
+        avgQuality: r.avg_quality != null ? Math.round(r.avg_quality * 10) / 10 : null,
+      };
+      totalEscalated += r.cnt;
+    }
+
+    return {
+      totalRequests: total.cnt,
+      totalEscalated,
+      escalatedPct: Math.round((totalEscalated / total.cnt) * 1000) / 10,
+      bySource,
+    };
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getEscalationStats failed");
+    return null;
+  }
+}
+
+/**
+ * Aggregate quality-by-tier-and-request-type — feeds the de-escalator's
+ * evidence check. Returns rows of {tier, request_type, count, avg_quality,
+ * error_rate}.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.since] - ms epoch, defaults to 7 days ago
+ * @param {number} [opts.until] - defaults to now
+ * @param {string[]} [opts.tiers] - filter to specific tiers
+ * @returns {Array<{tier:string, request_type:string, count:number, avg_quality:number|null, error_rate:number}>|null}
+ */
+function getQualityByTierAndType(opts = {}) {
+  if (!init()) return null;
+
+  const since = opts.since ?? Date.now() - 7 * 24 * 60 * 60 * 1000;
+  const until = opts.until ?? Date.now();
+
+  try {
+    const tierFilter = Array.isArray(opts.tiers) && opts.tiers.length > 0
+      ? `AND tier IN (${opts.tiers.map(() => "?").join(",")})`
+      : "";
+    const params = [since, until, ...(Array.isArray(opts.tiers) ? opts.tiers : [])];
+    const rows = db
+      .prepare(
+        `SELECT
+           tier,
+           request_type,
+           COUNT(*) as count,
+           AVG(quality_score) as avg_quality,
+           SUM(CASE WHEN error_type IS NOT NULL THEN 1 ELSE 0 END) * 1.0 / COUNT(*) as error_rate
+         FROM routing_telemetry
+         WHERE timestamp BETWEEN ? AND ?
+           AND tier IS NOT NULL
+           AND request_type IS NOT NULL
+           ${tierFilter}
+         GROUP BY tier, request_type`
+      )
+      .all(...params);
+    return rows.map((r) => ({
+      tier: r.tier,
+      request_type: r.request_type,
+      count: r.count,
+      avg_quality: r.avg_quality != null ? Math.round(r.avg_quality * 10) / 10 : null,
+      error_rate: Math.round(r.error_rate * 10000) / 10000,
+    }));
+  } catch (err) {
+    logger.debug({ err: err.message }, "Telemetry getQualityByTierAndType failed");
+    return null;
+  }
+}
+
 /**
  * Delete telemetry records older than a given threshold.
  *
@@ -527,11 +693,118 @@ function getProviderStatsCached(provider, timeRange = {}) {
   return result;
 }
 
+/**
+ * Return the shared telemetry sqlite handle (initialising if needed) so other
+ * routing subsystems can persist state alongside routing telemetry without
+ * opening a second WAL connection to the same file. Returns null when
+ * better-sqlite3 is unavailable or initialisation failed.
+ * @returns {import('better-sqlite3').Database|null}
+ */
+function getDb() {
+  if (!init()) return null;
+  return db;
+}
+
+/**
+ * Record a token-savings event (tool stripping, compression, cache hit).
+ * Fire-and-forget like record(): never blocks or throws on the request path.
+ *
+ * @param {"tool_stripping"|"compression"|"cache_hit"} category
+ * @param {number} tokensSaved - Estimated tokens avoided (must be > 0 to record)
+ */
+function recordSavings(category, tokensSaved) {
+  if (!Number.isFinite(tokensSaved) || tokensSaved <= 0) return;
+  if (!init()) return;
+
+  setImmediate(() => {
+    try {
+      const insert = stmt(
+        "insertSavings",
+        `INSERT INTO savings_events (timestamp, category, tokens_saved)
+         VALUES (@timestamp, @category, @tokens_saved)`
+      );
+      if (!insert) return;
+      insert.run({
+        timestamp: Date.now(),
+        category: String(category),
+        tokens_saved: Math.round(tokensSaved),
+      });
+    } catch (err) {
+      logger.debug({ err: err.message }, "Failed to record savings event");
+    }
+  });
+}
+
+/**
+ * Summarise savings events since a timestamp.
+ *
+ * @param {number} sinceMs - Epoch ms lower bound (0 for all time)
+ * @returns {{total: number, byCategory: Object<string, number>}}
+ */
+function getSavingsSummary(sinceMs = 0) {
+  const empty = { total: 0, byCategory: {} };
+  if (!init()) return empty;
+  try {
+    const rows = db
+      .prepare(
+        `SELECT category, SUM(tokens_saved) AS tokens
+         FROM savings_events WHERE timestamp >= ? GROUP BY category`
+      )
+      .all(sinceMs);
+    const byCategory = {};
+    let total = 0;
+    for (const row of rows) {
+      byCategory[row.category] = row.tokens || 0;
+      total += row.tokens || 0;
+    }
+    return { total, byCategory };
+  } catch (err) {
+    logger.debug({ err: err.message }, "Failed to read savings summary");
+    return empty;
+  }
+}
+
+/**
+ * Test-only helpers. Do NOT call from production code. These exist because
+ * the DB path was hardcoded (no more `LYNKR_TELEMETRY_DB_PATH` env var), so
+ * tests need an alternative way to route telemetry at an isolated file.
+ *
+ * Both helpers must be called BEFORE the first `record()` call — after
+ * that the DB handle is memoised and won't re-open. Call `_resetForTests`
+ * between tests to force re-initialisation.
+ */
+function _setDbPathForTests(p) {
+  _testDbPath = p || null;
+  _testDbDisabled = false;
+}
+function _disableForTests() {
+  _testDbDisabled = true;
+  _testDbPath = null;
+}
+function _resetForTests() {
+  if (db) {
+    try { db.close(); } catch { /* ignore */ }
+  }
+  db = null;
+  initialised = false;
+  _testDbPath = null;
+  _testDbDisabled = false;
+}
+
 module.exports = {
   record,
   query,
   getStats: getStatsCached,
   getProviderStats: getProviderStatsCached,
   getRoutingAccuracy,
+  getEscalationStats,
+  getQualityByTierAndType,
+  recordSavings,
+  getSavingsSummary,
   cleanup,
+  getDb,
+  // Test-only — do not use in production code.
+  _setDbPathForTests,
+  _disableForTests,
+  _resetForTests,
 };

package/src/routing/verifier.js

@@ -0,0 +1,267 @@
+/**
+ * WS6 — response verifier for cascade routing.
+ *
+ * Judges whether a CHEAP-tier response is good enough to serve, so the
+ * cascade can discard bad answers and escalate instead of delivering them.
+ * Rationale (deep-research, 2026-07-08): ex-ante difficulty prediction
+ * failed to beat trivial baselines on agentic coding traffic (SWE-Bench),
+ * while try-cheap-then-verify cascades gained up to 14%. The verifier is
+ * where that gain lives.
+ *
+ * Design constraints:
+ *   - Layer 1: deterministic structural checks targeting the cheap-model
+ *     failure modes observed live — language drift (CJK mid-English),
+ *     degeneration loops, truncation, malformed tool calls, empty/echo
+ *     output. High precision: flag only what is definitely broken.
+ *   - Layer 2: a coarse content-quality score with a conservative
+ *     threshold. Catches low-effort responses to substantive asks.
+ *   - No LLM-judge in v1 (research: unvalidated self-assessment is weak),
+ *     no logprobs (Ollama's Anthropic passthrough doesn't expose them).
+ *     A confidently-wrong but fluent answer WILL pass — the target is
+ *     garbage, not falsehood.
+ *   - Pure function, no I/O. Never throws: any internal error returns
+ *     verdict "pass" (fail-open — a broken verifier must not break
+ *     serving or force spurious escalations).
+ *
+ * Verification only ever applies to cheap-tier responses; expensive-tier
+ * answers are never second-guessed (caller enforces).
+ */
+
+const logger = require('../logger');
+
+// ---------------------------------------------------------------------------
+// Text extraction
+// ---------------------------------------------------------------------------
+
+function _responseText(responseBody) {
+  const content = responseBody?.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+function _lastUserText(payload) {
+  const msgs = payload?.messages;
+  if (!Array.isArray(msgs)) return '';
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (m?.role !== 'user') continue;
+    const raw = typeof m.content === 'string'
+      ? m.content
+      : Array.isArray(m.content)
+        ? m.content.filter((b) => b?.type === 'text').map((b) => b.text || '').join(' ')
+        : '';
+    return raw
+      .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, ' ')
+      // Codex harness blocks merged into the typed text — inflate askLen
+      // and trip the wants-code regexes ("claude-code", access="write"),
+      // failing every short answer to a trivial prompt.
+      .replace(/<environment_context>[\s\S]*?<\/environment_context>/g, ' ')
+      .replace(/<user_instructions>[\s\S]*?<\/user_instructions>/g, ' ')
+      // Goose wraps every typed message in a turn-context block (time, cwd,
+      // todo notes) — 275+ chars of harness plumbing that made a bare "Hi"
+      // look like a substantive ask, failing every short cheap-tier answer.
+      .replace(/<turn-context>[\s\S]*?<\/turn-context>/g, ' ')
+      .trim();
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------------------
+// Layer 1 — structural checks (each returns a reason string or null)
+// ---------------------------------------------------------------------------
+
+/**
+ * Language drift: unexpected CJK/Cyrillic content in a conversation whose
+ * user text contains none. Live incident: minimax emitting "+统一接口:" in
+ * the middle of an English refactor plan. Threshold is a RATIO so quoting
+ * a foreign identifier from the repo doesn't trip it.
+ */
+function checkLanguageDrift(userText, answerText) {
+  if (!answerText) return null;
+  const FOREIGN = /[一-鿿぀-ヿ가-힯Ѐ-ӿ]/g;
+  const userForeign = (userText.match(FOREIGN) || []).length;
+  if (userForeign > 0) return null; // user writes that script — anything goes
+  const answerForeign = (answerText.match(FOREIGN) || []).length;
+  if (answerForeign === 0) return null;
+  const ratio = answerForeign / Math.max(1, answerText.length);
+  // A couple of quoted characters is fine; sustained drift is not.
+  if (answerForeign >= 6 || ratio > 0.02) {
+    return `language-drift (${answerForeign} foreign chars, user text had none)`;
+  }
+  return null;
+}
+
+/**
+ * Degeneration: the same shingle repeating far beyond what natural text
+ * (or even a list) produces. Catches small-model repetition loops.
+ */
+function checkDegeneration(answerText) {
+  if (!answerText || answerText.length < 200) return null;
+  const words = answerText.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length < 40) return null;
+  const SHINGLE = 5;
+  const counts = new Map();
+  for (let i = 0; i + SHINGLE <= words.length; i++) {
+    const key = words.slice(i, i + SHINGLE).join(' ');
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  let max = 0;
+  for (const c of counts.values()) if (c > max) max = c;
+  const total = Math.max(1, words.length - SHINGLE + 1);
+  if (max >= 5 && max / total > 0.08) {
+    return `degeneration (a 5-gram repeats ${max}× across ${total} positions)`;
+  }
+  return null;
+}
+
+/**
+ * Truncation: response ran into max_tokens mid-structure. A length stop
+ * by itself is common (long answers); a length stop with an UNCLOSED code
+ * fence means the useful part is cut.
+ */
+function checkTruncation(answerText, responseBody) {
+  if (responseBody?.stop_reason !== 'max_tokens' && responseBody?.stop_reason !== 'length') return null;
+  const fences = (answerText.match(/```/g) || []).length;
+  if (fences % 2 === 1) {
+    return 'truncation (hit token limit inside an open code fence)';
+  }
+  return null;
+}
+
+/**
+ * Malformed tool calls: tool_use blocks whose input is not an object or
+ * whose name is missing. Live symptom: Claude Code's "Invalid tool
+ * parameters" errors on cheap-model responses.
+ */
+function checkMalformedToolCalls(responseBody) {
+  const content = responseBody?.content;
+  if (!Array.isArray(content)) return null;
+  for (const b of content) {
+    if (b?.type !== 'tool_use') continue;
+    if (!b.name || typeof b.name !== 'string') return 'malformed-tool-call (missing name)';
+    if (b.input === undefined || b.input === null || typeof b.input !== 'object' || Array.isArray(b.input)) {
+      return `malformed-tool-call (input is ${Array.isArray(b.input) ? 'array' : typeof b.input})`;
+    }
+  }
+  return null;
+}
+
+/** Empty or echo output. */
+function checkEmptyOrEcho(userText, answerText, responseBody) {
+  const hasToolUse = Array.isArray(responseBody?.content)
+    && responseBody.content.some((b) => b?.type === 'tool_use');
+  if (hasToolUse) return null; // tool-only turns legitimately carry no prose
+  const t = (answerText || '').trim();
+  if (t.length < 2) return 'empty-response';
+  if (userText.length > 40 && t.length > 40) {
+    const a = t.toLowerCase().slice(0, 200);
+    const u = userText.toLowerCase().slice(0, 200);
+    if (a === u) return 'prompt-echo';
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Layer 2 — coarse content-quality score
+// ---------------------------------------------------------------------------
+
+/**
+ * 0-100. Conservative: only very low scores fail (threshold below).
+ * Signals: effort proportional to the ask, structure when structure was
+ * requested, code when code was requested.
+ */
+function contentScore(userText, answerText, responseBody) {
+  const hasToolUse = Array.isArray(responseBody?.content)
+    && responseBody.content.some((b) => b?.type === 'tool_use');
+  if (hasToolUse) return 100; // agent turns are judged by their tool calls, not prose
+
+  let score = 60; // neutral prior
+  const askLen = userText.length;
+  const ansLen = (answerText || '').length;
+
+  // Effort: a substantive ask answered in a stub.
+  if (askLen > 200 && ansLen < 60) score -= 35;
+  else if (askLen > 100 && ansLen < 30) score -= 30;
+  else if (ansLen >= 120) score += 15;
+
+  // Structure requested → structure delivered?
+  const wantsStructure = /\b(list|steps?|plan|compare|table|pros and cons|trade-?offs)\b/i.test(userText);
+  const hasStructure = /(^|\n)\s*([-*•]|\d+[.)])\s+|\n#{1,3}\s|\|.*\|/.test(answerText || '');
+  if (wantsStructure) score += hasStructure ? 15 : -20;
+
+  // Code requested → code delivered?
+  const wantsCode = /\b(code|function|implement|snippet|example|replacement|fix)\b/i.test(userText)
+    && /```/.test(userText || '') === false; // asking about pasted code still often warrants code back — keep loose
+  const hasCode = /```|(^|\n) {4}\S/.test(answerText || '');
+  if (wantsCode && /\b(write|implement|show|give me)\b/i.test(userText)) {
+    score += hasCode ? 10 : -15;
+  }
+
+  return Math.max(0, Math.min(100, score));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const CONTENT_SCORE_FAIL_THRESHOLD = 30;
+
+/**
+ * @param {object} args
+ * @param {object} args.payload      — the request payload
+ * @param {object} args.responseBody — Anthropic-format response body
+ * @returns {{verdict: 'pass'|'fail', score: number|null, reasons: string[]}}
+ */
+function verify({ payload, responseBody } = {}) {
+  try {
+    // No body / unrecognizable content shape = nothing to verify (upstream
+    // error paths have their own handling). Verification judges answers,
+    // not absences or shapes we don't understand.
+    if (!responseBody || typeof responseBody !== 'object') {
+      return { verdict: 'pass', score: null, reasons: [] };
+    }
+    const c = responseBody.content;
+    if (typeof c !== 'string' && !Array.isArray(c)) {
+      return { verdict: 'pass', score: null, reasons: [] };
+    }
+    const userText = _lastUserText(payload);
+    const answerText = _responseText(responseBody);
+
+    const reasons = [
+      checkLanguageDrift(userText, answerText),
+      checkDegeneration(answerText),
+      checkTruncation(answerText, responseBody),
+      checkMalformedToolCalls(responseBody),
+      checkEmptyOrEcho(userText, answerText, responseBody),
+    ].filter(Boolean);
+
+    const score = contentScore(userText, answerText, responseBody);
+    if (reasons.length === 0 && score < CONTENT_SCORE_FAIL_THRESHOLD) {
+      reasons.push(`low-content-score (${score} < ${CONTENT_SCORE_FAIL_THRESHOLD})`);
+    }
+
+    return { verdict: reasons.length ? 'fail' : 'pass', score, reasons };
+  } catch (err) {
+    // Fail-open: a broken verifier must never block serving.
+    logger.debug({ err: err.message }, '[Verifier] error — failing open');
+    return { verdict: 'pass', score: null, reasons: [] };
+  }
+}
+
+module.exports = {
+  verify,
+  CONTENT_SCORE_FAIL_THRESHOLD,
+  // exported for unit tests
+  _internal: {
+    checkLanguageDrift,
+    checkDegeneration,
+    checkTruncation,
+    checkMalformedToolCalls,
+    checkEmptyOrEcho,
+    contentScore,
+  },
+};