prometeu-studio/docs/specs/compiler-languages/pbs/11. AST Specification.md

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.