# Agenda - Cartridge Manifest Entrypoint Removal and Runtime Protocol

## Problema

O runtime ainda trata `entrypoint` como dado vindo do `manifest.json`.

Hoje isso aparece em mais de uma camada:

- o `manifest.json` carrega `entrypoint`;
- o loader desserializa e propaga esse campo;
- o `Cartridge` e o `CartridgeDTO` preservam esse valor;
- o runtime system passa esse valor para a VM;
- e a VM ainda resolve boot usando string nominal, índice numérico ou fallback vazio.

Ao mesmo tempo, a linha nova do compiler/PBS está convergindo para outro modelo:

- o compiler publica um wrapper sintético como entrypoint físico;
- esse wrapper deve ocupar o índice físico `0`;
- e o entrypoint deixa de ser uma escolha configurável no manifesto para virar protocolo fixo do artefato.

Isso cria uma divergência concreta entre contrato atual do runtime e direção desejada do compiler.

## Dor

- O runtime mantém autoridade duplicada com o compiler sobre qual callable inicia o programa.
- O loader continua aceitando modelo nominal de entrypoint que o compiler quer abandonar.
- O `manifest.json` carrega responsabilidade que deveria pertencer ao protocolo executável.
- O caminho atual mistura:
  - resolução nominal por export,
  - resolução por índice,
  - e fallback implícito.
- Essa flexibilidade aumenta superfície de erro e enfraquece determinismo do boot.

## Alvo da Discussao

Definir a remoção de `entrypoint` do `manifest.json` e a migração do runtime para um protocolo fixo em que o entrypoint executável do cartucho é sempre o índice `0`.

O objetivo não é apenas "apagar um campo JSON".

Precisamos fechar:

- novo contrato do loader;
- impacto em `CartridgeManifest`, `CartridgeDTO` e `Cartridge`;
- impacto em `VirtualMachine::initialize(...)`;
- impacto em `VirtualMachineRuntime`;
- política de compatibilidade transitória;
- e a superfície de erro quando o artefato não cumprir o protocolo esperado.

## O Que Precisa Ser Definido

1. Contrato final do manifest.
   O campo `entrypoint` deixa de existir por completo?

2. Contrato final do loader.
   O loader deve parar de propagar qualquer entrypoint textual e assumir sempre boot pelo índice `0`?

3. Contrato final da VM.
   `VirtualMachine::initialize(...)` continua recebendo `entrypoint: &str`, ou a API deve ser endurecida para boot protocolar sem parâmetro textual?

4. Compatibilidade transitória.
   O runtime aceita manifestos antigos com `entrypoint` por um período, ignora com warning, ou rejeita explicitamente?

5. Superfície de erro.
   Qual erro canônico deve aparecer quando o artefato não tiver função válida no índice `0`?

6. Relação com exports nominais.
   Exports continuam existindo para linking/introspection, mas deixam de participar da autoridade de boot?

## Contexto Atual Observado

Hoje o acoplamento aparece ao menos nestes pontos do runtime:

- `prometeu-hal`:
  - `CartridgeManifest.entrypoint`
  - `CartridgeDTO.entrypoint`
  - `Cartridge.entrypoint`
- `cartridge_loader`:
  - leitura e propagação de `manifest.entrypoint`
- `prometeu-system`:
  - `initialize_vm()` repassa `cartridge.entrypoint`
  - `current_entrypoint` ainda é rastreado
- `prometeu-vm`:
  - `initialize(program_bytes, entrypoint)`
  - resolução por string, índice ou fallback

Isso mostra que a mudança necessária é funcional e estrutural, não apenas uma validação de manifesto.

## O Que Necessita Para Resolver

- decisão clara sobre estado final do protocolo;
- decisão clara sobre compatibilidade transitória;
- inventário de tipos/APIs a alterar no runtime;
- atualização de testes de loader, system runtime e VM init;
- alinhamento com spec do cartridge manifest e com a política de `func_id = 0`.

## Fora de Escopo

- discutir novamente qual callable do usuário é o root lógico;
- discutir wrapper sintético do compiler em detalhe;
- discutir lowering FE/BE do compiler;
- redesign geral do formato `manifest.json` além do campo `entrypoint`.

## Critério de Saida Desta Agenda

Pode virar decision quando houver definição escrita de:

- remoção ou não de `entrypoint` do manifest como contrato final;
- política de transição para cartuchos antigos;
- novo contrato do loader/VM para boot em índice `0`;
- erros canônicos quando o protocolo não for satisfeito;
- e escopo mínimo de mudanças de código e testes no runtime.