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

06ddcba·

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
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);

Mcmd/entire/cli/checkpoint_policy_test.go+3/-3

19 unmodified lines

20
21
22
23
24
23
24
25
26
27

19 unmodified lines

_ = repo.Close()
    })
    _, err = checkpointpolicy.WriteLocal(t.Context(), repo, plumbing.ZeroHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    });
    require.NoError(t, err);

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

71 unmodified lines

72
73
74
75
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

71 unmodified lines

CheckpointFamilyRefs:   1,
}

var branchV1Format = CheckpointFormat{Family: CheckpointFamilyBranch, Major: 1}
var (
    branchV1Format = CheckpointFormat{Family: CheckpointFamilyBranch, Major: 1}
    refsV1Format   = CheckpointFormat{Family: CheckpointFamilyRefs, Major: 1}
)

var (
    readFormats = map[CheckpointFormat]bool{
        branchV1Format: true,
        refsV1Format:   true,
    }

writeFormats = map[CheckpointFormat]bool{
        branchV1Format: true,
        refsV1Format:   true,
    }
)

Mcmd/entire/cli/checkpointpolicy/format.go+6/-1

51 unmodified lines

52
53
54
55
56
55
56
57
58
59
60

51 unmodified lines

require.True(t, checkpointpolicy.CanWrite(branchV1))
    require.Equal(t, checkpoint.CheckpointVersionBranchV1, branchV1.String())

require.False(t, checkpointpolicy.CanRead(refsV1))
    require.False(t, checkpointpolicy.CanWrite(refsV1))
    // refs-v1 is the git-refs store format: read- and write-supported.
    require.True(t, checkpointpolicy.CanRead(refsV1))
    require.True(t, checkpointpolicy.CanWrite(refsV1))
    require.Negative(t, checkpointpolicy.Compare(branchV1, refsV1))

require.False(t, checkpointpolicy.CanRead(unknownV1))

Mcmd/entire/cli/checkpointpolicy/format_test.go+3/-2

24 unmodified lines

25
26
27
28
28
29
30
31

24 unmodified lines

{name: "default", policy: checkpointpolicy.DefaultPolicy()},
    {name: "unknown current", policy: checkpointpolicy.Policy{CheckpointVersion: "future-v1", CheckpointMinVersion: "branch-v1"}, wantErr: `checkpoint_version "future-v1" is not supported by this Entire CLI`},
    {name: "unsupported current", policy: checkpointpolicy.Policy{CheckpointVersion: "branch-v2342", CheckpointMinVersion: "branch-v1"}, wantErr: `checkpoint_version "branch-v2342" is not supported by this Entire CLI`},
    {name: "unsupported minimum", policy: checkpointpolicy.Policy{CheckpointVersion: "branch-v1", CheckpointMinVersion: "refs-v1"}, wantErr: `checkpoint_min_version "refs-v1" is not supported by this Entire CLI`},
    {name: "unsupported minimum", policy: checkpointpolicy.Policy{CheckpointVersion: "branch-v1", CheckpointMinVersion: "refs-v2"}, wantErr: `checkpoint_min_version "refs-v2" is not supported by this Entire CLI`},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {

Mcmd/entire/cli/checkpointpolicy/policy_test.go+1/-1

70 unmodified lines

71
72
73
74
75
74
75
76
77
78
53 unmodified lines

132
133
134
135
136
135
136
137
138
139

70 unmodified lines

require.NoError(t, err)

remoteHash, err := checkpointpolicy.WriteLocal(t.Context(), remoteRepo, baseHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    })
    require.NoError(t, err)
    pushPolicyRefWithGit(t, remoteDir, bareDir)
53 unmodified lines

secondDir, secondRepo := initPolicyRepoWithDir(t)
    _, err = checkpointpolicy.WriteLocal(t.Context(), secondRepo, plumbing.ZeroHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    })
    require.NoError(t, err)

Mcmd/entire/cli/checkpointpolicy/remote_test.go+4/-4

66 unmodified lines

67
68
69
70
71
70
71
72
73
74

66 unmodified lines

t.Parallel()
    repo := initPolicyRepo(t)
    policy := checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    }
    data, err := json.Marshal(policy)
    require.NoError(t, err)

Mcmd/entire/cli/checkpointpolicy/store_test.go+2/-2

11 unmodified lines

12
13
14
15
16
15
16
17
18
19
14 unmodified lines

34
35
36
37
38
37
38
39
40
41
53 unmodified lines

95
96
97
98
99
98
99
100
101
102

11 unmodified lines

func TestUpdateRejectsDowngradeFromRemoteWithoutForce(t *testing.T) {
    remoteDir, remoteRepo, bareDir := initPolicyRemoteFixture(t)
    _, err := checkpointpolicy.WriteLocal(t.Context(), remoteRepo, plumbing.ZeroHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    })
    require.NoError(t, err)
    pushPolicyRefWithGit(t, remoteDir, bareDir)
14 unmodified lines

func TestUpdateAllowsDowngradeWithForce(t *testing.T) {
    remoteDir, remoteRepo, bareDir := initPolicyRemoteFixture(t)
    remoteHash, err := checkpointpolicy.WriteLocal(t.Context(), remoteRepo, plumbing.ZeroHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    })
    require.NoError(t, err)
    pushPolicyRefWithGit(t, remoteDir, bareDir)
53 unmodified lines

require.NoError(t, err)

remoteHash, err := checkpointpolicy.WriteLocal(t.Context(), remoteRepo, baseHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointMinVersion: "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "refs-v2",
    })
    require.NoError(t, err)
    pushPolicyRefWithGit(t, remoteDir, bareDir)

Mcmd/entire/cli/checkpointpolicy/update_test.go+6/-6

13 unmodified lines

14
15
16
17
17
18
19
20
6 unmodified lines

27
28
29
30
30
31
32
33

13 unmodified lines

require.False(t, checkpointpolicy.RequiresUpgrade(checkpointpolicy.DefaultPolicy()))
    require.True(t, checkpointpolicy.RequiresUpgrade(checkpointpolicy.Policy{
        CheckpointVersion:    checkpoint.CheckpointVersionBranchV1,
        CheckpointMinVersion: "refs-v1",
        CheckpointMinVersion: "refs-v2",
    }))
    require.True(t, checkpointpolicy.RequiresUpgrade(checkpointpolicy.Policy{
        CheckpointVersion:    checkpoint.CheckpointVersionBranchV1,
6 unmodified lines

require.False(t, checkpointpolicy.UnsupportedWrite(checkpointpolicy.DefaultPolicy()))
    require.True(t, checkpointpolicy.UnsupportedWrite(checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: checkpoint.CheckpointVersionBranchV1,
    }))
    require.True(t, checkpointpolicy.UnsupportedWrite(checkpointpolicy.Policy{

Mcmd/entire/cli/checkpointpolicy/warning_test.go+2/-2

11 unmodified lines

12
13
14
15
16
17
18
181 unmodified lines

200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

11 unmodified lines

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
    "github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
    "github.com/entireio/cli/cmd/entire/cli/settings"
    "github.com/entireio/cli/cmd/entire/cli/strategy"
    "github.com/entireio/cli/cmd/entire/cli/trailers"
)
181 unmodified lines

return matches, lookup

// git-refs primary: there is no single metadata branch to fetch — each
    // checkpoint is its own ref. When the prefix is a full checkpoint ID (the
    // Entire-Checkpoint commit trailer always is), fetch that one ref directly,
    // then re-list. Falls through to the v1-branch fetch below otherwise.
    if cpCfg, _ := settings.LoadCheckpointsConfig(ctx); checkpoint.PrimaryIsRefs(cpCfg) { //nolint:errcheck // fail-soft: bad config surfaces via Open elsewhere
        if cid, err := id.NewCheckpointID(prefix); err == nil {
            stop := startSpinner(errW, "Fetching checkpoint from remote")
            fetchErr := FetchCheckpointRef(ctx, checkpoint.RefName(cid))
            stop(false)
            if fetchErr == nil {
                if fresh, freshErr := newExplainCheckpointLookup(ctx); freshErr == nil {
                    if m := matchCheckpointPrefix(fresh, prefix); len(m) > 0 {
                        return m, fresh
                    }
                    _ = fresh.Close()
                }
            }
        }
        return nil, lookup
    }

stop := startSpinner(errW, "Fetching checkpoint metadata from remote")
    _, v1Repo, v1Err := getMetadataTree(ctx)
    if v1Repo != nil {

Mcmd/entire/cli/explain_export.go+22

96 unmodified lines

97
98
99
100
100
101
102
103
56 unmodified lines

160
161
162
163
163
164
165
166
145 unmodified lines

312
313
314
315
315
316
317
318

96 unmodified lines

require.NoError(t, err)
    var summary checkpoint.CheckpointSummary
    require.NoError(t, json.Unmarshal([]byte(content), &summary))
    summary.CheckpointVersion = "refs-v1"
    summary.CheckpointVersion = "refs-v2"
    metadataJSON, err := json.Marshal(summary)
    require.NoError(t, err)
    metadataHash, err := checkpoint.CreateBlobFromContent(repo, metadataJSON)
56 unmodified lines

json:         true,
    sessionIndex: -1,
    })
    require.ErrorContains(t, err, `checkpoint aaaabbbbcccc uses unsupported checkpoint_version "refs-v1"`)
    require.ErrorContains(t, err, `checkpoint aaaabbbbcccc uses unsupported checkpoint_version "refs-v2"`)
    require.Empty(t, stdout.String())
}

145 unmodified lines

var stdout, stderr bytes.Buffer
    err := runExplainExport(context.Background(), &stdout, &stderr, tt.opts)
    require.ErrorContains(t, err, `checkpoint abcd11112222 uses unsupported checkpoint_version "refs-v1"`)
    require.ErrorContains(t, err, `checkpoint abcd11112222 uses unsupported checkpoint_version "refs-v2"`)
    require.Empty(t, stdout.String())
    })
}
}

Mcmd/entire/cli/explain_export_test.go+3/-3

1009 unmodified lines

1010
1011
1012
1013
1013
1014
1015
1016
109 unmodified lines

1126
1127
1128
1129
1129
1130
1131
1132
11 unmodified lines

1144
1145
1146
1147
1147
1148
1149
1150

1009 unmodified lines

defer lookup.Close()

_, _, err = loadCheckpointForExplain(context.Background(), lookup, cpID)
    require.ErrorContains(t, err, `checkpoint bbbbccccdddd uses unsupported checkpoint_version "refs-v1"`)
    require.ErrorContains(t, err, `checkpoint bbbbccccdddd uses unsupported checkpoint_version "refs-v2"`)

// Not parallel: uses t.Chdir() and package-level var stubs.
109 unmodified lines

func TestGenerateCheckpointSummaryRejectsUnsupportedCheckpointWritePolicy(t *testing.T) {
    fixture := setupGenerateSummaryFixture(t)
    _, err := checkpointpolicy.WriteLocal(fixture.ctx, fixture.repo, plumbing.ZeroHash, checkpointpolicy.Policy{
        CheckpointVersion:    "refs-v1",
        CheckpointVersion:    "refs-v2",
        CheckpointMinVersion: "branch-v1",
    })
    require.NoError(t, err)
11 unmodified lines

false,
    0,
)
    require.ErrorContains(t, err, `checkpoint_version "refs-v1"`)
    require.ErrorContains(t, err, `checkpoint_version "refs-v2"`)

v1After, refErr := fixture.repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true)
    require.NoError(t, refErr)
}

Mcmd/entire/cli/explain_test.go+3/-3

640 unmodified lines

641
642
643
644
644
645
646
647
22 unmodified lines

670
671
672
673
673
674
675
676

640 unmodified lines

newID := id.MustCheckpointID("ccc333ddd444")
    reader := &resumeCheckpointInfoReaderStub{
        summaries: map[id.CheckpointID]*checkpoint.CheckpointSummary{
            unsupportedID: {CheckpointVersion: "refs-v1"},
            unsupportedID: {CheckpointVersion: "refs-v2"},
            newID:         {Sessions: []checkpoint.SessionFilePaths{{Metadata: "new"}}},
        },
        metadata: map[id.CheckpointID][]checkpoint.Metadata{
22 unmodified lines

unsupportedID := id.MustCheckpointID("aaa111bbb222")
    reader := &resumeCheckpointInfoReaderStub{
        summaries: map[id.CheckpointID]*checkpoint.CheckpointSummary{
            unsupportedID: {CheckpointVersion: "refs-v1"},
            unsupportedID: {CheckpointVersion: "refs-v2"},
        },
    }

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