backup: #904 v15 - two codex P2 v14 fixes

## Codex P2 v14 (1/2): mismatch cleanup must not delete directories

v12 added os.Remove(cfg.outputPath) on the self-test-mismatch branch
of writeAndPublish to keep the sidecar+FSM internally consistent.
That removal was unconditional. If --output names a directory (an
operator typo — e.g. forgot the .fsm filename and passed a directory
instead), the normal publish path would have failed at os.Rename,
but the mismatch cleanup branch would silently call os.Remove on the
directory and, for an empty one, delete it. Destructive behavior
specific to the mismatch path.

Fix: new helper removeStaleOutputFSM(outputPath, logger) performs an
os.Lstat first and only proceeds with os.Remove when info.Mode()
reports IsRegular. Non-regular files (directory, symlink, named
pipe, etc.) are logged at warn level and left alone. Stat errors
other than ErrNotExist are also warn-and-continue.

Pinned by TestCLISelfTestMismatchSkipsDirectoryAtOutputPath: pre-
places an empty directory at --output, drives a self-test mismatch
via the corruption seam, asserts publishErr == errSelfTestMismatch
AND the directory is still present + still a directory.

## Codex P2 v14 (2/2): classify corrupt manifests as data failures

readInputManifest returns backup.ErrInvalidManifest (invalid JSON or
schema-invariant violation) and backup.ErrUnsupportedFormatVersion
(format_version unknown) when the input MANIFEST.json is broken.
Neither sentinel was mapped in run(), so the CLI exited 1 — treating
a broken dump tree as an operator-flag error and breaking runbook
recovery paths that branch on exit status to triage corrupt-input
vs operator-typo.

Fix: extracted the error→exit-code mapping into classifyEncodeError
and added ErrInvalidManifest + ErrUnsupportedFormatVersion to the
exit-2 set. Switch-with-multiple-cases form keeps the function under
nestif/cyclop.

Pinned by TestCLIInvalidManifestExitsTwo (subtests: invalid JSON
body; unsupported format_version). Both subtests assert run() exits
exitDataErr.

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

- writeAndPublish self-test mismatch branch: os.Remove call replaced
  with removeStaleOutputFSM. Sole caller is encodeOne; the
  publishErr contract is unchanged (still errSelfTestMismatch);
  on-disk state changes ONLY when --output was a non-regular file,
  in which case the prior behavior was destructive AND wrong.
  No legitimate caller is impacted.
- run() error classification: extracted to classifyEncodeError.
  Sole caller is run(). Two additional sentinels now classify as
  exit-2 (ErrInvalidManifest, ErrUnsupportedFormatVersion); all
  prior exit-2 sentinels still classify as exit-2; exit-1 paths
  are strictly a subset of the prior set. No runbook that
  branches on exit-2 would regress; runbooks that branch on
  exit-1 will see corrupt-manifest cases move to exit-2 where
  they belong.

## Lint compliance

run() had nestif complexity 5 (six sequential errors.Is branches).
classifyEncodeError uses a switch with multiple errors.Is cases per
arm, which drops the complexity score below the linter bound.

Tests + lint green.

Author: bootjp

cmd/elastickv-snapshot-encode/main.go

@@ -81,29 +81,42 @@ func run(argv []string, logger *slog.Logger) (int, error) {
 		return exitUserErr, err
 	}
 	if err := encodeOne(cfg, logger); err != nil {
-		// Errors from the encoder layer that represent data constraints
-		// (HLC ceiling regression, JSONL layout, self-test mismatch,
-		// adapter rejecting input-tree contents) are exit 2; flag/path
-		// errors are exit 1. Runbooks branch on exit status to triage
-		// bad-dump-data vs operator typos, so this split is part of the
-		// CLI contract (codex P2 v9 #904 added the adapter-data branch).
-		if errors.Is(err, backup.ErrSelfTestLowerLastCommitTS) {
-			return exitDataErr, err
-		}
-		if errors.Is(err, backup.ErrEncodeUnsupportedDynamoDBLayout) {
-			return exitDataErr, err
-		}
-		if errors.Is(err, backup.ErrEncodeAdapterData) {
-			return exitDataErr, err
-		}
-		if errors.Is(err, errSelfTestMismatch) {
-			return exitDataErr, err
-		}
-		return exitUserErr, err
+		return classifyEncodeError(err), err
 	}
 	return exitSuccess, nil
 }
 
+// classifyEncodeError maps the encodeOne return value to a CLI exit
+// code. Data-correctness sentinels (HLC ceiling regression, JSONL
+// layout, adapter rejecting input-tree contents, self-test mismatch,
+// corrupt manifest) → exit 2; everything else → exit 1. Runbooks
+// branch on exit status to triage bad-dump-data vs operator typos,
+// so this mapping is part of the CLI contract.
+//
+// Sources of each sentinel:
+//   - ErrSelfTestLowerLastCommitTS: CLI resolveLastCommitTS + library
+//     validateEncodeOptionsData (codex P2 v2 #904)
+//   - ErrEncodeUnsupportedDynamoDBLayout: validateEncodeOptionsData
+//     (codex P2 v7 #904)
+//   - ErrEncodeAdapterData: runAdapterEncoders mark on adapter
+//     rejection (codex P2 v9 #904)
+//   - errSelfTestMismatch: writeAndPublish self-test branch
+//   - ErrInvalidManifest / ErrUnsupportedFormatVersion: readInputManifest
+//     surfacing backup.ReadManifest sentinels (codex P2 v14 #904)
+func classifyEncodeError(err error) int {
+	switch {
+	case errors.Is(err, backup.ErrSelfTestLowerLastCommitTS),
+		errors.Is(err, backup.ErrEncodeUnsupportedDynamoDBLayout),
+		errors.Is(err, backup.ErrEncodeAdapterData),
+		errors.Is(err, errSelfTestMismatch),
+		errors.Is(err, backup.ErrInvalidManifest),
+		errors.Is(err, backup.ErrUnsupportedFormatVersion):
+		return exitDataErr
+	default:
+		return exitUserErr
+	}
+}
+
 func parseFlags(argv []string) (*config, error) {
 	fs := flag.NewFlagSet("elastickv-snapshot-encode", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
@@ -312,6 +325,30 @@ func buildEncodeOptions(cfg *config, effectiveTS uint64, manifest backup.Manifes
 	return encodeOpts
 }
 
+// removeStaleOutputFSM removes outputPath ONLY if it exists and is a
+// regular file. A directory or special-file at the path is left alone
+// (codex P2 v14 #904 — the prior unconditional os.Remove would have
+// deleted an empty directory the operator passed in error to --output).
+// Errors other than ErrNotExist are downgraded to warn-and-continue so
+// the caller's primary mismatch error remains the dominant signal.
+func removeStaleOutputFSM(outputPath string, logger *slog.Logger) {
+	info, err := os.Lstat(outputPath)
+	if err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			logger.Warn("stat stale .fsm on self-test mismatch", "err", err)
+		}
+		return
+	}
+	if !info.Mode().IsRegular() {
+		logger.Warn("skip stale .fsm cleanup: --output is not a regular file",
+			"path", outputPath, "mode", info.Mode())
+		return
+	}
+	if rerr := os.Remove(outputPath); rerr != nil && !errors.Is(rerr, os.ErrNotExist) {
+		logger.Warn("remove stale .fsm on self-test mismatch", "err", rerr)
+	}
+}
+
 // writeAndPublish writes the .fsm to a temp path, runs the optional
 // self-test via EncodeSnapshot, and renames temp → output on success.
 // On self-test failure: writes mismatch.txt, removes any stale
@@ -338,15 +375,20 @@ func writeAndPublish(cfg *config, encodeOpts backup.EncodeOptions, mismatchPath
 			logger.Warn("write mismatch.txt", "err", werr)
 		}
 		// Remove the stale <output>.fsm if one exists from a prior
-		// successful run. encodeOne is about to write a fresh
-		// <output>.encode_info.json with self_test.matched=false and
-		// a NEW SHA pointing to the unpublished temp snapshot; leaving
-		// the old bytes on disk would make the sidecar describe an
-		// FSM that does not exist and violate the "self-test failure
-		// leaves no restore-visible FSM" contract (codex P2 v10 #904).
-		if rerr := os.Remove(cfg.outputPath); rerr != nil && !errors.Is(rerr, os.ErrNotExist) {
-			logger.Warn("remove stale .fsm on self-test mismatch", "err", rerr)
-		}
+		// successful run AND is a regular file. encodeOne is about to
+		// write a fresh <output>.encode_info.json with
+		// self_test.matched=false and a NEW SHA pointing to the
+		// unpublished temp snapshot; leaving old bytes on disk would
+		// make the sidecar describe an FSM that does not exist and
+		// violate the "self-test failure leaves no restore-visible
+		// FSM" contract (codex P2 v10 #904).
+		//
+		// The mode-check guards against an --output that names a
+		// directory (or any non-regular file): the normal publish
+		// path would fail at os.Rename anyway, but the mismatch
+		// cleanup must not destructively delete a directory the
+		// operator passed in error (codex P2 v14 #904).
+		removeStaleOutputFSM(cfg.outputPath, logger)
 		return result, errors.Wrap(errSelfTestMismatch, "self-test diff (see "+mismatchPath+")")
 	}
 	if err := os.Rename(tempPath, cfg.outputPath); err != nil {

cmd/elastickv-snapshot-encode/main_test.go

@@ -304,6 +304,126 @@ func readSidecar(t *testing.T, output string) backup.EncodeInfo {
 	return info
 }
 
+// TestCLISelfTestMismatchSkipsDirectoryAtOutputPath pins codex P2 v14
+// #904: the self-test-mismatch cleanup must NOT delete an --output
+// path that resolves to a directory (or any non-regular file). The
+// prior unconditional os.Remove(cfg.outputPath) would have wiped an
+// empty directory the operator passed in error.
+//
+// The fixture pre-creates an empty directory at the --output path,
+// drives a self-test mismatch, asserts publishErr == errSelfTestMismatch,
+// and asserts the directory is STILL PRESENT (the destructive
+// cleanup did not fire). The normal publish path would have failed
+// at os.Rename — this test pins the mismatch-cleanup-specific guard.
+func TestCLISelfTestMismatchSkipsDirectoryAtOutputPath(t *testing.T) {
+	t.Parallel()
+	rawIn := t.TempDir()
+	writeSQSFixture(t, rawIn)
+	emitMinimalManifest(t, rawIn, 7000)
+	canonicalIn := canonicalizeInput(t, rawIn, 7000)
+
+	out := filepath.Join(t.TempDir(), "out.fsm")
+	// Pre-create a directory at the --output path — an operator
+	// typo, but the cleanup MUST NOT destructively remove it.
+	if err := os.Mkdir(out, 0o755); err != nil {
+		t.Fatalf("Mkdir: %v", err)
+	}
+
+	scratchBase := t.TempDir()
+	encodeOpts := backup.EncodeOptions{
+		InputRoot:            canonicalIn,
+		Adapters:             backup.AdapterSet{SQS: true},
+		LastCommitTS:         7000,
+		ManifestLastCommitTS: 7000,
+		SelfTest:             true,
+		SelfTestDecodeOptions: backup.DecodeOptions{
+			OutRoot:  scratchBase,
+			Adapters: backup.AdapterSet{SQS: true},
+		},
+	}
+	encodeOpts.SetSelfTestCorruptHookForTest(func(f *os.File) {
+		info, ferr := f.Stat()
+		if ferr != nil {
+			t.Fatalf("temp Stat: %v", ferr)
+		}
+		const headerSkip = 200
+		if info.Size() <= headerSkip {
+			t.Fatalf("temp file too small to corrupt: %d", info.Size())
+		}
+		buf := make([]byte, info.Size()-headerSkip)
+		if _, rerr := f.ReadAt(buf, headerSkip); rerr != nil {
+			t.Fatalf("ReadAt: %v", rerr)
+		}
+		for i := 0; i < len(buf); i += 13 {
+			buf[i] ^= 0xFF
+		}
+		if _, werr := f.WriteAt(buf, headerSkip); werr != nil {
+			t.Fatalf("WriteAt: %v", werr)
+		}
+	})
+
+	cfg := &config{
+		inputPath:  canonicalIn,
+		outputPath: out,
+		adapters:   backup.AdapterSet{SQS: true},
+		selfTest:   true,
+	}
+	mismatchPath := out + ".mismatch.txt"
+
+	_, publishErr := writeAndPublish(cfg, encodeOpts, mismatchPath, quietLogger())
+	if !errors.Is(publishErr, errSelfTestMismatch) {
+		t.Fatalf("publishErr = %v, want errSelfTestMismatch", publishErr)
+	}
+	info, statErr := os.Stat(out)
+	if statErr != nil {
+		t.Fatalf("output path missing after mismatch (codex P2 v14 destructive cleanup regression): %v", statErr)
+	}
+	if !info.IsDir() {
+		t.Errorf("output mode = %s; expected the pre-placed directory to be preserved", info.Mode())
+	}
+}
+
+// TestCLIInvalidManifestExitsTwo pins codex P2 v14 #904: a malformed
+// MANIFEST.json (invalid JSON or unsupported format_version) surfaces
+// backup.ErrInvalidManifest / backup.ErrUnsupportedFormatVersion from
+// readInputManifest, and the CLI MUST map both to exit 2
+// (data-correctness). Treating a broken manifest as exit 1 misroutes
+// runbook recovery for corrupt-dump scenarios.
+func TestCLIInvalidManifestExitsTwo(t *testing.T) {
+	t.Parallel()
+	t.Run("invalid JSON body", func(t *testing.T) {
+		t.Parallel()
+		in := t.TempDir()
+		if err := os.WriteFile(filepath.Join(in, "MANIFEST.json"), []byte("{not json"), 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+		out := filepath.Join(t.TempDir(), "out.fsm")
+		code, err := run([]string{"--input", in, "--output", out}, quietLogger())
+		if err == nil {
+			t.Fatalf("run succeeded; want manifest parse error")
+		}
+		if code != exitDataErr {
+			t.Errorf("exit code = %d, want %d (invalid manifest is data-correctness)", code, exitDataErr)
+		}
+	})
+	t.Run("unsupported format_version", func(t *testing.T) {
+		t.Parallel()
+		in := t.TempDir()
+		if err := os.WriteFile(filepath.Join(in, "MANIFEST.json"),
+			[]byte(`{"format_version":99,"last_commit_ts":1}`), 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+		out := filepath.Join(t.TempDir(), "out.fsm")
+		code, err := run([]string{"--input", in, "--output", out}, quietLogger())
+		if err == nil {
+			t.Fatalf("run succeeded; want unsupported format_version")
+		}
+		if code != exitDataErr {
+			t.Errorf("exit code = %d, want %d (unsupported manifest format_version is data-correctness)", code, exitDataErr)
+		}
+	})
+}
+
 // TestCLIWriteAndPublishRemovesStaleFSMOnSelfTestMismatch pins codex
 // P2 v10 #904: when a prior successful run left an <output>.fsm on
 // disk and a new --self-test invocation produces a mismatch,