Document checksum recovery and synthetic module cache isolation

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.