@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/permissions.d.ts

@@ -57,4 +57,3 @@ export declare function isGroupWritable(bits: number | null): boolean;
 export declare function isWorldReadable(bits: number | null): boolean;
 export declare function isGroupReadable(bits: number | null): boolean;
 export declare function formatPosixMode(mode: number): string;
-//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.js

@@ -39,23 +39,9 @@ export async function inspectPathPermissions(targetPath, opts) {
     const admissionPlatform = process.platform === "win32"
         ? process.platform
         : (opts?.platform ?? process.platform);
-    if (hasWindowsPathAlias(targetPath, "filesystem", admissionPlatform)) {
-        const st = failedSafeStat("Path uses a Windows filesystem namespace alias");
-        return {
-            ok: false,
-            isSymlink: false,
-            isDir: false,
-            mode: null,
-            bits: null,
-            source: "unknown",
-            worldWritable: false,
-            groupWritable: false,
-            worldReadable: false,
-            groupReadable: false,
-            error: st.error,
-        };
-    }
-    const st = await safeStatAdmitted(targetPath);
+    const st = hasWindowsPathAlias(targetPath, "filesystem", admissionPlatform)
+        ? failedSafeStat("Path uses a Windows filesystem namespace alias")
+        : await safeStatAdmitted(targetPath);
     if (!st.ok) {
         return {
             ok: false,
@@ -85,28 +71,20 @@ export async function inspectPathPermissions(targetPath, opts) {
     }
     const bits = modeBits(effectiveMode);
     const platform = opts?.platform ?? process.platform;
-    if (platform === "win32") {
-        return await inspectWindowsPermissions({
-            targetPath,
-            stat: st,
-            effectiveIsDir,
-            effectiveMode,
-            bits,
-            opts,
-        });
-    }
-    return {
+    const windows = platform === "win32";
+    const permissions = {
         ok: true,
         isSymlink: st.isSymlink,
         isDir: effectiveIsDir,
         mode: effectiveMode,
         bits,
-        source: "posix",
-        worldWritable: isWorldWritable(bits),
-        groupWritable: isGroupWritable(bits),
-        worldReadable: isWorldReadable(bits),
-        groupReadable: isGroupReadable(bits),
+        source: windows ? "unknown" : "posix",
+        worldWritable: !windows && isWorldWritable(bits),
+        groupWritable: !windows && isGroupWritable(bits),
+        worldReadable: !windows && isWorldReadable(bits),
+        groupReadable: !windows && isGroupReadable(bits),
     };
+    return windows ? await inspectWindowsPermissions(targetPath, permissions, opts) : permissions;
 }
 export function formatPermissionDetail(targetPath, perms) {
     if (perms.source === "windows-acl") {

package/dist/pinned-mutation-admission.d.ts

@@ -22,4 +22,3 @@ export declare function preparePinnedWriteMutationAdmission(params: {
     relativeParentPath: string;
     mutationAdmission?: PinnedWriteMutationAdmission;
 }>;
-//# sourceMappingURL=pinned-mutation-admission.d.ts.map

package/dist/pinned-mutation-observation.d.ts

@@ -36,4 +36,3 @@ export declare function mutationObservationCurrent(observation: MutationPathObse
 export declare function mutationObservationsCurrent(observations: readonly MutationPathObservation[], directories: readonly MutationDirectoryObservation[]): boolean;
 export declare function advanceMutationObservation(observation: MutationPathObservation, parent: MutationDirectoryObservation, child: MutationDirectoryObservation): MutationPathObservation | undefined;
 export {};
-//# sourceMappingURL=pinned-mutation-observation.d.ts.map

package/dist/pinned-mutation-shared-route.d.ts

@@ -22,4 +22,3 @@ export declare function simpleSharedRoute(params: {
     rootIdentity: ExactRootIdentity;
 } | undefined;
 export {};
-//# sourceMappingURL=pinned-mutation-shared-route.d.ts.map

package/dist/pinned-open.d.ts

@@ -5,6 +5,7 @@ export type PinnedOpenSyncResult = {
     path: string;
     fd: number;
     stat: fs.Stats;
+    identity: fs.BigIntStats;
 } | {
     ok: false;
     reason: PinnedOpenSyncFailureReason;
@@ -27,4 +28,3 @@ export declare function openPinnedFileSync(params: {
     ioFs?: PinnedOpenSyncFs;
     finalAdmission?: PinnedOpenSyncFinalAdmission;
 }): PinnedOpenSyncResult;
-//# sourceMappingURL=pinned-open.d.ts.map

package/dist/pinned-open.js

@@ -63,7 +63,7 @@ export function openPinnedFileSync(params) {
             preRealpathIdentity: pathIdentity,
             descriptorIdentity: identity,
         }) ?? realPath;
-        const opened = { ok: true, path: admittedPath, fd, stat: openedStat };
+        const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };
         fd = null;
         return opened;
     }

package/dist/pinned-operation.d.ts

@@ -1,2 +1 @@
 export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
-//# sourceMappingURL=pinned-operation.d.ts.map

package/dist/pinned-write-input.d.ts

@@ -1,4 +1,3 @@
 import type { FileHandle } from "node:fs/promises";
 import type { PinnedWriteInput } from "./pinned-write-types.js";
 export declare function writePinnedInput(target: FileHandle | number, input: PinnedWriteInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
-//# sourceMappingURL=pinned-write-input.d.ts.map

package/dist/pinned-write-input.js

@@ -1,6 +1,16 @@
+import { types } from "node:util";
+import { snapshotByteView } from "./byte-view.js";
 import { writeCopyFileToFd } from "./copy-file-input.js";
 import { FsSafeError } from "./errors.js";
 import { writeAllToFile } from "./write-file-handle.js";
+const isUint8Array = types.isUint8Array;
+function streamChunkBytes(chunk) {
+    if (Buffer.isBuffer(chunk))
+        return chunk;
+    if (!isUint8Array(chunk))
+        return Buffer.from(chunk);
+    return snapshotByteView(chunk);
+}
 export async function writePinnedInput(target, input, maxBytes, assertBeforeMutation) {
     if (input.kind === "file") {
         await writeCopyFileToFd(typeof target === "number" ? target : target.fd, input, maxBytes, assertBeforeMutation);
@@ -19,7 +29,7 @@ export async function writePinnedInput(target, input, maxBytes, assertBeforeMuta
     }
     else {
         for await (const chunk of input.stream) {
-            await write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            await write(streamChunkBytes(chunk));
         }
     }
 }

package/dist/pinned-write-mode.d.ts

@@ -1,5 +1,4 @@
 import type { FileHandle } from "node:fs/promises";
-export declare function assertPinnedWriteMode(fd: number, mode: number): void;
-export declare function preparePinnedWriteMode(handle: FileHandle, createdMode: number, assertBeforeMutation?: () => void): Promise<(() => void) | undefined>;
-export declare function pinnedWriteModeAssertion(fd: number, mode: number, assertBeforeMutation?: () => void): () => void;
-//# sourceMappingURL=pinned-write-mode.d.ts.map
+export declare function assertPinnedWriteMode(fd: number, mode: number, privateCreation?: boolean): void;
+export declare function preparePinnedWriteMode(handle: FileHandle, createdMode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): Promise<(() => void) | undefined>;
+export declare function pinnedWriteModeAssertion(fd: number, mode: number, assertBeforeMutation?: () => void, privateCreation?: boolean): () => void;

package/dist/pinned-write-mode.js

@@ -1,24 +1,31 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
-export function assertPinnedWriteMode(fd, mode) {
+import { assertPrivateCreationFile } from "./creation-file-state.js";
+export function assertPinnedWriteMode(fd, mode, privateCreation = false) {
     if (process.platform === "win32")
         return;
-    if (Number(fs.fstatSync(fd, { bigint: true }).mode & 4095n) !== mode) {
-        throw new FsSafeError("insecure-permissions", "filesystem did not enforce the secret file mode");
+    const stat = fs.fstatSync(fd, { bigint: true });
+    if (privateCreation)
+        assertPrivateCreationFile(stat, fd);
+    if (Number(stat.mode & 4095n) !== mode) {
+        throw new FsSafeError("insecure-permissions", "filesystem did not enforce the requested file mode");
     }
 }
-export async function preparePinnedWriteMode(handle, createdMode, assertBeforeMutation) {
+export async function preparePinnedWriteMode(handle, createdMode, assertBeforeMutation, privateCreation = false) {
     if (process.platform === "win32")
         return assertBeforeMutation;
     assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
-    if (createdMode !== 0o600)
+    if (createdMode !== 0o600) {
+        if (privateCreation)
+            assertPrivateCreationFile(fs.fstatSync(handle.fd, { bigint: true }), handle.fd);
         await handle.chmod(0o600);
-    return pinnedWriteModeAssertion(handle.fd, 0o600, assertBeforeMutation);
+    }
+    return pinnedWriteModeAssertion(handle.fd, 0o600, assertBeforeMutation, privateCreation);
 }
-export function pinnedWriteModeAssertion(fd, mode, assertBeforeMutation) {
+export function pinnedWriteModeAssertion(fd, mode, assertBeforeMutation, privateCreation = false) {
     return () => {
         assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
-        assertPinnedWriteMode(fd, mode);
+        assertPinnedWriteMode(fd, mode, privateCreation);
     };
 }

package/dist/pinned-write-staged.d.ts

@@ -3,4 +3,3 @@ import type { AsyncDirectoryGuard } from "./directory-guard.js";
 import { type FileIdentityStat } from "./file-identity.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedStagedWrite(params: PinnedWriteParams, parentPath: string, parentGuard: AsyncDirectoryGuard<BigIntStats>): Promise<FileIdentityStat>;
-//# sourceMappingURL=pinned-write-staged.d.ts.map

package/dist/pinned-write-staged.js

@@ -9,7 +9,6 @@ import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity, sha256Hex } from "./file-identity.js";
 import { syncFileBestEffort } from "./file-sync.js";
-import { assertDarwinCreationAcl, privateFileMutationAssertion } from "./creation-darwin.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { writePinnedInput } from "./pinned-write-input.js";
 import { assertPinnedWriteMode, pinnedWriteModeAssertion, preparePinnedWriteMode } from "./pinned-write-mode.js";
@@ -20,7 +19,8 @@ import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createStagedFileReceipt, settleStagedFile } from "./staged-file-settlement.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
-    const verifyPosixMode = params.verifyPosixMode === true && process.platform !== "win32";
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
     const targetPath = path.join(parentPath, params.basename);
     // Private staging must not consume the destination basename's filename budget.
     const tempPath = path.join(parentPath, `.fs-safe-${randomUUID()}.tmp`);
@@ -49,18 +49,15 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
             : await fs.open(tempPath, tempFlags, verifyPosixMode ? 0o600 : params.mode);
         let verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
         tempIdentity = verificationIdentity;
-        let assertBeforeMutation = params.private
-            ? privateFileMutationAssertion(handle.fd, params.assertBeforeMutation) : params.assertBeforeMutation;
+        let assertBeforeMutation = params.assertBeforeMutation;
         const assertBeforeWrite = verifyPosixMode
-            ? await preparePinnedWriteMode(handle, Number(tempIdentity.mode & 4095n), assertBeforeMutation)
+            ? await preparePinnedWriteMode(handle, Number(tempIdentity.mode & 4095n), assertBeforeMutation, params.private)
             : assertBeforeMutation;
         if (verifyPosixMode)
-            assertPinnedWriteMode(handle.fd, 0o600);
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
         await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
         if (verifyPosixMode)
-            assertPinnedWriteMode(handle.fd, 0o600);
-        if (params.private)
-            assertDarwinCreationAcl(handle.fd);
+            assertPinnedWriteMode(handle.fd, 0o600, params.private);
         tempStat = fsSync.fstatSync(handle.fd);
         const tempPathStat = fsSync.lstatSync(tempPath);
         if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
@@ -69,8 +66,8 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
         const expectedTempStat = tempStat;
         await handle.chmod(params.mode);
         if (verifyPosixMode) {
-            assertPinnedWriteMode(handle.fd, params.mode);
-            assertBeforeMutation = pinnedWriteModeAssertion(handle.fd, params.mode, assertBeforeMutation);
+            assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            assertBeforeMutation = pinnedWriteModeAssertion(handle.fd, params.mode, params.assertBeforeMutation, params.private);
         }
         if (params.sync !== false) {
             if (params.strictFileSync)
@@ -146,6 +143,8 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
             }
         });
         await params.verifyPublished?.((readHandle ?? handle).fd, verificationIdentity, parentGuard);
+        if (verifyPosixMode)
+            assertPinnedWriteMode((readHandle ?? handle).fd, params.mode, params.private);
         return { dev: verifiedIdentity.dev, ino: verifiedIdentity.ino };
     }
     catch (error) {

package/dist/pinned-write-types.d.ts

@@ -24,18 +24,15 @@ export type PinnedCreatedDirectoryReceipt = Readonly<{
     parent: MutationDirectoryObservation;
     child: MutationDirectoryObservation;
 }>;
+export type PinnedMutationParentRequest = {
+    targetPath: string;
+    mutationPath: string;
+    phase: "parent" | "parent-create";
+};
 export type PinnedMutationParentWalkSession = Readonly<{
     retainedTargetPath: string;
-    tryAuthorizeAtParent(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    tryAuthorizeAtParent(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
     advanceCreatedDirectory(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
     dispose(): void;
 }>;
@@ -44,16 +41,8 @@ export type PinnedWriteMutationAdmission = Readonly<{
     beginParentWalk?(): string | undefined;
     beginSharedParentWalk?(): PinnedMutationParentWalkSession | undefined;
     beginNativeParentWalk?(): PinnedMutationParentWalkSession | undefined;
-    tryAuthorizeAtParent?(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
-    authorize(request: Readonly<{
-        targetPath: string;
-        mutationPath: string;
-        phase: "parent" | "parent-create";
-    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    tryAuthorizeAtParent?(request: Readonly<PinnedMutationParentRequest>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<PinnedMutationParentRequest>): Promise<PinnedMutationAdmissionReceipt | undefined>;
     advanceCreatedDirectory?(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
 }>;
 export type PinnedWriteParams = {
@@ -77,4 +66,3 @@ export type PinnedWriteParams = {
     onPublished?: (identity: PublishedWriteIdentity) => void;
     verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
 };
-//# sourceMappingURL=pinned-write-types.d.ts.map

package/dist/pinned-write.d.ts

@@ -11,4 +11,3 @@ export declare function withPinnedWriteRenameIdentityLock<T>(params: {
     targetPath: string;
     relativeTargetPath: string;
 }, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=pinned-write.d.ts.map

package/dist/pinned-write.js

@@ -1,5 +1,4 @@
 import { syncFileBestEffort } from "./file-sync.js";
-import { assertDarwinCreationAcl, privateFileMutationAssertion } from "./creation-darwin.js";
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -124,7 +123,8 @@ export async function withPinnedWriteRenameIdentityLock(params, run) {
     }, run);
 }
 async function runPinnedWriteFallback(params) {
-    const verifyPosixMode = params.verifyPosixMode === true && process.platform !== "win32";
+    const verifyPosixMode = process.platform !== "win32" &&
+        (params.verifyPosixMode === true || params.private === true);
     const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
         ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
     const mutationAdmission = params.mutationAdmission;
@@ -250,25 +250,23 @@ async function runPinnedWriteFallback(params) {
             },
         });
         let created = true;
+        let completed = false;
         let createdIdentity;
         try {
             const verificationIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
             createdIdentity = verificationIdentity;
-            let assertBeforeWrite = params.private
-                ? privateFileMutationAssertion(handle.fd, assertBeforeMutation) : assertBeforeMutation;
-            if (verifyPosixMode) {
-                assertBeforeWrite = await preparePinnedWriteMode(handle, Number(createdIdentity.mode & 4095n), assertBeforeWrite);
-                assertPinnedWriteMode(handle.fd, 0o600);
-            }
+            const assertBeforeWrite = verifyPosixMode
+                ? await preparePinnedWriteMode(handle, Number(createdIdentity.mode & 4095n), assertBeforeMutation, params.private)
+                : assertBeforeMutation;
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, 0o600, params.private);
             await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
             if (verifyPosixMode)
-                assertPinnedWriteMode(handle.fd, 0o600);
-            if (params.private)
-                assertDarwinCreationAcl(handle.fd);
+                assertPinnedWriteMode(handle.fd, 0o600, params.private);
             // Content writes may clear set-ID bits; finalize them through the owned fd.
             await handle.chmod(params.mode);
             if (verifyPosixMode)
-                assertPinnedWriteMode(handle.fd, params.mode);
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
             if (params.sync !== false) {
                 if (params.strictFileSync)
                     await handle.sync();
@@ -281,6 +279,9 @@ async function runPinnedWriteFallback(params) {
             // Publication is complete. A failed outer check must not remove its target.
             created = false;
             await params.verifyPublished?.(handle.fd, verificationIdentity, parentGuard);
+            if (verifyPosixMode)
+                assertPinnedWriteMode(handle.fd, params.mode, params.private);
+            completed = true;
             return { dev: stat.dev, ino: stat.ino };
         }
         finally {
@@ -290,7 +291,10 @@ async function runPinnedWriteFallback(params) {
                 }
             }
             finally {
-                await handle.close().catch(() => undefined);
+                if (completed)
+                    await handle.close();
+                else
+                    await handle.close().catch(() => undefined);
             }
         }
     }

package/dist/positional-read.d.ts

@@ -6,4 +6,3 @@ export type ReadFileWindowOptions = {
 export declare function readFileWindowFully(handle: FileHandle, buffer: Buffer, position: number, { signal }?: ReadFileWindowOptions): Promise<number>;
 /** Synchronous positional read; neither variant advances or closes its descriptor. */
 export declare function readFileWindowFullySync(fd: number, buffer: Buffer, position: number): number;
-//# sourceMappingURL=positional-read.d.ts.map

package/dist/private-directory.d.ts

@@ -2,4 +2,3 @@ export type CreatePrivateDirectoryOptions = {
     platform?: NodeJS.Platform;
 };
 export declare function createPrivateDirectory(targetPath: string, options?: CreatePrivateDirectoryOptions): Promise<void>;
-//# sourceMappingURL=private-directory.d.ts.map

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

@@ -11,4 +11,3 @@ export declare function handoffCreatedFileSync(params: {
     verifyDescriptor?: (fd: number, path: string, links: number) => void;
     onPublished?: () => void;
 }): OwnedFileDescriptorSync;
-//# sourceMappingURL=private-producer-handoff-sync.d.ts.map

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

@@ -1,16 +1,13 @@
 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 { assertInitialSource, FileHandoff, inspectLinkedFile, } 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;
+    const state = new FileHandoff(params, params.identity, true);
     function close(owner) {
         // A throwing close may already have released the descriptor for reuse.
         owners.delete(owner);
@@ -18,42 +15,20 @@ export function handoffCreatedFileSync(params) {
             owner.close();
         }
         catch (error) {
-            closeFailed = true;
+            state.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);
+        state.inspect(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";
+        state.inspect(retained, 1n);
+        state.publish();
         try {
             params.onPublished?.();
         }
@@ -74,12 +49,10 @@ export function handoffCreatedFileSync(params) {
         const descriptorPath = process.platform === "win32" ? params.targetPath : params.sourcePath;
         verifyCurrent(retained, descriptorPath, 2n);
         assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
-        assertIdentityCurrent(retained, 2n);
-        cleanup = "failed";
+        state.inspect(retained, 2n);
         // 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";
+        state.retireSource();
         verifyCurrent(retained, params.targetPath, 1n);
     }
     catch (error) {
@@ -95,20 +68,5 @@ export function handoffCreatedFileSync(params) {
             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,
-        },
-    });
+    throw state.failure(failures, "created file publication and settlement failed");
 }

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

@@ -1,5 +1,6 @@
 import { type BigIntStats } from "node:fs";
 import { type FileHandle } from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
 import { type TempPathRegistration } from "./temp-cleanup.js";
 export type PrivateProducerHandoff = {
     handle: FileHandle;
@@ -28,7 +29,25 @@ 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 class FileHandoff {
+    private readonly paths;
+    private readonly identity;
+    private readonly createdLabels;
+    siblingOwned: boolean;
+    publication: "not-published" | "published" | "indeterminate";
+    cleanup: "preserved" | "removed" | "failed";
+    closeFailed: boolean;
+    constructor(paths: HandoffPaths, identity: BigIntStats, createdLabels?: boolean);
+    inspect(owner: {
+        readonly fd: number;
+    }, links: bigint): {
+        opened: BigIntStats;
+        named?: BigIntStats;
+    };
+    publish(): void;
+    retireSource(): void;
+    failure(failures: readonly unknown[], aggregateMessage: string): FsSafeError;
+}
 export declare function handoffPrivateProducerFile(params: ProducerHandoffParams): Promise<PrivateProducerHandoff>;
 export declare function handoffCreatedFile(params: CreatedHandoffParams): Promise<FileHandle>;
 export {};
-//# sourceMappingURL=private-producer-handoff.d.ts.map