@autorag/librarian 2.13.8 → 2.13.10

package/dist/core.d.ts

@@ -2,6 +2,7 @@ import type { AutoRAGJikjiPrepareResult, AutoRAGRefreshOptions, AutoRAGRefreshRe
 import type { AutoRAGResultsDetails } from "./agent/results.js";
 import { type SearchDocumentsResponse } from "./agent/search-documents.js";
 import { type CliConfig, type ResolveConfigInput } from "./cli/config.js";
+import type { ConvertAndRelateResult, FileeConvertRequest } from "./convert/index.js";
 import type { EverythingSearchRequest, EverythingSearchResult } from "./everything/index.js";
 import type { FSearchSearchRequest, FSearchSearchResult } from "./fsearch/index.js";
 import type { JikjiPrepareOptions } from "./jikji/index.js";
@@ -84,6 +85,10 @@ export declare class AutoRAGLite {
     recordReport(query: string, details: AutoRAGResultsDetails): SearchDocumentsResponse;
     /** Return a detached snapshot of persisted evidence state. */
     getMemorySchema(): MemorySchema;
+    /** Convert files with Filee, then ask Dupey whether each output joins its source's family. */
+    convertFiles(request: FileeConvertRequest, signal?: AbortSignal): Promise<ConvertAndRelateResult>;
+    /** The formats Filee knows, or what one source format can become. */
+    listFileConversions(from?: string, signal?: AbortSignal): Promise<string>;
 }
 /** Resolve the existing CLI config and construct a model-free runtime. */
 export declare function createAutoRAGLite(options?: AutoRAGLiteOptions): AutoRAGLite;

package/dist/core.js

@@ -3668,20 +3668,30 @@ var init_bundle = __esm(() => {
 });
 
 // src/filesystem/path-exclusions.ts
-import { posix as posix2, win32 as win322 } from "node:path";
+import { matchesGlob, posix as posix2, win32 as win322 } from "node:path";
+function isGlobExclusion(entry) {
+  return /[*?[]/u.test(entry);
+}
+function matchesGlobExclusion(path, glob) {
+  const slashed = path.replaceAll("\\", "/");
+  if (matchesGlob(slashed, glob))
+    return true;
+  return glob.startsWith("**/") && matchesGlob(slashed, glob.slice(3));
+}
 function createPathExclusionMatcher(excludedPaths, platform = process.platform) {
   const paths = platform === "win32" ? win322 : posix2;
   const normalize = (path) => {
     const absolute = paths.resolve(path);
     return platform === "win32" ? absolute.toLowerCase() : absolute;
   };
-  const excluded = excludedPaths.map((path) => {
+  const globs = excludedPaths.filter(isGlobExclusion).map((glob) => platform === "win32" ? glob.toLowerCase() : glob);
+  const excluded = excludedPaths.filter((path) => !isGlobExclusion(path)).map((path) => {
     const absolute = normalize(path);
     return { absolute, prefix: absolute.endsWith(paths.sep) ? absolute : `${absolute}${paths.sep}` };
   });
   return (path) => {
     const absolute = normalize(path);
-    return excluded.some((entry) => absolute === entry.absolute || absolute.startsWith(entry.prefix));
+    return excluded.some((entry) => absolute === entry.absolute || absolute.startsWith(entry.prefix)) || globs.some((glob) => matchesGlobExclusion(absolute, glob));
   };
 }
 var init_path_exclusions = () => {};
@@ -7618,6 +7628,34 @@ var init_memory = __esm(() => {
   });
 });
 
+// src/minsync/channel-union.ts
+function unionChannelResults(channels, options = {}) {
+  const byChunk = new Map;
+  const depth = Math.max(0, ...channels.map((channel) => channel.results.length));
+  for (let rank = 0;rank < depth; rank++) {
+    for (const channel of channels) {
+      const result = channel.results[rank];
+      if (result === undefined)
+        continue;
+      const key = `${result.source}\x00${result.id}`;
+      const existing = byChunk.get(key);
+      if (existing === undefined)
+        byChunk.set(key, { result, ranks: { [channel.channel]: rank + 1 } });
+      else
+        existing.ranks[channel.channel] ??= rank + 1;
+    }
+  }
+  const union = [...byChunk.values()].map(({ result, ranks }) => ({
+    ...result,
+    metadata: {
+      ...result.metadata,
+      minsyncChannels: Object.keys(ranks).sort(),
+      minsyncChannelRanks: ranks
+    }
+  }));
+  return options.limit === undefined ? union : union.slice(0, options.limit);
+}
+
 // src/minsync/local-embedder.ts
 import { spawn as spawn11 } from "node:child_process";
 import { request } from "node:http";
@@ -10305,7 +10343,7 @@ var init_cloud = __esm(() => {
 // src/mirror/sync.ts
 import { createHash as createHash11 } from "node:crypto";
 import { opendir, readFile, stat as stat3 } from "node:fs/promises";
-import { basename as basename9, dirname as dirname12, extname as extname6, join as join27, resolve as resolve11, sep as sep6 } from "node:path";
+import { basename as basename9, dirname as dirname12, extname as extname6, join as join27, resolve as resolve11 } from "node:path";
 import { setTimeout as sleep3 } from "node:timers/promises";
 function errorCode(error) {
   if (!(error instanceof Error))
@@ -10852,13 +10890,14 @@ function normalizeExtension2(extension) {
   return lower.startsWith(".") ? lower : `.${lower}`;
 }
 function isPathExcluded(sourcePath, excluded) {
-  if (excluded === undefined)
+  if (excluded === undefined || excluded.size === 0)
     return false;
-  for (const excludedPath of excluded) {
-    if (sourcePath === excludedPath || sourcePath.startsWith(`${excludedPath}${sep6}`))
-      return true;
+  let matcher = matcherBySet.get(excluded);
+  if (matcher === undefined) {
+    matcher = createPathExclusionMatcher([...excluded]);
+    matcherBySet.set(excluded, matcher);
   }
-  return false;
+  return matcher(sourcePath);
 }
 function walkLimits(options) {
   return {
@@ -11025,10 +11064,11 @@ async function collectFiles(state, directory, depth) {
     warnDirectoryUnreadable(state, directory, code);
   }
 }
-var DEFAULT_MAX_SOURCE_BYTES, DEFAULT_MAX_DELETE_RATIO = 0.3, MASS_DELETE_FLOOR = 100, DEFAULT_MAX_SCANNED_ENTRIES = 2000000, DEFAULT_MAX_WALK_DEPTH = 64, DEFAULT_MIRROR_BATCH_SIZE = 25, PRODUCT_ARTIFACT_FILE_NAMES, SKIP_DIR_NAMES, PARSER_FAILURE_MESSAGE = "The registered parser failed on this file; it was skipped during indexing.", PARSER_CRASH_MESSAGE = "The registered parser crashed unexpectedly on this file; it was skipped during indexing.", DEFAULT_TRANSIENT_RETRIES = 3, DEFAULT_TRANSIENT_BACKOFF_MS = 50, TRANSIENT_ERROR_CODES, WORKSPACE_ERROR_CODES, MirrorWorkspaceError, STANDALONE_OCR_IMAGE_EXTENSIONS, SEARCH_ROOT_UNAVAILABLE_MESSAGES;
+var DEFAULT_MAX_SOURCE_BYTES, DEFAULT_MAX_DELETE_RATIO = 0.3, MASS_DELETE_FLOOR = 100, DEFAULT_MAX_SCANNED_ENTRIES = 2000000, DEFAULT_MAX_WALK_DEPTH = 64, DEFAULT_MIRROR_BATCH_SIZE = 25, PRODUCT_ARTIFACT_FILE_NAMES, SKIP_DIR_NAMES, PARSER_FAILURE_MESSAGE = "The registered parser failed on this file; it was skipped during indexing.", PARSER_CRASH_MESSAGE = "The registered parser crashed unexpectedly on this file; it was skipped during indexing.", DEFAULT_TRANSIENT_RETRIES = 3, DEFAULT_TRANSIENT_BACKOFF_MS = 50, TRANSIENT_ERROR_CODES, WORKSPACE_ERROR_CODES, MirrorWorkspaceError, STANDALONE_OCR_IMAGE_EXTENSIONS, matcherBySet, SEARCH_ROOT_UNAVAILABLE_MESSAGES;
 var init_sync = __esm(() => {
   init_cli2();
   init_cloud_placeholder();
+  init_path_exclusions();
   init_source_paths();
   init_binary();
   init_stage();
@@ -11087,6 +11127,7 @@ var init_sync = __esm(() => {
     }
   };
   STANDALONE_OCR_IMAGE_EXTENSIONS = new Set(KORDOC_IMAGE_EXTENSIONS);
+  matcherBySet = new WeakMap;
   SEARCH_ROOT_UNAVAILABLE_MESSAGES = {
     gone: "A search root no longer exists; its previously indexed documents were left untouched.",
     "not-a-directory": "A search root is no longer a directory; its previously indexed documents were left untouched.",
@@ -16161,7 +16202,7 @@ var init_automation_profiles = __esm(() => {
 
 // src/automation/config.ts
 import { existsSync as existsSync19, readFileSync as readFileSync14, realpathSync as realpathSync7 } from "node:fs";
-import { basename as basename10, dirname as dirname15, isAbsolute as isAbsolute8, join as join30, matchesGlob, relative as relative5, resolve as resolve12 } from "node:path";
+import { basename as basename10, dirname as dirname15, isAbsolute as isAbsolute8, join as join30, matchesGlob as matchesGlob2, relative as relative5, resolve as resolve12 } from "node:path";
 function automationsConfigPath(env = process.env) {
   return join30(resolveAutoRAGHome(env), "automations.json");
 }
@@ -16337,9 +16378,9 @@ function deleteAutomation(configPath, id) {
 function globMatches(relPosix, pattern) {
   if (pattern === "**")
     return true;
-  if (matchesGlob(relPosix, pattern))
+  if (matchesGlob2(relPosix, pattern))
     return true;
-  if (pattern.startsWith("**/") && matchesGlob(relPosix, pattern.slice(3)))
+  if (pattern.startsWith("**/") && matchesGlob2(relPosix, pattern.slice(3)))
     return true;
   return false;
 }
@@ -17136,7 +17177,7 @@ var init_permission_judgment = __esm(() => {
 
 // src/agent/permission-gate.ts
 import { statSync as statSync7 } from "node:fs";
-import { isAbsolute as isAbsolute9, relative as relative6, sep as sep7 } from "node:path";
+import { isAbsolute as isAbsolute9, relative as relative6, sep as sep6 } from "node:path";
 import { matchesKey } from "@earendil-works/pi-tui";
 function pathExists(path) {
   try {
@@ -17199,7 +17240,7 @@ class PermissionController {
       if (path === root)
         return true;
       const rel = relative6(root, path);
-      if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep7}`) && !isAbsolute9(rel))
+      if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep6}`) && !isAbsolute9(rel))
         return true;
     }
     return false;
@@ -18651,7 +18692,7 @@ var init_connector = () => {};
 // src/datasource/sidecar/config.ts
 import { readFileSync as readFileSync17 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
-import { dirname as dirname17, isAbsolute as isAbsolute10, join as join34, resolve as resolve14, sep as sep8 } from "node:path";
+import { dirname as dirname17, isAbsolute as isAbsolute10, join as join34, resolve as resolve14, sep as sep7 } from "node:path";
 import { parse as parseToml } from "smol-toml";
 function resolveSidecarOptions(input) {
   const { connector, workspaceRoot } = input;
@@ -18691,7 +18732,7 @@ function archivePathFromCrawlerConfig(input) {
 function expandHome(path) {
   if (path === "~")
     return homedir5();
-  const prefixed = path.startsWith("~/") || sep8 === "\\" && path.startsWith("~\\");
+  const prefixed = path.startsWith("~/") || sep7 === "\\" && path.startsWith("~\\");
   return prefixed ? join34(homedir5(), path.slice(2)) : path;
 }
 var init_config3 = __esm(() => {
@@ -25945,7 +25986,7 @@ import {
   writeFileSync as writeFileSync13
 } from "node:fs";
 import { opendir as opendir2, stat as stat4 } from "node:fs/promises";
-import { basename as basename11, dirname as dirname23, extname as extname8, join as join40, relative as relative7, sep as sep9 } from "node:path";
+import { basename as basename11, dirname as dirname23, extname as extname8, join as join40, relative as relative7, sep as sep8 } from "node:path";
 function errnoCode2(error) {
   const code = error instanceof Error ? error.code : undefined;
   return typeof code === "string" ? code : "UNKNOWN";
@@ -26015,7 +26056,7 @@ async function listVaultNotes(vaultPath) {
   return { notes, unreadableFolders, collisions };
 }
 function toRelative(vaultPath, path) {
-  return relative7(vaultPath, path).split(sep9).join("/").normalize("NFC");
+  return relative7(vaultPath, path).split(sep8).join("/").normalize("NFC");
 }
 function loadStagingState2(statePath) {
   try {
@@ -26099,7 +26140,7 @@ function removeUnexpected(filesRoot, directory, wanted) {
   return removed;
 }
 function toStagedRelative(filesRoot, path) {
-  return relative7(filesRoot, path).split(sep9).join("/").normalize("NFC");
+  return relative7(filesRoot, path).split(sep8).join("/").normalize("NFC");
 }
 var NOTE_EXTENSIONS, SKIPPED_DIRECTORIES, MAX_WALK_DEPTH = 64, VaultUnavailableError;
 var init_staging = __esm(() => {
@@ -28020,7 +28061,7 @@ function resolveExcludePaths(value, origin) {
   if (!Array.isArray(value) || value.some((path) => typeof path !== "string" || path.length === 0)) {
     throw new ConfigError("Config field 'excludePaths' must be a non-empty string array");
   }
-  return resolveSearchPaths(value, origin);
+  return value.map((entry) => isGlobExclusion(entry) ? entry : resolvePersistedPath(entry, origin));
 }
 function resolvePersistedPath(path, origin) {
   return isAbsolute11(path) ? path : resolve15(origin, path);
@@ -29325,6 +29366,7 @@ var init_config5 = __esm(() => {
   init_factory();
   init_embedding();
   init_file_lock();
+  init_path_exclusions();
   init_language();
   init_atomic_write();
   init_rerank();
@@ -38578,7 +38620,7 @@ var init_web_search_tool = __esm(() => {
 // src/agent/agent.ts
 import { randomUUID as randomUUID7 } from "node:crypto";
 import { existsSync as existsSync34, watch as fsWatch, mkdirSync as mkdirSync24, realpathSync as realpathSync8, statSync as statSync11, writeFileSync as writeFileSync17 } from "node:fs";
-import { basename as basename15, dirname as dirname27, join as join55, relative as relative8, resolve as resolve18, sep as sep10 } from "node:path";
+import { basename as basename15, dirname as dirname27, join as join55, relative as relative8, resolve as resolve18, sep as sep9 } from "node:path";
 import { clampThinkingLevel } from "@earendil-works/pi-ai/compat";
 import { getAgentDir as getAgentDir6, keyText } from "@earendil-works/pi-coding-agent";
 function describeDecisionModel(status) {
@@ -38721,6 +38763,7 @@ class AutoRAGAgent {
   reranker;
   rerankTopN;
   minSyncMethod;
+  minSyncSparseMethod;
   minSyncEmbedderConfig;
   minSyncBinaryPath;
   jikjiClient;
@@ -38843,6 +38886,7 @@ class AutoRAGAgent {
       ...this.limits.recordCut === undefined ? {} : { recordCut: this.limits.recordCut }
     };
     this.minSyncMethod = new MinSyncVectorMethod(minSyncDefaults);
+    this.minSyncSparseMethod = isSparseOnlyEmbedder(options.minSync?.embedder) ? undefined : new MinSyncVectorMethod({ ...minSyncDefaults, mode: "sparse" });
     this.methodRegistry.register(new MinSyncHybridMethod(minSyncDefaults));
     const registeredDatasourceIds = new Set;
     for (const skill of this.datasourceSkills) {
@@ -40317,13 +40361,7 @@ Warning: the edited config did not validate, so the previous config was restored
 ${list.map((entry, index) => `[${index + 1}] ${entry}`).join(`
 `)}`;
     const perQuery = await Promise.all(searchQueries.map((searchQuery) => Promise.all([
-      this.searchProgress.track("minsync", "MinSync semantic search", this.minSyncMethod.retrieve(searchQuery, retrieveOptions), {
-        count: (found) => found.length
-      }).catch((error) => {
-        if (error instanceof MinSyncRequiredError)
-          throw error;
-        return [];
-      }),
+      this.prefetchMinSyncCandidates(searchQuery, retrieveOptions),
       Promise.all(datasources.map((datasourceId) => this.searchProgress.track(`datasource:${datasourceId}`, `Datasource ${datasourceId}`, this.searchSingleDatasourceDocuments(datasourceId, searchQuery, {
         topK: this.limits.prefetch.datasourceTopK,
         scope: options.scope,
@@ -40438,6 +40476,30 @@ ${result.content.replace(/\s+/gu, " ")}`).join(`
 
 `);
   }
+  async prefetchMinSyncCandidates(searchQuery, options) {
+    const sparse = this.reranker === undefined ? undefined : this.minSyncSparseMethod;
+    const run = (id, label, method) => this.searchProgress.track(id, label, method.retrieve(searchQuery, options), { count: (found) => found.length }).catch((error) => {
+      if (error instanceof MinSyncRequiredError)
+        throw error;
+      if (sparse !== undefined) {
+        this.routingDiagnostics.push({
+          code: "retrieval-method-failed",
+          severity: "warning",
+          message: `MinSync ${id === "minsync" ? "dense" : "SPLADE"} search failed and its candidates were skipped; the other channel's were used: ${describeRetrievalError(error)}`,
+          source: id
+        });
+      }
+      return [];
+    });
+    const dense = run("minsync", "MinSync semantic search", this.minSyncMethod);
+    if (sparse === undefined)
+      return dense;
+    const [vector, splade] = await Promise.all([dense, run("minsync-sparse", "MinSync SPLADE search", sparse)]);
+    return unionChannelResults([
+      { channel: "vector", results: vector },
+      { channel: "sparse", results: splade }
+    ]);
+  }
   async prefetchWebSearch(searchQuery, signal) {
     const web = this.webSearchOptions;
     if (web === undefined)
@@ -41231,7 +41293,7 @@ ${this.discoveryHint((tools) => `When exploring local files and folders, activel
         return { ok: false, reason: "cloud-root-skipped", stdout: "", stderr: "", code: null };
       }
       const canonicalSourcePath = canonicalPath(sourcePath);
-      const exclude = scope.nestedCloudRoots.map((root) => relative8(canonicalSourcePath, root.path).split(sep10).join("/")).filter((pattern) => pattern !== "" && !pattern.startsWith(".."));
+      const exclude = scope.nestedCloudRoots.map((root) => relative8(canonicalSourcePath, root.path).split(sep9).join("/")).filter((pattern) => pattern !== "" && !pattern.startsWith(".."));
       return client.prepare(sourcePath, { ...options, ...exclude.length === 0 ? {} : { exclude } });
     }));
   }
@@ -41745,6 +41807,8 @@ function toMinSyncReasonDiagnostic(reason) {
   };
 }
 function pinExcludedPath(path) {
+  if (isGlobExclusion(path))
+    return path;
   const resolvedPath = resolve18(path);
   try {
     return join55(realpathSync8(dirname27(resolvedPath)), basename15(resolvedPath));
@@ -41793,6 +41857,7 @@ var init_agent = __esm(() => {
   init_embedding();
   init_everything();
   init_cloud_placeholder();
+  init_path_exclusions();
   init_fsearch();
   init_diagnostics();
   init_jikji();
@@ -41815,6 +41880,7 @@ var init_agent = __esm(() => {
   init_merger();
   init_rerank();
   init_scope();
+  init_skip();
   init_search();
   init_model_auth();
   init_answer_citations();
@@ -41952,6 +42018,12 @@ class AutoRAGLite {
   getMemorySchema() {
     return structuredClone(this.memory.getSchema());
   }
+  convertFiles(request, signal) {
+    return this.agent.convertFiles(request, signal);
+  }
+  listFileConversions(from, signal) {
+    return this.agent.listFileConversions(from, signal);
+  }
 }
 function createAutoRAGLite(options = {}) {
   const input = { flags: options.flags ?? {} };

package/dist/filesystem/path-exclusions.d.ts

@@ -1,2 +1,13 @@
-/** Match exact paths and directory subtrees without matching sibling prefixes. */
+/**
+ * An `excludePaths` entry with `*`, `?` or `[` is a glob over the whole absolute path (`**\/node_modules/**`,
+ * `**\/Downloads/**`, `**\/*.log`); any other entry is a file or directory path. A glob is never resolved against a
+ * directory: it would then stop matching anywhere else.
+ */
+export declare function isGlobExclusion(entry: string): boolean;
+/**
+ * Whether an absolute path matches a glob entry. Separators are compared as `/`, and a leading `**\/` also matches at
+ * the filesystem root, because `matchesGlob("/a.log", "**\/*.log")` differs between platforms in Node 24.
+ */
+export declare function matchesGlobExclusion(path: string, glob: string): boolean;
+/** Match exact paths and directory subtrees without matching sibling prefixes, and glob entries (see {@link isGlobExclusion}). */
 export declare function createPathExclusionMatcher(excludedPaths: readonly string[], platform?: NodeJS.Platform): (path: string) => boolean;

package/dist/find/groups.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The group runners behind `autorag lite find`: one model-free search per
+ * surface — the platform file-name index, local document content, and each
+ * connected datasource, each asked on its own so a slow one never blocks the
+ * rest.
+ */
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { FindGroupDescriptor, FindGroupStatus, FindHit, FindJudge, FindRuntime } from "./types.js";
+/** The result of running one group. */
+export interface FindGroupOutcome {
+    readonly status: FindGroupStatus;
+    readonly hits: readonly FindHit[];
+    readonly error: string | null;
+}
+export interface FindGroupRunner {
+    readonly key: string;
+    readonly descriptor: FindGroupDescriptor;
+    run(): Promise<FindGroupOutcome>;
+}
+export interface BuildGroupRunnersOptions {
+    readonly query: string;
+    readonly topK: number;
+    readonly runtime: FindRuntime;
+    readonly judge?: FindJudge;
+    readonly platform?: NodeJS.Platform;
+    /** Whether the platform file-name index is enabled in config (default true). */
+    readonly fileSearchEnabled?: boolean;
+    /** Whether local semantic search is enabled in config (default true). */
+    readonly semanticEnabled?: boolean;
+    /** The enabled, registered datasources, in config order. */
+    readonly datasources?: readonly FindGroupDescriptor[];
+}
+/** A retrieval result as a datasource hit; exported for tests. */
+export declare function sourceHit(result: RetrievalResult, query: string): FindHit;
+export declare function buildGroupRunners(options: BuildGroupRunnersOptions): FindGroupRunner[];

package/dist/find/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `autorag lite find`: a model-free whole search across the platform file-name
+ * index, local document content, and every connected datasource. Pure and
+ * injectable (runtime, judge); the CLI wires the real ones and prints NDJSON.
+ */
+export { type BuildGroupRunnersOptions, buildGroupRunners, type FindGroupOutcome, type FindGroupRunner, sourceHit, } from "./groups.js";
+export { createRelevanceGate, JEV_RELEVANCE_THRESHOLD, type RelevanceCandidate, type RelevanceGateDeps, type SearchRelevanceGate, } from "./relevance.js";
+export { type FindRunOptions, runFind } from "./run.js";
+export { capContent, contentSnippet, escapeSearchRegex, everythingRegexQuery, fsearchRegexQuery, matchesQueryLexically, SEARCH_HIT_CONTENT_LIMIT, } from "./text.js";
+export type { FindDoneLine, FindGroupDescriptor, FindGroupLine, FindGroupStatus, FindGroupsLine, FindHit, FindJudge, FindJudgment, FindKind, FindLine, FindRuntime, FindSearchAnswer, FindVerdict, } from "./types.js";

package/dist/find/relevance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The relevance gate for the `content` and `source:*` groups.
+ *
+ * A deterministic lexical pass auto-keeps obvious hits; everything else goes to
+ * the decision model as batched `noul` questions, and only candidates with
+ * P(relevant) at or above {@link JEV_RELEVANCE_THRESHOLD} survive, ordered by
+ * probability. When no decision model can answer — the judge throws, or returns
+ * no numeric verdicts — every candidate is kept unfiltered (fail open).
+ */
+import type { FindJudge } from "./types.js";
+/** Minimum judged probability `P(relevant)` required for a non-lexical hit to be shown. */
+export declare const JEV_RELEVANCE_THRESHOLD = 0.5;
+export interface RelevanceCandidate {
+    readonly id: string;
+    readonly sourceLabel: string;
+    readonly title?: string | null;
+    readonly subtitle?: string | null;
+    readonly content: string;
+}
+export interface SearchRelevanceGate {
+    filter<T extends RelevanceCandidate>(query: string, candidates: readonly T[]): Promise<T[]>;
+}
+export interface RelevanceGateDeps {
+    readonly judge: FindJudge;
+    readonly threshold?: number;
+    readonly maxQuestionsPerBatch?: number;
+    readonly maxConcurrentBatches?: number;
+}
+export declare function createRelevanceGate(deps: RelevanceGateDeps): SearchRelevanceGate;

package/dist/find/run.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Orchestrates a whole search: emit the group list immediately, run every group
+ * in parallel, stream one group line per group in completion order, and finish
+ * with the done line. One group throwing never affects the others.
+ */
+import type { FindGroupDescriptor, FindJudge, FindLine, FindRuntime } from "./types.js";
+export interface FindRunOptions {
+    readonly query: string;
+    readonly topK: number;
+    readonly runtime: FindRuntime;
+    readonly judge?: FindJudge;
+    readonly platform?: NodeJS.Platform;
+    readonly fileSearchEnabled?: boolean;
+    readonly semanticEnabled?: boolean;
+    /** The enabled, registered datasources, in config order. */
+    readonly datasources?: readonly FindGroupDescriptor[];
+    /** `--groups` narrowing: run only these keys. */
+    readonly groups?: readonly string[];
+    /** Emit the `groups` line before running. Pass false when the caller already announced it. */
+    readonly announce?: boolean;
+    readonly emit: (line: FindLine) => void;
+    readonly now?: () => number;
+}
+export declare function runFind(options: FindRunOptions): Promise<void>;

package/dist/find/text.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Text helpers for the whole-search groups: the relevance gate's deterministic
+ * lexical pass, the one-line snippet, and the platform file-name regexes.
+ *
+ * The lexical pass is ported from the Finder's `matchesQueryLexicallyOrApprox`
+ * with the approximate edit-distance step dropped, so it stays dependency-free.
+ */
+/** Passed text a hit carries, capped at this many characters. */
+export declare const SEARCH_HIT_CONTENT_LIMIT = 2000;
+/** The passage as one line, cut to {@link SNIPPET_LENGTH} around the first query term that appears in it. */
+export declare function contentSnippet(text: string, query: string): string;
+/** The passage flattened to one line and capped at {@link SEARCH_HIT_CONTENT_LIMIT} characters. */
+export declare function capContent(text: string): string;
+/**
+ * Fast deterministic pass-through before Jev: exact query word match (NFKC
+ * case-folded, ASCII boundary-aware so `_`/`-`/Hangul neighbors work while
+ * partial stems like `art` in `start` do not, plus Korean postposition
+ * stripping like `비행기를` → `비행기`). The approximate edit-distance step the
+ * Finder had is intentionally dropped: this is dependency-free.
+ */
+export declare function matchesQueryLexically(query: string, candidateText: string): boolean;
+/** Escape a literal query so an index's regex mode matches it as a substring. */
+export declare function escapeSearchRegex(text: string): string;
+/**
+ * Regex for the fsearch index. macOS stores Hangul file names decomposed (NFD)
+ * while typed queries are composed (NFC), and the index compares bytes, so a
+ * name matches only when the query uses the same form. Sending both forms as an
+ * alternation finds either spelling; a query that has one form (ASCII) stays the
+ * plain escaped substring.
+ */
+export declare function fsearchRegexQuery(text: string): string;
+/**
+ * Everything's `regex:` search function is the working regex surface on the
+ * bundled ES build. A bare space ends the function's argument, so spaces become
+ * `\x20` to keep a literal substring.
+ */
+export declare function everythingRegexQuery(text: string): string;

package/dist/find/types.d.ts

@@ -0,0 +1,86 @@
+import type { Question } from "jev-use";
+import type { EverythingSearchRequest, EverythingSearchResult } from "../everything/index.js";
+import type { FSearchSearchRequest, FSearchSearchResult } from "../fsearch/index.js";
+import type { RetrievalSelection } from "../retrieval/selection.js";
+import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "../retrieval/types.js";
+/** What a whole-search hit is: a file name, document content, or a datasource message. */
+export type FindKind = "file" | "content" | "message";
+/** One hit on one group, shared by the filename, content, and datasource surfaces. */
+export interface FindHit {
+    readonly id: string;
+    readonly kind: FindKind;
+    readonly title: string;
+    readonly author: string | null;
+    readonly snippet: string;
+    /** Passed text, capped at {@link SEARCH_HIT_CONTENT_LIMIT} characters. */
+    readonly content: string;
+    /** Absolute local path for file and content hits; null for datasource messages. */
+    readonly path: string | null;
+    readonly line: number | null;
+    /** Epoch milliseconds, when the source states one. */
+    readonly timestamp: number | null;
+    readonly url: string | null;
+    readonly score: number | null;
+}
+/** The group list line, printed before any group runs. */
+export interface FindGroupDescriptor {
+    readonly key: string;
+    readonly datasourceId?: string;
+    readonly datasourceType?: string;
+}
+/** `off` = the surface is disabled in config; `unavailable` = its index is not built. */
+export type FindGroupStatus = "ready" | "error" | "off" | "unavailable";
+export interface FindGroupsLine {
+    readonly type: "groups";
+    readonly groups: readonly FindGroupDescriptor[];
+}
+export interface FindGroupLine {
+    readonly type: "group";
+    readonly key: string;
+    readonly status: FindGroupStatus;
+    readonly hits: readonly FindHit[];
+    /** The group's own failure text verbatim, or null. */
+    readonly error: string | null;
+    readonly elapsedMs: number;
+}
+export interface FindDoneLine {
+    readonly type: "done";
+    readonly elapsedMs: number;
+}
+export type FindLine = FindGroupsLine | FindGroupLine | FindDoneLine;
+/** The answer shape `searchSelected` returns; a structural subset of the retrieval engine's. */
+export interface FindSearchAnswer {
+    readonly results: readonly RetrievalResult[];
+    readonly diagnostics: readonly RetrievalDiagnostic[];
+    readonly unsearched: readonly RetrievalUnsearchedSurface[];
+}
+/**
+ * The model-free runtime a whole search drives. `AutoRAGLite` satisfies it
+ * structurally; tests inject a fake. Only these methods are touched, so a
+ * search never enters the model-backed agent loop.
+ */
+export interface FindRuntime {
+    listDatasources(): readonly {
+        readonly datasourceId: string;
+    }[];
+    searchSelected(query: string, selection?: RetrievalSelection, options?: RetrievalOptions): Promise<FindSearchAnswer>;
+    searchFsearch(request: FSearchSearchRequest): Promise<FSearchSearchResult>;
+    searchEverything(request: EverythingSearchRequest): Promise<EverythingSearchResult>;
+}
+/**
+ * One batched `noul` judgment over relevance questions. The real implementation
+ * is `createDecisionModels(...).judge`; a thrown error means "no decision model
+ * can answer", and the gate fails open.
+ */
+export type FindJudge = (state: string, questions: Question[]) => Promise<FindJudgment>;
+/** The verdicts the gate reads; a structural subset of `jev-use`'s `JudgeResult`. */
+export interface FindJudgment {
+    readonly verdicts: readonly FindVerdict[];
+}
+export interface FindVerdict {
+    readonly id: string;
+    readonly type?: string;
+    readonly answer: number | string | null;
+    readonly confidence?: number;
+    readonly escalate?: boolean;
+}