@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/root-file.d.ts

@@ -44,4 +44,3 @@ export declare function matchRootFileOpenFailure<T>(failure: RootFileOpenFailure
 }): T;
 export declare function openRootFile(params: OpenRootFileParams): Promise<RootFileOpenResult>;
 export {};
-//# sourceMappingURL=root-file.d.ts.map

package/dist/root-file.js

@@ -70,14 +70,15 @@ export function matchRootFileOpenFailure(failure, handlers) {
     return handlers.fallback(failure);
 }
 function openRootFileResolved(params) {
+    const rejectHardlinks = params.rejectHardlinks ?? true;
     const opened = openPinnedFileSync({
         filePath: params.absolutePath,
         resolvedPath: params.resolvedPath,
-        rejectHardlinks: params.rejectHardlinks ?? true,
+        rejectHardlinks,
         maxBytes: params.maxBytes,
         allowedType: params.allowedType,
         ioFs: params.ioFs,
-        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel),
+        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel, rejectHardlinks),
     });
     if (!opened.ok) {
         return opened;

package/dist/root-impl.d.ts

@@ -62,14 +62,12 @@ export interface Root {
     walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
 }
 export declare class RootHandle implements Root {
-    private readonly rootGuard;
-    private readonly rootIdentity;
+    private readonly context;
     readonly rootDir: string;
     readonly rootReal: string;
     readonly rootWithSep: string;
     readonly defaults: RootDefaults;
     constructor(context: RootContext, defaults?: RootDefaults);
-    private get context();
     private mutationOptions;
     resolve(relativePath: string): Promise<string>;
     open(relativePath: string, options?: RootOpenOptions): Promise<OpenResult>;
@@ -119,12 +117,6 @@ export declare function readLocalFileSafely(params: {
 export declare function openLocalFileSafely(params: {
     filePath: string;
 }): Promise<OpenResult>;
-export type WritableOpenResult = {
-    handle: FileHandle;
-    containment: ContainmentGuarantee;
+export type WritableOpenResult = OpenResult & {
     createdForWrite: boolean;
-    realPath: string;
-    stat: Stats;
-    [Symbol.asyncDispose](): Promise<void>;
 };
-//# sourceMappingURL=root-impl.d.ts.map

package/dist/root-impl.js

@@ -73,18 +73,19 @@ import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
 import { realpathSync } from "./realpath.js";
 import { mkdirPathFallback, prepareRootWriteTarget, tryMkdirAtExactParent } from "./root-directory-creation.js";
 import { isNonRegularWriteOpenError, resolveNonblockingWriteFlag } from "./write-open-flags.js";
-import { resolveRootPath, resolveRootPathForRemoval } from "./root-path.js";
+import { resolveRootPath, resolveRootPathSync, resolveRootPathForRemoval } from "./root-path.js";
 import { RemovalPathReceipts } from "./root-remove-receipt.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-list.js";
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -99,7 +100,7 @@ import { finishRootFallbackWrite } from "./root-write-publication.js";
 import { withRootFallbackCompatibilityLock } from "./root-write-compatibility.js";
 import { assertRootFallbackWritePath } from "./root-write-lock-binding.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { movePathNoReplaceNative } from "./root-move-noreplace.js";
+import { admitMoveSourceStat, movePathNoReplaceNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.js";
 import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { writeAllToFile } from "./write-file-handle.js";
@@ -186,30 +187,19 @@ async function openVerifiedLocalFile(filePath, options) {
     }
 }
 export class RootHandle {
-    rootGuard;
-    rootIdentity;
+    context;
     rootDir;
     rootReal;
     rootWithSep;
     defaults;
     constructor(context, defaults = {}) {
-        this.rootGuard = context.rootGuard;
-        this.rootIdentity = context.rootIdentity;
+        this.context = context;
         this.rootDir = context.rootDir;
         this.rootReal = context.rootReal;
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
     }
-    get context() {
-        return {
-            rootDir: this.rootDir,
-            rootGuard: this.rootGuard,
-            rootIdentity: this.rootIdentity,
-            rootReal: this.rootReal,
-            rootWithSep: this.rootWithSep,
-        };
-    }
     mutationOptions(options) {
         return {
             ...options,
@@ -224,9 +214,9 @@ export class RootHandle {
     }
     async open(relativePath, options = {}) {
         return await openFileInRoot(this.context, {
-            relativePath,
             ...readDefaults(this.defaults),
             ...options,
+            relativePath,
         });
     }
     async read(relativePath, options = {}) {
@@ -246,9 +236,11 @@ export class RootHandle {
         return JSON.parse(await this.readText(relativePath, options));
     }
     async readAbsolute(filePath, options = {}) {
-        return await readPathInRoot(this.context, {
-            filePath,
-            ...mergeReadOptions(this.defaults, options),
+        const context = this.context;
+        const readOptions = mergeReadOptions(this.defaults, options);
+        return await readFileInRoot(context, {
+            relativePath: rootRelativeReadPath(context, filePath),
+            ...readOptions,
         });
     }
     reader(options = {}) {
@@ -260,10 +252,11 @@ export class RootHandle {
         assertValidRootDestinationPath(relativePath);
         const writeMode = options.writeMode ?? "replace";
         const target = await openWritableFileInRoot(this.context, {
-            relativePath,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            expectedWritePath: undefined,
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
         }).catch(rethrowMutationAuthorityError);
@@ -272,11 +265,11 @@ export class RootHandle {
     async append(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await appendFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -285,33 +278,34 @@ export class RootHandle {
         validateRemoveOptions(options);
         options.signal?.throwIfAborted();
         await removePathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
         }).catch(rethrowMutationAuthorityError);
     }
     async mkdir(relativePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await mkdirPathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
+            allowRoot: false,
         }).catch(rethrowMutationAuthorityError);
     }
     async ensureRoot(options = {}) {
         await mkdirPathInRoot(this.context, {
+            ...this.mutationOptions(options),
             relativePath: "",
             allowRoot: true,
-            ...this.mutationOptions(options),
         }).catch(rethrowMutationAuthorityError);
     }
     async write(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await writeFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             renameIdentity: this.defaults.renameIdentity,
             ...this.mutationOptions(options),
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -319,11 +313,11 @@ export class RootHandle {
         assertValidRootDestinationPath(relativePath);
         const durable = options.durable ?? this.defaults.durable ?? true;
         await writeFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(createInputOptions(data, options, this.defaults.maxBytes)),
+            relativePath,
+            data,
             durable: durable !== false,
             strictFileSync: durable === "file",
             overwrite: false,
@@ -343,12 +337,13 @@ export class RootHandle {
         options.signal?.throwIfAborted();
         assertValidRootDestinationPath(relativePath);
         const { maxBytes, ...copyOptions } = this.mutationOptions(options);
+        const copySource = typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath };
         await copyFileInRoot(this.context, {
-            source: typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath },
-            relativePath,
             maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
             ...copyOptions,
+            source: copySource,
+            relativePath,
             mode: options.mode ?? this.defaults.mode,
             durable: options.durable ?? this.defaults.durable ?? true,
             verifyPublished: options[onCopyPublication],
@@ -409,7 +404,7 @@ export class RootHandle {
     walk(relativePath, options) {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
-            rootReal: this.rootReal,
+            rootReal: this.context.rootReal,
             stat: relative => this.stat(relative),
             list: async (relative, listingOptions) => {
                 validatePinnedOperationPayload({ relativePath: relative });
@@ -468,15 +463,6 @@ async function readFileInRoot(root, params) {
         await opened.handle.close().catch(() => { });
     }
 }
-async function readPathInRoot(root, params) {
-    const relativePath = rootRelativeReadPath(root, params.filePath);
-    return await readFileInRoot(root, {
-        relativePath,
-        hardlinks: params.hardlinks,
-        maxBytes: params.maxBytes,
-        symlinks: params.symlinks,
-    });
-}
 export async function readLocalFileSafely(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
     const opened = await openLocalFileSafely({ filePath: params.filePath });
@@ -502,7 +488,7 @@ function buildAtomicWriteTempPath(targetPath) {
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
-async function openWritableFileInRoot(root, params) {
+async function openWritableFileInRoot(root, params, options) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : await resolveGuardedWriteTargetInRoot(root, {
@@ -566,6 +552,17 @@ async function openWritableFileInRoot(root, params) {
             if (!isNotFoundPathError(err)) {
                 throw err;
             }
+            if (options?.createIfMissing === false) {
+                const parentGuard = writePathSelection?.parentGuard ??
+                    await createAsyncDirectoryGuard(path.dirname(ioPath), { bigint: true });
+                assertRootIdentityCurrentSync(root);
+                if (!admitPathInsideRoot({
+                    rootPath: root.rootReal, candidatePath: parentGuard.realPath, rootIdentity: root.rootIdentity,
+                }))
+                    throw outsideWorkspaceError();
+                assertSyncDirectoryGuard(parentGuard);
+                return { missing: true, targetPath: ioPath, parentGuard, writeSelection: writePathSelection };
+            }
             if (writePathSelection)
                 await refreshRootWritePathSelection(writePathSelection);
             params.assertBeforeMutation?.();
@@ -723,8 +720,9 @@ async function appendFileInRoot(root, params) {
             if (params.prependNewlineIfNeeded === true &&
                 !target.createdForWrite &&
                 target.stat.size > 0 &&
+                params.data.length > 0 &&
                 ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
-                    (Buffer.isBuffer(params.data) && params.data.length > 0 && params.data[0] !== 0x0a))) {
+                    (Buffer.isBuffer(params.data) && params.data[0] !== 0x0a))) {
                 const newline = Buffer.from("\n", typeof params.data === "string" ? params.encoding : "utf8");
                 const tail = Buffer.alloc(newline.length);
                 const { bytesRead } = await target.handle.read(tail, 0, tail.length, Math.max(0, target.stat.size - tail.length));
@@ -789,16 +787,11 @@ async function mkdirPathInRoot(root, params) {
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
+    const resolution = { relativePath: params.relativePath, allowRoot: params.allowRoot, ...policy };
     const resolveCurrent = policy
-        ? async () => await resolvePinnedPathInRoot(root, {
-            ...params,
-            denyMutations: policy.denyMutations,
-            mutationSymlinks: policy.mutationSymlinks,
-        })
+        ? async () => await resolvePinnedPathInRoot(root, resolution)
         : undefined;
-    const resolved = resolveCurrent
-        ? await resolveCurrent()
-        : await resolvePinnedPathInRoot(root, params);
+    const resolved = await resolvePinnedPathInRoot(root, resolution);
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
@@ -994,20 +987,9 @@ async function copyFileInRoot(root, params) {
     }
 }
 async function resolvePinnedPathInRoot(root, params) {
-    return await resolvePinnedOperationPathInRoot(root, {
-        allowRoot: params.allowRoot,
-        denyMutations: params.denyMutations,
-        mutationSymlinks: params.mutationSymlinks,
-        protectDenyMutationAncestors: params.remove === true,
-        relativePath: params.relativePath,
-        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
-        removalReceipts: params.removalReceipts,
-    });
-}
-async function resolvePinnedOperationPathInRoot(root, params) {
     const resolved = await resolvePinnedRootPathInRoot(root, {
         relativePath: params.relativePath,
-        policy: params.policy,
+        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
         mutationSymlinks: params.mutationSymlinks,
         removalReceipts: params.removalReceipts,
     });
@@ -1034,7 +1016,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     }
     resolved.canonicalPath = admittedCanonicalPath.path;
     await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
-        protectAncestors: params.protectDenyMutationAncestors,
+        protectAncestors: params.remove === true,
     });
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
@@ -1085,6 +1067,8 @@ async function listPathFallback(root, relativePath, withFileTypes) {
     return await listDirectoryPath(root, resolved.resolved, withFileTypes, resolved.receipt);
 }
 async function movePathFallback(root, params) {
+    const originalRoutes = params.overwrite && params.assertBeforeMutation
+        ? await Promise.all([params.fromRelative, params.toRelative].map(expandRelativePathWithHome)) : undefined;
     const source = await resolvePathInRoot(root, params.fromRelative, {
         aliasErrorCode: "path-alias",
         allowFinalSymlink: true,
@@ -1120,9 +1104,14 @@ async function movePathFallback(root, params) {
                 targetStat?.isSymbolicLink() === true);
         },
     });
-    let sourceStat;
+    let sourceIdentity;
     try {
-        sourceStat = fsSync.lstatSync(source.resolved);
+        if (params.overwrite && params.assertBeforeMutation) {
+            sourceIdentity = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true));
+        }
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(source.resolved), params.overwrite);
+        }
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -1130,19 +1119,10 @@ async function movePathFallback(root, params) {
         }
         throw error;
     }
-    if (sourceStat.isSymbolicLink()) {
-        throw new FsSafeError("symlink", "symlink not allowed");
-    }
-    if (sourceStat.isFile() && sourceStat.nlink > 1) {
-        throw hardlinkedPathNotAllowedError();
-    }
-    if (!params.overwrite && sourceStat.isDirectory()) {
-        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    if (!pinnedTarget) {
+        throw new FsSafeError("path-mismatch", "destination admission was not completed");
     }
     if (!params.overwrite) {
-        if (!pinnedTarget) {
-            throw new FsSafeError("path-mismatch", "destination admission was not completed");
-        }
         await movePathNoReplaceNative(root, params, {
             sourcePath: source.resolved,
             sourceParentPath: path.dirname(pinnedSource.canonicalPath),
@@ -1151,8 +1131,9 @@ async function movePathFallback(root, params) {
         });
         return;
     }
-    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
-    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
+    const guardOptions = { bigint: sourceIdentity !== undefined };
+    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved), guardOptions);
+    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved), guardOptions);
     await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
     await assertAsyncDirectoryGuard(sourceParentGuard);
     await assertAsyncDirectoryGuard(targetParentGuard);
@@ -1160,6 +1141,31 @@ async function movePathFallback(root, params) {
         assertFinalSymlinkRejected(source.resolved, params.mutationSymlinks !== undefined);
         assertFinalSymlinkRejected(target.resolved, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
+        if (sourceIdentity) {
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(sourceParentGuard);
+            assertSyncDirectoryGuard(targetParentGuard);
+            for (const [route, selected, expected, policy] of [
+                [originalRoutes[0], source.resolved, pinnedSource.canonicalPath, PATH_ALIAS_POLICIES.strict],
+                [originalRoutes[1], target.resolved, pinnedTarget.canonicalPath, PATH_ALIAS_POLICIES.unlinkTarget],
+            ]) {
+                for (const absolutePath of new Set([path.isAbsolute(route) ? route : `${root.rootWithSep}${route}`, selected])) {
+                    try {
+                        const current = resolveRootPathSync({
+                            absolutePath, rootPath: root.rootReal, rootCanonicalPath: root.rootReal,
+                            rootIdentity: root.rootIdentity, boundaryLabel: "root", policy,
+                            ...mutationSymlinkResolution(params.mutationSymlinks),
+                        });
+                        if (current.canonicalPath !== expected)
+                            throw new FsSafeError("path-mismatch", "move route changed during authorization");
+                    }
+                    catch (error) {
+                        throw normalizePinnedPathError(error);
+                    }
+                }
+            }
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(source.resolved, { bigint: true }), true), sourceIdentity);
+        }
         await fs.rename(source.resolved, target.resolved);
     }
     catch (error) {
@@ -1197,48 +1203,59 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         await writeMissingFileFallback(root, params, expectedWritePath);
         return;
     }
-    const { opened: target, identity: targetIdentity, writeSelection: retainedSelection } = await openWritableFileInRoot(root, {
+    const admissionParams = {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
-        // Private, writable placeholder: Windows cannot rename over a read-only file.
-        mode: 0o600,
         denyMutations: params.denyMutations,
         assertBeforeMutation: params.assertBeforeMutation,
         mutationSymlinks: params.mutationSymlinks,
         truncateExisting: false,
         expectedWritePath,
-    });
+    };
+    const admission = await openWritableFileInRoot(root, admissionParams, { createIfMissing: false });
+    const existing = "missing" in admission ? undefined : admission;
+    const target = existing?.opened;
+    const retainedSelection = existing?.writeSelection;
+    const missingSelection = "missing" in admission ? admission.writeSelection : undefined;
     const policyEnabled = params.denyMutations !== undefined || params.mutationSymlinks !== undefined;
-    const destinationPath = retainedSelection?.selectedPath ?? target.realPath;
-    const mode = params.mode ?? (target.stat.mode & 0o777);
-    if (policyEnabled && !retainedSelection) {
-        await target.handle.close().catch(() => undefined);
+    const destinationPath = "missing" in admission ? admission.targetPath
+        : retainedSelection?.selectedPath ?? admission.opened.realPath;
+    let mode = params.mode ?? (target ? target.stat.mode & 0o777 : undefined);
+    if (policyEnabled && !retainedSelection && !missingSelection) {
+        await target?.handle.close().catch(() => undefined);
         throw new FsSafeError("path-mismatch", "write admission state was not retained");
     }
-    const destinationGuard = retainedSelection?.parentGuard ??
+    const destinationGuard = "missing" in admission ? admission.parentGuard : retainedSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(destinationPath), { bigint: true }).catch(async (error) => {
-            await target.handle.close().catch(() => undefined);
+            await target?.handle.close().catch(() => undefined);
             throw error;
         });
     let tempPath = null;
     let unregisterTempPath = null;
     let writtenHandle;
     let writtenIdentity;
-    let placeholderIdentity;
-    let published = false;
+    let lateTargetHandle;
     try {
-        if (target.createdForWrite)
-            placeholderIdentity = targetIdentity;
         tempPath = buildAtomicWriteTempPath(destinationPath);
         if (retainedSelection) {
-            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target.handle.fd);
+            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target?.handle.fd);
+        }
+        else if (missingSelection) {
+            await refreshRootWritePathSelection(missingSelection);
         }
         params.assertBeforeMutation?.();
         if (retainedSelection) {
-            assertRootWriteSelectionSync(root, retainedSelection, true, target.handle.fd);
+            assertRootWriteSelectionSync(root, retainedSelection, true, target?.handle.fd);
+        }
+        else if (missingSelection) {
+            assertRootWritePathSelectionSync(root, missingSelection);
         }
+        assertRootIdentityCurrentSync(root);
+        assertSyncDirectoryGuard(destinationGuard);
         writtenHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
         writtenIdentity = fsSync.fstatSync(writtenHandle.fd, { bigint: true });
+        // Preserve the creation mask when no existing destination supplies a mode.
+        mode ??= Number(writtenIdentity.mode & 511n);
         unregisterTempPath = registerTempPathForExit(tempPath, { identity: writtenIdentity, singleLinkFile: true });
         await writeAllToFile(writtenHandle, params.data, {
             encoding: params.encoding, assertBeforeMutation: params.assertBeforeMutation,
@@ -1253,24 +1270,42 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
                 root, targetPath: commitTempPath, fd: commitHandle.fd,
                 expectedIdentity: commitIdentity, parentGuard: destinationGuard,
             });
-            if (target.createdForWrite) {
-                await cleanupPinnedFilePath({
-                    pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-                });
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            let publicationIdentity = inspectFallbackReplacementDestination(destinationPath);
+            // A raced file needs its own access admission, not the old handle's rights.
+            if (publicationIdentity && (!existing || !sameFileIdentity(publicationIdentity, existing.identity))) {
+                const admitted = await openWritableFileInRoot(root, {
+                    ...admissionParams, mkdir: false, expectedWritePath: destinationPath,
+                }, { createIfMissing: false });
+                lateTargetHandle = "missing" in admitted ? undefined : admitted.opened.handle;
+                publicationIdentity = "missing" in admitted ? undefined : admitted.identity;
+                await lateTargetHandle?.close();
             }
             // Windows cannot replace a destination while its old handle remains open.
-            await target.handle.close();
+            await target?.handle.close();
             if (retainedSelection) {
-                await refreshRetainedRootWriteAdmission(root, retainedSelection, !target.createdForWrite);
+                await refreshRetainedRootWriteAdmission(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                await refreshRootWritePathSelection(missingSelection);
             }
             assertFinalSymlinkRejected(destinationPath, params.mutationSymlinks !== undefined);
             params.assertBeforeMutation?.();
             if (retainedSelection) {
-                assertRootWriteSelectionSync(root, retainedSelection, !target.createdForWrite);
+                assertRootWriteSelectionSync(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                assertRootWritePathSelectionSync(root, missingSelection);
+            }
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            const current = inspectFallbackReplacementDestination(destinationPath);
+            if (publicationIdentity ? !current || !sameFileIdentity(current, publicationIdentity) : current) {
+                throw new FsSafeError("path-mismatch", "write destination changed before publication");
             }
             await fs.rename(commitTempPath, destinationPath);
             tempPath = null;
-            published = true;
         });
         unregisterTempPath();
         unregisterTempPath = null;
@@ -1283,12 +1318,8 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         });
     }
     finally {
-        if (!published && target.createdForWrite) {
-            await cleanupPinnedFilePath({
-                pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-            });
-        }
-        await target.handle.close().catch(() => undefined);
+        await target?.handle.close().catch(() => undefined);
+        await lateTargetHandle?.close().catch(() => undefined);
         if (tempPath && writtenHandle) {
             await cleanupPinnedFilePath({
                 pathname: tempPath, handle: writtenHandle, identity: writtenIdentity, parentGuard: destinationGuard,
@@ -1298,6 +1329,23 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         unregisterTempPath?.();
     }
 }
+function inspectFallbackReplacementDestination(targetPath) {
+    let current;
+    try {
+        current = inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            return;
+        throw error;
+    }
+    if (current.isSymbolicLink() || !current.isFile()) {
+        throw new FsSafeError("path-mismatch", "write destination changed before publication");
+    }
+    if (current.nlink > 1n)
+        throw hardlinkedPathNotAllowedError();
+    return current;
+}
 async function writeMissingFileFallback(root, params, expectedWritePath) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
@@ -1324,6 +1372,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
     const parentGuard = pathSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     let created = false;
+    let completed = false;
     let createdIdentity;
     let writtenHandle;
     let verifyingPublication = false;
@@ -1367,6 +1416,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
         });
         if (params.durable !== false)
             await syncDirectoryBestEffort(path.dirname(targetPath));
+        completed = true;
     }
     catch (err) {
         if (verifyingPublication)
@@ -1384,6 +1434,9 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
                 pathname: targetPath, handle: writtenHandle, identity: createdIdentity, parentGuard,
             });
         }
-        await writtenHandle?.close().catch(() => undefined);
+        if (completed)
+            await writtenHandle?.close();
+        else
+            await writtenHandle?.close().catch(() => undefined);
     }
 }

package/dist/root-move-noreplace.d.ts

@@ -1,6 +1,8 @@
+import { type BigIntStats, type Stats } from "node:fs";
 import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootContext } from "./root-context.js";
 import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
 export declare function movePathNoReplaceNative(root: RootContext, params: {
     assertBeforeMutation?: () => void;
     denyMutations?: DenyMutationPolicy;
@@ -11,4 +13,3 @@ export declare function movePathNoReplaceNative(root: RootContext, params: {
     targetPath: string;
     targetParentPath: string;
 }): Promise<void>;
-//# sourceMappingURL=root-move-noreplace.d.ts.map

package/dist/root-move-noreplace.js

@@ -58,14 +58,14 @@ function normalizeRenameNoReplaceError(error) {
     }
     return normalizeMoveError(error);
 }
-function admitMoveSourceStat(stat) {
+export function admitMoveSourceStat(stat, overwrite = false) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("symlink", "symlink not allowed");
     }
     if (stat.isFile() && stat.nlink > 1) {
         throw hardlinkedPathNotAllowedError();
     }
-    if (stat.isDirectory()) {
+    if (!overwrite && stat.isDirectory()) {
         throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
     }
     return stat;