@openclaw/fs-safe 0.8.2 → 0.8.3

package/dist/guarded-mutation.d.ts

@@ -1,3 +1,4 @@
+import { type BigIntStats } from "node:fs";
 import { type AnyAsyncDirectoryGuard, type SyncDirectoryGuard } from "./directory-guard.js";
 export declare function withAsyncDirectoryGuards<T>(guards: readonly AnyAsyncDirectoryGuard[], mutate: () => Promise<T>, options?: {
     verifyAfter?: boolean;
@@ -8,6 +9,8 @@ export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirector
 }): T;
 export declare function guardedRename(params: {
     assertBeforeRename?: () => void;
+    onSourceInspected?: (identity: Pick<BigIntStats, "dev" | "ino">) => void;
+    onRenamed?: () => void;
     from: string;
     to: string;
     targetRoot?: string;

package/dist/guarded-mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAGA,OAAO,EAOL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAOL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC;IACzE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/dist/guarded-mutation.js

@@ -1,4 +1,4 @@
-import fsSync from "node:fs";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, createNearestExistingSyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
@@ -48,9 +48,13 @@ export async function guardedRename(params) {
         ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
         : await createAsyncDirectoryGuard(path.dirname(params.to));
     await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        if (params.onSourceInspected) {
+            params.onSourceInspected(await fs.lstat(params.from, { bigint: true }));
+        }
         // Authority must survive all awaited guards; do not yield before rename dispatch.
         params.assertBeforeRename?.();
         await fs.rename(params.from, params.to);
+        params.onRenamed?.();
     }, { verifyAfter: params.verifyAfter });
 }
 export function guardedRenameSync(params) {

package/dist/home-dir.d.ts

@@ -1,7 +1,5 @@
 export declare function resolveEffectiveHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string | undefined;
-export declare function resolveOsHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string | undefined;
 export declare function resolveRequiredHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
-export declare function resolveRequiredOsHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
 export declare function expandHomePrefix(input: string, opts?: {
     home?: string;
     env?: NodeJS.ProcessEnv;
@@ -11,12 +9,4 @@ export declare function resolveHomeRelativePath(input: string, opts?: {
     env?: NodeJS.ProcessEnv;
     homedir?: () => string;
 }): string;
-export declare function resolveUserPath(input: string, optsOrEnv?: {
-    env?: NodeJS.ProcessEnv;
-    homedir?: () => string;
-} | NodeJS.ProcessEnv, homedir?: () => string): string;
-export declare function resolveOsHomeRelativePath(input: string, opts?: {
-    env?: NodeJS.ProcessEnv;
-    homedir?: () => string;
-}): string;
 //# sourceMappingURL=home-dir.d.ts.map

package/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACD,MAAM,CAAC,UAAU,EACrB,OAAO,CAAC,EAAE,MAAM,MAAM,GACrB,MAAM,CAMR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}

package/dist/home-dir.js

@@ -15,10 +15,6 @@ export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir)
     const raw = resolveRawHomeDir(env, homedir);
     return raw ? path.resolve(raw) : undefined;
 }
-export function resolveOsHomeDir(env = process.env, homedir = os.homedir) {
-    const raw = resolveRawOsHomeDir(env, homedir);
-    return raw ? path.resolve(raw) : undefined;
-}
 function resolveRawHomeDir(env, homedir) {
     const explicitHome = normalize(env.OPENCLAW_HOME);
     if (!explicitHome) {
@@ -59,9 +55,6 @@ function normalizeSafe(homedir) {
 export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
     return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
 }
-export function resolveRequiredOsHomeDir(env = process.env, homedir = os.homedir) {
-    return resolveOsHomeDir(env, homedir) ?? path.resolve(process.cwd());
-}
 export function expandHomePrefix(input, opts) {
     const segments = path.normalize(input).split(path.sep);
     if (segments[0] !== "~") {
@@ -89,24 +82,3 @@ export function resolveHomeRelativePath(input, opts) {
     });
     return path.resolve(expanded);
 }
-export function resolveUserPath(input, optsOrEnv, homedir) {
-    const opts = optsOrEnv && ("env" in optsOrEnv || "homedir" in optsOrEnv)
-        ? optsOrEnv
-        : { env: optsOrEnv, homedir };
-    return resolveHomeRelativePath(input, opts);
-}
-export function resolveOsHomeRelativePath(input, opts) {
-    if (!input) {
-        return input;
-    }
-    const segments = path.normalize(input).split(path.sep);
-    if (segments[0] !== "~") {
-        return path.resolve(input);
-    }
-    const expanded = expandHomePrefix(input, {
-        home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
-        env: opts?.env,
-        homedir: opts?.homedir,
-    });
-    return path.resolve(expanded);
-}

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

@@ -13,4 +13,5 @@ export declare function moveDurableQueueEntryToFailed(params: {
     paths: DurableQueueEntryPathsLike;
     failedPath: string;
 }): Promise<void>;
+export declare function getErrorCode(error: unknown): string | null;
 //# sourceMappingURL=json-durable-queue-ownership.d.ts.map

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

@@ -1 +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;AAwED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,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"}
+{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAKpF;AA+DD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,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;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}

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

@@ -1,16 +1,11 @@
+import { randomUUID } from "node:crypto";
+import { withSidecarLock } from "./sidecar-lock.js";
 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 { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.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;
@@ -18,16 +13,6 @@ export function durableQueueProcessingPath(paths) {
         ? `${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)
@@ -169,3 +154,139 @@ export async function moveDurableQueueEntryToFailed(params) {
         await syncDirectory(path.dirname(sourcePath));
     });
 }
+const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
+const RETIREMENT_ENTRY_NAME = "entry";
+export 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);
+}
+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 });
+}
+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);
+}
+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.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAkBA,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,CAQhB;AA6DD,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,CA8Dd;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":"AAmBA,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;AAM3E,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,CAQhB;AA6DD,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,CA8Dd;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"}

package/dist/json-durable-queue.js

@@ -3,18 +3,13 @@ import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { syncDirectory } from "./directory-durability.js";
 import { syncQueueDirectoryCreation } from "./json-durable-queue-directory.js";
-import { acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
+import { getErrorCode, acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 export const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
-function getErrnoCode(error) {
-    return error && typeof error === "object" && "code" in error
-        ? String(error.code)
-        : null;
-}
 function assertSafeQueueEntryId(id) {
     assertSafePathSegment(id, { label: "queue entry id" });
 }
@@ -27,7 +22,7 @@ export async function jsonDurableQueueEntryExists(filePath) {
         return stat.isFile();
     }
     catch (error) {
-        if (getErrnoCode(error) === "ENOENT") {
+        if (getErrorCode(error) === "ENOENT") {
             return false;
         }
         throw error;
@@ -41,7 +36,7 @@ async function unlinkStaleTmpBestEffort(filePath, now, maxAgeMs) {
         }
     }
     catch (error) {
-        if (getErrnoCode(error) !== "ENOENT") {
+        if (getErrorCode(error) !== "ENOENT") {
             throw error;
         }
     }
@@ -302,7 +297,7 @@ export async function loadJsonDurableQueueEntry(params) {
         return result.entry;
     }
     catch (error) {
-        if (getErrnoCode(error) === "ENOENT") {
+        if (getErrorCode(error) === "ENOENT") {
             return null;
         }
         throw error;
@@ -314,7 +309,7 @@ export async function loadPendingJsonDurableQueueEntries(options) {
         files = await fs.promises.readdir(options.queueDir);
     }
     catch (error) {
-        if (getErrnoCode(error) === "ENOENT") {
+        if (getErrorCode(error) === "ENOENT") {
             return [];
         }
         throw error;

package/dist/json-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-store.d.ts","sourceRoot":"","sources":["../src/json-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,oBAAoB,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;AAEtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQvE"}
+{"version":3,"file":"json-store.d.ts","sourceRoot":"","sources":["../src/json-store.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,oBAAoB,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;AAEtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQvE"}

package/dist/json-store.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileStore } from "./file-store.js";
-import { createJsonStore, } from "./json-document-store.js";
+import {} from "./json-document-store.js";
 export function jsonStore(options) {
     const filePath = path.resolve(options.filePath);
     return fileStore({

package/dist/local-roots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAgDF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CAuC7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4CtC"}
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAQA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAgDF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CAuC7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA2CtC"}

package/dist/local-roots.js

@@ -2,7 +2,7 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
-import { expandHomePrefix, resolveUserPath } from "./home-dir.js";
+import { expandHomePrefix, resolveHomeRelativePath } from "./home-dir.js";
 import { isFileUrl, safeFileURLToPath } from "./local-file-access.js";
 import { isPathInside } from "./path.js";
 import { resolveRootPathSync } from "./root-path.js";
@@ -20,7 +20,7 @@ function resolveLocalPathInput(input, label) {
     if (input.includes("\0")) {
         throw new FsSafeError("invalid-path", `${label} must not contain NUL bytes`);
     }
-    return resolveUserPath(input);
+    return resolveHomeRelativePath(input);
 }
 function resolveLocalRootInput(input, label) {
     const trimmed = input.trim();
@@ -106,7 +106,6 @@ export async function readLocalFileFromRoots(options) {
         }
         const readOptions = {
             hardlinks: options.hardlinks,
-            nonBlockingRead: options.nonBlockingRead,
             symlinks: options.symlinks,
         };
         // Leave maxBytes absent when the caller omits it so Root's own default

package/dist/move-path-cleanup.d.ts

@@ -38,6 +38,6 @@ export declare function sameIdentity(a: EntryIdentity, b: EntryIdentity): boolea
 export declare function sourceChangedError(sourcePath: string): Error;
 export declare function assertSourceStillMatches(sourcePath: string, identity: EntryIdentity): Promise<void>;
 export declare function createCleanupCopiedEntryState(sourcePath: string, manifest: CopiedEntryManifest): CleanupCopiedEntryState;
-export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState): Promise<CleanupCopiedEntryResult>;
+export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState, assertBeforeMutation: () => void): Promise<CleanupCopiedEntryResult>;
 export {};
 //# sourceMappingURL=move-path-cleanup.d.ts.map

package/dist/move-path-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"move-path-cleanup.d.ts","sourceRoot":"","sources":["../src/move-path-cleanup.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,CAAC,aAAa,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvC,KAAK,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAUhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAMD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AA0BD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,uBAAuB,CAuBzB;AAsDD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAkDnC"}
+{"version":3,"file":"move-path-cleanup.d.ts","sourceRoot":"","sources":["../src/move-path-cleanup.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,CAAC,aAAa,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,GACF,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvC,KAAK,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAUhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAMD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAI5D;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AA0BD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,uBAAuB,CAuBzB;AAsDD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,uBAAuB,EAC9B,oBAAoB,EAAE,MAAM,IAAI,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAyDnC"}

package/dist/move-path-cleanup.js

@@ -111,7 +111,7 @@ async function observeOwnedAliasUnlink(sourcePath, group) {
 function mergeCleanupResults(a, b) {
     return a === "stale" || b === "stale" ? "stale" : "removed";
 }
-export async function cleanupCopiedEntry(sourcePath, manifest, state) {
+export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBeforeMutation) {
     const aliasGroup = manifest.kind === "leaf" ? state.aliasGroups.get(identityKey(manifest)) : undefined;
     if (aliasGroup?.stale) {
         return "stale";
@@ -134,8 +134,9 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state) {
         // clean manifest children so the fallback does not duplicate copied files.
         let result = "removed";
         for (const child of manifest.children) {
-            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state));
+            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeMutation));
         }
+        assertBeforeMutation();
         try {
             await fs.rmdir(sourcePath);
         }
@@ -152,6 +153,7 @@ export async function cleanupCopiedEntry(sourcePath, manifest, state) {
     if (!sameIdentity(expected, entryIdentity(currentStat))) {
         return aliasGroup ? poisonAliasGroup(aliasGroup) : "stale";
     }
+    assertBeforeMutation();
     await fs.unlink(sourcePath);
     return aliasGroup
         ? await observeOwnedAliasUnlink(sourcePath, aliasGroup)

package/dist/move-path.d.ts

@@ -1,6 +1,15 @@
+export type MovePathPublicationReceipt = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
 export type MovePathWithCopyFallbackOptions = {
+    /** Rechecks authority before each rename and copied-source unlink/rmdir dispatch. */
+    assertBeforeMutation?: () => void;
     /** Rechecks caller authority synchronously immediately before each rename dispatch. */
     assertBeforeRename?: () => void;
+    /** Reports the committed destination before post-rename checks or source cleanup. */
+    onDestinationPublished?: (receipt: MovePathPublicationReceipt) => void;
     from: string;
     sourceHardlinks?: "allow" | "reject";
     to: string;

package/dist/move-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AA8OD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAkFf"}
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,qFAAqF;IACrF,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAsPD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAqHf"}

package/dist/move-path.js

@@ -211,24 +211,49 @@ async function copyEntryWithManifest(from, to, options, expectedIdentity) {
     });
     return { ...identity, kind: "leaf" };
 }
+function assertSynchronousResult(returned, name) {
+    if (returned !== undefined) {
+        // TypeScript permits async functions for () => void; consume their rejection.
+        void Promise.resolve(returned).catch(() => { });
+        throw new TypeError(`${name} must return undefined synchronously`);
+    }
+}
 export async function movePathWithCopyFallback(options) {
-    // Keep the initiating owner's callback across preparation and copy fallback.
-    const callerAssert = options.assertBeforeRename;
+    // Keep the initiating owner's callbacks across preparation and copy fallback.
+    const callerRenameAssert = options.assertBeforeRename;
+    const callerMutationAssert = options.assertBeforeMutation;
+    const callerPublished = options.onDestinationPublished;
     let assertionRejected = false;
+    let destinationPublished = false;
+    const assertBeforeMutation = () => {
+        assertSynchronousResult(callerMutationAssert?.(), "assertBeforeMutation");
+    };
     const assertBeforeRename = () => {
         try {
-            const returned = callerAssert?.();
-            if (returned !== undefined) {
-                // TypeScript permits async functions for () => void; they cannot authorize a rename.
-                void Promise.resolve(returned).catch(() => { });
-                throw new TypeError("assertBeforeRename must return undefined synchronously");
-            }
+            assertSynchronousResult(callerRenameAssert?.(), "assertBeforeRename");
+            assertBeforeMutation();
         }
         catch (error) {
             assertionRejected = true;
             throw error;
         }
     };
+    let publicationReceipt;
+    const onSourceInspected = callerPublished
+        ? (identity) => {
+            publicationReceipt = Object.freeze({
+                path: targetPath,
+                dev: identity.dev,
+                ino: identity.ino,
+            });
+        }
+        : undefined;
+    const onRenamed = () => {
+        destinationPublished = true;
+        if (publicationReceipt) {
+            assertSynchronousResult(callerPublished?.(publicationReceipt), "onDestinationPublished");
+        }
+    };
     const sourcePath = path.resolve(options.from);
     const targetPath = path.resolve(options.to);
     const rejectHardlinks = options.sourceHardlinks === "reject";
@@ -237,12 +262,18 @@ export async function movePathWithCopyFallback(options) {
     }
     if (!rejectHardlinks) {
         try {
-            await guardedRename({ from: sourcePath, to: targetPath, assertBeforeRename });
+            await guardedRename({
+                from: sourcePath,
+                to: targetPath,
+                assertBeforeRename,
+                onSourceInspected,
+                onRenamed,
+            });
             return;
         }
         catch (error) {
             // An owner's EXDEV/EPERM refusal is not permission to copy instead.
-            if (assertionRejected || !moveCopyFallbackReasonForRenameError(error)) {
+            if (assertionRejected || destinationPublished || !moveCopyFallbackReasonForRenameError(error)) {
                 throw error;
             }
         }
@@ -256,7 +287,6 @@ export async function movePathWithCopyFallback(options) {
     const targetDir = path.dirname(targetPath);
     const staged = path.join(targetDir, `.fs-safe-move-${process.pid}-${randomUUID()}.tmp`);
     const unregisterStaged = registerTempPathForExit(staged, { recursive: true });
-    let stagedCommitted = false;
     try {
         const manifest = await copyEntryWithManifest(sourcePath, staged, {
             sourceHardlinks: options.sourceHardlinks ?? "allow",
@@ -265,16 +295,23 @@ export async function movePathWithCopyFallback(options) {
         const cleanupState = createCleanupCopiedEntryState(sourcePath, manifest);
         unregisterStaged.setIdentity(await fs.lstat(staged, { bigint: true }));
         await assertCopyDestinationOutsideSource(sourcePath, targetPath, manifest);
-        await guardedRename({ from: staged, to: targetPath, assertBeforeRename });
-        stagedCommitted = true;
-        unregisterStaged();
-        const cleanupResult = await cleanupCopiedEntry(sourcePath, manifest, cleanupState);
+        await guardedRename({
+            from: staged,
+            to: targetPath,
+            assertBeforeRename,
+            onSourceInspected,
+            onRenamed: () => {
+                unregisterStaged();
+                onRenamed();
+            },
+        });
+        const cleanupResult = await cleanupCopiedEntry(sourcePath, manifest, cleanupState, assertBeforeMutation);
         if (cleanupResult === "stale") {
             throw sourceChangedError(sourcePath);
         }
     }
     finally {
-        if (!stagedCommitted) {
+        if (!destinationPublished) {
             try {
                 const stagedIdentity = await fs.lstat(staged, { bigint: true });
                 if (!stagedIdentity.isSymbolicLink())

package/dist/native-operations.d.ts

@@ -18,5 +18,4 @@ export declare function removeNativeCreatedFileIfStillPinned(params: {
     created?: BigIntStats;
 }): void;
 export declare function createNativeExclusiveFile(targetPath: string, mode: number): Promise<NativeFileHandle | undefined>;
-export declare function syncNativeFileBestEffort(fd: number): void;
 //# sourceMappingURL=native-operations.d.ts.map

package/dist/native-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS5D;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,gBAAgB,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAsBD,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,GAAG,IAAI,CAqBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAwDvC;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAQzD"}
+{"version":3,"file":"native-operations.d.ts","sourceRoot":"","sources":["../src/native-operations.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS5D;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,gBAAgB,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAsBD,wBAAgB,oCAAoC,CAAC,MAAM,EAAE;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,GAAG,IAAI,CAqBP;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAwDvC"}

package/dist/native-operations.js

@@ -130,13 +130,3 @@ export async function createNativeExclusiveFile(targetPath, mode) {
         await parent.close().catch(() => undefined);
     }
 }
-export function syncNativeFileBestEffort(fd) {
-    try {
-        fsSync.fsyncSync(fd);
-    }
-    catch (error) {
-        if (error.code !== "EPERM") {
-            throw error;
-        }
-    }
-}