fix(makefile): credit .PHONY external entry points as api surface, not tech debt (#2904)

[squid-protocol]

Closes #2904.

Problem

A makefile's callable units are invoked externally — a human typing make all, CI, a Dockerfile — never by an in-repo caller or an import. Its popularity is therefore structurally 0, so galaxyscope's Contextual Baseline Fix (which credits an imported file's orphans to api surface — tier 2) can never reach it. Every .PHONY: entry point falls through to risk_tech_debt (e.g. an 18-line, fully-correct makefile reading 99.33% debt).

Fix — tier-3 external-entry-point rescue (one classification-layer change, per #2812 rule 4)

• New closed registry key export_visibility (detector.py), mirroring orphaned_logic reports 100% dead code for five languages whose invocation model never names the callee — the family #2727 closed without covering #2806's invocation_model: standard (default, census-everything) vs external_entry_points. Only makefile opts in — its .PHONY: (_visibility_export_list) names exactly the external interface, unlike a JS/TS export that decorates every symbol and would blind orphan census: an export -f name line counts as a use, so a declared-public uncalled function can never be reported dead #2774. splice emits a per-file exports_are_external_entry_points flag into the payload.
• Tier-3 branch in the Contextual Baseline Fix (galaxyscope.py), gated elif on the tier-2 branch not firing: for an opted-in file it clears the declared entry-point orphans (api_declared_orphans) from unreferenced_by_name and heals their usage_status.
  • Per-unit correct: only the declared portion moves. A genuinely internal, undeclared orphan target (never .PHONY, no in-repo caller) stays real dead weight — cpython's Makefile.pre.in drops 57 → 21 orphans, not to 0, keeping its 21 undeclared internal targets as debt.
  • No api double-count: a declared entry point's declaration line is already an api-rule hit, so api is left unchanged.
  • Census preserved: recorder: raw pre-adjustment hit_vector is unrecoverable once the Contextual Baseline Fix rewrites api/orphaned_logic #2536's raw_pre_adjustment snapshot still holds the honest orphan count; only the debt/surface classification moves.
• Decision (confirmed): the _calc_api_exposure popularity == 0 80% dampener is kept — tier-3 does not touch meta["popularity"]. Lifting it (via a synthetic popularity) is a possible follow-up, noted in makefile .PHONY entry points read as tech debt: the Contextual Baseline Fix has no external-invocation tier #2904.

Verification

• New test_export_visibility_contract_2904.py (closed-set + opt-in family, mirroring the orphaned_logic reports 100% dead code for five languages whose invocation model never names the callee — the family #2727 closed without covering #2806 contract) and test_galaxyscope.py::...tier3... (bootos all-declared → census 0, api unchanged; a mixed file keeps its undeclared internal orphan as debt; a non-opted-in language untouched).
• Golden masters regenerated (both legs); bless_scope footprint = 13 substantive diffs, leaf keys Tech Debt Exposure / Unreferenced By Name / tech_debt / avg_tech_debt only, no file newly parsed or excluded (rule did not cross the density aperture).
• rosetta 46/46, 0 regressions — its makefile fixture's targets are all referenced, so nothing moves. No paired keyword-rosetta corpus rebless is owed.
• ruff_audit/mypy_audit/dead_key_audit --ci: no new findings. Full pytest tests/: 8738 passed (only the pre-existing test_security_auditor.py xgboost-env failures, identical on origin/main).

Out of scope (follow-ups noted in #2904)

• risk_tech_debt over-sensitivity at small unit counts (3-of-4 in an 18-line file).
• Lifting the popularity == 0 api-exposure dampener for tier-3 via a synthetic popularity signal.

🤖 Generated with Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab