@jini-ai/platform 0.5.9 → 0.5.10

package/dist/fs/file-lock.js

@@ -10,7 +10,7 @@
  * multi-process races and are deliberately avoided. Atomic file replacement independently prevents
  * torn content. Hosts whose operations can legitimately exceed the stale budget use staleMs: Infinity.
  */
-import { readBootIdentity } from "./boot-identity.js";
+import { fromEarlierBoot, readBootIdentity } from "./boot-identity.js";
 import fs from "node:fs";
 import * as asyncFs from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -47,13 +47,25 @@ export function isContendedLockError({ code, platform }) {
 function errorCode(error) {
     return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
 }
+function isAbsentOrContended(error) {
+    const code = errorCode(error);
+    return code === "ENOENT" || isContendedLockError({ code, platform: process.platform });
+}
+function rethrowUnlessMissing(error) { if (errorCode(error) !== "ENOENT")
+    throw error; }
 function validPid(pid) { return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0; }
+function isHolderRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const row = value;
+    return validPid(row.pid) && typeof row.hostname === "string" && typeof row.token === "string" && typeof row.acquiredAt === "string";
+}
 function parseHolder(raw) {
     try {
         const value = JSON.parse(raw);
-        if (typeof value !== "object" || value === null || !("pid" in value) || !validPid(value.pid) || !("hostname" in value) || typeof value.hostname !== "string" || !("token" in value) || typeof value.token !== "string" || !("acquiredAt" in value) || typeof value.acquiredAt !== "string")
+        if (!isHolderRecord(value))
             return undefined;
-        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt, ...("bootId" in value && typeof value.bootId === "string" ? { bootId: value.bootId } : {}) };
+        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt, ...(typeof value.bootId === "string" ? { bootId: value.bootId } : {}) };
     }
     catch {
         return undefined;
@@ -64,60 +76,86 @@ function parseHolder(raw) {
 export function isLockStale(required) {
     return (required.ownerAlive === false || required.nowMs - required.mtimeMs > required.staleMs) && required.observedInode === required.currentInode && required.observedDevice === required.currentDevice;
 }
-function settings(options) {
+function intervalsValid({ timeoutMs, staleMs, pollMs }) {
+    return Number.isSafeInteger(timeoutMs) && timeoutMs >= 0 && (Number.isSafeInteger(staleMs) || staleMs === Infinity) && staleMs > 0 && Number.isSafeInteger(pollMs) && pollMs > 0;
+}
+function intervals(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_AFTER_MS, pollMs = options.pollMs ?? 10;
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || (!Number.isSafeInteger(staleMs) && staleMs !== Infinity) || staleMs <= 0 || !Number.isSafeInteger(pollMs) || pollMs <= 0)
+    if (!intervalsValid({ timeoutMs, staleMs, pollMs }))
         throw new RangeError((options.messages ?? defaultPlatformMessages).fileLockIntervalsInvalid());
-    const processPort = options.process ?? { pid: process.pid, bootIdentity: () => readBootIdentity({}), isAlive: ({ pid }) => { try {
+    return { timeoutMs, staleMs, pollMs };
+}
+function defaultProcessPort() {
+    return { pid: process.pid, bootIdentity: () => readBootIdentity({}), isAlive: ({ pid }) => { try {
             process.kill(pid, 0);
             return true;
         }
         catch (error) {
             return errorCode(error) !== "ESRCH";
         } } };
+}
+function settings(options) {
+    const checked = intervals(options);
+    const processPort = options.process ?? defaultProcessPort();
     const clock = options.clock ?? createSystemClock();
     const monotonicMs = options.monotonicMs ?? (() => clock.nowMs());
-    return { timeoutMs, staleMs, pollMs, processPort, clock, monotonicMs, boot: processPort.bootIdentity?.(), hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
+    return { ...checked, processPort, clock, monotonicMs, boot: processPort.bootIdentity?.(), hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
 }
 function ownership(s, options) {
     return options.format === "token" ? `${s.processPort.pid}:${s.token}${s.boot ? ":" + s.boot.id : ""}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString(), ...(s.boot ? { bootId: s.boot.id } : {}) });
 }
-function ownerAlive(snapshot, s) {
-    const holder = snapshot.holder;
-    if (holder) {
-        if (holder.hostname !== s.hostname)
-            return undefined;
-        if (s.boot && (holder.bootId !== undefined ? holder.bootId !== s.boot.id : Date.parse(holder.acquiredAt) < s.boot.startedAtMs))
-            return false;
-        return s.processPort.isAlive({ pid: holder.pid });
-    }
-    // Legacy synchronous stores wrote pid:random rather than JSON. Malformed pids remain unknown.
+function holderAlive(holder, s) {
+    if (holder.hostname !== s.hostname)
+        return undefined;
+    // A recorded boot id decides; without one, only an acquisition before this boot proves a restart.
+    if (fromEarlierBoot({ boot: s.boot, bootId: holder.bootId, atMs: Date.parse(holder.acquiredAt) }))
+        return false;
+    return s.processPort.isAlive({ pid: holder.pid });
+}
+// Legacy synchronous stores wrote pid:random rather than JSON. Malformed pids remain unknown.
+function legacyOwnerAlive(snapshot, s) {
     if (!/^\d+:/.test(snapshot.raw))
         return undefined;
     const parts = snapshot.raw.split(":");
     const pid = Number(parts[0]);
-    if (validPid(pid) && s.boot && (parts[2] ? parts[2] !== s.boot.id : snapshot.mtimeMs < s.boot.startedAtMs))
+    if (!validPid(pid))
+        return undefined;
+    if (fromEarlierBoot({ boot: s.boot, bootId: parts[2] || undefined, atMs: snapshot.mtimeMs }))
         return false;
-    return validPid(pid) ? s.processPort.isAlive({ pid }) : undefined;
+    return s.processPort.isAlive({ pid });
+}
+function ownerAlive(snapshot, s) {
+    return snapshot.holder ? holderAlive(snapshot.holder, s) : legacyOwnerAlive(snapshot, s);
 }
-function unchanged(a, b) { return a.ino === b.ino && a.dev === b.dev && a.raw === b.raw && a.mtimeMs === b.mtimeMs; }
+function sameFile(a, b) { return a.ino === b.ino && a.dev === b.dev; }
+function sameStat(a, b) { return sameFile(a, b) && a.mtimeMs === b.mtimeMs; }
+function unchanged(a, b) { return sameStat(a, b) && a.raw === b.raw; }
 function stale(observed, current, s) {
     return unchanged(observed, current) && isLockStale({ nowMs: s.clock.nowMs(), mtimeMs: observed.mtimeMs, staleMs: s.staleMs, ownerAlive: ownerAlive(current, s), observedInode: observed.ino, currentInode: current.ino, observedDevice: observed.dev, currentDevice: current.dev });
 }
+function messagesOption(options) { return options.messages ? { messages: options.messages } : {}; }
 function checkTimeout(lockPath, holder, start, s, options) {
     const waitedMs = s.monotonicMs() - start;
     if (waitedMs >= s.timeoutMs) {
         const message = options.timeoutMessage?.({ lockPath, waitMs: s.timeoutMs });
-        throw new FileLockTimeoutError({ lockPath, holder, waitedMs }, { ...(options.messages ? { messages: options.messages } : {}), ...(message !== undefined ? { message } : {}) });
+        throw new FileLockTimeoutError({ lockPath, holder, waitedMs }, { ...messagesOption(options), ...(message !== undefined ? { message } : {}) });
     }
 }
+function ownsSnapshot(current, raw, identity) {
+    return current !== undefined && current.raw === raw && sameFile(current, identity);
+}
+// A failed critical section keeps its original error; durable hosts also suppress release-only failures.
+function rethrowReleaseError(error, completed, options) {
+    if (completed && !options.suppressReleaseErrors)
+        rethrowUnlessMissing(error);
+}
 function inspectSync(lockPath, filesystem) {
     let descriptor;
     try {
         descriptor = filesystem.openSync(lockPath, "r");
     }
     catch (error) {
-        if (errorCode(error) === "ENOENT" || isContendedLockError({ code: errorCode(error), platform: process.platform }))
+        if (isAbsentOrContended(error))
             return undefined;
         throw error;
     }
@@ -135,7 +173,7 @@ async function inspectAsync(lockPath, filesystem) {
         handle = await filesystem.open(lockPath, "r");
     }
     catch (error) {
-        if (errorCode(error) === "ENOENT" || isContendedLockError({ code: errorCode(error), platform: process.platform }))
+        if (isAbsentOrContended(error))
             return undefined;
         throw error;
     }
@@ -147,77 +185,82 @@ async function inspectAsync(lockPath, filesystem) {
         await handle.close();
     }
 }
-const waitCell = new Int32Array(new SharedArrayBuffer(4));
-/** Synchronous read-modify-write guard. Durable stores pass their former 5s/30s/10ms values.
- * Release never evicts a later owner, even when the old owner reaches finally after a steal. */
-export function withFileLockSync({ lockPath, run }, options = {}) {
-    const filesystem = options.filesystem ?? fs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
-    if (options.createParent)
-        filesystem.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+function writeOwnershipSync({ raw, filesystem, options }, descriptor) {
+    const bytes = Buffer.from(raw);
+    let offset = 0;
+    while (offset < bytes.length) {
+        const written = filesystem.writeSync(descriptor, bytes, offset, bytes.length - offset);
+        if (written === 0)
+            throw new Error((options.messages ?? defaultPlatformMessages).fileLockWriteNoProgress());
+        offset += written;
+    }
+}
+/** Exclusive create; undefined means another owner holds the path. */
+function tryCreateSync(ctx) {
+    const { lockPath, filesystem } = ctx;
+    let descriptor;
+    try {
+        descriptor = filesystem.openSync(lockPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
+            throw error;
+        return undefined;
+    }
     let identity;
-    for (;;) {
-        let descriptor;
+    try {
+        identity = filesystem.fstatSync(descriptor);
+        // An unidentifiable lock would wedge writers until stale timeout; clean a failed creation
+        // only while its inode still matches, rather than deleting a replacement owner.
+        writeOwnershipSync(ctx, descriptor);
+    }
+    catch (error) {
         try {
-            descriptor = filesystem.openSync(lockPath, "wx", 0o600);
-        }
-        catch (error) {
-            if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
-                throw error;
-        }
-        if (descriptor !== undefined) {
-            try {
-                identity = filesystem.fstatSync(descriptor);
-                // An unidentifiable lock would wedge writers until stale timeout; clean a failed creation
-                // only while its inode still matches, rather than deleting a replacement owner.
-                const bytes = Buffer.from(raw);
-                let offset = 0;
-                while (offset < bytes.length) {
-                    const written = filesystem.writeSync(descriptor, bytes, offset, bytes.length - offset);
-                    if (written === 0)
-                        throw new Error((options.messages ?? defaultPlatformMessages).fileLockWriteNoProgress());
-                    offset += written;
-                }
-            }
-            catch (error) {
-                try {
-                    const created = filesystem.fstatSync(descriptor), current = filesystem.statSync(lockPath);
-                    if (created.ino === current.ino && created.dev === current.dev)
-                        filesystem.rmSync(lockPath, { force: true });
-                }
-                catch { /* preserve creation failure */ }
-                throw error;
-            }
-            finally {
-                filesystem.closeSync(descriptor);
-            }
-            break;
-        }
-        const observed = inspectSync(lockPath, filesystem);
-        if (observed) {
-            const current = inspectSync(lockPath, filesystem);
-            if (current && stale(observed, current, s)) {
-                const last = filesystem.statSync(lockPath, { throwIfNoEntry: false });
-                if (last && last.ino === current.ino && last.dev === current.dev && last.mtimeMs === current.mtimeMs) {
-                    try {
-                        filesystem.rmSync(lockPath, { force: true });
-                        options.onStaleLockRemoved?.({ holder: current.holder });
-                    }
-                    catch (error) {
-                        if (errorCode(error) !== "ENOENT")
-                            throw error;
-                    }
-                }
-            }
+            if (sameFile(filesystem.fstatSync(descriptor), filesystem.statSync(lockPath)))
+                filesystem.rmSync(lockPath, { force: true });
         }
+        catch { /* preserve creation failure */ }
+        throw error;
+    }
+    finally {
+        filesystem.closeSync(descriptor);
+    }
+    return identity;
+}
+function removeIfStaleSync(observed, { lockPath, filesystem, s, options }) {
+    const current = inspectSync(lockPath, filesystem);
+    if (!current || !stale(observed, current, s))
+        return;
+    const last = filesystem.statSync(lockPath, { throwIfNoEntry: false });
+    if (!last || !sameStat(last, current))
+        return;
+    try {
+        filesystem.rmSync(lockPath, { force: true });
+        options.onStaleLockRemoved?.({ holder: current.holder });
+    }
+    catch (error) {
+        rethrowUnlessMissing(error);
+    }
+}
+function acquireSync(ctx, start, sleep) {
+    for (;;) {
+        const identity = tryCreateSync(ctx);
+        if (identity)
+            return identity;
+        const observed = inspectSync(ctx.lockPath, ctx.filesystem);
+        if (observed)
+            removeIfStaleSync(observed, ctx);
         // Every contention path, including repeated stale breaks and release races, is bounded.
-        checkTimeout(lockPath, observed?.holder, start, s, options);
-        (options.sleep ?? (({ durationMs }) => { Atomics.wait(waitCell, 0, 0, durationMs); }))({ durationMs: s.pollMs });
+        checkTimeout(ctx.lockPath, observed?.holder, start, ctx.s, ctx.options);
+        sleep({ durationMs: ctx.s.pollMs });
     }
-    const held = () => { const current = inspectSync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+}
+function runHeldSync({ lockPath, raw, filesystem, options }, identity, run) {
+    const held = () => ownsSnapshot(inspectSync(lockPath, filesystem), raw, identity);
     let completed = false;
     try {
         const value = run({ lockPath, assertHeld: (_required) => { if (!held())
-                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+                throw new FileLockLostError({ lockPath }, messagesOption(options)); } });
         completed = true;
         return value;
     }
@@ -226,77 +269,92 @@ export function withFileLockSync({ lockPath, run }, options = {}) {
             if (held())
                 filesystem.rmSync(lockPath, { force: true });
         }
-        // A failed critical section keeps its original error; durable hosts also suppress release-only failures.
         catch (error) {
-            if (completed && !options.suppressReleaseErrors && errorCode(error) !== "ENOENT")
-                throw error;
+            rethrowReleaseError(error, completed, options);
         }
     }
 }
-/** Async adapter of the same stale and ownership policy; polling yields to other writers. */
-export async function withFileLock({ lockPath, run }, options = {}) {
-    const filesystem = options.filesystem ?? asyncFs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
+const waitCell = new Int32Array(new SharedArrayBuffer(4));
+/** Synchronous read-modify-write guard. Durable stores pass their former 5s/30s/10ms values.
+ * Release never evicts a later owner, even when the old owner reaches finally after a steal. */
+export function withFileLockSync({ lockPath, run }, options = {}) {
+    const filesystem = options.filesystem ?? fs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
     if (options.createParent)
-        await filesystem.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+        filesystem.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    const ctx = { lockPath, raw, filesystem, s, options };
+    const identity = acquireSync(ctx, start, options.sleep ?? (({ durationMs }) => { Atomics.wait(waitCell, 0, 0, durationMs); }));
+    return runHeldSync(ctx, identity, run);
+}
+async function removeFailedCreationAsync({ lockPath, filesystem }, handle) {
+    try {
+        const created = await handle.stat(), current = await inspectAsync(lockPath, filesystem);
+        if (current && sameFile(created, current))
+            await filesystem.rm(lockPath, { force: true });
+    }
+    catch { /* preserve creation failure */ }
+}
+/** Exclusive create; undefined means another owner holds the path. */
+async function tryCreateAsync(ctx) {
+    let handle;
+    try {
+        handle = await ctx.filesystem.open(ctx.lockPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
+            throw error;
+        return undefined;
+    }
     let identity;
+    try {
+        identity = await handle.stat();
+        await handle.writeFile(ctx.raw, "utf8");
+    }
+    catch (error) {
+        await removeFailedCreationAsync(ctx, handle);
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+    return identity;
+}
+async function removeIfStaleAsync(observed, { lockPath, filesystem, s, options }) {
+    const current = await inspectAsync(lockPath, filesystem);
+    if (!current || !stale(observed, current, s))
+        return;
+    const last = await inspectAsync(lockPath, filesystem);
+    if (!last || !unchanged(current, last))
+        return;
+    // Reading a descriptor pins an inode, not the pathname. Re-stat the pathname after the
+    // final descriptor closes, so replacement during awaited inspection cannot be stolen.
+    try {
+        if (!sameStat(await filesystem.stat(lockPath), last))
+            return;
+        await filesystem.rm(lockPath, { force: true });
+        options.onStaleLockRemoved?.({ holder: current.holder });
+    }
+    catch (error) {
+        rethrowUnlessMissing(error);
+    }
+}
+async function acquireAsync(ctx, start, sleep) {
     for (;;) {
-        let handle;
-        try {
-            handle = await filesystem.open(lockPath, "wx", 0o600);
-        }
-        catch (error) {
-            if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
-                throw error;
-        }
-        if (handle) {
-            try {
-                identity = await handle.stat();
-                await handle.writeFile(raw, "utf8");
-            }
-            catch (error) {
-                try {
-                    const created = await handle.stat(), current = await inspectAsync(lockPath, filesystem);
-                    if (current && created.ino === current.ino && created.dev === current.dev)
-                        await filesystem.rm(lockPath, { force: true });
-                }
-                catch { /* preserve creation failure */ }
-                throw error;
-            }
-            finally {
-                await handle.close();
-            }
-            break;
-        }
-        const observed = await inspectAsync(lockPath, filesystem);
-        if (observed) {
-            const current = await inspectAsync(lockPath, filesystem);
-            if (current && stale(observed, current, s)) {
-                const last = await inspectAsync(lockPath, filesystem);
-                if (last && unchanged(current, last)) {
-                    // Reading a descriptor pins an inode, not the pathname. Re-stat the pathname after the
-                    // final descriptor closes, so replacement during awaited inspection cannot be stolen.
-                    try {
-                        const atPath = await filesystem.stat(lockPath);
-                        if (atPath.ino === last.ino && atPath.dev === last.dev && atPath.mtimeMs === last.mtimeMs) {
-                            await filesystem.rm(lockPath, { force: true });
-                            options.onStaleLockRemoved?.({ holder: current.holder });
-                        }
-                    }
-                    catch (error) {
-                        if (errorCode(error) !== "ENOENT")
-                            throw error;
-                    }
-                }
-            }
-        }
-        checkTimeout(lockPath, observed?.holder, start, s, options);
-        await (options.sleep ?? (({ durationMs }) => new Promise(resolve => setTimeout(resolve, durationMs))))({ durationMs: s.pollMs });
+        const identity = await tryCreateAsync(ctx);
+        if (identity)
+            return identity;
+        const observed = await inspectAsync(ctx.lockPath, ctx.filesystem);
+        if (observed)
+            await removeIfStaleAsync(observed, ctx);
+        checkTimeout(ctx.lockPath, observed?.holder, start, ctx.s, ctx.options);
+        await sleep({ durationMs: ctx.s.pollMs });
     }
-    const held = async () => { const current = await inspectAsync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+}
+async function runHeldAsync({ lockPath, raw, filesystem, options }, identity, run) {
+    const held = async () => ownsSnapshot(await inspectAsync(lockPath, filesystem), raw, identity);
     let completed = false;
     try {
         const value = await run({ lockPath, assertHeld: async (_required) => { if (!await held())
-                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+                throw new FileLockLostError({ lockPath }, messagesOption(options)); } });
         completed = true;
         return value;
     }
@@ -305,11 +363,18 @@ export async function withFileLock({ lockPath, run }, options = {}) {
             if (await held())
                 await filesystem.rm(lockPath, { force: true });
         }
-        // A failed critical section keeps its original error; durable hosts also suppress release-only failures.
         catch (error) {
-            if (completed && !options.suppressReleaseErrors && errorCode(error) !== "ENOENT")
-                throw error;
+            rethrowReleaseError(error, completed, options);
         }
     }
 }
+/** Async adapter of the same stale and ownership policy; polling yields to other writers. */
+export async function withFileLock({ lockPath, run }, options = {}) {
+    const filesystem = options.filesystem ?? asyncFs, s = settings(options), start = s.monotonicMs(), raw = ownership(s, options);
+    if (options.createParent)
+        await filesystem.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    const ctx = { lockPath, raw, filesystem, s, options };
+    const identity = await acquireAsync(ctx, start, options.sleep ?? (({ durationMs }) => new Promise(resolve => setTimeout(resolve, durationMs))));
+    return runHeldAsync(ctx, identity, run);
+}
 //# sourceMappingURL=file-lock.js.map

package/dist/fs/guarded-reader.js

@@ -137,7 +137,8 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             }
         }
         // A target equal to base yields [""] after split, so check leaf length, not array length.
-        const effectiveLeaf = effectiveSegments.at(-1) ?? "";
+        // split always yields at least one element, so the leaf is always defined.
+        const effectiveLeaf = effectiveSegments[effectiveSegments.length - 1];
         if (effectiveLeaf.length > 0 && isDeniedFsFileName(effectiveLeaf)) {
             throw new FsFilePathError({ message: `path '${relativePath}' resolves to a denied filename pattern and cannot be accessed` });
         }
@@ -213,9 +214,18 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             return statSync(target, { throwIfNoEntry: false });
         }
         catch (err) {
-            throw new FsFilePathError({ message: `path '${relativePath}' could not be read: ${err instanceof Error ? err.message : String(err)}` });
+            throw new FsFilePathError({ message: `path '${relativePath}' could not be read: ${errorText(err)}` });
         }
     }
+    // Both read paths refuse missing and non-regular targets with identical wording.
+    function statRegularFile(target, relativePath) {
+        const stat = statOrFsPathError(target, relativePath);
+        if (!stat)
+            throw new FsFilePathError({ message: `file '${relativePath}' does not exist` });
+        if (!stat.isFile())
+            throw new FsFilePathError({ message: `path '${relativePath}' is not a regular file` });
+        return stat;
+    }
     // A bounded leading-NUL heuristic keeps binary databases/images/archives out of inline UTF-8
     // model input without making type sniffing proportional to the full file size.
     function looksBinary(buffer) {
@@ -228,16 +238,19 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     }
     function readFsFile(required) {
         const target = resolveFsFilePath(required);
-        const stat = statOrFsPathError(target, required.relativePath);
-        if (!stat)
-            throw new FsFilePathError({ message: `file '${required.relativePath}' does not exist` });
-        if (!stat.isFile())
-            throw new FsFilePathError({ message: `path '${required.relativePath}' is not a regular file` });
+        const stat = statRegularFile(target, required.relativePath);
         if (stat.size > MAX_FS_FILE_BYTES) {
             throw new FsFilePathError({ message: `file '${required.relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
         }
+        const buffer = readBoundedSync(target, required.relativePath);
+        if (looksBinary(buffer)) {
+            throw new FsFilePathError({ message: `file '${required.relativePath}' looks like a binary file and cannot be read as text` });
+        }
+        return { content: buffer.toString("utf8"), bytes: buffer.byteLength };
+    }
+    // Read one byte past the cap so a file that grew after stat is refused rather than clipped.
+    function readBoundedSync(target, relativePath) {
         const fd = fs.openSync(target, "r");
-        let buffer;
         try {
             const bounded = Buffer.alloc(MAX_FS_FILE_BYTES + 1);
             let count = 0;
@@ -248,16 +261,12 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
                 count += read;
             }
             if (count > MAX_FS_FILE_BYTES)
-                throw new FsFilePathError({ message: `file '${required.relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
-            buffer = bounded.subarray(0, count);
+                throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
+            return bounded.subarray(0, count);
         }
         finally {
             fs.closeSync(fd);
         }
-        if (looksBinary(buffer)) {
-            throw new FsFilePathError({ message: `file '${required.relativePath}' looks like a binary file and cannot be read as text` });
-        }
-        return { content: buffer.toString("utf8"), bytes: buffer.byteLength };
     }
     // A stat-only size check can be bypassed by a growing file: bound the stream independently and
     // reject rather than return a clipped image/video. Destroy the stream on success or failure.
@@ -267,32 +276,19 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             throw new FsFilePathError({ message: "maxBytes must be a positive safe integer" });
         }
         const target = resolveFsFilePath(required);
-        const stat = statOrFsPathError(target, relativePath);
-        if (!stat)
-            throw new FsFilePathError({ message: `file '${relativePath}' does not exist` });
-        if (!stat.isFile())
-            throw new FsFilePathError({ message: `path '${relativePath}' is not a regular file` });
+        const stat = statRegularFile(target, relativePath);
         if (stat.size > maxBytes) {
             throw new FsFilePathError({ message: `file '${relativePath}' is ${stat.size} bytes and exceeds the ${maxBytes}-byte import limit` });
         }
+        return readBoundedStream(target, { relativePath, maxBytes });
+    }
+    async function readBoundedStream(target, { relativePath, maxBytes }) {
         const stream = fs.createReadStream(target, { highWaterMark: Math.min(64 * 1024, maxBytes + 1) });
-        const chunks = [];
-        let totalBytes = 0;
         try {
-            for await (const chunk of stream) {
-                const bytes = chunk;
-                totalBytes += bytes.byteLength;
-                if (totalBytes > maxBytes) {
-                    throw new FsFilePathError({ message: `file '${relativePath}' is at least ${totalBytes} bytes and exceeds the ${maxBytes}-byte import limit` });
-                }
-                chunks.push(bytes);
-            }
-            return Buffer.concat(chunks, totalBytes);
-        }
-        catch (error) {
-            if (error instanceof FsFilePathError)
-                throw error;
-            throw new FsFilePathError({ message: `path '${relativePath}' could not be read: ${error instanceof Error ? error.message : String(error)}` });
+            // Own refusals pass through; any other stream failure becomes this reader's refusal class.
+            return await collectBoundedChunks(stream, { relativePath, maxBytes }).catch((error) => Promise.reject(error instanceof FsFilePathError
+                ? error
+                : new FsFilePathError({ message: `path '${relativePath}' could not be read: ${errorText(error)}` })));
         }
         finally {
             stream.destroy();
@@ -307,4 +303,20 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         isDeniedPathSegment: ({ segmentName }) => isDeniedFsPathSegment(segmentName),
     };
 }
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function collectBoundedChunks(stream, { relativePath, maxBytes }) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of stream) {
+        const bytes = chunk;
+        totalBytes += bytes.byteLength;
+        if (totalBytes > maxBytes) {
+            throw new FsFilePathError({ message: `file '${relativePath}' is at least ${totalBytes} bytes and exceeds the ${maxBytes}-byte import limit` });
+        }
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks, totalBytes);
+}
 //# sourceMappingURL=guarded-reader.js.map

package/dist/fs/user-data-directories.d.ts

@@ -15,7 +15,7 @@ export interface UserDirectoryOptions {
 export declare function resolveUserDataDirectories({ homeDir, appName }: {
     homeDir: string;
     appName: string;
-}, { platform, env, appDataDir, readText, windowsDocuments }?: UserDirectoryOptions): {
+}, options?: UserDirectoryOptions): {
     appData: string;
     documents: string;
 };