docs/command-surface.md

@@ -97,17 +97,22 @@ broken — is skipped by every later run forever and no backfill repairs it. Wit
 and replaced when it does not match. It costs a full GET per existing blob, so
 it is a repair pass, not the default.
 
-**After a repair, purge the pull zone before believing `verify`.** A repair is
+**After a repair, `verify` is what tells you which keys to purge.** A repair is
 the one thing that makes a key serve different bytes than it did before, and the
 edge caches these objects for 30 days precisely because that normally cannot
-happen. The two commands therefore look at different copies on purpose: `emit
---verify` repairs the **origin**, `verify` reads the **edge**, and in between a
-warm PoP still answers with the old bytes while a cold one answers with the new.
-Until the zone is purged `verify`'s verdict is per-PoP and settles nothing — a
-pass is not proof, and a failure is not the repair having failed. The purge is
-one call against the pull zone; it belongs in the repair procedure rather than
-in `emit`, which holds a storage credential and no CDN one (sow-tools#89, and
-the procedure itself is in sow-platform's NWSync runbook).
+happen. The two commands look at different copies on purpose: `emit --verify`
+repairs the **origin**, `verify` reads the **edge**. So a `verify` run straight
+after a repair is not a verdict — it is a survey, and every blob it still calls
+bad is one the edge is serving stale. Purge exactly those, then re-run it; only
+that second run is the verdict.
+
+Purging the keys `verify` names beats purging the zone, because the edge only
+ever cached what somebody actually fetched: the 2026-08-01 repair rewrote 2,603
+blobs at the origin and left 8 stale at the edge. The purge belongs in the
+repair procedure rather than in `emit`, which reports how many blobs it wrote
+and never which ones — so it could not target one even with a CDN credential,
+which it deliberately does not hold (#89; the procedure itself is in
+sow-platform's NWSync runbook).
 
 `emit` uploads blobs first and the index last, so the presence of an index is
 the publication marker: an artifact whose emit died halfway leaves real blobs in

internal/nwsync/run.go

@@ -67,8 +67,9 @@ check on a published blob upstream of a player's client.
 --verify makes emit hash what it would otherwise skip. emit normally treats a
 blob's presence as proof of its contents, so without this an object written
 truncated, or written by an emitter since found broken, is skipped forever.
---verify repairs the storage zone, while verify reads the edge in front of it,
-so purge the pull zone after a repair or verify answers differently per PoP.
+--verify repairs the storage zone, while verify reads the edge in front of it.
+So a verify run right after a repair is a survey, not a verdict: it names the
+keys the edge still serves stale. Purge those, then run it again.
 
 --out DIR writes to a local repository tree instead of uploading, which is the
 conformance path against upstream nwn_nwsync_write. Without it, the zone comes