feat(kms): orchestrate Vault restore ordering, verification, and mismatch detection

Restoring a Vault-backed deployment is an operator action for the trust
root and a RustFS action for everything else. This adds the orchestration
around that split.

Ordering is structural, not documented: VaultRestoreSequence refuses any
stage that is not the next one, so material and metadata can never be
published before the Transit/HSM trust root is verified back.

Every way the recovered Vault can disagree with the bundle is a distinct
typed mismatch: a missing Transit key, a min_decryption_version raised
above what the bundle still needs, a Transit version history restored
below the snapshot point, a rolled-back KV generation, and cluster,
namespace, or mount drift. A dry-run reports them all and issues reads
only; an actual restore refuses on the first one, before any KV path is
probed.

Writes are create-only check-and-set throughout, so version regression,
generation rollback, and reviving deleted state are impossible rather
than merely rejected, and a lost race stops the restore instead of
overwriting. A reserved KV record is the single commit point: published
before the first write and removed after the last, it names exactly the
records this restore owns, so re-running the same bundle rolls forward
idempotently and abort takes back precisely what was written — never a
record that pre-existed. Every interruption converges to the complete old
or the complete new state.

Tests drive the whole surface offline through the scripted Vault
responder, including the zero-write contract asserted at the wire; the
live-Vault drill is ignored but kept compiling.

Refs rustfs/backlog#1572 (part of rustfs/backlog#1562)

crates/kms/src/backup/mod.rs

@@ -17,9 +17,11 @@
 //! The contract side defines the versioned backup manifest, the per-backend
 //! responsibility matrix, typed failure modes, and the restore dry-run
 //! report. [`local_export`] implements the producer side and
-//! [`local_restore`] the consumer side for the Local backend as
-//! crate-internal APIs; the admin API builds on these pieces in follow-up
-//! changes.
+//! [`local_restore`] the consumer side for the Local backend;
+//! [`vault_restore`] orchestrates the consumer side for the Vault backends,
+//! whose cryptographic root is restored by Vault's own disaster-recovery
+//! flow. All are crate-internal APIs; the admin API builds on these pieces in
+//! follow-up changes.
 //!
 //! # Bundle model
 //!
@@ -54,6 +56,7 @@ mod error;
 pub mod local_export;
 pub mod local_restore;
 mod manifest;
+pub mod vault_restore;
 
 pub use capability::{AtRestProtection, BackupBackendKind, BackupResponsibility};
 pub use dry_run::{
@@ -62,7 +65,7 @@ pub use dry_run::{
 pub use error::BackupError;
 pub use local_export::{
     BackupKek, LOCAL_BUNDLE_MANIFEST_FILE, LocalBackupExportRequest, decrypt_bundle_artifact, export_local_backup,
-    read_local_bundle_manifest,
+    read_bundle_manifest, read_local_bundle_manifest,
 };
 pub use local_restore::{
     LocalRestoreReport, LocalRestoreRequest, RestoreConflictPolicy, abort_local_restore, dry_run_local_restore,
@@ -70,5 +73,10 @@ pub use local_restore::{
 };
 pub use manifest::{
     AeadAlgorithm, ArtifactDescriptor, ArtifactKind, BackupKekDescriptor, BackupManifest, CompletenessState, ContentDigest,
-    DigestAlgorithm, LocalKdfDescriptor, LocalKeyDerivation, ReservedSlot,
+    DigestAlgorithm, LocalKdfDescriptor, LocalKeyDerivation, ReservedSlot, VaultExternalReferences, VaultKvRecordReference,
+    VaultTransitReference,
+};
+pub use vault_restore::{
+    VaultRestoreClient, VaultRestoreMismatch, VaultRestoreReport, VaultRestoreRequest, VaultRestoreSequence, VaultRestoreStage,
+    VaultRestoreTarget, abort_vault_restore, dry_run_vault_restore, restore_vault_backup,
 };