prometeu-studio/docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md

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