trazum profile --json
Documentation / Command reference · Format contracts · Plan format
The machine-readable report, and what it promises.
Everything the terminal prints is derived from these fields, so a dashboard, a CI step or a spreadsheet importer can read the same figures the human report shows without parsing prose. This file is the contract, and every table in it is enforced in both directions: a key that disappears fails, and a key added without a line here fails too.
Which guard holds which table is written down, not assumed. That sentence
used to name one test file, and this file documents fifteen documents — nine of
them were held that way and six were not, which is how the roll-up came to emit
sixteen fields with no line here. packages/cli/test/contract-coverage.test.js
now takes the headings out of this file, matches each against the test that
harvests it, and fails on a table nobody claims and on a claim for a table
that no longer exists.
The promise#
These promises apply to the schemaVersion documents. The 2.6.0
task document uses its own strict version / kind
contract and retains explicit task metadata and non-cryptographic reuse
checksums; its separate privacy and validation boundaries are stated below.
schemaVersionis the only thing you must branch on. It starts at1and changes only when a field's meaning changes or one is removed.- Fields are added without a version bump. New findings arrive as new keys; a consumer that ignores unknown keys keeps working.
- Dollars are numbers, not strings, and never rounded for display — the terminal rounds, the JSON does not. Token counts are integers.
- Nothing here carries a session key or prompt text. Session identifiers group turns inside Trazum and never reach any output, which is the same promise the log format itself makes.
- Absence is
nullor an empty array, never zero.span: nullmeans the log carried no clock;spendByDay: []means the same. Zero would be a claim, and the difference between "not measured" and "measured as none" is the one this tool refuses to lose.
Four of those five were prose until they were not. Only absence is null
was enforced, on five fields of one document; the rest held and nothing would
have said so if they stopped.
packages/core/test/format-promises.test.js runs all of them over every
document this package can build — the profile, the roll-up and the prompt draft
— and takes the bullets out of the section above first, so the guard cannot
outlive the claim or the claim the guard.
Rounding is the awkward one: its absence cannot be proved from one document, so
what is asserted is the opposite of the failure. A document whose dollars had
been through toFixed(2) would carry none with more than two decimals, and
this one is required to carry a majority. Each check was proved by breaking the
product rather than the test — rounding on the way out, a dollar as a string,
a fractional token count, a session key reaching the document — and by rewording
this section without changing a promise, which must not fail.
Top-level fields#
| Field | What it holds |
|---|---|
schemaVersion | The contract version. 1 today. |
total | Every priced call, split by input, cache reads, cache writes and output, in tokens and dollars, and by web searches (since 2.7.5): webSearchRequests, webSearchUsd (inside totalUsd, billed per search) and webSearchUnpricedRequests (searches on a model with no per-search fee, left out of totalUsd). batchExcludedInputTokens, batchExcludedOutputTokens and batchExcludedUsd are the input and output the Batch API lever leaves out: calls already billed at the batch rate, and calls marked interactive. They are inside the lines above, not beside them. |
byLabel | The same breakdown per workload label, largest bill first. |
byModel | The same per model, largest bill first. Unpriced models appear with tokens and zero dollars. |
byLabelAndModel | The grain a routing decision is made at: one row per workload and model. |
unpricedModels | Model ids the price catalogue does not know, named rather than silently costed at zero. |
unpriced | What those calls used, kept entirely out of total. |
skippedLines | 1-based positions of lines that could not be read. |
conversations | What re-sending history costs per slice — a ceiling, never a saving. A conversation is a session's thread: a subagent that shares its session's id (thread on the record) is a conversation of its own here, and in repeatedTurns, truncationRetries, cacheTtlFit and singleTurnCacheWrites. sessionCosts and sessionSpend count the whole session, subagents included. |
hasSessions | Whether any record carried a session at all. Distinguishes "no growth" from "not measured". |
outputShapes | Where output spend concentrates, with the max_tokens ceilings the measured answers fit within. |
inputShapes | How big a slice's calls are: the ceilings half and 95% of them fit within, their ratio, and how much of the size was cache reads. Slices with too few calls for a percentile are absent, not zeroed. |
repeatedTurns | Calls that re-sent the previous call's exact input size in the same conversation, seconds apart — the shape of a retry or a loop, with what they cost. Needs a session and a clock. |
truncationRetries | Truncated answers followed within two minutes by another call in the same conversation — the "billed again" half of the truncation finding, priced on both sides, with the checkable denominator. Needs a session, a clock and a stop reason. |
span | The period the log covers, or null. Stated, never extrapolated. |
spendByDay | Exact dollars per UTC day, with the day's biggest label and the day's spend per model — the series modelMixDrift summarises, whole. |
duplicateLines | Lines identical to an earlier one (timestamped records only), and what they added to the total — the shape a doubled export has. |
fieldCoverage | How many parsed records carried each optional field — the counts behind "what this log cannot answer yet". interactive counts the records that said something waited on their answer. |
outcomeTally | What each recorded outcome value cost: byValue (value, calls, usd, dearest first), recorded, parsed, unrecordedUsd. Measurement only, no judgement — which values mean success is declared in the config, not decided here, so a consumer that wants a rate passes this through outcomeReport. An aggregate, never a list of calls. |
outcomeTallyByLabel | The same tally per label, each with the slice's own calls and totalUsd — so a coverage share describes the workload and not the file it came from. The grouping a decision is made at. |
outcomeTallyByModel | The same, per model. |
spendByHour | Exact dollars per hour of the UTC day — the shape that says whether the Batch API applies. |
modelMixDrift | Each model's share of spend in the first half of the log's days against the last half — the migration a total cannot show. null under four dated days: one day against one day is weather, not climate. |
cacheTtlFit | Whether each slice's cache TTL fits how fast its turns arrive. |
timeWindow | The --since/--until filter applied, with the clockless calls it excluded. null when unfiltered. |
singleTurnCacheWrites | Cache writes by conversations that never came back — a ceiling, or a fact when the slice read nothing. |
sessionCosts | What one session costs, its subagents included: median, p95 and maximum per slice. |
sessionSpend | The whole log's sessions summarised for a per-session budget: how many, and what the single most expensive one cost, subagents included. null when no record carried a session. |
cache | Whether caching paid for itself over the whole log, with the worst case when the TTL was not recorded. |
cacheByLabel | The same verdict per workload — where a total hides a loss. |
pricing | Which price table produced these dollars, and how old it is, in two parts. lastReviewed and ageDays are the table's: its oldest provider, which is what how old is this catalogue means. reportReviewed and reportAgeDays are these figures': the oldest provider among the models actually priced here, and the pair the staleness warning is decided from. They differ exactly when a report uses none of the models holding the table back, which is why the warning used to fire on reports it did not describe. |
levers | What would actually move the bill: routing, the Batch API, and the ceiling on prompt shortening. |
against | Present only with --against: the previous total, the delta, and the drivers per label and per model. |
contextPressure | Slices whose largest call is past half its model's context window: the call, the window, and the share. The failure a bill cannot show until the day it happens. |
whatIf | Present only with --what-if <model>: the same tokens at that model's rates, the slices too large for its context window, and sameTokensAssumed — the caveat travels inside the object so a consumer cannot print the figure without it. batchOnTarget holds the moved bill with the target's Batch API on top (null when the target sells none — a different statement from a $0 saving). Each slice carries cacheBeyondTarget — null, or the target's cache minimum and the no-cache price when the slice's cache traffic could not exist there, because the standard figure would otherwise flatter the move. |
What it deliberately does not contain#
No prompt text, no session keys, no per-call rows. The report is aggregate by construction: a usage log handed to Trazum carries no content, and nothing identifying comes back out of it either.
The --by-source document#
profile --by-source --json emits a different top-level shape — a fleet is
not one report:
| Field | What it holds |
|---|---|
schemaVersion | 1. The fleet document carries it too — a consumer branching on it should not have to infer that from the single-log table. |
bySource[] | One entry per configured source with traffic: its name and its full report, each identical in shape to the single-log document above. |
rollup | The fleet read as one thing, in the rows below. A container rather than a figure — the sums live inside it so a consumer never reaches for a fleet total on a document that is a list of sources. |
rollup.totalUsd, rollup.calls | The sum over every source. A total is a total, whatever the spans. |
rollup.sources[] | Every source, dearest first: usd, calls, share of the fleet, and spanDays (null when its logs carry no clock). |
rollup.worst | The dearest source with its share, or null when the fleet spent nothing — "nothing is bleeding" and "the worst of nothing" are different statements. |
rollup.mismatchedSpans | True when the sources' logs cover meaningfully different periods. Shares remain shares of a sum; reading them as rate comparisons is the mistake this flag names. |
rollup.splitBrains[] | The same label on different models in different sources, judged on each source's dearest model for that label. |
rollup.cacheUnderwater[] | Sources where caching lost money while the fleet's aggregate paid off. Empty when the aggregate itself lost — the whole-fleet report already says so. |
rollup.unmatchedFiles[] | Log files matching no source pattern — in no report above, named rather than silently dropped. |
The plan document#
trazum plan --json (and the file -o writes) is its own contract — a plan
is not a report:
| Field | What it holds |
|---|---|
schemaVersion | 1. Same discipline as the profile document: renames and meaning changes bump it. |
createdAt | When the plan was made (ISO 8601). A prediction nobody dated is a prediction nobody can be held to. |
span | The period the figures cover, or null when the log carried no clock. |
pricingLastReviewed | The price catalogue behind every dollar — the overlay's date when one was in effect, so a later check can tell "the prediction was wrong" from "the prices changed". |
actions[] | Ranked, largest money first. Each has kind (route, batch, route+batch, fix-truncation, fix-caching, edit-file), label, model, and exactly one of savingUsd (projected) or stakeUsd (already spent, measured) — never both, because a projection and a measurement in one field is a number that is neither. An edit-file action, which only --edits writes and which comes last, carries neither: its figure is detail.baseline, measured. |
actions[].assumes[] | What the log cannot confirm, as typed objects ({"kind": "model-capability", "model": ...}, {"kind": "batch-window"}, ...) rather than prose — renderers localize them, and a verification can match them structurally. |
actions[].check | The Trazum command that can check the assumption, when one exists. |
actions[].detail | routeTo for the moved calls; measured for the pieces behind a stake (the wasted and retry dollars, the cache counterfactual); baseline — the slice as the plan saw it (calls, dollars, tokens per call), the "before" a later verification attributes the world's movement against; edit for an edit-file action, its fields in the plan document. |
projectedSavingUsd | Projected savings summed. Additive by construction: same-slice compositions arrive pre-combined inside one action. With --min-usd it covers only the actions the document holds — the file never contradicts itself; what was dropped is stated on the terminal with its worth. |
measuredStakeUsd | Measured stakes summed — money already paid to problems this plan names, kept apart from the projections. Filtered the same way. |
totalUsd | The bill the plan was made against. |
batchExcludedUsd | Input and output dollars no batch action was drawn on: calls already billed at the batch rate, and calls something waited on ("interactive": true on the record, which from-claude-code, from-codex and from-gemini-cli write on every line). Zero when the log marked neither, and absent on a plan saved before the field existed. What the plan left out and why, never a saving. |
The verification document#
trazum verify --json is the plan's reckoning — its own contract:
| Field | What it holds |
|---|---|
schemaVersion | 1. |
planCreatedAt | When the plan was made, carried through — or null for an undated plan. |
planPricing | The catalogue that priced the plan, and the one pricing this check. When they differ, pricesChanged is true and every dollar comparison is two price lists, not one measurement. |
currentPricing | See above. |
pricesChanged | See above. |
actions[] | One verdict per plan action: the action verbatim, outcome (arrived, not-arrived, cannot-tell — three, never two), reason for the third (workload-vanished, fields-stopped, tier-not-recorded), observed (what this log measured: where the money sits, the new retry bill, the new cache delta), attribution (the world's movement from the plan's baseline — calls and tokens per call, before and after, never a verdict), and gateFailing. |
arrived | The three counts. They always sum to actions.length. |
notArrived | See above. |
cannotTell | See above. |
gateFailures | Actions that fail --gate: every not-arrived, plus cannot-tell with reason fields-stopped — a team must not pass on the strength of its own log's silence. A vanished workload and an unrecordable tier fail nothing. |
The history document#
trazum history --json — the long run as data, its own contract:
| Field | What it holds |
|---|---|
schemaVersion | 1. |
periods[] | The stored reports that carry a span, oldest first: name, fromMs/toMs, totalUsd, calls. |
labelSeries[] | Per label, dollars per period — null where the label had no traffic that period, which is absence and not zero. |
modelShareSeries[] | Per model, its share of that period's total — null where absent. The totals can look flat while the mix moves under them. |
cacheShareSeries[] | The share of input tokens served from cache, per period — null where unknowable. |
runs[] | The findings only a series can make: consecutive movement, named — label-spend-climbing, model-share-climbing, cache-share-decaying — each with how many consecutive periods, since which report, the first and last values, and unmeasuredDays: the days inside the run's stretch that no report covers. A run is consecutive reports and reads as consecutive time unless told otherwise, so the caveat travels on the finding rather than in a field the reader has to cross-reference. Shapes, never forecasts: nothing here extrapolates. |
repeatedPlanActions[] | The same action (kind, label, model) in two or more saved plans, with first and last planned dates — a decision nobody is executing. |
unmeasured[] | Stretches of calendar time between the first report's start and the last one's end that no report covers — fromMs, toMs, days, and the reports either side. Arithmetic on the spans, never an inference about a schedule: this module has no idea how often you meant to run anything. A scheduled job that stopped three weeks ago produces a series that looks exactly like a shorter one, and this is the field that tells them apart. |
overlappingReports[] | Two reports covering some of the same days, with how many. history never sums across periods, but a reader with the document in a spreadsheet will, and two reports over the same fortnight count it twice. Named, never merged — which of the two is the better measurement is not knowable from here. |
undatedReports[] | Reports with no span: on no timeline above, named rather than silently absorbed. |
unrecognizedFiles[] | JSON files that are neither a stored report nor a saved plan — in no series, named. |
waivers | The waiver record: since (the day recording started, or null), totalUses, habits[] and neverUsed[]. A habit carries the gate, uses, distinct days, firstDay/lastDay, every reason and expiry in the order first seen, a verdict (used-once, recurring, renewed-without-revisiting, reason-changed) and stillConfigured. Nothing here is derived from the config: a waiver written down and never hit appears in neverUsed with no count, because dead config is not a habit. |
The connected report document#
trazum connect --json (and the file -o writes) is the restricted report a
usage API can support — its own contract, deliberately not the profile
document:
| Field | What it holds |
|---|---|
schemaVersion | 1. |
provider | Which connector produced it. |
granularity | bucketed for a usage API that serves sums; per-call for a source that serves rows. |
span | The window the buckets actually cover, or null when none parsed. |
total | totalUsd, token counts, calls — null when the provider serves no request count, never zero, because zero reads as "no traffic" against real spend — and webSearchRequests and webSearchUsd (since 2.7.5), the searches billed per search inside totalUsd. |
byModel[] | Per model: token counts, the four dollar figures, cachedTokensAtInputRateUsd and cacheWriteUsdIfAssumed1h for the cache counterfactual, writeTtlKnown, and webSearchRequests and webSearchUsd. |
byDay[] | Spend per UTC day, oldest first, with the same nullable calls. |
unpricedModels[] | Models the catalogue could not price: named, with their tokens kept and their money absent. |
gaps[] | What the pull did not get — rate-limited, retention-boundary, cursor-expired, page-limit, unreadable-entry, unreadable-field — and what it got and could not price — unpriced-tier (a tier or speed no catalogue rate is the rate for) and unpriced-web-search (searches on a model with no per-search fee) — each with the detail. A window short by an unknown amount says so here. |
unavailable[] | Findings this source cannot support, each with because and unlockedBy. A restricted report that merely omitted them would read as a report that found nothing. |
The cost answer document#
trazum serve's POST /cost response, and the cost half of spend_guard's
answer. Contracted here since consumers build against it hardest — an agent
reads it on every call. It should have shipped with 1.44 and did not; the
omission is on the record in that release's notes.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
call | The call the caller described, priced: model, inputTokens, outputTokens, estimatedUsd, provenance (always estimated — nobody has sent it) and basis (token-count when the caller counted, heuristic when Trazum did). Null when no call was described or the model could not be priced. |
budget | Where the budget stands: limitUsd, consumedUsd, remainingUsd, provenance (always measured) and the window that figure covers, so staleness is visible rather than implied away. Null when there is no budget or nothing measured. |
verdict | within, over, or cannot-tell. Three, never two. |
restsOn | What the verdict rests on: measured when the budget is already past its limit and no estimate was needed, measured+estimated when it takes the described call to cross. Null on cannot-tell. |
reason | Why it cannot tell, kept apart because the fixes differ: no-budget-configured, nothing-measured, model-unpriced. |
afterCall | Where the budget would stand after this call — usd, with halves.measuredUsd and halves.estimatedUsd beside it. The composed figure never travels without its two halves, so it cannot be mistaken for a measurement. |
policy | The limits policy, judged for this call by the same function every door calls — verdict (within, over, cannot-tell), reason (no-policy when no ceiling applies), and one entry per applicable ceiling in judgements[], each carrying scope, label, limitUsd, verdict, restsOn, reason, measuredUsd, window, afterCallUsd and waived — a waived ceiling keeps its over and loses its refusal, with the waiver's reason and expiry attached so the silence is on the record. Always present: a missing field and a judged absence are different answers. Session identifiers scope the judgement and are never echoed. |
The spend-guard document#
spend_guard over MCP wraps the answer above with what to do instead:
| Field | What it holds |
|---|---|
schemaVersion | 1. |
verdict | yes, no, cannot-tell — mapped from the cost answer. cannot-tell never becomes yes: a guard that permits whatever it cannot judge permits everything the moment its inputs go missing. |
cost | The full cost answer above, halves and provenance intact. |
alternatives | Cheaper ways to make the same call, dearest saving first. Each carries kind (route, batch, route+batch), the model it moves to, savingUsd for this call rather than for a month, the typed assumes it rests on, and fits — only alternatives the prompt fits inside are ever offered. Present on a yes as well, since an agent allowed to spend that could spend less should be told. |
because | One line for a human reading a log. Never the only place a fact appears. |
policy | The limits policy, judged for this call by the same function the gateway and serve call — same shape as the cost answer's policy, field for field, which is the property three-doors.test.js holds. A judged over folds into the verdict as no; an unjudgeable ceiling folds a yes into cannot-tell; no-policy folds as nothing. |
The first-run document#
trazum init --json. The proposal init would write, plus what it declined
and why — the same value the human-readable run renders, so a script and a
person are looking at one document rather than two renderings that can drift.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
config | Exactly the keys init could justify, and nothing else. Serialises to a valid trazum.config.json; a key with no evidence behind it never appears, because a guessed threshold in a generated file reads as somebody's decision six weeks later. |
justified | One entry per key written, each with the observation behind it: key, the value, from (measured, source, walk, environment) and the arithmetic — call counts and day spans, token totals, the file and line a model literal came from. |
declined | One entry per key left out, each with key and a typed why, plus whatever would settle it. nothing-measured, window-too-short (with days), undated-calls (with how many), not-recorded, only-you-know, unprovable, provider-only, conflicting-evidence (with the files), a-budget-is-a-policy (with the measured figure, so the number is in hand even though the threshold is not written). A refusal never arrives bare. |
headline | The single most valuable finding, or null. Carries the slice from billLevers whole — label, model, calls, what it spent, its route and batch levers — plus lever, savingUsd (the slice's combinedUsd, computed and never summed), provenance (always measured) and the days behind it. |
noHeadline | Why there is none, when headline is null: nothing-measured, nothing-could-be-priced, no-lever-clears-the-floor. Three situations a reader would act on differently. |
overwrites | The config already present and which of its keys this proposal would replace, or null when there is no file. An empty keys array is a different statement from null: the file exists and nothing collides. |
unreadable | A usage source that is there and could not be read, with where and because. Null otherwise — and never folded into "no usage found", because the fixes are opposite. |
truncated | Whether the source-file walk hit its cap, so "no provider found" can be told apart from "stopped looking". |
The outcome report document#
Nothing emits this one, and that is the point of documenting it.
trazum profile renders it as terminal text over a log that carries outcomes;
@trazum/core's outcomeReport() computes it. It is a contract so that a tool
of yours can produce one and have trazum conform --contract outcome-report
check it — not a promise that Trazum will hand you the JSON.
The refusals are the part worth copying. A format that carried these fields and dropped the refusals would be worse than no format, because it would look interoperable.
| Field | What it holds |
|---|---|
schemaVersion | 1. Absent from this document from 1.50.4 until it was noticed — the contract required it and the reference producer did not emit it, so the only implementation of this format failed it. |
slices | One entry per declared outcome value, dearest first: value, verdict (success or other), calls, usd. |
undeclared | Values found in the log that the config never declared, each with verdict: "undeclared" and what it cost. Named, never folded into the failures — a typo in an exporter must surface as a typo and not as a shift in the success rate. |
coverage | recorded, parsed and unrecordedUsd. The denominator, stated: "eleven of forty thousand calls recorded an outcome" is a different document from "eleven succeeded". |
successShareOfRecordedUsd | The success rate by spend, or null. By spend rather than by call because this product's subject is money, and the two figures diverge exactly when the expensive half is the half that fails. Null is not zero: zero is a real and terrible measurement, and spelling "nobody told me" the same way destroys the difference. |
noRate | Why there is no rate, when there is none: nothing-recorded, or no-success-values-declared. Null when there is one. A refusal never arrives bare. |
The annual record document#
trazum report --year <yyyy> --json. The year assembled from the store and the
plans already kept — no new data, and nothing computed that cannot be checked
against a document that already exists.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
year | The four-digit year, as a string. |
months | One entry per month that has a record, oldest first: month (YYYY-MM), usd, calls. A month with nothing in it is not here. |
missingMonths | Every month of the year with no record at all, named rather than interpolated. A year report that quietly covers nine months and prints an annual total is wrong by a quarter and says nothing about it. |
totalUsd, totalCalls | Over the months present, and only those. |
promises | planned, arrived, notArrived, cannotTell, projectedUsd. Three outcomes, never two — the third is the one an ordinary annual report folds into the flattering one. |
promises.arrivedUsd | Deliberately absent. A verification says whether each action landed; it has never carried a per-action dollar figure for the saving that arrived. Summing one out of the observations would mean deciding which of them to believe, which is the annual-report arithmetic this document exists to replace. |
outcomes | The outcome coverage for the year — recorded, parsed, unrecordedUsd — or null when nothing recorded one. Attached when something was recorded, not merely parsed: keying on "calls were parsed" made the honest "no outcome was recorded this year" sentence unreachable. |
cannotSay | Typed reasons this record cannot answer something: months-missing, nothing-was-planned, and the rest. The list is part of the document, not a footnote in the terminal rendering. |
The roll-up document#
trazum rollup <document...> --json. Several people's profile documents
merged into one bill — the only document here assembled from measurements this
machine did not take.
It is a format and a merge, not a service. Nothing is uploaded and there is no account: the documents arrive however the team already moves files. What a consumer has to get right is not the arithmetic but the refusals, because a roll-up is the document most likely to be quoted with its caveats one screen away.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
contributors | One entry per merged machine: name, via, totalUsd, calls, span, spanDays, and gaps. |
contributors[].via | The roll-up this contributor arrived through, or null when it was handed over directly. Contributors are flattened, never collapsed — a roll-up of three roll-ups lists twelve machines rather than three, because collapsing them would average twelve sets of gaps into three. |
contributors[].claimed | The window this contributor asked for — sinceMs/untilMs, half-open — or null when it filtered by none. A claim, not a measurement: span says what the records showed and this says what was gone looking for, and only the second can tell a quiet week from an export that stopped. |
contributors[].silence | runs of contiguous days inside a fully bounded claim that recorded nothing, each with from, to and days, plus the total. Named rather than interpolated, the way a year report names its missing months. Null when there is nothing to measure against: no claim, one end only, or a claim too long to enumerate. |
contributors[].undatedExcluded | Records the contributor's own window could not place, because they carried no clock. Null when there was no window, never 0 — zero would say a window excluded nothing. |
contributors[].gaps | That contributor's own blind spots — unreadable-lines, unpriced-calls, no-clock, partial-clock, no-sessions, no-labels, duplicate-lines — each with a detail, and usd/calls that are null where the kind has none. Kept per contributor and never summed: "3% of this roll-up is unpriced" is the sentence that hides "one of your four machines is 90% unpriced". |
rejected | Every contribution handed over and not merged, with name, via and because. via names the roll-up a rejection arrived through: a rejection that stopped travelling at a nesting boundary would mean a broken export could be made to disappear by adding a layer. A machine that contributed nothing must not read like a machine that spent nothing, so this is a field rather than an absence — and the command exits 1 when it is non-empty. |
total | The merged bill: every contributor's priced calls summed, split by input, cache reads, cache writes and output, in tokens and dollars. Same UsageBreakdown shape as the profile document's total. |
unpriced | What the calls no catalogue could price used, kept entirely out of total — the same refusal the single-log report makes, preserved through the merge. |
unpricedModels | Model ids no contributor's catalogue knew, named rather than silently costed at zero. |
byLabel | The merged breakdown per workload label, largest bill first. |
byModel | The same per model. |
byLabelAndModel | The same at the grain a routing decision is made at. |
spendByDay | Dollars per UTC day over the whole fleet — the contributors' own bucketing, never re-derived — each day with its calls, how many contributors saw traffic on it, its byModel split, and topLabel/topLabelUsd that are null when more than one contributor covered the day. No document carries per-label-per-day spend, so the dearest label of a shared day is not knowable from here, and picking the larger of two answers is wrong whenever two runners-up outweigh either winner. |
span | Earliest start to latest end over the contributors that carried a clock, with the calls inside it — or null. |
claimedSpan | Earliest claimed start to latest claimed end, over contributors that stated a fully bounded window, with how many did. Kept apart from span deliberately: one is what the records showed and the other is what somebody went looking for, and merging them answers "what period does this cover" with a figure that is half measurement and half intention. Null when nobody claimed one. |
fieldCoverage | How many merged records carried each optional field — the counts behind what this roll-up cannot answer. |
outcomeTally | The merged outcome tally: byValue, recorded, parsed, unrecordedUsd. Measurement only; which values mean success is declared in a config, not here. |
duplicateLines | Duplicates within each contributor, summed. Overlap between contributors is a different fact and is not here — repeatedContributors and identicalContributions are where that lives. |
identicalContributions | Contributions whose whole text was byte-identical, in groups, with the usd the repeats added. Compared over the entire document rather than a hash, because a collision would report a duplicate that is not one and this figure exists to make somebody distrust a total. Named, never subtracted. |
repeatedContributors | Contributor names appearing more than once across nesting — handing over both a roll-up and one of the machines inside it. Unlike the identical-document check this one can see it: the documents differ, the name does not. Named, never subtracted, because two teams genuinely running an api.json is possible and deciding otherwise by removing money would be a repair this tool never makes. |
notMerged | Findings that exist in the contributions and cannot survive a merge, each with finding, because, and presentIn — the contributors that had one, so a reader knows where to go and look. A roll-up silently missing a finding reads as a fleet that does not have it. |
cannotSay | Typed codes for what this roll-up cannot say about itself — overlap-invisible, mismatched-spans, contributor-without-clock, day-top-label-unknown, identical-contributions, contribution-rejected, unknown-fields-dropped, no-claimed-period, silence-inside-a-claim, claim-not-bounded, claim-too-long-to-enumerate, contributor-named-twice. Codes rather than prose so a consumer can branch and the renderings carry the sentences. |
identicalContributions | groups of contribution names that were the same document, and the usd the repeats added. Merged and stated, never discarded — the rule a single profile already applies to duplicate lines. |
total, unpriced, unpricedModels | Summed across contributors, with unpricedModels a union. Every numeric field of a breakdown is summed except maxCallInputTokens, which is a maximum: four machines' largest calls added together is a call that never happened, in the direction that makes a context window look tight. |
byLabel, byModel, byLabelAndModel | Merged by key, largest bill first. |
spendByDay | Per UTC day, oldest first, with contributors — how many contributed to that day — and byModel. |
spendByDay[].topLabel | The day's dearest label, or null when more than one contributor covered the day, with topLabelUsd null beside it. The merged answer needs per-label-per-day spend no document carries, and the larger of two contributors' answers is wrong whenever a runner-up in both adds up to more than either winner. |
span | Earliest start to latest end over contributors that carried a clock, with calls summed. Null when none did. |
claimedSpan | Earliest claimed start to latest claimed end, over contributors that stated a fully bounded window, with how many did. Kept apart from span deliberately — one is what the records showed and the other what somebody went looking for, and merging them answers "what period does this cover" with a figure that is half measurement and half intention. |
fieldCoverage, outcomeTally, duplicateLines | Summed. duplicateLines is within-contributor only — overlap between contributors is in cannotSay and is not a number. |
repeatedContributors | Contributor names that appear more than once, across nesting. Handing over both a roll-up and one of the machines inside it counts that machine's money twice, and unlike the identical-document check this one can see it — the documents differ, the name does not. Named, never subtracted: two machines genuinely called api.json in two teams is possible, and deciding by removing money is the repair this tool does not make. |
notMerged | Findings that do not roll up, each with finding, because, and presentIn — the contributors that have one, so the reader knows where to go and look. Percentile shapes, conversation growth, repeated turns and truncation retries are all computed from individual calls, and a summary of a summary cannot reproduce them. |
cannotSay | Typed caveats: overlap-invisible, mismatched-spans, contributor-without-clock, day-top-label-unknown, identical-contributions, contribution-rejected, unknown-fields-dropped, no-claimed-period, silence-inside-a-claim, claim-not-bounded, claim-too-long-to-enumerate, contributor-named-twice. Part of the document, not a footnote in the terminal rendering. |
Two of those are enforced, not merely documented.
trazum conform --contract roll-up fails a roll-up of more than one contributor
whose cannotSay omits overlap-invisible, and fails one that rejected a
contribution and does not say so. Two people exporting the same traffic double
the bill and no merge of summaries can see it — a format that carried the fields
and lost that refusal would hand somebody a doubled total that looks audited.
A roll-up is a contribution too. Three teams roll up their own machines and
the organisation rolls up the three — rollup accepts a roll-up document
wherever it accepts a profile, because every summable part of one carries the
same field names. What is not summable is carried through by hand, and each of
those is a refusal that has to survive nesting or the format is worse than no
format: contributors are flattened rather than collapsed, rejections travel with
the roll-up they came through, cannotSay codes are unioned so an inner
blindness never becomes an outer sight, and a finding an inner roll-up refused to
merge does not become mergeable by being handed on.
A claim longer than ten years is kept and not walked. These documents come
from elsewhere, and a contribution claiming untilMs: 1e15 is a malformed
document rather than a team with a long memory — enumerating it would be thirty
million iterations inside a merge somebody ran on four files. The claim survives
into the roll-up; only its silence goes unmeasured, with
claim-too-long-to-enumerate saying so.
A field this version cannot classify is dropped and named, in cannotSay
and again in notMerged with the field's name. A number added after this
roll-up was written may be a sum, a maximum or a ratio, and combining it the
wrong way is worse than leaving it out.
The pulse document#
trazum pulse --json. Whether the things that are supposed to run, ran.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
nowMs | The instant the ages were taken against, so a document read later is still readable. |
maxStaleHours | The threshold the caller stated, or null when none was — in which case nothing is judged. |
beats[] | One per kind: watch-cycle, store-pull, store-coverage. Each carries lastMs (or null), ageHours (whole hours, floored, or null) and a verdict. |
beats[].verdict | never-run — it has never happened here, which is not late: there is no cadence to be late against. not-judged — it happened and no threshold was stated, or it is not a run. within / stale against the stated threshold. |
stale | True when something that has run before is past the threshold. Never true for never-run, and never true for store-coverage. |
store-coverage is reported and never judged. How far the measurements
reach is a provider reporting on its own schedule, not a job that failed;
gating on it with the same threshold would produce a red build for somebody
else's latency. It sits beside the runs because a reader wants both, and it is
a different fact.
The proactive document#
trazum proactive --json, for status, on and off. What speaks first, and whether it is on.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
action | status, on or off: what was asked. status never writes. |
dryRun | True when nothing was written because it was a dry run: asked for with --dry-run, or forced because the input was not a terminal and --yes was not given. Always true for status. |
home | The home directory every path was resolved against. |
project | The directory it ran in: where watch is scheduled and where project MCP config files live. |
items[] | One per item in a fixed order: statusline, watch, mcp. Limited by --only. Read after the action, from the files rather than assumed. |
items[].item | statusline, watch or mcp. |
items[].state | on, off, not-ready (it would work once something is done, and reason says what), not-available (it cannot work on this machine) or could-not-tell (a file could not be read, so no claim is made). |
items[].reason | A stable identifier for why, such as watch.noBudget or file.symlink. Branch on this, never on detail. |
items[].detail | The same reason as a sentence in the reader's language. |
items[].files | The files the item reads or would write, as absolute paths; the crontab is the word crontab. |
items[].notes[] | Things left alone, each with reason and detail: a status line somebody else configured, a file it could not parse, a managed crontab line for another project. |
changes[] | One per item the action looked at, empty for status. |
changes[].item | Which item. |
changes[].outcome | written, would-write (dry run), declined (the answer was no), nothing (nothing to change) or failed. |
changes[].error | null, or { reason, detail } for a refusal or a failed write. A refusal to write names the files the command may touch. |
changes[].files[] | Each file it touched or would touch, with file, and the lines it added and removed as they would be read in the file. A file it created has every line added; a crontab is the word crontab. |
It carries no prompt text and no spend figure. The detail of a watch.noBudget reason may carry the
store's measured total, because that is the figure a person is shown before choosing a limit; no
field holds one. The exit code is 1 when any change failed, and 0 otherwise: an item that is
not-ready or could-not-tell is a report, not an error.
The waste document#
trazum waste <transcript> --json. What a coding-agent session paid for twice or for nothing, priced from its own counts.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
kind | trazum-waste. |
pricing | Where the money comes from. |
pricing.source | Always bundled: this command never reads an overlay. |
pricing.lastReviewed | The catalogue's date. |
pricing.basis | api-equivalent: what the usage costs at list prices, not what was charged. |
session | What was read. |
session.calls | Calls priced. |
session.threads | Conversations they ran in: the main one and each subagent are one each. |
session.files | Transcript files read. |
cannotTell | null, or unreadable when the transcript could not be paired with its usage, or a call could not be read as usage. Nothing below is computed then. |
unpricedModels | Models in the session the catalogue has no price for. Their calls are in no figure, so each figure is a floor. |
reads | The same file read again. |
reads.minReads | The fewest reads of one path that were listed (--min-reads). It chooses what is listed and not what is counted. |
reads.findings[] | At most 20 paths, the dearest first. |
reads.findings[].path | The path as the tool call named it. |
reads.findings[].reads | Reads of it that were not an error, in every conversation. |
reads.findings[].repeats | Reads of the same range as an earlier one in the same conversation with no Edit, Write, MultiEdit or NotebookEdit of the path between. |
reads.findings[].measured | Repeats whose call made one tool call, so the growth it caused is known. The rest are counted and not priced. |
reads.findings[].tokens | The prompt growth of the measured repeats, summed: P(next) - P(this) - output(this) per repeat. |
reads.findings[].usd | What carrying those tokens cost, as the difference between the conversation priced as it was and priced without them, or null where nothing was measured. A lower bound. |
reads.omitted | Paths read again and not listed, under minReads or past the 20. |
reads.repeats, reads.measured | The same two counts over the listed paths. |
reads.usd | All listed repeats taken out together, or null where none was measured. It can differ slightly from the sum of the rows where a rate depends on prompt size. |
mcp | MCP servers loaded and never called. |
mcp.source | transcript (read from what Claude Code records as loaded), flag (named with --mcp-servers) or none, which means the list is unknown and nothing is claimed. |
mcp.loaded, mcp.called | Servers loaded, and how many of them were called at least once. |
mcp.unused[] | Loaded and never called, by name. No field of money: see mcp.unpricedReason. |
mcp.unused[].server | The server's name. |
mcp.unused[].tools | The tools it brought where the transcript names them, otherwise null. |
mcp.unpricedReason | definitions-not-recorded: a server's tool-definition tokens are not in a transcript, and where tools are deferred they are not sent until asked for. |
claudeMd | A CLAUDE.md carried on every turn. The one estimated figure. |
claudeMd.checked | Whether a size was available to look at: false when no CLAUDE.md was found in the session's directory and none was named. |
claudeMd.bandPct | The estimator's published band, in percent, either side of the token estimate. |
claudeMd.findings[] | One per file sized. |
claudeMd.findings[].path, claudeMd.findings[].bytes | The file and its size from a stat. Its content is never opened. |
claudeMd.findings[].tokens | ceil(bytes / 4), the estimator's divisor for text it cannot read. An estimate. |
claudeMd.findings[].usd | What carrying that many tokens cost on every call of the main thread: written by the first call and read by the rest, and written again after a compaction. |
claudeMd.findings[].usdLow, claudeMd.findings[].usdHigh | The same at the band's two ends. |
claudeMd.findings[].calls | The calls of the main thread that carried it. Subagents are not counted. |
limitations[] | What this report cannot say, in the words the terminal prints. |
It carries paths and counts and nothing else of the session. No message text, command, tool result or file content is read into it. The directory a session ran in is read to find a CLAUDE.md and is not in the document; the paths in it are the ones tool calls named and the one CLAUDE.md that was sized. The exit code is 0 whatever it found: it reports and does not gate.
The bench document#
trazum bench --json. What this machine measures, one shot per workload.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
node, platform, arch | The runtime the numbers were taken on — a measurement without its machine is a rumour. |
cpus, cpuModel | How many, and what kind. cpuModel is null where the OS does not say. |
workloads[] | One per standard workload, in a fixed order. |
workloads[].id, workloads[].wallMs | Which workload, and its wall time — not rounded: the terminal rounds, the JSON does not. |
workloads[].calibrationMs, workloads[].ratio | A fixed calibration loop timed in the same process right after the workload, and the workload's wall time divided by it. The ratio is the number a gate can hold: a CI runner lies about wall time to the workload and the yardstick by the same amount, and the lie cancels out. |
workloads[].bytes / .lines / .files | The input's size, in the unit the workload is named by. Exactly one is a number; the other two are null, never zero. |
workloads[].maxRssBytes | Peak RSS of the workload's own child process — what the operating system billed it, which is why each workload gets a process to itself. Named RSS because that is what it is: a heap high-water mark is not observable from inside a synchronous run without moving the number. |
With --workload <id>, the output is the single measurement object — the same
shape as one entry of workloads[] — because that is what the parent run
collects from each child, and two shapes for one fact is one too many.
The document never carries a verdict, whatever flags ran it. --record
writes the measured ratios to a separate baseline file — schemaVersion: 1
and one { id, ratio } per measured workload, meant to be committed — and
--against <file> --max-ratio <n> exits 1 when any measured workload is past
its recorded ratio times the stated factor, saying so on stderr. The gate is
the exit code, the way trazum check has always gated; the JSON shape does
not change with the gate flags, so a consumer never meets a field that is
sometimes there. A baseline whose schemaVersion this Trazum does not know is
a loud error naming --record, never a best-effort read — the file is
committed, so it crosses upgrades.
The rule-yield document#
trazum rules --measure <dir> --json. What each deterministic rule actually
recovers over a set of prompts.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
root, files, prompts, truncated | Where it looked, how many files it read, how many prompts came out of them, and whether the walk was cut short. |
tokensBefore | Tokens across every prompt before anything ran. |
tokensSaved | Tokens the rules save — the whole run's saving minus floor. |
floor | Tokens the optimiser saves with every rule disabled: normalisation that happens either way. Named rather than folded in — crediting it to the rules is how a headline percentage survives on a corpus where the rules recover nothing, and the first version of this measurement did exactly that. |
rules[] | Per rule: id, alone (tokens saved when it is the only rule running), marginal (tokens the whole set loses when it is removed), and prompts (how many it changed, running alone). Largest marginal first. |
sumOfAlone | alone summed over every rule, stated beside tokensSaved and deliberately not reconciled with it. The gap between them is the overlap; a single total would be the one number that cannot be true. |
redundantHere | Rules with a non-zero alone and a zero marginal — every token they find, something else finds too. An overlap, not a defect, and not a claim that a real run counts those tokens twice: the applied optimiser credits exactly one rule, and which one is decided by the catalogue's order. A repeated stanza is reported as one repeated paragraph rather than three repeated lines, for the same saving. |
inertHere | Rules that never fired in this corpus. A fact about these files, never about the rules: one that finds nothing here has not been shown to find nothing anywhere. |
firedWithoutSavingHere | Rules that fired and recovered nothing — they changed the prompt and the token count did not move. Kept apart from inertHere because the two look identical in a saving column and mean opposite things: a rule that never fired has not been exercised, and one that fired and saved nothing is altering somebody's instruction for no measured benefit. That is a finding about the rule rather than about the corpus. |
tokenSource | heuristic or external. Every figure inherits the counter's band, so a rule whose yield is a handful of tokens is inside the noise. |
Why two figures per rule. alone and marginal diverge exactly where rules
overlap: duplicate-lines and duplicate-blocks both see a repeated stanza, so
each has a real alone and a marginal of zero. Reporting alone by itself
makes an overlapping rule look load-bearing; reporting marginal by itself
makes it look inert. Both travel, and nothing here adds them together.
The prompt-draft document#
trazum write --json, and what @trazum/core's assemble() returns. A prompt
somebody was interviewed into, and what the interview could not get out of them.
Nothing here is generated. The words are the author's answers, placed under headings in a fixed order; a writer that paraphrased them would be answering a question nobody asked it.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
prompt | The assembled prompt, or null when required answers are missing. Null and never "" — an empty string reads as a prompt that came out blank, and "not built" and "built and empty" are different statements. |
sections | One entry per section that got words: its section, the text written under the heading, and from — the slots that supplied it, in the order they appear. A section nobody answered is absent rather than present and empty. |
answered | The slots that were answered. |
declined | The slots somebody was asked and declined. Kept apart from missing: a decision is not a gap, and folding the two would turn "I do not need that" into "nobody got round to it". |
missing | Required, open and still unanswered. Empty exactly when prompt is a string — the refusal and the output are the same fact read two ways, and they can never disagree. |
measured | The three claims, or null when there is no prompt to measure — never an object of zeros, because a draft that was never assembled has not been measured as costing nothing. complete is the checklist with its gaps named and no score: required, answered, declined, missing. cheap is tokens, tokenSource, model, monthlyUsd (null when it cannot be priced, never 0), provenance — always estimated, carried inside the object so the figure cannot travel without it — budgetUsd, and a verdict of within, over or cannot-tell with the reason for the third (no-budget, no-model, model-unpriced). clean is what trazum optimize still recovers: the rules that fired with their hits, and tokensRecoverable. The target is nothing, and a non-zero figure is printed rather than quietly fixed. |
The section order is fixed and the headings are English in every locale.
They are structure rather than prose — a contract with the model — and the
promise is that the same answers produce the same prompt byte for byte on any
machine and in any locale. A heading that moved with TRAZUM_LOCALE would
make the prompt a function of the machine that ran the interview.
The gateway refusal document#
The body trazum gateway returns with HTTP 402 when a call is over budget.
402 rather than 429 on purpose: every provider SDK retries a 429 automatically,
which would turn one refusal into a retry storm against a gateway that refuses
every time.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
error | {type: "trazum_budget_refusal", message} — shaped like a provider error so an SDK's own error path handles it, and typed so it cannot be mistaken for one. |
reason | budget-exhausted (already past, measured), call-would-cross (this call takes it past), limit-over (a ceiling in the limits policy is over — policy names which), or cannot-tell-and-closed (nothing could be judged and the operator chose fail-closed). |
cause | Why it could not be judged, when that is the reason: no-budget, nothing-measured, model-unpriced, output-unbounded (missing or invalid output-token limit), limit-unjudged (a limits ceiling could not be judged — policy says why). Null otherwise. |
restsOn | measured when the budget was already spent and nothing was estimated to reach the verdict; measured+estimated when it takes an estimate of this call to cross. Null on cannot-tell-and-closed. The two halves never merge. |
standing | The budget position the refusal rested on — limitUsd, consumedUsd, provenance (always measured) and asOfMs, so a caller can see how stale the figure is rather than assume it is current to the second. |
estimatedUsd | What this call was priced at, or null when the model could not be priced. |
alternatives | Cheaper ways to make the same call, dearest saving first: kind (route or batch), the model it moves to, savingUsd for this call, and the typed assumes it rests on. A refusal never arrives bare. Only models the call fits inside are ever offered. |
policy | The limits policy, judged for this call — same judge and same shape as serve's and the spend guard's policy, field for field. A refusal with reason: limit-over names the crossed ceiling here, and because states the limit, the measured spend and the period in one auditable sentence. |
No prompt, no completion, no credential. The body passed through the process and does not come back out of it — a test asserts a refusal carries no trace of the request text.
A 502 with error.type: "trazum_upstream_unreachable" is a different thing
entirely: the provider could not be reached. A caller needs to tell "your
provider is down" from "you are out of money", and a proxy that blurred them
would send somebody to fix the wrong thing at the worst possible moment.
The position document#
trazum position <usage.jsonl> --json — where the month stands, measured from
one named log. @trazum/core computes it with positionReport, the same pure
function every surface answers with, so a page and a terminal cannot disagree
about where the month is.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
source | Always usage-log — the document's own signature, and the statement of what was measured: this log, priced record by record. The store's provider-billed monthly standing is a different measurement and is never merged in. |
month | The UTC month as a period: id (YYYY-MM), fromMs, toMs, days. |
positions | One standing per measurable ceiling, in config order: scope (month, day, label), label, limitUsd, measuredUsd, remainingUsd, the window the figure covers, daysMeasured and daysElapsed — the denominator on every figure — a verdict (within, over, cannot-tell), and distance. |
positions[].distance | Division on the past, or null. daysAway is remainingUsd ÷ usdPerDay with usdPerDay and its own denominator overDays beside it, and arithmetic: "division" stated in the number. Null under the seven-day floor, on an over, and on a zero rate — absent, never zeroed, and there is no field naming a date anywhere in this document. |
unmeasured | Configured ceilings this log cannot answer for, each with scope, label, limitUsd and a why: no-clock, no-labels, nothing-recorded, or label-unseen — a label the log records but has not seen this month, which may be renamed or idle and is neither "under budget". |
cannotSay | Typed codes for what the document deliberately does not answer: session-limit-at-the-doors (a per-session ceiling is judged per call at the doors, and a "session position for the month" would be an average wearing a limit's name) and no-ceiling-configured (no monthly budget and no limits, so there is no ceiling to state a position against). Codes rather than prose, like every other document here, so a consumer can branch and each rendering carries the sentence in its own language. |
unpricedRecords | Records naming a model the catalogue cannot price. They contribute nothing to any figure above — money nobody can see, counted instead of dropped. |
The routing-measurement document#
trazum route <usage.jsonl> --prompt-file <file> --cases <file> --json --yes —
whether the cheaper model still does the job, on the workload profile already
priced. Two measurements meet here and stay apart: the money comes from the
usage log, the agreement comes from calls actually made.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
slice | The workload measured, straight from the bill: label, model and modelName, calls, spentUsd, the route that was tried (candidate.id, candidate.displayName, savingUsd), batch, combinedUsd, and shareOfBill. The saving is for these calls, and shareOfBill is what they are of the whole log — not of this slice. |
evaluation | The measurement: provider, model, candidateModel, verdict, selfAgreement, crossAgreement, callsMade and cases. |
evaluation.verdict | holds (the cheaper model's answers moved no more than the model moves against itself), diverges (they moved further), or inconclusive (the model disagreed with itself too much for any of this to mean anything). Agreement is not correctness: this measures whether the answers moved, never whether they were ever right. |
evaluation.selfAgreement | The model's agreement with itself on the same prompt. The yardstick — every other figure here is read against it, and a document that carried the cross rate alone would be a number without its denominator. |
evaluation.crossAgreement | Mean agreement between the model in the log and the candidate, same prompt on both sides. |
evaluation.callsMade | Calls actually spent reaching the verdict, so the bill is never a surprise. |
evaluation.cases | One entry per input: selfSimilarity and crossSimilarity. The inputs themselves are not here, and neither are the answers. |
No prompt, no cases, no completions, no credential. The prompt under test, the inputs it ran against and everything the models said are what this command reads; none of it comes back out. A test plants a marker in the prompt and asserts the document does not carry it.
The example-pruning document#
trazum prune --prompt-file <file> --cases <file> --json --yes — which few-shot
examples are paying for themselves, measured by removing each one and asking
whether the answers moved.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
provider | The provider the calls went to. |
model | The model that answered. |
selfAgreement | The model's agreement with itself given the full prompt. The yardstick every removal is judged against. |
recoverableTokens | Tokens held by examples whose removal changed nothing this measurement can see. Tokens, not money: what they cost depends on the model and the call volume, and this command measures neither. |
callsMade | Calls actually spent. |
contributions | One entry per example, in prompt order. |
contributions[].index | Position in the prompt's example block, from zero. Which example, without quoting it — the caller already has the prompt. |
contributions[].tokens | What that example costs to send. |
contributions[].agreementWithout | Mean agreement between the full prompt's answer and the answer with this example removed, across every input. |
contributions[].verdict | indistinguishable and within-noise both mean the removal changed nothing measurable; diverges means it did; inconclusive means the model disagreed with itself too much for the comparison to mean anything. |
No example text. A few-shot example is prompt text, and the terminal rendering quotes its first line; the document carries the index and the token count instead. Same test, same planted marker.
The store inventory document#
trazum store --json — what the local store holds, resolved and priced. The
store is append-only and converges on read, so this is the state a reader would
see, not the state on disk line by line.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
providers | One entry per provider held, oldest first by the span it covers: provider, records, the span those records cover, calls (null when no provider in the set serves request counts), and the models seen. |
totalRecords | Records the store resolves to, after overlapping pulls are collapsed. Not lines on disk — a re-pull of a period already held converges to one record, and the difference is what possiblyDouble counts. |
span | The stretch every held record falls inside — fromMs, toMs — or null when nothing is held. |
possiblyDouble | Records the store could not tell apart from each other. Counted rather than dropped or merged: a figure that silently deduplicated two genuine pulls would be quietly wrong, and one that summed two copies of the same pull would be quietly wrong the other way. |
unknownVersion | Records written by a schema this build does not know. They are held, counted, and contribute to nothing — a newer Trazum wrote them and this one will not guess at what they mean. |
totalUsd | What the resolved records priced to, from the catalogue. unknownVersion and unreadable contribute nothing to it. |
unreadable | Lines that would not parse, each named by file and line. The path is store-relative — the provider directory and the month file — which is what an operator needs to find the line and nothing more. |
No prompt text, no session key, no absolute path. The store holds billing records, never call bodies; the inventory holds counts of those records.
The conformance document#
trazum conform <file> --json — whether somebody else's document or log is one
Trazum can read, and what is missing when it is not. This is the document a
connector author checks their own emitter against, so it is the one place a
refusal has to be more useful than "invalid".
| Field | What it holds |
|---|---|
schemaVersion | 1. |
contract | Which contract the input looked like, or null when nothing did. Named with --contract or inferred from the shape. |
because | Why nothing matched. Present only when contract is null, and never a bare "invalid": a refusal with nothing after it is indistinguishable from a bug, which is the rule this project applies to every other refusal. |
problems | One entry per fault: at (line 12 for a log, a dotted path inside a document), kind, and a detail naming the field and what the contract asks of it. |
problems[].kind | missing (a required field is absent), wrong-type (present, and not the type the contract states), absence-as-zero (present as 0 where the contract requires null — the fault that turns "nobody measured it" into "it was nothing"), or unreadable (the line or the document would not parse at all). |
unavailable | Findings a valid document of this shape simply cannot support: the finding, the because, and the unlockedBy that would buy it. A conforming log with no labels is not broken, and it also cannot produce a per-workload bill — both are true, and only saying the first would be the flattering half. |
records | Records examined, for a log. Null for a single document, which is one thing rather than a count of things. |
conforms | The verdict. True only when problems is empty — unavailable never makes a document non-conforming. |
The watch cycle document#
trazum watch --json — one cycle of the spend watcher, whether it fired or
not. A cycle that reports nothing is not the same as a cycle that had nothing
to report, and this document is shaped so a reader cannot mistake one for the
other.
| Field | What it holds |
|---|---|
schemaVersion | 1. |
firedAtMs | The instant the cycle ran, so a consumer can see how stale a figure is rather than assume it is current. |
crossings | Gates over their limit, and news this cycle. Each carries the gate, the measuredUsd that crossed and the limitUsd it crossed, the window the figure covers, the day a day gate means, and provenance. |
crossings[].provenance | Always measured. A projected crossing is not a crossing, and the field is emitted anyway so a later version of this file cannot smuggle an estimate past a reader by leaving the question unasked. |
suppressed | Still over the limit, and already reported on an earlier cycle. Same shape as crossings. These are why a quiet cycle is not a clean one: the alert was suppressed, the crossing was not, and only one of those is news. |
abstentions | Gates that could not be judged, which is neither a pass nor a failure: the gate, a reason (window-too-short, dimension-unavailable), and a detail with coveredMs and neededMs where there is a figure to give. A gate silently skipped for a week reads exactly like a gate that has been passing for a week. |
gap | The stretch this cycle did not watch — fromMs, toMs — when the watcher was down or is starting for the first time. Null when there is none. A resumed watcher that said nothing would imply coverage it did not have. |
The task document#
Available in CLI/MCP 2.6.0 and later. One versioned task family contains three
variants. Branch on version and kind, not schemaVersion. conform and
schema do not support this family. Saved report inputs are validated strictly
by parseTaskReport and the task workflow; unknown fields and inconsistent
evidence are refused. Valid input is not authenticated evidence.
The task efficiency output contract documents nested fields, limits, coverage and privacy. All task outcomes and policy use are caller declarations; the comparison observes differences without establishing causal savings. Task policy export is plain text.
Report#
CLI task analyze emits this object; MCP analyze_task wraps it in report.
Save this object, not the MCP response envelope, for later comparison.
The Tasks dashboard imports and exports this
same report object, and exports the comparison object below without a wrapper.
| Field | What it holds |
|---|---|
version | 1, the task document family version. |
kind | trazum-task. |
task | Declared task ID, type, criterion, policy ID, outcome and assessor. |
usage | Recorded token counters, API-equivalent valuation, unpriced coverage and pricing provenance: bundled catalogue source, review date and API-equivalent basis. Missing evidence does not establish zero usage. |
sources | Source indexes, harness formats, non-cryptographic reuse checks, converter diagnostics and completeness limits; no raw session IDs or file paths. |
coverage | Observed harnesses, recognized models and evidence gaps. |
tools | Call/result coverage, replayed calls and repeated-result findings with local source/line references. |
limitations | Preserved evidence and interpretation boundaries. |
Comparison#
CLI task compare and MCP compare_tasks emit this object from two validated
task reports. Neither report is mutated.
| Field | What it holds |
|---|---|
version | 1. |
kind | trazum-task-comparison. |
verdict | lower-usage, higher-usage, similar-usage, quality-regressed or inconclusive. |
reasons | Why the observation supports a verdict or cannot be compared. |
tokenChange | before, after, delta and percent for a supported accepted comparison; otherwise null. |
limitations | Evidence and interpretation boundaries, including absence of causal proof. |
Policy receipt#
CLI task apply and task revert emit this receipt. It records the managed
instruction block's state, not whether a harness loaded or obeyed it.
| Field | What it holds |
|---|---|
version | 1. |
kind | trazum-task-policy. |
policyId | repeat-review-v1. |
applied | true after apply, false after revert. |
changed | Whether this invocation changed the selected instruction file; idempotent repeats return false. |
The capability an advisory names#
No field of any document above carries it, and this is where a consumer who
reads the model-downgrade advisory in trazum optimize --json, or in the
response of POST /api/optimize, will look. The advisory's detail is a
sentence for a person, and it quotes what the heuristic judged the prompt to
need in the words a catalogue model's capability has: small, mid or
large. Until 3.0.0 it quoted haiku, sonnet or opus. Read the sentence
for display and never parse it: the id, the severity and estimatedMonthlyUsd
are the fields. The same three names are what recommendTier returns and what
cheapestOfCapability takes in code. capability-names.test.js, in the core
and in the CLI, and api.test.mjs hold that none of the old three is quoted on
those surfaces. The MCP server's optimize_prompt prints an advisory's title
and not its detail, so no name reaches it.