@openclaw/fs-safe 0.17.0 → 0.18.0

package/dist/root-path.js

@@ -5,10 +5,9 @@ import { pathEscapeError, sanitizeRootPathError, symlinkEscapeError } from "./ro
 import { FsSafeError } from "./errors.js";
 import { isNativeDirectoryObservationGuard } from "./native-directory-observation.js";
 import { assertNoNulPathInput, isNotFoundPathError, isPathRelativeEscape, } from "./path.js";
-import { absolutePathWithRawSegments, rawPathRelativeToCanonicalRoot, resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+import { absolutePathWithRawSegments, rawPathRelativeToCanonicalRoot, resolveExistingAncestor, resolveSymlinkHopPath, } from "./root-path-existing.js";
 import { admitPathInsideRoot, } from "./root-boundary.js";
 import { RootPathObservationError, captureRootPathObservedDirectory, createRootPathTraversalObservation, inspectRootPathTraversalEntry, } from "./root-path-observation.js";
-import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
 import { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
@@ -24,85 +23,35 @@ export const ROOT_PATH_ALIAS_POLICIES = {
     }),
 };
 export async function resolveRootPath(params) {
-    try {
-        return await resolveRootPathInternal(params);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params);
 }
 export async function resolveRootPathWithCanonicalRootObservation(params, observeRoot) {
-    try {
-        return await resolveRootPathInternal(params, undefined, undefined, observeRoot);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
-}
-async function resolveRootPathInternal(params, observationRequest, observationOutput, observeRoot, removalReceipts) {
-    const input = captureValidRootPathInputs(params);
-    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
-    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
-    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
-    const rootCanonicalPath = input.rootCanonicalPath
-        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
-        : await resolvePathViaExistingAncestor(rootPath);
-    assertNoWindowsPathAlias(rootPath);
-    assertNoWindowsPathAlias(absolutePath);
-    assertNoWindowsPathAlias(rootCanonicalPath);
-    observeRoot?.(rootCanonicalPath);
-    return resolveRootPathLexicalAsync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath), observationRequest, observationOutput, removalReceipts);
+    return resolveRootPathInternal(params, { observeRoot });
 }
 export async function resolveRootPathWithObservation(params, request) {
-    const output = {};
-    try {
-        const resolved = await resolveRootPathInternal(params, request, output);
-        return output.receipt ? { resolved, receipt: output.receipt } : { resolved };
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    const observation = { request };
+    const resolved = resolveRootPathInternal(params, { observation });
+    return observation.receipt ? { resolved, receipt: observation.receipt } : { resolved };
 }
 // Removal receipts are separate from metadata observations and canonical-root
 // callbacks; the public resolver's options and result remain unchanged.
 export async function resolveRootPathForRemoval(params, receipts) {
-    try {
-        return await resolveRootPathInternal(params, undefined, undefined, undefined, receipts);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params, { removalReceipts: receipts });
 }
 export function resolveRootPathSync(params) {
-    try {
-        return resolveRootPathSyncInternal(params);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params, { mode: "ordinary" });
 }
 export function resolveRootPathSyncWithCanonicalRootObservation(params, observeRoot) {
+    return resolveRootPathInternal(params, { mode: "ordinary", observeRoot });
+}
+function resolveRootPathInternal(params, options = {}) {
     try {
-        return resolveRootPathSyncInternal(params, observeRoot);
+        return traverseRootPath(params, options);
     }
     catch (error) {
         throw sanitizeRootPathError(error);
     }
 }
-function resolveRootPathSyncInternal(params, observeRoot) {
-    const input = captureValidRootPathInputs(params);
-    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
-    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
-    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
-    const rootCanonicalPath = input.rootCanonicalPath
-        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
-        : resolvePathViaExistingAncestorSync(rootPath);
-    assertNoWindowsPathAlias(rootPath);
-    assertNoWindowsPathAlias(absolutePath);
-    assertNoWindowsPathAlias(rootCanonicalPath);
-    observeRoot?.(rootCanonicalPath);
-    return resolveRootPathLexicalSync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath));
-}
 function prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath) {
     let raw = rawAbsolutePath;
     let trustedAbsolutePath = false;
@@ -173,27 +122,23 @@ function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     const root = path.parse(filePath).root;
     assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
 }
-function createLexicalTraversalState(params) {
-    const rawAbsolutePath = params.rawAbsolutePath;
-    const relative = admitRawPathInsideRoot(params.rootPath, rawAbsolutePath, params.params.rootIdentity)?.relativePath;
+function createLexicalTraversalContext(params) {
+    const relative = admitRawPathInsideRoot(params.rootPath, params.rawAbsolutePath, params.params.rootIdentity)?.relativePath;
     if (relative === undefined)
         throw new Error("Path traversal must begin at the root");
     const segments = splitTraversalSegments(relative);
     return {
-        segments,
-        relativePath: relative,
-        reuseLexicalCanonical: false,
-        finalComponentIndex: segments.findLastIndex((segment) => segment !== "."),
-        allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
-        canonicalCursor: params.rootCanonicalPath,
-        lexicalCursor: params.rootPath,
-        preserveFinalSymlink: false,
-        missingDepth: 0,
-    };
-}
-function createLexicalTraversalContext(params) {
-    return {
-        state: createLexicalTraversalState(params),
+        state: {
+            segments,
+            relativePath: relative,
+            reuseLexicalCanonical: false,
+            finalComponentIndex: segments.findLastIndex((segment) => segment !== "."),
+            allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
+            canonicalCursor: params.rootCanonicalPath,
+            lexicalCursor: params.rootPath,
+            preserveFinalSymlink: false,
+            missingDepth: 0,
+        },
         resolveParams: params.params,
         rootPath: params.rootPath,
         rootCanonicalPath: params.rootCanonicalPath,
@@ -263,29 +208,15 @@ function disableLexicalTraversalObservation(context, observation) {
 }
 function finalizeLexicalResolution(context, kind) {
     context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
-    return buildResolvedRootPath({
+    return {
         absolutePath: context.absolutePath,
         canonicalPath: context.state.canonicalCursor,
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
-        kind,
-    });
-}
-function handleLexicalLstatFailure(context, error, segment) {
-    if (!isNotFoundPathError(error)) {
-        return false;
-    }
-    advanceCanonicalCursorForSegment(context, segment);
-    context.state.missingDepth = 1;
-    return true;
-}
-function lexicalStatDisposition(params) {
-    if (!params.isSymbolicLink)
-        return "continue";
-    if (params.rejectFinalSymlink || (params.rejectSymlinks === true && params.isLast)) {
-        throw new FsSafeError("symlink", "symlink path component not allowed");
-    }
-    return params.allowFinalSymlink && params.isLast ? "break" : "resolve-link";
+        relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
+        exists: kind.exists,
+        kind: kind.kind,
+    };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
     let admitted;
@@ -319,10 +250,23 @@ function assertResolvedLinkDirectory(pathname, isLast) {
     const stat = fs.statSync(pathForWindowsFilesystem(pathname));
     assertDirectoryBeforeMoreSegments(stat, pathname, isLast);
 }
-async function resolveRootPathLexicalAsync(params, observationRequest, observationOutput, removalReceipts) {
-    const context = createLexicalTraversalContext(params);
+// Both public APIs use synchronous metadata; only canonicalization and ancestor
+// existence differ. Promise wrappers preserve the asynchronous rejection API.
+function traverseRootPath(params, { mode = "native", observation: observationOutput, observeRoot, removalReceipts }) {
+    const input = captureValidRootPathInputs(params);
+    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
+    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
+    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
+    const rootCanonicalPath = input.rootCanonicalPath
+        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
+        : resolveExistingAncestor(rootPath, mode);
+    assertNoWindowsPathAlias(rootPath);
+    assertNoWindowsPathAlias(absolutePath);
+    assertNoWindowsPathAlias(rootCanonicalPath);
+    observeRoot?.(rootCanonicalPath);
+    const context = createLexicalTraversalContext(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath));
     const { state } = context;
-    const observation = createLexicalTraversalObservation(context, observationRequest);
+    const observation = createLexicalTraversalObservation(context, observationOutput?.request);
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
@@ -374,9 +318,11 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
                 // Preserve observation-only versus ordinary traversal error precedence.
                 throw new RootPathObservationError(error instanceof RootPathObservationError ? error.error : sanitizeRootPathError(error), parentReceipt, !(error instanceof RootPathObservationError));
             }
-            if (handleLexicalLstatFailure(context, error, segment))
-                continue;
-            throw error;
+            if (!isNotFoundPathError(error))
+                throw error;
+            advanceCanonicalCursorForSegment(context, segment);
+            state.missingDepth = 1;
+            continue;
         }
         if (isNativeDirectoryObservationGuard(observed)) {
             advanceCanonicalCursorForSegment(context, segment);
@@ -392,15 +338,13 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
         const isSymbolicLink = stat.isSymbolicLink();
         if (!isSymbolicLink)
             assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            rejectFinalSymlink: context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
+        if (isSymbolicLink && ((context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex) ||
+            (context.resolveParams.rejectSymlinks === true && isLast))) {
+            throw new FsSafeError("symlink", "symlink path component not allowed");
+        }
+        const preserveFinalSymlink = isSymbolicLink && state.allowFinalSymlink && isLast;
+        if (!isSymbolicLink || preserveFinalSymlink) {
+            state.preserveFinalSymlink = preserveFinalSymlink;
             advanceCanonicalCursorForSegment(context, segment);
             if (observation?.enabled && isSymbolicLink) {
                 disableLexicalTraversalObservation(context, observation);
@@ -420,9 +364,7 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
         }
         if (observation?.enabled)
             disableLexicalTraversalObservation(context, observation);
-        const linkCanonical = await resolveSymlinkHopPath(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
+        const linkCanonical = resolveSymlinkHopPath(state.lexicalCursor, mode, context.resolveParams.rejectUnresolvedSymlinks);
         applyResolvedSymlinkHop(context, linkCanonical);
         if (context.resolveParams.rejectSymlinks === true) {
             throw new FsSafeError("symlink", "symlink path component not allowed");
@@ -438,7 +380,7 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
                 ? "directory"
                 : toResolvedKind(observation.target.stat),
         }
-        : await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
+        : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
             kind: observation.request.kind,
@@ -451,76 +393,6 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
     }
     return finalizeLexicalResolution(context, kind);
 }
-function resolveRootPathLexicalSync(params) {
-    const context = createLexicalTraversalContext(params);
-    const { state } = context;
-    for (let idx = 0; idx < state.segments.length; idx += 1) {
-        const segment = state.segments[idx] ?? "";
-        const isLast = idx === state.segments.length - 1;
-        if (segment === ".")
-            continue;
-        if (segment === "..") {
-            applyParentTraversalStep(context);
-            continue;
-        }
-        state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        if (state.missingDepth > 0) {
-            advanceCanonicalCursorForSegment(context, segment);
-            state.missingDepth += 1;
-            continue;
-        }
-        let stat;
-        try {
-            stat = fs.lstatSync(state.lexicalCursor);
-        }
-        catch (error) {
-            if (handleLexicalLstatFailure(context, error, segment))
-                continue;
-            throw error;
-        }
-        const isSymbolicLink = stat.isSymbolicLink();
-        if (!isSymbolicLink)
-            assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            rejectFinalSymlink: context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
-            advanceCanonicalCursorForSegment(context, segment);
-            if (state.preserveFinalSymlink)
-                break;
-            continue;
-        }
-        const linkCanonical = resolveSymlinkHopPathSync(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
-        applyResolvedSymlinkHop(context, linkCanonical);
-        if (context.resolveParams.rejectSymlinks === true) {
-            throw new FsSafeError("symlink", "symlink path component not allowed");
-        }
-        assertResolvedLinkDirectory(linkCanonical, isLast);
-    }
-    const kind = getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
-    return finalizeLexicalResolution(context, kind);
-}
-function buildResolvedRootPath(params) {
-    return {
-        absolutePath: params.absolutePath,
-        canonicalPath: params.canonicalPath,
-        rootPath: params.rootPath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        relativePath: relativeInsideRoot(params.rootCanonicalPath, params.canonicalPath),
-        exists: params.kind.exists,
-        kind: params.kind.kind,
-    };
-}
-async function getPathKind(absolutePath, preserveFinalSymlink) {
-    return getPathKindSync(absolutePath, preserveFinalSymlink);
-}
 function getPathKindSync(absolutePath, preserveFinalSymlink) {
     try {
         const operationPath = pathForWindowsFilesystem(absolutePath);

package/dist/root-paths-lexical.d.ts

@@ -6,4 +6,3 @@ export declare function resolvePathWithinRoot(params: ResolvePathWithinRootParam
     ok: false;
     error: string;
 };
-//# sourceMappingURL=root-paths-lexical.d.ts.map

package/dist/root-paths.d.ts

@@ -60,4 +60,3 @@ export declare function resolvePathsWithinRoot(params: ResolvePathsWithinRootPar
 export declare function resolveExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function resolveStrictExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
-//# sourceMappingURL=root-paths.d.ts.map

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

@@ -23,4 +23,3 @@ export declare function admitRootReadHandle<T extends OwnedRootReadHandle>(param
     realPath: string;
 }>;
 export {};
-//# sourceMappingURL=root-read-admission.d.ts.map

package/dist/root-read-admission.js

@@ -31,40 +31,6 @@ export function inspectOpenedPathIdentitySync(filePath, symlinks) {
     }
     return stat;
 }
-function assertRootReadAdmissionCurrent(params) {
-    assertRootIdentityCurrentSync(params.root);
-    const admittedPath = (() => {
-        try {
-            const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
-            if (params.hardlinks !== "allow" && current.nlink > 1n)
-                throw hardlinkedPathNotAllowedError();
-            const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
-            assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
-            const admittedRealPath = admitPathInsideRoot({
-                rootPath: params.root.rootReal,
-                candidatePath: canonicalPath,
-                rootIdentity: params.root.rootIdentity,
-            });
-            if (!admittedRealPath) {
-                throw openedPathResolutionError(outsideWorkspaceError());
-            }
-            // This is a fresh no-follow observation even when canonicalPath and
-            // filePath have the same spelling; realpath may have raced a replacement.
-            const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
-            if (params.hardlinks !== "allow" && canonical.nlink > 1n)
-                throw hardlinkedPathNotAllowedError();
-            return admittedRealPath.path;
-        }
-        catch (error) {
-            throw isNotFoundPathError(error)
-                ? openedPathResolutionError(fileNotFoundError())
-                : error;
-        }
-    })();
-    params.afterPathIdentityCheck?.(params.filePath, params.handle);
-    assertRootIdentityCurrentSync(params.root);
-    return admittedPath;
-}
 export async function admitRootReadHandle(params) {
     try {
         if (params.hardlinks !== "allow" && params.opened.stat.nlink > 1) {
@@ -74,16 +40,37 @@ export async function admitRootReadHandle(params) {
             await params.beforeFinalFence(params.filePath, params.opened.handle);
         }
         try {
-            const finalRealPath = assertRootReadAdmissionCurrent({
-                root: params.root,
-                filePath: params.filePath,
-                handle: params.opened.handle,
-                identity: params.identity,
-                hardlinks: params.hardlinks,
-                symlinks: params.symlinks,
-                afterPathIdentityCheck: params.afterPathIdentityCheck,
-            });
-            return { ...params.opened, realPath: finalRealPath };
+            assertRootIdentityCurrentSync(params.root);
+            let realPath;
+            try {
+                const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+                if (params.hardlinks !== "allow" && current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
+                assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+                const admittedRealPath = admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: canonicalPath,
+                    rootIdentity: params.root.rootIdentity,
+                });
+                if (!admittedRealPath) {
+                    throw openedPathResolutionError(outsideWorkspaceError());
+                }
+                // This is a fresh no-follow observation even when canonicalPath and
+                // filePath have the same spelling; realpath may have raced a replacement.
+                const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+                if (params.hardlinks !== "allow" && canonical.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                realPath = admittedRealPath.path;
+            }
+            catch (error) {
+                throw isNotFoundPathError(error)
+                    ? openedPathResolutionError(fileNotFoundError())
+                    : error;
+            }
+            params.afterPathIdentityCheck?.(params.filePath, params.opened.handle);
+            assertRootIdentityCurrentSync(params.root);
+            return { ...params.opened, realPath };
         }
         catch (error) {
             if (params.identity.nlink <= 1n) {

package/dist/root-remove-identity.d.ts

@@ -12,4 +12,3 @@ export type RemovalDirectoryAssertion = Readonly<{
 export declare function createRemovalDirectoryAssertion(path: string, identity: ExactDirectoryIdentity, realPath?: string, platform?: NodeJS.Platform): RemovalDirectoryAssertion;
 export declare function assertRemovalDirectoryCurrent(assertion: RemovalDirectoryAssertion): void;
 export {};
-//# sourceMappingURL=root-remove-identity.d.ts.map

package/dist/root-remove-receipt.d.ts

@@ -14,4 +14,3 @@ export declare class RemovalPathReceipts {
         directories: readonly CapturedRemovalDirectory[];
     } | undefined;
 }
-//# sourceMappingURL=root-remove-receipt.d.ts.map

package/dist/root-remove.d.ts

@@ -4,4 +4,3 @@ import type { RemovalPathReceipts } from "./root-remove-receipt.js";
 export declare const nonrecursiveRemovalKind: unique symbol;
 export declare function validateRemoveOptions(options: RootRemoveOptions): void;
 export declare function removePathInRootFallback(root: RootContext, targetPath: string, options: RootRemoveOptions, receipts?: RemovalPathReceipts): Promise<void>;
-//# sourceMappingURL=root-remove.d.ts.map

package/dist/root-symlink-policy.d.ts

@@ -11,4 +11,3 @@ export declare function mutationSymlinkResolution(symlinks: MutationSymlinkPolic
     resolveCanonical: boolean;
 };
 export declare function assertFinalSymlinkRejected(targetPath: string, reject: boolean | undefined, details?: FsSafeErrorDetails): void;
-//# sourceMappingURL=root-symlink-policy.d.ts.map

package/dist/root-walk.d.ts

@@ -39,4 +39,3 @@ type RootWalkCapability = {
 };
 export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
 export {};
-//# sourceMappingURL=root-walk.d.ts.map

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

@@ -63,4 +63,3 @@ export declare function resolveGuardedWritePathInRoot(root: RootContext, params:
 export declare function resolveGuardedWriteTargetInRoot(root: RootContext, params: GuardedWritePathOptions): Promise<GuardedRootWriteTarget>;
 export declare function resolvePinnedWriteTargetInRoot(root: RootContext, relativePath: string, requestedMode?: number, denyMutations?: DenyMutationPolicy, overwrite?: boolean, mutationSymlinks?: MutationSymlinkPolicy): Promise<PinnedWriteTarget>;
 export {};
-//# sourceMappingURL=root-write-admission.d.ts.map

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

@@ -9,4 +9,3 @@ export declare function withRootFallbackCompatibilityLock<T>(params: {
     relativePath: string;
     assertBeforeMutation: () => void;
 }) => Promise<T>): Promise<T>;
-//# sourceMappingURL=root-write-compatibility.d.ts.map

package/dist/root-write-complete-parent.d.ts

@@ -39,4 +39,3 @@ export type SharedRootWriteTarget = Readonly<{
 export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
 export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
 export {};
-//# sourceMappingURL=root-write-complete-parent.d.ts.map

package/dist/root-write-lock-binding.d.ts

@@ -12,4 +12,3 @@ export declare function createRootWriteLockBinding(params: Readonly<{
     assertCurrent: () => void;
     dispose(): void;
 }>;
-//# sourceMappingURL=root-write-lock-binding.d.ts.map

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

@@ -5,4 +5,3 @@ export declare function inheritWriteTargetMode(params: {
     rootIdentity?: RootBoundaryIdentity;
     requestedMode?: number;
 }): Promise<number>;
-//# sourceMappingURL=root-write-mode.d.ts.map

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

@@ -21,4 +21,3 @@ export declare function finishRootFallbackWrite(params: {
     }>;
     onVerificationFailure: (error: unknown) => void;
 }): Promise<void>;
-//# sourceMappingURL=root-write-publication.d.ts.map

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

@@ -9,4 +9,3 @@ export declare function verifyAtomicWriteResult(params: {
     expectedMode?: number;
     parentGuard: AnyAsyncDirectoryGuard;
 }): Promise<void>;
-//# sourceMappingURL=root-write-verification.d.ts.map

package/dist/root.d.ts

@@ -4,4 +4,3 @@ 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";
-//# sourceMappingURL=root.d.ts.map

package/dist/safe-path-segment.d.ts

@@ -7,6 +7,5 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
-export declare function sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;
+export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;
-//# sourceMappingURL=safe-path-segment.d.ts.map

package/dist/safe-path-segment.js

@@ -47,17 +47,14 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value, fallback, options = {}) {
+export function sanitizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
     const trimmed = trimHyphenEdges(sanitized);
-    if (isSafePathSegment(trimmed, options)) {
-        return trimmed;
-    }
-    return assertSafePathSegment(fallback, { ...options, label: "fallback path segment" });
+    return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {
     // Prefixes are often derived from safe filenames. Normalize harmless

package/dist/secret-file.d.ts

@@ -23,4 +23,3 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export {};
-//# sourceMappingURL=secret-file.d.ts.map

package/dist/secret-file.js

@@ -31,29 +31,19 @@ export function readSecretFileSync(filePath, label, options = {}) {
     }
     let raw;
     try {
-        const openedIdentity = inspectFileIdentitySync(() => {
-            const stat = fs.fstatSync(opened.fd, { bigint: true });
-            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
-                throw new FsSafeError("path-mismatch", "security validation failed");
-            }
-            return stat;
-        }, previewStat);
-        inspectFileIdentitySync(() => {
-            const stat = fs.lstatSync(opened.path, { bigint: true });
-            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
-                throw new FsSafeError("path-mismatch", "security validation failed");
-            }
-            return stat;
-        }, openedIdentity);
+        // The pin already compared the descriptor and resolved name without yielding.
+        const openedIdentity = inspectFileIdentitySync(() => opened.identity, previewStat);
         inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedIdentity);
         raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
     }
     catch (error) {
+        try {
+            fs.closeSync(opened.fd);
+        }
+        catch { /* Preserve the read failure. */ }
         throw secretReadError(error instanceof FsSafeError ? error.code : "read-failed", "read", label, resolvedPath, error);
     }
-    finally {
-        fs.closeSync(opened.fd);
-    }
+    fs.closeSync(opened.fd);
     return trimSecretFileContent(raw, label, resolvedPath);
 }
 export function tryReadSecretFileSync(filePath, label, options = {}) {

package/dist/secret-read-async.d.ts

@@ -1,4 +1,3 @@
 import { type SecretFileReadOptions } from "./secret-read-policy.js";
 export declare function readSecretFile(filePath: string, label: string, options?: SecretFileReadOptions): Promise<string>;
 export declare function tryReadSecretFile(filePath: string | undefined, label: string, options?: SecretFileReadOptions): Promise<string | undefined>;
-//# sourceMappingURL=secret-read-async.d.ts.map