@jini-ai/platform 0.3.0 → 0.5.0

package/dist/fs/file-lock.js

@@ -0,0 +1,306 @@
+/**
+ * Atomic writes prevent tears but not lost updates between shared read-modify-writes. Plain readers
+ * need no lock. Deliberately non-reentrant: nesting times out rather than silently sharing an
+ * exclusive section; compose store operations from unlocked internals instead.
+ * Kernel exclusive create chooses the winner. A unique token AND inode identify that owner;
+ * pid alone cannot distinguish a later owner after a stale break. Signal-zero liveness probes
+ * treat only ESRCH as death: permission failure must never authorize evicting a live process.
+ * Stale removal rechecks inode, bytes and mtime immediately before unlink. There is still a residual
+ * check-to-unlink race on filesystems without conditional unlink; rename/restore chains create wider
+ * 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 fs from "node:fs";
+import * as asyncFs from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { hostname as nodeHostname } from "node:os";
+import path from "node:path";
+import { createSystemClock } from "@jini-ai/core/primitives";
+import { defaultPlatformMessages } from "../messages.js";
+export const DEFAULT_LOCK_TIMEOUT_MS = 15_000;
+export const DEFAULT_LOCK_STALE_AFTER_MS = 10_000;
+export class FileLockTimeoutError extends Error {
+    lockPath;
+    holder;
+    waitedMs;
+    constructor(required, optional = {}) {
+        super(optional.message ?? (optional.messages ?? defaultPlatformMessages).fileLockTimeout({ waitedMs: required.waitedMs }));
+        this.name = "FileLockTimeoutError";
+        this.lockPath = required.lockPath;
+        this.holder = required.holder;
+        this.waitedMs = required.waitedMs;
+    }
+}
+export class FileLockLostError extends Error {
+    lockPath;
+    constructor({ lockPath }, { messages = defaultPlatformMessages } = {}) {
+        super(messages.fileLockLost());
+        this.name = "FileLockLostError";
+        this.lockPath = lockPath;
+    }
+}
+/** Platform-specific contention classification retains the Windows exclusive-open behavior. */
+export function isContendedLockError({ code, platform }) {
+    return code === "EEXIST" || (code === "EPERM" && platform === "win32");
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+function validPid(pid) { return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0; }
+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")
+            return undefined;
+        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One pure stale decision serves both I/O adapters. Invalid/foreign pids have unknown liveness,
+ * never false liveness; otherwise kill(0/negative, 0) would address a process group. */
+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) {
+    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)
+        throw new RangeError((options.messages ?? defaultPlatformMessages).fileLockIntervalsInvalid());
+    const processPort = options.process ?? { pid: process.pid, isAlive: ({ pid }) => { try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return errorCode(error) !== "ESRCH";
+        } } };
+    const clock = options.clock ?? createSystemClock();
+    const monotonicMs = options.monotonicMs ?? (() => clock.nowMs());
+    return { timeoutMs, staleMs, pollMs, processPort, clock, monotonicMs, hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
+}
+function ownership(s, options) {
+    return options.format === "token" ? `${s.processPort.pid}:${s.token}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString() });
+}
+function ownerAlive(snapshot, s) {
+    const holder = snapshot.holder;
+    if (holder)
+        return holder.hostname === s.hostname ? s.processPort.isAlive({ pid: holder.pid }) : undefined;
+    // Legacy synchronous stores wrote pid:random rather than JSON. Malformed pids remain unknown.
+    if (!/^\d+:/.test(snapshot.raw))
+        return undefined;
+    const pid = Number(snapshot.raw.split(":", 1)[0]);
+    return validPid(pid) ? s.processPort.isAlive({ pid }) : undefined;
+}
+function unchanged(a, b) { return a.ino === b.ino && a.dev === b.dev && a.raw === b.raw && a.mtimeMs === b.mtimeMs; }
+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 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 } : {}) });
+    }
+}
+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 }))
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = filesystem.fstatSync(descriptor), raw = filesystem.readFileSync(descriptor, "utf8");
+        return { raw, holder: parseHolder(raw), mtimeMs: info.mtimeMs, ino: info.ino, dev: info.dev };
+    }
+    finally {
+        filesystem.closeSync(descriptor);
+    }
+}
+async function inspectAsync(lockPath, filesystem) {
+    let handle;
+    try {
+        handle = await filesystem.open(lockPath, "r");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || isContendedLockError({ code: errorCode(error), platform: process.platform }))
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = await handle.stat(), raw = await handle.readFile("utf8");
+        return { raw, holder: parseHolder(raw), mtimeMs: info.mtimeMs, ino: info.ino, dev: info.dev };
+    }
+    finally {
+        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 });
+    let identity;
+    for (;;) {
+        let descriptor;
+        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;
+                    }
+                }
+            }
+        }
+        // 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 });
+    }
+    const held = () => { const current = inspectSync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+    let completed = false;
+    try {
+        const value = run({ lockPath, assertHeld: (_required) => { if (!held())
+                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+        completed = true;
+        return value;
+    }
+    finally {
+        try {
+            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;
+        }
+    }
+}
+/** 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 });
+    let identity;
+    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 held = async () => { const current = await inspectAsync(lockPath, filesystem); return current && current.raw === raw && current.ino === identity.ino && current.dev === identity.dev; };
+    let completed = false;
+    try {
+        const value = await run({ lockPath, assertHeld: async (_required) => { if (!await held())
+                throw new FileLockLostError({ lockPath }, options.messages ? { messages: options.messages } : {}); } });
+        completed = true;
+        return value;
+    }
+    finally {
+        try {
+            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;
+        }
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/fs/guarded-reader.d.ts

@@ -0,0 +1,60 @@
+import nodeFs from "node:fs";
+/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
+export declare class FsFilePathError extends Error {
+    constructor({ message }: {
+        message: string;
+    });
+}
+export interface DenyRules {
+    segments: ReadonlySet<string>;
+    filenamePatterns: readonly RegExp[];
+}
+export interface GuardedReaderLimits {
+    maxFileBytes: number;
+    binarySniffBytes: number;
+    maxListedFiles: number;
+    maxWalkDepth: number;
+    maxWalkEntries: number;
+}
+export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream">;
+/** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
+export declare function createNodeGuardedReaderFilesystem(_required: Record<string, never>): GuardedReaderFilesystem;
+export interface GuardedFileReader {
+    resolve(required: {
+        relativePath: string;
+    }): string;
+    read(required: {
+        relativePath: string;
+    }): {
+        content: string;
+        bytes: number;
+    };
+    readBytes(required: {
+        relativePath: string;
+        maxBytes: number;
+    }): Promise<Uint8Array>;
+    list(required: Record<string, never>, optional?: {
+        relativePath?: string;
+    }): {
+        files: string[];
+        truncated: boolean;
+    };
+    isDeniedFileName(required: {
+        fileName: string;
+    }): boolean;
+    isDeniedPathSegment(required: {
+        segmentName: string;
+    }): boolean;
+}
+/** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
+ * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ */
+export declare function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }: {
+    rootPath: string;
+    denyRules: DenyRules;
+    limits: GuardedReaderLimits;
+    filesystem: GuardedReaderFilesystem;
+}, { excludedListingDirs }?: {
+    excludedListingDirs?: ReadonlySet<string>;
+}): GuardedFileReader;
+//# sourceMappingURL=guarded-reader.d.ts.map

package/dist/fs/guarded-reader.js

@@ -0,0 +1,310 @@
+import nodeFs from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+// A distinct refusal class lets tool adapters treat rejected paths/content as actionable input
+// problems instead of redacting them as an internal crash.
+/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
+export class FsFilePathError extends Error {
+    constructor({ message }) { super(message); this.name = "FsFilePathError"; }
+}
+/** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
+export function createNodeGuardedReaderFilesystem(_required) { return nodeFs; }
+/** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
+ * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ */
+export function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }, { excludedListingDirs = new Set(["node_modules", ".git", "dist"]) } = {}) {
+    if (!rootPath)
+        throw new TypeError("rootPath is required");
+    for (const value of Object.values(limits))
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new TypeError("reader limits must be positive safe integers");
+    const { existsSync, lstatSync, readdirSync, realpathSync, statSync } = fs;
+    const MAX_FS_FILE_BYTES = limits.maxFileBytes, BINARY_SNIFF_BYTES = limits.binarySniffBytes;
+    const MAX_LISTED_FILES = limits.maxListedFiles, MAX_WALK_DEPTH = limits.maxWalkDepth, MAX_WALK_ENTRIES = limits.maxWalkEntries;
+    // Listing exclusions reduce noise; they never grant or deny a known file read. Security comes
+    // from denyRules, applied to both the caller spelling and the effective target.
+    const EXCLUDED_LISTING_DIR_NAMES = excludedListingDirs;
+    function isDeniedFsFileName(fileName) {
+        const folded = foldFsNameForDenylist(fileName);
+        return denyRules.filenamePatterns.some((pattern) => new RegExp(pattern).test(fileName) || new RegExp(pattern).test(folded));
+    }
+    function isDeniedFsPathSegment(segmentName) {
+        return denyRules.segments.has(segmentName.toLowerCase()) || denyRules.segments.has(foldFsNameForDenylist(segmentName));
+    }
+    // Default case-insensitive APFS can open LONG S/KELVIN SIGN aliases of denied names that plain
+    // toLowerCase or non-Unicode /i misses. Windows also ignores trailing dots/spaces and opens
+    // name::$DATA as name. Compare raw AND folded names: folding may add denials, never remove them,
+    // and must not change the path actually opened.
+    function foldFsNameForDenylist(name) {
+        const withoutStream = name.replace(/:[^]*$/, "");
+        const withoutTrailing = withoutStream.replace(/[. ]+$/, "");
+        return withoutTrailing.toLowerCase().toUpperCase().toLowerCase();
+    }
+    // Split both separator spellings even on a host whose native separator is '/', so deny checks
+    // remain cross-platform. The guard and reader must resolve the same spelling consistently.
+    function normalizeFsRelativePath(relativePath) {
+        const segments = [];
+        for (const segment of relativePath.split(/[\\/]/)) {
+            if (segment === "" || segment === ".")
+                continue;
+            if (segment === "..") {
+                segments.pop();
+                continue;
+            }
+            segments.push(segment);
+        }
+        return segments.join("/");
+    }
+    // A string prefix admits siblings whose names extend the root and ignores traversal. Resolve
+    // first, then compare path.relative components; symlink containment needs its own check below.
+    function isWithin(base, target) {
+        if (base === target)
+            return true;
+        const rel = relative(base, target);
+        return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+    }
+    // Probe the deepest existing ancestor: a nonexistent descendant can still sit beneath a
+    // symlink that escapes the root, even when its lexical path passed containment.
+    // Bound ancestor steps to four times the listing depth, plus the endpoint check, so deeply
+    // nested missing paths cannot cause unbounded synchronous probes. Unknown containment refuses.
+    function assertNoSymlinkEscape(base, path, relativePathForError) {
+        let probe = path;
+        for (let i = 0; i < MAX_WALK_DEPTH * 4 && !existsSync(probe); i += 1) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                break;
+            probe = parent;
+        }
+        if (!existsSync(probe))
+            throw new FsFilePathError({ message: `path '${relativePathForError}' containment could not be established within the ancestor traversal limit` });
+        const realProbe = realpathSync(probe);
+        if (!isWithin(base, realProbe)) {
+            throw new FsFilePathError({ message: `path '${relativePathForError}' resolves outside the allowed root through a symbolic link` });
+        }
+    }
+    function resolveFsFilePath(required) {
+        const { rootPath, relativePath } = required;
+        assertWellFormedRelativePath(relativePath);
+        assertRequestedPathNotDenied(relativePath);
+        // Canonicalize a symlinked root too, or the ancestor's realpath would compare to a different
+        // representation and refuse legitimate reads through a linked package/root.
+        const base = existsSync(rootPath) ? realpathSync(rootPath) : resolve(rootPath);
+        const target = resolve(base, relativePath);
+        if (!isWithin(base, target)) {
+            throw new FsFilePathError({ message: `path '${relativePath}' resolves outside the allowed root` });
+        }
+        assertNoSymlinkEscape(base, target, relativePath);
+        assertEffectiveTargetNotDenied(base, target, relativePath);
+        return target;
+    }
+    // Isolate initial shape refusals so resolve reads as the ordered sequence of containment and
+    // deny checks, rather than burying that boundary in one long guard block.
+    function assertWellFormedRelativePath(relativePath) {
+        if (relativePath.length === 0) {
+            throw new FsFilePathError({ message: "path is required" });
+        }
+        if (relativePath.includes("\0")) {
+            throw new FsFilePathError({ message: "path must not contain a NUL byte" });
+        }
+        if (isAbsolute(relativePath)) {
+            throw new FsFilePathError({ message: `path '${relativePath}' must be relative to the root, not absolute` });
+        }
+    }
+    // Refuse denied spellings before filesystem access, regardless of whether they exist. The
+    // effective-target check is separate because a harmless alias can resolve to a denied file.
+    function assertRequestedPathNotDenied(relativePath) {
+        const normalized = normalizeFsRelativePath(relativePath);
+        const segments = normalized.length === 0 ? [] : normalized.split("/");
+        for (const segment of segments) {
+            if (isDeniedFsPathSegment(segment)) {
+                throw new FsFilePathError({ message: `path '${relativePath}' contains a denied path segment ('${segment}') and cannot be accessed` });
+            }
+        }
+        const leafName = segments.at(-1) ?? "";
+        if (leafName.length > 0 && isDeniedFsFileName(leafName)) {
+            throw new FsFilePathError({ message: `path '${relativePath}' matches a denied filename pattern and cannot be accessed` });
+        }
+    }
+    // public.txt -> .env stays inside the root and passes lexical checks; Node follows it on read.
+    // Deny the real target as well. existsSync excludes broken/circular links before realpath, and
+    // the subsequent stat translates their failure into this reader's own refusal class.
+    function assertEffectiveTargetNotDenied(base, target, relativePath) {
+        if (!existsSync(target))
+            return;
+        const effectiveSegments = relative(base, realpathSync(target)).split(sep);
+        for (const segment of effectiveSegments) {
+            if (isDeniedFsPathSegment(segment)) {
+                throw new FsFilePathError({ message: `path '${relativePath}' resolves to a denied path segment ('${segment}') and cannot be accessed` });
+            }
+        }
+        // A target equal to base yields [""] after split, so check leaf length, not array length.
+        const effectiveLeaf = effectiveSegments.at(-1) ?? "";
+        if (effectiveLeaf.length > 0 && isDeniedFsFileName(effectiveLeaf)) {
+            throw new FsFilePathError({ message: `path '${relativePath}' resolves to a denied filename pattern and cannot be accessed` });
+        }
+    }
+    function visitFsDirEntry(dir, name, depth, base, found, state) {
+        const full = resolve(dir, name);
+        // lstat examines the link itself: stat would follow circular links and throw ELOOP before
+        // the skip. Never enumerate/report links or descend denied directories, so listings do not
+        // advertise secrets or anything outside the root. Ordinary excluded directories are noise.
+        const stat = lstatSync(full, { throwIfNoEntry: false });
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink())
+            return;
+        if (stat.isDirectory()) {
+            if (isDeniedFsPathSegment(name) || EXCLUDED_LISTING_DIR_NAMES.has(name))
+                return;
+            walkFsDir(full, depth + 1, base, found, state);
+            return;
+        }
+        if (!stat.isFile())
+            return;
+        if (isDeniedFsFileName(name))
+            return;
+        found.push(relative(base, full).split(sep).join("/"));
+    }
+    // Results, entries, and depth are independent limits; keep the decision shared by entry and
+    // loop checks so adding one limit cannot leave an unbounded arm.
+    function walkBoundReached(found, state, depth) {
+        return depth > MAX_WALK_DEPTH || found.length >= MAX_LISTED_FILES || state.remaining <= 0;
+    }
+    function walkFsDir(dir, depth, base, found, state) {
+        if (walkBoundReached(found, state, depth)) {
+            state.truncated = true;
+            return;
+        }
+        for (const name of readdirSync(dir)) {
+            // Recheck per entry: this loop spends traversal budget and adds results. Remaining
+            // entries mean a bound must set truncated rather than present a short list as complete.
+            if (walkBoundReached(found, state, depth)) {
+                state.truncated = true;
+                return;
+            }
+            state.remaining -= 1;
+            visitFsDirEntry(dir, name, depth, base, found, state);
+        }
+    }
+    function listFsFiles(required) {
+        const { rootPath } = required;
+        const relativePath = required.relativePath ?? "";
+        const startDir = relativePath.length === 0 ? resolve(rootPath) : resolveFsFilePath({ rootPath, relativePath });
+        // Freshly provisioned roots/subdirectories may not exist yet; an empty listing is valid.
+        if (!existsSync(startDir))
+            return { files: [], truncated: false };
+        const startStat = statOrFsPathError(startDir, relativePath || ".");
+        if (!startStat)
+            return { files: [], truncated: false };
+        if (!startStat.isDirectory()) {
+            throw new FsFilePathError({ message: `path '${relativePath || "."}' is not a directory` });
+        }
+        const base = realpathSync(startDir);
+        const found = [];
+        const state = { remaining: MAX_WALK_ENTRIES, truncated: false };
+        walkFsDir(base, 0, base, found, state);
+        // Paths are relative to the requested walk base, so a subdirectory listing can be consumed
+        // without stripping that subdirectory's prefix a second time.
+        return { files: found.sort(), truncated: state.truncated };
+    }
+    // Circular-link ELOOP and other filesystem exceptions must become the reader's refusal class,
+    // not escape raw while an ordinary missing path is represented by undefined.
+    function statOrFsPathError(target, relativePath) {
+        try {
+            return statSync(target, { throwIfNoEntry: false });
+        }
+        catch (err) {
+            throw new FsFilePathError({ message: `path '${relativePath}' could not be read: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    // 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) {
+        const sniffLength = Math.min(buffer.length, BINARY_SNIFF_BYTES);
+        for (let i = 0; i < sniffLength; i += 1) {
+            if (buffer[i] === 0)
+                return true;
+        }
+        return false;
+    }
+    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` });
+        if (stat.size > MAX_FS_FILE_BYTES) {
+            throw new FsFilePathError({ message: `file '${required.relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
+        }
+        const fd = fs.openSync(target, "r");
+        let buffer;
+        try {
+            const bounded = Buffer.alloc(MAX_FS_FILE_BYTES + 1);
+            let count = 0;
+            while (count < bounded.length) {
+                const read = fs.readSync(fd, bounded, count, bounded.length - count, null);
+                if (read === 0)
+                    break;
+                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);
+        }
+        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.
+    async function openFsFileForRead(required) {
+        const { relativePath, maxBytes } = required;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            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` });
+        if (stat.size > maxBytes) {
+            throw new FsFilePathError({ message: `file '${relativePath}' is ${stat.size} bytes and exceeds the ${maxBytes}-byte import limit` });
+        }
+        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)}` });
+        }
+        finally {
+            stream.destroy();
+        }
+    }
+    return {
+        resolve: ({ relativePath }) => resolveFsFilePath({ rootPath, relativePath }),
+        read: ({ relativePath }) => readFsFile({ rootPath, relativePath }),
+        readBytes: ({ relativePath, maxBytes }) => openFsFileForRead({ rootPath, relativePath, maxBytes }),
+        list: (_required, optional = {}) => listFsFiles({ rootPath, ...optional }),
+        isDeniedFileName: ({ fileName }) => isDeniedFsFileName(fileName),
+        isDeniedPathSegment: ({ segmentName }) => isDeniedFsPathSegment(segmentName),
+    };
+}
+//# sourceMappingURL=guarded-reader.js.map