@openclaw/fs-safe 0.18.0 → 0.18.1

package/dist/creation-boundary.js

@@ -0,0 +1,371 @@
+import fs, {} from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { nodeDarwinDirectoryMetadataFlags, nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { assertNoNulPathInput } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+import { inspectWindowsDirectoryCommand, inspectWindowsDirectoryCommandSync, protectPrivateWindowsFileCommand, protectPrivateWindowsFileCommandSync, verifyPrivateWindowsFileCommand, verifyPrivateWindowsFileCommandSync, hasUnsettledWindowsSecurityCommand, } from "./windows-security-command.js";
+export function resolveCreationPermissions(options, directory) {
+    const privatePath = options.private;
+    const mode = options.mode;
+    if (privatePath !== undefined && typeof privatePath !== "boolean") {
+        throw new TypeError("private must be a boolean");
+    }
+    if (mode !== undefined && (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)) {
+        throw new RangeError("mode must contain only permission bits");
+    }
+    if (privatePath && mode !== undefined && (mode & 0o7077) !== 0) {
+        throw new FsSafeError("insecure-permissions", "private creation requires owner-only permission bits");
+    }
+    if (privatePath)
+        assertDarwinPrivateCreationAvailable();
+    if (privatePath && directory)
+        assertDarwinPrivateDirectoryMode(mode ?? 0o700);
+    return { private: privatePath === true, mode: mode ?? (privatePath ? directory ? 0o700 : 0o600 : undefined) };
+}
+function assertPrivatePosixDirectory(stat) {
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "private directory must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "existing directory is not private");
+    }
+}
+function unavailable() {
+    throw new FsSafeError("helper-unavailable", "private Windows creation requires an up-to-date native helper");
+}
+export function assertPrivateFileCreationAvailable() {
+    const native = getNativeBinding();
+    if (process.platform !== "win32" || getFsSafeNativeConfig().mode !== "require")
+        return;
+    if (typeof native?.createPrivateDirectoryWithParentIdentity !== "function" ||
+        typeof native.inspectWindowsDirectory !== "function" ||
+        typeof native.protectPrivateWindowsFile !== "function" ||
+        typeof native.verifyPrivateWindowsFile !== "function")
+        unavailable();
+}
+function commandFallback() {
+    if (getFsSafeNativeConfig().mode === "require")
+        unavailable();
+    warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
+}
+function creationOperation(name) {
+    const native = getNativeBinding();
+    const operation = native?.[name];
+    if (typeof operation === "function")
+        return operation.bind(native);
+    commandFallback();
+    return undefined;
+}
+/** Full Windows identity, with security validation when requested; no repairs. */
+export function inspectCreationDirectorySync(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : inspectWindowsDirectoryCommandSync(targetPath, privatePath)).identity;
+}
+export async function inspectCreationDirectory(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
+}
+export function assertPrivateDirectorySync(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        inspectCreationDirectorySync(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export async function assertPrivateDirectory(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        await inspectCreationDirectory(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export function protectCreatedFileSync(fd, targetPath, parentIdentity) {
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity)).identity;
+}
+export async function protectCreatedFile(fd, targetPath, parentIdentity) {
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
+}
+export function verifyCreatedFileSync(fd, targetPath, identity, parentIdentity, links = 1) {
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
+}
+export async function verifyCreatedFile(fd, targetPath, identity, parentIdentity, links = 1) {
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
+}
+function inspector() {
+    const native = getNativeBinding();
+    if (typeof native?.inspectDarwinAcl !== "function") {
+        throw new FsSafeError("helper-unavailable", "private Darwin creation requires native descriptor ACL inspection");
+    }
+    return native.inspectDarwinAcl.bind(native);
+}
+export function assertDarwinPrivateCreationAvailable() {
+    if (process.platform === "darwin")
+        inspector();
+}
+export function assertDarwinPrivateDirectoryMode(mode) {
+    if (process.platform === "darwin" && ((mode & ~process.umask()) & 0o500) === 0) {
+        throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission");
+    }
+}
+export function assertDarwinCreationAcl(fd, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    const inspect = inspector();
+    const state = inspect(fd, inheritanceTarget)?.state;
+    if (state === "present") {
+        throw new FsSafeError("insecure-permissions", inheritanceTarget
+            ? "private creation parent has inheritable Darwin ACL entries"
+            : "private creation object has Darwin ACL entries");
+    }
+    if (state !== "absent" && state !== "empty") {
+        throw new FsSafeError("helper-unavailable", "native Darwin ACL inspection returned incomplete facts");
+    }
+}
+export function assertDarwinCreationDirectoryAcl(pathname, expected, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    assertDarwinPrivateCreationAvailable();
+    let fd;
+    try {
+        fd = fs.openSync(pathname, nodeDarwinDirectoryMetadataFlags());
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const search = nodeDirectorySearchOnlyFlags();
+        if (!search)
+            throw error;
+        try {
+            fd = fs.openSync(pathname, search.flags | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        }
+        catch (cause) {
+            if (cause.code !== "EACCES")
+                throw cause;
+            throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission", { cause });
+        }
+    }
+    try {
+        const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+        if (!opened.isDirectory())
+            throw new FsSafeError("path-mismatch", "ACL target is not the admitted directory");
+        assertDarwinCreationAcl(fd, inheritanceTarget);
+        inspectDirectoryIdentitySync(pathname, expected);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function assertCreationFile(fd, pathname, expected) {
+    const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+    const named = inspectFileIdentitySync(() => fs.lstatSync(pathname, { bigint: true }), opened);
+    if (!opened.isFile() || !named.isFile() || named.isSymbolicLink() || opened.nlink !== 1n || named.nlink !== 1n) {
+        throw new FsSafeError("path-mismatch", "created file is not the expected single-linked regular file");
+    }
+    return opened;
+}
+export function assertPrivateCreationFile(stat, fd) {
+    if (process.platform === "win32")
+        return;
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "created private file must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "created private file is not owner-only");
+    }
+    assertDarwinCreationAcl(fd);
+}
+function assertRecordedFile(current, identity) {
+    if (!current.isFile() || current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity)) {
+        throw new FsSafeError("path-mismatch", "created file cleanup preserved a replacement");
+    }
+}
+export function removeRecordedCreationFileSync(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = fs.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertRecordedFile(current, identity);
+    fs.unlinkSync(pathname);
+}
+export async function removeRecordedCreationFile(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = await fsAsync.lstat(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertParent();
+    assertRecordedFile(current, identity);
+    // Recheck after the awaited observation before dispatching the unlink.
+    assertRecordedFile(fs.lstatSync(pathname, { bigint: true }), identity);
+    await fsAsync.unlink(pathname);
+}
+export function creationPublicationAfterFailure(error, recorded) {
+    if (error instanceof FsSafeError) {
+        const publication = error.details?.publication;
+        if (publication && typeof publication === "object" && "status" in publication &&
+            publication.status === "indeterminate")
+            return "indeterminate";
+    }
+    return recorded;
+}
+export function hasPreservedCreationArtifacts(error) {
+    if (!(error instanceof FsSafeError))
+        return false;
+    if (error.details?.cleanup === "preserved" || error.details?.cleanup === "failed")
+        return true;
+    const publication = error.details?.publication;
+    return publication !== null && typeof publication === "object" && "status" in publication &&
+        (publication.status === "published" || publication.status === "indeterminate");
+}
+export function rethrowPrivateStageCreationFailure(error, path, stageDirectory) {
+    if (error instanceof FsSafeError && error.code === "already-exists") {
+        throw new FsSafeError("helper-failed", "private file staging path already exists", {
+            cause: error, details: { publication: { status: "not-published" }, path, stageDirectory },
+        });
+    }
+    const publication = error instanceof FsSafeError ? error.details?.publication : undefined;
+    const created = error instanceof FsSafeError && error.details?.path === stageDirectory &&
+        publication !== null && typeof publication === "object" && "status" in publication &&
+        publication.status === "published";
+    let unconfirmed = hasUnsettledWindowsSecurityCommand(error);
+    if (error !== null && (typeof error === "object" || typeof error === "function")) {
+        try {
+            const outcome = Object.getOwnPropertyDescriptor(error, "creationOutcome");
+            unconfirmed ||= Boolean(outcome && "value" in outcome && outcome.value === "unconfirmed");
+        }
+        catch {
+            unconfirmed = true;
+        }
+    }
+    if (created || unconfirmed) {
+        throw privateFileSettlementFailure({
+            primary: error, cleanup: [], publication: "not-published", path, stageDirectory, preserved: true,
+        });
+    }
+    throw error;
+}
+export function privateFileSettlementFailure(params) {
+    return new FsSafeError("helper-failed", "file creation or staging settlement failed", {
+        cause: params.cleanup.length
+            ? new AggregateError([params.primary, ...params.cleanup], "file creation and cleanup failed")
+            : params.primary,
+        details: {
+            publication: { status: params.publication }, path: params.path, stageDirectory: params.stageDirectory,
+            cleanup: params.preserved || params.publication === "indeterminate" ? "preserved" : params.cleanup.length ? "failed" : "removed",
+        },
+    });
+}
+export function assertBeforeCreation(selected, permissions, assertion, kind) {
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private && kind === "directory")
+        assertDarwinPrivateDirectoryMode(permissions.mode);
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+}
+export function creationAdmissionFromParent(parent) {
+    const { dev, ino } = parent.stat;
+    if (typeof dev !== "bigint" || typeof ino !== "bigint") {
+        throw new FsSafeError("path-mismatch", "private creation requires an exact parent identity");
+    }
+    const identity = inspectDirectoryIdentitySync(parent.dir, { dev, ino });
+    return { expectedParentIdentity: { dev: identity.dev, ino: identity.ino, realPath: parent.realPath } };
+}
+export function prepareCreationPath(input, expectedParent) {
+    expectedParent = expectedParent && { dev: expectedParent.dev, ino: expectedParent.ino, realPath: expectedParent.realPath };
+    assertNoNulPathInput(input);
+    assertNoWindowsPathAlias(input, "filesystem");
+    if (process.platform === "win32" && input.replaceAll("/", "\\").split("\\")
+        .some(component => component.endsWith(".") || component.endsWith(" "))) {
+        throw new FsSafeError("invalid-path", "creation path contains an ambiguous Windows component");
+    }
+    const target = resolvePathPreservingWindowsRoot(input);
+    const directory = path.dirname(target);
+    if (target === directory || input.length === 0) {
+        throw new FsSafeError("invalid-path", "creation requires a child name");
+    }
+    if (expectedParent)
+        assertDirectoryIdentitySync(directory, expectedParent);
+    const stat = inspectDirectoryIdentitySync(directory);
+    const realPath = realpathSync.native(directory);
+    const parent = { dir: directory, realPath, stat };
+    const assertParent = () => {
+        assertDirectoryIdentitySync(directory, { dev: stat.dev, ino: stat.ino, realPath });
+        if (expectedParent)
+            assertDirectoryIdentitySync(directory, expectedParent);
+    };
+    assertParent();
+    return { target, parent, assertParent };
+}
+export function creationCollision(error) {
+    if (error?.code === "EEXIST") {
+        return new FsSafeError("already-exists", "creation target already exists", { cause: error });
+    }
+    return error;
+}
+/** Remove only the recorded empty stage; never traverse a replaced directory. */
+export function removeCreationDirectory(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        fs.rmdirSync(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}
+export async function removeCreationDirectoryAsync(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        await fsAsync.rmdir(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}

package/dist/directory-mode-node.js

@@ -95,7 +95,12 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
         return owner;
     }
     catch (error) {
-        await handle.close();
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
         throw error;
     }
 }
@@ -193,7 +198,12 @@ export function pinNodeDirectoryForModeSync(dirPath, options = {}) {
         };
     }
     catch (error) {
-        fsSync.closeSync(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
         throw error;
     }
 }

package/dist/durability.d.ts

@@ -1,3 +1,4 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
-export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, type PublishFileExclusiveCleanup, type PublishFileExclusiveDirectorySyncFailure, type PublishFileExclusiveFailureDetails, type PublishFileExclusiveFailurePhase, type PublishFileExclusiveSyncFailurePolicy, } from "./publish-file.js";
+export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, } from "./publish-file.js";
+export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
 export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";

package/dist/file-lock-sync-acquisition.js

@@ -10,7 +10,7 @@ export class SyncLockAcquisition {
     #admissions = getSyncLockAdmissions();
     #token = {};
     #owns = false;
-    #startedAt = Date.now();
+    #startedAt = performance.now();
     #attempt = 0;
     #transientDenials = 0;
     constructor(lockPath, normalizedTargetPath, retry, timeoutMs) {
@@ -51,7 +51,7 @@ export class SyncLockAcquisition {
     }
     waitForRetry() {
         this.release();
-        const delay = sidecarLockRetryDelay(this.retry, this.timeoutMs, Date.now() - this.#startedAt, this.#attempt);
+        const delay = sidecarLockRetryDelay(this.retry, this.timeoutMs, performance.now() - this.#startedAt, this.#attempt);
         if (delay === undefined)
             throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
         sleepSync(delay);

package/dist/file-lock-sync-root-acquire.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { captureRootSyncAcquireOptions } from "./file-lock-sync-root-options.js";
 import { defaultSyncShouldReclaim, foreignSyncHeldLock } from "./file-lock-sync-admission.js";
-import { isTransientLockFileDenial } from "./sidecar-lock-policy.js";
+import { isTransientLockFileDenial, sidecarLockStale } from "./sidecar-lock-policy.js";
 import { serializeSidecarLockPayload, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
@@ -280,11 +280,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                         }
                         releaseReclaimGuard();
                     }
-                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                        code: "file_lock_stale",
-                        lockPath,
-                        normalizedTargetPath,
-                    });
+                    throw sidecarLockStale(lockPath, normalizedTargetPath);
                 }
                 acquisition.waitForRetry();
             }

package/dist/file-lock-sync-root.d.ts

@@ -1,5 +1,6 @@
 import { type RootContext } from "./root-context.js";
-import type { Root, RootDefaults } from "./root-impl.js";
+import type { Root } from "./root-impl.js";
+import type { RootDefaults } from "./root-options.js";
 /** @internal Registers only instances constructed by RootHandle itself. */
 export declare function registerFileLockSyncRootAdapter(handle: object, context: RootContext, defaults: RootDefaults): void;
 export type FileLockSyncRootAuthority = Readonly<{

package/dist/file-lock-sync-stale-admission.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { defaultSyncShouldReclaim } from "./file-lock-sync-admission.js";
 import { parseSidecarLockSnapshot, readSidecarLockRawSnapshotSync, removeSidecarLockIfUnchangedSync, } from "./sidecar-lock-reclaim.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { sidecarLockStale } from "./sidecar-lock-policy.js";
 /** Handle one exclusive-create conflict without surrendering canonical admission. */
 export function handleSyncStaleAdmission(acquisition, params) {
     const holderChanged = {};
@@ -149,11 +150,7 @@ export function handleSyncStaleAdmission(acquisition, params) {
             throw error;
         }
         if (!approved) {
-            throw Object.assign(new Error(`file lock stale for ${acquisition.normalizedTargetPath}`), {
-                code: "file_lock_stale",
-                lockPath: acquisition.lockPath,
-                normalizedTargetPath: acquisition.normalizedTargetPath,
-            });
+            throw sidecarLockStale(acquisition.lockPath, acquisition.normalizedTargetPath);
         }
         try {
             fs.mkdirSync(params.reclaimGuardPath);
@@ -198,9 +195,5 @@ export function handleSyncStaleAdmission(acquisition, params) {
             return;
         }
     }
-    throw Object.assign(new Error(`file lock stale for ${acquisition.normalizedTargetPath}`), {
-        code: "file_lock_stale",
-        lockPath: acquisition.lockPath,
-        normalizedTargetPath: acquisition.normalizedTargetPath,
-    });
+    throw sidecarLockStale(acquisition.lockPath, acquisition.normalizedTargetPath);
 }

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

@@ -1,28 +1,11 @@
-import type { Root } from "./root-impl.js";
 import { type SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
-import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
-export type FileLockSyncAcquireOptions<TPayload extends Record<string, unknown>> = {
-    lockPath?: string;
+import type { SidecarLockCommonAcquireOptions, SidecarLockOptionFields, SidecarLockReclaimParams } from "./sidecar-lock-types.js";
+export type FileLockSyncAcquireOptions<TPayload extends Record<string, unknown>> = SidecarLockOptionFields<SidecarLockCommonAcquireOptions & {
     staleMs?: number;
-    timeoutMs?: number;
-    retry?: SidecarLockRetryOptions;
-    staleRecovery?: SidecarLockStaleRecovery;
-    reentrantOwner?: string;
     payload: () => TPayload;
-    shouldReclaim?: (params: {
-        lockPath: string;
-        normalizedTargetPath: string;
-        payload: unknown;
-        staleMs: number;
-        nowMs: number;
-        heldByThisProcess: false;
-    }) => boolean;
+    shouldReclaim?: (params: SidecarLockReclaimParams<false>) => boolean;
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean;
-    parsePayload?: (raw: string) => unknown;
-    lockRoot?: Root;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
-    compromiseCheckIntervalMs?: number;
-};
+}>;
 export type FileLockSyncHandle = {
     lockPath: string;
     normalizedTargetPath: string;

package/dist/file-store-boundary.d.ts

@@ -29,3 +29,10 @@ export declare function ensureStoreDirectorySync(params: {
     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/dist/file-store-boundary.js

@@ -5,13 +5,15 @@ 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 } from "./path.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);
@@ -118,3 +120,58 @@ export function ensureStoreDirectorySync(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;
+    }
+}

package/dist/file-store-sync-write.js

@@ -10,6 +10,7 @@ import { isPathInside } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { writeTempFileSync } from "./replace-file-descriptor.js";
 import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function verifyStoreFile(fd, expected, filePath) {
@@ -108,9 +109,7 @@ export function writeFileSyncAtomic(params) {
             if (error instanceof FsSafeError) {
                 throw error;
             }
-            throw new FsSafeError("path-mismatch", "store target changed after write", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("path-mismatch", "store target changed after write", errorCauseOptions(error));
         }
         assertSyncStoreDirectoryReceipt(parentGuard);
         if (params.durable) {

package/dist/file-store.js

@@ -1,13 +1,9 @@
 import syncFs from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
-import { assertFileStoreMaxBytes } from "./file-store-limit.js";
-import { assertRelativePath, resolveStorePath } from "./file-store-path.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
-import { ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -18,7 +14,6 @@ import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
 import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
-import { readFileStoreCopySource } from "./file-store-copy-source.js";
 function snapshotWriteOptions(options, durabilityFirst = true) {
     if (options == null)
         return undefined;

package/dist/guarded-mkdir.d.ts

@@ -1,6 +1,6 @@
 import { type RootBoundaryIdentity } from "./root-boundary.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
-import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write.js";
+import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write-types.js";
 /**
  * Creates each missing path component from `rootReal` down to `targetPath`,
  * guarding every step. Returns the real (symlink-resolved) path of the final