Crate oxgraph_snapshot 

Topology-agnostic byte-level snapshot container.

oxgraph-snapshot defines a sectioned, zero-copy checkpoint format that can validate, package, and read immutable topology snapshots without knowing whether their contents are graphs, hypergraphs, or anything else. Section semantics belong to upper layers (oxgraph-csr, oxgraph-graph, oxgraph-hyper); the container only validates and exposes byte-aligned section payloads.

Format overview

Every snapshot consists of a fixed HEADER_SIZE-byte header, a SECTION_ENTRY_SIZE-byte entry per section, and a payload region whose offsets and lengths are recorded in the entries. All multi-byte integer fields are little-endian and stored unaligned, so snapshots can be borrowed from any byte slice — Vec<u8>, mmap’d files, sub-slices — without an alignment requirement on the base pointer.

The container mandates two integrity invariants. Every section entry carries a CRC-32C over its payload bytes and the header carries a CRC-32C over the section-table bytes; the crate is no_std and bundles no CRC implementation, so writers and the checked/verify read paths take a Checksum32 function (e.g. oxgraph_layout_util::crc32c_append). Section kinds must be strictly ascending across the table, which makes the table duplicate-free and Snapshot::section a binary search.

Section payloads are exposed as byte slices via Section::bytes; the Section::try_as_slice helper checks the actual payload pointer’s alignment against align_of::<T>() so consumers can reinterpret &[u8] as &[T] only when it is safe to do so.

Cargo features

• default: reader-only API; no_std, no allocation.
• alloc: enables [SnapshotWriter], the owning write-through encoder that returns encoded Vec<u8> bytes.
• std: reserved for future mmap helpers; no effect beyond activating alloc.

Stability

The bytes are intentionally not yet promised as a stable ABI: a snapshot whose format major does not match this library is rejected at open. Format minor bumps will preserve backward read compatibility once they ship.

Modules

kinds

Section-kind band allocation registry: the single documented authority for who owns which range of the opaque u32 kind namespace.

Structs

HeaderOnlySnapshot

Header-only handle to a snapshot’s bytes.

PendingSection

Description of one section to include in a snapshot.

Section

Borrowed view of one validated section in a snapshot.

SectionIter

Iterator over a snapshot’s validated sections.

SectionKind

Typed wrapper over a section’s opaque u32 kind tag.

Snapshot

Validated, borrowed handle to a snapshot’s bytes and section table.

SnapshotPlan

Validated plan that can compute its encoded length and write itself.

Enums

PlanError

Error returned by snapshot writers.

SectionBindError

Error returned when binding a width-typed section by kind and version.

SectionViewError

Error returned when borrowing a section payload as a typed slice fails.

SnapshotError

Snapshot container validation error.

ValidationLevel

Validation depth applied at snapshot open time.

Constants

CRC32C_CHECK_INPUT

Standard CRC-32C check-vector input (the ASCII digits 123456789).

CRC32C_CHECK_VALUE

Standard CRC-32C check-vector result: crc32c(0, b"123456789").

FORMAT_MAGIC

Magic bytes identifying the topology snapshot container format.

FORMAT_MAJOR

Format major version this library reads and writes.

FORMAT_MINOR

Format minor version written by this library’s builder.

HEADER_SIZE

Size of the snapshot header in bytes.

MAX_ALIGNMENT_LOG2

Maximum permitted alignment_log2 value (2^12 = 4 KiB, page-friendly).

MAX_SECTION_COUNT

Maximum permitted section count for v2 snapshots.

MAX_SUPPORTED_MINOR

Highest format minor version this library can read.

SECTION_ENTRY_SIZE

Size of one section table entry in bytes.

Functions

patch_section_crc

Recomputes and patches one section’s entry CRC-32C (and the header’s table_crc32c, which covers that entry) in already-encoded snapshot bytes.

Type Aliases

Checksum32

Continuation-style CRC-32C (Castagnoli, polynomial 0x1EDC_6F41) fold.