Reframe backend taxonomy: git-branch type + one-of-each-type mirrors

d0e4056→main·

Soph·3w ago·5 files·+155 added/-65 removed

The registered type "git" conflated "uses git" with "stores on a git branch". Rename it to "git-branch" (the current backend stores the committed record on the entire/checkpoints/v1 branch); this leaves room for a future git-refs backend in the same git-backed family.

Replace the string-equality constraints with a declared capability and a topology rule:

• registeredBackend.gitBacked marks backends whose committed record lives in this repo's git object store. Only git-backed backends may be the primary (the lifecycle — resume/doctor/explain/push/cleanup/OPF — drives the primary through the repo and its refs). buildPrimary checks the capability instead of comparing against the literal "git".
• A backend type may appear at most once across the topology (primary + mirrors). This is the conservative form of "no two backends may write the same target": two backends of the same type share the same refs/storage today, so a git-branch mirror under a git-branch primary would double-write v1. It deliberately permits a different git-backed backend (e.g. a future git-refs) to mirror alongside a git-branch primary — the branch<->refs parallel-rollout topology — which the previous "no git-backed mirror" block would have forbidden.

A future per-mirror config (same type, distinct repo/refs) could relax the one-of-each-type rule further.

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

Sessions

b6014c28999aView transcript

Changes

5

• cmd/entire/cli/checkpoint

• fsstore

  • Mseam_test.go+1/-1
  • Mopen.go+49/-21
  • Mopen_config_test.go+33/-9
  • Mregistry.go+54/-24
  • Mregistry_test.go+18/-10

// json-encode the path so separators / spaces are escaped correctly.
encodedPath, err := json.Marshal(mirrorDir);
require.NoError(t, err);
body := `{"enabled": true, "checkpoints": {"primary": {"type": "git"}, "mirrors": [{"type": "fs", "config": {"path": ` + body := `{"enabled": true, "checkpoints": {"primary": {"type": "git-branch"}, "mirrors": [{"type": "fs", "config": {"path": ` +
string(encodedPath) + `}}]}}`;
require.NoError(t, os.MkdirAll(filepath.Join(repoDir, ".entire"), 0o755));
require.NoError(t, os.WriteFile(filepath.Join(repoDir, ".entire", "settings.json"), []byte(body), 0o644));

// Open resolves the checkpoint storage topology and constructs the backing // store(s). It keeps ref resolution, backend selection, and blob-fetcher wiring // in one place. The primary is built through the backend registry; with no // checkpoints config it resolves to the git backend with no mirrors, so default // behavior is unchanged. When mirrors are configured, the persistent store is a // fan-out wrapper (reads from primary, best-effort writes to each mirror). // checkpoints config it resolves to the git-branch backend with no mirrors, so // default behavior is unchanged. When mirrors are configured, the persistent // store is a fan-out wrapper (reads from primary, best-effort writes to mirrors). // Backend selection is read via settings.LoadCheckpointsConfig, which resolves // like settings.Load: from the context's worktree root if set, else relative to // the current working directory — not from repo. Callers opening a repository // that is not the cwd should wrap ctx with that worktree root (as dispatch does). // Resolution is fail-soft: a missing or unreadable settings file yields the // default git backend with no mirrors, preserving default behavior. // default git-branch backend with no mirrors, preserving default behavior.