@openclaw/fs-safe 0.18.0 → 0.18.2

package/dist/private-producer-handoff-sync.d.ts

@@ -1,13 +1,3 @@
-import { type BigIntStats } from "node:fs";
 import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
-export declare function handoffCreatedFileSync(params: {
-    source: OwnedFileDescriptorSync;
-    sourcePath: string;
-    targetPath: string;
-    identity: BigIntStats;
-    assertSourceParent: () => void;
-    assertTargetParent: () => void;
-    assertBeforeMutation?: () => void;
-    verifyDescriptor?: (fd: number, path: string, links: number) => void;
-    onPublished?: () => void;
-}): OwnedFileDescriptorSync;
+import { type CreatedHandoffParams } from "./private-producer-handoff.js";
+export declare function handoffCreatedFileSync(params: CreatedHandoffParams<OwnedFileDescriptorSync, void>): OwnedFileDescriptorSync;

package/dist/private-producer-handoff-sync.js

@@ -1,4 +1,4 @@
-import fs, {} from "node:fs";
+import fs from "node:fs";
 import { ownFileDescriptorSync } from "./create-owned-file.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { assertInitialSource, FileHandoff, inspectLinkedFile, } from "./private-producer-handoff.js";

package/dist/private-producer-handoff.d.ts

@@ -18,11 +18,11 @@ type HandoffPaths = HandoffParents & {
 type ProducerHandoffParams = HandoffPaths & {
     readWrite: boolean;
 };
-type CreatedHandoffParams = HandoffPaths & {
-    source: FileHandle;
+export type CreatedHandoffParams<TSource = FileHandle, TVerification = Promise<void>> = HandoffPaths & {
+    source: TSource;
     identity: BigIntStats;
     assertBeforeMutation?: () => void;
-    verifyDescriptor?: (fd: number, path: string, links: number) => Promise<void>;
+    verifyDescriptor?: (fd: number, path: string, links: number) => TVerification;
     onPublished?: () => void;
 };
 export declare function assertInitialSource(stat: BigIntStats): void;

package/dist/private-temp-workspace.js

@@ -12,9 +12,8 @@ import { registerTempPathForExit, } from "./temp-cleanup.js";
 import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, throwTempWorkspaceCreationFailure, } from "./temp-workspace-owner.js";
 import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
 import { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
-import { validateInitialTempWorkspaceChild } from "./temp-workspace-child-admission.js";
+import { validateInitialTempWorkspaceChild, validateTempWorkspaceDirMode } from "./temp-workspace-child-admission.js";
 import { admitTempWorkspaceRoot, admitTempWorkspaceRootSync, } from "./temp-workspace-admission.js";
-import { validateTempWorkspaceDirMode } from "./temp-workspace-permissions.js";
 function resolveTempWorkspaceCleanupSafety(value) {
     if (value === undefined || value === "compatible")
         return "compatible";

package/dist/publish-copy-stage.d.ts

@@ -1,6 +1,6 @@
 import { type BigIntStats } from "node:fs";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
-import type { PublishedWriteIdentity } from "./pinned-write.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
 export declare function publishCopyStage(params: {
     temporaryPath: string;
     targetPath: string;

package/dist/publish-file.d.ts

@@ -2,7 +2,6 @@ import { type BigIntStats, type Stats } from "node:fs";
 import { type DirectoryReceipt, type DirectorySyncOutcome } from "./directory-durability.js";
 import { type FileIdentityStat } from "./file-identity.js";
 import { type PublishFileExclusiveSyncFailurePolicy } from "./publish-file-failure.js";
-export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
 export type PublishFileExclusiveStrategy = "link-or-copy" | "link-required" | "rename-noreplace";
 export type PublishFileExclusiveResult = {
     method: "hardlink" | "exclusive-copy" | "rename-noreplace";

package/dist/publish-file.js

@@ -12,9 +12,8 @@ import { getNativeBinding, requireNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from "./publish-file-failure.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { hasErrorCode } from "./file-cleanup.js";
 import { writeAllToFile } from "./write-file-handle.js";
 const HARDLINK_FALLBACK_CODES = new Set(["EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);

package/dist/replace-directory.js

@@ -6,11 +6,10 @@ 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 } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { serializePathWrite } from "./write-queue.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 function distinctGuards(source, target) {
     return source === target ? [source] : [source, target];
 }
@@ -18,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/replace-file-rename-policy.d.ts

@@ -1,5 +1,4 @@
-import type { RenameIdentityPolicy } from "./pinned-write.js";
-export type { RenameIdentityPolicy };
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
 export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
 export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;

package/dist/replace-file.d.ts

@@ -1,7 +1,7 @@
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
-import { type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
-import { type RenameIdentityPolicy } from "./replace-file-rename-policy.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+import { type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
 export type ReplaceFileAtomicFileSystem = {
     promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
         /** @deprecated Accepted for adapter compatibility but never called. */
@@ -13,7 +13,6 @@ export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" |
     chmodSync?: typeof syncFs.chmodSync;
     fchmodSync?: typeof syncFs.fchmodSync;
 };
-export type { RenameIdentityPolicy, ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, };
 type ReplaceFileAtomicBaseOptions = {
     filePath: string;
     content: string | Uint8Array;
@@ -56,3 +55,4 @@ export type ReplaceFileAtomicResult = {
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicWithDirectorySync(options: ReplaceFileAtomicOptions, syncParent?: (directoryPath: string) => Promise<unknown>): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
+export {};

package/dist/replace-file.js

@@ -9,7 +9,7 @@ import { inheritedRegularFileMode } from "./replace-file-mode.js";
 import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
 import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 import { hasErrorCode, readErrorCode } from "./file-cleanup.js";

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-context.js

@@ -7,7 +7,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
 import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
@@ -223,14 +223,10 @@ export async function resolvePathInRoot(root, relativePath, options) {
             throw error;
         }
         if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
-            throw new FsSafeError("invalid-path", "relative path is too long", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
         }
         const code = options?.aliasErrorCode ?? "outside-workspace";
-        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
     }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }

package/dist/root-create-input.d.ts

@@ -1,4 +1,4 @@
-import type { PinnedWriteInput } from "./pinned-write.js";
+import type { PinnedWriteInput } from "./pinned-write-types.js";
 import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
 declare const exclusiveSidecarCreate: unique symbol;
 export declare const sidecarExclusiveCreate: Readonly<{

package/dist/root-directory-creation.d.ts

@@ -1,4 +1,4 @@
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
 import { type RootContext } from "./root-context.js";
 /**
  * Complete the common Root.mkdir case with one exact existing parent. This is

package/dist/root-directory-creation.js

@@ -1,7 +1,7 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertPrivateDirectory } from "./creation-permissions.js";
+import { assertPrivateDirectory } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";

package/dist/root-directory-list.js

@@ -7,7 +7,7 @@ import { FsSafeError } from "./errors.js";
 import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
-import { rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
@@ -50,9 +50,7 @@ export async function createRootDirectoryObservationGuard(root, directory) {
 function directoryChangedError(error) {
     if (error instanceof FsSafeError && error.code === "path-mismatch")
         return error;
-    return new FsSafeError("path-mismatch", "directory changed during operation", {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("path-mismatch", "directory changed during operation", errorCauseOptions(error));
 }
 export async function assertRootDirectoryObservationGuard(root, guard) {
     if (isNativeDirectoryObservationGuard(guard)) {
@@ -162,9 +160,7 @@ export function assertRootPathObservationReceiptCurrent(root, receipt, finalTarg
 }
 function normalizeDirectoryError(error) {
     if (isNotFoundPathError(error)) {
-        return new FsSafeError("not-found", "directory not found", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("not-found", "directory not found", errorCauseOptions(error));
     }
     return error;
 }

package/dist/root-entries.js

@@ -1,5 +1,5 @@
 import { FsSafeError } from "./errors.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { resolvePathInRoot } from "./root-context.js";
 import { openRootDirectoryListing } from "./root-directory-list.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
@@ -13,7 +13,7 @@ export async function* entriesInRoot(root, relativePath, options) {
         throw new TypeError(`invalid root entries order: ${String(options.order)}`);
     }
     options.signal?.throwIfAborted();
-    validatePinnedOperationPayload({ relativePath });
+    validatePinnedRelativePath(relativePath);
     const resolved = await resolvePathInRoot(root, relativePath, {
         ...readSymlinkResolution(options.symlinks),
         resolveCanonical: true,

package/dist/root-errors.d.ts

@@ -10,3 +10,7 @@ export declare function normalizePinnedPathError(error: unknown, details?: FsSaf
 export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
+/** Existing boundaries retain only Error instances as their cause. */
+export declare function errorCauseOptions(error: unknown): {
+    cause: Error | undefined;
+};

package/dist/root-errors.js

@@ -41,9 +41,7 @@ export function normalizePinnedWriteError(error) {
     const message = code
         ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
         : "path is not a regular file under root";
-    return new FsSafeError("invalid-path", message, {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("invalid-path", message, errorCauseOptions(error));
 }
 export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
@@ -88,3 +86,7 @@ export function throwFsSafeReadError(error, label) {
     }
     throw error;
 }
+/** Existing boundaries retain only Error instances as their cause. */
+export function errorCauseOptions(error) {
+    return { cause: error instanceof Error ? error : undefined };
+}

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

package/dist/root-impl.d.ts

@@ -7,13 +7,8 @@ import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
 import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
 import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
-export type { HardlinkPolicy, RootAppendOptions, RootCopyOptions, RootCopySource, RootCreateJsonOptions, RootCreateOptions, RootCreateStreamOptions, RootDefaults, RootMkdirOptions, RootMoveOptions, RootOpenOptions, RootOpenWritableOptions, RootOptions, RootReadOptions, RootRemoveOptions, RootWriteJsonOptions, RootWriteOptions, WritableOpenMode, } from "./root-options.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
-export type { DenyMutationPolicy } from "./deny-mutations.js";
-export type { RenameIdentityPolicy } from "./pinned-write.js";
-export type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
-export type { ReadResult } from "./read-opened-file.js";
 export type OpenResult = {
     handle: FileHandle;
     containment: ContainmentGuarantee;

package/dist/root-impl.js

@@ -56,7 +56,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertCopySourceCurrent, resolveFileCopyCloneMode } from "./copy-file-input.js";
-import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-permissions.js";
+import { assertPrivateFileCreationAvailable, resolveCreationPermissions } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -68,7 +68,7 @@ import { openedPathResolutionError, recordExclusiveCreateFailure, recordOpenedFi
 import { runPinnedWriteHelper, runPinnedWriteWithRenamePolicy } from "./pinned-write.js";
 import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy } from "./pinned-mutation-admission.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
@@ -86,7 +86,7 @@ import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
-import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { walkRoot } from "./root-walk.js";
@@ -304,6 +304,9 @@ export class RootHandle {
             mode: this.defaults.mode,
             renameIdentity: this.defaults.renameIdentity,
             ...this.mutationOptions(options),
+            atomic: undefined,
+            private: undefined,
+            strictFileSync: undefined,
             relativePath,
             data,
             durable: options.durable ?? this.defaults.durable ?? true,
@@ -364,18 +367,19 @@ export class RootHandle {
     }
     async stat(relativePath) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await statPathFallback(this.context, relativePath);
     }
     async list(relativePath, options = {}) {
         assertValidRootRelativePath(relativePath);
-        validatePinnedOperationPayload({ relativePath });
+        validatePinnedRelativePath(relativePath);
         return await listPathFallback(this.context, relativePath, options.withFileTypes === true);
     }
     async move(fromRelative, toRelative, options = {}) {
         assertValidRootRelativePath(fromRelative);
         assertValidRootDestinationPath(toRelative);
-        validatePinnedOperationPayload({ from: fromRelative, to: toRelative });
+        validatePinnedRelativePath(fromRelative);
+        validatePinnedRelativePath(toRelative);
         const mutationOptions = this.mutationOptions(options);
         const { assertBeforeMutation } = mutationOptions;
         const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
@@ -407,7 +411,7 @@ export class RootHandle {
             rootReal: this.context.rootReal,
             stat: relative => this.stat(relative),
             list: async (relative, listingOptions) => {
-                validatePinnedOperationPayload({ relativePath: relative });
+                validatePinnedRelativePath(relative);
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },
@@ -503,7 +507,6 @@ async function openWritableFileInRoot(root, params, options) {
         relativePath: params.relativePath, guardedTarget, mkdir: params.mkdir,
         assertBeforeMutation: params.assertBeforeMutation,
     }) : undefined;
-    const mutationAdmission = prepared?.mutationAdmission;
     const preparedParent = prepared?.preparedParent;
     let ioPath = prepared?.targetPath ?? (params.mkdir === false ? resolved :
         await prepareRootWriteTarget(root, resolved, params.assertBeforeMutation));
@@ -763,7 +766,7 @@ async function appendFileInRoot(root, params) {
     }
 }
 async function removePathInRoot(root, params) {
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    validatePinnedRelativePath(params.relativePath);
     const removalReceipts = params.recursive ? undefined : new RemovalPathReceipts();
     const resolved = await resolvePinnedPathInRoot(root, {
         relativePath: params.relativePath,
@@ -783,7 +786,7 @@ async function removePathInRoot(root, params) {
 }
 async function mkdirPathInRoot(root, params) {
     const privateMode = resolveCreationPermissions(params, true).private;
-    validatePinnedOperationPayload({ relativePath: params.relativePath });
+    validatePinnedRelativePath(params.relativePath);
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
@@ -862,7 +865,7 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             overwrite: params.overwrite,
             rejectFinalSymlink: params.mutationSymlinks !== undefined,
             input,
-            maxBytes: params.maxBytes,
+            maxBytes: input.kind === "buffer" ? undefined : params.maxBytes,
             rootIdentity: root.rootIdentity,
             mutationAdmission: pinned.mutationAdmission,
             assertBeforeMutation: params.assertBeforeMutation,
@@ -892,9 +895,7 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             throw error;
         }
         if (params.overwrite === false && isAlreadyExistsError(error)) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(error));
         }
         throw normalizePinnedWriteError(error);
     }
@@ -1173,9 +1174,7 @@ async function movePathFallback(root, params) {
             throw fileNotFoundError(error instanceof Error ? error : undefined);
         }
         if (hasNodeErrorCode(error, "EEXIST")) {
-            throw new FsSafeError("already-exists", "destination exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
         }
         throw error;
     }
@@ -1193,7 +1192,11 @@ async function writeFileFallback(root, params) {
     const policy = snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
     if (policy)
         params = { ...params, ...policy };
-    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, params);
+    const { rootReal, resolved } = await resolveGuardedWritePathInRoot(root, {
+        relativePath: params.relativePath,
+        denyMutations: params.denyMutations,
+        mutationSymlinks: params.mutationSymlinks,
+    });
     await withRootFallbackCompatibilityLock({
         rootPath: rootReal, rootIdentity: root.rootIdentity, targetPath: resolved, assertBeforeMutation: params.assertBeforeMutation,
     }, async ({ targetPath, ...binding }) => await writeFileFallbackUnlocked(root, { ...params, ...binding }, targetPath));
@@ -1422,9 +1425,7 @@ async function writeMissingFileFallback(root, params, expectedWritePath) {
         if (verifyingPublication)
             throw err;
         if (hasNodeErrorCode(err, "EEXIST")) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: err instanceof Error ? err : undefined,
-            });
+            throw new FsSafeError("already-exists", "file already exists", errorCauseOptions(err));
         }
         throw err;
     }