# PBS Diagnostics Specification

Status: Draft v0 (Skeleton)  
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, lowering boundaries, and related load-facing validation surfaces

## 1. Purpose

This document will define the PBS diagnostics contract.

Its purpose is to make diagnostics stable enough that:

- conforming tools report failures in the same places,
- users receive deterministic and actionable feedback,
- conformance can validate not only acceptance/rejection but also diagnostic class and location,
- frontend, manifest, and load-facing validation remain aligned.

## 2. Scope

This document is intended to define:

- diagnostic categories and phases,
- minimum metadata carried by diagnostics,
- stability expectations for source spans, file attribution, and phase attribution,
- the normative relationship between syntax/static diagnostics and later lowering/load diagnostics,
- which diagnostics are required versus implementation-defined enrichments,
- cost-visibility diagnostics or warnings once memory/effect decisions are closed.

This document does not define:

- the full runtime trap catalog,
- UI presentation or IDE styling,
- implementation-specific hint ranking,
- profiling output 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. `12. IR and Lowering 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`

This document will also depend on decisions closed in:

- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
- the future backend agenda sequence tracked in `docs/agendas/`

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

## 6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. diagnostic phases,
2. required diagnostic metadata,
3. span and file attribution,
4. syntax-diagnostic contract,
5. static-diagnostic contract,
6. manifest/import-resolution diagnostics,
7. lowering and host-binding diagnostics,
8. load-facing and capability diagnostics,
9. cost-visibility diagnostics and warnings.

## 7. A Ver

The following items remain to be closed before this document can be considered complete.

### 7.1 Depends on `9. Dynamic Semantics Specification.md`

- Which runtime-observable trap categories need source-facing compile-time or conformance hooks.
- Which constructs require special diagnostics for abrupt completion, propagation, or effect misuse beyond what static semantics already lists.

### 7.2 Depends on `10. Memory and Lifetime Specification.md`

- Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings.
- Which cost facts are mandatory versus implementation-defined enrichment.

### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`

- Whether diagnostic stability includes IR/lowering phase names, artifact offsets, or source maps.
- How host-binding lowering failures are surfaced back to source locations.
- Whether verifier/load diagnostics are part of the PBS diagnostics contract directly or only through artifact-facing tooling.

### 7.4 Still to decide inside this document

- Whether diagnostic codes are mandatory in v1.
- Which portions of human-readable wording are normative versus illustrative.
- Whether notes/help text are required, optional, or outside conformance.
- Exact cross-file diagnostic expectations for module/barrel/import failures.

## 8. Non-Goals

- Mandating one UI or IDE presentation style.
- Freezing a localization strategy in this pass.
- Turning every optimization hint into a normative diagnostic.
- Replacing the acceptance/rejection rules already defined elsewhere.

## 9. Exit Criteria

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

1. every required rejection in the current spec set is mapped to a diagnostic phase,
2. diagnostic metadata and attribution rules are explicit enough for conformance,
3. cost-visibility expectations are aligned with memory/effect specs,
4. the document no longer relies on unresolved backend and runtime-facing `A Ver` items for v1 tooling behavior.