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

docs(nwsync): purge the edge after a repair, or verify answers per PoP
ci / ci (pull_request) Successful in 3m31s
Details

Browse Source 
emit --verify repairs the storage zone; verify reads the pull zone in
front of it, on purpose, because the edge is what a player gets. A repair
is the first thing that ever makes a content-addressed key serve
different bytes, so between the two a warm PoP still answers with the old
blob and a cold one with the new — and verify's verdict settles nothing
until the zone is purged.

The purge stays out of emit: it is one call for the whole zone after a
repair, against a CDN credential emit deliberately does not hold. The
procedure itself lives in sow-platform's NWSync runbook.

Closes #89.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
archvillainette
2026-08-01 00:52:00 +02:00
co-authored by Claude Opus 5
parent 7cc53aeb68
commit 53cd6a79fb
2 changed files with 14 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/command-surface.md
+12
View File
@@ -97,6 +97,18 @@ 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
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).
`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 zone and no index. Blob names are content hashes, so re-running skips