prometeu-studio/docs/pbs/pull-requests/PR-009-pbs-diagnostics-contract-v1.md

PR-009 - PBS Diagnostics Contract V1

Briefing

O modelo atual de Diagnostic nao contem fase, template id nem placeholders estaveis, o que impede conformidade com o contrato de diagnosticos da spec. Este PR eleva o contrato de diagnosticos para v1 sem acoplar a UI.

Target

• Specs:
  • docs/pbs/specs/12. Diagnostics Specification.md (secoes 6, 7, 8, 9, 10)
  • docs/pbs/specs/13. Lowering IRBackend Specification.md (secao 7)
• Codigo:
  • prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/diagnostics/Diagnostic.java
  • prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/source/diagnostics/DiagnosticSink.java
  • emissores de diagnostico no frontend PBS.

Method

1. Estender Diagnostic com phase, templateId e placeholders nomeados.
2. Definir taxonomia minima de fases externas: syntax, static-semantics, manifest-import-resolution, linking, host-admission, load-facing-rejection.
3. Preservar code, severity, span e related spans como identidade estavel.
4. Introduzir helpers para emissao padronizada por fase/template.
5. Mapear erros atuais de lexer/parser/frontend para o novo contrato.

Acceptance Criteria

• Todo diagnostico PBS emitido tem code, severity, phase, templateId, primary span e mensagem renderizada.
• Duplicatas/conflitos incluem ao menos um related span quando aplicavel.
• Identidade de diagnostico independe do texto localizado.
• Nenhuma fase obrigatoria e colapsada de forma opaca para o usuario.
• Chamadas legadas continuam compilando com caminho de migracao claro.

Tests

• DiagnosticSinkTest e novos testes de contrato para:
  • presenca obrigatoria de campos;
  • estabilidade de templateId/placeholders;
  • caso com related span;
  • serializacao/toString com fase e codigo.
• Testes de integracao no frontend PBS garantindo fase correta por erro.