unreferenced_by_name: state the census contract, and stop asking the one language that cannot answer it

[squid-protocol]

Closes #2806. Part of #2812 (contract roadmap, Phase 3).

What #2806 asked for, and what the measurement changed

orphaned_logic reported every function in the file as unused for five languages — abap, jcl, m4, makefile, objective-c, all at 3.25 per file against a 2.50 corpus median. The issue proposed suppressing the metric for all five, on the reading that none of them reach a callable unit by name.

That premise held for one of them.

	claim	measurement
abap	no invoke-by-name form	PERFORM probe_branch is one. Real-world ABAP (language-crucible, abapGit) reads 8 unreferenced subroutines in 124 — a 6% rate, entirely through PERFORM
m4	no invoke-by-name form	bare-name macro expansion is one
makefile	no invoke-by-name form	a prerequisite is one (main.mk's one wired probe already cleared)
objective-c	no invoke-by-name form	a selector send is one
jcl	no invoke-by-name form	confirmed. A job's EXEC steps run in the order they are written; nothing in JCL references a step to make it run

What the four had in common was the corpus, not the engine: every median language's main dispatches its three probes (python's entry() calls probe_branch/probe_io/probe_risk), and in those four main declared a dispatch/entry unit that called nothing. Planting each language's own idiom moves all four to the median with no engine change — that is the companion corpus PR.

What this PR does

1. The contract. docs/unreferenced_by_name_contract.md: one hit is one extracted callable unit whose name occurs nowhere in the file outside its own definition, six corollaries, and the 46-language audit. One test per corollary in tests/core_engine/test_unreferenced_by_name_contract_2806.py, plus engine rule 19 in how_to_add_a_language.md.

2. jcl declares invocation_model: "positional" and the census is not computed there — absent, not maximal. Before it, 334 of 376 crucible steps (89%) read unreferenced, and the 42 that cleared did so by accident, not invocation: a step named CREATE beside inline SQL in a SYSIN DD * block, COBOL beside the same word inside a DSN, CRTABS repeated seven times in one job. Both tails were noise. Every other language keeps the by_name default and is unchanged by construction.

3. The rename (#2806 shape (c)). orphaned_logic → unreferenced_by_name; columns state_slop_orphans → state_unreferenced, raw_state_slop_orphans → raw_state_unreferenced. Both old names asserted the count was dead weight, which corollary 3 says the measurement cannot claim — any other occurrence of the name clears the flag, including a mention in a string literal. record_keeper.py renames a pre-#2806 database's columns in place; the values were never wrong, only the label.

One trap worth reading if you review nothing else

The first version of this put _invocation_model: "positional" in rules, beside _scope_filters. language_lens.py's _calibrate_lookup_maps compiles every string value inside rules into a regex (a defensive guard for definitions loaded from external JSON), so the detector received re.compile("positional") and compared unequal to "positional". Every unit test passed — they build the extractor from LANGUAGE_DEFINITIONS directly, which the lens has not touched — and the first golden-master bless was silently wrong. Only a real galaxyscope run on one JCL file showed it. The declaration is now a top-level language property beside lexical_family.

Verification

• pytest tests/ green; signal_contract_audit.py --ci clean; audit_check.py clean (ruff baseline regenerated for pure line-shifts, mypy/dead-key/ast-accuracy OK).
• Golden masters re-blessed, scoped with bless_scope.py and a full uncapped diff: 5,636 key renames (section 7's label), and 564 value differences, every one of them jcl — 150 Tech Debt Exposure (cics-java-jcics-samples 73.11 → 0.0), 34 API Exposure and 34 Documentation Exposure (the orphan → api conversion has nothing to convert), 33 Structural Mass, 267 topological X/Y/Z, and three global aggregates that are the same change summed. No other language moved in either fixture.
• rosetta_audit.py against the companion corpus branch: 44/46 pass; the two that move are the plants' own cost, both re-blessed and ledgered there (abap args 4 → 7, m4 args 6 → 8).

Found on the way, filed rather than fixed here

• unreferenced_by_name reads 0.25/file for haskell and scheme: a module export list and a type signature are declarations, not references #2823 — haskell and scheme read 0.25/file, the opposite sign: a module export list and a type signature are declarations, not references. Needs _visibility_export to yield more than one name per match, plus its own corpus plant.
• abap args counts call-site parameter keywords (CALL FUNCTION ... EXPORTING, PERFORM ... CHANGING) as declared parameters #2824 — abap args counts call-site parameter keywords (PERFORM ... CHANGING, CALL FUNCTION ... EXPORTING) as declared parameters — corollary 1 of the stated args contract. This PR's corpus plant is what exposed it.
• A comment on branch has no stated contract: handler keywords, the syntax words of one conditional, and goto count as decisions in some languages and not in others #2822 — cobol branch counts a bare out-of-line PERFORM (2,191 of 21,549 crucible hits), which is why cobol's plant is deliberately not in the companion PR: it would move a gated cell onto that defect to fix a cell already in band.

Cross-repo

Companion corpus PR: keyword-rosetta#82 — the four plants, the two owed args cells, three ledger entries and the regenerated bias report. This PR merges first; the corpus PR goes green against engine main once it lands. Label: rosetta:rebless-owed.

🤖 Generated with Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab