Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown. Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
294 lines
14 KiB
Markdown
294 lines
14 KiB
Markdown
# PBS Lowering IRBackend Specification
|
|
|
|
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 the common `IRBackend` handoff.
|
|
|
|
Its purpose is to keep PBS lowering deterministic while preserving the common frontend-to-backend contract owned by compiler-general backend specs.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- required preconditions before lowering starts,
|
|
- AST invariants that lowering may assume as hard contract,
|
|
- semantic obligations preserved in `IRBackend`,
|
|
- deterministic rejection behavior for unsupported frontend-lowering forms,
|
|
- diagnostics attribution obligations for lowering failures in frontend scope,
|
|
- PBS obligations for emitting the common executable `IRBackend` handoff,
|
|
- and backend-owned symbolic lowering obligations for asset-facing references.
|
|
|
|
This document does not define:
|
|
|
|
- VM lowering (`IRVM`),
|
|
- bytecode/PBX mapping,
|
|
- runtime execution behavior,
|
|
- verifier/loader internals,
|
|
- or common backend ownership of the `IRBackend -> IRVM` contract.
|
|
|
|
Those concerns belong to shared acceptance specs under `docs/specs/compiler`.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. `3. Core Syntax Specification.md`
|
|
2. `4. Static Semantics Specification.md`
|
|
3. `11. AST Specification.md`
|
|
4. `12. Diagnostics Specification.md`
|
|
5. This document
|
|
|
|
If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on:
|
|
|
|
- `3. Core Syntax Specification.md`
|
|
- `4. Static Semantics Specification.md`
|
|
- `11. AST Specification.md`
|
|
- `12. Diagnostics Specification.md`
|
|
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
|
|
|
## 5. Lowering Preconditions
|
|
|
|
Frontend lowering into `IRBackend` may start only when:
|
|
|
|
1. source has been tokenized and parsed,
|
|
2. required syntax diagnostics have been emitted,
|
|
3. AST output satisfies `11` required invariants for this source unit, including:
|
|
- one root per file,
|
|
- deterministic child ordering,
|
|
- mandatory node attribution (`file/start/end`) on nodes consumed by lowering,
|
|
- mandatory declaration metadata on declaration nodes required by the active source slice,
|
|
- and structural coherence after any parser recovery.
|
|
4. linking/name-resolution outcomes required for the current lowering slice are available,
|
|
5. and no unresolved semantic ambiguity is deferred to lowering.
|
|
|
|
Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases.
|
|
|
|
When the active source slice depends on a backend-owned symbolic surface such as PBS asset references:
|
|
|
|
- the frontend may assume access to the admitted frontend surface context selected for the build;
|
|
- 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. PBS IRBackend Emission Obligations
|
|
|
|
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,
|
|
3. declared return surface information,
|
|
4. source attribution anchor (`file + span`) for diagnostics and traceability,
|
|
5. source-observable parse intent for statement/expression structure (including precedence/associativity outcome already fixed by AST shape).
|
|
6. deterministic `requiredCapabilities` derived from admitted host-binding metadata for packer/runtime-manifest assistance.
|
|
7. a typed `IRLifecycleDeclaration` for executable programs, with file-init fragment, optional project-init, and required frame-root references,
|
|
8. explicit user globals and frontend-lowered file-init fragments required by later common lifecycle assembly,
|
|
9. backend-owned symbolic identities that must survive to later executable lowering, including symbolic asset references when admitted by the source slice.
|
|
|
|
PBS lowering MUST NOT emit module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard. Those artifacts are produced exclusively by common lifecycle assembly.
|
|
|
|
Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.
|
|
|
|
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:
|
|
|
|
1. rejection must be deterministic,
|
|
2. diagnostics must expose stable `code`, `severity`, `phase`, `message template id`, and primary attribution,
|
|
3. and unsupported forms must not silently degrade into different valid lowered behavior.
|
|
|
|
Lowering must not convert a required syntax/static rejection into accepted lowered behavior.
|
|
|
|
For multi-module builds, lowering admission must apply dependency-scoped fail-fast:
|
|
|
|
1. a module rejected in syntax, static semantics, linking, host-admission, or load-facing gates must not be emitted;
|
|
2. any module that imports a rejected module (directly or transitively) must also be excluded from `IRBackend` emission;
|
|
3. modules independent from the rejected dependency subgraph may continue to lower and emit in the same build.
|
|
|
|
## 8. Conformance Boundary
|
|
|
|
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`.
|
|
|
|
For this frontier, Gate U evidence is expected to cover at minimum:
|
|
|
|
- lexer behavior for covered inputs,
|
|
- parser behavior and AST shape invariants required by `11`,
|
|
- lowering outcomes at `IRBackend` boundary,
|
|
- and deterministic diagnostics identity/attribution for rejection cases.
|
|
|
|
Conformance at this boundary may be claimed only when the full claimed PBS source surface is implemented at `IRBackend` level.
|
|
|
|
## 9. Explicit Deferrals
|
|
|
|
The following are intentionally out of scope for this document:
|
|
|
|
- `IRBackend -> IRVM` lowering,
|
|
- artifact encoding and binary layout,
|
|
- runtime lifecycle behavior,
|
|
- verifier and loader checks.
|
|
|
|
## 10. Non-Goals
|
|
|
|
- Freezing one optimizer strategy.
|
|
- Freezing one compiler architecture.
|
|
- Repeating runtime or bytecode authority.
|
|
|
|
## 11. Exit Criteria
|
|
|
|
This document is healthy when:
|
|
|
|
1. lowering preconditions are explicit,
|
|
2. preserved `IRBackend` obligations are explicit,
|
|
3. deterministic rejection policy is explicit and test-backed,
|
|
4. and scope boundaries with general/backend acceptance specs are explicit.
|
|
|
|
## 12. PBS Executable Handoff Emission Obligations (v1)
|
|
|
|
For executable backends, PBS lowering must emit `IRBackend` satisfying the additional handoff obligations below before common backend lowering starts.
|
|
|
|
### 12.1 Callable obligations
|
|
|
|
For each executable callable admitted into `IRBackend`, the frontend must preserve:
|
|
|
|
1. stable callable identity in the current build graph,
|
|
2. observable callable signature (input arity and return shape),
|
|
3. callable category needed by downstream lowering,
|
|
4. source attribution anchor (`fileId`, `start`, `end`),
|
|
5. and executable body representation that is backend-lowerable.
|
|
|
|
### 12.2 Callsite classification obligations
|
|
|
|
Each executable callsite in `IRBackend` must be classified into exactly one category:
|
|
|
|
1. `CALL_FUNC`,
|
|
2. `CALL_HOST`,
|
|
3. `CALL_INTRINSIC`.
|
|
|
|
PBS lowering must not leave this category for backend inference by textual heuristics.
|
|
|
|
### 12.3 Host-backed metadata obligations
|
|
|
|
Each host-backed callsite admitted at this boundary must preserve canonical host identity:
|
|
|
|
1. `module`,
|
|
2. `name`,
|
|
3. `version`.
|
|
|
|
When available at this boundary, declared host ABI shape (`arg_slots`, `ret_slots`) must also be preserved for downstream validation.
|
|
|
|
When a host-backed callsite also depends on backend-owned symbolic asset lowering:
|
|
|
|
- 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;
|
|
- 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:
|
|
|
|
- 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.
|
|
|
|
### 12.4 VM-owned metadata obligations
|
|
|
|
VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:
|
|
|
|
1. `canonicalName`,
|
|
2. `canonicalVersion`.
|
|
|
|
VM-owned builtin projections/constants/intrinsics must not be reclassified as host bindings.
|
|
|
|
### 12.5 Deterministic capability obligations
|
|
|
|
`requiredCapabilities` derived at this boundary must be deterministic for the same admitted input graph.
|
|
|
|
### 12.6 Boundary with backend lowering specs
|
|
|
|
This addendum defines obligations preserved at the `IRBackend` boundary only.
|
|
|
|
It does not replace:
|
|
|
|
1. `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`,
|
|
2. `docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md`,
|
|
3. or `docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md`.
|
|
|
|
### 12.7 Executable Lifecycle Declaration Obligation
|
|
|
|
For executable PBS frontends, PBS lowering MUST emit a typed `IRLifecycleDeclaration` rather than assembling the published lifecycle.
|
|
|
|
At frontend `IRBackend` emission time:
|
|
|
|
1. PBS MUST retain marker admission for `[Init]`, `[Frame]`, `[BeforePause]`, `[BeforeResume]`, and `InitAllowed`,
|
|
2. PBS MUST emit typed references for:
|
|
- file-init fragments that include global materialization and non-project `[Init]`,
|
|
- the optional project-init callable, which is the `[Init]` colocated with `[Frame]`,
|
|
- and the required frame-root callable marked with `[Frame]`,
|
|
3. the colocated project init MUST be excluded from file-init fragments,
|
|
4. module order in the declaration MUST propagate the explicit dependency order already derived from resolved project/module data, without sorting by `FileId`, textual module name, or synthetic callable name,
|
|
5. PBS MUST NOT emit module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard,
|
|
6. and common lifecycle assembly remains the owner of derived artifacts, including the published wrapper that becomes the physical entrypoint and owns the final frame return.
|
|
|
|
## Existing values and input runtime alignment
|
|
|
|
The [PBS input and value alignment contract](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md) governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.
|
|
|
|
## Typed arrays and optional execution extension
|
|
|
|
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
|
|
defines the complete type, optional-flow and storage contract.
|
|
This chapter owns source-to-common-IR projection; the owner chapter defines
|
|
Array storage, optional carriers and complete-group requirements.
|
|
|
|
Array spelling and construction are owned by [Core Syntax](3.%20Core%20Syntax%20Specification.md)
|
|
and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.
|
|
|
|
|
|
## Parameterized contracts
|
|
|
|
The frontend substitutes each closed application and emits a concrete nominal Trait descriptor shared by equivalent uses. Distinct logical applications remain distinct despite shared physical carriers. Concrete implementation functions take the receiver first. CALL_TRAIT evaluates and roots the receiver before arguments, evaluates arguments left to right, then places the complete receiver/ImplementationId view after the argument groups as required by the runtime ABI. Preserve exact signatures, absence, ImplementationId zero, ownership, GC and quotas; generic calls do not add a Dynamic ABI or adaptation wrapper.
|
|
|
|
See [PBS generic contracts](16.%20Generic%20Contracts%20Specification.md).
|
|
|
|
|
|
## Concrete generic structs and free functions
|
|
|
|
Instantiate structs, free functions and owner-bound implementations within PBS before publishing executable descriptors. Registry receives concrete fields, signatures, bodies, capture groups and targets. Specialized free-function references use existing empty-environment Closure values; Fn remains structural. Preserve receiver identity, implementation zero, singletons, rooting, GC, ownership, evaluation/fault order and quotas. No generic Dynamic/boxing ABI, opcode, descriptor category or runtime instantiation engine is introduced.
|
|
|
|
See [Concrete generic structs and free functions](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md).
|
|
|
|
|
|
## Lowering optional runtime hook roles
|
|
|
|
Map BEFORE_PAUSE/BEFORE_RESUME to `IRRegistry.Role.BEFORE_PAUSE` (1) /
|
|
`BEFORE_RESUME` (2) in typed FunctionMetadata. Preserve the declaration/callable
|
|
identity, empty signature and capture list; no hidden receiver or parameter is
|
|
introduced. INIT/FRAME and ordinary functions retain role None (0). Function
|
|
names/exports/manifests are not role binding mechanisms. No MemcardBoot role is
|
|
inferred or emitted by these markers.
|
|
|
|
Each role target and its dependencies are externally entered retention roots,
|
|
even without source callers. Merge, lifecycle assembly, linking and optimization
|
|
MUST preserve bodies and metadata. Common code consumes neutral typed roles,
|
|
never PBS ASTs/names. The ordinary assembled entry remains physical FunctionId
|
|
zero; hook targets are nonzero after deterministic linking. Common Registry/PBX
|
|
validation and production runtime admission remain mandatory defenses.
|
|
|
|
|
|
## Memcard integration
|
|
|
|
The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specification.md>)
|
|
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
|
|
bootstrap, project identity/slot validation and complete installed mem ABI.
|
|
Its requirements apply in addition to this chapter; pause/resume remain independent.
|