133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
# Asset Workspace, Registry, and Stable Identity Agenda
|
|
|
|
## Status
|
|
|
|
Closed
|
|
|
|
Resolved by [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/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.
|