@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/native-pinned-write-windows.js

@@ -4,22 +4,21 @@ import fsSync, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, writeNativeInput, } from "./native-operations.js";
+import { captureNativeFdClose } from "./native-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
-export function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
-function closeWriteFd(fd) {
+function closeWriteFd(closeFd, fd) {
     if (fd === undefined)
         return;
     try {
-        fsSync.closeSync(fd);
+        closeFd(fd);
     }
     catch (error) {
         return error;
     }
 }
 export async function runPinnedWriteWindows(binding, params, root, parentFd, parentGuard) {
+    const closeFd = captureNativeFdClose(binding);
     const parentPath = parentGuard.realPath;
     let tempFd;
     let targetFd;
@@ -67,7 +66,7 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
                 syncFileBestEffortSync(targetFd);
         }
         catch (error) {
-            closeWriteFd(targetFd);
+            closeWriteFd(closeFd, targetFd);
             targetFd = undefined;
             // Staged copies and streamed creates preserve publication for caller recovery.
             if (params.input.kind === "buffer" ||
@@ -89,8 +88,8 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
         return { dev: targetIdentity.dev, ino: targetIdentity.ino };
     }
     finally {
-        const targetCloseError = closeWriteFd(targetFd);
-        const tempCloseError = closeWriteFd(tempFd);
+        const targetCloseError = closeWriteFd(closeFd, targetFd);
+        const tempCloseError = closeWriteFd(closeFd, tempFd);
         if (!renamed) {
             removeNativeCreatedFileIfStillPinned({
                 parentPath,
@@ -99,7 +98,7 @@ export async function runPinnedWriteWindows(binding, params, root, parentFd, par
                 created: tempIdentity,
             });
         }
-        const parentCloseError = closeWriteFd(parentFd);
+        const parentCloseError = closeWriteFd(closeFd, parentFd);
         await root.close().catch(() => undefined);
         const closeError = targetCloseError ?? tempCloseError ?? parentCloseError;
         if (completed && closeError !== undefined)

package/dist/native-pinned-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAK3D,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2FvH"}
+{"version":3,"file":"native-pinned-write.d.ts","sourceRoot":"","sources":["../src/native-pinned-write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAIV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAqV3B,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsGvH"}

package/dist/native-pinned-write.js

@@ -50,25 +50,295 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     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 fsSync, {} from "node:fs";
 import path from "node:path";
 import { inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { runPinnedWriteWindows, sameNativeIdentity } from "./native-pinned-write-windows.js";
+import { runPinnedWriteWindows } from "./native-pinned-write-windows.js";
+import { openNativeParentAdmission, openNativeRootAdmission } from "./native-parent-admission.js";
 import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
-import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
+function relativeParentSegments(relativeParentPath) {
+    return relativeParentPath.split("/").filter(Boolean);
+}
+function prospectiveTargetPath(parentPath, parentRoute, offset, basename) {
+    return joinPathSegmentRoute(parentPath, parentRoute, offset, basename);
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function assertDirectChildBasename(basename) {
+    if (!basename || basename === "." || basename === ".." || basename.includes("/") ||
+        basename.includes("\0") || (process.platform === "win32" && basename.includes("\\"))) {
+        throw new FsSafeError("invalid-path", "native parent creation requires one direct-child basename");
+    }
+}
+function mkdirPolicyChild(binding, parentFd, basename, mode) {
+    assertDirectChildBasename(basename);
+    const mkdirChild = binding.mkdirChildBeneath;
+    if (typeof mkdirChild === "function") {
+        const created = mkdirChild.call(binding, parentFd, basename, mode);
+        if (typeof created === "boolean")
+            return created;
+    }
+    // Old or malformed optional helpers still execute through the established
+    // recursive primitive, but cannot provide exclusive-creation provenance.
+    binding.mkdirBeneath(parentFd, basename, mode);
+    return false;
+}
+async function authorizePinnedMutation(params, request) {
+    return await params.mutationAdmission?.authorize(Object.freeze(request));
+}
+function normalizePolicyParentOpenError(error, params) {
+    if (!isSymlinkOpenError(error))
+        return error;
+    return params.mutationAdmission?.rejectParentSymlinks
+        ? new FsSafeError("symlink", "symlink path component not allowed", {
+            cause: error instanceof Error ? error : undefined,
+        })
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", {
+            cause: error instanceof Error ? error : undefined,
+        });
+}
+async function describePosixParent(parentFd, pathname) {
+    const parentPath = realpathSync.native(pathname);
+    const directory = describeStagedDirectory(parentFd, parentPath);
+    const parentPathStat = await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
+    return {
+        parentFd,
+        parentPath,
+        directory,
+        parentPathStat,
+        observation: checkedMutationDirectory(parentPath, directory.realPath, parentPathStat),
+    };
+}
+function describePolicyPosixParent(parentFd, pathname) {
+    const policyDirectory = describePolicyStagedDirectory(parentFd, pathname);
+    return {
+        parentFd,
+        parentPath: policyDirectory.directory.realPath,
+        directory: policyDirectory.directory,
+        parentPathStat: policyDirectory.stat,
+        observation: policyDirectory.observation,
+        policyDirectory,
+    };
+}
+function policyParentCaptureDeopt(error) {
+    return error instanceof FsSafeError &&
+        (error.code === "path-mismatch" || error.code === "not-file");
+}
+function tryDescribePolicyPosixParent(parentFd, pathname) {
+    try {
+        return describePolicyPosixParent(parentFd, pathname);
+    }
+    catch (error) {
+        if (!policyParentCaptureDeopt(error))
+            throw error;
+        return undefined;
+    }
+}
+function assertPosixParentCurrent(parent) {
+    return parent.policyDirectory
+        ? assertPolicyStagedDirectoryCurrent(parent.policyDirectory)
+        : assertStagedDirectoryCurrent(parent.directory);
+}
+async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryFlags) {
+    const closeFd = captureNativeFdClose(binding);
+    const segments = relativeParentSegments(params.relativeParentPath);
+    const parentSpelling = segments.length
+        ? path.join(params.rootPath, ...segments)
+        : params.rootPath;
+    const segmentRoute = createPathSegmentRoute(segments);
+    const initialTarget = prospectiveTargetPath(params.rootPath, segmentRoute, 0, params.basename);
+    let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
+    if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
+        retainedTargetPath = undefined;
+    }
+    // Preserve the one-open hot path when the complete parent still exists.
+    // Policy is attached only after the opened descriptor is associated with its
+    // current canonical pathname, so a contained redirect cannot retain the old
+    // preflight authorization.
+    let completeParentFd;
+    try {
+        completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT" || !params.mkdir)
+            throw error;
+    }
+    if (completeParentFd !== undefined) {
+        const parentFd = completeParentFd;
+        try {
+            let admitted = retainedTargetPath
+                ? tryDescribePolicyPosixParent(parentFd, parentSpelling)
+                : undefined;
+            if (!admitted) {
+                retainedTargetPath = undefined;
+                admitted = await describePosixParent(parentFd, parentSpelling);
+            }
+            const targetPath = path.join(admitted.parentPath, params.basename);
+            await authorizePinnedMutation(params, {
+                targetPath,
+                mutationPath: targetPath,
+                phase: "parent",
+            });
+            assertPosixParentCurrent(admitted);
+            return admitted;
+        }
+        catch (error) {
+            closeFd(parentFd);
+            throw error;
+        }
+    }
+    // The canonical preflight spelling has no intentional symlinks in its
+    // existing prefix. Walk missing-parent cases one direct child at a time so
+    // every existing/opened object is authorized and every mkdir is authorized
+    // before dispatch. O_NOFOLLOW makes a concurrently introduced link fail
+    // before the next component can be created through it.
+    const secureDirectoryFlags = directoryFlags | (fsSync.constants.O_NOFOLLOW ?? 0);
+    let currentFd = rootFd;
+    let currentOwnedFd;
+    let currentPath = params.rootPath;
+    let current = retainedTargetPath
+        ? tryDescribePolicyPosixParent(rootFd, currentPath)
+        : undefined;
+    if (!current) {
+        retainedTargetPath = undefined;
+        current = await describePosixParent(rootFd, currentPath);
+    }
+    try {
+        await authorizePinnedMutation(params, {
+            targetPath: retainedTargetPath ?? initialTarget,
+            mutationPath: retainedTargetPath ?? initialTarget,
+            phase: "parent",
+        });
+        assertPosixParentCurrent(current);
+        for (let index = 0; index < segments.length; index += 1) {
+            const segment = segments[index];
+            const childPath = path.join(currentPath, segment);
+            let childFd;
+            let createdByMkdir = false;
+            let createReceipt;
+            try {
+                childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+            }
+            catch (openError) {
+                if (!isNotFoundPathError(openError)) {
+                    throw normalizePolicyParentOpenError(openError, params);
+                }
+                const targetPath = retainedTargetPath ?? prospectiveTargetPath(currentPath, segmentRoute, index, params.basename);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: childPath,
+                    phase: "parent-create",
+                });
+                createReceipt = params.mutationAdmission?.tryAuthorizeAtParent?.(request, current.observation);
+                if (!createReceipt) {
+                    createReceipt = await authorizePinnedMutation(params, request);
+                    assertPosixParentCurrent(current);
+                }
+                params.assertBeforeMutation?.();
+                // Do not carry pathname freshness across the live authority callback.
+                assertPosixParentCurrent(current);
+                createdByMkdir = mkdirPolicyChild(binding, currentFd, segment, 0o777);
+                try {
+                    childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
+                }
+                catch (createdOpenError) {
+                    throw normalizePolicyParentOpenError(createdOpenError, params);
+                }
+            }
+            let child;
+            try {
+                const acceleratedChild = retainedTargetPath
+                    ? tryDescribePolicyPosixParent(childFd, childPath)
+                    : undefined;
+                if (acceleratedChild) {
+                    child = acceleratedChild;
+                }
+                else {
+                    retainedTargetPath = undefined;
+                    child = await describePosixParent(childFd, childPath);
+                }
+                if (!sameAbsolutePath(child.parentPath, childPath))
+                    retainedTargetPath = undefined;
+                let childAuthorization;
+                if (createdByMkdir && createReceipt && params.mutationAdmission?.advanceCreatedDirectory) {
+                    let evidence;
+                    try {
+                        const parent = current.policyDirectory
+                            ? refreshPolicyStagedDirectoryObservation(current.policyDirectory)
+                            : checkedMutationDirectory(currentPath, current.directory.realPath, assertStagedDirectoryCurrent(current.directory));
+                        evidence = Object.freeze({
+                            admission: createReceipt,
+                            parent,
+                            child: child.observation,
+                        });
+                    }
+                    catch {
+                        // Leave failed evidence to the full ordered admission below.
+                    }
+                    if (evidence) {
+                        childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
+                    }
+                }
+                const targetPath = retainedTargetPath ?? prospectiveTargetPath(child.parentPath, segmentRoute, index + 1, params.basename);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                childAuthorization ??= params.mutationAdmission?.tryAuthorizeAtParent?.(request, child.observation);
+                if (!childAuthorization) {
+                    await authorizePinnedMutation(params, request);
+                    assertPosixParentCurrent(child);
+                }
+            }
+            catch (error) {
+                closeFd(childFd);
+                throw error;
+            }
+            const previousOwnedFd = currentOwnedFd;
+            currentOwnedFd = child.parentFd;
+            currentFd = child.parentFd;
+            currentPath = child.parentPath;
+            current = child;
+            if (previousOwnedFd !== undefined)
+                closeFd(previousOwnedFd);
+            if (index === segments.length - 1) {
+                currentOwnedFd = undefined;
+                return child;
+            }
+        }
+        // Empty relative parents are handled by the complete-parent fast path.
+        throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+    }
+    finally {
+        if (currentOwnedFd !== undefined)
+            closeFd(currentOwnedFd);
+    }
+}
 export async function runPinnedWriteNative(binding, params) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        const closeFd = captureNativeFdClose(binding);
         const windows = process.platform === "win32";
         if (!windows) {
             assertNativeStaging(binding);
         }
         const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
-        const root = await fs.open(params.rootPath, directoryFlags);
+        const rootAdmission = await openNativeRootAdmission(binding, {
+            rootPath: params.rootPath,
+            rootIdentity: params.rootIdentity,
+            operation: "native write",
+        });
+        const root = rootAdmission.root;
         const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
         let parentFd;
         let windowsOwnsDirectories = false;
@@ -77,49 +347,42 @@ export async function runPinnedWriteNative(binding, params) {
         const parentGuard = __addDisposableResource(env_1, {
             [Symbol.dispose]() {
                 if (!windows && parentFd !== undefined) {
-                    fsSync.closeSync(parentFd);
+                    closeFd(parentFd);
                 }
             },
         }, false);
         try {
-            const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
-                ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
-            let rootMatches;
-            if (exactRoot) {
-                inspectFileIdentitySync(() => fsSync.fstatSync(root.fd, { bigint: true }), exactRoot);
-                rootMatches = true;
-            }
-            else if (windows) {
-                const identity = binding.fstatIdentity(root.fd);
-                rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
+            let parentPath;
+            let directory;
+            let parentPathStat;
+            let policyParentAdmitted = false;
+            if (!windows && params.mutationAdmission) {
+                const admitted = await capturePolicyAwarePosixParent(binding, params, root.fd, directoryFlags);
+                parentFd = admitted.parentFd;
+                parentPath = admitted.parentPath;
+                directory = admitted.directory;
+                parentPathStat = admitted.parentPathStat;
+                policyParentAdmitted = true;
             }
             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) {
-                params.assertBeforeMutation?.();
-                binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
-            }
-            parentFd = binding.openBeneath(root.fd, params.relativeParentPath, directoryFlags).fd;
-            const parentPath = realpathSync.native(params.relativeParentPath
-                ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
-                : params.rootPath);
-            const directory = windows ? undefined : describeStagedDirectory(parentFd, parentPath);
-            const parentPathStat = exactRoot
-                ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
-                : fsSync.lstatSync(parentPath);
-            if (windows && !exactRoot) {
-                const parentIdentity = binding.fstatIdentity(parentFd);
-                if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
-                    throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+                if (params.mkdir) {
+                    params.assertBeforeMutation?.();
+                    binding.mkdirBeneath(root.fd, params.relativeParentPath, 0o777);
                 }
+                const admitted = await openNativeParentAdmission(binding, rootAdmission, params.relativeParentPath);
+                parentFd = admitted.fd;
+                parentPath = admitted.guard.realPath;
+                directory = admitted.stagedDirectory;
+                parentPathStat = admitted.guard.stat;
             }
-            else if (!windows && (parentPathStat.isSymbolicLink() || !exactIdentityMatches(parentPathStat, directory.identity))) {
-                throw new FsSafeError("path-mismatch", "native write parent changed during resolution");
+            if (!policyParentAdmitted && params.mutationAdmission) {
+                const targetPath = path.join(parentPath, params.basename);
+                await authorizePinnedMutation(params, {
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
             }
             const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
             if (params.overwrite === false) {
@@ -140,12 +403,21 @@ export async function runPinnedWriteNative(binding, params) {
             }
             const ownedParent = parentFd;
             parentFd = undefined;
-            return await writeNativeStage(binding, ownedParent, directory, params, verificationGuard);
+            return await writeNativeStage(binding, ownedParent, closeFd, directory, params, verificationGuard);
         }
         finally {
             if (windows && !windowsOwnsDirectories) {
                 if (parentFd !== undefined) {
-                    fsSync.closeSync(parentFd);
+                    // Match the Windows leaf cleanup contract: an admission or identity
+                    // failure remains primary, while every owned directory is still given
+                    // a close attempt. In particular, a parent close failure must not skip
+                    // the root FileHandle close.
+                    try {
+                        closeFd(parentFd);
+                    }
+                    catch {
+                        // Best effort while propagating the operation failure.
+                    }
                 }
                 await root.close().catch(() => undefined);
             }

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

@@ -1,16 +1,16 @@
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native-binding.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, sync: boolean, assertBeforeMutation?: () => void);
-    static create(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean, sync?: boolean, assertBeforeMutation?: () => void): Promise<NativeStagedFile>;
-    static write(binding: NativeStagingBinding, parentFd: number, directory: StagedFileReceipt["directory"], params: PinnedWriteParams, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
+    constructor(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number, sync: boolean, assertBeforeMutation?: () => void);
+    static create(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean, sync?: boolean, assertBeforeMutation?: () => void): Promise<NativeStagedFile>;
+    static write(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], params: PinnedWriteParams, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
     get receipt(): StagedFileReceipt;
     assertCurrent(): Promise<void>;
     publish(basename: string, options: {

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

@@ -1 +1 @@
-{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAMlE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7E,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;;IAa1C,YACE,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,OAAO,EACb,oBAAoB,CAAC,EAAE,MAAM,IAAI,EASlC;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,EACpB,IAAI,UAAO,EACX,oBAAoB,CAAC,EAAE,MAAM,IAAI,GAChC,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,sBAAsB,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAc3B;IAED,IAAI,OAAO,IAAI,iBAAiB,CAK/B;IA8FK,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnC;IAEK,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,EAC/B,WAAW,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,GAC7C,OAAO,CAAC,oBAAoB,CAAC,CAyD/B;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;AAEvD,YAAY,EACV,oBAAoB,EAAE,UAAU,EAAE,wBAAwB,EAAE,wBAAwB,EACpF,qBAAqB,EAAE,iBAAiB,GACzC,MAAM,wBAAwB,CAAC;AAEhC,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACrC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,UAAU,CAAC,CAUtB"}
+{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"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"}

package/dist/native-staged-file.js

@@ -57,12 +57,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { MutationAuthorityError } from "./mutation-authority.js";
+import { captureNativeFdClose } from "./native-binding.js";
 import { writeNativeInput } from "./native-operations.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
 import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 export function assertNativeStaging(binding) {
     if ([
+        binding.closeOwnedFd,
         binding.createStagedFile,
         binding.stagedFileMatches,
         binding.removeStagedFile,
@@ -92,7 +94,9 @@ function failure(error, details) {
 }
 class NativeStagedFile {
     #binding;
+    #closeFd;
     #parentFd;
+    #closeParentFd;
     #directory;
     #portableNames;
     #publishedMode;
@@ -102,26 +106,29 @@ class NativeStagedFile {
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
     #rejectFinalSymlink = false;
-    constructor(binding, parentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation) {
+    constructor(binding, parentFd, closeParentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation) {
+        this.#closeFd = captureNativeFdClose(binding);
         this.#binding = binding;
         this.#parentFd = parentFd;
+        this.#closeParentFd = closeParentFd;
         this.#directory = directory;
         this.#portableNames = portableNames;
         this.#publishedMode = publishedMode;
         this.#sync = sync;
         this.#assertBeforeMutation = assertBeforeMutation;
     }
-    // Takes ownership of parentFd, including all construction and preparation failures.
-    static async create(binding, parentFd, directory, input, mode, maxBytes, 
+    // Public staging supplies a Node parent; pinned writes supply a native parent.
+    // The supplied closer owns parentFd even on construction or preparation failure.
+    static async create(binding, parentFd, closeParentFd, directory, input, mode, maxBytes, 
     // Public staging uses portable names; existing POSIX writes accept literal names.
     portableNames = true, sync = true, assertBeforeMutation) {
         let staged;
         try {
-            staged = new NativeStagedFile(binding, parentFd, directory, portableNames, mode, sync, assertBeforeMutation);
+            staged = new NativeStagedFile(binding, parentFd, closeParentFd, directory, portableNames, mode, sync, assertBeforeMutation);
         }
         catch (error) {
             try {
-                fs.closeSync(parentFd);
+                closeParentFd(parentFd);
             }
             catch (closeError) {
                 throw new AggregateError([error, closeError], "staged owner construction and close failed");
@@ -131,12 +138,12 @@ class NativeStagedFile {
         await staged.#prepare(input, maxBytes);
         return staged;
     }
-    static async write(binding, parentFd, directory, params, parentGuard) {
+    static async write(binding, parentFd, closeParentFd, 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, params.sync, params.assertBeforeMutation), true);
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, closeParentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation), true);
             staged.#rejectFinalSymlink = params.rejectFinalSymlink === true;
             if (params.input.kind === "file")
                 await params.input.verifySource();
@@ -336,12 +343,15 @@ class NativeStagedFile {
             }
         }
         let resources = "closed";
-        for (const fd of [state.fileFd, this.#parentFd]) {
+        for (const [fd, closeFd] of [
+            [state.fileFd, this.#closeFd],
+            [this.#parentFd, this.#closeParentFd],
+        ]) {
             if (fd === undefined) {
                 continue;
             }
             try {
-                fs.closeSync(fd);
+                closeFd(fd);
             }
             catch (error) {
                 resources = "close-failed";
@@ -385,5 +395,5 @@ export async function stageFileInDirectory(options) {
     const input = { kind: "buffer", data: Buffer.from(options.content) };
     const mode = options.mode ?? 0o600;
     const parent = openStagedDirectory(options.directory);
-    return await createNativeStage(binding, parent.fd, parent.receipt, input, mode);
+    return await createNativeStage(binding, parent.fd, fs.closeSync, parent.receipt, input, mode);
 }

package/dist/native.d.ts

@@ -1,4 +1,4 @@
-import type { NativeBinding } from "./native-binding.js";
+import { type NativeBinding } from "./native-binding.js";
 export type { NativeBinding } from "./native-binding.js";
 export declare function __loadBundledNativeForTest(): NativeBinding;
 export declare function __nativeLoaderDetectorsForTest(): {

package/dist/native.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAQA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAG/E,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwKzD,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,CAoB5D;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAQpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAK1E;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}

package/dist/native.js

@@ -1,6 +1,7 @@
 import { closeSync, openSync, readSync, readdirSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { FsSafeError } from "./errors.js";
+import { captureNativeFdClose } from "./native-binding.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 const require = createRequire(import.meta.url);
 let binding;
@@ -144,7 +145,9 @@ function loadBundledBinding() {
     if (!target) {
         throw new Error(`Unsupported OS or architecture: ${process.platform}-${process.arch}`);
     }
-    return require(nativePackageForTarget(target));
+    const loaded = require(nativePackageForTarget(target));
+    captureNativeFdClose(loaded);
+    return loaded;
 }
 export function __loadBundledNativeForTest() {
     return loadBundledBinding();
@@ -166,7 +169,9 @@ export function getNativeBinding() {
     if (!attempted) {
         attempted = true;
         try {
-            binding = loadBinding();
+            const loaded = loadBinding();
+            captureNativeFdClose(loaded);
+            binding = loaded;
         }
         catch (error) {
             loadError = error;

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAiDrC"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA2DrC"}