Two chapters, one shape. docs/json-output.md calls itself the contract and
docs/format.md is the index a connector author works from. Between them they
specify every document Trazum emits — and between them, six contracts had no
guard and three documents were on neither list. The second finding is a
consequence of the first, which is the whole point of putting them in one
release: a document nobody lists is a document nobody checks.
Fixed#
docs/json-output.md called itself the contract, and six of its fifteen
tables had no guard. The file's second sentence named one test — and one test
is what it had: nine of the fifteen documents were genuinely harvested by a
parity check somewhere in the repository, six were not, and nothing anywhere
recorded which was which. Two of the six had drifted. The roll-up document
listed three top-level fields and trazum rollup --json emits nineteen — the
merged bill, both periods, the duplicate and overlap findings and the typed
cannotSay caveats were absent from the contract a consumer builds against,
and notMerged sat beside a documented rejected where a reader handling one
would miss the other. The fleet document never mentioned schemaVersion, the
one field this file's own promise section calls the only thing you must branch
on. Both tables are complete now, and the roll-up's rows carry the refusals
rather than only the arithmetic — a shared day's dearest label is null, the
repeats are named and never subtracted.
Added#
packages/cli/test/contract-coverage.test.js — the inventory beside the
promise. It takes every ## heading in docs/json-output.md whose section
carries a field table, matches each against the test that harvests it, and
fails on a table nobody claims and on a claim for a table that is no longer
there. A claim is not taken on trust: the file named has to pass the heading to
a call, because a heading in a comment is not enforcement. It also walks all
three packages' test directories for harvests the map does not know about — the
direction that would have caught the six. The six unguarded tables — fleet,
roll-up, annual record, pulse, rule-yield and the outcome report — are now held
both ways by running the command (or, for the outcome report, the library
function; no command emits it).
And the harvest is proved on documents written for the purpose. It has to
tell a section carrying a table from two that carry only prose, and read a row
naming four fields (root, files, prompts, truncated) and one naming a
nested field documented and deliberately never emitted (promises.arrivedUsd)
— otherwise every "both ways" check above is agreeing with a misreading.
docs/format.md undercounted the interchange format by three, and the guard
on that count agreed with it. The front door of the format — the page a
connector author works from — said Trazum emits twelve documents and defines a
thirteenth. trazum pulse --json, trazum rules --measure --json and the
gateway's HTTP 402 body each have a contract table, a schemaVersion and
something that emits them, and were in neither the table nor the count.
README.md said twelve in the same breath.
The sentence was already guarded — against the table. interchange.test.js
has held the opening count to the rows beneath it since the day it said seven
with ten rows, and it derives the ordinal rather than typing it. It could not
have caught these three: both halves it compares are written by hand, so a
document missing from the table and missing from the sentence leaves the two in
perfect agreement. The missing half was never the arithmetic — it was the table
against the contracts that exist.
Fifteen emitted and a sixteenth defined, in both places. The new guard derives
the list from the contract tables in json-output.md and matches it against the
front-door table by the anchors the rows link to, failing on a table the
page omits and on a row pointing at a section that carries no table. It holds
README.md to the same count, compares the --contract column to the names the
CLI accepts as a set — the existing checks allow a contract named only in prose
— and holds the plan's two tables, in json-output.md and plan-format.md, to
each other. The three omitted documents were also three of the six with no
parity guard until the entry above, which is not a coincidence: a document
nobody lists is a document nobody checks.