@openclaw/fs-safe 0.13.0 → 0.14.0

package/dist/root-write-compatibility.js

@@ -1,74 +1,23 @@
-import fs from "node:fs";
-import path from "node:path";
-import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError } from "./path.js";
-import { admitPathInsideRoot } from "./root-boundary.js";
 import { withPinnedWriteRenameIdentityLock } from "./pinned-write.js";
-import { realpathSync } from "./realpath.js";
+import { createRootWriteLockBinding } from "./root-write-lock-binding.js";
 import { serializePathWrite } from "./write-queue.js";
-function unsupportedSpelling() {
-    return new FsSafeError("path-alias", "Windows compatibility writes require lower-case ASCII destination components");
-}
-// The caller first applies the Root's ordinary path and mutation policies. This
-// extra admission rule is deliberately narrower than general Windows filenames:
-// the existing lock protocol has no portable case/Unicode equivalence key for a
-// missing name. Do not guess one, or switch keys when a placeholder appears.
-function effectiveDestination(rootPath, targetPath, rootIdentity) {
-    let effective;
+export async function withRootFallbackCompatibilityLock(params, run) {
+    const binding = createRootWriteLockBinding(params);
+    const callerAssertion = params.assertBeforeMutation;
+    const assertBeforeMutation = callerAssertion === undefined
+        ? binding.assertCurrent
+        : () => { callerAssertion.call(params); binding.assertCurrent(); };
+    // Keep the alias queue and historical lock hash before admitting the writer.
     try {
-        effective = realpathSync.native(targetPath);
-    }
-    catch (error) {
-        if (!isNotFoundPathError(error))
-            throw error;
-        let cursor = targetPath;
-        const missing = [];
-        for (;;) {
-            try {
-                fs.lstatSync(cursor);
-                break;
-            }
-            catch (error) {
-                if (!isNotFoundPathError(error) || cursor === rootPath)
-                    throw error;
-                const parent = path.dirname(cursor);
-                if (parent === cursor)
-                    throw error;
-                missing.unshift(path.basename(cursor));
-                cursor = parent;
-            }
-        }
-        // An existing dangling link must fail resolution, not become a missing
-        // lexical component. Keep the fallback bounded by the retained Root.
-        effective = path.join(realpathSync.native(cursor), ...missing);
+        return await serializePathWrite(binding.targetPath, async () => await withPinnedWriteRenameIdentityLock({
+            rootPath: params.rootPath, targetPath: binding.targetPath, relativeTargetPath: binding.relativeLockPath,
+        }, async () => await run({
+            targetPath: binding.targetPath,
+            relativePath: binding.relativePath,
+            assertBeforeMutation,
+        })));
     }
-    const admitted = admitPathInsideRoot({ rootPath, candidatePath: effective, rootIdentity });
-    if (!admitted)
-        throw unsupportedSpelling();
-    const relative = admitted.relativePath;
-    if (!relative || !relative.split(path.sep).every(component => /^[a-z0-9._-]+$/.test(component) && !component.endsWith(".")))
-        throw unsupportedSpelling();
-    return admitted.path;
-}
-export function assertRootFallbackWritePath(expected, actual) {
-    if (expected !== undefined && actual !== expected) {
-        throw new FsSafeError("path-mismatch", "compatibility write destination changed after lock selection");
+    finally {
+        binding.dispose();
     }
 }
-export async function withRootFallbackCompatibilityLock(params, run) {
-    const targetPath = effectiveDestination(params.rootPath, params.targetPath, params.rootIdentity);
-    const relativePath = path.relative(params.rootPath, targetPath).split(path.sep).join("/");
-    const assertCurrent = () => assertRootFallbackWritePath(targetPath, effectiveDestination(params.rootPath, targetPath, params.rootIdentity));
-    // Sidecars are reentrant within one manager; aliases also need the same local
-    // queue before acquisition. The outer Root queue uses the caller's spelling.
-    return await serializePathWrite(targetPath, async () => await withPinnedWriteRenameIdentityLock({
-        rootPath: params.rootPath, targetPath, relativeTargetPath: relativePath,
-    }, async () => {
-        // The guarded open resolves again under the lock; each mutation rechecks
-        // below. Lock selection is never reused as post-lock filesystem authority.
-        return await run({
-            targetPath, relativePath,
-            assertBeforeMutation: () => { params.assertBeforeMutation?.(); assertCurrent(); },
-        });
-    }));
-}

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

@@ -1 +1 @@
-{"version":3,"file":"root-write-complete-parent.d.ts","sourceRoot":"","sources":["../src/root-write-complete-parent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAKxE,KAAK,8BAA8B,GAAG,QAAQ,CAC1C;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CACtC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,2BAA2B,GAAG,QAAQ,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,sBAAsB,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC,CAAC;AA2GH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,uBAAuB,EACjC,YAAY,UAAQ,GACnB,IAAI,CAqBN;AAwCD,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAqBhC"}
+{"version":3,"file":"root-write-complete-parent.d.ts","sourceRoot":"","sources":["../src/root-write-complete-parent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAMxE,KAAK,8BAA8B,GAAG,QAAQ,CAC1C;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CACtC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,2BAA2B,GAAG,QAAQ,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,sBAAsB,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC,CAAC;AA2GH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,uBAAuB,EACjC,YAAY,UAAQ,GACnB,IAAI,CAqBN;AAwCD,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAsBhC"}

package/dist/root-write-complete-parent.js

@@ -8,6 +8,7 @@ import { hasNodeErrorCode } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { prepareRootWriteTarget } from "./root-directory-creation.js";
+import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { isSafePathSegment } from "./safe-path-segment.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -185,7 +186,8 @@ export async function prepareSharedRootWriteTarget(root, params) {
     if (mutationAdmission)
         await beforeParentAdmission?.(resolvedPath);
     const preparedParent = params.mkdir !== false &&
-        params.assertBeforeMutation === undefined && beforeParentAdmission === undefined
+        canReuseParentWithMutationAssertion(params.assertBeforeMutation, root.rootReal, guardedTarget.targetPath) &&
+        beforeParentAdmission === undefined
         ? await prepareCompleteRootWriteParent(root, guardedTarget, params.relativePath)
         : undefined;
     const targetPath = params.mkdir === false

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

@@ -0,0 +1,15 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+export declare function canReuseParentWithMutationAssertion(assertion: (() => void) | undefined, rootPath: string, targetPath: string): boolean;
+export declare function assertRootFallbackWritePath(expected: string | undefined, actual: string): void;
+export declare function createRootWriteLockBinding(params: Readonly<{
+    rootPath: string;
+    targetPath: string;
+    rootIdentity?: RootBoundaryIdentity;
+}>): Readonly<{
+    targetPath: string;
+    relativePath: string;
+    relativeLockPath: string;
+    assertCurrent: () => void;
+    dispose(): void;
+}>;
+//# sourceMappingURL=root-write-lock-binding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-lock-binding.d.ts","sourceRoot":"","sources":["../src/root-write-lock-binding.ts"],"names":[],"mappings":"AAKA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAKpF,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,EACnC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAIT;AA6GD,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAI9F;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC,CAAC;;;;;;GAqCD"}

package/dist/root-write-lock-binding.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
+const lockObservations = new WeakMap();
+export function canReuseParentWithMutationAssertion(assertion, rootPath, targetPath) {
+    if (assertion === undefined)
+        return true;
+    const binding = lockObservations.get(assertion);
+    return binding?.rootPath === rootPath && binding.targetPath === targetPath;
+}
+function unsupportedSpelling() {
+    return new FsSafeError("path-alias", "Windows compatibility writes require lower-case ASCII destination components");
+}
+// Missing names have no portable case/Unicode lock key. Keep this admission
+// narrower than general Root paths and never change keys after acquisition.
+function effectiveDestination(rootPath, targetPath, rootIdentity) {
+    let effective;
+    let missingHint;
+    try {
+        effective = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        let cursor = targetPath;
+        const missing = [];
+        for (;;) {
+            try {
+                fs.lstatSync(cursor);
+                break;
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error) || cursor === rootPath)
+                    throw error;
+                const parent = path.dirname(cursor);
+                if (parent === cursor)
+                    throw error;
+                missing.unshift(path.basename(cursor));
+                cursor = parent;
+            }
+        }
+        // Existing dangling links must fail resolution, not become missing names.
+        const canonicalParent = realpathSync.native(cursor);
+        effective = path.join(canonicalParent, ...missing);
+        // The hint must describe the selected route exactly. The full resolver can
+        // normalize a missing raw `..` component out of the eventual lock path.
+        if (missing.length > 1 && path.resolve(canonicalParent) === canonicalParent &&
+            missing.every(component => /^[a-z0-9._-]+$/.test(component) &&
+                component !== "." && component !== ".." && !component.endsWith("."))) {
+            missingHint = Object.freeze({ parentPath: canonicalParent, parts: Object.freeze(missing), nextIndex: 0 });
+        }
+    }
+    const admitted = admitPathInsideRoot({ rootPath, candidatePath: effective, rootIdentity });
+    if (!admitted)
+        throw unsupportedSpelling();
+    const relative = admitted.relativePath;
+    if (!relative || !relative.split(path.sep).every(component => /^[a-z0-9._-]+$/.test(component) && !component.endsWith(".")))
+        throw unsupportedSpelling();
+    return {
+        path: admitted.path,
+        // Case-folded or rebased root spellings keep the full resolver and its
+        // existing root-identity admission at every mutation.
+        missing: admitted.admission === "exact" && admitted.path === effective ? missingHint : undefined,
+    };
+}
+// The hint stores only a location. Each call freshly binds the nearest existing
+// prefix and its first absent child; no identity or authorization crosses calls.
+function observeMissingDestination(hint) {
+    // A complete parent needs only the ordinary leaf check, not a prefix fence.
+    if (hint.parts.length - hint.nextIndex < 2)
+        return undefined;
+    try {
+        let parentPath = hint.parentPath;
+        let parent = inspectDirectoryIdentitySync(parentPath);
+        for (let nextIndex = hint.nextIndex; nextIndex < hint.parts.length; nextIndex++) {
+            const childPath = path.join(parentPath, hint.parts[nextIndex]);
+            let child;
+            try {
+                child = fs.lstatSync(childPath, { bigint: true });
+            }
+            catch (error) {
+                if (!hasNodeErrorCode(error, "ENOENT"))
+                    return undefined;
+                if (realpathSync.native(parentPath) !== parentPath)
+                    return undefined;
+                inspectDirectoryIdentitySync(parentPath, parent);
+                try {
+                    fs.lstatSync(childPath);
+                }
+                catch (error) {
+                    if (!hasNodeErrorCode(error, "ENOENT"))
+                        return undefined;
+                    // Absence can follow a renamed ancestor through a new alias while
+                    // preserving the directory's identity. Finish at its current name.
+                    if (realpathSync.native(parentPath) !== parentPath)
+                        return undefined;
+                    return Object.freeze({ parentPath, parts: hint.parts, nextIndex });
+                }
+                return undefined;
+            }
+            // An existing leaf always receives the historical full resolution,
+            // including final links, collisions and unsupported canonical spellings.
+            if (nextIndex === hint.parts.length - 1)
+                return undefined;
+            parent = inspectDirectoryIdentitySync(childPath, undefined, child);
+            parentPath = childPath;
+        }
+    }
+    catch {
+        // Removal, redirection and uncertain observations only discard the hint.
+        // The full resolver below still determines the destination and error.
+    }
+    return undefined;
+}
+export function assertRootFallbackWritePath(expected, actual) {
+    if (expected !== undefined && actual !== expected) {
+        throw new FsSafeError("path-mismatch", "compatibility write destination changed after lock selection");
+    }
+}
+export function createRootWriteLockBinding(params) {
+    const { rootPath } = params;
+    const rootIdentity = params.rootIdentity && Object.freeze({
+        dev: params.rootIdentity.dev, ino: params.rootIdentity.ino,
+    });
+    const selected = effectiveDestination(rootPath, params.targetPath, rootIdentity);
+    const targetPath = selected.path;
+    let missingHint = selected.missing;
+    const relativePath = path.relative(rootPath, targetPath);
+    let active = true;
+    const assertCurrent = () => {
+        if (!active)
+            throw new FsSafeError("path-mismatch", "compatibility lock observation expired");
+        const observed = missingHint && observeMissingDestination(missingHint);
+        if (observed) {
+            missingHint = observed;
+            return;
+        }
+        missingHint = undefined;
+        const current = effectiveDestination(rootPath, targetPath, rootIdentity);
+        assertRootFallbackWritePath(targetPath, current.path);
+        missingHint = current.missing;
+    };
+    // Only this library-owned, observation-only closure permits parent reuse.
+    // Callers cannot obtain that status by setting properties on their callback.
+    lockObservations.set(assertCurrent, Object.freeze({ rootPath, targetPath }));
+    return Object.freeze({
+        targetPath,
+        relativePath,
+        // The existing lock protocol uses slashes; the writer needs native spelling.
+        relativeLockPath: relativePath.split(path.sep).join("/"),
+        assertCurrent,
+        dispose() {
+            active = false;
+            missingHint = undefined;
+            lockObservations.delete(assertCurrent);
+        },
+    });
+}

package/dist/staged-directory.d.ts

@@ -1,13 +1,16 @@
 import { type BigIntStats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+import type { NativeBinding } from "./native-binding.js";
+import { type MutationDirectoryObservation, type MutationDirectoryObserver } from "./pinned-mutation-observation.js";
 import type { StagedFileReceipt } from "./staged-file-types.js";
 export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
 export type PolicyStagedDirectory = Readonly<{
     directory: StagedDirectorySnapshot;
     observation: MutationDirectoryObservation;
     stat: BigIntStats;
+    observeCurrent?: MutationDirectoryObserver;
+    disposeObservation?(): void;
 }>;
 export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
     dev: bigint;
@@ -15,7 +18,7 @@ export declare function exactIdentityMatches(expected: FileIdentityStat, actual:
 }>): boolean;
 export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
 export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
-export declare function describePolicyStagedDirectory(fd: number, pathname: string): PolicyStagedDirectory;
+export declare function describePolicyStagedDirectory(fd: number, pathname: string, binding?: NativeBinding): PolicyStagedDirectory;
 export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
 export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
 export declare function openStagedDirectory(directory: string | DirectoryReceipt): {

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAwBvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAOb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAU9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CA2CvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAeb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAoB9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}

package/dist/staged-directory.js

@@ -2,6 +2,7 @@ import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { realpathSync } from "./realpath.js";
 import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
@@ -38,12 +39,31 @@ function sameDirectoryMetadata(left, right) {
 }
 // The policy hot path is Node/POSIX-only. It deliberately uses native
 // canonicalization so a successful capture contains no JS realpath work.
-export function describePolicyStagedDirectory(fd, pathname) {
+export function describePolicyStagedDirectory(fd, pathname, binding) {
     const resolved = path.resolve(pathname);
     const descriptor = fs.fstatSync(fd, { bigint: true });
     if (!descriptor.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a directory");
     }
+    const observeCurrent = nativePolicyDirectoryObserver(binding, fd, resolved);
+    const observed = observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(descriptor, observed.identity)) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        const directory = Object.freeze({
+            path: resolved,
+            realPath: observed.canonicalPath,
+            identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+        });
+        return Object.freeze({
+            directory,
+            observation: checkedMutationDirectory(resolved, observed.canonicalPath, observed.identity, observeCurrent),
+            stat: descriptor,
+            observeCurrent,
+            disposeObservation: observeCurrent.dispose,
+        });
+    }
     const before = inspectDirectoryIdentitySync(resolved);
     const canonicalPath = path.resolve(realpathSync.native(resolved));
     const after = inspectDirectoryIdentitySync(resolved, descriptor);
@@ -64,6 +84,14 @@ export function describePolicyStagedDirectory(fd, pathname) {
     });
 }
 export function assertPolicyStagedDirectoryCurrent(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(captured.stat, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return captured.stat;
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     if (!sameDirectoryMetadata(captured.stat, current) ||
         path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
@@ -72,6 +100,14 @@ export function assertPolicyStagedDirectoryCurrent(captured) {
     return current;
 }
 export function refreshPolicyStagedDirectoryObservation(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!exactIdentityMatches(captured.directory.identity, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return checkedMutationDirectory(captured.directory.path, observed.canonicalPath, observed.identity, captured.observeCurrent);
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
     if (canonicalPath !== captured.directory.realPath) {

package/dist/temp-workspace-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AA0UF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}
+{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AAsWF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}

package/dist/temp-workspace-admission.js

@@ -116,6 +116,30 @@ function assertSnapshot(entry, uid) {
     assertTrustedTempWorkspaceDirectory(stat, uid);
     assertCanonicalRoot(entry);
 }
+function snapshotMissingRootComponent(parent, dir, ownerUid) {
+    if (parent.dir !== parent.realPath) {
+        assertSnapshot(parent, ownerUid);
+        return snapshot(dir, ownerUid);
+    }
+    const current = inspectSnapshotIdentity(parent);
+    assertTrustedTempWorkspaceDirectory(current, ownerUid);
+    let realPath;
+    try {
+        realPath = canonicalTempWorkspacePath(dir);
+    }
+    catch (error) {
+        // Keep parent resolution failures ahead of a missing or unreadable child.
+        assertCanonicalRoot(parent);
+        throw error;
+    }
+    if (path.dirname(realPath) !== parent.realPath) {
+        assertCanonicalRoot(parent);
+        return snapshot(dir, ownerUid);
+    }
+    // The child's canonical parent confirms the same parent name at this phase.
+    // Its exact non-symlink/owner observation still precedes mode initialization.
+    return snapshot(dir, ownerUid, realPath);
+}
 function assertChain(chain, uid) {
     for (const entry of chain) {
         const current = inspectSnapshotIdentity(entry);
@@ -321,6 +345,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
         return admission;
     const guardedChain = chain;
     for (const segment of missing) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
         assertNoWindowsPathAlias(dir, "filesystem");
@@ -334,8 +359,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        parent.assertCurrent();
-        const observed = snapshot(dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
         if (created) {
             const modeInitialization = admitTempWorkspaceChild(dir, observed.stat, parent, 0o700);
             if (modeInitialization)
@@ -351,6 +375,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
         return admission;
     const guardedChain = chain;
     for (const segment of missing) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
         assertNoWindowsPathAlias(dir, "filesystem");
@@ -364,8 +389,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        parent.assertCurrent();
-        const observed = snapshot(dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
         if (created)
             admitTempWorkspaceChildSync(dir, observed.stat, parent, 0o700);
         guardedChain.push(observed.entry);

package/docs/guest.md

@@ -80,7 +80,7 @@ disables. Do not omit required fields.
 | Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
 | Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
 | Make directories | `mkdirp root directory` | Creates missing relative directory components. |
-| List directory | `readdir root directory` | JSON array of `{ name, isDirectory }`; no sorting guarantee. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory, isFile }`; both kind fields are false for symlinks and special entries; no sorting guarantee. |
 
 The complete program rejects empty, `.`, `..`, slash-containing, and NUL
 basenames before opening roots or creating parents. Both leaf operands of copy

package/docs/native-helper.md

@@ -43,6 +43,19 @@ when admitting a temp workspace. Containment and identity checks stay intact.
 
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
+Native-created descriptors retain their originating native close operation through
+normal and error cleanup, including later mode changes. Node-created roots and
+directory handles keep Node's close operation, and borrowed handles keep their
+caller-owned lifetime. This preserves Node worker-thread descriptor tracking
+without unmanaged-descriptor warnings. A helper missing native close support is
+unavailable before descriptor allocation.
+
+Close retained native resources and let in-flight operations finish before
+forcibly terminating a worker. Native-created descriptors are not registered
+with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
+open until process exit. The native close operation handles explicit cleanup,
+not forced worker termination.
+
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
 remain available in every mode. Their default compatible cleanup uses guarded
 JavaScript quarantine when owned native tree removal is unavailable.
@@ -84,7 +97,7 @@ normalization, and the decision to fall back.
 
 - Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
 Native primitives back create-only and replacing pinned writes, no-clobber
 `Root.move()`, async sidecar creation, guarded publication, archive acceleration,

package/docs/native.md

@@ -206,6 +206,14 @@ that fallback does not apply to POSIX no-read modes.
 
 ## JavaScript fallback guarantees and delta
 
+Policy-bound parent creation can refresh exact directory facts through the
+retained POSIX descriptor. The optional native observer compares descriptor and
+no-follow pathname metadata and verifies the descriptor's canonical path before
+and after the observation. Ordinary paths can share that observation within one
+synchronous admission phase; callbacks, mutations, and later phases require fresh
+evidence. Unsupported helpers retain the guarded pathname checks. Policy and
+denied-path decisions remain in TypeScript.
+
 Public policy does not change with the selected mechanism: traversal and link
 rejection, archive filters/limits/modes, exclusive target creation, source and
 target identity fencing, publication cleanup receipts, and secret/lock policy

package/docs/writing.md

@@ -537,6 +537,12 @@ Windows `Root.write()` and `Root.writeJson()` honor this policy both as a Root d
 
 The Windows buffered compatibility path resolves permitted in-root aliases before choosing its lock and binds publication to that effective destination. With the existing lock protocol, effective path components beneath the Root must contain only lower-case ASCII letters, digits, `.`, `_`, or `-`, with no trailing `.`. Unsupported spellings, including missing upper-case or non-ASCII names, fail with `path-alias` before mutation; no filesystem case-sensitivity or Unicode-folding behavior is guessed. This restriction does not apply to strict writes. Opaque Windows pathname identities still use strict verification against the retained original descriptor: they never, by themselves, authorize content-based acceptance of a replacement.
 
+The library's own lock-destination check permits the writer to reuse parent
+admission within that operation. The lock key and destination checks remain
+unchanged, and evidence is revoked when the locked operation finishes. Supplying
+an `assertBeforeMutation` callback retains full parent admission because caller
+code can change the filesystem before dispatch.
+
 Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -167,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.13.0",
-    "@openclaw/fs-safe-darwin-x64": "0.13.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.13.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.13.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.13.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.13.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.13.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.14.0",
+    "@openclaw/fs-safe-darwin-x64": "0.14.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.14.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.14.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.14.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.14.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.14.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {