@dikolab/kbdb 0.1.0

package/src/shared/worker-daemon/functions/start-daemon.function.ts

@@ -0,0 +1,74 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readConfig } from './read-config.function.ts';
+import { computeSha256 } from '../../hash/functions/compute-sha256.ts';
+import { WorkerDaemon } from '../classes/worker-daemon.class.ts';
+
+/**
+ * Starts the worker daemon for the given knowledge-base context.
+ *
+ * Reads configuration from `worker.toml` in the context directory,
+ * validates startup preconditions (directory exists, accessible, and
+ * database version compatible), and then starts the `WorkerDaemon`.
+ *
+ * Signal handlers for `SIGTERM` and `SIGINT` trigger a graceful stop.
+ * Precondition failures are printed to stderr and cause exit code 1.
+ *
+ * @param contextPath - absolute path to the `.kbdb` context directory
+ */
+export async function startDaemon(
+   contextPath: string,
+   wasmDir?: string,
+): Promise<void> {
+   const config = readConfig(contextPath);
+   const hash = await computeSha256(contextPath);
+   const contextId = hash.slice(0, 16);
+
+   const daemon = new WorkerDaemon(
+      contextId,
+      contextPath,
+      config,
+      wasmDir,
+   );
+
+   try {
+      daemon.checkPreconditions();
+   } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // eslint-disable-next-line no-console
+      console.error(`kbdb-worker: ${message}`);
+      writeCrashLog(contextId, message);
+      process.exit(1);
+   }
+
+   try {
+      await daemon.start();
+   } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // eslint-disable-next-line no-console
+      console.error(`kbdb-worker: ${message}`);
+      writeCrashLog(contextId, message);
+      process.exit(1);
+   }
+
+   process.on('SIGTERM', () => {
+      daemon.stop();
+   });
+   process.on('SIGINT', () => {
+      daemon.stop();
+   });
+}
+
+function writeCrashLog(contextId: string, message: string): void {
+   try {
+      const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);
+      const payload = JSON.stringify({
+         error: message,
+         timestamp: Date.now(),
+      });
+      writeFileSync(crashPath, payload);
+   } catch {
+      // never mask the original error
+   }
+}

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

@@ -0,0 +1,16 @@
+export { readConfig } from './functions/read-config.function.ts';
+export { startDaemon } from './functions/start-daemon.function.ts';
+export { createIpcServer } from './functions/create-ipc-server.function.ts';
+export { loadWasmModules } from './functions/load-wasm-modules.function.ts';
+export type { DaemonConfig } from './typings/daemon-config.interface.ts';
+export type { WasmModules } from './typings/wasm-modules.interface.ts';
+export type {
+   IpcRequest,
+   IpcResponse,
+   IpcHandler,
+} from './typings/ipc-handler.interface.ts';
+export { runWorker } from './functions/run-worker.function.ts';
+export type {
+   WorkerResult,
+   WorkerDeps,
+} from './functions/run-worker.function.ts';

package/src/shared/worker-daemon/typings/daemon-config.interface.ts

@@ -0,0 +1,13 @@
+/** Configuration for the worker daemon process. */
+export interface DaemonConfig {
+   /** Absolute path to the knowledge-base context directory. */
+   readonly contextPath: string;
+   /** Maximum number of items held in memory at once. */
+   readonly itemLimit: number;
+   /** Maximum number of index entries held in memory at once. */
+   readonly indexLimit: number;
+   /** Idle timeout in milliseconds before the daemon shuts down. */
+   readonly timeoutMs: number;
+   /** Time-to-live in milliseconds for each cached item. */
+   readonly itemTtlMs: number;
+}

package/src/shared/worker-daemon/typings/ipc-handler.interface.ts

@@ -0,0 +1,39 @@
+/** A JSON-RPC 2.0 request sent to the daemon over IPC. */
+export interface IpcRequest {
+   /** JSON-RPC version string -- always `'2.0'`. */
+   readonly jsonrpc: '2.0';
+   /** Request identifier, echoed back in the response. */
+   readonly id: number | string;
+   /** Method name to invoke on the daemon. */
+   readonly method: string;
+   /** Optional method parameters. */
+   readonly params?: unknown;
+}
+
+/** Error detail included in a failed JSON-RPC response. */
+export interface IpcErrorDetail {
+   /** JSON-RPC error code. */
+   readonly code: number;
+   /** Human-readable error message. */
+   readonly message: string;
+   /** Optional additional error data. */
+   readonly data?: unknown;
+}
+
+/** A JSON-RPC 2.0 response returned by the daemon over IPC. */
+export interface IpcResponse {
+   /** JSON-RPC version string -- always `'2.0'`. */
+   readonly jsonrpc: '2.0';
+   /** Identifier matching the originating request. */
+   readonly id: number | string;
+   /** Successful result payload. Present on success. */
+   readonly result?: unknown;
+   /** Error detail. Present on failure. */
+   readonly error?: IpcErrorDetail;
+}
+
+/**
+ * Function that handles a single IPC request and returns a
+ * JSON-RPC response.
+ */
+export type IpcHandler = (request: IpcRequest) => Promise<IpcResponse>;

package/src/shared/worker-daemon/typings/wasm-modules.interface.ts

@@ -0,0 +1,7 @@
+/** Loaded and instantiated WASM module instances. */
+export interface WasmModules {
+   /** Linear memory exported by the kb-worker WASM module. */
+   readonly memory: WebAssembly.Memory;
+   /** Instantiated kb-worker WASM module. */
+   readonly kbWorker: WebAssembly.Instance;
+}

package/src/worker.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { getArgs } from './shared/runtime/index.ts';
+import {
+   resolveBaseDir,
+   resolveWasmDir,
+} from './shared/dir-resolver/index.ts';
+import {
+   startDaemon,
+   runWorker,
+} from './shared/worker-daemon/index.ts';
+
+const baseDir = resolveBaseDir(import.meta.url, import.meta.dirname);
+const wasmDir = resolveWasmDir(baseDir.scriptDir);
+
+async function main(): Promise<void> {
+   const result = await runWorker(getArgs(), {
+      existsSync,
+      startDaemon,
+      wasmDir,
+   });
+   if (result.error) {
+      // eslint-disable-next-line no-console
+      console.error(result.error);
+   }
+   if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode;
+   }
+}
+
+main().catch((err: unknown) => {
+   // eslint-disable-next-line no-console
+   console.error(err);
+   process.exitCode = 1;
+});