@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/root-impl.js

@@ -56,7 +56,7 @@ 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 { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-permissions.js";
+import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -68,11 +68,12 @@ import { openedPathResolutionError, recordExclusiveCreateFailure, recordOpenedFi
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy } from "./pinned-write.js";
 import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy } from "./pinned-mutation-admission.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 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";
@@ -85,7 +86,7 @@ import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.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 { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.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,37 @@ 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),
+            atomic: undefined,
+            private: undefined,
+            strictFileSync: undefined,
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -319,11 +316,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 +340,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],
@@ -369,18 +367,19 @@ export class RootHandle {
     }
     async stat(relativePath) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await statPathFallback(this.context, relativePath);
     }
     async list(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await listPathFallback(this.context, relativePath, options.withFileTypes === true);
     }
     async move(fromRelative, toRelative, options = {}) {
         assertValidRootRelativePath(fromRelative);
         assertValidRootDestinationPath(toRelative);
-        validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
+        validatePinnedRelativePath(fromRelative);
+        validatePinnedRelativePath(toRelative);
         const mutationOptions = this.mutationOptions(options);
         const { assertBeforeMutation } = mutationOptions;
         const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
@@ -409,10 +408,10 @@ 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 });
+                validatePinnedRelativePath(relative);
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },
@@ -468,15 +467,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 +492,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, {
@@ -517,7 +507,6 @@ async function openWritableFileInRoot(root, params) {
         relativePath: params.relativePath, guardedTarget, mkdir: params.mkdir,
         assertBeforeMutation: params.assertBeforeMutation,
     }) : undefined;
-    const mutationAdmission = prepared?.mutationAdmission;
     const preparedParent = prepared?.preparedParent;
     let ioPath = prepared?.targetPath ?? (params.mkdir === false ? resolved :
         await prepareRootWriteTarget(root, resolved, params.assertBeforeMutation));
@@ -566,6 +555,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?.();
@@ -766,7 +766,7 @@ async function appendFileInRoot(root, params) {
     }
 }
 async function removePathInRoot(root, params) {
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    validatePinnedRelativePath(params.relativePath);
     const removalReceipts = params.recursive ? undefined : new RemovalPathReceipts();
     const resolved = await resolvePinnedPathInRoot(root, {
         relativePath: params.relativePath,
@@ -786,20 +786,15 @@ async function removePathInRoot(root, params) {
 }
 async function mkdirPathInRoot(root, params) {
     const privateMode = resolveCreationPermissions(params, true).private;
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    validatePinnedRelativePath(params.relativePath);
     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,
@@ -870,7 +865,7 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             overwrite: params.overwrite,
             rejectFinalSymlink: params.mutationSymlinks !== undefined,
             input,
-            maxBytes: params.maxBytes,
+            maxBytes: input.kind === "buffer" ? undefined : params.maxBytes,
             rootIdentity: root.rootIdentity,
             mutationAdmission: pinned.mutationAdmission,
             assertBeforeMutation: params.assertBeforeMutation,
@@ -900,9 +895,7 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             throw error;
         }
         if (params.overwrite === false && isAlreadyExistsError(error)) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(error));
         }
         throw normalizePinnedWriteError(error);
     }
@@ -995,20 +988,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,
     });
@@ -1035,7 +1017,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 };
 }
@@ -1192,9 +1174,7 @@ async function movePathFallback(root, params) {
             throw fileNotFoundError(error instanceof Error ? error : undefined);
         }
         if (hasNodeErrorCode(error, "EEXIST")) {
-            throw new FsSafeError("already-exists", "destination exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
         }
         throw error;
     }
@@ -1212,7 +1192,11 @@ async function writeFileFallback(root, params) {
     const policy = snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
     if (policy)
         params = { ...params, ...policy };
-    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, params);
+    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
+    });
     await withRootFallbackCompatibilityLock({
         rootPath: rootReal, rootIdentity: root.rootIdentity, targetPath: resolved, assertBeforeMutation: params.assertBeforeMutation,
     }, async ({ targetPath, ...binding }) => await writeFileFallbackUnlocked(root, { ...params, ...binding }, targetPath));
@@ -1222,48 +1206,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,
@@ -1278,24 +1273,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;
@@ -1308,12 +1321,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,
@@ -1323,6 +1332,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
@@ -1399,9 +1425,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
         if (verifyingPublication)
             throw err;
         if (hasNodeErrorCode(err, "EEXIST")) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: err instanceof Error ? err : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(err));
         }
         throw err;
     }

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

@@ -13,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

@@ -9,7 +9,7 @@ import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
@@ -44,17 +44,13 @@ function normalizeMoveError(error) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
     if (nativePrimitiveUnavailable(error)) {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", errorCauseOptions(error));
     }
     return error;
 }
 function normalizeRenameNoReplaceError(error) {
     if (error?.code === "EINVAL") {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", errorCauseOptions(error));
     }
     return normalizeMoveError(error);
 }
@@ -157,9 +153,7 @@ export async function movePathNoReplaceNative(root, params, paths) {
         }
         catch (error) {
             if (isAlreadyExistsError(error) || error?.code === "ENOTEMPTY") {
-                throw new FsSafeError("already-exists", "destination exists", {
-                    cause: error instanceof Error ? error : undefined,
-                });
+                throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
             }
             throw normalizeRenameNoReplaceError(error);
         }

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

@@ -5,4 +5,3 @@ export declare function assertMoveMutationAllowed(root: RootContext, params: {
     toRelative: string;
     denyMutations?: DenyMutationPolicy;
 }): Promise<void>;
-//# sourceMappingURL=root-move-preflight.d.ts.map

package/dist/root-observed-path.d.ts

@@ -6,4 +6,3 @@ export type PinnedObservedPath = {
     receipt?: RootPathObservationReceipt;
 };
 export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath | undefined>;
-//# sourceMappingURL=root-observed-path.d.ts.map

package/dist/root-observed-path.js

@@ -7,7 +7,7 @@ import { admitPathInsideRoot } from "./root-boundary.js";
 import { assertRootPathObservationReceiptCurrent } from "./root-directory-list.js";
 import { RootPathObservationError, resolveRootPathWithObservation, } from "./root-path.js";
 import { createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, } from "./root-context.js";
-import { fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 export async function resolvePinnedObservedPathInRoot(root, relativePath, kind) {
     const rootGuard = await createRootObservationGuard(root);
@@ -50,9 +50,7 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
                 if (kind === "stat") {
                     throw fileNotFoundError(error.error instanceof Error ? error.error : undefined);
                 }
-                throw new FsSafeError("not-found", "directory not found", {
-                    cause: error.error instanceof Error ? error.error : undefined,
-                });
+                throw new FsSafeError("not-found", "directory not found", errorCauseOptions(error.error));
             }
             throw error.error;
         }

package/dist/root-options.d.ts

@@ -1,5 +1,5 @@
 import type { DenyMutationPolicy } from "./deny-mutations.js";
-import type { RenameIdentityPolicy } from "./pinned-write.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 import type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
 import type { CopyCloneMode } from "./copy-policy.js";
 import type { RootCopyPublicationReceipt } from "./copy-publication.js";
@@ -82,4 +82,3 @@ export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "deny
 export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
 export declare function readDefaults(defaults: RootDefaults): RootReadParams;
 export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;
-//# sourceMappingURL=root-options.d.ts.map

package/dist/root-path-errors.d.ts

@@ -10,4 +10,3 @@ export declare function symlinkEscapeError(params: {
     rootCanonicalPath: string;
     symlinkPath: string;
 }): Error;
-//# sourceMappingURL=root-path-errors.d.ts.map