docs: clarify the git-refs vs git-branch base-path difference

672fee0→main·

Soph·1w ago·1 file·+1 added/-1 removed

The write-path paragraph described the shared treeWriter as "anchored at base path """, which is both awkward and slightly wrong — basePath is a per-write argument, not a property of the treeWriter. Explain it in words: git-branch writes each checkpoint under its <id[:2]>/<id[2:]>/ shard prefix inside the one v1 tree, while git-refs writes with no prefix so the checkpoint subtree is the root of its own per-checkpoint commit.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

Sessions

01KX3B0P27TWE3S04XQGRR8M1JView transcript

Changes

1

• docs/architecture

• Mref-checkpoint-backend.md+1/-1

Write path

The git-refs store (gitRefsStore, checkpoint/refs_store.go) shares the checkpoint-subtree machinery with the git-branch store via an embedded *treeWriter anchored at base path "". The two differ only in where the subtree is committed: a per-checkpoint ref instead of a subtree of the v1 branch. The git-refs store (gitRefsStore, checkpoint/refs_store.go) shares the checkpoint-subtree machinery with the git-branch store via an embedded *treeWriter. Both build the exact same checkpoint subtree; they differ only in the base path they write it at and in where the result is committed. The git-branch store writes each checkpoint under its shard prefix <id[:2]>/<id[2:]>/ inside the single v1 tree, so many checkpoints share one tree. The git-refs store writes with no prefix (an empty base path), so the checkpoint subtree is the root of that checkpoint's own commit tree, and the commit is the tip of a per-checkpoint ref rather than a subtree of the v1 branch.

Every persistent write (WriteSession, and the Backfill* operations for transcript / summary / attribution) follows the same shape: