Lucene: correct MAX_ITOPK docs, reference native hang issue

The javadoc and README claimed native CAGRA rejects any oversized
itopk_size/searchWidth combination with a clear exception. Measurement
shows that only holds below a threshold: above roughly iTopK 1e9 the
native hash-table sizing loop fails to terminate and the search hangs
instead of erroring. Correct that claim, stop implying MAX_ITOPK is a
usable maximum, and point at #2523 which tracks the native defect.

Documentation only; no behaviour change.

Signed-off-by: Shaunak Kapur <shaunakk@nvidia.com>

Author: shaunakkapur

java/cuvs-lucene/README.md

@@ -107,15 +107,21 @@ and the rest of the build parameters are derived from the heuristic's output.
 **Only the lower bound of 1 and the `SINGLE_CTA` `iTopK` maximum of 512 are genuine native
 limits.** `MAX_ITOPK` (`Integer.MAX_VALUE`) is simply the largest value representable by the
 public Java API, and `MAX_SEARCH_WIDTH` (4,194,303) only keeps CAGRA's result buffer within its
-unsigned 32-bit indexing limit — neither is a promise that native CAGRA supports every value up
-to that ceiling. The true upper limit for a given search depends on the resolved CAGRA algorithm,
-`max_iterations`, graph degree, filtering, and available GPU memory. In particular, `MULTI_CTA`
-(which a normal one-query `AUTO` search resolves to) sizes an internal traversal hash table from
-`search_width`, `iTopK`, `max_iterations`, and the graph degree, and native CAGRA rejects
-combinations that exceed that table's capacity with a clear exception. This class does not
-replicate that check — `max_iterations` is itself auto-derived from the graph degree and dataset
-size, values not known at query-construction time — so out-of-range combinations under `MULTI_CTA`
-(and other non-`SINGLE_CTA` algorithms) are caught by native CAGRA at search time, not by this API.
+unsigned 32-bit indexing limit. Neither is a promise that native CAGRA supports every value up
+to that ceiling, and in practice values anywhere near `MAX_ITOPK` are not usable. The true upper
+limit for a given search depends on the resolved CAGRA algorithm, `max_iterations`, graph degree,
+filtering, and available GPU memory. In particular, `MULTI_CTA` (which a normal one-query `AUTO`
+search resolves to) sizes an internal traversal hash table from `search_width`, `iTopK`,
+`max_iterations`, and the graph degree. This API does not replicate that calculation, since
+`max_iterations` is itself auto-derived from the graph degree and dataset size, values not known
+at query-construction time, so out-of-range combinations are caught by native CAGRA at search
+time rather than here.
+
+Note that native CAGRA only reports some of those combinations cleanly. Moderately oversized
+values raise a clear exception, but above roughly `iTopK` 1e9 the native hash-table sizing loop
+fails to terminate and the search hangs instead of returning an error
+([#2523](https://github.com/NVIDIA/cuvs/issues/2523)). Treat these constants as representational
+ceilings only, and size `iTopK`/`searchWidth` to what the workload actually needs.
 
 The query uses an effective `iTopK` equal to the greater of the configured value and the requested
 Lucene `k`; for `SINGLE_CTA`, this effective value is re-validated against the 512 limit again once

java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/GPUKnnFloatVectorQuery.java

@@ -77,14 +77,19 @@ public class GPUKnnFloatVectorQuery extends KnnFloatVectorQuery {
   /**
    * Largest intermediate-result count representable by the public Java API.
    *
-   * <p>This is a representational limit only, not a guarantee that every value up to this bound
-   * is supported for every search. Native CAGRA sizes internal traversal hash tables from a
-   * combination of itopk_size, search_width, max_iterations, and (for MULTI_CTA, which a normal
-   * one-query {@code AUTO} search resolves to) the graph degree and dataset size — none of which
-   * are all known at query-construction time. Combinations that exceed native CAGRA's hash-table
-   * capacity are rejected by native CAGRA itself with a clear exception (see {@link
-   * Utils#handleThrowable}); this class does not attempt to replicate that dataset- and
-   * algorithm-dependent sizing logic.
+   * <p>This is a representational limit only. It is emphatically not a supported maximum: values
+   * anywhere near it are rejected by native CAGRA in practice. Native CAGRA sizes internal
+   * traversal hash tables from a combination of itopk_size, search_width, max_iterations, and
+   * (for MULTI_CTA, which a normal one-query {@code AUTO} search resolves to) the graph degree
+   * and dataset size, none of which are all known at query-construction time, so this class does
+   * not attempt to replicate that sizing logic.
+   *
+   * <p>Moderately oversized combinations are rejected by native CAGRA with a clear exception (see
+   * {@link Utils#handleThrowable}). Very large values are not: above roughly 1e9, native CAGRA's
+   * hash-table sizing loop fails to terminate and the search hangs instead of returning an error.
+   * See <a href="https://github.com/NVIDIA/cuvs/issues/2523">#2523</a>. Callers should treat
+   * itopk_size as bounded by what their algorithm and dataset actually support, not by this
+   * constant.
    */
   public static final int MAX_ITOPK = Integer.MAX_VALUE;
 

java/cuvs-lucene/src/test/java/com/nvidia/cuvs/lucene/TestNativeSearchPlanBoundaryRejection.java

@@ -40,11 +40,12 @@
  * dataset size -- so this test does not need to reproduce native CAGRA's {@code max_iterations}
  * auto-derivation to reliably trigger the rejection.
  *
- * <p>This class does not cover an oversized {@link GPUKnnFloatVectorQuery#MAX_ITOPK} the same
- * way: empirically, {@code iTopK = Integer.MAX_VALUE} does not fail fast like an oversized {@code
- * searchWidth} does -- it hangs inside the native call indefinitely instead of returning an
- * error, which would make a test asserting on it unsafe to run in CI (no bounded timeout reliably
- * recovers a thread stuck in native code). That hang is itself worth separate investigation.
+ * <p>This class deliberately does not cover an oversized {@link GPUKnnFloatVectorQuery#MAX_ITOPK}
+ * the same way. Above roughly 1e9, native CAGRA's hash-table sizing loop fails to terminate and
+ * the search hangs rather than returning an error, so a test asserting on it would not be safe to
+ * run in CI (no bounded timeout reliably recovers a thread stuck in native code). That is tracked
+ * as a native bug in <a href="https://github.com/NVIDIA/cuvs/issues/2523">#2523</a>; the clean
+ * rejection exercised here is the behaviour for the range below that threshold.
  */
 @SuppressSysoutChecks(bugUrl = "")
 public class TestNativeSearchPlanBoundaryRejection extends LuceneTestCase {