---
id: LSN-0018
ticket: pbs-learn-to-discussion-lessons-migration
title: PBS AST and Parser Contract Legacy Import
created: 2026-03-27
tags: [compiler, pbs, legacy-import, ast, parser, diagnostics]
---

## Context

Legacy import from `docs/compiler/pbs/learn/01. AST and Parser Contract.md`.

This lesson preserves the durable parser-facing contract that remained after the PBS workflow prune.
It records what later phases are allowed to assume about AST structure without freezing one parser implementation strategy.

## Key Decisions

### Obligations-first AST contract

**What:** PBS standardizes observable AST obligations rather than one mandatory in-memory representation.

**Why:** Downstream phases need deterministic structure and attribution, but the repository does not want to lock parser architecture or implementation language.

**Trade-offs:** The contract is flexible for implementation, but it requires strong conformance discipline around spans, node families, and rejection behavior.

### Recovery must preserve structural honesty

**What:** Parser recovery is allowed only when the recovered AST remains structurally coherent and attribution-safe.

**Why:** Recovery exists to keep diagnostics useful, not to hide invalid syntax behind permissive fake trees.

**Trade-offs:** This makes parser implementations slightly stricter, but it prevents later phases from operating on misleading AST shapes.

## Patterns and Algorithms

- Treat AST as a structural boundary, not a semantic one.
- Preserve declaration identity instead of collapsing overloads or rewriting source-observable parse outcomes.
- Make precedence and associativity visible in AST shape, because they are part of the user-observable contract.
- Require stable source attribution on every node that diagnostics or lowering may consume.
- Keep diagnostic identity locale-agnostic; wording is not the conformance key.

## Pitfalls

- Rewriting AST after parse in a way that changes observable parse meaning.
- Allowing recovery to downgrade a required rejection into an accepted semantic shape.
- Emitting nodes without enough attribution for diagnostics or lowering.
- Treating localized message strings as conformance identity.

## Takeaways

- PBS AST is standardized by obligations, not by one exact object model.
- Parser recovery is acceptable only when it stays structurally honest.
- Attribution and deterministic rejection are first-class parser contracts, not secondary details.