docs: add ref-based checkpoint backend (git-refs) architecture doc

main

Commit

Soph2mo ago

The git-refs backend is fully implemented (registry, refs store, push queue, routing store) but had no document explaining it as a system — its behavior was only reconstructable from code comments and scattered design notes. sessions-and-checkpoints.md covered the ID/read-routing layer but its Storage and Package Structure sections remained git-branch-only.

Add docs/architecture/ref-checkpoint-backend.md covering: primary/mirror taxonomy and the gitBacked capability, the refs/entire/checkpoints/ <shard>/<id> layout and last-two-char sharding, the per-checkpoint write path (orphan-then-parented history), the push-discovery queue and fast-forward-only push with fetch+replay recovery, on-demand ref fetch, kind-based read routing and coexistence, configuration + env override + rollout states, checkpoint-version formats, and known limitations.

Grounded in the current code (refs_naming.go, refs_store.go, pushqueue.go, routing_store.go, registry.go, checkpointpolicy/format.go, settings/checkpoints.go), not the older design notes — notably sharding is last-two-chars for both ID formats, not the earlier asymmetric plan.

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

Checkpoints

Document git-refs Checkpoint Backend Architecture

Claude CodeOpus 4.8[1m]
View session
Checkpoint 1