Implement DEC-0084 with factory-only Sprite/Animator structs, complete result lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP authoring through shared services. Qualify native dev/release with ordinary and optimized producers, zero-allocation playback, private-cycle reclamation, canonical Composer pixels, installed JARs and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
6.4 KiB
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
- One registered asset equals one asset root directory.
- One asset root contains exactly one anchor
asset.json. assets/.prometeu/index.jsonis the authoritative registry of registered assets.asset.jsonis the authoritative asset-local declaration.asset.jsonmust carry the stableasset_uuididentity anchor for that asset root.- An asset root absent from the registry is
unregistered. unregisteredassets are alwaysexcludedfrom build participation.- Registered assets may be
includedorexcludedfrom build participation without losing identity. - 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 identityasset_uuid: stable long-lived identity for migration/tooling scenariosincluded_in_build: build participation flag persisted in the registry
Identity authority is intentionally split:
asset_uuidis anchored locally inasset.json;asset_idis 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_uuidmust be present inasset.json;asset_uuidis stable across relocate and rename flows;asset_uuidis not allocated from path shape orasset_name;asset_uuidallows the packer to reconcile manual workspace changes with the registry/catalog model;asset_uuiddoes not replace registry authority overasset_id, build participation, or managed root tracking.
Relocation and Rename
Moving or renaming an asset root does not change identity.
Rules:
asset_idremains unchanged;asset_uuidremains 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_nameMUST 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_uuidstill 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_uuidacross different asset roots; - registry/catalog location that no longer matches the asset root carrying the expected
asset_uuid; asset.jsonmissing 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_uuidwhen 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.jsonschema - 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.