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

Workspace, Registry, and Asset Identity Specification

Status: Draft Scope: Managed 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 managed 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 managed assets.
4. asset.json is the authoritative asset-local declaration.
5. An asset root absent from the registry is not part of the managed build set.

Identity Model

Each managed asset has:

• asset_id: stable project-local identity
• asset_uuid: stable long-lived identity for migration/tooling scenarios

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.

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.

Orphan Anchors

An asset.json without a corresponding registry entry is an orphan declaration.

Rules:

• it does not enter the build automatically;
• it is diagnosable;
• it is adoptable only through explicit flow.

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 managed expectations;
• manual copy that creates identity collision;
• registered root missing anchor.

Non-Goals

• full asset.json schema
• asset format-specific metadata
• UI/editor workflow detail

Exit Criteria

This specification is complete enough when:

• managed asset boundaries are unambiguous;
• registry authority is explicit;
• identity survives relocation without ambiguity.