agendas, decisions and specs changes

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`

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`

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`

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`),

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.

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.

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.

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.