Module census 

pv census — ONT-001 v4.3 ONT-1: ONE cardinality over the contract corpus, reported by_kind, by_entity_type and by_anchoring.

WHY THIS WALKS WITH pv lint, AND WHY IT READS RAW YAML TOO.

ONT-001 §1 quote-freezes three different corpus sizes — 1818, 1460, 1331 — because three readers each had their own idea of what a contract file is. This command therefore collects with provable_contracts::lint’s walker, the one pv lint and pv validate already share: same directory exclusions, same is_contract_yaml rule. A census that counted its own universe would just be a fourth number.

The ANCHORING breakdown cannot come from the typed Contract, though. Contract is not #[serde(deny_unknown_fields)], so serde silently DROPS an entity: block it does not model (measured 2026-09-14: pv validate prints “Contract is valid” for a contract whose entity: it ignored). A census built only on the struct would report unanchored for every contract FOREVER, including after the corpus was anchored, and ONT-001 §11.2’s ratchet reading it would record 0 while the work was done. So each file is parsed twice: through the shared parser, for the file rule and by_kind, and as raw text, for the anchor the struct cannot see.

R-2 applies to the instrument itself:

• nothing to read → ZeroContracts, exit 2, decline: 0 contracts under <path>;
• a file that will not parse → ParseErrors, exit 1, reject: N parse error(s) under <path>.

A census of 4 over 3 readable contracts is the shape R-2 exists to refuse: the count would include a file nobody read.

Structs

AnchoringCounts

by_anchoring — the three anchoring levels of §0.0, always all three keys.

Census

The counts ONT-1 owes, in the order contracts/census.json carries them.

ExternalCorpus

The declaration’s shape, defined ONCE — in the schema module, beside the pv validate rules that check it (PMAT-1098). It used to be declared here, which made pv census and pv validate two readers each holding half of what the file is; EXT-CORPORA-009 now validates THROUGH this struct, so a declaration pv calls valid is one this command can count, by construction. One contracts/external-corpora.yaml entry, copied into the census verbatim.

Timing

timing — the baseline’s definition, not a measurement taken here.

Enums

Anchoring

How a contract names the thing it is a contract for (ONT-001 §0.0).

Constants

SCHEMA

Schema id of contracts/census.json.

TIMING_RUNS

Runs the timing baseline is defined over (ONT-001 §5 ONT-1). The values stay null until PVL EV-9’s provable-ladder job measures them on the CI host class; R-12 is unarmed until then. A number measured HERE would be a number from the wrong host, and would also make two runs of this command disagree — which the ONT-1 probe (tracked census == fresh census) would catch as drift.

Functions

census_of

Walk dir with pv lint’s file rule and count. Returns the census, or the refusal the corpus earned (see the module docs).

classify

Classify ONE raw YAML document. Pure, so the case table can pin every row without touching a filesystem.

parse_external_corpora_str

The declaration’s shape, defined ONCE — in the schema module, beside the pv validate rules that check it (PMAT-1098). It used to be declared here, which made pv census and pv validate two readers each holding half of what the file is; EXT-CORPORA-009 now validates THROUGH this struct, so a declaration pv calls valid is one this command can count, by construction. Parse an external-corpora declaration.

render_json

The tracked contracts/census.json bytes: deterministic, one trailing newline. Two runs over one tree are byte-identical — the ONT-1 probe compares the tracked file with a fresh run.

run

pv census <dir> [--format json].