diff --git a/docs/runtime/decisions/013-asset-codec-none-vs-raw.md b/docs/runtime/decisions/013-asset-codec-none-vs-raw.md deleted file mode 100644 index 656b0955..00000000 --- a/docs/runtime/decisions/013-asset-codec-none-vs-raw.md +++ /dev/null @@ -1,102 +0,0 @@ -# Decision 013 - Asset Codec `NONE` vs `RAW` - -## Status - -Accepted - -## Contexto - -O runtime ja fechou o contrato de `tile bank` v1 com: - -- layout normativo definido por `bank_type` + metadata do proprio bank; -- payload serializado que pode diferir da forma residente; -- decode especifico do bank antes da materializacao em memoria. - -Mesmo assim, o campo `codec` continua publicado como `RAW` em specs e codigo. - -Isso gera ambiguidade semantica porque `RAW` pode sugerir: - -- ausencia de compressao; -- ou bytes ja prontos para consumo direto. - -Essa segunda leitura conflita com o modelo que o runtime quer preservar: - -- layout pertence ao contrato do bank; -- `codec` deve representar a camada generica de transformacao do payload, sem substituir o contrato especifico de formato/layout de banks especializados. - -## Decisao - -O valor canonico para ausencia de codec adicional passa a ser `NONE`. - -Regras da decisao: - -1. `codec` passa a significar somente: - - pipeline generico de transformacao do payload; e/ou - - transformacao de transporte/materializacao que nao pertence ao contrato especifico de um `bank_type`. -2. O layout serializado de um asset continua pertencendo ao contrato normativo do `bank_type`, nao ao valor de `codec`. -3. `TILES` v1 deve migrar de `codec = RAW` para `codec = NONE`. -4. `SOUNDS` v1 tambem deve migrar de `codec = RAW` para `codec = NONE`, para manter semantica uniforme de assets sem codec adicional. -5. Durante uma janela curta de transicao, o runtime pode aceitar `RAW` como sinonimo legado de `NONE`. -6. A especificacao publicada deve tratar `NONE` como valor canonico e `RAW` como legado/deprecated durante a migracao. - -## Rationale - -`NONE` comunica melhor a ausencia de codec adicional do que `RAW`. - -Isso importa porque o runtime ja distingue com clareza: - -- bytes de transporte em `assets.pa`; -- decode normativo do bank quando o bank ja define seu proprio formato; -- objeto residente em memoria. - -Se `codec` continuar com nome que sugere "dados crus", ele enfraquece exatamente a separacao arquitetural que o modelo de assets quer proteger. - -Ao mesmo tempo, `codec` nao deve ser reduzido conceitualmente a "compressao apenas". - -Para banks especializados como `TILES` e `SOUNDS`, o contrato principal de formato/layout ja vive no proprio bank, entao `codec` tende a ficar restrito a uma camada adicional ou mesmo ausente. - -Para banks mais genericos, como um futuro `BLOB`, `codec` pode desempenhar papel mais abrangente e carregar um pipeline generico de formato + transformacao + compactacao. - -A opcao por uma compatibilidade curta evita uma segunda troca brusca no ecossistema, mas sem cristalizar dupla semantica por tempo indeterminado. - -## Invariantes / Contrato - -- `codec` nao define layout especifico de `bank_type`. -- `codec` define apenas a camada generica de transformacao aplicavel ao payload. -- `codec = NONE` significa ausencia de codec generico adicional. -- `codec = NONE` nao significa ausencia de decode do bank. -- `bank_type` + metadata normativa continuam definindo o layout serializado e a reconstrucao do asset. -- `RAW`, quando aceito durante a transicao, deve ser tratado como alias legado de `NONE`, nao como semantica diferente. -- Novo material normativo nao deve publicar `RAW` como valor canonico. - -## Impactos - -- Specs: - - `docs/runtime/specs/15-asset-management.md` deve trocar o valor canonico para `NONE` e explicitar a semantica de transicao. -- Runtime: - - o loader deve aceitar `NONE` como valor principal; - - durante a migracao, pode aceitar `RAW` como alias legado. -- Modelo de assets: - - `codec` continua disponivel para desempenhar papel mais abrangente em banks genericos futuros, como `BLOB`. -- Packer: - - deve publicar `NONE` como valor canonico no mesmo ciclo de propagacao. -- Tooling e fixtures: - - testes, exemplos e dados sinteticos devem migrar para `NONE`. -- Learn: - - guias pedagogicos devem refletir que `codec` pertence ao eixo de compressao/transporte, nao ao layout do bank. - -## Referencias - -- `docs/runtime/specs/15-asset-management.md` -- `docs/runtime/specs/04-gfx-peripheral.md` -- agenda source: `023-asset-codec-none-vs-raw` - -## Propagacao Necessaria - -1. Abrir PR de propagacao para: - - specs; - - runtime; - - testes/fixtures; - - packer. -2. Publicar `NONE` como canonico e marcar `RAW` como legado durante a janela curta de transicao. -3. Encerrar a compatibilidade com `RAW` apos a migracao coordenada do runtime e do packer. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index a60ed0f3..e3f3c992 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -16,7 +16,7 @@ Regra de uso: Decisoes ativas: -- `013-asset-codec-none-vs-raw.md` +Nenhuma no momento. Decisoes implementadas e aposentadas (migradas para `learn/`): @@ -40,6 +40,7 @@ Decisoes aposentadas que ja viraram spec: - `004-host-fault-taxonomy.md` -> `../specs/16a-syscall-policies.md` - `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md` -> `../specs/06-input-peripheral.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md` +- `013-asset-codec-none-vs-raw.md` -> `../specs/15-asset-management.md`, `../learn/mental-model-asset-management.md`, `crates/console/prometeu-drivers/src/asset.rs`, `crates/console/prometeu-hal/src/asset.rs` Racional historico (nao normativo): diff --git a/docs/runtime/learn/mental-model-asset-management.md b/docs/runtime/learn/mental-model-asset-management.md index d8a84d8f..9f9e7a9d 100644 --- a/docs/runtime/learn/mental-model-asset-management.md +++ b/docs/runtime/learn/mental-model-asset-management.md @@ -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".