This commit is contained in:
2026-03-24 13:40:56 +00:00
parent ecc1a864bb
commit 7b7a633ef4
3 changed files with 48 additions and 104 deletions
@@ -7,7 +7,10 @@ Companion specs:
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
Origin decision: [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
Origin decisions:
- [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
- [`../decisions/013-asset-codec-none-vs-raw.md`](../decisions/013-asset-codec-none-vs-raw.md)
PROMETEU treats assets as a self-contained cart artifact, not as metadata scattered across `manifest.json`, the loader, and the runtime.
@@ -106,6 +109,48 @@ The key point is to separate:
- the generic codec layer, when one exists;
- the operational strategy for reading and decode.
## Specialized Banks vs Generic Banks
The current asset model works better if you do not treat every bank as equally generic.
Some banks are specialized:
- `TILES`
- `SOUNDS`
For these, the bank contract already carries most of the important format rules. That means:
- serialized layout belongs primarily to the bank contract;
- metadata validation belongs primarily to the bank contract;
- `codec` may be absent or minimal.
Other banks may be more generic in the future, such as a `BLOB`-style bank.
For those, `codec` can do more real work and describe a broader generic transformation pipeline for the payload.
That is the right hierarchy:
- specialized bank first;
- generic codec layer second.
Not the other way around.
## Why `NONE` Matters
The move from `RAW` to `NONE` is not just a rename. It fixes the mental model.
`RAW` encouraged the wrong intuition that the bytes were somehow already "raw" in the runtime sense. But for specialized banks that is often false.
`NONE` is better because it says only this:
- there is no additional generic codec layer.
It does not say:
- there is no bank-specific decode;
- there is no transformation before residency;
- serialized bytes and resident memory are identical.
## Serialized Form Is Not Resident Form
One of the most important asset-management lessons in the current runtime is that `codec = NONE` does not mean "bitwise identical to in-memory layout".