prometeu-runtime/discussion/workflow/plans/PLN-0016-scene-binary-payload-format-and-decoder.md

id	ticket	title	status	created	completed	tags
PLN-0016	scene-bank-and-viewport-cache-refactor	Plan - Scene Binary Payload Format and Decoder	accepted	2026-04-13		asset runtime scene codec binary-format

Objective

Define the canonical binary payload contract for SCENE assets and implement the runtime decoder needed to load SceneBank content without JSON-based scene payloads.

Background

DEC-0013 established SceneBank as the canonical loaded scene aggregate. PLN-0011 introduced BankType::SCENE and the scene-aware bank slot model, but intentionally left SCENE payload decoding open. A temporary todo!() now blocks scene payload materialization in the asset manager until the binary contract is closed. This plan isolates that format and decoder work before the final integration pass.

Scope

Included

• Define the binary on-disk/on-wire payload format for SCENE.
• Define the minimum metadata contract needed in AssetEntry for SCENE.
• Implement the runtime decoder from payload bytes into SceneBank.
• Add format and decode tests for valid and invalid scene payloads.
• Re-enable scene asset load/preload coverage once the decoder exists.

Excluded

• SceneViewportCache
• SceneViewportResolver
• renderer migration
• cartridge authoring tooling beyond what is strictly needed to encode test fixtures
• reopening canonical scene/runtime type design

Execution Steps

Step 1 - Define the binary SCENE payload contract

What: Close the binary layout for serialized SceneBank assets.

How:

• Define a versioned binary format with:
  • file/payload prelude or version marker
  • fixed four-layer scene layout
  • per-layer metadata block
  • per-layer tilemap dimensions
  • serialized tile records
• Keep the format aligned with the canonical runtime shape from PLN-0011:
  • SceneBank
  • [SceneLayer; 4]
  • motion_factor
  • TileMap
  • Tile
• Document field sizes, endianness, ordering, and validation rules.

File(s):

• crates/console/prometeu-hal/src/asset.rs
• crates/console/prometeu-hal/src/cartridge_loader.rs
• Additional shared asset-format module(s) if needed

Step 2 - Define SCENE metadata requirements in AssetEntry

What: Decide what belongs in AssetEntry.metadata versus the binary payload itself.

How:

• Keep metadata minimal and stable.
• Add only fields that materially help validation or loader routing.
• Avoid duplicating large structural scene information in both metadata and payload.
• Add typed metadata helpers in HAL if required for scene assets.

File(s):

• crates/console/prometeu-hal/src/asset.rs

Step 3 - Implement the runtime SCENE decoder

What: Replace the current todo!() loader path with a real binary decoder.

How:

• Implement perform_load_scene_bank(...) using the accepted binary contract.
• Decode from slice/reader into canonical runtime objects:
  • SceneBank
  • SceneLayer
  • TileMap
  • Tile
• Add explicit validation for:
  • invalid version
  • short payload
  • invalid tile-size values
  • layer count mismatch
  • tile count mismatch
  • numeric overflow / malformed dimensions
• Keep decode logic self-contained and free of viewport/cache behavior.

File(s):

• crates/console/prometeu-drivers/src/asset.rs
• Supporting HAL/shared modules if decoder helpers are factored out

Step 4 - Re-enable scene asset loading paths and tests

What: Turn scene asset loading back on in the asset manager and restore coverage.

How:

• Re-enable the SCENE load/preload path currently blocked by the todo!().
• Add tests for:
  • scene payload decode success
  • scene asset load
  • scene preload on initialization
  • malformed scene payload rejection
• Ensure glyph/sound behavior remains unchanged.

File(s):

• crates/console/prometeu-drivers/src/asset.rs

Step 5 - Confirm cartridge-loader and asset-table compatibility

What: Ensure the broader cartridge/asset pipeline accepts the finalized SCENE contract cleanly.

How:

• Verify AssetEntry and cartridge-loading paths accept the new scene metadata contract.
• Add targeted tests for asset-table parsing or preload validation if needed.
• Keep this step scoped to compatibility with the finalized binary scene payload, not new tooling features.

File(s):

• crates/console/prometeu-hal/src/cartridge_loader.rs
• crates/console/prometeu-hal/src/asset.rs

Test Requirements

Unit Tests

• Valid binary scene payloads decode into the expected SceneBank.
• Invalid payloads fail with explicit decoder errors.
• Per-layer metadata and tile contents survive round-trip fixture decode.

Integration Tests

• SCENE assets can be loaded and preloaded through AssetManager.
• Scene bank slot installation works without breaking glyph/sound behavior.

Manual Verification

• Inspect one representative binary scene fixture and confirm the decoded SceneBank matches the expected four-layer canonical shape.

Acceptance Criteria

• The binary SCENE payload format is explicitly defined and versioned.
• AssetEntry requirements for SCENE are documented and implemented.
• perform_load_scene_bank(...) is implemented without JSON payload parsing.
• Scene load/preload tests pass against the finalized binary decoder.
• Glyph and sound asset paths remain unaffected.

Dependencies

• Depends on PLN-0011.
• Should complete before the final integration/cleanup pass in PLN-0015.
• Source decision: DEC-0013

Risks

• Overloading AssetEntry.metadata can duplicate scene structure and make the contract brittle.
• A weak binary format definition can create hidden compatibility problems for future scene growth.
• Decoder validation gaps can surface later as corrupted scene state instead of explicit asset-load failures.