[perfectra1n]

Summary

Two features that close the policy lifecycle gap described in #210: deleting a policy now cleans up its Snapshot CRs (keeping the kopia data), and recreating the policy adopts that history back so retention resumes governing it.

1. SnapshotPolicy deletion cascade

Deleting a SnapshotPolicy now removes its config-labeled Snapshot CRs via a new policy-cleanup finalizer:

• Default spec.deletion.onPolicyDelete: Retain — the CRs are removed, every kopia snapshot survives (rediscoverable on the next catalog scan, adoptable on recreation). The cascade stamps pruned-by: policy-cascade, so children release quietly with zero repository contact.
• Opt-in Delete — each CR's own deletionPolicy applies, issued as external deletions so the mass-deletion breaker (feat: mass-deletion protection (cascade guard, per-repo breaker, batched deletes) #265) gates bulk waves behind the allow-mass-deletion ack. Deliberately unstamped: a policy delete with Delete is exactly the kro-incident shape the breaker exists for.
• Retain-wins-ties for simultaneous schedule+policy deletion (GitOps prune); a terminating policy can no longer be fired against by its schedule (skip+retry); breaker-held children never wedge policy removal.

2. Auto-adoption of discovered snapshots (fixes #210)

Discovered snapshots whose exact resolved identity (structured username/hostname/sourcePath comparison) matches a live SnapshotPolicy are adopted automatically: the row is recreated in the policy's namespace as origin: adopted, phase: Succeeded, config-labeled — indistinguishable from produced snapshots to retention, deletion, batching, catalog dedup, and the breaker. GFS retention then governs and prunes the old history per spec.retention, ending the "pre-DR history occupies storage forever" failure mode.

• On by default; opt out per policy (spec.adoption: Ignore) or per repository (spec.catalog.adoption: Ignore).
• Foreign-cluster snapshots in shared repositories are never adopted — three independent guards (structured identity equality with cluster-scoped hostnames, foreign rows are never materialized as discovered under Ignore, and a hard HostClass::ForeignCluster refusal).
• The delete→recreate flow converges hands-off: the policy reconciler stamps a catalog-scan-requested-at token on the repository; scans retire it by token equality (status.catalog.scanRequestHonored), and launch attempts are rate-limited (scanRequestAttemptAt) so a Ready-but-unreachable repo never churns bootstrap Jobs.
• Loudly surfaced, not gated: SnapshotsAdopted / AdoptionScanRequested / SnapshotRetainedOnPolicyDelete events, status.adoption summary on the policy, and kopiur_snapshots_adopted + cascade counters.

Hardening that rode along

• Webhook now resolves Snapshot origin status-first: flipping a discovered row's origin label can no longer unlock deletionPolicy: Delete at admission.
• New policy-referencing manual Snapshots get the config label at admission, making them visible to retention and the cascade. Deliberately no retro-backfill: labeling pre-existing raw-applied Snapshots would silently make previously-immortal history prunable.
• The SnapshotRetainedOnScheduleDelete event no longer promises rediscovery "within the catalog refresh interval" (misleading with periodic refresh off).

BREAKING CHANGE

Deleting a SnapshotPolicy now removes its config-labeled Snapshot CRs by default (onPolicyDelete: Retain — kopia snapshots are kept and rediscoverable/adoptable). Previously the CRs were left dangling.

Test coverage

• Hermetic: new unit/serde coverage across api/controller/webhook — cascade planner matrix (terminating exclusion, origin filter, release condition), the 9-cell PrunedBy × DeletionPolicy prune table, scan-request predicate matrix (equality retirement, launch backoff, no-token regression pins), full adoption matrix (identity near-misses, foreign refusal, 409-heal, knob precedence), webhook origin-flip denials.
• e2e (6 new scenarios): the Discovered snapshots are permanently exempt from all pruning #210 acceptance test (produce → delete schedule+policy → CRs gone, kopia intact → recreate with keepLatest: 1 → scan request → discovered → adopted → retention prunes kopia-side to exactly 1, with a non-matching-identity negative control), ClusterRepository cross-namespace adoption, adoption opt-out, cascade default-Retain (incl. webhook-labeled manual Snapshot), breaker-gated opt-in Delete (hold → ack → drain), and the schedule+policy simultaneous-delete race.
• Every milestone landed with cargo test --workspace, clippy -D warnings, gen-check, and the cognitive-complexity ratchet (29/29, unchanged) green. Each milestone was independently review-gated; one Critical (object-store scan-request honoring) was caught in review and fixed with a regression test (734b2f8).

Local fresh-kind validation of the new e2e binaries is running; CI's e2e suite is the authoritative gate for this PR.

Closes #210

[greptile-apps]

Greptile Summary

This PR adds SnapshotPolicy lifecycle cleanup and automatic adoption of matching discovered snapshots. The main changes are:

• A policy cleanup finalizer that removes config-labeled Snapshot CRs on SnapshotPolicy deletion.
• onPolicyDelete behavior for retaining kopia data by default or opting into Snapshot deletion.
• Automatic adoption of discovered snapshots whose resolved identity matches a live policy.
• On-demand catalog scan requests for delete-and-recreate adoption flows.
• API, webhook, CRD, metrics, events, docs, examples, and tests for the new lifecycle paths.

Confidence Score: 5/5

The changes appear safe to merge.

The cascade, adoption, webhook, API, and scan-request paths did not leave actionable issues.

No files require special attention.

T-Rex Logs

What T-Rex did

• T-Rex attempted to capture the cargo test run using the default shell, but the capture could not proceed because the shell did not support set -o pipefail.
• T-Rex re-ran the cargo test command under bash -lc to obtain a valid validation artifact.
• The cargo test run completed with all test groups passing, including final doctest summaries for kopiur_api, kopiur_controller, kopiur_mover, and kopiur_webhook.
• The validation artifacts together provide the exact command, working directory, timestamps, full cargo output, and EXIT_CODE: 0 for review.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
crates/controller/src/adoption.rs	Adds adoption candidate extraction, identity matching, foreign-cluster refusal, bounded batches, and adopted Snapshot construction.
crates/controller/src/snapshot_policy.rs	Adds policy deletion cascade handling and adoption orchestration after retention.
crates/controller/src/snapshot/plan.rs	Extends Snapshot deletion planning for policy-cascade prunes and namespace teardown precedence.
crates/controller/src/snapshot/mod.rs	Adds adopted-row steady-state handling with provenance gating.
crates/controller/src/catalog.rs	Adds on-demand catalog scan predicates and scan-request retirement behavior.
crates/controller/src/repository.rs	Threads catalog scan request honoring and attempt status through Repository reconciliation.
crates/controller/src/cluster_repository.rs	Mirrors scan request honoring and attempt handling for ClusterRepository reconciliation.
crates/controller/src/io/repo.rs	Adds a helper for adoption-driven catalog scan requests and carries catalog adoption settings in resolved repositories.
crates/webhook/src/handlers.rs	Updates Snapshot admission to resolve origin status-first and stamp policy labels for managed Snapshot origins.
crates/api/src/snapshot_policy.rs	Adds policy deletion and adoption API fields plus adoption status summary types.
crates/api/src/common/cache.rs	Adds SnapshotAdoption settings and effective adoption precedence.
crates/api/src/validate/snapshot.rs	Extends validation so adopted snapshots cannot set schedule-deletion behavior.

_{Reviews (4): Last reviewed commit: "fix(controller): collision-free adopted ..." | Re-trigger Greptile}