157 lines
8.0 KiB
Markdown
157 lines
8.0 KiB
Markdown
# 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.
|