@dikolab/kbdb 0.5.0 → 0.6.0

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

@@ -1,124 +0,0 @@
-# embedding/typings -- Embedding Type Definitions
-
-*Interfaces and type aliases for the embedding
-module's providers, configuration, and search
-results.*
-
-## Source
-
-`src/shared/embedding/typings/`
-
-## Typings
-
-### `EmbeddingProvider`
-
-**File:** `embedding-provider.typing.ts`
-
-Core abstraction for text embedding. Accepts a batch
-of texts and returns a vector for each. Implemented
-by `TfidfEmbeddingProvider` (built-in default),
-`NullEmbeddingProvider`, `OnnxEmbeddingProvider`,
-and `ApiEmbeddingProvider`.
-
-```ts
-interface EmbeddingProvider {
-   embed(texts: string[]): Promise<Float32Array[]>;
-   dimensions(): number;
-   modelName(): string;
-}
-```
-
-| Member       | Description                             |
-|--------------|-----------------------------------------|
-| `embed`      | Produces one embedding vector per input |
-|              | text; accepts an array for batching     |
-|              | efficiency                              |
-| `dimensions` | Returns the length of each vector       |
-|              | (e.g. 384 for MiniLM)                  |
-| `modelName`  | Returns a stable identifier stored in   |
-|              | `vectors-meta.toml`; used to detect     |
-|              | model changes that require a rebuild    |
-
-### `EmbeddingConfig`
-
-**File:** `embedding-config.typing.ts`
-
-Configuration read from the `[embedding]` section
-of `worker.toml`. Determines which `EmbeddingProvider`
-implementation to instantiate at daemon startup.
-
-```ts
-interface EmbeddingConfig {
-   provider: 'none' | 'onnx' | 'api';
-   model?: string;
-   apiEndpoint?: string;
-   apiKey?: string;
-   dimensions?: number;
-}
-```
-
-| Property      | Description                              |
-|---------------|------------------------------------------|
-| `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       |
-|               | `provider` is `'api'`                    |
-| `apiKey`      | Bearer token for the remote API;         |
-|               | required when `provider` is `'api'`      |
-| `dimensions`  | Vector length; inferred from the model   |
-|               | when possible; required for API          |
-|               | providers that do not report dimensions  |
-
-### `VectorSearchResult`
-
-**File:** `vector-search-result.typing.ts`
-
-A single result from a vector similarity search.
-Used as input to the RRF fusion step alongside
-lexical search results.
-
-```ts
-interface VectorSearchResult {
-   kbid: string;
-   similarity: number;
-}
-```
-
-| Property     | Description                             |
-|--------------|-----------------------------------------|
-| `kbid`       | Knowledge-base identifier of the        |
-|              | matched section                         |
-| `similarity` | Cosine similarity score in [-1, 1]      |
-
-### `VectorIndexMeta`
-
-**File:** `vector-index-meta.typing.ts`
-
-Metadata stored in `vectors-meta.toml` alongside
-`vectors.idx`. Used to detect stale indexes: when
-`model` differs from the current provider's
-`modelName()`, vectors must be rebuilt.
-
-```ts
-interface VectorIndexMeta {
-   model: string;
-   dimensions: number;
-   recordCount: number;
-   version: number;
-}
-```
-
-| Property      | Description                             |
-|---------------|-----------------------------------------|
-| `model`       | `modelName()` value at index build time |
-| `dimensions`  | Vector length used when building the    |
-|               | index                                   |
-| `recordCount` | Number of vectors stored in the index   |
-| `version`     | Format version; currently `1`           |
-
-No spec -- typings are compile-time only.

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

@@ -1,20 +0,0 @@
-# hash/functions -- Hash Functions
-
-**Source:** `src/shared/hash/functions/`
-
-## computeSha256
-
-```ts
-computeSha256(input: string): Promise<string>
-```
-
-Returns a hex-encoded SHA-256 hash of the input string.
-
-Uses the Web Crypto API
-(`globalThis.crypto.subtle.digest`), which is available
-in both Deno and Node.js >= 20.
-
-### Usage
-
-Used by `compute-context-id.function.ts` (truncated to
-16 hex chars) and content hashing.

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

@@ -1,21 +0,0 @@
-# hash -- Hashing Utilities
-
-**Source:** `src/shared/hash/`
-
-## Responsibility
-
-SHA-256 hashing for context ID computation and
-content-addressable storage.
-
-## Directory Layout
-
-```
-src/shared/hash/
-   index.ts
-   functions/
-      compute-sha256.function.ts
-```
-
-## Exports
-
-- [Functions](functions.md) -- `computeSha256`

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

@@ -1,82 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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

@@ -1,153 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-# 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.