@openclaw/fs-safe 0.18.0 → 0.18.1

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

package/dist/root-move-noreplace.js

@@ -9,7 +9,7 @@ import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
@@ -44,17 +44,13 @@ function normalizeMoveError(error) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
     if (nativePrimitiveUnavailable(error)) {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", errorCauseOptions(error));
     }
     return error;
 }
 function normalizeRenameNoReplaceError(error) {
     if (error?.code === "EINVAL") {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", errorCauseOptions(error));
     }
     return normalizeMoveError(error);
 }
@@ -157,9 +153,7 @@ export async function movePathNoReplaceNative(root, params, paths) {
         }
         catch (error) {
             if (isAlreadyExistsError(error) || error?.code === "ENOTEMPTY") {
-                throw new FsSafeError("already-exists", "destination exists", {
-                    cause: error instanceof Error ? error : undefined,
-                });
+                throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
             }
             throw normalizeRenameNoReplaceError(error);
         }

package/dist/root-observed-path.js

@@ -7,7 +7,7 @@ import { admitPathInsideRoot } from "./root-boundary.js";
 import { assertRootPathObservationReceiptCurrent } from "./root-directory-list.js";
 import { RootPathObservationError, resolveRootPathWithObservation, } from "./root-path.js";
 import { createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, } from "./root-context.js";
-import { fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 export async function resolvePinnedObservedPathInRoot(root, relativePath, kind) {
     const rootGuard = await createRootObservationGuard(root);
@@ -50,9 +50,7 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
                 if (kind === "stat") {
                     throw fileNotFoundError(error.error instanceof Error ? error.error : undefined);
                 }
-                throw new FsSafeError("not-found", "directory not found", {
-                    cause: error.error instanceof Error ? error.error : undefined,
-                });
+                throw new FsSafeError("not-found", "directory not found", errorCauseOptions(error.error));
             }
             throw error.error;
         }

package/dist/root-options.d.ts

@@ -1,5 +1,5 @@
 import type { DenyMutationPolicy } from "./deny-mutations.js";
-import type { RenameIdentityPolicy } from "./pinned-write.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 import type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
 import type { CopyCloneMode } from "./copy-policy.js";
 import type { RootCopyPublicationReceipt } from "./copy-publication.js";

package/dist/root-path-existing.js

@@ -6,6 +6,7 @@ import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions } from "./root-errors.js";
 export function absolutePathWithRawSegments(candidate) {
     if (path.sep !== "\\") {
         if (path.isAbsolute(candidate))
@@ -144,9 +145,7 @@ export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
     }
     catch (error) {
         if (isSymlinkOpenError(error) || (rejectUnresolved && isNotFoundPathError(error))) {
-            throw new FsSafeError("symlink", "symlink path could not be resolved", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("symlink", "symlink path could not be resolved", errorCauseOptions(error));
         }
         if (!isNotFoundPathError(error))
             throw error;

package/dist/root-path-stat.js

@@ -4,7 +4,7 @@ import { FsSafeError } from "./errors.js";
 import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
 import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
 import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
-import { fileNotFoundError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -32,9 +32,7 @@ async function captureChangedObservedFile(error, pathname, before, observed, ass
     }
 }
 async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
-    const failure = new FsSafeError("path-mismatch", "file changed during operation", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    const failure = new FsSafeError("path-mismatch", "file changed during operation", errorCauseOptions(cause));
     if (hasNodeErrorCode(cause, "ENOENT") && before?.isFile() && !before.isSymbolicLink() &&
         (before.nlink === 1 || before.nlink === 1n)) {
         try {

package/dist/root-public-types.d.ts

@@ -0,0 +1,11 @@
+export type { OpenResult, WritableOpenResult, } from "./root-impl.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 type { DenyMutationPolicy } from "./deny-mutations.js";
+export type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { MutationSymlinkPolicy, SymlinkPolicy, } from "./root-symlink-policy.js";
+export type { ReadResult } from "./read-opened-file.js";
+export type { RootCopyPublicationReceipt } from "./copy-publication.js";
+export type { CopyCloneMode } from "./copy-policy.js";
+export type { RootEntriesOptions } from "./root-entries.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";

package/dist/root-remove-identity.js

@@ -2,12 +2,10 @@ import fsSync from "node:fs";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { realpathSync } from "./realpath.js";
-import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { directoryComponentNotDirectoryError, errorCauseOptions } from "./root-errors.js";
 const MAX_SAFE_DIRECTORY_IDENTITY = BigInt(Number.MAX_SAFE_INTEGER);
 function identityMismatch(cause) {
-    return new FsSafeError("path-mismatch", "removal ancestor identity changed or could not be verified", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    return new FsSafeError("path-mismatch", "removal ancestor identity changed or could not be verified", errorCauseOptions(cause));
 }
 function safeIdentityNumber(value) {
     if (value < 0n || value > MAX_SAFE_DIRECTORY_IDENTITY)

package/dist/root-remove.js

@@ -8,7 +8,7 @@ import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { MutationAuthorityError } from "./mutation-authority.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
-import { normalizeRemoveGuardError, normalizeRemovePathError, rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, normalizeRemoveGuardError, normalizeRemovePathError, rootPathChangedError } from "./root-errors.js";
 import { assertRemovalDirectoryCurrent, createRemovalDirectoryAssertion, } from "./root-remove-identity.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
@@ -44,9 +44,7 @@ function assertNotAborted(signal) {
     }
 }
 function removalAncestorChanged(error) {
-    return new FsSafeError("path-mismatch", "removal ancestor changed during operation", {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("path-mismatch", "removal ancestor changed during operation", errorCauseOptions(error));
 }
 function sameCanonicalDirectory(left, right) {
     return left === right || (isPathInside(left, right) && isPathInside(right, left));

package/dist/root-write-admission.d.ts

@@ -1,7 +1,7 @@
 import type { BigIntStats } from "node:fs";
 import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
 import type { RootContext } from "./root-context.js";
 import { resolvePathInRoot } from "./root-context.js";
 import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";

package/dist/root-write-admission.js

@@ -8,7 +8,7 @@ import { assertNoPathAliasEscape } from "./path-policy.js";
 import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy, } from "./pinned-mutation-admission.js";
 import { admitPathInsideRoot, sameNormalizedPathSpelling } from "./root-boundary.js";
 import { resolvePathInRoot } from "./root-context.js";
-import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { errorCauseOptions, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
 import { inheritWriteTargetMode } from "./root-write-mode.js";
 import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
@@ -23,9 +23,7 @@ export function createRootWriteSelectionForFd(selection, fd) {
     });
 }
 function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function inspectRegularSelectionPath(pathname, expected, follow) {
     let observed;
@@ -186,9 +184,7 @@ export async function resolveGuardedWritePathInRoot(root, params) {
             });
         }
         catch (error) {
-            throw new FsSafeError("path-alias", "path alias escape blocked", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("path-alias", "path alias escape blocked", errorCauseOptions(error));
         }
     }
     return resolvedPath;

package/dist/root-write-complete-parent.js

@@ -8,13 +8,12 @@ import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot, sameNormalizedPathSpelling } from "./root-boundary.js";
 import { ordinaryWindowsSegments } from "./pinned-mutation-shared-route.js";
 import { prepareRootWriteTarget } from "./root-directory-creation.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {
     if (process.versions.bun || relativePath === "" || relativePath.startsWith("~") ||

package/dist/root-write-verification.d.ts

@@ -1,5 +1,5 @@
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
-import type { PublishedWriteIdentity } from "./pinned-write.js";
+import type { PublishedWriteIdentity } from "./pinned-write-types.js";
 import { type RootContext } from "./root-context.js";
 export declare function verifyAtomicWriteResult(params: {
     root: RootContext;

package/dist/root.d.ts

@@ -1,6 +1,2 @@
-export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type MutationSymlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root-impl.js";
-export type { RootCopyPublicationReceipt } from "./copy-publication.js";
-export type { CopyCloneMode } from "./copy-policy.js";
-export type { RootEntriesOptions } from "./root-entries.js";
-export type { ContainmentGuarantee } from "./containment.js";
-export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type Root, } from "./root-impl.js";
+export type * from "./root-public-types.js";

package/dist/secret-file.js

@@ -8,7 +8,6 @@ import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryI
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertOwnedDirectory } from "./directory-mode-owner.js";
 import { FsSafeError } from "./errors.js";
-import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { ensureTrailingSep } from "./root-context.js";

package/dist/secure-temp-repair.js

@@ -14,9 +14,13 @@ export function captureSecureTempRepairAdapter(supplied, hasLegacyFsHooks) {
     }
     return { lstatSync, fstatSync, openSync, fchmodSync, closeSync, flags: O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK };
 }
+// Node exposes stat identity through BigInt64Array; a high OS bit can be negative.
+// Preserve raw values and existing positive adapter receipts, never normalize them.
+const MIN_NODE_STAT_IDENTITY = -(1n << 63n);
 export function secureTempDirectoryReceipt(stat, uid) {
     const { dev, ino, uid: owner, mode } = stat;
-    if (typeof dev !== "bigint" || dev < 0n || typeof ino !== "bigint" || ino <= 0n ||
+    if (typeof dev !== "bigint" || dev < MIN_NODE_STAT_IDENTITY ||
+        typeof ino !== "bigint" || ino < MIN_NODE_STAT_IDENTITY || ino === 0n ||
         typeof owner !== "bigint" || owner !== BigInt(uid) || typeof mode !== "bigint" ||
         mode < 0n || mode > 0xffffffffn || (mode & 61440n) !== 16384n ||
         stat.isDirectory() !== true || stat.isSymbolicLink() !== false) {

package/dist/sidecar-lock-acquire.js

@@ -69,7 +69,7 @@ export async function acquireSidecarLock(options, context) {
     if (activeDescendant)
         throw sidecarLockTimeout(lockPath, normalizedTargetPath);
     const admission = createSidecarAdmissionController(admissionAncestry, context.admissions, normalizedTargetPath);
-    const startedAt = Date.now();
+    const startedAt = performance.now();
     const reclaimGuardPath = `${lockPath}.reclaim`;
     let reclaimGuard;
     const releaseReclaimGuard = async () => {
@@ -90,7 +90,7 @@ export async function acquireSidecarLock(options, context) {
     const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
     const waitForRetry = async () => {
         admission.release();
-        const delay = sidecarLockRetryDelay(retry, timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs, Date.now() - startedAt, attempt);
+        const delay = sidecarLockRetryDelay(retry, timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs, performance.now() - startedAt, attempt);
         if (delay === undefined)
             throw sidecarLockTimeout(lockPath, normalizedTargetPath);
         attempt += 1;
@@ -357,8 +357,9 @@ export async function acquireSidecarLock(options, context) {
                 try {
                     if (createdHeld)
                         stopSidecarLockMonitoring(createdHeld);
+                    let failedSnapshot = createdSnapshot;
                     if (handle) {
-                        const failedSnapshot = createdSnapshot ?? { payload: null };
+                        failedSnapshot ??= { payload: null };
                         try {
                             failedSnapshot.stat = fsSync.fstatSync(handle.fd);
                         }
@@ -370,14 +371,10 @@ export async function acquireSidecarLock(options, context) {
                             context.held.delete(normalizedTargetPath);
                         }
                         await handle.close().catch(() => undefined);
-                        // Root records use the creator receipt; partial raw writes use fd identity.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot,
-                            parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),
-                        });
                     }
-                    else if (createdSnapshot) {
-                        await removeSidecarLockIfUnchanged(lockPath, createdSnapshot, {
+                    // Root records use the creator receipt; partial raw writes use fd identity.
+                    if (failedSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
                             lockRoot,
                             parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),
                         });

package/dist/sidecar-lock-policy.d.ts

@@ -5,6 +5,7 @@ export declare function validateSidecarLockStaleMs(staleMs: number | undefined):
 export declare function validateSidecarLockCompromiseCheckIntervalMs(intervalMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare function sidecarLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
+export declare function sidecarLockStale(lockPath: string, normalizedTargetPath: string): Error;
 /** Undefined means the deadline or retry count is exhausted. */
 export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, timeoutMs: number | undefined, elapsed: number, attempt: number): number | undefined;
 export declare const maxTransientLockDenials = 8;

package/dist/sidecar-lock-policy.js

@@ -62,6 +62,13 @@ export function sidecarLockTimeout(lockPath, normalizedTargetPath) {
         normalizedTargetPath,
     });
 }
+export function sidecarLockStale(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+        code: "file_lock_stale",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
 /** Undefined means the deadline or retry count is exhausted. */
 export function sidecarLockRetryDelay(retry, timeoutMs, elapsed, attempt) {
     if ((timeoutMs !== undefined && elapsed >= timeoutMs) ||

package/dist/sidecar-lock-stale-admission.js

@@ -1,4 +1,4 @@
-import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial } from "./sidecar-lock-policy.js";
+import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial, sidecarLockStale } from "./sidecar-lock-policy.js";
 import { readSidecarLockRawSnapshot, removeStaleSidecarLockIfAllowed, sidecarLockSnapshotStillPresent, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { observeSidecarLockParser, parseSidecarLockSnapshotUnderAdmission, scopedSidecarLockParser, } from "./sidecar-lock-admission-parser.js";
 /** Handle one historical EEXIST attempt while its canonical admission is held. */
@@ -224,9 +224,5 @@ export async function handleStaleSidecarAdmission(params) {
         }
         await params.releaseReclaimGuard();
     }
-    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-        code: "file_lock_stale",
-        lockPath,
-        normalizedTargetPath,
-    });
+    throw sidecarLockStale(lockPath, normalizedTargetPath);
 }

package/dist/sidecar-lock-types.d.ts

@@ -12,27 +12,35 @@ export type SidecarLockCompromisedInfo = {
     lockPath: string;
     normalizedTargetPath: string;
 };
-export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
-    targetPath: string;
+export type SidecarLockOptionFields<T> = {
+    [K in keyof T]: T[K];
+};
+export type SidecarLockCommonAcquireOptions = {
     lockPath?: string;
-    staleMs: number;
     timeoutMs?: number;
     retry?: SidecarLockRetryOptions;
     staleRecovery?: SidecarLockStaleRecovery;
     reentrantOwner?: string;
+    parsePayload?: (raw: string) => unknown;
+    lockRoot?: Root;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    compromiseCheckIntervalMs?: number;
+};
+export type SidecarLockReclaimParams<Held extends boolean = boolean> = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    payload: unknown;
+    staleMs: number;
+    nowMs: number;
+    heldByThisProcess: Held;
+};
+export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = SidecarLockOptionFields<SidecarLockCommonAcquireOptions & {
+    targetPath: string;
+    staleMs: number;
     payload: () => TPayload | Promise<TPayload>;
-    shouldReclaim?: (params: {
-        lockPath: string;
-        normalizedTargetPath: string;
-        payload: unknown;
-        staleMs: number;
-        nowMs: number;
-        heldByThisProcess: boolean;
-    }) => boolean | Promise<boolean>;
+    shouldReclaim?: (params: SidecarLockReclaimParams) => boolean | Promise<boolean>;
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     metadata?: Record<string, unknown>;
-    parsePayload?: (raw: string) => unknown;
-    lockRoot?: Root;
     /**
      * Keep the lock file when the process exits naturally. Default `false`:
      * process-exit handlers release held locks. Set only for deliberately
@@ -40,9 +48,7 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
      * liveness is governed by the caller's own stale policy.
      */
     retainOnExit?: boolean;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
-    compromiseCheckIntervalMs?: number;
-};
+}>;
 export type SidecarLockHandle = {
     lockPath: string;
     normalizedTargetPath: string;

package/dist/temp-workspace-admission.js

@@ -2,14 +2,12 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
-import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, } from "./temp-workspace-child-admission.js";
+import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, assertTrustedTempWorkspaceDirectory, inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 import { FsSafeError } from "./errors.js";
 import { recordFileObservationFailure } from "./file-observation.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
-import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
 const WINDOWS = process.platform === "win32";
 function effectiveOwner() {
     // Windows mode/uid fields do not describe ACL authority. The supplied root's

package/dist/temp-workspace-child-admission.d.ts

@@ -1,6 +1,20 @@
-import type { BigIntStats, Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
-import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+export type TempWorkspaceIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type TempWorkspaceNumericIdentity = Readonly<{
+    dev: number;
+    ino: number;
+}>;
+export type TempWorkspaceIdentityStat = BigIntStats | Stats;
+export declare const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY: boolean;
+export declare function projectTempWorkspaceNumericIdentity(identity: TempWorkspaceIdentity): TempWorkspaceNumericIdentity | undefined;
+export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function validateTempWorkspaceDirMode(mode: number): void;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "mode"> | Pick<Stats, "uid" | "mode">, uid: number | undefined, child?: boolean): void;
 export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
 export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
 export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;