prometeu-runtime/discussion/workflow/plans/PLN-0041-scene-glyph-runtime-resolution-and-fatal-paths.md

id	ticket	title	status	created	completed	tags
PLN-0041	scene-bank-glyph-runtime-binding-leak	Scene glyph runtime resolution, reverse index, and fatal paths	review	2026-04-24		gfx runtime asset scene glyph render

Briefing

Implement the runtime half of DEC-0021: remove canonical runtime glyph slot ids from scene types, widen scene dependency serialization to AssetId (i32), introduce and maintain the internal reverse glyph residency index, and enforce fatal machine behavior when scene dependencies are missing at bind time or draw time.

Decisions de Origem

• DEC-0021 — Scene Bank glyph dependencies MUST bind by asset_id, not runtime slot.

Alvo

• crates/console/prometeu-hal/
• crates/console/prometeu-drivers/
• crates/console/prometeu-system/ only if runtime-visible behavior or tests require updates.

Escopo

• Replace scene-layer glyph slot semantics with AssetId semantics in HAL/runtime types.
• Widen SCENE decode/encode logic to serialize AssetId (i32) per layer.
• Maintain an internal reverse index AssetId -> glyph slot for committed glyph assets.
• Enforce fatal handling with explicit logging when dependencies are missing during bind_scene or draw/composition.

Fora de Escopo

• Public guest ABI for reverse lookup.
• Compatibility with old glyph_bank_id scene payloads.
• Tooling/stress-fixture migration beyond the runtime code needed to compile.

Plano de Execucao

Step 1 - Change canonical scene types to cold dependency identity

What: Remove canonical runtime glyph slot ids from scene-layer related types and replace them with glyph dependency AssetId.

How: Refactor SceneLayer, scene cache entries, viewport cache state, resolver helpers, and tests so the scene model stores dependency identity rather than slot identity. Preserve only the information needed for cold scene description plus runtime materialization.

File(s):

• crates/console/prometeu-hal/src/scene_layer.rs
• crates/console/prometeu-hal/src/scene_viewport_cache.rs
• crates/console/prometeu-hal/src/scene_viewport_resolver.rs
• scene-related tests under prometeu-hal.

Step 2 - Update SCENE decode/encode path to AssetId (i32)

What: Rewrite the binary SCENE decoder and local encoders to read/write AssetId instead of single-byte glyph slot ids.

How: Adjust header width constants, field offsets, and validation in AssetManager::decode_scene_bank_* and any local test encoders. Ensure decode rejects malformed payloads under the new layout and that any helper fixture builder writes i32 dependencies per layer.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• any scene payload helpers under tests.

Step 3 - Introduce reverse glyph residency index

What: Add a runtime-owned reverse mapping from committed glyph AssetId to glyph slot.

How: Extend AssetManager so glyph preload, glyph commit, shutdown, and any slot replacement paths update both:

• the existing slot -> asset_id tracking;
• the new reverse asset_id -> slot index.

Keep this mechanism internal in this stage. Remove stale entries when a slot is overwritten or cleared.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• crates/console/prometeu-hal/src/asset_bridge.rs only if an internal-facing trait hook is required.

Step 4 - Enforce fatal dependency validation in bind_scene

What: Make scene activation fail fatally when any scene glyph dependency does not resolve to a committed glyph slot.

How: Update the FrameComposer bind path and any caller path so bind checks every layer dependency against the reverse index before activating the scene. Emit a clear fatal log naming the scene context, layer index, and missing dependency AssetId.

File(s):

• crates/console/prometeu-drivers/src/frame_composer.rs
• crates/console/prometeu-drivers/src/hardware.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs if behavior shaping is needed.

Step 5 - Enforce fatal dependency validation in draw/composition

What: Make render-time scene composition fail fatally if a previously bindable dependency later becomes unresolved.

How: Update the draw path so each layer resolves or revalidates the current glyph slot for the layer dependency through the reverse index instead of trusting old scene slot data. If resolution fails, emit the same class of fatal log and abort machine progress.

File(s):

• crates/console/prometeu-drivers/src/gfx.rs
• crates/console/prometeu-drivers/src/frame_composer.rs

Criterios de Aceite

• No canonical scene type stores runtime glyph slot id as scene dependency state.
• SCENE decode/encode paths serialize per-layer dependency as AssetId (i32).
• AssetManager maintains a reverse glyph index updated by preload and commit.
• bind_scene fatalizes with clear logging when a dependency is missing.
• Draw/composition fatalizes with clear logging when a dependency is missing.
• No runtime path continues scene composition after missing dependency detection.

Tests / Validacao

Unit Tests

• Add/update tests for scene decode under the widened AssetId field.
• Add/update tests for reverse index maintenance across preload, commit, overwrite, and shutdown.
• Add/update tests for FrameComposer bind failure on missing glyph dependency.

Integration Tests

• Add/update runtime integration tests covering:
  • scene bind with all dependencies present;
  • fatal bind when a dependency is absent;
  • fatal draw when a dependency becomes unresolved after bind, if that transition is constructible in tests.

Manual Verification

• Load a cartridge with scene and glyph dependencies committed in non-matching slot order and confirm bind still resolves correctly.
• Confirm fatal logs identify the missing AssetId and layer when dependency resolution fails.

Riscos

• Runtime fatalization may expose pre-existing tests or flows that assumed passive failure.
• Reverse-index maintenance can become incorrect if any overwrite/clear path is missed.
• Removing slot ids from scene/cache types can cascade into a larger render refactor than expected if code paths implicitly rely on them.