@openclaw/fs-safe 0.4.7 → 0.5.0

package/dist/pinned-write.js

@@ -8,8 +8,9 @@ import { syncDirectoryBestEffort } from "./fsync.js";
 import { sameFileIdentity, sha256Hex } from "./file-identity.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
-import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
-import { assertPinnedPythonOperationAvailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
+import { runPinnedWriteNative } from "./native-pinned-write.js";
+import { getNativeBinding } from "./native.js";
+import { validatePinnedOperationPayload } from "./pinned-operation.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function byteLength(input, encoding) {
@@ -57,74 +58,21 @@ async function writeStreamToHandle(stream, handle, maxBytes) {
         }
     }
 }
-async function inputToBase64(input, maxBytes) {
-    if (input.kind === "buffer") {
-        assertWithinMaxBytes(byteLength(input.data, input.encoding), maxBytes);
-        return (typeof input.data === "string"
-            ? Buffer.from(input.data, input.encoding ?? "utf8")
-            : input.data).toString("base64");
-    }
-    const chunks = [];
-    let bytes = 0;
-    for await (const chunk of input.stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += buffer.byteLength;
-        assertWithinMaxBytes(bytes, maxBytes);
-        chunks.push(buffer);
-    }
-    return Buffer.concat(chunks, bytes).toString("base64");
-}
 export async function runPinnedWriteHelper(params) {
     assertSafeBasename(params.basename);
     validatePinnedOperationPayload({
         relativeParentPath: params.relativeParentPath,
     });
-    // The Python helper deliberately enforces the strict post-rename inode
-    // contract. The explicit compatibility policy therefore uses the guarded
-    // Node fallback, where content verification can replace that one check.
+    // The explicit compatibility policy uses the guarded Node fallback, where
+    // content verification can replace the strict post-rename inode check.
     if (params.onRenameIdentityMismatch === "verify-content") {
         return await runPinnedWriteFallback(params);
     }
-    if (getFsSafePythonConfig().mode === "off") {
-        return await runPinnedWriteFallback(params);
-    }
-    if (params.input.kind === "stream") {
-        try {
-            assertPinnedPythonOperationAvailable();
-        }
-        catch (error) {
-            if (canFallbackFromPythonError(error)) {
-                return await runPinnedWriteFallback(params);
-            }
-            throw error;
-        }
-    }
-    const input = params.input.kind === "stream"
-        ? { kind: "buffer", data: Buffer.from(await inputToBase64(params.input, params.maxBytes), "base64") }
-        : params.input;
-    const payload = {
-        base64: await inputToBase64(input, params.maxBytes),
-        basename: params.basename,
-        maxBytes: params.maxBytes ?? -1,
-        mkdir: params.mkdir,
-        mode: params.mode || 0o600,
-        overwrite: params.overwrite !== false,
-        relativeParentPath: params.relativeParentPath,
-        ...(params.rootIdentity ? { rootDev: params.rootIdentity.dev, rootIno: params.rootIdentity.ino } : {}),
-    };
-    try {
-        return await runPinnedPythonOperation({
-            operation: "write",
-            rootPath: params.rootPath,
-            payload,
-        });
-    }
-    catch (error) {
-        if (canFallbackFromPythonError(error)) {
-            return await runPinnedWriteFallback({ ...params, input });
-        }
-        throw error;
+    const native = getNativeBinding();
+    if (native && params.overwrite === false) {
+        return await runPinnedWriteNative(native, params);
     }
+    return await runPinnedWriteFallback(params);
 }
 export async function runPinnedWriteWithRenamePolicy(params) {
     const { targetPath, renameIdentity, ...writeParams } = params;
@@ -147,34 +95,19 @@ export async function runPinnedWriteWithRenamePolicy(params) {
         onRenameIdentityMismatch: "verify-content",
     }));
 }
-export async function runPinnedCopyHelper(params) {
-    assertSafeBasename(params.basename);
-    validatePinnedOperationPayload({
-        relativeParentPath: params.relativeParentPath,
-    });
-    return await runPinnedPythonOperation({
-        operation: "copy",
-        rootPath: params.rootPath,
-        payload: {
-            basename: params.basename,
-            maxBytes: params.maxBytes ?? -1,
-            mkdir: params.mkdir,
-            mode: params.mode || 0o600,
-            overwrite: params.overwrite !== false,
-            relativeParentPath: params.relativeParentPath,
-            ...(params.rootIdentity ? { rootDev: params.rootIdentity.dev, rootIno: params.rootIdentity.ino } : {}),
-            sourceDev: params.sourceIdentity.dev,
-            sourceIno: params.sourceIdentity.ino,
-            sourcePath: params.sourcePath,
-        },
-    });
-}
 async function runPinnedWriteFallback(params) {
-    const parentPath = params.relativeParentPath
+    let parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
     if (params.mkdir) {
-        await mkdirPathComponentsWithGuards({ rootReal: params.rootPath, targetPath: parentPath });
+        // mkdirPathComponentsWithGuards may resolve the final component through
+        // an in-root symlink (e.g. a skill-bank layout). Use its returned real
+        // path for the subsequent guard and target path so we don't re-check the
+        // original, possibly-symlinked, lexical path and reject it outright.
+        parentPath = await mkdirPathComponentsWithGuards({
+            rootReal: params.rootPath,
+            targetPath: parentPath,
+        });
     }
     const parentGuard = params.mkdir
         ? await createAsyncDirectoryGuard(parentPath)
@@ -190,6 +123,7 @@ async function runPinnedWriteFallback(params) {
         });
         let created = true;
         try {
+            await handle.chmod(params.mode);
             if (params.input.kind === "buffer") {
                 assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
                 if (typeof params.input.data === "string") {
@@ -229,6 +163,7 @@ async function runPinnedWriteFallback(params) {
     let renamed = false;
     try {
         handle = await fs.open(tempPath, tempFlags, params.mode);
+        await handle.chmod(params.mode);
         if (params.input.kind === "buffer") {
             assertWithinMaxBytes(byteLength(params.input.data, params.input.encoding), params.maxBytes);
             if (typeof params.input.data === "string") {

package/dist/private-directory.d.ts

@@ -0,0 +1,5 @@
+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-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-directory.d.ts","sourceRoot":"","sources":["../src/private-directory.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/private-directory.js

@@ -0,0 +1,13 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+export async function createPrivateDirectory(targetPath, options) {
+    const platform = options?.platform ?? process.platform;
+    if (platform !== "win32") {
+        throw new FsSafeError("helper-unavailable", "private-directory creation is available only on Windows through the bundled native binding");
+    }
+    const native = getNativeBinding();
+    if (!native) {
+        throw new FsSafeError("helper-unavailable", "private Windows directory creation requires the bundled native binding");
+    }
+    native.createPrivateDirectory(targetPath);
+}

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

@@ -1,4 +1,6 @@
 import { type FileStore, type FileStoreSync } from "./file-store.js";
+import { type TempPathIdentityReceipt } from "./temp-cleanup.js";
+export type TempWorkspaceCleanupResult = "removed" | "missing" | "identity-mismatch";
 export type TempWorkspaceOptions = {
     rootDir: string;
     prefix: string;
@@ -7,6 +9,7 @@ export type TempWorkspaceOptions = {
 };
 export type TempWorkspace = {
     dir: string;
+    identity: TempPathIdentityReceipt;
     store: FileStore;
     path(fileName: string): string;
     write(fileName: string, data: string | Uint8Array): Promise<string>;
@@ -16,11 +19,12 @@ export type TempWorkspace = {
     }): Promise<string>;
     copyIn(fileName: string, sourcePath: string): Promise<string>;
     read(fileName: string): Promise<Buffer>;
-    cleanup(): Promise<void>;
+    cleanup(): Promise<TempWorkspaceCleanupResult>;
     [Symbol.asyncDispose](): Promise<void>;
 };
 export type TempWorkspaceSync = {
     dir: string;
+    identity: TempPathIdentityReceipt;
     store: FileStoreSync;
     path(fileName: string): string;
     write(fileName: string, data: string | Uint8Array): string;
@@ -29,7 +33,7 @@ export type TempWorkspaceSync = {
         trailingNewline?: boolean;
     }): string;
     read(fileName: string): Buffer;
-    cleanup(): void;
+    cleanup(): TempWorkspaceCleanupResult;
     [Symbol.dispose](): void;
 };
 export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<TempWorkspace>;

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

@@ -1 +1 @@
-{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAsGF,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAwEnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAUH"}
+{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAErF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,uBAAuB,CAAC;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC/C,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,uBAAuB,CAAC;IAClC,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC5F,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,IAAI,0BAA0B,CAAC;IACtC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AA0IF,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAsEnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAUH"}

package/dist/private-temp-workspace.js

@@ -4,7 +4,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileStore, fileStoreSync, } from "./file-store.js";
 import { openRootFileSync } from "./root-file.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { registerTempPathForExit, } from "./temp-cleanup.js";
 function sanitizeTempPrefix(prefix) {
     const sanitized = prefix.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
     if (!sanitized || sanitized === "." || sanitized === "..") {
@@ -49,6 +50,34 @@ function ensurePrivateDirectorySync(dir, mode) {
         // Best-effort on platforms that do not enforce POSIX modes.
     }
 }
+async function cleanupWorkspace(dir, identity) {
+    let current;
+    try {
+        current = await fs.lstat(dir);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "identity-mismatch";
+    }
+    if (!sameFileIdentity(current, identity)) {
+        return "identity-mismatch";
+    }
+    await fs.rm(dir, { recursive: true, force: true });
+    return "removed";
+}
+function cleanupWorkspaceSync(dir, identity) {
+    let current;
+    try {
+        current = fsSync.lstatSync(dir);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "identity-mismatch";
+    }
+    if (!sameFileIdentity(current, identity)) {
+        return "identity-mismatch";
+    }
+    fsSync.rmSync(dir, { recursive: true, force: true });
+    return "removed";
+}
 async function createTempWorkspace(options) {
     const dirMode = options.dirMode ?? 0o700;
     const mode = options.mode ?? 0o600;
@@ -56,15 +85,17 @@ async function createTempWorkspace(options) {
     const root = await fs.realpath(requestedRoot).catch(() => requestedRoot);
     await ensurePrivateDirectory(root, dirMode);
     const dir = await fs.mkdtemp(path.join(root, sanitizeTempPrefix(options.prefix)));
-    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true });
     await fs.chmod(dir, dirMode).catch(() => undefined);
     const stat = await fs.lstat(dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new Error(`Temp workspace must be a directory: ${dir}`);
     }
+    const identity = { dev: stat.dev, ino: stat.ino };
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const store = fileStore({ rootDir: dir, private: true, dirMode, mode });
     return {
         dir,
+        identity,
         store,
         path: (fileName) => resolveWorkspaceLeaf(dir, fileName),
         write: async (fileName, data) => await store.write(assertWorkspaceFileName(fileName), data, { mode }),
@@ -77,7 +108,7 @@ async function createTempWorkspace(options) {
         read: async (fileName) => await store.readBytes(assertWorkspaceFileName(fileName)),
         cleanup: async () => {
             try {
-                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+                return await cleanupWorkspace(dir, identity);
             }
             finally {
                 unregisterTempDir();
@@ -85,7 +116,7 @@ async function createTempWorkspace(options) {
         },
         [Symbol.asyncDispose]: async () => {
             try {
-                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+                await cleanupWorkspace(dir, identity);
             }
             finally {
                 unregisterTempDir();
@@ -121,7 +152,6 @@ export function tempWorkspaceSync(options) {
     }
     ensurePrivateDirectorySync(root, dirMode);
     const dir = fsSync.mkdtempSync(path.join(root, sanitizeTempPrefix(options.prefix)));
-    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true });
     try {
         fsSync.chmodSync(dir, dirMode);
     }
@@ -132,9 +162,12 @@ export function tempWorkspaceSync(options) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new Error(`Temp workspace must be a directory: ${dir}`);
     }
+    const identity = { dev: stat.dev, ino: stat.ino };
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const store = fileStoreSync({ rootDir: dir, private: true, dirMode, mode });
     return {
         dir,
+        identity,
         store,
         path: (fileName) => resolveWorkspaceLeaf(dir, fileName),
         write: (fileName, data) => store.write(assertWorkspaceFileName(fileName), data, { mode }),
@@ -162,10 +195,7 @@ export function tempWorkspaceSync(options) {
         },
         cleanup: () => {
             try {
-                fsSync.rmSync(dir, { recursive: true, force: true });
-            }
-            catch {
-                // Best-effort cleanup.
+                return cleanupWorkspaceSync(dir, identity);
             }
             finally {
                 unregisterTempDir();
@@ -173,10 +203,7 @@ export function tempWorkspaceSync(options) {
         },
         [Symbol.dispose]: () => {
             try {
-                fsSync.rmSync(dir, { recursive: true, force: true });
-            }
-            catch {
-                // Best-effort cleanup.
+                cleanupWorkspaceSync(dir, identity);
             }
             finally {
                 unregisterTempDir();

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

@@ -0,0 +1,27 @@
+import { FsSafeError } from "./errors.js";
+import type { FileIdentityStat } from "./file-identity.js";
+export type PublishFileExclusiveSyncFailurePolicy = "rollback" | "preserve";
+export type PublishFileExclusiveDirectorySyncFailure = {
+    status: "failed";
+    code?: string;
+};
+export type PublishFileExclusiveFailurePhase = "copy-create" | "copy-verify" | "directory-sync" | "hardlink-create" | "hardlink-verify" | "rename-create" | "rename-verify";
+export type PublishFileExclusiveCleanup = "removed" | "preserved" | "unknown";
+export type PublishFileExclusiveFailureDetails = {
+    phase: PublishFileExclusiveFailurePhase;
+    targetCreated: boolean;
+    targetIdentity?: FileIdentityStat;
+    cleanup: PublishFileExclusiveCleanup;
+    directorySync?: PublishFileExclusiveDirectorySyncFailure;
+};
+export type PublishFailureState = {
+    phase: PublishFileExclusiveFailurePhase;
+    targetCreated: boolean;
+    targetIdentity?: FileIdentityStat;
+    preserveTarget: boolean;
+    directorySync?: PublishFileExclusiveDirectorySyncFailure;
+};
+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-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-file-failure.d.ts","sourceRoot":"","sources":["../src/publish-file-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,qCAAqC,GAAG,UAAU,GAAG,UAAU,CAAC;AAC5E,MAAM,MAAM,wCAAwC,GAAG;IACrD,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AACF,MAAM,MAAM,gCAAgC,GACxC,aAAa,GACb,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,eAAe,CAAC;AACpB,MAAM,MAAM,2BAA2B,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAC9E,MAAM,MAAM,kCAAkC,GAAG;IAC/C,KAAK,EAAE,gCAAgC,CAAC;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC,OAAO,EAAE,2BAA2B,CAAC;IACrC,aAAa,CAAC,EAAE,wCAAwC,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,gCAAgC,CAAC;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,wCAAwC,CAAC;CAC1D,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gCAAgC,GACtC,IAAI,CAIN;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,2BAA2B,GACnC,WAAW,CAcb;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,wCAAwC,CAG1C"}

package/dist/publish-file-failure.js

@@ -0,0 +1,21 @@
+import { FsSafeError } from "./errors.js";
+export function rememberCreatedTarget(state, identity, phase) {
+    state.targetCreated = true;
+    state.targetIdentity = { dev: identity.dev, ino: identity.ino };
+    state.phase = phase;
+}
+export function publicationFailure(error, state, cleanup) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const details = {
+        phase: state.phase,
+        targetCreated: state.targetCreated,
+        ...(state.targetIdentity ? { targetIdentity: state.targetIdentity } : {}),
+        ...(state.directorySync ? { directorySync: state.directorySync } : {}),
+        cleanup,
+    };
+    return new FsSafeError(error instanceof FsSafeError ? error.code : "helper-failed", `exclusive file publication failed during ${state.phase}: ${cause.message}`, { cause, details });
+}
+export function directorySyncFailure(error) {
+    const code = error?.code;
+    return typeof code === "string" ? { status: "failed", code } : { status: "failed" };
+}

package/dist/publish-file.d.ts

@@ -0,0 +1,21 @@
+import { 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";
+    identity: Stats;
+    directorySync: DirectorySyncOutcome;
+};
+export declare function isHardlinkFallbackError(error: unknown): boolean;
+export declare function publishFileExclusive(params: {
+    sourcePath: string;
+    targetPath: string;
+    expectedSourceIdentity?: FileIdentityStat;
+    strategy: PublishFileExclusiveStrategy;
+    onSyncFailure?: PublishFileExclusiveSyncFailurePolicy;
+    parentReceipt?: DirectoryReceipt;
+}): Promise<PublishFileExclusiveResult>;
+//# sourceMappingURL=publish-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"publish-file.d.ts","sourceRoot":"","sources":["../src/publish-file.ts"],"names":[],"mappings":"AACA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAI7C,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAML,KAAK,qCAAqC,EAC3C,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wCAAwC,EACxC,kCAAkC,EAClC,gCAAgC,EAChC,qCAAqC,GACtC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,4BAA4B,GACpC,cAAc,GACd,eAAe,GACf,kBAAkB,CAAC;AAEvB,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;AAkBF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAoND,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,CA8LtC"}