244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
# PBS Diagnostics Specification
|
|
|
|
Status: Draft v1
|
|
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, linking, host-admission checks, and load-facing validation surfaces
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the 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,
|
|
- diagnostics remain machine-identifiable even when rendered in different locales,
|
|
- conformance can validate rejection class and attribution,
|
|
- and frontend, linking, manifest, and load-facing validation remain aligned.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- the required external diagnostic phases,
|
|
- the minimum machine-readable identity of a PBS-facing diagnostic,
|
|
- the minimum source-facing payload and attribution baseline,
|
|
- the boundary between normative diagnostic fields and implementation-defined rendering,
|
|
- the boundary between PBS-facing diagnostics and artifact/tooling failures,
|
|
- and the warning/cost-diagnostics boundary for v1.
|
|
|
|
This document does not define:
|
|
|
|
- a full runtime trap catalog,
|
|
- UI presentation or IDE styling,
|
|
- one exact localized sentence for every diagnostic,
|
|
- one transport-specific schema such as LSP field mapping,
|
|
- one standardized source-map or artifact-offset format,
|
|
- 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. `13. Lowering IRBackend 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`
|
|
- `13. Lowering IRBackend Specification.md`
|
|
|
|
Relevant backend-facing integration points also include:
|
|
|
|
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
|
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
|
|
- `docs/general/specs/19. Verification and Safety Checks 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
|
|
|
|
PBS-facing tooling must distinguish at least the following external diagnostic phases:
|
|
|
|
1. `syntax`,
|
|
2. `static semantics`,
|
|
3. `manifest/import resolution`,
|
|
4. `linking`,
|
|
5. `host-binding/capability admission`,
|
|
6. `load-facing rejection` when directly attributable to malformed or unauthorized PBS-facing artifact usage.
|
|
|
|
`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.
|
|
|
|
This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.
|
|
|
|
## 7. Required Diagnostic Identity, Payload, and Attribution
|
|
|
|
Every PBS-facing diagnostic must expose a stable machine-readable identity.
|
|
|
|
At minimum, every required source-facing diagnostic must include:
|
|
|
|
1. `diagnostic code`,
|
|
2. `severity`,
|
|
3. `phase`,
|
|
4. `primary file`,
|
|
5. `primary span/location`,
|
|
6. `message template id`,
|
|
7. stable named placeholders for that template when applicable,
|
|
8. and a rendered human-readable message.
|
|
|
|
The stable identity of a diagnostic is carried primarily by:
|
|
|
|
- `diagnostic code`,
|
|
- stable phase attribution,
|
|
- `message template id`,
|
|
- primary attribution,
|
|
- and the rejection-class semantics represented by the code/template pair.
|
|
|
|
Human wording alone is not the identity of the diagnostic.
|
|
|
|
Conformance assertions must key diagnostics by stable machine fields (`code`, `phase`, `message template id`, attribution), not by localized rendered sentence text.
|
|
|
|
## 8. Cross-File Attribution, Notes, and Hint Surface
|
|
|
|
Cross-file attribution follows an action-first rule.
|
|
|
|
Rules:
|
|
|
|
- import failures must point primarily to the importing site,
|
|
- barrel failures must point primarily to the barrel site or entry that triggered the failure,
|
|
- linking and cross-module lookup failures must point primarily to the use or reference site that could not be resolved,
|
|
- related sites may be attached when known,
|
|
- and `duplicate` or `conflict` diagnostics must include at least one related site.
|
|
|
|
`notes` are optional by default in v1 except where another rule explicitly requires related-location reporting.
|
|
|
|
The stable visible categories currently reserved are:
|
|
|
|
- `error`,
|
|
- `warning`,
|
|
- `note`,
|
|
- `hint`.
|
|
|
|
`hint` is part of the diagnostics model in v1, but hint content is not mandatory.
|
|
|
|
## 9. Wording, Templates, and Localization
|
|
|
|
Rendered wording does not need to be byte-for-byte identical across implementations or locales.
|
|
|
|
However:
|
|
|
|
- the rendered message must preserve the same normative rejection meaning,
|
|
- the rendered message must not contradict the governing spec rule,
|
|
- and the code/template/placeholder contract must remain stable.
|
|
|
|
This allows implementations to localize diagnostics while preserving conformance-friendly identity.
|
|
|
|
Human-readable messages may be rendered from locale-specific templates, but template/token identity remains stable across locales.
|
|
|
|
Implementations should preserve the ability to render an English default or fallback message for future interoperability-oriented transports such as a possible LSP integration, even when the local product surface renders another language by default.
|
|
|
|
Examples in this specification are illustrative unless explicitly marked normative.
|
|
|
|
`help` or guided remediation is outside the minimum mandatory contract in v1.
|
|
|
|
## 10. Required Diagnostic Coverage and Backend-Originated Failures
|
|
|
|
At minimum, the PBS 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. linking failures required by source-level name-resolution and module-linking rules,
|
|
5. 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`,
|
|
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
|
|
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
|
|
|
|
At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.
|
|
|
|
Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.
|
|
|
|
This means:
|
|
|
|
- lowering failures remain in scope when they reflect a normative source-facing lowering rule or impossibility,
|
|
- verifier or loader failures remain in scope when they are directly attributable to malformed or unauthorized PBS-facing artifact usage already within the PBS contract,
|
|
- and purely internal compiler exceptions, artifact corruption, or backend-internal failures with no stable user-facing source attribution remain outside the PBS-facing diagnostics contract.
|
|
|
|
When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.
|
|
|
|
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.
|
|
|
|
Dependency-scoped fail-fast admission is not equivalent to global build abort.
|
|
When failures exist, implementations must still preserve deterministic diagnostic identity and attribution for unaffected independent modules processed in the same build.
|
|
|
|
## 11. Cost Diagnostics and Warning Policy
|
|
|
|
Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline.
|
|
|
|
Tooling may surface qualitative cost facts as warnings or notes, especially for:
|
|
|
|
- retention-bearing `bind`,
|
|
- observable copy-versus-alias semantics,
|
|
- and host-boundary crossings.
|
|
|
|
The choice between `warning` and `note` is implementation-defined in v1.
|
|
|
|
This document does not make a detailed warning taxonomy normative and does not require a warning at every such site.
|
|
|
|
Quantitative metrics such as exact byte counts, exact allocation counts, collector timing, or performance ranking remain outside the diagnostics contract and belong to profiling/tooling rather than to language conformance.
|
|
|
|
## 12. Current Limits
|
|
|
|
The v1 diagnostics contract intentionally leaves the following items outside the currently standardized surface:
|
|
|
|
- transport-specific wire formats,
|
|
- one exact source-map format,
|
|
- one exact verifier/loader internal reporting shape,
|
|
- one mandatory warning catalog,
|
|
- and one mandatory remediation/help-content policy.
|
|
|
|
These are not licenses to weaken the required external fields defined above.
|
|
|
|
## 13. Non-Goals
|
|
|
|
- Mandating one UI or IDE presentation style.
|
|
- Freezing one exact localization strategy or locale set.
|
|
- Turning every optimization hint into a normative diagnostic.
|
|
- Replacing the acceptance/rejection rules already defined elsewhere.
|
|
- Standardizing profiler output as if it were language law.
|
|
|
|
## 14. 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 identity, metadata, and attribution rules are explicit enough for conformance, including locale-agnostic token/template identity,
|
|
3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures,
|
|
4. and cost/warning expectations are explicit where they are intended to be normative for v1.
|