@trazum/core 1.9.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.9.0",
+  "version": "1.25.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/advisories.ts

@@ -125,7 +125,25 @@ export function buildAdvisories(
   const monthlyOutputUsd =
     (usage.avgOutputTokens / 1_000_000) * outputPerMTok * usage.callsPerMonth * batchFactor;
 
-  // --- Context window ---
+  /**
+   * --- Context window ---
+   *
+   * The third place an estimate was compared against a hard threshold and the
+   * answer stated as fact, after `cache-prefix-reorder` and `prompt-caching`. This
+   * one has no dollar figure and is the most absolute of the three: **"The call
+   * will fail."**
+   *
+   * With a ±10% band it fails in both directions. An estimated 1,050,000 tokens
+   * against a 1,000,000 window can truly be 945,000 — the call succeeds and the
+   * reader has been sent to split a prompt that fitted. And an estimated 990,000
+   * can truly be 1,089,000, which does not fit, and nothing said anything at all.
+   *
+   * The silent direction is the worse one. A prompt over the window fails
+   * outright rather than degrading, so there is no partial result to notice.
+   */
+  const estimated = count === estimateTokens;
+  const band = ESTIMATE_ERROR_BAND_PCT / 100;
+
   if (tokensAfter > model.contextWindow) {
     advisories.push({
       id: 'context-overflow',
@@ -134,6 +152,20 @@ export function buildAdvisories(
         tokens: tokensAfter,
         modelName: model.displayName,
         contextWindow: model.contextWindow,
+        // Only an estimate can be uncertain. A caller who counted exactly is told
+        // the call fails, because it does.
+        uncertain: estimated && tokensAfter * (1 - band) <= model.contextWindow,
+      }),
+      estimatedMonthlyUsd: null,
+    });
+  } else if (estimated && tokensAfter * (1 + band) > model.contextWindow) {
+    advisories.push({
+      id: 'context-near-limit',
+      severity: 'warning',
+      ...t.advisories.contextNearLimit({
+        tokens: tokensAfter,
+        modelName: model.displayName,
+        contextWindow: model.contextWindow,
       }),
       estimatedMonthlyUsd: null,
     });
@@ -185,6 +217,22 @@ export function buildAdvisories(
             readPct: Math.round(rates.cacheRead * 100),
             writePct: Math.round(rates.cacheWrite5m * 100),
             explicit: (model.caching ?? 'explicit') === 'explicit',
+            /**
+             * The mirror of `couldReachMinimum` on `below-cache-minimum`, and the
+             * asymmetry between them was a real gap: that one hedged an estimate
+             * landing just *under* the threshold, while this one promised money on
+             * an estimate landing just *over* it. With a ±10% band an estimated
+             * 528-token prefix can truly be 475, and then nothing caches at all.
+             *
+             * The cautionary direction is the one that needed it, because this is
+             * the side with a dollar figure attached. Only when the number is an
+             * estimate: a caller who supplied their own counter has an
+             * authoritative prefix and hedging it would push them toward a check
+             * they have already done.
+             */
+            nearMinimum:
+              count === estimateTokens &&
+              cache.stablePrefixTokens * (1 - ESTIMATE_ERROR_BAND_PCT / 100) < minTokens,
           }),
           estimatedMonthlyUsd: saving,
         });
@@ -223,12 +271,49 @@ export function buildAdvisories(
       });
     }
 
-    // Stable content placed AFTER the first placeholder: never cached today,
-    // but moving it in front would make it cacheable.
+    /**
+     * Stable content placed AFTER the first placeholder: never cached today, and
+     * cacheable if it moves in front.
+     *
+     * **The prefix it would produce has to clear the minimum, and it did not used
+     * to be checked.** That was a money figure in the flattering direction, which
+     * is the one fault this file exists to avoid. On a 306-token support prompt
+     * against Claude Opus 5's 512-token minimum, the best prefix a rearrangement
+     * can build is 302 — so nothing caches, and the advisory offered $48.67 a
+     * month that cannot be collected.
+     *
+     * Worse, it said so in the same report as `below-cache-minimum`, which was
+     * telling the reader caching would not work here at all. Two advisories
+     * contradicting each other, and the one with a dollar sign winning the
+     * argument.
+     *
+     * `reorderForCache` already refused these prompts for exactly this reason, so
+     * the tool's advice and its action disagreed: follow the advice, run
+     * `--reorder`, and watch nothing happen.
+     */
+    /**
+     * The best prefix any rearrangement could build, compared strictly.
+     *
+     * **No band hedge here, and that was tried first.** Widening the comparison by
+     * ±10% — on the same reasoning that makes `below-cache-minimum` hedge near the
+     * line — opened a window between 466 and 512 tokens where this advisory
+     * offered a saving and `reorderForCache` refused to perform it. That is the
+     * fault being fixed, reintroduced one layer up, and a test caught it.
+     *
+     * The near-the-line case is already handled and in the right place:
+     * `below-cache-minimum` says the estimate is close to the threshold and names
+     * `--exact-tokens`. Settle the number and both this advisory and the command
+     * work from the same certainty. Two components disagreeing is worse than one
+     * of them being briefly quiet.
+     */
+    const reorderedPrefix = cache.stablePrefixTokens + cache.staticTokensAfter;
+    const reachableAfterReorder = reorderedPrefix >= minTokens;
+
     if (
       cache.firstPlaceholder &&
       cache.staticTokensAfter >= 200 &&
-      cache.staticTokensAfter >= tokensAfter * 0.3
+      cache.staticTokensAfter >= tokensAfter * 0.3 &&
+      reachableAfterReorder
     ) {
       const movableShare = tokensAfter > 0 ? cache.staticTokensAfter / tokensAfter : 0;
       const saving = monthlyInputUsd * movableShare * Math.max(0, 1 - factor);
@@ -239,6 +324,13 @@ export function buildAdvisories(
           staticTokensAfter: cache.staticTokensAfter,
           sharePct: Math.round(movableShare * 100),
           placeholder: cache.firstPlaceholder,
+          /**
+           * Trazum can do this, and until now it told you to do it by hand.
+           * `reorderForCache` moves whole blocks, refuses any block carrying a
+           * backward reference, and refuses everything after one — so the command
+           * is the safe way to attempt what the prose was describing.
+           */
+          command: 'trazum optimize <file> --reorder',
         }),
         estimatedMonthlyUsd: saving > 0 ? saving : null,
       });

package/src/against.ts

@@ -0,0 +1,48 @@
+/**
+ * The drivers of a change between two bills.
+ *
+ * One implementation, exported from core, because the sign convention here —
+ * **positive means the bill grew**, the diff convention — has already flipped
+ * once in this repository's history when restated by hand. The CLI, the MCP
+ * and the web all render these rows; three inline computations of the same
+ * union-and-subtract is three chances for one of them to disagree about what
+ * a vanished workload contributed.
+ *
+ * Derived over the **union** of keys, so an appeared or vanished workload is
+ * named rather than folded silently into the total: `was: null` is a key the
+ * previous log did not have, `now: null` one this log no longer has. Both are
+ * different statements from `$0.00`, and the renderings say which.
+ */
+
+export interface AgainstDriver {
+  key: string;
+  /** What this key cost in the previous log, or null when it was not there. */
+  was: number | null;
+  /** What it costs now, or null when it is gone. */
+  now: number | null;
+  /** `(now ?? 0) - (was ?? 0)` — positive means the bill grew. */
+  delta: number;
+}
+
+/**
+ * Noise floor, not a judgement threshold: the same accumulated-double drift
+ * `cacheEconomics` refuses to report as a finding.
+ */
+const DRIVER_NOISE_USD = 1e-9;
+
+export function driversBetween(
+  before: ReadonlyArray<{ key: string; usd: number }>,
+  after: ReadonlyArray<{ key: string; usd: number }>,
+): AgainstDriver[] {
+  const wasBy = new Map(before.map((row) => [row.key, row.usd]));
+  const nowBy = new Map(after.map((row) => [row.key, row.usd]));
+  return [...new Set([...wasBy.keys(), ...nowBy.keys()])]
+    .map((key) => ({
+      key,
+      was: wasBy.has(key) ? wasBy.get(key)! : null,
+      now: nowBy.has(key) ? nowBy.get(key)! : null,
+    }))
+    .map((driver) => ({ ...driver, delta: (driver.now ?? 0) - (driver.was ?? 0) }))
+    .filter((driver) => Math.abs(driver.delta) > DRIVER_NOISE_USD)
+    .sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+}

package/src/config-schema.ts

@@ -48,6 +48,21 @@ export interface BaselineConfig {
   maxGrowthPct?: number;
 }
 
+/**
+ * Money budgets, in dollars, for the log-reading side of the tool.
+ *
+ * A budget for a workload that made no calls is **not** a pass and not a
+ * failure: it is a measurement that did not happen, and the report says so
+ * rather than reporting green over an absence. That is the same three-state
+ * rule the counts, the timestamps and the stop reasons all follow.
+ */
+export interface SpendConfig {
+  /** Whole-log budget. `--max-usd` overrides it. */
+  maxUsd?: number;
+  /** Per-label budgets, each gated against that label's own spend. */
+  byLabel?: Record<string, number>;
+}
+
 export interface TrazumConfig {
   level?: RuleLevel;
   locale?: Locale;
@@ -59,6 +74,32 @@ export interface TrazumConfig {
    * leaving it to be inferred.
    */
   budgets?: Record<string, number>;
+  /**
+   * Which prompt file each usage-log label sends, so `profile` can close the
+   * loop it opens.
+   *
+   * `profile` can say "caching loses money on `support-rag`" and nothing more —
+   * the log carries counts, not content. With this map it reads the named file
+   * and says *why*: where the first placeholder sits, how many stable tokens
+   * never reach the cacheable prefix, and whether the model's minimum is met at
+   * all. The file is whatever is in the repository today, which may not be what
+   * produced the log, and the report says so.
+   */
+  labels?: Record<string, string>;
+  /**
+   * Money budgets for `trazum profile`, in dollars.
+   *
+   * `budgets` gates the tokens a prompt file may hold; this gates the dollars
+   * a usage log records — the same difference `check` and `profile` have
+   * everywhere else. Written in the repository rather than passed as a flag
+   * because a per-workload budget is a policy several people agree on, and a
+   * policy that lives in one CI invocation is a policy nobody can read.
+   *
+   * `maxUsd` is the default for `--max-usd`; `byLabel` gates each named
+   * workload against its own limit in the same run. A flag still wins over
+   * the config, as everywhere in this tool.
+   */
+  spend?: SpendConfig;
   /** Default for `trazum diff --max-growth`, in tokens. */
   maxGrowth?: number;
   /**
@@ -94,6 +135,8 @@ export const CONFIG_KEYS = [
   'disable',
   'usage',
   'budgets',
+  'labels',
+  'spend',
   'maxGrowth',
   'baseline',
   'extensions',
@@ -102,6 +145,8 @@ export const CONFIG_KEYS = [
 
 export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct'] as const;
 
+export const CONFIG_SPEND_KEYS = ['maxUsd', 'byLabel'] as const;
+
 export const CONFIG_USAGE_KEYS = [
   'model',
   'callsPerMonth',
@@ -217,6 +262,31 @@ function parseUsage(raw: unknown, source: string): Partial<UsageProfile> {
  */
 const IS_ABSOLUTE = /^(?:[/\\]|[A-Za-z]:[/\\])/;
 
+function parseLabels(raw: unknown, source: string): Record<string, string> {
+  if (!isPlainObject(raw)) throw new ConfigError('"labels" must be an object', source);
+
+  const labels: Record<string, string> = {};
+  for (const [label, value] of Object.entries(raw)) {
+    if (label.length === 0) {
+      throw new ConfigError('"labels" has an empty label', source);
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new ConfigError(`labels["${label}"] must be a file path`, source);
+    }
+    // Same boundary as budgets, for the same reason: an absolute path or one
+    // that climbs out with ".." points outside the project, and both are
+    // mistakes worth naming rather than files worth reading.
+    if (IS_ABSOLUTE.test(value) || value.includes('..')) {
+      throw new ConfigError(
+        `labels["${label}"] must be a relative path inside the project`,
+        source,
+      );
+    }
+    labels[label] = value;
+  }
+  return labels;
+}
+
 function parseBudgets(raw: unknown, source: string): Record<string, number> {
   if (!isPlainObject(raw)) throw new ConfigError('"budgets" must be an object', source);
 
@@ -243,6 +313,40 @@ function parseBudgets(raw: unknown, source: string): Record<string, number> {
   return budgets;
 }
 
+/**
+ * Validates the `spend` block.
+ *
+ * Dollars, not tokens, so non-integers are legitimate — $0.50 is a budget
+ * somebody means. Negative is not: a budget below zero can only fail, which
+ * makes it a mistake dressed as a policy. An empty label is rejected for the
+ * reason the empty string is the unlabelled bucket's sentinel: a config that
+ * meant "calls with no label" should say so through a real key, not through a
+ * value that collides with an internal one.
+ */
+function parseSpend(raw: unknown, source: string): SpendConfig {
+  if (!isPlainObject(raw)) throw new ConfigError('"spend" must be an object', source);
+  rejectUnknownKeys(raw, CONFIG_SPEND_KEYS, source, 'spend.');
+
+  const spend: SpendConfig = {};
+  if (raw.maxUsd !== undefined) {
+    spend.maxUsd = requireNonNegativeNumber(raw.maxUsd, 'spend.maxUsd', source);
+  }
+  if (raw.byLabel !== undefined) {
+    if (!isPlainObject(raw.byLabel)) {
+      throw new ConfigError('"spend.byLabel" must be an object', source);
+    }
+    const byLabel: Record<string, number> = {};
+    for (const [label, value] of Object.entries(raw.byLabel)) {
+      if (label.trim().length === 0) {
+        throw new ConfigError('"spend.byLabel" has an empty label', source);
+      }
+      byLabel[label] = requireNonNegativeNumber(value, `spend.byLabel["${label}"]`, source);
+    }
+    spend.byLabel = byLabel;
+  }
+  return spend;
+}
+
 /**
  * Validates the `baseline` block.
  *
@@ -390,6 +494,8 @@ export function parseConfig(raw: string, source = CONFIG_FILENAME): TrazumConfig
 
   if (document.usage !== undefined) config.usage = parseUsage(document.usage, source);
   if (document.budgets !== undefined) config.budgets = parseBudgets(document.budgets, source);
+  if (document.labels !== undefined) config.labels = parseLabels(document.labels, source);
+  if (document.spend !== undefined) config.spend = parseSpend(document.spend, source);
   if (document.baseline !== undefined) {
     config.baseline = parseBaselineConfig(document.baseline, source);
   }

package/src/conversation.ts

@@ -0,0 +1,305 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageRecord } from './usage.js';
+
+/**
+ * What re-sending the conversation costs.
+ *
+ * ## The line nothing was watching
+ *
+ * A chat or agent workload sends the whole conversation back on every turn. Turn
+ * one is a system prompt and a question; turn twenty is a system prompt and
+ * nineteen previous exchanges and a question. The input grows linearly with the
+ * turn count, and on an agent bill that growth is routinely the largest single
+ * line — larger than the prompt, larger than the answers.
+ *
+ * Nothing in this package could see it. A prompt file shows the system prompt and
+ * not the history. A total shows the sum and not the shape. Even `profile` reported
+ * "input is 71% of this bill" without being able to say that most of that input was
+ * the same sentences, sent again.
+ *
+ * ## What it will and will not claim
+ *
+ * The honest figure is a **ceiling**, and the token half of it is exact: the
+ * input tokens beyond every turn being the size of the session's smallest turn.
+ * That quantity is order-independent — the first-seen anchor made the identical
+ * workload vanish when exported newest-first — and it is immune to billing
+ * rates: a cost-based anchor charged an ordinary 5-minute-TTL agent 77.5%
+ * "growth" on a conversation that never grew, because a cache-miss turn costs
+ * 12.5x a cache-hit turn of the same size. The dollars are that token share of
+ * what the session actually spent, at its own blended rate.
+ *
+ * It is a ceiling and not a saving because part of that growth is the user's own
+ * new messages, which nobody can truncate away, and this module cannot tell those
+ * apart from re-sent history — it sees counts, not content. Reporting the ceiling
+ * as an opportunity would be the flattering direction; reporting nothing because
+ * the exact split is unknowable would be worse. So it reports the bound and says
+ * what it is.
+ *
+ * ## The session key never leaves this module
+ *
+ * A session identifier is somebody's conversation, and in a real log it is often an
+ * account id, a ticket number or an email. It is used to group calls and count
+ * turns; **no figure reported anywhere carries it**, and every result is aggregated
+ * per label. The promise that a usage log handed to Trazum contains no content is
+ * only worth something if nothing identifying comes back out either.
+ */
+
+/** How one label-and-model slice grows across a conversation. */
+export interface ConversationGrowth {
+  label: string;
+  model: string;
+  modelName: string;
+  /** How many distinct conversations were seen. Never which ones. */
+  sessions: number;
+  calls: number;
+  /** Mean input tokens on the smallest turn of a conversation. */
+  minTurnTokens: number;
+  /** Mean input tokens on the largest turn. */
+  maxTurnTokens: number;
+  /** Turns in the longest conversation seen. */
+  longestSession: number;
+  /** Input-side spend: plain input, cache reads and cache writes. */
+  inputUsd: number;
+  /** What that would have been if every turn had cost what its cheapest turn did. */
+  flatUsd: number;
+  /**
+   * `inputUsd - flatUsd`. **A ceiling on what removing conversation growth could
+   * be worth, not a saving** — part of it is the user's own new messages.
+   */
+  growthUsd: number;
+  /** `growthUsd` as a fraction of the whole bill in the log. */
+  shareOfBill: number;
+}
+
+export interface ConversationOptions {
+  catalogue: PricingCatalogue;
+  on?: Date;
+  /**
+   * Slices whose growth is below this share of the bill are dropped, and slices
+   * shorter than `minTurns` never count as conversations at all.
+   */
+  minShare?: number;
+  /**
+   * Conversations shorter than this are ignored.
+   *
+   * Two turns is not a conversation, it is a retry — and a workload that never
+   * exceeds two turns has no growth to measure, so including it would put a row on
+   * screen whose figure is arithmetic noise. Default 3.
+   */
+  minTurns?: number;
+}
+
+/** Input-side cost of one call at its own model's rates. */
+function inputCostOf(record: UsageRecord, catalogue: PricingCatalogue, on: Date): number | null {
+  const model = catalogue.byId.get(record.model);
+  if (!model) return null;
+  const { inputPerMTok } = effectivePricing(model, on);
+  const rates = multipliersFor(model);
+  const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
+  return (
+    per(record.inputTokens, inputPerMTok) +
+    per(record.cacheReadTokens, inputPerMTok * rates.cacheRead) +
+    per(record.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m) +
+    per(record.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h)
+  );
+}
+
+/** Every input-side token of one call, whatever rate it was billed at. */
+const inputTokensOf = (r: UsageRecord): number =>
+  r.inputTokens + r.cacheReadTokens + r.cacheWrite5mTokens + r.cacheWrite1hTokens;
+
+interface Session {
+  turns: number;
+  /**
+   * The smallest turn by **tokens**, not by billed cost.
+   *
+   * Two faults taught this shape. Anchoring on the first record seen made the
+   * measurement depend on the order of the log: the identical workload exported
+   * newest-first computed a *negative* growth and the section silently vanished.
+   * Anchoring on the cheapest turn's *cost* fixed the ordering and introduced
+   * the second fault: per-turn cost varies with the cache multiplier even when
+   * the input never grows — an identical 10,000-token turn costs 12.5x more as
+   * a cache write than as a cache read — so an ordinary 5-minute-TTL agent
+   * whose conversation stayed flat reported 77.5% of its bill as "conversation
+   * growth", and the report recommended trimming history that was not there.
+   *
+   * Tokens are what growth *is*, and they are immune to both: order-independent,
+   * and identical however each turn happened to be billed.
+   */
+  minTokens: number;
+  maxTokens: number;
+  totalTokens: number;
+  totalUsd: number;
+}
+
+/**
+ * Measures what conversation growth costs, from records that carry a session.
+ *
+ * Records without one are skipped rather than lumped together: calls from
+ * different conversations pushed into a single bucket would report a turn count
+ * that is really a call count, and a growth figure derived from it would be
+ * arithmetic performed on a fiction.
+ *
+ * Takes records rather than a report because turn order is the whole measurement,
+ * and a breakdown has already thrown it away.
+ */
+export interface ConversationTracker {
+  /** Feed one parsed record. Records without a session are ignored. */
+  add(record: UsageRecord): void;
+  /** The finished measurement, once the whole bill is known. */
+  finish(totalUsd: number): ConversationGrowth[];
+}
+
+/**
+ * An accumulator, so a profile can measure this in the pass it already makes.
+ *
+ * The alternative was holding every record to hand to a pure function afterwards,
+ * and a usage log is measured in megabytes — a profile that needs the whole file in
+ * memory to answer one question is a profile that stops working on the logs most
+ * worth reading. What this holds is bounded by the number of **conversations**, and
+ * only ever four numbers each.
+ */
+export function createConversationTracker(options: ConversationOptions): ConversationTracker {
+  const { catalogue, on = new Date(), minShare = 0.01, minTurns = 3 } = options;
+
+  // Keyed on the pair, then on the session inside it. A newline cannot occur in a
+  // model id, and both halves are trimmed strings.
+  const slices = new Map<string, Map<string, Session>>();
+
+  const add = (record: UsageRecord): void => {
+    if (record.session === null) return;
+    const cost = inputCostOf(record, catalogue, on);
+    // An unpriced model contributes no dollars anywhere else either; including it
+    // here would report growth of zero on a workload that grew.
+    if (cost === null) return;
+
+    const sliceKey = `${record.label ?? UNLABELLED}\n${record.model}`;
+    let sessions = slices.get(sliceKey);
+    if (!sessions) {
+      sessions = new Map();
+      slices.set(sliceKey, sessions);
+    }
+
+    const tokens = inputTokensOf(record);
+    const existing = sessions.get(record.session);
+    if (!existing) {
+      sessions.set(record.session, {
+        turns: 1,
+        minTokens: tokens,
+        maxTokens: tokens,
+        totalTokens: tokens,
+        totalUsd: cost,
+      });
+      return;
+    }
+    existing.turns += 1;
+    existing.minTokens = Math.min(existing.minTokens, tokens);
+    existing.maxTokens = Math.max(existing.maxTokens, tokens);
+    existing.totalTokens += tokens;
+    existing.totalUsd += cost;
+  };
+
+  const finish = (totalUsd: number): ConversationGrowth[] => {
+  const out: ConversationGrowth[] = [];
+
+  for (const [sliceKey, sessions] of slices) {
+    const split = sliceKey.indexOf('\n');
+    const label = sliceKey.slice(0, split);
+    const modelId = sliceKey.slice(split + 1);
+    const model = catalogue.byId.get(modelId);
+    if (!model) continue;
+
+    /**
+     * Only conversations long enough to have grown. A two-turn session has one
+     * step of growth and is as likely to be a retry, and averaging it in drags the
+     * measured shape towards flat — understating the real thing, which is the
+     * direction that flatters.
+     */
+    const long = [...sessions.values()].filter((s) => s.turns >= minTurns);
+    if (long.length === 0) continue;
+
+    let inputUsd = 0;
+    let flatUsd = 0;
+    let minTokens = 0;
+    let maxTokens = 0;
+    let calls = 0;
+    let longestSession = 0;
+
+    for (const session of long) {
+      inputUsd += session.totalUsd;
+      /**
+       * The growth is measured in tokens — `totalTokens - minTokens·turns`,
+       * which is exact, order-independent, and zero for a conversation whose
+       * turns never change size however each one was billed. The money is that
+       * token share of what the session actually spent: pricing the excess at
+       * any single rate would either overstate it (full input rate, when most
+       * re-sent history is cache-read cheap) or move with billing noise (the
+       * cheapest turn's rate, which is what mis-billed a flat cached agent).
+       */
+      const flatTokens = session.minTokens * session.turns;
+      flatUsd +=
+        session.totalTokens > 0
+          ? session.totalUsd * (flatTokens / session.totalTokens)
+          : session.totalUsd;
+      minTokens += session.minTokens;
+      maxTokens += session.maxTokens;
+      calls += session.turns;
+      longestSession = Math.max(longestSession, session.turns);
+    }
+
+    const growthUsd = inputUsd - flatUsd;
+    const shareOfBill = totalUsd > 0 ? growthUsd / totalUsd : 0;
+    /**
+     * Below the attention threshold — **and that covers shrinking conversations
+     * too**, because a negative share is below any threshold at or above zero.
+     *
+     * There was a separate `growthUsd <= 0` check here. No mutation could break
+     * it: every case it caught, this one caught first. A guard nothing can
+     * distinguish is not defence in depth, it is a second place for the intent to
+     * drift from the code, so the intent lives in this comment instead.
+     *
+     * The case it was written for is ordinary: an opening turn carrying an
+     * attachment or a retrieved document is bigger than everything after it, and
+     * reporting that as "conversation growth" would be a negative ceiling
+     * presented as an opportunity.
+     */
+    if (shareOfBill < minShare) continue;
+
+    out.push({
+      label,
+      model: modelId,
+      modelName: model.displayName,
+      sessions: long.length,
+      calls,
+      minTurnTokens: minTokens / long.length,
+      maxTurnTokens: maxTokens / long.length,
+      longestSession,
+      inputUsd,
+      flatUsd,
+      growthUsd,
+      shareOfBill,
+    });
+  }
+
+    return out.sort((a, b) => b.growthUsd - a.growthUsd);
+  };
+
+  return { add, finish };
+}
+
+/**
+ * The same measurement over a list of records, for a caller holding one already.
+ *
+ * `profileUsage` uses the tracker instead, so it never has to keep the log.
+ */
+export function conversationGrowth(
+  records: readonly UsageRecord[],
+  totalUsd: number,
+  options: ConversationOptions,
+): ConversationGrowth[] {
+  const tracker = createConversationTracker(options);
+  for (const record of records) tracker.add(record);
+  return tracker.finish(totalUsd);
+}