@openclaw/fs-safe 0.17.0 → 0.18.0

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

@@ -21,20 +21,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 +87,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

@@ -4,4 +4,3 @@ import type { FileIdentityStat } from "./file-identity.js";
 import type { NativeBinding } from "./native.js";
 import type { PinnedWriteParams } from "./pinned-write.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.d.ts

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

package/dist/native-pinned-write.js

@@ -66,12 +66,6 @@ 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)) === "";
 }
@@ -172,12 +166,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 +249,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 +305,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

@@ -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

@@ -8,10 +8,23 @@ import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, Staged
 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>;
@@ -30,4 +43,3 @@ export declare function stageFileInDirectory(options: {
     /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
     mode?: number;
 }): Promise<StagedFile>;
-//# sourceMappingURL=native-staged-file.d.ts.map

package/dist/native-staged-file.js

@@ -86,50 +86,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 +128,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 +190,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 +202,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 +217,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 +228,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 +270,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 +300,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 +344,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 +376,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 +386,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 +400,7 @@ class NativeStagedFile {
             }
         }
         const receipt = Object.freeze({
-            temporaryBasename: this.#name,
+            temporaryBasename: this.#owner.name,
             publication: state.publication,
             status: outcome,
             resources,
@@ -447,5 +436,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

package/dist/permission-exec.js

@@ -8,7 +8,6 @@ export function formatPermissionErrorDetail(value) {
     const formatted = formatErrorDetail(value);
     return formatted.length > 400 ? `${formatted.slice(0, 399)}…` : formatted;
 }
-const MISSING_DATA_PROPERTY = Object.freeze({ found: false });
 const MAX_CAUGHT_FAILURE_PROTOTYPES = 4;
 const primitiveString = String;
 const isUint8Array = utilTypes.isUint8Array;
@@ -36,32 +35,28 @@ function isInspectableCaughtObject(value) {
     }
 }
 function dataProperty(value, name) {
-    if (!isInspectableCaughtObject(value))
-        return MISSING_DATA_PROPERTY;
     let current = value;
     for (let depth = 0; current !== null && depth < MAX_CAUGHT_FAILURE_PROTOTYPES; depth += 1) {
         if (!isInspectableCaughtObject(current))
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         let descriptor;
         try {
             descriptor = Object.getOwnPropertyDescriptor(current, name);
         }
         catch {
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         }
         if (descriptor) {
-            return Object.hasOwn(descriptor, "value")
-                ? { found: true, value: descriptor.value }
-                : MISSING_DATA_PROPERTY;
+            return Object.hasOwn(descriptor, "value") ? descriptor : undefined;
         }
         try {
             current = Object.getPrototypeOf(current);
         }
         catch {
-            return MISSING_DATA_PROPERTY;
+            return undefined;
         }
     }
-    return MISSING_DATA_PROPERTY;
+    return undefined;
 }
 function caughtPrimitiveDisplay(value) {
     if (value !== null && (typeof value === "object" || typeof value === "function"))
@@ -78,9 +73,9 @@ export function formatCaughtPermissionFailure(error) {
     }
     const message = dataProperty(error, "message");
     const name = dataProperty(error, "name");
-    const rawMessage = message.found && typeof message.value === "string"
+    const rawMessage = typeof message?.value === "string"
         ? message.value : "";
-    const rawName = name.found && typeof name.value === "string"
+    const rawName = typeof name?.value === "string"
         ? name.value : "";
     const messageText = rawMessage.slice(0, 400);
     const nameText = rawName.slice(0, 400);
@@ -123,12 +118,11 @@ function commandFailureFields(error) {
     const signal = dataProperty(error, "signal");
     const stderr = dataProperty(error, "stderr");
     return {
-        found: killed.found || code.found || signal.found || stderr.found,
-        timedOut: killed.found && killed.value === true &&
-            signal.found && signal.value === "SIGKILL",
-        exitCode: code.found && typeof code.value === "number" ? code.value : null,
-        signal: signal.found && typeof signal.value === "string" ? signal.value : null,
-        stderr: stderr.found ? safeStderr(stderr.value) : "",
+        found: !!(killed || code || signal || stderr),
+        timedOut: killed?.value === true && signal?.value === "SIGKILL",
+        exitCode: typeof code?.value === "number" ? code.value : null,
+        signal: typeof signal?.value === "string" ? signal.value : null,
+        stderr: stderr ? safeStderr(stderr.value) : "",
     };
 }
 export class PermissionCommandError extends Error {
@@ -155,20 +149,20 @@ export class PermissionCommandError extends Error {
 export function getPermissionCommandFailure(error, command, durationMs) {
     if (isInspectableCaughtObject(error) && utilTypes.isNativeError(error)) {
         const name = dataProperty(error, "name");
-        if (name.found && name.value === "PermissionCommandError") {
+        if (name?.value === "PermissionCommandError") {
             const wrappedCommand = dataProperty(error, "command");
             const wrappedDuration = dataProperty(error, "durationMs");
             const wrappedTimedOut = dataProperty(error, "timedOut");
             const wrappedExitCode = dataProperty(error, "exitCode");
             const wrappedSignal = dataProperty(error, "signal");
             const wrappedStderr = dataProperty(error, "stderr");
-            if (wrappedCommand.found && typeof wrappedCommand.value === "string" &&
-                wrappedDuration.found && typeof wrappedDuration.value === "number" &&
+            if (typeof wrappedCommand?.value === "string" &&
+                typeof wrappedDuration?.value === "number" &&
                 Number.isSafeInteger(wrappedDuration.value) && wrappedDuration.value >= 0 &&
-                wrappedTimedOut.found && typeof wrappedTimedOut.value === "boolean" &&
-                wrappedExitCode.found && (wrappedExitCode.value === null || typeof wrappedExitCode.value === "number") &&
-                wrappedSignal.found && (wrappedSignal.value === null || typeof wrappedSignal.value === "string") &&
-                wrappedStderr.found) {
+                typeof wrappedTimedOut?.value === "boolean" &&
+                wrappedExitCode && (wrappedExitCode.value === null || typeof wrappedExitCode.value === "number") &&
+                wrappedSignal && (wrappedSignal.value === null || typeof wrappedSignal.value === "string") &&
+                wrappedStderr) {
                 return {
                     command: wrappedCommand.value,
                     durationMs: wrappedDuration.value,

package/dist/permissions-public.d.ts

@@ -1,4 +1,3 @@
 export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type PermissionCommandFailure, type SafeStatResult, } from "./permissions.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";
-//# sourceMappingURL=permissions-public.d.ts.map