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

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

b01b596→main·

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.

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

Sessions

53f11b080581View transcript

Changes

4

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//), 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//. 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//, where 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 / 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 /. 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) } }) } }