105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0040
|
|
ticket: scene-bank-glyph-runtime-binding-leak
|
|
title: Scene glyph dependency spec and wire layout migration
|
|
status: done
|
|
created: 2026-04-24
|
|
completed: 2026-04-24
|
|
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.
|