@openclaw/fs-safe 0.9.0 → 0.10.0

package/dist/root-impl.js

@@ -1,8 +1,61 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { randomUUID } from "node:crypto";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -18,9 +71,11 @@ import { validatePinnedOperationPayload } from "./pinned-operation.js";
 import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
+import { cleanupPinnedFilePath } from "./replace-file-temp-owner.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { isNonRegularWriteOpenError, resolveNonblockingWriteFlag } from "./write-open-flags.js";
 import { resolveRootPath } from "./root-path.js";
+import { listDirectoryForWalk, listDirectoryPath, pathStatFromStats } from "./root-directory-list.js";
 import { assertRootIdentityCurrent, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, normalizeRemoveGuardError, normalizeRemovePathError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -31,7 +86,12 @@ import { serializePathWrite } from "./write-queue.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
 import { inheritWriteTargetMode } from "./root-write-mode.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-import { onCopyPublication } from "./copy-publication.js";
+import { createCopyPublicationObserver, onCopyPublication } from "./copy-publication.js";
+import { writeAllToFile } from "./write-file-handle.js";
+import { assertFinalSymlinkRejected, mutationSymlinkResolution, readSymlinkResolution } from "./root-symlink-policy.js";
+import { mergeReadOptions, readDefaults, } from "./root-options.js";
+import { composeMutationAssertions, MutationAuthorityError, rethrowMutationAuthorityError } from "./mutation-authority.js";
+export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
 function logWarn(message) {
     if (process.env.FS_SAFE_DEBUG_WARNINGS === "1") {
@@ -54,22 +114,6 @@ const OPEN_APPEND_CREATE_FLAGS = fsConstants.O_RDWR |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
     (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
-function pathStatFromStats(stat) {
-    return {
-        dev: Number(stat.dev),
-        gid: Number(stat.gid),
-        ino: Number(stat.ino),
-        isDirectory: stat.isDirectory(),
-        isFile: stat.isFile(),
-        isSymbolicLink: stat.isSymbolicLink(),
-        mode: stat.mode,
-        mtimeMs: stat.mtimeMs,
-        nlink: stat.nlink,
-        size: stat.size,
-        uid: stat.uid,
-    };
-}
 function openResult(params) {
     return {
         handle: params.handle,
@@ -215,12 +259,14 @@ export class RootHandle {
     mutationOptions(options) {
         return {
             ...options,
+            assertBeforeMutation: composeMutationAssertions(this.defaults.assertBeforeMutation, options.assertBeforeMutation),
+            mutationSymlinks: options.mutationSymlinks ?? this.defaults.mutationSymlinks,
             denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
         };
     }
     async resolve(relativePath) {
         assertValidRootDestinationPath(relativePath);
-        return (await resolvePathInRoot(this.context, relativePath, { allowFinalSymlink: true })).resolved;
+        return (await resolvePathInRoot(this.context, relativePath, { allowFinalSymlink: true, resolveCanonical: true })).resolved;
     }
     async open(relativePath, options = {}) {
         return await openFileInRoot(this.context, {
@@ -266,7 +312,7 @@ export class RootHandle {
             ...this.mutationOptions(options),
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async append(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
@@ -277,28 +323,28 @@ export class RootHandle {
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
             durable: options.durable ?? this.defaults.durable ?? true,
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async remove(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
         await removePathInRoot(this.context, {
             relativePath,
             ...this.mutationOptions(options),
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async mkdir(relativePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await mkdirPathInRoot(this.context, {
             relativePath,
             ...this.mutationOptions(options),
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async ensureRoot(options = {}) {
         await mkdirPathInRoot(this.context, {
             relativePath: "",
             allowRoot: true,
             ...this.mutationOptions(options),
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async write(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
@@ -310,7 +356,7 @@ export class RootHandle {
             renameIdentity: this.defaults.renameIdentity,
             ...this.mutationOptions(options),
             durable: options.durable ?? this.defaults.durable ?? true,
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async create(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
@@ -322,7 +368,7 @@ export class RootHandle {
             ...this.mutationOptions(options),
             durable: options.durable ?? this.defaults.durable ?? true,
             overwrite: false,
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async writeJson(relativePath, data, options = {}) {
         const { replacer, space, trailingNewline = true, ...writeOptions } = options;
@@ -334,19 +380,20 @@ export class RootHandle {
         const json = stringifyJsonDocument(data, replacer, space);
         await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
     }
-    async copyIn(relativePath, sourcePath, options = {}) {
+    async copyIn(relativePath, source, options = {}) {
+        options.signal?.throwIfAborted();
         assertValidRootDestinationPath(relativePath);
         const { maxBytes, ...copyOptions } = this.mutationOptions(options);
         await copyFileInRoot(this.context, {
-            sourcePath,
+            source: typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath },
             relativePath,
             maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
             ...copyOptions,
+            mode: options.mode ?? this.defaults.mode,
             durable: options.durable ?? this.defaults.durable ?? true,
             verifyPublished: options[onCopyPublication],
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     async exists(relativePath) {
         try {
@@ -374,7 +421,7 @@ export class RootHandle {
         assertValidRootRelativePath(fromRelative);
         assertValidRootDestinationPath(toRelative);
         validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
-        const { denyMutations } = this.mutationOptions(options);
+        const { denyMutations, assertBeforeMutation, mutationSymlinks } = this.mutationOptions(options);
         await assertMoveMutationAllowed(this.context, {
             fromRelative,
             toRelative,
@@ -383,31 +430,25 @@ export class RootHandle {
         await movePathFallback(this.context, {
             fromRelative,
             denyMutations,
+            assertBeforeMutation,
+            mutationSymlinks,
             overwrite: options.overwrite ?? false,
             toRelative,
-        });
+        }).catch(rethrowMutationAuthorityError);
     }
     walk(relativePath, options) {
         assertValidRootRelativePath(relativePath);
-        return walkRoot(this, relativePath, options);
+        return walkRoot({
+            rootReal: this.rootReal,
+            stat: relative => this.stat(relative),
+            list: async (relative, listingOptions) => {
+                validatePinnedOperationPayload({ relativePath: relative });
+                const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
+                return await listDirectoryForWalk(this.context, resolved.resolved, listingOptions);
+            },
+        }, relativePath, options);
     }
 }
-function readDefaults(defaults) {
-    return {
-        hardlinks: defaults.hardlinks,
-        maxBytes: normalizeMaxBytes(defaults.maxBytes, { defaultValue: DEFAULT_ROOT_MAX_BYTES }),
-        symlinks: defaults.symlinks,
-    };
-}
-function mergeReadOptions(defaults, options) {
-    const merged = readDefaults(defaults);
-    if (options.hardlinks !== undefined)
-        merged.hardlinks = options.hardlinks;
-    merged.maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: merged.maxBytes });
-    if (options.symlinks !== undefined)
-        merged.symlinks = options.symlinks;
-    return merged;
-}
 export async function root(rootDir, defaults = {}) {
     normalizeMaxBytes(defaults.maxBytes);
     return new RootHandle(await resolveRootContext(rootDir), defaults);
@@ -416,7 +457,8 @@ async function openFileInRoot(root, params) {
     const { rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath, {
         allowFinalSymlink: true,
         rejectUnsafeDeviceReads: true,
-        rejectSymlinks: params.symlinks !== "follow-within-root",
+        ...readSymlinkResolution(params.symlinks),
+        resolveCanonical: true,
     });
     const { opened } = await openVerifiedLocalFile(resolved, {
         symlinks: params.symlinks,
@@ -472,38 +514,22 @@ function buildAtomicWriteTempPath(targetPath) {
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
-async function prepareRootWriteTarget(rootReal, targetPath) {
+async function prepareRootWriteTarget(rootReal, targetPath, assertBeforeMutation) {
     const parentPath = await mkdirPathComponentsWithGuards({
         rootReal,
         targetPath: path.dirname(targetPath),
+        assertBeforeMutation,
     });
     // Continue through the guarded walk's real parent instead of re-entering
     // the original path through a symlinked component.
     return path.join(parentPath, path.basename(targetPath));
 }
-async function writeTempFileForAtomicReplace(params) {
-    const tempHandle = await fs.open(params.tempPath, OPEN_WRITE_CREATE_FLAGS, params.mode);
-    try {
-        if (typeof params.data === "string") {
-            await tempHandle.writeFile(params.data, params.encoding ?? "utf8");
-        }
-        else {
-            await tempHandle.writeFile(params.data);
-        }
-        return {
-            handle: tempHandle,
-            identity: fsSync.fstatSync(tempHandle.fd, { bigint: true }),
-        };
-    }
-    catch (error) {
-        await tempHandle.close().catch(() => { });
-        throw error;
-    }
-}
 async function resolveGuardedWritePathInRoot(root, params) {
     const resolvedPath = await resolvePathInRoot(root, params.relativePath, {
         aliasErrorCode: "path-alias",
+        rejectAmbiguousParents: true,
         allowFinalSymlink: params.allowFinalSymlink,
+        ...mutationSymlinkResolution(params.mutationSymlinks),
     });
     await assertMutationNotDenied(resolvedPath.resolved, params.denyMutations, params.protectDeniedAncestors ? { protectAncestors: true } : undefined);
     if (await (params.shouldAssertNoPathAlias?.(resolvedPath) ?? true)) {
@@ -526,12 +552,14 @@ async function openWritableFileInRoot(root, params) {
     const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
         relativePath: params.relativePath,
         denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
     });
     let ioPath = params.mkdir === false
         ? resolved
-        : await prepareRootWriteTarget(rootReal, resolved);
+        : await prepareRootWriteTarget(rootReal, resolved, params.assertBeforeMutation);
     try {
-        const resolvedRealPath = fsSync.realpathSync.native(ioPath);
+        assertFinalSymlinkRejected(ioPath, params.mutationSymlinks !== undefined);
+        const resolvedRealPath = params.mutationSymlinks === undefined ? fsSync.realpathSync.native(ioPath) : ioPath;
         if (!isPathInside(rootWithSep, resolvedRealPath)) {
             throw outsideWorkspaceError();
         }
@@ -561,6 +589,7 @@ async function openWritableFileInRoot(root, params) {
             if (!isNotFoundPathError(err)) {
                 throw err;
             }
+            params.assertBeforeMutation?.();
             handle = await fs.open(ioPath, createFlags, mode);
             createdForWrite = true;
         }
@@ -619,6 +648,8 @@ async function openWritableFileInRoot(root, params) {
         // Truncate only after boundary and identity checks complete. This avoids
         // irreversible side effects if a symlink target changes before validation.
         if (params.append !== true && params.truncateExisting !== false && !createdForWrite) {
+            assertFinalSymlinkRejected(ioPath, params.mutationSymlinks !== undefined);
+            params.assertBeforeMutation?.();
             await handle.truncate(0);
         }
         return {
@@ -641,42 +672,72 @@ async function openWritableFileInRoot(root, params) {
     }
 }
 async function appendFileInRoot(root, params) {
-    const target = await openWritableFileInRoot(root, {
-        relativePath: params.relativePath,
-        mkdir: params.mkdir,
-        mode: params.mode,
-        denyMutations: params.denyMutations,
-        truncateExisting: false,
-        append: true,
-    });
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        let prefix = "";
-        if (params.prependNewlineIfNeeded === true &&
-            !target.createdForWrite &&
-            target.stat.size > 0 &&
-            ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
-                (Buffer.isBuffer(params.data) && params.data.length > 0 && params.data[0] !== 0x0a))) {
-            const lastByte = Buffer.alloc(1);
-            const { bytesRead } = await target.handle.read(lastByte, 0, 1, target.stat.size - 1);
-            if (bytesRead === 1 && lastByte[0] !== 0x0a) {
-                prefix = "\n";
+        const target = await openWritableFileInRoot(root, {
+            relativePath: params.relativePath,
+            mkdir: params.mkdir,
+            mode: params.mode,
+            denyMutations: params.denyMutations,
+            assertBeforeMutation: params.assertBeforeMutation,
+            mutationSymlinks: params.mutationSymlinks,
+            truncateExisting: false,
+            append: true,
+        });
+        let dispatched = false;
+        // Reverse disposal order closes the handle before path cleanup and retains both failures.
+        const cleanup = __addDisposableResource(env_1, {
+            async [Symbol.asyncDispose]() {
+                if (!dispatched && target.createdForWrite) {
+                    await removePathIfIdentityUnchanged(target.realPath, target.stat);
+                }
+            },
+        }, true);
+        const handle = __addDisposableResource(env_1, target.handle, true);
+        try {
+            let prefix = "";
+            if (params.prependNewlineIfNeeded === true &&
+                !target.createdForWrite &&
+                target.stat.size > 0 &&
+                ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
+                    (Buffer.isBuffer(params.data) && params.data.length > 0 && 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));
+                if (bytesRead > 0 && (bytesRead !== newline.length || !tail.equals(newline))) {
+                    prefix = "\n";
+                }
+            }
+            const payload = typeof params.data === "string" ? `${prefix}${params.data}`
+                : prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
+            await writeAllToFile(target.handle, payload, {
+                encoding: params.encoding,
+                assertBeforeMutation: () => {
+                    assertFinalSymlinkRejected(target.realPath, params.mutationSymlinks !== undefined);
+                    params.assertBeforeMutation?.();
+                    dispatched = true;
+                },
+            });
+            // A successful empty append still creates the file, as Node's appendFile does.
+            dispatched = true;
+            if (params.durable !== false)
+                await target.handle.sync();
+            if (params.durable !== false && target.createdForWrite) {
+                await syncDirectoryBestEffort(path.dirname(target.realPath));
             }
         }
-        if (typeof params.data === "string") {
-            await target.handle.appendFile(`${prefix}${params.data}`, params.encoding ?? "utf8");
-        }
-        else {
-            const payload = prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
-            await target.handle.appendFile(payload);
-        }
-        if (params.durable !== false)
-            await target.handle.sync();
-        if (params.durable !== false && target.createdForWrite) {
-            await syncDirectoryBestEffort(path.dirname(target.realPath));
+        catch (error) {
+            rethrowMutationAuthorityError(error);
         }
     }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
     finally {
-        await target.handle.close().catch(() => { });
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
     }
 }
 async function removePathInRoot(root, params) {
@@ -684,10 +745,11 @@ async function removePathInRoot(root, params) {
     const resolved = await resolvePinnedPathInRoot(root, {
         relativePath: params.relativePath,
         denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
         remove: true,
     });
     try {
-        await removePathFallback(resolved);
+        await removePathFallback(resolved, params.assertBeforeMutation, params.mutationSymlinks !== undefined);
     }
     catch (error) {
         throw normalizePinnedPathError(error);
@@ -697,7 +759,7 @@ async function mkdirPathInRoot(root, params) {
     validatePinnedOperationPayload({ relativePath: params.relativePath });
     const resolved = await resolvePinnedPathInRoot(root, params);
     try {
-        await mkdirPathFallback(resolved);
+        await mkdirPathFallback(resolved, params.assertBeforeMutation, params.mutationSymlinks !== undefined);
     }
     catch (error) {
         throw normalizePinnedPathError(error);
@@ -710,7 +772,7 @@ async function writeFileInRoot(root, params) {
             await writeFileFallback(root, params);
             return;
         }
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations, params.overwrite);
+        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations, params.overwrite, params.mutationSymlinks);
         await serializePathWrite(pinned.targetPath, async () => {
             await commitPinnedWriteInRoot(root, pinned, params);
         });
@@ -729,8 +791,10 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
             mode: params.mode ?? pinned.mode,
             sync: params.durable !== false,
             overwrite: params.overwrite,
+            rejectFinalSymlink: params.mutationSymlinks !== undefined,
             input: { kind: "buffer", data: params.data, encoding: params.encoding },
             rootIdentity: root.rootIdentity,
+            assertBeforeMutation: params.assertBeforeMutation,
             verifyPublished: async (fd, expectedIdentity, parentGuard) => {
                 verifyingPublication = true;
                 try {
@@ -765,46 +829,75 @@ async function commitPinnedWriteInRoot(root, pinned, params) {
     }
 }
 async function copyFileInRoot(root, params) {
-    assertValidRootRelativePath(params.relativePath);
-    assertNoNulPathInput(params.sourcePath, "source path contains a NUL byte");
-    const { opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.sourcePath, {
-        hardlinks: params.sourceHardlinks,
-    });
+    params.signal?.throwIfAborted();
+    const clone = resolveFileCopyCloneMode(params.clone);
+    let source;
+    let sourceIdentity;
+    if (typeof params.source === "string") {
+        assertNoNulPathInput(params.source, "source path contains a NUL byte");
+        ({ opened: source, identity: sourceIdentity } = await openVerifiedLocalFile(params.source, {
+            hardlinks: params.sourceHardlinks,
+        }));
+    }
+    else {
+        source = await params.source.root.open(params.source.relativePath, params.sourceHardlinks === undefined ? undefined : { hardlinks: params.sourceHardlinks });
+        try {
+            sourceIdentity = await inspectFileIdentity(() => fsSync.fstatSync(source.handle.fd, { bigint: true }));
+        }
+        catch (error) {
+            await source.handle.close().catch(() => undefined);
+            throw error;
+        }
+    }
     if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
         await source.handle.close().catch(() => { });
         throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
     }
     try {
         await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode, params.denyMutations);
+            const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode ?? (params.preserveSourceMode ? Number(sourceIdentity.mode & 4095n) : undefined), params.denyMutations, params.overwrite !== false, params.mutationSymlinks);
             await serializePathWrite(pinned.targetPath, async () => {
                 await assertCopySourceCurrent(source, sourceIdentity);
-                let identity;
+                const verifySource = async () => {
+                    params.signal?.throwIfAborted();
+                    if (typeof params.source !== "string") {
+                        await params.source.root.stat(".");
+                    }
+                    await assertCopySourceCurrent(source, sourceIdentity);
+                };
+                const observer = createCopyPublicationObserver(pinned.targetPath, params.onDestinationPublished);
                 try {
-                    identity = await runPinnedWriteHelper({
+                    await runPinnedWriteHelper({
                         rootPath: pinned.rootReal,
                         relativeParentPath: pinned.relativeParentPath,
                         basename: pinned.basename,
                         mkdir: params.mkdir !== false,
                         mode: pinned.mode,
-                        overwrite: true,
+                        overwrite: params.overwrite !== false,
+                        rejectFinalSymlink: params.mutationSymlinks !== undefined,
                         maxBytes: params.maxBytes,
                         sync: params.durable !== false,
+                        assertBeforeMutation: () => {
+                            if (params.signal?.aborted)
+                                throw new MutationAuthorityError(params.signal.reason);
+                            params.assertBeforeMutation?.();
+                        },
                         verifyPublished: params.verifyPublished,
-                        input: { kind: "stream", stream: source.handle.createReadStream() },
+                        onPublished: observer.onPublished,
+                        input: { kind: "file", handle: source.handle, size: source.stat.size, clone, signal: params.signal, verifySource },
                         rootIdentity: root.rootIdentity,
                     });
                 }
                 catch (error) {
+                    observer.rethrowObserverFailure(error);
+                    if (params.signal?.aborted && error === params.signal.reason)
+                        throw error;
+                    if (isAlreadyExistsError(error)) {
+                        throw new FsSafeError("already-exists", "copy destination already exists", { cause: error });
+                    }
                     throw normalizePinnedWriteError(error);
                 }
-                try {
-                    await assertCopySourcePathCurrent(source, sourceIdentity);
-                }
-                catch (error) {
-                    await removePathIfIdentityUnchanged(pinned.targetPath, identity).catch(() => undefined);
-                    throw error;
-                }
+                await verifySource();
             });
         });
     }
@@ -812,33 +905,20 @@ async function copyFileInRoot(root, params) {
         await source.handle.close().catch(() => { });
     }
 }
-async function assertCopySourceCurrent(source, identity) {
-    await inspectFileIdentity(() => fsSync.fstatSync(source.handle.fd, { bigint: true }), identity);
-    await assertCopySourcePathCurrent(source, identity);
-}
-async function assertCopySourcePathCurrent(source, identity) {
-    await inspectFileIdentity(async () => {
-        const current = fsSync.lstatSync(source.realPath, { bigint: true });
-        if (current.isSymbolicLink() || !current.isFile()) {
-            throw new FsSafeError("path-mismatch", "copy source path changed");
-        }
-        return current;
-    }, identity);
-}
 async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
-    const current = fsSync.lstatSync(targetPath);
-    if (current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity)) {
-        return;
-    }
     await withAsyncDirectoryGuards([parentGuard], async () => {
-        await fs.rm(targetPath);
+        const current = fsSync.lstatSync(targetPath);
+        if (current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity))
+            return;
+        await fs.unlink(targetPath);
     });
 }
-async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations, overwrite = true) {
+async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations, overwrite = true, mutationSymlinks) {
     const { rootReal, rootWithSep, resolved } = await resolveGuardedWritePathInRoot(root, {
         relativePath,
         denyMutations,
+        mutationSymlinks,
     });
     // resolvePathInRoot already enforces isPathInside, so any actual escape
     // is rejected upstream.
@@ -884,6 +964,7 @@ 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,
@@ -893,6 +974,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     const resolved = await resolvePinnedRootPathInRoot(root, {
         relativePath: params.relativePath,
         policy: params.policy,
+        mutationSymlinks: params.mutationSymlinks,
     });
     const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
     if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
@@ -929,9 +1011,12 @@ async function resolvePinnedRootPathInRoot(root, params) {
             rootCanonicalPath: rootReal,
             boundaryLabel: "root",
             policy: params.policy,
+            ...mutationSymlinkResolution(params.mutationSymlinks),
         });
     }
     catch (err) {
+        if (err instanceof FsSafeError && err.code === "symlink")
+            throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
     const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
@@ -952,19 +1037,23 @@ async function prepareRemoveGuard(targetPath) {
         throw normalizeRemoveGuardError(error);
     }
 }
-async function removePathFallback(resolved) {
+async function removePathFallback(resolved, assertBeforeMutation, rejectFinalSymlink = false) {
     const guard = await prepareRemoveGuard(resolved.resolved);
     try {
-        await (fsSync.lstatSync(resolved.resolved).isDirectory() ? fs.rmdir(resolved.resolved) : fs.rm(resolved.resolved));
+        const isDirectory = fsSync.lstatSync(resolved.resolved).isDirectory();
+        assertFinalSymlinkRejected(resolved.resolved, rejectFinalSymlink);
+        assertBeforeMutation?.();
+        await (isDirectory ? fs.rmdir(resolved.resolved) : fs.unlink(resolved.resolved));
     }
     catch (error) {
         throw normalizeRemovePathError(error);
     }
-    await assertAsyncDirectoryGuard(guard).catch(() => undefined);
+    await assertAsyncDirectoryGuard(guard).catch(error => { throw normalizeRemoveGuardError(error); });
 }
-async function mkdirPathFallback(resolved) {
+async function mkdirPathFallback(resolved, assertBeforeMutation, rejectSymlinks = false) {
     await mkdirPathComponentsWithGuards({
-        rootReal: resolved.rootReal, targetPath: resolved.resolved,
+        rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
+        rejectSymlinks,
         beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
     });
 }
@@ -984,31 +1073,7 @@ async function statPathFallback(root, relativePath) {
 }
 async function listPathFallback(root, relativePath, withFileTypes) {
     const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
-    try {
-        const names = await fs.readdir(resolved.resolved);
-        const sortedNames = names.toSorted();
-        if (!withFileTypes) {
-            await assertRootIdentityCurrent(root);
-            return sortedNames;
-        }
-        const entries = [];
-        for (const name of sortedNames) {
-            entries.push({
-                name,
-                ...pathStatFromStats(fsSync.lstatSync(path.join(resolved.resolved, name))),
-            });
-        }
-        await assertRootIdentityCurrent(root);
-        return entries;
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "directory not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
+    return await listDirectoryPath(root, resolved.resolved, withFileTypes);
 }
 async function assertMoveMutationAllowed(root, params) {
     // Keep this preflight separate from the pinned resolutions in movePathFallback:
@@ -1028,15 +1093,18 @@ async function movePathFallback(root, params) {
     const source = await resolvePathInRoot(root, params.fromRelative, {
         aliasErrorCode: "path-alias",
         allowFinalSymlink: true,
+        ...mutationSymlinkResolution(params.mutationSymlinks),
     });
     await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
     await resolvePinnedRootPathInRoot(root, {
         relativePath: params.fromRelative,
         policy: PATH_ALIAS_POLICIES.strict,
+        mutationSymlinks: params.mutationSymlinks,
     });
     const target = await resolveGuardedWritePathInRoot(root, {
         relativePath: params.toRelative,
         denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
         allowFinalSymlink: true,
         protectDeniedAncestors: true,
         shouldAssertNoPathAlias: async (resolvedTarget) => {
@@ -1093,6 +1161,9 @@ async function movePathFallback(root, params) {
     await assertAsyncDirectoryGuard(sourceParentGuard);
     await assertAsyncDirectoryGuard(targetParentGuard);
     try {
+        assertFinalSymlinkRejected(source.resolved, params.mutationSymlinks !== undefined);
+        assertFinalSymlinkRejected(target.resolved, params.mutationSymlinks !== undefined);
+        params.assertBeforeMutation?.();
         await fs.rename(source.resolved, target.resolved);
     }
     catch (error) {
@@ -1106,7 +1177,13 @@ async function movePathFallback(root, params) {
         }
         throw error;
     }
-    await assertAsyncDirectoryGuard(targetParentGuard).catch(() => undefined);
+    try {
+        await assertAsyncDirectoryGuard(sourceParentGuard);
+        await assertAsyncDirectoryGuard(targetParentGuard);
+    }
+    catch (error) {
+        throw normalizePinnedPathError(error);
+    }
 }
 async function writeFileFallback(root, params) {
     if (params.overwrite === false) {
@@ -1119,47 +1196,76 @@ async function writeFileFallback(root, params) {
         // Private, writable placeholder: Windows cannot rename over a read-only file.
         mode: 0o600,
         denyMutations: params.denyMutations,
+        assertBeforeMutation: params.assertBeforeMutation,
+        mutationSymlinks: params.mutationSymlinks,
         truncateExisting: false,
     });
     const destinationPath = target.realPath;
     const mode = params.mode ?? (target.stat.mode & 0o777);
-    await target.handle.close().catch(() => { });
-    const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
+    const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath), { bigint: true }).catch(async (error) => {
+        await target.handle.close().catch(() => undefined);
+        throw error;
+    });
     let tempPath = null;
     let unregisterTempPath = null;
     let writtenHandle;
+    let writtenIdentity;
+    let placeholderIdentity;
+    let published = false;
     try {
+        if (target.createdForWrite)
+            placeholderIdentity = fsSync.fstatSync(target.handle.fd, { bigint: true });
         tempPath = buildAtomicWriteTempPath(destinationPath);
-        unregisterTempPath = registerTempPathForExit(tempPath);
-        const written = await writeTempFileForAtomicReplace({
-            tempPath,
-            data: params.data,
-            encoding: params.encoding,
-            mode: 0o600,
+        params.assertBeforeMutation?.();
+        writtenHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
+        writtenIdentity = fsSync.fstatSync(writtenHandle.fd, { bigint: true });
+        unregisterTempPath = registerTempPathForExit(tempPath, { identity: writtenIdentity, singleLinkFile: true });
+        await writeAllToFile(writtenHandle, params.data, {
+            encoding: params.encoding, assertBeforeMutation: params.assertBeforeMutation,
         });
-        writtenHandle = written.handle;
-        unregisterTempPath.setIdentity(written.identity);
+        if (params.durable !== false)
+            await writtenHandle.sync();
         const commitTempPath = tempPath;
+        const commitHandle = writtenHandle;
+        const commitIdentity = writtenIdentity;
         await withAsyncDirectoryGuards([destinationGuard], async () => {
+            await verifyAtomicWriteResult({
+                root, targetPath: commitTempPath, fd: commitHandle.fd,
+                expectedIdentity: commitIdentity, parentGuard: destinationGuard,
+            });
+            if (target.createdForWrite) {
+                await cleanupPinnedFilePath({
+                    pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
+                });
+            }
+            // Windows cannot replace a destination while its old handle remains open.
+            await target.handle.close();
+            assertFinalSymlinkRejected(destinationPath, params.mutationSymlinks !== undefined);
+            params.assertBeforeMutation?.();
             await fs.rename(commitTempPath, destinationPath);
             tempPath = null;
+            published = true;
         });
         unregisterTempPath();
         unregisterTempPath = null;
         // Final mode via the retained handle after publication, as the native writer does.
         try {
-            await written.handle.chmod(mode);
+            await writtenHandle.chmod(mode);
         }
         catch (error) {
-            await removePathIfIdentityUnchanged(destinationPath, written.identity).catch(() => { });
+            await cleanupPinnedFilePath({
+                pathname: destinationPath, handle: writtenHandle, identity: writtenIdentity, parentGuard: destinationGuard,
+            });
             throw error;
         }
+        if (params.durable !== false)
+            await writtenHandle.sync();
         try {
             await verifyAtomicWriteResult({
                 root,
                 targetPath: destinationPath,
-                expectedIdentity: written.identity,
-                fd: written.handle.fd,
+                expectedIdentity: writtenIdentity,
+                fd: writtenHandle.fd,
                 parentGuard: destinationGuard,
             });
         }
@@ -1167,12 +1273,22 @@ async function writeFileFallback(root, params) {
             emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
             throw err;
         }
+        if (params.durable !== false)
+            await syncDirectoryBestEffort(path.dirname(destinationPath));
     }
     finally {
-        await writtenHandle?.close().catch(() => undefined);
-        if (tempPath) {
-            await fs.rm(tempPath, { force: true }).catch(() => { });
+        if (!published && target.createdForWrite) {
+            await cleanupPinnedFilePath({
+                pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
+            });
+        }
+        await target.handle.close().catch(() => undefined);
+        if (tempPath && writtenHandle) {
+            await cleanupPinnedFilePath({
+                pathname: tempPath, handle: writtenHandle, identity: writtenIdentity, parentGuard: destinationGuard,
+            });
         }
+        await writtenHandle?.close().catch(() => undefined);
         unregisterTempPath?.();
     }
 }
@@ -1180,38 +1296,38 @@ async function writeMissingFileFallback(root, params) {
     const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, {
         relativePath: params.relativePath,
         denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
     });
     const targetPath = params.mkdir === false
         ? resolved
-        : await prepareRootWriteTarget(rootReal, resolved);
-    const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath));
+        : await prepareRootWriteTarget(rootReal, resolved, params.assertBeforeMutation);
+    const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     let created = false;
     let createdIdentity;
     let writtenHandle;
     let verifyingPublication = false;
     try {
         const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
+            assertFinalSymlinkRejected(targetPath, params.mutationSymlinks !== undefined);
+            params.assertBeforeMutation?.();
             const handle = await fs.open(targetPath, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600).catch((error) => recordExclusiveCreateFailure(error, targetPath));
+            writtenHandle = handle;
             created = true;
-            try {
-                createdIdentity = fsSync.fstatSync(handle.fd);
-                const writtenStat = fsSync.fstatSync(handle.fd, { bigint: true });
-                if (typeof params.data === "string") {
-                    await handle.writeFile(params.data, params.encoding ?? "utf8");
-                }
-                else {
-                    await handle.writeFile(params.data);
-                }
-                return { handle, writtenStat };
-            }
-            catch (error) {
-                await handle.close().catch(() => undefined);
-                throw error;
-            }
+            const writtenStat = fsSync.fstatSync(handle.fd, { bigint: true });
+            createdIdentity = writtenStat;
+            await writeAllToFile(handle, params.data, {
+                encoding: params.encoding,
+                assertBeforeMutation: () => {
+                    assertFinalSymlinkRejected(targetPath, params.mutationSymlinks !== undefined);
+                    params.assertBeforeMutation?.();
+                },
+            });
+            if (params.durable !== false)
+                await handle.sync();
+            return { handle, writtenStat };
         }, {
-            onPostGuardFailure: async ({ handle }) => {
+            onPostGuardFailure: () => {
                 created = false; // Parent is untrusted now; skip outer path cleanup by name.
-                await handle.close().catch(() => undefined);
             },
         });
         writtenHandle = handle;
@@ -1224,6 +1340,8 @@ async function writeMissingFileFallback(root, params) {
             fd: handle.fd,
             parentGuard,
         });
+        if (params.durable !== false)
+            await syncDirectoryBestEffort(path.dirname(targetPath));
     }
     catch (err) {
         if (verifyingPublication)
@@ -1236,9 +1354,11 @@ async function writeMissingFileFallback(root, params) {
         throw err;
     }
     finally {
-        await writtenHandle?.close().catch(() => undefined);
-        if (created && createdIdentity) {
-            await removePathIfIdentityUnchanged(targetPath, createdIdentity).catch(() => undefined);
+        if (created && writtenHandle) {
+            await cleanupPinnedFilePath({
+                pathname: targetPath, handle: writtenHandle, identity: createdIdentity, parentGuard,
+            });
         }
+        await writtenHandle?.close().catch(() => undefined);
     }
 }