@openclaw/fs-safe 0.15.0 → 0.17.0

package/dist/private-producer-handoff-sync.js

@@ -0,0 +1,114 @@
+import fs, {} from "node:fs";
+import { ownFileDescriptorSync } from "./create-owned-file.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertInitialSource, assertParents, inspectLinkedFile, normalizeLinkError, } from "./private-producer-handoff.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+export function handoffCreatedFileSync(params) {
+    let retained = params.source;
+    const owners = new Set([retained]);
+    const failures = [];
+    let publication = "not-published";
+    let cleanup = "preserved";
+    let closeFailed = false;
+    function close(owner) {
+        // A throwing close may already have released the descriptor for reuse.
+        owners.delete(owner);
+        try {
+            owner.close();
+        }
+        catch (error) {
+            closeFailed = true;
+            throw error;
+        }
+    }
+    function assertIdentityCurrent(owner, links) {
+        assertParents(params);
+        inspectLinkedFile(() => fs.fstatSync(owner.fd, { bigint: true }), params.identity, links, "created file descriptor");
+        if (cleanup !== "removed") {
+            inspectLinkedFile(() => fs.lstatSync(params.sourcePath, { bigint: true }), params.identity, links, "created file stage");
+        }
+        if (publication === "published") {
+            inspectLinkedFile(() => fs.lstatSync(params.targetPath, { bigint: true }), params.identity, links, "created file destination");
+        }
+    }
+    function verifyCurrent(owner, descriptorPath, links) {
+        assertIdentityCurrent(owner, links);
+        params.verifyDescriptor?.(owner.fd, descriptorPath, Number(links));
+    }
+    try {
+        assertInitialSource(params.identity);
+        verifyCurrent(retained, params.sourcePath, 1n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        assertIdentityCurrent(retained, 1n);
+        publication = "indeterminate";
+        try {
+            fs.linkSync(params.sourcePath, params.targetPath);
+        }
+        catch (error) {
+            const normalized = normalizeLinkError(error);
+            if (normalized instanceof FsSafeError &&
+                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
+                publication = "not-published";
+            }
+            throw normalized;
+        }
+        publication = "published";
+        try {
+            params.onPublished?.();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (process.platform === "win32") {
+            verifyCurrent(retained, params.sourcePath, 2n);
+            // Keep the original pin until a verified published-name pin exists, so
+            // Windows can retire the staging name without leaving it delete-pending.
+            const sibling = ownFileDescriptorSync(fs.openSync(params.targetPath, fs.constants.O_RDWR | resolveReadOpenFlags()));
+            owners.add(sibling);
+            verifyCurrent(sibling, params.targetPath, 2n);
+            inspectLinkedFile(() => fs.fstatSync(retained.fd, { bigint: true }), params.identity, 2n, "created file descriptor");
+            close(retained);
+            retained = sibling;
+        }
+        const descriptorPath = process.platform === "win32" ? params.targetPath : params.sourcePath;
+        verifyCurrent(retained, descriptorPath, 2n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        assertIdentityCurrent(retained, 2n);
+        cleanup = "failed";
+        // Link and unlink stay in one JS turn. Only the verified stage is removed;
+        // publication has committed and the destination is never rollback cleanup.
+        fs.unlinkSync(params.sourcePath);
+        cleanup = "removed";
+        verifyCurrent(retained, params.targetPath, 1n);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length === 0)
+        return retained;
+    for (const owner of owners) {
+        try {
+            close(owner);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    const primary = failures[0];
+    // Collision-as-no-op callers must still observe a failed settlement.
+    const code = closeFailed || failures.length > 1
+        ? "helper-failed"
+        : primary instanceof FsSafeError ? primary.code : "helper-failed";
+    throw new FsSafeError(code, "created file publication failed", {
+        cause: failures.length === 1 ? primary : new AggregateError(failures, "created file publication and settlement failed"),
+        details: {
+            publication: { status: publication },
+            cleanup,
+            resources: closeFailed ? "close-failed" : "closed",
+            path: params.targetPath,
+            dev: params.identity.dev,
+            ino: params.identity.ino,
+        },
+    });
+}

package/dist/private-producer-handoff.d.ts

@@ -6,11 +6,29 @@ export type PrivateProducerHandoff = {
     identity: BigIntStats;
     unregister: TempPathRegistration;
 };
-export declare function handoffPrivateProducerFile(params: {
-    sourcePath: string;
-    targetPath: string;
+type HandoffParents = {
     assertSourceParent: () => void;
     assertTargetParent: () => void;
+};
+type HandoffPaths = HandoffParents & {
+    sourcePath: string;
+    targetPath: string;
+};
+type ProducerHandoffParams = HandoffPaths & {
     readWrite: boolean;
-}): Promise<PrivateProducerHandoff>;
+};
+type CreatedHandoffParams = HandoffPaths & {
+    source: FileHandle;
+    identity: BigIntStats;
+    assertBeforeMutation?: () => void;
+    verifyDescriptor?: (fd: number, path: string, links: number) => Promise<void>;
+    onPublished?: () => void;
+};
+export declare function assertInitialSource(stat: BigIntStats): void;
+export declare function inspectLinkedFile(inspect: () => BigIntStats, expected: BigIntStats, links: bigint, label: string): BigIntStats;
+export declare function assertParents(params: HandoffParents): void;
+export declare function normalizeLinkError(error: unknown): unknown;
+export declare function handoffPrivateProducerFile(params: ProducerHandoffParams): Promise<PrivateProducerHandoff>;
+export declare function handoffCreatedFile(params: CreatedHandoffParams): Promise<FileHandle>;
+export {};
 //# sourceMappingURL=private-producer-handoff.d.ts.map

package/dist/private-producer-handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-producer-handoff.d.ts","sourceRoot":"","sources":["../src/private-producer-handoff.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKvD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,oBAAoB,CAAC;CAClC,CAAC;AA2OF,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA6HlC"}
+{"version":3,"file":"private-producer-handoff.d.ts","sourceRoot":"","sources":["../src/private-producer-handoff.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMvD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,oBAAoB,CAAC;CAClC,CAAC;AASF,KAAK,cAAc,GAAG;IACpB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC,CAAC;AAEF,KAAK,YAAY,GAAG,cAAc,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAChF,KAAK,qBAAqB,GAAG,YAAY,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC;AACnE,KAAK,oBAAoB,GAAG,YAAY,GAAG;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAMF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAU3D;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,WAAW,EAC1B,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,WAAW,CAQb;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAG1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmB1D;AAiUD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAEzG;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAEpF"}

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

@@ -1,4 +1,4 @@
-import { type Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import { type DirectoryReceipt, type DirectorySyncOutcome } from "./directory-durability.js";
 import { type FileIdentityStat } from "./file-identity.js";
 import { type PublishFileExclusiveSyncFailurePolicy } from "./publish-file-failure.js";
@@ -16,6 +16,6 @@ export declare function publishFileExclusive(params: {
     expectedSourceIdentity?: FileIdentityStat;
     strategy: PublishFileExclusiveStrategy;
     onSyncFailure?: PublishFileExclusiveSyncFailurePolicy;
-    parentReceipt?: DirectoryReceipt;
+    parentReceipt?: DirectoryReceipt<Stats | BigIntStats>;
 }): Promise<PublishFileExclusiveResult>;
 //# sourceMappingURL=publish-file.d.ts.map

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,EAAE,KAAK,WAAW,EAAE,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;AAOnC,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;AAgOD,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,KAAK,GAAG,WAAW,CAAC,CAAC;CACvD,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAsKtC"}