prometeu-studio/docs/pbs/decisions/AST Statements and Expressions Decision.md

AST Statements and Expressions Decision

Status: Accepted
Date: 2026-03-05
Related Agenda: docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md

Context

After closing AST contract/root and declaration surfaces, PBS needed a precise v1 decision for statement/expression AST obligations, including precedence/associativity representation, unsupported-form behavior, and Gate U evidence.

Decision

PBS adopts the following statement/expression AST policy for v1:

1. Mandatory statement/expression AST families must cover the supported PBS core syntax slice, including at minimum:
   • statements: block, let, return, expression statement, and other supported statement forms;
   • expressions: identifier, literals, unary, binary, call, group, and other supported expression forms.
2. Precedence and associativity parsing outcomes are normative via AST shape and must be preserved explicitly.
3. Non-associative or forbidden chained forms are deterministic reject with stable diagnostics.
4. AST remains structural; semantic compatibility/type decisions are owned by static semantics/linking phases.
5. Unsupported statement/expression forms are deterministic reject and must not be represented by permissive synthetic placeholder nodes that mask real rejection.
6. Parser recovery may continue after syntax errors, but recovered AST must remain structurally coherent with stable attribution.
7. Gate U evidence must include positive and negative fixtures with AST-shape assertions and diagnostics assertions.

Invariants

1. Statement/expression AST obligations are implementation-language agnostic.
2. AST shape must not be post-rewritten in a way that changes source-observable parse meaning.
3. Required nodes for diagnostics/lowering must preserve stable file/start/end.
4. Recovery must preserve integrity and must not silently convert invalid syntax into valid semantics.

Explicit Non-Decisions

1. This decision does not define static type-checking algorithms.
2. This decision does not define IRBackend -> IRVM lowering.
3. This decision does not define runtime/bytecode/verifier policy.
4. This decision does not freeze one parser implementation strategy.

Spec Impact

1. docs/pbs/specs/11. AST Specification.md must encode statement/expression node-family obligations, precedence/associativity shape obligations, and recovery/rejection invariants.
2. docs/pbs/specs/12. Diagnostics Specification.md remains the authority for stable diagnostics identity/phase/attribution requirements.
3. docs/pbs/specs/13. Lowering IRBackend Specification.md may assume statement/expression AST invariants as lowering preconditions.

Validation Notes

Gate U evidence (per docs/general/specs/13. Conformance Test Specification.md) should include:

1. valid fixtures proving expected precedence/associativity AST shape;
2. invalid fixtures for non-associative or unsupported forms with deterministic diagnostics;
3. assertions for stable node attribution (file/start/end) where diagnostics and lowering consume those nodes.