# Inventory models, hierarchy, and cache

The native inventory layer mirrors the value and hierarchy behavior of
LibreMetaverse's `InventoryBase`, `InventoryItem`, `InventoryFolder`,
`InventoryNode`, and `Inventory` types without depending on a network
transport. Concrete item subclasses remain concrete when inserted, queried,
notified, or restored from disk; link detection is based on `AssetType`, not on
the Rust wrapper type. This preserves the C# misclassified-link behavior.

Store mutation is serialized by one inventory state lock. Parent/child and link
indexes and recursive item counts are rebuilt as one transaction, with cycle
and depth bounds. Missing parents become placeholder folders until their real
folder record arrives. Self-loops and longer parent cycles remain queryable but
are not linked into a cyclic ownership graph. Removing a folder removes its
bounded descendant subtree. Root and library roots are tracked independently,
and direct system folders can be found by `FolderType`. Sorting supports the
`ByDate`, `FoldersByName`, and `SystemFoldersToTop` flags.

Added, updated, and removed notifications clone their arguments and subscriber
list before invoking observers. No inventory, node, or subscriber lock is held
during a callback, so observers may safely query or mutate the store. A panic
in one observer is isolated by the shared event registry.

Cache files start with `INVCACHE`, a little-endian format version, owner and
root identities, and tagged concrete records. Reads are limited to 64 MiB,
one million records, one MiB per string, and a 512-level hierarchy. Invalid
magic, versions, UTF-8, enums, duplicate IDs, zero IDs, truncated records, and
trailing data are rejected before the live store is replaced. Synchronous
restore returns `-1` for compatibility; asynchronous restore returns the typed
error. Saves snapshot under the state lock, release it before I/O, write and
sync a same-directory temporary file, then replace the destination. The
replacement includes a rollback path on platforms that cannot rename over an
existing file.

The focused compatibility suites are
`inventory_store_semantics` and `misclassified_link_semantics`; native unit
tests additionally cover concrete cache round trips, permissions, corruption,
unknown versions, system-folder sorting, and callback re-entry.