@trazum/cli 1.48.0 → 1.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.48.0",
+  "version": "1.49.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.48.0"
+    "@trazum/core": "1.49.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -1666,7 +1666,9 @@ ${bold('EXAMPLES')}
     nothingMeasured: (dir) =>
       `Nothing is measured yet (the store at ${dir} is empty), so the budget half of every answer will say so. The cost half still answers from the catalogue: offline is a mode, not a failure.`,
     noBudget: () =>
-      'No spend.maxUsd is configured, so "is there budget left" has no subject and every answer says so rather than guessing one.',
+      'No spend.monthlyUsd is configured, so "is there budget left" has no subject and every answer says so rather than guessing one. spend.maxUsd is deliberately not read here: it gates whatever period a log covers, and reading it as a monthly limit is how two surfaces of this tool come to disagree.',
+    partialCoverage: (measuredDays, elapsedDays, period) =>
+      `Only ${measuredDays} of the ${elapsedDays} elapsed days of ${period} carry any measurement, so the consumed figure is a floor on the period rather than the period. Pull the missing days with trazum connect before treating what is left as headroom.`,
     badPort: (value) => `"${value}" is not a port. Give a whole number from 0 to 65535, or use --socket.`,
   },
 
@@ -1742,6 +1744,27 @@ ${bold('EXAMPLES')}
       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.`,
+    budgetHeading: (period) => `Budget for ${period}`,
+    budgetStanding: (consumed, limit, share, measuredDays, periodDays) =>
+      `${consumed} of ${limit} (${share}), measured over ${measuredDays} of the month's ${periodDays} days.`,
+    budgetShape: (shape, elapsedPct, coverage) =>
+      shape === 'ahead'
+        ? `The money is going faster than the calendar: ${elapsedPct}% of the month has elapsed.`
+        : shape === 'behind'
+          ? `The money is going slower than the calendar: ${elapsedPct}% of the month has elapsed.`
+          : shape === 'on-pace'
+            ? `Tracking the calendar: ${elapsedPct}% of the month has elapsed.`
+            : coverage === 'partial'
+              ? 'Whether that is fast or slow for the month cannot be told from a floor: the unmeasured days spent something, and only an overrun would be unarguable.'
+              : 'There is nothing to compare the spend against yet.',
+    budgetNeverForecast: () =>
+      'That is a shape, not a forecast. Where this goes next depends on what you do next, and no arithmetic here knows that.',
+    budgetNothingMeasured: (elapsedDays) =>
+      `Nothing has been measured this month, across ${elapsedDays} elapsed ${elapsedDays === 1 ? 'day' : 'days'}. That is not a budget under control — it is a budget nobody is watching. Run trazum connect to pull what the provider has.`,
+    budgetPartial: (measuredDays, elapsedDays, days) =>
+      `Only ${measuredDays} of ${elapsedDays} elapsed days carry any measurement, so the figure below is a floor on the month rather than the month. Missing: ${days}.`,
+    budgetScopesUnmeasured: (count) =>
+      `${count} budgeted ${count === 1 ? 'scope' : 'scopes'} (per label or per service) cannot be answered from the store: a store record carries a provider and a model, not a workload label. Gate those with trazum profile against a per-call log.`,
   },
 
   connect: {

package/src/i18n/es.ts

@@ -1696,7 +1696,9 @@ ${bold('EJEMPLOS')}
     nothingMeasured: (dir) =>
       `Todavía no hay nada medido (el almacén de ${dir} está vacío), así que la mitad de presupuesto de cada respuesta lo dirá. La mitad del coste sigue respondiendo desde el catálogo: sin conexión es un modo, no un fallo.`,
     noBudget: () =>
-      'No hay spend.maxUsd configurado, así que "queda presupuesto" no tiene sujeto y cada respuesta lo dice en vez de inventarse uno.',
+      'No hay spend.monthlyUsd configurado, así que "queda presupuesto" no tiene sujeto y cada respuesta lo dice en vez de inventarse uno. spend.maxUsd no se lee aquí a propósito: ese controla el periodo que cubra un registro, y leerlo como límite mensual es justo como dos superficies de esta herramienta acaban en desacuerdo.',
+    partialCoverage: (measuredDays, elapsedDays, period) =>
+      `Solo ${measuredDays} de los ${elapsedDays} días transcurridos de ${period} tienen alguna medición, así que la cifra consumida es un suelo del periodo y no el periodo. Descarga los días que faltan con trazum connect antes de tratar lo que queda como margen.`,
     badPort: (value) => `"${value}" no es un puerto. Da un número entero de 0 a 65535, o usa --socket.`,
   },
 
@@ -1772,6 +1774,27 @@ ${bold('EJEMPLOS')}
       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.`,
+    budgetHeading: (period) => `Presupuesto de ${period}`,
+    budgetStanding: (consumed, limit, share, measuredDays, periodDays) =>
+      `${consumed} de ${limit} (${share}), medido sobre ${measuredDays} de los ${periodDays} días del mes.`,
+    budgetShape: (shape, elapsedPct, coverage) =>
+      shape === 'ahead'
+        ? `El dinero va más rápido que el calendario: ha transcurrido el ${elapsedPct}% del mes.`
+        : shape === 'behind'
+          ? `El dinero va más lento que el calendario: ha transcurrido el ${elapsedPct}% del mes.`
+          : shape === 'on-pace'
+            ? `Al ritmo del calendario: ha transcurrido el ${elapsedPct}% del mes.`
+            : coverage === 'partial'
+              ? 'Si eso es rápido o lento para el mes no se puede saber desde un suelo: los días sin medir gastaron algo, y solo un exceso sería incontestable.'
+              : 'Todavía no hay nada con lo que comparar el gasto.',
+    budgetNeverForecast: () =>
+      'Eso es una forma, no un pronóstico. A dónde va esto después depende de lo que hagas después, y ninguna aritmética de aquí lo sabe.',
+    budgetNothingMeasured: (elapsedDays) =>
+      `No se ha medido nada este mes, en ${elapsedDays} ${elapsedDays === 1 ? 'día transcurrido' : 'días transcurridos'}. Eso no es un presupuesto bajo control — es un presupuesto que nadie está mirando. Ejecuta trazum connect para descargar lo que tenga el proveedor.`,
+    budgetPartial: (measuredDays, elapsedDays, days) =>
+      `Solo ${measuredDays} de ${elapsedDays} días transcurridos tienen alguna medición, así que la cifra de abajo es un suelo del mes y no el mes. Faltan: ${days}.`,
+    budgetScopesUnmeasured: (count) =>
+      `${count} ${count === 1 ? 'ámbito presupuestado' : 'ámbitos presupuestados'} (por etiqueta o por servicio) no se pueden responder desde el almacén: un registro del almacén lleva un proveedor y un modelo, no una etiqueta de flujo. Contrólalos con trazum profile contra un registro por llamada.`,
   },
 
   connect: {

package/src/i18n/types.ts

@@ -1151,6 +1151,12 @@ export interface CliMessages {
     measuredFrom(usd: string): string;
     nothingMeasured(dir: string): string;
     noBudget(): string;
+    /**
+     * The period is only partly measured — said out loud, because a position
+     * standing on three days out of thirty must not read as a comfortable
+     * ninety per cent remaining.
+     */
+    partialCoverage(measuredDays: number, elapsedDays: number, period: string): string;
     badPort(value: string): string;
   };
 
@@ -1205,6 +1211,15 @@ export interface CliMessages {
     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;
+    /** The live budget — the one number `serve` and the MCP guard also read. */
+    budgetHeading(period: string): string;
+    budgetStanding(consumed: string, limit: string, share: string, measuredDays: string, periodDays: string): string;
+    /** The shape of the burn, named. Never a date — see `budgetNeverForecast`. */
+    budgetShape(shape: string, elapsedPct: number, coverage: string): string;
+    budgetNeverForecast(): string;
+    budgetNothingMeasured(elapsedDays: number): string;
+    budgetPartial(measuredDays: number, elapsedDays: number, days: string): string;
+    budgetScopesUnmeasured(count: number): string;
   };
 
   /**

package/src/index.ts

@@ -35,6 +35,7 @@ import {
   computeSavings,
   countTokensAnthropic,
   DEFAULT_USAGE,
+  budgetPositions,
   detectFromSource,
   matchLocale,
   parsePlanDocument,
@@ -127,6 +128,7 @@ import type {
   UsageProfile,
 } from '@trazum/core';
 import type {
+  BudgetReport,
   UsageProfileReport,
   WaiverUse,
   InitDecline,
@@ -2747,41 +2749,39 @@ async function commandServe(
   t: CliMessages,
 ): Promise<void> {
   const root = process.cwd();
-  const limitUsd = config.spend?.maxUsd;
 
   const { resolved } = await readStore(root);
-  const measured = resolved.records.length > 0;
+
   /**
-   * The window the measurement covers, carried into every answer.
+   * The live budget, from `budgetPositions` — the same number `store` prints
+   * and the same one the MCP guard consults.
    *
-   * The position is read once at start, so a caller has to be able to see how
-   * old it is. A null window here would let a figure from last month read as
-   * current, which is the staleness this endpoint is otherwise honest about.
+   * **This used to read `spend.maxUsd` against the whole store**, which is a
+   * per-log gate compared against however much history the store happened to
+   * hold. A year of records against a monthly limit reported as a budget
+   * position, with a straight face and no way for a caller to tell. Same
+   * units, different denominators, and the two surfaces disagreed by exactly
+   * as much history as the machine had. `spend.monthlyUsd` is the key for a
+   * calendar month and nothing infers one key from the other: a repository
+   * with a per-log gate and no monthly budget has no monthly position, and
+   * this says so rather than picking a number that is the right shape.
    */
-  const window = measured
-    ? {
-        fromMs: Math.min(...resolved.records.map((record) => record.fromMs)),
-        toMs: Math.max(...resolved.records.map((record) => record.toMs)),
-      }
-    : null;
-  const report = bucketedProfile(
-    {
-      provider: 'store',
-      granularity: 'bucketed',
-      buckets: bucketsFromRecords(resolved.records),
-      window,
-      gaps: [],
-      unavailable: [],
-    },
-    { catalogue: pricing },
-  );
+  const budget = budgetPositions(resolved.records, config.spend, { catalogue: pricing });
+  const standing = budget.positions[0] ?? null;
+  const limitUsd = config.spend?.monthlyUsd;
+  const measured = standing !== null && standing.coverage !== 'none';
 
   const server = buildServer({
     catalogue: pricing,
     position: () => ({
-      consumedUsd: measured ? report.total.totalUsd : undefined,
+      // Nothing measured inside the period is `undefined`, never zero: the
+      // endpoint's `cannot-tell` exists for exactly this, and a $0 consumed
+      // would be the healthiest-looking budget a dead store can produce.
+      consumedUsd: measured ? standing.consumedUsd : undefined,
       limitUsd,
-      window: report.span,
+      // The period, not the store's span. A caller judging staleness needs to
+      // know which month the figure is about.
+      window: standing === null ? null : { fromMs: standing.period.fromMs, toMs: standing.period.toMs },
     }),
   });
 
@@ -2796,8 +2796,13 @@ async function commandServe(
   console.log(c.bold(t.serve.listening(where)));
   console.log(`  ${c.dim(wrap(t.serve.loopbackOnly(), 74, '    '))}`);
   console.log(
-    `  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(report.total.totalUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`,
+    `  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(standing.consumedUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`,
   );
+  if (standing !== null && standing.coverage === 'partial') {
+    console.log(
+      `  ${c.yellow(wrap(t.serve.partialCoverage(standing.measuredDays, standing.elapsedDays, standing.period.id), 74, '    '))}`,
+    );
+  }
   if (limitUsd === undefined) {
     console.log(`  ${c.dim(wrap(t.serve.noBudget(), 74, '    '))}`);
   }
@@ -3164,6 +3169,72 @@ async function commandStore(
   console.log(
     `  ${c.dim(wrap(keepDays === undefined ? t.store.noRetention() : t.store.retention(String(keepDays)), 74, '    '))}`,
   );
+
+  /**
+   * The live budget, printed here because this is where the measurement lives.
+   *
+   * The same call `serve` makes and the same call the MCP guard makes, so the
+   * three cannot disagree about how much of the month is gone — which is the
+   * whole point of the number existing in one place.
+   */
+  renderBudget(budgetPositions(resolved.records, config.spend, { catalogue: pricing }), t, n);
+}
+
+/**
+ * One budget standing, rendered.
+ *
+ * Coverage before the money, deliberately. A reader who sees "$61 of $100"
+ * first has already formed a view by the time they reach "over three of
+ * nineteen elapsed days", and the second sentence has to undo the first.
+ */
+function renderBudget(report: BudgetReport, t: CliMessages, n: (value: number) => string): void {
+  const standing = report.positions[0];
+  if (standing === undefined) {
+    if (report.unmeasuredScopes.length > 0) {
+      console.log();
+      console.log(
+        `  ${c.dim(wrap(t.store.budgetScopesUnmeasured(report.unmeasuredScopes.length), 74, '    '))}`,
+      );
+    }
+    return;
+  }
+
+  console.log();
+  console.log(c.bold(t.store.budgetHeading(standing.period.id)));
+
+  if (standing.coverage === 'none') {
+    // Nothing measured is never rendered as nothing spent. A dead store and a
+    // quiet month produce the same zero, and only one of them is good news.
+    console.log(`  ${c.red(wrap(t.store.budgetNothingMeasured(standing.elapsedDays), 74, '    '))}`);
+    return;
+  }
+  if (standing.coverage === 'partial') {
+    console.log(
+      `  ${c.yellow(wrap(t.store.budgetPartial(standing.measuredDays, standing.elapsedDays, standing.unmeasuredDays.join(', ')), 74, '    '))}`,
+    );
+  }
+
+  const share = standing.burn.consumedShare;
+  console.log(
+    `  ${t.store.budgetStanding(
+      formatUsd(standing.consumedUsd),
+      formatUsd(standing.limitUsd),
+      share === null ? '—' : `${Math.round(share * 100)}%`,
+      n(standing.measuredDays),
+      n(standing.period.days),
+    )}`,
+  );
+  const line = t.store.budgetShape(
+    standing.burn.shape,
+    Math.round(standing.burn.elapsedShare * 100),
+    standing.coverage,
+  );
+  console.log(`  ${standing.verdict === 'over' ? c.red(line) : c.dim(wrap(line, 74, '    '))}`);
+  // Only where there is a shape to disclaim. "That is a shape, not a forecast"
+  // under "nothing to compare against" is a disclaimer about nothing.
+  if (standing.burn.shape !== 'cannot-tell') {
+    console.log(`  ${c.dim(wrap(t.store.budgetNeverForecast(), 74, '    '))}`);
+  }
 }
 
 /**