# AST Diagnostics, Recovery, and Gate Evidence Decision

Status: Accepted  
Date: 2026-03-05  
Related Agenda: `docs/pbs/agendas/archive/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.