implements PLN-0005

This commit is contained in:
2026-03-27 17:01:40 +00:00
parent 124c6d078e
commit e0c57814e1
12 changed files with 143 additions and 10 deletions
@@ -199,6 +199,10 @@ At minimum, the PBS diagnostics baseline must cover:
- `published entrypoint is not function index 0`,
- `hidden boot guard is missing`,
- `synthetic callable origin missing`.
9. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
- unresolved terminal asset reference,
- namespace-versus-terminal asset misuse,
- structurally invalid symbolic asset path admitted by source syntax but rejected by semantic surface rules.
At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.
@@ -212,6 +216,12 @@ This means:
When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.
For backend-owned symbolic asset surfaces:
- diagnostics SHOULD point primarily to the symbolic reference site in source;
- the frontend MAY use backend-provided surface context to improve earlier diagnostics;
- backend ownership of final validation does not remove the requirement for deterministic source-facing diagnostics when validation fails.
Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap.
Dependency-scoped fail-fast admission is not equivalent to global build abort.
@@ -18,7 +18,8 @@ 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,
- and executable-backend handoff obligations at the `IRBackend` boundary.
- executable-backend handoff obligations at the `IRBackend` boundary,
- and backend-owned symbolic lowering obligations for asset-facing references.
This document does not define:
@@ -68,6 +69,12 @@ Frontend lowering into `IRBackend` may start only when:
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. IRBackend Preserved Obligations
For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum:
@@ -80,6 +87,7 @@ For each admitted source unit and callable in the current lowering slice, `IRBac
6. deterministic `requiredCapabilities` derived from admitted host-binding metadata for packer/runtime-manifest assistance.
7. compiler-selected published-wrapper entrypoint identity for backend handoff,
8. explicit global and synthetic lifecycle structure required by executable lowering.
9. backend-owned symbolic identities that must survive to later executable lowering, including symbolic asset references when admitted by the source slice.
Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.
@@ -174,6 +182,12 @@ Each host-backed callsite admitted at this boundary must preserve canonical host
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;
- 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.
### 12.4 VM-owned metadata obligations
VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:
@@ -52,6 +52,24 @@ Rules:
- Builtin simple types are resolved without import or declaration.
- User-authored type declarations must not reuse builtin simple type names.
### 2.2.1 Backend-provided symbolic asset surface
PBS static semantics may consume a backend-provided symbolic asset surface.
Rules:
- The frontend-facing symbolic asset surface is rooted at `assets`.
- `assets` is a compile-time namespace root, not an ordinary runtime value by default.
- Intermediate `assets...` nodes are namespace-only and MUST NOT be treated as terminal asset values.
- Terminal asset leaves are represented statically as `Addressable`.
- For PBS v1, `Addressable` is the canonical public/editorial type shape for symbolic asset references.
- The PBS frontend may use a fake/frontend-owned `Addressable` type surface for semantics and tooling.
- This frontend-owned surface MUST NOT transfer final validation or executable lowering ownership away from the backend.
- The backend-provided asset surface contract for v1 is `List<Addressable(address, asset_id)>`.
- The canonical symbolic identity of an asset reference is its normalized `address`, not `asset_name`.
- `asset_name` MUST NOT remain the operational compile-time identity for symbolic asset lookup.
- A terminal asset path MUST NOT also act as a namespace prefix for descendant assets.
### 2.3 Attribute metadata
Attributes are compile-time metadata attached to declaration surfaces.
@@ -217,6 +235,9 @@ Rules:
- `BuiltinConst.target` and `BuiltinConst.name` MUST be non-empty string literals.
- `BuiltinConst.version` MUST be a positive integer literal.
- Two builtin constant declarations in the same resolved stdlib environment MUST NOT lower to the same canonical `(target, name, version)` unless they denote the same builtin constant declaration after project/module resolution.
- Symbolic asset references admitted by the frontend MUST resolve against the backend-provided `Addressable` surface rather than by direct packer queries.
- A valid symbolic asset reference MUST correspond to a terminal `Addressable` entry in the backend-provided surface.
- Intermediate `assets...` namespace nodes MUST NOT type-check as `Addressable` values.
### 3.4 Constant expressions
@@ -20,11 +20,15 @@ This document is the authority for how the compiler discovers and loads:
- ordinary project modules,
- reserved stdlib modules such as `@sdk:gfx`,
- compile-time reserved metadata attached to those reserved modules,
- and interface-only service facades that wrap host surfaces for source ergonomics.
- interface-only service facades that wrap host surfaces for source ergonomics,
- and backend-provided compile surfaces consumed by the frontend for symbolic authoring.
This document does not define runtime load behavior.
PBX host-binding emission and loader-side syscall resolution are defined by the Host ABI Binding and Loader Resolution Specification.
It also does not define the raw packer snapshot format.
Frontend-facing compile surfaces consume only the backend-owned surface contract selected for the active build.
## 2. Scope
This document defines:
@@ -37,6 +41,7 @@ This document defines:
- reserved project spaces such as `@sdk:*` and `@core:*`,
- the source model for stdlib interface modules,
- the compile-time role of reserved attributes such as `[Host(...)]`.
- the boundary between backend-owned compile surfaces and frontend semantic consumption.
This document does not define:
@@ -44,10 +49,23 @@ This document does not define:
- loader-side syscall resolution,
- cartridge capability policy,
- package registry protocol details,
- runtime reflection over attributes.
- runtime reflection over attributes,
- or the full operational snapshot model owned by packer.
## 3. Core Terms
### 3.5 Backend-owned frontend surface context
The compiler backend may provide a frontend-facing semantic surface context to the active language frontend.
Rules:
- The frontend surface context is backend-owned.
- The frontend surface context is not the raw operational snapshot owned by packer or other domain services.
- The frontend surface context exists to support semantic consumption, diagnostics, and tooling-oriented source interpretation.
- For PBS asset references in v1, the frontend surface context asset slice SHALL be `List<Addressable(address, asset_id)>`.
- Future surface slices MAY exist, but they are outside this document's v1 PBS asset contract.
### 3.1 Project
A project is the unit described by `prometeu.json`.
@@ -258,6 +276,17 @@ For an import:
import { X } from @project:path/to/module;
```
## 9. Backend-Owned Symbolic Compile Surfaces
Some source-level semantics depend on backend-owned symbolic surfaces rather than on imported stdlib modules alone.
Rules:
- A symbolic compile surface consumed by the frontend MUST enter through the backend/frontend compile contract, not through direct frontend service queries.
- PBS symbolic asset references are resolved from the backend-owned frontend surface context rather than from stdlib import discovery.
- Stdlib interfaces such as `@sdk:asset` define host-backed callable surfaces, but they do not replace backend ownership of symbolic `Addressable` resolution.
- The backend/frontend contract MAY carry symbolic surfaces that are not themselves importable modules.
the compiler MUST:
1. parse the project space and module path,