---
id: PLN-0004
ticket: asset-entry-codec-enum-with-metadata
title: Asset Entry Codec Enum Execution
status: accepted
created: 2026-04-09
completed:
tags: [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.