@openclaw/fs-safe 0.18.1 → 0.19.0

package/dist/file-store.js

@@ -3,7 +3,7 @@ import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
-import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, literalStoreRootPath, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -61,7 +61,7 @@ function handleSyncStoreReadOpenFailure(opened) {
     });
 }
 async function copyIntoRoot(params) {
-    const relativePath = assertRelativePath(params.relativePath);
+    const relativePath = params.relativePath;
     const destination = resolveStorePath(params.rootDir, relativePath);
     assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
     const sourceStat = syncFs.lstatSync(params.sourcePath);
@@ -75,7 +75,7 @@ async function copyIntoRoot(params) {
         maxBytes: params.maxBytes,
     });
     await ensureParentInRoot(scopedRoot, relativePath, params.dirMode);
-    await scopedRoot.copyIn(relativePath, params.sourcePath, {
+    await scopedRoot.copyIn(literalStoreRootPath(relativePath), params.sourcePath, {
         durable: params.durable,
         maxBytes: params.maxBytes,
         mkdir: false,
@@ -97,8 +97,7 @@ export function fileStore(options) {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
     }
     async function write(relativePath, data, writeOptions) {
-        const safeRelativePath = assertRelativePath(relativePath);
-        const destination = resolveStorePath(rootDir, safeRelativePath);
+        const destination = resolveStorePath(rootDir, relativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
         const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
         assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
@@ -121,8 +120,8 @@ export function fileStore(options) {
             dirMode: writeDirMode,
             maxBytes: writeMaxBytes,
         });
-        await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
-        await scopedRoot.write(safeRelativePath, content, {
+        await ensureParentInRoot(scopedRoot, relativePath, writeDirMode);
+        await scopedRoot.write(literalStoreRootPath(relativePath), content, {
             mkdir: false,
             mode: writeMode,
             durable: writeDurable,
@@ -135,8 +134,7 @@ export function fileStore(options) {
         root: openRoot,
         write,
         writeStream: async (relativePath, stream, writeOptions) => {
-            const safeRelativePath = assertRelativePath(relativePath);
-            const destination = resolveStorePath(rootDir, safeRelativePath);
+            const destination = resolveStorePath(rootDir, relativePath);
             const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
             const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
             if (privateMode) {
@@ -172,7 +170,7 @@ export function fileStore(options) {
             try {
                 await copyIntoRoot({
                     rootDir,
-                    relativePath: safeRelativePath,
+                    relativePath,
                     sourcePath: staged.path,
                     durable: writeDurable,
                     maxBytes: limit,
@@ -214,17 +212,17 @@ export function fileStore(options) {
                 tempPrefix: writeOptions?.tempPrefix,
             });
         },
-        open: async (relativePath, readOptions) => await (await openRoot()).open(assertRelativePath(relativePath), readOptions),
-        read: async (relativePath, readOptions) => await (await openRoot()).read(assertRelativePath(relativePath), readOptions),
-        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(assertRelativePath(relativePath), readOptions),
+        open: async (relativePath, readOptions) => await (await openRoot()).open(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        read: async (relativePath, readOptions) => await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
         readText: async (relativePath, readOptions) => {
             const { encoding = "utf8", ...options } = readOptions ?? {};
-            return (await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+            return (await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
                 .toString(encoding);
         },
         readTextIfExists: async (relativePath, readOptions) => {
             try {
-                return await (await openRoot()).readText(assertRelativePath(relativePath), readOptions);
+                return await (await openRoot()).readText(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
             }
             catch (error) {
                 if (isNotFound(error)) {
@@ -235,12 +233,12 @@ export function fileStore(options) {
         },
         readJson: async (relativePath, readOptions) => {
             const { encoding = "utf8", ...options } = readOptions ?? {};
-            return JSON.parse((await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+            return JSON.parse((await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
                 .toString(encoding));
         },
         readJsonIfExists: async (relativePath, readOptions) => {
             try {
-                return await (await openRoot()).readJson(assertRelativePath(relativePath), readOptions);
+                return await (await openRoot()).readJson(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
             }
             catch (error) {
                 if (isNotFound(error)) {
@@ -250,9 +248,9 @@ export function fileStore(options) {
             }
         },
         remove: async (relativePath) => {
-            await (await openRoot()).remove(assertRelativePath(relativePath));
+            await (await openRoot()).remove(literalStoreRootPath(assertRelativePath(relativePath)));
         },
-        exists: async (relativePath) => await (await openRoot()).exists(assertRelativePath(relativePath)),
+        exists: async (relativePath) => await (await openRoot()).exists(literalStoreRootPath(assertRelativePath(relativePath))),
         writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
         writeJson: async (relativePath, data, writeOptions) => {
             const trailingNewline = writeOptions?.trailingNewline;
@@ -269,7 +267,7 @@ export function fileStore(options) {
                 } : {}),
                 readIfExists: async () => {
                     try {
-                        return await (await openRoot()).readJson(assertRelativePath(relativePath));
+                        return await (await openRoot()).readJson(literalStoreRootPath(relativePath));
                     }
                     catch (error) {
                         if (isNotFound(error)) {
@@ -278,7 +276,7 @@ export function fileStore(options) {
                         throw error;
                     }
                 },
-                readRequired: async () => await (await openRoot()).readJson(assertRelativePath(relativePath)),
+                readRequired: async () => await (await openRoot()).readJson(literalStoreRootPath(relativePath)),
                 write: async (value, options) => {
                     const json = stringifyJsonDocument(value, null, 2);
                     await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`, { durable: options?.durable });

package/dist/guest-native-python.js

@@ -36,15 +36,6 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "    is_linux = sys.platform.startswith('linux')",
     "    if is_linux:",
     "        rename_fn = getattr(libc, 'renameat2', None)",
-    "        if rename_fn is None:",
-    "            os.link(",
-    "                src_basename,",
-    "                dst_basename,",
-    "                src_dir_fd=src_parent_fd,",
-    "                dst_dir_fd=dst_parent_fd,",
-    "                follow_symlinks=False,",
-    "            )",
-    "            return",
     "        flags = 1  # RENAME_NOREPLACE",
     "    elif sys.platform == 'darwin':",
     "        rename_fn = getattr(libc, 'renameatx_np', None)",
@@ -52,32 +43,33 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "    else:",
     "        rename_fn = None",
     "        flags = 0",
-    "    if rename_fn is None:",
-    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
-    "    rename_fn.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]",
-    "    rename_fn.restype = ctypes.c_int",
-    "    result = rename_fn(",
-    "        src_parent_fd,",
-    "        os.fsencode(src_basename),",
-    "        dst_parent_fd,",
-    "        os.fsencode(dst_basename),",
-    "        flags,",
-    "    )",
-    "    if result != 0:",
+    "    if rename_fn is not None:",
+    "        rename_fn.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]",
+    "        rename_fn.restype = ctypes.c_int",
+    "        result = rename_fn(",
+    "            src_parent_fd,",
+    "            os.fsencode(src_basename),",
+    "            dst_parent_fd,",
+    "            os.fsencode(dst_basename),",
+    "            flags,",
+    "        )",
+    "        if result == 0:",
+    "            return",
     "        error_code = ctypes.get_errno()",
     "        unsupported_codes = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP}",
     "        if hasattr(errno, 'EOPNOTSUPP'):",
     "            unsupported_codes.add(errno.EOPNOTSUPP)",
-    "        if is_linux and error_code in unsupported_codes:",
-    "            os.link(",
-    "                src_basename,",
-    "                dst_basename,",
-    "                src_dir_fd=src_parent_fd,",
-    "                dst_dir_fd=dst_parent_fd,",
-    "                follow_symlinks=False,",
-    "            )",
-    "            return",
-    "        raise OSError(error_code, os.strerror(error_code), dst_basename)",
+    "        if not is_linux or error_code not in unsupported_codes:",
+    "            raise OSError(error_code, os.strerror(error_code), dst_basename)",
+    "    elif not is_linux:",
+    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
+    "    os.link(",
+    "        src_basename,",
+    "        dst_basename,",
+    "        src_dir_fd=src_parent_fd,",
+    "        dst_dir_fd=dst_parent_fd,",
+    "        follow_symlinks=False,",
+    "    )",
 ].join("\n");
 export const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON = [
     "def create_exclusive(parent_fd, basename, stdin_buffer):",

package/dist/guest.js

@@ -270,13 +270,15 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "def copy_entry(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
     "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
     "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
-    "        os.mkdir(dst_basename, stat.S_IMODE(src_stat.st_mode) or 0o755, dir_fd=dst_parent_fd)",
     "        copied_children = []",
     "        src_dir_fd = None",
     "        dst_dir_fd = None",
+    "        destination_created = False",
     "        try:",
     "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
     "            src_stat = os.fstat(src_dir_fd)",
+    "            os.mkdir(dst_basename, stat.S_IMODE(src_stat.st_mode), dir_fd=dst_parent_fd)",
+    "            destination_created = True",
     "            dst_dir_fd = open_dir(dst_basename, dir_fd=dst_parent_fd)",
     "            for child in os.listdir(src_dir_fd):",
     "                copied_children.append((child, copy_entry(src_dir_fd, child, dst_dir_fd, child)))",
@@ -284,10 +286,11 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            if dst_dir_fd is not None:",
     "                os.close(dst_dir_fd)",
     "                dst_dir_fd = None",
-    "            try:",
-    "                remove_tree(dst_parent_fd, dst_basename)",
-    "            except FileNotFoundError:",
-    "                pass",
+    "            if destination_created:",
+    "                try:",
+    "                    remove_tree(dst_parent_fd, dst_basename)",
+    "                except FileNotFoundError:",
+    "                    pass",
     "            raise",
     "        finally:",
     "            if src_dir_fd is not None:",
@@ -328,30 +331,36 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            raise",
     "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
     "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
-    "        temp_dir_name = create_temp_dir(dst_parent_fd, stat.S_IMODE(src_stat.st_mode) or 0o755)",
+    "        temp_dir_name = None",
     "        copied_children = []",
     "        temp_dir_fd = None",
     "        src_dir_fd = None",
     "        try:",
-    "            temp_dir_fd = open_dir(temp_dir_name, dir_fd=dst_parent_fd)",
     "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
     "            src_stat = os.fstat(src_dir_fd)",
+    "            source_mode = stat.S_IMODE(src_stat.st_mode)",
+    "            temp_dir_name = create_temp_dir(dst_parent_fd, source_mode or 0o700)",
+    "            temp_dir_fd = open_dir(temp_dir_name, dir_fd=dst_parent_fd)",
     "            for child in os.listdir(src_dir_fd):",
     "                copied_children.append((child, copy_entry(src_dir_fd, child, temp_dir_fd, child)))",
     "            os.close(src_dir_fd)",
     "            src_dir_fd = None",
+    "            os.rename(temp_dir_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "            temp_dir_name = None",
+    "            if source_mode == 0:",
+    "                os.fchmod(temp_dir_fd, 0)",
     "            os.close(temp_dir_fd)",
     "            temp_dir_fd = None",
-    "            os.rename(temp_dir_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
     "        except Exception:",
     "            if src_dir_fd is not None:",
     "                os.close(src_dir_fd)",
     "            if temp_dir_fd is not None:",
     "                os.close(temp_dir_fd)",
-    "            try:",
-    "                remove_tree(dst_parent_fd, temp_dir_name)",
-    "            except FileNotFoundError:",
-    "                pass",
+    "            if temp_dir_name is not None:",
+    "                try:",
+    "                    remove_tree(dst_parent_fd, temp_dir_name)",
+    "                except FileNotFoundError:",
+    "                    pass",
     "            raise",
     "        remove_copied_entry(src_parent_fd, src_basename, ('dir', entry_identity(src_stat), copied_children))",
     "        os.fsync(dst_parent_fd)",

package/dist/json-durable-queue-ownership.d.ts

@@ -4,11 +4,7 @@ export type DurableQueueEntryPathsLike = {
     deliveredPath: string;
     processingPath?: string;
 };
-export type ValidatedDurableQueueEntryPaths = Readonly<{
-    jsonPath: string;
-    deliveredPath: string;
-    processingPath: string;
-}>;
+export type ValidatedDurableQueueEntryPaths = Readonly<Required<DurableQueueEntryPathsLike>>;
 export declare function validateDurableQueueEntryPaths(paths: DurableQueueEntryPathsLike): ValidatedDurableQueueEntryPaths;
 export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike, options?: {
     skipUnowned?: boolean;

package/dist/json-durable-queue.d.ts

@@ -1,4 +1,3 @@
-export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
 export type JsonDurableQueueEntryPaths = {
     jsonPath: string;
     deliveredPath: string;

package/dist/json-durable-queue.js

@@ -8,7 +8,6 @@ import { stringifyJsonDocument } from "./json-stringify.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { admitStandalonePublicationPath, assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
-export { DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES } from "./json-durable-queue-read.js";
 function assertSafeQueueEntryId(id) {
     assertSafePathSegment(id, { label: "queue entry id" });
 }
@@ -146,8 +145,7 @@ export async function loadPendingJsonDurableQueueEntries(options) {
             await unlinkStaleTmpBestEffort(path.join(queueDir, file), now, options.cleanupTmpMaxAgeMs);
         }
     }
-    const ids = [];
-    const seenIds = new Set();
+    const ids = new Set();
     for (const file of files) {
         const suffix = file.endsWith(".processing")
             ? ".processing"
@@ -163,10 +161,7 @@ export async function loadPendingJsonDurableQueueEntries(options) {
         catch {
             continue;
         }
-        if (seenIds.has(id))
-            continue;
-        seenIds.add(id);
-        ids.push(id);
+        ids.add(id);
     }
     const entries = [];
     for (const id of ids) {

package/dist/local-file-descriptor.d.ts

@@ -1,16 +1,13 @@
 import type { BigIntStats, Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
-import type { HardlinkPolicy } from "./root-options.js";
-import type { SymlinkPolicy } from "./root-symlink-policy.js";
+import type { RootReadOptions } from "./root-options.js";
 type OwnedLocalFile = {
     handle: FileHandle;
     stat: Stats;
     identity: BigIntStats;
     preOpenStat: BigIntStats | undefined;
 };
-export declare function openLocalFileDescriptor(filePath: string, options?: {
-    hardlinks?: HardlinkPolicy;
-    symlinks?: SymlinkPolicy;
+export declare function openLocalFileDescriptor(filePath: string, options?: Pick<RootReadOptions, "hardlinks" | "symlinks"> & {
     readWrite?: true;
 }): Promise<OwnedLocalFile>;
 export {};

package/dist/local-roots.d.ts

@@ -1,4 +1,4 @@
-import { type HardlinkPolicy, type ReadResult, type SymlinkPolicy } from "./root.js";
+import { type ReadResult, type RootReadOptions } from "./root.js";
 export type LocalRootsPathResult = {
     path: string;
     root: string;
@@ -15,11 +15,6 @@ export type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
     allowMissing?: boolean;
     requireFile?: boolean;
 };
-export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
-    hardlinks?: HardlinkPolicy;
-    maxBytes?: number;
-    nonBlockingRead?: boolean;
-    symlinks?: SymlinkPolicy;
-};
+export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & RootReadOptions;
 export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
 export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;

package/dist/native-binding.d.ts

@@ -1,6 +1,7 @@
 import type { TarMeterLimits } from "./archive-limits.js";
 import type { ArchiveMemberKind } from "./archive-plan.js";
 import type { CopyCloneMode } from "./copy-policy.js";
+import type { WindowsAceFlags } from "./owner-dacl.js";
 export interface NativeFileHash {
     bytes: number;
     digest: string;
@@ -58,16 +59,7 @@ export interface NativeWindowsAccessControlEntry {
     sid: string;
     mask: number;
     aceType: string;
-    flags: {
-        raw: number;
-        objectInherit: boolean;
-        containerInherit: boolean;
-        noPropagateInherit: boolean;
-        inheritOnly: boolean;
-        inherited: boolean;
-        successfulAccess: boolean;
-        failedAccess: boolean;
-    };
+    flags: WindowsAceFlags;
 }
 export interface NativeWindowsSecurityFacts {
     ownerSid: string;
@@ -96,6 +88,12 @@ export interface NativeWindowsDirectoryReceipt {
 export interface NativeDarwinAclFacts {
     state: "absent" | "empty" | "present";
 }
+type NativeTwoPathArgs = [
+    sourceRootFd: number,
+    sourceRelPath: string,
+    targetRootFd: number,
+    targetRelPath: string
+];
 export interface NativeBinding {
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
@@ -141,7 +139,7 @@ export interface NativeBinding {
     extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
     fstatIdentity(fd: number): NativeFileIdentity;
     inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
-    linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    linkBeneath(...args: NativeTwoPathArgs): void;
     /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
     mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
@@ -153,10 +151,11 @@ export interface NativeBinding {
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
     removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
     removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
-    renameNoReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameNoReplace(...args: NativeTwoPathArgs): void;
     /** Identity-fenced retained-directory rename capability. */
     renameNoReplaceWithIdentity?(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string, expectedSourceDev: bigint, expectedSourceIno: bigint): void;
-    renameReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameReplace(...args: NativeTwoPathArgs): void;
     sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
 }
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
+export {};

package/dist/permission-exec.d.ts

@@ -7,6 +7,12 @@ export type PermissionCommandFailure = {
     signal: string | null;
     stderr: string;
 };
+export type PermissionFailureFields = {
+    error?: string;
+    errorDetail?: PermissionCommandFailure;
+    /** Original inspection failure, retained separately from serializable diagnostics. */
+    errorCause?: unknown;
+};
 export declare function formatPermissionErrorDetail(value: string): string;
 /** Formats only caught permission-query failures without invoking user code. */
 export declare function formatCaughtPermissionFailure(error: unknown): string;

package/dist/permissions-public.d.ts

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

package/dist/permissions-windows.d.ts

@@ -1,4 +1,4 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
@@ -13,16 +13,13 @@ export type WindowsAclEntry = {
     canRead: boolean;
     canWrite: boolean;
 };
-export type WindowsAclSummary = {
+export type WindowsAclSummary = Omit<PermissionFailureFields & {
     ok: boolean;
     entries: WindowsAclEntry[];
     untrustedWorld: WindowsAclEntry[];
     untrustedGroup: WindowsAclEntry[];
     trusted: WindowsAclEntry[];
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsUserInfoProvider = () => {
     username?: string | null;
 };

package/dist/permissions.d.ts

@@ -1,9 +1,6 @@
-import type { PermissionCommandFailure } from "./permission-exec.js";
+import type { PermissionFailureFields } from "./permission-exec.js";
 import { type PermissionExec } from "./permissions-windows.js";
-export type { PermissionCommandFailure } from "./permission-exec.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
-export type { IcaclsResetCommandOptions, PermissionExec, WindowsAclEntry, WindowsAclSummary, WindowsUserInfoProvider, } from "./permissions-windows.js";
-export type PermissionCheck = {
+export type PermissionCheck = Omit<PermissionFailureFields & {
     ok: boolean;
     isSymlink: boolean;
     isDir: boolean;
@@ -21,11 +18,7 @@ export type PermissionCheck = {
     /** Owner-query failure detail when Windows ownership could not be verified. */
     ownerError?: string;
     aclSummary?: string;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    /** Original inspection failure, retained separately from serializable diagnostics. */
-    errorCause?: unknown;
-};
+}, never>;
 export type PermissionCheckOptions = {
     platform?: NodeJS.Platform;
     env?: NodeJS.ProcessEnv;

package/dist/permissions.js

@@ -1,7 +1,6 @@
 import fsSync from "node:fs";
 import { formatIcaclsResetCommand, inspectWindowsPermissions, } from "./permissions-windows.js";
 import { hasWindowsPathAlias, pathForWindowsFilesystem, } from "./windows-path-alias.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
 function failedSafeStat(error) {
     return {
         ok: false,

package/dist/pinned-mutation-shared-route.d.ts

@@ -1,14 +1,9 @@
-import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { PinnedMutationPolicySnapshot } from "./pinned-mutation-admission.js";
 import type { RootBoundaryIdentity } from "./root-boundary.js";
-import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type ExactRootIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
-type SharedMutationPolicy = Readonly<{
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}>;
 export declare function ordinaryWindowsSegments(relativePath: string): boolean;
 export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
 export declare function simpleSharedRoute(params: {
@@ -16,9 +11,8 @@ export declare function simpleSharedRoute(params: {
     rootIdentity?: RootBoundaryIdentity;
     originalPath?: string;
     selectedTarget: string;
-    policy: SharedMutationPolicy;
+    policy: PinnedMutationPolicySnapshot;
 }): {
     route: string;
     rootIdentity: ExactRootIdentity;
 } | undefined;
-export {};

package/dist/pinned-open.d.ts

@@ -18,6 +18,7 @@ export type PinnedOpenSyncFinalAdmission = (params: {
     descriptorIdentity: fs.BigIntStats;
 }) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
+export declare function isExpectedPathError(error: unknown): boolean;
 export declare function openPinnedFileSync(params: {
     filePath: string;
     resolvedPath?: string;

package/dist/pinned-open.js

@@ -5,7 +5,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
-function isExpectedPathError(error) {
+export function isExpectedPathError(error) {
     const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
     return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
 }

package/dist/replace-directory.js

@@ -6,7 +6,7 @@ import { assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryId
 import { FsSafeError } from "./errors.js";
 import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, } from "./native-rename-outcome.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
-import { RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
+import { copyOperationalCode, RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { serializePathWrite } from "./write-queue.js";
@@ -17,30 +17,18 @@ function assertGuardsCurrent(guards) {
     for (const guard of guards)
         assertSyncDirectoryGuard(guard);
 }
-function copyOperationalCode(target, source) {
-    const code = source?.code;
-    if (typeof code === "string") {
-        Object.defineProperty(target, "code", { configurable: true, value: code });
-    }
-}
-function replacementFailure(error, message, details) {
+function replacementFailure(error, message, details, cause = error) {
     if (error instanceof FsSafeError) {
-        return new FsSafeError(error.code, message, { cause: error, details });
+        return new FsSafeError(error.code, message, { cause, details });
     }
-    const failure = new Error(message, { cause: error });
+    const failure = new Error(message, { cause });
     copyOperationalCode(failure, error);
     Object.defineProperty(failure, "details", { configurable: true, value: details });
     return failure;
 }
 function replacementAggregate(error, recoveryError, message, details) {
     const combined = new AggregateError([error, recoveryError], "directory replacement operation and recovery both failed");
-    if (error instanceof FsSafeError) {
-        return new FsSafeError(error.code, message, { cause: combined, details });
-    }
-    const failure = new Error(message, { cause: combined });
-    copyOperationalCode(failure, error);
-    Object.defineProperty(failure, "details", { configurable: true, value: details });
-    return failure;
+    return replacementFailure(error, message, details, combined);
 }
 function isMissingDirectoryEntry(error) {
     return error?.code === "ENOENT";

package/dist/replace-file-copy-fallback.d.ts

@@ -24,15 +24,8 @@ export declare function copyFallbackReplace(params: {
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
 }): Promise<void>;
-export declare function copyFallbackReplaceSync(params: {
+export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;
-    src: string;
-    dest: string;
-    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
-    restore: ReplaceFileCopyFallbackRestorePolicy;
-    maxRestoreBytes?: number;
-    expectedSourceIdentity?: BigIntStats;
     fchmodSync?: (fd: number, mode: number) => void;
-    sync: boolean;
 }): void;
 export {};