@trazum/cli 1.39.0 → 1.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.39.0",
+  "version": "1.40.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.39.0"
+    "@trazum/core": "1.40.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -41,6 +41,7 @@ ${bold('USAGE')}
   trazum route <log.jsonl> --prompt-file <file> --cases <file> --yes
   trazum plan <log.jsonl|dir> [options]
   trazum verify <plan.json> --against <newer.jsonl|dir> [options]
+  trazum history <dir-of-stored-reports> [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -318,6 +319,20 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR history')}
+  --markdown-out <file>       Also write the series as Markdown, for a CI job
+                              summary or a pull request comment.
+  --json                      The history as data.
+
+  Takes a directory of stored reports — the --json documents profile already
+  writes — plus any saved plans beside them, and builds the series no
+  pairwise comparison can see: a workload climbing a little every period, a
+  model share rising since a date, a cache share decaying slowly enough that
+  no single week's report called it a finding, and the same action planned
+  again and again with nothing executing it. Derived from stored reports,
+  never re-parsed logs, so a year of JSON is enough and the raw logs can be
+  thrown away. Shapes are named; nothing is forecast.
+
 ${bold('OPTIONS FOR verify')}
   --against <log|dir>         The newer usage log the plan is held to. Required.
   --gate                      Exit 1 when an action did not produce what the
@@ -1432,6 +1447,39 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  history: {
+    noTarget: () =>
+      'Point this at a directory of stored reports: trazum history reports/. It reads the --json documents "trazum profile" writes (and any saved plans beside them) and builds the series no pairwise comparison can see.',
+    needsThree: (count) =>
+      `A series needs at least three dated reports, and this directory has ${count}. Two reports is a comparison, and "trazum profile --against" already does that better.`,
+    heading: (periods, from, to) => `The long run: ${periods} periods, ${from} → ${to}`,
+    periodRow: (name, usd, calls, days) => `${name}  ${usd} · ${calls} calls · ${days} days`,
+    runLabel: (label, periods, sinceName, from, to) =>
+      `${label} has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. A shape, not a forecast.`,
+    runModel: (model, periods, sinceName, from, to) =>
+      `${model}'s share of the bill has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. The totals can look flat while the mix moves under them.`,
+    runCache: (periods, sinceName, from, to) =>
+      `The cache share has decayed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to} — slowly enough that no single report called it a finding, which is exactly why a series exists.`,
+    repeated: (kind, label, model, appearances, first, last) => {
+      const what =
+        kind === 'route'
+          ? `Routing ${label} (${model})`
+          : kind === 'batch'
+            ? `Batching ${label} (${model})`
+            : kind === 'route+batch'
+              ? `Routing and batching ${label} (${model})`
+              : kind === 'fix-truncation'
+                ? `Fixing the truncation retries on ${label} (${model})`
+                : `Fixing the cache on ${label} (${model})`;
+      const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
+      return `${what} has been planned ${appearances} times${span} and is still in the newest plan — a decision nobody is revisiting.`;
+    },
+    undated: (name) => `${name} carries no span, so it is on no timeline above — named, never silently absorbed.`,
+    unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
+    footer: () =>
+      'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable — where these lines go next is yours to judge.',
+  },
+
   verify: {
     noTarget: () =>
       'Point this at a saved plan and a newer log: trazum verify plan.json --against usage.jsonl. It says, per action, whether the change arrived, did not arrive, or cannot be told — and never fewer than those three.',

package/src/i18n/es.ts

@@ -28,6 +28,7 @@ ${bold('USO')}
   trazum route <log.jsonl> --prompt-file <fichero> --cases <fichero> --yes
   trazum plan <log.jsonl|dir> [opciones]
   trazum verify <plan.json> --against <nuevo.jsonl|dir> [opciones]
+  trazum history <dir-de-informes-guardados> [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -325,6 +326,21 @@ ${bold('OPCIONES DE plan')}
   consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
   gastado son totales separados en todas partes.
 
+${bold('OPCIONES DE history')}
+  --markdown-out <fichero>    Escribe además la serie como Markdown, para un
+                              resumen de CI o un comentario de pull request.
+  --json                      La historia como datos.
+
+  Toma un directorio de informes guardados — los documentos --json que
+  profile ya escribe — más los planes guardados que haya al lado, y construye
+  la serie que ninguna comparación por pares puede ver: una carga que sube un
+  poco cada período, una cuota de modelo creciendo desde una fecha, una cuota
+  de caché decayendo tan despacio que ningún informe semanal lo llamó
+  hallazgo, y la misma acción planificada una y otra vez sin que nadie la
+  ejecute. Derivada de informes guardados, nunca de registros re-parseados:
+  un año de JSON basta y los registros crudos pueden tirarse. Las formas se
+  nombran; nada se pronostica.
+
 ${bold('OPCIONES DE verify')}
   --against <log|dir>         El registro de uso posterior al que se somete el
                               plan. Obligatorio.
@@ -1454,6 +1470,39 @@ ${bold('EJEMPLOS')}
       `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
   },
 
+  history: {
+    noTarget: () =>
+      'Apunta esto a un directorio de informes guardados: trazum history informes/. Lee los documentos --json que escribe "trazum profile" (y los planes guardados que haya al lado) y construye la serie que ninguna comparación por pares puede ver.',
+    needsThree: (count) =>
+      `Una serie necesita al menos tres informes con fecha, y este directorio tiene ${count}. Dos informes son una comparación, y "trazum profile --against" ya la hace mejor.`,
+    heading: (periods, from, to) => `La larga distancia: ${periods} períodos, ${from} → ${to}`,
+    periodRow: (name, usd, calls, days) => `${name}  ${usd} · ${calls} llamadas · ${days} días`,
+    runLabel: (label, periods, sinceName, from, to) =>
+      `${label} lleva ${periods} períodos consecutivos subiendo desde ${sinceName}: ${from} → ${to}. Una forma, no un pronóstico.`,
+    runModel: (model, periods, sinceName, from, to) =>
+      `La cuota de ${model} en la factura lleva ${periods} períodos consecutivos subiendo desde ${sinceName}: ${from} → ${to}. Los totales pueden parecer planos mientras la mezcla se mueve debajo.`,
+    runCache: (periods, sinceName, from, to) =>
+      `La cuota de caché lleva ${periods} períodos consecutivos decayendo desde ${sinceName}: ${from} → ${to} — tan despacio que ningún informe suelto lo llamó hallazgo, que es exactamente para lo que existe una serie.`,
+    repeated: (kind, label, model, appearances, first, last) => {
+      const what =
+        kind === 'route'
+          ? `Enrutar ${label} (${model})`
+          : kind === 'batch'
+            ? `Agrupar en batch ${label} (${model})`
+            : kind === 'route+batch'
+              ? `Enrutar y agrupar ${label} (${model})`
+              : kind === 'fix-truncation'
+                ? `Arreglar los reintentos por truncado de ${label} (${model})`
+                : `Arreglar la caché de ${label} (${model})`;
+      const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
+      return `${what} se ha planificado ${appearances} veces${span} y sigue en el plan más reciente — una decisión que nadie está revisando.`;
+    },
+    undated: (name) => `${name} no lleva período, así que no está en ninguna línea de tiempo de arriba — nombrado, nunca absorbido en silencio.`,
+    unrecognized: (name) => `${name} no es ni un informe guardado ni un plan guardado, así que no está en ninguna serie de arriba.`,
+    footer: () =>
+      'Una serie nombra formas, no futuros. Veinte puntos hacen visible una tendencia; no hacen conocible el mes que viene — adónde van estas líneas después lo juzgas tú.',
+  },
+
   verify: {
     noTarget: () =>
       'Apunta esto a un plan guardado y a un registro posterior: trazum verify plan.json --against usage.jsonl. Dice, por acción, si el cambio llegó, no llegó o no se puede saber — y nunca menos de esos tres.',

package/src/i18n/types.ts

@@ -1072,6 +1072,28 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum history` — many reports over many periods, as one series.
+   *
+   * Shapes are named as consecutive movement, never a fitted line, and no
+   * series becomes a forecast: where the line goes next stays the reader's.
+   */
+  history: {
+    noTarget(): string;
+    /** Under three dated reports there is no series — only the comparison --against already does. */
+    needsThree(count: string): string;
+    heading(periods: string, from: string, to: string): string;
+    periodRow(name: string, usd: string, calls: string, days: string): string;
+    runLabel(label: string, periods: string, sinceName: string, from: string, to: string): string;
+    runModel(model: string, periods: string, sinceName: string, from: string, to: string): string;
+    runCache(periods: string, sinceName: string, from: string, to: string): string;
+    /** The same action in plan after plan: a decision nobody is executing. */
+    repeated(kind: PlanActionKind, label: string, model: string, appearances: string, first: string | null, last: string | null): string;
+    undated(name: string): string;
+    unrecognized(name: string): string;
+    footer(): string;
+  };
+
   /**
    * `trazum verify` — the plan held to the log that came after it.
    *

package/src/index.ts

@@ -11,7 +11,9 @@ import {
   cacheableMinimum,
   analyzeCachePrefix,
   billLevers,
+  buildHistory,
   buildPlan,
+  storedReportFrom,
   verifyPlan,
   cacheEconomics,
   cacheHitRate,
@@ -79,8 +81,10 @@ import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cac
 import { dayOf, formatGap, median, spanDays } from './time.js';
 import type {
   FleetSource,
+  HistoryRun,
   MeasuredUsage,
   PlanDocument,
+  StoredReport,
   VerifiedAction,
   BaselineBreach,
   BaselineChange,
@@ -479,6 +483,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source'],
   plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
   verify: ['against', 'gate', 'json', 'markdown-out', 'pricing', 'pricing-live'],
+  history: ['json', 'markdown-out'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2218,6 +2223,126 @@ function isoDate(): string {
  * metered API calls somebody was actually billed for — the bill exists wherever
  * Trazum happens to be running, so the host has no bearing on it.
  */
+/**
+ * `trazum history <dir>` — many reports over many periods, as one series.
+ *
+ * Derived from *stored* `--json` documents, never re-parsed logs: a team can
+ * keep a year of reports and throw the raw logs away, which is what the
+ * privacy story requires anyway. Shapes are named — a climb, a decay, the
+ * same action planned twice — and no series, however long, becomes a
+ * forecast.
+ */
+async function commandHistory(args: Args, t: CliMessages): Promise<void> {
+  const path = args.positional[0];
+  if (path === undefined) throw new Error(t.history.noTarget());
+  const target = await stat(path).catch(() => null);
+  if (!target?.isDirectory()) throw new Error(t.history.noTarget());
+
+  const entries = await readdir(path, { withFileTypes: true });
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => join(path, entry.name))
+    .sort((a, b) => a.localeCompare(b));
+
+  const reports: StoredReport[] = [];
+  const plans: (PlanDocument & { createdAt?: string })[] = [];
+  const unrecognized: string[] = [];
+  for (const file of files) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await readFile(file, 'utf8'));
+    } catch {
+      unrecognized.push(file);
+      continue;
+    }
+    const report = storedReportFrom(file, parsed);
+    if (report !== null) {
+      reports.push(report);
+      continue;
+    }
+    const maybePlan = parsed as PlanDocument & { createdAt?: string };
+    if (maybePlan?.schemaVersion === 1 && Array.isArray(maybePlan.actions)) {
+      plans.push(maybePlan);
+      continue;
+    }
+    unrecognized.push(file);
+  }
+
+  const history = buildHistory(reports, plans);
+  if (history.periods.length < 3) {
+    throw new Error(t.history.needsThree(String(history.periods.length)));
+  }
+
+  const stamped = { ...history, unrecognizedFiles: unrecognized };
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
+  const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
+
+  const runLine = (run: HistoryRun): string => {
+    if (run.kind === 'label-spend-climbing') {
+      const name = run.subject === UNLABELLED ? t.profile.unlabelled() : run.subject;
+      return t.history.runLabel(name, n(run.periods), run.sinceName, formatUsd(run.from), formatUsd(run.to));
+    }
+    if (run.kind === 'model-share-climbing') {
+      return t.history.runModel(run.subject, n(run.periods), run.sinceName, pct(run.from), pct(run.to));
+    }
+    return t.history.runCache(n(run.periods), run.sinceName, pct(run.from), pct(run.to));
+  };
+
+  const lines = (md: boolean): string[] => {
+    const out: string[] = [];
+    const first = history.periods[0]!;
+    const last = history.periods[history.periods.length - 1]!;
+    const heading = t.history.heading(n(history.periods.length), day(first.fromMs), day(last.toMs));
+    out.push(md ? `## ${heading}` : heading);
+    for (const period of history.periods) {
+      const row = t.history.periodRow(
+        period.name,
+        formatUsd(period.totalUsd),
+        n(period.calls),
+        ((period.toMs - period.fromMs) / 86_400_000).toFixed(1),
+      );
+      out.push(md ? `- ${row}` : `  ${row}`);
+    }
+    if (history.runs.length > 0) out.push('');
+    for (const run of history.runs) {
+      out.push(md ? `- ${runLine(run)}` : `  ! ${runLine(run)}`);
+    }
+    if (history.repeatedPlanActions.length > 0) out.push('');
+    for (const repeat of history.repeatedPlanActions) {
+      const name = repeat.label === UNLABELLED ? t.profile.unlabelled() : repeat.label;
+      const row = t.history.repeated(
+        repeat.kind,
+        name,
+        repeat.model,
+        n(repeat.appearances),
+        repeat.firstPlanned?.slice(0, 10) ?? null,
+        repeat.lastPlanned?.slice(0, 10) ?? null,
+      );
+      out.push(md ? `- ${row}` : `  ! ${row}`);
+    }
+    for (const name of history.undatedReports) {
+      out.push(md ? `- ${t.history.undated(name)}` : `  ${t.history.undated(name)}`);
+    }
+    for (const name of unrecognized) {
+      out.push(md ? `- ${t.history.unrecognized(name)}` : `  ${t.history.unrecognized(name)}`);
+    }
+    out.push('');
+    out.push(md ? `_${t.history.footer()}_` : `  ${t.history.footer()}`);
+    return out;
+  };
+
+  await writeMarkdown(args, () => lines(true).join('\n'));
+
+  if (boolFlag(args, 'json')) {
+    console.log(JSON.stringify(stamped, null, 2));
+    return;
+  }
+  const [head, ...rest] = lines(false);
+  console.log(c.bold(head!));
+  for (const row of rest) console.log(row === '' ? '' : wrap(row, 76, '    '));
+}
+
 /**
  * `trazum verify <plan.json> --against <newer.jsonl|dir>` — did it work?
  *
@@ -6302,6 +6427,9 @@ async function main(): Promise<void> {
     case 'verify':
       await commandVerify(args, pricing, t);
       break;
+    case 'history':
+      await commandHistory(args, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;