65 lines
3.0 KiB
Markdown
65 lines
3.0 KiB
Markdown
# 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.
|