# Run e2e against a configurable checkpoint backend + git-refs CI

`655d528`·

Soph·2w ago·15 files·+289 added/-61 removed

\- settings: LoadCheckpointsConfig honors ENTIRE_CHECKPOINTS_PRIMARY (+ comma-separated ENTIRE_CHECKPOINTS_MIRRORS), env-wins-over-file, matching the other ENTIRE_* overrides. Backend selection only.
\- e2e: make the harness backend-aware (e2e/testutil/backend.go: checkpointStoreMode, CheckpointState advance digest, checkpointBlobSpec/checkpointRefName/checkpointShard). Advance detection, metadata reads, CheckpointIDs, push, and artifact capture route through it; the v1-branch-specific alternate-object sync test skips under git-refs. AssertCheckpointIDFormat keeps the production Validate (hex or ULID).
\- e2e TestMain maps E2E_CHECKPOINT_STORE (git-branch default, or git-refs) to the ENTIRE_CHECKPOINTS_PRIMARY override so every spawned binary/hook uses it.
\- CI: e2e-checkpoint-store workflow with a checkpoint_store input; e2e/README doc.

## Sessions

[?\
Build Checkpoints Store Based on DesignClaude Code·1 step](/content/gh/entireio/cli/session/6852b33a-0d22-4364-aa6c-8de706ecc215#timeline-d9646529ed6e/index.html)

## Changes

15

- cmd/entire/cli/settings

- Mcheckpoints.go+39

- Mcheckpoints_test.go+38

- e2e

- MREADME.md+1

- tests

- Malternates_test.go+3

- Mattach_test.go+1/-1

- Medge_cases_test.go+2/-2

- Mexplain_test.go+1/-2

- Mmain_test.go+8

- Mresume_remote_test.go+4/-6

- Mrewind_test.go+1/-1

- Msession_lifecycle_test.go+3/-3

- testutil

- Martifacts.go+16/-6

- Massertions.go+33/-22

- Abackend.go+94

- Mrepo.go+45/-18

``` go
7 unmodified lines
```

// block is malformed (e.g. a backend with no type).
var ErrInvalidCheckpointsConfig = errors.New("invalid checkpoints config")

// Environment overrides for checkpoint backend selection. When EnvCheckpointsPrimary
// is set, it (and the optional comma-separated EnvCheckpointsMirrors) fully
// replaces any checkpoints block in settings — env wins over file, matching the
// other ENTIRE_* overrides (ENTIRE_LOG_LEVEL, ENTIRE_TOKEN, …). Primarily for
// driving e2e/CI and rollout against a specific backend without editing settings.
const (
	EnvCheckpointsPrimary = "ENTIRE_CHECKPOINTS_PRIMARY"
	EnvCheckpointsMirrors = "ENTIRE_CHECKPOINTS_MIRRORS"
)

// CheckpointsConfig selects checkpoint storage backends: one primary (source of
// truth, serves all reads and writes) and zero or more mirrors (independent
// backends that receive best-effort write fan-out). When absent, the checkpoint

// a deep-merged document). Clone preferences carry no checkpoint config and are
// not consulted.
func LoadCheckpointsConfig(ctx context.Context) (*CheckpointsConfig, error) {
	// Env override wins over any settings file (precedence like ENTIRE_LOG_LEVEL).
	if cfg, ok := checkpointsConfigFromEnv(); ok {
		if err := cfg.validate(); err != nil {
			return nil, err
		}
		return cfg, nil
	}

base, local := checkpointsSettingsPaths(ctx)

// "local replaces base wholesale": prefer a checkpoints block from local
	return env.Checkpoints
}

// checkpointsConfigFromEnv builds a CheckpointsConfig from the environment when
// EnvCheckpointsPrimary is set. Mirrors are taken from EnvCheckpointsMirrors as a
// comma-separated list of backend types (no per-backend config blocks — the env
// override is for backend selection only). Returns ok=false when no primary is
// set, leaving file-based resolution in charge.
func checkpointsConfigFromEnv() (*CheckpointsConfig, bool) {
	primary := strings.TrimSpace(os.Getenv(EnvCheckpointsPrimary))
	if primary == "" {
		return nil, false
	}
	cfg := &CheckpointsConfig{Primary: BackendConfig{Type: primary}}
	for _, m := range strings.Split(os.Getenv(EnvCheckpointsMirrors), ",") {
		if t := strings.TrimSpace(m); t != "" {
			cfg.Mirrors = append(cfg.Mirrors, BackendConfig{Type: t})
		}
	}
	return cfg, true
}

func (c *CheckpointsConfig) validate() error {
	if c.Primary.Type == "" {
		return fmt.Errorf("%w: checkpoints.primary.type is required", ErrInvalidCheckpointsConfig)
	}
}

| `E2E_ENTIRE_BIN` | Path to a pre-built `entire` binary | builds from source |
| `E2E_TIMEOUT` | Timeout per prompt | `2m` |
| `E2E_KEEP_REPOS` | Set to `1` to preserve temp repos after test | unset |
| `E2E_CHECKPOINT_STORE` | Checkpoint backend to run the suite against (`git-branch`, `git-refs`). Maps to the `ENTIRE_CHECKPOINTS_PRIMARY` override that every spawned binary/hook honors. | `git-branch` |
| `E2E_ARTIFACT_DIR` | Override artifact output directory | `e2e/artifacts/<timestamp>` |
| `ANTHROPIC_API_KEY` | Required for Claude Code | — |
| `GEMINI_API_KEY` | Required for Gemini CLI | — |

``` go
// collectCommitsSince() fails with "object not found" on alternate-resident
// checkpoint commits, even though git itself resolves them.
func TestAlternates_RelativeObjectAlternate_CheckpointSync(t *testing.T) {
	if testutil.UsingGitRefs() {
		t.Skip("git-branch-specific: exercises the v1 checkpoint branch's non-fast-forward push/rebase sync over an object alternate; the git-refs store force-pushes independent per-checkpoint refs with no such rebase path")
	}
	// Siblings under one parent so the relative alternate path is short and
	// mirrors a real shared-clone layout.
	parent := t.TempDir()
}
```

---

// Validate session metadata exists and has checkpoint_id
sessionBlob := fmt.Sprintf("%s:%s/0/metadata.json", checkpointRef, path)
sessionBlob := checkpointBlobSpec(v.CheckpointID, "0/metadata.json")
sessionRaw := gitOutputSafe(dir, "show", sessionBlob)
if assert.NotEmpty(t, sessionRaw, "session metadata should exist at %s", sessionBlob) {
var sessionMeta map[string]any

// Validate transcript is valid JSONL
transcriptBlob := fmt.Sprintf("%s:%s/0/full.jsonl", checkpointRef, path)
transcriptBlob := checkpointBlobSpec(v.CheckpointID, "0/full.jsonl")
transcriptRaw := gitOutputSafe(dir, "show", transcriptBlob)
if assert.NotEmpty(t, transcriptRaw, "transcript should exist at %s", transcriptBlob) {

// Validate content hash
hashBlob := fmt.Sprintf("%s:%s/0/content_hash.txt", checkpointRef, path)
hashBlob := checkpointBlobSpec(v.CheckpointID, "0/content_hash.txt")
hashRaw := gitOutputSafe(dir, "show", hashBlob)
if hashRaw != "" {
hash := sha256.Sum256([]byte(transcriptRaw))