@trazum/cli 1.35.0 → 1.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.35.0"
+    "@trazum/core": "1.36.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -119,6 +119,20 @@ ${bold('OPTIONS FOR optimize')}
   --calls <n>                 Calls per month. Default: ${d.callsPerMonth}.
   --output-tokens <n>         Average output tokens. Default: ${d.avgOutputTokens}.
   --cache-hit-rate <0-1>      Estimated cache hit rate. Default: ${d.cacheHitRate}.
+  --all-labels                With --from-log: every prompt in the config's
+                              "labels" map, optimised and priced against its
+                              own measured traffic, ranked by what the change
+                              is worth — plus the mismatches in both
+                              directions (mapped prompts with no traffic,
+                              traffic with no mapped prompt).
+  --from-log <usage.jsonl>    Measure the three figures above from a usage log
+                              instead of typing them: real call count, real
+                              output size, real cache share, and the model the
+                              calls actually went to. Refuses the typed flags
+                              beside it, scales to a month only past a full
+                              week of data, and says which figures are
+                              measured. Pair with --label, or map the prompt
+                              under "labels" in trazum.config.json.
   --batch                     The work tolerates latency (Batch API, 50% off).
   --disable <id,id>           Turn off specific rules (see "trazum rules").
   --suggest                   Ask the LLM for phrase-level rewrites and list them
@@ -444,6 +458,18 @@ ${bold('EXAMPLES')}
     mustBeNonNegative: (name, raw) =>
       `--${name} must be a non-negative number (received: "${raw}").`,
     badLevel: (received) => `--level must be "safe" or "aggressive" (received: "${received}").`,
+    allLabelsNeedsLog: () =>
+      '--all-labels ranks prompts by measured traffic, so it needs --from-log <usage.jsonl>. Without a log every saving would be multiplied by the same typed guess, which ranks prompts by length and calls it a priority.',
+    allLabelsNeedsMap: () =>
+      '--all-labels reads the "labels" map in trazum.config.json — label to prompt file — and this config has none. Map at least one workload to its prompt.',
+    fromLogConflict: (flag) =>
+      `--from-log measures the figure --${flag} types, and merging a measurement with a guess produces a number that is neither. Pass one or the other.`,
+    fromLogNeedsLabel: (available) =>
+      `--from-log needs to know which workload this prompt is: pass --label, or map the prompt file under "labels" in trazum.config.json. Labels with traffic in this log: ${available}.`,
+    fromLogAmbiguousLabel: (target, labels) =>
+      `${target} is mapped to more than one label in trazum.config.json (${labels}), so --from-log cannot pick one silently. Pass --label.`,
+    fromLogLabelEmpty: (label, available) =>
+      `No priced call in this log carries the label "${label}", so there is nothing to measure — a zero-call profile would price this change as worthless rather than as unmeasured. Labels with traffic: ${available}.`,
     unknownRuleInDisable: (id) => `Unknown rule in --disable: "${id}". Full list: trazum rules`,
     unknownCommand: (command) => `Unknown command: "${command}". Try "trazum --help".`,
     missingInputFile: () => 'Missing input file. Use "-" to read from standard input.',
@@ -510,6 +536,30 @@ ${bold('EXAMPLES')}
     costWith: (modelName) => `Cost with ${modelName}`,
     usageLine: (calls, outputTokens, batch) =>
       `${calls} calls/month · ${outputTokens} output tokens per call${batch ? ' · Batch API' : ''}`,
+    allLabelsHeading: (count) => `Every mapped prompt against its own measured traffic — ${count} ranked by what the change is worth`,
+    allLabelsRow: (saving) => `${saving}/month if optimised`,
+    allLabelsRowPeriod: (saving) => `${saving} over the measured period if optimised`,
+    allLabelsFooter: () =>
+      'Ranked by measured traffic, not by prompt length: a big prompt on a dead workload is worth less than a small one on a busy one. Each figure is this prompt\'s token delta at its own label\'s measured rate.',
+    allLabelsUnmapped: (label, usd) =>
+      `${label} carries ${usd} of measured spend and no prompt file is mapped to it — the workload nobody can optimise because nobody said where it lives. Map it under "labels" in trazum.config.json.`,
+    allLabelsDead: (label, path) =>
+      `${label} is mapped to ${path} and has no traffic in this log — a retired workload, a renamed label, or a typo that has been silently doing nothing.`,
+    allLabelsUnreadable: (label, path) =>
+      `${label} is mapped to ${path}, which could not be read. The mapping exists; the file does not.`,
+    usageLineMeasured: (calls, days, scaled, outputTokens, batch) =>
+      `${calls} calls measured over ${days} days — ${scaled}/month at that rate · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
+    usageLineMeasuredPeriod: (calls, days, outputTokens, batch) =>
+      `${calls} calls measured${days === null ? ' (the log carries no clock)' : ` over ${days} days`} · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
+    measuredModelShare: (model, share, count) =>
+      `This label ran on ${count} models; the figures use ${model}, which carried ${share} of its spend.`,
+    measuredNoOutput: () =>
+      'No call in this slice recorded output tokens, so the output half of every figure below is $0 measured — not $0 assumed.',
+    perPeriodSaving: (saving, pct) => `saving ${saving} over the measured period (${pct}%)`,
+    periodNotScaled: (days) =>
+      days === null
+        ? 'Not scaled to a month: the log carries no clock, so there is no rate to scale. These figures cover exactly the calls measured.'
+        : `Not scaled to a month: ${days} days is under the week a scaling needs — shorter than one weekly cycle multiplies whichever part of the cycle it caught. These figures cover exactly the period measured.`,
     perMonthSaving: (saving, pct) => `saving ${saving}/month (${pct}%)`,
     beyondShortening: () => 'Beyond shortening the prompt',
     biggestLever: () => 'Start here:',

package/src/i18n/es.ts

@@ -109,6 +109,20 @@ ${bold('OPCIONES DE optimize')}
   --calls <n>                 Llamadas al mes. Por defecto: ${d.callsPerMonth}.
   --output-tokens <n>         Tokens de salida medios. Por defecto: ${d.avgOutputTokens}.
   --cache-hit-rate <0-1>      Tasa de acierto de caché estimada. Por defecto: ${d.cacheHitRate}.
+  --all-labels                Con --from-log: cada prompt del mapa "labels"
+                              de la config, optimizado y valorado contra su
+                              propio tráfico medido, ordenado por lo que vale
+                              el cambio — más los desajustes en ambos sentidos
+                              (prompts mapeados sin tráfico, tráfico sin
+                              prompt mapeado).
+  --from-log <usage.jsonl>    Mide las tres cifras de arriba desde un registro
+                              de uso en vez de teclearlas: llamadas reales,
+                              tamaño de salida real, cuota de caché real y el
+                              modelo al que fueron las llamadas. Rechaza los
+                              flags tecleados a su lado, escala a un mes solo
+                              con una semana completa de datos, y dice qué
+                              cifras están medidas. Combínalo con --label, o
+                              mapea el prompt en "labels" de trazum.config.json.
   --batch                     El trabajo tolera latencia (Batch API, 50% menos).
   --disable <id,id>           Desactiva reglas concretas (ver "trazum rules").
   --suggest                   Pide al LLM reescrituras a nivel de frase y las lista
@@ -451,6 +465,18 @@ ${bold('EJEMPLOS')}
     mustBeNonNegative: (name, raw) =>
       `--${name} debe ser un número no negativo (recibido: "${raw}").`,
     badLevel: (received) => `--level debe ser "safe" o "aggressive" (recibido: "${received}").`,
+    allLabelsNeedsLog: () =>
+      '--all-labels ordena los prompts por tráfico medido, así que necesita --from-log <usage.jsonl>. Sin registro cada ahorro se multiplicaría por la misma suposición tecleada, lo que ordena los prompts por longitud y lo llama prioridad.',
+    allLabelsNeedsMap: () =>
+      '--all-labels lee el mapa "labels" de trazum.config.json — etiqueta a fichero de prompt — y esta config no tiene ninguno. Mapea al menos una carga a su prompt.',
+    fromLogConflict: (flag) =>
+      `--from-log mide la cifra que --${flag} teclea, y mezclar una medición con una suposición produce un número que no es ninguna de las dos. Pasa una u otra.`,
+    fromLogNeedsLabel: (available) =>
+      `--from-log necesita saber qué carga es este prompt: pasa --label, o mapea el fichero bajo "labels" en trazum.config.json. Etiquetas con tráfico en este registro: ${available}.`,
+    fromLogAmbiguousLabel: (target, labels) =>
+      `${target} está mapeado a más de una etiqueta en trazum.config.json (${labels}), así que --from-log no puede elegir una en silencio. Pasa --label.`,
+    fromLogLabelEmpty: (label, available) =>
+      `Ninguna llamada valorada de este registro lleva la etiqueta "${label}", así que no hay nada que medir — un perfil de cero llamadas valoraría este cambio como inútil en vez de como no medido. Etiquetas con tráfico: ${available}.`,
     unknownRuleInDisable: (id) =>
       `Regla desconocida en --disable: "${id}". Lista completa: trazum rules`,
     unknownCommand: (command) => `Comando desconocido: "${command}". Prueba con "trazum --help".`,
@@ -519,6 +545,30 @@ ${bold('EJEMPLOS')}
       `${calls} llamadas/mes · ${outputTokens} tokens de salida por llamada${
         batch ? ' · Batch API' : ''
       }`,
+    allLabelsHeading: (count) => `Cada prompt mapeado contra su propio tráfico medido — ${count} ordenados por lo que vale el cambio`,
+    allLabelsRow: (saving) => `${saving}/mes si se optimiza`,
+    allLabelsRowPeriod: (saving) => `${saving} en el periodo medido si se optimiza`,
+    allLabelsFooter: () =>
+      'Ordenado por tráfico medido, no por longitud del prompt: un prompt grande en una carga muerta vale menos que uno pequeño en una ocupada. Cada cifra es el delta de tokens de este prompt al ritmo medido de su propia etiqueta.',
+    allLabelsUnmapped: (label, usd) =>
+      `${label} lleva ${usd} de gasto medido y ningún fichero de prompt está mapeado a ella — la carga que nadie puede optimizar porque nadie dijo dónde vive. Mapéala en "labels" de trazum.config.json.`,
+    allLabelsDead: (label, path) =>
+      `${label} está mapeada a ${path} y no tiene tráfico en este registro — una carga retirada, una etiqueta renombrada, o una errata que lleva sin hacer nada en silencio.`,
+    allLabelsUnreadable: (label, path) =>
+      `${label} está mapeada a ${path}, que no se pudo leer. El mapeo existe; el fichero no.`,
+    usageLineMeasured: (calls, days, scaled, outputTokens, batch) =>
+      `${calls} llamadas medidas en ${days} días — ${scaled}/mes a ese ritmo · ${outputTokens} tokens de salida por llamada, medidos${batch ? ' · Batch API' : ''}`,
+    usageLineMeasuredPeriod: (calls, days, outputTokens, batch) =>
+      `${calls} llamadas medidas${days === null ? ' (el registro no tiene reloj)' : ` en ${days} días`} · ${outputTokens} tokens de salida por llamada, medidos${batch ? ' · Batch API' : ''}`,
+    measuredModelShare: (model, share, count) =>
+      `Esta etiqueta corrió en ${count} modelos; las cifras usan ${model}, que llevó el ${share} de su gasto.`,
+    measuredNoOutput: () =>
+      'Ninguna llamada de este corte registró tokens de salida, así que la mitad de salida de cada cifra de abajo es $0 medido — no $0 supuesto.',
+    perPeriodSaving: (saving, pct) => `ahorro de ${saving} en el periodo medido (${pct}%)`,
+    periodNotScaled: (days) =>
+      days === null
+        ? 'Sin escalar a un mes: el registro no tiene reloj, así que no hay ritmo que escalar. Estas cifras cubren exactamente las llamadas medidas.'
+        : `Sin escalar a un mes: ${days} días queda por debajo de la semana que un escalado necesita — menos de un ciclo semanal multiplica la parte del ciclo que pilló. Estas cifras cubren exactamente el periodo medido.`,
     perMonthSaving: (saving, pct) => `ahorro ${saving}/mes (${pct}%)`,
     beyondShortening: () => 'Además de acortar el prompt',
     biggestLever: () => 'Empieza por aquí:',

package/src/i18n/types.ts

@@ -37,6 +37,13 @@ export interface CliMessages {
     optionNeedsValue(name: string): string;
     mustBeNonNegative(name: string, raw: string): string;
     badLevel(received: string): string;
+    /** `--from-log`'s refusals: contradiction, missing label, ambiguity, emptiness. */
+    allLabelsNeedsLog(): string;
+    allLabelsNeedsMap(): string;
+    fromLogConflict(flag: string): string;
+    fromLogNeedsLabel(available: string): string;
+    fromLogAmbiguousLabel(target: string, labels: string): string;
+    fromLogLabelEmpty(label: string, available: string): string;
     unknownRuleInDisable(id: string): string;
     unknownCommand(command: string): string;
     unknownFlag(name: string, allowed: string): string;
@@ -82,6 +89,28 @@ export interface CliMessages {
     llmRejected(reason: string): string;
     costWith(modelName: string): string;
     usageLine(calls: string, outputTokens: number, batch: boolean): string;
+    /**
+     * `--from-log`: the usage line names its provenance. Measured and typed
+     * are different claims about the same multiplication, and under the week
+     * floor nothing says "month".
+     */
+    /**
+     * `--all-labels`: every mapped prompt against its own measured traffic,
+     * ranked by what the change is worth, with both coverage mismatches named.
+     */
+    allLabelsHeading(count: string): string;
+    allLabelsRow(saving: string): string;
+    allLabelsRowPeriod(saving: string): string;
+    allLabelsFooter(): string;
+    allLabelsUnmapped(label: string, usd: string): string;
+    allLabelsDead(label: string, path: string): string;
+    allLabelsUnreadable(label: string, path: string): string;
+    usageLineMeasured(calls: string, days: string, scaled: string, outputTokens: number, batch: boolean): string;
+    usageLineMeasuredPeriod(calls: string, days: string | null, outputTokens: number, batch: boolean): string;
+    measuredModelShare(model: string, share: string, count: string): string;
+    measuredNoOutput(): string;
+    perPeriodSaving(saving: string, pct: string): string;
+    periodNotScaled(days: string | null): string;
     perMonthSaving(saving: string, pct: string): string;
     beyondShortening(): string;
     biggestLever(): string;

package/src/index.ts

@@ -23,6 +23,8 @@ import {
   coverageDrift,
   driversBetween,
   explainGateFailure,
+  labelCoverage,
+  measuredUsage,
   gateMargin,
   GATE_MARGIN_TIGHT,
   estimateTokens,
@@ -72,6 +74,7 @@ import {
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 import type {
+  MeasuredUsage,
   BaselineBreach,
   BaselineChange,
   BaselineComparison,
@@ -165,6 +168,7 @@ interface Args {
 
 const VALUE_FLAGS = new Set([
   'against',
+  'from-log',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -305,6 +309,23 @@ function levelFlag(args: Args, config: TrazumConfig, t: CliMessages): RuleLevel
  * model id. It beats the default because reading the code is better than
  * assuming, and loses to config because being told is better than reading.
  */
+/**
+ * One usage log, gzip included, shared by every command that reads one.
+ *
+ * A `.gz` that will not decompress is an error naming the file — skipping it
+ * would be a figure quietly missing a day, the failure this repository
+ * refuses everywhere it can occur.
+ */
+async function readUsageLog(file: string, t: CliMessages): Promise<string> {
+  if (!file.endsWith('.gz')) return readFile(file, 'utf8');
+  const compressed = await readFile(file);
+  try {
+    return gunzipSync(compressed).toString('utf8');
+  } catch (error) {
+    throw new Error(t.profile.badGzip(file, error instanceof Error ? error.message : String(error)));
+  }
+}
+
 function usageFrom(
   args: Args,
   config: TrazumConfig,
@@ -436,7 +457,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
     'level', 'model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch',
     'disable', 'llm', 'exact-tokens', 'diff', 'reorder', 'out', 'o',
     'tokens-only', 'cost', 'prompt', 'suggest', 'apply-suggestions',
-    'cache-suggestions',
+    'cache-suggestions', 'from-log', 'label', 'all-labels',
   ],
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
@@ -629,6 +650,8 @@ function printReport(
   suggestions: { result: SuggestResult; applied: boolean; locale: Locale } | null = null,
   /** They named a scenario, and the host is suppressing the money anyway. */
   namedScenario = false,
+  /** Present when the usage came from a log rather than from typing. */
+  measured: MeasuredUsage | null = null,
 ): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const sourceNote =
@@ -776,7 +799,7 @@ function printReport(
   if (tokensOnly) {
     printTokensOnly(result, host, t, n, namedScenario);
   } else {
-    printMoney(result, t, n);
+    printMoney(result, t, n, measured);
   }
 
   // On a subscription, an advisory whose entire pitch is money is not weaker
@@ -852,17 +875,61 @@ function printReport(
 }
 
 /** The cost section, for anyone billed by the token. */
-function printMoney(result: OptimizationResult, t: CliMessages, n: (v: number) => string): void {
+function printMoney(
+  result: OptimizationResult,
+  t: CliMessages,
+  n: (v: number) => string,
+  /** Present when the usage came from a log rather than from typing. */
+  measured: MeasuredUsage | null = null,
+): void {
   const { savings } = result;
   console.log();
   console.log(c.bold(t.report.costWith(savings.modelDisplayName)));
-  console.log(
-    `  ${t.report.usageLine(
-      n(result.usage.callsPerMonth),
-      result.usage.avgOutputTokens,
-      result.usage.batchEligible,
-    )}`,
-  );
+  /**
+   * The usage line names its provenance. "1,000 calls/month" typed and
+   * "1,043 calls measured over 12 days, scaled" are different claims about
+   * the same multiplication, and the reader budgeting on the result must
+   * know which one they are holding. Under the week floor nothing is scaled
+   * and nothing says "month": the figures cover exactly the period measured.
+   */
+  if (measured !== null) {
+    if (measured.scaled !== null) {
+      console.log(
+        `  ${t.report.usageLineMeasured(
+          n(measured.calls),
+          measured.scaled.fromDays.toFixed(1),
+          n(result.usage.callsPerMonth),
+          result.usage.avgOutputTokens,
+          result.usage.batchEligible,
+        )}`,
+      );
+    } else {
+      console.log(
+        `  ${t.report.usageLineMeasuredPeriod(
+          n(measured.calls),
+          measured.spanDays === null ? null : measured.spanDays.toFixed(1),
+          result.usage.avgOutputTokens,
+          result.usage.batchEligible,
+        )}`,
+      );
+    }
+    if (measured.models.count > 1) {
+      console.log(
+        `  ${c.dim(wrap(t.report.measuredModelShare(measured.models.chosen, `${(measured.models.chosenShareOfSpend * 100).toFixed(0)}%`, n(measured.models.count)), 74, '  '))}`,
+      );
+    }
+    if (measured.outputUnmeasured) {
+      console.log(`  ${c.dim(wrap(t.report.measuredNoOutput(), 74, '  '))}`);
+    }
+  } else {
+    console.log(
+      `  ${t.report.usageLine(
+        n(result.usage.callsPerMonth),
+        result.usage.avgOutputTokens,
+        result.usage.batchEligible,
+      )}`,
+    );
+  }
   // Said, not assumed. Once prices can be overlaid locally, a figure from the
   // bundled catalogue and a figure from somebody's JSON file look identical, and
   // the reader has to be able to tell which one they are about to budget against.
@@ -875,17 +942,27 @@ function printMoney(result: OptimizationResult, t: CliMessages, n: (v: number) =
       `  ${c.yellow(t.report.pricingOverlaid(touched.join(', '), result.pricingSource.lastReviewed))}`,
     );
   }
+  const periodOnly = measured !== null && measured.scaled === null;
   console.log(
     `  ${formatUsd(savings.perMonth.before.totalUsd)} → ` +
       `${c.green(formatUsd(savings.perMonth.after.totalUsd))}   ` +
       c.bold(
-        t.report.perMonthSaving(
-          formatUsd(savings.monthlySavingsUsd),
-          savings.monthlySavingsPct.toFixed(1),
-        ),
+        periodOnly
+          ? t.report.perPeriodSaving(
+              formatUsd(savings.monthlySavingsUsd),
+              savings.monthlySavingsPct.toFixed(1),
+            )
+          : t.report.perMonthSaving(
+              formatUsd(savings.monthlySavingsUsd),
+              savings.monthlySavingsPct.toFixed(1),
+            ),
       ),
   );
-
+  if (periodOnly) {
+    console.log(
+      `  ${c.dim(wrap(t.report.periodNotScaled(measured!.spanDays === null ? null : measured!.spanDays.toFixed(1)), 74, '  '))}`,
+    );
+  }
 }
 
 /**
@@ -1372,6 +1449,97 @@ async function commandOptimize(
   t: CliMessages,
   locale: Locale,
 ): Promise<void> {
+  /**
+   * `--all-labels`: every mapped prompt against its own measured traffic,
+   * ranked by what the change is worth — the list a person actually wants,
+   * which is "which prompt do I edit first".
+   *
+   * Requires `--from-log`, because ranking estimated savings that were all
+   * multiplied by the same typed guess ranks the prompts by length, and calls
+   * that a priority. And it renders both coverage mismatches at the end: a
+   * prompt mapped to a label with no traffic is dead weight or a rename, and
+   * a label carrying real money with no prompt mapped is the workload nobody
+   * can optimise because nobody said where it lives.
+   */
+  if (boolFlag(args, 'all-labels')) {
+    const fromLogPath = stringFlag(args, 'from-log');
+    if (fromLogPath === undefined) throw new Error(t.errors.allLabelsNeedsLog());
+    const labelsMap = config.labels ?? {};
+    if (Object.keys(labelsMap).length === 0) throw new Error(t.errors.allLabelsNeedsMap());
+    const report = profileUsage(await readUsageLog(fromLogPath, t), { catalogue: pricing });
+    const coverage = labelCoverage(report, labelsMap);
+    const level = levelFlag(args, config, t);
+
+    interface Row {
+      label: string;
+      path: string;
+      tokensBefore: number;
+      tokensAfter: number;
+      savingUsd: number;
+      periodOnly: boolean;
+      spentUsd: number;
+    }
+    const rows: Row[] = [];
+    const unreadable: { label: string; path: string }[] = [];
+    for (const { label, promptPath } of coverage.joined) {
+      const m = measuredUsage(report, label, { batchEligible: config.usage?.batchEligible ?? false });
+      if (m === null) continue;
+      let text: string;
+      try {
+        text = await readFile(promptPath, 'utf8');
+      } catch {
+        unreadable.push({ label, path: promptPath });
+        continue;
+      }
+      const r = optimize(text, { level, usage: m.profile, locale, pricing });
+      rows.push({
+        label,
+        path: promptPath,
+        tokensBefore: r.tokensBefore,
+        tokensAfter: r.tokensAfter,
+        savingUsd: r.savings.monthlySavingsUsd,
+        periodOnly: m.scaled === null,
+        spentUsd: m.spentUsd,
+      });
+    }
+    rows.sort((a, b) => b.savingUsd - a.savingUsd);
+
+    const n = (value: number): string => value.toLocaleString(t.numberLocale);
+    console.log(c.bold(t.report.allLabelsHeading(n(rows.length))));
+    for (const row of rows) {
+      const saving = row.periodOnly
+        ? t.report.allLabelsRowPeriod(formatUsd(row.savingUsd))
+        : t.report.allLabelsRow(formatUsd(row.savingUsd));
+      console.log(
+        `  ${row.savingUsd > 0 ? c.green('→') : c.dim('·')} ${c.bold(row.label)}  ${saving}  ${c.dim(`${row.path} · ${n(row.tokensBefore)} → ${n(row.tokensAfter)} tokens · ${formatUsd(row.spentUsd)} measured`)}`,
+      );
+    }
+    if (rows.length > 0) {
+      console.log(`  ${c.dim(wrap(t.report.allLabelsFooter(), 74, '  '))}`);
+    }
+
+    /**
+     * The mismatches, both directions, never silently. These are the two
+     * failures neither side can see alone.
+     */
+    for (const gap of coverage.trafficWithoutPrompt.slice(0, 5)) {
+      console.log(
+        `  ${c.yellow('!')} ${wrap(t.report.allLabelsUnmapped(gap.label, formatUsd(gap.spentUsd)), 74, '    ')}`,
+      );
+    }
+    for (const dead of coverage.mappedWithoutTraffic) {
+      console.log(
+        `  ${c.dim(wrap(t.report.allLabelsDead(dead.label, dead.promptPath), 74, '    '))}`,
+      );
+    }
+    for (const miss of unreadable) {
+      console.log(
+        `  ${c.yellow('!')} ${wrap(t.report.allLabelsUnreadable(miss.label, miss.path), 74, '    ')}`,
+      );
+    }
+    return;
+  }
+
   const target = args.positional[0];
   const raw = await readInput(target, t);
   const level = levelFlag(args, config, t);
@@ -1393,7 +1561,61 @@ async function commandOptimize(
   // Detection sits between config and defaults, as everywhere: a flag beats
   // config, config beats what the code says, and what the code says beats a
   // built-in default that has no idea which provider you use.
-  const usage = usageFrom(args, config, t, source?.model);
+  let usage = usageFrom(args, config, t, source?.model);
+
+  /**
+   * `--from-log`: the multiplication stops guessing.
+   *
+   * The saving printed below is `token delta × usage`, and until now every
+   * part of `usage` was typed by a human. A usage log knows the real call
+   * count, the real output size, the real cache share and the model the
+   * calls actually went to — so `--from-log` measures them, and the typed
+   * flags are refused beside it rather than merged: measuring and typing the
+   * same figure is a contradiction, not a preference order.
+   */
+  const fromLog = stringFlag(args, 'from-log');
+  let measured: MeasuredUsage | null = null;
+  if (fromLog !== undefined) {
+    for (const flag of ['calls', 'output-tokens', 'cache-hit-rate', 'model']) {
+      if (args.flags.get(flag) !== undefined) {
+        throw new Error(t.errors.fromLogConflict(flag));
+      }
+    }
+    const report = profileUsage(await readUsageLog(fromLog, t), { catalogue: pricing });
+
+    /**
+     * Which label this prompt is. `--label` says it outright; otherwise the
+     * config's `labels` map is read in reverse — it maps labels to prompt
+     * files, and the file on the command line is looked up among its values.
+     * Ambiguity (two labels mapped to one file) is an error naming both,
+     * never a silent first match.
+     */
+    let label = stringFlag(args, 'label');
+    if (label === undefined && target !== undefined && config.labels !== undefined) {
+      const hits = Object.entries(config.labels)
+        .filter(([, path]) => resolvePath(path) === resolvePath(target))
+        .map(([name]) => name);
+      if (hits.length > 1) throw new Error(t.errors.fromLogAmbiguousLabel(target, hits.join(', ')));
+      label = hits[0];
+    }
+    if (label === undefined) {
+      const available = report.byLabel
+        .map((row) => (row.label === UNLABELLED ? t.profile.unlabelled() : row.label))
+        .join(', ');
+      throw new Error(t.errors.fromLogNeedsLabel(available || '—'));
+    }
+
+    measured = measuredUsage(report, label, {
+      batchEligible: boolFlag(args, 'batch', config.usage?.batchEligible ?? false),
+    });
+    if (measured === null) {
+      const available = report.byLabel
+        .map((row) => (row.label === UNLABELLED ? t.profile.unlabelled() : row.label))
+        .join(', ');
+      throw new Error(t.errors.fromLogLabelEmpty(label, available || '—'));
+    }
+    usage = measured.profile;
+  }
 
   const disableRules = disabledRules(args, config) ?? [];
   for (const id of disableRules) {
@@ -1586,7 +1808,15 @@ async function commandOptimize(
   // Cursor wants the dollars, and they should not have to leave the editor to
   // see them.
   const host = detectHost();
-  const tokensOnly = boolFlag(args, 'cost')
+  /**
+   * `--from-log` implies `--cost`, and the reasoning is different from the
+   * `--calls` case documented below: `--calls` is a typed scenario parameter,
+   * but a usage log with billed token counts is *evidence* — proof this
+   * prompt's traffic goes to a metered API, whatever the terminal running
+   * the command bills like. Withholding the money there would suppress
+   * exactly the figures the person measured in order to see.
+   */
+  const tokensOnly = boolFlag(args, 'cost') || measured !== null
     ? false
     : boolFlag(args, 'tokens-only') || host.billing === 'subscription';
   /**
@@ -1609,6 +1839,7 @@ async function commandOptimize(
       ? { result: suggestions, applied: boolFlag(args, 'apply-suggestions'), locale }
       : null,
     namedScenario,
+    measured,
   );
   if (outPath) {
     console.log(c.dim(t.report.wroteTo(outPath)));
@@ -2031,16 +2262,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
    * alternative — skipping it — is a total quietly missing a day, which is
    * the failure this repository refuses in every other place it can occur.
    */
-  const readLog = async (file: string): Promise<string> => {
-    if (!file.endsWith('.gz')) return readFile(file, 'utf8');
-    const compressed = await readFile(file);
-    try {
-      return gunzipSync(compressed).toString('utf8');
-    } catch (error) {
-      throw new Error(t.profile.badGzip(file, error instanceof Error ? error.message : String(error)));
-    }
-  };
-  const logTexts = await Promise.all(logFiles.map((file) => readLog(file)));
+  const logTexts = await Promise.all(logFiles.map((file) => readUsageLog(file, t)));
   // A file that does not end in a newline would otherwise glue its last record
   // to the next file's first one, and both would be reported as unreadable.
   const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
@@ -2206,7 +2428,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
       // The same reader as the log itself, so `--against last-month.jsonl.gz`
       // works: a comparison that could only read one of the two formats would
       // be a flag that fails on exactly the rotated file it exists to read.
-      ? profileUsage(await readLog(againstPath), {
+      ? profileUsage(await readUsageLog(againstPath, t), {
           catalogue: pricing,
           label: onlyLabel,
           // The same window on both sides, for the same reason as the label: