docs: cover both persistent backends in sessions-and-checkpoints

c15fe35→main·

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

The Storage table and Package Structure were git-branch-only and the package listing had drifted (temporary.go/committed.go no longer exist).

Add a git-refs row to the Storage table, note the store is pluggable with a pointer to the ref-backend doc, and refresh the checkpoint/ package listing to the current files (open.go, registry.go, routing_store.go, fanout.go, refs_store.go, refs_naming.go, pushqueue.go, persistent*.go, ephemeral.go, fsstore/).

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

Sessions

01KX36R9EZPC2VFF2PT74TN82GView transcript

?\ Document git-refs Checkpoint Backend ArchitectureClaude Code·Opus 4.8[1m]·4 steps

Changes

1

• docs/architecture

• Msessions-and-checkpoints.md+19/-7

145 unmodified lines

146
147
148
149
149
150
151
152
153
154
155
323 unmodified lines

479
480
481
479
480
481
482
483
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
487
499
500
501
502

145 unmodified lines

|------|----------|----------|
| Session State | `.git/entire-sessions/<id>.json` | Active session tracking |
| Ephemeral | `entire/<commit[:7]>-<worktreeHash[:6]>` branch | Full state (code + metadata) |
| Persistent | `entire/checkpoints/v1` branch (sharded) | Metadata + commit reference |
| Persistent (git-branch) | `entire/checkpoints/v1` branch, sharded `<id[:2]>/<id[2:]>/` | Metadata + commit reference |
| Persistent (git-refs) | `refs/entire/checkpoints/<shard>/<id>`, one ref per checkpoint | Metadata + commit reference |

The persistent store is pluggable: `git-branch` (the default) stores every committed checkpoint as a subtree of a single `entire/checkpoints/v1` branch, while `git-refs` stores one ref per checkpoint. Both are git-backed and share the same checkpoint tree layout; they differ only in where that tree is committed. This document describes the git-branch layout; for the ref-based backend — its ref naming, sharding, push/fetch model, read routing, and configuration — see [Ref-Based Checkpoint Backend](ref-checkpoint-backend.md).

### Session State

323 unmodified lines

├── phase.go             # Session phase state machine (ACTIVE, IDLE, ENDED, etc.)

checkpoint/
├── checkpoint.go        # checkpoint.Type, checkpoint.Store interface, CheckpointSummary, etc.
├── store.go             # GitStore implementation
├── temporary.go         # Shadow branch storage
├── committed.go         # Metadata branch storage
├── id/                  # CheckpointID type and generation
├── checkpoint.go        # checkpoint.Type, store interfaces, CheckpointSummary, etc.
├── open.go              # Open() facade: resolves topology, wires stores + fetchers
├── registry.go          # Backend registry + gitBacked capability (git-branch, git-refs)
├── routing_store.go     # kindRoutingStore: id-kind read routing across both backends
├── fanout.go            # Mirror write fan-out (primary + best-effort mirrors)
├── generate.go          # GenerateCheckpointID (format follows the configured primary)
├── persistent.go        # git-branch persistent store (entire/checkpoints/v1)
├── persistent_write.go  # git-branch write path (treeWriter, subtree splicing)
├── refs_store.go        # git-refs persistent store (one ref per checkpoint)
├── refs_naming.go       # RefName / ParseRef, CheckpointRefPrefix, sharding
├── pushqueue.go         # git-refs push-discovery queue (flock JSONL)
├── ephemeral.go         # Shadow-branch (ephemeral) store
├── fsstore/             # Filesystem mirror backend (non-git-backed, mirror-only)
├── id/                  # CheckpointID type, Kind/KindOf, ShardFor, generation
│   └── id.go

Strategies use checkpoint.Store primitives - storage details are encapsulated. Strategies use the checkpoint.Open facade and store primitives - backend and storage details are encapsulated.

Strategy Role