agendas, decisions and specs changes

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`

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
 

docs/pbs/agendas/archive/11. AST Agenda.md

@@ -1,6 +1,6 @@
 # PBS AST Agenda
 
-Status: Active
+Status: Closed (2026-03-05)
 
 ## Purpose
 

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`

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`

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`

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`

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.

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
 

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
 

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
 

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
 

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.

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.

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