loader protocol: remove entrypoint
This commit is contained in:
-104
@@ -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.
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user