implements PLN-0005

This commit is contained in:
2026-03-27 17:01:40 +00:00
parent 124c6d078e
commit e0c57814e1
12 changed files with 143 additions and 10 deletions
@@ -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: