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?

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