@dikolab/kbdb 0.3.2 → 0.4.1

package/dist/src/shared/worker-client/classes/worker-client.class.d.ts

@@ -14,6 +14,7 @@ import type { SectionRecord } from '../../wasm-codec/functions/decode-section-re
 import type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';
 import type { RecallParams, RecallResult } from '../typings/recall-result.model.ts';
 import type { ExportResult } from '../typings/export-result.model.ts';
+import type { ImportResult } from '../typings/import-result.model.ts';
 /**
  * IPC client that communicates with the worker daemon over a Unix
  * domain socket (or Windows named pipe) using JSON-RPC 2.0 with
@@ -25,6 +26,7 @@ import type { ExportResult } from '../typings/export-result.model.ts';
 export declare class WorkerClient {
     private readonly socketPath;
     private readonly contextId;
+    private readonly requestTimeoutMs?;
     /** Underlying socket; `null` when not connected. */
     private socket;
     /** Monotonically increasing request ID counter. */
@@ -38,16 +40,40 @@ export declare class WorkerClient {
      *   (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: string, contextId: string);
+    constructor(socketPath: string, contextId: string, requestTimeoutMs?: number | undefined);
+    /** Whether the underlying socket is connected. */
+    get isConnected(): boolean;
     /**
      * 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
      */
     connect(): Promise<void>;
     /** Destroys the IPC socket and clears the connection state. */
     disconnect(): void;
+    /**
+     * Kills the daemon process and disconnects the client.
+     *
+     * Discovers the daemon via PID file and sends `SIGTERM`.
+     * Always disconnects the socket regardless of kill outcome.
+     */
+    killDaemon(): void;
+    /**
+     * Single connection attempt with keepalive and
+     * post-connect failure handlers.
+     */
+    private tryConnect;
+    /**
+     * Rejects all pending calls and marks the client as
+     * disconnected.
+     */
+    private handleSocketFailure;
     /**
      * Searches the knowledge base.
      *
@@ -236,7 +262,18 @@ export declare class WorkerClient {
      */
     export(params?: {
         path?: string;
+        format?: string;
     }): Promise<ExportResult>;
+    /**
+     * Imports an exported database from the given path.
+     *
+     * @param params - source path and dry-run flag
+     * @returns import report with counts and timing
+     */
+    import(params: {
+        from: string;
+        dryRun: boolean;
+    }): Promise<ImportResult>;
     /**
      * Sends a JSON-RPC 2.0 request and awaits the response.
      *

package/dist/src/shared/worker-client/constants/request-timeout.constant.d.ts

@@ -0,0 +1,2 @@
+/** Default per-request timeout for daemon IPC calls (ms). */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;

package/dist/src/shared/worker-client/constants/retry-defaults.constant.d.ts

@@ -0,0 +1,2 @@
+/** Default number of retries on request timeout. */
+export declare const DEFAULT_RETRY_COUNT = 5;

package/dist/src/shared/worker-client/functions/get-or-create-client.function.d.ts

@@ -0,0 +1,20 @@
+import type { WorkerClient } from '../classes/worker-client.class.ts';
+import type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';
+/**
+ * Returns a cached `WorkerClient` for the given context
+ * path, or creates and caches a new one if the cached
+ * client is disconnected or absent.
+ *
+ * Intended for library consumers and the MCP server. CLI
+ * one-shots should use `createWorkerClient()` directly.
+ *
+ * @param options - optional configuration forwarded to
+ *   `createWorkerClient`
+ * @returns a connected `WorkerClient`
+ */
+export declare function getOrCreateClient(options?: WorkerClientOptions): Promise<WorkerClient>;
+/**
+ * Clears the internal client cache. Intended for tests
+ * that need isolation between runs.
+ */
+export declare function clearClientCache(): void;

package/dist/src/shared/worker-client/functions/retry-on-timeout.function.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Retries an operation when the daemon responds with
+ * a `REQUEST_TIMEOUT` error. Each retry disconnects
+ * the current client, creates a fresh one (which
+ * auto-spawns the daemon), and re-runs the operation.
+ *
+ * @param createClient - factory that returns a connected client
+ * @param operation - the work to perform with the client
+ * @param maxRetries - maximum retry attempts
+ * @returns the final client and result
+ */
+export declare function retryOnTimeout<TClient extends {
+    disconnect(): void;
+    killDaemon?: () => void;
+}, TResult>(createClient: () => Promise<TClient>, operation: (client: TClient) => Promise<TResult>, maxRetries: number): Promise<{
+    client: TClient;
+    result: TResult;
+}>;

package/dist/src/shared/worker-client/index.d.ts

@@ -1,5 +1,6 @@
 export { WorkerClient } from './classes/worker-client.class.ts';
 export { createWorkerClient } from './functions/create-worker-client.function.ts';
+export { getOrCreateClient, clearClientCache, } from './functions/get-or-create-client.function.ts';
 export { resolveDbPath } from './functions/resolve-db-path.function.ts';
 export { computeContextId } from './functions/compute-context-id.function.ts';
 export { discoverDaemon } from './functions/discover-daemon.function.ts';
@@ -15,9 +16,11 @@ export type { DaemonInfo } from './typings/daemon-info.model.ts';
 export type { AddSectionResult, NearDuplicateEntry, } from './typings/add-section-result.model.ts';
 export type { RemoveSectionResult } from './typings/remove-section-result.model.ts';
 export type { ContentResult } from './typings/content-result.model.ts';
-export type { IntegrityCheckResult, IntegrityError, } from './typings/integrity-check-result.model.ts';
+export type { IntegrityCheckResult, IntegrityError, SemanticContradictionEntry, } from './typings/integrity-check-result.model.ts';
 export type { GcResult } from './typings/gc-result.model.ts';
 export type { RebuildResult } from './typings/rebuild-result.model.ts';
 export type { MigrateResult } from './typings/migrate-result.model.ts';
 export type { VersionCompatibility, VersionStatus, } from './typings/version-status.model.ts';
 export type { RecallParams, RecallResult, RecallDocument, RecallSibling, RecallReference, } from './typings/recall-result.model.ts';
+export type { ImportResult } from './typings/import-result.model.ts';
+export type { ExportResult } from './typings/export-result.model.ts';

package/dist/src/shared/worker-client/typings/import-result.model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Report returned after importing an exported database into the
+ * current knowledge base.
+ */
+export interface ImportResult {
+    /** Number of sections imported. */
+    readonly sections_imported: number;
+    /** Number of documents imported. */
+    readonly documents_imported: number;
+    /** Whether a rebuild was triggered after import. */
+    readonly rebuilt: boolean;
+    /** Whether this was a dry-run (no writes). */
+    readonly dry_run: boolean;
+    /** Wall-clock time in milliseconds. */
+    readonly elapsed_ms: number;
+}

package/dist/src/shared/worker-client/typings/integrity-check-result.model.d.ts

@@ -16,6 +16,24 @@ export interface IntegrityError {
     /** Human-readable description of the specific problem. */
     readonly detail: string;
 }
+/**
+ * Advisory finding: two sections whose embedding vectors point in
+ * opposite directions, indicating potential semantic conflict.
+ *
+ * Does not affect the `ok` field of `IntegrityCheckResult`.
+ */
+export interface SemanticContradictionEntry {
+    /** Knowledge-base identifier of the first section in the pair. */
+    readonly kbid_a: string;
+    /** Knowledge-base identifier of the second section in the pair. */
+    readonly kbid_b: string;
+    /**
+     * Cosine similarity score (negative, in range -1.0 to 0.0).
+     *
+     * More negative values indicate stronger semantic opposition.
+     */
+    readonly score: number;
+}
 /**
  * Report returned by the daemon after running an integrity check
  * on the knowledge-base database.
@@ -33,4 +51,10 @@ export interface IntegrityCheckResult {
     readonly references_checked: number;
     /** Time taken to complete the check, in milliseconds. */
     readonly elapsed_ms: number;
+    /**
+     * Advisory list of section pairs with semantically contradictory
+     * embeddings. Empty when no embedding provider is configured or
+     * when no `vectors.idx` file is present. Never affects `ok`.
+     */
+    readonly semantic_contradictions: SemanticContradictionEntry[];
 }

package/dist/src/shared/worker-client/typings/search-params.model.d.ts

@@ -11,4 +11,8 @@ export interface SearchParams {
     readonly limit?: number;
     /** Number of results to skip (pagination offset). */
     readonly offset?: number;
+    /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
+    readonly algo?: string;
+    /** Use relaxed (OR) matching for the query. */
+    readonly relaxed?: boolean;
 }

package/dist/src/shared/worker-client/typings/search-result.model.d.ts

@@ -39,4 +39,10 @@ export interface PagedSearchResult {
     readonly limit: number;
     /** Whether more results exist beyond this page. */
     readonly has_more: boolean;
+    /** Whether the engine relaxed the query to produce results. */
+    readonly relaxed?: boolean;
+    /** Algorithm that produced these results. */
+    readonly search_mode?: string;
+    /** Retrieval strategy used (e.g. `'lexical'`, `'rrf'`). */
+    readonly retrieval_method?: string;
 }

package/dist/src/shared/worker-client/typings/worker-client-options.interface.d.ts

@@ -27,4 +27,11 @@ export interface WorkerClientOptions {
      * `spawnDaemon` needs no runtime-specific path logic.
      */
     readonly workerScript?: string;
+    /**
+     * Per-request timeout in milliseconds for daemon IPC
+     * calls. When a request exceeds this duration, the
+     * Promise rejects with a `REQUEST_TIMEOUT` error.
+     * Defaults to `undefined` (no timeout).
+     */
+    readonly requestTimeoutMs?: number;
 }

package/dist/src/shared/worker-daemon/classes/worker-daemon.class.d.ts

@@ -21,9 +21,11 @@ export declare class WorkerDaemon {
     get connectionCount(): number;
     private _connectionCount;
     private _wasmModules;
+    private _embeddingProvider;
     private _idleAt;
     private _idleTimer;
     private _server;
+    private readonly _sockets;
     private readonly _wasmDir;
     /** Queue of waiters for the single-writer lock. */
     private _writeQueue;
@@ -121,6 +123,7 @@ export declare class WorkerDaemon {
     private dispatch;
     private dispatchWasm;
     private handleSearch;
+    private runLexicalSearch;
     private handleResultStatus;
     private handleGetResult;
     private handleAddSection;
@@ -142,6 +145,9 @@ export declare class WorkerDaemon {
     private handleGc;
     private handleRebuild;
     private handleExport;
+    private handleImport;
+    private countFiles;
+    private collectFiles;
     private scanNearDuplicates;
     private extractTermSet;
     /**

package/dist/src/shared/worker-daemon/functions/create-ipc-server.function.d.ts

@@ -1,18 +1,18 @@
 import type { Server } from 'node:net';
 import type { IpcHandler } from '../typings/ipc-handler.interface.ts';
 /**
- * Creates a Unix socket (or named pipe on Windows) IPC server that
- * reads newline-delimited JSON-RPC requests and writes responses.
+ * Creates a Unix socket (or named pipe on Windows) IPC
+ * server that reads newline-delimited JSON-RPC requests
+ * and writes responses.
  *
- * Each line received on a socket connection is parsed as an
- * `IpcRequest`, dispatched to `handler`, and the resulting
- * `IpcResponse` is written back as a newline-terminated JSON string.
- * A malformed line that cannot be parsed results in a JSON-RPC
- * parse-error response (`-32700`).
+ * Resolves after the server is bound and listening.
+ * Accepted connections have `SO_KEEPALIVE` enabled at
+ * a 30-second interval.
  *
- * @param socketPath - path to the Unix domain socket or Windows
- *   named pipe
- * @param handler - async function invoked for each valid request
+ * @param socketPath - path to the Unix domain socket or
+ *   Windows named pipe
+ * @param handler - async function invoked for each valid
+ *   request
  * @returns the listening `net.Server` instance
  */
-export declare function createIpcServer(socketPath: string, handler: IpcHandler): Server;
+export declare function createIpcServer(socketPath: string, handler: IpcHandler): Promise<Server>;

package/dist/src/shared/worker-daemon/functions/embed-after-learn.function.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
+/**
+ * Embeds a section's content and appends it to `vectors.idx`.
+ *
+ * Skips silently when embeddings are disabled (no provider or
+ * zero dimensions) or when the content is empty.
+ *
+ * @param provider - embedding provider (undefined = disabled)
+ * @param targetDir - path to the `.kbdb` directory
+ * @param kbid - section identifier to embed
+ * @param content - section text content
+ */
+export declare function embedAfterLearn(provider: EmbeddingProvider | undefined, targetDir: string, kbid: string, content: string): Promise<void>;

package/dist/src/shared/worker-daemon/functions/handle-hybrid-search.function.d.ts

@@ -0,0 +1,44 @@
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
+/** Lexical search result from WASM decoder. */
+interface LexicalResult {
+    items: LexicalItem[];
+    total: number;
+    offset: number;
+    limit: number;
+    has_more: boolean;
+    relaxed: boolean;
+}
+/** A single item from the lexical search result. */
+interface LexicalItem {
+    kbid: string;
+    heading: string | null;
+    type: string;
+    docids: string[];
+    score: number;
+    confidence: number;
+    snippet: string;
+    matched_terms: string[];
+    matched_fields: string[];
+    created_at: string;
+}
+/** Search result with search_mode and retrieval_method. */
+interface FusedSearchResult extends LexicalResult {
+    search_mode: string;
+    retrieval_method: string;
+}
+/**
+ * Fuses lexical search results with vector search results.
+ *
+ * When `algo` is `'lexical'`, returns the lexical result as-is.
+ * When `algo` is `'hybrid'`, runs vector search against
+ * `vectors.idx` and fuses via RRF. When `algo` is `'vector'`,
+ * returns vector-only results.
+ *
+ * @param lexical - decoded lexical result from WASM
+ * @param algo - search algorithm: lexical, hybrid, or vector
+ * @param query - the original search query text
+ * @param provider - embedding provider (undefined = disabled)
+ * @param targetDir - path to the `.kbdb` directory
+ */
+export declare function fuseSearchResults(lexical: LexicalResult, algo: string, query: string, provider: EmbeddingProvider | undefined, targetDir: string): Promise<FusedSearchResult>;
+export {};

package/dist/src/shared/worker-daemon/functions/handle-import.function.d.ts

@@ -0,0 +1,14 @@
+import type { HandlerContext } from '../typings/handler-context.interface.ts';
+import type { ImportResult } from '../../worker-client/typings/import-result.model.ts';
+/**
+ * Handles the `importDb` IPC method.
+ *
+ * Reads sections and documents from an exported directory and
+ * feeds them back through the WASM add-section pipeline. When
+ * `dryRun` is `true`, counts files without writing.
+ *
+ * @param ctx - handler context with WASM modules
+ * @param params - `sourcePath` and `dryRun` flag
+ * @returns import report with counts and timing
+ */
+export declare function handleImport(ctx: HandlerContext, params: Record<string, unknown>): Promise<ImportResult>;

package/dist/src/shared/worker-daemon/functions/handle-read-ops.function.d.ts

@@ -4,8 +4,9 @@ import type { HandlerContext } from '../typings/handler-context.interface.ts';
  *
  * Encodes parameters, invokes the `worker_search` token pipeline,
  * waits synchronously for the result, and decodes the paged result.
+ * When `algo` is `'hybrid'` or `'vector'`, fuses with vector search.
  */
-export declare function handleSearch(ctx: HandlerContext, params: Record<string, unknown>): unknown;
+export declare function handleSearch(ctx: HandlerContext, params: Record<string, unknown>): Promise<unknown>;
 /**
  * Handles the `get_result_status` IPC method.
  */
@@ -28,6 +29,11 @@ export declare function handleRetrieveDoc(ctx: HandlerContext, params: Record<st
 export declare function handleCompose(ctx: HandlerContext, params: Record<string, unknown>): unknown;
 /**
  * Handles the `integrityCheck` IPC method.
+ *
+ * Runs the WASM integrity check and, when an embedding provider is
+ * available, appends an advisory `stale_vectors` field if the
+ * `vectors.idx` is outdated. The `ok` flag is not affected by stale
+ * vectors.
  */
 export declare function handleIntegrityCheck(ctx: HandlerContext): unknown;
 /**

package/dist/src/shared/worker-daemon/functions/handle-write-ops.function.d.ts

@@ -2,10 +2,12 @@ import type { HandlerContext } from '../typings/handler-context.interface.ts';
 /**
  * Handles the `addSection` IPC method.
  *
- * Encodes the section input, delegates to `worker_add_section`, and
- * runs a near-duplicate scan when the WASM result reports none.
+ * Encodes the section input, delegates to `worker_add_section`,
+ * runs a near-duplicate scan when the WASM result reports none,
+ * and embeds the section content when an embedding provider is
+ * configured.
  */
-export declare function handleAddSection(ctx: HandlerContext, params: Record<string, unknown>): unknown;
+export declare function handleAddSection(ctx: HandlerContext, params: Record<string, unknown>): Promise<unknown>;
 /**
  * Handles the `updateSection` IPC method.
  */
@@ -40,5 +42,8 @@ export declare function handleInvalidateAll(ctx: HandlerContext): unknown;
 export declare function handleGc(ctx: HandlerContext): unknown;
 /**
  * Handles the `rebuildIndexes` IPC method.
+ *
+ * Invokes the WASM keyword-index rebuild and, when an embedding
+ * provider is configured, also rebuilds the vector index.
  */
-export declare function handleRebuild(ctx: HandlerContext): unknown;
+export declare function handleRebuild(ctx: HandlerContext): Promise<unknown>;

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

@@ -1,9 +1,12 @@
+import type { LogLevel } from '../../log/typings/log-level.type.ts';
 /** Result of the worker entry point. */
 export interface WorkerResult {
     /** Error message (if any). */
     error?: string;
     /** Process exit code. `0` means success. */
     exitCode: number;
+    /** Parsed log level from `--log-level`, if provided. */
+    logLevel?: LogLevel;
 }
 /**
  * Injectable dependencies for the worker entry point.
@@ -20,7 +23,9 @@ export interface WorkerDeps {
  * absolute path, checks existence, and delegates to
  * `startDaemon`.
  *
- * @param argv - raw arguments (expects `[contextPath]`)
+ * Accepts `--log-level <level>` to configure daemon logging.
+ *
+ * @param argv - raw arguments
  * @param deps - injectable dependencies
  */
 export declare function runWorker(argv: string[], deps: WorkerDeps): Promise<WorkerResult>;

package/dist/src/shared/worker-daemon/typings/handler-context.interface.d.ts

@@ -1,5 +1,6 @@
 import type { DaemonConfig } from './daemon-config.interface.ts';
 import type { WasmModules } from './wasm-modules.interface.ts';
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
 /**
  * Runtime context passed to all IPC request handler functions.
  *
@@ -15,4 +16,6 @@ export interface HandlerContext {
     readonly config: DaemonConfig;
     /** Loaded WASM module instances. */
     readonly modules: WasmModules;
+    /** Embedding provider for vector/hybrid search. */
+    readonly embeddingProvider?: EmbeddingProvider;
 }

package/dist/src/shared/worker-daemon/typings/wasm-modules.interface.d.ts

@@ -4,4 +4,9 @@ export interface WasmModules {
     readonly memory: WebAssembly.Memory;
     /** Instantiated kb-worker WASM module. */
     readonly kbWorker: WebAssembly.Instance;
+    /**
+     * Instantiated default-embedding WASM module.
+     * Absent when the WASM file is unavailable.
+     */
+    readonly embedding?: WebAssembly.Instance;
 }

package/dist/wasm/default-embedding/kbdb_default_embedding.d.ts

@@ -0,0 +1,55 @@
+declare namespace wasm_bindgen {
+    /* tslint:disable */
+    /* eslint-disable */
+
+    /**
+     * Returns the number of dimensions in the embedding vector.
+     */
+    export function embedding_dimensions(): number;
+
+    /**
+     * Writes the model name "tfidf-v1" to the return slot. Returns 1.
+     */
+    export function embedding_model_name(): number;
+
+    /**
+     * Embed a single UTF-8 text into a 256-dimensional TF-IDF vector.
+     *
+     * Reads text from `(ptr, len)`, writes raw little-endian f32 bytes to
+     * the return slot. Returns 1 on success.
+     */
+    export function embedding_tfidf(ptr: number, len: number): number;
+
+    /**
+     * Embed a newline-separated batch of texts into 256-dimensional vectors.
+     *
+     * Encodes: u32 count, then count × DIMENSIONS f32 values (little-endian).
+     * Returns 1 on success.
+     */
+    export function embedding_tfidf_batch(ptr: number, len: number): number;
+
+}
+declare type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+declare interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly set_return: (a: number, b: number) => void;
+    readonly embedding_tfidf: (a: number, b: number) => number;
+    readonly embedding_tfidf_batch: (a: number, b: number) => number;
+    readonly embedding_dimensions: () => number;
+    readonly embedding_model_name: () => number;
+    readonly kbdb_alloc: (a: number) => number;
+    readonly get_return_len: () => number;
+    readonly get_return_ptr: () => number;
+    readonly kbdb_free: (a: number, b: number) => void;
+}
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+declare function wasm_bindgen (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;