ShadowsOverWestgate/sow-tools
7
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 38 Activity

verify is what tells you which keys to purge (#91)

Browse Source 
Running the repair disproved the advice #90 landed an hour earlier.

"Purge the zone, then believe `verify`" assumed the stale set was unknowable. It is not. `verify` reads the edge, so the run straight after a repair names every key the edge is still serving stale — a survey, not a verdict. Purge those, re-run, and the second run is the verdict.

The measured numbers are the whole argument:

| | |
| --- | --- |
| blobs rewritten at the origin | 2,603 |
| blobs stale at the edge | **8** |

All eight were ones a failed player sync had pulled ninety minutes before the backfill. The edge only caches what someone fetched, so purging the zone would have cooled 69,169 objects to fix 8.

Full sweep after the targeted purge: `verified 69177 of 69177 blobs behind 72544 resources: 0 failures, 14887519535 bytes checked`. #75's gate is met.

Docs only. Runbook side in sow-platform.

Refs #88, #89, #75.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #91
Reviewed-by: xtul <mpiasecki720@protonmail.com>
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
This commit was merged in pull request #91.
This commit is contained in:
archvillainette
2026-08-01 09:20:16 +00:00
committed by archvillainette
parent 3cac6e9484
commit f23009ed50
2 changed files with 17 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/command-surface.md
+14 -9
View File
@@ -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 and replaced when it does not match. It costs a full GET per existing blob, so
it is a repair pass, not the default. 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 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 edge caches these objects for 30 days precisely because that normally cannot
happen. The two commands therefore look at different copies on purpose: `emit happen. The two commands look at different copies on purpose: `emit --verify`
--verify` repairs the **origin**, `verify` reads the **edge**, and in between a repairs the **origin**, `verify` reads the **edge**. So a `verify` run straight
warm PoP still answers with the old bytes while a cold one answers with the new. after a repair is not a verdict — it is a survey, and every blob it still calls
Until the zone is purged `verify`'s verdict is per-PoP and settles nothing — a bad is one the edge is serving stale. Purge exactly those, then re-run it; only
pass is not proof, and a failure is not the repair having failed. The purge is that second run is the verdict.
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 Purging the keys `verify` names beats purging the zone, because the edge only
the procedure itself is in sow-platform's NWSync runbook). 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 `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 the publication marker: an artifact whose emit died halfway leaves real blobs in
internal/nwsync/run.go
+3 -2
View File
@@ -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 --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 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. 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, --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. 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 --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 conformance path against upstream nwn_nwsync_write. Without it, the zone comes