# 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`
- `docs/pbs/agendas/14.4. Name Resolution Workshop 4 - Linking Phase Boundary.md`