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

agendas and decisions

Browse Source
This commit is contained in:
bQUARKz 2026-03-04 19:28:00 +00:00
parent c66ccd7efe
commit 96f971bbe4
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
34 changed files with 1090 additions and 1447 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
docs/pbs/agendas/11. Diagnostics Agenda.md
View File

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

143
docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md
View File

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

113
docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md
View File

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

127
docs/pbs/agendas/11.3. Diagnostics Workshop 3 - Cost Diagnostics and Warning Policy.md
View File

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

125
docs/pbs/agendas/11.4. Diagnostics Workshop 4 - Backend-Originated Diagnostic Mapping.md
View File

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

116
docs/pbs/agendas/13. Conformance Test Agenda.md
View File

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

98
docs/pbs/agendas/13.1. Conformance Workshop 1 - Conformance Claim Levels.md
View File

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

96
docs/pbs/agendas/13.2. Conformance Workshop 2 - Source-Level Oracle and Diagnostic Oracle.md
View File

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

98
docs/pbs/agendas/13.3. Conformance Workshop 3 - Artifact-Level Conformance and Fixtures.md
View File

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

100
docs/pbs/agendas/13.4. Conformance Workshop 4 - Regression and Compatibility Matrices.md
View File

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

3
docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md
View File

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

16
docs/pbs/agendas/17.3. Compatibility Workshop 3 - Compatibility Matrices and Published Claims.md
View File

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

2
docs/pbs/decisions/Allocation and Cost Visibility Decision.md
View File

@ -1,6 +1,6 @@
# Allocation and Cost Visibility Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial allocation-and-cost closure pass
## 1. Context

133
docs/pbs/decisions/Artifact-Level Conformance and Fixture Model Decision.md Normal file
View File

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

164
docs/pbs/decisions/Compatibility Matrix and Published Claims Decision.md Normal file
View File

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

167
docs/pbs/decisions/Conformance Claim Levels Decision.md Normal file
View File

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

215
docs/pbs/decisions/Diagnostics Contract Decision.md Normal file
View File

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

2
docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md
View File

@ -1,6 +1,6 @@
# Dynamic Semantics - Branch Selection Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial branch-selection closure pass
## 1. Context

2
docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md
View File

@ -1,6 +1,6 @@
# Dynamic Semantics - Effect Surfaces Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial effect-surfaces closure pass
## 1. Context

2
docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md
View File

@ -1,6 +1,6 @@
# Dynamic Semantics - Execution Model Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial execution-model closure pass
## 1. Context

2
docs/pbs/decisions/GC and Reachability Decision.md
View File

@ -1,6 +1,6 @@
# GC and Reachability Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial GC-and-reachability closure pass
## 1. Context

2
docs/pbs/decisions/Host Memory Boundary Decision.md
View File

@ -1,6 +1,6 @@
# Host Memory Boundary Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial host-boundary closure pass
## 1. Context

2
docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md
View File

@ -1,6 +1,6 @@
# Lifetime Control and Future Profiles Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial lifetime-control policy closure pass
## 1. Context

2
docs/pbs/decisions/Name Resolution - Builtin Shells and Host Owners Decision.md
View File

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

2
docs/pbs/decisions/Name Resolution - Callable Sets and Cross-Module Linking Decision.md
View File

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

2
docs/pbs/decisions/Name Resolution - Linking Phase Boundary Decision.md
View File

@ -1,6 +1,6 @@
# Name Resolution - Linking Phase Boundary Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context

2
docs/pbs/decisions/Name Resolution - Scope, Lookup, and Imports Decision.md
View File

@ -1,6 +1,6 @@
# Name Resolution - Scope, Lookup, and Imports Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context

2
docs/pbs/decisions/Value Representation and Identity Decision.md
View File

@ -1,6 +1,6 @@
# Value Representation and Identity Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial value-representation closure pass
## 1. Context

176
docs/pbs/specs/11. Diagnostics Specification.md
View File

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

36
docs/pbs/specs/12. IR and Lowering Specification.md
View File

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

198
docs/pbs/specs/13. Conformance Test Specification.md
View File

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

32
docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md
View File

@ -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 <sysc_index>`;
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 <id>` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL <decl_index>`.
- 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:

126
docs/pbs/specs/17. Compatibility and Evolution Policy.md
View File

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

106
docs/pbs/specs/19. Verification and Safety Checks Specification.md
View File

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