@trazum/cli 1.29.0 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.29.0",
+  "version": "1.30.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.29.0"
+    "@trazum/core": "1.30.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -1173,6 +1173,21 @@ ${bold('EXAMPLES')}
       `The 95th percentile is ${ratio}x the median there: most conversations are cheap and a few are not, which is a tail a quota can catch. Where median and p95 sit close together the workload is simply expensive and there is no tail to hunt.`,
     sessionSpendOnly: (sessions, max) =>
       `${sessions} ${sessions === '1' ? 'conversation' : 'conversations'} in this log; the most expensive cost ${max}. Too few per workload for a percentile — a maximum is a fact at any count, and it is the figure --max-session-usd judges.`,
+    maxGrowthCoverageLost: (fields, was, now) =>
+      `FAILED — this log stopped recording ${fields} (${was} of records before, ${now} now), so the comparison cannot be made. That is not a pass: a bill whose growth nobody could measure is not a bill that stayed flat, and every finding that needed the field went quiet for a reason that has nothing to do with spend.`,
+    coverageField: (field) =>
+      ({ label: 'label', session: 'session', ts: 'timestamp', stopReason: 'stop reason' })[field] ?? field,
+    coverageSilenced: (field) =>
+      ({
+        label: 'Gone quiet with it: per-workload spend, the drill-down, and levers that describe a decision rather than a mixture.',
+        session: 'Gone quiet with it: conversation growth, per-conversation cost, repeated turns, truncation retries and the cache-TTL fit.',
+        ts: 'Gone quiet with it: the period, the per-day and per-hour shape, the model mix drift, and the cache-TTL question entirely.',
+        stopReason: 'Gone quiet with it: answers cut off at max_tokens, and the retries billed after them.',
+      })[field] ?? '',
+    coverageDrift: (field, was, now) =>
+      `Coverage moved: ${field} was on ${was} of records and is now on ${now}.`,
+    coverageDriftWhy: () =>
+      'A field the log stopped recording is not a finding that got fixed — every finding that needed it has gone quiet for a reason that has nothing to do with the bill. Reported from a 20-point move in either direction; a field that appeared means this report can see what the previous one could not.',
     againstOverlap: (from, to) =>
       `These two logs both cover ${from} → ${to}, so some of the same calls sit on both sides of this subtraction and part of the change is the same money counted twice. Compare periods that do not overlap — or window both logs with --since/--until.`,
     windowLine: (since, until) =>

package/src/i18n/es.ts

@@ -1188,6 +1188,21 @@ ${bold('EJEMPLOS')}
       `El percentil 95 es ${ratio}x la mediana ahí: casi todas las conversaciones son baratas y unas pocas no, y esa es una cola que una cuota puede cazar. Cuando mediana y p95 quedan cerca, la carga es cara sin más y no hay cola que perseguir.`,
     sessionSpendOnly: (sessions, max) =>
       `${sessions} ${sessions === '1' ? 'conversación' : 'conversaciones'} en este registro; la más cara costó ${max}. Demasiado pocas por carga para un percentil — un máximo es un hecho con cualquier recuento, y es la cifra que juzga --max-session-usd.`,
+    maxGrowthCoverageLost: (fields, was, now) =>
+      `FALLÓ — este registro dejó de grabar ${fields} (${was} de los registros antes, ${now} ahora), así que la comparación no se puede hacer. Eso no es un aprobado: una factura cuyo crecimiento nadie pudo medir no es una factura que se mantuvo plana, y todo hallazgo que necesitaba ese campo se calló por un motivo que nada tiene que ver con el gasto.`,
+    coverageField: (field) =>
+      ({ label: 'etiqueta', session: 'sesión', ts: 'marca de tiempo', stopReason: 'razón de parada' })[field] ?? field,
+    coverageSilenced: (field) =>
+      ({
+        label: 'Se callaron con él: el gasto por carga, el desglose y unas palancas que describan una decisión y no una mezcla.',
+        session: 'Se callaron con él: el crecimiento de conversación, el coste por conversación, los turnos repetidos, los reintentos por truncado y el ajuste del TTL de caché.',
+        ts: 'Se callaron con él: el periodo, la forma por día y por hora, la deriva de mezcla de modelos y la pregunta del TTL de caché por completo.',
+        stopReason: 'Se callaron con él: las respuestas cortadas en max_tokens y los reintentos facturados después.',
+      })[field] ?? '',
+    coverageDrift: (field, was, now) =>
+      `La cobertura se movió: ${field} estaba en el ${was} de los registros y ahora está en el ${now}.`,
+    coverageDriftWhy: () =>
+      'Un campo que el registro dejó de grabar no es un hallazgo arreglado — todo hallazgo que lo necesitaba se ha callado por un motivo que nada tiene que ver con la factura. Se informa a partir de 20 puntos de movimiento en cualquier dirección; un campo que aparece significa que este informe ve lo que el anterior no podía.',
     againstOverlap: (from, to) =>
       `Estos dos registros cubren ambos ${from} → ${to}, así que algunas de las mismas llamadas están a los dos lados de esta resta y parte del cambio es el mismo dinero contado dos veces. Compara periodos que no se solapen — o acota ambos registros con --since/--until.`,
     windowLine: (since, until) =>

package/src/i18n/types.ts

@@ -769,6 +769,26 @@ export interface CliMessages {
      * money on both sides of the subtraction. Only decidable when both logs
      * carry a clock; unknown stays silent rather than reassuring.
      */
+    /**
+     * What the comparison stopped being able to see. Dollars cannot tell a
+     * fixed finding from a field the log stopped recording; only coverage can,
+     * so the copy names the threshold and states the distinction.
+     */
+    /**
+     * The comparison gate's refusal: the current log stopped recording a field
+     * the previous one carried, so "did not grow" is a claim nobody could
+     * check. "Not measured" is not "did not grow", as everywhere here.
+     */
+    maxGrowthCoverageLost(fields: string, was: string, now: string): string;
+    coverageField(field: string): string;
+    /**
+     * Which findings a collapsed field took with it. Named rather than left as
+     * "some findings": a reader deciding whether to trust this report needs to
+     * know exactly which sections are now silence rather than absence.
+     */
+    coverageSilenced(field: string): string;
+    coverageDrift(field: string, was: string, now: string): string;
+    coverageDriftWhy(): string;
     againstOverlap(from: string, to: string): string;
     /**
      * What one conversation costs — median against p95, never a mean: one

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   countTokensAnthropic,
   DEFAULT_USAGE,
   detectFromSource,
+  coverageDrift,
   driversBetween,
   estimateTokens,
   evaluate,
@@ -2320,7 +2321,34 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     }
     if (typeof args.flags.get('max-growth-usd') === 'string' && againstDelta !== null) {
       const maxGrowth = numberFlag(args, 'max-growth-usd', 0, t);
-      if (againstDelta > maxGrowth) {
+      /**
+       * A comparison that went blind fails before it is judged.
+       *
+       * The dollars can hold flat while the current log stopped recording a
+       * field the previous one carried — and every finding that needed the
+       * field is now silent for a reason that has nothing to do with spend.
+       * A gate passing there would be certifying a comparison it could not
+       * make: "not measured" is not "did not grow", the same refusal
+       * --max-day-usd makes on a clockless log and --max-session-usd on a
+       * sessionless one. Only a collapse fails; a field that appeared means
+       * this side can see more, which is never a reason to refuse.
+       */
+      const blinded = previous !== null
+        ? coverageDrift(previous.fieldCoverage, report.fieldCoverage).filter((d) => d.delta < 0)
+        : [];
+      const worst = blinded[0];
+      if (worst !== undefined) {
+        console.error(
+          c.red(
+            t.profile.maxGrowthCoverageLost(
+              blinded.map((d) => t.profile.coverageField(d.field)).join(', '),
+              pct(worst.was),
+              pct(worst.now),
+            ),
+          ),
+        );
+        process.exitCode = 1;
+      } else if (againstDelta > maxGrowth) {
         console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
         process.exitCode = 1;
       }
@@ -3643,6 +3671,46 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
           console.log(`  ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
         }
       }
+
+      /**
+       * What the comparison stopped being able to see.
+       *
+       * Every figure above is dollars, and dollars cannot tell a finding that
+       * was fixed from a finding whose field the log stopped recording — both
+       * are silence. This is the only section that can, so it is loud: a
+       * collapse in coverage invalidates whichever findings depended on it,
+       * and reading the drop as good news is the specific mistake it exists
+       * to prevent.
+       */
+      const drifts = coverageDrift(previous.fieldCoverage, report.fieldCoverage);
+      if (drifts.length > 0) {
+        console.log();
+        for (const drift of drifts) {
+          const line = t.profile.coverageDrift(
+            t.profile.coverageField(drift.field),
+            pct(drift.was),
+            pct(drift.now),
+          );
+          console.log(
+            drift.delta < 0
+              ? `  ${c.yellow('!')} ${c.bold(wrap(line, 74, '    '))}`
+              : `  ${c.dim(wrap(line, 74, '  '))}`,
+          );
+          /**
+           * Which findings went with it, named. "Some findings are silent" is
+           * not something a reader can act on; knowing that conversation
+           * growth and the cache-TTL fit are now silence rather than absence
+           * tells them exactly which sections of this report to distrust.
+           */
+          if (drift.delta < 0) {
+            const silenced = t.profile.coverageSilenced(drift.field);
+            if (silenced !== '') console.log(`    ${c.dim(wrap(silenced, 72, '    '))}`);
+          }
+        }
+        if (drifts.some((d) => d.delta < 0)) {
+          console.log(`  ${c.dim(wrap(t.profile.coverageDriftWhy(), 74, '    '))}`);
+        }
+      }
     }
   }