From 8a68a2a025bc1cdb62232dfb92c5a8e785613352 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 5 Mar 2026 07:49:01 +0000 Subject: [PATCH] clean up --- docs/pbs/agendas/archive/11. AST Agenda.md | 99 ----------------- ...orkshop 1 - AST Contract and Root Model.md | 64 ----------- ...shop 2 - Declarations and Type Surfaces.md | 62 ----------- ...Workshop 3 - Statements and Expressions.md | 62 ----------- ...iagnostics, Recovery, and Gate Evidence.md | 67 ------------ ...hop 1 - Lowering Contract and IR Status.md | 102 ------------------ docs/pbs/agendas/archive/README.md | 5 - 7 files changed, 461 deletions(-) delete mode 100644 docs/pbs/agendas/archive/11. AST Agenda.md delete mode 100644 docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md delete mode 100644 docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md delete mode 100644 docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md delete mode 100644 docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md delete mode 100644 docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md delete mode 100644 docs/pbs/agendas/archive/README.md diff --git a/docs/pbs/agendas/archive/11. AST Agenda.md b/docs/pbs/agendas/archive/11. AST Agenda.md deleted file mode 100644 index 46d79c2a..00000000 --- a/docs/pbs/agendas/archive/11. AST Agenda.md +++ /dev/null @@ -1,99 +0,0 @@ -# PBS AST Agenda - -Status: Closed (2026-03-05) - -## Purpose - -Drive closure of `11. AST Specification.md` as the frontend contract between parser output and IRBackend lowering input. - -## Context - -PBS now has syntax and static-semantics rules, but AST needs a sharper normative boundary so implementations and tests stay aligned. - -This agenda focuses on: - -- required AST node families for v1 PBS, -- source-attribution invariants (`file/start/end`) in AST, -- parser recovery constraints, -- and Gate U evidence for AST behavior. - -## Scope Boundary - -In scope: - -- parser-produced AST contract, -- declaration/statement/expression shape obligations, -- source span and parent-child structural invariants, -- AST-facing deterministic rejection behavior. - -Out of scope: - -- full static semantics (owned by `4`), -- IRBackend lowering contract details (owned by `13`), -- VM/runtime/bytecode/verifier/loader concerns. - -## Decisions To Produce - -1. Decide mandatory AST node families for v1 source surface. -2. Decide structural invariants for valid and recovered AST. -3. Decide attribution invariants required for diagnostics and lowering. -4. Decide deterministic parser/AST rejection and recovery boundaries. -5. Decide minimum Gate U fixture evidence for AST. - -## Core Questions - -1. What is the minimum AST contract that all PBS frontends must expose? -2. Which syntax forms must have explicit node-level representation versus deterministic rejection? -3. What AST guarantees must hold even after parser recovery? -4. How strict must span/attribution fidelity be for conformance? -5. Which AST fixtures are mandatory to prevent regression? - -## Proposed Workshop Sequence - -### Workshop 1: AST Contract and Root Model - -- root/file model, -- canonical node-family baseline, -- mandatory attribution fields. - -### Workshop 2: Declarations and Type Surfaces - -- declaration node obligations, -- callable/type/const/module-level declaration shape, -- barrel/linking-facing declaration needs. - -### Workshop 3: Statements and Expressions - -- statement/expression node obligations, -- precedence/associativity representation expectations, -- unsupported-form rejection boundaries. - -### Workshop 4: Diagnostics, Recovery, and Gate Evidence - -- syntax-phase diagnostics attribution from AST, -- recovery invariants, -- Gate U fixture baseline for AST. - -## Expected Spec Material - -The resulting `11` content should close: - -- AST contract baseline, -- structural and attribution invariants, -- recovery/rejection rules, -- and test-evidence hooks for conformance. - -## Non-Goals - -- Freezing one parser implementation architecture. -- Freezing backend/IRVM decisions. -- Replacing static semantics with AST rules. - -## Inputs - -- `docs/pbs/specs/3. Core Syntax Specification.md` -- `docs/pbs/specs/4. Static Semantics Specification.md` -- `docs/pbs/specs/11. AST Specification.md` -- `docs/pbs/specs/12. Diagnostics Specification.md` -- `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/general/specs/13. Conformance Test Specification.md` diff --git a/docs/pbs/agendas/archive/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 deleted file mode 100644 index bce3a156..00000000 --- a/docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md +++ /dev/null @@ -1,64 +0,0 @@ -# PBS AST Workshop 1 - -Status: Closed (2026-03-05) - -## Purpose - -Close the top-level AST contract for `11. AST Specification.md`: - -- file/root model, -- minimum node-family baseline, -- mandatory attribution fields. - -## Decisions To Produce - -1. Root/file node contract and per-file AST boundary. -2. Mandatory attribution fields on AST nodes (`file/start/end`). -3. Which families are mandatory in v1 AST (declaration/statement/expression categories). -4. Contract status: obligations-based versus one mandatory in-memory class hierarchy. - -## Candidate Decisions - -### 1. Obligations-First AST Contract - -- Spec defines required observable AST obligations. -- Internal object model remains implementation-defined. - -### 2. Attribution Is Mandatory - -- Nodes consumed by diagnostics or lowering must carry stable source attribution. -- Missing attribution on mandatory nodes is non-conformant. - -### 3. Root Boundary Is Per Source File - -- Parser output is one root per file. -- Root must preserve deterministic child ordering. - -## Questions To Resolve - -1. Which minimal node families are required immediately for v1 conformance? -2. Which optional node metadata may remain implementation-defined for now? -3. What is the minimum integrity rule for recovered AST after parse errors? - -## Expected Outputs - -1. Decision note on AST contract model. -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/specs/11. AST Specification.md` -- `docs/pbs/specs/12. Diagnostics Specification.md` -- `docs/pbs/agendas/archive/11. AST Agenda.md` diff --git a/docs/pbs/agendas/archive/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 deleted file mode 100644 index 921893ef..00000000 --- a/docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md +++ /dev/null @@ -1,62 +0,0 @@ -# PBS AST Workshop 2 - -Status: Closed (2026-03-05) - -## Purpose - -Close AST obligations for declaration and type-facing source surfaces in frontend scope. - -## Decisions To Produce - -1. Mandatory declaration-node families in v1 AST. -2. Structural rules for declaration nesting and ordering. -3. Deterministic rejection boundaries for unsupported declaration forms. -4. Minimum declaration metadata needed by diagnostics and lowering. - -## Candidate Decisions - -### 1. Declaration Families Are Explicit - -- Top-level callable/type/const/import/module-facing constructs have explicit node families. -- No implicit desugaring that hides declaration identity at AST boundary. - -### 2. Declaration Integrity Rules - -- Parent-child hierarchy and spans must remain coherent. -- Duplicate or malformed declaration syntax remains parser/AST rejection, not silent AST repair. - -### 3. Lowering-Relevant Declaration Metadata - -- Declaration nodes expose minimally required identity/arity/return-surface hooks used by `13`. - -## Questions To Resolve - -1. Which declaration surfaces are mandatory now versus deferred? -2. How much normalization is allowed at AST level before static semantics? -3. Which malformed declaration shapes must still produce recoverable AST? - -## Expected Outputs - -1. Decision note on declaration AST model. -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/specs/4. Static Semantics Specification.md` -- `docs/pbs/specs/11. AST Specification.md` -- `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md` diff --git a/docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md b/docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md deleted file mode 100644 index a35edfe1..00000000 --- a/docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md +++ /dev/null @@ -1,62 +0,0 @@ -# PBS AST Workshop 3 - -Status: Closed (2026-03-05) - -## Purpose - -Close AST obligations for statement and expression surfaces, including precedence/associativity representation and unsupported-form boundaries. - -## Decisions To Produce - -1. Mandatory statement/expression node families for v1 AST. -2. Representation obligations for precedence and associativity outcomes. -3. Deterministic rejection policy for unsupported statement/expression forms. -4. Minimum node consistency rules used by diagnostics and lowering. - -## Candidate Decisions - -### 1. Parsing Outcomes Must Be Visible in AST Shape - -- Precedence and associativity results are reflected by explicit tree shape. -- No hidden post-parse rewrites that change source-observable meaning. - -### 2. Unsupported Forms Are Deterministic Reject - -- Forms outside supported syntax/lowering slice must fail with stable diagnostics. -- They must not collapse into permissive placeholder AST nodes. - -### 3. AST Consistency for Downstream Use - -- Statement/expression nodes needed by static semantics and lowering must always carry coherent spans and child structure. - -## Questions To Resolve - -1. Which expression forms are mandatory in v1 AST conformance? -2. Which recoveries are acceptable without masking parse errors? -3. What exact AST checks should Gate U fixtures assert? - -## Expected Outputs - -1. Decision note on statement/expression AST model. -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/specs/11. AST Specification.md` -- `docs/pbs/specs/12. Diagnostics Specification.md` -- `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md` diff --git a/docs/pbs/agendas/archive/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 deleted file mode 100644 index bf964681..00000000 --- a/docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md +++ /dev/null @@ -1,67 +0,0 @@ -# PBS AST Workshop 4 - -Status: Closed (2026-03-05) - -## Purpose - -Close AST-facing diagnostics/recovery rules and Gate U evidence needed to finalize the AST contract. - -## Decisions To Produce - -1. Required diagnostics attribution behavior sourced from AST. -2. Recovery invariants for parser output after syntax errors. -3. Mandatory AST fixture corpus for Gate U evidence. -4. Explicit deferred list for non-AST concerns. - -## Candidate Decisions - -### 1. AST Must Sustain Diagnostics Fidelity - -- Primary attribution for syntax diagnostics must remain stable and source-anchored. -- Cross-file related spans are attached when required by diagnostics rules. - -### 2. Recovery Must Preserve Structural Integrity - -- Recovered AST may be partial, but must remain structurally coherent. -- Recovery must not fabricate semantically valid shapes that hide syntax failure. - -### 3. Gate U Evidence Baseline - -- AST conformance evidence includes representative valid trees, invalid/recovery cases, and attribution assertions. - -## Questions To Resolve - -1. Which recovery behaviors are mandatory versus implementation-defined? -2. What is the minimum fixture set to prevent AST regressions? -3. Which AST-facing diagnostics codes must be frozen now? - -## Expected Outputs - -1. Decision note on AST diagnostics/recovery policy. -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`), -- backend/runtime/verifier concerns, -- compatibility/publication policy. - -## Inputs - -- `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/archive/11.3. AST Workshop 3 - Statements and Expressions.md` diff --git a/docs/pbs/agendas/archive/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 deleted file mode 100644 index c45d6293..00000000 --- a/docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md +++ /dev/null @@ -1,102 +0,0 @@ -# PBS Frontend IR and Lowering Workshop 1 - -Status: Closed (2026-03-05) - -## Purpose - -Run the first focused discussion for `13. Lowering IRBackend Specification.md` in frontend scope: - -- what frontend lowering consumes, -- what frontend lowering must produce, -- and whether one canonical frontend IR shape is required. - -## Why This Slice First - -Every later workshop depends on a stable contract for: - -- preconditions before lowering, -- and which frontend IR obligations are normative. - -## Proposed Meeting Order - -1. Reconfirm frontend-only scope boundary for agenda 13. -2. Close minimum preconditions before frontend lowering starts. -3. Close normative status of frontend IR shape versus obligations. -4. Close minimum preserved semantic facts for v1. -5. Record construct-specific gaps for Workshops 2 to 4. - -## Decisions To Produce - -1. Normative status of frontend IR in v1. -2. Required input state before frontend lowering begins. -3. Minimum preserved semantic facts at frontend-lowering boundary. -4. Minimum deterministic rejection policy for unsupported lowering inputs. - -## Candidate Decisions - -### 1. Standardize Preserved Obligations, Not One In-Memory Class Graph - -Candidate direction: - -- v1 standardizes preserved frontend obligations and observable outcomes, -- not one mandatory Java object model. - -### 2. Frontend Lowering Requires Fully Parsed and Linked Source - -Candidate direction: - -- parser and linking outcomes are already complete, -- type/name diagnostics already produced where required, -- and lowering does not invent unresolved semantic answers. - -### 3. Minimum Preserved Facts For V1 Frontend IR - -Candidate direction: - -- callable identity, -- parameter arity, -- declared return surface, -- and source attribution anchor (`file + span`) for diagnostics. - -### 4. Unsupported Constructs Must Fail Deterministically - -Candidate direction: - -- constructs outside v1 frontend-lowering slice fail with stable diagnostics, -- never silently degrade into partial/implicit behavior. - -## Questions To Resolve In The Room - -1. Which facts are mandatory in v1 `IRFunction` versus optional? -2. Is obligations-only precise enough for conformance tests? -3. Which rejected constructs must already have fixed diagnostic codes? -4. What is the exact pass/fail boundary between parser/linking and frontend lowering errors? - -## Expected Outputs - -1. a decision note on frontend IR normative status, -2. a decision note on lowering preconditions, -3. and a checklist of preserved frontend-lowering obligations. - -## Decision Outcome (2026-03-05) - -1. `13` remains normative by preserved obligations, not by one mandatory in-memory IR shape. -2. Frontend lowering starts only after parse/linking completion and required prior diagnostics. -3. Minimum v1 frontend IR facts are mandatory: callable identity, arity, declared return surface, and source anchor (`file + span`). -4. Unsupported frontend-lowering forms must fail deterministically with stable diagnostics. -5. Scope boundary confirmed: `IRBackend` is the first lowering (frontend responsibility); `IRVM` is a later lowering (backend responsibility) and is out of `13` agenda scope. -6. Evidence baseline confirmed for now: Gate U only (`lexer/parser/AST/IRBackend/diagnostics`), without S-U requirement at this stage. -7. Conformance-valid IR claim rule: only when the full PBS spec surface is implemented at `IRBackend` level. - -## Explicit Deferrals For Workshop 2 - -- expression/control-flow construct mapping details, -- and propagation construct obligations. - -## Inputs - -- `docs/pbs/specs/4. Static Semantics Specification.md` -- `docs/pbs/specs/12. Diagnostics Specification.md` -- `docs/pbs/specs/13. Lowering IRBackend Specification.md` -- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/agendas/13. IR and Lowering Agenda.md` diff --git a/docs/pbs/agendas/archive/README.md b/docs/pbs/agendas/archive/README.md deleted file mode 100644 index bfbaf982..00000000 --- a/docs/pbs/agendas/archive/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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.