@dikolab/kbdb 0.4.3 → 0.6.0

package/docs/goals/worker-client.md

@@ -1,1005 +0,0 @@
-# Worker Client
-
-*A shared TypeScript module that discovers or spawns
-the worker daemon and provides a typed API for all
-knowledge base operations over IPC.*
-
-## Goal
-
-`src/cli.ts` needs to communicate with the worker
-daemon (`src/worker.ts`) to perform database
-operations. The worker client module is the single
-shared entry point for that communication. It
-handles:
-
-- Resolving the database directory path.
-- Computing the context ID.
-- Discovering an existing daemon or spawning a new one.
-- Connecting to the daemon's IPC socket.
-- Exposing every daemon IPC method as a typed async
-  function.
-- Managing connection lifecycle (connect, reconnect,
-  disconnect).
-
-No other module in the TypeScript layer communicates
-with the daemon directly. `src/cli.ts` imports the
-worker client and calls its methods -- it never
-constructs IPC messages, manages PID files, or
-spawns processes itself.
-
-```
-src/cli.ts ──→ worker-client ──→ src/worker.ts
-```
-
-## Module Location
-
-```
-src/shared/worker-client/
-├── mod.ts              # public API: createWorkerClient
-├── resolve.ts          # database directory resolution
-├── context.ts          # context ID computation
-├── discovery.ts        # PID file lookup, process check
-├── spawn.ts            # daemon spawning (Node + Deno)
-├── connection.ts       # IPC socket connect / reconnect
-└── types.ts            # request/response type defs
-```
-
-The module is internal to the package. It is not
-exported from the library's public API (`mod.ts` at
-the project root). Only `src/cli.ts` imports it.
-
-## When the Daemon Is Needed
-
-The worker client is only created when the caller needs
-to perform operations that involve the `.kbdb` database
-directory:
-
-- **Search and query** -- Looking up indexes, ranking
-  results, retrieving sections or documents.
-- **Content management** -- `kbdb learn` (import,
-  index) and `kbdb unlearn` (remove, re-index).
-- **Status and retrieval** -- Database metadata,
-  content retrieval by ID.
-
-Operations that do not touch the database do not create
-a worker client and do not require a daemon:
-
-- `kbdb --help`, `kbdb --version`
-- Invalid commands or argument validation errors
-- Any subcommand that exits before reaching the
-  database
-
-## Database Directory Resolution
-
-The worker client resolves the database directory path
-before connecting to the daemon:
-
-1. If the caller provides a `targetDir` (e.g. from a
-   CLI `--db <path>` flag), use it.
-2. Otherwise, use the current working directory.
-
-The database directory is always
-`${targetDir}/.kbdb`. The worker client checks that
-this directory exists before proceeding. If `.kbdb`
-does not exist, the factory throws -- the caller is
-responsible for database initialization (e.g. the CLI
-prompts the user to create it).
-
-## Context ID
-
-The worker client computes the context ID during
-`createWorkerClient()` and includes it in every IPC
-request. The context ID is a **SHA-256 hash of the
-database directory's absolute path**, truncated to 16
-lowercase hexadecimal characters.
-
-```
-SHA-256(absolutePath) → truncate to 16 hex chars → ctx
-```
-
-See [Worker Daemon -- Context ID](
-worker-daemon.md#context-id) for the full
-specification, including how the daemon validates the
-context ID on every request.
-
-## Daemon Discovery
-
-When the worker client is created, it follows this
-discovery sequence:
-
-1. Compute the context ID from the database directory
-   path.
-2. Look for `kb-worker-{ctx}.pid` in the OS temporary
-   directory (e.g., `/tmp` on Linux/macOS, `%TEMP%` on
-   Windows).
-3. If the PID file exists, read the process ID and
-   check whether the process is alive (see
-   Platform-Specific PID Handling below).
-4. If the process is alive, connect to the IPC socket
-   at `kb-worker-{ctx}.sock` (or the named pipe on
-   Windows).
-5. If the PID file is missing or the process is dead
-   (stale PID file), remove the stale file and spawn
-   a new daemon (see Spawning below).
-
-The PID file contains only the process ID number as
-plain text (e.g., `12345`). No other data.
-
-### Platform-Specific PID Handling
-
-Both Linux/macOS and Windows use integer process IDs.
-The PID file format is identical across platforms -- a
-single integer as plain text. The differences are in
-how the worker client resolves the temporary directory
-and checks whether the process is alive.
-
-**Temporary directory:**
-
-| Platform      | Resolution                            |
-|---------------|---------------------------------------|
-| Linux / macOS | `$TMPDIR` if set, otherwise `/tmp`    |
-| Windows       | `%TEMP%` (typically `C:\Users\{user}\AppData\Local\Temp`) |
-
-In Node.js, `os.tmpdir()` returns the correct path on
-all platforms. In Deno, `Deno.env.get("TMPDIR")` (Unix)
-or `Deno.env.get("TEMP")` (Windows) provides the same.
-
-**Checking if a process is alive:**
-
-The worker client must verify that the PID read from
-the file refers to a running daemon, not a dead process
-whose PID has been recycled by the OS.
-
-**Linux / macOS** -- Use a zero signal via `kill()`:
-
-```ts
-// Node.js
-try {
-   process.kill(pid, 0); // signal 0 = no signal sent
-   // process exists
-} catch {
-   // process does not exist (ESRCH) or
-   // not permitted (EPERM -- process exists
-   // but is owned by another user)
-}
-```
-
-`kill(pid, 0)` sends no actual signal. It returns
-successfully if the process exists and the caller has
-permission to signal it. It throws `ESRCH` if the
-process does not exist. An `EPERM` error means the
-process exists but belongs to another user -- this
-should be treated as "alive" since the PID is in use.
-
-**Windows** -- `process.kill(pid, 0)` is supported in
-Node.js on Windows and behaves the same way: it checks
-process existence without sending a signal. This is the
-preferred cross-platform method.
-
-For Deno on Windows, where `Deno.kill()` does not
-support signal 0, use a subprocess check:
-
-```ts
-// Deno (Windows fallback)
-const cmd = new Deno.Command('tasklist', {
-   args: ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'],
-   stdout: 'piped',
-   stderr: 'null',
-});
-const { stdout } = await cmd.output();
-const output = new TextDecoder().decode(stdout);
-const alive = output.includes(`"${pid}"`);
-```
-
-`tasklist /FI "PID eq {pid}"` filters the process list
-by PID. If the output contains the PID, the process is
-alive. The `/NH` flag suppresses the header and `/FO
-CSV` outputs in CSV format for reliable parsing.
-
-**Cross-platform wrapper:**
-
-The worker client implements a single
-`isProcessAlive(pid)` function that selects the correct
-method based on `process.platform` (Node.js) or
-`Deno.build.os` (Deno):
-
-| Runtime   | Linux / macOS          | Windows                  |
-|-----------|------------------------|--------------------------|
-| Node.js   | `process.kill(pid, 0)` | `process.kill(pid, 0)`   |
-| Deno      | `Deno.kill(pid, "SIGCONT")` | `tasklist` subprocess |
-
-This function returns `true` if the process is alive,
-`false` if it is not. The daemon discovery sequence
-calls it after reading the PID file to decide whether
-to connect or spawn.
-
-## Spawning
-
-The worker client spawns the daemon as a **detached
-child process** so it outlives the parent. Unlike a
-typical fire-and-forget detach, the worker client
-**captures the daemon's stderr** during the spawn
-window so that startup failures can be relayed to the
-caller.
-
-**Node.js:**
-
-```js
-const child = spawn(
-   'node',
-   ['kb-worker.js', contextPath],
-   {
-      detached: true,
-      stdio: ['ignore', 'ignore', 'pipe'],
-   },
-);
-```
-
-**Deno:**
-
-```ts
-const cmd = new Deno.Command('deno', {
-   args: [
-      'run', '--allow-all',
-      'src/worker.ts', contextPath,
-   ],
-   stdin: 'null',
-   stdout: 'null',
-   stderr: 'piped',
-});
-const child = cmd.spawn();
-```
-
-Note: `stderr` is `'pipe'` / `'piped'`, not
-`'ignore'`. The worker client reads from it during
-the spawn window. Once the PID file appears
-(indicating successful startup), the worker client
-closes the stderr pipe and unrefs the child so the
-daemon can outlive the parent.
-
-The spawning sequence:
-
-1. Worker client ensures `worker.toml` exists in the
-   context directory (writes defaults if missing).
-2. Worker client spawns `src/worker.ts` (or its
-   compiled `.js` equivalent) with the context path as
-   the sole command-line argument. stderr is piped to
-   the worker client.
-3. Worker client polls for the PID file to appear (with
-   a short timeout, default 10 000 ms) to confirm the
-   daemon started.
-4. **On PID file found (success):** worker client
-   closes the stderr pipe, detaches the child, unrefs
-   it, and connects to the IPC socket. Because the
-   daemon writes the PID file only after the socket
-   is listening, the client can connect immediately.
-5. **On timeout or child exit (failure):** worker
-   client reads all buffered stderr from the daemon,
-   includes it in the thrown error (see Startup
-   Failure Handling below).
-
-There is no fallback to in-process WASM loading -- the
-daemon is required for all database operations.
-
-### Startup Failure Handling
-
-When the daemon fails to start -- either because a
-startup precondition failed (see
-[Worker Daemon -- Startup Preconditions](
-worker-daemon.md#startup-preconditions)) or the
-process exited unexpectedly -- the worker client
-detects the failure by one of:
-
-- The child process exits before the PID file appears.
-- The PID file poll times out.
-
-In either case, the worker client:
-
-1. Reads the daemon's buffered stderr output.
-2. Throws a `WorkerClientError` that includes the
-   daemon's stderr message in the error's `message`
-   property.
-
-```ts
-interface WorkerClientError extends Error {
-   code: number;
-   /** Daemon stderr output, if available. */
-   daemonStderr?: string;
-}
-```
-
-The error code is `-32003` (daemon unavailable).
-
-The caller (CLI or MCP) is responsible for printing
-the error. In practice, the CLI prints the error to
-its own stderr and exits non-zero. This means the
-daemon's error message flows through to the user's
-terminal:
-
-```
-kbdb search "query"
-  -> worker client spawns daemon
-  -> daemon checks preconditions
-  -> daemon prints to its stderr:
-     "error: database version 3 is newer than kbdb
-       version 2 -- upgrade kbdb to open this database"
-  -> daemon exits with code 1
-  -> worker client reads daemon stderr
-  -> worker client throws WorkerClientError with
-     daemonStderr containing the message
-  -> src/cli.ts catches error, prints to stderr:
-     "error: daemon failed to start: database version
-       3 is newer than kbdb version 2 -- upgrade kbdb
-       to open this database"
-  -> src/cli.ts sets process.exitCode = 1
-```
-
-This relay ensures the user sees the daemon's specific
-error reason even though the daemon runs as a separate
-detached process. The daemon's stderr is the single
-source of truth for startup failure diagnostics.
-
-## Connection Retry
-
-When the worker client calls `connect()`, transient
-errors (`ENOENT` -- socket not yet created, or
-`ECONNREFUSED` -- server not yet accepting) are
-retried with exponential backoff:
-
-- **Max retries**: 5
-- **Initial delay**: 50 ms
-- **Backoff**: doubles each attempt (50, 100, 200,
-  400, 800 ms = ~1.55 s worst case)
-- **Non-transient errors** (`EACCES`, `EINVAL`, etc.)
-  fail immediately without retry.
-
-This covers the narrow window where the PID file
-exists but the socket has not yet finished binding
-(e.g. under heavy load or slow I/O).
-
-## Post-Connect Failure Handling
-
-After a successful `connect()`, if the daemon crashes
-or the IPC socket dies:
-
-1. All pending RPC calls (in `this.pending`) are
-   rejected with a descriptive error.
-2. The client marks itself as disconnected
-   (`this.socket = null`).
-3. The socket is destroyed.
-
-The `isConnected` getter exposes the connection
-state so callers (and the cached client factory) can
-check before reusing a client.
-
-## Cached Client Factory
-
-`getOrCreateClient(options?)` returns a cached
-`WorkerClient` for the given context path, or creates
-and caches a new one if the cached client is
-disconnected or absent.
-
-```ts
-import { getOrCreateClient } from '@dikolab/kbdb';
-
-const client = await getOrCreateClient({
-   dbPath: '/path/to/project',
-});
-```
-
-Intended for library consumers and the MCP server.
-CLI one-shots should use `createWorkerClient()`
-directly (each is a separate process anyway).
-
-## Socket Keepalive
-
-Both the client and server enable `SO_KEEPALIVE`
-with a 30-second interval. This ensures both ends
-detect a dead peer within ~30 seconds, even if no
-application-level traffic is flowing.
-
-## `createWorkerClient(options?)`
-
-Factory function. Returns a connected `WorkerClient`
-instance.
-
-```ts
-interface WorkerClientOptions {
-   targetDir?: string;
-}
-
-function createWorkerClient(
-   options?: WorkerClientOptions,
-): Promise<WorkerClient>;
-```
-
-**Resolution order for `targetDir`:**
-
-1. If `options.targetDir` is provided, use it.
-2. Otherwise, use the current working directory.
-
-The factory then:
-
-1. Resolves the absolute path: `${targetDir}/.kbdb`.
-2. Computes the context ID (SHA-256 of the absolute
-   path, truncated to 16 lowercase hex characters).
-3. Checks whether `.kbdb` exists at the resolved path.
-   If not, throws -- the caller is responsible for
-   prompting the user or initializing the database
-   before creating a client.
-4. Looks for `kb-worker-{ctx}.pid` in the OS temp
-   directory and checks whether the daemon is alive
-   (see Daemon Discovery above).
-5. If no daemon is running, spawns one (see Spawning
-   above).
-6. Connects to the IPC socket
-   (`kb-worker-{ctx}.sock` on Unix,
-   `\\.\pipe\kb-worker-{ctx}` on Windows).
-7. Returns the connected `WorkerClient`.
-
-If the daemon fails to start or the IPC connection
-cannot be established, the factory throws.
-
-## `WorkerClient`
-
-All methods are async. High-level methods (`search`,
-`readSections`, `addSection`, `updateSection`,
-`removeSection`, `groupSections`, `removeGrouping`,
-`retrieveDocument`, `content`) are composed from
-the low-level IPC primitives (`query` →
-`get_result_status` → `get_result`) documented in
-[Worker Daemon -- IPC API](worker-daemon.md). The
-daemon routes these queries to `kb-worker.wasm`,
-which orchestrates `fs-database.wasm` and
-`query-parser.wasm`.
-
-`content()` takes one or more kbid or docid
-identifiers (mixed freely) and returns a composed
-Markdown document. It delegates to the daemon's
-`compose` IPC method, which triggers `kb-worker.wasm`
-to resolve identifiers, fetch sections, extract
-markers recursively, and call the `content-composer`
-module in `kbdb-shared`. See
-[Content Composer](content-composer.md) for the full
-composition specification.
-
-Maintenance methods (`integrityCheck`, `gc`,
-`rebuildIndexes`) delegate to the corresponding
-daemon IPC methods (`integrity_check`, `gc`,
-`rebuild_indexes`). These return results directly
-(not via the token pattern) because maintenance
-operations are infrequent and their results are not
-cached.
-
-`dbStatus()` returns data from the initialization
-response cached at connect time -- it does not
-issue a separate IPC call.
-
-```ts
-interface WorkerClient {
-   readonly ctx: string;
-   readonly targetDir: string;
-
-   // Lifecycle
-   disconnect(): Promise<void>;
-
-   // Status
-   status(): Promise<DaemonStatus>;
-   idleAt(): Promise<number>;
-   config(key: ConfigKey): Promise<number>;
-   dbStatus(): Promise<DbStatus>;
-
-   // Search
-   search(params: SearchParams):
-      Promise<PagedSearchResult>;
-
-   // Context expansion
-   recall(params: {
-      kbid?: string;
-      kbids?: string[];
-      depth?: number;
-   }): Promise<RecallResult | RecallResult[]>;
-
-   // Sections
-   readSections(kbIds: string[]):
-      Promise<KbdbResult<Section[]>>;
-   addSection(params: AddSectionParams):
-      Promise<AddSectionResult>;
-   updateSection(params: UpdateSectionParams):
-      Promise<UpdateSectionResult>;
-   removeSection(kbId: string):
-      Promise<RemoveSectionResult>;
-
-   // Documents
-   groupSections(params: GroupSectionsParams):
-      Promise<GroupSectionsResult>;
-   removeGrouping(docid: string):
-      Promise<RemoveGroupingResult>;
-   retrieveDocument(docid: string):
-      Promise<KbdbResult<DocumentResult>>;
-
-   // Content composition
-   content(ids: string[]):
-      Promise<ContentResult>;
-
-   // Maintenance
-   integrityCheck(): Promise<IntegrityCheckResult>;
-   gc(): Promise<GcResult>;
-   rebuildIndexes(): Promise<RebuildResult>;
-
-   // Cache
-   invalidate(keys: string[]): Promise<number>;
-   invalidateAll(): Promise<number>;
-
-   // Low-level query (token-based)
-   query(kbId: string): Promise<string>;
-   getResultStatus(token: string):
-      Promise<ResultStatus>;
-   getResult<T extends ResultType>(
-      token: string,
-      type: T,
-   ): Promise<ResultData<T> | null>;
-}
-```
-
-## Type Definitions
-
-**Status types:**
-
-```ts
-type DaemonStatus = 'busy' | 'idle';
-
-type ConfigKey =
-   | 'timeout_ms'
-   | 'item_ttl_ms'
-   | 'item_limit'
-   | 'index_limit';
-
-interface DbStatus {
-   target_dir: string;
-   document_count: number;
-   section_count: number;
-   index_size_bytes: number;
-   last_modified: string;
-   cache_stats: {
-      items_cached: number;
-      hit_rate: number;
-   };
-}
-```
-
-**Search types:**
-
-`search()` now returns a `PagedSearchResult` envelope.
-Individual `SectionMatch` items include `heading`,
-`type`, `docids`, `snippet`, and `matched_terms`
-alongside `score`. The MCP layer strips `score`; the
-CLI and IPC layers retain it.
-
-```ts
-interface SearchParams {
-   query: string;
-   mode: 'sections' | 'documents' | 'stats';
-   limit?: number;
-   offset?: number;
-}
-
-interface PagedSearchResult {
-   items: SectionMatch[];
-   total: number;
-   offset: number;
-   limit: number;
-   has_more: boolean;
-}
-
-type SearchResult =
-   | SectionSearchResult
-   | DocumentSearchResult
-   | StatsSearchResult;
-
-interface SectionSearchResult {
-   type: 'section';
-   data: SectionMatch[];
-   references: (Section | DocumentResult)[];
-   total: number;
-   query_time_ms: number;
-   query: string;
-}
-
-interface DocumentSearchResult {
-   type: 'document';
-   data: DocumentMatch[];
-   references: (Section | DocumentResult)[];
-   total: number;
-   query_time_ms: number;
-   query: string;
-}
-
-interface StatsSearchResult {
-   total_matches: number;
-   query_time_ms: number;
-   top_terms: TermStat[];
-   query: string;
-}
-```
-
-**Match types:**
-
-```ts
-interface SectionMatch {
-   kbid: string;
-   docids: string[];
-   type: string;
-   heading: string | null;
-   score: number;
-   snippet: string;
-   matched_terms: string[];
-}
-
-interface DocumentMatch {
-   docid: string;
-   title: string;
-   score: number;
-   matching_sections: Array<{
-      kbid: string;
-      type: string;
-      heading: string;
-      score: number;
-      snippet: string;
-   }>;
-}
-
-interface TermStat {
-   term: string;
-   frequency: number;
-   sections_matched: number;
-}
-```
-
-**Recall types:**
-
-`recall()` returns progressive context expansion for
-one or more sections. Returns `RecallResult` for a
-single kbid or `RecallResult[]` for a batch. The
-`depth` parameter controls how much context is
-included (0--3).
-
-```ts
-interface RecallResult {
-   kbid: string;
-   heading: string | null;
-   type: string;
-   content: string;
-   docids: string[];
-   // Present at depth >= 1:
-   documents?: RecallDocument[];
-   back_references?: RecallReference[];
-   // Present at depth >= 2:
-   siblings?: RecallResult[];
-   // Present at depth >= 3:
-   references?: RecallResult[];
-}
-
-interface RecallDocument {
-   docid: string;
-   title: string;
-   sections: Array<{
-      kbid: string;
-      heading: string | null;
-      type: string;
-   }>;
-}
-
-interface RecallReference {
-   kbid: string;
-   heading: string | null;
-   type: string;
-   marker_type: string;
-   context_snippet: string;
-   direction: 'back';
-}
-```
-
-Maps to the daemon's `recall` IPC method, which
-calls `worker_recall` in the WASM engine.
-
-**Section types:**
-
-```ts
-interface Section {
-   kbid: string;
-   docids: string[];
-   type: string;
-   title?: string;
-   description?: string;
-   token_count: number;
-   heading_token_count: number;
-   body_token_count: number;
-   code_token_count: number;
-   content: string;
-}
-
-interface AddSectionParams {
-   content: string;
-   type: string;
-   title?: string;
-   description?: string;
-   docid?: string;
-}
-
-interface AddSectionResult {
-   kbid: string;
-   type: string;
-   title?: string;
-   description?: string;
-   token_count: number;
-   indexed_terms_count: number;
-   elapsed_ms: number;
-   attached: boolean;
-}
-
-interface UpdateSectionParams {
-   kbid: string;
-   content: string;
-}
-
-interface UpdateSectionResult {
-   old_kbid: string;
-   new_kbid: string;
-   reindexed_terms_count: number;
-   elapsed_ms: number;
-}
-
-interface RemoveSectionResult {
-   removed: boolean;
-   elapsed_ms: number;
-}
-```
-
-**Document types:**
-
-```ts
-interface GroupSectionsParams {
-   docid: string;
-   title: string;
-   kbids: string[];
-}
-
-interface GroupSectionsResult {
-   docid: string;
-   section_count: number;
-   elapsed_ms: number;
-}
-
-interface RemoveGroupingResult {
-   removed: boolean;
-   sections_ungrouped: number;
-   elapsed_ms: number;
-}
-
-interface DocumentResult {
-   docid: string;
-   title: string;
-   created_at: string;
-   sections: Array<{
-      kbid: string;
-      docids: string[];
-      type: string;
-      title?: string;
-      description?: string;
-      content: string;
-      position: number;
-   }>;
-}
-```
-
-**Unified result shape:**
-
-```ts
-interface KbdbResult<T> {
-   type: 'section' | 'document';
-   data: T;
-   references: (Section | DocumentResult)[];
-   total: number;
-}
-```
-
-`KbdbResult<T>` wraps all retrieval and search
-responses. The `references` array contains unique,
-recursively resolved records for every marker found
-in the returned content (see
-[Document](document.md) for marker types and
-[Content Parser](content-parser.md) for extraction).
-`total` is the full count of matching entities --
-`data.length` may be smaller when `limit` is applied.
-
-`SearchResult` (`SectionSearchResult` and
-`DocumentSearchResult`) follows the same shape with
-additional search-specific fields (`query_time_ms`,
-`query`). `StatsSearchResult` does not use the
-unified shape since it returns aggregate statistics,
-not entities.
-
-**Content composition result:**
-
-```ts
-interface ContentResult {
-   type: 'text/markdown';
-   data: string;
-   total: number;
-}
-```
-
-`ContentResult` wraps the output of the content
-composition engine. `data` is the composed Markdown
-string. `total` is the character count of `data`
-(not byte count). See
-[Content Composer](content-composer.md) for the full
-composition specification.
-
-**Maintenance types:**
-
-```ts
-interface IntegrityCheckResult {
-   ok: boolean;
-   errors: IntegrityError[];
-   sections_checked: number;
-   documents_checked: number;
-   references_checked: number;
-   elapsed_ms: number;
-}
-
-interface IntegrityError {
-   type:
-      | 'checksum_mismatch'
-      | 'orphan_section'
-      | 'orphan_document'
-      | 'broken_reference'
-      | 'type_mismatch'
-      | 'circular_reference';
-   entity: string;
-   detail: string;
-}
-
-interface GcResult {
-   removed_sections: number;
-   removed_bytes: number;
-   elapsed_ms: number;
-}
-
-interface RebuildResult {
-   sections_reindexed: number;
-   terms_indexed: number;
-   elapsed_ms: number;
-}
-```
-
-`IntegrityCheckResult` reports all issues found in
-the database. Error types match
-[Database -- Integrity and Maintenance](database.md).
-`GcResult` reports sections removed and bytes freed.
-`RebuildResult` reports sections and terms
-re-indexed.
-
-**Low-level query types:**
-
-```ts
-type ResultType =
-   | 'kbid'
-   | 'docid'
-   | 'section'
-   | 'content'
-   | 'kbid[]'
-   | 'docid[]'
-   | 'section[]'
-   | 'content[]';
-
-interface ResultStatus {
-   status: 'busy' | 'success' | 'fail';
-   reason: string;
-}
-```
-
-## Connection Lifecycle
-
-**Short-lived (CLI):**
-
-```
-src/cli.ts
-  │
-  ├─ parse args, resolve targetDir
-  ├─ createWorkerClient({ targetDir })
-  │    ├─ find or spawn daemon
-  │    └─ connect to IPC socket
-  ├─ client.search(...) / client.addSection(...)
-  ├─ print result to stdout
-  └─ client.disconnect()
-```
-
-The CLI creates the client, makes one or a few calls,
-and disconnects. The daemon stays alive for subsequent
-invocations.
-
-**Long-lived (MCP):**
-
-```
-src/cli.ts
-  │
-  ├─ createWorkerClient({ targetDir })
-  │    ├─ find or spawn daemon
-  │    └─ connect to IPC socket
-  ├─ listen for MCP requests
-  │    ├─ MCP search  → client.search(...)
-  │    ├─ MCP add     → client.addSection(...)
-  │    ├─ MCP remove  → client.removeSection(...)
-  │    └─ ...
-  └─ on shutdown: client.disconnect()
-```
-
-The MCP server holds the connection open. All incoming
-MCP requests route through the same `WorkerClient`.
-
-## Reconnection
-
-If the IPC connection drops (daemon crashed, idle
-timeout, OS killed the process), the client does not
-throw immediately. On the next method call, it:
-
-1. Detects the broken connection.
-2. Runs the discovery sequence again (PID file check,
-   spawn if needed).
-3. Reconnects to the new daemon's IPC socket.
-4. Retries the method call once.
-
-If reconnection fails, the method throws. The caller
-handles the error.
-
-This makes the MCP server resilient to daemon restarts
-without manual reconnection logic. The CLI benefits
-too -- if a daemon dies between the spawn check and
-the first method call, the client recovers.
-
-## Error Handling
-
-All client methods throw on:
-
-- **Connection failure** -- Cannot connect to the
-  daemon after discovery and spawn attempts.
-- **Spawn failure** -- Daemon did not start within
-  the timeout.
-- **IPC error** -- JSON-RPC 2.0 error response from
-  the daemon (context mismatch, invalid token, method
-  not found).
-- **Reconnection failure** -- Broken connection and
-  the retry also failed.
-
-Errors are thrown as typed error objects with a `code`
-property matching the JSON-RPC 2.0 error codes defined
-in [Worker Daemon -- Error Responses](
-worker-daemon.md#error-responses):
-
-```ts
-interface WorkerClientError extends Error {
-   code: number;
-}
-```
-
-## Design Constraints
-
-- The worker client is the **sole IPC client** for the
-  daemon. No other TypeScript module sends messages to
-  `src/worker.ts`.
-- The client does not cache data. Caching is the
-  daemon's responsibility (via `kb-worker.wasm`).
-- The client does not perform database I/O. All
-  storage operations go through the daemon.
-- The client does not perform text processing. That is
-  `query-parser.wasm`'s job inside the daemon.
-- The module works on both Deno and Node.js. Platform
-  differences (IPC sockets, process spawning, PID
-  checks) are abstracted inside internal files.
-- The client's public API mirrors the IPC wire format.
-  Types match the JSON shapes defined in the Endpoints
-  section of [Database](database.md) and the IPC API
-  sections of [Worker Daemon](worker-daemon.md). No
-  transformation layer.