prometeu-studio/docs/pbs/pull-requests/PR-002-pbs-ast-contract-v1.md

PR-002 - PBS AST Contract V1

Briefing

Hoje o AST representa apenas funcoes, let/return e expressoes basicas. A spec exige familias obrigatorias de declaracoes e metadados estaveis para parser, diagnosticos e lowering. Este PR fecha o contrato estrutural do AST sem ainda resolver todas as regras semanticas.

Target

• Specs:
  • docs/pbs/specs/11. AST Specification.md (secoes 6, 7, 8, 9, 10)
  • docs/pbs/specs/3. Core Syntax Specification.md (secoes 6, 7, 8, 9, 10)
• Codigo:
  • prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java
  • prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsParser.java

Method

1. Remodelar o root para conter imports e uma lista de TopDecl em ordem de fonte.
2. Introduzir familias obrigatorias de declaracao (fn, struct, contract, service, error, enum, callback, declare const, implements).
3. Adicionar estruturas de tipo (unit, simple, optional, tuple nomeada, Self) e retorno (plain, result).
4. Garantir file/start/end em todos os nos consumidos por diagnostico/lowering.
5. Definir nos de erro/recovery explicitos para evitar AST permissivo.

Acceptance Criteria

• Existe exatamente um root por arquivo com filhos em ordem deterministica.
• AST preserva identidade de declaracoes sem colapsar overload cedo.
• Cada declaracao obrigatoria possui nome, assinatura/superficie e span.
• Parser recovery nao fabrica semantica valida; erros ficam marcados no AST.
• Precedencia e associatividade continuam observaveis pelo shape da arvore.

Tests

• PbsParserTest:
  • validacao de shape do root (imports + topDecls);
  • cobertura de todas as familias de declaracao obrigatorias no AST;
  • asserts de spans (file/start/end) em nos principais;
  • fixture com erro e recovery garantindo estrutura coerente.