# PBS Diagnostics Agenda

Status: Active

## Purpose

Drive the remaining discussions needed to close `11. Diagnostics Specification.md` without inventing backend or UI policy prematurely.

## Context

The diagnostics spec already fixes the minimum phase split and source-attribution baseline, but it still leaves open:

- whether diagnostic codes are mandatory in v1,
- which parts of wording are normative,
- what cross-file attribution is required for import and barrel failures,
- whether cost-facing warnings become part of conformance,
- and how backend-facing failures map back to source once lowering and PBX mapping are closed.

This agenda should keep the diagnostics contract narrow, deterministic, and implementable by more than one toolchain.

## Decisions To Produce

1. Decide the minimum normative diagnostic identity model for v1:
   phase only, phase plus category, or stable machine-readable code.
2. Decide the minimum normative attribution package:
   file, primary span, secondary span/note requirements, and cross-file references.
3. Decide which human-facing wording requirements are normative versus illustrative.
4. Decide whether any qualitative cost diagnostics are mandatory in v1.
5. Decide how lowering, verifier, and load-facing failures surface back into the PBS-facing diagnostics contract.

## Core Questions

1. Is a stable diagnostic code required for conformance, or is deterministic rejection phase and source attribution enough?
2. For import, barrel, and cross-module lookup failures, what exact locations must be reported?
3. Must notes and help text exist for certain classes of error, or are they optional tooling quality?
4. Which backend-originated failures remain PBS diagnostics versus artifact-tool diagnostics?
5. Are warnings part of the normative contract at all in v1, and if so which ones?

## Expected Spec Material

The resulting spec work should be able to add or close sections for:

- diagnostic identity and stability,
- source attribution rules,
- cross-file attribution rules,
- optional versus required notes/help,
- warning taxonomy boundaries,
- backend-facing diagnostic mapping boundaries,
- and conformance hooks consumed by `13. Conformance Test Specification.md`.

## Non-Goals

- Designing IDE presentation, colors, or UX.
- Building a complete trap taxonomy.
- Standardizing localization.
- Freezing one internal compiler error architecture.
- Rewriting rejection rules already owned by syntax, semantics, or loader specs.

## Inputs

- `docs/pbs/specs/3. Core Syntax Specification.md`
- `docs/pbs/specs/4. Static Semantics Specification.md`
- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
- `docs/pbs/specs/11. Diagnostics Specification.md`
- `docs/pbs/specs/12. IR and Lowering Specification.md`
- `docs/pbs/specs/13. Conformance Test Specification.md`
- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`