loader protocol: remove entrypoint
This commit is contained in:
parent
6fc0bf129c
commit
c7e4d7398f
@ -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.
|
|
||||||
@ -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:
|
||||||
|
|||||||
@ -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.
|
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`
|
||||||
|
|||||||
@ -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)
|
||||||
|
|
||||||
|
|||||||
@ -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.
|
||||||
@ -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.
|
|
||||||
@ -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.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user