@trazum/cli 1.80.1 → 1.82.0

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/dist/i18n/en.js CHANGED
@@ -3,8 +3,8 @@ const count = (value) => value.toLocaleString('en-US');
3
3
  /**
4
4
  * A grouped count and its noun, agreeing.
5
5
  *
6
- * `1 calls` and `1 prompts` were reachable on ordinary input — a one-call log, a
7
- * repository with a single prompt — and two messages in this file already did the
6
+ * `1 calls` and `1 prompts` were reachable on ordinary input, a one-call log, a
7
+ * repository with a single prompt, and two messages in this file already did the
8
8
  * agreement by hand while a dozen did not. A helper rather than a dozen ternaries,
9
9
  * so the next message written gets it for free.
10
10
  */
@@ -12,7 +12,7 @@ const plural = (value, one, many = `${one}s`) => `${count(value)} ${value === 1
12
12
  /** "(46 days ago)", or nothing when the age is unknown. */
13
13
  const ago = (days) => days === null ? '' : days === 0 ? ' (today)' : days === 1 ? ' (1 day ago)' : ` (${days} days ago)`;
14
14
  /**
15
- * English catalogue — the source of truth.
15
+ * English catalogue, the source of truth.
16
16
  *
17
17
  * When a message changes here, the other catalogues need the same change.
18
18
  * `test/i18n.test.js` in the core enforces the equivalent guarantee for the
@@ -21,7 +21,7 @@ const ago = (days) => days === null ? '' : days === 0 ? ' (today)' : days === 1
21
21
  export const en = {
22
22
  locale: 'en',
23
23
  numberLocale: 'en-US',
24
- help: (d, bold) => `${bold('trazum')} — cut the cost of your prompts without losing what they ask for.
24
+ help: (d, bold) => `${bold('trazum')}, cut the cost of your prompts without losing what they ask for.
25
25
 
26
26
  ${bold('USAGE')}
27
27
  trazum init [dir] [--dry-run | --yes]
@@ -52,6 +52,8 @@ ${bold('USAGE')}
52
52
  trazum position <usage.jsonl>
53
53
  trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
54
54
  trazum from-otel <file|dir> [--label-from-service] [-o <file>]
55
+ trazum from-litellm <file|dir> [-o <file>]
56
+ trazum from-helicone <file|dir> [-o <file>]
55
57
  trazum switch <usage.jsonl> --to <model> [--migration-usd <n>] [--cases <n>]
56
58
  trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]
57
59
  trazum pulse [--max-stale-hours <n>]
@@ -83,7 +85,7 @@ ${bold('OPTIONS FOR init')}
83
85
  found, arithmetic first.
84
86
 
85
87
  It never invents a threshold. A budget is a policy, so init hands you the
86
- measured figure and leaves the limit to you — a generated config full of
88
+ measured figure and leaves the limit to you: a generated config full of
87
89
  guessed numbers is one nobody trusts.
88
90
 
89
91
  ${bold('OPTIONS FOR conform')}
@@ -91,7 +93,7 @@ ${bold('OPTIONS FOR conform')}
91
93
  detecting one: ${d.contracts.join(', ')}.
92
94
  --json The report as data.
93
95
 
94
- Answers two questions and keeps them apart. Does this document conform —
96
+ Answers two questions and keeps them apart. Does this document conform,
95
97
  required fields, present and the right type, exits 1 when not. And what can a
96
98
  valid document of this shape not answer, with the field that would unlock
97
99
  each.
@@ -102,7 +104,7 @@ ${bold('OPTIONS FOR conform')}
102
104
  ${bold('OPTIONS FOR rollup')}
103
105
  --json The roll-up document as data. See docs/format.md.
104
106
  --html-out <file> Also write the roll-up as one self-contained HTML
105
- file — the team-facing report, for whoever pays
107
+ file, the team-facing report, for whoever pays
106
108
  the bill. Each contributor's gaps stay under that
107
109
  contributor, and what no merge can measure is in
108
110
  the caveat block, impossible to crop.
@@ -110,13 +112,13 @@ ${bold('OPTIONS FOR rollup')}
110
112
  Several people's bills, one roll-up. Each contributor runs
111
113
  \`trazum profile --json\` where their traffic already is; this merges the
112
114
  documents. A format and a merge, not a service: nothing is uploaded and there
113
- is no account — the documents arrive however your team already moves files.
115
+ is no account: the documents arrive however your team already moves files.
114
116
 
115
117
  Most of the output is what the merge could not do. Each contributor's own
116
118
  gaps stay with that contributor rather than being averaged into one figure,
117
119
  the findings that need individual calls are named instead of dropped, and
118
120
  every roll-up of more than one document says that overlap between
119
- contributors is unmeasurable — two people exporting the same traffic double
121
+ contributors is unmeasurable: two people exporting the same traffic double
120
122
  the bill and no merge of summaries can see it.
121
123
 
122
124
  Exits 1 when a contribution was handed over and could not be merged.
@@ -139,11 +141,11 @@ ${bold('OPTIONS FOR switch')}
139
141
  Unlocks the line pricing that evaluation.
140
142
 
141
143
  The decision every what-if serves, priced: what this measured mix costs on
142
- the candidate, the saving with its sign stated, and — with a declared
143
- migration cost — the break-even as division on the measured past, days of
144
+ the candidate, the saving with its sign stated, and, with a declared
145
+ migration cost, the break-even as division on the measured past, days of
144
146
  window attached, never a forecast. The evaluation the switch requires is
145
147
  priced at this log's own mean call, two calls on the incumbent and one on
146
- the candidate per case. What it refuses: any sentence about quality — that
148
+ the candidate per case. What it refuses: any sentence about quality, that
147
149
  verdict belongs to trazum route, and the report ends by printing it.
148
150
 
149
151
  ${bold('OPTIONS FOR ownrate')}
@@ -152,19 +154,42 @@ ${bold('OPTIONS FOR ownrate')}
152
154
  --utilization <0-1> Fraction of the hour actually serving.
153
155
  Defaults to 1.
154
156
 
155
- Your self-hosted model's $/MTok, derived from your own two numbers —
157
+ Your self-hosted model's $/MTok, derived from your own two numbers,
156
158
  division, nothing else: no amortisation, no energy model, no guessed
157
159
  efficiency. Prints the figure and the pricing-overlay snippet to paste
158
160
  into trazum.config.json, so the model you run yourself becomes a
159
161
  first-class row in every report, priced by you and marked as such.
160
162
 
163
+ ${bold('OPTIONS FOR from-helicone')}
164
+ -o, --out <file> Write the usage log there instead of stdout.
165
+
166
+ A Helicone request export, read as a usage log: model, timestamp, label and
167
+ the token counts from each row, and nothing else. The request body, the
168
+ response body and the user id stay in the row. The model that answered is
169
+ what is priced, and rows answered by a different model than the one
170
+ requested are counted. cache_enabled is a flag and never a token split, so
171
+ cache verdicts read "cannot tell". A request id is one call and never a
172
+ conversation, so the records carry no session and the conversation findings
173
+ cannot be answered from this log; that is said on every run.
174
+
175
+ ${bold('OPTIONS FOR from-litellm')}
176
+ -o, --out <file> Write the usage log there instead of stdout.
177
+
178
+ A LiteLLM spend log, read as a usage log: model, timestamp, label, session
179
+ and the token counts from each row, and nothing else. The messages, the
180
+ response, the hashed key, the requester address and the end user stay in the
181
+ row. cache_hit is a flag and never a token split, so cache verdicts read
182
+ "cannot tell" rather than a guessed one. Rows naming no model are counted
183
+ and left out: model_group is a route, not a model. LiteLLM's own spend
184
+ figure is printed beside Trazum's and never merged into it.
185
+
161
186
  ${bold('OPTIONS FOR from-otel')}
162
187
  --label-from-service Label each record with its span's service name,
163
188
  so a per-service bill falls out.
164
189
  -o, --out <file> Write the usage log there instead of stdout.
165
190
 
166
191
  OpenTelemetry GenAI spans, read as a usage log: model, timestamp, label and
167
- the token counts from each gen_ai.* span — and nothing else. Prompt content
192
+ the token counts from each gen_ai.* span, and nothing else. Prompt content
168
193
  and trace ids stay in the span. OTel has no cache TTL split, so cache
169
194
  verdicts read "cannot tell" rather than a guessed one. Non-LLM spans are
170
195
  counted and skipped, said on stderr.
@@ -172,19 +197,19 @@ ${bold('OPTIONS FOR from-otel')}
172
197
  ${bold('OPTIONS FOR from-claude-code')}
173
198
  --label <name> Stamp every record with one label.
174
199
  --label-from-project Label each record with its transcript's project
175
- directory name, verbatim — map it to a workload
200
+ directory name, verbatim, map it to a workload
176
201
  name with the config's \`labels\` block.
177
202
  -o, --out <file> Write the usage log there instead of stdout.
178
203
 
179
204
  Claude Code's transcripts, read as a usage log: model, timestamp, session
180
- and the API's own usage object — the cache TTL split included — and
205
+ and the API's own usage object, the cache TTL split included, and
181
206
  nothing else. No message text, no paths, no branches cross the
182
207
  conversion. One API call is written as one line per content block, so
183
208
  lines are collapsed by request id; what was collapsed or passed over is
184
209
  said on stderr, never silently.
185
210
 
186
211
  ${bold('OPTIONS FOR position')}
187
- --html-out <file> The position as one self-contained page — the
212
+ --html-out <file> The position as one self-contained page, the
188
213
  same sentences the terminal prints, caveats
189
214
  first, for the person who does not run CLIs.
190
215
  --json The position document, contract-checked like
@@ -203,7 +228,7 @@ ${bold('OPTIONS FOR pulse')}
203
228
  --json The report as data.
204
229
 
205
230
  Did the things that are supposed to run, run? \`watch --once\` is built for a
206
- scheduler, and its state file is read by exactly one thing — the next cycle.
231
+ scheduler, and its state file is read by exactly one thing, the next cycle.
207
232
  So nothing could tell you the watcher had stopped, because the thing that
208
233
  would tell you was the thing that stopped.
209
234
 
@@ -211,8 +236,8 @@ ${bold('OPTIONS FOR pulse')}
211
236
  is your CI: a step running this on the schedule you already have turns a dead
212
237
  cron into a red build, without Trazum holding anybody's metrics.
213
238
 
214
- Never gates on a first run that never happened — that has no cadence to be
215
- late against — and never on how far the measurements reach, which is a
239
+ Never gates on a first run that never happened: that has no cadence to be
240
+ late against, and never on how far the measurements reach, which is a
216
241
  provider reporting on its own schedule rather than a job that failed.
217
242
 
218
243
  ${bold('OPTIONS FOR bench')}
@@ -227,7 +252,7 @@ ${bold('OPTIONS FOR bench')}
227
252
  --against: how much regression is too much is a
228
253
  policy, and this tool does not write yours.
229
254
  --json The measurements as data. The shape never changes
230
- with the gate flags — a verdict is the exit code
255
+ with the gate flags: a verdict is the exit code
231
256
  and sentences on stderr, the way check gates.
232
257
 
233
258
  Measures this machine: the standard workloads, one shot each, wall time and
@@ -261,7 +286,7 @@ ${bold('OPTIONS FOR feedback')}
261
286
  (none)
262
287
 
263
288
  Prints where to report a wrong optimisation, a bug, a question or a security
264
- problem — and a blank issue with the version, runtime and platform already
289
+ problem, and a blank issue with the version, runtime and platform already
265
290
  filled in, printed in full first so nothing travels you have not read.
266
291
 
267
292
  It sends nothing. Trazum has no telemetry: no ping, no install hook, no
@@ -270,17 +295,17 @@ ${bold('OPTIONS FOR feedback')}
270
295
 
271
296
  ${bold('OPTIONS FOR gateway')}
272
297
  --on-cannot-tell <policy> Required, no default: fail-open or fail-closed.
273
- What happens when the gateway cannot judge a call
274
- — no budget, nothing measured, an unpriced model.
298
+ What happens when the gateway cannot judge a call:
299
+ no budget, nothing measured, an unpriced model.
275
300
  --port <n> | --socket <p> Where to listen. Loopback only, always.
276
301
  --log <usage.jsonl> The usage log the limits policy is measured
277
- against, read once at start — same flag as
302
+ against, read once at start, same flag as
278
303
  serve's, same reason: label and session spend
279
304
  live in a usage log, not in the store.
280
305
 
281
306
  Stands between your SDK and the provider, speaking their wire format, so no
282
307
  code changes. Usage is measured from the provider's own response as it comes
283
- back — no export, no connector lag, no missing day.
308
+ back, no export, no connector lag, no missing day.
284
309
 
285
310
  It refuses and never substitutes: a call over budget gets HTTP 402 with the
286
311
  cheaper alternatives named. Substitution happens only where you wrote it down
@@ -297,7 +322,7 @@ ${bold('OPTIONS FOR experiment')}
297
322
  honoured.
298
323
 
299
324
  Judges recorded outcomes and cost together. Three-valued: A wins, B wins, or
300
- not separable — with the number of outcomes per arm that would settle it, so
325
+ not separable, with the number of outcomes per arm that would settle it, so
301
326
  "run it longer" is an instruction rather than a shrug. Nothing is promoted.
302
327
 
303
328
  ${bold('OPTIONS FOR quality')}
@@ -312,7 +337,7 @@ ${bold('OPTIONS FOR quality')}
312
337
 
313
338
  A before-and-after rather than an experiment, so it reports "cannot tell"
314
339
  whenever the model mix, the call volume or the outcome coverage moved across
315
- the boundary — the prompt is not the only variable and it says so.
340
+ the boundary: the prompt is not the only variable and it says so.
316
341
 
317
342
  ${bold('OPTIONS FOR semantic')}
318
343
  --yes Required to send anything. Without it the command
@@ -333,14 +358,14 @@ ${bold('OPTIONS FOR commitment')}
333
358
 
334
359
  Replays measured whole months against the deal's terms. Both directions are
335
360
  priced: the months that cleared the floor, and what the floor cost in the
336
- months that fell short — kept as its own figure, because netted into the
361
+ months that fell short, kept as its own figure, because netted into the
337
362
  saving it disappears. An as-if calculation about the past, never a forecast.
338
363
 
339
364
  ${bold('OPTIONS FOR report')}
340
365
  --year <yyyy> Required. Which year to assemble.
341
366
  --json The record as data.
342
367
 
343
- Everything comes from the store and the plans you already keep — nothing is
368
+ Everything comes from the store and the plans you already keep: nothing is
344
369
  computed that cannot be checked against a document that already exists.
345
370
  Months with no record are named rather than filled, promises are kept in
346
371
  three outcomes rather than two, and the report lists what it cannot say.
@@ -365,14 +390,14 @@ ${bold('OPTIONS FOR eval')}
365
390
  --concurrency <n> Calls in flight at once. Default: 3.
366
391
  --export promptfoo Write a promptfoo suite instead of running anything:
367
392
  both prompts, every case, no API key needed and no
368
- call made. The assertions are yours — this exists
393
+ call made. The assertions are yours: this exists
369
394
  for the question agreement cannot answer.
370
395
  -o, --out <file> Where to write it. Defaults to stdout.
371
396
 
372
397
  Runs both prompt versions over your cases and reports whether the
373
398
  optimisation changed the answers. Costs THREE provider calls per case: the
374
399
  original twice, to measure the model's own run-to-run variance, and the
375
- optimised once. That baseline is the yardstick — without it, a divergence
400
+ optimised once. That baseline is the yardstick, without it, a divergence
376
401
  figure means nothing. Exits with code 1 when the answers genuinely diverge.
377
402
 
378
403
  ${bold('OPTIONS FOR rank')}
@@ -434,7 +459,7 @@ ${bold('OPTIONS FOR optimize')}
434
459
  --all-labels With --from-log: every prompt in the config's
435
460
  "labels" map, optimised and priced against its
436
461
  own measured traffic, ranked by what the change
437
- is worth — plus the mismatches in both
462
+ is worth, plus the mismatches in both
438
463
  directions (mapped prompts with no traffic,
439
464
  traffic with no mapped prompt).
440
465
  --from-log <usage.jsonl> Measure the three figures above from a usage log
@@ -448,7 +473,7 @@ ${bold('OPTIONS FOR optimize')}
448
473
  --batch The work tolerates latency (Batch API, 50% off).
449
474
  --disable <id,id> Turn off specific rules (see "trazum rules").
450
475
  --suggest Ask the LLM for phrase-level rewrites and list them
451
- with what each saves. Changes nothing on its own —
476
+ with what each saves. Changes nothing on its own,
452
477
  every proposal is checked against your prompt first
453
478
  and dropped if it does not survive.
454
479
  --apply-suggestions Take them. Only with --suggest; alone it is an error
@@ -469,7 +494,7 @@ ${bold('OPTIONS FOR optimize')}
469
494
  --tokens-only Report the token saving and no money at all. The
470
495
  default inside Claude Code, Codex or Cursor, where
471
496
  a subscription means there is no bill to reduce.
472
- --cost Show the money even there — the host says where
497
+ --cost Show the money even there: the host says where
473
498
  Trazum runs, not where your prompt goes.
474
499
  --prompt <name> Which marked prompt to optimise, when a source file
475
500
  holds more than one. See "trazum where".
@@ -496,7 +521,7 @@ ${bold('OPTIONS FOR check')}
496
521
  --baseline Gate on the recorded cost baseline. On by default whenever
497
522
  the config declares one, so CI needs no argument; the useful
498
523
  spelling is --no-baseline, which skips it for one run.
499
- --files-from <file|-> Check only the files listed, one path per line — the shape
524
+ --files-from <file|-> Check only the files listed, one path per line, the shape
500
525
  git diff --name-only produces, so a pre-commit hook is one
501
526
  pipe: git diff --cached --name-only | trazum check --files-from -
502
527
  Non-prompt paths and deletions are dropped and counted out
@@ -509,7 +534,7 @@ ${bold('OPTIONS FOR check')}
509
534
 
510
535
  ${bold('OPTIONS FOR baseline')}
511
536
  Records what the prompts in a directory cost right now, to a file you commit.
512
- Then "check" fails the build when the repository drifts past it — the question
537
+ Then "check" fails the build when the repository drifts past it: the question
513
538
  budgets cannot answer, because a repository at 95% of every budget passes
514
539
  forever while a pull request adds four hundred tokens across a dozen files.
515
540
 
@@ -518,7 +543,7 @@ ${bold('OPTIONS FOR baseline')}
518
543
  --model, --calls, --output-tokens, --cache-hit-rate, --batch
519
544
  The scenario the monthly figure is recorded under. It is
520
545
  recorded so a later comparison can say whether the money is
521
- comparable — the gate itself is in tokens, so a repriced
546
+ comparable: the gate itself is in tokens, so a repriced
522
547
  model never fails a build on its own.
523
548
  --exact-tokens Exact counts (needs ANTHROPIC_API_KEY).
524
549
  --json Result as JSON.
@@ -527,7 +552,7 @@ ${bold('OPTIONS FOR baseline')}
527
552
  writing the thing you would fix the failure with is a loop.
528
553
 
529
554
  Given a directory it checks every prompt inside it against the "budgets"
530
- patterns in ${bold('trazum.config.json')} — one CI step for a whole repository of
555
+ patterns in ${bold('trazum.config.json')}: one CI step for a whole repository of
531
556
  prompts. A file no pattern covers is listed as unbudgeted rather than
532
557
  skipped quietly, and a run where nothing at all was budgeted is an error:
533
558
  "0 failures" from a check that measured nothing is the most misleading
@@ -537,7 +562,7 @@ ${bold('OPTIONS FOR ladder')}
537
562
  --since <when> Read only calls in this window. A UTC day
538
563
  --until <when> (2026-08-14), a full ISO 8601 timestamp, a
539
564
  relative window (7d, 24h) or "now". Calls with no
540
- "ts" cannot be placed and are left out — counted
565
+ "ts" cannot be placed and are left out, counted
541
566
  out loud, never dropped silently.
542
567
  --label <name> Judge one workload's ladder rather than the whole
543
568
  log. A label that matches nothing is an error
@@ -552,9 +577,9 @@ ${bold('OPTIONS FOR owners')}
552
577
  ${bold('OPTIONS FOR profile')}
553
578
  --against <log.jsonl> Compare this bill to a previous log. Positive
554
579
  means the bill grew; drivers are ranked by their
555
- contribution to the change. No period is assumed —
580
+ contribution to the change. No period is assumed,
556
581
  judge the call counts before judging the money.
557
- --label <name> Profile only the calls carrying this label — the
582
+ --label <name> Profile only the calls carrying this label, the
558
583
  drill-down once the full report named a suspect.
559
584
  A label that matches nothing is an error naming
560
585
  the labels that exist. With --against, both logs
@@ -568,16 +593,16 @@ ${bold('OPTIONS FOR profile')}
568
593
  an error, not a flag that silently gates nothing.
569
594
  --max-cache-loss-usd <n> Exit 1 when caching added more than n dollars to
570
595
  this bill. Reads the worst case when the log did
571
- not record the write TTL — a gate reading the
596
+ not record the write TTL: a gate reading the
572
597
  flattering half would pass the bills it exists
573
- to catch — and says which claim fired.
598
+ to catch, and says which claim fired.
574
599
  --max-day-usd <n> Fail when any single UTC day inside the log spent
575
600
  more than this. A month under budget can hide the
576
601
  afternoon a loop burned a quarter of it. A log
577
602
  with no timestamps fails: not measured is not
578
603
  under budget.
579
604
  --max-session-usd <n> Fail when any single conversation in the log
580
- cost more than this — the unit an agent product
605
+ cost more than this, the unit an agent product
581
606
  blows up in. A log with no sessions fails: not
582
607
  measured is not under budget.
583
608
  --since <when> Profile only calls at or after this moment. A UTC
@@ -585,22 +610,22 @@ ${bold('OPTIONS FOR profile')}
585
610
  relative window (7d, 24h) or "now";
586
611
  --until with a bare date includes that whole day.
587
612
  Calls with no "ts" cannot be placed and are left
588
- out — counted out loud, never dropped silently.
613
+ out, counted out loud, never dropped silently.
589
614
  With --against, both logs get the same window.
590
615
  --what-if <model> Price these exact calls on another model. The
591
- same token counts at a different rate card —
616
+ same token counts at a different rate card,
592
617
  multiplication, not advice, and it says so.
593
618
  Calls larger than that model's context window
594
619
  are named as impossible, not priced as cheap.
595
620
  --markdown-out <file> Also write the report as Markdown, for a CI job
596
621
  summary or a pull request comment.
597
622
  --html-out <file> Also write the report as one self-contained HTML
598
- file — the one to email to whoever pays the bill.
623
+ file, the one to email to whoever pays the bill.
599
624
  Same figures as --json, caveats rendered as
600
625
  prominently as the totals they qualify.
601
626
  --csv-shape <shape> Which table --csv-out writes: slice (default),
602
627
  day, hour, or model-day (one row per day and
603
- model — charts the mix moving). One row shape
628
+ model, charts the mix moving). One row shape
604
629
  per file, so nothing has to be filtered before
605
630
  it can be summed.
606
631
  --csv-out <file> Also write the report as CSV, one row per label
@@ -611,20 +636,20 @@ ${bold('OPTIONS FOR profile')}
611
636
  --pricing <file> Local price overlay, as everywhere else.
612
637
  --json The full report as data, including the levers.
613
638
 
614
- Takes a log file or a directory of them — rotated daily logs are read in
639
+ Takes a log file or a directory of them, rotated daily logs are read in
615
640
  name order as one bill, and how many were read is stated. Gzipped files
616
641
  (.jsonl.gz and the rest) are read too, because that is what a rotated log
617
642
  looks like a day later; one that will not decompress is an error naming the
618
643
  file, never a bill quietly missing a day.
619
644
 
620
645
  Reads what the provider actually charged. Optional fields unlock findings:
621
- "label" (which workload), "session" (which conversation — grouped by, never
646
+ "label" (which workload), "session" (which conversation, grouped by, never
622
647
  printed), "stop_reason"/"finish_reason" (answers cut off at max_tokens).
623
648
 
624
649
  ${bold('OPTIONS FOR plan')}
625
650
  --min-usd <n> Leave out actions worth less than n dollars. How
626
651
  many were left out is stated, never silent.
627
- -o, --out <file> Save the plan as dated JSON — the file
652
+ -o, --out <file> Save the plan as dated JSON: the file
628
653
  "trazum verify" will later hold it to.
629
654
  --markdown-out <file> Also write the plan as Markdown, for a CI job
630
655
  summary or a pull request comment.
@@ -633,8 +658,8 @@ ${bold('OPTIONS FOR plan')}
633
658
 
634
659
  Reads a usage log and turns the report's findings into a ranked plan: route
635
660
  this, batch that, fix the truncation pair, look at the cache. The money is
636
- composed correctly — route and batch on the same slice arrive combined,
637
- never summed — and every action names what the log cannot confirm, because
661
+ composed correctly, route and batch on the same slice arrive combined,
662
+ never summed, and every action names what the log cannot confirm, because
638
663
  a plan that hides its assumptions is advice pretending to be arithmetic.
639
664
  Projected savings and money already spent are separate totals throughout.
640
665
 
@@ -647,8 +672,8 @@ ${bold('OPTIONS FOR serve')}
647
672
  the store; without this, every ceiling in
648
673
  "limits" answers cannot-tell.
649
674
 
650
- Answers the two questions that matter at call time — what will this cost,
651
- and is there budget left — in single-digit milliseconds, so an agent or a
675
+ Answers the two questions that matter at call time, what will this cost,
676
+ and is there budget left, in single-digit milliseconds, so an agent or a
652
677
  wrapper can ask before it spends rather than reading a report afterwards.
653
678
 
654
679
  POST /cost with {"model": "...", "inputTokens": n, "outputTokens": n};
@@ -660,7 +685,7 @@ ${bold('OPTIONS FOR serve')}
660
685
  It listens on 127.0.0.1 and nowhere else, and there is no flag to change
661
686
  that: a cost oracle on a network interface holds a company's spend, its
662
687
  model mix and its budgets, and answers whoever asks. There is no auth for
663
- the same reason there is no --host — a token checked over loopback is
688
+ the same reason there is no --host: a token checked over loopback is
664
689
  theatre, and the honest posture is a surface small enough not to need one.
665
690
 
666
691
  With no store and no budget it still prices the call and says the budget
@@ -679,15 +704,15 @@ ${bold('OPTIONS FOR watch')}
679
704
  instead of the store.
680
705
  --json The cycle as data: crossings, abstentions, gap.
681
706
 
682
- Evaluates the spend gates from your config — maxUsd, maxDayUsd,
683
- maxCacheLossUsd — against what has been measured, and tells you the
707
+ Evaluates the spend gates from your config, maxUsd, maxDayUsd,
708
+ maxCacheLossUsd, against what has been measured, and tells you the
684
709
  afternoon it happens rather than three weeks later. Exits 1 when something
685
710
  crossed, so cron mails it and CI fails.
686
711
 
687
712
  An alert fires on a measured crossing and never on a projection: "you have
688
713
  spent $412 of a $400 budget" is a fact and "you will exceed" is a forecast,
689
714
  which this tool does not make at any window length. A day still being
690
- measured is reported as not yet judgeable rather than passed — but a day
715
+ measured is reported as not yet judgeable rather than passed, but a day
691
716
  already over budget fires whatever the hour, because it does not become less
692
717
  over budget at midnight.
693
718
 
@@ -706,8 +731,8 @@ ${bold('OPTIONS FOR store')}
706
731
 
707
732
  Says what the local store holds: how many measurements, over what span, per
708
733
  provider, and what a prune would take. The store keeps aggregates and
709
- billing fields — never prompt text, never completion text, never a
710
- credential — so it is a file a team can back up without a privacy review.
734
+ billing fields, never prompt text, never completion text, never a
735
+ credential, so it is a file a team can back up without a privacy review.
711
736
 
712
737
  Pruning is the one operation here that destroys something, so it refuses to
713
738
  run without a retention policy: set "store": {"keepDays": 90} in the config
@@ -722,7 +747,7 @@ ${bold('OPTIONS FOR connect')}
722
747
  variable the key would come from. Sends nothing
723
748
  and needs no credential.
724
749
  --payload <file> Price a usage payload you already have, instead of
725
- pulling one. No credential, no network — the same
750
+ pulling one. No credential, no network, the same
726
751
  arithmetic on the same shape.
727
752
  --store Keep what was pulled in the local store, so the
728
753
  next run does not download it again and "trazum
@@ -740,8 +765,8 @@ ${bold('OPTIONS FOR connect')}
740
765
 
741
766
  These APIs serve sums over a window, not one row per call, so a connected
742
767
  report is a restricted one and says so: the totals, the model split, the day
743
- series and the cache verdict are all available, and the per-call findings —
744
- input shapes, truncation retries, conversations, context pressure — are
768
+ series and the cache verdict are all available, and the per-call findings,
769
+ input shapes, truncation retries, conversations, context pressure, are
745
770
  listed as unavailable with what would unlock them. A rate limit, a page cap
746
771
  or an expired cursor returns what arrived with the gap named, never a total
747
772
  that quietly describes less traffic than you asked about.
@@ -750,15 +775,15 @@ ${bold('OPTIONS FOR history')}
750
775
  --store Build the series from the local store instead of
751
776
  a directory of stored reports. Bucketed sources
752
777
  carry no label, so the label series is absent and
753
- said to be — the model-share and cache-share
778
+ said to be: the model-share and cache-share
754
779
  series are what a series exists for, and both
755
780
  work.
756
781
  --markdown-out <file> Also write the series as Markdown, for a CI job
757
782
  summary or a pull request comment.
758
783
  --json The history as data.
759
784
 
760
- Takes a directory of stored reports — the --json documents profile already
761
- writes — plus any saved plans beside them, and builds the series no
785
+ Takes a directory of stored reports, the --json documents profile already
786
+ writes, plus any saved plans beside them, and builds the series no
762
787
  pairwise comparison can see: a workload climbing a little every period, a
763
788
  model share rising since a date, a cache share decaying slowly enough that
764
789
  no single week's report called it a finding, and the same action planned
@@ -770,7 +795,7 @@ ${bold('OPTIONS FOR verify')}
770
795
  --against <log|dir> The newer usage log the plan is held to. Required.
771
796
  --gate Exit 1 when an action did not produce what the
772
797
  plan promised, or its fields stopped being
773
- recorded — "not recorded" must not read as
798
+ recorded, "not recorded" must not read as
774
799
  "fixed". A vanished workload fails nothing.
775
800
  --markdown-out <file> Also write the verdicts as Markdown, for a CI
776
801
  job summary or a pull request comment.
@@ -778,7 +803,7 @@ ${bold('OPTIONS FOR verify')}
778
803
  --json The verification as data.
779
804
 
780
805
  Holds a saved plan to the log that came after it, with three outcomes and
781
- never two: the change arrived, it did not, or it cannot be told — because
806
+ never two: the change arrived, it did not, or it cannot be told, because
782
807
  the workload vanished, the fields the detection needs stopped being
783
808
  recorded, or tokens cannot say which tier billed them. Differences carry
784
809
  the world's measured movement (calls, output per call) from the plan's own
@@ -797,7 +822,7 @@ ${bold('OPTIONS FOR route')}
797
822
 
798
823
  Reads a usage log, finds the slice where routing to a cheaper model is worth
799
824
  the most, and measures whether that model still does the job. The same prompt
800
- goes to both, and the original runs twice per case — so the verdict is judged
825
+ goes to both, and the original runs twice per case, so the verdict is judged
801
826
  against that model's own variance rather than a threshold somebody picked.
802
827
 
803
828
  Costs three provider calls per case and needs TRAZUM_LLM_* configured.
@@ -824,7 +849,7 @@ ${bold('OPTIONS FOR diff')}
824
849
  is given: deciding that growth is unacceptable is your call, not ours.
825
850
 
826
851
  ${bold('trazum where')}
827
- Says which provider a file's prompts are actually sent to, and how it knows —
852
+ Says which provider a file's prompts are actually sent to, and how it knows,
828
853
  an SDK import, a base URL, a quoted model id, or "model=" on a trazum:prompt
829
854
  marker. Every answer names the line it came from.
830
855
 
@@ -836,7 +861,7 @@ ${bold('trazum where')}
836
861
  are all called through the OpenAI SDK with a different base_url, so treating
837
862
  that as a contradiction would refuse to price an ordinary client.
838
863
 
839
- With no file, it reports only which tool Trazum is running inside — and warns
864
+ With no file, it reports only which tool Trazum is running inside, and warns
840
865
  when that tool bills by subscription, because a monthly saving is arithmetic
841
866
  about tokens there, not money you get back.
842
867
 
@@ -848,14 +873,14 @@ ${bold('CONFIG FILE')}
848
873
  usage { model, callsPerMonth, avgOutputTokens, cacheHitRate, batchEligible }
849
874
  budgets { "prompts/**": 2000, "prompts/system.txt": 4000 }
850
875
  baseline { "path": "trazum.baseline.json", "maxGrowthTokens": 0, "maxGrowthPct": 5 }
851
- pricing "./prices.json" — local price corrections, see below
852
- labels { "support-rag": "prompts/support.txt" } — which prompt file each
876
+ pricing "./prices.json": local price corrections, see below
877
+ labels { "support-rag": "prompts/support.txt" }: which prompt file each
853
878
  usage-log label sends, so "trazum profile" can read the file and
854
879
  say why a failing cache fails
855
- spend { "maxUsd": 200, "byLabel": { "chat": 40 } } — money budgets for
880
+ spend { "maxUsd": 200, "byLabel": { "chat": 40 } }: money budgets for
856
881
  "trazum profile", in dollars. A budgeted label with no calls in
857
882
  the log is reported as not measured, never as a pass
858
- limits { "dayUsd": 25, "sessionUsd": 1.5, "byLabel": { "chat": 5 } } —
883
+ limits { "dayUsd": 25, "sessionUsd": 1.5, "byLabel": { "chat": 5 } }:
859
884
  the enforcement policy: USD ceilings judged before a call is
860
885
  made, at whichever door it arrives (the gateway's 402, "serve",
861
886
  spend_guard over MCP). Separate from "spend" because a report
@@ -864,17 +889,17 @@ ${bold('CONFIG FILE')}
864
889
  outage written as a policy
865
890
  owners { "patterns": { "payments": ["billing-*"] },
866
891
  "shared": { "search": { "payments": 0.6, "support": 0.4 } },
867
- "budgets": { "payments": 400 } } — whose budget each workload
892
+ "budgets": { "payments": 400 } }: whose budget each workload
868
893
  lands on. Spend matching no owner is its own line and is NEVER
869
894
  divided between the others; a shared split must sum to 1, and the
870
895
  rule travels with the report so the argument is about the rule
871
896
  ladders { "support": { "tiers": ["claude-haiku-4-5", "claude-opus-5"],
872
- "escalateOn": ["escalated"] } } — cheap model first, escalate a
897
+ "escalateOn": ["escalated"] } }: cheap model first, escalate a
873
898
  recorded failure to a dearer one. Both fields required.
874
899
  "trazum ladder <log>" prints the break-even escalation rate
875
900
  beside the measured one: an escalation pays twice, so above that
876
901
  rate the ladder costs more than never having built it
877
- outcomes { "values": ["resolved", "escalated"], "success": ["resolved"] } —
902
+ outcomes { "values": ["resolved", "escalated"], "success": ["resolved"] }:
878
903
  your own vocabulary for what happened, and which of it counts as
879
904
  a win. Both required: which words mean success is a judgement
880
905
  about your product rather than your bill, and this tool has no
@@ -882,27 +907,27 @@ ${bold('CONFIG FILE')}
882
907
  value in a log that "values" never declares is named as
883
908
  undeclared, never counted as a failure
884
909
  waive [{ "gate": "maxUsd", "reason": "August migration", "until":
885
- "2026-09-15" }] — a gate failure decided about, on the record.
910
+ "2026-09-15" }]: a gate failure decided about, on the record.
886
911
  All three fields required: a waiver with no end date is a
887
912
  finding deleted with extra steps. Waived failures still print,
888
913
  and the day the waiver expires the gate fails again
889
914
 
890
915
  Flags beat the config; the config beats the defaults. Budgets resolve to the
891
- most specific matching pattern — most literal characters wins. A boolean the
916
+ most specific matching pattern: most literal characters wins. A boolean the
892
917
  config switched on comes back off with --no-<flag>, e.g. --no-batch.
893
918
 
894
919
  ${bold('budgets')} is a ceiling; ${bold('baseline')} is a gate. One asks whether a file fits,
895
920
  the other whether the repository got worse than the commit somebody recorded
896
921
  with "trazum baseline". A repository at 95% of every budget passes forever
897
922
  while a pull request adds four hundred tokens across a dozen files. With
898
- baseline in the config, "check" on a directory reads it and gates on it — no
923
+ baseline in the config, "check" on a directory reads it and gates on it, no
899
924
  flag, because a gate you have to remember to pass an argument to runs in the
900
925
  author's terminal and not in CI. Thresholds are in tokens, never dollars: a
901
926
  repriced model would otherwise fail a build for a change nobody made.
902
927
 
903
928
  A config that will not validate is an error, including an unknown key. A
904
929
  lenient parser would silently restore defaults, and for a budget the default
905
- is "no budget" — a green build for a prompt nobody measured.
930
+ is "no budget", a green build for a prompt nobody measured.
906
931
 
907
932
  --config <file> Use this config instead of searching for one.
908
933
 
@@ -926,7 +951,7 @@ ${bold('PRICES')}
926
951
  --pricing-live Take prices from OpenRouter instead of the bundled
927
952
  table: today's figures for hundreds of models across
928
953
  dozens of providers. Opt-in, because it is a network
929
- call — the deterministic core never makes one.
954
+ call: the deterministic core never makes one.
930
955
  A --pricing file wins over this.
931
956
 
932
957
  What that source does not publish is whether a model
@@ -950,7 +975,7 @@ ${bold('OPTIONAL LLM')}
950
975
 
951
976
  ${bold('LANGUAGE')}
952
977
  The report language follows --locale, then TRAZUM_LOCALE, then LANG, and last
953
- the config file — so a project can set the language its CI logs read in
978
+ the config file, so a project can set the language its CI logs read in
954
979
  without overriding the language of whoever is at the keyboard. It changes the
955
980
  report only: the same prompt always optimises the same way.
956
981
 
@@ -970,7 +995,7 @@ ${bold('EXAMPLES')}
970
995
  used: (hits, misses) => `Suggestions: ${hits} from cache, ${misses} asked. Cached answers are what the model said last time; --clear-suggestion-cache to start over.`,
971
996
  },
972
997
  errors: {
973
- livePricingFailed: (url, detail) => `Could not load live prices from ${url}: ${detail}. The bundled prices are still there — drop --pricing-live to use them.`,
998
+ livePricingFailed: (url, detail) => `Could not load live prices from ${url}: ${detail}. The bundled prices are still there. Drop --pricing-live to use them.`,
974
999
  optionNeedsValue: (name) => `Option --${name} needs a value.`,
975
1000
  mustBeNonNegative: (name, raw) => `--${name} must be a non-negative number (received: "${raw}").`,
976
1001
  inputTooLarge: (source, size, limit) => `${source} is ${count(size)} characters, past the ${count(limit)}-character ceiling for a prompt. Raise it deliberately with --max-input <chars> if this input really is one.`,
@@ -978,11 +1003,11 @@ ${bold('EXAMPLES')}
978
1003
  fractionFlag: (name, raw) => `--${name} is a fraction between 0 and 1 (received: ${raw}). The config refuses the same value the same way.`,
979
1004
  badLevel: (received) => `--level must be "safe" or "aggressive" (received: "${received}").`,
980
1005
  allLabelsNeedsLog: () => '--all-labels ranks prompts by measured traffic, so it needs --from-log <usage.jsonl>. Without a log every saving would be multiplied by the same typed guess, which ranks prompts by length and calls it a priority.',
981
- allLabelsNeedsMap: () => '--all-labels reads the "labels" map in trazum.config.json — label to prompt file — and this config has none. Map at least one workload to its prompt.',
1006
+ allLabelsNeedsMap: () => '--all-labels reads the "labels" map in trazum.config.json, label to prompt file, and this config has none. Map at least one workload to its prompt.',
982
1007
  fromLogConflict: (flag) => `--from-log measures the figure --${flag} types, and merging a measurement with a guess produces a number that is neither. Pass one or the other.`,
983
1008
  fromLogNeedsLabel: (available) => `--from-log needs to know which workload this prompt is: pass --label, or map the prompt file under "labels" in trazum.config.json. Labels with traffic in this log: ${available}.`,
984
1009
  fromLogAmbiguousLabel: (target, labels) => `${target} is mapped to more than one label in trazum.config.json (${labels}), so --from-log cannot pick one silently. Pass --label.`,
985
- fromLogLabelEmpty: (label, available) => `No priced call in this log carries the label "${label}", so there is nothing to measure — a zero-call profile would price this change as worthless rather than as unmeasured. Labels with traffic: ${available}.`,
1010
+ fromLogLabelEmpty: (label, available) => `No priced call in this log carries the label "${label}", so there is nothing to measure: a zero-call profile would price this change as worthless rather than as unmeasured. Labels with traffic: ${available}.`,
986
1011
  unknownRuleInDisable: (id) => `Unknown rule in --disable: "${id}". Full list: trazum rules`,
987
1012
  unknownCommand: (command) => `Unknown command: "${command}". Try "trazum --help".`,
988
1013
  missingInputFile: () => 'Missing input file. Use "-" to read from standard input.',
@@ -996,12 +1021,12 @@ ${bold('EXAMPLES')}
996
1021
  * Named, and told what it cannot do rather than merely that it will not.
997
1022
  *
998
1023
  * The alternative on offer has to be somebody else's tooling, because
999
- * Trazum has none for this family — saying so is the whole refusal. A
1024
+ * Trazum has none for this family, saying so is the whole refusal. A
1000
1025
  * refusal never arrives bare.
1001
1026
  */
1002
1027
  exactTokensWrongFamily: (model, provider) => `--exact-tokens counts with Anthropic's endpoint, which counts Claude's tokenizer${provider === null
1003
- ? `, and the catalogue records no provider for "${model}" — so which tokenizer it uses is not something Trazum knows`
1004
- : `, and ${model} is a model from ${provider}`}. Counting it there would either be refused upstream or return a number for a different tokenizer, and this tool will not label that exact. Drop --exact-tokens for the estimate — which is honest about being one — or count with ${provider === null ? "that model's" : provider + "'s"} own tooling.`,
1028
+ ? `, and the catalogue records no provider for "${model}", so which tokenizer it uses is not something Trazum knows`
1029
+ : `, and ${model} is a model from ${provider}`}. Counting it there would either be refused upstream or return a number for a different tokenizer, and this tool will not label that exact. Drop --exact-tokens for the estimate, which is honest about being one, or count with ${provider === null ? "that model's" : provider + "'s"} own tooling.`,
1005
1030
  checkNeedsMaxTokens: () => 'trazum check needs --max-tokens <n>.',
1006
1031
  evalNeedsCases: () => 'trazum eval needs --cases <file>.',
1007
1032
  unknownExportFormat: (received, allowed) => `Unknown export format "${received}". Available: ${allowed}.`,
@@ -1019,9 +1044,15 @@ ${bold('EXAMPLES')}
1019
1044
  },
1020
1045
  report: {
1021
1046
  inputTokens: () => 'Input tokens',
1022
- estimated: (offFamily) => offFamily === null
1023
- ? ' (estimated, ±10%)'
1024
- : ` (estimated — the counter is calibrated on Claude, not ${offFamily})`,
1047
+ estimated: (offFamily, band, measuredOff) => {
1048
+ if (offFamily === null)
1049
+ return ` (estimated, ±${band}%)`;
1050
+ return measuredOff === null
1051
+ ? ` (estimated: the counter is calibrated on Claude, not ${offFamily}, and nobody has`
1052
+ + ' measured how far off it is there)'
1053
+ : ` (estimated: the counter is calibrated on Claude, not ${offFamily}, where it has`
1054
+ + ` measured up to ${measuredOff}% out)`;
1055
+ },
1025
1056
  exactCount: () => ' (exact count)',
1026
1057
  rulesApplied: () => 'Rules applied',
1027
1058
  nothingToTrim: () => ' No rule found anything to trim.',
@@ -1030,12 +1061,12 @@ ${bold('EXAMPLES')}
1030
1061
  // detected: guessing the prompt's language is one more thing to get wrong,
1031
1062
  // and naming the coverage cannot be wrong.
1032
1063
  dictionaryCoverage: (languages) => ` The phrase dictionaries cover ${languages}. A prompt in another language `
1033
- + 'is not necessarily efficient — it may just be one Trazum cannot read yet.',
1064
+ + 'is not necessarily efficient: it may just be one Trazum cannot read yet.',
1034
1065
  dictionaryUnreviewed: (languages) => ` Of those, ${languages} carry entries nobody here reads: written by the same `
1035
1066
  + 'process that wrote the rules, never agreed by a speaker of the language.',
1036
1067
  dictionaryAppliedUnreviewed: (language) => ` These changes came from the ${language} dictionary, which nobody here reads. `
1037
1068
  + 'Its entries were written by the same process that wrote the rules and never '
1038
- + 'agreed by a speaker — read the diff before trusting it.',
1069
+ + 'agreed by a speaker. Read the diff before trusting it.',
1039
1070
  levelAggressive: () => '[aggressive]',
1040
1071
  levelSafe: () => '[safe]',
1041
1072
  ruleHits: (hits, tokensSaved) => `(${hits}×, ~${tokensSaved} tokens)`,
@@ -1048,28 +1079,28 @@ ${bold('EXAMPLES')}
1048
1079
  llmRejected: (reason) => `rejected: ${reason}`,
1049
1080
  costWith: (modelName) => `Cost with ${modelName}`,
1050
1081
  usageLine: (calls, outputTokens, batch) => `${calls} calls/month · ${outputTokens} output tokens per call${batch ? ' · Batch API' : ''}`,
1051
- allLabelsHeading: (count) => `Every mapped prompt against its own measured traffic — ${count} ranked by what the change is worth`,
1082
+ allLabelsHeading: (count) => `Every mapped prompt against its own measured traffic, ${count} ranked by what the change is worth`,
1052
1083
  allLabelsRow: (saving) => `${saving}/month if optimised`,
1053
1084
  allLabelsRowPeriod: (saving) => `${saving} over the measured period if optimised`,
1054
1085
  allLabelsFooter: () => 'Ranked by measured traffic, not by prompt length: a big prompt on a dead workload is worth less than a small one on a busy one. Each figure is this prompt\'s token delta at its own label\'s measured rate.',
1055
- allLabelsUnmapped: (label, usd) => `${label} carries ${usd} of measured spend and no prompt file is mapped to it — the workload nobody can optimise because nobody said where it lives. Map it under "labels" in trazum.config.json.`,
1056
- allLabelsDead: (label, path) => `${label} is mapped to ${path} and has no traffic in this log — a retired workload, a renamed label, or a typo that has been silently doing nothing.`,
1086
+ allLabelsUnmapped: (label, usd) => `${label} carries ${usd} of measured spend and no prompt file is mapped to it: the workload nobody can optimise because nobody said where it lives. Map it under "labels" in trazum.config.json.`,
1087
+ allLabelsDead: (label, path) => `${label} is mapped to ${path} and has no traffic in this log, a retired workload, a renamed label, or a typo that has been silently doing nothing.`,
1057
1088
  allLabelsUnreadable: (label, path) => `${label} is mapped to ${path}, which could not be read. The mapping exists; the file does not.`,
1058
- usageLineMeasured: (calls, days, scaled, outputTokens, batch) => `${calls} calls measured over ${days} days — ${scaled}/month at that rate · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
1089
+ usageLineMeasured: (calls, days, scaled, outputTokens, batch) => `${calls} calls measured over ${days} days, ${scaled}/month at that rate · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
1059
1090
  usageLineMeasuredPeriod: (calls, days, outputTokens, batch) => `${calls} calls measured${days === null ? ' (the log carries no clock)' : ` over ${days} days`} · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
1060
1091
  measuredModelShare: (model, share, count) => `This label ran on ${count} models; the figures use ${model}, which carried ${share} of its spend.`,
1061
- measuredNoOutput: () => 'No call in this slice recorded output tokens, so the output half of every figure below is $0 measured — not $0 assumed.',
1092
+ measuredNoOutput: () => 'No call in this slice recorded output tokens, so the output half of every figure below is $0 measured, not $0 assumed.',
1062
1093
  perPeriodSaving: (saving, pct) => `saving ${saving} over the measured period (${pct}%)`,
1063
1094
  periodNotScaled: (days) => days === null
1064
1095
  ? 'Not scaled to a month: the log carries no clock, so there is no rate to scale. These figures cover exactly the calls measured.'
1065
- : `Not scaled to a month: ${days} days is under the week a scaling needs — shorter than one weekly cycle multiplies whichever part of the cycle it caught. These figures cover exactly the period measured.`,
1096
+ : `Not scaled to a month: ${days} days is under the week a scaling needs, and being shorter than one weekly cycle multiplies whichever part of the cycle it caught. These figures cover exactly the period measured.`,
1066
1097
  perMonthSaving: (saving, pct) => `saving ${saving}/month (${pct}%)`,
1067
1098
  beyondShortening: () => 'Beyond shortening the prompt',
1068
1099
  biggestLever: () => 'Start here:',
1069
1100
  biggestLeverDetail: (title, amount, times) =>
1070
1101
  // The title keeps its case: lowercasing it turned "Claude Opus 5" into
1071
1102
  // "claude opus 5", which is a product name mangled to fit a sentence.
1072
- `"${title}" — ${amount}/month` +
1103
+ `"${title}", ${amount}/month` +
1073
1104
  (times !== null && times >= 2 ? `, ${times}× what the rules saved.` : '.'),
1074
1105
  perMonthSuffix: (amount) => ` ~${amount}/month`,
1075
1106
  diff: () => 'Diff',
@@ -1079,12 +1110,12 @@ ${bold('EXAMPLES')}
1079
1110
  // `tokens` arrives already formatted for the locale, so the singular is
1080
1111
  // decided on the string rather than on a number that is no longer here.
1081
1112
  tokensSaved: (tokens) => `${tokens} token${tokens === '1' ? '' : 's'} back, every call.`,
1082
- windowNegligible: (tokens, model, window) => `${tokens} tokens of ${model}'s ${window}-token window — under a tenth of a percent, so the window is not what constrains this prompt.`,
1113
+ windowNegligible: (tokens, model, window) => `${tokens} tokens of ${model}'s ${window}-token window, under a tenth of a percent, so the window is not what constrains this prompt.`,
1083
1114
  windowUnmoved: (share, model, window) => `${share} of ${model}'s ${window}-token window, before and after: this change is too small to move it.`,
1084
1115
  beyondThisPromptTokensOnly: () => 'Shortening a prompt is the smallest lever there is: measured on an ordinary support prompt, the rules recover about 1% of a monthly bill. If any of your prompts go to a metered API, "trazum profile <usage.jsonl>" reads what the provider actually charged and prices the levers that are not the prompt. Recording that log is a few lines and it never contains prompt text.',
1085
- beyondThisPrompt: () => 'Shortening a prompt is the smallest lever there is: measured on an ordinary support prompt, the rules recover about 1% of a monthly bill. On a metered API the things that move 40% to 80% are which model the call goes to, the Batch API, prompt caching, and what re-sending the conversation costs — and "trazum profile <usage.jsonl>" prices all four from what the provider actually charged. Recording that log is a few lines and it never contains prompt text.',
1086
- windowUse: (before, after, model, window) => `Context window: ${before} → ${after} of ${model}'s ${window} tokens — room the conversation gets instead.`,
1087
- tokensOnlyAskedFor: () => 'You named a scenario, and it was not priced: Trazum is running somewhere that bills by subscription, so there is no bill here to reduce. Add --cost to price it anyway — the host says where Trazum runs, not where your prompt goes.',
1116
+ beyondThisPrompt: () => 'Shortening a prompt is the smallest lever there is: measured on an ordinary support prompt, the rules recover about 1% of a monthly bill. On a metered API the things that move 40% to 80% are which model the call goes to, the Batch API, prompt caching, and what re-sending the conversation costs, and "trazum profile <usage.jsonl>" prices all four from what the provider actually charged. Recording that log is a few lines and it never contains prompt text.',
1117
+ windowUse: (before, after, model, window) => `Context window: ${before} → ${after} of ${model}'s ${window} tokens, room the conversation gets instead.`,
1118
+ tokensOnlyAskedFor: () => 'You named a scenario, and it was not priced: Trazum is running somewhere that bills by subscription, so there is no bill here to reduce. Add --cost to price it anyway: the host says where Trazum runs, not where your prompt goes.',
1088
1119
  tokensOnlyCost: () => 'Pass --cost if this prompt is bound for a metered API.',
1089
1120
  pricingOverlaid: (models, lastReviewed) => `Prices for ${models} came from a local overlay reviewed ${lastReviewed}, not from the bundled catalogue.`,
1090
1121
  reorderHeading: () => 'Reordered for caching',
@@ -1120,14 +1151,14 @@ ${bold('EXAMPLES')}
1120
1151
  heading: () => 'What is here',
1121
1152
  host: (name) => `Running inside ${name}.`,
1122
1153
  prompts: (count) => `${count} prompt ${count === 1 ? 'file' : 'files'} found.`,
1123
- noPrompts: () => 'No prompt files found. Directory mode reads .txt, .md, .prompt and .tmpl by default — set "extensions" if yours are named otherwise.',
1154
+ noPrompts: () => 'No prompt files found. Directory mode reads .txt, .md, .prompt and .tmpl by default. Set "extensions" if yours are named otherwise.',
1124
1155
  sourcesTruncated: (cap) => `Stopped after ${cap} source files, so a provider named further down was not seen.`,
1125
1156
  usageFound: (kind, where) => kind === 'connector-credential'
1126
1157
  ? `Usage can be pulled: a credential is in ${where}. Run trazum connect.`
1127
1158
  : kind === 'store'
1128
1159
  ? `A local store of past measurements is in ${where}.`
1129
1160
  : `Usage log found: ${where}.`,
1130
- noUsage: () => 'No usage found. Point trazum at a log (trazum profile <log.jsonl>) or pull one (trazum connect anthropic) — every money figure in this tool comes from one.',
1161
+ noUsage: () => 'No usage found. Point trazum at a log (trazum profile <log.jsonl>) or pull one (trazum connect anthropic): every money figure in this tool comes from one.',
1131
1162
  usageUnreadable: (where, because) => `${where} is there and could not be read: ${because}. That is a different problem from having no usage, and it is the one to fix first.`,
1132
1163
  configHeading: () => 'What the config would say',
1133
1164
  nothingJustified: () => 'Nothing. Every key below needs evidence this run did not find, and a guessed config is worse than none.',
@@ -1140,7 +1171,7 @@ ${bold('EXAMPLES')}
1140
1171
  whyCache: (rate, cacheReadTokens, inputTokens) => `${cacheReadTokens} cached against ${inputTokens} fresh input is a hit rate of ${rate}`,
1141
1172
  noModelEvidence: () => 'nothing measured or written in the source names one model',
1142
1173
  modelConflict: (files) => `these files name more than one provider: ${files}`,
1143
- modelProviderOnly: (provider, file) => `${file} names ${provider} and no model — a provider default would read as your decision six weeks from now`,
1174
+ modelProviderOnly: (provider, file) => `${file} names ${provider} and no model: a provider default would read as your decision six weeks from now`,
1144
1175
  nothingMeasured: () => 'nothing has been measured yet',
1145
1176
  windowTooShort: (days, minimum) => `${days} days measured; ${minimum} are needed before that is a monthly rate rather than a forecast`,
1146
1177
  undatedCalls: (undated, calls) => `${undated} of ${calls} calls carry no timestamp, so they cannot be placed inside the window a rate would divide by`,
@@ -1148,7 +1179,7 @@ ${bold('EXAMPLES')}
1148
1179
  batchOnlyYouKnow: () => 'whether the work can wait for a batch window is a product decision, and no log records it',
1149
1180
  labelsUnprovable: (labels) => `${labels} ${labels === 1 ? 'label' : 'labels'} in the log, and nothing here proves which prompt file sends which`,
1150
1181
  budgetIsPolicy: () => 'a budget is a policy, and there is no measured figure to write one against yet',
1151
- budgetIsPolicyMeasured: (usd, days) => `a budget is a policy, so it is yours to set — the measured figure is $${usd} over ${days} days`,
1182
+ budgetIsPolicyMeasured: (usd, days) => `a budget is a policy, so it is yours to set: the measured figure is $${usd} over ${days} days`,
1152
1183
  findingHeading: () => 'The most valuable thing found',
1153
1184
  noFinding: (why) => why === 'nothing-measured'
1154
1185
  ? 'Nothing, because nothing has been measured. Every figure this tool prints as money comes from a usage log.'
@@ -1160,7 +1191,7 @@ ${bold('EXAMPLES')}
1160
1191
  findingRoute: (model) => `The same work fits ${model}, which is cheaper per token.`,
1161
1192
  findingBatch: () => 'The Batch API halves both halves of the bill, for work that can wait.',
1162
1193
  findingTotal: (usd, days) => `Together: $${usd} over the same ${days} days.`,
1163
- findingNext: () => 'trazum plan <your log> ranks every action, not just this one. If a figure here looks wrong, trazum feedback says where to tell us — it sends nothing on its own.',
1194
+ findingNext: () => 'trazum plan <your log> ranks every action, not just this one. If a figure here looks wrong, trazum feedback says where to tell us, it sends nothing on its own.',
1164
1195
  wouldOverwrite: (keys) => `This replaces keys you already set: ${keys}. Pass --yes to write anyway.`,
1165
1196
  nothingToWrite: () => 'No config written: nothing above could be justified from what is here.',
1166
1197
  wouldWrite: (path) => `Would write ${path}:`,
@@ -1173,11 +1204,11 @@ ${bold('EXAMPLES')}
1173
1204
  needsYear: () => '--year is required, as four digits: trazum report <log> --year 2026.',
1174
1205
  spent: (usd, calls, months) => `${usd} across ${calls} calls, over ${months} recorded months.`,
1175
1206
  missing: (months) => `No record at all for ${months}. Those months are named rather than filled: a year that quietly covers part of itself and prints an annual total is wrong by the rest and says nothing about it.`,
1176
- promises: (planned, arrived, notArrived, cannotTell) => `${planned} actions planned. ${arrived} arrived, ${notArrived} did not, and ${cannotTell} could not be judged. Three outcomes, never two \u2014 the third is the one an ordinary annual report folds into the flattering one.`,
1207
+ promises: (planned, arrived, notArrived, cannotTell) => `${planned} actions planned. ${arrived} arrived, ${notArrived} did not, and ${cannotTell} could not be judged. Three outcomes, never two, the third is the one an ordinary annual report folds into the flattering one.`,
1177
1208
  projected: (usd) => `The plans projected ${usd} of savings.`,
1178
- noArrivedFigure: () => 'There is deliberately no figure beside it for what arrived. A verification says WHETHER each action landed; it has never carried a per-action dollar figure for the saving. Assembling one here would mean deciding which of several observed numbers is "the saving" \u2014 a judgement the verification refused to make, and exactly the annual-report arithmetic this document replaces.',
1209
+ noArrivedFigure: () => 'There is deliberately no figure beside it for what arrived. A verification says WHETHER each action landed; it has never carried a per-action dollar figure for the saving. Assembling one here would mean deciding which of several observed numbers is "the saving", a judgement the verification refused to make, and exactly the annual-report arithmetic this document replaces.',
1179
1210
  outcomes: (recorded, parsed, unrecordedUsd) => `${recorded} of ${parsed} calls recorded an outcome; ${unrecordedUsd} of the year\u2019s spend did not.`,
1180
- noOutcomes: () => 'No outcome was recorded this year, so nothing here says what the money bought. That is not a success rate of zero \u2014 an uninstrumented year and a failing year are different sentences.',
1211
+ noOutcomes: () => 'No outcome was recorded this year, so nothing here says what the money bought. That is not a success rate of zero, an uninstrumented year and a failing year are different sentences.',
1181
1212
  cannotSayHeading: () => 'What this record cannot say',
1182
1213
  cannotSay: (kind) => kind === 'months-missing'
1183
1214
  ? 'what happened in the months with no record'
@@ -1186,60 +1217,60 @@ ${bold('EXAMPLES')}
1186
1217
  : kind === 'nothing-was-verified'
1187
1218
  ? 'whether the promises were kept, because no plan was verified'
1188
1219
  : kind === 'some-promises-unjudgeable'
1189
- ? 'whether some promises were kept \u2014 they could not be judged from the logs that exist'
1220
+ ? 'whether some promises were kept, they could not be judged from the logs that exist'
1190
1221
  : kind === 'arrived-savings-not-quantified'
1191
1222
  ? 'how many dollars the kept promises were worth'
1192
1223
  : kind === 'no-outcomes-recorded'
1193
1224
  ? 'what any of the money bought'
1194
1225
  : 'what the uninstrumented share of the traffic did',
1195
- noNewData: () => 'Every figure above comes from the store and the plans you already keep. Nothing was computed here that cannot be checked against a document that already exists \u2014 which is the only reason an annual report is worth trusting, since it is the document most likely to be quoted out of the room it was written in.',
1226
+ noNewData: () => 'Every figure above comes from the store and the plans you already keep. Nothing was computed here that cannot be checked against a document that already exists, which is the only reason an annual report is worth trusting, since it is the document most likely to be quoted out of the room it was written in.',
1196
1227
  },
1197
1228
  commitment: {
1198
1229
  heading: (floor, discount, months) => `A ${months}-month commitment: ${floor} a month at ${discount} off`,
1199
1230
  needsTerms: () => '--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.',
1200
- asIf: () => '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.',
1231
+ asIf: () => 'This is what the deal WOULD HAVE done on the traffic you actually had. It is a measurement of the past, not a prediction, every month below happened.',
1201
1232
  columns: { month: 'month', list: 'list', paid: 'would pay', saving: 'saving' },
1202
1233
  net: (usd, months) => `Net over ${months} measured months: ${usd}.`,
1203
1234
  good: (usd) => `The months that cleared the floor saved ${usd}.`,
1204
1235
  lost: (usd, months) => `${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.`,
1205
1236
  noShortfall: () => 'No measured month would have fallen short of the floor.',
1206
1237
  breakEven: (usd) => `Break-even is ${usd} of monthly spend. Below it you pay the floor for less usage than it buys; above it the saving grows.`,
1207
- spread: (low, high, median) => `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.`,
1238
+ spread: (low, high, median) => `Measured spread: ${low} to ${high}, median ${median}. That is the shortfall risk in the only form a log can state it, a count of real months and the range they covered, rather than a probability from a distribution nobody fitted.`,
1208
1239
  shortTerm: (covered, term) => `This replays ${covered} months against a ${term}-month commitment. It is a real answer about ${covered} months and not about ${term}.`,
1209
1240
  cannotTell: (why, needed) => why === 'no-history'
1210
1241
  ? 'Nothing to replay: this log has no whole months in it.'
1211
- : `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.`,
1212
- neverAForecast: () => '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.',
1242
+ : `Cannot judge this from ${needed === '0' ? 'what exists' : `what exists, ${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.`,
1243
+ neverAForecast: () => 'Nothing here is annualised, extrapolated or fitted to a trend. If next quarter looks nothing like last quarter, this arithmetic says nothing about it, which is the honest limit of what a log can tell you about a contract.',
1213
1244
  },
1214
1245
  owners: {
1215
1246
  heading: () => 'Whose money',
1216
1247
  noOwners: () => 'No owners configured. Add "owners" to trazum.config.json to attribute spend, for example {"patterns": {"payments": ["billing-*"]}, "budgets": {"payments": 400}}.',
1217
1248
  columns: { owner: 'owner', spend: 'spend', budget: 'budget', calls: 'calls' },
1218
- verdict: (kind) => kind === 'over' ? 'over' : kind === 'within' ? 'within' : kind === 'not-measured' ? 'not measured' : '\u2014',
1249
+ verdict: (kind) => kind === 'over' ? 'over' : kind === 'within' ? 'within' : kind === 'not-measured' ? 'not measured' : 'no verdict',
1219
1250
  unallocated: (usd, share, labels) => `Unallocated: ${usd} (${share} of the bill), from ${labels}.`,
1220
- neverSpread: () => '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.',
1251
+ neverSpread: () => '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, 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.',
1221
1252
  nothingUnallocated: () => 'Every workload in this log has an owner.',
1222
1253
  sharedHeading: () => 'Shared, by a rule somebody wrote',
1223
1254
  sharedRule: (label, rule) => `${label}: ${rule}`,
1224
1255
  problemsHeading: () => 'This ownership config will not do what it looks like it does',
1225
1256
  problem: (kind, detail) => kind === 'split-does-not-sum'
1226
- ? `${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.`
1257
+ ? `${detail}, 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.`
1227
1258
  : kind === 'split-names-unknown-owner'
1228
1259
  ? `${detail} names an owner that "owners.patterns" does not declare.`
1229
1260
  : kind === 'split-has-one-owner'
1230
- ? `${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.`
1261
+ ? `${detail} is "shared" with one owner, 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.`
1231
1262
  : kind === 'negative-share'
1232
1263
  ? `${detail} has a negative share.`
1233
1264
  : `${detail} has a budget but no patterns, so nothing can ever land on it.`,
1234
- notMeasured: (owner) => `${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.`,
1265
+ notMeasured: (owner) => `${owner} has a budget and no measured calls. That is NOT under budget, 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.`,
1235
1266
  },
1236
1267
  semantic: {
1237
1268
  heading: (path) => `Semantic pass on ${path}`,
1238
- willCost: (usd, input, output, model) => `This will send the prompt to ${model}: about ${input} tokens in and ${output} out, roughly ${usd}. Estimated, not measured \u2014 a tool that spends your money to tell you how to spend less should be the first thing audited by its own arithmetic. Pass --yes to run it.`,
1269
+ willCost: (usd, input, output, model) => `This will send the prompt to ${model}: about ${input} tokens in and ${output} out, roughly ${usd}. Estimated, not measured, a tool that spends your money to tell you how to spend less should be the first thing audited by its own arithmetic. Pass --yes to run it.`,
1239
1270
  needsYes: () => 'Nothing was sent. Add --yes once you have read the price above.',
1240
1271
  finding: (kind, because) => `${kind === 'contradiction' ? 'Contradiction' : kind === 'restated-instruction' ? 'Restated' : 'Same thing, different words'}: ${because}`,
1241
1272
  span: (line, text) => `line ${line}: ${text}`,
1242
- ceiling: (tokens) => `At most ${tokens} tokens \u2014 a ceiling, not a saving. Merging these two means writing one passage that does the work of both, and nobody knows yet how long that is.`,
1273
+ ceiling: (tokens) => `At most ${tokens} tokens, a ceiling, not a saving. Merging these two means writing one passage that does the work of both, and nobody knows yet how long that is.`,
1243
1274
  noCeiling: () => 'No tokens attached. A contradiction is worth fixing because the prompt is wrong, not because it is long, and putting a figure on it would sell the wrong reason.',
1244
1275
  nothingFound: () => 'Nothing survived checking. That is a real answer.',
1245
1276
  rejected: (count) => `${count} proposals did not survive checking against the prompt.`,
@@ -1253,7 +1284,7 @@ ${bold('EXAMPLES')}
1253
1284
  ? `quoted the same passage twice: ${span}`
1254
1285
  : `covers ground an accepted finding covers: ${span}`,
1255
1286
  disposes: () => 'The model proposes and the deterministic layer disposes: every quoted passage is checked character for character against the prompt, pairs the rules engine already catches are dropped, and every token figure is counted here rather than believed.',
1256
- optIn: () => 'This pass is optional and always will be. Trazum works with no key, no network and no model \u2014 that has been true since 0.1.0 and this does not change it.',
1287
+ optIn: () => 'This pass is optional and always will be. Trazum works with no key, no network and no model, that has been true since 0.1.0 and this does not change it.',
1257
1288
  },
1258
1289
  quality: {
1259
1290
  heading: (label) => `Quality across the change: ${label}`,
@@ -1261,13 +1292,13 @@ ${bold('EXAMPLES')}
1261
1292
  needsAt: () => '--at is required: give the moment the change landed, as an ISO timestamp. Without it there is no boundary to compare across, and picking one from the log would be this tool choosing which change to blame.',
1262
1293
  sides: (beforeRate, afterRate, before, after) => `before ${beforeRate} (${before} outcomes) after ${afterRate} (${after} outcomes)`,
1263
1294
  dropped: (from, to, outcomes, cost) => `The resolution rate moved from ${from} to ${to} on ${outcomes} measured outcomes, and this change ${cost}. Both halves are measured; neither is an estimate.`,
1264
- held: (from, to, outcomes) => `The resolution rate moved from ${from} to ${to} on ${outcomes} measured outcomes \u2014 up, measurably.`,
1295
+ held: (from, to, outcomes) => `The resolution rate moved from ${from} to ${to} on ${outcomes} measured outcomes, up, measurably.`,
1265
1296
  cannotTell: (why, need) => why === 'too-few-before'
1266
1297
  ? `Cannot tell: only ${need} outcomes before the change, and this gate needs 100 a side. It fails builds, so the threshold is not the one a rate uses elsewhere.`
1267
1298
  : why === 'too-few-after'
1268
1299
  ? `Cannot tell yet: only ${need} outcomes since the change, and this gate needs 100 a side. Run it again once the traffic has caught up.`
1269
1300
  : why === 'not-separable'
1270
- ? 'Cannot tell: the rate did not measurably move. That is NOT the same as "it held" \u2014 a gate that spelled them the same way would pass a real regression it merely lacked the power to see.'
1301
+ ? 'Cannot tell: the rate did not measurably move. That is NOT the same as "it held", a gate that spelled them the same way would pass a real regression it merely lacked the power to see.'
1271
1302
  : why === 'no-vocabulary'
1272
1303
  ? 'Cannot tell: "outcomes.success" declares nothing, so there is no resolution rate to compare.'
1273
1304
  : 'Cannot tell: something other than the prompt moved across the boundary. See below.',
@@ -1275,33 +1306,33 @@ ${bold('EXAMPLES')}
1275
1306
  confounder: (kind, detail) => kind === 'model-mix-moved'
1276
1307
  ? `The model mix moved by ${detail}. The drop may be entirely somebody else's migration, and this tool cannot separate the two.`
1277
1308
  : kind === 'volume-moved'
1278
- ? `The call volume moved ${detail}. A workload whose traffic moved that much is usually a workload whose population changed \u2014 a new surface, a new customer, a campaign \u2014 and the questions being asked are not the questions from before.`
1309
+ ? `The call volume moved ${detail}. A workload whose traffic moved that much is usually a workload whose population changed, a new surface, a new customer, a campaign, and the questions being asked are not the questions from before.`
1279
1310
  : `Outcome coverage moved from ${detail}. The two rates describe different populations: a team that starts instrumenting its hard cases sees its measured rate fall without anything having got worse.`,
1280
- notRandomised: () => 'This is a before-and-after, not an experiment. It splits traffic by time rather than at random, so everything else that changed at the same time is in the difference too \u2014 which is why it says "cannot tell" far more readily than an A/B would.',
1311
+ notRandomised: () => 'This is a before-and-after, not an experiment. It splits traffic by time rather than at random, so everything else that changed at the same time is in the difference too, which is why it says "cannot tell" far more readily than an A/B would.',
1281
1312
  cannotSee: () => 'It cannot see anything else you deployed that day. A "dropped" verdict says the rate fell and the three things it can check did not move. That is a smaller claim than "the prompt did it", and it is the largest one the evidence supports.',
1282
1313
  gateFailed: () => 'Gate failed: a measured drop with nothing else to explain it.',
1283
- gateHeldOpen: () => 'Gate not passed and not failed. "Cannot tell" holds the claim open rather than exiting green \u2014 the posture verify has had since 1.39.',
1314
+ gateHeldOpen: () => 'Gate not passed and not failed. "Cannot tell" holds the claim open rather than exiting green, the posture verify has had since 1.39.',
1284
1315
  },
1285
1316
  experiment: {
1286
1317
  heading: (a, b) => `Experiment: ${a} against ${b}`,
1287
1318
  needsTwo: () => 'Name two labels to compare, for example: trazum experiment <log> --a prompt-v1 --b prompt-v2',
1288
1319
  needsRule: () => '--min-outcomes is required, and it is the point: a stopping rule declared after looking at the numbers is not a stopping rule. Say how many outcomes each arm must record before the result may be read.',
1289
1320
  arm: (name, rate, successes, recorded, interval) => `${name} ${rate} (${successes} of ${recorded} recorded) 95% ${interval}`,
1290
- wins: (name, low, high) => `${name} wins. The difference is between ${low} and ${high} at 95% confidence \u2014 the whole interval is on one side of zero, which is what "wins" means here.`,
1321
+ wins: (name, low, high) => `${name} wins. The difference is between ${low} and ${high} at 95% confidence, the whole interval is on one side of zero, which is what "wins" means here.`,
1291
1322
  notSeparable: (why, needed) => why === 'no-difference-observed'
1292
- ? 'Not separable: both arms recorded the same rate. No sample size separates a difference of zero, so there is no "run it longer" to offer \u2014 there is nothing here to find.'
1323
+ ? 'Not separable: both arms recorded the same rate. No sample size separates a difference of zero, so there is no "run it longer" to offer, there is nothing here to find.'
1293
1324
  : why === 'nothing-recorded'
1294
1325
  ? 'Not separable: an arm recorded no outcomes at all, so there is no rate to compare.'
1295
1326
  : `Not separable on this traffic: the 95% interval on the difference includes zero. One number is larger, and that is not a finding. About ${needed} outcomes per arm would settle the difference observed so far.`,
1296
1327
  peeked: (short, declared, recorded) => `Read early. The declared rule was ${declared} outcomes per arm and ${short} has ${recorded}. Nothing can stop a number being read early; this line exists so whoever reads the result later can see that it was.`,
1297
1328
  honoured: (declared) => `Stopping rule honoured: both arms cleared ${declared} recorded outcomes.`,
1298
- marginalDearer: (better, usd) => `${better} resolves more and costs more. One extra success costs ${usd} \u2014 that figure, not the rate, is what the decision turns on.`,
1329
+ marginalDearer: (better, usd) => `${better} resolves more and costs more. One extra success costs ${usd}, that figure, not the rate, is what the decision turns on.`,
1299
1330
  marginalCheaper: (better) => `${better} resolves more AND costs less per call. Nothing is being traded.`,
1300
1331
  neverPromotes: () => 'Nothing was changed. A winner is a finding; taking it is a decision with a name attached, and it belongs in the plan like everything else.',
1301
1332
  },
1302
1333
  ladder: {
1303
1334
  heading: () => 'Escalation ladders',
1304
- noLadders: () => 'No ladders configured. A ladder sends a workload to a cheap model first and escalates a recorded failure to a dearer one — add "ladders" to trazum.config.json, for example {"support": {"tiers": ["claude-haiku-4-5", "claude-opus-5"], "escalateOn": ["escalated"]}}.',
1335
+ noLadders: () => 'No ladders configured. A ladder sends a workload to a cheap model first and escalates a recorded failure to a dearer one. Add "ladders" to trazum.config.json, for example {"support": {"tiers": ["claude-haiku-4-5", "claude-opus-5"], "escalateOn": ["escalated"]}}.',
1305
1336
  workload: (label) => label,
1306
1337
  arithmetic: (cheap, dear, breakEven) => `${cheap} a call cheap, ${dear} dear. Break-even escalation rate: ${breakEven}.`,
1307
1338
  measured: (rate, escalations, calls) => `Measured: ${rate} (${escalations} of ${calls} calls escalated).`,
@@ -1315,7 +1346,7 @@ ${bold('EXAMPLES')}
1315
1346
  : why === 'tier-unpriced'
1316
1347
  ? 'Cannot tell: one of the tiers is not in the price catalogue, so the break-even rate cannot be computed.'
1317
1348
  : 'Cannot tell: this ladder declares no escalation values.',
1318
- problemsHeading: (label) => `${label} — this ladder will not do what it looks like it does`,
1349
+ problemsHeading: (label) => `${label}: this ladder will not do what it looks like it does`,
1319
1350
  problem: (kind, detail) => kind === 'escalate-on-a-success'
1320
1351
  ? `escalateOn names "${detail}", which "outcomes.success" declares a SUCCESS. This ladder pays twice for work that already worked, on every call, while looking exactly like a cost-saving measure.`
1321
1352
  : kind === 'escalate-on-undeclared'
@@ -1327,15 +1358,15 @@ ${bold('EXAMPLES')}
1327
1358
  : kind === 'unknown-model'
1328
1359
  ? `"${detail}" is not in the price catalogue.`
1329
1360
  : `a ladder needs at least two tiers; this one has ${detail}.`,
1330
- theDoubleSpend: () => 'An escalation pays twice: the cheap attempt is not refunded. So a ladder saves money only below its break-even escalation rate, and above it costs more than never having built one — which is why the rate is printed beside the measurement rather than left to be worked out in somebody\u2019s head.',
1361
+ theDoubleSpend: () => 'An escalation pays twice: the cheap attempt is not refunded. So a ladder saves money only below its break-even escalation rate, and above it costs more than never having built one, which is why the rate is printed beside the measurement rather than left to be worked out in somebody\u2019s head.',
1331
1362
  notExecuted: () => 'Trazum does not run the escalation. A ladder escalates after a failure is known, which is after the answer came back and usually after something downstream judged it, so the retry belongs in your own loop. What is here is the policy and the arithmetic that says whether the policy is worth running.',
1332
1363
  },
1333
1364
  gateway: {
1334
1365
  badProvider: (given, known) => given === ''
1335
1366
  ? `Name the provider to stand in front of. Known: ${known}.`
1336
1367
  : `"${given}" is not a provider this gateway speaks for. Known: ${known}.`,
1337
- pricedNotFronted: (given, known) => `Trazum prices ${given} but this gateway does not stand in front of it yet — it fronts ${known}. That is a real gap and it is on the roadmap, not a typo on your part. Until then: "trazum profile" prices a ${given} log you export, and its --max-usd gate fails a build on the bill after the fact. What you do not get is a refusal before the money is spent, which is the whole point of the gateway and the reason this is worth saying rather than listing ${given} as unknown.`,
1338
- needsPolicy: (policies) => `--on-cannot-tell is required, and there is no default: ${policies}. When the gateway cannot judge a call — no budget, nothing measured, an unpriced model — one of these happens, and only you know which failure your product can survive. fail-open keeps it working and lets the bill run; fail-closed stops the bill and takes it down with it. Picking one for you would be the most consequential decision in your architecture, made silently at install time.`,
1368
+ pricedNotFronted: (given, known) => `Trazum prices ${given} but this gateway does not stand in front of it yet: it fronts ${known}. That is a real gap and it is on the roadmap, not a typo on your part. Until then: "trazum profile" prices a ${given} log you export, and its --max-usd gate fails a build on the bill after the fact. What you do not get is a refusal before the money is spent, which is the whole point of the gateway and the reason this is worth saying rather than listing ${given} as unknown.`,
1369
+ needsPolicy: (policies) => `--on-cannot-tell is required, and there is no default: ${policies}. When the gateway cannot judge a call, no budget, nothing measured, an unpriced model, one of these happens, and only you know which failure your product can survive. fail-open keeps it working and lets the bill run; fail-closed stops the bill and takes it down with it. Picking one for you would be the most consequential decision in your architecture, made silently at install time.`,
1339
1370
  listening: (where, provider) => `Gateway on ${where}, in front of ${provider}`,
1340
1371
  /**
1341
1372
  * One sentence per cause, and no `else`.
@@ -1343,42 +1374,42 @@ ${bold('EXAMPLES')}
1343
1374
  * This was a two-branch ternary whose second arm explained OpenAI's
1344
1375
  * `stream_options`. A third cause added later would have inherited that
1345
1376
  * sentence and told a Gemini user about a setting that does not exist in
1346
- * their SDK — a message bounded by its neighbour rather than by its
1377
+ * their SDK, a message bounded by its neighbour rather than by its
1347
1378
  * subject, which is this project's most repeated mistake.
1348
1379
  */
1349
1380
  unmeasured: (cause, sofar) => {
1350
1381
  if (cause === 'stream-broke') {
1351
- return `unmeasured: the stream broke before its usage event — the provider billed this call and this session cannot see it (${sofar} unmeasured so far)`;
1382
+ return `unmeasured: the stream broke before its usage event, so the provider billed this call and this session cannot see it (${sofar} unmeasured so far)`;
1352
1383
  }
1353
1384
  if (cause === 'no-usage-event') {
1354
- return `unmeasured: the stream carried no usage event — on OpenAI that is every streaming call without stream_options.include_usage, so the total below is short by these (${sofar} unmeasured so far)`;
1385
+ return `unmeasured: the stream carried no usage event, on OpenAI that is every streaming call without stream_options.include_usage, so the total below is short by these (${sofar} unmeasured so far)`;
1355
1386
  }
1356
- return `unmeasured: the provider answered without any usage in the body — the call was made and its cost is not knowable from the response, so the total below is short by these (${sofar} unmeasured so far)`;
1387
+ return `unmeasured: the provider answered without any usage in the body, so the call was made and its cost is not knowable from the response, so the total below is short by these (${sofar} unmeasured so far)`;
1357
1388
  },
1358
1389
  pointYourSdk: (where) => `Point your SDK's base URL at ${where} and change nothing else. It speaks the provider's own wire format, so no code changes and no new client.`,
1359
1390
  credential: () => 'Your credential is forwarded untouched and never read, never stored, never logged and never put in a URL. Trazum holds no key here and cannot make a call of its own through this.',
1360
- neverSubstitutes: () => 'A call over budget is refused with HTTP 402 and the cheaper alternatives named — never silently swapped, trimmed or downgraded. 402 rather than 429 on purpose: every provider SDK retries a 429, which would turn one refusal into a retry storm.',
1361
- standing: (consumed, limit) => `Judging against ${consumed} of ${limit}, measured, read once at start — a file read in the request path would put this tool's latency between you and your provider on every call.`,
1391
+ neverSubstitutes: () => 'A call over budget is refused with HTTP 402 and the cheaper alternatives named, never silently swapped, trimmed or downgraded. 402 rather than 429 on purpose: every provider SDK retries a 429, which would turn one refusal into a retry storm.',
1392
+ standing: (consumed, limit) => `Judging against ${consumed} of ${limit}, measured, read once at start: a file read in the request path would put this tool's latency between you and your provider on every call.`,
1362
1393
  noStanding: () => 'Nothing measured for this period, so every call is unjudged and the failure policy below decides. Set spend.monthlyUsd and pull with trazum connect.',
1363
1394
  policy: (policy) => policy === 'fail-open'
1364
1395
  ? 'When it cannot judge: the call goes through, and the record says it was unjudged rather than within budget.'
1365
1396
  : 'When it cannot judge: the call is refused. Nothing gets through unmeasured.',
1366
- measured: (model, label, input, output, substituted) => ` ${model}${label === null ? '' : ` [${label}]`}: ${input} in, ${output} out${substituted ? ' (substituted — marked, and never counted as the call that was asked for)' : ''}`,
1397
+ measured: (model, label, input, output, substituted) => ` ${model}${label === null ? '' : ` [${label}]`}: ${input} in, ${output} out${substituted ? ' (substituted, marked, and never counted as the call that was asked for)' : ''}`,
1367
1398
  },
1368
1399
  feedback: {
1369
1400
  heading: () => 'Telling us something',
1370
1401
  sendsNothing: () => 'This command sends nothing, and neither does anything else here. Trazum has no telemetry: no ping, no install hook, no anonymous counter. A tool whose whole argument is that it reads your bill without uploading it cannot also be quietly reporting on you, and a test fails the build if this command ever reaches the network.',
1371
1402
  whereHeading: () => 'Where',
1372
- wrongOptimisation: () => 'A rule changed what a prompt asks for — the report that matters most, and the failure this product exists to avoid:',
1403
+ wrongOptimisation: () => 'A rule changed what a prompt asks for, the report that matters most, and the failure this product exists to avoid:',
1373
1404
  bug: () => 'Anything else that is wrong:',
1374
1405
  question: () => 'A question, or an idea you are not sure about:',
1375
- security: () => 'A security problem — privately, never a public issue:',
1406
+ security: () => 'A security problem, privately, never a public issue:',
1376
1407
  environmentHeading: () => 'What a maintainer will ask for',
1377
- environmentOnly: () => 'That is the whole of it. Nothing about your work is here — not the config, not a prompt, not a label, not a figure. Those are what a good report needs and what only you can decide to share.',
1408
+ environmentOnly: () => 'That is the whole of it. Nothing about your work is here, not the config, not a prompt, not a label, not a figure. Those are what a good report needs and what only you can decide to share.',
1378
1409
  linkHeading: () => 'A blank issue with the above already filled in',
1379
1410
  },
1380
1411
  conform: {
1381
- noTarget: () => 'Pass a file to check — a usage log, or any document Trazum emits. Use "-" to read from stdin.',
1412
+ noTarget: () => 'Pass a file to check, a usage log, or any document Trazum emits. Use "-" to read from stdin.',
1382
1413
  badContract: (given, known) => `"${given}" is not a contract. Known contracts: ${known}.`,
1383
1414
  unrecognised: (path) => `${path} does not match any contract Trazum knows.`,
1384
1415
  /**
@@ -1401,39 +1432,39 @@ ${bold('EXAMPLES')}
1401
1432
  problem: (at, kind, detail) => `${at}: ${detail} (${kind})`,
1402
1433
  moreProblems: (count) => `…and ${count} more. Fix these first; they are often the same mistake.`,
1403
1434
  unavailableHeading: () => 'What this cannot answer, and what would unlock it',
1404
- unavailable: (finding, because, unlockedBy) => `${finding} — ${because}. Add ${unlockedBy}.`,
1435
+ unavailable: (finding, because, unlockedBy) => `${finding}, ${because}. Add ${unlockedBy}.`,
1405
1436
  unavailableNeverGates: () => 'None of those failed anything. Choosing not to record a field is a decision, not a defect, and a gate that failed on it would be this tool telling you what to log.',
1406
1437
  },
1407
1438
  rollup: {
1408
- noTargets: () => 'Pass the profile documents to roll up — each one written by `trazum profile --json` — or a directory of them.',
1439
+ noTargets: () => 'Pass the profile documents to roll up, each one written by `trazum profile --json`, or a directory of them.',
1409
1440
  noSuchTarget: (path) => `${path} is not there. A roll-up never guesses at a contribution it could not read.`,
1410
1441
  emptyDirectory: (path) => `${path} holds no .json documents. An empty folder rolled up silently would report a team that spent nothing.`,
1411
- heading: (contributors, usd, calls) => `Roll-up of ${plural(contributors, 'contributor')} — ${usd} over ${plural(calls, 'call')}`,
1442
+ heading: (contributors, usd, calls) => `Roll-up of ${plural(contributors, 'contributor')}, ${usd} over ${plural(calls, 'call')}`,
1412
1443
  span: (from, to) => `Covering ${from} to ${to}, stated and never extrapolated from.`,
1413
1444
  noSpan: () => 'No contributor carried a clock, so this roll-up covers no stated period.',
1414
1445
  contributorsHeading: () => 'Contributors, and what each one could not see',
1415
- contributor: (name, usd, calls, spanDays) => `${name} — ${usd}, ${plural(calls, 'call')}${spanDays === null ? ', no clock' : `, ${plural(spanDays, 'day')}`}`,
1416
- claimedSpan: (from, to, contributors) => `Asked for ${from} to ${to} by ${plural(contributors, 'contributor')} — a claim about what was gone looking for, kept apart from what the records showed.`,
1446
+ contributor: (name, usd, calls, spanDays) => `${name}, ${usd}, ${plural(calls, 'call')}${spanDays === null ? ', no clock' : `, ${plural(spanDays, 'day')}`}`,
1447
+ claimedSpan: (from, to, contributors) => `Asked for ${from} to ${to} by ${plural(contributors, 'contributor')}: a claim about what was gone looking for, kept apart from what the records showed.`,
1417
1448
  claimedRow: (from, to) => `asked for ${from} to ${to}`,
1418
1449
  silentRuns: (runs) => runs,
1419
1450
  undated: (count) => `${plural(count, 'record')} this contributor's own window could not place, because they carried no clock`,
1420
1451
  rejectedHeading: () => 'Handed over and not merged',
1421
- rejected: (name, because) => `${name} — ${because}`,
1452
+ rejected: (name, because) => `${name}, ${because}`,
1422
1453
  via: (rollup) => `via ${rollup}`,
1423
- rejectedVia: (name, via, because) => `${name}, via ${via} — ${because}`,
1424
- repeated: (names) => `Handed over more than once, by name: ${names}. Its money is counted every time. Two machines genuinely sharing a name is possible, so nothing was subtracted — check whether a roll-up and one of the machines inside it were both handed over.`,
1454
+ rejectedVia: (name, via, because) => `${name}, via ${via}, ${because}`,
1455
+ repeated: (names) => `Handed over more than once, by name: ${names}. Its money is counted every time. Two machines genuinely sharing a name is possible, so nothing was subtracted. Check whether a roll-up and one of the machines inside it were both handed over.`,
1425
1456
  identical: (names) => `The same document arrived more than once: ${names}.`,
1426
- identicalUsd: (usd) => `${usd} of the total above is the repeat. It is counted, not discarded — whether it is one export handed over twice or two machines that agreed exactly is yours to know.`,
1457
+ identicalUsd: (usd) => `${usd} of the total above is the repeat. It is counted, not discarded, whether it is one export handed over twice or two machines that agreed exactly is yours to know.`,
1427
1458
  byLabelHeading: () => 'The merged bill, per workload',
1428
- labelRow: (label, usd, calls) => `${label} — ${usd}, ${plural(calls, 'call')}`,
1459
+ labelRow: (label, usd, calls) => `${label}, ${usd}, ${plural(calls, 'call')}`,
1429
1460
  notMergedHeading: () => 'Findings that do not roll up',
1430
- notMerged: (finding, because) => `${finding} — ${because}.`,
1461
+ notMerged: (finding, because) => `${finding}, ${because}.`,
1431
1462
  presentIn: (names) => `Present in: ${names}. Read it there.`,
1432
1463
  cannotSayHeading: () => 'What this roll-up cannot say about itself',
1433
1464
  caveat: (code) => {
1434
1465
  switch (code) {
1435
1466
  case 'overlap-invisible':
1436
- return 'Overlap between contributors is unmeasurable here. Two people exporting the same traffic double the bill, and a merge of summaries cannot see it — the raw lines a duplicate check needs are in no document.';
1467
+ return 'Overlap between contributors is unmeasurable here. Two people exporting the same traffic double the bill, and a merge of summaries cannot see it: the raw lines a duplicate check needs are in no document.';
1437
1468
  case 'mismatched-spans':
1438
1469
  return 'The contributors cover meaningfully different periods. The sum is a sum; reading a share of it as a comparison of rates is the mistake this names.';
1439
1470
  case 'contributor-without-clock':
@@ -1441,7 +1472,7 @@ ${bold('EXAMPLES')}
1441
1472
  case 'day-top-label-unknown':
1442
1473
  return "A day drew from more than one contributor, so its dearest label is unknown: each contributor knows its own, and the merged answer needs per-label-per-day spend no document carries.";
1443
1474
  case 'no-claimed-period':
1444
- return 'A contributor stated no window, so its span is all that is known of it — and a log whose latest record is the 5th may be a log of a quiet week or a log that stopped being written on the 5th.';
1475
+ return 'A contributor stated no window, so its span is all that is known of it, and a log whose latest record is the 5th may be a log of a quiet week or a log that stopped being written on the 5th.';
1445
1476
  case 'silence-inside-a-claim':
1446
1477
  return 'A contributor recorded nothing on days it asked for. Whether that is a quiet stretch or an export that stopped is yours to know; the days are named above.';
1447
1478
  case 'claim-not-bounded':
@@ -1466,15 +1497,15 @@ ${bold('EXAMPLES')}
1466
1497
  noTarget: () => 'Name the candidate: --to <model>. trazum models lists the catalogue.',
1467
1498
  unknownModel: (id) => `The catalogue has no price for "${id}", and a comparison against a price nobody has is worse than none. trazum models lists what it knows; a pricing overlay adds what it does not.`,
1468
1499
  heading: (target) => `Switching this traffic to ${target}, measured`,
1469
- saves: (current, target, saving) => `${current} on this log becomes ${target} on the candidate — ${saving} less, on the same tokens.`,
1470
- costs: (current, target, extra) => `${current} on this log becomes ${target} on the candidate — ${extra} MORE. This switch loses money before quality is even asked.`,
1500
+ saves: (current, target, saving) => `${current} on this log becomes ${target} on the candidate, ${saving} less, on the same tokens.`,
1501
+ costs: (current, target, extra) => `${current} on this log becomes ${target} on the candidate, ${extra} MORE. This switch loses money before quality is even asked.`,
1471
1502
  nothingMovable: () => 'Nothing here can move: every slice is already on the candidate or exceeds its context window.',
1472
1503
  movable: (calls, slices) => `${calls} call(s) across ${slices} slice(s) could move.`,
1473
- overContext: (slices, usd) => `${slices} slice(s) worth ${usd} cannot move — at least one call exceeds the candidate's context window. Their money is in none of the figures above.`,
1504
+ overContext: (slices, usd) => `${slices} slice(s) worth ${usd} cannot move, at least one call exceeds the candidate's context window. Their money is in none of the figures above.`,
1474
1505
  alreadyOnTarget: (calls, usd) => `${calls} call(s) worth ${usd} are already on the candidate.`,
1475
- window: (days) => `Measured over ${days} day(s) of this log — every figure above is arithmetic on that window.`,
1506
+ window: (days) => `Measured over ${days} day(s) of this log: every figure above is arithmetic on that window.`,
1476
1507
  noWindow: () => 'No record carries a timestamp, so this log has no measured rate.',
1477
- breakEvenDays: (migration, days, measuredDays) => `A declared migration cost of ${migration} is recovered after ~${days} day(s) at the saving measured over ${measuredDays} day(s). Division on the past — what next month does is next month's business.`,
1508
+ breakEvenDays: (migration, days, measuredDays) => `A declared migration cost of ${migration} is recovered after ~${days} day(s) at the saving measured over ${measuredDays} day(s). Division on the past, what next month does is next month's business.`,
1478
1509
  breakEvenNoSaving: (migration) => `Break-even refused: the switch saves nothing, so the declared ${migration} has nothing to recover.`,
1479
1510
  breakEvenNoClock: (migration) => `Break-even refused for ${migration}: no record carries a timestamp, so there is no measured rate to divide by.`,
1480
1511
  evalCost: (cases, total) => `Knowing whether the candidate is good enough costs money too: ${cases} case(s) through trazum route is ~${total} at this log's own mean call (two calls on the incumbent, one on the candidate, per case).`,
@@ -1484,7 +1515,7 @@ ${bold('EXAMPLES')}
1484
1515
  ownrate: {
1485
1516
  missing: () => 'Both numbers are yours to declare: trazum ownrate --gpu-usd-hour <n> --tokens-per-second <n> [--utilization <0-1>]',
1486
1517
  invalid: (flag) => `--${flag} must be a positive number (utilization: greater than 0, at most 1).`,
1487
- result: (usdPerMTok, tokensPerSecond, gpuUsdPerHour, utilizationPct) => `${usdPerMTok} per million tokens — ${gpuUsdPerHour}/hour over ${tokensPerSecond} tokens/second at ${utilizationPct}% serving.`,
1518
+ result: (usdPerMTok, tokensPerSecond, gpuUsdPerHour, utilizationPct) => `${usdPerMTok} per million tokens, ${gpuUsdPerHour}/hour over ${tokensPerSecond} tokens/second at ${utilizationPct}% serving.`,
1488
1519
  declared: () => 'Derived from your declaration, honest only if the throughput was measured. Every report that prices this model will rest on these two numbers.',
1489
1520
  snippetHeading: () => 'Paste into trazum.config.json (the "pricing" overlay file):',
1490
1521
  },
@@ -1493,34 +1524,64 @@ ${bold('EXAMPLES')}
1493
1524
  notFound: (path) => `${path}: not found`,
1494
1525
  noExports: (path) => `${path}: no .json/.jsonl/.ndjson OTLP exports under it.`,
1495
1526
  summary: (files, llmSpans) => `${files} file(s), ${llmSpans} LLM span(s) priced.`,
1496
- skipped: (otherSpans) => `${otherSpans} non-LLM span(s) skipped — the trace's other work, not a bill.`,
1527
+ skipped: (otherSpans) => `${otherSpans} non-LLM span(s) skipped, the trace's other work, not a bill.`,
1497
1528
  noCache: (count) => `${count} span(s) carried no cache data. OpenTelemetry has not standardised the cache TTL split, so the cache verdicts read "cannot tell" on this log rather than a fabricated one.`,
1498
1529
  unparseable: (count) => `${count} line(s) did not parse as JSON.`,
1499
1530
  written: (file) => `Wrote ${file}.`,
1500
1531
  },
1532
+ fromHelicone: {
1533
+ noPath: () => 'from-helicone needs a request export or a directory: trazum from-helicone requests.json',
1534
+ notFound: (path) => `${path}: not found`,
1535
+ noExports: (path) => `${path}: no .json/.jsonl/.ndjson exports under it. Helicone's requests come out of its POST /v1/request/query endpoint, or the export button on the requests table.`,
1536
+ summary: (files, rows) => `${files} file(s), ${rows} request(s) read.`,
1537
+ unnamedModel: (count) => `${count} row(s) named no model in any of the three columns and are not in the output: nothing on the row says what answered, so nothing can price it.`,
1538
+ disagreements: (count) => `${count} row(s) were answered by a different model than the one requested. The model that answered is what is priced, because a bill is about what was billed; the count is here so a substitution is something you see rather than find inside a total.`,
1539
+ noTokens: (count) => `${count} row(s) carried zero tokens on both sides: logged requests nobody can price. Counted here and worth a look at Helicone.`,
1540
+ cacheFlagged: (count) => `${count} row(s) were served from Helicone's cache. That is a flag on the row and never a token split, so the cache verdicts read "cannot tell" on this log rather than a fabricated one.`,
1541
+ noSessions: () => 'No session identity: a Helicone request id names one call, not a conversation, so the conversation findings (single-turn cache waste, context pressure) cannot be answered from this log. Passing a per-call id off as a conversation would report every call as a conversation of one.',
1542
+ unparseable: (count) => `${count} line(s) did not parse as JSON.`,
1543
+ written: (file) => `Wrote ${file}.`,
1544
+ },
1545
+ fromLiteLlm: {
1546
+ noPath: () => 'from-litellm needs a spend-log export or a directory: trazum from-litellm spend.json',
1547
+ notFound: (path) => `${path}: not found`,
1548
+ noExports: (path) => `${path}: no .json/.jsonl/.ndjson exports under it. LiteLLM's spend logs come out of the LiteLLM_SpendLogs table, or from the proxy's own /spend endpoints.`,
1549
+ summary: (files, rows) => `${files} file(s), ${rows} logged call(s) read.`,
1550
+ unnamedModel: (count) => `${count} row(s) named no model and are not in the output. "model_group" is the name of a proxy route and several models can sit behind one, so pricing those calls by the route they took would attribute a figure to something it does not describe.`,
1551
+ noTokens: (count) => `${count} row(s) carried zero tokens on both sides: logged calls nobody can price. They are counted here and worth a look at the proxy.`,
1552
+ cacheFlagged: (count) => `${count} row(s) are marked as a cache hit. LiteLLM records that as a flag and never as a token split, so the cache verdicts read "cannot tell" on this log rather than a fabricated one.`,
1553
+ reportedSpend: (usd) => `LiteLLM priced these same calls at ${usd} with its own table. That figure is not merged into anything Trazum computes: two price tables summed into one total is how a report becomes quietly wrong. Compare them deliberately or not at all.`,
1554
+ unparseable: (count) => `${count} line(s) did not parse as JSON.`,
1555
+ written: (file) => `Wrote ${file}.`,
1556
+ },
1501
1557
  fromClaudeCode: {
1502
1558
  noPath: () => 'from-claude-code needs a transcript file or directory: trazum from-claude-code ~/.claude/projects',
1503
1559
  notFound: (path) => `${path}: not found`,
1504
1560
  noTranscripts: (path) => `${path}: no .jsonl transcripts under it. Claude Code writes them per session under ~/.claude/projects/<project>/.`,
1505
1561
  summary: (files, records) => `${files} transcript(s), ${records} priced call(s).`,
1506
- collapsed: (lines) => `${lines} extra line(s) of already-counted calls collapsed — one API call is written as one line per content block, and counting each line would overbill.`,
1562
+ collapsed: (lines) => `${lines} extra line(s) of already-counted calls collapsed: one API call is written as one line per content block, and counting each line would overbill.`,
1507
1563
  streamed: (count) => `${count} call(s) were written while still streaming; the final line's counts stood.`,
1508
- disagreements: (count) => `${count} call(s) had lines that disagreed beyond streaming growth — a count shrank, or another field changed. The last line stood, but that is a finding: worth a look at the transcript.`,
1564
+ disagreements: (count) => `${count} call(s) had lines that disagreed beyond streaming growth: a count shrank, or another field changed. The last line stood, but that is a finding: worth a look at the transcript.`,
1509
1565
  noRequestId: (count) => `${count} call(s) carried no request id, so nothing could be collapsed against them; each is priced as recorded.`,
1510
1566
  synthetic: (count) => `${count} turn(s) Claude Code wrote itself (model "<synthetic>") are not in the output: no provider ever billed them, so they are not calls.`,
1511
1567
  labelled: () => 'Labelled by project folder. Pass --no-label-from-project to leave the label off, or --label <name> to set one.',
1512
1568
  skipped: (other, unparseable, withoutUsage) => `Passed over: ${other} non-assistant line(s) (the transcript's other business), ${unparseable} unparseable, ${withoutUsage} assistant line(s) without usage.`,
1513
1569
  written: (file) => `Wrote ${file}.`,
1570
+ stateNeedsFile: () => '--state reads one transcript, not a folder: the state ties an offset in the transcript to a length of the output, and several transcripts appending to one output have no single such length. Point it at the .jsonl file.',
1571
+ stateNeedsOut: () => '--state needs --out: there is nothing to resume against when the records go to stdout.',
1572
+ resumed: (skipped, offset) => skipped === 0
1573
+ ? `Read the transcript in full and recorded a resume point at byte ${offset}.`
1574
+ : `Resumed at byte ${skipped}, so ${skipped} byte(s) were not re-read. Next resume point: byte ${offset}.`,
1514
1575
  },
1515
1576
  position: {
1516
1577
  heading: (month) => `Where ${month} stands, measured`,
1517
1578
  scopeMonth: () => 'the month',
1518
1579
  scopeDay: () => 'today',
1519
1580
  scopeLabel: (label) => `"${label}"`,
1520
- within: (scope, measured, limit, remaining, days, elapsed) => `${scope}: ${measured} of ${limit} measured — ${remaining} left (${days} of ${elapsed} elapsed days measured)`,
1521
- over: (scope, measured, limit, overBy) => `${scope}: over — ${measured} measured against ${limit}, ${overBy} past the ceiling`,
1522
- cannotTell: (scope) => `${scope}: cannot tell — nothing measured in this window`,
1523
- distance: (days, rate, overDays) => `at ${rate}/day over ${overDays} measured days, the ceiling is ${days} days away — division on the past, not a forecast`,
1581
+ within: (scope, measured, limit, remaining, days, elapsed) => `${scope}: ${measured} of ${limit} measured, ${remaining} left (${days} of ${elapsed} elapsed days measured)`,
1582
+ over: (scope, measured, limit, overBy) => `${scope}: over, ${measured} measured against ${limit}, ${overBy} past the ceiling`,
1583
+ cannotTell: (scope) => `${scope}: cannot tell, because nothing was measured in this window`,
1584
+ distance: (days, rate, overDays) => `at ${rate}/day over ${overDays} measured days, the ceiling is ${days} days away, division on the past, not a forecast`,
1524
1585
  unmeasuredHeading: () => 'Configured and not measurable from this log',
1525
1586
  unmeasured: (scope, why) => `${scope}: ${why}`,
1526
1587
  why: (reason) => reason === 'no-clock'
@@ -1528,8 +1589,8 @@ ${bold('EXAMPLES')}
1528
1589
  : reason === 'no-labels'
1529
1590
  ? 'no record carries a label, so per-label spend is unknowable here'
1530
1591
  : reason === 'nothing-recorded'
1531
- ? 'the log is empty — nothing was recorded'
1532
- : 'the log records labels and has never seen this one this month — possibly renamed, possibly idle, and neither is "under budget"',
1592
+ ? 'the log is empty: nothing was recorded'
1593
+ : 'the log records labels and has never seen this one this month, possibly renamed, possibly idle, and neither is "under budget"',
1533
1594
  cannotSayHeading: () => 'What this deliberately does not answer',
1534
1595
  cannotSay: (code) => {
1535
1596
  switch (code) {
@@ -1541,8 +1602,8 @@ ${bold('EXAMPLES')}
1541
1602
  return code;
1542
1603
  }
1543
1604
  },
1544
- unpriced: (count) => `${count} record(s) name a model the catalogue cannot price. They contribute nothing to any figure above — money nobody can see, said here rather than hidden.`,
1545
- source: () => 'Measured from this log alone, priced record by record. The store\'s provider-billed monthly standing is a different measurement — "trazum store" prints it — and the two are never merged into one figure.',
1605
+ unpriced: (count) => `${count} record(s) name a model the catalogue cannot price. They contribute nothing to any figure above: money nobody can see, said here rather than hidden.`,
1606
+ source: () => 'Measured from this log alone, priced record by record. The store\'s provider-billed monthly standing is a different measurement, "trazum store" prints it, and the two are never merged into one figure.',
1546
1607
  noLog: () => 'position needs a usage log: trazum position usage.jsonl',
1547
1608
  },
1548
1609
  pulse: {
@@ -1559,16 +1620,16 @@ ${bold('EXAMPLES')}
1559
1620
  return kind;
1560
1621
  }
1561
1622
  },
1562
- neverRun: (name) => `${name}: never here. Not late — there is no cadence to be late against.`,
1623
+ neverRun: (name) => `${name}: never here. Not late: there is no cadence to be late against.`,
1563
1624
  age: (name, when, hours) => `${name}: ${when}Z, ${plural(hours, 'hour')} ago`,
1564
1625
  noThreshold: () => 'Nothing was judged. Pass --max-stale-hours <n> to make a run that stopped a failing exit code; how stale is too stale is a policy, and this tool does not write yours.',
1565
1626
  within: (hours) => `Everything that has run here ran within ${plural(hours, 'hour')}.`,
1566
1627
  stale: (hours) => `Something that runs here has not run in over ${plural(hours, 'hour')}. Silence from a scheduled job and silence from a job with nothing to report look identical; this is which.`,
1567
- notAService: () => 'This command runs nothing and hosts nothing. Something has to notice, and the something is your CI: a step that runs this on the schedule you already have turns a dead cron into a red build, without Trazum holding anybody\'s metrics. How far the measurements reach is reported and never judged — that is a provider reporting on its own schedule, not a job that failed.',
1628
+ notAService: () => 'This command runs nothing and hosts nothing. Something has to notice, and the something is your CI: a step that runs this on the schedule you already have turns a dead cron into a red build, without Trazum holding anybody\'s metrics. How far the measurements reach is reported and never judged: that is a provider reporting on its own schedule, not a job that failed.',
1568
1629
  },
1569
1630
  html: {
1570
1631
  caveatsHeading: () => 'What this report cannot say',
1571
- noClock: () => 'No record carried a timestamp, so days, rates and drift are not in this report — a total is still a total.',
1632
+ noClock: () => 'No record carried a timestamp, so days, rates and drift are not in this report: a total is still a total.',
1572
1633
  noSessions: () => 'No record carried a session, so conversation growth and per-conversation costs are not in this report.',
1573
1634
  byLabelHeading: () => 'By workload',
1574
1635
  byModelHeading: () => 'By model',
@@ -1587,7 +1648,7 @@ ${bold('EXAMPLES')}
1587
1648
  written: (path) => `HTML report written to ${path}.`,
1588
1649
  },
1589
1650
  schema: {
1590
- noTarget: (known) => `Name a contract to print its JSON Schema. Known: ${known}. The schema validates with any draft 2020-12 validator — no Trazum required.`,
1651
+ noTarget: (known) => `Name a contract to print its JSON Schema. Known: ${known}. The schema validates with any draft 2020-12 validator, no Trazum required.`,
1591
1652
  unknown: (name, known) => `"${name}" is not a contract. Known: ${known}.`,
1592
1653
  },
1593
1654
  bench: {
@@ -1597,7 +1658,7 @@ ${bold('EXAMPLES')}
1597
1658
  colWall: () => 'wall ms',
1598
1659
  colRatio: () => 'ratio',
1599
1660
  colPeakRss: () => 'peak RSS',
1600
- note: () => 'One shot each, this machine, today. The wall clock is for a person reading two tables side by side; the ratio — workload over an in-process calibration loop — is the number a gate can hold, because the machine cancels out of it. Record one with --record, hold a build to it with --against and a stated --max-ratio.',
1661
+ note: () => 'One shot each, this machine, today. The wall clock is for a person reading two tables side by side; the ratio, workload over an in-process calibration loop, is the number a gate can hold, because the machine cancels out of it. Record one with --record, hold a build to it with --against and a stated --max-ratio.',
1601
1662
  unknownWorkload: (id, known) => `Unknown workload "${id}". Known: ${known}.`,
1602
1663
  recorded: (path) => `Baseline written to ${path}. Commit it; --against reads it.`,
1603
1664
  needsMaxRatio: () => '--against needs --max-ratio <n>. How much regression is too much is a policy, and this tool does not write yours.',
@@ -1612,19 +1673,19 @@ ${bold('EXAMPLES')}
1612
1673
  },
1613
1674
  where: {
1614
1675
  hostHeading: () => 'Running inside',
1615
- subscription: (host) => `${host} bills by subscription, not by the token. A monthly saving below is arithmetic about tokens, not money you get back — what you gain is context window and rate-limit headroom.`,
1676
+ subscription: (host) => `${host} bills by subscription, not by the token. A monthly saving below is arithmetic about tokens, not money you get back, what you gain is context window and rate-limit headroom.`,
1616
1677
  noTarget: () => 'Pass a source file to see which provider its prompts are sent to.',
1617
1678
  sourceHeading: (path) => `Prompts in ${path} go to`,
1618
1679
  conflict: () => 'Cannot tell: the file names more than one provider.',
1619
1680
  conflictFallback: () => 'Nothing was assumed. Set "usage.model" in trazum.config.json, or pass --model.',
1620
1681
  nothingFound: () => 'Nothing in this file says which provider it calls.',
1621
- providerOnly: () => ' (provider only — nothing named a model)',
1682
+ providerOnly: () => ' (provider only, nothing named a model)',
1622
1683
  evidenceLine: (line, kind, detail) => `line ${line} ${kind}: ${detail}`,
1623
1684
  pricedAs: () => 'Priced as',
1624
1685
  fromConfig: () => '(from trazum.config.json)',
1625
1686
  fromDetection: () => '(read from the source)',
1626
1687
  fromProviderDefault: (provider) => `(${provider} was read from the source; nothing named a model, so this is theirs)`,
1627
- fromDefault: () => '(the built-in default — nothing said otherwise)',
1688
+ fromDefault: () => '(the built-in default, nothing said otherwise)',
1628
1689
  },
1629
1690
  pricing: {
1630
1691
  liveLoaded: (added, refreshed, skipped) => `Live prices: ${refreshed} refreshed, ${added} models added, ${skipped} skipped for having no usable price or context window. Caching minimums are not published by this source, so caching advice is withheld for the added models.`,
@@ -1657,13 +1718,13 @@ ${bold('EXAMPLES')}
1657
1718
  noteExamples: (count, tokens) => `${count} examples, ~${tokens} tokens`,
1658
1719
  noteFormat: (tokens) => `~${tokens} tokens restating the output format`,
1659
1720
  noteProtected: (pct) => `${pct}% is code or URLs, which cannot be trimmed`,
1660
- skipped: (count) => `Skipped ${count} source ${count === 1 ? 'file' : 'files'} with no \`// trazum:prompt\` marker — `
1721
+ skipped: (count) => `Skipped ${count} source ${count === 1 ? 'file' : 'files'} with no \`// trazum:prompt\` marker, `
1661
1722
  + 'their prompts are not in this ranking.',
1662
- densityNote: () => 'Tok/sen is tokens per sentence: verbosity independent of length. There is no score — every column is a measurement you can check against the file.',
1663
- recoverableNote: () => 'Recover is what the deterministic rules would take at this level, priced by the usage profile, with the token count beside it — a saving of one token is twenty-five cents and no work worth doing. It is measured by running the rules, not by a formula.',
1723
+ densityNote: () => 'Tok/sen is tokens per sentence: verbosity independent of length. There is no score. Every column is a measurement you can check against the file.',
1724
+ recoverableNote: () => 'Recover is what the deterministic rules would take at this level, priced by the usage profile, with the token count beside it: a saving of one token is twenty-five cents and no work worth doing. It is measured by running the rules, not by a formula.',
1664
1725
  },
1665
1726
  blame: {
1666
- heading: (path, revisions) => `${path} — ${revisions} ${revisions === 1 ? 'revision' : 'revisions'}`,
1727
+ heading: (path, revisions) => `${path}, ${revisions} ${revisions === 1 ? 'revision' : 'revisions'}`,
1667
1728
  notARepository: () => 'blame reads a file\'s history from git, and this directory is not inside a repository.',
1668
1729
  outsideRepository: (path) => `${path} is outside the repository, so there is no history to read.`,
1669
1730
  noHistory: (path) => `git has no commits touching ${path}.`,
@@ -1672,12 +1733,12 @@ ${bold('EXAMPLES')}
1672
1733
  net: (first, last, delta, pct) => `Net across this history: ${first} → ${last} tokens (${delta}, ${pct}).`,
1673
1734
  netCost: (amount, model, calls) => `That movement is ${amount} a month on ${model} at ${calls} calls.`,
1674
1735
  biggestRise: () => 'Biggest single increase',
1675
- biggestRiseDetail: (tokens, author, subject, sha) => `+${tokens} tokens — ${author}, "${subject}" (${sha})`,
1736
+ biggestRiseDetail: (tokens, author, subject, sha) => `+${tokens} tokens, ${author}, "${subject}" (${sha})`,
1676
1737
  addedAt: () => 'added',
1677
1738
  goneAt: () => 'not present',
1678
1739
  truncated: (shown) => `Showing the most recent ${shown}. Pass --limit for more.`,
1679
1740
  followedRename: (from) => `Followed a rename: earlier revisions are ${from}.`,
1680
- estimateNote: () => 'Token counts are estimates (±10%). The trend is the point; the absolute figures are not.',
1741
+ estimateNote: (band) => `Token counts are estimates (±${band}% for text of this kind). The trend is the point; the absolute figures are not.`,
1681
1742
  },
1682
1743
  languages: {
1683
1744
  and: 'and',
@@ -1692,19 +1753,19 @@ ${bold('EXAMPLES')}
1692
1753
  rules: {
1693
1754
  title: () => 'Available rules',
1694
1755
  disableHint: () => ' Turn off the ones you do not want with --disable id1,id2',
1695
- measureHeading: (root, prompts, level) => `What each rule recovers in ${root} — ${plural(prompts, 'prompt')}, level ${level}`,
1756
+ measureHeading: (root, prompts, level) => `What each rule recovers in ${root}, ${plural(prompts, 'prompt')}, level ${level}`,
1696
1757
  measureTotals: (before, saved, floor) => `${before} tokens before. The rules recover ${saved}; normalisation recovers ${floor} whether a rule is enabled or not, and that is not the rules' work.`,
1697
1758
  measureRow: (id, marginal, alone, prompts) => `${id.padEnd(22)} lost if removed ${marginal.padStart(6)} alone ${alone.padStart(6)} ${plural(prompts, 'prompt')}`,
1698
- measureOverlap: (sumOfAlone, saved) => `The rules recover ${sumOfAlone} between them one at a time and ${saved} together. The gap is the overlap — two rules finding the same tokens — and it is stated rather than resolved into a total, because a single figure here is the one number that cannot be true.`,
1699
- measureRedundant: (ids) => `Every token these find, something else finds too, here: ${ids}. An overlap, not a defect — and not a reason to delete one without deciding which is the better to keep.`,
1700
- measureFiredWithoutSaving: (ids) => `These changed the prompt and recovered no tokens: ${ids}. Not the same as inert — they were exercised, and they are altering somebody's instruction for no measured benefit.`,
1759
+ measureOverlap: (sumOfAlone, saved) => `The rules recover ${sumOfAlone} between them one at a time and ${saved} together. The gap is the overlap: two rules finding the same tokens, and it is stated rather than resolved into a total, because a single figure here is the one number that cannot be true.`,
1760
+ measureRedundant: (ids) => `Every token these find, something else finds too, here: ${ids}. An overlap, not a defect, and not a reason to delete one without deciding which is the better to keep.`,
1761
+ measureFiredWithoutSaving: (ids) => `These changed the prompt and recovered no tokens: ${ids}. Not the same as inert: they were exercised, and they are altering somebody's instruction for no measured benefit.`,
1701
1762
  measureInert: (ids) => `These changed nothing in this corpus: ${ids}. That is a fact about these files, not about the rules: a rule that finds nothing here has not been shown to find nothing anywhere.`,
1702
1763
  measureBand: (source) => source === 'heuristic'
1703
1764
  ? 'Counted with the built-in estimator, so every figure above carries its documented band. A rule whose yield is a handful of tokens is inside the noise.'
1704
1765
  : 'Counted with an external tokenizer.',
1705
1766
  },
1706
1767
  doctor: {
1707
- heading: (root, prompts) => `${root} — ${prompts} ${prompts === 1 ? 'prompt' : 'prompts'}`,
1768
+ heading: (root, prompts) => `${root}, ${prompts} ${prompts === 1 ? 'prompt' : 'prompts'}`,
1708
1769
  subheading: (model, calls) => `Priced on ${model} at ${calls} calls a month.`,
1709
1770
  pricesReviewed: (date, days) => `Prices reviewed ${date}${ago(days)}.`,
1710
1771
  budgetsHeading: () => 'Budgets',
@@ -1713,14 +1774,14 @@ ${bold('EXAMPLES')}
1713
1774
  : `All ${count} prompts have a budget and are inside it.`,
1714
1775
  unbudgeted: (count, total) => `${count} of ${total} ${count === 1 ? 'prompt has' : 'prompts have'} no budget, so nothing is watching ${count === 1 ? 'it' : 'them'}`,
1715
1776
  overBudget: (count) => count === 1
1716
- ? '1 prompt is already over its budget — trazum check would fail on it'
1717
- : `${count} prompts are already over their budget — trazum check would fail on them`,
1777
+ ? '1 prompt is already over its budget: trazum check would fail on it'
1778
+ : `${count} prompts are already over their budget: trazum check would fail on them`,
1718
1779
  andMore: (count) => `and ${count} more`,
1719
1780
  findingsHeading: () => 'What it would be worth fixing',
1720
1781
  acrossPrompts: (count) => `${count} ${count === 1 ? 'prompt' : 'prompts'}`,
1721
1782
  findingsNote: () => 'Each line is the same advisory trazum optimize raises on those prompts, summed. '
1722
1783
  + 'Run it on any one of them to see the figure on its own.',
1723
- notAGate: () => 'Nothing here fails a build. trazum check is the gate; this is the survey — the '
1784
+ notAGate: () => 'Nothing here fails a build. trazum check is the gate; this is the survey: the '
1724
1785
  + 'model recommendation is a keyword heuristic, and a build gated on one teaches '
1725
1786
  + 'people to re-run until green.',
1726
1787
  sharedPrefixHeading: () => 'Preambles that could share a cache entry and do not',
@@ -1730,9 +1791,9 @@ ${bold('EXAMPLES')}
1730
1791
  : 'differing in wording, capitalisation or punctuation'),
1731
1792
  sharedPrefixFix: (drift) => drift === 'whitespace'
1732
1793
  ? 'A formatter fixes this: the text already agrees, only the spacing does not.'
1733
- : 'Someone has to pick one wording — the text itself differs, not just its spacing.',
1794
+ : 'Someone has to pick one wording, the text itself differs, not just its spacing.',
1734
1795
  sharedPrefixNoFigure: () => 'No figure is attached, deliberately. Caching matches bytes, so these prompts hold '
1735
- + 'one cache entry each instead of one between them — but what that costs depends on '
1796
+ + 'one cache entry each instead of one between them, but what that costs depends on '
1736
1797
  + 'how the calls are spread across the group, and Trazum applies a single '
1737
1798
  + '--cache-hit-rate to every prompt. Pricing it would mean inventing your traffic.',
1738
1799
  },
@@ -1745,13 +1806,13 @@ ${bold('EXAMPLES')}
1745
1806
  heading: (model) => `What each example is doing, measured on ${model}`,
1746
1807
  selfAgreement: (pct) => `The prompt agrees with itself ${pct} of the time. That is the yardstick: a removal `
1747
1808
  + 'that moves the answer less than this moved nothing attributable to the example.',
1748
- line: (n, tokens, pct) => `example ${n} — ${tokens} tokens, ${pct} agreement without it`,
1809
+ line: (n, tokens, pct) => `example ${n}, ${tokens} tokens, ${pct} agreement without it`,
1749
1810
  verdictNeeded: () => 'needed here',
1750
1811
  verdictRecoverable: () => 'no effect on these inputs',
1751
1812
  verdictUnknown: () => 'inconclusive',
1752
1813
  recoverable: (tokens) => `${tokens} tokens sit in examples whose removal changed nothing measurable here.`,
1753
1814
  caveat: () => 'Which is not the same as "delete them". An example may exist for a case these '
1754
- + 'inputs do not contain — the boundary condition somebody hit in production and '
1815
+ + 'inputs do not contain, the boundary condition somebody hit in production and '
1755
1816
  + 'added a demonstration for. This measures the inputs you gave it, and only you '
1756
1817
  + 'know whether they cover what matters. Nothing was edited.',
1757
1818
  },
@@ -1799,13 +1860,13 @@ ${bold('EXAMPLES')}
1799
1860
  someOverLimit: (count, max) => `${count} ${count === 1 ? 'prompt grew' : 'prompts grew'} past the per-prompt limit of ${max} tokens:`,
1800
1861
  allSubheading: (prompts) => `${prompts} ${prompts === 1 ? 'prompt' : 'prompts'} on both sides.`,
1801
1862
  allTotal: (delta, prompts) => `${delta} tokens across ${prompts} ${prompts === 1 ? 'prompt' : 'prompts'}`,
1802
- signConvention: () => 'Every figure is after minus before, so positive means worse — the opposite of the rest of Trazum.',
1863
+ signConvention: () => 'Every figure is after minus before, so positive means worse, the opposite of the rest of Trazum.',
1803
1864
  onlyBefore: () => 'only before',
1804
1865
  onlyAfter: () => 'only after ',
1805
1866
  onlyOneSideNote: () => 'Not counted in the totals. A prompt that vanished is a question, not a saving.',
1806
1867
  },
1807
1868
  markdown: {
1808
- checkHeading: (target) => `Trazum — token budgets for ${target}`,
1869
+ checkHeading: (target) => `Trazum, token budgets for ${target}`,
1809
1870
  baselineGrew: (delta, pct) => `This branch adds ${delta} tokens (${pct}) to the prompts here`,
1810
1871
  baselineShrank: (delta, pct) => `This branch removes ${delta} tokens (${pct}) from the prompts here`,
1811
1872
  baselineUnchanged: () => 'No change against the recorded baseline',
@@ -1817,9 +1878,9 @@ ${bold('EXAMPLES')}
1817
1878
  baselineMoney: (before, after, delta) => `Monthly cost **${before} \u2192 ${after}** (${delta})`,
1818
1879
  baselineMoneyIncomparable: () => 'The scenario or the price list moved since the baseline was recorded, so the two monthly figures are not the same measurement and are not subtracted here. The token comparison above is unaffected.',
1819
1880
  baselineReRecord: (command, path) => `If this growth is intended, re-record with \`${command}\` and commit \`${path}\`.`,
1820
- diffHeading: (before, after) => `Trazum — ${before} → ${after}`,
1821
- rankHeading: (root, count) => `Trazum — what to fix first in ${root} (${count} ${count === 1 ? "prompt" : "prompts"})`,
1822
- blameHeading: (path) => `Trazum — token history for ${path}`,
1881
+ diffHeading: (before, after) => `Trazum, ${before} → ${after}`,
1882
+ rankHeading: (root, count) => `Trazum, what to fix first in ${root} (${count} ${count === 1 ? "prompt" : "prompts"})`,
1883
+ blameHeading: (path) => `Trazum, token history for ${path}`,
1823
1884
  rankLevel: (level) => `Measured at rule level \`${level}\`.`,
1824
1885
  columnFile: () => 'Prompt',
1825
1886
  columnTokens: () => 'Tokens',
@@ -1830,7 +1891,7 @@ ${bold('EXAMPLES')}
1830
1891
  ? 'The prompt is within budget.'
1831
1892
  : `All ${budgeted} budgeted prompts are within budget.`,
1832
1893
  overBudget: (failures, budgeted) => `${failures} of ${budgeted} over budget`,
1833
- noBudget: () => '—',
1894
+ noBudget: () => 'none',
1834
1895
  unbudgetedNote: (count) => count === 1
1835
1896
  ? '1 prompt is not covered by any budget pattern, so nothing is watching it.'
1836
1897
  : `${count} prompts are not covered by any budget pattern, so nothing is watching them.`,
@@ -1840,7 +1901,7 @@ ${bold('EXAMPLES')}
1840
1901
  truncated: () => 'Stopped early: the directory is larger than the walk limit, so this is not the whole picture.',
1841
1902
  footer: (source, level) => `Token counts ${source} · rule level \`${level}\``,
1842
1903
  pricingOverlaid: (count, lastReviewed) => `Prices for ${count} ${count === 1 ? 'model' : 'models'} came from a local overlay reviewed ${lastReviewed}.`,
1843
- sourceEstimated: () => 'estimated, ±10%',
1904
+ sourceEstimated: (band) => `estimated, ±${band}%`,
1844
1905
  sourceExact: () => 'counted exactly',
1845
1906
  measuringOptimised: () => 'Measuring what the rules would leave, not what is written in the file.',
1846
1907
  metricTokens: (before, after) => `Input tokens (${before} → ${after})`,
@@ -1857,7 +1918,7 @@ ${bold('EXAMPLES')}
1857
1918
  },
1858
1919
  check: {
1859
1920
  okLabel: () => 'OK',
1860
- embeddedHeading: (path, count) => `${path} — ${count} marked ${count === 1 ? 'prompt' : 'prompts'}`,
1921
+ embeddedHeading: (path, count) => `${path}, ${count} marked ${count === 1 ? 'prompt' : 'prompts'}`,
1861
1922
  declinedHeading: (count) => `${count} ${count === 1 ? 'marker' : 'markers'} could not be read:`,
1862
1923
  declinedAt: (line, detail) => `line ${line}: ${detail}`,
1863
1924
  failedLabel: () => 'FAILED',
@@ -1865,18 +1926,18 @@ ${bold('EXAMPLES')}
1865
1926
  failed: (tokens, budget) => `${tokens} tokens busts the budget of ${budget}.`,
1866
1927
  wouldFit: (level, optimizedTokens) => ` Optimised with "trazum optimize --level ${level}" it would land at ~${optimizedTokens} tokens and fit.`,
1867
1928
  stillTooBig: (optimizedTokens) => ` Even optimised it does not fit (~${optimizedTokens} tokens): content has to be cut by hand.`,
1868
- directoryHeading: (directory, files) => `${directory} — ${files} ${files === 1 ? 'prompt' : 'prompts'}`,
1929
+ directoryHeading: (directory, files) => `${directory}, ${files} ${files === 1 ? 'prompt' : 'prompts'}`,
1869
1930
  directorySummary: (failures, files) => failures === 0
1870
1931
  ? `All ${files} within budget.`
1871
1932
  : `${failures} of ${files} over budget.`,
1872
1933
  noBudget: () => '(no budget)',
1873
1934
  walkTruncated: () => 'Stopped early: the directory is larger than the walk limit, so this is not the whole picture.',
1874
- filesFromSummary: (checked, listed, dropped) => `Checking ${checked} of ${listed} listed file(s) — ${dropped} dropped: not a prompt extension, ignored by config, or no longer on disk.`,
1935
+ filesFromSummary: (checked, listed, dropped) => `Checking ${checked} of ${listed} listed file(s), ${dropped} dropped: not a prompt extension, ignored by config, or no longer on disk.`,
1875
1936
  filesFromNoBaseline: () => 'The baseline gate is skipped under --files-from: it compares the whole repository against the committed record, and a partial list would read as removals. Budgets are checked per file as always; run "trazum check ." for the baseline.',
1876
1937
  exactCountsCost: (files) => `Counting ${files} ${files === 1 ? 'file' : 'files'} through the API, one call each. This takes a moment.`,
1877
1938
  },
1878
1939
  profile: {
1879
- noTarget: () => 'Point this at a usage log: trazum profile usage.jsonl — one JSON object per line, each with a "model" and the "usage" object the API returned. Add "label" (which workload), "session" (which conversation) and "ts" (when) while you are there: without them every call looks alike, and the largest findings this command makes — conversation growth, and whether the cache TTL fits how fast your turns come — cannot be made at all. Recording it is four lines in your own code, it never contains prompt text, and the session key is grouped by and never printed.',
1940
+ noTarget: () => 'Point this at a usage log: trazum profile usage.jsonl, one JSON object per line, each with a "model" and the "usage" object the API returned. Add "label" (which workload), "session" (which conversation) and "ts" (when) while you are there: without them every call looks alike, and the largest findings this command makes, conversation growth, and whether the cache TTL fits how fast your turns come, cannot be made at all. Recording it is four lines in your own code, it never contains prompt text, and the session key is grouped by and never printed.',
1880
1941
  heading: () => 'Where the money went',
1881
1942
  calls: (n) => plural(n, 'call'),
1882
1943
  spent: (calls, total) => `${calls} · ${total}`,
@@ -1889,11 +1950,11 @@ ${bold('EXAMPLES')}
1889
1950
  byModelHeading: () => 'By model',
1890
1951
  row: (name, usd, pct, calls) => `${usd.padStart(11)} ${pct.padStart(5)} ${name} (${calls})`,
1891
1952
  // Parenthesised so a real label named "unlabelled" cannot read identically
1892
- // beside it — the data already keeps them apart; the display should too.
1953
+ // beside it, the data already keeps them apart; the display should too.
1893
1954
  unlabelled: () => '(no label)',
1894
1955
  cacheHit: (pct) => `Cache hit rate ${pct} of billable input.`,
1895
1956
  cacheNever: () => 'Caching was never used on these calls. If any prefix repeats, that is the largest saving available.',
1896
- cacheLost: (usd, writes, reads) => `Caching added ${usd} to this bill instead of taking it off. ${writes} tokens were written to the cache and ${reads} read back — and a write costs 1.25x plain input, or 2x at the 1-hour TTL. A prefix that changes faster than it is reused pays that premium for nothing. Either cache a prefix that holds still, or turn caching off here.`,
1957
+ cacheLost: (usd, writes, reads) => `Caching added ${usd} to this bill instead of taking it off. ${writes} tokens were written to the cache and ${reads} read back, and a write costs 1.25x plain input, or 2x at the 1-hour TTL. A prefix that changes faster than it is reused pays that premium for nothing. Either cache a prefix that holds still, or turn caching off here.`,
1897
1958
  cachePaidOff: (usd) => `Caching took ${usd} off this bill, against the same tokens uncached.`,
1898
1959
  cacheNoDifference: () => 'Caching came out level on this bill: what it charged for these tokens is what they would have cost as ordinary input. It is neither paying for itself nor costing you anything.',
1899
1960
  cacheLostBy: (labels) => `The loss is in: ${labels}.`,
@@ -1904,155 +1965,155 @@ ${bold('EXAMPLES')}
1904
1965
  cacheTtlUnsettledLabels: (labels) => `These would be losing money if their unrecorded writes used the 1-hour TTL: ${labels}.`,
1905
1966
  biggestPart: (name, pct) => `${name} is ${pct} of this bill.`,
1906
1967
  outputDominates: (pct) => `Output is ${pct} of this bill, so shortening prompts has a low ceiling here. What moves it is asking for shorter answers and capping max_tokens.`,
1907
- unpriced: (models, calls) => `${count(calls)} ${calls === 1 ? 'call is' : 'calls are'} not in these totals — the pricing catalogue does not know: ${models}. Add them with a pricing overlay (--pricing) to include them.`,
1968
+ unpriced: (models, calls) => `${count(calls)} ${calls === 1 ? 'call is' : 'calls are'} not in these totals, because the pricing catalogue does not know: ${models}. Add them with a pricing overlay (--pricing) to include them.`,
1908
1969
  skipped: (lineCount, lines) => `${count(lineCount)} ${lineCount === 1 ? 'line' : 'lines'} could not be read and ${lineCount === 1 ? 'was' : 'were'} left out (${lineCount === 1 ? 'line' : 'lines'} ${lines}).`,
1909
1970
  empty: () => 'No usage records in that file.',
1910
1971
  nothingPriced: () => 'None of the models in that log are in the pricing catalogue, so there is no bill to report. Add them with a pricing overlay (--pricing) and run this again.',
1911
1972
  leversHeading: () => 'What would actually move this bill',
1912
- leverSlice: (label, model, usd, pct) => `${label} on ${model} — up to ${usd} of this bill (${pct})`,
1973
+ leverSlice: (label, model, usd, pct) => `${label} on ${model}, up to ${usd} of this bill (${pct})`,
1913
1974
  leverRoute: (candidate, usd) => `route it to ${candidate}, ${usd}`,
1914
1975
  leverRouteVerify: (candidate) => `Whether that holds is an evaluation question, not an arithmetic one, and nothing here has seen a single answer. Measure it: trazum route <log> --prompt-file <prompt> --cases <cases> --yes`,
1915
1976
  leverBatch: (usd) => `send it through the Batch API, ${usd}`,
1916
1977
  leverCalls: (calls, spent) => `${calls}, ${spent} spent`,
1917
- leverPromptCeiling: (usd, pct) => `For comparison: shortening the prompt text can touch ${usd} at the very most — ${pct} of this bill, and only if you deleted every input token. The real figure is far below that, because most of those tokens are retrieved context, conversation history and tool results that no prompt file contains.`,
1978
+ leverPromptCeiling: (usd, pct) => `For comparison: shortening the prompt text can touch ${usd} at the very most, ${pct} of this bill, and only if you deleted every input token. The real figure is far below that, because most of those tokens are retrieved context, conversation history and tool results that no prompt file contains.`,
1918
1979
  historyHeading: () => 'What re-sending the conversation costs',
1919
1980
  historyGrowth: (label, model, first, last, turns) => `${label} on ${model}: input ranges from ${first} tokens on the smallest turn to ${last} on the largest, over conversations of up to ${turns} turns.`,
1920
- historyCeiling: (usd, pct, flat, spent) => `If every turn had been the size of its smallest one, that input would have cost ${flat} instead of ${spent} — so at most ${usd} of this bill is conversation growth (${pct}). It is a ceiling and not a saving: some of that is the user's own new messages, which nothing can truncate away, and this reads counts rather than content so it cannot tell the two apart. What moves it is capping the history you replay, or summarising it.`,
1921
- truncatedWaste: (calls, usd, pct) => `${calls} hit the max_tokens ceiling: ${usd} of the output spend (${pct}) bought answers that were cut off mid-generation — paid in full, frequently retried and billed again. Where the answer genuinely needs the room, raise max_tokens; where it does not, ask for less. Either way this is the one slice of a bill that is waste without a counterpart.`,
1981
+ historyCeiling: (usd, pct, flat, spent) => `If every turn had been the size of its smallest one, that input would have cost ${flat} instead of ${spent}, so at most ${usd} of this bill is conversation growth (${pct}). It is a ceiling and not a saving: some of that is the user's own new messages, which nothing can truncate away, and this reads counts rather than content so it cannot tell the two apart. What moves it is capping the history you replay, or summarising it.`,
1982
+ truncatedWaste: (calls, usd, pct) => `${calls} hit the max_tokens ceiling: ${usd} of the output spend (${pct}) bought answers that were cut off mid-generation, paid in full, frequently retried and billed again. Where the answer genuinely needs the room, raise max_tokens; where it does not, ask for less. Either way this is the one slice of a bill that is waste without a counterpart.`,
1922
1983
  againstHeading: () => 'Against the previous log',
1923
- againstTotals: (before, after, delta, pct, callsBefore, callsAfter) => `${before} → ${after} ${delta} (${pct}) ${callsBefore} → ${callsAfter}. Positive means the bill grew. Both figures are exactly what each file holds — no period is assumed, so judge the call counts before judging the money.`,
1984
+ againstTotals: (before, after, delta, pct, callsBefore, callsAfter) => `${before} → ${after} ${delta} (${pct}) ${callsBefore} → ${callsAfter}. Positive means the bill grew. Both figures are exactly what each file holds, no period is assumed, so judge the call counts before judging the money.`,
1924
1985
  againstDriver: (delta, label, before, after) => `${delta} ${label} (${before} → ${after})`,
1925
1986
  againstDriverNew: (delta, label) => `${delta} ${label} (new since the previous log)`,
1926
1987
  againstDriverGone: (delta, label) => `${delta} ${label} (gone since the previous log)`,
1927
- againstByModel: () => 'The same change, by model — where the mix moved:',
1928
- labelPrefixBelowMinimum: (file, prefix, minimum, model) => `${file} (as it is today — the log may predate it): the stable prefix is ${prefix} tokens and ${model} caches nothing under ${minimum}. Setting cache_control there does not error, it simply never caches — which is what a cache that only writes looks like from the bill.`,
1929
- labelPrefixMovable: (file, movable, prefix) => `${file} (as it is today — the log may predate it): ~${movable} stable tokens sit after the first placeholder, where caching cannot reach them; the cacheable prefix is ${prefix}. "trazum optimize ${file} --reorder" moves them in front and shows the diff.`,
1930
- labelPrefixHealthy: (file, prefix, minimum) => `${file} (as it is today — the log may predate it): the stable prefix is ${prefix} tokens, over the ${minimum} minimum. The prompt file is not the problem; look at whether the prefix is byte-identical between calls.`,
1931
- labelFileMissing: (label, file) => `labels["${label}"] points at ${file}, which does not exist — the mapping was skipped.`,
1988
+ againstByModel: () => 'The same change, by model, where the mix moved:',
1989
+ labelPrefixBelowMinimum: (file, prefix, minimum, model) => `${file} (as it is today, and the log may predate it): the stable prefix is ${prefix} tokens and ${model} caches nothing under ${minimum}. Setting cache_control there does not error, it simply never caches, which is what a cache that only writes looks like from the bill.`,
1990
+ labelPrefixMovable: (file, movable, prefix) => `${file} (as it is today, and the log may predate it): ~${movable} stable tokens sit after the first placeholder, where caching cannot reach them; the cacheable prefix is ${prefix}. "trazum optimize ${file} --reorder" moves them in front and shows the diff.`,
1991
+ labelPrefixHealthy: (file, prefix, minimum) => `${file} (as it is today, and the log may predate it): the stable prefix is ${prefix} tokens, over the ${minimum} minimum. The prompt file is not the problem; look at whether the prefix is byte-identical between calls.`,
1992
+ labelFileMissing: (label, file) => `labels["${label}"] points at ${file}, which does not exist: the mapping was skipped.`,
1932
1993
  againstNothingPriced: () => 'The previous log has nothing the pricing catalogue knows, so there is no comparison to make.',
1933
- truncatedNotRecorded: () => 'Whether any answers were cut off could not be measured — no call in this log carries a stop reason. Add "stop_reason" (Anthropic) or "finish_reason" (OpenAI) to the record; the API already returns it beside "usage".',
1934
- historyNoSessions: () => 'No call in this log carried a session, so what re-sending the conversation costs could not be measured — usually the largest line on a chat or agent bill. Add "session" (or "conversation_id") to the record and run this again. Trazum groups by it and never prints it.',
1935
- leversUnlabelled: () => 'None of these calls carried a label, so this is every workload in one row — a classifier and a RAG pipeline merged into a single figure, with one route suggested for both. Add "label" to the record and the levers split by workload, which is the grouping a decision is actually made at.',
1994
+ truncatedNotRecorded: () => 'Whether any answers were cut off could not be measured, no call in this log carries a stop reason. Add "stop_reason" (Anthropic) or "finish_reason" (OpenAI) to the record; the API already returns it beside "usage".',
1995
+ historyNoSessions: () => 'No call in this log carried a session, so what re-sending the conversation costs could not be measured, usually the largest line on a chat or agent bill. Add "session" (or "conversation_id") to the record and run this again. Trazum groups by it and never prints it.',
1996
+ leversUnlabelled: () => 'None of these calls carried a label, so this is every workload in one row, a classifier and a RAG pipeline merged into a single figure, with one route suggested for both. Add "label" to the record and the levers split by workload, which is the grouping a decision is actually made at.',
1936
1997
  outputShapeHeading: () => 'Where the output spend concentrates',
1937
- outputTail: (label, model, callPct, spendPct, above, usd) => `${label} on ${model}: ${callPct} of calls hold ${spendPct} of the output spend — the ones answering with more than ${above} tokens, out of ${usd} of output on this slice.`,
1998
+ outputTail: (label, model, callPct, spendPct, above, usd) => `${label} on ${model}: ${callPct} of calls hold ${spendPct} of the output spend, the ones answering with more than ${above} tokens, out of ${usd} of output on this slice.`,
1938
1999
  outputTailAdvice: () => 'That is a tail, and a tail has a cause: a path through the prompt that invites an essay, a call with no max_tokens, a retrieval that returned a book. Finding it is a morning; it is not "make everything shorter".',
1939
- outputFlat: (label, model, callPct, spendPct, usd) => `${label} on ${model}: the output spend sits where the calls are — ${callPct} of them hold ${spendPct} of ${usd}. There is no tail to hunt.`,
2000
+ outputFlat: (label, model, callPct, spendPct, usd) => `${label} on ${model}: the output spend sits where the calls are, ${callPct} of them hold ${spendPct} of ${usd}. There is no tail to hunt.`,
1940
2001
  outputFlatAdvice: () => 'The answer length is the task here, so the levers are the blunt ones: ask for shorter answers in the prompt, and cap max_tokens.',
1941
- outputPercentiles: (p50, p95) => `Half the measured answers fit within ${p50} output tokens, and 95% within ${p95} — the number a max_tokens cap actually wants. Measured on these calls, promised for nothing.`,
2002
+ outputPercentiles: (p50, p95) => `Half the measured answers fit within ${p50} output tokens, and 95% within ${p95}, the number a max_tokens cap actually wants. Measured on these calls, promised for nothing.`,
1942
2003
  inputShapeHeading: () => 'How big these calls are',
1943
- inputSkewed: (label, model, p50, p95, ratio, usd) => `${label} on ${model} is uneven: half its calls fit within ${p50} input tokens and 95% within ${p95} — about ${ratio}x the ordinary call, over ${usd} of input spend.`,
2004
+ inputSkewed: (label, model, p50, p95, ratio, usd) => `${label} on ${model} is uneven: half its calls fit within ${p50} input tokens and 95% within ${p95}, about ${ratio}x the ordinary call, over ${usd} of input spend.`,
1944
2005
  inputSkewedAdvice: () => 'Past four times the median, the ordinary call is fine and something is growing on top of it: a conversation nobody truncates, a retrieval with no cap, a tool result pasted in whole. The fix is a limit on the large calls, not a rewrite of the prompt every call sends.',
1945
2006
  inputEven: (label, model, p50, p95, usd) => `${label} on ${model} is even: half its calls fit within ${p50} input tokens and 95% within ${p95}, over ${usd} of input spend.`,
1946
- inputEvenAdvice: () => 'The large calls are not much larger than the ordinary one, so there is no tail to cap — the prompt is simply big. The levers are fewer retrieved documents, a shorter system block, and caching if the prefix repeats.',
1947
- inputHuge: (label, model, calls, usd) => `${label} on ${model}: every one of its ${calls} is larger than this tool measures precisely, over ${usd} of input spend. No ceiling is named because there is none to name honestly — that size is itself the finding.`,
2007
+ inputEvenAdvice: () => 'The large calls are not much larger than the ordinary one, so there is no tail to cap: the prompt is simply big. The levers are fewer retrieved documents, a shorter system block, and caching if the prefix repeats.',
2008
+ inputHuge: (label, model, calls, usd) => `${label} on ${model}: every one of its ${calls} is larger than this tool measures precisely, over ${usd} of input spend. No ceiling is named because there is none to name honestly: that size is itself the finding.`,
1948
2009
  repeatsHeading: () => 'The same request, sent again',
1949
2010
  repeatsFound: (label, model, repeats, checked, seconds, usd) => `${label} on ${model}: ${repeats} of ${checked} calls re-sent the previous call's exact input size within ${seconds} seconds, in the same conversation, costing ${usd}.`,
1950
2011
  pressureHeading: () => 'Approaching the context window',
1951
- pressureLine: (label, model, tokens, window, share) => `${label} on ${model}: the largest call carried ${tokens} input tokens against a ${window}-token window — ${share} of the ceiling.`,
2012
+ pressureLine: (label, model, tokens, window, share) => `${label} on ${model}: the largest call carried ${tokens} input tokens against a ${window}-token window, ${share} of the ceiling.`,
1952
2013
  mixDriftHeading: () => 'The mix moved inside this log',
1953
- mixDriftLine: (model, firstShare, lastShare, firstDays, lastDays, lastUsd) => `${model} went from ${firstShare} of the spend in the first ${firstDays} days to ${lastShare} in the last ${lastDays} — ${lastUsd} of the recent half.`,
1954
- truncationRetryLine: (label, model, retried, truncated, seconds, wasted, retry) => `${label} on ${model}: ${retried} of ${truncated} truncated answers were followed within ${seconds} seconds by another call in the same conversation — ${wasted} spent on the cut attempts, plus ${retry} on the follow-ups.`,
2014
+ mixDriftLine: (model, firstShare, lastShare, firstDays, lastDays, lastUsd) => `${model} went from ${firstShare} of the spend in the first ${firstDays} days to ${lastShare} in the last ${lastDays}, ${lastUsd} of the recent half.`,
2015
+ truncationRetryLine: (label, model, retried, truncated, seconds, wasted, retry) => `${label} on ${model}: ${retried} of ${truncated} truncated answers were followed within ${seconds} seconds by another call in the same conversation, ${wasted} spent on the cut attempts, plus ${retry} on the follow-ups.`,
1955
2016
  truncationRetryNote: () => 'The pair is the shape a retry has; the log cannot see content, so whether each was one is yours to know. Both sides of it are real money, and the fix is the same either way: a max_tokens the answers actually fit in.',
1956
2017
  mixDriftNote: () => 'A bill can grow with no workload growing: traffic migrating between models, a deploy that flipped a default, a fallback that became the main path. Shown past fifteen points of movement. Where the mix goes next is not in this log, so it is not said here.',
1957
2018
  pressureAdvice: () => 'At 100% the call fails outright, and nothing on the bill changes until that day. The levers are a cap on retrieved context, truncating conversation history, or a larger-window model. When it crosses is not predicted here: the share is a fact, the trajectory is yours to know.',
1958
- repeatsAdvice: () => 'A conversation\'s input grows with every turn, so the same size twice in a row seconds apart is usually a retry after a timeout, an agent step repeating, or a loop — this reads counts and cannot see content, so it names the pattern and stops. Whatever it is, the money bought nothing the call before it had not already paid for.',
1959
- inputMostlyCached: (share) => `${share} of those tokens were cache reads, billed at a tenth of the input rate — the size is real and most of it is cheap.`,
2019
+ repeatsAdvice: () => 'A conversation\'s input grows with every turn, so the same size twice in a row seconds apart is usually a retry after a timeout, an agent step repeating, or a loop: this reads counts and cannot see content, so it names the pattern and stops. Whatever it is, the money bought nothing the call before it had not already paid for.',
2020
+ inputMostlyCached: (share) => `${share} of those tokens were cache reads, billed at a tenth of the input rate: the size is real and most of it is cheap.`,
1960
2021
  inputFullRate: () => 'Almost none of that was a cache read, so every one of those tokens was billed at the full input rate. If any prefix repeats across these calls, caching is the lever with the largest ceiling here.',
1961
2022
  leversNone: () => 'Nothing here clears 1% of the bill: these calls are already on the cheapest model of their family, or their provider has no batch API. That is a real answer, not an empty section.',
1962
2023
  assumedWriteTtl: (calls) => `${count(calls)} ${calls === 1 ? 'call did' : 'calls did'} not say which cache-write TTL was used, so the cheaper 5-minute rate was assumed. A 1-hour entry costs 2x input rather than 1.25x, so this total is a floor for those calls. Record the "cache_creation" object the API returns to remove the assumption.`,
1963
- spanLine: (from, to, days) => `This log covers ${from} → ${to} (${days} days). The span is stated, never extrapolated — the monthly arithmetic is yours to do, and now it is valid.`,
2024
+ spanLine: (from, to, days) => `This log covers ${from} → ${to} (${days} days). The span is stated, never extrapolated: the monthly arithmetic is yours to do, and now it is valid.`,
1964
2025
  spanPartial: (withTs, total) => `Only ${withTs} of ${total} calls carry a timestamp; the span describes those.`,
1965
- ttlFitExpires: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart and the 5-minute entry is gone by then — writes expire before the next turn reads them, which from the bill is a cache that only writes. The 1-hour TTL costs 2x input to write and would survive these gaps; the other honest option is caching switched off here.`,
1966
- ttlFitExpiresBoth: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart, and no cache entry lives that long — even the 1-hour TTL is gone by the next turn. Caching cannot work at this pace; turn it off here and stop paying the write premium.`,
1967
- ttlFitOverlong: (label, model, gap, usd) => `${label} on ${model}: turns arrive a median of ${gap} apart — comfortably inside the 5-minute window — and these writes pay the 1-hour rate, 2x input against 1.25x, for endurance the gaps never use. The same writes at the 5-minute TTL are ${usd} cheaper on this log, and that figure is exact: the same tokens at the other published rate.`,
1968
- ttlFitUnsettledGap: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart — a 5-minute entry is gone by then and a 1-hour one survives — and the log did not record which these writes were, so whether they ever get read back cannot be settled. Record the "cache_creation" object the API returns and it settles itself.`,
2026
+ ttlFitExpires: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart and the 5-minute entry is gone by then, writes expire before the next turn reads them, which from the bill is a cache that only writes. The 1-hour TTL costs 2x input to write and would survive these gaps; the other honest option is caching switched off here.`,
2027
+ ttlFitExpiresBoth: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart, and no cache entry lives that long, even the 1-hour TTL is gone by the next turn. Caching cannot work at this pace; turn it off here and stop paying the write premium.`,
2028
+ ttlFitOverlong: (label, model, gap, usd) => `${label} on ${model}: turns arrive a median of ${gap} apart, comfortably inside the 5-minute window, and these writes pay the 1-hour rate, 2x input against 1.25x, for endurance the gaps never use. The same writes at the 5-minute TTL are ${usd} cheaper on this log, and that figure is exact: the same tokens at the other published rate.`,
2029
+ ttlFitUnsettledGap: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart, which a 5-minute entry does not survive and a 1-hour one does, and the log did not record which these writes were, so whether they ever get read back cannot be settled. Record the "cache_creation" object the API returns and it settles itself.`,
1969
2030
  ttlFitFits: (label, model, gap) => `${label} on ${model}: turns arrive a median of ${gap} apart, inside the lifetime these writes use. The TTL is not the problem here.`,
1970
- ttlFitUnmeasured: () => 'Whether the cache TTL fits how fast the turns arrive could not be measured — it needs both "session" and "ts" on the record. A 5-minute entry on a workload whose turns come nine minutes apart expires unread on every write, and only the clock can see it. Trazum groups by the session and never shows it.',
2031
+ ttlFitUnmeasured: () => 'Whether the cache TTL fits how fast the turns arrive could not be measured, it needs both "session" and "ts" on the record. A 5-minute entry on a workload whose turns come nine minutes apart expires unread on every write, and only the clock can see it. Trazum groups by the session and never shows it.',
1971
2032
  dayPeak: (day, usd, xMedian) => `The most expensive day in this log was ${day}: ${usd}, ${xMedian}x the median day.`,
1972
2033
  dayPeakLabel: (label, usd) => `Most of it was ${label} (${usd}).`,
1973
2034
  maxUsdOk: (total, max) => `Within budget: ${total} spent against --max-usd ${max}.`,
1974
- maxUsdFailed: (total, max) => `FAILED — this log spent ${total} against a --max-usd of ${max}. The figures are the provider's own billed counts over exactly this log; no period was assumed.`,
1975
- maxGrowthUsdFailed: (delta, max) => `FAILED — the bill grew ${delta} against the previous log, over the --max-growth-usd limit of ${max}.`,
2035
+ maxUsdFailed: (total, max) => `FAILED: this log spent ${total} against a --max-usd of ${max}. The figures are the provider's own billed counts over exactly this log; no period was assumed.`,
2036
+ maxGrowthUsdFailed: (delta, max) => `FAILED, the bill grew ${delta} against the previous log, over the --max-growth-usd limit of ${max}.`,
1976
2037
  maxGrowthNeedsAgainst: () => '--max-growth-usd has nothing to compare without --against <previous.jsonl>. On its own it would have run silently and gated nothing, which is not an answer.',
1977
2038
  maxCacheLossOk: (worst, max) => `Cache within budget: caching cost at most ${worst} against --max-cache-loss-usd ${max}, worst case included.`,
1978
- maxCacheLossFailed: (delta, max) => `FAILED — caching added ${delta} to this bill (the same tokens as plain input would have cost less), over the --max-cache-loss-usd limit of ${max}. The counterfactual is exact: the same tokens at the published input rate.`,
2039
+ maxCacheLossFailed: (delta, max) => `FAILED, caching added ${delta} to this bill (the same tokens as plain input would have cost less), over the --max-cache-loss-usd limit of ${max}. The counterfactual is exact: the same tokens at the published input rate.`,
1979
2040
  maxDayOk: (day, usd, max) => `No single day over budget: the worst was ${day} at ${usd}, against --max-day-usd ${max}.`,
1980
- maxDayFailed: (day, usd, max) => `FAILED — ${day} spent ${usd}, over the --max-day-usd limit of ${max}. A total under budget can hide a single runaway day, which is what this gate exists to catch.`,
1981
- maxDayNoClock: () => 'FAILED — --max-day-usd was asked for and no record in this log carries a timestamp, so there are no days to judge. That is not a pass: a bill nobody could measure by day is not a bill that stayed under a daily budget. Add "ts" to the record and the gate arms.',
2041
+ maxDayFailed: (day, usd, max) => `FAILED, ${day} spent ${usd}, over the --max-day-usd limit of ${max}. A total under budget can hide a single runaway day, which is what this gate exists to catch.`,
2042
+ maxDayNoClock: () => 'FAILED, --max-day-usd was asked for and no record in this log carries a timestamp, so there are no days to judge. That is not a pass: a bill nobody could measure by day is not a bill that stayed under a daily budget. Add "ts" to the record and the gate arms.',
1982
2043
  maxSessionOk: (worst, max, sessions) => `No conversation over budget: the most expensive of ${sessions} cost ${worst}, against --max-session-usd ${max}. A conversation that started before this log is counted only for the turns recorded here, so this is a floor.`,
1983
- maxSessionFailed: (worst, max, sessions) => `FAILED — the most expensive of ${sessions} conversations cost ${worst}, over the --max-session-usd limit of ${max}. A month's budget and a day's budget both pass while one conversation loops its way through this; the per-conversation figure is the one that catches it.`,
1984
- maxSessionNoSessions: () => 'FAILED — --max-session-usd was asked for and no record in this log carries a session, so there are no conversations to judge. That is not a pass. Add "session" (or "conversation_id") to the record and the gate arms; Trazum groups by it and never prints it.',
1985
- maxDayUndated: (calls) => `${calls} calls carry no timestamp, so they are in the bill and in none of the days above — the worst day is a floor by whatever they held. A failure would stand regardless; this pass is over the part that could be dated.`,
1986
- maxCacheLossWorstCase: (calls, worst, max) => `FAILED — ${count(calls)} ${calls === 1 ? 'call' : 'calls'} did not record which cache-write TTL was paid, and at the 1-hour rate caching added up to ${worst}, over the --max-cache-loss-usd limit of ${max}. The gate reads the worst case on purpose: a gate reading the flattering half would pass exactly the bills it exists to catch. Record the "cache_creation" object the API returns and the ceiling becomes a figure.`,
1987
- pricesStale: (date, days) => `The price table behind every dollar here was last reviewed ${date} — ${count(days)} days ago, past the 45 this tool considers current. If the provider changed prices since, this report is wrong by exactly that change. --pricing-live fetches today's prices; --pricing overlays your own.`,
2044
+ maxSessionFailed: (worst, max, sessions) => `FAILED: the most expensive of ${sessions} conversations cost ${worst}, over the --max-session-usd limit of ${max}. A month's budget and a day's budget both pass while one conversation loops its way through this; the per-conversation figure is the one that catches it.`,
2045
+ maxSessionNoSessions: () => 'FAILED, --max-session-usd was asked for and no record in this log carries a session, so there are no conversations to judge. That is not a pass. Add "session" (or "conversation_id") to the record and the gate arms; Trazum groups by it and never prints it.',
2046
+ maxDayUndated: (calls) => `${calls} calls carry no timestamp, so they are in the bill and in none of the days above: the worst day is a floor by whatever they held. A failure would stand regardless; this pass is over the part that could be dated.`,
2047
+ maxCacheLossWorstCase: (calls, worst, max) => `FAILED, ${count(calls)} ${calls === 1 ? 'call' : 'calls'} did not record which cache-write TTL was paid, and at the 1-hour rate caching added up to ${worst}, over the --max-cache-loss-usd limit of ${max}. The gate reads the worst case on purpose: a gate reading the flattering half would pass exactly the bills it exists to catch. Record the "cache_creation" object the API returns and the ceiling becomes a figure.`,
2048
+ pricesStale: (date, days) => `The price table behind every dollar here was last reviewed ${date}, ${count(days)} days ago, past the 45 this tool considers current. If the provider changed prices since, this report is wrong by exactly that change. --pricing-live fetches today's prices; --pricing overlays your own.`,
1988
2049
  dayTableDay: () => 'Day (UTC)',
1989
2050
  dayTableCalls: () => 'calls',
1990
2051
  dayTableTop: () => 'biggest that day',
1991
2052
  dayTableEarlier: (days) => `…and ${count(days)} earlier ${days === 1 ? 'day' : 'days'} not shown here. The full series rides --json as spendByDay.`,
1992
- gateOnFloor: (reasons) => `Note: the gated figure is a floor, not the bill — ${reasons}. Whatever those calls cost is not in the number the gate just judged, so a pass here means "the part I could read fits", never "the bill fits".`,
2053
+ gateOnFloor: (reasons) => `Note: the gated figure is a floor, not the bill, ${reasons}. Whatever those calls cost is not in the number the gate just judged, so a pass here means "the part I could read fits", never "the bill fits".`,
1993
2054
  floorSkipped: (lines) => `${count(lines)} ${lines === 1 ? 'line was' : 'lines were'} unreadable and left out`,
1994
2055
  floorUnpriced: (calls) => `${count(calls)} ${calls === 1 ? 'call is' : 'calls are'} on models the price table does not know`,
1995
2056
  floorUndated: (calls) => `${count(calls)} ${calls === 1 ? 'call carries' : 'calls carry'} no timestamp and fell outside the window`,
1996
- sessionCost: (label, model, sessions, median, medianTurns, p95, max) => `${label} on ${model}: across ${sessions} conversations, the median one costs ${median} over ${medianTurns} turns, 95% come in under ${p95}, and the most expensive was ${max}. Exact billed counts, per conversation — the figure a per-seat price or a quota is set from. A conversation that started before this log or continues after it is counted only for the turns recorded here.`,
2057
+ sessionCost: (label, model, sessions, median, medianTurns, p95, max) => `${label} on ${model}: across ${sessions} conversations, the median one costs ${median} over ${medianTurns} turns, 95% come in under ${p95}, and the most expensive was ${max}. Exact billed counts, per conversation: the figure a per-seat price or a quota is set from. A conversation that started before this log or continues after it is counted only for the turns recorded here.`,
1997
2058
  labelBudgetOk: (label, usd, max) => `Within budget: ${label} spent ${usd} against ${max}.`,
1998
- labelBudgetFailed: (label, usd, max) => `FAILED — ${label} spent ${usd} against its budget of ${max} in trazum.config.json.`,
2059
+ labelBudgetFailed: (label, usd, max) => `FAILED, ${label} spent ${usd} against its budget of ${max} in trazum.config.json.`,
1999
2060
  labelBudgetMissing: (label) => `${label} has a budget in trazum.config.json and no calls in this log, so nothing was measured for it. Not a pass: a workload that did not appear is not a workload that came in under budget.`,
2000
2061
  labelBudgetWindowed: () => 'Per-label budgets in trazum.config.json were not applied: --since/--until make "what this label spent" mean a slice, and a budget written for the whole period would be gating against something it does not describe.',
2001
- duplicateLines: (calls, usd) => `${plural(calls, 'line is an exact duplicate', `lines are exact duplicates`)} of an earlier line — same counts, same label and session, same millisecond — and that adds ${usd} to the total above. If a log was exported twice or two files in a directory overlap, this bill is overstated by that much. Two real calls colliding on all of that is possible; it is just unlikely.`,
2002
- budgetVsWire: (label, file, budget, perCall, share) => `The budget on ${file} is ${budget} tokens, and calls labelled ${label} carry about ${perCall} input tokens each — so that gate governs roughly ${share} of what actually goes up the wire. The rest is retrieved context, conversation history and tool results, which no prompt file contains and no budget on one can see. The budget is not wrong; it is just smaller than the bill.`,
2003
- badCsvShape: (value) => `--csv-shape does not know "${value}". It takes "slice" (one row per label and model, the default), "day", "hour" or "model-day" (one row per day and model — the long format a pivot table wants).`,
2062
+ duplicateLines: (calls, usd) => `${plural(calls, 'line is an exact duplicate', `lines are exact duplicates`)} of an earlier line, same counts, same label and session, same millisecond, and that adds ${usd} to the total above. If a log was exported twice or two files in a directory overlap, this bill is overstated by that much. Two real calls colliding on all of that is possible; it is just unlikely.`,
2063
+ budgetVsWire: (label, file, budget, perCall, share) => `The budget on ${file} is ${budget} tokens, and calls labelled ${label} carry about ${perCall} input tokens each, so that gate governs roughly ${share} of what actually goes up the wire. The rest is retrieved context, conversation history and tool results, which no prompt file contains and no budget on one can see. The budget is not wrong; it is just smaller than the bill.`,
2064
+ badCsvShape: (value) => `--csv-shape does not know "${value}". It takes "slice" (one row per label and model, the default), "day", "hour" or "model-day" (one row per day and model, the long format a pivot table wants).`,
2004
2065
  whatIfHeading: (model) => `These exact calls on ${model}`,
2005
2066
  whatIfAssumption: () => 'This is multiplication, not advice: the same token counts at another rate card. It says nothing about whether that model could do the work, and a model that answers at greater length or gets retried would not send these counts at all.',
2006
- whatIfTotal: (current, target, delta) => `${current} of movable spend would have been ${target} — a difference of ${delta}.`,
2067
+ whatIfTotal: (current, target, delta) => `${current} of movable spend would have been ${target}, a difference of ${delta}.`,
2007
2068
  whatIfCheaper: () => 'Verify before you move anything: trazum route measures one prompt against both models on your own examples.',
2008
2069
  whatIfDearer: () => 'That direction costs more. The arithmetic is here so the number is not a guess.',
2009
- whatIfBatchOnTarget: (batched, moved) => `If those calls can also wait, the target's Batch API takes the moved bill from ${moved} to ${batched} — the discount applies to the target's rates, not the ones you left. Whether they can wait is not in the log; that half of the decision is yours.`,
2010
- whatIfCacheBeyond: (largest, min, noCache) => `Its cache traffic could not exist there: the largest call is ${largest} tokens against the target's ${min}-token cache minimum, so no call in this slice could create an entry. Without the cache the same tokens cost ${noCache} — that is the figure the target would actually bill, and the row above flatters the move.`,
2070
+ whatIfBatchOnTarget: (batched, moved) => `If those calls can also wait, the target's Batch API takes the moved bill from ${moved} to ${batched}, the discount applies to the target's rates, not the ones you left. Whether they can wait is not in the log; that half of the decision is yours.`,
2071
+ whatIfCacheBeyond: (largest, min, noCache) => `Its cache traffic could not exist there: the largest call is ${largest} tokens against the target's ${min}-token cache minimum, so no call in this slice could create an entry. Without the cache the same tokens cost ${noCache}: that is the figure the target would actually bill, and the row above flatters the move.`,
2011
2072
  whatIfSlice: (label, model, current, target) => `${label} on ${model}: ${current} → ${target}`,
2012
2073
  whatIfOverContext: (label, tokens, window, usd) => `${label} cannot move: its largest call carries ${tokens} input tokens and that model's window is ${window}. Those calls would fail, not cost less, so their ${usd} is excluded from the figures above.`,
2013
- whatIfAlreadyThere: (calls, usd) => `Already on that model: ${calls} worth ${usd}, left out of the figures above — money that cannot move would make the difference look smaller than it is.`,
2074
+ whatIfAlreadyThere: (calls, usd) => `Already on that model: ${calls} worth ${usd}, left out of the figures above, because money that cannot move would make the difference look smaller than it is.`,
2014
2075
  whatIfUnpriced: (calls, models) => `Excluded: ${calls} whose model has no price here (${models}). Their cost on the target is knowable; the difference is not, because there is no current figure to subtract from.`,
2015
2076
  whatIfNothingToMove: () => 'Nothing to compare: every priced call in this log is already on that model, or too large for its context window.',
2016
2077
  whatIfUnknown: (value, available) => `--what-if does not know "${value}". Priced models: ${available}. Add it with --pricing if you have its rates.`,
2017
2078
  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.`,
2018
- dryRunHeading: () => 'What this log can answer — no bill was produced',
2079
+ dryRunHeading: () => 'What this log can answer, no bill was produced',
2019
2080
  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.`,
2020
2081
  dryRunUnpriced: (models) => `Models the price table does not know: ${models}. Their tokens parse; their dollars need a --pricing overlay.`,
2021
2082
  dryRunTotals: () => 'The bill itself: totals, per-model split, cache economics, the levers.',
2022
- dryRunLabels: (share) => `Per-workload findings and label budgets — "label" on ${share} of records.`,
2023
- dryRunClock: (share) => `The period, per-day and per-hour shape, --max-day-usd, --since/--until — a timestamp on ${share} of records.`,
2024
- dryRunSessions: (share) => `Conversation growth, per-conversation cost, --max-session-usd — a session on ${share} of records. Grouped by, never printed.`,
2025
- dryRunStopReason: (share) => `Truncated answers and their retry bill — a stop reason on ${share} of records.`,
2026
- dryRunCacheTtl: (ttl, writes) => `Settled cache verdicts — the "cache_creation" split on ${ttl} of ${writes} cache-writing records.`,
2027
- dryRunNoCacheTraffic: () => 'Cache verdicts: nothing wrote to the cache in this log, so there is nothing to settle — not a missing field.',
2083
+ dryRunLabels: (share) => `Per-workload findings and label budgets, "label" on ${share} of records.`,
2084
+ dryRunClock: (share) => `The period, per-day and per-hour shape, --max-day-usd, --since/--until, a timestamp on ${share} of records.`,
2085
+ dryRunSessions: (share) => `Conversation growth, per-conversation cost, --max-session-usd, a session on ${share} of records. Grouped by, never printed.`,
2086
+ dryRunStopReason: (share) => `Truncated answers and their retry bill, a stop reason on ${share} of records.`,
2087
+ dryRunCacheTtl: (ttl, writes) => `Settled cache verdicts, the "cache_creation" split on ${ttl} of ${writes} cache-writing records.`,
2088
+ dryRunNoCacheTraffic: () => 'Cache verdicts: nothing wrote to the cache in this log, so there is nothing to settle, not a missing field.',
2028
2089
  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.',
2029
2090
  dryRunNoGates: () => '--dry-run produces no bill, so a gate beside it would exit green having judged nothing. Run the gates without --dry-run.',
2030
- bySourceNeedsConfig: () => '--by-source reads the "sources" block in trazum.config.json — a name per service, each with glob patterns over log paths — and this config has none. Name at least one source.',
2091
+ bySourceNeedsConfig: () => '--by-source reads the "sources" block in trazum.config.json, a name per service, each with glob patterns over log paths, and this config has none. Name at least one source.',
2031
2092
  bySourceNothingMatched: (sources) => 'No log file matched any source pattern. The sources configured: ${sources}. Patterns match the paths as given on the command line.'.replace('${sources}', sources),
2032
2093
  fleetHeading: (count, total, calls) => `The fleet: ${count} sources · ${total} · ${calls}`,
2033
2094
  fleetRow: (name, usd, share, calls, span) => `${name} ${usd} ${share} of the fleet · ${calls} · ${span}`,
2034
2095
  fleetSpan: (days) => `${days} days`,
2035
2096
  fleetNoClock: () => 'no clock',
2036
2097
  fleetWorst: (name, usd, share) => `${name} is where the money is: ${usd}, ${share} of the fleet's total.`,
2037
- fleetMismatchedSpans: () => 'These sources cover different periods, so the shares above compare totals, not rates — a 3-day log looks cheap next to a 30-day one for reasons that have nothing to do with cost. Each row states its own span.',
2038
- fleetSplitBrain: (label, detail) => `The same workload runs on different models in different sources — ${label}: ${detail}. Same job, different rate cards; whether that is a decision or an accident is not in the logs.`,
2039
- fleetCacheUnderwater: (name, usd) => `Caching pays for the fleet overall but loses ${usd} in ${name} — the aggregate verdict was hiding it.`,
2040
- fleetUnmatched: (file) => `${file} matched no source pattern, so it is in no report above — spend missing from every bill until a pattern covers it.`,
2098
+ fleetMismatchedSpans: () => 'These sources cover different periods, so the shares above compare totals, not rates: a 3-day log looks cheap next to a 30-day one for reasons that have nothing to do with cost. Each row states its own span.',
2099
+ fleetSplitBrain: (label, detail) => `The same workload runs on different models in different sources, ${label}: ${detail}. Same job, different rate cards; whether that is a decision or an accident is not in the logs.`,
2100
+ fleetCacheUnderwater: (name, usd) => `Caching pays for the fleet overall but loses ${usd} in ${name}: the aggregate verdict was hiding it.`,
2101
+ fleetUnmatched: (file) => `${file} matched no source pattern, so it is in no report above, spend missing from every bill until a pattern covers it.`,
2041
2102
  fleetFooter: () => 'Summaries per source; the full report for one service is "trazum profile <its logs>". Same thresholds, same findings, one source at a time.',
2042
2103
  fleetBudgetOk: (name, usd, max) => `Within budget: ${name} spent ${usd} against its ${max} in spend.bySource.`,
2043
- fleetBudgetFailed: (name, usd, max) => `FAILED — ${name} spent ${usd} against its budget of ${max} in spend.bySource. The fleet total can be fine while one service bleeds; this gate names which.`,
2104
+ fleetBudgetFailed: (name, usd, max) => `FAILED, ${name} spent ${usd} against its budget of ${max} in spend.bySource. The fleet total can be fine while one service bleeds; this gate names which.`,
2044
2105
  fleetBudgetMissing: (name) => `${name} has a budget in spend.bySource and no logs matched it in this run, so nothing was measured for it. Not a pass: a service that did not appear is not a service under budget.`,
2045
2106
  coverageHeading: () => 'What this log cannot answer yet',
2046
2107
  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.`,
2047
- 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".`,
2108
+ 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".`,
2048
2109
  dryRunOutcomes: (share) => `cost per outcome and a success rate (${share} of records carry an "outcome")`,
2049
2110
  outcomeHeading: () => 'Outcomes',
2050
- 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.`,
2111
+ outcomeRate: (rate, ofUsd) => `${rate} of ${ofUsd} in declared outcomes succeeded, by spend rather than by call, because the two diverge exactly when the expensive half is the half that fails.`,
2051
2112
  outcomeNoRate: (why) => why === 'nothing-recorded'
2052
- ? '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.'
2113
+ ? 'No success rate: nothing in this log recorded an outcome. That is not a rate of zero, a rate of zero is a real and terrible measurement, and this is nobody having told us.'
2053
2114
  : '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.',
2054
2115
  outcomeUnrecorded: (share, usd) => `${share} of the bill (${usd}) carried no outcome, and is in neither half of the rate above.`,
2055
- 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.`,
2116
+ outcomeUndeclared: (values) => `Not declared in "outcomes.values": ${values}. Named rather than counted as failures, a typo in an exporter should look like a typo, not like a product regression.`,
2056
2117
  perOutcomeHeading: () => 'What an outcome costs',
2057
2118
  perOutcomeRow: (key, perCall, perOutcome, coverage) => `${key} ${perCall} ${perOutcome} ${coverage}`,
2058
2119
  perOutcomeColumns: {
@@ -2070,37 +2131,37 @@ ${bold('EXAMPLES')}
2070
2131
  : why === 'nothing-recorded'
2071
2132
  ? 'not recorded'
2072
2133
  : 'no vocabulary',
2073
- 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.',
2134
+ perOutcomeNumerator: () => 'Per success divides the spend on calls that recorded an outcome, never the whole bill, 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.',
2074
2135
  perOutcomeDisagreement: (key, callRank, outcomeRank) => `${key} is #${callRank} by cost per call and #${outcomeRank} by cost per success.`,
2075
2136
  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.',
2076
2137
  outcomeColumns: { outcome: 'outcome', calls: 'calls', spend: 'spend' },
2077
2138
  verdictSuccess: () => 'success',
2078
- verdictOther: () => '\u2014',
2139
+ verdictOther: () => 'other',
2079
2140
  verdictUndeclared: () => 'undeclared',
2080
2141
  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.`,
2081
2142
  needsTs: (seen) => `"ts" on ${seen} records: without it the log has no period, no per-day or per-hour shape, and the cache-TTL question cannot be asked at all.`,
2082
- needsStopReason: (seen) => `"stop_reason" (Anthropic) or "finish_reason" (OpenAI) on ${seen} records: without it, answers cut off at max_tokens are invisible — and silence there is not the same as none.`,
2143
+ needsStopReason: (seen) => `"stop_reason" (Anthropic) or "finish_reason" (OpenAI) on ${seen} records: without it, answers cut off at max_tokens are invisible, and silence there is not the same as none.`,
2083
2144
  needsCacheTtl: (seen) => `the "cache_creation" object on ${seen} of the records that wrote to the cache: without it the 5-minute rate is assumed, so those totals are a floor and some cache verdicts cannot be settled.`,
2084
- hoursConcentrated: (hours, list) => `80% of this spend lands in ${hours} hours of the UTC day (${list}) — interactive traffic somebody is waiting on, where the Batch API's 24-hour turnaround does not fit. Hours are UTC; shift them yourself if your traffic sits in one region.`,
2085
- hoursFlat: (hours) => `The spend is spread across the day: it takes ${hours} hours of the UTC day to cover 80% of it. That is the shape background work has, and background work is what the Batch API halves the price of — see the levers above for what it would be worth here. Whether these calls can wait is yours to say; the log only shows when they happened.`,
2086
- truncatedBy: (label, calls, measured, rate, usd) => `${label}: ${calls} of ${measured} calls that recorded a stop reason were cut off (${rate}), ${usd} of output. The denominator is the calls that measured, not every call — a workload logging the field half the time is not a workload whose other half completed.`,
2145
+ hoursConcentrated: (hours, list) => `80% of this spend lands in ${hours} hours of the UTC day (${list}), interactive traffic somebody is waiting on, where the Batch API's 24-hour turnaround does not fit. Hours are UTC; shift them yourself if your traffic sits in one region.`,
2146
+ hoursFlat: (hours) => `The spend is spread across the day: it takes ${hours} hours of the UTC day to cover 80% of it. That is the shape background work has, and background work is what the Batch API halves the price of. See the levers above for what it would be worth here. Whether these calls can wait is yours to say; the log only shows when they happened.`,
2147
+ truncatedBy: (label, calls, measured, rate, usd) => `${label}: ${calls} of ${measured} calls that recorded a stop reason were cut off (${rate}), ${usd} of output. The denominator is the calls that measured, not every call: a workload logging the field half the time is not a workload whose other half completed.`,
2087
2148
  truncatedCeiling: (p95) => `95% of the answers that finished fit within ${p95} output tokens, so a cap around there would stop cutting them off. Measured on these calls, promised for nothing.`,
2088
2149
  readFiles: (files, directory) => `Read ${count(files)} log files from ${directory}, in name order, as one bill. Every figure below covers all of them.`,
2089
2150
  noLogsInDirectory: (directory, extensions) => `No usage logs in "${directory}". Looked for files ending in ${extensions}. A directory with nothing readable in it is an error rather than an empty report, which would read as "you spent nothing".`,
2090
2151
  sessionCostTail: (ratio) => `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.`,
2091
- 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.`,
2092
- 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.`,
2093
- 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.`,
2152
+ 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.`,
2153
+ 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.`,
2154
+ 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.`,
2094
2155
  waiveNotRecorded: (path, because) => ` (This waiver was not written to ${path}: ${because}. The gate's verdict above is unaffected.)`,
2095
- summaryNoComparison: () => 'No previous log was given, so nothing here says whether the bill moved — a summary without a comparison states the bill, not its stability.',
2096
- summaryFooter: () => 'The short form: what changed and the largest lever, nothing else. Run trazum profile for the full report — every figure here comes from it.',
2156
+ summaryNoComparison: () => 'No previous log was given, so nothing here says whether the bill moved, a summary without a comparison states the bill, not its stability.',
2157
+ summaryFooter: () => 'The short form: what changed and the largest lever, nothing else. Run trazum profile for the full report: every figure here comes from it.',
2097
2158
  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.`,
2098
- gateLever: (label, action, saving, overage, covers) => `The largest lever the report priced would save ${saving} on ${label} by ${action} — ${covers ? `enough to cover the ${overage} this is over by` : `short of the ${overage} this is over by, so it is part of the answer rather than all of it`}. Whether that is the right call for this workload is yours to judge; the figure is arithmetic, not advice.`,
2159
+ gateLever: (label, action, saving, overage, covers) => `The largest lever the report priced would save ${saving} on ${label} by ${action}, ${covers ? `enough to cover the ${overage} this is over by` : `short of the ${overage} this is over by, so it is part of the answer rather than all of it`}. Whether that is the right call for this workload is yours to judge; the figure is arithmetic, not advice.`,
2099
2160
  gateLeverRoute: (model) => `moving it to ${model}`,
2100
2161
  gateLeverBatch: () => 'sending it through the Batch API',
2101
2162
  gateLeverBoth: (model) => `moving it to ${model} and sending it through the Batch API`,
2102
- gateMarginTight: (margin, room) => `Passed with ${margin} of the budget left — ${room}. Under a tenth is close enough that an ordinary week crosses it; a pass this tight is worth knowing about before it becomes a failure.`,
2103
- 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.`,
2163
+ gateMarginTight: (margin, room) => `Passed with ${margin} of the budget left, ${room}. Under a tenth is close enough that an ordinary week crosses it; a pass this tight is worth knowing about before it becomes a failure.`,
2164
+ 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.`,
2104
2165
  coverageField: (field) => ({ label: 'label', session: 'session', ts: 'timestamp', stopReason: 'stop reason' })[field] ?? field,
2105
2166
  coverageSilenced: (field) => ({
2106
2167
  label: 'Gone quiet with it: per-workload spend, the drill-down, and levers that describe a decision rather than a mixture.',
@@ -2109,24 +2170,24 @@ ${bold('EXAMPLES')}
2109
2170
  stopReason: 'Gone quiet with it: answers cut off at max_tokens, and the retries billed after them.',
2110
2171
  })[field] ?? '',
2111
2172
  coverageDrift: (field, was, now) => `Coverage moved: ${field} was on ${was} of records and is now on ${now}.`,
2112
- 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.',
2113
- 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.`,
2173
+ 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.',
2174
+ 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.`,
2114
2175
  windowLine: (since, until) => `Filtered to --since ${since} --until ${until}. Everything below describes this window, not the whole log; a bare date means the whole of that UTC day.`,
2115
- windowUndated: (calls) => `${count(calls)} ${calls === 1 ? 'call carries' : 'calls carry'} no timestamp and cannot be placed inside or outside this window, so ${calls === 1 ? 'it was' : 'they were'} left out. Their spend is in the log and not in this report — the window's figures are a floor on the period.`,
2116
- windowRelative: () => 'That window is relative to this machine\'s clock, not to the log\'s last record — a log exported a month ago will answer "the last 7 days" with nothing.',
2176
+ windowUndated: (calls) => `${count(calls)} ${calls === 1 ? 'call carries' : 'calls carry'} no timestamp and cannot be placed inside or outside this window, so ${calls === 1 ? 'it was' : 'they were'} left out. Their spend is in the log and not in this report: the window's figures are a floor on the period.`,
2177
+ windowRelative: () => 'That window is relative to this machine\'s clock, not to the log\'s last record: a log exported a month ago will answer "the last 7 days" with nothing.',
2117
2178
  windowRelativeEmpty: () => 'A relative window is measured from this machine\'s clock: if this log was exported earlier, ask for the dates it covers instead.',
2118
- windowNeedsClock: () => 'No record in this log carries a timestamp, so --since/--until have nothing to filter by. A time window over a clockless log would gate nothing, which is not an answer. Add "ts" to the records — the recipe in the README shows where.',
2119
- windowMatchesNothing: (from, to) => `No record falls inside this window. The log covers ${from} → ${to}. A window matching nothing must not become a $0 report — under --max-usd it would pass a budget gate over a period the log does not cover.`,
2179
+ windowNeedsClock: () => 'No record in this log carries a timestamp, so --since/--until have nothing to filter by. A time window over a clockless log would gate nothing, which is not an answer. Add "ts" to the records, the recipe in the README shows where.',
2180
+ windowMatchesNothing: (from, to) => `No record falls inside this window. The log covers ${from} → ${to}. A window matching nothing must not become a $0 report, under --max-usd it would pass a budget gate over a period the log does not cover.`,
2120
2181
  sinceAfterUntil: () => '--since is at or after --until, so the window contains no time at all. Check the two dates.',
2121
2182
  badWhen: (flag, value) => `--${flag} could not read "${value}". It takes a UTC day (2026-08-14) or a full ISO 8601 timestamp (2026-08-14T09:30:00Z).`,
2122
- singleTurnCeiling: (label, model, single, sessions, usd) => `${label} on ${model}: ${single} of ${sessions} conversations ended after their first turn, and their cache writes — ${usd} — paid for reuse their own conversation never made. Another conversation sharing the same prefix within the TTL could have read them; the log cannot see whose write a read hit, so that figure is a ceiling on the waste, not a bill.`,
2123
- singleTurnConfirmed: (label, model, single, sessions, usd) => `${label} on ${model}: ${single} of ${sessions} conversations ended after their first turn and spent ${usd} writing a cache that nothing in this log ever read. Within the conversation, across conversations — no read anywhere, so those writes bought nothing. Caching a one-shot call is pure write premium; stop marking these calls with cache_control.`,
2183
+ singleTurnCeiling: (label, model, single, sessions, usd) => `${label} on ${model}: ${single} of ${sessions} conversations ended after their first turn, and their cache writes, ${usd}, paid for reuse their own conversation never made. Another conversation sharing the same prefix within the TTL could have read them; the log cannot see whose write a read hit, so that figure is a ceiling on the waste, not a bill.`,
2184
+ singleTurnConfirmed: (label, model, single, sessions, usd) => `${label} on ${model}: ${single} of ${sessions} conversations ended after their first turn and spent ${usd} writing a cache that nothing in this log ever read. Within the conversation, across conversations, no read anywhere, so those writes bought nothing. Caching a one-shot call is pure write premium; stop marking these calls with cache_control.`,
2124
2185
  },
2125
2186
  plan: {
2126
- noTarget: () => 'Point this at a usage log or a directory of them: trazum plan usage.jsonl. It turns the report into a ranked plan — what to do first, what each action is worth, and what the log cannot confirm about it.',
2127
- nothingPriced: () => 'This log priced nothing — no call in it matched a model in the catalogue. A plan over zero dollars would be advice about nothing; check the log with "trazum profile" first.',
2187
+ noTarget: () => 'Point this at a usage log or a directory of them: trazum plan usage.jsonl. It turns the report into a ranked plan, what to do first, what each action is worth, and what the log cannot confirm about it.',
2188
+ nothingPriced: () => 'This log priced nothing, no call in it matched a model in the catalogue. A plan over zero dollars would be advice about nothing; check the log with "trazum profile" first.',
2128
2189
  heading: (actions, total) => `The plan: ${actions} actions against a ${total} bill`,
2129
- totals: (projected, staked) => `${projected} projected savings, on assumptions listed below. ${staked} already spent on problems this plan names — measured, not projected.`,
2190
+ totals: (projected, staked) => `${projected} projected savings, on assumptions listed below. ${staked} already spent on problems this plan names, measured, not projected.`,
2130
2191
  noClock: () => 'No timestamps in this log, so every figure is per this log, not per any period.',
2131
2192
  projected: (usd) => `${usd} projected`,
2132
2193
  staked: (usd) => `${usd} already spent`,
@@ -2142,43 +2203,43 @@ ${bold('EXAMPLES')}
2142
2203
  : 'Look at the cache on';
2143
2204
  return `${verb} ${label} (${model})`;
2144
2205
  },
2145
- routeTo: (model) => `to ${model} — combined with batching where both apply, never summed`,
2206
+ routeTo: (model) => `to ${model}, combined with batching where both apply, never summed`,
2146
2207
  assume: (assumption) => {
2147
2208
  switch (assumption.kind) {
2148
2209
  case 'model-capability':
2149
- return `assumes ${assumption.model} can do this work — the log prices the move, it cannot judge the answers`;
2210
+ return `assumes ${assumption.model} can do this work, the log prices the move, it cannot judge the answers`;
2150
2211
  case 'batch-window':
2151
2212
  return 'assumes these calls can wait for a batch window';
2152
2213
  case 'retry-pattern-real':
2153
- return 'assumes the retry pattern is real — the log sees shapes, not content';
2214
+ return 'assumes the retry pattern is real, the log sees shapes, not content';
2154
2215
  case 'max-tokens-fits':
2155
2216
  return 'assumes a max_tokens the answers fit in removes the pair';
2156
2217
  case 'traffic-pattern-holds':
2157
- return 'assumes the traffic pattern holds — a cache that lost money on this log may pay on different traffic';
2218
+ return 'assumes the traffic pattern holds: a cache that lost money on this log may pay on different traffic';
2158
2219
  }
2159
2220
  },
2160
2221
  check: (command) => `check it: ${command}`,
2161
- filtered: (count, minUsd, worth) => `${count} actions under ${minUsd}, worth ${worth} together, left out by --min-usd — left out of this document entirely, not disproved.`,
2222
+ filtered: (count, minUsd, worth) => `${count} actions under ${minUsd}, worth ${worth} together, left out by --min-usd, left out of this document entirely, not disproved.`,
2162
2223
  footer: () => 'Ranked by money, projected or already spent alike. The assumptions are yours to answer: this plan is arithmetic over the log, not knowledge of your product.',
2163
2224
  wrote: (path) => `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
2164
2225
  },
2165
2226
  serve: {
2166
2227
  listening: (where) => `Answering on ${where}`,
2167
2228
  limitsNoLog: () => 'A limits policy is configured and no --log was given, so every ceiling will answer cannot-tell: per-label and per-session spend live in a usage log, not in the store. Point --log at your usage log to make the ceilings judgeable.',
2168
- limitsUnpriced: (count) => `${count} record(s) in the --log name a model the catalogue cannot price. They contribute nothing to any measured figure — money the limits policy cannot see, said here rather than hidden.`,
2169
- loopbackOnly: () => 'Loopback only, and there is no flag to change that: this holds your spend, your model mix and your budgets, and would answer whoever asked. There is no auth for the same reason — a token checked over loopback is theatre.',
2170
- measuredFrom: (usd) => `Budget answers are measured against ${usd} from the store, read once at start. Every answer carries the window that figure covers rather than implying it is current to the second — restart to refresh it.`,
2229
+ limitsUnpriced: (count) => `${count} record(s) in the --log name a model the catalogue cannot price. They contribute nothing to any measured figure: money the limits policy cannot see, said here rather than hidden.`,
2230
+ loopbackOnly: () => 'Loopback only, and there is no flag to change that: this holds your spend, your model mix and your budgets, and would answer whoever asked. There is no auth for the same reason: a token checked over loopback is theatre.',
2231
+ measuredFrom: (usd) => `Budget answers are measured against ${usd} from the store, read once at start. Every answer carries the window that figure covers rather than implying it is current to the second, restart to refresh it.`,
2171
2232
  nothingMeasured: (dir) => `Nothing is measured yet (the store at ${dir} is empty), so the budget half of every answer will say so. The cost half still answers from the catalogue: offline is a mode, not a failure.`,
2172
2233
  noBudget: () => 'No spend.monthlyUsd is configured, so "is there budget left" has no subject and every answer says so rather than guessing one. spend.maxUsd is deliberately not read here: it gates whatever period a log covers, and reading it as a monthly limit is how two surfaces of this tool come to disagree.',
2173
2234
  partialCoverage: (measuredDays, elapsedDays, period) => `Only ${measuredDays} of the ${elapsedDays} elapsed days of ${period} carry any measurement, so the consumed figure is a floor on the period rather than the period. Pull the missing days with trazum connect before treating what is left as headroom.`,
2174
2235
  badPort: (value) => `"${value}" is not a port. Give a whole number from 0 to 65535, or use --socket.`,
2175
2236
  },
2176
2237
  watch: {
2177
- noThresholds: () => 'Watching needs something to watch for. Set spend.maxUsd, spend.maxDayUsd or spend.maxCacheLossUsd in trazum.config.json — a watcher with no threshold is a green light nobody earned.',
2178
- nothingToWatch: (dir) => `Nothing has been measured yet: the store at ${dir} is empty. Fill it with "trazum connect <provider> --store" first — watching nothing would report that everything is fine.`,
2238
+ noThresholds: () => 'Watching needs something to watch for. Set spend.maxUsd, spend.maxDayUsd or spend.maxCacheLossUsd in trazum.config.json: a watcher with no threshold is a green light nobody earned.',
2239
+ nothingToWatch: (dir) => `Nothing has been measured yet: the store at ${dir} is empty. Fill it with "trazum connect <provider> --store" first, watching nothing would report that everything is fine.`,
2179
2240
  intervalTooTight: () => '--interval must be at least 5m. Usage APIs are rate limited, and a tight loop is a way to get your own key throttled by a tool that exists to save you money.',
2180
2241
  badWebhook: (reason) => reason === 'credentials-in-url'
2181
- ? 'That webhook URL carries credentials. URLs end up in logs, shell history and error messages, so this one is refused — put the secret in a header your receiver checks, or in the receiver itself.'
2242
+ ? 'That webhook URL carries credentials. URLs end up in logs, shell history and error messages, so this one is refused, put the secret in a header your receiver checks, or in the receiver itself.'
2182
2243
  : reason === 'insecure-scheme'
2183
2244
  ? 'A webhook must be https, except on loopback. An alert carries your spend figures, and sending them in the clear across a network is a leak you did not ask for.'
2184
2245
  : 'That webhook is not a URL this tool can parse.',
@@ -2188,7 +2249,7 @@ ${bold('EXAMPLES')}
2188
2249
  : gate === 'maxDayUsd'
2189
2250
  ? `Spend on ${day}`
2190
2251
  : 'Money lost to caching';
2191
- return `CROSSED — ${what} is ${measured} against a limit of ${limit}. Measured, not projected.`;
2252
+ return `CROSSED, ${what} is ${measured} against a limit of ${limit}. Measured, not projected.`;
2192
2253
  },
2193
2254
  stillOver: (gate, measured, limit, day) => {
2194
2255
  const what = gate === 'maxUsd'
@@ -2196,31 +2257,31 @@ ${bold('EXAMPLES')}
2196
2257
  : gate === 'maxDayUsd'
2197
2258
  ? `Spend on ${day}`
2198
2259
  : 'Money lost to caching';
2199
- return `STILL OVER — ${what} is ${measured} against a limit of ${limit}, and was already reported. Quiet is not clean.`;
2260
+ return `STILL OVER, ${what} is ${measured} against a limit of ${limit}, and was already reported. Quiet is not clean.`;
2200
2261
  },
2201
2262
  notJudgeable: (gate, reason, covered) => reason === 'window-too-short'
2202
- ? `${gate} cannot be judged yet: this period is ${covered ?? 'partly'} measured, and a threshold over part of a day is a threshold over something else. Not a pass — it will be judged when the day is in.`
2263
+ ? `${gate} cannot be judged yet: this period is ${covered ?? 'partly'} measured, and a threshold over part of a day is a threshold over something else. Not a pass: it will be judged when the day is in.`
2203
2264
  : `${gate} cannot be judged on this source, which does not serve what the gate is written against. Not a pass: a gate silently skipped reads exactly like a gate that keeps passing.`,
2204
2265
  gap: (from, to) => `Nothing was watching between ${from} and ${to}. Whatever crossed in that stretch was not seen, and this line exists so a resumed watcher does not imply coverage it did not have.`,
2205
2266
  allWithin: (gates) => `Within every threshold: ${gates} gates evaluated against measured spend.`,
2206
- webhookFailed: (status) => `The webhook did not deliver (${status}). The crossing is still in the exit code and in the output above — a receiver being down must not be the quietest failure in the room.`,
2267
+ webhookFailed: (status) => `The webhook did not deliver (${status}). The crossing is still in the exit code and in the output above: a receiver being down must not be the quietest failure in the room.`,
2207
2268
  watching: (minutes) => `Watching every ${minutes} minutes. Ctrl-C stops it.`,
2208
2269
  },
2209
2270
  store: {
2210
2271
  appended: (count, dir) => `Kept ${count} measurements in ${dir}.`,
2211
- empty: (dir) => `The store at ${dir} is empty. Fill it with "trazum connect <provider> --store" — that is a state, not an error.`,
2272
+ empty: (dir) => `The store at ${dir} is empty. Fill it with "trazum connect <provider> --store": that is a state, not an error.`,
2212
2273
  heading: (records, usd, from, to) => `The store: ${records} measurements · ${usd} · ${from} → ${to}`,
2213
2274
  providerRow: (provider, records, span, models) => `${provider} ${records} measurements · ${span} · ${models} models`,
2214
- holds: (files) => `Held in ${files} files: token counts, billed dollars and the account's own workspace and key identifiers. Never prompt text, never completion text, never a credential — this is a file you can back up without a privacy review.`,
2215
- possiblyDouble: (count) => `${count} records could not be told apart from another — a window of no length, or a record naming no model. They are kept whole rather than merged, so a total built on them may count the same spend twice. Saying so beats a smaller number nobody can check.`,
2275
+ holds: (files) => `Held in ${files} files: token counts, billed dollars and the account's own workspace and key identifiers. Never prompt text, never completion text, never a credential: this is a file you can back up without a privacy review.`,
2276
+ possiblyDouble: (count) => `${count} records could not be told apart from another, a window of no length, or a record naming no model. They are kept whole rather than merged, so a total built on them may count the same spend twice. Saying so beats a smaller number nobody can check.`,
2216
2277
  unknownVersion: (count) => `${count} records come from a newer schema than this version knows, so they are kept and left out of the figures above rather than guessed at. Upgrade to read them.`,
2217
- unreadable: (file, line) => `${file} line ${line} would not parse, so it is not in the figures above. The rest of the file was read — one broken line must not lose a month.`,
2278
+ unreadable: (file, line) => `${file} line ${line} would not parse, so it is not in the figures above. The rest of the file was read: one broken line must not lose a month.`,
2218
2279
  retention: (days) => `Retention: ${days} days, from "store.keepDays". Run "trazum store --prune" to apply it.`,
2219
2280
  noRetention: () => 'No retention policy is configured, so nothing is ever deleted on its own. Set "store": {"keepDays": 90} when you want one.',
2220
2281
  pruneNeedsPolicy: () => 'Pruning needs a retention policy: set "store": {"keepDays": 90} in trazum.config.json, or pass --keep 90d for this run. Deleting measurements on a policy nobody wrote down is not a default you should get by accident.',
2221
2282
  pruneDryRun: (count, days, span, usd) => span === null
2222
2283
  ? `Nothing is older than ${days} days, so a prune would delete nothing.`
2223
- : `A prune would delete ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. Nothing was deleted — this was --dry-run.`,
2284
+ : `A prune would delete ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. Nothing was deleted: this was --dry-run.`,
2224
2285
  pruned: (count, days, span, usd, kept) => span === null
2225
2286
  ? `Nothing was older than ${days} days. ${kept} measurements kept, and the append log compacted.`
2226
2287
  : `Deleted ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. ${kept} kept, and the append log compacted to what the store already resolved to.`,
@@ -2236,27 +2297,27 @@ ${bold('EXAMPLES')}
2236
2297
  ? 'Whether that is fast or slow for the month cannot be told from a floor: the unmeasured days spent something, and only an overrun would be unarguable.'
2237
2298
  : 'There is nothing to compare the spend against yet.',
2238
2299
  budgetNeverForecast: () => 'That is a shape, not a forecast. Where this goes next depends on what you do next, and no arithmetic here knows that.',
2239
- budgetNothingMeasured: (elapsedDays) => `Nothing has been measured this month, across ${elapsedDays} elapsed ${elapsedDays === 1 ? 'day' : 'days'}. That is not a budget under control — it is a budget nobody is watching. Run trazum connect to pull what the provider has.`,
2300
+ budgetNothingMeasured: (elapsedDays) => `Nothing has been measured this month, across ${elapsedDays} elapsed ${elapsedDays === 1 ? 'day' : 'days'}. That is not a budget under control: it is a budget nobody is watching. Run trazum connect to pull what the provider has.`,
2240
2301
  budgetPartial: (measuredDays, elapsedDays, days) => `Only ${measuredDays} of ${elapsedDays} elapsed days carry any measurement, so the figure below is a floor on the month rather than the month. Missing: ${days}.`,
2241
2302
  budgetScopesUnmeasured: (count) => `${count} budgeted ${count === 1 ? 'scope' : 'scopes'} (per label or per service) cannot be answered from the store: a store record carries a provider and a model, not a workload label. Gate those with trazum profile against a per-call log.`,
2242
2303
  },
2243
2304
  connect: {
2244
- noTarget: (providers) => `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored — add --dry-run to see exactly what would be called and which variable it would be read from.`,
2305
+ noTarget: (providers) => `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored. Add --dry-run to see exactly what would be called and which variable it would be read from.`,
2245
2306
  unknownProvider: (id, providers) => `There is no connector for "${id}". The ones that exist are: ${providers}.`,
2246
- pricedNoConnector: (id, providers) => `Trazum prices ${id} but has no connector for it yet — it connects to ${providers}. Either that provider publishes no usage API, or one has not been written; both are gaps rather than mistakes of yours. Until then, export a log and run "trazum profile" on it: every figure works except the ones a usage API would supply on its own.`,
2307
+ pricedNoConnector: (id, providers) => `Trazum prices ${id} but has no connector for it yet, it connects to ${providers}. Either that provider publishes no usage API, or one has not been written; both are gaps rather than mistakes of yours. Until then, export a log and run "trazum profile" on it: every figure works except the ones a usage API would supply on its own.`,
2247
2308
  dryRun: (provider, from, to, envVars, keyKind) => `Would read ${provider} usage from ${from} to ${to}, using ${keyKind} taken from ${envVars}. Nothing was sent and no credential was needed to print this.`,
2248
2309
  heading: (provider, from, to, usd, calls) => calls === null
2249
2310
  ? `${provider} · ${from} → ${to} · ${usd}`
2250
2311
  : `${provider} · ${from} → ${to} · ${usd} · ${calls} calls`,
2251
2312
  modelRow: (model, usd, share, calls) => calls === null ? `${model} ${usd} ${share}` : `${model} ${usd} ${share} · ${calls} calls`,
2252
- nothingBilled: () => 'The provider billed nothing in this window. That is a measurement, not an error — widen it with --since if you expected traffic.',
2313
+ nothingBilled: () => 'The provider billed nothing in this window. That is a measurement, not an error, widen it with --since if you expected traffic.',
2253
2314
  cachePaid: (saved) => `Caching paid for itself: ${saved} less than these tokens would have cost as ordinary input.`,
2254
2315
  cacheLost: (added) => `Caching added ${added} to this bill against what the same tokens would have cost as ordinary input.`,
2255
2316
  cacheUnsettled: () => 'This source did not say which TTL the cache writes used, so the cheaper rate was assumed and the verdict moves under the other one. Unsettled, not settled in your favour.',
2256
2317
  noCallCount: (provider) => `${provider}'s usage report serves token sums and no request count, so there is no call count here and no per-call average. A zero would read as "no traffic", so nothing is printed instead.`,
2257
2318
  unpriced: (model, tokens) => `${model} is not in the price catalogue, so its ${tokens} tokens are counted and its money is not. Add it with --pricing rather than reading the total as complete.`,
2258
2319
  gap: (detail) => `This window is incomplete: ${detail}.`,
2259
- unavailable: (findings) => `Findings this source cannot support: ${findings}. They need one row per call, and a sum has lost the rows — a per-call log still answers them.`,
2320
+ unavailable: (findings) => `Findings this source cannot support: ${findings}. They need one row per call, and a sum has lost the rows, a per-call log still answers them.`,
2260
2321
  wrote: (path) => `Report written to ${path}.`,
2261
2322
  footer: () => 'Every figure here is the provider\u2019s own billed token count at the catalogue\u2019s rates. Nothing was estimated, and nothing the provider did not serve was filled in.',
2262
2323
  },
@@ -2267,7 +2328,7 @@ ${bold('EXAMPLES')}
2267
2328
  periodRow: (name, usd, calls, days) => calls === null ? `${name} ${usd} · ${days} days` : `${name} ${usd} · ${calls} calls · ${days} days`,
2268
2329
  runLabel: (label, periods, sinceName, from, to) => `${label} has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. A shape, not a forecast.`,
2269
2330
  runModel: (model, periods, sinceName, from, to) => `${model}'s share of the bill has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. The totals can look flat while the mix moves under them.`,
2270
- runCache: (periods, sinceName, from, to) => `The cache share has decayed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to} — slowly enough that no single report called it a finding, which is exactly why a series exists.`,
2331
+ runCache: (periods, sinceName, from, to) => `The cache share has decayed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}, slowly enough that no single report called it a finding, which is exactly why a series exists.`,
2271
2332
  repeated: (kind, label, model, appearances, first, last) => {
2272
2333
  const what = kind === 'route'
2273
2334
  ? `Routing ${label} (${model})`
@@ -2279,37 +2340,37 @@ ${bold('EXAMPLES')}
2279
2340
  ? `Fixing the truncation retries on ${label} (${model})`
2280
2341
  : `Fixing the cache on ${label} (${model})`;
2281
2342
  const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
2282
- return `${what} has been planned ${appearances} times${span} and is still in the newest plan — a decision nobody is revisiting.`;
2343
+ return `${what} has been planned ${appearances} times${span} and is still in the newest plan: a decision nobody is revisiting.`;
2283
2344
  },
2284
- storeNoLabels: () => 'This series comes from the store, and a usage API groups by model and workspace rather than by workload — so there is no label series here at all. Absent, not empty: nothing above says a workload did or did not move.',
2285
- unmeasured: (days, from, to, after, before) => `Nothing covers ${from} to ${to} — ${plural(days, 'day')} between ${after} and ${before}.`,
2345
+ storeNoLabels: () => 'This series comes from the store, and a usage API groups by model and workspace rather than by workload, so there is no label series here at all. Absent, not empty: nothing above says a workload did or did not move.',
2346
+ unmeasured: (days, from, to, after, before) => `Nothing covers ${from} to ${to}, ${plural(days, 'day')} between ${after} and ${before}.`,
2286
2347
  unmeasuredTotal: (days) => `${plural(days, 'day')} of this stretch are covered by no report. A series with a hole in it and a shorter series read identically; this is which.`,
2287
- overlap: (a, b, days) => `${a} and ${b} both cover ${plural(days, 'day')}. Named, never merged — which is the better measurement is not knowable from here, and adding both totals counts those days twice.`,
2288
- runHole: (days) => ` — ${plural(days, 'day')} of this run are covered by no report`,
2289
- undated: (name) => `${name} carries no span, so it is on no timeline above — named, never silently absorbed.`,
2348
+ overlap: (a, b, days) => `${a} and ${b} both cover ${plural(days, 'day')}. Named, never merged, which is the better measurement is not knowable from here, and adding both totals counts those days twice.`,
2349
+ runHole: (days) => `, ${plural(days, 'day')} of this run are covered by no report`,
2350
+ undated: (name) => `${name} carries no span, so it is on no timeline above, named, never silently absorbed.`,
2290
2351
  unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
2291
- footer: () => 'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable — where these lines go next is yours to judge.',
2352
+ footer: () => 'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable, where these lines go next is yours to judge.',
2292
2353
  waiverHeading: () => 'What this repository has been living with',
2293
2354
  waiverSince: (day, uses) => `${uses} recorded ${uses === 1 ? 'use' : 'uses'} since ${day}, when recording started.`,
2294
- waiverNoneRecorded: () => 'No waiver has silenced a gate since recording started. Nothing here is inferred from the config — a waiver written down and never hit is not a decision anyone is living with.',
2355
+ waiverNoneRecorded: () => 'No waiver has silenced a gate since recording started. Nothing here is inferred from the config: a waiver written down and never hit is not a decision anyone is living with.',
2295
2356
  waiverHabit: (gate, uses, days, firstDay, lastDay) => `${gate}: ${uses} ${uses === 1 ? 'use' : 'uses'} across ${days} ${days === 1 ? 'day' : 'days'}, ${firstDay} to ${lastDay}`,
2296
2357
  waiverVerdict: (verdict) => verdict === 'used-once'
2297
2358
  ? 'Used once. Nothing to read into it yet.'
2298
2359
  : verdict === 'recurring'
2299
2360
  ? 'The same decision, holding. The gate keeps firing and the reason has not moved.'
2300
2361
  : verdict === 'renewed-without-revisiting'
2301
- ? 'The expiry has moved and the reason has not. That is the shape a decision takes when nobody is revisiting it — which is sometimes exactly right, and worth saying out loud either way.'
2362
+ ? 'The expiry has moved and the reason has not. That is the shape a decision takes when nobody is revisiting it, which is sometimes exactly right, and worth saying out loud either way.'
2302
2363
  : 'The reason changed between uses. Somebody looked again.',
2303
2364
  waiverReasonNow: (reason) => `Reason: ${reason}`,
2304
2365
  waiverReasonsChanged: (count) => `${count} different reasons given over that time.`,
2305
2366
  waiverExpiriesMoved: (from, to, count) => `Expiry moved ${count} ${count === 1 ? 'time' : 'times'}: ${from} → ${to}.`,
2306
2367
  waiverNoLongerConfigured: () => 'Not in the config any more. The decision was reversed; the record keeps it.',
2307
- waiverNeverUsed: (gates) => `Waived in the config and never hit by a recorded run: ${gates}. Either the gate stopped failing — good news nobody wrote down — or the waiver names a situation that does not arise. Both are worth deleting.`,
2368
+ waiverNeverUsed: (gates) => `Waived in the config and never hit by a recorded run: ${gates}. Either the gate stopped failing, good news nobody wrote down, or the waiver names a situation that does not arise. Both are worth deleting.`,
2308
2369
  waiverUnreadable: (count, path) => `${count} ${count === 1 ? 'line' : 'lines'} in ${path} could not be read and are not counted above.`,
2309
2370
  waiverStartsHere: () => 'Nothing before that day exists. This record began when recording did, and no past was reconstructed from the config as it stands.',
2310
2371
  },
2311
2372
  verify: {
2312
- noTarget: () => 'Point this at a saved plan and a newer log: trazum verify plan.json --against usage.jsonl. It says, per action, whether the change arrived, did not arrive, or cannot be told — and never fewer than those three.',
2373
+ noTarget: () => 'Point this at a saved plan and a newer log: trazum verify plan.json --against usage.jsonl. It says, per action, whether the change arrived, did not arrive, or cannot be told, and never fewer than those three.',
2313
2374
  needsAgainst: () => '--against <newer.jsonl|dir> is required. A plan can only be verified against a log that came after it; without one there is nothing to hold the prediction to.',
2314
2375
  badPlan: (path, why) => `${path} is not a plan document this tool can verify: ${why}. Expected the JSON that "trazum plan -o" writes.`,
2315
2376
  planRefusal: (why) => why.kind === 'not-json'
@@ -2325,7 +2386,7 @@ ${bold('EXAMPLES')}
2325
2386
  ? `Did it work? ${actions} actions from an undated plan, against this log`
2326
2387
  : `Did it work? ${actions} actions from the plan of ${planDate}, against this log`,
2327
2388
  counts: (arrived, notArrived, cannotTell) => `${arrived} arrived · ${notArrived} did not arrive · ${cannotTell} cannot be told. The third is not a soft version of the second: it means this log cannot answer, which is its own finding.`,
2328
- pricesChanged: (planReviewed, nowReviewed) => `Prices were reviewed ${planReviewed} when the plan was made and ${nowReviewed} now, so every dollar comparison here is two price lists, not one measurement — a team must not be blamed for a saving that arithmetic revoked.`,
2389
+ pricesChanged: (planReviewed, nowReviewed) => `Prices were reviewed ${planReviewed} when the plan was made and ${nowReviewed} now, so every dollar comparison here is two price lists, not one measurement: a team must not be blamed for a saving that arithmetic revoked.`,
2329
2390
  action: (kind, label, model, outcome) => {
2330
2391
  const what = kind === 'route'
2331
2392
  ? `Route ${label} (${model})`
@@ -2337,21 +2398,21 @@ ${bold('EXAMPLES')}
2337
2398
  ? `Fix the truncation retries on ${label} (${model})`
2338
2399
  : `Fix the cache on ${label} (${model})`;
2339
2400
  const verdict = outcome === 'arrived' ? 'ARRIVED' : outcome === 'not-arrived' ? 'DID NOT ARRIVE' : 'CANNOT BE TOLD';
2340
- return `${what} — ${verdict}`;
2401
+ return `${what}, ${verdict}`;
2341
2402
  },
2342
2403
  reason: (reason) => reason === 'workload-vanished'
2343
- ? 'the label carries no priced traffic in this log — a vanished workload is not a fixed one, and not a broken one either'
2404
+ ? 'the label carries no priced traffic in this log: a vanished workload is not a fixed one, and not a broken one either'
2344
2405
  : reason === 'fields-stopped'
2345
- ? 'the fields the detection needs are not in this log — "not recorded" must not read as "fixed", so with --gate this fails'
2346
- : 'the log records tokens, and tokens do not say which tier billed them — the Batch API cannot be seen from here',
2406
+ ? 'the fields the detection needs are not in this log, "not recorded" must not read as "fixed", so with --gate this fails'
2407
+ : 'the log records tokens, and tokens do not say which tier billed them: the Batch API cannot be seen from here',
2347
2408
  routeObserved: (dearestModel, onTargetUsd, onOldUsd) => `the label's dearest model is now ${dearestModel} · ${onTargetUsd} on the target, ${onOldUsd} still on the old model`,
2348
2409
  batchUnobservable: () => 'the batch half of this action cannot be seen in token counts; the verdict above is the route half alone',
2349
2410
  truncationObserved: (retryBillUsd) => `this log still shows ${retryBillUsd} of truncation waste and retries`,
2350
2411
  cacheObserved: (deltaUsd, outcome) => outcome === 'arrived'
2351
2412
  ? `caching now pays for itself on this slice (${deltaUsd} against the no-cache bill)`
2352
2413
  : `caching still adds ${deltaUsd} to this slice's bill`,
2353
- attribution: (callsBefore, callsAfter, outBefore, outAfter) => `the world moved too: calls ${callsBefore} → ${callsAfter}, output/call ${outBefore} → ${outAfter} tokens — stated so the verdict is not read as the whole story`,
2354
- gateFailed: (failures, total) => `GATE FAILED — ${failures} of ${total} actions did not produce what the plan promised, or stopped being measurable by the team's own log.`,
2414
+ attribution: (callsBefore, callsAfter, outBefore, outAfter) => `the world moved too: calls ${callsBefore} → ${callsAfter}, output/call ${outBefore} → ${outAfter} tokens, stated so the verdict is not read as the whole story`,
2415
+ gateFailed: (failures, total) => `GATE FAILED, ${failures} of ${total} actions did not produce what the plan promised, or stopped being measurable by the team's own log.`,
2355
2416
  gateOk: () => 'Gate passed: every verifiable action arrived, and nothing became unverifiable.',
2356
2417
  footer: () => 'Arrived and did-not-arrive are measurements; cannot-be-told is the log refusing to guess. All three are the verification working, not failing.',
2357
2418
  },
@@ -2361,18 +2422,18 @@ ${bold('EXAMPLES')}
2361
2422
  labelNotFound: (label, available) => `No call in this log carries the label "${label}". The labels here are: ${available}.`,
2362
2423
  noRoute: () => 'No route on this log clears 1% of the bill. These calls are already on the cheapest model of their family, or the catalogue has nothing below them.',
2363
2424
  picked: (label, model, candidate, usd, pct) => `${label} on ${model} → ${candidate}, worth ${usd} of this bill (${pct}).`,
2364
- willSpend: (calls, model, candidate) => `This will make ${count(calls)} provider calls: two per case on ${model} to measure its own variance, one per case on ${candidate}. Nothing has been spent yet — add --yes to run it.`,
2425
+ willSpend: (calls, model, candidate) => `This will make ${count(calls)} provider calls: two per case on ${model} to measure its own variance, one per case on ${candidate}. Nothing has been spent yet. Add --yes to run it.`,
2365
2426
  dryRun: () => 'Nothing was called.',
2366
2427
  running: (cases) => `Running ${count(cases)} cases...`,
2367
- agreement: (cross, self) => `The cheaper model agrees with the original ${cross} of the time. The original agrees with itself ${self} of the time — that is the yardstick, not 100%.`,
2368
- holds: (usd) => `HOLDS — the difference is inside the original model's own noise. On this bill that route is worth ${usd}.`,
2369
- diverges: (usd) => `DIVERGES — the cheaper model gives materially different answers. The ${usd} is real and so is the change in behaviour; this one is not free money.`,
2370
- inconclusive: () => 'INCONCLUSIVE — the original model was too inconsistent with itself on these cases to judge anything against. Add cases, or pick ones with less room for the model to wander.',
2371
- unlabelledSlice: () => 'These calls carry no label, so Trazum cannot tell whether they are all this prompt. If they are not, the figure above covers calls this measurement never touched — add "label" to the record and the slice becomes one workload, which is what makes the number attributable.',
2372
- yours: () => 'Agreement is not correctness. This measures whether the answers moved, not whether they were ever right — the decision is still yours.',
2428
+ agreement: (cross, self) => `The cheaper model agrees with the original ${cross} of the time. The original agrees with itself ${self} of the time: that is the yardstick, not 100%.`,
2429
+ holds: (usd) => `HOLDS: the difference is inside the original model's own noise. On this bill that route is worth ${usd}.`,
2430
+ diverges: (usd) => `DIVERGES: the cheaper model gives materially different answers. The ${usd} is real and so is the change in behaviour; this one is not free money.`,
2431
+ inconclusive: () => 'INCONCLUSIVE: the original model was too inconsistent with itself on these cases to judge anything against. Add cases, or pick ones with less room for the model to wander.',
2432
+ unlabelledSlice: () => 'These calls carry no label, so Trazum cannot tell whether they are all this prompt. If they are not, the figure above covers calls this measurement never touched. Add "label" to the record and the slice becomes one workload, which is what makes the number attributable.',
2433
+ yours: () => 'Agreement is not correctness. This measures whether the answers moved, not whether they were ever right: the decision is still yours.',
2373
2434
  },
2374
2435
  baseline: {
2375
- recorded: (path, files, tokens) => `Recorded ${files} prompts, ${tokens} tokens, to ${path}. Commit it — the gate compares the tree against what is committed.`,
2436
+ recorded: (path, files, tokens) => `Recorded ${files} prompts, ${tokens} tokens, to ${path}. Commit it: the gate compares the tree against what is committed.`,
2376
2437
  recordedMoney: (monthly, model, calls) => `That is ${monthly} per month with ${model} at ${calls} calls. Reported, not gated on: thresholds are in tokens, so a repriced model never fails a build on its own.`,
2377
2438
  heading: () => 'Against the baseline',
2378
2439
  unchanged: (tokens) => `unchanged at ${tokens} tokens`,
@@ -2393,7 +2454,7 @@ ${bold('EXAMPLES')}
2393
2454
  slots: {
2394
2455
  task: {
2395
2456
  question: 'What should the model do, in one sentence?',
2396
- unlocks: 'the whole prompt — without it there is nothing to write',
2457
+ unlocks: 'the whole prompt, without it there is nothing to write',
2397
2458
  },
2398
2459
  role: {
2399
2460
  question: 'Who is the model being while it does that?',
@@ -2401,7 +2462,7 @@ ${bold('EXAMPLES')}
2401
2462
  },
2402
2463
  inputs: {
2403
2464
  question: 'What changes from one call to the next?',
2404
- unlocks: 'the varying part — without it the prompt hard-codes one case and is rewritten for the next',
2465
+ unlocks: 'the varying part, without it the prompt hard-codes one case and is rewritten for the next',
2405
2466
  },
2406
2467
  'output-shape': {
2407
2468
  question: 'What should come back: prose, json, list or table?',
@@ -2417,7 +2478,7 @@ ${bold('EXAMPLES')}
2417
2478
  },
2418
2479
  audience: {
2419
2480
  question: 'Who reads the output?',
2420
- unlocks: 'the register — an answer for an engineer and one for a customer are different answers',
2481
+ unlocks: 'the register: an answer for an engineer and one for a customer are different answers',
2421
2482
  },
2422
2483
  constraints: {
2423
2484
  question: 'What must it never do?',
@@ -2433,7 +2494,7 @@ ${bold('EXAMPLES')}
2433
2494
  },
2434
2495
  'example-inputs': {
2435
2496
  question: 'What input produced that example?',
2436
- unlocks: 'the pairing — an example answer with no input teaches the shape and not the mapping',
2497
+ unlocks: 'the pairing, an example answer with no input teaches the shape and not the mapping',
2437
2498
  },
2438
2499
  'failure-modes': {
2439
2500
  question: 'What has gone wrong with this before?',
@@ -2441,11 +2502,11 @@ ${bold('EXAMPLES')}
2441
2502
  },
2442
2503
  model: {
2443
2504
  question: 'Which model is this for?',
2444
- unlocks: 'the cost estimate — this changes the report and never the prompt',
2505
+ unlocks: 'the cost estimate, this changes the report and never the prompt',
2445
2506
  },
2446
2507
  budget: {
2447
2508
  question: 'What is the monthly ceiling for this prompt?',
2448
- unlocks: 'the budget check — this changes the report and never the prompt',
2509
+ unlocks: 'the budget check, this changes the report and never the prompt',
2449
2510
  },
2450
2511
  },
2451
2512
  missing: (count) => count === 1
@@ -2458,7 +2519,7 @@ ${bold('EXAMPLES')}
2458
2519
  : `"${id}" is not a slot. Did you mean "${nearest}"?`,
2459
2520
  answerNotText: (id) => `"${id}" must be a string, or null to decline it.`,
2460
2521
  tokens: (count) => `${count} tokens`,
2461
- monthly: (usd) => `${usd} per month, estimated — nobody has sent this prompt yet`,
2522
+ monthly: (usd) => `${usd} per month, estimated: nobody has sent this prompt yet`,
2462
2523
  budget: (verdict, limit) => verdict === 'over' ? `over the budget of ${limit}` : `within the budget of ${limit}`,
2463
2524
  noVerdict: (reason) => reason === 'no-budget'
2464
2525
  ? 'No budget answered, so there is nothing to check it against.'
@@ -2466,7 +2527,7 @@ ${bold('EXAMPLES')}
2466
2527
  ? 'No model answered, so it cannot be priced.'
2467
2528
  : 'That model is not in the price catalogue, so it cannot be priced.',
2468
2529
  clean: () => 'trazum optimize recovers nothing from this.',
2469
- notClean: (rules, tokens) => `trazum optimize would still recover ${tokens} tokens here (${rules}) — from your answers, not from the structure.`,
2530
+ notClean: (rules, tokens) => `trazum optimize would still recover ${tokens} tokens here (${rules}), from your answers, not from the structure.`,
2470
2531
  declined: (ids) => `Declined, and left out: ${ids}`,
2471
2532
  },
2472
2533
  };