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

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

3f06d01·

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

Build Checkpoints Store Based on DesignClaude Code·3 steps

Changes

4

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

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

Acmd/entire/cli/checkpoint/refs_naming_test.go+107