Skip to content
Trazum

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.

  • schemaVersion is the only thing you must branch on. It starts at 1 and 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 null or an empty array, never zero. span: null means 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#

FieldWhat it holds
schemaVersionThe contract version. 1 today.
totalEvery 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.
byLabelThe same breakdown per workload label, largest bill first.
byModelThe same per model, largest bill first. Unpriced models appear with tokens and zero dollars.
byLabelAndModelThe grain a routing decision is made at: one row per workload and model.
unpricedModelsModel ids the price catalogue does not know, named rather than silently costed at zero.
unpricedWhat those calls used, kept entirely out of total.
skippedLines1-based positions of lines that could not be read.
conversationsWhat 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.
hasSessionsWhether any record carried a session at all. Distinguishes "no growth" from "not measured".
outputShapesWhere output spend concentrates, with the max_tokens ceilings the measured answers fit within.
inputShapesHow 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.
repeatedTurnsCalls 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.
truncationRetriesTruncated 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.
spanThe period the log covers, or null. Stated, never extrapolated.
spendByDayExact dollars per UTC day, with the day's biggest label and the day's spend per model — the series modelMixDrift summarises, whole.
duplicateLinesLines identical to an earlier one (timestamped records only), and what they added to the total — the shape a doubled export has.
fieldCoverageHow 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.
outcomeTallyWhat 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.
outcomeTallyByLabelThe 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.
outcomeTallyByModelThe same, per model.
spendByHourExact dollars per hour of the UTC day — the shape that says whether the Batch API applies.
modelMixDriftEach 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.
cacheTtlFitWhether each slice's cache TTL fits how fast its turns arrive.
timeWindowThe --since/--until filter applied, with the clockless calls it excluded. null when unfiltered.
singleTurnCacheWritesCache writes by conversations that never came back — a ceiling, or a fact when the slice read nothing.
sessionCostsWhat one session costs, its subagents included: median, p95 and maximum per slice.
sessionSpendThe 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.
cacheWhether caching paid for itself over the whole log, with the worst case when the TTL was not recorded.
cacheByLabelThe same verdict per workload — where a total hides a loss.
pricingWhich 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.
leversWhat would actually move the bill: routing, the Batch API, and the ceiling on prompt shortening.
againstPresent only with --against: the previous total, the delta, and the drivers per label and per model.
contextPressureSlices 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.
whatIfPresent 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:

FieldWhat it holds
schemaVersion1. 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.
rollupThe 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.callsThe 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.worstThe dearest source with its share, or null when the fleet spent nothing — "nothing is bleeding" and "the worst of nothing" are different statements.
rollup.mismatchedSpansTrue 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:

FieldWhat it holds
schemaVersion1. Same discipline as the profile document: renames and meaning changes bump it.
createdAtWhen the plan was made (ISO 8601). A prediction nobody dated is a prediction nobody can be held to.
spanThe period the figures cover, or null when the log carried no clock.
pricingLastReviewedThe 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[].checkThe Trazum command that can check the assumption, when one exists.
actions[].detailrouteTo 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.
projectedSavingUsdProjected 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.
measuredStakeUsdMeasured stakes summed — money already paid to problems this plan names, kept apart from the projections. Filtered the same way.
totalUsdThe bill the plan was made against.
batchExcludedUsdInput 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:

FieldWhat it holds
schemaVersion1.
planCreatedAtWhen the plan was made, carried through — or null for an undated plan.
planPricingThe 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.
currentPricingSee above.
pricesChangedSee 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.
arrivedThe three counts. They always sum to actions.length.
notArrivedSee above.
cannotTellSee above.
gateFailuresActions 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:

FieldWhat it holds
schemaVersion1.
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.
waiversThe 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:

FieldWhat it holds
schemaVersion1.
providerWhich connector produced it.
granularitybucketed for a usage API that serves sums; per-call for a source that serves rows.
spanThe window the buckets actually cover, or null when none parsed.
totaltotalUsd, 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.

FieldWhat it holds
schemaVersion1.
callThe 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.
budgetWhere 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.
verdictwithin, over, or cannot-tell. Three, never two.
restsOnWhat 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.
reasonWhy it cannot tell, kept apart because the fixes differ: no-budget-configured, nothing-measured, model-unpriced.
afterCallWhere 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.
policyThe 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:

FieldWhat it holds
schemaVersion1.
verdictyes, 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.
costThe full cost answer above, halves and provenance intact.
alternativesCheaper 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.
becauseOne line for a human reading a log. Never the only place a fact appears.
policyThe 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.

FieldWhat it holds
schemaVersion1.
configExactly 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.
justifiedOne 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.
declinedOne 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.
headlineThe 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.
noHeadlineWhy 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.
overwritesThe 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.
unreadableA 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.
truncatedWhether 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.

FieldWhat it holds
schemaVersion1. 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.
slicesOne entry per declared outcome value, dearest first: value, verdict (success or other), calls, usd.
undeclaredValues 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.
coveragerecorded, parsed and unrecordedUsd. The denominator, stated: "eleven of forty thousand calls recorded an outcome" is a different document from "eleven succeeded".
successShareOfRecordedUsdThe 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.
noRateWhy 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.

FieldWhat it holds
schemaVersion1.
yearThe four-digit year, as a string.
monthsOne entry per month that has a record, oldest first: month (YYYY-MM), usd, calls. A month with nothing in it is not here.
missingMonthsEvery 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, totalCallsOver the months present, and only those.
promisesplanned, arrived, notArrived, cannotTell, projectedUsd. Three outcomes, never two — the third is the one an ordinary annual report folds into the flattering one.
promises.arrivedUsdDeliberately 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.
outcomesThe 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.
cannotSayTyped 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.

FieldWhat it holds
schemaVersion1.
contributorsOne entry per merged machine: name, via, totalUsd, calls, span, spanDays, and gaps.
contributors[].viaThe 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[].claimedThe 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[].silenceruns 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[].undatedExcludedRecords 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[].gapsThat 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".
rejectedEvery 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.
totalThe 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.
unpricedWhat the calls no catalogue could price used, kept entirely out of total — the same refusal the single-log report makes, preserved through the merge.
unpricedModelsModel ids no contributor's catalogue knew, named rather than silently costed at zero.
byLabelThe merged breakdown per workload label, largest bill first.
byModelThe same per model.
byLabelAndModelThe same at the grain a routing decision is made at.
spendByDayDollars 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.
spanEarliest start to latest end over the contributors that carried a clock, with the calls inside it — or null.
claimedSpanEarliest 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.
fieldCoverageHow many merged records carried each optional field — the counts behind what this roll-up cannot answer.
outcomeTallyThe merged outcome tally: byValue, recorded, parsed, unrecordedUsd. Measurement only; which values mean success is declared in a config, not here.
duplicateLinesDuplicates within each contributor, summed. Overlap between contributors is a different fact and is not here — repeatedContributors and identicalContributions are where that lives.
identicalContributionsContributions 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.
repeatedContributorsContributor 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.
notMergedFindings 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.
cannotSayTyped 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.
identicalContributionsgroups 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, unpricedModelsSummed 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, byLabelAndModelMerged by key, largest bill first.
spendByDayPer UTC day, oldest first, with contributors — how many contributed to that day — and byModel.
spendByDay[].topLabelThe 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.
spanEarliest start to latest end over contributors that carried a clock, with calls summed. Null when none did.
claimedSpanEarliest 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, duplicateLinesSummed. duplicateLines is within-contributor only — overlap between contributors is in cannotSay and is not a number.
repeatedContributorsContributor 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.
notMergedFindings 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.
cannotSayTyped 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.

FieldWhat it holds
schemaVersion1.
nowMsThe instant the ages were taken against, so a document read later is still readable.
maxStaleHoursThe 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[].verdictnever-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.
staleTrue 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.

FieldWhat it holds
schemaVersion1.
actionstatus, on or off: what was asked. status never writes.
dryRunTrue 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.
homeThe home directory every path was resolved against.
projectThe 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[].itemstatusline, watch or mcp.
items[].stateon, 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[].reasonA stable identifier for why, such as watch.noBudget or file.symlink. Branch on this, never on detail.
items[].detailThe same reason as a sentence in the reader's language.
items[].filesThe 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[].itemWhich item.
changes[].outcomewritten, would-write (dry run), declined (the answer was no), nothing (nothing to change) or failed.
changes[].errornull, 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.

FieldWhat it holds
schemaVersion1.
kindtrazum-waste.
pricingWhere the money comes from.
pricing.sourceAlways bundled: this command never reads an overlay.
pricing.lastReviewedThe catalogue's date.
pricing.basisapi-equivalent: what the usage costs at list prices, not what was charged.
sessionWhat was read.
session.callsCalls priced.
session.threadsConversations they ran in: the main one and each subagent are one each.
session.filesTranscript files read.
cannotTellnull, 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.
unpricedModelsModels in the session the catalogue has no price for. Their calls are in no figure, so each figure is a floor.
readsThe same file read again.
reads.minReadsThe 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[].pathThe path as the tool call named it.
reads.findings[].readsReads of it that were not an error, in every conversation.
reads.findings[].repeatsReads 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[].measuredRepeats whose call made one tool call, so the growth it caused is known. The rest are counted and not priced.
reads.findings[].tokensThe prompt growth of the measured repeats, summed: P(next) - P(this) - output(this) per repeat.
reads.findings[].usdWhat 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.omittedPaths read again and not listed, under minReads or past the 20.
reads.repeats, reads.measuredThe same two counts over the listed paths.
reads.usdAll 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.
mcpMCP servers loaded and never called.
mcp.sourcetranscript (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.calledServers 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[].serverThe server's name.
mcp.unused[].toolsThe tools it brought where the transcript names them, otherwise null.
mcp.unpricedReasondefinitions-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.
claudeMdA CLAUDE.md carried on every turn. The one estimated figure.
claudeMd.checkedWhether a size was available to look at: false when no CLAUDE.md was found in the session's directory and none was named.
claudeMd.bandPctThe estimator's published band, in percent, either side of the token estimate.
claudeMd.findings[]One per file sized.
claudeMd.findings[].path, claudeMd.findings[].bytesThe file and its size from a stat. Its content is never opened.
claudeMd.findings[].tokensceil(bytes / 4), the estimator's divisor for text it cannot read. An estimate.
claudeMd.findings[].usdWhat 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[].usdHighThe same at the band's two ends.
claudeMd.findings[].callsThe 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.

FieldWhat it holds
schemaVersion1.
node, platform, archThe runtime the numbers were taken on — a measurement without its machine is a rumour.
cpus, cpuModelHow 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[].wallMsWhich workload, and its wall time — not rounded: the terminal rounds, the JSON does not.
workloads[].calibrationMs, workloads[].ratioA 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 / .filesThe input's size, in the unit the workload is named by. Exactly one is a number; the other two are null, never zero.
workloads[].maxRssBytesPeak 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.

FieldWhat it holds
schemaVersion1.
root, files, prompts, truncatedWhere it looked, how many files it read, how many prompts came out of them, and whether the walk was cut short.
tokensBeforeTokens across every prompt before anything ran.
tokensSavedTokens the rules save — the whole run's saving minus floor.
floorTokens 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.
sumOfAlonealone 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.
redundantHereRules 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.
inertHereRules 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.
firedWithoutSavingHereRules 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.
tokenSourceheuristic 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.

FieldWhat it holds
schemaVersion1.
promptThe 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.
sectionsOne 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.
answeredThe slots that were answered.
declinedThe 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".
missingRequired, 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.
measuredThe 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.

FieldWhat it holds
schemaVersion1.
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.
reasonbudget-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).
causeWhy 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.
restsOnmeasured 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.
standingThe 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.
estimatedUsdWhat this call was priced at, or null when the model could not be priced.
alternativesCheaper 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.
policyThe 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.

FieldWhat it holds
schemaVersion1.
sourceAlways 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.
monthThe UTC month as a period: id (YYYY-MM), fromMs, toMs, days.
positionsOne 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[].distanceDivision 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.
unmeasuredConfigured 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".
cannotSayTyped 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.
unpricedRecordsRecords 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.

FieldWhat it holds
schemaVersion1.
sliceThe 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.
evaluationThe measurement: provider, model, candidateModel, verdict, selfAgreement, crossAgreement, callsMade and cases.
evaluation.verdictholds (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.selfAgreementThe 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.crossAgreementMean agreement between the model in the log and the candidate, same prompt on both sides.
evaluation.callsMadeCalls actually spent reaching the verdict, so the bill is never a surprise.
evaluation.casesOne 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.

FieldWhat it holds
schemaVersion1.
providerThe provider the calls went to.
modelThe model that answered.
selfAgreementThe model's agreement with itself given the full prompt. The yardstick every removal is judged against.
recoverableTokensTokens 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.
callsMadeCalls actually spent.
contributionsOne entry per example, in prompt order.
contributions[].indexPosition in the prompt's example block, from zero. Which example, without quoting it — the caller already has the prompt.
contributions[].tokensWhat that example costs to send.
contributions[].agreementWithoutMean agreement between the full prompt's answer and the answer with this example removed, across every input.
contributions[].verdictindistinguishable 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.

FieldWhat it holds
schemaVersion1.
providersOne 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.
totalRecordsRecords 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.
spanThe stretch every held record falls inside — fromMs, toMs — or null when nothing is held.
possiblyDoubleRecords 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.
unknownVersionRecords 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.
totalUsdWhat the resolved records priced to, from the catalogue. unknownVersion and unreadable contribute nothing to it.
unreadableLines 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".

FieldWhat it holds
schemaVersion1.
contractWhich contract the input looked like, or null when nothing did. Named with --contract or inferred from the shape.
becauseWhy 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.
problemsOne 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[].kindmissing (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).
unavailableFindings 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.
recordsRecords examined, for a log. Null for a single document, which is one thing rather than a count of things.
conformsThe 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.

FieldWhat it holds
schemaVersion1.
firedAtMsThe instant the cycle ran, so a consumer can see how stale a figure is rather than assume it is current.
crossingsGates 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[].provenanceAlways 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.
suppressedStill 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.
abstentionsGates 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.
gapThe 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.

FieldWhat it holds
version1, the task document family version.
kindtrazum-task.
taskDeclared task ID, type, criterion, policy ID, outcome and assessor.
usageRecorded 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.
sourcesSource indexes, harness formats, non-cryptographic reuse checks, converter diagnostics and completeness limits; no raw session IDs or file paths.
coverageObserved harnesses, recognized models and evidence gaps.
toolsCall/result coverage, replayed calls and repeated-result findings with local source/line references.
limitationsPreserved evidence and interpretation boundaries.

Comparison#

CLI task compare and MCP compare_tasks emit this object from two validated task reports. Neither report is mutated.

FieldWhat it holds
version1.
kindtrazum-task-comparison.
verdictlower-usage, higher-usage, similar-usage, quality-regressed or inconclusive.
reasonsWhy the observation supports a verdict or cannot be compared.
tokenChangebefore, after, delta and percent for a supported accepted comparison; otherwise null.
limitationsEvidence 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.

FieldWhat it holds
version1.
kindtrazum-task-policy.
policyIdrepeat-review-v1.
appliedtrue after apply, false after revert.
changedWhether 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.