@indigoai-us/hq-cloud 6.15.73 → 6.15.75

package/dist/sync/state-store.js

@@ -38,15 +38,66 @@ const MAX_FRAME_BYTES = 256 * 1024 * 1024;
 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;
+let rotationClaimWriteHookForTest;
 export function resetStateStoreSnapshotRecoveryCountForTest() {
     snapshotRecoveryCount = 0;
 }
 export function getStateStoreSnapshotRecoveryCountForTest() {
     return snapshotRecoveryCount;
 }
+export function resetStateStoreSnapshotMaterializationCountForTest() {
+    snapshotMaterializationCount = 0;
+}
+export function getStateStoreSnapshotMaterializationCountForTest() {
+    return snapshotMaterializationCount;
+}
+export function resetStateStoreSnapshotEncodeCountForTest() {
+    snapshotEncodeCount = 0;
+}
+export function getStateStoreSnapshotEncodeCountForTest() {
+    return snapshotEncodeCount;
+}
+/** Test-only seam placed immediately before the expensive snapshot write. */
+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;
+}
+/** Test-only seam for filesystems that do not support forced reflinks. */
+export function setStateStoreReflinkCopyHookForTest(hook) {
+    reflinkCopyHookForTest = hook;
+}
+/** Test-only seam for short positional snapshot writes. */
+export function setStateStorePositionalWriteForTest(write) {
+    positionalWriteForTest = write;
+}
+/** Test-only seam for rotation-claim PID write failures. */
+export function setStateStoreRotationClaimWriteHookForTest(hook) {
+    rotationClaimWriteHookForTest = hook;
+}
 export class StateStoreCorruptionError extends Error {
     constructor(message, options) {
         super(`state-store corruption: ${message}`, options);
@@ -65,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;
@@ -77,6 +131,7 @@ export class StateStore {
     recordCount;
     walBytes;
     maxRecoveryReadBytes;
+    observedHighestSnapshotGeneration;
     constructor(options, recovered, wasCreated) {
         this.options = options;
         this.scopeDigest = digestScope(options.scopeId);
@@ -87,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) {
@@ -105,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) {
@@ -130,28 +194,38 @@ 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 opening it once and refreshing it
-     * a second time. The entire recovery and two-copy publication happens under
-     * the scope lock, so an appender cannot race the migration.
+     * Repair an over-budget generation without making appenders wait for snapshot
+     * I/O.  Recovery captures a stable generation while holding the scope lock,
+     * then materialises the replacement off-lock; publication is conditional on
+     * that source generation still being current.
      */
     static repairIfNeeded(options, maintenance = {}) {
         const normalized = normalizeOptions(options);
@@ -159,50 +233,91 @@ export class StateStore {
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         if (!hasSnapshotGeneration(dir))
             return { status: "missing" };
-        return withScopeLock(dir, () => {
-            cleanupUnpublishedInitialGeneration(dir);
-            const newestGeneration = highestSnapshotGenerationOnDisk(dir);
-            if (newestGeneration === undefined)
-                return { status: "missing" };
-            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 { status: "not-needed" };
+                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 { status: "missing" };
-            const store = new StateStore(normalized, recovered, false);
-            const recoveredGeneration = recovered.generation;
-            const recoveredWalBytes = recovered.walBytes;
-            const firstCompactGeneration = highestGenerationOnDisk(dir) + 1;
-            const first = store.compactGeneration(firstCompactGeneration);
-            const second = store.compactGeneration(firstCompactGeneration + 1);
-            writeCurrentPointer(dir, second.generation);
-            pruneGenerations(dir, [first.generation, second.generation]);
-            store.installGeneration(second);
-            return {
-                status: "repaired",
-                recoveredGeneration,
-                recoveredWalBytes,
-                firstCompactGeneration: first.generation,
-                currentGeneration: second.generation,
-            };
-        });
+                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,
+            lastRecordSequence: plan.recovered.lastRecordSequence,
+            recordCount: 0,
+            walBytes: WAL_HEADER_BYTES,
+            maxReadBytes: 0,
+        };
+        // Keep two rollback-readable generations, but derive the second snapshot
+        // from a copy-on-write clone of the first so one logical repair has one
+        // full snapshot materialisation on filesystems that support reflinks.
+        const next = { ...first, generation: first.generation + 1 };
+        const stagedFirst = stageGeneration(dir, scopeDigest, first);
+        let staged;
+        try {
+            staged = stageGenerationFromSnapshot(dir, scopeDigest, stagedFirst.snapshotTemporary, next);
+        }
+        catch (error) {
+            discardStagedGeneration(stagedFirst);
+            throw error;
+        }
+        try {
+            afterGenerationStageHookForTest?.();
+            return withScopeLock(dir, () => {
+                // A writer won while the snapshot was being built. It has kept the old
+                // WAL authoritative, so leave it alone and let a later maintenance pass
+                // compact a fresh view rather than publishing a stale snapshot.
+                if (highestGenerationOnDisk(dir) !== plan.highestGeneration ||
+                    generationFileSize(walPath(dir, plan.recovered.generation), "WAL", plan.recovered.generation) !== plan.recovered.walBytes)
+                    return { status: "not-needed" };
+                publishStagedGeneration(dir, stagedFirst);
+                publishStagedGeneration(dir, staged);
+                writeCurrentPointer(dir, next.generation);
+                pruneGenerations(dir, [first.generation, next.generation]);
+                return {
+                    status: "repaired",
+                    recoveredGeneration: plan.recovered.generation,
+                    recoveredWalBytes: plan.recovered.walBytes,
+                    firstCompactGeneration: first.generation,
+                    currentGeneration: next.generation,
+                };
+            });
+        }
+        finally {
+            discardStagedGeneration(stagedFirst);
+            discardStagedGeneration(staged);
+        }
     }
     getState() {
         return this.state;
@@ -219,7 +334,26 @@ export class StateStore {
     append(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
-        return withScopeLock(this.stateDir, () => this.appendUnlocked(type, payload, flags));
+        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
@@ -229,24 +363,77 @@ export class StateStore {
     async appendAsync(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
-        return withScopeLockAsync(this.stateDir, () => this.appendUnlocked(type, payload, flags));
+        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");
-        return withScopeLockAsync(this.stateDir, () => shouldAppend() ? this.appendUnlocked(type, payload, flags) : undefined);
+        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,
@@ -271,9 +458,6 @@ export class StateStore {
         this.lastRecordSequence = record.sequence;
         this.recordCount++;
         this.walBytes += frame.length;
-        if (this.recordCount >= this.options.maxRecordsBeforeCompaction ||
-            this.walBytes >= this.options.maxWalBytesBeforeCompaction)
-            this.compactUnlocked();
         return { ...record, refresh };
     }
     /**
@@ -286,33 +470,104 @@ export class StateStore {
      * and retain the prior compact copy.
      */
     replaceState(nextState) {
-        withScopeLock(this.stateDir, () => {
-            this.refreshFromDisk();
+        for (let attempt = 0; attempt < REPLACE_STATE_MAX_ATTEMPTS; attempt++) {
+            if (this.replaceStateAttempt(nextState))
+                return;
+        }
+        throw new StateStoreLockError(`cannot replace state after ${REPLACE_STATE_MAX_ATTEMPTS} concurrent writes`);
+    }
+    replaceStateAttempt(nextState) {
+        const plan = withScopeLock(this.stateDir, () => {
+            if (!this.refreshFromDisk())
+                return undefined;
             const previousGeneration = this.generation;
             const previousWalHasRecords = this.walBytes > WAL_HEADER_BYTES;
-            const first = this.compactGeneration(highestGenerationOnDisk(this.stateDir) + 1, nextState);
+            const first = {
+                generation: highestGenerationOnDisk(this.stateDir) + 1,
+                state: nextState,
+                lastRecordSequence: this.lastRecordSequence,
+                recordCount: 0,
+                walBytes: WAL_HEADER_BYTES,
+                maxReadBytes: 0,
+            };
             let retainedGeneration = previousGeneration;
             let current = first;
             if (previousWalHasRecords) {
-                current = this.compactGeneration(first.generation + 1, nextState);
+                current = { ...first, generation: first.generation + 1 };
                 retainedGeneration = first.generation;
             }
-            writeCurrentPointer(this.stateDir, current.generation);
-            pruneGenerations(this.stateDir, [retainedGeneration, current.generation]);
-            this.installGeneration(current);
+            return {
+                sourceGeneration: previousGeneration,
+                sourceSequence: this.lastRecordSequence,
+                sourceWalBytes: this.walBytes,
+                first,
+                current,
+                retainedGeneration,
+            };
         });
+        if (!plan) {
+            this.recoverNewestGenerationOutsideLock();
+            return false;
+        }
+        const first = stageGeneration(this.stateDir, this.scopeDigest, plan.first);
+        let second;
+        try {
+            second = plan.current.generation === plan.first.generation
+                ? undefined
+                : stageGenerationFromSnapshot(this.stateDir, this.scopeDigest, first.snapshotTemporary, plan.current);
+        }
+        catch (error) {
+            discardStagedGeneration(first);
+            throw error;
+        }
+        try {
+            return withScopeLock(this.stateDir, () => {
+                if (!this.refreshFromDisk())
+                    return false;
+                if (this.generation !== plan.sourceGeneration ||
+                    this.lastRecordSequence !== plan.sourceSequence ||
+                    this.walBytes !== plan.sourceWalBytes)
+                    return false;
+                publishStagedGeneration(this.stateDir, first);
+                if (second)
+                    publishStagedGeneration(this.stateDir, second);
+                writeCurrentPointer(this.stateDir, plan.current.generation);
+                pruneGenerations(this.stateDir, [plan.retainedGeneration, plan.current.generation]);
+                this.installGeneration(plan.current);
+                return true;
+            });
+        }
+        finally {
+            discardStagedGeneration(first);
+            if (second)
+                discardStagedGeneration(second);
+        }
     }
     /** Create G+1 without ever merging two generations during recovery. */
     compact() {
-        withScopeLock(this.stateDir, () => {
-            this.refreshFromDisk();
-            this.compactUnlocked();
+        withRotationClaim(this.stateDir, () => {
+            // Appenders do not wait for rotation.lock. If one advances the source
+            // while this claim owns off-lock staging, it will skip its own compact;
+            // keep this claim and retry from the refreshed source instead.
+            while (true) {
+                const plan = withScopeLock(this.stateDir, () => {
+                    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;
+            }
         });
     }
     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;
@@ -330,30 +585,61 @@ 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);
-        return { records: [], recovered: true };
-    }
-    compactUnlocked() {
-        const previousGeneration = this.generation;
-        const next = this.compactGeneration(highestGenerationOnDisk(this.stateDir) + 1);
-        writeCurrentPointer(this.stateDir, next.generation);
-        pruneGenerations(this.stateDir, [previousGeneration, next.generation]);
-        this.installGeneration(next);
-    }
-    compactGeneration(generation, state = this.state) {
-        const next = {
-            generation,
-            state,
-            lastRecordSequence: this.lastRecordSequence,
-            recordCount: 0,
-            walBytes: WAL_HEADER_BYTES,
-            maxReadBytes: 0,
+    }
+    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);
+    }
+    needsCompaction() {
+        return this.recordCount >= this.options.maxRecordsBeforeCompaction ||
+            this.walBytes >= this.options.maxWalBytesBeforeCompaction;
+    }
+    compactionPlan(state, sourceGeneration, sourceSequence, sourceWalBytes) {
+        return {
+            sourceGeneration,
+            sourceSequence,
+            sourceWalBytes,
+            next: {
+                generation: highestGenerationOnDisk(this.stateDir) + 1,
+                state,
+                lastRecordSequence: sourceSequence,
+                recordCount: 0,
+                walBytes: WAL_HEADER_BYTES,
+                maxReadBytes: 0,
+            },
         };
-        writeGeneration(this.stateDir, this.scopeDigest, next);
-        return next;
+    }
+    /** Materialise off-lock, then publish only if no writer advanced the source. */
+    publishCompactionPlan(plan) {
+        const staged = stageGeneration(this.stateDir, this.scopeDigest, plan.next);
+        try {
+            afterGenerationStageHookForTest?.();
+            return withScopeLock(this.stateDir, () => {
+                if (!this.refreshFromDisk())
+                    return false;
+                if (this.generation !== plan.sourceGeneration ||
+                    this.lastRecordSequence !== plan.sourceSequence ||
+                    this.walBytes !== plan.sourceWalBytes)
+                    return false;
+                publishStagedGeneration(this.stateDir, staged);
+                writeCurrentPointer(this.stateDir, plan.next.generation);
+                pruneGenerations(this.stateDir, [plan.sourceGeneration, plan.next.generation]);
+                this.installGeneration(plan.next);
+                return true;
+            });
+        }
+        finally {
+            discardStagedGeneration(staged);
+        }
     }
     installGeneration(generation) {
         this.generation = generation.generation;
@@ -362,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])
@@ -373,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) {
@@ -383,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,
@@ -406,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,
@@ -418,6 +847,130 @@ function writeGeneration(dir, scopeDigest, generation) {
     const header = encodeWalHeader(generation.generation, scopeDigest);
     writeNewDurably(walPath(dir, generation.generation), header);
 }
+/**
+ * Build both files for a generation before taking append.lock for publication.
+ * Temporary names never match the recovery generation pattern, so a process
+ * crash here leaves the prior complete generation authoritative.
+ */
+function stageGeneration(dir, scopeDigest, generation) {
+    snapshotMaterializationCount++;
+    const snapshot = encodeSnapshot(generation.generation, scopeDigest, {
+        lastRecordSequence: generation.lastRecordSequence,
+        state: generation.state,
+    });
+    let snapshotTemporary;
+    let walTemporary;
+    try {
+        snapshotTemporary = writeDurableTemporary(dir, `snapshot-${generation.generation}`, snapshot);
+        walTemporary = writeDurableTemporary(dir, `wal-${generation.generation}`, encodeWalHeader(generation.generation, scopeDigest));
+        return { generation, snapshotTemporary, walTemporary };
+    }
+    catch (error) {
+        if (snapshotTemporary !== undefined)
+            try {
+                fs.rmSync(snapshotTemporary, { force: true });
+            }
+            catch { /* preserve staging error */ }
+        if (walTemporary !== undefined)
+            try {
+                fs.rmSync(walTemporary, { force: true });
+            }
+            catch { /* preserve staging error */ }
+        throw error;
+    }
+}
+/**
+ * Make the rollback copy without serialising or writing the snapshot payload a
+ * second time when the store directory is on a reflink-capable filesystem.
+ */
+function stageGenerationFromSnapshot(dir, scopeDigest, sourceSnapshot, generation) {
+    const snapshotTemporary = temporaryPath(dir, `snapshot-${generation.generation}`);
+    let walTemporary;
+    try {
+        try {
+            reflinkCopyHookForTest?.();
+            fs.copyFileSync(sourceSnapshot, snapshotTemporary, fs.constants.COPYFILE_FICLONE_FORCE);
+            rewriteStagedSnapshotGeneration(snapshotTemporary, generation.generation);
+        }
+        catch {
+            // Reflinks are an optimisation, not a storage prerequisite. Reuse the
+            // bytes already encoded for the first snapshot on filesystems without
+            // clone support rather than materialising the state a second time.
+            if (fs.existsSync(snapshotTemporary))
+                fs.rmSync(snapshotTemporary, { force: true });
+            fs.copyFileSync(sourceSnapshot, snapshotTemporary);
+            rewriteStagedSnapshotGeneration(snapshotTemporary, generation.generation);
+        }
+        walTemporary = writeDurableTemporary(dir, `wal-${generation.generation}`, encodeWalHeader(generation.generation, scopeDigest));
+        return { generation, snapshotTemporary, walTemporary };
+    }
+    catch (error) {
+        try {
+            fs.rmSync(snapshotTemporary, { force: true });
+        }
+        catch { /* preserve staging error */ }
+        if (walTemporary !== undefined)
+            try {
+                fs.rmSync(walTemporary, { force: true });
+            }
+            catch { /* preserve staging error */ }
+        throw error;
+    }
+}
+function rewriteStagedSnapshotGeneration(filePath, generation) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r+");
+        const header = Buffer.alloc(52);
+        if (readIntoSync(fd, header, 0) !== header.length)
+            throw new Error("state-store: cloned snapshot header is torn");
+        writeU64(header, generation, 8);
+        writeAllAtSync(fd, header, 0);
+        const payloadLength = header.readUInt32BE(16);
+        const hash = crypto.createHash("sha256").update(header);
+        const chunk = Buffer.allocUnsafe(Math.min(payloadLength, 1024 * 1024));
+        let offset = 0;
+        while (offset < payloadLength) {
+            const length = Math.min(chunk.length, payloadLength - offset);
+            if (readIntoSync(fd, chunk.subarray(0, length), 52 + offset) !== length) {
+                throw new Error("state-store: cloned snapshot payload is torn");
+            }
+            hash.update(chunk.subarray(0, length));
+            offset += length;
+        }
+        const checksum = hash.digest();
+        writeAllAtSync(fd, checksum, 52 + payloadLength);
+        fs.fdatasyncSync(fd);
+    }
+    catch (error) {
+        throw new Error(`state-store: failed to prepare cloned snapshot generation ${generation}`, { cause: error });
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** Publish already-fsynced files; this is the only snapshot-rotation I/O under the lock. */
+function publishStagedGeneration(dir, staged) {
+    try {
+        fs.renameSync(staged.snapshotTemporary, snapshotPath(dir, staged.generation.generation));
+        fs.renameSync(staged.walTemporary, walPath(dir, staged.generation.generation));
+        fsyncDirectory(dir);
+    }
+    catch (error) {
+        throw new Error(`state-store: staged generation publication failed for ${staged.generation.generation}`, { cause: error });
+    }
+}
+function discardStagedGeneration(staged) {
+    try {
+        fs.rmSync(staged.snapshotTemporary, { force: true });
+    }
+    catch { /* staged files are best-effort cleanup */ }
+    try {
+        fs.rmSync(staged.walTemporary, { force: true });
+    }
+    catch { /* staged files are best-effort cleanup */ }
+}
 function readSnapshot(filePath, scopeDigest, generation) {
     snapshotRecoveryCount++;
     let fd;
@@ -426,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 });
     }
@@ -449,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`);
@@ -482,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) {
@@ -572,6 +1127,8 @@ function readWal(filePath, scopeDigest, generation, snapshotSequence, initialSta
             lastRecordSequence: sequence,
             recordCount,
             walBytes: truncateBoundary ?? walBytes,
+            observedWalBytes: walBytes,
+            tornWalTailBoundary: truncateBoundary,
             maxReadBytes,
         };
     }
@@ -583,7 +1140,7 @@ function readWal(filePath, scopeDigest, generation, snapshotSequence, initialSta
     }
     finally {
         fs.closeSync(fd);
-        if (truncateBoundary !== undefined)
+        if (repairTornTail && truncateBoundary !== undefined)
             truncateWal(filePath, truncateBoundary);
     }
 }
@@ -759,6 +1316,7 @@ function decodeFrame(bytes, offset) {
     };
 }
 function encodeSnapshot(generation, scopeDigest, payload) {
+    snapshotEncodeCount++;
     const data = Buffer.from(canonicalJson(payload), "utf8");
     const header = Buffer.alloc(52);
     SNAPSHOT_MAGIC.copy(header, 0);
@@ -845,6 +1403,35 @@ function writeDurableTempThenRename(dir, destination, bytes) {
         throw new Error(`state-store: snapshot write/rename failed for ${destination}`, { cause: error });
     }
 }
+function writeDurableTemporary(dir, label, bytes) {
+    const temporary = temporaryPath(dir, label);
+    writeDurableTemporaryAt(temporary, bytes, label);
+    return temporary;
+}
+function temporaryPath(dir, label) {
+    return path.join(dir, `.${label}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+}
+function writeDurableTemporaryAt(temporary, bytes, label) {
+    let fd;
+    try {
+        fd = fs.openSync(temporary, "wx");
+        if (label.startsWith("snapshot-"))
+            snapshotWriteHookForTest?.();
+        writeAllSync(fd, bytes);
+        fs.fdatasyncSync(fd);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch { /* preserve durable-write error */ }
+        throw new Error(`state-store: staged write failed for ${label}`, { cause: error });
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
 function writeCurrentPointer(dir, generation) {
     const pointer = path.join(dir, "current");
     writeDurableTempThenRename(dir, pointer, Buffer.from(`${generation}\n`, "ascii"));
@@ -858,6 +1445,18 @@ function writeAllSync(fd, bytes) {
         offset += written;
     }
 }
+function writeAllAtSync(fd, bytes, position) {
+    let offset = 0;
+    while (offset < bytes.length) {
+        const length = bytes.length - offset;
+        const written = positionalWriteForTest
+            ? positionalWriteForTest(fd, bytes, offset, length, position + offset)
+            : fs.writeSync(fd, bytes, offset, length, position + offset);
+        if (written <= 0)
+            throw new Error("state-store: short positional write made no progress");
+        offset += written;
+    }
+}
 function readIntoSync(fd, target, position) {
     let offset = 0;
     while (offset < target.length) {
@@ -911,6 +1510,73 @@ function withScopeLock(dir, action) {
         throw actionError;
     return result;
 }
+/**
+ * A best-effort, non-blocking claim for off-lock snapshot materialisation.
+ * Appenders deliberately ignore it; it only prevents several stale handles
+ * from concurrently staging the same logical rotation.
+ */
+function withRotationClaim(dir, action) {
+    const claimPath = path.join(dir, "rotation.lock");
+    let fd;
+    for (let attempt = 0; attempt < 2 && fd === undefined; attempt++) {
+        try {
+            fd = fs.openSync(claimPath, "wx");
+            rotationClaimWriteHookForTest?.();
+            fs.writeFileSync(fd, String(process.pid));
+            fs.fdatasyncSync(fd);
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                let closeError;
+                try {
+                    fs.closeSync(fd);
+                }
+                catch (cleanupError) {
+                    closeError = cleanupError;
+                }
+                finally {
+                    fd = undefined;
+                }
+                try {
+                    fs.unlinkSync(claimPath);
+                }
+                catch (cleanupError) {
+                    if (!isMissing(cleanupError)) {
+                        throw new StateStoreLockError(`cannot clean up ${claimPath}`, { cause: cleanupError });
+                    }
+                }
+                if (closeError !== undefined) {
+                    throw new StateStoreLockError(`cannot close ${claimPath}`, { cause: closeError });
+                }
+                return undefined;
+            }
+            if (!isAlreadyExists(error) || !removeDeadLock(claimPath))
+                return undefined;
+        }
+    }
+    if (fd === undefined)
+        return undefined;
+    let result;
+    let actionError;
+    try {
+        result = action();
+    }
+    catch (error) {
+        actionError = error;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.unlinkSync(claimPath);
+    }
+    catch (error) {
+        throw new Error(`state-store: cannot release ${claimPath}`, { cause: error });
+    }
+    if (actionError !== undefined)
+        throw actionError;
+    return result;
+}
 /**
  * Acquire the same inter-process lock without parking the Node event loop
  * while another writer owns it. This is deliberately additive: pass-side
@@ -968,7 +1634,7 @@ function removeDeadLock(lockPath) {
         return isMissing(error);
     }
     if (!Number.isSafeInteger(pid) || pid <= 0)
-        return false;
+        return removeMalformedLock(lockPath);
     try {
         process.kill(pid, 0);
         return false;
@@ -996,7 +1662,7 @@ async function removeDeadLockAsync(lockPath) {
         return false;
     }
     if (!Number.isSafeInteger(pid) || pid <= 0)
-        return false;
+        return removeMalformedLockAsync(lockPath);
     try {
         process.kill(pid, 0);
         return false;
@@ -1015,6 +1681,24 @@ async function removeDeadLockAsync(lockPath) {
         return false;
     }
 }
+function removeMalformedLock(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        return isMissing(error);
+    }
+}
+async function removeMalformedLockAsync(lockPath) {
+    try {
+        await fs.promises.unlink(lockPath);
+        return true;
+    }
+    catch (error) {
+        return isMissing(error);
+    }
+}
 function truncateWal(filePath, boundary) {
     let fd;
     try {
@@ -1071,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,
             });
         }
@@ -1090,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`);
 }
@@ -1112,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());