set_initial_sync_complete can express the unguarded true direction — narrow its type

[MichaelTaylor3d]

Task

set_initial_sync_complete (crates/dig-wallet/src/sage/db.rs) is a raw, unguarded setter for initial_sync_complete with no production caller. Make it unreachable from production code.

Why it matters now rather than as tidiness

dig-node#454 has just made every real writer of that flag take a reset_epoch guard, because an unguarded write is the money-lie defect that PR exists to close: a catch-up completing after a cache reset set initial_sync_complete = 1 over an emptied table, producing balance 0, synced true on a funded wallet — proven by execution, not by reading.

Two writers were found and guarded (complete_catch_up and refresh_tracked_coins; the second was found only because someone went looking for a sibling). This setter is a third path to the same state that bypasses the guard entirely. It is safe today only because nothing calls it — which is precisely the condition that changes the moment someone needs to set that flag and finds a function whose name says it does exactly that.

The guard is the invariant. A public unguarded setter beside it is an invitation to re-open the hole, and the next author will have no reason to suspect one exists.

Scope

Make it #[cfg(test)], or delete it if the tests do not need it either. Confirm the no-caller claim yourself before removing anything — git grep set_initial_sync_complete across the workspace, not just the crate, since a consumer outside dig-wallet would make this a breaking change rather than a cleanup.

If tests genuinely need to force the flag, keep it test-only and name it so its danger is on its face (force_initial_sync_complete_for_test, or similar). A test-only escape hatch is fine; an ambiguous one is what this ticket is about.

Evidence

Found by the dig-node#454 lane while guarding the two real writers, and flagged by it as "a loaded gun for the next writer" — correctly filed rather than folded into an unrelated diff.

Acceptance

initial_sync_complete cannot be written from production code except through a reset_epoch-guarded path, enforced by the compiler rather than by convention. A test that greps for callers is not sufficient — the point is that the next writer cannot reach it, not that today's writers do not.

[MichaelTaylor3d]

Correction — the premise of this ticket is WRONG, and the real reason is different

I filed this saying the setter has no production caller. That is false.

set_initial_sync_complete does have one: crates/dig-wallet/src/sage/sync.rs:952, passing false. Found by the re-gate of PR #454, which checked the claim instead of taking it from me.

The ticket still stands, but for a different and narrower reason. It is safe today not because nothing calls it, but because its only caller passes false — i.e. it only ever clears the flag, and clearing is the safe direction. The dangerous direction (true, setting the replica authoritative) is the one the reset_epoch guard exists to control, and this setter can still express it.

So the correct framing:

• Do not delete it — that would break a real caller.
• Do not make it #[cfg(test)] — same problem. My original recommendation was wrong on both counts.
• Narrow the TYPE, not the visibility. A setter that can only clear cannot re-open the hole: split it into a clear_initial_sync_complete() with no argument, or take an enum whose only production-constructible value is the clearing one. Then the compiler enforces what the git grep currently only observes.

Verify the caller's direction yourself before changing anything — my last claim about this function was wrong, and a fix built on "the only caller passes false" deserves the same scepticism I did not apply the first time.

The underlying risk is unchanged: two writers of initial_sync_complete = 1 were found and guarded in #454, the second only because someone went looking for a sibling. A third path that can express true without the guard is what this ticket exists to close.

[MichaelTaylor3d]

Fixed on loop/mc-drain-wallet, head 78c2b51, draft PR #474.

Your title is right and your body is wrong, and the difference changed the fix.

The setter DOES have a production caller

The body says "a raw, unguarded setter ... with no production caller" and asks for
#[cfg(test)]. I confirmed the no-caller claim as the ticket instructs — and got it wrong the first
time, from a truncated grep output that showed only the first 20 of 56 references, all of which
happened to be test code.

The full set contains one production call:

crates/dig-wallet/src/sage/sync.rs:952 — the reorg handler, inside apply_update, well above that
file's #[cfg(test)] boundary at line 1318:

if moved_backwards {
    tracing::warn!(... "wallet sync: replica moved backwards; clearing initial-sync-complete ...");
    db.set_initial_sync_complete(false).await?;
}

#[cfg(test)] would not have compiled. That is the ticket's own acceptance bar working — "enforced by
the compiler rather than by convention" — just earlier than intended.

The title states the correct fix: narrow the TYPE

"can express the unguarded true direction — narrow its type". Exactly. The production call writes
false, and that direction is not the defect:

direction	what it does	is it the #454 money lie?
true	arms initial_sync_complete; over an emptied table this is balance 0, synced true on a funded wallet	yes — the whole reason #454 added reset_epoch guards
false	disarms, so wallet reads fall back until a fresh catch-up	no — it can only make the node claim LESS than it knows

So gating the whole function would have removed a legitimate, conservative production capability in
order to close a hole that only exists in one of its two directions.

What shipped

pub async fn clear_initial_sync_complete(&self) -> sqlx::Result<()>   // no argument: cannot arm
async fn write_initial_sync_complete(&self, complete: bool)            // private
#[cfg(test)] pub async fn force_initial_sync_complete_for_test(&self, complete: bool)

There is no true to pass. The unguarded arm is unrepresentable rather than discouraged — the same
shape as a scalar that cannot represent a set of two. Arming stays reachable only through
complete_catch_up and record_coverage, which carry the reset_epoch guards. All 55 test call sites
were renamed to the forcing hatch, whose name carries its own danger as the ticket asks.

Evidence

The arming half is discharged structurally and cannot be a runtime assertion — which is stated in
the new test's doc-comment rather than left implied, so a reader who finds only the test does not
conclude the arming direction went unconsidered. The ticket rules out a grep-for-callers test; the type
is the enforcement.

clear_initial_sync_complete_disarms_an_armed_flag pins the direction that IS representable, from an
explicitly ARMED fixture so the clear is not asserted against an already-false flag.

dig-wallet full lib suite: 758 passed; 0 failed; 1 ignored. dig-node-service builds clean.

(Measured and fixed by the standing dig-node backlog-drain lane, 2026-08-31.)