CONVERTED tier: stop scoring MMIO as a codegen trick, and TU promotions as deletions

[andrewboudreau]

Two defects in the CONVERTED-tier gate. Both are the same species — the gate counting something other than what it says it counts — and both are tools/ + baseline only, with no source touched.

Defect 1 — tools/tiers.py scored hardware registers as a codegen trick

no_codegen_trick ORs LAUNDER, VOLATILE and ASM, and VOLATILE was a bare \bvolatile\b. On a Nintendo DS the only way to reach VRAM, the geometry engine or the IPC/DMA/divider registers is a volatile-qualified pointer, so the criterion failed the code that had no alternative:

file	volatile hits	what they are
src/_ZN8dScene_c22ResetHardwareRegistersEv.cpp	74	stores to 0x0400xxxx and VRAM bank registers
src/_ZN2GX13SetBankForTexEt.cpp	25	VRAM bank control
src/_ZN3G2x12SetBGyAffineEPVtP9Matrix2x2iiii.cpp	5	the register block is a parameter

That compounds with the TU work rather than sitting still: the criteria are file-wide, so a reconstructed TU that absorbs any of those inherits the failure whole.

The two shapes are separable by what is volatile-qualified:

• MMIO qualifies the pointed-to type, so a * follows it — *(volatile u32 *)0x4000400, volatile u16 *ime, volatile DMAChannelRegs *reg, f(volatile void *dst).
• Match hack qualifies an object — volatile int li;, volatile Vector3 v;, volatile s32 zero = 0;, the (s32)(volatile s32)rsc round-trip that demotes a local out of a register, and Node *volatile arr[4] where the pointer rather than the pointee is volatile.

-VOLATILE = re.compile(r"\bvolatile\b")
+VOLATILE = re.compile(r"\bvolatile\b(?![\s\w:]*\*)")

A negative lookahead rather than the equivalent greedy form on purpose: [\s\w:]*\* would backtrack into the type name, stop mid-identifier and call volatile u32 *p a scalar.

Both directions were measured, not assumed — a volatile regex that stops catching match hacks is a worse defect than the one being fixed.

• Files scoring a codegen trick: 655 → 254. All 401 released were confirmed MMIO-only.
• The 254 kept still include every volatile int li; spill pad, every volatile Vector3 v; stack reserver, every volatile int dummy[4]; frame filler, the (volatile s32) round-trip and the Node *volatile form.
• no_codegen_trick 10,623 → 11,020; CONVERTED 2,511 → 2,568 functions, 22.20% → 22.71%. Additions only.

Known conservative reading, documented at the regex rather than hidden: typedef volatile u32 vu32; used only as vu32 * (4 files) still scores. Excluding typedefs opens a real evasion — typedef volatile int vi; vi dummy; would carry no volatile at the use site at all.

Defect 2 — tools/tiers_ratchet.py reported a TU promotion as a vanished file

The ratchet banks the SET of paths passing all five criteria and fails when a path leaves. A TU promotion consolidates N per-symbol src/_ZN....cpp files into the one src/actors/X.cpp they always were; git records that as N deletions plus one addition, so every one read as:

GONE -- not a tracked source file any more (deleted, renamed or moved)

Measured on PR #1882 (tu/inline-dtor-order, 9c6396c5f): 90 of 90 backslid paths were TU legacy_source entries whose TU is "status": "promoted" and whose promoted_source exists on the branch. Zero were real deletions. A gate whose entire output is false alarms trains people to re-bank without reading it.

A GONE path is now resolved through the manifest — via tools/tu_manifest.py, never the files — and reported as a MOVE naming the absorbing file and what that file does with the five criteria:

  src/_ZN15daObjPathLift_cD1Ev.cpp
      MOVED -- absorbed into src/actors/daObjPathLift_c.cpp by TU promotion
      (ov100/daObjPathLift_c), which fails: No raw offset arithmetic
      (*(u32*)(c + 0x74)); Calls things by real names, not mangled _Z

versus a genuine deletion, which still reads GONE.

A promotion is not free. The criteria are file-wide, so a clean function merged into a file with one bad line really does lose its status, and that case still exits 1. Only a move into a file that itself passes all five is silent (it is then an ordinary addition on the next --update). Both halves are exercised on live data by the current manifest: the two _ZN7fBase_c9SceneNode* legacy paths absorbed into src/actors/ActorBase_SceneNode.cpp are clean moves; the eight absorbed into src/actors/daObjPathLift_c.cpp still fail.

In practice a promotion lands in the failing case by construction: a reconstructed TU must spell _ZN7fBase_cnwEj, _ZN8dActor_cC2Ev and _ZN8dActor_cD2Ev directly or its range will not link, so no_mangled_refs can never pass for one. That is structural, not sloppiness, and it is not fixed by exempting mangled refs — byte-match outranks readability, and --update --reason is where that trade gets a name against it. --check now says so in its footer when a MOVE is among the failures.

Re-banked in the same PR

Changing a criterion requires re-baking the baseline or CI goes red.

python tools/tiers_ratchet.py --update
wrote config/converted-baseline.json: 1957 -> 2567 (+610 / -0)

Zero removals — set-diffed against HEAD, not trusted from the counter. The diff looks larger than +610 only because the previous file was not sorted and write_baseline sorts; the old "count": 1958 was also stale against its own 1957-entry list and is now consistent.

Verification

python tools/tiers_ratchet.py --check     # CONVERTED ratchet PASS  baseline 2567  current 2567   (exit 0)
python tools/tiers.py                     # clean, exit 0
python -m unittest tools.test_tiers        # 29 tests, OK
python -m unittest tools.test_tu_manifest  # 25 tests, OK
python tools/check_python_names.py         # PASS
python -m pyflakes tools/tiers*.py         # clean

tools/rombuild.py and tools/eligible.py were deliberately not run: no source file is touched and the build directory is shared with other agents.

Also in here

• tools/test_tiers.py (new, 29 tests) pins both readings in both directions — MMIO must not score, a match hack still must; a promotion must read as a MOVE, and a move into a failing file must still fail the gate.
• .github/workflows/converted-ratchet.yml runs those tests, and now also triggers on tools/tu_manifest.py and config/tu_manifest.d/** — a PR that only re-labels an entry "status": "promoted" changes what this gate says about an existing baseline.
• notes/converted-tier.md gains a dated section for both, in the style of the existing writeup.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WdCK1xgrJdiJzPCh3bAJfQ

[tangos-validator]

✅ PR validation — Passed

Committed merge introduces no reconstruction or attribution regression.

Full merge validation

Check	Result
Committed test merge	yes
Byte-verified functions	11,048 / 11,347 (97.36%, +0)
Byte-verified code bytes	2,050,236 / 2,211,124 (92.72%, +0)
Claimed, not byte-verified	168 functions, 55,068 bytes (+0)
Perfect source moves	0 R100
Enrolled ranges (delinks complete)	11,058 functions, 2,052,772 bytes (92.84%, +0) -- differs from byte-verified by +10
Contributor credit	0 added, 0 changed, 0 lost
Relocation check	0 checked; no affected slots
Module fidelity	106/106 exact; 100.000000% compared bytes
Code linked from verified source	11,087 functions, 2,066,772 bytes (93.47%)
Module bytes from source	2,066,772 / 3,049,600 (67.8%); 811,492 (26.6%) are data no delink entry reaches
ROM data reproduced from source	446 symbol(s) exact, 242 partial, 15 differ

Byte-verified means the range carries complete in a delinks.txt, so the ROM build compiled it and compared it to the cartridge. The 168 claimed functions have a src/ file named after the symbol with no NONMATCHING banner, and nothing compiles them -- dsd fills their addresses with the ROM's own bytes. Both together are the 11,216 this project calls matched.

_{The private worker commits a test merge, builds the stock ROM profile, compares every executable module, measures matched and source-built code, checks contributor lineage, and verifies affected relocations. The mod profile is opt-in and is not part of this merge gate.}