prometeu-studio/docs/pbs/specs/11. Diagnostics Specification.md

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.