loader protocol: remove entrypoint

This commit is contained in:
2026-03-24 13:40:57 +00:00
parent 6fc0bf129c
commit c7e4d7398f
9 changed files with 89 additions and 388 deletions
@@ -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.
@@ -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.
-2
View File
@@ -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.