@trazum/cli 1.50.3 → 1.50.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.50.3",
+  "version": "1.50.5",
   "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.5"
   },
   "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,49 @@ ${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.`,
+    perOutcomeHeading: () => 'What an outcome costs',
+    perOutcomeRow: (key, perCall, perOutcome, coverage) => `${key} ${perCall} ${perOutcome} ${coverage}`,
+    perOutcomeColumns: {
+      workload: 'workload',
+      perCall: 'per call',
+      perOutcome: 'per success',
+      recorded: 'recorded',
+    },
+    perOutcomeWithheld: (why, successes, coverage) =>
+      why === 'too-few-outcomes'
+        ? `${successes} so far`
+        : why === 'too-little-coverage'
+          ? `${coverage} covered`
+          : why === 'no-successes-recorded'
+            ? 'none succeeded'
+            : why === 'nothing-recorded'
+              ? 'not recorded'
+              : 'no vocabulary',
+    perOutcomeNumerator: () =>
+      'Per success divides the spend on calls that recorded an outcome, never the whole bill \u2014 dividing everything would charge your uninstrumented traffic to your measured successes and report a figure too high by exactly the uncovered share, silently, in the direction that gets a working feature killed. "recorded" is what share of each workload\u2019s spend the figure covers.',
+    perOutcomeDisagreement: (key, callRank, outcomeRank) =>
+      `${key} is #${callRank} by cost per call and #${outcomeRank} by cost per success.`,
+    perOutcomeBothOrders: () =>
+      'Cheapest per call and cheapest per success are different orders, and both are printed rather than one being picked. A workload can move up one while moving down the other, and somebody optimising on the first number would be moving the wrong one.',
+    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,49 @@ ${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.`,
+    perOutcomeHeading: () => 'Lo que cuesta un resultado',
+    perOutcomeRow: (key, perCall, perOutcome, coverage) => `${key} ${perCall} ${perOutcome} ${coverage}`,
+    perOutcomeColumns: {
+      workload: 'carga',
+      perCall: 'por llamada',
+      perOutcome: 'por acierto',
+      recorded: 'cubierto',
+    },
+    perOutcomeWithheld: (why, successes, coverage) =>
+      why === 'too-few-outcomes'
+        ? `${successes} hasta ahora`
+        : why === 'too-little-coverage'
+          ? `${coverage} cubierto`
+          : why === 'no-successes-recorded'
+            ? 'ninguno acert\u00f3'
+            : why === 'nothing-recorded'
+              ? 'sin registrar'
+              : 'sin vocabulario',
+    perOutcomeNumerator: () =>
+      'Por acierto divide el gasto de las llamadas que registraron un resultado, nunca la factura entera \u2014 dividirlo todo cargar\u00eda tu tr\u00e1fico sin instrumentar a tus aciertos medidos y dar\u00eda una cifra alta por exactamente la parte no cubierta, en silencio, en la direcci\u00f3n que mata una funci\u00f3n que s\u00ed funciona. "cubierto" es qu\u00e9 parte del gasto de cada carga cubre la cifra.',
+    perOutcomeDisagreement: (key, callRank, outcomeRank) =>
+      `${key} es el #${callRank} por coste por llamada y el #${outcomeRank} por coste por acierto.`,
+    perOutcomeBothOrders: () =>
+      'M\u00e1s barato por llamada y m\u00e1s barato por acierto son \u00f3rdenes distintos, y se imprimen los dos en vez de elegir uno. Una carga puede subir en uno mientras baja en el otro, y quien optimice por el primer n\u00famero estar\u00eda moviendo el equivocado.',
+    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,24 @@ 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;
+    perOutcomeHeading(): string;
+    perOutcomeRow(key: string, perCall: string, perOutcome: string, coverage: string): string;
+    perOutcomeColumns: { workload: string; perCall: string; perOutcome: string; recorded: string };
+    perOutcomeWithheld(why: string, successes: string, coverage: string): string;
+    perOutcomeNumerator(): string;
+    perOutcomeDisagreement(key: string, callRank: string, outcomeRank: string): string;
+    perOutcomeBothOrders(): 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,8 @@ import {
   DEFAULT_USAGE,
   budgetPositions,
   conform,
+  outcomeReport,
+  rankPerOutcome,
   FAILURE_POLICIES,
   detectFromSource,
   matchLocale,
@@ -4585,6 +4587,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 +6419,167 @@ 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,
+            '    ',
+          )}`,
+        );
+      }
+      /**
+       * What an outcome costs, per workload — the finding a total cannot make.
+       *
+       * Printed only when at least one workload has enough recorded outcomes
+       * to say something, and every row that cannot state a figure says which
+       * of the five reasons applies rather than showing a blank.
+       */
+      const ranking = rankPerOutcome(
+        report.outcomeTallyByLabel.map((entry) => ({
+          key: entry.label,
+          calls: entry.calls,
+          totalUsd: entry.totalUsd,
+          tally: entry.tally,
+        })),
+        config.outcomes ?? null,
+      );
+      if (ranking.byCall.length > 0) {
+        console.log();
+        console.log(c.bold(t.profile.perOutcomeHeading()));
+        const pcol = t.profile.perOutcomeColumns;
+        const prows = ranking.byCall.map((slice) => ({
+          key: slice.key,
+          perCall: formatUsd(slice.usdPerCall),
+          perOutcome:
+            slice.per.usdPerSuccess !== null
+              ? formatUsd(slice.per.usdPerSuccess)
+              : t.profile.perOutcomeWithheld(
+                  slice.per.withheld ?? 'no-vocabulary',
+                  n(slice.per.successes),
+                  pct(slice.per.coverage),
+                ),
+          recorded: pct(slice.per.coverage),
+        }));
+        const pw = {
+          key: Math.max(...prows.map((r) => r.key.length), pcol.workload.length),
+          perCall: Math.max(...prows.map((r) => r.perCall.length), pcol.perCall.length),
+          perOutcome: Math.max(...prows.map((r) => r.perOutcome.length), pcol.perOutcome.length),
+          recorded: Math.max(...prows.map((r) => r.recorded.length), pcol.recorded.length),
+        };
+        console.log(
+          c.dim(
+            `  ${pcol.workload.padEnd(pw.key)}  ${pcol.perCall.padStart(pw.perCall)}  ` +
+              `${pcol.perOutcome.padStart(pw.perOutcome)}  ${pcol.recorded.padStart(pw.recorded)}`,
+          ),
+        );
+        for (const row of prows) {
+          console.log(
+            `  ${row.key.padEnd(pw.key)}  ${row.perCall.padStart(pw.perCall)}  ` +
+              `${row.perOutcome.padStart(pw.perOutcome)}  ${c.dim(row.recorded.padStart(pw.recorded))}`,
+          );
+        }
+        console.log();
+        console.log(`  ${c.dim(wrap(t.profile.perOutcomeNumerator(), 74, '    '))}`);
+
+        // The disagreement between the two orders, which is itself the finding.
+        if (ranking.disagreements.length > 0) {
+          console.log();
+          console.log(`  ${c.dim(wrap(t.profile.perOutcomeBothOrders(), 74, '    '))}`);
+          for (const d of ranking.disagreements) {
+            console.log(
+              `  ${c.yellow('→')} ${wrap(
+                t.profile.perOutcomeDisagreement(d.slice.key, n(d.callRank + 1), n(d.outcomeRank + 1)),
+                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 +6590,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)));
     }