---
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.