implements PLN-0117
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user