@openclaw/fs-safe 0.18.0 → 0.18.2

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

@@ -5,10 +5,8 @@ import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
-import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
-import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { pinNodeDirectoryForMode, assertOwnedDirectory } from "./directory-mode-node.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";
@@ -200,7 +198,11 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, parentGuard: targetGuard };
 }
-function snapshotSecretFileWriteParams(params, rootDir, filePath) {
+function snapshotSecretFileWriteParams(params) {
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     return {
         rootDir,
         filePath,
@@ -306,31 +308,23 @@ async function materializeSecretFileAtomic(params, createOnly) {
     });
 }
 export async function writeSecretFileAtomic(params) {
-    const rootDir = params.rootDir;
-    const filePath = params.filePath;
-    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-    const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-    const canonicalPath = await secretFileWriteQueueKey(filePath);
+    const ownedParams = snapshotSecretFileWriteParams(params);
+    const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
     await serializePathWrite(canonicalPath, async () => {
         await materializeSecretFileAtomic(ownedParams, false);
     });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        const rootDir = params.rootDir;
-        const filePath = params.filePath;
-        assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-        assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-        const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-        const canonicalPath = await secretFileWriteQueueKey(filePath);
+        const ownedParams = snapshotSecretFileWriteParams(params);
+        const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
         await serializePathWrite(canonicalPath, async () => {
             await materializeSecretFileAtomic(ownedParams, true);
         });
     }
     catch (error) {
         if ((error instanceof FsSafeError && error.code === "already-exists") ||
-            error.code === "EEXIST") {
+            error?.code === "EEXIST") {
             throw new FsSafeError("secret-exists", "Private secret file already exists.", { cause: error });
         }
         throw error;

package/dist/secret-read-policy.js

@@ -7,7 +7,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
-    const code = error.code;
+    const code = error?.code;
     return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
 }
 export function secretReadError(code, action, label, resolvedPath, error) {

package/dist/secure-file-windows.js

@@ -1,5 +1,5 @@
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
+import { fileIdentityMismatchError } from "./strict-file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { warnNativeFallback } from "./native-fallback-warning.js";
@@ -10,20 +10,15 @@ const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators
 function permissionUnverified(message, cause) {
     throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
 function parseIdentity(value) {
     if (typeof value !== "string")
-        identityMismatch();
+        throw fileIdentityMismatchError();
     const match = IDENTITY_RE.exec(value);
     if (!match)
-        identityMismatch();
+        throw fileIdentityMismatchError();
     return {
         dev: BigInt(`0x${match[1]}`),
         ino: BigInt(`0x${match[2]}`),
@@ -34,7 +29,7 @@ function inspectDescriptorResult(params, result, mechanism) {
         permissionUnverified("Windows descriptor ACL facts were malformed");
     const observed = parseIdentity(result.identity);
     if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
-        identityMismatch();
+        throw fileIdentityMismatchError();
     }
     const facts = validateSecureWindowsSecurityFacts(result.security);
     return {

package/dist/secure-temp-dir.js

@@ -3,15 +3,10 @@ import { tmpdir as getOsTmpDir } from "node:os";
 import path from "node:path";
 import { directoryEntryPath } from "./directory-entry-path.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { hasNodeErrorCode } from "./path.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
-function isNodeErrorWithCode(err, code) {
-    return (typeof err === "object" &&
-        err !== null &&
-        "code" in err &&
-        err.code === code);
-}
 export function resolveSecureTempRoot(options) {
     const { fallbackPrefix: prefix, accessSync: suppliedAccess, lstatSync: suppliedLstat, mkdirSync: suppliedMkdir, descriptor: suppliedDescriptor, getuid: suppliedGetuid, tmpdir: suppliedTmpdir, platform: suppliedPlatform, preferredDir, skipPreferredOnWindows, warn: suppliedWarn, warningPrefix: suppliedWarningPrefix, unsafeFallbackLabel: suppliedFallbackLabel, } = options;
     const platform = suppliedPlatform ?? process.platform;
@@ -87,7 +82,7 @@ export function resolveSecureTempRoot(options) {
             candidate = lstatSync(candidatePath);
         }
         catch (error) {
-            return { kind: isNodeErrorWithCode(error, "ENOENT") ? "missing" : "invalid", error };
+            return { kind: hasNodeErrorCode(error, "ENOENT") ? "missing" : "invalid", error };
         }
         let receipt;
         try {

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;
@@ -102,7 +102,7 @@ export async function acquireSidecarLock(options, context) {
             await waitForRetry();
         }
         catch (waitError) {
-            if (waitError.code === "file_lock_timeout")
+            if (waitError?.code === "file_lock_timeout")
                 throw denial;
             throw waitError;
         }
@@ -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-reclaim.js

@@ -357,13 +357,12 @@ export async function removeStaleSidecarLockIfAllowed(params) {
     if (params.assertGuardHeld)
         await params.assertGuardHeld();
     params.assertAuthorized?.();
+    if (params.lockRoot) {
+        await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath), { assertBeforeMutation: params.assertAuthorized });
+        return "removed";
+    }
     try {
-        if (params.lockRoot) {
-            await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath), { assertBeforeMutation: params.assertAuthorized });
-        }
-        else {
-            await fs.rm(params.lockPath);
-        }
+        await fs.rm(params.lockPath);
         return "removed";
     }
     catch (err) {

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/stat-observation.js

@@ -1,11 +1,4 @@
-import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 function safeNumber(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
@@ -35,7 +28,7 @@ function observeStatSync(inspect, expected, initial, platform = process.platform
     const ino = numericIno ? BigInt(rawIno) : typeof rawIno === "bigint" ? rawIno : undefined;
     if (expected && ((dev !== undefined && dev !== expected.dev) ||
         (ino !== undefined && ino !== expected.ino)))
-        identityMismatch();
+        throw fileIdentityMismatchError();
     if (numericDev && numericIno) {
         return (captureIdentity
             ? { stat, identity: expected ?? { dev: dev, ino: ino } }
@@ -47,7 +40,7 @@ function observeStatSync(inspect, expected, initial, platform = process.platform
         const current = inspect(true);
         if ((dev !== undefined && current.dev !== dev) ||
             (ino !== undefined && current.ino !== ino))
-            identityMismatch();
+            throw fileIdentityMismatchError();
         return current;
     }, expected, platform);
     return (captureIdentity

package/dist/strict-file-identity.d.ts

@@ -1,5 +1,7 @@
 import type { BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
 type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare function fileIdentityMismatchError(): FsSafeError;
 export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
 export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform, mismatch?: () => Error): T;
 export {};