54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# AST Contract and Root Model Decision
|
|
|
|
Status: Accepted
|
|
Date: 2026-03-05
|
|
Related Agenda: `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md`
|
|
|
|
## Context
|
|
|
|
PBS introduced `11. AST Specification.md` as the language-specific AST layer between parser output and frontend lowering to `IRBackend`.
|
|
|
|
The open question was whether AST should be standardized by one mandatory implementation model (for example one Java class hierarchy) or by observable contract obligations.
|
|
|
|
## Decision
|
|
|
|
PBS adopts an obligations-first AST contract.
|
|
|
|
The specification standardizes required observable AST behavior and invariants, not one mandatory in-memory representation.
|
|
|
|
The following are required:
|
|
|
|
1. one AST root per source file;
|
|
2. deterministic child ordering consistent with source order;
|
|
3. mandatory source attribution (`file`, `start`, `end`) on nodes consumed by diagnostics or lowering;
|
|
4. explicit declaration/statement/expression node families for the supported v1 source slice;
|
|
5. deterministic rejection for unsupported forms, without permissive synthetic AST that hides rejection.
|
|
|
|
## Invariants
|
|
|
|
1. AST conformance is implementation-language agnostic.
|
|
2. Missing required attribution on mandatory nodes is non-conformant.
|
|
3. Parser recovery may produce partial AST, but structural integrity must remain valid for continued diagnostics.
|
|
4. Lowering and diagnostics are allowed to depend on the required AST invariants above.
|
|
|
|
## Explicit Non-Decisions
|
|
|
|
1. This decision does not freeze one parser architecture.
|
|
2. This decision does not define full static-semantics rules.
|
|
3. This decision does not define `IRBackend -> IRVM` lowering.
|
|
4. This decision does not define runtime/bytecode/verifier policies.
|
|
|
|
## Spec Impact
|
|
|
|
1. `docs/pbs/specs/11. AST Specification.md` must encode the obligations-first contract and invariants.
|
|
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for diagnostic identity/phase/attribution payload rules consumed by AST-facing diagnostics.
|
|
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume the mandatory AST invariants as lowering preconditions.
|
|
|
|
## Validation Notes
|
|
|
|
At minimum, Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:
|
|
|
|
1. valid AST shape fixtures for representative declarations/statements/expressions;
|
|
2. deterministic syntax rejection fixtures with stable diagnostics;
|
|
3. attribution checks (`file/start/end`) on nodes required by diagnostics and lowering.
|