clean up

docs/runtime/decisions/013-asset-codec-none-vs-raw.md

@@ -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.

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):
 

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".