160 lines
6.9 KiB
Markdown
160 lines
6.9 KiB
Markdown
# PBS Diagnostics Specification
|
|
|
|
Status: Draft v1 (Temporary)
|
|
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, and load-facing validation surfaces
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the current PBS diagnostics baseline for v1.
|
|
|
|
Its purpose is to make diagnostics stable enough that:
|
|
|
|
- conforming tools report failures in the same phases,
|
|
- users receive deterministic and actionable source-facing feedback,
|
|
- conformance can validate rejection class and attribution,
|
|
- and frontend, manifest, and load-facing validation remain aligned.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- the current required diagnostic phases,
|
|
- the minimum source-facing attribution baseline,
|
|
- the relationship between higher-precedence rejection rules and diagnostics,
|
|
- and the current limits of v1 diagnostics while lowering and artifact-facing specs remain incomplete.
|
|
|
|
This document does not define:
|
|
|
|
- a full runtime trap catalog,
|
|
- UI presentation or IDE styling,
|
|
- one localization strategy,
|
|
- one diagnostics-code namespace,
|
|
- or profiling/reporting 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`
|
|
- `9. Dynamic Semantics Specification.md`
|
|
- `10. Memory and Lifetime Specification.md`
|
|
|
|
Later expansion of this document will also depend on:
|
|
|
|
- `12. IR and Lowering Specification.md`
|
|
- `15. Bytecode and PBX Mapping Specification.md`
|
|
- `16. Runtime Execution and Initialization Specification.md`
|
|
|
|
## 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.
|
|
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
|
|
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
|
|
|
|
## 6. Required Diagnostic Phases
|
|
|
|
At the current v1 baseline, PBS-facing tooling must distinguish at least the following diagnostic phases:
|
|
|
|
1. syntax,
|
|
2. static semantics,
|
|
3. manifest and import resolution,
|
|
4. host-binding and capability admission,
|
|
5. load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage.
|
|
|
|
This document does not yet require a finer-grained normative phase split for lowering, verifier, or artifact diagnostics. That remains open until the corresponding backend-facing specs are closed.
|
|
|
|
## 7. Minimum Diagnostic Attribution
|
|
|
|
For every required source-facing rejection that is attributable to source text, tooling must provide diagnostics with at least:
|
|
|
|
1. deterministic phase attribution,
|
|
2. primary file attribution,
|
|
3. a useful primary source span or location,
|
|
4. and enough human-readable content to distinguish the rejection class.
|
|
|
|
This document does not yet require one normalized diagnostics-code system or one fixed human wording template.
|
|
|
|
## 8. Required Diagnostic Coverage
|
|
|
|
At minimum, the current diagnostics baseline must cover:
|
|
|
|
1. syntax errors already required by `3. Core Syntax Specification.md`,
|
|
2. static-semantics errors already required by `4. Static Semantics Specification.md`,
|
|
3. deterministic manifest and import-resolution failures required by `5. Manifest, Stdlib, and SDK Resolution Specification.md`,
|
|
4. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`.
|
|
|
|
Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap.
|
|
|
|
## 9. Cost and Runtime-Facing Diagnostics
|
|
|
|
The current baseline is intentionally narrow.
|
|
|
|
Tooling may surface cost-visibility notes or warnings around facts such as:
|
|
|
|
- retention-bearing `bind`,
|
|
- observable copy-versus-alias semantics,
|
|
- and host-boundary crossings.
|
|
|
|
However, this document does not yet make a detailed warning taxonomy normative. Quantitative metrics, exact ranking, and profiling detail remain implementation-defined.
|
|
|
|
## 10. TODO
|
|
|
|
The following items remain to be closed before this document can be considered complete:
|
|
|
|
### 10.1 Depends on later closure of backend-facing specs
|
|
|
|
- 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.
|
|
|
|
### 10.2 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;
|
|
- which qualitative cost warnings, if any, become mandatory rather than optional tooling enrichment.
|
|
|
|
## 11. 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.
|
|
|
|
## 12. Exit Criteria
|
|
|
|
This document is ready to move beyond temporary 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 explicit where they are intended to be normative,
|
|
4. and the document no longer relies on unresolved backend- and runtime-facing TODO items for v1 tooling behavior.
|