MetaCrate/docs/inventory.md

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.