@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/replace-file-temp-owner.js

@@ -1,7 +1,8 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { createAsyncDirectoryGuard } from "./directory-guard.js";
+import { hasErrorCode, removeOwnedPath } from "./file-cleanup.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
@@ -9,6 +10,22 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 const PUBLISHED_READ_FLAGS = resolveReadOpenFlags();
+function describeFailure(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        return "<unprintable failure>";
+    }
+}
+function isErrorValue(error) {
+    try {
+        return error instanceof Error;
+    }
+    catch {
+        return false;
+    }
+}
 export async function removePathIfIdentityUnchanged(targetPath, identity) {
     const parentGuard = await createAsyncDirectoryGuard(path.dirname(targetPath), { bigint: true });
     await withAsyncDirectoryGuards([parentGuard], async () => {
@@ -34,65 +51,24 @@ function missingOwnedFile(pathname, cause) {
         cause,
     });
 }
-function cleanupFailure(originalError, cleanupError) {
-    if (originalError !== undefined) {
-        return new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
+function cleanupFailure(originalFailure, cleanupError) {
+    if (originalFailure) {
+        return new Error(`Atomic file replace failed (${describeFailure(originalFailure.error)}); cleanup also failed (${describeFailure(cleanupError)})`, { cause: originalFailure.error });
     }
-    return cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError));
+    return isErrorValue(cleanupError) ? cleanupError : new Error(describeFailure(cleanupError));
 }
 async function cleanupOwnedPath(params) {
-    if (!params.identity)
-        return true;
     try {
-        const current = params.fsModule === fs
-            ? syncFs.lstatSync(params.pathname, { bigint: true })
-            : await params.fsModule.lstat(params.pathname, { bigint: true });
-        if (current.isSymbolicLink() ||
-            !current.isFile() ||
-            current.nlink !== 1n ||
-            !sameFileIdentityForCleanup(current, params.identity)) {
-            return true;
-        }
-        await params.fsModule.unlink(params.pathname);
+        await removeOwnedPath(params);
         return true;
     }
     catch (cleanupError) {
-        if (cleanupError.code === "ENOENT")
-            return true;
         if (params.throwOnCleanupError) {
-            throw cleanupFailure(params.originalError, cleanupError);
+            throw cleanupFailure(params.originalFailure, cleanupError);
         }
         return false;
     }
 }
-// Borrowed handle: the caller retains it until this best-effort cleanup finishes.
-export async function cleanupPinnedFilePath(params) {
-    if (!params.identity)
-        return;
-    try {
-        const guard = params.parentGuard;
-        if ([guard.stat.dev, guard.stat.ino].some((value) => typeof value === "number" && !Number.isSafeInteger(value)))
-            return;
-        await assertAsyncDirectoryGuard(guard);
-        const parent = syncFs.lstatSync(guard.dir, { bigint: true });
-        if (parent.isSymbolicLink() || !parent.isDirectory() ||
-            !sameFileIdentityForCleanup(parent, guard.stat))
-            return;
-        const opened = syncFs.fstatSync(params.handle.fd, { bigint: true });
-        if (!opened.isFile() || opened.nlink !== 1n ||
-            !sameFileIdentityForCleanup(opened, params.identity))
-            return;
-        await cleanupOwnedPath({
-            fsModule: fs,
-            pathname: params.pathname,
-            identity: params.identity,
-            throwOnCleanupError: false,
-        });
-    }
-    catch {
-        // Unverifiable authority must preserve the path and the original write failure.
-    }
-}
 function cleanupOwnedPathSync(params) {
     if (!params.identity)
         return true;
@@ -108,10 +84,10 @@ function cleanupOwnedPathSync(params) {
         return true;
     }
     catch (cleanupError) {
-        if (cleanupError.code === "ENOENT")
+        if (hasErrorCode(cleanupError, "ENOENT"))
             return true;
         if (params.throwOnCleanupError) {
-            throw cleanupFailure(params.originalError, cleanupError);
+            throw cleanupFailure(params.originalFailure, cleanupError);
         }
         return false;
     }
@@ -202,7 +178,9 @@ export class AsyncAtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            await this.#handle?.close();
+            const previousHandle = this.#handle;
+            this.#handle = undefined;
+            await previousHandle?.close();
             this.#handle = published;
             this.#identity = identity;
             published = undefined;
@@ -216,7 +194,7 @@ export class AsyncAtomicTempOwner {
         this.#unregister();
     }
     async finish(params) {
-        let deferredError;
+        let deferredFailure;
         let cleanupComplete = !this.#exists;
         if (this.#exists) {
             try {
@@ -224,28 +202,32 @@ export class AsyncAtomicTempOwner {
                     fsModule: params.fsModule,
                     pathname: this.pathname,
                     identity: this.#identity,
-                    originalError: params.originalError,
+                    originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
             }
             catch (error) {
-                deferredError = error;
+                deferredFailure = { error };
             }
         }
         if (cleanupComplete)
             this.#unregister();
+        const handle = this.#handle;
+        this.#handle = undefined;
         try {
-            await this.#handle?.close();
+            await handle?.close();
         }
         catch (closeError) {
-            deferredError = deferredError
-                ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
-                : params.originalError !== undefined
-                    ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
-                    : closeError;
+            deferredFailure = {
+                error: deferredFailure
+                    ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
+                    : params.originalFailure
+                        ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                        : closeError,
+            };
         }
-        if (deferredError)
-            throw deferredError;
+        if (deferredFailure)
+            throw deferredFailure.error;
     }
 }
 export class SyncAtomicTempOwner {
@@ -353,7 +335,7 @@ export class SyncAtomicTempOwner {
         this.#unregister();
     }
     finish(params) {
-        let deferredError;
+        let deferredFailure;
         let cleanupComplete = !this.#exists;
         if (this.#exists) {
             try {
@@ -361,12 +343,12 @@ export class SyncAtomicTempOwner {
                     fsModule: params.fsModule,
                     pathname: this.pathname,
                     identity: this.#identity,
-                    originalError: params.originalError,
+                    originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
             }
             catch (error) {
-                deferredError = error;
+                deferredFailure = { error };
             }
         }
         if (cleanupComplete)
@@ -378,14 +360,16 @@ export class SyncAtomicTempOwner {
                 params.fsModule.closeSync(fd);
             }
             catch (closeError) {
-                deferredError = deferredError
-                    ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
-                    : params.originalError !== undefined
-                        ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
-                        : closeError;
+                deferredFailure = {
+                    error: deferredFailure
+                        ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
+                        : params.originalFailure
+                            ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                            : closeError,
+                };
             }
         }
-        if (deferredError)
-            throw deferredError;
+        if (deferredFailure)
+            throw deferredFailure.error;
     }
 }

package/dist/replace-file.js

@@ -171,7 +171,7 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
@@ -229,13 +229,13 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         await tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }
@@ -271,7 +271,7 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new SyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
         fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
         applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
@@ -327,13 +327,13 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }

package/dist/retained-directory-replacement.d.ts

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+import type { NativeBinding, NativeOwnedTreeRemovalResult } from "./native-binding.js";
+type RenameBinding = NativeBinding & Required<Pick<NativeBinding, "renameNoReplaceWithIdentity">>;
+export type RetainedReplacementParent = Readonly<{
+    path: string;
+    realPath: string;
+    identity: Pick<BigIntStats, "dev" | "ino">;
+}>;
+export declare class RetainedDirectoryReplacement {
+    #private;
+    private constructor();
+    static requireBinding(): RenameBinding;
+    static retain(params: {
+        targetParent: RetainedReplacementParent;
+        stagedParent: RetainedReplacementParent;
+        originalTarget?: Readonly<{
+            path: string;
+            identity: Pick<BigIntStats, "dev" | "ino">;
+        }>;
+    }, binding?: RenameBinding): RetainedDirectoryReplacement;
+    renameNoReplace(sourceParent: "staged" | "target", sourceBasename: string, targetBasename: string, expectedSource: Pick<BigIntStats, "dev" | "ino">): void;
+    removeOriginal(backupBasename: string): Promise<NativeOwnedTreeRemovalResult["outcome"]>;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=retained-directory-replacement.d.ts.map

package/dist/retained-directory-replacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retained-directory-replacement.d.ts","sourceRoot":"","sources":["../src/retained-directory-replacement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,OAAO,KAAK,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAGvF,KAAK,aAAa,GAAG,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,EAC9D,6BAA6B,CAAC,CAAC,CAAC;AAIlC,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;CAC5C,CAAC,CAAC;AAsHH,qBAAa,4BAA4B;;IAQvC,OAAO,eAUN;IAED,MAAM,CAAC,cAAc,IAAI,aAAa,CAQrC;IAED,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE;QACpB,YAAY,EAAE,yBAAyB,CAAC;QACxC,YAAY,EAAE,yBAAyB,CAAC;QACxC,cAAc,CAAC,EAAE,QAAQ,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;SAC5C,CAAC,CAAC;KACJ,EAAE,OAAO,gBAAgD,GAAG,4BAA4B,CAiDxF;IAED,eAAe,CACb,YAAY,EAAE,QAAQ,GAAG,QAAQ,EACjC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAC/C,IAAI,CAYN;IAEK,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC,SAAS,CAAC,CAAC,CA2B7F;IAED,KAAK,IAAI,IAAI,CAQZ;CACF"}

package/dist/retained-directory-replacement.js

@@ -0,0 +1,193 @@
+import fsSync from "node:fs";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+function helperUnavailable(message, cause) {
+    return new FsSafeError("helper-unavailable", message, {
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function primaryWithCloseFailure(error, closeError, message) {
+    const cause = new AggregateError([error, closeError], message);
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, {
+            cause,
+            ...(error.details ? { details: error.details } : {}),
+        });
+    }
+    const wrapped = new Error(message, { cause });
+    copyOperationalCode(wrapped, error);
+    return wrapped;
+}
+function supportsRename(binding) {
+    return typeof binding?.renameNoReplaceWithIdentity === "function";
+}
+function supportsCleanup(binding) {
+    return typeof binding.ownedTreeRemovalAvailable === "function" &&
+        typeof binding.removeOwnedTree === "function";
+}
+function closeDescriptors(descriptors) {
+    const errors = [];
+    const closed = new Set();
+    for (const fd of descriptors) {
+        if (fd === undefined || closed.has(fd))
+            continue;
+        closed.add(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "retained directory replacement descriptors failed to close");
+    }
+}
+const retainedDirectoryOpenFlags = fsSync.constants.O_RDONLY |
+    fsSync.constants.O_DIRECTORY |
+    fsSync.constants.O_NOFOLLOW |
+    fsSync.constants.O_NONBLOCK;
+function openRetainedDirectory(label, expected) {
+    let fd;
+    try {
+        fd = fsSync.openSync(expected.path, retainedDirectoryOpenFlags);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            const purpose = label === "original target"
+                ? "original target for bounded cleanup"
+                : label;
+            throw helperUnavailable(`atomic directory replacement cannot retain the ${purpose}`, error);
+        }
+        throw error;
+    }
+    try {
+        const descriptor = fsSync.fstatSync(fd, { bigint: true });
+        if (!descriptor.isDirectory()) {
+            throw new FsSafeError("not-file", `directory replacement ${label} must be a directory`);
+        }
+        if (descriptor.dev !== expected.identity.dev || descriptor.ino !== expected.identity.ino) {
+            throw new FsSafeError("path-mismatch", `directory replacement ${label} changed during admission`);
+        }
+        assertDirectoryIdentitySync(expected.path, {
+            dev: expected.identity.dev,
+            ino: expected.identity.ino,
+            ...(expected.realPath === undefined ? {} : { realPath: expected.realPath }),
+        });
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (closeError) {
+            throw primaryWithCloseFailure(error, closeError, `directory replacement ${label} admission and close failed`);
+        }
+        throw error;
+    }
+    return fd;
+}
+export class RetainedDirectoryReplacement {
+    #binding;
+    #originalDirectoryFd;
+    #stagedParentFd;
+    #targetParentFd;
+    #cleanupUsed = false;
+    #closed = false;
+    constructor(binding, targetParentFd, stagedParentFd, originalDirectoryFd) {
+        this.#binding = binding;
+        this.#targetParentFd = targetParentFd;
+        this.#stagedParentFd = stagedParentFd;
+        this.#originalDirectoryFd = originalDirectoryFd;
+    }
+    static requireBinding() {
+        const binding = getNativeBinding();
+        if (!supportsRename(binding)) {
+            throw helperUnavailable("atomic directory replacement requires native identity-fenced no-replace rename support");
+        }
+        return binding;
+    }
+    static retain(params, binding = RetainedDirectoryReplacement.requireBinding()) {
+        let targetParentFd;
+        let stagedParentFd;
+        let originalDirectoryFd;
+        try {
+            targetParentFd = openRetainedDirectory("target parent", params.targetParent);
+            stagedParentFd = params.stagedParent.path === params.targetParent.path
+                ? targetParentFd
+                : openRetainedDirectory("staged parent", params.stagedParent);
+            if (params.originalTarget) {
+                if (!supportsCleanup(binding)) {
+                    throw helperUnavailable("replacing an existing directory requires native bounded owned-tree cleanup");
+                }
+                let available = false;
+                try {
+                    available = binding.ownedTreeRemovalAvailable(targetParentFd) === true;
+                }
+                catch (error) {
+                    throw helperUnavailable("native owned-tree cleanup capability probe failed", error);
+                }
+                if (!available) {
+                    throw helperUnavailable("native owned-tree cleanup is unavailable for the target parent");
+                }
+                originalDirectoryFd = openRetainedDirectory("original target", {
+                    path: params.originalTarget.path,
+                    identity: params.originalTarget.identity,
+                });
+            }
+            return new RetainedDirectoryReplacement(binding, targetParentFd, stagedParentFd, originalDirectoryFd);
+        }
+        catch (error) {
+            try {
+                closeDescriptors([originalDirectoryFd, stagedParentFd, targetParentFd]);
+            }
+            catch (closeError) {
+                throw primaryWithCloseFailure(error, closeError, "retained directory replacement admission and descriptor close failed");
+            }
+            throw error;
+        }
+    }
+    renameNoReplace(sourceParent, sourceBasename, targetBasename, expectedSource) {
+        if (this.#closed) {
+            throw new FsSafeError("path-mismatch", "retained directory rename authority is unavailable");
+        }
+        this.#binding.renameNoReplaceWithIdentity(sourceParent === "staged" ? this.#stagedParentFd : this.#targetParentFd, sourceBasename, this.#targetParentFd, targetBasename, expectedSource.dev, expectedSource.ino);
+    }
+    async removeOriginal(backupBasename) {
+        if (this.#closed || this.#cleanupUsed || this.#originalDirectoryFd === undefined ||
+            !supportsCleanup(this.#binding)) {
+            throw new FsSafeError("path-mismatch", "retained owned-tree cleanup authority is unavailable");
+        }
+        this.#cleanupUsed = true;
+        const result = await this.#binding.removeOwnedTree(this.#targetParentFd, backupBasename, this.#originalDirectoryFd);
+        if (result.errorCode) {
+            if (result.errorCode === "path-mismatch") {
+                throw new FsSafeError("path-mismatch", result.errorMessage ?? "native owned-tree cleanup lost retained identity");
+            }
+            throw Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), { code: result.errorCode });
+        }
+        if (result.outcome !== "removed" && result.outcome !== "preserved") {
+            throw helperUnavailable("native owned-tree cleanup returned an invalid result");
+        }
+        return result.outcome;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        closeDescriptors([
+            this.#originalDirectoryFd,
+            this.#stagedParentFd,
+            this.#targetParentFd,
+        ]);
+    }
+}

package/dist/root-boundary.d.ts

@@ -1,3 +1,4 @@
+export declare function sameNormalizedPathSpelling(left: string, right: string): boolean;
 export type RootBoundaryIdentity = Readonly<{
     dev: number | bigint;
     ino: number | bigint;

package/dist/root-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-boundary.d.ts","sourceRoot":"","sources":["../src/root-boundary.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAwHH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,CACrB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,KAC7C,IAAI,CAAC;CACX,GAAG,gBAAgB,GAAG,SAAS,CAiE/B"}
+{"version":3,"file":"root-boundary.d.ts","sourceRoot":"","sources":["../src/root-boundary.ts"],"names":[],"mappings":"AAKA,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG/E;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAwHH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,CACrB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,KAC7C,IAAI,CAAC;CACX,GAAG,gBAAgB,GAAG,SAAS,CAiE/B"}

package/dist/root-boundary.js

@@ -2,6 +2,10 @@ import path from "node:path";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { isPathRelativeEscape } from "./path.js";
 import { realpathSync } from "./realpath.js";
+export function sameNormalizedPathSpelling(left, right) {
+    // Preserve case on Windows, where individual directories can be case-sensitive.
+    return path.resolve(left) === path.resolve(right);
+}
 function windowsComparablePath(value, normalize) {
     const original = normalize
         ? path.win32.normalize(value.replaceAll("/", "\\"))

package/dist/root-context.d.ts

@@ -41,12 +41,4 @@ export declare function resolvePathInRoot(root: RootContext, relativePath: strin
     rootWithSep: string;
     resolved: string;
 }>;
-export declare function resolvePathWithinRoot(params: {
-    rootDir: string;
-    relativePath: string;
-}): Promise<{
-    rootReal: string;
-    rootWithSep: string;
-    resolved: string;
-}>;
 //# sourceMappingURL=root-context.d.ts.map

package/dist/root-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAuB9B,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAOtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiC9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBhF;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,IAAI,CAmBN;AAED,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAYhD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuEtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAuB9B,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAOtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiC9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBhF;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,IAAI,CAmBN;AAED,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAYhD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuEtE"}

package/dist/root-context.js

@@ -234,6 +234,3 @@ export async function resolvePathInRoot(root, relativePath, options) {
     }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }
-export async function resolvePathWithinRoot(params) {
-    return await resolvePathInRoot(await resolveRootContext(params.rootDir), params.relativePath);
-}

package/dist/root-create-input.d.ts

@@ -1,10 +1,17 @@
 import type { PinnedWriteInput } from "./pinned-write.js";
 import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
-export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+declare const exclusiveSidecarCreate: unique symbol;
+export declare const sidecarExclusiveCreate: Readonly<{
+    [exclusiveSidecarCreate]: true;
+}>;
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
     relativePath: string;
     data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
+    [exclusiveSidecarCreate]?: true;
 };
 export declare function rethrowCreateInputError(error: unknown): never;
 export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
 export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+export {};
 //# sourceMappingURL=root-create-input.d.ts.map

package/dist/root-create-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-create-input.d.ts","sourceRoot":"","sources":["../src/root-create-input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtG,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,uBAAuB,GAAG;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;CACnD,CAAC;AAQF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,EACpD,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,uBAAuB,CAe7C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAwCxE"}
+{"version":3,"file":"root-create-input.d.ts","sourceRoot":"","sources":["../src/root-create-input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAItG,QAAA,MAAM,sBAAsB,eAAmC,CAAC;AAChE,eAAO,MAAM,sBAAsB;;EAA6D,CAAC;AAEjG,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,uBAAuB,GAAG;IAC7F,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,CAAC,sBAAsB,CAAC,CAAC,EAAE,IAAI,CAAC;CACjC,CAAC;AAQF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,EACpD,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,uBAAuB,CAkB7C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CA8CxE"}

package/dist/root-create-input.js

@@ -1,6 +1,10 @@
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { MutationAuthorityError } from "./mutation-authority.js";
+// Lock records need exclusive creation, not private-before-visible publication.
+// Keep this composition hook off the public Root options and package exports.
+const exclusiveSidecarCreate = Symbol("exclusiveSidecarCreate");
+export const sidecarExclusiveCreate = Object.freeze({ [exclusiveSidecarCreate]: true });
 class CreateInputError extends FsSafeError {
     rejection;
     constructor(rejection) {
@@ -16,24 +20,33 @@ export function rethrowCreateInputError(error) {
 export function createInputOptions(data, options, defaultMaxBytes) {
     if (typeof data === "string" || Buffer.isBuffer(data))
         return options;
-    options.signal?.throwIfAborted();
+    const { signal } = options;
+    signal?.throwIfAborted();
     if (options.encoding !== undefined || options.renameIdentity !== undefined) {
         throw new TypeError("streamed create does not accept encoding or renameIdentity");
     }
     const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    const { assertBeforeMutation } = options;
     return {
         ...options,
         maxBytes,
+        signal,
         assertBeforeMutation: () => {
-            options.signal?.throwIfAborted();
-            return options.assertBeforeMutation?.();
+            signal?.throwIfAborted();
+            return assertBeforeMutation == null ? undefined : Reflect.apply(assertBeforeMutation, options, []);
         },
     };
 }
 export function rootWriteInput(params) {
+    if (params.atomic !== undefined && typeof params.atomic !== "boolean") {
+        throw new TypeError("atomic must be a boolean");
+    }
     const data = params.data;
     if (typeof data === "string" || Buffer.isBuffer(data)) {
-        return { kind: "buffer", data, encoding: params.encoding };
+        return {
+            kind: "buffer", data, encoding: params.encoding,
+            stageBeforePublish: params[exclusiveSidecarCreate] ? false : params.atomic === true ? true : undefined,
+        };
     }
     return {
         kind: "stream",

package/dist/root-directory-creation.d.ts

@@ -1,13 +1,13 @@
 import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
-import type { RootContext } from "./root-context.js";
+import { type RootContext } from "./root-context.js";
 /**
  * Complete the common Root.mkdir case with one exact existing parent. This is
  * optional evidence: every uncertain probe returns to the ordered root walk.
  */
 export declare function tryMkdirAtExactParent(root: RootContext, targetPath: string, mutationAdmission: PinnedWriteMutationAdmission): Promise<boolean>;
-export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission): Promise<string>;
+export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<string>;
 export declare function mkdirPathFallback(root: RootContext, resolved: {
     rootReal: string;
     resolved: string;
-}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission): Promise<void>;
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;
 //# sourceMappingURL=root-directory-creation.d.ts.map