SQLite 快照

Graft 把 SQLite 数据库路径跟踪为 snapshot。snapshot 是一个不可变的数据库 状态，可以被 repository commit 引用。

这让 SQLite 数据库路径在 Graft 中成为一等版本对象。repository 不必把 data.sqlite 只当作 opaque binary blob：它可以记录 snapshot、比较支持的 row/schema changes、合并兼容编辑，并把结果 materialize 回普通 SQLite 文件。

project/
  data.sqlite
  .graft/

data.sqlite 是 worktree path；commit 里保存的是 .graft/ 支撑的 snapshot descriptor。

物理 Worktree 模式

graft sql --db data.sqlite "INSERT INTO notes(body) VALUES ('hello');"
graft add data.sqlite
graft commit -m "add note"

SQL transaction 修改 data.sqlite，以及可能存在的 WAL；此时不会直接写 Graft storage。graft add 才是 storage boundary：它通过 SQLite online backup 捕获一个 committed database state，包含 committed WAL frames，但不会 checkpoint 或修改 源数据库。private snapshot 会被规范化为 standalone rollback-journal database。

随后 Graft 按 4 KiB Graft storage chunk 与 staged 或 committed base 比较，只追加 变化 chunk。物理数据库可以使用更大的合法 SQLite page size，例如 8 KiB；存储去重 粒度仍是 4 KiB。如果没有变化，会复用原 CommitFileState 和 snapshot，不产生新的 storage commit。rollback-journal database 使用同一流程，只是通常没有 WAL。 未提交 transaction 不会进入 staged state。

Materialized Files

默认情况下，commit、checkout、switch、pull、merge-continue 后，Graft 会把 tracked SQLite snapshot 写回 worktree 中的普通 SQLite 文件。

sqlite3 data.sqlite "SELECT count(*) FROM notes;"

repository commit 仍然保存可验证的 snapshot descriptor，而不是只保存整个 文件副本。

Export

graft export --source HEAD --output data.head.sqlite data.sqlite

graft export 不移动 HEAD，不修改 index，也不把导出文件连接到当前 Graft volume。

Checkout Safety

checkout、switch、restore 或 reset 需要替换物理 database 时，Graft 会取得 SQLite exclusive lock、处理旧 WAL、清理 sidecar，再执行 atomic rename。如果其他 writer 仍然活跃，操作会失败而不是从它下面替换 main file。执行 branch operation 前应关闭 长时间存在的 database connection。

可选 Live VFS 模式

应用明确需要 SQLite commit 直接推进 Graft Volume 时，可以加载 extension 并使用 vfs=graft。这是高级 data-plane 模式，不是 repository control plane；status、 stage、history、merge 和 sync 仍使用 CLI。与物理 staging 不同，live Graft VFS 写入路径要求 SQLite page_size=4096，因为一个 SQLite page 会直接映射到一个 Graft page。

不要让同一个逻辑 database 同时接受普通 file VFS 和 Graft VFS 的写入。