@openclaw/fs-safe 0.17.0 → 0.18.1

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

@@ -1,27 +1,26 @@
 import fs from "node:fs";
-import { defaultSyncShouldReclaim, syncLockTimeout } from "./file-lock-sync-admission.js";
+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(params) {
+export function handleSyncStaleAdmission(acquisition, params) {
     const holderChanged = {};
     const assertUnheld = () => {
-        if (!params.hasToken()) {
-            throw syncLockTimeout(params.lockPath, params.normalizedTargetPath);
-        }
+        acquisition.assert();
         if (params.currentHeld())
             throw holderChanged;
     };
     const retryHolderChange = (error) => {
         if (error !== holderChanged)
             return false;
-        params.waitForRetry();
+        acquisition.waitForRetry();
         return true;
     };
     let rawSnapshot;
     let lockFileOpenDenied = false;
     try {
-        rawSnapshot = readSidecarLockRawSnapshotSync(params.lockPath, {
+        rawSnapshot = readSidecarLockRawSnapshotSync(acquisition.lockPath, {
             rejectNonFile: true,
             onOpenFailure: (error) => {
                 lockFileOpenDenied = true;
@@ -41,7 +40,7 @@ export function handleSyncStaleAdmission(params) {
                 return;
             throw boundaryError;
         }
-        if (lockFileOpenDenied && params.retryLockFileDenial(error))
+        if (lockFileOpenDenied && acquisition.retryDenial(error))
             return;
         throw error;
     }
@@ -93,7 +92,7 @@ export function handleSyncStaleAdmission(params) {
         throw error;
     }
     if (!snapshot) {
-        params.waitForRetry();
+        acquisition.waitForRetry();
         return;
     }
     const nowMs = Date.now();
@@ -103,8 +102,8 @@ export function handleSyncStaleAdmission(params) {
         try {
             reclaim = stale.shouldReclaim
                 ? Reflect.apply(stale.shouldReclaim, params.options, [{
-                        lockPath: params.lockPath,
-                        normalizedTargetPath: params.normalizedTargetPath,
+                        lockPath: acquisition.lockPath,
+                        normalizedTargetPath: acquisition.normalizedTargetPath,
                         payload: snapshot.payload,
                         staleMs: params.staleMs,
                         nowMs,
@@ -123,7 +122,7 @@ export function handleSyncStaleAdmission(params) {
         throw error;
     }
     if (!reclaim) {
-        params.waitForRetry();
+        acquisition.waitForRetry();
         return;
     }
     if (params.staleRecovery === "remove-if-unchanged" &&
@@ -134,8 +133,8 @@ export function handleSyncStaleAdmission(params) {
             assertUnheld();
             try {
                 approved = Reflect.apply(stale.shouldRemove, params.options, [{
-                        lockPath: params.lockPath,
-                        normalizedTargetPath: params.normalizedTargetPath,
+                        lockPath: acquisition.lockPath,
+                        normalizedTargetPath: acquisition.normalizedTargetPath,
                         raw: snapshot.raw,
                         payload: snapshot.payload,
                     }]);
@@ -151,11 +150,7 @@ export function handleSyncStaleAdmission(params) {
             throw error;
         }
         if (!approved) {
-            throw Object.assign(new Error(`file lock stale for ${params.normalizedTargetPath}`), {
-                code: "file_lock_stale",
-                lockPath: params.lockPath,
-                normalizedTargetPath: params.normalizedTargetPath,
-            });
+            throw sidecarLockStale(acquisition.lockPath, acquisition.normalizedTargetPath);
         }
         try {
             fs.mkdirSync(params.reclaimGuardPath);
@@ -170,7 +165,7 @@ export function handleSyncStaleAdmission(params) {
                 throw boundaryError;
             }
             if (error.code === "EEXIST") {
-                params.waitForRetry();
+                acquisition.waitForRetry();
                 return;
             }
             throw error;
@@ -178,7 +173,7 @@ export function handleSyncStaleAdmission(params) {
         let holderInterrupted = false;
         try {
             assertUnheld();
-            if (removeSidecarLockIfUnchangedSync(params.lockPath, snapshot, assertUnheld))
+            if (removeSidecarLockIfUnchangedSync(acquisition.lockPath, snapshot, assertUnheld))
                 return;
         }
         catch (error) {
@@ -196,13 +191,9 @@ export function handleSyncStaleAdmission(params) {
             }
         }
         if (holderInterrupted) {
-            params.waitForRetry();
+            acquisition.waitForRetry();
             return;
         }
     }
-    throw Object.assign(new Error(`file lock stale for ${params.normalizedTargetPath}`), {
-        code: "file_lock_stale",
-        lockPath: params.lockPath,
-        normalizedTargetPath: params.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;
@@ -32,4 +15,3 @@ export type FileLockSyncHandle = {
 };
 export declare function acquireFileLockSync<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>): FileLockSyncHandle;
 export declare function withFileLockSync<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockSyncAcquireOptions<TPayload>, fn: () => T): T;
-//# sourceMappingURL=file-lock-sync.d.ts.map

package/dist/file-lock-sync.js

@@ -3,14 +3,14 @@ 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 { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { sidecarLockTimeout, isTransientLockFileDenial, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
-import { sleepSync } from "./timing.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, syncLockTimeout, } from "./file-lock-sync-admission.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();
@@ -135,15 +135,7 @@ export function acquireFileLockSync(targetPath, options) {
         initiallyHeld.refCount += 1;
         return createSyncHeldLockHandle(initiallyHeld);
     }
-    const admissions = getSyncLockAdmissions();
-    const admissionToken = {};
-    let ownsAdmission = false;
-    const hasAdmissionToken = () => admissions.get(normalizedTargetPath) === admissionToken;
-    const releaseAdmission = () => {
-        if (ownsAdmission && hasAdmissionToken())
-            admissions.delete(normalizedTargetPath);
-        ownsAdmission = false;
-    };
+    const acquisition = new SyncLockAcquisition(lockPath, normalizedTargetPath, retry, timeoutMs);
     let payloadCallback;
     let onCompromised = undefined;
     let onCompromisedObserved = false;
@@ -152,54 +144,10 @@ export function acquireFileLockSync(targetPath, options) {
     let staleRecovery = undefined;
     let staleRecoveryObserved = false;
     const staleOptions = {};
-    const startedAt = Date.now();
-    let attempt = 0;
-    let transientDenials = 0;
     const reclaimGuardPath = `${lockPath}.reclaim`;
-    const waitForRetry = () => {
-        releaseAdmission();
-        const elapsed = Date.now() - startedAt;
-        const timedOut = timeoutMs !== undefined && elapsed >= timeoutMs;
-        if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
-            throw syncLockTimeout(lockPath, normalizedTargetPath);
-        }
-        const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, timeoutMs - elapsed);
-        sleepSync(Math.min(computeSidecarLockDelayMs(retry, attempt), remaining));
-        attempt += 1;
-    };
-    const retryLockFileDenial = (error) => {
-        if (!isTransientLockFileDenial(error, lockPath) ||
-            ++transientDenials > maxTransientLockDenials)
-            return false;
-        try {
-            waitForRetry();
-        }
-        catch (waitError) {
-            // Preserve the filesystem diagnosis when the caller's budget runs out.
-            if (waitError.code === "file_lock_timeout")
-                throw error;
-            throw waitError;
-        }
-        return true;
-    };
-    const assertAdmissionToken = () => {
-        if (!hasAdmissionToken())
-            throw syncLockTimeout(lockPath, normalizedTargetPath);
-    };
-    const runAdmissionBoundary = (callback) => {
-        assertAdmissionToken();
-        try {
-            return callback();
-        }
-        finally {
-            assertAdmissionToken();
-        }
-    };
     try {
         while (true) {
-            if (!ownsAdmission) {
+            if (!acquisition.owns) {
                 const held = heldLocks.get(normalizedTargetPath);
                 if (held && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
                     requestedReentrantOwner !== undefined &&
@@ -208,12 +156,7 @@ export function acquireFileLockSync(targetPath, options) {
                     held.refCount += 1;
                     return createSyncHeldLockHandle(held);
                 }
-                if (admissions.has(normalizedTargetPath)) {
-                    // The owner can only finish after this synchronous callback unwinds.
-                    throw syncLockTimeout(lockPath, normalizedTargetPath);
-                }
-                admissions.set(normalizedTargetPath, admissionToken);
-                ownsAdmission = true;
+                acquisition.reserve();
             }
             const attemptHeld = currentTargetHolder();
             const holderWasReplaced = () => {
@@ -221,60 +164,60 @@ export function acquireFileLockSync(targetPath, options) {
                 return current !== undefined && current !== attemptHeld;
             };
             if (!staleRecoveryObserved) {
-                staleRecovery = runAdmissionBoundary(() => options.staleRecovery ?? defaults.staleRecovery);
+                staleRecovery = acquisition.run(() => options.staleRecovery ?? defaults.staleRecovery);
                 staleRecoveryObserved = true;
                 if (holderWasReplaced()) {
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
             }
             const reclaimGuardExists = syncReclaimGuardExists(reclaimGuardPath);
-            if (!hasAdmissionToken())
-                throw syncLockTimeout(lockPath, normalizedTargetPath);
+            if (!acquisition.hasToken())
+                throw sidecarLockTimeout(lockPath, normalizedTargetPath);
             if (holderWasReplaced()) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
             if (reclaimGuardExists) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
             let fd;
             let createdHeld;
             let createdSnapshot;
             if (!payloadCallback)
-                payloadCallback = runAdmissionBoundary(() => options.payload);
+                payloadCallback = acquisition.run(() => options.payload);
             if (holderWasReplaced()) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
-            const payload = runAdmissionBoundary(() => Reflect.apply(payloadCallback, options, []));
+            const payload = acquisition.run(() => Reflect.apply(payloadCallback, options, []));
             if (holderWasReplaced()) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
-            const { raw, ownershipToken } = runAdmissionBoundary(() => serializeSidecarLockPayload(payload));
+            const { raw, ownershipToken } = acquisition.run(() => serializeSidecarLockPayload(payload));
             if (holderWasReplaced()) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
             if (currentTargetHolder() !== undefined) {
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
             if (!onCompromisedObserved) {
-                onCompromised = runAdmissionBoundary(() => options.onCompromised);
+                onCompromised = acquisition.run(() => options.onCompromised);
                 onCompromisedObserved = true;
                 if (currentTargetHolder() !== undefined) {
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
             }
             if (!parsePayloadObserved) {
-                parsePayload = runAdmissionBoundary(() => options.parsePayload);
+                parsePayload = acquisition.run(() => options.parsePayload);
                 parsePayloadObserved = true;
                 if (currentTargetHolder() !== undefined) {
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
             }
@@ -311,34 +254,17 @@ export function acquireFileLockSync(targetPath, options) {
                 };
                 const candidateHeld = createdHeld;
                 ensureSyncLockExitCleanupRegistered(releaseAllSyncHeldLocks, lockPath, normalizedTargetPath);
-                if (!hasAdmissionToken() || currentTargetHolder() !== undefined) {
-                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                if (!acquisition.hasToken() || currentTargetHolder() !== undefined) {
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
                 }
                 const returnedHandle = createSyncHeldLockHandle(candidateHeld);
-                if (onCompromised && (compromiseCheckIntervalMs ?? 0) > 0) {
-                    const compromisedCallback = onCompromised;
-                    candidateHeld.timer = setInterval(() => {
-                        let stillHeld;
-                        try {
-                            stillHeld = returnedHandle.verifyStillHeld();
-                        }
-                        catch {
-                            stillHeld = false;
-                        }
-                        if (!stillHeld && candidateHeld.timer) {
-                            clearInterval(candidateHeld.timer);
-                            candidateHeld.timer = undefined;
-                            Reflect.apply(compromisedCallback, options, [{ lockPath, normalizedTargetPath }]);
-                        }
-                    }, compromiseCheckIntervalMs);
-                    candidateHeld.timer.unref();
-                }
-                if (!hasAdmissionToken() ||
+                acquisition.monitor(candidateHeld, returnedHandle, onCompromised, compromiseCheckIntervalMs, options);
+                if (!acquisition.hasToken() ||
                     currentTargetHolder() !== undefined) {
-                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
                 }
                 heldLocks.set(normalizedTargetPath, candidateHeld);
-                releaseAdmission();
+                acquisition.release();
                 fd = undefined;
                 return returnedHandle;
             }
@@ -374,44 +300,39 @@ export function acquireFileLockSync(targetPath, options) {
                     }
                 }
                 if (lockFileCreateDenied) {
-                    if (!hasAdmissionToken())
-                        throw syncLockTimeout(lockPath, normalizedTargetPath);
+                    if (!acquisition.hasToken())
+                        throw sidecarLockTimeout(lockPath, normalizedTargetPath);
                     if (currentTargetHolder() !== undefined) {
-                        waitForRetry();
+                        acquisition.waitForRetry();
                         continue;
                     }
-                    if (retryLockFileDenial(error))
+                    if (acquisition.retryDenial(error))
                         continue;
                     throw error;
                 }
                 if (!exclusiveCreateConflict)
                     throw error;
-                if (!hasAdmissionToken())
-                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                if (!acquisition.hasToken())
+                    throw sidecarLockTimeout(lockPath, normalizedTargetPath);
                 if (currentTargetHolder() !== undefined) {
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
-                handleSyncStaleAdmission({
-                    hasToken: hasAdmissionToken,
+                handleSyncStaleAdmission(acquisition, {
                     currentHeld: currentTargetHolder,
-                    lockPath,
-                    normalizedTargetPath,
                     options,
                     parsePayload,
                     reclaimGuardPath,
-                    retryLockFileDenial,
                     staleMs,
                     staleOptions,
                     staleRecovery,
-                    waitForRetry,
                 });
                 continue;
             }
         }
     }
     finally {
-        releaseAdmission();
+        acquisition.release();
     }
 }
 export function withFileLockSync(targetPath, options, fn) {

package/dist/file-lock.d.ts

@@ -21,4 +21,3 @@ export declare function withFileLock<T, TPayload extends Record<string, unknown>
 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;
-//# sourceMappingURL=file-lock.d.ts.map

package/dist/file-observation.d.ts

@@ -6,4 +6,3 @@ export declare function fileObservation(): {
     has(error: unknown, kind: FailureKind): boolean;
 };
 export {};
-//# sourceMappingURL=file-observation.d.ts.map

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

@@ -18,7 +18,6 @@ export declare function writeStreamToTempSource(params: {
     path: string;
     cleanup: () => Promise<void>;
 }>;
-export declare function assertSyncDirectoryGuard(guard: SyncParentGuard): void;
 export declare function ensureParentSync(params: {
     rootDir: string;
     filePath: string;
@@ -30,4 +29,10 @@ export declare function ensureStoreDirectorySync(params: {
     mode: number;
     messagePrefix: "private store" | "store";
 }): SyncParentGuard;
-//# sourceMappingURL=file-store-boundary.d.ts.map
+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

@@ -2,25 +2,22 @@ import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createByteLimitTransform } from "./bounded-read-stream.js";
-import { normalizeMaxBytes } from "./byte-budget.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";
-function parentRelativePath(relativePath) {
-    const parent = path.posix.dirname(relativePath);
-    return parent === "." ? "" : parent;
-}
 export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
-    const parent = parentRelativePath(relativePath);
-    if (!parent) {
+    const parent = path.posix.dirname(relativePath);
+    if (parent === ".") {
         return;
     }
     await scopedRoot.mkdir(parent);
@@ -28,10 +25,9 @@ export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
 }
 export async function openWritableStoreRoot(params) {
     assertNoWindowsPathAlias(params.rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
-    const maxBytes = normalizeMaxBytes(params.maxBytes);
     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 });
+    return await root(params.rootDir, { hardlinks: "reject", maxBytes: params.maxBytes });
 }
 export async function openPrivateStoreLockRoot(params) {
     const { parentGuard } = await prepareSecretFileWrite(params);
@@ -66,15 +62,8 @@ async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
         await handle.close().catch(() => undefined);
     }
 }
-function createMaxBytesTransform(maxBytes) {
-    const limit = normalizeMaxBytes(maxBytes);
-    if (limit === undefined) {
-        return undefined;
-    }
-    return createByteLimitTransform(limit, () => new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`));
-}
 export async function writeStreamToTempSource(params) {
-    const maxBytes = normalizeMaxBytes(params.maxBytes);
+    const maxBytes = params.maxBytes;
     const tempRoot = resolveSecureTempRoot({
         fallbackPrefix: "fs-safe-file-store",
         unsafeFallbackLabel: "file store temp dir",
@@ -90,7 +79,7 @@ export async function writeStreamToTempSource(params) {
         writable.once("close", () => {
             handleClosedByStream = true;
         });
-        const limiter = createMaxBytesTransform(maxBytes);
+        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);
         }
@@ -116,13 +105,6 @@ export async function writeStreamToTempSource(params) {
         throw err;
     }
 }
-export function assertSyncDirectoryGuard(guard) {
-    assertSyncStoreDirectoryReceipt({
-        dir: guard.dir,
-        realPath: guard.realPath,
-        exactStat: guard.exactStat,
-    });
-}
 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");
@@ -135,6 +117,61 @@ export function ensureParentSync(params) {
 }
 export function ensureStoreDirectorySync(params) {
     const guard = ensureSyncStoreDirectory(params);
-    assertSyncDirectoryGuard(guard);
+    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-prune.d.ts

@@ -9,4 +9,3 @@ export declare function pruneExpiredStoreEntries(params: {
     dirMode: number;
     options: FileStorePruneOptions;
 }): Promise<void>;
-//# sourceMappingURL=file-store-prune.d.ts.map

package/dist/file-store-sync-directory.d.ts

@@ -13,4 +13,3 @@ export declare function ensureSyncStoreDirectory(params: {
 }): SyncStoreDirectoryReceipt;
 export declare function assertSyncStoreDirectoryReceipt(receipt: SyncStoreDirectoryReceipt): void;
 export {};
-//# sourceMappingURL=file-store-sync-directory.d.ts.map