Support explicit contract type parameters, canonical nominal applications, recursive substitution, concrete implementations and instantiated editor views. Complete parametric Array syntax and contextual construction integration. Preserve type origins across imports and reexports, fix trait argument stack order, and relocate global slots before lifecycle assembly. Publish specs, installed examples and consolidated discussion lessons. Validate frontend, common pipeline, architecture, LSP and installed knowledge gates, plus the full production VM conformance corpus with 14 generic fixtures.
192 lines
7.9 KiB
Markdown
192 lines
7.9 KiB
Markdown
# 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]`,
|
|
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]`,
|
|
- 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 [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
|
|
|
|
Array syntax uses `array<T>` with compositional nesting. Explicit `new array<T>(n)` supplies its type; `new array<>(n)` and `new array(n)` use the expected type. The [Array contract](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines contextual closers, spans, invariant validation and lowering; obsolete Array spellings are rejected.
|
|
|
|
|
|
## 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](../../../compiler/pbs/specs/generic-contracts.md).
|