@dikolab/kbdb 0.1.0

package/src/shared/worker-client/functions/wait-for-daemon.function.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/** Default maximum wait time for the daemon PID file to appear. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Polling interval in milliseconds between existence checks. */
+const POLL_INTERVAL_MS = 100;
+
+/**
+ * Waits for the worker daemon's PID file to appear on disk.
+ *
+ * Polls every 100 ms until the PID file at
+ * `<tmpdir>/kbdb-<contextId>.pid` exists or the timeout elapses.
+ *
+ * @param contextId - the 16-character context identifier
+ * @param timeoutMs - maximum wait time in milliseconds; defaults
+ *   to 10 000 ms
+ * @returns `true` if the PID file appeared before the timeout,
+ *   `false` otherwise
+ */
+export async function waitForDaemon(
+   contextId: string,
+   timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<boolean> {
+   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);
+   const start = Date.now();
+   while (Date.now() - start < timeoutMs) {
+      if (existsSync(pidPath)) return true;
+      await new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));
+   }
+   return false;
+}

package/src/shared/worker-client/index.ts

@@ -0,0 +1,31 @@
+export { WorkerClient } from './classes/worker-client.class.ts';
+export { createWorkerClient } from './functions/create-worker-client.function.ts';
+export { resolveDbPath } from './functions/resolve-db-path.function.ts';
+export { computeContextId } from './functions/compute-context-id.function.ts';
+export { discoverDaemon } from './functions/discover-daemon.function.ts';
+export { spawnDaemon } from './functions/spawn-daemon.function.ts';
+export { waitForDaemon } from './functions/wait-for-daemon.function.ts';
+export type { WorkerClientOptions } from './typings/worker-client-options.interface.ts';
+export type { SearchParams } from './typings/search-params.model.ts';
+export type { SearchResult } from './typings/search-result.model.ts';
+export type {
+   Section,
+   AddSectionParams,
+} from './typings/section.model.ts';
+export type { StatusResult } from './typings/status-result.model.ts';
+export type { WorkerClientError } from './typings/worker-client-error.interface.ts';
+export type { DaemonInfo } from './typings/daemon-info.model.ts';
+export type { AddSectionResult } from './typings/add-section-result.model.ts';
+export type { RemoveSectionResult } from './typings/remove-section-result.model.ts';
+export type { ContentResult } from './typings/content-result.model.ts';
+export type {
+   IntegrityCheckResult,
+   IntegrityError,
+} from './typings/integrity-check-result.model.ts';
+export type { GcResult } from './typings/gc-result.model.ts';
+export type { RebuildResult } from './typings/rebuild-result.model.ts';
+export type { MigrateResult } from './typings/migrate-result.model.ts';
+export type {
+   VersionCompatibility,
+   VersionStatus,
+} from './typings/version-status.model.ts';

package/src/shared/worker-client/typings/add-section-result.model.ts

@@ -0,0 +1,22 @@
+/** Result returned by the daemon after adding a new section. */
+export interface AddSectionResult {
+   /** Knowledge-base identifier assigned to the section. */
+   readonly kbid: string;
+   /** MIME type of the stored section. */
+   readonly type: string;
+   /** Section title, if provided. */
+   readonly title?: string;
+   /** Section description, if provided. */
+   readonly description?: string;
+   /** Total token count for the section. */
+   readonly token_count: number;
+   /** Number of unique terms indexed for this section. */
+   readonly indexed_terms_count: number;
+   /** Time taken to process and store the section, in milliseconds. */
+   readonly elapsed_ms: number;
+   /**
+    * `true` when the content already existed and the provided docid
+    * was added to the existing section's `docids` list.
+    */
+   readonly attached: boolean;
+}

package/src/shared/worker-client/typings/content-result.model.ts

@@ -0,0 +1,12 @@
+/**
+ * Result returned by the daemon after composing a Markdown document
+ * from one or more kbid or docid identifiers.
+ */
+export interface ContentResult {
+   /** MIME type of the composed output, always `'text/markdown'`. */
+   readonly type: 'text/markdown';
+   /** The composed Markdown string. */
+   readonly data: string;
+   /** Character count of `data` (not byte count). */
+   readonly total: number;
+}

package/src/shared/worker-client/typings/daemon-info.model.ts

@@ -0,0 +1,7 @@
+/** Location information for a running worker daemon process. */
+export interface DaemonInfo {
+   /** PID of the running daemon process. */
+   readonly pid: number;
+   /** Absolute path to the daemon's IPC socket. */
+   readonly socketPath: string;
+}

package/src/shared/worker-client/typings/gc-result.model.ts

@@ -0,0 +1,12 @@
+/**
+ * Report returned by the daemon after running garbage collection
+ * on the knowledge-base database.
+ */
+export interface GcResult {
+   /** Number of unreferenced sections removed. */
+   readonly removed_sections: number;
+   /** Total bytes freed by removing unreferenced sections. */
+   readonly removed_bytes: number;
+   /** Time taken to complete garbage collection, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/worker-client/typings/integrity-check-result.model.ts

@@ -0,0 +1,43 @@
+/** A single integrity error found during a database check. */
+export interface IntegrityError {
+   /**
+    * The category of integrity violation detected.
+    *
+    * - `'checksum_mismatch'` -- stored content does not match its hash
+    * - `'orphan_section'` -- section not referenced by any document
+    * - `'orphan_document'` -- document references no existing sections
+    * - `'broken_reference'` -- a marker references a non-existent entity
+    * - `'type_mismatch'` -- stored MIME type conflicts with content
+    * - `'circular_reference'` -- marker chain contains a cycle
+    */
+   readonly type:
+      | 'checksum_mismatch'
+      | 'orphan_section'
+      | 'orphan_document'
+      | 'broken_reference'
+      | 'type_mismatch'
+      | 'circular_reference';
+   /** Identifier of the entity (kbid or docid) that has the issue. */
+   readonly entity: string;
+   /** Human-readable description of the specific problem. */
+   readonly detail: string;
+}
+
+/**
+ * Report returned by the daemon after running an integrity check
+ * on the knowledge-base database.
+ */
+export interface IntegrityCheckResult {
+   /** `true` when all checks passed and no errors were found. */
+   readonly ok: boolean;
+   /** All integrity errors found; empty when `ok` is `true`. */
+   readonly errors: IntegrityError[];
+   /** Total number of sections examined. */
+   readonly sections_checked: number;
+   /** Total number of documents examined. */
+   readonly documents_checked: number;
+   /** Total number of marker references checked. */
+   readonly references_checked: number;
+   /** Time taken to complete the check, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/worker-client/typings/migrate-result.model.ts

@@ -0,0 +1,11 @@
+/**
+ * Report returned by the daemon after running database migrations.
+ */
+export interface MigrateResult {
+   /** The database format version before migration. */
+   readonly oldVersion: number;
+   /** The database format version after migration. */
+   readonly newVersion: number;
+   /** Number of individual migration steps that were applied. */
+   readonly migrationsRun: number;
+}

package/src/shared/worker-client/typings/rebuild-result.model.ts

@@ -0,0 +1,12 @@
+/**
+ * Report returned by the daemon after rebuilding all database indexes
+ * from section files and document manifests.
+ */
+export interface RebuildResult {
+   /** Number of text and code sections that were re-indexed. */
+   readonly sections_reindexed: number;
+   /** Total number of unique terms written to the rebuilt indexes. */
+   readonly terms_indexed: number;
+   /** Time taken to complete the rebuild, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/worker-client/typings/remove-section-result.model.ts

@@ -0,0 +1,7 @@
+/** Result returned by the daemon after removing a section. */
+export interface RemoveSectionResult {
+   /** `true` when the section was found and successfully removed. */
+   readonly removed: boolean;
+   /** Time taken to perform the removal, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/worker-client/typings/search-params.model.ts

@@ -0,0 +1,12 @@
+/** Parameters for a search query sent to the worker daemon. */
+export interface SearchParams {
+   /** The search query string. */
+   readonly query: string;
+   /**
+    * Controls what entity type is returned.
+    * Defaults to `'sections'` when omitted.
+    */
+   readonly mode?: 'sections' | 'documents' | 'stats';
+   /** Maximum number of results to return. */
+   readonly limit?: number;
+}

package/src/shared/worker-client/typings/search-result.model.ts

@@ -0,0 +1,14 @@
+/** A single ranked result returned by a search query. */
+export interface SearchResult {
+   /** Knowledge-base identifier for the matched section. */
+   readonly kbid: string;
+   /** Relevance score assigned by the ranking engine. */
+   readonly score: number;
+   /** Terms that matched within this section. */
+   readonly matches: readonly {
+      /** The matched term. */
+      readonly term: string;
+      /** Number of times the term appears in the section. */
+      readonly frequency: number;
+   }[];
+}

package/src/shared/worker-client/typings/section.model.ts

@@ -0,0 +1,27 @@
+/** A content section stored in the knowledge-base. */
+export interface Section {
+   /** Knowledge-base identifier for this section. */
+   readonly kbid: string;
+   /** Parent document identifier, if the section belongs to one. */
+   readonly docid?: string;
+   /** Semantic type label assigned to the section. */
+   readonly sectionType: string;
+   /** Raw text content of the section. */
+   readonly content: string;
+   /** Byte size of the stored content. */
+   readonly size: number;
+   /** Unix epoch timestamp (ms) when the section was created. */
+   readonly createdAt: number;
+   /** SHA-256 checksum of the stored content. */
+   readonly checksum: string;
+}
+
+/** Parameters required to add or update a section. */
+export interface AddSectionParams {
+   /** Semantic type label to assign to the section. */
+   readonly sectionType: string;
+   /** Raw text content for the section. */
+   readonly content: string;
+   /** Parent document identifier to associate the section with. */
+   readonly docid?: string;
+}

package/src/shared/worker-client/typings/status-result.model.ts

@@ -0,0 +1,14 @@
+/** Diagnostic status returned by the worker daemon. */
+export interface StatusResult {
+   /** Whether the daemon has finished loading its WASM modules. */
+   readonly initialized: boolean;
+   /** Absolute path to the context directory the daemon serves. */
+   readonly contextPath: string;
+   /** In-memory cache statistics. */
+   readonly cacheStats: {
+      /** Number of content entries currently cached. */
+      readonly contentCount: number;
+      /** Number of index entries currently cached. */
+      readonly indexCount: number;
+   };
+}

package/src/shared/worker-client/typings/version-status.model.ts

@@ -0,0 +1,28 @@
+/**
+ * Compatibility status categories returned by a database version check.
+ *
+ * - `'compatible'` -- database version matches the WASM engine version
+ * - `'needs_migration'` -- database is older and must be migrated with
+ *   `kbdb --migrate`
+ * - `'too_new'` -- database was created by a newer version of kbdb;
+ *   upgrade the kbdb binary
+ */
+export type VersionCompatibility =
+   | 'compatible'
+   | 'needs_migration'
+   | 'too_new';
+
+/**
+ * Version compatibility status returned by a database version check.
+ */
+export interface VersionStatus {
+   /** The format version stored in the database's `catalog.toml`. */
+   readonly currentVersion: number;
+   /**
+    * The format version required by the current WASM engine.
+    * Equivalent to `DB_FORMAT_VERSION` from the Rust shared crate.
+    */
+   readonly requiredVersion: number;
+   /** Compatibility result between the database and WASM engine. */
+   readonly status: VersionCompatibility;
+}

package/src/shared/worker-client/typings/worker-client-error.interface.ts

@@ -0,0 +1,8 @@
+/**
+ * An error returned by the worker daemon over JSON-RPC,
+ * carrying a numeric error code alongside the message.
+ */
+export interface WorkerClientError extends Error {
+   /** JSON-RPC error code returned by the daemon. */
+   readonly code: number;
+}

package/src/shared/worker-client/typings/worker-client-options.interface.ts

@@ -0,0 +1,30 @@
+/** Options for configuring a WorkerClient connection. */
+export interface WorkerClientOptions {
+   /**
+    * Path to the directory containing the `.kbdb` database
+    * folder. Defaults to `process.cwd()` when omitted.
+    */
+   readonly dbPath?: string;
+   /**
+    * Absolute path to the context directory. When provided,
+    * skips the `.kbdb` discovery step performed by `dbPath`.
+    */
+   readonly contextPath?: string;
+   /**
+    * When `true` (default), automatically spawns the worker
+    * daemon if it is not already running before connecting.
+    * Set to `false` to require a running daemon.
+    */
+   readonly autoSpawn?: boolean;
+   /**
+    * Maximum milliseconds to wait for the daemon PID file to
+    * appear after spawning. Defaults to 10 000 ms.
+    */
+   readonly connectTimeoutMs?: number;
+   /**
+    * Absolute path to the worker daemon script. Resolved
+    * once at the entry point and injected here so that
+    * `spawnDaemon` needs no runtime-specific path logic.
+    */
+   readonly workerScript?: string;
+}