fix(ecstore): allow intentional decommission listing signatures under strict clippy

The sftp/swift feature-matrix clippy gates run with -D warnings and
flag the unresolved-entry resolver (large Err payload by design, 8
context parameters) and the decommission listing driver (9 args).
Document why and align with the existing decommission_entry precedent.

crates/config/src/constants/object.rs

@@ -168,6 +168,19 @@ pub const DEFAULT_DATA_MOVEMENT_PART_CHECKSUMS_FLEET_CONFIRMED: bool = false;
 const _: () = assert!(!DEFAULT_DATA_MOVEMENT_PART_CHECKSUMS_WRITE);
 const _: () = assert!(!DEFAULT_DATA_MOVEMENT_PART_CHECKSUMS_FLEET_CONFIRMED);
 
+/// Request writing pool metadata version 2.
+///
+/// This remains ineffective until [`ENV_POOL_META_V2_FLEET_CONFIRMED`] is also enabled.
+pub const ENV_POOL_META_V2_WRITE: &str = "RUSTFS_POOL_META_V2_WRITE";
+pub const DEFAULT_POOL_META_V2_WRITE: bool = false;
+
+/// Operator-attested confirmation that every pool metadata reader and writer understands version 2.
+pub const ENV_POOL_META_V2_FLEET_CONFIRMED: &str = "RUSTFS_POOL_META_V2_FLEET_CONFIRMED";
+pub const DEFAULT_POOL_META_V2_FLEET_CONFIRMED: bool = false;
+
+const _: () = assert!(!DEFAULT_POOL_META_V2_WRITE);
+const _: () = assert!(!DEFAULT_POOL_META_V2_FLEET_CONFIRMED);
+
 // =============================================================================
 // Concurrent Request Fix - Timeout and Backpressure Configuration
 // =============================================================================
@@ -736,4 +749,10 @@ mod remote_version_state_tests {
             "RUSTFS_OBJECT_TRANSACTION_FENCING_FLEET_CONFIRMED"
         );
     }
+
+    #[test]
+    fn pool_meta_v2_gate_uses_stable_environment_names() {
+        assert_eq!(super::ENV_POOL_META_V2_WRITE, "RUSTFS_POOL_META_V2_WRITE");
+        assert_eq!(super::ENV_POOL_META_V2_FLEET_CONFIRMED, "RUSTFS_POOL_META_V2_FLEET_CONFIRMED");
+    }
 }

crates/ecstore/src/store/init.rs

@@ -635,7 +635,7 @@ mod tests {
     };
     use crate::{
         bucket::replication::{ReplicationState, ReplicationStatusType, replication_statuses_map},
-        core::pools::{POOL_META_FORMAT, POOL_META_VERSION, PoolDecommissionInfo, PoolMeta, PoolStatus},
+        core::pools::{POOL_META_VERSION, PoolDecommissionInfo, PoolMeta, PoolStatus},
         disk::endpoint::Endpoint,
         error::{Error, Result, StorageError},
         io_support::rio::{WritePlan, compression_metadata_value},
@@ -649,7 +649,6 @@ mod tests {
             range::HTTPRangeSpec,
         },
     };
-    use byteorder::{LittleEndian, WriteBytesExt};
     #[cfg(feature = "test-util")]
     use futures::{StreamExt as _, TryStreamExt as _};
     use http::HeaderMap;
@@ -679,13 +678,7 @@ mod tests {
     use tokio_util::sync::CancellationToken;
 
     fn startup_pool_meta_payload(meta: &PoolMeta) -> Vec<u8> {
-        let mut data = Vec::new();
-        data.write_u16::<LittleEndian>(POOL_META_FORMAT)
-            .expect("pool metadata format should encode");
-        data.write_u16::<LittleEndian>(POOL_META_VERSION)
-            .expect("pool metadata version should encode");
-        data.extend(rmp_serde::to_vec(meta).expect("legacy pool metadata payload should encode"));
-        data
+        meta.encode_config_data_for_test().expect("pool metadata should encode")
     }
 
     #[derive(Debug)]

docs/operations/rolling-restart.md

@@ -31,6 +31,15 @@ failure pattern reported in rustfs/rustfs#4304.
 > older build is not supported: older readers ignore the sidecar and can
 > report an object checksum in place of the requested part checksum.
 
+> [!WARNING]
+> Writing pool metadata version 2 remains inactive unless both
+> `RUSTFS_POOL_META_V2_WRITE=true` and
+> `RUSTFS_POOL_META_V2_FLEET_CONFIRMED=true`. Leave either setting disabled
+> until every node that can read or write `pool.bin` supports version 2. Once a node
+> observes or writes version 2 it will not downgrade the file, and older
+> binaries or rollback builds cannot read it. Unresolved decommission entries
+> fail closed instead of being written in the version 1 format.
+
 ## TL;DR
 
 - **Rolling restart (no downtime):** restart **one node at a time**, and wait

rustfs/src/storage/storage_api.rs

@@ -522,9 +522,9 @@ pub(crate) mod ecstore_rpc {
         KMS_SIGNAL_SUBSYSTEM, LocalPeerS3Client, PEER_RESTDRY_RUN, PEER_RESTSIGNAL, PEER_RESTSUB_SYS, PeerRestClient,
         PeerS3Client, SERVICE_SIGNAL_REFRESH_CONFIG, SERVICE_SIGNAL_RELOAD_DYNAMIC, TONIC_RPC_PREFIX,
         check_and_record_signed_rpc_nonce, decode_heal_bucket_rpc_options, normalize_tonic_rpc_audience,
-        sign_ns_scanner_capability, sign_ns_scanner_capability_with_tier_registry_generation, sign_put_file_capability,
-        sign_tonic_rpc_response_proof, tonic_boot_epoch_challenge, tonic_boot_epoch_response_headers,
-        tonic_rpc_auth_failure_reason, verify_put_file_auth_trailer, verify_rpc_signature, verify_tonic_canonical_body_digest,
+        sign_ns_scanner_capability_with_tier_registry_generation, sign_put_file_capability, sign_tonic_rpc_response_proof,
+        tonic_boot_epoch_challenge, tonic_boot_epoch_response_headers, tonic_rpc_auth_failure_reason,
+        verify_put_file_auth_trailer, verify_rpc_signature, verify_tonic_canonical_body_digest,
         verify_tonic_mutation_body_digest, verify_tonic_rpc_signature_with_bootstrap,
     };
     #[cfg(test)]
@@ -1409,11 +1409,6 @@ where
 }
 
 pub(crate) trait StoragePeerS3ClientExt {
-    async fn heal_bucket(
-        &self,
-        bucket: &str,
-        opts: &rustfs_common::heal_channel::HealOpts,
-    ) -> DiskResult<rustfs_madmin::heal_commands::HealResultItem>;
     async fn heal_bucket_with_fence(
         &self,
         bucket: &str,
@@ -1431,14 +1426,6 @@ pub(crate) trait StoragePeerS3ClientExt {
 }
 
 impl StoragePeerS3ClientExt for LocalPeerS3Client {
-    async fn heal_bucket(
-        &self,
-        bucket: &str,
-        opts: &rustfs_common::heal_channel::HealOpts,
-    ) -> DiskResult<rustfs_madmin::heal_commands::HealResultItem> {
-        ecstore_rpc::PeerS3Client::heal_bucket(self, bucket, opts).await
-    }
-
     async fn heal_bucket_with_fence(
         &self,
         bucket: &str,