Module zwinder 

Zwinder-class compressed, density-tiered state manager (v1.7.0 “Forge” Workstream D2).

This is the compressed successor to the v1.6.0 uncompressed greenzone (rustynes-frontend::tastudio::greenzone::Greenzone) and the v1.5.0 keyframe-cached rewind ring (crate::rewind::RewindRing). It is the state engine that lets the TAStudio greenzone scale to feature-length TASes: thousands of frames of seekable history in a fixed RAM budget.

Source / lineage

Clean-room port of the BizHawk Zwinder concept (BizHawk/src/BizHawk.Client.Common/rewind/ZwinderBuffer.cs + tasproj/ZwinderStateManager.cs), distilled to the determinism-critical essentials:

• Frame-keyed snapshots stored sorted ascending by frame, like the uncompressed greenzone.
• XOR-delta + LZ4 compression. Each stored frame is either a keyframe (a full LZ4-compressed snapshot) or a delta (an LZ4-compressed byte-XOR against the nearest preceding keyframe). NES state changes slowly between adjacent frames, so most delta bytes are zero and LZ4 crushes them.
• Density tiers (current / recent / ancient). The frames near the playhead are kept dense (cheap to seek into); the distant past decays to a sparse skeleton, thinned first by eviction.
• Reserved anchors (frame 0, markers, branch points) are never evicted and are always stored as keyframes (so they decode without a dependency).
• A byte budget with density-tiered eviction, identical in spirit to the uncompressed greenzone’s policy — but operating on the compressed sizes, so the same RAM holds far more history.

Determinism contract (the D2 gate)

Compression is lossless: restore(compress(store(s))) == s byte-for-byte. This is the determinism-critical invariant — the round-trip equality test (round_trip_equality_lossless in this module’s tests, plus the integration test in rustynes-test-harness) is the gate. There is no timebase change: the manager only stores and returns the exact deterministic save-state blobs the core already produces, so it cannot perturb emulation.

This type is #![no_std] + alloc-only and deliberately decoupled from the emulator: it stores opaque snapshot byte-blobs keyed by frame, so its compression / eviction / lookup logic is pure and unit-testable without a running crate::Nes.

Structs

ZwinderStateManager

A compressed, density-tiered, byte-budgeted history of frame-keyed save-states. See the module docs for the design.

Enums

ZwinderError

Errors raised when a stored Zwinder frame can’t be reconstructed.

Constants

ZWINDER_DEFAULT_BUDGET_BYTES

Default byte budget for the Zwinder store — 256 MiB. With XOR-delta + LZ4 this holds tens of thousands of greenzone frames (feature-length TASes).

ZWINDER_DEFAULT_KEYFRAME_INTERVAL

Default keyframe interval: every Nth stored frame is a full keyframe.