backup: M4-2b reject encoded reserved-subtree targets (codex P2 round 5 #928)

walkObjectSubdir skips top-level '_orphans/' and
'_incomplete_uploads/' when they contain no sidecars (the dump's
own payload). A KEYMAP entry whose Encoded names a file under
those subtrees (e.g. '_orphans/foo.bin' or
'_incomplete_uploads/records.jsonl') passes the IsRegular check in
verifyKeymapTargetsExist - the dump-control payload genuinely
exists - but the walk never consumes it, so Encode finishes while
silently dropping the intended object.

The companion gate for the decoded original key was already in
validateKeymapReservedRoot; this commit mirrors the same restriction
on the encoded side via validateKeymapEncodedPathWalkerSkipped.

Function structure: validateKeymapEncodedPath now delegates the
walker-skip checks (sidecar suffix, top-level control files,
reserved-subtree roots) to a helper to keep cyclop under 10.

Caller audit: validateKeymapEncodedPath is invoked once from
validateKeymapRecord. No call-site changes.

Regression: TestValidateKeymapEncodedPath_ReservedSubtree with 6
sub-cases - top-level + nested _orphans / _incomplete_uploads
reject; _orphansFoo (longer name, NOT reserved) and prefix/_orphans
(nested, not top-level) accept.

Author: bootjp

internal/backup/encode_s3_collision.go

@@ -219,8 +219,17 @@ func validateKeymapEncodedPath(encoded string) error {
 				"encoded path %q contains invalid segment %q", encoded, seg)
 		}
 	}
-	last := segs[len(segs)-1]
-	if strings.HasSuffix(last, S3MetaSuffixReserved) {
+	return validateKeymapEncodedPathWalkerSkipped(encoded, segs)
+}
+
+// validateKeymapEncodedPathWalkerSkipped rejects encoded paths the
+// object walk would silently skip — sidecar suffixes at any depth,
+// top-level "_bucket.json" / "KEYMAP.jsonl" control files, and any
+// path rooted in a reserved dump subtree (_orphans /
+// _incomplete_uploads). Split out of validateKeymapEncodedPath so
+// the parent stays under cyclop. Codex P2 #928 round 4 + round 5.
+func validateKeymapEncodedPathWalkerSkipped(encoded string, segs []string) error {
+	if strings.HasSuffix(segs[len(segs)-1], S3MetaSuffixReserved) {
 		return errors.Wrapf(ErrInvalidKeymapRecord,
 			"encoded path %q ends in reserved sidecar suffix %q (walker would skip)",
 			encoded, S3MetaSuffixReserved)
@@ -233,6 +242,19 @@ func validateKeymapEncodedPath(encoded string) error {
 		return errors.Wrapf(ErrInvalidKeymapRecord,
 			"encoded path %q names a top-level control file the walker skips", encoded)
 	}
+	// Reserved-subtree first-segment guard. walkObjectSubdir skips
+	// top-level "_orphans/" and "_incomplete_uploads/" when they
+	// hold no sidecars (the dump's own payload). A KEYMAP entry
+	// whose Encoded is under those subtrees passes the IsRegular
+	// check on the existing dump-control payload (e.g.
+	// "_orphans/foo.bin" or "_incomplete_uploads/records.jsonl") but
+	// the walk never consumes it. The companion gate for the
+	// decoded original key lives in validateKeymapReservedRoot;
+	// this mirror catches the encoded side. Codex P2 #928 round 5.
+	if _, reserved := keymapReservedRoots[segs[0]]; reserved {
+		return errors.Wrapf(ErrInvalidKeymapRecord,
+			"encoded path %q targets reserved dump subtree %q (walker would skip)", encoded, segs[0])
+	}
 	return nil
 }
 

internal/backup/encode_s3_collision_test.go

@@ -281,6 +281,51 @@ func TestValidateKeymapEncodedPath_Backslash(t *testing.T) {
 	}
 }
 
+// TestValidateKeymapEncodedPath_ReservedSubtree pins codex P2 #928
+// round 5. walkObjectSubdir skips top-level "_orphans/" and
+// "_incomplete_uploads/" when they hold no sidecars (the dump's
+// own payload). A KEYMAP entry pointing into those subtrees passes
+// the IsRegular existence check but the walk never consumes it -
+// the rename is silently dropped.
+func TestValidateKeymapEncodedPath_ReservedSubtree(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name    string
+		encoded string
+		wantErr bool
+	}{
+		{"_orphans top-level payload", "_orphans/foo.bin", true},
+		{"_orphans nested", "_orphans/gen-1/x.bin", true},
+		{"_incomplete_uploads top-level", "_incomplete_uploads/records.jsonl", true},
+		{"_incomplete_uploads nested", "_incomplete_uploads/sub/x", true},
+		// _orphansFoo / nested _orphans are NOT reserved — only the
+		// exact top-level segment matches.
+		{"_orphansFoo (not reserved)", "_orphansFoo/x" + S3LeafDataSuffix, false},
+		{"nested _orphans (not top-level)", "prefix/_orphans/x" + S3LeafDataSuffix, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+			rec := KeymapRecord{
+				Encoded:     c.encoded,
+				OriginalB64: base64.RawURLEncoding.EncodeToString([]byte("original/key")),
+				Kind:        KindSHAFallback,
+			}
+			err := validateKeymapRecord(rec)
+			if c.wantErr {
+				if !errors.Is(err, ErrInvalidKeymapRecord) {
+					t.Fatalf("err = %v, want ErrInvalidKeymapRecord", err)
+				}
+				if !strings.Contains(err.Error(), "reserved dump subtree") {
+					t.Fatalf("err = %v, want reserved-dump-subtree message", err)
+				}
+			} else if err != nil {
+				t.Fatalf("unexpected err = %v", err)
+			}
+		})
+	}
+}
+
 // TestValidateKeymapEncodedPath_WalkerSkipped pins codex P2 #928
 // round 4 (walker-skipped reserved files): a corrupt KEYMAP entry
 // whose Encoded names a top-level "_bucket.json" / "KEYMAP.jsonl"