@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/dist/permissions.js

@@ -1,9 +1,21 @@
 import fsSync from "node:fs";
 import { formatIcaclsResetCommand, inspectWindowsPermissions, } from "./permissions-windows.js";
+import { hasWindowsPathAlias, pathForWindowsFilesystem, } from "./windows-path-alias.js";
 export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
-export async function safeStat(targetPath) {
+function failedSafeStat(error) {
+    return {
+        ok: false,
+        isSymlink: false,
+        isDir: false,
+        mode: null,
+        uid: null,
+        gid: null,
+        error,
+    };
+}
+async function safeStatAdmitted(targetPath) {
     try {
-        const lst = fsSync.lstatSync(targetPath);
+        const lst = fsSync.lstatSync(pathForWindowsFilesystem(targetPath));
         return {
             ok: true,
             isSymlink: lst.isSymbolicLink(),
@@ -14,19 +26,36 @@ export async function safeStat(targetPath) {
         };
     }
     catch (err) {
+        return failedSafeStat(String(err));
+    }
+}
+export async function safeStat(targetPath) {
+    if (hasWindowsPathAlias(targetPath, "filesystem")) {
+        return failedSafeStat("Path uses a Windows filesystem namespace alias");
+    }
+    return await safeStatAdmitted(targetPath);
+}
+export async function inspectPathPermissions(targetPath, opts) {
+    const admissionPlatform = process.platform === "win32"
+        ? process.platform
+        : (opts?.platform ?? process.platform);
+    if (hasWindowsPathAlias(targetPath, "filesystem", admissionPlatform)) {
+        const st = failedSafeStat("Path uses a Windows filesystem namespace alias");
         return {
             ok: false,
             isSymlink: false,
             isDir: false,
             mode: null,
-            uid: null,
-            gid: null,
-            error: String(err),
+            bits: null,
+            source: "unknown",
+            worldWritable: false,
+            groupWritable: false,
+            worldReadable: false,
+            groupReadable: false,
+            error: st.error,
         };
     }
-}
-export async function inspectPathPermissions(targetPath, opts) {
-    const st = await safeStat(targetPath);
+    const st = await safeStatAdmitted(targetPath);
     if (!st.ok) {
         return {
             ok: false,

package/dist/pinned-mutation-admission.d.ts

@@ -0,0 +1,25 @@
+import { type DenyMutationPolicy } from "./deny-mutations.js";
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export type PinnedMutationPolicySnapshot = Readonly<{
+    denyMutations?: DenyMutationPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+}>;
+export declare function snapshotPinnedMutationPolicy(denyMutations: DenyMutationPolicy | undefined, mutationSymlinks: MutationSymlinkPolicy | undefined): PinnedMutationPolicySnapshot | undefined;
+export declare function preparePinnedWriteMutationAdmission(params: {
+    rootReal: string;
+    rootWithSep: string;
+    rootIdentity?: RootBoundaryIdentity;
+    resolvedTargetPath: string;
+    defaultRelativeParentPath: string;
+    originalPath?: string;
+    policy: PinnedMutationPolicySnapshot | undefined;
+    resolveCurrent(): Promise<{
+        resolved: string;
+    }>;
+}): Promise<{
+    relativeParentPath: string;
+    mutationAdmission?: PinnedWriteMutationAdmission;
+}>;
+//# sourceMappingURL=pinned-mutation-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-mutation-admission.d.ts","sourceRoot":"","sources":["../src/pinned-mutation-admission.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAKV,4BAA4B,EAC7B,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAgCtE,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,CAAC,CAAC;AAEH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,kBAAkB,GAAG,SAAS,EAC7C,gBAAgB,EAAE,qBAAqB,GAAG,SAAS,GAClD,4BAA4B,GAAG,SAAS,CAO1C;AAuJD,wBAAsB,mCAAmC,CAAC,MAAM,EAAE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yBAAyB,EAAE,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,4BAA4B,GAAG,SAAS,CAAC;IACjD,cAAc,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD,GAAG,OAAO,CAAC;IACV,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;CAClD,CAAC,CAsQD"}

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"}