@trazum/cli 1.41.0 → 1.42.0

package/dist/store-fs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where the store actually lives.
+ *
+ * The core decides what a record is and when two are the same; this decides
+ * where the bytes go. Split that way for the reason every module here is:
+ * `@trazum/core` stays browser-safe, and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, one buffer per write.** A pull appends a single block and
+ * never rewrites what is already there. Two consequences worth stating: a
+ * crash during a write loses the tail of one block rather than a year of
+ * measurements, and two runs writing at once interleave whole blocks rather
+ * than half-lines. Compaction is a separate, explicit errand — `store
+ * --prune` — because collapsing a log is the one operation that destroys
+ * something, and it should never happen as a side effect of a pull.
+ *
+ * **A line that will not parse is kept, counted and skipped.** The store is a
+ * file a human may open, a backup may truncate and a merge may mangle. Losing
+ * the whole month because one line is broken would be the worst possible
+ * response; so would silently pretending the month is complete.
+ */
+import type { ResolvedStore, StoreRecord } from '@trazum/core';
+/** The directory name, relative to wherever the caller roots the store. */
+export declare const STORE_DIR = ".trazum/store";
+export interface StoreReadResult {
+    resolved: ResolvedStore;
+    /** Lines that would not parse: counted and named by file, never dropped quietly. */
+    unreadable: {
+        file: string;
+        line: number;
+    }[];
+    /** Files read, so an empty store can be told from an unread one. */
+    files: string[];
+}
+/**
+ * Reads every record in the store.
+ *
+ * Returns an empty result rather than throwing when the store does not exist:
+ * "you have not stored anything yet" is a state, not an error, and the caller
+ * says so in a sentence that names `trazum connect`.
+ */
+export declare function readStore(root: string): Promise<StoreReadResult>;
+/**
+ * Appends records, grouped into one write per month file.
+ *
+ * Nothing already on disk is read, rewritten or resolved here: convergence
+ * happens when the store is *read*, which is what keeps a write cheap enough
+ * to run on a schedule and impossible to corrupt by racing.
+ */
+export declare function appendRecords(root: string, records: readonly StoreRecord[]): Promise<number>;
+/**
+ * Rewrites the store with exactly the records given.
+ *
+ * The one operation that destroys something, so it is only ever reached from
+ * an explicit `--prune`. Each month file is written whole, and a month left
+ * with nothing is written empty rather than removed — a missing file and an
+ * empty one say different things to whoever looks next.
+ */
+export declare function rewriteStore(root: string, records: readonly StoreRecord[]): Promise<void>;
+//# sourceMappingURL=store-fs.d.ts.map

package/dist/store-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-fs.d.ts","sourceRoot":"","sources":["../src/store-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,2EAA2E;AAC3E,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAOzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,oFAAoF;IACpF,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,oEAAoE;IACpE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2CtE;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlG;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F"}

package/dist/store-fs.js

@@ -0,0 +1,145 @@
+/**
+ * Where the store actually lives.
+ *
+ * The core decides what a record is and when two are the same; this decides
+ * where the bytes go. Split that way for the reason every module here is:
+ * `@trazum/core` stays browser-safe, and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, one buffer per write.** A pull appends a single block and
+ * never rewrites what is already there. Two consequences worth stating: a
+ * crash during a write loses the tail of one block rather than a year of
+ * measurements, and two runs writing at once interleave whole blocks rather
+ * than half-lines. Compaction is a separate, explicit errand — `store
+ * --prune` — because collapsing a log is the one operation that destroys
+ * something, and it should never happen as a side effect of a pull.
+ *
+ * **A line that will not parse is kept, counted and skipped.** The store is a
+ * file a human may open, a backup may truncate and a merge may mangle. Losing
+ * the whole month because one line is broken would be the worst possible
+ * response; so would silently pretending the month is complete.
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveStore } from '@trazum/core';
+/** The directory name, relative to wherever the caller roots the store. */
+export const STORE_DIR = '.trazum/store';
+/** Records are filed by the UTC month their window starts in. */
+function monthOf(record) {
+    return new Date(record.fromMs).toISOString().slice(0, 7);
+}
+/**
+ * Reads every record in the store.
+ *
+ * Returns an empty result rather than throwing when the store does not exist:
+ * "you have not stored anything yet" is a state, not an error, and the caller
+ * says so in a sentence that names `trazum connect`.
+ */
+export async function readStore(root) {
+    const dir = join(root, STORE_DIR);
+    const records = [];
+    const unreadable = [];
+    const files = [];
+    let providers;
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        providers = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return { resolved: resolveStore([]), unreadable, files };
+    }
+    for (const provider of providers.sort()) {
+        const providerDir = join(dir, provider);
+        let months;
+        try {
+            months = (await readdir(providerDir)).filter((name) => name.endsWith('.jsonl')).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const month of months) {
+            const path = join(providerDir, month);
+            files.push(join(STORE_DIR, provider, month));
+            const text = await readFile(path, 'utf8');
+            for (const [index, line] of text.split('\n').entries()) {
+                if (line.trim() === '')
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed?.provider === 'string' && typeof parsed?.fromMs === 'number') {
+                        records.push(parsed);
+                    }
+                    else {
+                        unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+                    }
+                }
+                catch {
+                    unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+                }
+            }
+        }
+    }
+    return { resolved: resolveStore(records), unreadable, files };
+}
+/**
+ * Appends records, grouped into one write per month file.
+ *
+ * Nothing already on disk is read, rewritten or resolved here: convergence
+ * happens when the store is *read*, which is what keeps a write cheap enough
+ * to run on a schedule and impossible to corrupt by racing.
+ */
+export async function appendRecords(root, records) {
+    if (records.length === 0)
+        return 0;
+    const byFile = new Map();
+    for (const record of records) {
+        const key = join(record.provider, `${monthOf(record)}.jsonl`);
+        const list = byFile.get(key) ?? [];
+        list.push(record);
+        byFile.set(key, list);
+    }
+    for (const [relative, list] of byFile) {
+        const path = join(root, STORE_DIR, relative);
+        await mkdir(join(path, '..'), { recursive: true });
+        const block = `${list.map((record) => JSON.stringify(record)).join('\n')}\n`;
+        await writeFile(path, block, { flag: 'a', mode: 0o600 });
+    }
+    return records.length;
+}
+/**
+ * Rewrites the store with exactly the records given.
+ *
+ * The one operation that destroys something, so it is only ever reached from
+ * an explicit `--prune`. Each month file is written whole, and a month left
+ * with nothing is written empty rather than removed — a missing file and an
+ * empty one say different things to whoever looks next.
+ */
+export async function rewriteStore(root, records) {
+    const dir = join(root, STORE_DIR);
+    const existing = new Set();
+    try {
+        for (const provider of await readdir(dir)) {
+            for (const month of await readdir(join(dir, provider)).catch(() => [])) {
+                if (month.endsWith('.jsonl'))
+                    existing.add(join(provider, month));
+            }
+        }
+    }
+    catch {
+        // Nothing stored yet: the writes below create what is needed.
+    }
+    const byFile = new Map();
+    for (const record of records) {
+        const key = join(record.provider, `${monthOf(record)}.jsonl`);
+        const list = byFile.get(key) ?? [];
+        list.push(record);
+        byFile.set(key, list);
+    }
+    for (const relative of new Set([...existing, ...byFile.keys()])) {
+        const list = byFile.get(relative) ?? [];
+        const path = join(dir, relative);
+        await mkdir(join(path, '..'), { recursive: true });
+        const block = list.length === 0 ? '' : `${list.map((r) => JSON.stringify(r)).join('\n')}\n`;
+        await writeFile(path, block, { mode: 0o600 });
+    }
+}
+//# sourceMappingURL=store-fs.js.map

package/dist/store-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-fs.js","sourceRoot":"","sources":["../src/store-fs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.41.0",
+  "version": "1.42.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.41.0"
+    "@trazum/core": "1.42.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -43,6 +43,7 @@ ${bold('USAGE')}
   trazum verify <plan.json> --against <newer.jsonl|dir> [options]
   trazum history <dir-of-stored-reports> [options]
   trazum connect <anthropic|openai> [options]
+  trazum store [--prune] [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -320,6 +321,25 @@ ${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 store')}
+  --prune                     Drop measurements older than the retention
+                              policy, and compact the append log to what the
+                              store already resolves to. Says what went.
+  --keep <n>d                 Retention for this run, when the config has none.
+  --dry-run                   With --prune: say what would go, and delete
+                              nothing.
+  --json                      The inventory as data.
+
+  Says what the local store holds: how many measurements, over what span, per
+  provider, and what a prune would take. The store keeps aggregates and
+  billing fields — never prompt text, never completion text, never a
+  credential — so it is a file a team can back up without a privacy review.
+
+  Pruning is the one operation here that destroys something, so it refuses to
+  run without a retention policy: set "store": {"keepDays": 90} in the config
+  or pass --keep. Deleting measurements on a policy nobody wrote down is not a
+  default anybody should get by accident.
+
 ${bold('OPTIONS FOR connect')}
   --since <when>              The window to pull. A UTC day, an ISO timestamp,
   --until <when>              a relative window (7d, 24h) or "now". Defaults to
@@ -330,6 +350,9 @@ ${bold('OPTIONS FOR connect')}
   --payload <file>            Price a usage payload you already have, instead of
                               pulling one. No credential, no network — the same
                               arithmetic on the same shape.
+  --store                     Keep what was pulled in the local store, so the
+                              next run does not download it again and "trazum
+                              history --store" has a series.
   -o, --out <file>            Save the priced report as JSON.
   --markdown-out <file>       Also write it as Markdown, for a CI job summary.
   --json                      The report as data.
@@ -350,6 +373,12 @@ ${bold('OPTIONS FOR connect')}
   that quietly describes less traffic than you asked about.
 
 ${bold('OPTIONS FOR history')}
+  --store                     Build the series from the local store instead of
+                              a directory of stored reports. Bucketed sources
+                              carry no label, so the label series is absent and
+                              said to be — the model-share and cache-share
+                              series are what a series exists for, and both
+                              work.
   --markdown-out <file>       Also write the series as Markdown, for a CI job
                               summary or a pull request comment.
   --json                      The history as data.
@@ -1477,6 +1506,37 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  store: {
+    appended: (count, dir) => `Kept ${count} measurements in ${dir}.`,
+    empty: (dir) =>
+      `The store at ${dir} is empty. Fill it with "trazum connect <provider> --store" — that is a state, not an error.`,
+    heading: (records, usd, from, to) =>
+      `The store: ${records} measurements · ${usd} · ${from} → ${to}`,
+    providerRow: (provider, records, span, models) =>
+      `${provider}  ${records} measurements · ${span} · ${models} models`,
+    holds: (files) =>
+      `Held in ${files} files: token counts, billed dollars and the account's own workspace and key identifiers. Never prompt text, never completion text, never a credential — this is a file you can back up without a privacy review.`,
+    possiblyDouble: (count) =>
+      `${count} records could not be told apart from another — a window of no length, or a record naming no model. They are kept whole rather than merged, so a total built on them may count the same spend twice. Saying so beats a smaller number nobody can check.`,
+    unknownVersion: (count) =>
+      `${count} records come from a newer schema than this version knows, so they are kept and left out of the figures above rather than guessed at. Upgrade to read them.`,
+    unreadable: (file, line) =>
+      `${file} line ${line} would not parse, so it is not in the figures above. The rest of the file was read — one broken line must not lose a month.`,
+    retention: (days) => `Retention: ${days} days, from "store.keepDays". Run "trazum store --prune" to apply it.`,
+    noRetention: () =>
+      'No retention policy is configured, so nothing is ever deleted on its own. Set "store": {"keepDays": 90} when you want one.',
+    pruneNeedsPolicy: () =>
+      'Pruning needs a retention policy: set "store": {"keepDays": 90} in trazum.config.json, or pass --keep 90d for this run. Deleting measurements on a policy nobody wrote down is not a default you should get by accident.',
+    pruneDryRun: (count, days, span, usd) =>
+      span === null
+        ? `Nothing is older than ${days} days, so a prune would delete nothing.`
+        : `A prune would delete ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. Nothing was deleted — this was --dry-run.`,
+    pruned: (count, days, span, usd, kept) =>
+      span === null
+        ? `Nothing was older than ${days} days. ${kept} measurements kept, and the append log compacted.`
+        : `Deleted ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. ${kept} kept, and the append log compacted to what the store already resolved to.`,
+  },
+
   connect: {
     noTarget: (providers) =>
       `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored — add --dry-run to see exactly what would be called and which variable it would be read from.`,
@@ -1514,7 +1574,8 @@ ${bold('EXAMPLES')}
     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`,
+    periodRow: (name, usd, calls, days) =>
+      calls === null ? `${name}  ${usd} · ${days} 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) =>
@@ -1535,6 +1596,8 @@ ${bold('EXAMPLES')}
       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.`;
     },
+    storeNoLabels: () =>
+      'This series comes from the store, and a usage API groups by model and workspace rather than by workload — so there is no label series here at all. Absent, not empty: nothing above says a workload did or did not move.',
     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: () =>

package/src/i18n/es.ts

@@ -30,6 +30,7 @@ ${bold('USO')}
   trazum verify <plan.json> --against <nuevo.jsonl|dir> [opciones]
   trazum history <dir-de-informes-guardados> [opciones]
   trazum connect <anthropic|openai> [opciones]
+  trazum store [--prune] [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -327,6 +328,26 @@ ${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 store')}
+  --prune                     Borra las mediciones más antiguas que la política
+                              de retención y compacta el log a lo que el
+                              almacén ya resuelve. Dice qué se fue.
+  --keep <n>d                 Retención para esta ejecución, si la config no
+                              tiene ninguna.
+  --dry-run                   Con --prune: dice qué se iría y no borra nada.
+  --json                      El inventario como datos.
+
+  Dice qué guarda el almacén local: cuántas mediciones, sobre qué período, por
+  proveedor, y qué se llevaría una poda. El almacén guarda agregados y campos
+  de facturación — nunca texto de prompt, nunca texto de respuesta, nunca una
+  credencial — así que es un fichero que un equipo puede respaldar sin una
+  revisión de privacidad.
+
+  La poda es la única operación de aquí que destruye algo, así que se niega a
+  correr sin política de retención: pon "store": {"keepDays": 90} en la config
+  o pasa --keep. Borrar mediciones con una política que nadie escribió no es un
+  valor por defecto que nadie deba recibir por accidente.
+
 ${bold('OPCIONES DE connect')}
   --since <cuándo>            La ventana que se descarga. Un día UTC, una marca
   --until <cuándo>            ISO, una ventana relativa (7d, 24h) o "now". Por
@@ -337,6 +358,9 @@ ${bold('OPCIONES DE connect')}
   --payload <fichero>         Tasa un payload de uso que ya tengas, en vez de
                               descargar uno. Sin credencial y sin red — la misma
                               aritmética sobre la misma forma.
+  --store                     Guarda lo descargado en el almacén local, para que
+                              la próxima vez no haya que bajarlo otra vez y
+                              "trazum history --store" tenga una serie.
   -o, --out <fichero>         Guarda el informe tasado como JSON.
   --markdown-out <fichero>    Lo escribe además como Markdown, para CI.
   --json                      El informe como datos.
@@ -358,6 +382,12 @@ ${bold('OPCIONES DE connect')}
   que describe en silencio menos tráfico del que pediste.
 
 ${bold('OPCIONES DE history')}
+  --store                     Construye la serie desde el almacén local en vez
+                              de un directorio de informes guardados. Las
+                              fuentes agregadas no llevan label, así que la
+                              serie por label está ausente y se dice — las de
+                              cuota de modelo y de caché son para lo que existe
+                              una serie, y funcionan enteras.
   --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.
@@ -1501,6 +1531,37 @@ ${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.`,
   },
 
+  store: {
+    appended: (count, dir) => `Guardadas ${count} mediciones en ${dir}.`,
+    empty: (dir) =>
+      `El almacén de ${dir} está vacío. Llénalo con "trazum connect <proveedor> --store" — eso es un estado, no un error.`,
+    heading: (records, usd, from, to) =>
+      `El almacén: ${records} mediciones · ${usd} · ${from} → ${to}`,
+    providerRow: (provider, records, span, models) =>
+      `${provider}  ${records} mediciones · ${span} · ${models} modelos`,
+    holds: (files) =>
+      `Guardado en ${files} ficheros: recuentos de tokens, dólares facturados y los identificadores de workspace y clave de la propia cuenta. Nunca texto de prompt, nunca texto de respuesta, nunca una credencial — esto es un fichero que puedes respaldar sin una revisión de privacidad.`,
+    possiblyDouble: (count) =>
+      `${count} registros no se pudieron distinguir de otro — una ventana de longitud cero, o un registro que no nombra modelo. Se guardan enteros en vez de fundirse, así que un total construido sobre ellos puede contar el mismo gasto dos veces. Decirlo es mejor que un número más pequeño que nadie puede comprobar.`,
+    unknownVersion: (count) =>
+      `${count} registros vienen de un esquema más nuevo del que esta versión conoce, así que se conservan y quedan fuera de las cifras de arriba en vez de adivinarse. Actualiza para leerlos.`,
+    unreadable: (file, line) =>
+      `${file} línea ${line} no se pudo parsear, así que no está en las cifras de arriba. El resto del fichero sí se leyó — una línea rota no puede costar un mes.`,
+    retention: (days) => `Retención: ${days} días, de "store.keepDays". Ejecuta "trazum store --prune" para aplicarla.`,
+    noRetention: () =>
+      'No hay política de retención configurada, así que nunca se borra nada por su cuenta. Pon "store": {"keepDays": 90} cuando quieras una.',
+    pruneNeedsPolicy: () =>
+      'Podar necesita una política de retención: pon "store": {"keepDays": 90} en trazum.config.json, o pasa --keep 90d para esta ejecución. Borrar mediciones con una política que nadie escribió no es un valor por defecto que debas recibir por accidente.',
+    pruneDryRun: (count, days, span, usd) =>
+      span === null
+        ? `Nada es más antiguo que ${days} días, así que una poda no borraría nada.`
+        : `Una poda borraría ${count} mediciones de más de ${days} días, que cubren ${span} y ${usd} de gasto medido. No se borró nada — esto era --dry-run.`,
+    pruned: (count, days, span, usd, kept) =>
+      span === null
+        ? `Nada era más antiguo que ${days} días. ${kept} mediciones conservadas, y el log compactado.`
+        : `Borradas ${count} mediciones de más de ${days} días, que cubren ${span} y ${usd} de gasto medido. ${kept} conservadas, y el log compactado a lo que el almacén ya resolvía.`,
+  },
+
   connect: {
     noTarget: (providers) =>
       `Nombra un proveedor del que leer tu factura: trazum connect anthropic. Disponibles: ${providers}. La credencial sale del entorno y nunca se guarda — añade --dry-run para ver exactamente qué se llamaría y de qué variable saldría.`,
@@ -1538,7 +1599,8 @@ ${bold('EJEMPLOS')}
     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`,
+    periodRow: (name, usd, calls, days) =>
+      calls === null ? `${name}  ${usd} · ${days} días` : `${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) =>
@@ -1559,6 +1621,8 @@ ${bold('EJEMPLOS')}
       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.`;
     },
+    storeNoLabels: () =>
+      'Esta serie viene del almacén, y una API de uso agrupa por modelo y workspace, no por carga de trabajo — así que aquí no hay serie por label en absoluto. Ausente, no vacía: nada de lo de arriba dice que una carga se moviera o dejara de moverse.',
     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: () =>

package/src/i18n/types.ts

@@ -1072,6 +1072,33 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum store` — the measurements kept on disk.
+   *
+   * The one part of this product that deletes something, so its copy is
+   * written to make that visible: what is held, what a prune would take, and
+   * a refusal when no retention policy exists to prune against.
+   */
+  store: {
+    /** Records appended by a pull that asked to keep them. */
+    appended(count: string, dir: string): string;
+    empty(dir: string): string;
+    heading(records: string, usd: string, from: string, to: string): string;
+    providerRow(provider: string, records: string, span: string, models: string): string;
+    /** What the store holds — and what it never holds. */
+    holds(files: string): string;
+    /** Records the store could not tell apart, kept whole rather than merged. */
+    possiblyDouble(count: string): string;
+    unknownVersion(count: string): string;
+    unreadable(file: string, line: string): string;
+    retention(days: string): string;
+    noRetention(): string;
+    /** Deleting on a policy nobody wrote down is refused, never defaulted. */
+    pruneNeedsPolicy(): string;
+    pruneDryRun(count: string, days: string, span: string | null, usd: string): string;
+    pruned(count: string, days: string, span: string | null, usd: string, kept: string): string;
+  };
+
   /**
    * `trazum connect` — the bill, read from the provider.
    *
@@ -1115,12 +1142,15 @@ export interface CliMessages {
     /** 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;
+    /** `calls` is null on a source that serves no request count. */
+    periodRow(name: string, usd: string, calls: string | null, 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;
+    /** A store source carries no labels, so the label series is absent, not empty. */
+    storeNoLabels(): string;
     undated(name: string): string;
     unrecognized(name: string): string;
     footer(): string;