prometeu-studio/docs/packer/specs/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

asset_name may still be used by authoring and runtime-facing APIs as a logical reference label.

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.

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.