@dikolab/kbdb 0.1.6 → 0.2.1

package/docs/modules/typescript/shared/worker-client/classes.md

@@ -0,0 +1,264 @@
+# worker-client/classes -- WorkerClient
+
+*IPC client class. Sends JSON-RPC 2.0 requests to the
+worker daemon over a Unix socket or Windows named pipe
+and returns typed results.*
+
+## Source
+
+`src/shared/worker-client/classes/`
+
+## Classes
+
+### `WorkerClient`
+
+**File:** `worker-client.class.ts`
+
+Holds the IPC connection and exposes every daemon
+operation as a typed async method. Instantiated
+directly via the constructor -- not created through a
+factory function.
+
+All methods send a JSON-RPC 2.0 request over the IPC
+connection and await the response. The `ctx` parameter
+is automatically injected into every request.
+
+```ts
+class WorkerClient {
+   constructor(
+      socketPath: string,
+      contextId: string,
+   );
+
+   // Lifecycle
+   connect(): Promise<void>;
+   disconnect(): void;
+
+   // Status
+   status(): Promise<StatusResult>;
+   dbStatus(): Promise<StatusResult>;
+
+   // Search
+   search(params: SearchParams):
+      Promise<PagedSearchResult>;
+   recall(params: RecallParams):
+      Promise<RecallResult | RecallResult[]>;
+
+   // Sections
+   readSections(kbids: string[]):
+      Promise<Section[]>;
+   addSection(params: AddSectionParams):
+      Promise<AddSectionResult>;
+   updateSection(
+      kbid: string,
+      params: AddSectionParams,
+   ): Promise<string>;
+   removeSection(kbid: string):
+      Promise<RemoveSectionResult>;
+
+   // Documents
+   groupSections(
+      title: string,
+      kbids: string[],
+   ): Promise<string>;
+   removeGrouping(docid: string): Promise<void>;
+   retrieveDocument(docid: string): Promise<unknown>;
+
+   // Content composition
+   content(ids: string[]): Promise<ContentResult>;
+
+   // Maintenance
+   integrityCheck(): Promise<IntegrityCheckResult>;
+   gc(): Promise<GcResult>;
+   rebuildIndexes(): Promise<RebuildResult>;
+
+   // Typed listing
+   listByType(sectionType: string): Promise<Section[]>;
+   listDocumentsByType(docType: string): Promise<unknown[]>;
+
+   // Cache
+   invalidate(kbid: string): Promise<void>;
+   invalidateAll(): Promise<void>;
+
+   // Version and migration
+   checkVersion(targetPath: string):
+      Promise<VersionStatus>;
+   migrateDatabase(targetPath: string):
+      Promise<MigrateResult>;
+
+   // Directory initialization
+   initDirectory(targetPath: string): Promise<void>;
+}
+```
+
+### Constructor
+
+| Parameter    | Type     | Description                   |
+|--------------|----------|-------------------------------|
+| `socketPath` | `string` | Absolute IPC socket path or   |
+|              |          | Windows named pipe path       |
+| `contextId`  | `string` | 16-character context ID sent  |
+|              |          | as `ctx` in every request     |
+
+### Lifecycle
+
+#### `connect()`
+
+Establishes the IPC connection to the worker daemon.
+Must be called before any other method.
+
+#### `disconnect()`
+
+Destroys the IPC socket and clears the connection
+state. The daemon continues running. After
+disconnecting, all method calls throw until
+`connect()` is called again.
+
+### Status Methods
+
+#### `status()`
+
+Returns the daemon's current initialization state and
+cache statistics.
+
+#### `dbStatus()`
+
+Returns database metadata from the daemon's cached
+state, including document count, section count, index
+size, and cache statistics.
+
+### Search
+
+#### `search(params)`
+
+Executes a ranked search. Returns a `PagedSearchResult`
+containing items sorted by descending relevance score
+along with pagination metadata.
+
+#### `recall(params)`
+
+Progressive context expansion. Returns section
+content, metadata, and optionally parent document
+manifests, sibling sections, and forward/back
+references depending on the `depth` parameter.
+Accepts single `kbid` or batch `kbids`.
+
+```ts
+recall(params: RecallParams):
+   Promise<RecallResult | RecallResult[]>;
+```
+
+### Section Methods
+
+#### `addSection(params)`
+
+Adds a new section. Returns `AddSectionResult` with
+the assigned `kbid`.
+
+#### `updateSection(kbid, params)`
+
+Replaces a section's content and metadata. Returns the
+knowledge-base identifier of the updated section.
+
+#### `removeSection(kbid)`
+
+Removes a section and its index entries.
+
+#### `readSections(kbids)`
+
+Retrieves one or more sections by their identifiers.
+
+### Document Methods
+
+#### `groupSections(title, kbids)`
+
+Groups sections under a named document. Returns the
+assigned document identifier (`docid`).
+
+#### `removeGrouping(docid)`
+
+Removes the document grouping record. The sections
+themselves are not deleted.
+
+#### `retrieveDocument(docid)`
+
+Returns a document record including its sections.
+
+### Typed Listing Methods
+
+#### `listByType(sectionType)`
+
+Returns all sections whose `sectionType` field
+matches the given value. Used to retrieve all
+sections of a particular semantic type (e.g.
+`'skill'`) without a search query.
+
+#### `listDocumentsByType(docType)`
+
+Returns all document manifests whose `type` field
+matches the given value. Used to retrieve all
+documents of a particular kind (e.g. `'agent'`).
+
+### Content Composition
+
+#### `content(ids)`
+
+Composes a rendered Markdown document from one or more
+kbid or docid identifiers. IDs are auto-detected
+(try kbid first, then docid).
+
+### Maintenance Methods
+
+#### `integrityCheck()`
+
+Runs a full integrity check on the database.
+
+#### `gc()`
+
+Runs garbage collection to remove orphaned sections.
+
+#### `rebuildIndexes()`
+
+Rebuilds all indexes from section files and document
+manifests on disk.
+
+### Cache Methods
+
+#### `invalidate(kbid)`
+
+Invalidates the cache entry for a single section.
+
+#### `invalidateAll()`
+
+Clears all entries from the daemon's in-memory cache.
+
+### Version and Migration Methods
+
+#### `checkVersion(targetPath)`
+
+Checks the format version of the `.kbdb` database at
+the given path against the version required by the
+current WASM engine. Read-only -- makes no changes.
+
+#### `migrateDatabase(targetPath)`
+
+Runs all pending database migrations for the `.kbdb`
+directory at the given path.
+
+### Directory Initialization
+
+#### `initDirectory(targetPath)`
+
+Initialises a new `.kbdb` database directory by
+sending an `initDirectory` request to the worker
+daemon.
+
+## Testing
+
+```
+src/shared/worker-client/
+├── worker-client.spec.ts
+└── tests/
+    ├── client-lifecycle.spec.ts
+    └── e2e-worker-client.spec.ts
+```

package/docs/modules/typescript/shared/worker-client/functions.md

@@ -0,0 +1,175 @@
+# worker-client/functions -- Factory and Utilities
+
+*Factory function that returns a connected
+WorkerClient, plus internal utilities for path
+resolution, context ID computation, daemon discovery,
+spawning, and process checking.*
+
+## Source
+
+`src/shared/worker-client/functions/`
+
+## Functions
+
+### `createWorkerClient`
+
+**File:** `create-worker-client.function.ts`
+
+Factory function. Returns a connected `WorkerClient`
+instance ready for use.
+
+```ts
+async function createWorkerClient(
+   options?: WorkerClientOptions,
+): Promise<WorkerClient>;
+```
+
+**Resolution sequence:**
+
+1. Resolve context path -- use `options.contextPath`
+   directly if provided; otherwise call
+   `resolveDbPath(options.dbPath)` which appends
+   `/.kbdb` to `dbPath` (or `cwd()`).
+2. Compute the context ID via `computeContextId()`.
+3. Discover a running daemon via `discoverDaemon()`.
+4. If no daemon is running and `autoSpawn !== false`,
+   spawn one via `spawnDaemon()` then poll with
+   `waitForDaemon()`.
+5. Connect to the IPC socket and return the connected
+   `WorkerClient`.
+
+Throws if the daemon fails to start or the IPC
+connection cannot be established.
+
+### `resolveDbPath`
+
+**File:** `resolve-db-path.function.ts`
+
+Resolves the absolute path to the `.kbdb` database
+directory.
+
+```ts
+function resolveDbPath(
+   targetDir?: string,
+): string;
+```
+
+Resolves `targetDir` (or `process.cwd()`) to an
+absolute path and appends `/.kbdb`. Throws if the
+`.kbdb` directory does not exist at the resolved path.
+
+@throws {Error} if no `.kbdb` directory is found.
+
+### `computeContextId`
+
+**File:** `compute-context-id.function.ts`
+
+Computes the context ID from a database directory's
+absolute path.
+
+```ts
+async function computeContextId(
+   absolutePath: string,
+): Promise<string>;
+```
+
+Produces the SHA-256 hash of the UTF-8 encoded path
+string, then truncates the hex digest to 16 lowercase
+characters.
+
+```
+SHA-256("/home/user/project/.kbdb")
+  → "a3f1...64 hex chars..."
+  → "a3f1b2c4d5e6f789"   (first 16 chars)
+```
+
+### `discoverDaemon`
+
+**File:** `discover-daemon.function.ts`
+
+Looks for a running daemon matching the given context
+ID. Returns synchronously.
+
+```ts
+function discoverDaemon(
+   contextId: string,
+): DaemonInfo | null;
+```
+
+1. Look for `kbdb-{contextId}.pid` in the OS temp
+   directory.
+2. If the PID file exists, read the process ID.
+3. Call `isProcessAlive(pid)` from `shared/platform/`
+   to verify the process is running.
+4. If alive, return `{ pid, socketPath }`.
+5. If the PID file is missing or the process is dead,
+   removes the stale PID file and returns `null`.
+
+### `spawnDaemon`
+
+**File:** `spawn-daemon.function.ts`
+
+Spawns a new worker daemon as a detached child process
+and immediately unrefs the child so it does not keep
+the parent process alive.
+
+```ts
+function spawnDaemon(
+   contextPath: string,
+   runtime: Runtime,
+   workerScript?: string,
+): void;
+```
+
+| Parameter      | Description                          |
+|----------------|--------------------------------------|
+| `contextPath`  | Absolute path to the `.kbdb` dir     |
+| `runtime`      | `'deno'` or `'node'`                 |
+| `workerScript` | Absolute path to the daemon script   |
+
+Throws if `workerScript` is not provided. The worker
+script path must be resolved at the entry point by
+`resolveWorkerScript` from the `dir-resolver` module.
+
+**Deno:** spawns `deno run --allow-all <script> <path>`
+
+**Node.js:** spawns `<execPath> <script> <path>`
+
+After calling `spawnDaemon`, the caller should use
+`waitForDaemon` to poll for the PID file before
+attempting to connect.
+
+### `waitForDaemon`
+
+**File:** `wait-for-daemon.function.ts`
+
+Waits for the worker daemon's PID file to appear on
+disk after spawning.
+
+```ts
+async function waitForDaemon(
+   contextId: string,
+   timeoutMs?: number,
+): Promise<boolean>;
+```
+
+Polls every 100 ms until the PID file at
+`<tmpdir>/kbdb-<contextId>.pid` exists or the timeout
+elapses. Returns `true` when the file appeared before
+the timeout, `false` otherwise.
+
+`timeoutMs` defaults to `10 000` ms.
+
+## Testing
+
+Each function has a `.spec.ts` at the module root:
+
+```
+src/shared/worker-client/
+├── create-worker-client.spec.ts
+├── resolve-db-path.spec.ts
+├── compute-context-id.spec.ts
+├── discover-daemon.spec.ts
+├── spawn-daemon.spec.ts
+└── wait-for-daemon.spec.ts
+```

package/docs/modules/typescript/shared/worker-client/module.md

@@ -0,0 +1,84 @@
+# worker-client -- IPC Client Module
+
+*Sole IPC client for the worker daemon. Resolves the
+database path, computes a context ID, discovers or
+spawns the daemon, connects via IPC socket, and
+provides a typed async API for all operations.*
+
+## Source
+
+`src/shared/worker-client/`
+
+## Responsibility
+
+The worker-client module is the only TypeScript module
+that communicates with the worker daemon. It:
+
+- Resolves the `.kbdb` database directory path.
+- Computes the context ID (SHA-256 of the absolute
+  path, truncated to 16 hex characters).
+- Discovers a running daemon or spawns a new one.
+- Connects to the daemon's Unix socket or Windows
+  named pipe.
+- Exposes every daemon IPC method as a typed async
+  function (JSON-RPC 2.0 over IPC).
+- Handles reconnection when the connection drops.
+
+The module is **not** exported from the library API
+(`mod.ts`). Only `src/cli.ts` imports it.
+
+```
+src/cli.ts ──→ worker-client ──→ src/worker.ts
+```
+
+See [Worker Client](../../../../goals/worker-client.md)
+for the full behavioral specification.
+
+## Directory Layout
+
+```
+src/shared/worker-client/
+├── index.ts
+├── classes/
+│   └── worker-client.class.ts
+├── functions/
+│   ├── compute-context-id.function.ts
+│   ├── create-worker-client.function.ts
+│   ├── discover-daemon.function.ts
+│   ├── resolve-db-path.function.ts
+│   ├── spawn-daemon.function.ts
+│   └── wait-for-daemon.function.ts
+├── typings/
+│   ├── add-section-result.model.ts
+│   ├── content-result.model.ts
+│   ├── daemon-info.model.ts
+│   ├── gc-result.model.ts
+│   ├── integrity-check-result.model.ts
+│   ├── migrate-result.model.ts
+│   ├── rebuild-result.model.ts
+│   ├── remove-section-result.model.ts
+│   ├── search-params.model.ts
+│   ├── search-result.model.ts
+│   ├── section.model.ts
+│   ├── status-result.model.ts
+│   ├── version-status.model.ts
+│   ├── worker-client-error.interface.ts
+│   └── worker-client-options.interface.ts
+└── *.spec.ts
+```
+
+## Exports
+
+- **[classes.md](classes.md)** -- `WorkerClient`.
+- **[functions.md](functions.md)** --
+  `createWorkerClient`, `resolveDbPath`,
+  `computeContextId`, `discoverDaemon`,
+  `spawnDaemon`, `waitForDaemon`.
+- **[typings.md](typings.md)** --
+  `WorkerClientOptions`, `SearchParams`,
+  `SearchResult`, `Section`, `AddSectionParams`,
+  `AddSectionResult`, `RemoveSectionResult`,
+  `ContentResult`, `StatusResult`, `DaemonInfo`,
+  `VersionCompatibility`, `VersionStatus`,
+  `MigrateResult`, `IntegrityCheckResult`,
+  `GcResult`, `RebuildResult`, `WorkerClientError`.