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 close in coordination with 15. Bytecode and PBX Mapping Specification.md and 16. Runtime Execution and Initialization Specification.md.

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.
• Backend-originated failures only enter the PBS-facing diagnostics contract when they remain source-attributable and user-actionable.

6. Current Lowering and Artifact Boundary Baseline

The current backend-facing division of responsibility is:

• this document defines what semantic and artifact-boundary facts lowering must preserve before verifier or loader validation,
• 15. Bytecode and PBX Mapping Specification.md defines how those facts appear in PBX/bytecode-visible form,
• and 19. Verification and Safety Checks Specification.md defines which later safety and validity checks are applied after lowering and, where relevant, after loader patching.

At minimum, the current lowering baseline requires:

1. admitted host-backed uses lower to canonical host-binding declarations and pre-load call references rather than to resolved syscall identifiers;
2. canonical host-binding declarations remain deduplicated by canonical identity and ordered by first occurrence;
3. VM-owned builtin projections, builtin constants, and intrinsic callsites remain outside host-binding metadata surfaces;
4. stdlib interface modules remain compile-time-only and do not emit executable bytecode by themselves;
5. lowering preserves enough attribution metadata that at least one source location can later be recovered for backend failures that remain source-attributable and user-actionable.

This document defines those obligations as preserved facts, not as one exact PBX encoding.

7. 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.

8. TODO

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

8.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.

8.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.

8.3 Still open across this document and adjacent backend-facing specs

• 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 additional artifact invariants beyond the current conformance baseline belong here versus in 15.
• Which richer attribution/debug hooks, if any, should be added beyond the minimum one-location recovery baseline already required for in-scope backend failures.

9. 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.

10. 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 TODO items for ordinary v1 lowering behavior.