@dikolab/kbdb 0.3.0 → 0.3.2

package/dist/src/shared/worker-daemon/functions/parse-embedding-section.function.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingConfig } from '../../embedding/typings/embedding-config.interface.ts';
+/**
+ * Parses key-value pairs from a `[embedding]` TOML section into an
+ * `EmbeddingConfig`.
+ *
+ * Recognises: `provider`, `model`, `endpoint`, `dimensions`.
+ * Unknown keys are silently ignored. Returns `undefined` when the
+ * `provider` key is absent from the supplied entries.
+ *
+ * @param entries - key-value pairs from inside the `[embedding]`
+ *   section
+ */
+export declare function parseEmbeddingSection(entries: ReadonlyMap<string, string>): EmbeddingConfig | undefined;

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

@@ -0,0 +1,11 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+/**
+ * Parses a `worker.toml` file body into a partial `DaemonConfig`.
+ *
+ * Handles `[embedding]` sub-sections and root key-value pairs.
+ * Unknown keys are silently ignored.
+ *
+ * @param text - raw content of `worker.toml`
+ * @param contextPath - daemon context directory path
+ */
+export declare function parseWorkerToml(text: string, contextPath: string): DaemonConfig;

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

@@ -0,0 +1,18 @@
+import type { WasmModules } from '../typings/wasm-modules.interface.ts';
+/** Result of a startup integrity check. */
+export interface StartupIntegrityResult {
+    /** Whether the check passed without errors. */
+    readonly integrityOk: boolean;
+    /** Integrity error descriptions found at startup. */
+    readonly integrityErrors: string[];
+}
+/**
+ * Runs `worker_check_integrity` immediately after WASM context
+ * initialisation and returns the result.
+ *
+ * Logs a warning to stderr when issues are found. Never throws --
+ * failures are captured and returned as part of the result.
+ *
+ * @param modules - loaded WASM module instances
+ */
+export declare function runStartupIntegrityCheck(modules: WasmModules): StartupIntegrityResult;

package/dist/src/shared/worker-daemon/functions/scan-near-duplicates.function.d.ts

@@ -0,0 +1,21 @@
+/** A near-duplicate match found during add-section scanning. */
+export interface NearDuplicateMatch {
+    /** Knowledge-base identifier of the near-duplicate section. */
+    readonly kbid: string;
+    /** Jaccard similarity score, rounded to 2 decimal places (0–1). */
+    readonly similarity: number;
+}
+/**
+ * Scans existing section files for near-duplicates of `content`.
+ *
+ * Uses Jaccard similarity on a set of lowercased tokens (3+ chars)
+ * extracted from the section body. Sections with a similarity of
+ * 0.85 or above are included in the result. The `newKbid` section
+ * is excluded from comparison.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @param content - raw text content of the newly added section
+ * @param newKbid - identifier of the just-added section to exclude
+ * @returns near-duplicate matches sorted by insertion order
+ */
+export declare function scanNearDuplicates(targetDir: string, content: string, newKbid: string): NearDuplicateMatch[];

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

@@ -0,0 +1,51 @@
+import type { WasmModules } from '../typings/wasm-modules.interface.ts';
+import type { WasmFn } from '../typings/wasm-fn.type.ts';
+/**
+ * Retrieves a named export from the kb-worker WASM instance.
+ *
+ * @throws {Error} if WASM modules are not yet loaded
+ * @throws {Error} if the named export does not exist or is not a
+ *   function
+ */
+export declare function getWasmExport(modules: WasmModules, name: string): WasmFn;
+/**
+ * Allocates `size` bytes in WASM linear memory.
+ *
+ * Returns `0` when `size` is zero or the allocator export is
+ * absent.
+ */
+export declare function wasmAlloc(modules: WasmModules, size: number): number;
+/**
+ * Frees a previously allocated WASM memory region.
+ *
+ * No-ops when `ptr` or `size` is zero, or when the free export
+ * is absent.
+ */
+export declare function wasmFree(modules: WasmModules, ptr: number, size: number): void;
+/**
+ * Writes `data` into WASM linear memory at `ptr`.
+ *
+ * @throws {Error} if the write would exceed memory bounds
+ */
+export declare function wasmWrite(modules: WasmModules, ptr: number, data: Uint8Array): void;
+/**
+ * Reads the WASM return slot, frees the underlying buffer, and
+ * returns its contents as a `Uint8Array`.
+ *
+ * Returns an empty array when the slot is unset or memory is
+ * unavailable.
+ */
+export declare function readReturnSlot(modules: WasmModules): Uint8Array;
+/**
+ * Calls a WASM export with binary-encoded input via the
+ * alloc/write/call/read/free protocol.
+ *
+ * @throws {IpcError} when the export returns `-1` (error sentinel)
+ */
+export declare function callWasmSync(modules: WasmModules, exportName: string, input: Uint8Array): Uint8Array;
+/**
+ * Calls a zero-argument WASM export and checks its return code.
+ *
+ * @throws {IpcError} when the export returns `-1` (error sentinel)
+ */
+export declare function callWasmZeroArg(modules: WasmModules, exportName: string): void;

package/dist/src/shared/worker-daemon/functions/wasm-memory-helpers.function.d.ts

@@ -0,0 +1,22 @@
+import type { MemoryRef } from '../typings/memory-ref.interface.ts';
+/**
+ * Returns the current `ArrayBuffer` backing WASM linear memory.
+ *
+ * Must be called after WASM module instantiation. The buffer
+ * reference may change after WASM memory growth, so callers
+ * should call this function each time they need a fresh view.
+ *
+ * @param memoryRef - deferred reference to WASM linear memory
+ * @throws {Error} when memory is not yet initialised
+ */
+export declare function getWasmBuffer(memoryRef: MemoryRef): ArrayBuffer;
+/**
+ * Decodes a UTF-8 path from WASM linear memory and resolves it
+ * relative to `contextPath` when the path is not absolute.
+ *
+ * @param memoryRef - deferred reference to WASM linear memory
+ * @param contextPath - base directory for relative paths
+ * @param ptr - byte offset of the path string in WASM memory
+ * @param len - byte length of the path string
+ */
+export declare function readWasmPathArg(memoryRef: MemoryRef, contextPath: string, ptr: number, len: number): string;

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

@@ -0,0 +1,32 @@
+import type { WriteLockState } from '../typings/write-lock.interface.ts';
+/**
+ * Acquires the single-writer lock.
+ *
+ * Enforces the single-writer guarantee: at most one write
+ * operation runs at a time inside the daemon. Concurrent writes
+ * are serialized through an in-memory FIFO queue -- each caller
+ * awaits this function and proceeds only when it is at the head
+ * of the queue. Read operations bypass this lock entirely and
+ * may proceed concurrently with writes and with each other.
+ *
+ * Crash recovery: the lock is purely in-memory. If the daemon
+ * process crashes mid-write, the OS reclaims process memory,
+ * releasing the lock automatically. The WASM engine is
+ * responsible for leaving on-disk state consistent (it uses
+ * atomic rename: write to a `.tmp` file, then `host_rename` to
+ * the final path).
+ *
+ * @param state - shared write-lock state
+ */
+export declare function acquireWriteLock(state: WriteLockState): Promise<void>;
+/**
+ * Releases the single-writer lock.
+ *
+ * Grants the lock to the next queued waiter if one exists;
+ * otherwise marks the lock as free. Must always be called in a
+ * `finally` block after `acquireWriteLock` to prevent permanent
+ * lock starvation.
+ *
+ * @param state - shared write-lock state
+ */
+export declare function releaseWriteLock(state: WriteLockState): void;

package/dist/src/shared/worker-daemon/typings/allocator-ref.interface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A mutable reference to the WASM allocator function.
+ *
+ * The `alloc` field starts as `null` and is wired up after the
+ * `kb-worker` WASM module is instantiated. Host import functions
+ * that must allocate memory in WASM linear memory check this
+ * reference before proceeding and return `-1` when it is null.
+ */
+export interface AllocatorRef {
+    /**
+     * Allocates `size` bytes in WASM linear memory and returns the
+     * byte offset of the allocated region, or `null` when the
+     * allocator is not yet available.
+     */
+    alloc: ((size: number) => number) | null;
+}

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

@@ -1,3 +1,5 @@
+import type { EmbeddingConfig } from '../../embedding/typings/embedding-config.interface.ts';
+import type { AutoCaptureConfig } from '../../auto-capture/typings/auto-capture-config.interface.ts';
 /** Configuration for the worker daemon process. */
 export interface DaemonConfig {
     /** Absolute path to the knowledge-base context directory. */
@@ -10,4 +12,8 @@ export interface DaemonConfig {
     readonly timeoutMs: number;
     /** Time-to-live in milliseconds for each cached item. */
     readonly itemTtlMs: number;
+    /** Embedding provider configuration. */
+    readonly embedding?: EmbeddingConfig;
+    /** Auto-capture behaviour configuration. */
+    readonly autoCapture?: AutoCaptureConfig;
 }

package/dist/src/shared/worker-daemon/typings/fs-adapter.interface.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimal filesystem operations required by the WASM host imports.
+ *
+ * The default implementation delegates to `node:fs` synchronous
+ * APIs. Tests inject a stub to avoid touching the real filesystem.
+ */
+export interface FsAdapter {
+    /** Read entire file as a Buffer. */
+    readFileSync(path: string): Buffer;
+    /** Write data buffer to file. */
+    writeFileSync(path: string, data: Uint8Array): void;
+    /** Rename `oldPath` to `newPath`. */
+    renameSync(oldPath: string, newPath: string): void;
+    /** Delete a file. */
+    unlinkSync(path: string): void;
+    /** List directory entries as strings. */
+    readdirSync(path: string): string[];
+    /** Create a directory (and parents) recursively. */
+    mkdirSync(path: string): void;
+    /** Return true if the path exists. */
+    existsSync(path: string): boolean;
+}

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

@@ -0,0 +1,18 @@
+import type { DaemonConfig } from './daemon-config.interface.ts';
+import type { WasmModules } from './wasm-modules.interface.ts';
+/**
+ * Runtime context passed to all IPC request handler functions.
+ *
+ * Groups the minimal shared state needed by every request handler
+ * so that handler functions can be standalone (not methods on a
+ * class) while still accessing WASM modules, configuration, and
+ * the database directory path.
+ */
+export interface HandlerContext {
+    /** Absolute path to the `.kbdb` directory. */
+    readonly targetDir: string;
+    /** Parsed daemon configuration from `worker.toml`. */
+    readonly config: DaemonConfig;
+    /** Loaded WASM module instances. */
+    readonly modules: WasmModules;
+}

package/dist/src/shared/worker-daemon/typings/memory-ref.interface.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A mutable reference to the WASM linear memory.
+ *
+ * The `memory` field starts as `null` and is wired up after the
+ * `kb-worker` WASM module is instantiated (the module exports its
+ * own memory rather than importing one). Host import functions
+ * read `memory` at call time, not at creation time, so the ref
+ * can be populated after the import record is built.
+ */
+export interface MemoryRef {
+    /** WASM linear memory; `null` until the module is instantiated. */
+    memory: WebAssembly.Memory | null;
+}

package/dist/src/shared/worker-daemon/typings/wasm-fn.type.d.ts

@@ -0,0 +1,2 @@
+/** Callable WASM export function signature. */
+export type WasmFn = (...args: unknown[]) => unknown;

package/dist/src/shared/worker-daemon/typings/write-lock.interface.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mutable state for the single-writer lock used by WorkerDaemon.
+ *
+ * Holds the current lock flag and the queue of pending waiters.
+ * Both fields are mutated by `acquireWriteLock` and
+ * `releaseWriteLock`.
+ */
+export interface WriteLockState {
+    /** Whether the write lock is currently held. */
+    locked: boolean;
+    /** Queue of resolve callbacks for pending lock waiters. */
+    queue: {
+        resolve: () => void;
+    }[];
+}

package/docs/details/cli.md

@@ -80,8 +80,17 @@ These options apply to the `search` command.
 | `--limit <n>` | `-l` | `20` | positive integer | Maximum results returned |
 | `--offset <n>` | | `0` | non-negative integer | Zero-based result offset for pagination |
 | `--format <fmt>` | `-f` | `json` | `json`, `text`, `mcp` | Output format |
+| `--algo <algo>` | | `lexical` | `lexical`, `vector`, `hybrid` | Search algorithm |
 | `--content` | `-c` | off | boolean flag | Hydrate results with section content |
 
+### Search Algorithms
+
+| Algorithm | Description |
+|-----------|-------------|
+| `lexical` | Keyword matching with stemming and synonyms (default) |
+| `vector` | AI-powered similarity search using embeddings (requires a configured embedding provider) |
+| `hybrid` | Combines keyword and similarity results for best coverage |
+
 ### Search Modes
 
 | Mode | Description |

package/docs/details/mcp-server.md

@@ -188,7 +188,7 @@ own worker client connection.
 
 ## Tools Reference
 
-The MCP server exposes 19 tools grouped by
+The MCP server exposes 20 tools grouped by
 function. All tools communicate with the worker
 daemon via JSON-RPC 2.0 over IPC.
 
@@ -196,7 +196,7 @@ daemon via JSON-RPC 2.0 over IPC.
 
 | Tool | Parameters | Description | Read-only | Destructive |
 |------|-----------|-------------|-----------|-------------|
-| `search` | `query` (string, required), `mode` (string), `limit` (number), `offset` (number), `content` (boolean) | Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use multiple short keyword queries for best coverage. | yes | no |
+| `search` | `query` (string, required), `mode` (string), `algo` (string: lexical, vector, hybrid), `limit` (number), `offset` (number), `content` (boolean) | Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use `algo` to select search algorithm (default: lexical). | yes | no |
 | `learn` | `content` (string, required), `type` (string), `title` (string), `description` (string), `docid` (string), `tags` (string[]), `replace` (boolean) | Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use `replace` when updating existing knowledge. Attach `tags` for scoping. | no | no |
 | `unlearn` | `kbid` (string, required) | Remove a section by kb-id. Cascades deletion to index entries and ranking data. | no | yes |
 | `retrieve` | `kbid` (string), `docid` (string) | Fetch a specific section or document by identifier. At least one of `kbid` or `docid` required. | yes | no |
@@ -207,6 +207,7 @@ daemon via JSON-RPC 2.0 over IPC.
 | `gc` | (none) | Remove unreferenced sections (no document manifest references). | no | yes |
 | `rebuild` | (none) | Reconstruct all index files from section files and document manifests on disk. | no | no |
 | `export` | `path` (string) | Export the knowledge base as a self-contained directory snapshot for backup or versioning. Copies sections, documents, and catalog (no indexes). | no | no |
+| `auto-capture-review` | `action` (string: list, approve, reject) | Review and approve pending auto-captured knowledge before storage. | no | no |
 
 ### Skills Tools
 
@@ -249,6 +250,7 @@ daemon via JSON-RPC 2.0 over IPC.
 | `agent-list` | yes |
 | `agent-get` | yes |
 | `agent-delete` | yes |
+| `auto-capture-review` | yes |
 
 ## Prompts
 
@@ -340,7 +342,7 @@ Protocol version **2025-11-25** and advertises the
 following capabilities:
 
 - **tools** -- `tools/list` and `tools/call` for
-  all 19 tools.
+  all 20 tools.
 - **resources** -- `resources/list`,
   `resources/read`, and
   `resources/templates/list` for URI-based content

package/docs/details/search-and-ranking.md

@@ -1,5 +1,15 @@
 # How Search Works
 
+When you search, kbdb finds the sections that best
+match your query and ranks them by relevance. By
+default it matches keywords (like a search engine).
+You can also enable AI-powered similarity search
+or combine both with `--algo hybrid`. The rest of
+this page explains how ranking works under the hood
+-- you don't need to read it to use kbdb.
+
+---
+
 kbdb uses field-weighted BM25F ranking to score search
 results by relevance. Sections are indexed across
 three fields -- heading, body, and code -- each with a
@@ -513,3 +523,48 @@ Neither standalone module calls the other directly.
 | `sections`  | Individual matching sections with scores, snippets, and matched terms |
 | `documents` | Documents containing matches, with aggregated scores and per-section details |
 | `stats`     | Match counts and top terms without content bodies |
+
+## Search Algorithms
+
+kbdb supports three search algorithms, selected
+with `--algo` (CLI) or the `algo` parameter (MCP).
+
+### Lexical (default)
+
+Keyword matching with stemming and synonym
+expansion, scored by BM25F as described above.
+Fast, works offline, and gives consistent results.
+This is the default when no `--algo` flag is given.
+
+### Vector
+
+Embedding-based similarity search. Each section's
+content is converted into a numeric vector (an
+"embedding") by an AI model. Search finds sections
+whose vectors are closest to the query's vector
+using cosine similarity.
+
+Vector search catches matches that keyword search
+misses -- for example, searching "database
+rationale" finds a section about "we chose Postgres
+because of JSONB" even though none of the words
+overlap.
+
+Requires an embedding provider to be configured.
+Without one, vector mode falls back to lexical.
+
+### Hybrid
+
+Runs both lexical and vector searches in parallel,
+then merges the two ranked lists using Reciprocal
+Rank Fusion (RRF). This combines the precision of
+keyword matching with the associative recall of
+embeddings.
+
+RRF works by converting each result's rank position
+into a score (`1 / (k + rank)` with k=60), then
+summing scores across both lists. Results that rank
+well in both lists get the highest combined scores.
+
+Hybrid mode requires an embedding provider. Without
+one, it falls back to lexical.