prometeu-studio/docs/pbs/pull-requests/PR-05.1-pbs-frontend-semantic-executable-lowering-cfg.md

PR-05.1 - PBS Frontend Semantic Executable Lowering (CFG)

Briefing

O frontend PBS ainda gera IRBackendExecutableFunction por varredura de callsites no AST, o que perde semântica de execução real.

Esta PR substitui esse caminho por lowering semântico baseado em fluxo de controle (CFG), preservando ordem de execução, terminadores e formas de desvio.

Motivation

Dor atual que esta PR resolve

1. Execução divergente entre programa fonte e artefato gerado em cenários com if, while, for, switch, handle e return antecipado.
2. Impossibilidade de elevar o backend para JVM-grade porque o contrato executável nasce semanticamente incompleto.
3. Falsos positivos de conformidade: testes passam para casos lineares, mas o modelo quebra em fluxo real.

Target

Esta PR altera o frontend PBS para que IRBackendExecutableFunction.instructions represente fluxo executável real, não apenas uma lista de chamadas encontradas.

Dependencies

Prerequisitos diretos:

1. PR-05.0.1 (NameTable compartilhada por fase).
2. PR-05.0.2 (identidade de modulo por ModuleId).
3. PR-05.0.3 (IDs tipados de callable/intrinseco no contrato).
4. PR-05.0.4 (internacao de shape/signature).

Scope

1. Gerador de IR executável no frontend PBS.
2. Emissão de labels e jumps para estruturas de controle.
3. Recalculo de maxStackSlots com base no fluxo emitido.
4. Testes de fidelidade semântica do FE para IR executável.

Non-Goals

1. Não introduz otimizações.
2. Não altera formato binário PBX.
3. Não altera runtime.

Method

O que deve ser feito explicitamente

1. Substituir o mecanismo de collectCallsFrom* por lowering orientado a nós semânticos de statements/expressions.
2. Emitir instruções de controle (LABEL, JMP, JMP_IF_TRUE, JMP_IF_FALSE, RET) para cada forma de fluxo suportada.
3. Garantir que return termine bloco/caminho e que caminhos alcançáveis terminem em instrução terminadora.
4. Preservar spans de origem em cada instrução emitida para diagnóstico.
5. Manter validação fail-fast quando existir forma semântica não lowerável em v1.
6. Atualizar análise de stack para operar sobre o programa realmente emitido.
7. Emitir referências de chamada via IDs tipados (CallableId/IntrinsicId) sem chave textual ad-hoc.

Acceptance Criteria

1. IRBackendExecutableFunction deixa de ser construído por varredura cega de callsites.
2. Para casos com ramificação e laço, a ordem de execução no IR executável é semanticamente equivalente ao AST validado.
3. Funções com return antecipado não emitem execução espúria após ponto de saída.
4. maxStackSlots calculado bate com programa emitido e passa em validação backend.
5. Diagnósticos de lowering preservam fase e span corretamente.
6. Não há lookup de identidade de callsite baseado em concatenação string no caminho principal.

Tests

1. Testes positivos com fixtures de if/else, while, for, switch, handle, return antecipado.
2. Testes negativos para caminhos sem terminador, labels inválidos e formas não suportadas.
3. Teste de regressão comparando resultado anterior vs novo para provar correção em casos não lineares.

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/19. Verification and Safety Checks Specification.md

Open Questions

Sem bloqueios arquiteturais. Implementação deve seguir decisões já fechadas na Agenda 18.