From f3f689fbef3de098965668efb2cb7ae5aa81a4de Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 06:57:10 +0000 Subject: [PATCH] clean up --- ...ssets-pa-autocontained-spec-propagation.md | 93 ------------------- ...-assets-pa-bootstrap-and-header-loading.md | 76 --------------- ...assets-pa-payload-source-and-open-slice.md | 60 ------------ ...t-manager-on-demand-payload-and-op-mode.md | 70 -------------- docs/runtime/pull-requests/README.md | 12 --- 5 files changed, 311 deletions(-) delete mode 100644 docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md delete mode 100644 docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md delete mode 100644 docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md delete mode 100644 docs/runtime/pull-requests/PR-011d-asset-manager-on-demand-payload-and-op-mode.md 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 deleted file mode 100644 index 16e7673a..00000000 --- a/docs/runtime/pull-requests/PR-011a-assets-pa-autocontained-spec-propagation.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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 deleted file mode 100644 index 3f5938ed..00000000 --- a/docs/runtime/pull-requests/PR-011b-assets-pa-bootstrap-and-header-loading.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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 deleted file mode 100644 index 17b115f5..00000000 --- a/docs/runtime/pull-requests/PR-011c-assets-pa-payload-source-and-open-slice.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 deleted file mode 100644 index bba5fac8..00000000 --- a/docs/runtime/pull-requests/PR-011d-asset-manager-on-demand-payload-and-op-mode.md +++ /dev/null @@ -1,70 +0,0 @@ -# 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 94a4a264..17ade7f7 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -38,15 +38,3 @@ Uma PR deste diretório deve: 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`