@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-admission.js

@@ -0,0 +1,419 @@
+import path from "node:path";
+import { assertMutationNotDenied } from "./deny-mutations.js";
+import { FsSafeError } from "./errors.js";
+import { isPathInside } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { ordinarySharedAbsoluteInsideRoot, simpleSharedRoute, } from "./pinned-mutation-shared-route.js";
+import { resolvePathViaExistingAncestor } from "./root-path-existing.js";
+import { outsideWorkspaceError } from "./root-errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { advanceMutationObservation, mutationObservationCurrent, observeMutationPath, mutationObservationsCurrent, mutationObservationUsesDirectory, missingMutationSegments, nextMissingMutationPath, } from "./pinned-mutation-observation.js";
+export function snapshotPinnedMutationPolicy(denyMutations, mutationSymlinks) {
+    if (denyMutations === undefined && mutationSymlinks === undefined)
+        return undefined;
+    const denySnapshot = denyMutations === undefined ? undefined : Object.freeze({
+        paths: denyMutations.paths === undefined ? undefined : Object.freeze([...denyMutations.paths]),
+        prefixes: denyMutations.prefixes === undefined ? undefined : Object.freeze([...denyMutations.prefixes]),
+    });
+    return Object.freeze({ denyMutations: denySnapshot, mutationSymlinks });
+}
+async function canonicalMutationEntryPath(targetPath) {
+    const canonicalParent = await resolvePathViaExistingAncestor(path.dirname(targetPath));
+    return path.join(canonicalParent, path.basename(targetPath));
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function simplePinnedRoute(rootReal, originalPath) {
+    // These routes can depend on raw traversal, platform aliases, home expansion,
+    // or live native canonicalization. They retain full admission at every step.
+    if (!originalPath || process.platform === "win32" || process.versions.bun ||
+        originalPath.startsWith("~") || originalPath.includes("\\") || originalPath.includes("\0"))
+        return undefined;
+    const segments = originalPath.split("/");
+    if (segments.some((segment, index) => segment === "." || segment === ".." ||
+        (segment === "" && index !== 0)))
+        return undefined;
+    const target = path.resolve(rootReal, originalPath);
+    return isPathInside(rootReal, target) && target !== rootReal ? target : undefined;
+}
+function nonzeroObservationIdentity(observation) {
+    return observation.entry.dev !== 0n && observation.entry.ino !== 0n &&
+        observation.identity.dev !== 0n && observation.identity.ino !== 0n;
+}
+function captureEpoch(rootReal, target, policy, session) {
+    const observations = new Map();
+    const observe = (pathname) => {
+        if (!observations.has(pathname)) {
+            const observation = observeMutationPath(pathname);
+            if (!observation)
+                throw new Error("incomplete mutation observation");
+            observations.set(pathname, observation);
+        }
+        return observations.get(pathname);
+    };
+    try {
+        const root = observe(rootReal);
+        const route = observe(target);
+        // A canonical spelling alone cannot certify a route containing aliases.
+        if (root.canonicalPath !== rootReal || route.canonicalPath !== target ||
+            route.ancestor !== route.canonicalAncestor || route.entry.dev !== route.identity.dev ||
+            route.entry.ino !== route.identity.ino)
+            return undefined;
+        const comparables = (entries) => Object.freeze((entries ?? []).map((entry) => {
+            if (!entry || !path.isAbsolute(entry) || entry.includes("\0"))
+                throw new Error("invalid policy observation");
+            const resolved = path.resolve(entry);
+            if (session.kind === "shared" && (!session.rootIdentity || entry !== resolved ||
+                !ordinarySharedAbsoluteInsideRoot(rootReal, resolved, session.rootIdentity))) {
+                throw new Error("ineligible shared policy observation");
+            }
+            const observation = observe(resolved);
+            if (session.kind === "shared" && (observation.canonicalPath !== resolved ||
+                observation.ancestor !== observation.canonicalAncestor ||
+                !nonzeroObservationIdentity(observation))) {
+                throw new Error("incomplete shared policy observation");
+            }
+            return Object.freeze([resolved, observation.canonicalPath]);
+        }));
+        const paths = comparables(policy.denyMutations?.paths);
+        const prefixes = comparables(policy.denyMutations?.prefixes);
+        if (session.kind === "shared" && (!session.rootIdentity ||
+            root.entry.dev !== session.rootIdentity.dev || root.entry.ino !== session.rootIdentity.ino ||
+            root.identity.dev !== session.rootIdentity.dev || root.identity.ino !== session.rootIdentity.ino ||
+            !nonzeroObservationIdentity(root) || !nonzeroObservationIdentity(route)))
+            return undefined;
+        return Object.freeze({
+            mode: getFsSafeNativeConfig().mode, target: route, paths, prefixes,
+            observations: Object.freeze([...observations.values()]), session,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function epochCurrent(epoch, directories) {
+    return !process.versions.bun && epoch.mode === epoch.session.nativeMode &&
+        getFsSafeNativeConfig().mode === epoch.mode &&
+        (directories ? mutationObservationsCurrent(epoch.observations, directories) :
+            epoch.observations.every(mutationObservationCurrent)) &&
+        getFsSafeNativeConfig().mode === epoch.mode;
+}
+function assertCachedNotDenied(target, epoch) {
+    if (epoch.paths.some((paths) => paths.some((denied) => isPathInside(denied, target) && isPathInside(target, denied))) ||
+        epoch.prefixes.some((paths) => paths.some((denied) => isPathInside(denied, target)))) {
+        throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+    }
+}
+function reusableRequest(request, epoch) {
+    return request.targetPath === epoch.target.path &&
+        ((request.phase === "parent" && request.mutationPath === request.targetPath) ||
+            (request.phase === "parent-create" && missingMutationSegments(epoch.target) > 1 &&
+                request.mutationPath === nextMissingMutationPath(epoch.target)));
+}
+function reusableSharedCreateRequest(request, epoch) {
+    return request.phase === "parent-create" && request.targetPath === epoch.target.path &&
+        request.mutationPath === nextMissingMutationPath(epoch.target);
+}
+function reusableSharedRequest(request, epoch) {
+    return request.phase === "parent"
+        ? request.targetPath === epoch.target.path && request.mutationPath === request.targetPath
+        : reusableSharedCreateRequest(request, epoch);
+}
+function nonzeroDirectoryObservation(observation) {
+    return observation.identity.dev !== 0n && observation.identity.ino !== 0n;
+}
+function advanceAuthorizedDirectory(admittedEpoch, admitted, receipt) {
+    if (!admittedEpoch || !admitted || receipt.admission !== admitted ||
+        admitted.epoch !== admittedEpoch || admitted.session !== admittedEpoch.session ||
+        admitted.childPath !== receipt.child.path ||
+        (admittedEpoch.session.kind === "shared" &&
+            (!nonzeroDirectoryObservation(receipt.parent) ||
+                !nonzeroDirectoryObservation(receipt.child))))
+        return undefined;
+    // The walker calls this only after its live parent fence, exact-parent deny,
+    // authority callback, successful mkdir, and exact child checks.
+    const observations = admittedEpoch.observations.map((observation) => advanceMutationObservation(observation, receipt.parent, receipt.child));
+    if (observations.some((observation) => !observation))
+        return undefined;
+    const complete = observations;
+    const target = complete.find((observation) => observation.path === admittedEpoch.target.path);
+    if (!target || target.missingOffset !== admittedEpoch.target.missingOffset + 1)
+        return undefined;
+    const next = Object.freeze({
+        ...admittedEpoch,
+        target,
+        observations: Object.freeze(complete),
+    });
+    if (!mutationObservationUsesDirectory(target, receipt.child) ||
+        !epochCurrent(next, [receipt.parent, receipt.child]))
+        return undefined;
+    assertCachedNotDenied(target.path, next);
+    assertCachedNotDenied(receipt.child.path, next);
+    return next;
+}
+export async function preparePinnedWriteMutationAdmission(params) {
+    if (!params.policy) {
+        return { relativeParentPath: params.defaultRelativeParentPath };
+    }
+    const policy = params.policy;
+    const route = simplePinnedRoute(params.rootReal, params.originalPath);
+    const sharedRoute = simpleSharedRoute({
+        rootReal: params.rootReal,
+        rootIdentity: params.rootIdentity,
+        originalPath: params.originalPath,
+        selectedTarget: params.resolvedTargetPath,
+        policy,
+    });
+    const nativeRoute = sharedRoute ?? (process.platform === "win32" && params.originalPath?.includes("/")
+        ? simpleSharedRoute({ rootReal: params.rootReal, rootIdentity: params.rootIdentity,
+            originalPath: params.originalPath.replaceAll("/", "\\"), selectedTarget: params.resolvedTargetPath, policy })
+        : undefined);
+    let pinnedSession;
+    let epoch;
+    let pending;
+    const observedCanonicalParent = await resolvePathViaExistingAncestor(path.dirname(params.resolvedTargetPath));
+    const admittedCanonicalParent = admitPathInsideRoot({
+        rootPath: params.rootReal,
+        candidatePath: observedCanonicalParent,
+        rootIdentity: params.rootIdentity,
+    });
+    if (!admittedCanonicalParent)
+        throw outsideWorkspaceError();
+    const relativeCanonicalParent = admittedCanonicalParent.relativePath;
+    const authorizeFully = async (request) => {
+        // Preserve the original route's symlink/deny error ordering, then apply
+        // the same snapshot to the object-bound destination selected below.
+        const current = await params.resolveCurrent();
+        await assertMutationNotDenied(request.targetPath, policy.denyMutations);
+        if (!sameAbsolutePath(request.targetPath, request.mutationPath)) {
+            await assertMutationNotDenied(request.mutationPath, policy.denyMutations);
+        }
+        const [currentTarget, admittedTarget] = await Promise.all([
+            canonicalMutationEntryPath(current.resolved),
+            canonicalMutationEntryPath(request.targetPath),
+        ]);
+        if (!sameAbsolutePath(currentTarget, admittedTarget)) {
+            throw new FsSafeError("path-mismatch", "write target changed during mutation policy admission");
+        }
+        return current;
+    };
+    const createSharedParentWalk = (admittedRoute) => {
+        const session = Object.freeze({
+            kind: "shared",
+            route: admittedRoute.route,
+            selectedTarget: params.resolvedTargetPath,
+            nativeMode: getFsSafeNativeConfig().mode,
+            rootIdentity: admittedRoute.rootIdentity,
+            authorizationToken: Object.freeze({}),
+        });
+        let disposed = false;
+        let disabled = false;
+        let sharedEpoch;
+        let sharedPending;
+        const disable = () => {
+            disabled = true;
+            sharedEpoch = undefined;
+            sharedPending = undefined;
+        };
+        return Object.freeze({
+            retainedTargetPath: session.route,
+            tryAuthorizeAtParent(request, parent) {
+                if (disposed || disabled)
+                    return undefined;
+                // The walk's first missing component has no receipt epoch yet. Treat
+                // that as an ordinary cache miss so authorize() can bracket the full
+                // ordered admission and seed this session.
+                if (!sharedEpoch && !sharedPending)
+                    return undefined;
+                // A receipt must be consumed by the exact mkdir/advance pair before
+                // another parent-bound authorization can be attempted.
+                if (sharedPending) {
+                    disable();
+                    return undefined;
+                }
+                const reusable = sharedEpoch;
+                if (!reusable || reusable.session !== session ||
+                    !reusableSharedCreateRequest(request, reusable) ||
+                    !mutationObservationUsesDirectory(reusable.target, parent) ||
+                    !nonzeroDirectoryObservation(parent) || !epochCurrent(reusable, [parent])) {
+                    disable();
+                    return undefined;
+                }
+                assertCachedNotDenied(request.targetPath, reusable);
+                assertCachedNotDenied(request.mutationPath, reusable);
+                // The epoch check ends with the exact parent fence. The receipt is
+                // consumed synchronously before any intervening authority callback.
+                sharedPending = Object.freeze({
+                    epoch: reusable,
+                    childPath: request.mutationPath,
+                    session,
+                });
+                return sharedPending;
+            },
+            async authorize(request) {
+                // A create receipt reaching a full before-use admission means mkdir
+                // did not yield owned, complete post-create evidence (including
+                // EEXIST). The rest of this walk stays on ordered admission.
+                if (sharedPending)
+                    disable();
+                const reusable = sharedEpoch;
+                if (!disposed && !disabled && reusable?.session === session &&
+                    reusableSharedRequest(request, reusable) && epochCurrent(reusable)) {
+                    assertCachedNotDenied(request.targetPath, reusable);
+                    assertCachedNotDenied(request.mutationPath, reusable);
+                    return undefined;
+                }
+                if (reusable)
+                    disable();
+                const captureRequested = !disposed && !disabled &&
+                    request.targetPath === session.route;
+                const candidate = captureRequested
+                    ? captureEpoch(params.rootReal, session.route, policy, session)
+                    : undefined;
+                if (captureRequested &&
+                    (!candidate || !reusableSharedRequest(request, candidate)))
+                    disable();
+                const current = await authorizeFully(request);
+                if (disposed || disabled || !candidate) {
+                    sharedEpoch = undefined;
+                    return undefined;
+                }
+                if (current.resolved !== session.route ||
+                    current.resolved !== session.selectedTarget || !epochCurrent(candidate)) {
+                    disable();
+                    return undefined;
+                }
+                // Observations bracket the ordered admission. Never attach a receipt
+                // to evidence collected only after the policy decisions it replaces.
+                sharedEpoch = candidate;
+                if (request.phase === "parent")
+                    return undefined;
+                sharedPending = Object.freeze({
+                    epoch: candidate,
+                    childPath: request.mutationPath,
+                    session,
+                });
+                return sharedPending;
+            },
+            advanceCreatedDirectory(receipt) {
+                const admitted = sharedPending;
+                const admittedEpoch = sharedEpoch;
+                sharedPending = undefined;
+                sharedEpoch = undefined;
+                if (disposed || disabled || admittedEpoch?.session !== session) {
+                    disable();
+                    return undefined;
+                }
+                const next = advanceAuthorizedDirectory(admittedEpoch, admitted, receipt);
+                if (!next) {
+                    disable();
+                    return undefined;
+                }
+                sharedEpoch = next;
+                return session.authorizationToken;
+            },
+            dispose() {
+                disposed = true;
+                disable();
+            },
+        });
+    };
+    const mutationAdmission = Object.freeze({
+        rejectParentSymlinks: policy.mutationSymlinks === "reject",
+        beginParentWalk: route ? () => {
+            pinnedSession = Object.freeze({
+                kind: "pinned",
+                route,
+                selectedTarget: params.resolvedTargetPath,
+                nativeMode: getFsSafeNativeConfig().mode,
+                authorizationToken: Object.freeze({}),
+            });
+            epoch = undefined;
+            pending = undefined;
+            return route;
+        } : undefined,
+        beginSharedParentWalk: sharedRoute ? () => createSharedParentWalk(sharedRoute) : undefined,
+        beginNativeParentWalk: nativeRoute ? () => createSharedParentWalk(nativeRoute) : undefined,
+        tryAuthorizeAtParent(request, parent) {
+            pending = undefined;
+            const reusable = epoch;
+            if (!reusable || reusable.session !== pinnedSession ||
+                !reusableRequest(request, reusable) ||
+                !mutationObservationUsesDirectory(reusable.target, parent) ||
+                !epochCurrent(reusable, [parent])) {
+                epoch = undefined;
+                return undefined;
+            }
+            assertCachedNotDenied(request.targetPath, reusable);
+            assertCachedNotDenied(request.mutationPath, reusable);
+            // The epoch check ends at the exact parent pathname, canonical spelling,
+            // identity, type, mode and link-count fence, with no intervening await.
+            if (request.phase === "parent-create") {
+                pending = Object.freeze({
+                    epoch: reusable,
+                    childPath: request.mutationPath,
+                    session: reusable.session,
+                });
+                return pending;
+            }
+            return reusable.session.authorizationToken;
+        },
+        async authorize(request) {
+            pending = undefined;
+            if (epoch && epoch.session === pinnedSession &&
+                reusableRequest(request, epoch) && epochCurrent(epoch)) {
+                assertCachedNotDenied(request.targetPath, epoch);
+                assertCachedNotDenied(request.mutationPath, epoch);
+                if (request.phase === "parent-create") {
+                    pending = Object.freeze({
+                        epoch,
+                        childPath: request.mutationPath,
+                        session: epoch.session,
+                    });
+                    return pending;
+                }
+                return undefined;
+            }
+            epoch = undefined;
+            const session = pinnedSession;
+            const candidate = session && route === request.targetPath
+                ? captureEpoch(params.rootReal, route, policy, session) : undefined;
+            const current = await authorizeFully(request);
+            // Observations bracket the ordered admission. Never attach a cache to
+            // evidence collected only after the policy decisions it would replace.
+            if (candidate && candidate.session === pinnedSession &&
+                current.resolved === route && epochCurrent(candidate)) {
+                epoch = candidate;
+                if (request.phase === "parent-create" && reusableRequest(request, candidate)) {
+                    pending = Object.freeze({
+                        epoch: candidate,
+                        childPath: request.mutationPath,
+                        session: candidate.session,
+                    });
+                    return pending;
+                }
+            }
+            return undefined;
+        },
+        advanceCreatedDirectory: route ? (receipt) => {
+            const admitted = pending;
+            pending = undefined;
+            const admittedEpoch = epoch;
+            // Completion is fail-closed: no partially checked candidate remains
+            // reusable if any provenance, observation, or freshness check fails.
+            epoch = undefined;
+            const next = advanceAuthorizedDirectory(admittedEpoch, admitted, receipt);
+            if (!next)
+                return undefined;
+            epoch = next;
+            return next.session.authorizationToken;
+        } : undefined,
+    });
+    return {
+        relativeParentPath: relativeCanonicalParent
+            ? relativeCanonicalParent.split(path.sep).join(path.posix.sep)
+            : "",
+        mutationAdmission,
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-observation.d.ts

@@ -0,0 +1,38 @@
+import { type BigIntStats } from "node:fs";
+export type MutationIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    mode: bigint;
+    nlink: bigint;
+}>;
+declare const checkedDirectoryObservation: unique symbol;
+export type MutationDirectoryCurrent = Readonly<{
+    canonicalPath: string;
+    identity: MutationIdentity;
+}>;
+export type MutationDirectoryObserver = () => MutationDirectoryCurrent | undefined;
+export type MutationDirectoryObservation = Readonly<{
+    path: string;
+    canonicalPath: string;
+    identity: MutationIdentity;
+    [checkedDirectoryObservation]: true;
+}>;
+export type MutationPathObservation = Readonly<{
+    path: string;
+    ancestor: string;
+    canonicalAncestor: string;
+    canonicalPath: string;
+    entry: MutationIdentity;
+    identity: MutationIdentity;
+    missingSegments: readonly string[];
+    missingOffset: number;
+}>;
+export declare function missingMutationSegments(observation: MutationPathObservation): number;
+export declare function nextMissingMutationPath(observation: MutationPathObservation): string | undefined;
+export declare function checkedMutationDirectory(pathname: string, canonicalPath: string, stat: Pick<BigIntStats, "dev" | "ino" | "mode" | "nlink">, observeCurrent?: MutationDirectoryObserver): MutationDirectoryObservation;
+export declare function mutationObservationUsesDirectory(observation: MutationPathObservation, directory: MutationDirectoryObservation): boolean;
+export declare function observeMutationPath(pathname: string): MutationPathObservation | undefined;
+export declare function mutationObservationCurrent(observation: MutationPathObservation): boolean;
+export declare function mutationObservationsCurrent(observations: readonly MutationPathObservation[], directories: readonly MutationDirectoryObservation[]): boolean;
+export declare function advanceMutationObservation(observation: MutationPathObservation, parent: MutationDirectoryObservation, child: MutationDirectoryObservation): MutationPathObservation | undefined;
+export {};

package/node_modules/@openclaw/fs-safe/dist/pinned-mutation-observation.js

@@ -0,0 +1,205 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+const checkedDirectoryObservation = Symbol("checked mutation directory observation");
+const directoryObservers = new WeakMap();
+function identity(stat) {
+    return Object.freeze({ dev: stat.dev, ino: stat.ino, mode: stat.mode, nlink: stat.nlink });
+}
+function sameIdentity(left, right, directory = false) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        // mkdir changes a parent's link count. File link counts remain live evidence.
+        (directory || left.nlink === right.nlink);
+}
+function directoryMode(mode) {
+    return (mode & 61440n) === 16384n;
+}
+function absent(pathname) {
+    try {
+        return fs.lstatSync(pathname, { throwIfNoEntry: false }) === undefined;
+    }
+    catch (error) {
+        // ENOTDIR is incomplete evidence, not a missing child of a directory.
+        return isNotFoundPathError(error) && error.code === "ENOENT";
+    }
+}
+export function missingMutationSegments(observation) {
+    return observation.missingSegments.length - observation.missingOffset;
+}
+export function nextMissingMutationPath(observation) {
+    const segment = observation.missingSegments[observation.missingOffset];
+    return segment === undefined ? undefined : path.join(observation.ancestor, segment);
+}
+// Callers may construct this only from their just-completed exact pathname and
+// canonical fences. The private brand prevents unverified structural objects
+// from advancing an admission epoch.
+export function checkedMutationDirectory(pathname, canonicalPath, stat, observeCurrent) {
+    if (!directoryMode(stat.mode)) {
+        throw new TypeError("mutation directory evidence must describe a real directory");
+    }
+    const observation = Object.freeze({
+        path: pathname,
+        canonicalPath,
+        identity: identity(stat),
+        [checkedDirectoryObservation]: true,
+    });
+    if (observeCurrent)
+        directoryObservers.set(observation, observeCurrent);
+    return observation;
+}
+function checkedDirectory(observation) {
+    return observation[checkedDirectoryObservation] === true &&
+        path.isAbsolute(observation.path) && path.isAbsolute(observation.canonicalPath) &&
+        directoryMode(observation.identity.mode);
+}
+export function mutationObservationUsesDirectory(observation, directory) {
+    return checkedDirectory(directory) &&
+        observation.ancestor === directory.path &&
+        observation.canonicalAncestor === directory.canonicalPath &&
+        sameIdentity(observation.entry, directory.identity) &&
+        sameIdentity(observation.identity, directory.identity);
+}
+// Optional evidence only: failures select full admission, never a new error order.
+export function observeMutationPath(pathname) {
+    try {
+        let ancestor = pathname;
+        const reversedMissing = [];
+        while (absent(ancestor)) {
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return undefined;
+            reversedMissing.push(path.basename(ancestor));
+            ancestor = parent;
+        }
+        reversedMissing.reverse();
+        const missingSegments = Object.freeze(reversedMissing);
+        const entry = inspectFileIdentitySync(() => fs.lstatSync(ancestor, { bigint: true }));
+        const canonicalAncestor = realpathSync.native(ancestor);
+        const stat = canonicalAncestor === ancestor ? entry :
+            inspectFileIdentitySync(() => fs.lstatSync(canonicalAncestor, { bigint: true }));
+        if (stat.isSymbolicLink() || (missingSegments.length > 0 && !stat.isDirectory()))
+            return undefined;
+        const observation = Object.freeze({
+            path: pathname, ancestor, canonicalAncestor,
+            canonicalPath: path.join(canonicalAncestor, ...missingSegments),
+            entry: identity(entry), identity: identity(stat), missingSegments, missingOffset: 0,
+        });
+        return mutationObservationCurrent(observation) ? observation : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function mutationObservationCurrent(observation) {
+    try {
+        const entry = inspectFileIdentitySync(() => fs.lstatSync(observation.ancestor, { bigint: true }));
+        if (!sameIdentity(observation.entry, entry, entry.isDirectory()) ||
+            realpathSync.native(observation.ancestor) !== observation.canonicalAncestor)
+            return false;
+        const stat = observation.canonicalAncestor === observation.ancestor ? entry :
+            inspectFileIdentitySync(() => fs.lstatSync(observation.canonicalAncestor, { bigint: true }));
+        return sameIdentity(observation.identity, stat, stat.isDirectory()) &&
+            (missingMutationSegments(observation) === 0 ||
+                (stat.isDirectory() && absent(nextMissingMutationPath(observation))));
+    }
+    catch {
+        return false;
+    }
+}
+// Share only ordinary spelling observations collected in this synchronous
+// phase. Aliases retain their independent raw/canonical binding checks, and no
+// fact escapes this call or crosses an authority callback or mutation.
+export function mutationObservationsCurrent(observations, directories) {
+    const groups = new Map();
+    const groupFor = (pathname) => {
+        let group = groups.get(pathname);
+        if (!group) {
+            group = { observations: [], directories: [] };
+            groups.set(pathname, group);
+        }
+        return group;
+    };
+    try {
+        for (const observation of observations) {
+            if (observation.ancestor !== observation.canonicalAncestor) {
+                if (!mutationObservationCurrent(observation))
+                    return false;
+            }
+            else {
+                groupFor(observation.ancestor).observations.push(observation);
+            }
+        }
+        for (const directory of directories) {
+            if (!checkedDirectory(directory))
+                return false;
+            groupFor(directory.path).directories.push(directory);
+        }
+        const current = (pathname, group) => {
+            const missing = new Set(group.observations.flatMap((observation) => {
+                const next = nextMissingMutationPath(observation);
+                return next === undefined ? [] : [next];
+            }));
+            // Exact directory roles are the end fence. Observe missing children
+            // before refreshing that parent, matching the ordered admission fence.
+            if (group.directories.length && ![...missing].every(absent))
+                return false;
+            const observed = group.directories.length
+                ? directoryObservers.get(group.directories[0])?.() : undefined;
+            const stat = observed?.identity ??
+                inspectFileIdentitySync(() => fs.lstatSync(pathname, { bigint: true }));
+            const canonical = observed?.canonicalPath ?? realpathSync.native(pathname);
+            const isDirectory = directoryMode(stat.mode);
+            if (!group.observations.every((observation) => canonical === observation.canonicalAncestor &&
+                sameIdentity(observation.entry, stat, isDirectory) &&
+                sameIdentity(observation.identity, stat, isDirectory) &&
+                (missingMutationSegments(observation) === 0 || isDirectory)))
+                return false;
+            if (!group.directories.every((directory) => isDirectory &&
+                sameIdentity(directory.identity, stat) && canonical === directory.canonicalPath))
+                return false;
+            return group.directories.length > 0 || [...missing].every(absent);
+        };
+        for (const [pathname, group] of groups) {
+            if (!group.directories.length && !current(pathname, group))
+                return false;
+        }
+        // Preserve the supplied parent/child order, even when a directory also
+        // appeared earlier as the Root or a denied path's nearest ancestor.
+        const checked = new Set();
+        for (const directory of directories) {
+            if (checked.has(directory.path))
+                continue;
+            if (!current(directory.path, groups.get(directory.path)))
+                return false;
+            checked.add(directory.path);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// This is deliberately a pure tentative update. The immediately following
+// parent authorization validates the complete epoch once before reusing it.
+export function advanceMutationObservation(observation, parent, child) {
+    const nextMissingPath = nextMissingMutationPath(observation);
+    if (nextMissingPath === undefined || nextMissingPath !== child.path)
+        return observation;
+    if (!checkedDirectory(parent) || !checkedDirectory(child) ||
+        observation.ancestor !== parent.path || observation.canonicalAncestor !== parent.canonicalPath ||
+        !sameIdentity(observation.entry, parent.identity, true) ||
+        !sameIdentity(observation.identity, parent.identity, true) ||
+        parent.path !== parent.canonicalPath || child.path !== child.canonicalPath ||
+        path.dirname(child.path) !== parent.path)
+        return undefined;
+    return Object.freeze({
+        ...observation,
+        ancestor: child.path,
+        canonicalAncestor: child.canonicalPath,
+        entry: child.identity,
+        identity: child.identity,
+        missingOffset: observation.missingOffset + 1,
+    });
+}