Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

clean up

Browse Source
This commit is contained in:
bQUARKz 2026-03-05 07:49:01 +00:00
parent 813ff67c1c
commit 8a68a2a025
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
7 changed files with 0 additions and 461 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
docs/pbs/agendas/archive/11. AST Agenda.md
View File

@ -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`

64
docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md
View File

@ -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`

62
docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md
View File

@ -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`

62
docs/pbs/agendas/archive/11.3. AST Workshop 3 - Statements and Expressions.md
View File

@ -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`

67
docs/pbs/agendas/archive/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md
View File

@ -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`

102
docs/pbs/agendas/archive/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md
View File

@ -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`

5
docs/pbs/agendas/archive/README.md
View File

@ -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.