DirectoryTaxonomyWriter gives later categories wrong ordinals after IndexWriter rejects one enriched ordinal document

In a taxonomy index each facet label is one document, and its ordinal is that document's doc ID; the taxonomy must never contain deleted documents. Since 9.10.0, ReindexingEnrichedDirectoryTaxonomyWriter (or an enrichOrdinalDocument override) lets an application add its own fields to those documents. DirectoryTaxonomyWriter.addCategoryDocument calls the hook, then indexWriter.addDocument(d), and advances its ordinal counter only after that call returns. When IndexWriter rejects the document with a non-aborting exception, such as a term over 32,766 bytes or a vector of another dimension, it has already used up a doc ID and keeps the document as deleted. addCategory throws IllegalArgumentException, the application skips that category, and from then on, until a merge reclaims the deleted document, every new category gets an ordinal one below its doc ID: readers resolve it to the previous category (even the rejected label), main-index documents store it, and commit() persists it. In the repro two color/y documents are counted as color: bad (2), x (1) with no error, and a reopened writer returns 3 instead of 2 for a category that already exists. Other shapes throw ArrayIndexOutOfBoundsException or CorruptIndexException. The opt-in, experimental enrichment hook is the only demonstrated trigger; every release from 9.10.0 to 10.5.2, and main, is affected.

• Taxonomy and ordinal. Taxonomy facets store each label, such as color/x, once in a side index, as one document; its doc ID is the label's ordinal. Main-index documents store ordinals, and facet counts are kept per ordinal. The writer's own notes say the taxonomy never has deleted documents: "internal docids of the configured index must not be altered. For that, categories are never deleted from the taxonomy index" (DirectoryTaxonomyWriter.java:227-229; also :364, :628-632).
• Enrichment. Since 9.10.0, ReindexingEnrichedDirectoryTaxonomyWriter lets an application "append arbitrary fields to the ordinal documents" through an appender, called from the protected, @lucene.experimental hook enrichOrdinalDocument (ReindexingEnrichedDirectoryTaxonomyWriter.java:31-54, DirectoryTaxonomyWriter.java:440-446).
• A non-aborting rejection. IndexWriter rejects a document with IllegalArgumentException when a term is longer than MAX_TERM_LENGTH (32,766 bytes) or a vector's dimension differs from the field's, and stays open. It has already reserved a doc ID for the document: "Even on exception, the document is still added (but marked deleted), so we don't need to un-reserve at that point" (DocumentsWriterPerThread.java:283-290, deleted at :302-306).

1. addCategoryDocument (DirectoryTaxonomyWriter.java:452-482) builds the category document, calls enrichOrdinalDocument(d, categoryPath) (:466), then indexWriter.addDocument(d) (:468), and only then int id = nextID.getAndIncrement() (:469).
2. If addDocument rejects the document, the exception leaves between :468 and :469: maxDoc is k+1, nextID is still k.
3. The next category is indexed as doc k+1 and handed ordinal k, and so on for every later category until a merge reclaims the deleted document. The writer's cache and parent array use its own ordinals (:475, :479), so nothing fails inside the writer while its cache still holds the labels it added (true at repro scale). By code reading, not executed: once the 4,000-entry cache (:89) evicts a label added after the rejection, the writer looks it up on disk and finds its doc ID (:347-377, :484-494), so the same session can return a second ordinal for that label.
4. Readers resolve ordinals by doc ID: ordinal k is the deleted, rejected document (getPath returns its label, or throws IllegalStateException when it has no doc values, as in the vector case), and getSize() returns numDocs, one less than maxDoc (DirectoryTaxonomyReader.java:429-456, :591-594). Main-index documents store the writer's ordinals (FacetsConfig.java:383), so they are counted under the previous category.
5. A reopened writer starts at nextID = maxDoc (DirectoryTaxonomyWriter.java:174) and looks labels up by doc ID, so it returns 3 for a category the first writer returned as 2.
6. Enrichment fields are the only demonstrated trigger and the only route through the stock writer's own fields (an openIndexWriter override may supply another IndexWriter, DirectoryTaxonomyWriter.java:203-217, not explored): FacetLabel.MAX_CATEGORY_PATH_LENGTH (8,191 characters, FacetLabel.java:32-39, :90-100) keeps a category's own term below the limit. An exception thrown by the appender itself, before addDocument, is harmless (control test).

Facet scenario (this doc's test): color/x is doc 2 and committed; the document for color/bad (32,767-byte description) is rejected and stays as deleted doc 3; color/y, size, size/s, size/t are docs 4-7 but get ordinals 3-6. Reader: getSize() 7, maxDoc 8. FastTaxonomyFacetCounts.getTopChildren(10, "color") returns bad (2), x (1) instead of y (2), x (1). Writer view: after a (ordinal 1) and the rejected rejected, addCategory("b") returns 2; the reader says ordinal 2 is [rejected] and [b] is 3; a reopened writer returns 3 for b. With a 3-dimensional vector after 2-dimensional ones: the same 2 vs 3, and getPath(2) throws IllegalStateException. Same with assertions on and off, on main and 10.5.2.

• Who is exposed. Users of the enrichment hook (@lucene.experimental, 9.10.0 and later) whose enrichment value can be rejected inside IndexWriter.addDocument (two executed triggers: an unbounded per-category text indexed as a StringField longer than 32,766 bytes, and a vector whose dimension differs from earlier category documents, for example after switching embedding models), and who keep using the writer after addCategory or FacetsConfig.build threw. For these non-aborting failures IndexWriter stays usable and documents that its own index stays consistent; no taxonomy javadoc says whether the taxonomy writer may be reused. The taxonomy writer's own stock IndexWriterConfig; single-threaded; the test framework randomizes the codec, the main index's config and the directories, and 40 of 40 bug-test runs fail with --iters 10. A plain DirectoryTaxonomyWriter cannot hit it.
• Downstream. A read-only code search of the default branches of Elasticsearch, OpenSearch and Solr found no use of DirectoryTaxonomyWriter; custom applications that embed the facet module are the ones exposed.
• Effect. Until a merge reclaims the deleted document, every category added after the rejection resolves to the previous one, across dimensions too (a probe's lang dimension showed {} instead of {en=1}). Counts go to the wrong labels silently (color: bad (2), x (1); with 1,100 earlier categories and a selective query, sparse counting, nothing throws either). Other shapes throw ArrayIndexOutOfBoundsException; after a vector rejection every taxonomy facet request throws CorruptIndexException: Missing parent data for category 3, and a restarted writer cannot add a new category. Each further rejection adds one more position (after 3: writer 3, reader 6).
• Persistence. The wrong ordinals are stored in main-index documents and committed. Within one writer session, a merge that drops the deleted document realigns that session's ordinals; if a new writer reopened the taxonomy before that merge, one set of stored ordinals stays wrong for good. Once a reopened writer's ordinals are stored as well, repair means rebuilding the taxonomy and re-indexing the affected documents (inference from the design, not executed).
• Not affected. Drill-down filters use path terms, not ordinals, and matched exactly the right documents; no document is exposed; no hang or unbounded resource use.
• Likelihood. Rare: it needs the opt-in hook, a value IndexWriter rejects, and continued use of the writer. The only upstream test of the hook adds small valid fields.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: taxonomy ordinal of [b] vs the ordinal addCategory returned for it expected:<2> but was:<1>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.apache.lucene.facet.taxonomy.directory.TestTaxonomyWriterRejectedOrdinalDocument.testOrdinalAfterRejectedOrdinalDocument(TestTaxonomyWriterRejectedOrdinalDocument.java:48)

• Contract. TaxonomyWriter.java:51-53: "addCategory() adds a category with a given path name to the taxonomy, and returns its ordinal. If the category was already present in the taxonomy, its existing ordinal is returned." No exception carve-out; the reopen test breaks it with the writer alone.
• The writer's design. "internal docids of the configured index must not be altered. For that, categories are never deleted from the taxonomy index" (DirectoryTaxonomyWriter.java:227-229); "liveDocs=null because the taxonomy has no deletes" (:364); "there are no deletions in the index" (:628-632).
• IndexWriter's contract. A term longer than MAX_TERM_LENGTH makes addDocument throw IllegalArgumentException (IndexWriter.java:1480-1481), and after an exception "the index will be consistent, but this document may not have been added" (:1465-1466); IndexWriter stays open after this non-aborting rejection (executed). It closes itself on tragic events, such as "if you hit an Error, or disaster strikes during a checkpoint" (:162-165), an aborting indexing exception (DocumentsWriterPerThread.java:594-605, IndexWriter.java:1634-1639) or a failed merge (:5109-5113, :6090-6105); none of these happens here. The consistency promise covers IndexWriter's own index, not wrappers with their own invariants.
• The hook's docs. "append arbitrary fields to the ordinal documents" (ReindexingEnrichedDirectoryTaxonomyWriter.java:31-33); "modify the document corresponding to a category path before indexing it" (DirectoryTaxonomyWriter.java:441-442). Nothing restricts the fields or says the writer must be rolled back after a rejection; the rollback() javadoc only describes rollback (:855-859).
• Tests and history. #12337, which added the hook, and its issue and dev@ design thread never discuss fields that IndexWriter rejects; its only test, TestOrdinalData, adds small valid fields. LUCENE-5048 (#6112, 2013) capped label length so that a label's terms stay below the indexer limit (the comment at FacetLabel.java:32-39 names the drill-down term), which also keeps a category's own term below it; the hook added a second, uncapped way to put terms into the same document.

Strongest case (the devil's advocate; the cross-model intended-lens reviewer rated it moderate): the hook is @lucene.experimental; "arbitrary fields" should mean valid fields; the application built the field that IndexWriter rejected and received an IllegalArgumentException; rollback() exists; IndexWriter only promises that the document "may not have been added".

What to concede: no API expressly promises that the taxonomy writer stays usable after an unchecked exception caused by the caller's enrichment, and IndexWriter's consistency promise covers its own index, not the taxonomy's ordinal invariants. Why it fails anyway: @lucene.experimental reserves the right to change the API (asked for in the #12337 review "so we reserve the right to break them on subsequent releases"), not to corrupt ordinals. The argument explains the one failed call, not the silent wrong ordinals of every later, valid category, nor one category getting two ordinals across sessions. "Roll back after any exception" is documented nowhere and is stricter than the IndexWriter the writer wraps, and the writer breaks its own stated invariant (no deleted documents). A rare trigger lowers severity, not intent. Verdict: a defect. Expect the reply "validate your fields or roll back"; answer with the addCategory contract and the reopen test.

Option A was built and validated with gradle in a scratch worktree; option B was run and is not enough; options C to E were not run. Until a fix lands, applications can validate enrichment values inside the appender, where throwing is harmless (not a complete guard: analyzer output, the current field schema and codec limits cannot all be checked outside IndexWriter), and keep the enrichment schema fixed.

One file, DirectoryTaxonomyWriter.java. Wrap indexWriter.addDocument(d) in addCategoryDocument: if it throws while IndexWriter is open and its maxDoc no longer equals nextID, call rollback() (which closes the taxonomy writer) and rethrow, adding a secondary failure as suppressed. Plus a javadoc paragraph on enrichOrdinalDocument saying so, and that an exception thrown by the hook itself leaves the writer usable. The logic is the finder's sketch; the snippet abridges the patch's two-line comment (the full text is in the patch and in the brief).

try {
  indexWriter.addDocument(d);
} catch (Throwable t) {
  // (abridged) a non-aborting failure still uses up a doc ID: roll back
  try {
    if (indexWriter.isOpen() && indexWriter.getDocStats().maxDoc != nextID.get()) {
      rollback();
    }
  } catch (Throwable t2) {
    t.addSuppressed(t2);
  }
  throw t;
}
int id = nextID.getAndIncrement();

Trade-offs

• Why rollback: the writer can neither remove the deleted document nor reuse its doc ID. Only a later merge reclaims it, so a writer that keeps going commits a taxonomy with a hole that readers resolve wrongly until then, and a reopen before that merge leaves one set of ordinals wrong for good. The last commit is the one consistent state the writer can reach by itself. The rejected document never reaches a commit.
• Behaviour change: callers that continue today get AlreadyClosedException on their next call and must open a new writer. Every uncommitted category is lost, and main-index documents indexed since the last taxonomy commit must be discarded too (taxonomy first, then main index, TaxonomyWriter.java:36-42), since their ordinals will be handed out again. Executed in the diagram probe with the fix: a main-index color/x document, indexed before the rejection and committed, stores ordinal 2, which the reopened writer hands to color/y, so it is counted as y.
• Unchanged: an exception from the hook itself, before addDocument, leaves the writer usable; an aborting failure that closes IndexWriter is rethrown as before; the normal path only gains a try. Not benchmarked; not reviewed upstream.
• By code reading, not tested: addCategory checks ensureOpen() and the cache outside the lock (DirectoryTaxonomyWriter.java:381-388) and rollback() sets isClosed only after indexWriter.rollback() returns (:861-864), so only calls that start after the rollback reliably get AlreadyClosedException; a concurrent cache hit can still return an uncommitted ordinal. If indexWriter.rollback() itself throws, the taxonomy writer is not marked closed. No targeted tests for these, for a tragic failure, or for a coordinated rollback of both writers; maintainers may prefer a poison-first variant (like option C) or a revised version that also blocks the cache fast path.
• Taxonomies already damaged are not repaired. DirectoryTaxonomyWriter.java is byte-identical from 10.0.0 to main; 9.x needs its own (same) patch.

What the checks validated

• Scratch worktree at a9779ef3c193, gradle, JDK 25: the new test fails 4 of 6 on stock and passes 6 of 6 with the fix, assertions on and off; with TestDirectoryTaxonomyWriter and TestOrdinalData: 24 tests, 0 failures (1 skipped).
• The whole facet module: 40 suites, 312 tests (306 upstream + 6 new), 0 failures, with assertions on (7 skipped) and off (8 skipped); :lucene:facet:check -x test (google-java-format, ecjLint, forbiddenApis) passes.
• Standalone runner with the patched class: the new test passes (assertions on and off) and the finder's JUnit passes; the independent reproducer's 4 bug tests get AlreadyClosedException, because they keep using the writer after the rejection, which this fix forbids (its control passes).

After a failed addDocument, set nextID to maxDoc and rethrow.

Trade-offs

The deleted document stays: the reader's getSize() (numDocs) is one short of the highest ordinal. By code reading the hole also keeps the rejected label readable, lacks parent data in the vector case, and a later merge that drops it shifts every later doc ID again (not run with this variant).

What the checks validated

Gradle on main: the three ordinal tests pass, but the facet-count test throws ArrayIndexOutOfBoundsException: Index 7 out of bounds for length 7 in FastTaxonomyFacetCounts.count.

Mark the writer broken, like IndexWriter's tragic-event handling, so addCategory, commit and close throw until the application calls rollback().

Trade-offs

Same data loss as the recommended option, more code paths, and the application must know to roll back. Not run.

Count maxDoc instead of numDocs, give the hole placeholder parent data, and use a merge policy that never reclaims the deleted document.

Trade-offs

Invasive: it changes the reader, the taxonomy arrays and the merge policy. Not run, not recommended.

Javadoc only, on the hook and on ReindexingEnrichedDirectoryTaxonomyWriter.

Trade-offs

No code risk, but nothing stops the silent corruption.

Method: TLA+ model checking (TLC 1.8.0) (semi-formal tier: a hypothesis formed while modelling, then witnessed by the tool), in a hunt unit on concurrent adds to the taxonomy writer.

• The model (TaxoWriterCache.tla, 518 lines) covers addCategory, the writer's cache, its reader and parent array, with optional failure points; the rejection step follows DocumentsWriterPerThread's non-aborting path (the document keeps its doc ID and is deleted).
• The invariant SizeMatchesDocs (the writer's counter equals the number of taxonomy documents) fails after one rejection in all 8 rejection configurations (new and existing taxonomy, cache sizes 1, 2, 3 and unbounded; 15 states for the first one), while all 96 configurations without injected failures or rejections keep every invariant. The model is bounded; it corroborates the Java finding and proves nothing about the Java code.
• The trace was reduced to a same-package JUnit on the stock jars, then checked by an independent reproducer, a reviewer from another model family (OpenAI GPT-5.6, reading only), a devil's advocate, an adjudication and an audit.