SamandClaude Fable 5.1
3e12fa1d7f
Until now this repo was an export of a private tree, pushed as squashed snapshots. From here on it is the working tree itself, and the private repo is archived. The root holds AGENTS.md and the Rust and GitHub files only. Everything an agent needs to orient is in docs/: METHOD.md (the rules and how the project is built, 123 lines, project method only), MAP.md (generated from the code at every land) and CONTRIBUTING.md (what gets in and how a change is judged). One skill, `probe`, holds the procedure for running the client unattended against the local server. Brought over because the project needs it: reference/ (the 1.12 name catalogues 34 source files read; the export failed its own tests without them), the gate chain and the pool (scripts/), the hooks that enforce the install rule and the worktree rule, the full .gitignore, the `cargo play` alias, and the original wording of eleven source files the export had reworded. Left out: the decision records (archived with the private repo), the export tooling, the operator's Discord and triage loop, the lab-laptop scripts and the instruments nothing references, which live outside the repo now. What read the records is gone from the tooling: no corpus lint, no records index, no `reserve` verb, no number-collision check. Three hooks are gone: fmt-at-commit and the file-size nudge were redundant with the gates, and the assets/ui guard is now a test (`assets_ui_does_not_grow`) that fails for everyone, not only for a Claude Code session. The remaining pool hooks stand down on a machine without a pool. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
88 lines
5.6 KiB
Markdown
88 lines
5.6 KiB
Markdown
# `reference/` — verified facts about the 1.12.1 client, vendored
|
|
|
|
Generated artifacts describing **the reference client**, committed so benilla can measure itself
|
|
against them on any day without a re-derivation. Not documentation, not state: data, with a
|
|
generator beside it in `scripts/`.
|
|
|
|
Nothing here is Blizzard content. A catalogue of *names* is not the thing named — the same reason
|
|
`decisions/` may quote a byte address and `MAP.md` may name a file.
|
|
|
|
## `1.12-globals.tsv`
|
|
|
|
The 1.12.1 client's entire global namespace — 21,555 names, `name<TAB>type<TAB>origin`.
|
|
|
|
**Where it comes from.** wow-5875-re ships an addon (`W5875Capture`) that dumps the in-world `_G`
|
|
of the *running* reference client, and its output is committed there as a fixture. This is the
|
|
authoritative answer to "what can an addon see in 1.12", and it is strictly better evidence than
|
|
the binary's registration table would be: it is the actual runtime table, so it carries
|
|
FrameXML-defined globals as well as engine ones — which is exactly the surface an addon sees, and
|
|
therefore exactly the surface an addon-compatibility target needs (decision 1189).
|
|
|
|
**Plus what a capture structurally cannot see** (decision 1200). The twelve `Blizzard_*` addons are
|
|
**LoadOnDemand**: unless the player had opened the talent window, the trainer, the auction house and
|
|
the rest before the dump, none of their globals is in it — so the capture alone reported
|
|
`TalentFrame`, `MacroFrame`, `TradeSkillFrame`, `CraftFrame`, `TrainerFrame` and `InspectFrame` as
|
|
absent from 1.12 while listing their `*_LoadUI` stubs. The table is therefore the capture **union**
|
|
every global the shipped-UI corpus *defines*, and those 1,986 extra rows carry type **`lod`** so
|
|
the two halves stay distinguishable. The question this artifact answers is "is this a 1.12 name?",
|
|
not "was this name live at one moment in one session".
|
|
|
|
**The `origin` column** answers a second question the capture alone cannot — *whose job is it to
|
|
provide this?* — by attributing every name to its definition site in a complete 1.12 shipped-UI
|
|
corpus:
|
|
|
|
| origin | count | meaning |
|
|
|---|---|---|
|
|
| `engine` | 1,104 | the C client provides it. **benilla implements these in Rust.** |
|
|
| `framexml` | 20,427 | the shipped UI defines it. **benilla transcribes these into `assets/ui/`.** |
|
|
| `lua` | 24 | Lua 5.0's own runtime. mlua gives us these. |
|
|
|
|
Of the `framexml` rows, **1,986 carry type `lod`**: defined by the shipped UI but absent from the
|
|
capture, which is what a LoadOnDemand addon looks like from a live dump (decision 1200).
|
|
|
|
The `framexml` bulk is UI objects — `ContainerFrame1Item16IconTexture` and its 11,000 siblings —
|
|
which materialize from whatever XML we ship and are nobody's to implement. The number that
|
|
matters for the API surface is the function split: **1,100 engine functions, 1,075 FrameXML
|
|
functions.** This is the `tContains` distinction (1187 got it right for one name) applied
|
|
wholesale: a name defined in shipped Lua is FrameXML's, and hardcoding it in Rust is a category
|
|
error even when it works.
|
|
|
|
**Regenerating** — `scripts/gen-reference-globals.py`, whose header carries the full method and
|
|
the traps. It needs the director's 1.12 install and the sibling RE repo, so it is a manual
|
|
regeneration like `genmap.sh`, not something CI can run. The artifact is stable: it describes a
|
|
client that shipped in 2006.
|
|
|
|
**Reading it** — `scripts/api-coverage.sh` is the instrument. It asks a real `UiScript::new()`
|
|
what benilla exposes and reports `have / missing / beyond-1.12`, always with 1178's split.
|
|
`crates/benilla-ui/src/script/tests/reference_surface.rs` is the gate: it fails if benilla grows a
|
|
global that 1.12 does not have and nobody wrote down why.
|
|
|
|
## `1.12-shapes.tsv` and `1.12-events.tsv`
|
|
|
|
wow-5875-re's binding-shape table (what each Lua verb takes and returns; decision 1842, gated by
|
|
`ui_script/shape_gate.rs`) and the event table with the arguments each producer pushes
|
|
(decision 2140, `scripts/gen-reference-events.py`, gated by `ui_script/event_shape_gate.rs`).
|
|
Each file's header carries its column contract.
|
|
|
|
## `1.12-verb-events.tsv`
|
|
|
|
Every event the reference fires **from inside a Lua verb**, keyed by the verb — the verb's own
|
|
body, or a helper that only registered verbs call (`0x4d8c90` is the trainer's). The third
|
|
question on the event seam: the two tables above say what an event carries and whether something
|
|
fires it; this one says *who*. A stock file that calls a verb for its side effect of an event
|
|
repaints nothing when the verb fires nothing, which is how the trainer filter regressed twelve
|
|
days after its window went stock (decision 2244), and the class every migrated window shares.
|
|
|
|
**Regenerating** — `scripts/gen-reference-verb-events.py`, whose header carries the rule, the
|
|
two families it drops (glue-space verbs, the unit-field bridge) and why getters are excluded (a
|
|
getter's fire is a cache-miss re-query, a state event benilla's feeds fire off the packet). A fire
|
|
site is attributed to a function against wow-re's verified extents (the ledgers' `size=`) plus the
|
|
disassembly's padding boundaries, and a site past its candidate's extent is left out rather than
|
|
mis-filed (decision 2257: four of the first table's rows were callbacks reached by pointer, or a
|
|
site past an extent). It reads the sibling RE repo's disassembly, so it is manual, like the others.
|
|
|
|
**Reading it** — `crates/benilla-app/src/ui_script/verb_event_gate.rs` is the gate: for every
|
|
pair whose verb benilla registers, the module that registers the verb fires the event, or the
|
|
pair is declared there — `ELSEWHERE` (a feed fires it on the state the verb changes, and the
|
|
named file is checked to) or `GAP` (nothing does, with the reason). Decision 2251.
|