# AST Declarations and Type Surfaces Decision

Status: Accepted  
Date: 2026-03-05  
Related Agenda: `docs/pbs/agendas/archive/11.2. AST Workshop 2 - Declarations and Type Surfaces.md`

## Context

After closing the AST contract/root model, PBS needed a precise declaration-layer AST decision for v1 so parser output, diagnostics, and IRBackend lowering remain aligned.

The open points were:

- mandatory declaration families in AST,
- declaration identity preservation,
- declaration metadata requirements for downstream phases,
- AST/static-semantics phase boundary,
- rejection and recovery behavior for malformed declarations,
- and minimum Gate U evidence.

## Decision

PBS adopts the following declaration/type-surface AST policy for v1:

1. Mandatory declaration families include:
   - imports,
   - top-level `fn`,
   - `struct`, `contract`, `service`, `error`, `enum`, `callback`,
   - `declare const`,
   - and declaration nodes required by barrel/linking flow.
2. Declaration identity is preserved at AST boundary; implementations must not prematurely merge declarations (including overload sets).
3. Minimum declaration metadata includes:
   - declaration name,
   - declared signature/surface (parameters/return when applicable),
   - stable source attribution (`file/start/end`),
   - and required declaration-level syntactic flags/attributes needed by later phases.
4. AST/static boundary is explicit:
   - AST preserves structure,
   - static/linking phases own semantic compatibility and resolution rules.
5. Unsupported declaration forms are deterministic parser/AST rejection with stable diagnostics.
6. Recovery may continue after declaration syntax errors, but recovered AST must remain structurally coherent and attribution-consistent.
7. Gate U evidence must include positive and negative declaration fixtures with AST-shape, attribution, and diagnostics assertions.

## Invariants

1. Declaration AST remains obligations-first and implementation-language agnostic.
2. Overload identity is not collapsed at AST layer.
3. Missing required declaration metadata on mandatory nodes is non-conformant.
4. Recovery must not fabricate permissive declaration shapes that hide syntax failures.

## Explicit Non-Decisions

1. This decision does not define static type-checking algorithms.
2. This decision does not define lowering from `IRBackend` to `IRVM`.
3. This decision does not define runtime/bytecode/verifier policy.
4. This decision does not freeze one parser architecture.

## Spec Impact

1. `docs/pbs/specs/11. AST Specification.md` must encode declaration families, identity preservation, metadata minimums, and recovery/rejection invariants.
2. `docs/pbs/specs/12. Diagnostics Specification.md` remains authority for diagnostic identity/phase/attribution semantics consumed by declaration diagnostics.
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md` may assume declaration metadata invariants as lowering preconditions.

## Validation Notes

Gate U evidence (per `docs/general/specs/13. Conformance Test Specification.md`) should include:

1. valid declaration fixtures for each mandatory family,
2. malformed declaration fixtures with deterministic rejection diagnostics,
3. AST assertions for declaration identity, spans, and required metadata fields.
