@indigoai-us/hq-cloud 6.15.72 → 6.15.74

package/dist/sync/state-store.js

@@ -38,15 +38,55 @@ 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;
 // 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 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 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);
@@ -124,10 +164,35 @@ export class StateStore {
             return new StateStore(normalized, initial, true);
         });
     }
+    /** Yielding first-open variant for callback-originated projections. */
+    static async openAsync(options) {
+        const normalized = normalizeOptions(options);
+        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);
+            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.
+     * 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);
@@ -135,11 +200,11 @@ export class StateStore {
         const dir = stateDirectory(normalized.rootDir, scopeDigest);
         if (!hasSnapshotGeneration(dir))
             return { status: "missing" };
-        return withScopeLock(dir, () => {
+        const plan = withScopeLock(dir, () => {
             cleanupUnpublishedInitialGeneration(dir);
             const newestGeneration = highestSnapshotGenerationOnDisk(dir);
             if (newestGeneration === undefined)
-                return { status: "missing" };
+                return undefined;
             if (!maintenance.force) {
                 let walBytes;
                 let snapshotBytes;
@@ -157,28 +222,65 @@ export class StateStore {
                     retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGeneration) ||
                     walBytes > normalized.maxWalBytesBeforeCompaction;
                 if (!overBudget)
-                    return { status: "not-needed" };
+                    return undefined;
             }
             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 undefined;
             return {
-                status: "repaired",
-                recoveredGeneration,
-                recoveredWalBytes,
-                firstCompactGeneration: first.generation,
-                currentGeneration: second.generation,
+                recovered,
+                highestGeneration: highestGenerationOnDisk(dir),
             };
         });
+        if (!plan)
+            return hasSnapshotGeneration(dir) ? { status: "not-needed" } : { status: "missing" };
+        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;
@@ -195,7 +297,15 @@ 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 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;
     }
     /**
      * Async lock acquisition for callback-originated work. The write itself
@@ -205,7 +315,31 @@ 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 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;
+    }
+    /** 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;
     }
     /** Refresh only the authenticated unseen WAL suffix when possible. */
     refresh() {
@@ -241,9 +375,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 };
     }
     /**
@@ -256,27 +387,87 @@ export class StateStore {
      * and retain the prior compact copy.
      */
     replaceState(nextState) {
-        withScopeLock(this.stateDir, () => {
+        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, () => {
             this.refreshFromDisk();
             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,
+            };
         });
+        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, () => {
+                this.refreshFromDisk();
+                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, () => {
+                    this.refreshFromDisk();
+                    return this.compactionPlan(this.state, this.generation, this.lastRecordSequence, this.walBytes);
+                });
+                if (this.publishCompactionPlan(plan))
+                    return;
+            }
         });
     }
     refreshFromDisk() {
@@ -306,24 +497,46 @@ export class StateStore {
         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);
+    needsCompaction() {
+        return this.recordCount >= this.options.maxRecordsBeforeCompaction ||
+            this.walBytes >= this.options.maxWalBytesBeforeCompaction;
     }
-    compactGeneration(generation, state = this.state) {
-        const next = {
-            generation,
-            state,
-            lastRecordSequence: this.lastRecordSequence,
-            recordCount: 0,
-            walBytes: WAL_HEADER_BYTES,
-            maxReadBytes: 0,
+    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, () => {
+                this.refreshFromDisk();
+                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;
@@ -388,6 +601,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;
@@ -729,6 +1066,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);
@@ -815,6 +1153,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"));
@@ -828,6 +1195,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) {
@@ -881,6 +1260,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
@@ -938,7 +1384,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;
@@ -966,7 +1412,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;
@@ -985,6 +1431,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 {