# tighten committed-ref mirror visibility and ctx handling

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

pfleidi·1mo ago·3 files·+37 added/-3 removed

Three small visibility fixes for the v1.1 mirror best-effort path:

- Add ErrPrimaryMetadataMissing sentinel. MirrorCommittedMetadataRef
wraps the primary-ref NotFound case with the sentinel, so the
best-effort caller can log Debug only for that case and Warn for
every other failure — including a SetReference NotFound that the
previous errors.Is(err, plumbing.ErrReferenceNotFound) check
conflated with 'primary missing'.

- Detach cancellation in MirrorCommittedMetadataRefBestEffort with
context.WithoutCancel. A near-expired parent deadline (e.g. the
2-minute fetch budget in fetchMetadataFromOrigin) could fail
settings.Load silently inside ResolveCommittedRefs, causing
HasMirror to report false and the mirror to skip with no log. The
mirror is short and best-effort; trace/value context is preserved.

- Log Debug in mirrorSyncedMetadataBranch for the two cases that
previously returned silently (primary not a branch; branch name
does not match primary). These are future-topology guards; today
they never fire, but a silent skip would be hard to find later.

## Sessions

3372c9e81e2dView transcript

## Changes

3

- cmd/entire/cli/strategy

- Mpush_common.go+9/-1

- Mv1_custom_ref_mirror.go+15/-2

- Mv1_custom_ref_mirror_test.go+13

```
474 unmodified lines

func mirrorSyncedMetadataBranch(ctx context.Context, repo *git.Repository, branchName string) {
	refs := checkpoint.ResolveCommittedRefs(ctx)
	if !refs.Primary.IsBranch() || branchName != refs.Primary.Short() {
		if !refs.Primary.IsBranch() {
			logging.Debug(ctx, "committed-ref mirror skipped after sync: primary metadata ref is not a branch",
				slog.String("primary", refs.Primary.String()))
			return
		}
		if branchName != refs.Primary.Short() {
			logging.Debug(ctx, "committed-ref mirror skipped after sync: branch name does not match primary",
				slog.String("branch_name", branchName),
				slog.String("primary_short", refs.Primary.Short()))
			return
		}
	}
	MirrorCommittedMetadataRefBestEffort(ctx, repo)
}
```

// ErrPrimaryMetadataMissing is returned by MirrorCommittedMetadataRef when the
// primary ref does not exist yet. Callers can match this sentinel to
// distinguish "expected on first use" from a real read failure, and from a
// SetReference NotFound on the mirror itself.
var ErrPrimaryMetadataMissing = errors.New("primary metadata ref missing")

// MirrorCommittedMetadataRef points the committed-metadata mirror at the primary
// ref's tip. No-op when the topology has no mirror.
func MirrorCommittedMetadataRef(ctx context.Context, repo *git.Repository, refs checkpoint.CommittedRefs) error {
	primaryRef, err := repo.Reference(refs.Primary, true)
	if err != nil {
		if errors.Is(err, plumbing.ErrReferenceNotFound) {
			return fmt.Errorf("primary metadata ref %s missing: %w", refs.Primary, err)
			return fmt.Errorf("primary metadata ref %s missing: %w", refs.Primary, ErrPrimaryMetadataMissing)
		}
		return fmt.Errorf("read primary metadata ref %s: %w", refs.Primary, err)
	}
}

// MirrorCommittedMetadataRefBestEffort mirrors committed metadata for callers
// where mirror failure must not affect the primary operation.
//
// The mirror runs under context.WithoutCancel so a parent deadline that is
// already near-expired (e.g. the 2-minute fetch budget) cannot silently fail
// settings.Load and skip the mirror with no log. Trace/value context is
// preserved; only cancellation is detached. The mirror itself is short.
func MirrorCommittedMetadataRefBestEffort(ctx context.Context, repo *git.Repository) {
	ctx = context.WithoutCancel(ctx)

refs := checkpoint.ResolveCommittedRefs(ctx)
	if !refs.HasMirror() {
		return
	}

if err := MirrorCommittedMetadataRef(ctx, repo, refs); err != nil {
		if errors.Is(err, plumbing.ErrReferenceNotFound) {
			if errors.Is(err, ErrPrimaryMetadataMissing) {
				// No primary metadata ref yet — nothing to mirror. Expected on first use.
				logging.Debug(ctx, "committed-ref mirror skipped: primary metadata ref unavailable",
					slog.String("error", err.Error()))
			}
		}
	}
}

```

// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_SetReferenceNotFoundIsNotPrimaryMissing(t *testing.T) {
	repo := setupV1CustomRefRepo(t, `"1.1"`)
	setV1MetadataBranch(t, repo)
	repo.Storer = setReferenceErrorStorer{Storer: repo.Storer, err: plumbing.ErrReferenceNotFound}

err := MirrorCommittedMetadataRef(t.Context(), repo, v1CustomRefsForTest())
	require.Error(t, err)
	require.ErrorIs(t, err, plumbing.ErrReferenceNotFound, "SetReference NotFound should still unwrap to plumbing.ErrReferenceNotFound")
	require.NotErrorIs(t, err, ErrPrimaryMetadataMissing, "SetReference NotFound must not be mistaken for a missing primary")
}

// Not parallel: uses t.Chdir().
func TestMirrorCommittedMetadataRef_SetReferenceErrorNamesTarget(t *testing.T) {
	repo := setupV1CustomRefRepo(t, `"1.1"`)