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
- 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
Verified first live `PresentationCallbackBroker` batch landed on 2026-04-08.
- Created class owner `Remorse::PresentationCallbackBroker` in the active `CRUSADER.EXE` database.
- Re-anchored the global install/teardown pair into live `12d0:` helpers by direct access to the `0x4588/0x458c/0x4590/0x4594/0x4595/0x45a6` broker globals:
-`12d0:0513` -> `InitOnce`
-`12d0:0656` -> `TeardownOnce`
- Added short decompiler comments to both methods so the current `0x4588` lifecycle remains visible in-session:
-`InitOnce` now records the `0x4594` guard, state snapshot into `0x458c/0x4590`, broker install at `0x4588`, and fallback-buffer allocation at `0x45a6`.
-`TeardownOnce` now records the `0x4595` guard, broker clear, conditional slot `+0x0c` emit when `0x4590 != 0x458c`, slot `+0x04` release, and final cleanup path.
- Re-anchored the finalize-phase caller as well: `1288:0fc3` is now `allocator_phase_finalize_pass` in the live database with a comment recording that it exercises broker slot `+0x08` twice before sweeping allocator heads.
- Preserved two verified live slot `+0x0c` callers with decompiler comments instead of forcing premature renames:
-`1278:0616 Vport_1278_0616` uses the installed broker callback when the local vport path takes its fallback branch with `param_2 == 0`.
-`1320:1588 Dispatch_ModalGump` emits the broker callback before and after modal dispatch when the requested state pair differs from the current mode snapshot.
- This remains intentionally conservative live authoring:
- no forced `this` typing yet for the broker pointer parameter on `InitOnce`
- no live promotion yet of `allocator_phase_finalize_pass` under the class owner itself, because it is a broker caller rather than a broker method
- no attempt yet to rename the wider subsystem beyond the existing `PresentationCallbackBroker` placeholder
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.
