@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/pinned-mutation-admission.js

@@ -0,0 +1,425 @@
+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, mutationDirectoryObservationCurrent, 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) {
+    return !process.versions.bun && epoch.mode === epoch.session.nativeMode &&
+        getFsSafeNativeConfig().mode === epoch.mode &&
+        epoch.observations.every(mutationObservationCurrent);
+}
+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 (!mutationDirectoryObservationCurrent(receipt.parent) ||
+        !mutationDirectoryObservationCurrent(receipt.child) ||
+        !mutationObservationUsesDirectory(target, receipt.child) ||
+        !epochCurrent(next))
+        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,
+    });
+    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 beginSharedParentWalk = sharedRoute ? () => {
+        const session = Object.freeze({
+            kind: "shared",
+            route: sharedRoute.route,
+            selectedTarget: params.resolvedTargetPath,
+            nativeMode: getFsSafeNativeConfig().mode,
+            rootIdentity: sharedRoute.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) ||
+                    !epochCurrent(reusable)) {
+                    disable();
+                    return undefined;
+                }
+                assertCachedNotDenied(request.targetPath, reusable);
+                assertCachedNotDenied(request.mutationPath, reusable);
+                // This is the required end fence. A returned receipt remains usable
+                // only synchronously, while the exact parent identity and spelling
+                // still match the observation captured by this walk.
+                if (!nonzeroDirectoryObservation(parent) ||
+                    !mutationDirectoryObservationCurrent(parent)) {
+                    disable();
+                    return undefined;
+                }
+                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();
+            },
+        });
+    } : undefined;
+    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,
+        tryAuthorizeAtParent(request, parent) {
+            pending = undefined;
+            const reusable = epoch;
+            if (!reusable || reusable.session !== pinnedSession ||
+                !reusableRequest(request, reusable) ||
+                !mutationObservationUsesDirectory(reusable.target, parent) ||
+                !epochCurrent(reusable)) {
+                epoch = undefined;
+                return undefined;
+            }
+            assertCachedNotDenied(request.targetPath, reusable);
+            assertCachedNotDenied(request.mutationPath, reusable);
+            // This is the required end fence. The caller can consume the returned
+            // token without awaiting only while the exact pathname, canonical
+            // spelling, descriptor identity, type, mode, and link count still match.
+            if (!mutationDirectoryObservationCurrent(parent)) {
+                epoch = undefined;
+                return undefined;
+            }
+            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/dist/pinned-mutation-observation.d.ts

@@ -0,0 +1,34 @@
+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 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: BigIntStats): MutationDirectoryObservation;
+export declare function mutationDirectoryObservationCurrent(observation: MutationDirectoryObservation): boolean;
+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 advanceMutationObservation(observation: MutationPathObservation, parent: MutationDirectoryObservation, child: MutationDirectoryObservation): MutationPathObservation | undefined;
+export {};
+//# sourceMappingURL=pinned-mutation-observation.d.ts.map

package/dist/pinned-mutation-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-mutation-observation.d.ts","sourceRoot":"","sources":["../src/pinned-mutation-observation.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,QAAA,MAAM,2BAA2B,eAAmD,CAAC;AAErF,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,CAAC,2BAA2B,CAAC,EAAE,IAAI,CAAC;CACrC,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AA8BH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,uBAAuB,GAAG,MAAM,CAEpF;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAGhG;AAKD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,WAAW,GAChB,4BAA4B,CAU9B;AAQD,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,4BAA4B,GACxC,OAAO,CAUT;AAED,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,uBAAuB,EACpC,SAAS,EAAE,4BAA4B,GACtC,OAAO,CAMT;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CA0BzF;AAED,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,uBAAuB,GAAG,OAAO,CAaxF;AAID,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,uBAAuB,EACpC,MAAM,EAAE,4BAA4B,EACpC,KAAK,EAAE,4BAA4B,GAClC,uBAAuB,GAAG,SAAS,CAiBrC"}

package/dist/pinned-mutation-observation.js

@@ -0,0 +1,142 @@
+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");
+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 {
+        fs.lstatSync(pathname);
+        return false;
+    }
+    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) {
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new TypeError("mutation directory evidence must describe a real directory");
+    }
+    return Object.freeze({
+        path: pathname,
+        canonicalPath,
+        identity: identity(stat),
+        [checkedDirectoryObservation]: true,
+    });
+}
+function checkedDirectory(observation) {
+    return observation[checkedDirectoryObservation] === true &&
+        path.isAbsolute(observation.path) && path.isAbsolute(observation.canonicalPath) &&
+        directoryMode(observation.identity.mode);
+}
+export function mutationDirectoryObservationCurrent(observation) {
+    if (!checkedDirectory(observation))
+        return false;
+    try {
+        const stat = inspectFileIdentitySync(() => fs.lstatSync(observation.path, { bigint: true }));
+        return stat.isDirectory() && !stat.isSymbolicLink() &&
+            sameIdentity(observation.identity, stat) &&
+            realpathSync.native(observation.path) === observation.canonicalPath;
+    }
+    catch {
+        return false;
+    }
+}
+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;
+    }
+}
+// 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,
+    });
+}

package/dist/pinned-mutation-shared-route.d.ts

@@ -0,0 +1,24 @@
+import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootBoundaryIdentity } from "./root-boundary.js";
+import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export type ExactRootIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+type SharedMutationPolicy = Readonly<{
+    denyMutations?: DenyMutationPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+}>;
+export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
+export declare function simpleSharedRoute(params: {
+    rootReal: string;
+    rootIdentity?: RootBoundaryIdentity;
+    originalPath?: string;
+    selectedTarget: string;
+    policy: SharedMutationPolicy;
+}): {
+    route: string;
+    rootIdentity: ExactRootIdentity;
+} | undefined;
+export {};
+//# sourceMappingURL=pinned-mutation-shared-route.d.ts.map

package/dist/pinned-mutation-shared-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-mutation-shared-route.d.ts","sourceRoot":"","sources":["../src/pinned-mutation-shared-route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvE,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,CAAC,CAAC;AA+BH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,iBAAiB,GAC9B,OAAO,CAeT;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;CAC9B,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,GAAG,SAAS,CAqBjE"}