prometeu-studio/docs/pbs/pull-requests/PR-010-pbs-irbackend-lowering-contract.md

PR-010 - PBS IRBackend Lowering Contract Alignment

Briefing

O lowering atual reduz tudo a IRFunction(name, arity, hasReturnType) e perde informacao exigida pela spec de lowering. Este PR alinha o frontend boundary para preservar identidade, superficie de retorno e atribuicao de origem.

Target

• Specs:
  • docs/pbs/specs/13. Lowering IRBackend Specification.md (secoes 5, 6, 7, 8)
  • docs/pbs/specs/11. AST Specification.md (metadados obrigatorios)
• Codigo:
  • prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsFrontendCompiler.java
  • prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java
  • prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend*.java

Method

1. Expandir modelos de IR para preservar categoria de callable e superficie de retorno.
2. Propagar atribuicao de origem estavel (file + span) de forma obrigatoria.
3. Diferenciar rejeicao de forma nao suportada vs erro interno.
4. Garantir determinismo de ordem de emissao conforme ordem de fonte.
5. Manter bridge de compatibilidade para consumidores atuais de IR.

Acceptance Criteria

• IRBackend preserva identidade e aridade de callables sem perda de categoria.
• Retorno (unit/plain/result) e mantido no boundary de frontend.
• Diagnosticos de lowering seguem contrato estavel (code/phase/template/span).
• Formas nao suportadas nao degradam silenciosamente para comportamento valido alternativo.
• Testes existentes de lowering continuam passando com adaptacao minima.

Tests

• PbsFrontendCompilerTest ampliado para:
  • preservacao de metadata no IR;
  • ordem deterministica de callables;
  • casos de rejeicao de lowering com diagnostico estavel.
• Novos testes para serializacao/debug de IRBackend.