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

PBS Diagnostics Specification

Status: Draft v0 (Skeleton)
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, lowering boundaries, and related load-facing validation surfaces

1. Purpose

This document will define the PBS diagnostics contract.

Its purpose is to make diagnostics stable enough that:

• conforming tools report failures in the same places,
• users receive deterministic and actionable feedback,
• conformance can validate not only acceptance/rejection but also diagnostic class and location,
• frontend, manifest, and load-facing validation remain aligned.

2. Scope

This document is intended to define:

• diagnostic categories and phases,
• minimum metadata carried by diagnostics,
• stability expectations for source spans, file attribution, and phase attribution,
• the normative relationship between syntax/static diagnostics and later lowering/load diagnostics,
• which diagnostics are required versus implementation-defined enrichments,
• cost-visibility diagnostics or warnings once memory/effect decisions are closed.

This document does not define:

• the full runtime trap catalog,
• UI presentation or IDE styling,
• implementation-specific hint ranking,
• profiling output 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

This document will also depend on decisions closed in:

• 9. Dynamic Semantics Specification.md
• 10. Memory and Lifetime Specification.md
• the future backend agenda sequence tracked in docs/agendas/

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.

6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. diagnostic phases,
2. required diagnostic metadata,
3. span and file attribution,
4. syntax-diagnostic contract,
5. static-diagnostic contract,
6. manifest/import-resolution diagnostics,
7. lowering and host-binding diagnostics,
8. load-facing and capability diagnostics,
9. cost-visibility diagnostics and warnings.

7. A Ver

The following items remain to be closed before this document can be considered complete.

7.1 Depends on 9. Dynamic Semantics Specification.md

• Which runtime-observable trap categories need source-facing compile-time or conformance hooks.
• Which constructs require special diagnostics for abrupt completion, propagation, or effect misuse beyond what static semantics already lists.

7.2 Depends on 10. Memory and Lifetime Specification.md

• Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings.
• Which cost facts are mandatory versus implementation-defined enrichment.

7.3 Depends on the future backend agenda sequence tracked in docs/agendas/

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

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

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

9. Exit Criteria

This document is ready to move beyond skeleton 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 aligned with memory/effect specs,
4. the document no longer relies on unresolved backend and runtime-facing A Ver items for v1 tooling behavior.