From 53cd6a79fb64ba2a6afb02a17d6db97be2e613c9 Mon Sep 17 00:00:00 2001 From: vickydotbat Date: Sat, 1 Aug 2026 00:52:00 +0200 Subject: [PATCH] docs(nwsync): purge the edge after a repair, or verify answers per PoP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/command-surface.md | 12 ++++++++++++ internal/nwsync/run.go | 2 ++ 2 files changed, 14 insertions(+) diff --git a/docs/command-surface.md b/docs/command-surface.md index 9e17d20..05d3329 100644 --- a/docs/command-surface.md +++ b/docs/command-surface.md @@ -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 diff --git a/internal/nwsync/run.go b/internal/nwsync/run.go index 81d324c..c221797 100644 --- a/internal/nwsync/run.go +++ b/internal/nwsync/run.go @@ -67,6 +67,8 @@ 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. --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 -- 2.54.0