126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# 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`
|