142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
---
|
|
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.
|