@dikolab/kbdb 0.1.6 → 0.2.0

package/docs/goals/worker-client.md

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