Breadth tiers

explanation

Depth tiers sort every manifest by the kind of output it produces: a parser with a shared viewer, a standalone parser, a metadata card. They say nothing about how much of the file format is decoded. Breadth tiers answer that question.

Breadth: how much of the file format does Poka read?

Breadth is measured against the format itself (its structure, its versions and its features). It is not measured against how good the output looks, and not against whether the decoded content is correct: correctness is the job of the corpus tests (tests/samples.rs).

Depth and breadth are independent, and each can disagree with the other:

A T1 parser with a shared viewer can be B3. It draws the geometry or the tables, which is what the viewer wants, and skips materials, layers or annotations.
A T3 metadata card can be B4 by design. The format is a container, the card lists what is inside and how big it is, and Poka never claimed to render the content. If the card carries only a magic number, it is B5.
A T1 or T2 parser for a small, simple format can be B1.

A depth tier is derived from the manifests and cannot be argued with. A breadth tier is a reviewer's judgement, recorded with the evidence behind it, so it can be checked and changed.

The scale

Id	Name	What it means
B1	Complete	Everything the format defines that a reader would see is decoded, in every version Poka claims. Anything not decoded is immaterial and listed.
B2	Broad	The common content of the current and the common older versions is decoded. Some named features or versions are not, and are listed.
B3	Core	Only the main content type or types are decoded (for example geometry but not materials, layers or annotations, or only one version family). The list of gaps is substantial.
B4	Summary	The container and metadata are read and summarised (counts, properties, structure), but the main content is not rendered.
B5	Identification	The format is recognised and a few properties are shown (name, size, version string). Nothing of the content is decoded.
none	Not assessed	No review has been done. A format page says "Not assessed yet".

Every format with a page is in exactly one row. Not assessed is the starting point, not a low tier: it says Poka has not looked, not that Poka reads little. Read the list of gaps as well as the id: the id is a summary of it.

The ids are stable. A name or its wording can change; B2 keeps meaning "broad, with named gaps".

How a tier is assigned

A reviewer reads the evidence, picks the row that fits, and writes four things into the format's entry:

Field	What it holds
`breadth`	The id, `B1` to `B5`. Leave it out for not assessed.
`breadth_gaps`	What Poka does not decode, as short phrases a user would recognise (feature or version names). Required for every tier below B1.
`breadth_basis`	What the tier rests on: the files, tests and corpus samples read, and the review date as `YYYY-MM-DD`.
`breadth_confidence`	`high`, `medium` or `low`.

Evidence rules

Evidence only. The sources are the parser source, its tests (tests/samples.rs and the unit tests), the corpus in poka-samples, the format's own documentation, and what the viewer shows (the "Not drawn" lists). The per-version poka claims already in the entry are a starting point to check, not an answer. A reviewer does not guess.
Name the gaps. A tier below B1 comes with a concrete list of what is not decoded. "Some features" is not a gap; "layer visibility" is.
Code wins. If the documentation claims something the code does not support, the reviewer says so and tiers by the code. The claim is then corrected in the same change.
A tier is per format entry, not per file. The basis says which versions and variants it covers. The per-version poka field (read, partial, not-read) carries the version detail, and a tier does not repeat it: there is no tier per version. B1 cannot sit beside a partial version (the generator rejects that); a version marked not-read is one Poka does not claim, and belongs in the gaps when a user would expect it.
Confidence. High means the reviewer read the code and a test that proves the claim. Medium means they read the code. Low means a judgement from the documentation alone.

The review pass

The review pass works through the documented formats in groups (for example CAD, 3D, documents). Each format gets a finding in the form above, based on the evidence rules, and the findings are entered into docs/data/format-metadata/. The date in breadth_basis is the day of the review; a tier is a statement about the code on that day, and a later parser change can make it stale. The scorecard shows how many documented formats are assessed so far.

The first full pass, 2026-10-16

Reviewed 2026-10-16: the first full pass covered all 121 formats that had a format page on that date, each read from the parser source, its tests and the corpus, and each given a tier, a gap list, a basis and a confidence. The review also corrected per-version poka claims and notes where the code did not support them (most often a version marked "Read" that is now "Partly read").

To re-assess a format later, repeat the same steps: re-read the code and tests the basis names, check the gaps against what the parser does now, pick the row that fits, and write all four fields again with the new date. Where a gap has closed, remove it; where the tier rises, say what changed in the basis.

Several tiers rest on less evidence than the confidence field suggests at first sight. For a number of formats (XCU, CAT, CNT, BLO, EKD, TSM, DWL, DWL2, DYF, DGN and SKP) the corpus holds no real sample, or the samples were removed. Their corpus tests cannot pass in a clean checkout, or exercise only synthetic files, so the tier is a reading of the code. Treat those tiers as provisional, and re-assess them first when real samples are added.

What a tier does not prove

Correctness. A format can be B1 and still decode a field wrongly. Only the corpus tests speak to that, and only for the files in the corpus.
Anything about unreviewed formats. Not assessed is not B5, and a format without a format page is outside this scheme altogether.
A fixed measure. Two reviewers can place a format a row apart. The gaps list and the basis are what make a tier checkable; the id alone is a summary.
That it is current. The tier belongs to a review date, not to the code as it is now.
A file-level promise. A B2 format can contain a drawing that uses only the missing features. The tier describes the format entry, not the file.

Proposing a change

Breadth tiers live in the hand-written format entries, one file per group under docs/data/format-metadata/, and never in a generated page.

Edit the format's entry: set breadth, breadth_gaps, breadth_basis and breadth_confidence, and correct any poka version claim the review shows to be wrong. Cite what you read in breadth_basis, with the date.
Run python3 scripts/gen-format-pages.py, then python3 scripts/gen-format-catalogue.py and python3 scripts/scorecard.py, and commit what they write.
Run python3 scripts/check-docs.py --check. It rejects an unknown id, a tier below B1 with no gaps, a missing review date or confidence, and a stale page.

A batch of review findings written as toml blocks (one per format, with the four fields) can be applied in one go with python3 scripts/apply-breadth-findings.py <findings file>. It validates each block, edits only those keys, and writes nothing if any block is wrong.

poka.sh