@trazum/cli 1.82.0 → 1.85.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/index.js CHANGED
@@ -7,8 +7,9 @@ import { createInterface } from 'node:readline/promises';
7
7
  import { dirname, join, resolve as resolvePath } from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
9
  import { gunzipSync } from 'node:zlib';
10
- import { CONTRACT_NAMES, contractSchema, applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, rollUp, heartbeats, ruleYield, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, matchGlob, MAX_INPUT_CHARS, moneyIsComparable, mostSpecificMatch, assemble, interview, nearestName, slot, SLOT_IDS, optimize, parseBaseline, PHRASE_LANGUAGES, detectTextLanguage, dictionaryStanding, languagesWithStanding, indexUsage, parseUsageLine, plannedCalls, claudeCodeRecords, ESTIMATE_ERROR_BAND_PCT, bandFor, foreignTokenizer, measuredForeignError, heliconeRecords, litellmRecords, otelRecords, ownRate, positionAt, positionReport, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, switchAnalysis, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
10
+ import { CONTRACT_NAMES, contractSchema, applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, rollUp, heartbeats, ruleYield, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, receiptFrom, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, matchGlob, MAX_INPUT_CHARS, moneyIsComparable, mostSpecificMatch, assemble, interview, nearestName, slot, SLOT_IDS, optimize, parseBaseline, PHRASE_LANGUAGES, detectTextLanguage, dictionaryStanding, languagesWithStanding, indexUsage, parseUsageLine, plannedCalls, claudeCodeRecords, ESTIMATE_ERROR_BAND_PCT, bandFor, foreignTokenizer, measuredForeignError, heliconeRecords, langsmithRecords, litellmRecords, otelRecords, ownRate, positionAt, positionReport, PRICING_LAST_REVIEWED, PROVIDER_REVIEWED, STALE_PRICING_DAYS, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, switchAnalysis, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, isOffered, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
11
11
  import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
12
+ import { OPTIONAL_COUNTERS } from './optional-counters.js';
12
13
  import { dayOf, formatGap, median, spanDays } from './time.js';
13
14
  // Everything that reads the filesystem, on its own entry point so the web
14
15
  // bundle cannot reach it. See packages/core/src/node.ts.
@@ -362,7 +363,7 @@ const COMMAND_FLAGS = {
362
363
  ],
363
364
  check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline', 'files-from'],
364
365
  baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
365
- profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'html-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source'],
366
+ profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'html-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source', 'allow-empty'],
366
367
  plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
367
368
  verify: ['against', 'gate', 'json', 'markdown-out', 'pricing', 'pricing-live'],
368
369
  history: ['store', 'json', 'markdown-out'],
@@ -381,10 +382,12 @@ const COMMAND_FLAGS = {
381
382
  schema: [],
382
383
  rollup: ['json', 'html-out'],
383
384
  position: ['json', 'html-out', 'pricing', 'pricing-live'],
385
+ receipt: ['out', 'o', 'stamp', 'pricing', 'pricing-live'],
384
386
  'from-claude-code': ['label', 'label-from-project', 'out', 'o', 'state'],
385
387
  'from-otel': ['label-from-service', 'out', 'o'],
386
388
  'from-litellm': ['out', 'o'],
387
389
  'from-helicone': ['out', 'o'],
390
+ 'from-langsmith': ['out', 'o'],
388
391
  switch: ['to', 'migration-usd', 'cases'],
389
392
  ownrate: ['gpu-usd-hour', 'tokens-per-second', 'utilization'],
390
393
  pulse: ['json', 'max-stale-hours'],
@@ -769,7 +772,7 @@ measured = null) {
769
772
  *
770
773
  * `optimize` is the first command anybody runs, and it reports the smallest
771
774
  * line item on the bill: measured, about 1% of a monthly figure. Everything
772
- * that moves 40% to 80% — which model the call goes to, the Batch API,
775
+ * that moves 60% to 80% — which model the call goes to, the Batch API,
773
776
  * caching, what re-sending the conversation costs — lives in `profile`, which
774
777
  * needs a usage log a new reader does not have and has no reason to go looking
775
778
  * for.
@@ -993,7 +996,23 @@ function defaultModelFor(provider, pricing) {
993
996
  // not an edge one.
994
997
  const RANK = { small: 0, mid: 1, large: 2, frontier: 3 };
995
998
  const want = RANK[getModel(DEFAULT_USAGE.model).capability] ?? 2;
996
- const candidates = pricing.models.filter((m) => m.provider === provider && m.recommendable !== false);
999
+ /**
1000
+ * Offered first, and a retired model only when the provider has nothing else.
1001
+ *
1002
+ * `isOffered` is the rule everywhere a model is recommended, and this is not
1003
+ * quite that: nothing is being recommended here, a provider's call is being
1004
+ * priced. The distinction matters because three providers in this catalogue
1005
+ * have **only** retired ids today, and dropping them would return null and
1006
+ * fall through to the global default — printing "goes to deepseek / priced as
1007
+ * Claude Opus 5", which is wrong by an order of magnitude in the direction
1008
+ * this function exists to avoid.
1009
+ *
1010
+ * So a retired model's price is still that provider's price and is used as a
1011
+ * last resort. What the reader is not left to infer is that it is current:
1012
+ * `buildAdvisories` warns by name on a retired id, quoting the provider.
1013
+ */
1014
+ const offered = pricing.models.filter((m) => m.provider === provider && isOffered(m));
1015
+ const candidates = offered.length > 0 ? offered : pricing.models.filter((m) => m.provider === provider);
997
1016
  const best = candidates.reduce((chosen, m) => {
998
1017
  if (chosen === null)
999
1018
  return m;
@@ -2288,6 +2307,77 @@ async function commandFromClaudeCode(args, t) {
2288
2307
  console.error(t.fromClaudeCode.labelled());
2289
2308
  console.error(t.fromClaudeCode.skipped(otherLines, unparseable, withoutUsage));
2290
2309
  }
2310
+ /**
2311
+ * `trazum receipt <usage.jsonl|dir>` — the bill's counts, with the provenance
2312
+ * of every figure attached.
2313
+ *
2314
+ * A profile answers a question on the terminal that ran it. The same figures
2315
+ * filed against an invoice, or read next month by somebody who was not there,
2316
+ * stop answering it: a dollar total with no provenance cannot tell a repricing
2317
+ * from a team whose spend moved. This writes the shape that keeps answering.
2318
+ *
2319
+ * **It sends nothing anywhere.** There is no endpoint, no key, no retry and no
2320
+ * queue: the document goes to a path you name or to standard output, and what
2321
+ * happens to it next is not this command's business. A command in this package
2322
+ * that phoned home would break the roadmap's first rule in the same release
2323
+ * that claims to be protecting it.
2324
+ *
2325
+ * **The document is undated unless you ask for a stamp**, and that is a
2326
+ * deliberate default rather than an omission. This product's first promise is
2327
+ * the same answer every time; a command that wrote the current clock into its
2328
+ * output would produce different bytes on every run, so it could not be
2329
+ * committed, diffed in a pull request, or compared against yesterday's. The
2330
+ * period the figures actually cover is already in the document, read from the
2331
+ * log's own clock. `--stamp` adds the emission time for whoever wants it, and
2332
+ * an undated receipt is valid: `receiptFrom` says so, and says why.
2333
+ *
2334
+ * The offline guard found this. The command stamped by default, two runs
2335
+ * disagreed, and the test that exists to catch a hidden network call caught a
2336
+ * hidden clock instead.
2337
+ *
2338
+ * The redaction property is not enforced here. It is a property of
2339
+ * `receiptFrom`, which takes a `UsageProfileReport` -- a shape with no field
2340
+ * that can hold prompt text -- and it is held by `receipt-redaction.test.js`
2341
+ * planting the 4 things that must never appear. This function only chooses the
2342
+ * log and the destination.
2343
+ */
2344
+ async function commandReceipt(args, pricing, t) {
2345
+ const file = args.positional[0];
2346
+ if (file === undefined)
2347
+ throw new Error(t.receipt.noLog());
2348
+ const text = await readUsageLog(file, t);
2349
+ const report = profileUsage(text, { catalogue: pricing });
2350
+ const document = receiptFrom(report, pricing, boolFlag(args, 'stamp') ? { emittedAt: new Date() } : {});
2351
+ const json = JSON.stringify(document, null, 2);
2352
+ const out = stringFlag(args, 'out') ?? stringFlag(args, 'o');
2353
+ if (out !== undefined) {
2354
+ await writeFile(out, json + '\n', 'utf8');
2355
+ console.error(t.receipt.written(out, document.lines.length));
2356
+ }
2357
+ else {
2358
+ console.log(json);
2359
+ }
2360
+ /*
2361
+ * Everything below goes to stderr, so `trazum receipt log.jsonl > receipt.json`
2362
+ * writes a document and not a document with a summary stapled to the front.
2363
+ * The gaps are read off the document rather than recomputed, so what the
2364
+ * reader is told and what the file carries cannot drift apart.
2365
+ */
2366
+ if (document.lines.length === 0) {
2367
+ console.error(t.receipt.nothingToBill());
2368
+ }
2369
+ else {
2370
+ console.error(t.receipt.summary(document.lines.length, formatUsd(document.total.usd)));
2371
+ }
2372
+ for (const gap of document.gaps) {
2373
+ if (gap.kind === 'unpriced')
2374
+ console.error(t.receipt.unpriced(gap.models.length, gap.calls));
2375
+ if (gap.kind === 'unread-lines')
2376
+ console.error(t.receipt.unread(gap.count));
2377
+ if (gap.kind === 'no-clock')
2378
+ console.error(t.receipt.noClock());
2379
+ }
2380
+ }
2291
2381
  /**
2292
2382
  * `trazum from-otel <file|dir>` — OpenTelemetry GenAI spans as a usage log.
2293
2383
  *
@@ -2582,6 +2672,94 @@ async function commandFromLiteLlm(args, t) {
2582
2672
  if (unparseable > 0)
2583
2673
  console.error(t.fromLiteLlm.unparseable(unparseable));
2584
2674
  }
2675
+ /**
2676
+ * `trazum from-langsmith <file|dir>` — a LangSmith run export as a usage log.
2677
+ *
2678
+ * The fifth converter, and the one where the unit is wrong before anything
2679
+ * else can be right: LangSmith records a **run**, and a trace is a tree of
2680
+ * them. The chain that wrapped a model call carries the same tokens as the
2681
+ * call, so summing the export bills them once per level. Only `run_type: llm`
2682
+ * is a call, and every run that is not one is counted out loud — skipping two
2683
+ * thirds of a file silently would look exactly like reading it.
2684
+ *
2685
+ * The model is refused rather than inferred. There is no model column; the
2686
+ * name lives in the metadata, and the obvious substitute is the run's own
2687
+ * `name`, which LangChain sets to the client class. Pricing a call by
2688
+ * `ChatAnthropic` would attribute a figure to something it does not describe.
2689
+ *
2690
+ * LangSmith's own cost is reported on its own line and never merged into
2691
+ * anything Trazum computes, the way `from-litellm` keeps the gateway's
2692
+ * arithmetic apart. Two price tables summed into one total is how a report
2693
+ * becomes quietly wrong.
2694
+ */
2695
+ async function commandFromLangsmith(args, t) {
2696
+ const target = args.positional[0];
2697
+ if (target === undefined)
2698
+ throw new Error(t.fromLangsmith.noPath());
2699
+ let info;
2700
+ try {
2701
+ info = await stat(target);
2702
+ }
2703
+ catch {
2704
+ throw new Error(t.fromLangsmith.notFound(target));
2705
+ }
2706
+ const files = [];
2707
+ if (info.isDirectory()) {
2708
+ const entries = await readdir(target, { recursive: true, withFileTypes: true });
2709
+ for (const entry of entries) {
2710
+ if (entry.isFile() && /\.(json|jsonl|ndjson)$/i.test(entry.name)) {
2711
+ files.push(join(entry.parentPath, entry.name));
2712
+ }
2713
+ }
2714
+ files.sort();
2715
+ if (files.length === 0)
2716
+ throw new Error(t.fromLangsmith.noExports(target));
2717
+ }
2718
+ else {
2719
+ files.push(target);
2720
+ }
2721
+ const lines = [];
2722
+ let rows = 0;
2723
+ let notModelCalls = 0;
2724
+ let unnamedModel = 0;
2725
+ let noTokens = 0;
2726
+ let unparseable = 0;
2727
+ let reportedCostUsd = null;
2728
+ for (const file of files) {
2729
+ const conversion = langsmithRecords(await readFile(file, 'utf8'));
2730
+ for (const record of conversion.records)
2731
+ lines.push(JSON.stringify(record));
2732
+ rows += conversion.rows;
2733
+ notModelCalls += conversion.notModelCalls;
2734
+ unnamedModel += conversion.unnamedModel;
2735
+ noTokens += conversion.noTokens;
2736
+ unparseable += conversion.unparseable;
2737
+ if (conversion.reportedCostUsd !== null) {
2738
+ reportedCostUsd = (reportedCostUsd ?? 0) + conversion.reportedCostUsd;
2739
+ }
2740
+ }
2741
+ const out = stringFlag(args, 'out') ?? stringFlag(args, 'o');
2742
+ if (out !== undefined) {
2743
+ await writeFile(out, lines.join('\n') + (lines.length > 0 ? '\n' : ''), 'utf8');
2744
+ console.error(t.fromLangsmith.written(out));
2745
+ }
2746
+ else {
2747
+ for (const line of lines)
2748
+ console.log(line);
2749
+ }
2750
+ console.error(t.fromLangsmith.summary(files.length, rows));
2751
+ if (notModelCalls > 0)
2752
+ console.error(t.fromLangsmith.notModelCalls(notModelCalls));
2753
+ if (unnamedModel > 0)
2754
+ console.error(t.fromLangsmith.unnamedModel(unnamedModel));
2755
+ if (noTokens > 0)
2756
+ console.error(t.fromLangsmith.noTokens(noTokens));
2757
+ if (reportedCostUsd !== null) {
2758
+ console.error(t.fromLangsmith.reportedCost(formatUsd(reportedCostUsd)));
2759
+ }
2760
+ if (unparseable > 0)
2761
+ console.error(t.fromLangsmith.unparseable(unparseable));
2762
+ }
2585
2763
  /**
2586
2764
  * `trazum from-helicone <file|dir>` — a Helicone request export as a usage log.
2587
2765
  *
@@ -4116,7 +4294,35 @@ function commandModels(t, pricing) {
4116
4294
  const col = t.models.columns;
4117
4295
  console.log();
4118
4296
  console.log(sectionHeading(`${t.models.title()}${t.models.unit()}`));
4119
- console.log(c.dim(t.models.reviewedOn(pricing.lastReviewed, reviewAgeDays(pricing.lastReviewed, new Date()))));
4297
+ const now = new Date();
4298
+ console.log(c.dim(t.models.reviewedOn(pricing.lastReviewed, reviewAgeDays(pricing.lastReviewed, now))));
4299
+ /**
4300
+ * The headline date is the oldest provider's, which is the honest answer to
4301
+ * "how old is this table" and the wrong answer to "how old is the price I am
4302
+ * being quoted". A reader pricing Claude calls was told two months when
4303
+ * their half had been checked that morning, so the providers say for
4304
+ * themselves — and only when they disagree, since one date repeated seven
4305
+ * times is noise.
4306
+ *
4307
+ * Suppressed under an overlay: `--pricing` and `--pricing-live` replace
4308
+ * prices with numbers whose provenance is the overlay's own date, and these
4309
+ * are the bundled table's.
4310
+ */
4311
+ const dates = [...new Set(Object.values(PROVIDER_REVIEWED))];
4312
+ if (dates.length > 1 && pricing.lastReviewed === PRICING_LAST_REVIEWED) {
4313
+ const priced = new Set(pricing.models.map((m) => m.provider));
4314
+ /* Grouped by date: six providers repeating one date is noise, not provenance. */
4315
+ const byDate = new Map();
4316
+ for (const [provider, date] of Object.entries(PROVIDER_REVIEWED)) {
4317
+ if (!priced.has(provider))
4318
+ continue;
4319
+ byDate.set(date, [...(byDate.get(date) ?? []), provider]);
4320
+ }
4321
+ const rows = [...byDate.entries()]
4322
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
4323
+ .map(([date, providers]) => t.models.reviewedGroup(date, reviewAgeDays(date, now), providers.join(', ')));
4324
+ console.log(c.dim(t.models.reviewedByProvider(rows.join(' · '))));
4325
+ }
4120
4326
  console.log();
4121
4327
  const rows = pricing.models.map((m) => ({
4122
4328
  id: m.id,
@@ -4295,6 +4501,48 @@ async function readInput(source, t, limit = null) {
4295
4501
  const text = await readFile(source, 'utf8');
4296
4502
  return limit === null ? text : capInput(text, source, limit, t);
4297
4503
  }
4504
+ /**
4505
+ * A counter for this model from an optional package, or `null`.
4506
+ *
4507
+ * `null` covers three different situations on purpose -- the package is not
4508
+ * installed, it is installed and does not know this model, or the model belongs
4509
+ * to a family no optional package exists for. The caller does not branch on
4510
+ * which: it falls through to the remote path, which produces the right sentence
4511
+ * for each. What matters here is that **a missing package is not an error**.
4512
+ * `@trazum/core` depends on nothing and so does this CLI; a dynamic import that
4513
+ * throws `ERR_MODULE_NOT_FOUND` is the normal, expected state of a machine that
4514
+ * did not opt in, and turning it into a crash would make an optional dependency
4515
+ * a required one by accident.
4516
+ */
4517
+ async function localCounterFor(model) {
4518
+ let loaded;
4519
+ try {
4520
+ /*
4521
+ * The specifier is built rather than written literally, so `tsc` cannot
4522
+ * resolve it at compile time and try to type-check a package that may not
4523
+ * be installed. The cast is to the contract declared above, which is
4524
+ * checked against the real package by a test rather than assumed here.
4525
+ */
4526
+ const specifier = ['@trazum', 'tokenizer-openai'].join('/');
4527
+ loaded = (await import(specifier));
4528
+ }
4529
+ catch {
4530
+ /*
4531
+ * Not installed. Deliberately swallowed and not logged: it is the default
4532
+ * state, and a CLI that warned about it on every run would be nagging
4533
+ * people to install twenty-two megabytes they have already decided against.
4534
+ */
4535
+ return null;
4536
+ }
4537
+ const result = await loaded.openaiCounter(model);
4538
+ if (!result.ok)
4539
+ return null;
4540
+ return {
4541
+ count: result.count,
4542
+ counter: 'openai-tiktoken',
4543
+ detail: result.encoding,
4544
+ };
4545
+ }
4298
4546
  async function commandOptimize(args, config, pricing, t, locale) {
4299
4547
  /**
4300
4548
  * `--all-labels`: every mapped prompt against its own measured traffic,
@@ -4556,28 +4804,60 @@ async function commandOptimize(args, config, pricing, t, locale) {
4556
4804
  }
4557
4805
  if (boolFlag(args, 'exact-tokens')) {
4558
4806
  /**
4559
- * The family check comes **before** the key check, and the order is the
4560
- * point.
4561
- *
4562
- * This branch used to hand `result.usage.model` straight to Anthropic's
4563
- * `count_tokens`. On a Claude model that is exactly right. On `gpt-5` it
4564
- * sends somebody else's model id to Anthropic and returns either a
4565
- * confusing upstream error or a number counted with the wrong tokenizer and
4566
- * labelled exact — and "exact" is the strongest word this tool uses about a
4567
- * count.
4807
+ * The local counter is tried first, and the order is deliberate.
4568
4808
  *
4569
- * Asking for `ANTHROPIC_API_KEY` first would send a reader on another
4570
- * family to find a credential that could not have helped them.
4809
+ * It costs nothing, sends nothing and needs no credential, so a family it
4810
+ * can count should never be sent looking for a key -- and never sent over
4811
+ * the network at all. A prompt counted here is read in this process and
4812
+ * goes nowhere, which is the distinction `TokenProvenance.where` carries.
4571
4813
  */
4572
- const priced = pricing.byId.get(result.usage.model);
4573
- if (!bandGoverns(priced?.provider)) {
4574
- throw new Error(t.errors.exactTokensWrongFamily(result.usage.model, priced?.provider ?? null));
4814
+ const local = await localCounterFor(result.usage.model);
4815
+ if (local !== null) {
4816
+ result = await withExactTokenCounts(result, async (text) => local.count(text), pricing, {
4817
+ counter: local.counter,
4818
+ model: result.usage.model,
4819
+ detail: local.detail,
4820
+ where: 'local',
4821
+ });
4575
4822
  }
4576
- const apiKey = process.env.ANTHROPIC_API_KEY;
4577
- if (!apiKey) {
4578
- throw new Error(t.errors.exactTokensNeedsKey());
4823
+ else {
4824
+ /**
4825
+ * The family check comes **before** the key check, and the order is the
4826
+ * point.
4827
+ *
4828
+ * This branch used to hand `result.usage.model` straight to Anthropic's
4829
+ * `count_tokens`. On a Claude model that is exactly right. On `gpt-5` it
4830
+ * sends somebody else's model id to Anthropic and returns either a
4831
+ * confusing upstream error or a number counted with the wrong tokenizer and
4832
+ * labelled exact — and "exact" is the strongest word this tool uses about a
4833
+ * count.
4834
+ *
4835
+ * Asking for `ANTHROPIC_API_KEY` first would send a reader on another
4836
+ * family to find a credential that could not have helped them.
4837
+ */
4838
+ const priced = pricing.byId.get(result.usage.model);
4839
+ if (!bandGoverns(priced?.provider)) {
4840
+ /*
4841
+ * A family with an optional counter gets a different sentence from one
4842
+ * with none. "Go and find somebody else's tooling" is the wrong refusal
4843
+ * when the answer ships under this scope and is one install away.
4844
+ */
4845
+ const offered = OPTIONAL_COUNTERS[priced?.provider ?? ''];
4846
+ throw new Error(offered === undefined
4847
+ ? t.errors.exactTokensWrongFamily(result.usage.model, priced?.provider ?? null)
4848
+ : t.errors.exactTokensNeedsPackage(result.usage.model, offered));
4849
+ }
4850
+ const apiKey = process.env.ANTHROPIC_API_KEY;
4851
+ if (!apiKey) {
4852
+ throw new Error(t.errors.exactTokensNeedsKey());
4853
+ }
4854
+ result = await withExactTokenCounts(result, countTokensAnthropic({ apiKey, model: result.usage.model }), pricing, {
4855
+ counter: 'anthropic-count-tokens',
4856
+ model: result.usage.model,
4857
+ detail: 'api.anthropic.com/v1/messages/count_tokens',
4858
+ where: 'remote',
4859
+ });
4579
4860
  }
4580
- result = await withExactTokenCounts(result, countTokensAnthropic({ apiKey, model: result.usage.model }), pricing);
4581
4861
  }
4582
4862
  const outPath = stringFlag(args, 'out');
4583
4863
  if (outPath) {
@@ -5851,615 +6131,315 @@ async function commandVerify(args, pricing, t) {
5851
6131
  }
5852
6132
  }
5853
6133
  /**
5854
- * `trazum plan <log>` — not a list of findings, a ranked plan of what to do.
5855
- *
5856
- * The composition (route and batch on one slice never summed) happens in
5857
- * core's `buildPlan`; this command owns the I/O and the rendering. The plan
5858
- * saves as a dated JSON file on request, which is what makes verifying it
5859
- * against a later log possible at all — a prediction nobody wrote down is a
5860
- * prediction nobody can be held to.
6134
+ * `--by-source`: one report per service, plus the rollup, the fleet.
6135
+ *
6136
+ * A merged bill is right for one service and wrong for twelve: it hides which
6137
+ * service the money comes from, per-service budgets cannot exist, and the
6138
+ * findings a comparison between services could make are invisible. Files are
6139
+ * assigned to sources by the most specific matching glob from the config’s
6140
+ * `sources` block; a file matching no source is named loudly, because a log
6141
+ * that silently joined no report is spend missing from every bill.
6142
+ *
6143
+ * Lifted out of `commandProfile` unchanged. It was one of several complete
6144
+ * outputs sharing a 2,359-line body with the report they are alternatives to,
6145
+ * and it needs a fraction of what that body had in scope: naming the fraction
6146
+ * is most of the point of moving it.
5861
6147
  */
5862
- async function commandPlan(args, pricing, t) {
5863
- const path = args.positional[0];
5864
- if (path === undefined)
5865
- throw new Error(t.plan.noTarget());
5866
- const GZ = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
5867
- const READABLE = [...LOG_EXTENSIONS, ...GZ];
5868
- const target = await stat(path).catch(() => null);
5869
- let files = [path];
5870
- if (target?.isDirectory()) {
5871
- const entries = await readdir(path, { withFileTypes: true });
5872
- files = entries
5873
- .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
5874
- .map((entry) => join(path, entry.name))
5875
- .sort((a, b) => a.localeCompare(b));
5876
- if (files.length === 0)
5877
- throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
5878
- }
5879
- const texts = await Promise.all(files.map((file) => readUsageLog(file, t)));
5880
- const raw = texts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
5881
- const report = profileUsage(raw, { catalogue: pricing });
5882
- if (report.total.calls === 0)
5883
- throw new Error(t.plan.nothingPriced());
5884
- const levers = billLevers(report, { catalogue: pricing });
5885
- const plan = buildPlan(report, levers, pricing.lastReviewed);
5886
- const minUsd = typeof args.flags.get('min-usd') === 'string' ? numberFlag(args, 'min-usd', 0, t) : 0;
5887
- const actions = plan.actions.filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) >= minUsd);
5888
- const filtered = plan.actions.length - actions.length;
5889
- const droppedUsd = plan.actions
5890
- .filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) < minUsd)
5891
- .reduce((sum, a) => sum + (a.savingUsd ?? a.stakeUsd ?? 0), 0);
6148
+ async function profileBySource(args, config, logFiles, logTexts, pricing, window, t) {
5892
6149
  const n = (value) => value.toLocaleString(t.numberLocale);
5893
- /**
5894
- * The document's totals cover the actions the document holds — a filtered
5895
- * plan whose totals still counted the filtered actions would be a file
5896
- * that contradicts itself, and 1.39's verify would hold it to money it
5897
- * cannot see. What --min-usd dropped is stated with its worth, never
5898
- * silently.
5899
- */
5900
- const stamped = {
5901
- ...plan,
5902
- actions,
5903
- projectedSavingUsd: actions.reduce((sum, a) => sum + (a.savingUsd ?? 0), 0),
5904
- measuredStakeUsd: actions.reduce((sum, a) => sum + (a.stakeUsd ?? 0), 0),
5905
- createdAt: new Date().toISOString(),
5906
- };
5907
- const outPath = stringFlag(args, 'out');
5908
- if (outPath !== undefined) {
5909
- await writeFile(outPath, `${JSON.stringify(stamped, null, 2)}\n`);
6150
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6151
+ const { onlyLabel, sinceMs, untilMs } = window;
6152
+ /* The same join the caller makes, from the same texts: one log, all files. */
6153
+ const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
6154
+ const sourceDefs = config.sources;
6155
+ if (sourceDefs === undefined || Object.keys(sourceDefs).length === 0) {
6156
+ throw new Error(t.profile.bySourceNeedsConfig());
6157
+ }
6158
+ const { bySource, unmatched } = assignSources(logFiles, sourceDefs);
6159
+ if (bySource.size === 0) {
6160
+ throw new Error(t.profile.bySourceNothingMatched(Object.keys(sourceDefs).join(', ')));
6161
+ }
6162
+ const textByFile = new Map(logFiles.map((file, i) => [file, logTexts[i]]));
6163
+ const fleetSources = [];
6164
+ const cacheDeltas = new Map();
6165
+ for (const [name, files] of [...bySource.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
6166
+ const text = files
6167
+ .map((file) => textByFile.get(file))
6168
+ .map((chunk) => (chunk.endsWith('\n') ? chunk : `${chunk}\n`))
6169
+ .join('');
6170
+ const sourceReport = profileUsage(text, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
6171
+ fleetSources.push({ name, report: sourceReport });
6172
+ cacheDeltas.set(name, cacheEconomics(sourceReport.total).deltaUsd);
6173
+ }
6174
+ const aggregate = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
6175
+ const rollup = fleetRollup(fleetSources, {
6176
+ cacheDeltas,
6177
+ aggregateCacheDelta: cacheEconomics(aggregate.total).deltaUsd,
6178
+ });
6179
+ if (boolFlag(args, 'json')) {
6180
+ console.log(JSON.stringify({
6181
+ schemaVersion: 1,
6182
+ bySource: fleetSources.map((source) => ({ name: source.name, report: source.report })),
6183
+ rollup: {
6184
+ totalUsd: rollup.totalUsd,
6185
+ calls: rollup.calls,
6186
+ sources: rollup.sources,
6187
+ worst: rollup.worst,
6188
+ mismatchedSpans: rollup.mismatchedSpans,
6189
+ splitBrains: rollup.splitBrains,
6190
+ cacheUnderwater: rollup.cacheUnderwater,
6191
+ unmatchedFiles: unmatched,
6192
+ },
6193
+ }, (key, value) => (value instanceof Map ? undefined : value), 2));
5910
6194
  }
5911
- await writeMarkdown(args, () => {
5912
- const lines = [];
5913
- lines.push(`## ${t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))}`);
5914
- lines.push('');
5915
- lines.push(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)));
5916
- if (plan.span === null) {
5917
- lines.push('');
5918
- lines.push(`_${t.plan.noClock()}_`);
6195
+ else {
6196
+ console.log(sectionHeading(t.profile.fleetHeading(n(rollup.sources.length), formatUsd(rollup.totalUsd), t.profile.calls(rollup.calls))));
6197
+ for (const row of rollup.sources) {
6198
+ const span = row.spanDays === null ? t.profile.fleetNoClock() : t.profile.fleetSpan(row.spanDays.toFixed(1));
6199
+ console.log(` ${t.profile.fleetRow(row.name, formatUsd(row.usd), pct(row.share), t.profile.calls(row.calls), span)}`);
5919
6200
  }
5920
- for (const action of actions) {
5921
- const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
5922
- const money = action.savingUsd !== null
5923
- ? t.plan.projected(formatUsd(action.savingUsd))
5924
- : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
5925
- lines.push('');
5926
- lines.push(`### ${t.plan.action(action.kind, name, action.model)} — ${money}`);
5927
- if (action.detail.routeTo !== undefined)
5928
- lines.push(`- ${t.plan.routeTo(action.detail.routeTo.displayName)}`);
5929
- for (const assumption of action.assumes)
5930
- lines.push(`- ${t.plan.assume(assumption)}`);
5931
- if (action.check !== null)
5932
- lines.push(`- ${t.plan.check(action.check)}`);
6201
+ if (rollup.worst !== null && rollup.sources.length > 1) {
6202
+ console.log();
6203
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.fleetWorst(rollup.worst.name, formatUsd(rollup.worst.usd), pct(rollup.worst.share)), 74, ' '))}`);
5933
6204
  }
5934
- if (filtered > 0) {
5935
- lines.push('');
5936
- lines.push(`_${t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd))}_`);
6205
+ if (rollup.mismatchedSpans) {
6206
+ console.log(` ${c.dim(wrap(t.profile.fleetMismatchedSpans(), 74, ' '))}`);
6207
+ }
6208
+ for (const split of rollup.splitBrains.slice(0, 3)) {
6209
+ console.log();
6210
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetSplitBrain(split.label, split.sources.map((v) => `${v.name} → ${v.model} (${formatUsd(v.usd)})`).join(', ')), 74, ' ')}`);
6211
+ }
6212
+ for (const under of rollup.cacheUnderwater.slice(0, 3)) {
6213
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetCacheUnderwater(under.name, formatUsd(under.deltaUsd)), 74, ' ')}`);
6214
+ }
6215
+ for (const file of unmatched) {
6216
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetUnmatched(file), 74, ' ')}`);
5937
6217
  }
5938
- lines.push('');
5939
- lines.push(`_${t.plan.footer()}_`);
5940
- return lines.join('\n');
5941
- });
5942
- if (boolFlag(args, 'json')) {
5943
- console.log(JSON.stringify(stamped, null, 2));
5944
- return;
5945
- }
5946
- console.log(sectionHeading(t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))));
5947
- console.log(` ${wrap(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)), 74, ' ')}`);
5948
- if (plan.span === null) {
5949
- console.log(` ${c.dim(wrap(t.plan.noClock(), 74, ' '))}`);
5950
- }
5951
- for (const action of actions) {
5952
- const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
5953
- const money = action.savingUsd !== null
5954
- ? t.plan.projected(formatUsd(action.savingUsd))
5955
- : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
5956
6218
  console.log();
5957
- console.log(` ${c.green('→')} ${c.bold(t.plan.action(action.kind, name, action.model))} ${money}`);
5958
- if (action.detail.routeTo !== undefined) {
5959
- console.log(` ${c.dim(t.plan.routeTo(action.detail.routeTo.displayName))}`);
6219
+ console.log(` ${c.dim(wrap(t.profile.fleetFooter(), 74, ' '))}`);
6220
+ }
6221
+ /**
6222
+ * The per-source gates. Each budget judges its own service and the run
6223
+ * fails naming the service — a total that hides which source crossed its
6224
+ * line is the rendering this mode exists to end. Waivable per source
6225
+ * through `bySource:<name>`, under the same expiry discipline.
6226
+ */
6227
+ const bySourceBudgets = config.spend?.bySource ?? {};
6228
+ for (const [name, limit] of Object.entries(bySourceBudgets)) {
6229
+ const found = fleetSources.find((source) => source.name === name);
6230
+ if (found === undefined) {
6231
+ console.error(c.dim(t.profile.fleetBudgetMissing(name)));
6232
+ continue;
5960
6233
  }
5961
- for (const assumption of action.assumes) {
5962
- console.log(` ${c.yellow('?')} ${c.dim(wrap(t.plan.assume(assumption), 72, ' '))}`);
6234
+ const usd = found.report.total.totalUsd;
6235
+ if (usd > limit) {
6236
+ console.error(c.red(t.profile.fleetBudgetFailed(name, formatUsd(usd), formatUsd(limit))));
6237
+ process.exitCode = 1;
5963
6238
  }
5964
- if (action.check !== null) {
5965
- console.log(` ${c.dim(wrap(t.plan.check(action.check), 72, ' '))}`);
6239
+ else {
6240
+ console.error(c.dim(t.profile.fleetBudgetOk(name, formatUsd(usd), formatUsd(limit))));
5966
6241
  }
5967
6242
  }
5968
- if (filtered > 0) {
5969
- console.log();
5970
- console.log(` ${c.dim(wrap(t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd)), 74, ' '))}`);
6243
+ }
6244
+ /**
6245
+ * `--dry-run`: what this log could and could not answer, and no bill.
6246
+ *
6247
+ * The question somebody has *before* wiring Trazum into CI is not "what did we
6248
+ * spend" but "will this log support the gates I want", and answering it with a
6249
+ * full report makes them read a bill to find out a field is missing. This path
6250
+ * states readiness per capability and produces no dollar figure at all, so
6251
+ * nothing here can be mistaken for spend. It also refuses to coexist with the
6252
+ * gates: a gate over a report that was never produced would exit green having
6253
+ * judged nothing.
6254
+ */
6255
+ function profileDryRun(args, report, t) {
6256
+ const n = (value) => value.toLocaleString(t.numberLocale);
6257
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6258
+ const gateFlags = ['max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd'];
6259
+ if (gateFlags.some((flag) => typeof args.flags.get(flag) === 'string')) {
6260
+ throw new Error(t.profile.dryRunNoGates());
6261
+ }
6262
+ const cov = report.fieldCoverage;
6263
+ const parsed = cov.parsed;
6264
+ console.log(sectionHeading(t.profile.dryRunHeading()));
6265
+ console.log(` ${wrap(t.profile.dryRunParsed(n(parsed), n(report.skippedLines.length)), 74, ' ')}`);
6266
+ if (report.unpricedModels.length > 0) {
6267
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.dryRunUnpriced(report.unpricedModels.join(', ')), 74, ' ')}`);
5971
6268
  }
5972
6269
  console.log();
5973
- console.log(` ${c.dim(wrap(t.plan.footer(), 74, ' '))}`);
5974
- if (outPath !== undefined)
5975
- console.log(c.dim(wrap(t.plan.wrote(outPath), 74, '')));
5976
- }
5977
- async function commandProfile(args, config, configDir, pricing, t) {
5978
- const path = args.positional[0];
5979
- if (path === undefined) {
5980
- console.log();
5981
- console.log(c.dim(wrap(t.profile.noTarget(), 74, ' ')));
5982
- console.log();
5983
- return;
6270
+ const can = (ok, line) => {
6271
+ console.log(` ${ok ? c.green('✓') : c.yellow('✗')} ${wrap(line, 74, ' ')}`);
6272
+ };
6273
+ const share = (count) => (parsed > 0 ? pct(count / parsed) : '0%');
6274
+ can(parsed > 0, t.profile.dryRunTotals());
6275
+ can(cov.label > 0, t.profile.dryRunLabels(share(cov.label)));
6276
+ can(cov.ts > 0, t.profile.dryRunClock(share(cov.ts)));
6277
+ can(cov.session > 0, t.profile.dryRunSessions(share(cov.session)));
6278
+ can(cov.outcome > 0, t.profile.dryRunOutcomes(share(cov.outcome)));
6279
+ can(cov.stopReason > 0, t.profile.dryRunStopReason(share(cov.stopReason)));
6280
+ // "No cache traffic" is not a missing field: the split can only exist on
6281
+ // records that wrote, and a log that never wrote has nothing to record.
6282
+ if (cov.cacheWrites > 0) {
6283
+ can(cov.cacheTtl > 0, t.profile.dryRunCacheTtl(n(cov.cacheTtl), n(cov.cacheWrites)));
5984
6284
  }
5985
- /**
5986
- * A log, or a directory of them.
5987
- *
5988
- * Usage logs rotate: `logs/2026-08-01.jsonl`, `logs/2026-08-02.jsonl`, one
5989
- * per day for a month. Making somebody `cat` them together before a profile
5990
- * will read them is a setup cost that gets a tool skipped, and doing it for
5991
- * them is a directory listing.
5992
- *
5993
- * Files are read in name order — which for dated names is time order — and
5994
- * how many were read is stated, because a report over "the logs" that
5995
- * silently skipped one is a total that is wrong by an unknown amount. A
5996
- * directory holding nothing readable is an error naming what it looked for,
5997
- * not an empty report.
5998
- */
5999
- /**
6000
- * The same names, gzipped — which is what a rotated log actually looks like
6001
- * a day after it rotates.
6002
- *
6003
- * `logrotate`, Docker's json-file driver and every cloud log export compress
6004
- * yesterday's file, so a directory of a month's logs is one plain file and
6005
- * twenty-nine `.gz` ones. Reading only the plain one and saying nothing
6006
- * would report a month's bill from a day of it, in the flattering
6007
- * direction, which is exactly the failure directory mode was added to
6008
- * prevent.
6009
- */
6010
- const GZ_EXTENSIONS = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
6011
- const READABLE = [...LOG_EXTENSIONS, ...GZ_EXTENSIONS];
6012
- const target = await stat(path).catch(() => null);
6013
- let logFiles = [path];
6014
- if (target?.isDirectory()) {
6015
- /**
6016
- * Recursive under `--by-source`, flat otherwise. The fleet's whole point
6017
- * is one directory per service, so the walk must descend; the flat mode
6018
- * keeps its long-standing behaviour because a directory of rotated logs
6019
- * with an unrelated subfolder should not quietly absorb it.
6020
- */
6021
- const bySourceMode = boolFlag(args, 'by-source');
6022
- const entries = await readdir(path, { withFileTypes: true, recursive: bySourceMode });
6023
- logFiles = entries
6024
- .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
6025
- .map((entry) => join(entry.parentPath ?? path, entry.name))
6026
- .sort((a, b) => a.localeCompare(b));
6027
- if (logFiles.length === 0) {
6028
- throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
6029
- }
6285
+ else {
6286
+ console.log(` ${c.dim('·')} ${wrap(t.profile.dryRunNoCacheTraffic(), 74, ' ')}`);
6030
6287
  }
6288
+ console.log();
6289
+ console.log(` ${c.dim(wrap(t.profile.dryRunFooter(), 74, ' '))}`);
6290
+ if (parsed === 0)
6291
+ process.exitCode = 1;
6292
+ }
6293
+ /**
6294
+ * The money gates: run them, and say what they said.
6295
+ *
6296
+ * `check` gates tokens before the money is spent; these gate the spend itself,
6297
+ * from the provider’s own billed counts. No period is assumed — the budget
6298
+ * applies to exactly the log handed in, so a nightly job that profiles
6299
+ * yesterday’s log has a daily budget without Trazum ever guessing what a day is.
6300
+ *
6301
+ * ## Why this is one function and not five
6302
+ *
6303
+ * `waiverFor`, `waived`, the uses it collects, the verdict capture and the
6304
+ * flush to the waiver log were five closures inside `commandProfile`, sharing
6305
+ * its 2,359-line scope with the report they have nothing to do with. They are
6306
+ * one concern — policy — and the only two things the rest of the command needs
6307
+ * from them are whether a gate failed and what the gates said.
6308
+ *
6309
+ * ## Why it returns rather than assigns
6310
+ *
6311
+ * `gateFailed` and `gateVerdicts` were `let` and `const` in the enclosing
6312
+ * scope, written here and read three hundred lines away by the side-file
6313
+ * writer. That is an output channel nothing declares. They are the return
6314
+ * value now, and `failed` is still read off `process.exitCode` exactly as it
6315
+ * was — the gates set the exit code, and this reports what they set.
6316
+ */
6317
+ async function runProfileGates(context) {
6318
+ const { args, config, configDir, report, previous, againstDelta, windowed, now, pricing, t } = context;
6319
+ const n = (value) => value.toLocaleString(t.numberLocale);
6320
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6321
+ /*
6322
+ What a failing gate points at. The enclosing command computes this too, a
6323
+ few hundred lines further down, and the gate block used to reach forward
6324
+ into that declaration — legal only because the closure that read it was
6325
+ called later. `billLevers` is pure, so the honest fix is to ask for it here.
6326
+ */
6327
+ const levers = billLevers(report, { catalogue: pricing });
6031
6328
  /**
6032
- * Gzipped files are decompressed in memory; everything else is read as text.
6033
- *
6034
- * Decided by **extension**, not by sniffing the first two bytes: a file
6035
- * named `.jsonl` whose contents happen to start with 0x1f8b is far more
6036
- * likely to be a corrupt log than a mislabelled archive, and silently
6037
- * treating it as one would turn a diagnosable error into an empty report.
6329
+ * The money gates, armed by flags and applied on every output path.
6038
6330
  *
6039
- * A `.gz` that will not decompress is an error naming the file. The
6040
- * alternative — skipping it — is a total quietly missing a day, which is
6041
- * the failure this repository refuses in every other place it can occur.
6331
+ * `check` gates tokens before the money is spent; these gate the spend
6332
+ * itself, from the provider's own billed counts. No period is assumed —
6333
+ * the budget applies to exactly the log handed in, so a nightly job that
6334
+ * profiles yesterday's log has a daily budget without Trazum ever
6335
+ * guessing what a day is.
6042
6336
  */
6043
- const logTexts = await Promise.all(logFiles.map((file) => readUsageLog(file, t)));
6044
- // A file that does not end in a newline would otherwise glue its last record
6045
- // to the next file's first one, and both would be reported as unreadable.
6046
- const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
6047
6337
  /**
6048
- * The drill-down. A label that matches nothing is an error naming the labels
6049
- * that exist — the route command's rule, for the route command's reason: a
6050
- * report over zero calls silently filtered would read as "this workload is
6051
- * free".
6338
+ * The gate verdicts, kept so the markdown summary can carry them.
6339
+ *
6340
+ * Collected by wrapping `console.error` for the duration of `applyGates`
6341
+ * rather than by threading a return value through every gate. That is the
6342
+ * unusual choice here and it is deliberate: a gate added later reaches the
6343
+ * summary without anyone remembering to register it, and the alternative —
6344
+ * one push per verdict at a dozen call sites — is a list that goes stale
6345
+ * silently. Colour is stripped, because a summary is markdown and an
6346
+ * escape sequence in it is noise a reader has to look past.
6052
6347
  */
6053
- const onlyLabel = stringFlag(args, 'label');
6348
+ const gateVerdicts = [];
6349
+ let gateFailed = false;
6054
6350
  /**
6055
- * The drill-down in time. `--since`/`--until` take a UTC day or a full
6056
- * timestamp; a bare day means the whole of it — since its first instant,
6057
- * until its last — because "--until 2026-08-14" excluding the named day is
6058
- * a trap sprung on everyone who reads dates the way humans do. Internally
6059
- * the window is half-open `[since, until)`, so two adjacent windows share
6060
- * no record.
6351
+ * Findings as policy. A waiver silences one gate's exit code for a bounded
6352
+ * time, on the record: the failure still prints (waived is shown as
6353
+ * waived, never hidden — the bill still counts it), the reason and the
6354
+ * days left print beside it, and the day the waiver expires the gate
6355
+ * fails again louder, naming the date and the reason somebody wrote.
6356
+ * That expiry is the entire mechanism by which a waiver stays a decision
6357
+ * instead of becoming a habit.
6061
6358
  */
6062
- const now = Date.now();
6063
- const sinceWhen = parseWhen(args, 'since', false, t, now);
6064
- const untilWhen = parseWhen(args, 'until', true, t, now);
6065
- const relativeWindow = sinceWhen.relative || untilWhen.relative;
6066
- const sinceMs = sinceWhen.ms;
6067
- const untilMs = untilWhen.ms;
6068
- if (sinceMs !== undefined && untilMs !== undefined && sinceMs >= untilMs) {
6069
- throw new Error(t.profile.sinceAfterUntil());
6070
- }
6071
- const windowed = sinceMs !== undefined || untilMs !== undefined;
6359
+ const waiverFor = (gate) => {
6360
+ const entry = (config.waive ?? []).find((w) => w.gate === gate);
6361
+ if (entry === undefined)
6362
+ return null;
6363
+ // The waiver covers its named day whole: expiry begins the next UTC day.
6364
+ const expiresMs = Date.parse(`${entry.until}T00:00:00Z`) + 86_400_000;
6365
+ return { entry, expired: Date.now() >= expiresMs };
6366
+ };
6072
6367
  /**
6073
- * How old the price table behind every dollar below is. Stated only when it
6074
- * is old enough to matter: `models` and `doctor` always print the date, but
6075
- * a profile is read for its figures, and the one fact that silently
6076
- * invalidates all of them is a table the provider has re-priced since.
6077
- * The threshold is in the sentence, not hidden here.
6368
+ * Applies a waiver to one failing gate. Returns true when the failure is
6369
+ * silenced — the caller skips its exitCode — and prints the record either
6370
+ * way, because a waived failure that vanished from the output would be a
6371
+ * finding deleted with extra steps.
6078
6372
  */
6079
- const STALE_PRICING_DAYS = 45;
6080
- const pricingAgeDays = reviewAgeDays(pricing.lastReviewed, new Date());
6081
- const pricingStale = pricingAgeDays !== null && pricingAgeDays > STALE_PRICING_DAYS
6082
- ? { date: pricing.lastReviewed, days: pricingAgeDays }
6083
- : null;
6084
- const report = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
6085
- if (report.total.calls === 0 && report.unpriced.calls === 0) {
6086
- if (onlyLabel !== undefined || windowed) {
6087
- // Diagnose against the log without the failed filter, so the error can
6088
- // name what does exist instead of describing an absence.
6089
- const unfiltered = profileUsage(raw, { catalogue: pricing });
6090
- if (unfiltered.total.calls > 0 || unfiltered.unpriced.calls > 0) {
6091
- if (onlyLabel !== undefined && !unfiltered.byLabel.some((r) => r.label === onlyLabel)) {
6092
- const available = unfiltered.byLabel
6093
- .map((r) => (r.label === UNLABELLED ? t.profile.unlabelled() : r.label))
6094
- .join(', ');
6095
- throw new Error(t.route.labelNotFound(onlyLabel, available || '—'));
6096
- }
6097
- if (windowed) {
6098
- /**
6099
- * A window that matches nothing must not become a $0 report — under
6100
- * `--max-usd` it would pass a budget gate over a period the log
6101
- * simply does not cover, which is the flattering non-answer. The
6102
- * error names what the log *does* cover, or says it has no clock at
6103
- * all, so the fix is visible in the message.
6104
- */
6105
- if (unfiltered.span === null)
6106
- throw new Error(t.profile.windowNeedsClock());
6107
- throw new Error(`${t.profile.windowMatchesNothing(dayOf(unfiltered.span.fromMs), dayOf(unfiltered.span.toMs))}${relativeWindow ? ` ${t.profile.windowRelativeEmpty()}` : ''}`);
6108
- }
6109
- }
6110
- }
6111
- }
6112
- const n = (value) => value.toLocaleString(t.numberLocale);
6113
- const pct = (share) => `${(share * 100).toFixed(1)}%`;
6114
6373
  /**
6115
- * `--by-source`: one report per service, plus the rollup — the fleet.
6374
+ * Uses recorded this run, flushed after the gates have finished.
6116
6375
  *
6117
- * A merged bill is right for one service and wrong for twelve: it hides
6118
- * which service the money comes from, per-service budgets cannot exist,
6119
- * and the findings a comparison between services could make are invisible.
6120
- * Files are assigned to sources by the most specific matching glob from the
6121
- * config's `sources` block; a file matching no source is named loudly,
6122
- * because a log that silently joined no report is spend missing from every
6123
- * bill.
6376
+ * Collected rather than written inline because `waived` is synchronous and
6377
+ * called from seven places inside the gate pass. Writing from each of them
6378
+ * would mean seven awaits threaded through the exit-code logic — the one
6379
+ * part of this command where a mistake turns a red build green.
6124
6380
  */
6125
- if (boolFlag(args, 'by-source')) {
6126
- const sourceDefs = config.sources;
6127
- if (sourceDefs === undefined || Object.keys(sourceDefs).length === 0) {
6128
- throw new Error(t.profile.bySourceNeedsConfig());
6129
- }
6130
- const { bySource, unmatched } = assignSources(logFiles, sourceDefs);
6131
- if (bySource.size === 0) {
6132
- throw new Error(t.profile.bySourceNothingMatched(Object.keys(sourceDefs).join(', ')));
6133
- }
6134
- const textByFile = new Map(logFiles.map((file, i) => [file, logTexts[i]]));
6135
- const fleetSources = [];
6136
- const cacheDeltas = new Map();
6137
- for (const [name, files] of [...bySource.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
6138
- const text = files
6139
- .map((file) => textByFile.get(file))
6140
- .map((chunk) => (chunk.endsWith('\n') ? chunk : `${chunk}\n`))
6141
- .join('');
6142
- const sourceReport = profileUsage(text, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
6143
- fleetSources.push({ name, report: sourceReport });
6144
- cacheDeltas.set(name, cacheEconomics(sourceReport.total).deltaUsd);
6145
- }
6146
- const aggregate = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
6147
- const rollup = fleetRollup(fleetSources, {
6148
- cacheDeltas,
6149
- aggregateCacheDelta: cacheEconomics(aggregate.total).deltaUsd,
6150
- });
6151
- if (boolFlag(args, 'json')) {
6152
- console.log(JSON.stringify({
6153
- schemaVersion: 1,
6154
- bySource: fleetSources.map((source) => ({ name: source.name, report: source.report })),
6155
- rollup: {
6156
- totalUsd: rollup.totalUsd,
6157
- calls: rollup.calls,
6158
- sources: rollup.sources,
6159
- worst: rollup.worst,
6160
- mismatchedSpans: rollup.mismatchedSpans,
6161
- splitBrains: rollup.splitBrains,
6162
- cacheUnderwater: rollup.cacheUnderwater,
6163
- unmatchedFiles: unmatched,
6164
- },
6165
- }, (key, value) => (value instanceof Map ? undefined : value), 2));
6166
- }
6167
- else {
6168
- console.log(sectionHeading(t.profile.fleetHeading(n(rollup.sources.length), formatUsd(rollup.totalUsd), t.profile.calls(rollup.calls))));
6169
- for (const row of rollup.sources) {
6170
- const span = row.spanDays === null ? t.profile.fleetNoClock() : t.profile.fleetSpan(row.spanDays.toFixed(1));
6171
- console.log(` ${t.profile.fleetRow(row.name, formatUsd(row.usd), pct(row.share), t.profile.calls(row.calls), span)}`);
6172
- }
6173
- if (rollup.worst !== null && rollup.sources.length > 1) {
6174
- console.log();
6175
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.fleetWorst(rollup.worst.name, formatUsd(rollup.worst.usd), pct(rollup.worst.share)), 74, ' '))}`);
6176
- }
6177
- if (rollup.mismatchedSpans) {
6178
- console.log(` ${c.dim(wrap(t.profile.fleetMismatchedSpans(), 74, ' '))}`);
6179
- }
6180
- for (const split of rollup.splitBrains.slice(0, 3)) {
6181
- console.log();
6182
- console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetSplitBrain(split.label, split.sources.map((v) => `${v.name} → ${v.model} (${formatUsd(v.usd)})`).join(', ')), 74, ' ')}`);
6183
- }
6184
- for (const under of rollup.cacheUnderwater.slice(0, 3)) {
6185
- console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetCacheUnderwater(under.name, formatUsd(under.deltaUsd)), 74, ' ')}`);
6186
- }
6187
- for (const file of unmatched) {
6188
- console.log(` ${c.yellow('!')} ${wrap(t.profile.fleetUnmatched(file), 74, ' ')}`);
6189
- }
6190
- console.log();
6191
- console.log(` ${c.dim(wrap(t.profile.fleetFooter(), 74, ' '))}`);
6381
+ const waiverUses = [];
6382
+ const waived = (gate, measuredUsd = null, limitUsd = null) => {
6383
+ const found = waiverFor(gate);
6384
+ if (found === null)
6385
+ return false;
6386
+ if (found.expired) {
6387
+ console.error(c.red(t.profile.waiveExpired(gate, found.entry.until, found.entry.reason)));
6388
+ return false;
6192
6389
  }
6390
+ const daysLeft = Math.max(0, Math.ceil((Date.parse(`${found.entry.until}T00:00:00Z`) + 86_400_000 - Date.now()) / 86_400_000));
6391
+ console.error(c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))));
6193
6392
  /**
6194
- * The per-source gates. Each budget judges its own service and the run
6195
- * fails naming the service — a total that hides which source crossed its
6196
- * line is the rendering this mode exists to end. Waivable per source
6197
- * through `bySource:<name>`, under the same expiry discipline.
6393
+ * Recorded **when it silences something**, never when it is configured.
6394
+ *
6395
+ * A waiver nobody's build has ever hit is not a habit — it is dead config
6396
+ * — and the history reports the two apart. This is also the only honest
6397
+ * way to build the record 1.40 refused to invent: it starts today and
6398
+ * says so, rather than reconstructing a past from the present.
6399
+ *
6400
+ * The reason and the expiry are taken from the config **as it stands at
6401
+ * this moment**, because that is the decision that was actually in force.
6402
+ * Reading today's reason back onto last quarter's use is the same mistake
6403
+ * one layer down.
6198
6404
  */
6199
- const bySourceBudgets = config.spend?.bySource ?? {};
6200
- for (const [name, limit] of Object.entries(bySourceBudgets)) {
6201
- const found = fleetSources.find((source) => source.name === name);
6202
- if (found === undefined) {
6203
- console.error(c.dim(t.profile.fleetBudgetMissing(name)));
6204
- continue;
6205
- }
6206
- const usd = found.report.total.totalUsd;
6207
- if (usd > limit) {
6208
- console.error(c.red(t.profile.fleetBudgetFailed(name, formatUsd(usd), formatUsd(limit))));
6209
- process.exitCode = 1;
6405
+ waiverUses.push({
6406
+ schemaVersion: 1,
6407
+ day: waiverDay(new Date()),
6408
+ gate,
6409
+ reason: found.entry.reason,
6410
+ until: found.entry.until,
6411
+ commit: process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? null,
6412
+ measuredUsd,
6413
+ limitUsd,
6414
+ });
6415
+ return true;
6416
+ };
6417
+ const applyGates = () => {
6418
+ /**
6419
+ * Before any verdict: whether the gated figure is the whole bill. A gate
6420
+ * can only judge the money it can see, and three things hide money from
6421
+ * it — unreadable lines, unpriced models, and clockless calls left
6422
+ * outside a window. Passing on a floor is acceptable; passing on a floor
6423
+ * *silently* is the flattering omission this repository refuses, because
6424
+ * an over-budget bill with three corrupt lines would read as green.
6425
+ */
6426
+ const anyGate = typeof args.flags.get('max-usd') === 'string' ||
6427
+ typeof args.flags.get('max-growth-usd') === 'string' ||
6428
+ typeof args.flags.get('max-cache-loss-usd') === 'string' ||
6429
+ typeof args.flags.get('max-day-usd') === 'string' ||
6430
+ typeof args.flags.get('max-session-usd') === 'string' ||
6431
+ config.spend !== undefined;
6432
+ if (anyGate) {
6433
+ const reasons = [];
6434
+ if (report.skippedLines.length > 0)
6435
+ reasons.push(t.profile.floorSkipped(report.skippedLines.length));
6436
+ if (report.unpriced.calls > 0)
6437
+ reasons.push(t.profile.floorUnpriced(report.unpriced.calls));
6438
+ if (report.timeWindow !== null && report.timeWindow.undatedExcluded > 0) {
6439
+ reasons.push(t.profile.floorUndated(report.timeWindow.undatedExcluded));
6210
6440
  }
6211
- else {
6212
- console.error(c.dim(t.profile.fleetBudgetOk(name, formatUsd(usd), formatUsd(limit))));
6213
- }
6214
- }
6215
- return;
6216
- }
6217
- /**
6218
- * `--dry-run`: what this log could and could not answer, and no bill.
6219
- *
6220
- * The question somebody has *before* wiring Trazum into CI is not "what did
6221
- * we spend" but "will this log support the gates I want" — and answering it
6222
- * with a full report makes them read a bill to find out a field is missing.
6223
- * This path states readiness per capability and produces no dollar figure
6224
- * at all, so nothing here can be mistaken for spend. It also refuses to
6225
- * coexist with the gates: a gate over a report that was never produced
6226
- * would exit green having judged nothing.
6227
- */
6228
- if (boolFlag(args, 'dry-run')) {
6229
- const gateFlags = ['max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd'];
6230
- if (gateFlags.some((flag) => typeof args.flags.get(flag) === 'string')) {
6231
- throw new Error(t.profile.dryRunNoGates());
6232
- }
6233
- const cov = report.fieldCoverage;
6234
- const parsed = cov.parsed;
6235
- console.log(sectionHeading(t.profile.dryRunHeading()));
6236
- console.log(` ${wrap(t.profile.dryRunParsed(n(parsed), n(report.skippedLines.length)), 74, ' ')}`);
6237
- if (report.unpricedModels.length > 0) {
6238
- console.log(` ${c.yellow('!')} ${wrap(t.profile.dryRunUnpriced(report.unpricedModels.join(', ')), 74, ' ')}`);
6239
- }
6240
- console.log();
6241
- const can = (ok, line) => {
6242
- console.log(` ${ok ? c.green('✓') : c.yellow('✗')} ${wrap(line, 74, ' ')}`);
6243
- };
6244
- const share = (count) => (parsed > 0 ? pct(count / parsed) : '0%');
6245
- can(parsed > 0, t.profile.dryRunTotals());
6246
- can(cov.label > 0, t.profile.dryRunLabels(share(cov.label)));
6247
- can(cov.ts > 0, t.profile.dryRunClock(share(cov.ts)));
6248
- can(cov.session > 0, t.profile.dryRunSessions(share(cov.session)));
6249
- can(cov.outcome > 0, t.profile.dryRunOutcomes(share(cov.outcome)));
6250
- can(cov.stopReason > 0, t.profile.dryRunStopReason(share(cov.stopReason)));
6251
- // "No cache traffic" is not a missing field: the split can only exist on
6252
- // records that wrote, and a log that never wrote has nothing to record.
6253
- if (cov.cacheWrites > 0) {
6254
- can(cov.cacheTtl > 0, t.profile.dryRunCacheTtl(n(cov.cacheTtl), n(cov.cacheWrites)));
6255
- }
6256
- else {
6257
- console.log(` ${c.dim('·')} ${wrap(t.profile.dryRunNoCacheTraffic(), 74, ' ')}`);
6258
- }
6259
- console.log();
6260
- console.log(` ${c.dim(wrap(t.profile.dryRunFooter(), 74, ' '))}`);
6261
- if (parsed === 0)
6262
- process.exitCode = 1;
6263
- return;
6264
- }
6265
- /**
6266
- * The previous log, loaded before the output paths split so the growth gate
6267
- * exists under `--json` too — a CI step reads the JSON and trusts the exit
6268
- * code, and a gate that only arms in the human rendering is a gate CI never
6269
- * had.
6270
- */
6271
- const againstPath = stringFlag(args, 'against');
6272
- // The same filter on both sides: comparing one workload's bill against the
6273
- // whole previous log would report every sibling workload as vanished savings.
6274
- const previous = againstPath !== undefined
6275
- // The same reader as the log itself, so `--against last-month.jsonl.gz`
6276
- // works: a comparison that could only read one of the two formats would
6277
- // be a flag that fails on exactly the rotated file it exists to read.
6278
- ? profileUsage(await readUsageLog(againstPath, t), {
6279
- catalogue: pricing,
6280
- label: onlyLabel,
6281
- // The same window on both sides, for the same reason as the label:
6282
- // a windowed bill against an unwindowed one compares a slice to a
6283
- // whole and calls the difference growth.
6284
- sinceMs,
6285
- untilMs,
6286
- })
6287
- : null;
6288
- const againstDelta = previous !== null && previous.total.calls > 0
6289
- ? report.total.totalUsd - previous.total.totalUsd
6290
- : null;
6291
- /**
6292
- * The same tokens at another model's rates, computed before the output paths
6293
- * split so `--json` carries it too.
6294
- *
6295
- * An unknown id **throws** rather than printing nothing. A flag that silently
6296
- * does nothing is worse than a missing feature: the reader typed a question,
6297
- * got a report with no answer in it, and has no way to tell a typo from a
6298
- * model this comparison had nothing to say about.
6299
- */
6300
- /**
6301
- * The largest call against each model's window, computed once here so the
6302
- * terminal, the JSON and the markdown state the same ratio — the
6303
- * denominator lives in the (possibly overlaid) catalogue.
6304
- */
6305
- const pressures = contextPressure(report, pricing);
6306
- const whatIfModel = stringFlag(args, 'what-if');
6307
- const whatIf = whatIfModel !== undefined ? repriceProfile(report, whatIfModel, pricing) : null;
6308
- if (whatIfModel !== undefined && whatIf === null) {
6309
- throw new Error(t.profile.whatIfUnknown(whatIfModel, pricing.models.map((m) => m.id).join(', ')));
6310
- }
6311
- /**
6312
- * The drivers of the change, per label and per model, computed once here so
6313
- * the terminal, the JSON and any future rendering describe the same change.
6314
- * The model half answers the question the label half cannot: "the growth is
6315
- * traffic moving from Haiku to Opus" is a fact about the mix, invisible in
6316
- * per-workload rows whose names did not change.
6317
- */
6318
- const labelDrivers = previous !== null && previous.total.calls > 0
6319
- ? driversBetween(previous.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })), report.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })))
6320
- : [];
6321
- const modelDrivers = previous !== null && previous.total.calls > 0
6322
- ? driversBetween(previous.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })), report.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })))
6323
- : [];
6324
- /**
6325
- * Whether the two logs share any time at all. This comparison is meant for
6326
- * disjoint periods or snapshots of different systems; when both spans are
6327
- * known and intersect, the same calls may sit on both sides of the
6328
- * subtraction and the "growth" is partly the same money counted twice.
6329
- * Only decidable when both logs carry a clock — three states, as always:
6330
- * warned, clear, or unknown, and unknown stays silent rather than clear.
6331
- */
6332
- const againstOverlap = previous !== null &&
6333
- previous.total.calls > 0 &&
6334
- previous.span !== null &&
6335
- report.span !== null &&
6336
- Math.min(report.span.toMs, previous.span.toMs) >=
6337
- Math.max(report.span.fromMs, previous.span.fromMs)
6338
- ? {
6339
- fromMs: Math.max(report.span.fromMs, previous.span.fromMs),
6340
- toMs: Math.min(report.span.toMs, previous.span.toMs),
6341
- }
6342
- : null;
6343
- // A gate flag that silently does nothing is not an answer — same rule as
6344
- // --apply-suggestions without --suggest.
6345
- if (typeof args.flags.get('max-growth-usd') === 'string' && againstPath === undefined) {
6346
- throw new Error(t.profile.maxGrowthNeedsAgainst());
6347
- }
6348
- /**
6349
- * The money gates, armed by flags and applied on every output path.
6350
- *
6351
- * `check` gates tokens before the money is spent; these gate the spend
6352
- * itself, from the provider's own billed counts. No period is assumed —
6353
- * the budget applies to exactly the log handed in, so a nightly job that
6354
- * profiles yesterday's log has a daily budget without Trazum ever
6355
- * guessing what a day is.
6356
- */
6357
- /**
6358
- * The gate verdicts, kept so the markdown summary can carry them.
6359
- *
6360
- * Collected by wrapping `console.error` for the duration of `applyGates`
6361
- * rather than by threading a return value through every gate. That is the
6362
- * unusual choice here and it is deliberate: a gate added later reaches the
6363
- * summary without anyone remembering to register it, and the alternative —
6364
- * one push per verdict at a dozen call sites — is a list that goes stale
6365
- * silently. Colour is stripped, because a summary is markdown and an
6366
- * escape sequence in it is noise a reader has to look past.
6367
- */
6368
- const gateVerdicts = [];
6369
- let gateFailed = false;
6370
- /**
6371
- * Findings as policy. A waiver silences one gate's exit code for a bounded
6372
- * time, on the record: the failure still prints (waived is shown as
6373
- * waived, never hidden — the bill still counts it), the reason and the
6374
- * days left print beside it, and the day the waiver expires the gate
6375
- * fails again louder, naming the date and the reason somebody wrote.
6376
- * That expiry is the entire mechanism by which a waiver stays a decision
6377
- * instead of becoming a habit.
6378
- */
6379
- const waiverFor = (gate) => {
6380
- const entry = (config.waive ?? []).find((w) => w.gate === gate);
6381
- if (entry === undefined)
6382
- return null;
6383
- // The waiver covers its named day whole: expiry begins the next UTC day.
6384
- const expiresMs = Date.parse(`${entry.until}T00:00:00Z`) + 86_400_000;
6385
- return { entry, expired: Date.now() >= expiresMs };
6386
- };
6387
- /**
6388
- * Applies a waiver to one failing gate. Returns true when the failure is
6389
- * silenced — the caller skips its exitCode — and prints the record either
6390
- * way, because a waived failure that vanished from the output would be a
6391
- * finding deleted with extra steps.
6392
- */
6393
- /**
6394
- * Uses recorded this run, flushed after the gates have finished.
6395
- *
6396
- * Collected rather than written inline because `waived` is synchronous and
6397
- * called from seven places inside the gate pass. Writing from each of them
6398
- * would mean seven awaits threaded through the exit-code logic — the one
6399
- * part of this command where a mistake turns a red build green.
6400
- */
6401
- const waiverUses = [];
6402
- const waived = (gate, measuredUsd = null, limitUsd = null) => {
6403
- const found = waiverFor(gate);
6404
- if (found === null)
6405
- return false;
6406
- if (found.expired) {
6407
- console.error(c.red(t.profile.waiveExpired(gate, found.entry.until, found.entry.reason)));
6408
- return false;
6409
- }
6410
- const daysLeft = Math.max(0, Math.ceil((Date.parse(`${found.entry.until}T00:00:00Z`) + 86_400_000 - Date.now()) / 86_400_000));
6411
- console.error(c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))));
6412
- /**
6413
- * Recorded **when it silences something**, never when it is configured.
6414
- *
6415
- * A waiver nobody's build has ever hit is not a habit — it is dead config
6416
- * — and the history reports the two apart. This is also the only honest
6417
- * way to build the record 1.40 refused to invent: it starts today and
6418
- * says so, rather than reconstructing a past from the present.
6419
- *
6420
- * The reason and the expiry are taken from the config **as it stands at
6421
- * this moment**, because that is the decision that was actually in force.
6422
- * Reading today's reason back onto last quarter's use is the same mistake
6423
- * one layer down.
6424
- */
6425
- waiverUses.push({
6426
- schemaVersion: 1,
6427
- day: waiverDay(new Date()),
6428
- gate,
6429
- reason: found.entry.reason,
6430
- until: found.entry.until,
6431
- commit: process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? null,
6432
- measuredUsd,
6433
- limitUsd,
6434
- });
6435
- return true;
6436
- };
6437
- const applyGates = () => {
6438
- /**
6439
- * Before any verdict: whether the gated figure is the whole bill. A gate
6440
- * can only judge the money it can see, and three things hide money from
6441
- * it — unreadable lines, unpriced models, and clockless calls left
6442
- * outside a window. Passing on a floor is acceptable; passing on a floor
6443
- * *silently* is the flattering omission this repository refuses, because
6444
- * an over-budget bill with three corrupt lines would read as green.
6445
- */
6446
- const anyGate = typeof args.flags.get('max-usd') === 'string' ||
6447
- typeof args.flags.get('max-growth-usd') === 'string' ||
6448
- typeof args.flags.get('max-cache-loss-usd') === 'string' ||
6449
- typeof args.flags.get('max-day-usd') === 'string' ||
6450
- typeof args.flags.get('max-session-usd') === 'string' ||
6451
- config.spend !== undefined;
6452
- if (anyGate) {
6453
- const reasons = [];
6454
- if (report.skippedLines.length > 0)
6455
- reasons.push(t.profile.floorSkipped(report.skippedLines.length));
6456
- if (report.unpriced.calls > 0)
6457
- reasons.push(t.profile.floorUnpriced(report.unpriced.calls));
6458
- if (report.timeWindow !== null && report.timeWindow.undatedExcluded > 0) {
6459
- reasons.push(t.profile.floorUndated(report.timeWindow.undatedExcluded));
6460
- }
6461
- if (reasons.length > 0) {
6462
- console.error(c.yellow(t.profile.gateOnFloor(reasons.join('; '))));
6441
+ if (reasons.length > 0) {
6442
+ console.error(c.yellow(t.profile.gateOnFloor(reasons.join('; '))));
6463
6443
  }
6464
6444
  }
6465
6445
  /**
@@ -6741,461 +6721,908 @@ async function commandProfile(args, config, configDir, pricing, t) {
6741
6721
  }
6742
6722
  }
6743
6723
  };
6724
+ recordGates();
6725
+ await recordWaiverUses();
6726
+ return { failed: gateFailed, verdicts: gateVerdicts };
6727
+ }
6728
+ /**
6729
+ * The side files the caller asked for.
6730
+ *
6731
+ * Written on **both** output paths: under `--json` the human rendering returns
6732
+ * early, and the first version of `--csv-out` therefore wrote nothing at all
6733
+ * there — a flag that silently did nothing, which is the fault this repository
6734
+ * keeps refusing elsewhere.
6735
+ *
6736
+ * Its inputs are named because it had eleven of them and declared none: it was
6737
+ * a closure over `commandProfile`’s scope, so what a CSV or a markdown summary
6738
+ * is built from could only be learned by reading the whole body it sat in.
6739
+ */
6740
+ async function writeProfileSideFiles(context) {
6741
+ const { args, path, report, previous, pressures, labelDrivers, modelDrivers, againstOverlap, whatIf, pricingStale, windowed, gates, pricing, t, } = context;
6744
6742
  /**
6745
- * The side files the caller asked for. Written on **both** output paths:
6746
- * under --json the human rendering returns early, and the first version of
6747
- * --csv-out therefore wrote nothing at all there — a flag that silently did
6748
- * nothing, which is the fault this repository keeps refusing elsewhere.
6743
+ * Where the "wrote to" notice goes. Under `--json`, stdout carries the
6744
+ * report and nothing else — a status line there turns a parseable
6745
+ * document into a parse error, which is how a pipeline discovers the
6746
+ * feature. The gates already route their verdicts to stderr for the same
6747
+ * reason.
6749
6748
  */
6750
- const writeSideFiles = async () => {
6749
+ const notice = boolFlag(args, 'json')
6750
+ ? (message) => console.error(message)
6751
+ : (message) => console.log(message);
6752
+ /**
6753
+ * The same report as GitHub-flavoured markdown, for a job summary or a PR
6754
+ * comment. Written from the same message catalogue the terminal used, because
6755
+ * two renderings of one finding drift the moment they are worded twice.
6756
+ */
6757
+ const markdownOut = stringFlag(args, 'markdown-out');
6758
+ const htmlOut = stringFlag(args, 'html-out');
6759
+ if (markdownOut !== undefined || htmlOut !== undefined) {
6751
6760
  /**
6752
- * Where the "wrote to" notice goes. Under `--json`, stdout carries the
6753
- * report and nothing else — a status line there turns a parseable
6754
- * document into a parse error, which is how a pipeline discovers the
6755
- * feature. The gates already route their verdicts to stderr for the same
6756
- * reason.
6761
+ * Derived here, not borrowed from the terminal path. Under `--json`
6762
+ * that path never runs, and the outer `levers` this block used to
6763
+ * reach for was an uninitialised binding — `profile --json
6764
+ * --markdown-out` crashed with a ReferenceError from 1.59 until the
6765
+ * HTML door's test drove both flags together and found it. The flag
6766
+ * did not silently do nothing; it loudly did nothing, and no test had
6767
+ * ever asked.
6757
6768
  */
6758
- const notice = boolFlag(args, 'json')
6759
- ? (message) => console.error(message)
6760
- : (message) => console.log(message);
6769
+ const levers = billLevers(report, { catalogue: pricing });
6770
+ const cache = cacheEconomics(report.total);
6761
6771
  /**
6762
- * The same report as GitHub-flavoured markdown, for a job summary or a PR
6763
- * comment. Written from the same message catalogue the terminal used, because
6764
- * two renderings of one finding drift the moment they are worded twice.
6765
- */
6766
- const markdownOut = stringFlag(args, 'markdown-out');
6767
- const htmlOut = stringFlag(args, 'html-out');
6768
- if (markdownOut !== undefined || htmlOut !== undefined) {
6769
- /**
6770
- * Derived here, not borrowed from the terminal path. Under `--json`
6771
- * that path never runs, and the outer `levers` this block used to
6772
- * reach for was an uninitialised binding — `profile --json
6773
- * --markdown-out` crashed with a ReferenceError from 1.59 until the
6774
- * HTML door's test drove both flags together and found it. The flag
6775
- * did not silently do nothing; it loudly did nothing, and no test had
6776
- * ever asked.
6777
- */
6778
- const levers = billLevers(report, { catalogue: pricing });
6779
- const cache = cacheEconomics(report.total);
6780
- /**
6781
- * One input object for both doors, built once: the HTML file and the
6782
- * Markdown file are two projections of the same figures, and building
6783
- * the input twice is how two renderings of one bill start disagreeing.
6784
- */
6785
- const renderInput = ({
6786
- report,
6787
- levers,
6788
- cache,
6789
- t,
6790
- ...(windowed
6791
- ? { window: { since: stringFlag(args, 'since') ?? '—', until: stringFlag(args, 'until') ?? '—' } }
6792
- : {}),
6793
- ...(pricingStale !== null ? { stalePricing: pricingStale } : {}),
6794
- // The verdict, where the person reading CI will see it. recordGates()
6795
- // runs before the side files for exactly this.
6796
- ...(gateVerdicts.length > 0 ? { gates: { failed: gateFailed, lines: gateVerdicts } } : {}),
6797
- // The short form, for a reader who is not in the terminal.
6798
- ...(boolFlag(args, 'markdown-summary') ? { summary: true } : {}),
6799
- // The repricing, when --what-if was given: computed once above and
6800
- // handed over, so the summary in a pull request cannot disagree
6801
- // with the terminal about what a move would cost.
6802
- ...(whatIf !== null ? { whatIf } : {}),
6803
- pressure: pressures,
6804
- // The comparison, when there was one — the same figures and the same
6805
- // drivers the terminal printed, never re-derived here.
6806
- ...(previous !== null
6807
- ? {
6808
- against: {
6809
- previousTotalUsd: previous.total.totalUsd,
6810
- previousCalls: previous.total.calls,
6811
- labelDrivers,
6812
- modelDrivers: new Set([
6813
- ...previous.byModel.map((r) => r.model),
6814
- ...report.byModel.map((r) => r.model),
6815
- ]).size > 1
6816
- ? modelDrivers
6817
- : [],
6818
- overlap: againstOverlap !== null
6819
- ? { from: dayOf(againstOverlap.fromMs), to: dayOf(againstOverlap.toMs) }
6820
- : null,
6821
- nothingPriced: previous.total.calls === 0,
6822
- },
6823
- }
6824
- : {}),
6825
- });
6826
- if (markdownOut !== undefined) {
6827
- await writeFile(markdownOut, renderProfileMarkdown(renderInput), 'utf8');
6828
- notice(c.dim(t.report.wroteTo(markdownOut)));
6829
- }
6830
- if (htmlOut !== undefined) {
6831
- await writeFile(htmlOut, renderProfileHtml(renderInput), 'utf8');
6832
- notice(c.dim(t.html.written(htmlOut)));
6833
- }
6772
+ * One input object for both doors, built once: the HTML file and the
6773
+ * Markdown file are two projections of the same figures, and building
6774
+ * the input twice is how two renderings of one bill start disagreeing.
6775
+ */
6776
+ const renderInput = ({
6777
+ report,
6778
+ levers,
6779
+ cache,
6780
+ t,
6781
+ ...(windowed
6782
+ ? { window: { since: stringFlag(args, 'since') ?? '—', until: stringFlag(args, 'until') ?? '—' } }
6783
+ : {}),
6784
+ ...(pricingStale !== null ? { stalePricing: pricingStale } : {}),
6785
+ // The verdict, where the person reading CI will see it. recordGates()
6786
+ // runs before the side files for exactly this.
6787
+ ...(gates.verdicts.length > 0 ? { gates: { failed: gates.failed, lines: gates.verdicts } } : {}),
6788
+ // The short form, for a reader who is not in the terminal.
6789
+ ...(boolFlag(args, 'markdown-summary') ? { summary: true } : {}),
6790
+ // The repricing, when --what-if was given: computed once above and
6791
+ // handed over, so the summary in a pull request cannot disagree
6792
+ // with the terminal about what a move would cost.
6793
+ ...(whatIf !== null ? { whatIf } : {}),
6794
+ pressure: pressures,
6795
+ // The comparison, when there was one — the same figures and the same
6796
+ // drivers the terminal printed, never re-derived here.
6797
+ ...(previous !== null
6798
+ ? {
6799
+ against: {
6800
+ previousTotalUsd: previous.total.totalUsd,
6801
+ previousCalls: previous.total.calls,
6802
+ labelDrivers,
6803
+ modelDrivers: new Set([
6804
+ ...previous.byModel.map((r) => r.model),
6805
+ ...report.byModel.map((r) => r.model),
6806
+ ]).size > 1
6807
+ ? modelDrivers
6808
+ : [],
6809
+ overlap: againstOverlap !== null
6810
+ ? { from: dayOf(againstOverlap.fromMs), to: dayOf(againstOverlap.toMs) }
6811
+ : null,
6812
+ nothingPriced: previous.total.calls === 0,
6813
+ },
6814
+ }
6815
+ : {}),
6816
+ });
6817
+ if (markdownOut !== undefined) {
6818
+ await writeFile(markdownOut, renderProfileMarkdown(renderInput), 'utf8');
6819
+ notice(c.dim(t.report.wroteTo(markdownOut)));
6834
6820
  }
6821
+ if (htmlOut !== undefined) {
6822
+ await writeFile(htmlOut, renderProfileHtml(renderInput), 'utf8');
6823
+ notice(c.dim(t.html.written(htmlOut)));
6824
+ }
6825
+ }
6826
+ /**
6827
+ * The same report as a spreadsheet, one row per label and model — the grain
6828
+ * a routing or budget decision is made at. Deliberately without a total
6829
+ * row: a total inside a data file is summed with the data and doubles every
6830
+ * figure downstream.
6831
+ */
6832
+ const csvOut = stringFlag(args, 'csv-out');
6833
+ if (csvOut !== undefined) {
6835
6834
  /**
6836
- * The same report as a spreadsheet, one row per label and model — the grain
6837
- * a routing or budget decision is made at. Deliberately without a total
6838
- * row: a total inside a data file is summed with the data and doubles every
6839
- * figure downstream.
6835
+ * Which table the file holds. One row shape per file on purpose: a
6836
+ * spreadsheet that has to filter before it can sum is a spreadsheet
6837
+ * somebody sums wrong.
6840
6838
  */
6841
- const csvOut = stringFlag(args, 'csv-out');
6842
- if (csvOut !== undefined) {
6843
- /**
6844
- * Which table the file holds. One row shape per file on purpose: a
6845
- * spreadsheet that has to filter before it can sum is a spreadsheet
6846
- * somebody sums wrong.
6847
- */
6848
- const shape = stringFlag(args, 'csv-shape') ?? 'slice';
6849
- if (shape !== 'slice' && shape !== 'day' && shape !== 'hour' && shape !== 'model-day') {
6850
- throw new Error(t.profile.badCsvShape(shape));
6851
- }
6852
- await writeFile(csvOut, profileToCsv(report, { unlabelled: t.profile.unlabelled(), shape }), 'utf8');
6853
- notice(c.dim(t.report.wroteTo(csvOut)));
6839
+ const shape = stringFlag(args, 'csv-shape') ?? 'slice';
6840
+ if (shape !== 'slice' && shape !== 'day' && shape !== 'hour' && shape !== 'model-day') {
6841
+ throw new Error(t.profile.badCsvShape(shape));
6854
6842
  }
6855
- };
6856
- if (boolFlag(args, 'json')) {
6857
- /**
6858
- * The report, plus everything the human output leads on.
6859
- *
6860
- * Additive rather than a reshape: `report` keeps the shape `@trazum/core`
6861
- * returns. The cache verdict is included because leaving a consumer to
6862
- * re-derive it means two implementations of a sign convention where positive
6863
- * means *worse*, and one of them will eventually get it backwards.
6864
- *
6865
- * `levers` is included because it was not, and that made the flagship
6866
- * section terminal-only: "What would actually move this bill" — the reason
6867
- * the command exists — was invisible to any pipeline, dashboard or CI step
6868
- * reading the JSON. A finding the machine-readable output omits is a finding
6869
- * the reader's tooling will never surface.
6870
- */
6871
- console.log(JSON.stringify({
6843
+ await writeFile(csvOut, profileToCsv(report, { unlabelled: t.profile.unlabelled(), shape }), 'utf8');
6844
+ notice(c.dim(t.report.wroteTo(csvOut)));
6845
+ }
6846
+ }
6847
+ /**
6848
+ * What this log recorded about outcomes, and what it cannot answer.
6849
+ *
6850
+ * Every finding past the totals needs a field the format does not require, and a
6851
+ * reader who never adds them sees a report quietly missing half of itself, with no
6852
+ * way to tell "nothing to report" from "nothing recorded". Named with counts rather
6853
+ * than booleans: twelve labelled records out of forty thousand is not a labelled
6854
+ * log, and a boolean would call it one.
6855
+ *
6856
+ * Outcomes print above coverage rather than below, and the two travel together here
6857
+ * for the same reason they do on screen: coverage is the sentence that qualifies
6858
+ * whatever the outcomes just claimed.
6859
+ */
6860
+ function reportOutcomesAndCoverage(report, config, t) {
6861
+ const n = (value) => value.toLocaleString(t.numberLocale);
6862
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6863
+ /**
6864
+ * What this log cannot answer, and what would fix it.
6865
+ *
6866
+ * Every finding past the totals needs a field the format does not require,
6867
+ * and a reader who never adds them sees a report quietly missing half of
6868
+ * itself — with no way to tell "nothing to report" from "nothing recorded".
6869
+ * Named with counts rather than booleans: twelve labelled records out of
6870
+ * forty thousand is not a labelled log, and a boolean would call it one.
6871
+ *
6872
+ * Only fields that are actually missing are listed. A complete log gets no
6873
+ * section at all, because a paragraph of things that are fine is the
6874
+ * paragraph readers learn to skip.
6875
+ */
6876
+ /**
6877
+ * Outcomes — the counterpart, where somebody recorded one.
6878
+ *
6879
+ * Printed above the coverage section rather than below it, because when this
6880
+ * section is present it is the most valuable thing on the page: every other
6881
+ * figure in this report is a cost, and this is the only one that says what
6882
+ * the money bought.
6883
+ *
6884
+ * Silent when nothing recorded an outcome. The coverage section below
6885
+ * already names the missing field and what it would unlock, and printing an
6886
+ * empty Outcomes heading above it would be the same sentence twice.
6887
+ */
6888
+ {
6889
+ const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
6890
+ if (outcomes.coverage.recorded > 0) {
6891
+ console.log();
6892
+ console.log(sectionHeading(t.profile.outcomeHeading()));
6893
+ const col = t.profile.outcomeColumns;
6894
+ const rows = [...outcomes.slices, ...outcomes.undeclared].map((slice) => ({
6895
+ value: slice.value,
6896
+ verdict: slice.verdict === 'success'
6897
+ ? t.profile.verdictSuccess()
6898
+ : slice.verdict === 'undeclared'
6899
+ ? t.profile.verdictUndeclared()
6900
+ : t.profile.verdictOther(),
6901
+ calls: n(slice.calls),
6902
+ spend: formatUsd(slice.usd),
6903
+ }));
6904
+ const w = {
6905
+ value: Math.max(...rows.map((r) => r.value.length), col.outcome.length),
6906
+ verdict: Math.max(...rows.map((r) => r.verdict.length), 0),
6907
+ calls: Math.max(...rows.map((r) => r.calls.length), col.calls.length),
6908
+ spend: Math.max(...rows.map((r) => r.spend.length), col.spend.length),
6909
+ };
6910
+ console.log(c.dim(` ${col.outcome.padEnd(w.value)} ${''.padEnd(w.verdict)} ` +
6911
+ `${col.calls.padStart(w.calls)} ${col.spend.padStart(w.spend)}`));
6912
+ for (const row of rows) {
6913
+ const tint = row.verdict === t.profile.verdictUndeclared()
6914
+ ? c.yellow
6915
+ : row.verdict === t.profile.verdictSuccess()
6916
+ ? c.green
6917
+ : c.dim;
6918
+ console.log(` ${row.value.padEnd(w.value)} ${tint(row.verdict.padEnd(w.verdict))} ` +
6919
+ `${row.calls.padStart(w.calls)} ${row.spend.padStart(w.spend)}`);
6920
+ }
6921
+ console.log();
6922
+ if (outcomes.successShareOfRecordedUsd !== null) {
6923
+ const declaredUsd = outcomes.slices.reduce((sum, slice) => sum + slice.usd, 0);
6924
+ console.log(` ${wrap(t.profile.outcomeRate(pct(outcomes.successShareOfRecordedUsd), formatUsd(declaredUsd)), 74, ' ')}`);
6925
+ }
6926
+ else if (outcomes.noRate !== null) {
6927
+ console.log(` ${c.dim(wrap(t.profile.outcomeNoRate(outcomes.noRate), 74, ' '))}`);
6928
+ }
6929
+ // What the rate does not cover, every time it is printed. A rate over a
6930
+ // twelfth of the bill is a rate about a twelfth of the bill.
6931
+ if (outcomes.coverage.unrecordedUsd > 0 && report.total.totalUsd > 0) {
6932
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.outcomeUnrecorded(pct(outcomes.coverage.unrecordedUsd / report.total.totalUsd), formatUsd(outcomes.coverage.unrecordedUsd)), 74, ' ')}`);
6933
+ }
6872
6934
  /**
6873
- * `schemaVersion` arrives inside `report` now, and that is the point.
6935
+ * What an outcome costs, per workload — the finding a total cannot make.
6874
6936
  *
6875
- * It used to be stamped here, which made the profile the one contract
6876
- * of the ten whose version existed only if you went through this
6877
- * command. `docs/format.md` says every document carries it and
6878
- * `conform` rejects one that does not, so a connector author using
6879
- * `@trazum/core` produced a profile this tool refuses.
6937
+ * Printed only when at least one workload has enough recorded outcomes
6938
+ * to say something, and every row that cannot state a figure says which
6939
+ * of the five reasons applies rather than showing a blank.
6940
+ */
6941
+ const ranking = rankPerOutcome(report.outcomeTallyByLabel.map((entry) => ({
6942
+ key: entry.label,
6943
+ calls: entry.calls,
6944
+ totalUsd: entry.totalUsd,
6945
+ tally: entry.tally,
6946
+ })), config.outcomes ?? null);
6947
+ if (ranking.byCall.length > 0) {
6948
+ console.log();
6949
+ console.log(sectionHeading(t.profile.perOutcomeHeading()));
6950
+ const pcol = t.profile.perOutcomeColumns;
6951
+ const prows = ranking.byCall.map((slice) => ({
6952
+ key: slice.key,
6953
+ perCall: formatUsd(slice.usdPerCall),
6954
+ perOutcome: slice.per.usdPerSuccess !== null
6955
+ ? formatUsd(slice.per.usdPerSuccess)
6956
+ : t.profile.perOutcomeWithheld(slice.per.withheld ?? 'no-vocabulary', n(slice.per.successes), pct(slice.per.coverage)),
6957
+ recorded: pct(slice.per.coverage),
6958
+ }));
6959
+ const pw = {
6960
+ key: Math.max(...prows.map((r) => r.key.length), pcol.workload.length),
6961
+ perCall: Math.max(...prows.map((r) => r.perCall.length), pcol.perCall.length),
6962
+ perOutcome: Math.max(...prows.map((r) => r.perOutcome.length), pcol.perOutcome.length),
6963
+ recorded: Math.max(...prows.map((r) => r.recorded.length), pcol.recorded.length),
6964
+ };
6965
+ console.log(c.dim(` ${pcol.workload.padEnd(pw.key)} ${pcol.perCall.padStart(pw.perCall)} ` +
6966
+ `${pcol.perOutcome.padStart(pw.perOutcome)} ${pcol.recorded.padStart(pw.recorded)}`));
6967
+ for (const row of prows) {
6968
+ console.log(` ${row.key.padEnd(pw.key)} ${row.perCall.padStart(pw.perCall)} ` +
6969
+ `${row.perOutcome.padStart(pw.perOutcome)} ${c.dim(row.recorded.padStart(pw.recorded))}`);
6970
+ }
6971
+ console.log();
6972
+ console.log(` ${c.dim(wrap(t.profile.perOutcomeNumerator(), 74, ' '))}`);
6973
+ // The disagreement between the two orders, which is itself the finding.
6974
+ if (ranking.disagreements.length > 0) {
6975
+ console.log();
6976
+ console.log(` ${c.dim(wrap(t.profile.perOutcomeBothOrders(), 74, ' '))}`);
6977
+ for (const d of ranking.disagreements) {
6978
+ console.log(` ${c.yellow('→')} ${wrap(t.profile.perOutcomeDisagreement(d.slice.key, n(d.callRank + 1), n(d.outcomeRank + 1)), 74, ' ')}`);
6979
+ }
6980
+ }
6981
+ }
6982
+ if (outcomes.undeclared.length > 0) {
6983
+ console.log(` ${c.yellow('!')} ${wrap(t.profile.outcomeUndeclared(outcomes.undeclared.map((s) => s.value).join(', ')), 74, ' ')}`);
6984
+ }
6985
+ }
6986
+ }
6987
+ const coverage = report.fieldCoverage;
6988
+ if (coverage.parsed > 0) {
6989
+ const missing = [];
6990
+ const partial = (seen) => `${n(seen)}/${n(coverage.parsed)}`;
6991
+ if (coverage.label < coverage.parsed) {
6992
+ missing.push(t.profile.needsLabel(partial(coverage.label)));
6993
+ }
6994
+ if (coverage.session < coverage.parsed) {
6995
+ missing.push(t.profile.needsSession(partial(coverage.session)));
6996
+ }
6997
+ /**
6998
+ * Listed first among the missing when it is missing entirely, because it
6999
+ * is the one field that changes what every other figure here *means*. The
7000
+ * rest sharpen a cost; this one gives it a counterpart.
7001
+ */
7002
+ if (coverage.outcome < coverage.parsed) {
7003
+ missing.push(t.profile.needsOutcome(partial(coverage.outcome)));
7004
+ }
7005
+ if (coverage.ts < coverage.parsed) {
7006
+ missing.push(t.profile.needsTs(partial(coverage.ts)));
7007
+ }
7008
+ if (coverage.stopReason < coverage.parsed) {
7009
+ missing.push(t.profile.needsStopReason(partial(coverage.stopReason)));
7010
+ }
7011
+ if (coverage.cacheWrites > 0 && coverage.cacheTtl < coverage.cacheWrites) {
7012
+ missing.push(t.profile.needsCacheTtl(`${n(coverage.cacheTtl)}/${n(coverage.cacheWrites)}`));
7013
+ }
7014
+ if (missing.length > 0) {
7015
+ console.log();
7016
+ console.log(sectionHeading(t.profile.coverageHeading()));
7017
+ for (const line of missing)
7018
+ console.log(` ${c.dim(wrap(line, 74, ' '))}`);
7019
+ }
7020
+ }
7021
+ }
7022
+ /**
7023
+ * This bill against the previous one: how spend actually gets out of hand.
7024
+ *
7025
+ * Nobody adds five thousand a month in one day; bills grow four percent a week
7026
+ * while every snapshot looks reasonable. This is the baseline gate the prompts
7027
+ * already had, applied to the money itself. **Positive means the bill grew** (the
7028
+ * diff convention), and every figure is between exactly these two files.
7029
+ *
7030
+ * Its inputs are stated because it had eight of them and declared none. Two are
7031
+ * drivers computed three hundred lines earlier and used nowhere else, which is a
7032
+ * thing you could only find out by reading both places.
7033
+ */
7034
+ function reportAgainstPrevious(context) {
7035
+ const { report, previous, againstOverlap, labelDrivers, modelDrivers, gates, now, t } = context;
7036
+ const n = (value) => value.toLocaleString(t.numberLocale);
7037
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7038
+ /**
7039
+ * This bill against the previous one — how spend actually gets out of hand.
7040
+ *
7041
+ * Nobody adds five thousand a month in one day; bills grow four percent a week
7042
+ * while every snapshot looks reasonable. This is the baseline gate the prompts
7043
+ * already had, applied to the money itself. **Positive means the bill grew**
7044
+ * (the diff convention), and every figure is between exactly these two files:
7045
+ * no period is assumed, so the call counts print beside the money for the
7046
+ * reader to judge comparability before judging the trend.
7047
+ */
7048
+ if (previous !== null) {
7049
+ console.log();
7050
+ console.log(sectionHeading(t.profile.againstHeading()));
7051
+ if (previous.total.calls === 0) {
7052
+ console.log(` ${c.dim(wrap(t.profile.againstNothingPriced(), 74, ' '))}`);
7053
+ }
7054
+ else {
7055
+ const delta = report.total.totalUsd - previous.total.totalUsd;
7056
+ const growthPct = previous.total.totalUsd > 0
7057
+ ? `${delta >= 0 ? '+' : ''}${((delta / previous.total.totalUsd) * 100).toFixed(1)}%`
7058
+ : '—';
7059
+ console.log(` ${c.bold(wrap(t.profile.againstTotals(formatUsd(previous.total.totalUsd), formatUsd(report.total.totalUsd), formatSignedUsd(delta), growthPct, t.profile.calls(previous.total.calls), t.profile.calls(report.total.calls)), 74, ' '))}`);
7060
+ // Overlapping spans mean part of this "growth" is the same money on
7061
+ // both sides of the subtraction. Said after the figure it qualifies
7062
+ // and before the drivers built from it.
7063
+ if (againstOverlap !== null) {
7064
+ console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.againstOverlap(dayOf(againstOverlap.fromMs), dayOf(againstOverlap.toMs)), 74, ' '))}`);
7065
+ }
7066
+ // Drivers: per-key contribution to the change, largest magnitude first,
7067
+ // computed once beside the gates so no rendering derives its own.
7068
+ const driverLine = (d, shown) => d.was === null
7069
+ ? t.profile.againstDriverNew(formatSignedUsd(d.delta), shown)
7070
+ : d.now === null
7071
+ ? t.profile.againstDriverGone(formatSignedUsd(d.delta), shown)
7072
+ : t.profile.againstDriver(formatSignedUsd(d.delta), shown, formatUsd(d.was), formatUsd(d.now));
7073
+ console.log();
7074
+ for (const d of labelDrivers.slice(0, 5)) {
7075
+ const line = driverLine(d, d.key === UNLABELLED ? t.profile.unlabelled() : d.key);
7076
+ console.log(` ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
7077
+ }
7078
+ if (labelDrivers.length > 5) {
7079
+ console.log(` ${c.dim(t.profile.andMoreLabels(labelDrivers.length - 5))}`);
7080
+ }
7081
+ /**
7082
+ * The same change, by model — where the mix moved. The label rows cannot
7083
+ * show it: a workload that kept its name and switched from Haiku to Opus
7084
+ * reads as "chat grew", and the reason is the model. Only printed when
7085
+ * more than one model is involved; with one model on both sides, this
7086
+ * section restates the totals line and says nothing new.
7087
+ */
7088
+ const modelsInvolved = new Set([
7089
+ ...previous.byModel.map((r) => r.model),
7090
+ ...report.byModel.map((r) => r.model),
7091
+ ]);
7092
+ if (modelDrivers.length > 0 && modelsInvolved.size > 1) {
7093
+ console.log();
7094
+ console.log(` ${c.dim(t.profile.againstByModel())}`);
7095
+ for (const d of modelDrivers.slice(0, 3)) {
7096
+ const line = driverLine(d, d.key);
7097
+ console.log(` ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
7098
+ }
7099
+ }
7100
+ /**
7101
+ * What the comparison stopped being able to see.
6880
7102
  *
6881
- * The contract is documented in docs/json-output.md and enforced by
6882
- * json-contract.test.js. It changes only when a field's meaning
6883
- * changes or one is removed — new findings arrive as new keys, so a
6884
- * consumer that ignores unknown ones keeps working.
7103
+ * Every figure above is dollars, and dollars cannot tell a finding that
7104
+ * was fixed from a finding whose field the log stopped recording — both
7105
+ * are silence. This is the only section that can, so it is loud: a
7106
+ * collapse in coverage invalidates whichever findings depended on it,
7107
+ * and reading the drop as good news is the specific mistake it exists
7108
+ * to prevent.
6885
7109
  */
6886
- ...report,
6887
- cache: cacheEconomics(report.total),
6888
- cacheByLabel: report.byLabel.map((r) => ({
6889
- label: r.label,
6890
- cache: cacheEconomics(r.breakdown),
6891
- })),
6892
- // The provenance of every dollar above: which price table, how old.
6893
- pricing: { lastReviewed: pricing.lastReviewed, ageDays: pricingAgeDays },
6894
- levers: billLevers(report, { catalogue: pricing }),
6895
- // Present only when --against was passed: null delta means the
6896
- // previous log had nothing priced, which is a different answer from
6897
- // zero growth.
6898
- ...(previous !== null
6899
- ? {
6900
- against: {
6901
- previousTotalUsd: previous.total.totalUsd,
6902
- deltaUsd: againstDelta,
6903
- // The same drivers the terminal names, as data. A finding
6904
- // the machine-readable output omits is a finding the
6905
- // reader's tooling will never surface.
6906
- byLabel: labelDrivers,
6907
- byModel: modelDrivers,
6908
- },
7110
+ const drifts = coverageDrift(previous.fieldCoverage, report.fieldCoverage);
7111
+ if (drifts.length > 0) {
7112
+ console.log();
7113
+ for (const drift of drifts) {
7114
+ const line = t.profile.coverageDrift(t.profile.coverageField(drift.field), pct(drift.was), pct(drift.now));
7115
+ console.log(drift.delta < 0
7116
+ ? ` ${c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`
7117
+ : ` ${c.dim(wrap(line, 74, ' '))}`);
7118
+ /**
7119
+ * Which findings went with it, named. "Some findings are silent" is
7120
+ * not something a reader can act on; knowing that conversation
7121
+ * growth and the cache-TTL fit are now silence rather than absence
7122
+ * tells them exactly which sections of this report to distrust.
7123
+ */
7124
+ if (drift.delta < 0) {
7125
+ const silenced = t.profile.coverageSilenced(drift.field);
7126
+ if (silenced !== '')
7127
+ console.log(` ${c.dim(wrap(silenced, 72, ' '))}`);
7128
+ }
6909
7129
  }
6910
- : {}),
6911
- // How close each slice's largest call is to its model's window —
6912
- // derived like `cache` and `levers`, so a dashboard need not
6913
- // re-derive a ratio whose denominator lives in the catalogue.
6914
- contextPressure: pressures,
6915
- // Present only when --what-if was passed. `sameTokensAssumed` rides
6916
- // along inside it so a consumer cannot print the dollar figure
6917
- // without the caveat being in the same object.
6918
- ...(whatIf !== null ? { whatIf } : {}),
6919
- }, null, 2));
6920
- recordGates();
6921
- await recordWaiverUses();
6922
- await writeSideFiles();
6923
- return;
7130
+ if (drifts.some((d) => d.delta < 0)) {
7131
+ console.log(` ${c.dim(wrap(t.profile.coverageDriftWhy(), 74, ' '))}`);
7132
+ }
7133
+ }
7134
+ }
7135
+ }
7136
+ }
7137
+ /**
7138
+ * The same request, sent again a moment later.
7139
+ *
7140
+ * A conversation's input grows with every turn, so two calls of the same size
7141
+ * seconds apart are not a conversation: they are a retry, a duplicated step, a
7142
+ * loop. Loud, because the money bought nothing, and hedged, because this reads
7143
+ * counts and cannot see content.
7144
+ */
7145
+ function reportRepeatedCalls(report, t) {
7146
+ const n = (value) => value.toLocaleString(t.numberLocale);
7147
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7148
+ /**
7149
+ * The same request, sent again a moment later.
7150
+ *
7151
+ * A conversation's input grows with every turn, so two consecutive calls in
7152
+ * one conversation carrying the same size seconds apart is a thing going
7153
+ * wrong rather than a thing working — a retry after a timeout, an agent
7154
+ * step repeating, a loop. Loud, because the money bought nothing, and
7155
+ * hedged, because this reads counts and cannot see content: the sentence
7156
+ * says the pattern is *usually* a retry, never that it is one.
7157
+ */
7158
+ if (report.repeatedTurns.length > 0) {
7159
+ console.log();
7160
+ console.log(sectionHeading(t.profile.repeatsHeading()));
7161
+ for (const row of report.repeatedTurns.slice(0, 3)) {
7162
+ const label = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7163
+ console.log();
7164
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.repeatsFound(label, row.modelName, n(row.repeats), n(row.checkedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.usd)), 74, ' '))}`);
7165
+ console.log(` ${c.dim(wrap(t.profile.repeatsAdvice(), 74, ' '))}`);
7166
+ }
7167
+ }
7168
+ /**
7169
+ * Output spend that bought answers cut off mid-generation — the one slice of
7170
+ * a bill that is waste without a counterpart. Paid in full, frequently
7171
+ * retried and billed again, and the truncated attempt bought nothing.
7172
+ *
7173
+ * Three states, kept apart on purpose: waste found, none found on a log that
7174
+ * measured, and a log that never recorded a stop reason at all — which gets
7175
+ * the missing-field message, because silence there would read as a clean bill
7176
+ * of health on a question the log never asked.
7177
+ */
7178
+ if (report.total.truncatedCalls > 0 && report.total.outputUsd > 0) {
7179
+ console.log();
7180
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.truncatedWaste(t.profile.calls(report.total.truncatedCalls), formatUsd(report.total.truncatedOutputUsd), pct(report.total.truncatedOutputUsd / report.total.outputUsd)), 74, ' '))}`);
7181
+ /**
7182
+ * Which workloads are paying for it, and at what rate — the actionable
7183
+ * half the total hides. A 40% truncation rate is a max_tokens setting
7184
+ * that is simply wrong; 1% is a long tail, and the two call for opposite
7185
+ * responses.
7186
+ *
7187
+ * The rate is over calls that **recorded a stop reason**, never over all
7188
+ * calls: a workload that logs the field on half its traffic must not be
7189
+ * reported as though the unmeasured half completed. Both numbers print,
7190
+ * so the denominator is visible rather than implied.
7191
+ */
7192
+ const truncatedLabels = report.byLabel
7193
+ .filter((row) => row.breakdown.truncatedCalls > 0)
7194
+ .sort((a, b) => b.breakdown.truncatedOutputUsd - a.breakdown.truncatedOutputUsd);
7195
+ if (truncatedLabels.length > 0 && report.byLabel.length > 1) {
7196
+ for (const row of truncatedLabels.slice(0, 3)) {
7197
+ const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7198
+ console.log(` ${c.dim(wrap(t.profile.truncatedBy(name, n(row.breakdown.truncatedCalls), n(row.breakdown.stopReasonCalls), pct(row.breakdown.truncatedCalls / row.breakdown.stopReasonCalls), formatUsd(row.breakdown.truncatedOutputUsd)), 74, ' '))}`);
7199
+ }
7200
+ }
7201
+ /**
7202
+ * The ceiling the completed answers actually needed, when the output
7203
+ * shapes measured it: "95% of the answers that finished fit within N
7204
+ * tokens" is the number a max_tokens cap wants, and it sits next to the
7205
+ * evidence that the current cap is too low. Measured on these calls,
7206
+ * promised for nothing.
7207
+ */
7208
+ const ceiling = report.outputShapes.find((shape) => shape.p95WithinTokens !== null);
7209
+ if (ceiling !== undefined) {
7210
+ console.log(` ${c.dim(wrap(t.profile.truncatedCeiling(n(ceiling.p95WithinTokens)), 74, ' '))}`);
7211
+ }
7212
+ /**
7213
+ * The "billed again" half, measured. The sentence above has always said
7214
+ * truncated answers are frequently retried; this is the count and the
7215
+ * money, when the log can carry it — a pattern, never a certainty, and
7216
+ * attributed to the truncated call's slice, where the ceiling that
7217
+ * caused it lives.
7218
+ */
7219
+ for (const row of report.truncationRetries.slice(0, 3)) {
7220
+ const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7221
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.truncationRetryLine(name, row.modelName, n(row.retried), n(row.truncatedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.wastedUsd), formatUsd(row.retryUsd)), 74, ' '))}`);
7222
+ }
7223
+ if (report.truncationRetries.length > 0) {
7224
+ console.log(` ${c.dim(wrap(t.profile.truncationRetryNote(), 74, ' '))}`);
7225
+ }
6924
7226
  }
6925
- /**
6926
- * Nothing priced means there is no report, not a report of zero.
6927
- *
6928
- * The guard was `total.calls === 0 && unpriced.calls === 0`, so a log whose every
6929
- * model was unknown fell through and printed a full report built from a zeroed
6930
- * total: `0 calls · $0`, four `$0 / 0.0%` rows, a meaningless "Input is 0.0% of
6931
- * this bill", and — on a log containing a hundred thousand cache-read tokens —
6932
- * the flatly false "Caching was never used on these calls".
6933
- *
6934
- * Two affirmatively wrong claims and a $0 headline for a real bill. The trailing
6935
- * unpriced note was the only correct line on screen, and it was the quietest.
6936
- */
6937
- if (report.total.calls === 0) {
7227
+ else if (report.total.stopReasonCalls === 0) {
6938
7228
  console.log();
6939
- console.log(c.dim(report.unpriced.calls === 0 ? t.profile.empty() : t.profile.nothingPriced()));
6940
- reportProfileGaps(report, t, n, pricingStale);
6941
- return;
7229
+ console.log(` ${c.dim(wrap(t.profile.truncatedNotRecorded(), 74, ' '))}`);
6942
7230
  }
6943
- const shares = sharesOf(report.total);
6944
- const parts = [
6945
- [t.profile.partInput(), report.total.inputUsd, shares.input, report.total.inputTokens],
6946
- [t.profile.partCacheRead(), report.total.cacheReadUsd, shares.cacheRead, report.total.cacheReadTokens],
6947
- [t.profile.partCacheWrite(), report.total.cacheWriteUsd, shares.cacheWrite, report.total.cacheWriteTokens],
6948
- [t.profile.partOutput(), report.total.outputUsd, shares.output, report.total.outputTokens],
6949
- ];
6950
- console.log();
6951
- console.log(sectionHeading(t.profile.heading()));
6952
- console.log(` ${t.profile.spent(t.profile.calls(report.total.calls), formatUsd(report.total.totalUsd))}`);
7231
+ }
7232
+ /**
7233
+ * The mix moving inside one log: the drift `--against` needs two files to see.
7234
+ *
7235
+ * Spoken only past fifteen points, and hedged in the copy while the data states
7236
+ * exact shares, because a mix that moved is a question rather than a finding.
7237
+ */
7238
+ function reportMixDrift(report, t) {
7239
+ const n = (value) => value.toLocaleString(t.numberLocale);
7240
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6953
7241
  /**
6954
- * The period, when the log carries a clock — stated, never extrapolated. A
6955
- * span makes the reader's own monthly arithmetic valid; a per-month figure
6956
- * printed from a partial month would be this tool doing the guessing it
6957
- * exists to end. Partial coverage is said in the same breath, because a span
6958
- * over a third of the calls silently presented as the log's period is a
6959
- * figure attributed to something it does not describe.
7242
+ * The mix moving inside one log — the drift `--against` needs a second log
7243
+ * to see. Spoken only past fifteen points, a presentation threshold stated
7244
+ * in the copy; the data states exact shares and the JSON carries them all.
6960
7245
  */
6961
- if (report.span !== null) {
6962
- const totalParsed = report.total.calls + report.unpriced.calls;
6963
- const partial = report.span.calls < totalParsed
6964
- ? ` ${t.profile.spanPartial(n(report.span.calls), n(totalParsed))}`
6965
- : '';
6966
- console.log(` ${c.dim(wrap(`${t.profile.spanLine(dayOf(report.span.fromMs), dayOf(report.span.toMs), spanDays(report.span.fromMs, report.span.toMs))}${partial}`, 74, ' '))}`);
6967
- }
6968
- // How many files this report covers, when it covers more than one: a total
6969
- // over "the logs" that silently skipped one is wrong by an unknown amount.
6970
- if (logFiles.length > 1) {
6971
- console.log(` ${c.dim(wrap(t.profile.readFiles(logFiles.length, path), 74, ' '))}`);
7246
+ if (report.modelMixDrift !== null) {
7247
+ const moved = report.modelMixDrift.models.filter((m) => Math.abs(m.lastShare - m.firstShare) >= 0.15);
7248
+ if (moved.length > 0) {
7249
+ console.log();
7250
+ console.log(sectionHeading(t.profile.mixDriftHeading()));
7251
+ for (const m of moved.slice(0, 3)) {
7252
+ console.log();
7253
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.mixDriftLine(m.model, pct(m.firstShare), pct(m.lastShare), n(report.modelMixDrift.firstDays), n(report.modelMixDrift.lastDays), formatUsd(m.lastUsd)), 74, ' '))}`);
7254
+ }
7255
+ console.log(` ${c.dim(wrap(t.profile.mixDriftNote(), 74, ' '))}`);
7256
+ }
6972
7257
  }
7258
+ }
7259
+ /**
7260
+ * How close the largest call is to the model's ceiling.
7261
+ *
7262
+ * A window is a wall, not a budget: the call that hits it fails rather than costing
7263
+ * more, so this is a different warning from every dollar above it and is kept a
7264
+ * different shape.
7265
+ */
7266
+ function reportContextPressure(pressures, t) {
7267
+ const n = (value) => value.toLocaleString(t.numberLocale);
7268
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
6973
7269
  /**
6974
- * A doubled bill, said before anything is believed.
7270
+ * How close the largest call is to the model's ceiling.
6975
7271
  *
6976
- * Reading a directory of rotated logs makes double-counting easy — a log
6977
- * exported twice, an overlapping export, a copy left in the folder — and
6978
- * the total then reads high with nothing else able to see it. Only counted
6979
- * over records with a clock, where an identical line is a claim worth
6980
- * making. It states the count and the money and stops: whether it is a
6981
- * double export or a genuinely busy millisecond is the reader's to know.
6982
- */
6983
- if (report.duplicateLines.count > 0) {
6984
- console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.duplicateLines(report.duplicateLines.count, formatUsd(report.duplicateLines.usd)), 74, ' '))}`);
6985
- }
6986
- /**
6987
- * The window, said before any figure is trusted as "the log": everything
6988
- * below describes a slice, and a slice presented as the whole is a figure
6989
- * attributed to something it does not describe. The undated count is loud —
6990
- * those calls' spend is in the log and not in this report, so the window's
6991
- * figures are a floor on the period, and only this line says so.
7272
+ * The failure a bill cannot show: input grows turn by turn or document by
7273
+ * document, costs nothing extra to grow, and then one call crosses the
7274
+ * context window and the API refuses it. Loud from 85% — close enough
7275
+ * that the next retrieval bump or long conversation plausibly crosses —
7276
+ * and quiet above half, so the reader sees it coming either way. No
7277
+ * prediction of *when*: a straight line through two points is a guess
7278
+ * wearing arithmetic's clothes.
6992
7279
  */
6993
- if (report.timeWindow !== null) {
6994
- console.log(` ${c.dim(wrap(t.profile.windowLine(stringFlag(args, 'since') ?? '—', stringFlag(args, 'until') ?? '—'), 74, ' '))}`);
6995
- if (relativeWindow) {
6996
- console.log(` ${c.dim(wrap(t.profile.windowRelative(), 74, ' '))}`);
6997
- }
6998
- if (report.timeWindow.undatedExcluded > 0) {
6999
- console.log(` ${c.yellow(wrap(t.profile.windowUndated(report.timeWindow.undatedExcluded), 74, ' '))}`);
7280
+ {
7281
+ if (pressures.length > 0) {
7282
+ console.log();
7283
+ console.log(sectionHeading(t.profile.pressureHeading()));
7284
+ for (const row of pressures.slice(0, 3)) {
7285
+ const label = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7286
+ const line = t.profile.pressureLine(label, row.modelName, n(row.maxCallInputTokens), n(row.contextWindow), pct(row.share));
7287
+ console.log();
7288
+ if (row.share >= 0.85) {
7289
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`);
7290
+ console.log(` ${c.dim(wrap(t.profile.pressureAdvice(), 74, ' '))}`);
7291
+ }
7292
+ else {
7293
+ console.log(` ${c.dim(wrap(line, 74, ' '))}`);
7294
+ }
7295
+ }
7000
7296
  }
7001
7297
  }
7002
- console.log();
7003
- // Every part, including the zero ones. A row missing because it was zero reads
7004
- // as a row somebody forgot, and "you are not caching at all" is a finding.
7005
- for (const [name, usd, share, tokens] of parts) {
7006
- console.log(` ${bar(share)} ${t.profile.part(name, formatUsd(usd), pct(share), n(tokens))}`);
7007
- }
7298
+ }
7299
+ /**
7300
+ * How big the calls themselves are, which is the other half of the bill.
7301
+ *
7302
+ * The totals say what was spent; this says whether it went on many small calls or a
7303
+ * few enormous ones, and those two bills are fixed by different things.
7304
+ */
7305
+ function reportInputShape(report, t) {
7306
+ const n = (value) => value.toLocaleString(t.numberLocale);
7307
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7008
7308
  /**
7009
- * The line the command exists for: which part of the bill to argue with.
7309
+ * How big the calls themselves are — the other half of the bill.
7010
7310
  *
7011
- * When output is both the biggest part and over half, the two sentences say the
7012
- * same thing and the second says more — so only the second prints. Reporting a
7013
- * fact twice in adjacent lines reads as a bug, and it was one.
7014
- */
7015
- const [biggestName, , biggestShare] = parts.reduce((a, b) => (b[1] > a[1] ? b : a));
7016
- const outputDominates = shares.output > 0.5;
7017
- console.log();
7018
- if (outputDominates) {
7019
- console.log(` ${c.bold(wrap(t.profile.outputDominates(pct(shares.output)), 74, ' '))}`);
7020
- }
7021
- else {
7022
- console.log(` ${c.bold(t.profile.biggestPart(biggestName, pct(biggestShare)))}`);
7023
- }
7024
- /**
7025
- * The most expensive day, with a suspect attached.
7311
+ * The section above describes output; on a RAG or agent workload input is
7312
+ * most of the invoice, and a total could only ever say "input is 63% of
7313
+ * this bill", which nobody can act on. The actionable question is whether
7314
+ * the ordinary call is large or a few calls are enormous, and those two
7315
+ * shapes want opposite responses: a cap on something, or a shorter prompt.
7026
7316
  *
7027
- * The shape of a bill over time is the finding the total hides: a steady $3 a
7028
- * day and a quiet week broken by one $40 spike sum to the same number and call
7029
- * for opposite responses. Rendered against the **median** day — a mean would
7030
- * let the spike inflate its own yardstick — and loud only when it clears twice
7031
- * the median, a threshold stated in the sentence rather than hidden in code.
7317
+ * Loud past **four times** the median — far enough from an even
7318
+ * distribution that a bucket boundary cannot flip the message, and stated
7319
+ * in the sentence rather than hidden here. Both figures are bucket
7320
+ * ceilings, so the ratio is coarse by construction and the copy says so.
7032
7321
  */
7033
- if (report.spendByDay.length >= 2) {
7034
- const medianUsd = median(report.spendByDay.map((d) => d.usd));
7035
- const peak = report.spendByDay.reduce((a, b) => (b.usd > a.usd ? b : a));
7036
- if (medianUsd > 0) {
7037
- const ratio = (peak.usd / medianUsd).toFixed(1);
7038
- const line = t.profile.dayPeak(peak.day, formatUsd(peak.usd), ratio);
7039
- const labelClause = peak.topLabel !== null && report.byLabel.length > 1
7040
- ? ` ${t.profile.dayPeakLabel(peak.topLabel === UNLABELLED ? t.profile.unlabelled() : peak.topLabel, formatUsd(peak.topLabelUsd))}`
7041
- : '';
7042
- const loud = peak.usd > 2 * medianUsd;
7043
- const text = wrap(`${line}${labelClause}`, 74, ' ');
7044
- console.log(` ${loud ? c.yellow(text) : c.dim(text)}`);
7322
+ if (report.inputShapes.length > 0) {
7323
+ console.log();
7324
+ console.log(sectionHeading(t.profile.inputShapeHeading()));
7325
+ for (const shape of report.inputShapes.slice(0, 3)) {
7326
+ const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
7327
+ console.log();
7328
+ if (shape.medianWithinTokens === null || shape.p95WithinTokens === null || shape.p95OverMedian === null) {
7329
+ /**
7330
+ * The covering bucket is the open-ended last one, so there is no
7331
+ * ceiling to name. Said rather than skipped: a slice whose calls are
7332
+ * all above a million tokens is a finding, and silence would drop it.
7333
+ */
7334
+ console.log(` ${c.bold(wrap(t.profile.inputHuge(label, shape.modelName, t.profile.calls(shape.calls), formatUsd(shape.inputUsd)), 74, ' '))}`);
7335
+ continue;
7336
+ }
7337
+ const skewed = shape.p95OverMedian >= 4;
7338
+ const line = skewed
7339
+ ? t.profile.inputSkewed(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), shape.p95OverMedian.toFixed(1), formatUsd(shape.inputUsd))
7340
+ : t.profile.inputEven(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), formatUsd(shape.inputUsd));
7341
+ console.log(` ${c.bold(wrap(line, 74, ' '))}`);
7342
+ console.log(` ${c.dim(wrap(skewed ? t.profile.inputSkewedAdvice() : t.profile.inputEvenAdvice(), 74, ' '))}`);
7343
+ /**
7344
+ * What that size actually costs. A cache read is a tenth of input on
7345
+ * Anthropic, so a large slice reading almost everything from cache is a
7346
+ * very different bill from one paying full rate — and the token counts
7347
+ * alone cannot tell them apart.
7348
+ */
7349
+ if (shape.cachedShare >= 0.5) {
7350
+ console.log(` ${c.dim(wrap(t.profile.inputMostlyCached(pct(shape.cachedShare)), 74, ' '))}`);
7351
+ }
7352
+ else if (shape.cachedShare < 0.1) {
7353
+ console.log(` ${c.dim(wrap(t.profile.inputFullRate(), 74, ' '))}`);
7354
+ }
7045
7355
  }
7046
7356
  }
7357
+ }
7358
+ /**
7359
+ * Where the output spend concentrates.
7360
+ *
7361
+ * Output is usually most of the bill, so the shape of it is usually the actionable
7362
+ * half of the report rather than a footnote to the totals.
7363
+ */
7364
+ function reportOutputShape(report, t) {
7365
+ const n = (value) => value.toLocaleString(t.numberLocale);
7366
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7047
7367
  /**
7048
- * The shape of the day, and what it says about batching.
7049
- *
7050
- * Spend packed into the hours a country is awake is interactive traffic
7051
- * somebody is waiting on; spend spread evenly across twenty-four is
7052
- * background work — and background work is what the Batch API halves. The
7053
- * measure is exact and needs no threshold to state: the **fewest hours that
7054
- * hold 80% of the spend**. Two or three means concentrated; sixteen means
7055
- * flat.
7368
+ * Where the output spend concentrates — the actionable half of "output
7369
+ * dominates", which the headline above could only state as a total.
7056
7370
  *
7057
- * It says what the shape is and stops. Whether a workload can wait is a
7058
- * product decision Trazum cannot make from counts, so the sentence names
7059
- * the lever and never claims the saving — the batch figure the levers
7060
- * section already prints is the one with money attached.
7371
+ * Two bills with identical output spend want opposite responses. Six per cent
7372
+ * of calls holding half of it is a tail, and a tail has a cause worth a
7373
+ * morning; forty-five per cent is what evenly spread looks like, and the only
7374
+ * lever there is asking every answer to be shorter. The threshold between the
7375
+ * two is a quarter of the calls — far enough from both shapes that rounding
7376
+ * cannot flip the message, and stated here because it is a presentation choice,
7377
+ * not a measurement.
7061
7378
  */
7062
- if (report.spendByHour.length >= 4 && report.total.totalUsd > 0) {
7063
- const sorted = [...report.spendByHour].sort((a, b) => b.usd - a.usd);
7064
- let covered = 0;
7065
- let hoursForMost = 0;
7066
- for (const hour of sorted) {
7067
- covered += hour.usd;
7068
- hoursForMost += 1;
7069
- if (covered >= 0.8 * report.total.totalUsd)
7070
- break;
7379
+ if (report.outputShapes.length > 0) {
7380
+ console.log();
7381
+ console.log(sectionHeading(t.profile.outputShapeHeading()));
7382
+ for (const shape of report.outputShapes.slice(0, 3)) {
7383
+ const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
7384
+ const isTail = shape.heavyCallShare < 0.25;
7385
+ console.log();
7386
+ if (isTail) {
7387
+ console.log(` ${c.bold(wrap(t.profile.outputTail(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), n(shape.aboveTokens), formatUsd(shape.outputUsd)), 74, ' '))}`);
7388
+ console.log(` ${c.dim(wrap(t.profile.outputTailAdvice(), 74, ' '))}`);
7389
+ }
7390
+ else {
7391
+ console.log(` ${c.bold(wrap(t.profile.outputFlat(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), formatUsd(shape.outputUsd)), 74, ' '))}`);
7392
+ console.log(` ${c.dim(wrap(t.profile.outputFlatAdvice(), 74, ' '))}`);
7393
+ }
7394
+ /**
7395
+ * The ceilings a max_tokens cap actually wants, exact over the
7396
+ * histogram: every measured answer at or under the named number is
7397
+ * counted, none interpolated. Omitted when the covering bucket is the
7398
+ * open-ended last one, which has no ceiling to name honestly.
7399
+ */
7400
+ if (shape.medianWithinTokens !== null && shape.p95WithinTokens !== null) {
7401
+ console.log(` ${c.dim(wrap(t.profile.outputPercentiles(n(shape.medianWithinTokens), n(shape.p95WithinTokens)), 74, ' '))}`);
7402
+ }
7071
7403
  }
7072
- const busiest = sorted
7073
- .slice(0, hoursForMost)
7074
- .map((hour) => hour.hour)
7075
- .sort((a, b) => a - b)
7076
- .map((hour) => `${String(hour).padStart(2, '0')}:00`)
7077
- .join(', ');
7078
- console.log();
7079
- console.log(` ${c.dim(wrap(hoursForMost <= 8 ? t.profile.hoursConcentrated(n(hoursForMost), busiest) : t.profile.hoursFlat(n(hoursForMost)), 74, ' '))}`);
7080
7404
  }
7405
+ }
7406
+ /**
7407
+ * What re-sending the conversation costs.
7408
+ *
7409
+ * A chat or agent workload sends the whole conversation every turn, so the history
7410
+ * is paid for again on each call. It is one of the four levers with real money on
7411
+ * it and the one least likely to be noticed, because nothing in the bill is
7412
+ * labelled "history".
7413
+ */
7414
+ function reportConversationHistory(report, t) {
7415
+ const n = (value) => value.toLocaleString(t.numberLocale);
7416
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7081
7417
  /**
7082
- * The hit rate, and then the question the hit rate does not answer.
7418
+ * What re-sending the conversation costs — the line nothing here could see.
7083
7419
  *
7084
- * `cacheNever()` is keyed off the **verdict**, not off a null hit rate. Those
7085
- * two came apart on a log whose calls were entirely cache writes with no plain
7086
- * input: the rate is undefined there — zero reads over zero attempts — while
7087
- * caching was plainly in use, and the old branch printed "caching was never
7088
- * used" over a bill made of cache writes.
7420
+ * A chat or agent workload sends the whole conversation back on every turn, so
7421
+ * the input grows with the turn count and that growth is routinely the largest
7422
+ * item on the bill. A prompt file shows the system prompt and not the history; a
7423
+ * total shows the sum and not the shape.
7424
+ *
7425
+ * Reported as a **ceiling**, because part of the growth is the user's own new
7426
+ * messages and this reads counts rather than content, so it cannot separate the
7427
+ * two. Saying nothing because the exact split is unknowable would be worse: the
7428
+ * bound is exact, and the reader can act on it.
7089
7429
  */
7090
- const cache = cacheEconomics(report.total);
7091
- const hitRate = cacheHitRate(report.total);
7092
- if (cache.verdict === 'not-attempted') {
7093
- console.log(` ${c.dim(wrap(t.profile.cacheNever(), 74, ' '))}`);
7430
+ if (report.conversations.length > 0) {
7431
+ console.log();
7432
+ console.log(sectionHeading(t.profile.historyHeading()));
7433
+ for (const growth of report.conversations.slice(0, 3)) {
7434
+ const label = growth.label === UNLABELLED ? t.profile.unlabelled() : growth.label;
7435
+ console.log();
7436
+ console.log(` ${c.bold(wrap(t.profile.historyGrowth(label, growth.modelName, n(Math.round(growth.minTurnTokens)), n(Math.round(growth.maxTurnTokens)), n(growth.longestSession)), 74, ' '))}`);
7437
+ console.log(` ${c.dim(wrap(t.profile.historyCeiling(formatUsd(growth.growthUsd), pct(growth.shareOfBill), formatUsd(growth.flatUsd), formatUsd(growth.inputUsd)), 74, ' '))}`);
7438
+ }
7094
7439
  }
7095
- else if (hitRate !== null) {
7096
- console.log(` ${c.dim(t.profile.cacheHit(pct(hitRate)))}`);
7440
+ else if (!report.hasSessions) {
7441
+ /**
7442
+ * Not the same as "no growth". A log without a session field cannot be asked
7443
+ * the question at all, and silence there would read as a clean bill of health
7444
+ * on the line most likely to be the biggest.
7445
+ */
7446
+ console.log();
7447
+ console.log(sectionHeading(t.profile.historyHeading()));
7448
+ console.log(` ${c.dim(wrap(t.profile.historyNoSessions(), 74, ' '))}`);
7097
7449
  }
7450
+ }
7451
+ /**
7452
+ * `--what-if <model>`: these exact calls, at another model's prices.
7453
+ *
7454
+ * Priced from the tokens that were actually billed rather than from an estimate,
7455
+ * which is the only version of this question worth answering: a migration priced
7456
+ * off a guess is a forecast, and this product does not forecast.
7457
+ */
7458
+ function reportWhatIf(whatIf, report, t) {
7459
+ const n = (value) => value.toLocaleString(t.numberLocale);
7460
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7098
7461
  /**
7099
- * Whether the caching was worth doing — the one finding here that can
7100
- * contradict the advice Trazum gives everywhere else.
7101
- *
7102
- * A cache write costs 1.25x plain input on Anthropic and 2x at the one-hour
7103
- * TTL, so a prefix rebuilt faster than it is reused is billed at a premium and
7104
- * returns nothing: that workload is cheaper with caching switched off. The
7105
- * counterfactual is exact rather than a projection — caching changes the
7106
- * multiplier on a token, never the token — so this is the one place in `profile`
7107
- * where a comparison against what-might-have-been is arithmetic instead of a
7108
- * guess about a prompt nobody wrote.
7109
- */
7110
- /**
7111
- * The losing labels, **ranked by what caching cost them** and not by bill size.
7112
- *
7113
- * `byLabel` arrives sorted by total spend, which is the right order for the
7114
- * table above and the wrong one here: the worst cache in an estate usually sits
7115
- * on a small workload, so taking the first three off a spend-ordered list meant
7116
- * the biggest loser could be the one that went unnamed.
7117
- */
7118
- const lostLabels = report.byLabel
7119
- .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
7120
- .filter((r) => r.cache.verdict === 'lost-money')
7121
- .sort((a, b) => b.cache.deltaUsd - a.cache.deltaUsd);
7122
- const NAMED = 3;
7123
- const nameOf = (row) => row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7124
- /**
7125
- * The names, with the ones that did not fit **counted rather than dropped**.
7462
+ * `--what-if <model>`: these exact calls, at another model's rates.
7126
7463
  *
7127
- * The first version sliced to three silently while the money beside it was
7128
- * summed over every loser — so four bleeding labels printed three names and a
7129
- * figure that charged them with a fourth label's loss. Truncating is fine;
7130
- * truncating without saying so is the flattering omission this repository keeps
7131
- * catching itself at, and `reportProfileGaps` already had the pattern.
7132
- */
7133
- const listNames = (rows) => {
7134
- const names = rows.slice(0, NAMED).map((r) => nameOf(r.row)).join(', ');
7135
- return rows.length <= NAMED
7136
- ? names
7137
- : `${names} ${t.profile.andMoreLabels(rows.length - NAMED)}`;
7138
- };
7139
- const namedLosers = listNames(lostLabels);
7140
- const bleeding = lostLabels.reduce((sum, r) => sum + r.cache.deltaUsd, 0);
7141
- /**
7142
- * Whether the log can settle the question at all.
7464
+ * The levers above pick their own candidate; this answers the question the
7465
+ * reader arrived with. It is multiplication, not advice, and every part of
7466
+ * this section is built so it cannot be read as advice:
7143
7467
  *
7144
- * Decided before anything prints, because it governs whether the confident
7145
- * sentence prints — not merely whether a caveat follows it. The first attempt
7146
- * added the caveat and left the assertion above it, so the reader met `Caching
7147
- * took $0.1000 off this bill` and only afterwards learned it might be a $3.65
7148
- * loss. A finding a later line retracts is still a finding somebody acted on.
7468
+ * - the caveat line prints **before** the figure, not after it;
7469
+ * - calls the target's context window could not have accepted are named as
7470
+ * impossible rather than priced as cheap, and their money is in none of
7471
+ * the totals;
7472
+ * - spend already on the target is stated separately, because a difference
7473
+ * computed over money that cannot move is a percentage of the wrong
7474
+ * denominator.
7149
7475
  */
7150
- const unsettled = cache.worstCaseVerdict !== cache.verdict && report.total.assumedWriteTtlCalls > 0;
7151
- if (unsettled) {
7152
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheTtlUnsettled(report.total.assumedWriteTtlCalls, formatUsd(-cache.deltaUsd), formatUsd(cache.worstCaseDeltaUsd)), 74, ' '))}`);
7153
- }
7154
- else if (cache.verdict === 'lost-money') {
7155
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheLost(formatUsd(cache.deltaUsd), n(report.total.cacheWriteTokens), n(report.total.cacheReadTokens)), 74, ' '))}`);
7156
- // Only when it narrows the search. One label is the total again, said twice.
7157
- if (lostLabels.length > 0 && report.byLabel.length > 1) {
7158
- console.log(` ${c.dim(wrap(t.profile.cacheLostBy(namedLosers), 74, ' '))}`);
7476
+ if (whatIf !== null) {
7477
+ console.log();
7478
+ console.log(sectionHeading(t.profile.whatIfHeading(whatIf.target.displayName)));
7479
+ console.log(` ${c.dim(wrap(t.profile.whatIfAssumption(), 74, ' '))}`);
7480
+ console.log();
7481
+ if (whatIf.slices.length === 0) {
7482
+ console.log(` ${c.dim(wrap(t.profile.whatIfNothingToMove(), 74, ' '))}`);
7159
7483
  }
7160
- }
7161
- else {
7162
- if (cache.verdict === 'paid-off') {
7163
- console.log(` ${c.dim(wrap(t.profile.cachePaidOff(formatUsd(-cache.deltaUsd)), 74, ' '))}`);
7484
+ else {
7485
+ const cheaper = whatIf.deltaUsd < 0;
7486
+ const line = t.profile.whatIfTotal(formatUsd(whatIf.currentUsd), formatUsd(whatIf.targetUsd), formatUsd(Math.abs(whatIf.deltaUsd)));
7487
+ console.log(` ${cheaper ? c.green('→') : c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`);
7488
+ console.log(` ${c.dim(wrap(cheaper ? t.profile.whatIfCheaper() : t.profile.whatIfDearer(), 74, ' '))}`);
7489
+ /**
7490
+ * The other half of the whole decision: the same move with the target's
7491
+ * Batch API on top. Computed against the target's rates, never by
7492
+ * adding two savings, and hedged the only honest way — whether these
7493
+ * calls can wait is not in the log.
7494
+ */
7495
+ if (whatIf.batchOnTarget !== null) {
7496
+ console.log(` ${c.dim(wrap(t.profile.whatIfBatchOnTarget(formatUsd(whatIf.batchOnTarget.targetUsd), formatUsd(whatIf.targetUsd)), 74, ' '))}`);
7497
+ }
7498
+ for (const slice of whatIf.slices.slice(0, 5)) {
7499
+ const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7500
+ console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.whatIfSlice(label, slice.model, formatUsd(slice.currentUsd), formatUsd(slice.targetUsd)), 74, ' '))}`);
7501
+ /**
7502
+ * Cache traffic the target could not grant, said loudly and beside
7503
+ * the figure it corrects. The standard row prices cache entries the
7504
+ * target's minimum would refuse to create — an error that flatters
7505
+ * the move, which is the direction this repository refuses.
7506
+ */
7507
+ if (slice.cacheBeyondTarget !== null) {
7508
+ console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.whatIfCacheBeyond(n(slice.maxCallInputTokens), n(slice.cacheBeyondTarget.minTokens), formatUsd(slice.cacheBeyondTarget.noCacheUsd)), 74, ' '))}`);
7509
+ }
7510
+ }
7164
7511
  }
7165
- else if (cache.verdict === 'no-difference') {
7166
- console.log(` ${c.dim(wrap(t.profile.cacheNoDifference(), 74, ' '))}`);
7512
+ /**
7513
+ * The refusal, and it is loud. A call larger than the target's window is
7514
+ * not a cheaper call, and a comparison that priced it anyway would report
7515
+ * a saving for traffic that would have failed outright.
7516
+ */
7517
+ for (const slice of whatIf.overContext.slice(0, 3)) {
7518
+ const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7519
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.whatIfOverContext(label, n(slice.maxCallInputTokens), n(whatIf.target.contextWindow), formatUsd(slice.currentUsd)), 74, ' '))}`);
7520
+ }
7521
+ // Money that is already there cannot move, and leaving it out of the
7522
+ // totals above is only honest if the reader is told it exists.
7523
+ if (whatIf.alreadyOnTarget.calls > 0) {
7524
+ console.log(` ${c.dim(wrap(t.profile.whatIfAlreadyThere(t.profile.calls(whatIf.alreadyOnTarget.calls), formatUsd(whatIf.alreadyOnTarget.usd)), 74, ' '))}`);
7525
+ }
7526
+ // Models with no current price have no difference to state — their target
7527
+ // cost is knowable and the subtraction is not.
7528
+ if (whatIf.unpricedCalls > 0) {
7529
+ console.log(` ${c.dim(wrap(t.profile.whatIfUnpriced(t.profile.calls(whatIf.unpricedCalls), whatIf.unpricedModels.join(', ')), 74, ' '))}`);
7167
7530
  }
7168
7531
  }
7532
+ }
7533
+ /**
7534
+ * The section this command exists for: what would actually move this bill.
7535
+ *
7536
+ * Shortening the prompt is the smallest line item there is. Which model a call goes
7537
+ * to, the Batch API, caching and re-sent conversation history are the levers with
7538
+ * real money on them, and all four are priced here from what the provider charged
7539
+ * rather than from what a file would cost.
7540
+ */
7541
+ function reportLevers(report, pricing, t) {
7542
+ const n = (value) => value.toLocaleString(t.numberLocale);
7543
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7169
7544
  /**
7170
- * A workload bleeding underneath a total that does not report a loss.
7545
+ * The section this command is for, and the answer to the fairest complaint the
7546
+ * product has had: on a bill of twenty thousand, the rules recover two hundred.
7171
7547
  *
7172
- * The case the aggregate is actively hiding, so it prints as a warning: a cache
7173
- * paying for itself on one label and losing on another nets out to a comfortable
7174
- * number, and nothing else on screen would say otherwise.
7548
+ * That figure is right — measured, three tokens out of three hundred and six on
7549
+ * an ordinary support prompt. The conclusion is not that the tool is worthless
7550
+ * but that it had been looking at the smallest line item. Which model a call
7551
+ * goes to moves 60% to 80%. The Batch API moves 50% flat. Both are priced here
7552
+ * from the reader's own tokens, at published rates, with no modelling in
7553
+ * between — and printed above the breakdowns, because a lever nobody scrolls to
7554
+ * is a lever nobody pulls.
7175
7555
  *
7176
- * The sentence deliberately does not restate the total's verdict. It used to
7177
- * open "Caching pays off overall", which this position cannot claim — it also
7178
- * runs under `no-difference`, where the line immediately above has just said the
7179
- * opposite, and under `unsettled`, where there is no verdict to report at all.
7556
+ * The ceiling on prompt shortening prints underneath them on purpose. A 1% win
7557
+ * reported without saying 1% of what is not information, and this repository
7558
+ * would rather say the uncomfortable number itself than let somebody else
7559
+ * discover it.
7180
7560
  */
7181
- if (lostLabels.length > 0 && cache.verdict !== 'lost-money') {
7182
- console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.cacheLostHidden(formatUsd(bleeding), namedLosers), 74, ' '))}`);
7183
- }
7561
+ const levers = billLevers(report, { catalogue: pricing });
7562
+ console.log();
7563
+ console.log(sectionHeading(t.profile.leversHeading()));
7184
7564
  /**
7185
- * A label that loses money only if its unstated TTL was the long one.
7565
+ * Every lever below describes a mixture when nothing carries a label.
7186
7566
  *
7187
- * The same ambiguity one level down, and it hides better here: a total whose
7188
- * TTLs are mostly recorded reads as settled while one workload inside it is
7189
- * entirely unstated. Listed apart from the confirmed losers because it is a
7190
- * different claim — this one is conditional, and merging the two would make
7191
- * every name in either list mean less.
7567
+ * A 2,000-call classifier and a 400-call RAG pipeline merge into one slice, and
7568
+ * the section then offers a single route for two workloads that need different
7569
+ * answers — and `trazum route` would measure one prompt against a figure
7570
+ * covering both. The session case already tells the reader to add the field;
7571
+ * this one named the row `unlabelled` and said nothing, as though that were a
7572
+ * workload.
7192
7573
  */
7193
- const maybeLostLabels = report.byLabel
7194
- .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
7195
- .filter((r) => r.cache.verdict !== 'lost-money' && r.cache.worstCaseVerdict === 'lost-money');
7196
- if (maybeLostLabels.length > 0) {
7197
- console.log(` ${c.dim(wrap(t.profile.cacheTtlUnsettledLabels(listNames(maybeLostLabels)), 74, ' '))}`);
7574
+ const unlabelledOnly = report.byLabel.length === 1 && report.byLabel[0].label === UNLABELLED;
7575
+ if (unlabelledOnly && levers.slices.length > 0) {
7576
+ console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.leversUnlabelled(), 74, ' '))}`);
7577
+ }
7578
+ if (levers.slices.length === 0) {
7579
+ console.log(` ${c.dim(wrap(t.profile.leversNone(), 74, ' '))}`);
7580
+ }
7581
+ else {
7582
+ for (const slice of levers.slices.slice(0, 5)) {
7583
+ const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7584
+ console.log();
7585
+ /**
7586
+ * The headline is the **combined** figure, and the options underneath are
7587
+ * the ways to reach it — not rows to add up. Batching a routed call
7588
+ * discounts the cheaper model's price, so listing them separately printed
7589
+ * $12.60 and $10.50 against a slice that had spent $21.00: a saving larger
7590
+ * than the bill it came from, in the flattering direction.
7591
+ */
7592
+ console.log(` ${c.green('→')} ${c.bold(wrap(t.profile.leverSlice(label, slice.modelName, formatUsd(slice.combinedUsd), pct(slice.shareOfBill)), 74, ' '))}`);
7593
+ console.log(` ${c.dim(t.profile.leverCalls(t.profile.calls(slice.calls), formatUsd(slice.spentUsd)))}`);
7594
+ if (slice.route) {
7595
+ console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.leverRoute(slice.route.candidate.displayName, formatUsd(slice.route.savingUsd)), 74, ' '))}`);
7596
+ }
7597
+ if (slice.batch) {
7598
+ console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.leverBatch(formatUsd(slice.batch.savingUsd)), 74, ' '))}`);
7599
+ }
7600
+ // The arithmetic is exact and the quality question is untouched by it.
7601
+ // Naming the command is the difference between a saving and a gamble.
7602
+ if (slice.route) {
7603
+ console.log(` ${c.dim(wrap(t.profile.leverRouteVerify(slice.route.candidate.id), 74, ' '))}`);
7604
+ }
7605
+ }
7198
7606
  }
7607
+ console.log();
7608
+ console.log(` ${c.dim(wrap(t.profile.leverPromptCeiling(formatUsd(levers.promptCeilingUsd), pct(levers.promptCeilingShare)), 74, ' '))}`);
7609
+ }
7610
+ /**
7611
+ * What the labels, the budgets and the cache TTLs say about this bill.
7612
+ *
7613
+ * Why a label's caching is failing, read from the prompt file itself: the log
7614
+ * carries counts, so `profile` can say *that* caching loses money on a label and
7615
+ * nothing more, and `labels` in the config maps a label to the file it sends.
7616
+ * Every sentence carries "as it is today", because the file is whatever the
7617
+ * repository holds now and may not be what produced the log.
7618
+ *
7619
+ * Then the budgets, the TTL fits, the single-turn writes and the shape of the
7620
+ * sessions: two hundred lines of one topic, what the configuration and the
7621
+ * conversation did to the money.
7622
+ */
7623
+ async function reportLabelsBudgetsAndCache(report, config, pricing, t) {
7624
+ const n = (value) => value.toLocaleString(t.numberLocale);
7625
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7199
7626
  /**
7200
7627
  * Why, read from the prompt file itself — the loop `profile` could not close.
7201
7628
  *
@@ -7389,664 +7816,794 @@ async function commandProfile(args, config, configDir, pricing, t) {
7389
7816
  if (report.total.assumedWriteTtlCalls > 0) {
7390
7817
  console.log(` ${c.dim(wrap(t.profile.assumedWriteTtl(report.total.assumedWriteTtlCalls), 74, ' '))}`);
7391
7818
  }
7819
+ }
7820
+ /**
7821
+ * What caching did to this bill, and what it is about to do.
7822
+ *
7823
+ * The hit rate, the money the cache made or lost, the labels bleeding on it, and
7824
+ * the TTL question the hit rate cannot answer. One topic, and it needs the report
7825
+ * and the messages: it was a hundred and thirty lines inside a function with
7826
+ * twenty-three values in scope, and the only way to learn it used two of them was
7827
+ * to read it.
7828
+ */
7829
+ function reportCacheVerdict(report, t) {
7830
+ const n = (value) => value.toLocaleString(t.numberLocale);
7831
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7392
7832
  /**
7393
- * The section this command is for, and the answer to the fairest complaint the
7394
- * product has had: on a bill of twenty thousand, the rules recover two hundred.
7833
+ * The hit rate, and then the question the hit rate does not answer.
7395
7834
  *
7396
- * That figure is right — measured, three tokens out of three hundred and six on
7397
- * an ordinary support prompt. The conclusion is not that the tool is worthless
7398
- * but that it had been looking at the smallest line item. Which model a call
7399
- * goes to moves 40% to 80%. The Batch API moves 50% flat. Both are priced here
7400
- * from the reader's own tokens, at published rates, with no modelling in
7401
- * between — and printed above the breakdowns, because a lever nobody scrolls to
7402
- * is a lever nobody pulls.
7835
+ * `cacheNever()` is keyed off the **verdict**, not off a null hit rate. Those
7836
+ * two came apart on a log whose calls were entirely cache writes with no plain
7837
+ * input: the rate is undefined there — zero reads over zero attempts — while
7838
+ * caching was plainly in use, and the old branch printed "caching was never
7839
+ * used" over a bill made of cache writes.
7840
+ */
7841
+ const cache = cacheEconomics(report.total);
7842
+ const hitRate = cacheHitRate(report.total);
7843
+ if (cache.verdict === 'not-attempted') {
7844
+ console.log(` ${c.dim(wrap(t.profile.cacheNever(), 74, ' '))}`);
7845
+ }
7846
+ else if (hitRate !== null) {
7847
+ console.log(` ${c.dim(t.profile.cacheHit(pct(hitRate)))}`);
7848
+ }
7849
+ /**
7850
+ * Whether the caching was worth doing — the one finding here that can
7851
+ * contradict the advice Trazum gives everywhere else.
7403
7852
  *
7404
- * The ceiling on prompt shortening prints underneath them on purpose. A 1% win
7405
- * reported without saying 1% of what is not information, and this repository
7406
- * would rather say the uncomfortable number itself than let somebody else
7407
- * discover it.
7853
+ * A cache write costs 1.25x plain input on Anthropic and 2x at the one-hour
7854
+ * TTL, so a prefix rebuilt faster than it is reused is billed at a premium and
7855
+ * returns nothing: that workload is cheaper with caching switched off. The
7856
+ * counterfactual is exact rather than a projection — caching changes the
7857
+ * multiplier on a token, never the token — so this is the one place in `profile`
7858
+ * where a comparison against what-might-have-been is arithmetic instead of a
7859
+ * guess about a prompt nobody wrote.
7408
7860
  */
7409
- const levers = billLevers(report, { catalogue: pricing });
7410
- console.log();
7411
- console.log(sectionHeading(t.profile.leversHeading()));
7412
7861
  /**
7413
- * Every lever below describes a mixture when nothing carries a label.
7862
+ * The losing labels, **ranked by what caching cost them** and not by bill size.
7414
7863
  *
7415
- * A 2,000-call classifier and a 400-call RAG pipeline merge into one slice, and
7416
- * the section then offers a single route for two workloads that need different
7417
- * answers — and `trazum route` would measure one prompt against a figure
7418
- * covering both. The session case already tells the reader to add the field;
7419
- * this one named the row `unlabelled` and said nothing, as though that were a
7420
- * workload.
7864
+ * `byLabel` arrives sorted by total spend, which is the right order for the
7865
+ * table above and the wrong one here: the worst cache in an estate usually sits
7866
+ * on a small workload, so taking the first three off a spend-ordered list meant
7867
+ * the biggest loser could be the one that went unnamed.
7421
7868
  */
7422
- const unlabelledOnly = report.byLabel.length === 1 && report.byLabel[0].label === UNLABELLED;
7423
- if (unlabelledOnly && levers.slices.length > 0) {
7424
- console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.leversUnlabelled(), 74, ' '))}`);
7869
+ const lostLabels = report.byLabel
7870
+ .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
7871
+ .filter((r) => r.cache.verdict === 'lost-money')
7872
+ .sort((a, b) => b.cache.deltaUsd - a.cache.deltaUsd);
7873
+ const NAMED = 3;
7874
+ const nameOf = (row) => row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7875
+ /**
7876
+ * The names, with the ones that did not fit **counted rather than dropped**.
7877
+ *
7878
+ * The first version sliced to three silently while the money beside it was
7879
+ * summed over every loser — so four bleeding labels printed three names and a
7880
+ * figure that charged them with a fourth label's loss. Truncating is fine;
7881
+ * truncating without saying so is the flattering omission this repository keeps
7882
+ * catching itself at, and `reportProfileGaps` already had the pattern.
7883
+ */
7884
+ const listNames = (rows) => {
7885
+ const names = rows.slice(0, NAMED).map((r) => nameOf(r.row)).join(', ');
7886
+ return rows.length <= NAMED
7887
+ ? names
7888
+ : `${names} ${t.profile.andMoreLabels(rows.length - NAMED)}`;
7889
+ };
7890
+ const namedLosers = listNames(lostLabels);
7891
+ const bleeding = lostLabels.reduce((sum, r) => sum + r.cache.deltaUsd, 0);
7892
+ /**
7893
+ * Whether the log can settle the question at all.
7894
+ *
7895
+ * Decided before anything prints, because it governs whether the confident
7896
+ * sentence prints — not merely whether a caveat follows it. The first attempt
7897
+ * added the caveat and left the assertion above it, so the reader met `Caching
7898
+ * took $0.1000 off this bill` and only afterwards learned it might be a $3.65
7899
+ * loss. A finding a later line retracts is still a finding somebody acted on.
7900
+ */
7901
+ const unsettled = cache.worstCaseVerdict !== cache.verdict && report.total.assumedWriteTtlCalls > 0;
7902
+ if (unsettled) {
7903
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheTtlUnsettled(report.total.assumedWriteTtlCalls, formatUsd(-cache.deltaUsd), formatUsd(cache.worstCaseDeltaUsd)), 74, ' '))}`);
7904
+ }
7905
+ else if (cache.verdict === 'lost-money') {
7906
+ console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheLost(formatUsd(cache.deltaUsd), n(report.total.cacheWriteTokens), n(report.total.cacheReadTokens)), 74, ' '))}`);
7907
+ // Only when it narrows the search. One label is the total again, said twice.
7908
+ if (lostLabels.length > 0 && report.byLabel.length > 1) {
7909
+ console.log(` ${c.dim(wrap(t.profile.cacheLostBy(namedLosers), 74, ' '))}`);
7910
+ }
7911
+ }
7912
+ else {
7913
+ if (cache.verdict === 'paid-off') {
7914
+ console.log(` ${c.dim(wrap(t.profile.cachePaidOff(formatUsd(-cache.deltaUsd)), 74, ' '))}`);
7915
+ }
7916
+ else if (cache.verdict === 'no-difference') {
7917
+ console.log(` ${c.dim(wrap(t.profile.cacheNoDifference(), 74, ' '))}`);
7918
+ }
7919
+ }
7920
+ /**
7921
+ * A workload bleeding underneath a total that does not report a loss.
7922
+ *
7923
+ * The case the aggregate is actively hiding, so it prints as a warning: a cache
7924
+ * paying for itself on one label and losing on another nets out to a comfortable
7925
+ * number, and nothing else on screen would say otherwise.
7926
+ *
7927
+ * The sentence deliberately does not restate the total's verdict. It used to
7928
+ * open "Caching pays off overall", which this position cannot claim — it also
7929
+ * runs under `no-difference`, where the line immediately above has just said the
7930
+ * opposite, and under `unsettled`, where there is no verdict to report at all.
7931
+ */
7932
+ if (lostLabels.length > 0 && cache.verdict !== 'lost-money') {
7933
+ console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.cacheLostHidden(formatUsd(bleeding), namedLosers), 74, ' '))}`);
7934
+ }
7935
+ /**
7936
+ * A label that loses money only if its unstated TTL was the long one.
7937
+ *
7938
+ * The same ambiguity one level down, and it hides better here: a total whose
7939
+ * TTLs are mostly recorded reads as settled while one workload inside it is
7940
+ * entirely unstated. Listed apart from the confirmed losers because it is a
7941
+ * different claim — this one is conditional, and merging the two would make
7942
+ * every name in either list mean less.
7943
+ */
7944
+ const maybeLostLabels = report.byLabel
7945
+ .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
7946
+ .filter((r) => r.cache.verdict !== 'lost-money' && r.cache.worstCaseVerdict === 'lost-money');
7947
+ if (maybeLostLabels.length > 0) {
7948
+ console.log(` ${c.dim(wrap(t.profile.cacheTtlUnsettledLabels(listNames(maybeLostLabels)), 74, ' '))}`);
7949
+ }
7950
+ }
7951
+ /**
7952
+ * `trazum plan <log>` — not a list of findings, a ranked plan of what to do.
7953
+ *
7954
+ * The composition (route and batch on one slice never summed) happens in
7955
+ * core's `buildPlan`; this command owns the I/O and the rendering. The plan
7956
+ * saves as a dated JSON file on request, which is what makes verifying it
7957
+ * against a later log possible at all — a prediction nobody wrote down is a
7958
+ * prediction nobody can be held to.
7959
+ */
7960
+ async function commandPlan(args, pricing, t) {
7961
+ const path = args.positional[0];
7962
+ if (path === undefined)
7963
+ throw new Error(t.plan.noTarget());
7964
+ const GZ = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
7965
+ const READABLE = [...LOG_EXTENSIONS, ...GZ];
7966
+ const target = await stat(path).catch(() => null);
7967
+ let files = [path];
7968
+ if (target?.isDirectory()) {
7969
+ const entries = await readdir(path, { withFileTypes: true });
7970
+ files = entries
7971
+ .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
7972
+ .map((entry) => join(path, entry.name))
7973
+ .sort((a, b) => a.localeCompare(b));
7974
+ if (files.length === 0)
7975
+ throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
7976
+ }
7977
+ const texts = await Promise.all(files.map((file) => readUsageLog(file, t)));
7978
+ const raw = texts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
7979
+ const report = profileUsage(raw, { catalogue: pricing });
7980
+ if (report.total.calls === 0)
7981
+ throw new Error(t.plan.nothingPriced());
7982
+ const levers = billLevers(report, { catalogue: pricing });
7983
+ const plan = buildPlan(report, levers, pricing.lastReviewed);
7984
+ const minUsd = typeof args.flags.get('min-usd') === 'string' ? numberFlag(args, 'min-usd', 0, t) : 0;
7985
+ const actions = plan.actions.filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) >= minUsd);
7986
+ const filtered = plan.actions.length - actions.length;
7987
+ const droppedUsd = plan.actions
7988
+ .filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) < minUsd)
7989
+ .reduce((sum, a) => sum + (a.savingUsd ?? a.stakeUsd ?? 0), 0);
7990
+ const n = (value) => value.toLocaleString(t.numberLocale);
7991
+ /**
7992
+ * The document's totals cover the actions the document holds — a filtered
7993
+ * plan whose totals still counted the filtered actions would be a file
7994
+ * that contradicts itself, and 1.39's verify would hold it to money it
7995
+ * cannot see. What --min-usd dropped is stated with its worth, never
7996
+ * silently.
7997
+ */
7998
+ const stamped = {
7999
+ ...plan,
8000
+ actions,
8001
+ projectedSavingUsd: actions.reduce((sum, a) => sum + (a.savingUsd ?? 0), 0),
8002
+ measuredStakeUsd: actions.reduce((sum, a) => sum + (a.stakeUsd ?? 0), 0),
8003
+ createdAt: new Date().toISOString(),
8004
+ };
8005
+ const outPath = stringFlag(args, 'out');
8006
+ if (outPath !== undefined) {
8007
+ await writeFile(outPath, `${JSON.stringify(stamped, null, 2)}\n`);
8008
+ }
8009
+ await writeMarkdown(args, () => {
8010
+ const lines = [];
8011
+ lines.push(`## ${t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))}`);
8012
+ lines.push('');
8013
+ lines.push(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)));
8014
+ if (plan.span === null) {
8015
+ lines.push('');
8016
+ lines.push(`_${t.plan.noClock()}_`);
8017
+ }
8018
+ for (const action of actions) {
8019
+ const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
8020
+ const money = action.savingUsd !== null
8021
+ ? t.plan.projected(formatUsd(action.savingUsd))
8022
+ : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
8023
+ lines.push('');
8024
+ lines.push(`### ${t.plan.action(action.kind, name, action.model)} — ${money}`);
8025
+ if (action.detail.routeTo !== undefined)
8026
+ lines.push(`- ${t.plan.routeTo(action.detail.routeTo.displayName)}`);
8027
+ for (const assumption of action.assumes)
8028
+ lines.push(`- ${t.plan.assume(assumption)}`);
8029
+ if (action.check !== null)
8030
+ lines.push(`- ${t.plan.check(action.check)}`);
8031
+ }
8032
+ if (filtered > 0) {
8033
+ lines.push('');
8034
+ lines.push(`_${t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd))}_`);
8035
+ }
8036
+ lines.push('');
8037
+ lines.push(`_${t.plan.footer()}_`);
8038
+ return lines.join('\n');
8039
+ });
8040
+ if (boolFlag(args, 'json')) {
8041
+ console.log(JSON.stringify(stamped, null, 2));
8042
+ return;
7425
8043
  }
7426
- if (levers.slices.length === 0) {
7427
- console.log(` ${c.dim(wrap(t.profile.leversNone(), 74, ' '))}`);
8044
+ console.log(sectionHeading(t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))));
8045
+ console.log(` ${wrap(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)), 74, ' ')}`);
8046
+ if (plan.span === null) {
8047
+ console.log(` ${c.dim(wrap(t.plan.noClock(), 74, ' '))}`);
7428
8048
  }
7429
- else {
7430
- for (const slice of levers.slices.slice(0, 5)) {
7431
- const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7432
- console.log();
7433
- /**
7434
- * The headline is the **combined** figure, and the options underneath are
7435
- * the ways to reach it — not rows to add up. Batching a routed call
7436
- * discounts the cheaper model's price, so listing them separately printed
7437
- * $12.60 and $10.50 against a slice that had spent $21.00: a saving larger
7438
- * than the bill it came from, in the flattering direction.
7439
- */
7440
- console.log(` ${c.green('→')} ${c.bold(wrap(t.profile.leverSlice(label, slice.modelName, formatUsd(slice.combinedUsd), pct(slice.shareOfBill)), 74, ' '))}`);
7441
- console.log(` ${c.dim(t.profile.leverCalls(t.profile.calls(slice.calls), formatUsd(slice.spentUsd)))}`);
7442
- if (slice.route) {
7443
- console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.leverRoute(slice.route.candidate.displayName, formatUsd(slice.route.savingUsd)), 74, ' '))}`);
7444
- }
7445
- if (slice.batch) {
7446
- console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.leverBatch(formatUsd(slice.batch.savingUsd)), 74, ' '))}`);
7447
- }
7448
- // The arithmetic is exact and the quality question is untouched by it.
7449
- // Naming the command is the difference between a saving and a gamble.
7450
- if (slice.route) {
7451
- console.log(` ${c.dim(wrap(t.profile.leverRouteVerify(slice.route.candidate.id), 74, ' '))}`);
7452
- }
8049
+ for (const action of actions) {
8050
+ const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
8051
+ const money = action.savingUsd !== null
8052
+ ? t.plan.projected(formatUsd(action.savingUsd))
8053
+ : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
8054
+ console.log();
8055
+ console.log(` ${c.green('→')} ${c.bold(t.plan.action(action.kind, name, action.model))} ${money}`);
8056
+ if (action.detail.routeTo !== undefined) {
8057
+ console.log(` ${c.dim(t.plan.routeTo(action.detail.routeTo.displayName))}`);
8058
+ }
8059
+ for (const assumption of action.assumes) {
8060
+ console.log(` ${c.yellow('?')} ${c.dim(wrap(t.plan.assume(assumption), 72, ' '))}`);
8061
+ }
8062
+ if (action.check !== null) {
8063
+ console.log(` ${c.dim(wrap(t.plan.check(action.check), 72, ' '))}`);
7453
8064
  }
7454
8065
  }
8066
+ if (filtered > 0) {
8067
+ console.log();
8068
+ console.log(` ${c.dim(wrap(t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd)), 74, ' '))}`);
8069
+ }
7455
8070
  console.log();
7456
- console.log(` ${c.dim(wrap(t.profile.leverPromptCeiling(formatUsd(levers.promptCeilingUsd), pct(levers.promptCeilingShare)), 74, ' '))}`);
8071
+ console.log(` ${c.dim(wrap(t.plan.footer(), 74, ' '))}`);
8072
+ if (outPath !== undefined)
8073
+ console.log(c.dim(wrap(t.plan.wrote(outPath), 74, '')));
8074
+ }
8075
+ async function commandProfile(args, config, configDir, pricing, t) {
8076
+ const path = args.positional[0];
8077
+ if (path === undefined) {
8078
+ console.log();
8079
+ console.log(c.dim(wrap(t.profile.noTarget(), 74, ' ')));
8080
+ console.log();
8081
+ return;
8082
+ }
7457
8083
  /**
7458
- * `--what-if <model>`: these exact calls, at another model's rates.
8084
+ * A log, or a directory of them.
7459
8085
  *
7460
- * The levers above pick their own candidate; this answers the question the
7461
- * reader arrived with. It is multiplication, not advice, and every part of
7462
- * this section is built so it cannot be read as advice:
8086
+ * Usage logs rotate: `logs/2026-08-01.jsonl`, `logs/2026-08-02.jsonl`, one
8087
+ * per day for a month. Making somebody `cat` them together before a profile
8088
+ * will read them is a setup cost that gets a tool skipped, and doing it for
8089
+ * them is a directory listing.
7463
8090
  *
7464
- * - the caveat line prints **before** the figure, not after it;
7465
- * - calls the target's context window could not have accepted are named as
7466
- * impossible rather than priced as cheap, and their money is in none of
7467
- * the totals;
7468
- * - spend already on the target is stated separately, because a difference
7469
- * computed over money that cannot move is a percentage of the wrong
7470
- * denominator.
8091
+ * Files are read in name order — which for dated names is time order — and
8092
+ * how many were read is stated, because a report over "the logs" that
8093
+ * silently skipped one is a total that is wrong by an unknown amount. A
8094
+ * directory holding nothing readable is an error naming what it looked for,
8095
+ * not an empty report.
7471
8096
  */
7472
- if (whatIf !== null) {
7473
- console.log();
7474
- console.log(sectionHeading(t.profile.whatIfHeading(whatIf.target.displayName)));
7475
- console.log(` ${c.dim(wrap(t.profile.whatIfAssumption(), 74, ' '))}`);
7476
- console.log();
7477
- if (whatIf.slices.length === 0) {
7478
- console.log(` ${c.dim(wrap(t.profile.whatIfNothingToMove(), 74, ' '))}`);
7479
- }
7480
- else {
7481
- const cheaper = whatIf.deltaUsd < 0;
7482
- const line = t.profile.whatIfTotal(formatUsd(whatIf.currentUsd), formatUsd(whatIf.targetUsd), formatUsd(Math.abs(whatIf.deltaUsd)));
7483
- console.log(` ${cheaper ? c.green('→') : c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`);
7484
- console.log(` ${c.dim(wrap(cheaper ? t.profile.whatIfCheaper() : t.profile.whatIfDearer(), 74, ' '))}`);
7485
- /**
7486
- * The other half of the whole decision: the same move with the target's
7487
- * Batch API on top. Computed against the target's rates, never by
7488
- * adding two savings, and hedged the only honest way — whether these
7489
- * calls can wait is not in the log.
7490
- */
7491
- if (whatIf.batchOnTarget !== null) {
7492
- console.log(` ${c.dim(wrap(t.profile.whatIfBatchOnTarget(formatUsd(whatIf.batchOnTarget.targetUsd), formatUsd(whatIf.targetUsd)), 74, ' '))}`);
7493
- }
7494
- for (const slice of whatIf.slices.slice(0, 5)) {
7495
- const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7496
- console.log(` ${c.dim('·')} ${c.dim(wrap(t.profile.whatIfSlice(label, slice.model, formatUsd(slice.currentUsd), formatUsd(slice.targetUsd)), 74, ' '))}`);
7497
- /**
7498
- * Cache traffic the target could not grant, said loudly and beside
7499
- * the figure it corrects. The standard row prices cache entries the
7500
- * target's minimum would refuse to create — an error that flatters
7501
- * the move, which is the direction this repository refuses.
7502
- */
7503
- if (slice.cacheBeyondTarget !== null) {
7504
- console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.whatIfCacheBeyond(n(slice.maxCallInputTokens), n(slice.cacheBeyondTarget.minTokens), formatUsd(slice.cacheBeyondTarget.noCacheUsd)), 74, ' '))}`);
7505
- }
7506
- }
7507
- }
8097
+ /**
8098
+ * The same names, gzipped — which is what a rotated log actually looks like
8099
+ * a day after it rotates.
8100
+ *
8101
+ * `logrotate`, Docker's json-file driver and every cloud log export compress
8102
+ * yesterday's file, so a directory of a month's logs is one plain file and
8103
+ * twenty-nine `.gz` ones. Reading only the plain one and saying nothing
8104
+ * would report a month's bill from a day of it, in the flattering
8105
+ * direction, which is exactly the failure directory mode was added to
8106
+ * prevent.
8107
+ */
8108
+ const GZ_EXTENSIONS = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
8109
+ const READABLE = [...LOG_EXTENSIONS, ...GZ_EXTENSIONS];
8110
+ const target = await stat(path).catch(() => null);
8111
+ let logFiles = [path];
8112
+ if (target?.isDirectory()) {
7508
8113
  /**
7509
- * The refusal, and it is loud. A call larger than the target's window is
7510
- * not a cheaper call, and a comparison that priced it anyway would report
7511
- * a saving for traffic that would have failed outright.
8114
+ * Recursive under `--by-source`, flat otherwise. The fleet's whole point
8115
+ * is one directory per service, so the walk must descend; the flat mode
8116
+ * keeps its long-standing behaviour because a directory of rotated logs
8117
+ * with an unrelated subfolder should not quietly absorb it.
7512
8118
  */
7513
- for (const slice of whatIf.overContext.slice(0, 3)) {
7514
- const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
7515
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.whatIfOverContext(label, n(slice.maxCallInputTokens), n(whatIf.target.contextWindow), formatUsd(slice.currentUsd)), 74, ' '))}`);
7516
- }
7517
- // Money that is already there cannot move, and leaving it out of the
7518
- // totals above is only honest if the reader is told it exists.
7519
- if (whatIf.alreadyOnTarget.calls > 0) {
7520
- console.log(` ${c.dim(wrap(t.profile.whatIfAlreadyThere(t.profile.calls(whatIf.alreadyOnTarget.calls), formatUsd(whatIf.alreadyOnTarget.usd)), 74, ' '))}`);
7521
- }
7522
- // Models with no current price have no difference to state — their target
7523
- // cost is knowable and the subtraction is not.
7524
- if (whatIf.unpricedCalls > 0) {
7525
- console.log(` ${c.dim(wrap(t.profile.whatIfUnpriced(t.profile.calls(whatIf.unpricedCalls), whatIf.unpricedModels.join(', ')), 74, ' '))}`);
8119
+ const bySourceMode = boolFlag(args, 'by-source');
8120
+ const entries = await readdir(path, { withFileTypes: true, recursive: bySourceMode });
8121
+ logFiles = entries
8122
+ .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
8123
+ .map((entry) => join(entry.parentPath ?? path, entry.name))
8124
+ .sort((a, b) => a.localeCompare(b));
8125
+ if (logFiles.length === 0) {
8126
+ throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
7526
8127
  }
7527
8128
  }
7528
8129
  /**
7529
- * What re-sending the conversation costs — the line nothing here could see.
8130
+ * Gzipped files are decompressed in memory; everything else is read as text.
7530
8131
  *
7531
- * A chat or agent workload sends the whole conversation back on every turn, so
7532
- * the input grows with the turn count and that growth is routinely the largest
7533
- * item on the bill. A prompt file shows the system prompt and not the history; a
7534
- * total shows the sum and not the shape.
8132
+ * Decided by **extension**, not by sniffing the first two bytes: a file
8133
+ * named `.jsonl` whose contents happen to start with 0x1f8b is far more
8134
+ * likely to be a corrupt log than a mislabelled archive, and silently
8135
+ * treating it as one would turn a diagnosable error into an empty report.
7535
8136
  *
7536
- * Reported as a **ceiling**, because part of the growth is the user's own new
7537
- * messages and this reads counts rather than content, so it cannot separate the
7538
- * two. Saying nothing because the exact split is unknowable would be worse: the
7539
- * bound is exact, and the reader can act on it.
8137
+ * A `.gz` that will not decompress is an error naming the file. The
8138
+ * alternative — skipping it — is a total quietly missing a day, which is
8139
+ * the failure this repository refuses in every other place it can occur.
7540
8140
  */
7541
- if (report.conversations.length > 0) {
7542
- console.log();
7543
- console.log(sectionHeading(t.profile.historyHeading()));
7544
- for (const growth of report.conversations.slice(0, 3)) {
7545
- const label = growth.label === UNLABELLED ? t.profile.unlabelled() : growth.label;
7546
- console.log();
7547
- console.log(` ${c.bold(wrap(t.profile.historyGrowth(label, growth.modelName, n(Math.round(growth.minTurnTokens)), n(Math.round(growth.maxTurnTokens)), n(growth.longestSession)), 74, ' '))}`);
7548
- console.log(` ${c.dim(wrap(t.profile.historyCeiling(formatUsd(growth.growthUsd), pct(growth.shareOfBill), formatUsd(growth.flatUsd), formatUsd(growth.inputUsd)), 74, ' '))}`);
7549
- }
7550
- }
7551
- else if (!report.hasSessions) {
7552
- /**
7553
- * Not the same as "no growth". A log without a session field cannot be asked
7554
- * the question at all, and silence there would read as a clean bill of health
7555
- * on the line most likely to be the biggest.
7556
- */
7557
- console.log();
7558
- console.log(sectionHeading(t.profile.historyHeading()));
7559
- console.log(` ${c.dim(wrap(t.profile.historyNoSessions(), 74, ' '))}`);
7560
- }
8141
+ const logTexts = await Promise.all(logFiles.map((file) => readUsageLog(file, t)));
8142
+ // A file that does not end in a newline would otherwise glue its last record
8143
+ // to the next file's first one, and both would be reported as unreadable.
8144
+ const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
7561
8145
  /**
7562
- * Where the output spend concentrates — the actionable half of "output
7563
- * dominates", which the headline above could only state as a total.
7564
- *
7565
- * Two bills with identical output spend want opposite responses. Six per cent
7566
- * of calls holding half of it is a tail, and a tail has a cause worth a
7567
- * morning; forty-five per cent is what evenly spread looks like, and the only
7568
- * lever there is asking every answer to be shorter. The threshold between the
7569
- * two is a quarter of the calls — far enough from both shapes that rounding
7570
- * cannot flip the message, and stated here because it is a presentation choice,
7571
- * not a measurement.
8146
+ * The drill-down. A label that matches nothing is an error naming the labels
8147
+ * that exist — the route command's rule, for the route command's reason: a
8148
+ * report over zero calls silently filtered would read as "this workload is
8149
+ * free".
7572
8150
  */
7573
- if (report.outputShapes.length > 0) {
7574
- console.log();
7575
- console.log(sectionHeading(t.profile.outputShapeHeading()));
7576
- for (const shape of report.outputShapes.slice(0, 3)) {
7577
- const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
7578
- const isTail = shape.heavyCallShare < 0.25;
7579
- console.log();
7580
- if (isTail) {
7581
- console.log(` ${c.bold(wrap(t.profile.outputTail(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), n(shape.aboveTokens), formatUsd(shape.outputUsd)), 74, ' '))}`);
7582
- console.log(` ${c.dim(wrap(t.profile.outputTailAdvice(), 74, ' '))}`);
7583
- }
7584
- else {
7585
- console.log(` ${c.bold(wrap(t.profile.outputFlat(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), formatUsd(shape.outputUsd)), 74, ' '))}`);
7586
- console.log(` ${c.dim(wrap(t.profile.outputFlatAdvice(), 74, ' '))}`);
7587
- }
7588
- /**
7589
- * The ceilings a max_tokens cap actually wants, exact over the
7590
- * histogram: every measured answer at or under the named number is
7591
- * counted, none interpolated. Omitted when the covering bucket is the
7592
- * open-ended last one, which has no ceiling to name honestly.
7593
- */
7594
- if (shape.medianWithinTokens !== null && shape.p95WithinTokens !== null) {
7595
- console.log(` ${c.dim(wrap(t.profile.outputPercentiles(n(shape.medianWithinTokens), n(shape.p95WithinTokens)), 74, ' '))}`);
8151
+ const onlyLabel = stringFlag(args, 'label');
8152
+ /**
8153
+ * The drill-down in time. `--since`/`--until` take a UTC day or a full
8154
+ * timestamp; a bare day means the whole of it — since its first instant,
8155
+ * until its last — because "--until 2026-08-14" excluding the named day is
8156
+ * a trap sprung on everyone who reads dates the way humans do. Internally
8157
+ * the window is half-open `[since, until)`, so two adjacent windows share
8158
+ * no record.
8159
+ */
8160
+ const now = Date.now();
8161
+ const sinceWhen = parseWhen(args, 'since', false, t, now);
8162
+ const untilWhen = parseWhen(args, 'until', true, t, now);
8163
+ const relativeWindow = sinceWhen.relative || untilWhen.relative;
8164
+ const sinceMs = sinceWhen.ms;
8165
+ const untilMs = untilWhen.ms;
8166
+ if (sinceMs !== undefined && untilMs !== undefined && sinceMs >= untilMs) {
8167
+ throw new Error(t.profile.sinceAfterUntil());
8168
+ }
8169
+ const windowed = sinceMs !== undefined || untilMs !== undefined;
8170
+ /**
8171
+ * How old the price table behind every dollar below is. Stated only when it
8172
+ * is old enough to matter: `models` and `doctor` always print the date, but
8173
+ * a profile is read for its figures, and the one fact that silently
8174
+ * invalidates all of them is a table the provider has re-priced since.
8175
+ * The threshold is in the sentence, and the number behind it is
8176
+ * `STALE_PRICING_DAYS` — shared with the MCP report and the browser's bill,
8177
+ * which used to keep their own copies of it.
8178
+ */
8179
+ const pricingAgeDays = reviewAgeDays(pricing.lastReviewed, new Date());
8180
+ const pricingStale = pricingAgeDays !== null && pricingAgeDays > STALE_PRICING_DAYS
8181
+ ? { date: pricing.lastReviewed, days: pricingAgeDays }
8182
+ : null;
8183
+ const report = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
8184
+ if (report.total.calls === 0 && report.unpriced.calls === 0) {
8185
+ if (onlyLabel !== undefined || windowed) {
8186
+ // Diagnose against the log without the failed filter, so the error can
8187
+ // name what does exist instead of describing an absence.
8188
+ const unfiltered = profileUsage(raw, { catalogue: pricing });
8189
+ if (unfiltered.total.calls > 0 || unfiltered.unpriced.calls > 0) {
8190
+ if (onlyLabel !== undefined && !unfiltered.byLabel.some((r) => r.label === onlyLabel)) {
8191
+ const available = unfiltered.byLabel
8192
+ .map((r) => (r.label === UNLABELLED ? t.profile.unlabelled() : r.label))
8193
+ .join(', ');
8194
+ throw new Error(t.route.labelNotFound(onlyLabel, available || '—'));
8195
+ }
8196
+ if (windowed) {
8197
+ /**
8198
+ * A window that matches nothing must not become a $0 report — under
8199
+ * `--max-usd` it would pass a budget gate over a period the log
8200
+ * simply does not cover, which is the flattering non-answer. The
8201
+ * error names what the log *does* cover, or says it has no clock at
8202
+ * all, so the fix is visible in the message.
8203
+ */
8204
+ if (unfiltered.span === null)
8205
+ throw new Error(t.profile.windowNeedsClock());
8206
+ throw new Error(`${t.profile.windowMatchesNothing(dayOf(unfiltered.span.fromMs), dayOf(unfiltered.span.toMs))}${relativeWindow ? ` ${t.profile.windowRelativeEmpty()}` : ''}`);
8207
+ }
7596
8208
  }
7597
8209
  }
7598
8210
  }
8211
+ const n = (value) => value.toLocaleString(t.numberLocale);
8212
+ const pct = (share) => `${(share * 100).toFixed(1)}%`;
7599
8213
  /**
7600
- * How big the calls themselves are — the other half of the bill.
8214
+ * A gate armed over a report with nothing in it, refused rather than passed.
7601
8215
  *
7602
- * The section above describes output; on a RAG or agent workload input is
7603
- * most of the invoice, and a total could only ever say "input is 63% of
7604
- * this bill", which nobody can act on. The actionable question is whether
7605
- * the ordinary call is large or a few calls are enormous, and those two
7606
- * shapes want opposite responses: a cap on something, or a shorter prompt.
8216
+ * The product had already made this call once and only once. A `--since` that
8217
+ * matches no record throws, and the comment above it says why: "under
8218
+ * --max-usd it would pass a budget gate over a period the log does not
8219
+ * cover". Two other ways of measuring nothing reached the same gate and were
8220
+ * never given the same answer — a log whose every line was unreadable, and a
8221
+ * log with no records at all. Both exited 0 against a budget, on the human
8222
+ * path and under `--json`.
7607
8223
  *
7608
- * Loud past **four times** the median — far enough from an even
7609
- * distribution that a bucket boundary cannot flip the message, and stated
7610
- * in the sentence rather than hidden here. Both figures are bucket
7611
- * ceilings, so the ratio is coarse by construction and the copy says so.
8224
+ * That is the doctrine's own rule, verbatim: *a period, or a service, nobody
8225
+ * measured is not one under budget. Name the gap; never report the absence as
8226
+ * a pass.* A pipeline that stopped writing looks exactly like a quiet month,
8227
+ * and the whole reason the rule exists is that the quiet month is the one
8228
+ * that reads as green.
8229
+ *
8230
+ * `--allow-empty` is the way to say a period with no calls is the expected
8231
+ * answer, because that is a real thing a nightly job wants and it should be
8232
+ * said out loud rather than inferred from silence.
7612
8233
  */
7613
- if (report.inputShapes.length > 0) {
7614
- console.log();
7615
- console.log(sectionHeading(t.profile.inputShapeHeading()));
7616
- for (const shape of report.inputShapes.slice(0, 3)) {
7617
- const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
7618
- console.log();
7619
- if (shape.medianWithinTokens === null || shape.p95WithinTokens === null || shape.p95OverMedian === null) {
7620
- /**
7621
- * The covering bucket is the open-ended last one, so there is no
7622
- * ceiling to name. Said rather than skipped: a slice whose calls are
7623
- * all above a million tokens is a finding, and silence would drop it.
7624
- */
7625
- console.log(` ${c.bold(wrap(t.profile.inputHuge(label, shape.modelName, t.profile.calls(shape.calls), formatUsd(shape.inputUsd)), 74, ' '))}`);
7626
- continue;
7627
- }
7628
- const skewed = shape.p95OverMedian >= 4;
7629
- const line = skewed
7630
- ? t.profile.inputSkewed(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), shape.p95OverMedian.toFixed(1), formatUsd(shape.inputUsd))
7631
- : t.profile.inputEven(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), formatUsd(shape.inputUsd));
7632
- console.log(` ${c.bold(wrap(line, 74, ' '))}`);
7633
- console.log(` ${c.dim(wrap(skewed ? t.profile.inputSkewedAdvice() : t.profile.inputEvenAdvice(), 74, ' '))}`);
7634
- /**
7635
- * What that size actually costs. A cache read is a tenth of input on
7636
- * Anthropic, so a large slice reading almost everything from cache is a
7637
- * very different bill from one paying full rate — and the token counts
7638
- * alone cannot tell them apart.
7639
- */
7640
- if (shape.cachedShare >= 0.5) {
7641
- console.log(` ${c.dim(wrap(t.profile.inputMostlyCached(pct(shape.cachedShare)), 74, ' '))}`);
7642
- }
7643
- else if (shape.cachedShare < 0.1) {
7644
- console.log(` ${c.dim(wrap(t.profile.inputFullRate(), 74, ' '))}`);
7645
- }
7646
- }
8234
+ const gateArmed = typeof args.flags.get('max-usd') === 'string' ||
8235
+ typeof args.flags.get('max-growth-usd') === 'string' ||
8236
+ typeof args.flags.get('max-cache-loss-usd') === 'string' ||
8237
+ typeof args.flags.get('max-day-usd') === 'string' ||
8238
+ typeof args.flags.get('max-session-usd') === 'string' ||
8239
+ config.spend !== undefined;
8240
+ if (gateArmed && report.total.calls === 0 && !boolFlag(args, 'allow-empty')) {
8241
+ const gap = report.unpriced.calls > 0
8242
+ ? t.profile.nothingUnpriced(report.unpriced.calls)
8243
+ : report.skippedLines.length > 0
8244
+ ? t.profile.nothingUnreadable(report.skippedLines.length)
8245
+ : t.profile.nothingEmpty();
8246
+ throw new Error(t.profile.gateNothingMeasured(gap));
8247
+ }
8248
+ if (boolFlag(args, 'by-source')) {
8249
+ await profileBySource(args, config, logFiles, logTexts, pricing, { onlyLabel, sinceMs, untilMs }, t);
8250
+ return;
8251
+ }
8252
+ if (boolFlag(args, 'dry-run')) {
8253
+ profileDryRun(args, report, t);
8254
+ return;
7647
8255
  }
7648
8256
  /**
7649
- * How close the largest call is to the model's ceiling.
8257
+ * The previous log, loaded before the output paths split so the growth gate
8258
+ * exists under `--json` too — a CI step reads the JSON and trusts the exit
8259
+ * code, and a gate that only arms in the human rendering is a gate CI never
8260
+ * had.
8261
+ */
8262
+ /* Filled by `runProfileGates` on whichever output path runs, and read by
8263
+ the side-file writer, which is why it is declared here rather than
8264
+ inlined at either call. */
8265
+ let gates = { failed: false, verdicts: [] };
8266
+ const againstPath = stringFlag(args, 'against');
8267
+ // The same filter on both sides: comparing one workload's bill against the
8268
+ // whole previous log would report every sibling workload as vanished savings.
8269
+ const previous = againstPath !== undefined
8270
+ // The same reader as the log itself, so `--against last-month.jsonl.gz`
8271
+ // works: a comparison that could only read one of the two formats would
8272
+ // be a flag that fails on exactly the rotated file it exists to read.
8273
+ ? profileUsage(await readUsageLog(againstPath, t), {
8274
+ catalogue: pricing,
8275
+ label: onlyLabel,
8276
+ // The same window on both sides, for the same reason as the label:
8277
+ // a windowed bill against an unwindowed one compares a slice to a
8278
+ // whole and calls the difference growth.
8279
+ sinceMs,
8280
+ untilMs,
8281
+ })
8282
+ : null;
8283
+ const againstDelta = previous !== null && previous.total.calls > 0
8284
+ ? report.total.totalUsd - previous.total.totalUsd
8285
+ : null;
8286
+ /**
8287
+ * The same tokens at another model's rates, computed before the output paths
8288
+ * split so `--json` carries it too.
7650
8289
  *
7651
- * The failure a bill cannot show: input grows turn by turn or document by
7652
- * document, costs nothing extra to grow, and then one call crosses the
7653
- * context window and the API refuses it. Loud from 85% — close enough
7654
- * that the next retrieval bump or long conversation plausibly crosses —
7655
- * and quiet above half, so the reader sees it coming either way. No
7656
- * prediction of *when*: a straight line through two points is a guess
7657
- * wearing arithmetic's clothes.
8290
+ * An unknown id **throws** rather than printing nothing. A flag that silently
8291
+ * does nothing is worse than a missing feature: the reader typed a question,
8292
+ * got a report with no answer in it, and has no way to tell a typo from a
8293
+ * model this comparison had nothing to say about.
7658
8294
  */
7659
- {
7660
- if (pressures.length > 0) {
7661
- console.log();
7662
- console.log(sectionHeading(t.profile.pressureHeading()));
7663
- for (const row of pressures.slice(0, 3)) {
7664
- const label = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7665
- const line = t.profile.pressureLine(label, row.modelName, n(row.maxCallInputTokens), n(row.contextWindow), pct(row.share));
7666
- console.log();
7667
- if (row.share >= 0.85) {
7668
- console.log(` ${c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`);
7669
- console.log(` ${c.dim(wrap(t.profile.pressureAdvice(), 74, ' '))}`);
7670
- }
7671
- else {
7672
- console.log(` ${c.dim(wrap(line, 74, ' '))}`);
7673
- }
7674
- }
7675
- }
8295
+ /**
8296
+ * The largest call against each model's window, computed once here so the
8297
+ * terminal, the JSON and the markdown state the same ratio — the
8298
+ * denominator lives in the (possibly overlaid) catalogue.
8299
+ */
8300
+ const pressures = contextPressure(report, pricing);
8301
+ const whatIfModel = stringFlag(args, 'what-if');
8302
+ const whatIf = whatIfModel !== undefined ? repriceProfile(report, whatIfModel, pricing) : null;
8303
+ if (whatIfModel !== undefined && whatIf === null) {
8304
+ throw new Error(t.profile.whatIfUnknown(whatIfModel, pricing.models.map((m) => m.id).join(', ')));
7676
8305
  }
7677
8306
  /**
7678
- * The mix moving inside one log — the drift `--against` needs a second log
7679
- * to see. Spoken only past fifteen points, a presentation threshold stated
7680
- * in the copy; the data states exact shares and the JSON carries them all.
8307
+ * The drivers of the change, per label and per model, computed once here so
8308
+ * the terminal, the JSON and any future rendering describe the same change.
8309
+ * The model half answers the question the label half cannot: "the growth is
8310
+ * traffic moving from Haiku to Opus" is a fact about the mix, invisible in
8311
+ * per-workload rows whose names did not change.
7681
8312
  */
7682
- if (report.modelMixDrift !== null) {
7683
- const moved = report.modelMixDrift.models.filter((m) => Math.abs(m.lastShare - m.firstShare) >= 0.15);
7684
- if (moved.length > 0) {
7685
- console.log();
7686
- console.log(sectionHeading(t.profile.mixDriftHeading()));
7687
- for (const m of moved.slice(0, 3)) {
7688
- console.log();
7689
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.mixDriftLine(m.model, pct(m.firstShare), pct(m.lastShare), n(report.modelMixDrift.firstDays), n(report.modelMixDrift.lastDays), formatUsd(m.lastUsd)), 74, ' '))}`);
7690
- }
7691
- console.log(` ${c.dim(wrap(t.profile.mixDriftNote(), 74, ' '))}`);
8313
+ const labelDrivers = previous !== null && previous.total.calls > 0
8314
+ ? driversBetween(previous.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })), report.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })))
8315
+ : [];
8316
+ const modelDrivers = previous !== null && previous.total.calls > 0
8317
+ ? driversBetween(previous.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })), report.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })))
8318
+ : [];
8319
+ /**
8320
+ * Whether the two logs share any time at all. This comparison is meant for
8321
+ * disjoint periods or snapshots of different systems; when both spans are
8322
+ * known and intersect, the same calls may sit on both sides of the
8323
+ * subtraction and the "growth" is partly the same money counted twice.
8324
+ * Only decidable when both logs carry a clock — three states, as always:
8325
+ * warned, clear, or unknown, and unknown stays silent rather than clear.
8326
+ */
8327
+ const againstOverlap = previous !== null &&
8328
+ previous.total.calls > 0 &&
8329
+ previous.span !== null &&
8330
+ report.span !== null &&
8331
+ Math.min(report.span.toMs, previous.span.toMs) >=
8332
+ Math.max(report.span.fromMs, previous.span.fromMs)
8333
+ ? {
8334
+ fromMs: Math.max(report.span.fromMs, previous.span.fromMs),
8335
+ toMs: Math.min(report.span.toMs, previous.span.toMs),
7692
8336
  }
8337
+ : null;
8338
+ // A gate flag that silently does nothing is not an answer — same rule as
8339
+ // --apply-suggestions without --suggest.
8340
+ if (typeof args.flags.get('max-growth-usd') === 'string' && againstPath === undefined) {
8341
+ throw new Error(t.profile.maxGrowthNeedsAgainst());
8342
+ }
8343
+ if (boolFlag(args, 'json')) {
8344
+ /**
8345
+ * The report, plus everything the human output leads on.
8346
+ *
8347
+ * Additive rather than a reshape: `report` keeps the shape `@trazum/core`
8348
+ * returns. The cache verdict is included because leaving a consumer to
8349
+ * re-derive it means two implementations of a sign convention where positive
8350
+ * means *worse*, and one of them will eventually get it backwards.
8351
+ *
8352
+ * `levers` is included because it was not, and that made the flagship
8353
+ * section terminal-only: "What would actually move this bill" — the reason
8354
+ * the command exists — was invisible to any pipeline, dashboard or CI step
8355
+ * reading the JSON. A finding the machine-readable output omits is a finding
8356
+ * the reader's tooling will never surface.
8357
+ */
8358
+ console.log(JSON.stringify({
8359
+ /**
8360
+ * `schemaVersion` arrives inside `report` now, and that is the point.
8361
+ *
8362
+ * It used to be stamped here, which made the profile the one contract
8363
+ * of the ten whose version existed only if you went through this
8364
+ * command. `docs/format.md` says every document carries it and
8365
+ * `conform` rejects one that does not, so a connector author using
8366
+ * `@trazum/core` produced a profile this tool refuses.
8367
+ *
8368
+ * The contract is documented in docs/json-output.md and enforced by
8369
+ * json-contract.test.js. It changes only when a field's meaning
8370
+ * changes or one is removed — new findings arrive as new keys, so a
8371
+ * consumer that ignores unknown ones keeps working.
8372
+ */
8373
+ ...report,
8374
+ cache: cacheEconomics(report.total),
8375
+ cacheByLabel: report.byLabel.map((r) => ({
8376
+ label: r.label,
8377
+ cache: cacheEconomics(r.breakdown),
8378
+ })),
8379
+ // The provenance of every dollar above: which price table, how old.
8380
+ pricing: { lastReviewed: pricing.lastReviewed, ageDays: pricingAgeDays },
8381
+ levers: billLevers(report, { catalogue: pricing }),
8382
+ // Present only when --against was passed: null delta means the
8383
+ // previous log had nothing priced, which is a different answer from
8384
+ // zero growth.
8385
+ ...(previous !== null
8386
+ ? {
8387
+ against: {
8388
+ previousTotalUsd: previous.total.totalUsd,
8389
+ deltaUsd: againstDelta,
8390
+ // The same drivers the terminal names, as data. A finding
8391
+ // the machine-readable output omits is a finding the
8392
+ // reader's tooling will never surface.
8393
+ byLabel: labelDrivers,
8394
+ byModel: modelDrivers,
8395
+ },
8396
+ }
8397
+ : {}),
8398
+ // How close each slice's largest call is to its model's window —
8399
+ // derived like `cache` and `levers`, so a dashboard need not
8400
+ // re-derive a ratio whose denominator lives in the catalogue.
8401
+ contextPressure: pressures,
8402
+ // Present only when --what-if was passed. `sameTokensAssumed` rides
8403
+ // along inside it so a consumer cannot print the dollar figure
8404
+ // without the caveat being in the same object.
8405
+ ...(whatIf !== null ? { whatIf } : {}),
8406
+ }, null, 2));
8407
+ gates = await runProfileGates({
8408
+ args, config, configDir, report, previous, againstDelta, windowed, now, pricing, t,
8409
+ });
8410
+ await writeProfileSideFiles({
8411
+ args, path, report, previous, pressures, labelDrivers, modelDrivers, againstOverlap,
8412
+ whatIf, pricingStale, windowed, gates, pricing, t,
8413
+ });
8414
+ return;
7693
8415
  }
7694
8416
  /**
7695
- * The same request, sent again a moment later.
8417
+ * Nothing priced means there is no report, not a report of zero.
7696
8418
  *
7697
- * A conversation's input grows with every turn, so two consecutive calls in
7698
- * one conversation carrying the same size seconds apart is a thing going
7699
- * wrong rather than a thing working — a retry after a timeout, an agent
7700
- * step repeating, a loop. Loud, because the money bought nothing, and
7701
- * hedged, because this reads counts and cannot see content: the sentence
7702
- * says the pattern is *usually* a retry, never that it is one.
8419
+ * The guard was `total.calls === 0 && unpriced.calls === 0`, so a log whose every
8420
+ * model was unknown fell through and printed a full report built from a zeroed
8421
+ * total: `0 calls · $0`, four `$0 / 0.0%` rows, a meaningless "Input is 0.0% of
8422
+ * this bill", and — on a log containing a hundred thousand cache-read tokens —
8423
+ * the flatly false "Caching was never used on these calls".
8424
+ *
8425
+ * Two affirmatively wrong claims and a $0 headline for a real bill. The trailing
8426
+ * unpriced note was the only correct line on screen, and it was the quietest.
7703
8427
  */
7704
- if (report.repeatedTurns.length > 0) {
8428
+ if (report.total.calls === 0) {
7705
8429
  console.log();
7706
- console.log(sectionHeading(t.profile.repeatsHeading()));
7707
- for (const row of report.repeatedTurns.slice(0, 3)) {
7708
- const label = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7709
- console.log();
7710
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.repeatsFound(label, row.modelName, n(row.repeats), n(row.checkedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.usd)), 74, ' '))}`);
7711
- console.log(` ${c.dim(wrap(t.profile.repeatsAdvice(), 74, ' '))}`);
7712
- }
8430
+ console.log(c.dim(report.unpriced.calls === 0 ? t.profile.empty() : t.profile.nothingPriced()));
8431
+ reportProfileGaps(report, t, n, pricingStale);
8432
+ return;
7713
8433
  }
8434
+ const shares = sharesOf(report.total);
8435
+ const parts = [
8436
+ [t.profile.partInput(), report.total.inputUsd, shares.input, report.total.inputTokens],
8437
+ [t.profile.partCacheRead(), report.total.cacheReadUsd, shares.cacheRead, report.total.cacheReadTokens],
8438
+ [t.profile.partCacheWrite(), report.total.cacheWriteUsd, shares.cacheWrite, report.total.cacheWriteTokens],
8439
+ [t.profile.partOutput(), report.total.outputUsd, shares.output, report.total.outputTokens],
8440
+ ];
8441
+ console.log();
8442
+ console.log(sectionHeading(t.profile.heading()));
8443
+ console.log(` ${t.profile.spent(t.profile.calls(report.total.calls), formatUsd(report.total.totalUsd))}`);
7714
8444
  /**
7715
- * Output spend that bought answers cut off mid-generation — the one slice of
7716
- * a bill that is waste without a counterpart. Paid in full, frequently
7717
- * retried and billed again, and the truncated attempt bought nothing.
7718
- *
7719
- * Three states, kept apart on purpose: waste found, none found on a log that
7720
- * measured, and a log that never recorded a stop reason at all — which gets
7721
- * the missing-field message, because silence there would read as a clean bill
7722
- * of health on a question the log never asked.
8445
+ * The period, when the log carries a clock — stated, never extrapolated. A
8446
+ * span makes the reader's own monthly arithmetic valid; a per-month figure
8447
+ * printed from a partial month would be this tool doing the guessing it
8448
+ * exists to end. Partial coverage is said in the same breath, because a span
8449
+ * over a third of the calls silently presented as the log's period is a
8450
+ * figure attributed to something it does not describe.
7723
8451
  */
7724
- if (report.total.truncatedCalls > 0 && report.total.outputUsd > 0) {
7725
- console.log();
7726
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.truncatedWaste(t.profile.calls(report.total.truncatedCalls), formatUsd(report.total.truncatedOutputUsd), pct(report.total.truncatedOutputUsd / report.total.outputUsd)), 74, ' '))}`);
7727
- /**
7728
- * Which workloads are paying for it, and at what rate — the actionable
7729
- * half the total hides. A 40% truncation rate is a max_tokens setting
7730
- * that is simply wrong; 1% is a long tail, and the two call for opposite
7731
- * responses.
7732
- *
7733
- * The rate is over calls that **recorded a stop reason**, never over all
7734
- * calls: a workload that logs the field on half its traffic must not be
7735
- * reported as though the unmeasured half completed. Both numbers print,
7736
- * so the denominator is visible rather than implied.
7737
- */
7738
- const truncatedLabels = report.byLabel
7739
- .filter((row) => row.breakdown.truncatedCalls > 0)
7740
- .sort((a, b) => b.breakdown.truncatedOutputUsd - a.breakdown.truncatedOutputUsd);
7741
- if (truncatedLabels.length > 0 && report.byLabel.length > 1) {
7742
- for (const row of truncatedLabels.slice(0, 3)) {
7743
- const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7744
- console.log(` ${c.dim(wrap(t.profile.truncatedBy(name, n(row.breakdown.truncatedCalls), n(row.breakdown.stopReasonCalls), pct(row.breakdown.truncatedCalls / row.breakdown.stopReasonCalls), formatUsd(row.breakdown.truncatedOutputUsd)), 74, ' '))}`);
7745
- }
7746
- }
7747
- /**
7748
- * The ceiling the completed answers actually needed, when the output
7749
- * shapes measured it: "95% of the answers that finished fit within N
7750
- * tokens" is the number a max_tokens cap wants, and it sits next to the
7751
- * evidence that the current cap is too low. Measured on these calls,
7752
- * promised for nothing.
7753
- */
7754
- const ceiling = report.outputShapes.find((shape) => shape.p95WithinTokens !== null);
7755
- if (ceiling !== undefined) {
7756
- console.log(` ${c.dim(wrap(t.profile.truncatedCeiling(n(ceiling.p95WithinTokens)), 74, ' '))}`);
7757
- }
7758
- /**
7759
- * The "billed again" half, measured. The sentence above has always said
7760
- * truncated answers are frequently retried; this is the count and the
7761
- * money, when the log can carry it — a pattern, never a certainty, and
7762
- * attributed to the truncated call's slice, where the ceiling that
7763
- * caused it lives.
7764
- */
7765
- for (const row of report.truncationRetries.slice(0, 3)) {
7766
- const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
7767
- console.log(` ${c.yellow('!')} ${c.bold(wrap(t.profile.truncationRetryLine(name, row.modelName, n(row.retried), n(row.truncatedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.wastedUsd), formatUsd(row.retryUsd)), 74, ' '))}`);
7768
- }
7769
- if (report.truncationRetries.length > 0) {
7770
- console.log(` ${c.dim(wrap(t.profile.truncationRetryNote(), 74, ' '))}`);
7771
- }
8452
+ if (report.span !== null) {
8453
+ const totalParsed = report.total.calls + report.unpriced.calls;
8454
+ const partial = report.span.calls < totalParsed
8455
+ ? ` ${t.profile.spanPartial(n(report.span.calls), n(totalParsed))}`
8456
+ : '';
8457
+ console.log(` ${c.dim(wrap(`${t.profile.spanLine(dayOf(report.span.fromMs), dayOf(report.span.toMs), spanDays(report.span.fromMs, report.span.toMs))}${partial}`, 74, ' '))}`);
7772
8458
  }
7773
- else if (report.total.stopReasonCalls === 0) {
7774
- console.log();
7775
- console.log(` ${c.dim(wrap(t.profile.truncatedNotRecorded(), 74, ' '))}`);
8459
+ // How many files this report covers, when it covers more than one: a total
8460
+ // over "the logs" that silently skipped one is wrong by an unknown amount.
8461
+ if (logFiles.length > 1) {
8462
+ console.log(` ${c.dim(wrap(t.profile.readFiles(logFiles.length, path), 74, ' '))}`);
7776
8463
  }
7777
8464
  /**
7778
- * This bill against the previous one — how spend actually gets out of hand.
8465
+ * A doubled bill, said before anything is believed.
7779
8466
  *
7780
- * Nobody adds five thousand a month in one day; bills grow four percent a week
7781
- * while every snapshot looks reasonable. This is the baseline gate the prompts
7782
- * already had, applied to the money itself. **Positive means the bill grew**
7783
- * (the diff convention), and every figure is between exactly these two files:
7784
- * no period is assumed, so the call counts print beside the money for the
7785
- * reader to judge comparability before judging the trend.
8467
+ * Reading a directory of rotated logs makes double-counting easy — a log
8468
+ * exported twice, an overlapping export, a copy left in the folder — and
8469
+ * the total then reads high with nothing else able to see it. Only counted
8470
+ * over records with a clock, where an identical line is a claim worth
8471
+ * making. It states the count and the money and stops: whether it is a
8472
+ * double export or a genuinely busy millisecond is the reader's to know.
7786
8473
  */
7787
- if (previous !== null) {
7788
- console.log();
7789
- console.log(sectionHeading(t.profile.againstHeading()));
7790
- if (previous.total.calls === 0) {
7791
- console.log(` ${c.dim(wrap(t.profile.againstNothingPriced(), 74, ' '))}`);
7792
- }
7793
- else {
7794
- const delta = report.total.totalUsd - previous.total.totalUsd;
7795
- const growthPct = previous.total.totalUsd > 0
7796
- ? `${delta >= 0 ? '+' : ''}${((delta / previous.total.totalUsd) * 100).toFixed(1)}%`
7797
- : '—';
7798
- console.log(` ${c.bold(wrap(t.profile.againstTotals(formatUsd(previous.total.totalUsd), formatUsd(report.total.totalUsd), formatSignedUsd(delta), growthPct, t.profile.calls(previous.total.calls), t.profile.calls(report.total.calls)), 74, ' '))}`);
7799
- // Overlapping spans mean part of this "growth" is the same money on
7800
- // both sides of the subtraction. Said after the figure it qualifies
7801
- // and before the drivers built from it.
7802
- if (againstOverlap !== null) {
7803
- console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.againstOverlap(dayOf(againstOverlap.fromMs), dayOf(againstOverlap.toMs)), 74, ' '))}`);
7804
- }
7805
- // Drivers: per-key contribution to the change, largest magnitude first,
7806
- // computed once beside the gates so no rendering derives its own.
7807
- const driverLine = (d, shown) => d.was === null
7808
- ? t.profile.againstDriverNew(formatSignedUsd(d.delta), shown)
7809
- : d.now === null
7810
- ? t.profile.againstDriverGone(formatSignedUsd(d.delta), shown)
7811
- : t.profile.againstDriver(formatSignedUsd(d.delta), shown, formatUsd(d.was), formatUsd(d.now));
7812
- console.log();
7813
- for (const d of labelDrivers.slice(0, 5)) {
7814
- const line = driverLine(d, d.key === UNLABELLED ? t.profile.unlabelled() : d.key);
7815
- console.log(` ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
7816
- }
7817
- if (labelDrivers.length > 5) {
7818
- console.log(` ${c.dim(t.profile.andMoreLabels(labelDrivers.length - 5))}`);
7819
- }
7820
- /**
7821
- * The same change, by model — where the mix moved. The label rows cannot
7822
- * show it: a workload that kept its name and switched from Haiku to Opus
7823
- * reads as "chat grew", and the reason is the model. Only printed when
7824
- * more than one model is involved; with one model on both sides, this
7825
- * section restates the totals line and says nothing new.
7826
- */
7827
- const modelsInvolved = new Set([
7828
- ...previous.byModel.map((r) => r.model),
7829
- ...report.byModel.map((r) => r.model),
7830
- ]);
7831
- if (modelDrivers.length > 0 && modelsInvolved.size > 1) {
7832
- console.log();
7833
- console.log(` ${c.dim(t.profile.againstByModel())}`);
7834
- for (const d of modelDrivers.slice(0, 3)) {
7835
- const line = driverLine(d, d.key);
7836
- console.log(` ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
7837
- }
7838
- }
7839
- /**
7840
- * What the comparison stopped being able to see.
7841
- *
7842
- * Every figure above is dollars, and dollars cannot tell a finding that
7843
- * was fixed from a finding whose field the log stopped recording — both
7844
- * are silence. This is the only section that can, so it is loud: a
7845
- * collapse in coverage invalidates whichever findings depended on it,
7846
- * and reading the drop as good news is the specific mistake it exists
7847
- * to prevent.
7848
- */
7849
- const drifts = coverageDrift(previous.fieldCoverage, report.fieldCoverage);
7850
- if (drifts.length > 0) {
7851
- console.log();
7852
- for (const drift of drifts) {
7853
- const line = t.profile.coverageDrift(t.profile.coverageField(drift.field), pct(drift.was), pct(drift.now));
7854
- console.log(drift.delta < 0
7855
- ? ` ${c.yellow('!')} ${c.bold(wrap(line, 74, ' '))}`
7856
- : ` ${c.dim(wrap(line, 74, ' '))}`);
7857
- /**
7858
- * Which findings went with it, named. "Some findings are silent" is
7859
- * not something a reader can act on; knowing that conversation
7860
- * growth and the cache-TTL fit are now silence rather than absence
7861
- * tells them exactly which sections of this report to distrust.
7862
- */
7863
- if (drift.delta < 0) {
7864
- const silenced = t.profile.coverageSilenced(drift.field);
7865
- if (silenced !== '')
7866
- console.log(` ${c.dim(wrap(silenced, 72, ' '))}`);
7867
- }
7868
- }
7869
- if (drifts.some((d) => d.delta < 0)) {
7870
- console.log(` ${c.dim(wrap(t.profile.coverageDriftWhy(), 74, ' '))}`);
7871
- }
7872
- }
8474
+ if (report.duplicateLines.count > 0) {
8475
+ console.log(` ${c.yellow('!')} ${c.dim(wrap(t.profile.duplicateLines(report.duplicateLines.count, formatUsd(report.duplicateLines.usd)), 74, ' '))}`);
8476
+ }
8477
+ /**
8478
+ * The window, said before any figure is trusted as "the log": everything
8479
+ * below describes a slice, and a slice presented as the whole is a figure
8480
+ * attributed to something it does not describe. The undated count is loud —
8481
+ * those calls' spend is in the log and not in this report, so the window's
8482
+ * figures are a floor on the period, and only this line says so.
8483
+ */
8484
+ if (report.timeWindow !== null) {
8485
+ console.log(` ${c.dim(wrap(t.profile.windowLine(stringFlag(args, 'since') ?? '—', stringFlag(args, 'until') ?? '—'), 74, ' '))}`);
8486
+ if (relativeWindow) {
8487
+ console.log(` ${c.dim(wrap(t.profile.windowRelative(), 74, ' '))}`);
7873
8488
  }
7874
- }
7875
- for (const [heading, rows] of [
7876
- [t.profile.byLabelHeading(), report.byLabel.map((r) => [r.label === UNLABELLED ? t.profile.unlabelled() : r.label, r.breakdown])],
7877
- [t.profile.byModelHeading(), report.byModel.map((r) => [r.model, r.breakdown])],
7878
- ]) {
7879
- if (rows.length <= 1)
7880
- continue; // One row is the total again, said twice.
7881
- console.log();
7882
- console.log(sectionHeading(heading));
7883
- for (const [name, breakdown] of rows) {
7884
- const share = report.total.totalUsd > 0 ? breakdown.totalUsd / report.total.totalUsd : 0;
7885
- console.log(` ${bar(share)} ${t.profile.row(name, formatUsd(breakdown.totalUsd), pct(share), t.profile.calls(breakdown.calls))}`);
8489
+ if (report.timeWindow.undatedExcluded > 0) {
8490
+ console.log(` ${c.yellow(wrap(t.profile.windowUndated(report.timeWindow.undatedExcluded), 74, ' '))}`);
7886
8491
  }
7887
8492
  }
8493
+ console.log();
8494
+ // Every part, including the zero ones. A row missing because it was zero reads
8495
+ // as a row somebody forgot, and "you are not caching at all" is a finding.
8496
+ for (const [name, usd, share, tokens] of parts) {
8497
+ console.log(` ${bar(share)} ${t.profile.part(name, formatUsd(usd), pct(share), n(tokens))}`);
8498
+ }
7888
8499
  /**
7889
- * What this log cannot answer, and what would fix it.
8500
+ * The line the command exists for: which part of the bill to argue with.
7890
8501
  *
7891
- * Every finding past the totals needs a field the format does not require,
7892
- * and a reader who never adds them sees a report quietly missing half of
7893
- * itself — with no way to tell "nothing to report" from "nothing recorded".
7894
- * Named with counts rather than booleans: twelve labelled records out of
7895
- * forty thousand is not a labelled log, and a boolean would call it one.
8502
+ * When output is both the biggest part and over half, the two sentences say the
8503
+ * same thing and the second says more — so only the second prints. Reporting a
8504
+ * fact twice in adjacent lines reads as a bug, and it was one.
8505
+ */
8506
+ const [biggestName, , biggestShare] = parts.reduce((a, b) => (b[1] > a[1] ? b : a));
8507
+ const outputDominates = shares.output > 0.5;
8508
+ console.log();
8509
+ if (outputDominates) {
8510
+ console.log(` ${c.bold(wrap(t.profile.outputDominates(pct(shares.output)), 74, ' '))}`);
8511
+ }
8512
+ else {
8513
+ console.log(` ${c.bold(t.profile.biggestPart(biggestName, pct(biggestShare)))}`);
8514
+ }
8515
+ /**
8516
+ * The most expensive day, with a suspect attached.
7896
8517
  *
7897
- * Only fields that are actually missing are listed. A complete log gets no
7898
- * section at all, because a paragraph of things that are fine is the
7899
- * paragraph readers learn to skip.
8518
+ * The shape of a bill over time is the finding the total hides: a steady $3 a
8519
+ * day and a quiet week broken by one $40 spike sum to the same number and call
8520
+ * for opposite responses. Rendered against the **median** day — a mean would
8521
+ * let the spike inflate its own yardstick — and loud only when it clears twice
8522
+ * the median, a threshold stated in the sentence rather than hidden in code.
7900
8523
  */
8524
+ if (report.spendByDay.length >= 2) {
8525
+ const medianUsd = median(report.spendByDay.map((d) => d.usd));
8526
+ const peak = report.spendByDay.reduce((a, b) => (b.usd > a.usd ? b : a));
8527
+ if (medianUsd > 0) {
8528
+ const ratio = (peak.usd / medianUsd).toFixed(1);
8529
+ const line = t.profile.dayPeak(peak.day, formatUsd(peak.usd), ratio);
8530
+ const labelClause = peak.topLabel !== null && report.byLabel.length > 1
8531
+ ? ` ${t.profile.dayPeakLabel(peak.topLabel === UNLABELLED ? t.profile.unlabelled() : peak.topLabel, formatUsd(peak.topLabelUsd))}`
8532
+ : '';
8533
+ const loud = peak.usd > 2 * medianUsd;
8534
+ const text = wrap(`${line}${labelClause}`, 74, ' ');
8535
+ console.log(` ${loud ? c.yellow(text) : c.dim(text)}`);
8536
+ }
8537
+ }
7901
8538
  /**
7902
- * Outcomes — the counterpart, where somebody recorded one.
8539
+ * The shape of the day, and what it says about batching.
7903
8540
  *
7904
- * Printed above the coverage section rather than below it, because when this
7905
- * section is present it is the most valuable thing on the page: every other
7906
- * figure in this report is a cost, and this is the only one that says what
7907
- * the money bought.
8541
+ * Spend packed into the hours a country is awake is interactive traffic
8542
+ * somebody is waiting on; spend spread evenly across twenty-four is
8543
+ * background work — and background work is what the Batch API halves. The
8544
+ * measure is exact and needs no threshold to state: the **fewest hours that
8545
+ * hold 80% of the spend**. Two or three means concentrated; sixteen means
8546
+ * flat.
7908
8547
  *
7909
- * Silent when nothing recorded an outcome. The coverage section below
7910
- * already names the missing field and what it would unlock, and printing an
7911
- * empty Outcomes heading above it would be the same sentence twice.
8548
+ * It says what the shape is and stops. Whether a workload can wait is a
8549
+ * product decision Trazum cannot make from counts, so the sentence names
8550
+ * the lever and never claims the saving — the batch figure the levers
8551
+ * section already prints is the one with money attached.
7912
8552
  */
7913
- {
7914
- const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
7915
- if (outcomes.coverage.recorded > 0) {
7916
- console.log();
7917
- console.log(sectionHeading(t.profile.outcomeHeading()));
7918
- const col = t.profile.outcomeColumns;
7919
- const rows = [...outcomes.slices, ...outcomes.undeclared].map((slice) => ({
7920
- value: slice.value,
7921
- verdict: slice.verdict === 'success'
7922
- ? t.profile.verdictSuccess()
7923
- : slice.verdict === 'undeclared'
7924
- ? t.profile.verdictUndeclared()
7925
- : t.profile.verdictOther(),
7926
- calls: n(slice.calls),
7927
- spend: formatUsd(slice.usd),
7928
- }));
7929
- const w = {
7930
- value: Math.max(...rows.map((r) => r.value.length), col.outcome.length),
7931
- verdict: Math.max(...rows.map((r) => r.verdict.length), 0),
7932
- calls: Math.max(...rows.map((r) => r.calls.length), col.calls.length),
7933
- spend: Math.max(...rows.map((r) => r.spend.length), col.spend.length),
7934
- };
7935
- console.log(c.dim(` ${col.outcome.padEnd(w.value)} ${''.padEnd(w.verdict)} ` +
7936
- `${col.calls.padStart(w.calls)} ${col.spend.padStart(w.spend)}`));
7937
- for (const row of rows) {
7938
- const tint = row.verdict === t.profile.verdictUndeclared()
7939
- ? c.yellow
7940
- : row.verdict === t.profile.verdictSuccess()
7941
- ? c.green
7942
- : c.dim;
7943
- console.log(` ${row.value.padEnd(w.value)} ${tint(row.verdict.padEnd(w.verdict))} ` +
7944
- `${row.calls.padStart(w.calls)} ${row.spend.padStart(w.spend)}`);
7945
- }
7946
- console.log();
7947
- if (outcomes.successShareOfRecordedUsd !== null) {
7948
- const declaredUsd = outcomes.slices.reduce((sum, slice) => sum + slice.usd, 0);
7949
- console.log(` ${wrap(t.profile.outcomeRate(pct(outcomes.successShareOfRecordedUsd), formatUsd(declaredUsd)), 74, ' ')}`);
7950
- }
7951
- else if (outcomes.noRate !== null) {
7952
- console.log(` ${c.dim(wrap(t.profile.outcomeNoRate(outcomes.noRate), 74, ' '))}`);
7953
- }
7954
- // What the rate does not cover, every time it is printed. A rate over a
7955
- // twelfth of the bill is a rate about a twelfth of the bill.
7956
- if (outcomes.coverage.unrecordedUsd > 0 && report.total.totalUsd > 0) {
7957
- console.log(` ${c.yellow('!')} ${wrap(t.profile.outcomeUnrecorded(pct(outcomes.coverage.unrecordedUsd / report.total.totalUsd), formatUsd(outcomes.coverage.unrecordedUsd)), 74, ' ')}`);
7958
- }
7959
- /**
7960
- * What an outcome costs, per workload — the finding a total cannot make.
7961
- *
7962
- * Printed only when at least one workload has enough recorded outcomes
7963
- * to say something, and every row that cannot state a figure says which
7964
- * of the five reasons applies rather than showing a blank.
7965
- */
7966
- const ranking = rankPerOutcome(report.outcomeTallyByLabel.map((entry) => ({
7967
- key: entry.label,
7968
- calls: entry.calls,
7969
- totalUsd: entry.totalUsd,
7970
- tally: entry.tally,
7971
- })), config.outcomes ?? null);
7972
- if (ranking.byCall.length > 0) {
7973
- console.log();
7974
- console.log(sectionHeading(t.profile.perOutcomeHeading()));
7975
- const pcol = t.profile.perOutcomeColumns;
7976
- const prows = ranking.byCall.map((slice) => ({
7977
- key: slice.key,
7978
- perCall: formatUsd(slice.usdPerCall),
7979
- perOutcome: slice.per.usdPerSuccess !== null
7980
- ? formatUsd(slice.per.usdPerSuccess)
7981
- : t.profile.perOutcomeWithheld(slice.per.withheld ?? 'no-vocabulary', n(slice.per.successes), pct(slice.per.coverage)),
7982
- recorded: pct(slice.per.coverage),
7983
- }));
7984
- const pw = {
7985
- key: Math.max(...prows.map((r) => r.key.length), pcol.workload.length),
7986
- perCall: Math.max(...prows.map((r) => r.perCall.length), pcol.perCall.length),
7987
- perOutcome: Math.max(...prows.map((r) => r.perOutcome.length), pcol.perOutcome.length),
7988
- recorded: Math.max(...prows.map((r) => r.recorded.length), pcol.recorded.length),
7989
- };
7990
- console.log(c.dim(` ${pcol.workload.padEnd(pw.key)} ${pcol.perCall.padStart(pw.perCall)} ` +
7991
- `${pcol.perOutcome.padStart(pw.perOutcome)} ${pcol.recorded.padStart(pw.recorded)}`));
7992
- for (const row of prows) {
7993
- console.log(` ${row.key.padEnd(pw.key)} ${row.perCall.padStart(pw.perCall)} ` +
7994
- `${row.perOutcome.padStart(pw.perOutcome)} ${c.dim(row.recorded.padStart(pw.recorded))}`);
7995
- }
7996
- console.log();
7997
- console.log(` ${c.dim(wrap(t.profile.perOutcomeNumerator(), 74, ' '))}`);
7998
- // The disagreement between the two orders, which is itself the finding.
7999
- if (ranking.disagreements.length > 0) {
8000
- console.log();
8001
- console.log(` ${c.dim(wrap(t.profile.perOutcomeBothOrders(), 74, ' '))}`);
8002
- for (const d of ranking.disagreements) {
8003
- console.log(` ${c.yellow('→')} ${wrap(t.profile.perOutcomeDisagreement(d.slice.key, n(d.callRank + 1), n(d.outcomeRank + 1)), 74, ' ')}`);
8004
- }
8005
- }
8006
- }
8007
- if (outcomes.undeclared.length > 0) {
8008
- console.log(` ${c.yellow('!')} ${wrap(t.profile.outcomeUndeclared(outcomes.undeclared.map((s) => s.value).join(', ')), 74, ' ')}`);
8009
- }
8553
+ if (report.spendByHour.length >= 4 && report.total.totalUsd > 0) {
8554
+ const sorted = [...report.spendByHour].sort((a, b) => b.usd - a.usd);
8555
+ let covered = 0;
8556
+ let hoursForMost = 0;
8557
+ for (const hour of sorted) {
8558
+ covered += hour.usd;
8559
+ hoursForMost += 1;
8560
+ if (covered >= 0.8 * report.total.totalUsd)
8561
+ break;
8010
8562
  }
8563
+ const busiest = sorted
8564
+ .slice(0, hoursForMost)
8565
+ .map((hour) => hour.hour)
8566
+ .sort((a, b) => a - b)
8567
+ .map((hour) => `${String(hour).padStart(2, '0')}:00`)
8568
+ .join(', ');
8569
+ console.log();
8570
+ console.log(` ${c.dim(wrap(hoursForMost <= 8 ? t.profile.hoursConcentrated(n(hoursForMost), busiest) : t.profile.hoursFlat(n(hoursForMost)), 74, ' '))}`);
8011
8571
  }
8012
- const coverage = report.fieldCoverage;
8013
- if (coverage.parsed > 0) {
8014
- const missing = [];
8015
- const partial = (seen) => `${n(seen)}/${n(coverage.parsed)}`;
8016
- if (coverage.label < coverage.parsed) {
8017
- missing.push(t.profile.needsLabel(partial(coverage.label)));
8018
- }
8019
- if (coverage.session < coverage.parsed) {
8020
- missing.push(t.profile.needsSession(partial(coverage.session)));
8021
- }
8022
- /**
8023
- * Listed first among the missing when it is missing entirely, because it
8024
- * is the one field that changes what every other figure here *means*. The
8025
- * rest sharpen a cost; this one gives it a counterpart.
8026
- */
8027
- if (coverage.outcome < coverage.parsed) {
8028
- missing.push(t.profile.needsOutcome(partial(coverage.outcome)));
8029
- }
8030
- if (coverage.ts < coverage.parsed) {
8031
- missing.push(t.profile.needsTs(partial(coverage.ts)));
8032
- }
8033
- if (coverage.stopReason < coverage.parsed) {
8034
- missing.push(t.profile.needsStopReason(partial(coverage.stopReason)));
8035
- }
8036
- if (coverage.cacheWrites > 0 && coverage.cacheTtl < coverage.cacheWrites) {
8037
- missing.push(t.profile.needsCacheTtl(`${n(coverage.cacheTtl)}/${n(coverage.cacheWrites)}`));
8038
- }
8039
- if (missing.length > 0) {
8040
- console.log();
8041
- console.log(sectionHeading(t.profile.coverageHeading()));
8042
- for (const line of missing)
8043
- console.log(` ${c.dim(wrap(line, 74, ' '))}`);
8572
+ reportCacheVerdict(report, t);
8573
+ await reportLabelsBudgetsAndCache(report, config, pricing, t);
8574
+ reportLevers(report, pricing, t);
8575
+ reportWhatIf(whatIf, report, t);
8576
+ reportConversationHistory(report, t);
8577
+ reportOutputShape(report, t);
8578
+ reportInputShape(report, t);
8579
+ reportContextPressure(pressures, t);
8580
+ reportMixDrift(report, t);
8581
+ reportRepeatedCalls(report, t);
8582
+ reportAgainstPrevious({
8583
+ report, previous, againstOverlap, labelDrivers, modelDrivers, gates, now, t,
8584
+ });
8585
+ for (const [heading, rows] of [
8586
+ [t.profile.byLabelHeading(), report.byLabel.map((r) => [r.label === UNLABELLED ? t.profile.unlabelled() : r.label, r.breakdown])],
8587
+ [t.profile.byModelHeading(), report.byModel.map((r) => [r.model, r.breakdown])],
8588
+ ]) {
8589
+ if (rows.length <= 1)
8590
+ continue; // One row is the total again, said twice.
8591
+ console.log();
8592
+ console.log(sectionHeading(heading));
8593
+ for (const [name, breakdown] of rows) {
8594
+ const share = report.total.totalUsd > 0 ? breakdown.totalUsd / report.total.totalUsd : 0;
8595
+ console.log(` ${bar(share)} ${t.profile.row(name, formatUsd(breakdown.totalUsd), pct(share), t.profile.calls(breakdown.calls))}`);
8044
8596
  }
8045
8597
  }
8598
+ reportOutcomesAndCoverage(report, config, t);
8046
8599
  reportProfileGaps(report, t, n, pricingStale);
8047
- recordGates();
8048
- await recordWaiverUses();
8049
- await writeSideFiles();
8600
+ gates = await runProfileGates({
8601
+ args, config, configDir, report, previous, againstDelta, windowed, now, pricing, t,
8602
+ });
8603
+ await writeProfileSideFiles({
8604
+ args, path, report, previous, pressures, labelDrivers, modelDrivers, againstOverlap,
8605
+ whatIf, pricingStale, windowed, gates, pricing, t,
8606
+ });
8050
8607
  }
8051
8608
  /**
8052
8609
  * What the profile could not account for, said out loud.
@@ -9634,12 +10191,18 @@ async function main() {
9634
10191
  case 'from-claude-code':
9635
10192
  await commandFromClaudeCode(args, t);
9636
10193
  break;
10194
+ case 'receipt':
10195
+ await commandReceipt(args, pricing, t);
10196
+ break;
9637
10197
  case 'from-otel':
9638
10198
  await commandFromOtel(args, t);
9639
10199
  break;
9640
10200
  case 'from-litellm':
9641
10201
  await commandFromLiteLlm(args, t);
9642
10202
  break;
10203
+ case 'from-langsmith':
10204
+ await commandFromLangsmith(args, t);
10205
+ break;
9643
10206
  case 'from-helicone':
9644
10207
  await commandFromHelicone(args, t);
9645
10208
  break;
@@ -9683,9 +10246,47 @@ async function main() {
9683
10246
  throw new Error(t.errors.unknownCommand(args.command));
9684
10247
  }
9685
10248
  }
10249
+ /**
10250
+ * A filesystem error, said in this product's voice.
10251
+ *
10252
+ * `optimize`, `check`, `profile`, `position`, `diff`, `semantic` and `conform`
10253
+ * all read a path the reader typed, and all seven let Node's own error through:
10254
+ * `ENOENT: no such file or directory, open '/nope/x.txt'` on the commonest
10255
+ * mistake there is. The five converters `stat` first and answer
10256
+ * `/nope/x.json: not found`, so the CLI disagreed with itself about how to
10257
+ * refuse, and the majority spelling was the one that names a syscall.
10258
+ *
10259
+ * Translated here rather than at each of the seven, because the seven is the
10260
+ * part that changes: a command added next year reads a path too, and a fix
10261
+ * applied per call site is one somebody has to remember. A converter's own
10262
+ * message is more specific and is thrown earlier, so it still wins.
10263
+ */
10264
+ function filesystemRefusal(error, t) {
10265
+ if (!(error instanceof Error) || !('code' in error))
10266
+ return null;
10267
+ const path = 'path' in error && typeof error.path === 'string' ? error.path : null;
10268
+ /*
10269
+ `readFile` on a directory fails at `read` rather than `open`, and Node
10270
+ attaches no path to that one. The refusal still has to arrive with
10271
+ something in it, so it names what went wrong without naming which file.
10272
+ */
10273
+ if (path === null)
10274
+ return error.code === 'EISDIR' ? t.errors.fileIsDirectoryUnnamed() : null;
10275
+ switch (error.code) {
10276
+ case 'ENOENT':
10277
+ return t.errors.fileNotFound(path);
10278
+ case 'EISDIR':
10279
+ return t.errors.fileIsDirectory(path);
10280
+ case 'EACCES':
10281
+ case 'EPERM':
10282
+ return t.errors.fileNotReadable(path);
10283
+ default:
10284
+ return null;
10285
+ }
10286
+ }
9686
10287
  main().catch((error) => {
9687
- const message = error instanceof Error ? error.message : String(error);
9688
10288
  const t = getCliMessages(localeFromArgv(process.argv.slice(2)));
10289
+ const message = filesystemRefusal(error, t) ?? (error instanceof Error ? error.message : String(error));
9689
10290
  console.error(`\n${c.red(t.errors.errorLabel())}: ${message}\n`);
9690
10291
  process.exitCode = 1;
9691
10292
  });