bQUARKz
d7c2ec880f
Some checks are pending
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17766/28676)
* Branch Coverage: 52.69% (6860/13019)
* Lines of Code: 28676
* Cyclomatic Complexity: 11490
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 645
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Publish the language-versus-platform validation matrix in compiler-general specs, retitle spec 19, and recut PBS diagnostics so common structural failures are not PBS coverage. Housekeep DSC-0060 with LSN-0063.
299 lines
15 KiB
Markdown
299 lines
15 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/specs/compiler/15. Bytecode and PBX Mapping Specification.md`
|
|
- `docs/specs/compiler/16. Runtime Execution and Initialization Specification.md`
|
|
- `docs/specs/compiler/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.
|
|
- PBS requires deterministic diagnostics for source-form globals, lifecycle markers, and init admission.
|
|
- Published-wrapper, boot-guard, synthetic-origin, and invalid-lifecycle-declaration failures are compiler-general. See `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
|
|
|
## 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.
|
|
|
|
The `host-binding/capability admission` phase covers the source shape of `[Host]` and `[Capability]`. Canonical host-binding identity and capability consistency over `IRReservedMetadata` are platform-owned and are not moved by this specification.
|
|
|
|
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.
|
|
8. lifecycle-marker and source-form global diagnostics, including:
|
|
- `global initializer uses unsupported form`,
|
|
- `global dependency cycle detected`,
|
|
- `global import must resolve through a global barrel entry`,
|
|
- `imported symbol shadows existing visible symbol; alias required`,
|
|
- `init function must have signature fn name() -> void`,
|
|
- `frame function must have signature fn name() -> void`,
|
|
- `multiple module init functions detected`,
|
|
- `multiple project init functions detected`,
|
|
- `multiple frame functions detected`,
|
|
- `missing frame function for executable project`,
|
|
- `project init must be colocated with frame`,
|
|
- `Init attribute target invalid`,
|
|
- `InitAllowed is valid only on SDK host methods`,
|
|
- `host call not allowed during init`.
|
|
9. compiler-general lifecycle-assembly and IRVM-precondition failures, which this PBS catalog MUST NOT claim as PBS required coverage; see `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
|
10. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
|
|
- unresolved terminal asset reference,
|
|
- namespace-versus-terminal asset misuse,
|
|
- structurally invalid symbolic asset path admitted by source syntax but rejected by semantic surface rules.
|
|
11. ignored-value diagnostics for expression statements, including:
|
|
- a stable warning when a materialized value is produced and then ignored,
|
|
- and no warning for unit-like expression statements.
|
|
|
|
Reserved-attribute diagnostics for host-backed asset lowering must also cover:
|
|
|
|
- duplicate `AssetLowering` declarations on the same host signature,
|
|
- missing or malformed `AssetLowering(param = N)` arguments,
|
|
- out-of-range `AssetLowering.param` indexes,
|
|
- and `AssetLowering` targets whose selected parameter is not statically typed as `Addressable`.
|
|
|
|
Documentation attribute diagnostics must cover:
|
|
|
|
- unterminated documentation text block syntax,
|
|
- `Doc` used without the required `markdown` argument,
|
|
- `Doc` with extra or unknown arguments,
|
|
- `Doc` with a non-documentation-text-block payload,
|
|
- duplicate `Doc` on the same declaration,
|
|
- `Doc` applied to a parameter or other non-documentable surface,
|
|
- normalized empty or whitespace-only documentation payload,
|
|
- and rejected aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
|
|
|
|
Diagnostics for duplicate `Doc` attributes must be static semantic diagnostics and should include a related site for the conflicting declaration attribute when available.
|
|
|
|
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.
|
|
|
|
For backend-owned symbolic asset surfaces:
|
|
|
|
- diagnostics SHOULD point primarily to the symbolic reference site in source;
|
|
- the frontend MAY use backend-provided surface context to improve earlier diagnostics;
|
|
- backend ownership of final validation does not remove the requirement for deterministic source-facing diagnostics when validation fails.
|
|
|
|
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 in v1, and one warning is mandatory for PBS core: ignored materialized values in expression statements.
|
|
|
|
The mandatory warning identity for this rule is `W_SEM_IGNORED_VALUE`.
|
|
|
|
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.
|