ekkolon · ekkolon · Feb 27, 2026 · Feb 27, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -14,3 +14,6 @@ keywords = ["storage", "distributed", "leveldb", "object-store"]
 categories = ["database", "network-programming"]
 
 [workspace.dependencies]
+thiserror = "2"
+base64 = "0.22"
+blake3 = "1.8"
diff --git a/minikv-core/Cargo.toml b/minikv-core/Cargo.toml
@@ -11,3 +11,6 @@ keywords.workspace = true
 categories.workspace = true
 
 [dependencies]
+thiserror.workspace = true
+base64 = { workspace = true }
+blake3 = { workspace = true }
diff --git a/minikv-core/src/hashing.rs b/minikv-core/src/hashing.rs
@@ -0,0 +1,81 @@
+use base64::{Engine as _, engine::general_purpose::STANDARD as B64_STANDARD};
+
+/// Convert a raw key into a stable, deterministic storage path for volume servers.
+///
+/// Algorithm:
+/// 1. Compute BLAKE3-256 hash of `key`.
+/// 2. Use the first two bytes as two hex directory components (fanout = 256²).
+/// 3. Base64-encode the raw key as the filename.
+///
+/// Format: `/%02x/%02x/<base64-key>`
+///
+/// # Stability
+/// Changing this function after data is stored is a breaking change.\
+/// Stored keys map to different paths if the algorithm is modified, requiring a full rebalance.
+#[must_use]
+pub fn key_to_path(key: &[u8]) -> String {
+    let hash = blake3::hash(key);
+    let b = hash.as_bytes();
+    let b64 = B64_STANDARD.encode(key);
+    format!("/{:02x}/{:02x}/{}", b[0], b[1], b64)
+}
+
+/// Compute a per-volume BLAKE3 score for a key.
+///
+/// Combines the key bytes and the volume name to produce a 32-byte hash suitable
+/// for consistent shard placement.
+#[must_use]
+pub fn volume_score(key: &[u8], volume: &str) -> [u8; 32] {
+    let mut hasher = blake3::Hasher::new();
+    hasher.update(key);
+    hasher.update(volume.as_bytes());
+    *hasher.finalize().as_bytes()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn key_to_path_stability_hello() {
+        let path = key_to_path(b"hello");
+        assert_eq!(path, "/ea/8f/aGVsbG8=");
+    }
+
+    #[test]
+    fn key_to_path_stability_helloworld() {
+        let path = key_to_path(b"helloworld");
+        let parts: Vec<&str> = path.splitn(4, '/').collect();
+        assert_eq!(parts.len(), 4);
+        assert_eq!(parts[1].len(), 2);
+        assert_eq!(parts[2].len(), 2);
+        let decoded = B64_STANDARD.decode(parts[3]).unwrap();
+        assert_eq!(decoded, b"helloworld");
+    }
+
+    #[test]
+    fn key_to_path_snapshot_helloworld() {
+        let path = key_to_path(b"helloworld");
+        let hash = blake3::hash(b"helloworld");
+        let b = hash.as_bytes();
+        let expected = format!("/{:02x}/{:02x}/aGVsbG93b3JsZA==", b[0], b[1]);
+        assert_eq!(path, expected);
+    }
+
+    #[test]
+    fn key_to_path_empty_key() {
+        let path = key_to_path(b"");
+        let parts: Vec<&str> = path.splitn(4, '/').collect();
+        assert_eq!(parts.len(), 4);
+    }
+
+    #[test]
+    fn key_to_path_binary_key() {
+        let key: Vec<u8> = (0u8..=255).collect();
+        let path = key_to_path(&key);
+        let parts: Vec<&str> = path.splitn(4, '/').collect();
+        assert_eq!(parts.len(), 4);
+        let decoded = B64_STANDARD.decode(parts[3]).unwrap();
+        assert_eq!(decoded, key);
+    }
+}
diff --git a/minikv-core/src/lib.rs b/minikv-core/src/lib.rs
@@ -1 +1,2 @@
-
+pub mod hashing;
+pub mod volumes;