@openclaw/fs-safe 0.6.0 → 0.7.1

package/dist/file-store.js

@@ -1,8 +1,10 @@
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
+import { assertFileStoreMaxBytes } from "./file-store-limit.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
 import { ensureParentInRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
@@ -38,15 +40,8 @@ function assertRelativePath(relativePath) {
 function resolveStorePath(rootDir, relativePath) {
     return resolveSafeRelativePath(rootDir, assertRelativePath(relativePath));
 }
-function assertMaxBytes(size, maxBytes) {
-    if (maxBytes !== undefined && size > maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`);
-    }
-}
 function isNotFound(error) {
-    return error instanceof FsSafeError
-        ? error.code === "not-found"
-        : isNotFoundPathError(error);
+    return error instanceof FsSafeError ? error.code === "not-found" : isNotFoundPathError(error);
 }
 function handleSyncStoreReadOpenFailure(opened) {
     return matchRootFileOpenFailure(opened, {
@@ -81,7 +76,7 @@ async function readFileStoreCopySource(params) {
     if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
         throw new FsSafeError("not-file", "source path is not a file");
     }
-    assertMaxBytes(sourceStat.size, params.maxBytes);
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
     try {
         return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
             .buffer;
@@ -108,7 +103,7 @@ async function copyIntoRoot(params) {
     if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
         throw new FsSafeError("not-file", "source path is not a file");
     }
-    assertMaxBytes(sourceStat.size, params.maxBytes);
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
     const dirMode = params.dirMode ?? 0o700;
     const scopedRoot = await openWritableStoreRoot({
         rootDir: params.rootDir,
@@ -128,7 +123,7 @@ export function fileStore(options) {
     const privateMode = options.private ?? false;
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
-    const maxBytes = options.maxBytes;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
     async function openRoot() {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
     }
@@ -136,7 +131,8 @@ export function fileStore(options) {
         const safeRelativePath = assertRelativePath(relativePath);
         const destination = resolveStorePath(rootDir, safeRelativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
-        assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
         if (privateMode) {
             await writeSecretFileAtomic({
                 rootDir,
@@ -151,7 +147,7 @@ export function fileStore(options) {
         const scopedRoot = await openWritableStoreRoot({
             rootDir,
             dirMode: writeDirMode,
-            maxBytes: writeOptions?.maxBytes ?? maxBytes,
+            maxBytes: writeMaxBytes,
         });
         await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
         await scopedRoot.write(safeRelativePath, content, {
@@ -168,14 +164,15 @@ export function fileStore(options) {
         writeStream: async (relativePath, stream, writeOptions) => {
             const safeRelativePath = assertRelativePath(relativePath);
             const destination = resolveStorePath(rootDir, safeRelativePath);
-            const limit = writeOptions?.maxBytes ?? maxBytes ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
                 const chunks = [];
                 let total = 0;
                 for await (const chunk of stream) {
                     const buffer = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
                     total += buffer.byteLength;
-                    assertMaxBytes(total, limit);
+                    assertFileStoreMaxBytes(total, limit);
                     chunks.push(buffer);
                 }
                 await writeSecretFileAtomic({
@@ -208,23 +205,25 @@ export function fileStore(options) {
             }
             return destination;
         },
-        copyIn: async (relativePath, sourcePath, writeOptions) => privateMode
-            ? await (async () => {
+        copyIn: async (relativePath, sourcePath, writeOptions) => {
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            if (privateMode) {
                 const buffer = await readFileStoreCopySource({
                     sourcePath,
-                    maxBytes: writeOptions?.maxBytes ?? maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
+                    maxBytes: configuredLimit ?? DEFAULT_ROOT_MAX_BYTES,
                 });
                 return await write(relativePath, buffer, writeOptions);
-            })()
-            : await copyIntoRoot({
+            }
+            return await copyIntoRoot({
                 rootDir,
                 relativePath,
                 sourcePath,
                 dirMode: writeOptions?.dirMode ?? dirMode,
-                maxBytes: writeOptions?.maxBytes ?? maxBytes,
+                maxBytes: configuredLimit,
                 mode: writeOptions?.mode ?? mode,
                 tempPrefix: writeOptions?.tempPrefix,
-            }),
+            });
+        },
         open: async (relativePath, readOptions) => await (await openRoot()).open(assertRelativePath(relativePath), readOptions),
         read: async (relativePath, readOptions) => await (await openRoot()).read(assertRelativePath(relativePath), readOptions),
         readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(assertRelativePath(relativePath), readOptions),
@@ -301,11 +300,12 @@ export function fileStoreSync(options) {
     const privateMode = options.private ?? false;
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
-    const maxBytes = options.maxBytes;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
     function write(relativePath, data, writeOptions) {
         const destination = resolveStorePath(rootDir, relativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
-        assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
         return writeFileSyncAtomic({
             rootDir,
             filePath: destination,
@@ -319,6 +319,7 @@ export function fileStoreSync(options) {
         rootDir,
         path: (relativePath) => resolveStorePath(rootDir, relativePath),
         readTextIfExists: (relativePath, readOptions) => {
+            const limit = normalizeMaxBytes(readOptions?.maxBytes, { defaultValue: maxBytes });
             const targetPath = resolveStorePath(rootDir, relativePath);
             const opened = openRootFileSync({
                 absolutePath: targetPath,
@@ -330,8 +331,7 @@ export function fileStoreSync(options) {
                 return handleSyncStoreReadOpenFailure(opened);
             }
             try {
-                assertMaxBytes(opened.stat.size, readOptions?.maxBytes ?? maxBytes);
-                const limit = readOptions?.maxBytes ?? maxBytes;
+                assertFileStoreMaxBytes(opened.stat.size, limit);
                 try {
                     return limit === undefined
                         ? syncFs.readFileSync(opened.fd, "utf8")

package/dist/json-durable-queue-directory.d.ts

@@ -0,0 +1,2 @@
+export declare function syncQueueDirectoryCreation(dir: string, validationBase: string): Promise<void>;
+//# sourceMappingURL=json-durable-queue-directory.d.ts.map

package/dist/json-durable-queue-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-directory.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-directory.ts"],"names":[],"mappings":"AAKA,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/json-durable-queue-directory.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { isPathRelativeEscape } from "./path.js";
+export async function syncQueueDirectoryCreation(dir, validationBase) {
+    const baseReal = await fs.realpath(validationBase);
+    const targetReal = await fs.realpath(dir);
+    const relative = path.relative(baseReal, targetReal);
+    if (isPathRelativeEscape(relative)) {
+        throw new Error(`durable queue directory escapes validation base: ${dir}`);
+    }
+    const directories = [baseReal];
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        directories.push(path.join(directories.at(-1), segment));
+    }
+    await syncDirectory(targetReal, { label: "durable queue directory" });
+    for (const parent of directories.slice(0, -1).toReversed()) {
+        await syncDirectory(parent, { label: "durable queue parent" });
+    }
+}

package/dist/json-durable-queue-ownership.d.ts

@@ -0,0 +1,14 @@
+export type DurableQueueEntryPathsLike = {
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath?: string;
+};
+export declare function durableQueueProcessingPath(paths: DurableQueueEntryPathsLike): string;
+export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike): Promise<string | null>;
+export declare function completeDeliveredQueueEntry(paths: DurableQueueEntryPathsLike): Promise<boolean>;
+export declare function acknowledgeDurableQueueEntry(paths: DurableQueueEntryPathsLike): Promise<void>;
+export declare function moveDurableQueueEntryToFailed(params: {
+    paths: DurableQueueEntryPathsLike;
+    failedPath: string;
+}): Promise<void>;
+//# sourceMappingURL=json-durable-queue-ownership.d.ts.map

package/dist/json-durable-queue-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAQF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAKpF;AAqED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAalB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}

package/dist/json-durable-queue-ownership.js

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { recoverDurableQueueRetirement, retireDurableQueueSource, } from "./json-durable-queue-retirement.js";
+import { withQueueTransferLock } from "./json-durable-queue-transfer-lock.js";
+import { serializePathWrite } from "./write-queue.js";
+function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+export function durableQueueProcessingPath(paths) {
+    if (paths.processingPath)
+        return paths.processingPath;
+    return paths.jsonPath.endsWith(".json")
+        ? `${paths.jsonPath.slice(0, -".json".length)}.processing`
+        : `${paths.jsonPath}.processing`;
+}
+async function lstatOrNull(filePath) {
+    try {
+        return await fs.lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function regularQueueFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new Error(`queue entry is not a regular file: ${filePath}`);
+    }
+    return identity;
+}
+async function withQueueEntryLock(paths, run) {
+    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(path.resolve(paths.jsonPath), run));
+}
+async function claimDurableQueueEntryUnlocked(paths) {
+    const processingPath = durableQueueProcessingPath(paths);
+    await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
+    const existingProcessing = await regularQueueFileIdentity(processingPath);
+    if (existingProcessing) {
+        const pending = await lstatOrNull(paths.jsonPath);
+        if (pending &&
+            !pending.isSymbolicLink() &&
+            pending.isFile() &&
+            sameFileIdentityForCleanup(pending, existingProcessing)) {
+            await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+        }
+        return processingPath;
+    }
+    const pending = await lstatOrNull(paths.jsonPath);
+    if (!pending || pending.isSymbolicLink() || !pending.isFile())
+        return null;
+    if (pending.nlink > 1n || !sameFileIdentityForCleanup(pending, pending)) {
+        throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
+    }
+    try {
+        await fs.link(paths.jsonPath, processingPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "EEXIST") {
+            return (await regularQueueFileIdentity(processingPath)) ? processingPath : null;
+        }
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    await syncDirectory(path.dirname(processingPath));
+    const claimed = await regularQueueFileIdentity(processingPath);
+    if (!claimed || claimed.nlink > 2n) {
+        throw new FsSafeError("path-mismatch", "queue claim is not an owned regular file");
+    }
+    await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+    return processingPath;
+}
+export async function claimDurableQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return null;
+    return await withQueueEntryLock(paths, async () => await claimDurableQueueEntryUnlocked(paths));
+}
+export async function completeDeliveredQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.deliveredPath))))
+        return false;
+    return await withQueueEntryLock(paths, async () => {
+        if (!(await regularQueueFileIdentity(paths.deliveredPath)))
+            return false;
+        if (await regularQueueFileIdentity(durableQueueProcessingPath(paths))) {
+            await fs.unlink(paths.deliveredPath);
+            await syncDirectory(path.dirname(paths.deliveredPath));
+            return false;
+        }
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        return true;
+    });
+}
+export async function acknowledgeDurableQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return;
+    await withQueueEntryLock(paths, async () => {
+        const processingPath = durableQueueProcessingPath(paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const delivered = await regularQueueFileIdentity(paths.deliveredPath);
+        if (!processing) {
+            if (delivered) {
+                await fs.unlink(paths.deliveredPath);
+                await syncDirectory(path.dirname(paths.deliveredPath));
+            }
+            if (await regularQueueFileIdentity(paths.jsonPath)) {
+                throw new FsSafeError("path-mismatch", "queue acknowledgement requires a processing claim");
+            }
+            return;
+        }
+        if (delivered)
+            await fs.unlink(paths.deliveredPath);
+        await fs.rename(processingPath, paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+    });
+}
+export async function moveDurableQueueEntryToFailed(params) {
+    await withQueueEntryLock(params.paths, async () => {
+        const processingPath = durableQueueProcessingPath(params.paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const existingFailed = await regularQueueFileIdentity(params.failedPath);
+        if (!processing && existingFailed) {
+            await syncDirectory(path.dirname(params.failedPath));
+            await syncDirectory(path.dirname(processingPath));
+            const recoveredFailed = await regularQueueFileIdentity(params.failedPath);
+            if (!recoveredFailed ||
+                !sameFileIdentityForCleanup(existingFailed, recoveredFailed)) {
+                throw new FsSafeError("path-mismatch", "failed queue destination changed during recovery");
+            }
+            if (await regularQueueFileIdentity(params.paths.jsonPath)) {
+                throw new FsSafeError("already-exists", "failed queue destination already exists");
+            }
+            return;
+        }
+        const sourcePath = processing
+            ? processingPath
+            : await claimDurableQueueEntryUnlocked(params.paths);
+        if (!sourcePath) {
+            throw Object.assign(new Error("queue entry does not exist"), { code: "ENOENT" });
+        }
+        const source = await regularQueueFileIdentity(sourcePath);
+        const failed = await regularQueueFileIdentity(params.failedPath);
+        if (failed) {
+            if (source && sameFileIdentityForCleanup(source, failed)) {
+                await syncDirectory(path.dirname(params.failedPath));
+                await fs.unlink(sourcePath);
+                await syncDirectory(path.dirname(sourcePath));
+                return;
+            }
+            throw new FsSafeError("already-exists", "failed queue destination already exists");
+        }
+        await fs.link(sourcePath, params.failedPath);
+        await syncDirectory(path.dirname(params.failedPath));
+        await fs.unlink(sourcePath);
+        await syncDirectory(path.dirname(sourcePath));
+    });
+}

package/dist/json-durable-queue-retirement.d.ts

@@ -0,0 +1,9 @@
+export declare function recoverDurableQueueRetirement(params: {
+    jsonPath: string;
+    processingPath: string;
+}): Promise<void>;
+export declare function retireDurableQueueSource(params: {
+    jsonPath: string;
+    processingPath: string;
+}): Promise<void>;
+//# sourceMappingURL=json-durable-queue-retirement.d.ts.map

package/dist/json-durable-queue-retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-retirement.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-retirement.ts"],"names":[],"mappings":"AAgFA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/json-durable-queue-retirement.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
+const RETIREMENT_ENTRY_NAME = "entry";
+function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+async function lstatOrNull(filePath) {
+    try {
+        return await fs.lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertDirectory(identity, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("path-mismatch", `${label} is not an owned directory`);
+    }
+}
+async function regularFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new FsSafeError("path-mismatch", "queue retirement path is not a regular file");
+    }
+    return identity;
+}
+function retirementPaths(jsonPath) {
+    const rootPath = path.join(path.dirname(jsonPath), RETIREMENT_ROOT_NAME);
+    const dirPath = path.join(rootPath, path.basename(jsonPath));
+    return { dirPath, entryPath: path.join(dirPath, RETIREMENT_ENTRY_NAME), rootPath };
+}
+async function inspectRetirementRoot(jsonPath) {
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    const root = await lstatOrNull(rootPath);
+    if (!root)
+        return null;
+    assertDirectory(root, "queue retirement root");
+    return rootPath;
+}
+async function ensureRetirementRoot(jsonPath) {
+    const parentPath = path.dirname(jsonPath);
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    await fs.mkdir(rootPath, { mode: 0o700 }).catch((error) => {
+        if (getErrorCode(error) !== "EEXIST")
+            throw error;
+    });
+    const root = await fs.lstat(rootPath, { bigint: true });
+    assertDirectory(root, "queue retirement root");
+    await syncDirectory(parentPath);
+    return rootPath;
+}
+async function removeRetirementRecord(params) {
+    await fs.rmdir(params.dirPath).catch((error) => {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(params.rootPath);
+}
+export async function recoverDurableQueueRetirement(params) {
+    const rootPath = await inspectRetirementRoot(params.jsonPath);
+    if (!rootPath)
+        return;
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    const dir = await lstatOrNull(dirPath);
+    if (!dir)
+        return;
+    assertDirectory(dir, "queue retirement record");
+    const names = await fs.readdir(dirPath);
+    if (names.length === 0) {
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    if (names.length !== 1 || names[0] !== RETIREMENT_ENTRY_NAME) {
+        throw new FsSafeError("path-mismatch", "queue retirement record is ambiguous");
+    }
+    const entry = await regularFileIdentity(entryPath);
+    const processing = await regularFileIdentity(params.processingPath);
+    if (!entry || !processing) {
+        throw new FsSafeError("path-mismatch", "queue retirement ownership is incomplete");
+    }
+    if (!sameFileIdentityForCleanup(entry, processing)) {
+        const pending = await regularFileIdentity(params.jsonPath);
+        if (!pending) {
+            await fs.link(entryPath, params.jsonPath);
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (sameFileIdentityForCleanup(pending, entry)) {
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (pending.nlink > 1n) {
+            throw new FsSafeError("path-mismatch", "queue replacement identity is ambiguous");
+        }
+    }
+    await fs.unlink(entryPath);
+    await syncDirectory(dirPath);
+    await removeRetirementRecord({ dirPath, rootPath });
+}
+export async function retireDurableQueueSource(params) {
+    await recoverDurableQueueRetirement(params);
+    const rootPath = await ensureRetirementRoot(params.jsonPath);
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    await fs.mkdir(dirPath, { mode: 0o700 });
+    await syncDirectory(rootPath);
+    try {
+        await fs.rename(params.jsonPath, entryPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    await syncDirectory(dirPath);
+    await syncDirectory(path.dirname(params.jsonPath));
+    await recoverDurableQueueRetirement(params);
+}

package/dist/json-durable-queue-transfer-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withQueueTransferLock<T>(filePath: string, run: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=json-durable-queue-transfer-lock.d.ts.map

package/dist/json-durable-queue-transfer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-transfer-lock.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-transfer-lock.ts"],"names":[],"mappings":"AAKA,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}

package/dist/json-durable-queue-transfer-lock.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { sha256Hex } from "./file-identity.js";
+import { withSidecarLock } from "./sidecar-lock.js";
+export async function withQueueTransferLock(filePath, run) {
+    const lockPath = path.join(path.dirname(filePath), `.fs-safe-transfer-${sha256Hex(path.basename(filePath)).slice(0, 32)}.lock`);
+    return await withSidecarLock(filePath, {
+        managerKey: "fs-safe.queue-transfer",
+        lockPath,
+        staleMs: 30_000,
+        staleRecovery: "fail-closed",
+        timeoutMs: 45_000,
+        payload: () => ({
+            ownerToken: randomUUID(),
+            createdAt: new Date().toISOString(),
+        }),
+        retry: { retries: 180, minTimeout: 25, maxTimeout: 250, factor: 1.1 },
+    }, run);
+}

package/dist/json-durable-queue.d.ts

@@ -1,6 +1,7 @@
 export type JsonDurableQueueEntryPaths = {
     jsonPath: string;
     deliveredPath: string;
+    processingPath?: string;
 };
 export type JsonDurableQueueReadResult<T> = {
     entry: T;

package/dist/json-durable-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAM5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+KD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAsDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAO5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAgLD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AA4ED,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CA4Dd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}