163 lines
5.8 KiB
Markdown
163 lines
5.8 KiB
Markdown
# Workspace, Registry, and Asset Identity Specification
|
|
|
|
Status: Draft
|
|
Scope: Registered asset roots, registry authority, and stable identity
|
|
Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
|
|
|
|
## Authority and Precedence
|
|
|
|
This specification consolidates the initial packer agenda and decision wave into normative form.
|
|
|
|
## Normative Inputs
|
|
|
|
- `assets/`
|
|
- `assets/.prometeu/index.json`
|
|
- per-asset `asset.json`
|
|
|
|
## Core Rules
|
|
|
|
1. One registered asset equals one asset root directory.
|
|
2. One asset root contains exactly one anchor `asset.json`.
|
|
3. `assets/.prometeu/index.json` is the authoritative registry of registered assets.
|
|
4. `asset.json` is the authoritative asset-local declaration.
|
|
5. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
|
|
6. An asset root absent from the registry is `unregistered`.
|
|
7. `unregistered` assets are always `excluded` from build participation.
|
|
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
|
|
9. The baseline build set includes registered assets whose registry entry is marked as build-included.
|
|
|
|
## Identity Model
|
|
|
|
Each registered asset has:
|
|
|
|
- `asset_id`: stable project-local identity
|
|
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
|
|
- `included_in_build`: build participation flag persisted in the registry
|
|
|
|
Identity authority is intentionally split:
|
|
|
|
- `asset_uuid` is anchored locally in `asset.json`;
|
|
- `asset_id` is allocated and persisted by the registry;
|
|
- registry-managed location and build participation remain catalog concerns in `index.json`.
|
|
|
|
The following are not primary identity:
|
|
|
|
- `asset_name`
|
|
- filesystem path
|
|
- internal input file names
|
|
|
|
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
|
|
|
|
`asset_uuid` is the stable asset-local identity anchor.
|
|
|
|
Rules:
|
|
|
|
- `asset_uuid` must be present in `asset.json`;
|
|
- `asset_uuid` is stable across relocate and rename flows;
|
|
- `asset_uuid` is not allocated from path shape or `asset_name`;
|
|
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
|
|
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
|
|
|
|
## Relocation and Rename
|
|
|
|
Moving or renaming an asset root does not change identity.
|
|
|
|
Rules:
|
|
|
|
- `asset_id` remains unchanged;
|
|
- `asset_uuid` remains unchanged;
|
|
- registry location is updated;
|
|
- relocation is not recreation.
|
|
|
|
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.
|
|
|
|
Rules:
|
|
|
|
- it is excluded from the build automatically;
|
|
- it is diagnosable;
|
|
- it becomes registered only through explicit flow;
|
|
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
|
|
|
|
## Build Participation
|
|
|
|
Build participation is registry-owned for registered assets.
|
|
|
|
Rules:
|
|
|
|
- excluding a registered asset from builds does not remove `asset_id`;
|
|
- excluding a registered asset from builds does not remove `asset_uuid`;
|
|
- inclusion changes must preserve asset identity and registry location;
|
|
- unregistered assets cannot be marked as build-included.
|
|
|
|
## Asset ID Allocation
|
|
|
|
`asset_id` allocation is registry-owned and strictly monotonic within a project.
|
|
|
|
Rules:
|
|
|
|
- allocation occurs at registration time;
|
|
- issued IDs are not silently recycled;
|
|
- allocator state is persisted in the registry;
|
|
- rollback is not baseline behavior.
|
|
|
|
## Structural Conflicts
|
|
|
|
Identity-bearing conflicts are structural errors.
|
|
|
|
Examples:
|
|
|
|
- duplicate or ambiguous anchors under registered expectations;
|
|
- manual copy that creates identity collision;
|
|
- registered root missing anchor;
|
|
- duplicate `asset_uuid` across different asset roots;
|
|
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
|
|
- `asset.json` missing or malformed in a root expected to preserve identity.
|
|
|
|
## Reconcile Expectations
|
|
|
|
The packer may need to reconcile registry/catalog state against the authoring workspace.
|
|
|
|
Rules:
|
|
|
|
- manual move or rename of an asset root must not imply identity loss by itself;
|
|
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
|
|
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
|
|
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
|
|
|
|
## Non-Goals
|
|
|
|
- full `asset.json` schema
|
|
- asset format-specific metadata
|
|
- UI/editor workflow detail
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- registered asset boundaries are unambiguous;
|
|
- registry authority is explicit;
|
|
- identity survives relocation without ambiguity.
|