prometeu-studio/docs/compiler/pbs/specs/12. Diagnostics Specification.md

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.