Merge remote-tracking branch 'origin/main' into overtrue/docs-1923-free-version-disposition

Tier free versions (xl.meta cleanup records for deleted transitioned
versions) are not migrated as free versions during decommission: the
exact inventory keeps them inline in versions and the migration loop
routes them through the generic delete-marker path, dropping the flag
and remote-tier identity. Reference audit across GET, heal, ILM,
transition, replication, and restore found no cluster-local consumer
that resolves a free version after decommission; on user-facing delete
paths the remote-delete obligation is also carried by a committed
tier-journal entry, leaving only journal-less records (transition
state unknown) exposed to remote orphaning.

- count and log skipped free versions per decommission entry with
  disposition reason tier_free_version_not_migrated instead of
  omitting them silently
- document free-version lifecycle, non-migration invariant, allowed
  physical-delete timing, and the reference-audit result in
  docs/architecture/decommission-compatibility.md
- state the invariant in doc comments at the filemeta free-version
  sites
- guard the accounting with
  decommission_free_version_accounting_reports_skipped_records

Closes rustfs/backlog#1923

Cargo.lock

@@ -9587,7 +9587,6 @@ dependencies = [
  "serde",
  "serde_json",
  "serial_test",
- "sha2 0.11.0",
  "temp-env",
  "tempfile",
  "thiserror 2.0.20",

crates/data-usage/src/data_usage.rs

@@ -585,12 +585,9 @@ impl VersionsHistogram {
     }
 }
 
-/// Replication statistics for a single target.
-///
-/// Renamed from `ReplicationStats`; serde field names are preserved
-/// byte-identically to maintain wire compatibility with existing snapshots.
-#[derive(Debug, Default, Clone, Serialize, Deserialize, PartialEq, Eq)]
-pub struct ReplicationTargetUsage {
+/// Replication statistics for a single target
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct ReplicationStats {
     pub pending_size: u64,
     pub replicated_size: u64,
     pub failed_size: u64,
@@ -603,7 +600,7 @@ pub struct ReplicationTargetUsage {
     pub replicated_count: u64,
 }
 
-impl ReplicationTargetUsage {
+impl ReplicationStats {
     pub fn is_empty(&self) -> bool {
         let Self {
             pending_size,
@@ -639,7 +636,7 @@ impl ReplicationTargetUsage {
 /// Replication statistics for all targets
 #[derive(Debug, Default, Clone, Serialize, Deserialize)]
 pub struct ReplicationAllStats {
-    pub targets: HashMap<String, ReplicationTargetUsage>,
+    pub targets: HashMap<String, ReplicationStats>,
     pub replica_size: u64,
     pub replica_count: u64,
 }
@@ -652,7 +649,7 @@ impl ReplicationAllStats {
             targets,
         } = self;
 
-        *replica_size == 0 && *replica_count == 0 && targets.values().all(ReplicationTargetUsage::is_empty)
+        *replica_size == 0 && *replica_count == 0 && targets.values().all(ReplicationStats::is_empty)
     }
 
     #[deprecated(note = "use is_empty instead")]
@@ -2469,7 +2466,7 @@ mod tests {
 
     #[test]
     fn replication_stats_empty_checks_every_field() {
-        type SetField = fn(&mut ReplicationTargetUsage);
+        type SetField = fn(&mut ReplicationStats);
 
         let cases: [(&str, SetField); 10] = [
             ("pending_size", |stats| stats.pending_size = 1),
@@ -2484,9 +2481,9 @@ mod tests {
             ("replicated_count", |stats| stats.replicated_count = 1),
         ];
 
-        assert!(ReplicationTargetUsage::default().is_empty());
+        assert!(ReplicationStats::default().is_empty());
         for (field, set_nonzero) in cases {
-            let mut stats = ReplicationTargetUsage::default();
+            let mut stats = ReplicationStats::default();
             set_nonzero(&mut stats);
             assert!(!stats.is_empty(), "{field} must make replication stats non-empty");
         }
@@ -2517,17 +2514,17 @@ mod tests {
         }
 
         let empty_targets = ReplicationAllStats {
-            targets: HashMap::from([("arn:test:empty".to_string(), ReplicationTargetUsage::default())]),
+            targets: HashMap::from([("arn:test:empty".to_string(), ReplicationStats::default())]),
             ..Default::default()
         };
         assert!(empty_targets.is_empty(), "all-empty targets must keep aggregate stats empty");
 
         let stats = ReplicationAllStats {
             targets: HashMap::from([
-                ("arn:test:empty".to_string(), ReplicationTargetUsage::default()),
+                ("arn:test:empty".to_string(), ReplicationStats::default()),
                 (
                     "arn:test:non-empty".to_string(),
-                    ReplicationTargetUsage {
+                    ReplicationStats {
                         pending_count: 1,
                         ..Default::default()
                     },
@@ -2568,7 +2565,7 @@ mod tests {
                 replication_stats: Some(ReplicationAllStats {
                     targets: HashMap::from([(
                         "arn:test:pending".to_string(),
-                        ReplicationTargetUsage {
+                        ReplicationStats {
                             pending_count: 1,
                             ..Default::default()
                         },
@@ -2717,7 +2714,7 @@ mod tests {
                 targets: HashMap::from([
                     (
                         "arn:self-only".to_string(),
-                        ReplicationTargetUsage {
+                        ReplicationStats {
                             pending_size: 7,
                             pending_count: 1,
                             ..Default::default()
@@ -2725,7 +2722,7 @@ mod tests {
                     ),
                     (
                         "arn:shared".to_string(),
-                        ReplicationTargetUsage {
+                        ReplicationStats {
                             failed_size: 3,
                             failed_count: 1,
                             missed_threshold_size: 2,
@@ -2744,7 +2741,7 @@ mod tests {
                 targets: HashMap::from([
                     (
                         "arn:shared".to_string(),
-                        ReplicationTargetUsage {
+                        ReplicationStats {
                             failed_size: 5,
                             failed_count: 2,
                             after_threshold_size: 4,
@@ -2754,7 +2751,7 @@ mod tests {
                     ),
                     (
                         "arn:other-only".to_string(),
-                        ReplicationTargetUsage {
+                        ReplicationStats {
                             replicated_size: 11,
                             replicated_count: 3,
                             ..Default::default()
@@ -2996,9 +2993,7 @@ mod tests {
     fn replication_target_deserialization_preserves_large_historical_maps() {
         let mut stats = ReplicationAllStats::default();
         for index in 0..=1024 {
-            stats
-                .targets
-                .insert(format!("target-{index}"), ReplicationTargetUsage::default());
+            stats.targets.insert(format!("target-{index}"), ReplicationStats::default());
         }
         let encoded = rmp_serde::to_vec_named(&stats).expect("large replication target fixture should encode");
         let decoded = rmp_serde::from_slice::<ReplicationAllStats>(&encoded)
@@ -3007,47 +3002,6 @@ mod tests {
         assert_eq!(decoded.targets.len(), stats.targets.len());
     }
 
-    /// Round-trip test: encoding a [`ReplicationTargetUsage`] and decoding it back
-    /// must produce the exact same value.  This guards against accidental serde
-    /// field-name drift during the `ReplicationStats` -> `ReplicationTargetUsage`
-    /// rename.  Wire-level field names are the serialized Rust field identifiers,
-    /// which must remain byte-identical.
-    #[test]
-    fn replication_target_usage_rmp_round_trip() {
-        let original = ReplicationTargetUsage {
-            pending_size: 100,
-            replicated_size: 2_000,
-            failed_size: 50,
-            failed_count: 3,
-            pending_count: 7,
-            missed_threshold_size: 11,
-            after_threshold_size: 22,
-            missed_threshold_count: 1,
-            after_threshold_count: 2,
-            replicated_count: 99,
-        };
-
-        let buf = rmp_serde::to_vec_named(&original).expect("encode ReplicationTargetUsage to msgpack");
-        let decoded: ReplicationTargetUsage = rmp_serde::from_slice(&buf).expect("decode ReplicationTargetUsage from msgpack");
-        assert_eq!(original, decoded, "round-trip through rmp must preserve every field");
-
-        // Also verify that encoding as an unnamed sequence and then decoding
-        // with named fields produces the correct mapping (this catches reordering).
-        let named_buf = rmp_serde::to_vec_named(&original).expect("re-encode for field-name pinning");
-        // Spot-check that known field names appear in the named encoding.
-        let named_str = String::from_utf8_lossy(&named_buf);
-        assert!(named_str.contains("pending_size"), "field 'pending_size' must survive the rename");
-        assert!(named_str.contains("replicated_size"), "field 'replicated_size' must survive the rename");
-        assert!(
-            named_str.contains("missed_threshold_size"),
-            "field 'missed_threshold_size' must survive the rename"
-        );
-        assert!(
-            named_str.contains("after_threshold_count"),
-            "field 'after_threshold_count' must survive the rename"
-        );
-    }
-
     #[test]
     fn checked_merge_rejects_noncanonical_histograms_without_mutation() {
         let mut entry = DataUsageEntry {

crates/e2e_test/src/heal_erasure_disk_rebuild_test.rs

@@ -380,24 +380,10 @@ mod tests {
         cluster.start_node(1).await?;
 
         let status_url = format!("{}/rustfs/admin/v3/background-heal/status", cluster.nodes[0].url);
-        let mut recovered = serde_json::Value::Null;
-        for _ in 0..60 {
-            let status_body = signed_admin_post(&status_url, None, &cluster.access_key, &cluster.secret_key).await?;
-            assert!(
-                !status_body.contains("MissingContentLength"),
-                "background heal status should not fail without an explicit Content-Length: {status_body}"
-            );
-            recovered = serde_json::from_str(&status_body)
-                .map_err(|err| format!("background heal status is not JSON ({err}): {status_body}"))?;
-            if recovered["clusterStatusComplete"] == serde_json::Value::Bool(true) {
-                break;
-            }
-            sleep(Duration::from_secs(1)).await;
-        }
-        assert_eq!(
-            recovered["clusterStatusComplete"],
-            serde_json::Value::Bool(true),
-            "cluster heal status should recover before root heal starts: {recovered}"
+        let status_body = signed_admin_post(&status_url, None, &cluster.access_key, &cluster.secret_key).await?;
+        assert!(
+            !status_body.contains("MissingContentLength"),
+            "background heal status should not fail without an explicit Content-Length: {status_body}"
         );
 
         let heal_body = r#"{"recursive":true,"dryRun":false,"remove":false,"recreate":true,"scanMode":2,"updateParity":false,"nolock":false}"#;

crates/ecstore/src/config/storageclass.rs

@@ -248,13 +248,10 @@ impl Config {
         let shard_size = shard_size as usize;
         // Keep the historical two-data-shard object budget while preventing
         // wider EC layouts from multiplying the maximum inline object size.
-        // Use div_ceil to match the shard_file_size calculation (which also uses
-        // div_ceil), avoiding a 1-byte rounding discrepancy that prevents inline
-        // for objects right at the threshold.
         let inline_block = if self.initialized && self.inline_block_explicit {
             self.inline_block
         } else {
-            DEFAULT_INLINE_OBJECT_BUDGET.div_ceil(data_shards).min(DEFAULT_INLINE_BLOCK)
+            (DEFAULT_INLINE_OBJECT_BUDGET / data_shards).min(DEFAULT_INLINE_BLOCK)
         };
 
         if versioned {

crates/ecstore/src/core/pools.rs

@@ -1130,6 +1130,23 @@ fn should_cleanup_decommission_source_entry(decommissioned: usize, total_version
     decommissioned.saturating_add(expired) == total_versions
 }
 
+/// Disposition reason logged for tier free-version records that decommission
+/// skips instead of migrating.
+const DECOMMISSION_FREE_VERSION_SKIP_REASON: &str = "tier_free_version_not_migrated";
+
+/// Counts the tier free-version records present in a decommission entry
+/// inventory. The exact loader (`load_file_info_versions_exact`) keeps these
+/// records inline in `versions` instead of separating them into
+/// `free_versions`, and the migration loop then routes them through the
+/// generic delete-marker path: the free-version flag and its remote-tier
+/// identity are never carried to the target pool, and a lone record is skipped
+/// by the empty-delete-marker rule. Accounting for them here keeps the final
+/// sweep from silently omitting records whose free-version disposition was
+/// dropped (see docs/architecture/decommission-compatibility.md).
+fn decommission_free_versions_skipped(fivs: &FileInfoVersions) -> usize {
+    fivs.versions.iter().filter(|version| version.tier_free_version()).count()
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[allow(
     dead_code,
@@ -3097,6 +3114,22 @@ impl ECStore {
         fivs.versions
             .sort_by_key(|v| (v.mod_time.is_none(), std::cmp::Reverse(v.mod_time)));
 
+        let skipped_free_versions = decommission_free_versions_skipped(&fivs);
+        if skipped_free_versions > 0 {
+            debug!(
+                event = EVENT_DECOMMISSION_ENTRY,
+                component = LOG_COMPONENT_ECSTORE,
+                subsystem = LOG_SUBSYSTEM_POOLS,
+                pool_index = idx,
+                bucket = %bucket,
+                object = %entry.name,
+                skipped_free_versions,
+                reason = DECOMMISSION_FREE_VERSION_SKIP_REASON,
+                state = "free_versions_skipped",
+                "Decommission skipped free-version migration"
+            );
+        }
+
         let mut decommissioned: usize = 0;
         let mut expired: usize = 0;
         let mut cleanup_preflight_allowed_missing = Vec::new();
@@ -5458,11 +5491,12 @@ pub(crate) fn fallback_free_capacity_dedup(disks: &[rustfs_madmin::Disk]) -> usi
 #[cfg(test)]
 mod pools_tests {
     use super::{
-        DECOMMISSION_PROGRESS_SAVE_INTERVAL, DECOMMISSION_PROGRESS_SAVE_ITEM_THRESHOLD, DECOMMISSION_PROGRESS_SAVE_RETRY_BACKOFF,
-        DecomBucketInfo, DecommissionStartPoolState, DecommissionTerminalState, ListCallback, PoolDecommissionInfo, PoolMeta,
-        PoolSpaceInfo, PoolStatus, apply_decommission_status_space_info, bind_decommission_cancelers,
-        bind_missing_decommission_cancelers, cancel_decommission_canceler, classify_decommission_terminal_state,
-        count_decommission_item, decommission_cancel_signal_result, decommission_item_size, decommission_meta_bucket_options,
+        DECOMMISSION_FREE_VERSION_SKIP_REASON, DECOMMISSION_PROGRESS_SAVE_INTERVAL, DECOMMISSION_PROGRESS_SAVE_ITEM_THRESHOLD,
+        DECOMMISSION_PROGRESS_SAVE_RETRY_BACKOFF, DecomBucketInfo, DecommissionStartPoolState, DecommissionTerminalState,
+        ListCallback, PoolDecommissionInfo, PoolMeta, PoolSpaceInfo, PoolStatus, apply_decommission_status_space_info,
+        bind_decommission_cancelers, bind_missing_decommission_cancelers, cancel_decommission_canceler,
+        classify_decommission_terminal_state, count_decommission_item, decommission_cancel_signal_result,
+        decommission_free_versions_skipped, decommission_item_size, decommission_meta_bucket_options,
         decommission_start_pool_state, dedup_indices, default_decommission_bucket_concurrency,
         ensure_decommission_cancel_allowed, ensure_decommission_clear_allowed, ensure_decommission_listing_disks_available,
         ensure_decommission_not_rebalancing, ensure_decommission_start_allowed, ensure_decommission_start_keeps_active_pool,
@@ -6762,6 +6796,27 @@ mod pools_tests {
         assert!(!should_cleanup_decommission_source_entry(2, 2, 1));
     }
 
+    #[test]
+    fn decommission_free_version_accounting_reports_skipped_records() {
+        let mut fivs = FileInfoVersions::default();
+        assert_eq!(decommission_free_versions_skipped(&fivs), 0);
+
+        fivs.versions.push(FileInfo {
+            name: "object.txt".to_string(),
+            ..Default::default()
+        });
+        let mut free_one = FileInfo::default();
+        free_one.set_tier_free_version();
+        fivs.versions.push(free_one);
+        let mut free_two = FileInfo::default();
+        free_two.set_tier_free_version();
+        free_two.transition_tier = "WARM".to_string();
+        fivs.versions.push(free_two);
+
+        assert_eq!(decommission_free_versions_skipped(&fivs), 2);
+        assert_eq!(DECOMMISSION_FREE_VERSION_SKIP_REASON, "tier_free_version_not_migrated");
+    }
+
     #[test]
     fn test_pool_meta_update_after_rejects_out_of_range_index() {
         let mut meta = PoolMeta::default();

crates/ecstore/src/disk/local.rs

@@ -7949,15 +7949,10 @@ impl DiskAPI for LocalDisk {
             use std::io::Write as _;
 
             let file_path = self.io_get_object_path(volume, path)?;
+            let lock_path = file_path.with_extension("rustfs-cas.lock");
             let path = path.to_string();
             let sync_metadata = effective_durability(volume).syncs_commit_metadata();
             return Ok(tokio::task::spawn_blocking(move || {
-                // A persistent directory lock bounds metadata growth. Removing
-                // per-target lock files can split flock ownership across inodes.
-                let lock_path = file_path
-                    .parent()
-                    .ok_or_else(|| std::io::Error::new(ErrorKind::InvalidInput, "conditional file has no parent"))?
-                    .join(".rustfs-cas.lock");
                 let lock = std::fs::OpenOptions::new()
                     .create(true)
                     .truncate(false)
@@ -21846,10 +21841,7 @@ mod test {
         let marker_path = disk
             .get_object_path(RUSTFS_META_BUCKET, HEALING_MARKER_PATH)
             .expect("marker path should resolve");
-        let lock_path = marker_path
-            .parent()
-            .expect("marker path should have a parent")
-            .join(".rustfs-cas.lock");
+        let lock_path = marker_path.with_extension("rustfs-cas.lock");
         let lock = std::fs::OpenOptions::new()
             .create(true)
             .truncate(false)

crates/ecstore/src/set_disk/ops/object.rs

@@ -2123,27 +2123,14 @@ impl SetDisks {
             let erasure = Arc::new(erasure_from_file_info(&fi, false)?);
 
             let put_object_size = known_put_object_storage_size(data.size());
-            let shard_file_size_raw = erasure.shard_file_size(put_object_size);
             let is_inline_buffer =
-                storage_class_config.should_inline(shard_file_size_raw, erasure.data_shards, opts.versioned);
+                storage_class_config.should_inline(erasure.shard_file_size(put_object_size), erasure.data_shards, opts.versioned);
 
             let collect_stage_timing = rustfs_io_metrics::put_stage_metrics_enabled() || issue3031_diag_enabled();
-            let shard_file_size = shard_file_size_raw;
+            let shard_file_size = erasure.shard_file_size(put_object_size);
             let shard_size = erasure.shard_size();
             let write_path = classify_put_write_path(is_inline_buffer, put_object_size, fi.erasure.block_size);
             let direct_inline_commit = matches!(write_path, SmallWritePath::Inline);
-            {
-                use std::io::Write;
-                let msg = format!(
-                    "INLINE_DEBUG: bucket={} obj={} size={} shard_fs={} ds={} bs={} inline={} direct={} path={} iblock={} ver={}\n",
-                    bucket, object, put_object_size, shard_file_size_raw, erasure.data_shards, fi.erasure.block_size,
-                    is_inline_buffer, direct_inline_commit, write_path.metric_label(), storage_class_config.inline_block(), opts.versioned
-                );
-                if let Ok(mut f) = std::fs::OpenOptions::new().create(true).append(true).open("/tmp/rustfs_inline_debug.log") {
-                    let _ = f.write_all(msg.as_bytes());
-                }
-                let _ = std::io::stderr().write_all(msg.as_bytes());
-            }
             rustfs_io_metrics::record_put_object_path(write_path.metric_label());
             let writer_setup_stage_start = collect_stage_timing.then(Instant::now);
             let (mut writers, errors) = if direct_inline_commit {

crates/filemeta/src/filemeta.rs

@@ -90,6 +90,22 @@ fn legacy_data_key_for_version(version_id: Option<Uuid>) -> Option<String> {
 pub const TRANSITION_COMPLETE: &str = "complete";
 pub const TRANSITION_PENDING: &str = "pending";
 
+/// xl.meta key marking a tier free-version record.
+///
+/// A free version is a delete-marker-shaped cleanup hint appended by
+/// [`MetaObject::delete_version`] when a version whose remote transition
+/// completed is removed from xl.meta; it carries the remote tier identity for
+/// an idempotent remote delete and is never a user-visible version
+/// (`num_versions` excludes it). While the record exists it is consumed by the
+/// lifecycle free-version recovery scan and the usage scanner, which re-enqueue
+/// the pending remote delete, and by heal metadata walks. On S3 and lifecycle
+/// delete paths the same obligation is also carried by a committed tier-journal
+/// entry; deletes without such an entry (for example a removed version whose
+/// transition state decodes as unknown) rely on this record alone until the
+/// worker removes it after a successful remote delete. Decommission does not
+/// preserve these semantics: its exact inventory keeps the records inline in
+/// `versions` and the migration loop treats them as ordinary delete markers —
+/// see docs/architecture/decommission-compatibility.md.
 pub const FREE_VERSION: &str = "free-version";
 
 pub const TRANSITION_STATUS: &str = "transition-status";

crates/filemeta/src/filemeta/version.rs

@@ -2725,6 +2725,15 @@ impl MetaObject {
         self.meta_sys.retain(|k, _| !k.starts_with("X-Amz-Restore"));
     }
 
+    /// Builds the free-version cleanup record appended when a transitioned
+    /// version is removed from xl.meta. The record keeps the remote tier
+    /// identity so the lifecycle worker can issue the idempotent remote delete
+    /// and only then remove the record; until then the recovery scan and the
+    /// usage scanner keep re-enqueueing it. S3 and lifecycle deletes also
+    /// persist a committed tier-journal entry for the same remote delete, so a
+    /// record destroyed without its remote delete (as decommission does when it
+    /// treats these records as ordinary delete markers) strands only the
+    /// journal-less cases — see docs/architecture/decommission-compatibility.md.
     pub fn init_free_version(&self, fi: &FileInfo) -> Result<(FileMetaVersion, bool)> {
         if fi.skip_tier_free_version() {
             return Ok((FileMetaVersion::default(), false));

crates/heal/Cargo.toml

@@ -91,7 +91,6 @@ metrics = { workspace = true }
 base64 = { workspace = true }
 bytes = { workspace = true }
 crc-fast = { workspace = true }
-sha2 = { workspace = true }
 
 [dev-dependencies]
 serde_json = { workspace = true, features = ["raw_value"] }

crates/heal/src/heal/erasure_healer.rs

@@ -373,11 +373,6 @@ impl ErasureSetHealer {
         set_disk_id: &str,
         buckets: &[String],
     ) -> Result<(ResumeManager, CheckpointManager)> {
-        if self.replacement_task_id.is_none() && CheckpointManager::is_blocked(&self.disk, task_id).await {
-            return Err(Error::TaskExecutionFailed {
-                message: format!("Resume task {task_id} has a blocked checkpoint"),
-            });
-        }
         // check if resume state exists
         let has_resume_state = if self.replacement_task_id.is_some() {
             ResumeManager::has_replacement_intent(&self.disk, task_id).await

crates/heal/src/heal/resume.rs

@@ -51,7 +51,6 @@ const RESUME_STATE_FILE: &str = "ahm_resume_state.json";
 const REPLACEMENT_INTENT_FILE: &str = "ahm_replacement_intent.json";
 const RESUME_PROGRESS_FILE: &str = "ahm_progress.json";
 pub(super) const RESUME_CHECKPOINT_FILE: &str = "ahm_checkpoint.json";
-pub(super) const RESUME_CHECKPOINT_BLOCKED_FILE: &str = "ahm_checkpoint.blocked";
 const REPLACEMENT_COMPLETION_PROOF_FILE: &str = "ahm_replacement_completion_proof.json";
 const REPLACEMENT_RECOVERY_DIR: &str = "ahm-replacement";
 const REPLACEMENT_INTENT_SEAL_FILE: &str = "ahm_replacement_intent_seal";

crates/heal/src/heal/resume/checkpoint.rs

@@ -13,31 +13,26 @@
 // limitations under the License.
 
 use crate::{Error, Result};
-use base64::Engine as _;
 use serde::{Deserialize, Serialize};
-use sha2::{Digest, Sha256};
 use std::collections::HashSet;
 use std::path::Path;
 use std::sync::{Arc, Mutex};
 use std::time::{SystemTime, UNIX_EPOCH};
-use tokio::sync::{Mutex as AsyncMutex, RwLock};
+use tokio::sync::RwLock;
 use tracing::{debug, warn};
 
-use super::super::storage_api::owner::{EcstoreConditionalFileUpdate, EcstoreDiskAPI, EcstoreDiskBytes};
-use super::super::{BUCKET_META_PREFIX, DiskStore, HealDiskExt, RUSTFS_META_BUCKET};
+use super::super::{BUCKET_META_PREFIX, DiskStore, HealDiskExt as _, RUSTFS_META_BUCKET};
 use super::{
-    LOG_COMPONENT_HEAL, LOG_SUBSYSTEM_RESUME, PersistThrottle, RESUME_CHECKPOINT_BLOCKED_FILE, RESUME_CHECKPOINT_FILE,
-    delete_resume_file, path_to_str, validate_resume_task_id,
+    LOG_COMPONENT_HEAL, LOG_SUBSYSTEM_RESUME, PersistThrottle, RESUME_CHECKPOINT_FILE, delete_resume_file, path_to_str,
+    validate_resume_task_id,
 };
 
 const EVENT_HEAL_CHECKPOINT_STATE: &str = "heal_checkpoint_state";
-const RESUME_CHECKPOINT_DIGEST_FILE: &str = "ahm_checkpoint.sha256";
-const CHECKPOINT_PER_VERSION_SCHEMA: u32 = 5;
 
 /// Current on-disk schema version for `ResumeCheckpoint`. Same rationale as
 /// `CURRENT_RESUME_SCHEMA`: pre-per-version dedup identities are not comparable
 /// to the new `compose_key` identities, so a stale checkpoint is discarded.
-pub(super) const CURRENT_CHECKPOINT_SCHEMA: u32 = 6;
+pub(super) const CURRENT_CHECKPOINT_SCHEMA: u32 = 5;
 
 /// resume checkpoint
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -62,11 +57,6 @@ pub struct ResumeCheckpoint {
     pub failed_objects: HashSet<String>,
     /// skipped objects
     pub skipped_objects: HashSet<String>,
-    /// Integrity digest over the checkpoint with this field set to `None`.
-    /// Keeping it in the checkpoint makes the payload and its authentication
-    /// record one CAS generation instead of two independently-written files.
-    #[serde(default)]
-    pub integrity_digest: Option<String>,
 }
 
 impl ResumeCheckpoint {
@@ -80,7 +70,6 @@ impl ResumeCheckpoint {
             processed_objects: HashSet::new(),
             failed_objects: HashSet::new(),
             skipped_objects: HashSet::new(),
-            integrity_digest: None,
         }
     }
 
@@ -127,111 +116,17 @@ pub struct CheckpointManager {
     disk: DiskStore,
     checkpoint: Arc<RwLock<ResumeCheckpoint>>,
     throttle: Mutex<PersistThrottle>,
-    save_lock: AsyncMutex<()>,
-    last_saved: Mutex<Option<EcstoreDiskBytes>>,
 }
 
 impl CheckpointManager {
-    fn blocked_path(task_id: &str) -> std::path::PathBuf {
-        Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_BLOCKED_FILE}"))
-    }
-
-    /// Return whether a checkpoint was permanently isolated after a malformed
-    /// or unsupported snapshot was observed.
-    pub(crate) async fn is_blocked(disk: &DiskStore, task_id: &str) -> bool {
-        if validate_resume_task_id(task_id).is_err() {
-            return false;
-        }
-        let blocked_path = Self::blocked_path(task_id);
-        let Ok(path) = path_to_str(&blocked_path) else {
-            return false;
-        };
-        match HealDiskExt::read_all(disk.as_ref(), RUSTFS_META_BUCKET, path).await {
-            Ok(_) => true,
-            Err(crate::heal::DiskError::FileNotFound) => false,
-            Err(_) => true,
-        }
-    }
-
-    /// Validate the checkpoint while enumerating resumable state. This reads
-    /// the checkpoint once and also isolates malformed or unsupported data.
-    pub(crate) async fn is_resumable(disk: &DiskStore, task_id: &str) -> Result<bool> {
-        validate_resume_task_id(task_id)?;
-        if Self::is_blocked(disk, task_id).await {
-            return Err(Error::InvalidCheckpoint(format!("Resume task {task_id} has a blocked checkpoint")));
-        }
-        let file_path = Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_FILE}"));
-        let Ok(path) = path_to_str(&file_path) else {
-            return Err(Error::InvalidCheckpoint("Resume checkpoint path is not valid UTF-8".to_string()));
-        };
-        match HealDiskExt::read_all(disk.as_ref(), RUSTFS_META_BUCKET, path).await {
-            Ok(bytes) if bytes.is_empty() => Ok(true),
-            Ok(bytes) => Self::load_from_data(disk.clone(), task_id, bytes.to_vec())
-                .await
-                .map(|_| true),
-            Err(crate::heal::DiskError::FileNotFound) => Ok(true),
-            Err(error) => Err(error.into()),
-        }
-    }
-
-    async fn block_invalid_snapshot(disk: &DiskStore, task_id: &str) {
-        // This marker is intentionally version-agnostic: an unsupported reader
-        // must stop selector retries until an operator cleans up the snapshot.
-        let blocked_path = Self::blocked_path(task_id);
-        let Ok(path) = path_to_str(&blocked_path) else {
-            return;
-        };
-        let result = EcstoreDiskAPI::compare_and_update_file(
-            disk.as_ref(),
-            RUSTFS_META_BUCKET,
-            path,
-            None,
-            Some(EcstoreDiskBytes::from_static(b"blocked")),
-        )
-        .await;
-        match result {
-            Ok(EcstoreConditionalFileUpdate::Updated | EcstoreConditionalFileUpdate::Mismatch) => {}
-            Ok(EcstoreConditionalFileUpdate::Missing) => warn!(
-                target: "rustfs::heal::resume",
-                event = EVENT_HEAL_CHECKPOINT_STATE,
-                component = LOG_COMPONENT_HEAL,
-                subsystem = LOG_SUBSYSTEM_RESUME,
-                task_id,
-                state = "blocked_marker_write_failed",
-                error = "marker target disappeared",
-                "Heal checkpoint could not persist its blocked marker"
-            ),
-            Err(error) => warn!(
-                target: "rustfs::heal::resume",
-                event = EVENT_HEAL_CHECKPOINT_STATE,
-                component = LOG_COMPONENT_HEAL,
-                subsystem = LOG_SUBSYSTEM_RESUME,
-                task_id,
-                state = "blocked_marker_write_failed",
-                error = %error,
-                "Heal checkpoint could not persist its blocked marker"
-            ),
-        }
-    }
-
     /// create new checkpoint manager
     pub async fn new(disk: DiskStore, task_id: String) -> Result<Self> {
         validate_resume_task_id(&task_id)?;
-        let checkpoint_volume = format!("{RUSTFS_META_BUCKET}/{BUCKET_META_PREFIX}");
-        if let Err(error) = EcstoreDiskAPI::make_volume(disk.as_ref(), &checkpoint_volume).await
-            && error != crate::heal::DiskError::VolumeExists
-        {
-            return Err(Error::TaskExecutionFailed {
-                message: format!("Failed to create checkpoint volume: {error}"),
-            });
-        }
         let checkpoint = ResumeCheckpoint::new(task_id);
         let manager = Self {
             disk,
             checkpoint: Arc::new(RwLock::new(checkpoint)),
             throttle: Mutex::new(PersistThrottle::new()),
-            save_lock: AsyncMutex::new(()),
-            last_saved: Mutex::new(None),
         };
 
         // save initial checkpoint
@@ -245,7 +140,6 @@ impl CheckpointManager {
                 error = %e,
                 "Heal checkpoint persistence failed"
             );
-            return Err(e);
         }
         Ok(manager)
     }
@@ -254,22 +148,11 @@ impl CheckpointManager {
     pub async fn load_from_disk(disk: DiskStore, task_id: &str) -> Result<Self> {
         validate_resume_task_id(task_id)?;
         let checkpoint_data = Self::read_checkpoint_file(&disk, task_id).await?;
-        Self::load_from_data(disk, task_id, checkpoint_data).await
-    }
-
-    async fn load_from_data(disk: DiskStore, task_id: &str, checkpoint_data: Vec<u8>) -> Result<Self> {
-        validate_resume_task_id(task_id)?;
-        let mut checkpoint: ResumeCheckpoint = match serde_json::from_slice(&checkpoint_data) {
-            Ok(checkpoint) => checkpoint,
-            Err(error) => {
-                Self::block_invalid_snapshot(&disk, task_id).await;
-                return Err(Error::TaskExecutionFailed {
-                    message: format!("Failed to deserialize checkpoint: {error}"),
-                });
-            }
-        };
+        let mut checkpoint: ResumeCheckpoint =
+            serde_json::from_slice(&checkpoint_data).map_err(|e| Error::TaskExecutionFailed {
+                message: format!("Failed to deserialize checkpoint: {e}"),
+            })?;
         if checkpoint.task_id != task_id {
-            Self::block_invalid_snapshot(&disk, task_id).await;
             return Err(Error::TaskExecutionFailed {
                 message: "Resume checkpoint task id does not match filename".to_string(),
             });
@@ -280,7 +163,6 @@ impl CheckpointManager {
         // identities. Discard the stale sets and position, then stamp the
         // current schema so the scan restarts cleanly.
         if checkpoint.schema_version > CURRENT_CHECKPOINT_SCHEMA {
-            Self::block_invalid_snapshot(&disk, task_id).await;
             return Err(Error::TaskExecutionFailed {
                 message: format!(
                     "Checkpoint schema {} is newer than supported schema {CURRENT_CHECKPOINT_SCHEMA}",
@@ -288,43 +170,7 @@ impl CheckpointManager {
                 ),
             });
         }
-
-        if let Some(expected) = checkpoint.integrity_digest.as_deref() {
-            let actual = Self::checkpoint_digest(&Self::serialize_without_digest(&checkpoint)?);
-            if expected != actual {
-                Self::block_invalid_snapshot(&disk, task_id).await;
-                return Err(Error::InvalidCheckpoint(format!(
-                    "Resume checkpoint digest does not match task {task_id}"
-                )));
-            }
-        } else if checkpoint.schema_version >= CURRENT_CHECKPOINT_SCHEMA {
-            Self::block_invalid_snapshot(&disk, task_id).await;
-            return Err(Error::InvalidCheckpoint(format!(
-                "Resume checkpoint digest is missing for task {task_id}"
-            )));
-        } else {
-            let digest_path = Self::digest_path(task_id);
-            let digest_path = path_to_str(&digest_path)?;
-            match HealDiskExt::read_all(disk.as_ref(), RUSTFS_META_BUCKET, digest_path).await {
-                Ok(expected) => {
-                    let actual = Self::checkpoint_digest(&checkpoint_data);
-                    if expected.as_ref() != actual.as_bytes() {
-                        Self::block_invalid_snapshot(&disk, task_id).await;
-                        return Err(Error::InvalidCheckpoint(format!(
-                            "Resume checkpoint digest does not match task {task_id}"
-                        )));
-                    }
-                }
-                Err(crate::heal::DiskError::FileNotFound) => {}
-                Err(error) => {
-                    return Err(Error::TaskExecutionFailed {
-                        message: format!("Failed to read checkpoint digest: {error}"),
-                    });
-                }
-            }
-        }
-
-        if checkpoint.schema_version < CHECKPOINT_PER_VERSION_SCHEMA {
+        if checkpoint.schema_version < CURRENT_CHECKPOINT_SCHEMA {
             warn!(
                 target: "rustfs::heal::resume",
                 event = EVENT_HEAL_CHECKPOINT_STATE,
@@ -341,15 +187,13 @@ impl CheckpointManager {
             checkpoint.skipped_objects.clear();
             checkpoint.current_bucket_index = 0;
             checkpoint.current_object_index = 0;
+            checkpoint.schema_version = CURRENT_CHECKPOINT_SCHEMA;
         }
-        checkpoint.schema_version = CURRENT_CHECKPOINT_SCHEMA;
 
         Ok(Self {
             disk,
             checkpoint: Arc::new(RwLock::new(checkpoint)),
             throttle: Mutex::new(PersistThrottle::new()),
-            save_lock: AsyncMutex::new(()),
-            last_saved: Mutex::new(Some(EcstoreDiskBytes::from(checkpoint_data))),
         })
     }
 
@@ -360,7 +204,7 @@ impl CheckpointManager {
         }
         let file_path = Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_FILE}"));
         match path_to_str(&file_path) {
-            Ok(path_str) => match HealDiskExt::read_all(disk.as_ref(), RUSTFS_META_BUCKET, path_str).await {
+            Ok(path_str) => match disk.read_all(RUSTFS_META_BUCKET, path_str).await {
                 Ok(data) => !data.is_empty(),
                 Err(_) => false,
             },
@@ -448,8 +292,6 @@ impl CheckpointManager {
 
         let checkpoint_file = Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_FILE}"));
         delete_resume_file(&self.disk, &checkpoint_file).await?;
-        delete_resume_file(&self.disk, &Self::digest_path(&task_id)).await?;
-        delete_resume_file(&self.disk, &Self::blocked_path(&task_id)).await?;
 
         debug!(
             target: "rustfs::heal::resume",
@@ -465,130 +307,21 @@ impl CheckpointManager {
 
     /// save checkpoint to disk
     async fn save_checkpoint(&self) -> Result<()> {
-        // Serialize saves and take the snapshot only after acquiring the lock:
-        // a slower writer must not publish a snapshot taken before a newer one.
-        let _save_guard = self.save_lock.lock().await;
-        let checkpoint = self.checkpoint.read().await.clone();
+        let checkpoint = self.checkpoint.read().await;
         validate_resume_task_id(&checkpoint.task_id)?;
-        let unsigned_checkpoint_data = Self::serialize_without_digest(&checkpoint)?;
-        let digest = Self::checkpoint_digest(&unsigned_checkpoint_data);
-        let mut persisted_checkpoint = checkpoint.clone();
-        persisted_checkpoint.integrity_digest = Some(digest);
-        let checkpoint_data =
-            EcstoreDiskBytes::from(serde_json::to_vec(&persisted_checkpoint).map_err(|e| Error::TaskExecutionFailed {
-                message: format!("Failed to serialize checkpoint: {e}"),
-            })?);
+        let checkpoint_data = serde_json::to_vec(&*checkpoint).map_err(|e| Error::TaskExecutionFailed {
+            message: format!("Failed to serialize checkpoint: {e}"),
+        })?;
 
         let file_path = Path::new(BUCKET_META_PREFIX).join(format!("{}_{}", checkpoint.task_id, RESUME_CHECKPOINT_FILE));
 
         let path_str = path_to_str(&file_path)?;
-        let last_saved = self
-            .last_saved
-            .lock()
-            .map_err(|_| Error::TaskExecutionFailed {
-                message: "Checkpoint save state lock is poisoned; refusing to save".to_string(),
-            })?
-            .clone();
-        let update = EcstoreDiskAPI::compare_and_update_file(
-            self.disk.as_ref(),
-            RUSTFS_META_BUCKET,
-            path_str,
-            last_saved.clone(),
-            Some(checkpoint_data.clone()),
-        )
-        .await
-        .map_err(|e| Error::TaskExecutionFailed {
-            message: format!("Failed to save checkpoint: {e}"),
-        })?;
-
-        let expected = match update {
-            EcstoreConditionalFileUpdate::Updated => None,
-            EcstoreConditionalFileUpdate::Missing => {
-                return Err(Error::TaskExecutionFailed {
-                    message: "Checkpoint was removed after this manager saved it; refusing to recreate it".to_string(),
-                });
-            }
-            EcstoreConditionalFileUpdate::Mismatch => {
-                // A healthy manager normally completes the CAS above without
-                // another read or JSON parse. Inspect only after a mismatch so
-                // corruption and future schemas cannot be overwritten blindly.
-                let existing = match HealDiskExt::read_all(self.disk.as_ref(), RUSTFS_META_BUCKET, path_str).await {
-                    Ok(existing) => existing,
-                    Err(crate::heal::DiskError::FileNotFound) => {
-                        return Err(Error::TaskExecutionFailed {
-                            message: "Checkpoint was removed after this manager saved it; refusing to recreate it".to_string(),
-                        });
-                    }
-                    Err(error) => {
-                        return Err(Error::TaskExecutionFailed {
-                            message: format!("Failed to inspect checkpoint after CAS mismatch: {error}"),
-                        });
-                    }
-                };
-
-                if existing.is_empty() && last_saved.is_none() {
-                    Some(existing)
-                } else {
-                    let current: ResumeCheckpoint = match serde_json::from_slice(&existing) {
-                        Ok(current) => current,
-                        Err(error) => {
-                            Self::block_invalid_snapshot(&self.disk, &checkpoint.task_id).await;
-                            return Err(Error::TaskExecutionFailed {
-                                message: format!("Existing checkpoint is corrupt: {error}"),
-                            });
-                        }
-                    };
-                    if current.task_id != checkpoint.task_id {
-                        Self::block_invalid_snapshot(&self.disk, &checkpoint.task_id).await;
-                        return Err(Error::TaskExecutionFailed {
-                            message: "Existing checkpoint task id does not match filename".to_string(),
-                        });
-                    }
-                    if current.schema_version > CURRENT_CHECKPOINT_SCHEMA {
-                        Self::block_invalid_snapshot(&self.disk, &checkpoint.task_id).await;
-                        return Err(Error::TaskExecutionFailed {
-                            message: format!(
-                                "Existing checkpoint schema {} is newer than supported schema {CURRENT_CHECKPOINT_SCHEMA}",
-                                current.schema_version
-                            ),
-                        });
-                    }
-                    if last_saved.as_ref().is_none_or(|saved| saved.as_ref() != existing.as_ref()) {
-                        return Err(Error::TaskExecutionFailed {
-                            message: "Checkpoint changed since this manager loaded it; refusing to overwrite newer progress"
-                                .to_string(),
-                        });
-                    }
-                    Some(existing)
-                }
-            }
-        };
-
-        if let Some(expected) = expected {
-            match EcstoreDiskAPI::compare_and_update_file(
-                self.disk.as_ref(),
-                RUSTFS_META_BUCKET,
-                path_str,
-                Some(expected),
-                Some(checkpoint_data.clone()),
-            )
+        self.disk
+            .write_all(RUSTFS_META_BUCKET, path_str, checkpoint_data.into())
             .await
             .map_err(|e| Error::TaskExecutionFailed {
-                message: format!("Failed to save checkpoint after CAS mismatch: {e}"),
-            })? {
-                EcstoreConditionalFileUpdate::Updated => {}
-                EcstoreConditionalFileUpdate::Missing | EcstoreConditionalFileUpdate::Mismatch => {
-                    return Err(Error::TaskExecutionFailed {
-                        message: "Checkpoint changed while saving; refusing to overwrite newer progress".to_string(),
-                    });
-                }
-            }
-        }
-
-        let mut last_saved = self.last_saved.lock().map_err(|_| Error::TaskExecutionFailed {
-            message: "Checkpoint save state lock is poisoned after save".to_string(),
-        })?;
-        *last_saved = Some(checkpoint_data);
+                message: format!("Failed to save checkpoint: {e}"),
+            })?;
 
         debug!(
             target: "rustfs::heal::resume",
@@ -608,38 +341,11 @@ impl CheckpointManager {
         let file_path = Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_FILE}"));
 
         let path_str = path_to_str(&file_path)?;
-        HealDiskExt::read_all(disk.as_ref(), RUSTFS_META_BUCKET, path_str)
+        disk.read_all(RUSTFS_META_BUCKET, path_str)
             .await
             .map(|bytes| bytes.to_vec())
             .map_err(|e| Error::TaskExecutionFailed {
                 message: format!("Failed to read checkpoint file: {e}"),
             })
     }
-
-    fn serialize_without_digest(checkpoint: &ResumeCheckpoint) -> Result<Vec<u8>> {
-        let mut unsigned = checkpoint.clone();
-        unsigned.integrity_digest = None;
-        let mut value = serde_json::to_value(&unsigned).map_err(|e| Error::TaskExecutionFailed {
-            message: format!("Failed to serialize checkpoint: {e}"),
-        })?;
-        for field in ["processed_objects", "failed_objects", "skipped_objects"] {
-            let Some(values) = value.get_mut(field).and_then(serde_json::Value::as_array_mut) else {
-                return Err(Error::TaskExecutionFailed {
-                    message: format!("Failed to canonicalize checkpoint field: {field}"),
-                });
-            };
-            values.sort_by(|left, right| left.as_str().cmp(&right.as_str()));
-        }
-        serde_json::to_vec(&value).map_err(|e| Error::TaskExecutionFailed {
-            message: format!("Failed to serialize checkpoint: {e}"),
-        })
-    }
-
-    fn checkpoint_digest(checkpoint_data: &[u8]) -> String {
-        base64::engine::general_purpose::STANDARD.encode(Sha256::digest(checkpoint_data))
-    }
-
-    fn digest_path(task_id: &str) -> std::path::PathBuf {
-        Path::new(BUCKET_META_PREFIX).join(format!("{task_id}_{RESUME_CHECKPOINT_DIGEST_FILE}"))
-    }
 }

crates/heal/src/heal/resume/tests.rs

@@ -1600,29 +1600,6 @@ async fn test_checkpoint_schema_v4_discarded_on_load() {
     temp_dir.close().expect("remove schema test directory");
 }
 
-#[tokio::test]
-async fn unsigned_previous_checkpoint_schema_preserves_progress() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let mut legacy = ResumeCheckpoint::new(task_id.clone());
-    legacy.schema_version = CURRENT_CHECKPOINT_SCHEMA - 1;
-    legacy.update_position(2, 500);
-    legacy.add_processed_object("object".to_string());
-    legacy.integrity_digest = None;
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, serde_json::to_vec(&legacy).unwrap().into())
-        .await
-        .expect("write previous-schema checkpoint");
-
-    let manager = CheckpointManager::load_from_disk(disk, &task_id).await.unwrap();
-    let checkpoint = manager.get_checkpoint().await;
-    assert_eq!(checkpoint.schema_version, CURRENT_CHECKPOINT_SCHEMA);
-    assert_eq!(checkpoint.current_bucket_index, 2);
-    assert_eq!(checkpoint.current_object_index, 500);
-    assert!(checkpoint.processed_objects.contains("object"));
-    temp_dir.close().unwrap();
-}
-
 #[tokio::test]
 async fn current_normal_resume_schema_preserves_progress() {
     let (temp_dir, disk) = schema_test_disk().await;
@@ -1698,369 +1675,6 @@ async fn future_resume_and_checkpoint_schemas_are_rejected() {
     temp_dir.close().expect("remove schema test directory");
 }
 
-#[tokio::test]
-async fn checkpoint_save_does_not_replace_a_non_empty_truncated_snapshot() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    let truncated = b"{\"schema_version\":5,\"task_id\":";
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, truncated.as_slice().into())
-        .await
-        .expect("write truncated checkpoint fixture");
-
-    let error = manager
-        .update_position(2, 7)
-        .await
-        .expect_err("a truncated checkpoint must fail closed during save");
-    assert!(error.to_string().contains("Existing checkpoint is corrupt"));
-    assert_eq!(
-        disk.read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-            .await
-            .expect("read truncated checkpoint fixture"),
-        truncated.as_slice()
-    );
-    assert!(CheckpointManager::is_blocked(&disk, &task_id).await);
-    temp_dir.close().expect("remove checkpoint save test directory");
-}
-
-#[tokio::test]
-async fn checkpoint_save_does_not_replace_a_future_schema_snapshot() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    let mut future = ResumeCheckpoint::new(task_id.clone());
-    future.schema_version = CURRENT_CHECKPOINT_SCHEMA + 1;
-    let future_bytes = serde_json::to_vec(&future).expect("serialize future checkpoint fixture");
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, future_bytes.clone().into())
-        .await
-        .expect("write future checkpoint fixture");
-
-    let error = manager
-        .update_position(2, 7)
-        .await
-        .expect_err("a future schema must fail closed during save");
-    assert!(error.to_string().contains("Existing checkpoint schema"));
-    assert_eq!(
-        disk.read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-            .await
-            .expect("read future checkpoint fixture"),
-        future_bytes
-    );
-    assert!(CheckpointManager::is_blocked(&disk, &task_id).await);
-    temp_dir.close().expect("remove future schema test directory");
-}
-
-#[tokio::test]
-async fn checkpoint_digest_rejects_same_length_progress_tampering() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    manager
-        .add_processed_object("victim-a".to_string())
-        .await
-        .expect("persist checkpoint progress");
-    manager.update_position(1, 1).await.expect("flush checkpoint progress");
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    let original = disk
-        .read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-        .await
-        .expect("read checkpoint fixture");
-    let tampered = original
-        .windows(b"victim-a".len())
-        .position(|window| window == b"victim-a")
-        .map(|index| {
-            let mut bytes = original.to_vec();
-            bytes[index..index + b"victim-a".len()].copy_from_slice(b"victim-b");
-            bytes
-        })
-        .expect("checkpoint should contain the processed object");
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, tampered.into())
-        .await
-        .expect("write tampered checkpoint fixture");
-
-    assert!(CheckpointManager::load_from_disk(disk.clone(), &task_id).await.is_err());
-    assert!(CheckpointManager::is_blocked(&disk, &task_id).await);
-    temp_dir.close().expect("remove digest test directory");
-}
-
-#[tokio::test]
-async fn checkpoint_integrity_survives_missing_legacy_sidecar() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone()).await.unwrap();
-    manager.update_position(2, 9).await.unwrap();
-
-    let digest_path = format!("{BUCKET_META_PREFIX}/{task_id}_ahm_checkpoint.sha256");
-    delete_resume_file(&disk, Path::new(&digest_path)).await.unwrap();
-
-    let restored = CheckpointManager::load_from_disk(disk, &task_id).await.unwrap();
-    let checkpoint = restored.get_checkpoint().await;
-    assert_eq!(checkpoint.current_bucket_index, 2);
-    assert_eq!(checkpoint.current_object_index, 9);
-    assert!(checkpoint.integrity_digest.is_some());
-    temp_dir.close().unwrap();
-}
-
-#[tokio::test]
-async fn checkpoint_integrity_survives_multi_object_reload() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone()).await.unwrap();
-    for index in 0..32 {
-        manager.add_processed_object(format!("processed-{index}")).await.unwrap();
-        manager.add_failed_object(format!("failed-{index}")).await.unwrap();
-        manager.add_skipped_object(format!("skipped-{index}")).await.unwrap();
-    }
-    manager.update_position(2, 9).await.unwrap();
-
-    CheckpointManager::load_from_disk(disk, &task_id)
-        .await
-        .expect("a healthy multi-object checkpoint must survive reload");
-    temp_dir.close().unwrap();
-}
-
-#[tokio::test]
-async fn checkpoint_integrity_rejects_a_removed_embedded_digest() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone()).await.unwrap();
-    manager.update_position(2, 9).await.unwrap();
-
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    let bytes = disk
-        .read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-        .await
-        .expect("read checkpoint fixture");
-    let mut value: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
-    value["current_object_index"] = serde_json::json!(10);
-    value.as_object_mut().unwrap().remove("integrity_digest");
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, serde_json::to_vec(&value).unwrap().into())
-        .await
-        .expect("write tampered checkpoint fixture");
-
-    assert!(
-        CheckpointManager::load_from_disk(disk.clone(), &task_id).await.is_err(),
-        "a current checkpoint without its embedded digest must fail closed"
-    );
-    assert!(CheckpointManager::is_blocked(&disk, &task_id).await);
-    temp_dir.close().unwrap();
-}
-
-#[tokio::test]
-async fn new_checkpoint_manager_rebuilds_an_empty_snapshot() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-    disk.write_all(RUSTFS_META_BUCKET, &checkpoint_path, EcstoreDiskBytes::new())
-        .await
-        .expect("write empty checkpoint fixture");
-
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("a new manager must rebuild an empty checkpoint");
-    manager
-        .update_position(3, 11)
-        .await
-        .expect("rebuilt checkpoint must remain writable");
-    assert!(CheckpointManager::has_checkpoint(&disk, &task_id).await);
-    temp_dir.close().expect("remove empty checkpoint test directory");
-}
-
-#[tokio::test]
-async fn deleted_checkpoint_is_not_recreated_by_an_old_manager() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    manager.cleanup().await.expect("delete checkpoint fixture");
-
-    let error = manager
-        .update_position(1, 2)
-        .await
-        .expect_err("an old manager must not resurrect a deleted checkpoint");
-    assert!(error.to_string().contains("removed after this manager saved it"));
-    assert!(!CheckpointManager::has_checkpoint(&disk, &task_id).await);
-    temp_dir.close().expect("remove deleted checkpoint test directory");
-}
-
-#[cfg(unix)]
-#[tokio::test]
-async fn checkpoint_cleanup_leaves_no_task_specific_lock_artifact() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    let lock_path = Path::new(BUCKET_META_PREFIX)
-        .join(format!("{task_id}_{RESUME_CHECKPOINT_FILE}"))
-        .with_extension("rustfs-cas.lock");
-    let lock_path = temp_dir.path().join(RUSTFS_META_BUCKET).join(lock_path);
-
-    manager.cleanup().await.expect("delete checkpoint fixture");
-
-    assert!(
-        !lock_path.exists(),
-        "successful checkpoint cleanup must not leave a task-specific lock artifact"
-    );
-}
-
-#[tokio::test]
-async fn an_empty_blocked_marker_still_blocks_resume_selection() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let manager = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create checkpoint manager");
-    let blocked_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_BLOCKED_FILE}");
-    disk.write_all(RUSTFS_META_BUCKET, &blocked_path, EcstoreDiskBytes::new())
-        .await
-        .expect("write empty blocked marker fixture");
-
-    assert!(CheckpointManager::is_blocked(&disk, &task_id).await);
-    assert!(CheckpointManager::is_resumable(&disk, &task_id).await.is_err());
-    // Recovery requires replacing/cleaning the snapshot, then removing the
-    // marker; ordinary selector retries are intentionally not an unlock path.
-    manager.cleanup().await.expect("clean blocked checkpoint");
-    assert!(!CheckpointManager::is_blocked(&disk, &task_id).await);
-    temp_dir.close().expect("remove empty blocked marker test directory");
-}
-
-#[tokio::test]
-async fn resumable_selector_skips_healthy_tasks_with_blocked_markers() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let tasks = [
-        (ResumeUtils::generate_task_id(), EcstoreDiskBytes::new()),
-        (ResumeUtils::generate_task_id(), EcstoreDiskBytes::from_static(b"blocked")),
-    ];
-    for (task_id, marker) in &tasks {
-        ResumeManager::new(
-            disk.clone(),
-            task_id.clone(),
-            "erasure_set".to_string(),
-            "pool_0_set_0".to_string(),
-            vec!["bucket".to_string()],
-        )
-        .await
-        .expect("create healthy resume state");
-        CheckpointManager::new(disk.clone(), task_id.clone())
-            .await
-            .expect("create healthy checkpoint");
-        let checkpoint_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_FILE}");
-        let checkpoint_bytes = disk
-            .read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-            .await
-            .expect("read healthy checkpoint before blocking");
-        let marker_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_BLOCKED_FILE}");
-        disk.write_all(RUSTFS_META_BUCKET, &marker_path, marker.clone())
-            .await
-            .expect("write blocked marker");
-
-        assert!(ResumeUtils::get_resumable_tasks(&disk).await.is_err());
-        assert_eq!(
-            disk.read_all(RUSTFS_META_BUCKET, &checkpoint_path)
-                .await
-                .expect("read healthy checkpoint after blocking"),
-            checkpoint_bytes
-        );
-    }
-    temp_dir.close().expect("remove blocked selector test directory");
-}
-
-#[tokio::test]
-async fn stale_checkpoint_manager_cannot_overwrite_newer_progress() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let task_id = ResumeUtils::generate_task_id();
-    let first = CheckpointManager::new(disk.clone(), task_id.clone())
-        .await
-        .expect("create first checkpoint manager");
-    let second = CheckpointManager::load_from_disk(disk.clone(), &task_id)
-        .await
-        .expect("load second checkpoint manager");
-
-    second
-        .update_position(4, 20)
-        .await
-        .expect("persist newer checkpoint progress");
-    let error = first
-        .update_position(1, 3)
-        .await
-        .expect_err("stale checkpoint manager must not overwrite newer progress");
-    assert!(error.to_string().contains("newer progress"));
-
-    let persisted = CheckpointManager::load_from_disk(disk.clone(), &task_id)
-        .await
-        .expect("load newer checkpoint progress")
-        .get_checkpoint()
-        .await;
-    assert_eq!(persisted.current_bucket_index, 4);
-    assert_eq!(persisted.current_object_index, 20);
-    temp_dir.close().expect("remove stale manager test directory");
-}
-
-#[tokio::test]
-async fn resumable_selector_isolates_future_and_corrupt_checkpoints() {
-    let (temp_dir, disk) = schema_test_disk().await;
-    let future_task = ResumeUtils::generate_task_id();
-    let corrupt_task = ResumeUtils::generate_task_id();
-    for task_id in [&future_task, &corrupt_task] {
-        ResumeManager::new(
-            disk.clone(),
-            task_id.to_string(),
-            "erasure_set".to_string(),
-            "pool_0_set_0".to_string(),
-            vec!["bucket".to_string()],
-        )
-        .await
-        .expect("create resumable state fixture");
-    }
-
-    let future_path = format!("{BUCKET_META_PREFIX}/{future_task}_{RESUME_CHECKPOINT_FILE}");
-    let mut future = ResumeCheckpoint::new(future_task.clone());
-    future.schema_version = CURRENT_CHECKPOINT_SCHEMA + 1;
-    let future_bytes = serde_json::to_vec(&future).expect("serialize future checkpoint fixture");
-    disk.write_all(RUSTFS_META_BUCKET, &future_path, future_bytes.clone().into())
-        .await
-        .expect("write future checkpoint fixture");
-    let corrupt_path = format!("{BUCKET_META_PREFIX}/{corrupt_task}_{RESUME_CHECKPOINT_FILE}");
-    let corrupt_bytes = b"{truncated";
-    disk.write_all(RUSTFS_META_BUCKET, &corrupt_path, corrupt_bytes.as_slice().into())
-        .await
-        .expect("write corrupt checkpoint fixture");
-
-    assert!(CheckpointManager::is_resumable(&disk, &future_task).await.is_err());
-    assert!(CheckpointManager::is_resumable(&disk, &corrupt_task).await.is_err());
-    assert!(ResumeUtils::get_resumable_tasks(&disk).await.is_err());
-    for (task_id, path, bytes) in [
-        (&future_task, future_path, future_bytes),
-        (&corrupt_task, corrupt_path, corrupt_bytes.to_vec()),
-    ] {
-        assert_eq!(
-            disk.read_all(RUSTFS_META_BUCKET, &path)
-                .await
-                .expect("read isolated checkpoint bytes"),
-            bytes
-        );
-        let blocked_path = format!("{BUCKET_META_PREFIX}/{task_id}_{RESUME_CHECKPOINT_BLOCKED_FILE}");
-        assert!(
-            !disk
-                .read_all(RUSTFS_META_BUCKET, &blocked_path)
-                .await
-                .expect("read checkpoint blocked marker")
-                .is_empty()
-        );
-    }
-    temp_dir.close().expect("remove selector isolation test directory");
-}
-
 #[test]
 fn test_persist_throttle_batches_until_threshold() {
     let mut throttle = PersistThrottle::new();

crates/heal/src/heal/resume/utils.rs

@@ -21,7 +21,7 @@ use uuid::Uuid;
 use super::super::{BUCKET_META_PREFIX, DiskError, DiskStore, HealDiskExt as _, RUSTFS_META_BUCKET};
 use super::replacement::{ReplacementPhase, ReplacementRecoveryRecord};
 use super::{
-    CheckpointManager, EVENT_HEAL_RESUME_STATE, LOG_COMPONENT_HEAL, LOG_SUBSYSTEM_RESUME, REPLACEMENT_COMPLETION_PROOF_FILE,
+    EVENT_HEAL_RESUME_STATE, LOG_COMPONENT_HEAL, LOG_SUBSYSTEM_RESUME, REPLACEMENT_COMPLETION_PROOF_FILE,
     REPLACEMENT_INTENT_FILE, RESUME_STATE_FILE, ResumeManager, ResumeStateFile, is_replacement_intent, path_to_str,
     replacement_recovery_corruption_for_state_load, replacement_recovery_dir, validate_resume_task_id,
 };
@@ -67,7 +67,6 @@ impl ResumeUtils {
                 // Extract task ID from filename: {task_id}_ahm_resume_state.json
                 if let Some(task_id) = entry.strip_suffix(&format!("_{RESUME_STATE_FILE}"))
                     && validate_resume_task_id(task_id).is_ok()
-                    && CheckpointManager::is_resumable(disk, task_id).await?
                 {
                     task_ids.push(task_id.to_string());
                 }

crates/scanner/src/data_usage_define/tests.rs

@@ -16,7 +16,7 @@ use super::persistence::DataUsageCacheLoadAttempt;
 use super::*;
 use crate::storage_api::scanner_io::{HTTPRangeSpec, ObjectIO};
 use crate::{ScannerGetObjectReader, ScannerPutObjReader};
-use rustfs_data_usage::{ReplicationAllStats, ReplicationTargetUsage};
+use rustfs_data_usage::{ReplicationAllStats, ReplicationStats};
 use serde_json::Value;
 use std::io::Cursor;
 use std::pin::Pin;
@@ -1636,7 +1636,7 @@ fn size_recursive_prunes_empty_and_preserves_threshold_replication_stats() {
             replication_stats: Some(ReplicationAllStats {
                 targets: HashMap::from([(
                     "arn:test:threshold".to_string(),
-                    ReplicationTargetUsage {
+                    ReplicationStats {
                         after_threshold_count: 1,
                         ..Default::default()
                     },

crates/scanner/src/scanner_io/publish_gate_tests.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 use super::*;
-use rustfs_data_usage::{ReplicationAllStats, ReplicationTargetUsage};
+use rustfs_data_usage::{ReplicationAllStats, ReplicationStats};
 
 const TEST_PLAN_DIGEST: DataUsageScanPlanDigest = DataUsageScanPlanDigest([7; 32]);
 
@@ -271,7 +271,7 @@ fn completed_data_usage_info_flattens_nested_bucket_entries() {
         replication_stats: Some(ReplicationAllStats {
             targets: HashMap::from([(
                 "arn:target".to_string(),
-                ReplicationTargetUsage {
+                ReplicationStats {
                     replicated_size: 2048,
                     replicated_count: 2,
                     ..Default::default()

docs/architecture/decommission-compatibility.md

@@ -153,6 +153,91 @@ No migration step is required for these decisions because this note documents th
 current RustFS behavior. Changing either decision later requires an operator
 compatibility note and updated characterization tests.
 
+## Tier Free Versions During Decommission
+
+A tier free version is an internal xl.meta record (`rustfs_filemeta::FREE_VERSION`,
+flagged `XL_FLAG_FREE_VERSION`) shaped like a delete marker. It is created by
+`MetaObject::init_free_version` when a version whose remote transition completed is
+deleted locally: the visible version is removed and the record keeps the remote-tier
+identity (tier, object name, version id, state, destination id) needed for an
+idempotent remote delete. Free versions are not user-visible versions; `num_versions`
+and all listing/GET paths exclude them.
+
+### Lifecycle And Consumers
+
+Creation: any local delete that removes a version whose transition status is
+`complete` appends the record via `MetaObject::delete_version` →
+`init_free_version` (skipped only when `skip_tier_free_version` is set, as on
+data-movement copies). The same deletes also persist a durable tier-journal
+entry on every user-facing path: S3 single deletes (`execute_delete_object` →
+`delete_object_with_tier_delete_journal`), S3 batch deletes, lifecycle expiry,
+and lifecycle delete-all all prepare and commit a journal entry around the
+delete. A journal entry is omitted when the removed version's transition state
+decodes as `TransitionVersionState::Unknown`, or on internal journal-less
+delete paths that never touch transitioned user objects.
+
+Consumption while the record exists: the background recovery loop started by
+`init_background_expiry` (spawned by `spawn_tier_free_version_recovery_once`,
+enabled by default) scans disks for pending records and re-enqueues them; the
+usage scanner does the same; the lifecycle worker then deletes the remote tier
+object idempotently and only afterwards removes the local record. Heal walks
+include free-version records in metadata healing. Transition planning,
+replication, restore, GET, listings, and usage aggregation never depend on
+them.
+
+### Decommission Handling
+
+The exact decommission inventory loader (`load_file_info_versions_exact` via
+`get_all_file_info_versions`) keeps free-version records inline in `versions`; it
+never populates `free_versions`, so the source-cleanup preflight comparison of
+`free_versions` is vacuous for decommission. The migration loop then routes every
+record through the generic delete-marker handling:
+
+- a record that is the only remaining version without replication is skipped by the
+  empty-delete-marker rule and counted as done;
+- any other record is copied to the target pool as an ordinary delete marker with the
+  same version id and mod time.
+
+In both cases the free-version flag and its remote-tier identity are dropped:
+decommission neither preserves free-version semantics nor performs or reschedules the
+pending remote-tier delete. Source cleanup then removes the original records together
+with the source xl.meta.
+
+Allowed physical-delete timing: the source record may be removed once the migration
+loop has dispositioned it (copied as a plain marker or skipped as lone), which
+happens regardless of whether its remote-tier delete was ever performed.
+
+### Reference-Audit Result
+
+No cluster-local consumer resolves a free version after decommission finishes: GET,
+listing, transition planning, replication, restore, and heal operate either on
+user-visible versions or while the record still exists. The remote exposure is
+bounded:
+
+- On every user-facing delete path the remote-delete obligation is durably carried
+  by the committed tier-journal entry, which the tier sweeper processes
+  independently of xl.meta; the free-version record is an idempotent second
+  pointer, not the only one. Dropping it during decommission therefore does not
+  orphan the remote object.
+- Residual exposure: for records whose version state decoded as `Unknown` no
+  journal entry exists, so dropping the unconsumed record loses that cleanup hint
+  and the remote-tier object is orphaned. The same applies to any future internal
+  delete path that removes transitioned versions without a journal entry.
+
+Copying a pending record as an ordinary delete marker also adds a user-visible
+tombstone to the target pool's version history that the source never exposed.
+
+Because of the residual journal-less case, decommission must account for every
+free-version record instead of omitting it silently:
+
+- `decommission_free_versions_skipped` counts the records per decommission entry;
+- entries with a non-zero count log `state = "free_versions_skipped"` with reason
+  `tier_free_version_not_migrated`.
+
+Regression guard:
+
+- `decommission_free_version_accounting_reports_skipped_records`
+
 ## Regression Guard
 
 The queued multi-pool contract is guarded by: