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