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 index 94da7671..32e7f534 100644 --- 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 @@ -1,111 +1,144 @@ -# Agenda - Cartridge Manifest Entrypoint Removal and Runtime Protocol +# 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 -O runtime ainda trata `entrypoint` como dado vindo do `manifest.json`. +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`. -Hoje isso aparece em mais de uma camada: +O ponto principal nao e apenas remover um campo JSON. -- o `manifest.json` carrega `entrypoint`; -- o loader desserializa e propaga esse campo; -- o `Cartridge` e o `CartridgeDTO` preservam esse valor; -- o runtime system passa esse valor para a VM; -- e a VM ainda resolve boot usando string nominal, índice numérico ou fallback vazio. +A agenda precisa fechar quem tem autoridade sobre o boot do cartucho: -Ao mesmo tempo, a linha nova do compiler/PBS está convergindo para outro modelo: +- se o manifesto continua escolhendo callable inicial; +- ou se o artefato compilado passa a carregar esse contrato de forma estrutural e obrigatoria. -- o compiler publica um wrapper sintético como entrypoint físico; -- esse wrapper deve ocupar o índice físico `0`; -- e o entrypoint deixa de ser uma escolha configurável no manifesto para virar protocolo fixo do artefato. +## Pontos Criticos -Isso cria uma divergência concreta entre contrato atual do runtime e direção desejada do compiler. +### Fatos observados -## Dor +- 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. -- O runtime mantém autoridade duplicada com o compiler sobre qual callable inicia o programa. -- O loader continua aceitando modelo nominal de entrypoint que o compiler quer abandonar. -- O `manifest.json` carrega responsabilidade que deveria pertencer ao protocolo executável. -- O caminho atual mistura: - - resolução nominal por export, - - resolução por índice, - - e fallback implícito. -- Essa flexibilidade aumenta superfície de erro e enfraquece determinismo do boot. +### Riscos -## Alvo da Discussao +- 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. -Definir a remoção de `entrypoint` do `manifest.json` e a migração do runtime para um protocolo fixo em que o entrypoint executável do cartucho é sempre o índice `0`. +### Tradeoffs -O objetivo não é apenas "apagar um campo JSON". +- 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. -Precisamos fechar: +### Hipoteses que precisam ser assumidas explicitamente -- novo contrato do loader; -- impacto em `CartridgeManifest`, `CartridgeDTO` e `Cartridge`; -- impacto em `VirtualMachine::initialize(...)`; -- impacto em `VirtualMachineRuntime`; -- política de compatibilidade transitória; -- e a superfície de erro quando o artefato não cumprir o protocolo esperado. +- 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. -## O Que Precisa Ser Definido +## Opcoes -1. Contrato final do manifest. - O campo `entrypoint` deixa de existir por completo? +### Opcao A - Manter `entrypoint` no manifesto como autoridade de boot -2. Contrato final do loader. - O loader deve parar de propagar qualquer entrypoint textual e assumir sempre boot pelo índice `0`? +O runtime continua lendo `manifest.json` e escolhendo o callable inicial por string ou indice textual. -3. Contrato final da VM. - `VirtualMachine::initialize(...)` continua recebendo `entrypoint: &str`, ou a API deve ser endurecida para boot protocolar sem parâmetro textual? +Consequencia: -4. Compatibilidade transitória. - O runtime aceita manifestos antigos com `entrypoint` por um período, ignora com warning, ou rejeita explicitamente? +- preserva o modelo atual; +- continua divergindo da direcao do compiler; +- mantem duplicidade de autoridade e superficie de erro desnecessaria. -5. Superfície de erro. - Qual erro canônico deve aparecer quando o artefato não tiver função válida no índice `0`? +### Opcao B - Remover `entrypoint` do manifesto e migrar o boot para protocolo fixo em `func_id = 0` -6. Relação com exports nominais. - Exports continuam existindo para linking/introspection, mas deixam de participar da autoridade de boot? +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. -## Contexto Atual Observado +Consequencia: -Hoje o acoplamento aparece ao menos nestes pontos do runtime: +- 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. -- `prometeu-hal`: - - `CartridgeManifest.entrypoint` - - `CartridgeDTO.entrypoint` - - `Cartridge.entrypoint` -- `cartridge_loader`: - - leitura e propagação de `manifest.entrypoint` -- `prometeu-system`: - - `initialize_vm()` repassa `cartridge.entrypoint` - - `current_entrypoint` ainda é rastreado -- `prometeu-vm`: - - `initialize(program_bytes, entrypoint)` - - resolução por string, índice ou fallback +### Opcao C - Manter `entrypoint` apenas como compatibilidade, mas ignorar no runtime novo -Isso mostra que a mudança necessária é funcional e estrutural, não apenas uma validação de manifesto. +O manifesto antigo continua aceito por algum tempo, porem `entrypoint` vira campo sem efeito operacional. -## O Que Necessita Para Resolver +Consequencia: -- decisão clara sobre estado final do protocolo; -- decisão clara sobre compatibilidade transitória; -- inventário de tipos/APIs a alterar no runtime; -- atualização de testes de loader, system runtime e VM init; -- alinhamento com spec do cartridge manifest e com a política de `func_id = 0`. +- reduz quebra imediata; +- mas preserva ambiguidade documental e risco de produtores continuarem emitindo dado morto. -## Fora de Escopo +## Sugestao / Recomendacao -- discutir novamente qual callable do usuário é o root lógico; -- discutir wrapper sintético do compiler em detalhe; -- discutir lowering FE/BE do compiler; -- redesign geral do formato `manifest.json` além do campo `entrypoint`. +Adotar `Opcao B`, sem compatibilidade transitoria normativa no runtime. -## Critério de Saida Desta Agenda +Direcao recomendada: -Pode virar decision quando houver definição escrita de: +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. -- remoção ou não de `entrypoint` do manifest como contrato final; -- política de transição para cartuchos antigos; -- novo contrato do loader/VM para boot em índice `0`; -- erros canônicos quando o protocolo não for satisfeito; -- e escopo mínimo de mudanças de código e testes no runtime. +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 f5801110..b57a690c 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -24,6 +24,7 @@ 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` +- `025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md` - `024-asset-entry-metadata-normalization-contract.md` ## Sequenciamento Recomendado [PERF] @@ -88,4 +89,3 @@ Regra de uso: - se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código; - se uma agenda já estiver resolvida, a PR derivada deve citar explicitamente qual decisão foi tomada; - se a agenda revelar ambiguidade demais, ela não deve ser convertida em PR até o alvo ficar preciso. - 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 new file mode 100644 index 00000000..be66dbd0 --- /dev/null +++ b/docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md @@ -0,0 +1,98 @@ +# 025-cartridge-manifest-entrypoint-removal-and-runtime-protocol + +Status: Accepted +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) + +## 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 + +- abrir `PR/plan` derivada desta decision separando: + - propagacao editorial em spec; + - propagacao de codigo em loader, system, VM e tooling auxiliar; +- atualizar `spec 13` antes ou em paralelo ao codigo para evitar contrato dividido; +- apos publicacao de spec e codigo, consolidar o modelo final em `learn` se esta decisao se somar a outras de cartridge/boot. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index e3f3c992..d2667672 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -16,7 +16,9 @@ Regra de uso: Decisoes ativas: -Nenhuma no momento. +- `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`. Decisoes implementadas e aposentadas (migradas para `learn/`): 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 new file mode 100644 index 00000000..22ec4056 --- /dev/null +++ b/docs/runtime/pull-requests/025-spec-cartridge-entrypoint-removal-and-boot-protocol.md @@ -0,0 +1,57 @@ +# 025-spec-cartridge-entrypoint-removal-and-boot-protocol + +## 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 new file mode 100644 index 00000000..a4f0306b --- /dev/null +++ b/docs/runtime/pull-requests/026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md @@ -0,0 +1,64 @@ +# 026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation + +## 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 f5aab88c..b5a487b4 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -36,7 +36,12 @@ Uma PR deste diretório deve: ## Roadmap Atual -Nenhuma PR em aberto no momento. +- `025-spec-cartridge-entrypoint-removal-and-boot-protocol.md` + - origem: `decision 025` + - foco: propagar o contrato normativo sem `entrypoint` e publicar boot em `func_id = 0`. +- `026-runtime-cartridge-entrypoint-removal-and-boot-protocol-propagation.md` + - origem: `decision 025` + - foco: remover `entrypoint` de loader/system/VM e ajustar testes e stress tooling local. ## PRs Finalizadas