prometeu-studio/docs/pbs/specs/12. IR and Lowering Specification.md

PBS IR and Lowering Specification

Status: Draft v0 (Skeleton)
Applies to: lowering of bound PBS programs into internal compiler IR and runtime-facing artifacts

1. Purpose

This document will define the normative lowering contract from PBS source semantics to implementation artifacts.

Its purpose is to make backend-facing behavior explicit enough that:

• different compilers lower the same bound program compatibly,
• host-binding emission does not drift from frontend resolution,
• builtin and intrinsic lowering does not drift from VM-owned metadata,
• later verifier and loader behavior can rely on stable artifact expectations,
• conformance can test more than parser and binder behavior.

2. Scope

This document is intended to define:

• the minimum semantic obligations of the compiler after parsing, binding, and type checking,
• the role of internal IR as an implementation stage,
• what semantic facts lowering must preserve,
• lowering of control flow, calls, callbacks, services, contracts, constants, and host-backed calls,
• lowering of builtin projections, builtin constants, and intrinsic member calls,
• artifact-facing requirements that must hold before loader/verifier consumption.

This document does not define:

• the full PBX binary layout,
• optimizer heuristics or performance tuning strategy,
• the exact in-memory data structures of one compiler implementation,
• runtime GC algorithm internals.

3. Authority and Precedence

Normative precedence:

1. Runtime authority (docs/specs/hardware/topics/chapter-2.md, chapter-3.md, chapter-9.md, chapter-12.md, chapter-16.md)
2. Bytecode authority (docs/specs/bytecode/ISA_CORE.md)
3. 3. Core Syntax Specification.md
4. 4. Static Semantics Specification.md
5. 5. Manifest, Stdlib, and SDK Resolution Specification.md
6. 6. VM-owned vs Host-backed.md
7. 6.1. Intrinsics and Builtin Types Specification.md
8. 6.2. Host ABI Binding and Loader Resolution Specification.md
9. 9. Dynamic Semantics Specification.md
10. 10. Memory and Lifetime Specification.md
11. This document

If a lowering rule here contradicts a higher-precedence semantic rule, the higher-precedence rule wins.

4. Normative Inputs

This document depends on, at minimum:

• 3. Core Syntax Specification.md
• 4. Static Semantics Specification.md
• 5. Manifest, Stdlib, and SDK Resolution Specification.md
• 6. VM-owned vs Host-backed.md
• 6.1. Intrinsics and Builtin Types Specification.md
• 6.2. Host ABI Binding and Loader Resolution Specification.md
• 9. Dynamic Semantics Specification.md
• 10. Memory and Lifetime Specification.md

This document is expected to be closed using a future backend agenda sequence tracked in docs/agendas/.

5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

• The compiler consumes reserved Host metadata while resolving host-backed SDK members.
• The compiler consumes reserved BuiltinType, BuiltinConst, IntrinsicCall, and Slot metadata while resolving builtin shells.
• The compiler emits canonical host-binding declarations into the PBX SYSC table.
• The compiler emits host-backed callsites in pre-load form as HOSTCALL <sysc_index>.
• SYSC entries are deduplicated by canonical identity and ordered by first occurrence.
• The loader, not the compiler, resolves canonical host bindings to final numeric syscall identifiers.
• Builtin projection lowering remains VM-owned and does not emit host-binding metadata.
• Builtin constants lower through VM-owned materialization rather than through ordinary compile-time constant evaluation.
• Builtin intrinsic member calls lower through a VM-owned intrinsic path rather than through SYSC, HOSTCALL, or SYSCALL.
• Stdlib interface modules are compile-time-only and do not emit executable bytecode by themselves.

6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. lowering preconditions,
2. semantic obligations preserved by IR,
3. lowering of expressions and control flow,
4. lowering of callable categories,
5. lowering of optional and result<E> constructs,
6. lowering of callbacks, services, and contracts,
7. lowering of builtin projections, builtin constants, and builtin intrinsic calls,
8. host-binding emission,
9. artifact invariants required before verifier/loader stages.

7. A Ver

The following items remain to be closed before this document can be considered complete.

7.1 Depends on 9. Dynamic Semantics Specification.md

• Which evaluation-order guarantees must be preserved explicitly in lowering.
• Which traps, abrupt completions, and propagation paths require dedicated lowered forms.
• Whether callback formation and contract dispatch need dedicated runtime artifacts or only implementation-defined IR shapes.

7.2 Depends on 10. Memory and Lifetime Specification.md

• Which lowered operations allocate, alias, retain, or cross the host-memory boundary.
• Which runtime storage/identity facts IR must preserve explicitly versus infer later.

7.3 Depends on the future backend agenda sequence tracked in docs/agendas/

• Whether one canonical IR is normative or only the preserved semantic obligations are normative.
• The exact mapping from bound PBS constructs to PBX/bytecode-facing artifacts beyond already-settled host-binding and intrinsic behavior.
• Lowering strategy for services, contracts, callbacks, tuples, and result propagation.
• Whether declaration-based intrinsic preload forms such as INTRCALL are part of v1 lowering or whether compilers should emit final INTRINSIC <id> directly for a selected VM line.
• Which artifact invariants belong here versus a future dedicated PBX/bytecode mapping document.

8. Non-Goals

• Freezing one optimizer design.
• Requiring one compiler implementation architecture.
• Repeating the full bytecode ISA specification.
• Defining loader-side patching internals already owned elsewhere.

9. Exit Criteria

This document is ready to move beyond skeleton status only when:

1. every semantically distinct core construct has an explicit lowering story,
2. the boundary between source semantics, compiler IR, and emitted artifacts is clear,
3. host-binding emission is fully aligned with the Host ABI spec,
4. builtin and intrinsic lowering is fully aligned with the VM-owned builtin spec,
5. the document no longer relies on unresolved backend A Ver items for ordinary v1 lowering behavior.