prometeu-studio/docs/pbs/pull-requests/PR-07.3-irvm-entrypoint-export-emission-for-runtime-loader.md

PR-07.3 - IRVM Entrypoint Export Emission for Runtime Loader Compatibility

Briefing

Hoje um cartridge pode compilar com entrypoint: "frame" no manifest.json e pub fn frame() no mod.barrel, mas ainda falhar em runtime com EntrypointNotFound.

A causa observada e que o program.pbx pode ser emitido sem secao exports (section kind 4), enquanto o loader resolve entrypoint nominal usando program.exports.

Motivation

Dor atual que esta PR resolve

1. Build aparentemente valido, mas falha de bootstrap em runtime.
2. Divergencia entre contrato de manifesto (entrypoint nominal) e artefato PBX emitido.
3. Falta de evidencia automatizada para evitar regressao de exports no caminho IRBackend -> IRVM -> Bytecode.

Target

Corrigir o pipeline backend para sempre emitir export nominal do entrypoint no PBX de preload, garantindo compatibilidade com o loader quando o manifest.json declara entrypoint por nome.

Dependencies

Prerequisitos diretos:

1. PR-05.3 (politica deterministica de entrypoint no indice 0).
2. PR-05.4 (coerencia unica entre IRVM e EmissionPlan).

Scope

1. LowerToIRVMService deve preencher EmissionPlan.exports com o simbolo do entrypoint apontando para func_idx = 0.
2. Adicionar regressao dedicada para garantir que coherentEmissionPlan() preserva export do entrypoint.
3. Validar serializacao PBX com secao exports presente quando houver entrypoint nominal.
4. Cobrir cenario de integracao onde manifest.entrypoint = "frame" inicializa VM sem EntrypointNotFound.

Non-Goals

1. Nao exportar toda a superficie de funcoes executaveis neste passo.
2. Nao alterar formato binario PBX alem da presenca correta da secao exports.
3. Nao mudar semantica de resolucao por indice numerico de entrypoint.

Method

O que deve ser feito explicitamente

1. No LowerToIRVMService, construir BytecodeEmitter.EmissionPlan com exports contendo, no minimo, Export(entryPointCallableName, 0).
2. Garantir determinismo do export do entrypoint a partir da mesma politica que fixa func_id = 0.
3. Adicionar teste unitario em LowerToIRVMServiceTest para verificar export nominal do entrypoint no plano coerente.
4. Adicionar teste de emissao/link para verificar secao exports no modulo serializado.
5. Adicionar teste de integracao runtime-backed para falhar se regressar para EntrypointNotFound em cartridge com entrypoint nominal valido.

Acceptance Criteria

1. Build de projeto PBS com entrypoint frame gera PBX com secao exports.
2. O simbolo frame aponta para func_idx = 0 no artefato emitido.
3. Execucao de cartridge com manifest.entrypoint = "frame" nao falha por EntrypointNotFound quando o programa contem o entrypoint admitido.
4. Rebuilds equivalentes produzem mapping de export deterministico.

Tests

1. Novos testes de backend:
   • :prometeu-compiler:prometeu-build-pipeline:test
2. Reexecucao de compatibilidade runtime-backed:
   • :prometeu-compiler:prometeu-build-pipeline:test --tests *Runtime*
3. Smoke local recomendado:
   • ./runtime/prometeu build .
   • ./runtime/prometeu run cartridge

Affected Documents

1. docs/general/specs/15. Bytecode and PBX Mapping Specification.md
2. docs/general/specs/20. IRBackend to IRVM Lowering Specification.md
3. docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md
4. docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md

Open Questions

1. Em evolucao futura, devemos exportar apenas o entrypoint ou tambem funcoes explicitamente marcadas para linking externo?