@openclaw/fs-safe 0.18.0 → 0.18.1

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCopyPublicationReceipt, type CopyCloneMode, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootEntriesOptions, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type MutationSymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
-export type { ContainmentGuarantee } from "./containment.js";
-export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
-export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
-export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export type * from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type Root, } from "./root.js";
+export type * from "./root-public-types.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export type * from "./config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export type * from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/json-durable-queue-read.js

@@ -43,6 +43,7 @@ export async function withJsonDurableQueueEntry(filePath, options, run) {
     const handle = await fs.promises.open(filePath, resolveReadOpenFlags());
     let closePromise;
     const releaseReadPin = () => closePromise ??= (async () => { await handle.close(); })();
+    let result;
     try {
         const openedStat = inspectQueueEntry(() => fs.fstatSync(handle.fd, { bigint: true }), maxBytes, initialStat);
         inspectQueueEntry(inspectPath, maxBytes, openedStat);
@@ -53,9 +54,12 @@ export async function withJsonDurableQueueEntry(filePath, options, run) {
         });
         // The migration owner may release this pin only at the verified publication
         // boundary; until then an unlinked inode cannot be recycled into a new claim.
-        return await run(JSON.parse(bytes.toString("utf8")), openedStat, releaseReadPin);
+        result = await run(JSON.parse(bytes.toString("utf8")), openedStat, releaseReadPin);
     }
-    finally {
-        await releaseReadPin();
+    catch (error) {
+        await releaseReadPin().catch(() => undefined);
+        throw error;
     }
+    await releaseReadPin();
+    return result;
 }

package/dist/json-durable-queue.js

@@ -7,8 +7,7 @@ import { withJsonDurableQueueEntry } from "./json-durable-queue-read.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
 import { replaceFileAtomicWithDirectorySync } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.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/json-store.js

@@ -1,8 +1,7 @@
 import path from "node:path";
 import { fileStore } from "./file-store.js";
 import {} from "./json-document-store.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export function jsonStore(options) {
     const filePathInput = admitStandalonePublicationPath(options.filePath);
     const filePath = path.resolve(filePathInput);

package/dist/json.js

@@ -9,10 +9,9 @@ import { openRootFileSync } from "./root-file.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { writeTempFileSync } from "./replace-file-descriptor.js";
 import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { writeTextAtomic } from "./text-atomic.js";
 import { sleep } from "./timing.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 const READ_RETRY_MAX_ATTEMPTS = 5;
 const READ_RETRY_BASE_DELAY_MS = 50;
 function isRetryableReadError(err) {

package/dist/move-path.js

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

package/dist/native-operations.js

@@ -1,7 +1,6 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";

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

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

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

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

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

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

package/dist/native-pinned-write.js

@@ -63,6 +63,7 @@ import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observa
 import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
@@ -95,12 +96,8 @@ function normalizePolicyParentOpenError(error, params) {
     if (!isSymlinkOpenError(error))
         return error;
     return params.mutationAdmission?.rejectParentSymlinks
-        ? new FsSafeError("symlink", "symlink path component not allowed", {
-            cause: error instanceof Error ? error : undefined,
-        })
-        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        ? new FsSafeError("symlink", "symlink path component not allowed", errorCauseOptions(error))
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", errorCauseOptions(error));
 }
 async function describePosixParent(parentFd, pathname) {
     const parentPath = realpathSync.native(pathname);

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

@@ -2,7 +2,7 @@ import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type NativeRootAdmission } from "./native-parent-admission.js";
 import type { NativeBinding } from "./native.js";
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
 type PolicyParent = {
     fd: number;

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

@@ -3,7 +3,7 @@ import { type BigIntStats, type Stats } from "node:fs";
 import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import { type NativeBinding } from "./native-binding.js";
-import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteInput, PinnedWriteParams } from "./pinned-write-types.js";
 import type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
 export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding, "createStagedFile" | "stagedFileMatches" | "removeStagedFile">>;
 export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
@@ -36,10 +36,10 @@ declare class NativeStagedFile implements StagedFile {
 }
 export declare const createNativeStage: (...args: Parameters<typeof NativeStagedFile.create>) => Promise<StagedFile>;
 export declare const writeNativeStage: typeof NativeStagedFile.write;
-export type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt, } from "./staged-file-types.js";
 export declare function stageFileInDirectory(options: {
     directory: string | DirectoryReceipt<Stats | BigIntStats>;
     content: string | Uint8Array;
     /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
     mode?: number;
 }): Promise<StagedFile>;
+export {};

package/dist/native-staged-file.js

@@ -50,8 +50,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { assertDarwinCreationAcl } from "./creation-darwin.js";
-import { assertPrivateCreationFile } from "./creation-file-state.js";
+import { assertDarwinCreationAcl, assertPrivateCreationFile } from "./creation-boundary.js";
 import { requireNativeBinding } from "./native.js";
 import { syncFileBestEffortSync } from "./file-sync.js";
 import { randomUUID } from "node:crypto";

package/dist/pinned-mutation-admission.d.ts

@@ -1,6 +1,6 @@
 import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootBoundaryIdentity } from "./root-boundary.js";
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
 import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type PinnedMutationPolicySnapshot = Readonly<{
     denyMutations?: DenyMutationPolicy;

package/dist/pinned-open.js

@@ -77,7 +77,12 @@ export function openPinnedFileSync(params) {
     }
     finally {
         if (fd !== null) {
-            ioFs.closeSync(fd);
+            try {
+                ioFs.closeSync(fd);
+            }
+            catch {
+                // Preserve the failed admission result; success transfers fd above.
+            }
         }
     }
 }

package/dist/pinned-operation.d.ts

@@ -1 +1 @@
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
+export declare function validatePinnedRelativePath(relativePath: unknown): void;

package/dist/pinned-operation.js

@@ -1,19 +1,7 @@
 import { FsSafeError } from "./errors.js";
-export function validatePinnedOperationPayload(payload) {
-    if (typeof payload.relativePath === "string") {
-        validatePinnedRelativePath(payload.relativePath);
-    }
-    if (typeof payload.relativeParentPath === "string") {
-        validatePinnedRelativePath(payload.relativeParentPath);
-    }
-    if (typeof payload.from === "string") {
-        validatePinnedRelativePath(payload.from);
-    }
-    if (typeof payload.to === "string") {
-        validatePinnedRelativePath(payload.to);
-    }
-}
-function validatePinnedRelativePath(relativePath) {
+export function validatePinnedRelativePath(relativePath) {
+    if (typeof relativePath !== "string")
+        return;
     if (relativePath.length === 0 || relativePath === ".") {
         return;
     }
@@ -21,7 +9,6 @@ function validatePinnedRelativePath(relativePath) {
         throw new FsSafeError("invalid-path", "relative path contains a NUL byte");
     }
     if (relativePath.startsWith("/") ||
-        relativePath.startsWith("//") ||
         relativePath === ".." ||
         relativePath.startsWith("../") ||
         relativePath.startsWith("..\\")) {

package/dist/pinned-write-mode.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
-import { assertPrivateCreationFile } from "./creation-file-state.js";
+import { assertPrivateCreationFile } from "./creation-boundary.js";
 export function assertPinnedWriteMode(fd, mode, privateCreation = false) {
     if (process.platform === "win32")
         return;

package/dist/pinned-write-staged.js

@@ -3,8 +3,7 @@ import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { hasPreservedCreationArtifacts } from "./creation-file-state.js";
-import { creationAdmissionFromParent } from "./creation-path.js";
+import { hasPreservedCreationArtifacts, creationAdmissionFromParent } from "./creation-boundary.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity, sha256Hex } from "./file-identity.js";

package/dist/pinned-write.d.ts

@@ -1,6 +1,5 @@
 import type { FileIdentityStat } from "./file-identity.js";
 import type { PinnedWriteParams, RenameIdentityPolicy } from "./pinned-write-types.js";
-export type { PinnedWriteInput, RenameIdentityPolicy, PublishedWriteIdentity, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken, PinnedCreatedDirectoryReceipt, PinnedMutationParentWalkSession, PinnedWriteMutationAdmission, PinnedWriteParams, } from "./pinned-write-types.js";
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;
 export declare function runPinnedWriteWithRenamePolicy(params: PinnedWriteParams & {
     targetPath: string;

package/dist/pinned-write.js

@@ -3,7 +3,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createFileHandle } from "./create.js";
-import { creationAdmissionFromParent } from "./creation-path.js";
+import { creationAdmissionFromParent } from "./creation-boundary.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -13,7 +13,7 @@ import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { runPinnedWriteNative } from "./native-pinned-write.js";
 import { getNativeBinding } from "./native.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { withSidecarLock } from "./sidecar-lock.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -71,9 +71,7 @@ export async function runPinnedWriteHelper(params) {
         rootIdentity,
     };
     assertSafeBasename(normalizedParams.basename);
-    validatePinnedOperationPayload({
-        relativeParentPath: normalizedParams.relativeParentPath,
-    });
+    validatePinnedRelativePath(normalizedParams.relativeParentPath);
     assertNoWindowsPathAlias(normalizedParams.rootPath, "filesystem", "pinned write root uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.relativeParentPath, "relative", "pinned write parent uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(normalizedParams.basename, "relative", "pinned write basename uses a Windows filesystem namespace alias");

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

@@ -8,9 +8,8 @@ import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, }
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { 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];
 }

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