Skip to content
Graft

Snapshots And LSNs

Graft has two related histories:

repository history
  commit ids, refs, branches, tags


storage history
  LogId, LSN, storage commit hash

Most users should think in repository commits. Internal diagnostics sometimes expose storage coordinates.

Repository Commit Id

Section titled “Repository Commit Id”

A repository commit id identifies a Graft commit object. It is content-addressed:

commit object bytes -> BLAKE3 object id

It changes when the commit payload changes: parent, tree, message, timestamp, or file snapshot objects.

Use commit ids and revspecs with normal repository commands:

Terminal window
graft show HEAD
graft diff HEAD~1 HEAD app.db
graft checkout HEAD~1 app.db

Storage LSN

Section titled “Storage LSN”

An LSN is a logical sequence number inside a storage log:

(LogId, LSN) -> storage commit

The LSN is not globally unique by itself. It only makes sense with its LogId. It is also not a hash. It is a position in a storage log.

Storage diagnostics expose LSNs:

Terminal window
graft sql "PRAGMA graft_debug_log_lsn;"

Storage Commit Hash

Section titled “Storage Commit Hash”

Each storage commit has a content hash. Snapshot objects record these hashes so Graft can verify that an LSN range refers to the exact page history expected by the repository object.

That gives the repository snapshot stronger integrity than simply saying:

log X from LSN 1 to LSN 4

Instead, the snapshot records the commits inside that range too.

Why One Repository Commit Can Contain Multiple LSNs

Section titled “Why One Repository Commit Can Contain Multiple LSNs”

SQLite can write multiple pages and internal state changes while completing a transaction. Graft stores those page-level changes in the storage log. A single repository commit then snapshots the resulting database state.

So this is normal:

repository commit HEAD
  app.db snapshot
    log abc
    LSN 1
    LSN 2
    LSN 3
    LSN 4

Use repository commits for user-facing history. Use LSNs when debugging low-level page or row diffs.

Practical Rule

Section titled “Practical Rule”
  • If the command is graft diff, graft show, graft checkout, graft branch, or graft push, use commit ids, branch names, tags, or revspecs.
  • If the command is PRAGMA graft_debug_volume_diff, use LSNs.
  • If you need row-level diagnostic diff today, first get LSNs with PRAGMA graft_debug_log_lsn.