# 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.