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