@openclaw/fs-safe 0.17.0 → 0.18.0

package/dist/root-impl.js

@@ -73,6 +73,7 @@ import { PATH_ALIAS_POLICIES } from "./path-policy.js";
 import { assertNoNulPathInput, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { readOpenedFileSafely } from "./read-opened-file.js";
 import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { sameFileIdentity } from "./file-identity.js";
 import { removePathIfIdentityUnchanged } from "./replace-file-temp-owner.js";
 import { realpathSync } from "./realpath.js";
 import { mkdirPathFallback, prepareRootWriteTarget, tryMkdirAtExactParent } from "./root-directory-creation.js";
@@ -186,30 +187,19 @@ async function openVerifiedLocalFile(filePath, options) {
     }
 }
 export class RootHandle {
-    rootGuard;
-    rootIdentity;
+    context;
     rootDir;
     rootReal;
     rootWithSep;
     defaults;
     constructor(context, defaults = {}) {
-        this.rootGuard = context.rootGuard;
-        this.rootIdentity = context.rootIdentity;
+        this.context = context;
         this.rootDir = context.rootDir;
         this.rootReal = context.rootReal;
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
     }
-    get context() {
-        return {
-            rootDir: this.rootDir,
-            rootGuard: this.rootGuard,
-            rootIdentity: this.rootIdentity,
-            rootReal: this.rootReal,
-            rootWithSep: this.rootWithSep,
-        };
-    }
     mutationOptions(options) {
         return {
             ...options,
@@ -224,9 +214,9 @@ export class RootHandle {
     }
     async open(relativePath, options = {}) {
         return await openFileInRoot(this.context, {
-            relativePath,
             ...readDefaults(this.defaults),
             ...options,
+            relativePath,
         });
     }
     async read(relativePath, options = {}) {
@@ -246,9 +236,11 @@ export class RootHandle {
         return JSON.parse(await this.readText(relativePath, options));
     }
     async readAbsolute(filePath, options = {}) {
-        return await readPathInRoot(this.context, {
-            filePath,
-            ...mergeReadOptions(this.defaults, options),
+        const context = this.context;
+        const readOptions = mergeReadOptions(this.defaults, options);
+        return await readFileInRoot(context, {
+            relativePath: rootRelativeReadPath(context, filePath),
+            ...readOptions,
         });
     }
     reader(options = {}) {
@@ -260,10 +252,11 @@ export class RootHandle {
         assertValidRootDestinationPath(relativePath);
         const writeMode = options.writeMode ?? "replace";
         const target = await openWritableFileInRoot(this.context, {
-            relativePath,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            expectedWritePath: undefined,
             append: writeMode === "append",
             truncateExisting: writeMode === "replace",
         }).catch(rethrowMutationAuthorityError);
@@ -272,11 +265,11 @@ export class RootHandle {
     async append(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await appendFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(options),
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -285,33 +278,34 @@ export class RootHandle {
         validateRemoveOptions(options);
         options.signal?.throwIfAborted();
         await removePathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
         }).catch(rethrowMutationAuthorityError);
     }
     async mkdir(relativePath, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await mkdirPathInRoot(this.context, {
-            relativePath,
             ...this.mutationOptions(options),
+            relativePath,
+            allowRoot: false,
         }).catch(rethrowMutationAuthorityError);
     }
     async ensureRoot(options = {}) {
         await mkdirPathInRoot(this.context, {
+            ...this.mutationOptions(options),
             relativePath: "",
             allowRoot: true,
-            ...this.mutationOptions(options),
         }).catch(rethrowMutationAuthorityError);
     }
     async write(relativePath, data, options = {}) {
         assertValidRootDestinationPath(relativePath);
         await writeFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             renameIdentity: this.defaults.renameIdentity,
             ...this.mutationOptions(options),
+            relativePath,
+            data,
             durable: options.durable ?? this.defaults.durable ?? true,
         }).catch(rethrowMutationAuthorityError);
     }
@@ -319,11 +313,11 @@ export class RootHandle {
         assertValidRootDestinationPath(relativePath);
         const durable = options.durable ?? this.defaults.durable ?? true;
         await writeFileInRoot(this.context, {
-            relativePath,
-            data,
             mkdir: this.defaults.mkdir,
             mode: this.defaults.mode,
             ...this.mutationOptions(createInputOptions(data, options, this.defaults.maxBytes)),
+            relativePath,
+            data,
             durable: durable !== false,
             strictFileSync: durable === "file",
             overwrite: false,
@@ -343,12 +337,13 @@ export class RootHandle {
         options.signal?.throwIfAborted();
         assertValidRootDestinationPath(relativePath);
         const { maxBytes, ...copyOptions } = this.mutationOptions(options);
+        const copySource = typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath };
         await copyFileInRoot(this.context, {
-            source: typeof source === "string" ? source : { root: source.root, relativePath: source.relativePath },
-            relativePath,
             maxBytes: normalizeMaxBytes(maxBytes, { defaultValue: this.defaults.maxBytes }),
             mkdir: this.defaults.mkdir,
             ...copyOptions,
+            source: copySource,
+            relativePath,
             mode: options.mode ?? this.defaults.mode,
             durable: options.durable ?? this.defaults.durable ?? true,
             verifyPublished: options[onCopyPublication],
@@ -409,7 +404,7 @@ export class RootHandle {
     walk(relativePath, options) {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
-            rootReal: this.rootReal,
+            rootReal: this.context.rootReal,
             stat: relative => this.stat(relative),
             list: async (relative, listingOptions) => {
                 validatePinnedOperationPayload({ relativePath: relative });
@@ -468,15 +463,6 @@ async function readFileInRoot(root, params) {
         await opened.handle.close().catch(() => { });
     }
 }
-async function readPathInRoot(root, params) {
-    const relativePath = rootRelativeReadPath(root, params.filePath);
-    return await readFileInRoot(root, {
-        relativePath,
-        hardlinks: params.hardlinks,
-        maxBytes: params.maxBytes,
-        symlinks: params.symlinks,
-    });
-}
 export async function readLocalFileSafely(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
     const opened = await openLocalFileSafely({ filePath: params.filePath });
@@ -502,7 +488,7 @@ function buildAtomicWriteTempPath(targetPath) {
 function rootWriteQueueKey(root, relativePath) {
     return `${root.rootReal}\0${relativePath}`;
 }
-async function openWritableFileInRoot(root, params) {
+async function openWritableFileInRoot(root, params, options) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : await resolveGuardedWriteTargetInRoot(root, {
@@ -566,6 +552,17 @@ async function openWritableFileInRoot(root, params) {
             if (!isNotFoundPathError(err)) {
                 throw err;
             }
+            if (options?.createIfMissing === false) {
+                const parentGuard = writePathSelection?.parentGuard ??
+                    await createAsyncDirectoryGuard(path.dirname(ioPath), { bigint: true });
+                assertRootIdentityCurrentSync(root);
+                if (!admitPathInsideRoot({
+                    rootPath: root.rootReal, candidatePath: parentGuard.realPath, rootIdentity: root.rootIdentity,
+                }))
+                    throw outsideWorkspaceError();
+                assertSyncDirectoryGuard(parentGuard);
+                return { missing: true, targetPath: ioPath, parentGuard, writeSelection: writePathSelection };
+            }
             if (writePathSelection)
                 await refreshRootWritePathSelection(writePathSelection);
             params.assertBeforeMutation?.();
@@ -790,16 +787,11 @@ async function mkdirPathInRoot(root, params) {
     const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined
         : snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
+    const resolution = { relativePath: params.relativePath, allowRoot: params.allowRoot, ...policy };
     const resolveCurrent = policy
-        ? async () => await resolvePinnedPathInRoot(root, {
-            ...params,
-            denyMutations: policy.denyMutations,
-            mutationSymlinks: policy.mutationSymlinks,
-        })
+        ? async () => await resolvePinnedPathInRoot(root, resolution)
         : undefined;
-    const resolved = resolveCurrent
-        ? await resolveCurrent()
-        : await resolvePinnedPathInRoot(root, params);
+    const resolved = await resolvePinnedPathInRoot(root, resolution);
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
@@ -995,20 +987,9 @@ async function copyFileInRoot(root, params) {
     }
 }
 async function resolvePinnedPathInRoot(root, params) {
-    return await resolvePinnedOperationPathInRoot(root, {
-        allowRoot: params.allowRoot,
-        denyMutations: params.denyMutations,
-        mutationSymlinks: params.mutationSymlinks,
-        protectDenyMutationAncestors: params.remove === true,
-        relativePath: params.relativePath,
-        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
-        removalReceipts: params.removalReceipts,
-    });
-}
-async function resolvePinnedOperationPathInRoot(root, params) {
     const resolved = await resolvePinnedRootPathInRoot(root, {
         relativePath: params.relativePath,
-        policy: params.policy,
+        policy: params.remove ? PATH_ALIAS_POLICIES.unlinkTarget : PATH_ALIAS_POLICIES.strict,
         mutationSymlinks: params.mutationSymlinks,
         removalReceipts: params.removalReceipts,
     });
@@ -1035,7 +1016,7 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     }
     resolved.canonicalPath = admittedCanonicalPath.path;
     await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
-        protectAncestors: params.protectDenyMutationAncestors,
+        protectAncestors: params.remove === true,
     });
     return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
 }
@@ -1222,48 +1203,59 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         await writeMissingFileFallback(root, params, expectedWritePath);
         return;
     }
-    const { opened: target, identity: targetIdentity, writeSelection: retainedSelection } = await openWritableFileInRoot(root, {
+    const admissionParams = {
         relativePath: params.relativePath,
         mkdir: params.mkdir,
-        // Private, writable placeholder: Windows cannot rename over a read-only file.
-        mode: 0o600,
         denyMutations: params.denyMutations,
         assertBeforeMutation: params.assertBeforeMutation,
         mutationSymlinks: params.mutationSymlinks,
         truncateExisting: false,
         expectedWritePath,
-    });
+    };
+    const admission = await openWritableFileInRoot(root, admissionParams, { createIfMissing: false });
+    const existing = "missing" in admission ? undefined : admission;
+    const target = existing?.opened;
+    const retainedSelection = existing?.writeSelection;
+    const missingSelection = "missing" in admission ? admission.writeSelection : undefined;
     const policyEnabled = params.denyMutations !== undefined || params.mutationSymlinks !== undefined;
-    const destinationPath = retainedSelection?.selectedPath ?? target.realPath;
-    const mode = params.mode ?? (target.stat.mode & 0o777);
-    if (policyEnabled && !retainedSelection) {
-        await target.handle.close().catch(() => undefined);
+    const destinationPath = "missing" in admission ? admission.targetPath
+        : retainedSelection?.selectedPath ?? admission.opened.realPath;
+    let mode = params.mode ?? (target ? target.stat.mode & 0o777 : undefined);
+    if (policyEnabled && !retainedSelection && !missingSelection) {
+        await target?.handle.close().catch(() => undefined);
         throw new FsSafeError("path-mismatch", "write admission state was not retained");
     }
-    const destinationGuard = retainedSelection?.parentGuard ??
+    const destinationGuard = "missing" in admission ? admission.parentGuard : retainedSelection?.parentGuard ??
         await createAsyncDirectoryGuard(path.dirname(destinationPath), { bigint: true }).catch(async (error) => {
-            await target.handle.close().catch(() => undefined);
+            await target?.handle.close().catch(() => undefined);
             throw error;
         });
     let tempPath = null;
     let unregisterTempPath = null;
     let writtenHandle;
     let writtenIdentity;
-    let placeholderIdentity;
-    let published = false;
+    let lateTargetHandle;
     try {
-        if (target.createdForWrite)
-            placeholderIdentity = targetIdentity;
         tempPath = buildAtomicWriteTempPath(destinationPath);
         if (retainedSelection) {
-            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target.handle.fd);
+            await refreshRetainedRootWriteAdmission(root, retainedSelection, true, target?.handle.fd);
+        }
+        else if (missingSelection) {
+            await refreshRootWritePathSelection(missingSelection);
         }
         params.assertBeforeMutation?.();
         if (retainedSelection) {
-            assertRootWriteSelectionSync(root, retainedSelection, true, target.handle.fd);
+            assertRootWriteSelectionSync(root, retainedSelection, true, target?.handle.fd);
         }
+        else if (missingSelection) {
+            assertRootWritePathSelectionSync(root, missingSelection);
+        }
+        assertRootIdentityCurrentSync(root);
+        assertSyncDirectoryGuard(destinationGuard);
         writtenHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
         writtenIdentity = fsSync.fstatSync(writtenHandle.fd, { bigint: true });
+        // Preserve the creation mask when no existing destination supplies a mode.
+        mode ??= Number(writtenIdentity.mode & 511n);
         unregisterTempPath = registerTempPathForExit(tempPath, { identity: writtenIdentity, singleLinkFile: true });
         await writeAllToFile(writtenHandle, params.data, {
             encoding: params.encoding, assertBeforeMutation: params.assertBeforeMutation,
@@ -1278,24 +1270,42 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
                 root, targetPath: commitTempPath, fd: commitHandle.fd,
                 expectedIdentity: commitIdentity, parentGuard: destinationGuard,
             });
-            if (target.createdForWrite) {
-                await cleanupPinnedFilePath({
-                    pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-                });
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            let publicationIdentity = inspectFallbackReplacementDestination(destinationPath);
+            // A raced file needs its own access admission, not the old handle's rights.
+            if (publicationIdentity && (!existing || !sameFileIdentity(publicationIdentity, existing.identity))) {
+                const admitted = await openWritableFileInRoot(root, {
+                    ...admissionParams, mkdir: false, expectedWritePath: destinationPath,
+                }, { createIfMissing: false });
+                lateTargetHandle = "missing" in admitted ? undefined : admitted.opened.handle;
+                publicationIdentity = "missing" in admitted ? undefined : admitted.identity;
+                await lateTargetHandle?.close();
             }
             // Windows cannot replace a destination while its old handle remains open.
-            await target.handle.close();
+            await target?.handle.close();
             if (retainedSelection) {
-                await refreshRetainedRootWriteAdmission(root, retainedSelection, !target.createdForWrite);
+                await refreshRetainedRootWriteAdmission(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                await refreshRootWritePathSelection(missingSelection);
             }
             assertFinalSymlinkRejected(destinationPath, params.mutationSymlinks !== undefined);
             params.assertBeforeMutation?.();
             if (retainedSelection) {
-                assertRootWriteSelectionSync(root, retainedSelection, !target.createdForWrite);
+                assertRootWriteSelectionSync(root, retainedSelection, true);
+            }
+            else if (missingSelection) {
+                assertRootWritePathSelectionSync(root, missingSelection);
+            }
+            assertRootIdentityCurrentSync(root);
+            assertSyncDirectoryGuard(destinationGuard);
+            const current = inspectFallbackReplacementDestination(destinationPath);
+            if (publicationIdentity ? !current || !sameFileIdentity(current, publicationIdentity) : current) {
+                throw new FsSafeError("path-mismatch", "write destination changed before publication");
             }
             await fs.rename(commitTempPath, destinationPath);
             tempPath = null;
-            published = true;
         });
         unregisterTempPath();
         unregisterTempPath = null;
@@ -1308,12 +1318,8 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         });
     }
     finally {
-        if (!published && target.createdForWrite) {
-            await cleanupPinnedFilePath({
-                pathname: destinationPath, handle: target.handle, identity: placeholderIdentity, parentGuard: destinationGuard,
-            });
-        }
-        await target.handle.close().catch(() => undefined);
+        await target?.handle.close().catch(() => undefined);
+        await lateTargetHandle?.close().catch(() => undefined);
         if (tempPath && writtenHandle) {
             await cleanupPinnedFilePath({
                 pathname: tempPath, handle: writtenHandle, identity: writtenIdentity, parentGuard: destinationGuard,
@@ -1323,6 +1329,23 @@ async function writeFileFallbackUnlocked(root, params, expectedWritePath) {
         unregisterTempPath?.();
     }
 }
+function inspectFallbackReplacementDestination(targetPath) {
+    let current;
+    try {
+        current = inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            return;
+        throw error;
+    }
+    if (current.isSymbolicLink() || !current.isFile()) {
+        throw new FsSafeError("path-mismatch", "write destination changed before publication");
+    }
+    if (current.nlink > 1n)
+        throw hardlinkedPathNotAllowedError();
+    return current;
+}
 async function writeMissingFileFallback(root, params, expectedWritePath) {
     const guardedTarget = params.denyMutations === undefined && params.mutationSymlinks === undefined
         ? undefined

package/dist/root-move-noreplace.d.ts

@@ -13,4 +13,3 @@ export declare function movePathNoReplaceNative(root: RootContext, params: {
     targetPath: string;
     targetParentPath: string;
 }): Promise<void>;
-//# sourceMappingURL=root-move-noreplace.d.ts.map

package/dist/root-move-preflight.d.ts

@@ -5,4 +5,3 @@ export declare function assertMoveMutationAllowed(root: RootContext, params: {
     toRelative: string;
     denyMutations?: DenyMutationPolicy;
 }): Promise<void>;
-//# sourceMappingURL=root-move-preflight.d.ts.map

package/dist/root-observed-path.d.ts

@@ -6,4 +6,3 @@ export type PinnedObservedPath = {
     receipt?: RootPathObservationReceipt;
 };
 export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath | undefined>;
-//# sourceMappingURL=root-observed-path.d.ts.map

package/dist/root-options.d.ts

@@ -82,4 +82,3 @@ export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "deny
 export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
 export declare function readDefaults(defaults: RootDefaults): RootReadParams;
 export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;
-//# sourceMappingURL=root-options.d.ts.map

package/dist/root-path-errors.d.ts

@@ -10,4 +10,3 @@ export declare function symlinkEscapeError(params: {
     rootCanonicalPath: string;
     symlinkPath: string;
 }): Error;
-//# sourceMappingURL=root-path-errors.d.ts.map

package/dist/root-path-existing.d.ts

@@ -7,4 +7,6 @@ export declare function rawPathRelativeToCanonicalRoot(candidate: string, rootCa
 }): string | undefined;
 export declare function resolvePathViaExistingAncestor(targetPath: string): Promise<string>;
 export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
-//# sourceMappingURL=root-path-existing.d.ts.map
+export type RootPathMetadataMode = "native" | "ordinary";
+export declare function resolveExistingAncestor(targetPath: string, mode: RootPathMetadataMode): string;
+export declare function resolveSymlinkHopPath(symlinkPath: string, mode: RootPathMetadataMode, rejectUnresolved?: boolean): string;

package/dist/root-path-existing.js

@@ -2,9 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
 import { realpathSync } from "./realpath.js";
-import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 export function absolutePathWithRawSegments(candidate) {
     if (path.sep !== "\\") {
@@ -81,9 +81,6 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
     }
     return undefined;
 }
-function isFilesystemRoot(candidate) {
-    return path.parse(candidate).root === candidate;
-}
 function pathExists(targetPath) {
     try {
         return fs.lstatSync(pathForWindowsFilesystem(targetPath), { throwIfNoEntry: false }) !== undefined;
@@ -96,28 +93,25 @@ function pathExists(targetPath) {
     }
 }
 export async function resolvePathViaExistingAncestor(targetPath) {
-    return resolveExistingAncestor(targetPath, pathExists, realpathSync.native);
+    return resolveExistingAncestor(targetPath, "native");
 }
 function pathExistsSync(targetPath) {
     return fs.existsSync(pathForWindowsFilesystem(targetPath));
 }
 export function resolvePathViaExistingAncestorSync(targetPath) {
-    return resolveExistingAncestor(targetPath, pathExistsSync, realpathSync);
+    return resolveExistingAncestor(targetPath, "ordinary");
 }
-function resolveExistingAncestor(targetPath, exists, canonicalize) {
+export function resolveExistingAncestor(targetPath, mode) {
+    const exists = mode === "native" ? pathExists : pathExistsSync;
+    const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
     assertNoWindowsPathAlias(targetPath);
     const normalized = resolvePathPreservingWindowsRoot(targetPath);
     assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) &&
+    const filesystemRoot = path.parse(normalized).root;
+    while (cursor !== filesystemRoot &&
         !exists(cursor)) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
+        cursor = path.dirname(cursor);
     }
     if (!exists(cursor)) {
         return normalized;
@@ -132,9 +126,36 @@ function resolveExistingAncestor(targetPath, exists, canonicalize) {
     assertNoWindowsPathAlias(rawResolvedAncestor);
     const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
     assertNoWindowsPathAlias(resolvedAncestor);
-    const resolved = missingSuffix.length === 0
+    // Keep a leading suffix separator relative to the canonical ancestor.
+    const resolved = cursor === normalized
         ? resolvedAncestor
-        : path.resolve(resolvedAncestor, ...missingSuffix);
+        : path.resolve(resolvedAncestor, `.${path.sep}${normalized.slice(cursor.length)}`);
     assertNoWindowsPathAlias(resolved);
     return resolved;
 }
+export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
+    try {
+        const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+        const rawRealPath = canonicalize(symlinkPath);
+        assertNoWindowsPathAlias(rawRealPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        const realPath = resolvePathPreservingWindowsRoot(rawRealPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return realPath;
+    }
+    catch (error) {
+        if (isSymlinkOpenError(error) || (rejectUnresolved && isNotFoundPathError(error))) {
+            throw new FsSafeError("symlink", "symlink path could not be resolved", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        if (!isNotFoundPathError(error))
+            throw error;
+        const linkTarget = fs.readlinkSync(symlinkPath);
+        assertNoWindowsPathAlias(linkTarget, "filesystem", "symlink target uses a Windows filesystem namespace alias");
+        const linkDir = resolvePathPreservingWindowsRoot(path.dirname(symlinkPath));
+        const targetPath = resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget);
+        const resolved = resolveExistingAncestor(targetPath, mode);
+        assertNoWindowsPathAlias(resolved, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return resolved;
+    }
+}

package/dist/root-path-observation.d.ts

@@ -60,4 +60,3 @@ export type RootPathTraversalContext = {
 export declare function createRootPathTraversalObservation(context: RootPathTraversalContext, request?: RootPathObservationRequest): RootPathTraversalObservation | undefined;
 export declare function inspectRootPathTraversalEntry(pathname: string, directorySlot: boolean, observation: RootPathTraversalObservation): RootPathObservedTraversalEntry;
 export declare function captureRootPathObservedDirectory(observation: RootPathTraversalObservation, observed: RootPathObservedTraversalEntry, publicPath: string, canonicalPath: string, rootCanonicalPath: string, rootIdentity?: RootBoundaryIdentity): boolean;
-//# sourceMappingURL=root-path-observation.d.ts.map

package/dist/root-path-stat.d.ts

@@ -2,4 +2,3 @@ import type { RootContext } from "./root-context.js";
 import type { RootPathObservationReceipt } from "./root-path.js";
 import type { PathStat } from "./types.js";
 export declare function statResolvedPathInRoot(root: RootContext, resolvedPath: string, receipt?: RootPathObservationReceipt): Promise<PathStat>;
-//# sourceMappingURL=root-path-stat.d.ts.map

package/dist/root-path.d.ts

@@ -51,4 +51,3 @@ export declare function resolveRootPathWithObservation(params: ResolveRootPathPa
 export declare function resolveRootPathForRemoval(params: ResolveRootPathParams, receipts: RemovalPathReceipts): Promise<ResolvedRootPath>;
 export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
 export declare function resolveRootPathSyncWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): ResolvedRootPath;
-//# sourceMappingURL=root-path.d.ts.map