Files
prometeu-studio/docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

193 lines
7.8 KiB
Markdown

# 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. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
6. An asset root absent from the registry is `unregistered`.
7. `unregistered` assets are always `excluded` from build participation.
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
9. 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
Identity authority is intentionally split:
- `asset_uuid` is anchored locally in `asset.json`;
- `asset_id` is allocated and persisted by the registry;
- registry-managed location and build participation remain catalog concerns in `index.json`.
The following are not primary identity:
- `asset_name`
- filesystem path
- internal input file names
The packer may also derive a canonical symbolic address from the asset root path for compile-time authoring surfaces.
That derived address is not a replacement for registry authority over `asset_id`.
`asset_name` may still exist as an authoring label, but it is not the operational compile-time identity used by the backend-owned symbolic asset surface.
## Local Identity Anchor
`asset_uuid` is the stable asset-local identity anchor.
Rules:
- `asset_uuid` must be present in `asset.json`;
- `asset_uuid` is stable across relocate and rename flows;
- `asset_uuid` is not allocated from path shape or `asset_name`;
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
## 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.
Renaming or moving an asset root may change the derived canonical symbolic address used by compile-time symbolic references, even when `asset_id` and `asset_uuid` remain stable.
## Canonical Symbolic Address Projection
The packer runtime may project a canonical symbolic asset address derived from the asset root under `assets/`.
Rules:
- The canonical symbolic address is derived from the normalized relative asset root path.
- The canonical symbolic address is a projection for backend/frontend compile-time consumption.
- The canonical symbolic address MUST NOT replace registry ownership of `asset_id`.
- The backend may publish the projected symbolic address through a frontend-facing surface contract without exposing the raw packer snapshot format.
- `asset_name` MUST NOT be required as the operational key for this projected symbolic address.
## 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;
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
## 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;
- duplicate `asset_uuid` across different asset roots;
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
- `asset.json` missing or malformed in a root expected to preserve identity.
## Reconcile Expectations
The packer may need to reconcile registry/catalog state against the authoring workspace.
Rules:
- manual move or rename of an asset root must not imply identity loss by itself;
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
## 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.
## Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
## Revision-checked authoring batches
The packer project write lane MUST support previewed atomic batches spanning
declared asset bytes, manifests, registry and related Studio metadata. Preview
leaves published state unchanged. Revalidate the complete input revision and
relevant source hashes immediately before commit. Shared reads/builds/writes
MUST observe the old complete batch or the new complete batch, with durable
journal recovery before admission after interruption.
Registration continues to allocate identity through this registry. An
uncommitted staged allocation is not an issued published identity. Identical
reimport MUST preserve UUID/AssetId, stable artifact IDs, selected order, output
hashes and references; append MUST NOT renumber existing glyphs/artifacts.
Incompatible replacement, removal or size/order/layout change requires complete
affected-reference analysis and explicit rebind in the same batch.
Cancellation/failure before commit leaves the old published state. After the
commit point, retained result/recovery reports the applied state rather than
claiming rollback. Request/batch correlation supports response-loss recovery
without acting as authority. The write lane coordinates participating services;
external writers that ignore it are detected by revision revalidation rather
than claimed to be serialized.