@openclaw/fs-safe 0.5.1 → 0.5.2

package/dist/sidecar-lock.js

@@ -1,13 +1,11 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
-import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotMatches, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
-import { FsSafeError } from "./errors.js";
-import { createNativeExclusiveFile } from "./native-operations.js";
+import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle } from "./sidecar-lock-handle.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, } from "./sidecar-lock-policy.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
+const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
+const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
 function getGlobalManagers() {
     const globalWithState = globalThis;
     if (!globalWithState[GLOBAL_STATE_KEY]) {
@@ -79,17 +77,6 @@ function snapshotMatchesSync(lockPath, observed) {
         }
     }
 }
-async function resolveNormalizedTargetPath(targetPath) {
-    const resolved = path.resolve(targetPath);
-    const dir = path.dirname(resolved);
-    await fs.mkdir(dir, { recursive: true });
-    try {
-        return path.join(await fs.realpath(dir), path.basename(resolved));
-    }
-    catch {
-        return resolved;
-    }
-}
 function releaseAllReclaimGuardsSync(state) {
     for (const reclaimGuardPath of state.reclaimGuards) {
         try {
@@ -116,6 +103,19 @@ function releaseAllLocksSync(state) {
     }
     releaseAllReclaimGuardsSync(state);
 }
+function ensureGlobalExitCleanupRegistered() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
+        return;
+    globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
+    const cleanup = () => {
+        for (const state of getGlobalManagers().values()) {
+            releaseAllLocksSync(state);
+        }
+    };
+    globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
+    process.on("exit", cleanup);
+}
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
     if (current !== held) {
@@ -164,217 +164,18 @@ function handleForHeldLock(state, normalizedTargetPath, held) {
 export function createSidecarLockManager(key) {
     const state = resolveManagerState(key);
     function ensureExitCleanupRegistered() {
-        if (!state.cleanupRegistered) {
-            state.cleanupRegistered = true;
-            state.reclaimCleanupRegistered = true;
-            process.on("exit", () => releaseAllLocksSync(state));
-            return;
-        }
-        if (!state.reclaimCleanupRegistered) {
-            state.reclaimCleanupRegistered = true;
-            process.on("exit", () => releaseAllReclaimGuardsSync(state));
-        }
+        state.cleanupRegistered = true;
+        state.reclaimCleanupRegistered = true;
+        ensureGlobalExitCleanupRegistered();
     }
     async function acquire(options) {
-        ensureExitCleanupRegistered();
-        const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
-        const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
-        const held = state.held.get(normalizedTargetPath);
-        if (held &&
-            options.reentrantOwner !== undefined &&
-            held.reentrantOwner !== undefined &&
-            options.reentrantOwner === held.reentrantOwner) {
-            held.refCount += 1;
-            return handleForHeldLock(state, normalizedTargetPath, held);
-        }
-        const startedAt = Date.now();
-        const retry = options.retry ?? {};
-        const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
-        const reclaimGuardPath = `${lockPath}.reclaim`;
-        let ownsReclaimGuard = false;
-        let attempt = 0;
-        const waitForRetry = async () => {
-            const elapsed = Date.now() - startedAt;
-            if ((options.timeoutMs !== undefined &&
-                options.timeoutMs !== Number.POSITIVE_INFINITY &&
-                elapsed >= options.timeoutMs) ||
-                (maxRetries !== undefined && attempt >= maxRetries)) {
-                throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                    code: "file_lock_timeout",
-                    lockPath,
-                    normalizedTargetPath,
-                });
-            }
-            const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
-                ? Number.POSITIVE_INFINITY
-                : Math.max(0, options.timeoutMs - elapsed);
-            const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
-            attempt += 1;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-        };
-        try {
-            while (true) {
-                if (!ownsReclaimGuard && (await sidecarReclaimGuardExists(reclaimGuardPath))) {
-                    await waitForRetry();
-                    continue;
-                }
-                let handle = null;
-                try {
-                    const payload = await options.payload();
-                    const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-                    if (options.lockRoot) {
-                        const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
-                        try {
-                            await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
-                        }
-                        catch (error) {
-                            if (error instanceof FsSafeError && error.code === "already-exists") {
-                                throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
-                            }
-                            throw error;
-                        }
-                        handle = (await options.lockRoot.open(relativeLockPath)).handle;
-                    }
-                    else {
-                        handle = (await createNativeExclusiveFile(lockPath, 0o600)) ?? await fs.open(lockPath, "wx");
-                        await handle.writeFile(raw, "utf8");
-                    }
-                    const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
-                    const createdHeld = {
-                        refCount: 1,
-                        reentrantOwner: options.reentrantOwner,
-                        handle,
-                        lockPath,
-                        snapshot,
-                        acquiredAt: Date.now(),
-                        metadata: options.metadata ?? {},
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    };
-                    state.held.set(normalizedTargetPath, createdHeld);
-                    if (ownsReclaimGuard) {
-                        try {
-                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                            ownsReclaimGuard = false;
-                        }
-                        catch (err) {
-                            await releaseHeldLock(state, normalizedTargetPath, createdHeld, { force: true });
-                            throw err;
-                        }
-                    }
-                    const returnedHandle = handleForHeldLock(state, normalizedTargetPath, createdHeld);
-                    const interval = options.compromiseCheckIntervalMs;
-                    if (options.onCompromised && interval !== undefined && interval > 0) {
-                        createdHeld.compromiseTimer = setInterval(() => {
-                            void returnedHandle.verifyStillHeld().then((stillHeld) => {
-                                if (!stillHeld && createdHeld.compromiseTimer) {
-                                    clearInterval(createdHeld.compromiseTimer);
-                                    createdHeld.compromiseTimer = undefined;
-                                    options.onCompromised?.({ lockPath, normalizedTargetPath });
-                                }
-                            });
-                        }, interval);
-                        createdHeld.compromiseTimer.unref();
-                    }
-                    return returnedHandle;
-                }
-                catch (err) {
-                    if (handle) {
-                        const failedSnapshot = { payload: null };
-                        try {
-                            failedSnapshot.stat = await handle.stat();
-                        }
-                        catch {
-                            // Best-effort cleanup of a failed exclusive create.
-                        }
-                        const current = state.held.get(normalizedTargetPath);
-                        if (current?.handle === handle) {
-                            state.held.delete(normalizedTargetPath);
-                        }
-                        // If payload serialization/write fails, the file may be empty or
-                        // partial JSON, so remove while our exclusive handle is still open.
-                        if (!options.lockRoot) {
-                            await fs.rm(lockPath, { force: true }).catch(() => undefined);
-                        }
-                        await handle.close().catch(() => undefined);
-                        // Windows can refuse removing an open file; retry after close but
-                        // only if the path still points at the file identity we created.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        });
-                    }
-                    if (err.code !== "EEXIST") {
-                        throw err;
-                    }
-                    if (ownsReclaimGuard) {
-                        await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                        ownsReclaimGuard = false;
-                        continue;
-                    }
-                    const nowMs = Date.now();
-                    const snapshot = await readSidecarLockSnapshot(lockPath, {
-                        lockRoot: options.lockRoot,
-                        parsePayload: options.parsePayload,
-                    });
-                    if (!snapshot) {
-                        continue;
-                    }
-                    if (state.held.has(normalizedTargetPath)) {
-                        await waitForRetry();
-                        continue;
-                    }
-                    const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
-                    if (await shouldReclaim({
-                        lockPath,
-                        normalizedTargetPath,
-                        payload: snapshot?.payload ?? null,
-                        staleMs: options.staleMs,
-                        nowMs,
-                        heldByThisProcess: state.held.has(normalizedTargetPath),
-                    })) {
-                        if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
-                            lockRoot: options.lockRoot,
-                            parsePayload: options.parsePayload,
-                        }))) {
-                            continue;
-                        }
-                        const staleRecovery = options.staleRecovery ?? "fail-closed";
-                        if (staleRecovery === "remove-if-unchanged") {
-                            if (!(await tryAcquireSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath))) {
-                                await waitForRetry();
-                                continue;
-                            }
-                            ownsReclaimGuard = true;
-                            const removal = await removeStaleSidecarLockIfAllowed({
-                                lockPath,
-                                normalizedTargetPath,
-                                snapshot,
-                                shouldRemoveStaleLock: options.shouldRemoveStaleLock,
-                                lockRoot: options.lockRoot,
-                                parsePayload: options.parsePayload,
-                            });
-                            if (removal === "removed" || removal === "changed") {
-                                continue;
-                            }
-                            await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath);
-                            ownsReclaimGuard = false;
-                        }
-                        throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                            code: "file_lock_stale",
-                            lockPath,
-                            normalizedTargetPath,
-                        });
-                    }
-                    await waitForRetry();
-                }
-            }
-        }
-        finally {
-            if (ownsReclaimGuard) {
-                await releaseSidecarReclaimGuard(state.reclaimGuards, reclaimGuardPath).catch(() => undefined);
-            }
-        }
+        return await acquireSidecarLock(options, {
+            held: state.held,
+            reclaimGuards: state.reclaimGuards,
+            ensureExitCleanupRegistered,
+            handleForHeldLock: (normalizedTargetPath, held) => handleForHeldLock(state, normalizedTargetPath, held),
+            releaseHeldLock: async (normalizedTargetPath, held, releaseOptions) => await releaseHeldLock(state, normalizedTargetPath, held, releaseOptions),
+        });
     }
     async function withLock(options, fn) {
         const lock = await acquire(options);

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
-import { mkdtemp, rm } from "node:fs/promises";
+import { lstat, mkdtemp, rm } from "node:fs/promises";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
@@ -89,8 +90,17 @@ function isNodeErrorWithCode(err, code) {
         "code" in err &&
         err.code === code);
 }
-async function cleanupTempDir(dir, onCleanupError) {
+async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
+        const current = await lstat(dir).catch((error) => {
+            if (isNodeErrorWithCode(error, "ENOENT")) {
+                return undefined;
+            }
+            throw error;
+        });
+        if (!current || !sameFileIdentity(current, identity)) {
+            return;
+        }
         await rm(dir, { recursive: true, force: true });
     }
     catch (err) {
@@ -106,11 +116,12 @@ export async function tempFile(params) {
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
     const dir = await mkdtemp(path.join(rootDir, prefix));
-    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true });
+    const identity = await lstat(dir);
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
     const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
     const cleanup = async () => {
         try {
-            await cleanupTempDir(dir, params.onCleanupError);
+            await cleanupTempDir(dir, identity, params.onCleanupError);
         }
         finally {
             unregisterTempDir();

package/dist/test-hooks.d.ts

@@ -10,6 +10,7 @@ export type FsSafeTestHooks = {
     beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
     afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
     beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+    beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
     beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;

package/dist/test-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}
+{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,6BAA6B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/timing.d.ts

@@ -1,3 +1,5 @@
+export declare function sleep(ms: number): Promise<void>;
+export declare function sleepSync(ms: number): void;
 export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, labelOrOptions?: string | {
     label?: string;
     message?: string;

package/dist/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAK1C;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/timing.js

@@ -1,3 +1,12 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function sleepSync(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 export async function withTimeout(promise, timeoutMs, labelOrOptions = {
     message: "timeout",
 }) {

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA8EF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAwDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAwD1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA+FF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}

package/dist/walk.js

@@ -1,6 +1,19 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+function validateWalkBudget(name, value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function validateWalkOptions(options) {
+    validateWalkBudget("maxDepth", options.maxDepth);
+    validateWalkBudget("maxEntries", options.maxEntries);
+    if (options.symlinks !== undefined &&
+        !["skip", "follow", "include"].includes(options.symlinks)) {
+        throw new TypeError(`invalid walk symlink policy: ${String(options.symlinks)}`);
+    }
+}
 function kindForDirent(dirent) {
     if (dirent.isDirectory())
         return "directory";
@@ -75,6 +88,7 @@ async function resolveAsyncKind(fullPath, dirent, symlinks) {
     return "other";
 }
 export function walkDirectorySync(rootDir, options = {}) {
+    validateWalkOptions(options);
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {
@@ -133,6 +147,7 @@ export function walkDirectorySync(rootDir, options = {}) {
     return result;
 }
 export async function walkDirectory(rootDir, options = {}) {
+    validateWalkOptions(options);
     const root = path.resolve(rootDir);
     const symlinks = options.symlinks ?? "skip";
     const result = {

package/docs/advanced.md

@@ -56,7 +56,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
-| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level no-follow open routed through the root-file path. |
+| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `rejectSymlinks: false` for explicit in-root following. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |

package/docs/archive.md

@@ -42,10 +42,10 @@ await extractArchive({
 ### Parameters
 
 ```ts
-type ExtractArchiveParams = {
+type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
-  timeoutMs: number;            // wall-clock cap; throws on overrun
+  timeoutMs: number;            // positive wall-clock cap; <= 0/non-finite disables it
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
@@ -107,7 +107,7 @@ of leaving a paused parser to drain indefinitely. The native path finishes its
 bounded manifest read before TypeScript policy evaluation, so a rejected plan
 never starts the extraction worker.
 
-If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names).
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline.
 
 ### Limits
 
@@ -122,18 +122,22 @@ type ArchiveExtractLimits = {
 };
 ```
 
-Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
 
-A limit violation throws `ArchiveLimitError`. The error's code is one of:
+A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 
-```ts
-ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT
-```
+| Constant | Code |
+|---|---|
+| `ARCHIVE_SIZE_EXCEEDS_LIMIT` | `archive-size-exceeds-limit` |
+| `ENTRY_COUNT_EXCEEDS_LIMIT` | `archive-entry-count-exceeds-limit` |
+| `EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-extracted-size-exceeds-limit` |
+| `ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT` | `archive-entry-extracted-size-exceeds-limit` |
+| `META_ENTRY_SIZE_EXCEEDS_LIMIT` | `archive-meta-entry-size-exceeds-limit` |
+| `ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT` | `archive-entry-path-components-exceeds-limit` |
+| `MANIFEST_SIZE_EXCEEDS_LIMIT` | `archive-manifest-size-exceeds-limit` |
+
+`MANIFEST_SIZE_EXCEEDS_LIMIT` is retained in the public compatibility union;
+no current public extractor emits it.
 
 Catch and branch on the code to surface a meaningful response to the caller.
 
@@ -144,10 +148,12 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 
 ## What it defends against
 
-- **Path traversal:** entries with `..`, absolute paths, or Windows drive prefixes are rejected (`ArchiveSecurityError`).
+- **Path traversal:** entries with `..`, absolute paths, NUL bytes, or Windows drive-relative segments such as `C:secret` and `nested/C:secret` are rejected (`ArchiveSecurityError`).
 - **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
+- **Ambiguous output names:** duplicate names and distinct names that collide after `stripComponents`, case normalization, or Unicode normalization are rejected instead of relying on backend- or volume-specific overwrite order.
 - **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. Destination symlink swaps are checked with the selected platform mechanism; non-Linux routes retain the best-effort race window documented in the [security model](security-model.md#containment-guarantees-by-platform).
 - **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
+- **Corrupt ZIP payloads:** streamed output must match both the central-directory CRC and declared uncompressed size before it can leave private staging.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
 - **Metadata bombs:** a fixed-header pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 size fields without interpreting metadata content.
 
@@ -168,7 +174,7 @@ import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive"
 const kind = resolveArchiveKind("upload.zip"); // "zip"
 const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
 const zstd = resolveArchiveKind("upload.tar.zst"); // "tar-zstd" when native is available
-const unknown = resolveArchiveKind("upload.bin"); // undefined
+const unknown = resolveArchiveKind("upload.bin"); // null
 ```
 
 Recognizes:
@@ -178,7 +184,7 @@ Recognizes:
 - `*.tar.zst`, `*.tar.zstd`, `*.tzst` → `"tar-zstd"` (native only)
 - `*.tar.bz2`, `*.tbz2`, `*.tbz` → `"tar-bzip2"` (native only)
 
-Returns `undefined` for unknown extensions; check the result before calling
+Returns `null` for unknown extensions; check the result before calling
 `extractArchive` if the filename is caller-controlled. A recognized zstd or
 bzip2 TAR extension with no native binding throws the typed
 `FsSafeError("helper-unavailable")` with installation guidance. This includes
@@ -204,7 +210,8 @@ await extractArchive({
 
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
 regular-file entry into a bounded `Buffer` without extracting a tree. It pins
-and privately stages the archive input, rejects link and directory entries,
+and privately stages the archive input, rejects link, directory, and duplicate
+entries, verifies ZIP CRC and declared size,
 and throws `ArchiveLimitError` if decompressed bytes exceed `maxBytes`. ZIP
 inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
@@ -248,11 +255,11 @@ import {
 } from "@openclaw/fs-safe/archive";
 ```
 
-- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, drive-prefixed, or otherwise unsafe entry paths.
-- `normalizeArchiveEntryPath(raw)` — POSIX-normalizes the entry path (forward slashes, no `.` segments).
+- `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, NUL-containing, drive-relative, or otherwise unsafe entry paths.
+- `normalizeArchiveEntryPath(raw)` — converts backslashes in the entry path to forward slashes.
 - `stripArchivePath(entryPath, n)` — strip the leading N path components, returning `null` if not enough remain.
 - `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
-- `isWindowsDrivePath(value)` — detects `C:\…` style entries that should be rejected.
+- `isWindowsDrivePath(value)` — detects drive-relative segments such as `C:secret` or `nested/C:secret` that should be rejected.
 
 ## Common patterns