# Add per-checkpoint ref resolver (ShardFor + RefName/ParseRef)

`b01b596`→[main](/content/gh/entireio/cli/commits/main/index.html)·

Soph·2w ago·4 files·+221 added/-0 removed

First slice of the per-checkpoint git-ref checkpoint store (#1471), on top of the
merged understanding layer. Pure naming/resolution; nothing constructs a ref
store yet.

- id: re-add CheckpointID.ShardFor (first-2 chars for legacy hex, last-2 for a
  ULID so the random suffix spreads evenly while the ID stays sortable) and the
  CheckpointID.Kind() method. These were deferred out of the understanding-layer
  PR (#1546) because sharding is a storage concern; they land here with their
  consumer.
- checkpoint: RefName builds refs/entire/checkpoints/<shard>/<id>; ParseRef
  inverts it, rejecting a mismatched shard or extra path segments so a malformed
  ref never resolves to the wrong bucket.

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

## Sessions

53f11b080581View transcript

## Changes

4

- cmd/entire/cli/checkpoint

- id

- Mid.go+29

- Mid_test.go+34

- Arefs_naming.go+51

- Arefs_naming_test.go+107

```
87 unmodified lines

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

87 unmodified lines

}
```

// Kind classifies this checkpoint ID.
func (id CheckpointID) Kind() Kind {
    return KindOf(string(id))
}

// ShardFor returns the two-character shard for storing this ID under a
// per-checkpoint git ref (refs/entire/checkpoints/<shard>/<id>), chosen so
// checkpoints spread evenly across buckets:
//
//   - Legacy hex IDs shard on the FIRST two characters, preserving the existing
//     entire/checkpoints/v1 tree layout (see Path).
//   - ULIDs shard on the LAST two characters: a ULID's leading characters encode
//     its timestamp and barely vary between nearby checkpoints, while the trailing
//     characters are random, so the suffix spreads evenly while the ID itself
//     stays lexicographically sortable.
//
// For an ID shorter than two characters the whole ID is returned; an unrecognized
// ID falls back to the first-two (prefix) layout.
func (id CheckpointID) ShardFor() string {
    s := string(id)
    if len(s) < 2 {
        return s
    }
    if id.Kind() == KindULID {
        return s[len(s)-2:]
    }
    return s[:2]
}

// NewCheckpointID creates a CheckpointID from a string, validating its format.
// Returns an error unless the string is a valid checkpoint ID (12-char hex or ULID).
func NewCheckpointID(s string) (CheckpointID, error) {
```

Mcmd/entire/cli/checkpoint/id/id.go+29

```
144 unmodified lines

145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184

144 unmodified lines

if got := KindOf(tt.input); got != tt.want {
                t.Errorf("KindOf(%q) = %v, want %v", tt.input, got, tt.want)
            }
            if got := CheckpointID(tt.input).Kind(); got != tt.want {
                t.Errorf("CheckpointID(%q).Kind() = %v, want %v", tt.input, got, tt.want)
            }
        })
    }
}

func TestCheckpointID_ShardFor(t *testing.T) {
    t.Parallel()
    tests := []struct {
        name  string
        input string
        want  string
    }{
        // Legacy hex shards on the first two chars (preserves the v1 layout).
        {"legacy", "a1b2c3d4e5f6", "a1"},
        {"legacy other", "abcdef123456", "ab"},
        // ULID shards on the LAST two chars.
        {"ulid", sampleULID, "ZN"},
        {"ulid trailing", "0123456789ABCDEFGHJKMNPQRS", "RS"},
        // Unknown falls back to the prefix (first-two) layout.
        {"unknown", "XYZ", "XY"},
        // Short-string fallbacks.
        {"empty", "", ""},
        {"one char", "a", "a"},
        {"two chars", "ab", "ab"},
    }

for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            if got := CheckpointID(tt.input).ShardFor(); got != tt.want {
                t.Errorf("CheckpointID(%q).ShardFor() = %q, want %q", tt.input, got, tt.want)
            }
        })
    }
}
```

Mcmd/entire/cli/checkpoint/id/id_test.go+34

```
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

package checkpoint

import (
	"strings"

"github.com/go-git/go-git/v6/plumbing"

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

// CheckpointRefPrefix is the namespace under which the git-refs backend stores
// one ref per checkpoint: refs/entire/checkpoints/<shard>/<id>. Each ref points
// at a checkpoint commit whose tree root is that checkpoint's contents. This is
// distinct from the git-branch backend's single entire/checkpoints/v1 branch.
const CheckpointRefPrefix = "refs/entire/checkpoints/"

// RefName returns the per-checkpoint git ref for a checkpoint ID:
// refs/entire/checkpoints/<shard>/<id>, where <shard> is id.ShardFor() (the
// first two chars for legacy hex IDs, the last two for ULIDs). The full ID is
// always the leaf, so the ref round-trips through ParseRef.
func RefName(cid id.CheckpointID) plumbing.ReferenceName {
    return plumbing.ReferenceName(CheckpointRefPrefix + cid.ShardFor() + "/" + cid.String())
}

// ParseRef extracts the checkpoint ID from a per-checkpoint ref name,
// reporting whether name is a well-formed checkpoint ref. A ref is well-formed
// when it has the CheckpointRefPrefix, exactly a <shard>/<id> tail, and the
// shard matches the ID's own ShardFor — so refs the resolver did not write
// (mismatched shard, extra path segments) are rejected rather than silently
// resolved to the wrong bucket. It does not require the ID to be a recognized
// kind, so a future ID format still parses as long as it shards consistently.
func ParseRef(name plumbing.ReferenceName) (id.CheckpointID, bool) {
    s := name.String()
    tail, ok := strings.CutPrefix(s, CheckpointRefPrefix)
    if !ok {
        return id.EmptyCheckpointID, false
    }
    shard, rest, ok := strings.Cut(tail, "/")
    if !ok || shard == "" || rest == "" {
        return id.EmptyCheckpointID, false
    }
    // Reject extra path segments: the tail must be exactly <shard>/<id>.
    if strings.Contains(rest, "/") {
        return id.EmptyCheckpointID, false
    }
    cid := id.CheckpointID(rest)
    if cid.ShardFor() != shard {
        return id.EmptyCheckpointID, false
    }
    return cid, true
}
```

Acmd/entire/cli/checkpoint/refs_naming.go+51

```
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

package checkpoint

import (
	"testing"

"github.com/go-git/go-git/v6/plumbing"
	"github.com/stretchr/testify/assert"

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

func TestRefName(t *testing.T) {
    t.Parallel()

tests := []struct {
        name string
        cid  id.CheckpointID
        want plumbing.ReferenceName
    }{
        {
            name: "legacy hex shards on first two",
            cid:  "a1b2c3d4e5f6",
            want: "refs/entire/checkpoints/a1/a1b2c3d4e5f6",
        },
        {
            name: "ulid shards on last two",
            cid:  "01KVBJCWYA4YW6J5M9GP655HZN",
            want: "refs/entire/checkpoints/ZN/01KVBJCWYA4YW6J5M9GP655HZN",
        },
    }

for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            assert.Equal(t, tt.want, RefName(tt.cid))
        })
    }
}

func TestParseRef(t *testing.T) {
    t.Parallel()

tests := []struct {
        name   string
        ref    plumbing.ReferenceName
        wantID id.CheckpointID
        wantOK bool
    }{
        {
            name:   "legacy round-trip",
            ref:    "refs/entire/checkpoints/a1/a1b2c3d4e5f6",
            wantID: "a1b2c3d4e5f6",
            wantOK: true,
        },
        {
            name:   "ulid round-trip",
            ref:    "refs/entire/checkpoints/ZN/01KVBJCWYA4YW6J5M9GP655HZN",
            wantID: "01KVBJCWYA4YW6J5M9GP655HZN",
            wantOK: true,
        },
        {
            name:   "wrong prefix",
            ref:    "refs/heads/entire/checkpoints/v1",
            wantOK: false,
        },
        {
            name:   "shard does not match id (legacy in last-two bucket)",
            ref:    "refs/entire/checkpoints/f6/a1b2c3d4e5f6",
            wantOK: false,
        },
        {
            name:   "extra path segment",
            ref:    "refs/entire/checkpoints/a1/a1b2c3d4e5f6/0",
            wantOK: false,
        },
        {
            name:   "missing id",
            ref:    "refs/entire/checkpoints/a1/",
            wantOK: false,
        },
        {
            name:   "missing shard separator",
            ref:    "refs/entire/checkpoints/a1b2c3d4e5f6",
            wantOK: false,
        },
        {
            name:   "prefix only",
            ref:    "refs/entire/checkpoints/",
            wantOK: false,
        },
    }

for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            gotID, gotOK := ParseRef(tt.ref)
            assert.Equal(t, tt.wantOK, gotOK)
            if tt.wantOK {
                assert.Equal(t, tt.wantID, gotID)
                // Round-trip: building the ref from the parsed ID reproduces it.
                assert.Equal(t, tt.ref, RefName(gotID))
            } else {
                assert.Equal(t, id.EmptyCheckpointID, gotID)
            }
        })
    }
}

```