prometeu-runtime/docs/runtime/decisions/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md

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 Implementation:

• spec propagation: ../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, 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 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 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
• ../specs/13-cartridge.md
• ../specs/12-firmware-pos-and-prometeuhub.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.