loader protocol: remove entrypoint

This commit is contained in:
bQUARKz 2026-03-23 00:03:46 +00:00
parent 6fc0bf129c
commit c7e4d7398f
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
9 changed files with 89 additions and 388 deletions

View File

@ -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.

View File

@ -25,10 +25,6 @@ As agendas atuais são:
- `021-perf-vm-allocation-and-copy-pressure.md` - `021-perf-vm-allocation-and-copy-pressure.md`
- `022-perf-cartridge-boot-and-program-ownership.md` - `022-perf-cartridge-boot-and-program-ownership.md`
- `024-asset-entry-metadata-normalization-contract.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] ## Sequenciamento Recomendado [PERF]
Ordem sugerida para discussao das agendas de performance: Ordem sugerida para discussao das agendas de performance:

View File

@ -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.

View File

@ -18,13 +18,6 @@ Decisoes ativas:
Nenhuma no momento. 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/`): Decisoes implementadas e aposentadas (migradas para `learn/`):
- `historical-vm-core-and-assets.md` - `historical-vm-core-and-assets.md`

View File

@ -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-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-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-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-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) - [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md)

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -40,8 +40,6 @@ Nenhuma PR em aberto no momento.
## PRs Finalizadas ## 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. - `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`. - `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. - `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.