# 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]`, `[Frame]`, `[BeforePause]` or `[BeforeResume]`, 6. documentation attribute metadata when a declaration carries `[Doc(markdown = """...""")]`. Missing required attribution or metadata on mandatory nodes is non-conformant. Documentation metadata rules: - The AST MUST preserve the `Doc` attribute name, the `markdown` argument name, the raw documentation text block payload, and source attribution for the whole attribute and payload. - The AST MUST distinguish documentation text block payloads from ordinary string literals. - The AST MUST preserve enough attribution for later diagnostics to point at malformed or invalid `Doc` usage. - AST construction MUST NOT normalize documentation text block content in a way that loses source-observable parse meaning before the semantic normalization step. ## 8. Mandatory Declaration Families The v1 AST must represent, at minimum, declaration families for: - imports, - top-level `fn`, - `struct`, - `contract`, - `service`, - `error`, - `enum`, - structural `Fn` types and lambda expressions with explicit captures, - `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]`, - top-level `fn` marked with `[BeforePause]` or `[BeforeResume]`, - and host method signatures marked with `[InitAllowed]`. Documentation-observable declarations must preserve `Doc` metadata explicitly on every accepted named API declaration surface that carries `[Doc(markdown = """...""")]`. ## 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. ## Typed arrays and optional execution extension The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) defines the complete type, optional-flow and storage contract. This chapter preserves syntax and type arguments in the AST; the owner chapter defines Array application admissibility and execution. Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md) and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax. ## Parameterized contracts Contract declarations and barrel items preserve ordered type-parameter names and individual spans. Applied type references preserve ordered child arguments and spans. Implements and as carry a complete target type reference. Semantic imported bindings retain the original declaration and importing lexical scope rather than inventing nominal origins. Existing visitors must traverse type arguments as well as inner/group/Fn/tuple children. See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md). ## Concrete generic structs and free functions Structs and free functions preserve ordered parameter declarations and spans. Explicit applied function references preserve type arguments and their source span. Implements preserves its binder, full applied owner and target. Substitution rewrites every field, signature, annotation and executable body/capture position with a declaration-local environment. Concrete application provenance retains original declaration, canonical logical arguments and requesting use; it is not an executable runtime template. See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md). ## Guest hook marker identity LifecycleMarker explicitly distinguishes NONE, INIT, FRAME, BEFORE_PAUSE and BEFORE_RESUME and MEMCARD_BOOT. Preserve marker attributes and source spans alongside the marker; never reconstruct the role from a function name or an import alias. Invalid attribute targets/combinations MUST be diagnosed rather than silently treated as ordinary functions. Generic substitution/import processing MUST preserve canonical source identity and marker metadata. The additional MEMCARD_BOOT marker follows the dedicated memcard contract. ## Memcard integration The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>) defines the additional [MemcardBoot] marker, exact signature, neutral once-only bootstrap, project identity/slot validation and complete installed mem ABI. Its requirements apply in addition to this chapter; pause/resume remain independent.