diff --git a/docs/general/README.md b/docs/general/README.md new file mode 100644 index 00000000..6cce3415 --- /dev/null +++ b/docs/general/README.md @@ -0,0 +1,20 @@ +# General Documentation + +This directory contains documentation that applies to language implementations in general, not only PBS. + +## Tree + +```text +docs/general/ +└── specs/ +``` + +## Purpose + +`general/specs` is the cross-language acceptance layer. + +Use it to define: + +- shared conformance and quality-gate contracts, +- shared compatibility and verification policy, +- and backend/runtime acceptance boundaries that are language-agnostic. diff --git a/docs/pbs/specs/13. Conformance Test Specification.md b/docs/general/specs/13. Conformance Test Specification.md similarity index 96% rename from docs/pbs/specs/13. Conformance Test Specification.md rename to docs/general/specs/13. Conformance Test Specification.md index 59dfe67b..3d9dd78a 100644 --- a/docs/pbs/specs/13. Conformance Test Specification.md +++ b/docs/general/specs/13. Conformance Test Specification.md @@ -36,8 +36,8 @@ Normative precedence: 2. `2. Governance and Versioning.md` 3. `3. Core Syntax Specification.md` 4. `4. Static Semantics Specification.md` -5. `11. Diagnostics Specification.md` -6. `12. IR and Lowering Specification.md` +5. `12. Diagnostics Specification.md` +6. `13. Lowering IRBackend Specification.md` 7. This document This document must not weaken normative requirements from higher-precedence specs. @@ -48,8 +48,8 @@ This document depends on: - `3. Core Syntax Specification.md` - `4. Static Semantics Specification.md` -- `11. Diagnostics Specification.md` -- `12. IR and Lowering Specification.md` +- `12. Diagnostics Specification.md` +- `13. Lowering IRBackend Specification.md` - `17. Compatibility and Evolution Policy.md` ## 5. Quality Gate Model diff --git a/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md b/docs/general/specs/14. Name Resolution and Module Linking Specification.md similarity index 100% rename from docs/pbs/specs/14. Name Resolution and Module Linking Specification.md rename to docs/general/specs/14. Name Resolution and Module Linking Specification.md diff --git a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md b/docs/general/specs/15. Bytecode and PBX Mapping Specification.md similarity index 96% rename from docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md rename to docs/general/specs/15. Bytecode and PBX Mapping Specification.md index 827f096c..a93642c8 100644 --- a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md +++ b/docs/general/specs/15. Bytecode and PBX Mapping Specification.md @@ -31,7 +31,7 @@ Normative precedence: 2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`) 3. `6.1. Intrinsics and Builtin Types Specification.md` 4. `6.2. Host ABI Binding and Loader Resolution Specification.md` -5. `12. IR and Lowering Specification.md` +5. `13. Lowering IRBackend Specification.md` 6. This document If a rule here conflicts with higher-precedence authorities, it is invalid. @@ -42,7 +42,7 @@ This document depends on, at minimum: - `6.1. Intrinsics and Builtin Types Specification.md` - `6.2. Host ABI Binding and Loader Resolution Specification.md` -- `12. IR and Lowering Specification.md` +- `13. Lowering IRBackend Specification.md` ## 5. Already-Settled Inputs @@ -60,7 +60,7 @@ The following inputs are already fixed elsewhere and must not be contradicted he The current boundary across backend-facing specs is: -- `12. IR and Lowering Specification.md` defines what facts must be preserved by lowering, +- `13. Lowering IRBackend Specification.md` defines what facts must be preserved by lowering, - this document defines how the PBS-facing artifact facts appear in PBX/bytecode-visible form, - and `19. Verification and Safety Checks Specification.md` defines later validity checks after the artifact is formed and, where relevant, patched by the loader. diff --git a/docs/pbs/specs/16. Runtime Execution and Initialization Specification.md b/docs/general/specs/16. Runtime Execution and Initialization Specification.md similarity index 100% rename from docs/pbs/specs/16. Runtime Execution and Initialization Specification.md rename to docs/general/specs/16. Runtime Execution and Initialization Specification.md diff --git a/docs/pbs/specs/17. Compatibility and Evolution Policy.md b/docs/general/specs/17. Compatibility and Evolution Policy.md similarity index 100% rename from docs/pbs/specs/17. Compatibility and Evolution Policy.md rename to docs/general/specs/17. Compatibility and Evolution Policy.md diff --git a/docs/pbs/specs/18. Standard Library Surface Specification.md b/docs/general/specs/18. Standard Library Surface Specification.md similarity index 100% rename from docs/pbs/specs/18. Standard Library Surface Specification.md rename to docs/general/specs/18. Standard Library Surface Specification.md diff --git a/docs/pbs/specs/19. Verification and Safety Checks Specification.md b/docs/general/specs/19. Verification and Safety Checks Specification.md similarity index 95% rename from docs/pbs/specs/19. Verification and Safety Checks Specification.md rename to docs/general/specs/19. Verification and Safety Checks Specification.md index b43c5d41..608bdab0 100644 --- a/docs/pbs/specs/19. Verification and Safety Checks Specification.md +++ b/docs/general/specs/19. Verification and Safety Checks Specification.md @@ -28,8 +28,8 @@ This document does not define: Normative precedence: 1. `2. Governance and Versioning.md` -2. `11. Diagnostics Specification.md` -3. `12. IR and Lowering Specification.md` +2. `12. Diagnostics Specification.md` +3. `13. Lowering IRBackend Specification.md` 4. `13. Conformance Test Specification.md` 5. `15. Bytecode and PBX Mapping Specification.md` 6. This document @@ -40,8 +40,8 @@ If a rule here conflicts with higher-precedence authorities, it is invalid. This document depends on: -- `11. Diagnostics Specification.md` -- `12. IR and Lowering Specification.md` +- `12. Diagnostics Specification.md` +- `13. Lowering IRBackend Specification.md` - `13. Conformance Test Specification.md` - `15. Bytecode and PBX Mapping Specification.md` diff --git a/docs/general/specs/README.md b/docs/general/specs/README.md new file mode 100644 index 00000000..68649ddf --- /dev/null +++ b/docs/general/specs/README.md @@ -0,0 +1,18 @@ +# General Specs + +This directory contains shared acceptance specifications for all supported languages in Prometeu. + +## Scope + +These specs are above language-specific specs and should be reused by each language line. + +Typical topics: + +- conformance gates and evidence, +- compatibility publication policy, +- verification/safety acceptance boundaries, +- artifact/runtime acceptance contracts. + +## Rule + +Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy. diff --git a/docs/pbs/README.md b/docs/pbs/README.md index 2f0759ba..96bced82 100644 --- a/docs/pbs/README.md +++ b/docs/pbs/README.md @@ -53,6 +53,9 @@ Use it to: - define precedence, scope, rules, and exit criteria, - provide the baseline for implementation, verification, and conformance. +`docs/pbs/specs` is language-specific. +Cross-language acceptance specs live in `docs/general/specs`. + Specs must not operate as discussion backlogs. If a point is still disputed or underspecified, it belongs in `agendas/` or `decisions/`, not directly in `specs/`. @@ -83,5 +86,5 @@ The preferred pipeline is: - `agendas/` stores open questions. - `decisions/` stores closed answers. -- `specs/` stores the normative contract. +- `specs/` stores the PBS-specific normative contract. - `pull-requests/` stores reviewable change packages. diff --git a/docs/pbs/agendas/12. IR and Lowering Agenda.md b/docs/pbs/agendas/12. IR and Lowering Agenda.md deleted file mode 100644 index 453caf45..00000000 --- a/docs/pbs/agendas/12. IR and Lowering Agenda.md +++ /dev/null @@ -1,123 +0,0 @@ -# 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? - -## Proposed Workshop Sequence - -### Workshop 1: Lowering Contract and IR Status - -Purpose: - -- decide whether PBS standardizes one canonical IR or only preserved obligations, -- and close lowering preconditions after parsing, resolution, and type checking. - -Expected decisions: - -- canonical IR versus obligations-only model, -- required bound-program inputs, -- and minimal preserved semantic facts. - -### Workshop 2: Control Flow, Evaluation Order, and Propagation - -Purpose: - -- close the lowering model for expressions, branching, abrupt completion, `optional`, and `result`. - -Expected decisions: - -- explicit evaluation-order preservation, -- lowered forms for `else`, `!`, and `handle`, -- and trap versus propagation boundaries. - -### Workshop 3: Callables, Services, Contracts, and Callbacks - -Purpose: - -- close the lowering story for callable categories beyond ordinary top-level functions. - -Expected decisions: - -- callback formation model, -- service and contract dispatch shape, -- and runtime-artifact obligations for callable categories. - -### Workshop 4: Builtins, Host Bindings, and Artifact Invariants - -Purpose: - -- close builtin lowering, host-binding emission, and the invariants required before verifier and loader stages. - -Expected decisions: - -- builtin projection and intrinsic lowering obligations, -- host-binding emission boundary versus PBX mapping, -- and artifact invariants consumed by `15` and `19`. - -## 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/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md b/docs/pbs/agendas/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md deleted file mode 100644 index 8194f2d6..00000000 --- a/docs/pbs/agendas/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md +++ /dev/null @@ -1,116 +0,0 @@ -# PBS IR and Lowering Workshop 1 - -Status: Active - -## Purpose - -Run the first focused discussion for `12. IR and Lowering Specification.md` on the front door of lowering: - -- what the lowering contract consumes, -- whether IR itself is normative, -- and which semantic obligations must be preserved independent of IR shape. - -## Why This Slice First - -This slice should come first because every later lowering discussion depends on knowing: - -- what counts as a well-formed input to lowering, -- and whether the spec standardizes one IR shape or only semantic preservation duties. - -## Proposed Meeting Order - -1. Reconfirm already-settled lowering inputs. -2. Close the preconditions for lowering. -3. Close the normative status of IR. -4. Close the minimum preserved semantic obligations. -5. Record construct-specific issues for later workshops. - -## Decisions To Produce - -1. The normative status of IR in PBS v1. -2. The minimum required input state before lowering begins. -3. The semantic facts that lowering must preserve regardless of IR architecture. -4. The boundary between `12` and `15`. - -## Candidate Decisions - -### 1. Standardize Preserved Obligations, Not One Canonical In-Memory IR - -Candidate direction: - -- PBS v1 does not require one canonical compiler IR data model, -- but it does require one stable set of preserved semantic obligations. - -Rationale: - -- This keeps the spec implementation-neutral while still preventing semantic drift. - -Alternative to discuss: - -- define one normative abstract IR grammar in the spec. - -### 2. Lowering Preconditions Require A Fully Bound Program - -Candidate direction: - -- parsing, name resolution, visibility/linking, and type checking must already be complete, -- reserved builtin and host metadata must already be validated, -- callable sets and canonical identities must already be resolved. - -Rationale: - -- Lowering should not invent unresolved semantic answers. - -### 3. Minimum Preserved Obligations Include Evaluation Order, Identity, and Host Boundary Facts - -Candidate direction: - -- lowering must preserve: - source-observable evaluation order, - abrupt-completion behavior, - value-identity and aliasing facts, - host-boundary crossings, - and trap-versus-propagation distinctions. - -Rationale: - -- These are the semantic anchors later workshops will rely on. - -### 4. `15` Owns Final Artifact Layout, `12` Owns The Contract Before It - -Candidate direction: - -- `12` defines the semantic and artifact-facing invariants a lowered program must satisfy, -- `15` defines the final PBX and bytecode mapping details. - -Rationale: - -- This keeps the lowering spec from collapsing into artifact byte layout. - -## Questions To Resolve In The Room - -1. Is obligations-only precise enough, or does PBS need a normative abstract IR? -2. Should canonical identity resolution be fully complete before lowering? -3. Which semantic facts are mandatory to preserve explicitly rather than infer later? -4. Does `12` need one explicit “bound program” model? -5. How much artifact vocabulary can `12` use before it starts stealing `15`'s job? - -## Expected Outputs - -1. a decision record on IR status, -2. a decision record on lowering preconditions, -3. and a checklist of preserved semantic obligations for `12`. - -## Explicit Deferrals For Workshop 2 - -- control-flow shapes, -- propagation operators, -- and callable-category-specific lowering. - -## Inputs - -- `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/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/agendas/12. IR and Lowering Agenda.md` diff --git a/docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md b/docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md deleted file mode 100644 index 631e214b..00000000 --- a/docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md +++ /dev/null @@ -1,117 +0,0 @@ -# PBS IR and Lowering Workshop 2 - -Status: Active - -## Purpose - -Run the second focused discussion for `12. IR and Lowering Specification.md` on control flow and propagation: - -- evaluation order, -- branching, -- abrupt completion, -- `optional`, -- `result`, -- `!`, -- and `handle`. - -## Why This Slice Second - -This slice follows naturally from Workshop 1 because it applies the preserved-obligations model to the core execution constructs. - -## Proposed Meeting Order - -1. Reconfirm the preserved semantic obligations from Workshop 1. -2. Close evaluation-order preservation in lowered form. -3. Close the lowered model for branching and abrupt completion. -4. Close the lowered model for `optional` and `result` propagation. -5. Record callable and runtime-artifact issues for Workshop 3. - -## Decisions To Produce - -1. How evaluation order is preserved explicitly. -2. How abrupt completion is represented in lowered control flow. -3. The lowered shape of `optional else`, `expr!`, and `handle`. -4. The boundary between propagation and trap in lowering. - -## Candidate Decisions - -### 1. Lowering Must Make Single Evaluation Explicit - -Candidate direction: - -- call target formation, -- argument evaluation, -- `if` conditions, -- `switch` selectors, -- `some(expr)` payload formation, -- and `bind(context, fn_name)` capture -must each lower to explicit once-only evaluation points. - -Rationale: - -- These are already language-observable guarantees. - -### 2. Branching Lowers To Explicit Control Transfers - -Candidate direction: - -- `if` and `switch` lower to explicit branch structure, -- non-selected arms do not evaluate, -- and tail-result formation is explicit rather than implicit. - -Rationale: - -- This keeps the dynamic-semantics contract visible through lowering. - -### 3. Propagation Uses Dedicated Lowered Paths - -Candidate direction: - -- `optional else` lowers to a presence test plus fallback path, -- `expr!` lowers to success-path unpack plus immediate error propagation path, -- `handle` lowers to explicit arm dispatch over the error case space. - -Rationale: - -- These constructs are semantically distinct enough that ordinary expression lowering should not blur them. - -### 4. Trap Is Not Rewritten Into Result Flow - -Candidate direction: - -- lowered trap paths remain fatal abort paths outside ordinary `result` propagation, -- and `handle` never intercepts trap. - -Rationale: - -- This preserves the existing semantics cleanly. - -## Questions To Resolve In The Room - -1. Does `12` need dedicated abstract operations for propagation, or only obligations on the emitted control flow? -2. How explicit must once-only evaluation be in the spec text? -3. Does `switch` lowering need one canonical decision-tree shape? -4. Is `handle` best specified as arm dispatch plus remap semantics, or as a more abstract effect-preservation rule? -5. Which of these details belong to `12` versus `15`? - -## Expected Outputs - -1. a decision record for evaluation-order preservation, -2. a decision record for propagation lowering, -3. and control-flow section targets for `12`. - -## Explicit Deferrals For Workshop 3 - -- services, -- contracts, -- callbacks, -- and runtime dispatch artifacts. - -## Inputs - -- `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/agendas/12. IR and Lowering Agenda.md` -- `docs/pbs/agendas/12.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md` - diff --git a/docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md b/docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md deleted file mode 100644 index f1cffe7e..00000000 --- a/docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md +++ /dev/null @@ -1,111 +0,0 @@ -# PBS IR and Lowering Workshop 3 - -Status: Active - -## Purpose - -Run the third focused discussion for `12. IR and Lowering Specification.md` on callable categories beyond ordinary top-level functions: - -- callbacks, -- services, -- contracts, -- methods, -- and dispatch obligations. - -## Why This Slice Third - -This slice should come after control-flow lowering because it builds on the general execution model while introducing runtime-dispatch and identity-sensitive concerns. - -## Proposed Meeting Order - -1. Reconfirm callable categories and identity facts already fixed. -2. Close callback formation and invocation lowering. -3. Close service and method lowering. -4. Close contract-view and dispatch lowering. -5. Record builtin and host-binding specifics for Workshop 4. - -## Decisions To Produce - -1. The lowering story for callback formation and invocation. -2. The lowering story for service singleton methods. -3. The lowering story for contracts and dispatch. -4. Which runtime-artifact facts must be explicit versus implementation-defined. - -## Candidate Decisions - -### 1. Callback Lowering Must Preserve Captured Identity And Retention - -Candidate direction: - -- callback values created by `bind` lower to a representation that preserves: - target callable identity, - captured context identity, - and retention-bearing lifetime facts. - -Rationale: - -- These are already required by memory and semantics specs. - -### 2. Service Lowering Preserves Singleton Identity - -Candidate direction: - -- service method calls lower through the module-owned singleton identity, -- and lowering must not accidentally materialize new service instances. - -Rationale: - -- This is a language-observable property. - -### 3. Contract Lowering Must Preserve Selected Implementation Identity - -Candidate direction: - -- contract values lower as runtime-dispatchable views over an underlying owner plus implementation selection, -- but `12` does not freeze one concrete table or object layout yet. - -Rationale: - -- This keeps the semantic contract clear while deferring layout choices. - -### 4. Receiver-Bearing Method Calls Need Explicit Lowered Receiver Handling - -Candidate direction: - -- struct, service, and contract method calls lower through an explicit receiver-bearing callable shape, -- even if the backend later optimizes the representation. - -Rationale: - -- This keeps receiver identity and call semantics visible in the spec. - -## Questions To Resolve In The Room - -1. Does contract dispatch need a dedicated runtime artifact category in the spec? -2. Does callback lowering need one explicit abstract representation? -3. How much of method dispatch belongs in `12` versus runtime execution specs? -4. Are service methods lowered like receiver calls or like specialized global calls? -5. Which of these constructs need explicit artifact invariants before `15`? - -## Expected Outputs - -1. a decision record for callback lowering, -2. a decision record for service and contract lowering, -3. and callable-category section targets for `12`. - -## Explicit Deferrals For Workshop 4 - -- builtin projection lowering, -- builtin constants, -- host-binding emission, -- and verifier-facing artifact invariants. - -## Inputs - -- `docs/pbs/specs/4. Static Semantics 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/agendas/12. IR and Lowering Agenda.md` -- `docs/pbs/agendas/12.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md` - diff --git a/docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md b/docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md deleted file mode 100644 index ea30050c..00000000 --- a/docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md +++ /dev/null @@ -1,111 +0,0 @@ -# PBS IR and Lowering Workshop 4 - -Status: Active - -## Purpose - -Run the fourth focused discussion for `12. IR and Lowering Specification.md` on the backend-facing edges: - -- builtin projections, -- builtin constants, -- intrinsic member calls, -- host-binding emission, -- and artifact invariants required before verifier or loader stages. - -## Why This Slice Last - -This slice should come last because it depends on the general lowering contract plus the special ownership rules around VM-owned versus host-backed behavior. - -## Proposed Meeting Order - -1. Reconfirm already-settled builtin and host-binding facts. -2. Close lowering obligations for builtin projections and constants. -3. Close lowering obligations for intrinsic member calls. -4. Close host-binding emission obligations. -5. Close pre-verifier and pre-loader artifact invariants. - -## Decisions To Produce - -1. Builtin lowering obligations beyond already-settled metadata consumption. -2. Host-binding emission obligations before loader resolution. -3. The artifact invariants required before verifier/loader stages. -4. The exact boundary between `12`, `15`, and `19`. - -## Candidate Decisions - -### 1. Builtin Projections Stay VM-Owned Through Lowering - -Candidate direction: - -- builtin projection access lowers through VM-owned operations only, -- and never through host-binding tables or host syscall paths. - -Rationale: - -- This is already settled; `12` needs only to make the preserved obligation explicit. - -### 2. Builtin Constants Lower Through Materialization, Not Constant Folding Semantics - -Candidate direction: - -- builtin constants lower through their VM-owned materialization path, -- not through ordinary user-authored compile-time constant evaluation. - -Rationale: - -- This keeps builtin shells distinct from ordinary `declare const`. - -### 3. Host-Binding Emission Must Be Explicit Before `15` - -Candidate direction: - -- lowering must produce canonical host-binding entries, -- deduplicate them by canonical identity, -- and emit host-backed callsites in the pre-load form already fixed elsewhere. - -Rationale: - -- This is the bridge between bound source and artifact mapping. - -### 4. `12` Defines Artifact Invariants, `15` Defines Encoding - -Candidate direction: - -- `12` states what must be true of the emitted artifact boundary, -- `15` states exactly how those facts appear in PBX and bytecode form, -- `19` states what must be verified. - -Rationale: - -- This keeps the three backend-facing specs from overlapping. - -## Questions To Resolve In The Room - -1. Does `12` need any abstract instruction vocabulary for builtins and host calls? -2. Which invariants belong to lowering rather than to verification? -3. How much ordering and dedup detail should `12` restate versus reference from other specs? -4. Should intrinsic lowering be specified as abstract op families or only semantic obligations? -5. What exact artifact guarantees must `13` eventually assert? - -## Expected Outputs - -1. a decision record for builtin lowering obligations, -2. a decision record for host-binding emission obligations, -3. and an artifact-invariants checklist spanning `12`, `15`, and `19`. - -## Explicit Deferrals - -- exact bytecode instruction encodings, -- exact PBX section layout, -- and verifier algorithm details. - -## Inputs - -- `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/12. IR and Lowering Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` -- `docs/pbs/agendas/12. IR and Lowering Agenda.md` -- `docs/pbs/agendas/12.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md` - diff --git a/docs/pbs/agendas/13. IR and Lowering Agenda.md b/docs/pbs/agendas/13. IR and Lowering Agenda.md new file mode 100644 index 00000000..76bba2a7 --- /dev/null +++ b/docs/pbs/agendas/13. IR and Lowering Agenda.md @@ -0,0 +1,122 @@ +# PBS Frontend IR and Lowering Agenda + +Status: Active + +## Purpose + +Drive closure of `13. Lowering IRBackend Specification.md` for frontend scope only. + +This agenda exists to define the first normative lowering boundary: + +- PBS source to frontend IR (`IRBackend` / `IRBackendFile`), +- deterministic diagnostic behavior for unsupported or invalid source forms, +- and test-backed acceptance criteria for Gate U. + +## Scope Boundary + +In scope: + +- lexer/parser/AST/linking outputs consumed by frontend lowering, +- semantic facts that must be preserved in frontend IR, +- deterministic rejection classes and diagnostic attribution, +- and conformance evidence for frontend gates. + +Out of scope: + +- VM lowering, +- bytecode/PBX mapping, +- runtime execution behavior, +- verifier/loader algorithms. + +## Decisions To Produce + +1. Decide whether `13` standardizes one frontend IR shape or only preserved obligations. +2. Decide the minimum preconditions before frontend lowering begins. +3. Decide which semantic facts must be explicit in frontend IR for v1. +4. Decide the minimum deterministic rejection set for unsupported frontend-lowering cases. +5. Decide the gate evidence expected from tests (`lexer/parser/AST/IRBackend/diagnostics`). + +## Core Questions + +1. What is the minimum frontend IR contract that keeps implementation practical and testable now? +2. Which source-observable guarantees must already be explicit before any backend stage exists? +3. Which constructs are in-scope for v1 lowering and which must fail deterministically? +4. What diagnostics identity must be stable for lowering-related frontend failures? +5. Which regression fixtures become mandatory Gate U evidence? + +## Proposed Workshop Sequence + +### Workshop 1: Frontend Lowering Contract and Preconditions + +Purpose: + +- close input preconditions, +- and close the normative status of frontend IR. + +Expected decisions: + +- obligations-only versus canonical frontend IR model, +- and minimum required bound-program state before lowering. + +### Workshop 2: Expressions, Control Flow, and Propagation in Frontend IR + +Purpose: + +- close frontend-lowering obligations for core expression/control-flow forms. + +Expected decisions: + +- once-only evaluation obligations in frontend IR terms, +- representation obligations for branching and propagation constructs. + +### Workshop 3: Callable Categories in Frontend IR + +Purpose: + +- close frontend-lowering obligations for functions, callbacks, services, and contracts as source-level categories. + +Expected decisions: + +- minimum callable metadata preserved in frontend IR, +- and deterministic rejection boundaries for unsupported callable forms. + +### Workshop 4: Builtins, Diagnostics, and Test Gates + +Purpose: + +- close builtin-facing frontend obligations plus gate-ready diagnostics/test evidence. + +Expected decisions: + +- frontend treatment of builtin shells/metadata at lowering boundary, +- minimum diagnostics identity and attribution for lowering-related failures, +- and required fixture families for Gate U. + +## Expected Spec Material + +The resulting `13` content should close: + +- lowering preconditions for frontend scope, +- frontend IR preserved-obligation model, +- construct-by-construct frontend lowering baseline, +- deterministic unsupported-case rejection policy, +- and frontend-facing diagnostic/test evidence hooks. + +## Non-Goals + +- Defining VM or bytecode artifacts. +- Freezing runtime semantics in this agenda. +- Defining verifier or loader internals. +- Freezing optimizer architecture. + +## Inputs + +- `docs/pbs/specs/3. Core Syntax Specification.md` +- `docs/pbs/specs/4. Static Semantics Specification.md` +- `docs/pbs/specs/9. Dynamic Semantics Specification.md` +- `docs/pbs/specs/10. Memory and Lifetime 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` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` diff --git a/docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md b/docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md new file mode 100644 index 00000000..c45d6293 --- /dev/null +++ b/docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md @@ -0,0 +1,102 @@ +# 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/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md b/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md new file mode 100644 index 00000000..1cb1ad1a --- /dev/null +++ b/docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md @@ -0,0 +1,86 @@ +# PBS Frontend IR and Lowering Workshop 2 + +Status: Active + +## Purpose + +Run the second focused discussion for `13. Lowering IRBackend Specification.md` on frontend-lowering obligations for: + +- expression evaluation order, +- branching behavior, +- and propagation-related constructs at frontend IR boundary. + +## Why This Slice Second + +After Workshop 1 closes contract/preconditions, this workshop closes construct-level obligations that must be testable in frontend scope. + +## Proposed Meeting Order + +1. Reconfirm preserved obligations from Workshop 1. +2. Close once-only evaluation obligations in frontend IR terms. +3. Close branch and abrupt-completion representation obligations. +4. Close propagation construct obligations (`optional`, `result`, `!`, `handle`) at frontend boundary. +5. Record callable-category leftovers for Workshop 3. + +## Decisions To Produce + +1. Which evaluation-order guarantees must remain explicit in frontend IR obligations. +2. Which branch/abrupt-completion facts are mandatory in v1 frontend lowering. +3. Which propagation constructs are in-scope versus deterministic rejection in v1 slice. +4. Which diagnostics are required when unsupported propagation constructs are used. + +## Candidate Decisions + +### 1. Frontend Lowering Must Preserve Once-Only Evaluation Facts + +Candidate direction: + +- source-observable single-evaluation points are preserved as explicit lowering obligations, +- independent of one exact IR node taxonomy. + +### 2. Branching Obligations Are Normative At Frontend Boundary + +Candidate direction: + +- selected/non-selected branch semantics remain explicit in frontend lowering contract, +- with no implicit permissive fallbacks. + +### 3. Propagation Constructs Have Explicit V1 Status + +Candidate direction: + +- each construct is marked `supported in v1 frontend lowering` or `deterministic reject`, +- and this status is mirrored in Gate U fixtures. + +### 4. Diagnostics Identity Must Be Stable For Unsupported Forms + +Candidate direction: + +- unsupported forms emit stable code/severity/primary attribution, +- so regression tests can lock behavior. + +## Questions To Resolve In The Room + +1. Which propagation constructs are fully represented now versus deferred? +2. What minimum frontend IR evidence is enough to prove evaluation-order obligations? +3. Which failures should be classified as parse/static errors versus lowering errors? +4. Which fixture shapes are mandatory for Gate U here? + +## Expected Outputs + +1. a decision note on expression/control-flow lowering obligations, +2. a decision note on propagation status map (support/reject), +3. and fixture targets for frontend conformance tests. + +## Explicit Deferrals For Workshop 3 + +- callable-category representation details, +- and service/contract/callback-specific obligations. + +## Inputs + +- `docs/pbs/specs/9. Dynamic Semantics 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` +- `docs/pbs/agendas/13.1. IR and Lowering Workshop 1 - Lowering Contract and IR Status.md` diff --git a/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md b/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md new file mode 100644 index 00000000..63ce58f2 --- /dev/null +++ b/docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.md @@ -0,0 +1,88 @@ +# PBS Frontend IR and Lowering Workshop 3 + +Status: Active + +## Purpose + +Run the third focused discussion for `13. Lowering IRBackend Specification.md` on callable categories in frontend scope: + +- top-level functions, +- callbacks, +- services, +- and contracts as source-level callable surfaces. + +## Why This Slice Third + +Callable categories depend on the core expression/control-flow obligations from Workshop 2 and now need explicit frontend representation/rejection boundaries. + +## Proposed Meeting Order + +1. Reconfirm callable and identity facts already settled by syntax/static/linking specs. +2. Close frontend-lowering obligations for function and callback forms. +3. Close frontend-lowering obligations for service/contract callable surfaces. +4. Close deterministic rejection policy for unsupported callable forms. +5. Record builtin/diagnostics gate closure points for Workshop 4. + +## Decisions To Produce + +1. Minimum callable metadata preserved by frontend IR for each callable category. +2. V1 support map for callable categories (`supported` versus deterministic reject). +3. Required diagnostics identity for rejected callable forms. +4. Required regression fixtures for callable categories in Gate U. + +## Candidate Decisions + +### 1. Callable Identity Must Be Explicit In Frontend IR Contract + +Candidate direction: + +- callable name/category/arity/source attribution are mandatory preserved facts, +- regardless of internal object-model differences. + +### 2. Callback/Service/Contract Surfaces Need Explicit V1 Status + +Candidate direction: + +- each callable surface is classified now as `represented` or `rejected`, +- with no silent fallback behavior. + +### 3. Unsupported Callable Forms Are Deterministic Diagnostics + +Candidate direction: + +- unsupported callable patterns must emit stable diagnostics, +- and become mandatory regression tests. + +### 4. Gate U Must Cover Callable Categories Explicitly + +Candidate direction: + +- representative valid+invalid fixtures per callable category are mandatory, +- including diagnostics assertions for rejected forms. + +## Questions To Resolve In The Room + +1. Which callable category fields are mandatory in `IRBackend` today? +2. Which callable constructs remain deferred in v1 frontend scope? +3. What is the minimum fixture set to protect callable behavior regressions? +4. Which diagnostics codes must be fixed now versus later? + +## Expected Outputs + +1. a decision note on callable frontend-lowering obligations, +2. a decision note on callable support/rejection map, +3. and Gate U fixture requirements for callable categories. + +## Explicit Deferrals For Workshop 4 + +- builtin-specific lowering obligations, +- and final diagnostics/gate packaging for spec closure. + +## 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/13. Conformance Test Specification.md` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/agendas/13.2. IR and Lowering Workshop 2 - Control Flow, Evaluation Order, and Propagation.md` diff --git a/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md b/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md new file mode 100644 index 00000000..6b9f0f12 --- /dev/null +++ b/docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md @@ -0,0 +1,89 @@ +# PBS Frontend IR and Lowering Workshop 4 + +Status: Active + +## Purpose + +Run the fourth focused discussion for `13. Lowering IRBackend Specification.md` to close frontend-specific pending points: + +- builtin-facing source semantics at frontend lowering boundary, +- diagnostics stability for lowering-related failures, +- and test-gate evidence needed to close v1 frontend slice. + +## Why This Slice Last + +This workshop should close only after Workshops 1 to 3 define the base lowering contract and callable status map. + +## Proposed Meeting Order + +1. Reconfirm frontend-only scope and deferred backend concerns. +2. Close builtin-shell obligations at frontend lowering boundary. +3. Close diagnostics identity/attribution obligations for lowering-related failures. +4. Close minimum gate evidence package (Gate U). +5. Produce closure checklist for spec `13` frontend slice. + +## Decisions To Produce + +1. Frontend-lowering obligations for builtin-facing constructs in v1. +2. Stable diagnostics contract for frontend-lowering rejections. +3. Mandatory fixture families to prove `13` frontend obligations. +4. Explicit list of deferred topics that belong to future backend-focused agenda. + +## Candidate Decisions + +### 1. Builtin Surfaces Are Frontend-Validated Before Any Backend Contract + +Candidate direction: + +- builtin names and metadata usage are validated at frontend scope per existing specs, +- and lowering emits deterministic outcomes or deterministic rejection. + +### 2. Diagnostics Contract Is Mandatory For Frontend-Lowering Failures + +Candidate direction: + +- code/severity/primary attribution are fixed and test-backed for required rejection classes, +- enabling reliable regression protection. + +### 3. Gate Evidence Is Small But Mandatory + +Candidate direction: + +- each required obligation has at least one positive and one negative fixture where applicable, +- with assertions for lexer/parser/AST/IRBackend/diagnostics. + +### 4. Backend Topics Are Explicitly Deferred + +Candidate direction: + +- VM lowering, bytecode mapping, runtime, verifier, and loader remain out of this agenda, +- and are listed as deferred backlog topics. + +## Questions To Resolve In The Room + +1. Which builtin scenarios are mandatory in v1 fixture corpus? +2. Which lowering-related diagnostics are mandatory to freeze now? +3. What is the minimum evidence bar to declare `13` frontend slice closed? +4. Which open points are explicitly deferred without blocking frontend progress? + +## Expected Outputs + +1. a decision note on builtin frontend-lowering obligations, +2. a decision note on diagnostics/test evidence obligations, +3. and a closure checklist for `13` frontend scope. + +## Explicit Deferrals + +- VM lowering design, +- bytecode/PBX mapping, +- runtime execution contracts, +- verifier and loader internals. + +## Inputs + +- `docs/pbs/specs/6.1. Intrinsics and Builtin Types 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` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` +- `docs/pbs/agendas/13.3. IR and Lowering Workshop 3 - Callables, Services, Contracts, and Callbacks.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 deleted file mode 100644 index 6fdd9d3a..00000000 --- a/docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md +++ /dev/null @@ -1,113 +0,0 @@ -# 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? - -## Proposed Workshop Sequence - -### Workshop 1: Compatibility Domains and Promise Levels - -Purpose: - -- define the domains PBS makes compatibility promises about, -- and decide the strength of each promise. - -Expected decisions: - -- source, stdlib, cartridge, artifact, and runtime domain boundaries, -- and behavioral versus binary compatibility split. - -### Workshop 2: Deprecation, Removal, and Migration Duties - -Purpose: - -- close the lifecycle policy for changes that affect published users. - -Expected decisions: - -- deprecation windows, -- removal preconditions, -- and migration tooling versus documentation-only obligations. - -### Workshop 3: Compatibility Matrices and Published Claims - -Purpose: - -- decide how compatibility claims are expressed across language line, stdlib line, runtime line, and conformance level. - -Expected decisions: - -- matrix shape, -- supported-line expectations, -- and alignment with `13`. - -### Workshop 4: Artifact and PBX Compatibility Policy - -Purpose: - -- decide whether artifact compatibility has an independent policy track from source compatibility. - -Expected decisions: - -- PBX compatibility promise, -- runtime-loading compatibility boundaries, -- and obligations when the artifact line changes. - -## 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` diff --git a/docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md b/docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md deleted file mode 100644 index 7abd1a17..00000000 --- a/docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md +++ /dev/null @@ -1,97 +0,0 @@ -# PBS Compatibility Workshop 1 - -Status: Active - -## Purpose - -Run the first focused discussion for `17. Compatibility and Evolution Policy.md` on the top-level policy model: - -- which compatibility domains PBS recognizes, -- and what strength of promise applies to each. - -## Why This Slice First - -This slice should come first because every deprecation, migration, and matrix policy depends on a clean definition of domains and promise levels. - -## Proposed Meeting Order - -1. Reconfirm already-settled governance and versioning inputs. -2. Close the compatibility domains. -3. Close the promise level for each domain. -4. Close behavioral versus binary compatibility terminology. -5. Record migration and matrix issues for later workshops. - -## Decisions To Produce - -1. The compatibility domains PBS speaks about normatively. -2. The promise level for each domain. -3. The behavioral versus binary compatibility split. -4. The relationship between claim level and compatibility promise. - -## Candidate Decisions - -### 1. Recognize Separate Domains - -Candidate direction: - -- PBS should distinguish at least: - source compatibility, - stdlib compatibility, - cartridge/runtime compatibility, - artifact compatibility, - and conformance-claim compatibility. - -Rationale: - -- Different breakages affect different users and toolchains. - -### 2. Promise Strength Differs By Domain - -Candidate direction: - -- source and published-cartridge behavior get the strongest promise, -- stdlib and artifact domains may have tighter line-based conditions, -- partial conformance claims get narrower promises than full ones. - -Rationale: - -- This avoids one vague compatibility slogan that means too many things. - -### 3. Separate Behavioral From Binary Compatibility - -Candidate direction: - -- source-level and runtime-observable behavior compatibility is not the same as artifact binary compatibility, -- and the policy should state both explicitly. - -Rationale: - -- This prevents PBX policy from silently driving all evolution policy. - -## Questions To Resolve In The Room - -1. What are the minimum compatibility domains that PBS must name explicitly? -2. Which domains deserve the strongest guarantees? -3. Is cartridge compatibility mainly behavioral, binary, or both? -4. How does staged conformance affect compatibility promises? -5. Does stdlib compatibility belong as its own domain or inside source compatibility? - -## Expected Outputs - -1. a decision record for compatibility domains, -2. a promise-level matrix draft, -3. and terminology targets for `17`. - -## Explicit Deferrals For Workshop 2 - -- deprecation windows, -- migration-tooling duties, -- and artifact-line change policy. - -## Inputs - -- `docs/pbs/specs/2. Governance and Versioning.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/decisions/Conformance Claim Levels Decision.md` -- `docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md` diff --git a/docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md b/docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md deleted file mode 100644 index e6c6c428..00000000 --- a/docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md +++ /dev/null @@ -1,94 +0,0 @@ -# PBS Compatibility Workshop 2 - -Status: Active - -## Purpose - -Run the second focused discussion for `17. Compatibility and Evolution Policy.md` on lifecycle discipline: - -- deprecation, -- removal, -- migration duties, -- and when tooling is mandatory versus documentation-only guidance. - -## Why This Slice Second - -This slice follows domain definition because the right deprecation and migration policy depends on what kind of surface is changing. - -## Proposed Meeting Order - -1. Reconfirm the compatibility domains and promise strengths from Workshop 1. -2. Close deprecation requirements by domain. -3. Close removal preconditions. -4. Close migration-tooling versus documentation obligations. -5. Record matrix consequences for Workshop 3. - -## Decisions To Produce - -1. Deprecation windows by domain. -2. Removal preconditions by domain. -3. Migration-tooling obligations. -4. The policy for changes that are incompatible but still deliberate. - -## Candidate Decisions - -### 1. Deprecation Must Precede Removal For User-Facing Stable Surfaces - -Candidate direction: - -- source and stdlib user-facing surfaces require explicit deprecation before removal, -- unless the change is confined to a new major line. - -Rationale: - -- This matches additive-first evolution goals. - -### 2. Migration Tooling Is Required Only For High-Frequency Or High-Impact Breaks - -Candidate direction: - -- some incompatible changes require tooling, -- others may be served by precise migration notes, -- and the policy should name the factors that trigger tooling duty. - -Rationale: - -- This is more realistic than requiring tools for every break. - -### 3. Removal Must Be Paired With An Announced Support Boundary - -Candidate direction: - -- removal is allowed only with a clearly documented support boundary and migration path or explanation. - -Rationale: - -- This makes policy operational rather than rhetorical. - -## Questions To Resolve In The Room - -1. Which domains require deprecation before removal? -2. What triggers mandatory migration tooling? -3. Can artifact-line changes skip deprecation if they stay behind a new major line? -4. How should deprecated stdlib APIs be tested in conformance while still supported? -5. When is documentation-only migration guidance enough? - -## Expected Outputs - -1. a decision record for deprecation policy, -2. a decision record for migration duties, -3. and lifecycle section targets for `17`. - -## Explicit Deferrals For Workshop 3 - -- compatibility matrices, -- published-claim aging, -- and artifact compatibility line policy. - -## Inputs - -- `docs/pbs/specs/2. Governance and Versioning.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md` - diff --git a/docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md b/docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md deleted file mode 100644 index 5c70ee01..00000000 --- a/docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md +++ /dev/null @@ -1,107 +0,0 @@ -# PBS Compatibility Workshop 3 - -Status: Decision recorded - -## Purpose - -Run the third focused discussion for `17. Compatibility and Evolution Policy.md` on support claims over time: - -- compatibility matrices, -- supported combinations, -- published claims, -- and how those claims age or retire. - -## Resolution Snapshot - -This workshop direction is now recorded in: - -- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md` - -Integrated spec follow-up belongs to: - -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` - -## Why This Slice Third - -This slice follows domain and lifecycle policy because matrix policy is where those choices become operational. - -## Proposed Meeting Order - -1. Reconfirm domain and lifecycle decisions from Workshops 1 and 2. -2. Close the shape of the compatibility matrix. -3. Close what counts as a published support claim. -4. Close how claims retire or narrow over time. -5. Record artifact-specific leftovers for Workshop 4. - -## Decisions To Produce - -1. The compatibility-matrix dimensions PBS must publish. -2. The policy for published support claims. -3. The relationship between claims, conformance, and regression. -4. The retirement policy for supported combinations. - -## Candidate Decisions - -### 1. Publish A Matrix Across The Major Compatibility Domains - -Candidate direction: - -- the matrix should cover at least: - language line, - stdlib line, - runtime line, - and conformance claim level. - -Rationale: - -- These are the main axes users will rely on. - -### 2. Published Claims Must Be Backed By Conformance Or Regression Evidence - -Candidate direction: - -- support claims are not just prose; -- they must correspond to maintained test evidence where support is promised. - -Rationale: - -- This aligns policy with `13`. - -### 3. Unsupported Combinations Must Be Explicit - -Candidate direction: - -- the matrix must allow explicit “unsupported” states rather than implying silence equals support. - -Rationale: - -- This reduces accidental ambiguity. - -## Questions To Resolve In The Room - -1. What exact axes belong in the official matrix? -2. Must every supported combination have conformance evidence? -3. How should experimental or provisional combinations be labeled? -4. When support is dropped, how is that reflected in the matrix and docs? -5. Which parts of this are policy versus test-harness detail? - -## Expected Outputs - -1. a decision record for the compatibility-matrix model, -2. a published-claims policy note, -3. and alignment tasks for `13`. - -## Explicit Deferrals For Workshop 4 - -- PBX compatibility, -- binary-loading policy, -- and artifact-line changes. - -## Inputs - -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md` -- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md` -- `docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md` diff --git a/docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md b/docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md deleted file mode 100644 index ff13d243..00000000 --- a/docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md +++ /dev/null @@ -1,93 +0,0 @@ -# PBS Compatibility Workshop 4 - -Status: Active - -## Purpose - -Run the fourth focused discussion for `17. Compatibility and Evolution Policy.md` on artifact compatibility: - -- PBX compatibility, -- runtime-loading compatibility, -- and how artifact-line changes are versioned and promised. - -## Why This Slice Last - -This slice should come last because artifact policy is the most backend-dependent and should be informed by the broader domain and matrix decisions first. - -## Proposed Meeting Order - -1. Reconfirm the source, stdlib, cartridge, and matrix policy already chosen. -2. Decide whether artifact compatibility is an independent policy track. -3. Decide PBX and runtime-loading promise boundaries. -4. Decide how artifact-line changes are versioned and communicated. -5. Record final integration tasks for `17`, `15`, and `19`. - -## Decisions To Produce - -1. Whether artifact compatibility is independent from source compatibility. -2. The promise boundary for PBX and loader compatibility. -3. The versioning and communication policy for artifact-line changes. -4. The relationship between artifact policy and published cartridge support. - -## Candidate Decisions - -### 1. Artifact Compatibility Is A Distinct Policy Track - -Candidate direction: - -- PBX and emitted-artifact compatibility should be named explicitly rather than assumed from source compatibility. - -Rationale: - -- Binary and loader compatibility carry different risks and evolution constraints. - -### 2. Runtime Loading Promise Must Be Stated By Supported Line - -Candidate direction: - -- artifact compatibility should be expressed against explicit runtime and artifact lines, -- not as a timeless blanket guarantee. - -Rationale: - -- This keeps the promise honest and testable. - -### 3. Artifact-Line Breaks Require Explicit Version Signaling - -Candidate direction: - -- incompatible artifact changes require an explicit line or major-boundary signal, -- plus migration or tooling guidance when older published cartridges are affected. - -Rationale: - -- This aligns artifact evolution with the broader compatibility policy. - -## Questions To Resolve In The Room - -1. How strong should PBX compatibility promises be? -2. Are published cartridges protected mainly by source compatibility or by explicit artifact-line support? -3. What counts as an artifact compatibility break? -4. Must artifact-line changes always align with major language-version changes? -5. How should loader support boundaries be documented and tested? - -## Expected Outputs - -1. a decision record for artifact compatibility policy, -2. a PBX/runtime promise note, -3. and final section targets for `17`. - -## Explicit Deferrals - -- exact PBX layout details, -- exact loader algorithms, -- and binary test harness implementation. - -## Inputs - -- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution 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` -- `docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md` diff --git a/docs/pbs/decisions/Allocation and Cost Visibility Decision.md b/docs/pbs/decisions/Allocation and Cost Visibility Decision.md index 9f014ee1..c8cee21c 100644 --- a/docs/pbs/decisions/Allocation and Cost Visibility Decision.md +++ b/docs/pbs/decisions/Allocation and Cost Visibility Decision.md @@ -142,7 +142,7 @@ This decision record does not yet close: This decision should feed at least: - `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` ## 12. Validation Notes diff --git a/docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md b/docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md index dd273242..193f53fe 100644 --- a/docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md +++ b/docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md @@ -5,8 +5,8 @@ Cycle: Conformance agenda closure pass Superseded by: -- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` (Quality-Gate Baseline) +- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) +- `docs/general/specs/19. Verification and Safety Checks Specification.md` (Quality-Gate Baseline) Superseded on: 2026-03-04 @@ -84,7 +84,7 @@ This model is intentionally small. It is sufficient to prevent fake portability The adopted boundary is: - `13. Conformance Test Specification.md` defines which invariant families are pass/fail conformance obligations and which fixture assumptions must be declared; -- `12. IR and Lowering Specification.md` defines the semantic and artifact-boundary facts that lowering must preserve before loader or verifier work begins; +- `13. Lowering IRBackend Specification.md` defines the semantic and artifact-boundary facts that lowering must preserve before loader or verifier work begins; - `15. Bytecode and PBX Mapping Specification.md` defines the PBX/bytecode-visible mapping of those facts into inspectable artifact surfaces; - `19. Verification and Safety Checks Specification.md` defines the later validation and rejection obligations applied after lowering and, where relevant, after loader patching. @@ -113,16 +113,16 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` It should also constrain later work in: -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` +- `docs/general/specs/17. Compatibility and Evolution Policy.md` - `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md` -- `docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md` +- `docs/pbs/agendas/13.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md` ## 9. Validation Notes diff --git a/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md b/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md index 8218b758..6c3b3875 100644 --- a/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md +++ b/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md @@ -5,8 +5,8 @@ Cycle: Conformance and compatibility agenda closure pass Superseded by: -- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline) +- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) +- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline) Superseded on: 2026-03-04 @@ -146,13 +146,13 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` +- `docs/general/specs/13. Conformance Test Specification.md` +- `docs/general/specs/17. Compatibility and Evolution Policy.md` It should also constrain later work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` - `docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md` ## 11. Validation Notes diff --git a/docs/pbs/decisions/Conformance Claim Levels Decision.md b/docs/pbs/decisions/Conformance Claim Levels Decision.md index 4139d4dd..24675a4b 100644 --- a/docs/pbs/decisions/Conformance Claim Levels Decision.md +++ b/docs/pbs/decisions/Conformance Claim Levels Decision.md @@ -5,8 +5,8 @@ Cycle: Conformance agenda closure pass Superseded by: -- `docs/pbs/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline) +- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline) +- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline) Superseded on: 2026-03-04 @@ -146,14 +146,14 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` +- `docs/general/specs/13. Conformance Test Specification.md` +- `docs/general/specs/17. Compatibility and Evolution Policy.md` It should also constrain later work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` - `docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md` - `docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md` - `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md` diff --git a/docs/pbs/decisions/Diagnostics Contract Decision.md b/docs/pbs/decisions/Diagnostics Contract Decision.md index 3580da26..79f47a23 100644 --- a/docs/pbs/decisions/Diagnostics Contract Decision.md +++ b/docs/pbs/decisions/Diagnostics Contract Decision.md @@ -198,11 +198,11 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` ## 13. Validation Notes diff --git a/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md b/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md index 296eeb09..6111e45b 100644 --- a/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md +++ b/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md @@ -331,7 +331,7 @@ This decision should feed at least: - `docs/pbs/specs/9. Dynamic Semantics Specification.md` - `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` The unresolved cost and retention wording for these surfaces should be completed through: diff --git a/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md b/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md index 56acd549..1f8d7bab 100644 --- a/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md +++ b/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md @@ -113,12 +113,12 @@ This decision should feed at least: - `docs/pbs/specs/9. Dynamic Semantics Specification.md` - `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md` +- `docs/general/specs/16. Runtime Execution and Initialization Specification.md` It should also constrain future work in: -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` ## 9. Validation Notes diff --git a/docs/pbs/decisions/GC and Reachability Decision.md b/docs/pbs/decisions/GC and Reachability Decision.md index b65e6290..4cfa9f96 100644 --- a/docs/pbs/decisions/GC and Reachability Decision.md +++ b/docs/pbs/decisions/GC and Reachability Decision.md @@ -117,8 +117,8 @@ This decision record does not yet close: This decision should feed at least: - `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/16. Runtime Execution and Initialization Specification.md` ## 12. Validation Notes diff --git a/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md b/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md index 40a2bd74..2514b0a8 100644 --- a/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md +++ b/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md @@ -108,7 +108,7 @@ This decision record does not yet close: This decision should feed at least: - `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` +- `docs/general/specs/17. Compatibility and Evolution Policy.md` - `docs/pbs/specs/3. Core Syntax Specification.md` ## 11. Validation Notes diff --git a/docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md b/docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md index 8bfc90c9..3dadd587 100644 --- a/docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md +++ b/docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md @@ -121,19 +121,19 @@ Implementations may internally perform some of these checks during environment v This decision record does not yet close: - the full stdlib-surface policy of `18. Standard Library Surface Specification.md`, -- and the final lowering consequences in `12. IR and Lowering Specification.md`. +- and the final lowering consequences in `13. Lowering IRBackend Specification.md`. ## 11. Spec Impact This decision should feed at least: -- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/specs/18. Standard Library Surface Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/general/specs/18. Standard Library Surface Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` It should also constrain future work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` ## 12. Validation Notes diff --git a/docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md b/docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md index 4dc9724c..5a0b2d11 100644 --- a/docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md +++ b/docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md @@ -125,19 +125,19 @@ This decision record does not yet close: - per-overload import syntax, - aliasing policy for callable imports beyond the already-closed generic alias rules, -- and any lowering consequences in `12. IR and Lowering Specification.md`. +- and any lowering consequences in `13. Lowering IRBackend Specification.md`. ## 10. Spec Impact This decision should feed at least: -- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` It should also constrain future work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` ## 11. Validation Notes diff --git a/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md b/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md index abec82f3..8185610a 100644 --- a/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md +++ b/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md @@ -157,13 +157,13 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` It should also constrain future work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` - `docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md` - `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md` - `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md` diff --git a/docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md b/docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md index 3690f0df..b3357e0e 100644 --- a/docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md +++ b/docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md @@ -212,13 +212,13 @@ This decision record does not yet close: This decision should feed at least: -- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/general/specs/14. Name Resolution and Module Linking Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` It should also constrain future work in: -- `docs/pbs/specs/12. IR and Lowering Specification.md` +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` - `docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md` - `docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md` - `docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md` diff --git a/docs/pbs/decisions/Value Representation and Identity Decision.md b/docs/pbs/decisions/Value Representation and Identity Decision.md index 78eaf5ca..04de20fb 100644 --- a/docs/pbs/decisions/Value Representation and Identity Decision.md +++ b/docs/pbs/decisions/Value Representation and Identity Decision.md @@ -179,7 +179,7 @@ This decision should feed at least: - `docs/pbs/specs/10. Memory and Lifetime Specification.md` - `docs/pbs/specs/4. Static Semantics Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` +- `docs/pbs/specs/12. Diagnostics Specification.md` ## 12. Validation Notes diff --git a/docs/pbs/specs/1. Language Charter.md b/docs/pbs/specs/1. Language Charter.md index c159ba39..f80fac03 100644 --- a/docs/pbs/specs/1. Language Charter.md +++ b/docs/pbs/specs/1. Language Charter.md @@ -79,10 +79,10 @@ Before implementation starts, PBS must define at least: 4. Memory and Lifetime Specification. 5. Host ABI Binding Specification. 6. Module/Package Specification. -7. Diagnostics Specification. -8. IR and Lowering Specification. -9. Conformance Test Specification. -10. Compatibility and Evolution Policy. +7. AST Specification. +8. Diagnostics Specification. +9. Lowering IRBackend Specification. +10. Shared acceptance specs in `docs/general/specs` (Conformance, Compatibility, Verification). ## 11. Decision Rule diff --git a/docs/pbs/specs/11. AST Specification.md b/docs/pbs/specs/11. AST Specification.md new file mode 100644 index 00000000..b9e3351b --- /dev/null +++ b/docs/pbs/specs/11. AST Specification.md @@ -0,0 +1,105 @@ +# PBS AST Specification + +Status: Draft v0 +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. + +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. + +## 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. + +This document does not define: + +- static-semantics type rules, +- VM/runtime execution behavior, +- bytecode/PBX mapping, +- or backend-specific IR/optimizer internals. + +## 3. Authority and Precedence + +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 + +If a rule here conflicts with higher-precedence syntax or semantic rules, the higher-precedence rule wins. + +## 4. Normative Inputs + +This document depends on: + +- `3. Core Syntax Specification.md` +- `4. Static Semantics Specification.md` +- `12. Diagnostics Specification.md` +- `13. Lowering IRBackend Specification.md` + +## 5. AST Contract Baseline + +At minimum, parser output must provide: + +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. + +## 6. Structural Invariants + +Minimum structural invariants: + +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. + +## 7. Diagnostics Integration + +AST-related diagnostics must follow `12. Diagnostics Specification.md`: + +- stable `diagnostic code`, +- stable `severity`, +- stable primary source attribution. + +Parser/AST diagnostics are in `syntax` phase unless another higher-precedence rule assigns a different phase. + +## 8. Conformance and Test 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: + +1. representative valid AST shapes, +2. deterministic syntax rejection and recovery behavior, +3. stable source attribution for required diagnostics. + +## 9. Non-Goals + +- Defining one programming-language-neutral AST framework. +- Freezing one parser implementation architecture. +- Encoding runtime behavior in AST rules. + +## 10. 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. diff --git a/docs/pbs/specs/11. Diagnostics Specification.md b/docs/pbs/specs/12. Diagnostics Specification.md similarity index 97% rename from docs/pbs/specs/11. Diagnostics Specification.md rename to docs/pbs/specs/12. Diagnostics Specification.md index 14754925..18071ccc 100644 --- a/docs/pbs/specs/11. Diagnostics Specification.md +++ b/docs/pbs/specs/12. Diagnostics Specification.md @@ -47,7 +47,7 @@ Normative precedence: 6. `7. Cartridge Manifest and Runtime Capabilities Specification.md` 7. `9. Dynamic Semantics Specification.md` 8. `10. Memory and Lifetime Specification.md` -9. `12. IR and Lowering Specification.md` +9. `13. Lowering IRBackend Specification.md` 10. This document If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins. @@ -63,13 +63,13 @@ This document depends on, at minimum: - `7. Cartridge Manifest and Runtime Capabilities Specification.md` - `9. Dynamic Semantics Specification.md` - `10. Memory and Lifetime Specification.md` -- `12. IR and Lowering Specification.md` +- `13. Lowering IRBackend Specification.md` Relevant backend-facing integration points also include: -- `15. Bytecode and PBX Mapping Specification.md` -- `16. Runtime Execution and Initialization Specification.md` -- `19. Verification and Safety Checks Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/16. Runtime Execution and Initialization Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` ## 5. Already-Settled Inputs diff --git a/docs/pbs/specs/12. IR and Lowering Specification.md b/docs/pbs/specs/12. IR and Lowering Specification.md deleted file mode 100644 index dc6860f3..00000000 --- a/docs/pbs/specs/12. IR and Lowering Specification.md +++ /dev/null @@ -1,156 +0,0 @@ -# PBS IR and Lowering Specification - -Status: Draft v0 (Skeleton) -Applies to: lowering of bound PBS programs into internal compiler IR and runtime-facing artifacts - -## 1. Purpose - -This document will define the normative lowering contract from PBS source semantics to implementation artifacts. - -Its purpose is to make backend-facing behavior explicit enough that: - -- different compilers lower the same bound program compatibly, -- host-binding emission does not drift from frontend resolution, -- builtin and intrinsic lowering does not drift from VM-owned metadata, -- later verifier and loader behavior can rely on stable artifact expectations, -- conformance can test more than parser and binder behavior. - -## 2. Scope - -This document is intended to define: - -- the minimum semantic obligations of the compiler after parsing, binding, and type checking, -- the role of internal IR as an implementation stage, -- what semantic facts lowering must preserve, -- lowering of control flow, calls, callbacks, services, contracts, constants, and host-backed calls, -- lowering of builtin projections, builtin constants, and intrinsic member calls, -- artifact-facing requirements that must hold before loader/verifier consumption. - -This document does not define: - -- the full PBX binary layout, -- optimizer heuristics or performance tuning strategy, -- the exact in-memory data structures of one compiler implementation, -- runtime GC algorithm internals. - -## 3. Authority and Precedence - -Normative precedence: - -1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`) -2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`) -3. `3. Core Syntax Specification.md` -4. `4. Static Semantics Specification.md` -5. `5. Manifest, Stdlib, and SDK Resolution Specification.md` -6. `6. VM-owned vs Host-backed.md` -7. `6.1. Intrinsics and Builtin Types Specification.md` -8. `6.2. Host ABI Binding and Loader Resolution Specification.md` -9. `9. Dynamic Semantics Specification.md` -10. `10. Memory and Lifetime Specification.md` -11. This document - -If a lowering rule here contradicts a higher-precedence semantic rule, the higher-precedence rule wins. - -## 4. Normative Inputs - -This document depends on, at minimum: - -- `3. Core Syntax Specification.md` -- `4. Static Semantics Specification.md` -- `5. Manifest, Stdlib, and SDK Resolution Specification.md` -- `6. VM-owned vs Host-backed.md` -- `6.1. Intrinsics and Builtin Types Specification.md` -- `6.2. Host ABI Binding and Loader Resolution Specification.md` -- `9. Dynamic Semantics Specification.md` -- `10. Memory and Lifetime Specification.md` - -This document is expected to close in coordination with `15. Bytecode and PBX Mapping Specification.md` and `16. Runtime Execution and Initialization Specification.md`. - -## 5. Already-Settled Inputs - -The following inputs are already fixed elsewhere and must not be contradicted here: - -- The compiler consumes reserved `Host` metadata while resolving host-backed SDK members. -- The compiler consumes reserved `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot` metadata while resolving builtin shells. -- The compiler emits canonical host-binding declarations into the PBX `SYSC` table. -- The compiler emits host-backed callsites in pre-load form as `HOSTCALL `. -- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence. -- The loader, not the compiler, resolves canonical host bindings to final numeric syscall identifiers. -- Builtin projection lowering remains VM-owned and does not emit host-binding metadata. -- Builtin constants lower through VM-owned materialization rather than through ordinary compile-time constant evaluation. -- Builtin intrinsic member calls lower through a VM-owned intrinsic path rather than through `SYSC`, `HOSTCALL`, or `SYSCALL`. -- Stdlib interface modules are compile-time-only and do not emit executable bytecode by themselves. -- Backend-originated failures only enter the PBS-facing diagnostics contract when they remain source-attributable and user-actionable. - -## 6. Current Lowering and Artifact Boundary Baseline - -The current backend-facing division of responsibility is: - -- this document defines what semantic and artifact-boundary facts lowering must preserve before verifier or loader validation, -- `15. Bytecode and PBX Mapping Specification.md` defines how those facts appear in PBX/bytecode-visible form, -- and `19. Verification and Safety Checks Specification.md` defines which later safety and validity checks are applied after lowering and, where relevant, after loader patching. - -At minimum, the current lowering baseline requires: - -1. admitted host-backed uses lower to canonical host-binding declarations and pre-load call references rather than to resolved syscall identifiers; -2. canonical host-binding declarations remain deduplicated by canonical identity and ordered by first occurrence; -3. VM-owned builtin projections, builtin constants, and intrinsic callsites remain outside host-binding metadata surfaces; -4. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves; -5. lowering preserves enough attribution metadata that at least one source location can later be recovered for backend failures that remain source-attributable and user-actionable. - -This document defines those obligations as preserved facts, not as one exact PBX encoding. - -## 7. Initial Section Targets - -At minimum, the completed document should contain normative sections for: - -1. lowering preconditions, -2. semantic obligations preserved by IR, -3. lowering of expressions and control flow, -4. lowering of callable categories, -5. lowering of `optional` and `result` constructs, -6. lowering of callbacks, services, and contracts, -7. lowering of builtin projections, builtin constants, and builtin intrinsic calls, -8. host-binding emission, -9. artifact invariants required before verifier/loader stages. - -## 8. TODO - -The following items remain to be closed before this document can be considered complete. - -### 8.1 Depends on `9. Dynamic Semantics Specification.md` - -- Which evaluation-order guarantees must be preserved explicitly in lowering. -- Which traps, abrupt completions, and propagation paths require dedicated lowered forms. -- Whether callback formation and contract dispatch need dedicated runtime artifacts or only implementation-defined IR shapes. - -### 8.2 Depends on `10. Memory and Lifetime Specification.md` - -- Which lowered operations allocate, alias, retain, or cross the host-memory boundary. -- Which runtime storage/identity facts IR must preserve explicitly versus infer later. - -### 8.3 Still open across this document and adjacent backend-facing specs - -- Whether one canonical IR is normative or only the preserved semantic obligations are normative. -- The exact mapping from bound PBS constructs to PBX/bytecode-facing artifacts beyond already-settled host-binding and intrinsic behavior. -- Lowering strategy for services, contracts, callbacks, tuples, and result propagation. -- Whether declaration-based intrinsic preload forms such as `INTRCALL` are part of v1 lowering or whether compilers should emit final `INTRINSIC ` directly for a selected VM line. -- Which additional artifact invariants beyond the current conformance baseline belong here versus in `15`. -- Which richer attribution/debug hooks, if any, should be added beyond the minimum one-location recovery baseline already required for in-scope backend failures. - -## 9. Non-Goals - -- Freezing one optimizer design. -- Requiring one compiler implementation architecture. -- Repeating the full bytecode ISA specification. -- Defining loader-side patching internals already owned elsewhere. - -## 10. Exit Criteria - -This document is ready to move beyond skeleton status only when: - -1. every semantically distinct core construct has an explicit lowering story, -2. the boundary between source semantics, compiler IR, and emitted artifacts is clear, -3. host-binding emission is fully aligned with the Host ABI spec, -4. builtin and intrinsic lowering is fully aligned with the VM-owned builtin spec, -5. the document no longer relies on unresolved backend `TODO` items for ordinary v1 lowering behavior. diff --git a/docs/pbs/specs/13. Lowering IRBackend Specification.md b/docs/pbs/specs/13. Lowering IRBackend Specification.md new file mode 100644 index 00000000..d9cdb435 --- /dev/null +++ b/docs/pbs/specs/13. Lowering IRBackend Specification.md @@ -0,0 +1,109 @@ +# PBS Lowering IRBackend Specification + +Status: Draft v1 (Frontend Scope) +Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile` + +## 1. Purpose + +This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`. + +Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve. + +## 2. Scope + +This document defines: + +- required preconditions before lowering starts, +- semantic obligations preserved in `IRBackend`, +- deterministic rejection behavior for unsupported frontend-lowering forms, +- and diagnostics attribution obligations for lowering failures in frontend scope. + +This document does not define: + +- VM lowering (`IRVM`), +- bytecode/PBX mapping, +- runtime execution behavior, +- verifier/loader internals. + +Those concerns belong to shared acceptance specs under `docs/general/specs`. + +## 3. Authority and Precedence + +Normative precedence: + +1. `3. Core Syntax Specification.md` +2. `4. Static Semantics Specification.md` +3. `11. AST Specification.md` +4. `12. Diagnostics Specification.md` +5. This document + +If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins. + +## 4. Normative Inputs + +This document depends on: + +- `3. Core Syntax Specification.md` +- `4. Static Semantics Specification.md` +- `11. AST Specification.md` +- `12. Diagnostics Specification.md` + +## 5. Lowering Preconditions + +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. + +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: + +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. + +The normative contract is obligation-based, not tied to one mandatory in-memory class graph. + +## 7. Deterministic Rejection Policy + +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, +3. and unsupported forms must not silently degrade into different valid 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. + +## 9. Explicit Deferrals + +The following are intentionally out of scope for this document: + +- `IRBackend -> IRVM` lowering, +- artifact encoding and binary layout, +- runtime lifecycle behavior, +- verifier and loader checks. + +## 10. Non-Goals + +- Freezing one optimizer strategy. +- Freezing one compiler architecture. +- Repeating runtime or bytecode authority. + +## 11. Exit Criteria + +This document is healthy when: + +1. lowering preconditions are explicit, +2. preserved `IRBackend` obligations are explicit, +3. deterministic rejection policy is explicit and test-backed, +4. and scope boundaries with general/backend acceptance specs are explicit. diff --git a/docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md b/docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md index f3c6c688..7325aab3 100644 --- a/docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md +++ b/docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md @@ -67,7 +67,7 @@ This document depends on, at minimum: - `5. Manifest, Stdlib, and SDK Resolution Specification.md` - `6.2. Host ABI Binding and Loader Resolution Specification.md` - `6. VM-owned vs Host-backed.md` -- `12. IR and Lowering Specification.md` +- `13. Lowering IRBackend Specification.md` - `15. Bytecode and PBX Mapping Specification.md` ## 5. Core Model diff --git a/docs/pbs/specs/README.md b/docs/pbs/specs/README.md index 639a59d3..3959f917 100644 --- a/docs/pbs/specs/README.md +++ b/docs/pbs/specs/README.md @@ -4,10 +4,13 @@ This directory contains the normative PBS specification set. ## Purpose -Specs define the official PBS contract. +Specs define the official PBS language/frontend contract. They exist to make behavior, constraints, and interfaces stable across implementations and reviews. +Cross-language acceptance rules are not defined here. +Those are maintained in `docs/general/specs`. + ## Expected Format The exact structure may vary by document, but a spec should usually contain: @@ -46,3 +49,11 @@ Specs should normally be fed by: 3. then spec integration. If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first. + +## Current Chapter Focus + +The active PBS chapter focus is: + +- `11. AST Specification.md` +- `12. Diagnostics Specification.md` +- `13. Lowering IRBackend Specification.md`