@dikolab/kbdb 0.3.2 → 0.4.1

package/docs/modules/typescript/shared/log/functions.md

@@ -0,0 +1,131 @@
+# log/functions -- Logging Functions
+
+*Core log emitter, configuration applier, level parser,
+level resolver, and cross-runtime stderr writer.*
+
+## Source
+
+`src/shared/log/functions/`
+
+## Functions
+
+### `log`
+
+**File:** `log.function.ts`
+
+Writes a formatted, colorized message to the configured
+output for the given level. Messages below the current
+minimum level are silently discarded.
+
+```ts
+function log(
+   message: string,
+   level: LogLevel = LogLevel.ERROR,
+): void;
+```
+
+Output format:
+
+```
+<ANSI_COLOR><ICON> [LEVEL_NAME] message<ANSI_RESET>\n
+```
+
+The level defaults to `LogLevel.ERROR` when omitted.
+The output target and minimum level are module-level
+state managed by `configureLog`.
+
+### `configureLog`
+
+**File:** `configure-log.function.ts`
+
+Applies a log configuration, setting the active log
+level and optionally overriding the output target for
+individual levels.
+
+```ts
+function configureLog(config: LogConfig): void;
+```
+
+Only levels listed in `config.outputs` are affected;
+all other level outputs remain unchanged. Calling this
+function multiple times is safe -- the last call's
+settings take effect.
+
+### `parseLogLevel`
+
+**File:** `parse-log-level.function.ts`
+
+Parses a string into a `LogLevel` enum value.
+
+```ts
+function parseLogLevel(value: string): LogLevel;
+```
+
+Matching is case-insensitive. Recognized values are
+`'debug'`, `'info'`, `'warning'`, and `'error'`.
+Returns `LogLevel.WARNING` for any unrecognized value,
+including empty strings.
+
+| Input       | Result              |
+|-------------|---------------------|
+| `'debug'`   | `LogLevel.DEBUG`    |
+| `'info'`    | `LogLevel.INFO`     |
+| `'warning'` | `LogLevel.WARNING`  |
+| `'error'`   | `LogLevel.ERROR`    |
+| `'ERROR'`   | `LogLevel.ERROR`    |
+| `'unknown'` | `LogLevel.WARNING`  |
+| `''`        | `LogLevel.WARNING`  |
+
+### `resolveLogLevel`
+
+**File:** `resolve-log-level.function.ts`
+
+Resolves the active log level from a CLI flag or the
+`KBDB_LOG_LEVEL` environment variable, falling back to
+`DEFAULT_LOG_LEVEL`.
+
+```ts
+function resolveLogLevel(
+   cliLevel?: LogLevel,
+): LogLevel;
+```
+
+Priority order:
+
+1. `cliLevel` when provided (highest priority)
+2. `KBDB_LOG_LEVEL` environment variable, parsed via
+   `parseLogLevel`
+3. `DEFAULT_LOG_LEVEL` (`LogLevel.ERROR`) when neither
+   is set
+
+### `writeStderr`
+
+**File:** `write-stderr.function.ts`
+
+Writes a string to the process standard error stream.
+
+```ts
+function writeStderr(message: string): void;
+```
+
+Works on both Node.js (via `process.stderr.write`) and
+Deno (via `Deno.stderr.writeSync`). Silently does
+nothing when neither runtime API is available. Both
+runtime APIs are accessed through `globalThis` to avoid
+hard references to platform-specific globals.
+
+## Testing
+
+Each function has a `.spec.ts` in the functions
+directory:
+
+```
+src/shared/log/functions/
+├── configure-log.spec.ts
+├── log.spec.ts
+├── parse-log-level.spec.ts
+└── resolve-log-level.spec.ts
+```
+
+`write-stderr.function.ts` is covered through the
+`log.spec.ts` integration path.

package/docs/modules/typescript/shared/log/module.md

@@ -0,0 +1,153 @@
+# log -- Structured Logging
+
+*Formats and routes diagnostic messages to stderr with
+per-level ANSI color coding, Unicode icons, and a
+configurable minimum verbosity threshold.*
+
+## Source
+
+`src/shared/log/`
+
+## Responsibility
+
+Provides a single `log(message, level)` entry point
+that formats and emits a colorized line to the active
+output for the given level. Messages below the current
+minimum level are silently discarded.
+
+The module owns its own mutable state (current level,
+per-level output functions) and exposes `configureLog`
+to replace that state at startup. All formatting
+constants (icons, ANSI colors) are kept in dedicated
+constant files so they can be consumed independently.
+
+The module does **not** buffer messages, write to
+stdout, or interact with the filesystem. All output is
+written to stderr.
+
+## Directory Layout
+
+```
+src/shared/log/
+├── index.ts
+├── constants/
+│   ├── log-colors.constant.ts
+│   ├── log-defaults.constant.ts
+│   └── log-icons.constant.ts
+├── functions/
+│   ├── configure-log.function.ts
+│   ├── configure-log.spec.ts
+│   ├── log.function.ts
+│   ├── log.spec.ts
+│   ├── parse-log-level.function.ts
+│   ├── parse-log-level.spec.ts
+│   ├── resolve-log-level.function.ts
+│   ├── resolve-log-level.spec.ts
+│   └── write-stderr.function.ts
+└── typings/
+    ├── log-config.interface.ts
+    ├── log-level.type.ts
+    └── log-output.interface.ts
+```
+
+## Exports
+
+- **[functions.md](functions.md)** -- `log`,
+  `configureLog`, `parseLogLevel`, `resolveLogLevel`,
+  `writeStderr`.
+- **[typings.md](typings.md)** -- `LogLevel`,
+  `LogOutput`, `LogConfig`.
+- **[constants.md](constants.md)** -- `DEFAULT_LOG_LEVEL`,
+  `LOG_ICONS`, `LOG_COLORS`, `ANSI_RESET`.
+
+## How Logging Works
+
+### Level Filtering
+
+`LogLevel` is a numeric enum ordered from most verbose
+to least:
+
+```
+DEBUG (0) < INFO (1) < WARNING (2) < ERROR (3)
+```
+
+When `log(message, level)` is called, the level is
+compared against the current minimum level. Messages
+with a level strictly below the minimum are dropped
+without any output.
+
+### Output Format
+
+Each accepted message is formatted as a single line:
+
+```
+<ANSI_COLOR><ICON> [LEVEL_NAME] message<ANSI_RESET>\n
+```
+
+For example, an `ERROR` message renders as:
+
+```
+\x1b[91m✖ [ERROR] something went wrong\x1b[0m\n
+```
+
+### Icons
+
+Each level has a distinct Unicode icon from
+`LOG_ICONS`:
+
+| Level   | Icon |
+|---------|------|
+| DEBUG   | `▸`  |
+| INFO    | `ℹ`  |
+| WARNING | `⚠`  |
+| ERROR   | `✖`  |
+
+### ANSI Colors
+
+Each level has a distinct foreground color from
+`LOG_COLORS`:
+
+| Level   | ANSI Code     | Appearance     |
+|---------|---------------|----------------|
+| DEBUG   | `\x1b[37m`    | White          |
+| INFO    | `\x1b[36m`    | Cyan           |
+| WARNING | `\x1b[33m`    | Yellow         |
+| ERROR   | `\x1b[91m`    | Bright red     |
+
+`ANSI_RESET` (`\x1b[0m`) is appended after every
+message to restore the terminal's default style.
+
+## Configuration Flow
+
+```
+CLI flag (--log-level) → resolveLogLevel(cliLevel)
+                       ↓
+         KBDB_LOG_LEVEL env var  (if no CLI flag)
+                       ↓
+         DEFAULT_LOG_LEVEL = LogLevel.ERROR (fallback)
+                       ↓
+                 configureLog({ level })
+                       ↓
+              log() uses the resolved level
+```
+
+Priority order inside `resolveLogLevel`:
+
+1. `cliLevel` argument -- highest priority
+2. `KBDB_LOG_LEVEL` environment variable, parsed by
+   `parseLogLevel`
+3. `DEFAULT_LOG_LEVEL` (`LogLevel.ERROR`) -- fallback
+
+## Dependency Direction
+
+```
+cli.ts / worker.ts
+   └─ resolveLogLevel  (reads env var + CLI flag)
+   └─ configureLog     (writes module state)
+   └─ log              (emits formatted lines)
+         └─ writeStderr  (cross-runtime stderr write)
+         └─ LOG_COLORS, LOG_ICONS  (formatting constants)
+```
+
+The `log` module has no dependency on any other
+`src/shared/` module.

package/docs/modules/typescript/shared/log/typings.md

@@ -0,0 +1,82 @@
+# log/typings -- Log Type Definitions
+
+*Enum, interface, and configuration shape for the log
+module.*
+
+## Source
+
+`src/shared/log/typings/`
+
+## Typings
+
+### `LogLevel`
+
+**File:** `log-level.type.ts`
+
+Verbosity levels, ordered from most to least verbose.
+
+```ts
+enum LogLevel {
+   DEBUG   = 0,
+   INFO    = 1,
+   WARNING = 2,
+   ERROR   = 3,
+}
+```
+
+| Member    | Value | Description                         |
+|-----------|-------|-------------------------------------|
+| `DEBUG`   | `0`   | Verbose diagnostic messages         |
+| `INFO`    | `1`   | Informational progress messages     |
+| `WARNING` | `2`   | Non-fatal conditions worth noting   |
+| `ERROR`   | `3`   | Failures and unexpected conditions  |
+
+Numeric ordering enables threshold comparisons:
+`level < currentLevel` discards messages below the
+configured minimum.
+
+### `LogOutput`
+
+**File:** `log-output.interface.ts`
+
+Writable target for a single log level.
+
+```ts
+interface LogOutput {
+   readonly write: (message: string) => void;
+}
+```
+
+| Member  | Description                              |
+|---------|------------------------------------------|
+| `write` | Receives a fully formatted log line      |
+
+`LogOutput` is the unit of per-level output override
+passed in `LogConfig.outputs`. The default output for
+all levels is `writeStderr`.
+
+### `LogConfig`
+
+**File:** `log-config.interface.ts`
+
+Configuration for the log module, accepted by
+`configureLog`.
+
+```ts
+interface LogConfig {
+   readonly level: LogLevel;
+   readonly outputs?: Partial<Record<LogLevel, LogOutput>>;
+}
+```
+
+| Property  | Description                               |
+|-----------|-------------------------------------------|
+| `level`   | Minimum level; messages below are dropped |
+| `outputs` | Optional per-level output overrides       |
+
+`outputs` is a partial record keyed by `LogLevel`.
+Only levels present in the record are affected;
+unspecified levels keep their existing output target.
+Omitting `outputs` entirely changes only the level.
+
+No spec -- typings are compile-time only.

package/docs/modules/typescript/shared/mcp/module.md

@@ -94,7 +94,7 @@ src/shared/mcp/
 cli.ts (entry point, MCP mode)
   │
   ├─ detect runtime (Deno / Node)
-  ├─ resolve db path (--db flag or KBDB_DIR env)
+  ├─ resolve db path (--db flag or KBDB_DB_DIR env or cwd)
   ├─ createWorkerClient({ targetDir })
   ├─ createMcpServer(client)
   │    └─ returns McpServer

package/docs/modules/typescript/shared/mcp/typings.md

@@ -61,7 +61,14 @@ interface McpWorkerClient {
       readonly depth?: number;
    }): Promise<RecallResult | RecallResult[]>;
 
-   dbStatus(): Promise<DbStatus>;
+   dbStatus(): Promise<{
+      initialized: boolean;
+      contextPath: string;
+      cacheStats: {
+         contentCount: number;
+         indexCount: number;
+      };
+   }>;
 
    disconnect(): void;
 }

package/docs/modules/typescript/shared/module.md

@@ -33,7 +33,8 @@ src/shared/
 ├── version/           ← Package version constant
 ├── runtime/           ← Deno / Node.js detection
 ├── platform/          ← OS abstractions
-└── hash/              ← SHA-256 hashing
+├── hash/              ← SHA-256 hashing
+└── log/               ← Structured logging
 ```
 
 ## Modules
@@ -63,6 +64,9 @@ src/shared/
   helpers (tmpdir, PID checks, IPC socket paths).
 - **[hash/](hash/module.md)** -- SHA-256 hashing via
   Web Crypto API.
+- **[log/](log/module.md)** -- Structured logging with
+  configurable levels, ANSI colors, and per-level
+  Unicode icons.
 
 ## Dependency Direction
 
@@ -78,17 +82,29 @@ src/worker.ts
 
 shared/worker-client/
   ├── shared/platform/
-  └── shared/hash/
+  ├── shared/hash/
+  └── shared/log/
 
 shared/worker-daemon/
-  └── shared/platform/
+  ├── shared/platform/
+  └── shared/log/
+
+shared/cli/
+  └── shared/log/
+
+shared/mcp/
+  └── shared/log/
 
 mod.ts
   └── shared/version/
 ```
 
 Utility modules (`version`, `runtime`, `platform`,
-`hash`) have no dependencies on application modules.
-Application modules may depend on utility modules
-but not on each other, except through the
+`hash`, `log`) have no dependencies on application
+modules. Application modules may depend on utility
+modules but not on each other, except through the
 worker-client which both `cli` and `mcp` share.
+`shared/log/` is a standalone utility with no
+dependencies; `cli/`, `mcp/`, `worker-daemon/`, and
+`worker-client/` all depend on it for structured
+output.

package/docs/modules/typescript/shared/worker-client/module.md

@@ -22,6 +22,12 @@ that communicates with the worker daemon. It:
   named pipe.
 - Exposes every daemon IPC method as a typed async
   function (JSON-RPC 2.0 over IPC).
+- Retries transient connection failures (`ENOENT`,
+  `ECONNREFUSED`) with exponential backoff.
+- Rejects all pending calls on post-connect socket
+  failure and marks the client as disconnected.
+- Exposes `isConnected` state and a cached client
+  factory (`getOrCreateClient`).
 - Handles reconnection when the connection drops.
 
 The module is **not** exported from the library API
@@ -45,6 +51,7 @@ src/shared/worker-client/
 │   ├── compute-context-id.function.ts
 │   ├── create-worker-client.function.ts
 │   ├── discover-daemon.function.ts
+│   ├── get-or-create-client.function.ts
 │   ├── resolve-db-path.function.ts
 │   ├── spawn-daemon.function.ts
 │   └── wait-for-daemon.function.ts
@@ -71,7 +78,8 @@ src/shared/worker-client/
 
 - **[classes.md](classes.md)** -- `WorkerClient`.
 - **[functions.md](functions.md)** --
-  `createWorkerClient`, `resolveDbPath`,
+  `createWorkerClient`, `getOrCreateClient`,
+  `clearClientCache`, `resolveDbPath`,
   `computeContextId`, `discoverDaemon`,
   `spawnDaemon`, `waitForDaemon`.
 - **[typings.md](typings.md)** --

package/docs/modules/typescript/shared/worker-client/typings.md

@@ -22,6 +22,7 @@ interface WorkerClientOptions {
    readonly autoSpawn?: boolean;
    readonly connectTimeoutMs?: number;
    readonly workerScript?: string;
+   readonly requestTimeoutMs?: number;
 }
 ```
 
@@ -38,6 +39,8 @@ interface WorkerClientOptions {
 |                    | after spawning; defaults to 10000 |
 | `workerScript`     | Absolute path to the worker       |
 |                    | daemon script                     |
+| `requestTimeoutMs` | Per-request timeout; default      |
+|                    | 30 000 ms                         |
 
 ### `SearchParams`
 

package/docs/modules/typescript/shared/worker-daemon/functions.md

@@ -15,9 +15,12 @@ and configuration reading.*
 **File:** `run-worker.function.ts`
 
 Worker daemon entry point extracted from
-`src/worker.ts`. Validates the context path argument,
-resolves it to an absolute path, checks existence, and
-delegates to `startDaemon`.
+`src/worker.ts`. Parses `argv` for the context path
+and the optional `--log-level <level>` argument,
+configures the log level, validates the context path,
+and delegates to `startDaemon`.
+
+Usage: `kbdb-worker <context-path> [--log-level <level>]`
 
 ```ts
 async function runWorker(
@@ -39,9 +42,15 @@ interface WorkerDeps {
 interface WorkerResult {
    error?: string;
    exitCode: number;
+   logLevel?: LogLevel;
 }
 ```
 
+`LogLevel` is `'debug' | 'info' | 'warning' | 'error'`.
+The log level is resolved from the `--log-level` CLI
+argument, then the `KBDB_LOG_LEVEL` environment
+variable, then defaults to `'error'`.
+
 Returns a `WorkerResult` without touching process
 globals, making it fully testable.
 
@@ -139,8 +148,8 @@ interface AllocatorRef {
 
 **File:** `load-wasm-modules.function.ts`
 
-Compiles and instantiates the `kb-worker.wasm` module
-along with its host imports.
+Compiles and instantiates the WASM modules used by
+the worker daemon.
 
 ```ts
 async function loadWasmModules(
@@ -157,9 +166,13 @@ Loading sequence:
    passing host imports.
 3. Wires the exported `memory` and `kbdb_alloc`
    function back into the deferred refs.
+4. Compiles and instantiates
+   `default-embedding.wasm` -- no host imports
+   needed (pure computation). The module is
+   instantiated with an empty import object.
 
 Returns a `WasmModules` object containing the
-instantiated module and its exported memory.
+instantiated modules and their shared memory.
 
 ### `createIpcServer`
 

package/docs/modules/typescript/shared/worker-daemon/module.md

@@ -15,13 +15,15 @@ signal.*
 The worker-daemon module implements a detached
 background process that:
 
-- Loads and compiles the three WASM modules once at
+- Loads and compiles the four WASM modules once at
   startup (`query-parser.wasm`, `fs-database.wasm`,
-  `kb-worker.wasm`).
+  `default-embedding.wasm`, `kb-worker.wasm`).
 - Reads configuration from `worker.toml` in the
   context directory.
 - Listens on a local IPC socket (Unix domain socket
   or Windows named pipe) for JSON-RPC 2.0 requests.
+  Configures accepted connections with `SO_KEEPALIVE`
+  (30 s) and listens with backlog 256.
 - Maintains an in-memory LRU cache with TTL expiry
   for indexes, content objects, and manifests.
 - Tracks active connections and resets the idle timer
@@ -89,14 +91,18 @@ src/worker.ts (entry point)
   │         │    ├─ compile fs-database.wasm ──┤
   │         │    │  (parallel, standalone,     │
   │         │    │   shared memory)            │
+  │         │    ├─ compile default-embedding ─┤
+  │         │    │  (standalone, no host       │
+  │         │    │   imports, pure computation)│
   │         │    └─ compile kb-worker.wasm ────┘
   │         │       (imports both modules)
   │         ├─ init cache
+  │         ├─ remove stale IPC socket
+  │         ├─ await createIpcServer(ctx, handler)
+  │         │    └─ kb-worker-{ctx}.sock (listening)
   │         ├─ write PID file
   │         │    └─ kb-worker-{ctx}.pid
-  │         ├─ createIpcServer(ctx, handler)
-  │         │    └─ kb-worker-{ctx}.sock
-  │         └─ listen for connections
+  │         └─ start idle timer
   └─ daemon running
 ```
 

package/docs/modules/typescript/shared/worker-daemon/typings.md

@@ -105,21 +105,27 @@ type and is passed to `createIpcServer`.
 **File:** `wasm-modules.interface.ts`
 
 References to the compiled and instantiated WASM
-module and its exported memory.
+modules and their shared exported memory.
 
 ```ts
 interface WasmModules {
    readonly memory: WebAssembly.Memory;
    readonly kbWorker: WebAssembly.Instance;
+   readonly embedding?: WebAssembly.Instance;
 }
 ```
 
-| Property   | Type                   | Description            |
-|------------|------------------------|------------------------|
-| `memory`   | `WebAssembly.Memory`   | Linear memory exported |
-|            |                        | by `kb-worker.wasm`    |
-| `kbWorker` | `WebAssembly.Instance` | Instantiated           |
-|            |                        | `kb-worker.wasm`       |
+| Property    | Type                   | Description            |
+|-------------|------------------------|------------------------|
+| `memory`    | `WebAssembly.Memory`   | Linear memory exported |
+|             |                        | by `kb-worker.wasm`    |
+| `kbWorker`  | `WebAssembly.Instance` | Instantiated           |
+|             |                        | `kb-worker.wasm`       |
+| `embedding` | `WebAssembly.Instance?`| Instantiated           |
+|             |                        | `default-embedding.wasm`. |
+|             |                        | Optional -- absent only |
+|             |                        | when build omits the   |
+|             |                        | embedding crate.       |
 
 Returned by `loadWasmModules()`.
 

package/docs/overview.md

@@ -37,8 +37,7 @@ to it as a tool.
 - **Import** Markdown files with automatic keyword
   extraction and indexing
 - **Search** three ways: keyword (default),
-  AI similarity, or hybrid (both combined) via
-  `--algo`
+  hybrid, or AI similarity via `--algo`
 - **Auto-fallback** -- loosens your query when
   exact matches return nothing
 - **Recall** sections with progressive context