@indigoai-us/hq-cloud 6.15.74 → 6.15.76

package/dist/sync/state-store.js

@@ -39,12 +39,15 @@ const DEFAULT_MAX_WAL_BYTES_BEFORE_COMPACTION = 16 * 1024 * 1024;
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 5_000;
 const REPLACE_STATE_MAX_ATTEMPTS = 3;
+const OPTIMISTIC_RECOVERY_MAX_RESAMPLES = 3;
 // Test instrumentation for materialisation regressions. Kept at the storage
 // seam so a fixture counts actual snapshot JSON decodes, not API invocations.
 let snapshotRecoveryCount = 0;
 let snapshotMaterializationCount = 0;
 let snapshotEncodeCount = 0;
 let snapshotWriteHookForTest;
+let snapshotReadHookForTest;
+let walReadHookForTest;
 let afterGenerationStageHookForTest;
 let reflinkCopyHookForTest;
 let positionalWriteForTest;
@@ -71,6 +74,14 @@ export function getStateStoreSnapshotEncodeCountForTest() {
 export function setStateStoreSnapshotWriteHookForTest(hook) {
     snapshotWriteHookForTest = hook;
 }
+/** Test-only seam after snapshot validation and before its large payload read. */
+export function setStateStoreSnapshotReadHookForTest(hook) {
+    snapshotReadHookForTest = hook;
+}
+/** Test-only seam after the WAL length is sampled during cold recovery. */
+export function setStateStoreWalReadHookForTest(hook) {
+    walReadHookForTest = hook;
+}
 /** Test-only crash seam after durable staging and before lock-protected publish. */
 export function setStateStoreAfterGenerationStageHookForTest(hook) {
     afterGenerationStageHookForTest = hook;
@@ -105,6 +116,9 @@ class StateStoreReducerError extends Error {
         this.name = "StateStoreReducerError";
     }
 }
+/** A sampled generation disappeared while it was being read off-lock. */
+class StateStoreGenerationMissingError extends StateStoreCorruptionError {
+}
 /** A recovered v3 store. `append` is the ordinary hot path. */
 export class StateStore {
     options;
@@ -117,6 +131,7 @@ export class StateStore {
     recordCount;
     walBytes;
     maxRecoveryReadBytes;
+    observedHighestSnapshotGeneration;
     constructor(options, recovered, wasCreated) {
         this.options = options;
         this.scopeDigest = digestScope(options.scopeId);
@@ -127,6 +142,7 @@ export class StateStore {
         this.recordCount = recovered.recordCount;
         this.walBytes = recovered.walBytes;
         this.maxRecoveryReadBytes = recovered.maxReadBytes;
+        this.observedHighestSnapshotGeneration = recovered.observedHighestSnapshotGeneration ?? recovered.generation;
         this.wasCreated = wasCreated;
     }
     static exists(rootDir, scopeId) {
@@ -145,24 +161,32 @@ export class StateStore {
         const scopeDigest = digestScope(normalized.scopeId);
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         fs.mkdirSync(dir, { recursive: true });
-        return withScopeLock(dir, () => {
-            cleanupUnpublishedInitialGeneration(dir);
-            const recovered = readNewestGeneration(dir, scopeDigest, normalized.reduce);
-            if (recovered) {
+        while (true) {
+            const recovered = readNewestGenerationOptimistically(dir, scopeDigest, normalized.reduce);
+            if (recovered)
                 return new StateStore(normalized, recovered, false);
-            }
-            const initial = {
-                generation: 1,
-                state: normalized.initialState,
-                lastRecordSequence: 0,
-                recordCount: 0,
-                walBytes: WAL_HEADER_BYTES,
-                maxReadBytes: 0,
-            };
-            writeGeneration(dir, scopeDigest, initial);
-            writeCurrentPointer(dir, initial.generation);
-            return new StateStore(normalized, initial, true);
-        });
+            const created = withScopeLock(dir, () => {
+                cleanupUnpublishedInitialGeneration(dir);
+                if (highestCompleteGenerationOnDisk(dir) !== undefined)
+                    return undefined;
+                if (hasStateStoreArtifacts(dir)) {
+                    throw new StateStoreCorruptionError("no complete generation remains while opening");
+                }
+                const initial = {
+                    generation: 1,
+                    state: normalized.initialState,
+                    lastRecordSequence: 0,
+                    recordCount: 0,
+                    walBytes: WAL_HEADER_BYTES,
+                    maxReadBytes: 0,
+                };
+                writeGeneration(dir, scopeDigest, initial);
+                writeCurrentPointer(dir, initial.generation);
+                return new StateStore(normalized, initial, true);
+            });
+            if (created)
+                return created;
+        }
     }
     /** Yielding first-open variant for callback-originated projections. */
     static async openAsync(options) {
@@ -170,23 +194,32 @@ export class StateStore {
         const scopeDigest = digestScope(normalized.scopeId);
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         await fs.promises.mkdir(dir, { recursive: true });
-        return withScopeLockAsync(dir, () => {
-            cleanupUnpublishedInitialGeneration(dir);
-            const recovered = readNewestGeneration(dir, scopeDigest, normalized.reduce);
+        while (true) {
+            const recovered = await readNewestGenerationOptimisticallyAsync(dir, scopeDigest, normalized.reduce);
             if (recovered)
                 return new StateStore(normalized, recovered, false);
-            const initial = {
-                generation: 1,
-                state: normalized.initialState,
-                lastRecordSequence: 0,
-                recordCount: 0,
-                walBytes: WAL_HEADER_BYTES,
-                maxReadBytes: 0,
-            };
-            writeGeneration(dir, scopeDigest, initial);
-            writeCurrentPointer(dir, initial.generation);
-            return new StateStore(normalized, initial, true);
-        });
+            const created = await withScopeLockAsync(dir, () => {
+                cleanupUnpublishedInitialGeneration(dir);
+                if (highestCompleteGenerationOnDisk(dir) !== undefined)
+                    return undefined;
+                if (hasStateStoreArtifacts(dir)) {
+                    throw new StateStoreCorruptionError("no complete generation remains while opening");
+                }
+                const initial = {
+                    generation: 1,
+                    state: normalized.initialState,
+                    lastRecordSequence: 0,
+                    recordCount: 0,
+                    walBytes: WAL_HEADER_BYTES,
+                    maxReadBytes: 0,
+                };
+                writeGeneration(dir, scopeDigest, initial);
+                writeCurrentPointer(dir, initial.generation);
+                return new StateStore(normalized, initial, true);
+            });
+            if (created)
+                return created;
+        }
     }
     /**
      * Repair an over-budget generation without making appenders wait for snapshot
@@ -200,40 +233,44 @@ export class StateStore {
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         if (!hasSnapshotGeneration(dir))
             return { status: "missing" };
-        const plan = withScopeLock(dir, () => {
-            cleanupUnpublishedInitialGeneration(dir);
-            const newestGeneration = highestSnapshotGenerationOnDisk(dir);
-            if (newestGeneration === undefined)
-                return undefined;
-            if (!maintenance.force) {
-                let walBytes;
-                let snapshotBytes;
-                const currentGeneration = currentGenerationOnDisk(dir);
-                try {
-                    walBytes = fs.statSync(walPath(dir, newestGeneration)).size;
-                    snapshotBytes = fs.statSync(snapshotPath(dir, newestGeneration)).size;
+        let plan;
+        while (!plan) {
+            const preflight = withScopeLock(dir, () => {
+                cleanupUnpublishedInitialGeneration(dir);
+                const newestGeneration = highestCompleteGenerationOnDisk(dir);
+                if (newestGeneration === undefined)
+                    return undefined;
+                if (!maintenance.force && !needsMaintenance(dir, newestGeneration, normalized)) {
+                    return false;
                 }
-                catch {
-                    // Let the structural recovery path below classify/fall back rather
-                    // than turning an incomplete newest generation into a false no-op.
+                return newestGeneration;
+            });
+            if (preflight === undefined) {
+                // Preserve recovery's corruption classification for a crashed or
+                // malformed store that has snapshots but no complete generation.
+                if (hasSnapshotGeneration(dir)) {
+                    readNewestGeneration(dir, scopeDigest, normalized.reduce, maintenance.onProgress, false);
+                    continue;
                 }
-                const overBudget = walBytes === undefined ||
-                    snapshotBytes === undefined ||
-                    retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGeneration) ||
-                    walBytes > normalized.maxWalBytesBeforeCompaction;
-                if (!overBudget)
-                    return undefined;
+                return { status: "missing" };
             }
-            const recovered = readNewestGeneration(dir, scopeDigest, normalized.reduce, maintenance.onProgress);
+            if (preflight === false)
+                return { status: "not-needed" };
+            // Snapshot and WAL replay are read-only.  Do not make appenders wait for
+            // this potentially multi-second materialisation; validate its view before
+            // using it to build a replacement generation.
+            const recovered = readNewestGeneration(dir, scopeDigest, normalized.reduce, maintenance.onProgress, false);
             if (!recovered)
-                return undefined;
-            return {
-                recovered,
-                highestGeneration: highestGenerationOnDisk(dir),
-            };
-        });
-        if (!plan)
-            return hasSnapshotGeneration(dir) ? { status: "not-needed" } : { status: "missing" };
+                continue;
+            plan = withScopeLock(dir, () => {
+                const validated = validateOptimisticRecovery(dir, scopeDigest, normalized.reduce, preflight, recovered);
+                if (!validated)
+                    return undefined;
+                if (!maintenance.force && !needsMaintenance(dir, preflight, normalized))
+                    return undefined;
+                return { recovered: validated, highestGeneration: highestGenerationOnDisk(dir) };
+            });
+        }
         const first = {
             generation: plan.highestGeneration + 1,
             state: plan.recovered.state,
@@ -297,15 +334,26 @@ export class StateStore {
     append(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
-        let compact = false;
-        const result = withScopeLock(this.stateDir, () => {
-            const appended = this.appendUnlocked(type, payload, flags);
-            compact = this.needsCompaction();
-            return appended;
-        });
-        if (compact)
-            this.compact();
-        return result;
+        let recovered = false;
+        while (true) {
+            let compact = false;
+            const result = withScopeLock(this.stateDir, () => {
+                const refresh = this.refreshFromDisk();
+                if (!refresh)
+                    return undefined;
+                const appended = this.appendUnlocked(type, payload, flags, recovered ? { records: [], recovered: true } : refresh);
+                compact = this.needsCompaction();
+                return appended;
+            });
+            if (!result) {
+                this.recoverNewestGenerationOutsideLock();
+                recovered = true;
+                continue;
+            }
+            if (compact)
+                this.compact();
+            return result;
+        }
     }
     /**
      * Async lock acquisition for callback-originated work. The write itself
@@ -315,42 +363,77 @@ export class StateStore {
     async appendAsync(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
-        let compact = false;
-        const result = await withScopeLockAsync(this.stateDir, () => {
-            const appended = this.appendUnlocked(type, payload, flags);
-            compact = this.needsCompaction();
-            return appended;
-        });
-        if (compact)
-            this.compact();
-        return result;
+        let recovered = false;
+        while (true) {
+            let compact = false;
+            const result = await withScopeLockAsync(this.stateDir, () => {
+                const refresh = this.refreshFromDisk();
+                if (!refresh)
+                    return undefined;
+                const appended = this.appendUnlocked(type, payload, flags, recovered ? { records: [], recovered: true } : refresh);
+                compact = this.needsCompaction();
+                return appended;
+            });
+            if (!result) {
+                await this.recoverNewestGenerationOutsideLockAsync();
+                recovered = true;
+                continue;
+            }
+            if (compact)
+                this.compact();
+            return result;
+        }
     }
     /** Conditionally append after obtaining the async scope lock. */
     async appendIfAsync(type, payload, shouldAppend, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
-        let compact = false;
-        const result = await withScopeLockAsync(this.stateDir, () => {
-            if (!shouldAppend())
-                return undefined;
-            const appended = this.appendUnlocked(type, payload, flags);
-            compact = this.needsCompaction();
-            return appended;
-        });
-        if (compact)
-            this.compact();
-        return result;
+        let recovered = false;
+        while (true) {
+            let compact = false;
+            const result = await withScopeLockAsync(this.stateDir, () => {
+                const refresh = this.refreshFromDisk();
+                if (!refresh)
+                    return { retry: true };
+                if (!shouldAppend())
+                    return { retry: false, result: undefined };
+                const appended = this.appendUnlocked(type, payload, flags, recovered ? { records: [], recovered: true } : refresh);
+                compact = this.needsCompaction();
+                return { retry: false, result: appended };
+            });
+            if (result.retry) {
+                await this.recoverNewestGenerationOutsideLockAsync();
+                recovered = true;
+                continue;
+            }
+            if (compact)
+                this.compact();
+            return result.result;
+        }
     }
     /** Refresh only the authenticated unseen WAL suffix when possible. */
     refresh() {
-        return withScopeLock(this.stateDir, () => this.refreshFromDisk());
+        let recovered = false;
+        while (true) {
+            const refreshed = withScopeLock(this.stateDir, () => this.refreshFromDisk());
+            if (refreshed)
+                return recovered ? { records: [], recovered: true } : refreshed;
+            this.recoverNewestGenerationOutsideLock();
+            recovered = true;
+        }
     }
     /** Async counterpart for callback-originated projections. */
     async refreshAsync() {
-        return withScopeLockAsync(this.stateDir, () => this.refreshFromDisk());
+        let recovered = false;
+        while (true) {
+            const refreshed = await withScopeLockAsync(this.stateDir, () => this.refreshFromDisk());
+            if (refreshed)
+                return recovered ? { records: [], recovered: true } : refreshed;
+            await this.recoverNewestGenerationOutsideLockAsync();
+            recovered = true;
+        }
     }
-    appendUnlocked(type, payload, flags) {
-        const refresh = this.refreshFromDisk();
+    appendUnlocked(type, payload, flags, refresh) {
         const record = {
             sequence: this.lastRecordSequence + 1,
             type,
@@ -395,7 +478,8 @@ export class StateStore {
     }
     replaceStateAttempt(nextState) {
         const plan = withScopeLock(this.stateDir, () => {
-            this.refreshFromDisk();
+            if (!this.refreshFromDisk())
+                return undefined;
             const previousGeneration = this.generation;
             const previousWalHasRecords = this.walBytes > WAL_HEADER_BYTES;
             const first = {
@@ -421,6 +505,10 @@ export class StateStore {
                 retainedGeneration,
             };
         });
+        if (!plan) {
+            this.recoverNewestGenerationOutsideLock();
+            return false;
+        }
         const first = stageGeneration(this.stateDir, this.scopeDigest, plan.first);
         let second;
         try {
@@ -434,7 +522,8 @@ export class StateStore {
         }
         try {
             return withScopeLock(this.stateDir, () => {
-                this.refreshFromDisk();
+                if (!this.refreshFromDisk())
+                    return false;
                 if (this.generation !== plan.sourceGeneration ||
                     this.lastRecordSequence !== plan.sourceSequence ||
                     this.walBytes !== plan.sourceWalBytes)
@@ -462,9 +551,14 @@ export class StateStore {
             // keep this claim and retry from the refreshed source instead.
             while (true) {
                 const plan = withScopeLock(this.stateDir, () => {
-                    this.refreshFromDisk();
+                    if (!this.refreshFromDisk())
+                        return undefined;
                     return this.compactionPlan(this.state, this.generation, this.lastRecordSequence, this.walBytes);
                 });
+                if (!plan) {
+                    this.recoverNewestGenerationOutsideLock();
+                    continue;
+                }
                 if (this.publishCompactionPlan(plan))
                     return;
             }
@@ -473,7 +567,7 @@ export class StateStore {
     refreshFromDisk() {
         // The current pointer is deliberately not consulted: ordinary append does
         // not rewrite it.  A newer snapshot generation is the publication signal.
-        if (highestSnapshotGenerationOnDisk(this.stateDir) === this.generation) {
+        if (highestSnapshotGenerationOnDisk(this.stateDir) === this.observedHighestSnapshotGeneration) {
             try {
                 const tail = readWalTail(walPath(this.stateDir, this.generation), this.scopeDigest, this.generation, this.walBytes, this.lastRecordSequence, this.state, this.options.reduce);
                 this.state = tail.state;
@@ -491,11 +585,19 @@ export class StateStore {
                 // stale-pointer and corrupt-newest-generation selection semantics.
             }
         }
-        const recovered = readNewestGeneration(this.stateDir, this.scopeDigest, this.options.reduce);
+        return undefined;
+    }
+    recoverNewestGenerationOutsideLock() {
+        const recovered = readNewestGenerationOptimistically(this.stateDir, this.scopeDigest, this.options.reduce);
+        if (!recovered)
+            throw new StateStoreCorruptionError("no valid generation remains while appending");
+        this.installGeneration(recovered);
+    }
+    async recoverNewestGenerationOutsideLockAsync() {
+        const recovered = await readNewestGenerationOptimisticallyAsync(this.stateDir, this.scopeDigest, this.options.reduce);
         if (!recovered)
             throw new StateStoreCorruptionError("no valid generation remains while appending");
         this.installGeneration(recovered);
-        return { records: [], recovered: true };
     }
     needsCompaction() {
         return this.recordCount >= this.options.maxRecordsBeforeCompaction ||
@@ -522,7 +624,8 @@ export class StateStore {
         try {
             afterGenerationStageHookForTest?.();
             return withScopeLock(this.stateDir, () => {
-                this.refreshFromDisk();
+                if (!this.refreshFromDisk())
+                    return false;
                 if (this.generation !== plan.sourceGeneration ||
                     this.lastRecordSequence !== plan.sourceSequence ||
                     this.walBytes !== plan.sourceWalBytes)
@@ -545,9 +648,10 @@ export class StateStore {
         this.recordCount = generation.recordCount;
         this.walBytes = generation.walBytes;
         this.maxRecoveryReadBytes = generation.maxReadBytes;
+        this.observedHighestSnapshotGeneration = generation.observedHighestSnapshotGeneration ?? generation.generation;
     }
 }
-function readNewestGeneration(dir, scopeDigest, reduce, onProgress) {
+function readNewestGeneration(dir, scopeDigest, reduce, onProgress, repairTornTail = true) {
     const names = fs.readdirSync(dir);
     const generations = names
         .map((name) => /^snapshot-(\d+)\.bin$/.exec(name)?.[1])
@@ -556,9 +660,13 @@ function readNewestGeneration(dir, scopeDigest, reduce, onProgress) {
         .filter(Number.isSafeInteger)
         .sort((a, b) => b - a);
     const errors = [];
+    let sawMissingGeneration = false;
     for (const generation of generations) {
         try {
-            return readGeneration(dir, scopeDigest, generation, reduce, onProgress);
+            return {
+                ...readGeneration(dir, scopeDigest, generation, reduce, onProgress, repairTornTail),
+                observedHighestSnapshotGeneration: generations[0],
+            };
         }
         catch (error) {
             if (error instanceof StateStoreReducerError) {
@@ -566,22 +674,27 @@ function readNewestGeneration(dir, scopeDigest, reduce, onProgress) {
             }
             if (!(error instanceof StateStoreCorruptionError))
                 throw error;
+            if (error instanceof StateStoreGenerationMissingError)
+                sawMissingGeneration = true;
             errors.push(error);
         }
     }
     if (generations.length > 0) {
-        throw new StateStoreCorruptionError("no valid snapshot/WAL generation remains", {
+        const ErrorType = sawMissingGeneration
+            ? StateStoreGenerationMissingError
+            : StateStoreCorruptionError;
+        throw new ErrorType("no valid snapshot/WAL generation remains", {
             cause: errors[0],
         });
     }
     return undefined;
 }
-function readGeneration(dir, scopeDigest, generation, reduce, onProgress) {
+function readGeneration(dir, scopeDigest, generation, reduce, onProgress, repairTornTail = true) {
     const snapshotBytes = generationFileSize(snapshotPath(dir, generation), "snapshot", generation);
     const totalBytes = snapshotBytes + generationFileSize(walPath(dir, generation), "WAL", generation);
     const snapshot = readSnapshot(snapshotPath(dir, generation), scopeDigest, generation);
     onProgress?.({ bytesRead: snapshotBytes, totalBytes });
-    const parsed = readWal(walPath(dir, generation), scopeDigest, generation, snapshot.payload.lastRecordSequence, snapshot.payload.state, reduce, snapshotBytes, totalBytes, onProgress);
+    const parsed = readWal(walPath(dir, generation), scopeDigest, generation, snapshot.payload.lastRecordSequence, snapshot.payload.state, reduce, snapshotBytes, totalBytes, onProgress, repairTornTail);
     return {
         generation,
         state: parsed.state,
@@ -589,8 +702,141 @@ function readGeneration(dir, scopeDigest, generation, reduce, onProgress) {
         recordCount: parsed.recordCount,
         walBytes: parsed.walBytes,
         maxReadBytes: Math.max(snapshot.maxReadBytes, parsed.maxReadBytes),
+        observedWalBytes: parsed.observedWalBytes,
+        tornWalTailBoundary: parsed.tornWalTailBoundary,
+    };
+}
+/**
+ * Snapshots are immutable once published.  Cold recovery therefore parses the
+ * selected snapshot and WAL without append.lock, then validates its generation
+ * under the lock. Appends made during the replay are read as one short locked
+ * WAL suffix rather than restarting the expensive immutable snapshot read.
+ * Rotation or a torn suffix remains lock-protected.
+ */
+function readNewestGenerationOptimistically(dir, scopeDigest, reduce, onProgress) {
+    let resamples = 0;
+    while (true) {
+        const candidate = withScopeLock(dir, () => {
+            cleanupUnpublishedInitialGeneration(dir);
+            return highestCompleteGenerationOnDisk(dir);
+        });
+        if (candidate === undefined)
+            return undefined;
+        let recovered;
+        try {
+            recovered = readNewestGeneration(dir, scopeDigest, reduce, onProgress, false);
+        }
+        catch (error) {
+            if (!(error instanceof StateStoreGenerationMissingError))
+                throw error;
+            const freshCandidate = withScopeLock(dir, () => highestCompleteGenerationOnDisk(dir));
+            if (freshCandidate === candidate)
+                throw error;
+            if (resamples++ >= OPTIMISTIC_RECOVERY_MAX_RESAMPLES) {
+                throw new StateStoreLockError("generation changed repeatedly during optimistic recovery", { cause: error });
+            }
+            continue;
+        }
+        if (!recovered)
+            continue;
+        const validated = withScopeLock(dir, () => validateOptimisticRecovery(dir, scopeDigest, reduce, candidate, recovered));
+        if (validated)
+            return validated;
+    }
+}
+async function readNewestGenerationOptimisticallyAsync(dir, scopeDigest, reduce, onProgress) {
+    let resamples = 0;
+    while (true) {
+        const candidate = await withScopeLockAsync(dir, () => {
+            cleanupUnpublishedInitialGeneration(dir);
+            return highestCompleteGenerationOnDisk(dir);
+        });
+        if (candidate === undefined)
+            return undefined;
+        let recovered;
+        try {
+            recovered = readNewestGeneration(dir, scopeDigest, reduce, onProgress, false);
+        }
+        catch (error) {
+            if (!(error instanceof StateStoreGenerationMissingError))
+                throw error;
+            const freshCandidate = await withScopeLockAsync(dir, () => highestCompleteGenerationOnDisk(dir));
+            if (freshCandidate === candidate)
+                throw error;
+            if (resamples++ >= OPTIMISTIC_RECOVERY_MAX_RESAMPLES) {
+                throw new StateStoreLockError("generation changed repeatedly during optimistic recovery", { cause: error });
+            }
+            continue;
+        }
+        if (!recovered)
+            continue;
+        const validated = await withScopeLockAsync(dir, () => validateOptimisticRecovery(dir, scopeDigest, reduce, candidate, recovered));
+        if (validated)
+            return validated;
+    }
+}
+function validateOptimisticRecovery(dir, scopeDigest, reduce, candidate, recovered) {
+    cleanupUnpublishedInitialGeneration(dir);
+    if (highestCompleteGenerationOnDisk(dir) !== candidate)
+        return undefined;
+    const observedWalBytes = recovered.observedWalBytes ?? recovered.walBytes;
+    const filePath = walPath(dir, recovered.generation);
+    const currentWalBytes = generationFileSize(filePath, "WAL", recovered.generation);
+    if (recovered.tornWalTailBoundary !== undefined) {
+        if (currentWalBytes !== observedWalBytes)
+            return undefined;
+        truncateWal(filePath, recovered.tornWalTailBoundary);
+        return {
+            ...recovered,
+            observedWalBytes: recovered.tornWalTailBoundary,
+            tornWalTailBoundary: undefined,
+        };
+    }
+    if (currentWalBytes < observedWalBytes)
+        return undefined;
+    if (currentWalBytes === observedWalBytes)
+        return recovered;
+    const tail = (() => {
+        try {
+            return readWalTail(filePath, scopeDigest, recovered.generation, recovered.walBytes, recovered.lastRecordSequence, recovered.state, reduce);
+        }
+        catch (error) {
+            // A complete but invalid concurrent suffix makes this generation invalid;
+            // replay selection below can still choose a retained valid generation.
+            if (error instanceof StateStoreCorruptionError)
+                return undefined;
+            throw error;
+        }
+    })();
+    if (!tail)
+        return undefined;
+    return {
+        ...recovered,
+        state: tail.state,
+        lastRecordSequence: tail.lastRecordSequence,
+        recordCount: recovered.recordCount + tail.recordCount,
+        walBytes: tail.walBytes,
+        maxReadBytes: Math.max(recovered.maxReadBytes, tail.maxReadBytes),
+        observedWalBytes: tail.walBytes,
     };
 }
+function needsMaintenance(dir, newestGeneration, options) {
+    let walBytes;
+    let snapshotBytes;
+    const currentGeneration = currentGenerationOnDisk(dir);
+    try {
+        walBytes = fs.statSync(walPath(dir, newestGeneration)).size;
+        snapshotBytes = fs.statSync(snapshotPath(dir, newestGeneration)).size;
+    }
+    catch {
+        // Structural recovery below classifies a missing or incomplete generation;
+        // it must not be mistaken for a healthy no-op.
+    }
+    return walBytes === undefined ||
+        snapshotBytes === undefined ||
+        retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGeneration) ||
+        walBytes > options.maxWalBytesBeforeCompaction;
+}
 function writeGeneration(dir, scopeDigest, generation) {
     const snapshot = encodeSnapshot(generation.generation, scopeDigest, {
         lastRecordSequence: generation.lastRecordSequence,
@@ -733,7 +979,7 @@ function readSnapshot(filePath, scopeDigest, generation) {
     }
     catch (error) {
         if (isMissing(error)) {
-            throw new StateStoreCorruptionError(`snapshot generation ${generation} is missing`, { cause: error });
+            throw new StateStoreGenerationMissingError(`snapshot generation ${generation} is missing`, { cause: error });
         }
         throw new Error(`state-store: cannot read snapshot generation ${generation}`, { cause: error });
     }
@@ -756,6 +1002,7 @@ function readSnapshot(filePath, scopeDigest, generation) {
         if (!header.subarray(20, 52).equals(scopeDigest)) {
             throw new StateStoreCorruptionError(`snapshot generation ${generation} has a scope digest mismatch`);
         }
+        snapshotReadHookForTest?.();
         const data = Buffer.allocUnsafe(payloadLength);
         if (readIntoSync(fd, data, 52) !== data.length) {
             throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn payload`);
@@ -789,20 +1036,21 @@ function readSnapshot(filePath, scopeDigest, generation) {
         fs.closeSync(fd);
     }
 }
-function readWal(filePath, scopeDigest, generation, snapshotSequence, initialState, reduce, recoveryBytesBeforeWal = 0, recoveryTotalBytes, onProgress) {
+function readWal(filePath, scopeDigest, generation, snapshotSequence, initialState, reduce, recoveryBytesBeforeWal = 0, recoveryTotalBytes, onProgress, repairTornTail = true) {
     let fd;
     try {
         fd = fs.openSync(filePath, "r");
     }
     catch (error) {
         if (isMissing(error)) {
-            throw new StateStoreCorruptionError(`WAL generation ${generation} is missing`, { cause: error });
+            throw new StateStoreGenerationMissingError(`WAL generation ${generation} is missing`, { cause: error });
         }
         throw new Error(`state-store: cannot read WAL generation ${generation}`, { cause: error });
     }
     let truncateBoundary;
     try {
         const walBytes = fs.fstatSync(fd).size;
+        walReadHookForTest?.();
         const header = Buffer.alloc(WAL_HEADER_BYTES);
         const headerBytes = readIntoSync(fd, header, 0);
         if (headerBytes < WAL_HEADER_BYTES) {
@@ -879,6 +1127,8 @@ function readWal(filePath, scopeDigest, generation, snapshotSequence, initialSta
             lastRecordSequence: sequence,
             recordCount,
             walBytes: truncateBoundary ?? walBytes,
+            observedWalBytes: walBytes,
+            tornWalTailBoundary: truncateBoundary,
             maxReadBytes,
         };
     }
@@ -890,7 +1140,7 @@ function readWal(filePath, scopeDigest, generation, snapshotSequence, initialSta
     }
     finally {
         fs.closeSync(fd);
-        if (truncateBoundary !== undefined)
+        if (repairTornTail && truncateBoundary !== undefined)
             truncateWal(filePath, truncateBoundary);
     }
 }
@@ -1505,7 +1755,7 @@ function generationFileSize(filePath, kind, generation) {
     }
     catch (error) {
         if (isMissing(error)) {
-            throw new StateStoreCorruptionError(`${kind} generation ${generation} is missing`, {
+            throw new StateStoreGenerationMissingError(`${kind} generation ${generation} is missing`, {
                 cause: error,
             });
         }
@@ -1524,6 +1774,9 @@ function hasSnapshotGeneration(dir) {
         throw new Error(`state-store: cannot inspect ${dir}`, { cause: error });
     }
 }
+function hasStateStoreArtifacts(dir) {
+    return fs.readdirSync(dir).some((name) => name === "current" || /^(?:snapshot|wal)-\d+\.bin$/.test(name));
+}
 function snapshotPath(dir, generation) {
     return path.join(dir, `snapshot-${generation}.bin`);
 }
@@ -1546,6 +1799,21 @@ function highestSnapshotGenerationOnDisk(dir) {
         .filter(Number.isSafeInteger);
     return generations.length === 0 ? undefined : Math.max(...generations);
 }
+/** The highest published generation: both immutable snapshot and WAL exist. */
+function highestCompleteGenerationOnDisk(dir) {
+    const snapshots = new Set();
+    const wals = new Set();
+    for (const name of fs.readdirSync(dir)) {
+        const snapshot = /^snapshot-(\d+)\.bin$/.exec(name);
+        if (snapshot)
+            snapshots.add(Number(snapshot[1]));
+        const wal = /^wal-(\d+)\.bin$/.exec(name);
+        if (wal)
+            wals.add(Number(wal[1]));
+    }
+    const generations = [...snapshots].filter((generation) => wals.has(generation));
+    return generations.length === 0 ? undefined : Math.max(...generations);
+}
 function currentGenerationOnDisk(dir) {
     try {
         const generation = Number(fs.readFileSync(path.join(dir, "current"), "ascii").trim());