@openclaw/fs-safe 0.4.7 → 0.5.1

package/dist/file-lock-sync.js

@@ -0,0 +1,233 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { readSidecarLockSnapshotSync, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { computeSidecarLockDelayMs, sidecarLockPayloadIsStale, } from "./sidecar-lock-policy.js";
+const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
+function getSyncHeldLocks() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
+        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_HELD_LOCKS_KEY];
+}
+function verifySyncHeldLock(held) {
+    const current = readSidecarLockSnapshotSync(held.lockPath, held.parsePayload);
+    return !!current && sidecarLockSnapshotMatches(current, held.snapshot);
+}
+function releaseSyncHeldLock(held) {
+    const heldLocks = getSyncHeldLocks();
+    if (heldLocks.get(held.normalizedTargetPath) !== held)
+        return false;
+    held.refCount -= 1;
+    if (held.refCount > 0)
+        return false;
+    heldLocks.delete(held.normalizedTargetPath);
+    if (held.timer) {
+        clearInterval(held.timer);
+        held.timer = undefined;
+    }
+    fs.closeSync(held.fd);
+    removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+    return true;
+}
+function createSyncHeldLockHandle(held) {
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        releaseSyncHeldLock(held);
+    };
+    return {
+        lockPath: held.lockPath,
+        normalizedTargetPath: held.normalizedTargetPath,
+        verifyStillHeld: () => verifySyncHeldLock(held),
+        release,
+        [Symbol.dispose]: release,
+    };
+}
+function normalizeTargetPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    try {
+        return path.join(fs.realpathSync(path.dirname(resolved)), path.basename(resolved));
+    }
+    catch {
+        return resolved;
+    }
+}
+function boundedLockPath(lockPath, lockRoot) {
+    const resolved = path.resolve(lockPath);
+    if (!lockRoot)
+        return resolved;
+    relativeSidecarLockPath(lockRoot, resolved);
+    const parent = path.dirname(resolved);
+    const parentReal = fs.realpathSync(parent);
+    const parentRelative = path.relative(lockRoot.rootReal, parentReal);
+    if (parentRelative === ".." || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
+        throw new FsSafeError("outside-workspace", "sidecar lock parent is outside lockRoot");
+    }
+    return path.join(parentReal, path.basename(resolved));
+}
+function defaultShouldReclaim(payload, lockPath, staleMs, nowMs) {
+    if (sidecarLockPayloadIsStale(payload, staleMs, nowMs))
+        return true;
+    try {
+        return nowMs - fs.statSync(lockPath).mtimeMs > staleMs;
+    }
+    catch {
+        return true;
+    }
+}
+function sleep(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+export function acquireFileLockSync(targetPath, options) {
+    const normalizedTargetPath = normalizeTargetPath(targetPath);
+    const lockPath = boundedLockPath(options.lockPath ?? `${normalizedTargetPath}.lock`, options.lockRoot);
+    const heldLocks = getSyncHeldLocks();
+    const held = heldLocks.get(normalizedTargetPath);
+    if (held &&
+        options.reentrantOwner !== undefined &&
+        held.reentrantOwner !== undefined &&
+        options.reentrantOwner === held.reentrantOwner) {
+        held.refCount += 1;
+        return createSyncHeldLockHandle(held);
+    }
+    const staleMs = options.staleMs ?? 30_000;
+    const retry = options.retry ?? {};
+    const startedAt = Date.now();
+    let attempt = 0;
+    while (true) {
+        let fd;
+        try {
+            const payload = options.payload();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+            const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+                ? fs.constants.O_NOFOLLOW
+                : 0;
+            fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+            fs.writeFileSync(fd, raw, "utf8");
+            fs.fsyncSync(fd);
+            const snapshot = {
+                raw,
+                payload,
+                stat: fs.fstatSync(fd),
+                ownershipToken,
+            };
+            const createdHeld = {
+                fd,
+                lockPath,
+                normalizedTargetPath,
+                parsePayload: options.parsePayload,
+                refCount: 1,
+                reentrantOwner: options.reentrantOwner,
+                snapshot,
+            };
+            heldLocks.set(normalizedTargetPath, createdHeld);
+            const returnedHandle = createSyncHeldLockHandle(createdHeld);
+            if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
+                createdHeld.timer = setInterval(() => {
+                    if (!returnedHandle.verifyStillHeld()) {
+                        if (createdHeld.timer)
+                            clearInterval(createdHeld.timer);
+                        createdHeld.timer = undefined;
+                        options.onCompromised?.({ lockPath, normalizedTargetPath });
+                    }
+                }, options.compromiseCheckIntervalMs);
+                createdHeld.timer.unref();
+            }
+            fd = undefined;
+            return returnedHandle;
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                const failed = { payload: null, stat: fs.fstatSync(fd) };
+                fs.closeSync(fd);
+                fd = undefined;
+                removeSidecarLockIfUnchangedSync(lockPath, failed);
+            }
+            if (error.code !== "EEXIST")
+                throw error;
+            if (heldLocks.has(normalizedTargetPath)) {
+                const elapsed = Date.now() - startedAt;
+                const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
+                if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
+                    throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                        code: "file_lock_timeout",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
+                }
+                sleep(computeSidecarLockDelayMs(retry, attempt));
+                attempt += 1;
+                continue;
+            }
+            const snapshot = readSidecarLockSnapshotSync(lockPath, options.parsePayload);
+            if (!snapshot)
+                continue;
+            const nowMs = Date.now();
+            const reclaim = options.shouldReclaim
+                ? options.shouldReclaim({
+                    lockPath,
+                    normalizedTargetPath,
+                    payload: snapshot.payload,
+                    staleMs,
+                    nowMs,
+                    heldByThisProcess: false,
+                })
+                : defaultShouldReclaim(snapshot.payload, lockPath, staleMs, nowMs);
+            if (reclaim) {
+                if (options.staleRecovery === "remove-if-unchanged" &&
+                    snapshot.raw !== undefined &&
+                    options.shouldRemoveStaleLock?.({
+                        lockPath,
+                        normalizedTargetPath,
+                        raw: snapshot.raw,
+                        payload: snapshot.payload,
+                    })) {
+                    const reclaimGuard = `${lockPath}.reclaim`;
+                    try {
+                        fs.mkdirSync(reclaimGuard);
+                        if (removeSidecarLockIfUnchangedSync(lockPath, snapshot))
+                            continue;
+                    }
+                    finally {
+                        try {
+                            fs.rmdirSync(reclaimGuard);
+                        }
+                        catch {
+                            // A surviving reclaim guard fails closed.
+                        }
+                    }
+                }
+                throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                    code: "file_lock_stale",
+                    lockPath,
+                    normalizedTargetPath,
+                });
+            }
+            const elapsed = Date.now() - startedAt;
+            const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
+            if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
+                throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                    code: "file_lock_timeout",
+                    lockPath,
+                    normalizedTargetPath,
+                });
+            }
+            sleep(computeSidecarLockDelayMs(retry, attempt));
+            attempt += 1;
+        }
+    }
+}
+export function withFileLockSync(targetPath, options, fn) {
+    const lock = acquireFileLockSync(targetPath, options);
+    try {
+        return fn();
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/file-lock.d.ts

@@ -1,4 +1,5 @@
 import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions, type SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export { acquireFileLockSync, withFileLockSync, type FileLockSyncAcquireOptions, type FileLockSyncHandle, } from "./file-lock-sync.js";
 export type FileLockRetryOptions = SidecarLockRetryOptions;
 export type FileLockStaleRecovery = SidecarLockStaleRecovery;
 export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath" | "staleMs"> & {
@@ -7,6 +8,7 @@ export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = O
 };
 export type FileLockHandle = SidecarLockHandle;
 export type FileLockHeldEntry = SidecarLockHeldEntry;
+export type { SidecarLockCompromisedInfo } from "./sidecar-lock.js";
 export type FileLockManager = {
     acquire<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
     withLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;

package/dist/file-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,GAAG,SAAS,CACzB,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAmBF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE7D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,GAAG,SAAS,CACzB,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAmBF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}

package/dist/file-lock.js

@@ -1,5 +1,6 @@
 import { createSidecarLockManager, } from "./sidecar-lock.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
+export { acquireFileLockSync, withFileLockSync, } from "./file-lock-sync.js";
 function resolveFileLockManagerKey(targetPath, managerKey) {
     return managerKey ?? `fs-safe.file-lock:${targetPath}`;
 }

package/dist/filename.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../src/filename.ts"],"names":[],"mappings":"AAEA,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAuBxF"}
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../src/filename.ts"],"names":[],"mappings":"AAIA,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CA2BxF"}

package/dist/filename.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+const WINDOWS_INVALID_FILE_NAME_CHARACTERS = new Set('<>:"/\\|?*');
 export function sanitizeUntrustedFileName(fileName, fallbackName) {
     const trimmed = typeof fileName === "string" ? fileName.trim() : "";
     if (!trimmed) {
@@ -9,7 +10,9 @@ export function sanitizeUntrustedFileName(fileName, fallbackName) {
     let cleaned = "";
     for (let i = 0; i < base.length; i++) {
         const code = base.charCodeAt(i);
-        if (code < 0x20 || code === 0x7f) {
+        if (code < 0x20 ||
+            (code >= 0x7f && code <= 0x9f) ||
+            WINDOWS_INVALID_FILE_NAME_CHARACTERS.has(base[i])) {
             continue;
         }
         cleaned += base[i];

package/dist/guarded-mkdir.d.ts

@@ -1,6 +1,12 @@
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
 export declare function mkdirPathComponentsWithGuards(params: {
     rootReal: string;
     targetPath: string;
     beforeComponent?: (componentPath: string) => Promise<void> | void;
-}): Promise<void>;
+}): Promise<string>;
 //# sourceMappingURL=guarded-mkdir.d.ts.map

package/dist/guarded-mkdir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAWA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AA0BA;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}

package/dist/guarded-mkdir.js

@@ -2,11 +2,32 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { isPathRelativeEscape } from "./path.js";
+import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 function isSameOrChildPath(candidate, parent) {
     const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
     return candidate === parent || candidate.startsWith(parentPrefix);
 }
+async function realpathOrThrowNotFile(target) {
+    try {
+        return path.resolve(await fs.realpath(target));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            // A dangling symlink (or a component removed between lstat and
+            // realpath) is not a usable directory component.
+            throw new FsSafeError("not-file", "directory component must be a directory", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
 export async function mkdirPathComponentsWithGuards(params) {
     const root = path.resolve(params.rootReal);
     const rootCanonical = path.resolve(await fs.realpath(root));
@@ -30,16 +51,37 @@ export async function mkdirPathComponentsWithGuards(params) {
             }
         }
         const stat = await fs.lstat(next);
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        if (!stat.isSymbolicLink() && !stat.isDirectory()) {
             throw new FsSafeError("not-file", "directory component must be a directory");
         }
         // Node's recursive mkdir follows symlinks in missing components. Build one
         // segment at a time and realpath-check each segment before descending.
-        if (!isSameOrChildPath(path.resolve(await fs.realpath(next)), rootCanonical)) {
+        const nextReal = await realpathOrThrowNotFile(next);
+        if (!isSameOrChildPath(nextReal, rootCanonical)) {
             throw new FsSafeError("outside-workspace", "directory escaped workspace root");
         }
+        if (stat.isSymbolicLink()) {
+            // An existing path component may legitimately be a symlink to a real
+            // directory inside the root (e.g. a skill-bank layout). We already
+            // verified above that it resolves inside the root, so treat the
+            // resolved real path as the directory for the rest of this walk
+            // instead of rejecting it outright. Guard checks from here on operate
+            // on the real (non-symlink) path, preserving TOCTOU protection for
+            // every subsequent segment. Callers that need the final directory
+            // (e.g. to guard it themselves after this function returns) must use
+            // the returned resolved path, not their own lexical parent path.
+            const targetStat = await fs.stat(nextReal);
+            if (!targetStat.isDirectory()) {
+                throw new FsSafeError("not-file", "directory component must be a directory");
+            }
+            await createAsyncDirectoryGuard(nextReal);
+            await assertAsyncDirectoryGuard(parentGuard);
+            current = nextReal;
+            continue;
+        }
         await createAsyncDirectoryGuard(next);
         await assertAsyncDirectoryGuard(parentGuard);
         current = next;
     }
+    return current;
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
-export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
-export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
 export { writeExternalFileWithinRoot, } from "./output.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/dist/json-document-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA6Dd"}
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAKlE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA0Ed"}

package/dist/json-document-store.js

@@ -1,5 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
 import { createSidecarLockManager } from "./sidecar-lock.js";
+import { serializePathWrite } from "./write-queue.js";
+const activeStoreMutations = new AsyncLocalStorage();
 function cloneFallback(value) {
     if (value && typeof value === "object") {
         return structuredClone(value);
@@ -35,19 +40,29 @@ export function createJsonStore(adapter, options = {}) {
             trailingNewline: options.trailingNewline ?? true,
         });
     }
-    async function withOptionalLock(run) {
-        if (!locks || !lockOptions) {
-            return await run();
+    async function withSerializedMutation(run) {
+        const canonicalPath = await canonicalPathFromExistingAncestor(adapter.filePath);
+        const activePaths = activeStoreMutations.getStore();
+        if (activePaths?.has(canonicalPath)) {
+            throw new FsSafeError("store-reentrant-update", `jsonStore cannot write or update ${canonicalPath} from inside its active update callback; return the complete next value from the outer update instead`);
         }
-        return await locks.withLock({
-            targetPath: adapter.filePath,
-            staleMs: lockOptions.staleMs,
-            timeoutMs: lockOptions.timeoutMs,
-            retry: lockOptions.retry,
-            staleRecovery: lockOptions.staleRecovery,
-            allowReentrant: true,
-            payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
-        }, run);
+        return await serializePathWrite(`json-store:${canonicalPath}`, async () => {
+            const mutationPaths = new Set(activePaths);
+            mutationPaths.add(canonicalPath);
+            return await activeStoreMutations.run(mutationPaths, async () => {
+                if (!locks || !lockOptions) {
+                    return await run();
+                }
+                return await locks.withLock({
+                    targetPath: adapter.filePath,
+                    staleMs: lockOptions.staleMs,
+                    timeoutMs: lockOptions.timeoutMs,
+                    retry: lockOptions.retry,
+                    staleRecovery: lockOptions.staleRecovery,
+                    payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+                }, run);
+            });
+        });
     }
     return {
         filePath: adapter.filePath,
@@ -55,16 +70,16 @@ export function createJsonStore(adapter, options = {}) {
         readOr,
         readRequired: adapter.readRequired,
         write: async (value) => {
-            await withOptionalLock(async () => {
+            await withSerializedMutation(async () => {
                 await write(value);
             });
         },
-        update: async (run) => await withOptionalLock(async () => {
+        update: async (run) => await withSerializedMutation(async () => {
             const next = await run(await read());
             await write(next);
             return next;
         }),
-        updateOr: async (fallback, run) => await withOptionalLock(async () => {
+        updateOr: async (fallback, run) => await withSerializedMutation(async () => {
             const current = await read();
             const next = await run(current === undefined ? cloneFallback(fallback) : current);
             await write(next);

package/dist/move-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AAqPD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAyBf"}
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,sBAAsB,GAAG,cAAc,GAAG,uBAAuB,CAAC;AAEvE,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,sBAAsB,GAAG,SAAS,CASpC;AA4UD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAuCf"}