implements PLN-0117

This commit is contained in:
2026-07-15 12:10:10 +01:00
parent 26c69d5660
commit bde999f1fe
5 changed files with 77 additions and 37 deletions
@@ -1,13 +1,13 @@
# PBS Lowering IRBackend Specification
Status: Draft v1 (Frontend Scope + Backend Handoff Addendum)
Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile`, plus executable-backend handoff obligations at this boundary
Status: Draft v1 (PBS Frontend Scope + Common Handoff Emission)
Applies to: first lowering boundary from bound PBS frontend model into the common `IRBackend`/`IRBackendFile` handoff
## 1. Purpose
This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`.
This document defines the normative frontend lowering contract from PBS source semantics to the common `IRBackend` handoff.
Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve.
Its purpose is to keep PBS lowering deterministic while preserving the common frontend-to-backend contract owned by compiler-general backend specs.
## 2. Scope
@@ -18,7 +18,7 @@ This document defines:
- semantic obligations preserved in `IRBackend`,
- deterministic rejection behavior for unsupported frontend-lowering forms,
- diagnostics attribution obligations for lowering failures in frontend scope,
- executable-backend handoff obligations at the `IRBackend` boundary,
- PBS obligations for emitting the common executable `IRBackend` handoff,
- and backend-owned symbolic lowering obligations for asset-facing references.
This document does not define:
@@ -26,7 +26,8 @@ This document does not define:
- VM lowering (`IRVM`),
- bytecode/PBX mapping,
- runtime execution behavior,
- verifier/loader internals.
- verifier/loader internals,
- or common backend ownership of the `IRBackend -> IRVM` contract.
Those concerns belong to shared acceptance specs under `docs/specs/compiler`.
@@ -75,9 +76,9 @@ When the active source slice depends on a backend-owned symbolic surface such as
- the frontend must not query domain services directly to discover operational assets;
- and lowering must preserve enough identity for the backend to complete final operational resolution.
## 6. IRBackend Preserved Obligations
## 6. PBS IRBackend Emission Obligations
For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum:
For each admitted PBS source unit and callable in the current lowering slice, PBS lowering must emit `IRBackend` that preserves at minimum:
1. callable identity (name/category as applicable),
2. callable arity,
@@ -93,6 +94,8 @@ Lowering must not collapse source categories in a way that erases required decla
The normative contract is obligation-based, not tied to one mandatory in-memory class graph.
`IRBackend` itself is the common frontend-to-backend executable handoff. This PBS spec owns only the PBS-specific admission and translation path into that handoff. Common backend rules for consuming `IRBackend` are owned by `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
## 7. Deterministic Rejection Policy
If a source form is outside current frontend-lowering support:
@@ -111,7 +114,7 @@ For multi-module builds, lowering admission must apply dependency-scoped fail-fa
## 8. Conformance Boundary
`IRBackend` is the first lowering boundary (frontend responsibility).
PBS emission into `IRBackend` is the first PBS lowering boundary (frontend responsibility).
Conformance-valid claims at this boundary require Gate U evidence from `docs/specs/compiler/13. Conformance Test Specification.md`.
@@ -148,9 +151,9 @@ This document is healthy when:
3. deterministic rejection policy is explicit and test-backed,
4. and scope boundaries with general/backend acceptance specs are explicit.
## 12. Executable Backend Handoff Addendum (v1)
## 12. PBS Executable Handoff Emission Obligations (v1)
For executable backends, the `IRBackend` output from this frontend boundary must satisfy the additional handoff obligations below.
For executable backends, PBS lowering must emit `IRBackend` satisfying the additional handoff obligations below before common backend lowering starts.
### 12.1 Callable obligations
@@ -170,7 +173,7 @@ Each executable callsite in `IRBackend` must be classified into exactly one cate
2. `CALL_HOST`,
3. `CALL_INTRINSIC`.
Backend lowering must not infer this category by textual heuristics.
PBS lowering must not leave this category for backend inference by textual heuristics.
### 12.3 Host-backed metadata obligations
@@ -187,11 +190,11 @@ When a host-backed callsite also depends on backend-owned symbolic asset lowerin
- the frontend boundary MUST preserve which callsite argument is asset-facing;
- for PBS v1 this asset-facing designation is carried by reserved host metadata `[AssetLowering(param = N)]`;
- the preserved symbolic operand MUST remain attributable to a backend-provided `Addressable` identity;
- backend stages MUST be able to rewrite that symbolic operand into runtime-facing `asset_id` before the final low-level host path is emitted.
- common backend stages MUST be able to rewrite that symbolic operand into runtime-facing `asset_id` before the final low-level host path is emitted.
When an expression statement leaves a materialized runtime value on the stack:
- `IRBackend` lowering MUST emit explicit discard behavior rather than relying on implicit backend stack cleanup;
- PBS lowering into `IRBackend` MUST emit explicit discard behavior rather than relying on implicit backend stack cleanup;
- for single-slot materialized values this discard is represented by `POP`;
- and the discard path MUST preserve stack-accounting validity for subsequent backend lowering stages.
@@ -220,7 +223,7 @@ It does not replace:
### 12.7 Executable Lifecycle and Published Wrapper Obligation
For executable PBS frontends, backend handoff must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint.
For executable PBS frontends, PBS lowering must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint.
At `IRBackend` emission time:
@@ -230,8 +233,8 @@ At `IRBackend` emission time:
- module init,
- project init when present,
- and the published frame wrapper,
2. the published frame wrapper must be the effective entrypoint identity handed to backend stages,
2. the published frame wrapper must be the effective entrypoint identity handed to common backend stages,
3. the userland callable marked with `[Frame]` must remain distinguishable as the logical frame root,
4. the wrapper must own final `FRAME_RET`,
5. backend stages must not reintroduce manifest-owned or `FrontendSpec`-owned nominal entrypoint authority,
5. common backend stages must not reintroduce manifest-owned or `FrontendSpec`-owned nominal entrypoint authority,
6. and hidden compiler-owned lifecycle state such as the boot guard must remain structurally distinguishable from user globals.