Module snapshot 

Snapshot container: the file format’s header, section table and checksums.

A snapshot is the engine’s memory image: a 64-byte header, the binary Config block, a section table, then the sections — each one a structure dump from plugmem-arena (dump_*/load methods there), everything 64-byte aligned:

[header 64][config][pad][table: n × 32][pad][section][pad]...

All container fields are little-endian. Byte layout of the header:

off	size	field
0	4	magic 0x504C_474D (“PLGM”)
4	2	format version (this module: 1)
6	2	flags (bit 0: vector section present; rest reserved zero)
8	2	section count
10	6	reserved, zero
16	4	config block length
20	8	file xxh3
28	8	created_at (informational, unix ms)
36	24	engine version, UTF-8, zero-padded (informational)
60	4	reserved, zero

and of one section-table entry:

off	size	field
0	2	kind
2	2	alignment (always 64)
4	4	reserved, zero
8	8	offset from file start
16	8	length
24	8	section xxh3

The file hash covers the whole file with the hash field zeroed (tightened relative to the original spec draft, which hashed only the bytes after the field and left the header prefix — notably flags — covered by nothing but field validation).

Trust model

Snapshot::parse treats its input as untrusted: every offset and length is bounds-checked with u64 arithmetic before any access, and the layout must be canonical (sections contiguous in table order, all padding zero, no trailing bytes) — arbitrary bytes can produce any Error but never a panic. The container xxh3 checksums are not verified at parse; that runs on demand, in slices, via Snapshot::scrub (the ZFS-scrub model), keeping an open sparse on large files.

Structs

Prefix

The header + config + section-table region of a snapshot: everything before the first section body. Small and bounded (kilobytes), so it is materialized even when the bodies stream.

ScrubCursor

A resumable, budget-bounded container-checksum scan over a parsed snapshot (— the ZFS-scrub model, run on demand instead of at open).

ScrubProgress

Progress of an in-flight ScrubCursor scan.

SectionMeta

One section’s size and checksum, computed in the streaming writer’s first pass (see build_prefix).

Snapshot

A parsed, validated snapshot borrowing the input buffer.

SnapshotWriter

Builds a snapshot file from section dumps.

Constants

DEFAULT_SCRUB_BUDGET

Default number of bytes a ScrubCursor hashes per next() slice The scrub slice-size bench sweeps 64 KiB…64 MiB and finds throughput essentially flat (the scan is xxh3/memory-bandwidth-bound, not per-slice-overhead-bound), so the budget is a pacing quantum, not a throughput knob: 1 MiB is ~sub-millisecond per slice — fine-grained enough to pause, cancel or report progress smoothly, with negligible overhead.

FILE_HASH_OFFSET

Absolute offset of the header file-hash field — the one location the streaming writer patches after the running hash is known.

FLAG_VECTORS

Flag bit: the image carries vector-layer sections.

FORMAT_VERSION

Snapshot format version written and accepted by this build.

MAGIC

"PLGM" interpreted as a little-endian u32.

Traits

SnapshotSink

A byte sink for streaming a snapshot without materializing the whole image: write appends in file order, patch overwrites a short run at an absolute offset — used once for the header file-hash field, the only non-sequential write, done after the body has streamed.

Functions

build_prefix

Lays out the header, config block and section table from per-section (kind, len, hash) metadata (the streaming writer’s first pass), byte for byte identical to SnapshotWriter::finish’s leading region. The caller then streams each section body followed by pad_len zero bytes, feeding a running Xxh3 the prefix and every body/pad byte, and finally calls SnapshotSink::patch.

pad_len

Alignment-padding length that follows a section body of len starting at offset (zero bytes up to the next 64-byte boundary).