SCENE BANL leaking slot ids to binary contract
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
---
|
||||
id: PLN-0040
|
||||
ticket: scene-bank-glyph-runtime-binding-leak
|
||||
title: Scene glyph dependency spec and wire layout migration
|
||||
status: review
|
||||
created: 2026-04-24
|
||||
completed:
|
||||
tags: [gfx, runtime, asset, scene, glyph, format, spec]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the specification-side portion of `DEC-0021` by rewriting the `SCENE` payload contract so that each scene layer serializes a glyph dependency by canonical `AssetId (i32)` instead of a runtime glyph slot id. This plan covers only normative docs and wire-layout definition. It does not implement runtime code.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0021` — Scene Bank glyph dependencies MUST bind by `asset_id`, not runtime slot.
|
||||
|
||||
## Alvo
|
||||
|
||||
- Canonical runtime specs under `docs/specs/runtime/`.
|
||||
- Shared payload constants and comments under `crates/console/prometeu-hal/` only where needed to reflect the normative wire layout.
|
||||
|
||||
## Escopo
|
||||
|
||||
- Rewrite the `SCENE` payload description to replace per-layer runtime slot semantics with per-layer `AssetId`.
|
||||
- Define widened field width for serialized scene glyph dependencies.
|
||||
- Remove any spec language implying passive missing-dependency status for scene composition.
|
||||
- Align related comments/constants with the new payload field width and meaning.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Runtime bind/draw implementation.
|
||||
- Reverse index implementation in `AssetManager`.
|
||||
- Test fixture rewrites and tool migration.
|
||||
- Any compatibility or versioning path for the old payload.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Rewrite the normative `SCENE` payload contract
|
||||
|
||||
**What:**
|
||||
Define the scene-layer dependency field as `AssetId (i32)` and remove all remaining wording that treats scene glyph linkage as runtime slot topology.
|
||||
|
||||
**How:**
|
||||
Update the relevant `docs/specs/runtime` sections so the payload layout, field meaning, and operational consequences all match `DEC-0021`. State explicitly that the scene asset is cold-description only and MUST NOT encode runtime slot ids.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- any scene/gfx spec chapter that documents `SCENE` payload fields or scene dependency semantics.
|
||||
|
||||
### Step 2 - Update shared HAL wire-layout constants and inline documentation
|
||||
|
||||
**What:**
|
||||
Bring shared constants and comments into sync with the widened scene dependency field.
|
||||
|
||||
**How:**
|
||||
Review `crates/console/prometeu-hal/src/asset.rs` and any nearby scene-related code comments. Update layer-header sizing constants and field comments if the payload header width changes from the previous single-byte dependency representation.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/asset.rs`
|
||||
- neighboring scene payload comments when affected.
|
||||
|
||||
### Step 3 - Tighten the published fatal-error semantics
|
||||
|
||||
**What:**
|
||||
Make the public documentation consistent with the accepted fatal behavior for missing scene glyph dependencies.
|
||||
|
||||
**How:**
|
||||
Remove proposed/legacy wording that frames missing dependencies as recoverable status returns for scene activation/composition. Describe the bind-time and draw-time dependency absence as fatal machine errors with clear logging expectations.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/runtime/04-gfx-peripheral.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|
||||
- any other spec chapter that describes `composer.bind_scene`.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] The published `SCENE` payload contract defines per-layer glyph dependency as `AssetId (i32)`.
|
||||
- [ ] No normative spec text claims that `SCENE` serializes runtime glyph slot ids.
|
||||
- [ ] No normative spec text retains `ERROR_MISSING_DEPENDENCIES` as the accepted contract for scene dependency failures.
|
||||
- [ ] Shared HAL constants/comments reflect the revised payload layout where applicable.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Add or update compile-time/runtime assertions only if shared payload constants are exercised by existing tests.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- None in this plan; verification is doc/contract oriented.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Review the updated spec text to ensure every `SCENE` glyph dependency reference uses `AssetId` language.
|
||||
- Verify that the documented payload width matches `AssetId = i32`.
|
||||
- Verify that fatal semantics for missing dependencies are stated consistently across spec chapters.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Spec-only edits can drift from the runtime implementation if later plans are not executed promptly.
|
||||
- Scene payload layout changes may require touching multiple docs; missing one will leave contradictory contract text.
|
||||
- If HAL constants are updated here before runtime code, temporary compile or test fallout may appear in later plans and must be handled intentionally.
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
id: PLN-0041
|
||||
ticket: scene-bank-glyph-runtime-binding-leak
|
||||
title: Scene glyph runtime resolution, reverse index, and fatal paths
|
||||
status: review
|
||||
created: 2026-04-24
|
||||
completed:
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
id: PLN-0042
|
||||
ticket: scene-bank-glyph-runtime-binding-leak
|
||||
title: Scene glyph tooling, fixtures, and test payload migration
|
||||
status: review
|
||||
created: 2026-04-24
|
||||
completed:
|
||||
tags: [gfx, runtime, asset, scene, glyph, tooling, tests]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Complete the implementation surface of `DEC-0021` by migrating all scene payload producers, fixtures, stress tools, and test data away from serialized runtime glyph slots and onto per-layer glyph dependency `AssetId (i32)`.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0021` — Scene Bank glyph dependencies MUST bind by `asset_id`, not runtime slot.
|
||||
|
||||
## Alvo
|
||||
|
||||
- Runtime tests and helpers under `crates/console/prometeu-drivers/`
|
||||
- Runtime tests under `crates/console/prometeu-system/`
|
||||
- Tooling and stress generators under `crates/tools/`
|
||||
|
||||
## Escopo
|
||||
|
||||
- Rewrite scene payload writers in tests and tools.
|
||||
- Rewrite test fixtures and expectations that still name or assert `glyph_bank_id`.
|
||||
- Ensure stress and fixture content uses valid `AssetId` dependencies and exercises runtime resolution order independence.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Core runtime implementation of reverse index and fatal semantics.
|
||||
- Public API exposure of reverse lookup.
|
||||
- Backward-compatible scene payload generation.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Rewrite local scene payload builders in driver tests
|
||||
|
||||
**What:**
|
||||
Update every driver-side scene helper and binary payload builder that still writes per-layer runtime slot ids.
|
||||
|
||||
**How:**
|
||||
Search all `SceneLayer` builders and `SCENE` payload encoders in driver tests. Replace slot-oriented setup with per-layer dependency `AssetId`, then adjust assertions accordingly.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- `crates/console/prometeu-drivers/src/frame_composer.rs`
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`
|
||||
- `crates/console/prometeu-drivers/src/hardware.rs`
|
||||
|
||||
### Step 2 - Rewrite system/runtime integration fixtures
|
||||
|
||||
**What:**
|
||||
Migrate integration fixtures so scene setup reflects asset-id dependencies and runtime slot resolution.
|
||||
|
||||
**How:**
|
||||
Update helper functions and tests under `prometeu-system` that construct scenes or assume direct slot semantics. Ensure tests explicitly preload/commit glyph assets under varying slot orders and verify correct resolution behavior.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`
|
||||
- other runtime test modules that build scene fixtures.
|
||||
|
||||
### Step 3 - Rewrite tooling and stress generators
|
||||
|
||||
**What:**
|
||||
Update scene-producing tools so published binary payloads match the accepted scene dependency contract.
|
||||
|
||||
**How:**
|
||||
Rewrite stress/payload builders to write `AssetId (i32)` per layer and to generate coherent asset tables/preload data that prove runtime resolution by dependency identity rather than baked slot topology.
|
||||
|
||||
**File(s):**
|
||||
- `crates/tools/pbxgen-stress/src/lib.rs`
|
||||
- any other local scene payload generators discovered during implementation.
|
||||
|
||||
### Step 4 - Add regression coverage for former slot leakage
|
||||
|
||||
**What:**
|
||||
Add focused regression cases that fail if scene payloads again leak runtime glyph slot ids.
|
||||
|
||||
**How:**
|
||||
Introduce tests that deliberately load glyph dependencies into different slots from their prior fixture order and verify scene bind/draw behavior depends on `AssetId` resolution only.
|
||||
|
||||
**File(s):**
|
||||
- affected test modules under `prometeu-drivers`, `prometeu-system`, and tool tests if present.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] No test or tooling payload writer serializes per-layer runtime glyph slot id for `SCENE`.
|
||||
- [ ] Scene fixtures express glyph dependencies by `AssetId`.
|
||||
- [ ] At least one regression test proves glyph slot order does not matter for scene activation.
|
||||
- [ ] At least one regression test would fail if old slot-leak behavior returned.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Update existing scene codec/fixture tests to assert `AssetId`-based dependency behavior.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Run runtime integration coverage where scene dependencies resolve correctly despite different glyph slot placement.
|
||||
- Run regression coverage for fatal behavior when dependencies are absent.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Inspect representative generated payload bytes to confirm widened dependency field writing.
|
||||
- Verify stress/tool outputs remain consumable by the updated runtime.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Test helper churn may be broad because many fixtures were written around the leaked slot model.
|
||||
- Tool outputs may silently drift if any scene payload writer is missed.
|
||||
- Regression tests can become brittle if they depend on incidental slot ordering instead of declared dependency identity.
|
||||
|
||||
Reference in New Issue
Block a user