@leu2m/semantic-search 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leu2m
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @leu2m/semantic-search
+
+Source-oriented retrieval infrastructure for independent host products. Sources supply documents; ordinary code recognizes file types, parses structure, chunks content, narrows a catalog and returns ranked evidence with provenance. Vector and Nexus can consume the same API without either product owning the engine.
+
+**Status: `0.1.0-alpha.5`, ready for experimental use.** Lexical, semantic and hybrid retrieval are implemented. Sources are parsed into chunks and a deterministic catalog. Optional storage persists records and vectors; MiniLM or a custom embedder generates vectors with exact-input reuse across refreshes, renames and restart. Search now supports exact cosine and lexical/semantic Reciprocal Rank Fusion (RRF), with full provenance. Core remains host-neutral and imports no model runtime.
+
+## Install
+
+The repository provides an ESM package with TypeScript declarations. Requires Node 20+ for the filesystem adapter. It is not yet published to npm.
+
+```sh
+npm install git+ssh://git@github.com/leu2m/semantic-search.git#main
+```
+
+Pin a commit instead of `main` for reproducible consumption. Git installation builds the package through `prepare`. For a local checkout, run `npm ci`, `npm run build`, then `npm pack`; install the resulting tarball in the consumer. Registry publication is a later release step. Built-package core consumers do not install Transformers.js automatically. Git/source builds install development dependencies, including the runtime for typechecking; use a built tarball when those build dependencies are unwanted.
+
+## Use
+
+```ts
+import { SemanticSearchEngine, createSearchSession } from '@leu2m/semantic-search';
+import { FileSystemFolderSource } from '@leu2m/semantic-search/filesystem';
+
+// The host obtains approval/configuration for this root before registering it.
+const source = new FileSystemFolderSource({
+  id: 'project',
+  root: configuredAbsoluteRoot,
+});
+const engine = new SemanticSearchEngine();
+engine.addSource(source);
+await engine.initialize();
+
+const run = createSearchSession(engine);
+const results = await run.search({
+  query: 'validateSession',
+  sources: ['project'],
+  filters: { extensions: ['.ts'] },
+  limit: 8,
+});
+// Each hit includes sourceId, documentId, chunkId, URI, lines and snippet.
+// After host-observed changes:
+await engine.refreshSource('project');
+```
+
+`search({ query, mode?, sources?, filters?, limit? })` is one retrieval API:
+
+| Mode | Behavior |
+| --- | --- |
+| `lexical` | Existing filename/code-symbol/content scoring; never calls `embedQuery`. |
+| `semantic` | Requires an embedder; exact cosine over eligible stored vectors. |
+| `hybrid` | Requires an embedder; complete lexical/semantic rankings fused with RRF, k=60. |
+
+Omitted mode defaults to **hybrid with an embedder**, otherwise lexical. This deliberately changes Alpha.3's embedder-enabled default; request `mode: 'lexical'` to retain it. `engine.defaultMode` exposes the effective default. Explicit semantic/hybrid requests without an embedder fail.
+
+Filters narrow sources, folders, extensions, dates, tags and outgoing links **before ranking**. The final limit applies after fusion. Channel ranks and `combinedRank` are one-based positions, not confidence scores; match reasons identify lexical/semantic evidence. A bounded run cache includes effective mode and avoids repeated query inference. See the [retrieval decision](docs/decisions/0002-retrieval-modes.md) for consistency and cache semantics.
+
+## Sources and extension points
+
+- `SearchSource`: host-supplied `list` and `read`; document IDs are scoped by source ID. An Obsidian vault adapter belongs in the host and can enrich metadata without importing Obsidian into this package.
+- `FileSystemFolderSource`: recursive, explicitly registered root; no symlinks followed in this release. Containment and file identity are checked on reads. It refuses unknown types, oversized files and invalid UTF-8/binary contents. It does not install watchers: hosts call `refreshSource` after changes or use their own debounced watcher.
+- `ParserRegistry`: register custom parsers and, for additional formats, a shared `FileTypeRegistry`. Missing parsers can fall back to text only when the definition permits it. Default parsers cover Markdown, text, generic code and structured configuration as text.
+- `Embedder` and `IndexStorage`: independent optional engine options. Use neither for lexical memory indexing, storage alone for persisted lexical records, an embedder alone for in-process vectors, or both for restart reuse. Hosts own storage locations and model/worker execution.
+- `MiniLMEmbedder`: optional portable `/minilm` export using an exact optional Transformers.js peer; never imported by core.
+- `FileIndexStorage`: atomic JSON persistence available only from the Node-only `filesystem` export; supply an absolute file path whose parent directory already exists.
+
+The [canonical generated file table](docs/file-types.md) covers Markdown/text, JS/TS, common programming languages, web/style files, JSON/YAML/TOML, shell and SQL. No binary extraction is implemented.
+
+## Optional persistence and vectors
+
+```ts
+// These are host implementations of the exported contracts, not package factories.
+const engine = new SemanticSearchEngine({ storage: myIndexStorage, embedder: myEmbedder });
+engine.addSource(mySource);
+await engine.initialize({ signal });
+const report = await engine.refreshSource(mySource.id, { signal });
+// report.embeddedTexts counts new inference inputs; unchanged content needs none.
+```
+
+The same core works with browser sources, IndexedDB-backed host storage and a worker embedder, or with Node/CLI/desktop adapters. The root export never imports those host implementations. Custom parser registries need an explicit behavior version to reuse persisted snapshots. See [integration](docs/integration.md) for configuration and [architecture](docs/architecture.md) for compatibility and transaction details.
+
+## Local embeddings
+
+Install the runtime only when using `/minilm`:
+
+```sh
+npm install @huggingface/transformers@4.2.0
+```
+
+```ts
+import { MiniLMEmbedder } from '@leu2m/semantic-search/minilm';
+const embedder = new MiniLMEmbedder({ device: 'cpu', batchSize: 4 });
+const engine = new SemanticSearchEngine({ embedder, storage: myIndexStorage });
+engine.addSource(mySource);
+try {
+  await engine.initialize();
+  const evidence = await engine.search({ query: 'recover a forgotten password' }); // hybrid
+}
+finally { await embedder.dispose(); } // Host owns lifetime; dispose after all users finish.
+```
+
+Import and construction do not load the runtime or model. First inference lazily loads `Xenova/all-MiniLM-L6-v2` at revision `751bff37182d3f1213fa05d7196b954e230abad9`. Defaults are CPU, fp32, mean pooling and normalized 384-dimensional Float32 vectors. Browser/worker hosts choose `device: 'wasm'` or supported WebGPU, and own execution placement and runtime assets. The adapter implements document and query embeddings; semantic/hybrid search embeds each uncached nonempty query once when eligible chunks exist.
+
+Embedding-input version 1 includes content-derived heading context for continuation chunks without repeating an initial Markdown heading. Paths/URIs do not participate. Schema 3 invalidates older snapshots before reuse; the generic engine sends unique missing inputs once and the adapter owns batching.
+
+| Loading mode | Contract |
+| --- | --- |
+| Online/cached Hub model | Supported; may access the network. |
+| Host-staged local assets | Strict offline supported with host runtime configuration and remote loading disabled. |
+| Hub cache alone + `localFilesOnly` | Not a zero-network guarantee in Transformers.js 4.2.0. |
+
+`cacheDir` is a cache location. `localFilesOnly` forwards a runtime option whose 4.2.0 tokenizer metadata probes can still access the network for Hub IDs. Strict offline deployment uses staged local assets and **host-owned** environment configuration; the adapter never changes global runtime settings. See [integration](docs/integration.md#strict-offline-host-staged-assets) and [ADR 0001](docs/decisions/0001-minilm-loading.md) for the verified limitation, staging layout and ownership rules.
+
+Alpha.5 hardens cache semantics and characterizes quality, scale and portability without changing ranking. See the [release record](docs/alpha5-hardening.md), [public API responsibilities](docs/api.md) and [maintained examples](examples/README.md).
+
+Alpha.6A+B establishes an explicit **retrieval-only answerability boundary**; see the [design record](docs/alpha6-answerability.md) and [chunk evidence traces](docs/alpha6-evidence-traces.md). Results remain unassessed candidates; an empty list does not prove corpus-wide absence. The tested [host example](examples/evidence.mjs) labels both empty and nonempty retrieval as `answerability: 'not-assessed'`, propagates failures and preserves provenance. This is consumer example code, not a new package API. Runtime/ranking is unchanged, so the package stays `0.1.0-alpha.5`; independent Alpha.6C review is next.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run docs:file-types
+npm run benchmark
+npm pack
+```
+
+`npm test` uses deterministic fixtures and does not download/load a model. `npm run benchmark` retains the original lexical/lifecycle baselines and compares all three retrieval modes with deterministic test vectors. The explicit `npm run test:minilm` command may download model assets and separately measures real inference, lifecycle reuse, staged strict offline operation, and the known cache-only limitation. Use the separate `npm run benchmark:minilm` for actual three-mode retrieval quality, or append `-- --staged` after provisioning assets for strict local evaluation. See [evaluation](docs/evaluation.md) for results and individual modes.
+
+The richer Alpha.5 fixture has 64 documents, 72 chunks and 50 queries. On 40 answerable queries, document-level Recall@5/@10 is **0.6417/0.7813 lexical**, **0.8688/0.9479 semantic**, **0.8479/0.9292 hybrid**. Semantic leads on conceptual/noisy queries; hybrid recovers some terminology and multi-document evidence. Every mode returns irrelevant candidates on the ten no-answer/near-miss queries. Ranks are not answer confidence, and no rejection threshold is implemented.
+
+`npm run evaluate` validates representative evaluation offline; `npm run evaluate:minilm -- --staged` measures real quality from provisioned local assets. `npm run benchmark:scale` measures 1k–100k synthetic chunks separately from inference. Real Chrome page/worker core consumption and opt-in MiniLM WASM retrieval passed using installed tarballs and no external requests. Use `npm run test:browser` and `npm run test:browser:minilm` to reproduce after provisioning browser/model assets. See [evaluation](docs/evaluation.md) for all precision/recall/MRR/nDCG class breakdowns, raw chunk coverage and limitations.
+
+On the measured older laptop, 100k unfiltered 384-dimensional candidates took about **0.79 seconds semantic / 1.44 seconds hybrid**. Scope searches and choose host worker placement for interactive workloads. These are observations, not package guarantees. Alpha.5 remains experimental rather than Beta; [next slice](docs/next-slice.md) recommends evidence-driven relevance/answerability design before broader integration.
+
+`npm run evaluate:evidence` exercises the separate Alpha.6 development judgments offline; `npm run evaluate:evidence:minilm -- --staged` measures real chunk/set retrieval on the unchanged corpus. Judgments are authored development evidence, not independent validation. No answerability classifier, public confidence/cosine field, or rejection threshold has been added.
+
+Every change and accepted decision must update the relevant docs and README in the same work. ADRs record durable choices; ignored local planning is supplementary.
+
+## Boundaries and limitations
+
+The core export contains no Node filesystem, Obsidian, Vector or Nexus imports and has zero runtime dependencies. The separate filesystem export is Node-only. Vector's esbuild bundle can consume the ESM core; Nexus's ESM core/daemon can import it directly. There is no unbundled CommonJS `require` export.
+
+The live index remains in memory. Exact semantic ranking costs O(N·D + N log N) for N eligible chunks and D dimensions; hybrid adds O(N log N) fusion and O(N) temporary references, without copying stored vectors. There is no ANN, calibrated confidence, relevance cutoff or large-corpus performance claim. Refresh rescans and parses a source, reusing identical chunk records and exact-content vectors. Compatible persisted records can be reused after restart only after reconciliation with live sources. Failed scans, embeddings or saves preserve the source's last good live index and surface errors; hosts decide when stale results should be disabled. Storage must publish atomically; each successful save precedes the live commit. Markdown recognition is intentionally lightweight, frontmatter is preserved raw, and code parsing is not AST-based. Chunk sizes are soft character targets: a single long line is never cut. Source roots should be curated—there is no automatic ignore-file interpreter or directory exclusion policy.
+
+See [API](docs/api.md), [examples](examples/README.md), [architecture](docs/architecture.md), [integration](docs/integration.md), [evaluation](docs/evaluation.md), [MiniLM loading decision](docs/decisions/0001-minilm-loading.md), and [next slice](docs/next-slice.md). MIT © 2026 leu2m.

package/dist/adapters/file-storage.d.ts

@@ -0,0 +1,8 @@
+import type { IndexSnapshot, IndexStorage, OperationOptions } from '../contracts.js';
+/** Atomic single-writer store at an explicit host-chosen absolute path. Parent must exist. */
+export declare class FileIndexStorage implements IndexStorage {
+    private readonly path;
+    constructor(path: string);
+    load(options?: OperationOptions): Promise<IndexSnapshot | null>;
+    save(snapshot: IndexSnapshot, options?: OperationOptions): Promise<void>;
+}

package/dist/adapters/file-storage.js

@@ -0,0 +1,55 @@
+import { open, readFile, rename, unlink } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Atomic single-writer store at an explicit host-chosen absolute path. Parent must exist. */
+export class FileIndexStorage {
+    path;
+    constructor(path) {
+        this.path = path;
+        if (!isAbsolute(path))
+            throw new Error('An explicit absolute index path is required');
+    }
+    async load(options = {}) {
+        options.signal?.throwIfAborted();
+        try {
+            const text = await readFile(this.path, { encoding: 'utf8', ...options });
+            options.signal?.throwIfAborted();
+            return JSON.parse(text);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async save(snapshot, options = {}) {
+        options.signal?.throwIfAborted();
+        const text = JSON.stringify(snapshot);
+        const temporary = `${this.path}.${randomUUID()}.tmp`;
+        const handle = await open(temporary, 'wx', 0o600);
+        let closed = false;
+        let published = false;
+        try {
+            await handle.writeFile(text, { encoding: 'utf8', ...options });
+            await handle.sync();
+            await handle.close();
+            closed = true;
+            options.signal?.throwIfAborted();
+            // rename is the publication boundary; cancellation after this point is too late.
+            await rename(temporary, this.path);
+            published = true;
+        }
+        finally {
+            try {
+                if (!closed)
+                    await handle.close();
+            }
+            finally {
+                if (!published)
+                    await unlink(temporary);
+            }
+        }
+    }
+}
+//# sourceMappingURL=file-storage.js.map

package/dist/adapters/file-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage.js","sourceRoot":"","sources":["../../src/adapters/file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,8FAA8F;AAC9F,MAAM,OAAO,gBAAgB;IACE;IAA7B,YAA6B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;QACvC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACxF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,UAA4B,EAAE;QACvC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;YACzE,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;YACjC,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACpE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,QAAuB,EAAE,UAA4B,EAAE;QAChE,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAClD,IAAI,MAAM,GAAG,KAAK,CAAC;QAAC,IAAI,SAAS,GAAG,KAAK,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;YAC/D,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,MAAM,GAAG,IAAI,CAAC;YACzD,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;YACjC,iFAAiF;YACjF,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAAC,SAAS,GAAG,IAAI,CAAC;QACvD,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBAAC,IAAI,CAAC,MAAM;oBAAE,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;oBAClC,CAAC;gBAAC,IAAI,CAAC,SAAS;oBAAE,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YAAC,CAAC;QACtD,CAAC;IACH,CAAC;CACF","sourcesContent":["import { open, readFile, rename, unlink } from 'node:fs/promises';\nimport { isAbsolute } from 'node:path';\nimport { randomUUID } from 'node:crypto';\nimport type { IndexSnapshot, IndexStorage, OperationOptions } from '../contracts.js';\n/** Atomic single-writer store at an explicit host-chosen absolute path. Parent must exist. */\nexport class FileIndexStorage implements IndexStorage {\n  constructor(private readonly path: string) {\n    if (!isAbsolute(path)) throw new Error('An explicit absolute index path is required');\n  }\n  async load(options: OperationOptions = {}): Promise<IndexSnapshot | null> {\n    options.signal?.throwIfAborted();\n    try {\n      const text = await readFile(this.path, { encoding: 'utf8', ...options });\n      options.signal?.throwIfAborted();\n      return JSON.parse(text) as IndexSnapshot;\n    } catch (error) {\n      options.signal?.throwIfAborted();\n      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;\n      throw error;\n    }\n  }\n  async save(snapshot: IndexSnapshot, options: OperationOptions = {}): Promise<void> {\n    options.signal?.throwIfAborted();\n    const text = JSON.stringify(snapshot);\n    const temporary = `${this.path}.${randomUUID()}.tmp`;\n    const handle = await open(temporary, 'wx', 0o600);\n    let closed = false; let published = false;\n    try {\n      await handle.writeFile(text, { encoding: 'utf8', ...options });\n      await handle.sync(); await handle.close(); closed = true;\n      options.signal?.throwIfAborted();\n      // rename is the publication boundary; cancellation after this point is too late.\n      await rename(temporary, this.path); published = true;\n    } finally {\n      try { if (!closed) await handle.close(); }\n      finally { if (!published) await unlink(temporary); }\n    }\n  }\n}\n"]}

package/dist/adapters/filesystem.d.ts

@@ -0,0 +1,23 @@
+import type { OperationOptions, SearchSource, SourceDocument, SourceContent } from '../contracts.js';
+import { type FileTypeRegistry } from '../file-types/registry.js';
+export interface FileSystemSourceOptions {
+    id: string;
+    root: string;
+    maxFileBytes?: number;
+    fileTypes?: FileTypeRegistry;
+}
+/** Explicit root only. No symlinks (including internal ones) are followed in this first adapter. */
+export declare class FileSystemFolderSource implements SearchSource {
+    readonly type = "filesystem";
+    readonly id: string;
+    private readonly root;
+    private readonly maxBytes;
+    private readonly fileTypes;
+    private canonicalRoot;
+    constructor(options: FileSystemSourceOptions);
+    private getRoot;
+    private checkedPath;
+    list(options?: OperationOptions): Promise<SourceDocument[]>;
+    read(documentId: string, options?: OperationOptions): Promise<SourceContent>;
+}
+export { FileIndexStorage } from './file-storage.js';

package/dist/adapters/filesystem.js

@@ -0,0 +1,119 @@
+import { lstat, opendir, realpath, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defaultFileTypes } from '../file-types/registry.js';
+/** Explicit root only. No symlinks (including internal ones) are followed in this first adapter. */
+export class FileSystemFolderSource {
+    type = 'filesystem';
+    id;
+    root;
+    maxBytes;
+    fileTypes;
+    canonicalRoot;
+    constructor(options) {
+        if (!options.id.trim() || !isAbsolute(options.root))
+            throw new Error('A source ID and explicit absolute root are required');
+        this.fileTypes = options.fileTypes ?? defaultFileTypes;
+        this.id = options.id;
+        this.root = resolve(options.root);
+        this.maxBytes = options.maxFileBytes ?? 2 * 1024 * 1024;
+        if (!Number.isSafeInteger(this.maxBytes) || this.maxBytes < 1)
+            throw new Error('Invalid file size limit');
+    }
+    async getRoot() {
+        const root = await realpath(this.root);
+        if (!(await lstat(root)).isDirectory())
+            throw new Error('Source root is not a directory');
+        if (this.canonicalRoot && this.canonicalRoot !== root)
+            throw new Error('Source root changed; register it again explicitly');
+        this.canonicalRoot = root;
+        return root;
+    }
+    async checkedPath(id) {
+        if (!id || id.includes('\0') || id.includes('\\') || isAbsolute(id) || id.split('/').some(part => !part || part === '.' || part === '..'))
+            throw new Error('Invalid document path');
+        const root = await this.getRoot();
+        const candidate = resolve(root, id);
+        const inside = relative(root, candidate);
+        if (!inside || inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside))
+            throw new Error('Path escapes source root');
+        let current = root;
+        for (const part of id.split('/')) {
+            current = resolve(current, part);
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error('Symlinks are not followed');
+        }
+        if (await realpath(candidate) !== candidate)
+            throw new Error('Path changed or escaped its root');
+        return candidate;
+    }
+    async list(options = {}) {
+        const root = await this.getRoot();
+        const documents = [];
+        const walk = async (folder) => {
+            options.signal?.throwIfAborted();
+            for await (const entry of await opendir(folder)) {
+                options.signal?.throwIfAborted();
+                if (entry.isSymbolicLink())
+                    continue;
+                const path = resolve(folder, entry.name);
+                const id = relative(root, path).split(sep).join('/');
+                const checked = await this.checkedPath(id);
+                if (entry.isDirectory()) {
+                    await walk(checked);
+                    continue;
+                }
+                const definition = this.fileTypes.get(entry.name);
+                if (!entry.isFile() || !definition?.indexable)
+                    continue;
+                const stat = await lstat(checked);
+                if (!stat.isFile() || stat.size > Math.min(this.maxBytes, definition.maxBytes))
+                    continue;
+                documents.push({ id, sourceId: this.id, uri: pathToFileURL(checked).href, path: id, name: entry.name,
+                    createdAt: stat.birthtimeMs, modifiedAt: stat.mtimeMs });
+            }
+        };
+        await walk(root);
+        return documents.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    async read(documentId, options = {}) {
+        options.signal?.throwIfAborted();
+        const type = this.fileTypes.get(documentId);
+        if (!type?.indexable)
+            throw new Error('Unsupported file type');
+        const path = await this.checkedPath(documentId);
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            const max = Math.min(this.maxBytes, type.maxBytes);
+            if (!stat.isFile() || stat.size > max)
+                throw new Error('File is not indexable or exceeds the size limit');
+            const buffer = new Uint8Array(max + 1);
+            let count = 0;
+            while (count <= max) {
+                options.signal?.throwIfAborted();
+                const { bytesRead } = await handle.read(buffer, count, buffer.length - count, null);
+                if (!bytesRead)
+                    break;
+                count += bytesRead;
+            }
+            if (count > max)
+                throw new Error('File exceeds the size limit');
+            // Recheck containment and identity before returning bytes if the source changed during I/O.
+            const current = await lstat(await this.checkedPath(documentId));
+            const after = await handle.stat();
+            if (current.ino !== stat.ino || current.dev !== stat.dev || after.mtimeMs !== stat.mtimeMs || after.size !== stat.size)
+                throw new Error('File changed while reading; retry');
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, count));
+            if (text.includes('\0'))
+                throw new Error('Binary content is not indexable');
+            return { text };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export { FileIndexStorage } from './file-storage.js';
+//# sourceMappingURL=filesystem.js.map

package/dist/adapters/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../src/adapters/filesystem.ts"],"names":[],"mappings":"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","sourcesContent":["import { lstat, opendir, realpath, open } from 'node:fs/promises';\nimport { constants } from 'node:fs';\nimport { resolve, relative, isAbsolute, sep } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport type { OperationOptions, SearchSource, SourceDocument, SourceContent } from '../contracts.js';\nimport { defaultFileTypes, type FileTypeRegistry } from '../file-types/registry.js';\nexport interface FileSystemSourceOptions { id: string; root: string; maxFileBytes?: number; fileTypes?: FileTypeRegistry; }\n/** Explicit root only. No symlinks (including internal ones) are followed in this first adapter. */\nexport class FileSystemFolderSource implements SearchSource {\n  readonly type = 'filesystem';\n  readonly id: string;\n  private readonly root: string;\n  private readonly maxBytes: number;\n  private readonly fileTypes: FileTypeRegistry;\n  private canonicalRoot: string | undefined;\n  constructor(options: FileSystemSourceOptions) {\n    if (!options.id.trim() || !isAbsolute(options.root)) throw new Error('A source ID and explicit absolute root are required');\n    this.fileTypes = options.fileTypes ?? defaultFileTypes;\n    this.id = options.id; this.root = resolve(options.root); this.maxBytes = options.maxFileBytes ?? 2 * 1024 * 1024;\n    if (!Number.isSafeInteger(this.maxBytes) || this.maxBytes < 1) throw new Error('Invalid file size limit');\n  }\n  private async getRoot(): Promise<string> {\n    const root = await realpath(this.root);\n    if (!(await lstat(root)).isDirectory()) throw new Error('Source root is not a directory');\n    if (this.canonicalRoot && this.canonicalRoot !== root) throw new Error('Source root changed; register it again explicitly');\n    this.canonicalRoot = root; return root;\n  }\n  private async checkedPath(id: string): Promise<string> {\n    if (!id || id.includes('\\0') || id.includes('\\\\') || isAbsolute(id) || id.split('/').some(part => !part || part === '.' || part === '..')) throw new Error('Invalid document path');\n    const root = await this.getRoot(); const candidate = resolve(root, id);\n    const inside = relative(root, candidate);\n    if (!inside || inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside)) throw new Error('Path escapes source root');\n    let current = root;\n    for (const part of id.split('/')) { current = resolve(current, part); if ((await lstat(current)).isSymbolicLink()) throw new Error('Symlinks are not followed'); }\n    if (await realpath(candidate) !== candidate) throw new Error('Path changed or escaped its root');\n    return candidate;\n  }\n  async list(options: OperationOptions = {}): Promise<SourceDocument[]> {\n    const root = await this.getRoot(); const documents: SourceDocument[] = [];\n    const walk = async (folder: string): Promise<void> => {\n      options.signal?.throwIfAborted();\n      for await (const entry of await opendir(folder)) {\n        options.signal?.throwIfAborted(); if (entry.isSymbolicLink()) continue;\n        const path = resolve(folder, entry.name); const id = relative(root, path).split(sep).join('/');\n        const checked = await this.checkedPath(id);\n        if (entry.isDirectory()) { await walk(checked); continue; }\n        const definition = this.fileTypes.get(entry.name);\n        if (!entry.isFile() || !definition?.indexable) continue;\n        const stat = await lstat(checked); if (!stat.isFile() || stat.size > Math.min(this.maxBytes, definition.maxBytes)) continue;\n        documents.push({ id, sourceId: this.id, uri: pathToFileURL(checked).href, path: id, name: entry.name,\n          createdAt: stat.birthtimeMs, modifiedAt: stat.mtimeMs });\n      }\n    };\n    await walk(root); return documents.sort((a, b) => a.id.localeCompare(b.id));\n  }\n  async read(documentId: string, options: OperationOptions = {}): Promise<SourceContent> {\n    options.signal?.throwIfAborted();\n    const type = this.fileTypes.get(documentId); if (!type?.indexable) throw new Error('Unsupported file type');\n    const path = await this.checkedPath(documentId);\n    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);\n    try {\n      const stat = await handle.stat(); const max = Math.min(this.maxBytes, type.maxBytes);\n      if (!stat.isFile() || stat.size > max) throw new Error('File is not indexable or exceeds the size limit');\n      const buffer = new Uint8Array(max + 1); let count = 0;\n      while (count <= max) {\n        options.signal?.throwIfAborted();\n        const { bytesRead } = await handle.read(buffer, count, buffer.length - count, null);\n        if (!bytesRead) break; count += bytesRead;\n      }\n      if (count > max) throw new Error('File exceeds the size limit');\n      // Recheck containment and identity before returning bytes if the source changed during I/O.\n      const current = await lstat(await this.checkedPath(documentId)); const after = await handle.stat();\n      if (current.ino !== stat.ino || current.dev !== stat.dev || after.mtimeMs !== stat.mtimeMs || after.size !== stat.size) throw new Error('File changed while reading; retry');\n      const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, count));\n      if (text.includes('\\0')) throw new Error('Binary content is not indexable');\n      return { text };\n    } finally { await handle.close(); }\n  }\n}\n\nexport { FileIndexStorage } from './file-storage.js';\n"]}

package/dist/adapters/minilm.d.ts

@@ -0,0 +1,50 @@
+import type { Embedder, OperationOptions } from '../contracts.js';
+export declare const MINILM_DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
+export declare const MINILM_DEFAULT_REVISION = "751bff37182d3f1213fa05d7196b954e230abad9";
+export interface MiniLMEmbedderOptions {
+    /** Custom/local model must produce 384-dimensional sentence embeddings; supply its revision explicitly. */
+    model?: string;
+    revision?: string;
+    batchSize?: number;
+    /** Node default is cpu. Browser/worker hosts select wasm or supported webgpu explicitly. */
+    device?: 'cpu' | 'wasm' | 'webgpu';
+    dtype?: 'fp32' | 'fp16' | 'q8';
+    /** Forwarded to Transformers.js; Hub-ID metadata probes in 4.2.0 may still access the network.
+     * Strict offline operation requires host-staged assets and host env.allowRemoteModels=false.
+     */
+    localFilesOnly?: boolean;
+    /** Passed to the runtime; a populated Hub cache alone does not guarantee offline resolution. */
+    cacheDir?: string;
+    onProgress?: (event: {
+        status: string;
+        file?: string;
+        progress?: number;
+        loaded?: number;
+        total?: number;
+    }) => void;
+}
+/** Optional local sentence embedder. Import/construction never load the runtime or model.
+ * Hosts own placement and disposal. Calls are serialized; cancellation cannot preempt native inference.
+ */
+export declare class MiniLMEmbedder implements Embedder {
+    readonly dimensions = 384;
+    readonly id: string;
+    private readonly options;
+    private readonly model;
+    private readonly revision;
+    private readonly batchSize;
+    private readonly device;
+    private readonly dtype;
+    private extractor;
+    private tail;
+    private disposed;
+    private disposal;
+    constructor(options?: MiniLMEmbedderOptions);
+    private check;
+    private load;
+    embedDocuments(texts: string[], options?: OperationOptions): Promise<Float32Array[]>;
+    embedQuery(text: string, options?: OperationOptions): Promise<Float32Array>;
+    private run;
+    /** Terminal and idempotent. Waits for active work, releases the pipeline; further use rejects. */
+    dispose(): Promise<void>;
+}

package/dist/adapters/minilm.js

@@ -0,0 +1,141 @@
+export const MINILM_DEFAULT_MODEL = 'Xenova/all-MiniLM-L6-v2';
+export const MINILM_DEFAULT_REVISION = '751bff37182d3f1213fa05d7196b954e230abad9';
+const RUNTIME_VERSION = '4.2.0';
+/** Optional local sentence embedder. Import/construction never load the runtime or model.
+ * Hosts own placement and disposal. Calls are serialized; cancellation cannot preempt native inference.
+ */
+export class MiniLMEmbedder {
+    dimensions = 384;
+    id;
+    options;
+    model;
+    revision;
+    batchSize;
+    device;
+    dtype;
+    extractor;
+    tail = Promise.resolve();
+    disposed = false;
+    disposal;
+    constructor(options = {}) {
+        this.options = { ...options };
+        this.model = options.model ?? MINILM_DEFAULT_MODEL;
+        this.revision = options.revision ?? MINILM_DEFAULT_REVISION;
+        this.batchSize = options.batchSize ?? 4;
+        this.device = options.device ?? 'cpu';
+        this.dtype = options.dtype ?? 'fp32';
+        if (!this.model.trim() || !this.revision.trim() || (this.model !== MINILM_DEFAULT_MODEL && !options.revision))
+            throw new Error('A custom MiniLM model requires an explicit revision');
+        if (!Number.isSafeInteger(this.batchSize) || this.batchSize < 1)
+            throw new Error('Invalid MiniLM batch size');
+        if (!['cpu', 'wasm', 'webgpu'].includes(this.device) || !['fp32', 'fp16', 'q8'].includes(this.dtype))
+            throw new Error('Unsupported MiniLM device or dtype');
+        this.id = JSON.stringify({ adapter: 'minilm-v1', runtime: RUNTIME_VERSION, model: this.model, revision: this.revision,
+            device: this.device, dtype: this.dtype, pooling: 'mean', normalize: true, truncation: 'pinned-tokenizer-default' });
+    }
+    check(options) {
+        options.signal?.throwIfAborted();
+        if (this.disposed)
+            throw new Error('MiniLMEmbedder is disposed');
+    }
+    async load(options) {
+        this.check(options);
+        if (!this.extractor) {
+            try {
+                const runtime = await import('@huggingface/transformers');
+                this.check(options);
+                if (runtime.env.version !== RUNTIME_VERSION)
+                    throw new Error(`Expected @huggingface/transformers ${RUNTIME_VERSION}, received ${runtime.env.version}`);
+                const loading = {
+                    revision: this.revision, device: this.device, dtype: this.dtype,
+                    ...(this.options.cacheDir !== undefined ? { cache_dir: this.options.cacheDir } : {}),
+                    ...(this.options.localFilesOnly !== undefined ? { local_files_only: this.options.localFilesOnly } : {}),
+                    ...(this.options.onProgress ? { progress_callback: (event) => this.options.onProgress({
+                            status: event.status,
+                            ...('file' in event ? { file: event.file } : {}),
+                            ...('progress' in event ? { progress: event.progress } : {}),
+                            ...('loaded' in event ? { loaded: event.loaded } : {}),
+                            ...('total' in event ? { total: event.total } : {}),
+                        }) } : {}),
+                };
+                // Avoid factory preflight; the 4.2.0 tokenizer still probes unversioned metadata.
+                // Strict offline hosts stage local assets and configure the runtime globally (see integration docs).
+                const tokenizer = await runtime.AutoTokenizer.from_pretrained(this.model, loading);
+                this.check(options);
+                const model = await runtime.AutoModel.from_pretrained(this.model, loading);
+                try {
+                    this.extractor = new runtime.FeatureExtractionPipeline({ task: 'feature-extraction', tokenizer, model });
+                }
+                catch (cause) {
+                    await model.dispose();
+                    throw cause;
+                }
+                this.options.onProgress?.({ status: 'ready' });
+            }
+            catch (cause) {
+                this.check(options);
+                throw new Error(`MiniLM model load failed (${this.model}@${this.revision}). Install @huggingface/transformers@${RUNTIME_VERSION} and check model/cache availability.`, { cause });
+            }
+        }
+        this.check(options);
+        return this.extractor;
+    }
+    async embedDocuments(texts, options = {}) {
+        this.check(options);
+        if (!Array.isArray(texts) || texts.some(text => typeof text !== 'string'))
+            throw new Error('MiniLM inputs must be strings');
+        const inputs = [...texts];
+        const operationOptions = { ...options };
+        const operation = this.tail.then(() => this.run(inputs, operationOptions));
+        this.tail = operation.then(() => { }, () => { });
+        return operation;
+    }
+    async embedQuery(text, options = {}) {
+        return (await this.embedDocuments([text], options))[0];
+    }
+    async run(texts, options) {
+        this.check(options);
+        if (!texts.length)
+            return [];
+        const extractor = await this.load(options);
+        const vectors = [];
+        for (let start = 0; start < texts.length; start += this.batchSize) {
+            this.check(options);
+            const batch = texts.slice(start, start + this.batchSize);
+            const output = await extractor(batch, { pooling: 'mean', normalize: true });
+            try {
+                this.check(options);
+                const data = output.data;
+                if (output.type !== 'float32' || !(data instanceof Float32Array) || output.dims.length !== 2 ||
+                    output.dims[0] !== batch.length || output.dims[1] !== this.dimensions || data.length !== batch.length * this.dimensions)
+                    throw new Error('Invalid MiniLM output shape/type');
+                for (let row = 0; row < batch.length; row++) {
+                    const vector = data.slice(row * this.dimensions, (row + 1) * this.dimensions);
+                    const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+                    if (!vector.every(Number.isFinite) || Math.abs(norm - 1) > 0.001)
+                        throw new Error('Invalid MiniLM output: expected finite unit vectors');
+                    vectors.push(vector);
+                }
+            }
+            finally {
+                output.dispose();
+            }
+        }
+        this.check(options);
+        return vectors;
+    }
+    /** Terminal and idempotent. Waits for active work, releases the pipeline; further use rejects. */
+    dispose() {
+        if (!this.disposal) {
+            this.disposed = true;
+            this.disposal = this.tail.then(async () => {
+                const extractor = this.extractor;
+                this.extractor = undefined;
+                if (extractor)
+                    await extractor.dispose();
+            });
+        }
+        return this.disposal;
+    }
+}
+//# sourceMappingURL=minilm.js.map