Add per-checkpoint ref resolver (ShardFor + RefName/ParseRef) · Entire
Add per-checkpoint ref resolver (ShardFor + RefName/ParseRef)
7ab7073·
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/
/ ; 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
...
// 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) {
144 unmodified lines
...
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)
}
})
}
}
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
}
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)
}
})
}
}