Rust crate as a downstream dependency: SearchResults derives nothing, search() has no non-panicking form, MSRV over-declared by 9 releases

[RyanCodrai]

Found by bug-hunt wave 29 (crate-as-library lens — the cargo add turbovec experience). All compiled against the crate as a path dependency.

1. HIGH — SearchResults implements no traits at all. turbovec/src/lib.rs:185 has no #[derive(...)], while every other public type has Debug (TurboQuantIndex lib.rs:127, IdMapIndex id_map.rs:83) and all three error enums have Debug + Clone + PartialEq plus Error/Display.

error[E0277]: `SearchResults` doesn't implement `Debug`
error[E0277]: the trait bound `SearchResults: Clone` is not satisfied

A downstream struct holding one can't #[derive(Debug)], dbg!(results) fails, assert_eq! in a user's test fails, and it can't be cached or cloned — on the type every search returns. #[derive(Debug, Clone, PartialEq)] is a one-line fix.

Verified good by the same probe: TurboQuantIndex and IdMapIndex are Send + Sync + Debug, Arc<RwLock<TurboQuantIndex>> compiles, and all three error enums satisfy Error + Send + Sync + 'static (anyhow/thiserror work) and are #[non_exhaustive].

2. HIGH — search has no non-panicking form, though the Python bindings have one. lib.rs:608/626 panic on a query buffer that isn't a multiple of dim (assert_eq! at :645) and on any non-finite or huge coordinate (explicit panic! at :653); id_map.rs:347 panics on an allowlist id not in the index. Meanwhile turbovec-python/src/lib.rs:781-802 pre-validates the same three conditions and raises ValueError/KeyError. So Python callers get recoverable errors and Rust callers get an aborted request thread. The add path got the typed-error treatment (add_2d -> Result<_, AddError>); the search path didn't. A service taking query vectors or filter id-lists from users must hand-roll first_invalid_coord + length + contains checks per call, duplicating logic that already exists in the binding. Gap: no try_search/search_checked -> Result<SearchResults, SearchError>. (Related to #318, which covers the allowlist panics specifically.)

3. MEDIUM — declared MSRV 1.89 is ~9 releases higher than the crate needs, locking out users on 1.85–1.88 for no reason. turbovec/Cargo.toml:5. Verified by building:

cargo +1.83 build -p turbovec --ignore-rust-version  -> Finished
cargo +1.81 build -p turbovec --ignore-rust-version  -> Finished
cargo +1.83 check -p turbovec --all-targets          -> Finished (warnings only)

Newest std API used is div_ceil/next_multiple_of (1.73) and OnceLock (1.70); the real floor is rayon's 1.80. pyo3 0.29 and numpy 0.29 both declare rust-version = "1.83", so the python crate doesn't force it either. Cargo hard-fails (rustc 1.83.0 is not supported by … requires rustc 1.89), and the CI leg (ci.yml:60) only proves the declared value builds — it can never catch an over-declaration.

4. MEDIUM — docs.rs will render with 13 rustdoc warnings including 2 dead links, and RUSTDOCFLAGS="-D warnings" makes the doc build fail outright: lib.rs:746 unresolved link to add (should be Self::add); search.rs:92 unresolved block_pair_has_allowed; search.rs:91 and rotation.rs:100 link public docs to private items (render as plain text); io.rs ×6 ambiguous [`write`] (function vs write! macro — needs [`write()`]); id_map.rs:188-190 3× redundant explicit link target.

5. MEDIUM — 79% of the dependency tree exists to evaluate a Beta distribution. statrs = "0.17" is used at exactly three sites (codebook.rs:24,53,65 for Beta::cdf/pdf; encode.rs:461,463 for inverse_cdf), all symmetric Beta(a, a). cargo tree -p turbovec --edges normal = 38 crates, 30 of them under statrs — all of nalgebra 0.32, matrixmultiply, simba, num-complex/rational/bigint, rand_distr, and a syn/quote/proc-macro2 chain (a serialized build-graph choke point). That's a linear-algebra stack compiled by every downstream user so the codebook can call an incomplete-beta function, and it undercuts the "no native dependency" pitch — the ceremony moved from linker flags to ~30 s of cold-build time. A ~60-line regularized-incomplete-beta plus bisection inverse would drop the tree from 38 to 8. There's also no [features] section at all, so nobody can opt out. (See #346: this same dependency is an unpinned format-determinism hazard.)

6. MEDIUM — IdMapIndex::search returns a bare tuple while TurboQuantIndex::search returns a typed struct. id_map.rs:319 returns (Vec<f32>, Vec<u64>) with no nq/k, so the caller must reconstruct the stride as scores.len() / nq — the exact footgun SearchResults.k exists to prevent on the other index. Probe: m.search(queries, 10) on a 3-vector index returned ids.len() == 6 for 2 queries, i.e. stride 3, not 10; a user writing the obvious &ids[q*10..] gets a panic or wrong rows. IdMapIndex also exposes no iterator over its ids/slots.

7. MEDIUM — examples/downstream-smoke/ covers roughly a third of what a real embedder does. It exercises new → add → prepare → search → write → load on TurboQuantIndex only. Never exercised, and so never protected on the downstream build path: IdMapIndex entirely (the API most apps want); any error path (add_2d's Result, matching AddError, #[non_exhaustive] wildcard arms); any mutation (swap_remove, remove) or add-after-search cache invalidation; Send/Sync and Arc<RwLock<…>> — the crate's headline concurrency claim at lib.rs:22-35 is untested from downstream; to_bytes/from_bytes, write_with_durability + io::Durability, search_with_mask, from_parts; and k > len clamping (it uses K=5, N_DB=256, so it never sees results.k != K). Adding trait assertions (fn assert<T: Send + Sync + Debug>()) to this file would have caught finding 1 mechanically.

Informational: lib.rs:44's compile_error!("turbovec requires a 64-bit target") rules out wasm32 entirely, with a documented rationale (unchecked usize arithmetic). Not gratuitous, but a downstream app with a wasm target gets a hard failure in a dep it can't patch.

🤖 Generated with Claude Code

[github-actions]

Claude encountered an error after 1s —— View job

---

I'll analyze this and get back to you.

[RyanCodrai]

Finding 3 (MSRV over-declaration) is REFUTED — do not act on it

Investigated while fixing findings 1 and 2 in PR #403. The claim does not hold, and the reason is worth recording because both the original claim and the triage's doubt about it were aimed at the wrong thing.

The 1.83 result does reproduce on arm64 — with rust-version genuinely lowered in both manifests, no --ignore-rust-version, --locked --all-targets: it compiles.

But it does not compile for the target CI actually builds:

cargo +1.83 check -p turbovec --target x86_64-unknown-linux-gnu
  error[E0658]: use of unstable library feature 'stdarch_x86_avx512'   (×153)
  error[E0308]: _mm512_i32gather_ps signature changed at stabilization
  could not compile due to 153 previous errors

ci.yml records that the 1.89 bump was for AVX-512 intrinsics, and those kernels are #[cfg(target_arch = "x86_64")] — never compiled on ARM at all. So an arm64 check cannot see the constraint that sets the MSRV. 1.89 is correct and load-bearing.

Two corrections to the triage in #374

1. TRIAGE: clustered synthesis of the ~70 bug-hunt issues (#284-#373) with a fix-first ordering #374 doubted this finding because it was "verified with --ignore-rust-version, the very flag that suppresses the check being tested". That instinct was right to doubt it but wrong about the mechanism: --ignore-rust-version only suppresses cargo's manifest metadata check, not the compiler. A crate that genuinely needs 1.89 still fails to compile under 1.83 with that flag set. The operative error was architecture, not the flag.

2. This issue also states that the CI MSRV leg "can never catch an over-declaration". Not so here: that leg reads rust-version from the manifest and runs on x86_64, so it would have caught a genuine over-declaration. It is the local arm64 check that cannot.

The general lesson

This is the third instance today of an arm64-only verification reaching a confident wrong conclusion about x86 behaviour. The others: three clippy lint classes that are 0 findings on arm64 and 2–3 on x86_64 because they sit inside #[cfg(target_arch = "x86_64")] blocks; and a clippy validation that was silently running as aarch64 because the first pass had no --target.

Anything in this repo that reasons about compilation, lints, or intrinsics needs --target x86_64-unknown-linux-gnu explicitly before the conclusion is trustworthy.

Findings 1 and 2 are fixed in #403. Findings 4–7 remain open.

[RyanCodrai]

Narrowing after re-verification against main 60c6114. Findings 1 and 2 are fixed by #403; five remain.

FIXED:

• 1 — #[derive(Debug, Clone, PartialEq)] on SearchResults (turbovec/src/lib.rs:419), with a documented rationale for omitting Eq/Hash on a float-carrying type.
• 2 — try_search (lib.rs:1224) and try_search_with_mask (lib.rs:1304); IdMapIndex::search_with_allowlist (id_map.rs:426) now returns Result.

STILL OPEN — this is what the issue now covers:

• 3 MSRV over-declaration. turbovec/Cargo.toml:5 and turbovec-python/Cargo.toml:5 are both rust-version = "1.89". cargo +1.83 build -p turbovec --ignore-rust-version → Finished; cargo +1.81 → Finished. Real floor is still rayon's 1.80, so "over-declared by 9 releases" is unchanged and accurate.
• 4 rustdoc under -D warnings: RUSTDOCFLAGS="-D warnings" cargo doc -p turbovec --no-deps → error: could not document 'turbovec', 16 errors — up from the 13 originally reported, because perf: single-query pool gate moves from 8192 to 32768 vectors (#336(3)); IdMapIndex::prepare() warms the id map (#348) #405 added a prepare→Self::ids private-item link. Breakdown: 1 unresolved link to add, 3 private-item links, 5 redundant explicit link targets, 6 ambiguous [`write`] in io.rs.
• 5 statrs = "0.17" (turbovec/Cargo.toml:26) with the nalgebra/simba/num-* chain intact; no [features] section to make it optional.
• 6 IdMapIndex::search (id_map.rs:406) still returns a bare (Vec<f32>, Vec<u64>) with no nq/k.
• 7 examples/downstream-smoke/src/main.rs is still 66 lines covering only new → add → prepare → search → write → load on TurboQuantIndex, K=5/N_DB=256. No IdMapIndex, no error paths, no Send/Sync/Arc<RwLock<..>> assertions, no to_bytes/from_bytes, no mask, no mutation, and it never checks results.k != K.

[RyanCodrai]

Finding 3 re-measured on both architectures: 1.89 is the exact floor

Re-verified all three title findings against main (fc67831) from a separate cargo project that path-deps the crate. 1 and 2 are fixed (#[derive(Debug, Clone, PartialEq)] at lib.rs:419; try_search / try_search_with_mask / IdMapIndex::search_with_allowlist all return Result, and every one of the panic conditions this issue named comes back as Err from a downstream caller).

Finding 3 does not hold. The "still open, unchanged and accurate" narrowing above repeats the same arm64-only measurement the earlier comment already refuted, so here is the full grid — cargo check -p turbovec --locked --all-targets:

toolchain	--target x86_64-unknown-linux-gnu	native aarch64
1.83	153 errors	Finished
1.88	151 errors	—
1.89	Finished	Finished

1.88 is the number that settles it: the release immediately below the declared MSRV does not compile, so 1.89 is not merely defensible, it is the minimum. Errors are stdarch_x86_avx512 unstable-feature use, the unstable avx512bw target feature at search.rs:603, and two intrinsics that changed signature at stabilization (_mm512_loadu_si512, _mm512_i32gather_ps at rotation.rs:449-450).

Also checked rather than assumed: the locked pyo3 0.29.0 and numpy 0.29.0 both declare rust-version = "1.83", so the Python crate's dependencies do not set the floor either.

One clause in the original report is right and the correction to it above is not: the msrv leg builds the declared toolchain, which catches an under-declaration but cannot catch an over-declaration — that needs a check that the release below fails.

#446 records the measurement beside rust-version in both manifests (comment-only) so this does not get re-derived a fourth time. Findings 4–7 are untouched, so that PR says Refs, not Closes.

🤖 Generated with Claude Code

[RyanCodrai]

Findings 1-3 are resolved or measured false (see #446 and the evidence grid above); findings 4, 6 and 7 are fixed in #448. Finding 5 (statrs build cost) is all that remains, and it is a maintainer call: 30 of 38 crates and 6.7s of a 10.4s cold release build come from the statrs subtree, but the remedy is a numerics change to the core encoder — Beta::inverse_cdf sets tqplus_shift/tqplus_scale, which are stored in every file and pinned by tests/encode_fingerprint.rs — so replacing it can silently invalidate existing indexes. Labelled for your decision.