From 99f320fdea60ef12d763118887f5d4c04b7e38c9 Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Sun, 22 Mar 2026 12:16:33 +0000
Subject: [PATCH] loader protocol: remove entrypoint

---
 ...entrypoint-removal-and-runtime-protocol.md | 111 ++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md

diff --git a/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md b/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md
new file mode 100644
index 00000000..94da7671
--- /dev/null
+++ b/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md
@@ -0,0 +1,111 @@
+# 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.