# ADR 0005: Prefab Instance and Asset Registry

## Status

Accepted for asset identity; structural ownership superseded by
[ADR 0027](0027-stable-prefab-ownership-and-variants.md)

## Context

Editor prefab placement and content pipeline work (H1/H2) require stable asset identity across sessions. The asset browser previously regenerated UUIDs on every sync, breaking references.

## Decision

- Persist stable `AssetId` (UUID) per `assets/` path in `assets/.index/registry.ron`.
- Scene-instance `ModelRef` stores the registry UUID plus a cached source path. Hydration resolves
  the UUID-keyed generated manifest first, allowing uniquely identified model moves to retain scene
  and animation references.
- Catalog refresh reconciles a missing model record to one new path only when its generated content
  hash has exactly one match. Copies and ambiguous matches receive new IDs.
- Introduce `PrefabInstance { asset_id, source_path, overrides_ron }` on placed prefab roots alongside hydration via `PrefabRef`.
- Scene save includes `PrefabInstance` and gameplay marker components from `shared`.
- The initial structural boundary treated instance contents as read-only and required Unpack before
  authored structural edits. ADR 0027 replaces that boundary with explicit generated-member
  ownership while retaining this ADR's asset and instance identity.

## Consequences

- Prefab paths can be resolved through the registry for dependency tracking.
- Override apply/revert (H2) builds on `overrides_ron` without changing the instance component shape.
- Stable child identity, authored local children, nested instances, variants, and recursive graph
  validation are defined by ADR 0027.
- Registry must be version-controlled with the project.
- Legacy path-only `ModelRef` values remain readable but require reassignment before they gain stable
  move resolution.