prometeu-studio/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md

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.