@dikolab/kbdb 0.4.3 → 0.6.0

package/docs/modules/typescript/shared/wasm-codec/module.md

@@ -1,98 +0,0 @@
-# wasm-codec -- WASM Binary Codec Module
-
-*Encodes TypeScript values into the binary wire format
-consumed by `kb-worker.wasm` and decodes binary
-responses back into typed TypeScript values.*
-
-## Source
-
-`src/shared/wasm-codec/`
-
-## Responsibility
-
-The wasm-codec module provides the binary serialization
-layer between the TypeScript host and the Rust WASM
-engine. Each function handles one specific encode or
-decode operation -- there is no general-purpose codec
-framework.
-
-**Encoders** convert TypeScript values into
-`Uint8Array` buffers that can be written into WASM
-linear memory via the host bridge. Conventions:
-
-- Strings are encoded as a little-endian `u32` length
-  prefix followed by UTF-8 bytes.
-- Optional strings use a `0x00` tag byte for `null`
-  or `0x01` followed by the encoded string.
-- Section types use a `0x00` tag for `text`, `0x01`
-  for `code`, or `0x02` for `image`, followed by the
-  MIME type string for non-text types.
-- Lists use a little-endian `u32` count prefix
-  followed by each element in sequence.
-
-**Decoders** parse `Uint8Array` responses from WASM
-exports into typed TypeScript values. Each decoder
-returns the parsed value directly (not a
-`{ value, offset }` pair at the top level, though
-primitive helpers do return `DecodeResult<T>` for
-composability).
-
-The module has no runtime dependencies on the WASM
-binary itself -- it only manipulates `Uint8Array`
-buffers using `DataView` and `TextEncoder`/
-`TextDecoder`.
-
-## Directory Layout
-
-```
-src/shared/wasm-codec/
-├── index.ts
-└── functions/
-    ├── decode-compose-output.function.ts
-    ├── decode-document-manifest.function.ts
-    ├── decode-f32.function.ts
-    ├── decode-key-value-text.function.ts
-    ├── decode-remove-flag.function.ts
-    ├── decode-scored-results.function.ts
-    ├── decode-section-records.function.ts
-    ├── decode-string.function.ts
-    ├── decode-u32.function.ts
-    ├── decode-u64.function.ts
-    ├── encode-add-section-params.function.ts
-    ├── encode-group-params.function.ts
-    ├── encode-identifier-list.function.ts
-    ├── encode-kbid-list.function.ts
-    ├── encode-option-string.function.ts
-    ├── encode-search-params.function.ts
-    ├── encode-section-type.function.ts
-    ├── encode-string.function.ts
-    ├── encode-u32.function.ts
-    └── encode-update-section-params.function.ts
-```
-
-## Exports
-
-- **[functions.md](functions.md)** -- all encode and
-  decode functions plus exported data types
-  (`AddSectionInput`, `ScoredResult`, `TermMatch`,
-  `SectionRecord`, `DocumentManifest`,
-  `DocumentSection`, `ComposeOutput`, `DecodeResult`).
-
-## Usage
-
-The module is used exclusively by
-`WorkerDaemon.handleRequest` and its private dispatch
-helpers. Callers encode parameters before calling a
-WASM export and decode the response bytes after the
-call returns.
-
-```ts
-import {
-   encodeSearchParams,
-   decodeScoredResults,
-} from '../../wasm-codec/index.ts';
-
-const encoded = encodeSearchParams(query, mode, limit);
-// ... write encoded to WASM memory, call export ...
-const results = decodeScoredResults(responseBytes);
-```

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

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

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

@@ -1,92 +0,0 @@
-# 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).
-- 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
-(`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
-│   ├── get-or-create-client.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`, `getOrCreateClient`,
-  `clearClientCache`, `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`.