# 025-cartridge-manifest-entrypoint-removal-and-runtime-protocol

Status: Accepted
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)

## 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

- abrir `PR/plan` derivada desta decision separando:
  - propagacao editorial em spec;
  - propagacao de codigo em loader, system, VM e tooling auxiliar;
- atualizar `spec 13` antes ou em paralelo ao codigo para evitar contrato dividido;
- apos publicacao de spec e codigo, consolidar o modelo final em `learn` se esta decisao se somar a outras de cartridge/boot.