A reordered addIndexes of SortingCodecReader inputs writes vectors onto the wrong documents

SortingCodecReader's javadoc suggests re-sorting an index by wrapping its readers and passing them to IndexWriter#addIndexes(CodecReader...). When two or more inputs go into one such call (at least one a SortingCodecReader, built from a Sort or from a Sorter.DocMap such as BPIndexReorderer.reorder's output), the target writer has no index sort (and no input has document blocks without a parent field), and the merge policy's OneMerge#reorder returns a DocMap (misc BPReorderingMergePolicy computes one for every addIndexes merge, unless its reorderer runs out of RAM; an identity DocMap is enough), IndexWriter reorders through a merged view, SlowCompositeCodecReaderWrapper. Its vector iterator numbers ordinals by position while its vectorValue(ord) reads in each input's own ordinal space, and a SortingCodecReader keeps its vectors at their original ordinals. So within each re-sorted input the k-th document in sorted order is written with the vector at original ordinal k: in the repro all 8 documents get another document's float and byte vector, and a deleted document's vector lands on a live one. Nothing throws, CheckIndex reports the index clean, and kNN search ranks by other documents' embeddings until the segment is rebuilt. All 12 10.x releases from 10.0.0 to 10.5.2, 10.6.0 (by reading) and main are affected; it was introduced by #13779, and a two-line change (one line changed, one removed) fixes it.

• Ordinal: a vector's index inside a field's vector values. An iterator's index() gives the ordinal of its current document, and vectorValue(ord) reads that vector.
• SortingCodecReader: a merge-only view of a segment in a new document order. It does not move the vectors: it visits documents in the new order, and its index() returns each document's original ordinal (its javadoc: "index() may skip around, not increasing monotonically").
• Reordered addIndexes: when the target writer has no index sort, addIndexes joins all inputs of one merge into a merged view (SlowCompositeCodecReaderWrapper) and asks OneMerge#reorder for a new document order (unless an input has document blocks but no parent field). BPReorderingMergePolicy computes one for every addIndexes merge with a live document, unless its reorderer runs out of RAM.

1. The merged view's iterator numbers ordinals 0, 1, 2, ... as it walks the documents: ++ord per document (SlowCompositeCodecReaderWrapper.java:342 at ea57360912ed) and ord = current.ordStart - 1 on moving to the next input (:352).
2. Its vectorValue(ord) looks the ordinal up in the input's own ordinal space, sub.vectorValue(ord - sub.ordStart) (:912-920 float, :1011-1019 float16, :1060-1069 byte), with the comment that this random access exists "to support callers like SortingCodecReader that rely on it". That caller is the SortingCodecReader wrapped around the view (item 4); the comment does not speak to sorted inputs of the view, and nothing excludes them.
3. The two agree only if each input's index() equals its iteration position. On-disk segments satisfy that; a SortingCodecReader does not: index() returns docToOrd[doc] and vectorValue(ord) reads the wrapped reader at that ordinal (SortingCodecReader.java:265-290, :323-326).
4. IndexWriter.addIndexesReaderMerge builds SortingCodecReader.wrap(SlowCompositeCodecReaderWrapper.wrap(readers), docMap, null) whenever the writer has no index sort, no input has document blocks without a parent field, and the reorder returns a DocMap (IndexWriter.java:3548-3565). The outer reader records the merged iterator's ordinal for each document, and the codec's merge writes the vector read at that ordinal (current.values.vectorValue(current.index()), KnnVectorsWriter.java:484).
5. Input A re-sorted descending is visited as ids 3, 2, 1, 0 and gets merged ordinals 0, 1, 2, 3. Ordinal 0 is A's original ordinal 0, id 0's vector. So id 3 is written with id 0's vector, id 2 with id 1's, and so on; input B the same. The reorder itself does not matter: an identity DocMap takes the same path.
6. The codec merge code written in the same commit reads each input's own ordinal, current.values.vectorValue(current.index()) (KnnVectorsWriter.java:484, :643). Only the merged view assumes positional ordinals.

Nothing throws with assertions on or off, and CheckIndex reports the new index clean: every stored vector is valid, just on the wrong document.

• Who is exposed. An addIndexes(CodecReader...) merge with two or more inputs, at least one a SortingCodecReader (from SortingCodecReader.wrap(reader, Sort), or from a Sorter.DocMap, for example misc BPIndexReorderer.reorder(...), which returns one), into a writer with no index sort whose merge policy's OneMerge#reorder returns a DocMap for the addIndexes merge (misc BPReorderingMergePolicy, or any custom reorder, even the identity). The default findMerges(CodecReader...) puts all inputs in one merge. A tool that re-sorts or imports segments into a writer configured with BPReorderingMergePolicy would hit it; no such tool is known.
• Executed triggers. Inputs re-sorted by a Sort; two BPIndexReorderer.reorder outputs with no Sort at all; one SortingCodecReader next to a plain input (only the sorted input's vectors move). Float and byte vectors were executed; float16 vectors (main only) use the same iterator and mismatched in the finder's differential harness, but no JUnit covers them.
• Not affected. Two safe, tested in-tree usage patterns (executed; neither is documented as a requirement): a target writer with the same index sort as the inputs (no reorder runs) and one BPIndexReorderer output per addIndexes call (no merged view is built). Regular segment merges over the built-in segment readers, by code reading: their ordinals are positional, and wrapForMerge may not reorder doc IDs; a custom codec or wrapForMerge wrapper with non-positional vector ordinals was not ruled out.
• Opt-in. SortingCodecReader and OneMerge#reorder are @lucene.experimental; BPReorderingMergePolicy is a misc-module class. Nothing else is non-default: the tests pin the default codec and use the test framework's randomized directories.
• Scale and frequency. 8 documents in 2 segments; deterministic (over 10 iterations all 20 bug-test runs failed and all 10 control runs passed). Once on that path, every document with a vector whose input's index() differs from its position in that input's iteration order gets a wrong vector; documents whose ordinal equals their position keep theirs.
• Silent and lasting. No exception, CheckIndex clean; the wrong vectors are written to the new segment, so kNN search and any code that reads vectors back see them until the segment is rebuilt from source data. A code fix stops new damage only.
• Intact. Ids, stored fields, postings and doc values; vectors stayed inside their own input in every executed case.
• Downstream (read, not tested). No BPReorderingMergePolicy in Elasticsearch's code (code search); Solr makes it configurable (apache/solr#2641), but whether any Solr path also feeds SortingCodecReader inputs to addIndexes was not checked; the OpenSearch, Solr and OpenSearch k-NN code searches hit a rate limit.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: vector of id 1 expected:<1.0> but was:<0.0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:577)
       org.apache.lucene.index.TestReorderedAddIndexesOfSortedReaders.testIdentityReorderKeepsVectors(TestReorderedAddIndexesOfSortedReaders.java:97)

• The contract. KnnVectorValues.DocIndexIterator.index(): "return the value index (aka "ordinal" or "ord") corresponding to the current doc" (KnnVectorValues.java:140). The merged iterator's index() names another document's vector.
• The merged view is built to serve SortingCodecReader. "We need to implement fully random-access API here in order to support callers like SortingCodecReader that rely on it" (SlowCompositeCodecReaderWrapper.java:914-915, also :1014-1015, :1063-1064). The caller meant is the SortingCodecReader wrapped around the view, as IndexWriter builds it; the comment does not speak to sorted inputs of the view, but that outer reader only works if the view's ordinals match its vectors, and nothing keeps sorted readers out.
• SortingCodecReader documents both its ordinals and this use. "index() may skip around, not increasing monotonically as iteration proceeds" (SortingCodecReader.java:265-266), and "This can be used to re-sort and index after it's been created by wrapping all readers of the index with this reader and adding it to a fresh IndexWriter via IndexWriter#addIndexes(CodecReader...)" (:48-50).
• OneMerge#reorder only renumbers doc IDs. "Extend this method if you wish to renumber doc IDs. This method will be called when index sorting is disabled on a merged view of the OneMerge" (MergePolicy.java:312-313). An identity DocMap renumbers nothing and still moves the vectors.
• No precondition, no rejection. Nothing documents that addIndexes inputs need positional vector ordinals; validateMergeReader checks an input's sort only when the writer has an index sort (IndexWriter.java:3228).
• History. #13779 (6053e1e3137, 2024) added both halves in one commit; before it the merged view returned the current input's vector at the current document and 9.x SortingCodecReader copied vectors into the new order. None of its 37 inline review comments is on SlowCompositeCodecReaderWrapper or SortingCodecReader, and none says that an input's ordinals must be positional. The codec merge path of the same commit reads each input's index() (KnnVectorsWriter.java:484, :643).
• Why tests missed it. TestSortingCodecReader always gives the target the same index sort (no reorder); TestBPReorderingMergePolicy.testReorderOnAddIndexes adds plain inputs and checks stored fields, never vectors; MockRandomMergePolicy does not reorder addIndexes merges.
• Precedent. Upstream fixed other defects in this merged view as bugs (#14092) and an ordinal-tracking defect of the same kind in KnnVectorsWriter.MergedByteVectorValues (#14992 / #15553).

The strongest "works as designed" case (the intended-behaviour check, the intended-behaviour devil's advocate, and the cross-model lenses): the merged view is package-private and "primarily targeted at merging, not searching"; SortingCodecReader and OneMerge#reorder are @lucene.experimental; the two in-tree usage patterns are safe (a target with the same index sort, one reordered reader per addIndexes call; executed); the trigger sorts the data twice; and ++ord is correct for every on-disk reader.

Why it fails: the failure happens during a merge, the use the view exists for, and the view names SortingCodecReader as a caller to support (as its wrapper). Experimental status allows API changes, not silently wrong data. Neither safe pattern is documented as required; addIndexes is varargs, the default policy puts all inputs in one merge, BPReorderingMergePolicy deliberately reorders addIndexes merges, and nothing rejects or documents against the combination. An identity reorder sorts nothing and still corrupts. What remains on the other side is rarity: an unusual stack of opt-in APIs (and BPReorderingMergePolicy skips the reorder when its reorderer runs out of RAM) and no report since 10.0.0. The likely reply is "real, niche, fix it", not "by design"; no source supports by design.

One option was built and validated; the others are listed with their trade-offs.

SlowCompositeCodecReaderWrapper.MergedDocIterator.nextDoc: ord = current.ordStart + currentIterator.index() instead of ++ord, and remove ord = current.ordStart - 1 (1 changed line, 1 removed line, plus a comment and an assertion). The merged ordinal then names the same vector that the merged vectorValue(ord) reads.

It stays in range: Sorter.DocMap.size() "must be equal to the number of documents" of the reader it sorts, so a SortingCodecReader input reports every ordinal of the reader it wraps and ordStart + index() stays inside the input's [ordStart, ordStart + size()) slot. The added assertion checks that; it held in every run with assertions on. A DocMap that drops documents is outside that contract (flagged by the adjudication, untested); the assertion would catch it.

if (next != NO_MORE_DOCS) {
  // Use the sub's own ordinal: it need not follow the doc order (a SortingCodecReader
  // sub reports the ordinals of the reader it wraps), and vectorValue(ord) reads there.
  ord = current.ordStart + currentIterator.index();   // was: ++ord
  assert ord >= current.ordStart && ord < current.ordStart + current.sub.size();
  return doc = current.docStart + next;
}
...
current = it.next();
currentIterator = currentIterator();
// removed: ord = current.ordStart - 1;

Trade-offs

• One index() call per vector in a reordered merge, next to the vector read itself; no benchmark was run.
• Plain inputs and regular merges over the built-in segment readers get the same ordinals as before (index() equals the position there).
• Prevents new damage only: indexes already written through this path keep the wrong vectors and must be rebuilt.
• Leaves a separate question open (read, not run): with misc BpVectorReorderer as the reorderer, each reorder thread calls vectors.copy() on the merged view (BpVectorReorderer.java:110, :619-624), which copies every input, and Sorting*VectorValues.copy() throws UnsupportedOperationException (SortingCodecReader.java:345-348); its sparse-field path also counts ordinals by position (:735-770). By code reading that combination ends in the exception, with or without this fix, once the merged view is large enough to be split (:208-217); below that the reorder is the identity and this fix applies.

What the checks validated

• Scratch worktree at ea57360912ed (removed afterwards): this doc's test and the finder's misc test fail 2 of 3 each on stock and pass 3 of 3 each with the fix, assertions on and off.
• With the fix, the default lucene/core test task (8,868 tests, 322-325 skipped) and lucene/misc test task (318 tests, 9 skipped), with assertions on and off, and check -x test for both modules pass (0 failures).
• The same patched class as a shadow class: the independent reproducer's 6 tests, the security probe's 3 and the devil's advocate's 3 reach probes pass. The finder's variant without the assertion also passed four upstream BP and wrapper test classes and fixed the bug at the introducing commit.

Copy or remap vectors into the new order, as 9.x did.

Trade-offs

Turns a memory-light merge-only reader into one that buffers or remaps every vector, and leaves the merged view still assuming positional inputs for any future input with non-positional ordinals (for example the on-disk iterator of open PR #15430, read only). Not recommended.

Throw in addIndexes, or skip the reorder, when an input's vector ordinals are not positional.

Trade-offs

Turns silent corruption into an error or a lost reorder, but there is no cheap general way to detect non-positional ordinals, and it blocks a combination the javadocs invite. A stop-gap at most.

• Unit and method. A hunt unit (codec-reader wrappers), 2026-10-26. The finder's randomized differential harness compared SlowCompositeCodecReaderWrapper's merged view, and addIndexes through it with an identity reorder, against the per-input data: 3 runs x 150 iterations with SortingCodecReader inputs allowed. It reported float, byte and float16 vector mismatches (for example 7 float, 41 byte and 3 float16 in one run) only in the runs with SortingCodecReader inputs.
• The model. A small Z3 model of the merged iterator stated the hidden assumption, for inputs of 2 to 4 vectors: with monotone input ordinals no document can be given another document's vector (unsat); with an arbitrary permutation, as a SortingCodecReader allows, one can (sat: a witness exists). The first signal was the random differential, so this counts as a non-formal find.
• Then. A public-API JUnit on the stock jars; a cross-model review by a reviewer from another model family (OpenAI GPT-5.6, read-only, refute and intended lenses); an independent reproducer with its own tests and a 9.x port; a GPT-5.6 root-cause adversary; an intended-behaviour devil's advocate with reach probes; an adjudication (confirmed, high); a history sweep with commit builds; a prior-report search; a security assessment and probe; a registry re-run with fresh seeds; and this doc's own test and fix validation.