backup: #904 v9 - stat InputRoot + fix godoc attribution

Two findings on v8.

## Codex P2 v8: silent empty-restore on missing/stale InputRoot

validateEncodeOptions only rejected the empty string. A library caller
that passed a typo'd or deleted InputRoot would fan-out into every
enabled adapter, each treating its missing top-level subdirectory as
a no-op. Result: a "successful" header-only .fsm — exactly the silent
empty-restore artifact the encoder is supposed to fail closed against.

CLI callers don't hit this path (they open MANIFEST.json under
InputRoot first), but the library entrypoint is now a real surface,
so the guard belongs in EncodeSnapshot itself.

Fix: validateEncodeOptions now os.Stats InputRoot after the empty-
string check, rejecting non-existent paths (wraps the stat error)
and regular files (returns a typed error). Both rejection paths run
before any byte is written and before any adapter is invoked.

Pinned by TestEncodeSnapshotRejectsMissingInputRoot (subtests:
non-existent path; regular file). Existing TestEncodeSnapshot
LibraryRoundTrip + the manifest-floor tests use t.TempDir(), which
is a directory, so they continue to pass.

## Claude v8 doc bug: EncodeSnapshot godoc attributed to wrong symbol

The EncodeSnapshot doc block sat directly above the
validateEncodeOptions doc block with no blank line between them, so
godoc tooling (and gopls) attributed the entire merged comment to
validateEncodeOptions. EncodeSnapshot — the only exported function
in this file — had no godoc at all.

Fix: relocate the EncodeSnapshot doc block to immediately precede
`func EncodeSnapshot`, separated from validateEncodeOptionsData by
a blank line. Content unchanged; only the location moved.

## Caller audit per CLAUDE.md semantic-change rule

- validateEncodeOptions gained a fail-closed pre-condition (stat +
  IsDir). All in-tree callers pass either t.TempDir() (directory) or
  a real backup root (directory). No legitimate caller is impacted;
  bad-input callers now surface a typed error instead of silently
  producing a header-only .fsm — strictly safer.
- No exported signature or error semantics changed beyond the new
  rejection path.

Tests + lint green.

Author: bootjp

internal/backup/encode_snapshot.go

@@ -147,44 +147,28 @@ type EncodeResult struct {
 	AdaptersEnabled []string
 }
 
-// EncodeSnapshot reads the directory tree at opts.InputRoot, invokes the
-// enabled per-adapter encoders in canonical fan-out order, optionally
-// runs the round-trip self-test, and writes the .fsm bytes to out.
-// The .fsm bytes are NOT returned; they go to out.
-//
-// When opts.SelfTest=false the FSM streams straight to out with a
-// sha256 tee and no extra buffering. When opts.SelfTest=true the FSM
-// is written to an on-disk temp file (encode-self-test-fsm-*) under
-// opts.SelfTestDecodeOptions.OutRoot, the file is streamed through
-// DecodeSnapshot, and bytes are copied to out ONLY if the decode
-// survives. Memory cost in self-test mode is O(1) on top of the
-// sort working set (gemini high #904 — the earlier *bytes.Buffer
-// version would OOM on multi-GB snapshots).
-//
-// Self-test failure returns (result, nil) with result.SelfTestMatched
-// == false and result.SelfTestMismatchTxt populated. Callers MUST
-// check result.SelfTestMatched before treating a nil error as success.
-// The CLI relies on this contract to write mismatch.txt + exit 2;
-// library callers should follow the same pattern.
-//
-// EncodeSnapshot does NOT read MANIFEST.json itself, but it WILL
-// enforce a floor on opts.LastCommitTS when the caller threads the
-// manifest value through opts.ManifestLastCommitTS — a low
-// LastCommitTS returns ErrSelfTestLowerLastCommitTS BEFORE any bytes
-// are written. The CLI's resolveLastCommitTS sets both fields to the
-// reconciled values, and library callers SHOULD do the same. The
-// check is opt-in (ManifestLastCommitTS=0 disables it) so synthetic
-// test fixtures without a manifest reference can still call this
-// directly (codex P2 v2 #904).
 // validateEncodeOptions enforces the four pre-encode invariants:
-// InputRoot/out non-nil, non-empty adapter selection, optional
-// manifest-TS floor, and DDB JSONL guard. Split out so EncodeSnapshot
-// stays under the cyclop threshold; per-check helpers below keep each
-// branch's intent narrow.
+// InputRoot non-empty + exists-as-directory, out non-nil, non-empty
+// adapter selection, optional manifest-TS floor, and DDB JSONL guard.
+// Split out so EncodeSnapshot stays under the cyclop threshold; the
+// data-correctness checks live in validateEncodeOptionsData.
 func validateEncodeOptions(opts EncodeOptions, out io.Writer) error {
 	if opts.InputRoot == "" {
 		return errors.New("backup: EncodeOptions.InputRoot is required")
 	}
+	// Stat the path so a typo'd or deleted directory surfaces here
+	// rather than fan-out-no-op'ing every adapter and producing a
+	// header-only .fsm (codex P2 v8 #904). CLI callers indirectly
+	// catch this via os.Open(MANIFEST.json) before EncodeSnapshot,
+	// but a library caller that passes a stale path needs the guard
+	// at this layer.
+	info, statErr := os.Stat(opts.InputRoot)
+	if statErr != nil {
+		return errors.Wrapf(statErr, "stat InputRoot %q", opts.InputRoot)
+	}
+	if !info.IsDir() {
+		return errors.Errorf("backup: InputRoot %q is not a directory", opts.InputRoot)
+	}
 	if out == nil {
 		return errors.New("backup: EncodeSnapshot out writer is nil")
 	}
@@ -214,6 +198,35 @@ func validateEncodeOptionsData(opts EncodeOptions) error {
 	return nil
 }
 
+// EncodeSnapshot reads the directory tree at opts.InputRoot, invokes the
+// enabled per-adapter encoders in canonical fan-out order, optionally
+// runs the round-trip self-test, and writes the .fsm bytes to out.
+// The .fsm bytes are NOT returned; they go to out.
+//
+// When opts.SelfTest=false the FSM streams straight to out with a
+// sha256 tee and no extra buffering. When opts.SelfTest=true the FSM
+// is written to an on-disk temp file (encode-self-test-fsm-*) under
+// opts.SelfTestDecodeOptions.OutRoot, the file is streamed through
+// DecodeSnapshot, and bytes are copied to out ONLY if the decode
+// survives. Memory cost in self-test mode is O(1) on top of the
+// sort working set (gemini high #904 — the earlier *bytes.Buffer
+// version would OOM on multi-GB snapshots).
+//
+// Self-test failure returns (result, nil) with result.SelfTestMatched
+// == false and result.SelfTestMismatchTxt populated. Callers MUST
+// check result.SelfTestMatched before treating a nil error as success.
+// The CLI relies on this contract to write mismatch.txt + exit 2;
+// library callers should follow the same pattern.
+//
+// EncodeSnapshot does NOT read MANIFEST.json itself, but it WILL
+// enforce a floor on opts.LastCommitTS when the caller threads the
+// manifest value through opts.ManifestLastCommitTS — a low
+// LastCommitTS returns ErrSelfTestLowerLastCommitTS BEFORE any bytes
+// are written. The CLI's resolveLastCommitTS sets both fields to the
+// reconciled values, and library callers SHOULD do the same. The
+// check is opt-in (ManifestLastCommitTS=0 disables it) so synthetic
+// test fixtures without a manifest reference can still call this
+// directly (codex P2 v2 #904).
 func EncodeSnapshot(opts EncodeOptions, out io.Writer) (EncodeResult, error) {
 	if err := validateEncodeOptions(opts, out); err != nil {
 		return EncodeResult{}, err

internal/backup/encode_snapshot_test.go

@@ -211,6 +211,54 @@ func TestEncodeSnapshotRequiresInputRoot(t *testing.T) {
 	}
 }
 
+// TestEncodeSnapshotRejectsMissingInputRoot pins codex P2 v8 #904: a
+// non-existent or non-directory InputRoot must be rejected before any
+// adapter runs. Otherwise each enabled adapter treats its missing
+// top-level subdirectory as a no-op, the call "succeeds", and the
+// caller gets a header-only .fsm — a silent empty-restore artifact.
+// CLI callers don't hit this path (they open MANIFEST.json first),
+// but library callers can pass a stale path, so the guard belongs in
+// EncodeSnapshot itself.
+func TestEncodeSnapshotRejectsMissingInputRoot(t *testing.T) {
+	t.Parallel()
+	t.Run("non-existent path", func(t *testing.T) {
+		t.Parallel()
+		missing := filepath.Join(t.TempDir(), "does-not-exist")
+		var buf bytes.Buffer
+		_, err := EncodeSnapshot(EncodeOptions{
+			InputRoot:    missing,
+			Adapters:     AdapterSet{SQS: true},
+			LastCommitTS: 1,
+		}, &buf)
+		if err == nil {
+			t.Fatalf("EncodeSnapshot with non-existent InputRoot succeeded; want error")
+		}
+		if buf.Len() != 0 {
+			t.Errorf("buf.Len = %d, want 0 (no bytes should be written for missing InputRoot)", buf.Len())
+		}
+	})
+	t.Run("regular file", func(t *testing.T) {
+		t.Parallel()
+		dir := t.TempDir()
+		filePath := filepath.Join(dir, "not-a-dir")
+		if err := os.WriteFile(filePath, []byte("x"), 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+		var buf bytes.Buffer
+		_, err := EncodeSnapshot(EncodeOptions{
+			InputRoot:    filePath,
+			Adapters:     AdapterSet{SQS: true},
+			LastCommitTS: 1,
+		}, &buf)
+		if err == nil {
+			t.Fatalf("EncodeSnapshot with file-as-InputRoot succeeded; want error")
+		}
+		if buf.Len() != 0 {
+			t.Errorf("buf.Len = %d, want 0 (no bytes should be written for non-directory InputRoot)", buf.Len())
+		}
+	})
+}
+
 // TestEncodeSnapshotRejectsLowManifestFloor pins codex P2 v2: the
 // library-level HLC floor check fails-closed when opts.LastCommitTS
 // is below opts.ManifestLastCommitTS. Defense-in-depth for the CLI's