implements PLN-0005

This commit is contained in:
bQUARKz 2026-03-27 17:01:40 +00:00
parent 124c6d078e
commit e0c57814e1
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
12 changed files with 143 additions and 10 deletions

View File

@ -4,6 +4,6 @@
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0005","file":"DEC-0005-pbs-asset-address-surface-and-be-lowering.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"},{"id":"DEC-0006","file":"DEC-0006-pbs-ignored-values-lowering-and-warning.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-pbs-asset-address-surface-spec-propagation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0006","file":"PLN-0006-pbs-asset-address-surface-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0007","file":"PLN-0007-pbs-ignored-values-warning-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0006"]}],"lessons":[]} {"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0005","file":"DEC-0005-pbs-asset-address-surface-and-be-lowering.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"},{"id":"DEC-0006","file":"DEC-0006-pbs-ignored-values-lowering-and-warning.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-pbs-asset-address-surface-spec-propagation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0006","file":"PLN-0006-pbs-asset-address-surface-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0007","file":"PLN-0007-pbs-ignored-values-warning-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0006"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}

View File

@ -2,9 +2,9 @@
id: PLN-0005 id: PLN-0005
ticket: pbs-game-facing-asset-refs-and-call-result-discard ticket: pbs-game-facing-asset-refs-and-call-result-discard
title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs
status: review status: done
created: 2026-03-27 created: 2026-03-27
completed: completed: 2026-03-27
tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract] tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract]
--- ---

View File

@ -199,6 +199,10 @@ At minimum, the PBS diagnostics baseline must cover:
- `published entrypoint is not function index 0`, - `published entrypoint is not function index 0`,
- `hidden boot guard is missing`, - `hidden boot guard is missing`,
- `synthetic callable origin 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. 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. 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. 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. Dependency-scoped fail-fast admission is not equivalent to global build abort.

View File

@ -18,7 +18,8 @@ This document defines:
- semantic obligations preserved in `IRBackend`, - semantic obligations preserved in `IRBackend`,
- deterministic rejection behavior for unsupported frontend-lowering forms, - deterministic rejection behavior for unsupported frontend-lowering forms,
- diagnostics attribution obligations for lowering failures in frontend scope, - 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: 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. 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 ## 6. IRBackend Preserved Obligations
For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum: 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. 6. deterministic `requiredCapabilities` derived from admitted host-binding metadata for packer/runtime-manifest assistance.
7. compiler-selected published-wrapper entrypoint identity for backend handoff, 7. compiler-selected published-wrapper entrypoint identity for backend handoff,
8. explicit global and synthetic lifecycle structure required by executable lowering. 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. 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 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 ### 12.4 VM-owned metadata obligations
VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity: VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:

View File

@ -52,6 +52,24 @@ Rules:
- Builtin simple types are resolved without import or declaration. - Builtin simple types are resolved without import or declaration.
- User-authored type declarations must not reuse builtin simple type names. - 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 ### 2.3 Attribute metadata
Attributes are compile-time metadata attached to declaration surfaces. 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.target` and `BuiltinConst.name` MUST be non-empty string literals.
- `BuiltinConst.version` MUST be a positive integer literal. - `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. - 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 ### 3.4 Constant expressions

View File

@ -20,11 +20,15 @@ This document is the authority for how the compiler discovers and loads:
- ordinary project modules, - ordinary project modules,
- reserved stdlib modules such as `@sdk:gfx`, - reserved stdlib modules such as `@sdk:gfx`,
- compile-time reserved metadata attached to those reserved modules, - 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. 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. 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 ## 2. Scope
This document defines: This document defines:
@ -37,6 +41,7 @@ This document defines:
- reserved project spaces such as `@sdk:*` and `@core:*`, - reserved project spaces such as `@sdk:*` and `@core:*`,
- the source model for stdlib interface modules, - the source model for stdlib interface modules,
- the compile-time role of reserved attributes such as `[Host(...)]`. - 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: This document does not define:
@ -44,10 +49,23 @@ This document does not define:
- loader-side syscall resolution, - loader-side syscall resolution,
- cartridge capability policy, - cartridge capability policy,
- package registry protocol details, - 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. 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 ### 3.1 Project
A project is the unit described by `prometeu.json`. A project is the unit described by `prometeu.json`.
@ -258,6 +276,17 @@ For an import:
import { X } from @project:path/to/module; 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: the compiler MUST:
1. parse the project space and module path, 1. parse the project space and module path,

View File

@ -156,6 +156,14 @@ Rules:
- user code may import those host owners through ordinary stdlib module imports, - user code may import those host owners through ordinary stdlib module imports,
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`. - and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
Host-backed SDK modules do not own every symbolic authoring surface that may feed them.
Rules:
- a stdlib host surface such as `@sdk:asset` may provide the low-level executable callable owner while the backend still owns symbolic authoring resolution;
- PBS symbolic asset references (`Addressable`) are not themselves required to be stdlib-imported modules;
- backend-owned frontend surface contracts MAY supply symbolic values that later lower into stdlib host-backed APIs.
## 13. Stdlib Contract Expectations for Builtin MVP ## 13. Stdlib Contract Expectations for Builtin MVP
For the current builtin MVP, stdlib should be able to expose at least: For the current builtin MVP, stdlib should be able to expose at least:

View File

@ -114,6 +114,12 @@ For PBS executable lowering:
`CALL_HOST` lowers to pre-load `HOSTCALL <sysc_index>`, not raw `SYSCALL`. `CALL_HOST` lowers to pre-load `HOSTCALL <sysc_index>`, not raw `SYSCALL`.
When a host-backed callsite carries backend-owned symbolic asset lowering metadata:
1. the backend must validate the symbolic asset operand against the backend-owned admitted surface,
2. the backend must resolve the symbolic identity to canonical runtime-facing `asset_id`,
3. and the final host-backed lowering path must consume the resolved `asset_id`, not the original symbolic address.
### 9.3 VM-owned intrinsic calls ### 9.3 VM-owned intrinsic calls
`CALL_INTRINSIC` lowers to VM-owned intrinsic path and must remain distinct from host-binding paths. `CALL_INTRINSIC` lowers to VM-owned intrinsic path and must remain distinct from host-binding paths.
@ -142,6 +148,7 @@ Before bytecode emission, backend must run structural pre-verification on lowere
5. function-id validity, 5. function-id validity,
6. callsite arity consistency, 6. callsite arity consistency,
7. and structural validity of host/intrinsic call forms. 7. and structural validity of host/intrinsic call forms.
8. and structural validity of backend-owned symbolic-to-operational rewrites such as `Addressable -> asset_id`.
This pre-verification does not replace runtime verifier authority. This pre-verification does not replace runtime verifier authority.

View File

@ -46,7 +46,10 @@ The following are not primary identity:
- filesystem path - filesystem path
- internal input file names - internal input file names
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label. The packer may also derive a canonical symbolic address from the asset root path for compile-time authoring surfaces.
That derived address is not a replacement for registry authority over `asset_id`.
`asset_name` may still exist as an authoring label, but it is not the operational compile-time identity used by the backend-owned symbolic asset surface.
## Local Identity Anchor ## Local Identity Anchor
@ -73,6 +76,20 @@ Rules:
Renaming `asset_name` is an API-visible change, but not an identity change. Renaming `asset_name` is an API-visible change, but not an identity change.
Renaming or moving an asset root may change the derived canonical symbolic address used by compile-time symbolic references, even when `asset_id` and `asset_uuid` remain stable.
## Canonical Symbolic Address Projection
The packer runtime may project a canonical symbolic asset address derived from the asset root under `assets/`.
Rules:
- The canonical symbolic address is derived from the normalized relative asset root path.
- The canonical symbolic address is a projection for backend/frontend compile-time consumption.
- The canonical symbolic address MUST NOT replace registry ownership of `asset_id`.
- The backend may publish the projected symbolic address through a frontend-facing surface contract without exposing the raw packer snapshot format.
- `asset_name` MUST NOT be required as the operational key for this projected symbolic address.
## Unregistered Roots ## Unregistered Roots
An `asset.json` without a corresponding registry entry is an unregistered asset root. An `asset.json` without a corresponding registry entry is an unregistered asset root.

View File

@ -77,7 +77,8 @@ Rules:
- one entry per included asset in the current build set; - one entry per included asset in the current build set;
- no secondary runtime-only identity layer; - no secondary runtime-only identity layer;
- no synthetic dense reindexing layer; - no synthetic dense reindexing layer;
- `asset_name` remains present as logical/API-facing metadata. - `asset_name` may remain present as logical/API-facing metadata;
- `asset_name` is not the operational compile-time identity used by backend-owned symbolic asset surfaces.
### Asset Entry Metadata Convergence ### Asset Entry Metadata Convergence

View File

@ -52,6 +52,7 @@ Rules:
- normal read requests should be served from that coherent snapshot when the runtime is active; - normal read requests should be served from that coherent snapshot when the runtime is active;
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store; - the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
- the durable authoring workspace remains the persisted source of truth after successful commit. - the durable authoring workspace remains the persisted source of truth after successful commit.
- backend consumers may derive smaller frontend-facing compile surfaces from the runtime snapshot without exposing the raw snapshot as a frontend contract.
### Embedded Bootstrap Rule ### Embedded Bootstrap Rule
@ -223,6 +224,17 @@ Rules:
- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events. - adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events.
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent. - embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
## Compile-Surface Integration Boundary
The packer snapshot is not itself the normative frontend compile contract.
Rules:
- the backend may derive a smaller frontend-facing compile surface from packer-owned state;
- for asset references, that smaller surface may contain only `Addressable(address, asset_id)` entries;
- Studio and compiler frontends may consume the derived surface through backend-owned contracts;
- consumers must not treat the raw packer snapshot as the stable frontend API boundary.
### Event Ordering and Coalescing ### Event Ordering and Coalescing
Rules: Rules:

View File

@ -71,6 +71,7 @@ The workspace must help the user understand:
- what the asset declares toward the runtime-facing contract; - what the asset declares toward the runtime-facing contract;
- which operations are safe, staged, blocked, or destructive; - which operations are safe, staged, blocked, or destructive;
- whether the current view reflects healthy, stale, diverged, or reconciling packer state. - whether the current view reflects healthy, stale, diverged, or reconciling packer state.
- what the canonical symbolic asset address is when Studio surfaces compile-facing identity.
The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework. The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.
@ -133,7 +134,8 @@ Rules:
- `Preload` - `Preload`
- The navigator must support textual search. - The navigator must support textual search.
- Baseline search must cover at least: - Baseline search must cover at least:
- `asset_name` - canonical asset address
- `asset_name` when still present as an editorial label
- asset root path - asset root path
- path context - path context
@ -156,6 +158,7 @@ Rules:
- If an asset changes state while preserving identity, selection must remain attached to it. - If an asset changes state while preserving identity, selection must remain attached to it.
- If the selected asset is removed from the navigator, selection must clear explicitly. - If the selected asset is removed from the navigator, selection must clear explicitly.
- Selection must never silently drift to another asset due to refresh ordering. - Selection must never silently drift to another asset due to refresh ordering.
- If the selected asset keeps the same `asset_id` but its canonical address changes after a move or rename, Studio must preserve selection and refresh the visible address.
### Local Rendering Rules ### Local Rendering Rules
@ -206,7 +209,8 @@ Rules:
- `Summary` must always be present for a selected asset. - `Summary` must always be present for a selected asset.
- `Summary` must show: - `Summary` must show:
- `asset_name` - canonical asset address
- `asset_name` when available as an editorial label
- registration status - registration status
- build participation - build participation
- `asset_id` when available - `asset_id` when available
@ -258,6 +262,16 @@ Rules:
- Sensitive actions must not look interchangeable with routine actions. - Sensitive actions must not look interchangeable with routine actions.
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated. - `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.
- Automatic relocation targets are not sufficient Studio UX for `Relocate`. - Automatic relocation targets are not sufficient Studio UX for `Relocate`.
## Namespace Collision Rule
Studio must respect the symbolic asset namespace contract used by compile-time authoring surfaces.
Rules:
- Studio must not allow creation of a new asset root whose canonical address would collide with an existing terminal asset or namespace prefix.
- Studio must not allow a terminal asset root to coexist with descendant asset roots that would require the same canonical path to act as both terminal and namespace.
- If a move or rename would create such a collision, Studio must block the action and surface the conflict explicitly.
- `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel. - `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel.
## Activity, Progress, and Logs Rules ## Activity, Progress, and Logs Rules