added asset loading PRs

docs/runtime/agendas/023-asset-packer-runtime-facing-contract.md

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

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`
+4. `008-packed-cartridge-loader-pmc.md`
-5. `008-packed-cartridge-loader-pmc.md`
+5. `009-system-run-cart.md`
-6. `009-system-run-cart.md`
+6. `010-system-fault-semantics-and-control-surface.md`
-7. `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 da decisao `011`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio
-- `008` depende de `023`, 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`
 

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<u8>` 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<RwLock<Vec<u8>>>` 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.

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

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.

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.

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<u8>` 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.

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<RwLock<Vec<u8>>>` 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.

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`