@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/worker-daemon/constants/daemon-defaults.constant.ts

@@ -1,29 +0,0 @@
-/** Default maximum number of items held in daemon memory. */
-export const DEFAULT_ITEM_LIMIT = 1000;
-
-/** Default maximum number of index entries held in daemon memory. */
-export const DEFAULT_INDEX_LIMIT = 100;
-
-/**
- * Default idle timeout in milliseconds before the daemon shuts
- * down automatically (5 minutes).
- */
-export const DEFAULT_TIMEOUT_MS = 300_000;
-
-/**
- * Default time-to-live in milliseconds for each cached item
- * (1 minute).
- */
-export const DEFAULT_ITEM_TTL_MS = 60_000;
-
-/** Filename of the daemon configuration file inside `.kbdb/`. */
-export const WORKER_TOML_FILENAME = 'worker.toml';
-
-/**
- * Database format version the daemon supports.
- *
- * Read from `catalog.toml` at startup. If the catalog version
- * differs, the daemon prints a structured error to stderr and
- * exits with code 1 before loading any WASM modules.
- */
-export const DB_FORMAT_VERSION = 1;

package/src/shared/worker-daemon/constants/wasm-method-map.constant.ts

@@ -1,69 +0,0 @@
-import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
-
-/**
- * Maps incoming IPC method names to `kb-worker.wasm` export names.
- *
- * Both camelCase and snake_case variants of each method are
- * included so that clients may use either convention.
- */
-export const WASM_METHOD_MAP: Readonly<
-   Partial<Record<string, string>>
-> = {
-   search: 'worker_search',
-   addSection: 'worker_add_section',
-   add_section: 'worker_add_section',
-   updateSection: 'worker_update_section',
-   update_section: 'worker_update_section',
-   removeSection: 'worker_remove_section',
-   remove_section: 'worker_remove_section',
-   readSections: 'worker_read_sections',
-   read_sections: 'worker_read_sections',
-   groupSections: 'worker_group_sections',
-   group_sections: 'worker_group_sections',
-   removeGrouping: 'worker_remove_grouping',
-   remove_grouping: 'worker_remove_grouping',
-   retrieveDocument: 'worker_retrieve_doc',
-   retrieve_doc: 'worker_retrieve_doc',
-   content: 'worker_compose',
-   compose: 'worker_compose',
-   integrity_check: 'worker_check_integrity',
-   integrityCheck: 'worker_check_integrity',
-   gc: 'worker_garbage_collect',
-   rebuild_indexes: 'worker_rebuild_indexes',
-   rebuildIndexes: 'worker_rebuild_indexes',
-   init_directory: 'worker_init_directory',
-   initDirectory: 'worker_init_directory',
-   migrateDatabase: 'worker_migrate',
-   query: 'worker_query',
-   get_result_status: 'worker_result_status',
-   get_result: 'worker_get_result',
-   invalidate: 'worker_invalidate',
-   invalidate_all: 'worker_invalidate_all',
-   invalidateAll: 'worker_invalidate_all',
-   db_status: 'worker_status',
-   dbStatus: 'worker_status',
-   listByType: 'worker_list_by_type',
-   list_by_type: 'worker_list_by_type',
-   listDocumentsByType: 'worker_list_docs_by_type',
-   list_docs_by_type: 'worker_list_docs_by_type',
-   recall: 'worker_recall',
-   export: 'worker_export',
-   exportDb: 'worker_export',
-};
-
-/** Prefix shared by all IPC config-accessor method names. */
-export const CONFIG_PREFIX = 'config_';
-
-/**
- * Maps config IPC key suffixes to `DaemonConfig` property names.
- *
- * A client sends `config_timeout_ms` to read `config.timeoutMs`.
- */
-export const CONFIG_KEY_MAP: Readonly<
-   Partial<Record<string, keyof DaemonConfig>>
-> = {
-   timeout_ms: 'timeoutMs',
-   item_ttl_ms: 'itemTtlMs',
-   item_limit: 'itemLimit',
-   index_limit: 'indexLimit',
-};

package/src/shared/worker-daemon/functions/build-ipc-error-response.function.ts

@@ -1,16 +0,0 @@
-import type { IpcResponse } from '../typings/ipc-handler.interface.ts';
-
-/**
- * Builds a JSON-RPC 2.0 error response object.
- *
- * @param id - request identifier to echo back in the response
- * @param code - JSON-RPC error code
- * @param message - human-readable error description
- */
-export function buildIpcErrorResponse(
-   id: number | string,
-   code: number,
-   message: string,
-): IpcResponse {
-   return { jsonrpc: '2.0', id, error: { code, message } };
-}

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

@@ -1,54 +0,0 @@
-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';
-
-/**
- * Reads `catalog.toml` in `targetDir` and validates its version
- * against `DB_FORMAT_VERSION`.
- *
- * @param targetDir - absolute path to the `.kbdb` directory
- * @throws {Error} when the catalog cannot be read, is missing a
- *   version, or the version is incompatible with the current engine
- */
-export function checkCatalogVersion(targetDir: string): void {
-   const catalogPath = join(targetDir, 'catalog.toml');
-   let text: string;
-   try {
-      text = readFileSync(catalogPath, 'utf-8');
-   } catch {
-      throw new Error(
-         `cannot read database directory: ${targetDir}` +
-            ' -- permission denied',
-      );
-   }
-
-   const version = parseCatalogVersion(text);
-   if (version === null) {
-      throw new Error(
-         'database version 0 requires migration to version ' +
-            String(DB_FORMAT_VERSION) +
-            ' -- run `kbdb --migrate` before starting the daemon',
-      );
-   }
-
-   if (version > DB_FORMAT_VERSION) {
-      throw new Error(
-         'database version ' +
-            String(version) +
-            ' is newer than kbdb version ' +
-            String(DB_FORMAT_VERSION) +
-            ' -- upgrade kbdb to open this database',
-      );
-   }
-
-   if (version < DB_FORMAT_VERSION) {
-      throw new Error(
-         'database version ' +
-            String(version) +
-            ' requires migration to version ' +
-            String(DB_FORMAT_VERSION) +
-            ' -- run `kbdb --migrate` before starting the daemon',
-      );
-   }
-}

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

@@ -1,28 +0,0 @@
-import { existsSync, accessSync, constants } from 'node:fs';
-import { checkCatalogVersion } from './check-catalog-version.function.ts';
-
-/**
- * Validates startup preconditions for the worker daemon.
- *
- * Checks that `targetDir` exists, is readable and writable, and
- * that `catalog.toml` reports a compatible format version.
- *
- * @param targetDir - absolute path to the `.kbdb` directory
- * @throws {Error} when any precondition fails
- */
-export function checkPreconditions(targetDir: string): void {
-   if (!existsSync(targetDir)) {
-      throw new Error(`database directory not found: ${targetDir}`);
-   }
-
-   try {
-      accessSync(targetDir, constants.R_OK | constants.W_OK);
-   } catch {
-      throw new Error(
-         `cannot access database directory: ${targetDir}` +
-            ' -- permission denied',
-      );
-   }
-
-   checkCatalogVersion(targetDir);
-}

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

@@ -1,328 +0,0 @@
-import {
-   readFileSync,
-   writeFileSync,
-   renameSync,
-   unlinkSync,
-   readdirSync,
-   mkdirSync,
-   existsSync,
-} from 'node:fs';
-import { join } from 'node:path';
-
-// ---------------------------------------------------------------------------
-// FsAdapter interface (enables dependency injection for testing)
-// ---------------------------------------------------------------------------
-
-/**
- * Minimal filesystem operations required by the host imports.
- *
- * The default implementation delegates to `node:fs` synchronous
- * APIs. Tests inject a stub to avoid touching the real filesystem.
- */
-export interface FsAdapter {
-   /** Read entire file as a Buffer. */
-   readFileSync(path: string): Buffer;
-   /** Write data buffer to file. */
-   writeFileSync(path: string, data: Uint8Array): void;
-   /** Rename `oldPath` to `newPath`. */
-   renameSync(oldPath: string, newPath: string): void;
-   /** Delete a file. */
-   unlinkSync(path: string): void;
-   /** List directory entries as strings. */
-   readdirSync(path: string): string[];
-   /** Create a directory (and parents) recursively. */
-   mkdirSync(path: string): void;
-   /** Return true if the path exists. */
-   existsSync(path: string): boolean;
-}
-
-// ---------------------------------------------------------------------------
-// MemoryRef interface
-// ---------------------------------------------------------------------------
-
-/**
- * A mutable reference to the WASM linear memory.
- *
- * The `memory` field starts as `null` and is wired up after the
- * `kb-worker` WASM module is instantiated (the module exports its
- * own memory rather than importing one). Host import functions
- * read `memory` at call time, not at creation time, so the ref
- * can be populated after the import record is built.
- */
-export interface MemoryRef {
-   memory: WebAssembly.Memory | null;
-}
-
-// ---------------------------------------------------------------------------
-// AllocatorRef interface
-// ---------------------------------------------------------------------------
-
-/**
- * A mutable reference to the WASM allocator function.
- *
- * The `alloc` field starts as `null` and is wired up after the
- * `kb-worker` WASM module is instantiated. Host import functions
- * that must allocate memory in WASM linear memory check this
- * reference before proceeding and return -1 when it is null.
- */
-export interface AllocatorRef {
-   /**
-    * Allocates `size` bytes in WASM linear memory and returns the
-    * byte offset of the allocated region, or `null` when the
-    * allocator is not yet available.
-    */
-   alloc: ((size: number) => number) | null;
-}
-
-/** Default `FsAdapter` backed by `node:fs` synchronous APIs. */
-const nodeFsAdapter: FsAdapter = {
-   readFileSync: (p) => readFileSync(p),
-   writeFileSync: (p, d) => {
-      writeFileSync(p, d);
-   },
-   renameSync: (o, n) => {
-      renameSync(o, n);
-   },
-   unlinkSync: (p) => {
-      unlinkSync(p);
-   },
-   readdirSync: (p) => readdirSync(p),
-   mkdirSync: (p) => {
-      mkdirSync(p, { recursive: true });
-   },
-   existsSync: (p) => existsSync(p),
-};
-
-/** Default `MemoryRef` with no memory wired. */
-const nullMemory: MemoryRef = { memory: null };
-
-/** Default `AllocatorRef` with no allocator wired. */
-const nullAllocator: AllocatorRef = { alloc: null };
-
-// ---------------------------------------------------------------------------
-// createHostImports
-// ---------------------------------------------------------------------------
-
-/**
- * Creates the host I/O import functions required by `kb-worker.wasm`.
- *
- * All functions read the WASM linear memory through `memoryRef`,
- * a deferred reference wired up after module instantiation (the
- * module exports its own memory). Paths from WASM are resolved
- * relative to `contextPath`.
- *
- * @param contextPath - absolute path to the `.kbdb` database directory
- * @param memoryRef - deferred reference to the WASM module's
- *   exported memory; wired after instantiation
- * @param fs - filesystem adapter; defaults to real `node:fs` operations
- * @param allocator - reference to the WASM allocator; wired after
- *   `kb-worker` instantiation. Defaults to a null (uninitialized) ref.
- * @returns a record of host import functions keyed by their WASM import
- *   names
- */
-export function createHostImports(
-   contextPath: string,
-   memoryRef: MemoryRef = nullMemory,
-   fs: FsAdapter = nodeFsAdapter,
-   allocator: AllocatorRef = nullAllocator,
-): Record<string, WebAssembly.ImportValue> {
-   function getBuffer(): ArrayBuffer {
-      if (!memoryRef.memory) {
-         throw new Error('WASM memory not initialized');
-      }
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-      return memoryRef.memory.buffer as ArrayBuffer;
-   }
-
-   function readPathArg(ptr: number, len: number): string {
-      const bytes = new Uint8Array(getBuffer(), ptr, len);
-      const decoded = new TextDecoder().decode(bytes);
-      if (decoded.startsWith('/')) return decoded;
-      return join(contextPath, decoded);
-   }
-
-   return {
-      /**
-       * Reads a file at the path encoded in shared memory and writes
-       * the result back via the out-pointer protocol.
-       *
-       * `outPtr` and `outLen` are WASM linear-memory addresses. On
-       * success, the host allocates a buffer via `allocator.alloc`,
-       * copies the file data there, and writes the allocated pointer
-       * as a LE u32 to `outPtr` and the data length as a LE u32 to
-       * `outLen`. Returns 0 on success, -1 on error or when the
-       * allocator is not yet available.
-       */
-      host_read_file(
-         pathPtr: number,
-         pathLen: number,
-         outPtr: number,
-         outLen: number,
-      ): number {
-         try {
-            if (!allocator.alloc) return -1;
-            const filePath = readPathArg(pathPtr, pathLen);
-            const data = fs.readFileSync(filePath);
-            const dataLen = data.byteLength;
-            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(
-                  data.buffer,
-                  data.byteOffset,
-                  data.byteLength,
-               ),
-               dataPtr,
-            );
-            dv.setUint32(outPtr, dataPtr, true);
-            dv.setUint32(outLen, dataLen, true);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Writes bytes from shared memory (`dataPtr`, `dataLen`) to the
-       * file at the path encoded in shared memory. Returns 0 on
-       * success, -1 on error.
-       */
-      host_write_file(
-         pathPtr: number,
-         pathLen: number,
-         dataPtr: number,
-         dataLen: number,
-      ): number {
-         try {
-            const filePath = readPathArg(pathPtr, pathLen);
-            const data = new Uint8Array(getBuffer(), dataPtr, dataLen);
-            fs.writeFileSync(filePath, data);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Renames the file at `oldPtr/oldLen` to `newPtr/newLen`.
-       * Both paths are resolved relative to `contextPath`. Returns 0
-       * on success, -1 on error.
-       */
-      host_rename(
-         oldPtr: number,
-         oldLen: number,
-         newPtr: number,
-         newLen: number,
-      ): number {
-         try {
-            const oldPath = readPathArg(oldPtr, oldLen);
-            const newPath = readPathArg(newPtr, newLen);
-            fs.renameSync(oldPath, newPath);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Deletes the file at the path encoded in shared memory.
-       * Returns 0 on success, -1 on error.
-       */
-      host_remove_file(pathPtr: number, pathLen: number): number {
-         try {
-            const filePath = readPathArg(pathPtr, pathLen);
-            fs.unlinkSync(filePath);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Lists the directory at the path encoded in shared memory and
-       * writes the result back via the out-pointer protocol.
-       *
-       * `outPtr` and `outLen` are WASM linear-memory addresses. On
-       * success, the host allocates a buffer via `allocator.alloc`,
-       * copies a newline-delimited UTF-8 listing there, and writes
-       * the allocated pointer as a LE u32 to `outPtr` and the byte
-       * length as a LE u32 to `outLen`. Returns 0 on success, -1 on
-       * error or when the allocator is not yet available.
-       */
-      host_list_dir(
-         pathPtr: number,
-         pathLen: number,
-         outPtr: number,
-         outLen: number,
-      ): number {
-         try {
-            if (!allocator.alloc) return -1;
-            const dirPath = readPathArg(pathPtr, pathLen);
-            const entries = fs.readdirSync(dirPath);
-            const text = entries.join('\n');
-            const encoded = new TextEncoder().encode(text);
-            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,
-            );
-            dv.setUint32(outPtr, dataPtr, true);
-            dv.setUint32(outLen, encoded.length, true);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Creates the directory at the path encoded in shared memory,
-       * including any missing parent directories (recursive). Returns
-       * 0 on success, -1 on error.
-       */
-      host_mkdir(pathPtr: number, pathLen: number): number {
-         try {
-            const dirPath = readPathArg(pathPtr, pathLen);
-            fs.mkdirSync(dirPath);
-            return 0;
-         } catch {
-            return -1;
-         }
-      },
-
-      /**
-       * Checks whether the file at the path encoded in shared memory
-       * exists. Returns 1 if it exists, 0 if it does not.
-       */
-      host_file_exists(pathPtr: number, pathLen: number): number {
-         const filePath = readPathArg(pathPtr, pathLen);
-         return fs.existsSync(filePath) ? 1 : 0;
-      },
-   };
-}

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

@@ -1,87 +0,0 @@
-import { createServer } from 'node:net';
-import type { Server, Socket } from 'node:net';
-import type {
-   IpcHandler,
-   IpcRequest,
-   IpcResponse,
-} from '../typings/ipc-handler.interface.ts';
-
-/**
- * Creates a Unix socket (or named pipe on Windows) IPC server that
- * reads newline-delimited JSON-RPC requests and writes responses.
- *
- * Each line received on a socket connection is parsed as an
- * `IpcRequest`, dispatched to `handler`, and the resulting
- * `IpcResponse` is written back as a newline-terminated JSON string.
- * A malformed line that cannot be parsed results in a JSON-RPC
- * parse-error response (`-32700`).
- *
- * @param socketPath - path to the Unix domain socket or Windows
- *   named pipe
- * @param handler - async function invoked for each valid request
- * @returns the listening `net.Server` instance
- */
-export function createIpcServer(
-   socketPath: string,
-   handler: IpcHandler,
-): Server {
-   const server = createServer((socket) => {
-      let buffer = '';
-
-      let processingQueue = Promise.resolve();
-
-      socket.on('data', (chunk: Buffer) => {
-         buffer += chunk.toString();
-         const lines = buffer.split('\n');
-         buffer = lines.pop() ?? '';
-
-         for (const line of lines) {
-            if (!line.trim()) continue;
-            processingQueue = processingQueue.then(() =>
-               handleLine(line, handler, socket),
-            );
-         }
-      });
-
-      socket.on('error', (err: Error) => {
-         // eslint-disable-next-line no-console
-         console.error(
-            `kbdb-worker: ipc connection error: ${err.message}`,
-         );
-      });
-   });
-
-   server.on('error', (err: Error) => {
-      // eslint-disable-next-line no-console
-      console.error(`kbdb-worker: ipc server error: ${err.message}`);
-   });
-
-   server.listen(socketPath);
-   return server;
-}
-
-function bigintReplacer(_key: string, value: unknown): unknown {
-   return typeof value === 'bigint' ? Number(value) : value;
-}
-
-async function handleLine(
-   line: string,
-   handler: IpcHandler,
-   socket: Socket,
-): Promise<void> {
-   let response: IpcResponse;
-   try {
-      const request = JSON.parse(line) as IpcRequest;
-      response = await handler(request);
-   } catch {
-      response = {
-         jsonrpc: '2.0',
-         id: 0,
-         error: {
-            code: -32700,
-            message: 'Parse error',
-         },
-      };
-   }
-   socket.write(JSON.stringify(response, bigintReplacer) + '\n');
-}

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

@@ -1,33 +0,0 @@
-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;
-}