From 4f48bd7b46be4192a1b6cee3b0d01b3930ff52f3 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 5 Mar 2026 06:17:10 +0000 Subject: [PATCH] agendas, decisions and specs changes --- ...orkshop 1 - AST Contract and Root Model.md | 12 +++- ...shop 2 - Declarations and Type Surfaces.md | 14 +++- ...Workshop 3 - Statements and Expressions.md | 14 +++- ...iagnostics, Recovery, and Gate Evidence.md | 14 +++- .../AST Contract and Root Model Decision.md | 53 ++++++++++++++ ...Declarations and Type Surfaces Decision.md | 69 +++++++++++++++++++ ...s, Recovery, and Gate Evidence Decision.md | 64 +++++++++++++++++ ...AST Statements and Expressions Decision.md | 51 ++++++++++++++ 8 files changed, 287 insertions(+), 4 deletions(-) create mode 100644 docs/pbs/decisions/AST Contract and Root Model Decision.md create mode 100644 docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md create mode 100644 docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md create mode 100644 docs/pbs/decisions/AST Statements and Expressions Decision.md diff --git a/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md b/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md index 972fef50..923e6035 100644 --- a/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md +++ b/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md @@ -1,6 +1,6 @@ # PBS AST Workshop 1 -Status: Active +Status: Closed (2026-03-05) ## Purpose @@ -46,6 +46,16 @@ Close the top-level AST contract for `11. AST Specification.md`: 2. Decision note on attribution minimums. 3. Section targets for `11. AST Specification.md`. +## Decision Outcome (2026-03-05) + +Decision record: `docs/pbs/decisions/AST Contract and Root Model Decision.md`. + +1. `11` standardizes AST by observable obligations, not by one mandatory Java/in-memory class hierarchy. +2. AST root boundary is one root per source file with deterministic child order. +3. Nodes consumed by diagnostics or lowering must carry `file/start/end`. +4. Mandatory v1 families are declaration/statement/expression categories for the supported source slice. +5. Unsupported forms are deterministic reject and must not be masked by permissive synthetic AST. + ## Inputs - `docs/pbs/specs/3. Core Syntax Specification.md` diff --git a/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md b/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md index fd405764..6c94264e 100644 --- a/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md +++ b/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md @@ -1,6 +1,6 @@ # PBS AST Workshop 2 -Status: Active +Status: Closed (2026-03-05) ## Purpose @@ -41,6 +41,18 @@ Close AST obligations for declaration and type-facing source surfaces in fronten 2. Decision note on declaration rejection/recovery boundaries. 3. Fixture targets for declaration AST coverage. +## Decision Outcome (2026-03-05) + +Decision record: `docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md`. + +1. Mandatory declaration families for v1 include imports, top-level `fn`, `struct`, `contract`, `service`, `error`, `enum`, `callback`, `declare const`, and declaration nodes required by barrel/linking flow. +2. Declaration identity is preserved in AST; no premature merge/collapse of declarations (including overload sets). +3. Declaration metadata minimums are name, declared signature/surface when applicable, stable source attribution (`file/start/end`), and required syntactic flags/attributes. +4. AST keeps structural contract; static semantics/linking own compatibility and resolution decisions. +5. Unsupported declaration forms are deterministic parser/AST rejection with stable diagnostics. +6. Recovery is allowed, but recovered AST must remain structurally coherent with consistent attribution. +7. Gate U evidence requires positive/negative declaration fixtures with AST-shape, attribution, and diagnostics assertions. + ## Inputs - `docs/pbs/specs/3. Core Syntax Specification.md` diff --git a/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md b/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md index e957616d..3dccee73 100644 --- a/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md +++ b/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md @@ -1,6 +1,6 @@ # PBS AST Workshop 3 -Status: Active +Status: Closed (2026-03-05) ## Purpose @@ -41,6 +41,18 @@ Close AST obligations for statement and expression surfaces, including precedenc 2. Decision note on unsupported-form policy. 3. Fixture targets for precedence/associativity and rejection cases. +## Decision Outcome (2026-03-05) + +Decision record: `docs/pbs/decisions/AST Statements and Expressions Decision.md`. + +1. Mandatory statement/expression node families cover the supported v1 PBS syntax slice, including `block`, `let`, `return`, expression statement, `identifier`, literals, `unary`, `binary`, `call`, and `group`. +2. Precedence and associativity outcomes are normative via AST shape. +3. Non-associative/forbidden chained forms are deterministic reject with stable diagnostics. +4. AST remains structural; semantic compatibility/type rules stay in static semantics/linking. +5. Unsupported forms are deterministic reject and cannot be masked by permissive placeholder nodes. +6. Recovery is allowed, but recovered AST must remain structurally coherent with stable attribution. +7. Gate U evidence requires positive/negative fixtures with AST-shape and diagnostics assertions. + ## Inputs - `docs/pbs/specs/3. Core Syntax Specification.md` diff --git a/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md b/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md index 46585c43..dd25400b 100644 --- a/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md +++ b/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md @@ -1,6 +1,6 @@ # PBS AST Workshop 4 -Status: Active +Status: Closed (2026-03-05) ## Purpose @@ -41,6 +41,18 @@ Close AST-facing diagnostics/recovery rules and Gate U evidence needed to finali 2. Decision note on Gate U AST evidence baseline. 3. Closure checklist for `11. AST Specification.md`. +## Decision Outcome (2026-03-05) + +Decision record: `docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md`. + +1. AST-facing syntax diagnostics must remain stable by identity (`code`, `severity`, `phase`, primary attribution). +2. Human message text is locale-dependent and not the conformance identity key. +3. Stable i18n identity is token/template-id based, aligned with diagnostics contract fields. +4. Recovery is allowed for continued diagnostics, but recovered AST must stay structurally coherent with consistent attribution. +5. Recovery must not mask real syntax failure by fabricating permissive valid AST shapes. +6. Gate U AST evidence must include valid fixtures, malformed/recovery fixtures, diagnostics assertions, and attribution assertions. +7. Mandatory negative fixture families include unexpected tokens, missing closers, forbidden non-associative chains, and unsupported forms with deterministic rejection. + ## Explicit Deferrals - IRBackend lowering details (owned by `13`), diff --git a/docs/pbs/decisions/AST Contract and Root Model Decision.md b/docs/pbs/decisions/AST Contract and Root Model Decision.md new file mode 100644 index 00000000..af89ad5e --- /dev/null +++ b/docs/pbs/decisions/AST Contract and Root Model Decision.md @@ -0,0 +1,53 @@ +# AST Contract and Root Model Decision + +Status: Accepted +Date: 2026-03-05 +Related Agenda: `docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md` + +## Context + +PBS introduced `11. AST Specification.md` as the language-specific AST layer between parser output and frontend lowering to `IRBackend`. + +The open question was whether AST should be standardized by one mandatory implementation model (for example one Java class hierarchy) or by observable contract obligations. + +## Decision + +PBS adopts an obligations-first AST contract. + +The specification standardizes required observable AST behavior and invariants, not one mandatory in-memory representation. + +The following are required: + +1. one AST root per source file; +2. deterministic child ordering consistent with source order; +3. mandatory source attribution (`file`, `start`, `end`) on nodes consumed by diagnostics or lowering; +4. explicit declaration/statement/expression node families for the supported v1 source slice; +5. deterministic rejection for unsupported forms, without permissive synthetic AST that hides rejection. + +## Invariants + +1. AST conformance is implementation-language agnostic. +2. Missing required attribution on mandatory nodes is non-conformant. +3. Parser recovery may produce partial AST, but structural integrity must remain valid for continued diagnostics. +4. Lowering and diagnostics are allowed to depend on the required AST invariants above. + +## Explicit Non-Decisions + +1. This decision does not freeze one parser architecture. +2. This decision does not define full static-semantics rules. +3. This decision does not define `IRBackend -> IRVM` lowering. +4. This decision does not define runtime/bytecode/verifier policies. + +## Spec Impact + +1. `docs/pbs/specs/11. AST Specification.md` must encode the obligations-first contract and invariants. +2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for diagnostic identity/phase/attribution payload rules consumed by AST-facing diagnostics. +3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume the mandatory AST invariants as lowering preconditions. + +## Validation Notes + +At minimum, Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include: + +1. valid AST shape fixtures for representative declarations/statements/expressions; +2. deterministic syntax rejection fixtures with stable diagnostics; +3. attribution checks (`file/start/end`) on nodes required by diagnostics and lowering. diff --git a/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md b/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md new file mode 100644 index 00000000..2f488e47 --- /dev/null +++ b/docs/pbs/decisions/AST Declarations and Type Surfaces Decision.md @@ -0,0 +1,69 @@ +# AST Declarations and Type Surfaces Decision + +Status: Accepted +Date: 2026-03-05 +Related Agenda: `docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` + +## Context + +After closing the AST contract/root model, PBS needed a precise declaration-layer AST decision for v1 so parser output, diagnostics, and IRBackend lowering remain aligned. + +The open points were: + +- mandatory declaration families in AST, +- declaration identity preservation, +- declaration metadata requirements for downstream phases, +- AST/static-semantics phase boundary, +- rejection and recovery behavior for malformed declarations, +- and minimum Gate U evidence. + +## Decision + +PBS adopts the following declaration/type-surface AST policy for v1: + +1. Mandatory declaration families include: + - imports, + - top-level `fn`, + - `struct`, `contract`, `service`, `error`, `enum`, `callback`, + - `declare const`, + - and declaration nodes required by barrel/linking flow. +2. Declaration identity is preserved at AST boundary; implementations must not prematurely merge declarations (including overload sets). +3. Minimum declaration metadata includes: + - declaration name, + - declared signature/surface (parameters/return when applicable), + - stable source attribution (`file/start/end`), + - and required declaration-level syntactic flags/attributes needed by later phases. +4. AST/static boundary is explicit: + - AST preserves structure, + - static/linking phases own semantic compatibility and resolution rules. +5. Unsupported declaration forms are deterministic parser/AST rejection with stable diagnostics. +6. Recovery may continue after declaration syntax errors, but recovered AST must remain structurally coherent and attribution-consistent. +7. Gate U evidence must include positive and negative declaration fixtures with AST-shape, attribution, and diagnostics assertions. + +## Invariants + +1. Declaration AST remains obligations-first and implementation-language agnostic. +2. Overload identity is not collapsed at AST layer. +3. Missing required declaration metadata on mandatory nodes is non-conformant. +4. Recovery must not fabricate permissive declaration shapes that hide syntax failures. + +## Explicit Non-Decisions + +1. This decision does not define static type-checking algorithms. +2. This decision does not define lowering from `IRBackend` to `IRVM`. +3. This decision does not define runtime/bytecode/verifier policy. +4. This decision does not freeze one parser architecture. + +## Spec Impact + +1. `docs/pbs/specs/11. AST Specification.md` must encode declaration families, identity preservation, metadata minimums, and recovery/rejection invariants. +2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostic identity/phase/attribution semantics consumed by declaration diagnostics. +3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume declaration metadata invariants as lowering preconditions. + +## Validation Notes + +Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include: + +1. valid declaration fixtures for each mandatory family, +2. malformed declaration fixtures with deterministic rejection diagnostics, +3. AST assertions for declaration identity, spans, and required metadata fields. 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 new file mode 100644 index 00000000..636e1daa --- /dev/null +++ b/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md @@ -0,0 +1,64 @@ +# AST Diagnostics, Recovery, and Gate Evidence Decision + +Status: Accepted +Date: 2026-03-05 +Related Agenda: `docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md` + +## Context + +After closing AST contract, declaration surfaces, and statement/expression surfaces, PBS needed to close AST-facing diagnostics and parser-recovery policy plus the minimum Gate U evidence baseline. + +Additionally, localization policy needed explicit alignment: diagnostics wording is locale-dependent and should be keyed by stable message tokens/template ids. + +## Decision + +PBS adopts the following AST diagnostics/recovery/evidence policy: + +1. AST must preserve diagnostic fidelity: + - required syntax diagnostics remain stable in `code`, `severity`, `phase`, `primary file`, and `primary span`. +2. Human-readable message text is locale/rendering-dependent and not a conformance identity key. +3. Stable diagnostics identity for i18n is carried by: + - `diagnostic code`, + - `phase`, + - `message template id` (token), + - and primary attribution. +4. Parser recovery is allowed to continue diagnostics, but recovered AST must remain structurally coherent and attribution-consistent. +5. Recovery must not fabricate permissive valid shapes that hide real syntax failures. +6. Gate U AST evidence must include: + - representative valid AST fixtures, + - malformed/recovery fixtures, + - deterministic diagnostics assertions, + - and attribution assertions (`file/start/end`) on required nodes. +7. Minimum mandatory negative fixture families include: + - unexpected token in declaration context, + - missing required closer (`)`, `}`, or `;`) as applicable, + - non-associative forbidden chain forms, + - unsupported form outside the active syntax slice with deterministic rejection. + +## Invariants + +1. Diagnostics identity is token-based and locale-agnostic. +2. Recovery cannot downgrade a required rejection into accepted semantics. +3. AST attribution quality remains sufficient for `12` diagnostics contract and `13` lowering preconditions. +4. Gate U fixtures must lock rejection stability for required AST-facing failures. + +## Explicit Non-Decisions + +1. This decision does not define transport-specific wire schemas. +2. This decision does not define static type-checking rules. +3. This decision does not define backend/runtime/verifier algorithms. +4. This decision does not require one exact localized wording set. + +## Spec Impact + +1. `docs/pbs/specs/11. AST Specification.md` must encode recovery integrity and AST-facing rejection/recovery invariants. +2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostics identity fields, including template/token identity. +3. `docs/general/specs/13. Conformance Test Specification.md` provides Gate U evidence obligations referenced here. + +## Validation Notes + +Gate U validation should assert: + +1. stable diagnostic identity keys (`code`, `phase`, template/token id, primary attribution), +2. recovery integrity without semantic masking, +3. deterministic results for the mandatory negative fixture families above. diff --git a/docs/pbs/decisions/AST Statements and Expressions Decision.md b/docs/pbs/decisions/AST Statements and Expressions Decision.md new file mode 100644 index 00000000..c65bf8bc --- /dev/null +++ b/docs/pbs/decisions/AST Statements and Expressions Decision.md @@ -0,0 +1,51 @@ +# AST Statements and Expressions Decision + +Status: Accepted +Date: 2026-03-05 +Related Agenda: `docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md` + +## Context + +After closing AST contract/root and declaration surfaces, PBS needed a precise v1 decision for statement/expression AST obligations, including precedence/associativity representation, unsupported-form behavior, and Gate U evidence. + +## Decision + +PBS adopts the following statement/expression AST policy for v1: + +1. Mandatory statement/expression AST families must cover the supported PBS core syntax slice, including at minimum: + - statements: `block`, `let`, `return`, expression statement, and other supported statement forms; + - expressions: `identifier`, literals, `unary`, `binary`, `call`, `group`, and other supported expression forms. +2. Precedence and associativity parsing outcomes are normative via AST shape and must be preserved explicitly. +3. Non-associative or forbidden chained forms are deterministic reject with stable diagnostics. +4. AST remains structural; semantic compatibility/type decisions are owned by static semantics/linking phases. +5. Unsupported statement/expression forms are deterministic reject and must not be represented by permissive synthetic placeholder nodes that mask real rejection. +6. Parser recovery may continue after syntax errors, but recovered AST must remain structurally coherent with stable attribution. +7. Gate U evidence must include positive and negative fixtures with AST-shape assertions and diagnostics assertions. + +## Invariants + +1. Statement/expression AST obligations are implementation-language agnostic. +2. AST shape must not be post-rewritten in a way that changes source-observable parse meaning. +3. Required nodes for diagnostics/lowering must preserve stable `file/start/end`. +4. Recovery must preserve integrity and must not silently convert invalid syntax into valid semantics. + +## Explicit Non-Decisions + +1. This decision does not define static type-checking algorithms. +2. This decision does not define `IRBackend -> IRVM` lowering. +3. This decision does not define runtime/bytecode/verifier policy. +4. This decision does not freeze one parser implementation strategy. + +## Spec Impact + +1. `docs/pbs/specs/11. AST Specification.md` must encode statement/expression node-family obligations, precedence/associativity shape obligations, and recovery/rejection invariants. +2. `docs/pbs/specs/12. Diagnostics Specification.md` remains the authority for stable diagnostics identity/phase/attribution requirements. +3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume statement/expression AST invariants as lowering preconditions. + +## Validation Notes + +Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include: + +1. valid fixtures proving expected precedence/associativity AST shape; +2. invalid fixtures for non-associative or unsupported forms with deterministic diagnostics; +3. assertions for stable node attribution (`file/start/end`) where diagnostics and lowering consume those nodes.