@openclaw/fs-safe 0.17.0 → 0.18.0

package/dist/permissions-windows.d.ts

@@ -1,5 +1,5 @@
 import { type PermissionCommandFailure } from "./permission-exec.js";
-import { type PermissionCheck, type PermissionCheckOptions, type SafeStatResult } from "./permissions.js";
+import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
@@ -31,14 +31,7 @@ export type IcaclsResetCommandOptions = {
     env?: NodeJS.ProcessEnv;
     userInfo?: WindowsUserInfoProvider;
 };
-export declare function inspectWindowsPermissions(params: {
-    targetPath: string;
-    stat: SafeStatResult;
-    effectiveIsDir: boolean;
-    effectiveMode: number | null;
-    bits: number | null;
-    opts?: PermissionCheckOptions;
-}): Promise<PermissionCheck>;
+export declare function inspectWindowsPermissions(targetPath: string, unverified: Readonly<PermissionCheck>, opts?: PermissionCheckOptions): Promise<PermissionCheck>;
 export declare function resolveWindowsUserPrincipal(env?: NodeJS.ProcessEnv, userInfo?: WindowsUserInfoProvider): string | null;
 export declare function parseIcaclsOutput(output: string, targetPath: string): WindowsAclEntry[];
 export declare function summarizeWindowsAcl(entries: WindowsAclEntry[], env?: NodeJS.ProcessEnv): Pick<WindowsAclSummary, "trusted" | "untrustedWorld" | "untrustedGroup">;
@@ -56,4 +49,3 @@ export declare function createIcaclsResetCommand(targetPath: string, opts: Icacl
     args: string[];
     display: string;
 } | null;
-//# sourceMappingURL=permissions-windows.d.ts.map

package/dist/permissions-windows.js

@@ -39,20 +39,16 @@ const TRUSTED_BASE_ASCII = new Set([...TRUSTED_BASE].map(stripDiacritics));
 const normalize = (value) => normalizeLowercaseStringOrEmpty(value);
 const defaultWindowsUserInfo = () => os.userInfo();
 const defaultPermissionExec = executePermissionCommand;
-function inspectWindowsPermissionsNative(params) {
+function inspectWindowsPermissionsNative(targetPath, unverified) {
     const native = getNativeBinding();
     if (!native)
         return undefined;
     try {
-        const facts = native.readOwnerAndDacl(params.targetPath);
+        const facts = native.readOwnerAndDacl(targetPath);
         if (facts.fallbackRequired)
             return undefined;
         return {
-            ok: true,
-            isSymlink: params.stat.isSymlink,
-            isDir: params.effectiveIsDir,
-            mode: params.effectiveMode,
-            bits: params.bits,
+            ...unverified,
             source: "windows-acl",
             worldWritable: facts.worldWritable,
             groupWritable: facts.groupWritable,
@@ -69,32 +65,20 @@ function inspectWindowsPermissionsNative(params) {
         return undefined;
     }
 }
-export async function inspectWindowsPermissions(params) {
-    const unverified = {
-        ok: true,
-        isSymlink: params.stat.isSymlink,
-        isDir: params.effectiveIsDir,
-        mode: params.effectiveMode,
-        bits: params.bits,
-        source: "unknown",
-        worldWritable: false,
-        groupWritable: false,
-        worldReadable: false,
-        groupReadable: false,
-    };
-    if (hasWindowsPathAlias(params.targetPath, "filesystem", "win32")) {
+export async function inspectWindowsPermissions(targetPath, unverified, opts) {
+    if (hasWindowsPathAlias(targetPath, "filesystem", "win32")) {
         return {
             ...unverified,
             error: "Path uses a Windows filesystem namespace alias",
         };
     }
-    const native = inspectWindowsPermissionsNative(params);
+    const native = inspectWindowsPermissionsNative(targetPath, unverified);
     if (native)
         return native;
     const owner = await inspectWindowsOwner({
-        targetPath: params.targetPath,
-        env: params.opts?.env,
-        exec: params.opts?.exec ?? defaultPermissionExec,
+        targetPath,
+        env: opts?.env,
+        exec: opts?.exec ?? defaultPermissionExec,
     });
     if (owner.error !== undefined) {
         const error = `Windows owner inspection failed: ${owner.error}`;
@@ -109,11 +93,7 @@ export async function inspectWindowsPermissions(params) {
     if (!acl.ok)
         return { ...unverified, ...ownerFields, error: acl.error, errorDetail: acl.errorDetail, errorCause: acl.errorCause };
     return {
-        ok: true,
-        isSymlink: params.stat.isSymlink,
-        isDir: params.effectiveIsDir,
-        mode: params.effectiveMode,
-        bits: params.bits,
+        ...unverified,
         source: "windows-acl",
         worldWritable: acl.untrustedWorld.some((entry) => entry.canWrite),
         groupWritable: acl.untrustedGroup.some((entry) => entry.canWrite),

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

@@ -71,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-mode.d.ts

@@ -2,4 +2,3 @@ import type { FileHandle } from "node:fs/promises";
 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;
-//# sourceMappingURL=pinned-write-mode.d.ts.map

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-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/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

package/dist/private-producer-handoff.js

@@ -165,14 +165,62 @@ async function openProducerSource(params, identity, links = 1n) {
     }
     return fallback;
 }
-function inspectHandoff(params, handle, identity, state, links) {
-    assertParents(params);
-    const opened = inspectSourceDescriptor(handle, identity, links);
-    if (state.cleanup !== "removed") {
-        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, links, "isolated producer path");
+export class FileHandoff {
+    paths;
+    identity;
+    createdLabels;
+    siblingOwned = false;
+    publication = "not-published";
+    cleanup = "preserved";
+    closeFailed = false;
+    constructor(paths, identity, createdLabels = false) {
+        this.paths = paths;
+        this.identity = identity;
+        this.createdLabels = createdLabels;
+    }
+    inspect(owner, links) {
+        assertParents(this.paths);
+        const opened = inspectLinkedFile(() => fsSync.fstatSync(owner.fd, { bigint: true }), this.identity, links, this.createdLabels ? "created file descriptor" : "isolated producer descriptor");
+        if (this.cleanup !== "removed") {
+            inspectLinkedFile(() => fsSync.lstatSync(this.paths.sourcePath, { bigint: true }), this.identity, links, this.createdLabels ? "created file stage" : "isolated producer path");
+        }
+        const named = this.publication === "published"
+            ? inspectLinkedFile(() => fsSync.lstatSync(this.paths.targetPath, { bigint: true }), this.identity, links, this.createdLabels ? "created file destination" : "isolated producer sibling")
+            : undefined;
+        return { opened, named };
+    }
+    publish() {
+        this.publication = "indeterminate";
+        try {
+            fsSync.linkSync(this.paths.sourcePath, this.paths.targetPath);
+        }
+        catch (error) {
+            const normalized = normalizeLinkError(error);
+            if (normalized instanceof FsSafeError &&
+                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
+                this.publication = "not-published";
+            }
+            throw normalized;
+        }
+        this.publication = "published";
+    }
+    retireSource() {
+        this.cleanup = "failed";
+        fsSync.unlinkSync(this.paths.sourcePath);
+        this.cleanup = "removed";
+    }
+    failure(failures, aggregateMessage) {
+        const primary = failures[0];
+        // Collision-as-no-op callers must still observe a failed settlement.
+        return new FsSafeError(this.closeFailed || failures.length > 1 ? "helper-failed" : primary instanceof FsSafeError ? primary.code : "helper-failed", "created file publication failed", {
+            cause: failures.length === 1 ? primary : new AggregateError(failures, aggregateMessage),
+            details: {
+                publication: { status: this.publication }, cleanup: this.cleanup,
+                resources: this.closeFailed ? "close-failed" : "closed",
+                path: this.paths.targetPath, dev: this.identity.dev, ino: this.identity.ino,
+            },
+        });
     }
-    const named = state.publication === "published" ? inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, links, "isolated producer sibling") : undefined;
-    return { opened, named };
 }
 async function handoffFile(params) {
     const created = "source" in params ? params : undefined;
@@ -186,9 +234,7 @@ async function handoffFile(params) {
     const owners = new Set(handle ? [handle] : []);
     const failures = [];
     let unregister;
-    const state = {
-        siblingOwned: false, publication: "not-published", cleanup: "preserved", closeFailed: false,
-    };
+    const state = new FileHandoff(params, identity);
     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.
@@ -209,7 +255,7 @@ async function handoffFile(params) {
             handle = await openProducerSource({ ...params, readWrite: "readWrite" in params && params.readWrite }, identity);
             owners.add(handle);
         }
-        inspectHandoff(params, handle, identity, state, 1n);
+        state.inspect(handle, 1n);
         if (created?.verifyDescriptor)
             await created.verifyDescriptor(handle.fd, params.sourcePath, 1);
         if (!created) {
@@ -220,20 +266,8 @@ async function handoffFile(params) {
             });
         }
         assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
-        inspectHandoff(params, handle, identity, state, 1n);
-        state.publication = "indeterminate";
-        try {
-            fsSync.linkSync(params.sourcePath, params.targetPath);
-        }
-        catch (error) {
-            const normalized = normalizeLinkError(error);
-            if (normalized instanceof FsSafeError &&
-                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
-                state.publication = "not-published";
-            }
-            throw normalized;
-        }
-        state.publication = "published";
+        state.inspect(handle, 1n);
+        state.publish();
         state.siblingOwned = !created;
         try {
             assertSynchronousCallbackResult(created?.onPublished?.(), "onPublished");
@@ -241,7 +275,7 @@ async function handoffFile(params) {
         catch (error) {
             failures.push(error);
         }
-        inspectHandoff(params, handle, identity, state, 2n);
+        state.inspect(handle, 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.
@@ -250,26 +284,24 @@ async function handoffFile(params) {
                 : await openProducerSource({ ...params, sourcePath: params.targetPath,
                     readWrite: "readWrite" in params && params.readWrite }, identity, 2n);
             owners.add(sibling);
-            inspectHandoff(params, sibling, identity, state, 2n);
+            state.inspect(sibling, 2n);
             if (created?.verifyDescriptor)
                 await created.verifyDescriptor(sibling.fd, params.targetPath, 2);
-            inspectHandoff(params, sibling, identity, state, 2n);
+            state.inspect(sibling, 2n);
             inspectSourceDescriptor(handle, identity, 2n);
             await close(handle);
             handle = sibling;
             // The old handle's close yielded; both names must still be ours.
-            inspectHandoff(params, handle, identity, state, 2n);
+            state.inspect(handle, 2n);
         }
         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);
-        state.cleanup = "removed";
+        state.inspect(handle, 2n);
+        state.retireSource();
         if (created?.verifyDescriptor)
             await created.verifyDescriptor(handle.fd, params.targetPath, 1);
-        const { opened, named } = inspectHandoff(params, handle, identity, state, 1n);
+        const { opened, named } = state.inspect(handle, 1n);
         const originalMode = identity.mode & 511n;
         if (!created && process.platform === "win32" && (originalMode & 128n) === 0n &&
             ((opened.mode & 511n) !== originalMode || (named.mode & 511n) !== originalMode)) {
@@ -277,7 +309,7 @@ async function handoffFile(params) {
             // admitted sibling inode, without reopening or chmodding its pathname.
             assertParents(params);
             fsSync.fchmodSync(handle.fd, Number(originalMode));
-            const restored = inspectHandoff(params, handle, identity, state, 1n);
+            const restored = state.inspect(handle, 1n);
             if ((restored.opened.mode & 511n) !== originalMode || (restored.named.mode & 511n) !== originalMode) {
                 throw pathMismatch("isolated producer read-only mode could not be restored");
             }
@@ -314,18 +346,9 @@ async function handoffFile(params) {
             failures.push(error);
         }
     }
-    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,
-        },
-    });
+        throw combinedFailure(failures[0], failures.slice(1));
+    throw state.failure(failures, "isolated producer handoff and settlement failed");
 }
 export function handoffPrivateProducerFile(params) {
     return handoffFile(params);

package/dist/private-temp-workspace.d.ts

@@ -5,4 +5,3 @@ export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<Te
 export declare function withTempWorkspace<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspace) => Promise<T>): Promise<T>;
 export declare function tempWorkspaceSync(options: TempWorkspaceOptions): TempWorkspaceSync;
 export declare function withTempWorkspaceSync<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspaceSync) => T): T;
-//# sourceMappingURL=private-temp-workspace.d.ts.map