agendas and decisions
This commit is contained in:
@@ -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
-1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user