implements PLN-0005
This commit is contained in:
parent
124c6d078e
commit
e0c57814e1
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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"}]}
|
||||
|
||||
@ -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]
|
||||
---
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -114,6 +114,12 @@ For PBS executable lowering:
|
||||
|
||||
`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
|
||||
|
||||
`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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user