@dikolab/kbdb 0.4.3 → 0.6.0

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

@@ -1,511 +0,0 @@
-# worker-client/typings -- IPC Type Definitions
-
-*Interfaces, type aliases, and error types for
-worker-client IPC communication.*
-
-## Source
-
-`src/shared/worker-client/typings/`
-
-## Typings
-
-### `WorkerClientOptions`
-
-**File:** `worker-client-options.interface.ts`
-
-Options for configuring a `WorkerClient` connection.
-
-```ts
-interface WorkerClientOptions {
-   readonly dbPath?: string;
-   readonly contextPath?: string;
-   readonly autoSpawn?: boolean;
-   readonly connectTimeoutMs?: number;
-   readonly workerScript?: string;
-   readonly requestTimeoutMs?: number;
-}
-```
-
-| Property           | Description                       |
-|--------------------|-----------------------------------|
-| `dbPath`           | Path to the directory containing  |
-|                    | the `.kbdb` folder; falls back to |
-|                    | `process.cwd()` when omitted      |
-| `contextPath`      | Absolute path to the context dir; |
-|                    | skips `.kbdb` discovery when set  |
-| `autoSpawn`        | Auto-spawns the daemon if needed; |
-|                    | defaults to `true`                |
-| `connectTimeoutMs` | Max ms to wait for the PID file   |
-|                    | after spawning; defaults to 10000 |
-| `workerScript`     | Absolute path to the worker       |
-|                    | daemon script                     |
-| `requestTimeoutMs` | Per-request timeout; default      |
-|                    | 30 000 ms                         |
-
-### `SearchParams`
-
-**File:** `search-params.model.ts`
-
-Parameters for `WorkerClient.search()`.
-
-```ts
-interface SearchParams {
-   readonly query: string;
-   readonly mode?: 'sections' | 'documents' | 'stats';
-   readonly limit?: number;
-   readonly content?: boolean;
-   readonly offset?: number;
-}
-```
-
-| Property  | Description                     |
-|-----------|---------------------------------|
-| `query`   | Search query string             |
-| `mode`    | Result shape selector           |
-| `limit`   | Max results (optional)          |
-| `content` | Include full section content in |
-|           | each result when `true`         |
-| `offset`  | Zero-based result offset for    |
-|           | pagination                      |
-
-### `SearchResult`
-
-**File:** `search-result.model.ts`
-
-A single ranked result returned by a search query.
-
-```ts
-interface SearchResult {
-   readonly kbid: string;
-   readonly heading: string | null;
-   readonly type: string;
-   readonly docids: readonly string[];
-   readonly score: number;
-   readonly snippet: string;
-   readonly matched_terms: readonly string[];
-   readonly content?: string;
-}
-```
-
-| Property        | Description                         |
-|-----------------|-------------------------------------|
-| `kbid`          | Knowledge-base identifier for the   |
-|                 | matched section                     |
-| `heading`       | Section heading, or `null` when not |
-|                 | present                             |
-| `type`          | Semantic section type label         |
-| `docids`        | Parent document IDs for the section |
-| `score`         | Relevance score from ranking engine |
-| `snippet`       | Short excerpt highlighting matched  |
-|                 | terms                               |
-| `matched_terms` | Terms from the query that matched   |
-|                 | this section                        |
-| `content`       | Full section content; present only  |
-|                 | when `SearchParams.content` is true |
-
-### `PagedSearchResult`
-
-**File:** `paged-search-result.model.ts`
-
-Paginated container returned by `WorkerClient.search()`.
-
-```ts
-interface PagedSearchResult {
-   readonly items: readonly SearchResult[];
-   readonly total: number;
-   readonly offset: number;
-   readonly limit: number;
-   readonly has_more: boolean;
-}
-```
-
-| Property   | Description                          |
-|------------|--------------------------------------|
-| `items`    | Ranked search results for this page  |
-| `total`    | Total matching sections across all   |
-|            | pages                                |
-| `offset`   | Zero-based offset of this page       |
-| `limit`    | Page size used for this query        |
-| `has_more` | `true` when results beyond this page |
-|            | exist
-
-### `RecallParams`
-
-**File:** `recall-params.model.ts`
-
-Parameters for `WorkerClient.recall()`.
-
-```ts
-interface RecallParams {
-   readonly kbid?: string;
-   readonly kbids?: readonly string[];
-   readonly depth?: number;
-}
-```
-
-| Property | Description                          |
-|----------|--------------------------------------|
-| `kbid`   | Single section identifier to recall  |
-| `kbids`  | Batch of section identifiers; cannot |
-|          | be used together with `kbid`         |
-| `depth`  | Expansion depth: `0` = content only, |
-|          | `1` = include siblings, `2` = add    |
-|          | references, `3` = add parent         |
-|          | document manifests; clamped to 0--3  |
-
-### `RecallResult`
-
-**File:** `recall-result.model.ts`
-
-A single section result from a recall operation,
-optionally enriched with contextual data.
-
-```ts
-interface RecallResult {
-   readonly kbid: string;
-   readonly heading: string | null;
-   readonly type: string;
-   readonly content: string;
-   readonly docids: readonly string[];
-   readonly documents?: readonly RecallDocument[];
-   readonly back_references?: readonly RecallReference[];
-   readonly siblings?: readonly RecallSibling[];
-   readonly references?: readonly RecallReference[];
-}
-```
-
-| Property          | Description                         |
-|-------------------|-------------------------------------|
-| `kbid`            | Knowledge-base identifier           |
-| `heading`         | Section heading, or `null`          |
-| `type`            | Semantic section type label         |
-| `content`         | Full text content of the section    |
-| `docids`          | Parent document IDs                 |
-| `documents`       | Parent document manifests; present  |
-|                   | at `depth >= 3`                     |
-| `back_references` | Sections that reference this one;   |
-|                   | present at `depth >= 2`             |
-| `siblings`        | Adjacent sections in the same       |
-|                   | document; present at `depth >= 1`   |
-| `references`      | Forward references from this        |
-|                   | section; present at `depth >= 2`    |
-
-### `RecallDocument`
-
-**File:** `recall-result.model.ts`
-
-Parent document manifest included in a `RecallResult`
-at `depth >= 3`.
-
-```ts
-interface RecallDocument {
-   readonly docid: string;
-   readonly title: string;
-   readonly sections: readonly {
-      readonly kbid: string;
-      readonly heading: string | null;
-      readonly type: string;
-   }[];
-}
-```
-
-| Property   | Description                            |
-|------------|----------------------------------------|
-| `docid`    | Document identifier                    |
-| `title`    | Document title                         |
-| `sections` | Ordered list of section stubs in the   |
-|            | document                               |
-
-### `RecallSibling`
-
-**File:** `recall-result.model.ts`
-
-An adjacent section in the same document, returned
-at `depth >= 1`.
-
-```ts
-interface RecallSibling {
-   readonly kbid: string;
-   readonly heading: string | null;
-   readonly type: string;
-   readonly content: string;
-}
-```
-
-| Property  | Description                       |
-|-----------|-----------------------------------|
-| `kbid`    | Knowledge-base identifier         |
-| `heading` | Section heading, or `null`        |
-| `type`    | Semantic section type label       |
-| `content` | Full text content of the sibling  |
-
-### `RecallReference`
-
-**File:** `recall-result.model.ts`
-
-A forward or back reference between sections,
-returned at `depth >= 2`.
-
-```ts
-interface RecallReference {
-   readonly kbid: string;
-   readonly heading: string | null;
-   readonly type: string;
-   readonly marker_type: string;
-   readonly context_snippet: string;
-   readonly direction: 'forward' | 'back';
-}
-```
-
-| Property          | Description                       |
-|-------------------|-----------------------------------|
-| `kbid`            | Knowledge-base identifier of the  |
-|                   | referenced section                |
-| `heading`         | Section heading, or `null`        |
-| `type`            | Semantic section type label       |
-| `marker_type`     | Type of the link marker           |
-| `context_snippet` | Short excerpt around the marker   |
-| `direction`       | `'forward'` when this section     |
-|                   | references the target; `'back'`   |
-|                   | when the target references this   |
-|                   | section                           |
-
-### `Section`
-
-**File:** `section.model.ts`
-
-A content section stored in the knowledge base.
-
-```ts
-interface Section {
-   readonly kbid: string;
-   readonly docid?: string;
-   readonly sectionType: string;
-   readonly content: string;
-   readonly size: number;
-   readonly createdAt: number;
-   readonly checksum: string;
-}
-```
-
-| Property      | Description                       |
-|---------------|-----------------------------------|
-| `kbid`        | Knowledge-base identifier         |
-| `docid`       | Parent document ID (optional)     |
-| `sectionType` | Semantic type label               |
-| `content`     | Raw text content                  |
-| `size`        | Byte size of stored content       |
-| `createdAt`   | Unix epoch timestamp (ms)         |
-| `checksum`    | SHA-256 checksum of content       |
-
-### `AddSectionParams`
-
-**File:** `section.model.ts`
-
-Parameters required to add or update a section.
-
-```ts
-interface AddSectionParams {
-   readonly sectionType: string;
-   readonly content: string;
-   readonly docid?: string;
-}
-```
-
-### `AddSectionResult`
-
-**File:** `add-section-result.model.ts`
-
-Result returned by the daemon after adding a new
-section.
-
-```ts
-interface AddSectionResult {
-   readonly kbid: string;
-   readonly type: string;
-   readonly title?: string;
-   readonly description?: string;
-   readonly token_count: number;
-   readonly indexed_terms_count: number;
-   readonly elapsed_ms: number;
-   readonly attached: boolean;
-}
-```
-
-`attached` is `true` when content already existed and
-the provided `docid` was added to the existing
-section's `docids` list.
-
-### `RemoveSectionResult`
-
-**File:** `remove-section-result.model.ts`
-
-```ts
-interface RemoveSectionResult {
-   readonly removed: boolean;
-   readonly elapsed_ms: number;
-}
-```
-
-### `ContentResult`
-
-**File:** `content-result.model.ts`
-
-Result of a content composition operation.
-
-```ts
-interface ContentResult {
-   readonly type: 'text/markdown';
-   readonly data: string;
-   readonly total: number;
-}
-```
-
-| Property | Description                     |
-|----------|---------------------------------|
-| `type`   | Always `'text/markdown'`        |
-| `data`   | Composed Markdown string        |
-| `total`  | Character count of `data`       |
-
-### `StatusResult`
-
-**File:** `status-result.model.ts`
-
-Diagnostic status returned by the worker daemon.
-
-```ts
-interface StatusResult {
-   readonly initialized: boolean;
-   readonly contextPath: string;
-   readonly cacheStats: {
-      readonly contentCount: number;
-      readonly indexCount: number;
-   };
-}
-```
-
-### `DaemonInfo`
-
-**File:** `daemon-info.model.ts`
-
-Location information for a running worker daemon
-process.
-
-```ts
-interface DaemonInfo {
-   readonly pid: number;
-   readonly socketPath: string;
-}
-```
-
-### `VersionCompatibility`
-
-**File:** `version-status.model.ts`
-
-Compatibility status categories returned by a database
-version check.
-
-```ts
-type VersionCompatibility =
-   | 'compatible'
-   | 'needs_migration'
-   | 'too_new';
-```
-
-### `VersionStatus`
-
-**File:** `version-status.model.ts`
-
-Version compatibility status returned by
-`WorkerClient.checkVersion()`.
-
-```ts
-interface VersionStatus {
-   readonly currentVersion: number;
-   readonly requiredVersion: number;
-   readonly status: VersionCompatibility;
-}
-```
-
-### `MigrateResult`
-
-**File:** `migrate-result.model.ts`
-
-Report returned by the daemon after running database
-migrations.
-
-```ts
-interface MigrateResult {
-   readonly oldVersion: number;
-   readonly newVersion: number;
-   readonly migrationsRun: number;
-}
-```
-
-### `IntegrityCheckResult`
-
-**File:** `integrity-check-result.model.ts`
-
-Result of `WorkerClient.integrityCheck()`.
-
-```ts
-interface IntegrityCheckResult {
-   readonly ok: boolean;
-   readonly errors: IntegrityError[];
-   readonly sections_checked: number;
-   readonly documents_checked: number;
-   readonly references_checked: number;
-   readonly elapsed_ms: number;
-}
-```
-
-`IntegrityError.type` values: `checksum_mismatch`,
-`orphan_section`, `orphan_document`,
-`broken_reference`, `type_mismatch`,
-`circular_reference`.
-
-### `GcResult`
-
-**File:** `gc-result.model.ts`
-
-Result of `WorkerClient.gc()`.
-
-```ts
-interface GcResult {
-   readonly removed_sections: number;
-   readonly removed_bytes: number;
-   readonly elapsed_ms: number;
-}
-```
-
-### `RebuildResult`
-
-**File:** `rebuild-result.model.ts`
-
-Result of `WorkerClient.rebuildIndexes()`.
-
-```ts
-interface RebuildResult {
-   readonly sections_reindexed: number;
-   readonly terms_indexed: number;
-   readonly elapsed_ms: number;
-}
-```
-
-### `WorkerClientError`
-
-**File:** `worker-client-error.interface.ts`
-
-An error returned by the worker daemon over JSON-RPC,
-carrying a numeric error code alongside the message.
-
-```ts
-interface WorkerClientError extends Error {
-   readonly code: number;
-}
-```
-
-The `code` property matches JSON-RPC 2.0 error codes
-defined in the worker daemon spec.
-
-No spec -- typings are compile-time only.