prometeu-studio/docs/compiler/pbs/decisions/AST Contract and Root Model Decision.md

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.