71 lines
4.3 KiB
Markdown
71 lines
4.3 KiB
Markdown
---
|
|
id: LSN-0038
|
|
ticket: scene-bank-glyph-runtime-binding-leak
|
|
title: Cold Scene Dependencies Must Bind by Asset Identity, Not Runtime Residency
|
|
created: 2026-04-24
|
|
tags: [gfx, runtime, asset, scene, glyph, format, architecture]
|
|
---
|
|
|
|
## 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 `AssetId` as 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 -> slot` index 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.
|