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. An asset root absent from the registry is unregistered.
6. unregistered assets are always excluded from build participation.
7. Registered assets may be included or excluded from build participation without losing identity.
8. 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

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.

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.

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.

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.