Crate loom_snapshot 

loom_snapshot - deterministic, cross-language world-state snapshot hash (Rust core).

The native sibling of the TS world-state-snapshot.ts. v3.0 Phase 1 of the Living Persistent World: a world state reduces to a state_hash that is BYTE-IDENTICAL across TypeScript, Python, and Rust, so a snapshot at a known event index can be persisted compactly, verified against the HMAC event chain on resume, and compared across languages to prove no surface diverged.

REUSE, not re-implementation. The hash rides loom_events’ audited, golden-vector-pinned primitives: state_hash = hmac_sha256_hex(key, field(SNAPSHOT_DOMAIN) + field(canonical_json(state))) so it inherits cross-language byte-parity for free and adds no new canonical or crypto surface. Parity is proven by the shared golden vector (test_vectors/v3_0_snapshot_canonical.json), which is generated by the real TS and asserted here byte-for-byte.

DESIGN (reconciled with the Pantheon, matches the TS module):

• The state_hash is a PURE content hash; the event index is version metadata stored alongside in WorldStateSnapshot, never folded into the hash.
• ONE sort rule everywhere: UTF-16 code units. Object keys are sorted by canonical_json (UTF-16); normalize_tags sorts tags by the SAME comparator (encode_utf16), NOT Rust’s native str Ord (UTF-8 bytes).
• Fail-closed: canonical_json returns Err(CanonError) on any non-canonical value (non-integer / -0 / unsafe-int / __proto__ / over-depth) before a hash is produced.

Domain separation: SNAPSHOT_DOMAIN is distinct from the event-chain record (“loom.chain.rec/1”) and seal (“loom.chain.seal/1”) domains, so a snapshot hash can never be reinterpreted as a chain-record signature.

Structs

WorldStateSnapshot

A snapshot commitment: WHICH event index, and the pure content hash of the state at that index.

Constants

MAX_SAFE_EVENT_INDEX

The max event index that survives a JSON round-trip into JS (Number.MAX_SAFE_INTEGER, 2^53-1). The TS snapshotWorldState rejects an unsafe event index at creation; Rust matches it (audit P1) - otherwise a Rust-made snapshot’s index could silently round on the JS side and select the wrong replay tail even though state_hash itself is content-only.

SNAPSHOT_DOMAIN

Namespace tag for snapshot HMACs. The trailing /1 is a format version. MUST match the TS SNAPSHOT_DOMAIN verbatim.

Functions

canonical_world_state

The canonical (deterministic, injective) JSON encoding of a world state. Byte-identical to the TS canonicalWorldState.

global_region_hash

The GLOBAL region hash: HMAC over the canonical map of region leaf hashes (the 2-level Merkle root). Byte-identical to the TS globalRegionHash. Interest management: a partial-sync client verifies its own region leaf + this root without the full world.

normalize_tags

Deterministically de-duplicate + sort a tag list by UTF-16 code unit - the SAME ordering canonical_json uses for object keys (ONE sort rule). Do NOT use Rust’s native slice::sort on String here: that is UTF-8 byte order, which diverges from the TS normalizeTags (and JS key sort) on astral chars.

region_leaves

Per-region leaf hashes { regionId: regionHash } (a region is a world-state-shaped partition). Byte-identical to the TS regionLeaves; the leaf order is irrelevant because the map is key-sorted by canonical_json when it is hashed.

snapshot_world_state

Take a snapshot: the (event_index, state_hash) commitment. Fails closed if event_index exceeds the JS-safe range (so the metadata stays portable across the TS / Python / Rust surfaces).

verify_world_snapshot

Verify a world matches an expected snapshot hash. Constant-time over the hex (no early-exit timing leak), so it is safe as an integrity gate on an untrusted resumed snapshot: a mismatch means do NOT trust the state.

world_state_hash

Compute the pure content hash of a world state. Cross-language byte-identical to the TS worldStateHash. Err fail-closed on any non-canonical state.