Crate loom_epoch 

loom_epoch - the deterministic between-session Epoch world-tick (Rust core).

v3.0 Phase 3 (Living Persistent World). The native sibling of the TS src/runtime/world-epoch.ts. While a player is offline the world must keep moving - factions act, regions shift - WITHOUT the session/combat PRNG and WITHOUT any non-determinism, so the browser client and the authoritative server arrive at the BYTE-IDENTICAL world-state hash for the same epoch.

THE THREE GUARANTEES (all cross-language byte-parity, pinned by test_vectors/v3_3_epoch_tick.json):

1. PRNG ISOLATION. The Epoch PRNG is seeded from SHA-256(UTF8(world_id) || LE64(epoch_number)) - a fresh, PUBLIC derivation that never touches the session PRNG. digest[0..8] LE -> state, digest[8..16] LE |1 -> inc, built straight into Pcg32::from_raw with NO seeding steps.

2. DETERMINISTIC ORDER + FAIL-CLOSED RESOLUTION. Offline actors are the entities carrying an actor tag; they resolve in compare_ids order. A proposal naming an unknown action, or failing AST validation, or erroring mid-eval is REJECTED and consumes ZERO prng + ZERO state change (prng snapshot/restore + the AST’s clone-not-mutate contract). Reason codes are assigned HERE at fixed decision points - never parsed from error text - so they are identical on every surface.

3. BOUNDED COST. tick_epoch caps SUCCESSFUL resolutions at max_actions; catch_up_epochs caps replayed epochs at max_catchup. Both are PARAMETERS, never hardcoded.

Structs

CatchUpInput

CatchUpResult

TickEpochInput

TickEpochResult

Constants

DEFAULT_ACTOR_TAG

The default tag marking an entity that acts while the owner is offline.

MAX_SAFE_INT

The JS-safe integer bound (2^53 - 1). Epoch / catch-up / cap inputs beyond this are rejected at the JSON boundary, matching the TS/Python guards (and keeping the emitted event JSON hashable). Codex P1.

RESOURCE_WORLD_EPOCH

Resource key for the world’s resource registry (matches the TS constant).

Functions

catch_up_epochs

Deterministically replay offline epochs from state.epoch up to current_epoch, capped at max_catchup. Result depends only on (state, capped, proposals) - never on the wall clock directly. Errs (never panics) on a non-NFC world_id (round-6 audit HIGH).

catch_up_epochs_from_json

JSON-in / JSON-out catch_up_epochs WITH full input validation. Input: {worldId, state, currentEpoch, maxCatchup, ruleset, proposalsByEpoch?, actorTags?, maxActions?}. Returns {state, events, epochsResolved, epochsVoided}.

derive_epoch_prng

Derive the Epoch PRNG for (world_id, epoch_number). PUBLIC + deterministic: any surface computes the same PRNG from these two inputs.

is_safe_epoch

True iff n is a JS-safe integer epoch (|n| <= 2^53 - 1).

tick_epoch

Resolve one offline epoch. Pure: does not mutate input.state. Returns the new state (epoch advanced) + the canonical EpochResolved event. Errs (never panics) on a non-NFC world_id - the same inputs TS/Python throw on (round-6 audit HIGH).

tick_epoch_from_json

JSON-in / JSON-out tick_epoch WITH full input validation - the boundary the WASM