@neuralis/brain-core 0.3.2 → 0.4.1

package/dist/src/connectors/HostConnector.js

@@ -0,0 +1,903 @@
+var _a;
+/**
+ * The `host` connector — ONE class for a folder as a source, wherever the
+ * folder lives. A transport (`HostFsTransport`, the kernel port) moves the bytes
+ * and runs the kernel's one folder walk on the machine that holds them:
+ *
+ *  - no `device` in the stored config ⇒ `local`, this process's own filesystem
+ *    (`InProcessTransport`): a Docker mount, the native project zone, `data`,
+ *    `packages`, the App Zone;
+ *  - `device` ⇒ that paired device's broker over its link — agent-core's
+ *    transport, handed over through its device API (`devices.openTransport`), so
+ *    no broker code lives here.
+ *
+ * Everything a source MEANS is decided here, once: uri↔path in the folder's
+ * own flavour, the MIME table, the inline caps a model read honours, the
+ * byte-exact read, the bounded count cache, the watch-to-uri mapping and the
+ * package reader. The kernel's `sourcePlane` reads the same stored field that
+ * picks the transport.
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { posix as posixPath, win32 as win32Path } from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { CONNECTOR_PORT_VERSION, ConnectorRawReadTooLarge, ConnectorRootAccessError, HOST_SOURCE_KIND, isPackageFolderPath, sourcePlane, } from '@neuralis/package-system/contracts';
+import { detectDocker, discoverOsMounts, isPathInside } from '@neuralis/package-system/paths';
+import { isSkippableFsError } from '@neuralis/package-system/data';
+import { binaryMimeTypeForPath, inferMimeTypeFromFilename } from '../domain/mime.js';
+import { looksBinaryContent } from '../domain/text.js';
+import { getBrainConfigBoolean, getBrainConfigNumber, getInlineAudioCapBytes, getInlineImageCapBytes, getInlinePdfCapBytes, getInlineVideoCapBytes, } from '../config/env.js';
+import { DEFAULT_MAX_SCAN_FILES } from '../domain/scanCap.js';
+import { CHILD_ENV, InProcessTransport, OsUriUnresolvableError, deriveHostRootFromOsMounts, resolveLocalRoot, } from './inProcessTransport.js';
+/**
+ * The capability set of the `host` kind. It MUST equal the `host` connector's
+ * `capabilities` array in `package.json#neuralis.connectors` — the loader binds
+ * one kind to one set and refuses a drifted instance (boot-fatal for a native
+ * connector). `hostCapabilities.test.ts` derives the expectation from the manifest.
+ */
+export const HOST_CAPABILITIES = [
+    'list', 'read', 'stat', 'write', 'delete', 'move', 'mkdir', 'rmdir',
+    'scanDelta', 'walk', 'count', 'peekCount', 'scanContent', 'subscribeEvents', 'resolveOsUri',
+    'rawRead',
+];
+/** How long a `count` is fresh for `peekCount` and `count` (`brainCountCacheTtlMs`); older, `count` serves it while one walk refreshes it. */
+export const COUNT_CACHE_TTL_MS = 60_000;
+/** Count-cache entries one source keeps (each a key string + two numbers), fresh or stale; past it the oldest goes. */
+export const MAX_COUNT_CACHE_ENTRIES = 256;
+/** The folder budget of ONE package folder's watch (a device's broker clamps above). */
+export const PACKAGE_FOLDER_WATCH_MAX_FOLDERS = 5_000;
+/** Trees a package watch never enters — they hold no contribution the loader reads. */
+const PACKAGE_WATCH_EXCLUDES = ['**/node_modules/**', '**/.git/**'];
+/** A device package file is read whole only under this many bytes. */
+const PACKAGE_FILE_MAX_BYTES = 1_000_000;
+/** One write RPC/syscall carries at most this many bytes; a larger file goes in chunks. */
+export const WRITE_CHUNK_BYTES = 3 * 1024 * 1024;
+/** The ONE byte ceiling of a whole-file read (`brainMaxReadFileMb`, default 100 MB) — the same on both transports, read LIVE per call. */
+const maxReadBytes = () => getBrainConfigNumber('brainMaxReadFileMb', undefined, 100) * 1024 * 1024;
+/** PDF text-extract cap (`brainPdfTextExcerptBytes`, default 200 KB), LIVE. */
+const pdfTextExcerptBytes = () => getBrainConfigNumber('brainPdfTextExcerptBytes', undefined, 200 * 1024);
+/** First-page render, opt-in (`fsReadPdfRender`), LIVE. */
+const pdfRenderFirstPage = () => getBrainConfigBoolean('fsReadPdfRender', 'NEURALIS_FS_READ_PDF_RENDER', false);
+function formatBytes(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0 B';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** The per-MIME inline cap a model read honours; `null` ⇒ the MIME is never inlined. */
+function inlineCapForMime(mimeType) {
+    if (mimeType === 'application/pdf')
+        return getInlinePdfCapBytes();
+    if (mimeType.startsWith('image/'))
+        return getInlineImageCapBytes();
+    if (mimeType.startsWith('video/'))
+        return getInlineVideoCapBytes();
+    if (mimeType.startsWith('audio/'))
+        return getInlineAudioCapBytes();
+    return null;
+}
+let pdftotextProbed = null;
+let pdftoppmProbed = null;
+function whichBinary(name) {
+    return new Promise((resolve) => {
+        const child = execFile('which', [name], { env: CHILD_ENV }, (err, stdout) => {
+            if (err)
+                return resolve(false);
+            resolve(typeof stdout === 'string' && stdout.trim().length > 0);
+        });
+        child.on('error', () => resolve(false));
+    });
+}
+async function hasPdftotext() {
+    if (pdftotextProbed === null)
+        pdftotextProbed = await whichBinary('pdftotext');
+    return pdftotextProbed;
+}
+async function hasPdftoppm() {
+    if (pdftoppmProbed === null)
+        pdftoppmProbed = await whichBinary('pdftoppm');
+    return pdftoppmProbed;
+}
+async function pdftotextExcerpt(absPath) {
+    const excerptBytes = pdfTextExcerptBytes();
+    return new Promise((resolve) => {
+        const child = execFile('pdftotext', [absPath, '-'], { timeout: 10_000, maxBuffer: excerptBytes * 4, env: CHILD_ENV }, (err, stdout) => {
+            if (err)
+                return resolve(null);
+            const out = String(stdout ?? '');
+            resolve(out.length > excerptBytes ? `${out.slice(0, excerptBytes)}\n\n…(pdftotext output truncated at ${excerptBytes} bytes)` : out);
+        });
+        child.on('error', () => resolve(null));
+    });
+}
+/**
+ * THE PDF→PNG renderer (`pdftoppm -r 100`): pages `first..last`, in page order,
+ * one private temp directory per call. A failed or timed-out render answers `[]`.
+ */
+async function pdftoppmPages(absPath, first, last) {
+    const from = Math.max(1, Math.floor(first));
+    const to = Math.max(from, Math.floor(last));
+    let dir;
+    try {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'neuralis-pdfrender-'));
+    }
+    catch {
+        return [];
+    }
+    try {
+        const ok = await new Promise((resolve) => {
+            const child = execFile('pdftoppm', ['-f', String(from), '-l', String(to), '-r', '100', '-png', absPath, path.join(dir, 'page')], { timeout: 15_000 * (to - from + 1), env: CHILD_ENV }, (err) => resolve(!err));
+            child.on('error', () => resolve(false));
+        });
+        if (!ok)
+            return [];
+        const files = (await fs.readdir(dir))
+            .map((name) => ({ name, page: Number(/-(\d+)\.png$/.exec(name)?.[1]) }))
+            .filter((f) => Number.isFinite(f.page))
+            .sort((a, b) => a.page - b.page);
+        const pages = [];
+        for (const f of files)
+            pages.push({ page: f.page, png: await fs.readFile(path.join(dir, f.name)) });
+        return pages;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * The source root itself is missing or unreadable — a listing of the ROOT
+ * throws this (the abstract base is what routes and services catch); a missing
+ * sub-folder lists as empty.
+ */
+export class HostRootAccessError extends ConnectorRootAccessError {
+    constructor(code, rootPath, uri, cause) {
+        super(code, rootPath, uri, code === 'ROOT_MISSING'
+            ? `Source root "${rootPath}" does not exist`
+            : `Source root "${rootPath}" is not readable (permission denied)`, cause);
+        this.name = 'HostRootAccessError';
+    }
+}
+function rootAccessCode(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'ROOT_MISSING';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'ROOT_PERMISSION_DENIED';
+    return null;
+}
+/** A Windows drive-absolute root (`C:\…`), normalised, trailing separator dropped except on a drive root; `''` otherwise. */
+function windowsRoot(raw) {
+    if (!/^[A-Za-z]:[\\/]/.test(raw))
+        return '';
+    const normal = win32Path.normalize(raw);
+    return normal === win32Path.parse(normal).root ? normal : normal.replace(/[\\/]+$/, '');
+}
+/**
+ * The fixed code a transport refusal carries (`devices_disabled`,
+ * `device_offline`, `others_denied`, `device_owner_ungranted`, …) — never its
+ * text, which can name a device path. `undefined` for anything else (an errno,
+ * a plain failure): "could not ask" and "gone" stay apart.
+ */
+export function transportRefusalReason(error) {
+    const reason = error?.reason;
+    return typeof reason === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(reason) ? reason : undefined;
+}
+export class HostConnector {
+    kind = HOST_SOURCE_KIND;
+    source;
+    portVersion = CONNECTOR_PORT_VERSION;
+    #root;
+    #osRoot;
+    /** `#osRoot` normalized — the base a clean uri's `os_uri` is joined onto. */
+    #osBase;
+    #transport;
+    #path;
+    #capabilities = Object.freeze(new Set(HOST_CAPABILITIES));
+    /** A total (`value`) or a failed walk (`error`, and the last total if one existed) — each kept for the TTL. */
+    #countCache = new Map();
+    /** The ONE walk per count key in flight; removed when it settles, so bounded by the keys asked. */
+    #countWalks = new Map();
+    constructor(init) {
+        this.source = init.source;
+        this.#transport = init.transport;
+        this.#path = init.transport.flavour === 'win32' ? win32Path : posixPath;
+        this.#root = this.#path.normalize(init.root);
+        if (init.osRoot !== undefined) {
+            this.#osRoot = init.osRoot;
+            this.#osBase = this.#path.normalize(init.osRoot);
+        }
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    /** The paired device this folder lives on; `undefined` for an in-process folder. */
+    get device() {
+        return this.#transport.device;
+    }
+    /** The root on the folder's OWN machine (a device path for a device folder) — server-side only, never serialized. */
+    get root() {
+        return this.#root;
+    }
+    /** The root on THIS process's disk — `undefined` for a device folder (that disk is not ours). */
+    get localRoot() {
+        return this.#transport.kind === 'local' ? this.#root : undefined;
+    }
+    /** The transport this folder is reached through (the git engine's exec seam). */
+    get transport() {
+        return this.#transport;
+    }
+    /** The uri's path after `<source>://`, leading separators dropped; a foreign uri throws. */
+    #rest(uri) {
+        const prefix = `${this.source}://`;
+        if (!uri.startsWith(prefix))
+            throw new Error(`URI "${uri}" does not belong to source "${this.source}"`);
+        return uri.slice(prefix.length).replace(/^[\\/]+/, '');
+    }
+    /**
+     * `rest` as a path under `base` when it is lexically CLEAN — `/`-separated
+     * names, none empty, `.` or `..`, no `\` and no `:` — so the join cannot
+     * leave `base` and needs no normalize or containment pass (a listing
+     * resolves one per file). A name that only STARTS with dots (`..notes`,
+     * `...`) is clean, exactly as the kernel `isPathInside` reads it. `undefined`
+     * sends any other shape through the full normalize + `isPathInside` clamp.
+     */
+    #under(base, rest) {
+        const trimmed = rest.replace(/\/+$/, '');
+        if (/[\\:]|(?:^|\/)\.{0,2}(?:\/|$)/.test(trimmed))
+            return trimmed === '' ? base : undefined;
+        const sep = this.#path.sep;
+        return `${base}${base.endsWith(sep) ? '' : sep}${sep === '/' ? trimmed : trimmed.replaceAll('/', sep)}`;
+    }
+    /** `<source>://a/b` → the absolute path on the folder's machine; `..` never climbs out. */
+    #abs(uri) {
+        const rest = this.#rest(uri);
+        const clean = this.#under(this.#root, rest);
+        if (clean !== undefined)
+            return clean;
+        const p = this.#path;
+        const joined = p.normalize(rest ? p.join(this.#root, rest) : this.#root);
+        const resolved = joined.length > this.#root.length ? joined.replace(/[\\/]+$/, '') : joined;
+        if (resolved !== this.#root && !isPathInside(this.#root, resolved, p)) {
+            throw new Error(`Path traversal blocked: "${uri}" escapes the source root`);
+        }
+        return resolved;
+    }
+    /** A root-relative (`/`-separated) path for `uri`; `''` is the root. */
+    #rel(uri) {
+        const abs = this.#abs(uri);
+        return abs === this.#root ? '' : this.#path.relative(this.#root, abs).split(this.#path.sep).join('/');
+    }
+    #toUri(rel) {
+        const clean = rel.replace(/^\/+/, '');
+        return clean ? `${this.source}://${clean}` : `${this.source}://`;
+    }
+    /** A machine path under the root → its uri; `undefined` outside it. */
+    #uriOfPath(abs) {
+        const p = this.#path;
+        if (abs !== this.#root && !isPathInside(this.#root, abs, p))
+            return undefined;
+        return this.#toUri(abs === this.#root ? '' : p.relative(this.#root, abs).split(p.sep).join('/'));
+    }
+    /** `base` (root-relative) joined with a walk-relative `rel`. */
+    static #join(base, rel) {
+        return base ? (rel ? `${base}/${rel}` : base) : rel;
+    }
+    async probeConnection() {
+        return this.#transport.probe();
+    }
+    /**
+     * Why a device folder could not serve a call that threw: the plane is down —
+     * answered by the SAME probe the listing's `live`/`live_reason` comes from —
+     * or the device refused it by its fixed code. `undefined` for an in-process
+     * folder and for an error that is no transport refusal: the caller keeps its
+     * own answer. One probe on a failure path only (the device verdict is cached).
+     */
+    async unavailable(error) {
+        if (this.#transport.kind !== 'device')
+            return undefined;
+        const refused = transportRefusalReason(error);
+        if (refused === undefined)
+            return undefined;
+        const probe = await this.#transport.probe();
+        if (probe.connected)
+            return { refused };
+        return { live: false, reason: probe.reason ?? 'store_unreachable', ...(probe.notReady ? { notReady: probe.notReady } : {}) };
+    }
+    /** Wiring diagnostics (operator log only — the root names a machine path). */
+    async probeRoot() {
+        const probe = await this.#transport.probe();
+        return {
+            rootPath: this.#root,
+            exists: probe.connected || probe.reason !== 'fs_unreachable',
+            readable: probe.connected,
+            ...(probe.connected ? {} : { error: probe.reason ?? 'unreachable' }),
+        };
+    }
+    async list(uri) {
+        const rel = this.#rel(uri);
+        let entries;
+        try {
+            entries = await this.#transport.list(this.#abs(uri));
+        }
+        catch (error) {
+            const code = rootAccessCode(error);
+            if (rel === '' && code)
+                throw new HostRootAccessError(code, this.#root, uri, error);
+            if (isSkippableFsError(error))
+                return [];
+            throw error;
+        }
+        return entries
+            .map((entry) => ({
+            uri: this.#toUri(_a.#join(rel, entry.name)),
+            name: entry.name,
+            isDirectory: entry.isDirectory,
+            ...(entry.size === undefined ? {} : { size: entry.size }),
+            ...(entry.modifiedAt ? { modifiedAt: entry.modifiedAt } : {}),
+        }))
+            .sort((a, b) => (a.isDirectory !== b.isDirectory ? (a.isDirectory ? -1 : 1) : a.name.localeCompare(b.name)));
+    }
+    async stat(uri) {
+        return this.#transport.stat(this.#abs(uri));
+    }
+    /**
+     * The whole file at `abs`, `size` bytes as `stat` saw it, in transport-sized
+     * ranges. A file whose size moves between ranges, or that grew past `size`
+     * (one probe byte at the end), is refused — never returned torn.
+     */
+    async #readAll(abs, size, uri, tooLarge) {
+        if (size <= this.#transport.maxRangeBytes) {
+            // One range holds the file: its buffer IS the answer — no second copy.
+            // The +1 asks one byte past the size, so growth shows as a longer answer.
+            const range = await this.#transport.readRange(abs, 0, size + 1);
+            if (range.size !== size || range.bytes.length !== size) {
+                throw range.size > size || range.bytes.length > size ? tooLarge() : new Error(`File changed while reading: "${uri}"`);
+            }
+            return Buffer.from(range.bytes.buffer, range.bytes.byteOffset, range.bytes.byteLength);
+        }
+        const out = Buffer.allocUnsafe(size);
+        let filled = 0;
+        while (filled < size) {
+            const range = await this.#transport.readRange(abs, filled, Math.min(this.#transport.maxRangeBytes, size - filled));
+            if (range.size !== size)
+                throw range.size > size ? tooLarge() : new Error(`File changed while reading: "${uri}"`);
+            if (range.bytes.length === 0)
+                throw new Error(`File changed while reading: "${uri}"`);
+            out.set(range.bytes, filled);
+            filled += range.bytes.length;
+        }
+        const tail = await this.#transport.readRange(abs, size, 1);
+        if (tail.bytes.length > 0 || tail.size !== size)
+            throw tail.size > size ? tooLarge() : new Error(`File changed while reading: "${uri}"`);
+        return out;
+    }
+    /** Run `fn` on a real path of this file on THIS machine — the guarded path, or a private temp copy of a device file. */
+    async #withLocalFile(abs, size, uri, fn) {
+        if (this.#transport.localPath)
+            return fn(await this.#transport.localPath(abs));
+        const bytes = await this.#readAll(abs, size, uri, () => new Error(`File changed while reading: "${uri}"`));
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'neuralis-hostfile-'));
+        try {
+            const local = path.join(dir, `file${this.#path.extname(abs)}`);
+            await fs.writeFile(local, bytes);
+            return await fn(local);
+        }
+        finally {
+            await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async #statFile(abs, uri) {
+        const st = await this.#transport.stat(abs);
+        if (!st)
+            throw Object.assign(new Error(`ENOENT: no such file "${uri}"`), { code: 'ENOENT' });
+        if (st.isDirectory)
+            throw new Error(`Cannot read directory as file: "${uri}"`);
+        return st;
+    }
+    /**
+     * The byte-exact read: the whole file or a refusal, never a prefix or a
+     * marker. Cap = `min(opts.maxBytes, brainMaxReadFileMb)`, checked before any
+     * byte moves; a file that grows past it while it is read is refused too.
+     */
+    async readRaw(uri, opts) {
+        const abs = this.#abs(uri);
+        const planeCap = maxReadBytes();
+        const cap = Math.max(0, Math.min(Math.floor(opts.maxBytes), planeCap));
+        const tooLarge = (size) => new ConnectorRawReadTooLarge(uri, cap, {
+            ...(size === undefined ? {} : { size }),
+            ...(planeCap < opts.maxBytes ? { planeLimit: planeCap } : {}),
+        });
+        const st = await this.#statFile(abs, uri);
+        const size = st.size ?? 0;
+        if (size > cap)
+            throw tooLarge(size);
+        const bytes = await this.#readAll(abs, size, uri, () => tooLarge());
+        return {
+            bytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length),
+            size: bytes.length,
+            mimeType: binaryMimeTypeForPath(abs) ?? inferMimeTypeFromFilename(abs),
+        };
+    }
+    /**
+     * Bytes `[offset, offset+length)` of one file and the WHOLE file's size — the
+     * byte lane's `Range` answer. Moves only that range (in transport-sized
+     * pieces); the caller bounds `length`. Not a kernel port member.
+     */
+    async readByteRange(uri, offset, length) {
+        const abs = this.#abs(uri);
+        const parts = [];
+        let got = 0;
+        let size = -1;
+        while (got < length) {
+            const range = await this.#transport.readRange(abs, offset + got, Math.min(this.#transport.maxRangeBytes, length - got));
+            if (size === -1)
+                size = range.size;
+            else if (range.size !== size)
+                throw new Error(`File changed while reading: "${uri}"`);
+            if (range.bytes.length === 0)
+                break;
+            parts.push(range.bytes);
+            got += range.bytes.length;
+        }
+        const bytes = parts.length === 1 ? parts[0] : new Uint8Array(Buffer.concat(parts.map((p) => Buffer.from(p.buffer, p.byteOffset, p.byteLength))));
+        return { bytes, size: Math.max(size, 0), mimeType: binaryMimeTypeForPath(abs) ?? inferMimeTypeFromFilename(abs) };
+    }
+    /**
+     * The MODEL read: text decoded, a PDF as its text (or its rendered first
+     * page, opt-in), an image/video/audio inline as base64 under its per-MIME
+     * cap and as a `[binary file too large…]` marker above it. Same answer on
+     * both transports — the PDF helpers run on THIS server over a private copy.
+     */
+    async read(uri) {
+        const abs = this.#abs(uri);
+        const st = await this.#statFile(abs, uri);
+        const size = st.size ?? 0;
+        const readCap = maxReadBytes();
+        if (size > readCap)
+            throw new Error(`File too large (${size} bytes, max ${readCap}): "${uri}"`);
+        const tooLarge = () => new Error(`File too large (max ${readCap}): "${uri}"`);
+        const binaryMimeType = binaryMimeTypeForPath(abs);
+        if (binaryMimeType === 'application/pdf') {
+            return this.#withLocalFile(abs, size, uri, async (local) => {
+                const textExcerpt = (await hasPdftotext()) ? await pdftotextExcerpt(local) : null;
+                if (pdfRenderFirstPage() && (await hasPdftoppm())) {
+                    const rendered = (await pdftoppmPages(local, 1, 1))[0]?.png ?? null;
+                    if (rendered && rendered.length <= getInlineImageCapBytes()) {
+                        // The rendered-PDF signal: the journal persists these bytes INLINE —
+                        // re-reading the .pdf would re-render non-deterministically.
+                        return { text: textExcerpt ?? '', mimeType: 'image/png', sourceMimeType: 'application/pdf', size, bytes: rendered.toString('base64') };
+                    }
+                }
+                if (textExcerpt !== null)
+                    return { text: textExcerpt, mimeType: binaryMimeType, size };
+                return {
+                    text: '[application/pdf — pdftotext unavailable; install poppler-utils to enable PDF text extraction]',
+                    mimeType: binaryMimeType,
+                    size,
+                };
+            });
+        }
+        if (binaryMimeType) {
+            const cap = inlineCapForMime(binaryMimeType);
+            if (cap !== null && size <= cap) {
+                const bytes = await this.#readAll(abs, size, uri, tooLarge);
+                return { text: '', mimeType: binaryMimeType, size, bytes: bytes.toString('base64') };
+            }
+            if (cap !== null) {
+                return {
+                    text: `[binary file too large to inline: ${binaryMimeType} ${formatBytes(size)} (cap ${formatBytes(cap)})]`,
+                    mimeType: binaryMimeType,
+                    size,
+                };
+            }
+            // Other binaries (zip, exe, font, …): no text, no bytes — the use-case downgrades to a marker.
+            return { text: '', mimeType: binaryMimeType, size };
+        }
+        const buffer = await this.#readAll(abs, size, uri, tooLarge);
+        try {
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+            if (!looksBinaryContent(text))
+                return { text, size };
+        }
+        catch (error) {
+            if (!(error instanceof TypeError))
+                throw error;
+        }
+        return { text: `[binary or invalid UTF-8 @ ${uri}: ${size} bytes]`, mimeType: 'application/octet-stream', size };
+    }
+    /**
+     * The sync media lane's PDF read (not a kernel port member): the raw bytes'
+     * sha256 and pages `first..last` rendered by the ONE renderer — none when the
+     * hash equals `unlessHash`. `null` when `pdftoppm` is not installed.
+     */
+    async renderPdfPages(uri, opts) {
+        const abs = this.#abs(uri);
+        const st = await this.#statFile(abs, uri);
+        const size = st.size ?? 0;
+        const readCap = maxReadBytes();
+        if (size > readCap)
+            throw new Error(`File too large (${size} bytes, max ${readCap}): "${uri}"`);
+        if (!(await hasPdftoppm()))
+            return null;
+        return this.#withLocalFile(abs, size, uri, async (local) => {
+            const contentHash = createHash('sha256').update(await fs.readFile(local)).digest('hex');
+            if (opts.unlessHash !== undefined && opts.unlessHash === contentHash)
+                return { contentHash, pages: [] };
+            return { contentHash, pages: await pdftoppmPages(local, opts.first, opts.last) };
+        });
+    }
+    async write(uri, content) {
+        const bytes = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
+        await this.#transport.write(this.#abs(uri), bytes);
+        return { uri };
+    }
+    async delete(uri) {
+        await this.#transport.delete(this.#abs(uri));
+    }
+    async move(fromUri, toUri) {
+        await this.#transport.move(this.#abs(fromUri), this.#abs(toUri));
+        return { uri: toUri, previousUri: fromUri };
+    }
+    async mkdir(uri) {
+        await this.#transport.mkdir(this.#abs(uri));
+    }
+    async rmdir(uri) {
+        await this.#transport.rmdir(this.#abs(uri));
+    }
+    async walk(rootUri, opts) {
+        return (await this.#walk(rootUri, opts, false)).items;
+    }
+    /** `complete` proves absence; `walkWithStatus` exists on BOTH transports (the export's verifier reads it). */
+    async walkWithStatus(rootUri, opts) {
+        return this.#walk(rootUri, opts, true);
+    }
+    async #walk(rootUri, opts, diagnostic) {
+        // A trailing slash on the walk root never seeds a `//` into child uris.
+        const base = this.#rel(rootUri);
+        const positive = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0 ? Math.min(Math.floor(n), DEFAULT_MAX_SCAN_FILES) : undefined;
+        const maxItems = positive(opts?.maxItems) ?? (diagnostic ? DEFAULT_MAX_SCAN_FILES : 500);
+        const maxEntries = positive(opts?.maxEntries) ?? positive(opts?.maxItems) ?? 500;
+        let result;
+        try {
+            result = await this.#transport.walk(this.#abs(this.#toUri(base)), {
+                maxItems,
+                ...(diagnostic ? { maxEntries } : {}),
+                // No default excludes — a walk is the physical tree.
+                ...(opts?.excludeGlobs?.length ? { excludeGlobs: opts.excludeGlobs } : {}),
+            });
+        }
+        catch (error) {
+            if (diagnostic || isSkippableFsError(error))
+                return { items: [], complete: false, truncated: false };
+            throw error;
+        }
+        return {
+            items: result.entries.map((entry) => ({
+                uri: this.#toUri(_a.#join(base, entry.rel)),
+                name: entry.name,
+                isDirectory: entry.isDirectory,
+                ...(entry.size === undefined ? {} : { size: entry.size }),
+                ...(entry.modifiedAt ? { modifiedAt: entry.modifiedAt } : {}),
+            })),
+            complete: result.complete,
+            truncated: result.truncated,
+        };
+    }
+    #countKey(rootUri, opts) {
+        const cap = typeof opts?.maxScanFiles === 'number' && opts.maxScanFiles > 0 ? opts.maxScanFiles : DEFAULT_MAX_SCAN_FILES;
+        return `${rootUri}::${(opts?.excludeGlobs ?? []).join('|')}::${cap}`;
+    }
+    #countTtl() {
+        return getBrainConfigNumber('brainCountCacheTtlMs', undefined, COUNT_CACHE_TTL_MS);
+    }
+    /** Bounded: past `MAX_COUNT_CACHE_ENTRIES` the oldest goes. An expired entry stays as the stale answer. */
+    #rememberCount(key, entry) {
+        this.#countCache.delete(key);
+        if (this.#countCache.size >= MAX_COUNT_CACHE_ENTRIES)
+            this.#countCache.delete(this.#countCache.keys().next().value);
+        this.#countCache.set(key, { ...entry, ts: Date.now() });
+    }
+    /** The last `count` for the same root and options while younger than the TTL — never I/O. */
+    peekCount(rootUri, opts) {
+        const cached = this.#countCache.get(this.#countKey(rootUri, opts));
+        if (!cached || Date.now() - cached.ts >= this.#countTtl())
+            return undefined;
+        return cached.value;
+    }
+    /**
+     * Fresh ⇒ the cached total, or the cached FAILURE rethrown at once (a walk
+     * that failed or timed out is not tried again within the TTL; a total from
+     * before it is still answered). Expired with a total ⇒ that stale total AT
+     * ONCE while one walk refreshes it. Otherwise ⇒ the walk's answer.
+     * Concurrent callers of one key share ONE walk.
+     */
+    async count(rootUri, opts) {
+        const key = this.#countKey(rootUri, opts);
+        const cached = this.#countCache.get(key);
+        if (cached && Date.now() - cached.ts < this.#countTtl()) {
+            if (cached.value !== undefined)
+                return cached.value;
+            throw cached.error;
+        }
+        const walk = this.#countWalk(key, rootUri, opts);
+        if (cached?.value === undefined)
+            return walk;
+        // The stale total answers this call; the walk's outcome (total or failure) is remembered for the next.
+        walk.catch(() => undefined);
+        return cached.value;
+    }
+    #countWalk(key, rootUri, opts) {
+        const running = this.#countWalks.get(key);
+        if (running)
+            return running;
+        const cap = typeof opts?.maxScanFiles === 'number' && opts.maxScanFiles > 0 ? opts.maxScanFiles : DEFAULT_MAX_SCAN_FILES;
+        const walk = (async () => {
+            let total;
+            try {
+                total = await this.#transport.count(this.#abs(rootUri), {
+                    maxScanFiles: cap,
+                    ...(opts?.excludeGlobs?.length ? { excludeGlobs: opts.excludeGlobs } : {}),
+                });
+            }
+            catch (error) {
+                if (isSkippableFsError(error))
+                    return 0;
+                const before = this.#countCache.get(key)?.value;
+                this.#rememberCount(key, { error, ...(before !== undefined ? { value: before } : {}) });
+                throw error;
+            }
+            this.#rememberCount(key, { value: total });
+            return total;
+        })().finally(() => { this.#countWalks.delete(key); });
+        this.#countWalks.set(key, walk);
+        return walk;
+    }
+    async scanContent(rootUri, query, opts) {
+        if (!query)
+            return [];
+        const base = this.#rel(rootUri);
+        const maxMatches = typeof opts?.maxMatches === 'number' && opts.maxMatches > 0 ? opts.maxMatches : 500;
+        let matches;
+        try {
+            matches = await this.#transport.scanContent(this.#abs(rootUri), query, {
+                maxMatches,
+                ...(opts?.caseSensitive !== undefined ? { caseSensitive: opts.caseSensitive } : {}),
+                ...(opts?.includeGlobs?.length ? { includeGlobs: opts.includeGlobs } : {}),
+                ...(opts?.excludeGlobs?.length ? { excludeGlobs: opts.excludeGlobs } : {}),
+            });
+        }
+        catch (error) {
+            if (isSkippableFsError(error))
+                return [];
+            throw error;
+        }
+        return matches.map((match) => ({
+            uri: this.#toUri(_a.#join(base, match.rel)),
+            line: match.line,
+            ...(match.column !== undefined ? { column: match.column } : {}),
+            preview: match.preview,
+        }));
+    }
+    /**
+     * Change events under `rootUri` from a watcher on the folder's own machine
+     * (this process's `FsWatchHub`, or the device's broker over its link, re-opened
+     * on loss with ONE `overflow {watcher_restarted}`). An `overflow` means event
+     * delivery can no longer be trusted — the consumer reconciles the source.
+     */
+    subscribeEvents(rootUri, listener, opts) {
+        const watch = this.#transport.watch(this.#abs(rootUri), (event) => {
+            if (event.kind === 'overflow') {
+                listener({
+                    kind: 'overflow',
+                    uri: `${this.source}://`,
+                    ...(event.at ? { modifiedAt: event.at } : {}),
+                    ...(event.reason ? { reason: event.reason } : {}),
+                    ...(event.code ? { code: event.code } : {}),
+                });
+                return;
+            }
+            const uri = this.#uriOfPath(this.#path.normalize(event.path));
+            if (!uri || uri === `${this.source}://`)
+                return;
+            listener({ kind: event.kind, uri, ...(event.at ? { modifiedAt: event.at } : {}), ...(event.entry ? { entry: event.entry } : {}) });
+        }, {
+            ...(opts?.excludeGlobs?.length ? { excludeGlobs: opts.excludeGlobs } : {}),
+            ...(opts?.maxFolders !== undefined ? { maxFolders: opts.maxFolders } : {}),
+        });
+        return { unsubscribe: () => watch.unsubscribe(), watchState: () => watch.watchState() };
+    }
+    async scanDelta(request) {
+        request.signal?.throwIfAborted();
+        const rootUri = request.rootUri ?? `${this.source}://`;
+        const base = this.#rel(rootUri);
+        const cap = typeof request.maxScanFiles === 'number' && request.maxScanFiles > 0 ? request.maxScanFiles : DEFAULT_MAX_SCAN_FILES;
+        const result = await this.#transport.scanDelta(this.#abs(rootUri), {
+            maxScanFiles: cap,
+            ...(request.since !== undefined ? { since: request.since } : {}),
+            ...(request.excludeGlobs?.length ? { excludeGlobs: request.excludeGlobs } : {}),
+            ...(request.includeInventory ? { includeInventory: true } : {}),
+            ...(request.signal ? { signal: request.signal } : {}),
+        });
+        request.signal?.throwIfAborted();
+        const toItem = (entry) => ({
+            uri: this.#toUri(_a.#join(base, entry.rel)),
+            name: entry.name,
+            ...(entry.size === undefined ? {} : { size: entry.size }),
+            ...(entry.modifiedAt ? { modifiedAt: entry.modifiedAt } : {}),
+        });
+        return {
+            files: result.files.map(toItem),
+            checkpoint: result.checkpoint,
+            truncated: result.truncated,
+            ...(result.inventory ? { inventory: result.inventory.map(toItem) } : {}),
+        };
+    }
+    /**
+     * The machine path of `uri` (`os_uri`): the device's own path for a device
+     * folder, the native path, or a Docker mount's host half. Inside Docker with
+     * no host pair it THROWS `OsUriUnresolvableError` — never a container path.
+     */
+    resolveOsUri(uri) {
+        const rest = this.#rest(uri);
+        const fast = rest && this.#osBase !== undefined ? this.#under(this.#osBase, rest) : undefined;
+        if (fast !== undefined)
+            return fast;
+        const abs = this.#abs(uri);
+        if (this.#osRoot === undefined)
+            throw new OsUriUnresolvableError({ source: this.source, uri, root: this.#root });
+        if (this.#osRoot === this.#root)
+            return abs;
+        const rel = abs === this.#root ? '' : this.#path.relative(this.#root, abs);
+        return rel ? this.#path.join(this.#osRoot, rel) : this.#osRoot;
+    }
+    /**
+     * The package-byte reader of ONE package folder (`folder` is source-relative,
+     * `isPackageFolderPath`). Every path must lie inside `<root>/<folder>` —
+     * judged lexically in the folder's own flavour before any call, then by the
+     * transport's clamp. Nothing is cached or copied: `readText`/`readBytes` are
+     * one bounded read each, `list`/`stat` one call each; `available()` is the
+     * transport's (the live link table, no RPC); `watch` rides this folder's own
+     * watch plus — on a device — the link's come-and-go.
+     */
+    packageReader(folder, onReachabilityChange) {
+        if (!isPackageFolderPath(folder)) {
+            throw new Error(`[brain-core] source "${this.source}": package folder ${JSON.stringify(folder)} is not a source-relative folder.`);
+        }
+        const p = this.#path;
+        const sourceRoot = this.#root;
+        const transport = this.#transport;
+        const root = folder ? p.join(sourceRoot, ...folder.split('/')) : sourceRoot;
+        const inside = (target) => {
+            const normal = p.normalize(target);
+            if (normal !== root && !isPathInside(root, normal, p))
+                throw new Error('[brain-core] a package path left its package folder.');
+            return normal;
+        };
+        const readWhole = async (target, maxBytes) => {
+            const abs = inside(target);
+            const cap = Math.max(0, Math.min(Math.floor(maxBytes), PACKAGE_FILE_MAX_BYTES));
+            const st = await transport.stat(abs);
+            if (!st || st.isDirectory)
+                throw new Error('[brain-core] a package file is missing.');
+            const size = st.size ?? 0;
+            if (size > cap)
+                throw new Error(`[brain-core] a package file is ${size} bytes, over the ${cap}-byte read limit.`);
+            return this.#readAll(abs, size, this.#uriOfPath(abs) ?? this.source, () => new Error(`[brain-core] a package file grew past the ${cap}-byte read limit.`));
+        };
+        const reader = {
+            // Per SOURCE: every uri names its source, so two sources on one folder are two readers.
+            id: `${transport.id}:${encodeURIComponent(this.source)}:${root}`,
+            transport: transport.kind,
+            readText: async (target) => (await readWhole(target, PACKAGE_FILE_MAX_BYTES)).toString('utf-8'),
+            readBytes: async (target, maxBytes) => {
+                const bytes = await readWhole(target, maxBytes);
+                return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length);
+            },
+            list: async (dir) => (await transport.list(inside(dir)))
+                .map((e) => ({ name: e.name, isDirectory: e.isDirectory, isFile: !e.isDirectory })),
+            stat: async (target) => transport.stat(inside(target)),
+            uriOf: (target) => {
+                try {
+                    return this.#uriOfPath(inside(target));
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            available: () => transport.available(),
+            watch: (onChange) => {
+                const watch = this.subscribeEvents(this.#toUri(folder), () => onChange(), {
+                    excludeGlobs: PACKAGE_WATCH_EXCLUDES,
+                    maxFolders: PACKAGE_FOLDER_WATCH_MAX_FOLDERS,
+                });
+                const unlink = onReachabilityChange?.(onChange);
+                return () => { unlink?.(); watch.unsubscribe(); };
+            },
+        };
+        return { root, reader };
+    }
+}
+_a = HostConnector;
+/**
+ * An in-process `host` connector over `root` on this machine. `osRoot` is the
+ * root as the machine's user sees it: natively the root itself, in Docker the
+ * stored `hostRoot` or the os-mount pair's host half (absent ⇒ `resolveOsUri`
+ * throws, never a container path).
+ */
+export function inProcessHostConnector(input) {
+    const root = path.resolve(input.root);
+    return new HostConnector({
+        source: input.source,
+        root,
+        transport: new InProcessTransport(root),
+        ...(input.osRoot !== undefined ? { osRoot: path.resolve(input.osRoot) } : {}),
+    });
+}
+/**
+ * The device half of a `host` source: the stored `root` must be absolute ON
+ * THAT DEVICE — its flavour is its own shape (`C:\…` Windows, `/…` POSIX; a
+ * drive-relative `C:x` or a UNC share is refused) — and the device's transport
+ * comes from agent-core. A root whose shape contradicts the platform the device
+ * claimed is refused by agent-core (`openTransport`).
+ */
+export function deviceHostRoot(source, rawRoot) {
+    const raw = typeof rawRoot === 'string' ? rawRoot : '';
+    const isWindows = /^[A-Za-z]:[\\/]/.test(raw);
+    const root = isWindows ? windowsRoot(raw) : /^\/+$/.test(raw) ? '/' : raw.replace(/\/+$/, '');
+    if (!(isWindows ? root : root.startsWith('/'))) {
+        throw new Error(`[brain-core] device folder "${source}": config.root must be an absolute path on that device, got ${JSON.stringify(rawRoot)}`);
+    }
+    return root;
+}
+/**
+ * The `host` kind's factory — ONE connector class; the STORED config picks the
+ * transport (the kernel's `sourcePlane` reads the same field). A device folder
+ * without agent-core loaded cannot be served — the binding fails and the source
+ * reads as unavailable.
+ */
+export const createHostConnector = (ctx) => {
+    const cfg = ctx.config;
+    if (sourcePlane(HOST_SOURCE_KIND, ctx.config) === 'device') {
+        const state = ctx.packageState();
+        const devices = state.ctx?.packages?.getPackageApi('@neuralis/agent-core')?.devices;
+        if (!devices)
+            throw new Error(`[brain-core] device folder "${ctx.source}": the device plane (agent-core) is not loaded.`);
+        const root = deviceHostRoot(ctx.source, cfg.root);
+        // A PROJECT-scope folder carries its project: agent-core re-asks, at every
+        // use, whether the device's owner still holds `device.own` there.
+        const transport = devices.openTransport({
+            source: ctx.source,
+            device: String(cfg.device),
+            root,
+            ...(ctx.scope.kind === 'project' ? { project: { projectId: ctx.projectId } } : {}),
+        });
+        return new HostConnector({ source: ctx.source, root, transport, osRoot: root });
+    }
+    if (typeof cfg.root !== 'string' || cfg.root.length === 0) {
+        throw new Error(`[brain-core] host source "${ctx.source}": config.root is required.`);
+    }
+    const isDocker = detectDocker();
+    const { resolvedRoot } = resolveLocalRoot({
+        configured: cfg.root,
+        hostRoot: cfg.hostRoot,
+        projectRoot: ctx.projectRoot ?? '',
+        isDocker,
+        source: ctx.source,
+    });
+    // In a container the machine half is the stored `hostRoot`, else the
+    // `NEURALIS_MOUNT_*` os-mount pair's; natively it IS the resolved root, so an
+    // `os_uri` never names a path a moved home left behind.
+    const osRoot = isDocker
+        ? (typeof cfg.hostRoot === 'string' ? cfg.hostRoot : undefined) ?? deriveHostRootFromOsMounts(resolvedRoot, discoverOsMounts(process.env))
+        : resolvedRoot;
+    return inProcessHostConnector({ source: ctx.source, root: resolvedRoot, ...(osRoot !== undefined ? { osRoot } : {}) });
+};
+//# sourceMappingURL=HostConnector.js.map