prometeu-studio/docs/pbs/decisions/AST Diagnostics, Recovery, and Gate Evidence Decision.md

AST Diagnostics, Recovery, and Gate Evidence Decision

Status: Accepted
Date: 2026-03-05
Related Agenda: docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md

Context

After closing AST contract, declaration surfaces, and statement/expression surfaces, PBS needed to close AST-facing diagnostics and parser-recovery policy plus the minimum Gate U evidence baseline.

Additionally, localization policy needed explicit alignment: diagnostics wording is locale-dependent and should be keyed by stable message tokens/template ids.

Decision

PBS adopts the following AST diagnostics/recovery/evidence policy:

1. AST must preserve diagnostic fidelity:
   • required syntax diagnostics remain stable in code, severity, phase, primary file, and primary span.
2. Human-readable message text is locale/rendering-dependent and not a conformance identity key.
3. Stable diagnostics identity for i18n is carried by:
   • diagnostic code,
   • phase,
   • message template id (token),
   • and primary attribution.
4. Parser recovery is allowed to continue diagnostics, but recovered AST must remain structurally coherent and attribution-consistent.
5. Recovery must not fabricate permissive valid shapes that hide real syntax failures.
6. Gate U AST evidence must include:
   • representative valid AST fixtures,
   • malformed/recovery fixtures,
   • deterministic diagnostics assertions,
   • and attribution assertions (file/start/end) on required nodes.
7. Minimum mandatory negative fixture families include:
   • unexpected token in declaration context,
   • missing required closer (), }, or ;) as applicable,
   • non-associative forbidden chain forms,
   • unsupported form outside the active syntax slice with deterministic rejection.

Invariants

1. Diagnostics identity is token-based and locale-agnostic.
2. Recovery cannot downgrade a required rejection into accepted semantics.
3. AST attribution quality remains sufficient for 12 diagnostics contract and 13 lowering preconditions.
4. Gate U fixtures must lock rejection stability for required AST-facing failures.

Explicit Non-Decisions

1. This decision does not define transport-specific wire schemas.
2. This decision does not define static type-checking rules.
3. This decision does not define backend/runtime/verifier algorithms.
4. This decision does not require one exact localized wording set.

Spec Impact

1. docs/pbs/specs/11. AST Specification.md must encode recovery integrity and AST-facing rejection/recovery invariants.
2. docs/pbs/specs/12. Diagnostics Specification.md remains authority for diagnostics identity fields, including template/token identity.
3. docs/general/specs/13. Conformance Test Specification.md provides Gate U evidence obligations referenced here.

Validation Notes

Gate U validation should assert:

1. stable diagnostic identity keys (code, phase, template/token id, primary attribution),
2. recovery integrity without semantic masking,
3. deterministic results for the mandatory negative fixture families above.