diff --git a/crates/storage-api/Cargo.toml b/crates/storage-api/Cargo.toml
index 26dc25e93..346e226e2 100644
--- a/crates/storage-api/Cargo.toml
+++ b/crates/storage-api/Cargo.toml
@@ -29,6 +29,9 @@ doctest = false
 
 [dependencies]
 async-trait.workspace = true
+# NOTE: This dependency on rustfs-filemeta is a known architectural limitation.
+# The replication types (ReplicationStatusType, VersionPurgeStatusType, ReplicationState)
+# are shared between storage-api and filemeta. Moving them would require changes in 300+ files.
 rustfs-filemeta.workspace = true
 serde.workspace = true
 time.workspace = true