diff --git a/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md b/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md deleted file mode 100644 index 90ddcd6c..00000000 --- a/docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md +++ /dev/null @@ -1,181 +0,0 @@ -# Agenda - Asset Packer Runtime-Facing Contract - -## Contexto - -Hoje o runtime ja consome uma superficie de assets relativamente clara: - -- `asset_table` no `manifest.json`; -- `assets.pa` como blob packed de bytes frios; -- `preload` opcional para residency inicial. - -Essa superficie esta descrita em `13-cartridge.md` e `15-asset-management.md`, mas ainda do ponto de vista do consumidor runtime. - -Falta fechar a fronteira do produtor de `assets.pa`. - -Para o repositorio, a nomenclatura precisa ficar explicita: - -- `shipper` monta o cart distribuivel e e responsavel pelo `.pmc`; -- `packer` empacota somente os assets e produz a superficie que alimenta `asset_table` + `assets.pa`; -- `compiler` e outros workers entram como dependencias do `shipper`, nao como substitutos do `packer`. - -Sem essa separacao, a discussao de `.pmc` tende a misturar container de distribuicao com contrato de bytes/metadata dos assets. - -## Problema - -O runtime conhece `assets.pa`, mas o projeto ainda nao decidiu qual e a facing do `packer` que produz esse artefato. - -Hoje nao esta fechado: - -- qual e a entrada canonica do packer; -- qual e a saida normativa alem do blob cru; -- como `asset_id`, `asset_name`, `offset`, `size`, `decoded_size`, `codec` e `metadata` devem ser gerados e validados; -- quais invariantes o runtime pode assumir sobre ordenacao, alinhamento, identidade e compatibilidade dos assets; -- o que pertence ao contrato do packer vs o que pertence ao `shipper`. - -Sem essa decisao: - -- `assets.pa` corre o risco de virar artefato acidental em vez de contrato; -- o `shipper` nao tem base normativa para montar `.pmc` de forma deterministica; -- specs de asset continuam descrevendo so consumo, nao producao; -- tooling pode introduzir heuristica local para ids, offsets, metadata e codecs. - -## Pontos Criticos - -### Fatos - -- o runtime atual consome `asset_table` + `assets.pa`, nao uma API do packer; -- `AssetEntry` hoje exige `asset_id`, `asset_name`, `bank_type`, `offset`, `size`, `decoded_size`, `codec` e `metadata`; -- o loader atual so carrega cart em formato de diretorio; `.pmc` ainda nao esta implementado; -- o runtime hoje aceita apenas `RAW` para `TILES` e `SOUNDS`; -- o decode atual depende de metadata especifica por bank: - - `TILES`: `tile_size`, `width`, `height`; - - `SOUNDS`: `sample_rate` opcional, com default. - -### Riscos - -- deixar `asset_id` ou ordenacao dependentes de detalhes de filesystem; -- acoplar o formato interno de `assets.pa` ao container `.pmc`; -- permitir metadata insuficiente ou ambigua e empurrar validacao para o runtime; -- introduzir codec/versionamento sem registry ou politica de compatibilidade; -- permitir que packer e shipper dupliquem responsabilidade sobre manifest e tabela de assets. - -### Tradeoffs - -- packer minimalista e simples agora vs contrato mais rigido e extensivel depois; -- `asset_id` derivado automaticamente vs declarado/estavel; -- blob puro com offsets vs envelope com header interno proprio; -- metadata livre em JSON vs schema normativo por `bank_type` e `codec`; -- validacao forte no packer vs tolerancia maior no runtime. - -### Hipoteses - -- o `shipper` deve tratar `asset_table` + `assets.pa` como output fechado do packer, sem reinterpretar layout interno; -- o packer deve produzir resultado deterministico para a mesma entrada; -- a compatibilidade futura de codecs fica melhor se a facing do packer declarar registry e schema desde o inicio. - -## Opcoes - -### Opcao 1 - Packer como gerador de blob opaco + tabela - -O packer recebe fontes de asset, decide ids/layout e entrega: - -- `assets.pa`; -- `asset_table`; -- eventualmente um relatorio de build nao normativo. - -Vantagens: - -- encaixa direto no runtime atual; -- separa bem packer de shipper; -- reduz trabalho inicial. - -Desvantagens: - -- pode esconder heuristicas importantes dentro do tooling; -- tende a deixar `asset_id` e metadata sem contrato claro. - -### Opcao 2 - Packer com manifest proprio normativo - -O packer recebe uma spec de entrada dedicada de assets e produz uma saida formal com: - -- `assets.pa`; -- `asset_table`; -- manifesto/intermediate proprio do packer. - -Vantagens: - -- deixa ownership editorial mais claro; -- facilita reproducibilidade e testes de golden output; -- prepara evolucao de codecs e validadores. - -Desvantagens: - -- aumenta escopo antes de fechar o minimo necessario; -- corre risco de criar artefato intermediario normativo demais cedo. - -### Opcao 3 - Packer como biblioteca interna do shipper - -O packer nao ganha fronteira propria; o shipper absorve a logica de assets e so expomos o contrato final do cart. - -Vantagens: - -- menos moving parts no curto prazo. - -Desvantagens: - -- conflita com a separacao conceitual desejada; -- embaralha discussao de `assets.pa` com `.pmc`; -- dificulta testes focados na superficie de assets. - -## Sugestao / Recomendacao - -Fechar o packer como produtor normativo de `asset_table` + `assets.pa`, com fronteira propria e independente do `shipper`. - -Recomendacao objetiva para avancar: - -1. O contrato do packer deve ser definido em torno da saida observavel consumida pelo runtime, nao em torno do `.pmc`. -2. O `shipper` deve consumir o output do packer como artefato fechado e so cuidar de empacotar o cart final. -3. O v1 do packer deve assumir: - - `assets.pa` como blob sequencial deterministico; - - `asset_table` como mapa normativo da segmentacao do blob; - - registry inicial de codecs/banks suportados pelo runtime atual; - - schema minimo de metadata por combinacao `bank_type` + `codec`. -4. A decisao precisa fixar explicitamente: - - estrategia de `asset_id`; - - ordenacao canonica dos assets no blob; - - regras de alinhamento, se existirem; - - politica para duplicatas de nome; - - responsabilidades de validacao entre packer e runtime. - -Essa direcao reduz ambiguidade sem antecipar o design completo do `shipper`. - -## Perguntas em Aberto - -1. Qual e a entrada canonica do packer: arquivos soltos, manifesto de assets, API de biblioteca, ou combinacao? -2. `asset_id` precisa ser estavel entre builds identicos e entre reorganizacoes de input? -3. O packer deve ordenar assets por declaracao, por nome, por bank, ou por politica explicita de layout? -4. `assets.pa` continua sendo blob puro sem header proprio ou o packer deve ter envelope/versionamento interno? -5. Qual e o schema normativo minimo de `metadata` por tipo de asset no v1? -6. O v1 deve aceitar so `RAW` ou ja reservar namespace/registry para codecs futuros? -7. Quem rejeita inconsistencias de `decoded_size`, metadata faltante e offset invalido: packer, shipper, runtime, ou todos em camadas diferentes? -8. Preload pertence ao dominio do packer, do shipper, ou apenas do cart manifest? - -## Criterio para Encerrar - -Esta agenda pode virar `decision` quando houver definicao escrita de: - -- fronteira formal entre `packer` e `shipper`; -- input e output canonicos do packer; -- contrato normativo de producao de `asset_table` e `assets.pa`; -- politica de identidade, ordenacao e layout dos assets no blob; -- schema minimo de metadata e registry inicial de codecs/banks; -- matriz de validacao e erro entre packer, shipper e runtime; -- estrategia de teste de compatibilidade entre output do packer e consumo do runtime. - -## Referencias - -- `../specs/13-cartridge.md` -- `../specs/15-asset-management.md` -- `008-packed-cartridge-loader-pmc.md` -- `../../crates/console/prometeu-hal/src/asset.rs` -- `../../crates/console/prometeu-drivers/src/asset.rs` diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index af975264..dd51c29d 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-packer-runtime-facing-contract.md` ## Sequenciamento Recomendado [PERF] @@ -57,10 +56,9 @@ Ordem sugerida para discussão e futura execução: 1. `012-vm-owned-random-service.md` 2. `014-app-home-filesystem-surface-and-semantics.md` 3. `007-runtime-edge-test-plan.md` -4. `023-asset-packer-runtime-facing-contract.md` -5. `008-packed-cartridge-loader-pmc.md` -6. `009-system-run-cart.md` -7. `010-system-fault-semantics-and-control-surface.md` +4. `008-packed-cartridge-loader-pmc.md` +5. `009-system-run-cart.md` +6. `010-system-fault-semantics-and-control-surface.md` Justificativa curta: @@ -69,12 +67,11 @@ Justificativa curta: - `013` foi fechada e absorvida por `spec 08` (historico em `learn/historical-game-memcard-slots-surface-and-semantics.md`). - `014` fecha o contrato de `home` para apps sem abrir FS global. - a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`). -- `023` separa o contrato de producao de `assets.pa` do contrato de shipping do `.pmc`. - a decisao `008` fixa o contrato status-first de `gfx`. - a decisao `009` fixa o contrato status-first de `audio`. - a decisao `010` fixa o contrato status-first de `asset`. - a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime. -- `008` depende de `023`, porque o `shipper` do `.pmc` nao deve decidir o contrato interno do packer de assets no meio da implementacao. +- `008` depende da decisao `011`, porque o `shipper` do `.pmc` nao deve decidir o contrato interno do packer de assets no meio da implementacao. - `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual. Dependências principais: @@ -82,8 +79,7 @@ Dependências principais: - `012` depende da decisao `006` e de `16`/`16a` - `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`) - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio -- `023` depende do contrato atual de `13-cartridge.md`/`15-asset-management.md` e deve cristalizar a superficie produtora de `asset_table` + `assets.pa` -- `008` depende de `023`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio +- `008` depende da decisao `011`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio - `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs` - `010` depende de `16a` e da `009` diff --git a/docs/runtime/decisions/011-assets-pa-autocontained-runtime-contract.md b/docs/runtime/decisions/011-assets-pa-autocontained-runtime-contract.md new file mode 100644 index 00000000..72a7b93e --- /dev/null +++ b/docs/runtime/decisions/011-assets-pa-autocontained-runtime-contract.md @@ -0,0 +1,253 @@ +# Decision Record - `assets.pa` Autocontained Runtime Contract + +## Status + +Accepted + +## Contexto + +A agenda `023-asset-packer-runtime-facing-contract.md` existia para fechar a fronteira runtime-facing do packer de assets sem misturar essa discussao com o `shipper` do `.pmc`. + +O ponto de partida atual do runtime ainda e fragmentado: + +- `manifest.json` carrega `asset_table` e `preload`; +- `assets.pa` contem apenas os bytes packed de payload; +- o loader le `assets.pa` inteiro para memoria; +- o `AssetManager` mantem esse blob inteiro residente. + +Ao mesmo tempo, a direcao desejada para o projeto ja esta clara: + +- o `packer` continua responsavel por produzir o artefato de assets; +- o `shipper` continua responsavel por publicar `manifest.json` e montar o cart final; +- o runtime deve consumir um `assets.pa` autocontido; +- `asset_table`, `preload` e payload mantem o mesmo conteudo semantico atual; +- o que muda e onde esses artefatos vivem e como o runtime os carrega. + +O alvo de hardware do PROMETEU e um handheld de baixo custo. Portanto, manter o blob inteiro de assets em RAM como regra geral nao e um baseline aceitavel. + +## Decisao + +### 1. `assets.pa` passa a ser o contrato runtime-facing de assets + +O contrato primario de assets consumido pelo runtime passa a ser o proprio `assets.pa`. + +`manifest.json` deixa de ser a superficie primaria para: + +- `asset_table`; +- `preload`. + +O runtime continua agnostico a como o `packer` e o `shipper` produzem artefatos auxiliares. + +### 2. `assets.pa` v1 e um binario autocontido + +`assets.pa` v1 deve ser estruturado como: + +```text +[prelude binario fixo] +[header JSON] +[payload binario] +``` + +O prelude binario fixo v1 contem, no minimo: + +- `magic` +- `schema_version` +- `header_len` +- `payload_offset` + +Campos opcionais permitidos no prelude v1: + +- `flags` +- `reserved` +- `header_checksum` + +### 3. O header JSON carrega `asset_table` e `preload` + +O header JSON de `assets.pa` e a estrutura que carrega: + +- `asset_table` +- `preload` + +Essa decisao nao redefine o conteudo semantico dessas estruturas. + +Portanto: + +- `AssetEntry` permanece a fonte de verdade para identidade, codec, metadata e offsets; +- `PreloadEntry` permanece um insumo de boot; +- o payload packed continua representando os bytes frios dos assets. + +### 4. Offsets da `asset_table` sao relativos ao payload + +Os `offset`s de `asset_table` permanecem relativos ao inicio da regiao de payload, nao ao inicio do arquivo inteiro. + +Isso preserva a semantica atual do runtime e evita contaminar `AssetEntry` com detalhes do envelope externo. + +O runtime resolve cada slice como: + +```text +payload_base + entry.offset +``` + +### 5. Lifecycle de `preload` e `asset_table` no runtime + +O runtime deve tratar essas duas estruturas de forma diferente: + +- `preload` e dado transitorio de boot; +- `asset_table` e a fonte da verdade para resolucao e carregamento de assets. + +Contrato operacional: + +1. o runtime materializa `manifest.json`; +2. se `Capability::Asset` estiver presente, o runtime exige `assets.pa` valido imediatamente; +3. o runtime abre `assets.pa`, le o prelude e o header JSON; +4. o runtime materializa `asset_table` em memoria; +5. o runtime usa `preload` na fase de boot; +6. apos o boot, `preload` pode ser descartado; +7. `asset_table` permanece viva enquanto o cart estiver rodando. + +### 6. Falha antecipada quando `Capability::Asset` exigir `assets.pa` + +Cart sem `assets.pa` continuam validos. + +Mas, se o `manifest.json` declarar `Capability::Asset`, a ausencia de `assets.pa` deve falhar o mais cedo possivel, antes da fase de preload. + +Essa falha pertence ao bootstrap do cart, nao ao lifecycle de `asset.load`. + +### 7. Leitura de payload deve ser sob demanda + +O runtime nao deve manter o payload inteiro de `assets.pa` residente em memoria como comportamento baseline. + +O contrato de leitura do runtime passa a ser baseado em uma primitiva equivalente a: + +```text +open_slice(offset, size) +``` + +Essa primitiva abre uma view limitada para um asset dentro da regiao de payload. + +### 8. Pipeline canonico de carregamento de asset + +O caminho canonico de carregamento passa a ser: + +```text +ROM -> open_slice -> CODEX/decode -> Bank +``` + +ou, quando o CODEX exigir materializacao temporaria: + +```text +ROM -> open_slice -> blob temporario em memoria -> CODEX/decode -> Bank +``` + +O runtime nunca deve materializar o `assets.pa` inteiro apenas para suportar carregamento de asset. + +### 9. `OP_MODE` de consumo do payload + +O runtime deve encapsular o modo operacional de consumo do payload por asset. + +Esse `OP_MODE` escolhe entre: + +- leitura direta da ROM via view limitada; +- materializacao temporaria do slice em memoria. + +Direcao v1: + +- o `OP_MODE` e derivado do `codec`/CODEX por padrao; +- hint explicito adicional so deve ser introduzido se algum codec real admitir mais de um modo operacional viavel. + +### 10. Artefatos auxiliares do packer continuam permitidos + +O `packer` pode continuar emitindo artefatos auxiliares para o `shipper`, por exemplo: + +- `asset_table.json`; +- relatorios de build; +- hashes; +- inventarios. + +Mas esses artefatos: + +- sao derivados; +- nao substituem o header interno de `assets.pa`; +- nao definem o contrato runtime-facing. + +## Rationale + +Esta decisao fecha a ambiguidade central da agenda `023` sem reabrir a semantica do dominio `asset`. + +Ela foi escolhida porque: + +- separa claramente `packer` e `shipper`; +- reduz dependencia de metadata de asset espalhada em `manifest.json`; +- preserva o shape semantico atual de `asset_table`, `preload` e payload; +- melhora a adequacao do runtime para hardware barato; +- evita carregar o blob inteiro em RAM; +- permite que codecs com diferentes necessidades de IO operem sobre a mesma fronteira de leitura. + +O uso de prelude binario pequeno + header JSON foi adotado porque: + +- permite localizar o header com custo fixo; +- mantem o header facil de produzir, inspecionar e depurar; +- evita transformar o payload em estrutura textual; +- reduz complexidade editorial no v1. + +## Invariantes / Contrato + +- `assets.pa` e o contrato runtime-facing de assets. +- `asset_table` e `preload` deixam de ser contrato primario de runtime no `manifest.json`. +- `asset_table` e carregada do header de `assets.pa` e permanece viva durante toda a execucao do cart. +- `preload` e carregado do header de `assets.pa`, usado no boot e descartavel apos a inicializacao. +- payload offsets em `AssetEntry` sao relativos ao inicio da regiao de payload. +- o runtime deve falhar cedo se `Capability::Asset` exigir `assets.pa` e o artefato nao existir. +- o runtime nao deve manter o `assets.pa` inteiro em RAM como baseline. +- o runtime deve expor leitura sob demanda por slice. +- `OP_MODE` de consumo do slice e resolvido pelo runtime a partir do `codec`/CODEX, salvo decisao futura em contrario. +- auxiliares do `packer` para o `shipper` nao tem autoridade normativa sobre o runtime. + +## Impactos + +### Specs + +- `13-cartridge.md` deve mover `asset_table` e `preload` para dentro do contrato de `assets.pa`. +- `15-asset-management.md` deve descrever `assets.pa` como artefato autocontido, separar lifecycle de `preload` e `asset_table`, e registrar offsets relativos ao payload. +- `16-host-abi-and-syscalls.md` so precisa ser tocada se a superficie host/runtime de inicializacao de assets mudar de forma observavel. + +### Runtime + +- `cartridge_loader.rs` deve deixar de ler `assets.pa` inteiro para `Vec` como baseline. +- `cartridge.rs` deve parar de tratar `asset_table` e `preload` como dados vindos do `manifest`. +- o bootstrap deve checar cedo a presenca de `assets.pa` quando `Capability::Asset` estiver declarada. +- o `AssetManager` deve manter `asset_table` viva, aplicar `preload` no boot e ler payload por slice sob demanda. +- a leitura atual baseada em `Arc>>` deve evoluir para uma origem de leitura por ROM/view/slice. + +### Shipper / Packer + +- o `packer` deve produzir `assets.pa` com prelude + header JSON + payload. +- o `shipper` continua livre para consumir auxiliares JSON, mas deve tratar `assets.pa` como artefato de verdade para assets. +- o `manifest.json` publicado pelo `shipper` deixa de carregar `asset_table` e `preload` como contrato primario de runtime. + +### Firmware / Boot + +- a etapa de carga do cart deve abrir `assets.pa`, extrair header e decidir falha cedo antes de preload. +- preload deixa de ser atributo editorial do manifest e passa a ser insumo interno do artefato de assets. + +## Referencias + +- `../specs/13-cartridge.md` +- `../specs/15-asset-management.md` +- `../agendas/008-packed-cartridge-loader-pmc.md` +- `../../../studio/docs/packer/Prometeu Packer.md` +- `../../crates/console/prometeu-hal/src/cartridge_loader.rs` +- `../../crates/console/prometeu-hal/src/cartridge.rs` +- `../../crates/console/prometeu-drivers/src/asset.rs` + +## Propagacao Necessaria + +- criar PR/plan para atualizar specs `13` e `15`; +- criar PR/plan de codigo para: + - mudar o loader de cart para abrir header de `assets.pa`; + - mover `asset_table`/`preload` para a leitura do binario de assets; + - introduzir leitura sob demanda por slice; + - remover o baseline de payload inteiro residente; + - falhar cedo quando `Capability::Asset` exigir `assets.pa` ausente; +- agenda `023-asset-packer-runtime-facing-contract.md` deve ser considerada fechada e removida da lista de agendas ativas; +- agenda `008-packed-cartridge-loader-pmc.md` passa a depender desta decisao como base do artefato de assets. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index e63c5629..8537069d 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -19,6 +19,7 @@ Decisoes ativas: - `003-vm-owned-byte-transfer-protocol.md` - `006-vm-owned-stateful-core-contract.md` - `007-filesystem-fault-core-policy.md` +- `011-assets-pa-autocontained-runtime-contract.md` Decisoes implementadas e aposentadas (migradas para `learn/`): diff --git a/docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md b/docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md new file mode 100644 index 00000000..16e7673a --- /dev/null +++ b/docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md @@ -0,0 +1,93 @@ +# PR - Assets.pa Autocontained Spec Propagation + +## Briefing + +A decisao `011-assets-pa-autocontained-runtime-contract.md` fechou o contrato arquitetural de `assets.pa` como artefato runtime-facing autocontido. + +Agora o runtime precisa publicar esse contrato em spec para que: + +- `../runtime` tenha base normativa consolidada; +- o `studio` possa evoluir o packer em paralelo sem depender de heuristica local; +- a PR de codigo implemente um contrato ja estabilizado. + +Esta PR e editorial/normativa. Ela nao rediscute a arquitetura da decisao `011`. + +## Decisions de Origem + +- `../decisions/011-assets-pa-autocontained-runtime-contract.md` + +## Alvo + +Propagar a decisao `011` para o corpus normativo do runtime, principalmente: + +- `../specs/13-cartridge.md` +- `../specs/15-asset-management.md` + +## Escopo + +- mover `asset_table` e `preload` para dentro do contrato de `assets.pa`; +- descrever `assets.pa` v1 como: + - prelude binario fixo; + - header JSON; + - payload binario; +- registrar prelude minimo: + - `magic` + - `schema_version` + - `header_len` + - `payload_offset` +- registrar opcionais permitidos: + - `flags` + - `reserved` + - `header_checksum` +- fixar que offsets de `AssetEntry` sao relativos ao inicio da regiao de payload; +- fixar lifecycle: + - `preload` so no boot; + - `asset_table` viva durante a execucao do cart; +- fixar leitura sob demanda por slice (`open_slice` como conceito normativo); +- fixar `OP_MODE` derivado de `codec`/CODEX no v1; +- fixar falha antecipada quando `Capability::Asset` exigir `assets.pa` ausente. + +## Fora de Escopo + +- alterar codigo do loader, firmware ou `AssetManager`; +- implementar `.pmc`; +- definir formato dos JSONs auxiliares do `shipper` alem de seu status nao normativo para runtime; +- introduzir novos codecs ou alterar o shape semantico de `AssetEntry` e `PreloadEntry`; +- escrever a spec do packer no `studio`. + +## Plano de Execucao + +1. Atualizar `13-cartridge.md` para: + - remover `asset_table` e `preload` como superficie primaria de runtime no manifest; + - descrever `assets.pa` como artefato autocontido; + - registrar a regra de falha antecipada ligada a `Capability::Asset`. +2. Atualizar `15-asset-management.md` para: + - descrever o envelope de `assets.pa`; + - distinguir lifecycle de `preload` e `asset_table`; + - registrar offsets relativos ao payload; + - registrar leitura sob demanda por slice; + - registrar `OP_MODE` por codec/CODEX. +3. Revisar cross-references entre `13`, `15` e `16`. +4. Garantir que a linguagem normativa deixe claro o que e contrato runtime-facing e o que e apenas helper para o `shipper`. + +## Criterios de Aceite + +- `13-cartridge.md` nao apresenta mais `asset_table` e `preload` como contrato primario do manifest consumido pelo runtime. +- `15-asset-management.md` descreve `assets.pa` como artefato autocontido com prelude, header e payload. +- a spec fixa offsets relativos ao payload, nao ao arquivo inteiro. +- a spec fixa que `preload` e dado transitorio de boot e `asset_table` permanece viva durante a execucao do cart. +- a spec fixa leitura sob demanda do payload, sem baseline de blob inteiro residente em RAM. +- a spec fixa falha antecipada quando `Capability::Asset` exigir `assets.pa` ausente. +- a linguagem publicada e suficiente para o Studio implementar o packer em paralelo sem depender do codigo do runtime. + +## Tests / Validacao + +- revisao editorial cruzada entre `13` e `15` para garantir ausencia de contradicao; +- revisao de consistencia com a decisao `011`; +- conferência de que a PR de codigo derivada consegue citar trechos normativos concretos sem reinterpretacao arquitetural. + +## Riscos + +- deixar resquicios do modelo antigo (`asset_table`/`preload` no manifest) em texto normativo; +- documentar `open_slice` e `OP_MODE` de forma vaga demais, prejudicando a implementacao; +- deixar lacuna suficiente para que o Studio reabra localmente a autoridade dos JSONs auxiliares. diff --git a/docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md b/docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md new file mode 100644 index 00000000..3f5938ed --- /dev/null +++ b/docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md @@ -0,0 +1,76 @@ +# PR - Assets.pa Bootstrap and Header Loading + +## Briefing + +A decisao `011-assets-pa-autocontained-runtime-contract.md` exige que o runtime deixe de depender de `asset_table` e `preload` no `manifest.json` e passe a materializar essas estruturas a partir do header de `assets.pa`. + +O primeiro passo de codigo deve atacar apenas bootstrap e carga de header, sem misturar isso com a mudanca maior de leitura sob demanda do payload. + +Esta PR existe para fechar cedo: + +- falha antecipada quando `Capability::Asset` exigir `assets.pa` ausente; +- parse do prelude binario e do header JSON; +- materializacao de `asset_table` e `preload` a partir de `assets.pa`. + +## Decisions de Origem + +- `../decisions/011-assets-pa-autocontained-runtime-contract.md` + +## Alvo + +Implementar o novo caminho de bootstrap e leitura do header de `assets.pa`. + +## Escopo + +- atualizar `cartridge_loader.rs` para reconhecer `assets.pa` como binario autocontido; +- introduzir parse do prelude binario fixo; +- introduzir parse do header JSON; +- remover dependencia primaria de `asset_table` e `preload` no `manifest.json`; +- atualizar `cartridge.rs` para refletir a nova origem da metadata; +- falhar cedo quando `Capability::Asset` estiver declarada e `assets.pa` estiver ausente; +- disponibilizar `asset_table`, `preload`, `payload_offset` e origem de `assets.pa` para as etapas seguintes do runtime. + +## Fora de Escopo + +- leitura sob demanda por slice; +- refactor do `AssetManager` para deixar de depender de blob inteiro; +- integracao de `OP_MODE` com CODEX; +- `.pmc`; +- novos codecs. + +## Plano de Execucao + +1. Implementar parsing do envelope: + - prelude binario; + - header JSON; + - payload base offset. +2. Atualizar o modelo `Cartridge` para parar de tratar `asset_table` e `preload` como dados vindos primariamente do manifest. +3. Alterar o bootstrap do cart para: + - materializar `manifest.json`; + - checar cedo `Capability::Asset` vs presenca de `assets.pa`; + - abrir `assets.pa`; + - carregar `asset_table` e `preload` do header. +4. Preservar compatibilidade do restante do runtime com a nova origem dos dados, sem ainda mexer na estrategia de payload. + +## Criterios de Aceite + +- `asset_table` e `preload` passam a vir do header de `assets.pa`. +- o runtime falha cedo quando `Capability::Asset` estiver presente e `assets.pa` estiver ausente. +- carts sem `Capability::Asset` continuam validos sem `assets.pa`. +- `manifest.json` deixa de ser a fonte primaria de `asset_table` e `preload`. +- o envelope de `assets.pa` e parseado de forma consistente com a decisao `011`. + +## Tests / Validacao + +- testes de loader para: + - `assets.pa` ausente com e sem `Capability::Asset`; + - prelude invalido; + - header JSON invalido; + - parse valido de `asset_table` e `preload`; +- testes de boot para garantir falha antecipada antes de preload quando o artefato exigido nao existir. + +## Riscos + +- deixar fallback implicito para metadata no `manifest.json`; +- falhar tarde demais na ausencia de `assets.pa`; +- acoplar parse do envelope a detalhes de filesystem antes de introduzir uma fonte de payload mais limpa. diff --git a/docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md b/docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md new file mode 100644 index 00000000..17b115f5 --- /dev/null +++ b/docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md @@ -0,0 +1,60 @@ +# PR - Assets.pa Payload Source and Open Slice + +## Briefing + +Depois que o bootstrap souber abrir `assets.pa` e materializar seu header, o runtime precisa parar de tratar o payload como `Vec` residente por padrao. + +Esta PR introduz a fronteira de leitura sob demanda do payload, sem ainda acoplar isso ao refactor completo do `AssetManager`. + +## Decisions de Origem + +- `../decisions/011-assets-pa-autocontained-runtime-contract.md` + +## Alvo + +Introduzir a origem de payload por slice e a primitiva equivalente a `open_slice(offset, size)`. + +## Escopo + +- introduzir uma abstracao de origem de payload para `assets.pa`; +- suportar abertura de slices limitados por offset relativo ao payload; +- preservar `payload_offset` resolvido no bootstrap; +- permitir leitura a partir de ROM/storage sem materializar o `assets.pa` inteiro; +- preparar a integracao posterior com `AssetManager` e CODEX. + +## Fora de Escopo + +- alterar semantica observavel de `asset.load/status/commit/cancel`; +- refatorar decode de `TILES` e `SOUNDS` para `OP_MODE` final; +- preload; +- `.pmc`; +- novos codecs. + +## Plano de Execucao + +1. Introduzir a abstracao de source/view do payload. +2. Implementar `open_slice(offset, size)` sobre offsets relativos ao payload. +3. Garantir que a camada proteja contra leitura fora da faixa do payload. +4. Conectar bootstrap e modelo `Cartridge` a essa nova origem de payload. + +## Criterios de Aceite + +- o runtime possui uma abstracao explicita para abrir slices do payload. +- `open_slice` resolve offsets relativos ao payload, nao ao arquivo inteiro. +- o payload inteiro nao precisa ser carregado em RAM para o runtime operar. +- a nova abstracao e suficiente para alimentar o refactor do `AssetManager` na PR seguinte. + +## Tests / Validacao + +- testes unitarios de `open_slice` para: + - offset valido; + - offset fora da faixa; + - size fora da faixa; + - slice no fim do payload; +- testes de integracao minima garantindo que o bootstrap entrega uma origem de payload funcional. + +## Riscos + +- escolher uma abstracao acoplada demais ao filesystem local; +- introduzir API de source/view insuficiente para codecs futuros; +- vazar detalhe de offset absoluto para camadas superiores. diff --git a/docs/runtime/pull-requests/PR-011d-asset-manager-on-demand-payload-and-op-mode.md b/docs/runtime/pull-requests/PR-011d-asset-manager-on-demand-payload-and-op-mode.md new file mode 100644 index 00000000..bba5fac8 --- /dev/null +++ b/docs/runtime/pull-requests/PR-011d-asset-manager-on-demand-payload-and-op-mode.md @@ -0,0 +1,70 @@ +# PR - Asset Manager On-Demand Payload and OP_MODE + +## Briefing + +Com bootstrap e `open_slice` ja estabilizados, o `AssetManager` pode ser migrado do modelo atual baseado em blob inteiro residente para o modelo decidido na `011`: + +- `asset_table` viva durante toda a execucao; +- `preload` apenas no boot; +- payload lido sob demanda; +- pipeline `ROM -> open_slice -> CODEX/decode -> Bank` ou `ROM -> open_slice -> blob temporario -> CODEX/decode -> Bank`. + +Esta PR implementa a mudanca de comportamento interno do `AssetManager` sem reabrir o envelope de `assets.pa`. + +## Decisions de Origem + +- `../decisions/011-assets-pa-autocontained-runtime-contract.md` + +## Alvo + +Refatorar o `AssetManager` para consumir payload sob demanda e encapsular `OP_MODE` por codec/CODEX. + +## Escopo + +- remover o baseline de `Arc>>` para payload inteiro residente; +- fazer `AssetManager` depender de `asset_table` viva + origem de payload por slice; +- tratar `preload` apenas na inicializacao; +- encapsular `OP_MODE` por codec/CODEX; +- suportar: + - leitura direta da ROM via slice; + - materializacao temporaria em memoria quando o codec exigir; +- preservar a superficie observavel do dominio `asset`. + +## Fora de Escopo + +- redefinir envelope de `assets.pa`; +- `.pmc`; +- novos codecs; +- rediscutir a policy de `asset` syscall status-first. + +## Plano de Execucao + +1. Substituir `assets_data` por origem de payload em slices. +2. Adaptar preload para usar a nova origem de payload apenas durante o boot. +3. Adaptar `load()` e o caminho assíncrono para consumir slices sob demanda. +4. Introduzir `OP_MODE` derivado de `codec`/CODEX. +5. Garantir que o resultado continue indo para staging/resident/bank como hoje. + +## Criterios de Aceite + +- `AssetManager` nao depende mais de payload inteiro residente em RAM. +- preload usa a nova origem de payload e nao permanece vivo depois do boot. +- `asset_table` continua sendo a fonte da verdade para resolucao de asset. +- `asset.load/status/commit/cancel` preservam a superficie observavel atual. +- o pipeline para decode/bank suporta leitura direta ou blob temporario conforme o `OP_MODE`. + +## Tests / Validacao + +- testes de `AssetManager` para: + - preload no boot; + - leitura por offsets relativos ao payload; + - ausencia de dependencia em blob inteiro residente; + - path de leitura direta; + - path de blob temporario; +- smoke tests de `asset.load/status/commit/cancel` para garantir ausencia de regressao observavel. + +## Riscos + +- regressao de preload ao trocar a origem do payload; +- encapsulamento ruim entre source/view, codec e bank; +- reintroduzir copia excessiva por atalho local no caminho assíncrono. diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index b4b19f41..94a4a264 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -37,3 +37,16 @@ Uma PR deste diretório deve: ## Roadmap Publicado PRs propostas para execucao da rodada atual: + +- `PR-011a-assets-pa-autocontained-spec-propagation.md` + - origem: decisao `011-assets-pa-autocontained-runtime-contract.md` + - alvo: consolidar o contrato runtime-facing em `spec 13` e `spec 15` +- `PR-011b-assets-pa-bootstrap-and-header-loading.md` + - origem: decisao `011-assets-pa-autocontained-runtime-contract.md` + - alvo: implementar bootstrap, parse do header e falha antecipada por capability +- `PR-011c-assets-pa-payload-source-and-open-slice.md` + - origem: decisao `011-assets-pa-autocontained-runtime-contract.md` + - alvo: introduzir a origem de payload e `open_slice` +- `PR-011d-asset-manager-on-demand-payload-and-op-mode.md` + - origem: decisao `011-assets-pa-autocontained-runtime-contract.md` + - alvo: migrar o `AssetManager` para payload sob demanda e `OP_MODE`