deepened understanding

docs/presentation-callback-broker-layout.md

@@ -0,0 +1,207 @@
+# Presentation Callback Broker Layout
+
+## Purpose
+
+This note isolates the current class-lift-relevant evidence for the callback/broker object rooted at `0x4588`.
+
+The subsystem name is still intentionally conservative. The goal here is to freeze the object model, lifecycle, and vtable-slot surface that are already well evidenced, so later Ghidra class work does not have to rediscover them.
+
+Current working family name:
+
+- `PresentationCallbackBroker`
+
+That name is still provisional, but it fits the current evidence better than a generic allocator or generic render-object label.
+
+## Why This Looks Like A Real Object Family
+
+Current evidence does not support treating `0x4588` as a stray callback function pointer.
+
+What is already stable:
+
+- one installed nullable FAR object pointer at `0x4588`
+- explicit once-only install and teardown helpers
+- live vtable slots `+0x04`, `+0x08`, and `+0x0c`
+- state snapshot globals at `0x458c` and `0x4590`
+- once guards at `0x4594` and `0x4595`
+- a fallback/auxiliary buffer pointer at `0x45a6`
+
+That is strong enough to treat this as a typed broker/helper object with global lifetime rather than as a raw callback cell.
+
+## Core Lifecycle
+
+### Install
+
+Strong anchors:
+
+- `000a:4913 runtime_callback_object_init_once`
+- `000a:4a1f video_bios_state_snapshot`
+
+Current verified behavior from the raw notes:
+
+- checks one-time guard `0x4594`
+- snapshots state through `video_bios_state_snapshot`
+- stores previous/current state words in `0x458c` and `0x4590`
+- installs the incoming FAR object pointer at `0x4588`
+- ensures fallback buffer allocation at `0x45a6`
+
+Current safest role:
+
+- object installation is tied to video or presentation state capture, not to generic allocation alone
+
+### Teardown
+
+Strong anchor:
+
+- `000a:4a56 runtime_callback_object_teardown_once`
+
+Current verified behavior:
+
+- checks once-only teardown guard `0x4595`
+- clears `0x4588` when an object is present
+- emits vtable `+0x0c` callback only when `0x4590 != 0x458c`
+- then calls vtable slot `+0x04`
+- follows with cleanup through `FUN_0009_0d30()`
+
+Current safest role:
+
+- the broker is not only a notifier; it also owns a release/finalize path and a final conditional dispatch when presentation state changed
+
+### Finalize sweep phase
+
+Strong anchor:
+
+- `0009:b1c3 allocator_phase_finalize_pass`
+
+Verified behavior:
+
+- accepts finalize phase `0` or `1`
+- forwards that phase twice through broker vtable slot `+0x08`
+- then sweeps allocator heads through `allocator_head_finalize_sweep`
+
+Current safest role:
+
+- slot `+0x08` looks like a finalize or phase-advance callback surface shared with allocator/presentation cleanup, not a normal per-entity method
+
+## Vtable Surface
+
+### Slot `+0x04`
+
+Evidence:
+
+- teardown path calls it as the broker release path
+
+Current working meaning:
+
+- `release` or `shutdown`
+
+### Slot `+0x08`
+
+Evidence:
+
+- `allocator_phase_finalize_pass` forwards phase `0` or `1` twice through this slot
+
+Current working meaning:
+
+- `phase_finalize` or `advance_finalize_phase`
+
+### Slot `+0x0c`
+
+Evidence:
+
+- teardown emits it conditionally when recorded state changed
+- `entity_cleanup_resources_and_dispatch` uses it at `000d:9d5e` and `000d:a3b7`
+- raw notes also document callers `000a:b9e5` and `000a:ba66`
+- one caller uses literal mode-like pair `0x0101`
+
+Current working meaning:
+
+- `emit_state_pair` or `dispatch_state_change`
+
+Current caution:
+
+- payload semantics are still not closed well enough to call this a specific display-mode or palette-event method with confidence
+
+## Global State Cluster
+
+| Address | Current role |
+|---------|--------------|
+| `0x4588` | nullable FAR broker object pointer |
+| `0x458c` | recorded state word A |
+| `0x4590` | recorded state word B |
+| `0x4594` | install-once guard |
+| `0x4595` | teardown-once guard |
+| `0x45a6` | fallback or auxiliary FAR buffer |
+
+Current safest class-lift read:
+
+- this global cluster behaves like one installed process-wide broker instance plus its remembered state and support buffer
+
+## Caller-Side Payload Evidence
+
+The payload side is important even though exact semantics are still open.
+
+Verified pairs already documented:
+
+- `entity_cleanup_resources_and_dispatch` call at `000d:9d5e` uses object fields `+0x12d/+0x12f`
+- matching call at `000d:a3b7` uses object fields `+0x74f/+0x751`
+- one live caller uses literal `0x0101`
+
+What this supports now:
+
+- slot `+0x0c` is consuming compact two-word state/payload pairs
+- those pairs are presentation-adjacent enough to align with the earlier video-state snapshot evidence
+
+What it does not yet support:
+
+- one final semantic label for those two words across every callsite
+
+## Relationship To Other Families
+
+### Presentation and startup/display lane
+
+The broker note belongs next to the startup/display and runtime-state family notes because its callers overlap with that cleanup/palette/presentation lane.
+
+Strong surrounding anchors:
+
+- `entity_cleanup_resources_and_dispatch`
+- palette/state handoff work in `FUN_000d_938c`
+- active dispatch-entry hold token at `g_active_dispatch_entry_farptr[+0x40]`
+
+Current safest read:
+
+- the broker is presentation-side infrastructure shared by cleanup/finalize paths, not a child class of `EntityDispatchEntry`
+
+### Allocator lane
+
+The allocator interacts with this broker through finalize phases, but current evidence still reads as `allocator client callback` rather than `allocator-owned object`.
+
+That means:
+
+- keep allocator classes and this broker separate in future class modeling
+
+## Class-Lift Guidance
+
+If promoted in Ghidra later, safest current move is:
+
+1. create a conservative owner like `PresentationCallbackBroker`
+2. model the global state cluster as supporting globals, not as instance fields until constructor ownership is tighter
+3. create a provisional vtable with slots `+0x04`, `+0x08`, and `+0x0c`
+4. leave slot names conservative and role-based
+5. do not promote this family as the first MCP/class-lift pilot
+
+Why not first:
+
+- lifecycle is strong, but subsystem semantics are still weaker than `EntityDispatchEntry`, `SpriteNode`, or `EntityVmOwnerResource`
+
+## Best Next Evidence To Collect Later
+
+1. close more callers of vtable slot `+0x0c`
+2. classify the exact payload meaning of the two-word pairs
+3. decide whether `0x45a6` is an owned buffer, fallback object, or adapter scratch lane
+4. tighten the constructor/installation provenance in the live NE program, not only the raw notes
+
+## Bottom Line
+
+The `0x4588` family is now documented well enough to be treated as a real object candidate.
+
+The safest current model is: one global presentation-state callback broker with a small live vtable surface, explicit install/teardown, conditional state-pair emission, and allocator-linked finalize phases.