@dikolab/kbdb 0.3.1 → 0.4.0

package/dist/mod.mjs

@@ -1,5 +1,5 @@
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.2.2";
+var VERSION = "0.4.0";
 
 // src/shared/worker-client/classes/worker-client.class.ts
 import { connect } from "node:net";
@@ -9,10 +9,13 @@ var WorkerClient = class {
    *   (or Windows named pipe path)
    * @param contextId - 16-character context identifier sent as
    *   `ctx` in every JSON-RPC request
+   * @param requestTimeoutMs - per-request timeout in ms
+   *   (0 or undefined disables the timeout)
    */
-  constructor(socketPath, contextId) {
+  constructor(socketPath, contextId, requestTimeoutMs) {
     this.socketPath = socketPath;
     this.contextId = contextId;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
   /** Underlying socket; `null` when not connected. */
   socket = null;
@@ -22,30 +25,85 @@ var WorkerClient = class {
   pending = /* @__PURE__ */ new Map();
   /** Partial line buffer for split TCP/IPC frames. */
   buffer = "";
+  /** Whether the underlying socket is connected. */
+  get isConnected() {
+    return this.socket !== null;
+  }
   /**
    * Establishes the IPC connection to the worker daemon.
    *
+   * Retries up to 5 times with exponential backoff on
+   * transient errors (`ENOENT`, `ECONNREFUSED`).
+   *
    * @throws {Error} if the connection cannot be established
    */
   async connect() {
+    const maxRetries = 5;
+    let delay = 50;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await this.tryConnect();
+        return;
+      } catch (err) {
+        const code = err.code;
+        const retriable = code === "ENOENT" || code === "ECONNREFUSED";
+        if (!retriable || attempt === maxRetries) {
+          throw err;
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 1e3);
+      }
+    }
+  }
+  /** Destroys the IPC socket and clears the connection state. */
+  disconnect() {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+  /**
+   * Single connection attempt with keepalive and
+   * post-connect failure handlers.
+   */
+  async tryConnect() {
     return new Promise((resolve2, reject) => {
-      this.socket = connect(this.socketPath, () => {
+      const sock = connect(this.socketPath, () => {
+        sock.removeListener("error", reject);
+        sock.setKeepAlive(true, 3e4);
+        sock.on("error", (err) => {
+          this.handleSocketFailure(err);
+        });
+        sock.on("close", () => {
+          if (this.pending.size > 0) {
+            this.handleSocketFailure(
+              new Error("connection closed")
+            );
+          }
+          this.socket = null;
+        });
+        this.socket = sock;
         resolve2();
       });
-      this.socket.on("error", (err) => {
-        reject(err);
-      });
-      this.socket.on("data", (chunk) => {
+      sock.on("error", reject);
+      sock.on("data", (chunk) => {
         this.handleData(chunk.toString());
       });
     });
   }
-  /** Destroys the IPC socket and clears the connection state. */
-  disconnect() {
-    if (this.socket) {
-      this.socket.destroy();
-      this.socket = null;
+  /**
+   * Rejects all pending calls and marks the client as
+   * disconnected.
+   */
+  handleSocketFailure(err) {
+    const sock = this.socket;
+    this.socket = null;
+    for (const [id, call] of this.pending) {
+      this.pending.delete(id);
+      if (call.timer) clearTimeout(call.timer);
+      call.reject(err);
     }
+    if (sock) sock.destroy();
   }
   /**
    * Searches the knowledge base.
@@ -54,7 +112,10 @@ var WorkerClient = class {
    * @returns paginated search results with metadata
    */
   async search(params) {
-    return this.call("search", params);
+    return this.call("search", {
+      ...params,
+      algo: params.algo
+    });
   }
   /**
    * Retrieves full content and context for one or more sections by
@@ -305,7 +366,20 @@ var WorkerClient = class {
    */
   async export(params) {
     return this.call("export", {
-      targetPath: params?.path || void 0
+      targetPath: params?.path || void 0,
+      format: params?.format
+    });
+  }
+  /**
+   * Imports an exported database from the given path.
+   *
+   * @param params - source path and dry-run flag
+   * @returns import report with counts and timing
+   */
+  async import(params) {
+    return this.call("importDb", {
+      sourcePath: params.from,
+      dryRun: params.dryRun
     });
   }
   /**
@@ -328,8 +402,21 @@ var WorkerClient = class {
       method,
       params: { ctx: this.contextId, ...params }
     };
+    const timeoutMs = this.requestTimeoutMs;
     return new Promise((resolve2, reject) => {
-      this.pending.set(id, { resolve: resolve2, reject });
+      const call = { resolve: resolve2, reject };
+      if (timeoutMs) {
+        call.timer = setTimeout(() => {
+          if (!this.pending.has(id)) return;
+          this.pending.delete(id);
+          const err = new Error(
+            `request timeout after ${String(timeoutMs)}ms`
+          );
+          err.code = "REQUEST_TIMEOUT";
+          reject(err);
+        }, timeoutMs);
+      }
+      this.pending.set(id, call);
       socket.write(JSON.stringify(request) + "\n");
     });
   }
@@ -350,6 +437,7 @@ var WorkerClient = class {
         const pending = this.pending.get(response.id);
         if (pending) {
           this.pending.delete(response.id);
+          if (pending.timer) clearTimeout(pending.timer);
           if (response.error) {
             const err = new Error(response.error.message);
             err.code = response.error.code;
@@ -507,7 +595,11 @@ async function createWorkerClient(options) {
       `kbdb worker daemon did not start: ${readCrashReason(contextId)}`
     );
   }
-  const client = new WorkerClient(socketPath, contextId);
+  const client = new WorkerClient(
+    socketPath,
+    contextId,
+    options?.requestTimeoutMs
+  );
   await client.connect();
   return client;
 }
@@ -525,10 +617,23 @@ function readCrashReason(contextId) {
     return "daemon failed to start (crash log unreadable)";
   }
 }
+
+// src/shared/worker-client/functions/get-or-create-client.function.ts
+var cache = /* @__PURE__ */ new Map();
+async function getOrCreateClient(options) {
+  const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
+  const cached = cache.get(dbPath);
+  if (cached?.isConnected) return cached;
+  cache.delete(dbPath);
+  const client = await createWorkerClient(options);
+  cache.set(dbPath, client);
+  return client;
+}
 export {
   WorkerClient,
   computeContextId,
   createWorkerClient,
+  getOrCreateClient,
   resolveDbPath,
   VERSION as version
 };

package/dist/mod.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/shared/version/constants/version.constant.ts", "../src/shared/worker-client/classes/worker-client.class.ts", "../src/shared/worker-client/functions/create-worker-client.function.ts", "../src/shared/worker-client/functions/resolve-db-path.function.ts", "../src/shared/hash/functions/compute-sha256.ts", "../src/shared/worker-client/functions/compute-context-id.function.ts", "../src/shared/worker-client/functions/discover-daemon.function.ts", "../src/shared/platform/functions/is-process-alive.function.ts", "../src/shared/worker-client/functions/spawn-daemon.function.ts", "../src/shared/worker-client/functions/wait-for-daemon.function.ts", "../src/shared/runtime/functions/detect-runtime.ts", "../src/shared/platform/functions/get-ipc-path.function.ts", "../src/shared/platform/functions/get-tmpdir.function.ts"],
-  "sourcesContent": ["/** Current package version, kept in sync with package.json. */\nexport const VERSION = '0.2.2';\n", "import { connect } from 'node:net';\nimport type { Socket } from 'node:net';\nimport type { SearchParams } from '../typings/search-params.model.ts';\nimport type { PagedSearchResult } from '../typings/search-result.model.ts';\nimport type {\n   AddSectionParams,\n   Section,\n} from '../typings/section.model.ts';\nimport type { StatusResult } from '../typings/status-result.model.ts';\nimport type { AddSectionResult } from '../typings/add-section-result.model.ts';\nimport type { RemoveSectionResult } from '../typings/remove-section-result.model.ts';\nimport type { ContentResult } from '../typings/content-result.model.ts';\nimport type { IntegrityCheckResult } from '../typings/integrity-check-result.model.ts';\nimport type { GcResult } from '../typings/gc-result.model.ts';\nimport type { RebuildResult } from '../typings/rebuild-result.model.ts';\nimport type { MigrateResult } from '../typings/migrate-result.model.ts';\nimport type { VersionStatus } from '../typings/version-status.model.ts';\nimport type { SectionRecord } from '../../wasm-codec/functions/decode-section-records.function.ts';\nimport type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';\nimport type {\n   RecallParams,\n   RecallResult,\n} from '../typings/recall-result.model.ts';\nimport type { ExportResult } from '../typings/export-result.model.ts';\n\n/** Pending JSON-RPC call awaiting a response from the daemon. */\ninterface PendingCall {\n   resolve: (v: unknown) => void;\n   reject: (e: Error) => void;\n}\n\n/** Shape of a JSON-RPC 2.0 error object from the daemon. */\ninterface JsonRpcError {\n   readonly code: number;\n   readonly message: string;\n}\n\n/** Shape of a JSON-RPC 2.0 response from the daemon. */\ninterface JsonRpcResponse {\n   readonly id: number;\n   readonly result?: unknown;\n   readonly error?: JsonRpcError;\n}\n\n/**\n * IPC client that communicates with the worker daemon over a Unix\n * domain socket (or Windows named pipe) using JSON-RPC 2.0 with\n * newline-delimited message framing.\n *\n * Call `connect()` before any other method and `disconnect()` when\n * done to release the underlying socket.\n */\nexport class WorkerClient {\n   /** Underlying socket; `null` when not connected. */\n   private socket: Socket | null = null;\n\n   /** Monotonically increasing request ID counter. */\n   private nextId = 1;\n\n   /** Map of outstanding request IDs to their resolve/reject pairs. */\n   private readonly pending = new Map<number, PendingCall>();\n\n   /** Partial line buffer for split TCP/IPC frames. */\n   private buffer = '';\n\n   /**\n    * @param socketPath - absolute path to the daemon's IPC socket\n    *   (or Windows named pipe path)\n    * @param contextId - 16-character context identifier sent as\n    *   `ctx` in every JSON-RPC request\n    */\n   constructor(\n      private readonly socketPath: string,\n      private readonly contextId: string,\n   ) {}\n\n   /**\n    * Establishes the IPC connection to the worker daemon.\n    *\n    * @throws {Error} if the connection cannot be established\n    */\n   async connect(): Promise<void> {\n      return new Promise<void>((resolve, reject) => {\n         this.socket = connect(this.socketPath, () => {\n            resolve();\n         });\n         this.socket.on('error', (err: Error) => {\n            reject(err);\n         });\n         this.socket.on('data', (chunk: Buffer) => {\n            this.handleData(chunk.toString());\n         });\n      });\n   }\n\n   /** Destroys the IPC socket and clears the connection state. */\n   disconnect(): void {\n      if (this.socket) {\n         this.socket.destroy();\n         this.socket = null;\n      }\n   }\n\n   /**\n    * Searches the knowledge base.\n    *\n    * @param params - query parameters including the search string\n    * @returns paginated search results with metadata\n    */\n   async search(params: SearchParams): Promise<PagedSearchResult> {\n      return this.call('search', params) as Promise<PagedSearchResult>;\n   }\n\n   /**\n    * Retrieves full content and context for one or more sections by\n    * their knowledge-base identifiers.\n    *\n    * @param params - section identifier(s) and optional expansion depth\n    * @returns a single `RecallResult` when `kbid` is provided without\n    *   `kbids`, or a `RecallResult[]` when `kbids` is provided\n    */\n   async recall(\n      params: RecallParams,\n   ): Promise<RecallResult | RecallResult[]> {\n      return this.call('recall', params) as Promise<\n         RecallResult | RecallResult[]\n      >;\n   }\n\n   /**\n    * Adds a new section to the knowledge base.\n    *\n    * @param params - section content and metadata\n    * @returns the result including the assigned knowledge-base\n    *   identifier and indexing statistics\n    */\n   async addSection(\n      params: AddSectionParams,\n   ): Promise<AddSectionResult> {\n      return this.call(\n         'addSection',\n         params,\n      ) as Promise<AddSectionResult>;\n   }\n\n   /**\n    * Replaces an existing section's content and metadata.\n    *\n    * @param kbid - identifier of the section to update\n    * @param params - new content and metadata\n    * @returns the knowledge-base identifier of the updated section\n    */\n   async updateSection(\n      kbid: string,\n      params: AddSectionParams,\n   ): Promise<string> {\n      return this.call('updateSection', {\n         kbid,\n         ...params,\n      }) as Promise<string>;\n   }\n\n   /**\n    * Removes a section from the knowledge base.\n    *\n    * @param kbid - identifier of the section to remove\n    * @returns removal result with `removed` flag and elapsed time\n    */\n   async removeSection(kbid: string): Promise<RemoveSectionResult> {\n      return this.call('removeSection', {\n         kbid,\n      }) as Promise<RemoveSectionResult>;\n   }\n\n   /**\n    * Retrieves multiple sections by their identifiers.\n    *\n    * @param kbids - list of knowledge-base identifiers to fetch\n    * @returns sections in the order their IDs were requested\n    */\n   async readSections(kbids: string[]): Promise<Section[]> {\n      return this.call('readSections', {\n         kbids,\n      }) as Promise<Section[]>;\n   }\n\n   /**\n    * Groups a set of sections under a named document.\n    *\n    * @param title - human-readable document title\n    * @param kbids - identifiers of the sections to group\n    * @param docType - application-level document type tag; omit or\n    *   pass an empty string for untagged documents\n    * @returns the assigned document identifier\n    */\n   async groupSections(\n      title: string,\n      kbids: string[],\n      docType?: string,\n   ): Promise<string> {\n      const result = (await this.call('groupSections', {\n         title,\n         kbids,\n         docType: docType ?? '',\n      })) as { docid: string } | string;\n      return typeof result === 'string' ? result : result.docid;\n   }\n\n   /**\n    * Removes the document grouping for the given document.\n    *\n    * The sections themselves are not deleted; only the grouping\n    * record is removed.\n    *\n    * @param docid - identifier of the document grouping to remove\n    */\n   async removeGrouping(docid: string): Promise<void> {\n      await this.call('removeGrouping', { docid });\n   }\n\n   /**\n    * Retrieves a full document record including its sections.\n    *\n    * @param docid - identifier of the document to retrieve\n    * @returns the document record as returned by the daemon\n    */\n   async retrieveDocument(docid: string): Promise<unknown> {\n      return this.call('retrieveDocument', { docid });\n   }\n\n   /**\n    * Composes a rendered Markdown document from one or more kbid\n    * or docid identifiers.\n    *\n    * @param ids - list of kbid or docid identifiers (may be mixed)\n    * @returns composed Markdown result with character count\n    */\n   async content(ids: string[]): Promise<ContentResult> {\n      return this.call('content', { ids }) as Promise<ContentResult>;\n   }\n\n   /**\n    * Runs an integrity check on the knowledge-base database.\n    *\n    * @returns a report of all issues found; `ok` is `true` when\n    *   no errors were detected\n    */\n   async integrityCheck(): Promise<IntegrityCheckResult> {\n      return this.call(\n         'integrityCheck',\n         {},\n      ) as Promise<IntegrityCheckResult>;\n   }\n\n   /**\n    * Removes unreferenced sections from the database.\n    *\n    * @returns a report of sections removed and bytes freed\n    */\n   async gc(): Promise<GcResult> {\n      return this.call('gc', {}) as Promise<GcResult>;\n   }\n\n   /**\n    * Reconstructs all index files from section files and document\n    * manifests on disk. Text and code sections are re-tokenized;\n    * image sections are skipped.\n    *\n    * @returns a report of sections and terms re-indexed\n    */\n   async rebuildIndexes(): Promise<RebuildResult> {\n      return this.call('rebuildIndexes', {}) as Promise<RebuildResult>;\n   }\n\n   /**\n    * Invalidates the in-memory cache entry for a single section.\n    *\n    * @param kbid - identifier of the section to evict from cache\n    */\n   async invalidate(kbid: string): Promise<void> {\n      await this.call('invalidate', { kbid });\n   }\n\n   /** Clears all entries from the daemon's in-memory cache. */\n   async invalidateAll(): Promise<void> {\n      await this.call('invalidateAll', {});\n   }\n\n   /**\n    * Retrieves diagnostic status information from the daemon.\n    *\n    * @returns current initialization state and cache statistics\n    */\n   async status(): Promise<StatusResult> {\n      return this.call('status', {}) as Promise<StatusResult>;\n   }\n\n   /**\n    * Returns database metadata and status from the daemon,\n    * including document count, section count, index size, and\n    * cache statistics.\n    *\n    * @returns database metadata from the daemon's cached state\n    */\n   async dbStatus(): Promise<StatusResult> {\n      return this.call('dbStatus', {}) as Promise<StatusResult>;\n   }\n\n   /**\n    * Initialises a new `.kbdb` database directory at the given path\n    * by sending an init request to the worker daemon.\n    *\n    * The daemon creates all required subdirectories and seed files via\n    * the `worker_init_directory` WASM export.\n    *\n    * @param targetPath - absolute path to the directory that will\n    *   contain the new `.kbdb` database\n    * @throws {Error} if the `.kbdb` directory already exists or the\n    *   daemon cannot create the layout\n    */\n   async initDirectory(targetPath: string): Promise<void> {\n      await this.call('initDirectory', { targetPath });\n   }\n\n   /**\n    * Runs all pending database migrations for the `.kbdb` directory\n    * at the given path.\n    *\n    * Delegates to the `worker_migrate` WASM export on the daemon.\n    * Each migration step updates `catalog.toml` on success, so\n    * retrying after a partial failure is safe.\n    *\n    * @param targetPath - absolute path to the `.kbdb` database root\n    * @returns migration report with old version, new version, and\n    *   number of migration steps applied\n    */\n   async migrateDatabase(targetPath: string): Promise<MigrateResult> {\n      return this.call('migrateDatabase', {\n         targetPath,\n      }) as Promise<MigrateResult>;\n   }\n\n   /**\n    * Checks the format version of the `.kbdb` database at the given\n    * path against the version required by the current WASM engine.\n    *\n    * This is a read-only operation: it reads `catalog.toml` and\n    * returns the compatibility status without making any changes.\n    *\n    * @param targetPath - absolute path to the `.kbdb` database root\n    * @returns version compatibility report\n    */\n   async checkVersion(targetPath: string): Promise<VersionStatus> {\n      return this.call('checkVersion', {\n         targetPath,\n      }) as Promise<VersionStatus>;\n   }\n\n   /**\n    * Retrieves all sections whose type name matches the given string.\n    *\n    * @param sectionType - the application-level type name to filter by\n    * @returns all section records with a matching type name\n    */\n   async listByType(sectionType: string): Promise<SectionRecord[]> {\n      return this.call('listByType', {\n         sectionType,\n      }) as Promise<SectionRecord[]>;\n   }\n\n   /**\n    * Retrieves all documents whose type name matches the given string.\n    *\n    * @param docType - the application-level document type to filter by\n    * @returns all document manifests with a matching type name\n    */\n   async listDocumentsByType(\n      docType: string,\n   ): Promise<DocumentManifest[]> {\n      return this.call('listDocumentsByType', {\n         docType,\n      }) as Promise<DocumentManifest[]>;\n   }\n\n   /**\n    * Exports the database to a target directory on disk.\n    *\n    * Copies section files, document manifests, and `catalog.toml`\n    * to `params.path`. Index files are not exported because they\n    * are derivable from the section and document data.\n    *\n    * @param params - optional export parameters\n    * @param params.path - target directory path; defaults to\n    *   `./kbdb-export/` when not provided\n    * @returns export report with the resolved path and file counts\n    */\n   async export(params?: { path?: string }): Promise<ExportResult> {\n      return this.call('export', {\n         targetPath: params?.path || undefined,\n      }) as Promise<ExportResult>;\n   }\n\n   /**\n    * Sends a JSON-RPC 2.0 request and awaits the response.\n    *\n    * @param method - the RPC method name\n    * @param params - parameters to include in the request\n    * @throws {Error} if not connected\n    * @throws {Error} when the daemon returns an error response\n    */\n   private async call(\n      method: string,\n      params: unknown,\n   ): Promise<unknown> {\n      const socket = this.socket;\n      if (!socket) {\n         throw new Error('not connected');\n      }\n\n      const id = this.nextId++;\n      const request = {\n         jsonrpc: '2.0',\n         id,\n         method,\n         params: { ctx: this.contextId, ...(params as object) },\n      };\n\n      return new Promise<unknown>((resolve, reject) => {\n         this.pending.set(id, { resolve, reject });\n         socket.write(JSON.stringify(request) + '\\n');\n      });\n   }\n\n   /**\n    * Processes incoming data from the socket, splitting on newlines\n    * and dispatching complete JSON-RPC response objects.\n    *\n    * @param data - raw string chunk received from the socket\n    */\n   private handleData(data: string): void {\n      this.buffer += data;\n      const lines = this.buffer.split('\\n');\n      this.buffer = lines.pop() ?? '';\n\n      for (const line of lines) {\n         if (!line.trim()) continue;\n         try {\n            const response = JSON.parse(line) as JsonRpcResponse;\n            const pending = this.pending.get(response.id);\n            if (pending) {\n               this.pending.delete(response.id);\n               if (response.error) {\n                  const err = new Error(response.error.message);\n                  (err as unknown as Record<string, unknown>).code =\n                     response.error.code;\n                  pending.reject(err);\n               } else {\n                  pending.resolve(response.result);\n               }\n            }\n         } catch {\n            // Ignore unparseable lines\n         }\n      }\n   }\n}\n", "import { existsSync, readFileSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { WorkerClient } from '../classes/worker-client.class.ts';\nimport { resolveDbPath } from './resolve-db-path.function.ts';\nimport { computeContextId } from './compute-context-id.function.ts';\nimport { discoverDaemon } from './discover-daemon.function.ts';\nimport { spawnDaemon } from './spawn-daemon.function.ts';\nimport { waitForDaemon } from './wait-for-daemon.function.ts';\nimport { detectRuntime } from '../../runtime/functions/detect-runtime.ts';\nimport { getIpcPath } from '../../platform/functions/get-ipc-path.function.ts';\nimport type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';\n\n/**\n * Creates and connects a `WorkerClient` to the worker daemon.\n *\n * Resolves the context path, derives a stable context identifier,\n * and checks whether a daemon is already running. If no daemon is\n * found and `autoSpawn` is not `false`, a new daemon process is\n * spawned and the factory waits for its PID file to appear before\n * connecting.\n *\n * @param options - optional configuration for path resolution,\n *   auto-spawn behaviour, and connection timeout\n * @returns a connected `WorkerClient` ready to send requests\n * @throws {Error} if the `.kbdb` directory cannot be found\n * @throws {Error} if the socket connection cannot be established\n */\nexport async function createWorkerClient(\n   options?: WorkerClientOptions,\n): Promise<WorkerClient> {\n   const dbPath =\n      options?.contextPath ?? resolveDbPath(options?.dbPath);\n   const contextId = await computeContextId(dbPath);\n   const socketPath = getIpcPath(contextId);\n\n   let daemon = discoverDaemon(contextId);\n\n   if (!daemon && options?.autoSpawn !== false) {\n      const runtime = detectRuntime();\n      spawnDaemon(dbPath, runtime, options?.workerScript);\n      await waitForDaemon(contextId, options?.connectTimeoutMs);\n      daemon = discoverDaemon(contextId);\n   }\n\n   if (!daemon) {\n      throw new Error(\n         `kbdb worker daemon did not start: ${readCrashReason(contextId)}`,\n      );\n   }\n\n   const client = new WorkerClient(socketPath, contextId);\n   await client.connect();\n   return client;\n}\n\nfunction readCrashReason(contextId: string): string {\n   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);\n   if (!existsSync(crashPath)) {\n      return 'daemon failed to start (no details available)';\n   }\n   try {\n      const raw = readFileSync(crashPath, 'utf-8');\n      const crash = JSON.parse(raw) as { error?: string };\n      unlinkSync(crashPath);\n      return crash.error ?? 'unknown error (crash log empty)';\n   } catch {\n      return 'daemon failed to start (crash log unreadable)';\n   }\n}\n", "import { existsSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\n\n/**\n * Resolves the absolute path to the `.kbdb` database directory.\n *\n * Searches for a `.kbdb` sub-directory inside `targetDir`. When\n * `targetDir` is omitted, `process.cwd()` is used as the base.\n *\n * @param targetDir - directory to search in; defaults to cwd\n * @throws {Error} if no `.kbdb` directory exists at the resolved\n *   path\n */\nexport function resolveDbPath(targetDir?: string): string {\n   const base = targetDir ? resolve(targetDir) : process.cwd();\n   const dbPath = join(base, '.kbdb');\n   if (!existsSync(dbPath)) {\n      throw new Error(`database not found: ${dbPath}`);\n   }\n   return dbPath;\n}\n", "/**\n * Computes the SHA-256 hash of a UTF-8 string.\n *\n * Uses the Web Crypto API (`crypto.subtle`), which is available\n * in both Deno and Node.js >= 20 without additional imports.\n *\n * @param input - the string to hash\n * @returns lowercase hex-encoded SHA-256 digest (64 characters)\n */\nexport async function computeSha256(input: string): Promise<string> {\n   const data = new TextEncoder().encode(input);\n   const hash = await crypto.subtle.digest('SHA-256', data);\n   const bytes = new Uint8Array(hash);\n   return Array.from(bytes)\n      .map((b) => b.toString(16).padStart(2, '0'))\n      .join('');\n}\n", "import { computeSha256 } from '../../hash/functions/compute-sha256.ts';\n\n/**\n * Computes a short context identifier for an absolute path.\n *\n * Hashes the path with SHA-256 and returns the first 16 hex\n * characters. The result is stable for the same input and unique\n * enough to avoid accidental collisions across typical path sets.\n *\n * @param absolutePath - the absolute filesystem path to identify\n * @returns a 16-character lowercase hex string\n */\nexport async function computeContextId(\n   absolutePath: string,\n): Promise<string> {\n   const hash = await computeSha256(absolutePath);\n   return hash.slice(0, 16);\n}\n", "import { existsSync, readFileSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { isProcessAlive } from '../../platform/functions/is-process-alive.function.ts';\nimport type { DaemonInfo } from '../typings/daemon-info.model.ts';\n\nexport type { DaemonInfo };\n\n/**\n * Discovers a running worker daemon for the given context.\n *\n * Reads the PID file at `<tmpdir>/kbdb-<contextId>.pid`. If the\n * file exists and the process is alive, returns its PID and the\n * expected socket path. If the file is stale (process dead or PID\n * unparseable), removes the PID file and returns `null`.\n *\n * @param contextId - the 16-character context identifier\n * @returns daemon location info, or `null` if no live daemon found\n */\nexport function discoverDaemon(contextId: string): DaemonInfo | null {\n   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);\n\n   if (!existsSync(pidPath)) return null;\n\n   const pidStr = readFileSync(pidPath, 'utf-8').trim();\n   const pid = parseInt(pidStr, 10);\n\n   if (isNaN(pid) || !isProcessAlive(pid)) {\n      try {\n         unlinkSync(pidPath);\n      } catch {\n         // Stale PID file removal is best-effort\n      }\n      return null;\n   }\n\n   const socketPath = join(tmpdir(), `kbdb-${contextId}.sock`);\n\n   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);\n   try {\n      unlinkSync(crashPath);\n   } catch {\n      // stale crash file removal is best-effort\n   }\n\n   return { pid, socketPath };\n}\n", "/**\n * Checks whether a process with the given PID is alive.\n *\n * Sends signal `0` to the process, which performs a permission\n * check without sending an actual signal. Returns `true` if the\n * process exists and is reachable, `false` otherwise.\n *\n * @param pid - the process identifier to probe\n */\nexport function isProcessAlive(pid: number): boolean {\n   try {\n      process.kill(pid, 0);\n      return true;\n   } catch {\n      return false;\n   }\n}\n", "import { spawn } from 'node:child_process';\nimport type { Runtime } from '../../runtime/typings/runtime.ts';\n\n/**\n * Spawns a detached worker daemon process for the given context.\n *\n * @param contextPath - absolute path to the context directory the\n *   daemon should serve\n * @param runtime - the current JavaScript runtime environment\n * @param workerScript - absolute path to the worker daemon script,\n *   resolved at the entry point by `resolveWorkerScript`\n */\nexport function spawnDaemon(\n   contextPath: string,\n   runtime: Runtime,\n   workerScript?: string,\n): void {\n   if (!workerScript) {\n      throw new Error(\n         'workerScript must be provided' + ' (resolve at entry point)',\n      );\n   }\n   const execPath = runtime === 'deno' ? 'deno' : process.execPath;\n\n   const args =\n      runtime === 'deno'\n         ? ['run', '--allow-all', workerScript, contextPath]\n         : [workerScript, contextPath];\n\n   const child = spawn(execPath, args, {\n      detached: true,\n      stdio: 'ignore',\n   });\n   child.unref();\n}\n", "import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\n\n/** Default maximum wait time for the daemon PID file to appear. */\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\n/** Polling interval in milliseconds between existence checks. */\nconst POLL_INTERVAL_MS = 100;\n\n/**\n * Waits for the worker daemon's PID file to appear on disk.\n *\n * Polls every 100 ms until the PID file at\n * `<tmpdir>/kbdb-<contextId>.pid` exists or the timeout elapses.\n *\n * @param contextId - the 16-character context identifier\n * @param timeoutMs - maximum wait time in milliseconds; defaults\n *   to 10 000 ms\n * @returns `true` if the PID file appeared before the timeout,\n *   `false` otherwise\n */\nexport async function waitForDaemon(\n   contextId: string,\n   timeoutMs: number = DEFAULT_TIMEOUT_MS,\n): Promise<boolean> {\n   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);\n   const start = Date.now();\n   while (Date.now() - start < timeoutMs) {\n      if (existsSync(pidPath)) return true;\n      await new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));\n   }\n   return false;\n}\n", "import type { Runtime } from '../typings/runtime.ts';\n\n/**\n * Detects the current JavaScript runtime environment.\n *\n * Returns `'deno'` when the global `Deno` object is present,\n * otherwise returns `'node'`.\n */\nexport function detectRuntime(): Runtime {\n   if (typeof globalThis !== 'undefined' && 'Deno' in globalThis) {\n      return 'deno';\n   }\n   return 'node';\n}\n", "import { join } from 'node:path';\nimport { getTmpdir } from './get-tmpdir.function.ts';\n\n/**\n * Returns the platform-appropriate IPC socket path for a given\n * context identifier.\n *\n * On Windows, returns a named pipe path (`\\\\.\\pipe\\kbdb-<ctx>`).\n * On POSIX systems, returns a Unix domain socket path under the\n * system temp directory (`<tmpdir>/kbdb-<ctx>.sock`).\n *\n * @param ctx - unique context identifier embedded in the path\n */\nexport function getIpcPath(ctx: string): string {\n   if (process.platform === 'win32') {\n      return `\\\\\\\\.\\\\pipe\\\\kbdb-${ctx}`;\n   }\n   return join(getTmpdir(), `kbdb-${ctx}.sock`);\n}\n", "import { tmpdir } from 'node:os';\n\n/**\n * Returns the operating system's default temporary directory path.\n */\nexport function getTmpdir(): string {\n   return tmpdir();\n}\n"],
-  "mappings": "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",
+  "sources": ["../src/shared/version/constants/version.constant.ts", "../src/shared/worker-client/classes/worker-client.class.ts", "../src/shared/worker-client/functions/create-worker-client.function.ts", "../src/shared/worker-client/functions/resolve-db-path.function.ts", "../src/shared/hash/functions/compute-sha256.ts", "../src/shared/worker-client/functions/compute-context-id.function.ts", "../src/shared/worker-client/functions/discover-daemon.function.ts", "../src/shared/platform/functions/is-process-alive.function.ts", "../src/shared/worker-client/functions/spawn-daemon.function.ts", "../src/shared/worker-client/functions/wait-for-daemon.function.ts", "../src/shared/runtime/functions/detect-runtime.ts", "../src/shared/platform/functions/get-ipc-path.function.ts", "../src/shared/platform/functions/get-tmpdir.function.ts", "../src/shared/worker-client/functions/get-or-create-client.function.ts"],
+  "sourcesContent": ["/** Current package version, kept in sync with package.json. */\nexport const VERSION = '0.4.0';\n", "import { connect } from 'node:net';\nimport type { Socket } from 'node:net';\nimport type { SearchParams } from '../typings/search-params.model.ts';\nimport type { PagedSearchResult } from '../typings/search-result.model.ts';\nimport type {\n   AddSectionParams,\n   Section,\n} from '../typings/section.model.ts';\nimport type { StatusResult } from '../typings/status-result.model.ts';\nimport type { AddSectionResult } from '../typings/add-section-result.model.ts';\nimport type { RemoveSectionResult } from '../typings/remove-section-result.model.ts';\nimport type { ContentResult } from '../typings/content-result.model.ts';\nimport type { IntegrityCheckResult } from '../typings/integrity-check-result.model.ts';\nimport type { GcResult } from '../typings/gc-result.model.ts';\nimport type { RebuildResult } from '../typings/rebuild-result.model.ts';\nimport type { MigrateResult } from '../typings/migrate-result.model.ts';\nimport type { VersionStatus } from '../typings/version-status.model.ts';\nimport type { SectionRecord } from '../../wasm-codec/functions/decode-section-records.function.ts';\nimport type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';\nimport type {\n   RecallParams,\n   RecallResult,\n} from '../typings/recall-result.model.ts';\nimport type { ExportResult } from '../typings/export-result.model.ts';\nimport type { ImportResult } from '../typings/import-result.model.ts';\n\n/** Pending JSON-RPC call awaiting a response from the daemon. */\ninterface PendingCall {\n   resolve: (v: unknown) => void;\n   reject: (e: Error) => void;\n   timer?: ReturnType<typeof setTimeout>;\n}\n\n/** Shape of a JSON-RPC 2.0 error object from the daemon. */\ninterface JsonRpcError {\n   readonly code: number;\n   readonly message: string;\n}\n\n/** Shape of a JSON-RPC 2.0 response from the daemon. */\ninterface JsonRpcResponse {\n   readonly id: number;\n   readonly result?: unknown;\n   readonly error?: JsonRpcError;\n}\n\n/**\n * IPC client that communicates with the worker daemon over a Unix\n * domain socket (or Windows named pipe) using JSON-RPC 2.0 with\n * newline-delimited message framing.\n *\n * Call `connect()` before any other method and `disconnect()` when\n * done to release the underlying socket.\n */\nexport class WorkerClient {\n   /** Underlying socket; `null` when not connected. */\n   private socket: Socket | null = null;\n\n   /** Monotonically increasing request ID counter. */\n   private nextId = 1;\n\n   /** Map of outstanding request IDs to their resolve/reject pairs. */\n   private readonly pending = new Map<number, PendingCall>();\n\n   /** Partial line buffer for split TCP/IPC frames. */\n   private buffer = '';\n\n   /**\n    * @param socketPath - absolute path to the daemon's IPC socket\n    *   (or Windows named pipe path)\n    * @param contextId - 16-character context identifier sent as\n    *   `ctx` in every JSON-RPC request\n    * @param requestTimeoutMs - per-request timeout in ms\n    *   (0 or undefined disables the timeout)\n    */\n   constructor(\n      private readonly socketPath: string,\n      private readonly contextId: string,\n      private readonly requestTimeoutMs?: number,\n   ) {}\n\n   /** Whether the underlying socket is connected. */\n   get isConnected(): boolean {\n      return this.socket !== null;\n   }\n\n   /**\n    * Establishes the IPC connection to the worker daemon.\n    *\n    * Retries up to 5 times with exponential backoff on\n    * transient errors (`ENOENT`, `ECONNREFUSED`).\n    *\n    * @throws {Error} if the connection cannot be established\n    */\n   async connect(): Promise<void> {\n      const maxRetries = 5;\n      let delay = 50;\n      for (let attempt = 0; attempt <= maxRetries; attempt++) {\n         try {\n            await this.tryConnect();\n            return;\n         } catch (err: unknown) {\n            const code = (err as NodeJS.ErrnoException).code;\n            const retriable =\n               code === 'ENOENT' || code === 'ECONNREFUSED';\n            if (!retriable || attempt === maxRetries) {\n               throw err;\n            }\n            await new Promise<void>((r) => setTimeout(r, delay));\n            delay = Math.min(delay * 2, 1000);\n         }\n      }\n   }\n\n   /** Destroys the IPC socket and clears the connection state. */\n   disconnect(): void {\n      if (this.socket) {\n         this.socket.destroy();\n         this.socket = null;\n      }\n   }\n\n   /**\n    * Single connection attempt with keepalive and\n    * post-connect failure handlers.\n    */\n   private async tryConnect(): Promise<void> {\n      return new Promise<void>((resolve, reject) => {\n         const sock = connect(this.socketPath, () => {\n            sock.removeListener('error', reject);\n            sock.setKeepAlive(true, 30_000);\n            sock.on('error', (err: Error) => {\n               this.handleSocketFailure(err);\n            });\n            sock.on('close', () => {\n               if (this.pending.size > 0) {\n                  this.handleSocketFailure(\n                     new Error('connection closed'),\n                  );\n               }\n               this.socket = null;\n            });\n            this.socket = sock;\n            resolve();\n         });\n         sock.on('error', reject);\n         sock.on('data', (chunk: Buffer) => {\n            this.handleData(chunk.toString());\n         });\n      });\n   }\n\n   /**\n    * Rejects all pending calls and marks the client as\n    * disconnected.\n    */\n   private handleSocketFailure(err: Error): void {\n      const sock = this.socket;\n      this.socket = null;\n      for (const [id, call] of this.pending) {\n         this.pending.delete(id);\n         if (call.timer) clearTimeout(call.timer);\n         call.reject(err);\n      }\n      if (sock) sock.destroy();\n   }\n\n   /**\n    * Searches the knowledge base.\n    *\n    * @param params - query parameters including the search string\n    * @returns paginated search results with metadata\n    */\n   async search(params: SearchParams): Promise<PagedSearchResult> {\n      return this.call('search', {\n         ...params,\n         algo: params.algo,\n      }) as Promise<PagedSearchResult>;\n   }\n\n   /**\n    * Retrieves full content and context for one or more sections by\n    * their knowledge-base identifiers.\n    *\n    * @param params - section identifier(s) and optional expansion depth\n    * @returns a single `RecallResult` when `kbid` is provided without\n    *   `kbids`, or a `RecallResult[]` when `kbids` is provided\n    */\n   async recall(\n      params: RecallParams,\n   ): Promise<RecallResult | RecallResult[]> {\n      return this.call('recall', params) as Promise<\n         RecallResult | RecallResult[]\n      >;\n   }\n\n   /**\n    * Adds a new section to the knowledge base.\n    *\n    * @param params - section content and metadata\n    * @returns the result including the assigned knowledge-base\n    *   identifier and indexing statistics\n    */\n   async addSection(\n      params: AddSectionParams,\n   ): Promise<AddSectionResult> {\n      return this.call(\n         'addSection',\n         params,\n      ) as Promise<AddSectionResult>;\n   }\n\n   /**\n    * Replaces an existing section's content and metadata.\n    *\n    * @param kbid - identifier of the section to update\n    * @param params - new content and metadata\n    * @returns the knowledge-base identifier of the updated section\n    */\n   async updateSection(\n      kbid: string,\n      params: AddSectionParams,\n   ): Promise<string> {\n      return this.call('updateSection', {\n         kbid,\n         ...params,\n      }) as Promise<string>;\n   }\n\n   /**\n    * Removes a section from the knowledge base.\n    *\n    * @param kbid - identifier of the section to remove\n    * @returns removal result with `removed` flag and elapsed time\n    */\n   async removeSection(kbid: string): Promise<RemoveSectionResult> {\n      return this.call('removeSection', {\n         kbid,\n      }) as Promise<RemoveSectionResult>;\n   }\n\n   /**\n    * Retrieves multiple sections by their identifiers.\n    *\n    * @param kbids - list of knowledge-base identifiers to fetch\n    * @returns sections in the order their IDs were requested\n    */\n   async readSections(kbids: string[]): Promise<Section[]> {\n      return this.call('readSections', {\n         kbids,\n      }) as Promise<Section[]>;\n   }\n\n   /**\n    * Groups a set of sections under a named document.\n    *\n    * @param title - human-readable document title\n    * @param kbids - identifiers of the sections to group\n    * @param docType - application-level document type tag; omit or\n    *   pass an empty string for untagged documents\n    * @returns the assigned document identifier\n    */\n   async groupSections(\n      title: string,\n      kbids: string[],\n      docType?: string,\n   ): Promise<string> {\n      const result = (await this.call('groupSections', {\n         title,\n         kbids,\n         docType: docType ?? '',\n      })) as { docid: string } | string;\n      return typeof result === 'string' ? result : result.docid;\n   }\n\n   /**\n    * Removes the document grouping for the given document.\n    *\n    * The sections themselves are not deleted; only the grouping\n    * record is removed.\n    *\n    * @param docid - identifier of the document grouping to remove\n    */\n   async removeGrouping(docid: string): Promise<void> {\n      await this.call('removeGrouping', { docid });\n   }\n\n   /**\n    * Retrieves a full document record including its sections.\n    *\n    * @param docid - identifier of the document to retrieve\n    * @returns the document record as returned by the daemon\n    */\n   async retrieveDocument(docid: string): Promise<unknown> {\n      return this.call('retrieveDocument', { docid });\n   }\n\n   /**\n    * Composes a rendered Markdown document from one or more kbid\n    * or docid identifiers.\n    *\n    * @param ids - list of kbid or docid identifiers (may be mixed)\n    * @returns composed Markdown result with character count\n    */\n   async content(ids: string[]): Promise<ContentResult> {\n      return this.call('content', { ids }) as Promise<ContentResult>;\n   }\n\n   /**\n    * Runs an integrity check on the knowledge-base database.\n    *\n    * @returns a report of all issues found; `ok` is `true` when\n    *   no errors were detected\n    */\n   async integrityCheck(): Promise<IntegrityCheckResult> {\n      return this.call(\n         'integrityCheck',\n         {},\n      ) as Promise<IntegrityCheckResult>;\n   }\n\n   /**\n    * Removes unreferenced sections from the database.\n    *\n    * @returns a report of sections removed and bytes freed\n    */\n   async gc(): Promise<GcResult> {\n      return this.call('gc', {}) as Promise<GcResult>;\n   }\n\n   /**\n    * Reconstructs all index files from section files and document\n    * manifests on disk. Text and code sections are re-tokenized;\n    * image sections are skipped.\n    *\n    * @returns a report of sections and terms re-indexed\n    */\n   async rebuildIndexes(): Promise<RebuildResult> {\n      return this.call('rebuildIndexes', {}) as Promise<RebuildResult>;\n   }\n\n   /**\n    * Invalidates the in-memory cache entry for a single section.\n    *\n    * @param kbid - identifier of the section to evict from cache\n    */\n   async invalidate(kbid: string): Promise<void> {\n      await this.call('invalidate', { kbid });\n   }\n\n   /** Clears all entries from the daemon's in-memory cache. */\n   async invalidateAll(): Promise<void> {\n      await this.call('invalidateAll', {});\n   }\n\n   /**\n    * Retrieves diagnostic status information from the daemon.\n    *\n    * @returns current initialization state and cache statistics\n    */\n   async status(): Promise<StatusResult> {\n      return this.call('status', {}) as Promise<StatusResult>;\n   }\n\n   /**\n    * Returns database metadata and status from the daemon,\n    * including document count, section count, index size, and\n    * cache statistics.\n    *\n    * @returns database metadata from the daemon's cached state\n    */\n   async dbStatus(): Promise<StatusResult> {\n      return this.call('dbStatus', {}) as Promise<StatusResult>;\n   }\n\n   /**\n    * Initialises a new `.kbdb` database directory at the given path\n    * by sending an init request to the worker daemon.\n    *\n    * The daemon creates all required subdirectories and seed files via\n    * the `worker_init_directory` WASM export.\n    *\n    * @param targetPath - absolute path to the directory that will\n    *   contain the new `.kbdb` database\n    * @throws {Error} if the `.kbdb` directory already exists or the\n    *   daemon cannot create the layout\n    */\n   async initDirectory(targetPath: string): Promise<void> {\n      await this.call('initDirectory', { targetPath });\n   }\n\n   /**\n    * Runs all pending database migrations for the `.kbdb` directory\n    * at the given path.\n    *\n    * Delegates to the `worker_migrate` WASM export on the daemon.\n    * Each migration step updates `catalog.toml` on success, so\n    * retrying after a partial failure is safe.\n    *\n    * @param targetPath - absolute path to the `.kbdb` database root\n    * @returns migration report with old version, new version, and\n    *   number of migration steps applied\n    */\n   async migrateDatabase(targetPath: string): Promise<MigrateResult> {\n      return this.call('migrateDatabase', {\n         targetPath,\n      }) as Promise<MigrateResult>;\n   }\n\n   /**\n    * Checks the format version of the `.kbdb` database at the given\n    * path against the version required by the current WASM engine.\n    *\n    * This is a read-only operation: it reads `catalog.toml` and\n    * returns the compatibility status without making any changes.\n    *\n    * @param targetPath - absolute path to the `.kbdb` database root\n    * @returns version compatibility report\n    */\n   async checkVersion(targetPath: string): Promise<VersionStatus> {\n      return this.call('checkVersion', {\n         targetPath,\n      }) as Promise<VersionStatus>;\n   }\n\n   /**\n    * Retrieves all sections whose type name matches the given string.\n    *\n    * @param sectionType - the application-level type name to filter by\n    * @returns all section records with a matching type name\n    */\n   async listByType(sectionType: string): Promise<SectionRecord[]> {\n      return this.call('listByType', {\n         sectionType,\n      }) as Promise<SectionRecord[]>;\n   }\n\n   /**\n    * Retrieves all documents whose type name matches the given string.\n    *\n    * @param docType - the application-level document type to filter by\n    * @returns all document manifests with a matching type name\n    */\n   async listDocumentsByType(\n      docType: string,\n   ): Promise<DocumentManifest[]> {\n      return this.call('listDocumentsByType', {\n         docType,\n      }) as Promise<DocumentManifest[]>;\n   }\n\n   /**\n    * Exports the database to a target directory on disk.\n    *\n    * Copies section files, document manifests, and `catalog.toml`\n    * to `params.path`. Index files are not exported because they\n    * are derivable from the section and document data.\n    *\n    * @param params - optional export parameters\n    * @param params.path - target directory path; defaults to\n    *   `./kbdb-export/` when not provided\n    * @returns export report with the resolved path and file counts\n    */\n   async export(params?: {\n      path?: string;\n      format?: string;\n   }): Promise<ExportResult> {\n      return this.call('export', {\n         targetPath: params?.path || undefined,\n         format: params?.format,\n      }) as Promise<ExportResult>;\n   }\n\n   /**\n    * Imports an exported database from the given path.\n    *\n    * @param params - source path and dry-run flag\n    * @returns import report with counts and timing\n    */\n   async import(params: {\n      from: string;\n      dryRun: boolean;\n   }): Promise<ImportResult> {\n      return this.call('importDb', {\n         sourcePath: params.from,\n         dryRun: params.dryRun,\n      }) as Promise<ImportResult>;\n   }\n\n   /**\n    * Sends a JSON-RPC 2.0 request and awaits the response.\n    *\n    * @param method - the RPC method name\n    * @param params - parameters to include in the request\n    * @throws {Error} if not connected\n    * @throws {Error} when the daemon returns an error response\n    */\n   private async call(\n      method: string,\n      params: unknown,\n   ): Promise<unknown> {\n      const socket = this.socket;\n      if (!socket) {\n         throw new Error('not connected');\n      }\n\n      const id = this.nextId++;\n      const request = {\n         jsonrpc: '2.0',\n         id,\n         method,\n         params: { ctx: this.contextId, ...(params as object) },\n      };\n\n      const timeoutMs = this.requestTimeoutMs;\n      return new Promise<unknown>((resolve, reject) => {\n         const call: PendingCall = { resolve, reject };\n         if (timeoutMs) {\n            call.timer = setTimeout(() => {\n               if (!this.pending.has(id)) return;\n               this.pending.delete(id);\n               const err = new Error(\n                  `request timeout after ${String(timeoutMs)}ms`,\n               );\n               (err as unknown as Record<string, unknown>).code =\n                  'REQUEST_TIMEOUT';\n               reject(err);\n            }, timeoutMs);\n         }\n         this.pending.set(id, call);\n         socket.write(JSON.stringify(request) + '\\n');\n      });\n   }\n\n   /**\n    * Processes incoming data from the socket, splitting on newlines\n    * and dispatching complete JSON-RPC response objects.\n    *\n    * @param data - raw string chunk received from the socket\n    */\n   private handleData(data: string): void {\n      this.buffer += data;\n      const lines = this.buffer.split('\\n');\n      this.buffer = lines.pop() ?? '';\n\n      for (const line of lines) {\n         if (!line.trim()) continue;\n         try {\n            const response = JSON.parse(line) as JsonRpcResponse;\n            const pending = this.pending.get(response.id);\n            if (pending) {\n               this.pending.delete(response.id);\n               if (pending.timer) clearTimeout(pending.timer);\n               if (response.error) {\n                  const err = new Error(response.error.message);\n                  (err as unknown as Record<string, unknown>).code =\n                     response.error.code;\n                  pending.reject(err);\n               } else {\n                  pending.resolve(response.result);\n               }\n            }\n         } catch {\n            // Ignore unparseable lines\n         }\n      }\n   }\n}\n", "import { existsSync, readFileSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { WorkerClient } from '../classes/worker-client.class.ts';\nimport { resolveDbPath } from './resolve-db-path.function.ts';\nimport { computeContextId } from './compute-context-id.function.ts';\nimport { discoverDaemon } from './discover-daemon.function.ts';\nimport { spawnDaemon } from './spawn-daemon.function.ts';\nimport { waitForDaemon } from './wait-for-daemon.function.ts';\nimport { detectRuntime } from '../../runtime/functions/detect-runtime.ts';\nimport { getIpcPath } from '../../platform/functions/get-ipc-path.function.ts';\nimport type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';\n\n/**\n * Creates and connects a `WorkerClient` to the worker daemon.\n *\n * Resolves the context path, derives a stable context identifier,\n * and checks whether a daemon is already running. If no daemon is\n * found and `autoSpawn` is not `false`, a new daemon process is\n * spawned and the factory waits for its PID file to appear before\n * connecting.\n *\n * @param options - optional configuration for path resolution,\n *   auto-spawn behaviour, and connection timeout\n * @returns a connected `WorkerClient` ready to send requests\n * @throws {Error} if the `.kbdb` directory cannot be found\n * @throws {Error} if the socket connection cannot be established\n */\nexport async function createWorkerClient(\n   options?: WorkerClientOptions,\n): Promise<WorkerClient> {\n   const dbPath =\n      options?.contextPath ?? resolveDbPath(options?.dbPath);\n   const contextId = await computeContextId(dbPath);\n   const socketPath = getIpcPath(contextId);\n\n   let daemon = discoverDaemon(contextId);\n\n   if (!daemon && options?.autoSpawn !== false) {\n      const runtime = detectRuntime();\n      spawnDaemon(dbPath, runtime, options?.workerScript);\n      await waitForDaemon(contextId, options?.connectTimeoutMs);\n      daemon = discoverDaemon(contextId);\n   }\n\n   if (!daemon) {\n      throw new Error(\n         `kbdb worker daemon did not start: ${readCrashReason(contextId)}`,\n      );\n   }\n\n   const client = new WorkerClient(\n      socketPath,\n      contextId,\n      options?.requestTimeoutMs,\n   );\n   await client.connect();\n   return client;\n}\n\nfunction readCrashReason(contextId: string): string {\n   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);\n   if (!existsSync(crashPath)) {\n      return 'daemon failed to start (no details available)';\n   }\n   try {\n      const raw = readFileSync(crashPath, 'utf-8');\n      const crash = JSON.parse(raw) as { error?: string };\n      unlinkSync(crashPath);\n      return crash.error ?? 'unknown error (crash log empty)';\n   } catch {\n      return 'daemon failed to start (crash log unreadable)';\n   }\n}\n", "import { existsSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\n\n/**\n * Resolves the absolute path to the `.kbdb` database directory.\n *\n * Searches for a `.kbdb` sub-directory inside `targetDir`. When\n * `targetDir` is omitted, `process.cwd()` is used as the base.\n *\n * @param targetDir - directory to search in; defaults to cwd\n * @throws {Error} if no `.kbdb` directory exists at the resolved\n *   path\n */\nexport function resolveDbPath(targetDir?: string): string {\n   const base = targetDir ? resolve(targetDir) : process.cwd();\n   const dbPath = join(base, '.kbdb');\n   if (!existsSync(dbPath)) {\n      throw new Error(`database not found: ${dbPath}`);\n   }\n   return dbPath;\n}\n", "/**\n * Computes the SHA-256 hash of a UTF-8 string.\n *\n * Uses the Web Crypto API (`crypto.subtle`), which is available\n * in both Deno and Node.js >= 20 without additional imports.\n *\n * @param input - the string to hash\n * @returns lowercase hex-encoded SHA-256 digest (64 characters)\n */\nexport async function computeSha256(input: string): Promise<string> {\n   const data = new TextEncoder().encode(input);\n   const hash = await crypto.subtle.digest('SHA-256', data);\n   const bytes = new Uint8Array(hash);\n   return Array.from(bytes)\n      .map((b) => b.toString(16).padStart(2, '0'))\n      .join('');\n}\n", "import { computeSha256 } from '../../hash/functions/compute-sha256.ts';\n\n/**\n * Computes a short context identifier for an absolute path.\n *\n * Hashes the path with SHA-256 and returns the first 16 hex\n * characters. The result is stable for the same input and unique\n * enough to avoid accidental collisions across typical path sets.\n *\n * @param absolutePath - the absolute filesystem path to identify\n * @returns a 16-character lowercase hex string\n */\nexport async function computeContextId(\n   absolutePath: string,\n): Promise<string> {\n   const hash = await computeSha256(absolutePath);\n   return hash.slice(0, 16);\n}\n", "import { existsSync, readFileSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { isProcessAlive } from '../../platform/functions/is-process-alive.function.ts';\nimport type { DaemonInfo } from '../typings/daemon-info.model.ts';\n\nexport type { DaemonInfo };\n\n/**\n * Discovers a running worker daemon for the given context.\n *\n * Reads the PID file at `<tmpdir>/kbdb-<contextId>.pid`. If the\n * file exists and the process is alive, returns its PID and the\n * expected socket path. If the file is stale (process dead or PID\n * unparseable), removes the PID file and returns `null`.\n *\n * @param contextId - the 16-character context identifier\n * @returns daemon location info, or `null` if no live daemon found\n */\nexport function discoverDaemon(contextId: string): DaemonInfo | null {\n   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);\n\n   if (!existsSync(pidPath)) return null;\n\n   const pidStr = readFileSync(pidPath, 'utf-8').trim();\n   const pid = parseInt(pidStr, 10);\n\n   if (isNaN(pid) || !isProcessAlive(pid)) {\n      try {\n         unlinkSync(pidPath);\n      } catch {\n         // Stale PID file removal is best-effort\n      }\n      return null;\n   }\n\n   const socketPath = join(tmpdir(), `kbdb-${contextId}.sock`);\n\n   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);\n   try {\n      unlinkSync(crashPath);\n   } catch {\n      // stale crash file removal is best-effort\n   }\n\n   return { pid, socketPath };\n}\n", "/**\n * Checks whether a process with the given PID is alive.\n *\n * Sends signal `0` to the process, which performs a permission\n * check without sending an actual signal. Returns `true` if the\n * process exists and is reachable, `false` otherwise.\n *\n * @param pid - the process identifier to probe\n */\nexport function isProcessAlive(pid: number): boolean {\n   try {\n      process.kill(pid, 0);\n      return true;\n   } catch {\n      return false;\n   }\n}\n", "import { spawn } from 'node:child_process';\nimport type { Runtime } from '../../runtime/typings/runtime.ts';\n\n/**\n * Spawns a detached worker daemon process for the given context.\n *\n * @param contextPath - absolute path to the context directory the\n *   daemon should serve\n * @param runtime - the current JavaScript runtime environment\n * @param workerScript - absolute path to the worker daemon script,\n *   resolved at the entry point by `resolveWorkerScript`\n */\nexport function spawnDaemon(\n   contextPath: string,\n   runtime: Runtime,\n   workerScript?: string,\n): void {\n   if (!workerScript) {\n      throw new Error(\n         'workerScript must be provided' + ' (resolve at entry point)',\n      );\n   }\n   const execPath = runtime === 'deno' ? 'deno' : process.execPath;\n\n   const args =\n      runtime === 'deno'\n         ? ['run', '--allow-all', workerScript, contextPath]\n         : [workerScript, contextPath];\n\n   const child = spawn(execPath, args, {\n      detached: true,\n      stdio: 'ignore',\n   });\n   child.unref();\n}\n", "import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\n\n/** Default maximum wait time for the daemon PID file to appear. */\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\n/** Polling interval in milliseconds between existence checks. */\nconst POLL_INTERVAL_MS = 100;\n\n/**\n * Waits for the worker daemon's PID file to appear on disk.\n *\n * Polls every 100 ms until the PID file at\n * `<tmpdir>/kbdb-<contextId>.pid` exists or the timeout elapses.\n *\n * @param contextId - the 16-character context identifier\n * @param timeoutMs - maximum wait time in milliseconds; defaults\n *   to 10 000 ms\n * @returns `true` if the PID file appeared before the timeout,\n *   `false` otherwise\n */\nexport async function waitForDaemon(\n   contextId: string,\n   timeoutMs: number = DEFAULT_TIMEOUT_MS,\n): Promise<boolean> {\n   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);\n   const start = Date.now();\n   while (Date.now() - start < timeoutMs) {\n      if (existsSync(pidPath)) return true;\n      await new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));\n   }\n   return false;\n}\n", "import type { Runtime } from '../typings/runtime.ts';\n\n/**\n * Detects the current JavaScript runtime environment.\n *\n * Returns `'deno'` when the global `Deno` object is present,\n * otherwise returns `'node'`.\n */\nexport function detectRuntime(): Runtime {\n   if (typeof globalThis !== 'undefined' && 'Deno' in globalThis) {\n      return 'deno';\n   }\n   return 'node';\n}\n", "import { join } from 'node:path';\nimport { getTmpdir } from './get-tmpdir.function.ts';\n\n/**\n * Returns the platform-appropriate IPC socket path for a given\n * context identifier.\n *\n * On Windows, returns a named pipe path (`\\\\.\\pipe\\kbdb-<ctx>`).\n * On POSIX systems, returns a Unix domain socket path under the\n * system temp directory (`<tmpdir>/kbdb-<ctx>.sock`).\n *\n * @param ctx - unique context identifier embedded in the path\n */\nexport function getIpcPath(ctx: string): string {\n   if (process.platform === 'win32') {\n      return `\\\\\\\\.\\\\pipe\\\\kbdb-${ctx}`;\n   }\n   return join(getTmpdir(), `kbdb-${ctx}.sock`);\n}\n", "import { tmpdir } from 'node:os';\n\n/**\n * Returns the operating system's default temporary directory path.\n */\nexport function getTmpdir(): string {\n   return tmpdir();\n}\n", "import { createWorkerClient } from './create-worker-client.function.ts';\nimport type { WorkerClient } from '../classes/worker-client.class.ts';\nimport type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';\nimport { resolveDbPath } from './resolve-db-path.function.ts';\n\n/** Cache of connected clients keyed by database path. */\nconst cache = new Map<string, WorkerClient>();\n\n/**\n * Returns a cached `WorkerClient` for the given context\n * path, or creates and caches a new one if the cached\n * client is disconnected or absent.\n *\n * Intended for library consumers and the MCP server. CLI\n * one-shots should use `createWorkerClient()` directly.\n *\n * @param options - optional configuration forwarded to\n *   `createWorkerClient`\n * @returns a connected `WorkerClient`\n */\nexport async function getOrCreateClient(\n   options?: WorkerClientOptions,\n): Promise<WorkerClient> {\n   const dbPath =\n      options?.contextPath ?? resolveDbPath(options?.dbPath);\n   const cached = cache.get(dbPath);\n   if (cached?.isConnected) return cached;\n   cache.delete(dbPath);\n   const client = await createWorkerClient(options);\n   cache.set(dbPath, client);\n   return client;\n}\n\n/**\n * Clears the internal client cache. Intended for tests\n * that need isolation between runs.\n */\nexport function clearClientCache(): void {\n   for (const [key, client] of cache) {\n      client.disconnect();\n      cache.delete(key);\n   }\n}\n"],
+  "mappings": "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",
   "names": ["resolve", "existsSync", "readFileSync", "unlinkSync", "join", "tmpdir", "existsSync", "join", "join", "existsSync", "existsSync", "join", "tmpdir", "join", "tmpdir", "join", "join", "tmpdir", "existsSync", "readFileSync", "unlinkSync"]
 }

package/dist/src/shared/cli/functions/dispatch-command.function.d.ts

@@ -20,6 +20,7 @@ import type { AgentGetClient } from './run-agent-get.function.ts';
 import type { AgentDeleteClient } from './run-agent-delete.function.ts';
 import type { RecallClient } from './run-recall.function.ts';
 import type { ExportClient } from './run-export.function.ts';
+import type { ImportClient } from './run-import.function.ts';
 /**
  * Intersection of all data-command client interfaces.
  *
@@ -27,7 +28,7 @@ import type { ExportClient } from './run-export.function.ts';
  * intersection combines them so `dispatchCommand` can route
  * to any command handler with full type safety.
  */
-export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient & RecallClient & ExportClient;
+export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient & RecallClient & ExportClient & ImportClient;
 /**
  * Routes a parsed CLI command to the appropriate handler and
  * returns a `CommandResult` without touching process globals.

package/dist/src/shared/cli/functions/find-db.function.d.ts

@@ -1,13 +1,12 @@
 /**
- * Resolves the absolute path to the `.kbdb` database directory
- * under the given base path (or the current working directory).
+ * Locates the `.kbdb` database directory.
  *
- * Unlike `ensureDb`, this function is purely read-only: it never
- * creates the directory. Returns `null` when the `.kbdb` directory
- * does not exist.
+ * When `dbPath` is provided, checks only that directory.
+ * When omitted, walks up from the current working directory
+ * until a `.kbdb` directory is found or the filesystem root
+ * is reached.
  *
- * @param dbPath - optional path to the knowledge-base root directory
- * @returns absolute path to the `.kbdb` directory, or `null` when
- *   it does not exist
+ * @param dbPath - explicit base directory; skips traversal
+ * @returns absolute path to `.kbdb`, or `null` when not found
  */
 export declare function findDb(dbPath?: string): string | null;

package/dist/src/shared/cli/functions/handle-mcp.function.d.ts

@@ -8,7 +8,7 @@ import type { CliDeps } from '../typings/cli-deps.interface.ts';
  * the version gate, and starts the MCP server. Disconnects the
  * worker client when finished.
  *
- * @param options - parsed CLI options (uses `dbPath` and env fallback)
+ * @param options - parsed CLI options
  * @param deps - injectable CLI dependencies
  * @returns a `CommandResult` with `exitCode: 0` on success
  */

package/dist/src/shared/cli/functions/parse-args.function.d.ts

@@ -8,9 +8,10 @@ import type { CliOptions } from '../typings/cli-options.interface.ts';
  * becomes the command; subsequent non-flag tokens become `args`.
  *
  * Compound commands are supported: when the first positional token is
- * a group name (`db`, `skill`, or `agent`), the next positional token
- * is joined with a hyphen to form the compound command
- * (e.g. `db init` → `'db-init'`).
+ * a group name (`db`, `skill`, `agent`, or `worker`), the next
+ * positional token is joined with a hyphen to form the compound
+ * command (e.g. `db init` → `'db-init'`,
+ * `worker stop` → `'worker-stop'`).
  *
  * Context-aware `--help`: when `--help` or `-h` appears after a
  * command has been set, the existing command is moved to `args[0]`

package/dist/src/shared/cli/functions/resolve-kbid-prefix.function.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal client interface for listing section kbids.
+ *
+ * Decouples prefix resolution from the concrete
+ * `WorkerClient` so tests can use lightweight mocks.
+ */
+export interface PrefixResolver {
+    /** Returns all sections of the given type. */
+    listByType(sectionType: string): Promise<readonly {
+        kbid: string;
+    }[]>;
+}
+/**
+ * Resolves a potentially short kbid prefix to its full
+ * 26-character identifier.
+ *
+ * Full-length identifiers (>= 26 chars) are returned as-is.
+ * For shorter prefixes, all section types are scanned to find
+ * matching kbids. Throws when no match is found or the prefix
+ * is ambiguous (matches more than one kbid).
+ *
+ * @param prefix - full or partial kbid string
+ * @param client - client providing `listByType`
+ * @returns the resolved full kbid
+ * @throws when no match or ambiguous match is found
+ */
+export declare function resolveKbidPrefix(prefix: string, client: PrefixResolver): Promise<string>;

package/dist/src/shared/cli/functions/resolve-raw-db-path.function.d.ts

@@ -0,0 +1,10 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/**
+ * Resolves the explicit database path from CLI
+ * options or the `KBDB_DB_DIR` environment variable.
+ *
+ * Returns `undefined` when neither is set so that
+ * `findDb` can fall back to upward directory
+ * traversal from the current working directory.
+ */
+export declare function resolveRawDbPath(options: Pick<CliOptions, 'dbPath'>): string | undefined;

package/dist/src/shared/cli/functions/run-cli.function.d.ts

@@ -18,13 +18,15 @@ export interface DisconnectableClient extends DispatchClient {
  */
 export interface CliDeps {
     isStdinTty: () => boolean;
+    isStdoutTty: () => boolean;
     promptUser: (question: string) => Promise<string>;
     createWorkerClient: (opts: {
         contextPath: string;
+        requestTimeoutMs?: number;
     }) => Promise<DisconnectableClient>;
     findDb: (basePath?: string) => string | null;
     runInit: (options: CliOptions) => InitResult;
-    startMcpServer?: (contextPath: string) => Promise<void>;
+    startMcpServer?: (contextPath: string, clientFactory?: () => Promise<DisconnectableClient>, maxRetries?: number) => Promise<void>;
 }
 /**
  * Full CLI orchestrator extracted from `src/cli.ts`.

package/dist/src/shared/cli/functions/run-content.function.d.ts

@@ -1,4 +1,5 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { PrefixResolver } from './resolve-kbid-prefix.function.ts';
 /** Result returned by content composition. */
 interface ContentResult {
     /** MIME type of the composed output, always `'text/markdown'`. */
@@ -13,8 +14,10 @@ interface ContentResult {
  *
  * Decouples the CLI function from the concrete `WorkerClient`
  * implementation, making it straightforward to test with mocks.
+ * Extends `PrefixResolver` so short kbid prefixes can be resolved
+ * before the content call is made.
  */
-export interface ContentClient {
+export interface ContentClient extends PrefixResolver {
     /**
      * Composes a rendered Markdown document from one or more kbid
      * or docid identifiers.
@@ -28,13 +31,15 @@ export interface ContentClient {
  * Composes and returns a rendered Markdown document from the
  * identifiers listed in `options.args`.
  *
- * Delegates to `client.content(ids)`. The caller is responsible for
- * writing the result to stdout.
+ * Short kbid prefixes in `options.args` are resolved to full
+ * identifiers before calling `client.content`. The caller is
+ * responsible for writing the result to stdout.
  *
  * @param client - content client to delegate composition to
  * @param options - parsed CLI options whose `args` list the kbid or
  *   docid identifiers to compose
  * @returns the composed content result from the daemon
+ * @throws when a prefix matches no section or is ambiguous
  */
 export declare function runContent(client: ContentClient, options: CliOptions): Promise<ContentResult>;
 export {};

package/dist/src/shared/cli/functions/run-import.function.d.ts

@@ -0,0 +1,27 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { ImportResult } from '../../worker-client/typings/import-result.model.ts';
+/**
+ * Minimal client interface required by `runImport`.
+ */
+export interface ImportClient {
+    /**
+     * Imports an exported database from the given directory.
+     *
+     * @param params - source path and dry-run flag
+     * @returns import report with counts and timing
+     */
+    import(params: {
+        from: string;
+        dryRun: boolean;
+    }): Promise<ImportResult>;
+}
+/**
+ * Imports an exported knowledge-base from the path specified by
+ * `--from`, delegating to the worker client.
+ *
+ * @param client - import client to delegate to
+ * @param options - parsed CLI options with `from` path
+ * @returns the import result with section/document counts
+ * @throws when `--from` is not provided
+ */
+export declare function runImport(client: ImportClient, options: CliOptions): Promise<ImportResult>;

package/dist/src/shared/cli/functions/run-recall.function.d.ts

@@ -1,12 +1,15 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
+import type { PrefixResolver } from './resolve-kbid-prefix.function.ts';
 /**
  * Minimal client interface required by `runRecall`.
  *
  * Decouples the CLI function from the concrete `WorkerClient`
  * implementation, making it straightforward to test with mocks.
+ * Extends `PrefixResolver` so short kbid prefixes can be resolved
+ * before the recall call is made.
  */
-export interface RecallClient {
+export interface RecallClient extends PrefixResolver {
     /**
      * Retrieves full content and context for one or more sections
      * by their knowledge-base identifiers.
@@ -27,9 +30,11 @@ export interface RecallClient {
  * sections by kbid via the provided client.
  *
  * Returns an error result when no kbids are provided in
- * `options.args`. For a single kbid, calls `client.recall` with the
- * `kbid` parameter and returns the single `RecallResult`. For
- * multiple kbids, calls `client.recall` with the `kbids` array.
+ * `options.args`. Short kbid prefixes in `options.args` are
+ * resolved to full identifiers before the recall call. For a single
+ * kbid, calls `client.recall` with the `kbid` parameter and returns
+ * the single `RecallResult`. For multiple kbids, calls
+ * `client.recall` with the `kbids` array.
  *
  * The `depth` option is read from `options.depth`, defaulting to 0
  * and clamped to the range 0--3.
@@ -39,6 +44,7 @@ export interface RecallClient {
  *   expansion depth in `depth`
  * @returns the `RecallResult` or `RecallResult[]` from the client,
  *   or an error object when no kbids are provided
+ * @throws when a prefix matches no section or is ambiguous
  */
 export declare function runRecall(client: RecallClient, options: CliOptions): Promise<RecallResult | RecallResult[] | {
     error: string;