Separate an empty source from an unmatched scope, and let a verified-empty source converge

[nodo]

Replicate failed every run whose planning produced no desired refs, with one message — no source refs matched — covering unrelated conditions: the source has no refs, the source has refs the requested scope excluded, and the source has refs this reader was never shown. A caller cannot tell them apart, and the first is not always a failure: a mirror of a repository that has never been pushed to is trivially up to date, yet it reads as an error forever.

SyncPolicy.AllowEmptySource (off by default) opts into separating them:

condition	outcome
both sides asserted empty + corroborated	zero-plan success, ExecutionSummary.Converged
source empty, target has visible refs in scope	ErrSourceEmptyTargetPopulated
source's emptiness not established	ErrSourceEmptyUnverified
target's emptiness not established	ErrTargetEmptyUnverified
source has refs, exclusions removed all of them	ErrNoRefsSelected
not opted in	unchanged no source refs matched

The policy has three requirements, all rejected at the request edge rather than accepted and then ignored: Mode must be ModeReplicate, RefScope.AllRefs must be set (under a narrower scope the source listing is itself narrowed, so an empty result says nothing about the repository), and the source protocol must not be pinned to v1 — v1's ls-refs has no unborn signal, so the cross-check below could never be satisfied over it. ProtocolAuto is fine; it negotiates v2 wherever the server supports it.

git-sync does not decide that a repository is empty

It can't, on either leg. Ref hiding is invisible to the client by design, so a hidden ref and an absent one are the same observation — and the two legs hide independently.

Source. An unborn HEAD means only that HEAD's symref target does not exist. Against git 2.53:

# repo holds refs/heads/other; HEAD -> refs/heads/main, never created
unborn HEAD symref-target:refs/heads/main
<hash> refs/heads/other

# same repo, after: git config uploadpack.hideRefs refs/heads/other
unborn HEAD symref-target:refs/heads/main

Target. receive.hideRefs omits matching refs from receive-pack's advertisement:

# repo holds refs/heads/other
<hash> refs/heads/other report-status ... agent=git/2.53.0

# same repo, after: git config receive.hideRefs refs/heads/other
0000000000000000000000000000000000000000 capabilities^{} report-status ... agent=git/2.53.0

Both second responses are populated repositories, byte-identical to what empty ones send. The target case is the sharper of the two: receive.hideRefs and uploadpack.hideRefs are separate settings, and the same probe confirms upload-pack still serves refs/heads/other to fetchers while receive-pack conceals it — so a target wrongly judged empty is one whose readers see refs the source does not have.

So both assertions are inputs: SyncPolicy.SourceAssertedEmpty and TargetAssertedEmpty, supplied from repository-state queries that see past hiding. git-sync's role is to refuse to act on them unless everything it can observe agrees — nothing advertised on either side, HEAD reported unborn on the source (RefService.HeadUnborn, via protocol v2 ls-refs=unborn where advertised), and no advertised ref name dropped as invalid on either. Those checks can only refuse; none turns an absent assertion into a success, so a caller supplying nothing gets an unverified error however the wire reads.

A visible target ref is still divergence rather than an unknown: hiding can conceal refs but never invent them, so anything advertised is real. Divergence refuses rather than converging — converging means deleting every ref on the target, and the states that produce that signature (a source restored from backup, a wiped data plane, an out-of-band emptying) are the ones where the target may hold the only surviving copy.

Compatibility

The opt-in gate is checked before anything else, so a caller that has not opted in cannot receive a sentinel it has never heard of. The sentinels also avoid the historical no source refs matched text, so a consumer that substring-matches that phrase cannot read one as the other, and check order is not load-bearing. Both were defects in earlier revisions of this branch, each caught by a test rather than by reading.

Commits after the first review round

• SourceUnborn → HeadUnborn; its doc now states what the line does and does not prove.
• Emptiness moved from an inference to caller-supplied assertions on both legs, cross-checked as above.
• Ref names dropped by the new PartitionRefNames validation are retained on both sides and refuse a convergence claim: they leave a ref set empty while the repository plainly holds refs.
• DryRun was dropped from the zero-plan success, so a replicate-mode plan of two empty repositories reported execution.dryRun=false. Fixed, with a regression test.
• Exported docs on SyncPolicy and ErrSourceEmptyUnverified corrected where they still described the superseded unborn-only contract.

Commits after the second review round

A follow-up review found the policy inert or wrong on several of its own headline paths.

It could never fire for a mapping-scoped mirror. The decision hung off len(desiredRefs) == 0, after planning — but planner.BuildDesiredRefs errors on a mapped source ref that is absent, which on a genuinely empty source is every mapping. A mapping-pinned mirror got source ref X not found, matching none of the sentinels, on exactly the state the policy exists to make succeed. An empty advertisement is now resolved before planning, where under AllRefs it is already a complete observation.

Divergence ignored the request's own scope. The target check counted every advertised ref, unlike every other consumer of the target ref map. A mirror trimming refs/pull/* whose target held only refs/pull/1/head was reported as permanently diverged over a ref it would neither push nor prune — and refs/pull/* is the namespace these docs cite as the benign case.

SourceEmpty → Converged, and it is now visible. The flag requires both sides verified, so false did not mean "the source has refs" — it was false in the diverged outcome too, where the source was verified empty. It also carried omitempty, alone among the discriminating bools, so for the field whose whole purpose is separating a converged run from a no-op, false and "this binary has no such field" were the same JSON. And Result.Lines() never rendered it, so the text output the CLI actually prints was byte-identical to an ordinary zero-work sync.

The corroboration was vacuous on v1. RefService.SkippedRefNames was set at one of four construction sites; it failed closed only because the !HeadUnborn check happens to run first. It is now a count set on every path through one constructor — which also stops the slice being pinned to a struct that outlives the pack transfer.

A protocol limit was reported as a hostile server. did not report an unborn HEAD tells an operator their source is withholding refs, pointing at a hideRefs misconfiguration or a compromised source. Over v1 — including an auto SSH source that falls back mid-run — the real cause is that the protocol has no such signal. The two are now distinguished, as is a v2 source that does not advertise ls-refs=unborn.

Nothing covered the wiring the design rests on. Every test hand-built a syncSession, so the chain from the ls-refs argument through HeadUnborn to a converged Result had no coverage: deleting the request argument left the whole suite green. The in-package fake v2 server advertised ls-refs=unborn but never emitted an unborn line; it does now, and Run is exercised end to end. Reverting any fix in this round turns a test red.

Also: s.target is guarded (it is legitimately nil on Fetch and target-less Probe sessions); ErrNoRefsSelected's doc named two causes unreachable by construction; the divergence count is labelled; and docs/protocol.md now documents the unborn argument.

One caller-visible wire change

unborn is appended to every v2 ls-refs request whose server advertises support for it — probe, plan, sync, replicate, bootstrap, fetch — not only for callers who opted into this policy. That is deliberate: it costs no round trip, and a source with commits answers exactly as before. It does mean the earlier claim that nothing changes for existing callers was too strong for the wire, so the CHANGELOG is corrected and both the argument and its advertisement gate are pinned by tests.

Review caught that the original justification here — that it lets Probe report an unborn HEAD — was not actually implemented; HeadUnborn had a single reader behind the policy. Rather than walk the rationale back, ProbeResult.SourceHeadUnborn now exists, so the claim is true: an operator asking "why will this mirror not converge" can see whether the source reported unborn at all, which is otherwise unobservable from outside. It is diagnostic only and carries none of the policy's weight.

What "in scope" means for divergence

Three Bugbot rounds went into getting this right, so it is worth stating plainly. A target ref counts as divergence only if the request is responsible for it — planner.TargetScope.Manages, which is the union of push scope and prune scope:

target ref	in scope?
a declared mapping target	yes, and exclusions do not remove it (matching BuildDesiredRefs' mapping pass)
a tag, with IncludeTags or AllRefs	yes
other-kind (refs/notes/*, …) under AllRefs	yes — auto-discovery pushes these even with Mappings set
an unmapped branch, with Mappings set	no — the branch pass is in the else, and prune skips it
anything matching ExcludeRefPrefixes / ExcludeRefs	no
a zero hash	no — a deletion sentinel, not a ref

Both directions of getting this wrong are real and they fail oppositely: too narrow leaves a mirror permanently diverged over a ref it would never touch, too wide converges over a target still holding refs the source does not have. The second is the one that deletes data, and it is what the last two rounds were.

planner.PruneTarget answers only the prune half and is deliberately not widened — that would change what prune actually deletes, a live behaviour change outside this branch. The push/prune asymmetry under mappings is the planner's existing contract.

Separate commit: a prune bug this branch did not introduce

unstable's buildSyncConfig, buildBootstrapConfig and buildFetchConfig each forwarded Scope.ExcludeRefPrefixes but dropped Scope.ExcludeRefs, which the stable client threads. Under Prune, a ref the caller had explicitly reserved became a prune candidate and was deleted from the target. It is first in the branch and independent of everything above — happy to split it out if you would rather review it alone.

It is also the class the reflection guard was added to catch, and could not: the guard walked only bool fields on SyncPolicy, never RefScope. It now covers both, from one shared implementation instead of two copies that had already drifted, and no longer panics on an unexported field or a same-named field of a different type.

No behavior change for the CLI or any existing embedder beyond the ls-refs argument noted above. Note that neither assertion has a caller in this PR, so nothing reports a converged empty source yet — the safe direction, and what the opt-in default gives anyway.

🤖 Generated with Claude Code

https://claude.ai/code/session_01714HJZAqpgwuwp6fcMWEhG

---

Note

Medium Risk
Changes replicate empty-set classification and v2 ls-refs on the wire, plus prune scope via ExcludeRefs. Default empty-source errors stay the same unless callers opt in, but a wrong emptiness claim could still mis-report convergence vs divergence.

Overview
Adds opt-in SyncPolicy.AllowEmptySource so Replicate can treat a verified empty source as success instead of collapsing every empty desired set into no source refs matched.

Callers must assert emptiness on both sides (SourceAssertedEmpty / TargetAssertedEmpty); git-sync only corroborates (empty ads, v2 unborn HEAD, no dropped invalid names, no in-scope target refs). Outcomes: Converged zero-plan success, ErrNoRefsSelected, ErrSourceEmptyUnverified, ErrTargetEmptyUnverified, or ErrSourceEmptyTargetPopulated (refuses rather than deleting target refs). Policy is replicate-only, requires AllRefs, and rejects pinned v1 at the request edge. Off by default.

Every v2 ls-refs now requests unborn when advertised (not policy-gated). Unstable config builders now thread ExcludeRefs (was dropped, so prune could delete reserved refs). Reflection guards cover policy/scope field threading.

^{Reviewed by Cursor Bugbot for commit 6d1eb86. Configure here.}

[nodo]

bugbot run

[nodo]

bugbot run

[nodo]

bugbot run

[nodo]

bugbot run

[nodo]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6d1eb86. Configure here.}

[Soph]

No blockers. The dangerous direction — Converged: true while the target holds refs the source lacks — is guarded, and I verified it by mutation testing rather than reading: reverting Manages to delegate wholly to PruneTarget, forcing scope.Manages true, disabling the inScope > 0 check, dropping the unborn ls-refs argument, and re-dropping Scope.ExcludeRefs in unstable each turn a test red. Build, vet and the full suite are green.

Five findings below — two medium, three low. None is a correctness bug.