# 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.