105 lines
5.4 KiB
Markdown
105 lines
5.4 KiB
Markdown
# 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.
|