prometeu-studio/docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md

Diagnostics and Conformance Governance

Original Problem

PBS accumulated several governance decisions around:

• diagnostic identity,
• artifact-facing conformance,
• claim publication,
• compatibility matrices,
• runtime-backed gates,
• optimization-stage obligations,
• and late closure of diagnostics and conformance evidence.

Much of that work later moved into general compiler specs, which made the local PBS decisions useful as history but redundant as active workflow artifacts.

Consolidated Decision

The durable PBS lesson is:

1. Diagnostics must be stable by identity, not by prose wording.
2. Evidence must be executable, not rhetorical.
3. Published support claims require maintained proof.
4. Artifact-level obligations matter only where the selected claim level requires them.
5. Once a cross-language general spec becomes the normative owner, local PBS decision records should stop acting as the live policy surface.

Final Model

Today the normative owner for most of this policy is outside docs/compiler/pbs/:

• conformance baselines,
• compatibility publication,
• verification and safety checks,
• and broad backend claim policy

now live in general compiler specs.

PBS still keeps domain-specific learnings:

• diagnostics identity must remain deterministic,
• evidence must track the actual claim scope,
• and claim rescoping must be explicit rather than silently drifting.

That is especially important for SPAWN and YIELD: the honest policy was to rescope them out of core-v1, not to leave ambiguous “deferred” support language hanging around.

Practical Consequences

1. Prefer the general compiler specs when updating policy.
2. Use PBS-local docs only for PBS-specific deltas or examples.
3. Keep conformance rows, tests, and published claims aligned.
4. Treat superseded local decisions as historical input, not as live normative authority.

Common Pitfalls

• Keeping superseded local policy docs as if they still owned the contract.
• Publishing claims without executable evidence.
• Letting matrix/support language drift away from what the backend actually implements.
• Leaving rescope decisions implicit instead of explicit.

Source Decisions

• Diagnostics Contract Decision.md
• Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md
• IRVM Optimization Stage Placement Decision.md
• SPAWN-YIELD v1 Claim Rescope Decision.md
• Artifact-Level Conformance and Fixture Model Decision.md (superseded)
• Compatibility Matrix and Published Claims Decision.md (superseded)
• Conformance Claim Levels Decision.md (superseded)