@indigoai-us/hq-cloud 6.15.6 → 6.15.7

package/dist/sync/state-store.js

@@ -16,6 +16,7 @@ const WAL_HEADER_BYTES = 8 + 8 + 32 + 32;
 const FRAME_PREFIX_BYTES = 4 + 4;
 const FRAME_FIXED_BODY_BYTES = 8 + 2 + 2 + 4 + 4 + 32;
 const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_WAL_BYTES_BEFORE_COMPACTION = 16 * 1024 * 1024;
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 5_000;
 export class StateStoreCorruptionError extends Error {
@@ -30,6 +31,12 @@ class StateStoreLockError extends Error {
         this.name = "StateStoreLockError";
     }
 }
+class StateStoreReducerError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "StateStoreReducerError";
+    }
+}
 /** A recovered v3 store. `append` is the ordinary hot path. */
 export class StateStore {
     options;
@@ -40,6 +47,8 @@ export class StateStore {
     state;
     lastRecordSequence;
     recordCount;
+    walBytes;
+    maxRecoveryReadBytes;
     constructor(options, recovered, wasCreated) {
         this.options = options;
         this.scopeDigest = digestScope(options.scopeId);
@@ -48,6 +57,8 @@ export class StateStore {
         this.state = recovered.state;
         this.lastRecordSequence = recovered.lastRecordSequence;
         this.recordCount = recovered.recordCount;
+        this.walBytes = recovered.walBytes;
+        this.maxRecoveryReadBytes = recovered.maxReadBytes;
         this.wasCreated = wasCreated;
     }
     static exists(rootDir, scopeId) {
@@ -62,32 +73,86 @@ export class StateStore {
         }
     }
     static open(options) {
-        if (!options.scopeId)
-            throw new Error("state-store: scopeId is required");
-        const normalized = {
-            ...options,
-            maxRecordsBeforeCompaction: options.maxRecordsBeforeCompaction ?? 256,
-        };
-        if (normalized.maxRecordsBeforeCompaction < 1) {
-            throw new Error("state-store: maxRecordsBeforeCompaction must be positive");
-        }
+        const normalized = normalizeOptions(options);
         const scopeDigest = digestScope(normalized.scopeId);
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         fs.mkdirSync(dir, { recursive: true });
-        cleanupUnpublishedInitialGeneration(dir);
-        const generations = readGenerations(dir, scopeDigest, normalized.reduce);
-        if (generations.length > 0) {
-            return new StateStore(normalized, generations[0], false);
-        }
-        const initial = {
-            generation: 1,
-            state: normalized.initialState,
-            lastRecordSequence: 0,
-            recordCount: 0,
-        };
-        writeGeneration(dir, scopeDigest, initial);
-        writeCurrentPointer(dir, initial.generation);
-        return new StateStore(normalized, initial, true);
+        return withScopeLock(dir, () => {
+            cleanupUnpublishedInitialGeneration(dir);
+            const recovered = readNewestGeneration(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);
+        });
+    }
+    /**
+     * 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.
+     */
+    static repairIfNeeded(options, maintenance = {}) {
+        const normalized = normalizeOptions(options);
+        const scopeDigest = digestScope(normalized.scopeId);
+        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;
+                }
+                catch {
+                    // Let the structural recovery path below classify/fall back rather
+                    // than turning an incomplete newest generation into a false no-op.
+                }
+                const overBudget = walBytes === undefined ||
+                    snapshotBytes === undefined ||
+                    retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGeneration) ||
+                    walBytes > normalized.maxWalBytesBeforeCompaction ||
+                    (walBytes > WAL_HEADER_BYTES &&
+                        snapshotBytes > normalized.maxWalBytesBeforeCompaction);
+                if (!overBudget)
+                    return { status: "not-needed" };
+            }
+            const recovered = readNewestGeneration(dir, scopeDigest, normalized.reduce, maintenance.onProgress);
+            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,
+            };
+        });
     }
     getState() {
         return this.state;
@@ -98,6 +163,9 @@ export class StateStore {
     getLastRecordSequence() {
         return this.lastRecordSequence;
     }
+    getRecoveryStats() {
+        return { walBytes: this.walBytes, maxReadBytes: this.maxRecoveryReadBytes };
+    }
     append(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
@@ -114,15 +182,44 @@ export class StateStore {
             }
             // Validate reducer acceptance before making this frame durable.
             const nextState = this.options.reduce(this.state, record);
-            appendDurably(walPath(this.stateDir, this.generation), encodeFrame(record));
+            const frame = encodeFrame(record);
+            appendDurably(walPath(this.stateDir, this.generation), frame);
             this.state = nextState;
             this.lastRecordSequence = record.sequence;
             this.recordCount++;
-            if (this.recordCount >= this.options.maxRecordsBeforeCompaction)
+            this.walBytes += frame.length;
+            if (this.recordCount >= this.options.maxRecordsBeforeCompaction ||
+                this.walBytes >= this.options.maxWalBytesBeforeCompaction)
                 this.compactUnlocked();
             return record;
         });
     }
+    /**
+     * Atomically replace the current state with a compact snapshot generation.
+     *
+     * This is the rollback-compatible write path for domains whose previous
+     * reducer cannot understand a new WAL record type. If the recovered
+     * generation contains records, publish two compact copies so every retained
+     * WAL is header-only before pruning it. Later replacements need one new copy
+     * and retain the prior compact copy.
+     */
+    replaceState(nextState) {
+        withScopeLock(this.stateDir, () => {
+            this.refreshFromDisk();
+            const previousGeneration = this.generation;
+            const previousWalHasRecords = this.walBytes > WAL_HEADER_BYTES;
+            const first = this.compactGeneration(highestGenerationOnDisk(this.stateDir) + 1, nextState);
+            let retainedGeneration = previousGeneration;
+            let current = first;
+            if (previousWalHasRecords) {
+                current = this.compactGeneration(first.generation + 1, nextState);
+                retainedGeneration = first.generation;
+            }
+            writeCurrentPointer(this.stateDir, current.generation);
+            pruneGenerations(this.stateDir, [retainedGeneration, current.generation]);
+            this.installGeneration(current);
+        });
+    }
     /** Create G+1 without ever merging two generations during recovery. */
     compact() {
         withScopeLock(this.stateDir, () => {
@@ -131,31 +228,41 @@ export class StateStore {
         });
     }
     refreshFromDisk() {
-        const recovered = readGenerations(this.stateDir, this.scopeDigest, this.options.reduce);
-        if (recovered.length === 0) {
+        const recovered = readNewestGeneration(this.stateDir, this.scopeDigest, this.options.reduce);
+        if (!recovered) {
             throw new StateStoreCorruptionError("no valid generation remains while appending");
         }
-        const current = recovered[0];
-        this.generation = current.generation;
-        this.state = current.state;
-        this.lastRecordSequence = current.lastRecordSequence;
-        this.recordCount = current.recordCount;
+        this.installGeneration(recovered);
     }
     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: highestGenerationOnDisk(this.stateDir) + 1,
-            state: this.state,
+            generation,
+            state,
             lastRecordSequence: this.lastRecordSequence,
             recordCount: 0,
+            walBytes: WAL_HEADER_BYTES,
+            maxReadBytes: 0,
         };
         writeGeneration(this.stateDir, this.scopeDigest, next);
-        writeCurrentPointer(this.stateDir, next.generation);
-        pruneGenerations(this.stateDir, [this.generation, next.generation]);
-        this.generation = next.generation;
-        this.recordCount = 0;
+        return next;
+    }
+    installGeneration(generation) {
+        this.generation = generation.generation;
+        this.state = generation.state;
+        this.lastRecordSequence = generation.lastRecordSequence;
+        this.recordCount = generation.recordCount;
+        this.walBytes = generation.walBytes;
+        this.maxRecoveryReadBytes = generation.maxReadBytes;
     }
 }
-function readGenerations(dir, scopeDigest, reduce) {
+function readNewestGeneration(dir, scopeDigest, reduce, onProgress) {
     const names = fs.readdirSync(dir);
     const generations = names
         .map((name) => /^snapshot-(\d+)\.bin$/.exec(name)?.[1])
@@ -163,37 +270,40 @@ function readGenerations(dir, scopeDigest, reduce) {
         .map(Number)
         .filter(Number.isSafeInteger)
         .sort((a, b) => b - a);
-    const recovered = [];
     const errors = [];
     for (const generation of generations) {
         try {
-            recovered.push(readGeneration(dir, scopeDigest, generation, reduce));
+            return readGeneration(dir, scopeDigest, generation, reduce, onProgress);
         }
         catch (error) {
-            if (!(error instanceof StateStoreCorruptionError)) {
+            if (error instanceof StateStoreReducerError) {
                 throw new Error(`state-store: reducer rejected generation ${generation}`, { cause: error });
             }
+            if (!(error instanceof StateStoreCorruptionError))
+                throw error;
             errors.push(error);
         }
     }
-    if (recovered.length === 0 && generations.length > 0) {
+    if (generations.length > 0) {
         throw new StateStoreCorruptionError("no valid snapshot/WAL generation remains", {
             cause: errors[0],
         });
     }
-    return recovered;
+    return undefined;
 }
-function readGeneration(dir, scopeDigest, generation, reduce) {
+function readGeneration(dir, scopeDigest, generation, reduce, onProgress) {
+    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);
-    const parsed = readWal(walPath(dir, generation), scopeDigest, generation, snapshot.lastRecordSequence);
-    let state = snapshot.state;
-    for (const record of parsed.records)
-        state = reduce(state, record);
+    onProgress?.({ bytesRead: snapshotBytes, totalBytes });
+    const parsed = readWal(walPath(dir, generation), scopeDigest, generation, snapshot.payload.lastRecordSequence, snapshot.payload.state, reduce, snapshotBytes, totalBytes, onProgress);
     return {
         generation,
-        state,
+        state: parsed.state,
         lastRecordSequence: parsed.lastRecordSequence,
-        recordCount: parsed.records.length,
+        recordCount: parsed.recordCount,
+        walBytes: parsed.walBytes,
+        maxReadBytes: Math.max(snapshot.maxReadBytes, parsed.maxReadBytes),
     };
 }
 function writeGeneration(dir, scopeDigest, generation) {
@@ -207,71 +317,172 @@ function writeGeneration(dir, scopeDigest, generation) {
     writeNewDurably(walPath(dir, generation.generation), header);
 }
 function readSnapshot(filePath, scopeDigest, generation) {
-    let bytes;
+    let fd;
     try {
-        bytes = fs.readFileSync(filePath);
+        fd = fs.openSync(filePath, "r");
     }
     catch (error) {
-        throw new StateStoreCorruptionError(`cannot read snapshot generation ${generation}`, { cause: error });
-    }
-    if (bytes.length < SNAPSHOT_HEADER_BYTES) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn header`);
-    }
-    if (!bytes.subarray(0, 8).equals(SNAPSHOT_MAGIC)) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid magic`);
-    }
-    if (readU64(bytes, 8) !== generation) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has a generation mismatch`);
-    }
-    const payloadLength = bytes.readUInt32BE(16);
-    if (bytes.length !== SNAPSHOT_HEADER_BYTES + payloadLength) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid payload length`);
-    }
-    if (!bytes.subarray(20, 52).equals(scopeDigest)) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has a scope digest mismatch`);
-    }
-    const expected = sha256(bytes.subarray(0, 52 + payloadLength));
-    if (!expected.equals(bytes.subarray(52 + payloadLength))) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has a bad checksum`);
+        if (isMissing(error)) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} is missing`, { cause: error });
+        }
+        throw new Error(`state-store: cannot read snapshot generation ${generation}`, { cause: error });
     }
-    let decoded;
     try {
-        decoded = JSON.parse(bytes.subarray(52, 52 + payloadLength).toString("utf8"));
+        const stat = fs.fstatSync(fd);
+        const header = Buffer.alloc(52);
+        if (readIntoSync(fd, header, 0) !== header.length) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn header`);
+        }
+        if (!header.subarray(0, 8).equals(SNAPSHOT_MAGIC)) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid magic`);
+        }
+        if (readU64(header, 8) !== generation) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a generation mismatch`);
+        }
+        const payloadLength = header.readUInt32BE(16);
+        if (stat.size !== SNAPSHOT_HEADER_BYTES + payloadLength) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid payload length`);
+        }
+        if (!header.subarray(20, 52).equals(scopeDigest)) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a scope digest mismatch`);
+        }
+        const data = Buffer.allocUnsafe(payloadLength);
+        if (readIntoSync(fd, data, 52) !== data.length) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn payload`);
+        }
+        const checksum = Buffer.alloc(32);
+        if (readIntoSync(fd, checksum, 52 + payloadLength) !== checksum.length) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a torn checksum`);
+        }
+        const expected = crypto.createHash("sha256").update(header).update(data).digest();
+        if (!expected.equals(checksum)) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has a bad checksum`);
+        }
+        let decoded;
+        try {
+            decoded = JSON.parse(data.toString("utf8"));
+        }
+        catch (error) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has invalid JSON`, { cause: error });
+        }
+        if (!isSnapshotPayload(decoded)) {
+            throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid state payload`);
+        }
+        return { payload: decoded, maxReadBytes: data.length };
     }
     catch (error) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has invalid JSON`, { cause: error });
+        if (error instanceof StateStoreCorruptionError)
+            throw error;
+        throw new Error(`state-store: cannot read snapshot generation ${generation}`, { cause: error });
     }
-    if (!isSnapshotPayload(decoded)) {
-        throw new StateStoreCorruptionError(`snapshot generation ${generation} has an invalid state payload`);
+    finally {
+        fs.closeSync(fd);
     }
-    return decoded;
 }
-function readWal(filePath, scopeDigest, generation, snapshotSequence) {
-    let bytes;
+function readWal(filePath, scopeDigest, generation, snapshotSequence, initialState, reduce, recoveryBytesBeforeWal = 0, recoveryTotalBytes, onProgress) {
+    let fd;
     try {
-        bytes = fs.readFileSync(filePath);
+        fd = fs.openSync(filePath, "r");
     }
     catch (error) {
-        throw new StateStoreCorruptionError(`cannot read WAL generation ${generation}`, { cause: error });
+        if (isMissing(error)) {
+            throw new StateStoreCorruptionError(`WAL generation ${generation} is missing`, { cause: error });
+        }
+        throw new Error(`state-store: cannot read WAL generation ${generation}`, { cause: error });
     }
-    verifyWalHeader(bytes, scopeDigest, generation);
-    const records = [];
-    let offset = WAL_HEADER_BYTES;
-    let sequence = snapshotSequence;
-    while (offset < bytes.length) {
-        const parsed = decodeFrame(bytes, offset);
-        if (parsed.kind === "torn") {
-            truncateWal(filePath, offset);
-            break;
+    let truncateBoundary;
+    try {
+        const walBytes = fs.fstatSync(fd).size;
+        const header = Buffer.alloc(WAL_HEADER_BYTES);
+        const headerBytes = readIntoSync(fd, header, 0);
+        if (headerBytes < WAL_HEADER_BYTES) {
+            throw new StateStoreCorruptionError(`WAL generation ${generation} has a torn header`);
         }
-        if (parsed.record.sequence !== sequence + 1) {
-            throw new StateStoreCorruptionError(`WAL generation ${generation} has non-contiguous record sequence`);
+        verifyWalHeader(header, scopeDigest, generation);
+        let state = initialState;
+        let offset = WAL_HEADER_BYTES;
+        let sequence = snapshotSequence;
+        let recordCount = 0;
+        let maxReadBytes = header.length;
+        while (offset < walBytes) {
+            const prefix = Buffer.alloc(FRAME_PREFIX_BYTES);
+            if (readIntoSync(fd, prefix, offset) < FRAME_PREFIX_BYTES) {
+                truncateBoundary = offset;
+                break;
+            }
+            if (prefix.readUInt32BE(0) !== FRAME_MAGIC) {
+                throw new StateStoreCorruptionError("WAL has an invalid frame magic");
+            }
+            const frameLength = prefix.readUInt32BE(4);
+            if (frameLength < FRAME_FIXED_BODY_BYTES || frameLength > MAX_FRAME_BYTES) {
+                throw new StateStoreCorruptionError("WAL has an invalid frame length");
+            }
+            const available = walBytes - offset - FRAME_PREFIX_BYTES;
+            if (available < frameLength) {
+                if (available >= 16) {
+                    const fixed = Buffer.alloc(16);
+                    readIntoSync(fd, fixed, offset + FRAME_PREFIX_BYTES);
+                    const declaredPayloadLength = fixed.readUInt32BE(12);
+                    const declaredFrameLength = FRAME_FIXED_BODY_BYTES + declaredPayloadLength;
+                    if (declaredFrameLength <= available && declaredFrameLength !== frameLength) {
+                        throw new StateStoreCorruptionError("WAL frame length prefix is corrupt");
+                    }
+                }
+                truncateBoundary = offset;
+                break;
+            }
+            const frame = Buffer.allocUnsafe(FRAME_PREFIX_BYTES + frameLength);
+            prefix.copy(frame);
+            if (readIntoSync(fd, frame.subarray(FRAME_PREFIX_BYTES), offset + FRAME_PREFIX_BYTES) !== frameLength) {
+                truncateBoundary = offset;
+                break;
+            }
+            maxReadBytes = Math.max(maxReadBytes, frame.length);
+            const parsed = decodeFrame(frame, 0);
+            if (parsed.kind === "torn") {
+                truncateBoundary = offset;
+                break;
+            }
+            if (parsed.record.sequence !== sequence + 1) {
+                throw new StateStoreCorruptionError(`WAL generation ${generation} has non-contiguous record sequence`);
+            }
+            try {
+                state = reduce(state, parsed.record);
+            }
+            catch (error) {
+                throw new StateStoreReducerError(`record ${parsed.record.sequence} was rejected`, { cause: error });
+            }
+            sequence = parsed.record.sequence;
+            recordCount++;
+            offset += frame.length;
+            onProgress?.({
+                bytesRead: recoveryBytesBeforeWal + offset,
+                totalBytes: recoveryTotalBytes ?? recoveryBytesBeforeWal + walBytes,
+            });
         }
-        records.push(parsed.record);
-        sequence = parsed.record.sequence;
-        offset = parsed.nextOffset;
+        onProgress?.({
+            bytesRead: recoveryBytesBeforeWal + (truncateBoundary ?? walBytes),
+            totalBytes: recoveryTotalBytes ?? recoveryBytesBeforeWal + walBytes,
+        });
+        return {
+            state,
+            lastRecordSequence: sequence,
+            recordCount,
+            walBytes: truncateBoundary ?? walBytes,
+            maxReadBytes,
+        };
+    }
+    catch (error) {
+        if (error instanceof StateStoreCorruptionError ||
+            error instanceof StateStoreReducerError)
+            throw error;
+        throw new Error(`state-store: cannot read WAL generation ${generation}`, { cause: error });
+    }
+    finally {
+        fs.closeSync(fd);
+        if (truncateBoundary !== undefined)
+            truncateWal(filePath, truncateBoundary);
     }
-    return { records, lastRecordSequence: sequence };
 }
 function verifyWalHeader(bytes, scopeDigest, generation) {
     if (bytes.length < WAL_HEADER_BYTES) {
@@ -442,6 +653,16 @@ function writeAllSync(fd, bytes) {
         offset += written;
     }
 }
+function readIntoSync(fd, target, position) {
+    let offset = 0;
+    while (offset < target.length) {
+        const read = fs.readSync(fd, target, offset, target.length - offset, position + offset);
+        if (read === 0)
+            break;
+        offset += read;
+    }
+    return offset;
+}
 function withScopeLock(dir, action) {
     const lockPath = path.join(dir, "append.lock");
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
@@ -545,6 +766,47 @@ function fsyncDirectory(dir) {
 function stateDirectory(rootDir, scopeDigest) {
     return path.join(rootDir, "sync-state-v3", scopeDigest.toString("hex"));
 }
+function normalizeOptions(options) {
+    if (!options.scopeId)
+        throw new Error("state-store: scopeId is required");
+    const normalized = {
+        ...options,
+        maxRecordsBeforeCompaction: options.maxRecordsBeforeCompaction ?? 256,
+        maxWalBytesBeforeCompaction: options.maxWalBytesBeforeCompaction ?? DEFAULT_MAX_WAL_BYTES_BEFORE_COMPACTION,
+    };
+    if (normalized.maxRecordsBeforeCompaction < 1) {
+        throw new Error("state-store: maxRecordsBeforeCompaction must be positive");
+    }
+    if (normalized.maxWalBytesBeforeCompaction < WAL_HEADER_BYTES + 1) {
+        throw new Error("state-store: maxWalBytesBeforeCompaction must exceed the WAL header size");
+    }
+    return normalized;
+}
+function generationFileSize(filePath, kind, generation) {
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            throw new StateStoreCorruptionError(`${kind} generation ${generation} is missing`, {
+                cause: error,
+            });
+        }
+        throw new Error(`state-store: cannot inspect ${kind} generation ${generation}`, {
+            cause: error,
+        });
+    }
+}
+function hasSnapshotGeneration(dir) {
+    try {
+        return fs.readdirSync(dir).some((name) => /^snapshot-\d+\.bin$/.test(name));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw new Error(`state-store: cannot inspect ${dir}`, { cause: error });
+    }
+}
 function snapshotPath(dir, generation) {
     return path.join(dir, `snapshot-${generation}.bin`);
 }
@@ -559,6 +821,56 @@ function highestGenerationOnDisk(dir) {
         .filter(Number.isSafeInteger)
         .reduce((highest, generation) => Math.max(highest, generation), 0);
 }
+function highestSnapshotGenerationOnDisk(dir) {
+    const generations = fs.readdirSync(dir)
+        .map((name) => /^snapshot-(\d+)\.bin$/.exec(name)?.[1])
+        .filter((value) => value !== undefined)
+        .map(Number)
+        .filter(Number.isSafeInteger);
+    return generations.length === 0 ? undefined : Math.max(...generations);
+}
+function currentGenerationOnDisk(dir) {
+    try {
+        const generation = Number(fs.readFileSync(path.join(dir, "current"), "ascii").trim());
+        return Number.isSafeInteger(generation) && generation > 0 ? generation : undefined;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new Error("state-store: cannot read current generation pointer", { cause: error });
+    }
+}
+/**
+ * Detect a crash after pointer publication but before obsolete-history prune.
+ * Journal maintenance promises rollback readers that every retained WAL is a
+ * compact header, so an old record-bearing generation is migration work even
+ * when the newest generation and pointer already look healthy.
+ */
+function retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGeneration) {
+    if (currentGeneration !== newestGeneration)
+        return true;
+    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]));
+    }
+    if (snapshots.size === 0 || snapshots.size > 2 || snapshots.size !== wals.size) {
+        return true;
+    }
+    for (const generation of snapshots) {
+        if (!wals.has(generation))
+            return true;
+        if (generationFileSize(walPath(dir, generation), "WAL", generation) !== WAL_HEADER_BYTES) {
+            return true;
+        }
+    }
+    return false;
+}
 function pruneGenerations(dir, retain) {
     const retained = new Set(retain);
     for (const name of fs.readdirSync(dir)) {