@autorag/librarian 2.0.0

package/dist/jikji/answer-pack.d.ts

@@ -0,0 +1,31 @@
+import type { SourceRoot } from "../filesystem/source-paths.js";
+import type { JikjiAnswerPack } from "./types.js";
+/**
+ * Strict-parse and validate a `jikji find --json` answer-pack from raw stdout.
+ *
+ * Required fields are checked for presence and correct type; the
+ * `candidates[].next_read` and `evidence_pack[].next_read` enums and the
+ * `handoff_action` enum are validated. Extra fields are tolerated. Returns
+ * `undefined` when ANY required field is missing or wrong-typed, or when the
+ * stdout is not valid JSON.
+ */
+export declare function parseJikjiAnswerPack(stdout: string): JikjiAnswerPack | undefined;
+/**
+ * Normalize a path returned in a jikji answer-pack into a REAL absolute path
+ * usable by bash, scoped to one of the configured source roots.
+ *
+ * Accepted forms:
+ * - An absolute path that `realpath`-resolves within a configured root.
+ * - A relative path scoped to a root (resolved against each root in turn).
+ *
+ * Rejected:
+ * - Root escapes (realpath outside every root).
+ * - Windows drive-letter paths (`C:\...`, `C:/...`).
+ * - URL-like values (`https://`, `file://`, `file:foo`).
+ * - Empty / non-string input.
+ *
+ * Duplicate roots (same real path) are deduped: the first matching root wins
+ * and subsequent identical roots are skipped. Output is a real absolute path —
+ * no opaque IDs, no sanitization.
+ */
+export declare function normalizeJikjiAnswerPath(rawPath: string, sourceRoots: readonly SourceRoot[]): string | undefined;

package/dist/jikji/client.d.ts

@@ -0,0 +1,18 @@
+import type { JikjiFindOptions, JikjiFindResult, JikjiOptions, JikjiPrepareOptions, JikjiPrepareResult } from "./types.js";
+export declare class JikjiClient {
+    private readonly options;
+    private resolvedCommand;
+    constructor(options?: JikjiOptions);
+    /**
+     * Resolve the jikji command following the priority chain:
+     * 1. explicit binaryPath
+     * 2. PATH lookup for `jikji`
+     * 3. cached `<root>/.autorag/bin/jikji`
+     * 4. autoInstall (default true) via `cargo install jikji-cli` into the cache
+     * 5. bare `jikji` (spawn-error degrade preserves the previous behavior)
+     * The result is cached per client so a failed install is not retried.
+     */
+    private resolveCommand;
+    prepare(root: string, options?: JikjiPrepareOptions): Promise<JikjiPrepareResult>;
+    find(root: string, query: string, options?: JikjiFindOptions): Promise<JikjiFindResult>;
+}

package/dist/jikji/diagnostics.d.ts

@@ -0,0 +1,26 @@
+import type { JikjiFindResult, JikjiPrepareResult } from "./types.js";
+/**
+ * Diagnostic codes for the optional Jikji indexing/preparation layer. These are
+ * a subset of the search-level diagnostic code union and are intentionally
+ * path-free so they can be surfaced through public search/refresh diagnostics
+ * without leaking filesystem or binary paths.
+ */
+export type JikjiDiagnosticCode = "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed";
+export interface JikjiDiagnostic {
+    readonly code: JikjiDiagnosticCode;
+    readonly severity: "warning" | "error";
+    readonly message: string;
+    readonly source: "jikji";
+}
+/**
+ * Maps a {@link JikjiPrepareResult} to a path-opaque degraded-mode diagnostic.
+ * Successful results map to `undefined`. The message never echoes the binary
+ * path, stderr, or any filesystem path so it is safe for public diagnostics.
+ */
+export declare function jikjiPrepareDiagnostic(result: JikjiPrepareResult): JikjiDiagnostic | undefined;
+/**
+ * Maps a {@link JikjiFindResult} to a path-opaque degraded-mode diagnostic.
+ * Successful results map to `undefined`. The message never echoes the binary
+ * path, stderr, or any filesystem path so it is safe for public diagnostics.
+ */
+export declare function jikjiFindDiagnostic(result: JikjiFindResult): JikjiDiagnostic | undefined;

package/dist/jikji/index.d.ts

@@ -0,0 +1,10 @@
+export { normalizeJikjiAnswerPath, parseJikjiAnswerPack, } from "./answer-pack.js";
+export { JikjiClient } from "./client.js";
+export type { JikjiDiagnostic, JikjiDiagnosticCode } from "./diagnostics.js";
+export { jikjiFindDiagnostic, jikjiPrepareDiagnostic } from "./diagnostics.js";
+export type { EnsureJikjiBinaryOptions, EnsureJikjiBinaryResult, JikjiInstallRunner, JikjiInstallRunResult, } from "./installer.js";
+export { cachedJikjiBinaryPath, ensureJikjiBinary, JIKJI_CRATE_NAME, JIKJI_INSTALL_TIMEOUT_MS, jikjiExecutableName, lookupExecutableInPath, } from "./installer.js";
+export type { JikjiSourceRoot } from "./path-map.js";
+export { mapJikjiPath, planJikjiSourceRoots, resolveReturnedPath } from "./path-map.js";
+export type { JikjiAnswerPack, JikjiCandidate, JikjiEvidence, JikjiFailureReason, JikjiFindOptions, JikjiFindResult, JikjiHandoffAction, JikjiNextRead, JikjiOptions, JikjiPrepareOptions, JikjiPrepareResult, JikjiToolCallPolicy, } from "./types.js";
+export { DEFAULT_JIKJI_OPTIONS } from "./types.js";

package/dist/jikji/installer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Jikji CLI installer. Jikji ships as the `jikji-cli` crate on crates.io
+ * (binary name `jikji`); there are no prebuilt GitHub release binaries, so
+ * installation compiles from source through the user's Rust toolchain.
+ * The binary is cached under `<root>/.autorag/bin` — the same directory the
+ * MinSync installer uses.
+ */
+export declare const JIKJI_CRATE_NAME = "jikji-cli";
+export declare const JIKJI_INSTALL_TIMEOUT_MS: number;
+export declare function jikjiExecutableName(platform?: NodeJS.Platform): string;
+export declare function cargoExecutableName(platform?: NodeJS.Platform): string;
+export declare function cachedJikjiBinaryPath(root: string, platform?: NodeJS.Platform): string;
+/** Resolve an executable from PATH directories. Returns the absolute path of the first match or undefined. */
+export declare function lookupExecutableInPath(executable: string, env: NodeJS.ProcessEnv): string | undefined;
+export interface JikjiInstallRunResult {
+    readonly code: number | null;
+    readonly stderr: string;
+}
+export type JikjiInstallRunner = (args: readonly string[], timeoutMs: number) => Promise<JikjiInstallRunResult>;
+export interface EnsureJikjiBinaryOptions {
+    /** Workspace root; the binary is cached at `<root>/.autorag/bin/jikji`. */
+    readonly root: string;
+    /** crates.io version pin for `jikji-cli`. Defaults to latest. */
+    readonly version?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    /** Injectable process runner for tests. Defaults to spawning `cargo install`. */
+    readonly runner?: JikjiInstallRunner;
+    /** Injectable cargo lookup for tests. Defaults to PATH lookup. */
+    readonly cargoLocator?: (env: NodeJS.ProcessEnv) => string | undefined;
+}
+export type EnsureJikjiBinaryResult = {
+    readonly ok: true;
+    readonly binaryPath: string;
+    readonly source: "cached" | "installed";
+} | {
+    readonly ok: false;
+    readonly reason: "missing-cargo" | "install-failed";
+    readonly message: string;
+};
+/**
+ * Ensure a `jikji` binary exists under `<root>/.autorag/bin`, installing the
+ * `jikji-cli` crate through cargo when missing. Never throws: failures are
+ * reported as degraded results so callers can fall back to raw discovery.
+ */
+export declare function ensureJikjiBinary(options: EnsureJikjiBinaryOptions): Promise<EnsureJikjiBinaryResult>;

package/dist/jikji/path-map.d.ts

@@ -0,0 +1,8 @@
+import { type SourceRoot } from "../filesystem/source-paths.js";
+export interface JikjiSourceRoot extends SourceRoot {
+    readonly searchPath: string;
+}
+export declare function planJikjiSourceRoots(searchPaths: readonly string[]): readonly JikjiSourceRoot[];
+export declare function mapJikjiPath(sourceRoot: SourceRoot, returnedPath: string): string | undefined;
+export declare function resolveReturnedPath(rootPath: string, returnedPath: string): string | undefined;
+export declare function isUnsafeReturnedPath(normalizedPath: string): boolean;

package/dist/jikji/types.d.ts

@@ -0,0 +1,112 @@
+export interface JikjiOptions {
+    readonly binaryPath?: string;
+    /** Workspace root used to cache/auto-install the jikji binary under `.autorag/bin`. */
+    readonly root?: string;
+    /**
+     * When true (default) and no `jikji` binary is found on PATH or in the
+     * `.autorag/bin` cache, install the `jikji-cli` crate from crates.io via
+     * cargo. Set false to disable auto-installation.
+     */
+    readonly autoInstall?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxBufferBytes?: number;
+    readonly includeHidden?: boolean;
+    readonly includeSensitive?: boolean;
+    readonly parseTimeout?: number;
+    readonly maxFiles?: number;
+    readonly exclude?: readonly string[];
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly maxHashBytes?: number;
+    readonly docTextMaxChars?: number;
+    readonly docTextChunkChars?: number;
+    /**
+     * SAFE DEFAULT: AutoRAG passes `--no-agent-rules` to `jikji prepare` so it
+     * NEVER rewrites AGENTS.md/CLAUDE.md/.cursorrules. Set `writeAgentRules: true`
+     * to opt INTO upstream routing-block injection. This is the only way to omit
+     * `--no-agent-rules`.
+     */
+    readonly writeAgentRules?: boolean;
+    /**
+     * @deprecated Kept for back-compat. No longer controls `--no-agent-rules`.
+     * Use `writeAgentRules` instead. The flag is always emitted unless
+     * `writeAgentRules === true`.
+     */
+    readonly noAgentRules?: boolean;
+    readonly enableMediaIndex?: boolean;
+    readonly mediaIndexMaxMb?: number;
+}
+export interface JikjiDefaultOptions {
+    readonly binaryPath: string;
+    readonly timeoutMs: number;
+    readonly maxBufferBytes: number;
+    readonly includeHidden: boolean;
+    readonly includeSensitive: boolean;
+    readonly maxFiles: number;
+    readonly writeAgentRules: boolean;
+    readonly enableMediaIndex: boolean;
+    readonly exclude: readonly string[];
+}
+export declare const DEFAULT_JIKJI_OPTIONS: JikjiDefaultOptions;
+export interface JikjiPrepareOptions {
+    readonly signal?: AbortSignal;
+}
+export type JikjiFailureReason = "aborted" | "nonzero-exit" | "spawn-error" | "stderr-too-large" | "stdout-too-large" | "timeout" | "bad-answer-pack";
+export type JikjiPrepareResult = {
+    readonly ok: true;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+} | {
+    readonly ok: false;
+    readonly reason: JikjiFailureReason;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+};
+export type JikjiNextRead = "cache" | "wiki" | "original" | "none";
+export interface JikjiCandidate {
+    readonly path: string;
+    readonly nextRead: JikjiNextRead;
+    readonly label?: string;
+    readonly score?: number;
+}
+export interface JikjiEvidence {
+    readonly path: string;
+    readonly nextRead: JikjiNextRead;
+}
+export interface JikjiToolCallPolicy {
+    readonly stopAfterFind: boolean;
+    readonly forbiddenTools: readonly string[];
+    readonly allowedFollowups: readonly string[];
+}
+export type JikjiHandoffAction = "direct_use" | "jikji_retry" | "raw_fallback_after_retry";
+export interface JikjiAnswerPack {
+    readonly answerPaths: readonly string[];
+    readonly paths: readonly string[];
+    readonly candidates: readonly JikjiCandidate[];
+    readonly evidencePack: readonly JikjiEvidence[];
+    readonly handoffAction: JikjiHandoffAction;
+    readonly toolCallPolicy: JikjiToolCallPolicy;
+    readonly agentShouldNotRerank: boolean;
+}
+export interface JikjiFindOptions {
+    readonly topK?: number;
+    readonly first?: boolean;
+    readonly fresh?: boolean;
+    readonly autoPrepare?: boolean;
+    readonly staleAfterSeconds?: number;
+    readonly signal?: AbortSignal;
+}
+export type JikjiFindResult = {
+    readonly ok: true;
+    readonly answerPack: JikjiAnswerPack;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+} | {
+    readonly ok: false;
+    readonly reason: JikjiFailureReason;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+};

package/dist/manifest/index.d.ts

@@ -0,0 +1,2 @@
+export { loadManifest, loadManifests } from "./loader.js";
+export type { StoreManifest } from "./types.js";

package/dist/manifest/loader.d.ts

@@ -0,0 +1,3 @@
+import type { StoreManifest } from "./types.js";
+export declare function loadManifest(filePath: string): StoreManifest;
+export declare function loadManifests(dirPath: string): StoreManifest[];

package/dist/manifest/types.d.ts

@@ -0,0 +1,8 @@
+export interface StoreManifest {
+    name: string;
+    description: string;
+    type: "vector" | "bm25" | "hybrid" | "visual";
+    dataDescription: string;
+    contentTypes: string[];
+    config: Record<string, unknown>;
+}

package/dist/memory/check-memory-tool.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { RetrievalMemory } from "./memory.js";
+declare const checkMemorySchema: Type.TObject<{
+    query: Type.TString;
+}>;
+export interface CheckMemoryDetails {
+    signalCount: number;
+    topMethod: string | null;
+    insightCount: number;
+}
+export declare function createCheckMemoryTool(memory: RetrievalMemory): AgentTool<typeof checkMemorySchema, CheckMemoryDetails>;
+export {};

package/dist/memory/index.d.ts

@@ -0,0 +1,5 @@
+export type { CheckMemoryDetails } from "./check-memory-tool.js";
+export { createCheckMemoryTool } from "./check-memory-tool.js";
+export type { MemoryEntry, ResultFeedback, RetrievalInsight, RetrievalMemoryOptions, SearchAttempt } from "./memory.js";
+export { RetrievalMemory } from "./memory.js";
+export { renderMemoryContext } from "./renderer.js";

package/dist/memory/memory.d.ts

@@ -0,0 +1,179 @@
+import { type NormalizedEvidenceRef } from "../retrieval/evidence-id.js";
+export type FeedbackOutcome = "pending" | "useful" | "not_useful";
+export type FeedbackSentiment = "useful" | "not_useful";
+export type FeedbackSignalSource = "explicit" | "followup" | "retry";
+export interface SignalDefaults {
+    readonly explicitWeight: number;
+    readonly followupWeight: number;
+    readonly retryWeight: number;
+    readonly implicitCap: number;
+    readonly decayHalfLifeMs?: number;
+}
+export interface EvidenceChunkRecord extends NormalizedEvidenceRef {
+    readonly excerptHash: string;
+    readonly firstSeenAt: number;
+    readonly lastSeenAt: number;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface CuratedResultRecord {
+    readonly resultId: string;
+    readonly sessionId: string;
+    readonly number: number;
+    readonly query: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly resultHash: string;
+    readonly evidenceIds: readonly string[];
+    readonly createdAt: number;
+}
+export interface FeedbackSignal {
+    readonly id: string;
+    readonly target: {
+        readonly type: "curated_result";
+        readonly resultId: string;
+    } | {
+        readonly type: "evidence_chunk";
+        readonly stableEvidenceId: string;
+    } | {
+        readonly type: "method";
+        readonly method: string;
+    };
+    readonly query: string;
+    readonly method?: string;
+    readonly sentiment: FeedbackSentiment;
+    readonly source: FeedbackSignalSource;
+    readonly weight: number;
+    readonly confidenceCap: number;
+    readonly eventId: string;
+    readonly timestamp: number;
+}
+export interface MethodHint {
+    readonly method: string;
+    readonly score: number;
+    readonly confidence: number;
+    readonly reason: string;
+}
+export interface RetrievalInsight {
+    readonly id: string;
+    readonly clusterKey: string;
+    readonly domain: string;
+    readonly recommendedSources: string[];
+    readonly recommendedMethods: string[];
+    readonly rationale: string;
+    supportingSignalCount: number;
+    confidence: number;
+    readonly createdAt: number;
+    updatedAt: number;
+}
+export interface InsightExtractionSignal {
+    readonly signal: FeedbackSignal;
+    readonly method?: string;
+    readonly source?: string;
+}
+export type InsightExtractor = (signals: readonly InsightExtractionSignal[], now: number) => RetrievalInsight[];
+export interface MemoryWarning {
+    readonly code: string;
+    readonly message: string;
+    readonly timestamp: number;
+}
+export interface MemorySchemaV4 {
+    readonly version: 4;
+    curatedResults: CuratedResultRecord[];
+    evidenceChunks: EvidenceChunkRecord[];
+    feedbackSignals: FeedbackSignal[];
+    readonly signalDefaults: SignalDefaults;
+    warnings: MemoryWarning[];
+    insights: RetrievalInsight[];
+    pendingInsightSignals: InsightExtractionSignal[];
+}
+export interface MemoryEntry {
+    id: string;
+    query: string;
+    method: string;
+    outcome: FeedbackOutcome;
+    timestamp: number;
+    metadata?: {
+        resultCount?: number;
+    };
+}
+export interface SearchAttempt {
+    id: string;
+    query: string;
+    method: string;
+    sources: string[];
+    timestamp: number;
+}
+export interface ResultFeedback {
+    source: string;
+    useful: boolean;
+}
+export interface SessionEvidenceRef extends NormalizedEvidenceRef {
+    readonly metadata?: Record<string, unknown>;
+}
+export interface SessionCuratedResultInput {
+    readonly number: number;
+    readonly title: string;
+    readonly summary: string;
+    readonly content: string;
+    readonly method: string;
+    readonly source: string;
+    readonly evidenceRefs: readonly SessionEvidenceRef[];
+}
+export interface SessionRecordInput {
+    readonly sessionId: string;
+    readonly query: string;
+    readonly results: readonly SessionCuratedResultInput[];
+}
+export interface NumberedFeedbackInput {
+    readonly sessionId: string;
+    readonly query: string;
+    readonly feedback: readonly {
+        readonly number: number;
+        readonly useful: boolean;
+    }[];
+}
+export interface RetrievalMemoryOptions {
+    storagePath: string;
+    insightExtractor?: InsightExtractor;
+}
+export declare class RetrievalMemory {
+    private readonly storagePath;
+    private readonly insightExtractor;
+    private data;
+    private persistedData;
+    private legacyEntries;
+    private legacySourceToAttemptId;
+    constructor(options: RetrievalMemoryOptions);
+    load(): void;
+    save(): void;
+    getSchema(): MemorySchemaV4;
+    getSignalCount(): number;
+    recordCuratedResultsSession(input: SessionRecordInput): void;
+    recordNumberedFeedback(input: NumberedFeedbackInput): boolean;
+    recordWeakSignal(query: string, method: string, source: "followup" | "retry"): void;
+    getMethodHints(query: string): MethodHint[];
+    getInsights(query: string): RetrievalInsight[];
+    getMethodPriority(query: string): Array<{
+        method: string;
+        score: number;
+    }>;
+    append(entry: Omit<MemoryEntry, "id" | "timestamp">): MemoryEntry;
+    getEntries(): readonly MemoryEntry[];
+    registerAttempt(attempt: SearchAttempt): void;
+    recordResultFeedback(feedback: ResultFeedback[]): void;
+    resolvePendingEntries(query: string, method: string | null, outcome: "useful" | "not_useful"): void;
+    recordFeedback(query: string, methodName: string, satisfied: boolean): void;
+    private readPersistedData;
+    private incompatibleMemory;
+    private acquireLock;
+    private mergeWithPersisted;
+    private capData;
+    private extractInsightsFromEvictedSignals;
+    private mergeInsights;
+    private upsertEvidence;
+    private methodForSignal;
+    private sourceForSignal;
+}
+export declare function normalizeSessionEvidenceRef(input: Omit<SessionEvidenceRef, "stableEvidenceId"> & {
+    readonly stableEvidenceId?: string;
+}): SessionEvidenceRef;

package/dist/memory/renderer.d.ts

@@ -0,0 +1,6 @@
+import type { MethodHint, RetrievalInsight } from "./memory.js";
+export declare function renderMemoryContext(hints: readonly MethodHint[], opts?: {
+    maxHints?: number;
+    insights?: readonly RetrievalInsight[];
+    maxInsights?: number;
+}): string;

package/dist/minsync/client.d.ts

@@ -0,0 +1,14 @@
+import type { MinSyncEmbedderConfig, MinSyncQueryHit, MinSyncSyncResult } from "./types.js";
+export interface MinSyncClientOptions {
+    readonly binaryPath: string;
+    readonly workspacePath: string;
+    readonly embedder?: MinSyncEmbedderConfig;
+}
+export declare class MinSyncClient {
+    private readonly binaryPath;
+    private readonly workspacePath;
+    private readonly embedder;
+    constructor(options: MinSyncClientOptions);
+    sync(): Promise<MinSyncSyncResult>;
+    query(text: string, topK: number): Promise<readonly MinSyncQueryHit[]>;
+}

package/dist/minsync/embedder-config.d.ts

@@ -0,0 +1,22 @@
+import type { MinSyncEmbedderConfig } from "./types.js";
+/**
+ * MinSync config.toml lives at `<workspace>/.minsync/config.toml`.
+ * After `minsync init` runs, we rewrite allowlisted embedder fields so
+ * the caller's configuration wins over init defaults.
+ */
+export declare const MINSYNC_CONFIG_DIR = ".minsync";
+export declare const MINSYNC_CONFIG_FILE = "config.toml";
+export declare function minSyncConfigPath(workspacePath: string): string;
+/**
+ * Atomically rewrite allowlisted embedder fields in MinSync config.toml.
+ * Reads the existing file, merges the allowlisted fields from `embedder`,
+ * and writes the result back. Only fields present on `embedder` are applied;
+ * absent fields are left untouched.
+ *
+ * Allowlisted [embedder] fields: id, base_url, query_prefix, passage_prefix,
+ * batch_size, max_retries, max_concurrent, timeout_seconds (from timeoutMs / 1000 ceil).
+ * Dimension is written under [vectorstore.options] as `dimension`.
+ *
+ * Returns true if the file was rewritten, false if the file does not exist.
+ */
+export declare function rewriteEmbedderConfig(workspacePath: string, embedder: MinSyncEmbedderConfig): boolean;

package/dist/minsync/index.d.ts

@@ -0,0 +1,7 @@
+export { MinSyncClient, type MinSyncClientOptions } from "./client.js";
+export { MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, minSyncConfigPath, rewriteEmbedderConfig, } from "./embedder-config.js";
+export { type EnsureMinSyncBinaryOptions, ensureMinSyncBinary, executableName, fetchLatestMinSyncRelease, type InstalledMinSyncBinary, type MinSyncRelease, type MinSyncReleaseAsset, MinSyncReleaseError, selectReleaseAsset, } from "./installer.js";
+export { MinSyncVectorMethod, type MinSyncVectorMethodOptions } from "./method.js";
+export { MINSYNC_FILES_SUBDIR, MINSYNC_SUBDIR, minSyncDocumentPath, minSyncWorkspaceRoot } from "./paths.js";
+export type { MinSyncEmbedderConfig, MinSyncOptions, MinSyncQueryHit, MinSyncSyncResult } from "./types.js";
+export { buildMinSyncPathMap, type MinSyncWorkspaceEntry, type MinSyncWorkspaceSyncResult, syncMinSyncWorkspace, } from "./workspace.js";

package/dist/minsync/installer.d.ts

@@ -0,0 +1,27 @@
+export interface MinSyncReleaseAsset {
+    readonly name: string;
+    readonly downloadUrl: string;
+    readonly sha256?: string;
+}
+export interface MinSyncRelease {
+    readonly tagName: string;
+    readonly assets: readonly MinSyncReleaseAsset[];
+}
+export interface InstalledMinSyncBinary {
+    readonly binaryPath: string;
+    readonly version: string;
+}
+export interface EnsureMinSyncBinaryOptions {
+    readonly root: string;
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: NodeJS.Architecture;
+    readonly releaseProvider?: () => Promise<MinSyncRelease>;
+    readonly assetInstaller?: (asset: MinSyncReleaseAsset, destination: string) => Promise<void>;
+}
+export declare function ensureMinSyncBinary(options: EnsureMinSyncBinaryOptions): Promise<InstalledMinSyncBinary>;
+export declare function fetchLatestMinSyncRelease(): Promise<MinSyncRelease>;
+export declare function selectReleaseAsset(release: MinSyncRelease, platform: NodeJS.Platform, arch: NodeJS.Architecture): MinSyncReleaseAsset;
+export declare function executableName(platform: NodeJS.Platform): string;
+export declare class MinSyncReleaseError extends Error {
+    readonly name = "MinSyncReleaseError";
+}

package/dist/minsync/method.d.ts

@@ -0,0 +1,37 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { type EnsureMinSyncBinaryOptions } from "./installer.js";
+import type { MinSyncEmbedderConfig, MinSyncSyncResult } from "./types.js";
+export interface MinSyncVectorMethodOptions {
+    readonly root: string;
+    readonly binaryPath?: string;
+    readonly workspacePath?: string;
+    readonly installer?: Omit<EnsureMinSyncBinaryOptions, "root">;
+    readonly autoInstall?: boolean;
+    readonly embedder?: MinSyncEmbedderConfig;
+}
+export declare class MinSyncVectorMethod implements RetrievalMethod {
+    private readonly root;
+    private readonly binaryPath;
+    private readonly workspacePath;
+    private readonly installer;
+    private readonly autoInstall;
+    private readonly embedder;
+    constructor(options: MinSyncVectorMethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    sync(): Promise<MinSyncSyncResult>;
+    /** True when a configured binary path is missing (an explicit degraded state). */
+    isBinaryMissing(): boolean;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    /**
+     * Resolve the minsync binary path following the priority chain:
+     * 1. explicit binaryPath if set and exists
+     * 2. PATH lookup for `minsync`
+     * 3. cached join(root, '.autorag', 'bin', execName) if exists
+     * 4. if autoInstall===true, try ensureMinSyncBinary in try/catch => install-failed degrade
+     * 5. else return undefined (missing-binary degrade)
+     *
+     * Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
+     * for install-failed.
+     */
+    private resolveBinary;
+}

package/dist/minsync/paths.d.ts

@@ -0,0 +1,4 @@
+export declare const MINSYNC_SUBDIR: string;
+export declare const MINSYNC_FILES_SUBDIR = "files";
+export declare function minSyncWorkspaceRoot(root: string): string;
+export declare function minSyncDocumentPath(workspacePath: string, virtualPath: string): string;

package/dist/minsync/process.d.ts

@@ -0,0 +1,10 @@
+export interface ProcessResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+    readonly timedOut?: boolean;
+}
+export declare function spawnProcess(command: string, args: readonly string[], cwd: string, options?: {
+    readonly timeoutMs?: number;
+}): Promise<ProcessResult>;

package/dist/minsync/types.d.ts

@@ -0,0 +1,33 @@
+/** Embedder configuration for MinSync vector indexing. Shared by config and method layers. */
+export interface MinSyncEmbedderConfig {
+    readonly id?: string;
+    readonly baseUrl?: string;
+    /** Environment variable name whose value holds the embedder API key. /^[A-Za-z_][A-Za-z0-9_]*$/ */
+    readonly apiKeyEnv?: string;
+    /** Positive integer embedding dimension. */
+    readonly dimension?: number;
+    readonly queryPrefix?: string;
+    readonly passagePrefix?: string;
+    readonly timeoutMs?: number;
+    readonly batchSize?: number;
+    readonly maxRetries?: number;
+    readonly maxConcurrent?: number;
+}
+export interface MinSyncOptions {
+    readonly root: string;
+    readonly binaryPath?: string;
+    readonly workspacePath?: string;
+    readonly autoInstall?: boolean;
+    readonly embedder?: MinSyncEmbedderConfig;
+}
+export interface MinSyncSyncResult {
+    readonly ok: boolean;
+    readonly synced: number;
+    readonly workspacePath: string;
+    readonly reason?: string;
+}
+export interface MinSyncQueryHit {
+    readonly path: string;
+    readonly score: number;
+    readonly text: string;
+}

package/dist/minsync/workspace.d.ts

@@ -0,0 +1,14 @@
+export interface MinSyncWorkspaceEntry {
+    readonly virtualPath: string;
+    readonly sourcePath: string;
+    readonly parsedOutputPath: string;
+    readonly minSyncPath: string;
+}
+export interface MinSyncWorkspaceSyncResult {
+    readonly workspacePath: string;
+    readonly entries: readonly MinSyncWorkspaceEntry[];
+}
+export declare function syncMinSyncWorkspace(root: string, options?: {
+    readonly workspacePath?: string;
+}): MinSyncWorkspaceSyncResult;
+export declare function buildMinSyncPathMap(root: string, workspacePath: string): ReadonlyMap<string, MinSyncWorkspaceEntry>;