MetaCrate/docs/assets.md

# Asset models, transfers, and cache

The native asset layer owns the client-facing asset boundary from typed bytes to
transport and persistence. `Asset` retains its UUID, asset type, temporary flag,
and mutable raw payload. Concrete animation, sound, script, calling-card,
landmark, settings, mesh, texture, wearable, and notecard models enforce a 64 MiB
input ceiling and reject malformed structured formats with typed errors. Mesh and
settings parsing use StructuredData. Texture encode/decode uses the imaging
crate's bounded `jpeg2000` adapter, while the opt-in `vorbis` feature streams
PCM conversion through bounded planar Ogg Vorbis blocks; neither API exposes
codec implementation types. With either native codec feature disabled, its
public API remains present and returns a typed `InvalidOperation` for otherwise
valid input instead of discovering or linking a system codec implicitly.

`AssetManager` is client-owned and shares one `DownloadManager` and `AssetCache`.
ViewerAsset, GetMesh, GetTexture, and server-bake requests check the cache before
network I/O. Equal HTTP URIs share one in-flight request and its progress sinks;
each awaiting subscriber retains an independent cancellation token, so cancelling
one waiter cannot cancel the shared request for the others. Capability discovery
waits for the seed request's bounded completion rather than racing it.

When ViewerAsset is unavailable, asset and authenticated inventory requests use
LLUDP `TransferRequest`, `TransferInfo`, and `TransferPacket`. The receiver filters
by transfer UUID, preserves priority and source type, reassembles out-of-order
packets, limits announced data to 64 MiB, and sends `TransferAbort` on cancellation
or timeout. Inventory transfers include the agent, session, owner, task, item,
asset, and type parameters. Legacy Xfer downloads confirm each packet, enforce the
same bound, and publish only completely assembled results.

Small and large uploads use the simulator's `AssetUploadRequest`/Xfer handshake,
including packet confirmation and progress events. Baked texture and inventory or
task material uploads use their two-stage capability contracts and require a
complete response containing the new asset UUID. Upload size, cancellation, and
timeout failures remove their pending correlation state.

OAR and model workflows are native as well. The tar reader validates checksums,
ustar paths, entry kinds, offsets, counts, nesting depth, per-entry size, and
expanded size before exposing data. OAR output is sorted and uses fixed gzip and
tar metadata, so identical asset, object, terrain, parcel, and settings trees
produce identical bytes. Loading recognizes canonical `UUID_type.ext` asset
names, bounded RAW32 terrain, and typed region-settings XML. Archive paths never
escape their selected root, and symbolic or hard links are rejected.

`GltfDocument` accepts bounded JSON glTF 2.0 and GLB 2.0 documents, resolves data
URIs or caller-provided external buffers, validates buffer-view/accessor ranges,
and decodes normalized scalar, vector, matrix, skin, and animation data. JSON and
GLB output retain scenes, nodes, surfaces, materials, textures, skins, and
animations in stable order; multi-buffer GLB output aligns and rebases views.
Collada conversion applies declared units and up-axis orientation, resolves
profile-COMMON effects and material bindings, triangulates triangles/quads, and
confines referenced textures to the document directory. Mesh assets use stable
quantization and LLSD section ordering.

Model upload is deliberately opt-in. Offline resource/pricing payload generation
does no network I/O; live preparation discovers the completed capability and
inventory layers, includes real destination folders, permission masks, and the
configured cost, then honors cancellation through both pricing and upload calls.

The disk cache uses UUID-only filenames by default and confines custom filename
callbacks to the configured cache directory. Reads reject empty, oversized, or
non-regular files. Writes use uniquely named same-directory files, flush them,
and atomically rename them into place, making concurrent writers deterministic.
Pruning removes least-recently-accessed regular cache entries until usage is below 90% of
the configured maximum. Automatic pruning is activity-driven at the configured
millisecond interval, avoiding a permanent timer thread; cancellation is checked
between deletions. Clearing and pruning never inspect or delete files outside the
configured project/application cache directory.

Focused native tests in `asset_pipeline_semantics` cover real sound and texture
codec output, model typing, malformed mesh data, atomic cache replacement, cache
corruption, cached-image reconstruction, and pruning. The `caps_http`
deduplication case proves independent subscriber cancellation. Translated asset,
material, mesh, capability-upload, and cache compatibility cases provide the API
contract checks for this issue.