prometeu-studio/docs/pbs/pull-requests/PR-08.3-qualified-entrypoint-identity-contract.md

PR-08.3 - Qualified Entrypoint Identity (No Name-Only Resolution)

Briefing

A selecao de entrypoint no backend ainda filtra apenas por callableName.

Em projetos multi-modulo isso amplia risco de ambiguidade e cria acoplamento desnecessario a nomes globais.

Motivation

Dor atual que esta PR resolve

1. Ambiguidade de entrypoint quando existem callables homonimos.
2. Diagnostico tardio por nome sem contexto de modulo.
3. Divergencia potencial entre contrato de frontend e selecao real no backend.

Target

Evoluir o contrato para entrypoint qualificado e deterministico:

1. entryPointCallableName + entryPointModuleId (ou entryPointCallableId),
2. resolucao backend por identidade qualificada,
3. politicas de erro claras para mismatch/ausencia.

Dependencies

Prerequisitos diretos:

1. PR-08.2 (ModuleId no contrato IRBackend).
2. PR-05.3 (politica deterministica de indexacao e func_id=0).

Scope

1. Expandir FrontendSpec e handoff FE para declarar entrypoint qualificado.
2. Atualizar IRBackend para carregar declaracao qualificada de entrypoint.
3. Atualizar LowerToIRVMService para selecionar entrypoint por identidade qualificada.
4. Preservar fallback de compatibilidade durante migracao (com warning deterministico).

Non-Goals

1. Nao alterar semantica de func_id=0.
2. Nao mudar contrato de manifesto de cartridge nesta PR.
3. Nao introduzir multiple entrypoints por linguagem.

Method

O que deve ser feito explicitamente

1. Introduzir estrutura de entrada qualificada (ex.: EntrypointRef(moduleId, callableName)).
2. Popular estrutura no frontend PBS a partir do modulo de frame.
3. Modificar orderFunctions para usar referencia qualificada.
4. Em caso de fallback por nome, emitir diagnostico de deprecacao controlado.
5. Adicionar testes para:
   • homonimos em modulos distintos,
   • entrypoint valido qualificado,
   • entrypoint ausente com erro estavel.

Acceptance Criteria

1. Selecao de entrypoint nao depende apenas de nome.
2. Homonimos em modulos distintos nao geram ambiguidade quando entrypoint qualificado existe.
3. func_id=0 continua pertencendo ao entrypoint declarado.
4. Rebuilds equivalentes mantem func ordering deterministico.

Tests

1. :prometeu-compiler:prometeu-frontend-api:test
2. :prometeu-compiler:prometeu-build-pipeline:test --tests *LowerToIRVMServiceTest*
3. Testes de integracao com dois modulos contendo frame.

Affected Documents

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

Open Questions

1. Melhor contrato final: EntrypointRef(moduleId, callableName) ou CallableId global direto?