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

Asset Workspace, Registry, and Stable Identity Agenda

Status

Open

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.

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?

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.

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.

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.