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_startand a running output total on eachmessage_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.tsrelays withawait 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.mdhas 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'scount_tokensendpoint.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-reportnorannual-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
--contractname, and one — the outcome report — is defined but never emitted:trazum profilerenders 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:
--jsonparses 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/corepasses the check this repository publishes. The other parity tests check the document against the doc; this one checks what is actually produced. - Every
CONTRACT_NAMESmember is named bydocs/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
--contractname 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.