From 50d2e547b39102ea8e75f7fc248d8f164f4f5e9c Mon Sep 17 00:00:00 2001 From: Nelson Spence Date: Mon, 15 Jun 2026 11:37:33 -0500 Subject: [PATCH 1/2] docs(rank_io): document why OVFS is not in the metadata-probe path (#232) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A stop-gate review noted that `.ovfs` (RankQuantFastscan) persistence "bypasses the metadata path": `probe_index_metadata` dispatches the four OV*/TV* formats but `OVFS` falls through to the unknown-magic error, with no in-code note that this is deliberate. It IS deliberate: surfacing OVFS in the probe requires a new `IndexKind` variant, and `IndexKind` is not `#[non_exhaustive]`, so adding one is a breaking change — deferred to the 0.8.0 API re-architecture (#232). `.ovfs` files still round-trip via `RankQuantFastscan::{write,load}`; only the metadata-probe path is pending. Add a comment in the dispatch so the deferral reads as intentional, not an oversight. No behaviour change. Signed-off-by: Nelson Spence --- src/rank_io.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/rank_io.rs b/src/rank_io.rs index 00f618e..fb73b53 100644 --- a/src/rank_io.rs +++ b/src/rank_io.rs @@ -365,6 +365,12 @@ pub fn probe_index_metadata(path: impl AsRef) -> io::Result OVRQ_MAGIC | TVRQ_MAGIC => probe_rankquant_metadata(&mut f, file_size_bytes), OVBM_MAGIC | TVBM_MAGIC => probe_bitmap_metadata(&mut f, file_size_bytes), OVSB_MAGIC | TVSB_MAGIC => probe_sign_bitmap_metadata(&mut f, file_size_bytes), + // NOTE: `OVFS` (RankQuantFastscan) is intentionally NOT probed here. + // Surfacing it would need a new `IndexKind` variant, and `IndexKind` is + // not `#[non_exhaustive]`, so adding one is a breaking change — deferred + // to the 0.8.0 API re-architecture (#232). `.ovfs` files still round-trip + // via `RankQuantFastscan::{write,load}`; only this metadata-probe path is + // pending, and an `OVFS` magic falls through to the unknown-magic error. _ => Err(invalid("unknown ordvec index magic")), } } From f0808adfd08fff214d367a288ddaecccc13213d7 Mon Sep 17 00:00:00 2001 From: Nelson Spence Date: Mon, 15 Jun 2026 11:45:55 -0500 Subject: [PATCH 2/2] fix(rank_io): return specific error for OVFS metadata probe (#232) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address gemini review on #242: instead of letting an .ovfs (OVFS / RankQuantFastscan) magic fall through to the generic "unknown ordvec index magic" error in probe_index_metadata — misleading, since the magic *is* recognized — explicitly match OVFS_MAGIC and return an actionable error pointing the caller at RankQuantFastscan::load and the #232 probe deferral. Add a regression test pinning the deferral contract: probing a valid .ovfs file must return the specific unsupported-probe error and must NOT report it as an unknown magic. Signed-off-by: Nelson Spence --- src/rank_io.rs | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/src/rank_io.rs b/src/rank_io.rs index fb73b53..5da76ce 100644 --- a/src/rank_io.rs +++ b/src/rank_io.rs @@ -365,12 +365,19 @@ pub fn probe_index_metadata(path: impl AsRef) -> io::Result OVRQ_MAGIC | TVRQ_MAGIC => probe_rankquant_metadata(&mut f, file_size_bytes), OVBM_MAGIC | TVBM_MAGIC => probe_bitmap_metadata(&mut f, file_size_bytes), OVSB_MAGIC | TVSB_MAGIC => probe_sign_bitmap_metadata(&mut f, file_size_bytes), - // NOTE: `OVFS` (RankQuantFastscan) is intentionally NOT probed here. - // Surfacing it would need a new `IndexKind` variant, and `IndexKind` is - // not `#[non_exhaustive]`, so adding one is a breaking change — deferred - // to the 0.8.0 API re-architecture (#232). `.ovfs` files still round-trip - // via `RankQuantFastscan::{write,load}`; only this metadata-probe path is - // pending, and an `OVFS` magic falls through to the unknown-magic error. + // `OVFS` (RankQuantFastscan) is a recognized magic, but metadata probing + // is intentionally NOT wired up here yet: surfacing it would need a new + // `IndexKind` variant, and `IndexKind` is not `#[non_exhaustive]`, so + // adding one is a breaking change — deferred to the 0.8.0 API + // re-architecture (#232). `.ovfs` files still round-trip via + // `RankQuantFastscan::{write,load}`; only this metadata-probe path is + // pending. Return a specific, actionable error rather than letting it + // fall through to the generic unknown-magic case (which would be + // misleading, since the magic *is* known). + OVFS_MAGIC => Err(invalid( + "OVFS (RankQuantFastscan) metadata probing is not supported in this \ + version; load the index with RankQuantFastscan::load (tracked in #232)", + )), _ => Err(invalid("unknown ordvec index magic")), } } @@ -1606,4 +1613,30 @@ mod tests { assert_eq!(e.kind(), std::io::ErrorKind::InvalidData); assert!(!p3.exists(), "rejected write must not create a file"); } + + // Probing a valid `.ovfs` file returns a specific, actionable error — NOT the + // generic "unknown ordvec index magic" (which would be misleading, since the + // magic *is* recognized). Metadata-probe support for OVFS is deferred to #232; + // this pins the deferral contract so it can't silently regress to the generic + // case. See `probe_index_metadata`'s `OVFS_MAGIC` arm. + #[test] + fn probe_rejects_ovfs_with_specific_unsupported_error() { + use super::{probe_index_metadata, write_fastscan}; + let (dim, n) = (8usize, 4usize); + let payload = vec![0u8; 128]; + let p = temp_index_path("ovfs_probe"); + write_fastscan(&p, dim, n, &payload).unwrap(); + let err = probe_index_metadata(&p); + assert_err_contains( + err, + "OVFS (RankQuantFastscan) metadata probing is not supported", + ); + // It must NOT be reported as an unknown magic. + let again = probe_index_metadata(&p).unwrap_err().to_string(); + assert!( + !again.contains("unknown ordvec index magic"), + "OVFS is a recognized magic; probe must not report it as unknown, got {again:?}" + ); + let _ = std::fs::remove_file(&p); + } }