docs: the // @symbol marker convention for promoted TUs

[andrewboudreau]

Documents the // @symbol marker convention for genuine-TU promotions. Adds section 6 to notes/tu-promotion-conventions.md plus one reviewer-checklist item.

This is documentation-only. One file changed, 146 lines added. No tool, gate, workflow, header, src/ file, config or ledger is touched.

Why

tools/tiers.py scores a promoted TU per member, and // @symbol is the only thing that tells it where one member's text ends and the next begins. score_member (tools/tiers.py:406) says so in its own docstring:

Hand-written members use exact @symbol boundaries. Compiler-generated ctor/dtor variants use the inline lifecycle definition in a directly included class header. Anything without either form of evidence is scored against the entire file, preserving the old conservative behavior.

So one volatile object, one unk_<off> field or one mangled call anywhere in a promoted TU strips the tier from every clean member in it. The convention was load-bearing and documented nowhere.

Measured evidence

Line references, all in tools/tiers.py on main @ 9bfcd5d86:

what	where
SYMBOL = re.compile(r"//\s*@symbol\s+(\S+)")	line 74
_marked_member_fragment — slices marker-to-next-marker, return None if len(matches) != 1	line 309
_balanced_lifecycle_fragment	line 328
_lifecycle_member_fragment — the ctor/dtor second path	line 378
score_file — the five criteria	line 295
score_member — marker, then lifecycle, then whole file	line 406
_code_only — comments blanked before scoring	line 198

Marker counts on the landed promoted TUs, scored with tools/tiers.py against this tree:

promoted TU	members	@symbol markers	5/5	banked in converted-baseline.json
src/actors/daObjKinokoTag_c.cpp	9	7	6	6
src/actors/daObjFm_Battan_c.cpp	9	7	5	5
src/actors/daObjKm3_Kurumajiku_c.cpp	5	3	4	4
src/actors/daEyBm_c.cpp	13	0	2	2

In the first three, the unmarked members are exactly the two destructor variants, covered by the lifecycle path. daEyBm_c marks nothing: eleven of thirteen members fall to the whole-file fallback and all eleven fail the same two criteria — no_unk_field and no_mangled_refs — which are properties of the factory and of Behavior, not of the members being scored. Inserting the eleven marker lines locally and changing nothing else lifts it from 2 to 4 members at 5/5. Its two surviving members are D1/D0, rescued by the inline virtual ~daEyBm_c() {} at include/daEyBm_c.h:54.

The cost, on an open PR

• Promote daObjHatenaSwitch_c to a genuine C++ translation unit #2062 (daObjHatenaSwitch_c, thirteen functions) adds zero markers. Its diff moves config/converted-baseline.json from "count": 2568 to "count": 2560 — 8 credits — and adds 8 rows to config/converted-backslide-exceptions.jsonl, one per lost member, all with the same reason: the TU "needs the volatile stack value to avoid a 17-word codegen mismatch". The volatile is in one member; the other eight paid for it.
• TU: promote ov006/dScMgSingle3DBase_c — nine functions, vtable-proven boundary #2064 (dScMgSingle3DBase_c, nine functions) adds 6 markers and 0 backslide-exception rows. Both are cited in the note as the worked pair, and flagged there as open rather than as landed precedent.

Two things the code settled

• The whole-file fallback poisons four criteria, not all of them. score_member overwrites real_name (from the symbol) and shared_header (from the whole file) after scoring the fragment, so only no_raw_offset, no_unk_field, no_codegen_trick and no_mangled_refs are at risk. shared_header is also not in CRITERIA (line 180) at all — it is reported alongside the tier, not part of it.
• A member's slice runs to the next marker, so an extern "C" declaration written just above a function is charged to the preceding member. Text above the first marker belongs to no member. daObjKinokoTag_c gets this right (its ABI-seam block sits above the first marker on line 40); daEyBm_c does not. That placement rule is now written down.

Also in this PR

One stale line corrected: the note said #2004 (daObjKm3_Kurumajiku_c) was an open draft and "not precedent". #2004 is closed and that class landed via #2057, so the file is on main. Added a dated *Update.* under the original paragraph rather than rewriting it, so the section-2 measurements taken while it was a draft stay readable.

Gates

• python tools/check_dead_references.py — no new dead references, no broken markdown links, exit 0.
• Committed blob has zero CR bytes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WdCK1xgrJdiJzPCh3bAJfQ

[tangos-validator]

✅ PR validation — Passed

noverify: no source/build-data changes in this PR

_{Each changed src/*.c|*.cpp is compiled and its relocated bytes compared to the binary data on a private build box. Passing requires every changed file to reproduce the ROM byte-for-byte with correct relocation targets — this catches WRONG-DEST relocations and non-reproducing near-misses that ledger-scoped linkcheck skips.}