prometeu-runtime/discussion/workflow/plans/PLN-0040-scene-glyph-dependency-spec-and-wire-layout.md

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