A re-created PersistentSnapshotDeletionPolicy counts its saved snapshots but returns no commits until an IndexWriter opens with it, and no javadoc says so

PersistentSnapshotDeletionPolicy saves each snapshotted commit generation and its reference count to a snapshots_N file, so snapshots survive a restart. When the policy is created again over that file, its constructor loads only those counts and builds no IndexCommit; for the saved generations the IndexCommit objects are handed to it later, by the IndexWriter that opens with it (onInit). Until then getSnapshotCount() reports the saved snapshots while getSnapshots() is empty and getIndexCommit(gen) returns null, although the only case its javadoc names for null is "not currently snapshotted". The design is deliberate and nothing is lost: once a writer opens with the policy, the saved commits that are still in the index are protected and every getter agrees. What is missing is documentation: no javadoc, CHANGES or MIGRATE entry says what the getters of a re-created policy return before it has been passed to an IndexWriter, and the constructor's javadoc suggests more ("initializing the class with the snapshots information"). The case for "intended" is strong, so the fix is a few javadoc sentences, not a code change.

1. Two maps. SnapshotDeletionPolicy keeps refCounts ("Records how many snapshots are held against each commit generation", SnapshotDeletionPolicy.java:43-44) and indexCommits ("Used to map gen to IndexCommit", :46-47).
2. The constructor fills only the first. The PersistentSnapshotDeletionPolicy constructor calls loadPriorSnapshots() (PersistentSnapshotDeletionPolicy.java:99). It reads the header, the entry count and the (generation, count) pairs of the snapshots_N files it finds, keeps those of the newest in refCounts (:215-241), deletes older or broken save files and sets the next save-file number (:253-262). The file holds nothing else (persist(), :161-184), and it may live in a Directory other than the index (:39-42). The constructor is given only that Directory, so without another source of the commit list it cannot in general build the current commits; it builds none.
3. For the saved generations, onInit fills the second. onInit sets initCalled = true and puts each commit the writer hands over into indexCommits if its generation is in refCounts (SnapshotDeletionPolicy.java:69-81). The only other code that writes the map, incRef (:115-126), is reached from snapshot() and from an error path of release(IndexCommit), both refused before onInit (item 5). IndexWriter calls onInit, through IndexFileDeleter (IndexFileDeleter.java:237), when it opens with the policy (IndexDeletionPolicy.java:46-62: "The writer locates all index commits present in the index directory and calls this method"). onInit is public, so other code could call it; an IndexWriter opening with the policy is the normal path.
4. The getters read different maps. getSnapshotCount() sums refCounts (SnapshotDeletionPolicy.java:162-170); getSnapshots() (:157-160) and getIndexCommit(long) (:172-178) read indexCommits. Before onInit they give 1, [] and null.
5. Only the mutators are guarded. snapshot() (SnapshotDeletionPolicy.java:142-146) and releaseGen() (:94-98, reached from release(long), PersistentSnapshotDeletionPolicy.java:156-159) throw IllegalStateException while initCalled is false ("Used to detect misuse", SnapshotDeletionPolicy.java:55-56). The two commit getters have no guard and no caveat.

One empty document, one commit (generation 1), one snapshot(), writer closed. A policy created again with OpenMode.APPEND (or, since a save file exists, the default two-argument constructor) over the same directory: getSnapshotCount() = 1, getLastSaveFile() is set, DirectoryReader.listCommits(dir) contains generation 1, getSnapshots() = [], getIndexCommit(1) = null; snapshot() and release(1) throw IllegalStateException ("this instance is not being used by IndexWriter; be sure to use the instance returned from writer.getConfig().getIndexDeletionPolicy()"). After new IndexWriter(dir, config with this instance): getIndexCommit(1) is the commit of generation 1, getSnapshots().size() = 1, and release(1) works and is saved. (On a directory without a save file, OpenMode.APPEND throws IllegalStateException "no snapshots stored in this directory", PersistentSnapshotDeletionPolicy.java:101-103; the default constructor does not.)

• Who. Applications that opt into PersistentSnapshotDeletionPolicy (@lucene.experimental) and, after a restart, read getSnapshots() or getIndexCommit(gen) from the re-created policy before an IndexWriter has been opened with it: a backup or restore tool that first lists the saved snapshots, or code that uses getIndexCommit(gen) != null as "is this generation still snapshotted?" before releasing it (a check mentioned as a possible workaround on LUCENE-4973).
• What goes wrong. Without any error they see no snapshotted commits while getSnapshotCount() reports them, and could conclude that a saved snapshot is gone, then for example skip a backup or a release. These are possible consequences, not observed ones; no user report shows them. The getters change nothing: the saved counts are intact, and once a writer opens with the policy, onInit protects the saved commits that are still in the index and every getter agrees.
• Default vs opt-in. The policy is opt-in; default codec, directory and merge settings are enough. One document and one snapshot; no scale involved.
• How likely. Rare. The usual flow, and Lucene's own restart test (testExistingSnapshots), open the writer first. No user report or question about this state was found since it appeared in 4.4.0 (2013).

• Seeds. One empty document, one commit, one snapshot; the test framework randomizes the Directory and the config, and the three seeds run, 5EED0890, 7B890EA1 and 7B890DA2, give the same failure. Assertions on and off fail the same way.
• What it is not. It demonstrates the mismatch between getIndexCommit(long) and its javadoc. It is not a regression test for the recommended javadoc fix, which changes no code, so the test keeps failing under it. The hunt's control passes: it opens and closes an IndexWriter with the re-created policy before the read. Its other differences (class and method name, no assertion message, an extra check that the commit has generation gen) do not change what it exercises.
• Releases. Standalone, it fails on 10.5.2 as on main, and it also fails on 9.12.3 and 10.6.0. The version probes, which port it and also read getSnapshots(), fail on every release from 4.4.0 to 10.5.2 that was run.

cp $REPRO/TestReopenedPersistentSnapshotGetIndexCommit.java $LUCENE/lucene/core/src/test/org/apache/lucene/index/
cd $LUCENE
./gradlew :lucene:core:test --tests org.apache.lucene.index.TestReopenedPersistentSnapshotGetIndexCommit -Ptests.seed=5EED0890 -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed 5EED0890, -Ptests.asserts=true
TestReopenedPersistentSnapshotGetIndexCommit > testGetIndexCommitBeforeWriterOpens FAILED
    java.lang.AssertionError: expected the IndexCommit of snapshotted generation 1, got null
        at __randomizedtesting.SeedInfo.seed([5EED0890:53150589B4C14A07]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.junit.Assert.assertNotNull(Assert.java:713)
        at org.apache.lucene.index.TestReopenedPersistentSnapshotGetIndexCommit.testGetIndexCommitBeforeWriterOpens(TestReopenedPersistentSnapshotGetIndexCommit.java:44)
:lucene:core:test (FAILURE): 1 test, 1  failure
# -Ptests.asserts=false: the same failure
# documentation fix (option A): changes no code; the same failure, assertions on and off
# loud getters (option B): java.lang.IllegalStateException: snapshots were loaded but no IndexWriter has been
#   opened with this instance yet; open an IndexWriter with it before reading its IndexCommits

• The getters' own javadoc. getIndexCommit(long): "Retrieve an IndexCommit from its generation; returns null if this IndexCommit is not currently snapshotted" (SnapshotDeletionPolicy.java:172-175). getSnapshots(): "Returns all IndexCommits held by at least one snapshot" (:157). getSnapshotCount(): "Returns the total number of snapshots currently held" (:162). In the repro state generation 1 is counted by the same object and is in DirectoryReader.listCommits(dir). The javadoc of getIndexCommit(long) names no other case for null and does not mention the state before onInit.
• The persistent class promises the restart. "a persistence layer so that snapshots can be maintained across the life of an application" (PersistentSnapshotDeletionPolicy.java:34-37); the OpenMode parameter: "open an existing index, initializing the class with the snapshots information" (:85-87).
• Nothing says what the getters return before a writer opens. Not the javadoc of either class, IndexDeletionPolicy, IndexWriterConfig.setIndexDeletionPolicy (IndexWriterConfig.java:207-220), lucene/CHANGES.txt (LUCENE-4973 at :13564, LUCENE-4976 at :13715) or lucene/MIGRATE.md. The general lifecycle is documented: IndexDeletionPolicy is an "Expert" policy set on IndexWriterConfig (IndexDeletionPolicy.java:23-27) whose onInit gets the commits from the writer (:46-62), and the deletion policy "Only takes effect when IndexWriter is first created" (IndexWriterConfig.java:219). The closest thing to a caveat for this state is the exception message of the two mutators.
• getIndexCommit(gen) was added for applications that persist generations. On LUCENE-4973 (#6037), Shai Erera wrote on 2013-05-01 "pSDP needs to have a getIC(gen) because if the apps persists the gens, it needs a way to obtain their IC instance". On 2013-05-02, asking that releaseGen accept a generation that is not snapshotted, they mentioned as a possible workaround "calling sdp.getIC(gen) and if not null call release". The thread does not discuss a policy that is read before onInit.
• Early reads happen upstream, but only of the count. Upstream tests read getSnapshotCount() from a re-created policy before attaching it, after every snapshot was released (count 0; TestPersistentSnapshotDeletionPolicy.java:161-164, :178-181). No upstream test reads the commit getters or a positive count in that state.
• Not claimed. The snapshot() / release(gen) IllegalStateException (the designed misuse guard; its message names the fix), and "getSnapshots() must list what getSnapshotCount() counts" (one counts snapshot references, the other lists commits; they also differ after attachment when a saved generation has no commit left).

The strongest case for "intended", from the study's devil's advocate and an executing cross-model reviewer (OpenAI GPT-5.6, verdict not real): LUCENE-4973 moved onInit "to build the gen -> IC map" into SnapshotDeletionPolicy on purpose (Michael McCandless, #6037), and LUCENE-4976 "fixed PSDP to detect if you try to snapshot/release when it's not being used by an IW" (#6040). IndexDeletionPolicy is an Expert writer callback whose onInit supplies the commits; snapshot() protects a commit only "as long as this IndexDeletionPolicy is used"; the policy "Only takes effect when IndexWriter is first created"; upstream's restart test attaches first; and the save Directory may differ from the index, so the constructor is not in general able to build the commits. On that reading, commit lookups before attachment are outside the getters' meaningful domain. The cross-model fact check of this doc (OpenAI GPT-5.6) rated this argument "Strong": "A tiny clarification may be welcome; a defect claim is weak."

What it leaves open: it shows the code is intended, which is why this is classed as a documentation gap and not as a code bug. It does not show that the documentation describes this state. A careful reader can infer it by combining the public IndexDeletionPolicy contract (the writer supplies the commits in onInit) with the implementation (for the saved generations, the generation to IndexCommit map is filled there), but no text connects that contract to the getters of a re-created policy. The persistent class's javadoc points the other way, and the guard added on purpose covers only the mutators, so the getters answer without an error where the mutators fail loudly. The executing reviewer conceded "A narrow javadoc clarification could improve usability"; that clarification is the proposed fix, and nothing more is proposed.

Two options were applied in a scratch worktree of main 645d4fe14a20 and run with gradle; a third is described only. The documentation fix is the proposal, because the code is deliberate and has behaved this way since 4.4.0. Open PR #16482 already edits both files.

Add a paragraph to the PersistentSnapshotDeletionPolicy class javadoc (what a re-created policy has before a writer opens with it), qualify "initializing the class with the snapshots information" on the OpenMode parameter, and add one sentence each to getSnapshots() and getIndexCommit(long).

diff --git a/lucene/core/src/java/org/apache/lucene/index/PersistentSnapshotDeletionPolicy.java b/lucene/core/src/java/org/apache/lucene/index/PersistentSnapshotDeletionPolicy.java
index d3fa95c1623..4077d94b0da 100644
--- a/lucene/core/src/java/org/apache/lucene/index/PersistentSnapshotDeletionPolicy.java
+++ b/lucene/core/src/java/org/apache/lucene/index/PersistentSnapshotDeletionPolicy.java
@@ -44,6 +44,13 @@ import org.apache.lucene.util.IOUtils;
  * <p>This class adds a {@link #release(long)} method to release commits from a previous snapshot's
  * {@link IndexCommit#getGeneration}.
  *
+ * <p>A policy created over previously saved snapshots (for example after a restart) reads only the
+ * snapshotted commit generations and their counts from the save file: {@link #getSnapshotCount()}
+ * and {@link #getLastSaveFile()} reflect them right away, but the {@link IndexCommit}s come from
+ * the {@link IndexWriter}. Until an {@link IndexWriter} has been opened with this instance, {@link
+ * #getSnapshots()} is empty, {@link #getIndexCommit(long)} returns null, and {@link #snapshot()}
+ * and {@link #release(long)} throw {@link IllegalStateException}.
+ *
  * @lucene.experimental
  */
 public class PersistentSnapshotDeletionPolicy extends SnapshotDeletionPolicy {
@@ -84,7 +91,8 @@ public class PersistentSnapshotDeletionPolicy extends SnapshotDeletionPolicy {
    * @param dir the {@link Directory} which will be used to persist the snapshots information.
    * @param mode specifies whether a new index should be created, deleting all existing snapshots
    *     information (immediately), or open an existing index, initializing the class with the
-   *     snapshots information.
+   *     snapshots information (the snapshotted generations and their counts; see the class javadoc
+   *     for what is available before an {@link IndexWriter} has been opened with this instance).
    */
   public PersistentSnapshotDeletionPolicy(IndexDeletionPolicy primary, Directory dir, OpenMode mode)
       throws IOException {
diff --git a/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java b/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
index 19f2c0d110f..5cc07c157c1 100644
--- a/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
+++ b/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
@@ -154,7 +154,14 @@ public class SnapshotDeletionPolicy extends IndexDeletionPolicy {
     return lastCommit;
   }
 
-  /** Returns all IndexCommits held by at least one snapshot. */
+  /**
+   * Returns all IndexCommits held by at least one snapshot.
+   *
+   * <p>The commits are the ones handed to this policy by the {@link IndexWriter} that uses it. A
+   * {@link PersistentSnapshotDeletionPolicy} created over previously saved snapshots returns an
+   * empty list until an {@link IndexWriter} has been opened with it, although {@link
+   * #getSnapshotCount()} already counts the saved snapshots.
+   */
   public synchronized List<IndexCommit> getSnapshots() {
     return new ArrayList<>(indexCommits.values());
   }
@@ -171,7 +178,8 @@ public class SnapshotDeletionPolicy extends IndexDeletionPolicy {
 
   /**
    * Retrieve an {@link IndexCommit} from its generation; returns null if this IndexCommit is not
-   * currently snapshotted
+   * currently snapshotted, or if no {@link IndexWriter} has been opened with this policy yet (for
+   * example a {@link PersistentSnapshotDeletionPolicy} created over previously saved snapshots).
    */
   public synchronized IndexCommit getIndexCommit(long gen) {
     return indexCommits.get(gen);

Trade-offs

No behaviour change; it states what the code does in the three places a restart user reads. Optionally add a CHANGES entry under "Documentation". #16482 already removes the stale javadoc of the private loadPriorSnapshots(). The two getter sentences go into SnapshotDeletionPolicy, so they also describe a plain SnapshotDeletionPolicy, for which they hold as well (before a writer opens it has neither snapshots nor commits); they name PersistentSnapshotDeletionPolicy as the case that matters. They do not cover a third case: after onInit, a saved generation whose commit is gone stays counted but has no commit. A clause could cover it.

What the checks validated

• Applied in a scratch worktree of 645d4fe14a20 and run with gradle (seed 5EED0890): :lucene:core:checkGoogleJavaFormat and :lucene:core:renderJavadoc pass, and the rendered PersistentSnapshotDeletionPolicy.html and SnapshotDeletionPolicy.html show the new sentences.
• The snapshot-policy, IndexFileDeleter, IndexWriterConfig, DirectoryReader, DirectoryReaderReopen, IndexWriter and ControlledRealTimeReopenThread suites pass: 228 tests, 2 skipped, assertions on.
• The minimal test keeps failing with the same assertion, assertions on and off, as expected for a change that touches only comments.
• A first draft failed checkGoogleJavaFormat on line length in the class javadoc; the diff shown is the re-wrapped text that passes. Not run: gradlew check or other modules.

getSnapshots() and getIndexCommit(long) throw IllegalStateException when snapshots were loaded but no IndexWriter has opened with the policy yet, like snapshot() and release() already do.

diff --git a/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java b/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
index 19f2c0d110f..ce473fcf5c7 100644
--- a/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
+++ b/lucene/core/src/java/org/apache/lucene/index/SnapshotDeletionPolicy.java
@@ -156,6 +156,7 @@ public class SnapshotDeletionPolicy extends IndexDeletionPolicy {
 
   /** Returns all IndexCommits held by at least one snapshot. */
   public synchronized List<IndexCommit> getSnapshots() {
+    ensureCommitsKnown();
     return new ArrayList<>(indexCommits.values());
   }
 
@@ -174,9 +175,18 @@ public class SnapshotDeletionPolicy extends IndexDeletionPolicy {
    * currently snapshotted
    */
   public synchronized IndexCommit getIndexCommit(long gen) {
+    ensureCommitsKnown();
     return indexCommits.get(gen);
   }
 
+  /** Snapshots loaded before any IndexWriter used this instance have no IndexCommit yet. */
+  private void ensureCommitsKnown() {
+    if (initCalled == false && refCounts.isEmpty() == false) {
+      throw new IllegalStateException(
+          "snapshots were loaded but no IndexWriter has been opened with this instance yet; open an IndexWriter with it before reading its IndexCommits");
+    }
+  }
+
   /** Wraps each {@link IndexCommit} as a {@link SnapshotCommitPoint}. */
   private List<IndexCommit> wrapCommits(List<? extends IndexCommit> commits) {
     List<IndexCommit> wrappedCommits = new ArrayList<>(commits.size());

Trade-offs

Turns the silent wrong answer into an exception that names the fix, only in the trap state; a fresh or attached policy behaves as before. But it changes behaviour in an experimental API: code that reads these getters on a re-created policy before attaching it and copes with null or [] would now throw. Needs @throws javadoc and a CHANGES entry, probably on main only. The minimal test then fails with the exception instead of the assertion.

What the checks validated

• The same worktree and seed: :lucene:core:checkGoogleJavaFormat passes, and the same suites pass (228 tests, 2 skipped). Only the two snapshot-policy suites call these getters anywhere in the Lucene sources (grep), so no upstream test reads them on an unattached policy with saved snapshots.
• The minimal test now fails, assertions on and off, with IllegalStateException: snapshots were loaded but no IndexWriter has been opened with this instance yet; open an IndexWriter with it before reading its IndexCommits instead of the silent null.
• Not run: renderJavadoc (the change adds no public javadoc) or other modules.

When the save Directory also holds the index, fill indexCommits from DirectoryReader.listCommits(dir) for the loaded generations.

Trade-offs

Works only when the save file sits next to the index (the class allows another Directory), adds index I/O and a new failure path to a constructor that reads one small file, hands out reader-side commits that onInit later replaces with the writer's, and reverses the 2013 design in which commits come only from the writer. Not built or run.

• Lead. An independent model from another family (OpenAI GPT-5.6), using a configuration-lifecycle framing, proposed the question: what does a restarted snapshot policy report?
• Probe. An executed lifecycle probe on main a9779ef3c193 printed persistentAfterRestart count=1 commits=0 and an IllegalStateException for release (2026-10-28).
• Reduction. A hunt unit (snapshot deletion policies) took the lead; its finder traced it by code reading to the constructor / onInit split and wrote a public-API JUnit. The unit's bounded-exhaustive model-based test and its TLA+ model of commit retention ran on the same classes, but their findings were other items, so no tool output gave the first signal.
• Verification. An independent reproducer, cross-model reviews (OpenAI GPT-5.6), an intended-behaviour devil's advocate, an adjudication, a re-verification and a tie-break; the devil's advocate and the adjudication trimmed the claim to the documentation gap.