54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
---
|
|
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.
|