From c7e4d7398fc0e897b59dd67be1510b0449e6b9e1 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 23 Mar 2026 00:03:46 +0000 Subject: [PATCH] loader protocol: remove entrypoint --- ...entrypoint-removal-and-runtime-protocol.md | 144 ------------------ docs/runtime/agendas/README.md | 4 - ...entrypoint-removal-and-runtime-protocol.md | 104 ------------- docs/runtime/decisions/README.md | 7 - docs/runtime/learn/README.md | 1 + ...ge-boot-protocol-and-manifest-authority.md | 88 +++++++++++ ...ge-entrypoint-removal-and-boot-protocol.md | 60 -------- ...t-removal-and-boot-protocol-propagation.md | 67 -------- docs/runtime/pull-requests/README.md | 2 - 9 files changed, 89 insertions(+), 388 deletions(-) delete mode 100644 docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md delete mode 100644 docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md create mode 100644 docs/runtime/learn/historical-cartridge-boot-protocol-and-manifest-authority.md delete mode 100644 docs/runtime/pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md delete mode 100644 docs/runtime/pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md diff --git a/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md b/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md deleted file mode 100644 index 32e7f534..00000000 --- a/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md +++ /dev/null @@ -1,144 +0,0 @@ -# 025-cartridge-manifest-entrypoint-removal-and-runtime-protocol - -Status: Closed -Domain Owner: `runtime` -Cross-Domain Impact: `compiler/PBS`, `firmware`, `loader`, `VM`, `spec 13` -Resolution: materialized as [`../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) - -## Contexto - -O runtime atual ainda modela `entrypoint` como metadado autoritativo vindo de `manifest.json`. - -Esse contrato aparece hoje em mais de uma camada: - -- `CartridgeManifest.entrypoint`; -- `CartridgeDTO.entrypoint`; -- `Cartridge.entrypoint`; -- `VirtualMachineRuntime::initialize_vm(...)`, que repassa esse valor para a VM; -- `VirtualMachine::initialize(program_bytes, entrypoint)`, que resolve boot por string nominal, índice numérico ou fallback implícito para a primeira função; -- `VirtualMachine::prepare_call(entrypoint)`, que também aceita string nominal ou índice e cai em `0` como fallback local. - -Ao mesmo tempo, a direção nova do compiler/PBS é diferente: - -- o compiler publica um wrapper sintético como entrypoint físico do artefato; -- esse wrapper deve ocupar o índice físico `0`; -- o boot deixa de ser escolha configurável em manifesto e passa a ser protocolo fixo do executável. - -Isso cria conflito direto entre o contrato atual do runtime e a direção desejada do artefato compilado. - -Além disso, a spec vigente ainda normatiza `entrypoint` como campo obrigatório em [`13-cartridge.md`](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/runtime/specs/13-cartridge.md). - -## Problema - -Precisamos decidir se o runtime deve remover `entrypoint` do contrato do cartucho e endurecer o boot para um protocolo fixo em que a função inicial válida é sempre `func_id = 0`. - -O ponto principal nao e apenas remover um campo JSON. - -A agenda precisa fechar quem tem autoridade sobre o boot do cartucho: - -- se o manifesto continua escolhendo callable inicial; -- ou se o artefato compilado passa a carregar esse contrato de forma estrutural e obrigatoria. - -## Pontos Criticos - -### Fatos observados - -- o loader de diretorio hoje falha sem `manifest.json`, mas nao valida nenhum protocolo de boot alem de desserializar `entrypoint`; -- a VM aceita tres formas de boot no init: string vazia, indice numerico textual e nome de export; -- `prepare_call()` tem fallback local para `0`, o que mantem comportamento implicito mesmo fora do boot inicial; -- o runtime system ainda rastreia `current_entrypoint`, reforcando que a escolha de callable continua exposta como estado; -- a spec atual do cartucho ainda descreve `entrypoint` como obrigatorio. - -### Riscos - -- manter `entrypoint` no manifesto preserva autoridade duplicada entre runtime e compiler; -- aceitar nome de export, indice textual e fallback vazio enfraquece determinismo e piora observabilidade de erro; -- deixar compatibilidade transitoria mal definida cria zona cinzenta entre cartucho legado e protocolo novo; -- endurecer o protocolo sem erro canonico claro pode produzir falhas opacas de bootstrap. - -### Tradeoffs - -- remover `entrypoint` simplifica o contrato e centraliza a autoridade no artefato, mas exige propagacao coordenada em spec, loader, system e VM; -- manter compatibilidade temporaria reduz friccao de migracao, mas prolonga um contrato que ja ficou estruturalmente errado; -- rejeitar manifestos legados cedo reduz ambiguidade, mas pode bloquear artefatos intermediarios durante a virada de pipeline. - -### Hipoteses que precisam ser assumidas explicitamente - -- o compiler/PBS realmente consegue garantir `func_id = 0` como wrapper fisico estavel do programa publicado; -- exports nominais continuam existindo para linking, debug ou introspection, mas deixam de participar da autoridade de boot; -- o runtime nao precisa mais expor escolha textual de entrypoint depois da migracao. - -## Opcoes - -### Opcao A - Manter `entrypoint` no manifesto como autoridade de boot - -O runtime continua lendo `manifest.json` e escolhendo o callable inicial por string ou indice textual. - -Consequencia: - -- preserva o modelo atual; -- continua divergindo da direcao do compiler; -- mantem duplicidade de autoridade e superficie de erro desnecessaria. - -### Opcao B - Remover `entrypoint` do manifesto e migrar o boot para protocolo fixo em `func_id = 0` - -O loader deixa de carregar `entrypoint`, a VM endurece o init para boot protocolar e o runtime deixa de rastrear entrypoint textual como parte do contrato. - -Consequencia: - -- o artefato compilado vira a unica autoridade de boot; -- o manifesto volta a ser metadata de pacote, nao controle de execucao; -- exige plano de transicao explicito para cartuchos legados. - -### Opcao C - Manter `entrypoint` apenas como compatibilidade, mas ignorar no runtime novo - -O manifesto antigo continua aceito por algum tempo, porem `entrypoint` vira campo sem efeito operacional. - -Consequencia: - -- reduz quebra imediata; -- mas preserva ambiguidade documental e risco de produtores continuarem emitindo dado morto. - -## Sugestao / Recomendacao - -Adotar `Opcao B`, sem compatibilidade transitoria normativa no runtime. - -Direcao recomendada: - -1. o contrato final do cartucho remove `entrypoint` de `manifest.json`; -2. o boot do programa passa a ser sempre protocolar em `func_id = 0`; -3. `CartridgeManifest`, `CartridgeDTO` e `Cartridge` deixam de carregar `entrypoint`; -4. `VirtualMachine::initialize(...)` deve endurecer para init sem parametro textual de entrypoint; -5. `VirtualMachineRuntime` deixa de rastrear `current_entrypoint` como estado de boot; -6. exports nominais continuam permitidos para linking/introspection, mas deixam de participar do boot; -7. cartucho que nao oferecer funcao valida em `0` deve falhar com erro canonico de inicializacao, sem fallback implicito para outra funcao. - -Compatibilidade recomendada: - -- o runtime nao deve manter compatibilidade para cartuchos legados baseados em `entrypoint`; -- a unica excecao pratica do ciclo atual e manter o stress test rodando ate a propagacao correspondente no gerador; -- essa excecao nao muda o contrato final e nao deve virar regra normativa de runtime. - -## Perguntas Resolvidas - -1. Compatibilidade transitoria: - nao deve existir no runtime como contrato. A migracao deve ser feita no producer pipeline. A excecao pragmatica do ciclo e apenas nao quebrar o stress test antes da propagacao do gerador correspondente. - -2. Erro canonico: - a falha de boot protocolar em `func_id = 0` deve reutilizar `VmInitError::EntrypointNotFound`, agora com semantica endurecida para "entrypoint protocolar ausente ou invalido". - -3. `prepare_call()`: - o endurecimento obrigatorio desta agenda cobre o boot do cartucho. A eventual permanencia ou remocao de exports nominais em `prepare_call()` para chamadas nao relacionadas a boot fica fora do fechamento arquitetural desta agenda e pode ser tratada em ciclo separado, desde que nao preserve autoridade textual de boot. - -4. Dependencia de `current_entrypoint`: - o codigo atual nao revela dependencia host/debug relevante alem do proprio caminho de boot do runtime. O estado existe hoje para alimentar `vm.prepare_call(&self.current_entrypoint)` e para testes associados, nao como contrato externo autonomo. - -## Criterio para Encerrar - -Esta agenda ja possui definicao suficiente para virar `decision`, com os seguintes pontos fechados: - -- contrato final de `manifest.json` sem `entrypoint`; -- ausencia de compatibilidade normativa no runtime para cartuchos legados; -- contrato da VM e do runtime para boot fixo em `func_id = 0`; -- reutilizacao de `VmInitError::EntrypointNotFound` como erro canonico; -- e propagacao minima esperada para `spec 13`, loader, system, VM e testes. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index c72f8fd7..670dc7d3 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -25,10 +25,6 @@ As agendas atuais são: - `021-perf-vm-allocation-and-copy-pressure.md` - `022-perf-cartridge-boot-and-program-ownership.md` - `024-asset-entry-metadata-normalization-contract.md` - -Agendas encerradas recentemente: - -- `025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md` -> `../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md` ## Sequenciamento Recomendado [PERF] Ordem sugerida para discussao das agendas de performance: diff --git a/docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md b/docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md deleted file mode 100644 index ef28bac7..00000000 --- a/docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md +++ /dev/null @@ -1,104 +0,0 @@ -# 025-cartridge-manifest-entrypoint-removal-and-runtime-protocol - -Status: Implemented -Date: 2026-03-22 -Origin: [`../agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) -Implementation: -- spec propagation: [`../pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md`](../pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md), commit `e2f0904` -- runtime propagation: [`../pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md`](../pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md), commit `a30ac16` - -## Contexto - -O runtime atual ainda modela `entrypoint` como dado autoritativo vindo de `manifest.json`. - -Esse acoplamento aparece em varias camadas: - -- `CartridgeManifest.entrypoint`; -- `CartridgeDTO.entrypoint`; -- `Cartridge.entrypoint`; -- `VirtualMachineRuntime::initialize_vm(...)`, que repassa esse valor para a VM; -- `VirtualMachine::initialize(program_bytes, entrypoint)`, que aceita string nominal, indice numerico textual ou fallback implicito; -- `VirtualMachine::prepare_call(entrypoint)`, que tambem aceita entrada textual e preserva fallback local para `0`. - -Ao mesmo tempo, a direcao consolidada do compiler/PBS e publicar um wrapper sintetico no indice fisico `0`, transformando o boot em protocolo do artefato executavel, e nao em escolha configuravel de manifesto. - -A spec vigente ainda conflita com essa direcao, porque [`13-cartridge.md`](../specs/13-cartridge.md) descreve `entrypoint` como campo obrigatorio do cartucho. - -## Decisao - -O runtime passa a adotar boot protocolar fixo em `func_id = 0` e deixa de tratar `entrypoint` como parte do contrato do cartucho. - -Isso implica: - -- `entrypoint` sai do contrato final de `manifest.json`; -- `CartridgeManifest`, `CartridgeDTO` e `Cartridge` deixam de carregar `entrypoint`; -- `VirtualMachine::initialize(...)` deve endurecer para inicializacao sem parametro textual de entrypoint; -- `VirtualMachineRuntime` deixa de rastrear `current_entrypoint` como estado de boot; -- exports nominais podem continuar existindo para linking e introspection, mas deixam de ter autoridade sobre boot; -- cartucho sem funcao valida em `func_id = 0` falha na inicializacao. - -## Rationale - -Esta decisao elimina autoridade duplicada entre compiler e runtime sobre qual callable inicia o programa. - -Ela tambem remove tres fontes de ambiguidade operacional: - -- escolha textual por export; -- escolha textual por indice; -- fallback implicito para primeira funcao. - -Com o boot fixado no proprio artefato compilado, `manifest.json` volta a ser metadata de pacote e deixa de controlar execucao. Isso reduz superficie de erro, melhora determinismo e alinha runtime, compiler e spec em um contrato unico. - -## Invariantes / Contrato - -- o contrato final do cartucho nao inclui `entrypoint` em `manifest.json`; -- o boot do cartucho ocorre sempre em `func_id = 0`; -- o runtime nao deve manter compatibilidade normativa para cartuchos legados baseados em `entrypoint`; -- a unica excecao pragmatica do ciclo atual e nao quebrar o stress test antes da propagacao do gerador correspondente; -- essa excecao nao altera o contrato final e nao deve virar regra normativa do runtime; -- falha de boot protocolar em `func_id = 0` reutiliza `VmInitError::EntrypointNotFound`, agora com semantica endurecida para "entrypoint protocolar ausente ou invalido"; -- `prepare_call()` nao deve preservar autoridade textual de boot; qualquer decisao adicional sobre aceitar exports nominais para chamadas nao relacionadas a boot fica fora desta decision. - -## Impactos - -### Specs - -- atualizar [`13-cartridge.md`](../specs/13-cartridge.md) para remover `entrypoint` como campo requerido; -- registrar em spec que boot do cartucho e protocolar em `func_id = 0`; -- alinhar referencias em firmware/boot specs se hoje assumirem metadado textual de entrypoint. - -### Runtime / Loader - -- remover `entrypoint` de `CartridgeManifest`, `CartridgeDTO` e `Cartridge`; -- parar de propagar `entrypoint` no loader; -- endurecer `VirtualMachine::initialize(...)` para init protocolar; -- remover `current_entrypoint` do runtime system e do caminho de boot associado. - -### Tooling / Producer Pipeline - -- compiler/PBS e geradores relacionados devem publicar wrapper sintetico em `func_id = 0`; -- o stress test pode manter tratamento excepcional temporario apenas ate a propagacao do gerador correspondente. - -### Testes - -- atualizar testes de loader, runtime system e VM init para o contrato sem `entrypoint`; -- cobrir falha canonica quando `func_id = 0` estiver ausente ou invalido; -- ajustar o stress test para o novo protocolo assim que o gerador for propagado. - -## Referencias - -- [`../agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) -- [`../specs/13-cartridge.md`](../specs/13-cartridge.md) -- [`../specs/12-firmware-pos-and-prometeuhub.md`](../specs/12-firmware-pos-and-prometeuhub.md) -- [`../specs/14-boot-profiles.md`](../specs/14-boot-profiles.md) - -## Propagacao Necessaria - -Concluida neste ciclo: - -- PR `025` publicou o contrato normativo sem `entrypoint` e com boot em `func_id = 0`; -- PR `026` removeu `entrypoint` de loader/system/VM e ajustou testes e stress tooling local. - -Follow-up residual: - -- consolidar este modelo em `learn` se ele for agrupado com outras decisoes de cartridge/boot. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 3a45fe58..e3f3c992 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -18,13 +18,6 @@ Decisoes ativas: Nenhuma no momento. -Decisoes implementadas: - -- `025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md` - - origem: `../agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md` - - foco: remover `entrypoint` do contrato do cartucho e endurecer o boot em `func_id = 0`. - - execucao: PR `025` + PR `026` - Decisoes implementadas e aposentadas (migradas para `learn/`): - `historical-vm-core-and-assets.md` diff --git a/docs/runtime/learn/README.md b/docs/runtime/learn/README.md index dc84c29b..41bb32ef 100644 --- a/docs/runtime/learn/README.md +++ b/docs/runtime/learn/README.md @@ -43,6 +43,7 @@ These files preserve the rationale of decisions already absorbed by specs and/or - [`historical-gfx-status-first-fault-and-return-contract.md`](historical-gfx-status-first-fault-and-return-contract.md) - [`historical-audio-status-first-fault-and-return-contract.md`](historical-audio-status-first-fault-and-return-contract.md) - [`historical-asset-status-first-fault-and-return-contract.md`](historical-asset-status-first-fault-and-return-contract.md) +- [`historical-cartridge-boot-protocol-and-manifest-authority.md`](historical-cartridge-boot-protocol-and-manifest-authority.md) - [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md) - [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md) diff --git a/docs/runtime/learn/historical-cartridge-boot-protocol-and-manifest-authority.md b/docs/runtime/learn/historical-cartridge-boot-protocol-and-manifest-authority.md new file mode 100644 index 00000000..1ed5f1ce --- /dev/null +++ b/docs/runtime/learn/historical-cartridge-boot-protocol-and-manifest-authority.md @@ -0,0 +1,88 @@ +# Historical Cartridge Boot Protocol and Manifest Authority + +Status: pedagogical / historical +Normative anchors: +- [`../specs/13-cartridge.md`](../specs/13-cartridge.md) +- [`../specs/12-firmware-pos-and-prometeuhub.md`](../specs/12-firmware-pos-and-prometeuhub.md) +- [`../specs/14-boot-profiles.md`](../specs/14-boot-profiles.md) + +This document records the historical rationale behind removing `entrypoint` from the cartridge manifest and moving cartridge boot authority into the executable artifact itself. + +It is not a normative contract. The current contract lives in the specs above. + +## Core Shift + +The older runtime model treated `entrypoint` as cartridge metadata: + +- `manifest.json` declared the callable to run; +- loader and cartridge DTOs propagated that string; +- VM initialization accepted textual resolution; +- runtime state tracked the current entrypoint as if boot authority were part of runtime metadata. + +The newer model treats boot as executable protocol: + +- the cartridge artifact itself defines the physical boot target; +- the executable entrypoint is always `func_id = 0`; +- firmware selects the cartridge, but not the callable inside it; +- nominal exports may still exist, but they do not decide boot. + +## Why The Old Model Was Weak + +The manifest-driven model created duplicate authority between compiler and runtime. + +That duplication had three concrete effects: + +- it let the manifest override what should have been fixed by the compiled artifact; +- it mixed symbolic, numeric, and fallback boot paths in the VM; +- it made boot failures less deterministic and less explainable. + +In practice, the machine was carrying too much flexibility at the exact boundary where it needed a single source of truth. + +## Why `func_id = 0` Became The Right Boundary + +Boot is not user-facing metadata. It is part of executable structure. + +By fixing boot at `func_id = 0`, the machine gets: + +- one authority for startup; +- a simpler cartridge manifest; +- a more deterministic VM initialization path; +- clearer failure semantics when the artifact is malformed. + +This also keeps the cartridge manifest focused on package metadata such as identity, version, mode, and capabilities, instead of turning it into an execution control surface. + +## What Stayed Flexible + +This change did not ban nominal exports from the bytecode image. + +Exports still make sense for: + +- linking; +- introspection; +- debug-oriented naming. + +What changed is narrower and more important: + +- exports are no longer boot authority. + +## Runtime Consequence + +Once boot became protocol-driven, the runtime was simplified: + +- `entrypoint` disappeared from cartridge manifest and loader types; +- VM initialization stopped accepting textual boot resolution; +- runtime state no longer needed to track `current_entrypoint` for cartridge startup; +- the stress cartridge generator was updated to emit the new manifest shape. + +The canonical initialization failure remained `VmInitError::EntrypointNotFound`, but its meaning hardened to "protocol boot target is absent or invalid". + +## Historical Trace + +This model was closed through the historical pipeline: + +- agenda `025` +- decision `025` +- PR `025` for spec propagation +- PR `026` for runtime propagation + +Those working artifacts were intentionally pruned after implementation so that `agendas/`, `decisions/`, and `pull-requests/` remain focused on live work. diff --git a/docs/runtime/pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md b/docs/runtime/pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md deleted file mode 100644 index 263dce2e..00000000 --- a/docs/runtime/pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md +++ /dev/null @@ -1,60 +0,0 @@ -# 025-spec-cartridge-entrypoint-removal-and-boot-protocol - -Status: Completed -Decision: [`../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) -Commit: `e2f0904` - -## Briefing - -Propagar a [`decision 025`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) para o contrato normativo de cartridge, removendo `entrypoint` de `manifest.json` e publicando boot fixo em `func_id = 0`. - -Esta PR e editorial e normativa. Ela existe para fechar o contrato antes ou em paralelo a qualquer remocao de codigo, evitando dividir runtime e spec sobre a mesma autoridade de boot. - -## Decisions de Origem - -- [`025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) - -## Alvo - -Atualizar as specs que ainda descrevem `entrypoint` como parte do contrato do cartucho, com foco principal em [`../specs/13-cartridge.md`](../specs/13-cartridge.md). - -## Escopo - -- remover `entrypoint` do exemplo de `manifest.json`; -- remover `entrypoint` da lista de campos requeridos do cartucho; -- publicar explicitamente que o boot do cartucho e protocolar em `func_id = 0`; -- esclarecer que exports nominais nao exercem autoridade de boot; -- alinhar referencias em specs adjacentes caso ainda impliquem boot orientado por metadata textual. - -## Fora de Escopo - -- implementar a remocao em loader, system ou VM; -- discutir estrategia de compatibilidade em runtime; -- redefinir semantica de exports nominais fora do boot; -- qualquer redesign mais amplo de `manifest.json`. - -## Plano de Execucao - -1. Atualizar [`../specs/13-cartridge.md`](../specs/13-cartridge.md) para remover `entrypoint` do contrato normativo. -2. Incluir secao ou texto normativo explicitando que o entrypoint executavel do cartucho e sempre `func_id = 0`. -3. Revisar [`../specs/12-firmware-pos-and-prometeuhub.md`](../specs/12-firmware-pos-and-prometeuhub.md) e [`../specs/14-boot-profiles.md`](../specs/14-boot-profiles.md) para garantir que o fluxo de boot nao sugira metadado textual de entrypoint. -4. Validar consistencia editorial entre decision e spec final. - -## Criterios de Aceite - -- nenhuma spec normativa ativa descreve `entrypoint` como campo requerido de `manifest.json`; -- [`../specs/13-cartridge.md`](../specs/13-cartridge.md) afirma sem ambiguidade que o boot do cartucho ocorre em `func_id = 0`; -- as specs nao deixam espaco para interpretar exports nominais como autoridade de boot; -- a PR nao reabre a discussao arquitetural ja fechada na decision. - -## Tests / Validacao - -- revisao editorial cruzada entre [`../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) e as specs afetadas; -- busca textual por `entrypoint` nas specs para confirmar remocao do contrato antigo; -- validacao manual de coerencia entre exemplos JSON e listas de campos requeridos. - -## Riscos - -- remover `entrypoint` da spec sem linguagem normativa suficientemente explicita sobre `func_id = 0` pode deixar lacuna contratual; -- editar apenas `spec 13` e esquecer referencias em firmware/boot pode preservar ambiguidade documental; -- misturar guidance transitoria de tooling com texto normativo de runtime pode enfraquecer o contrato final. diff --git a/docs/runtime/pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md b/docs/runtime/pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md deleted file mode 100644 index b139f50e..00000000 --- a/docs/runtime/pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md +++ /dev/null @@ -1,67 +0,0 @@ -# 026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation - -Status: Completed -Decision: [`../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) -Commit: `a30ac16` - -## Briefing - -Executar a propagacao de codigo da [`decision 025`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) no runtime, removendo `entrypoint` do loader e do estado de cartridge, endurecendo o boot da VM em `func_id = 0` e ajustando testes e tooling local necessario para manter o stress path funcional. - -Esta PR assume que a discussao arquitetural e o contrato normativo ja estao fechados. Nao e lugar para rediscutir authority de boot. - -## Decisions de Origem - -- [`025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`](../decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md) - -## Alvo - -Propagar o protocolo de boot fixo em `func_id = 0` para `prometeu-hal`, `prometeu-system`, `prometeu-vm` e tooling local afetado nesta workspace. - -## Escopo - -- remover `entrypoint` de `CartridgeManifest`, `CartridgeDTO` e `Cartridge`; -- parar de desserializar e propagar `entrypoint` no loader; -- endurecer `VirtualMachine::initialize(...)` para boot protocolar sem parametro textual; -- remover `current_entrypoint` e o uso correspondente no boot do runtime system; -- atualizar testes de loader, runtime system e VM init para o novo contrato; -- ajustar o stress tooling local necessario para continuar emitindo artefato compativel com `func_id = 0`. - -## Fora de Escopo - -- redesign geral de `prepare_call()` para chamadas nao relacionadas a boot; -- compatibilidade normativa para cartuchos legados baseados em `entrypoint`; -- mudancas amplas no compiler/PBS fora desta workspace; -- qualquer reabertura da decisao sobre erro canonico ou autoridade de boot. - -## Plano de Execucao - -1. Remover `entrypoint` dos tipos de cartridge em `prometeu-hal` e atualizar o loader. -2. Endurecer `VirtualMachine::initialize(...)` para carregar o programa e resolver boot exclusivamente em `func_id = 0`, reutilizando `VmInitError::EntrypointNotFound` quando o protocolo falhar. -3. Remover `current_entrypoint` do runtime system e ajustar o caminho de `tick()` para preparar a chamada de entrada sem dependencia textual. -4. Atualizar testes afetados em `prometeu-hal`, `prometeu-system` e `prometeu-vm`. -5. Ajustar `crates/tools/pbxgen-stress` ou fixture equivalente para nao depender mais de `entrypoint` em `manifest.json`. -6. Rodar a bateria de testes proporcional ao risco da mudanca. - -## Criterios de Aceite - -- nenhum tipo ou loader ativo do runtime depende de `entrypoint` em `manifest.json`; -- o boot inicial da VM nao aceita mais parametro textual de entrypoint; -- cartucho sem funcao valida em `func_id = 0` falha com `VmInitError::EntrypointNotFound`; -- `current_entrypoint` deixa de existir como estado operacional do runtime system; -- o stress tooling local continua produzindo artefato executavel compativel com o contrato novo; -- os testes afetados passam sob o contrato endurecido. - -## Tests / Validacao - -- testes unitarios de `prometeu-vm` cobrindo boot valido em `func_id = 0` e falha quando `0` estiver ausente ou invalido; -- testes de `prometeu-system` cobrindo inicializacao e ciclo de boot sem `current_entrypoint`; -- testes de `prometeu-hal` cobrindo loader sem `entrypoint` no manifesto; -- validacao do stress tooling local para garantir que o gerador nao continue emitindo contrato legado. - -## Riscos - -- a remocao de `entrypoint` pode quebrar fixtures e helpers de teste dispersos fora dos call sites obvios; -- mudar `VirtualMachine::initialize(...)` sem revisar o caminho de `tick()` pode deixar boot sem prepare inicial coerente; -- deixar `prepare_call()` parcialmente textual sem delimitar seu papel pode gerar confusao futuras, embora isso nao bloqueie esta PR; -- tooling local que ainda grave `entrypoint` pode mascarar regressao se nao for atualizado no mesmo ciclo. diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index 3e1b9697..f5aab88c 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -40,8 +40,6 @@ Nenhuma PR em aberto no momento. ## PRs Finalizadas -- `025-spec-cartridge-entrypoint-removal-and-boot-protocol.md`: concluída. Contrato normativo de cartridge publicado sem `entrypoint` e com boot em `func_id = 0`. Commit `e2f0904`. -- `026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md`: concluída. Loader, system, VM e stress tooling local propagados para o protocolo fixo de boot. Commit `a30ac16`. - `012-assets-preload-asset-id-propagation.md`: concluída. Propagação de ID-based preload concluída em specs e prometeu-hal. - `013-tile-bank-runtime-contract-alignment.md`: concluída. Contrato normativo de `tile bank` v1 alinhado entre `specs/04` e `specs/15`. - `014-tile-bank-loader-packed-nibbles-and-palette-boundary.md`: concluída. Loader/runtime atualizado para consumir payload serializado `4bpp` packed com `64` paletas por bank.