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
@@ -1,6 +1,6 @@
# Allocation and Cost Visibility Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial allocation-and-cost closure pass
## 1. Context
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -1,6 +1,6 @@
# Dynamic Semantics - Branch Selection Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial branch-selection closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Dynamic Semantics - Effect Surfaces Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial effect-surfaces closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Dynamic Semantics - Execution Model Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial execution-model closure pass
## 1. Context
@@ -1,6 +1,6 @@
# GC and Reachability Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial GC-and-reachability closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Host Memory Boundary Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial host-boundary closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Lifetime Control and Future Profiles Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial lifetime-control policy closure pass
## 1. Context
@@ -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
@@ -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
@@ -1,6 +1,6 @@
# Name Resolution - Linking Phase Boundary Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Name Resolution - Scope, Lookup, and Imports Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial name-resolution closure pass
## 1. Context
@@ -1,6 +1,6 @@
# Value Representation and Identity Decision
Status: Accepted
Status: Accepted (Implemented)
Cycle: Initial value-representation closure pass
## 1. Context