# add checkpoint policy model

`7a9f373`·
  pfleidi·3w ago·4 files·+273 added/-0 removed

Define checkpoint format parsing and policy validation for the repo-wide checkpoint policy ref.

## Sessions

1d8503f2a450View transcript

[?\
Implement Checkpoint Policy Management SystemCodex·GPT-5.5·17 steps](/content/gh/entireio/cli/session/019ef111-70d5-7203-b653-e4834b8b92c0#timeline-1d8503f2a450/index.html)

## Changes

4

- cmd/entire/cli/checkpointpolicy

- Aformat.go+101

- Aformat_test.go+58

- Apolicy.go+72

- Apolicy_test.go+42

```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

package checkpointpolicy

import (
	"fmt"
	"strconv"
	"strings"
)

type CheckpointFamily string

const (
	CheckpointFamilyBranch CheckpointFamily = "branch"
	CheckpointFamilyRefs   CheckpointFamily = "refs"
)

type CheckpointFormat struct {
	Family CheckpointFamily
	Major  int
}

func ParseFormat(raw string) (CheckpointFormat, error) {
	familyRaw, majorRaw, ok := strings.Cut(raw, "-v")
	if !ok || familyRaw == "" || majorRaw == "" {
		return CheckpointFormat{}, fmt.Errorf("invalid checkpoint format %q", raw)
	}

family := CheckpointFamily(familyRaw)
	if _, ok := familyRanks[family]; !ok {
		return CheckpointFormat{}, fmt.Errorf("unknown checkpoint family %q", familyRaw)
	}

major, err := strconv.Atoi(majorRaw)
	if err != nil || major <= 0 {
		return CheckpointFormat{}, fmt.Errorf("invalid checkpoint major %q", majorRaw)
	}

return CheckpointFormat{Family: family, Major: major}, nil
}

func (f CheckpointFormat) String() string {
	if f.Family == "" || f.Major == 0 {
		return ""
	}
	return fmt.Sprintf("%s-v%d", f.Family, f.Major)
}

func Compare(a, b CheckpointFormat) int {
	aRank := familyRanks[a.Family]
	bRank := familyRanks[b.Family]
	if aRank != bRank {
		return compareInt(aRank, bRank)
	}
	return compareInt(a.Major, b.Major)
}

func KnowsFormat(format CheckpointFormat) bool {
	_, ok := knownFormats[format]
	return ok
}

func CanRead(format CheckpointFormat) bool {
	return readFormats[format]
}

func CanWrite(format CheckpointFormat) bool {
	return writeFormats[format]
}

func compareInt(a, b int) int {
	switch {
	case a < b:
		return -1
	case a > b:
		return 1
	default:
		return 0
	}
}

var familyRanks = map[CheckpointFamily]int{
	CheckpointFamilyBranch: 0,
	CheckpointFamilyRefs:   1,
}

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

knownFormats = map[CheckpointFormat]struct{}{
		branchV1Format: {},
		refsV1Format:   {},
	}

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

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

Acmd/entire/cli/checkpointpolicy/format.go+101

```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

package checkpointpolicy_test

import (
	"testing"

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
	"github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
	"github.com/stretchr/testify/require"
)

func TestParseFormat(t *testing.T) {
	t.Parallel()
	tests := []struct {
		name    string
		input   string
		want    checkpointpolicy.CheckpointFormat
		wantErr string
	}{
		{name: "branch v1", input: "branch-v1", want: checkpointpolicy.CheckpointFormat{Family: checkpointpolicy.CheckpointFamilyBranch, Major: 1}},
		{name: "refs v2", input: "refs-v2", want: checkpointpolicy.CheckpointFormat{Family: checkpointpolicy.CheckpointFamilyRefs, Major: 2}},
		{name: "unknown family", input: "unknown-v1", wantErr: "unknown checkpoint family"},
		{name: "missing v", input: "branch-1", wantErr: "invalid checkpoint format"},
		{name: "zero major", input: "branch-v0", wantErr: "invalid checkpoint major"},
		{name: "non numeric major", input: "branch-vx", wantErr: "invalid checkpoint major"},
	}
	for _, tt := range tests {
		tt := tt
		t.Run(tt.name, func(t *testing.T) {
			t.Parallel()
			got, err := checkpointpolicy.ParseFormat(tt.input)
			if tt.wantErr != "" {
				require.ErrorContains(t, err, tt.wantErr)
				return
			}
			require.NoError(t, err)
			require.Equal(t, tt.want, got)
			require.Equal(t, tt.input, got.String())
		})
	}
}

func TestSupportedFormats(t *testing.T) {
	t.Parallel()
	branchV1, err := checkpointpolicy.ParseFormat(checkpoint.CheckpointVersionBranchV1)
	require.NoError(t, err)
	refsV1, err := checkpointpolicy.ParseFormat("refs-v1")
	require.NoError(t, err)

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

require.True(t, checkpointpolicy.KnowsFormat(refsV1))
	require.False(t, checkpointpolicy.CanRead(refsV1))
	require.False(t, checkpointpolicy.CanWrite(refsV1))
	require.Less(t, checkpointpolicy.Compare(branchV1, refsV1), 0)
}
```

Acmd/entire/cli/checkpointpolicy/format_test.go+58

```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

package checkpointpolicy

import (
	"fmt"

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
)

type Policy struct {
	CheckpointVersion    string `json:"checkpoint_version"`
	CheckpointMinVersion string `json:"checkpoint_min_version"`
}

func DefaultPolicy() Policy {
	return Policy{
		CheckpointVersion:    checkpoint.CheckpointVersionBranchV1,
		CheckpointMinVersion: checkpoint.CheckpointVersionBranchV1,
	}
}

func Normalize(policy Policy) Policy {
	if policy.CheckpointVersion == "" {
		policy.CheckpointVersion = checkpoint.CheckpointVersionBranchV1
	}
	if policy.CheckpointMinVersion == "" {
		policy.CheckpointMinVersion = checkpoint.CheckpointVersionBranchV1
	}
	return policy
}

func ValidatePolicy(policy Policy) error {
	policy = Normalize(policy)

version, err := ParseFormat(policy.CheckpointVersion)
	if err != nil {
		return fmt.Errorf("checkpoint_version: %w", err)
	}
	if !CanWrite(version) {
		return fmt.Errorf("checkpoint_version %q is not write-supported by this Entire CLI", policy.CheckpointVersion)
	}

minVersion, err := ParseFormat(policy.CheckpointMinVersion)
	if err != nil {
		return fmt.Errorf("checkpoint_min_version: %w", err)
	}
	if !CanRead(minVersion) {
		return fmt.Errorf("checkpoint_min_version %q is not read-supported by this Entire CLI", policy.CheckpointMinVersion)
	}
	if Compare(minVersion, version) > 0 {
		return fmt.Errorf("checkpoint_min_version %q is newer than checkpoint_version %q", policy.CheckpointMinVersion, policy.CheckpointVersion)
	}

return nil
}

func RequiresUpgrade(policy Policy) bool {
	policy = Normalize(policy)
	minVersion, err := ParseFormat(policy.CheckpointMinVersion)
	if err != nil {
		return true
	}
	return !CanRead(minVersion)
}

func UnsupportedWrite(policy Policy) bool {
	policy = Normalize(policy)
	version, err := ParseFormat(policy.CheckpointVersion)
	if err != nil {
		return true
	}
	return !CanWrite(version)
}
}
```

Acmd/entire/cli/checkpointpolicy/policy.go+72

```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

package checkpointpolicy_test

import (
	"testing"

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
	"github.com/entireio/cli/cmd/entire/cli/checkpointpolicy"
	"github.com/stretchr/testify/require"
)

func TestDefaultPolicy(t *testing.T) {
	t.Parallel()
	got := checkpointpolicy.DefaultPolicy()
	require.Equal(t, checkpoint.CheckpointVersionBranchV1, got.CheckpointVersion)
	require.Equal(t, checkpoint.CheckpointVersionBranchV1, got.CheckpointMinVersion)
}

func TestValidatePolicy(t *testing.T) {
	t.Parallel()
	tests := []struct {
		name    string
		policy  checkpointpolicy.Policy
		wantErr string
	}{
		{name: "default", policy: checkpointpolicy.DefaultPolicy()},
		{name: "unknown current", policy: checkpointpolicy.Policy{CheckpointVersion: "future-v1", CheckpointMinVersion: "branch-v1"}, wantErr: "unknown checkpoint family"},
		{name: "unsupported current", policy: checkpointpolicy.Policy{CheckpointVersion: "refs-v1", CheckpointMinVersion: "branch-v1"}, wantErr: "not write-supported"},
		{name: "unsupported minimum", policy: checkpointpolicy.Policy{CheckpointVersion: "branch-v1", CheckpointMinVersion: "refs-v1"}, wantErr: "not read-supported"},
	}
	for _, tt := range tests {
		tt := tt
		t.Run(tt.name, func(t *testing.T) {
			t.Parallel()
			err := checkpointpolicy.ValidatePolicy(tt.policy)
			if tt.wantErr == "" {
				require.NoError(t, err)
				return
			}
			require.ErrorContains(t, err, tt.wantErr)
		})
	}
}
```