From e0c57814e1961b413e48f8d21db5c82783170048 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 27 Mar 2026 17:01:40 +0000 Subject: [PATCH] implements PLN-0005 --- discussion/index.ndjson | 2 +- ...-asset-address-surface-spec-propagation.md | 4 +-- .../pbs/12. Diagnostics Specification.md | 10 ++++++ .../13. Lowering IRBackend Specification.md | 16 ++++++++- .../pbs/4. Static Semantics Specification.md | 21 ++++++++++++ ...tdlib, and SDK Resolution Specification.md | 33 +++++++++++++++++-- ... Standard Library Surface Specification.md | 8 +++++ ...RBackend to IRVM Lowering Specification.md | 7 ++++ ...istry, and Asset Identity Specification.md | 19 ++++++++++- ...and Deterministic Packing Specification.md | 3 +- ...s, and Studio Integration Specification.md | 12 +++++++ .../4. Assets Workspace Specification.md | 18 ++++++++-- 12 files changed, 143 insertions(+), 10 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 98c81a5a..dcecd0b2 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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-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-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-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"}]} diff --git a/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md b/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md index 4b745fd0..110d9767 100644 --- a/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md +++ b/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md @@ -2,9 +2,9 @@ id: PLN-0005 ticket: pbs-game-facing-asset-refs-and-call-result-discard title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs -status: review +status: done created: 2026-03-27 -completed: +completed: 2026-03-27 tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract] --- diff --git a/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md b/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md index 7433e1cc..3815be05 100644 --- a/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md +++ b/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md @@ -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. diff --git a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md index 4741307b..dde0224f 100644 --- a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md +++ b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md @@ -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: diff --git a/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md b/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md index a24639f6..e3250f8f 100644 --- a/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md +++ b/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md @@ -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`. +- 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 diff --git a/docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md b/docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md index 7b870b7f..21a23fcb 100644 --- a/docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md +++ b/docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md @@ -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`. +- 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, diff --git a/docs/specs/compiler/18. Standard Library Surface Specification.md b/docs/specs/compiler/18. Standard Library Surface Specification.md index 1f2c093d..677955ac 100644 --- a/docs/specs/compiler/18. Standard Library Surface Specification.md +++ b/docs/specs/compiler/18. Standard Library Surface Specification.md @@ -156,6 +156,14 @@ Rules: - 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`. +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 For the current builtin MVP, stdlib should be able to expose at least: diff --git a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md index 74288b4c..1034b76b 100644 --- a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md +++ b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md @@ -114,6 +114,12 @@ For PBS executable lowering: `CALL_HOST` lowers to pre-load `HOSTCALL `, 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 `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, 6. callsite arity consistency, 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. diff --git a/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md b/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md index 405cd9f5..50e0c35b 100644 --- a/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md +++ b/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md @@ -46,7 +46,10 @@ The following are not primary identity: - filesystem path - 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 @@ -73,6 +76,20 @@ Rules: 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 An `asset.json` without a corresponding registry entry is an unregistered asset root. diff --git a/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md b/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md index c509b85b..10fcb271 100644 --- a/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md +++ b/docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md @@ -77,7 +77,8 @@ Rules: - one entry per included asset in the current build set; - no secondary runtime-only identity 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 diff --git a/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md b/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md index 9a52c3f4..ca3f8954 100644 --- a/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md +++ b/docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md @@ -52,6 +52,7 @@ Rules: - 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 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 @@ -223,6 +224,17 @@ Rules: - 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. +## 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 Rules: diff --git a/docs/specs/studio/4. Assets Workspace Specification.md b/docs/specs/studio/4. Assets Workspace Specification.md index f44707a1..ddb5b927 100644 --- a/docs/specs/studio/4. Assets Workspace Specification.md +++ b/docs/specs/studio/4. Assets Workspace Specification.md @@ -71,6 +71,7 @@ The workspace must help the user understand: - what the asset declares toward the runtime-facing contract; - which operations are safe, staged, blocked, or destructive; - 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. @@ -133,7 +134,8 @@ Rules: - `Preload` - The navigator must support textual search. - Baseline search must cover at least: - - `asset_name` + - canonical asset address + - `asset_name` when still present as an editorial label - asset root path - path context @@ -156,6 +158,7 @@ Rules: - 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. - 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 @@ -206,7 +209,8 @@ Rules: - `Summary` must always be present for a selected asset. - `Summary` must show: - - `asset_name` + - canonical asset address + - `asset_name` when available as an editorial label - registration status - build participation - `asset_id` when available @@ -258,6 +262,16 @@ Rules: - Sensitive actions must not look interchangeable with routine actions. - `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`. + +## 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. ## Activity, Progress, and Logs Rules