216 lines
9.5 KiB
Markdown
216 lines
9.5 KiB
Markdown
# 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/12. Diagnostics Specification.md`
|
|
- `docs/general/specs/13. Conformance Test Specification.md`
|
|
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
|
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
|
- `docs/general/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.
|