prometeu-studio/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md

Asset Workspace, Registry, and Stable Identity Agenda

Status

Closed

Resolved by 001-asset-workspace-registry-and-stable-identity-decision.md.

Purpose

Close the packer model for managed assets, registry truth, anchor files, and stable asset identity.

Context

The draft proposes a Git-like workspace:

• assets/ may be messy,
• assets/.prometeu/index.json is the source of truth,
• a managed asset is anchored by asset.json,
• each asset has asset_id and asset_uuid.

This is the core model of the packer. If it stays vague, all later specs become unstable.

For this agenda, the intended unit of management is the asset root, not each individual source file. That means one managed asset should have one dedicated root directory containing one anchor asset.json, while that asset may aggregate many internal input files.

Example consequence:

• an image atlas asset may own many sprite source images and palette files under the same asset root;
• those internal files are inputs of the managed asset, not separate managed assets by default.

Source Sections

• 4. Mental Model: A "Git-like" Asset Workspace
• 5. Core Concepts
• 6. Directory Structure and Control Files

Key Questions

1. Is index.json the sole source of truth, or does asset.json also carry authority?
2. What is the exact relationship between registry entry and anchor file?
3. Which fields are stable identity and which are mutable presentation?
4. Can an asset move directories without changing identity?
5. How should orphaned asset.json files be interpreted?
6. What is the normative lifecycle of asset_id allocation and persistence?
7. Is the unit of management a single source file or an asset root directory containing many inputs?

Closed Answers

The following points are considered directionally closed for this agenda:

1. index.json is the authoritative registry of managed assets.
2. asset.json is the asset-local declaration anchored at the asset root.
3. One managed asset maps to one asset root directory containing exactly one anchor asset.json.
4. A managed asset may aggregate many internal input files without making each input a separate managed asset.
5. asset_id is stable within the project and must never be silently recycled.
6. Move or rename of the asset root must not change asset_id or asset_uuid.
7. Orphaned asset.json files do not enter the build automatically; they are surfaced by diagnostics and adoption flows.

Allocation Direction

asset_id should be allocated by a strictly monotonic project-local allocator recorded in index.json.

Current recommendation:

• no reuse of prior IDs;
• no silent rollback of the counter;
• allocator state persisted in index.json;
• if creation metadata is useful, record creation date separately instead of encoding date logic into the identity itself.

Rationale:

• the runtime-facing ID should stay simple and stable;
• a plain monotonic numeric allocator is easier to audit and reason about than a day-scoped composite allocator;
• practical u32 exhaustion is not a realistic concern for normal project lifecycles.

Options

Option A

Treat index.json as the authoritative registry and asset.json as the asset-local contract.

Option B

Treat both as co-authoritative and reconcile divergences dynamically.

Tradeoffs

• Option A is easier to reason about and easier to validate.
• Option A enables clean diagnostics when local anchor and registry diverge.
• Option B increases reconciliation complexity and invites ambiguous conflict handling.

Recommendation

Adopt Option A:

• index.json is the authoritative registry,
• asset.json is the authoritative asset-local declaration,
• divergence between them must be explicit and diagnosable.

Also adopt this structural rule:

• one managed asset maps to one asset root directory;
• that asset root contains exactly one anchor asset.json;
• the asset may contain many internal input files without making each input a separate managed asset.

Also adopt this identity rule:

• asset_id is allocated once and never reused silently within the project;
• allocator state is registry-owned;
• date or audit metadata may exist, but it should not complicate the runtime-facing identity model unless a concrete need appears later.

Expected Decisions to Produce

1. Registry authority model.
2. Managed asset lifecycle.
3. Identity model for asset_id, asset_uuid, name, and path.
4. Rules for relocation, adoption, forgetting, and removal.
5. Asset root as the normative unit of management.
6. Monotonic, non-recycled asset_id allocation owned by the registry.

Expected Spec Follow-up

• Workspace and control files spec.
• Managed asset and identity spec.
• Registry consistency and validation spec.

Non-Goals

• Detailed build output layout.
• CLI syntax for every command.
• Format-specific asset.json payload definitions.