# remove read-time checkpoint ref mirroring

`4572c76`→[main](/content/gh/entireio/cli/commits/main/index.html)·

pfleidi·1mo ago·10 files·+35 added/-200 removed

Committed reads now use the configured read ref as-is. Active v1 write and fetch paths are responsible for keeping the v1.1 mirror current.

## Sessions

0adaf0f2e559View transcript

[?\ Centralize Checkpoint Metadata Mirror UpdatesCodex·GPT-5.5·1 step](/content/gh/entireio/cli/session/019e89b2-44f8-7393-aa5f-ca3123a80a76#timeline-0adaf0f2e559/index.html)

## Changes

10

- cmd/entire/cli

- checkpoint

- Mcommitted_read_store.go-106

- Mcommitted_read_store_test.go+25/-79

- Mcommitted_refs.go+1/-1

- Mstore.go+2/-2

- Mexplain.go-3

- Mexplain_test.go+2/-1

- paths

- Mpaths.go+2/-3

- Mresume_test.go+1/-1

- Mrewind.go-1

- strategy

- Mmanual_commit.go+2/-3

```
1 unmodified line

2
3
4
5
6
5
6
9
10
11
7
8
9
10
11
12
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
108
109
110
111
112
113
114
115
116
117
118

1 unmodified line

import (
	"context"
	"errors"
	"log/slog"

"github.com/go-git/go-git/v6"
	"github.com/go-git/go-git/v6/plumbing"

"github.com/entireio/cli/cmd/entire/cli/logging"
)

// NewCommittedReadStore returns a GitStore bound to the topology's read ref.
func NewCommittedReadStore(ctx context.Context, repo *git.Repository) *GitStore {
	return NewGitStoreWithRef(repo, ResolveCommittedRefs(ctx).Read)
}

// SyncCommittedReadRef advances the mirror ref to the primary tip before a read
// so a git pull (which updates the primary but not the local-only mirror) is
// reflected. No-op without a mirror. Best-effort.
func SyncCommittedReadRef(ctx context.Context, repo *git.Repository) {
	refs := ResolveCommittedRefs(ctx)
	if !refs.HasMirror() {
		return
	}
	syncMirrorForRead(ctx, repo, refs)
}

// syncMirrorForRead advances the mirror ref to the primary tip (local primary
// ref, or origin's on a fresh clone): seed when missing, advance when an
// ancestor, no-op when equal, leave a diverged ref as-is. Failures are logged.
func syncMirrorForRead(ctx context.Context, repo *git.Repository, refs CommittedRefs) {
	primaryHash, ok := resolvePrimaryTip(repo, refs.Primary)
	if !ok {
		logging.Debug(ctx, "mirror read sync skipped: no primary tip available")
		return
	}

mirrorRefName := refs.Mirror
	mirrorRef, err := repo.Reference(mirrorRefName, false)
	if errors.Is(err, plumbing.ErrReferenceNotFound) {
		setMirrorRef(ctx, repo, mirrorRefName, primaryHash) // missing — seed at primary tip
		return
	}
	if err != nil {
		// Unexpected read error — don't overwrite the ref; read it as-is.
		logging.Warn(ctx, "mirror read sync skipped: mirror ref unreadable",
			slog.String("ref", mirrorRefName.String()),
			slog.String("error", err.Error()))
		return
	}

if mirrorRef.Hash() == primaryHash {
		return // already current
	}

mirrorCommit, err := repo.CommitObject(mirrorRef.Hash())
	if err != nil {
		logging.Warn(ctx, "mirror read sync skipped: mirror ref commit unreadable",
			slog.String("ref", mirrorRefName.String()),
			slog.String("error", err.Error()))
		return
	}
	primaryCommit, err := repo.CommitObject(primaryHash)
	if err != nil {
		logging.Warn(ctx, "mirror read sync skipped: primary commit unreadable",
			slog.String("error", err.Error()))
		return
	}

isAncestor, err := mirrorCommit.IsAncestor(primaryCommit)
	if err != nil {
		logging.Warn(ctx, "mirror read sync skipped: ancestry check failed",
			slog.String("error", err.Error()))
		return
	}
	if !isAncestor {
		// Diverged from the primary: leave the ref untouched and read it as-is.
		logging.Warn(ctx, "mirror ref diverged from primary; reading mirror ref as-is",
			slog.String("ref", mirrorRefName.String()),
			slog.String("mirror_hash", mirrorRef.Hash().String()),
			slog.String("primary_hash", primaryHash.String()))
		return
	}

setMirrorRef(ctx, repo, mirrorRefName, primaryHash)
}

// resolvePrimaryTip returns the primary metadata tip, preferring the local
// primary ref and falling back to origin's remote-tracking branch (so the
// mirror can seed on a fresh clone).
func resolvePrimaryTip(repo *git.Repository, primary plumbing.ReferenceName) (plumbing.Hash, bool) {
	if ref, err := repo.Reference(primary, true); err == nil {
		return ref.Hash(), true
	}
	if primary.IsBranch() {
		tracking := plumbing.NewRemoteReferenceName("origin", primary.Short())
		if ref, err := repo.Reference(tracking, true); err == nil {
			return ref.Hash(), true
		}
	}
	return plumbing.ZeroHash, false
}

// setMirrorRef points refName at hash; failures are logged and swallowed so the
// read can proceed against the ref as-is.
func setMirrorRef(ctx context.Context, repo *git.Repository, refName plumbing.ReferenceName, hash plumbing.Hash) {
	if err := repo.Storer.SetReference(plumbing.NewHashReference(refName, hash)); err != nil {
		logging.Warn(ctx, "mirror read sync failed to advance mirror ref",
			slog.String("ref", refName.String()),
			slog.String("error", err.Error()))
		return
	}
	logging.Debug(ctx, "mirror ref synced for read",
			slog.String("ref", refName.String()),
			slog.String("hash", hash.String()))
}

```

Mcmd/entire/cli/checkpoint/committed_read_store.go-106

```
95 unmodified lines

96
97
98
99
100
101
102
103
104
99
100
101
102
103
104
111
112
113
114
115
116
117
118

1 unmodified line