feat: bytemuck::Pod + FORMAT_VERSION (v0.4.1)

Unblock UCFP's persistence story without structural breakage.

- pub const FORMAT_VERSION: u32 = 1; at crate root
- ImageFingerprint::format_version() / MultiHashFingerprint::format_version() accessors
- bytemuck::Pod + Zeroable derives on both fingerprint types with #[repr(C)]
- Compile-time layout assertions (168 / 536 bytes) — accidental drift fails build
- Copy derive added (required by Pod); doc note flags the move-by-value memcpy trade-off

Enables zero-copy persistence:
    let bytes: &[u8] = bytemuck::cast_slice(&fingerprints);

UCFP's index can now mmap fingerprint blobs without serde-roundtrip.

Author: bravo1goingdark

CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-04-27
+
+### Added
+
+- **`pub const FORMAT_VERSION: u32 = 1`** at crate root, plus `ImageFingerprint::format_version()` and `MultiHashFingerprint::format_version()` accessors. Persist alongside fingerprint bytes (or in a sidecar manifest) and refuse comparison across mismatched versions to guard against algorithm-version drift. The constant only changes when the algorithm output changes; layout drift is caught at compile time independently.
+
+- **`bytemuck::Pod + Zeroable` derives** on `ImageFingerprint` and `MultiHashFingerprint` with `#[repr(C)]`. Enables zero-copy persistence:
+
+  ```rust
+  use imgfprint::MultiHashFingerprint;
+  let bytes: &[u8] = bytemuck::cast_slice(&fingerprints);
+  // ...write to disk / mmap / send over the wire...
+  let back: &[MultiHashFingerprint] = bytemuck::cast_slice(bytes);
+  ```
+
+  Unblocks UCFP's `index` crate to store millions of fingerprints without serde-roundtrip overhead.
+
+- **Compile-time layout assertions** — `const _` size checks that `ImageFingerprint` is exactly 168 bytes and `MultiHashFingerprint` is exactly 536 bytes. Any accidental field reorder or padding addition fails the build, so consumers relying on `bytemuck::cast_slice` can't be silently broken.
+
+### Changed
+
+- **`ImageFingerprint` and `MultiHashFingerprint` now derive `Copy`** (required by `bytemuck::Pod`). Trade-off: move-by-value silently memcpys 168 / 536 bytes; prefer `&Fingerprint` borrows in hot loops where this matters. Purely additive change — nothing that compiled before fails to compile now.
+
+- **`#[repr(C)]`** added to both fingerprint types for stable cross-version binary layout. The default `repr(Rust)` layout was already padding-free at 168 / 536 bytes, so this is a guarantee, not a layout change.
+
+### Notes for UCFP integrators
+
+Storing fingerprints: cast a `&[MultiHashFingerprint]` to `&[u8]` with `bytemuck::cast_slice` before writing to your index. Persist the `FORMAT_VERSION` constant alongside (in your manifest or as a sidecar header). On read, verify the version matches before casting back. The layout-stability assertions guarantee that within a `FORMAT_VERSION`, the byte representation is identical across builds and platforms with the same endianness.
+
 ## [0.4.0] - 2026-04-27
 
 ### Added
@@ -268,7 +297,8 @@ Per-algorithm DCT/grid/hash-bit reconfiguration (different `dct_size`, `block_gr
 - Semantic embeddings via external providers
 - Local ONNX inference (optional feature)
 
-[Unreleased]: https://github.com/themankindproject/imgfprint-rs/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/themankindproject/imgfprint-rs/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/themankindproject/imgfprint-rs/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/themankindproject/imgfprint-rs/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/themankindproject/imgfprint-rs/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/themankindproject/imgfprint-rs/compare/v0.3.1...v0.3.2

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "imgfprint"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2021"
 description = "High-performance, deterministic image fingerprinting library"
 license = "MIT"
@@ -32,6 +32,7 @@ rayon = { version = "1.10", optional = true }
 tract-onnx = { version = "0.22.1", optional = true }
 tracing = { version = "0.1", optional = true }
 subtle = "2.6"
+bytemuck = { version = "1.18", features = ["derive"] }
 
 [features]
 default = ["serde", "parallel"]

Cargo.toml

@@ -48,7 +48,7 @@ Perfect for:
 
 ```toml
 [dependencies]
-imgfprint = "0.4.0"
+imgfprint = "0.4.1"
 ```
 
 ### Feature Flags
@@ -63,13 +63,13 @@ imgfprint = "0.4.0"
 Minimal build (no parallel processing):
 ```toml
 [dependencies]
-imgfprint = { version = "0.4.0", default-features = false }
+imgfprint = { version = "0.4.1", default-features = false }
 ```
 
 With local embeddings (requires ONNX model):
 ```toml
 [dependencies]
-imgfprint = { version = "0.4.0", features = ["local-embedding"] }
+imgfprint = { version = "0.4.1", features = ["local-embedding"] }
 ```
 
 ## Quick Start

README.md

@@ -30,7 +30,7 @@ Add the dependency to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-imgfprint = "0.4.0"
+imgfprint = "0.4.1"
 ```
 
 ### Basic Example (Multi-Algorithm)
@@ -852,7 +852,7 @@ With the `local-embedding` feature:
 
 ```toml
 [dependencies]
-imgfprint = { version = "0.4.0", features = ["local-embedding"] }
+imgfprint = { version = "0.4.1", features = ["local-embedding"] }
 ```
 
 ```rust
@@ -1011,13 +1011,13 @@ Configure the library for your needs:
 ```toml
 [dependencies]
 # Minimal build (no parallel processing)
-imgfprint = { version = "0.4.0", default-features = false }
+imgfprint = { version = "0.4.1", default-features = false }
 
 # Default (serialization + parallel processing)
-imgfprint = "0.4.0"
+imgfprint = "0.4.1"
 
 # With local ONNX inference
-imgfprint = { version = "0.4.0", features = ["local-embedding"] }
+imgfprint = { version = "0.4.1", features = ["local-embedding"] }
 ```
 
 ### Available Features
@@ -1035,7 +1035,7 @@ Enable the `tracing` feature to add performance instrumentation:
 
 ```toml
 [dependencies]
-imgfprint = { version = "0.4.0", features = ["tracing"] }
+imgfprint = { version = "0.4.1", features = ["tracing"] }
 ```
 
 ```rust

USAGE.md

@@ -13,6 +13,40 @@ Legend:
 
 ---
 
+## 0. Next Up: 0.4.1 (UCFP-unblocking patch)
+
+A small, additive patch that unblocks UCFP's persistence story without
+the structural breakage that 0.5.0 needs.
+
+| # | Item | Priority | Effort | Status |
+|---|------|----------|--------|--------|
+| 0.1 | **`pub const FORMAT_VERSION: u32`** at crate root + `MultiHashFingerprint::format_version()` accessor returning the same constant | P0 | S | planned |
+| 0.2 | **`bytemuck::Pod + Zeroable`** derives on `ImageFingerprint` / `MultiHashFingerprint` with `#[repr(C)]` for stable layout | P0 | S | planned |
+| 0.3 | **Zero-copy persistence example** — `bytemuck::cast_slice(&fingerprints)` ↔ `&[u8]` for UCFP's mmap'd index | P0 | S | planned |
+| 0.4 | **Layout-stability test** — `static_assertions::const_assert_eq!(size_of::<MultiHashFingerprint>(), 536)` so any accidental layout drift is caught at compile time | P1 | S | planned |
+
+Why this set: UCFP's `index` crate stores millions of fingerprints. Today
+serializing them goes through serde-roundtrip (slow, allocates).
+`bytemuck::cast_slice` gives a zero-copy `&[u8]` view, mmap-friendly. The
+`FORMAT_VERSION` constant lets UCFP refuse cross-version compares without
+embedding a version field in every fingerprint (which would change layout
+and balloon storage).
+
+Design choice: using full `Pod + Zeroable`. The earlier plan was to use
+`NoUninit + AnyBitPattern + Zeroable` to avoid `Copy`, but in current
+`bytemuck` (1.18+) those traits also require `Copy`. So `Copy` is
+unavoidable if we want any `cast_slice` capability. Trade-off accepted:
+move-by-value memcpys 168 / 536 bytes; `&Fingerprint` borrows in hot
+loops avoid this. If we ever want to drop `Copy`, we'd switch to the
+`zerocopy` crate (different trait shape) — left as a future option.
+
+Not in this patch:
+- Removing the redundant per-algorithm `exact: [u8; 32]` field from inner
+  `ImageFingerprint`s (saves 96 bytes per `MultiHashFingerprint`). It's a
+  layout break and changes `Hash` derivation; deferred to 0.5.0.
+
+---
+
 ## 1. Configurability Completeness
 
 The 0.4.0 release tuned every weight and decode-time guard. What's left

future.md

@@ -83,9 +83,27 @@ impl Default for MultiHashConfig {
 /// Fingerprints are deterministic and comparable across platforms. The structure
 /// includes exact hashing for identical detection and perceptual hashing for
 /// similarity detection with resistance to resizing, compression, and cropping.
+///
+/// # Binary layout
+///
+/// `#[repr(C)]` with no padding bytes (168 bytes total: 32 + 8 + 128). Implements
+/// [`bytemuck::Pod`] / [`bytemuck::Zeroable`] so a `&[ImageFingerprint]` can be
+/// zero-copy cast to `&[u8]` for mmap-based persistence:
+///
+/// ```rust
+/// use imgfprint::ImageFingerprint;
+/// # fn ex(fps: &[ImageFingerprint]) -> &[u8] {
+/// bytemuck::cast_slice(fps)
+/// # }
+/// ```
+///
+/// `Copy` is derived because `bytemuck::Pod` requires it; the trade-off is
+/// that move-by-value silently memcpys 168 bytes. Prefer borrowing
+/// (`&ImageFingerprint`) in hot loops where this matters.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, bytemuck::Pod, bytemuck::Zeroable)]
+#[repr(C)]
 pub struct ImageFingerprint {
     pub(crate) exact: [u8; 32],
     pub(crate) global_hash: u64,
@@ -112,6 +130,17 @@ impl ImageFingerprint {
         &self.exact
     }
 
+    /// Returns the on-disk format version this fingerprint was computed under.
+    ///
+    /// Equal to [`crate::FORMAT_VERSION`]. Persist alongside fingerprint bytes
+    /// (or in a sidecar manifest) and refuse comparison across mismatched
+    /// versions to guard against algorithm-version drift.
+    #[inline]
+    #[must_use]
+    pub const fn format_version() -> u32 {
+        crate::FORMAT_VERSION
+    }
+
     /// Returns the global perceptual hash from the center 32x32 region.
     ///
     /// This hash captures the overall structure of the image and is robust
@@ -187,16 +216,44 @@ impl ImageFingerprint {
 ///
 /// Provides enhanced similarity detection by combining results from multiple
 /// hash algorithms with weighted combination for improved accuracy.
+///
+/// # Binary layout
+///
+/// `#[repr(C)]` with no padding bytes (536 bytes total: 32 + 3 × 168). Implements
+/// [`bytemuck::Pod`] / [`bytemuck::Zeroable`] for zero-copy cast to `&[u8]`.
+/// See [`ImageFingerprint`] for an example.
+///
+/// Stable layout is enforced at compile time via a `const _` size assertion;
+/// any accidental layout drift fails the build.
+///
+/// `Copy` is derived for `bytemuck::Pod` compatibility; move-by-value silently
+/// memcpys 536 bytes. Prefer borrowing (`&MultiHashFingerprint`) in hot loops.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, bytemuck::Pod, bytemuck::Zeroable)]
+#[repr(C)]
 pub struct MultiHashFingerprint {
     pub(crate) exact: [u8; 32],
     pub(crate) ahash: ImageFingerprint,
     pub(crate) phash: ImageFingerprint,
     pub(crate) dhash: ImageFingerprint,
 }
 
+// Layout-stability gate. If anyone accidentally introduces padding or reorders
+// fields in a way that changes the binary size, the build fails here. UCFP and
+// any other consumer relying on bytemuck::cast_slice would otherwise get
+// silently broken artefacts.
+const _: () = {
+    assert!(
+        core::mem::size_of::<ImageFingerprint>() == 168,
+        "ImageFingerprint binary layout drifted"
+    );
+    assert!(
+        core::mem::size_of::<MultiHashFingerprint>() == 536,
+        "MultiHashFingerprint binary layout drifted"
+    );
+};
+
 impl MultiHashFingerprint {
     pub(crate) fn new(
         exact: [u8; 32],
@@ -219,6 +276,17 @@ impl MultiHashFingerprint {
         &self.exact
     }
 
+    /// Returns the on-disk format version this fingerprint was computed under.
+    ///
+    /// Equal to [`crate::FORMAT_VERSION`]. Persist alongside fingerprint bytes
+    /// (or in a sidecar manifest) and refuse comparison across mismatched
+    /// versions to guard against algorithm-version drift.
+    #[inline]
+    #[must_use]
+    pub const fn format_version() -> u32 {
+        crate::FORMAT_VERSION
+    }
+
     /// Returns the AHash-based fingerprint.
     #[inline]
     #[must_use]
@@ -467,4 +535,60 @@ mod tests {
         // Keeps `fp()` referenced so the helper test util doesn't bit-rot.
         let _ = fp(0x1234, 0xABCD);
     }
+
+    #[test]
+    fn format_version_is_one() {
+        assert_eq!(crate::FORMAT_VERSION, 1);
+        assert_eq!(ImageFingerprint::format_version(), 1);
+        assert_eq!(MultiHashFingerprint::format_version(), 1);
+    }
+
+    #[test]
+    fn image_fingerprint_layout_is_stable() {
+        assert_eq!(core::mem::size_of::<ImageFingerprint>(), 168);
+        assert_eq!(core::mem::align_of::<ImageFingerprint>(), 8);
+    }
+
+    #[test]
+    fn multi_hash_fingerprint_layout_is_stable() {
+        assert_eq!(core::mem::size_of::<MultiHashFingerprint>(), 536);
+        assert_eq!(core::mem::align_of::<MultiHashFingerprint>(), 8);
+    }
+
+    #[test]
+    fn image_fingerprint_cast_slice_roundtrips() {
+        let fps = vec![
+            ImageFingerprint::new([1u8; 32], 0xAAAA_BBBB_CCCC_DDDD, [0x1234; 16]),
+            ImageFingerprint::new([2u8; 32], 0xDEAD_BEEF_CAFE_BABE, [0xFEDC; 16]),
+            ImageFingerprint::new([3u8; 32], 0, [0; 16]),
+        ];
+        let bytes: &[u8] = bytemuck::cast_slice(&fps);
+        assert_eq!(bytes.len(), 3 * 168);
+
+        let back: &[ImageFingerprint] = bytemuck::cast_slice(bytes);
+        assert_eq!(back.len(), fps.len());
+        assert_eq!(back, &fps[..]);
+    }
+
+    #[test]
+    fn multi_hash_fingerprint_cast_slice_roundtrips() {
+        let fps = vec![
+            multi([1u8; 32], 0x1111, 0x2222, 0x3333),
+            multi([2u8; 32], 0xAAAA, 0xBBBB, 0xCCCC),
+        ];
+        let bytes: &[u8] = bytemuck::cast_slice(&fps);
+        assert_eq!(bytes.len(), 2 * 536);
+
+        let back: &[MultiHashFingerprint] = bytemuck::cast_slice(bytes);
+        assert_eq!(back.len(), fps.len());
+        assert_eq!(back, &fps[..]);
+    }
+
+    #[test]
+    fn fingerprint_zeroed_is_valid() {
+        // Zeroable means an all-zero bit pattern is a valid value of the type.
+        let z: MultiHashFingerprint = bytemuck::Zeroable::zeroed();
+        assert_eq!(*z.exact_hash(), [0u8; 32]);
+        assert_eq!(z.ahash().global_hash(), 0);
+    }
 }

src/core/fingerprint.rs

@@ -1077,7 +1077,7 @@ mod tests {
 
         let mut single_set = HashSet::new();
         let single = ImageFingerprinter::fingerprint_with(&img1, HashAlgorithm::DHash).unwrap();
-        single_set.insert(single.clone());
+        single_set.insert(single);
         single_set.insert(single);
         assert_eq!(single_set.len(), 1);
     }