@dikolab/kbdb 0.3.0 → 0.3.1

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/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.
 
@@ -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