@trazum/cli 1.50.9 → 1.50.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.50.9",
3
+ "version": "1.50.11",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.50.9"
40
+ "@trazum/core": "1.50.11"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -61,6 +61,8 @@ ${bold('USAGE')}
61
61
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
62
62
  trazum quality <log> --label <name> --at <iso> [--gate]
63
63
  trazum semantic <prompt> [--yes]
64
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
65
+ trazum owners <log>
64
66
  trazum ladder <log>
65
67
  trazum feedback
66
68
  trazum --version
@@ -159,6 +161,17 @@ ${bold('OPTIONS FOR semantic')}
159
161
  pairs the rules engine already catches are dropped, and every token figure is
160
162
  counted rather than believed. Optional, and always will be.
161
163
 
164
+ ${bold('OPTIONS FOR commitment')}
165
+ --floor <usd> What you commit to spending each month, after
166
+ the discount. Required.
167
+ --discount <pct> What you get off list. 20 and 0.2 both work.
168
+ --months <n> How long the deal runs. Defaults to 12.
169
+
170
+ Replays measured whole months against the deal's terms. Both directions are
171
+ priced: the months that cleared the floor, and what the floor cost in the
172
+ months that fell short — kept as its own figure, because netted into the
173
+ saving it disappears. An as-if calculation about the past, never a forecast.
174
+
162
175
  ${bold('OPTIONS FOR prune')}
163
176
  --cases <file> One input per line, or a JSON array. Required.
164
177
  --yes Actually spend the calls. Without it the estimate is
@@ -638,6 +651,12 @@ ${bold('CONFIG FILE')}
638
651
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } } — money budgets for
639
652
  "trazum profile", in dollars. A budgeted label with no calls in
640
653
  the log is reported as not measured, never as a pass
654
+ owners { "patterns": { "payments": ["billing-*"] },
655
+ "shared": { "search": { "payments": 0.6, "support": 0.4 } },
656
+ "budgets": { "payments": 400 } } — whose budget each workload
657
+ lands on. Spend matching no owner is its own line and is NEVER
658
+ divided between the others; a shared split must sum to 1, and the
659
+ rule travels with the report so the argument is about the rule
641
660
  ladders { "support": { "tiers": ["claude-haiku-4-5", "claude-opus-5"],
642
661
  "escalateOn": ["escalated"] } } — cheap model first, escalate a
643
662
  recorded failure to a dearer one. Both fields required.
@@ -1004,6 +1023,62 @@ ${bold('EXAMPLES')}
1004
1023
  `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
1005
1024
  },
1006
1025
 
1026
+ commitment: {
1027
+ heading: (floor, discount, months) =>
1028
+ `A ${months}-month commitment: ${floor} a month at ${discount} off`,
1029
+ needsTerms: () =>
1030
+ '--floor and --discount are required, and --months defaults to 12. Take them from the contract the provider is offering you: the floor is what you commit to spending each month after the discount, and the discount is what you get off list.',
1031
+ asIf: () =>
1032
+ 'This is what the deal WOULD HAVE done on the traffic you actually had. It is a measurement of the past, not a prediction \u2014 every month below happened.',
1033
+ columns: { month: 'month', list: 'list', paid: 'would pay', saving: 'saving' },
1034
+ net: (usd, months) => `Net over ${months} measured months: ${usd}.`,
1035
+ good: (usd) => `The months that cleared the floor saved ${usd}.`,
1036
+ lost: (usd, months) =>
1037
+ `${months} of them fell short, and the floor you would have paid for capacity nobody used comes to ${usd}. That figure is kept separate on purpose: netted into the line above it disappears, and the disappearing is what a vendor\u2019s slide relies on.`,
1038
+ noShortfall: () => 'No measured month would have fallen short of the floor.',
1039
+ breakEven: (usd) =>
1040
+ `Break-even is ${usd} of monthly spend. Below it you pay the floor for less usage than it buys; above it the saving grows.`,
1041
+ spread: (low, high, median) =>
1042
+ `Measured spread: ${low} to ${high}, median ${median}. That is the shortfall risk in the only form a log can state it \u2014 a count of real months and the range they covered, rather than a probability from a distribution nobody fitted.`,
1043
+ shortTerm: (covered, term) =>
1044
+ `This replays ${covered} months against a ${term}-month commitment. It is a real answer about ${covered} months and not about ${term}.`,
1045
+ cannotTell: (why, needed) =>
1046
+ why === 'no-history'
1047
+ ? 'Nothing to replay: this log has no whole months in it.'
1048
+ : `Cannot judge this from ${needed === '0' ? 'what exists' : `what exists \u2014 ${needed} more whole month(s) would settle it`}. A commitment is signed for a year, and an answer from one month is a year-long decision made on a fortnight of evidence.`,
1049
+ neverAForecast: () =>
1050
+ 'Nothing here is annualised, extrapolated or fitted to a trend. If next quarter looks nothing like last quarter, this arithmetic says nothing about it \u2014 which is the honest limit of what a log can tell you about a contract.',
1051
+ },
1052
+
1053
+ owners: {
1054
+ heading: () => 'Whose money',
1055
+ noOwners: () =>
1056
+ 'No owners configured. Add "owners" to trazum.config.json to attribute spend, for example {"patterns": {"payments": ["billing-*"]}, "budgets": {"payments": 400}}.',
1057
+ columns: { owner: 'owner', spend: 'spend', budget: 'budget', calls: 'calls' },
1058
+ verdict: (kind) =>
1059
+ kind === 'over' ? 'over' : kind === 'within' ? 'within' : kind === 'not-measured' ? 'not measured' : '\u2014',
1060
+ unallocated: (usd, share, labels) =>
1061
+ `Unallocated: ${usd} (${share} of the bill), from ${labels}.`,
1062
+ neverSpread: () =>
1063
+ 'It is not divided between the owners above, and it never will be. Spreading unattributed spend proportionally is the most common lie in cost reporting: it makes every line add up and every team\u2019s number wrong by an amount nobody can see \u2014 hardest on whoever instruments best, because their known spend is largest and they absorb the biggest share of somebody else\u2019s mystery. Claim it with a pattern.',
1064
+ nothingUnallocated: () => 'Every workload in this log has an owner.',
1065
+ sharedHeading: () => 'Shared, by a rule somebody wrote',
1066
+ sharedRule: (label, rule) => `${label}: ${rule}`,
1067
+ problemsHeading: () => 'This ownership config will not do what it looks like it does',
1068
+ problem: (kind, detail) =>
1069
+ kind === 'split-does-not-sum'
1070
+ ? `${detail} \u2014 a split that does not sum to 1 loses money or invents it, silently. That workload is left whole in the unallocated line until this is fixed.`
1071
+ : kind === 'split-names-unknown-owner'
1072
+ ? `${detail} names an owner that "owners.patterns" does not declare.`
1073
+ : kind === 'split-has-one-owner'
1074
+ ? `${detail} is "shared" with one owner \u2014 that is a pattern written the long way, and reading it as a share invites a second owner to be added without the first being adjusted.`
1075
+ : kind === 'negative-share'
1076
+ ? `${detail} has a negative share.`
1077
+ : `${detail} has a budget but no patterns, so nothing can ever land on it.`,
1078
+ notMeasured: (owner) =>
1079
+ `${owner} has a budget and no measured calls. That is NOT under budget \u2014 a team whose logs never arrived passes every budget it has, forever, and a green tick beside their name says the opposite of the truth.`,
1080
+ },
1081
+
1007
1082
  semantic: {
1008
1083
  heading: (path) => `Semantic pass on ${path}`,
1009
1084
  willCost: (usd, input, output, model) =>
package/src/i18n/es.ts CHANGED
@@ -48,6 +48,8 @@ ${bold('USO')}
48
48
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
49
49
  trazum quality <log> --label <name> --at <iso> [--gate]
50
50
  trazum semantic <prompt> [--yes]
51
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
52
+ trazum owners <log>
51
53
  trazum ladder <log>
52
54
  trazum feedback
53
55
  trazum --version
@@ -149,6 +151,18 @@ ${bold('OPCIONES DE semantic')}
149
151
  carácter contra el prompt, los pares que el motor de reglas ya caza se
150
152
  descartan, y toda cifra de tokens se cuenta en vez de creérsela.
151
153
 
154
+ ${bold('OPCIONES DE commitment')}
155
+ --floor <usd> Lo que te comprometes a gastar cada mes, después
156
+ del descuento. Obligatorio.
157
+ --discount <pct> Lo que te quitan de tarifa. Vale 20 y vale 0.2.
158
+ --months <n> Cuánto dura el acuerdo. Por defecto 12.
159
+
160
+ Replica los meses completos medidos contra las condiciones del acuerdo. Se
161
+ tarifan las dos direcciones: los meses que superaron el suelo, y lo que
162
+ costó el suelo en los meses que se quedaron cortos — como cifra aparte,
163
+ porque metida en el ahorro desaparece. Un cálculo sobre el pasado, nunca una
164
+ previsión.
165
+
152
166
  ${bold('OPCIONES DE prune')}
153
167
  --cases <fichero> Una entrada por línea, o un array JSON. Obligatorio.
154
168
  --yes Gasta las llamadas de verdad. Sin él se imprime la
@@ -658,6 +672,12 @@ ${bold('FICHERO DE CONFIGURACIÓN')}
658
672
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } } — presupuestos en
659
673
  dólares para "trazum profile". Una etiqueta con presupuesto y sin
660
674
  llamadas se informa como no medida, nunca como aprobada
675
+ owners { "patterns": { "payments": ["billing-*"] },
676
+ "shared": { "search": { "payments": 0.6, "support": 0.4 } },
677
+ "budgets": { "payments": 400 } } — de quién es el presupuesto de
678
+ cada carga. El gasto sin propietario es su propia línea y NUNCA se
679
+ reparte entre los demás; un reparto compartido debe sumar 1, y la
680
+ regla viaja con el informe para que se discuta la regla
661
681
  ladders { "support": { "tiers": ["claude-haiku-4-5", "claude-opus-5"],
662
682
  "escalateOn": ["escalated"] } } — modelo barato primero, escalar
663
683
  un fallo registrado a uno más caro. Los dos campos obligatorios.
@@ -1040,6 +1060,62 @@ ${bold('EJEMPLOS')}
1040
1060
  `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
1041
1061
  },
1042
1062
 
1063
+ commitment: {
1064
+ heading: (floor, discount, months) =>
1065
+ `Un compromiso de ${months} meses: ${floor} al mes con ${discount} de descuento`,
1066
+ needsTerms: () =>
1067
+ '--floor y --discount son obligatorios, y --months son 12 por defecto. S\u00e1calos del contrato que te ofrecen: el suelo es lo que te comprometes a gastar cada mes despu\u00e9s del descuento, y el descuento es lo que te quitan de tarifa.',
1068
+ asIf: () =>
1069
+ 'Esto es lo que el acuerdo HABR\u00cdA hecho sobre el tr\u00e1fico que realmente tuviste. Es una medici\u00f3n del pasado, no una predicci\u00f3n \u2014 todos los meses de abajo ocurrieron.',
1070
+ columns: { month: 'mes', list: 'tarifa', paid: 'pagar\u00edas', saving: 'ahorro' },
1071
+ net: (usd, months) => `Neto sobre ${months} meses medidos: ${usd}.`,
1072
+ good: (usd) => `Los meses que superaron el suelo ahorraron ${usd}.`,
1073
+ lost: (usd, months) =>
1074
+ `${months} de ellos se quedaron cortos, y el suelo que habr\u00edas pagado por capacidad que nadie us\u00f3 suma ${usd}. Esa cifra se mantiene aparte a prop\u00f3sito: metida en la l\u00ednea de arriba desaparece, y esa desaparici\u00f3n es de lo que vive la diapositiva de un comercial.`,
1075
+ noShortfall: () => 'Ning\u00fan mes medido se habr\u00eda quedado por debajo del suelo.',
1076
+ breakEven: (usd) =>
1077
+ `El equilibrio est\u00e1 en ${usd} de gasto mensual. Por debajo pagas el suelo por menos uso del que compra; por encima el ahorro crece.`,
1078
+ spread: (low, high, median) =>
1079
+ `Dispersi\u00f3n medida: de ${low} a ${high}, mediana ${median}. Ese es el riesgo de quedarse corto en la \u00fanica forma en que un log puede expresarlo \u2014 un recuento de meses reales y el rango que cubrieron, no una probabilidad de una distribuci\u00f3n que nadie ajust\u00f3.`,
1080
+ shortTerm: (covered, term) =>
1081
+ `Esto replica ${covered} meses contra un compromiso de ${term} meses. Es una respuesta real sobre ${covered} meses y no sobre ${term}.`,
1082
+ cannotTell: (why, needed) =>
1083
+ why === 'no-history'
1084
+ ? 'Nada que replicar: este log no tiene meses completos.'
1085
+ : `No se puede juzgar con ${needed === '0' ? 'lo que hay' : `lo que hay \u2014 ${needed} mes(es) completo(s) m\u00e1s lo zanjar\u00edan`}. Un compromiso se firma por un a\u00f1o, y una respuesta de un mes es una decisi\u00f3n anual tomada con quince d\u00edas de evidencia.`,
1086
+ neverAForecast: () =>
1087
+ 'Aqu\u00ed nada se anualiza, se extrapola ni se ajusta a una tendencia. Si el pr\u00f3ximo trimestre no se parece al anterior, esta aritm\u00e9tica no dice nada sobre \u00e9l \u2014 que es el l\u00edmite honesto de lo que un log puede contarte sobre un contrato.',
1088
+ },
1089
+
1090
+ owners: {
1091
+ heading: () => 'De qui\u00e9n es el dinero',
1092
+ noOwners: () =>
1093
+ 'No hay propietarios configurados. A\u00f1ade "owners" a trazum.config.json para atribuir gasto, por ejemplo {"patterns": {"payments": ["billing-*"]}, "budgets": {"payments": 400}}.',
1094
+ columns: { owner: 'propietario', spend: 'gasto', budget: 'presupuesto', calls: 'llamadas' },
1095
+ verdict: (kind) =>
1096
+ kind === 'over' ? 'pasado' : kind === 'within' ? 'dentro' : kind === 'not-measured' ? 'sin medir' : '\u2014',
1097
+ unallocated: (usd, share, labels) =>
1098
+ `Sin asignar: ${usd} (${share} de la factura), de ${labels}.`,
1099
+ neverSpread: () =>
1100
+ 'No se reparte entre los propietarios de arriba, y nunca se har\u00e1. Repartir el gasto sin atribuir de forma proporcional es la mentira m\u00e1s com\u00fan en informes de coste: hace que todas las l\u00edneas cuadren y que el n\u00famero de cada equipo est\u00e9 mal en una cantidad que nadie puede ver \u2014 y castiga m\u00e1s a quien mejor instrumenta, porque su gasto conocido es el mayor y absorbe la mayor parte del misterio ajeno. Recl\u00e1malo con un patr\u00f3n.',
1101
+ nothingUnallocated: () => 'Todas las cargas de este log tienen propietario.',
1102
+ sharedHeading: () => 'Compartido, por una regla que escribi\u00f3 alguien',
1103
+ sharedRule: (label, rule) => `${label}: ${rule}`,
1104
+ problemsHeading: () => 'Esta configuraci\u00f3n de propiedad no va a hacer lo que parece',
1105
+ problem: (kind, detail) =>
1106
+ kind === 'split-does-not-sum'
1107
+ ? `${detail} \u2014 un reparto que no suma 1 pierde dinero o lo inventa, en silencio. Esa carga se deja entera en la l\u00ednea sin asignar hasta que se arregle.`
1108
+ : kind === 'split-names-unknown-owner'
1109
+ ? `${detail} nombra un propietario que "owners.patterns" no declara.`
1110
+ : kind === 'split-has-one-owner'
1111
+ ? `${detail} est\u00e1 "compartido" con un solo propietario \u2014 eso es un patr\u00f3n escrito largo, y leerlo como reparto invita a a\u00f1adir un segundo sin ajustar el primero.`
1112
+ : kind === 'negative-share'
1113
+ ? `${detail} tiene un reparto negativo.`
1114
+ : `${detail} tiene presupuesto pero no patrones, as\u00ed que nunca podr\u00e1 caerle nada.`,
1115
+ notMeasured: (owner) =>
1116
+ `${owner} tiene presupuesto y ninguna llamada medida. Eso NO es estar dentro del presupuesto \u2014 un equipo cuyos logs nunca llegaron pasa todos sus presupuestos, siempre, y un tic verde junto a su nombre dice lo contrario de la verdad.`,
1117
+ },
1118
+
1043
1119
  semantic: {
1044
1120
  heading: (path) => `Pase sem\u00e1ntico sobre ${path}`,
1045
1121
  willCost: (usd, input, output, model) =>
package/src/i18n/types.ts CHANGED
@@ -268,6 +268,37 @@ export interface CliMessages {
268
268
  * The ladder. Every line here exists to stop somebody reading "we route to
269
269
  * the cheap model first" as a saving without the number that decides it.
270
270
  */
271
+ commitment: {
272
+ heading(floor: string, discount: string, months: string): string;
273
+ needsTerms(): string;
274
+ asIf(): string;
275
+ columns: { month: string; list: string; paid: string; saving: string };
276
+ net(usd: string, months: string): string;
277
+ good(usd: string): string;
278
+ lost(usd: string, months: string): string;
279
+ noShortfall(): string;
280
+ breakEven(usd: string): string;
281
+ spread(low: string, high: string, median: string): string;
282
+ shortTerm(covered: string, term: string): string;
283
+ cannotTell(why: string, needed: string): string;
284
+ neverAForecast(): string;
285
+ };
286
+
287
+ owners: {
288
+ heading(): string;
289
+ noOwners(): string;
290
+ columns: { owner: string; spend: string; budget: string; calls: string };
291
+ verdict(kind: string): string;
292
+ unallocated(usd: string, share: string, labels: string): string;
293
+ neverSpread(): string;
294
+ nothingUnallocated(): string;
295
+ sharedHeading(): string;
296
+ sharedRule(label: string, rule: string): string;
297
+ problemsHeading(): string;
298
+ problem(kind: string, detail: string): string;
299
+ notMeasured(owner: string): string;
300
+ };
301
+
271
302
  semantic: {
272
303
  heading(path: string): string;
273
304
  willCost(usd: string, input: string, output: string, model: string): string;
package/src/index.ts CHANGED
@@ -40,6 +40,9 @@ import {
40
40
  budgetPositions,
41
41
  conform,
42
42
  BREAK_EVEN_BAND,
43
+ allocate,
44
+ replayCommitment,
45
+ coversTheTerm,
43
46
  runExperiment,
44
47
  qualityGate,
45
48
  semanticPassCost,
@@ -256,6 +259,9 @@ const VALUE_FLAGS = new Set([
256
259
  'a',
257
260
  'at',
258
261
  'b',
262
+ 'floor',
263
+ 'discount',
264
+ 'months',
259
265
  'min-outcomes',
260
266
  'against',
261
267
  'contract',
@@ -589,6 +595,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
589
595
  experiment: ['a', 'b', 'min-outcomes', 'pricing', 'pricing-live'],
590
596
  quality: ['label', 'at', 'gate', 'pricing', 'pricing-live'],
591
597
  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
598
+ owners: ['pricing', 'pricing-live', 'since', 'until'],
599
+ commitment: ['floor', 'discount', 'months', 'pricing', 'pricing-live'],
592
600
  where: [],
593
601
  rules: [],
594
602
  blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2734,6 +2742,307 @@ async function commandSemantic(
2734
2742
  console.log();
2735
2743
  }
2736
2744
 
2745
+ /**
2746
+ * `trazum owners <log>` — whose budget each workload lands on.
2747
+ *
2748
+ * The fleet answered *which service* in 1.37. This answers *whose money*,
2749
+ * which is the question that decides whether anything on the list gets done: a
2750
+ * report saying "the bill is $40,000 and here is $9,000 of savings" is read by
2751
+ * four people who each assume it is one of the other three's problem.
2752
+ *
2753
+ * **The unallocated is its own line and is never spread.** See `owners.ts` for
2754
+ * why that is worth breaking a module over.
2755
+ */
2756
+ async function commandOwners(
2757
+ args: Args,
2758
+ config: TrazumConfig,
2759
+ pricing: PricingCatalogue,
2760
+ t: CliMessages,
2761
+ ): Promise<void> {
2762
+ const path = args.positional[0];
2763
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
2764
+
2765
+ console.log();
2766
+ console.log(c.bold(t.owners.heading()));
2767
+ if (config.owners === undefined) {
2768
+ console.log(` ${c.dim(wrap(t.owners.noOwners(), 74, ' '))}`);
2769
+ console.log();
2770
+ return;
2771
+ }
2772
+
2773
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
2774
+ const result = allocate(
2775
+ report.byLabel.map((entry) => ({
2776
+ label: entry.label,
2777
+ usd: entry.breakdown.totalUsd,
2778
+ calls: entry.breakdown.calls,
2779
+ })),
2780
+ config.owners,
2781
+ );
2782
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
2783
+ const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
2784
+
2785
+ /**
2786
+ * Problems first, before any figure.
2787
+ *
2788
+ * A split that does not sum to one sends a whole workload to unallocated,
2789
+ * and a reader who saw the table before the explanation would go looking for
2790
+ * a bug in their logs.
2791
+ */
2792
+ if (result.problems.length > 0) {
2793
+ console.log();
2794
+ console.log(` ${c.red('✗')} ${c.bold(t.owners.problemsHeading())}`);
2795
+ for (const problem of result.problems) {
2796
+ const detail =
2797
+ problem.kind === 'budget-for-unknown-owner'
2798
+ ? problem.owner
2799
+ : problem.kind === 'split-does-not-sum'
2800
+ ? `"${problem.label}" sums to ${problem.total}`
2801
+ : problem.kind === 'negative-share' || problem.kind === 'split-names-unknown-owner'
2802
+ ? `"${problem.label}" → ${problem.owner}`
2803
+ : `"${problem.label}"`;
2804
+ console.log(` ${wrap(t.owners.problem(problem.kind, detail), 70, ' ')}`);
2805
+ }
2806
+ process.exitCode = 1;
2807
+ }
2808
+
2809
+ console.log();
2810
+ const col = t.owners.columns;
2811
+ const rows = result.owners.map((line) => ({
2812
+ owner: line.owner,
2813
+ spend: formatUsd(line.usd),
2814
+ budget: line.budgetUsd === null ? '—' : formatUsd(line.budgetUsd),
2815
+ calls: n(Math.round(line.calls)),
2816
+ verdict: t.owners.verdict(line.verdict),
2817
+ kind: line.verdict,
2818
+ }));
2819
+ const w = {
2820
+ owner: Math.max(...rows.map((r) => r.owner.length), col.owner.length),
2821
+ spend: Math.max(...rows.map((r) => r.spend.length), col.spend.length),
2822
+ budget: Math.max(...rows.map((r) => r.budget.length), col.budget.length),
2823
+ calls: Math.max(...rows.map((r) => r.calls.length), col.calls.length),
2824
+ };
2825
+ console.log(
2826
+ c.dim(
2827
+ ` ${col.owner.padEnd(w.owner)} ${col.spend.padStart(w.spend)} ` +
2828
+ `${col.budget.padStart(w.budget)} ${col.calls.padStart(w.calls)}`,
2829
+ ),
2830
+ );
2831
+ for (const row of rows) {
2832
+ const tint = row.kind === 'over' ? c.red : row.kind === 'not-measured' ? c.yellow : c.dim;
2833
+ console.log(
2834
+ ` ${row.owner.padEnd(w.owner)} ${row.spend.padStart(w.spend)} ` +
2835
+ `${row.budget.padStart(w.budget)} ${row.calls.padStart(w.calls)} ${tint(row.verdict)}`,
2836
+ );
2837
+ }
2838
+
2839
+ // The 1.37 refusal, applied to people, said in full for each owner it hits.
2840
+ for (const line of result.owners) {
2841
+ if (line.verdict === 'not-measured') {
2842
+ console.log();
2843
+ console.log(` ${c.yellow('!')} ${wrap(t.owners.notMeasured(line.owner), 74, ' ')}`);
2844
+ }
2845
+ }
2846
+
2847
+ console.log();
2848
+ if (result.unallocated.usd > 0) {
2849
+ console.log(
2850
+ ` ${c.yellow('!')} ${wrap(
2851
+ t.owners.unallocated(
2852
+ formatUsd(result.unallocated.usd),
2853
+ report.total.totalUsd > 0 ? pct(result.unallocated.usd / report.total.totalUsd) : '—',
2854
+ result.unallocated.labels.slice(0, 6).join(', '),
2855
+ ),
2856
+ 74,
2857
+ ' ',
2858
+ )}`,
2859
+ );
2860
+ console.log(` ${c.dim(wrap(t.owners.neverSpread(), 72, ' '))}`);
2861
+ } else {
2862
+ console.log(` ${c.dim(t.owners.nothingUnallocated())}`);
2863
+ }
2864
+
2865
+ /**
2866
+ * The shared rules, printed with the report.
2867
+ *
2868
+ * The whole design: the argument then happens about the rule — "why is
2869
+ * search 60/40?" — rather than about the number, which is an argument nobody
2870
+ * can win because nobody can see where the number came from.
2871
+ */
2872
+ if (result.sharedApplied.length > 0) {
2873
+ console.log();
2874
+ console.log(` ${c.bold(t.owners.sharedHeading())}`);
2875
+ for (const { label, split } of result.sharedApplied) {
2876
+ const rule = Object.entries(split)
2877
+ .map(([owner, share]) => `${owner} ${pct(share)}`)
2878
+ .join(', ');
2879
+ console.log(` ${c.dim(t.owners.sharedRule(label, rule))}`);
2880
+ }
2881
+ }
2882
+ console.log();
2883
+ }
2884
+
2885
+ /**
2886
+ * `trazum commitment <log> --floor <usd> --discount <pct> [--months 12]`
2887
+ *
2888
+ * What a committed-use deal would have been worth **on the traffic you
2889
+ * actually had**. Every team that signs one of these is doing arithmetic in a
2890
+ * spreadsheet against a number they guessed, and it is the highest-stakes
2891
+ * instance of exactly the failure this product exists to end — because the
2892
+ * guess is annual and signed.
2893
+ *
2894
+ * Nothing here projects. "On the traffic you actually had, this would have
2895
+ * saved $X" is a measurement; "you will save $X" is a claim about the future
2896
+ * this product has refused at every scale since 1.27.
2897
+ */
2898
+ async function commandCommitment(
2899
+ args: Args,
2900
+ config: TrazumConfig,
2901
+ pricing: PricingCatalogue,
2902
+ t: CliMessages,
2903
+ ): Promise<void> {
2904
+ const path = args.positional[0];
2905
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
2906
+
2907
+ const floorRaw = stringFlag(args, 'floor');
2908
+ const discountRaw = stringFlag(args, 'discount');
2909
+ const floor = floorRaw === undefined ? Number.NaN : Number(floorRaw);
2910
+ const discountInput = discountRaw === undefined ? Number.NaN : Number(discountRaw);
2911
+ if (!Number.isFinite(floor) || floor <= 0 || !Number.isFinite(discountInput) || discountInput <= 0) {
2912
+ throw new Error(t.commitment.needsTerms());
2913
+ }
2914
+ // Written either way in a contract, so read either way: 20 and 0.2 are the
2915
+ // same deal, and refusing one of them would be pedantry with a stack trace.
2916
+ const discount = discountInput > 1 ? discountInput / 100 : discountInput;
2917
+ const months = Number(stringFlag(args, 'months') ?? 12);
2918
+ const terms = { monthlyFloorUsd: floor, discount, months };
2919
+
2920
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
2921
+ /**
2922
+ * Whole calendar months only.
2923
+ *
2924
+ * A partial month replayed against a monthly floor is a shortfall the
2925
+ * traffic never had — the deal would be judged against a fortnight of usage
2926
+ * and a full month of commitment. Dropping them costs an answer; keeping
2927
+ * them would manufacture one.
2928
+ */
2929
+ const byMonth = new Map<string, number>();
2930
+ for (const day of report.spendByDay) {
2931
+ const key = day.day.slice(0, 7);
2932
+ byMonth.set(key, (byMonth.get(key) ?? 0) + day.usd);
2933
+ }
2934
+ const days = new Map<string, Set<string>>();
2935
+ for (const day of report.spendByDay) {
2936
+ const key = day.day.slice(0, 7);
2937
+ const set = days.get(key) ?? new Set<string>();
2938
+ set.add(day.day);
2939
+ days.set(key, set);
2940
+ }
2941
+ const whole = [...byMonth.entries()]
2942
+ .filter(([key]) => {
2943
+ const [y, m] = key.split('-').map(Number);
2944
+ const inMonth = new Date(Date.UTC(y ?? 2026, m ?? 1, 0)).getUTCDate();
2945
+ return (days.get(key)?.size ?? 0) >= inMonth - 2;
2946
+ })
2947
+ .map(([month, usd]) => ({ month, usd }))
2948
+ .sort((a, b) => a.month.localeCompare(b.month));
2949
+
2950
+ const replay = replayCommitment(whole, terms);
2951
+ const coverage = coversTheTerm(replay, terms);
2952
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
2953
+ const pct = (value: number): string => `${(value * 100).toFixed(0)}%`;
2954
+
2955
+ console.log();
2956
+ console.log(c.bold(t.commitment.heading(formatUsd(floor), pct(discount), n(months))));
2957
+ console.log(` ${c.dim(wrap(t.commitment.asIf(), 74, ' '))}`);
2958
+ console.log();
2959
+
2960
+ if (replay.unknown !== null) {
2961
+ console.log(
2962
+ ` ${c.yellow('?')} ${wrap(t.commitment.cannotTell(replay.unknown, n(replay.monthsNeeded ?? 0)), 74, ' ')}`,
2963
+ );
2964
+ console.log();
2965
+ console.log(` ${c.dim(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)))}`);
2966
+ console.log();
2967
+ return;
2968
+ }
2969
+
2970
+ const col = t.commitment.columns;
2971
+ const rows = replay.months.map((m) => ({
2972
+ month: m.month,
2973
+ list: formatUsd(m.listUsd),
2974
+ paid: formatUsd(m.paidUsd),
2975
+ // Signed: every month in this column can go either way, and formatUsd
2976
+ // renders a negative as `$-2,400`, which reads as a typo. The sign carries
2977
+ // the whole meaning here, so it goes where a reader expects it.
2978
+ saving: formatSignedUsd(m.savingUsd),
2979
+ shortfall: m.shortfall,
2980
+ }));
2981
+ const w = {
2982
+ month: Math.max(...rows.map((r) => r.month.length), col.month.length),
2983
+ list: Math.max(...rows.map((r) => r.list.length), col.list.length),
2984
+ paid: Math.max(...rows.map((r) => r.paid.length), col.paid.length),
2985
+ saving: Math.max(...rows.map((r) => r.saving.length), col.saving.length),
2986
+ };
2987
+ console.log(
2988
+ c.dim(
2989
+ ` ${col.month.padEnd(w.month)} ${col.list.padStart(w.list)} ` +
2990
+ `${col.paid.padStart(w.paid)} ${col.saving.padStart(w.saving)}`,
2991
+ ),
2992
+ );
2993
+ for (const row of rows) {
2994
+ const tint = row.shortfall ? c.red : c.dim;
2995
+ console.log(
2996
+ ` ${row.month.padEnd(w.month)} ${row.list.padStart(w.list)} ` +
2997
+ `${row.paid.padStart(w.paid)} ${tint(row.saving.padStart(w.saving))}`,
2998
+ );
2999
+ }
3000
+
3001
+ console.log();
3002
+ console.log(` ${c.bold(t.commitment.net(formatUsd(replay.netUsd), n(replay.months.length)))}`);
3003
+ console.log(` ${c.dim(t.commitment.good(formatUsd(replay.savedInGoodMonthsUsd)))}`);
3004
+ if (replay.shortfallMonths > 0) {
3005
+ console.log(
3006
+ ` ${c.yellow('!')} ${wrap(
3007
+ t.commitment.lost(formatUsd(replay.lostToUnusedFloorUsd), n(replay.shortfallMonths)),
3008
+ 74,
3009
+ ' ',
3010
+ )}`,
3011
+ );
3012
+ } else {
3013
+ console.log(` ${c.dim(t.commitment.noShortfall())}`);
3014
+ }
3015
+
3016
+ console.log();
3017
+ console.log(` ${c.dim(wrap(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)), 74, ' '))}`);
3018
+ if (replay.spread !== null) {
3019
+ console.log(
3020
+ ` ${c.dim(
3021
+ wrap(
3022
+ t.commitment.spread(
3023
+ formatUsd(replay.spread.lowUsd),
3024
+ formatUsd(replay.spread.highUsd),
3025
+ formatUsd(replay.spread.medianUsd),
3026
+ ),
3027
+ 74,
3028
+ ' ',
3029
+ ),
3030
+ )}`,
3031
+ );
3032
+ }
3033
+ // Said, not enforced: a shorter history is a real answer about a shorter
3034
+ // period, and the gap must not go unmarked.
3035
+ if (coverage.short) {
3036
+ console.log();
3037
+ console.log(
3038
+ ` ${c.yellow('!')} ${wrap(t.commitment.shortTerm(n(coverage.covered), n(coverage.ofMonths)), 74, ' ')}`,
3039
+ );
3040
+ }
3041
+ console.log();
3042
+ console.log(` ${c.dim(wrap(t.commitment.neverAForecast(), 74, ' '))}`);
3043
+ console.log();
3044
+ }
3045
+
2737
3046
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
2738
3047
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
2739
3048
  const col = t.models.columns;
@@ -8934,6 +9243,12 @@ async function main(): Promise<void> {
8934
9243
  case 'models':
8935
9244
  commandModels(t, pricing);
8936
9245
  break;
9246
+ case 'commitment':
9247
+ await commandCommitment(args, config, pricing, t);
9248
+ break;
9249
+ case 'owners':
9250
+ await commandOwners(args, config, pricing, t);
9251
+ break;
8937
9252
  case 'semantic':
8938
9253
  await commandSemantic(args, config, pricing, t);
8939
9254
  break;