@openclaw/fs-safe 0.17.0 → 0.18.1

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;
@@ -17,18 +18,36 @@ type HandoffPaths = HandoffParents & {
 type ProducerHandoffParams = HandoffPaths & {
     readWrite: boolean;
 };
-type CreatedHandoffParams = HandoffPaths & {
-    source: FileHandle;
+export type CreatedHandoffParams<TSource = FileHandle, TVerification = Promise<void>> = HandoffPaths & {
+    source: TSource;
     identity: BigIntStats;
     assertBeforeMutation?: () => void;
-    verifyDescriptor?: (fd: number, path: string, links: number) => Promise<void>;
+    verifyDescriptor?: (fd: number, path: string, links: number) => TVerification;
     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 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

package/dist/private-temp-workspace.js

@@ -9,12 +9,11 @@ import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { throwFsSafeReadError } from "./root-errors.js";
 import { matchRootFileOpenFailure, openRootFileSync, } from "./root-file.js";
 import { registerTempPathForExit, } from "./temp-cleanup.js";
-import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, } from "./temp-workspace-owner.js";
+import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, throwTempWorkspaceCreationFailure, } from "./temp-workspace-owner.js";
 import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
 import { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
-import { admitRetainedTempWorkspaceChild, admitRetainedTempWorkspaceChildSync, validateInitialTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
+import { validateInitialTempWorkspaceChild, validateTempWorkspaceDirMode } from "./temp-workspace-child-admission.js";
 import { admitTempWorkspaceRoot, admitTempWorkspaceRootSync, } from "./temp-workspace-admission.js";
-import { validateTempWorkspaceDirMode } from "./temp-workspace-permissions.js";
 function resolveTempWorkspaceCleanupSafety(value) {
     if (value === undefined || value === "compatible")
         return "compatible";
@@ -125,36 +124,6 @@ function tempWorkspaceChildPrefix(root, options, scopedPrefix) {
     assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
     return childPrefix;
 }
-function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner) {
-    try {
-        if (owner)
-            owner.cleanupSync();
-        else {
-            const closeErrors = [];
-            try {
-                retainedChild?.close();
-            }
-            catch (closeError) {
-                closeErrors.push(closeError);
-            }
-            try {
-                capability.close();
-            }
-            catch (closeError) {
-                closeErrors.push(closeError);
-            }
-            if (closeErrors.length === 1)
-                throw closeErrors[0];
-            if (closeErrors.length > 1) {
-                throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
-            }
-        }
-    }
-    catch (cleanupError) {
-        throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
-    }
-    throw error;
-}
 function registerTempWorkspace(dir, retainedChild, capability, admission, dirMode) {
     let owner;
     let stat;
@@ -201,9 +170,9 @@ async function createTempWorkspace(options, scopedPrefix = false) {
         // Retain while the child still has its private creation mode so an
         // explicit dirMode such as 0 cannot make identity descriptor acquisition fail.
         retainedChild = TempWorkspaceRetainedChild.retain(dir, stat);
-        const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, dirMode);
-        if (modeInitialization)
-            await modeInitialization;
+        if (needsModeInitialization) {
+            await retainedChild.initializeMode(dirMode, admission.ownerUid, admission.assertCurrent);
+        }
     }
     catch (error) {
         throwTempWorkspaceCreationFailure(error, retainedChild, capability);
@@ -294,7 +263,12 @@ function createTempWorkspaceSync(options, scopedPrefix = false) {
         }
         const needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
         retainedChild ??= TempWorkspaceRetainedChild.retain(dir, stat);
-        admitRetainedTempWorkspaceChildSync(retainedChild, needsModeInitialization, admission, dirMode);
+        if (needsModeInitialization) {
+            retainedChild.initializeModeSync(dirMode, admission.ownerUid, admission.assertCurrent);
+        }
+        else {
+            retainedChild.discardInitialReceipt();
+        }
     }
     catch (error) {
         throwTempWorkspaceCreationFailure(error, retainedChild, capability);

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

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

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

@@ -25,4 +25,3 @@ export type PublishFailureState = {
 export declare function rememberCreatedTarget(state: PublishFailureState, identity: FileIdentityStat, phase: PublishFileExclusiveFailurePhase): void;
 export declare function publicationFailure(error: unknown, state: PublishFailureState, cleanup: PublishFileExclusiveCleanup): FsSafeError;
 export declare function directorySyncFailure(error: unknown): PublishFileExclusiveDirectorySyncFailure;
-//# sourceMappingURL=publish-file-failure.d.ts.map

package/dist/publish-file.d.ts

@@ -2,7 +2,6 @@ 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";
-export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
 export type PublishFileExclusiveStrategy = "link-or-copy" | "link-required" | "rename-noreplace";
 export type PublishFileExclusiveResult = {
     method: "hardlink" | "exclusive-copy" | "rename-noreplace";
@@ -18,4 +17,3 @@ export declare function publishFileExclusive(params: {
     onSyncFailure?: PublishFileExclusiveSyncFailurePolicy;
     parentReceipt?: DirectoryReceipt<Stats | BigIntStats>;
 }): Promise<PublishFileExclusiveResult>;
-//# sourceMappingURL=publish-file.d.ts.map

package/dist/publish-file.js

@@ -12,9 +12,8 @@ import { getNativeBinding, requireNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from "./publish-file-failure.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { hasErrorCode } from "./file-cleanup.js";
 import { writeAllToFile } from "./write-file-handle.js";
 const HARDLINK_FALLBACK_CODES = new Set(["EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);

package/dist/read-open-flags.d.ts

@@ -5,4 +5,3 @@ export declare function resolveReadOpenFlags(options?: {
     followSymlinks?: boolean;
 }): number;
 export {};
-//# sourceMappingURL=read-open-flags.d.ts.map

package/dist/read-opened-file.d.ts

@@ -18,4 +18,3 @@ export declare function readOpenedFileSafely(params: {
     maxBytes?: number;
 }): Promise<ReadResult>;
 export {};
-//# sourceMappingURL=read-opened-file.d.ts.map

package/dist/realpath.d.ts

@@ -1,4 +1,3 @@
 export declare const realpathSync: ((input: string) => string) & {
     native: (input: string) => string;
 };
-//# sourceMappingURL=realpath.d.ts.map

package/dist/recursive-mkdir-path.d.ts

@@ -1,3 +1,2 @@
 /** Bun's Windows recursive mkdir cannot inspect existing relative dot components. */
 export declare function recursiveMkdirPath(directory: string): string;
-//# sourceMappingURL=recursive-mkdir-path.d.ts.map

package/dist/regular-file.d.ts

@@ -35,4 +35,3 @@ export declare function readRegularFileSync(params: {
 export declare function appendRegularFile(options: AppendRegularFileOptions): Promise<void>;
 export declare function appendRegularFileSync(options: AppendRegularFileOptions): void;
 export {};
-//# sourceMappingURL=regular-file.d.ts.map