Architecture

This page is for contributors and advanced debugging. Product integrations should normally use the CLI, JSON output, and config reference. The SQLite extension is an optional data-plane integration.

Layers

Application
  ordinary SQLite connection -> physical worktree database
  optional SQLite connection using vfs=graft
  graft CLI / JSON

graft-sqlite
  repository command service (control plane)
  physical SQLite snapshot/import boundary
  optional VFS + VFS diagnostic PRAGMAs (data plane)

graft
  repository model
  objects, refs, index, merge, sync
  storage volumes, logs, snapshots
  remote backends

Remote storage
  fs, S3-compatible, Graft HTTP protocol

Core Crates

Crate	Role
graft	Core storage, repository objects, refs, index, merge, sync, remotes.
graft-sqlite	Repository command service, physical SQLite import boundary, and optional SQLite VFS.
graft-ext	Dynamic/static SQLite extension wrapper.
graft-tool	CLI that maps arguments to repository operations.
graft-test	Integration test harnesses and workloads.
graft-tracing	Tracing setup helpers.

CLI Flow

CLI repository commands call the typed repository service directly:

CLI arguments
  -> RepositoryCommand parser
  -> repository-scoped runtime/session
  -> repository operation

No SQLite connection or PRAGMA is used for that control flow. graft sql --db <path> separately opens the physical database with ordinary SQLite.

Commit Flow

SQLite commits to a physical database (main file and possibly WAL)
  -> graft add takes a consistent private SQLite backup
  -> unchanged pages are reused and changed pages extend Graft storage
  -> the index records the resulting snapshot descriptor
  -> graft commit writes a tree and commit object
  -> branch ref moves to the new commit
  -> SQLite snapshots are materialized back to physical worktree files

The optional Graft VFS skips the physical import step because SQLite writes Volume pages directly. That direct mapping requires SQLite page_size=4096. Physical import can capture databases with larger legal page sizes, such as 8 KiB, while still storing their images in 4 KiB Graft chunks. The VFS does not expose repository commands.

For file artifacts, staging records inline blobs or external payload pointers.

Checkout And Switch Flow

resolve target commit
  -> compare target tree to current worktree/index state
  -> acquire SQLite replacement locks and normalize/remove WAL sidecars
  -> materialize tracked SQLite snapshots and files
  -> update HEAD or branch

Conflicting local work blocks checkout unless the command is explicitly forced. An active SQLite writer also blocks physical database replacement.

Merge Flow

base tree + ours tree + theirs tree
  -> path-level merge
  -> SQLite row/schema analysis for database paths
     (direct parser fast path or materialized SQLite compatibility path)
  -> auto-merge compatible database changes
  -> store unresolved stages in the index
  -> merge --continue writes the merge commit

File artifacts use conservative file-level conflict handling unless a resolver understands the format.