backup: #904 v10 - classify adapter-data rejections as exit 2

## Codex P2 v9: adapter encoder rejections fall through to exit 1

When an adapter encoder rejects the input tree's contents (a malformed
DynamoDB _schema.json, an S3 collision artifact the encoder cannot
reverse, an SQS side-record with an unknown kind, etc.), the error
propagates out of EncodeSnapshot but does not match any of the three
exit-2 sentinels (ErrSelfTestLowerLastCommitTS,
ErrEncodeUnsupportedDynamoDBLayout, errSelfTestMismatch), so the
CLI's run() falls through to exit 1. Per the CLI contract, exit 1
is operator/flag error and exit 2 is data-correctness — runbooks
branch on exit status to quarantine bad dump data, so misclassifying
adapter rejections as user error is a real ergonomic regression.

The encoder is offline-only — it operates entirely on local files
under InputRoot. Every error from an adapter encoder originates from
the contents of that tree (a sentinel rejection, an unmarshalling
failure, etc.). Treating all adapter errors as data-correctness
matches the CLI contract.

Fix:
- New ErrEncodeAdapterData sentinel in internal/backup.
- runAdapterEncoders wraps each adapter error with errors.Mark so
  errors.Is(err, ErrEncodeAdapterData) is true. Mark preserves the
  inner sentinel chain — callers that errors.Is on the per-adapter
  sentinel (ErrDDBEncodeInvalidSchema, ErrS3EncodeKeyConflict, etc.)
  are unaffected.
- CLI run() gains a fourth exit-2 branch for ErrEncodeAdapterData.

Pinned by:
- TestEncodeSnapshotMarksAdapterDataErrors (library): malformed
  _schema.json triggers ErrDDBEncodeInvalidSchema inside the DDB
  encoder; assertion verifies BOTH errors.Is(ErrEncodeAdapterData)
  AND errors.Is(ErrDDBEncodeInvalidSchema) hold - the mark is
  additive, not lossy.
- TestCLIAdapterDataErrorExitsTwo (CLI): same fixture driven
  end-to-end through run(); asserts exit code = 2 and no .fsm
  published.

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

- runAdapterEncoders return semantics: every non-nil err is now
  marked. Sole caller is EncodeSnapshot; it propagates the marked
  error unchanged.
- EncodeSnapshot callers (library tests, CLI's encodeToTempFile):
  - Library tests that errors.Is on the validation sentinels
    fire BEFORE runAdapterEncoders, so they are NOT marked.
  - CLI's encodeToTempFile wraps with "EncodeSnapshot"; the run()
    layer above it now matches ErrEncodeAdapterData and routes to
    exit-2 (new branch).
- In-tree errors.Is on per-adapter sentinels (encode_dynamodb_test.go
  et al.) call the adapter encoders directly, not through
  EncodeSnapshot, so the mark wrapper is never on their path.

Tests + lint green. wrapcheck required errors.WithStack around the
Mark.

Author: bootjp

cmd/elastickv-snapshot-encode/main.go

@@ -82,14 +82,20 @@ func run(argv []string, logger *slog.Logger) (int, error) {
 	}
 	if err := encodeOne(cfg, logger); err != nil {
 		// Errors from the encoder layer that represent data constraints
-		// (HLC ceiling regression, self-test mismatch) are exit 2; other
-		// errors are exit 1.
+		// (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
 		}

cmd/elastickv-snapshot-encode/main_test.go

@@ -77,6 +77,46 @@ func TestCLIRejectsUnknownAdapter(t *testing.T) {
 	}
 }
 
+// TestCLIAdapterDataErrorExitsTwo pins codex P2 v9 #904: when an
+// adapter encoder rejects the input tree's contents (e.g. a malformed
+// DynamoDB _schema.json with an empty table_name), the CLI exits 2
+// (data-correctness) rather than 1 (operator/flag error) so runbooks
+// can branch on exit status to quarantine bad dump data. Pinned via
+// the same ErrDDBEncodeInvalidSchema fixture pattern used by the
+// in-package DynamoDB encoder tests.
+func TestCLIAdapterDataErrorExitsTwo(t *testing.T) {
+	t.Parallel()
+	in := t.TempDir()
+	emitMinimalManifest(t, in, 100)
+	// Empty table_name triggers ErrDDBEncodeInvalidSchema inside the
+	// DynamoDB encoder; runAdapterEncoders marks it with
+	// ErrEncodeAdapterData; run() maps that to exitDataErr.
+	schemaDir := filepath.Join(in, "dynamodb", "tbl")
+	if err := os.MkdirAll(schemaDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	schemaPath := filepath.Join(schemaDir, "_schema.json")
+	body := []byte(`{"format_version":1,"table_name":"","primary_key":{"hash_key":{"name":"id","type":"S"}}}`)
+	if err := os.WriteFile(schemaPath, body, 0o600); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	out := filepath.Join(t.TempDir(), "out.fsm")
+	code, err := run([]string{
+		"--input", in,
+		"--output", out,
+		"--adapter", "dynamodb",
+	}, quietLogger())
+	if err == nil {
+		t.Fatalf("run succeeded; want adapter rejection error")
+	}
+	if code != exitDataErr {
+		t.Errorf("exit code = %d, want %d (data error from adapter rejection, not flag-parse error)", code, exitDataErr)
+	}
+	if _, statErr := os.Stat(out); !os.IsNotExist(statErr) {
+		t.Errorf(".fsm exists at %s; should not be published on adapter rejection", out)
+	}
+}
+
 // TestCLIRejectsLowerLastCommitTSOverride is the fail-closed pin per
 // parent §"MVCC re-encoding": T < manifest.last_commit_ts → exit 2
 // (data-correctness failure, not flag-parse error).

internal/backup/encode_snapshot.go

@@ -41,6 +41,22 @@ var ErrSelfTestLowerLastCommitTS = errors.New("backup: --last-commit-ts T < mani
 // until the encoder learns the JSONL layout (M7 / future milestone).
 var ErrEncodeUnsupportedDynamoDBLayout = errors.New("backup: DynamoDB JSONL layout not supported by encoder")
 
+// ErrEncodeAdapterData marks every error returned by an adapter
+// encoder (Redis / DynamoDB / S3 / SQS) so callers can distinguish
+// "the input tree contained content the encoder cannot translate"
+// from "operator passed a bad flag". The encoder is offline-only —
+// every adapter error originates from rejecting the content under
+// opts.InputRoot (a malformed DynamoDB _schema.json, an S3 collision
+// artifact the encoder cannot reverse, a SQS side-record with an
+// unknown kind, …). These are data-correctness failures, not user
+// errors; the CLI maps this sentinel to exit 2 so runbooks can branch
+// on exit status to quarantine bad dump data (codex P2 v9 #904).
+//
+// Wrapped via errors.Mark inside runAdapterEncoders so the original
+// adapter sentinel chain (ErrDDBEncodeInvalidSchema, …) is preserved
+// for callers that errors.Is on the more specific type.
+var ErrEncodeAdapterData = errors.New("backup: adapter encoder rejected input tree")
+
 // The encoder dispatch order (redis → dynamodb → s3 → sqs) is encoded
 // inside adapterRunners() and is intentionally distinct from decode.go's
 // finalize order (dynamodb → s3 → redis → sqs). The final .fsm byte
@@ -353,14 +369,20 @@ func adapterRunners() []adapterRunner {
 // runAdapterEncoders invokes each enabled adapter encoder in
 // canonicalAdapterFanOutOrder, returning the list of adapter names
 // actually invoked (for ENCODE_INFO.json adapters_enabled).
+//
+// Adapter errors are marked with ErrEncodeAdapterData so the CLI can
+// route them to exit-2 (data-correctness) rather than exit-1 (user
+// error). The original adapter sentinel chain is preserved — callers
+// that errors.Is on ErrDDBEncodeInvalidSchema, ErrS3EncodeKeyConflict,
+// etc. still see those (codex P2 v9 #904).
 func runAdapterEncoders(b *snapshotBuilder, opts EncodeOptions) ([]string, error) {
 	var enabled []string
 	for _, r := range adapterRunners() {
 		if !r.enabled(opts.Adapters) {
 			continue
 		}
 		if err := r.encode(b, opts.InputRoot); err != nil {
-			return nil, err
+			return nil, errors.WithStack(errors.Mark(err, ErrEncodeAdapterData))
 		}
 		enabled = append(enabled, r.name)
 	}

internal/backup/encode_snapshot_test.go

@@ -388,6 +388,41 @@ func TestEncodeSnapshotRejectsZeroAdapterSet(t *testing.T) {
 	}
 }
 
+// TestEncodeSnapshotMarksAdapterDataErrors pins codex P2 v9 #904: when
+// an adapter encoder rejects the input tree's contents (e.g. a
+// malformed DynamoDB _schema.json), EncodeSnapshot must surface the
+// failure as ErrEncodeAdapterData so the CLI can route it to exit-2
+// (data-correctness) rather than exit-1 (operator/flag error).
+// Crucially, errors.Mark preserves the original sentinel chain, so a
+// caller that errors.Is on the per-adapter sentinel
+// (ErrDDBEncodeInvalidSchema here) still gets a match — the marking
+// is additive.
+func TestEncodeSnapshotMarksAdapterDataErrors(t *testing.T) {
+	t.Parallel()
+	in := t.TempDir()
+	// Empty table_name triggers ErrDDBEncodeInvalidSchema inside the
+	// DynamoDB encoder (encode_dynamodb.go:120).
+	writeDDBSchema(t, in, "tbl",
+		[]byte(`{"format_version":1,"table_name":"","primary_key":{"hash_key":{"name":"id","type":"S"}}}`))
+	var buf bytes.Buffer
+	_, err := EncodeSnapshot(EncodeOptions{
+		InputRoot:    in,
+		Adapters:     AdapterSet{DynamoDB: true},
+		LastCommitTS: 1,
+	}, &buf)
+	if err == nil {
+		t.Fatalf("EncodeSnapshot with malformed schema succeeded; want error")
+	}
+	if !errors.Is(err, ErrEncodeAdapterData) {
+		t.Errorf("err = %v, want errors.Is ErrEncodeAdapterData", err)
+	}
+	// Inner sentinel must still be reachable so existing per-adapter
+	// errors.Is callers are unaffected by the additional mark.
+	if !errors.Is(err, ErrDDBEncodeInvalidSchema) {
+		t.Errorf("err = %v, want errors.Is ErrDDBEncodeInvalidSchema (mark must preserve inner chain)", err)
+	}
+}
+
 // TestEncodeInfoSidecarPath pins the path-derivation rule for the
 // sidecar (gemini medium v2 #896): one .fsm path produces one distinct
 // sidecar path; two .fsm files in the same dir produce two distinct