prometeu-studio/docs/pbs/agendas/11. Diagnostics Agenda.md

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