<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-01-1-dead-symbol-allowlist-module-name-identity/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-01-1-dead-symbol-allowlist-module-name-identity/</id>
  <title>ADR: dead-symbol allowlist identity is (module, name)</title>
  <updated>2026-10-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-01-1-dead-symbol-allowlist-module-name-identity/"/>
  <summary>Accepted: dead-symbol allowlist entries are keyed (module, name) in a schema-checked YAML file; body hashes are computed at runtime only and never persisted.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-01&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), through the operator rulings recorded in
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/test-suite-remediation-01M3SSDW/decisions/&lt;/code&gt; (Decision Moments
&lt;code dir=&quot;auto&quot;&gt;DM-01M3SSRY&lt;/code&gt;, which put the re-key in scope, and &lt;code dir=&quot;auto&quot;&gt;DM-01M3SVDP&lt;/code&gt;, which withdrew
the census gate) and the plan rulings R2, RK-4 and RK-6 of that Mission.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5346&quot;&gt;#5346&lt;/a&gt;
under &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5353&quot;&gt;#5353&lt;/a&gt;, Mission
&lt;code dir=&quot;auto&quot;&gt;test-suite-remediation-01M3SSDW&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_symbols.py&lt;/code&gt; fails when a name in a module’s
&lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; has no non-test caller. Documented exceptions are held in an
allowlist. Before this ADR, each allowlist entry was a &lt;code dir=&quot;auto&quot;&gt;SymbolKey&lt;/code&gt; literal
inside the 4,800-line gate file, keyed on a &lt;strong&gt;persisted content hash&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;D-1 of Mission &lt;code dir=&quot;auto&quot;&gt;relocation-hardened-dead-code-scanners-01KX958P&lt;/code&gt; chose a
location-free content tier, &lt;code dir=&quot;auto&quot;&gt;(bare_name, body_hash)&lt;/code&gt;, so that a pure move
would keep its key. A module_path tier, &lt;code dir=&quot;auto&quot;&gt;(bare_name, module_path, body_hash)&lt;/code&gt;,
was escalated only for live same-name, same-hash collisions (18 entries).&lt;/li&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;frozen-baseline-toll-reduction-01M0A42D&lt;/code&gt; (FR-001/FR-002) added a
fail-closed refresh helper, &lt;code dir=&quot;auto&quot;&gt;_refresh_dead_symbol_hashes.py&lt;/code&gt;, that rewrote a
stale &lt;code dir=&quot;auto&quot;&gt;body_hash&lt;/code&gt; literal in the gate file.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3552&quot;&gt;#3552&lt;/a&gt; (FR-006/FR-007)
added a required &lt;code dir=&quot;auto&quot;&gt;source_module=&lt;/code&gt; provenance field and guards that red when
that module stops declaring the name.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The hash made every body edit an allowlist edit. Since the &lt;code dir=&quot;auto&quot;&gt;source_module&lt;/code&gt;
backfill on 2026-08-18, 41 of 78 commits that touched the allowlist carried a
body-edit re-pin: 57 re-pinned entries in total. In 25 of those commits the
re-pin was the only allowlist change. None of the sampled re-pins changed a
rationale; they re-pinned mechanically. The hash was not even formatter-stable:
&lt;code dir=&quot;auto&quot;&gt;2641f6b181&lt;/code&gt; re-pinned &lt;code dir=&quot;auto&quot;&gt;DeclaredCommandScopeSource&lt;/code&gt; because &lt;code dir=&quot;auto&quot;&gt;ruff format&lt;/code&gt; joined
a three-line call onto one line.&lt;/p&gt;
&lt;p&gt;The benefit D-1 bought, relocation-proof identity, was already gone in
practice. The #3552 provenance guard forced a &lt;code dir=&quot;auto&quot;&gt;source_module=&lt;/code&gt; edit on every
move: the &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; package rename (&lt;code dir=&quot;auto&quot;&gt;f5c15f9f88&lt;/code&gt;) edited 28
entries, and the charter-activation split (&lt;code dir=&quot;auto&quot;&gt;e72f8b8a0b&lt;/code&gt;) edited 26.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A behaviour-neutral body edit must cost zero allowlist edits (SC-003).&lt;/li&gt;
&lt;li&gt;The gate must not weaken: a new dead symbol still reds, and a stale entry is
still reported (C-007 canon; &lt;code dir=&quot;auto&quot;&gt;architectural-gate-non-vacuity&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Exemption data lives apart from gate logic, under one authority per gate
(single canonical authority; DIRECTIVE_044).&lt;/li&gt;
&lt;li&gt;Every mutable architectural allowlist is capped in &lt;code dir=&quot;auto&quot;&gt;_baselines.yaml&lt;/code&gt;
(Charter Burn-down Policy (a)); the dead-symbol allowlist had no cap.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;(module, name)&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;module&lt;/code&gt; is the &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt;-declaring module (chosen).&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;(module_path, qualname)&lt;/code&gt;: the same key in practice, because the gate only
covers module-level names. Rejected as a name: “qualname” promises nested
coverage the gate lacks.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;(bare_name, source_module)&lt;/code&gt; plus a stored advisory hash for rename hints.
Rejected: a stored hash nothing enforces rots and invites “just refresh it”.&lt;/li&gt;
&lt;li&gt;Keep &lt;code dir=&quot;auto&quot;&gt;(bare_name, body_hash)&lt;/code&gt; and run the refresh helper automatically.
Rejected: its output is still a test-source edit, so it fails SC-003; the
helper existed since &lt;code dir=&quot;auto&quot;&gt;01M0A42D&lt;/code&gt; and the 57 re-pins happened anyway.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;Chosen option 1, because it is the only option whose key a body edit cannot
change (SC-003): &lt;code dir=&quot;auto&quot;&gt;module&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt; are both structural facts about where a
name is declared, never a function of its content, unlike option 3’s stored
hash or option 4’s &lt;code dir=&quot;auto&quot;&gt;body_hash&lt;/code&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Identity.&lt;/strong&gt; An allowlist entry is &lt;code dir=&quot;auto&quot;&gt;DeadSymbolKey(module, name)&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;module&lt;/code&gt; is
the dotted module whose &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; declares the name; &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt; is the bare
module-level name. An &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; is a set, so the key is unique per location
by construction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Location.&lt;/strong&gt; The data lives in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/dead_symbol_allowlist.yaml&lt;/code&gt;
and is read by one loader, &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_dead_symbol_allowlist.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;load_allowlist&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ALLOWLIST&lt;/code&gt;). The loader enforces rules L1–L10 at import:
exact top-level keys, no duplicate mapping keys, &lt;code dir=&quot;auto&quot;&gt;schema_version: 1&lt;/code&gt;, only
allowed record keys (so &lt;code dir=&quot;auto&quot;&gt;line:&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;body_hash:&lt;/code&gt; and the retired provenance field
are refused), non-empty rationales, declared categories with an &lt;code dir=&quot;auto&quot;&gt;issue&lt;/code&gt; where
&lt;code dir=&quot;auto&quot;&gt;requires_issue&lt;/code&gt; is true, whole-file &lt;code dir=&quot;auto&quot;&gt;(module, name)&lt;/code&gt; uniqueness, no tombstone
categories, and identifier-shaped &lt;code dir=&quot;auto&quot;&gt;module&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt; values.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Categories.&lt;/strong&gt; Category ids are the former &lt;code dir=&quot;auto&quot;&gt;_CATEGORY_*&lt;/code&gt; constant names,
lower-cased with the leading underscore dropped (&lt;code dir=&quot;auto&quot;&gt;category_*&lt;/code&gt;, ruling RK-4).
&lt;code dir=&quot;auto&quot;&gt;requires_issue&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;false&lt;/code&gt; for every category today.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The #470 widened list&lt;/strong&gt; is folded into the same file, as the
&lt;code dir=&quot;auto&quot;&gt;widened_grandfathered_470&lt;/code&gt; section (91 entries), so the gate has one
exemption authority.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Body hashes are never persisted.&lt;/strong&gt; The gate still computes one at runtime,
for two jobs only: the keyability precondition (an allowlisted name must bind
a real definition, alias or facade entry, or the entry is INVALID) and
condition (1) of the re-export auto-exempt (a live same-name collision is
never auto-exempt).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stale verdicts.&lt;/strong&gt; Each entry that no longer earns its place gets exactly one
verdict, first match wins: INVALID (declared but un-keyable), GONE (no longer
in that module’s &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt;; a move gets a “probably moved to &lt;code dir=&quot;auto&quot;&gt;X&lt;/code&gt;; update
&lt;code dir=&quot;auto&quot;&gt;module:&lt;/code&gt;” hint), REVIVED (it has a caller again), SUPERSEDED (a structural
auto-exempt now covers it) and MOOT (the module is star-imported, so the entry
exempts nothing).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retired.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_refresh_dead_symbol_hashes.py&lt;/code&gt; and its tests are deleted, and
so is &lt;code dir=&quot;auto&quot;&gt;SymbolKey.source_module&lt;/code&gt; with its guards.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Size ratchet.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_baselines.yaml&lt;/code&gt; gains the section
&lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols&lt;/code&gt; with two shrink-only leaves: &lt;code dir=&quot;auto&quot;&gt;allowlist_entries: 293&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;widened_grandfathered_470: 91&lt;/code&gt; (ruling RK-6). The count lives only there,
never in the YAML data. The exact &lt;code dir=&quot;auto&quot;&gt;len(_REQUIRED_TOP_LEVEL_KEYS) == 15&lt;/code&gt; pin in
&lt;code dir=&quot;auto&quot;&gt;test_ratchet_baselines.py&lt;/code&gt; became the floor &lt;code dir=&quot;auto&quot;&gt;&gt;= 16&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The migration was lossless. The 294 &lt;code dir=&quot;auto&quot;&gt;SymbolKey&lt;/code&gt; literals collapsed to 293
entries: a duplicate &lt;code dir=&quot;auto&quot;&gt;check_push_safety&lt;/code&gt; literal inside one category had been
silently deduplicated by the frozenset. Nine empty tombstone categories were
dropped. The parity check compared the migrated YAML rows with the pre-migration
set: 293 = 293 entries, 91 = 91 widened entries, 0 category mismatches, and the
same digest on both sides
(&lt;code dir=&quot;auto&quot;&gt;c86703f3d8904b128cfb823e043915971298eb892995ad708bb2ea35707607a1&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Non-vacuity is kept by a corpus floor (at least 3,500 &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; names across at
least 600 modules, so a walker that silently scans a fraction of &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; reds),
by the M1–M13 mutation battery in &lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;test_dead_symbol_allowlist_contract.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;test_dead_symbol_allowlist_loader.py&lt;/code&gt;, and by
&lt;code dir=&quot;auto&quot;&gt;test_p1_planted_regression&lt;/code&gt;, which still catches a planted dead symbol.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A body edit to an allowlisted symbol costs zero allowlist edits (SC-003).&lt;/li&gt;
&lt;li&gt;Persisted collision escalation is gone, and with it the 18 module_path-tier
entries: a byte-identical rogue sibling in another module has a different
key. The runtime collision check survives as condition (1) of the
re-export auto-exempt (above) — a live same-name collision is still never
auto-exempt — it is only the persisted two-tier key that is retired.&lt;/li&gt;
&lt;li&gt;Duplicates within one category are now detectable (loader rule L8); the
frozenset union used to hide them.&lt;/li&gt;
&lt;li&gt;The gate file stops co-changing with &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; for data reasons, so its history
records logic changes.&lt;/li&gt;
&lt;li&gt;Charter Burn-down Policy (a) is honoured: the allowlist is capped.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A move or rename costs one YAML edit: the old entry is reported GONE, with a
“probably moved to” hint for a move, and the new location is a fresh
offender. This is the same cost as before, now explicit and hinted.&lt;/li&gt;
&lt;li&gt;The bite tests that encoded the old contract are retired or inverted:
&lt;code dir=&quot;auto&quot;&gt;bite_b&lt;/code&gt;, the body-edit arm of &lt;code dir=&quot;auto&quot;&gt;bite_g&lt;/code&gt;, and the relocation arm of &lt;code dir=&quot;auto&quot;&gt;bite_j&lt;/code&gt;.
M1, M7 and M8 cover the new contract.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SymbolKey.source_module&lt;/code&gt; and its G1–G6 guards are deleted.&lt;/li&gt;
&lt;li&gt;MOOT is stricter than the old behaviour, where an entry for a star-imported
module lingered silently. The live tree has no star-imported targets, so
this caused no red on landing.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The gate file keeps its name, marker and asserts; it stays in the C-007
enforcement canon.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_symbols.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;test_dead_symbol_allowlist_contract.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;test_dead_symbol_allowlist_loader.py&lt;/code&gt; are green on the live tree.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ratchet_baselines.py&lt;/code&gt; enforces the two
&lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols&lt;/code&gt; leaves.&lt;/li&gt;
&lt;li&gt;The gate’s guidance for contributors is in
&lt;a href=&quot;/development/reference/ci-gate-mechanics/&quot;&gt;CI and Architectural Gate Mechanics&lt;/a&gt;
and &lt;a href=&quot;/development/how-to/add-architectural-gate-exemption/&quot;&gt;Add an exemption to an architectural gate&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;supersession&quot;&gt;Supersession&lt;/h2&gt;
&lt;p&gt;This ADR &lt;strong&gt;partially supersedes&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;D-1 of Mission &lt;code dir=&quot;auto&quot;&gt;relocation-hardened-dead-code-scanners-01KX958P&lt;/code&gt;&lt;/strong&gt;, for the
persisted identity only. The runtime content key, collision classification
and keyability check remain in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/_symbol_key.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission &lt;code dir=&quot;auto&quot;&gt;frozen-baseline-toll-reduction-01M0A42D&lt;/code&gt; FR-001/FR-002&lt;/strong&gt;: the
refresh helper is retired.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission &lt;code dir=&quot;auto&quot;&gt;frozen-baseline-toll-reduction-01M0A42D&lt;/code&gt; FR-005&lt;/strong&gt;: its guarantee
that an inert &lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols&lt;/code&gt; baselines key cannot re-enter is subsumed
by the ratchet table’s row-to-leaf bijection. The section now exists again as
an enforced ratchet.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#3552 FR-006/FR-007&lt;/strong&gt;: the &lt;code dir=&quot;auto&quot;&gt;source_module&lt;/code&gt; field and its guards are deleted.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The superseded Mission artefacts are immutable and are not edited.&lt;/p&gt;
&lt;h2 id=&quot;non-goals&quot;&gt;Non-goals&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Changing the caller detectors (&lt;code dir=&quot;auto&quot;&gt;from&lt;/code&gt;-imports, module-attribute access,
&lt;code dir=&quot;auto&quot;&gt;getattr&lt;/code&gt; strings, facade dictionaries, dynamic accessors).&lt;/li&gt;
&lt;li&gt;Changing the #470 widened scope or its stale semantics.&lt;/li&gt;
&lt;li&gt;Removing condition (1) of the re-export auto-exempt; that is a follow-up.&lt;/li&gt;
&lt;li&gt;Renaming &lt;code dir=&quot;auto&quot;&gt;test_no_dead_symbols.py&lt;/code&gt;, which stays in the C-007 canon.&lt;/li&gt;
&lt;li&gt;Adding a census gate (C-008).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;links&quot;&gt;Links&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Related: &lt;a href=&quot;/adr/3.x/2026-09-14-1-census-floor-ratchet-adjudication/&quot;&gt;ADR 2026-09-14-1, census-floor ratchets: per-ratchet adjudication&lt;/a&gt;.
It is the precedent for adjudicating a toll ratchet on its own merits, and the
reason this Mission adds no census gate.&lt;/li&gt;
&lt;li&gt;Research: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/test-suite-remediation-01M3SSDW/research/dead-symbol-rekey.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/test-suite-remediation-01M3SSDW/contracts/dead-symbol-allowlist.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
