F8: freeze the source-syntax classifier population in a committed ledger (#211)

[milyin]

Stage F8 of #215 (umbrella for #211), landed before F1 — on purpose.

#211's sixth completion criterion:

A mechanical check prevents new source-syntax classifiers from being added outside the frontend.

What a site is

A place that looks at captured Rust syntax and asks what shape is this. Real lines, all outside the frontend:

// core/types_util.rs:263            — "what kind of type is this?"
syn::Type::Reference(r) => vec![(*r.elem).clone()],

// lang/jnigen/jni/emit/wrapper.rs:516  — "is this a &T?"
InputKind::Handle { direct: true } if !matches!(arg_ty, syn::Type::Reference(_)) => {

// lang/cbindgen/builder.rs:598      — "is this a &[T]?"
let syn::Type::Reference(r) = ty else { .. };
let syn::Type::Slice(s) = &*r.elem else { .. };

Each is an independent decision about what the source Rust means — the decisions #211 says belong to core::frontend alone. #210 was two of them, in one file, disagreeing about [u8; <Holder>::N].

boundary.ledger records how many live in each file. boundary_ledger recomputes and fails if any count moved.

• up — a new classifier landed outside the frontend. Move it in, or regenerate and justify it in review.
• down — one was migrated. That is the goal, and it is still a ledger edit, so F3–F6's progress shows as a diff instead of passing silently.

Why before F1

As written, F8 was seeded from F1's classification of "the 189 sites". That ordering makes F1 a large document that rots the day after it is written, with nothing failing behind it.

Inverted, the ledger freezes the population now — growth stops immediately — and F1 becomes entries coming off the ledger during F3–F6. The allow-list is the classification, not a second copy of it. F1's checklist in docs/source-frontend.md is rewritten accordingly, and its first concrete task is now extending WATCHED one enum at a time, each addition a regenerated ledger whose diff is the decision.

Three load-bearing properties

The count is read off disk, not from the compiled crate. CI runs both cargo test and cargo test --all --all-features, and unstable-cbindgen gates the whole cbindgen suite — so a check that inspected the compiled AST would count a different population in each, i.e. give two answers in one CI run. That is #219's failure mode, and avoiding it is why this walks files.

It walks tokens, not lines and not an AST. A grep -c counts lines rather than occurrences (two on one line is common), counts the five inline #[cfg(test)] mod blocks — so adding a test would fail the check, which is how these ledgers die — and is defeated by one line: use syn::Type; then Type::Reference(_) greps as zero. A syn::visit::Visit walk fixes all three and opens a worse hole: it cannot see inside macro invocations, and a large share of the sites live in matches!(..). A token walk sees patterns, expressions, types and macro bodies alike, and is immune to rustfmt line-wrapping.

The header lists what the check cannot see. Classification that never writes a syn:: path is invisible to it: token-string classification (core/domain.rs matching to_token_stream().to_string() against "f32"), ident-name classification (seg.ident == "Option"), helper delegation (jnigen/jni/classify.rs is a whole classifier with zero watched sites), types_util::match_pattern unification against parse_quote!(_) patterns, and every syn enum outside WATCHED. A check that silently under-reports is worse than no check, so the gaps are named in the ledger header and are F1's queue.

Scope of WATCHED

&["Type", "Expr"] — exactly the population #211 and the branch map already track, and the low-noise one. Emitters construct syn::Item::Fn constantly but rarely construct a syn::Type, so adding Item today would churn the ledger on every emission change. Extending it is one line plus a regenerated ledger.

Honest caveat: a few counted occurrences build syntax rather than classify it — cbindgen/builder.rs:570 returns a syn::Type::Path, which is emission. Separating build from match mechanically costs real code, and those sites are few and stable. The number's job is to not move, not to be a precise census.

The seed number

196 sites across 28 files. The branch map's hand-counted 189 (67/97/25) was wrong in both directions — a recount by hand gives 69/96/26, a token count a third answer. Cross-checked per file against grep -o: types_util.rs 41 vs grep's 42, the difference being a syn::Type::Infer mention inside a doc comment, which is correctly not a classifier. A scoreboard nobody can reproduce is not a scoreboard; the ledger is now the authoritative number and the doc says so.

Verification

• cargo test -p prebindgen boundary — the ledger test and a scanner test over fixture shapes: a match arm, a matches! body, a let .. else, two on one line, an aliased Type::Reference after use syn::Type, a use that must not count, a syn::Item::Fn outside WATCHED that must not count, and a #[cfg(test)] mod replace_ident_tests that must be skipped (that module is real — jnigen/jni/fold.rs:637 — so a name-based rule would miss it).
• Proven to bite, not assumed: adding matches!(t, syn::Type::Never(_)) to jnigen/util.rs fails with api/lang/jnigen/util.rs: 1 -> 2; the same site written as use syn::Type; + Type::Never(_) fails identically, which is the hole the alias handling closes.
• Feature-independent: cargo test and cargo test --all --all-features agree.
• cargo test --all --all-features — green. clippy --deny warnings, fmt — clean.
• ./examples/regen-check.sh — byte-identical. Per the branch's review protocol this stage is must not move; it adds no production code.

Test-only, no new dependency (proc-macro2 is already one), no new CI job — it rides both existing cargo test invocations.

🤖 Generated with Claude Code