@trazum/cli 1.32.0 → 1.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.32.0",
+  "version": "1.34.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.32.0"
+    "@trazum/core": "1.34.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -345,6 +345,11 @@ ${bold('CONFIG FILE')}
     spend     { "maxUsd": 200, "byLabel": { "chat": 40 } } — money budgets for
               "trazum profile", in dollars. A budgeted label with no calls in
               the log is reported as not measured, never as a pass
+    waive     [{ "gate": "maxUsd", "reason": "August migration", "until":
+              "2026-09-15" }] — a gate failure decided about, on the record.
+              All three fields required: a waiver with no end date is a
+              finding deleted with extra steps. Waived failures still print,
+              and the day the waiver expires the gate fails again
 
   Flags beat the config; the config beats the defaults. Budgets resolve to the
   most specific matching pattern — most literal characters wins. A boolean the
@@ -1150,6 +1155,28 @@ ${bold('EXAMPLES')}
       `--what-if does not know "${value}". Priced models: ${available}. Add it with --pricing if you have its rates.`,
     badGzip: (file, detail) =>
       `${file} is gzipped and would not decompress: ${detail}. Reading the rest and saying nothing would report a bill missing whatever that file held, so this stops instead. Check the file, or move it out of the directory.`,
+    dryRunHeading: () => 'What this log can answer — no bill was produced',
+    dryRunParsed: (parsed, skipped) =>
+      `${parsed} records parse; ${skipped} lines could not be read. A dry run prices nothing: the point is what the gates you are about to wire would stand on.`,
+    dryRunUnpriced: (models) =>
+      `Models the price table does not know: ${models}. Their tokens parse; their dollars need a --pricing overlay.`,
+    dryRunTotals: () => 'The bill itself: totals, per-model split, cache economics, the levers.',
+    dryRunLabels: (share) =>
+      `Per-workload findings and label budgets — "label" on ${share} of records.`,
+    dryRunClock: (share) =>
+      `The period, per-day and per-hour shape, --max-day-usd, --since/--until — a timestamp on ${share} of records.`,
+    dryRunSessions: (share) =>
+      `Conversation growth, per-conversation cost, --max-session-usd — a session on ${share} of records. Grouped by, never printed.`,
+    dryRunStopReason: (share) =>
+      `Truncated answers and their retry bill — a stop reason on ${share} of records.`,
+    dryRunCacheTtl: (ttl, writes) =>
+      `Settled cache verdicts — the "cache_creation" split on ${ttl} of ${writes} cache-writing records.`,
+    dryRunNoCacheTraffic: () =>
+      'Cache verdicts: nothing wrote to the cache in this log, so there is nothing to settle — not a missing field.',
+    dryRunFooter: () =>
+      'A ✗ is not a defect in the log; it is a finding this log cannot support yet. The README\'s recording recipe carries every field above.',
+    dryRunNoGates: () =>
+      '--dry-run produces no bill, so a gate beside it would exit green having judged nothing. Run the gates without --dry-run.',
     coverageHeading: () => 'What this log cannot answer yet',
     needsLabel: (seen) =>
       `"label" on ${seen} records: without it every workload is one row, so no per-workload spend, no drill-down, and the levers describe a mixture rather than a decision.`,
@@ -1177,6 +1204,10 @@ ${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.`,
+    waiveActive: (gate, reason, until, daysLeft) =>
+      `WAIVED — the ${gate} failure above is on the record and silenced until ${until} (${daysLeft} days left): "${reason}". The bill still counts it; only the exit code is quiet, and the day the waiver expires this gate fails again.`,
+    waiveExpired: (gate, until, reason) =>
+      `The waiver on ${gate} expired on ${until} and no longer silences anything. It was written for: "${reason}". Renew it with a new date and a current reason, or fix what it was covering — an expired waiver left in place is a finding deleted with extra steps.`,
     gateLargest: (label, model, usd, share) =>
       `Most of it is ${label} on ${model}: ${usd}, ${share} of the bill. That is where the money is, not necessarily where the fix is.`,
     gateLever: (label, action, saving, overage, covers) =>

package/src/i18n/es.ts

@@ -348,6 +348,12 @@ ${bold('FICHERO DE CONFIGURACIÓN')}
     spend     { "maxUsd": 200, "byLabel": { "chat": 40 } } — presupuestos en
               dólares para "trazum profile". Una etiqueta con presupuesto y sin
               llamadas se informa como no medida, nunca como aprobada
+    waive     [{ "gate": "maxUsd", "reason": "migración de agosto", "until":
+              "2026-09-15" }] — un fallo de gate sobre el que se ha decidido,
+              registrado. Los tres campos son obligatorios: un waiver sin
+              fecha de fin es un hallazgo borrado con pasos extra. Los fallos
+              waived se siguen imprimiendo, y el día que caduca el gate
+              vuelve a fallar
 
   Las opciones ganan al config; el config gana a los valores por defecto. Los
   presupuestos se resuelven con el patrón más específico que encaje — gana el
@@ -1165,6 +1171,28 @@ ${bold('EJEMPLOS')}
       `--what-if no conoce "${value}". Modelos con precio: ${available}. Añádelo con --pricing si tienes sus tarifas.`,
     badGzip: (file, detail) =>
       `${file} está comprimido con gzip y no se ha podido descomprimir: ${detail}. Leer el resto y no decir nada daría una factura a la que le falta lo que hubiera en ese fichero, así que se para aquí. Revisa el fichero, o sácalo del directorio.`,
+    dryRunHeading: () => 'Qué puede responder este registro — no se ha producido factura',
+    dryRunParsed: (parsed, skipped) =>
+      `${parsed} registros se leen; ${skipped} líneas no se pudieron leer. Un dry run no valora nada: el punto es sobre qué se apoyarían los gates que vas a cablear.`,
+    dryRunUnpriced: (models) =>
+      `Modelos que la tabla de precios no conoce: ${models}. Sus tokens se leen; sus dólares necesitan un overlay --pricing.`,
+    dryRunTotals: () => 'La factura en sí: totales, desglose por modelo, economía de caché, las palancas.',
+    dryRunLabels: (share) =>
+      `Hallazgos por carga y presupuestos por etiqueta — "label" en el ${share} de los registros.`,
+    dryRunClock: (share) =>
+      `El periodo, la forma por día y por hora, --max-day-usd, --since/--until — marca de tiempo en el ${share} de los registros.`,
+    dryRunSessions: (share) =>
+      `Crecimiento de conversación, coste por conversación, --max-session-usd — sesión en el ${share} de los registros. Se agrupa por ella, nunca se imprime.`,
+    dryRunStopReason: (share) =>
+      `Respuestas truncadas y su factura de reintentos — razón de parada en el ${share} de los registros.`,
+    dryRunCacheTtl: (ttl, writes) =>
+      `Veredictos de caché resueltos — el desglose "cache_creation" en ${ttl} de ${writes} registros que escriben caché.`,
+    dryRunNoCacheTraffic: () =>
+      'Veredictos de caché: nada escribió en la caché en este registro, así que no hay nada que resolver — no es un campo ausente.',
+    dryRunFooter: () =>
+      'Una ✗ no es un defecto del registro; es un hallazgo que este registro aún no puede sostener. La receta de registro del README lleva todos los campos de arriba.',
+    dryRunNoGates: () =>
+      '--dry-run no produce factura, así que un gate a su lado saldría en verde sin haber juzgado nada. Corre los gates sin --dry-run.',
     coverageHeading: () => 'Lo que este registro todavía no puede responder',
     needsLabel: (seen) =>
       `"label" en ${seen} registros: sin él todas las cargas son una sola fila, así que no hay gasto por carga, ni zoom, y las palancas describen una mezcla en vez de una decisión.`,
@@ -1192,6 +1220,10 @@ ${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.`,
+    waiveActive: (gate, reason, until, daysLeft) =>
+      `WAIVED — el fallo de ${gate} de arriba queda registrado y silenciado hasta ${until} (${daysLeft} días restantes): "${reason}". La factura lo sigue contando; solo el código de salida calla, y el día que caduque el waiver este gate vuelve a fallar.`,
+    waiveExpired: (gate, until, reason) =>
+      `El waiver de ${gate} caducó el ${until} y ya no silencia nada. Se escribió por: "${reason}". Renuévalo con fecha nueva y razón vigente, o arregla lo que cubría — un waiver caducado dejado ahí es un hallazgo borrado con pasos extra.`,
     gateLargest: (label, model, usd, share) =>
       `La mayor parte es ${label} en ${model}: ${usd}, el ${share} de la factura. Ahí está el dinero, no necesariamente el arreglo.`,
     gateLever: (label, action, saving, overage, covers) =>

package/src/i18n/types.ts

@@ -784,6 +784,13 @@ export interface CliMessages {
      * computed. Nothing here recommends: whether the cheaper model can do the
      * work is the reader's to judge, and the copy says so.
      */
+    /**
+     * Findings as policy. An active waiver silences one gate's exit code, on
+     * the record, with the reason and the days left; an expired one silences
+     * nothing and says so beside the failure it used to cover.
+     */
+    waiveActive(gate: string, reason: string, until: string, daysLeft: string): string;
+    waiveExpired(gate: string, until: string, reason: string): string;
     gateLargest(label: string, model: string, usd: string, share: string): string;
     gateLever(label: string, action: string, saving: string, overage: string, covers: boolean): string;
     /**
@@ -916,6 +923,23 @@ export interface CliMessages {
       * a skip: a total quietly missing a day is the failure this refuses.
       */
     badGzip(file: string, detail: string): string;
+    /**
+     * `--dry-run`: readiness per capability, no bill. The question somebody
+     * has before wiring CI, answered without making them read a report to
+     * discover a missing field.
+     */
+    dryRunHeading(): string;
+    dryRunParsed(parsed: string, skipped: string): string;
+    dryRunUnpriced(models: string): string;
+    dryRunTotals(): string;
+    dryRunLabels(share: string): string;
+    dryRunClock(share: string): string;
+    dryRunSessions(share: string): string;
+    dryRunStopReason(share: string): string;
+    dryRunCacheTtl(ttl: string, writes: string): string;
+    dryRunNoCacheTraffic(): string;
+    dryRunFooter(): string;
+    dryRunNoGates(): string;
     coverageHeading(): string;
     needsLabel(seen: string): string;
     needsSession(seen: string): string;

package/src/index.ts

@@ -440,7 +440,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   ],
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
-  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'],
+  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'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2146,6 +2146,52 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
 
+  /**
+   * `--dry-run`: what this log could and could not answer, and no bill.
+   *
+   * The question somebody has *before* wiring Trazum into CI is not "what did
+   * we spend" but "will this log support the gates I want" — and answering it
+   * with a full report makes them read a bill to find out a field is missing.
+   * This path states readiness per capability and produces no dollar figure
+   * at all, so nothing here can be mistaken for spend. It also refuses to
+   * coexist with the gates: a gate over a report that was never produced
+   * would exit green having judged nothing.
+   */
+  if (boolFlag(args, 'dry-run')) {
+    const gateFlags = ['max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd'];
+    if (gateFlags.some((flag) => typeof args.flags.get(flag) === 'string')) {
+      throw new Error(t.profile.dryRunNoGates());
+    }
+    const cov = report.fieldCoverage;
+    const parsed = cov.parsed;
+    console.log(c.bold(t.profile.dryRunHeading()));
+    console.log(`  ${wrap(t.profile.dryRunParsed(n(parsed), n(report.skippedLines.length)), 74, '  ')}`);
+    if (report.unpricedModels.length > 0) {
+      console.log(`  ${c.yellow('!')} ${wrap(t.profile.dryRunUnpriced(report.unpricedModels.join(', ')), 74, '    ')}`);
+    }
+    console.log();
+    const can = (ok: boolean, line: string): void => {
+      console.log(`  ${ok ? c.green('✓') : c.yellow('✗')} ${wrap(line, 74, '    ')}`);
+    };
+    const share = (count: number): string => (parsed > 0 ? pct(count / parsed) : '0%');
+    can(parsed > 0, t.profile.dryRunTotals());
+    can(cov.label > 0, t.profile.dryRunLabels(share(cov.label)));
+    can(cov.ts > 0, t.profile.dryRunClock(share(cov.ts)));
+    can(cov.session > 0, t.profile.dryRunSessions(share(cov.session)));
+    can(cov.stopReason > 0, t.profile.dryRunStopReason(share(cov.stopReason)));
+    // "No cache traffic" is not a missing field: the split can only exist on
+    // records that wrote, and a log that never wrote has nothing to record.
+    if (cov.cacheWrites > 0) {
+      can(cov.cacheTtl > 0, t.profile.dryRunCacheTtl(n(cov.cacheTtl), n(cov.cacheWrites)));
+    } else {
+      console.log(`  ${c.dim('·')} ${wrap(t.profile.dryRunNoCacheTraffic(), 74, '    ')}`);
+    }
+    console.log();
+    console.log(`  ${c.dim(wrap(t.profile.dryRunFooter(), 74, '  '))}`);
+    if (parsed === 0) process.exitCode = 1;
+    return;
+  }
+
   /**
    * The previous log, loaded before the output paths split so the growth gate
    * exists under `--json` too — a CI step reads the JSON and trusts the exit
@@ -2266,6 +2312,46 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
    */
   const gateVerdicts: string[] = [];
   let gateFailed = false;
+  /**
+   * Findings as policy. A waiver silences one gate's exit code for a bounded
+   * time, on the record: the failure still prints (waived is shown as
+   * waived, never hidden — the bill still counts it), the reason and the
+   * days left print beside it, and the day the waiver expires the gate
+   * fails again louder, naming the date and the reason somebody wrote.
+   * That expiry is the entire mechanism by which a waiver stays a decision
+   * instead of becoming a habit.
+   */
+  const waiverFor = (gate: string): { entry: { gate: string; reason: string; until: string }; expired: boolean } | null => {
+    const entry = (config.waive ?? []).find((w) => w.gate === gate);
+    if (entry === undefined) return null;
+    // The waiver covers its named day whole: expiry begins the next UTC day.
+    const expiresMs = Date.parse(`${entry.until}T00:00:00Z`) + 86_400_000;
+    return { entry, expired: Date.now() >= expiresMs };
+  };
+  /**
+   * Applies a waiver to one failing gate. Returns true when the failure is
+   * silenced — the caller skips its exitCode — and prints the record either
+   * way, because a waived failure that vanished from the output would be a
+   * finding deleted with extra steps.
+   */
+  const waived = (gate: string): boolean => {
+    const found = waiverFor(gate);
+    if (found === null) return false;
+    if (found.expired) {
+      console.error(
+        c.red(t.profile.waiveExpired(gate, found.entry.until, found.entry.reason)),
+      );
+      return false;
+    }
+    const daysLeft = Math.max(
+      0,
+      Math.ceil((Date.parse(`${found.entry.until}T00:00:00Z`) + 86_400_000 - Date.now()) / 86_400_000),
+    );
+    console.error(
+      c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))),
+    );
+    return true;
+  };
   const applyGates = (): void => {
     /**
      * Before any verdict: whether the gated figure is the whole bill. A gate
@@ -2312,7 +2398,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         }
         if (usd > limit) {
           console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
-          process.exitCode = 1;
+          if (!waived(`byLabel:${label}`)) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.labelBudgetOk(label, formatUsd(usd), formatUsd(limit))));
         }
@@ -2385,7 +2471,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
          * copy says so.
          */
         explainFailure(report.total.totalUsd - maxUsd);
-        process.exitCode = 1;
+        if (!waived('maxUsd')) process.exitCode = 1;
       } else {
         console.error(c.dim(t.profile.maxUsdOk(formatUsd(report.total.totalUsd), formatUsd(maxUsd))));
         explainMargin(report.total.totalUsd, maxUsd);
@@ -2419,10 +2505,13 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             ),
           ),
         );
+        // Deliberately unwaivable: this failure is "the comparison cannot
+        // be made", and a waiver on unmeasurability would be a decision to
+        // stop measuring — not a budget decision with an end date.
         process.exitCode = 1;
       } else if (againstDelta > maxGrowth) {
         console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
-        process.exitCode = 1;
+        if (!waived('maxGrowthUsd')) process.exitCode = 1;
       }
     }
     /**
@@ -2440,7 +2529,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         console.error(
           c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))),
         );
-        process.exitCode = 1;
+        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
       } else if (gateCache.worstCaseDeltaUsd > maxLoss) {
         console.error(
           c.red(
@@ -2451,7 +2540,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             ),
           ),
         );
-        process.exitCode = 1;
+        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxCacheLossOk(formatUsd(Math.max(0, gateCache.worstCaseDeltaUsd)), formatUsd(maxLoss))),
@@ -2500,7 +2589,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`),
           );
           explainFailure(worst.usd - maxDay, { namesLargest: true });
-          process.exitCode = 1;
+          if (!waived('maxDayUsd')) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.maxDayOk(worst.day, formatUsd(worst.usd), formatUsd(maxDay))));
           explainMargin(worst.usd, maxDay);
@@ -2542,7 +2631,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
           c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
         );
         explainFailure(report.sessionSpend.maxUsd - maxSession);
-        process.exitCode = 1;
+        if (!waived('maxSessionUsd')) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxSessionOk(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),