prometeu-studio/docs/pbs/agendas/archive/11.1. AST Workshop 1 - AST Contract and Root Model.md

PBS AST Workshop 1

Status: Closed (2026-03-05)

Purpose

Close the top-level AST contract for 11. AST Specification.md:

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

Decisions To Produce

1. Root/file node contract and per-file AST boundary.
2. Mandatory attribution fields on AST nodes (file/start/end).
3. Which families are mandatory in v1 AST (declaration/statement/expression categories).
4. Contract status: obligations-based versus one mandatory in-memory class hierarchy.

Candidate Decisions

1. Obligations-First AST Contract

• Spec defines required observable AST obligations.
• Internal object model remains implementation-defined.

2. Attribution Is Mandatory

• Nodes consumed by diagnostics or lowering must carry stable source attribution.
• Missing attribution on mandatory nodes is non-conformant.

3. Root Boundary Is Per Source File

• Parser output is one root per file.
• Root must preserve deterministic child ordering.

Questions To Resolve

1. Which minimal node families are required immediately for v1 conformance?
2. Which optional node metadata may remain implementation-defined for now?
3. What is the minimum integrity rule for recovered AST after parse errors?

Expected Outputs

1. Decision note on AST contract model.
2. Decision note on attribution minimums.
3. Section targets for 11. AST Specification.md.

Decision Outcome (2026-03-05)

Decision record: docs/pbs/decisions/AST Contract and Root Model Decision.md.

1. 11 standardizes AST by observable obligations, not by one mandatory Java/in-memory class hierarchy.
2. AST root boundary is one root per source file with deterministic child order.
3. Nodes consumed by diagnostics or lowering must carry file/start/end.
4. Mandatory v1 families are declaration/statement/expression categories for the supported source slice.
5. Unsupported forms are deterministic reject and must not be masked by permissive synthetic AST.

Inputs

• docs/pbs/specs/3. Core Syntax Specification.md
• docs/pbs/specs/11. AST Specification.md
• docs/pbs/specs/12. Diagnostics Specification.md
• docs/pbs/agendas/archive/11. AST Agenda.md