@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/move-path.js

@@ -10,8 +10,7 @@ import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { createMoveStageOwner } from "./move-path-stage.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function moveCopyFallbackReasonForRenameError(error, platform = process.platform) {
     const code = error?.code;
     if (code === "EXDEV") {

package/dist/mutation-authority.d.ts

@@ -6,4 +6,3 @@ export declare class MutationAuthorityError extends FsSafeError {
 export declare function assertSynchronousCallbackResult(returned: unknown, name: string): void;
 export declare function composeMutationAssertions(defaultAssertion?: () => void, callAssertion?: () => void): (() => void) | undefined;
 export declare function rethrowMutationAuthorityError(error: unknown): never;
-//# sourceMappingURL=mutation-authority.d.ts.map

package/dist/native-binding.d.ts

@@ -160,4 +160,3 @@ export interface NativeBinding {
     sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
 }
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
-//# sourceMappingURL=native-binding.d.ts.map

package/dist/native-config.d.ts

@@ -14,4 +14,3 @@ export declare function configureFsSafeNative(config: Partial<FsSafeNativeConfig
 export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
 export declare function getFsSafeNativeConfig(): FsSafeNativeConfig;
 export declare function __resetFsSafeNativeConfigForTest(): void;
-//# sourceMappingURL=native-config.d.ts.map

package/dist/native-directory-observation.d.ts

@@ -14,4 +14,3 @@ export declare function getNativeDirectoryObservationBackend(enabled?: boolean):
 export declare function inspectNativeDirectoryObservation(backend: NativeDirectoryObservationBackend, pathname: string, expected?: ExactStatIdentity, platform?: NodeJS.Platform): NativeDirectoryObservation;
 export declare function extendNativeDirectoryObservationGuard(observation: NativeDirectoryObservation, dir: string): NativeDirectoryObservationGuard;
 export declare function isNativeDirectoryObservationGuard(guard: unknown): guard is NativeDirectoryObservationGuard;
-//# sourceMappingURL=native-directory-observation.d.ts.map

package/dist/native-fallback-warning.d.ts

@@ -1,4 +1,3 @@
 /** Warn once per capability, without including caller paths or native error text. */
 export declare function warnNativeFallback(feature: string, limitation: string): void;
 export declare function __resetNativeFallbackWarningsForTest(): void;
-//# sourceMappingURL=native-fallback-warning.d.ts.map

package/dist/native-operations.d.ts

@@ -1,10 +1,7 @@
-import { type BigIntStats, type Stats } from "node:fs";
-import type { ContainmentGuarantee } from "./containment.js";
+import { type BigIntStats } from "node:fs";
 export type NativeFileHandle = {
     readonly fd: number;
-    readonly containment: ContainmentGuarantee;
     close(): Promise<void>;
-    stat(): Promise<Stats>;
     writeFile(data: string | Buffer, encoding?: BufferEncoding): Promise<void>;
 };
 export declare function nativeOpenFlags(flags: number): number;
@@ -16,4 +13,3 @@ export declare function removeNativeCreatedFileIfStillPinned(params: {
     created?: BigIntStats;
 }): void;
 export declare function createNativeExclusiveFile(targetPath: string, mode: number): Promise<NativeFileHandle | undefined>;
-//# sourceMappingURL=native-operations.d.ts.map

package/dist/native-operations.js

@@ -1,7 +1,6 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
@@ -21,20 +20,16 @@ export function writeNativeFd(fd, data) {
         offset += written;
     }
 }
-function wrapNativeFd(fd, containment, closeFd) {
+function wrapNativeFd(fd, closeFd) {
     let open = true;
     return {
         fd,
-        containment,
         async close() {
             if (open) {
                 open = false;
                 closeFd(fd);
             }
         },
-        async stat() {
-            return fsSync.fstatSync(fd);
-        },
         async writeFile(data, encoding) {
             writeNativeFd(fd, Buffer.isBuffer(data) ? data : Buffer.from(data, encoding ?? "utf8"));
         },
@@ -91,7 +86,7 @@ export async function createNativeExclusiveFile(targetPath, mode) {
         fd = opened.fd;
         fsSync.fchmodSync(fd, mode);
         created = fsSync.fstatSync(fd, { bigint: true });
-        return wrapNativeFd(fd, opened.containment, closeFd);
+        return wrapNativeFd(fd, closeFd);
     }
     catch (error) {
         if (fd !== undefined) {

package/dist/native-parent-admission.d.ts

@@ -32,4 +32,3 @@ export declare function openNativeParentAdmission(binding: NativeBinding, rootAd
     root: Pick<FileHandle, "fd">;
 }, relativeParentPath: string, observation?: "native-directory"): Promise<NativeParentAdmission>;
 export {};
-//# sourceMappingURL=native-parent-admission.d.ts.map

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

@@ -2,6 +2,5 @@ import type { FileHandle } from "node:fs/promises";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
-//# sourceMappingURL=native-pinned-write-windows.d.ts.map

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

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import fsSync, {} from "node:fs";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { hasPreservedCreationArtifacts } from "./creation-file-state.js";
+import { hasPreservedCreationArtifacts } from "./creation-boundary.js";
 import { assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { nativeOpenFlags, removeNativeCreatedFileIfStillPinned, } from "./native-operations.js";

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

@@ -1,5 +1,4 @@
 import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 export declare function runPinnedWriteNative(binding: NativeBinding, params: PinnedWriteParams): Promise<FileIdentityStat>;
-//# sourceMappingURL=native-pinned-write.d.ts.map

package/dist/native-pinned-write.js

@@ -63,15 +63,10 @@ import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observa
 import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { errorCauseOptions } from "./root-errors.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)) === "";
 }
@@ -101,12 +96,8 @@ 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,
-        });
+        ? new FsSafeError("symlink", "symlink path component not allowed", errorCauseOptions(error))
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", errorCauseOptions(error));
 }
 async function describePosixParent(parentFd, pathname) {
     const parentPath = realpathSync.native(pathname);
@@ -172,12 +163,12 @@ async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryF
                 observationDisposers.set(fd, dispose);
             return captured;
         };
-        const segments = relativeParentSegments(params.relativeParentPath);
+        const segments = params.relativeParentPath.split("/").filter(Boolean);
         const parentSpelling = segments.length
             ? path.join(params.rootPath, ...segments)
             : params.rootPath;
         const segmentRoute = createPathSegmentRoute(segments);
-        const initialTarget = prospectiveTargetPath(params.rootPath, segmentRoute, 0, params.basename);
+        const initialTarget = joinPathSegmentRoute(params.rootPath, segmentRoute, 0, params.basename);
         let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
         if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
             retainedTargetPath = undefined;
@@ -255,7 +246,7 @@ async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryF
                     if (!isNotFoundPathError(openError)) {
                         throw normalizePolicyParentOpenError(openError, params);
                     }
-                    const targetPath = retainedTargetPath ?? prospectiveTargetPath(currentPath, segmentRoute, index, params.basename);
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(currentPath, segmentRoute, index, params.basename);
                     const request = Object.freeze({
                         targetPath,
                         mutationPath: childPath,
@@ -311,7 +302,7 @@ async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryF
                             childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
                         }
                     }
-                    const targetPath = retainedTargetPath ?? prospectiveTargetPath(child.parentPath, segmentRoute, index + 1, params.basename);
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(child.parentPath, segmentRoute, index + 1, params.basename);
                     const request = Object.freeze({
                         targetPath,
                         mutationPath: targetPath,

package/dist/native-policy-directory-observation.d.ts

@@ -9,4 +9,3 @@ export type NativePolicyDirectoryObserver = MutationDirectoryObserver & {
 };
 /** Fresh name/metadata/canonical facts from a caller-owned POSIX descriptor. */
 export declare function nativePolicyDirectoryObserver(binding: NativeBinding | undefined, fd: number, pathname: string): NativePolicyDirectoryObserver | undefined;
-//# sourceMappingURL=native-policy-directory-observation.d.ts.map

package/dist/native-policy-parent-windows.d.ts

@@ -2,7 +2,7 @@ import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type NativeRootAdmission } from "./native-parent-admission.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
 type PolicyParent = {
     fd: number;
@@ -11,4 +11,3 @@ type PolicyParent = {
 };
 export declare function capturePolicyAwareWindowsParent(binding: NativeBinding, params: PinnedWriteParams, rootAdmission: NativeRootAdmission): Promise<PolicyParent>;
 export {};
-//# sourceMappingURL=native-policy-parent-windows.d.ts.map

package/dist/native-rename-outcome.d.ts

@@ -1,4 +1,3 @@
 export declare const NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH = "FS_SAFE_INTERNAL_RENAME_SOURCE_IDENTITY_MISMATCH";
 export type NativeRenameFailureOutcome = "uncommitted" | "indeterminate";
 export declare function classifyNativeRenameFailure(error: unknown): NativeRenameFailureOutcome;
-//# sourceMappingURL=native-rename-outcome.d.ts.map

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

@@ -3,15 +3,28 @@ import { type BigIntStats, type Stats } from "node:fs";
 import type { AnyAsyncDirectoryGuard } 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 { PinnedWriteInput, PinnedWriteParams } from "./pinned-write-types.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;
 type StagedPermissionPolicy = "private-creation" | "mode-only";
+type NativeStageOwner = Readonly<{
+    binding: NativeStagingBinding;
+    parentFd: number;
+    closeParentFd: (fd: number) => void;
+    directory: StagedFileReceipt["directory"];
+    portableNames?: boolean;
+    mode: number;
+    sync?: boolean;
+    strictFileSync?: boolean;
+    assertBeforeMutation?: () => void;
+    permissionPolicy?: StagedPermissionPolicy;
+    name?: string;
+}>;
 declare class NativeStagedFile implements StagedFile {
     #private;
-    constructor(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number, sync: boolean, assertBeforeMutation?: () => void, name?: string, strictFileSync?: boolean, permissionPolicy?: StagedPermissionPolicy);
-    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, exclusiveBasename?: string, strictFileSync?: boolean, permissionPolicy?: StagedPermissionPolicy): Promise<NativeStagedFile>;
+    constructor(owner: NativeStageOwner);
+    static create(owner: NativeStageOwner, input: PinnedWriteInput, maxBytes?: number): 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>;
@@ -23,11 +36,10 @@ declare class NativeStagedFile implements StagedFile {
 }
 export declare const createNativeStage: (...args: Parameters<typeof NativeStagedFile.create>) => Promise<StagedFile>;
 export declare const writeNativeStage: typeof NativeStagedFile.write;
-export type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt, } from "./staged-file-types.js";
 export declare function stageFileInDirectory(options: {
     directory: string | DirectoryReceipt<Stats | BigIntStats>;
     content: string | Uint8Array;
     /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
     mode?: number;
 }): Promise<StagedFile>;
-//# sourceMappingURL=native-staged-file.d.ts.map
+export {};

package/dist/native-staged-file.js

@@ -50,8 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { assertDarwinCreationAcl } from "./creation-darwin.js";
-import { assertPrivateCreationFile } from "./creation-file-state.js";
+import { assertDarwinCreationAcl, assertPrivateCreationFile } from "./creation-boundary.js";
 import { requireNativeBinding } from "./native.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { randomUUID } from "node:crypto";
@@ -86,50 +85,33 @@ function assertBasename(name, portable) {
 }
 const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
 class NativeStagedFile {
-    #binding;
+    #owner;
     #closeFd;
-    #parentFd;
-    #closeParentFd;
-    #directory;
-    #portableNames;
-    #publishedMode;
-    #sync;
-    #strictFileSync;
+    #assertBeforeMutation;
     #private;
     #verifyMode;
-    #assertBeforeMutation;
-    #name;
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
     #rejectFinalSymlink = false;
-    constructor(binding, parentFd, closeParentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation, name = `.fs-safe-${randomUUID()}.tmp`, strictFileSync = false, permissionPolicy) {
-        assertBasename(name, portableNames);
-        this.#name = name;
-        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.#strictFileSync = strictFileSync;
-        this.#private = permissionPolicy === "private-creation";
-        this.#verifyMode = permissionPolicy !== undefined;
-        this.#assertBeforeMutation = assertBeforeMutation;
+    constructor(owner) {
+        const name = owner.name ?? `.fs-safe-${randomUUID()}.tmp`;
+        assertBasename(name, owner.portableNames !== false);
+        this.#closeFd = captureNativeFdClose(owner.binding);
+        this.#owner = { ...owner, name };
+        this.#assertBeforeMutation = owner.assertBeforeMutation;
+        this.#private = owner.permissionPolicy === "private-creation";
+        this.#verifyMode = owner.permissionPolicy !== undefined;
     }
     // 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, exclusiveBasename, strictFileSync = false, permissionPolicy) {
+    static async create(owner, input, maxBytes) {
         let staged;
         try {
-            staged = new NativeStagedFile(binding, parentFd, closeParentFd, directory, portableNames, mode, sync, assertBeforeMutation, exclusiveBasename, strictFileSync, permissionPolicy);
+            staged = new NativeStagedFile(owner);
         }
         catch (error) {
             try {
-                closeParentFd(parentFd);
+                owner.closeParentFd(owner.parentFd);
             }
             catch (closeError) {
                 throw new AggregateError([error, closeError], "staged owner construction and close failed");
@@ -145,7 +127,13 @@ class NativeStagedFile {
             const exclusive = params.overwrite === false && params.input.kind === "buffer" && params.input.stageBeforePublish === false;
             // 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, closeParentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation, exclusive ? params.basename : undefined, params.strictFileSync, params.private ? "private-creation" : params.verifyPosixMode === true ? "mode-only" : undefined), true);
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create({
+                binding, parentFd, closeParentFd, directory, mode: params.mode, sync: params.sync,
+                // Public staging uses portable names; existing POSIX writes accept literal names.
+                portableNames: false, assertBeforeMutation: params.assertBeforeMutation,
+                name: exclusive ? params.basename : undefined, strictFileSync: params.strictFileSync,
+                permissionPolicy: params.private ? "private-creation" : params.verifyPosixMode === true ? "mode-only" : undefined,
+            }, params.input, params.maxBytes), true);
             staged.#rejectFinalSymlink = params.rejectFinalSymlink === true;
             if (params.input.kind === "file")
                 await params.input.verifySource();
@@ -201,7 +189,7 @@ class NativeStagedFile {
     }
     #assertNamed(name, expectedMode) {
         const fd = this.#file();
-        const stat = this.#binding.stagedFileMatches(this.#parentFd, name, fd)
+        const stat = this.#owner.binding.stagedFileMatches(this.#owner.parentFd, name, fd)
             ? fs.fstatSync(fd, { bigint: true }) : undefined;
         if (!stat || stat.nlink !== 1n) {
             throw new FsSafeError("path-mismatch", "staged entry no longer names the exclusive created file");
@@ -213,8 +201,8 @@ class NativeStagedFile {
         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, 0o600);
+        assertStagedDirectoryCurrent(this.#owner.directory);
+        this.#assertNamed(this.#owner.name, 0o600);
     }
     #assertPermissions(fd, stat, expectedMode) {
         if (this.#private)
@@ -228,7 +216,7 @@ class NativeStagedFile {
     }
     async #prepare(input, maxBytes) {
         try {
-            const mode = this.#publishedMode;
+            const mode = this.#owner.mode;
             if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
                 throw new FsSafeError("invalid-path", "invalid staged file mode");
             }
@@ -239,25 +227,25 @@ class NativeStagedFile {
                     throw new FsSafeError("helper-unavailable", "required cloning cannot verify staged permissions before copying");
                 }
             }
-            assertStagedDirectoryCurrent(this.#directory);
+            assertStagedDirectoryCurrent(this.#owner.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();
             if (this.#private)
-                assertDarwinCreationAcl(this.#parentFd, "file");
+                assertDarwinCreationAcl(this.#owner.parentFd, "file");
             this.#assertBeforeMutation?.();
             if (this.#private)
-                assertDarwinCreationAcl(this.#parentFd, "file");
+                assertDarwinCreationAcl(this.#owner.parentFd, "file");
             // Native copying populates its new file before returning its descriptor.
             const copied = input.kind === "file" && !this.#verifyMode
-                ? await createNativeCopyFile(this.#binding, input, this.#parentFd, this.#name, maxBytes, false)
+                ? await createNativeCopyFile(this.#owner.binding, input, this.#owner.parentFd, this.#owner.name, maxBytes, false)
                 : undefined;
             state.fileFd = copied?.fd;
             if (state.fileFd === undefined) {
                 this.#assertBeforeMutation?.();
                 if (this.#private)
-                    assertDarwinCreationAcl(this.#parentFd, "file");
-                state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+                    assertDarwinCreationAcl(this.#owner.parentFd, "file");
+                state.fileFd = this.#owner.binding.createStagedFile(this.#owner.parentFd, this.#owner.name);
             }
             const fd = state.fileFd;
             if (input.kind === "file")
@@ -281,14 +269,14 @@ class NativeStagedFile {
                 await writePinnedInput(fd, input, maxBytes, assertBeforeMutation);
             if (this.#verifyMode)
                 this.#assertStagePermissions(fd);
-            if (this.#sync) {
-                if (this.#strictFileSync)
+            if (this.#owner.sync !== false) {
+                if (this.#owner.strictFileSync)
                     fs.fsyncSync(fd);
                 else
                     syncFileBestEffortSync(fd);
             }
             const stat = fs.fstatSync(fd, { bigint: true });
-            this.#receipt = createStagedFileReceipt(this.#directory, this.#name, stat);
+            this.#receipt = createStagedFileReceipt(this.#owner.directory, this.#owner.name, stat);
             this.#assertCurrent();
         }
         catch (error) {
@@ -311,23 +299,23 @@ class NativeStagedFile {
         const overwrite = options?.overwrite;
         try {
             const state = this.#open();
-            assertBasename(basename, this.#portableNames);
-            if (basename === this.#name || typeof overwrite !== "boolean") {
+            assertBasename(basename, this.#owner.portableNames !== false);
+            if (basename === this.#owner.name || typeof overwrite !== "boolean") {
                 throw new FsSafeError("invalid-path", "publication needs a distinct basename and explicit overwrite policy");
             }
             this.#assertCurrent();
-            assertFinalSymlinkRejected(path.join(this.#directory.realPath, basename), this.#rejectFinalSymlink);
+            assertFinalSymlinkRejected(path.join(this.#owner.directory.realPath, basename), this.#rejectFinalSymlink);
             this.#assertBeforeMutation?.();
             if (this.#assertBeforeMutation) {
                 this.#assertCurrent();
-                assertFinalSymlinkRejected(path.join(this.#directory.realPath, basename), this.#rejectFinalSymlink);
+                assertFinalSymlinkRejected(path.join(this.#owner.directory.realPath, basename), this.#rejectFinalSymlink);
             }
             try {
                 if (overwrite) {
-                    this.#binding.renameReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                    this.#owner.binding.renameReplace(this.#owner.parentFd, this.#owner.name, this.#owner.parentFd, basename);
                 }
                 else {
-                    this.#binding.renameNoReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                    this.#owner.binding.renameNoReplace(this.#owner.parentFd, this.#owner.name, this.#owner.parentFd, basename);
                 }
             }
             catch (error) {
@@ -355,24 +343,24 @@ class NativeStagedFile {
         this.#open().publication = receipt;
         onPublished?.(receipt.staged.identity);
         const stagedMode = this.#assertNamed(basename, 0o600);
-        assertStagedDirectoryCurrent(this.#directory);
+        assertStagedDirectoryCurrent(this.#owner.directory);
         // Keep contents private until the name passes its identity fence. Mode
         // changes use the owned fd, including for final mode 000.
         const fd = this.#file();
-        if (this.#publishedMode !== 0o600 || stagedMode !== 0o600)
-            fs.fchmodSync(fd, this.#publishedMode);
+        if (this.#owner.mode !== 0o600 || stagedMode !== 0o600)
+            fs.fchmodSync(fd, this.#owner.mode);
         // Content was synced during preparation. A lost chmod leaves 0600, no wider
         // than modes retaining owner rw; restrictive modes still need a durable correction.
-        if (this.#sync && ((this.#publishedMode & 0o600) !== 0o600 || (stagedMode & ~this.#publishedMode) !== 0)) {
-            if (this.#strictFileSync)
+        if (this.#owner.sync !== false && ((this.#owner.mode & 0o600) !== 0o600 || (stagedMode & ~this.#owner.mode) !== 0)) {
+            if (this.#owner.strictFileSync)
                 fs.fsyncSync(fd);
             else
                 syncFileBestEffortSync(fd);
         }
-        if (this.#sync)
-            syncFileBestEffortSync(this.#parentFd);
-        this.#assertNamed(basename, this.#publishedMode);
-        assertStagedDirectoryCurrent(this.#directory);
+        if (this.#owner.sync !== false)
+            syncFileBestEffortSync(this.#owner.parentFd);
+        this.#assertNamed(basename, this.#owner.mode);
+        assertStagedDirectoryCurrent(this.#owner.directory);
         return receipt;
     }
     #finalize() {
@@ -387,7 +375,7 @@ class NativeStagedFile {
         }
         else if (state.publication.status === "not-published" && state.fileFd !== undefined) {
             try {
-                outcome = this.#binding.removeStagedFile(this.#parentFd, this.#name, state.fileFd);
+                outcome = this.#owner.binding.removeStagedFile(this.#owner.parentFd, this.#owner.name, state.fileFd);
             }
             catch (error) {
                 outcome = "failed";
@@ -397,7 +385,7 @@ class NativeStagedFile {
         let resources = "closed";
         for (const [fd, closeFd] of [
             [state.fileFd, this.#closeFd],
-            [this.#parentFd, this.#closeParentFd],
+            [this.#owner.parentFd, this.#owner.closeParentFd],
         ]) {
             if (fd === undefined) {
                 continue;
@@ -411,7 +399,7 @@ class NativeStagedFile {
             }
         }
         const receipt = Object.freeze({
-            temporaryBasename: this.#name,
+            temporaryBasename: this.#owner.name,
             publication: state.publication,
             status: outcome,
             resources,
@@ -447,5 +435,8 @@ 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, fs.closeSync, parent.receipt, input, mode, undefined, true, true, undefined, undefined, false, "mode-only");
+    return await createNativeStage({
+        binding, parentFd: parent.fd, closeParentFd: fs.closeSync,
+        directory: parent.receipt, mode, permissionPolicy: "mode-only",
+    }, input);
 }

package/dist/native.d.ts

@@ -11,4 +11,3 @@ export declare function getNativeBinding(): NativeBinding | undefined;
 export declare function requireNativeBinding(): NativeBinding;
 export declare function __setNativeLoaderForTest(loader: () => NativeBinding): void;
 export declare function __resetNativeLoaderForTest(): void;
-//# sourceMappingURL=native.d.ts.map

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

@@ -5,4 +5,3 @@ export declare function recordExclusiveCreateFailure(error: unknown, filePath: s
 export declare function openedPathResolutionError(error?: Error): Error;
 export declare function recordPreOpenFileChange(error: unknown, handle: FileHandle, filePath: string, before: BigIntStats | undefined, opened: BigIntStats | undefined): Promise<void>;
 export declare function recordOpenedFileFailure(error: unknown, handle: FileHandle, filePath: string, identity: BigIntStats): Promise<void>;
-//# sourceMappingURL=opened-file-failure.d.ts.map

package/dist/opened-realpath.d.ts

@@ -13,4 +13,3 @@ export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: F
     realPath: string;
     stat: Stats | BigIntStats;
 }>;
-//# sourceMappingURL=opened-realpath.d.ts.map

package/dist/output.d.ts

@@ -14,4 +14,3 @@ export type ExternalFileWriteResult<T = void> = {
     result: T;
 };
 export declare function writeExternalFileWithinRoot<T = void>(options: ExternalFileWriteOptions<T>): Promise<ExternalFileWriteResult<T>>;
-//# sourceMappingURL=output.d.ts.map

package/dist/overwrite-file-handle.d.ts

@@ -5,4 +5,3 @@ export type OverwriteFileHandleOptions = {
 };
 /** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
 export declare function overwriteFileHandle(handle: FileHandle, data: Uint8Array, options?: OverwriteFileHandleOptions): Promise<void>;
-//# sourceMappingURL=overwrite-file-handle.d.ts.map

package/dist/owner-dacl.d.ts

@@ -28,4 +28,3 @@ export type OwnerAndDaclResult = {
     platform: NodeJS.Platform;
 };
 export declare function readOwnerAndDacl(targetPath: string): OwnerAndDaclResult;
-//# sourceMappingURL=owner-dacl.d.ts.map

package/dist/path-case.d.ts

@@ -4,4 +4,3 @@ export type ProbePathCaseOptions = {
 };
 /** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
 export declare function probePathCaseInsensitiveSync(targetPath: string, options?: ProbePathCaseOptions): boolean | undefined;
-//# sourceMappingURL=path-case.d.ts.map

package/dist/path-policy.d.ts

@@ -22,4 +22,3 @@ export declare function assertNoHardlinkedFinalPath(params: {
     boundaryLabel: string;
     allowFinalHardlinkForUnlink?: boolean;
 }): Promise<void>;
-//# sourceMappingURL=path-policy.d.ts.map

package/dist/path-prefix.d.ts

@@ -4,4 +4,3 @@ export type ResolvedPathPrefix = {
     readonly unresolvedSegments: readonly string[];
 };
 export declare function resolvePathPrefixSync(input: string): ResolvedPathPrefix;
-//# sourceMappingURL=path-prefix.d.ts.map

package/dist/path-scope-lexical.d.ts

@@ -11,4 +11,3 @@ export declare function resolvePathWithinNormalizedRoot(params: ResolvePathWithi
     ok: false;
     error: string;
 };
-//# sourceMappingURL=path-scope-lexical.d.ts.map

package/dist/path-segment-route.d.ts

@@ -4,4 +4,3 @@ export type PathSegmentRoute = Readonly<{
 }>;
 export declare function createPathSegmentRoute(segments: readonly string[]): PathSegmentRoute;
 export declare function joinPathSegmentRoute(base: string, route: PathSegmentRoute, offset: number, tail?: string): string;
-//# sourceMappingURL=path-segment-route.d.ts.map

package/dist/path-suffix-aliases.d.ts

@@ -9,4 +9,3 @@ export type ProbePathSuffixAliasesOptions = {
 };
 /** Observe bounded missing suffix aliases; the caller owns caching and ambiguity policy. */
 export declare function probePathSuffixAliasesSync(options: ProbePathSuffixAliasesOptions): boolean | undefined;
-//# sourceMappingURL=path-suffix-aliases.d.ts.map

package/dist/path.d.ts

@@ -18,4 +18,3 @@ export declare function isPathInsideWithRealpath(basePath: string, candidatePath
 export declare function safeStatSync(targetPath: string): fs.Stats | null;
 export declare function splitSafeRelativePath(relativePath: string): string[];
 export declare function resolveSafeRelativePath(rootDir: string, relativePath: string): string;
-//# sourceMappingURL=path.d.ts.map

package/dist/permission-exec.d.ts

@@ -24,4 +24,3 @@ export declare function executePermissionCommand(command: string, args: string[]
     stdout: string;
     stderr: string;
 }>;
-//# sourceMappingURL=permission-exec.d.ts.map