144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# PBS Diagnostics Workshop 1
|
|
|
|
Status: Active
|
|
|
|
## Purpose
|
|
|
|
Run the first focused discussion for `11. Diagnostics Specification.md` on the minimum diagnostic contract:
|
|
|
|
- diagnostic identity,
|
|
- phase attribution,
|
|
- source attribution,
|
|
- and cross-file attribution for import and linking failures.
|
|
|
|
## Why This Slice First
|
|
|
|
This slice should come first because every later diagnostics discussion depends on a stable answer to:
|
|
|
|
- what one diagnostic fundamentally is,
|
|
- what metadata is guaranteed,
|
|
- and what conformance is even allowed to assert.
|
|
|
|
It should stay narrow and avoid wording or warning policy for now.
|
|
|
|
## Proposed Meeting Order
|
|
|
|
1. Reconfirm already-settled rejection and phase facts.
|
|
2. Close the minimum diagnostic identity model.
|
|
3. Close the minimum source-attribution package.
|
|
4. Close cross-file attribution for import, barrel, and linking failures.
|
|
5. Record carry-forward items for wording and warning workshops.
|
|
|
|
## Already-Settled Inputs To Reconfirm
|
|
|
|
The meeting should explicitly reaffirm:
|
|
|
|
- syntax and static semantics already define required rejection classes,
|
|
- manifest/import failures are deterministic compile-time failures,
|
|
- load-facing malformed or unauthorized host usage is deterministic,
|
|
- traps are fatal runtime outcomes rather than ordinary diagnostics,
|
|
- and stable source spans are already required at token and AST level.
|
|
|
|
These should not be reopened here.
|
|
|
|
## Decisions To Produce
|
|
|
|
1. The minimum normative identity of a diagnostic.
|
|
2. The minimum mandatory attribution fields.
|
|
3. Cross-file attribution rules for import and barrel failures.
|
|
4. The smallest stable phase vocabulary diagnostics must expose.
|
|
|
|
## Candidate Decisions
|
|
|
|
### 1. Diagnostic Identity Is Phase Plus Stable Class, Not Mandatory Numeric Code
|
|
|
|
Candidate direction:
|
|
|
|
- v1 requires deterministic phase attribution and a stable rejection class.
|
|
- A machine-readable code is allowed but not yet mandatory.
|
|
- Human wording is not the identity of the diagnostic.
|
|
|
|
Rationale:
|
|
|
|
- This keeps the contract stable without overfitting to one toolchain code system.
|
|
- It leaves room to add codes later without making v1 blocked on taxonomy design.
|
|
|
|
Alternative to discuss:
|
|
|
|
- require stable codes now because conformance and tooling benefit from them.
|
|
|
|
### 2. Minimum Attribution Package Is File, Primary Span, and Message Class
|
|
|
|
Candidate direction:
|
|
|
|
- every source-attributable diagnostic must expose:
|
|
primary file,
|
|
primary source span or location,
|
|
stable phase,
|
|
and enough human-readable content to distinguish the rejection class.
|
|
- secondary notes are optional unless another rule explicitly requires them.
|
|
|
|
Rationale:
|
|
|
|
- This matches the current draft while making the required payload explicit.
|
|
|
|
### 3. Cross-File Failures Need At Least One Primary Site And Optional Related Sites
|
|
|
|
Candidate direction:
|
|
|
|
- import failure must point primarily to the importing site,
|
|
- barrel-entry mismatch must point primarily to the barrel site,
|
|
- tools may additionally point to the unresolved or conflicting declaration site when known,
|
|
- but v1 does not require one exact note shape yet.
|
|
|
|
Rationale:
|
|
|
|
- This keeps source-facing diagnostics actionable without freezing one multi-span presentation format.
|
|
|
|
### 4. Keep A Small Stable Phase Vocabulary
|
|
|
|
Candidate direction:
|
|
|
|
- the minimum stable external vocabulary is:
|
|
syntax,
|
|
static semantics,
|
|
manifest/import resolution,
|
|
linking,
|
|
and host-binding/capability admission.
|
|
- tools may subdivide internally if they map back deterministically.
|
|
|
|
Rationale:
|
|
|
|
- This gives `13` enough oracle structure without forcing one compiler pipeline.
|
|
|
|
## Questions To Resolve In The Room
|
|
|
|
1. Is phase plus stable class enough, or should v1 require diagnostic codes now?
|
|
2. Must every cross-file failure include more than one source location?
|
|
3. Should `linking` be a diagnostics phase name directly, or only a broader `resolution` bucket?
|
|
4. Are secondary spans purely optional, or mandatory for some classes such as conflicting imports?
|
|
5. What is the minimum conformance-friendly diagnostic payload that is still implementation-neutral?
|
|
|
|
## Expected Outputs
|
|
|
|
This workshop should produce:
|
|
|
|
1. a decision record for diagnostic identity,
|
|
2. a decision record for required attribution fields,
|
|
3. a cross-file attribution policy draft,
|
|
4. and a cleanup list for `11`.
|
|
|
|
## Explicit Deferrals For Workshop 2
|
|
|
|
- wording stability,
|
|
- notes/help obligations,
|
|
- warning policy,
|
|
- and backend-originated diagnostic mapping.
|
|
|
|
## Inputs
|
|
|
|
- `docs/pbs/specs/11. Diagnostics Specification.md`
|
|
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
|
- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
|
|
- `docs/pbs/agendas/11. Diagnostics Agenda.md`
|