4.3 KiB
| id | ticket | title | created | tags | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0038 | scene-bank-glyph-runtime-binding-leak | Cold Scene Dependencies Must Bind by Asset Identity, Not Runtime Residency | 2026-04-24 |
|
Context
SCENE payloads had started to serialize a per-layer glyph_bank_id, and the runtime was consuming that byte as if it were the authoritative glyph residency binding. That meant a cold scene asset was no longer just describing its dependencies; it was leaking the runtime slot topology that happened to exist when the asset was authored.
The implementation work for DSC-0029 replaced that contract end to end. Scene layers now carry glyph dependencies by canonical AssetId (i32), the runtime owns the reverse residency lookup, and scene activation/composition fail fatally when required glyph assets are not currently resident.
Key Decisions
Scene Assets Must Describe Dependencies, Not Slot Topology
What:
Each SceneLayer now declares its glyph dependency by canonical AssetId, and the SCENE wire format serializes that dependency as i32.
Why: Runtime slot ids are operational state. They can change with preload order, slot reuse, and runtime relocation. Putting them on the wire couples a cold asset to an unstable residency layout and breaks the intended separation between authored content and runtime execution state.
Trade-offs: The payload widened and old payload compatibility was intentionally dropped. That makes the migration more abrupt, but it restores the correct contract boundary instead of preserving an invalid one.
Runtime Residency Must Be Resolved Through Runtime-Owned Indexes
What:
The runtime now owns the authoritative asset_id -> slot reverse index for committed glyph assets, and scene bind/draw paths consult that index instead of trusting scene bytes as slot bindings.
Why: Residency is a runtime concern. A reverse index gives the renderer and scene binder the correct primitive while keeping slot ownership inside the asset system where preload, commit, overwrite, and invalidation already live.
Trade-offs: The asset manager has more bookkeeping responsibility, but the model becomes coherent and future public lookup APIs can emerge from the same primitive.
Missing Scene Dependencies Are Fatal, Not Passive Status Errors
What:
If bind_scene cannot resolve a declared glyph dependency, or if composition later loses a required dependency, the machine fails fatally with explicit logging.
Why: A bound scene without its declared glyph dependencies is not operationally meaningful. Treating that condition as a soft status error would let the system continue from a broken render contract.
Trade-offs: This is stricter than a passive operational rejection. The runtime becomes less forgiving, but it also becomes more honest: malformed residency state cannot masquerade as a valid scene activation path.
Patterns and Algorithms
- Keep authored asset formats in cold identity space and runtime systems in residency space.
- Use
AssetIdas the handoff boundary between content and runtime resolution. - Maintain reverse residency indexes inside the asset manager whenever runtime services need dependency lookup by identity.
- Re-resolve runtime bindings in the active path when residency can change after activation.
- Prefer fatal failure over passive degradation when a declared scene dependency is mandatory for correct composition.
Pitfalls
- A one-byte field can look harmless while still encoding the wrong domain concept; width is less dangerous than semantics.
- Migrating the wire format without updating tooling and generated fixtures leaves the runtime correct but the stress assets incoherent.
- Freezing slot bindings too early would turn runtime residency changes into stale scene state.
- Introducing a reverse lookup only as an optimization shortcut invites future API and ownership problems; it should be modeled as a first-class runtime primitive.
Takeaways
- Cold scene payloads should carry dependency identity, never runtime residency topology.
- Runtime slot lookup belongs to the asset manager, not to authored scene data.
- A reverse
asset_id -> slotindex is the clean bridge between authored dependencies and runtime composition. - Missing scene dependencies should fail loudly because the render contract is broken, not merely unavailable.