prometeu-runtime/discussion/lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md

id	ticket	title	created	tags
LSN-0024	asset-entry-codec-enum-with-metadata	String on the Wire, Enum in the Runtime	2026-04-09	asset runtime codec rust contract

Context

This discussion closed the contract for AssetEntry.codec in the runtime asset model. The system already serialized assets.pa as JSON produced by the Studio in Java, while the runtime consumed that JSON in Rust. The original runtime model kept codec as a free-form String, which allowed legacy aliases such as RAW and pushed validation and branching into scattered string comparisons.

The implemented change moved the runtime to a typed enum while preserving the existing transport simplicity of the pack format.

Key Decisions

Asset Entry Codec Enum Contract

What: Keep codec as a JSON string in assets.pa, but deserialize it directly into a Rust enum in AssetEntry. The initial codec set contains only None, serialized canonically as NONE in SCREAMING_SNAKE_CASE.

Why: This preserves a simple cross-language wire contract for the Studio packer while making the runtime honest about the domain model it operates on. The loader now rejects unknown codecs early, and runtime consumers branch on enum variants instead of raw strings.

Trade-offs: The runtime loses open-ended tolerance for arbitrary codec names, which is intentional. Future codecs with payload-specific metadata still require a dedicated follow-up decision once a real codec exists.

Patterns and Algorithms

• Use a stable textual discriminant on the wire and a typed enum in the runtime model.
• Let deserialization enforce the supported variant set instead of adding compatibility shims deeper in the execution path.
• Keep the discriminant contract canonical across producers and consumers; do not allow per-producer aliases.
• Preserve editorial or bank-specific metadata outside the codec discriminant so future codec payload metadata can be added without collapsing the whole asset model into an untyped blob.

Pitfalls

• A runtime that accepts legacy aliases such as RAW keeps historical ambiguity alive and makes it harder to reason about the true contract.
• If fixtures are constructed directly in tests, typed metadata helpers can expose missing required fields that were previously masked by weaker validation.
• Cross-language contracts become fragile if the wire spelling is not explicitly canonized. The producer must conform exactly to the runtime contract.

Takeaways

• Use a string on the wire when cross-language transport simplicity matters, but deserialize into an enum as soon as the runtime needs semantic guarantees.
• Canonical spelling belongs to the shared contract, not to whichever producer happens to serialize first.
• Rejecting unknown codec values at asset-entry validation time keeps failures local, early, and easier to debug.