diff --git a/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md b/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md index 1cb1ad1a..a89410ca 100644 --- a/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md +++ b/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md @@ -83,4 +83,4 @@ Candidate direction: - `docs/pbs/specs/12. Diagnostics Specification.md` - `docs/pbs/specs/13. Lowering IRBackend Specification.md` - `docs/general/specs/13. Conformance Test Specification.md` -- `docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md` +- `docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md` diff --git a/docs/pbs/agendas/README.md b/docs/pbs/agendas/README.md index 62348f26..fef94f28 100644 --- a/docs/pbs/agendas/README.md +++ b/docs/pbs/agendas/README.md @@ -2,6 +2,8 @@ This directory contains active PBS discussion agendas. +Closed agendas are moved to `docs/pbs/agendas/archive`. + ## Purpose An agenda exists to drive a decision, not to serve as final normative text. @@ -13,7 +15,7 @@ Use an agenda when: - the scope and non-goals need to be made explicit, - the order of discussion matters. -Remove an agenda from this directory once the topic is no longer active. +Move an agenda to `docs/pbs/agendas/archive` once the topic is no longer active. ## Expected Format diff --git a/docs/pbs/agendas/11. AST Agenda.md b/docs/pbs/agendas/archive/11. AST Agenda.md similarity index 99% rename from docs/pbs/agendas/11. AST Agenda.md rename to docs/pbs/agendas/archive/11. AST Agenda.md index ff99a932..46d79c2a 100644 --- a/docs/pbs/agendas/11. AST Agenda.md +++ b/docs/pbs/agendas/archive/11. AST Agenda.md @@ -1,6 +1,6 @@ # PBS AST Agenda -Status: Active +Status: Closed (2026-03-05) ## Purpose diff --git a/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md b/docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md similarity index 97% rename from docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md rename to docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md index 923e6035..bce3a156 100644 --- a/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md +++ b/docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md @@ -61,4 +61,4 @@ Decision record: `docs/pbs/decisions/AST Contract and Root Model Decision.md`. - `docs/pbs/specs/3. Core Syntax Specification.md` - `docs/pbs/specs/11. AST Specification.md` - `docs/pbs/specs/12. Diagnostics Specification.md` -- `docs/pbs/agendas/11. AST Agenda.md` +- `docs/pbs/agendas/archive/11. AST Agenda.md` diff --git a/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md b/docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md similarity index 97% rename from docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md rename to docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md index 6c94264e..921893ef 100644 --- a/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md +++ b/docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md @@ -59,4 +59,4 @@ Decision record: `docs/pbs/decisions/AST Declarations and Type Surfaces Decision - `docs/pbs/specs/4. Static Semantics Specification.md` - `docs/pbs/specs/11. AST Specification.md` - `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md` +- `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md` diff --git a/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md b/docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md similarity index 96% rename from docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md rename to docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md index 3dccee73..a35edfe1 100644 --- a/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md +++ b/docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md @@ -59,4 +59,4 @@ Decision record: `docs/pbs/decisions/AST Statements and Expressions Decision.md` - `docs/pbs/specs/11. AST Specification.md` - `docs/pbs/specs/12. Diagnostics Specification.md` - `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` +- `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` diff --git a/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md b/docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md similarity index 97% rename from docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md rename to docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md index dd25400b..bf964681 100644 --- a/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md +++ b/docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md @@ -64,4 +64,4 @@ Decision record: `docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidenc - `docs/pbs/specs/11. AST Specification.md` - `docs/pbs/specs/12. Diagnostics Specification.md` - `docs/general/specs/13. Conformance Test Specification.md` -- `docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md` +- `docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md` diff --git a/docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md b/docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md similarity index 100% rename from docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md rename to docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md diff --git a/docs/pbs/agendas/archive/README.md b/docs/pbs/agendas/archive/README.md new file mode 100644 index 00000000..bfbaf982 --- /dev/null +++ b/docs/pbs/agendas/archive/README.md @@ -0,0 +1,5 @@ +# PBS Archived Agendas + +This directory stores closed PBS agendas that are no longer part of the active discussion set. + +Use these files as historical context for decisions and spec updates. diff --git a/docs/pbs/decisions/AST Contract and Root Model Decision.md b/docs/pbs/decisions/AST Contract and Root Model Decision.md index af89ad5e..c5f14fcb 100644 --- a/docs/pbs/decisions/AST Contract and Root Model Decision.md +++ b/docs/pbs/decisions/AST Contract and Root Model Decision.md @@ -2,7 +2,7 @@ Status: Accepted Date: 2026-03-05 -Related Agenda: `docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md` +Related Agenda: `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md` ## Context diff --git a/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md b/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md index 2f488e47..31f4ff11 100644 --- a/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md +++ b/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md @@ -2,7 +2,7 @@ Status: Accepted Date: 2026-03-05 -Related Agenda: `docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` +Related Agenda: `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` ## Context diff --git a/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md b/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md index 636e1daa..e2b479d9 100644 --- a/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md +++ b/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md @@ -2,7 +2,7 @@ Status: Accepted Date: 2026-03-05 -Related Agenda: `docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md` +Related Agenda: `docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md` ## Context diff --git a/docs/pbs/decisions/AST Statements and Expressions Decision.md b/docs/pbs/decisions/AST Statements and Expressions Decision.md index c65bf8bc..ee3b14a1 100644 --- a/docs/pbs/decisions/AST Statements and Expressions Decision.md +++ b/docs/pbs/decisions/AST Statements and Expressions Decision.md @@ -2,7 +2,7 @@ Status: Accepted Date: 2026-03-05 -Related Agenda: `docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md` +Related Agenda: `docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md` ## Context diff --git a/docs/pbs/specs/11. AST Specification.md b/docs/pbs/specs/11. AST Specification.md index b9e3351b..ae34f0ff 100644 --- a/docs/pbs/specs/11. AST Specification.md +++ b/docs/pbs/specs/11. AST Specification.md @@ -1,33 +1,29 @@ # PBS AST Specification -Status: Draft v0 +Status: Draft v1 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. +This document defines the mandatory AST contract between PBS parsing and frontend lowering to `IRBackend`. -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. +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: -- 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. +- 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 type rules, -- VM/runtime execution behavior, -- bytecode/PBX mapping, -- or backend-specific IR/optimizer internals. +- static-semantics algorithms, +- runtime/bytecode/verifier behavior, +- or `IRBackend -> IRVM` lowering. ## 3. Authority and Precedence @@ -36,10 +32,10 @@ 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 +4. This document +5. `13. Lowering IRBackend Specification.md` -If a rule here conflicts with higher-precedence syntax or semantic rules, the higher-precedence rule wins. +If a rule here conflicts with a higher-precedence source, the higher-precedence rule wins. ## 4. Normative Inputs @@ -50,56 +46,115 @@ This document depends on: - `12. Diagnostics Specification.md` - `13. Lowering IRBackend Specification.md` -## 5. AST Contract Baseline +## 5. AST Contract Model -At minimum, parser output must provide: +The AST contract is defined by required observable behavior, not by one mandatory class hierarchy or parser architecture. -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. +Conformance is implementation-language agnostic. -## 6. Structural Invariants +## 6. Root and Structural Invariants -Minimum structural invariants: +Parser output must satisfy all of the following: -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. +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. Diagnostics Integration +## 7. Mandatory Attribution and Declaration Metadata -AST-related diagnostics must follow `12. Diagnostics Specification.md`: +Every node consumed by diagnostics or lowering must carry stable source attribution: -- stable `diagnostic code`, -- stable `severity`, -- stable primary source attribution. +- `file`, +- `start`, +- `end`. -Parser/AST diagnostics are in `syntax` phase unless another higher-precedence rule assigns a different phase. +Mandatory declaration metadata on required declaration nodes includes: -## 8. Conformance and Test Evidence +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. + +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 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). + +## 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/general/specs/13. Conformance Test Specification.md`. -At minimum, fixtures must cover: +At minimum, Gate U must include: -1. representative valid AST shapes, -2. deterministic syntax rejection and recovery behavior, -3. stable source attribution for required diagnostics. +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. -## 9. Non-Goals +## 13. Non-Goals -- Defining one programming-language-neutral AST framework. - Freezing one parser implementation architecture. -- Encoding runtime behavior in AST rules. +- Replacing static semantics/linking decisions with AST-only rules. +- Defining backend/runtime/bytecode/verifier behavior. -## 10. Exit Criteria +## 14. 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. +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. diff --git a/docs/pbs/specs/12. Diagnostics Specification.md b/docs/pbs/specs/12. Diagnostics Specification.md index 18071ccc..ac833182 100644 --- a/docs/pbs/specs/12. Diagnostics Specification.md +++ b/docs/pbs/specs/12. Diagnostics Specification.md @@ -117,10 +117,14 @@ The stable identity of a diagnostic is carried primarily by: - `diagnostic code`, - stable phase attribution, +- `message template id`, +- primary attribution, - and the rejection-class semantics represented by the code/template pair. Human wording alone is not the identity of the diagnostic. +Conformance assertions must key diagnostics by stable machine fields (`code`, `phase`, `message template id`, attribution), not by localized rendered sentence text. + ## 8. Cross-File Attribution, Notes, and Hint Surface Cross-file attribution follows an action-first rule. @@ -156,6 +160,8 @@ However: This allows implementations to localize diagnostics while preserving conformance-friendly identity. +Human-readable messages may be rendered from locale-specific templates, but template/token identity remains stable across locales. + Implementations should preserve the ability to render an English default or fallback message for future interoperability-oriented transports such as a possible LSP integration, even when the local product surface renders another language by default. Examples in this specification are illustrative unless explicitly marked normative. @@ -226,6 +232,6 @@ These are not licenses to weaken the required external fields defined above. This document is ready to move beyond temporary status only when: 1. every required rejection in the current spec set is mapped to a diagnostic phase, -2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, +2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, including locale-agnostic token/template identity, 3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures, 4. and cost/warning expectations are explicit where they are intended to be normative for v1. diff --git a/docs/pbs/specs/13. Lowering IRBackend Specification.md b/docs/pbs/specs/13. Lowering IRBackend Specification.md index d9cdb435..5ec8c008 100644 --- a/docs/pbs/specs/13. Lowering IRBackend Specification.md +++ b/docs/pbs/specs/13. Lowering IRBackend Specification.md @@ -14,6 +14,7 @@ Its purpose is to keep the first lowering deterministic and shared across implem This document defines: - required preconditions before lowering starts, +- AST invariants that lowering may assume as hard contract, - semantic obligations preserved in `IRBackend`, - deterministic rejection behavior for unsupported frontend-lowering forms, - and diagnostics attribution obligations for lowering failures in frontend scope. @@ -54,19 +55,28 @@ Frontend lowering into `IRBackend` may start only when: 1. source has been tokenized and parsed, 2. required syntax diagnostics have been emitted, -3. linking/name-resolution outcomes required for the current lowering slice are available, -4. and no unresolved semantic ambiguity is deferred to lowering. +3. AST output satisfies `11` required invariants for this source unit, including: + - one root per file, + - deterministic child ordering, + - mandatory node attribution (`file/start/end`) on nodes consumed by lowering, + - mandatory declaration metadata on declaration nodes required by the active source slice, + - and structural coherence after any parser recovery. +4. linking/name-resolution outcomes required for the current lowering slice are available, +5. and no unresolved semantic ambiguity is deferred to lowering. Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases. ## 6. IRBackend Preserved Obligations -For each callable admitted by the current lowering slice, `IRBackend` must preserve at minimum: +For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum: 1. callable identity (name/category as applicable), 2. callable arity, 3. declared return surface information, -4. source attribution anchor (`file + span`) for diagnostics and traceability. +4. source attribution anchor (`file + span`) for diagnostics and traceability, +5. source-observable parse intent for statement/expression structure (including precedence/associativity outcome already fixed by AST shape). + +Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions. The normative contract is obligation-based, not tied to one mandatory in-memory class graph. @@ -75,14 +85,25 @@ The normative contract is obligation-based, not tied to one mandatory in-memory If a source form is outside current frontend-lowering support: 1. rejection must be deterministic, -2. diagnostics must expose stable `code`, `severity`, and primary attribution, +2. diagnostics must expose stable `code`, `severity`, `phase`, `message template id`, and primary attribution, 3. and unsupported forms must not silently degrade into different valid lowered behavior. +Lowering must not convert a required syntax/static rejection into accepted lowered behavior. + ## 8. Conformance Boundary `IRBackend` is the first lowering boundary (frontend responsibility). -Conformance-valid claims at this boundary require evidence from `docs/general/specs/13. Conformance Test Specification.md` and must only be published when the full claimed PBS surface is implemented at `IRBackend` level. +Conformance-valid claims at this boundary require Gate U evidence from `docs/general/specs/13. Conformance Test Specification.md`. + +For this frontier, Gate U evidence is expected to cover at minimum: + +- lexer behavior for covered inputs, +- parser behavior and AST shape invariants required by `11`, +- lowering outcomes at `IRBackend` boundary, +- and deterministic diagnostics identity/attribution for rejection cases. + +Conformance at this boundary may be claimed only when the full claimed PBS source surface is implemented at `IRBackend` level. ## 9. Explicit Deferrals