codec RAW -> NONE

docs/runtime/agendas/023-asset-codec-none-vs-raw.md

@@ -1,118 +0,0 @@
-# Agenda - Asset Codec `NONE` vs `RAW`
-
-## Contexto
-
-O runtime acabou de fechar o contrato de `tile bank` v1 com:
-
-- layout serializado especifico por `bank_type`;
-- metadata normativa do proprio bank;
-- `size` e `decoded_size` distintos;
-- decode runtime-side que pode transformar a forma serializada em forma residente.
-
-Nesse contexto, o campo `codec` continua aparecendo como `RAW` em `specs` e em codigo.
-
-Ao mesmo tempo, a direcao arquitetural desejada e mais estreita:
-
-- `bank_type` + contrato do bank definem formato/layout;
-- `codec` deve representar compressao ou transformacao generica de transporte;
-- layouts especificos de um bank nao devem vazar para o significado de `codec`.
-
-## Problema
-
-`RAW` hoje comunica mal a intencao do campo `codec`.
-
-Para `TILES`, o payload:
-
-- nao esta comprimido;
-- mas tambem nao esta em forma residente;
-- e exige decode normativo do bank antes de virar `TileBank`.
-
-Com isso, `RAW` pode ser lido de dois jeitos conflitantes:
-
-- "sem compressao";
-- "bytes ja estao crus/prontos para consumo".
-
-Se o segundo sentido entrar no modelo mental do projeto, o contrato fica confuso exatamente onde queriamos separar:
-
-- `codec` como compressao;
-- layout como contrato do bank.
-
-## Pontos Criticos
-
-- Fato: `TILES` v1 usa payload serializado `4bpp` packed e runtime materializa `u8` por pixel.
-- Fato: `codec` nao deveria descrever esse layout se o layout ja pertence ao contrato do bank.
-- Fato: `RAW` esta publicado em `specs/15`, fixtures de teste e paths de runtime.
-- Risco: manter `RAW` prolonga leitura ambigua de que `codec` descreve mais do que compressao.
-- Risco: trocar para `NONE` sem fechar linguagem normativa pode gerar migracao incompleta entre runtime e packer.
-- Tradeoff: `NONE` e semanticamente mais honesto para "sem codec adicional", mas exige propagacao coordenada.
-- Hipotese: a troca para `NONE` reduz ambiguidade sem exigir redesenho do modelo de assets, desde que a spec explicite que decode especifico do bank continua existindo mesmo com `codec = NONE`.
-
-## Opcoes
-
-### Opcao 1 - Manter `RAW`
-
-Vantagens:
-
-- zero churn imediato;
-- preserva compatibilidade literal com fixtures e tooling atuais.
-
-Desvantagens:
-
-- mantem um nome que sugere semantica mais larga do que compressao;
-- enfraquece a separacao entre `codec` e layout do bank.
-
-### Opcao 2 - Trocar `RAW` por `NONE`
-
-Vantagens:
-
-- alinha o nome do campo com a ideia de "sem codec adicional";
-- deixa mais claro que o decode de `TILES` vem do contrato do bank, nao do `codec`.
-
-Desvantagens:
-
-- exige propagacao coordenada em specs, runtime, testes e packer;
-- requer cuidado editorial para nao sugerir que `NONE` significa "sem decode".
-
-### Opcao 3 - Introduzir dupla compatibilidade temporaria (`RAW` e `NONE`)
-
-Vantagens:
-
-- reduz atrito de migracao entre runtime e packer;
-- permite transicao progressiva.
-
-Desvantagens:
-
-- aumenta a superficie normativa e a ambiguidade por mais tempo;
-- piora o contrato justamente quando o objetivo e simplifica-lo.
-
-## Sugestao / Recomendacao
-
-Recomendacao principal: adotar `codec = NONE` como contrato alvo e aposentar `RAW`.
-
-Motivo:
-
-- o layout continua sendo definido por `bank_type` e metadata normativa do bank;
-- `codec` fica semanticamente reservado para compressao ou transformacao generica de transporte;
-- `NONE` descreve melhor a ausencia de codec adicional sem negar que o bank ainda tenha seu proprio decode normativo.
-
-Recomendacao de propagacao, se a decisao for confirmada:
-
-1. atualizar `specs/15` para explicitar que `NONE` significa "no additional transport codec";
-2. atualizar runtime/tests para aceitar `NONE`;
-3. decidir se havera ou nao uma janela curta de compatibilidade com `RAW`;
-4. alinhar packer para publicar `NONE` no mesmo ciclo.
-
-## Perguntas em Aberto
-
-1. A transicao deve ser atomica ou com compatibilidade curta `RAW` + `NONE`?
-2. `SOUNDS` tambem deve migrar no mesmo passo para manter uniformidade?
-3. Existe algum artefato externo ao runtime atual que ainda dependa literalmente de `RAW`?
-
-## Criterio para Encerrar
-
-Esta agenda pode virar `decision` quando houver resposta fechada para:
-
-- semantica oficial de `codec` no modelo de assets;
-- string canonica publicada (`NONE` ou permanencia de `RAW`);
-- estrategia de compatibilidade da migracao;
-- lista de propagacao minima em `specs`, runtime e packer.

docs/runtime/agendas/README.md

@@ -24,7 +24,6 @@ As agendas atuais são:
 - `020-perf-host-debug-overlay-isolation.md`
 - `021-perf-vm-allocation-and-copy-pressure.md`
 - `022-perf-cartridge-boot-and-program-ownership.md`
-- `023-asset-codec-none-vs-raw.md`
 ## Sequenciamento Recomendado [PERF]
 
 Ordem sugerida para discussao das agendas de performance:

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

@@ -0,0 +1,102 @@
+# 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:
 
-Nenhuma no momento.
+- `013-asset-codec-none-vs-raw.md`
 
 Decisoes implementadas e aposentadas (migradas para `learn/`):
 

docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md

@@ -0,0 +1,63 @@
+# 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

docs/runtime/pull-requests/016-asset-codec-none-runtime-and-tests.md

@@ -0,0 +1,61 @@
+# 016 Asset Codec `NONE` Runtime and Tests
+
+## Briefing
+
+Com a decision `013`, o runtime deve migrar o valor canonico de `codec` para `NONE` sem quebrar a transicao curta a partir de `RAW`.
+
+Esta PR executa a propagacao em codigo, fixtures e testes do runtime.
+
+## Decisions de Origem
+
+- `docs/runtime/decisions/013-asset-codec-none-vs-raw.md`
+
+## Alvo
+
+Atualizar o runtime para que:
+
+1. `NONE` seja aceito como valor principal de `codec`;
+2. `RAW` seja aceito apenas como alias legado durante a janela curta de transicao;
+3. fixtures e testes passem a publicar `NONE` como valor canonico;
+4. `TILES` e `SOUNDS` fiquem coerentes com a decision.
+
+## Escopo
+
+- atualizar `crates/console/prometeu-drivers/src/asset.rs`
+- atualizar fixtures/testes em `prometeu-drivers`, `prometeu-hal` e `prometeu-system`
+- ajustar comentarios inline onde `RAW` ainda apareca como valor canonico
+
+## Fora de Escopo
+
+- remover imediatamente a compatibilidade com `RAW`
+- alterar packer
+- introduzir novos codecs
+- mudar contratos de layout de `TILES` ou `SOUNDS`
+- publicar banks genericos novos como `BLOB`
+
+## Plano de Execucao
+
+1. Atualizar o path de resolucao de `codec` para aceitar `NONE` como valor canonico.
+2. Preservar `RAW` como alias legado durante a transicao curta.
+3. Migrar fixtures e testes para emitir `NONE`.
+4. Revisar comentarios e exemplos inline para remover `RAW` como default canonico.
+5. Validar que `TILES` e `SOUNDS` continuam operando sem regressao comportamental.
+
+## Criterios de Aceite
+
+- runtime aceita `NONE` em `TILES` e `SOUNDS`
+- runtime continua aceitando `RAW` apenas como alias legado
+- fixtures e testes passam a usar `NONE` como valor canonico
+- nenhum comentario ou helper novo reforca `RAW` como valor principal
+
+## Tests / Validacao
+
+- testes unitarios do asset loader
+- testes do runtime/VM que passam por asset loading
+- revisao de fixtures de cartridge/asset metadata
+
+## Riscos
+
+- deixar paths diferentes tratando `NONE` e `RAW` de forma inconsistente
+- migrar fixtures parcialmente e mascarar regressao real
+- prolongar compatibilidade legacy sem rastro claro para remocao futura

docs/runtime/pull-requests/README.md

@@ -36,7 +36,8 @@ Uma PR deste diretório deve:
 
 ## Roadmap Atual
 
-Nenhuma PR em aberto no momento.
+- `015-asset-codec-none-canonicalization-in-specs.md`
+- `016-asset-codec-none-runtime-and-tests.md`
 
 ## PRs Finalizadas