73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# 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`
|