Grove.Tree.Snapshot (Grove v0.1.1)

View Source

Captures tree state at a critical version for fast document loading.

Snapshots are created when the version frontier has size <= 1 (all branches merged). This enables 100-1000x faster document loading by avoiding full CRDT reconstruction.

Fields

  • :version - The Version at snapshot time (must be critical)
  • :nodes - Complete map of node ID to Node structs
  • :root_id - ID of the root node
  • :clock - Lamport clock value at snapshot time
  • :operation_log - LogMove entries for undo-do-redo support
  • :move_winners - Map of node_id to winning move timestamp
  • :operation_validity - Map of operation to validity boolean
  • :created_at - Unix timestamp when snapshot was created
  • :tree_hash - SHA256 hash for integrity verification

Summary

Types

t()

Functions

create(tree)

Creates a snapshot from a tree at a critical version.

create!(tree)

Creates a snapshot from a tree, forcing creation even if not at critical version.

snapshot_event_id(snapshot)

Returns the event ID from the snapshot's version frontier.

to_tree(snapshot, replica_id)

Rebuilds a tree from a snapshot with the given replica ID.

valid?(snapshot)

Validates snapshot integrity by recomputing the hash.

Types

t()

@type t() :: %Grove.Tree.Snapshot{
  clock: non_neg_integer(),
  created_at: non_neg_integer(),
  move_winners: %{required(String.t()) => term()},
  nodes: %{required(String.t()) => Grove.Node.t()},
  operation_log: [term()],
  operation_validity: %{required(term()) => boolean()},
  root_id: String.t() | nil,
  tree_hash: binary(),
  version: Grove.Tree.Version.t()
}

Functions

create(tree)

@spec create(Grove.Tree.t()) :: {:ok, t()} | {:error, :not_critical}

Creates a snapshot from a tree at a critical version.

Returns {:ok, snapshot} if the tree is at a critical version, or {:error, :not_critical} if the frontier has multiple branches.

Examples

{:ok, snapshot} = Snapshot.create(tree)

# Tree with concurrent branches cannot be snapshotted
{:error, :not_critical} = Snapshot.create(branched_tree)

create!(tree)

@spec create!(Grove.Tree.t()) :: t()

Creates a snapshot from a tree, forcing creation even if not at critical version.

This should only be used for testing or emergency recovery scenarios.

snapshot_event_id(snapshot)

@spec snapshot_event_id(t()) :: Grove.Tree.Event.event_id() | nil

Returns the event ID from the snapshot's version frontier.

Returns nil if the frontier is empty.

to_tree(snapshot, replica_id)

@spec to_tree(t(), String.t()) :: Grove.Tree.t()

Rebuilds a tree from a snapshot with the given replica ID.

The replica_id determines the identity for new operations. History and pending_ops are cleared as they're not part of snapshots.

Examples

tree = Snapshot.to_tree(snapshot, "replica_1")

valid?(snapshot)

@spec valid?(t()) :: boolean()

Validates snapshot integrity by recomputing the hash.

Returns true if the hash matches, false otherwise.

Examples

true = Snapshot.valid?(snapshot)