driftproof 0.3.0 → 0.5.0

package/lib/run.js

@@ -1,12 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 'use strict';
 
-const { complete, resolveModel, surfaceLabel } = require('./provider');
+const { complete, resolveModel, surfaceForModel, isMeteredSurface, CODEX_OVERHEAD_NOTE } = require('./provider');
 const { gradeSamples, judgeSettings } = require('./judge');
 const { buildReceipt } = require('./receipt');
 const { sha256 } = require('./canonical');
-const { registryStatus } = require('./models');
+const { registryStatus, providerForModel, priceForModel } = require('./models');
 const { perCallCostUSD } = require('./cost');
+const { runChecks } = require('./checks');
+const { estimateTokens } = require('./skillCost');
+const { hasUsage, normalizeUsage } = require('./usage');
+const { buildPricingSnapshot, computeEconomics } = require('./value');
 const { RUNNER_VERSION, DEFAULT_JUDGE_SAMPLES } = require('../config');
 
 // Known model release dates (best-effort; null when unknown). Recorded into the
@@ -20,6 +24,8 @@ const MODEL_RELEASE_DATES = {
   'claude-haiku-4-5': '2025-10-01',
   'claude-sonnet-5': '2026-06-30',     // anthropic.com/news/claude-sonnet-5
   'claude-sonnet-4-6': '2026-02-17',   // anthropic.com/news/claude-sonnet-4-6
+  'claude-opus-5': '2026-07-24',       // anthropic.com/news/claude-opus-5
+  'claude-opus-4-8': '2026-05-28',     // anthropic.com/news/claude-opus-4-8
 };
 
 function releaseDateFor(modelId) {
@@ -39,9 +45,16 @@ function projectCalls(caseCount, samples) {
 // SKILL.md is prepended as a system prompt (the whole point: measure the skill's
 // marginal effect vs a bare baseline).
 async function runCase({ skillMd, caseObj, model, withSkill, timeoutMs }) {
+  // Test seam (gate only): force a persistent timeout for a named case id so the
+  // failed_timeout path is exercised deterministically without any live call.
+  if (process.env.DRIFTPROOF_TEST_TIMEOUT_CASEID && process.env.DRIFTPROOF_TEST_TIMEOUT_CASEID === caseObj.id) {
+    const e = new Error('provider timed out (test seam) after retries');
+    e.code = 'TIMEOUT'; e.attempts = 4;
+    throw e;
+  }
   const system = withSkill ? skillMd : undefined;
-  const { text, usage } = await complete({ system, prompt: caseObj.prompt, model, maxTokens: 1024, timeoutMs });
-  return { text, usage };
+  const { text, usage, wall_ms, attempts } = await complete({ system, prompt: caseObj.prompt, model, maxTokens: 1024, timeoutMs });
+  return { text, usage, wall_ms, attempts };
 }
 
 // Determine a case outcome from its sampled band and threshold.
@@ -77,7 +90,12 @@ async function judgeCase({ caseObj, response, generationHash, judgeModel, mode,
     reason: g.reason,
     judge: { model_id: g.model_id, rubric_hash: g.rubric_hash },
   };
-  return { caseResult, sampleTexts: g.sample_texts };
+  // v0.3.1 deterministic post-checks (supplementary; NOT folded into `outcome`).
+  const checks = runChecks(response, caseObj.checks);
+  if (checks.length) caseResult.checks = checks;
+  // v0.4: grading overhead for this case row, kept OUT of the skill-value math.
+  if (hasUsage(g.usage)) caseResult.judge_usage = g.usage;
+  return { caseResult, sampleTexts: g.sample_texts, attempts: g.attempts };
 }
 
 // Run up to `concurrency` async tasks at a time, preserving input order in the
@@ -112,6 +130,9 @@ async function runSkillOnModel({ skill, model, opts = {} }) {
   const modelId = resolveModel(model);
   const judgeModel = opts.judgeModel ? resolveModel(opts.judgeModel) : modelId;
   const timeoutMs = opts.timeoutMs || 120000;
+  // Optional per-case timeout overrides { caseId: ms }; a slow case can get a
+  // longer budget without lengthening every other case's per-call timeout.
+  const caseTimeoutMs = opts.caseTimeoutMs || {};
   const maxCalls = opts.maxCalls || 200;
   const samples = opts.samples || DEFAULT_JUDGE_SAMPLES;
   const concurrency = Math.max(1, opts.concurrency || 1);
@@ -137,46 +158,98 @@ async function runSkillOnModel({ skill, model, opts = {} }) {
   for (const c of cases) for (const withSkill of [true, false]) tasks.push({ c, withSkill });
 
   let calls = 0;
+  let failedCases = 0;
+  const isTimeout = (e) => !!(e && (e.code === 'TIMEOUT' || /tim(e|ed)\s*out/i.test(String((e && e.message) || ''))));
+  const genKind = (ws) => (ws ? 'gen_with_skill' : 'gen_baseline');
   const pairs = await mapPool(tasks, concurrency, async ({ c, withSkill }) => {
     const mode = withSkill ? 'with_skill' : 'baseline';
-    onProgress({ case: c.id, mode, phase: 'generate' });
-    const { text } = await runCase({ skillMd: skill.skillMd, caseObj: c, model: modelId, withSkill, timeoutMs });
-    calls += 1;
-    // Live budget: count the generation call, then hard-stop if over 1.25× cap.
-    if (budget) budget.add(perCallCostUSD(modelId, withSkill ? 'gen_with_skill' : 'gen_baseline'));
-    const generationHash = sha256(String(text || ''));
-    onProgress({ case: c.id, mode, phase: 'judge', samples });
-    const { caseResult, sampleTexts } = await judgeCase({ caseObj: c, response: text, generationHash, judgeModel, mode, timeoutMs, samples });
-    calls += samples;
-    // Live budget: count all `samples` judge calls for this (case, mode).
-    if (budget) budget.add(samples * perCallCostUSD(judgeModel, 'judge'));
-    onProgress({ case: c.id, mode, phase: 'done', outcome: caseResult.outcome, score: caseResult.mean, stddev: caseResult.stddev });
-    const transcript = keepTranscripts
-      ? { id: c.id, mode, generation: String(text || ''), judge_outputs: sampleTexts }
-      : null;
-    return { caseResult, transcript };
+    const ct = caseTimeoutMs[c.id] || timeoutMs;
+    try {
+      onProgress({ case: c.id, mode, phase: 'generate' });
+      const gen = await runCase({ skillMd: skill.skillMd, caseObj: c, model: modelId, withSkill, timeoutMs: ct });
+      calls += 1;
+      // Live budget: count the generation call INCLUDING retries, then hard-stop
+      // if over 1.25× cap.
+      if (budget) budget.add((gen.attempts || 1) * perCallCostUSD(modelId, genKind(withSkill)));
+      const generationHash = sha256(String(gen.text || ''));
+      onProgress({ case: c.id, mode, phase: 'judge', samples });
+      const jr = await judgeCase({ caseObj: c, response: gen.text, generationHash, judgeModel, mode, timeoutMs: ct, samples });
+      // v0.4: the GENERATION call's usage is the skill-value measurement (the
+      // judge's own usage rides separately on judge_usage, above).
+      if (hasUsage(gen.usage)) jr.caseResult.usage = normalizeUsage({ ...gen.usage, wall_ms: gen.wall_ms });
+      calls += samples;
+      // Live budget: count all judge calls (retries included) for this (case, mode).
+      if (budget) budget.add((jr.attempts || samples) * perCallCostUSD(judgeModel, 'judge'));
+      onProgress({ case: c.id, mode, phase: 'done', outcome: jr.caseResult.outcome, score: jr.caseResult.mean, stddev: jr.caseResult.stddev });
+      const transcript = keepTranscripts
+        ? { id: c.id, mode, generation: String(gen.text || ''), judge_outputs: jr.sampleTexts }
+        : null;
+      return { caseResult: jr.caseResult, transcript };
+    } catch (e) {
+      if (e && e.code === 'BUDGET_HARDSTOP') throw e;   // budget hard-stop stays fatal
+      if (!isTimeout(e)) throw e;                        // non-timeout errors stay fatal
+      // Persistent timeout → NON-FATAL: charge the consumed attempts, record the
+      // case as failed_timeout (no fabricated samples), and continue the run.
+      if (budget) {
+        try {
+          if (e.phase === 'judge') budget.add((e.judgeAttempts || 1) * perCallCostUSD(judgeModel, 'judge'));
+          else budget.add((e.attempts || 1) * perCallCostUSD(modelId, genKind(withSkill)));
+        } catch (be) { if (be && be.code === 'BUDGET_HARDSTOP') throw be; }
+      }
+      failedCases += 1;
+      onProgress({ case: c.id, mode, phase: 'failed', reason: String((e && e.message) || 'timeout') });
+      return { caseResult: { id: c.id, mode, case_status: 'failed_timeout', reason: String((e && e.message) || 'timeout').slice(0, 200) }, transcript: null };
+    }
   });
   const caseResults = pairs.map((p) => p.caseResult);
   const transcripts = keepTranscripts ? pairs.map((p) => p.transcript) : null;
 
+  const surface = surfaceForModel(modelId);
+  const nowIso = opts.nowIso || new Date().toISOString();
+  // v0.4 economics. The pricing snapshot is frozen HERE, at run time, from the
+  // registry; every derived dollar figure below is computed from the snapshot and
+  // never from the live registry, so this receipt keeps its meaning when prices
+  // later change.
+  const pricingSnapshot = buildPricingSnapshot({
+    models: [modelId, judgeModel],
+    lookup: priceForModel,
+    nowIso,
+  });
+  const economics = computeEconomics({
+    cases: caseResults,
+    modelId,
+    judgeModelId: judgeModel,
+    pricingSnapshot,
+    surface,
+    meteredSurface: isMeteredSurface(surface),
+  });
   const receipt = buildReceipt({
-    skill: { name: skill.name, version: skill.version, contentHash: skill.contentHash },
+    skill: {
+      name: skill.name, version: skill.version, contentHash: skill.contentHash,
+      // v0.3.1 value-per-token axis: estimated SKILL.md token size.
+      tokens: estimateTokens(skill.skillMd),
+    },
     suite: { format: skill.suite.format, suiteHash: skill.suite.suiteHash, caseCount: skill.suite.caseCount },
     run: {
       model_id: modelId,
       model_release_date: releaseDateFor(modelId),
-      surface: surfaceLabel(),
+      provider: providerForModel(modelId),
+      surface,
+      // v0.3.1: on the openai/cli (codex) surface, record the fixed harness preamble.
+      surface_overhead_note: surface === 'openai-cli' ? CODEX_OVERHEAD_NOTE : undefined,
       runner_version: RUNNER_VERSION,
-      date_utc: opts.nowIso || new Date().toISOString(),
+      date_utc: nowIso,
       registry: registryStatus(modelId),
       transcripts: keepTranscripts ? 'retained-local' : 'hashes-only',
-      judge: judgeSettings(samples),
+      judge: judgeSettings(samples, judgeModel),
+      pricing_snapshot: pricingSnapshot,
     },
     cases: caseResults,
+    economics,
     verificationLevel: 'TESTED',
   });
 
-  return { receipt, calls, transcripts };
+  return { receipt, calls, transcripts, failedCases };
 }
 
 function band(mean, sd) { return `${mean.toFixed(3)} ± ${sd.toFixed(3)}`; }
@@ -191,7 +264,7 @@ function summarizeReceipt(receipt) {
   L.push(`- **run (UTC):** ${receipt.run.date_utc}`);
   L.push(`- **runner:** v${receipt.run.runner_version}`);
   const j = receipt.run.judge || {};
-  L.push(`- **judge:** ${j.samples || 1} samples/case, temperature ${j.temperature == null ? 'n/a (surface-controlled)' : j.temperature} (${j.sampling || 'single'})`);
+  L.push(`- **judge:** ${j.samples || 1} samples/case, temperature ${j.temperature == null ? 'n/a' : j.temperature} (${j.sampling || 'single'})`);
   if (receipt.run.registry) L.push(`- **registry:** ${receipt.run.registry}   **transcripts:** ${receipt.run.transcripts || 'hashes-only'}`);
   L.push(`- **skill content_hash:** \`${receipt.skill.content_hash.slice(0, 16)}…\``);
   L.push(`- **suite:** ${receipt.suite.case_count} cases (${receipt.suite.format})`);
@@ -203,6 +276,10 @@ function summarizeReceipt(receipt) {
   const cmp = receipt.comparison;
   const aggs = receipt.results.aggregates;
   const sign = cmp.delta >= 0 ? '+' : '';
+  if (receipt.run.status === 'incomplete') {
+    L.push(`> ⏱ **INCOMPLETE** — ${receipt.run.failed_case_count} case(s) failed (timed out after retries) and are EXCLUDED from the aggregates below; this receipt must not be used to compute a drift/durability verdict.`);
+    L.push('');
+  }
   L.push(`with_skill **${band(aggs.with_skill.mean_score, aggs.with_skill.stddev)}** vs baseline **${band(aggs.baseline.mean_score, aggs.baseline.stddev)}**`);
   L.push('');
   L.push(`skill lift **${sign}${cmp.delta.toFixed(3)}** (combined uncertainty ± ${cmp.delta_uncertainty.toFixed(3)})`);
@@ -212,6 +289,10 @@ function summarizeReceipt(receipt) {
   L.push(`| case | mode | outcome | mean ± stddev | judge reason |`);
   L.push(`|---|---|---|---|---|`);
   for (const c of receipt.results.cases) {
+    if (c.case_status === 'failed_timeout') {
+      L.push(`| \`${c.id}\` | ${c.mode} | ⏱ failed_timeout | — (not measured) | ${c.reason || 'timed out'} |`);
+      continue;
+    }
     const flag = c.outcome === 'borderline' ? ' ⚠' : '';
     L.push(`| \`${c.id}\` | ${c.mode} | ${c.outcome}${flag} | ${band(c.mean, c.stddev || 0)} | ${c.reason || ''} |`);
   }

package/lib/skill.js

@@ -59,7 +59,13 @@ function loadSkill(skillDir) {
   }
   const suiteRaw = JSON.parse(fs.readFileSync(suitePath, 'utf8'));
   const cases = normalizeCases(suiteRaw);
-  const suiteHash = sha256Canonical(cases);
+  // suite_hash is over the CORE case fields only ({id, prompt, rubric,
+  // pass_threshold}); optional annotations (checks, and the claim/grounding the
+  // gate reads straight from the raw suite) are excluded so adding them never
+  // disturbs a receipt's suite_hash. See spec/RECEIPT.md § suite.
+  const suiteHash = sha256Canonical(cases.map((c) => ({
+    id: c.id, prompt: c.prompt, rubric: c.rubric, pass_threshold: c.pass_threshold,
+  })));
 
   return {
     dir,
@@ -110,7 +116,11 @@ function normalizeCases(raw) {
     if (!rubric) throw new Error(`case "${id}" is missing a rubric/criteria/expected`);
     const threshold = typeof c.pass_threshold === 'number' ? c.pass_threshold
       : typeof c.threshold === 'number' ? c.threshold : 0.7;
-    return { id, prompt: String(prompt), rubric: String(rubric), pass_threshold: threshold };
+    const norm = { id, prompt: String(prompt), rubric: String(rubric), pass_threshold: threshold };
+    // Optional deterministic post-checks (v0.3.1). Carried through for the runner
+    // but EXCLUDED from suite_hash (see loadSkill) so they never disturb a receipt.
+    if (Array.isArray(c.checks) && c.checks.length) norm.checks = c.checks;
+    return norm;
   });
 }
 

package/lib/skillCost.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+// Value-per-token axis.
+//
+// A skill is not free: its SKILL.md is prepended to every generation, so a skill
+// that lifts scores by +0.10 for 400 tokens is a very different proposition from
+// one that lifts +0.10 for 6,000 tokens. Driftproof reports each skill's lift
+// (delta) BOTH raw AND normalized per 1,000 skill tokens.
+//
+// Token estimate: a coarse `ceil(chars / 4)` proxy — the standard rough rule for
+// English text, NOT a model tokenizer (no tiktoken dependency; the number is a
+// consistent proxy for comparing skills, not a billing figure). Documented on
+// docs/methodology.html.
+
+const CHARS_PER_TOKEN = 4;
+
+function estimateTokens(text) {
+  const s = String(text || '');
+  if (!s.length) return 0;
+  return Math.ceil(s.length / CHARS_PER_TOKEN);
+}
+
+// Lift per 1,000 skill tokens: delta / (skillTokens / 1000). Null when the token
+// count is unknown or zero (avoids a divide-by-zero masquerading as infinite value).
+function deltaPer1kTokens(delta, skillTokens) {
+  if (typeof delta !== 'number' || !skillTokens || skillTokens <= 0) return null;
+  return Math.round((delta / (skillTokens / 1000)) * 1e4) / 1e4;
+}
+
+module.exports = { estimateTokens, deltaPer1kTokens, CHARS_PER_TOKEN };

package/lib/stub.js

@@ -39,16 +39,37 @@ function stubComplete({ system, prompt }) {
       pass: score >= 0.7,
       reason: `stub judge (DRIFTPROOF_STUB): ${helped ? 'with-skill marker present' : 'baseline'}`,
     };
-    return { text: JSON.stringify(body), usage: null };
+    return { text: JSON.stringify(body), usage: stubUsage({ kind: 'judge', prompt }) };
   }
   // Generation call: canned, marked by mode.
   const mark = system ? MARK_SKILL : MARK_BASE;
   const text = `${mark}\nfeat(stub): canned offline generation for CI (no model was called)`;
-  return { text, usage: null };
+  return { text, usage: stubUsage({ kind: 'gen', system, prompt }) };
+}
+
+// v0.4: deterministic synthetic usage, so a zero-model-call stub run still
+// exercises the whole economics path (usage → pricing snapshot → derived cost/
+// latency fields → the value report's three axes). The numbers are SYNTHETIC and
+// deliberately shaped like the real surfaces: a large fixed harness preamble that
+// is identical in both arms, plus the with-skill arm's extra SKILL.md input and
+// its slightly longer, slower output. No randomness — same input, same usage.
+const STUB_HARNESS_PREAMBLE_TOKENS = 20000;   // the fixed, arm-identical overhead
+function stubUsage({ kind, system, prompt }) {
+  const promptTokens = Math.ceil(String(prompt || '').length / 4);
+  if (kind === 'judge') {
+    return { input_tokens: 1200 + promptTokens, output_tokens: 60, cached_tokens: 800, wall_ms: 900 };
+  }
+  const skillTokens = system ? Math.ceil(String(system).length / 4) : 0;
+  return {
+    input_tokens: STUB_HARNESS_PREAMBLE_TOKENS + promptTokens + skillTokens,
+    output_tokens: system ? 420 : 350,
+    cached_tokens: STUB_HARNESS_PREAMBLE_TOKENS,
+    wall_ms: system ? 4200 : 3600,
+  };
 }
 
 function stubEnabled() {
   return process.env.DRIFTPROOF_STUB === '1';
 }
 
-module.exports = { stubComplete, stubEnabled, MARK_SKILL, MARK_BASE };
+module.exports = { stubComplete, stubEnabled, stubUsage, MARK_SKILL, MARK_BASE, STUB_HARNESS_PREAMBLE_TOKENS };

package/lib/usage.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+// Usage capture — normalizing what each surface reports about a single call.
+//
+// Every lane reports token usage in its own shape, and two of them (the CLI
+// lanes) were previously discarding it entirely: the `claude -p` default text
+// output carries no usage block at all, and `codex exec --json` streams usage on
+// stdout that we were routing to /dev/null. Spec v0.4 captures it.
+//
+// ONE normalized shape, so three substrates are comparable:
+//
+//   { input_tokens, output_tokens, cached_tokens, wall_ms }
+//
+//   input_tokens   TOTAL input presented to the model for this call, INCLUDING
+//                  any portion served from cache. This is the field that most
+//                  needs normalizing: the surfaces disagree about it (below).
+//   cached_tokens  the portion of input_tokens served from cache (null when the
+//                  surface does not surface it — never guessed, never 0-filled).
+//   output_tokens  tokens generated, INCLUDING reasoning/thinking tokens where
+//                  the surface bundles them (both CLI lanes do; the split is
+//                  reported by the surface but deliberately not modelled here —
+//                  see the disclosure in REPORT-STYLE.md).
+//   wall_ms        measured BY US around the call (see lib/provider), not taken
+//                  from the surface. It is the only field whose definition is
+//                  identical across lanes, which is exactly why latency is
+//                  reported as an observed, surface-disclosed number.
+//
+// THE INPUT-TOKEN DISAGREEMENT (verified against real output, 2026-08-18):
+//   - `claude -p --output-format json` reports input_tokens EXCLUDING cache:
+//     total input = input_tokens + cache_creation_input_tokens + cache_read_input_tokens.
+//     (Observed: 10 + 6,974 + 18,134 = 25,118 for a two-word prompt.)
+//   - `codex exec --json` reports input_tokens INCLUDING cache, with
+//     cached_input_tokens as a SUBSET of it. (Observed: 10,807 of which 4,480 cached.)
+//   Normalizing to "total including cache" makes the two comparable; the raw
+//   fixtures both parsers are tested against are checked in under tests/fixtures/.
+//
+// Both CLI surfaces prepend a large fixed harness preamble that we do not
+// control (~25k tokens on claude-cli, ~11k on codex). It is IDENTICAL in the
+// with-skill and baseline arms, so it cancels in the incremental (Δ) figures —
+// which is why Δcost is the honest axis and absolute per-call cost is not.
+
+function n(x) { return Number.isFinite(Number(x)) ? Number(x) : 0; }
+
+// The empty/unknown usage record. Deliberately null (not zeros) so "the surface
+// did not tell us" never reads as "the call cost nothing".
+function emptyUsage() {
+  return { input_tokens: null, output_tokens: null, cached_tokens: null, wall_ms: null };
+}
+
+function hasUsage(u) {
+  return !!(u && (u.input_tokens != null || u.output_tokens != null));
+}
+
+// ── anthropic/cli — `claude -p --output-format json` ──────────────────────────
+// The whole call is one JSON object; `result` carries the final text and `usage`
+// the token counts. input_tokens EXCLUDES cache, so both cache fields are added
+// back to reach the total actually presented to the model.
+function parseClaudeCliJson(stdout) {
+  let j;
+  try { j = JSON.parse(String(stdout || '')); } catch (_e) { return null; }
+  if (!j || typeof j !== 'object') return null;
+  const u = j.usage || {};
+  const cacheRead = n(u.cache_read_input_tokens);
+  const cacheCreate = n(u.cache_creation_input_tokens);
+  const usage = {
+    input_tokens: n(u.input_tokens) + cacheRead + cacheCreate,
+    output_tokens: n(u.output_tokens),
+    // Cache READ is the portion genuinely served from cache. Cache CREATION was
+    // processed fresh this call (and billed at a premium), so it is not cached.
+    cached_tokens: cacheRead,
+    wall_ms: null,
+  };
+  return {
+    text: typeof j.result === 'string' ? j.result : '',
+    usage,
+    isError: j.is_error === true,
+    // The CLI reports its own dollar figure. Recorded here for completeness but
+    // NOT used: costs are computed uniformly from the frozen pricing snapshot so
+    // three substrates are on one basis (see lib/value.js).
+    surfaceReportedCostUsd: Number.isFinite(Number(j.total_cost_usd)) ? Number(j.total_cost_usd) : null,
+  };
+}
+
+// ── openai/cli — `codex exec --json` JSONL event stream ───────────────────────
+// One JSON object per line. Usage rides the terminal `turn.completed` event;
+// input_tokens already INCLUDES cached_input_tokens. Unparseable lines are
+// skipped (the stream also carries progress events we do not model).
+function parseCodexJsonl(stdout) {
+  const lines = String(stdout || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  let usage = null;
+  let text = '';
+  for (const line of lines) {
+    let ev;
+    try { ev = JSON.parse(line); } catch (_e) { continue; }
+    if (!ev || typeof ev !== 'object') continue;
+    if (ev.type === 'turn.completed' && ev.usage) {
+      const u = ev.usage;
+      usage = {
+        input_tokens: n(u.input_tokens),          // already total (cache included)
+        output_tokens: n(u.output_tokens),        // includes reasoning_output_tokens
+        cached_tokens: u.cached_input_tokens == null ? null : n(u.cached_input_tokens),
+        wall_ms: null,
+      };
+    }
+    // The final message is normally read from the -o file; this is a fallback.
+    if (ev.type === 'item.completed' && ev.item && ev.item.type === 'agent_message' && typeof ev.item.text === 'string') {
+      text = ev.item.text;
+    }
+  }
+  return { usage, text };
+}
+
+// ── anthropic/api ─────────────────────────────────────────────────────────────
+// The Messages API reports input_tokens EXCLUDING cache, same as the CLI.
+function parseAnthropicApiUsage(u) {
+  if (!u) return emptyUsage();
+  const cacheRead = n(u.cache_read_input_tokens);
+  const cacheCreate = n(u.cache_creation_input_tokens);
+  return {
+    input_tokens: n(u.input_tokens) + cacheRead + cacheCreate,
+    output_tokens: n(u.output_tokens),
+    cached_tokens: u.cache_read_input_tokens == null ? null : cacheRead,
+    wall_ms: null,
+  };
+}
+
+// ── openai/api (Chat Completions-compatible) ──────────────────────────────────
+// prompt_tokens is the total; the cached portion, when present, is nested under
+// prompt_tokens_details.cached_tokens.
+function parseOpenaiApiUsage(u) {
+  if (!u) return emptyUsage();
+  const details = u.prompt_tokens_details || {};
+  return {
+    input_tokens: n(u.prompt_tokens),
+    output_tokens: n(u.completion_tokens),
+    cached_tokens: details.cached_tokens == null ? null : n(details.cached_tokens),
+    wall_ms: null,
+  };
+}
+
+// Sum a list of usage records into one (used for the N judge samples of a case).
+// Null-safe: unknown fields stay null unless at least one record reported them.
+function sumUsage(list) {
+  const records = (list || []).filter(Boolean);
+  if (!records.length) return emptyUsage();
+  const out = { input_tokens: null, output_tokens: null, cached_tokens: null, wall_ms: null };
+  for (const key of ['input_tokens', 'output_tokens', 'cached_tokens', 'wall_ms']) {
+    const present = records.filter((r) => r[key] != null);
+    if (present.length) out[key] = present.reduce((a, r) => a + n(r[key]), 0);
+  }
+  return out;
+}
+
+// Round a usage record's fields to integers (tokens and ms are whole units).
+function normalizeUsage(u) {
+  if (!u) return emptyUsage();
+  const out = emptyUsage();
+  for (const key of ['input_tokens', 'output_tokens', 'cached_tokens', 'wall_ms']) {
+    if (u[key] != null && Number.isFinite(Number(u[key]))) out[key] = Math.round(Number(u[key]));
+  }
+  return out;
+}
+
+module.exports = {
+  emptyUsage, hasUsage, sumUsage, normalizeUsage,
+  parseClaudeCliJson, parseCodexJsonl, parseAnthropicApiUsage, parseOpenaiApiUsage,
+};