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

Contrato final do manifest. O campo entrypoint deixa de existir por completo?
Contrato final do loader. O loader deve parar de propagar qualquer entrypoint textual e assumir sempre boot pelo índice 0?
Contrato final da VM. VirtualMachine::initialize(...) continua recebendo entrypoint: &str, ou a API deve ser endurecida para boot protocolar sem parâmetro textual?
Compatibilidade transitória. O runtime aceita manifestos antigos com entrypoint por um período, ignora com warning, ou rejeita explicitamente?
Superfície de erro. Qual erro canônico deve aparecer quando o artefato não tiver função válida no índice 0?
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.

4.3 KiB Raw Blame History