With soft deletes, a merge wrapper that drops documents breaks the merged segment's soft-delete count

OneMerge#wrapForMerge is documented as the place to "add/remove fields or documents" before a merge, for example to drop expired documents. When the index also has a soft-deletes field, the merge must record how many soft-deleted documents the new segment still holds. For a wrapped segment with hard deletes, IndexWriter.mergeMiddle counts them; for one without hard deletes it subtracts, getSoftDelCount() - wrappedReader.numDeletedDocs(), which is right only if the wrapper never hides a live document. With nothing soft-deleted, a wrapper that drops one expired document gives -1 and forceMerge(1) throws invalid softDelCount=-1 (maxDoc=2); the failure is a tragic event that closes the IndexWriter and rolls back its uncommitted changes, and a reopened writer fails the same way. Under SoftDeletesRetentionMergePolicy with one retained soft-deleted document the merge succeeds (assertions off) but records 0 soft deletes instead of 1: numDocs, IndexSearcher#count and getDocStats().numDocs say 3 while 2 documents are live, CheckIndex at level 2 reports actual soft deletes: 1 but expected: 0, and once the document is no longer retained the next merge of that segment throws invalid softDelCount=-1 (maxDoc=3) and closes the writer. Searches through the writer's readers stay right. The same merge works without a soft-deletes field, or when the segment happens to hold one unrelated hard delete. The shortcut came with LUCENE-8569 (2018); releases 7.4.0-7.6.0 counted correctly, every release from 7.7.0 to 10.6.0 (10.6.0 by reading) and main is affected. It needs the application's own document-dropping merge wrapper, so default configurations are not affected.

• Soft deletes: with IndexWriterConfig.setSoftDeletesField("soft"), softUpdateDocument (or updateDocValues on that field) hides a document by giving it a doc value in the soft-deletes field instead of marking it deleted. Each segment stores how many such documents it holds (softDelCount); the readers the writer hands out compute numDocs as maxDoc - delCount - softDelCount.
• Merge wrapper: MergePolicy.OneMerge#wrapForMerge may wrap each segment's reader before the merge "in order to add/remove fields or documents" (MergePolicy.java:301-309); OneMergeWrappingMergePolicy is the stock way to install one. A wrapper that returns fewer live documents drops them from the merged segment.
• SoftDeletesRetentionMergePolicy: a wrapper that does the opposite, it revives soft-deleted documents that match a retention query so they survive the merge.

1. IndexWriter.mergeMiddle wraps each reader (IndexWriter.java:5497). With soft deletes and a wrapped reader (:5499-5500) it must compute the soft deletes that survive.
2. With hard deletes it counts. If the segment has hard deletes (:5504), countSoftDeletes (:5427-5452) walks the soft-deletes doc values and counts the documents still live in the wrapped reader. Right for any wrapper.
3. Without hard deletes it subtracts (:5530-5535): getSoftDelCount() - wrappedReader.numDeletedDocs(), with the assertions "carry-over soft-deletes must be positive" and a recount check. If the segment has s soft-deleted documents and the wrapper revives r and hides k live ones, numDeletedDocs is s - r + k, so the result is r - k instead of r. Right only when k = 0.
4. The total is stored with merge.info.setSoftDelCount(...) (:5593). A negative total throws IllegalArgumentException("invalid softDelCount=...") (SegmentCommitInfo.java:384-388); a too-low total is committed. Only the total is checked at run time: with assertions off, one segment's negative carry-over can hide behind another segment's positive count.
5. A failed merge closes the writer. The exception escapes IndexWriter.merge, whose catch (Throwable t) calls tragicEvent(t, "merge") (IndexWriter.java:5109-5113); maybeCloseOnTragicEvent then runs rollbackInternal (:6098-6105). The writer drops everything since its last commit and closes; every later call throws AlreadyClosedException. Under the default ConcurrentMergeScheduler the merge thread does the same and forceMerge(1) throws IllegalStateException: this writer hit an unrecoverable error; cannot complete forceMerge (:2286-2289).
6. What reads it. In the writer's readers (DirectoryReader.open(IndexWriter)) and IndexWriter#getDocStats(), numDocs is derived from the stored count (PendingDeletes.java:242-250), and IndexSearcher#count(MatchAllDocsQuery) returns numDocs per leaf (search/MatchAllDocsQuery.java:57-58), while live docs are rebuilt from the doc values, so their searches stay right. A SoftDeletesDirectoryReaderWrapper over a directory reader recounts from the doc values (SoftDeletesDirectoryReaderWrapper.java:142-147) and, with assertions off, reports the right count. CheckIndex compares the stored and the counted value (CheckIndex.java:4941-4947) only at level 2 or higher (:1114); neither the command-line default (level 1) nor an API CheckIndex without setLevel (level 0) runs that check.
7. The next merge. Once the retention query stops matching, the wrapper hides the soft-deleted document again and the shortcut computes 0 - 1 = -1 from the too-low stored count: that merge throws and closes the writer.

With assertions on, every bug row fails at IndexWriter's own assertion instead (carry-over soft-deletes must be positive, or soft-deletes count mismatch expected: 0 but actual: 1), which closes the writer too. A bounded-exhaustive run on the real code covers 584 combinations (segments of 1-3 documents, each live, soft-deleted or hard-deleted, and a wrapper that keeps, removes or revives each one; reviving a hard-deleted document is excluded, so 584 of 819). It fails in exactly the 103 cases where the segment has no hard deletes and the wrapper removes a live document, and in none of the other 481. With assertions off 74 of the 103 throw and 29 commit a wrong count; with assertions on all 103 throw.

• Who. Applications that set a soft-deletes field and install their own merge policy whose OneMerge#wrapForMerge hides live documents, for example dropping expired documents at merge time through OneMergeWrappingMergePolicy (@lucene.experimental), alone or under SoftDeletesRetentionMergePolicy. The production overrides of wrapForMerge in Lucene revive (SoftDeletesRetentionMergePolicy) or delegate (IndexWriter, misc's BPReorderingMergePolicy), so default configurations are not affected.
• Trigger. Deterministic whenever a merge covers a segment without hard deletes and the wrapper hides at least one live document in it; the introducing commit calls segments without hard deletes "the common case". No scale, concurrency or special data.
• Effect. Loud form: the merge throws and, as a tragic event, closes the IndexWriter: uncommitted changes are rolled back, every later call throws AlreadyClosedException, and a reopened writer closes again on its next merge of the same segments (also under the default ConcurrentMergeScheduler). Silent form (assertions off, as in production, with a retention policy): the committed segment records too few soft deletes; the writer's document counts over-count by the number of hidden documents, CheckIndex at level 2 or higher reports corruption, and the next merge of that segment throws and closes the writer once the retained documents are no longer retained. Searches through the writer's readers still return only live documents; no committed document is lost or revived. With assertions on, every form fails at IndexWriter's own assertion, which closes the writer too.
• How rare. A judgement: the combination is uncommon. Apache Solr main has a wrapForMerge that drops documents but does not use soft deletes; GitHub searches of Elasticsearch, OpenSearch and Solr for the symptom strings return nothing; other downstream merge policies were not surveyed.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: carry-over soft-deletes must be positive
       org.apache.lucene.index.IndexWriter.mergeMiddle(IndexWriter.java:5533)
       org.apache.lucene.index.IndexWriter.merge(IndexWriter.java:5081)
       org.apache.lucene.index.IndexWriter$IndexWriterMergeSource.merge(IndexWriter.java:6884)
       org.apache.lucene.index.SerialMergeScheduler.merge(SerialMergeScheduler.java:38)
       org.apache.lucene.index.IndexWriter.executeMerge(IndexWriter.java:2451)
       org.apache.lucene.index.IndexWriter.maybeMerge(IndexWriter.java:2446)
       org.apache.lucene.index.IndexWriter.forceMerge(IndexWriter.java:2281)
       org.apache.lucene.index.IndexWriter.forceMerge(IndexWriter.java:2229)
       org.apache.lucene.index.TestSoftDeletesMergeWrapperDropsDoc.testMergeWrapperDropsLiveDoc(TestSoftDeletesMergeWrapperDropsDoc.java:56)

• Contracts. OneMerge#wrapForMerge: "Wrap a reader prior to merging in order to add/remove fields or documents"; only reordering doc IDs is illegal (MergePolicy.java:301-309, wording since 9.9.0 via #12622; before: "add/remove information to the merged segment"). setSoftDeletesField: "Soft deletes allow to retain documents across merges if the merge policy modifies the live docs of a merge reader" (IndexWriterConfig.java:551-552). IndexWriter's own comment: "this is also required if any MergePolicy modifies the liveDocs" (IndexWriter.java:4844-4845). CheckIndex treats a mismatching count as corruption.
• The inconsistency. No soft-deletes field: works. Soft-deletes field plus one unrelated hard delete in the segment: works (the counting path). Soft-deletes field, no hard delete: fails. A deliberate rule would not depend on an unrelated hard delete.
• History. 7.4.0-7.6.0 counted the surviving soft-deleted documents of every wrapped segment. LUCENE-8569 (#9615, apache/lucene-solr#502, 2018) replaced that with the subtraction as an optimization that gives "accurate counts"; neither the issue nor the PR mentions wrappers that hide live documents. In that review the negative-carry-over check was an IllegalStateException; a reviewer asked "AssertionError instead? This means we have a bug right?", and it became the assert: a negative result was treated as an IndexWriter bug, not as misuse.
• Tests. No upstream test removes documents in wrapForMerge in a soft-deletes index.

The intended-behaviour verifier and a cross-model review built the strongest case for "not a bug": the merge-policy hooks are expert API and OneMergeWrappingMergePolicy is @lucene.experimental; every in-tree wrapper only revives; the shortcut's assertions show its author expected revive-only wrappers; and the setSoftDeletesField sentence can be read as "with soft deletes, a merge policy changes live docs only to retain documents".

Why it fails: no document states a revive-only rule and wrapForMerge explicitly allows removing documents; the setSoftDeletesField sentence names retention "for instance" and restricts nothing; the review of the introducing change called a negative carry-over a bug; the outcome flips on an unrelated hard delete; 7.4.0-7.6.0 handled the same wrapper correctly; @lucene.experimental permits API changes, not a merge that stores a wrong count or closes the writer; and IndexWriter treats the outcome as a tragic event, not as a cleanly rejected policy. Indexing every document with softUpdateDocument, as setSoftDeletesField asks, fails the same way, so it is not misuse. Both rated the case weak. Verdict: a defect.

Points a maintainer may still raise (a cross-model fact check found the rebuttal fair but incomplete here): the explicit "add/remove fields or documents" wording came in 9.9.0, five years after the shortcut; the usual way to remove documents is a delete; nobody reported it in eight years; and LUCENE-8569 had a real performance motive. None of them makes a closed writer or a wrong stored count acceptable.

One fix was applied in a scratch worktree at a9779ef3c193 and run through gradle (seed DEADBEEF). The other options are sketches, not run. Which one, or another design, is the maintainers' call.

Replace the subtraction in the no-hard-deletes branch with countSoftDeletes, the counting the hard-deletes branch uses and that 7.4.0-7.6.0 used for every wrapped segment, and delete assertSoftDeletesCount, which becomes unused (the ECJ lint settings make an unused private member an error). Patch: fix-count-soft-deletes.diff, +9/-14 in IndexWriter.java. Equivalent by reading: drop the hardLiveDocs != null split and always call countSoftDeletes with hardLiveDocs, as 7.6.0 did.

} else {
  // The wrapper may revive soft-deleted documents and may also remove documents
  // (OneMerge#wrapForMerge), so the carried-over soft deletes cannot be derived from
  // the deletion counts alone: count the soft-deleted documents that stay live.
  countSoftDeletes(
      wrappedReader, wrappedReader.getLiveDocs(), null, softDeleteCount, Counter.newCounter(false));
}

Trade-offs

• It gives back the LUCENE-8569 optimization for wrapped segments without hard deletes: one pass over the soft-deletes doc values of each such segment (only documents that carry a soft-delete value, one Bits.get each). Segments that are not wrapped still skip all accounting.
• For SoftDeletesRetentionMergePolicy, the wrapper of such a segment already runs a query over its soft-deleted documents and copies its live docs (SoftDeletesRetentionMergePolicy.java:97-130), so the extra pass is of the same order (by reading). No benchmark was run.

What the checks validated

• Stock: the compact test and the finder's test together run 10 tests: 6 failed and 1 skipped with assertions on, 7 failed with assertions off.
• With the fix: 10 of 10 pass with assertions on and with assertions off.
• With the fix: the full lucene/core test suite passes (750 classes, 8,899 tests, 322 skipped, 0 failures, assertions on, including both repro classes and the soft-delete test classes); :lucene:core:ecjLint and :lucene:core:checkGoogleJavaFormat pass.
• Earlier, with the same change shadowed: the 584-case exhaustive run has 0 failures (assertions on and off); TestSoftDeletesRetentionMergePolicy (14 tests) and TestSoftDeletesDirectoryReaderWrapper (5 tests) pass over 3 iterations each; the independent reproducer's 6 tests pass.

No cheap runtime check can tell "revives r, hides k" from "revives r - k, hides nothing": both give the same numDeletedDocs. So the shortcut would need the wrapper to declare that it only revives, for example through a new OneMerge method that SoftDeletesRetentionMergePolicy overrides.

Trade-offs

• New API surface; a chain such as retention over a user wrapper needs every link to declare it; the saving is small by the trade-off above.
• A generic runtime test ("the wrapped live docs are a superset of the original ones") is no cheaper: it costs a pass over maxDoc and does not cover a wrapper that changes the soft-deletes field itself, which wrapForMerge also permits.

Turn the assertion into an explicit exception and document that wrappers in soft-deletes indexes must not hide live documents.

Trade-offs

• Contradicts the wrapForMerge javadoc and rejects merges that work without a soft-deletes field; it still fails inside the merge, so the writer still closes; a too-low but non-negative count can only be detected by counting, which is the first option's cost.

Drop expired documents with IndexWriter#deleteDocuments(Query) instead of hiding them in wrapForMerge; a segment with hard deletes takes the counting path. The delete must already be applied when the merge takes its readers: the branch is chosen from the merge reader's hard-live-docs snapshot (ReadersAndUpdates.java:1092-1108).

Trade-offs

• By reading only; it changes when the documents disappear (at the delete, not at the merge).

Method: a bounded-exhaustive differential and model-based test (semi-formal tier) of merge-policy wrapper compositions: 50 wrapper towers x 5 base policies x 10 triggers x 3 data profiles x 2 seeds, checked against a model oracle.

• To check that its oracle can fail, the harness runs mutants. The mutant that wraps merges to drop one live document was meant to be caught by the model's live-documents check; instead IndexWriter's own assertion "carry-over soft-deletes must be positive" fired in every cell.
• Reading IndexWriter.mergeMiddle located the no-hard-deletes subtraction.
• A second bounded-exhaustive run on the real code (584 combinations, reviving a hard-deleted document excluded: segments of 1-3 documents, each live, soft-deleted or hard-deleted, and a wrapper that keeps, removes or revives each) failed in exactly the 103 cases with no hard deletes and a removed live document, and in 0 of 481 others; with the fix, 0 of 584.
• Found 2026-10-27 on main a9779ef3c193; then checked by an independent reproducer, a devil's-advocate verifier, reviews by a model from another family (OpenAI GPT-5.6) that ran their own tests, an adjudication, a follow-up (history, prior reports, security) and an audit.