# PBS AST Specification

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

## 1. Purpose

This document defines the mandatory AST contract between PBS parsing and frontend lowering to `IRBackend`.

The contract is obligations-first: implementations may choose any internal representation, but must expose equivalent observable AST behavior and invariants.

## 2. Scope

This document defines:

- AST root and ordering invariants,
- mandatory node families for declarations, statements, and expressions in the supported v1 slice,
- mandatory node attribution and declaration metadata,
- deterministic rejection and recovery boundaries,
- and Gate U evidence obligations for AST conformance.

This document does not define:

- static-semantics algorithms,
- runtime/bytecode/verifier behavior,
- or `IRBackend -> IRVM` lowering.

## 3. Authority and Precedence

Normative precedence:

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

If a rule here conflicts with a higher-precedence source, 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 Model

The AST contract is defined by required observable behavior, not by one mandatory class hierarchy or parser architecture.

Conformance is implementation-language agnostic.

## 6. Root and Structural Invariants

Parser output must satisfy all of the following:

1. exactly one AST root per source file;
2. deterministic child ordering consistent with source order;
3. preserved declaration and lexical block hierarchy;
4. parent/child span integrity (no structurally impossible attribution relationships);
5. no post-parse AST rewrite that changes source-observable parse meaning.

## 7. Mandatory Attribution and Declaration Metadata

Every node consumed by diagnostics or lowering must carry stable source attribution:

- `file`,
- `start`,
- `end`.

Mandatory declaration metadata on required declaration nodes includes:

1. declaration name,
2. declared signature/surface when applicable (parameters/return),
3. declaration-level syntactic flags/attributes required by later phases,
4. stable `file/start/end` attribution,
5. lifecycle-marker metadata when a declaration carries `[Init]` or `[Frame]`.

Missing required attribution or metadata on mandatory nodes is non-conformant.

## 8. Mandatory Declaration Families

The v1 AST must represent, at minimum, declaration families for:

- imports,
- top-level `fn`,
- `struct`,
- `contract`,
- `service`,
- `error`,
- `enum`,
- `callback`,
- `declare global`,
- `declare const`,
- and declaration nodes required by barrel/linking flow.

Declaration identity must be preserved at AST boundary; implementations must not prematurely merge/collapse declarations (including overload sets).

Lifecycle-observable declarations must preserve marker metadata explicitly:

- top-level `fn` marked with `[Init]`,
- top-level `fn` marked with `[Frame]`,
- and host method signatures marked with `[InitAllowed]`.

## 9. Mandatory Statement and Expression Families

The v1 AST must represent statement/expression families for the supported core syntax slice, including at minimum:

- statements: `block`, `let`, `return`, expression statement;
- expressions: `identifier`, literals, `unary`, `binary`, `call`, `group`.

Additional supported forms required by `3` are also in scope for explicit node representation.

## 10. Precedence, Associativity, and Rejection

Precedence and associativity outcomes are normative through AST shape.

Rules:

1. accepted forms must preserve parse outcome explicitly in AST shape;
2. non-associative or forbidden chained forms are deterministic reject with stable diagnostics;
3. unsupported forms outside the active source slice are deterministic reject;
4. unsupported/invalid forms must not be masked by permissive synthetic nodes that imply accepted semantics.

## 11. Recovery and Diagnostics Integration

Parser recovery may continue after syntax errors for diagnostic collection, but recovered AST must remain:

- structurally coherent,
- attribution-consistent,
- and non-permissive (must not fabricate valid semantics that hide required rejection).

AST-facing diagnostics must follow `12` identity and attribution rules.

For conformance, required diagnostic identity is keyed by stable machine fields, not rendered sentence text.

## 12. Conformance and Gate U Evidence

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

At minimum, Gate U must include:

1. representative valid AST fixtures for mandatory declaration/statement/expression families;
2. malformed/recovery fixtures with deterministic rejection assertions;
3. attribution assertions (`file/start/end`) on required nodes;
4. precedence/associativity shape assertions for representative expressions;
5. mandatory negative families:
   - unexpected token in declaration context,
   - missing required closer (`)`, `}`, or `;`) as applicable,
   - forbidden non-associative chains,
   - unsupported forms outside the active syntax slice.

## 13. Non-Goals

- Freezing one parser implementation architecture.
- Replacing static semantics/linking decisions with AST-only rules.
- Defining backend/runtime/bytecode/verifier behavior.

## 14. Exit Criteria

This document is healthy when:

1. mandatory AST families and metadata are explicit,
2. recovery/rejection invariants are explicit and test-backed,
3. attribution invariants are explicit and test-backed,
4. lowering preconditions consumed by `13` are unambiguous.