# AST and Parser Contract

## Original Problem

PBS needed a stable AST contract that downstream phases could rely on without freezing one implementation language, one parser architecture, or one exact in-memory tree layout.

The earlier decision set also needed to close:

- which declaration families are mandatory,
- how statement and expression structure is represented,
- how precedence and associativity become observable,
- and how recovery and diagnostics stay deterministic.

## Consolidated Decision

PBS adopts an obligations-first AST contract.

The language standardizes observable AST behavior rather than one mandatory runtime representation.

The durable rules are:

1. One AST root exists per source file.
2. Child ordering is deterministic and follows source order.
3. Nodes consumed by diagnostics or lowering carry stable source attribution.
4. Declaration, statement, and expression families are explicit and structurally distinguishable.
5. Unsupported syntax is rejected deterministically instead of being hidden behind permissive synthetic nodes.
6. Recovery is allowed only when the recovered tree remains structurally coherent and attribution-safe.
7. Diagnostic identity is token-based and locale-agnostic; wording is not the conformance key.

## Final Model

The AST is not a semantic layer.

It preserves:

- source structure,
- declaration identity,
- precedence/associativity outcomes,
- and enough metadata for diagnostics and lowering.

It does not own:

- type checking,
- overload resolution,
- backend lowering policy,
- or runtime behavior.

That split matters because it keeps parser work honest: the parser records what the user wrote, and later phases decide what that structure means.

## Practical Consequences

When implementing or reviewing PBS parser work:

1. Reject malformed forms early and deterministically.
2. Do not collapse overload sets at AST boundary.
3. Do not use recovery to invent a valid semantic shape for invalid syntax.
4. Preserve spans on every node that diagnostics or lowering may consume.
5. Treat precedence and associativity as part of the observable contract, not an implementation detail.

## Common Pitfalls

- Treating localized message text as a conformance identity key.
- Rewriting AST shape after parse in a way that changes the observable parse result.
- Allowing recovery to mask a required rejection.
- Emitting nodes without enough attribution for diagnostics or lowering.

## Source Decisions

- `AST Contract and Root Model Decision.md`
- `AST Declarations and Type Surfaces Decision.md`
- `AST Statements and Expressions Decision.md`
- `AST Diagnostics, Recovery, and Gate Evidence Decision.md`