From f652e8d5d390186f7fd5f5e0ab4ba4b6e2c3066f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 20 Mar 2026 08:04:55 +0000 Subject: [PATCH] codec RAW -> NONE --- .../agendas/023-asset-codec-none-vs-raw.md | 118 ------------------ docs/runtime/agendas/README.md | 1 - .../decisions/013-asset-codec-none-vs-raw.md | 102 +++++++++++++++ docs/runtime/decisions/README.md | 2 +- ...et-codec-none-canonicalization-in-specs.md | 63 ++++++++++ .../016-asset-codec-none-runtime-and-tests.md | 61 +++++++++ docs/runtime/pull-requests/README.md | 3 +- 7 files changed, 229 insertions(+), 121 deletions(-) delete mode 100644 docs/runtime/agendas/023-asset-codec-none-vs-raw.md create mode 100644 docs/runtime/decisions/013-asset-codec-none-vs-raw.md create mode 100644 docs/runtime/pull-requests/015-asset-codec-none-canonicalization-in-specs.md create mode 100644 docs/runtime/pull-requests/016-asset-codec-none-runtime-and-tests.md diff --git a/docs/runtime/agendas/023-asset-codec-none-vs-raw.md b/docs/runtime/agendas/023-asset-codec-none-vs-raw.md deleted file mode 100644 index 6f5cf4db..00000000 --- a/docs/runtime/agendas/023-asset-codec-none-vs-raw.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 95dec250..50c745d0 100644 --- a/docs/runtime/agendas/README.md +++ b/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: diff --git a/docs/runtime/decisions/013-asset-codec-none-vs-raw.md b/docs/runtime/decisions/013-asset-codec-none-vs-raw.md new file mode 100644 index 00000000..656b0955 --- /dev/null +++ b/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. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index beb86265..a60ed0f3 100644 --- a/docs/runtime/decisions/README.md +++ b/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/`): 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 new file mode 100644 index 00000000..16d81d94 --- /dev/null +++ b/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 diff --git a/docs/runtime/pull-requests/016-asset-codec-none-runtime-and-tests.md b/docs/runtime/pull-requests/016-asset-codec-none-runtime-and-tests.md new file mode 100644 index 00000000..59a5ddf5 --- /dev/null +++ b/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 diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index 9a96ae15..9ab0c91e 100644 --- a/docs/runtime/pull-requests/README.md +++ b/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