From da238000e6df725e89414f034544f55bbfc20f74 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 5 Mar 2026 05:17:01 +0000 Subject: [PATCH] agendas, decisions and specs changes --- docs/pbs/agendas/11. AST Agenda.md | 99 +++++++++++++++++++ ...orkshop 1 - AST Contract and Root Model.md | 54 ++++++++++ ...shop 2 - Declarations and Type Surfaces.md | 50 ++++++++++ ...Workshop 3 - Statements and Expressions.md | 50 ++++++++++ ...iagnostics, Recovery, and Gate Evidence.md | 55 +++++++++++ 5 files changed, 308 insertions(+) create mode 100644 docs/pbs/agendas/11. AST Agenda.md create mode 100644 docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md create mode 100644 docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md create mode 100644 docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md create mode 100644 docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md diff --git a/docs/pbs/agendas/11. AST Agenda.md b/docs/pbs/agendas/11. AST Agenda.md new file mode 100644 index 00000000..ff99a932 --- /dev/null +++ b/docs/pbs/agendas/11. AST Agenda.md @@ -0,0 +1,99 @@ +# PBS AST Agenda + +Status: Active + +## 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/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 new file mode 100644 index 00000000..972fef50 --- /dev/null +++ b/docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md @@ -0,0 +1,54 @@ +# PBS AST Workshop 1 + +Status: Active + +## 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`. + +## 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/11. AST Agenda.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 new file mode 100644 index 00000000..fd405764 --- /dev/null +++ b/docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md @@ -0,0 +1,50 @@ +# PBS AST Workshop 2 + +Status: Active + +## 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. + +## 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/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/11.3. AST Workshop 3 - Statements and Expressions.md new file mode 100644 index 00000000..e957616d --- /dev/null +++ b/docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md @@ -0,0 +1,50 @@ +# PBS AST Workshop 3 + +Status: Active + +## 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. + +## 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/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/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md new file mode 100644 index 00000000..46585c43 --- /dev/null +++ b/docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md @@ -0,0 +1,55 @@ +# PBS AST Workshop 4 + +Status: Active + +## 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`. + +## 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/11.3. AST Workshop 3 - Statements and Expressions.md`