Repository Mode

Repository mode is the part of Graft that makes SQLite database snapshots behave like project files.

Discovery

Given a database path:

/work/app/app.db

Graft walks upward looking for:

/work/app/.graft/

If found, the database belongs to that repository. If not found, repository commands fail until graft_init or graft_clone creates one.

Path Normalization

The VFS receives database paths from SQLite. On macOS and other systems, the same physical directory can appear through aliases such as:

/var/folders/...
/private/var/folders/...

Repository mode normalizes path-like tags by canonicalizing the parent directory and keeping the file name. This prevents the same app.db from being treated as two different database tags.

Repo-Local Runtime

Before a database attaches to a repository, the extension may use process-temporary base storage. After repository discovery, it forks the runtime to use:

.graft/store/

That gives each project isolated durable storage.

Index State

The index records the next commit’s file states. For normal staged entries, stage 0 contains the snapshot that will be committed.

Merge conflicts use multiple stages:

stage 1: base
stage 2: ours
stage 3: theirs

Conflict resolution chooses one side or writes a resolved database state, then records a normal stage 0 entry again.

Worktree Dirty State

The VFS marks a repo-relative path dirty when SQLite commits page changes. Status then compares:

HEAD tree vs index
index vs worktree
conflict stages
physical SQLite files found by directory scan

That is why graft status can report:

untracked: app.db
modified: app.db
deleted: app.db

Physical SQLite Files

Repository mode can stage SQLite database files from the physical worktree, even if the current process did not write them through the VFS. Graft validates that the file has a SQLite header and compatible page size, imports pages into repo-local storage, and records a snapshot.

This is useful for migration, but normal editing should use the Graft VFS so status and dirty state stay immediate.