agendas and decisions

This commit is contained in:
2026-03-24 13:42:18 +00:00
parent c66ccd7efe
commit 96f971bbe4
34 changed files with 1090 additions and 1447 deletions
+124 -52
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.
@@ -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:
@@ -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.
@@ -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:
@@ -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.
@@ -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.