diff --git a/docs/pbs/agendas/11. Diagnostics Agenda.md b/docs/pbs/agendas/11. Diagnostics Agenda.md new file mode 100644 index 00000000..afa22078 --- /dev/null +++ b/docs/pbs/agendas/11. Diagnostics Agenda.md @@ -0,0 +1,71 @@ +# PBS Diagnostics Agenda + +Status: Active + +## Purpose + +Drive the remaining discussions needed to close `11. Diagnostics Specification.md` without inventing backend or UI policy prematurely. + +## Context + +The diagnostics spec already fixes the minimum phase split and source-attribution baseline, but it still leaves open: + +- whether diagnostic codes are mandatory in v1, +- which parts of wording are normative, +- what cross-file attribution is required for import and barrel failures, +- whether cost-facing warnings become part of conformance, +- and how backend-facing failures map back to source once lowering and PBX mapping are closed. + +This agenda should keep the diagnostics contract narrow, deterministic, and implementable by more than one toolchain. + +## Decisions To Produce + +1. Decide the minimum normative diagnostic identity model for v1: + phase only, phase plus category, or stable machine-readable code. +2. Decide the minimum normative attribution package: + file, primary span, secondary span/note requirements, and cross-file references. +3. Decide which human-facing wording requirements are normative versus illustrative. +4. Decide whether any qualitative cost diagnostics are mandatory in v1. +5. Decide how lowering, verifier, and load-facing failures surface back into the PBS-facing diagnostics contract. + +## Core Questions + +1. Is a stable diagnostic code required for conformance, or is deterministic rejection phase and source attribution enough? +2. For import, barrel, and cross-module lookup failures, what exact locations must be reported? +3. Must notes and help text exist for certain classes of error, or are they optional tooling quality? +4. Which backend-originated failures remain PBS diagnostics versus artifact-tool diagnostics? +5. Are warnings part of the normative contract at all in v1, and if so which ones? + +## Expected Spec Material + +The resulting spec work should be able to add or close sections for: + +- diagnostic identity and stability, +- source attribution rules, +- cross-file attribution rules, +- optional versus required notes/help, +- warning taxonomy boundaries, +- backend-facing diagnostic mapping boundaries, +- and conformance hooks consumed by `13. Conformance Test Specification.md`. + +## Non-Goals + +- Designing IDE presentation, colors, or UX. +- Building a complete trap taxonomy. +- Standardizing localization. +- Freezing one internal compiler error architecture. +- Rewriting rejection rules already owned by syntax, semantics, or loader specs. + +## Inputs + +- `docs/pbs/specs/3. Core Syntax Specification.md` +- `docs/pbs/specs/4. Static Semantics Specification.md` +- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md` +- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` +- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` +- `docs/pbs/specs/10. Memory and Lifetime Specification.md` +- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` + diff --git a/docs/pbs/agendas/12. IR and Lowering Agenda.md b/docs/pbs/agendas/12. IR and Lowering Agenda.md new file mode 100644 index 00000000..cc2f5626 --- /dev/null +++ b/docs/pbs/agendas/12. IR and Lowering Agenda.md @@ -0,0 +1,73 @@ +# PBS IR and Lowering Agenda + +Status: Active + +## Purpose + +Drive the decisions needed to turn `12. IR and Lowering Specification.md` from a skeleton into a normative lowering contract that can guide implementation. + +## Context + +The language now has substantial source-level semantics, but lowering still lacks closure around: + +- which semantic obligations IR must preserve, +- whether one canonical IR shape is normative, +- how core constructs map into lowered control flow and data flow, +- how services, contracts, callbacks, tuples, `optional`, and `result` lower, +- and which invariants belong in lowering versus PBX/bytecode mapping. + +This agenda should keep the focus on semantic preservation and artifact obligations, not on one compiler's class hierarchy. + +## Decisions To Produce + +1. Decide the normative status of IR: + canonical IR, canonical obligations only, or hybrid. +2. Decide the required lowering preconditions after parsing, resolution, and type checking. +3. Decide the lowered forms required for expressions, control flow, abrupt completion, and propagation. +4. Decide the lowering story for callbacks, services, contracts, tuples, `optional`, and `result`. +5. Decide the boundary between this spec and `15. Bytecode and PBX Mapping Specification.md`. +6. Decide the artifact invariants that must hold before verifier or loader stages. + +## Core Questions + +1. Which evaluation-order guarantees from dynamic semantics must be explicit in lowered form? +2. Which memory and identity facts must remain explicit through IR rather than inferred later? +3. Do callback formation and contract dispatch need dedicated runtime artifacts or only preserved semantic obligations? +4. What is the minimal lowering model for builtin projections, builtin constants, and intrinsic member calls beyond what is already fixed? +5. Which host-binding failures are lowering failures versus later verifier or loader failures? + +## Expected Spec Material + +The resulting spec work should be able to add or close sections for: + +- lowering preconditions, +- preserved semantic obligations, +- control-flow lowering, +- callable lowering by category, +- tuple, `optional`, and `result` lowering, +- callback, service, and contract lowering, +- builtin and host-binding lowering, +- artifact invariants before PBX emission, +- and source-to-artifact trace hooks consumed by diagnostics and conformance. + +## Non-Goals + +- Freezing optimizer internals. +- Freezing one in-memory compiler IR data model. +- Repeating the bytecode ISA. +- Defining loader patching internals. +- Designing performance heuristics. + +## Inputs + +- `docs/pbs/specs/4. Static Semantics Specification.md` +- `docs/pbs/specs/6. VM-owned vs Host-backed.md` +- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md` +- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` +- `docs/pbs/specs/9. Dynamic Semantics Specification.md` +- `docs/pbs/specs/10. Memory and Lifetime Specification.md` +- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md` + diff --git a/docs/pbs/agendas/13. Conformance Test Agenda.md b/docs/pbs/agendas/13. Conformance Test Agenda.md new file mode 100644 index 00000000..a432c0ec --- /dev/null +++ b/docs/pbs/agendas/13. Conformance Test Agenda.md @@ -0,0 +1,65 @@ +# PBS Conformance Test Agenda + +Status: Active + +## Purpose + +Drive the decisions needed to turn `13. Conformance Test Specification.md` into an executable conformance contract for PBS v1. + +## Context + +The current conformance spec already defines a source-level baseline, but it still leaves open: + +- whether PBS has one conformance level or staged claims, +- how diagnostics participate in conformance, +- when artifact-level golden tests become mandatory, +- how fixtures for stdlib environments, host registries, and capability grants are modeled, +- and how compatibility promises are validated over time. + +This agenda should keep conformance practical and layered so the project can evolve from frontend tests to full-toolchain claims without ambiguity. + +## Decisions To Produce + +1. Decide the conformance-claim model: + one level only or staged levels such as frontend-only and full toolchain. +2. Decide the normative oracle shape for diagnostics. +3. Decide when artifact-level conformance becomes required in addition to source-level behavior. +4. Decide the minimum fixture model for stdlib, host registry, capabilities, and runtime lines. +5. Decide how compatibility and regression claims are encoded in the conformance corpus. + +## Core Questions + +1. Is a parser plus binder implementation allowed to claim partial conformance, and under what label? +2. Do diagnostics tests assert codes, phases, spans, wording classes, or only acceptance and rejection? +3. Which lowering and host-binding invariants require golden tests once `12` and `15` are closed? +4. What is the smallest reusable fixture set that still exercises host-backed and stdlib-backed surfaces honestly? +5. How should compatibility expectations across language, stdlib, and cartridge domains be tested over time? + +## Expected Spec Material + +The resulting spec work should be able to add or close sections for: + +- conformance levels or claim classes, +- required positive and negative suites, +- diagnostic oracle rules, +- artifact-level oracle rules, +- fixture model and environment assumptions, +- regression and compatibility matrices, +- and acceptance criteria for claiming PBS v1 support. + +## Non-Goals + +- Choosing one repository layout or test framework. +- Turning benchmarks into conformance. +- Replacing the normative specs with test precedent. +- Freezing every temporary implementation quirk as a golden artifact. + +## Inputs + +- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` +- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` + diff --git a/docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md b/docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md new file mode 100644 index 00000000..bada0def --- /dev/null +++ b/docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md @@ -0,0 +1,66 @@ +# PBS Name Resolution and Module Linking Agenda + +Status: Active + +## Purpose + +Drive the closure of `14. Name Resolution and Module Linking Specification.md` so frontend implementation can proceed without inventing lookup or linking rules. + +## Context + +This is the main unresolved frontend-facing spec. The current skeleton still leaves open: + +- exact lookup order across locals, top-level declarations, imports, builtin shells, and reserved surfaces, +- shadowing and duplicate rules by namespace, +- import alias and barrel-export matching behavior, +- cross-module callable and overload visibility, +- and the resolution model for builtin and host-backed stdlib shells. + +Without this closure, parser and AST work can proceed only as exploratory implementation rather than normative frontend work. + +## Decisions To Produce + +1. Decide deterministic lookup order for every relevant namespace. +2. Decide shadowing, duplicate, and ambiguity rules for local, module, and imported names. +3. Decide import alias resolution and barrel matching rules in enough detail for implementation. +4. Decide the resolution model for builtin shells, builtin constants, intrinsic members, and host owners. +5. Decide which rejections belong to static semantics and which belong to a distinct linking phase. + +## Core Questions + +1. What is the exact lookup order in value position, type position, callable position, and host-owner position? +2. Do shadowing rules differ between locals, imports, top-level declarations, and builtin surfaces? +3. How are callable overload sets formed across local module declarations and imports? +4. When two imported modules make the same name visible, what is the exact ambiguity and rejection rule? +5. Are reserved stdlib shells resolved as ordinary visible declarations with metadata, or do they have any special priority? + +## Expected Spec Material + +The resulting spec work should be able to add or close sections for: + +- scope construction, +- namespace-specific lookup order, +- import and alias resolution, +- barrel export matching, +- overload-set visibility across modules, +- builtin and host-shell resolution, +- linking-phase versus static-phase rejection boundaries, +- and deterministic cross-module failure cases. + +## Non-Goals + +- Redefining grammar already fixed in core syntax. +- Designing runtime loader behavior. +- Freezing one symbol-table implementation. +- Designing IDE auto-import behavior. + +## Inputs + +- `docs/pbs/specs/3. Core Syntax Specification.md` +- `docs/pbs/specs/4. Static Semantics Specification.md` +- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md` +- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md` +- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md` +- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/specs/18. Standard Library Surface Specification.md` + diff --git a/docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md b/docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md new file mode 100644 index 00000000..3119fad6 --- /dev/null +++ b/docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md @@ -0,0 +1,63 @@ +# PBS Compatibility and Evolution Policy Agenda + +Status: Active + +## Purpose + +Drive the closure of `17. Compatibility and Evolution Policy.md` so PBS can make explicit promises before implementation and release claims expand. + +## Context + +The current skeleton identifies the right policy areas, but it still leaves open: + +- compatibility domains and windows, +- the separation between source, stdlib, artifact, and runtime compatibility, +- deprecation and removal duties, +- migration-tooling versus documentation-only obligations, +- and whether phased implementation claims need distinct compatibility labels. + +This agenda should produce a policy that is strict enough to protect users and toolchains, while still allowing deliberate evolution. + +## Decisions To Produce + +1. Decide the compatibility domains PBS speaks about normatively. +2. Decide the compatibility promise and window for each domain. +3. Decide the deprecation and removal policy for source, stdlib, and artifact surfaces. +4. Decide when migration tooling is mandatory versus when written guidance is enough. +5. Decide whether phased implementation or conformance claims need distinct compatibility labels. + +## Core Questions + +1. What exact promise is made to old source code, published cartridges, stdlib consumers, and emitted artifacts? +2. Is PBX compatibility governed independently from source compatibility? +3. How do stdlib-line changes affect downstream dependency projects over time? +4. Which incompatible changes require migration tooling rather than only release notes? +5. How are compatibility claims constrained by conformance level and runtime line? + +## Expected Spec Material + +The resulting spec work should be able to add or close sections for: + +- compatibility domains, +- compatibility windows and support lines, +- behavioral versus binary compatibility, +- deprecation and removal discipline, +- migration obligations, +- compatibility matrices across language, stdlib, and runtime lines, +- and labeling rules for partial or staged implementation claims. + +## Non-Goals + +- Defining one release calendar. +- Replacing governance with case-by-case exceptions. +- Treating every editorial clarification as a compatibility event. +- Designing product marketing labels. + +## Inputs + +- `docs/pbs/specs/1. Language Charter.md` +- `docs/pbs/specs/2. Governance and Versioning.md` +- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` +- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` +- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`