Snapshot Objects

A repository commit does not store a raw copy of app.db. It stores a tree that points to a SQLite snapshot object.

commit
  tree
    app.db -> sqlite-snapshot-v1

Object Identity

Repository objects are content-addressed. A canonical object payload is hashed with BLAKE3, producing the object id used in commits, trees, and snapshot references.

If the payload changes, the object id changes.

SQLite Snapshot Payload

A sqlite-snapshot-v1 object records enough information to reconstruct and verify a database state:

volume <VolumeId>
page_count <PageCount>
range <LogId> <start_lsn> <end_lsn>
commit <lsn> <storage_commit_hash>
commit <lsn> <storage_commit_hash>

Important fields:

• VolumeId tells Graft which logical database volume the snapshot belongs to.
• page_count gives the database length in pages.
• range identifies storage log intervals needed for reconstruction.
• commit lines pin each LSN to its expected storage commit hash.

Why Store Commit Hashes With LSNs?

An LSN is a position in a log. It is not itself proof of content.

The storage commit hash verifies content:

(LogId, LSN) -> storage commit -> commit hash

By recording both ranges and hashes, the repository object can detect mismatches where an LSN coordinate does not refer to the expected storage commit.

Diff Implications

Repository diffs compare snapshot objects:

graft diff --json HEAD~1 HEAD app.db

The JSON output exposes the snapshot ranges and commit hashes. That is the bridge between user-facing commit history and storage-level diagnostics.