From 96f971bbe42a6b938bcb4621c40f737d0ce8b27d Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 4 Mar 2026 19:28:00 +0000 Subject: [PATCH] agendas and decisions --- docs/pbs/agendas/11. Diagnostics Agenda.md | 125 ---------- ...1 - Diagnostic Identity and Attribution.md | 143 ------------ ...op 2 - Wording, Notes, and Help Surface.md | 113 --------- ...3 - Cost Diagnostics and Warning Policy.md | 127 ----------- ...- Backend-Originated Diagnostic Mapping.md | 125 ---------- .../agendas/13. Conformance Test Agenda.md | 116 ---------- ...e Workshop 1 - Conformance Claim Levels.md | 98 -------- ...urce-Level Oracle and Diagnostic Oracle.md | 96 -------- ...Artifact-Level Conformance and Fixtures.md | 98 -------- ...- Regression and Compatibility Matrices.md | 100 -------- ...ompatibility Domains and Promise Levels.md | 3 +- ...atibility Matrices and Published Claims.md | 16 +- ...Allocation and Cost Visibility Decision.md | 2 +- ... Conformance and Fixture Model Decision.md | 133 +++++++++++ ...ty Matrix and Published Claims Decision.md | 164 +++++++++++++ .../Conformance Claim Levels Decision.md | 167 ++++++++++++++ .../Diagnostics Contract Decision.md | 215 ++++++++++++++++++ ...c Semantics - Branch Selection Decision.md | 2 +- ...ic Semantics - Effect Surfaces Decision.md | 2 +- ...ic Semantics - Execution Model Decision.md | 2 +- .../decisions/GC and Reachability Decision.md | 2 +- .../Host Memory Boundary Decision.md | 2 +- ...me Control and Future Profiles Decision.md | 2 +- ...Builtin Shells and Host Owners Decision.md | 2 +- ... Sets and Cross-Module Linking Decision.md | 2 +- ...ution - Linking Phase Boundary Decision.md | 2 +- ...n - Scope, Lookup, and Imports Decision.md | 2 +- ...ue Representation and Identity Decision.md | 2 +- .../specs/11. Diagnostics Specification.md | 176 +++++++++----- .../12. IR and Lowering Specification.md | 36 ++- .../13. Conformance Test Specification.md | 198 ++++++---------- ... Bytecode and PBX Mapping Specification.md | 32 ++- .../17. Compatibility and Evolution Policy.md | 126 ++++++---- ...ication and Safety Checks Specification.md | 106 +++++---- 34 files changed, 1090 insertions(+), 1447 deletions(-) delete mode 100644 docs/pbs/agendas/11. Diagnostics Agenda.md delete mode 100644 docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md delete mode 100644 docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md delete mode 100644 docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md delete mode 100644 docs/pbs/agendas/11.4. Diagnostics Workshop 4 - Backend-Originated Diagnostic Mapping.md delete mode 100644 docs/pbs/agendas/13. Conformance Test Agenda.md delete mode 100644 docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md delete mode 100644 docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md delete mode 100644 docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md delete mode 100644 docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.md create mode 100644 docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md create mode 100644 docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md create mode 100644 docs/pbs/decisions/Conformance Claim Levels Decision.md create mode 100644 docs/pbs/decisions/Diagnostics Contract Decision.md diff --git a/docs/pbs/agendas/11. Diagnostics Agenda.md b/docs/pbs/agendas/11. Diagnostics Agenda.md deleted file mode 100644 index 7a64c760..00000000 --- a/docs/pbs/agendas/11. Diagnostics Agenda.md +++ /dev/null @@ -1,125 +0,0 @@ -# PBS Diagnostics Agenda - -Status: Active - -## Purpose - -Drive the remaining discussions needed to close `11. Diagnostics Specification.md` without inventing backend or UI policy prematurely. - -## Context - -The diagnostics spec already fixes the minimum phase split and source-attribution baseline, but it still leaves open: - -- whether diagnostic codes are mandatory in v1, -- which parts of wording are normative, -- what cross-file attribution is required for import and barrel failures, -- whether cost-facing warnings become part of conformance, -- and how backend-facing failures map back to source once lowering and PBX mapping are closed. - -This agenda should keep the diagnostics contract narrow, deterministic, and implementable by more than one toolchain. - -## Decisions To Produce - -1. Decide the minimum normative diagnostic identity model for v1: - phase only, phase plus category, or stable machine-readable code. -2. Decide the minimum normative attribution package: - file, primary span, secondary span/note requirements, and cross-file references. -3. Decide which human-facing wording requirements are normative versus illustrative. -4. Decide whether any qualitative cost diagnostics are mandatory in v1. -5. Decide how lowering, verifier, and load-facing failures surface back into the PBS-facing diagnostics contract. - -## Core Questions - -1. Is a stable diagnostic code required for conformance, or is deterministic rejection phase and source attribution enough? -2. For import, barrel, and cross-module lookup failures, what exact locations must be reported? -3. Must notes and help text exist for certain classes of error, or are they optional tooling quality? -4. Which backend-originated failures remain PBS diagnostics versus artifact-tool diagnostics? -5. Are warnings part of the normative contract at all in v1, and if so which ones? - -## Proposed Workshop Sequence - -### Workshop 1: Diagnostic Identity and Attribution - -Purpose: - -- close the minimum diagnostic identity model, -- close required source-attribution fields, -- and decide cross-file attribution for import and linking failures. - -Expected decisions: - -- phase-only versus stable code model, -- required file/span/note package, -- and minimum cross-file reporting rules. - -### Workshop 2: Wording, Notes, and Help Surface - -Purpose: - -- decide what human-facing wording is normative, -- whether notes/help are required anywhere, -- and where implementation freedom should remain. - -Expected decisions: - -- wording stability boundary, -- note/help obligations, -- and illustrative versus normative examples policy. - -### Workshop 3: Cost Diagnostics and Warning Policy - -Purpose: - -- decide whether warnings are part of v1 conformance at all, -- and, if yes, which qualitative cost warnings become mandatory. - -Expected decisions: - -- warning-in-conformance yes or no, -- mandatory versus optional cost notes, -- and boundary between diagnostics and profiling/tooling. - -### Workshop 4: Backend-Originated Diagnostic Mapping - -Purpose: - -- decide how lowering, verifier, and load-facing failures map back to the PBS-facing contract. - -Expected decisions: - -- PBS-facing versus artifact-facing boundary, -- source-mapping obligations for backend failures, -- and inputs needed from `12` and `15`. - -## Expected Spec Material - -The resulting spec work should be able to add or close sections for: - -- diagnostic identity and stability, -- source attribution rules, -- cross-file attribution rules, -- optional versus required notes/help, -- warning taxonomy boundaries, -- backend-facing diagnostic mapping boundaries, -- and conformance hooks consumed by `13. Conformance Test Specification.md`. - -## Non-Goals - -- Designing IDE presentation, colors, or UX. -- Building a complete trap taxonomy. -- Standardizing localization. -- Freezing one internal compiler error architecture. -- Rewriting rejection rules already owned by syntax, semantics, or loader specs. - -## Inputs - -- `docs/pbs/specs/3. Core Syntax Specification.md` -- `docs/pbs/specs/4. Static Semantics Specification.md` -- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md` -- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` -- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md` -- `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` diff --git a/docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md b/docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md deleted file mode 100644 index db6b68cc..00000000 --- a/docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md +++ /dev/null @@ -1,143 +0,0 @@ -# PBS Diagnostics Workshop 1 - -Status: Active - -## Purpose - -Run the first focused discussion for `11. Diagnostics Specification.md` on the minimum diagnostic contract: - -- diagnostic identity, -- phase attribution, -- source attribution, -- and cross-file attribution for import and linking failures. - -## Why This Slice First - -This slice should come first because every later diagnostics discussion depends on a stable answer to: - -- what one diagnostic fundamentally is, -- what metadata is guaranteed, -- and what conformance is even allowed to assert. - -It should stay narrow and avoid wording or warning policy for now. - -## Proposed Meeting Order - -1. Reconfirm already-settled rejection and phase facts. -2. Close the minimum diagnostic identity model. -3. Close the minimum source-attribution package. -4. Close cross-file attribution for import, barrel, and linking failures. -5. Record carry-forward items for wording and warning workshops. - -## Already-Settled Inputs To Reconfirm - -The meeting should explicitly reaffirm: - -- syntax and static semantics already define required rejection classes, -- manifest/import failures are deterministic compile-time failures, -- load-facing malformed or unauthorized host usage is deterministic, -- traps are fatal runtime outcomes rather than ordinary diagnostics, -- and stable source spans are already required at token and AST level. - -These should not be reopened here. - -## Decisions To Produce - -1. The minimum normative identity of a diagnostic. -2. The minimum mandatory attribution fields. -3. Cross-file attribution rules for import and barrel failures. -4. The smallest stable phase vocabulary diagnostics must expose. - -## Candidate Decisions - -### 1. Diagnostic Identity Is Phase Plus Stable Class, Not Mandatory Numeric Code - -Candidate direction: - -- v1 requires deterministic phase attribution and a stable rejection class. -- A machine-readable code is allowed but not yet mandatory. -- Human wording is not the identity of the diagnostic. - -Rationale: - -- This keeps the contract stable without overfitting to one toolchain code system. -- It leaves room to add codes later without making v1 blocked on taxonomy design. - -Alternative to discuss: - -- require stable codes now because conformance and tooling benefit from them. - -### 2. Minimum Attribution Package Is File, Primary Span, and Message Class - -Candidate direction: - -- every source-attributable diagnostic must expose: - primary file, - primary source span or location, - stable phase, - and enough human-readable content to distinguish the rejection class. -- secondary notes are optional unless another rule explicitly requires them. - -Rationale: - -- This matches the current draft while making the required payload explicit. - -### 3. Cross-File Failures Need At Least One Primary Site And Optional Related Sites - -Candidate direction: - -- import failure must point primarily to the importing site, -- barrel-entry mismatch must point primarily to the barrel site, -- tools may additionally point to the unresolved or conflicting declaration site when known, -- but v1 does not require one exact note shape yet. - -Rationale: - -- This keeps source-facing diagnostics actionable without freezing one multi-span presentation format. - -### 4. Keep A Small Stable Phase Vocabulary - -Candidate direction: - -- the minimum stable external vocabulary is: - syntax, - static semantics, - manifest/import resolution, - linking, - and host-binding/capability admission. -- tools may subdivide internally if they map back deterministically. - -Rationale: - -- This gives `13` enough oracle structure without forcing one compiler pipeline. - -## Questions To Resolve In The Room - -1. Is phase plus stable class enough, or should v1 require diagnostic codes now? -2. Must every cross-file failure include more than one source location? -3. Should `linking` be a diagnostics phase name directly, or only a broader `resolution` bucket? -4. Are secondary spans purely optional, or mandatory for some classes such as conflicting imports? -5. What is the minimum conformance-friendly diagnostic payload that is still implementation-neutral? - -## Expected Outputs - -This workshop should produce: - -1. a decision record for diagnostic identity, -2. a decision record for required attribution fields, -3. a cross-file attribution policy draft, -4. and a cleanup list for `11`. - -## Explicit Deferrals For Workshop 2 - -- wording stability, -- notes/help obligations, -- warning policy, -- and backend-originated diagnostic mapping. - -## Inputs - -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md` -- `docs/pbs/agendas/11. Diagnostics Agenda.md` diff --git a/docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md b/docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md deleted file mode 100644 index d92ccd7e..00000000 --- a/docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md +++ /dev/null @@ -1,113 +0,0 @@ -# PBS Diagnostics Workshop 2 - -Status: Active - -## Purpose - -Run the second focused discussion for `11. Diagnostics Specification.md` on the human-facing surface: - -- wording stability, -- required versus optional notes, -- help text, -- and the boundary between normative content and tooling freedom. - -## Why This Slice Second - -This slice should follow Workshop 1 because wording cannot be scoped responsibly until the diagnostic identity and minimum attribution package are already settled. - -## Proposed Meeting Order - -1. Reconfirm the identity and attribution baseline from Workshop 1. -2. Close which human-facing wording elements are normative. -3. Close whether notes and help text are ever required. -4. Close the illustrative versus normative example policy. -5. Record warning and backend mapping topics for later workshops. - -## Decisions To Produce - -1. The normative boundary for human-facing wording. -2. Whether notes are mandatory for any diagnostic classes. -3. Whether help text is part of the v1 contract. -4. Whether example wording in the spec is illustrative or binding. - -## Candidate Decisions - -### 1. Human Wording Is Illustrative Except For Distinguishing The Rejection Class - -Candidate direction: - -- wording does not need to be byte-for-byte stable across implementations, -- but it must remain specific enough to distinguish the rejection class, -- and it must not contradict the governing spec rule. - -Rationale: - -- This preserves tool freedom while keeping diagnostics usable. - -### 2. Notes Are Optional By Default - -Candidate direction: - -- notes are optional quality features in v1, -- except where a later explicit rule may require related-location reporting for a narrow class. - -Rationale: - -- This keeps conformance small while leaving room for richer UX. - -Alternative to discuss: - -- require notes for multi-file conflicts because they are otherwise under-attributed. - -### 3. Help Text Is Outside Core Conformance - -Candidate direction: - -- help text, suggestions, and remediation hints are encouraged, -- but not part of the normative minimum contract. - -Rationale: - -- This avoids binding the spec to one editorial style or educational approach. - -### 4. Spec Examples Are Illustrative Unless Marked Normative - -Candidate direction: - -- sample messages in `11` are examples only, -- and the normative content lives in phase, attribution, and class requirements. - -Rationale: - -- This prevents examples from accidentally becoming the wording standard. - -## Questions To Resolve In The Room - -1. Should any diagnostic class require notes by default in v1? -2. Is there any value in standardizing wording templates now? -3. Should the spec reserve words like `error`, `note`, and `help` as output categories? -4. Does conformance need to inspect wording classes at all? -5. How much editorial freedom is acceptable before diagnostics stop feeling stable? - -## Expected Outputs - -This workshop should produce: - -1. a decision record for wording stability, -2. a decision record for notes/help obligations, -3. editing guidance for future `11` examples, -4. and carry-forward items for conformance discussion in `13`. - -## Explicit Deferrals For Workshop 3 - -- mandatory warnings, -- cost visibility taxonomy, -- and backend-originated failure mapping. - -## Inputs - -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/agendas/11. Diagnostics Agenda.md` -- `docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md` - diff --git a/docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md b/docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md deleted file mode 100644 index 28091399..00000000 --- a/docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md +++ /dev/null @@ -1,127 +0,0 @@ -# PBS Diagnostics Workshop 3 - -Status: Active - -## Purpose - -Run the third focused discussion for `11. Diagnostics Specification.md` on warnings and cost-facing diagnostics: - -- whether warnings are part of the normative contract, -- which qualitative cost facts deserve mandatory surfacing, -- and where diagnostics stops and profiling begins. - -## Why This Slice Third - -This slice should come after identity and wording because warning policy is only meaningful once the baseline diagnostic surface is already stable. - -It should also stay qualitative and avoid turning performance metrics into language law. - -## Proposed Meeting Order - -1. Reconfirm the cost facts already fixed by memory and lifetime rules. -2. Decide whether warnings are in or out of conformance. -3. Decide whether any qualitative cost diagnostics are mandatory. -4. Decide the boundary between diagnostics, linting, and profiling. -5. Record backend-mapping implications for Workshop 4. - -## Already-Settled Inputs To Reconfirm - -The meeting should explicitly reaffirm: - -- retention-bearing `bind` is a normatively relevant cost fact, -- host-boundary crossings are normatively relevant cost facts, -- copy-versus-alias behavior is normatively relevant qualitatively, -- and exact byte counts or performance rankings are not normative. - -## Decisions To Produce - -1. Whether warnings are part of v1 conformance. -2. Whether any qualitative cost diagnostics are mandatory. -3. The line between core diagnostics and optional tooling enrichment. -4. Whether cost diagnostics belong in `11` alone or also in `13`. - -## Candidate Decisions - -### 1. Warnings Are Outside Minimum Conformance In v1 - -Candidate direction: - -- conforming tools may emit warnings, -- but v1 does not require them for conformance. - -Rationale: - -- This keeps the baseline small. -- It avoids forcing one style of beginner guidance too early. - -Alternative to discuss: - -- require a very small mandatory warning set for high-value cost facts. - -### 2. Cost Notes Are Encouraged But Optional - -Candidate direction: - -- tools may surface notes or warnings for: - retention-bearing `bind`, - host-boundary crossings, - and observable alias-versus-copy behavior. -- none of these are mandatory in v1 conformance. - -Rationale: - -- This respects the normative cost model without overcommitting on tooling policy. - -### 3. Quantitative Performance Reporting Is Not Diagnostics Contract - -Candidate direction: - -- exact allocation counts, -- exact byte counts, -- and performance ranking remain outside the diagnostics spec. - -Rationale: - -- Those belong to profiling, not to language acceptance/rejection diagnostics. - -### 4. Linting Remains Implementation-Defined - -Candidate direction: - -- style hints, performance nudges, and educational suggestions remain implementation-defined unless later promoted deliberately. - -Rationale: - -- This prevents `11` from becoming a general lint catalog. - -## Questions To Resolve In The Room - -1. Is there any warning that is valuable enough to make mandatory in v1? -2. Should cost diagnostics be notes only, warnings only, or fully tool-defined? -3. Do host-boundary warnings belong to diagnostics, SDK guidance, or both? -4. How should `13` treat optional warnings in conformance fixtures? -5. Does excluding warnings from conformance undermine the beginner-facing goals of PBS? - -## Expected Outputs - -This workshop should produce: - -1. a decision record for warnings and conformance, -2. a decision record for cost diagnostics boundaries, -3. and follow-up notes for `13`. - -## Explicit Deferrals For Workshop 4 - -- backend-originated error mapping, -- source maps, -- verifier/load-facing attribution, -- and artifact-tool diagnostics. - -## Inputs - -- `docs/pbs/specs/10. Memory and Lifetime Specification.md` -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/agendas/11. Diagnostics Agenda.md` -- `docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md` - diff --git a/docs/pbs/agendas/11.4. Diagnostics Workshop 4 - Backend-Originated Diagnostic Mapping.md b/docs/pbs/agendas/11.4. Diagnostics Workshop 4 - Backend-Originated Diagnostic Mapping.md deleted file mode 100644 index 711b01e2..00000000 --- a/docs/pbs/agendas/11.4. Diagnostics Workshop 4 - Backend-Originated Diagnostic Mapping.md +++ /dev/null @@ -1,125 +0,0 @@ -# PBS Diagnostics Workshop 4 - -Status: Active - -## Purpose - -Run the fourth focused discussion for `11. Diagnostics Specification.md` on backend-originated failures: - -- lowering failures, -- verifier failures, -- load-facing failures, -- and how or whether they map back into the PBS-facing diagnostics contract. - -## Why This Slice Last - -This slice should come last because it depends on: - -- the phase vocabulary, -- the attribution baseline, -- and the lowering boundary being clearer. - -It should be the point where `11` explicitly interfaces with `12`, `15`, and `19`. - -## Proposed Meeting Order - -1. Reconfirm the frontend diagnostics baseline already closed. -2. Sort backend-originated failure classes. -3. Decide which backend failures remain PBS-facing diagnostics. -4. Decide which failures belong only to artifact-facing tooling. -5. Decide the minimum source-mapping obligations, if any. - -## Failure Classes To Sort - -- lowering rejection due to unsupported semantic state, -- host-binding emission mismatch, -- verifier rejection of malformed artifact invariants, -- loader rejection directly attributable to malformed or unauthorized PBS-facing artifact usage, -- and artifact-only corruption not attributable to valid PBS source. - -## Decisions To Produce - -1. The boundary between PBS-facing and artifact-facing diagnostics. -2. The minimum source-mapping obligation for backend failures. -3. Whether verifier/load failures participate in `11` directly. -4. The input contract `13` may assert for these classes. - -## Candidate Decisions - -### 1. Only Source-Attributable Backend Failures Enter The PBS Diagnostics Contract - -Candidate direction: - -- if a backend failure is directly attributable to validly analyzed PBS source plus normative lowering rules, it remains part of the PBS-facing diagnostics contract, -- otherwise it is artifact-tool or implementation failure surface. - -Rationale: - -- This keeps PBS diagnostics user-facing rather than compiler-internal. - -### 2. Verifier And Loader Failures Enter `11` Only When Userland Actionability Exists - -Candidate direction: - -- malformed or unauthorized host-facing artifact usage attributable to source remains in scope, -- purely artifact-internal corruption or implementation bugs remain out of scope. - -Rationale: - -- This matches the current draft's narrow load-facing baseline. - -### 3. Source Mapping Is Useful But Minimal In v1 - -Candidate direction: - -- v1 requires a source-facing location when the failure is source-attributable, -- but does not yet require one standardized artifact offset map or source-map format. - -Rationale: - -- This keeps the contract implementable while leaving room for richer tooling later. - -### 4. Conformance Should Assert Only The Stable External Surface - -Candidate direction: - -- `13` may assert rejection phase, source attribution, and rejection class for backend-originated PBS diagnostics, -- but not one exact verifier or loader message format. - -Rationale: - -- This keeps conformance aligned with the rest of `11`. - -## Questions To Resolve In The Room - -1. Which lowering failures are legitimate user-facing diagnostics versus compiler bugs? -2. Do verifier failures need their own normative phase label, or map into linking/load-facing rejection? -3. Is one source location enough for backend-originated failures? -4. How much of artifact-facing tooling belongs in the PBS language contract at all? -5. What exactly must `13` be able to test once `12` and `15` are closed? - -## Expected Outputs - -This workshop should produce: - -1. a decision record for backend diagnostics boundaries, -2. a source-mapping obligations note, -3. and explicit integration tasks for `11`, `12`, `13`, and `15`. - -## Explicit Deferrals - -- exact source-map file formats, -- artifact UI presentation, -- implementation bug reporting policy, -- and internal compiler exception handling. - -## Inputs - -- `docs/pbs/specs/11. Diagnostics 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/11. Diagnostics Agenda.md` -- `docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md` -- `docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md` - diff --git a/docs/pbs/agendas/13. Conformance Test Agenda.md b/docs/pbs/agendas/13. Conformance Test Agenda.md deleted file mode 100644 index 96c8726f..00000000 --- a/docs/pbs/agendas/13. Conformance Test Agenda.md +++ /dev/null @@ -1,116 +0,0 @@ -# PBS Conformance Test Agenda - -Status: Active - -## Purpose - -Drive the decisions needed to turn `13. Conformance Test Specification.md` into an executable conformance contract for PBS v1. - -## Context - -The current conformance spec already defines a source-level baseline, but it still leaves open: - -- whether PBS has one conformance level or staged claims, -- how diagnostics participate in conformance, -- when artifact-level golden tests become mandatory, -- how fixtures for stdlib environments, host registries, and capability grants are modeled, -- and how compatibility promises are validated over time. - -This agenda should keep conformance practical and layered so the project can evolve from frontend tests to full-toolchain claims without ambiguity. - -## Decisions To Produce - -1. Decide the conformance-claim model: - one level only or staged levels such as frontend-only and full toolchain. -2. Decide the normative oracle shape for diagnostics. -3. Decide when artifact-level conformance becomes required in addition to source-level behavior. -4. Decide the minimum fixture model for stdlib, host registry, capabilities, and runtime lines. -5. Decide how compatibility and regression claims are encoded in the conformance corpus. - -## Core Questions - -1. Is a parser plus binder implementation allowed to claim partial conformance, and under what label? -2. Do diagnostics tests assert codes, phases, spans, wording classes, or only acceptance and rejection? -3. Which lowering and host-binding invariants require golden tests once `12` and `15` are closed? -4. What is the smallest reusable fixture set that still exercises host-backed and stdlib-backed surfaces honestly? -5. How should compatibility expectations across language, stdlib, and cartridge domains be tested over time? - -## Proposed Workshop Sequence - -### Workshop 1: Conformance Claim Levels - -Purpose: - -- decide whether PBS has one conformance level or staged claims. - -Expected decisions: - -- claim taxonomy, -- minimum requirements for each claim, -- and naming constraints for partial implementations. - -### Workshop 2: Source-Level Oracle and Diagnostic Oracle - -Purpose: - -- close what source-level behavior must be asserted, -- and decide how diagnostics enter conformance. - -Expected decisions: - -- positive versus negative suite boundaries, -- diagnostic oracle granularity, -- and minimum deterministic assertions. - -### Workshop 3: Artifact-Level Conformance and Fixtures - -Purpose: - -- decide when artifact-level tests become mandatory, -- and close the fixture model for stdlib, registry, capability, and runtime scenarios. - -Expected decisions: - -- artifact-golden boundary, -- fixture strategy, -- and environment assumptions for host-backed tests. - -### Workshop 4: Regression and Compatibility Matrices - -Purpose: - -- decide how already-published behavior claims are preserved and tested over time. - -Expected decisions: - -- regression corpus policy, -- compatibility-matrix expectations, -- and alignment with `17`. - -## Expected Spec Material - -The resulting spec work should be able to add or close sections for: - -- conformance levels or claim classes, -- required positive and negative suites, -- diagnostic oracle rules, -- artifact-level oracle rules, -- fixture model and environment assumptions, -- regression and compatibility matrices, -- and acceptance criteria for claiming PBS v1 support. - -## Non-Goals - -- Choosing one repository layout or test framework. -- Turning benchmarks into conformance. -- Replacing the normative specs with test precedent. -- Freezing every temporary implementation quirk as a golden artifact. - -## Inputs - -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/specs/19. Verification and Safety Checks Specification.md` diff --git a/docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md b/docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md deleted file mode 100644 index f71bee3d..00000000 --- a/docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md +++ /dev/null @@ -1,98 +0,0 @@ -# PBS Conformance Workshop 1 - -Status: Active - -## Purpose - -Run the first focused discussion for `13. Conformance Test Specification.md` on conformance claims: - -- whether PBS has one conformance level or multiple claim tiers, -- what each claim means, -- and how partial implementations must describe themselves. - -## Why This Slice First - -This slice should come first because every later conformance workshop depends on knowing what kind of claim the tests are intended to validate. - -## Proposed Meeting Order - -1. Reconfirm the current source-level conformance baseline. -2. Decide whether claim levels exist. -3. Decide minimum requirements for each allowed claim. -4. Decide naming restrictions for partial implementations. -5. Record oracle and fixture consequences for later workshops. - -## Decisions To Produce - -1. One-level versus staged conformance model. -2. Minimum obligations per conformance claim. -3. Naming policy for partial implementations. -4. The dependency from conformance claims into compatibility policy. - -## Candidate Decisions - -### 1. Allow Staged Claims - -Candidate direction: - -- permit staged claims such as: - frontend conformance, - source-runtime conformance, - and full toolchain conformance. - -Rationale: - -- This lets the project evolve honestly without pretending an unfinished backend is complete. - -Alternative to discuss: - -- keep only one conformance level to avoid user confusion. - -### 2. Each Claim Must Name What It Does Not Cover - -Candidate direction: - -- every partial claim must explicitly state excluded domains such as artifact emission, loader interaction, or verifier behavior. - -Rationale: - -- This prevents marketing-language ambiguity. - -### 3. Full PBS v1 Claim Requires The Whole Active Spec Set - -Candidate direction: - -- only the full claim may say “PBS v1 conforming” without qualifier, -- staged claims must remain explicitly qualified. - -Rationale: - -- This protects the meaning of the top-level claim. - -## Questions To Resolve In The Room - -1. Are multiple conformance levels helpful or too confusing? -2. What exact names should staged claims use? -3. Can a parser-plus-binder implementation claim anything beyond “frontend”? -4. Must runtime execution without artifact emission count as a distinct level? -5. How does this interact with `17` compatibility labels? - -## Expected Outputs - -1. a decision record for claim levels, -2. a claim taxonomy draft for `13`, -3. and follow-up requirements for `17`. - -## Explicit Deferrals For Workshop 2 - -- diagnostic oracle granularity, -- source-level suite structure, -- and artifact-level tests. - -## Inputs - -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/agendas/13. Conformance Test Agenda.md` -- `docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md` - diff --git a/docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md b/docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md deleted file mode 100644 index d9ffe8ea..00000000 --- a/docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md +++ /dev/null @@ -1,96 +0,0 @@ -# PBS Conformance Workshop 2 - -Status: Active - -## Purpose - -Run the second focused discussion for `13. Conformance Test Specification.md` on the source-level oracle: - -- positive and negative suites, -- runtime-oracle scope, -- and how diagnostics participate in conformance. - -## Why This Slice Second - -This slice follows claim levels because it defines the actual assertions needed for the frontend and source-runtime portions of conformance. - -## Proposed Meeting Order - -1. Reconfirm the claim taxonomy from Workshop 1. -2. Close the positive and negative source-level suite boundaries. -3. Close the source-level runtime oracle. -4. Close the diagnostic oracle granularity. -5. Record artifact and fixture dependencies for Workshop 3. - -## Decisions To Produce - -1. The exact source-level oracle categories. -2. The minimum diagnostic assertions conformance may check. -3. The distinction between acceptance/rejection tests and runtime-oracle tests. -4. The boundary between source-level conformance and artifact-level conformance. - -## Candidate Decisions - -### 1. Keep Source-Level Oracle As The Core Baseline - -Candidate direction: - -- conformance must at minimum assert parsing, rejection, binding, typing, dynamic semantics, and memory/identity behavior at source level. - -Rationale: - -- This matches the current maturity of the corpus. - -### 2. Diagnostic Oracle Checks Stable External Fields Only - -Candidate direction: - -- conformance may assert: - acceptance or rejection, - diagnostic phase, - source attribution, - and stable rejection class if adopted, -- but not exact message wording. - -Rationale: - -- This aligns `13` to the likely direction of `11`. - -### 3. Runtime Oracle Remains Language-Observable - -Candidate direction: - -- conformance asserts only language-observable outcomes at this stage, -- not implementation timing or internal GC behavior. - -Rationale: - -- This preserves portability across implementations. - -## Questions To Resolve In The Room - -1. Should diagnostic codes become part of the conformance oracle if `11` later adopts them? -2. Must source-level runtime tests be required for every claim level or only some? -3. How should trap behavior be asserted without over-specifying runtime internals? -4. Which negative tests belong to parsing versus static semantics versus linking? -5. How much source attribution detail is enough for conformance? - -## Expected Outputs - -1. a decision record for source-level oracle scope, -2. a decision record for diagnostics in conformance, -3. and suite-structure targets for `13`. - -## Explicit Deferrals For Workshop 3 - -- artifact goldens, -- stdlib and host fixtures, -- and runtime-line environment modeling. - -## Inputs - -- `docs/pbs/specs/11. Diagnostics Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md` -- `docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md` - diff --git a/docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md b/docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md deleted file mode 100644 index fb283569..00000000 --- a/docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md +++ /dev/null @@ -1,98 +0,0 @@ -# PBS Conformance Workshop 3 - -Status: Active - -## Purpose - -Run the third focused discussion for `13. Conformance Test Specification.md` on artifact-level testing and fixtures: - -- when artifact goldens become mandatory, -- which invariants are asserted, -- and how stdlib, host-registry, capability, and runtime fixtures are modeled. - -## Why This Slice Third - -This slice should come after the source-level oracle is stable and after lowering discussions have progressed enough to identify meaningful artifact obligations. - -## Proposed Meeting Order - -1. Reconfirm the claim taxonomy and source-level baseline. -2. Decide when artifact-level conformance becomes required. -3. Decide which artifact invariants are testable at conformance level. -4. Decide the minimum fixture model for stdlib and host-backed scenarios. -5. Record regression and compatibility consequences for Workshop 4. - -## Decisions To Produce - -1. The role of artifact-level conformance in PBS v1. -2. The minimum fixture model for reserved stdlib and host-backed scenarios. -3. The artifact oracle boundary between `13`, `12`, and `15`. -4. The runtime-line assumptions fixtures must encode. - -## Candidate Decisions - -### 1. Artifact-Level Conformance Belongs Only To Full Toolchain Claims - -Candidate direction: - -- frontend-only and source-runtime claims do not require artifact goldens, -- full toolchain claims do. - -Rationale: - -- This keeps staged conformance honest and tractable. - -### 2. Conformance Should Assert Invariants, Not One Entire Binary Snapshot - -Candidate direction: - -- artifact tests should assert stable invariants such as presence, dedup, ordering rules, and canonical identity mappings, -- not one complete opaque binary image unless later needed. - -Rationale: - -- This is more robust across legitimate implementation variation. - -### 3. Fixtures Must Model Real Resolved Environments - -Candidate direction: - -- conformance fixtures must explicitly model: - selected stdlib environment, - host registry line, - granted capabilities, - and runtime line where relevant. - -Rationale: - -- These affect observable acceptance and lowering behavior. - -## Questions To Resolve In The Room - -1. Does full conformance need binary goldens or only invariant checks? -2. What is the smallest honest fixture model for host-backed tests? -3. Should stdlib fixtures be versioned as part of the conformance corpus? -4. How much loader behavior must be simulated in conformance? -5. Which artifact guarantees are stable enough today to test? - -## Expected Outputs - -1. a decision record for artifact-level conformance scope, -2. a fixture model draft for `13`, -3. and integration tasks for `12`, `15`, and `17`. - -## Explicit Deferrals For Workshop 4 - -- regression policy over time, -- compatibility-matrix assertions, -- and published behavior preservation. - -## Inputs - -- `docs/pbs/specs/12. IR and Lowering Specification.md` -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/agendas/12.4. IR and Lowering Workshop 4 - Builtins, Host Bindings, and Artifact Invariants.md` -- `docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md` - diff --git a/docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.md b/docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.md deleted file mode 100644 index 9a808234..00000000 --- a/docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.md +++ /dev/null @@ -1,100 +0,0 @@ -# PBS Conformance Workshop 4 - -Status: Active - -## Purpose - -Run the fourth focused discussion for `13. Conformance Test Specification.md` on long-lived behavior preservation: - -- regression corpus policy, -- compatibility matrices, -- and how published claims are tested over time. - -## Why This Slice Last - -This slice should come last because it depends on: - -- claim taxonomy, -- source-level oracle, -- artifact-level scope, -- and compatibility policy direction. - -## Proposed Meeting Order - -1. Reconfirm the settled claim levels and oracle shapes. -2. Decide what becomes part of the regression corpus. -3. Decide how compatibility matrices are represented in tests. -4. Decide how already-published behavior claims are preserved. -5. Record final spec-integration tasks for `13` and `17`. - -## Decisions To Produce - -1. Regression corpus policy. -2. Compatibility-matrix testing policy. -3. The relationship between published claims and test obligations. -4. How partial claims and full claims age over time. - -## Candidate Decisions - -### 1. Published Behavior Claims Must Enter A Regression Corpus - -Candidate direction: - -- once behavior is claimed as conforming or supported, it should become regression-protected in the corpus appropriate to that claim level. - -Rationale: - -- This turns compatibility promises into executable checks. - -### 2. Compatibility Matrices Should Be Testable, Not Only Documented - -Candidate direction: - -- the matrix across language line, - stdlib line, - runtime line, - and conformance claim -must have test-backed meaning where support is promised. - -Rationale: - -- This prevents compatibility tables from becoming marketing-only artifacts. - -### 3. Retired Claims Must Be Explicitly Removed, Not Silently Forgotten - -Candidate direction: - -- when support is dropped, the corresponding claim and tests must be retired deliberately with migration or policy notes. - -Rationale: - -- This aligns conformance with compatibility governance. - -## Questions To Resolve In The Room - -1. What exactly enters the regression corpus: only bugs, or every published example and decision? -2. How granular should compatibility matrices be? -3. Can staged claims have separate regression corpora? -4. How are unsupported combinations represented in tests? -5. Which parts of this belong in `13` versus `17`? - -## Expected Outputs - -1. a decision record for regression policy, -2. a decision record for compatibility-matrix testing, -3. and a final alignment checklist between `13` and `17`. - -## Explicit Deferrals - -- release tooling implementation, -- repository layout for the test corpus, -- and changelog formatting. - -## Inputs - -- `docs/pbs/specs/13. Conformance Test Specification.md` -- `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md` -- `docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md` -- `docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.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 index 62307af9..7abd1a17 100644 --- 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 @@ -93,6 +93,5 @@ Rationale: - `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/13.1. Conformance Workshop 1 - Conformance Claim Levels.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.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 index 8a5e74e7..5c70ee01 100644 --- 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 @@ -1,6 +1,6 @@ # PBS Compatibility Workshop 3 -Status: Active +Status: Decision recorded ## Purpose @@ -11,6 +11,17 @@ Run the third focused discussion for `17. Compatibility and Evolution Policy.md` - 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. @@ -91,7 +102,6 @@ Rationale: - `docs/pbs/specs/13. Conformance Test Specification.md` - `docs/pbs/specs/17. Compatibility and Evolution Policy.md` -- `docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.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/decisions/Allocation and Cost Visibility Decision.md b/docs/pbs/decisions/Allocation and Cost Visibility Decision.md index 233654d8..9f014ee1 100644 --- a/docs/pbs/decisions/Allocation and Cost Visibility Decision.md +++ b/docs/pbs/decisions/Allocation and Cost Visibility Decision.md @@ -1,6 +1,6 @@ # Allocation and Cost Visibility Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial allocation-and-cost closure pass ## 1. Context 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 new file mode 100644 index 00000000..dd273242 --- /dev/null +++ b/docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md @@ -0,0 +1,133 @@ +# Artifact-Level Conformance and Fixture Model Decision + +Status: Superseded +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) + +Superseded on: 2026-03-04 + +## 1. Context + +PBS v1 needed a decision for the point where conformance stops being source-only and begins asserting artifact-facing behavior. + +The open questions from the conformance agenda closure pass and Workshop 3 were: + +- whether artifact-level conformance is mandatory for every claim or only for full toolchain claims, +- whether conformance should snapshot whole binaries or only stable invariants, +- what the smallest honest fixture model is for stdlib and host-backed scenarios, +- and how `13`, `12`, `15`, and `19` divide responsibility. + +The adopted direction needed to keep full conformance meaningful without freezing one emitter layout, one repository structure, or one implementation-specific binary image. + +## 2. Decision + +PBS v1 adopts the following artifact-level conformance baseline: + +1. Artifact-level conformance belongs only to `full toolchain conformance`. +2. `frontend conformance` and `source-runtime conformance` do not require artifact-level oracle checks. +3. Full toolchain conformance must assert stable artifact invariants rather than one opaque byte-for-byte binary snapshot. +4. The conformance fixture model must explicitly declare the resolved environment assumptions that affect observable admission or lowering behavior. +5. `12` defines what semantic and artifact-boundary facts lowering must preserve. +6. `15` defines how the conformance-facing artifact facts appear in PBX/bytecode-visible form. +7. `19` defines which later safety and validation obligations are checked by loader and verifier rather than by lowering itself. + +## 3. Artifact-Level Oracle Baseline + +The v1 artifact-level oracle is invariant-based. + +Full toolchain conformance must be able to assert, at minimum: + +1. required canonical host-binding declarations are emitted for admitted host-backed uses; +2. `SYSC` entries are deduplicated by canonical identity; +3. `SYSC` entry order follows first occurrence in the lowered program; +4. host-backed callsites are emitted in pre-load form as `HOSTCALL ` referencing the emitted canonical binding set; +5. VM-owned builtin projections, builtin constants, and intrinsic callsites do not leak into host-binding metadata such as `SYSC`; +6. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves; +7. emitted artifacts preserve at least one source-attribution hook for backend failures that remain source-attributable and user-actionable under the diagnostics contract. + +This baseline does not require: + +- one full PBX binary snapshot, +- one exact section byte layout outside the stable invariants above, +- one exact source-map format, +- or one verifier-internal trace shape. + +## 4. Fixture Model + +Conformance fixtures must model the resolved environment honestly whenever the selected environment affects acceptance, lowering, or artifact meaning. + +Every fixture that depends on environment selection must declare, as applicable: + +- selected stdlib environment or reserved stdlib line, +- selected host registry line, +- granted capability set, +- and selected runtime line. + +If an axis is irrelevant for a fixture, the fixture should declare that explicitly rather than leaving it implicit. + +The minimum reusable fixture families for v1 are: + +1. source-only fixtures whose expectations do not depend on host registry or runtime selection; +2. stdlib-resolved fixtures that name the selected stdlib environment when reserved modules affect acceptance or behavior; +3. host-admitted fixtures that name both host registry line and granted capabilities for positive host-backed cases; +4. host-rejected fixtures that name the missing or unauthorized capability or host-registry condition for deterministic negative cases; +5. full-toolchain artifact fixtures that name the runtime line whenever emitted intrinsic or host-binding form depends on the selected executable target line. + +This model is intentionally small. It is sufficient to prevent fake portability claims while avoiding one mandatory repository layout. + +## 5. Boundary Across `13`, `12`, `15`, and `19` + +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; +- `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. + +Conformance therefore does not require `12` to define one binary encoding and does not require `15` to redefine semantic ownership already fixed in `12`. + +## 6. Invariants + +- Artifact-level conformance is required only for the full toolchain claim. +- The v1 artifact oracle is invariant-based, not whole-image-based. +- Fixture assumptions that change observable behavior must be explicit. +- Host-binding metadata remains distinct from VM-owned builtin and intrinsic lowering. +- The boundary among lowering, encoding, and verification must remain reviewable and non-overlapping. +- Source-attributable backend failures must retain at least one recoverable source location, but richer debug surfaces remain optional. + +## 7. Explicit Non-Decisions + +This decision record does not yet close: + +- which PBX sections beyond the current stable invariant baseline become part of the PBS-facing contract, +- whether intrinsic declarations require an additional dedicated PBX preload section in v1, +- the full verifier test surface for conformance, +- the compatibility-matrix policy for aging and retirement of published combinations, +- or one repository structure for the conformance corpus. + +## 8. Spec Impact + +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` + +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/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` + +## 9. Validation Notes + +The intended operational reading is: + +- a direct interpreter may still claim `source-runtime conformance` without artifact checks, +- a full compiler toolchain must expose enough artifact surface to prove the stable invariants above, +- and a host-backed test is not valid conformance evidence unless the selected registry, capability set, and runtime assumptions are declared where they affect the outcome. diff --git a/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md b/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md new file mode 100644 index 00000000..8218b758 --- /dev/null +++ b/docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md @@ -0,0 +1,164 @@ +# Compatibility Matrix and Published Claims Decision + +Status: Superseded +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) + +Superseded on: 2026-03-04 + +## 1. Context + +PBS v1 needed one operational policy for how support claims are published, tested, aged, and retired over time. + +The open questions from the conformance closure pass, especially Workshop 4, and from `17. Compatibility and Evolution Policy Agenda.md`, Workshop 3 were: + +- what enters the regression corpus, +- which compatibility dimensions PBS must publish explicitly, +- what counts as a published support claim, +- how claims relate to conformance evidence, +- and how supported combinations retire without becoming ambiguous. + +The adopted direction needed to ensure that compatibility tables and support statements are executable commitments rather than prose-only promises. + +## 2. Decision + +PBS v1 adopts the following baseline policy: + +1. Published support claims must be represented by an explicit compatibility matrix. +2. Every published supported combination must be backed by maintained conformance or regression evidence appropriate to the claim level being published. +3. The regression corpus is not limited to bug reproductions; it also includes already-published normative examples, accepted behavior claims, and supported matrix combinations. +4. Unsupported combinations must be stated explicitly rather than inferred from silence. +5. Claim retirement must be deliberate: when support narrows or ends, the matrix entry, supporting tests, and migration/support note must all change together. + +## 3. Compatibility Matrix Baseline + +The minimum PBS compatibility matrix must expose, at minimum, the following dimensions where support is published: + +1. language line, +2. stdlib line when reserved stdlib environment selection affects the claim, +3. runtime line when execution target selection affects the claim, +4. conformance claim level. + +The matrix must also expose an explicit support state for each published combination. + +The minimum support states are: + +- `supported` +- `unsupported` +- `provisional` + +Meanings: + +- `supported` means the combination is promised by the publisher and backed by maintained evidence. +- `unsupported` means the combination is intentionally not promised and tools may reject or decline it without violating the published support policy. +- `provisional` means the combination is published as incomplete or experimental and must not be confused with ordinary stable support. + +Silence must not be used where a published matrix exists and a reasonable reader could infer support. + +## 4. Published Claims and Evidence + +A published support claim exists whenever a publisher represents, in user-facing or tool-facing form, that a combination or behavior is supported, conforming, or maintained. + +This includes, at minimum: + +- a matrix entry marked `supported`, +- an unqualified or qualified PBS conformance claim, +- compatibility statements in product or release documentation, +- and published examples or fixtures presented as normative or supported behavior. + +Every published claim must map to maintained executable evidence. + +The evidence may be: + +- conformance tests, +- regression tests, +- or both, + +provided the evidence covers the claim scope actually being published. + +`frontend conformance`, `source-runtime conformance`, and `full toolchain conformance` may therefore have different evidence sets, but each published claim still needs evidence inside its own scope. + +## 5. Regression Corpus Policy + +The regression corpus must preserve already-published behavior inside the scope of active support claims. + +At minimum, the regression corpus must include: + +1. bug reproductions for behavior that was fixed and remains within a supported scope; +2. published examples that are treated as normative or supported behavior; +3. accepted conformance claims and the behavior they promise; +4. supported compatibility-matrix combinations and their required outcomes. + +The regression corpus may be organized into separate slices by claim level or domain. + +What matters normatively is: + +- published supported behavior is regression-protected, +- evidence remains attributable to the claim it protects, +- and narrowing support requires deliberate retirement rather than silent drift. + +## 6. Retirement and Narrowing Policy + +When a supported combination is retired or narrowed: + +1. the matrix entry must change explicitly; +2. the old support state must not remain implied by stale documentation; +3. the corresponding evidence must be retired, reclassified, or moved to a historical/non-supporting corpus deliberately; +4. a migration, support-boundary, or rationale note must accompany the change when users could reasonably depend on the retired combination. + +Retirement does not require one universal changelog format in this decision. + +It does require that the support boundary become visible and reviewable. + +## 7. Boundary Between `13` and `17` + +The adopted split is: + +- `13. Conformance Test Specification.md` defines the executable evidence obligations: what must enter the conformance or regression corpus and how supported claims become test-backed; +- `17. Compatibility and Evolution Policy.md` defines the publication policy: which matrix dimensions and support states are required and how supported combinations age or retire. + +This keeps `13` test-oriented and `17` promise-oriented while ensuring both documents describe the same support contract. + +## 8. Invariants + +- Published support claims must be test-backed. +- A compatibility matrix is normative only when its states have executable meaning. +- `unsupported` must be explicit when omission would mislead users. +- `provisional` must not be mistaken for ordinary supported compatibility. +- Regression protection follows published supported behavior, not only bug history. +- Narrowing support is a deliberate policy act, not an accidental omission. + +## 9. Explicit Non-Decisions + +This decision record does not yet close: + +- exact compatibility-window lengths by domain, +- exact migration-tooling triggers, +- PBX-specific binary compatibility policy, +- release tooling implementation, +- or one repository layout for matrix and regression data. + +## 10. Spec Impact + +This decision should feed at least: + +- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/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/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md` + +## 11. Validation Notes + +The intended operational reading is: + +- if a publisher marks one matrix row as `supported`, there must be maintained evidence for that row; +- if a combination is no longer supported, the matrix must say so explicitly rather than simply dropping mention of it; +- and if an example or claim is published as supported behavior, it belongs in the regression story even if it did not originate as a bug report. diff --git a/docs/pbs/decisions/Conformance Claim Levels Decision.md b/docs/pbs/decisions/Conformance Claim Levels Decision.md new file mode 100644 index 00000000..4139d4dd --- /dev/null +++ b/docs/pbs/decisions/Conformance Claim Levels Decision.md @@ -0,0 +1,167 @@ +# Conformance Claim Levels Decision + +Status: Superseded +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) + +Superseded on: 2026-03-04 + +## 1. Context + +PBS v1 needed a conformance-claim model that stays honest while the conformance corpus matures across frontend, runtime, and artifact-facing work. + +The open questions from the conformance agenda closure pass and Workshop 1 were: + +- whether PBS should use one conformance label or staged claims, +- what a partial implementation is allowed to claim, +- how published conformance claims must describe missing coverage, +- and how claim levels constrain later compatibility policy. + +The adopted direction needed to avoid two failure modes: + +- pretending an unfinished backend is already full PBS v1 conformance, +- and allowing vague marketing language that hides excluded domains such as artifact emission or verifier behavior. + +## 2. Decision + +PBS v1 adopts staged conformance claims. + +The canonical claim levels are: + +1. `frontend conformance` +2. `source-runtime conformance` +3. `full toolchain conformance` + +These claims mean: + +1. `frontend conformance` covers deterministic source acceptance and rejection behavior through parsing, manifest/import resolution, linking/static semantics, and the stable diagnostics surface required for those rejection tests. +2. `source-runtime conformance` covers all frontend obligations plus source-level runtime, memory/identity, and host-boundary behavior already defined as language-observable in the active specs. +3. `full toolchain conformance` covers all source-runtime obligations plus the artifact-facing, loader-facing, verifier-facing, and compatibility obligations required by the full active PBS v1 spec set. + +Only `full toolchain conformance` may be published without qualifier as `PBS v1 conforming`. + +Any narrower claim must remain explicitly qualified in published wording, for example: + +- `PBS v1 frontend conforming` +- `PBS v1 source-runtime conforming` + +An implementation that does not satisfy one complete canonical level must not claim PBS conformance merely because it implements a subset such as parsing-only or parser-plus-binder behavior. + +Any partial claim must explicitly state excluded domains when they matter to user expectations, including as applicable: + +- artifact emission, +- loader interaction, +- verifier behavior, +- supported runtime line, +- selected stdlib environment, +- host-registry line, +- and capability assumptions. + +The unqualified claim `PBS v1 conforming` is reserved until the artifact-facing conformance surface is fully closed in `13`, `12`, `15`, and `19`. + +## 3. Claim Meanings + +### 3.1 Frontend Conformance + +`frontend conformance` is the minimum canonical PBS conformance claim. + +It requires: + +- deterministic parsing behavior, +- deterministic source rejection for in-scope syntax, linking, and static-semantics failures, +- deterministic manifest/import resolution outcomes, +- regression protection for already-published behavior inside that claim scope, +- and the stable diagnostics fields required by the diagnostics contract for those failures. + +It does not imply: + +- runtime execution support, +- host-backed call execution, +- artifact emission, +- loader integration, +- or verifier integration. + +### 3.2 Source-Runtime Conformance + +`source-runtime conformance` extends `frontend conformance`. + +It additionally requires: + +- source-level runtime oracle coverage, +- source-level memory and identity oracle coverage, +- host-boundary behavior already fixed by the Host ABI and capability specs at source-visible level, +- and regression protection for already-published behavior inside that claim scope. + +It does not by itself imply: + +- one normative PBX image shape, +- one artifact-level golden contract, +- loader patching behavior beyond source-visible requirements, +- or verifier-surface conformance. + +### 3.3 Full Toolchain Conformance + +`full toolchain conformance` is the top-level PBS v1 conformance claim. + +It requires: + +- all `source-runtime conformance` obligations, +- all artifact-level oracle requirements once closed, +- loader/verifier-facing acceptance and rejection obligations that belong to PBS-facing conformance, +- required fixture modeling for stdlib, registry, capability, and runtime lines, +- and maintained regression/compatibility evidence for every published supported combination inside the claim. + +Until those artifact-facing obligations are normatively closed, implementations may publish only the narrower qualified claims above. + +## 4. Naming and Publication Rules + +- If the word `conforming` is used in a PBS v1 product claim, it must use one of the canonical claim levels. +- The bare wording `PBS v1 conforming` is reserved for the full toolchain claim only. +- `frontend` and `source-runtime` claims must keep the qualifier adjacent to the published claim and must not be shortened to imply full PBS v1 conformance. +- If an implementation is still below `frontend conformance`, it should describe itself as partial, experimental, or implementation-specific rather than conforming. +- Published conformance claims must state the tested scope when environment selection changes observable behavior. + +## 5. Invariants + +- PBS conformance is staged, not all-or-nothing, during the v1 maturation path. +- The meaning of the unqualified top-level claim must remain stronger than any partial claim. +- Partial claims must not hide excluded domains behind vague wording. +- Conformance claims and compatibility claims are related but not identical; compatibility policy may refine promise strength per claim level without redefining the claim levels themselves. +- Published claims must be backed by executable evidence in the conformance or regression corpus appropriate to that claim level. + +## 6. Explicit Non-Decisions + +This decision record does not yet close: + +- the full fixture model for stdlib, host-registry, capability, and runtime-line scenarios, +- the final artifact-level oracle for PBX or lowering invariants, +- the compatibility-matrix dimensions and retirement policy, +- or the exact repository layout of the conformance corpus. + +## 7. Spec Impact + +This decision should feed at least: + +- `docs/pbs/specs/13. Conformance Test Specification.md` +- `docs/pbs/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/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` + +## 8. Validation Notes + +The intended operational reading is: + +- a parser-plus-binder implementation may claim `frontend conformance` only if it actually satisfies the complete frontend obligations, including deterministic rejection behavior and the stable diagnostics surface in scope, +- an interpreter or direct-execution implementation may claim `source-runtime conformance` without yet claiming artifact or verifier conformance, +- and no implementation should imply full PBS v1 conformance until the artifact-facing contract is normatively testable. diff --git a/docs/pbs/decisions/Diagnostics Contract Decision.md b/docs/pbs/decisions/Diagnostics Contract Decision.md new file mode 100644 index 00000000..3580da26 --- /dev/null +++ b/docs/pbs/decisions/Diagnostics Contract Decision.md @@ -0,0 +1,215 @@ +# Diagnostics Contract Decision + +Status: Accepted (Implemented) +Cycle: Diagnostics agenda closure pass + +## 1. Context + +PBS v1 needed one coherent diagnostics contract that closes the open questions from the diagnostics agenda: + +- diagnostic identity, +- attribution and cross-file reporting, +- wording and localization boundaries, +- warning and cost-diagnostics policy, +- and the boundary between PBS-facing diagnostics and backend/artifact-facing failures. + +The adopted direction needed to stay deterministic and conformance-friendly without freezing one editor UX, one compiler architecture, or one backend-internal reporting format. + +## 2. Decision + +PBS v1 adopts the following diagnostics baseline: + +1. Every PBS-facing diagnostic has a mandatory `diagnostic code`. +2. Every PBS-facing diagnostic has a mandatory `severity`. +3. The stable external diagnostic phases include: + - `syntax`, + - `static semantics`, + - `manifest/import resolution`, + - `linking`, + - `host-binding/capability admission`, + - and load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage. +4. `linking` is a first-class diagnostics phase and should remain visible to users as part of the didactic pipeline. +5. The minimum source-facing payload is: + - `diagnostic code`, + - `severity`, + - `phase`, + - `primary file`, + - `primary span/location`, + - and a human-readable message. +6. The diagnostics model must also carry a stable `message template id` with stable named placeholders for localized rendering. +7. Human wording is not byte-for-byte normative. The normative contract is the stable association among diagnostic code, message template id, placeholders, and rejection meaning. +8. Implementations may localize rendered messages by language, provided the rendered message preserves the same normative rejection meaning. +9. For future interoperability-oriented transports such as a possible LSP integration, implementations should preserve the ability to render an English default/fallback message even when a product renders another locale locally. +10. In cross-file failures, the primary site must be the source location where the user action triggered the failure. +11. `notes` and `related sites` are optional by default. +12. For `duplicate` and `conflict` classes, at least one related site is mandatory. +13. `hint` is a reserved diagnostics category in v1, but hint content is not mandatory. +14. `help` and guided remediation are outside the core conformance contract in v1. +15. Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline. +16. Qualitative cost facts may be surfaced as warnings or notes, especially for: + - retention-bearing `bind`, + - host-boundary crossings, + - and observable copy-versus-alias behavior. +17. Quantitative reporting such as byte counts, allocation counts, and performance ranking is outside the diagnostics contract and belongs to profiling/tooling. +18. Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract. +19. Pure artifact corruption, verifier internals, loader internals, and compiler implementation bugs remain outside the PBS-facing diagnostics contract unless they are directly attributable to validly analyzed PBS source or to malformed/unauthorized PBS-facing artifact usage already in scope. +20. When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format. + +## 3. Diagnostic Identity and Payload + +The minimum stable identity of a PBS-facing diagnostic is not free-form wording. + +The stable identity is carried by: + +- `diagnostic code`, +- stable phase attribution, +- and the rejection class semantics represented by the code/template pair. + +The minimum externally relevant fields are: + +- `diagnostic code`, +- `severity`, +- `phase`, +- `primary file`, +- `primary span/location`, +- `message template id`, +- stable named placeholders, +- and a rendered human-readable message. + +This baseline keeps diagnostics testable and localizable without forcing one exact byte-for-byte phrasing. + +## 4. Cross-File Attribution + +Cross-file attribution follows an action-first rule. + +Rules: + +- import failures point primarily to the importing site, +- barrel failures point primarily to the barrel entry or reference site that triggered the failure, +- linking or cross-module lookup failures point primarily to the use or reference site that could not be resolved, +- related sites may be attached when known, +- and `duplicate` or `conflict` diagnostics must include at least one related site in addition to the primary site. + +This keeps diagnostics actionable for users and stable enough for conformance. + +## 5. Message Rendering and Localization + +PBS v1 permits localized diagnostics, including localized editor-first experiences. + +The normative boundary is: + +- codes are stable, +- template ids are stable, +- placeholders are stable, +- and rendered wording may vary by locale and product surface. + +Examples in specs should therefore be treated as illustrative unless a spec explicitly marks a template shape or placeholder contract as normative. + +## 6. Categories, Notes, and Hints + +The stable visible categories currently reserved are: + +- `error`, +- `warning`, +- `note`, +- `hint`. + +`notes` are optional by default in v1. + +`hint` exists in the diagnostics model from v1 onward so implementations can grow into educational guidance without changing the core schema. + +This decision does not require one exact distinction between short hints and richer remediation flows. + +## 7. Warning and Cost-Diagnostics Boundary + +PBS v1 deliberately keeps warnings out of the minimum conformance baseline. + +This means: + +- implementations may emit warnings, +- the editor can use warnings aggressively for pedagogy, +- but conformance does not currently fail merely because an implementation omits optional warnings. + +The diagnostics contract does recognize the importance of qualitative cost facts already fixed elsewhere, but it does not promote them to mandatory warnings in v1. + +## 8. Backend-Originated Failure Boundary + +PBS-facing diagnostics stop where failures stop being source-attributable and user-actionable. + +In scope for PBS-facing diagnostics: + +- lowering failures that reflect a normative source-facing lowering rule or impossibility, +- verifier or loader rejections that are directly attributable to malformed or unauthorized PBS-facing artifact usage, +- and backend-originated failures that can still be mapped back to source in a way the user can act on. + +Out of scope for PBS-facing diagnostics: + +- internal compiler exceptions, +- implementation bugs, +- artifact corruption not attributable to valid PBS source or to in-scope malformed/unauthorized artifact usage, +- and backend-internal failure surfaces with no stable user-facing source attribution. + +## 9. Conformance Boundary + +The conformance surface for diagnostics should check only stable external fields. + +Conformance may assert: + +- rejection versus acceptance, +- diagnostic code, +- severity/category when in scope, +- phase, +- source attribution, +- and related-site requirements for narrow classes such as `duplicate` or `conflict`. + +Conformance should not require: + +- one exact rendered message, +- one exact localized wording, +- one exact note shape outside explicitly required classes, +- one verifier/loader internal format, +- or one profiling/reporting style. + +Warnings remain outside pass/fail conformance in v1, though any emitted warning must remain semantically compatible with the spec. + +## 10. Invariants + +- The diagnostics contract must remain deterministic across conforming implementations. +- Diagnostic identity must not depend on one locale or one exact rendered sentence. +- `linking` remains a visible diagnostics phase rather than being collapsed away into a generic resolution bucket. +- Cross-file diagnostics must remain action-oriented from the user's point of view. +- Localized rendering must not erase the stable machine-readable identity of a diagnostic. +- The contract must stay narrow enough that more than one toolchain can implement it. +- Backend-internal reporting must not leak into the PBS language contract unless the failure is source-attributable and user-actionable. + +## 11. Explicit Non-Decisions + +This decision record does not yet close: + +- the full warning catalog for future versions, +- whether a future version promotes a subset of warnings into mandatory conformance, +- exact remediation/help-content policy, +- exact source-map or artifact-offset formats, +- verifier trace schemas, +- transport-specific LSP field mapping, +- or internal compiler bug-reporting policy. + +## 12. Spec Impact + +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` + +## 13. Validation Notes + +The intended operational reading is: + +- diagnostics are machine-identifiable first and human-rendered second, +- localized editor UX is fully compatible with the contract, +- a future interoperable transport can still fall back to English rendering, +- warnings are available for pedagogy without being required for conformance, +- and backend-originated failures only enter the PBS-facing contract when they still behave like actionable source diagnostics rather than internal tool failures. diff --git a/docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md b/docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md index 467d4797..02eeca7b 100644 --- a/docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md +++ b/docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md @@ -1,6 +1,6 @@ # Dynamic Semantics - Branch Selection Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial branch-selection closure pass ## 1. Context diff --git a/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md b/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md index fff867da..296eeb09 100644 --- a/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md +++ b/docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md @@ -1,6 +1,6 @@ # Dynamic Semantics - Effect Surfaces Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial effect-surfaces closure pass ## 1. Context diff --git a/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md b/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md index c03e872c..56acd549 100644 --- a/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md +++ b/docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md @@ -1,6 +1,6 @@ # Dynamic Semantics - Execution Model Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial execution-model closure pass ## 1. Context diff --git a/docs/pbs/decisions/GC and Reachability Decision.md b/docs/pbs/decisions/GC and Reachability Decision.md index 2419a57c..b65e6290 100644 --- a/docs/pbs/decisions/GC and Reachability Decision.md +++ b/docs/pbs/decisions/GC and Reachability Decision.md @@ -1,6 +1,6 @@ # GC and Reachability Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial GC-and-reachability closure pass ## 1. Context diff --git a/docs/pbs/decisions/Host Memory Boundary Decision.md b/docs/pbs/decisions/Host Memory Boundary Decision.md index 114bd698..774f8944 100644 --- a/docs/pbs/decisions/Host Memory Boundary Decision.md +++ b/docs/pbs/decisions/Host Memory Boundary Decision.md @@ -1,6 +1,6 @@ # Host Memory Boundary Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial host-boundary closure pass ## 1. Context 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 3c65a614..40a2bd74 100644 --- a/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md +++ b/docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md @@ -1,6 +1,6 @@ # Lifetime Control and Future Profiles Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial lifetime-control policy closure pass ## 1. Context 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 e7e54654..8bfc90c9 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 @@ -1,6 +1,6 @@ # Name Resolution - Builtin Shells and Host Owners Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial name-resolution closure pass ## 1. Context 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 a20ee11d..4dc9724c 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 @@ -1,6 +1,6 @@ # Name Resolution - Callable Sets and Cross-Module Linking Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial name-resolution closure pass ## 1. Context 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 dabc2cb1..abec82f3 100644 --- a/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md +++ b/docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md @@ -1,6 +1,6 @@ # Name Resolution - Linking Phase Boundary Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial name-resolution closure pass ## 1. Context 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 556392e3..3690f0df 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 @@ -1,6 +1,6 @@ # Name Resolution - Scope, Lookup, and Imports Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial name-resolution closure pass ## 1. Context diff --git a/docs/pbs/decisions/Value Representation and Identity Decision.md b/docs/pbs/decisions/Value Representation and Identity Decision.md index 12553841..78eaf5ca 100644 --- a/docs/pbs/decisions/Value Representation and Identity Decision.md +++ b/docs/pbs/decisions/Value Representation and Identity Decision.md @@ -1,6 +1,6 @@ # Value Representation and Identity Decision -Status: Accepted +Status: Accepted (Implemented) Cycle: Initial value-representation closure pass ## 1. Context diff --git a/docs/pbs/specs/11. Diagnostics Specification.md b/docs/pbs/specs/11. Diagnostics Specification.md index 5eb72902..14754925 100644 --- a/docs/pbs/specs/11. Diagnostics Specification.md +++ b/docs/pbs/specs/11. Diagnostics Specification.md @@ -1,34 +1,38 @@ # PBS Diagnostics Specification -Status: Draft v1 (Temporary) -Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, and load-facing validation surfaces +Status: Draft v1 +Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, linking, host-admission checks, and load-facing validation surfaces ## 1. Purpose -This document defines the current PBS diagnostics baseline for v1. +This document defines the PBS diagnostics baseline for v1. Its purpose is to make diagnostics stable enough that: - conforming tools report failures in the same phases, - users receive deterministic and actionable source-facing feedback, +- diagnostics remain machine-identifiable even when rendered in different locales, - conformance can validate rejection class and attribution, -- and frontend, manifest, and load-facing validation remain aligned. +- and frontend, linking, manifest, and load-facing validation remain aligned. ## 2. Scope This document defines: -- the current required diagnostic phases, -- the minimum source-facing attribution baseline, -- the relationship between higher-precedence rejection rules and diagnostics, -- and the current limits of v1 diagnostics while lowering and artifact-facing specs remain incomplete. +- the required external diagnostic phases, +- the minimum machine-readable identity of a PBS-facing diagnostic, +- the minimum source-facing payload and attribution baseline, +- the boundary between normative diagnostic fields and implementation-defined rendering, +- the boundary between PBS-facing diagnostics and artifact/tooling failures, +- and the warning/cost-diagnostics boundary for v1. This document does not define: - a full runtime trap catalog, - UI presentation or IDE styling, -- one localization strategy, -- one diagnostics-code namespace, +- one exact localized sentence for every diagnostic, +- one transport-specific schema such as LSP field mapping, +- one standardized source-map or artifact-offset format, - or profiling/reporting formats. ## 3. Authority and Precedence @@ -59,12 +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` - -Later expansion of this document will also depend on: - - `12. IR and Lowering 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` ## 5. Already-Settled Inputs @@ -80,80 +85,147 @@ The following inputs are already fixed elsewhere and must not be contradicted he ## 6. Required Diagnostic Phases -At the current v1 baseline, PBS-facing tooling must distinguish at least the following diagnostic phases: +PBS-facing tooling must distinguish at least the following external diagnostic phases: -1. syntax, -2. static semantics, -3. manifest and import resolution, -4. host-binding and capability admission, -5. load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage. +1. `syntax`, +2. `static semantics`, +3. `manifest/import resolution`, +4. `linking`, +5. `host-binding/capability admission`, +6. `load-facing rejection` when directly attributable to malformed or unauthorized PBS-facing artifact usage. -This document does not yet require a finer-grained normative phase split for lowering, verifier, or artifact diagnostics. That remains open until the corresponding backend-facing specs are closed. +`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket. -## 7. Minimum Diagnostic Attribution +This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here. -For every required source-facing rejection that is attributable to source text, tooling must provide diagnostics with at least: +## 7. Required Diagnostic Identity, Payload, and Attribution -1. deterministic phase attribution, -2. primary file attribution, -3. a useful primary source span or location, -4. and enough human-readable content to distinguish the rejection class. +Every PBS-facing diagnostic must expose a stable machine-readable identity. -This document does not yet require one normalized diagnostics-code system or one fixed human wording template. +At minimum, every required source-facing diagnostic must include: -## 8. Required Diagnostic Coverage +1. `diagnostic code`, +2. `severity`, +3. `phase`, +4. `primary file`, +5. `primary span/location`, +6. `message template id`, +7. stable named placeholders for that template when applicable, +8. and a rendered human-readable message. -At minimum, the current diagnostics baseline must cover: +The stable identity of a diagnostic is carried primarily by: + +- `diagnostic code`, +- stable phase attribution, +- and the rejection-class semantics represented by the code/template pair. + +Human wording alone is not the identity of the diagnostic. + +## 8. Cross-File Attribution, Notes, and Hint Surface + +Cross-file attribution follows an action-first rule. + +Rules: + +- import failures must point primarily to the importing site, +- barrel failures must point primarily to the barrel site or entry that triggered the failure, +- linking and cross-module lookup failures must point primarily to the use or reference site that could not be resolved, +- related sites may be attached when known, +- and `duplicate` or `conflict` diagnostics must include at least one related site. + +`notes` are optional by default in v1 except where another rule explicitly requires related-location reporting. + +The stable visible categories currently reserved are: + +- `error`, +- `warning`, +- `note`, +- `hint`. + +`hint` is part of the diagnostics model in v1, but hint content is not mandatory. + +## 9. Wording, Templates, and Localization + +Rendered wording does not need to be byte-for-byte identical across implementations or locales. + +However: + +- the rendered message must preserve the same normative rejection meaning, +- the rendered message must not contradict the governing spec rule, +- and the code/template/placeholder contract must remain stable. + +This allows implementations to localize diagnostics while preserving conformance-friendly identity. + +Implementations should preserve the ability to render an English default or fallback message for future interoperability-oriented transports such as a possible LSP integration, even when the local product surface renders another language by default. + +Examples in this specification are illustrative unless explicitly marked normative. + +`help` or guided remediation is outside the minimum mandatory contract in v1. + +## 10. Required Diagnostic Coverage and Backend-Originated Failures + +At minimum, the PBS diagnostics baseline must cover: 1. syntax errors already required by `3. Core Syntax Specification.md`, 2. static-semantics errors already required by `4. Static Semantics Specification.md`, 3. deterministic manifest and import-resolution failures required by `5. Manifest, Stdlib, and SDK Resolution Specification.md`, -4. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`. +4. linking failures required by source-level name-resolution and module-linking rules, +5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`, +6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules. + +Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract. + +This means: + +- lowering failures remain in scope when they reflect a normative source-facing lowering rule or impossibility, +- verifier or loader failures remain in scope when they are directly attributable to malformed or unauthorized PBS-facing artifact usage already within the PBS contract, +- and purely internal compiler exceptions, artifact corruption, or backend-internal failures with no stable user-facing source attribution remain outside the PBS-facing diagnostics contract. + +When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format. Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap. -## 9. Cost and Runtime-Facing Diagnostics +## 11. Cost Diagnostics and Warning Policy -The current baseline is intentionally narrow. +Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline. -Tooling may surface cost-visibility notes or warnings around facts such as: +Tooling may surface qualitative cost facts as warnings or notes, especially for: - retention-bearing `bind`, - observable copy-versus-alias semantics, - and host-boundary crossings. -However, this document does not yet make a detailed warning taxonomy normative. Quantitative metrics, exact ranking, and profiling detail remain implementation-defined. +The choice between `warning` and `note` is implementation-defined in v1. -## 10. TODO +This document does not make a detailed warning taxonomy normative and does not require a warning at every such site. -The following items remain to be closed before this document can be considered complete: +Quantitative metrics such as exact byte counts, exact allocation counts, collector timing, or performance ranking remain outside the diagnostics contract and belong to profiling/tooling rather than to language conformance. -### 10.1 Depends on later closure of backend-facing specs +## 12. Current Limits -- whether diagnostic stability includes IR/lowering phase names, artifact offsets, or source maps; -- how host-binding lowering failures are surfaced back to source locations; -- whether verifier/load diagnostics are part of the PBS diagnostics contract directly or only through artifact-facing tooling. +The v1 diagnostics contract intentionally leaves the following items outside the currently standardized surface: -### 10.2 Still to decide inside this document +- transport-specific wire formats, +- one exact source-map format, +- one exact verifier/loader internal reporting shape, +- one mandatory warning catalog, +- and one mandatory remediation/help-content policy. -- whether diagnostic codes are mandatory in v1; -- which portions of human-readable wording are normative versus illustrative; -- whether notes/help text are required, optional, or outside conformance; -- exact cross-file diagnostic expectations for module/barrel/import failures; -- which qualitative cost warnings, if any, become mandatory rather than optional tooling enrichment. +These are not licenses to weaken the required external fields defined above. -## 11. Non-Goals +## 13. Non-Goals - Mandating one UI or IDE presentation style. -- Freezing a localization strategy in this pass. +- Freezing one exact localization strategy or locale set. - Turning every optimization hint into a normative diagnostic. - Replacing the acceptance/rejection rules already defined elsewhere. +- Standardizing profiler output as if it were language law. -## 12. Exit Criteria +## 14. Exit Criteria This document is ready to move beyond temporary status only when: 1. every required rejection in the current spec set is mapped to a diagnostic phase, -2. diagnostic metadata and attribution rules are explicit enough for conformance, -3. cost-visibility expectations are explicit where they are intended to be normative, -4. and the document no longer relies on unresolved backend- and runtime-facing TODO items for v1 tooling behavior. +2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, +3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures, +4. and cost/warning expectations are explicit where they are intended to be normative for v1. diff --git a/docs/pbs/specs/12. IR and Lowering Specification.md b/docs/pbs/specs/12. IR and Lowering Specification.md index e84e07cc..dc6860f3 100644 --- a/docs/pbs/specs/12. IR and Lowering Specification.md +++ b/docs/pbs/specs/12. IR and Lowering Specification.md @@ -80,8 +80,27 @@ The following inputs are already fixed elsewhere and must not be contradicted he - 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. Initial Section Targets +## 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: @@ -95,37 +114,38 @@ At minimum, the completed document should contain normative sections for: 8. host-binding emission, 9. artifact invariants required before verifier/loader stages. -## 7. TODO +## 8. TODO The following items remain to be closed before this document can be considered complete. -### 7.1 Depends on `9. Dynamic Semantics Specification.md` +### 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. -### 7.2 Depends on `10. Memory and Lifetime Specification.md` +### 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. -### 7.3 Still open across this document and adjacent backend-facing specs +### 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 artifact invariants belong here versus a future dedicated PBX/bytecode mapping document. +- 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. -## 8. Non-Goals +## 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. -## 9. Exit Criteria +## 10. Exit Criteria This document is ready to move beyond skeleton status only when: diff --git a/docs/pbs/specs/13. Conformance Test Specification.md b/docs/pbs/specs/13. Conformance Test Specification.md index 4121d5ba..59dfe67b 100644 --- a/docs/pbs/specs/13. Conformance Test Specification.md +++ b/docs/pbs/specs/13. Conformance Test Specification.md @@ -1,33 +1,32 @@ # PBS Conformance Test Specification -Status: Draft v1 (Temporary) -Applies to: conformance obligations, test categories, and acceptance criteria for PBS implementations +Status: Draft v1 (Quality-Gate Baseline) +Applies to: executable quality gates for PBS language frontends and language-level regression evidence ## 1. Purpose -This document defines the current PBS conformance-test baseline for v1. +This document defines the minimum quality-gate contract for PBS language implementations. -Its purpose is to make the active specification operational by stating: +The goal is practical and test-driven: -- which categories of behavior must be tested, -- which outcomes must be deterministic across conforming implementations, -- and which parts of the corpus are not yet mature enough to demand full conformance coverage. +- keep quality measurable while language, lowering, and runtime integration are still evolving, +- require only gates that can be proved with tests today, +- avoid freezing speculative backend policy too early. ## 2. Scope This document defines: -- required positive and negative source-level conformance surfaces, -- runtime-oracle expectations already fixed by active semantics, -- minimum host-binding and capability-gating test surfaces, -- and the current limits of v1 conformance while diagnostics and lowering remain incomplete. +- required unit-test gates for language frontend work, +- required regression gate behavior for published language behavior, +- and the boundary for runtime integration regression tests when a backend can emit executable artifacts. This document does not define: -- one specific test harness or repository layout, -- benchmark or performance certification, -- one artifact-level golden format, -- or product release governance policy. +- runtime semantics or VM behavior taxonomy, +- full artifact-level compatibility matrices, +- one test harness layout, +- or one repository structure for fixtures. ## 3. Authority and Precedence @@ -37,155 +36,94 @@ Normative precedence: 2. `2. Governance and Versioning.md` 3. `3. Core Syntax Specification.md` 4. `4. Static Semantics Specification.md` -5. `5. Manifest, Stdlib, and SDK Resolution Specification.md` -6. `6.2. Host ABI Binding and Loader Resolution Specification.md` -7. `7. Cartridge Manifest and Runtime Capabilities Specification.md` -8. `9. Dynamic Semantics Specification.md` -9. `10. Memory and Lifetime Specification.md` -10. `11. Diagnostics Specification.md` -11. `12. IR and Lowering Specification.md` -12. This document +5. `11. Diagnostics Specification.md` +6. `12. IR and Lowering Specification.md` +7. This document -This document must not weaken a normative requirement imposed by higher-precedence specs. +This document must not weaken normative requirements from higher-precedence specs. ## 4. Normative Inputs -This document depends on the active PBS v1 spec set. - -For the currently integrated conformance baseline, the key inputs are: +This document depends on: - `3. Core Syntax Specification.md` - `4. Static Semantics Specification.md` -- `5. Manifest, Stdlib, and SDK Resolution Specification.md` -- `6.2. Host ABI Binding and Loader Resolution Specification.md` -- `7. Cartridge Manifest and Runtime Capabilities Specification.md` -- `9. Dynamic Semantics Specification.md` -- `10. Memory and Lifetime Specification.md` - -Later expansion of this document will also depend on: - - `11. Diagnostics Specification.md` - `12. IR and Lowering Specification.md` -- `15. Bytecode and PBX Mapping Specification.md` +- `17. Compatibility and Evolution Policy.md` -## 5. Already-Settled Inputs +## 5. Quality Gate Model -The following inputs are already fixed elsewhere and must not be contradicted here: +PBS v1 uses two practical gate families. -- The parser must behave deterministically. -- Syntax and static semantics already enumerate minimum required rejection cases. -- Import/manifest failures are required to be deterministic. -- Loader failures for malformed or unauthorized host usage are required to be deterministic. -- Dynamic semantics are single-threaded and deterministic at the language-observable level. -- Memory semantics already distinguish identity-bearing values from pure-value and carrier forms. -- Traps are fatal runtime aborts rather than recoverable userland outcomes. +### 5.1 Gate U: Language Unit Quality Gate (Required) -## 6. Current Conformance Baseline +Every language frontend integrated into Studio/compiler must have passing unit tests that cover, at minimum: -At the current maturity level, a conforming PBS implementation must support tests in the following categories: +1. lexer behavior (valid tokenization and deterministic lexical rejection), +2. parser behavior (valid parse and deterministic syntax rejection), +3. AST shape for representative valid programs, +4. frontend-to-IR backend emission (`IRBackend`/`IRBackendFile`) for representative valid programs, +5. diagnostics surface for required rejection cases (`code`, `severity`, and primary attribution). -1. positive syntax and parsing tests, -2. negative syntax rejection tests, -3. positive binding and static-typing tests, -4. negative static-semantics rejection tests, -5. manifest/import-resolution tests, -6. host-binding and capability-gating tests, -7. source-level dynamic-semantics runtime tests, -8. source-level memory/identity behavior tests, -9. compatibility/regression tests for already-published behavior claims. +This gate is mandatory for each language regardless of backend maturity. -## 7. Source-Level Runtime Oracle +### 5.2 Gate I: Integration Regression Gate With Runtime (Conditional) -The current conformance oracle for runtime behavior is source-level and language-observable. +When a language backend can emit executable artifacts (for example bytecode), integration regression tests must be introduced for that language. -At minimum, conformance tests must cover: +At minimum, those tests must: -1. strict left-to-right evaluation where the language does not define an exception, -2. exactly-once evaluation of: - - call-target formation, - - call arguments, - - `if` conditions, - - `switch` selectors, - - `some(expr)` payload formation, - - `bind(context, fn_name)` context capture, -3. `optional` behavior: - - `some(expr)` is eager, - - `none` is canonical absence, - - `opt else fallback` evaluates `fallback` only on `none`, -4. `result` behavior: - - `expr!` passes through success payload, - - `expr!` immediately propagates same-domain error, - - `handle expr { ... }` passes through success payload, - - `handle` block arms terminate with `ok(payload)` or `err(E.case)`, - - short `handle` arms remap error as specified, -5. branch-selection behavior: - - non-selected `if` and `switch` arms do not execute, - - `switch` selects deterministically over admitted static discriminants, -6. trap behavior: - - traps do not enter `result` flow, - - traps are not intercepted by `handle`, - - traps abort the running PBS program path. +1. compile selected fixtures through the executable pipeline for that language, +2. execute them against the runtime line declared for that backend, +3. assert deterministic observable outcomes for supported fixtures, +4. and preserve fixed bugs and published supported examples as regression tests. -Conformance does not currently require a userland-visible trap taxonomy. It requires only the fatal-abort boundary already defined by the runtime and dynamic-semantics specs. +Until executable artifact emission exists for a language, Gate I is explicitly `deferred` for that language and does not block frontend progress. -## 8. Source-Level Memory and Identity Oracle +## 6. Regression Policy -At minimum, conformance tests must cover the following language-observable memory/identity facts: +Published supported behavior must remain regression-protected. -1. `struct` values are identity-bearing and alias through assignment, parameter passing, and return, -2. `service` values preserve singleton identity, -3. tuples, `optional`, and `result` do not create new userland identity of their own, -4. carriers preserve the identity behavior of their payloads, -5. `bind(context, fn_name)` captures the same runtime identity of the `struct` context rather than copying it, -6. callback invocation after `bind` observes mutation against that same captured context identity, -7. GC timing itself is not a conformance oracle, -8. reclamation is validated only indirectly through correctness and safety boundaries, not through collection timing. +At minimum, each language corpus must retain: -## 9. Host-Binding and Boundary Tests +1. bug reproductions for fixes that remain in supported scope, +2. published supported examples, +3. and core gate fixtures required to justify the language support state. -At minimum, conformance tests must cover: +Regression grouping by language is expected; one shared monolithic corpus is not required. -1. deterministic rejection of malformed or unauthorized host usage, -2. deterministic acceptance of valid host-backed declarations admitted by the active capability/runtime line, -3. correct source-level behavior of host-backed calls that are already admitted by the Host ABI and capability specs, -4. the absence of userland-visible raw pointers or heap-shared host-memory surfaces at the PBS boundary. +## 7. Claims and Evidence -This document does not yet require one artifact-level oracle for host-lowering shape. That remains dependent on later closure of lowering and PBX-mapping specifications. +For PBS quality claims at this stage: -## 10. TODO +- a language may be considered `frontend-ready` only with Gate U passing, +- a language may be considered `integration-ready` only with Gate U and Gate I passing where Gate I applies, +- and a published support claim must map to executable evidence from these gates. -The following items remain open before this document can be considered complete: +The exact publication vocabulary is owned by `17. Compatibility and Evolution Policy.md`. -### 10.1 Depends on `11. Diagnostics Specification.md` +## 8. Explicit Deferrals -- whether conformance checks diagnostic codes, spans, categories, wording classes, or only rejection phase and location; -- which warnings or cost diagnostics are in conformance scope. +The following are intentionally deferred until backend/runtime contracts stabilize further: -### 10.2 Depends on `12. IR and Lowering Specification.md` and `15. Bytecode and PBX Mapping Specification.md` +- detailed artifact-level conformance taxonomy, +- verifier-facing conformance taxonomy, +- full compatibility matrix axes beyond the current minimum support table, +- and one mandatory fixture repository layout. -- whether artifact-level conformance is required in addition to source-level conformance; -- which emitted host-binding and lowering invariants require golden tests; -- which source-to-artifact mapping hooks are part of the conformance contract. +## 9. Non-Goals -### 10.3 Still to decide inside this document +- Replacing normative language specs with tests. +- Defining runtime semantics in this document. +- Freezing backend architecture decisions prematurely. +- Treating performance benchmarks as conformance gates. -- whether PBS v1 has one conformance level or staged claims such as frontend-only versus full toolchain; -- fixture strategy for stdlib environments, host registries, and capability-grant scenarios; -- how compatibility-matrix claims are validated across language/profile/stdlib domains. +## 10. Exit Criteria -## 11. Non-Goals +This document is in a healthy state when: -- Replacing the normative specs with tests as the primary authority. -- Forcing one repository layout or one test harness. -- Treating performance benchmarking as language conformance. -- Inventing new language rules through test-only precedent. - -## 12. Exit Criteria - -This document is ready to move beyond temporary status only when: - -1. every active PBS v1 spec has a corresponding conformance surface, -2. positive and negative obligations are clearly separated, -3. diagnostics and artifact-level behavior have explicit oracle expectations where required, -4. compatibility and version claims can be tested rather than asserted informally, -5. and the document no longer relies on unresolved TODO items for the intended conformance level. +1. every active language has an explicit Gate U status, +2. languages with executable backends have an explicit Gate I status, +3. published supported language behavior has regression evidence, +4. and no support claim exists without mapped test evidence. diff --git a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md b/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md index b44b702a..827f096c 100644 --- a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md +++ b/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md @@ -54,8 +54,30 @@ The following inputs are already fixed elsewhere and must not be contradicted he - The loader resolves host bindings and rewrites `HOSTCALL` into `SYSCALL`. - VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata. - VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`. +- V1 source-attribution hooks for diagnostics/conformance need only support recovery of at least one source location for source-attributable backend failures; one exact source-map format is not yet required. -## 6. Initial Section Targets +## 6. Current Conformance-Facing Mapping Baseline + +The current boundary across backend-facing specs is: + +- `12. IR and Lowering 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. + +The current conformance-facing artifact baseline is invariant-based. + +At minimum, the PBS-facing artifact contract currently includes: + +1. canonical host-binding declarations in `SYSC` for admitted host-backed uses; +2. `SYSC` deduplication by canonical identity and ordering by first occurrence; +3. host-backed callsites emitted in pre-load form as `HOSTCALL `; +4. no host-binding metadata emission for VM-owned builtin projections, builtin constants, or intrinsic callsites; +5. no executable bytecode emission for stdlib interface modules by themselves; +6. enough source-attribution information to recover at least one source location for backend failures that remain in the PBS-facing diagnostics/conformance surface. + +This baseline does not require one full-image PBX golden. + +## 7. Initial Section Targets At minimum, the completed document should contain normative sections for: @@ -66,7 +88,7 @@ At minimum, the completed document should contain normative sections for: 5. intrinsic and builtin artifact obligations, 6. source-attribution hooks for diagnostics/conformance. -## 7. TODO +## 8. TODO The following items remain to be closed in future agenda discussion. @@ -75,15 +97,15 @@ The following items remain to be closed in future agenda discussion. - Which source-level constructs require dedicated artifact patterns versus implementation freedom. - How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority. - Whether compilers should emit final `INTRINSIC ` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL `. -- Whether a separate debug/source-map surface is part of v1. +- Which richer debug/source-map surfaces, if any, are added beyond the minimum attribution hooks already sufficient for v1 diagnostics and conformance. -## 8. Non-Goals +## 9. Non-Goals - Repeating the full PBX or ISA documentation. - Mandating one binary-emitter implementation strategy. - Defining loader patching internals already owned elsewhere. -## 9. Exit Criteria +## 10. Exit Criteria This document is ready to move beyond skeleton status only when: diff --git a/docs/pbs/specs/17. Compatibility and Evolution Policy.md b/docs/pbs/specs/17. Compatibility and Evolution Policy.md index f8fd8d31..fa23f69e 100644 --- a/docs/pbs/specs/17. Compatibility and Evolution Policy.md +++ b/docs/pbs/specs/17. Compatibility and Evolution Policy.md @@ -1,27 +1,31 @@ # PBS Compatibility and Evolution Policy -Status: Draft v0 (Skeleton) -Applies to: compatibility commitments, migration boundaries, deprecation discipline, and evolution constraints across PBS language and related domains +Status: Draft v0 (Quality-Gate Baseline) +Applies to: practical support states and compatibility publication policy tied to executable quality gates ## 1. Purpose -This document will define the normative compatibility and evolution policy for PBS. +This document defines how PBS support is published at the current project stage. + +The policy is intentionally minimal: + +- publish only support claims that are backed by tests, +- use a small support-state model that a solo project can maintain, +- and avoid over-specifying compatibility promises before backend/runtime contracts settle. ## 2. Scope -This document is intended to define: +This document defines: -- compatibility promises across language, profile, stdlib, and artifact domains, -- migration boundaries for additive versus incompatible changes, -- deprecation and removal policy details, -- behavioral versus binary compatibility expectations, -- obligations when publishing changes that affect older cartridges or projects. +- support-state vocabulary for language lines, +- minimum published support table fields, +- and how support-state changes must be recorded. This document does not define: -- one repository's release workflow, -- one implementation's branching strategy, -- detailed changelog formatting. +- full deprecation-window math per domain, +- one binary/PBX compatibility model, +- one release process implementation. ## 3. Authority and Precedence @@ -29,62 +33,86 @@ Normative precedence: 1. `1. Language Charter.md` 2. `2. Governance and Versioning.md` -3. Runtime and bytecode authority where applicable +3. `13. Conformance Test Specification.md` 4. This document If a rule here conflicts with higher-precedence authorities, it is invalid. ## 4. Normative Inputs -This document depends on, at minimum: +This document depends on: -- `1. Language Charter.md` - `2. Governance and Versioning.md` -- `6.2. Host ABI Binding and Loader Resolution Specification.md` -- `7. Cartridge Manifest and Runtime Capabilities Specification.md` +- `13. Conformance Test Specification.md` -## 5. Already-Settled Inputs +## 5. Support States -The following inputs are already fixed elsewhere and must not be contradicted here: +PBS currently uses three support states: -- Additive-first evolution is preferred for minor releases. -- Incompatible changes belong only in major lines with migration guidance. -- Canonical host primitive versioning uses `(module, name, version)`. -- Toolchains must reject unsupported targets deterministically. -- Older supported cartridges are expected to keep running across updates. +- `unsupported` +- `experimental` +- `supported` -## 6. Initial Section Targets +Meaning: -At minimum, the completed document should contain normative sections for: +- `unsupported`: no compatibility promise. +- `experimental`: active development; behavior may change; tests may exist but are not yet a stable support promise. +- `supported`: active compatibility promise for declared scope, backed by required quality gates. -1. compatibility domains, -2. behavioral versus binary compatibility, -3. deprecation windows, -4. migration obligations, -5. compatibility-matrix expectations, -6. artifact and runtime compatibility boundaries. +## 6. Gate-Backed Support Rule -## 7. TODO +Support states must map to quality-gate evidence: -The following items remain to be closed in future agenda discussion. +1. `frontend-ready` evidence requires Gate U from `13`. +2. `integration-ready` evidence requires Gate U plus Gate I when Gate I applies to the language/backend. +3. `supported` state requires maintained evidence for the scope being promised. -- Exact compatibility window by domain. -- Whether PBX/binary compatibility has an independent policy track from source-level compatibility. -- How stdlib-line compatibility interacts with dependency projects over time. -- Which changes require migration tooling versus documentation-only migration notes. -- Whether frontend-only phased implementation claims need distinct compatibility labels. +No published `supported` claim may exist without mapped test evidence. -## 8. Non-Goals +## 7. Minimum Published Support Table -- Replacing governance with ad hoc decisions. -- Defining one product release calendar. -- Freezing every editorial clarification as a compatibility event. +A published support table must include, at minimum: -## 9. Exit Criteria +1. language identifier, +2. language line/version scope, +3. runtime line (or `N/A` when Gate I is not applicable yet), +4. Gate U status, +5. Gate I status (`pass`, `fail`, or `deferred`), +6. support state (`unsupported`, `experimental`, `supported`), +7. optional notes. -This document is ready to move beyond skeleton status only when: +No additional matrix dimensions are mandatory at this stage. -1. compatibility commitments are explicit by domain, -2. deprecation and migration duties are normatively described, -3. source, stdlib, artifact, and runtime compatibility boundaries are separated clearly, -4. the document no longer relies on unresolved `TODO` items for ordinary v1 compatibility claims. +## 8. Support-State Changes + +When support changes, the project must update together: + +1. support table state, +2. gate evidence status, +3. and a short rationale note when users could be affected. + +This document requires visibility of change, not a specific changelog format. + +## 9. Explicit Deferrals + +The following remain intentionally open: + +- domain-specific promise strength beyond the current gate-backed model, +- exact deprecation/removal windows, +- PBX/binary compatibility policy details, +- mandatory migration tooling triggers. + +## 10. Non-Goals + +- Simulating large-organization compatibility governance. +- Freezing domains that are still not implemented. +- Requiring one matrix tooling format. + +## 11. Exit Criteria + +This document is in a healthy state when: + +1. every active language line has an explicit support state, +2. every `supported` state has mapped gate evidence, +3. support changes are reflected in table + evidence + note, +4. and no compatibility promise depends on undocumented assumptions. diff --git a/docs/pbs/specs/19. Verification and Safety Checks Specification.md b/docs/pbs/specs/19. Verification and Safety Checks Specification.md index c73d32b1..b43c5d41 100644 --- a/docs/pbs/specs/19. Verification and Safety Checks Specification.md +++ b/docs/pbs/specs/19. Verification and Safety Checks Specification.md @@ -1,35 +1,36 @@ # PBS Verification and Safety Checks Specification -Status: Draft v0 (Skeleton) -Applies to: verifier-facing safety obligations, artifact validation boundaries, and the division of safety checks across compiler, loader, verifier, and runtime +Status: Draft v0 (Quality-Gate Baseline) +Applies to: test-backed safety gates for compiler stages and integration regression safety checks ## 1. Purpose -This document will define the verification and safety-check model relevant to PBS-produced artifacts. +This document defines the minimum safety/verification quality gates that can be enforced now. + +The intent is to keep safety measurable without over-specifying future verifier internals before backend and runtime integration stabilize. ## 2. Scope -This document is intended to define: +This document defines: -- which safety obligations are enforced before runtime execution, -- the division of responsibility across compiler, loader, verifier, and runtime, -- verifier-facing assumptions about already-lowered artifacts, -- safety properties that must hold for conforming PBS-produced images. +- compiler-stage safety checks that must be covered by tests now, +- conditional integration safety regression checks for executable backends, +- and evidence requirements for safety-related support claims. This document does not define: -- full runtime trap semantics, -- source-language typing rules already owned elsewhere, -- one verifier implementation architecture. +- full verifier algorithm internals, +- full bytecode/runtime proof obligations, +- or one mandatory verifier implementation architecture. ## 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. `6.2. Host ABI Binding and Loader Resolution Specification.md` -4. `12. IR and Lowering Specification.md` +1. `2. Governance and Versioning.md` +2. `11. Diagnostics Specification.md` +3. `12. IR and Lowering Specification.md` +4. `13. Conformance Test Specification.md` 5. `15. Bytecode and PBX Mapping Specification.md` 6. This document @@ -37,52 +38,67 @@ If a rule here conflicts with higher-precedence authorities, it is invalid. ## 4. Normative Inputs -This document depends on, at minimum: +This document depends on: -- `6.2. Host ABI Binding and Loader Resolution Specification.md` +- `11. Diagnostics Specification.md` - `12. IR and Lowering Specification.md` +- `13. Conformance Test Specification.md` - `15. Bytecode and PBX Mapping Specification.md` -## 5. Already-Settled Inputs +## 5. Safety Gate Model -The following inputs are already fixed elsewhere and must not be contradicted here: +PBS currently uses two safety gate families. -- Loader-side ABI validation is mandatory. -- Capability gating is mandatory during load. -- The verifier runs after loader patching on the final numeric executable image. -- Loader and verifier validate different layers of the contract. +### 5.1 Gate S-U: Compiler-Stage Safety Unit Tests (Required) -## 6. Initial Section Targets +At minimum, test coverage must exist for: -At minimum, the completed document should contain normative sections for: +1. deterministic rejection of malformed source input at lexer/parser level, +2. deterministic rejection of in-scope frontend semantic failures, +3. deterministic dependency/manifest validation failures, +4. stable diagnostics identity for required rejection surfaces (`code`, `severity`, primary attribution). -1. safety-check phase boundaries, -2. compiler-emitted safety assumptions, -3. loader-side safety checks, -4. verifier-side safety checks, -5. residual runtime safety assumptions, -6. required deterministic rejection conditions. +This gate is mandatory regardless of backend maturity. -## 7. TODO +### 5.2 Gate S-I: Integration Safety Regression With Runtime (Conditional) -The following items remain to be closed in future agenda discussion. +For languages/backends that emit executable artifacts, integration safety regression tests must be introduced. -- Exact verifier obligations beyond what is already implied by runtime/bytecode authority. -- Which safety properties must be proven before execution versus checked defensively at runtime. -- Whether PBS-level conformance includes explicit verifier test surfaces or only artifact validity outcomes. -- How source-level diagnostics relate to verifier and artifact-level safety failures. +At minimum, these tests must cover: + +1. deterministic rejection behavior for known malformed/unsupported integration scenarios in supported scope, +2. preservation of fixed safety regressions, +3. and repeatability across the declared runtime line for that backend. + +When executable artifact emission is not yet present, Gate S-I is explicitly `deferred`. + +## 6. Evidence Requirements + +Safety claims must map to gate evidence: + +- `S-U` evidence is required for baseline safety posture, +- `S-I` evidence is additionally required for integration-ready safety claims, +- and no published safety-related support claim should exist without current gate evidence. + +## 7. Explicit Deferrals + +The following are intentionally deferred: + +- full verifier obligation catalog, +- formal proof of runtime safety properties, +- richer source-map/debug attribution standards beyond current minimum diagnostics needs. ## 8. Non-Goals -- Replacing runtime or bytecode authority. -- Duplicating the full Host ABI spec. -- Freezing one verifier implementation algorithm. +- Replacing runtime/bytecode authority. +- Freezing verifier architecture before implementation maturity. +- Defining performance tooling in a safety spec. ## 9. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is in a healthy state when: -1. the division of safety responsibilities is explicit, -2. verifier-facing assumptions are aligned with lowering and artifact mapping, -3. deterministic rejection surfaces are normatively described, -4. the document no longer relies on unresolved `TODO` items for ordinary v1 safety claims. +1. required compiler-stage safety checks are test-backed, +2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`), +3. safety regressions are preserved in tests, +4. and safety-related support claims remain evidence-backed.