@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/creation-darwin.js

@@ -2,7 +2,6 @@ import fs, {} from "node:fs";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nodeDarwinDirectoryMetadataFlags, nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
-import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { getNativeBinding } from "./native.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 function inspector() {
@@ -69,11 +68,3 @@ export function assertDarwinCreationDirectoryAcl(pathname, expected, inheritance
         fs.closeSync(fd);
     }
 }
-export function privateFileMutationAssertion(fd, assertion) {
-    if (process.platform !== "darwin")
-        return assertion;
-    return () => {
-        assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
-        assertDarwinCreationAcl(fd);
-    };
-}

package/dist/creation-file-state.d.ts

@@ -16,4 +16,3 @@ export declare function privateFileSettlementFailure(params: {
     stageDirectory: string;
     preserved?: boolean;
 }): FsSafeError;
-//# sourceMappingURL=creation-file-state.d.ts.map

package/dist/creation-path.d.ts

@@ -1,5 +1,6 @@
 import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard, type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { CreationPermissions } from "./creation-permissions.js";
 export type CreationParentIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
@@ -10,6 +11,7 @@ export type CreationPath = {
     parent: AsyncDirectoryGuard<BigIntStats>;
     assertParent(): void;
 };
+export declare function assertBeforeCreation(selected: CreationPath, permissions: CreationPermissions, assertion: (() => void) | undefined, kind: "file" | "directory"): void;
 export declare function creationAdmissionFromParent(parent: AnyAsyncDirectoryGuard): {
     expectedParentIdentity: CreationParentIdentity;
 };
@@ -18,4 +20,3 @@ export declare function creationCollision(error: unknown): unknown;
 /** Remove only the recorded empty stage; never traverse a replaced directory. */
 export declare function removeCreationDirectory(directory: string, identity: BigIntStats, assertParent: () => void): void;
 export declare function removeCreationDirectoryAsync(directory: string, identity: BigIntStats, assertParent: () => void): Promise<void>;
-//# sourceMappingURL=creation-path.d.ts.map

package/dist/creation-path.js

@@ -3,9 +3,21 @@ import fsAsync from "node:fs/promises";
 import path from "node:path";
 import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { assertDarwinCreationDirectoryAcl, assertDarwinPrivateDirectoryMode } from "./creation-darwin.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { assertNoNulPathInput } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+export function assertBeforeCreation(selected, permissions, assertion, kind) {
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private && kind === "directory")
+        assertDarwinPrivateDirectoryMode(permissions.mode);
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+}
 export function creationAdmissionFromParent(parent) {
     const { dev, ino } = parent.stat;
     if (typeof dev !== "bigint" || typeof ino !== "bigint") {

package/dist/creation-permissions.d.ts

@@ -16,4 +16,3 @@ export declare function protectCreatedFileSync(fd: number, targetPath: string, p
 export declare function protectCreatedFile(fd: number, targetPath: string, parentIdentity: string): Promise<string>;
 export declare function verifyCreatedFileSync(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): void;
 export declare function verifyCreatedFile(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): Promise<void>;
-//# sourceMappingURL=creation-permissions.d.ts.map

package/dist/creation-permissions.js

@@ -50,24 +50,24 @@ function commandFallback() {
         unavailable();
     warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
 }
+function creationOperation(name) {
+    const native = getNativeBinding();
+    const operation = native?.[name];
+    if (typeof operation === "function")
+        return operation.bind(native);
+    commandFallback();
+    return undefined;
+}
 /** Full Windows identity, with security validation when requested; no repairs. */
 export function inspectCreationDirectorySync(targetPath, privatePath) {
     assertNoWindowsPathAlias(targetPath, "filesystem");
-    const native = getNativeBinding();
-    if (typeof native?.inspectWindowsDirectory === "function") {
-        return native.inspectWindowsDirectory(targetPath, privatePath).identity;
-    }
-    commandFallback();
-    return inspectWindowsDirectoryCommandSync(targetPath, privatePath).identity;
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : inspectWindowsDirectoryCommandSync(targetPath, privatePath)).identity;
 }
 export async function inspectCreationDirectory(targetPath, privatePath) {
     assertNoWindowsPathAlias(targetPath, "filesystem");
-    const native = getNativeBinding();
-    if (typeof native?.inspectWindowsDirectory === "function") {
-        return native.inspectWindowsDirectory(targetPath, privatePath).identity;
-    }
-    commandFallback();
-    return (await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
 }
 export function assertPrivateDirectorySync(targetPath) {
     const stat = inspectDirectoryIdentitySync(targetPath);
@@ -90,36 +90,26 @@ export async function assertPrivateDirectory(targetPath) {
     inspectDirectoryIdentitySync(targetPath, stat);
 }
 export function protectCreatedFileSync(fd, targetPath, parentIdentity) {
-    const native = getNativeBinding();
-    if (typeof native?.protectPrivateWindowsFile === "function") {
-        return native.protectPrivateWindowsFile(fd, targetPath, parentIdentity).identity;
-    }
-    commandFallback();
-    return protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity).identity;
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity)).identity;
 }
 export async function protectCreatedFile(fd, targetPath, parentIdentity) {
-    const native = getNativeBinding();
-    if (typeof native?.protectPrivateWindowsFile === "function") {
-        return native.protectPrivateWindowsFile(fd, targetPath, parentIdentity).identity;
-    }
-    commandFallback();
-    return (await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
 }
 export function verifyCreatedFileSync(fd, targetPath, identity, parentIdentity, links = 1) {
-    const native = getNativeBinding();
-    if (typeof native?.verifyPrivateWindowsFile === "function") {
-        native.verifyPrivateWindowsFile(fd, targetPath, identity, parentIdentity, links);
-        return;
-    }
-    commandFallback();
-    verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
 }
 export async function verifyCreatedFile(fd, targetPath, identity, parentIdentity, links = 1) {
-    const native = getNativeBinding();
-    if (typeof native?.verifyPrivateWindowsFile === "function") {
-        native.verifyPrivateWindowsFile(fd, targetPath, identity, parentIdentity, links);
-        return;
-    }
-    commandFallback();
-    await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
 }

package/dist/deny-mutations.d.ts

@@ -1,4 +1,4 @@
-export declare function resolveMutationComparablePaths(rawPath: string): Promise<Set<string>>;
+export declare function resolveMutationComparablePaths(rawPath: string): Set<string>;
 export type DenyMutationPolicy = {
     paths?: readonly string[];
     prefixes?: readonly string[];
@@ -6,7 +6,6 @@ export type DenyMutationPolicy = {
 type DenyMutationCheckOptions = {
     protectAncestors?: boolean;
 };
-export declare function assertMutationNotDenied(filePath: string, policy: DenyMutationPolicy | undefined, options?: DenyMutationCheckOptions): Promise<void>;
+export declare function assertMutationNotDenied(filePath: string, policy: DenyMutationPolicy | undefined, options?: DenyMutationCheckOptions, mode?: "root" | "sync-root-lock"): void;
 export declare function mergeDenyMutationPolicies(defaultPolicy: DenyMutationPolicy | undefined, callPolicy: DenyMutationPolicy | undefined): DenyMutationPolicy | undefined;
 export {};
-//# sourceMappingURL=deny-mutations.d.ts.map

package/dist/deny-mutations.js

@@ -1,61 +1,81 @@
+import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isPathInside } from "./path.js";
-import { resolvePathViaExistingAncestor } from "./root-path-existing.js";
-import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
-export async function resolveMutationComparablePaths(rawPath) {
+import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { resolveExistingAncestor } from "./root-path-existing.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+export function resolveMutationComparablePaths(rawPath) {
     assertNoNulPathInput(rawPath, "path contains a NUL byte");
     assertNoWindowsPathAlias(rawPath, "filesystem", "mutation path uses a Windows filesystem namespace alias");
     const resolved = resolvePathPreservingWindowsRoot(rawPath);
     assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
-    const canonical = await resolvePathViaExistingAncestor(resolved);
+    const canonical = resolveExistingAncestor(resolved, "native");
     assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
     return new Set([resolved, canonical]);
 }
-function isSamePath(left, right) {
-    return isPathInside(left, right) && isPathInside(right, left);
-}
-function hasPolicyEntries(policy) {
-    return Boolean(policy?.paths?.length || policy?.prefixes?.length);
+function strictMutationComparablePaths(pathname) {
+    const resolved = resolvePathPreservingWindowsRoot(pathname);
+    assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    let cursor = resolved;
+    const filesystemRoot = path.parse(resolved).root;
+    while (cursor !== filesystemRoot) {
+        try {
+            fs.lstatSync(pathForWindowsFilesystem(cursor));
+            break;
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+            cursor = path.dirname(cursor);
+        }
+    }
+    // Synchronous Root locks require authority-grade canonicalization. Keep
+    // ambiguous existing ancestors distinct from Root's lexical fallback.
+    const canonicalAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
+    assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    const canonical = cursor === resolved
+        ? canonicalAncestor
+        : path.resolve(canonicalAncestor, `.${path.sep}${resolved.slice(cursor.length)}`);
+    assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    return path.relative(path.resolve(resolved), path.resolve(canonical)) === ""
+        ? [resolved] : [resolved, canonical];
 }
-function policyPathEntries(entries) {
+function policyPathEntries(entries, strict) {
     const paths = [];
     for (const entry of entries ?? []) {
+        if (strict && (!entry || !path.isAbsolute(entry))) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty absolute paths");
+        }
         if (entry.length === 0) {
             throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty");
         }
         assertNoNulPathInput(entry, "deny mutation path contains a NUL byte");
         assertNoWindowsPathAlias(entry, "filesystem", "deny mutation path uses a Windows filesystem namespace alias");
-        if (!path.isAbsolute(entry)) {
+        if (!strict && !path.isAbsolute(entry)) {
             throw new FsSafeError("invalid-path", "deny mutation paths must be absolute");
         }
-        paths.push(entry);
+        paths.push(strict ? resolvePathPreservingWindowsRoot(entry) : entry);
     }
     return paths;
 }
-export async function assertMutationNotDenied(filePath, policy, options = {}) {
-    if (!hasPolicyEntries(policy)) {
+export function assertMutationNotDenied(filePath, policy, options = {}, mode = "root") {
+    if (!policy?.paths?.length && !policy?.prefixes?.length)
         return;
-    }
-    const targetPaths = await resolveMutationComparablePaths(filePath);
-    for (const deniedPath of policyPathEntries(policy.paths)) {
-        const deniedPaths = await resolveMutationComparablePaths(deniedPath);
-        for (const target of targetPaths) {
-            for (const denied of deniedPaths) {
-                if (isSamePath(denied, target) ||
-                    (options.protectAncestors === true && isPathInside(target, denied))) {
-                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
-                }
-            }
-        }
-    }
-    for (const deniedPrefix of policyPathEntries(policy.prefixes)) {
-        const deniedPaths = await resolveMutationComparablePaths(deniedPrefix);
-        for (const target of targetPaths) {
-            for (const denied of deniedPaths) {
-                if (isPathInside(denied, target) ||
-                    (options.protectAncestors === true && isPathInside(target, denied))) {
-                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+    const strict = mode === "sync-root-lock";
+    const comparablePaths = strict ? strictMutationComparablePaths : resolveMutationComparablePaths;
+    const targets = comparablePaths(filePath);
+    // Validate one complete phase at a time. A paths denial must not read or
+    // canonicalize prefixes, and invalid later paths retain validation precedence.
+    for (const kind of ["paths", "prefixes"]) {
+        for (const entry of policyPathEntries(policy[kind], strict)) {
+            const deniedPaths = comparablePaths(entry);
+            for (const target of targets) {
+                for (const denied of deniedPaths) {
+                    if ((isPathInside(denied, target) && (kind === "prefixes" || isPathInside(target, denied))) ||
+                        (options.protectAncestors === true && isPathInside(target, denied))) {
+                        throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                    }
                 }
             }
         }

package/dist/device-path.d.ts

@@ -12,4 +12,3 @@ export declare function isWindowsReservedDeviceName(name: string): boolean;
 export declare function matchUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): UnsafeDeviceReadPathMatch | undefined;
 export declare function isUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): boolean;
 export declare function assertNoUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): void;
-//# sourceMappingURL=device-path.d.ts.map

package/dist/directory-durability.d.ts

@@ -1,4 +1,4 @@
-import { type Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { FileIdentityStat } from "./file-identity.js";
 export type DirectorySyncOutcome = {
     status: "synced";
@@ -6,10 +6,10 @@ export type DirectorySyncOutcome = {
     status: "unsupported";
     code?: string;
 };
-export type DirectoryReceipt = {
+export type DirectoryReceipt<T extends Stats | BigIntStats = Stats> = {
     path: string;
     realPath: string;
-    identity: Stats;
+    identity: T;
 };
 export type DurableDirectoryReceipt = DirectoryReceipt & {
     parentSync: DirectorySyncOutcome | {
@@ -29,16 +29,15 @@ export type EnsureDurableDirectoryOptions = {
     expectedExistingIdentity?: FileIdentityStat;
     create?: (directoryPath: string) => Promise<void>;
 };
-export declare function pinDirectory(directory: string | DirectoryReceipt, options?: {
+export declare function pinDirectory(directory: string | DirectoryReceipt<Stats | BigIntStats>, options?: {
     label?: string;
 }): Promise<PinnedDirectory>;
-export declare function syncDirectory(directory: string | DirectoryReceipt, options?: {
+export declare function syncDirectory(directory: string | DirectoryReceipt<Stats | BigIntStats>, options?: {
     label?: string;
 }): Promise<DirectorySyncOutcome>;
-export declare function syncDirectorySync(directory: string | DirectoryReceipt, options?: {
+export declare function syncDirectorySync(directory: string | DirectoryReceipt<Stats | BigIntStats>, options?: {
     label?: string;
 }): DirectorySyncOutcome;
 export declare function syncDirectoryBestEffort(directoryPath: string): Promise<void>;
 export declare function syncDirectoryBestEffortSync(directoryPath: string): void;
 export declare function ensureDurableDirectory(options: EnsureDurableDirectoryOptions): Promise<DurableDirectoryReceipt>;
-//# sourceMappingURL=directory-durability.d.ts.map

package/dist/directory-entry-path.d.ts

@@ -1,3 +1,2 @@
 /** Strip only trailing separators: lstat must inspect the entry, not follow a leaf link. */
 export declare function directoryEntryPath(dir: string, platform?: NodeJS.Platform): string;
-//# sourceMappingURL=directory-entry-path.d.ts.map

package/dist/directory-guard.d.ts

@@ -6,11 +6,7 @@ export type AsyncDirectoryGuard<T extends Stats | BigIntStats = Stats> = {
     stat: T;
 };
 export type AnyAsyncDirectoryGuard = AsyncDirectoryGuard<Stats | BigIntStats>;
-export type SyncDirectoryGuard = {
-    dir: string;
-    realPath: string;
-    stat: Stats;
-};
+export type SyncDirectoryGuard = AsyncDirectoryGuard;
 export type DirectoryIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
@@ -30,8 +26,8 @@ export declare function createAsyncDirectoryGuard(dir: string, options?: {
 export declare function createAsyncDirectoryGuard(dir: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
-export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
 export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
+export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
 export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard | AnyAsyncDirectoryGuard): void;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
@@ -57,4 +53,3 @@ export declare function extendDirectoryObservationGuard(observation: StatObserva
 export declare function inspectDirectoryObservationSync(dir: string, expected?: ExactStatIdentity): StatObservationReceipt;
 export declare function assertDirectoryObservationSync(dir: string, expected: ExactStatIdentity): Stats | BigIntStats;
 export declare function assertDirectoryObservationGuardSync(guard: DirectoryObservationGuard): void;
-//# sourceMappingURL=directory-guard.d.ts.map

package/dist/directory-guard.js

@@ -30,6 +30,12 @@ export function assertDirectoryIdentitySync(observedPath, expected) {
     }
 }
 export async function createAsyncDirectoryGuard(dir, options) {
+    return captureDirectoryGuard(dir, "native", options);
+}
+export function createSyncDirectoryGuard(dir) {
+    return captureDirectoryGuard(dir, "normalized");
+}
+function captureDirectoryGuard(dir, mode, options) {
     const operationPath = directoryOperationPath(dir);
     const stat = options?.bigint
         ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
@@ -37,11 +43,17 @@ export async function createAsyncDirectoryGuard(dir, options) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    const realPath = realpathSync.native(operationPath);
+    const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
     return { dir, realPath, stat };
 }
 export async function assertAsyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "native");
+}
+export function assertSyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "normalized");
+}
+function assertDirectoryGuard(guard, mode) {
     const dir = guard.dir;
     const operationPath = directoryOperationPath(dir);
     const expectedRealPath = guard.realPath;
@@ -57,71 +69,32 @@ export async function assertAsyncDirectoryGuard(guard) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, expectedIdentity)) {
+    // Native guards check identity first; normalized numeric guards preserve
+    // canonicalization errors before their final identity comparison.
+    if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem");
-    if (realPath !== expectedRealPath) {
-        throw new FsSafeError("path-mismatch", "directory changed during operation");
-    }
-}
-export function createSyncDirectoryGuard(dir) {
-    const operationPath = directoryOperationPath(dir);
-    const stat = fsSync.lstatSync(operationPath);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem");
-    return { dir, realPath, stat };
-}
-export function assertSyncDirectoryGuard(guard) {
-    const dir = guard.dir;
-    const operationPath = directoryOperationPath(dir);
-    const expectedRealPath = guard.realPath;
-    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
-    const expectedStat = guard.stat;
-    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
-    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
-        ? inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedIdentity.dev, ino: expectedIdentity.ino })
-        : fsSync.lstatSync(operationPath);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    const realPath = typeof expectedIdentity.ino === "bigint"
+    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
         ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
-    if (!sameFileIdentity(stat, expectedIdentity) || realPath !== expectedRealPath) {
+    if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
-    assertNoWindowsPathAlias(rootReal, "filesystem");
-    assertNoWindowsPathAlias(targetPath, "filesystem");
-    let current = resolvePathPreservingWindowsRoot(targetPath);
-    const root = resolvePathPreservingWindowsRoot(rootReal);
-    while (current !== root) {
-        try {
-            return await createAsyncDirectoryGuard(current, options);
-        }
-        catch (error) {
-            if (!isNotFoundPathError(error)) {
-                throw error;
-            }
-            current = path.dirname(current);
-        }
-    }
-    return await createAsyncDirectoryGuard(root, options);
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
 }
 export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
+}
+function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
     assertNoWindowsPathAlias(rootReal, "filesystem");
     assertNoWindowsPathAlias(targetPath, "filesystem");
     let current = resolvePathPreservingWindowsRoot(targetPath);
     const root = resolvePathPreservingWindowsRoot(rootReal);
     while (current !== root) {
         try {
-            return createSyncDirectoryGuard(current);
+            return captureDirectoryGuard(current, mode, options);
         }
         catch (error) {
             if (!isNotFoundPathError(error)) {
@@ -130,15 +103,11 @@ export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
             current = path.dirname(current);
         }
     }
-    return createSyncDirectoryGuard(root);
+    return captureDirectoryGuard(root, mode, options);
 }
 // Recovery receipts must retain every identity bit, including on Windows.
 export async function inspectDirectoryIdentity(dir, expected) {
-    const operationPath = directoryOperationPath(dir);
-    const expectedIdentity = expected === undefined
-        ? undefined
-        : { dev: expected.dev, ino: expected.ino };
-    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity);
+    return inspectDirectoryIdentitySync(dir, expected);
 }
 function directoryOperationPath(dir) {
     assertNoWindowsPathAlias(dir, "filesystem");

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

@@ -19,4 +19,3 @@ export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
     apply(mode: number, check?: () => void): void;
     close(): void;
 };
-//# sourceMappingURL=directory-mode-node.d.ts.map

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

@@ -18,4 +18,3 @@ export declare function ownDirectoryMode(params: {
     close: () => Promise<void>;
     ignoreChmodError?: boolean;
 }): DirectoryModeOwner;
-//# sourceMappingURL=directory-mode-owner.d.ts.map

package/dist/directory-receipt.d.ts

@@ -14,11 +14,10 @@ type DirectoryAuthority = DirectoryProvenance & Readonly<{
     realPath: string;
 }>;
 export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
-export declare function directoryReceiptAuthority(receipt: DirectoryReceipt): DirectoryAuthority;
-export declare function ownDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function directoryReceiptAuthority(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryAuthority;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryReceipt;
 export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
 export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
 export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
 export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
 export {};
-//# sourceMappingURL=directory-receipt.d.ts.map

package/dist/directory-receipt.js

@@ -53,10 +53,18 @@ function snapshotDirectoryReceipt(receipt) {
 function snapshotDirectoryMetadata(stat, identity) {
     const metadata = {};
     for (const field of numericFields) {
-        metadata[field] = field === "dev" || field === "ino" ? Number(identity[field]) : stat[field];
+        metadata[field] = Number(field === "dev" || field === "ino" ? identity[field] : stat[field]);
+    }
+    for (const field of timeFields) {
+        if ("atimeNs" in stat) {
+            const nanoseconds = stat[`${field}Ns`];
+            const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+            metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+        }
+        else {
+            metadata[`${field}Ms`] = stat[`${field}Ms`];
+        }
     }
-    for (const field of timeFields)
-        metadata[`${field}Ms`] = stat[`${field}Ms`];
     return Object.freeze(metadata);
 }
 export function directoryReceiptAuthority(receipt) {
@@ -81,27 +89,15 @@ function receiptFromAuthority(authority) {
         identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
     }, authority);
 }
-function numericDirectoryMetadata(exact) {
-    // Keep metadata and authority from one observation. A second pathname stat
-    // can describe a replacement even when a later fence sees the original again.
-    const metadata = {};
-    for (const field of numericFields) {
-        metadata[field] = Number(exact[field]);
-    }
-    for (const field of timeFields) {
-        const nanoseconds = exact[`${field}Ns`];
-        const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
-        metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
-    }
-    return Object.freeze(metadata);
-}
 // The caller already admitted the exact observation and its paths.
 export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {
+    const identity = Object.freeze({ dev: exactStat.dev, ino: exactStat.ino });
     return receiptFromAuthority(Object.freeze({
         path: pathname,
         realPath,
-        identity: Object.freeze({ dev: exactStat.dev, ino: exactStat.ino }),
-        metadata: numericDirectoryMetadata(exactStat),
+        identity,
+        // Project metadata from the admitted observation, never a fresh pathname stat.
+        metadata: snapshotDirectoryMetadata(exactStat, identity),
     }));
 }
 export function createDirectoryReceiptSync(directoryPath, label, canonicalize = realpathSync) {

package/dist/durability.d.ts

@@ -1,4 +1,3 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
 export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, type PublishFileExclusiveCleanup, type PublishFileExclusiveDirectorySyncFailure, type PublishFileExclusiveFailureDetails, type PublishFileExclusiveFailurePhase, type PublishFileExclusiveSyncFailurePolicy, } from "./publish-file.js";
 export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";
-//# sourceMappingURL=durability.d.ts.map

package/dist/effective-uid.d.ts

@@ -1,2 +1 @@
 export declare function resolveEffectiveUid(): number;
-//# sourceMappingURL=effective-uid.d.ts.map

package/dist/error-detail.d.ts

@@ -1,3 +1,2 @@
 export declare function formatErrorDetail(value: string): string;
 export declare function shortPath(value: string): string;
-//# sourceMappingURL=error-detail.d.ts.map

package/dist/errors.d.ts

@@ -11,4 +11,3 @@ export declare class FsSafeError extends Error {
         details?: FsSafeErrorDetails;
     });
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/file-cleanup.d.ts

@@ -1,6 +1,7 @@
 import { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export declare function readErrorCode(error: unknown): unknown;
 export declare function hasErrorCode(error: unknown, expected: string): boolean;
 type OwnedPathCleanupStatus = "removed" | "name-absent" | "preserved";
 export declare function removeOwnedPath(params: {
@@ -16,4 +17,3 @@ export declare function cleanupPinnedFilePath(params: {
     throwOnCleanupError?: boolean;
 }): Promise<OwnedPathCleanupStatus>;
 export {};
-//# sourceMappingURL=file-cleanup.d.ts.map