架构

本页面面向贡献者和高级调试。产品集成通常应使用 CLI、JSON 输出和配置参考； SQLite extension 是可选 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

Crates

Crate	作用
graft	core storage、repository objects、refs、index、merge、sync、remotes。
graft-sqlite	repository command service、物理 SQLite import boundary 和可选 SQLite VFS。
graft-ext	SQLite extension wrapper。
graft-tool	CLI。
graft-test	integration tests 和 workloads。
graft-tracing	tracing helpers。

CLI Flow

repository CLI command 直接调用 typed repository service：

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

这条 control flow 不打开 SQLite connection，也不执行 PRAGMA。graft sql --db <path> 是独立的数据路径，使用普通 SQLite 打开物理 database。

Commit / Checkout / Merge

commit flow：

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

可选 Graft VFS 会直接写 Volume page，因此跳过 physical import；这个直接映射要求 SQLite page_size=4096。physical import 可以捕获例如 8 KiB page size 的合法 数据库，同时仍按 4 KiB Graft chunk 存储其镜像。VFS 不暴露 repository command。

checkout materialize 物理 database 前会取得 SQLite replacement lock、处理 WAL 并清理 sidecar。活跃 writer 会阻止替换。

merge flow 从 base/ours/theirs tree 开始，对 SQLite 路径通过 direct parser fast path 或 materialized SQLite compatibility path 做 row/schema analysis，对文件 artifact 使用保守 file-level conflicts。