check_kernel_residuals: a bare, uncorroborated strings-only line is not a residual (macOS) - #525

What

scripts/check_kernel_residuals.py no longer reports a free-standing, uncorroborated strings line as an unruled identifier. The macOS arm64 Release kernel archive prints the 4-byte machine-code run TvJO through strings -a (whole line TvJO; not an nm symbol; no source text contains it), and the "Tv/TV camel case" vocabulary read it as an identifier with no ADR-0001 row. test_kernel_residuals has been red on every compiled main macOS Release run since the kernel-residuals vocabulary rule because of it.

The rule

An unruled identifier finding is dropped only when all of these hold:

• its surface is strings,
• the whole stripped line is exactly that one identifier, and
• none of (a) normalised nm symbols, (b) installed-header code and header-literal identifiers, (c) the identifiers of the decoded, joined string values of the kernel sources contains it.

(c) is a new, separately collected set (decode_string_literal: simple, hex, octal and universal escapes, adjacent, prefixed and raw literals; directives and include paths kept apart). The legacy source-literal surface, its findings and its role in ruled-row presence are unchanged. Ruled rows are resolved before the suppression, so presence and stale-row behaviour are unchanged. Texts, separators, phrase hits, nm, header and source-literal findings are judged exactly as before. No ADR row, no vocabulary or regex change, no length-floor change, no special case of the token.

Limit (stated, not closed)

Bare identifier-only archive strings now require symbol, header, or decoded/joined source-literal evidence; this removes printable machine-code noise but also stops detecting otherwise uncorroborated bare names assembled as character arrays or macro-built data, which the previous strings-only rule would have reported.

The same hole in the shapes the reviewer listed: a bare archive identifier line with no symbol, installed-header token or decoded source literal behind it is dropped, which also covers a stringised macro argument (#x alone), a __func__ string of a function with no symbol left, pieces joined across a preprocessor conditional ("tv_" #if A "foo" #endif), and any compiled literal outside the scanned set (a generated file, a header outside src/ and the installed set). On the kernel scope at this commit none of them occurs (the reviewer's greps: no __func__; the two #field macros always carry a "trades." prefix so their result is a dotted text, still judged; no literal split across #if; no kernel include of include/pineforge/source or compat; one char-array initialiser, tags{'E','T','O','V','K','X','H'}, which is not vocabulary). Nothing real is lost today; the gate is silent at exactly the moment someone adds such a name. Optional later hardening (not in this PR): add the identifiers of the kernel sources' code (comments stripped, literals blanked) to the corroboration set.

Evidence of the failure being fixed

macOS Release diagnostics (run 40259306020, job 121368062308): test_kernel_residuals failed with exactly ONE finding, unruled 'TvJO' ... line=[[TvJO]] (... 188 archive hits ... 1 findings ... FAIL). Nothing else was red in that test.

How the PR proves it

• Row test BareStringsTests.test_an_uncorroborated_bare_identifier_is_not_a_finding: the exact bare line TvJO (and an unrelated TvQZ) with no nm, header or source evidence gives no finding and exit 0. It is red on the base checker (one unruled finding); the lab "red on base" job runs the new tests against the old checker: rj-20261026t050742-abe8cb: exactly the 3 expected subtests fail on the old checker (61 tests run).
• Preservation controls (green on the base, by design): nm-corroborated and source-literal-corroborated bare names (TvJO, tv_foo, three-character tv_) stay findings; escaped (hex, octal, universal), joined, prefixed and raw literals keep their finding through the decoded set; texts, separators, phrase hits and a ruled bare line (live and stale) behave as before; the existing header-only ruling control is untouched.
• Real-archive controls through check() on a compiled probe archive (Linux): lab remote ctest-only kernel_residuals: rj-20261026t050054-766c02 on the fix commit: PASS (Ran 61 tests ... OK); re-run on the merged tree ec60b10394c4: rj-20261026t054611-c1edb4: PASS.
• This PR does NOT prove the fix on macOS. The kernel-residuals check on a macOS archive runs only in ci-post; the first macOS proof is the cut commit's ci-post. No ci-post run was dispatched on this branch. What the PR carries is the row test above (red on the base, green on the fix) plus the Linux kernel leg. Risk: if the cut-commit ci-post shows any OTHER finding (another machine-code run, or TvJO with one more printable byte, which this rule does not cover), the window to fix it is the last push at 19:00.

Not run on the author's Mac.

🤖 Generated with Claude Code