@dikolab/kbdb 0.4.0 → 0.4.1

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

@@ -16,7 +16,8 @@ results.*
 
 Core abstraction for text embedding. Accepts a batch
 of texts and returns a vector for each. Implemented
-by `NullEmbeddingProvider`, `OnnxEmbeddingProvider`,
+by `TfidfEmbeddingProvider` (built-in default),
+`NullEmbeddingProvider`, `OnnxEmbeddingProvider`,
 and `ApiEmbeddingProvider`.
 
 ```ts
@@ -58,10 +59,11 @@ interface EmbeddingConfig {
 
 | Property      | Description                              |
 |---------------|------------------------------------------|
-| `provider`    | Selects the backend: `'none'` →          |
-|               | `NullEmbeddingProvider`; `'onnx'` →      |
-|               | `OnnxEmbeddingProvider`; `'api'` →       |
-|               | `ApiEmbeddingProvider`                   |
+| `provider`    | Selects the backend: missing →            |
+|               | `TfidfEmbeddingProvider`; `'none'` →     |
+|               | `NullEmbeddingProvider`;                 |
+|               | `'onnx'` → `OnnxEmbeddingProvider`;      |
+|               | `'api'` → `ApiEmbeddingProvider`         |
 | `model`       | Path to the local ONNX model file;       |
 |               | required when `provider` is `'onnx'`     |
 | `apiEndpoint` | Remote HTTP API URL; required when       |

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

@@ -0,0 +1,82 @@
+# log/constants -- Log Constants
+
+*Default log level, per-level Unicode icons, and per-level
+ANSI color codes.*
+
+## Source
+
+`src/shared/log/constants/`
+
+## Constants
+
+### `DEFAULT_LOG_LEVEL`
+
+**File:** `log-defaults.constant.ts`
+
+Default log level used when no CLI flag or `KBDB_LOG_LEVEL`
+environment variable is set.
+
+```ts
+const DEFAULT_LOG_LEVEL = LogLevel.ERROR;
+```
+
+Evaluated by `resolveLogLevel` as the lowest-priority
+fallback.
+
+### `LOG_ICONS`
+
+**File:** `log-icons.constant.ts`
+
+Single-character Unicode icon used as the visual prefix
+for each log level's output line.
+
+```ts
+const LOG_ICONS: Record<LogLevel, string> = {
+   [LogLevel.DEBUG]:   '▸',
+   [LogLevel.INFO]:    'ℹ',
+   [LogLevel.WARNING]: '⚠',
+   [LogLevel.ERROR]:   '✖',
+};
+```
+
+| Level     | Icon | Meaning           |
+|-----------|------|-------------------|
+| `DEBUG`   | `▸`  | Right arrow       |
+| `INFO`    | `ℹ`  | Information sign  |
+| `WARNING` | `⚠`  | Warning sign      |
+| `ERROR`   | `✖`  | Multiplication X  |
+
+### `LOG_COLORS`
+
+**File:** `log-colors.constant.ts`
+
+ANSI foreground color escape sequence applied before
+each log line's content.
+
+```ts
+const LOG_COLORS: Record<LogLevel, string> = {
+   [LogLevel.DEBUG]:   '\x1b[37m',
+   [LogLevel.INFO]:    '\x1b[36m',
+   [LogLevel.WARNING]: '\x1b[33m',
+   [LogLevel.ERROR]:   '\x1b[91m',
+};
+```
+
+| Level     | Code       | Color       |
+|-----------|------------|-------------|
+| `DEBUG`   | `\x1b[37m` | White       |
+| `INFO`    | `\x1b[36m` | Cyan        |
+| `WARNING` | `\x1b[33m` | Yellow      |
+| `ERROR`   | `\x1b[91m` | Bright red  |
+
+### `ANSI_RESET`
+
+**File:** `log-colors.constant.ts`
+
+ANSI escape sequence that resets all text formatting.
+Appended at the end of every log line so subsequent
+terminal output is unaffected.
+
+```ts
+const ANSI_RESET = '\x1b[0m';
+```

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/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-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,9 +15,9 @@ 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
@@ -91,6 +91,9 @@ 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

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()`.