@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -41,14 +41,16 @@ interface CliDeps {
 
 Routes:
 
-| Command     | Handler                          |
-|-------------|----------------------------------|
-| `help`      | returns `HELP_TEXT`              |
-| `version`   | returns `VERSION`                |
-| `init`      | calls `deps.runInit`             |
-| `mcp`       | calls `deps.startMcpServer`      |
-| `migrate`   | version check + migrate daemon   |
-| *(other)*   | `dispatchCommand(client, opts)`  |
+| Command          | Handler                          |
+|------------------|----------------------------------|
+| `help`           | returns `HELP_TEXT`              |
+| `version`        | returns `VERSION`                |
+| `init`           | calls `deps.runInit`             |
+| `mcp`            | calls `deps.startMcpServer`      |
+| `migrate`        | version check + migrate daemon   |
+| `worker-stop`    | `runWorkerStop(dbDir)`           |
+| `worker-restart` | `runWorkerRestart(dbDir)`        |
+| *(other)*        | `dispatchCommand(client, opts)`  |
 
 ### `dispatchCommand`
 
@@ -69,8 +71,8 @@ async function dispatchCommand(
 `DispatchClient` is the intersection of all per-command
 client interfaces (`SearchClient & LearnClient &
 UnlearnClient & RecallClient & ContentClient &
-CheckClient & GcClient & RebuildClient & ExportClient &
-SkillClient & AgentClient`).
+CheckClient & GcClient & RebuildClient & StatusClient &
+ExportClient & SkillClient & AgentClient`).
 
 | Command        | Handler                          |
 |----------------|----------------------------------|
@@ -82,6 +84,7 @@ SkillClient & AgentClient`).
 | `content`      | `runContent(client, options)`    |
 | `check`        | `runCheck(client, options)`      |
 | `gc`           | `runGc(client, options)`         |
+| `status`       | `runStatus(client, options)`     |
 | `rebuild`      | `runRebuild(client, options)`    |
 | `skill-learn`  | `runSkillLearn(client, options)` |
 | `skill-list`   | `runSkillList(client, options)`  |
@@ -110,9 +113,9 @@ Throws on invalid or missing required arguments.
 Prints help text and exits for `--help` / `--version`.
 
 **Compound command handling**: when the first positional
-argument is `db`, `skill`, or `agent`, the parser
-consumes the next positional as the subcommand and sets
-`command` to the hyphenated form:
+argument is `db`, `skill`, `agent`, or `worker`, the
+parser consumes the next positional as the subcommand
+and sets `command` to the hyphenated form:
 
 | First positional | Second positional | `command` value  |
 |------------------|-------------------|------------------|
@@ -126,6 +129,8 @@ consumes the next positional as the subcommand and sets
 | `agent`          | `list`            | `agent-list`     |
 | `agent`          | `get`             | `agent-get`      |
 | `agent`          | `delete`          | `agent-delete`   |
+| `worker`         | `stop`            | `worker-stop`    |
+| `worker`         | `restart`         | `worker-restart` |
 
 **New options parsed:**
 
@@ -384,6 +389,70 @@ Output: JSON `{ "path": "...",
 "documents_exported": number,
 "elapsed_ms": number }`.
 
+### `runStatus`
+
+**File:** `run-status.function.ts`
+
+Retrieves the database status summary report from the
+worker daemon.
+
+```ts
+async function runStatus(
+   client: StatusClient,
+   options: CliOptions,
+): Promise<unknown>;
+```
+
+`StatusClient` interface:
+
+```ts
+interface StatusClient {
+   dbStatus(): Promise<unknown>;
+}
+```
+
+Delegates to `client.dbStatus()`. The caller is
+responsible for serialising the result and setting
+the process exit code.
+
+### `runWorkerStop`
+
+**File:** `run-worker-stop.function.ts`
+
+Stops the background worker daemon for the current
+database. Discovers the daemon via its PID file and
+sends `SIGTERM`. Returns success when the daemon was
+stopped or was not running.
+
+```ts
+async function runWorkerStop(
+   dbDir: string,
+): Promise<CommandResult>;
+```
+
+Routed directly by `runCli` (not via
+`dispatchCommand`) because the worker-stop command
+does not require a live worker client connection.
+
+### `runWorkerRestart`
+
+**File:** `run-worker-restart.function.ts`
+
+Stops and restarts the background worker daemon.
+Calls `runWorkerStop` internally; the daemon
+auto-spawns on the next CLI command, so restart only
+needs to stop the current instance.
+
+```ts
+async function runWorkerRestart(
+   dbDir: string,
+): Promise<CommandResult>;
+```
+
+Routed directly by `runCli` (not via
+`dispatchCommand`) for the same reason as
+`runWorkerStop`.
+
 ### `ensureDb`
 
 **File:** `ensure-db.function.ts`
@@ -470,6 +539,35 @@ interface PromptIO {
 
 Defaults to readline on `process.stdin`/`process.stdout`.
 
+### `resolveKbidPrefix`
+
+**File:** `resolve-kbid-prefix.function.ts`
+
+Resolves a short kbid prefix to a full 26-character
+kbid. Scans all section types (`text`, `code`, `image`)
+for kbids matching the prefix and returns the full
+identifier when exactly one match exists. Full-length
+identifiers (>= 26 chars) are returned as-is. Throws
+when the prefix is ambiguous (multiple matches) or
+unrecognized (no matches).
+
+```ts
+async function resolveKbidPrefix(
+   prefix: string,
+   client: PrefixResolver,
+): Promise<string>;
+```
+
+`PrefixResolver` interface:
+
+```ts
+interface PrefixResolver {
+   listByType(
+      sectionType: string,
+   ): Promise<readonly { kbid: string }[]>;
+}
+```
+
 ### `runDbInit`
 
 **File:** `run-db-init.function.ts`
@@ -675,10 +773,15 @@ src/shared/cli/
 ├── run-export.spec.ts
 ├── run-unlearn.spec.ts
 ├── run-search.spec.ts
+├── run-recall.spec.ts
 ├── run-content.spec.ts
+├── run-status.spec.ts
 ├── run-check.spec.ts
 ├── run-gc.spec.ts
 ├── run-rebuild.spec.ts
+├── run-worker-stop.spec.ts
+├── run-worker-restart.spec.ts
+├── resolve-kbid-prefix.spec.ts
 ├── run-skill-learn.spec.ts
 ├── run-skill-list.spec.ts
 ├── run-skill-get.spec.ts

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

@@ -40,6 +40,7 @@ src/shared/cli/
 │   ├── is-stdin-tty.function.ts
 │   ├── parse-args.function.ts
 │   ├── prompt-user.function.ts
+│   ├── resolve-kbid-prefix.function.ts
 │   ├── run-agent-create.function.ts
 │   ├── run-agent-delete.function.ts
 │   ├── run-agent-get.function.ts
@@ -49,17 +50,22 @@ src/shared/cli/
 │   ├── run-content.function.ts
 │   ├── run-db-init.function.ts
 │   ├── run-db-migrate.function.ts
+│   ├── run-export.function.ts
 │   ├── run-gc.function.ts
 │   ├── run-init.function.ts
 │   ├── run-learn.function.ts
 │   ├── run-migrate.function.ts
+│   ├── run-recall.function.ts
 │   ├── run-rebuild.function.ts
 │   ├── run-search.function.ts
 │   ├── run-skill-delete.function.ts
 │   ├── run-skill-get.function.ts
 │   ├── run-skill-learn.function.ts
 │   ├── run-skill-list.function.ts
-│   └── run-unlearn.function.ts
+│   ├── run-status.function.ts
+│   ├── run-unlearn.function.ts
+│   ├── run-worker-restart.function.ts
+│   └── run-worker-stop.function.ts
 ├── typings/
 │   ├── cli-options.interface.ts
 │   ├── command-result.model.ts
@@ -72,14 +78,16 @@ src/shared/cli/
 
 - **[functions.md](functions.md)** -- `runCli`,
   `dispatchCommand`, `parseArgs`, `findDb`,
-  `runInit`, `runMigrate`, `runLearn`, `runUnlearn`,
-  `runSearch`, `runContent`, `runCheck`, `runGc`,
-  `runRebuild`, `ensureDb`, `formatOutput`,
+  `resolveKbidPrefix`, `runInit`, `runMigrate`,
+  `runLearn`, `runUnlearn`, `runSearch`, `runRecall`,
+  `runContent`, `runExport`, `runStatus`, `runCheck`,
+  `runGc`, `runRebuild`, `ensureDb`, `formatOutput`,
   `errorToMessage`, `isStdinTty`, `promptUser`,
   `runDbInit`, `runDbMigrate`, `runSkillLearn`,
   `runSkillList`, `runSkillGet`, `runSkillDelete`,
   `runAgentCreate`, `runAgentList`, `runAgentGet`,
-  `runAgentDelete`.
+  `runAgentDelete`, `runWorkerStop`,
+  `runWorkerRestart`.
 - **[typings.md](typings.md)** -- `CliOptions`,
   `CommandResult`, `LearnResult`, `SearchDisplay`,
   `SearchMode`, `OutputFormat`.
@@ -100,26 +108,31 @@ cli.ts (entry point)
   │    ├─ command === 'migrate'    → runMigrate(client, options)
   │    ├─ command === 'db-init'    → runDbInit(options)
   │    ├─ command === 'db-migrate' → runDbMigrate(client, options)
+  │    ├─ command === 'worker-stop'    → runWorkerStop(dbDir)
+  │    ├─ command === 'worker-restart' → runWorkerRestart(dbDir)
   │    └─ data command:
   │         ├─ findDb(options.dbPath) → dbDir
   │         ├─ if not found: isStdinTty() / promptUser()
   │         ├─ createWorkerClient({ contextPath: dbDir })
   │         ├─ version gate (checkVersion)
   │         └─ dispatchCommand(client, options)
-  │              ├─ learn         → runLearn(client, options)
-  │              ├─ unlearn       → runUnlearn(client, options)
-  │              ├─ search        → runSearch(client, options)
-  │              ├─ content       → runContent(client, options)
-  │              ├─ check         → runCheck(client, options)
-  │              ├─ gc            → runGc(client, options)
-  │              ├─ rebuild       → runRebuild(client, options)
-  │              ├─ skill-learn   → runSkillLearn(client, options)
-  │              ├─ skill-list    → runSkillList(client, options)
-  │              ├─ skill-get     → runSkillGet(client, options)
-  │              ├─ skill-delete  → runSkillDelete(client, options)
-  │              ├─ agent-create  → runAgentCreate(client, options)
-  │              ├─ agent-list    → runAgentList(client, options)
-  │              ├─ agent-get     → runAgentGet(client, options)
-  │              └─ agent-delete  → runAgentDelete(client, options)
+  │              ├─ learn           → runLearn(client, options)
+  │              ├─ unlearn         → runUnlearn(client, options)
+  │              ├─ search          → runSearch(client, options)
+  │              ├─ recall          → runRecall(client, options)
+  │              ├─ content         → runContent(client, options)
+  │              ├─ export          → runExport(client, options)
+  │              ├─ status          → runStatus(client, options)
+  │              ├─ check           → runCheck(client, options)
+  │              ├─ gc              → runGc(client, options)
+  │              ├─ rebuild         → runRebuild(client, options)
+  │              ├─ skill-learn     → runSkillLearn(client, options)
+  │              ├─ skill-list      → runSkillList(client, options)
+  │              ├─ skill-get       → runSkillGet(client, options)
+  │              ├─ skill-delete    → runSkillDelete(client, options)
+  │              ├─ agent-create    → runAgentCreate(client, options)
+  │              ├─ agent-list      → runAgentList(client, options)
+  │              ├─ agent-get       → runAgentGet(client, options)
+  │              └─ agent-delete    → runAgentDelete(client, options)
   └─ returns CommandResult { output?, error?, exitCode }
 ```

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

@@ -32,6 +32,8 @@ interface CliOptions {
    persona?: string;
    body?: string;
    skills?: string[];
+   timeoutMs?: number;
+   retry?: number;
 }
 ```
 
@@ -61,6 +63,8 @@ interface CliOptions {
 | `persona`     | Agent persona file path (`--persona`) |
 | `body`        | Skill body file path (`--body`)       |
 | `skills`      | Ordered skill kbid list (`--skills`)  |
+| `timeoutMs`   | Request timeout in ms                 |
+| `retry`       | Max retry count on timeout            |
 
 ### `OutputFormat`
 

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

@@ -2,35 +2,19 @@
 
 **Source:** `src/shared/embedding/functions/`
 
-## embed
+## createEmbeddingProvider
 
 ```ts
-embed(
-   provider: EmbeddingProvider,
-   text: string,
-): Promise<Float32Array>
-```
-
-Computes a single embedding vector for the given text.
-Delegates to the provider's `embed()` method. Returns a
-`Float32Array` of dimensions matching `provider.dimensions()`.
-
-Used during `learn` to embed section content and during
-`search` to embed the query string.
-
-## batchEmbed
-
-```ts
-batchEmbed(
-   provider: EmbeddingProvider,
-   texts: string[],
-): Promise<Float32Array[]>
+createEmbeddingProvider(
+   config: EmbeddingConfig,
+): EmbeddingProvider
 ```
 
-Computes embeddings for multiple texts in a single batch.
-More efficient than calling `embed()` in a loop -- providers
-can batch API calls or parallelize ONNX inference. Used
-during `rebuild` to re-embed all sections.
+Factory that returns the appropriate `EmbeddingProvider`
+implementation based on the given config. Returns an
+`OnnxEmbeddingProvider` for `type: 'onnx'`, an
+`ApiEmbeddingProvider` for `type: 'api'`, or a
+`NullEmbeddingProvider` for `type: 'none'`.
 
 ## cosineSimilarity
 
@@ -92,3 +76,98 @@ Note: This is a brute-force linear scan. For corpus sizes
 under 100k sections, this is fast enough (< 50ms). A future
 version may add approximate nearest neighbor (ANN) indexing
 if scale demands it.
+
+## appendVectorEntry
+
+```ts
+appendVectorEntry(
+   provider: EmbeddingProvider,
+   kbid: string,
+   content: string,
+   indexPath: string,
+): Promise<void>
+```
+
+Appends a single vector entry to an existing vector index.
+Used during incremental `learn` to add new sections without
+a full rebuild.
+
+## readVectorIndexMeta
+
+```ts
+readVectorIndexMeta(
+   indexPath: string,
+): Promise<VectorIndexMeta | null>
+```
+
+Reads the `vectors-meta.toml` file for an existing vector
+index. Returns `null` if the index does not exist.
+
+## rrfFuse
+
+```ts
+rrfFuse(
+   lexical: { kbid: string; rank: number }[],
+   vector: { kbid: string; score: number }[],
+   k?: number,
+): { kbid: string; score: number }[]
+```
+
+Merges lexical and vector result lists using Reciprocal
+Rank Fusion. The `k` parameter controls rank smoothing
+(default: 60).
+
+## jaccardCoefficient
+
+```ts
+jaccardCoefficient(
+   a: Set<string>,
+   b: Set<string>,
+): number
+```
+
+Computes the Jaccard similarity coefficient between two
+term sets. Returns a value in [0, 1]. Used as the first
+pass in near-duplicate detection.
+
+## detectNearDuplicates
+
+```ts
+detectNearDuplicates(
+   sections: SectionRecord[],
+   provider?: EmbeddingProvider,
+): Promise<NearDuplicateResult[]>
+```
+
+Two-pass near-duplicate detection: Jaccard coefficient on
+term sets (always), then cosine similarity on embeddings
+(when a provider is available). Returns pairs of sections
+that exceed the similarity thresholds.
+
+## detectStaleVectors
+
+```ts
+detectStaleVectors(
+   indexPath: string,
+   currentKbids: Set<string>,
+): Promise<StaleVectorsReport>
+```
+
+Compares the vector index against the current section set
+and reports entries whose kbid no longer exists. Used by
+`check` to flag stale vector data.
+
+## rebuildVectors
+
+```ts
+rebuildVectors(
+   provider: EmbeddingProvider,
+   sections: SectionRecord[],
+   outPath: string,
+): Promise<VectorIndexMeta>
+```
+
+Rebuilds the entire vector index from scratch. Embeds all
+sections and writes a fresh `vectors.idx` and
+`vectors-meta.toml`. Called by `rebuild` when an embedding
+provider is configured.

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/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/module.md

@@ -22,6 +22,8 @@ background process that:
   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
@@ -92,11 +94,12 @@ src/worker.ts (entry point)
   │         │    └─ 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
 ```