From ae0e4a02630bd7fb270ac2696c9aed08b47c336b Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Thu, 8 Oct 2026 14:25:46 +0000
Subject: [PATCH] Document checksum recovery and synthetic module cache
 isolation

---
 docs/consumers/check.md    |  3 +++
 docs/consumers/delivery.md | 45 ++++++++++++++++++++++++++++++++++++++
 docs/development.md        | 14 ++++++++++++
 3 files changed, 62 insertions(+)

diff --git a/docs/consumers/check.md b/docs/consumers/check.md
index 47c65d2..0754fc9 100644
--- a/docs/consumers/check.md
+++ b/docs/consumers/check.md
@@ -86,6 +86,9 @@ settings are preserved, including values from Go's persistent environment
 file. The check revalidates the branch, commit, and cleanliness after
 validation.
 
+For checksum failures during dependency preparation, use the
+[module checksum investigation guide](delivery.md#investigating-module-checksum-mismatches).
+
 A successful check is evidence about the local candidate only. It does not
 check whether a remote branch or tag is available and does not create a tag.
 The [`check` command](../cli.md) reads the product and optional additional
diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md
index 2f6f993..882d8f1 100644
--- a/docs/consumers/delivery.md
+++ b/docs/consumers/delivery.md
@@ -214,3 +214,48 @@ move the tag to make a retry pass. See
 for runner-provided tag and commit variables and
 [workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax) for tag
 events, sequential steps, and the shared workspace.
+
+## Investigating module checksum mismatches
+
+During tool installation or dependency preparation, a checksum mismatch means
+the bytes Go read differ from a recorded checksum. The message alone does not
+identify whether those bytes came from the local cache or a remote source.
+Keep checksum verification enabled and retain the error, selected version,
+and relevant `go.sum` entries. Go's [module authentication reference](https://go.dev/ref/mod#authenticating)
+describes these checks.
+
+To isolate a public ReleaseKit download from application settings and the
+existing module cache, run the following with a compatible local Go toolchain.
+Replace `v0.2.0` with the affected version. This diagnostic accesses the public
+Go proxy and checksum database and retains its temporary directory for inspection.
+
+```sh
+(
+    checksum_dir=$(mktemp -d) || exit 1
+    printf 'Checksum investigation directory: %s\n' "$checksum_dir"
+    cd "$checksum_dir" || exit 1
+    GOENV=off GOFLAGS= GOWORK=off GOTOOLCHAIN=local \
+        GOPRIVATE= GONOPROXY= GONOSUMDB= \
+        GOPROXY=https://proxy.golang.org GOSUMDB=sum.golang.org \
+        GOMODCACHE="$checksum_dir/modules" \
+        go mod download -json gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0
+)
+```
+
+A successful isolated download establishes that this version verifies through
+the selected proxy. Compare its `GoMod`, `GoModSum`, and `Sum` with the affected
+cache and the application's recorded checksums. Locate the original cache with
+`go env GOMODCACHE`; Go stores downloaded module metadata separately from the
+extracted source. See the [module cache reference](https://go.dev/ref/mod#module-cache).
+
+Once a stale cache entry is confirmed, preserve a copy, quarantine that entry
+while no Go process is using it, and retry normal dependency preparation. For
+a confirmed stale `.mod`, quarantine that file alone. Preserve application
+checksums and published tags. Routine downloads can continue to use the normal
+module cache.
+
+If the isolated download also fails, investigate the selected proxy, tagged
+source, and recorded checksums with the maintainer before changing local state.
+Record any difference between proxy and direct fetching. A confirmed cache
+problem can be repaired locally; changes to published source follow the
+maintainer's immutable-release procedure.
diff --git a/docs/development.md b/docs/development.md
index 94662e3..51c1440 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -75,3 +75,17 @@ validation. The [maintainer release procedure](release.md) owns preparation,
 publication, and recovery. Hosted note-page delivery is a separate prepared
 workflow and does not change the successful-tag-push completion point. ReleaseKit
 does not declare binary deliverables.
+
+## Testing synthetic modules
+
+Tests that serve synthetic module versions through local proxies should pass a
+test-owned temporary `GOMODCACHE` to every Go subprocess that consumes those
+versions. Scope fixture-specific proxy and checksum settings to those processes.
+This applies the [testing policy's isolation requirements](policy/testing.md#test-execution-requirements)
+to module downloads and keeps fixture metadata out of developer and CI caches.
+
+Distinct fixture version numbers still occupy the real module's cache namespace.
+Use temporary caches even when the selected versions have never been published.
+Verify isolation at the shared fixture boundary; ordinary builds can continue
+to use their prepared dependency cache. Consumer recovery guidance lives in the
+[module checksum investigation guide](consumers/delivery.md#investigating-module-checksum-mismatches).