Move ShardFor/Kind() out of the understanding layer

5bd1049→main·

Soph·2w ago·2 files·+1 added/-65 removed

ShardFor (and the CheckpointID.Kind() method it used) had no production caller in this PR — their only consumer is the git-refs store's RefName, which lands with the ref-store work — so their doc comments had to forward-reference a per-checkpoint ref store that isn't here. Sharding is a storage concern, not part of recognizing/validating an ID, so move both (and their tests) to the ref-store change.

This PR now contains only the universal "understanding" layer: KindOf/Kind, isULID (oklog-backed), Validate/NewCheckpointID/UnmarshalJSON, and the Pattern/CheckpointPattern matchers. No unused exports, no forward-referencing comments; the Kind type doc drops its git-ref clause.

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

Sessions

510078f47f13View transcript

Changes

2

• cmd/entire/cli/checkpoint/id

• Mid.go+1/-31

• Mid_test.go-34

62 unmodified lines

63
64
65
66
67
66
67
68
69
18 unmodified lines

88
89
90
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
91
92
93

62 unmodified lines

return err == nil && v.String() == s
}

// Kind classifies a checkpoint ID by its storage format. The two valid kinds
// shard differently when stored as a git ref (see ShardFor).
// Kind classifies a checkpoint ID by its format: legacy 12-hex or ULID.
type Kind int

const (
18 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+1/-31

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
148
149
150

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