@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync.js

@@ -0,0 +1,341 @@
+import fs from "node:fs";
+import { acquireFileLockSyncWithRoot } from "./file-lock-sync-root-acquire.js";
+import { withSyncHeldLockHandle } from "./file-lock-sync-root-held.js";
+import path from "node:path";
+import { readSidecarLockRawSnapshotSync, readSidecarLockSnapshotSync, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { sidecarLockTimeout, isTransientLockFileDenial, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { getFsSafeLockConfig } from "./lock-config.js";
+import { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { ensureSyncLockExitCleanupRegistered, getSyncHeldLocks, foreignSyncHeldLock, getSyncLockAdmissions, syncReclaimGuardExists, } from "./file-lock-sync-admission.js";
+import { handleSyncStaleAdmission, } from "./file-lock-sync-stale-admission.js";
+function releaseAllSyncHeldLocks() {
+    const heldLocks = getSyncHeldLocks();
+    for (const [normalizedTargetPath, held] of heldLocks) {
+        if (held.timer) {
+            clearInterval(held.timer);
+            held.timer = undefined;
+        }
+        try {
+            if (held.fd !== undefined)
+                fs.closeSync(held.fd);
+        }
+        catch {
+            // Best-effort process-exit cleanup.
+        }
+        try {
+            removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+        }
+        catch {
+            // A surviving sidecar fails closed and can be reclaimed by policy.
+        }
+        heldLocks.delete(normalizedTargetPath);
+    }
+    getSyncLockAdmissions().clear();
+}
+function verifySyncHeldLock(held) {
+    const lockPath = held.lockPath;
+    const parsePayload = held.parsePayload;
+    const current = parsePayload
+        ? readSidecarLockSnapshotSync(lockPath, parsePayload)
+        : readSidecarLockRawSnapshotSync(lockPath);
+    return !!current && sidecarLockSnapshotMatches(current, held.snapshot);
+}
+function releaseSyncHeldLock(held) {
+    const heldLocks = getSyncHeldLocks();
+    if (heldLocks.get(held.normalizedTargetPath) !== held)
+        return false;
+    if (held.refCount > 1) {
+        held.refCount -= 1;
+        return false;
+    }
+    // Keep the final reference and cleanup receipt until deletion succeeds.
+    if (held.timer) {
+        clearInterval(held.timer);
+        held.timer = undefined;
+    }
+    if (held.fd !== undefined) {
+        const fd = held.fd;
+        // A close error may still free the number; consume ownership before closing.
+        held.fd = undefined;
+        fs.closeSync(fd);
+    }
+    removeSidecarLockIfUnchangedSync(held.lockPath, held.snapshot);
+    heldLocks.delete(held.normalizedTargetPath);
+    return true;
+}
+function createSyncHeldLockHandle(held) {
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        releaseSyncHeldLock(held);
+        released = true;
+    };
+    return {
+        lockPath: held.lockPath,
+        normalizedTargetPath: held.normalizedTargetPath,
+        verifyStillHeld: () => verifySyncHeldLock(held),
+        release,
+        [Symbol.dispose]: release,
+    };
+}
+function canonicalLockParentSync(parent) {
+    // Match Root's async realpath, including Windows short-name expansion.
+    return process.platform === "win32" ? realpathSync.native(parent) : realpathSync(parent);
+}
+function normalizeTargetPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    assertNoWindowsPathAlias(resolved);
+    fs.mkdirSync(recursiveMkdirPath(path.dirname(resolved)), { recursive: true });
+    let parent;
+    try {
+        parent = canonicalLockParentSync(path.dirname(resolved));
+    }
+    catch {
+        return resolved;
+    }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
+}
+export function acquireFileLockSync(targetPath, options) {
+    const lockRoot = options.lockRoot;
+    if (lockRoot)
+        return acquireFileLockSyncWithRoot(targetPath, options, lockRoot);
+    const defaults = getFsSafeLockConfig();
+    const retry = options.retry ?? defaults.retry ?? {};
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(timeoutMs);
+    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
+    validateSidecarLockStaleMs(staleMs);
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    const explicitLockPath = options.lockPath;
+    assertNoWindowsPathAlias(targetPath);
+    if (explicitLockPath !== undefined)
+        assertNoWindowsPathAlias(explicitLockPath);
+    const normalizedTargetPath = normalizeTargetPath(targetPath);
+    const lockPath = path.resolve(explicitLockPath ?? `${normalizedTargetPath}.lock`);
+    assertNoWindowsPathAlias(lockPath);
+    const requestedReentrantOwner = options.reentrantOwner;
+    const heldLocks = getSyncHeldLocks();
+    const currentTargetHolder = () => heldLocks.get(normalizedTargetPath) ??
+        foreignSyncHeldLock("raw", normalizedTargetPath);
+    const initiallyHeld = heldLocks.get(normalizedTargetPath);
+    if (initiallyHeld && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+        requestedReentrantOwner !== undefined &&
+        initiallyHeld.reentrantOwner !== undefined &&
+        requestedReentrantOwner === initiallyHeld.reentrantOwner) {
+        initiallyHeld.refCount += 1;
+        return createSyncHeldLockHandle(initiallyHeld);
+    }
+    const acquisition = new SyncLockAcquisition(lockPath, normalizedTargetPath, retry, timeoutMs);
+    let payloadCallback;
+    let onCompromised = undefined;
+    let onCompromisedObserved = false;
+    let parsePayload = undefined;
+    let parsePayloadObserved = false;
+    let staleRecovery = undefined;
+    let staleRecoveryObserved = false;
+    const staleOptions = {};
+    const reclaimGuardPath = `${lockPath}.reclaim`;
+    try {
+        while (true) {
+            if (!acquisition.owns) {
+                const held = heldLocks.get(normalizedTargetPath);
+                if (held && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+                    requestedReentrantOwner !== undefined &&
+                    held.reentrantOwner !== undefined &&
+                    requestedReentrantOwner === held.reentrantOwner) {
+                    held.refCount += 1;
+                    return createSyncHeldLockHandle(held);
+                }
+                acquisition.reserve();
+            }
+            const attemptHeld = currentTargetHolder();
+            const holderWasReplaced = () => {
+                const current = currentTargetHolder();
+                return current !== undefined && current !== attemptHeld;
+            };
+            if (!staleRecoveryObserved) {
+                staleRecovery = acquisition.run(() => options.staleRecovery ?? defaults.staleRecovery);
+                staleRecoveryObserved = true;
+                if (holderWasReplaced()) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+            }
+            const reclaimGuardExists = syncReclaimGuardExists(reclaimGuardPath);
+            if (!acquisition.hasToken())
+                throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            if (reclaimGuardExists) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            let fd;
+            let createdHeld;
+            let createdSnapshot;
+            if (!payloadCallback)
+                payloadCallback = acquisition.run(() => options.payload);
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            const payload = acquisition.run(() => Reflect.apply(payloadCallback, options, []));
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            const { raw, ownershipToken } = acquisition.run(() => serializeSidecarLockPayload(payload));
+            if (holderWasReplaced()) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            if (currentTargetHolder() !== undefined) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            if (!onCompromisedObserved) {
+                onCompromised = acquisition.run(() => options.onCompromised);
+                onCompromisedObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+            }
+            if (!parsePayloadObserved) {
+                parsePayload = acquisition.run(() => options.parsePayload);
+                parsePayloadObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+            }
+            let lockFileCreateDenied = false;
+            let exclusiveCreateConflict = false;
+            try {
+                const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+                    ? fs.constants.O_NOFOLLOW
+                    : 0;
+                try {
+                    fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+                }
+                catch (error) {
+                    lockFileCreateDenied = isTransientLockFileDenial(error, lockPath);
+                    exclusiveCreateConflict = error.code === "EEXIST";
+                    throw error;
+                }
+                fs.writeFileSync(fd, raw, "utf8");
+                fs.fsyncSync(fd);
+                createdSnapshot = {
+                    raw,
+                    payload,
+                    stat: fs.fstatSync(fd),
+                    ownershipToken,
+                };
+                createdHeld = {
+                    fd,
+                    lockPath,
+                    normalizedTargetPath,
+                    parsePayload,
+                    refCount: 1,
+                    reentrantOwner: requestedReentrantOwner,
+                    snapshot: createdSnapshot,
+                };
+                const candidateHeld = createdHeld;
+                ensureSyncLockExitCleanupRegistered(releaseAllSyncHeldLocks, lockPath, normalizedTargetPath);
+                if (!acquisition.hasToken() || currentTargetHolder() !== undefined) {
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                }
+                const returnedHandle = createSyncHeldLockHandle(candidateHeld);
+                acquisition.monitor(candidateHeld, returnedHandle, onCompromised, compromiseCheckIntervalMs, options);
+                if (!acquisition.hasToken() ||
+                    currentTargetHolder() !== undefined) {
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                }
+                heldLocks.set(normalizedTargetPath, candidateHeld);
+                acquisition.release();
+                fd = undefined;
+                return returnedHandle;
+            }
+            catch (error) {
+                if (createdHeld?.timer) {
+                    clearInterval(createdHeld.timer);
+                    createdHeld.timer = undefined;
+                }
+                if (createdHeld && heldLocks.get(normalizedTargetPath) === createdHeld) {
+                    heldLocks.delete(normalizedTargetPath);
+                }
+                if (fd !== undefined) {
+                    const failed = createdSnapshot ?? { payload: null };
+                    if (!failed.stat) {
+                        try {
+                            failed.stat = fs.fstatSync(fd);
+                        }
+                        catch {
+                            // Missing identity leaves the sidecar in place, but must not skip close.
+                        }
+                    }
+                    const failedFd = fd;
+                    fd = undefined;
+                    if (createdHeld)
+                        createdHeld.fd = undefined;
+                    try {
+                        fs.closeSync(failedFd);
+                        if (failed.stat)
+                            removeSidecarLockIfUnchangedSync(lockPath, failed);
+                    }
+                    catch (cleanupError) {
+                        throw createSuppressedError(error, cleanupError, "file lock acquisition and cleanup both failed");
+                    }
+                }
+                if (lockFileCreateDenied) {
+                    if (!acquisition.hasToken())
+                        throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                    if (currentTargetHolder() !== undefined) {
+                        acquisition.waitForRetry();
+                        continue;
+                    }
+                    if (acquisition.retryDenial(error))
+                        continue;
+                    throw error;
+                }
+                if (!exclusiveCreateConflict)
+                    throw error;
+                if (!acquisition.hasToken())
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+                if (currentTargetHolder() !== undefined) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                handleSyncStaleAdmission(acquisition, {
+                    currentHeld: currentTargetHolder,
+                    options,
+                    parsePayload,
+                    reclaimGuardPath,
+                    staleMs,
+                    staleOptions,
+                    staleRecovery,
+                });
+                continue;
+            }
+        }
+    }
+    finally {
+        acquisition.release();
+    }
+}
+export function withFileLockSync(targetPath, options, fn) {
+    const lock = acquireFileLockSync(targetPath, options);
+    return withSyncHeldLockHandle(lock, fn);
+}

package/node_modules/@openclaw/fs-safe/dist/file-lock.d.ts

@@ -0,0 +1,23 @@
+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"> & {
+    managerKey?: string;
+    staleMs?: number;
+};
+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>;
+    drain(): Promise<void>;
+    reset(): void;
+    heldEntries(): FileLockHeldEntry[];
+};
+export declare function acquireFileLock<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
+export declare function withFileLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
+export declare function createFileLockManager(key: string): FileLockManager;
+export declare function drainFileLockManagerForTest(targetPath: string, managerKey?: string): Promise<void>;
+export declare function resetFileLockManagerForTest(targetPath: string, managerKey?: string): void;

package/node_modules/@openclaw/fs-safe/dist/file-lock.js

@@ -0,0 +1,66 @@
+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}`;
+}
+function withLockDefaults(options) {
+    const { managerKey: _managerKey, lockPath } = options;
+    const acquireOptions = {};
+    for (const key of Reflect.ownKeys(options)) {
+        // Node 22 object-rest can read excluded accessors; exclude before copying.
+        if (key === "managerKey" || key === "lockPath")
+            continue;
+        if (!Object.getOwnPropertyDescriptor(options, key)?.enumerable)
+            continue;
+        Object.defineProperty(acquireOptions, key, {
+            value: Reflect.get(options, key),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    const defaults = getFsSafeLockConfig();
+    return {
+        ...acquireOptions,
+        retry: acquireOptions.retry ?? defaults.retry,
+        staleMs: acquireOptions.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: acquireOptions.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: acquireOptions.timeoutMs ?? defaults.timeoutMs,
+        ...(lockPath === undefined ? {} : { lockPath }),
+    };
+}
+export async function acquireFileLock(targetPath, options) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .acquire(targetPath, options);
+}
+export async function withFileLock(targetPath, options, fn) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .withLock(targetPath, options, fn);
+}
+export function createFileLockManager(key) {
+    const manager = createSidecarLockManager(key);
+    return {
+        acquire: async (targetPath, options) => {
+            return await manager.acquire({
+                ...withLockDefaults(options),
+                targetPath,
+            });
+        },
+        withLock: async (targetPath, options, fn) => {
+            return await manager.withLock({
+                ...withLockDefaults(options),
+                targetPath,
+            }, fn);
+        },
+        drain: manager.drain,
+        reset: manager.reset,
+        heldEntries: manager.heldEntries,
+    };
+}
+export async function drainFileLockManagerForTest(targetPath, managerKey) {
+    await createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).drain();
+}
+export function resetFileLockManagerForTest(targetPath, managerKey) {
+    createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).reset();
+}

package/node_modules/@openclaw/fs-safe/dist/file-observation.d.ts

@@ -0,0 +1,8 @@
+type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}` | `stat-leaf-missing:${string}` | `stat-leaf-changed:${string}`;
+export declare function recordFileObservationFailure(error: unknown, kind: FailureKind): void;
+export declare function isFileObservationFailure(error: unknown, kind: FailureKind): boolean;
+export declare function fileObservation(): {
+    run<T>(operation: () => T): T;
+    has(error: unknown, kind: FailureKind): boolean;
+};
+export {};

package/node_modules/@openclaw/fs-safe/dist/file-observation.js

@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const active = new AsyncLocalStorage();
+export function recordFileObservationFailure(error, kind) {
+    const failures = active.getStore();
+    if (!failures)
+        return;
+    let kinds = failures.get(error);
+    if (!kinds)
+        failures.set(error, kinds = new Set());
+    kinds.add(kind);
+}
+export function isFileObservationFailure(error, kind) {
+    return active.getStore()?.get(error)?.has(kind) === true;
+}
+// Each Root observation owns its receipts, including nested and concurrent reads.
+export function fileObservation() {
+    const failures = new Map();
+    return {
+        run(operation) { return active.run(failures, operation); },
+        has(error, kind) { return failures.get(error)?.has(kind) === true; },
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/file-store-boundary.d.ts

@@ -0,0 +1,38 @@
+import type { Readable } from "node:stream";
+import { type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
+import { type Root } from "./root.js";
+import { prepareSecretFileWrite } from "./secret-file.js";
+export type SyncParentGuard = SyncStoreDirectoryReceipt;
+export declare function ensureParentInRoot(scopedRoot: Root, relativePath: string, mode: number): Promise<void>;
+export declare function openWritableStoreRoot(params: {
+    rootDir: string;
+    dirMode: number;
+    maxBytes?: number;
+}): Promise<Root>;
+export declare function openPrivateStoreLockRoot(params: Parameters<typeof prepareSecretFileWrite>[0]): Promise<Root>;
+export declare function writeStreamToTempSource(params: {
+    stream: Readable;
+    maxBytes?: number;
+    mode: number;
+}): Promise<{
+    path: string;
+    cleanup: () => Promise<void>;
+}>;
+export declare function ensureParentSync(params: {
+    rootDir: string;
+    filePath: string;
+    mode: number;
+}): SyncParentGuard;
+export declare function ensureStoreDirectorySync(params: {
+    rootDir: string;
+    targetDir: string;
+    mode: number;
+    messagePrefix: "private store" | "store";
+}): SyncParentGuard;
+export declare function assertRelativePath(relativePath: string): string;
+export declare function resolveStorePath(rootDir: string, relativePath: string): string;
+export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;
+export declare function readFileStoreCopySource(params: {
+    sourcePath: string;
+    maxBytes: number;
+}): Promise<Buffer>;

package/node_modules/@openclaw/fs-safe/dist/file-store-boundary.js

@@ -0,0 +1,177 @@
+import syncFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createByteLimitTransform } from "./bounded-read-stream.js";
+import { pipeline } from "node:stream/promises";
+import { FsSafeError } from "./errors.js";
+import { assertSyncStoreDirectoryReceipt, ensureSyncStoreDirectory, } from "./file-store-sync-directory.js";
+import { isPathInside, splitSafeRelativePath } from "./path.js";
+import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
+import { ensureTrailingSep } from "./root-context.js";
+import { RootHandle } from "./root-impl.js";
+import { prepareSecretFileWrite } from "./secret-file.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { readRegularFile } from "./regular-file.js";
+import { errorCauseOptions } from "./root-errors.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
+    const parent = path.posix.dirname(relativePath);
+    if (parent === ".") {
+        return;
+    }
+    await scopedRoot.mkdir(parent);
+    await chmodDirectoryInRootBestEffort(scopedRoot, parent, mode).catch(() => undefined);
+}
+export async function openWritableStoreRoot(params) {
+    assertNoWindowsPathAlias(params.rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    await fs.mkdir(recursiveMkdirPath(params.rootDir), { recursive: true, mode: params.dirMode });
+    await fs.chmod(params.rootDir, params.dirMode).catch(() => undefined);
+    return await root(params.rootDir, { hardlinks: "reject", maxBytes: params.maxBytes });
+}
+export async function openPrivateStoreLockRoot(params) {
+    const { parentGuard } = await prepareSecretFileWrite(params);
+    // Bind to the admitted parent, never resolve a replacement into a fresh capability.
+    return new RootHandle({
+        rootDir: parentGuard.dir,
+        rootGuard: { dir: parentGuard.realPath, realPath: parentGuard.realPath, stat: parentGuard.stat },
+        rootReal: parentGuard.realPath,
+        rootWithSep: ensureTrailingSep(parentGuard.realPath),
+        rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
+    }, { hardlinks: "reject" });
+}
+async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
+    const dirPath = await scopedRoot.resolve(relativePath);
+    const directoryFlag = "O_DIRECTORY" in syncFs.constants ? syncFs.constants.O_DIRECTORY : 0;
+    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants
+        ? syncFs.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fs.open(dirPath, syncFs.constants.O_RDONLY | directoryFlag | noFollowFlag);
+    try {
+        const stat = syncFs.fstatSync(handle.fd);
+        if (!stat.isDirectory()) {
+            return;
+        }
+        const realPath = await resolveOpenedFileRealPathForHandle(handle, dirPath);
+        if (!isPathInside(scopedRoot.rootWithSep, realPath)) {
+            throw new FsSafeError("outside-workspace", "directory is outside store root");
+        }
+        await handle.chmod(mode).catch(() => undefined);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function writeStreamToTempSource(params) {
+    const maxBytes = params.maxBytes;
+    const tempRoot = resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-file-store",
+        unsafeFallbackLabel: "file store temp dir",
+        warn: () => undefined,
+    });
+    const dir = await fs.mkdtemp(path.join(tempRoot, "fs-safe-file-store-"));
+    const filePath = path.join(dir, "payload");
+    let handle = null;
+    let handleClosedByStream = false;
+    try {
+        handle = await fs.open(filePath, "wx", params.mode);
+        const writable = handle.createWriteStream();
+        writable.once("close", () => {
+            handleClosedByStream = true;
+        });
+        const limiter = maxBytes === undefined ? undefined : createByteLimitTransform(maxBytes, () => new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`));
+        if (limiter) {
+            await pipeline(params.stream, limiter, writable);
+        }
+        else {
+            await pipeline(params.stream, writable);
+        }
+        if (!handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.chmod(filePath, params.mode).catch(() => undefined);
+        return {
+            path: filePath,
+            cleanup: async () => {
+                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+            },
+        };
+    }
+    catch (err) {
+        if (handle && !handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+export function ensureParentSync(params) {
+    assertNoWindowsPathAlias(params.rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(params.filePath, "filesystem", "store path uses a Windows filesystem namespace alias");
+    return ensureStoreDirectorySync({
+        rootDir: params.rootDir,
+        targetDir: path.dirname(path.resolve(params.filePath)),
+        mode: params.mode,
+        messagePrefix: "store",
+    });
+}
+export function ensureStoreDirectorySync(params) {
+    const guard = ensureSyncStoreDirectory(params);
+    assertSyncStoreDirectoryReceipt(guard);
+    return guard;
+}
+export function assertRelativePath(relativePath) {
+    const raw = relativePath.trim();
+    if (!raw || raw !== relativePath) {
+        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
+    }
+    const segments = splitSafeRelativePath(raw);
+    if (segments.length === 0 ||
+        segments.join("/") !== raw ||
+        raw.normalize("NFC") !== raw ||
+        segments.some((segment) => /[ .]$/u.test(segment))) {
+        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
+    }
+    return raw;
+}
+export function resolveStorePath(rootDir, relativePath) {
+    const key = assertRelativePath(relativePath);
+    // FileStore constructors snapshot an absolute root before this helper runs.
+    // Do not re-resolve it: Node drops the trailing separator from an exact
+    // Windows namespace drive root such as `\\?\C:\`.
+    const root = path.isAbsolute(rootDir) ? rootDir : path.resolve(rootDir);
+    // The immutable key already passed segment validation; keep the containment check.
+    const target = path.resolve(root, key);
+    if (!isPathInside(root, target)) {
+        throw new FsSafeError("outside-workspace", "relative path escapes root");
+    }
+    return target;
+}
+// Store operation boundaries admit the primitive limit before reaching this helper.
+export function assertFileStoreMaxBytes(size, limit) {
+    if (limit !== undefined && size > limit) {
+        throw new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`);
+    }
+}
+export async function readFileStoreCopySource(params) {
+    assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
+    const sourceStat = syncFs.lstatSync(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
+    try {
+        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
+            .buffer;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("regular file") || message.includes("not a regular file")) {
+            throw new FsSafeError("not-file", "source path is not a file", errorCauseOptions(error));
+        }
+        if (message.includes(`exceeds ${params.maxBytes} bytes`)) {
+            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, errorCauseOptions(error));
+        }
+        throw error;
+    }
+}