comments: the generators, the tools and the reference table headers

Docstrings keep their usage and exit codes; table headers keep the
column contract and the client addresses and lose the dates, the
correction history and every path into another repository. A
generated header changes in its generator's template, so each of the
four generators still reproduces its output byte for byte, and no data
row changed in any of the seven tables.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

reference/1.12-event-catalog.tsv

@@ -1,12 +1,11 @@
-# FrameScript C->Lua event catalog — eventId -> name, extracted from WoW.exe 1.12.1.5875
-# source: the event-name pointer array at .data 0xbe1198 (stride 4, 0x225=549 slots), RE 2026-06-21,
-#   BASE CORRECTED 2026-07-21 (was 0xbe11d8 -> every id was 16 too low; see
-#   system/object-layer/scratch/lootroll-chat-and-lifecycle.md §3). The base is VERIFIED at
-#   0x48fea1-0x48feab: `mov edx,0x225; mov ecx,0xbe1198; call 0x703d90`, and 0x703d90 builds the
+# FrameScript C->Lua event catalog of the 1.12.1 client (WoW.exe build 5875): eventId -> name.
+# Source: the event-name pointer array at .data 0xbe1198 (stride 4, 0x225 = 549 slots), passed
+#   at 0x48fea1-0x48feab (`mov edx,0x225; mov ecx,0xbe1198; call 0x703d90`). 0x703d90 builds the
 #   runtime 16-byte-stride dispatch table [0xceef68] as table[i].name = strdup(nameArray[i])
-#   (0x703e06-0x703e2e), so the id passed to FrameScript_SignalEvent 0x703e50 / 0x703f50 IS this index.
-# NB slots 0..15 carry no `mov imm32` name write in this scan (they are set from a register at
-#   0x51acbf and neighbours); coverage is unchanged from the pre-correction extraction (383 rows).
+#   (0x703e06-0x703e2e), so the id passed to FrameScript_SignalEvent 0x703e50 / 0x703f50 is
+#   this index.
+# Slots 0..15 carry no `mov imm32` name write in this scan (they are set from a register at
+#   0x51acbf and neighbours).
 0	UNIT_PET
 2	UNIT_PET
 16	UNIT_HEALTH

reference/1.12-event-firesites.tsv

@@ -1,50 +1,39 @@
-# C->Lua event fire sites — every call AND TAIL-JMP to FrameScript_SignalEvent (0x703e50, ecx=eventId)
-# (the 85 `jmp 0x703e50` sites were absent until 2026-08-21 — the census had been written over `call`
-#  alone, so a tail-jmp fire read as "this event has no fire site here"; see re/audit/re-sweep-status.md)
-# and SignalEvent2 (0x703f50, [esp]=eventId + printf-style arg_format). eventId resolved via event-catalog.tsv.
-# eventId "dyn" = computed (e.g. a UnitField update loop); blank name = eventId has no entry in the name table.
+# C->Lua event fire sites of the 1.12.1 client (build 5875): every call and tail-jmp to
+# FrameScript_SignalEvent (0x703e50, ecx=eventId) and SignalEvent2 (0x703f50, [esp]=eventId +
+# printf-style arg_format). eventId is resolved via 1.12-event-catalog.tsv; "dyn" = computed
+# (e.g. a UnitField update loop); a blank name = the id has no entry in the name table.
 #
-# CAVEAT (2026-09-04, staticpopup round): the `arg_format` column is the FORMAT STRING the site pushes,
-# which is a declaration, NOT a census of what the caller actually pushed. The marshaller 0x704f10
-# consumes one vararg per directive (%f eight bytes, everything else four), so a site whose format
-# declares more than its caller pushed hands Lua undefined values. `re/audit/signalevent2-fmt-args.py`
-# audits all 149 sites (0 unadjudicated) and finds exactly THREE such sites -- read that column with
-# these in mind: 0x496230 TRADE_REPLACE_ENCHANT "%s%s%d" declares 3 and pushes 2; 0x5e4527 and
-# 0x5e7960 UPDATE_TICKET "%d%s%f%f%f%d%d" declare 10 dwords and push 7 (their sibling 0x5e45e2 pushes
-# the full 12). Every other site's format matches its caller. See method.md §6.
+# arg_format is the format string the site pushes: a declaration, not a census of what the
+# caller pushed. The marshaller 0x704f10 consumes one vararg per directive (%f eight bytes,
+# everything else four), so a format that declares more than its caller pushed hands Lua
+# undefined values. Of the 149 SignalEvent2 sites exactly three do: 0x496230
+# TRADE_REPLACE_ENCHANT "%s%s%d" declares 3 and pushes 2; 0x5e4527 and 0x5e7960 UPDATE_TICKET
+# "%d%s%f%f%f%d%d" declare 10 dwords and push 7 (their sibling 0x5e45e2 pushes the full 12).
+# Every other site's format matches its caller.
 #
-# CAVEAT (2026-09-03, found while carving `UpdateSpells` for benilla; the answer was already on `main`
-# in system/glue/): the `name` column resolves every id through event-catalog.tsv, which is the
-# IN-GAME table (0xbe1198, 549 entries). 0x703d90 is called TWICE with different populations --
-# 0x46a88f with (0xb41e70, 26) for the GLUE phase and 0x48feab with (0xbe1198, 549) for the world --
-# and it rebuilds [0xceef68] wholesale from whichever it is handed, so THE SAME INTEGER NAMES A
-# DIFFERENT EVENT IN THE TWO PHASES and 0x703e50 bounds-checks nothing. 22 rows here sit in a
-# `Source\Glue\` TU (0x46aa34; 0x46bc9d-0x46c52e inside 0x46b930; 0x46e73d; 0x47461e) and their ids
-# belong to the GLUE space: name them from system/glue/scratch/glue-event-name-map.md, never from
-# event-catalog.tsv. 0x46aa34 was the one row where that produced a WRONG name (id 22 read as
-# UNIT_MAXHEALTH; it is FRAMES_LOADED -- glue-event-name-map.md's own control, with GlueParent.lua:94
-# as the independent oracle); it is blanked below. The other 21 were already blank, because those ids
-# are NULL slots in the in-game table. Owed: the glue node names them in its own artifact.
+# The name column resolves every id through the in-game table (0xbe1198, 549 entries). 0x703d90
+# is called twice with different populations, 0x46a88f with (0xb41e70, 26) for the glue phase
+# and 0x48feab with (0xbe1198, 549) for the world, and rebuilds [0xceef68] wholesale from
+# whichever it is handed, so the same integer names a different event in the two phases, and
+# 0x703e50 bounds-checks nothing. 22 rows here sit in a `Source\Glue\` TU (0x46aa34;
+# 0x46bc9d-0x46c52e inside 0x46b930; 0x46e73d; 0x47461e): their ids belong to the glue space and
+# are never named from 1.12-event-catalog.tsv; their names are blank here. 0x46aa34 fires id 22,
+# which is FRAMES_LOADED in the glue table (GlueParent.lua:94), not the in-game UNIT_MAXHEALTH.
 #
-# CAVEAT 2 (2026-09-03, carving UNIT_FLAGS for benilla): AN EVENT WITH NO ROW HERE IS NOT AN EVENT
-# WITH NO PRODUCER. This census is over the two signal helpers' own call/jmp sites, and the whole
-# per-field UNIT_* family reaches them through a WRAPPER: 0x515e50(&guid, id) fans out over the unit
-# tokens and fires 0x703f50(id, "%s", token) at 0x515e7a -- the "?" row below. Its 38 callers carry
-# the id in edx, and one of them, 0x51bd5b in the UpdateField watch callback 0x51bd50, computes it as
-# (registered field byte offset >> 2). So ids 0x00-0xb5 -- every named unit descriptor field,
-# UNIT_FLAGS 40 included -- are produced there and appear nowhere in this file.
-# SCOPE WIDENED 2026-09-07 (PLAYER_FLAGS round, benilla dispatch): "0x00-0xb5" is the COMPUTED-id
-# subset only, and reading it as the whole absent set is a trap -- most 0x515e50 sites carry a
-# LITERAL id in edx, and those are absent from this file too, at any magnitude. The literal set is
-# {0x10 0x16 0x1c 0x1d 0x1e 0x29 0xb7 0xb8 0xb9 0xba 0xbb 0x159 0x197 0x20a}. Notably 0x197 = 407
-# PLAYER_FLAGS_CHANGED (0x5eea35 mov edx,0x197 / 0x5eea3d call 0x515e50, inside the PLAYER_FLAGS
-# delta handler 0x5ee990) sits OUTSIDE 0x00-0xb5, so a reader checking 407 against the range above
-# would wrongly conclude it has no producer. It has one; it is simply not a SignalEvent call site.
-# See system/object-layer/scratch/player-flags-delta-arms.md. Mechanism, the
-# bounded four-way census that makes 0x51bd50 the SOLE producer of 40, and the fire condition
-# (a repe cmpsb of the watched span against the object's shadow, at 0x4655bb) are in
-# system/ui/scratch/unit-field-event-bridge.md. Same shape for 0x5de4b0 (id = its userdata,
-# arg1 hardcoded "player") and 0x49b199 (id from the table at 0x8062e0).
+# An event with no row here is not an event with no producer. This covers the two signal
+# helpers' own call/jmp sites, and the per-field UNIT_* family reaches them through a wrapper:
+# 0x515e50(&guid, id) fans out over the unit tokens and fires 0x703f50(id, "%s", token) at
+# 0x515e7a, the "?" row below. Its 38 callers carry the id in edx; one of them, 0x51bd5b in the
+# UpdateField watch callback 0x51bd50, computes it as (registered field byte offset >> 2), so
+# ids 0x00-0xb5 (every named unit descriptor field, UNIT_FLAGS 40 included) are produced there
+# and appear nowhere in this file. 0x51bd50 is the sole producer of 40; its fire condition is a
+# repe cmpsb of the watched span against the object's shadow, at 0x4655bb. Most other
+# 0x515e50 sites carry a literal id in edx, absent here too at any magnitude: {0x10 0x16 0x1c
+# 0x1d 0x1e 0x29 0xb7 0xb8 0xb9 0xba 0xbb 0x159 0x197 0x20a}. So 0x197 = 407
+# PLAYER_FLAGS_CHANGED (0x5eea35 mov edx,0x197 / 0x5eea3d call 0x515e50, inside the
+# PLAYER_FLAGS delta handler 0x5ee990) lies outside 0x00-0xb5 and still has a producer. Same
+# shape for 0x5de4b0 (id = its userdata, arg1 hardcoded "player") and 0x49b199 (id from the
+# table at 0x8062e0).
 fire_site_va	dispatcher	eventId	name	arg_format
 0x4018df	SignalEvent2	259	TIME_PLAYED_MSG	%d%d
 0x46aa34	SignalEvent	22		

reference/1.12-events.tsv

@@ -1,14 +1,14 @@
-# The 1.12.1 client's FrameScript events and the ARGUMENTS their producers push.
-# GENERATED — scripts/gen-reference-events.py. Source: wow-5875-re's
-# re/events/event-catalog.tsv + event-firesites.tsv. Decision 2140.
+# The 1.12.1 client's FrameScript events and the arguments their producers push.
+# Generated by scripts/gen-reference-events.py from reference/1.12-event-catalog.tsv
+# and reference/1.12-event-firesites.tsv.
 #
 # arg_formats  `|`-separated, one per distinct producer shape. `()` = zero Lua values.
 #              Directives: %s string, %d/%u number, %f number. An event with two
-#              producers of different shapes carries both, and which one a given
-#              transition takes is a question about the transition, not the name.
+#              producers of different shapes carries both; which one fires depends
+#              on the transition, not the name.
 # conf         exact = gate on it. advisory = a contributing site declares more
-#              varargs than it pushes. none = no producer family reaches it HERE,
-#              which is not a claim that it has none; never gate on it.
+#              varargs than it pushes. none = no producer family reaches it here,
+#              which does not mean it has none; never gate on it.
 # producers    signal (0x703e50, no varargs) | signal2 (0x703f50, format-driven) |
 #              unit-field-bridge (0x51bbb0/0x51bd50 -> 0x515e50, always %s) |
 #              token-fanout (0x515e50 with a literal id, also %s).

reference/1.12-globals.tsv

@@ -1,9 +1,9 @@
-# The 1.12.1 client's global namespace. GENERATED — scripts/gen-reference-globals.py.
-# Source: wow-5875-re's W5875Capture fixture (the running client's in-world _G),
-# attributed against the complete 1.12 shipped-UI corpus. Decision 1189.
-# UNION every name that corpus defines but the capture did not contain (type
-# `lod`): the twelve Blizzard_* addons are LoadOnDemand, so a live dump misses
-# them unless the player had opened those windows. Decision 1200.
+# The 1.12.1 client's global namespace. Generated by scripts/gen-reference-globals.py.
+# Source: a capture of the running client's in-world _G (the maintainer's analysis,
+# `WOW_RE`), attributed against the complete 1.12 shipped-UI corpus.
+# Also every name that corpus defines but the capture lacks, as type `lod`: the
+# twelve Blizzard_* addons are LoadOnDemand, so a live dump misses them unless
+# their windows were opened.
 # name	type	origin(lua|engine|framexml)
 ABANDON_PET	string	framexml
 ABANDON_QUEST	string	framexml

reference/1.12-message-catalog.tsv

@@ -1,7 +1,7 @@
 # build 5875 CGGameUI message catalog (the 0xb4b498 table indexed by 0x496720)
 # 465 rows, ids 0x0..0x1d0; consumer bound `cmp id,0x1d1; jge` at 0x49672c
 # kind 0 -> 0x49a870(text, chan); 1 -> UI_INFO_MESSAGE 0xe1; 2 -> UI_ERROR_MESSAGE 0xe0; 3 -> console 0x63cd00
-# regenerate (in wow-5875-re): python3 re/ui/extract-message-catalog.py <WoW.exe> > re/ui/message-catalog.tsv
+# Vendored from the maintainer's analysis (`WOW_RE`); messages/catalog.rs is generated from it.
 id_hex	id_dec	row_va	key	kind	sound	type_tag	chan
 0x0	0	0xb4b498	ERR_INV_FULL	2	NONE	0x0	10
 0x1	1	0xb4b4ac	ERR_BANK_FULL	2	NONE	0x44	10

reference/1.12-shapes.tsv

@@ -1,56 +1,43 @@
-# Lua binding SHAPE table for WoW.exe 1.12.1 build 5875 — one row per registered
-# binding: name -> (argc, return arity, return kinds), with per-column confidence.
-# WHY: a client that gates its Lua globals by NAME accepts a binding with the right
-# name and the wrong return arity, which silently breaks a stock FrameXML file.
-# Evidence + five worked examples: system/ui/scratch/binding-shape-arity-law.md.
+# Lua binding shapes of the 1.12.1 client (WoW.exe build 5875): one row per registered
+# binding, name -> (argc, return arity, return kinds), with per-column confidence.
 #
-# 82 registrar tables, 1722 bindings, 1722 analysed, 0 unresolved registrar sites.
-# Four registration routes, extents read from the REGISTRAR's own literal, never a
-# run scan (see re/audit/registrar-dump.py): 0x704120 RegisterFunction loops;
-# 0x701d80 widget method tables; the INLINED base-library loop at 0x811e28; and the
-# four luaL_openlib 0x6f4dc0 tables (bit/math/table/string).
+# 82 registrar tables, 1722 bindings, 1722 analysed, 0 unresolved registrar sites. Four
+# registration routes, extents read from the registrar's own literal: 0x704120
+# RegisterFunction loops; 0x701d80 widget method tables; the inlined base-library loop at
+# 0x811e28; and the four luaL_openlib 0x6f4dc0 tables (bit/math/table/string).
 #
-# COLUMN CONTRACT — a consumer may rely on exactly this:
-#   arity / arity_conf   SOUND. exact = one constant; set = a `|`-separated set of
-#     possible counts; unknown = `?`. The lattice only widens on merge, so an
-#     imprecise result is a set or `?` and NEVER a wrong single number. Gate on this.
-#   kind `string?`       STRING-OR-NIL, and this distinction has bitten a consumer.
-#     lua_pushstring 0x6f3890 alone begins `test edx,edx ; jne` and TAIL-JUMPS to
-#     lua_pushnil when the char* is NULL, so a push call does not prove a string
-#     reached Lua. `string` is emitted only where the pointer is a constant that
-#     resolves to a readable literal; every other lua_pushstring is `string?`. This
-#     is why an empty/miss path can show a fixed arity with no kind alternation and
-#     still answer nil in that slot (GetMapInfo -> nil,0,0; GetChannelName -> 0,nil,0).
-#   kinds / kinds_conf   ADVISORY unless kinds_conf == agree, which means the
-#     independent lua_push* trace length matches `eax` at every ret AND every ret
-#     was checked. A loop (GetTexCoord: 2 textual pushes, 8 real) -> unverified.
-#     `agree` is a claim about THIS BINDING'S OWN ops. Two things it does not say.
-#     (1) It used to say nothing about an op with a net delta of ZERO that rewrites
-#     a slot in place: lua_gettable 0x6f3a40 and lua_rawget 0x6f3b00 pop the key
-#     off the top and write the looked-up value into that same slot, so the kind
-#     recorded was the KEY's. That is now modelled (REPLACE_TOP -> `any`), and it
-#     was wrong on exactly three rows: getglobal, pairs, ipairs.
-#     (2) It still says nothing about a CALLEE that pushes on its own behalf --
-#     the trace cannot see those, so the returned window may hold slots it never
-#     described. Not corrected; DECLARED, as the note token `delegated-push`.
-#     Evidence for both: system/ui/scratch/binding-kinds-stack-overwrite.md.
-#   argc / argc_conf     NEVER GATE ON THIS. argc is a max over observed constant Lua
-#     stack indices; it has no unknown state and degrades to a silent LOWER BOUND when
-#     a binding delegates argument parsing to a helper. Such rows say lower-bound, but
-#     the detector is one level deep, so treat EVERY argc as a floor.
-#   name       NOT A KEY. 60 names are registered from more than one table and 21 of
-#     those DIFFER IN ARITY between registrations — GetBuildInfo returns 5 on the glue
-#     screen (table 0x8373b8) and 3 in-game (0x83de68); GetAddOnInfo 8 and 7. Key on
-#     `fn`, or on (table_va, name). Every such row carries the note name-not-unique.
-#   notes  stack-leak    = the reference pushes a value and then returns 0 (or fewer).
-#     A faithful client must NOT copy this; these are the disabled lottery/vendor
-#     stubs. variadic = the count comes from lua_gettop, no constant exists.
-#     delegated-push = the binding calls a foreign callee that itself pushes, so
-#     `agree` covers this row's own ops only (see the kinds contract above).
-#     cfg-truncated / indirect-branch / iteration-cap = an edge the walk could not
-#     resolve; such a row's arity is not covered by the soundness claim above.
+# Column contract:
+#   arity / arity_conf   sound. exact = one constant; set = a `|`-separated set of possible
+#     counts; unknown = `?`. An imprecise result is a set or `?`, never a wrong single
+#     number. Gate on this.
+#   kind `string?`       string or nil. lua_pushstring 0x6f3890 begins `test edx,edx ; jne`
+#     and tail-jumps to lua_pushnil when the char* is NULL, so `string` is emitted only where
+#     the pointer is a constant that resolves to a readable literal; every other
+#     lua_pushstring is `string?`. A miss path can show a fixed arity and still answer nil in
+#     that slot (GetMapInfo -> nil,0,0; GetChannelName -> 0,nil,0).
+#   kinds / kinds_conf   advisory unless kinds_conf == agree: the independent lua_push* trace
+#     length matches `eax` at every ret, and every ret was checked. A loop (GetTexCoord: 2
+#     textual pushes, 8 real) -> unverified. `agree` is about the binding's own ops:
+#     lua_gettable 0x6f3a40 and lua_rawget 0x6f3b00 replace the key on top with the looked-up
+#     value (recorded as `any`), and a callee that pushes on the binding's behalf is invisible
+#     to the trace, so the returned window may hold slots it never described (note
+#     `delegated-push`).
+#   argc / argc_conf     never gate on this. argc is a max over observed constant Lua stack
+#     indices, with no unknown state, and a silent lower bound when a binding delegates
+#     argument parsing to a helper. Such rows say lower-bound, but the detector is one level
+#     deep, so treat every argc as a floor.
+#   name       not a key. 60 names are registered from more than one table and 21 of those
+#     differ in arity between registrations: GetBuildInfo returns 5 on the glue screen (table
+#     0x8373b8) and 3 in-game (0x83de68); GetAddOnInfo 8 and 7. Key on `fn`, or on
+#     (table_va, name). Every such row carries the note name-not-unique.
+#   notes  stack-leak = the reference pushes a value and then returns 0 (or fewer): the
+#     disabled lottery/vendor stubs, which a faithful client does not copy. variadic = the
+#     count comes from lua_gettop, no constant exists. delegated-push = a foreign callee
+#     pushes on the binding's behalf, so `agree` covers this row's own ops only.
+#     cfg-truncated / indirect-branch / iteration-cap = an edge the walk could not resolve;
+#     such a row's arity is not covered by the soundness claim above.
 #
-# regenerate (in wow-5875-re): python3 re/audit/binding-shapes.py > re/audit/binding-shapes.tsv
+# Vendored from the maintainer's analysis (`WOW_RE`); no generator for it lives in this repo.
 name	fn	pair_va	table_va	table_kind	argc	argc_conf	arity	arity_conf	kinds	kinds_conf	notes
 AbandonQuest	0x4dfe00	0x84b128	0x84b0f0	global	0	exact	0	exact	()	agree	
 AbandonSkill	0x4d3ab0	0x849d08	0x849cf8	global	1	exact	0	exact	()	agree	

reference/1.12-verb-events.tsv

@@ -1,16 +1,14 @@
-# The 1.12.1 client's FrameScript events fired FROM INSIDE A LUA VERB, keyed by the verb.
-# GENERATED — scripts/gen-reference-verb-events.py. Source: wow-5875-re's
-# re/audit/binding-shapes.tsv + re/events/event-firesites.tsv + re/names/out/names-5875.tsv
-# + system/ui/scratch/disasm-full.txt.
+# The 1.12.1 client's FrameScript events fired from inside a Lua verb, keyed by the verb.
+# Generated by scripts/gen-reference-verb-events.py from reference/1.12-shapes.tsv,
+# reference/1.12-event-firesites.tsv and the maintainer's analysis (`WOW_RE`).
 #
 # shape  body   = a fire site inside the verb's own extent.
-#        helper = a fire site inside a function that ONLY registered verbs call
+#        helper = a fire site inside a function that only registered verbs call
 #                 (at most 8 of them); `via` is that helper. A helper with any
-#                 non-verb caller is a state event's producer and is NOT here.
-# sites  the fire sites themselves, for the grep into wow-re.
-# A floor, not a census: no row is not a claim of no fire (see the generator's header).
-# Sites are attributed against the ledgers' verified function extents; a site past its
-# candidate's extent is left out rather than mis-filed (decision 2257).
+#                 non-verb caller produces a state event and is not here.
+# sites  the fire sites themselves.
+# A floor, not a census: a verb with no row may still fire an event.
+# A site past its candidate function's extent is left out rather than mis-filed.
 # 43 pairs over 41 verbs and 27 events; 2 site(s) past a verified extent.
 verb	event	shape	via	sites
 AddSkillUp	SKILL_LINES_CHANGED	helper	0x4d32d0	0x4d346f