# PBS Diagnostics Specification

Status: Draft v1  
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, linking, host-admission checks, and load-facing validation surfaces

## 1. Purpose

This document defines the PBS diagnostics baseline for v1.

Its purpose is to make diagnostics stable enough that:

- conforming tools report failures in the same phases,
- users receive deterministic and actionable source-facing feedback,
- diagnostics remain machine-identifiable even when rendered in different locales,
- conformance can validate rejection class and attribution,
- and frontend, linking, manifest, and load-facing validation remain aligned.

## 2. Scope

This document defines:

- the required external diagnostic phases,
- the minimum machine-readable identity of a PBS-facing diagnostic,
- the minimum source-facing payload and attribution baseline,
- the boundary between normative diagnostic fields and implementation-defined rendering,
- the boundary between PBS-facing diagnostics and artifact/tooling failures,
- and the warning/cost-diagnostics boundary for v1.

This document does not define:

- a full runtime trap catalog,
- UI presentation or IDE styling,
- one exact localized sentence for every diagnostic,
- one transport-specific schema such as LSP field mapping,
- one standardized source-map or artifact-offset format,
- or profiling/reporting formats.

## 3. Authority and Precedence

Normative precedence:

1. `1. Language Charter.md`
2. `3. Core Syntax Specification.md`
3. `4. Static Semantics Specification.md`
4. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
6. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
7. `9. Dynamic Semantics Specification.md`
8. `10. Memory and Lifetime Specification.md`
9. `13. Lowering IRBackend Specification.md`
10. This document

If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins.

## 4. Normative Inputs

This document depends on, at minimum:

- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
- `13. Lowering IRBackend Specification.md`

Relevant backend-facing integration points also include:

- `docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md`
- `docs/specs/compiler/16. Runtime Execution and Initialization Specification.md`
- `docs/specs/compiler/19. Verification and Safety Checks Specification.md`

## 5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

- The syntax specification already enumerates minimum required syntax diagnostics.
- The static semantics specification already enumerates minimum required static diagnostics.
- Manifest/import resolution failures are required to be deterministic compile-time errors.
- Loader failures around malformed or unauthorized host usage are required to be deterministic.
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
- PBS requires deterministic diagnostics for source-form globals, lifecycle markers, and init admission.
- Published-wrapper, boot-guard, synthetic-origin, and invalid-lifecycle-declaration failures are compiler-general. See `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.

## 6. Required Diagnostic Phases

PBS-facing tooling must distinguish at least the following external diagnostic phases:

1. `syntax`,
2. `static semantics`,
3. `manifest/import resolution`,
4. `linking`,
5. `host-binding/capability admission`,
6. `load-facing rejection` when directly attributable to malformed or unauthorized PBS-facing artifact usage.

`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.

The `host-binding/capability admission` phase covers the source shape of `[Host]` and `[Capability]`. Canonical host-binding identity and capability consistency over `IRReservedMetadata` are platform-owned and are not moved by this specification.

This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.

## 7. Required Diagnostic Identity, Payload, and Attribution

Every PBS-facing diagnostic must expose a stable machine-readable identity.

At minimum, every required source-facing diagnostic must include:

1. `diagnostic code`,
2. `severity`,
3. `phase`,
4. `primary file`,
5. `primary span/location`,
6. `message template id`,
7. stable named placeholders for that template when applicable,
8. and a rendered human-readable message.

The stable identity of a diagnostic is carried primarily by:

- `diagnostic code`,
- stable phase attribution,
- `message template id`,
- primary attribution,
- and the rejection-class semantics represented by the code/template pair.

Human wording alone is not the identity of the diagnostic.

Conformance assertions must key diagnostics by stable machine fields (`code`, `phase`, `message template id`, attribution), not by localized rendered sentence text.

## 8. Cross-File Attribution, Notes, and Hint Surface

Cross-file attribution follows an action-first rule.

Rules:

- import failures must point primarily to the importing site,
- barrel failures must point primarily to the barrel site or entry that triggered the failure,
- linking and cross-module lookup failures must point primarily to the use or reference site that could not be resolved,
- related sites may be attached when known,
- and `duplicate` or `conflict` diagnostics must include at least one related site.

`notes` are optional by default in v1 except where another rule explicitly requires related-location reporting.

The stable visible categories currently reserved are:

- `error`,
- `warning`,
- `note`,
- `hint`.

`hint` is part of the diagnostics model in v1, but hint content is not mandatory.

## 9. Wording, Templates, and Localization

Rendered wording does not need to be byte-for-byte identical across implementations or locales.

However:

- the rendered message must preserve the same normative rejection meaning,
- the rendered message must not contradict the governing spec rule,
- and the code/template/placeholder contract must remain stable.

This allows implementations to localize diagnostics while preserving conformance-friendly identity.

Human-readable messages may be rendered from locale-specific templates, but template/token identity remains stable across locales.

Implementations should preserve the ability to render an English default or fallback message for future interoperability-oriented transports such as a possible LSP integration, even when the local product surface renders another language by default.

Examples in this specification are illustrative unless explicitly marked normative.

`help` or guided remediation is outside the minimum mandatory contract in v1.

## 10. Required Diagnostic Coverage and Backend-Originated Failures

At minimum, the PBS diagnostics baseline must cover:

1. syntax errors already required by `3. Core Syntax Specification.md`,
2. static-semantics errors already required by `4. Static Semantics Specification.md`,
3. deterministic manifest and import-resolution failures required by `5. Manifest, Stdlib, and SDK Resolution Specification.md`,
4. linking failures required by source-level name-resolution and module-linking rules,
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
8. lifecycle-marker and source-form global diagnostics, including:
   - `global initializer uses unsupported form`,
   - `global dependency cycle detected`,
   - `global import must resolve through a global barrel entry`,
   - `imported symbol shadows existing visible symbol; alias required`,
   - `init function must have signature fn name() -> void`,
   - `frame function must have signature fn name() -> void`,
   - `multiple module init functions detected`,
   - `multiple project init functions detected`,
   - `multiple frame functions detected`,
   - `missing frame function for executable project`,
   - `project init must be colocated with frame`,
   - `Init attribute target invalid`,
   - `InitAllowed is valid only on SDK host methods`,
   - `host call not allowed during init`.
9. compiler-general lifecycle-assembly and IRVM-precondition failures, which this PBS catalog MUST NOT claim as PBS required coverage; see `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
10. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
   - unresolved terminal asset reference,
   - namespace-versus-terminal asset misuse,
   - structurally invalid symbolic asset path admitted by source syntax but rejected by semantic surface rules.
11. ignored-value diagnostics for expression statements, including:
   - a stable warning when a materialized value is produced and then ignored,
   - and no warning for unit-like expression statements.

Reserved-attribute diagnostics for host-backed asset lowering must also cover:

- duplicate `AssetLowering` declarations on the same host signature,
- missing or malformed `AssetLowering(param = N)` arguments,
- out-of-range `AssetLowering.param` indexes,
- and `AssetLowering` targets whose selected parameter is not statically typed as `Addressable`.

Documentation attribute diagnostics must cover:

- unterminated documentation text block syntax,
- `Doc` used without the required `markdown` argument,
- `Doc` with extra or unknown arguments,
- `Doc` with a non-documentation-text-block payload,
- duplicate `Doc` on the same declaration,
- `Doc` applied to a parameter or other non-documentable surface,
- normalized empty or whitespace-only documentation payload,
- and rejected aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.

Diagnostics for duplicate `Doc` attributes must be static semantic diagnostics and should include a related site for the conflicting declaration attribute when available.

At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.

Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.

This means:

- lowering failures remain in scope when they reflect a normative source-facing lowering rule or impossibility,
- verifier or loader failures remain in scope when they are directly attributable to malformed or unauthorized PBS-facing artifact usage already within the PBS contract,
- and purely internal compiler exceptions, artifact corruption, or backend-internal failures with no stable user-facing source attribution remain outside the PBS-facing diagnostics contract.

When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.

For backend-owned symbolic asset surfaces:

- diagnostics SHOULD point primarily to the symbolic reference site in source;
- the frontend MAY use backend-provided surface context to improve earlier diagnostics;
- backend ownership of final validation does not remove the requirement for deterministic source-facing diagnostics when validation fails.

Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap.

Dependency-scoped fail-fast admission is not equivalent to global build abort.  
When failures exist, implementations must still preserve deterministic diagnostic identity and attribution for unaffected independent modules processed in the same build.

## 11. Cost Diagnostics and Warning Policy

Warnings are supported in v1, and one warning is mandatory for PBS core: ignored materialized values in expression statements.

The mandatory warning identity for this rule is `W_SEM_IGNORED_VALUE`.

Tooling may surface qualitative cost facts as warnings or notes, especially for:

- retention-bearing `bind`,
- observable copy-versus-alias semantics,
- and host-boundary crossings.

The choice between `warning` and `note` is implementation-defined in v1.

This document does not make a detailed warning taxonomy normative and does not require a warning at every such site.

Quantitative metrics such as exact byte counts, exact allocation counts, collector timing, or performance ranking remain outside the diagnostics contract and belong to profiling/tooling rather than to language conformance.

## 12. Current Limits

The v1 diagnostics contract intentionally leaves the following items outside the currently standardized surface:

- transport-specific wire formats,
- one exact source-map format,
- one exact verifier/loader internal reporting shape,
- one mandatory warning catalog,
- and one mandatory remediation/help-content policy.

These are not licenses to weaken the required external fields defined above.

## 13. Non-Goals

- Mandating one UI or IDE presentation style.
- Freezing one exact localization strategy or locale set.
- Turning every optimization hint into a normative diagnostic.
- Replacing the acceptance/rejection rules already defined elsewhere.
- Standardizing profiler output as if it were language law.

## 14. Exit Criteria

This document is ready to move beyond temporary status only when:

1. every required rejection in the current spec set is mapped to a diagnostic phase,
2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, including locale-agnostic token/template identity,
3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures,
4. and cost/warning expectations are explicit where they are intended to be normative for v1.