Implement native inventory store and cache (#61)

docs/inventory.md

@@ -0,0 +1,38 @@
+# 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.