snapshot

func ApplyCSRToGraph ¶

func ApplyCSRToGraph[N comparable, W any](g *lpg.Graph[N, W], rb *CSRReadback) error

ApplyCSRToGraph replays the adjacency in rb into g. The pre- condition is that g's underlying mapper has already been populated with every NodeID referenced by rb — typically by an immediately- preceding ApplyMapperToGraph (v3 snapshots) or by a WAL replay (v2 snapshots that pair with a WAL prefix). Records whose endpoints the mapper cannot resolve are skipped and counted via `store.snapshot.ApplyCSR.unresolved`; the function does not return an error for them so a partial mapper degrades cleanly rather than aborting recovery mid-way.

Weights in the DENSE native layout are decoded for the fixed-width primitives (int8/uint8/bool, int16/uint16, int32/uint32/float32, int/uint/int64/uint64/float64/uintptr). Weights in the codec-encoded layout are decoded through the supplied weight codec, which covers every other W.

The metric `store.snapshot.ApplyCSR.weightFallback` counts dense-layout slots that decoded to the zero value for want of bytes. It is NOT a signal that weights were lost to an unsupported type: that loss used to happen at WRITE time, where the file recorded "no weights" and there was nothing here to count. rmp #2526 removed that path — the writer now refuses — so this counter means a malformed file, not an unsupported weight type.

ApplyCSRToGraph is idempotent against a freshly-loaded mapper but not against a graph that already contains edges: re-applying a CSR to a graph with existing edges may duplicate them in multigraph mode or no-op in simple-graph mode. Callers should run this exactly once per recovery, immediately after the mapper restore and before any WAL replay.

rb is passed by pointer to avoid copying the three slices in the readback (vertices, edges, weight bytes) on every call. The function does not mutate rb.

A snapshot whose weights are codec-encoded cannot be applied through this entry point, which has no codec to decode them: it returns ErrWeightCodecRequired. Use ApplyCSRToGraphWithWeightCodec.

func ApplyCSRToGraphWithWeightCodec ¶ added in v0.12.0

func ApplyCSRToGraphWithWeightCodec[N comparable, W any](g *lpg.Graph[N, W], rb *CSRReadback, wdec weightDecoder[W]) error

ApplyCSRToGraphWithWeightCodec is the weight-codec-aware variant of ApplyCSRToGraph. wdec decodes the variable-width weights section written by WriteCSRWithWeightCodec; pass the owning store's codec, [txn.Store.WeightCodec].

A nil wdec is accepted and behaves exactly as ApplyCSRToGraph for every snapshot whose weights are in the dense native layout (the fixed-width primitives) or absent. It is refused with ErrWeightCodecRequired for a snapshot whose weights ARE codec-encoded: those weights are durably present on disk, and applying zero weights instead would discard committed data (rmp #2526).

CSR apply walks every src slot, resolves endpoints, decodes weight by W type

func ApplyEdgeHandlesToGraph ¶

func ApplyEdgeHandlesToGraph[N comparable, W any](g *lpg.Graph[N, W], rb EdgeHandlesReadback) error

ApplyEdgeHandlesToGraph replays rb into a live g, re-attaching every per-handle edge label and property keyed by its stable handle and the endpoint NodeID pair. It MUST run AFTER the mapper and CSR (with its handle column) are applied so the handle the record references is already live on the adjacency slot — though the per-handle metadata stores are keyed by (NodeID pair, handle) directly and do not require the adjacency edge to be present, so a record whose edge the CSR did not materialise is still re-attached harmlessly. The handle high-water counter is re-seeded for every record so a post-recovery edge creation never re-mints a live handle (invariant I5).

It returns an error wrapping lpg.ErrTokenTooLong when a record carries a relationship type or property key longer than lpg.MaxTokenLen bytes (rmp #2748): the engine refuses such a token on every write path, so a snapshot carrying one predates that bound, and loading it silently would hide the data it names. The error result is a breaking change: this function used to return nothing.

func ApplyLabelsToGraph ¶

func ApplyLabelsToGraph[N comparable, W any](g *lpg.Graph[N, W], rb LabelsReadback) error

ApplyLabelsToGraph replays rb into a live g. The pre-condition is that g's underlying mapper has already been populated with every NodeID referenced by rb — typically by replaying the WAL prefix covered by the snapshot, or by re-issuing the original AddNode / AddEdge calls. Records whose NodeID cannot be resolved by the mapper are skipped and counted via the `store.snapshot.ApplyLabels.unresolved` metric counter; the function does not return an error for them so a partial mapper degrades cleanly rather than aborting recovery mid-way.

Edge label records whose endpoints are resolvable but whose edge is absent from the adjacency list (e.g., the CSR was not yet applied) are likewise skipped and counted under `store.snapshot.ApplyLabels.edgeMissing`; this matches lpg.Graph.SetEdgeLabel's own no-op-on-missing-edge contract.

Per-slot versus per-pair replay ¶

From labels.bin version 2 ([labelsFormatVersionPerSlot]) each edge record names ONE place on the pair. A record carrying a canonical ordinal is replayed through lpg.Graph.SetEdgeRelTypeAtSlotByID, so a multigraph pair's parallel slots keep the types they actually carried; a record marked EdgeLabelSlotOverflow is replayed through lpg.Graph.AddEdgeRelTypeOverflowByID, restoring the pair-wide half of its type state. A record whose ordinal the live adjacency cannot resolve — the pair now holds fewer slots than the snapshot recorded — is skipped and counted under `store.snapshot.ApplyLabels.slotMissing` rather than being retargeted at some other slot, because guessing would be the very failure this format removes.

A version-1 readback (and any hand-constructed one, which leaves Version at zero) is replayed through lpg.Graph.SetEdgeLabel, which names the PAIR. That is exactly what those records meant when they were written; see [labelsFormatVersionPerSlot] for why an older file is read rather than rejected.

func ApplyMapperToGraph ¶

func ApplyMapperToGraph[N comparable, W any](g *lpg.Graph[N, W], rb MapperReadback) error

ApplyMapperToGraph rebuilds g's underlying graph.Mapper from the snapshot readback. It is only meaningful for string-keyed graphs: any other N type returns nil without touching g, because no v3 mapper.bin is ever produced for non-string graphs. The caller is expected to invoke this function before ApplyCSRToGraph, ApplyLabelsToGraph, or ApplyPropertiesToGraph so subsequent resolution calls see the restored interning table.

Pre-condition: g must hold a fresh (empty) mapper. Calling on a graph that already has interned values returns ErrMapperApply wrapping graph.ErrMapperNotEmpty so the caller can distinguish a programmer error from a corruption error.

Concurrency: ApplyMapperToGraph is not safe to call concurrently with mutations or reads on g. It is intended for the one-shot snapshot-load phase of recovery.

func ApplyMapperToGraphWithCodec ¶

func ApplyMapperToGraphWithCodec[N comparable, W any](g *lpg.Graph[N, W], rb MapperReadback, codec keyDecoder[N]) error

ApplyMapperToGraphWithCodec rebuilds g's underlying graph.Mapper from a version-2 (codec) snapshot readback for ANY comparable key type N. Each MapperRawPair carries the codec-encoded key bytes the snapshot writer produced via WriteMapper; this function decodes them back into N via the supplied codec (the same one the store uses on the WAL) and seeds the interning table through graph.Mapper.LoadFrom.

It is the codec-aware dual of ApplyMapperToGraph: recovery calls this when the loaded readback carries RawPairs (non-string keys) and the string-specialised path when it carries Pairs. An empty readback is a no-op.

Pre-condition and concurrency contract match ApplyMapperToGraph: g must hold a fresh (empty) mapper, and the call must not race with any other access to g. A decode failure surfaces as ErrMapperApply wrapping the codec error; a structural violation surfaces as ErrMapperApply wrapping the relevant [graph.ErrMapper…] sentinel.

func ApplyPropertiesToGraph ¶

func ApplyPropertiesToGraph[N comparable, W any](g *lpg.Graph[N, W], rb PropertiesReadback) error

ApplyPropertiesToGraph replays rb into a live g. The pre-condition is that g's underlying mapper has already been populated with every NodeID referenced by rb — typically by replaying the WAL prefix covered by the snapshot, or by re-issuing the original AddNode / AddEdge calls. Records whose NodeID cannot be resolved by the mapper are skipped and counted via the `store.snapshot.ApplyProperties.unresolved` metric counter; the function does not return an error for them so a partial mapper degrades cleanly rather than aborting recovery mid-way.

Edge property records whose endpoints are resolvable but whose edge is absent from the adjacency list (e.g., the CSR was not yet applied) are likewise skipped and counted under `store.snapshot.ApplyProperties.edgeMissing`; this matches lpg.Graph.SetEdgeProperty's own no-op-on-missing-edge contract.

apply: bounds + mapper resolve + edge resolve + kind decode

func ApplyTombstonesToGraph ¶

func ApplyTombstonesToGraph[N comparable, W any](g *lpg.Graph[N, W], rb TombstonesReadback) error

ApplyTombstonesToGraph replays rb into a live g, re-tombstoning every NodeID the snapshot recorded as removed. It must run AFTER the snapshot nodes are loaded (mapper + CSR) so the ids it restores reference the same stable slots; it re-tombstones by id directly via lpg.Graph.RestoreTombstones and so does not require the natural keys to be resolvable.

A later WAL re-create (OpAddNode) for any of these ids still revives it, preserving the chronology of a delete→recreate cycle that straddles the snapshot boundary.

It returns the error lpg.Graph.RestoreTombstones reports — lpg.ErrIndexedRawWrite when g already has a secondary index registered, which recovery never does because it applies the snapshot to a graph it has just constructed.

func ReadNodeIDs ¶ added in v0.16.0

func ReadNodeIDs(r io.Reader) (*[graph.MapperShards]uint64, error)

ReadNodeIDs parses a nodeids.bin from r.

func VerifyMapperDecodable ¶ added in v0.14.1

func VerifyMapperDecodable[N comparable](rb MapperReadback, codec keyDecoder[N]) error

VerifyMapperDecodable decodes every codec-encoded key in rb through codec and discards the decoded values, returning nil only when the readback would survive the decode step of ApplyMapperToGraphWithCodec — the call recovery makes on this same readback. It performs NO filesystem I/O: rb is already in memory, so the whole cost is CPU over bytes the caller has already read.

It exists for the checkpointer (rmp #2780). Parsing a published snapshot establishes that the reader accepts it; it does NOT establish that the applier accepts it, and the checkpointer discards the WAL prefix — the only other copy of the data — on the strength of the latter. A key whose encoding the codec refuses, or whose bytes the codec does not consume in full, passes LoadSnapshotFull and fails recovery.

An empty readback (a version-1 string mapper, whose keys carry no codec framing and land in MapperReadback.Pairs, or no mapper.bin at all) is a no-op and returns nil: there is nothing to decode. A nil codec with a non-empty MapperReadback.RawPairs is refused, exactly as ApplyMapperToGraphWithCodec refuses it — the keys cannot be verified and must not be assumed good.

What this does NOT establish ¶

The structural half of the apply — graph.Mapper.LoadFrom's intra-shard gap, hash/shard and duplicate-key invariants — is NOT checked here, because running it requires an interning table to load into, and the caller's purpose is to verify an image rather than to build a graph from it. Nor does it establish media durability: like the parse it accompanies, it reads bytes the process handed to the OS moments earlier.

Errors wrap ErrMapperApply and the underlying codec error, so callers can branch on either via errors.Is.

func WriteCSR ¶

func WriteCSR[W any](w io.Writer, c *csr.CSR[W]) (size int64, crc uint32, err error)

WriteCSR serialises c to w, returning the number of bytes written and the CRC32C of the serialised payload. The on-disk layout is:

uint64 nVertices      (little-endian)
uint64 nEdges
uint8  hasWeights     (1 = weights array present)
uint8  weightSizeBytes (0 when hasWeights = 0; 0xFF = codec-encoded)
[vertices]            (nVertices * 8 bytes)
[edges]               (nEdges * 8 bytes)
[weights]             (nEdges * weightSizeBytes bytes, when present)
uint8  hasHandles      (OPTIONAL trailing block; 1 = handle array present)
[handles]             (nEdges * 8 bytes, when hasHandles = 1)

WriteCSR persists weights only for the fixed-width primitives [csrWeightSize] knows. A graph whose weights are of any other type — a struct, a NAMED integer type such as time.Duration, a string — needs a weight codec, which this entry point does not take: it returns ErrWeightNotPersistable rather than writing a weightless snapshot, because a weightless snapshot would let the caller's checkpoint truncate the WAL prefix holding the only surviving copy (rmp #2526). Use WriteCSRWithWeightCodec to persist those weights.

The trailing handles block (Stage 2 of the stable-edge-handle work) is emitted ONLY when the source CSR carries a per-slot handle column (csr.CSR.HandlesSlice != nil). A graph that never used AddEdgeH produces no trailing block, so its csr.bin is byte-identical to one written before this column existed — the v1 golden and the cross-process byte-equality fixtures are unaffected. [readCSRLimited] detects the block by attempting to read one more byte after the weights array: present → handles follow, EOF → none (the backward-compatible read branch).

func WriteCSRWithWeightCodec ¶ added in v0.12.0

func WriteCSRWithWeightCodec[W any](w io.Writer, c *csr.CSR[W], wenc weightEncoder[W]) (size int64, crc uint32, err error)

WriteCSRWithWeightCodec is the weight-codec-aware variant of WriteCSR. It persists edge weights of ANY type W by encoding each one through wenc — pass the owning store's codec, [txn.Store.WeightCodec] — into a variable-width section indexed by an offsets array. See csr_weight_codec.go for the layout and the compatibility argument.

The codec is consulted ONLY for weight types the fixed-width path cannot size. A float64, int64 or int32 weight still takes the original dense native layout and the bytes are unchanged, so a snapshot written with a codec installed is byte-identical to one written without it whenever W is one of those types.

A nil wenc is accepted and behaves exactly as WriteCSR.

func WriteCapture ¶ added in v0.11.0

func WriteCapture[W any](dir string, capt *Capture[W], constraints []ConstraintSpec, indexDefs []IndexDefSpec) error

WriteCapture publishes a Capture taken earlier to dir, emitting constraints.bin from constraints and indexdefs.bin from indexDefs (each omitted when nil or empty). It touches no graph: every graph-derived byte was fixed when the Capture was taken, which is what lets a checkpointer publish LOCK-FREE while still writing a single-instant, transaction-boundary image (rmp #2269).

constraints and indexDefs must be captured by the caller in the SAME exclusion window as capt, or the published snapshot mixes two instants again.

func WriteCaptureFS ¶ added in v0.11.0

func WriteCaptureFS[W any](fsys fileSystem, dir string, capt *Capture[W], constraints []ConstraintSpec, indexDefs []IndexDefSpec) error

WriteCaptureFS is the filesystem-seam variant of WriteCapture, routing every filesystem operation through fsys. It is what the deterministic-simulation harness (internal/sim) publishes a capture through so it can crash mid-publish. Passing osBackend{} reproduces WriteCapture byte-for-byte.

The fsys parameter type ([fileSystem]) is intentionally unexported: an external package cannot name it but can still supply a value satisfying it (mirroring wal.OpenWith).

func WriteConstraints ¶ added in v0.2.0

func WriteConstraints(w io.Writer, specs []ConstraintSpec) (size int64, crc uint32, err error)

WriteConstraints serialises specs into w in the constraints.bin format. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the component so LoadSnapshotFull can verify integrity at load time.

The CRC32C covers the entire on-disk file, including the magic header, matching the tombstones.bin / labels.bin discipline. The records are emitted in deterministic order (kind, label, property, name) so the component is byte-identical across writes of the same logical state.

func WriteEdgeHandles ¶

func WriteEdgeHandles[N comparable, W any](w io.Writer, g *lpg.Graph[N, W], at *lpg.Snapshot) (size int64, crc uint32, emitted bool, err error)

WriteEdgeHandles serialises every per-handle edge label and property attached to g into w in the edgehandles.bin format. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry so LoadSnapshotFull can verify integrity at load time. It returns (0, 0, nil, false) when the graph carries no per-handle metadata, signalling the caller to omit the component entirely.

Records are emitted in the deterministic order lpg.Graph.WalkEdgeHandles yields (the same source-node order csr.bin / labels.bin use), and within a record the label names and property keys are sorted, so the component is byte-stable across writes of the same logical state — the cross-process byte-equality contract the snapshot relies on.

edgehandles write: collect + two string tables + per-record labels + per-record props, each guarded

func WriteIndexDefs ¶ added in v0.6.0

func WriteIndexDefs(w io.Writer, specs []IndexDefSpec) (size int64, crc uint32, err error)

WriteIndexDefs serialises specs into w in the indexdefs.bin format. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the component so LoadSnapshotFull can verify integrity at load time.

The CRC32C covers the entire on-disk file, including the magic header, matching the constraints.bin / tombstones.bin discipline. The records are emitted in deterministic order (kind, name, label, property) so the component is byte-identical across writes of the same logical state.

func WriteLabels ¶

func WriteLabels[N comparable, W any](w io.Writer, g *lpg.Graph[N, W], at *lpg.Snapshot) (size int64, crc uint32, err error)

WriteLabels serialises every node and edge label attached to g into w in the labels.bin format documented at the top of this file. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the labels.bin component so Open / LoadSnapshotFull can verify integrity at load time.

The CRC32C covers the entire on-disk file, including the magic header. This lets the manifest's CRC field validate every byte of labels.bin end-to-end without a separate inner-payload checksum.

The on-disk string table is populated by walking g's lpg.LabelRegistry in interning order; the labelStringIdx written for each (node | edge) record indexes into that table. Because LabelID is itself assigned in interning order, this preserves the registry's identity across save and load: the reader interns each name back in the same order and observes the same LabelID values without an extra remap step.

lpg.LabelRegistry is a lock-free, copy-on-write structure (see its own doc): there is no RLock held across the string-table emission and the later node/edge enumeration, which read the registry and the live graph independently, at different times, via the same lock-free / per-shard-RLock-only primitives the public LPG accessors expose. A name interned strictly between those two reads and immediately attached to a node/edge is therefore visible to the enumeration but absent from the already-captured string table: collectNodeLabelRecords / collectEdgeLabelRecords detect this and return a "not in registry snapshot" error. Rather than abort the whole checkpoint attempt on that race, WriteLabels re-captures and retries as one consistent unit (self-healing, bounded by [maxRegistryCaptureRetries]); because the registry is monotonic and append-only, a re-capture is guaranteed to include the newly-interned name, so the retry converges — in the steady state on the first attempt (#1880). Only sustained, adversarial schema churn that races every attempt exhausts the budget, in which case WriteLabels falls back to the prior fail-stop (return the error with nothing written or truncated — the identical fail-safe posture [Checkpointer.truncatePrefixLocked] uses for a schema DDL racing phase 2, #1774), never a Consistency violation.

func WriteManifest ¶

func WriteManifest(w io.Writer, m Manifest) error

WriteManifest writes m to w in canonical (pretty-printed) JSON followed by a CRC32C trailer over the whole document (see the integrity section on Manifest). It sets Manifest.Integrity on its own copy of m, so callers need not — and must not rely on the value they passed in surviving.

The document is buffered rather than streamed because the checksum must be computed over the finished bytes; it is also what makes the file reach w in a single Write.

func WriteMapper ¶

func WriteMapper[N comparable](w io.Writer, m *graph.Mapper[N], codec keyEncoder[N], include func(graph.NodeID) bool) (size int64, crc uint32, err error)

WriteMapper serialises every (NodeID -> key) pair held by m into w, generalising WriteMapperString to any comparable key type N via the supplied codec. It returns the number of bytes written and the CRC32C of the serialised payload, both recorded in the manifest's FileEntry for the mapper.bin component so LoadSnapshotFull can verify integrity at load time.

Back-compatibility: when N is the canonical string type the function delegates to WriteMapperString, which emits the frozen version-1 layout (raw UTF-8 key bytes, no codec framing). The on-disk image is therefore byte-identical to every string mapper.bin produced before the codec generalisation, regardless of which string codec is supplied. For any other N the function emits a version-2 layout whose per-record key bytes are the output of codec.Encode.

On-disk layout (version 2, all little-endian):

uint32  magic           ('GMAP', 0x50414D47)
uint16  formatVersion   (2)
uint64  pairCount
for each pair:
    uint64  nodeID
    uint32  keyLen       (length of the codec-encoded key bytes)
    [keyLen]byte key     (codec.Encode output for the natural key)

Pairs are emitted in graph.Mapper.Walk order (shard-major, intra-index-major) so the read side reconstructs the mapper deterministically. The CRC32C covers the entire on-disk file, including the magic header.

func WriteMapperString ¶

func WriteMapperString(w io.Writer, m *graph.Mapper[string], include func(graph.NodeID) bool) (size int64, crc uint32, err error)

WriteMapperString serialises every (NodeID -> string key) pair held by m into w in the mapper.bin format documented below. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the mapper.bin component so LoadSnapshotFull can verify integrity at load time.

On-disk layout (all little-endian):

uint32  magic           ('GMAP', 0x50414D47)
uint16  formatVersion   (1)
uint64  pairCount
for each pair:
    uint64  nodeID
    uint32  keyLen
    [keyLen]byte key

Pairs are emitted in graph.Mapper.Walk order (shard-major, intra-index-major) so the read side can reconstruct the mapper deterministically.

The CRC32C covers the entire on-disk file, including the magic header. The reader recomputes the CRC end-to-end at load time.

func WriteNodeIDs ¶ added in v0.16.0

func WriteNodeIDs(w io.Writer, next *[graph.MapperShards]uint64) (int64, uint32, error)

WriteNodeIDs serialises next to w and returns the byte count and the CRC32C of what it wrote.

func WriteProperties ¶

func WriteProperties[N comparable, W any](w io.Writer, g *lpg.Graph[N, W], at *lpg.Snapshot) (size int64, crc uint32, err error)

WriteProperties serialises every node and edge property attached to g into w in the properties.bin format documented at the top of this file. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the properties.bin component so LoadSnapshotFull can verify integrity at load time.

The CRC32C covers the entire on-disk file, including the magic header. This lets the manifest's CRC field validate every byte of properties.bin end-to-end without a separate inner-payload checksum.

The on-disk key string table is populated by walking g's lpg.PropertyKeyRegistry in interning order; the keyIdx written for each (node | edge) record indexes into that table.

Concurrency contract: lpg.PropertyKeyRegistry is a lock-free, copy-on-write structure (see its own doc), so the walk relies on the same lock-free / RLock-only primitives the public LPG accessors expose, with no RLock held across the key-table snapshot and the later node/edge enumeration — the identical structure WriteLabels uses for labels, and the identical narrow race applies: a key interned strictly between those two reads and immediately attached to a node/edge is visible to the enumeration but absent from the already-captured key table, which the collectors detect and reject with a "not in registry snapshot" error. As in WriteLabels, WriteProperties re-captures and retries the key-table snapshot plus record collection as one consistent unit (self-healing, bounded by [maxRegistryCaptureRetries]); the monotonic append-only registry guarantees the retry converges (#1880). Budget exhaustion under sustained churn falls back to the prior fail-stop — a clean abort of this checkpoint attempt with nothing written or truncated — never a silently inconsistent record.

func WriteSnapshotCSR ¶

func WriteSnapshotCSR[W any](dir string, c *csr.CSR[W]) error

WriteSnapshotCSR is the legacy high-level helper that lays a snapshot directory containing a v1 manifest plus the CSR. It is retained for backward compatibility: callers that also need LPG label durability must use WriteSnapshotFull which writes a v2 manifest with both csr.bin and labels.bin. Atomic publication is achieved by assembling the snapshot under dir + ".tmp" and renaming it to dir on success.

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/csr"
	"github.com/FlavioCFOliveira/GoGraph/store/snapshot"
)

func main() {
	dir, err := os.MkdirTemp("", "snapshot-csr-example")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(dir) }()

	a := adjlist.New[string, int64](adjlist.Config{Directed: true})
	if err := a.AddEdge("a", "b", 1); err != nil {
		panic(err)
	}
	if err := a.AddEdge("a", "c", 2); err != nil {
		panic(err)
	}
	c := csr.BuildFromAdjList(a)

	snapDir := filepath.Join(dir, "snapshot")
	if err := snapshot.WriteSnapshotCSR(snapDir, c); err != nil {
		panic(err)
	}

	loaded, err := snapshot.Open(snapDir)
	if err != nil {
		panic(err)
	}
	fmt.Printf("manifest version=%d\n", loaded.Manifest.Version)
	fmt.Printf("csr edges=%d\n", len(loaded.CSR.Edges))

}

Output:
manifest version=1
csr edges=2

func WriteSnapshotCSRCtx ¶

func WriteSnapshotCSRCtx[W any](ctx context.Context, dir string, c *csr.CSR[W]) error

WriteSnapshotCSRCtx is the context-aware variant of WriteSnapshotCSR. ctx.Err() is checked at three stage boundaries: before the CSR write, before the manifest write, and before the atomic rename. On cancellation the temporary staging directory is cleaned up and the wrapped ctx.Err is returned.

func WriteSnapshotFull ¶

func WriteSnapshotFull[N comparable, W any](dir string, c *csr.CSR[W], g *lpg.Graph[N, W]) error

WriteSnapshotFull is the v2/v3 high-level helper: it lays out a snapshot directory containing csr.bin (legacy v1 component), labels.bin (v2 component), properties.bin (v2 component) and a manifest indexing them. When the underlying graph.Mapper is string-keyed (N=string) the writer additionally emits mapper.bin — the durable (NodeID -> natural key) interning table — and the manifest is stamped at ManifestVersion (v4). For any other N the writer falls back to the v2 layout (no mapper.bin) and the manifest records [manifestVersionV2]; recovery from a v2 snapshot continues to rely on WAL replay to re-intern keys.

Atomic publication is achieved by assembling the snapshot under dir + ".tmp" and renaming it to dir on success — the same protocol used by WriteSnapshotCSR.

When g carries a non-nil index.Manager (set via lpg.Graph.SetIndexManager) with at least one registered index that implements index.Serializer, an indexes/ sub-directory is also produced — one file per registered serializable index, each referenced from the manifest's Indexes field. Subscribers that do not implement index.Serializer are skipped (rebuild-on-restart).

Callers that do not need durable LPG labels or properties can keep using WriteSnapshotCSR; it writes a v1-shaped directory that future readers (including this one) accept transparently.

func WriteSnapshotFullCtx ¶

func WriteSnapshotFullCtx[N comparable, W any](
	ctx context.Context,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
) error

WriteSnapshotFullCtx is the context-aware variant of WriteSnapshotFull. ctx.Err() is checked at five stage boundaries: before the CSR write, before the labels write, before the properties write, before the manifest write, and before the atomic rename. On cancellation the temporary staging directory is cleaned up and the wrapped ctx.Err is returned.

func WriteSnapshotFullWithConstraints ¶ added in v0.2.0

func WriteSnapshotFullWithConstraints[N comparable, W any](
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	constraints []ConstraintSpec,
) error

WriteSnapshotFullWithConstraints is WriteSnapshotFull plus a durable constraints.bin component carrying the engine's schema constraint set. It is the snapshot entry point a checkpointer must use when the engine has constraints declared: without the component a checkpoint that truncated the WAL prefix which first declared a constraint would lose that constraint (a durability defect). The mapper.bin component is emitted for string-keyed graphs exactly as WriteSnapshotFull does.

constraints may be nil or empty, in which case no constraints.bin is written and the output is byte-identical to WriteSnapshotFull.

func WriteSnapshotFullWithConstraintsAndIndexDefs ¶ added in v0.6.0

func WriteSnapshotFullWithConstraintsAndIndexDefs[N comparable, W any](
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	constraints []ConstraintSpec,
	indexDefs []IndexDefSpec,
) error

WriteSnapshotFullWithConstraintsAndIndexDefs is WriteSnapshotFullWithConstraints plus a durable indexdefs.bin component carrying the engine's secondary-index definition set. It is the snapshot entry point a checkpointer must use when the engine has indexes declared: without the component a checkpoint that truncated the WAL prefix which first declared an index would lose that index definition (a durability defect — #1755), the index analogue of the constraints case.

Both constraints and indexDefs may be nil or empty; when both are empty the output is byte-identical to WriteSnapshotFull.

func WriteSnapshotFullWithMapperCodec ¶

func WriteSnapshotFullWithMapperCodec[N comparable, W any](
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
) error

WriteSnapshotFullWithMapperCodec is the codec-aware variant of WriteSnapshotFull: it threads codec (the same [txn.Codec] the store uses to serialise node identifiers onto the WAL) into the mapper.bin writer so the durable NodeID->key interning table is emitted for ANY comparable key type N, not just string. A snapshot written this way is self-sufficient on load for every key type, which lets the checkpointer truncate the WAL instead of retaining it unboundedly (audit gap F3).

For string-keyed graphs the mapper bytes remain byte-identical to the version-1 layout (see WriteMapper), so this entry point is a safe drop-in for the existing WriteSnapshotFull on string stores too.

codec must not be nil; pass the store's [txn.Store.Codec].

func WriteSnapshotFullWithMapperCodecAndConstraints ¶ added in v0.2.0

func WriteSnapshotFullWithMapperCodecAndConstraints[N comparable, W any](
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
	constraints []ConstraintSpec,
) error

WriteSnapshotFullWithMapperCodecAndConstraints is the codec-aware variant of WriteSnapshotFullWithConstraints: it threads codec into the mapper.bin writer (so the snapshot is self-sufficient for any key type) AND persists the constraint set. This is the entry point a checkpointer over a non-string store uses when constraints are declared.

codec must not be nil. constraints may be nil or empty (no constraints.bin).

func WriteSnapshotFullWithMapperCodecAndConstraintsFS ¶ added in v0.6.0

func WriteSnapshotFullWithMapperCodecAndConstraintsFS[N comparable, W any](
	fsys fileSystem,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
	constraints []ConstraintSpec,
) error

WriteSnapshotFullWithMapperCodecAndConstraintsFS is the filesystem-seam variant of WriteSnapshotFullWithMapperCodecAndConstraints: it routes every filesystem operation of the snapshot publish through fsys instead of the default OS backend. It is the entry point the deterministic-simulation harness (internal/sim) uses to back a snapshot with an in-memory disk so it can crash mid-publish and during the WAL prefix-truncate that follows a checkpoint.

The fsys parameter type ([fileSystem]) is intentionally unexported: an external package cannot name it but can still supply a value that satisfies it (mirroring wal.OpenWith). Passing osBackend{} reproduces WriteSnapshotFullWithMapperCodecAndConstraints byte-for-byte.

codec must not be nil. constraints may be nil or empty (no constraints.bin).

func WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefs ¶ added in v0.6.0

func WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefs[N comparable, W any](
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
	constraints []ConstraintSpec,
	indexDefs []IndexDefSpec,
) error

WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefs is the codec-aware variant of WriteSnapshotFullWithConstraintsAndIndexDefs: it threads codec into the mapper.bin writer (so the snapshot is self-sufficient for any key type) AND persists BOTH the constraint set and the index-definition set. This is the entry point a checkpointer over a non-string store uses when either constraints or indexes are declared.

codec must not be nil. constraints and indexDefs may each be nil or empty (the corresponding component is then omitted).

func WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefsFS ¶ added in v0.6.0

func WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefsFS[N comparable, W any](
	fsys fileSystem,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
	constraints []ConstraintSpec,
	indexDefs []IndexDefSpec,
) error

WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefsFS is the filesystem-seam variant of WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefs: it routes every filesystem operation of the snapshot publish through fsys instead of the default OS backend, persisting BOTH the constraint set and the index-definition set. It is the entry point the deterministic-simulation harness (internal/sim) uses to back a snapshot with an in-memory disk so the simulated checkpoint also carries durable index definitions (#1755).

The fsys parameter type ([fileSystem]) is intentionally unexported (mirroring wal.OpenWith). Passing osBackend{} reproduces WriteSnapshotFullWithMapperCodecConstraintsAndIndexDefs byte-for-byte.

codec must not be nil. constraints and indexDefs may each be nil or empty.

func WriteSnapshotFullWithMapperCodecCtx ¶

func WriteSnapshotFullWithMapperCodecCtx[N comparable, W any](
	ctx context.Context,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	codec keyEncoder[N],
) error

WriteSnapshotFullWithMapperCodecCtx is the context-aware variant of WriteSnapshotFullWithMapperCodec. ctx cancellation is honoured at the same stage boundaries as WriteSnapshotFullCtx; the only difference is that the mapper.bin component is emitted for every key type via codec rather than for string alone.

func WriteSnapshotFullWithWeightCodecCtx ¶ added in v0.12.0

func WriteSnapshotFullWithWeightCodecCtx[N comparable, W any](
	ctx context.Context,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	wcodec weightEncoder[W],
) error

WriteSnapshotFullWithWeightCodecCtx is the weight-codec-aware variant of WriteSnapshotFullCtx: it persists edge weights of ANY type W by encoding them through wcodec.

Without a codec this writer can persist only weights whose Go type has a fixed width (the built-in integer, float and bool primitives), and a graph holding any other weight type fails with ErrWeightNotPersistable rather than publishing a weightless snapshot (rmp #2526). A nil wcodec is accepted and behaves exactly as WriteSnapshotFullCtx.

The mapper is persisted for string-keyed graphs only, as on WriteSnapshotFullCtx; pair with a mapper codec via the WriteSnapshotFullWithMapperCodec* family when the key type needs one.

func WriteSnapshotFullWithWeightCodecCtxFS ¶ added in v0.16.0

func WriteSnapshotFullWithWeightCodecCtxFS[N comparable, W any](
	ctx context.Context,
	fsys fileSystem,
	dir string,
	c *csr.CSR[W],
	g *lpg.Graph[N, W],
	wcodec weightEncoder[W],
) error

WriteSnapshotFullWithWeightCodecCtxFS is the filesystem-seam variant of WriteSnapshotFullWithWeightCodecCtx: it routes every filesystem operation of the snapshot publish through fsys instead of the default OS backend. It is the entry point store/bulkimport's seamed publish uses, so the deterministic- simulation harness (internal/sim) can inject faults into a bulk-import publish and crash it mid-way (rmp #2518).

The fsys parameter type ([fileSystem]) is intentionally unexported, as on WriteSnapshotFullWithMapperCodecAndConstraintsFS. Passing osBackend{} reproduces WriteSnapshotFullWithWeightCodecCtx byte for byte. A nil wcodec behaves exactly as WriteSnapshotFullCtx over fsys.

func WriteTombstones ¶

func WriteTombstones[N comparable, W any](w io.Writer, g *lpg.Graph[N, W], at *lpg.Snapshot) (size int64, crc uint32, err error)

WriteTombstones serialises g's current tombstone set (the NodeIDs removed via lpg.Graph.RemoveNode) into w in the tombstones.bin format. It returns the number of bytes written and the CRC32C of the serialised payload — both stored in the manifest's FileEntry for the component so LoadSnapshotFull can verify integrity at load time.

The CRC32C covers the entire on-disk file, including the magic header, matching the labels.bin / properties.bin discipline. The id list is emitted in ascending order (lpg.Graph.TombstonedIDs sorts it) so the component is deterministic across writes of the same logical state.

func WriteTombstonesFrom ¶ added in v0.11.0

func WriteTombstonesFrom(w io.Writer, ids []graph.NodeID) (size int64, crc uint32, err error)

WriteTombstonesFrom is WriteTombstones over an ALREADY-COMPUTED dead set.

It exists because a concurrent capture must derive every number in its manifest from ONE walk of the mapper (rmp #2310). Recomputing the set here would be a second walk at a second moment, and while writers commit those two moments do not agree: each narrowing of that window reduced the disagreement — 8 nodes, then 10, then 2 — and none could close it, because the window IS the design. The capture now walks once, keeps the interned set and the dead set from that walk, and hands both to the writers that serialise them.

ids must be ascending, which is what the reader expects.