@openclaw/fs-safe 0.18.1 → 0.18.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.18.2 - 2026-09-22
+
+### Fixes
+
+- **Lock errors:** preserve Root stale-removal rejections and `null` or `undefined` retry failures instead of masking them with timeouts or `TypeError`s. ([#624](https://github.com/openclaw/fs-safe/pull/624))
+- **Secret-file reads:** report caught `null` or `undefined` inspection and read failures as structured errors instead of internal `TypeError`s. ([#623](https://github.com/openclaw/fs-safe/pull/623))
+- **Secret-file creation:** preserve `null` or `undefined` thrown by parameter getters instead of masking them with an internal `TypeError`. ([#625](https://github.com/openclaw/fs-safe/pull/625))
+
 ## 0.18.1 - 2026-09-22
 
 ### Fixes

package/dist/advanced.d.ts

@@ -33,4 +33,5 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
+export type { PermissionCommandFailure } from "./permission-exec.js";

package/dist/advanced.js

@@ -35,4 +35,4 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";

package/dist/archive-merge.js

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";

package/dist/archive-staging.d.ts

@@ -3,7 +3,6 @@ import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
 export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
 export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
@@ -29,5 +28,5 @@ export declare function withStagedArchiveDestination<T>(params: {
     stagingDirPrefix?: string;
     run: (stagingDir: string) => Promise<T>;
 }): Promise<T>;
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+export {};

package/dist/archive-staging.js

@@ -21,7 +21,6 @@ const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
     deadline?.check();
 }
-export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
 }
@@ -302,7 +301,6 @@ export async function withStagedArchiveDestination(params) {
         }
     }
 }
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export function createArchiveSymlinkTraversalError(originalPath) {
     return symlinkTraversalError(originalPath);
 }

package/dist/archive-zip-preflight.d.ts

@@ -1,5 +1,3 @@
 import { type ArchiveExtractLimits } from "./archive-limits.js";
 import { type ZipArchiveWithFiles } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
-export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;

package/dist/archive-zip-preflight.js

@@ -1,7 +1,6 @@
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 export async function loadZipArchiveWithPreflight(buffer, limits) {
     const resolvedLimits = resolveExtractLimits(limits);
     if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {

package/dist/archive.d.ts

@@ -6,10 +6,13 @@ export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./ar
 export { readArchiveEntry } from "./archive-read.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.js";
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";
-export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
-export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
+export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
 export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
 export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;

package/dist/archive.js

@@ -29,10 +29,12 @@ export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, } from "./archive-limits.js";
 export { ArchiveFormatError } from "./archive-errors.js";
-export { ArchiveSecurityError } from "./archive-staging.js";
-export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { ArchiveSecurityError } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export { createTarEntryPreflightChecker } from "./archive-plan.js";
-export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, } from "./archive-zip-preflight.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |

package/dist/directory-guard.d.ts

@@ -36,7 +36,6 @@ export declare function createNearestExistingDirectoryGuard(rootReal: string, ta
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
-export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
 export declare function inspectDirectoryIdentity(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): Promise<BigIntStats>;
 export declare function observeDirectoryIdentitySync(dir: string, options: {
     bigint: true;

package/dist/directory-guard.js

@@ -84,9 +84,6 @@ function assertDirectoryGuard(guard, mode) {
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
     return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
 }
-export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
-    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
-}
 function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
     assertNoWindowsPathAlias(rootReal, "filesystem");
     assertNoWindowsPathAlias(targetPath, "filesystem");

package/dist/directory-mode-node.d.ts

@@ -1,5 +1,23 @@
-import { type BigIntStats } from "node:fs";
-import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+import { type BigIntStats, type Stats } from "node:fs";
+export type DirectoryModeChecks = {
+    check?: () => void;
+    beforeChmod?: () => Promise<void>;
+};
+export type DirectoryModeOwner = {
+    verify(check?: () => void): Promise<void>;
+    apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
+    close(): Promise<void>;
+};
+export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actual: Stats | BigIntStats): void;
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export declare function ownDirectoryMode(params: {
+    inspect: () => Promise<number>;
+    chmod: (mode: number) => Promise<void>;
+    prepareChmod?: () => Promise<void>;
+    verifyChmod?: () => Promise<void>;
+    close: () => Promise<void>;
+    ignoreChmodError?: boolean;
+}): DirectoryModeOwner;
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export declare function nodeDarwinDirectoryMetadataFlags(): number;
 export declare function nodeDirectorySearchOnlyFlags(): {

package/dist/directory-mode-node.js

@@ -3,7 +3,83 @@ import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function assertOwnedDirectory(expected, actual) {
+    if (actual.isSymbolicLink() || !actual.isDirectory()) {
+        throw new FsSafeError("not-file", "directory mode target must be a real directory");
+    }
+    if (!sameFileIdentityForCleanup(expected, actual)) {
+        throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+    }
+}
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export function ownDirectoryMode(params) {
+    let pending = Promise.resolve();
+    let closing;
+    const enqueue = (run) => {
+        if (closing)
+            return Promise.reject(new FsSafeError("path-mismatch", "directory mode owner is closed"));
+        const operation = pending.then(run);
+        pending = operation.catch(() => undefined);
+        return operation;
+    };
+    return {
+        verify: (check) => enqueue(async () => {
+            check?.();
+            await params.inspect();
+            check?.();
+        }),
+        apply: (mode, checks = {}) => enqueue(async () => {
+            // inspect() reports permission bits only; chmod ignores file-type bits,
+            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
+            mode &= 0o7777;
+            checks.check?.();
+            const currentMode = await params.inspect();
+            checks.check?.();
+            if (currentMode === mode && !checks.beforeChmod && !checks.check)
+                return;
+            if (currentMode !== mode) {
+                await params.prepareChmod?.();
+                checks.check?.();
+            }
+            await checks.beforeChmod?.();
+            checks.check?.();
+            // Hooks/ancestor checks can yield; recheck the original named association.
+            await params.inspect();
+            checks.check?.();
+            let dispatchDeadlineFailure;
+            if (currentMode !== mode) {
+                checks.check?.();
+                try {
+                    await params.chmod(mode);
+                }
+                catch (error) {
+                    if (!params.ignoreChmodError)
+                        throw error;
+                }
+                // Expiry cannot release the fd while post-dispatch verification is pending.
+                try {
+                    checks.check?.();
+                }
+                catch (error) {
+                    dispatchDeadlineFailure = { error };
+                }
+                await params.verifyChmod?.();
+            }
+            const finalMode = await params.inspect();
+            if (dispatchDeadlineFailure)
+                throw dispatchDeadlineFailure.error;
+            checks.check?.();
+            if (!params.ignoreChmodError && finalMode !== mode) {
+                throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+            }
+        }),
+        close() {
+            closing ??= pending.then(params.close);
+            return closing;
+        },
+    };
+}
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export function nodeDarwinDirectoryMetadataFlags() {
     if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {

package/dist/file-lock-sync-acquisition.js

@@ -66,7 +66,7 @@ export class SyncLockAcquisition {
         }
         catch (waitError) {
             // Exhausted backoff must preserve the filesystem denial diagnosis.
-            if (waitError.code === "file_lock_timeout")
+            if (waitError?.code === "file_lock_timeout")
                 throw error;
             throw waitError;
         }

package/dist/file-lock-sync-root-options.d.ts

@@ -1,19 +1,11 @@
 import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
-import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
-type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<{
-    compromiseCheckIntervalMs?: number;
-    lockPath?: string;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<Pick<FileLockSyncAcquireOptions<TPayload>, "compromiseCheckIntervalMs" | "lockPath" | "onCompromised" | "parsePayload" | "payload" | "reentrantOwner" | "staleRecovery" | "timeoutMs"> & {
     optionsReceiver: FileLockSyncAcquireOptions<TPayload>;
-    parsePayload?: (raw: string) => unknown;
-    payload: () => TPayload;
-    reentrantOwner?: string;
     retry: Readonly<SidecarLockRetryOptions>;
     shouldReclaim?: FileLockSyncAcquireOptions<TPayload>["shouldReclaim"];
     shouldRemoveStaleLock?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
     staleMs: number;
-    staleRecovery?: SidecarLockStaleRecovery;
-    timeoutMs?: number;
 }>;
 export declare function captureRootSyncAcquireOptions<TPayload extends Record<string, unknown>>(options: FileLockSyncAcquireOptions<TPayload>): CapturedRootSyncAcquireOptions<TPayload>;
 export {};

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" });
 }

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-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 {};

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

@@ -1,6 +1,6 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+import { type DirectoryModeOwner } from "./directory-mode-node.js";
 type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
 type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
 export type SyncFchmod = (fd: number, mode: number) => void;
@@ -12,11 +12,8 @@ export declare function pinDirectoryForMode(params: {
     /** Compatibility for best-effort directory modes; admission and close still fail closed. */
     ignoreChmodError?: boolean;
 }): Promise<DirectoryModeOwner | undefined>;
-export declare function applyDirectoryMode(params: {
-    fsModule: AsyncTempFileSystem;
-    dirPath: string;
+export declare function applyDirectoryMode(params: Parameters<typeof pinDirectoryForMode>[0] & {
     mode: number;
-    ignoreChmodError?: boolean;
 }): Promise<void>;
 export declare function applyDirectoryModeSync(params: {
     fsModule: SyncTempFileSystem;
@@ -35,14 +32,9 @@ export declare function writeTempFile(params: {
     handle: FileHandle;
     identity: BigIntStats;
 }>;
-export declare function writeTempFileSync(params: {
+export declare function writeTempFileSync(params: Omit<Parameters<typeof writeTempFile>[0], "fsModule"> & {
     fsModule: SyncTempFileSystem;
-    tempPath: string;
-    content: string | Uint8Array;
-    mode: number;
     fchmodSync?: SyncFchmod;
-    sync: boolean;
-    onIdentity?: (identity: BigIntStats) => void;
 }): {
     fd: number;
     identity: BigIntStats;

package/dist/replace-file-descriptor.js

@@ -3,7 +3,7 @@ import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { ownDirectoryMode } from "./directory-mode-owner.js";
+import { ownDirectoryMode } from "./directory-mode-node.js";
 export async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
     try {

package/dist/retained-directory-replacement.d.ts

@@ -6,6 +6,7 @@ export type RetainedReplacementParent = Readonly<{
     realPath: string;
     identity: Pick<BigIntStats, "dev" | "ino">;
 }>;
+export declare function copyOperationalCode(target: Error, source: unknown): void;
 export declare class RetainedDirectoryReplacement {
     #private;
     private constructor();

package/dist/retained-directory-replacement.js

@@ -7,7 +7,7 @@ function helperUnavailable(message, cause) {
         ...(cause instanceof Error ? { cause } : {}),
     });
 }
-function copyOperationalCode(target, source) {
+export function copyOperationalCode(target, source) {
     const code = source?.code;
     if (typeof code === "string") {
         Object.defineProperty(target, "code", { configurable: true, value: code });

package/dist/root-file-final-admission.d.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+import { type PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
 export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
 type ExactIdentity = Readonly<{
     dev: bigint;

package/dist/root-file-final-admission.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
+import { isExpectedPathError } from "./pinned-open.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { hardlinkedPathNotAllowedError } from "./root-errors.js";
@@ -8,12 +9,6 @@ import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-pa
 function rootIdentityMismatch(cause) {
     return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
 }
-function isExpectedPathError(error) {
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
-}
 function inspectCanonicalRoot(ioFs, rootPath, expected) {
     try {
         assertNoWindowsPathAlias(rootPath);

package/dist/root-file.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveRootPathSyncWithCanonicalRootObservation, resolveRootPathWithCanonicalRootObservation, } from "./root-path.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
-import { openPinnedFileSync, } from "./pinned-open.js";
+import { isExpectedPathError, openPinnedFileSync, } from "./pinned-open.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { FsSafeError } from "./errors.js";
 import { createRootFileFinalAdmission, observeCanonicalRoot, } from "./root-file-final-admission.js";
@@ -198,10 +198,7 @@ function snapshotAsyncResolution(params, absolutePath) {
 function toRootObservationError(error) {
     if (error instanceof FsSafeError)
         return toBoundaryValidationError(error);
-    const code = typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : "";
-    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
+    if (isExpectedPathError(error)) {
         return { ok: false, reason: "path", error };
     }
     return { ok: false, reason: "io", error };