diff --git a/docs/runtime/learn/mental-model-asset-management.md b/docs/runtime/learn/mental-model-asset-management.md index 8d7710ff..d8a84d8f 100644 --- a/docs/runtime/learn/mental-model-asset-management.md +++ b/docs/runtime/learn/mental-model-asset-management.md @@ -103,18 +103,25 @@ In v1, that decision comes from the `codec`/CODEX: The key point is to separate: - the asset storage contract; +- the generic codec layer, when one exists; - the operational strategy for reading and decode. ## Serialized Form Is Not Resident Form -One of the most important asset-management lessons in the current runtime is that `RAW` does not mean "bitwise identical to in-memory layout". +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". The tile-bank path is the concrete example: +- there is no additional generic codec layer for the asset; - the serialized payload stores indexed pixels as packed `4bpp`; - the palette table remains serialized as `RGB565` little-endian; - the runtime expands pixels into one `u8` index per pixel after decode. +That is exactly why `codec` and bank contract must stay separate in the mental model: + +- `codec` may be absent; +- the bank-specific decode may still be real and mandatory. + That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of as different concepts: - `size` is transport cost inside `assets.pa`; diff --git a/docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md b/docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md deleted file mode 100644 index 16d81d94..00000000 --- a/docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md +++ /dev/null @@ -1,63 +0,0 @@ -# 015 Asset Codec `NONE` Canonicalization in Specs - -## Briefing - -A decision `013` fechou que o valor canonico para ausencia de codec adicional passa a ser `NONE`, com `RAW` tratado apenas como alias legado durante a migracao curta. - -O runtime precisa publicar essa semantica nas specs antes de seguir com a propagacao completa em codigo e tooling. - -## Decisions de Origem - -- `docs/runtime/decisions/013-asset-codec-none-vs-raw.md` - -## Alvo - -Atualizar o contrato normativo de assets para que: - -1. `codec = NONE` seja o valor canonico publicado; -2. `RAW` apareca apenas como legado/deprecated durante a janela curta de transicao; -3. a semantica de `codec` fique clara como camada generica de transformacao do payload; -4. a diferenca entre `codec` e layout especifico de `bank_type` fique explicita. - -## Escopo - -- revisar `docs/runtime/specs/15-asset-management.md` -- revisar `docs/runtime/specs/13-cartridge.md` somente se necessario para coerencia de referencia -- revisar `docs/runtime/learn/mental-model-asset-management.md` somente se a explicacao pedagogica ficar contraditoria apos a mudanca normativa - -## Fora de Escopo - -- alterar codigo do runtime -- alterar packer -- encerrar a compatibilidade legacy em runtime -- redefinir layout de `TILES` ou `SOUNDS` - -## Plano de Execucao - -1. Trocar o valor canonico publicado de `RAW` para `NONE` em `specs/15`. -2. Explicitar que: - - `NONE` significa ausencia de codec generico adicional; - - `NONE` nao significa ausencia de decode do bank; - - layouts especificos continuam pertencendo ao contrato do `bank_type`. -3. Registrar `RAW` apenas como alias legado durante a migracao curta. -4. Revisar linguagem de `OP_MODE` para evitar que `codec` pareca dono do layout de `TILES`. -5. Ajustar referencias editoriais relacionadas se houver contradicao residual. - -## Criterios de Aceite - -- `docs/runtime/specs/15-asset-management.md` publica `NONE` como valor canonico -- a spec deixa claro que `codec` e camada generica de transformacao -- a spec nao atribui a `codec` o layout especifico de `TILES` ou `SOUNDS` -- `RAW` aparece apenas como legado/deprecated, se aparecer - -## Tests / Validacao - -- revisao editorial cruzada entre `specs/15`, `specs/13` e a decision `013` -- checklist de coerencia contra o contrato atual de `TILES` -- verificacao de que o texto nao fecha prematuramente contratos para banks genericos futuros como `BLOB` - -## Riscos - -- deixar a linguagem de transicao ambigua e publicar dupla semantica por tempo demais -- descrever `NONE` de forma que pareca "sem decode" -- endurecer demais `codec` e bloquear banks genericos futuros diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index 9ab0c91e..93edeb84 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -36,7 +36,6 @@ Uma PR deste diretório deve: ## Roadmap Atual -- `015-asset-codec-none-canonicalization-in-specs.md` - `016-asset-codec-none-runtime-and-tests.md` ## PRs Finalizadas @@ -44,3 +43,4 @@ Uma PR deste diretório deve: - `012-assets-preload-asset-id-propagation.md`: concluída. Propagação de ID-based preload concluída em specs e prometeu-hal. - `013-tile-bank-runtime-contract-alignment.md`: concluída. Contrato normativo de `tile bank` v1 alinhado entre `specs/04` e `specs/15`. - `014-tile-bank-loader-packed-nibbles-and-palette-boundary.md`: concluída. Loader/runtime atualizado para consumir payload serializado `4bpp` packed com `64` paletas por bank. +- `015-asset-codec-none-canonicalization-in-specs.md`: concluída. `NONE` publicado como valor canonico de ausencia de codec adicional nas specs. diff --git a/docs/runtime/specs/15-asset-management.md b/docs/runtime/specs/15-asset-management.md index 8c2af766..1ea014c2 100644 --- a/docs/runtime/specs/15-asset-management.md +++ b/docs/runtime/specs/15-asset-management.md @@ -104,19 +104,28 @@ This table describes content identity and storage layout, not live residency. `decoded_size` is the byte count of the materialized runtime bank after decode, not necessarily the same as the serialized payload size. -`codec` identifies how the runtime must interpret the serialized payload slice before the asset becomes a resident bank. +`codec` identifies the generic transformation pipeline applied to the serialized payload slice before the asset becomes a resident bank. + +`codec` does not define the bank-specific serialized layout itself. Specialized banks may still have normative decode rules even when `codec = NONE`. ### 4.1 `TILES` asset contract in v1 For `BankType::TILES`, the runtime-facing v1 contract is: -- `codec = RAW` +- `codec = NONE` - serialized pixels use packed `u4` palette indices - serialized palettes use `RGB565` (`u16`, little-endian) - `palette_count = 64` - runtime materialization may expand pixel indices to one `u8` per pixel -`RAW` for `TILES` means there is no compression stage beyond deterministic reconstruction of the tile bank from its serialized payload. It does not require the serialized byte layout to be identical to the in-memory layout. +`NONE` for `TILES` means there is no additional generic codec layer beyond the bank contract itself. + +For the current transition window: + +- `RAW` is a deprecated legacy alias of `NONE` +- new published material must use `NONE` as the canonical value + +Even with `codec = NONE`, `TILES` still requires deterministic bank-specific decode from its serialized payload. The serialized byte layout is therefore not required to be identical to the in-memory layout. Required `AssetEntry.metadata` fields for `TILES`: @@ -198,7 +207,8 @@ For v1: - `OP_MODE` is derived from `codec`/CODEX; - explicit per-asset hinting is not part of the baseline contract. -- `TILES` with `codec = RAW` may still stage in memory before bank installation because runtime decode expands packed pixel indices into the resident representation. +- `TILES` with `codec = NONE` may still stage in memory before bank installation because bank-specific decode expands packed pixel indices into the resident representation. +- during the migration window, runtime may accept legacy `RAW` as an alias of `NONE`. The runtime does not treat asset installation as implicit side effect.