strategy: finish refs.Primary migration · Entire

strategy: finish refs.Primary migration

96c0ff0→main· pfleidi·1mo ago·8 files·+58 added/-47 removed

Remaining v1-pinned production sites move to refs.Primary: GetRemoteMetadataBranchTree becomes GetRemotePrimaryTree; trailer formatters in manual_commit_logs.go use Primary's short name; ListTemporary filters out the primary ref when it's a branch; DeleteOrphanedCheckpoints, IsMetadataDisconnected, WarnIfMetadataDisconnected, ReconcileDisconnectedMetadataBranch, and doctor's disconnected-metadata check all consult refs.Primary and gate remote-tracking work on PrimaryFetchableFromOrigin. The only remaining paths.MetadataBranchName uses in production are the resolver itself and IsShadowBranch's structural v1 filter.

Sessions

652bebbe8e4bView transcript

?\ Streamline Checkpoint Version Mirroring with refs.PrimaryClaude Code·1 step

Changes

8

234 unmodified lines

235
236
237
238
239
238
239
240
241
242
243

234 unmodified lines

return nil
}

// Skip the sessions branch
if branchName == paths.MetadataBranchName {
// Skip the primary metadata ref when it's a branch (shares the
// entire/ prefix but isn't a shadow branch).
if s.refs.Primary.IsBranch() && branchName == s.refs.Primary.Short() {
return nil
}

Mcmd/entire/cli/checkpoint/temporary.go+3/-2

335 unmodified lines

336
337
338
339
339
340
341
342
343
344
345
346
347
348
349
350
345
346
351
352
353
354
355
356
353
357
358
359
360

335 unmodified lines

d
repo.Close()

ctx := cmd.Context()
remoteRefName := plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName)
refs := checkpoint.ResolveCommittedRefs(ctx)
w := cmd.OutOrStdout()
if !refs.PrimaryFetchableFromOrigin() {
fmt.Fprintf(w, "✓ Metadata branches: OK (primary ref %s is not pushed to origin)\n", refs.Primary)
return nil
}
remoteRefName := plumbing.NewRemoteReferenceName("origin", refs.Primary.Short())
disconnected, err := strategy.IsMetadataDisconnected(ctx, repo, remoteRefName)
if err != nil {
return fmt.Errorf("could not check metadata branch state: %w", err)
}

w := cmd.OutOrStdout()

if !disconnected {
fmt.Fprintln(w, "✓ Metadata branches: OK")
return nil
}

fmt.Fprintln(w, "Metadata branches: DISCONNECTED")
fmt.Fprintln(w, "  Local and remote entire/checkpoints/v1 branches share no common ancestor.")
fmt.Fprintf(w, "  Local and remote %s branches share no common ancestor.\n", refs.Primary.Short())
fmt.Fprintln(w, "  Some remote checkpoints may not be visible locally.")
fmt.Fprintln(w, "  Fix: cherry-pick local checkpoints onto remote tip (preserves all data).")

Mcmd/entire/cli/doctor.go+8/-4

763 unmodified lines

764
765
766
767
767
768
769
770
57 unmodified lines

828
829
830
831
831
832
833
834
835
836
837
838
838
839
840
841

763 unmodified lines

func prefetchCheckpointBlobs(ctx context.Context, repo *git.Repository, cpID id.CheckpointID) {
refs := checkpoint.ResolveCommittedRefs(ctx)
loadPrimaryRoot := func(repo *git.Repository) (*object.Tree, error) {
return loadPrimaryMetadataRootTree(repo, refs)
return loadPrimaryMetadataRootTree(ctx, repo, refs)
v1FT := buildCheckpointFetchingTree(ctx, repo, cpID, "primary", loadPrimaryRoot)

57 unmodified lines
// loadPrimaryMetadataRootTree reads the tree at refs.Primary, falling back to
// origin's remote-tracking ref when reads are bootstrappable from origin
// (Read == Primary && Primary in Push).
func loadPrimaryMetadataRootTree(repo *git.Repository, refs checkpoint.CommittedRefs) (*object.Tree, error) {
func loadPrimaryMetadataRootTree(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs) (*object.Tree, error) {
if tree, err := strategy.GetMetadataRefTree(repo, refs.Primary); err == nil {
return tree, nil
}
if refs.Read != refs.Primary || !refs.PrimaryFetchableFromOrigin() {
return nil, fmt.Errorf("read primary metadata tree %s: ref not found locally", refs.Primary)
}
tree, err := strategy.GetRemoteMetadataBranchTree(repo)
tree, err := strategy.GetRemotePrimaryTree(ctx, repo)
if err != nil {
return nil, fmt.Errorf("read primary metadata tree (local + remote-tracking): %w", err)
}

Mcmd/entire/cli/explain.go+3/-3

425 unmodified lines

426
427
428
429
429
430
431
432
433
434
435
435
436
437
438

425 unmodified lines

)
}

// Try remote tree directly (origin/entire/checkpoints/v1)
// Try remote tree directly (origin's tracking ref for Primary)
remoteRepo, repoErr := openRepository(ctx)
if repoErr != nil {
return nil, nil, fmt.Errorf("failed to open repository: %w", repoErr)
}
logRefHash(remoteRepo, "remote-tracking")
remoteTree, remoteErr := strategy.GetRemoteMetadataBranchTree(remoteRepo)
remoteTree, remoteErr := strategy.GetRemotePrimaryTree(ctx, remoteRepo)
if remoteErr == nil {
logging.Debug(logCtx, "metadata tree obtained from remote-tracking branch")
return remoteTree, remoteRepo, nil

Mcmd/entire/cli/resume.go+2/-2

257 unmodified lines

258
259
260
261
262
263
261
262
263
265
264
265
266
267

257 unmodified lines

}

d
repo.Close()

// Get sessions branch
refName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
ref, err := repo.Reference(refName, true)
refs := checkpoint.ResolveCommittedRefs(ctx)
ref, err := repo.Reference(refs.Primary, true)
if err != nil {
return nil, nil, fmt.Errorf("sessions branch not found: %w", err)
return nil, nil, fmt.Errorf("primary metadata ref %s not found: %w", refs.Primary, err)
}

parentCommit, err := repo.CommitObject(ref.Hash())

Mcmd/entire/cli/strategy/cleanup.go+3/-4

99 unmodified lines

100
101
102
103
104
103
104
105
107
106
107
108
109
110
855 unmodified lines

966
967
968
969
970
971
969
970
971
972
973
974
975
976
977
978
974
979
980
981
982
983
979
984
985
986
987
988
984
989
990
991
992

99 unmodified lines

// the tmp ref. The cleanup is deferred so the tmp ref is reaped even when
// the advance fails.
//
// label is a short human-readable name used in error messages (e.g.
// "entire/checkpoints/v1"). Typical use:
// label is a short human-readable name used in error messages. Typical use:
//
// // fetch with refspec "+<src>:<tmpRefName>"
// return PromoteTmpRefSafely(ctx, tmpRefName, plumbing.NewBranchReferenceName(paths.MetadataBranchName), "entire/checkpoints/v1")
// refs := checkpoint.ResolveCommittedRefs(ctx)
// return PromoteTmpRefSafely(ctx, tmpRefName, refs.Primary, refs.Primary.Short())
func PromoteTmpRefSafely(ctx context.Context, tmpRefName, destRefName plumbing.ReferenceName, label string) error {
repo, err := OpenRepository(ctx)
if err != nil {
855 unmodified lines

return prompts
}

// GetRemoteMetadataBranchTree returns the tree object for origin/entire/checkpoints/v1.
func GetRemoteMetadataBranchTree(repo *git.Repository) (*object.Tree, error) {
refName := plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName)
// GetRemotePrimaryTree returns the tree at origin's remote-tracking ref for
// the configured Primary. Errors when Primary isn't in Push (no origin shadow).
func GetRemotePrimaryTree(ctx context.Context, repo *git.Repository) (*object.Tree, error) {
refs := checkpoint.ResolveCommittedRefs(ctx)
if !refs.PrimaryFetchableFromOrigin() {
return nil, fmt.Errorf("primary metadata ref %s is not pushed to origin", refs.Primary)
}
refName := plumbing.NewRemoteReferenceName("origin", refs.Primary.Short())
ref, err := repo.Reference(refName, true)
if err != nil {
return nil, fmt.Errorf("failed to get remote metadata branch reference: %w", err)
return nil, fmt.Errorf("failed to get remote metadata reference %s: %w", refName, err)
}

commit, err := repo.CommitObject(ref.Hash())
if err != nil {
return nil, fmt.Errorf("failed to get remote metadata branch commit: %w", err)
return nil, fmt.Errorf("failed to get remote metadata commit: %w", err)
}

tree, err := commit.Tree()
if err != nil {
return nil, fmt.Errorf("failed to get remote metadata branch tree: %w", err)
return nil, fmt.Errorf("failed to get remote metadata tree: %w", err)
}
return tree, nil
}

Mcmd/entire/cli/strategy/common.go+14/-9

4 unmodified lines

5
6
7
8
8
9
10
11
54 unmodified lines

66
67
68
69
70
71
69
70
71
72
73
74
74
75
76
77
78
78
79
80
81
82
1 unmodified line

84
85
86
86
87
88
87
88
89
90
91
92
93
94
95
93
94
95
96
97
98

4 unmodified lines

"fmt"
    "strings"

"github.com/entireio/cli/cmd/entire/cli/paths"
    "github.com/entireio/cli/cmd/entire/cli/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/trailers"

"github.com/go-git/go-git/v6/plumbing"
54 unmodified lines

}

// GetMetadataRef returns a reference to the metadata for the given checkpoint.
// For manual-commit strategy, returns the sharded path on entire/checkpoints/v1 branch.
func (s *ManualCommitStrategy) GetMetadataRef(_ context.Context, checkpoint Checkpoint) string {
if checkpoint.CheckpointID.IsEmpty() {
// For manual-commit strategy, returns the sharded path on refs.Primary.
func (s *ManualCommitStrategy) GetMetadataRef(ctx context.Context, cp Checkpoint) string {
if cp.CheckpointID.IsEmpty() {
return ""
}
return paths.MetadataBranchName + ":" + checkpoint.CheckpointID.Path()
refs := checkpoint.ResolveCommittedRefs(ctx)
return refs.Primary.Short() + ":" + cp.CheckpointID.Path()
}

// GetSessionMetadataRef returns a reference to the most recent metadata commit for a session.
// For manual-commit strategy, metadata lives on the entire/checkpoints/v1 branch.
// For manual-commit strategy, metadata lives on refs.Primary.
func (s *ManualCommitStrategy) GetSessionMetadataRef(ctx context.Context, _ string) string {
repo, err := OpenRepository(ctx)
if err != nil {
1 unmodified line
}

d
repo.Close()

// Get the sessions branch
refName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
ref, err := repo.Reference(refName, true)
refs := checkpoint.ResolveCommittedRefs(ctx)
ref, err := repo.Reference(refs.Primary, true)
if err != nil {
return ""
}

// The tip of entire/checkpoints/v1 contains all condensed sessions
// Return a reference to it (sessionID is not used as all sessions are on the same branch)
return trailers.FormatSourceRef(paths.MetadataBranchName, ref.Hash().String())
// The tip of Primary contains all condensed sessions; return a reference to
// it (sessionID is not used because all sessions live on the same ref).
return trailers.FormatSourceRef(refs.Primary.Short(), ref.Hash().String())
}

// GetCheckpointLog returns the session transcript for a specific checkpoint.

Mcmd/entire/cli/strategy/manual_commit_logs.go+12/-12

14 unmodified lines

15
16
17
18
18
19
20
4 unmodified lines

25
26
27
29
30
28
29
30
31
33
34
32
33
34
35
36
37
39
38
39
40
41
1 unmodified line

43
44
45
47
46
47
48
49
25 unmodified lines

75
76
77
79
78
79
80
81
82
83
84
85
26 unmodified lines

112
113
114
112
115
114
115
116
117
118
119
120

14 unmodified lines

"github.com/entireio/cli/cmd/entire/cli/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/logging"
    "github.com/entireio/cli/cmd/entire/cli/paths"

"github.com/go-git/go-git/v6"
    "github.com/go-git/go-git/v6/plumbing"
4 unmodified lines

// disconnectedOnce ensures the disconnection warning runs at most once per process.
var disconnectedOnce sync.Once //nolint:gochecknoglobals // intentional per-process gate

// IsMetadataDisconnected checks whether the local metadata branch
// and the provided fetched or remote-tracking ref exist but share no common
// IsMetadataDisconnected checks whether the local primary metadata ref and
// the provided fetched or remote-tracking ref exist but share no common
// ancestor.
func IsMetadataDisconnected(ctx context.Context, repo *git.Repository, remoteRefName plumbing.ReferenceName) (bool, error) {
refName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
localRef, err := repo.Reference(refName, true)
refs := checkpoint.ResolveCommittedRefs(ctx)
localRef, err := repo.Reference(refs.Primary, true)
if errors.Is(err, plumbing.ErrReferenceNotFound) {
return false, nil
}
if err != nil {
return false, fmt.Errorf("failed to check local metadata branch: %w", err)
return false, fmt.Errorf("failed to check local primary metadata ref: %w", err)
}

remoteRef, err := repo.Reference(remoteRefName, true)
1 unmodified line
return false, nil
}
if err != nil {
return false, fmt.Errorf("failed to check remote metadata branch: %w", err)
return false, fmt.Errorf("failed to check remote metadata ref: %w", err)
}

if localRef.Hash() == remoteRef.Hash() {
25 unmodified lines

return
}

d
repo.Close()

disconnected, err := IsMetadataDisconnected(ctx, repo, plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName))
refs := checkpoint.ResolveCommittedRefs(ctx)
if !refs.PrimaryFetchableFromOrigin() {
return // origin doesn't track Primary; nothing to disconnect from
}
disconnected, err := IsMetadataDisconnected(ctx, repo, plumbing.NewRemoteReferenceName("origin", refs.Primary.Short()))
if err != nil {
logging.Debug(ctx, "metadata disconnection check failed",
    slog.String("error", err.Error()))
26 unmodified lines

w io.Writer,
) error {
refs := checkpoint.ResolveCommittedRefs(ctx)
refName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)

// Check local branch
localRef, err := repo.Reference(refName, true)
// Check local primary ref
localRef, err := repo.Reference(refs.Primary, true)
if errors.Is(err, plumbing.ErrReferenceNotFound) {
return nil // No local branch — nothing to reconcile
}