141 lines
6.1 KiB
Markdown
141 lines
6.1 KiB
Markdown
---
|
|
id: PLN-0041
|
|
ticket: scene-bank-glyph-runtime-binding-leak
|
|
title: Scene glyph runtime resolution, reverse index, and fatal paths
|
|
status: done
|
|
created: 2026-04-24
|
|
completed: 2026-04-24
|
|
tags: [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.
|