@jcode.labs/ragmir 2.14.0 → 2.16.0

package/README.md

@@ -1,26 +1,27 @@
-# Ragmir Core
+# @jcode.labs/ragmir
 
 [![npm version](https://img.shields.io/npm/v/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
 [![npm downloads](https://img.shields.io/npm/dm/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
 [![Node.js](https://img.shields.io/node/v/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
 [![MIT](https://img.shields.io/npm/l/@jcode.labs/ragmir)](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE)
 
-**Local RAG with verifiable citations for coding agents, scripts, and MCP clients.**
+**Local RAG for your coding agents.**
 
-`@jcode.labs/ragmir` indexes the files a project selects and returns source-backed passages without
-a hosted document store. The default `local-hash` retrieval path works offline, without an account
-or model download.
+`@jcode.labs/ragmir` indexes the project files you select, keeps the index on your machine, and
+returns bounded evidence with verifiable citations. Your coding agent or local script gets the
+context it needs without a hosted document store. The default `local-hash` path works offline,
+without an account or model download.
 
-Core is independent of the model or client that consumes those passages. Connect the coding agent
-or script you already use, keep the consumer local when no retrieved passage may leave the
-workstation, or call the typed API from Node.js.
+Core is model-agnostic. Connect the coding agent or local script you already use through generated
+project skills, local MCP, or the JSON CLI. Use the typed Node.js API when your application owns the
+control flow.
 
 [Project overview](https://github.com/jcode-works/jcode-ragmir#readme) ·
 [Documentation](https://github.com/jcode-works/jcode-ragmir/wiki) ·
 [CLI reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/cli-reference.md) ·
 [API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md)
 
-## Install Core when you need
+## What your coding agent gains
 
 | Goal | Core interface |
 | --- | --- |
@@ -30,12 +31,12 @@ workstation, or call the typed API from Node.js.
 | Give an agent bounded project context | Local stdio MCP server and generated helpers |
 | Index scanned PDFs | Embedded text first, with optional page-aware local OCR |
 
-Core retrieves cited evidence. It does not require a generative model or generate answers. Add
-[Ragmir Chat](https://www.npmjs.com/package/@jcode.labs/ragmir-chat) only when local
-GGUF synthesis is useful, or [Ragmir TTS](https://www.npmjs.com/package/@jcode.labs/ragmir-tts)
-when you need audio output.
+Core retrieves cited evidence. It does not require a generative model or generate answers. Use
+[Ragmir Chat](https://www.npmjs.com/package/@jcode.labs/ragmir-chat) only when local GGUF synthesis
+is useful, or [Ragmir TTS](https://www.npmjs.com/package/@jcode.labs/ragmir-tts) when you need audio
+output.
 
-## Use Ragmir with a coding agent or script
+## Connect a coding agent in minutes
 
 Requires Node.js 20 or later.
 
@@ -62,7 +63,7 @@ The same setup works with any compatible MCP client. Hermes can launch `.ragmir/
 scripts, CI, and internal tools can call the JSON CLI or the TypeScript API without a dedicated
 connector.
 
-## Use Ragmir from an automation
+## Use the same evidence from an automation
 
 ```bash
 npx rgr search "Should this renewal require approval?" --compact --json
@@ -72,9 +73,9 @@ Use that command from a local shell script, a Node.js worker, or a CI step after
 and its local `.ragmir/` state. The process returns machine-readable cited passages; the workflow
 decides whether to continue, request human approval, or stop.
 
-For long-running integrations, start the local stdio server with `npx rgr serve-mcp`. The MCP surface
-is bounded and read-focused: status, source coverage, search, retrieval-only ask, research, exact
-citation expansion, audit, evaluation, usage, and security checks. It never exposes index deletion.
+For long-running agent integrations, start the local stdio server with `npx rgr serve-mcp`. For a
+Node.js worker that owns the control flow, use `createRagmirClient()` and reuse one client per project
+root. Ragmir does not open an HTTP port or define an authentication layer.
 
 ## Search directly from the CLI
 
@@ -112,20 +113,29 @@ multi-query retrieval pass and reports missing or weak evidence.
 ## TypeScript API
 
 ```ts
-import { ingest, search } from "@jcode.labs/ragmir"
-
-await ingest({ cwd: process.cwd() })
-
-const results = await search("Which decision changed the rollout?", {
-  cwd: process.cwd(),
-  topK: 5,
-})
-
-for (const result of results) {
-  console.log(result.citation, result.text)
+import { createRagmirClient } from "@jcode.labs/ragmir"
+
+const ragmir = await createRagmirClient({ cwd: process.cwd() })
+try {
+  await ragmir.ingest({ timeoutMs: 120_000 })
+
+  const results = await ragmir.search("Which decision changed the rollout?", {
+    topK: 5,
+    timeoutMs: 10_000,
+  })
+
+  for (const result of results) {
+    console.log(result.citation, result.text)
+  }
+} finally {
+  await ragmir.close()
 }
 ```
 
+The persistent client reuses one local database connection, supports cooperative cancellation, and
+waits for active work before shutdown. The top-level functions remain the smallest API for one-shot
+scripts.
+
 Frequently used exports:
 
 | Export | Purpose |
@@ -133,11 +143,12 @@ Frequently used exports:
 | `setupProject`, `addSourceEntries` | Initialize project state and select files |
 | `discoverKnowledgeBases`, `knowledgeBaseIdentity` | Route root and nested monorepo bases |
 | `getKnowledgeBaseContext`, `getKnowledgeBaseSourceCatalog` | Give agents bounded readiness and source context |
+| `createRagmirClient`, `RagmirClient` | Reuse local retrieval safely in a stateful Node.js process |
 | `ingest`, `audit` | Build the index and compare it with files on disk |
 | `previewChunks` | Inspect redacted chunks and distributions without writing storage |
 | `search`, `ask`, `research`, `expandCitation` | Retrieve or expand cited passages |
 | `doctor`, `securityAudit` | Inspect readiness and local privacy posture |
-| `serveMcp` | Start the read-focused local MCP server |
+| `createMcpServer`, `connectMcpServer`, `serveMcp` | Construct, connect, or start the read-focused local MCP server |
 | `configurePdfOcr`, `inspectPdfOcr` | Configure and inspect local PDF OCR |
 
 See the [complete API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md)

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import type { PathLike } from "node:fs";
+import type { AskResult, ExpandCitationOptions, ExpandedCitation, IngestOptions, IngestResult, KnowledgeBaseContextReport, KnowledgeBaseSourceCatalog, ResearchOptions, ResearchReport, SearchOptions, SearchResult } from "./types.js";
+export interface RagmirClientOptions {
+    cwd?: PathLike;
+}
+export declare class RagmirClient {
+    readonly projectRoot: string;
+    private readonly config;
+    private readonly connection;
+    private readonly activeOperations;
+    private closed;
+    private closePromise;
+    private constructor();
+    get isClosed(): boolean;
+    static create(options?: RagmirClientOptions): Promise<RagmirClient>;
+    ingest(options?: Omit<IngestOptions, "cwd">): Promise<IngestResult>;
+    search(query: string, options?: Omit<SearchOptions, "cwd">): Promise<SearchResult[]>;
+    ask(query: string, options?: Omit<SearchOptions, "cwd">): Promise<AskResult>;
+    research(query: string, options?: Omit<ResearchOptions, "cwd">): Promise<ResearchReport>;
+    expandCitation(citation: string, options?: Omit<ExpandCitationOptions, "cwd">): Promise<ExpandedCitation>;
+    status(): Promise<KnowledgeBaseContextReport>;
+    sources(): Promise<KnowledgeBaseSourceCatalog>;
+    close(): Promise<void>;
+    private assertOpen;
+    private run;
+}
+export declare function createRagmirClient(options?: RagmirClientOptions): Promise<RagmirClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AASvC,OAAO,KAAK,EACV,SAAS,EAET,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,0BAA0B,EAC1B,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,QAAQ,CAAA;CACf;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA8B;IAC/D,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAA2B;IAE/C,OAAO;IAMP,IAAI,QAAQ,IAAI,OAAO,CAEtB;WAEY,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IAUvE,MAAM,CAAC,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIxF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAIhF,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAM,GACzC,OAAO,CAAC,cAAc,CAAC;IAIpB,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,CAAM,GAC/C,OAAO,CAAC,gBAAgB,CAAC;IAItB,MAAM,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI7C,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,GAAG;CAgBZ;AAED,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CAEjG"}

package/dist/client.js

@@ -0,0 +1,87 @@
+import { loadConfig } from "./config.js";
+import { getKnowledgeBaseContext, getKnowledgeBaseSourceCatalog } from "./context-resources.js";
+import { normalizeRagmirError, RagmirError } from "./errors.js";
+import { ingestWithConfig } from "./ingest.js";
+import { askWithConfig, expandCitationWithConfig, searchWithConfig } from "./query.js";
+import { researchWithConfig } from "./research.js";
+import { connectStore } from "./store.js";
+export class RagmirClient {
+    projectRoot;
+    config;
+    connection;
+    activeOperations = new Set();
+    closed = false;
+    closePromise;
+    constructor(config, connection) {
+        this.config = config;
+        this.connection = connection;
+        this.projectRoot = config.projectRoot;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    static async create(options = {}) {
+        try {
+            const config = await loadConfig(String(options.cwd ?? process.cwd()));
+            const connection = await connectStore(config);
+            return new RagmirClient(config, connection);
+        }
+        catch (error) {
+            throw normalizeRagmirError(error);
+        }
+    }
+    async ingest(options = {}) {
+        return this.run(() => ingestWithConfig(this.config, options, this.connection));
+    }
+    async search(query, options = {}) {
+        return this.run(() => searchWithConfig(query, options, this.config, this.connection));
+    }
+    async ask(query, options = {}) {
+        return this.run(() => askWithConfig(query, options, this.config, this.connection));
+    }
+    async research(query, options = {}) {
+        return this.run(() => researchWithConfig(query, options, this.config, this.connection));
+    }
+    async expandCitation(citation, options = {}) {
+        return this.run(() => expandCitationWithConfig(citation, options, this.config, this.connection));
+    }
+    async status() {
+        return this.run(() => getKnowledgeBaseContext(this.projectRoot));
+    }
+    async sources() {
+        return this.run(() => getKnowledgeBaseSourceCatalog(this.projectRoot));
+    }
+    async close() {
+        if (!this.closePromise) {
+            this.closed = true;
+            this.closePromise = (async () => {
+                await Promise.allSettled([...this.activeOperations]);
+                this.connection.close();
+            })();
+        }
+        await this.closePromise;
+    }
+    assertOpen() {
+        if (this.closed || !this.connection.isOpen()) {
+            throw new RagmirError("CLIENT_CLOSED", "Ragmir client is closed.");
+        }
+    }
+    run(operation) {
+        this.assertOpen();
+        const active = (async () => {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                throw normalizeRagmirError(error);
+            }
+        })();
+        this.activeOperations.add(active);
+        void active.then(() => this.activeOperations.delete(active), () => this.activeOperations.delete(active));
+        return active;
+    }
+}
+export async function createRagmirClient(options = {}) {
+    return RagmirClient.create(options);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export type RagmirErrorCode = "ABORTED" | "CLIENT_CLOSED" | "INTERNAL" | "INVALID_ARGUMENT" | "TIMEOUT";
+interface RagmirErrorOptions {
+    cause?: unknown;
+    retryable?: boolean;
+}
+export declare class RagmirError extends Error {
+    readonly code: RagmirErrorCode;
+    readonly retryable: boolean;
+    constructor(code: RagmirErrorCode, message: string, options?: RagmirErrorOptions);
+}
+export declare function isRagmirError(error: unknown): error is RagmirError;
+export declare function normalizeRagmirError(error: unknown): RagmirError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,eAAe,GACf,UAAU,GACV,kBAAkB,GAClB,SAAS,CAAA;AAEb,UAAU,kBAAkB;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;gBAEf,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAMrF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAShE"}

package/dist/errors.js

@@ -0,0 +1,20 @@
+export class RagmirError extends Error {
+    code;
+    retryable;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "RagmirError";
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+    }
+}
+export function isRagmirError(error) {
+    return error instanceof RagmirError;
+}
+export function normalizeRagmirError(error) {
+    if (isRagmirError(error)) {
+        return error;
+    }
+    return new RagmirError("INTERNAL", error instanceof Error ? error.message : "Ragmir operation failed.", { cause: error });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAiB;IACrB,SAAS,CAAS;IAE3B,YAAY,IAAqB,EAAE,OAAe,EAAE,UAA8B,EAAE;QAClF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;QAClF,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAA;IAC7C,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,WAAW,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,WAAW,CACpB,UAAU,EACV,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,EACnE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;AACH,CAAC"}

package/dist/index-write-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withIndexWriteLock<T>(key: string, signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=index-write-lock.d.ts.map

package/dist/index-write-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-write-lock.d.ts","sourceRoot":"","sources":["../src/index-write-lock.ts"],"names":[],"mappings":"AAIA,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAwBZ"}

package/dist/index-write-lock.js

@@ -0,0 +1,46 @@
+import { throwIfAborted } from "./operation.js";
+const writeQueues = new Map();
+export async function withIndexWriteLock(key, signal, operation) {
+    const previous = writeQueues.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.then(() => current, () => current);
+    writeQueues.set(key, tail);
+    void tail.then(() => {
+        if (writeQueues.get(key) === tail) {
+            writeQueues.delete(key);
+        }
+    });
+    try {
+        await waitForTurn(previous, signal);
+        throwIfAborted(signal);
+        return await operation();
+    }
+    finally {
+        release?.();
+    }
+}
+async function waitForTurn(previous, signal) {
+    if (!signal) {
+        await previous;
+        return;
+    }
+    throwIfAborted(signal);
+    let onAbort;
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve();
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        await Promise.race([previous, aborted]);
+        throwIfAborted(signal);
+    }
+    finally {
+        if (onAbort) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+}
+//# sourceMappingURL=index-write-lock.js.map

package/dist/index-write-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-write-lock.js","sourceRoot":"","sources":["../src/index-write-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAyB,CAAA;AAEpD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAW,EACX,MAA+B,EAC/B,SAA2B;IAE3B,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1D,IAAI,OAAiC,CAAA;IACrC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,OAAO,CAAA;IACnB,CAAC,CAAC,CAAA;IACF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CACxB,GAAG,EAAE,CAAC,OAAO,EACb,GAAG,EAAE,CAAC,OAAO,CACd,CAAA;IACD,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAC1B,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;QAClB,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QACnC,cAAc,CAAC,MAAM,CAAC,CAAA;QACtB,OAAO,MAAM,SAAS,EAAE,CAAA;IAC1B,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,EAAE,CAAA;IACb,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,QAAuB,EACvB,MAA+B;IAE/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,QAAQ,CAAA;QACd,OAAM;IACR,CAAC;IACD,cAAc,CAAC,MAAM,CAAC,CAAA;IAEtB,IAAI,OAAiC,CAAA;IACrC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAA;QACzB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IACF,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;QACvC,cAAc,CAAC,MAAM,CAAC,CAAA;IACxB,CAAC;YAAS,CAAC;QACT,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,17 +1,21 @@
 export { accessLogUsageReport } from "./access-log.js";
+export type { RagmirClientOptions } from "./client.js";
+export { createRagmirClient, RagmirClient } from "./client.js";
 export { loadConfig } from "./config.js";
 export { getKnowledgeBaseContext, getKnowledgeBaseSourceCatalog, } from "./context-resources.js";
 export { destroyIndex } from "./destroy.js";
 export { doctor } from "./doctor.js";
 export type { PullEmbeddingModelResult } from "./embeddings.js";
 export { clearTransformersCache, pullEmbeddingModel } from "./embeddings.js";
+export type { RagmirErrorCode } from "./errors.js";
+export { isRagmirError, normalizeRagmirError, RagmirError } from "./errors.js";
 export { evaluateGoldenQueries } from "./evaluate.js";
 export { getIndexFreshnessWarning, getLexicalScanWarning, INDEX_SCHEMA_VERSION, } from "./index-diagnostics.js";
 export { audit, ingest } from "./ingest.js";
 export { initProject } from "./init.js";
 export { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js";
 export { ingestionLimits } from "./limits.js";
-export { serveMcp } from "./mcp.js";
+export { connectMcpServer, createMcpServer, serveMcp } from "./mcp.js";
 export type { ConfigurePdfOcrOptions, ConfigurePdfOcrResult, ExtractPdfPageOptions, OcrExecutableStatus, PdfOcrEngine, PdfOcrEngineSelection, PdfOcrStatus, } from "./ocr.js";
 export { configurePdfOcr, extractPdfPage, inspectPdfOcr } from "./ocr.js";
 export type { PackageManager, RagmirCommand } from "./package-manager.js";
@@ -31,6 +35,6 @@ export type { AgentHelperFile, AgentInstallMode, AgentInstallScope, AgentIntegra
 export { bundledSkillPath, inspectAgentIntegration, installAgentSkills, installSkill, parseAgentTargets, SUPPORTED_AGENT_TARGETS, } from "./skill.js";
 export type { AddSourceEntriesOptions, AddSourceEntriesResult, SourceEntriesResult, } from "./sources.js";
 export { addSourceEntries, listSourceEntries } from "./sources.js";
-export type { AccessLogAction, AccessLogUsageOptions, AccessLogUsageReport, AskResult, AuditReport, ChunkStats, CodeEvidence, CompactSearchResult, Config, DestroyIndexResult, DoctorReport, EvaluationCaseResult, EvaluationOptions, EvaluationResult, ExpandCitationOptions, ExpandedCitation, GoldenQuery, IndexManifest, IndexManifestFile, IngestionLimitsReport, IngestOptions, IngestResult, KnowledgeBaseContextReport, KnowledgeBaseIdentity, KnowledgeBaseInfo, KnowledgeBaseInventory, KnowledgeBaseSourceCatalog, McpOutputTool, McpOutputUsageReport, ParsedPage, PreviewChunk, PreviewChunksOptions, PreviewFile, PreviewReport, PrivacyProfile, RedactionCount, ResearchEvidence, ResearchOptions, ResearchReport, RetrievalProfile, SearchContextChunk, SearchOptions, SearchResult, SearchScoreExplanation, SecurityAuditReport, SourceDiagnostics, SourceDuplicateCandidate, SourcePathCandidate, } from "./types.js";
+export type { AccessLogAction, AccessLogUsageOptions, AccessLogUsageReport, AskResult, AuditReport, ChunkStats, CodeEvidence, CompactSearchResult, Config, DestroyIndexResult, DoctorReport, EvaluationCaseResult, EvaluationOptions, EvaluationResult, ExpandCitationOptions, ExpandedCitation, GoldenQuery, IndexManifest, IndexManifestFile, IngestionLimitsReport, IngestOptions, IngestResult, KnowledgeBaseContextReport, KnowledgeBaseIdentity, KnowledgeBaseInfo, KnowledgeBaseInventory, KnowledgeBaseSourceCatalog, McpOutputTool, McpOutputUsageReport, OperationOptions, ParsedPage, PreviewChunk, PreviewChunksOptions, PreviewFile, PreviewReport, PrivacyProfile, RedactionCount, ResearchEvidence, ResearchOptions, ResearchReport, RetrievalProfile, SearchContextChunk, SearchOptions, SearchResult, SearchScoreExplanation, SecurityAuditReport, SourceDiagnostics, SourceDuplicateCandidate, SourcePathCandidate, } from "./types.js";
 export { VERSION } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,qBAAqB,EACrB,YAAY,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACzE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzE,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAA;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,WAAW,EACX,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,SAAS,EACT,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,MAAM,EACN,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,16 +1,18 @@
 export { accessLogUsageReport } from "./access-log.js";
+export { createRagmirClient, RagmirClient } from "./client.js";
 export { loadConfig } from "./config.js";
 export { getKnowledgeBaseContext, getKnowledgeBaseSourceCatalog, } from "./context-resources.js";
 export { destroyIndex } from "./destroy.js";
 export { doctor } from "./doctor.js";
 export { clearTransformersCache, pullEmbeddingModel } from "./embeddings.js";
+export { isRagmirError, normalizeRagmirError, RagmirError } from "./errors.js";
 export { evaluateGoldenQueries } from "./evaluate.js";
 export { getIndexFreshnessWarning, getLexicalScanWarning, INDEX_SCHEMA_VERSION, } from "./index-diagnostics.js";
 export { audit, ingest } from "./ingest.js";
 export { initProject } from "./init.js";
 export { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js";
 export { ingestionLimits } from "./limits.js";
-export { serveMcp } from "./mcp.js";
+export { connectMcpServer, createMcpServer, serveMcp } from "./mcp.js";
 export { configurePdfOcr, extractPdfPage, inspectPdfOcr } from "./ocr.js";
 export { detectPackageManager, kbCommand, ragmirCommand, rgrCommand } from "./package-manager.js";
 export { previewChunks } from "./preview.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAUnC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAEzE,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAczC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AAMnB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAmDlE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE5E,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAUtE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAEzE,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAczC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AAMnB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAoDlE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/ingest.d.ts

@@ -1,4 +1,6 @@
-import type { AuditReport, IngestOptions, IngestResult } from "./types.js";
+import type { Connection } from "@lancedb/lancedb";
+import type { AuditReport, Config, IngestOptions, IngestResult } from "./types.js";
 export declare function ingest(options?: IngestOptions): Promise<IngestResult>;
+export declare function ingestWithConfig(config: Config, options?: IngestOptions, connection?: Connection): Promise<IngestResult>;
 export declare function audit(cwd?: string): Promise<AuditReport>;
 //# sourceMappingURL=ingest.d.ts.map

package/dist/ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,WAAW,EAGX,aAAa,EACb,YAAY,EAMb,MAAM,YAAY,CAAA;AAmBnB,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6L/E;AA0BD,wBAAsB,KAAK,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CA+ErE"}
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AA2BlD,OAAO,KAAK,EACV,WAAW,EACX,MAAM,EAEN,aAAa,EACb,YAAY,EAMb,MAAM,YAAY,CAAA;AAmBnB,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAG/E;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,EAC3B,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,YAAY,CAAC,CAKvB;AAmOD,wBAAsB,KAAK,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CA+ErE"}

package/dist/ingest.js

@@ -7,6 +7,8 @@ import { embedTexts } from "./embeddings.js";
 import { countSkippedByReason, inventorySourceFiles, summarizeUnsupportedExtensions, } from "./files.js";
 import { INDEX_SCHEMA_VERSION } from "./index-diagnostics.js";
 import { indexPolicyFingerprint } from "./index-policy.js";
+import { withIndexWriteLock } from "./index-write-lock.js";
+import { operationSignal, throwIfAborted } from "./operation.js";
 import { parseFile } from "./parsing.js";
 import { redactText, totalRedactions } from "./redaction.js";
 import { openRowsTable, readEmptyTextFiles, readIndexManifest, updateRows, writeEmptyTextFiles, writeIndexManifest, writeRows, } from "./store.js";
@@ -28,13 +30,21 @@ const MIRROR_PATH_PATTERNS = [
 ];
 export async function ingest(options = {}) {
     const config = await loadConfig(String(options.cwd ?? process.cwd()));
+    return ingestWithConfig(config, options);
+}
+export async function ingestWithConfig(config, options = {}, connection) {
+    const signal = operationSignal(options);
+    return withIndexWriteLock(config.storageDir, signal, () => ingestUnlocked(config, options, connection, signal));
+}
+async function ingestUnlocked(config, options, connection, signal) {
+    throwIfAborted(signal);
     const policyFingerprint = indexPolicyFingerprint(config);
     const existingManifest = await readIndexManifest(config);
     const manifestCompatible = !options.rebuild &&
         existingManifest?.schemaVersion === INDEX_SCHEMA_VERSION &&
         existingManifest.indexPolicyFingerprint === policyFingerprint &&
         existingManifest.indexedFiles !== undefined;
-    const existingTable = manifestCompatible ? await openRowsTable(config) : null;
+    const existingTable = manifestCompatible ? await openRowsTable(config, connection) : null;
     const storedEmptyFiles = manifestCompatible ? await readEmptyTextFiles(config) : [];
     const knownFiles = new Map([...(existingManifest?.indexedFiles ?? []), ...storedEmptyFiles].map((file) => [
         file.relativePath,
@@ -62,14 +72,16 @@ export async function ingest(options = {}) {
     const errors = [];
     const redactionCounts = [];
     const emptyTextFiles = [];
-    const results = await mapLimit(filesToIndex, config.ingestConcurrency, async (file) => {
+    const results = await mapLimit(filesToIndex, config.ingestConcurrency, signal, async (file) => {
         try {
             const parsed = await parseFile(file, config);
+            throwIfAborted(signal);
             const redacted = redactText(parsed.text, config);
             const chunks = chunkDocument({ ...parsed, text: redacted.text }, config.chunkSize, config.chunkOverlap);
             return { path: file.relativePath, chunks, redactions: redacted.counts, error: null };
         }
         catch (error) {
+            throwIfAborted(signal);
             return {
                 path: file.relativePath,
                 chunks: [],
@@ -94,8 +106,10 @@ export async function ingest(options = {}) {
     }
     const rows = [];
     for (let i = 0; i < allChunks.length; i += config.embeddingBatchSize) {
+        throwIfAborted(signal);
         const batch = allChunks.slice(i, i + config.embeddingBatchSize);
         const embeddings = await embedTexts(batch.map(chunkSearchText), config);
+        throwIfAborted(signal);
         for (const [index, chunk] of batch.entries()) {
             const vector = embeddings[index];
             if (!vector) {
@@ -119,13 +133,14 @@ export async function ingest(options = {}) {
         ...filesToIndex.map((file) => file.relativePath),
         ...[...previousPaths].filter((relativePath) => !currentPaths.has(relativePath)),
     ];
+    throwIfAborted(signal);
     const writeResult = !canReuse || chunkCount === 0
-        ? await writeRows(rows, config)
+        ? await writeRows(rows, config, connection)
         : replacePaths.length > 0
-            ? await updateRows(rows, replacePaths, config)
+            ? await updateRows(rows, replacePaths, config, connection)
             : { vectorIndexWarning: null, lexicalIndexWarning: null };
     if (chunkCount > 0) {
-        const firstRow = rows[0] ?? (await firstStoredRow(config));
+        const firstRow = rows[0] ?? (await firstStoredRow(config, connection));
         if (!firstRow) {
             throw new Error("Cannot write an index manifest without indexed rows.");
         }
@@ -205,8 +220,8 @@ function indexedFileRecords(rows) {
     }
     return [...records.values()];
 }
-async function firstStoredRow(config) {
-    const table = await openRowsTable(config);
+async function firstStoredRow(config, connection) {
+    const table = await openRowsTable(config, connection);
     if (!table) {
         return null;
     }
@@ -338,16 +353,18 @@ async function currentEmptyTextFiles(config, files) {
     }
     return emptyTextFiles;
 }
-async function mapLimit(items, concurrency, worker) {
+async function mapLimit(items, concurrency, signal, worker) {
     const results = new Array(items.length);
     let nextIndex = 0;
     async function run() {
         while (nextIndex < items.length) {
+            throwIfAborted(signal);
             const index = nextIndex;
             nextIndex += 1;
             const item = items[index];
             if (item !== undefined) {
                 results[index] = await worker(item);
+                throwIfAborted(signal);
             }
         }
     }