Name ADV graphics layer slots

docs/engine-re.md

@@ -445,6 +445,26 @@ at a time, so sharing slot 0 is harmless and the fresh-branch geometry is correc
 with several simultaneous distinct-slot objects would need the setup to run. Tracked as the scene-coroutine
 work, separate from this fix.
 
+#### ADV layer surface-slot registry (`G[0x3239]`, closed 2026-07-23)
+
+The former auto label `rec[s3]` is the eight-row `adv_layer_surface_slots` registry. Each scene's
+setup helper writes the same three banks: column zero `primary_surface_slot` = 4..11, column one
+`alternate_surface_slot` = 43..50, and column two `transition_surface_slot` = 51..58. The shape is
+pervasive rather than SC0000-specific: 309 scripts reference the base, with 2,657 table-base
+accesses; 143 scripts contain the initializer.
+
+The common CG loader proves the column roles. `adv_gfx_layer_index` (`G[0x62450]`, always assigned
+0..7) selects both this row and `adv_gfx_object_handles` (`G[0x62455]`). For a fresh retained object,
+the loader uses the primary slot. For an already-bound object, it compares the live slot returned
+by op `0x215` in `adv_gfx_surface_slot_work` (`G[0x62452]`) and chooses the other member of the
+primary/alternate pair before rebinding. Column two is released and reused by the transition path.
+The resource passed to `set-texture` is the transient `adv_gfx_resource_id` (`G[0x62424]`).
+
+INIT2 seeds the first nine cells of the 20-cell retained-object handle array with `0xcb20`,
+`0xcb2a`, `0xcb8e`..`0xcbc0`, and `0xcf08`. The eight-row layer table governs indices zero through
+seven; the ninth handle is a fixed extra object outside that row-indexed layer set. These names now
+live canonically in `vm-map/globals.toml`.
+
 **⇒ Scene-coroutine framework — INVESTIGATION COMPLETE (2026-07-09).** The mechanism behind the slot-0
 collapse is fully understood; the native finding and the implemented host-model disposition follow:
 

docs/name-resolution.md

@@ -692,7 +692,8 @@ The v1 map labels *shapes and tables*; the next increments add *meaning*, cheape
    247 description strings formerly misread as records), six pre/post-clear text slots, progression and
    story gates, map/minimap geometry, rewards, and 174 resolved entry/clear/failure transitions. With
    RTINIT's used-provider surface closed, ITMES/SKMES/VIMES/EIMES/CIMES/MAMES joined, INFOMES/MES
-   classified, and STINIT2's engine-dead authoring tier retained at medium confidence, continue with
+   classified, STINIT2's engine-dead authoring tier retained at medium confidence, and the
+   309-script ADV primary/alternate/transition surface-slot registry named, continue with
    consumer-led tables that still have shipped readers;
    never assign one universal meaning to a parameter bank whose meaning varies by provider selector.
 2. **Label remaining 2D record tables by their readers** — cross-reference which scripts read each

docs/phase-a-slice-plan.md

@@ -3222,3 +3222,24 @@ only through script operands, the array is now named `stage_authoring_difficulty
 confidence and explicitly classified as engine-dead authoring metadata.
 
 **Next:** continue consumer-led naming of the remaining two-dimensional tables; STINIT2 is closed.
+
+## Data-semantics sidebar: ADV layer surface-slot registry (2026-07-23)
+
+The highest-use unnamed row table, `G[0x3239]`, is now closed as
+`adv_layer_surface_slots`. Its eight rows contain three graphics surface banks:
+`primary_surface_slot` 4..11, `alternate_surface_slot` 43..50, and
+`transition_surface_slot` 51..58. The corpus contains 2,657 table-base accesses across 309 scripts,
+and 143 scene scripts repeat the same initializer.
+
+The shared CG loader proves the ABI. `adv_gfx_layer_index` selects a row and the corresponding
+`adv_gfx_object_handles` cell. A fresh object loads into the primary slot; an already-bound layer
+swaps between the primary and alternate slots; the third slot stages and cleans up transitions.
+`adv_gfx_surface_slot_work` carries the op-`0x215` query result or fallback slot, while
+`adv_gfx_resource_id` carries the transient SYS4INI resource id into `set-texture`. INIT2 seeds the
+first nine cells of the 20-cell retained-object handle array; the first eight participate in the
+row registry.
+
+Registry tests protect all 24 initialized slot cells, use of all three columns in SC0000, the nine
+INIT2 handle constants, and the canonical global/column names.
+
+**Next:** rank the next unnamed row table by shipped-reader evidence.

docs/vm-mapping-plan.md

@@ -69,8 +69,9 @@
 - [x] **2.3l — Extract `CDINIT2`'s card definitions.** Name specialization classifies all 558 instructions into 81 cards inside a reserved 100-row registry. FIELD proves six type-specific effect paths and the engine-dead third required-flag column; ITINIT, SCINIT, ILINIT, and SYS4INI resolve all item, event, condition, and visual references, while STAGECLEAR proves the deferred point-award accumulator.
 - [x] **2.3m — Extract `BTANINIT`/`BTANINIT2`'s battle-animation registry.** BTANINIT2 specialization classifies all 1,018 instructions into 122 sparse six-effect timelines, 573 effect references, paired start delays, and 111 complete durations. BTANINIT dispatch specialization classifies all 4,472 instructions into 202 visual/audio/hit-pulse definitions. BTL proves movie/sprite playback, blend, anchor, geometry, sound, and pulse semantics; SKINIT/ITINIT resolve skill and weapon-class selection.
 - [x] **2.3n — Extract `STINIT2`'s stage-definition registry.** Name/string-matrix specialization corrects the generic 321-record view to 74 sparse stages plus 296 strings in six pre/post-clear description slots, classifying all 1,634 instructions. FORT, FIELD, SELSTAGE, and STAGECLEAR prove main/EX flags, seven-column story gates, unlock groups, numbered/event presentation, map/minimap geometry, base point and three-coin rewards, and the loader contract. All 174 entry/clear/failure decisions resolve through SCINIT and all 74 loader ids resolve to STINIT. The remaining `0xedc4d` array has no shipped reader and is retained at medium confidence as the authoring-only stage difficulty tier: values 1..8 correlate with challenge/reward progression but have no runtime effect.
+- [x] **2.3o — Name the ADV layer surface-slot registry.** `G[0x3239]` is an eight-by-three primary/alternate/transition surface bank initialized by 143 scripts and read across 309. The common CG loader proves double-buffer selection and transition staging; INIT2 supplies the paired retained-object handles, and the companion resource, layer-index, live-slot, and handle globals are curated.
 - [x] **2.4 — Partial global-var map BUILT + wired into the disassembler.** `tools/global_map.py` → `build/global-var-map.{json,md}` (16,354/49,435 globals labelled: string tables, `*INIT` field arrays, 122 record tables w/ strides, current-entity index pointers). `sys4load` renders the labels inline (`=rec[s30]`, `=current-entity-index?`). See `docs/name-resolution.md`.
-- [ ] **2.5 — Grow the global-var map (future, incremental).** Static first: RTINIT is closed at 1,043/1,043 movement steps; the RECOVER/ILINIT condition ABI, ALINIT recipes, AFINIT affinity/progression tables, CTINIT name palette, CVINIT character-voice registry, LAINIT terrain definitions, MPINIT stage-terrain atlas, SPINIT H-scene gallery, TRINIT training actions, CDINIT/CDINIT2 card selection/effects, BTANINIT/BTANINIT2 battle animations, and STINIT2's complete stage surface are closed; ITMES/SKMES/VIMES/EIMES/CIMES/MAMES are joined to their definitions; and the non-table INFOMES/MES ABIs are classified. Next, continue remaining consumer-led 2D table naming. Full detail: `docs/name-resolution.md` → "Future step — growing the map". Packed `call-script` ids, SCJUMP decision-to-scene dispatch, the shipped RTINIT movement-provider join, and the six completed message joins are resolved.
+- [ ] **2.5 — Grow the global-var map (future, incremental).** Static first: RTINIT is closed at 1,043/1,043 movement steps; the RECOVER/ILINIT condition ABI, ALINIT recipes, AFINIT affinity/progression tables, CTINIT name palette, CVINIT character-voice registry, LAINIT terrain definitions, MPINIT stage-terrain atlas, SPINIT H-scene gallery, TRINIT training actions, CDINIT/CDINIT2 card selection/effects, BTANINIT/BTANINIT2 battle animations, STINIT2's complete stage surface, and the 309-script ADV layer surface-slot registry are closed; ITMES/SKMES/VIMES/EIMES/CIMES/MAMES are joined to their definitions; and the non-table INFOMES/MES ABIs are classified. Next, continue remaining consumer-led 2D table naming. Full detail: `docs/name-resolution.md` → "Future step — growing the map". Packed `call-script` ids, SCJUMP decision-to-scene dispatch, the shipped RTINIT movement-provider join, and the six completed message joins are resolved.
 
 ## Phase 3 — Name the unnamed opcodes *(top ~20 BEFORE Phase 4; the rest on demand)*
 

tools/test_globals.py

@@ -4,6 +4,7 @@ import os, sys
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import paths
 import globals_build as G
+import sys4load
 
 FAILS = []
 def check(cond, msg):
@@ -128,6 +129,15 @@ def test_load_and_lint():
           and entries[0xedc4d]["name"]
           == "stage_authoring_difficulty_tiers",
           "STINIT2 numbering, minimap, points, and authoring tiers are curated")
+    check(entries[0x3239]["columns"] == {
+        "0": "primary_surface_slot",
+        "1": "alternate_surface_slot",
+        "2": "transition_surface_slot",
+    } and entries[0x62424]["name"] == "adv_gfx_resource_id"
+      and entries[0x62450]["name"] == "adv_gfx_layer_index"
+      and entries[0x62452]["name"] == "adv_gfx_surface_slot_work"
+      and entries[0x62455]["name"] == "adv_gfx_object_handles",
+      "ADV graphics layer slots and companion work globals are curated")
     check(entries[0xee035]["columns"]
           == {"0": "entry", "1": "clear", "2": "failure"}
           and entries[0xeebed]["name"] == "stage_extra_dungeon_flags"
@@ -167,6 +177,56 @@ def test_lint_catches_bad_vocab():
     check(any("column index" in e for e in errors), "lint flags nonnumeric column indices")
     check(any("negative column" in e for e in errors), "lint flags negative column indices")
 
+def test_adv_layer_surface_slot_evidence():
+    scene = sys4load.load(paths.scripts()["SC0000.BIN"])
+    expected = {
+        0x3239 + row * 3 + column: value + row
+        for row in range(8)
+        for column, value in enumerate((4, 43, 51))
+    }
+    initialized = {
+        instruction.args[0][1]: instruction.args[1][1]
+        for instruction in scene.instructions
+        if 0x125bd <= instruction.offset <= 0x12630
+        and len(instruction.args) == 2
+        and instruction.args[0][0] == 3
+        and instruction.args[0][1] in expected
+        and instruction.args[1][0] == 0
+    }
+    check(initialized == expected,
+          "SC0000 initializes all eight ADV layer surface-slot triplets")
+
+    table_lookups = [
+        instruction.args
+        for instruction in scene.instructions
+        if (3, 0x3239) in instruction.args
+        and (0, 3) in instruction.args
+    ]
+    static_columns = {
+        args[-1][1]
+        for args in table_lookups
+        if args[-1][0] == 0
+    }
+    check(static_columns == {0, 1, 2},
+          "SC0000's common graphics paths read all three surface-slot columns")
+
+    init2 = sys4load.load(paths.scripts()["INIT2.BIN"])
+    handle_writes = {
+        instruction.args[0][1]: instruction.args[1][1]
+        for instruction in init2.instructions
+        if len(instruction.args) == 2
+        and instruction.args[0][0] == 3
+        and 0x62455 <= instruction.args[0][1] <= 0x6245d
+        and instruction.args[1][0] == 0
+    }
+    expected_handles = [
+        0xcb20, 0xcb2a, 0xcb8e, 0xcb98, 0xcba2,
+        0xcbac, 0xcbb6, 0xcbc0, 0xcf08,
+    ]
+    check([handle_writes.get(0x62455 + index) for index in range(9)]
+          == expected_handles,
+          "INIT2 seeds the nine ADV retained-object handles")
+
 def test_merge_precedence():
     curated, _ = G.load_toml(paths.VM_MAP / "globals.toml")
     auto = G.load_auto(paths.BUILD / "global-var-map.json")
@@ -229,6 +289,7 @@ def test_bootstrap_is_additive_and_idempotent():
 if __name__ == "__main__":
     test_load_and_lint()
     test_lint_catches_bad_vocab()
+    test_adv_layer_surface_slot_evidence()
     test_merge_precedence()
     test_sys4load_labels_from_registry()
     test_miner_finds_known_flags()

vm-map/globals.toml

@@ -1175,6 +1175,62 @@ source = "investigation"
 confidence = "high"
 depends_on = ["0x6c1"]
 
+[[global]]
+address = "0x3239"
+name = "adv_layer_surface_slots"
+category = "data-table"
+type = "int[8][3]"
+columns = { "0" = "primary_surface_slot", "1" = "alternate_surface_slot", "2" = "transition_surface_slot" }
+value_domain = "eight rows initialized to primary slots 4..11, alternate slots 43..50, and transition slots 51..58"
+usage = "Shared ADV graphics-layer surface-slot registry. Scene setup initializes the three banks. The CG loader uses the primary slot for a fresh retained object, alternates between columns zero and one when replacing an already-bound layer, and uses column two for the transition/crossfade surface and cleanup. The corpus has 2,657 table-base accesses across 309 scripts."
+source = "investigation"
+confidence = "high"
+depends_on = ["0x62450", "0x62452", "0x62455"]
+
+[[global]]
+address = "0x62424"
+name = "adv_gfx_resource_id"
+category = "index-pointer"
+type = "int"
+value_domain = "SYS4INI file/resource id"
+usage = "Transient ADV graphics-load input. Scene scripts set this immediately before their common layer loader, which passes it to set-texture together with adv_gfx_surface_slot_work."
+source = "investigation"
+confidence = "high"
+depends_on = ["0x62452"]
+
+[[global]]
+address = "0x62450"
+name = "adv_gfx_layer_index"
+category = "index-pointer"
+type = "int"
+value_domain = "0..7"
+usage = "Current ADV graphics-layer row. All immediate assignments across the corpus are 0..7; common scene loaders use it to index adv_gfx_object_handles, per-layer geometry arrays, and adv_layer_surface_slots."
+source = "investigation"
+confidence = "high"
+depends_on = ["0x3239", "0x62455"]
+
+[[global]]
+address = "0x62452"
+name = "adv_gfx_surface_slot_work"
+category = "index-pointer"
+type = "int"
+value_domain = "-1 for no retained-object binding, otherwise a graphics surface slot"
+usage = "Working surface slot for the current ADV layer. Opcode 0x215 writes the retained object's existing source slot or -1; the common loader falls back to adv_layer_surface_slots, then passes the selected slot through set-texture, size queries, draw binding, and release."
+source = "investigation"
+confidence = "high"
+depends_on = ["0x3239", "0x62455"]
+
+[[global]]
+address = "0x62455"
+name = "adv_gfx_object_handles"
+category = "data-table"
+type = "int[20]"
+value_domain = "retained graphics-object handles; INIT2 populates the first nine cells"
+usage = "ADV retained-object handles indexed by adv_gfx_layer_index. INIT2 seeds handles 0xcb20, 0xcb2a, and 0xcb8e..0xcbc0 for the first nine cells; scene loaders query, bind, animate, and erase those objects while the eight-row surface-slot registry governs layers zero through seven."
+source = "investigation"
+confidence = "high"
+depends_on = ["0x62450", "0x62452"]
+
 [[global]]
 address = "0x2e49"
 name = "character_voice_suppressed"