99 lines
2.5 KiB
Markdown
99 lines
2.5 KiB
Markdown
# 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 is grounded in:
|
|
|
|
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
|
|
|
|
## 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.
|