@bglocation/tune-context 2.3.1 → 2.5.0

package/eval/pricing.mjs

@@ -0,0 +1,461 @@
+// pricing — dollars for the token components prompt-metrics.mjs emits.
+// See tasks/TASK-086.
+//
+// ┌───────────────────────────────────────────────────────────────────────────┐
+// │ THIS IS NOT AN INVOICE. It is API LIST PRICE for the same tokens.          │
+// │                                                                           │
+// │ Claude Code on a Pro or Max subscription is NOT billed per token — you pay │
+// │ the plan fee and consume plan limits. The published price table is API     │
+// │ pay-as-you-go pricing, so the figure below answers "what would this work   │
+// │ have cost through the API", not "what did you pay". On a $25 Pro plan you  │
+// │ paid $25 no matter what this says.                                        │
+// │                                                                           │
+// │ It stays the right yardstick for EPIC-009 anyway: comparing two arms needs │
+// │ a consumption measure that is proportional to work done, and list price is │
+// │ exactly that. It must never be printed as money spent — the fields are     │
+// │ named list_cost_* so the qualifier travels with the data.                  │
+// └───────────────────────────────────────────────────────────────────────────┘
+//
+// Why not a plain token sum: a random sample from a live transcript reads
+// `cache_read 31 650`, `cache_creation 13 890`, `input_tokens 2`. Cache reads
+// cost 0.1x base, so counting those as input inflates the figure ~10x — and
+// prints like a fact (EPIC-009, error class 1).
+//
+// Two rules run through everything below:
+//   • The price table is DATA — one table, dated, with its source, kept apart
+//     from the code that multiplies. Prices change; the claude-sonnet-5
+//     introductory price ends 2026-08-31 and has to end in the table too.
+//   • An unknown model is never priced at zero. The row gets `list_cost_usd:
+//     null` and a reason, and the reason is reported. A silent zero is a
+//     fabricated saving. `<synthetic>` entries are NOT this case: prompt-metrics
+//     drops them earlier as unbillable, so they never reach here and never
+//     pollute the counter that is supposed to signal a gap in the table.
+//
+// Refusal is whole-row. A row mixing a priced and an unpriced model is not
+// partially priced: a number that looks complete and covers half the turns is
+// worse than an admitted gap.
+
+/**
+ * Base prices per million tokens, USD. Verified line by line against the
+ * published table on 2026-07-30 (see PRICES.source).
+ *
+ * Only base input/output are stored. The published 5m-write, 1h-write and
+ * cache-hit columns are exactly base x 1.25 / x 2 / x 0.1 for every model in
+ * the table, so storing them would be storing the same fact twice — and two
+ * copies of a price are two prices that can disagree. `test/pricing.test.mjs`
+ * asserts the derivation reproduces the published columns.
+ *
+ * Keys are model ids as they appear in transcripts, with any -YYYYMMDD suffix
+ * stripped (see normalizeModel).
+ *
+ * `source` / `retrieved` at the top cover every entry that does not carry its
+ * own. Base and promo entries share one shape — `{ input, output, speeds? }` —
+ * so a promotional price can carry its own speed variants without a special
+ * case. `speeds` holds ABSOLUTE prices, not multipliers.
+ */
+export const PRICES = {
+  source: 'https://platform.claude.com/docs/en/about-claude/pricing',
+  retrieved: '2026-07-30',
+  unit: 'USD per 1M tokens, API list price (NOT subscription billing)',
+  models: {
+    // Fast mode is a research preview on Opus 5 and Opus 4.8 only, at $10/$50.
+    'claude-opus-5': { input: 5, output: 25, speeds: { fast: { input: 10, output: 50 } } },
+    'claude-opus-4-8': { input: 5, output: 25, speeds: { fast: { input: 10, output: 50 } } },
+    // Opus 4.7 rejects speed:"fast" outright, so no variant — a fast turn on it
+    // cannot exist, and if one appears the refusal is the correct answer.
+    'claude-opus-4-7': { input: 5, output: 25 },
+    // Opus 4.6 accepts speed:"fast" but runs and BILLS at standard rates, so the
+    // variant is deliberately equal to base rather than absent: refusing here
+    // would hide a turn we can price exactly.
+    'claude-opus-4-6': { input: 5, output: 25, speeds: { fast: { input: 5, output: 25 } } },
+    'claude-opus-4-5': { input: 5, output: 25 },
+    'claude-opus-4-1': { input: 15, output: 75 },
+    'claude-opus-4': { input: 15, output: 75 },
+    'claude-fable-5': { input: 10, output: 50 },
+    'claude-mythos-5': { input: 10, output: 50 },
+    'claude-sonnet-5': { input: 3, output: 15, promo: { input: 2, output: 10, through: '2026-08-31' } },
+    'claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude-sonnet-4-5': { input: 3, output: 15 },
+    'claude-sonnet-4': { input: 3, output: 15 },
+    'claude-haiku-4-5': { input: 1, output: 5 },
+    // Older naming order (claude-3-5-haiku-20241022), not claude-haiku-3-5.
+    'claude-3-5-haiku': { input: 0.8, output: 4 },
+  },
+};
+
+/**
+ * Cache multipliers on the INPUT price. The 5m/1h split is in
+ * `usage.cache_creation`, so a write is priced exactly rather than approximated
+ * — which is why prompt-metrics keeps `cache_write_unsplit` separate instead of
+ * folding undated writes into 5m and inventing up to 60% of a cost line.
+ */
+export const CACHE_MULTIPLIERS = { read: 0.1, write_5m: 1.25, write_1h: 2 };
+
+/**
+ * Service tier. Batch is half base price on both input and output — a valuation
+ * that ignores this field doubles the figure the moment anyone uses it.
+ * Measured values so far are `standard` and absent.
+ *
+ * Absent is not the same as unknown: a field Claude Code did not emit means the
+ * API default (standard), while a tier string that is NOT in this table is a
+ * tier we cannot price and must refuse. That refusal also catches `mixed`,
+ * which prompt-metrics writes when one turn spans two tiers.
+ */
+export const TIER_MULTIPLIERS = { standard: 1, batch: 0.5 };
+
+/**
+ * Data residency. `inference_geo: "us"` costs 1.1x across every token class on
+ * Claude 4.6 and later. The field is in the transcript (17 089 entries locally,
+ * all `not_available`, which is what models predating the parameter report), so
+ * this is handled rather than assumed — the one measured value must not be the
+ * only value the code survives.
+ */
+export const GEO_MULTIPLIERS = { global: 1, not_available: 1, us: 1.1 };
+
+/** $10 per 1,000 searches. Web FETCH is free — only search is billed. */
+export const WEB_SEARCH_USD = 0.01;
+
+/**
+ * The five priced classes, paired with the field each one is read from on a
+ * prompt-metrics row. Two vocabularies for one fact — `input`/`output` are cost
+ * classes, `input_tokens`/`output_tokens` are row fields — and this is the one
+ * place that knows the translation, because costOfTokens() below is already its
+ * other reader. Anything that folds tokens up (eval/analyze.mjs) reads it from
+ * here rather than retyping the list: a sixth class added to the collector's
+ * emptyTokens() must not be able to fall out of a downstream total by being
+ * forgotten in a hand-written array.
+ *
+ * `cache_write_unsplit` is deliberately NOT here. It is not a priced class — it
+ * is the admission that a write's TTL is unknown, and a row carrying it is
+ * refused rather than priced.
+ */
+export const TOKEN_CLASS_FIELDS = [
+  ['input', 'input_tokens'],
+  ['cache_read', 'cache_read'],
+  ['cache_write_5m', 'cache_write_5m'],
+  ['cache_write_1h', 'cache_write_1h'],
+  ['output', 'output_tokens'],
+];
+
+const TOKEN_CLASSES = TOKEN_CLASS_FIELDS.map(([className]) => className);
+
+function emptyCost() {
+  return Object.fromEntries(TOKEN_CLASSES.map((c) => [c, 0]));
+}
+
+/** Micro-dollar resolution. Enough for a per-prompt line, stable for tests. */
+function round6(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+
+/**
+ * The published total is the sum of the published classes — rounded FIRST, then
+ * added. Rounding the total separately from its parts is how a figure ends up
+ * disagreeing with its own breakdown, which EPIC-009 criterion 2 forbids
+ * outright; TASK-085 already had to fix the identical bug in the token totals.
+ *
+ * A class that did not come out a real number is refused rather than published.
+ * NaN reads as a number to every check that asks "is there a price here?", so a
+ * single such row used to be counted as PRICED and drag the whole run's total to
+ * NaN — a figure that prints as `$NaN` and, one `??` away, as a saving. Same rule
+ * as an unknown model: an amount we cannot compute is admitted, never shown.
+ */
+function priced(total) {
+  const list_cost_by_class = {};
+  for (const c of TOKEN_CLASSES) list_cost_by_class[c] = round6(total[c]);
+  if (!TOKEN_CLASSES.every((c) => Number.isFinite(list_cost_by_class[c]))) return unpriced('non-finite-cost');
+  return {
+    list_cost_usd: round6(TOKEN_CLASSES.reduce((s, c) => s + list_cost_by_class[c], 0)),
+    list_cost_by_class,
+    unpriced_reason: null,
+    unpriced_models: [],
+  };
+}
+
+/**
+ * `models` names only the models whose RATE could not be resolved — never the
+ * ones that merely rode along on a refused row. A mixed row is refused whole,
+ * so without this the report blames every model in it, and a reader is sent to
+ * add a price for a model that already has one. (Measured: 5 rows blamed
+ * claude-sonnet-5 and claude-fable-5 for claude-opus-4-8's absence.)
+ */
+function unpriced(reason, models = []) {
+  return { list_cost_usd: null, list_cost_by_class: null, unpriced_reason: reason, unpriced_models: models };
+}
+
+/**
+ * Model ids may carry a release date (`claude-haiku-4-5-20251001`). The table
+ * is keyed by family, so the suffix is stripped — a dated id must not land in
+ * `unpriced` for a model whose price we know.
+ */
+export function normalizeModel(model) {
+  return typeof model === 'string' ? model.replace(/-\d{8}$/, '') : '';
+}
+
+/**
+ * Table lookup that answers only about the table. A plain object also answers
+ * for everything on Object.prototype, so `PRICES.models['constructor']` hands
+ * back a function instead of undefined — and a function sails through an
+ * `if (!entry)` guard straight into the arithmetic. Model ids, tiers and geos
+ * all come from the transcript, i.e. from outside this file, so the lookups that
+ * decide whether we can price a row ask for OWN keys.
+ */
+function lookup(table, key) {
+  return typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : undefined;
+}
+
+function promoActive(promo, atMs) {
+  return atMs <= Date.parse(`${promo.through}T23:59:59.999Z`);
+}
+
+/**
+ * Price per MTok for a model at a point in time.
+ *
+ * `at` is the moment the prompt RAN, not the moment the report runs: a prompt
+ * from July priced in September must still get July's price, or re-running the
+ * same report over the same transcripts would quietly produce different money.
+ *
+ * @returns {{rate: {input:number, output:number}|null, reason: string|null}}
+ */
+export function rateFor(model, { speed = null, at = null } = {}) {
+  const entry = lookup(PRICES.models, normalizeModel(model));
+  if (!entry) return { rate: null, reason: 'unknown-model' };
+
+  let active = entry;
+  if (entry.promo) {
+    // Only date-dependent models need a date, so an undated row is refused
+    // exactly where the date would have changed the answer.
+    if (at === null || Number.isNaN(at)) return { rate: null, reason: 'unknown-date' };
+    if (promoActive(entry.promo, at)) active = entry.promo;
+  }
+
+  // Absent speed = standard, same reading as the tier and geo fields; an
+  // unrecognized speed (including `mixed`) is refused rather than guessed,
+  // because on an Opus model that guess is a factor of two.
+  const s = speed ?? 'standard';
+  const rate = s === 'standard' ? active : active.speeds && lookup(active.speeds, s);
+  if (!rate) return { rate: null, reason: 'unknown-speed' };
+  return { rate: { input: rate.input, output: rate.output }, reason: null };
+}
+
+/**
+ * Dollars for one token bucket, split by class. Never returns a single number
+ * on its own — EPIC-009 criterion 2 forbids a cost figure without its
+ * breakdown, and the cheapest way to honour that is to not produce one.
+ *
+ * Multipliers stack, as the published table says they do: cache class x
+ * service tier x inference geography.
+ */
+export function costOfTokens(tokens, rate, multiplier = 1) {
+  const perInput = (rate.input / 1e6) * multiplier;
+  const perOutput = (rate.output / 1e6) * multiplier;
+  return {
+    input: (tokens.input_tokens || 0) * perInput,
+    cache_read: (tokens.cache_read || 0) * perInput * CACHE_MULTIPLIERS.read,
+    cache_write_5m: (tokens.cache_write_5m || 0) * perInput * CACHE_MULTIPLIERS.write_5m,
+    cache_write_1h: (tokens.cache_write_1h || 0) * perInput * CACHE_MULTIPLIERS.write_1h,
+    output: (tokens.output_tokens || 0) * perOutput,
+  };
+}
+
+function bucketIsEmpty(t) {
+  return (
+    !(t.input_tokens > 0) &&
+    !(t.cache_read > 0) &&
+    !(t.cache_write_5m > 0) &&
+    !(t.cache_write_1h > 0) &&
+    !(t.cache_write_unsplit > 0) &&
+    !(t.output_tokens > 0)
+  );
+}
+
+/**
+ * Price one prompt-metrics row, at API list price.
+ *
+ * Priced per entry of `by_model`, not off the row's flat totals: a turn that
+ * switched models (measured — opus and sonnet inside one session) would
+ * otherwise be charged at one model's rate, and the opus/sonnet gap is 1.7x,
+ * larger than any effect this epic is looking for (error class 4).
+ *
+ * `speed`, `service_tier` and `inference_geo` stay row-level, so a turn that
+ * mixed them is refused rather than split on an assumption.
+ *
+ * A row with no billable tokens costs $0 and is NOT unpriced — a prompt with no
+ * API turn is free, not unknown, and must not dilute the counter that means
+ * "our table has a gap".
+ */
+export function priceRow(row, { at } = {}) {
+  const buckets = Object.entries(row?.by_model ?? {}).filter(([, t]) => !bucketIsEmpty(t));
+  if (buckets.length === 0) return priced(emptyCost());
+
+  const tier = lookup(TIER_MULTIPLIERS, row.service_tier ?? 'standard');
+  if (tier === undefined) return unpriced('unknown-tier');
+  const geo = lookup(GEO_MULTIPLIERS, row.inference_geo ?? 'global');
+  if (geo === undefined) return unpriced('unknown-geo');
+
+  const when = at !== undefined ? at : Date.parse(row.ts_submit ?? row.ts_end ?? '');
+  const total = emptyCost();
+  let refusal = null;
+  const offenders = [];
+  // Every bucket is examined even after the first refusal: the row is still
+  // refused whole, but the report can then name ALL the models it could not
+  // price instead of only the alphabetically first one.
+  for (const [model, tokens] of buckets) {
+    // The field exists precisely so a TTL is never guessed: 1.25x vs 2x is up
+    // to 60% of the write line. Zero on every entry measured to date. The model
+    // is not at fault here, so it is not named as an offender.
+    if (tokens.cache_write_unsplit > 0) {
+      refusal ??= 'cache-write-unsplit';
+      continue;
+    }
+    const { rate, reason } = rateFor(model, { speed: row.speed ?? null, at: when });
+    if (rate === null) {
+      refusal ??= reason;
+      offenders.push(model);
+      continue;
+    }
+    const part = costOfTokens(tokens, rate, tier * geo);
+    for (const c of TOKEN_CLASSES) total[c] += part[c];
+  }
+  if (refusal !== null) return unpriced(refusal, offenders);
+  return priced(total);
+}
+
+/**
+ * Server-side tools are billed per REQUEST, not per token, so they sit outside
+ * list_cost_by_class and its total — folding them in would break the rule that
+ * the total equals its own token breakdown. Reported alongside, additive.
+ *
+ * Web fetch is free; only web search is billed. Counting both as billable was
+ * an error in the first cut of this module.
+ */
+export function webSearchCost(requests) {
+  return round6((requests || 0) * WEB_SEARCH_USD);
+}
+
+/**
+ * The breakdown of a row that really is priced, or **null**.
+ *
+ * Keyed off the absence of a usable price, not off the reason: a row with no
+ * list_cost_usd is unpriced even if it forgot to say why, and the alternative
+ * reading — treating it as $0 — is the fabricated saving this file exists to
+ * prevent. A total or class that is not a finite number fails the same way and
+ * is refused for the same reason: it would be added to the run total, which is
+ * how one bad row makes every other row's money disappear into NaN.
+ */
+function pricedClasses(row) {
+  const classes = row.list_cost_by_class;
+  if (!Number.isFinite(row.list_cost_usd) || !classes) return null;
+  return TOKEN_CLASSES.every((c) => Number.isFinite(classes[c])) ? classes : null;
+}
+
+/**
+ * Roll priced rows up. Keeps the unpriced ones visible BY MODEL: the whole
+ * point of the counter is to name the gap in the table, and "318 unpriced" says
+ * far less than "318 unpriced: claude-opus-4-8".
+ */
+export function summarizeCost(rows) {
+  const cost = emptyCost();
+  // Null-prototype: the keys are model ids and reasons, i.e. strings from the
+  // transcript. On a plain object a model called `constructor` would read back
+  // as a function, and `fn ?? 0` then counts it as `fn1`.
+  const unpricedRows = { rows: 0, reasons: Object.create(null), models: Object.create(null) };
+  let pricedRows = 0;
+  let searches = 0;
+  for (const row of rows) {
+    searches += row.web_search_requests ?? 0;
+    const classes = pricedClasses(row);
+    if (classes === null) {
+      unpricedRows.rows++;
+      const r = row.unpriced_reason ?? 'unknown';
+      unpricedRows.reasons[r] = (unpricedRows.reasons[r] ?? 0) + 1;
+      for (const m of row.unpriced_models ?? []) unpricedRows.models[m] = (unpricedRows.models[m] ?? 0) + 1;
+      continue;
+    }
+    pricedRows++;
+    for (const c of TOKEN_CLASSES) cost[c] += classes[c];
+  }
+  // Same rule as one row: the run total is the fold of the published classes,
+  // never a parallel sum that could disagree with them.
+  const { list_cost_usd, list_cost_by_class } = priced(cost);
+  return {
+    list_cost_usd,
+    list_cost_by_class,
+    web_search_requests: searches,
+    web_search_cost_usd: webSearchCost(searches),
+    priced_rows: pricedRows,
+    total_rows: pricedRows + unpricedRows.rows,
+    unpriced: unpricedRows,
+  };
+}
+
+function usd(n) {
+  return `$${n.toFixed(4)}`;
+}
+
+/**
+ * An amount for human eyes, including the case where there is none. An
+ * uncomputable total prints as the word, never as `$0.0000` — the whole file
+ * exists to stop an unknown cost reading as a cheap one.
+ */
+export function formatUsd(n) {
+  return Number.isFinite(n) ? usd(n) : 'unknown (NOT $0)';
+}
+
+function count(n) {
+  return n.toLocaleString('en-US');
+}
+
+/**
+ * Cost lines for a run summary. Always emits the per-class split next to the
+ * total — the one formatting rule EPIC-009 states outright (criterion 2), kept
+ * here rather than at the call site so it is testable on its own. And always
+ * says what the figure IS: a subscription user who reads it as their bill has
+ * been misled by us, not by the number.
+ */
+export function formatCostLines(summary, tokens) {
+  const L = [];
+  if (tokens) {
+    // Labelled "all rows" because the cost line below covers only the priced
+    // ones: two figures side by side that quietly span different populations
+    // invite exactly the wrong division.
+    L.push(
+      `  tokens (all rows): input ${count(tokens.input_tokens)} | cache-read ${count(tokens.cache_read)}` +
+        ` | cache-write-5m ${count(tokens.cache_write_5m)} | cache-write-1h ${count(tokens.cache_write_1h)}` +
+        ` | output ${count(tokens.output_tokens)}` +
+        // Otherwise the classes would not add up to the tokens actually seen,
+        // and a breakdown that silently omits a class is not a breakdown.
+        (tokens.cache_write_unsplit > 0 ? ` | cache-write-UNSPLIT ${count(tokens.cache_write_unsplit)}` : ''),
+    );
+  }
+  const c = summary.list_cost_by_class;
+  L.push(
+    `  API list price: ${usd(summary.list_cost_usd)} over ${summary.priced_rows} of ${summary.total_rows} row(s)` +
+      ` = input ${usd(c.input)} + cache-read ${usd(c.cache_read)} + cache-write-5m ${usd(c.cache_write_5m)}` +
+      ` + cache-write-1h ${usd(c.cache_write_1h)} + output ${usd(c.output)}`,
+  );
+  L.push(
+    '    ^ what these tokens WOULD cost via the API. NOT a bill: a Pro/Max plan' +
+      ' charges its flat fee, not per token. Use it to compare arms, not to reconcile a statement.',
+  );
+  if (summary.web_search_requests > 0) {
+    L.push(
+      `  web searches: ${summary.web_search_requests} = ${usd(summary.web_search_cost_usd)}` +
+        ' — billed per request, additive to the figure above (web fetch is free)',
+    );
+  }
+  if (summary.unpriced.rows > 0) {
+    const reasons = Object.entries(summary.unpriced.reasons)
+      .sort((a, b) => b[1] - a[1])
+      .map(([r, n]) => `${r} ${n}`)
+      .join(', ');
+    const models = Object.entries(summary.unpriced.models)
+      .sort((a, b) => b[1] - a[1])
+      .map(([m, n]) => `${m} ${n}`)
+      .join(', ');
+    L.push(`  UNPRICED rows: ${summary.unpriced.rows} (${reasons}) — their cost is unknown, NOT zero`);
+    if (models) L.push(`    models seen on unpriced rows: ${models}`);
+    L.push(`    price table: ${PRICES.source} (retrieved ${PRICES.retrieved})`);
+  }
+  return L;
+}