@trazum/cli 1.50.3 → 1.50.4

package/package.json

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

package/src/i18n/en.ts

@@ -597,6 +597,13 @@ ${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
+    outcomes  { "values": ["resolved", "escalated"], "success": ["resolved"] } —
+              your own vocabulary for what happened, and which of it counts as
+              a win. Both required: which words mean success is a judgement
+              about your product rather than your bill, and this tool has no
+              standing to make it. Use [] if none of them are successes. A
+              value in a log that "values" never declares is named as
+              undeclared, never counted as a failure
     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
@@ -1631,6 +1638,25 @@ ${bold('EXAMPLES')}
     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.`,
+    needsOutcome: (seen) =>
+      `an "outcome" — ${seen}. The one field that changes what every other figure here means: without it this tool can say a workload got 40% cheaper and cannot say whether it stopped working. Record your own word for what happened and declare the vocabulary under "outcomes".`,
+    dryRunOutcomes: (share) =>
+      `cost per outcome and a success rate (${share} of records carry an "outcome")`,
+    outcomeHeading: () => 'Outcomes',
+    outcomeRate: (rate, ofUsd) =>
+      `${rate} of ${ofUsd} in declared outcomes succeeded \u2014 by spend rather than by call, because the two diverge exactly when the expensive half is the half that fails.`,
+    outcomeNoRate: (why) =>
+      why === 'nothing-recorded'
+        ? 'No success rate: nothing in this log recorded an outcome. That is not a rate of zero \u2014 a rate of zero is a real and terrible measurement, and this is nobody having told us.'
+        : 'No success rate: "outcomes.success" declares no values, so nothing here counts as one. A legitimate thing to declare, and it means the rate is not this tool\u2019s to compute.',
+    outcomeUnrecorded: (share, usd) =>
+      `${share} of the bill (${usd}) carried no outcome, and is in neither half of the rate above.`,
+    outcomeUndeclared: (values) =>
+      `Not declared in "outcomes.values": ${values}. Named rather than counted as failures \u2014 a typo in an exporter should look like a typo, not like a product regression.`,
+    outcomeColumns: { outcome: 'outcome', calls: 'calls', spend: 'spend' },
+    verdictSuccess: () => 'success',
+    verdictOther: () => '\u2014',
+    verdictUndeclared: () => 'undeclared',
     needsSession: (seen) =>
       `"session" on ${seen} records: without it there is no conversation growth, no per-conversation cost, and no cache-TTL fit. It is grouped by and never printed.`,
     needsTs: (seen) =>

package/src/i18n/es.ts

@@ -617,6 +617,13 @@ ${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
+    outcomes  { "values": ["resolved", "escalated"], "success": ["resolved"] } —
+              tu propio vocabulario para lo que pasó, y cuál de él cuenta como
+              acierto. Los dos son obligatorios: qué palabras significan éxito
+              es un juicio sobre tu producto y no sobre tu factura, y esta
+              herramienta no tiene potestad para hacerlo. Usa [] si ninguna lo
+              es. Un valor en un log que "values" no declare se nombra como
+              sin declarar, nunca se cuenta como fallo
     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
@@ -1664,6 +1671,25 @@ ${bold('EJEMPLOS')}
     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.`,
+    needsOutcome: (seen) =>
+      `un "outcome" \u2014 ${seen}. El \u00fanico campo que cambia lo que significa cualquier otra cifra de aqu\u00ed: sin \u00e9l esta herramienta puede decir que una carga baj\u00f3 un 40% y no puede decir si dej\u00f3 de funcionar. Registra tu propia palabra para lo que pas\u00f3 y declara el vocabulario en "outcomes".`,
+    dryRunOutcomes: (share) =>
+      `coste por resultado y una tasa de \u00e9xito (${share} de los registros llevan "outcome")`,
+    outcomeHeading: () => 'Resultados',
+    outcomeRate: (rate, ofUsd) =>
+      `${rate} de ${ofUsd} en resultados declarados tuvo \u00e9xito \u2014 por gasto y no por llamada, porque las dos cifras divergen justo cuando la mitad cara es la que falla.`,
+    outcomeNoRate: (why) =>
+      why === 'nothing-recorded'
+        ? 'Sin tasa de \u00e9xito: nada en este log registr\u00f3 un resultado. Eso no es una tasa de cero \u2014 una tasa de cero es una medici\u00f3n real y p\u00e9sima, y esto es que nadie nos lo ha dicho.'
+        : 'Sin tasa de \u00e9xito: "outcomes.success" no declara ning\u00fan valor, as\u00ed que aqu\u00ed nada cuenta como \u00e9xito. Es leg\u00edtimo declararlo as\u00ed, y significa que la tasa no le corresponde calcularla a esta herramienta.',
+    outcomeUnrecorded: (share, usd) =>
+      `${share} de la factura (${usd}) no llev\u00f3 resultado, y no est\u00e1 en ninguna de las dos mitades de la tasa de arriba.`,
+    outcomeUndeclared: (values) =>
+      `No declarados en "outcomes.values": ${values}. Nombrados en vez de contados como fallos \u2014 una errata en un exportador debe parecer una errata, no una regresi\u00f3n del producto.`,
+    outcomeColumns: { outcome: 'resultado', calls: 'llamadas', spend: 'gasto' },
+    verdictSuccess: () => '\u00e9xito',
+    verdictOther: () => '\u2014',
+    verdictUndeclared: () => 'sin declarar',
     needsSession: (seen) =>
       `"session" en ${seen} registros: sin él no hay crecimiento de conversación, ni coste por conversación, ni encaje del TTL de caché. Se agrupa por él y nunca se imprime.`,
     needsTs: (seen) =>

package/src/i18n/types.ts

@@ -1121,6 +1121,17 @@ export interface CliMessages {
     coverageHeading(): string;
     needsLabel(seen: string): string;
     needsSession(seen: string): string;
+    needsOutcome(seen: string): string;
+    dryRunOutcomes(share: string): string;
+    outcomeHeading(): string;
+    outcomeRate(rate: string, ofUsd: string): string;
+    outcomeNoRate(why: string): string;
+    outcomeUnrecorded(share: string, usd: string): string;
+    outcomeUndeclared(values: string): string;
+    outcomeColumns: { outcome: string; calls: string; spend: string };
+    verdictSuccess(): string;
+    verdictOther(): string;
+    verdictUndeclared(): string;
     needsTs(seen: string): string;
     needsStopReason(seen: string): string;
     needsCacheTtl(seen: string): string;

package/src/index.ts

@@ -39,6 +39,7 @@ import {
   DEFAULT_USAGE,
   budgetPositions,
   conform,
+  outcomeReport,
   FAILURE_POLICIES,
   detectFromSource,
   matchLocale,
@@ -4585,6 +4586,7 @@ async function commandProfile(
     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.outcome > 0, t.profile.dryRunOutcomes(share(cov.outcome)));
     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.
@@ -6416,6 +6418,97 @@ async function commandProfile(
    * section at all, because a paragraph of things that are fine is the
    * paragraph readers learn to skip.
    */
+  /**
+   * Outcomes — the counterpart, where somebody recorded one.
+   *
+   * Printed above the coverage section rather than below it, because when this
+   * section is present it is the most valuable thing on the page: every other
+   * figure in this report is a cost, and this is the only one that says what
+   * the money bought.
+   *
+   * Silent when nothing recorded an outcome. The coverage section below
+   * already names the missing field and what it would unlock, and printing an
+   * empty Outcomes heading above it would be the same sentence twice.
+   */
+  {
+    const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
+    if (outcomes.coverage.recorded > 0) {
+      console.log();
+      console.log(c.bold(t.profile.outcomeHeading()));
+
+      const col = t.profile.outcomeColumns;
+      const rows = [...outcomes.slices, ...outcomes.undeclared].map((slice) => ({
+        value: slice.value,
+        verdict:
+          slice.verdict === 'success'
+            ? t.profile.verdictSuccess()
+            : slice.verdict === 'undeclared'
+              ? t.profile.verdictUndeclared()
+              : t.profile.verdictOther(),
+        calls: n(slice.calls),
+        spend: formatUsd(slice.usd),
+      }));
+      const w = {
+        value: Math.max(...rows.map((r) => r.value.length), col.outcome.length),
+        verdict: Math.max(...rows.map((r) => r.verdict.length), 0),
+        calls: Math.max(...rows.map((r) => r.calls.length), col.calls.length),
+        spend: Math.max(...rows.map((r) => r.spend.length), col.spend.length),
+      };
+      console.log(
+        c.dim(
+          `  ${col.outcome.padEnd(w.value)}  ${''.padEnd(w.verdict)}  ` +
+            `${col.calls.padStart(w.calls)}  ${col.spend.padStart(w.spend)}`,
+        ),
+      );
+      for (const row of rows) {
+        const tint =
+          row.verdict === t.profile.verdictUndeclared()
+            ? c.yellow
+            : row.verdict === t.profile.verdictSuccess()
+              ? c.green
+              : c.dim;
+        console.log(
+          `  ${row.value.padEnd(w.value)}  ${tint(row.verdict.padEnd(w.verdict))}  ` +
+            `${row.calls.padStart(w.calls)}  ${row.spend.padStart(w.spend)}`,
+        );
+      }
+
+      console.log();
+      if (outcomes.successShareOfRecordedUsd !== null) {
+        const declaredUsd = outcomes.slices.reduce((sum, slice) => sum + slice.usd, 0);
+        console.log(
+          `  ${wrap(t.profile.outcomeRate(pct(outcomes.successShareOfRecordedUsd), formatUsd(declaredUsd)), 74, '    ')}`,
+        );
+      } else if (outcomes.noRate !== null) {
+        console.log(`  ${c.dim(wrap(t.profile.outcomeNoRate(outcomes.noRate), 74, '    '))}`);
+      }
+
+      // What the rate does not cover, every time it is printed. A rate over a
+      // twelfth of the bill is a rate about a twelfth of the bill.
+      if (outcomes.coverage.unrecordedUsd > 0 && report.total.totalUsd > 0) {
+        console.log(
+          `  ${c.yellow('!')} ${wrap(
+            t.profile.outcomeUnrecorded(
+              pct(outcomes.coverage.unrecordedUsd / report.total.totalUsd),
+              formatUsd(outcomes.coverage.unrecordedUsd),
+            ),
+            74,
+            '    ',
+          )}`,
+        );
+      }
+      if (outcomes.undeclared.length > 0) {
+        console.log(
+          `  ${c.yellow('!')} ${wrap(
+            t.profile.outcomeUndeclared(outcomes.undeclared.map((s) => s.value).join(', ')),
+            74,
+            '    ',
+          )}`,
+        );
+      }
+    }
+  }
+
   const coverage = report.fieldCoverage;
   if (coverage.parsed > 0) {
     const missing: string[] = [];
@@ -6426,6 +6519,14 @@ async function commandProfile(
     if (coverage.session < coverage.parsed) {
       missing.push(t.profile.needsSession(partial(coverage.session)));
     }
+    /**
+     * Listed first among the missing when it is missing entirely, because it
+     * is the one field that changes what every other figure here *means*. The
+     * rest sharpen a cost; this one gives it a counterpart.
+     */
+    if (coverage.outcome < coverage.parsed) {
+      missing.push(t.profile.needsOutcome(partial(coverage.outcome)));
+    }
     if (coverage.ts < coverage.parsed) {
       missing.push(t.profile.needsTs(partial(coverage.ts)));
     }