@trazum/core 2.4.2 → 2.4.3

package/src/pricing.ts

@@ -48,10 +48,30 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
    * and priority. The standard one is the catalogue's, identified by the other
    * three being its multiples (0.5x, 0.5x, 2x) rather than by trusting the
    * order they appear in.
+   *
+   * Re-read 2026-10-11 with the prompt-caching guide, the GPT-5 model page and
+   * the deprecations page. GPT-5, mini and nano matched to the cent. Their
+   * dated snapshots (`gpt-5-2025-08-07` and the mini and nano ones), which is
+   * the id a usage log usually carries, shut down on 2026-12-11 and are now
+   * declared as aliases. The current generation (gpt-6-astra, gpt-6.1-sol,
+   * gpt-6-sol, gpt-6-luna and gpt-5.6 sol, terra and luna) is on the same
+   * page and not added: every one of them doubles its rates for prompts over
+   * 272K tokens, a per-request condition no log Trazum prices passes yet.
+   */
+  openai: '2026-10-11',
+  /*
+   * ai.google.dev/gemini-api/docs/pricing, docs/caching and the model pages,
+   * read 2026-10-10. Every price matched; what changed is how caching starts
+   * and what it costs on the old models. Implicit caching is on by default
+   * for every Gemini 2.5 and newer model, so `caching` is 'automatic' across
+   * the board; the minimums moved to 4,096 on 3.6 and 3.8 Flash and 2,048 on
+   * 2.5 Flash; and the 2.5 models read the cache at 10% of input today, not
+   * the 25% this table carried. Gemini 3.8 Flash was added. Gemini 3.1 Pro
+   * Preview and 2.5 Pro's prompts over 200k are priced by prompt length per
+   * request, which nothing that prices a log passes yet, so the first is left
+   * out and the second's tier is named in its note rather than guessed.
    */
-  openai: '2026-08-31',
-  /* ai.google.dev/gemini-api/docs/pricing, read 2026-08-28. */
-  google: '2026-08-28',
+  google: '2026-10-10',
   /*
    * platform.kimi.ai/docs/pricing/chat (platform.moonshot.ai 301s there),
    * read 2026-09-12. The page prices kimi-k3, kimi-k2.6, kimi-k2.7-code and
@@ -64,8 +84,15 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
    * not read is a number it would be inventing.
    */
   moonshot: '2026-09-12',
-  /* api-docs.deepseek.com/quick_start/pricing, read 2026-08-28. */
-  deepseek: '2026-08-28',
+  /*
+   * api-docs.deepseek.com/quick_start/pricing read 2026-10-10, and the
+   * 2026-09-10 announcement (api-docs.deepseek.com/news/news260910) read
+   * 2026-10-11 for the instant: "New pricing takes effect at 04:00 UTC on
+   * Sept 10, 2026." V4 Flash was retired that day and its id now bills at
+   * the new deepseek-flash price, so the old price lives in its `history`.
+   * V4 Pro matched the page unchanged.
+   */
+  deepseek: '2026-10-10',
   /*
    * docs.x.ai/docs/models, read 2026-09-12. The page prices grok-4.6, 4.5,
    * 4.3 and the 4.20 family, each at two rates split at 200k prompt tokens;
@@ -86,7 +113,18 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
    * servable is not the same as checking, and moving the date then would have
    * said it was.
    */
-  mistral: '2026-08-28',
+  /*
+   * Re-read 2026-10-11 from mistral.ai/cloud/inference/ and the model cards
+   * at mistral.ai/news/mistral-3/, /mistral-small-4/ and
+   * /vibe-remote-agents-mistral-medium-3-5/, which carry the prices in their
+   * markup (`data-prices`) and bind the `-latest` ids. Every price matched.
+   * What changed is caching: the inference page offers "Cached input tokens
+   * -90% on input token", and every one of the three cards marks its input
+   * price as carrying the cache discount. This table said Mistral had no
+   * prompt caching at all. docs.mistral.ai, where a minimum or a mechanism
+   * would be, is not reachable from here, so neither is claimed.
+   */
+  mistral: '2026-10-11',
 });
 
 /**
@@ -132,12 +170,17 @@ const multipliersMemo = new WeakMap<
   { cacheWrite5m: number; cacheWrite1h: number; cacheRead: number; batch: number | null }
 >();
 
-export function multipliersFor(model: ModelPricing): {
+export function multipliersFor(model: ModelPricing, on?: Date): {
   cacheWrite5m: number;
   cacheWrite1h: number;
   cacheRead: number;
   batch: number | null;
 } {
+  // A dated question about a repriced model asks the period in force then.
+  if (on !== undefined && model.history !== undefined) {
+    const period = pricedAt(model, on);
+    if (period !== model) return multipliersFor(period);
+  }
   const cached = multipliersMemo.get(model);
   if (cached !== undefined) return cached;
   const m = model.multipliers ?? {};
@@ -151,6 +194,23 @@ export function multipliersFor(model: ModelPricing): {
   return result;
 }
 
+/**
+ * Mistral discounts cached input by 90% and publishes nothing else about it
+ * that can be read from here: not how caching starts, not a minimum, not a
+ * write price. Its usage reports no write tokens, so the write ratio of 1 is
+ * never multiplied by anything; it is there so the default (Anthropic's 1.25)
+ * cannot be.
+ */
+/** What the GPT-5 family's three rows share, from OpenAI's guide and deprecations page, read 2026-10-11. */
+const OPENAI_GPT5_NOTE =
+  'Caching is automatic, with no cache_control to set. OpenAI says the minimum for models before GPT-5.6 varies by'
+  + ' request settings, so 1,024 here is the nearest published floor. The 2025-08-07 snapshot shuts down on'
+  + ' 2026-12-11; OpenAI names the gpt-5.6 models as replacements.';
+
+const MISTRAL_CACHE_NOTE =
+  'Cached input costs 10% of the input price (mistral.ai/cloud/inference, read 2026-10-11). How caching starts and'
+  + ' its minimum are not published anywhere Trazum can read, so no caching advice is given for it.';
+
 export const MODELS: ModelPricing[] = [
   {
     /*
@@ -380,13 +440,17 @@ export const MODELS: ModelPricing[] = [
   // ------------------------------------------------------------------------
   // OpenAI
   //
-  // Caching is AUTOMATIC above 1,024 tokens — there is no cache_control to set,
-  // and a cached read costs about half the input price rather than a tenth. The
-  // reordering advice is identical (a prefix is a prefix), the marker advice is
-  // not, which is why `caching` and `multipliers` exist at all.
+  // Caching is AUTOMATIC, with no cache_control to set, and a cached read costs
+  // a tenth of input on these three ($0.125 against $1.25). The reordering
+  // advice is identical (a prefix is a prefix), the marker advice is not, which
+  // is why `caching` and `multipliers` exist at all. The 1,024 minimum is the
+  // one OpenAI publishes for GPT-5.6 and later; for these older models its
+  // guide says the minimum "varies by request settings", so it is the nearest
+  // published floor, not a promise, and each row's note says so.
   // ------------------------------------------------------------------------
   {
     id: 'gpt-5',
+    aliases: ['gpt-5-2025-08-07'],
     provider: 'openai',
     displayName: 'GPT-5',
     inputPerMTok: 1.25,
@@ -397,10 +461,11 @@ export const MODELS: ModelPricing[] = [
     multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'frontier',
     tier: 'frontier',
-    notes: 'Caching is automatic above 1,024 tokens; there is no cache_control to set.',
+    notes: OPENAI_GPT5_NOTE,
   },
   {
     id: 'gpt-5-mini',
+    aliases: ['gpt-5-mini-2025-08-07'],
     provider: 'openai',
     displayName: 'GPT-5 mini',
     inputPerMTok: 0.25,
@@ -411,9 +476,11 @@ export const MODELS: ModelPricing[] = [
     multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'mid',
     tier: 'sonnet',
+    notes: OPENAI_GPT5_NOTE,
   },
   {
     id: 'gpt-5-nano',
+    aliases: ['gpt-5-nano-2025-08-07'],
     provider: 'openai',
     displayName: 'GPT-5 nano',
     inputPerMTok: 0.05,
@@ -424,6 +491,7 @@ export const MODELS: ModelPricing[] = [
     multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'small',
     tier: 'haiku',
+    notes: OPENAI_GPT5_NOTE,
   },
 
   // ------------------------------------------------------------------------
@@ -437,8 +505,9 @@ export const MODELS: ModelPricing[] = [
     outputPerMTok: 10,
     contextWindow: 1_048_576,
     cacheMinTokens: 2048,
-    caching: 'explicit',
-    multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    caching: 'automatic',
+    /* $0.125 cached against $1.25 input for prompts up to 200k, read 2026-10-10. */
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
     retired: {
       on: '2026-08-28',
@@ -447,7 +516,10 @@ export const MODELS: ModelPricing[] = [
     },
     capability: 'large',
     tier: 'opus',
-    notes: 'Context caching is billed for storage per hour as well as per read.',
+    notes:
+      'Prompts over 200k tokens are billed $2.50 in and $15.00 out; this row prices every prompt at the up-to-200k rate,'
+      + ' because no log Trazum prices says how long each prompt was. Implicit caching is automatic; explicit caching is'
+      + ' also billed for storage per hour.',
   },
   {
     id: 'gemini-2.5-flash',
@@ -456,9 +528,10 @@ export const MODELS: ModelPricing[] = [
     inputPerMTok: 0.3,
     outputPerMTok: 2.5,
     contextWindow: 1_048_576,
-    cacheMinTokens: 1024,
-    caching: 'explicit',
-    multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    cacheMinTokens: 2048,
+    caching: 'automatic',
+    /* $0.03 cached against $0.30 input (text), read 2026-10-10. */
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
     retired: {
       on: '2026-08-28',
@@ -471,9 +544,10 @@ export const MODELS: ModelPricing[] = [
 
   {
     /*
-     * Google's own error message names this as the replacement for the two
-     * retired 2.5 models, and ai.google.dev/gemini-api/docs/pricing carries the
-     * rates, read 2026-08-28.
+     * Google's own error message names this as the replacement for the retired
+     * 2.5 Flash (the 2.5 Pro refusal names 3.1 Pro Preview), and
+     * ai.google.dev/gemini-api/docs/pricing carries the rates, read 2026-08-28
+     * and again on 2026-10-10.
      *
      * The introductory price has a published end date and a published successor,
      * which is exactly what `promo` is for and is the shape the catalogue nearly
@@ -487,8 +561,8 @@ export const MODELS: ModelPricing[] = [
     outputPerMTok: 7.5,
     promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
     contextWindow: 1_048_576,
-    cacheMinTokens: 1024,
-    caching: 'explicit',
+    cacheMinTokens: 4096,
+    caching: 'automatic',
     /*
      * $0.075 against $0.75 inside the introductory window, and $0.15 against
      * $1.50 after it: Google scales the cache price with the headline one, so
@@ -499,7 +573,32 @@ export const MODELS: ModelPricing[] = [
     capability: 'mid',
     tier: 'sonnet',
     notes:
-      'Context caching is billed for storage per hour as well as per read:'
+      'Implicit caching is automatic above 4,096 tokens. Explicit caching is also billed for storage:'
+      + ' $0.50 per 1M tokens per hour through 2026-12-31, $1.00 after.',
+  },
+  {
+    /*
+     * Gemini 3.8 Flash, from ai.google.dev/gemini-api/docs/pricing, its model
+     * page and docs/caching, read 2026-10-10. The same rates and the same
+     * introductory window as 3.6 Flash, published as one table each: $0.75
+     * and $3.75 through 2026-12-31, $1.50 and $7.50 from 2027-01-01, and the
+     * cache price scales with them ($0.075, then $0.15).
+     */
+    id: 'gemini-3.8-flash',
+    provider: 'google',
+    displayName: 'Gemini 3.8 Flash',
+    inputPerMTok: 1.5,
+    outputPerMTok: 7.5,
+    promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
+    contextWindow: 1_048_576,
+    cacheMinTokens: 4096,
+    caching: 'automatic',
+    /* $0.075 / $0.75 = 0.1 (and $0.15 / $1.50); batch $0.375 / $0.75 = 0.5 (and $1.875 / $3.75). */
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'mid',
+    tier: 'sonnet',
+    notes:
+      'Implicit caching is automatic above 4,096 tokens. Explicit caching is also billed for storage:'
       + ' $0.50 per 1M tokens per hour through 2026-12-31, $1.00 after.',
   },
 
@@ -547,34 +646,97 @@ export const MODELS: ModelPricing[] = [
   },
   {
     /*
-     * DeepSeek V4 Flash, from api-docs.deepseek.com/quick_start/pricing, read
-     * 2026-08-28. It replaced `deepseek-v3`, which the API now refuses.
+     * DeepSeek V4 Flash, retired on 2026-09-10. The pricing page (read
+     * 2026-10-10) says the id "is still accepted ... served by the
+     * DeepSeek-V4.1-Flash model and billed at the Flash price", so from
+     * 04:00 UTC that day it carries deepseek-flash's rates. Before that
+     * instant it billed at its own, read off the same page on 2026-08-28:
+     * $0.22/$0.66 off-peak, double at peak, $0.007 a cache hit.
      *
      * The base rate is off-peak because off-peak is the common case: peak is
      * 01:00-04:00 and 06:00-10:00 UTC on weekdays, which is 35 hours of 168.
-     * The peak tier is exactly double, published as such.
+     * The peak tier is exactly double, published as such. Clock pricing began
+     * at 16:00 UTC on 2026-08-16; the flat price before it is on no page this
+     * table can read, so calls before then are priced as the first period.
+     *
+     * Not recommendable: a legacy id DeepSeek routes "temporarily". Without
+     * this, a tie on price would offer it ahead of deepseek-flash.
      */
     id: 'deepseek-v4-flash',
     provider: 'deepseek',
     displayName: 'DeepSeek V4 Flash',
-    inputPerMTok: 0.22,
-    outputPerMTok: 0.66,
+    recommendable: false,
+    inputPerMTok: 0.15,
+    outputPerMTok: 0.6,
+    tiers: [
+      {
+        id: 'peak',
+        when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+        inputPerMTok: 0.3,
+        outputPerMTok: 1.2,
+      },
+    ],
+    history: [
+      {
+        until: '2026-09-10T04:00:00Z',
+        inputPerMTok: 0.22,
+        outputPerMTok: 0.66,
+        tiers: [
+          {
+            id: 'peak',
+            when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+            inputPerMTok: 0.44,
+            outputPerMTok: 1.32,
+          },
+        ],
+        /* $0.007 cache hit against $0.22 input off-peak. */
+        multipliers: { cacheRead: 0.0318, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+      },
+    ],
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    /* $0.003 cache hit against $0.15 input off-peak, $0.006 against $0.30 at peak. */
+    multipliers: { cacheRead: 0.02, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'mid',
+    tier: 'sonnet',
+    notes:
+      'Retired 2026-09-10: the id is still accepted, served by V4.1 Flash and billed at the deepseek-flash price.'
+      + ' Maximum output 384K tokens. Peak excludes Chinese public holidays, which this table cannot express.',
+  },
+  {
+    /*
+     * DeepSeek V4.1 Flash, from api-docs.deepseek.com/quick_start/pricing,
+     * read 2026-10-10. Released 2026-09-10; its price took effect at 04:00
+     * UTC that day. Off-peak is the base and peak is exactly double, as
+     * published; the cache hit is 2% of input at both ($0.003 and $0.006).
+     *
+     * The cache minimum is carried from deepseek-v4-flash: DeepSeek's pages
+     * publish none for this generation, and 1,024 is the figure the earlier
+     * row was reviewed with.
+     */
+    id: 'deepseek-flash',
+    provider: 'deepseek',
+    displayName: 'DeepSeek V4.1 Flash',
+    inputPerMTok: 0.15,
+    outputPerMTok: 0.6,
     tiers: [
       {
         id: 'peak',
         when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
-        inputPerMTok: 0.44,
-        outputPerMTok: 1.32,
+        inputPerMTok: 0.3,
+        outputPerMTok: 1.2,
       },
     ],
     contextWindow: 1_000_000,
     cacheMinTokens: 1024,
     caching: 'automatic',
-    /* $0.007 cache hit against $0.22 input off-peak. */
-    multipliers: { cacheRead: 0.0318, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    multipliers: { cacheRead: 0.02, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
     capability: 'mid',
     tier: 'sonnet',
-    notes: 'Maximum output 384K tokens.',
+    notes:
+      'Maximum output 384K tokens. Peak excludes Chinese public holidays, which this table cannot express:'
+      + ' on a weekday holiday it charges peak where DeepSeek charges off-peak.',
   },
   {
     /* Same page, same clock. Pro is three times Flash at both ends. */
@@ -667,12 +829,12 @@ export const MODELS: ModelPricing[] = [
     inputPerMTok: 0.5,
     outputPerMTok: 1.5,
     contextWindow: 262_144,
-    cacheMinTokens: 0,
-    caching: 'none',
-    multipliers: { batch: 0.5 },
+    cacheMinTokens: null,
+    caching: 'unknown',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'large',
     tier: 'opus',
-    notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
+    notes: MISTRAL_CACHE_NOTE,
   },
   {
     /*
@@ -695,11 +857,12 @@ export const MODELS: ModelPricing[] = [
     inputPerMTok: 1.5,
     outputPerMTok: 7.5,
     contextWindow: 262_144,
-    cacheMinTokens: 0,
-    caching: 'none',
-    multipliers: { batch: 0.5 },
+    cacheMinTokens: null,
+    caching: 'unknown',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'mid',
     tier: 'sonnet',
+    notes: MISTRAL_CACHE_NOTE,
   },
   {
     /* Same page, same day. `mistral-small-2603` is what the API reports. */
@@ -710,11 +873,12 @@ export const MODELS: ModelPricing[] = [
     inputPerMTok: 0.15,
     outputPerMTok: 0.6,
     contextWindow: 262_144,
-    cacheMinTokens: 0,
-    caching: 'none',
-    multipliers: { batch: 0.5 },
+    cacheMinTokens: null,
+    caching: 'unknown',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
     capability: 'small',
     tier: 'haiku',
+    notes: MISTRAL_CACHE_NOTE,
   },
 ];
 
@@ -879,6 +1043,40 @@ const pricingMemo = new WeakMap<
   { untilMs: number | null; promo: Rates | null; base: Rates }
 >();
 
+/**
+ * The row as it stood at `on`: itself when the current price applies, or a
+ * frozen copy carrying the period's rates, tiers and ratios. Built once per
+ * period, so a log of a million calls does not build a million rows.
+ */
+const periodMemo = new WeakMap<ModelPricing, { untilMs: number; row: ModelPricing }[]>();
+
+function pricedAt(model: ModelPricing, on: Date): ModelPricing {
+  const history = model.history;
+  if (history === undefined || history.length === 0) return model;
+  let periods = periodMemo.get(model);
+  if (periods === undefined) {
+    periods = history.map((period) => {
+      const { history: _history, promo: _promo, tiers: _tiers, multipliers: _multipliers, ...rest } = model;
+      const row: ModelPricing = Object.freeze({
+        ...rest,
+        inputPerMTok: period.inputPerMTok,
+        outputPerMTok: period.outputPerMTok,
+        ...(period.tiers !== undefined ? { tiers: period.tiers } : {}),
+        ...(period.multipliers !== undefined
+          ? { multipliers: period.multipliers }
+          : model.multipliers !== undefined
+            ? { multipliers: model.multipliers }
+            : {}),
+      });
+      return { untilMs: new Date(period.until).getTime(), row };
+    });
+    periodMemo.set(model, periods);
+  }
+  const at = on.getTime();
+  for (const period of periods) if (at < period.untilMs) return period.row;
+  return model;
+}
+
 /** The two unconditional answers for one model, parsed once. */
 function cache(model: ModelPricing): {
   untilMs: number | null;
@@ -948,6 +1146,11 @@ export function effectivePricing(
   on: Date = new Date(),
   context: { inputTokens?: number } = {},
 ): Rates {
+  /* A call before a published price change is priced as it was billed then. */
+  if (model.history !== undefined) {
+    const period = pricedAt(model, on);
+    if (period !== model) return effectivePricing(period, on, context);
+  }
   const memo = pricingMemo.get(model) ?? cache(model);
 
   /**

package/src/types.ts

@@ -203,6 +203,18 @@ export interface PricingTier {
   outputPerMTok: number;
 }
 
+/** One published price this model carried until an instant. See `ModelPricing.history`. */
+export interface PricePeriod {
+  /** ISO 8601 instant, exclusive: a call at exactly this instant is priced by what came after. */
+  until: string;
+  inputPerMTok: number;
+  outputPerMTok: number;
+  /** The conditional rates in force during the period; none means none applied. */
+  tiers?: PricingTier[];
+  /** The cache and batch ratios during the period; absent means the row's own. */
+  multipliers?: CostMultipliers;
+}
+
 export interface ModelPricing {
   id: string;
   displayName: string;
@@ -298,6 +310,22 @@ export interface ModelPricing {
    * and keeps this field optional in effect as well as in the type.
    */
   tiers?: PricingTier[];
+  /**
+   * What this id cost before its current price, earliest period first.
+   *
+   * A usage log is history, and a provider that cuts a price at 04:00 UTC on
+   * a Thursday has billed the same id two ways in one month. One price for
+   * all time priced the older calls at the newer rate, or the newer at the
+   * older, and nothing on screen said which. A call at `on` is priced by the
+   * first period whose `until` is after it; a call at or after the last
+   * `until` takes the fields above. Each period carries its own tiers and
+   * cache ratio, because a provider that reprices usually reprices both.
+   *
+   * Only periods a provider published, with the instant it published. A
+   * period before the first one this table can source is not guessed at: the
+   * earliest period stands for it, and the row's note says so.
+   */
+  history?: PricePeriod[];
   /**
    * Other ids that bill at exactly this rate.
    *

package/src/usage.ts

@@ -944,8 +944,20 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
   if (!model) return false;
 
   countInto(into, record);
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  /**
+   * **Each call at the price of its own moment.** A bill is history: a call
+   * made inside a promotion was billed at the promotional rate, a DeepSeek
+   * call at 03:00 UTC on a weekday was billed at peak, and a call before a
+   * published price change was billed at the old price. Priced at the report's
+   * date instead, every one of those came out at whatever applied the day the
+   * report ran: a clock-priced log read during peak hours was all peak, and an
+   * August log read in October lost its August promotion. `on` is the date for
+   * a record that carries no clock, which is the only thing it can mean here.
+   */
+  const at = record.ts !== null ? new Date(record.ts) : on;
+  const { inputPerMTok, outputPerMTok } = effectivePricing(model, at);
+  // Dated, like the rate above: a repriced cache read is part of the reprice.
+  const rates = multipliersFor(model, at);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
 
   into.inputUsd += per(record.inputTokens, inputPerMTok);
@@ -991,7 +1003,11 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
 
 export interface UsageProfileOptions {
   catalogue: PricingCatalogue;
-  /** Date the prices are read at, so a promotional rate resolves the same way. */
+  /**
+   * The date a record with no timestamp is priced at, and the date the
+   * forward-looking findings (levers, what-ifs) are priced at. A record that
+   * carries its own `ts` is billed at its own moment: see `add`.
+   */
   on?: Date;
   /**
    * Profile only the records carrying this label — the drill-down, once the