# Read-support refs-v1; explain fetches a git-refs checkpoint on clone

`2e99244`·
  
Soph·2w ago·15 files·+63 added/-35 removed

- checkpointpolicy: refs-v1 is now read- AND write-supported (refsV1Format added to both readFormats and writeFormats) so explain/resume/attach accept git-refs checkpoints and the git-refs store may write them. Tests that used "refs-v1" as a stand-in *unsupported* version now use "refs-v2" (the next, genuinely unsupported refs major); format_test asserts refs-v1 is supported.
- explain: on a fresh clone the prefix→ID remote fallback only fetched the v1 metadata branch (empty under git-refs). When the primary is git-refs and the prefix is a full checkpoint ID (the Entire-Checkpoint trailer always is), fetch that one ref via FetchCheckpointRef and re-list.

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

## Sessions

291fe479c0a8View transcript

## Changes

15

- cmd/entire/cli  
  
  - Mattach_test.go+2/-2
  
  - Mcheckpoint_policy_read_test.go+2/-2
  
  - Mcheckpoint_policy_test.go+3/-3
  
  - Mcheckpoint_policy_warning_test.go+2/-2
  
  - checkpointpolicy  
  
    - Mformat.go+6/-1
    
    - Mformat_test.go+3/-2
    
    - Mpolicy_test.go+1/-1
    
    - Mremote_test.go+4/-4
    
    - Mstore_test.go+2/-2
    
    - Mupdate_test.go+6/-6
    
    - Mwarning_test.go+2/-2

- Mexplain_export.go+22
  
  - Mexplain_export_test.go+3/-3
  
  - Mexplain_test.go+3/-3
  
  - Mresume_test.go+2/-2

```  
77 unmodified lines  
78  
79  
80  
81  
82  
83  
84  
9 unmodified lines  
94  
95  
96  
97  
97  
98  
99  
100

77 unmodified lines

t.Fatal(err)  
}  
if _, err := checkpointpolicy.WriteLocal(context.Background(), repo, plumbing.ZeroHash, checkpointpolicy.Policy{  
	CheckpointVersion:    "refs-v1",  
	CheckpointVersion:    "refs-v2",  
	CheckpointMinVersion: "branch-v1",  
}); err != nil {  
	t.Fatal(err)  
9 unmodified lines  
if err == nil {  
	t.Fatal("expected unsupported checkpoint policy error")  
}  
if !strings.Contains(err.Error(), `checkpoint_version "refs-v1"`) {  
if !strings.Contains(err.Error(), `checkpoint_version "refs-v2"`) {  
	t.Fatalf("error = %v, want checkpoint policy version", err)  
}  
if _, refErr := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true); refErr == nil {  
```

Mcmd/entire/cli/attach_test.go+2/-2

```
15 unmodified lines

16
17
18
19
19
20
21
22
23
23
24
25
26

15 unmodified lines

_, err := readCheckpointInfoFromStore(context.Background(), checkpointInfoPolicyStub{  
	summary: &checkpoint.CheckpointSummary{  
		CheckpointID:      cpID,  
		CheckpointVersion: "refs-v1",  
		CheckpointVersion: "refs-v2",  
	},  
}, cpID)

require.EqualError(t, err, `checkpoint 111111111111 uses unsupported checkpoint_version "refs-v1": not read-supported by this Entire CLI`)
require.EqualError(t, err, `checkpoint 111111111111 uses unsupported checkpoint_version "refs-v2": not read-supported by this Entire CLI`)
}

type checkpointInfoPolicyStub struct {
```

Mcmd/entire/cli/checkpoint_policy_read_test.go+2/-2

```
33 unmodified lines

34
35
36
37
37
38
39
40
9 unmodified lines

50
51
52
53
54
53
54
55
56
57

33 unmodified lines

wantErr string  
}{  
	{name: "checkpoint version", args: []string{"--checkpoint-version", "branch-v2342"}, wantErr: `checkpoint_version "branch-v2342" is not supported by this Entire CLI`},  
	{name: "minimum version", args: []string{"--checkpoint-min-version", "refs-v1"}, wantErr: `checkpoint_min_version "refs-v1" is not supported by this Entire CLI`},  
	{name: "minimum version", args: []string{"--checkpoint-min-version", "refs-v2"}, wantErr: `checkpoint_min_version "refs-v2" is not supported by this Entire CLI`},
}

for _, tt := range tests {
9 unmodified lines

func TestCheckpointPolicyCmd_RejectsDowngradeWithoutForce(t *testing.T) {
	dir, bareDir := setupCheckpointPolicyRepo(t)
	seedCheckpointPolicyForCommand(t, dir, checkpointpolicy.Policy{  
		CheckpointVersion:    "refs-v1",  
		CheckpointMinVersion: "refs-v1",  
		CheckpointVersion:    "refs-v2",  
		CheckpointMinVersion: "refs-v2",  
	})
	pushCheckpointPolicyRefForCommandTest(t, dir, bareDir)
```

... (truncated for brevity)