sync: full_scans is not two per pass, and the docs said it was

[myobie]

sync_passes shipped three hours ago (#68) with a doc comment naming a correction factor: full_scans counts "TWO per call", and reading it as a pass rate "overstates the rate by 2x". Applying that 2x to the live fleet gives a wrong number.

Measured

Silber, one 300 s window, both entries sampled in the same window:

entry	scans per pass
st2-bus-default	3.71
st2-declarations-default	2.33

Not 2.00, and not the same on both.

Why

scan_entry has three callers, not one:

• sync_once calls it twice, once each side of the peer step.
• complete_inbound calls it exactly once per guarded inbound transaction.
• prepare_inbound_entry calls it at most once more, and skips it when the durable scan is still good.

So the relation is a bound, not a constant:

2*passes + guarded <= full_scans <= 2*passes + 2*guarded

Both live samples sit inside it. Inbound traffic is not a fixed multiple of local passes, so no constant converts one counter into the other, and the error is invisible from this side.

Why it matters

Dividing a live full_scans by 2 overstates the rate on the busy entry by 85%. That is the same class of miscorrection that produced the 58% guard figure, which was reported against the fleet and then withdrawn. This counter was added to stop that error; it documented it instead.

The test, and I watched it fail

full_scans_counts_inbound_transactions_as_well_as_passes drives three passes and two guarded inbound transactions, then pins the bound. I mutated the code to the false belief — no increment in scan_entry, fetch_add(2) in sync_once — and it failed:

inbound transactions scan too, so full_scans must exceed two per pass: scans=6, passes=3

The existing test still passed under that mutation. It runs on LoopbackTransport with no inbound traffic, so it pins the isolated path and cannot see this. That test is not wrong and is not changed; its doc now states the condition it holds under.

Scope

No behaviour changes. A comment, a test, and a bound.

Agent: Silber.fabric