@bongos/core 1.17.0

package/src/bongos/llm-cache.js

@@ -0,0 +1,260 @@
+// src/bongos/llm-cache.js — System 5 (task 1359): content-addressed LLM result
+// cache. Memoizes idempotent model runs at the shared spawn primitive
+// (grader.runSubagent) so an identical (normalized-prompt, model, task_type,
+// git-tree-sha) invocation over UNCHANGED inputs replays a stored result at zero
+// new tokens. v1 is EXACT-MATCH (semantic match deferred — ADR, task 1360).
+//
+// Validity is bound to the git SHA of the embedded inputs (scope_sha): a stale
+// answer is only ever returned when the inputs are provably unchanged. The
+// per-task-type normalizer registry is the OTHER correctness surface — it strips
+// only provably-volatile lines (timestamps, run-ids, the architect's `version=`
+// echo) so two logically-identical prompts hash the same WITHOUT ever collapsing
+// two different requests.
+//
+// The pure helpers (sha256, normalizers, computeCacheKey, makeCacheSpec,
+// scopeShaFor) are unit-tested DB-free (tests/llm-cache.mjs). The lookup/store/
+// withCache helpers touch Postgres and are best-effort: any DB error degrades to
+// "cache miss / no store", never breaking the caller (a cache must never be able
+// to take down the thing it accelerates).
+
+'use strict';
+
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const { pool } = require('./pool');
+
+// --- transport (System 5 transport fix, task 1381) ---------------------------
+// The cache DB lives on the droplet (peer-socket pool). Its consumers
+// (architect-audit, onboarding-analyze) run as CLI/cron on BUILDER machines where
+// the pool is unreachable — so before this, every cache op silently degraded to
+// miss/no-store and the cache could never hit. Fix: keep the pool as the server
+// fast path; fall back to the GDS API when the pool is unavailable. The core
+// NEVER statically requires the CLI layer (scripts/gds/cli-lib.js) — that would
+// drag session/fetch plumbing into the always-on server and cross the core↔host
+// boundary the fitness gate guards. Instead the consumer (which already imports
+// cli-lib) INJECTS apiCall via setApiFallback(). If it's never set, behaviour is
+// exactly today's pool-only best-effort.
+let _apiCall = null;        // injected: (method, path, body, opts) => {ok,status,data}
+let _poolReachable = null;  // memoized SELECT-1 probe: `true` is sticky; false is never memoized (re-probe)
+
+function setApiFallback(fn) { _apiCall = typeof fn === 'function' ? fn : null; }
+function _resetTransportForTests() { _apiCall = null; _poolReachable = null; }
+
+// Is the in-process pool usable? On the droplet → true (peer socket), memoized
+// sticky. On a builder box → false (no DB) and we route through the injected
+// apiCall. We deliberately do NOT memoize a `false` result (the critique's
+// fix): a transient boot-time blip must never permanently disable the server
+// cache — so a false just re-probes next call. The probe fails fast on a missing
+// socket (ENOENT/ECONNREFUSED), not a long TCP timeout.
+async function poolReachable() {
+  if (_poolReachable === true) return true;
+  try { await pool.query('SELECT 1'); _poolReachable = true; return true; }
+  catch (_) { return false; }
+}
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(String(s == null ? '' : s), 'utf8').digest('hex');
+}
+
+// Lines that are provably volatile between two otherwise-identical runs. Stripping
+// them is what lets a re-run of an unchanged audit hash identically. Conservative
+// by design — only patterns that cannot carry request meaning.
+const VOLATILE_LINE = [
+  /\bversion\s*=\s*\S+/i,                 // the architect prompt's version= echo
+  /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/,     // ISO-ish timestamps
+  /\brun[_-]?id\b/i,
+  /\bgenerated[_ ]?at\b/i,
+];
+
+function stripVolatile(text) {
+  return String(text == null ? '' : text)
+    .split('\n')
+    .filter((l) => !VOLATILE_LINE.some((re) => re.test(l)))
+    .join('\n')
+    .trim();
+}
+
+// Per-task-type normalizers. Default trims; the known idempotent producers strip
+// volatile lines. Register more via registerNormalizer (kept open for new crons).
+const NORMALIZERS = {
+  default: (p) => String(p == null ? '' : p).trim(),
+  'architect-audit': stripVolatile,
+  'onboarding-analyze': stripVolatile,
+};
+function registerNormalizer(taskType, fn) { NORMALIZERS[taskType] = fn; }
+function normalize(taskType, prompt) {
+  const fn = NORMALIZERS[taskType] || NORMALIZERS.default;
+  return fn(prompt);
+}
+
+// The content address: sha256 over the normalized prompt + the dimensions that
+// change correctness (model, task_type, the input git-tree sha). NUL-joined so
+// no field can bleed into the next.
+function computeCacheKey({ prompt, model, task_type, scope_sha } = {}) {
+  const normalized = normalize(task_type, prompt);
+  return sha256([normalized, model || '', task_type || '', scope_sha || ''].join('\u0000'));
+}
+
+// A complete cache spec the caller hands to runSubagentCached / withCache.
+function makeCacheSpec({ prompt, model, task_type, scope_sha, owner_builder_id = null, ttl_ms = null } = {}) {
+  return {
+    key: computeCacheKey({ prompt, model, task_type, scope_sha }),
+    prompt_hash: sha256(normalize(task_type, prompt)),
+    model: model || null,
+    task_type: task_type || null,
+    scope_sha: scope_sha || null,
+    owner_builder_id: owner_builder_id == null ? null : Number(owner_builder_id),
+    ttl_ms: ttl_ms == null ? null : Number(ttl_ms),
+  };
+}
+
+// git tree/blob SHA of the embedded inputs — the invalidation key. A directory
+// path resolves to its tree SHA (changes iff any file under it changes); a file
+// to its blob SHA. runner injectable for tests. A path absent from HEAD → MISSING
+// (so an unborn/typo'd path never silently collides with a real one).
+function scopeShaFor(paths, { runner, cwd } = {}) {
+  const run = runner || ((cmd) => execSync(cmd, { encoding: 'utf8', cwd: cwd || process.cwd() }).trim());
+  const parts = [];
+  for (const p of paths || []) {
+    let sha = 'MISSING';
+    try { sha = run(`git rev-parse HEAD:${p}`) || 'MISSING'; } catch (_) { sha = 'MISSING'; }
+    parts.push(`${p}:${sha}`);
+  }
+  return sha256(parts.join('\n'));
+}
+
+// --- DB (best-effort; a cache error degrades to miss/no-store) ---------------
+
+// Look up a live (unexpired) entry by key. On a hit, atomically bump hit_count +
+// last_hit_at and return the stored result. Returns null on miss or any error.
+async function lookup(cacheKey, { tokensSavedEst = 0 } = {}) {
+  if (!cacheKey) return null;
+  const est = Math.max(0, Number(tokensSavedEst) || 0);
+  // Pool fast path (server).
+  if (await poolReachable()) {
+    try {
+      const { rows } = await pool.query(
+        `UPDATE llm_cache
+            SET hit_count = hit_count + 1,
+                last_hit_at = now(),
+                tokens_saved_est = tokens_saved_est + $2
+          WHERE cache_key = $1
+            AND (expires_at IS NULL OR expires_at > now())
+          RETURNING result_stdout, result_cost_usd, hit_count, task_type, scope_sha, model`,
+        [cacheKey, est]
+      );
+      return rows[0] || null;
+    } catch (_) { /* fall through to API if injected, else miss */ }
+  }
+  // API fallback (builder machine). Best-effort: any error → miss. allowUnauthenticated
+  // so an expired session degrades to a miss instead of process.exit — a cache
+  // must never take down the thing it accelerates.
+  if (_apiCall) {
+    try {
+      const r = await _apiCall('POST', '/api/gds/llm-cache/lookup',
+        { cache_key: cacheKey, tokens_saved_est: est }, { allowUnauthenticated: true });
+      if (r && r.ok && r.data && r.data.hit) return r.data.result || null;
+    } catch (_) { /* network/auth error → miss */ }
+  }
+  return null; // missing table / unreachable / no fallback → treat as a miss
+}
+
+// Store a freshly-produced result. Upsert so a re-store refreshes. Best-effort.
+async function store(spec, { resultStdout, resultCostUsd = 0 } = {}) {
+  if (!spec || !spec.key || resultStdout == null) return false;
+  // Pool fast path (server).
+  if (await poolReachable()) {
+    const expiresExpr = spec.ttl_ms ? `now() + ($9::bigint * interval '1 millisecond')` : 'NULL';
+    try {
+      await pool.query(
+        `INSERT INTO llm_cache
+           (cache_key, prompt_hash, model, task_type, scope_sha, result_stdout, result_cost_usd, owner_builder_id, expires_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, ${expiresExpr})
+         ON CONFLICT (cache_key) DO UPDATE
+           SET result_stdout = EXCLUDED.result_stdout,
+               result_cost_usd = EXCLUDED.result_cost_usd,
+               last_hit_at = now()`,
+        spec.ttl_ms
+          ? [spec.key, spec.prompt_hash, spec.model, spec.task_type, spec.scope_sha, resultStdout, Number(resultCostUsd) || 0, spec.owner_builder_id, spec.ttl_ms]
+          : [spec.key, spec.prompt_hash, spec.model, spec.task_type, spec.scope_sha, resultStdout, Number(resultCostUsd) || 0, spec.owner_builder_id]
+      );
+      return true;
+    } catch (_) { /* fall through to API if injected, else no-store */ }
+  }
+  // API fallback (builder machine). The route re-validates the spec + clamps the
+  // cost server-side; best-effort: any error → no-store (never throws).
+  if (_apiCall) {
+    try {
+      const r = await _apiCall('POST', '/api/gds/llm-cache/store',
+        { spec, result_stdout: resultStdout, result_cost_usd: Number(resultCostUsd) || 0 },
+        { allowUnauthenticated: true });
+      return !!(r && r.ok && r.data && r.data.stored);
+    } catch (_) { return false; }
+  }
+  return false;
+}
+
+// Record a hit as a SAVING in System 1's counterfactual ledger (cost_baseline,
+// ADR 0075): baseline_usd = what the run WOULD have cost, amount_usd = 0 (the hit
+// was free). source_ref is per-hit-unique so each replay counts once. Best-effort.
+async function recordSaving(spec, { resultCostUsd = 0, hitCount = 0 } = {}) {
+  const baseline = Number(resultCostUsd) || 0;
+  if (!spec || !spec.key || baseline <= 0) return; // nothing priced → nothing to claim
+  // Pool-ONLY by design — deliberately NO API fallback. The saving lands in the
+  // PUBLIC cost ledger (cost_baseline → /public/cost-summary), so per the
+  // migration-124 contract it must be a server-side-priced figure, never a
+  // client-supplied dollar amount. Off-server (builder machine) this no-ops: a
+  // System-5 hit is still RECORDED (hit_count bumped in lookup), but its $ saving
+  // is not booked until a follow-up forwards the subagent's token usage so /store
+  // can re-price it server-side via priceUsage (task 1381 notes → follow-up).
+  // Booking nothing here is correct; booking a client figure would break the
+  // contract. The poolReachable guard also avoids a failed-query log on builders.
+  if (!(await poolReachable())) return;
+  try {
+    await pool.query(
+      `INSERT INTO cost_baseline (system, baseline_usd, amount_usd, source_ref, description)
+       VALUES ('system5:llm-cache', $1, 0, $2, $3)
+       ON CONFLICT (system, source_ref) WHERE source_ref IS NOT NULL DO NOTHING`,
+      [baseline, `${spec.key}:${hitCount}`, `llm-cache hit (${spec.task_type || 'unknown'})`]
+    );
+  } catch (_) { /* cost_baseline absent (pre-deploy) or transient → skip */ }
+}
+
+// Orchestrator: hit → return cached at $0 (+ record the saving); miss → run the
+// producer, store on a clean result, return it. `producer` resolves to a
+// runSubagent-shaped object { stdout, exit_code, cost_usd }.
+async function withCache(spec, producer) {
+  if (!spec || !spec.key) return { ...(await producer()), cached: false };
+  const hit = await lookup(spec.key);
+  if (hit) {
+    await recordSaving(spec, { resultCostUsd: Number(hit.result_cost_usd) || 0, hitCount: hit.hit_count });
+    return { stdout: hit.result_stdout, stderr: '', run_ms: 0, exit_code: 0, cost_usd: 0, cached: true };
+  }
+  const res = await producer();
+  // Only ever cache a clean, completed run — never a timeout or a non-zero exit.
+  if (res && res.exit_code === 0 && res.stdout != null) {
+    await store(spec, { resultStdout: res.stdout, resultCostUsd: Number(res.cost_usd) || 0 });
+  }
+  return { ...res, cached: false };
+}
+
+module.exports = {
+  // pure (unit-tested)
+  sha256,
+  stripVolatile,
+  NORMALIZERS,
+  registerNormalizer,
+  normalize,
+  computeCacheKey,
+  makeCacheSpec,
+  scopeShaFor,
+  // transport (System 5 transport fix, task 1381)
+  setApiFallback,
+  poolReachable,
+  _resetTransportForTests,
+  // DB (best-effort)
+  lookup,
+  store,
+  recordSaving,
+  withCache,
+};

package/src/bongos/llm-pricing.js

@@ -0,0 +1,220 @@
+// src/bongos/llm-pricing.js — ADR 0028 path 2 (#560).
+//
+// Prices a Claude transcript `usage` block into USD. The interactive builder
+// session is not a `claude -p` subprocess, so (unlike the grader path, #486)
+// there is no `total_cost_usd` envelope — the session transcript JSONL carries
+// only TOKEN counts. This module is the small, auditable table + pure function
+// that turns those tokens into dollars.
+//
+// Pure: no I/O, no Date.now(), no network. Imported by scripts/gds/session-cost.js
+// (and available as the grader's envelope-absent fallback). Unit-tested in
+// tests/llm-pricing.mjs.
+//
+// PRICES are USD per MILLION tokens (Anthropic public list price). When prices
+// change this table is the single edit point; a price change is `decision`-worthy
+// and gets its own task. Cache multipliers follow Anthropic's published model:
+//   - cache WRITE 5-minute TTL = 1.25× base input
+//   - cache WRITE 1-hour TTL   = 2.00× base input
+//   - cache READ               = 0.10× base input
+//
+// Pricing is FLAT across the full context window — current Opus 4.8 and Sonnet
+// 4.6 provide the 1M window at standard pricing with NO long-context (>200K)
+// premium (verified against platform.claude.com models overview, 2026-06-20).
+// So there is no per-tier "1M premium" table to maintain; do not add one unless
+// Anthropic introduces a long-context surcharge.
+//
+// VERIFIED 2026-06-20 against the live Anthropic models/pricing page (GDS-V4
+// task 1343): the table below had drifted to Opus 4.1-era pricing ($15/$75),
+// which 3× over-priced the platform's Opus 4.8 interactive sessions and inflated
+// the recorded cost_log ~3× on the opus-dominated spend. Corrected to the
+// current per-model list rates:
+//   - opus   = Claude Opus 4.8 / 4.7  ($5 in / $25 out)   [was $15/$75]
+//   - sonnet = Claude Sonnet 4.6      ($3 in / $15 out)   [unchanged — was correct]
+//   - haiku  = Claude Haiku 4.5       ($1 in / $5 out)    [was $0.8/$4 = Haiku 3.5]
+// Family-based pricing assumes the CURRENT model in each family (what this
+// instance runs). A historical id like claude-opus-4-1 ($15/$75) would be
+// mis-priced low here — acceptable: the platform only runs 4.x-current models.
+const PRICES = {
+  // family : { input, output, cache_write_5m, cache_write_1h, cache_read }  (USD / 1e6 tokens)
+  opus:   { input: 5,  output: 25, cache_write_5m: 6.25, cache_write_1h: 10, cache_read: 0.5 },
+  sonnet: { input: 3,  output: 15, cache_write_5m: 3.75, cache_write_1h: 6,  cache_read: 0.3 },
+  haiku:  { input: 1,  output: 5,  cache_write_5m: 1.25, cache_write_1h: 2,  cache_read: 0.1 },
+};
+
+// Resolve a model id (e.g. 'claude-opus-4-8', 'claude-sonnet-4-6',
+// 'claude-haiku-4-5') to a price family by substring — mirrors grader.js's
+// family-token convention (all live Claude ids contain one of these three).
+// Unknown → null (caller decides: we conservatively price at the opus rate AND
+// flag it, so an unpriced model is loud, never silently $0).
+function familyFor(model) {
+  const m = String(model || '').toLowerCase();
+  if (m.includes('opus')) return 'opus';
+  if (m.includes('sonnet')) return 'sonnet';
+  if (m.includes('haiku')) return 'haiku';
+  return null;
+}
+
+/**
+ * Price one usage block.
+ * @param {string} model - message.model from a transcript line.
+ * @param {object} usage - message.usage: { input_tokens, output_tokens,
+ *   cache_read_input_tokens, cache_creation_input_tokens,
+ *   cache_creation?: { ephemeral_5m_input_tokens, ephemeral_1h_input_tokens } }
+ * @returns {{ usd:number, family:string, priced_as:string, unknown_model:boolean,
+ *   components:{ input, output, cache_read, cache_write_5m, cache_write_1h } }}
+ *   where each component is { tokens:number, usd:number } — the per-tier split the
+ *   cost ledger persists (GDS-V4 task 1343/1344) so spend can be broken down by
+ *   tier (cache_read is the dominant marathon-session cost). `usd` is their sum.
+ */
+function priceUsage(model, usage) {
+  const u = usage || {};
+  const fam = familyFor(model);
+  const unknownModel = fam === null;
+  const priceFamily = fam || 'opus'; // conservative default for an unrecognized model
+  const p = PRICES[priceFamily];
+
+  const input = Number(u.input_tokens) || 0;          // uncached input
+  const output = Number(u.output_tokens) || 0;
+  const cacheRead = Number(u.cache_read_input_tokens) || 0;
+  const cacheCreateTotal = Number(u.cache_creation_input_tokens) || 0;
+
+  // Prefer the 5m/1h breakdown when present; otherwise treat the whole
+  // cache-creation lump at the 5m rate (the common default TTL).
+  const br = u.cache_creation || {};
+  const has5 = u.cache_creation && u.cache_creation.ephemeral_5m_input_tokens != null;
+  const has1h = u.cache_creation && u.cache_creation.ephemeral_1h_input_tokens != null;
+  let write5m, write1h;
+  if (has5 || has1h) {
+    write5m = Number(br.ephemeral_5m_input_tokens) || 0;
+    write1h = Number(br.ephemeral_1h_input_tokens) || 0;
+    // The breakdown may not enumerate every creation token. cache_creation_input_tokens
+    // is the authoritative total — fold any remainder beyond the 5m+1h split into
+    // the 5m tier so those tokens are still priced rather than silently dropped.
+    const remainder = cacheCreateTotal - write5m - write1h;
+    if (remainder > 0) write5m += remainder;
+  } else {
+    write5m = cacheCreateTotal; // no breakdown → price the lump as 5m
+    write1h = 0;
+  }
+
+  // Per-tier component split (tokens + usd). The cost ledger persists these so a
+  // marathon session's spend can be attributed to the tier it actually came from
+  // (overwhelmingly cache_read — a large context re-read every turn for hours).
+  const components = {
+    input:          { tokens: input,     usd: (input * p.input) / 1e6 },
+    output:         { tokens: output,    usd: (output * p.output) / 1e6 },
+    cache_read:     { tokens: cacheRead, usd: (cacheRead * p.cache_read) / 1e6 },
+    cache_write_5m: { tokens: write5m,   usd: (write5m * p.cache_write_5m) / 1e6 },
+    cache_write_1h: { tokens: write1h,   usd: (write1h * p.cache_write_1h) / 1e6 },
+  };
+  const usd = components.input.usd + components.output.usd + components.cache_read.usd
+            + components.cache_write_5m.usd + components.cache_write_1h.usd;
+
+  return { usd, family: priceFamily, priced_as: priceFamily, unknown_model: unknownModel, components };
+}
+
+// Canonicalize a raw transcript model id into a stable grouping key so a session
+// emitting both 'claude-opus-4-8' and 'claude-opus-4-8[1m]' (or a '-fast' /
+// date-suffixed variant) collapses to ONE breakdown label. Pricing is family-
+// based (familyFor matches by substring), so the canonical id is only a tidy
+// label — the priced total is identical either way. Strips a trailing [..] tag,
+// a -fast suffix, and an 8-digit date suffix.
+function canonicalizeModelId(model) {
+  let s = String(model || '').trim();
+  s = s.replace(/\[[^\]]*\]\s*$/, ''); // drop trailing [1m] etc.
+  s = s.replace(/-fast$/i, '');        // drop -fast
+  s = s.replace(/-\d{8}$/, '');        // drop -YYYYMMDD date suffix
+  return s;
+}
+
+/**
+ * Price a per-model token-usage map into ONE total USD figure, server-side.
+ * This is the cost-plus reward's "true_cost_usd" source (task 1005, ADR 0054):
+ * it NEVER trusts a client dollar figure — it prices token counts via the
+ * locked PRICES table here.
+ *
+ * @param {Object<string, {input?:number,output?:number,cache_read?:number,cache_creation?:number}>} modelUsage
+ *   keyed by model id (raw or canonical). Field names are the session_records
+ *   model_usage shape (NOT the transcript *_input_tokens shape).
+ * @returns {{ true_cost_usd:number, per_model:Array, unknown_models:string[] }}
+ *   true_cost_usd rounded to 4 decimals (matches session-cost.js convention).
+ */
+function priceModelUsage(modelUsage) {
+  let usd = 0;
+  const perModel = [];
+  const unknown = [];
+  for (const [rawId, u] of Object.entries(modelUsage || {})) {
+    const usage = u || {};
+    // Map the model_usage field names → priceUsage's transcript field names.
+    // cache_creation here is a plain NUMBER (a lump), so we pass it as
+    // cache_creation_input_tokens (priced at the 5m rate) and never set the
+    // cache_creation breakdown object.
+    const priced = priceUsage(rawId, {
+      input_tokens: Number(usage.input) || 0,
+      output_tokens: Number(usage.output) || 0,
+      cache_read_input_tokens: Number(usage.cache_read) || 0,
+      cache_creation_input_tokens: Number(usage.cache_creation) || 0,
+    });
+    usd += priced.usd;
+    const label = canonicalizeModelId(rawId);
+    perModel.push({ model: label, usd: priced.usd, unknown_model: priced.unknown_model });
+    if (priced.unknown_model) unknown.push(label);
+  }
+  return {
+    true_cost_usd: Math.round(usd * 10000) / 10000,
+    per_model: perModel,
+    unknown_models: Array.from(new Set(unknown)),
+  };
+}
+
+/**
+ * Split a session_records `model_usage` map into the 4-tier USD breakdown the
+ * cost ledger persists, summed across every model. This is the SERVER-SIDE
+ * reconciler's pricing source (GDS-V4 task 1366): when System 1's client cost
+ * hook never posted a cost_log row (cloud box / overnight agent with no GDS
+ * token, or a digest-posted-but-cost-POST-failed session), the priceable
+ * model_usage already on the session_records row is re-priced here into the
+ * same fresh/cache_read/cache_write/output split logCost stores.
+ *
+ * Like priceModelUsage, model_usage has NO 5m/1h cache-creation breakdown — the
+ * `cache_creation` lump is priced at the 5m rate, exactly as session-cost.js
+ * priceTranscript does in its `else` branch (no breakdown → 5m). Unknown model
+ * ids are conservatively priced as opus AND collected, so an unpriced model is
+ * loud, never silently $0. Pure: no I/O, no Date.now().
+ *
+ * @param {Object<string, {input?:number,output?:number,cache_read?:number,cache_creation?:number}>} modelUsage
+ *   the session_records model_usage shape (NOT the transcript *_input_tokens shape).
+ * @returns {{ fresh_input_usd:number, cache_read_usd:number, cache_write_usd:number,
+ *   output_usd:number, total_usd:number, unknown_models:string[] }}
+ *   total_usd is the sum of the four tiers; each is the unrounded USD figure (the
+ *   reconciler rounds at the logCost call site, matching session-cost.js).
+ */
+function componentsFromModelUsage(modelUsage) {
+  let fresh_input_usd = 0;
+  let cache_read_usd = 0;
+  let cache_write_usd = 0;
+  let output_usd = 0;
+  const unknown = [];
+  for (const [rawId, u] of Object.entries(modelUsage || {})) {
+    const usage = u || {};
+    const fam = familyFor(rawId);
+    if (fam === null) unknown.push(canonicalizeModelId(rawId));
+    const p = PRICES[fam || 'opus']; // conservative default for an unrecognized model
+    fresh_input_usd += ((Number(usage.input) || 0) * p.input) / 1e6;
+    output_usd += ((Number(usage.output) || 0) * p.output) / 1e6;
+    cache_read_usd += ((Number(usage.cache_read) || 0) * p.cache_read) / 1e6;
+    // No 5m/1h split in model_usage → price the cache_creation lump at the 5m rate.
+    cache_write_usd += ((Number(usage.cache_creation) || 0) * p.cache_write_5m) / 1e6;
+  }
+  const total_usd = fresh_input_usd + cache_read_usd + cache_write_usd + output_usd;
+  return {
+    fresh_input_usd,
+    cache_read_usd,
+    cache_write_usd,
+    output_usd,
+    total_usd,
+    unknown_models: Array.from(new Set(unknown)),
+  };
+}
+
+module.exports = { PRICES, familyFor, priceUsage, canonicalizeModelId, priceModelUsage, componentsFromModelUsage };