Skip to content
Trazum

1.51.2

The stream, and fourteen things nothing was checking

Added#

The gateway relays a streamed answer as it arrives — 1.52's first chapter. Until now gateway-server.ts read await upstreamResponse.text() for every response. For "stream": true — nearly all production traffic, and every agent loop — the caller waited for the entire answer and then received it at once, so time to first token became the total generation time.

The page had the argument against itself already: reading a budget file per request would "put Trazum's own latency between you and your provider on every call — a cost this tool would otherwise be reporting on somebody else." Buffering a stream was a far larger version of that, in the same file.

The provider decides, not the request. A body asking to stream can still come back whole, so the branch turns on the content-type that actually arrived rather than on what was asked for.

streamingUsageReader reads the counts off the events on their way past and holds three numbers and a partial line — never the text. That is the same promise the buffered path makes, kept structurally rather than by intention.

  • Anthropic puts input and cache counts on message_start and a running output total on each message_delta. The last one wins. Summing them would report a bill several times the real one, in the direction that makes this tool look like it found money it did not.
  • OpenAI sends usage only when the caller passed stream_options: {include_usage: true}. Without it the stream carries no counts and the gateway records nothing — not zero. A call whose usage never arrived is not a free call, and zero is the flattering direction.
  • A line that never ends is refused past 1 MB rather than buffered. A proxy that promised to hold no text must not be turned into one holding a gigabyte by an upstream that omits a newline; losing those counts surfaces as "usage not recorded", which is the honest failure.
  • A stream that breaks partway destroys the socket — the head is already sent, so there is no status left to change — and notes the call as unmeasured. The money was spent and its counts rode an event that never arrived; recording the partial counts would be a measurement of the part that arrived, read as the cost of the whole.

The end-to-end test cannot pass against a buffering proxy — it hangs. The stub upstream emits message_start and then holds; the test asserts the first event reached the caller before releasing the rest. Restoring the old relay does not fail the assertion, it deadlocks: the proxy waits for a body that will not end until the test that is waiting for the proxy lets it. Proven by doing exactly that, under a timeout.

The type is GatewayUsage, not MeasuredUsage — measured-profile.ts already uses that name for a label's coverage across a log, and two types with one name is a rename waiting to be got wrong.

A plan through 1.60.0 — docs/plan-1.52-1.60.md, nine arcs, written before the code as the four before it were. Under the numbering adopted at 1.50.1 a minor closes an arc, so 1.52.0 … 1.60.0 land one thesis each.

The plan says which of its arcs are measured and which are intentions, and that is the part worth arguing about. The first three answer things that are wrong or missing today and cite the line of code:

  • 1.52.0 — the gateway in a real path. gateway-server.ts relays with await upstreamResponse.text(), buffering the whole upstream reply before writing a byte back. For "stream": true — nearly all production traffic — time to first token becomes the total generation time. The page argues that reading a budget file per request would put Trazum's latency between you and your provider; buffering a stream is a much larger version of that, in the same file.
  • 1.53.0 — every provider you pay for. Seven priced, two connected, and the gateway fronts two. Five providers can be priced from a hand-exported log and cannot have their bill read automatically or their calls gated live.
  • 1.54.0 — the counter, per family. The estimator is calibrated on Claude over 21 samples and prices seven families. ROADMAP.md has called the per-family error the one number that settles the real-tokenizer question, and nobody has measured it.

The remaining six — 1.55.0 through 1.60.0 — are an ordering of intentions, not commitments about content, and each says so in its own section. Presenting all nine with equal confidence would be merging a measurement with a projection on the roadmap of a tool whose first doctrine rule forbids exactly that.

The order changed while writing it. The token band went first in the draft, because it is the question the roadmap has carried longest. It is third now: a shipped feature most callers cannot use outranks an open question somebody wrote down. That reordering is in the document rather than silently applied.

What would reorder it is written down instead of left to be inferred — a user with a provider Trazum prices and cannot gate, a measured band that comes back far out, or somebody volunteering as a language maintainer.

ROADMAP.md's ## Next now carries the plan, and names the three Under consideration entries this schedules: the tokenizer question (1.54.0), cost alerting (1.56.0) and the editor extension (1.58.0). It said "Nothing is planned" since #288, which was true when it was written and is not now.

Fixed#

SUPPORT.md's "No telemetry" section claimed to enumerate every network call and listed three of seven. It said "The only network calls any of them make are the ones you asked for: connect reaching a provider's usage API, --pricing-live fetching a price feed, eval/route/prune/--suggest making the model calls they warn you about first."

Missing:

  • trazum gateway, which forwards your entire prompt and your credential to the provider, and has done since 1.50.3.
  • --exact-tokens, which calls Anthropic's count_tokens endpoint.
  • trazum watch --webhook, which POSTs an alert to a URL you gave it.
  • Vertex AI's token exchange, when Vertex is the configured endpoint.

Every one of those is a call somebody asked for, and that is not the point. The sentence claimed to enumerate them, on the page a reader opens to check whether this tool phones home, and an enumeration missing its largest member is wrong however defensible each omission is on its own.

The section is now a table: what reaches out, where it goes, and what asks for it — with the gateway called out for a second reading, because forwarding a prompt and a credential is what standing in the path means, and a reader deserves that said plainly rather than found out.

docs/plan-format.md was checked and is entirely correct — the eight top-level fields, the eight action fields, the five kind values and the five refusal reasons all match plan.ts and a plan emitted for the purpose. Reported because a page that survives the check is worth recording too.

Added#

outbound-surfaces.test.js: every module that can reach the network is named in SUPPORT.md. The file set is derived; the map from file to prose is deliberate. That asymmetry is the design — a new module that can call out fails by name, and the only way to make it pass is to decide what the page should say about it, which is the review a new outbound surface deserves. A fourth assertion refuses any count in front of the list.

The guard's first draft missed the gateway, which is the surface it was written to find. gateway-server.ts assigns const doFetch = context.fetchImpl ?? fetch and calls doFetch(...); matching only fetch( and fetchImpl( skipped it. Aliases assigned from fetch are resolved now.

Its second draft missed a planted module entirely, because it derived the file list from git ls-files and the probe was written but not yet staged. CI would have caught it after the commit — which is precisely the reassurance that lets a guard be useless where it is actually used, at the desk, before the commit. It reads untracked-but-not-ignored files too.

And the fix's own first draft wrote "six" above a table of seven rows — the same failure corrected in three other files this session, committed again by the person who had just corrected them. There is no number there now.

The CI page's first example has never worked. docs/ci.md opened its GitHub Actions section with:

with:
  path: prompts/
  max-tokens: '900'

There is no path input and there never has been. git log -S" path:" on action.yml finds it in no revision; the input has been target since 0.11.0, with file as a deprecated alias. The page shipped at 1.48.0 and has said path since the release that introduced it — so the first example on the page a reader lands on to set up CI was wrong from the day it was written, across sixteen releases.

What kept it from being worse is the Action's own refusal. With no target and no usage-log it stops with "Set the 'target' input to the prompt file or directory to check, or 'usage-log' to gate the spend." A reader copying the example got a red build naming the right input — not a green build gating nothing. That distinction is the whole difference between a wasted afternoon and a budget everybody believed in, and it is the argument for writing a refusal even where nobody expects to need one.

The example now uses target, and the paragraph under it says what file is, that no path input exists, and what the Action does when given neither.

The rest of the page was checked and is correct. Every flag in its GitLab, Jenkins, CircleCI and pre-commit examples was matched against COMMAND_FLAGS for the command it follows: no unknown flag anywhere.

Added#

action/test/documented-inputs.test.mjs, deriving the input list from action.yml. Every with: key in a Trazum Action example, in any tracked markdown file, must be an input the Action declares.

Run across the corpus rather than the one broken page, because README.md carries three of these examples and all three were right the whole time — a guard that only ever saw the file it was written for would not have shown that. Proven in both places: restoring path: fails naming docs/ci.md, and a planted targets: typo in the README fails naming the README.

The agent-facing skill listed nine config keys. The schema knows seventeen. .claude/skills/trazum/SKILL.md is what an agent reads before answering a question about this tool, so a gap in it is not a documentation gap — it is a wrong answer given to somebody who asked.

The eight it never named: labels, spend, sources, store, waive, outcomes, ladders, owners. That is the entire budget surface, the fleet, the waiver record, and the vocabulary the whole 1.51 arc rests on. An agent asked "can Trazum tell me whether the cheaper model made things worse?" would have consulted this list, not found outcomes, and said no — about the one capability that release existed to add.

The section is now a table: every key, what it settles, and the sub-keys of the three whose shape an agent has to produce rather than merely mention. It ends by saying which key to suggest first when somebody asks whether a change made things worse.

The rest of the file was checked and is correct — "three provider calls per case" matches evaluate.ts, the ±10% band matches ESTIMATE_ERROR_BAND_PCT, and the 1.25x/2x cache write premiums match COST_MULTIPLIERS. Its command coverage is deliberately narrower than the CLI's, so an absent command is scope rather than drift, and is not asserted.

Added#

skill-doc.test.js, deriving the key list from CONFIG_KEYS. Four assertions: every top-level key is named; the sub-keys of spend, outcomes and ladders are named, because those are the three an agent must fill in rather than mention; and the cache multipliers and the error band are quoted as the code holds them, since the skill tells an agent to report a cache loss "plainly rather than softening it" and quotes the premium as its evidence.

The sub-key lists stay internal to the schema. Exporting them so a test could import them would widen the public surface to suit the test; an in-package test may reach into its own package instead.

Two things went wrong writing it, and both are the same habit paying off. The guard failed the replacement table on spend.monthlyUsd — I had omitted it while writing out a list whose whole point was completeness. And the multiplier assertion demanded **2x** in bold, because that is how packages/cli/README.md writes it, and so failed a sentence in this file that says 2x plainly and is entirely correct. The number is the claim; the bold is a house style that differs per file.

Proven by restoring the original nine-key line — "the schema accepts these and SKILL.md does not name them: labels, spend, sources, store, waive, outcomes, ladders, owners" — and by planting a stale multiplier.

A mislabelled index sent readers looking for an API key to a page about signing in with GitHub. docs/README.md described docs/accounts.md as "Provider accounts — Connecting a provider so usage arrives on its own". That file is about the web app's accounts: GitHub OAuth, the prompt library, share links, what the database holds. It contains no provider key, no admin API and no mention of trazum connect.

docs/usage-logs.md then ended its connector paragraph with "See accounts.md for the key" — written trusting the index. A mislabelled index does not stay one mistake; it propagates into every document that consults it, and it did so within two changes. Both were mine: the index row at 1.51.1, the cross-reference in #296.

The index row now says what the file is. usage-logs.md names the variable outright — TRAZUM_ANTHROPIC_ADMIN_KEY, or ANTHROPIC_ADMIN_KEY — and links to the README's trazum connect walkthrough, because a reader who wants a key should be given the key rather than another hop.

The OpenAI connector's credential was documented nowhere at all. Found by the guard below, not by reading. trazum connect openai has existed since 1.41, the command's own refusal says "Available: anthropic, openai", and the README section explains how the two providers' reports differ — while showing only Anthropic's export line. TRAZUM_OPENAI_ADMIN_KEY and OPENAI_ADMIN_KEY appeared in no markdown file in the repository, so setting up the OpenAI connector required reading connector.ts. The section now gives both invocations, both variables, and what each key must be able to do — read a usage report, never spend.

Added#

credential-pointers.test.js, deriving both checks from CONNECTORS.

There is no mechanical way to assert that a one-line index summary describes a file honestly. There is a mechanical way to assert the consequence that hurt: a sentence promising a credential must point at a file that names one. Links are matched only where the prose actually promises a key, so a page naming ANTHROPIC_API_KEY inline — which needs no pointer — is not dragged in.

The second assertion runs the other way: every connector's credential must be named in the documentation at all. That is the one that found OpenAI.

Proven both ways. Restoring "See accounts.md for the key" gives "accounts.md → accounts.md, which names no connector credential"; removing the OpenAI export line again gives "these connectors exist and their credential is documented nowhere: openai".

The gateway fronts two providers. Its page named one. docs/gateway.md opened with trazum gateway anthropic and never mentioned openai — which the gateway has spoken for since 1.50.3, added in the same commit that wrote the page. The command's own refusal says "Name the provider to stand in front of. Known: anthropic, openai." The product named both; the documentation named one. A reader on OpenAI could read the page end to end and conclude the gateway was Anthropic-only.

The page now carries the compiled-in table — provider, upstream origin, and the single path each forwards — which is also the first time either forwarded path appeared in the documentation at all.

"It forwards exactly one path" was counting the wrong subject. That sentence is the security argument — "a gateway that forwarded any path would be a general proxy for your API key" — and the property holds: one path per provider, two in total. The claim is now stated per provider and points at the table.

Added#

gateway-doc.test.js, asserting the page against UPSTREAMS. Three checks, every subject derived from the compiled-in table: each provider is named, each origin and forwarded path appears verbatim, and the "exactly one path" sentence must say per provider while more than one provider exists.

The path assertion is the one that matters. The page's security claim is about which path is forwarded, so asserting the property abstractly would let the page keep the argument and lose the specifics.

Its first draft would have fired on a correct page. Requiring each provider as inline code failed anthropic as well, which the original page named perfectly well inside its opening bash block — naming a provider in an example command is naming it. Caught by running the check against the original text, not just the new one. Matching is now word-boundary, and the probe isolates exactly the real gap: "the gateway fronts these and docs/gateway.md does not name them: openai".

The product tells you to record an outcome. The page it sends you to never mentioned the field. docs/usage-logs.md exists to answer one question — what do I put in the log, and what does each field buy me? — and it named nine of the fourteen keys parseUsageLine accepts.

outcome and trazum_outcome appeared nowhere in the file, five releases after 1.50.4 introduced them. The profile report says, in the product, that this is "the one field that changes what every other figure here means: without it this tool can say a workload got 40% cheaper and cannot say whether it stopped working." A reader could follow that advice to this page, record every field it named, and get the same warning again.

Five aliases were also missing — ts, created_at, created, conversation_id and finish_reason. Omitting an alias breaks no log; it makes somebody rewrite one that already worked, or conclude that truncation detection is Anthropic-only because their OpenAI records say finish_reason. The page now carries a table of every accepted spelling, in the order the parser tries them, and says why trazum_outcome exists: so a field-name collision is not a reason to go unmeasured.

Added#

usage-logs-doc.test.js — the page that says what Trazum reads, against what it reads. Keys are harvested from parseUsageLine and bounded to it: the normalised UsageRecord reuses several of the same names further down the module, so a harvest over the whole file would assert the output shape while claiming to assert the input one.

A second assertion checks the outcome row still says what recording it buys, not merely that the word appears. The row exists to answer "why would I record this?", and its answer is the only one in the table that is not about cost.

Its first draft passed while the alias was undocumented. Matching each key as a bare substring, ts was found in the ```ts language tag on a code fence — so an accepted-and-undocumented key read as documented. Caught by running the check against the real page before trusting it, which is the habit the tenth occurrence of bound an assertion by its subject bought. Keys are now matched as the page actually writes a field: inline code, or a JSON key in an example.

Proven three ways: removing the alias table names all six it hides, removing the outcome row fails by name, and gutting the row's explanation while leaving the word fails the second assertion.

docs/releasing.md said "both manifests" and "both publish steps". There are three. The release document was written when @trazum/core and @trazum/cli were the only publishable packages, and @trazum/mcp never reached the prose:

  • "the tests before either upload"
  • "so both manifests carry publishConfig.access: \"public\""
  • "and both publish steps pass --access public"

The bash block six lines above it already lists three publishes, so the page contradicted itself, and no test opened docs/releasing.md at all.

The sentence immediately after is the one that stings. It explains that publish.test.js "derives the set of publishable workspaces from the root workspaces globs — so a workspace added later has to make the choice rather than inherit one". The mechanism was built for exactly this growth. The prose describing the mechanism was not.

Added#

A guard, counting from the same derivation the paragraph describes. PACKAGES — the workspaces globs minus anything private — is the count, so adding a fourth publishable package fails the sentence rather than quietly outgrowing it.

Its first draft was wrong, and its own probe caught it. Matching every quantity word beside "manifest", "publish step" or "upload" across the whole file failed two true sentences: "all five manifests — root, packages/core, packages/cli, packages/mcp, apps/web", which counts the version manifests a release bumps and enumerates itself, and "a failure that happens between two uploads", where "two" means consecutive rather than total.

That is this repository's most-broken rule — bound an assertion by its subject, never by its neighbour — arriving for a tenth time, in a guard written three changes after the doctrine entry was rewritten to warn about it. It was caught before merge only because the guard was run against the real file rather than against the defect alone. The assertion is now bounded to the sentences making the publish-access claim, which is its actual subject.

Proven both ways: restoring "both manifests", "both publish steps" and "either upload" each fails naming the phrase and the real count, and the two true sentences pass untouched. A guard that cries wolf gets deleted, so the second half is not optional.

npm test said "core + cli test suites". It runs five. CONTRIBUTING.md printed four commands with a comment beside each explaining what it covers. Two were written before @trazum/mcp existed and never revisited:

  • npm run build # core + cli — it builds three workspaces.
  • npm test # core + cli test suites — it runs five: core, the CLI, MCP, the web app and the Action.

The same omission had reached CI's step names, from the same cause: Build library and CLI and Tests (core, CLI, web, Action). So the MCP package's tests ran on every pull request under a label that did not mention them, and a contributor whose check failed there had to read the workflow to find out what had actually run.

Nothing was broken by this — every suite ran, and verify remains a superset of what CI does. What was wrong is the thing a stranger reads to decide whether their change is covered. Someone adding an MCP tool could reasonably have concluded npm test did not reach it, and either skipped it or duplicated it.

Correcting the CI label turned up a smaller one: the build step called @trazum/core "library". It is not wrong English — core is the library — but a step name is what a contributor scans when a check goes red, and the package it names should be the package they can grep for. It now says core.

Added#

contributing.test.js — what the documentation says each command runs, against what it runs. Coverage is computed from package.json by walking each script's -w @trazum/… flags and any script it calls, so verify resolves through build, test and typecheck without a list kept anywhere. Four assertions: the comment beside npm run build, npm test and npm run typecheck, plus the CI step names read out of ci.yml.

Membership, not wording. The sentence may be phrased however reads best — # all four workspaces is accepted for typecheck because it is a true statement about every one of them — as long as each workspace the script really drives is named. A count would have gone stale exactly as the prose did.

Proven by restoring all four original texts. npm run build reports "runs these and its comment does not name them: @trazum/mcp"; npm test reports "@trazum/mcp, @trazum/web, action" — three of its five suites hidden by one comment; the CI names report "Build library and CLI" omits @trazum/core and omits @trazum/mcp, and "Tests (core, CLI, web, Action)" omits @trazum/mcp.

The README told you Anthropic's cache floor was 512. It spans 512 to 4,096, and the error ran in the direction that promises money. The provider-facts table under Every model you pay for by the token said "Cache minimum | 512 on Anthropic, 1,024 on OpenAI and Moonshot, 2,048 on Gemini Pro". cacheMinTokens is a property of the model, not the provider: 512 on Fable 5, Mythos 5 and Opus 5; 1,024 on Opus 4.8, Sonnet 5 and Sonnet 4.6; 2,048 on Opus 4.7; 4,096 on Opus 4.6 and Haiku 4.5.

A reader on Haiku 4.5 who trusted the table would have built a prefix eight times too short and expected a cache saving that could never arrive. This project's own rule is that a floor proves over, never under, and its front page was breaking it about the floor itself.

The code was never wrong. trazum models prints the real figure per model and every cache advisory has always read cacheMinTokens — the 1.14 work on below-cache-minimum exists precisely because the floor is per model. Only the prose summarising it by provider was wrong, which is the failure mode of any table that flattens a per-item fact into a per-group one.

Two more rows had gone stale by omission. DeepSeek was missing from the cache-read row and xAI from the row saying how caching starts. Nothing false was written about either; they were added to the catalogue and not to the prose, which is how a table stops being a description and becomes a snapshot.

Added#

pricing-prose.test.js — the money table, checked against the catalogue it describes. Six rows of hard numbers about what caching and batching cost, hand written, read by nothing until now. Five assertions, all deriving their subjects from BUNDLED_CATALOGUE rather than from a list typed beside them:

  • every priced provider appears in the table at all;
  • every provider with a cache is named in the cache-read row;
  • every provider with a cache is named on one side of the automatic/explicit split;
  • no single cache minimum is attributed to a provider that has several — the defect itself, stated as a property;
  • every distinct cache minimum in the catalogue is named somewhere in the row.

Membership is asserted rather than counted, for the reason this repository has now learned nine times.

Proven by planting each defect back. The original row fails two of them independently — "Anthropic has 4 different cache minimums (512, 1024, 2048, 4096) and the row states one figure for it" and "these cache minimums are in the catalogue and named nowhere in the row: 4096". Dropping DeepSeek gives "DeepSeek reads cache at 10% and the cache-read row does not name it"; dropping xAI gives the matching failure on the other row.

A comment saying "the six below" above a list of five — in the change whose whole argument was that a gap should be named rather than counted. The --json interchange suite explained which commands it could not drive and closed with "The six below are the ones a usage log alone can drive, and they are named rather than counted so the gap is visible." There were five, and history appeared in neither half: not in the covered list, not among the named exceptions. The one command the sentence could not account for was the one it made invisible.

history --json is in fact fine — history.test.js drives it on three dated reports and parses its stdout whole — so this was a hole in the account, not in the coverage. That is worth saying precisely rather than inflating: nothing shipped broken. The exception now names where it is proven and why, because "it is tested elsewhere" is the sentence that stops being true without anybody noticing, and the count is gone.

Added#

"Every command that accepts --json is covered here or named as an exception". The partition is asserted from COMMAND_FLAGS rather than kept by hand: every command whose flags include json must appear in the driven list, in the covered-elsewhere map with a reason, or in the needs-more-than-a-log list. Twelve commands, three buckets, no remainder.

Proven in both directions. A new --json command classified nowhere fails with "these commands emit --json and appear in neither the covered list nor a named exception, which is how history went missing from both". An exception left behind after its command stops accepting --json fails the other way, so an excuse cannot outlive the thing it excused.

The doctrine prescribed the fix that kept causing the failure. Bound an assertion by its subject, never by its neighbour is the rule this repository has broken more than any other, and its own entry in docs/doctrine.md ended with: "The fix is the same in every case: name the end as well as the start."

That is exactly what every repair had done, and naming the new neighbour only moves the trap one section further along. The canonical document was telling every future reader to re-arm it. It now draws the distinction that took nine occurrences to state: "until the next heading, whatever it is" is the subject's own extent; "until the heading called X" is a neighbour. The first survives an insertion; the second is a trap with a delay on it.

The entry's history was also wrong. It said "four contract harvests"; there were eight, plus a ninth that claimed a bound it did not have. Corrected, along with the count — six to nine — and the README's advisory count added as the occurrence the rule gained after it was written.

docs/our-own-medicine.md had stopped being current, which for the document whose entire subject is this project's own record is the failure it exists to catch. It was missing #288, #289 and #290, and its claim that "the two long ones are the interesting ones" was overtaken: the front page contradicted itself about the advisory count for fifty-two releases, longer than either. It also carried the same wrong tally as the doctrine. Both are now the same numbers, because they are the same facts.

A guard against undocumented commands accepted any backticked word. "Every command is mentioned in the README" filtered on trazum <id> or `<id> — a backtick followed by the name, anywhere in the file. The README has eighty-nine backticked lowercase words that are not commands, several of them plausible names for one: batch, cache, label, locale, drift. Planting a command called cache, documented nowhere, passed. All thirty-two commands satisfy the strict form already, so the loose clause was covering nothing and hiding the next command added.

trazum report --year --json emitted a stream no machine could read. It printed the human report and then appended the document, and its help said "Also emit". Every other --json in this CLI is the document instead of the report. So the one command emitting the annual-record contract was the one command whose output | jq and | trazum conform - both choke on.

The test covering it did stdout.indexOf('{') and parsed from there — a step no consumer can take. The assertion passed, the defect was invisible, and the guard standing next to the bug was working around it. --json now returns before any prose, the help in both locales says "The record as data", and the test parses the whole of stdout.

--contract refused two contracts that exist. The CLI kept a hand-written copy of the contract names for --contract, and it stopped at cost-answer: outcome-report (1.50.4) and annual-record (1.51.0) had field rules, had cross-rules, and were answered with "is not a contract" — the list telling the caller they had made a typo when the list was the thing that was wrong. The names are now a single CONTRACT_NAMES export in @trazum/core, with the union derived from it. One home per fact.

@trazum/core produced an outcome-report its own contract rejects. conform requires schemaVersion of every document — the one field checked outside the per-contract rules, because a consumer branches on it and its absence cannot be told from a pre-contract document. outcomeReport() never emitted one, from 1.50.4. A format whose reference producer fails it is worse than no format: anybody mirroring this output, which is exactly what docs/format.md invites, would have inherited the defect and looked interoperable.

docs/format.md was wrong about the format in three ways at once, on the page whose entire job is telling another tool what it can build against:

  • It opened with "Trazum emits seven documents. All seven are contracts" while its own table listed ten rows, three lines below the sentence.
  • It named neither outcome-report nor annual-record, so the two newest contracts were undiscoverable from the page that exists to list them.
  • It flattened two distinctions worth keeping. Three of the documents it lists have no --contract name, and one — the outcome report — is defined but never emitted: trazum profile renders it as terminal text and no command writes it as JSON. It is a contract so that your tool can produce one and have it checked, which is a different promise from "Trazum will hand you one".

The page now says eleven emitted plus one defined-not-emitted, carries a --contract column saying which nine are nameable, and documents the two missing contracts in docs/json-output.md.

Eight contract harvests were bounded by naming their neighbour. Every parity test that reads its promised fields out of docs/json-output.md did:

const start = doc.indexOf('## The first-run document');
const end = doc.indexOf('## The gateway refusal document');

Correct exactly until a section is inserted between the two — which documenting the outcome report and the annual record did. Four suites failed at once, demanding slices, year and missingMonths of documents that have nothing to do with them. This is the ninth occurrence of bounding an assertion by its neighbour, and the first that was systemic rather than a single test: the comment above one of them already said it was "the sixth time in this file's life", and the fix each previous time was to name the next neighbour again.

A ninth harvest was worse. gateway-proxy.test.js carried the comment "Bounded to its own section, like every other harvest in this repository" above doc.slice(start) — running to the end of the file, bounded by nothing. It passed only because that section happens to be last. A comment asserting a property the code does not have is worse than no comment: it is what a reviewer reads instead of the code.

All nine now use one sectionOf(document, heading) helper that ends at the next heading, whatever it is. A section that moves, is renamed or gains a neighbour keeps working; a section that is deleted fails loudly naming itself, which is the correct outcome and is proven by deleting one.

"a outcome-report". Every contract name that existed before 1.50.4 began with a consonant, so conform's heading hard-coded a. Making the two new ones reachable exposed it. The first fix was also wrong — a letter-only vowel test turned the correct "a usage-log" into "an usage-log", because usage opens on /juː/. The rule is now bounded to the closed set of contract names, and a test refuses to let a new name through whose initial English decides by sound.

The README disagreed with itself about the number of advisories, for fifty-two releases. The hero says "fourteen findings". Three lines below it, the paragraph that carries the actual argument said "Thirteen advisories" — the same claim, a different noun, and wrong. AdvisoryId has fourteen members.

A guard was standing right next to it and could not see it. "The counts the README claims are the counts the code has" reads the AdvisoryId union out of source rather than hardcoding a number, and asserts the README says "<word> findings". It does. When the fourteenth advisory landed at 1.9.1 the guard forced the hero sentence and said nothing about the sentence under it, because it was bounded to the word findings rather than to its subject — the number of advisories. Every release since shipped a front page contradicting itself on the load-bearing number of the pitch.

That is the eighth time in this repository an assertion has been bounded by a neighbour instead of by its subject, and the first time the cost was on the front page rather than in a test fixture.

Added#

packages/cli/test/interchange.test.js — the format held to what it says about itself, in five guards, each proven by planting the violation:

  • --json parses as one JSON document, for the five commands a usage log alone can drive. The ones needing a prior document, a credential, a running loop or a paid call are named rather than counted, so the gap is visible.
  • The annual record survives a pipe into conform, which is the whole claim the format page makes.
  • The reference producer conforms: an outcome report from @trazum/core passes the check this repository publishes. The other parity tests check the document against the doc; this one checks what is actually produced.
  • Every CONTRACT_NAMES member is named by docs/format.md, and the count it claims matches the rows of its own table minus the one it says is not emitted — counting the rows is the only version of that check a stale sentence cannot satisfy on its own.
  • No --contract name is offered that the CLI would refuse.

test-utils/section.mjs — the shared bound described above, with the whole history of why in it.

A ratchet on the class: "no test bounds a section of prose by naming the section after it". Nine occurrences were repaired one at a time; this is what closes the class. It walks every suite and fails on indexOf('## …'), because the pattern is easy to re-introduce and reads perfectly well in review. Proven by putting the old two-indexOf bound back into init.test.js and watching it fail naming the file.

Changed#

The guard now checks both nouns, and refuses any stale count beside a correct one. Two halves, because requiring the right phrase is only half the job:

  • The README must say "<word> findings" and "<word> advisories", both matching the union, matched case-insensitively — the second begins a sentence and a lowercase-only pattern would have been the same bug again.
  • No number word may precede either noun unless it is the real count. An inclusion check passes on a document that states a figure twice and disagrees with itself; this half fails it.

Proven against the live defect rather than a probe. Widening the guard made it fail on the README as it stood — the README should say "fourteen advisories" (the code has 14) — which is the strongest form of proof available: the violation was already in the repository. Both halves were then re-planted afterwards and each failed naming the wrong figure. The README now says fourteen in both places.

CHANGELOG.md still says "thirteen advisories" under 1.9.0 and that is left alone. It was true of 1.9.0, and rewriting history to satisfy a guard is the failure this file exists to prevent — the same split RELEASES.md already draws between its standing header and its record.

ROADMAP.md's forward-looking section was narrating a past. ## Next opened with "the arc in progress is docs/plan-1.51.md" — after every chapter of that arc had shipped and the arc had landed at 1.51.0. It is exactly the failure 1.51.1 fixed in the three plan documents, one section further down in a file those fixes touched, and it went unnoticed while they were being made. A reader deciding whether to depend on this would have read work that is finished as work that is coming.

## Next now says nothing is planned, because nothing is: four arcs have been planned in advance and all four are delivered, and there is no fifth. The delivered arcs are stated as delivered, with 1.51.0's ten chapters named.

Added#

A guard on the roadmap: "the section called Next points forward, or says it does not". The invariant is deliberately not "Next must be full" — a project with nothing planned is a real state, and a roadmap that manufactures a queue to look busy is worse than an empty one. It is that the section either names a version newer than anything released, or says plainly that nothing is planned. Doing neither leaves only one reading: delivered work described as forthcoming.

Proven in both directions. Restoring the old "the arc in progress" opening fails the test by name, quoting the newest released version. Replacing it with a genuine forward plan naming a higher version passes without the escape phrase, which is the half that matters — a guard satisfiable only by a magic sentence would be answered by pasting the sentence.

The version comparison is numeric rather than lexical, because '1.9.0' sorts above '1.51.0' as a string and that is precisely the version pair this repository has.