loader protocol: remove entrypoint
This commit is contained in:
parent
6fc0bf129c
commit
c7e4d7398f
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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`
|
||||
- `022-perf-cartridge-boot-and-program-ownership.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]
|
||||
|
||||
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.
|
||||
|
||||
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`
|
||||
|
||||
@ -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-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-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-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
|
||||
|
||||
- `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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user