@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/native-pinned-write.js

@@ -1,142 +1,151 @@
-import { randomUUID } from "node:crypto";
-import fsSync, {} from "node:fs";
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { removeNativeCreatedFileIfStillPinned, syncNativeFileBestEffort, writeNativeFd, } from "./native-operations.js";
-function assertWithinMaxBytes(bytes, maxBytes) {
-    if (maxBytes !== undefined && bytes > maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
-    }
-}
-async function writeNativeInput(fd, input, maxBytes) {
-    if (input.kind === "buffer") {
-        const data = typeof input.data === "string"
-            ? Buffer.from(input.data, input.encoding ?? "utf8")
-            : Buffer.from(input.data);
-        assertWithinMaxBytes(data.byteLength, maxBytes);
-        writeNativeFd(fd, data);
-        return;
-    }
-    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);
-        writeNativeFd(fd, buffer);
-    }
-}
-function nativeOpenFlags(flags) {
-    const closeOnExec = fsSync.constants.O_CLOEXEC;
-    return (flags |
-        (closeOnExec ?? 0) |
-        (typeof fsSync.constants.O_NOFOLLOW === "number" ? fsSync.constants.O_NOFOLLOW : 0));
-}
-function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
+import { runPinnedWriteWindows, sameNativeIdentity } from "./native-pinned-write-windows.js";
+import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
+import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
 export async function runPinnedWriteNative(binding, params) {
-    const root = await fs.open(params.rootPath, fsSync.constants.O_RDONLY |
-        (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
-    let parentFd;
-    let tempFd;
-    let targetFd;
-    let tempIdentity;
-    let parentPath = params.rootPath;
-    const tempName = `.${params.basename}.${randomUUID()}.native.tmp`;
-    let renamed = false;
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const rootIdentity = binding.fstatIdentity(root.fd);
-        if (params.rootIdentity && !sameNativeIdentity(params.rootIdentity, rootIdentity)) {
-            throw new FsSafeError("path-mismatch", "root path changed during native write");
-        }
-        if (params.mkdir) {
-            binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
-        }
-        const parentFlags = fsSync.constants.O_RDONLY |
-            (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0);
-        parentFd = binding.openBeneath(root.fd, params.relativeParentPath, parentFlags).fd;
-        parentPath = await fs.realpath(params.relativeParentPath
-            ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
-            : params.rootPath);
-        const parentPathStat = await fs.lstat(parentPath);
-        const parentIdentity = binding.fstatIdentity(parentFd);
-        if (parentPathStat.isSymbolicLink() ||
-            !sameNativeIdentity(parentPathStat, parentIdentity)) {
-            throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+        const windows = process.platform === "win32";
+        if (!windows) {
+            assertNativeStaging(binding);
         }
-        if (params.overwrite === false) {
-            try {
-                await fs.lstat(path.join(parentPath, params.basename));
-                throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+        const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
+        const root = await fs.open(params.rootPath, directoryFlags);
+        const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
+        let parentFd;
+        let windowsOwnsDirectories = false;
+        // Until stage construction takes ownership, even admission failures must close
+        // the raw POSIX parent. Disposal preserves both admission and close failures.
+        const parentGuard = __addDisposableResource(env_1, {
+            [Symbol.dispose]() {
+                if (!windows && parentFd !== undefined) {
+                    fsSync.closeSync(parentFd);
+                }
+            },
+        }, false);
+        try {
+            let rootMatches;
+            if (windows) {
+                const identity = binding.fstatIdentity(root.fd);
+                rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
             }
-            catch (error) {
-                if (error.code !== "ENOENT") {
-                    throw error;
+            else {
+                const identity = fsSync.fstatSync(root.fd, { bigint: true });
+                rootMatches = !params.rootIdentity || exactIdentityMatches(params.rootIdentity, identity);
+            }
+            if (!rootMatches) {
+                throw new FsSafeError("path-mismatch", "root path changed during native write");
+            }
+            if (params.mkdir) {
+                binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
+            }
+            parentFd = binding.openBeneath(root.fd, params.relativeParentPath, directoryFlags).fd;
+            const parentPath = await fs.realpath(params.relativeParentPath
+                ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
+                : params.rootPath);
+            const directory = windows ? undefined : describeStagedDirectory(parentFd, parentPath);
+            const parentPathStat = await fs.lstat(parentPath);
+            if (windows) {
+                const parentIdentity = binding.fstatIdentity(parentFd);
+                if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
+                    throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
                 }
             }
+            else if (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, directory.identity)) {
+                throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+            }
+            const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
+            if (params.overwrite === false) {
+                try {
+                    await fs.lstat(path.join(parentPath, params.basename));
+                    throw Object.assign(new Error("destination already exists"), { code: "EEXIST" });
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            }
+            if (windows) {
+                // The Windows leaf owns both directories after admission.
+                windowsOwnsDirectories = true;
+                return await runPinnedWriteWindows(binding, params, root, parentFd, verificationGuard);
+            }
+            const ownedParent = parentFd;
+            parentFd = undefined;
+            return await writeNativeStage(binding, ownedParent, directory, params, verificationGuard);
         }
-        tempFd = binding.openBeneath(parentFd, tempName, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL)).fd;
-        tempIdentity = fsSync.fstatSync(tempFd);
-        // Creation is requested at 0600 in the binding, but a restrictive umask
-        // can remove owner access. Keep the unpublished inode private and
-        // reopenable until the published name has been identity-fenced.
-        fsSync.fchmodSync(tempFd, 0o600);
-        await writeNativeInput(tempFd, params.input, params.maxBytes);
-        syncNativeFileBestEffort(tempFd);
-        if (params.overwrite === false) {
-            binding.renameNoReplace(parentFd, tempName, parentFd, params.basename);
-        }
-        else {
-            binding.renameReplace(parentFd, tempName, parentFd, params.basename);
-        }
-        renamed = true;
-        targetFd = binding.openBeneath(parentFd, params.basename, nativeOpenFlags(fsSync.constants.O_RDONLY)).fd;
-        const targetIdentity = binding.fstatIdentity(targetFd);
-        if (!targetIdentity.isFile || !sameNativeIdentity(tempIdentity, targetIdentity)) {
-            throw new FsSafeError("path-mismatch", "native write target changed after rename");
-        }
-        // Native exclusive creation starts at 0600. Apply the requested mode only
-        // after reopening and fencing the published name, both so mode 000 stays
-        // verifiable and so broader modes are never exposed before that fence.
-        try {
-            fsSync.fchmodSync(targetFd, params.mode);
-            syncNativeFileBestEffort(targetFd);
-        }
-        catch (error) {
-            fsSync.closeSync(targetFd);
-            targetFd = undefined;
-            removeNativeCreatedFileIfStillPinned({
-                binding,
-                parentPath,
-                parentFd,
-                basename: params.basename,
-                created: tempIdentity,
-            });
-            throw error;
+        finally {
+            if (windows && !windowsOwnsDirectories) {
+                if (parentFd !== undefined) {
+                    fsSync.closeSync(parentFd);
+                }
+                await root.close().catch(() => undefined);
+            }
         }
-        syncNativeFileBestEffort(parentFd);
-        return { dev: targetIdentity.dev, ino: targetIdentity.ino };
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
     }
     finally {
-        if (targetFd !== undefined) {
-            fsSync.closeSync(targetFd);
-        }
-        if (tempFd !== undefined) {
-            fsSync.closeSync(tempFd);
-        }
-        if (!renamed && parentFd !== undefined) {
-            removeNativeCreatedFileIfStillPinned({
-                binding,
-                parentPath,
-                parentFd,
-                basename: tempName,
-                created: tempIdentity,
-            });
-        }
-        if (parentFd !== undefined) {
-            fsSync.closeSync(parentFd);
-        }
-        await root.close().catch(() => undefined);
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
     }
 }

package/dist/native-staged-file.d.ts

@@ -0,0 +1,24 @@
+import type { AsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write.js";
+import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
+export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile">>;
+export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
+declare class NativeStagedFile implements StagedFile {
+    #private;
+    constructor(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number);
+    static create(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean): Promise<NativeStagedFile>;
+    static write(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], params: PinnedWriteParams, parentGuard: AsyncDirectoryGuard): Promise<FileIdentityStat>;
+    get receipt(): StagedFileReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string, options: {
+        overwrite: boolean;
+    }): Promise<PublishedFileReceipt>;
+    cleanup(): Promise<StagedFileCleanupReceipt>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare const createNativeStage: (...args: Parameters<typeof NativeStagedFile.create>) => Promise<StagedFile>;
+export declare const writeNativeStage: typeof NativeStagedFile.write;
+export {};
+//# sourceMappingURL=native-staged-file.d.ts.map

package/dist/native-staged-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,wBAAwB,EAGxB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,QAAQ,CAAC,IAAI,CAC9D,aAAa,EACb,kBAAkB,GAAG,mBAAmB,GAAG,kBAAkB,CAC9D,CAAC,CAAC;AAEH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,IAAI,oBAAoB,CAUnG;AA6BD,cAAM,gBAAiB,YAAW,UAAU;;IAU1C,YACE,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,MAAM,EAOtB;IAGD,OAAa,MAAM,CACjB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,EAEjB,aAAa,UAAO,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAc3B;IAED,OAAa,KAAK,CAChB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAU3B;IAED,IAAI,OAAO,IAAI,iBAAiB,CAK/B;IAoFK,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnC;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgD9F;IA6CK,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAMjD;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3C;CACF;AAED,eAAO,MAAM,iBAAiB,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,UAAU,CAClF,CAAC;AAC1B,eAAO,MAAM,gBAAgB,+BAAyB,CAAC"}

package/dist/native-staged-file.js

@@ -0,0 +1,337 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { syncNativeFileBestEffort, writeNativeInput } from "./native-operations.js";
+import { assertStagedDirectoryCurrent } from "./staged-directory.js";
+export function assertNativeStaging(binding) {
+    if ([
+        binding.createStagedFile,
+        binding.stagedFileMatches,
+        binding.removeStagedFile,
+        binding.renameReplace,
+        binding.renameNoReplace,
+    ].some((fn) => typeof fn !== "function")) {
+        throw new FsSafeError("helper-unavailable", "native retained-directory staging is unavailable");
+    }
+}
+function assertBasename(name, portable) {
+    if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0") ||
+        (portable && /[\\:\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(name))) {
+        throw new FsSafeError("invalid-path", "publication requires one direct-child basename");
+    }
+}
+const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
+const UNCOMMITTED_RENAME_ERRORS = new Set([
+    "EACCES", "EBADF", "EBUSY", "EEXIST", "EINVAL", "EISDIR", "ELOOP", "EMLINK",
+    "ENAMETOOLONG", "ENOENT", "ENOSPC", "ENOSYS", "ENOTDIR", "ENOTEMPTY", "ENOTSUP",
+    "EPERM", "EROFS", "ETXTBSY", "EXDEV",
+]);
+function failure(error, details) {
+    const code = error instanceof FsSafeError
+        ? error.code
+        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
+}
+class NativeStagedFile {
+    #binding;
+    #parentFd;
+    #directory;
+    #portableNames;
+    #publishedMode;
+    #name = `.fs-safe-${randomUUID()}.tmp`;
+    #state = { status: "open", publication: NOT_PUBLISHED };
+    #receipt;
+    constructor(binding, parentFd, directory, portableNames, publishedMode) {
+        this.#binding = binding;
+        this.#parentFd = parentFd;
+        this.#directory = directory;
+        this.#portableNames = portableNames;
+        this.#publishedMode = publishedMode;
+    }
+    // Takes ownership of parentFd, including all construction and preparation failures.
+    static async create(binding, parentFd, directory, input, mode, maxBytes, 
+    // Public staging uses portable names; existing POSIX writes accept literal names.
+    portableNames = true) {
+        let staged;
+        try {
+            staged = new NativeStagedFile(binding, parentFd, directory, portableNames, mode);
+        }
+        catch (error) {
+            try {
+                fs.closeSync(parentFd);
+            }
+            catch (closeError) {
+                throw new AggregateError([error, closeError], "staged owner construction and close failed");
+            }
+            throw error;
+        }
+        await staged.#prepare(input, maxBytes);
+        return staged;
+    }
+    static async write(binding, parentFd, directory, params, parentGuard) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // This owner never escapes. Only the internal verifier borrows its fd;
+            // public descriptor methods remain await-free and cannot race disposal.
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, directory, params.input, params.mode, params.maxBytes, false), true);
+            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false });
+            const identity = published.staged.identity;
+            await params.verifyPublished?.(staged.#file(), identity, parentGuard);
+            return { dev: identity.dev, ino: identity.ino };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    }
+    get receipt() {
+        if (!this.#receipt) {
+            throw new FsSafeError("helper-failed", "staged file preparation is incomplete");
+        }
+        return this.#receipt;
+    }
+    #open() {
+        if (this.#state.status === "closed") {
+            throw new FsSafeError("helper-failed", "staged file is closed");
+        }
+        return this.#state;
+    }
+    #file() {
+        const state = this.#open();
+        if (state.fileFd === undefined) {
+            throw new FsSafeError("helper-failed", "staged file has not been created");
+        }
+        return state.fileFd;
+    }
+    #assertNamed(name) {
+        const fd = this.#file();
+        if (!this.#binding.stagedFileMatches(this.#parentFd, name, fd) ||
+            fs.fstatSync(fd, { bigint: true }).nlink !== 1n) {
+            throw new FsSafeError("path-mismatch", "staged entry no longer names the exclusive created file");
+        }
+    }
+    #assertCurrent() {
+        if (this.#open().publication.status !== "not-published") {
+            throw new FsSafeError("helper-failed", "staged file publication has already been attempted");
+        }
+        assertStagedDirectoryCurrent(this.#directory);
+        this.#assertNamed(this.#name);
+    }
+    async #prepare(input, maxBytes) {
+        try {
+            const mode = this.#publishedMode;
+            if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+                throw new FsSafeError("invalid-path", "invalid staged file mode");
+            }
+            assertStagedDirectoryCurrent(this.#directory);
+            // The exclusive open performs no fallible post-open checks. Store its fd
+            // before every subsequent operation, including the first metadata read.
+            const state = this.#open();
+            state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+            const fd = state.fileFd;
+            fs.fchmodSync(fd, 0o600);
+            await writeNativeInput(fd, input, maxBytes);
+            syncNativeFileBestEffort(fd);
+            const stat = fs.fstatSync(fd, { bigint: true });
+            this.#receipt = Object.freeze({
+                directory: this.#directory,
+                temporaryBasename: this.#name,
+                identity: Object.freeze({
+                    dev: stat.dev,
+                    ino: stat.ino,
+                    mode: Number(stat.mode & 4095n),
+                    nlink: stat.nlink,
+                    size: stat.size,
+                    uid: Number(stat.uid),
+                    gid: Number(stat.gid),
+                    mtimeNs: stat.mtimeNs,
+                    ctimeNs: stat.ctimeNs,
+                }),
+            });
+            this.#assertCurrent();
+        }
+        catch (error) {
+            const { receipt: cleanup, error: cleanupError } = this.#finalize();
+            if (cleanupError) {
+                throw failure(new AggregateError([error, cleanupError], "preparation and cleanup failed"), { phase: "prepare", publication: cleanup.publication, cleanup });
+            }
+            if (cleanup.status === "preserved") {
+                throw failure(error, { phase: "prepare", publication: cleanup.publication, cleanup });
+            }
+            throw error;
+        }
+    }
+    // Keep public descriptor work await-free: each call completes its mutations
+    // before the next invocation, including closure and cached cleanup failures.
+    async assertCurrent() {
+        this.#assertCurrent();
+    }
+    async publish(basename, options) {
+        const overwrite = options?.overwrite;
+        try {
+            const state = this.#open();
+            assertBasename(basename, this.#portableNames);
+            if (basename === this.#name || typeof overwrite !== "boolean") {
+                throw new FsSafeError("invalid-path", "publication needs a distinct basename and explicit overwrite policy");
+            }
+            this.#assertCurrent();
+            try {
+                if (overwrite) {
+                    this.#binding.renameReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                }
+                else {
+                    this.#binding.renameNoReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                }
+            }
+            catch (error) {
+                // Unknown rename errors can be indeterminate on remote filesystems.
+                if (!UNCOMMITTED_RENAME_ERRORS.has(error?.code ?? "")) {
+                    state.publication = Object.freeze({ status: "indeterminate", basename, overwrite });
+                }
+                throw error;
+            }
+            // Commit is recorded synchronously before any post-rename operation.
+            const receipt = Object.freeze({
+                status: "published",
+                staged: this.receipt,
+                basename,
+                overwrite,
+            });
+            state.publication = receipt;
+            this.#assertNamed(basename);
+            assertStagedDirectoryCurrent(this.#directory);
+            // Keep contents private until the published name passes its identity
+            // fence. Mode changes use the owned fd, including for final mode 000.
+            const fd = this.#file();
+            fs.fchmodSync(fd, this.#publishedMode);
+            syncNativeFileBestEffort(fd);
+            syncNativeFileBestEffort(this.#parentFd);
+            this.#assertNamed(basename);
+            assertStagedDirectoryCurrent(this.#directory);
+            return receipt;
+        }
+        catch (error) {
+            // Closure rejects further use, not the recorded outcome of an earlier publication.
+            const publication = this.#state.status === "closed"
+                ? this.#state.receipt.publication
+                : this.#state.publication;
+            throw failure(error, { phase: "publish", publication });
+        }
+    }
+    #finalize() {
+        if (this.#state.status === "closed") {
+            return this.#state;
+        }
+        const state = this.#state;
+        let outcome = "not-needed";
+        const errors = [];
+        if (state.publication.status === "indeterminate") {
+            outcome = "preserved";
+        }
+        else if (state.publication.status === "not-published" && state.fileFd !== undefined) {
+            try {
+                outcome = this.#binding.removeStagedFile(this.#parentFd, this.#name, state.fileFd);
+            }
+            catch (error) {
+                outcome = "failed";
+                errors.push(error);
+            }
+        }
+        let resources = "closed";
+        for (const fd of [state.fileFd, this.#parentFd]) {
+            if (fd === undefined) {
+                continue;
+            }
+            try {
+                fs.closeSync(fd);
+            }
+            catch (error) {
+                resources = "close-failed";
+                errors.push(error);
+            }
+        }
+        const receipt = Object.freeze({
+            temporaryBasename: this.#name,
+            publication: state.publication,
+            status: outcome,
+            resources,
+        });
+        const error = errors.length ? failure(errors.length === 1 ? errors[0] : new AggregateError(errors, "staged cleanup failed"), { phase: "cleanup", publication: state.publication, cleanup: receipt }) : undefined;
+        this.#state = { status: "closed", receipt, error };
+        return this.#state;
+    }
+    async cleanup() {
+        const closed = this.#finalize();
+        if (closed.error) {
+            throw closed.error;
+        }
+        return closed.receipt;
+    }
+    async [Symbol.asyncDispose]() {
+        const cleanup = await this.cleanup();
+        if (cleanup.status === "preserved") {
+            throw new FsSafeError("not-removable", "staged cleanup preserved an unverified entry", {
+                details: { phase: "cleanup", publication: cleanup.publication, cleanup },
+            });
+        }
+    }
+}
+export const createNativeStage = NativeStagedFile.create;
+export const writeNativeStage = NativeStagedFile.write;

package/dist/native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmKzD,wBAAgB,0BAA0B,IAAI,aAAa,CAE1D;AAED,wBAAgB,8BAA8B,IAAI;IAChD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC,CAMA;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,UAAQ,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAkB5D;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAQpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAK1E;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsKzD,wBAAgB,0BAA0B,IAAI,aAAa,CAE1D;AAED,wBAAgB,8BAA8B,IAAI;IAChD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC,CAMA;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,UAAQ,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAkB5D;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAQpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAK1E;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}