prometeu-studio/docs/pbs/agendas/11. AST Agenda.md

PBS AST Agenda

Status: Active

Purpose

Drive closure of 11. AST Specification.md as the frontend contract between parser output and IRBackend lowering input.

Context

PBS now has syntax and static-semantics rules, but AST needs a sharper normative boundary so implementations and tests stay aligned.

This agenda focuses on:

• required AST node families for v1 PBS,
• source-attribution invariants (file/start/end) in AST,
• parser recovery constraints,
• and Gate U evidence for AST behavior.

Scope Boundary

In scope:

• parser-produced AST contract,
• declaration/statement/expression shape obligations,
• source span and parent-child structural invariants,
• AST-facing deterministic rejection behavior.

Out of scope:

• full static semantics (owned by 4),
• IRBackend lowering contract details (owned by 13),
• VM/runtime/bytecode/verifier/loader concerns.

Decisions To Produce

1. Decide mandatory AST node families for v1 source surface.
2. Decide structural invariants for valid and recovered AST.
3. Decide attribution invariants required for diagnostics and lowering.
4. Decide deterministic parser/AST rejection and recovery boundaries.
5. Decide minimum Gate U fixture evidence for AST.

Core Questions

1. What is the minimum AST contract that all PBS frontends must expose?
2. Which syntax forms must have explicit node-level representation versus deterministic rejection?
3. What AST guarantees must hold even after parser recovery?
4. How strict must span/attribution fidelity be for conformance?
5. Which AST fixtures are mandatory to prevent regression?

Proposed Workshop Sequence

Workshop 1: AST Contract and Root Model

• root/file model,
• canonical node-family baseline,
• mandatory attribution fields.

Workshop 2: Declarations and Type Surfaces

• declaration node obligations,
• callable/type/const/module-level declaration shape,
• barrel/linking-facing declaration needs.

Workshop 3: Statements and Expressions

• statement/expression node obligations,
• precedence/associativity representation expectations,
• unsupported-form rejection boundaries.

Workshop 4: Diagnostics, Recovery, and Gate Evidence

• syntax-phase diagnostics attribution from AST,
• recovery invariants,
• Gate U fixture baseline for AST.

Expected Spec Material

The resulting 11 content should close:

• AST contract baseline,
• structural and attribution invariants,
• recovery/rejection rules,
• and test-evidence hooks for conformance.

Non-Goals

• Freezing one parser implementation architecture.
• Freezing backend/IRVM decisions.
• Replacing static semantics with AST rules.

Inputs

• docs/pbs/specs/3. Core Syntax Specification.md
• docs/pbs/specs/4. Static Semantics Specification.md
• docs/pbs/specs/11. AST Specification.md
• docs/pbs/specs/12. Diagnostics Specification.md
• docs/pbs/specs/13. Lowering IRBackend Specification.md
• docs/general/specs/13. Conformance Test Specification.md