# PBS AST Specification

Status: Draft v0  
Applies to: canonical AST contract emitted by PBS parser/frontend before IRBackend lowering

## 1. Purpose

This document defines the PBS AST contract used as the frontend boundary between syntax parsing and IRBackend lowering.

Its purpose is to keep AST behavior deterministic enough that:

- parser outputs are stable across implementations,
- diagnostics attribution remains source-anchored,
- and lowering to `IRBackend` starts from a predictable tree contract.

## 2. Scope

This document defines:

- minimum AST node families required for PBS v1 source forms,
- source-span attribution obligations for AST nodes,
- parser-output invariants consumed by static semantics and lowering,
- and AST-facing rejection boundaries for malformed syntax.

This document does not define:

- static-semantics type rules,
- VM/runtime execution behavior,
- bytecode/PBX mapping,
- or backend-specific IR/optimizer internals.

## 3. Authority and Precedence

Normative precedence:

1. `3. Core Syntax Specification.md`
2. `4. Static Semantics Specification.md`
3. `12. Diagnostics Specification.md`
4. `13. Lowering IRBackend Specification.md`
5. This document

If a rule here conflicts with higher-precedence syntax or semantic rules, the higher-precedence rule wins.

## 4. Normative Inputs

This document depends on:

- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`

## 5. AST Contract Baseline

At minimum, parser output must provide:

1. one file/root node per parsed source file;
2. declaration nodes required by the active PBS syntax surface;
3. statement and expression nodes for accepted executable forms;
4. stable source attribution (`file`, `start`, `end`) on nodes used by diagnostics and lowering;
5. deterministic child ordering matching source-observable evaluation order.

## 6. Structural Invariants

Minimum structural invariants:

1. AST preserves declaration nesting and lexical block hierarchy from source.
2. Node spans are stable and must not overlap in impossible parent/child order.
3. Recovered parser output (after syntax errors) must remain internally consistent enough for additional diagnostics.
4. Unsupported syntax forms are rejected deterministically and must not be rewritten into semantically different valid AST shapes.

## 7. Diagnostics Integration

AST-related diagnostics must follow `12. Diagnostics Specification.md`:

- stable `diagnostic code`,
- stable `severity`,
- stable primary source attribution.

Parser/AST diagnostics are in `syntax` phase unless another higher-precedence rule assigns a different phase.

## 8. Conformance and Test Evidence

AST conformance evidence is provided through Gate U fixtures as defined in `docs/general/specs/13. Conformance Test Specification.md`.

At minimum, fixtures must cover:

1. representative valid AST shapes,
2. deterministic syntax rejection and recovery behavior,
3. stable source attribution for required diagnostics.

## 9. Non-Goals

- Defining one programming-language-neutral AST framework.
- Freezing one parser implementation architecture.
- Encoding runtime behavior in AST rules.

## 10. Exit Criteria

This document is healthy when:

1. required AST node families are explicit,
2. attribution and structural invariants are explicit,
3. deterministic AST-facing rejection classes are test-backed,
4. and lowering preconditions for `13` are unambiguous.