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