prometeu-studio/docs/pbs/agendas/12. IR and Lowering Agenda.md

PBS IR and Lowering Agenda

Status: Active

Purpose

Drive the decisions needed to turn 12. IR and Lowering Specification.md from a skeleton into a normative lowering contract that can guide implementation.

Context

The language now has substantial source-level semantics, but lowering still lacks closure around:

• which semantic obligations IR must preserve,
• whether one canonical IR shape is normative,
• how core constructs map into lowered control flow and data flow,
• how services, contracts, callbacks, tuples, optional, and result lower,
• and which invariants belong in lowering versus PBX/bytecode mapping.

This agenda should keep the focus on semantic preservation and artifact obligations, not on one compiler's class hierarchy.

Decisions To Produce

1. Decide the normative status of IR: canonical IR, canonical obligations only, or hybrid.
2. Decide the required lowering preconditions after parsing, resolution, and type checking.
3. Decide the lowered forms required for expressions, control flow, abrupt completion, and propagation.
4. Decide the lowering story for callbacks, services, contracts, tuples, optional, and result.
5. Decide the boundary between this spec and 15. Bytecode and PBX Mapping Specification.md.
6. Decide the artifact invariants that must hold before verifier or loader stages.

Core Questions

1. Which evaluation-order guarantees from dynamic semantics must be explicit in lowered form?
2. Which memory and identity facts must remain explicit through IR rather than inferred later?
3. Do callback formation and contract dispatch need dedicated runtime artifacts or only preserved semantic obligations?
4. What is the minimal lowering model for builtin projections, builtin constants, and intrinsic member calls beyond what is already fixed?
5. Which host-binding failures are lowering failures versus later verifier or loader failures?

Proposed Workshop Sequence

Workshop 1: Lowering Contract and IR Status

Purpose:

• decide whether PBS standardizes one canonical IR or only preserved obligations,
• and close lowering preconditions after parsing, resolution, and type checking.

Expected decisions:

• canonical IR versus obligations-only model,
• required bound-program inputs,
• and minimal preserved semantic facts.

Workshop 2: Control Flow, Evaluation Order, and Propagation

Purpose:

• close the lowering model for expressions, branching, abrupt completion, optional, and result.

Expected decisions:

• explicit evaluation-order preservation,
• lowered forms for else, !, and handle,
• and trap versus propagation boundaries.

Workshop 3: Callables, Services, Contracts, and Callbacks

Purpose:

• close the lowering story for callable categories beyond ordinary top-level functions.

Expected decisions:

• callback formation model,
• service and contract dispatch shape,
• and runtime-artifact obligations for callable categories.

Workshop 4: Builtins, Host Bindings, and Artifact Invariants

Purpose:

• close builtin lowering, host-binding emission, and the invariants required before verifier and loader stages.

Expected decisions:

• builtin projection and intrinsic lowering obligations,
• host-binding emission boundary versus PBX mapping,
• and artifact invariants consumed by 15 and 19.

Expected Spec Material

The resulting spec work should be able to add or close sections for:

• lowering preconditions,
• preserved semantic obligations,
• control-flow lowering,
• callable lowering by category,
• tuple, optional, and result lowering,
• callback, service, and contract lowering,
• builtin and host-binding lowering,
• artifact invariants before PBX emission,
• and source-to-artifact trace hooks consumed by diagnostics and conformance.

Non-Goals

• Freezing optimizer internals.
• Freezing one in-memory compiler IR data model.
• Repeating the bytecode ISA.
• Defining loader patching internals.
• Designing performance heuristics.

Inputs

• docs/pbs/specs/4. Static Semantics Specification.md
• docs/pbs/specs/6. VM-owned vs Host-backed.md
• docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md
• docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md
• docs/pbs/specs/9. Dynamic Semantics Specification.md
• docs/pbs/specs/10. Memory and Lifetime Specification.md
• docs/pbs/specs/12. IR and Lowering Specification.md
• docs/pbs/specs/14. Name Resolution and Module Linking Specification.md
• docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md
• docs/pbs/specs/16. Runtime Execution and Initialization Specification.md