@openclaw/fs-safe 0.15.0 → 0.16.0

package/dist/private-producer-handoff.js

@@ -2,13 +2,14 @@ import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit, } from "./temp-cleanup.js";
 function pathMismatch(message) {
     return new FsSafeError("path-mismatch", message);
 }
-function assertInitialSource(stat) {
+export function assertInitialSource(stat) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("path-alias", "isolated producer output must not be a symlink");
     }
@@ -19,7 +20,7 @@ function assertInitialSource(stat) {
         throw new FsSafeError("hardlink", "isolated producer output must have exactly one link");
     }
 }
-function inspectLinkedFile(inspect, expected, links, label) {
+export function inspectLinkedFile(inspect, expected, links, label) {
     return inspectFileIdentitySync(() => {
         const stat = inspect();
         if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== links) {
@@ -28,11 +29,11 @@ function inspectLinkedFile(inspect, expected, links, label) {
         return stat;
     }, expected);
 }
-function assertParents(params) {
+export function assertParents(params) {
     params.assertTargetParent();
     params.assertSourceParent();
 }
-function normalizeLinkError(error) {
+export function normalizeLinkError(error) {
     const code = error?.code;
     if (code === "EEXIST") {
         return new FsSafeError("already-exists", "isolated producer sibling already exists", {
@@ -101,7 +102,7 @@ async function throwAfterClosing(primary, handles) {
     throw combinedFailure(primary, settlement);
 }
 function inspectSourceDescriptor(handle, identity, links = 1n) {
-    inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
+    return inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
 }
 function historicalOpenFlags(readWrite) {
     const access = readWrite ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
@@ -164,109 +165,171 @@ async function openProducerSource(params, identity, links = 1n) {
     }
     return fallback;
 }
-function assertLinkedHandoff(params, handle, identity) {
+function inspectHandoff(params, handle, identity, state, links) {
     assertParents(params);
-    inspectSourceDescriptor(handle, identity, 2n);
-    inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 2n, "isolated producer path");
-    inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 2n, "isolated producer sibling");
+    const opened = inspectSourceDescriptor(handle, identity, links);
+    if (state.cleanup !== "removed") {
+        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, links, "isolated producer path");
+    }
+    const named = state.publication === "published" ? inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, links, "isolated producer sibling") : undefined;
+    return { opened, named };
 }
-export async function handoffPrivateProducerFile(params) {
-    assertParents(params);
-    const identity = inspectFileIdentitySync(() => {
+async function handoffFile(params) {
+    const created = "source" in params ? params : undefined;
+    const identity = created?.identity ?? inspectFileIdentitySync(() => {
+        assertParents(params);
         const stat = fsSync.lstatSync(params.sourcePath, { bigint: true });
         assertInitialSource(stat);
         return stat;
     });
-    let handle;
-    let siblingHandle;
+    let handle = created?.source;
+    const owners = new Set(handle ? [handle] : []);
+    const failures = [];
     let unregister;
-    const state = { siblingOwned: false };
+    const state = {
+        siblingOwned: false, publication: "not-published", cleanup: "preserved", closeFailed: false,
+    };
+    async function close(owned) {
+        // Final creation consumes its pin before close can release and recycle it.
+        // Legacy temporary handoff retains its historical FileHandle close retry.
+        if (created)
+            owners.delete(owned);
+        try {
+            await owned.close();
+            owners.delete(owned);
+        }
+        catch (error) {
+            state.closeFailed = true;
+            throw error;
+        }
+    }
     try {
-        handle = await openProducerSource(params, identity);
-        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 1n, "isolated producer path");
-        assertParents(params);
-        unregister = registerTempPathForExit(params.targetPath, {
-            cleanupSync: () => removeSiblingIfOwned({
-                assertTargetParent: params.assertTargetParent,
-                identity,
-                state,
-                targetPath: params.targetPath,
-            }),
-        });
-        assertParents(params);
+        assertInitialSource(identity);
+        if (!handle) {
+            handle = await openProducerSource({ ...params, readWrite: "readWrite" in params && params.readWrite }, identity);
+            owners.add(handle);
+        }
+        inspectHandoff(params, handle, identity, state, 1n);
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, params.sourcePath, 1);
+        if (!created) {
+            unregister = registerTempPathForExit(params.targetPath, {
+                cleanupSync: () => removeSiblingIfOwned({
+                    assertTargetParent: params.assertTargetParent, identity, state, targetPath: params.targetPath,
+                }),
+            });
+        }
+        assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
+        inspectHandoff(params, handle, identity, state, 1n);
+        state.publication = "indeterminate";
         try {
             fsSync.linkSync(params.sourcePath, params.targetPath);
         }
         catch (error) {
-            throw normalizeLinkError(error);
+            const normalized = normalizeLinkError(error);
+            if (normalized instanceof FsSafeError &&
+                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
+                state.publication = "not-published";
+            }
+            throw normalized;
         }
-        state.siblingOwned = true;
-        assertLinkedHandoff(params, handle, identity);
+        state.publication = "published";
+        state.siblingOwned = !created;
+        try {
+            assertSynchronousCallbackResult(created?.onPublished?.(), "onPublished");
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        inspectHandoff(params, handle, identity, state, 2n);
         if (process.platform === "win32") {
             // Legacy Windows unlink retains a delete-pending name until handles
             // opened through that name close. Transfer the pin before retiring it.
-            siblingHandle = await openProducerSource({ ...params, sourcePath: params.targetPath }, identity, 2n);
-            assertLinkedHandoff(params, siblingHandle, identity);
+            const sibling = created
+                ? await fs.open(params.targetPath, historicalOpenFlags(true))
+                : await openProducerSource({ ...params, sourcePath: params.targetPath,
+                    readWrite: "readWrite" in params && params.readWrite }, identity, 2n);
+            owners.add(sibling);
+            inspectHandoff(params, sibling, identity, state, 2n);
+            if (created?.verifyDescriptor)
+                await created.verifyDescriptor(sibling.fd, params.targetPath, 2);
+            inspectHandoff(params, sibling, identity, state, 2n);
             inspectSourceDescriptor(handle, identity, 2n);
-            await handle.close();
-            handle = siblingHandle;
-            siblingHandle = undefined;
+            await close(handle);
+            handle = sibling;
             // The old handle's close yielded; both names must still be ours.
-            assertLinkedHandoff(params, handle, identity);
+            inspectHandoff(params, handle, identity, state, 2n);
         }
-        assertParents(params);
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, process.platform === "win32" ? params.targetPath : params.sourcePath, 2);
+        assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
+        inspectHandoff(params, handle, identity, state, 2n);
+        state.cleanup = "failed";
         fsSync.unlinkSync(params.sourcePath);
-        assertParents(params);
-        const opened = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
-        const sibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+        state.cleanup = "removed";
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, params.targetPath, 1);
+        const { opened, named } = inspectHandoff(params, handle, identity, state, 1n);
         const originalMode = identity.mode & 511n;
-        if (process.platform === "win32" && (originalMode & 128n) === 0n &&
-            ((opened.mode & 511n) !== originalMode || (sibling.mode & 511n) !== originalMode)) {
+        if (!created && process.platform === "win32" && (originalMode & 128n) === 0n &&
+            ((opened.mode & 511n) !== originalMode || (named.mode & 511n) !== originalMode)) {
             // Legacy unlink clears the shared read-only attribute. Repair only the
             // admitted sibling inode, without reopening or chmodding its pathname.
             assertParents(params);
             fsSync.fchmodSync(handle.fd, Number(originalMode));
-            assertParents(params);
-            const restored = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
-            const restoredSibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
-            if ((restored.mode & 511n) !== originalMode || (restoredSibling.mode & 511n) !== originalMode) {
+            const restored = inspectHandoff(params, handle, identity, state, 1n);
+            if ((restored.opened.mode & 511n) !== originalMode || (restored.named.mode & 511n) !== originalMode) {
                 throw pathMismatch("isolated producer read-only mode could not be restored");
             }
         }
-        const registered = unregister;
-        const release = (() => {
-            state.siblingOwned = false;
-            registered();
-        });
-        release.setIdentity = registered.setIdentity;
-        return { handle, identity, unregister: release };
+        if (!created) {
+            const registered = unregister;
+            const release = (() => {
+                state.siblingOwned = false;
+                registered();
+            });
+            release.setIdentity = registered.setIdentity;
+            return { handle, identity, unregister: release };
+        }
     }
     catch (error) {
-        const settlement = [];
-        if (unregister) {
-            try {
-                removeSiblingIfOwned({
-                    assertTargetParent: params.assertTargetParent,
-                    identity,
-                    state,
-                    targetPath: params.targetPath,
-                });
-                unregister();
-            }
-            catch (cleanupError) {
-                settlement.push(cleanupError);
-            }
+        failures.push(error);
+    }
+    if (failures.length === 0)
+        return handle;
+    if (unregister) {
+        try {
+            removeSiblingIfOwned({ assertTargetParent: params.assertTargetParent, identity, state, targetPath: params.targetPath });
+            unregister();
         }
-        for (const retained of new Set([siblingHandle, handle])) {
-            if (!retained)
-                continue;
-            try {
-                await retained.close();
-            }
-            catch (closeError) {
-                settlement.push(closeError);
-            }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    for (const owned of [...owners].reverse()) {
+        try {
+            await close(owned);
+        }
+        catch (error) {
+            failures.push(error);
         }
-        throw combinedFailure(error, settlement);
     }
+    const primary = failures[0];
+    const cause = combinedFailure(primary, failures.slice(1));
+    if (!created)
+        throw cause;
+    throw new FsSafeError(state.closeFailed || failures.length > 1 ? "helper-failed" : primary instanceof FsSafeError ? primary.code : "helper-failed", "created file publication failed", {
+        cause,
+        details: {
+            publication: { status: state.publication }, cleanup: state.cleanup,
+            resources: state.closeFailed ? "close-failed" : "closed",
+            path: params.targetPath, dev: identity.dev, ino: identity.ino,
+        },
+    });
+}
+export function handoffPrivateProducerFile(params) {
+    return handoffFile(params);
+}
+export function handoffCreatedFile(params) {
+    return handoffFile(params);
 }

package/dist/publish-copy-stage.d.ts

@@ -1,5 +1,5 @@
 import { type BigIntStats } from "node:fs";
-import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { PublishedWriteIdentity } from "./pinned-write.js";
 export declare function publishCopyStage(params: {
     temporaryPath: string;
@@ -8,6 +8,7 @@ export declare function publishCopyStage(params: {
     identity: BigIntStats;
     parentGuard: AnyAsyncDirectoryGuard;
     assertBeforeMutation?: () => void;
+    onPublicationAttempt?: () => void;
     onPublished?: (identity: PublishedWriteIdentity) => void;
 }): void;
 //# sourceMappingURL=publish-copy-stage.d.ts.map

package/dist/publish-copy-stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish-copy-stage.d.ts","sourceRoot":"","sources":["../src/publish-copy-stage.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIhE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC1D,GAAG,IAAI,CAqCP"}
+{"version":3,"file":"publish-copy-stage.d.ts","sourceRoot":"","sources":["../src/publish-copy-stage.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAA4B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG7F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIhE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC1D,GAAG,IAAI,CA4CP"}

package/dist/publish-copy-stage.js

@@ -1,19 +1,28 @@
 import fs, {} from "node:fs";
 import path from "node:path";
+import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 // Node has no portable no-replace rename. Link only our completed private stage,
 // then unlink it in the same JS turn so local readers never observe two names.
 export function publishCopyStage(params) {
     const { identity, temporaryPath, targetPath } = params;
-    const staged = fs.lstatSync(temporaryPath, { bigint: true });
-    const opened = fs.fstatSync(params.fd, { bigint: true });
-    if (!staged.isFile() || staged.isSymbolicLink() || staged.nlink !== 1n ||
-        !sameFileIdentityForCleanup(staged, identity) ||
-        !sameFileIdentityForCleanup(opened, identity)) {
-        throw new FsSafeError("path-mismatch", "exclusive copy stage changed before publication");
-    }
+    const assertCurrent = () => {
+        assertSyncDirectoryGuard(params.parentGuard);
+        const staged = fs.lstatSync(temporaryPath, { bigint: true });
+        const opened = fs.fstatSync(params.fd, { bigint: true });
+        if (!staged.isFile() || staged.isSymbolicLink() || staged.nlink !== 1n ||
+            !sameFileIdentityForCleanup(staged, identity) ||
+            !sameFileIdentityForCleanup(opened, identity)) {
+            throw new FsSafeError("path-mismatch", "exclusive copy stage changed before publication");
+        }
+    };
+    assertCurrent();
     params.assertBeforeMutation?.();
+    // Caller authority checks can synchronously replace a parent or staged entry.
+    if (params.assertBeforeMutation)
+        assertCurrent();
+    params.onPublicationAttempt?.();
     fs.linkSync(temporaryPath, targetPath);
     let observerRejected = false;
     let observerError;

package/dist/publish-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAKnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GAAG,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAEjG,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAIF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AA0ND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA6NtC"}
+{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAKnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GAAG,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAEjG,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAIF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AA0ND,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,aAAa,CAAC,EAAE,qCAAqC,CAAC;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4NtC"}

package/dist/publish-file.js

@@ -4,6 +4,7 @@ import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { pinDirectory, } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
+import { ownDirectoryReceipt } from "./directory-receipt.js";
 import { hashFileHandle } from "./file-hash.js";
 import { sameFileIdentity, sameFileIdentityForCleanup, } from "./file-identity.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
@@ -183,8 +184,7 @@ export async function publishFileExclusive(params) {
     const targetPathInput = admitStandalonePublicationPath(params.targetPath, "publication target uses a Windows filesystem namespace alias");
     const parentReceiptInput = params.parentReceipt;
     const parentReceipt = parentReceiptInput
-        ? { path: parentReceiptInput.path, realPath: parentReceiptInput.realPath,
-            identity: parentReceiptInput.identity }
+        ? ownDirectoryReceipt(parentReceiptInput)
         : undefined;
     if (parentReceipt) {
         assertNoWindowsPathAlias(parentReceipt.path, "filesystem", "publication parent uses a Windows filesystem namespace alias");

package/dist/replace-file-temp-owner.d.ts

@@ -1,18 +1,11 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
 export type AtomicTempFailure = Readonly<{
     error: unknown;
 }>;
 export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
-export declare function cleanupPinnedFilePath(params: {
-    pathname: string;
-    handle: FileHandle;
-    identity?: BigIntStats;
-    parentGuard: AnyAsyncDirectoryGuard;
-}): Promise<void>;
 export declare class AsyncAtomicTempOwner {
     #private;
     readonly pathname: string;

package/dist/replace-file-temp-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWvD,KAAK,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AACzE,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CACrF,CAAC;AAIF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAmB7D,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAOf;AAkFD,qBAAa,oBAAoB;;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAG/D;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAEK,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA8Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,eAAe,CAAC,EAAE,iBAAiB,CAAC;QACpC,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqChB;CACF;AAED,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAED,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,SAAgB,GAAG,IAAI,CAkB3E;IAED,eAAe,CACb,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAkDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,eAAe,CAAC,EAAE,iBAAiB,CAAC;QACpC,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAuCP;CACF"}

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,17 +10,6 @@ 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 hasErrorCode(error, expected) {
-    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
-        return false;
-    }
-    try {
-        return Reflect.get(error, "code") === expected;
-    }
-    catch {
-        return false;
-    }
-}
 function describeFailure(error) {
     try {
         return String(error);
@@ -68,58 +58,17 @@ function cleanupFailure(originalFailure, 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 (hasErrorCode(cleanupError, "ENOENT"))
-            return true;
         if (params.throwOnCleanupError) {
             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;

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

@@ -4,9 +4,10 @@ declare const exclusiveSidecarCreate: unique symbol;
 export declare const sidecarExclusiveCreate: Readonly<{
     [exclusiveSidecarCreate]: true;
 }>;
-export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
     relativePath: string;
     data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
     [exclusiveSidecarCreate]?: true;
 };
 export declare function rethrowCreateInputError(error: unknown): never;

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;AAItG,QAAA,MAAM,sBAAsB,eAAmC,CAAC;AAChE,eAAO,MAAM,sBAAsB;;EAA6D,CAAC;AAEjG,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;IAClD,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,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

@@ -20,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, stageBeforePublish: !params[exclusiveSidecarCreate] };
+        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

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

@@ -1 +1 @@
-{"version":3,"file":"root-directory-creation.d.ts","sourceRoot":"","sources":["../src/root-directory-creation.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuDrD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,4BAA4B,GAC9C,OAAO,CAAC,OAAO,CAAC,CAoGlB;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,cAAc,UAAQ,EACtB,iBAAiB,CAAC,EAAE,4BAA4B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAyBf"}
+{"version":3,"file":"root-directory-creation.d.ts","sourceRoot":"","sources":["../src/root-directory-creation.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuDhF;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,4BAA4B,GAC9C,OAAO,CAAC,OAAO,CAAC,CAoGlB;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,iBAAiB,CAAC,EAAE,4BAA4B,EAChD,WAAW,UAAQ,GAClB,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,oBAAoB,CAAC,EAAE,MAAM,IAAI,EACjC,cAAc,UAAQ,EACtB,iBAAiB,CAAC,EAAE,4BAA4B,EAChD,WAAW,UAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CAiCf"}