@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/worker-daemon/functions/create-host-imports.function.ts

@@ -136,8 +136,9 @@ export function createHostImports(
 
    function readPathArg(ptr: number, len: number): string {
       const bytes = new Uint8Array(getBuffer(), ptr, len);
-      const relative = new TextDecoder().decode(bytes);
-      return join(contextPath, relative);
+      const decoded = new TextDecoder().decode(bytes);
+      if (decoded.startsWith('/')) return decoded;
+      return join(contextPath, decoded);
    }
 
    return {
@@ -163,14 +164,21 @@ export function createHostImports(
             const filePath = readPathArg(pathPtr, pathLen);
             const data = fs.readFileSync(filePath);
             const dataLen = data.byteLength;
-            const dv = new DataView(getBuffer());
             if (dataLen === 0) {
+               // No allocation -- buffer cannot have grown; safe to
+               // create DataView now.
+               const dv = new DataView(getBuffer());
                dv.setUint32(outPtr, 0, true);
                dv.setUint32(outLen, 0, true);
                return 0;
             }
             const dataPtr = allocator.alloc(dataLen);
             if (dataPtr === 0) return -1;
+            // Create DataView AFTER alloc() -- alloc may trigger WASM
+            // memory growth, which detaches the old ArrayBuffer and
+            // replaces it with a new one. A DataView captured before
+            // growth would reference the detached buffer and throw.
+            const dv = new DataView(getBuffer());
             const memView = new Uint8Array(getBuffer());
             memView.set(
                new Uint8Array(
@@ -267,14 +275,21 @@ export function createHostImports(
             const entries = fs.readdirSync(dirPath);
             const text = entries.join('\n');
             const encoded = new TextEncoder().encode(text);
-            const dv = new DataView(getBuffer());
             if (encoded.length === 0) {
+               // No allocation -- buffer cannot have grown; safe to
+               // create DataView now.
+               const dv = new DataView(getBuffer());
                dv.setUint32(outPtr, 0, true);
                dv.setUint32(outLen, 0, true);
                return 0;
             }
             const dataPtr = allocator.alloc(encoded.length);
             if (dataPtr === 0) return -1;
+            // Create DataView AFTER alloc() -- alloc may trigger WASM
+            // memory growth, which detaches the old ArrayBuffer and
+            // replaces it with a new one. A DataView captured before
+            // growth would reference the detached buffer and throw.
+            const dv = new DataView(getBuffer());
             new Uint8Array(getBuffer(), dataPtr, encoded.length).set(
                encoded,
             );

package/src/shared/worker-daemon/functions/create-ipc-server.function.ts

@@ -28,6 +28,8 @@ export function createIpcServer(
    const server = createServer((socket) => {
       let buffer = '';
 
+      let processingQueue = Promise.resolve();
+
       socket.on('data', (chunk: Buffer) => {
          buffer += chunk.toString();
          const lines = buffer.split('\n');
@@ -35,7 +37,9 @@ export function createIpcServer(
 
          for (const line of lines) {
             if (!line.trim()) continue;
-            void handleLine(line, handler, socket);
+            processingQueue = processingQueue.then(() =>
+               handleLine(line, handler, socket),
+            );
          }
       });
 

package/src/shared/worker-daemon/functions/detect-stale-pid.function.ts

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { isProcessAlive } from '../../platform/functions/is-process-alive.function.ts';
+
+/**
+ * Checks whether a PID file contains a stale process ID.
+ *
+ * Reads the PID from the file and checks whether the process is
+ * still running using `process.kill(pid, 0)`. If the process is
+ * dead, or the PID is unparseable, removes the PID file and
+ * returns `true`. Returns `false` when the process is alive or
+ * the file does not exist.
+ *
+ * @param pidPath - absolute path to the PID file to inspect
+ * @returns `true` if the PID file is stale (process dead or
+ *   content invalid) and was removed; `false` if the process is
+ *   alive or the file does not exist
+ */
+export function detectStalePid(pidPath: string): boolean {
+   if (!existsSync(pidPath)) return false;
+
+   const pidStr = readFileSync(pidPath, 'utf-8').trim();
+   const pid = parseInt(pidStr, 10);
+   const isAlive = !isNaN(pid) && pid > 0 && isProcessAlive(pid);
+
+   if (isAlive) return false;
+
+   try {
+      unlinkSync(pidPath);
+   } catch {
+      // Best-effort removal; stale file is treated as detected
+   }
+   return true;
+}

package/src/shared/worker-daemon/functions/dispatch-request.function.ts

@@ -0,0 +1,190 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import type { HandlerContext } from '../typings/handler-context.interface.ts';
+import { IpcError } from '../classes/ipc-error.class.ts';
+import {
+   WASM_METHOD_MAP,
+   CONFIG_PREFIX,
+} from '../constants/wasm-method-map.constant.ts';
+import {
+   handleSearch,
+   handleResultStatus,
+   handleGetResult,
+   handleReadSections,
+   handleRetrieveDoc,
+   handleCompose,
+   handleIntegrityCheck,
+   handleDbStatus,
+   handleListByType,
+   handleListDocsByType,
+   handleRecall,
+   handleExport,
+} from './handle-read-ops.function.ts';
+import {
+   handleAddSection,
+   handleUpdateSection,
+   handleRemoveSection,
+   handleGroupSections,
+   handleRemoveGrouping,
+   handleInitDirectory,
+   handleInvalidate,
+   handleInvalidateAll,
+   handleGc,
+   handleRebuild,
+} from './handle-write-ops.function.ts';
+import { handleCheckVersion } from './handle-check-version.function.ts';
+import { handleConfigMethod } from './handle-config-method.function.ts';
+import {
+   acquireWriteLock,
+   releaseWriteLock,
+} from './write-lock.function.ts';
+import type { WriteLockState } from '../typings/write-lock.interface.ts';
+import { callWasmSync } from './wasm-bridge.function.ts';
+
+/** Daemon status information returned by `status` and `idle_at`. */
+interface DaemonStatus {
+   /** Whether the daemon is currently serving connections. */
+   readonly status: 'busy' | 'idle';
+   /** Whether the startup integrity check passed. */
+   readonly integrityOk: boolean;
+   /** Integrity errors found at startup, if any. */
+   readonly integrityErrors: string[];
+   /** Unix timestamp (seconds) of the last completed request. */
+   readonly idleAt: number;
+}
+
+/**
+ * Dispatches an IPC method to its handler.
+ *
+ * Routes daemon-state methods inline and delegates WASM read/write
+ * operations to their respective handler functions. Write operations
+ * are serialised through the single-writer lock.
+ *
+ * @param method - IPC method name
+ * @param params - request parameters
+ * @param ctx - handler context (WASM modules, config, targetDir)
+ * @param daemonStatus - live daemon state read by the `status` method
+ * @param writeLock - shared write-lock state
+ */
+export async function dispatchRequest(
+   method: string,
+   params: Record<string, unknown>,
+   ctx: HandlerContext,
+   daemonStatus: DaemonStatus,
+   writeLock: WriteLockState,
+): Promise<unknown> {
+   if (method === 'status') {
+      return {
+         status: daemonStatus.status,
+         integrityOk: daemonStatus.integrityOk,
+         integrityErrors: daemonStatus.integrityErrors,
+      };
+   }
+   if (method === 'idle_at') return daemonStatus.idleAt;
+   if (method === 'checkVersion') {
+      return handleCheckVersion(params, ctx.targetDir);
+   }
+   if (method.startsWith(CONFIG_PREFIX)) {
+      return handleConfigMethod(method, ctx.config);
+   }
+
+   const wasmMethod = WASM_METHOD_MAP[method];
+   if (wasmMethod === undefined) {
+      throw new IpcError(-32601, `Method not found: ${method}`);
+   }
+   return dispatchWasm(method, wasmMethod, params, ctx, writeLock);
+}
+
+async function dispatchWasm(
+   method: string,
+   wasmExport: string,
+   params: Record<string, unknown>,
+   ctx: HandlerContext,
+   writeLock: WriteLockState,
+): Promise<unknown> {
+   // Read-only operations -- no write lock required.
+   if (method === 'search' || method === 'query') {
+      return handleSearch(ctx, params);
+   }
+   if (method === 'readSections' || method === 'read_sections') {
+      return handleReadSections(ctx, params);
+   }
+   if (method === 'retrieveDocument' || method === 'retrieve_doc') {
+      return handleRetrieveDoc(ctx, params);
+   }
+   if (method === 'content' || method === 'compose') {
+      return handleCompose(ctx, params);
+   }
+   if (method === 'integrityCheck' || method === 'integrity_check') {
+      return handleIntegrityCheck(ctx);
+   }
+   if (method === 'dbStatus' || method === 'db_status') {
+      return handleDbStatus(ctx);
+   }
+   if (method === 'get_result_status') {
+      return handleResultStatus(ctx, params);
+   }
+   if (method === 'get_result') {
+      return handleGetResult(ctx, params);
+   }
+   if (method === 'listByType' || method === 'list_by_type') {
+      return handleListByType(ctx, params);
+   }
+   if (
+      method === 'listDocumentsByType' ||
+      method === 'list_docs_by_type'
+   ) {
+      return handleListDocsByType(ctx, params);
+   }
+   if (method === 'recall') return handleRecall(ctx, params);
+   if (method === 'export' || method === 'exportDb') {
+      return handleExport(ctx, params);
+   }
+
+   // Write operations -- serialised through the single-writer lock.
+   await acquireWriteLock(writeLock);
+   try {
+      if (method === 'invalidate') return handleInvalidate(ctx, params);
+      if (method === 'invalidateAll' || method === 'invalidate_all') {
+         return handleInvalidateAll(ctx);
+      }
+      if (method === 'addSection' || method === 'add_section') {
+         return handleAddSection(ctx, params);
+      }
+      if (method === 'updateSection' || method === 'update_section') {
+         return handleUpdateSection(ctx, params);
+      }
+      if (method === 'removeSection' || method === 'remove_section') {
+         return handleRemoveSection(ctx, params);
+      }
+      if (method === 'groupSections' || method === 'group_sections') {
+         return handleGroupSections(ctx, params);
+      }
+      if (method === 'removeGrouping' || method === 'remove_grouping') {
+         return handleRemoveGrouping(ctx, params);
+      }
+      if (method === 'gc') return handleGc(ctx);
+      if (method === 'rebuildIndexes' || method === 'rebuild_indexes') {
+         return handleRebuild(ctx);
+      }
+      if (method === 'initDirectory' || method === 'init_directory') {
+         return handleInitDirectory(ctx, params);
+      }
+      if (method === 'migrateDatabase') {
+         throw new IpcError(
+            -32601,
+            'migrateDatabase is not yet supported',
+         );
+      }
+      return callWasmSync(ctx.modules, wasmExport, new Uint8Array(0));
+   } finally {
+      releaseWriteLock(writeLock);
+   }
+}
+
+/**
+ * Re-export `DaemonConfig` so callers can pass strongly-typed
+ * config without an extra import.
+ *
+ * @internal
+ */
+export type { DaemonConfig };

package/src/shared/worker-daemon/functions/handle-check-version.function.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DB_FORMAT_VERSION } from '../constants/daemon-defaults.constant.ts';
+import { parseCatalogVersion } from './parse-catalog-version.function.ts';
+
+/** Payload returned by the `checkVersion` IPC method. */
+interface VersionCheckResult {
+   /** Compatibility status string. */
+   readonly status: string;
+   /** Format version stored in the catalog. */
+   readonly currentVersion: number;
+   /** Format version required by the current engine. */
+   readonly requiredVersion: number;
+}
+
+/**
+ * Handles the `checkVersion` IPC method.
+ *
+ * Reads `catalog.toml` at `targetPath` and compares its format
+ * version to `DB_FORMAT_VERSION`. Returns a result object without
+ * making any modifications.
+ *
+ * @param targetPath - absolute path to the `.kbdb` directory to
+ *   inspect; falls back to `defaultDir` when not provided in params
+ * @param defaultDir - fallback directory when `params.targetPath`
+ *   is absent
+ */
+export function handleCheckVersion(
+   params: Record<string, unknown>,
+   defaultDir: string,
+): VersionCheckResult {
+   const targetPath =
+      typeof params['targetPath'] === 'string'
+         ? params['targetPath']
+         : defaultDir;
+   const catalogPath = join(targetPath, 'catalog.toml');
+   let text: string;
+   try {
+      text = readFileSync(catalogPath, 'utf-8');
+   } catch {
+      return {
+         status: 'needs_migration',
+         currentVersion: 0,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   const version = parseCatalogVersion(text);
+   if (version === null) {
+      return {
+         status: 'needs_migration',
+         currentVersion: 0,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   if (version > DB_FORMAT_VERSION) {
+      return {
+         status: 'too_new',
+         currentVersion: version,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   if (version < DB_FORMAT_VERSION) {
+      return {
+         status: 'needs_migration',
+         currentVersion: version,
+         requiredVersion: DB_FORMAT_VERSION,
+      };
+   }
+   return {
+      status: 'compatible',
+      currentVersion: version,
+      requiredVersion: DB_FORMAT_VERSION,
+   };
+}

package/src/shared/worker-daemon/functions/handle-config-method.function.ts

@@ -0,0 +1,27 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import { IpcError } from '../classes/ipc-error.class.ts';
+import {
+   CONFIG_PREFIX,
+   CONFIG_KEY_MAP,
+} from '../constants/wasm-method-map.constant.ts';
+
+/**
+ * Handles `config_{key}` IPC methods by returning the corresponding
+ * `DaemonConfig` field value.
+ *
+ * @param method - the full method name, e.g. `config_timeout_ms`
+ * @param config - parsed daemon configuration
+ * @throws {IpcError} with code `-32601` when the key suffix is not
+ *   in `CONFIG_KEY_MAP`
+ */
+export function handleConfigMethod(
+   method: string,
+   config: DaemonConfig,
+): unknown {
+   const key = method.slice(CONFIG_PREFIX.length);
+   const prop = CONFIG_KEY_MAP[key];
+   if (prop === undefined) {
+      throw new IpcError(-32601, `Method not found: ${method}`);
+   }
+   return config[prop];
+}

package/src/shared/worker-daemon/functions/handle-read-ops.function.ts

@@ -0,0 +1,236 @@
+import {
+   encodeSearchParams,
+   encodeKbidList,
+   encodeIdentifierList,
+   encodeTypeFilterParam,
+   encodeRecallParams,
+   decodePagedSearchResult,
+   decodeSectionRecords,
+   decodeSectionRecordList,
+   decodeDocumentManifest,
+   decodeDocumentManifestList,
+   decodeComposeOutput,
+   decodeKeyValueText,
+   decodeRecallResult,
+} from '../../wasm-codec/index.ts';
+import type { HandlerContext } from '../typings/handler-context.interface.ts';
+import { IpcError } from '../classes/ipc-error.class.ts';
+import {
+   getWasmExport,
+   wasmAlloc,
+   wasmWrite,
+   wasmFree,
+   readReturnSlot,
+   callWasmSync,
+   callWasmZeroArg,
+} from './wasm-bridge.function.ts';
+
+/**
+ * Handles `search` and `query` IPC methods.
+ *
+ * Encodes parameters, invokes the `worker_search` token pipeline,
+ * waits synchronously for the result, and decodes the paged result.
+ */
+export function handleSearch(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const query = (params['query'] as string | undefined) ?? '';
+   const mode = (params['mode'] as string | undefined) ?? 'and';
+   const limit = Number(params['limit'] ?? 20);
+   const offset = Number(params['offset'] ?? 0);
+   const encoded = encodeSearchParams(query, mode, limit, offset);
+
+   const searchFn = getWasmExport(ctx.modules, 'worker_search');
+   const ptr = wasmAlloc(ctx.modules, encoded.length);
+   wasmWrite(ctx.modules, ptr, encoded);
+   const token = searchFn(ptr, encoded.length) as number;
+   wasmFree(ctx.modules, ptr, encoded.length);
+
+   const statusFn = getWasmExport(ctx.modules, 'worker_result_status');
+   const status = statusFn(token) as number;
+   if (status === 3) {
+      getWasmExport(ctx.modules, 'worker_get_result')(token);
+      const errBytes = readReturnSlot(ctx.modules);
+      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
+   }
+
+   const getResultFn = getWasmExport(ctx.modules, 'worker_get_result');
+   const rc = getResultFn(token) as number;
+   if (rc === -1) {
+      const errBytes = readReturnSlot(ctx.modules);
+      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
+   }
+   return decodePagedSearchResult(readReturnSlot(ctx.modules));
+}
+
+/**
+ * Handles the `get_result_status` IPC method.
+ */
+export function handleResultStatus(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const token = Number(params['token'] ?? 0);
+   const fn = getWasmExport(ctx.modules, 'worker_result_status');
+   return { status: fn(token) as number };
+}
+
+/**
+ * Handles the `get_result` IPC method.
+ */
+export function handleGetResult(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const token = Number(params['token'] ?? 0);
+   const fn = getWasmExport(ctx.modules, 'worker_get_result');
+   const rc = fn(token) as number;
+   if (rc === -1) {
+      const errBytes = readReturnSlot(ctx.modules);
+      throw new IpcError(-32000, new TextDecoder().decode(errBytes));
+   }
+   return decodePagedSearchResult(readReturnSlot(ctx.modules));
+}
+
+/**
+ * Handles the `readSections` IPC method.
+ */
+export function handleReadSections(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const kbids = (params['kbids'] ?? []) as string[];
+   const encoded = encodeKbidList(kbids);
+   const bytes = callWasmSync(
+      ctx.modules,
+      'worker_read_sections',
+      encoded,
+   );
+   return decodeSectionRecords(bytes);
+}
+
+/**
+ * Handles the `retrieveDocument` IPC method.
+ */
+export function handleRetrieveDoc(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const docid = (params['docid'] as string | undefined) ?? '';
+   const encoded = new TextEncoder().encode(docid);
+   const bytes = callWasmSync(
+      ctx.modules,
+      'worker_retrieve_doc',
+      encoded,
+   );
+   return decodeDocumentManifest(bytes);
+}
+
+/**
+ * Handles the `content` and `compose` IPC methods.
+ */
+export function handleCompose(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const ids = (params['ids'] ?? []) as string[];
+   const encoded = encodeIdentifierList(ids);
+   const bytes = callWasmSync(ctx.modules, 'worker_compose', encoded);
+   const output = decodeComposeOutput(bytes);
+   return { data: output.markdown, total: Number(output.totalChars) };
+}
+
+/**
+ * Handles the `integrityCheck` IPC method.
+ */
+export function handleIntegrityCheck(ctx: HandlerContext): unknown {
+   callWasmZeroArg(ctx.modules, 'worker_check_integrity');
+   const bytes = readReturnSlot(ctx.modules);
+   return decodeKeyValueText(new TextDecoder().decode(bytes));
+}
+
+/**
+ * Handles the `dbStatus` IPC method.
+ */
+export function handleDbStatus(ctx: HandlerContext): unknown {
+   callWasmZeroArg(ctx.modules, 'worker_status');
+   const bytes = readReturnSlot(ctx.modules);
+   return decodeKeyValueText(new TextDecoder().decode(bytes));
+}
+
+/**
+ * Handles the `listByType` IPC method.
+ */
+export function handleListByType(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const typeStr = (params['sectionType'] as string | undefined) ?? '';
+   const encoded = encodeTypeFilterParam(typeStr);
+   const bytes = callWasmSync(
+      ctx.modules,
+      'worker_list_by_type',
+      encoded,
+   );
+   return decodeSectionRecordList(bytes);
+}
+
+/**
+ * Handles the `listDocumentsByType` IPC method.
+ */
+export function handleListDocsByType(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const typeStr = (params['docType'] as string | undefined) ?? '';
+   const encoded = encodeTypeFilterParam(typeStr);
+   const bytes = callWasmSync(
+      ctx.modules,
+      'worker_list_docs_by_type',
+      encoded,
+   );
+   return decodeDocumentManifestList(bytes);
+}
+
+/**
+ * Handles the `recall` IPC method.
+ */
+export function handleRecall(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const kbid =
+      typeof params['kbid'] === 'string' ? params['kbid'] : undefined;
+   const kbids = Array.isArray(params['kbids'])
+      ? (params['kbids'] as string[])
+      : undefined;
+   const depth = Number(params['depth'] ?? 0);
+   const encoded = encodeRecallParams({ kbid, kbids, depth });
+   const bytes = callWasmSync(ctx.modules, 'worker_recall', encoded);
+   return decodeRecallResult(bytes);
+}
+
+/**
+ * Handles the `export` and `exportDb` IPC methods.
+ */
+export function handleExport(
+   ctx: HandlerContext,
+   params: Record<string, unknown>,
+): unknown {
+   const targetPath =
+      (params['targetPath'] as string | undefined) ??
+      (params['path'] as string | undefined) ??
+      './kbdb-export/';
+   const encoded = new TextEncoder().encode(targetPath);
+   const start = Date.now();
+   const bytes = callWasmSync(ctx.modules, 'worker_export', encoded);
+   const elapsed = Date.now() - start;
+   const kv = decodeKeyValueText(new TextDecoder().decode(bytes));
+   return {
+      path: kv['path'] ?? targetPath,
+      sections_exported: Number(kv['sections_exported'] ?? 0),
+      documents_exported: Number(kv['documents_exported'] ?? 0),
+      elapsed_ms: elapsed,
+   };
+}