134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# PBS Diagnostics Specification
|
|
|
|
Status: Draft v0 (Skeleton)
|
|
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, lowering boundaries, and related load-facing validation surfaces
|
|
|
|
## 1. Purpose
|
|
|
|
This document will define the PBS diagnostics contract.
|
|
|
|
Its purpose is to make diagnostics stable enough that:
|
|
|
|
- conforming tools report failures in the same places,
|
|
- users receive deterministic and actionable feedback,
|
|
- conformance can validate not only acceptance/rejection but also diagnostic class and location,
|
|
- frontend, manifest, and load-facing validation remain aligned.
|
|
|
|
## 2. Scope
|
|
|
|
This document is intended to define:
|
|
|
|
- diagnostic categories and phases,
|
|
- minimum metadata carried by diagnostics,
|
|
- stability expectations for source spans, file attribution, and phase attribution,
|
|
- the normative relationship between syntax/static diagnostics and later lowering/load diagnostics,
|
|
- which diagnostics are required versus implementation-defined enrichments,
|
|
- cost-visibility diagnostics or warnings once memory/effect decisions are closed.
|
|
|
|
This document does not define:
|
|
|
|
- the full runtime trap catalog,
|
|
- UI presentation or IDE styling,
|
|
- implementation-specific hint ranking,
|
|
- profiling output formats.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. `1. Language Charter.md`
|
|
2. `3. Core Syntax Specification.md`
|
|
3. `4. Static Semantics Specification.md`
|
|
4. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
6. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
7. `9. Dynamic Semantics Specification.md`
|
|
8. `10. Memory and Lifetime Specification.md`
|
|
9. `12. IR and Lowering Specification.md`
|
|
10. This document
|
|
|
|
If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `3. Core Syntax Specification.md`
|
|
- `4. Static Semantics Specification.md`
|
|
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
|
|
This document will also depend on decisions closed in:
|
|
|
|
- `9. Dynamic Semantics Specification.md`
|
|
- `10. Memory and Lifetime Specification.md`
|
|
- the future backend agenda sequence tracked in `docs/agendas/`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- The syntax specification already enumerates minimum required syntax diagnostics.
|
|
- The static semantics specification already enumerates minimum required static diagnostics.
|
|
- Manifest/import resolution failures are required to be deterministic compile-time errors.
|
|
- Loader failures around malformed or unauthorized host usage are required to be deterministic.
|
|
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
|
|
|
## 6. Initial Section Targets
|
|
|
|
At minimum, the completed document should contain normative sections for:
|
|
|
|
1. diagnostic phases,
|
|
2. required diagnostic metadata,
|
|
3. span and file attribution,
|
|
4. syntax-diagnostic contract,
|
|
5. static-diagnostic contract,
|
|
6. manifest/import-resolution diagnostics,
|
|
7. lowering and host-binding diagnostics,
|
|
8. load-facing and capability diagnostics,
|
|
9. cost-visibility diagnostics and warnings.
|
|
|
|
## 7. A Ver
|
|
|
|
The following items remain to be closed before this document can be considered complete.
|
|
|
|
### 7.1 Depends on `9. Dynamic Semantics Specification.md`
|
|
|
|
- Which runtime-observable trap categories need source-facing compile-time or conformance hooks.
|
|
- Which constructs require special diagnostics for abrupt completion, propagation, or effect misuse beyond what static semantics already lists.
|
|
|
|
### 7.2 Depends on `10. Memory and Lifetime Specification.md`
|
|
|
|
- Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings.
|
|
- Which cost facts are mandatory versus implementation-defined enrichment.
|
|
|
|
### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`
|
|
|
|
- Whether diagnostic stability includes IR/lowering phase names, artifact offsets, or source maps.
|
|
- How host-binding lowering failures are surfaced back to source locations.
|
|
- Whether verifier/load diagnostics are part of the PBS diagnostics contract directly or only through artifact-facing tooling.
|
|
|
|
### 7.4 Still to decide inside this document
|
|
|
|
- Whether diagnostic codes are mandatory in v1.
|
|
- Which portions of human-readable wording are normative versus illustrative.
|
|
- Whether notes/help text are required, optional, or outside conformance.
|
|
- Exact cross-file diagnostic expectations for module/barrel/import failures.
|
|
|
|
## 8. Non-Goals
|
|
|
|
- Mandating one UI or IDE presentation style.
|
|
- Freezing a localization strategy in this pass.
|
|
- Turning every optimization hint into a normative diagnostic.
|
|
- Replacing the acceptance/rejection rules already defined elsewhere.
|
|
|
|
## 9. Exit Criteria
|
|
|
|
This document is ready to move beyond skeleton status only when:
|
|
|
|
1. every required rejection in the current spec set is mapped to a diagnostic phase,
|
|
2. diagnostic metadata and attribution rules are explicit enough for conformance,
|
|
3. cost-visibility expectations are aligned with memory/effect specs,
|
|
4. the document no longer relies on unresolved backend and runtime-facing `A Ver` items for v1 tooling behavior.
|