106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# 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.
|