backup: PR810 r6 — codex r5 P2 (empty CHECKSUMS + missing-target classification)

Two codex P2 findings on r5 (commit 7a8e2f3):

1. (codex P2, checksums.go:256) VerifyChecksums returned nil on
   a CHECKSUMS file with zero parsed rows (empty file, blank
   lines only). Phase 0a dumps are non-empty by construction
   (WriteChecksums lists every regular file), so a zero-row
   CHECKSUMS is always a producer-side corruption signal, never
   a benign shape. The verifier was hiding partial-write or
   truncation failures behind a "no rows checked == OK" answer.

   Fix: VerifyChecksums now counts verified rows and returns
   ErrChecksumsEmpty when the count is zero. Blank lines still
   skip silently (matching sha256sum -c's tolerance of trailing
   newlines) but do not satisfy the at-least-one-row guard.

   Test: TestVerifyChecksums_RejectsEmptyChecksumsFile covers
   three corruption shapes (empty file, blank lines only,
   trailing-newline only).

2. (codex P2, checksums.go:306) refuseSymlinkComponents returned
   raw fs.ErrNotExist when a CHECKSUMS-listed file was missing
   from disk. Callers branching on errors.Is(err,
   ErrChecksumMismatch) missed this case — partial restores and
   tamper-deletes produced an unclassified path error instead.

   Fix: detect fs.ErrNotExist at the refuseSymlinkComponents
   call site (and at sha256File's call site as belt-and-braces)
   and promote to ErrChecksumMismatch. The design's contract
   ("Files referenced by CHECKSUMS but missing on disk surface
   as the same error class so a partial-restore is obvious") is
   now honored.

   Test: TestVerifyChecksums_MissingTargetIsMismatch — writes
   a CHECKSUMS row, deletes the listed file, asserts
   ErrChecksumMismatch via errors.Is.

API shape: verifyOneChecksumLine returns (bool, error) so the
parent loop can count "real" verified rows separately from
blank-line skips. Internal helper; signature change does not
escape the package.

Caller audit:
- verifyOneChecksumLine is internal to checksums.go; the
  signature change is contained.
- VerifyChecksums has no production callers yet (test-only).
  The new ErrChecksumsEmpty and the promoted ErrChecksumMismatch
  shapes are additive on the typed-sentinel surface; honest
  CHECKSUMS still verify cleanly.

Self-review:
1. Data loss — none; both fixes catch silent-corruption signals.
2. Concurrency — none.
3. Performance — one int counter per file; sha256 streaming
   unchanged.
4. Data consistency — empty-CHECKSUMS hole closed; missing-
   target now classified.
5. Test coverage — two new tests; existing thirteen CHECKSUMS
   tests still pass.

Author: bootjp

internal/backup/checksums.go

@@ -6,6 +6,7 @@ import (
 	"encoding/hex"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"sort"
@@ -233,48 +234,98 @@ func VerifyChecksums(root string) error {
 	sc := bufio.NewScanner(f)
 	sc.Buffer(make([]byte, 0, maxChecksumLineLen), maxChecksumLineLen)
 	lineNum := 0
+	verified := 0
 	for sc.Scan() {
 		lineNum++
-		if err := verifyOneChecksumLine(root, sc.Text(), lineNum); err != nil {
+		got, err := verifyOneChecksumLine(root, sc.Text(), lineNum)
+		if err != nil {
 			return err
 		}
+		if got {
+			verified++
+		}
 	}
 	if err := sc.Err(); err != nil {
 		return errors.WithStack(err)
 	}
+	// Refuse a CHECKSUMS that yielded zero verified rows. An empty
+	// (or all-blank) file would otherwise pass verification and
+	// hide a producer-side corruption — the dump tree itself is
+	// non-empty (WriteChecksums lists every regular file), so a
+	// CHECKSUMS with no rows is always a signal, never a benign
+	// shape. Codex r5 P2 on PR #810.
+	if verified == 0 {
+		return errors.WithStack(ErrChecksumsEmpty)
+	}
 	return nil
 }
 
+// ErrChecksumsEmpty is returned by VerifyChecksums when the
+// CHECKSUMS file parsed to zero checksum rows (empty file, all
+// blank lines, or comment-only — none of which are valid Phase 0a
+// dump shapes). Typed so callers can distinguish "CHECKSUMS file
+// did not list anything" from "a listed file mismatched".
+var ErrChecksumsEmpty = errors.New("backup: CHECKSUMS contains no checksum rows")
+
 // verifyOneChecksumLine handles a single CHECKSUMS line: parse,
 // path-validate, recompute, compare. Extracted from VerifyChecksums
 // so the parent stays under the project's cyclop ceiling and the
 // per-line failure modes (malformed shape, traversal, symlink
 // escape, missing file, mismatch) each surface as a distinct
 // typed error.
-func verifyOneChecksumLine(root, line string, lineNum int) error {
+//
+// Returns (verified, err): verified=true when the line was a real
+// checksum row that VerifyChecksums should count toward the
+// "at least one row" empty-file guard (blank lines do not count).
+// A missing file referenced by an honest CHECKSUMS row is
+// surfaced as ErrChecksumMismatch — partial restores and
+// adversarial deletions land in the same typed failure class
+// callers branch on. Codex r5 P2 on PR #810.
+func verifyOneChecksumLine(root, line string, lineNum int) (bool, error) {
 	if line == "" {
-		return nil
+		return false, nil
 	}
 	want, rel, ok := splitChecksumLine(line)
 	if !ok {
-		return errors.Wrapf(ErrChecksumsMalformedLine, "line %d: %q", lineNum, line)
+		return false, errors.Wrapf(ErrChecksumsMalformedLine, "line %d: %q", lineNum, line)
 	}
 	cleaned, err := validateChecksumRelPath(rel)
 	if err != nil {
-		return errors.Wrapf(err, "line %d", lineNum)
+		return false, errors.Wrapf(err, "line %d", lineNum)
 	}
 	joined := filepath.Join(root, cleaned)
 	if err := refuseSymlinkComponents(root, cleaned); err != nil {
-		return errors.Wrapf(err, "line %d", lineNum)
+		// Missing file along the resolved path is a partial-
+		// restore / tamper signal — same operational category
+		// as a hash mismatch. The Lstat-walk caller bubbles up
+		// raw fs.ErrNotExist; promote it to the typed
+		// ErrChecksumMismatch class so callers branching on
+		// errors.Is keep covering this case. Codex r5 P2 on
+		// PR #810.
+		if errors.Is(err, fs.ErrNotExist) {
+			return false, errors.Wrapf(ErrChecksumMismatch,
+				"%s: missing on disk", cleaned)
+		}
+		return false, errors.Wrapf(err, "line %d", lineNum)
 	}
 	got, err := sha256File(joined)
 	if err != nil {
-		return errors.Wrapf(err, "verifying %s", cleaned)
+		// A missing target is a partial-restore or tamper
+		// signal; either way it is operationally identical to
+		// a checksum mismatch for the caller. Surface as
+		// ErrChecksumMismatch so `errors.Is(err,
+		// ErrChecksumMismatch)` covers both cases. Codex r5 P2
+		// on PR #810.
+		if errors.Is(err, fs.ErrNotExist) {
+			return false, errors.Wrapf(ErrChecksumMismatch,
+				"%s: missing on disk", cleaned)
+		}
+		return false, errors.Wrapf(err, "verifying %s", cleaned)
 	}
 	if got != want {
-		return errors.Wrapf(ErrChecksumMismatch, "%s: have %s want %s", cleaned, got, want)
+		return false, errors.Wrapf(ErrChecksumMismatch, "%s: have %s want %s", cleaned, got, want)
 	}
-	return nil
+	return true, nil
 }
 
 // refuseSymlinkComponents walks rel one path segment at a time

internal/backup/checksums_test.go

@@ -393,6 +393,63 @@ func TestSplitChecksumLine_RejectsDanglingEscape(t *testing.T) {
 	}
 }
 
+// TestVerifyChecksums_RejectsEmptyChecksumsFile is the regression
+// for codex r5 P2 on PR #810: a CHECKSUMS file with zero parsed
+// rows (empty, blank lines only) previously returned nil, hiding
+// a producer-side corruption. The dump tree is non-empty by
+// construction (WriteChecksums lists every regular file), so an
+// empty CHECKSUMS is always a signal.
+func TestVerifyChecksums_RejectsEmptyChecksumsFile(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		body string
+	}{
+		{"empty file", ""},
+		{"blank lines only", "\n\n\n"},
+		{"trailing newline only", "\n"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			root := t.TempDir()
+			mustWrite(t, filepath.Join(root, CHECKSUMSFilename), []byte(tc.body))
+			err := VerifyChecksums(root)
+			if err == nil {
+				t.Fatalf("expected ErrChecksumsEmpty for %q, got nil", tc.body)
+			}
+			if !errors.Is(err, ErrChecksumsEmpty) {
+				t.Fatalf("err = %v, want ErrChecksumsEmpty", err)
+			}
+		})
+	}
+}
+
+// TestVerifyChecksums_MissingTargetIsMismatch is the regression
+// for codex r5 P2 on PR #810: a CHECKSUMS line whose listed file
+// was deleted from disk (partial restore / tamper) now surfaces
+// as ErrChecksumMismatch — previously the raw fs.ErrNotExist
+// bubbled up through refuseSymlinkComponents and bypassed the
+// typed checksum-failure path callers branch on.
+func TestVerifyChecksums_MissingTargetIsMismatch(t *testing.T) {
+	t.Parallel()
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "a.txt"), []byte("hello"))
+	if err := WriteChecksums(root); err != nil {
+		t.Fatalf("WriteChecksums: %v", err)
+	}
+	if err := os.Remove(filepath.Join(root, "a.txt")); err != nil {
+		t.Fatalf("rm a.txt: %v", err)
+	}
+	err := VerifyChecksums(root)
+	if err == nil {
+		t.Fatalf("expected ErrChecksumMismatch for missing target, got nil")
+	}
+	if !errors.Is(err, ErrChecksumMismatch) {
+		t.Fatalf("err = %v, want ErrChecksumMismatch", err)
+	}
+}
+
 // TestVerifyChecksums_StreamsLargeFile pins the bufio.Scanner path
 // — the previous implementation slurped the entire CHECKSUMS file
 // via os.ReadFile, which OOMs on large dump trees (gemini