prometeu-runtime/discussion/workflow/plans/PLN-0004-asset-entry-codec-enum-execution.md

id	ticket	title	status	created	completed	tags
PLN-0004	asset-entry-codec-enum-with-metadata	Asset Entry Codec Enum Execution	accepted	2026-04-09		asset runtime codec metadata

Briefing

Implement DEC-0005 by replacing AssetEntry.codec: String with a typed Rust enum while keeping the assets.pa JSON wire format as a canonical SCREAMING_SNAKE_CASE string. The initial supported codec set contains only None, serialized as NONE. Unknown codecs must fail during AssetEntry validation, RAW must be removed from the accepted contract, and runtime code must stop relying on free-form string comparisons.

Decisions de Origem

• DEC-0005: Asset Entry Codec Enum Contract

Alvo

Land a runtime-side implementation that:

• introduces a serializable/deserializable AssetCodec enum in prometeu-hal;
• migrates AssetEntry to use the enum directly;
• rejects unknown codec strings during assets.pa parsing/validation;
• removes legacy RAW handling from runtime consumers and tests;
• preserves the current JSON transport contract for the Studio packer: codec remains a SCREAMING_SNAKE_CASE string in assets.pa.

Escopo

• Runtime contract changes in prometeu-hal for AssetEntry and codec serialization.
• Cartridge loading and assets.pa validation behavior.
• Asset driver logic and tests that currently assume codec is a String.
• Runtime test fixtures that construct AssetEntry instances directly.

Fora de Escopo

• Studio/Java packer implementation work.
• Introduction of any real codec beyond None.
• Design or implementation of metadata.codec payload shapes for future codecs.
• Discussion or implementation of a separate DTO just for AssetEntry.

Plano de Execucao

Step 1 - Introduce AssetCodec in prometeu-hal

What: Define the runtime enum for asset codecs and migrate AssetEntry.codec from String to that enum.

How: Add AssetCodec to crates/console/prometeu-hal/src/asset.rs with idiomatic Rust variant naming and explicit serde mapping to SCREAMING_SNAKE_CASE. The initial enum must contain only None, serialized as NONE. Update AssetEntry to use AssetCodec and remove the legacy comment about RAW.

File(s):

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

Step 2 - Make assets.pa parsing fail on unknown codecs

What: Ensure unknown codec strings are rejected before any asset load path proceeds.

How: Rely on enum deserialization failure or an explicit validation hook during assets.pa header parsing so that invalid codec values produce CartridgeError::InvalidFormat. Keep the failure at AssetEntry validation time inside cartridge loading, not delayed to driver execution.

File(s):

• crates/console/prometeu-hal/src/cartridge_loader.rs
• Any supporting type definitions in crates/console/prometeu-hal/src/cartridge.rs if required by parsing flow

Step 3 - Remove runtime string-based codec branching

What: Update asset runtime behavior to consume the enum directly and remove legacy RAW acceptance.

How: Replace codec_is_none_or_legacy_raw and string matches in crates/console/prometeu-drivers/src/asset.rs with enum-based matching on AssetCodec. Ensure unsupported codecs remain an error path, but RAW is no longer recognized anywhere in runtime logic.

File(s):

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

Step 4 - Update test fixtures and regression coverage

What: Bring existing tests and fixtures in line with the new typed contract and add regression tests for rejection behavior.

How: Replace direct string fixture values such as "NONE" and "RAW" with enum construction where tests instantiate AssetEntry directly. Add or update loader tests to cover:

• successful parse of codec: "NONE";
• failure on unknown codec strings;
• failure on legacy RAW if it still appears in serialized input.

Update driver tests to assert enum-based behavior for the supported codec set.

File(s):

• crates/console/prometeu-hal/src/cartridge_loader.rs
• crates/console/prometeu-drivers/src/asset.rs
• crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs

Step 5 - Align downstream packer work item

What: Capture the non-runtime propagation requirement for the Studio packer.

How: Record in implementation notes, issue tracking, or follow-up execution context that the Studio/Java packer must emit canonical SCREAMING_SNAKE_CASE codec strings and must stop producing RAW. No runtime code should add compatibility shims for packer drift.

File(s):

• No runtime file changes required in this repository for this step

Criterios de Aceite

• AssetEntry.codec is an enum in Rust, not a String.
• assets.pa still serializes/deserializes codec as a JSON string.
• The canonical wire spelling for the initial codec is NONE.
• Unknown codec strings cause cartridge loading to fail before asset loading proceeds.
• RAW is no longer accepted by runtime code or runtime tests.
• Asset driver code branches on AssetCodec, not string literals.
• Existing runtime tests pass after fixture migration, and regression tests cover the new failure behavior.

Tests / Validacao

Unit Tests

• Serialization/deserialization tests for AssetCodec proving AssetCodec::None <-> "NONE".
• Asset driver tests that match on enum variants instead of strings.

Integration Tests

• Cartridge loader test that accepts assets.pa headers containing codec: "NONE".
• Cartridge loader test that rejects an unknown codec string.
• Cartridge loader test that rejects legacy RAW.

Manual Verification

• Inspect generated assets.pa header JSON from a known-good sample and verify codec remains a string field with SCREAMING_SNAKE_CASE.
• Run the relevant Rust test suites for prometeu-hal, prometeu-drivers, and any affected runtime tests.

Riscos

• Existing tests and fixtures may be numerous because AssetEntry is widely constructed directly.
• If deserialization failure maps too generically, debugging bad packer output may become opaque unless tests assert the intended failure path clearly.
• Studio work is out of scope for this repository, so rollout coordination is required to avoid runtime/packer contract skew.