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?

Proposed Workshop Sequence

Workshop 1: Diagnostic Identity and Attribution

Purpose:

• close the minimum diagnostic identity model,
• close required source-attribution fields,
• and decide cross-file attribution for import and linking failures.

Expected decisions:

• phase-only versus stable code model,
• required file/span/note package,
• and minimum cross-file reporting rules.

Workshop 2: Wording, Notes, and Help Surface

Purpose:

• decide what human-facing wording is normative,
• whether notes/help are required anywhere,
• and where implementation freedom should remain.

Expected decisions:

• wording stability boundary,
• note/help obligations,
• and illustrative versus normative examples policy.

Workshop 3: Cost Diagnostics and Warning Policy

Purpose:

• decide whether warnings are part of v1 conformance at all,
• and, if yes, which qualitative cost warnings become mandatory.

Expected decisions:

• warning-in-conformance yes or no,
• mandatory versus optional cost notes,
• and boundary between diagnostics and profiling/tooling.

Workshop 4: Backend-Originated Diagnostic Mapping

Purpose:

• decide how lowering, verifier, and load-facing failures map back to the PBS-facing contract.

Expected decisions:

• PBS-facing versus artifact-facing boundary,
• source-mapping obligations for backend failures,
• and inputs needed from 12 and 15.

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