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