docs(qdrant): fix multivector README distance claims, round 4

Round 4 found the round-3 README fix was wrong again, in a new way -- third
consecutive round the same paragraph has been wrong:

- The sentence claimed cosine/angular/euclid all "hard-error at load" via the
  normalization guard. False for euclid specifically: needs_normalization()
  only matches cosine/angular, so euclid never trips that guard at all. The
  only thing that rejects euclid is map_qdrant_distance, called solely from
  Engine::configure()'s create-collection paths -- which --skip-upload skips
  entirely. So a euclid-registered multivector dataset run with --skip-upload
  against an existing collection silently passes both checks, contrary to
  what the README claimed. Rewrote to separate the two mechanisms: the
  normalization guard (cosine/angular/omitted, fires on every read path
  including --skip-upload) from collection-creation-time rejection of any
  other unrecognized string (configure()-only, bypassed by --skip-upload).
- A round-3 fix to the test doc comment replaced a unit error ("docs" vs "KB")
  with a magnitude error: the fixture is actually ~56 KB (150 docs x mean 6
  tokens x 16 dims x 4 bytes), not "well under a KB" -- and ~350x under the
  20000 KB threshold, not "several orders of magnitude". Corrected with the
  actual computed size.
- Also: reworded write_multivector_project_with_distance's doc comment,
  which claimed a test purpose (exercising the guard against cosine) that
  the actual test doesn't use it for; and added the dot-only-ground-truth
  caveat directly to the README paragraph, not just to generate_multivector's
  doc comment, so a reader hits it before registering an l2 dataset.

All via 9-way agent consensus, verified live (text-only changes; reran both
multivector integration tests to confirm no regression).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: fcostaoliveira

README.md

@@ -918,14 +918,21 @@ neighbours.jsonl # ground truth: one JSON array of ids per query line
 
 Register it in `datasets/datasets.json` with `"type": "multivector"` and the
 per-token `vector_size`/`distance`. **Only `dot`/`l2` are accepted** (`ip`/
-`euclidean` also work, as synonyms) — `cosine`/`angular`/`euclid` (and an
-*omitted* `distance`, which defaults to `cosine`) hard-error at load, since
+`euclidean` also work, as synonyms). `cosine`/`angular` (and an *omitted*
+`distance`, which defaults to `cosine`) are rejected by a normalization guard
+that runs on every read path — including under `--skip-upload` — since
 neither the reader nor the generator apply per-token normalization yet; this
 is the most likely first-attempt failure, since omitting `distance` is common
-elsewhere in this file. Ground truth for a multivector dataset MUST
-be a genuine brute-force MaxSim ranking, not a heuristic — see
-`generate_multivector`'s doc comment in `src/synthetic.rs` for why the hybrid
-generator's "planted" shortcut does not carry over. The end-to-end path
+elsewhere in this file. Any other string (e.g. a typo'd `euclid`) is rejected
+only by Qdrant's collection creation, which `--skip-upload` bypasses entirely
+— such a value silently passes through unrejected in that mode. Ground truth
+for a multivector dataset MUST be a genuine brute-force MaxSim ranking, not a
+heuristic — see `generate_multivector`'s doc comment in `src/synthetic.rs` for
+why the hybrid generator's "planted" shortcut does not carry over. That ground
+truth is always scored with raw dot-product MaxSim regardless of the declared
+`distance` — correct for `dot` (what this repo ships) but silently wrong for
+`l2`, which would need its own Euclid-MaxSim ground truth that
+`generate_multivector` does not produce. The end-to-end path
 (collection creation, ragged upload, and a `query_points` search using the
 `"colbert"` vector) is covered by
 `tests/integration_qdrant.rs::test_binary_qdrant_multivector`, which also

tests/common/mod.rs

@@ -1734,9 +1734,12 @@ pub fn write_multivector_project(
 }
 
 /// Same fixture as [`write_multivector_project`], but with a caller-chosen
-/// `distance` — used to exercise the normalization guard against a
-/// cosine/angular (or omitted) multivector dataset, which this repo does not
-/// yet support (#316 review round 2).
+/// `distance`. NOTE: as of #316, this parameter is only ever exercised with
+/// `"dot"` (via [`write_multivector_project`]) — the live cosine-guard
+/// integration test needs to re-register an ALREADY-UPLOADED corpus under a
+/// different distance mid-test, which this function can't do (it always
+/// allocates a fresh corpus/tempdir), so that test hand-writes its own
+/// second `datasets.json` instead of calling this with `"cosine"`.
 pub fn write_multivector_project_with_distance(
     dataset_name: &str,
     engine_configs_json: &str,

tests/integration_qdrant.rs

@@ -643,12 +643,13 @@ fn test_binary_qdrant_sparse() {
 /// real engine (a "colbert" named vector with `multivector_config`/`MaxSim`,
 /// upsert of ragged per-doc token vectors, and a `query_points` search using
 /// that named vector), then assert recall against the brute-force MaxSim
-/// ranking. `indexing_threshold` is a KB-of-vector-data size, not a doc count —
-/// at this fixture's size (150 docs of a handful of 16-dim token vectors each,
-/// well under a KB total) Qdrant's collection stays several orders of
-/// magnitude under the default HNSW `indexing_threshold` (20000 KB), so no
-/// segment is ever indexed and the search is an exact full scan, not ANN —
-/// recall must therefore be exact, not merely above a tolerant floor.
+/// ranking. `indexing_threshold` is a KB-of-vector-data size, not a doc count
+/// — at this fixture's size (150 docs, mean 6 tokens each of 16-dim f32
+/// vectors, ≈56 KB of vector data total) Qdrant's collection stays roughly
+/// 350x (~2.5 orders of magnitude) under the default HNSW `indexing_threshold`
+/// (20000 KB), so no segment is ever indexed and the search is an exact full
+/// scan, not ANN — recall must therefore be exact, not merely above a
+/// tolerant floor.
 #[test]
 fn test_binary_qdrant_multivector() {
     wait_for_qdrant();