@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/worker-daemon/classes/worker-daemon.class.ts

@@ -1,1291 +0,0 @@
-import {
-   existsSync,
-   readFileSync,
-   readdirSync,
-   accessSync,
-   writeFileSync,
-   unlinkSync,
-   constants,
-} from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import type { Server } from 'node:net';
-import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
-import type { WasmModules } from '../typings/wasm-modules.interface.ts';
-import type {
-   IpcRequest,
-   IpcResponse,
-   IpcHandler,
-} from '../typings/ipc-handler.interface.ts';
-import { DB_FORMAT_VERSION } from '../constants/daemon-defaults.constant.ts';
-import { loadWasmModules } from '../functions/load-wasm-modules.function.ts';
-import { createIpcServer } from '../functions/create-ipc-server.function.ts';
-import { getIpcPath } from '../../platform/functions/get-ipc-path.function.ts';
-import {
-   encodeSearchParams,
-   encodeAddSectionParams,
-   encodeUpdateSectionParams,
-   encodeKbidList,
-   encodeGroupParams,
-   encodeIdentifierList,
-   encodeTypeFilterParam,
-   encodeRecallParams,
-   decodePagedSearchResult,
-   decodeSectionRecords,
-   decodeSectionRecordList,
-   decodeDocumentManifest,
-   decodeDocumentManifestList,
-   decodeComposeOutput,
-   decodeKeyValueText,
-   decodeRemoveFlag,
-   decodeRecallResult,
-   decodeAddSectionResult,
-} from '../../wasm-codec/index.ts';
-
-import type { AddSectionInput } from '../../wasm-codec/index.ts';
-
-// ---------------------------------------------------------------------------
-// Internal types
-// ---------------------------------------------------------------------------
-
-/** Callable WASM export function signature. */
-type WasmFn = (...args: unknown[]) => unknown;
-
-/** Mapping from IPC method name to kb-worker.wasm export name. */
-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',
-};
-
-/** Config method name prefix. */
-const CONFIG_PREFIX = 'config_';
-
-/** Config key → DaemonConfig property mapping. */
-const CONFIG_KEY_MAP: Readonly<
-   Partial<Record<string, keyof DaemonConfig>>
-> = {
-   timeout_ms: 'timeoutMs',
-   item_ttl_ms: 'itemTtlMs',
-   item_limit: 'itemLimit',
-   index_limit: 'indexLimit',
-};
-
-// ---------------------------------------------------------------------------
-// IpcError
-// ---------------------------------------------------------------------------
-
-/** Typed JSON-RPC error used internally by WorkerDaemon dispatch. */
-class IpcError extends Error {
-   /** JSON-RPC error code. */
-   readonly code: number;
-
-   constructor(code: number, message: string) {
-      super(message);
-      this.code = code;
-      this.name = 'IpcError';
-   }
-}
-
-// ---------------------------------------------------------------------------
-// WorkerDaemon
-// ---------------------------------------------------------------------------
-
-/**
- * Core daemon class that manages the full worker daemon lifecycle.
- *
- * Orchestrates WASM module loading, IPC server creation, request
- * routing to `kb-worker.wasm` exports, idle timeout tracking, and
- * graceful shutdown. The daemon validates startup preconditions before
- * loading WASM modules and rejects IPC requests whose `ctx` param does
- * not match the daemon's context ID.
- */
-export class WorkerDaemon {
-   /** Context ID (16-character hex SHA-256 prefix). */
-   readonly ctx: string;
-
-   /** Absolute path to the `.kbdb` directory. */
-   readonly targetDir: string;
-
-   /** Parsed daemon configuration from `worker.toml`. */
-   readonly config: DaemonConfig;
-
-   /** Number of currently active IPC client connections. */
-   get connectionCount(): number {
-      return this._connectionCount;
-   }
-
-   private _connectionCount = 0;
-   private _wasmModules: WasmModules | null = null;
-   private _idleAt = 0;
-   private _idleTimer: ReturnType<typeof setTimeout> | null = null;
-   private _server: Server | null = null;
-   private readonly _wasmDir: string;
-
-   /** Queue of waiters for the single-writer lock. */
-   private _writeQueue: { resolve: () => void }[] = [];
-
-   /** Whether the write lock is currently held. */
-   private _writeLocked = false;
-
-   /** Whether the startup integrity check passed. */
-   private _integrityOk = true;
-
-   /** Integrity errors found at startup, if any. */
-   private _integrityErrors: string[] = [];
-
-   /**
-    * @param ctx - context ID (16-hex characters), the first 16 of
-    *   the SHA-256 hash of `targetDir`
-    * @param targetDir - absolute path to the `.kbdb` directory
-    * @param config - parsed daemon configuration
-    * @param wasmDir - path to the WASM build output directory
-    */
-   constructor(
-      ctx: string,
-      targetDir: string,
-      config: DaemonConfig,
-      wasmDir?: string,
-   ) {
-      this.ctx = ctx;
-      this.targetDir = targetDir;
-      this.config = config;
-      this._wasmDir = wasmDir ?? '';
-   }
-
-   // -----------------------------------------------------------------------
-   // Public API
-   // -----------------------------------------------------------------------
-
-   /**
-    * Validates startup preconditions before WASM module loading.
-    *
-    * Checks that the database directory exists, is readable and
-    * writable, and that `catalog.toml` reports a compatible version.
-    *
-    * @throws {Error} if any precondition fails -- `startDaemon`
-    *   catches this, prints to stderr, and exits with code 1
-    */
-   checkPreconditions(): void {
-      if (!existsSync(this.targetDir)) {
-         throw new Error(
-            `database directory not found: ${this.targetDir}`,
-         );
-      }
-
-      try {
-         accessSync(
-            this.targetDir,
-
-            constants.R_OK | constants.W_OK,
-         );
-      } catch {
-         throw new Error(
-            `cannot access database directory: ${this.targetDir}` +
-               ' -- permission denied',
-         );
-      }
-
-      this.checkCatalogVersion();
-   }
-
-   /**
-    * Starts the daemon: loads WASM modules, writes the PID file,
-    * creates the IPC socket, and begins listening for connections.
-    *
-    * Call `checkPreconditions()` before `start()` to validate the
-    * database directory. The daemon will not start if any precondition
-    * fails.
-    *
-    * @throws when WASM module loading fails or the IPC socket cannot
-    *   be created
-    */
-   async start(): Promise<void> {
-      const wasmModules = await loadWasmModules(
-         this.config,
-         this._wasmDir,
-      );
-      this._wasmModules = wasmModules;
-
-      this.initWorkerContext();
-      this.runStartupIntegrityCheck();
-
-      const pidPath = join(tmpdir(), `kbdb-${this.ctx}.pid`);
-      writeFileSync(pidPath, process.pid.toString());
-
-      const ipcPath = getIpcPath(this.ctx);
-
-      if (existsSync(ipcPath)) {
-         try {
-            unlinkSync(ipcPath);
-         } catch {
-            // ignore stale socket removal errors
-         }
-      }
-
-      const handler: IpcHandler = (req) => this.handleRequest(req);
-      this._server = createIpcServer(ipcPath, handler);
-
-      this._server.on('connection', () => {
-         this.incrementConnections();
-         this.resetIdleTimer();
-      });
-
-      this._server.on('close', () => {
-         this.decrementConnections();
-         if (this._connectionCount === 0) {
-            this.resetIdleTimer();
-         }
-      });
-
-      this.resetIdleTimer();
-   }
-
-   /**
-    * Gracefully shuts down the daemon.
-    *
-    * Stops accepting new connections, clears the idle timer, purges
-    * WASM state, removes the PID file and IPC socket file, then exits
-    * the process.
-    */
-   stop(): void {
-      if (this._idleTimer !== null) {
-         clearTimeout(this._idleTimer);
-         this._idleTimer = null;
-      }
-
-      if (this._server !== null) {
-         this._server.close();
-         this._server = null;
-      }
-
-      this._wasmModules = null;
-
-      const pidPath = join(tmpdir(), `kbdb-${this.ctx}.pid`);
-      try {
-         unlinkSync(pidPath);
-      } catch {
-         // ignore cleanup errors
-      }
-
-      const ipcPath = getIpcPath(this.ctx);
-      try {
-         unlinkSync(ipcPath);
-      } catch {
-         // ignore cleanup errors
-      }
-
-      const crashPath = join(tmpdir(), `kbdb-${this.ctx}.crash`);
-      try {
-         unlinkSync(crashPath);
-      } catch {
-         // ignore cleanup errors
-      }
-
-      process.exit(0);
-   }
-
-   /**
-    * Handles a single JSON-RPC 2.0 request.
-    *
-    * Validates context, then routes to a daemon-state handler or a
-    * WASM export. Requests whose `ctx` param does not match the
-    * daemon's context ID are rejected with error code `-32001`.
-    *
-    * @param request - incoming JSON-RPC request
-    * @returns the JSON-RPC response
-    */
-   async handleRequest(request: IpcRequest): Promise<IpcResponse> {
-      const params = request.params as
-         | Record<string, unknown>
-         | undefined;
-      if (params === undefined || params.ctx !== this.ctx) {
-         return this.errorResponse(
-            request.id,
-            -32001,
-            'context mismatch',
-         );
-      }
-
-      this.resetIdleTimer();
-
-      try {
-         const result = await this.dispatch(request.method, params);
-         this._idleAt = Math.floor(Date.now() / 1000);
-         return {
-            jsonrpc: '2.0',
-            id: request.id,
-            result,
-         };
-      } catch (err) {
-         this._idleAt = Math.floor(Date.now() / 1000);
-         if (err instanceof IpcError) {
-            return this.errorResponse(
-               request.id,
-               err.code,
-               err.message,
-            );
-         }
-         const message =
-            err instanceof Error ? err.message : String(err);
-         return this.errorResponse(request.id, -32000, message);
-      }
-   }
-
-   /**
-    * Increments the active connection count.
-    *
-    * Call when a new IPC client connects.
-    */
-   incrementConnections(): void {
-      this._connectionCount++;
-   }
-
-   /**
-    * Decrements the active connection count, clamped to zero.
-    *
-    * Call when an IPC client disconnects.
-    */
-   decrementConnections(): void {
-      if (this._connectionCount > 0) {
-         this._connectionCount--;
-      }
-   }
-
-   /**
-    * Injects pre-built WASM modules for unit testing.
-    *
-    * This method exists solely to support unit tests that cannot
-    * load real WASM binaries. It must not be called in production
-    * code -- production code uses `start()` to load modules.
-    *
-    * @param modules - pre-built WASM module instances
-    * @internal
-    */
-   injectModulesForTesting(modules: WasmModules): void {
-      this._wasmModules = modules;
-   }
-
-   // -----------------------------------------------------------------------
-   // Private helpers
-   // -----------------------------------------------------------------------
-
-   /** Resets the idle timer; triggers stop() when it fires. */
-   private resetIdleTimer(): void {
-      if (this._idleTimer !== null) {
-         clearTimeout(this._idleTimer);
-      }
-      if (this._connectionCount === 0) {
-         this._idleTimer = setTimeout(() => {
-            this.stop();
-         }, this.config.timeoutMs);
-      }
-   }
-
-   /** Reads catalog.toml and validates the version field. */
-   private checkCatalogVersion(): void {
-      const catalogPath = join(this.targetDir, 'catalog.toml');
-      let text: string;
-      try {
-         text = readFileSync(catalogPath, 'utf-8');
-      } catch {
-         throw new Error(
-            `cannot read database directory: ${this.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',
-         );
-      }
-   }
-
-   /** Builds a JSON-RPC error response. */
-   private errorResponse(
-      id: number | string,
-      code: number,
-      message: string,
-   ): IpcResponse {
-      return {
-         jsonrpc: '2.0',
-         id,
-         error: { code, message },
-      };
-   }
-
-   /**
-    * Dispatches a request method to the appropriate handler.
-    *
-    * Handles daemon-state methods (`status`, `idle_at`,
-    * `config_{key}`) inline and routes WASM methods to the
-    * correct calling convention for each export.
-    */
-   private dispatch(
-      method: string,
-      params: Record<string, unknown>,
-   ): unknown {
-      if (method === 'status') {
-         return {
-            status: this._connectionCount > 0 ? 'busy' : 'idle',
-            integrityOk: this._integrityOk,
-            integrityErrors: this._integrityErrors,
-         };
-      }
-
-      if (method === 'idle_at') {
-         return this._idleAt;
-      }
-
-      if (method === 'checkVersion') {
-         return this.handleCheckVersion(params);
-      }
-
-      if (method.startsWith(CONFIG_PREFIX)) {
-         return this.handleConfigMethod(method);
-      }
-
-      const wasmMethod = WASM_METHOD_MAP[method];
-      if (wasmMethod !== undefined) {
-         return this.dispatchWasm(method, wasmMethod, params);
-      }
-
-      throw new IpcError(-32601, `Method not found: ${method}`);
-   }
-
-   private async dispatchWasm(
-      method: string,
-      wasmExport: string,
-      params: Record<string, unknown>,
-   ): Promise<unknown> {
-      // Read-only operations — no write lock required.
-      if (method === 'search' || method === 'query') {
-         return this.handleSearch(params);
-      }
-      if (method === 'readSections' || method === 'read_sections') {
-         return this.handleReadSections(params);
-      }
-      if (method === 'retrieveDocument' || method === 'retrieve_doc') {
-         return this.handleRetrieveDoc(params);
-      }
-      if (method === 'content' || method === 'compose') {
-         return this.handleCompose(params);
-      }
-      if (method === 'integrityCheck' || method === 'integrity_check') {
-         return this.handleIntegrityCheck();
-      }
-      if (method === 'dbStatus' || method === 'db_status') {
-         return this.handleDbStatus();
-      }
-      if (method === 'get_result_status') {
-         return this.handleResultStatus(params);
-      }
-      if (method === 'get_result') {
-         return this.handleGetResult(params);
-      }
-      if (method === 'listByType' || method === 'list_by_type') {
-         return this.handleListByType(params);
-      }
-      if (
-         method === 'listDocumentsByType' ||
-         method === 'list_docs_by_type'
-      ) {
-         return this.handleListDocsByType(params);
-      }
-      if (method === 'recall') {
-         return this.handleRecall(params);
-      }
-      if (method === 'export' || method === 'exportDb') {
-         return this.handleExport(params);
-      }
-
-      // Write operations — serialised through the single-writer lock.
-      await this.acquireWriteLock();
-      try {
-         if (method === 'invalidate') {
-            return this.handleInvalidate(params);
-         }
-         if (
-            method === 'invalidateAll' ||
-            method === 'invalidate_all'
-         ) {
-            return this.handleInvalidateAll();
-         }
-         if (method === 'addSection' || method === 'add_section') {
-            return this.handleAddSection(params);
-         }
-         if (
-            method === 'updateSection' ||
-            method === 'update_section'
-         ) {
-            return this.handleUpdateSection(params);
-         }
-         if (
-            method === 'removeSection' ||
-            method === 'remove_section'
-         ) {
-            return this.handleRemoveSection(params);
-         }
-         if (
-            method === 'groupSections' ||
-            method === 'group_sections'
-         ) {
-            return this.handleGroupSections(params);
-         }
-         if (
-            method === 'removeGrouping' ||
-            method === 'remove_grouping'
-         ) {
-            return this.handleRemoveGrouping(params);
-         }
-         if (method === 'gc') {
-            return this.handleGc();
-         }
-         if (
-            method === 'rebuildIndexes' ||
-            method === 'rebuild_indexes'
-         ) {
-            return this.handleRebuild();
-         }
-         if (
-            method === 'initDirectory' ||
-            method === 'init_directory'
-         ) {
-            return this.handleInitDirectory(params);
-         }
-         if (method === 'migrateDatabase') {
-            throw new IpcError(
-               -32601,
-               'migrateDatabase is not yet supported',
-            );
-         }
-         return this.invokeWasmRaw(wasmExport, new Uint8Array(0));
-      } finally {
-         this.releaseWriteLock();
-      }
-   }
-
-   // -- Search/query (token-based async) --
-
-   private handleSearch(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 = this.getExport('worker_search');
-      const ptr = this.wasmAlloc(encoded.length);
-      this.wasmWrite(ptr, encoded);
-      const token = searchFn(ptr, encoded.length) as number;
-      this.wasmFree(ptr, encoded.length);
-
-      const statusFn = this.getExport('worker_result_status');
-      const status = statusFn(token) as number;
-      if (status === 3) {
-         const getResultFn = this.getExport('worker_get_result');
-         getResultFn(token);
-         const errBytes = this.readReturnSlot();
-         const errMsg = new TextDecoder().decode(errBytes);
-         throw new IpcError(-32000, errMsg);
-      }
-
-      const getResultFn = this.getExport('worker_get_result');
-      const rc = getResultFn(token) as number;
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         throw new IpcError(-32000, new TextDecoder().decode(errBytes));
-      }
-      const resultBytes = this.readReturnSlot();
-      return decodePagedSearchResult(resultBytes);
-   }
-
-   // -- Token status/result (u32 direct params) --
-
-   private handleResultStatus(
-      params: Record<string, unknown>,
-   ): unknown {
-      const token = Number(params['token'] ?? 0);
-      const fn = this.getExport('worker_result_status');
-      const status = fn(token) as number;
-      return { status };
-   }
-
-   private handleGetResult(params: Record<string, unknown>): unknown {
-      const token = Number(params['token'] ?? 0);
-      const fn = this.getExport('worker_get_result');
-      const rc = fn(token) as number;
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         throw new IpcError(-32000, new TextDecoder().decode(errBytes));
-      }
-      const bytes = this.readReturnSlot();
-      return decodePagedSearchResult(bytes);
-   }
-
-   // -- Binary-encoded input methods --
-
-   private handleAddSection(params: Record<string, unknown>): unknown {
-      const sectionType = (params['sectionType'] ?? 'text') as string;
-      const semanticType =
-         sectionType === 'text' ||
-         sectionType === 'code' ||
-         sectionType === 'image'
-            ? sectionType
-            : 'text';
-      const typeName =
-         sectionType !== semanticType ? sectionType : null;
-      const tags = Array.isArray(params['tags'])
-         ? (params['tags'] as string[])
-         : [];
-      const input: AddSectionInput = {
-         sectionType: semanticType,
-         mimeType: params['mimeType'] as string | undefined,
-         content: (params['content'] as string | undefined) ?? '',
-         title: (params['title'] as string | null) ?? null,
-         description: (params['description'] as string | null) ?? null,
-         docid: (params['docid'] as string | null) ?? null,
-         typeName,
-         sourcePath:
-            typeof params['sourcePath'] === 'string'
-               ? params['sourcePath']
-               : undefined,
-         sourceMtime:
-            typeof params['sourceMtime'] === 'string'
-               ? params['sourceMtime']
-               : undefined,
-         tags,
-         replace: params['replace'] === true,
-      };
-      const encoded = encodeAddSectionParams(input);
-      const bytes = this.callWasmSync('worker_add_section', encoded);
-      const decoded = decodeAddSectionResult(bytes);
-      const nearDups =
-         decoded.nearDuplicates.length > 0
-            ? decoded.nearDuplicates
-            : this.scanNearDuplicates(input.content, decoded.kbid);
-      return {
-         kbid: decoded.kbid,
-         indexed_terms_count: decoded.indexedTermsCount,
-         elapsed_ms: decoded.elapsedMs,
-         superseded: decoded.superseded,
-         warnings: decoded.warnings,
-         near_duplicates: nearDups,
-      };
-   }
-
-   private handleUpdateSection(
-      params: Record<string, unknown>,
-   ): unknown {
-      const oldKbid = (params['kbid'] as string | undefined) ?? '';
-      const updSectionType = (params['sectionType'] ??
-         'text') as string;
-      const updSemanticType =
-         updSectionType === 'text' ||
-         updSectionType === 'code' ||
-         updSectionType === 'image'
-            ? updSectionType
-            : 'text';
-      const updTypeName =
-         updSectionType !== updSemanticType ? updSectionType : null;
-      const input: AddSectionInput = {
-         sectionType: updSemanticType,
-         mimeType: params['mimeType'] as string | undefined,
-         content: (params['content'] as string | undefined) ?? '',
-         title: (params['title'] as string | null) ?? null,
-         description: (params['description'] as string | null) ?? null,
-         docid: (params['docid'] as string | null) ?? null,
-         typeName: updTypeName,
-      };
-      const encoded = encodeUpdateSectionParams(oldKbid, input);
-      const bytes = this.callWasmSync('worker_update_section', encoded);
-      const newKbid = new TextDecoder().decode(bytes);
-      return { kbid: newKbid };
-   }
-
-   private handleReadSections(
-      params: Record<string, unknown>,
-   ): unknown {
-      const kbids = (params['kbids'] ?? []) as string[];
-      const encoded = encodeKbidList(kbids);
-      const bytes = this.callWasmSync('worker_read_sections', encoded);
-      return decodeSectionRecords(bytes);
-   }
-
-   private handleGroupSections(
-      params: Record<string, unknown>,
-   ): unknown {
-      const title = (params['title'] as string | undefined) ?? '';
-      const kbids = (params['kbids'] ?? []) as string[];
-      const docType = (params['docType'] as string | undefined) ?? '';
-      const encoded = encodeGroupParams(title, kbids, docType);
-      const bytes = this.callWasmSync('worker_group_sections', encoded);
-      const docid = new TextDecoder().decode(bytes);
-      return { docid };
-   }
-
-   private handleCompose(params: Record<string, unknown>): unknown {
-      const ids = (params['ids'] ?? []) as string[];
-      const encoded = encodeIdentifierList(ids);
-      const bytes = this.callWasmSync('worker_compose', encoded);
-      const output = decodeComposeOutput(bytes);
-      return {
-         data: output.markdown,
-         total: Number(output.totalChars),
-      };
-   }
-
-   // -- Raw UTF-8 string input methods --
-
-   private handleRemoveSection(
-      params: Record<string, unknown>,
-   ): unknown {
-      const kbid = (params['kbid'] as string | undefined) ?? '';
-      const encoded = new TextEncoder().encode(kbid);
-      const bytes = this.callWasmSync('worker_remove_section', encoded);
-      return { removed: decodeRemoveFlag(bytes) };
-   }
-
-   private handleRetrieveDoc(params: Record<string, unknown>): unknown {
-      const docid = (params['docid'] as string | undefined) ?? '';
-      const encoded = new TextEncoder().encode(docid);
-      const bytes = this.callWasmSync('worker_retrieve_doc', encoded);
-      return decodeDocumentManifest(bytes);
-   }
-
-   private handleRemoveGrouping(
-      params: Record<string, unknown>,
-   ): unknown {
-      const docid = (params['docid'] as string | undefined) ?? '';
-      const encoded = new TextEncoder().encode(docid);
-      this.callWasmSync('worker_remove_grouping', encoded);
-      return { ok: true };
-   }
-
-   private handleInitDirectory(
-      params: Record<string, unknown>,
-   ): unknown {
-      const path =
-         (params['path'] as string | undefined) ?? this.targetDir;
-      const encoded = new TextEncoder().encode(path);
-      this.callWasmSync('worker_init_directory', encoded);
-      return { ok: true };
-   }
-
-   private handleInvalidate(params: Record<string, unknown>): unknown {
-      const kbid = (params['kbid'] as string | undefined) ?? '';
-      const encoded = new TextEncoder().encode(kbid);
-      const fn = this.getExport('worker_invalidate');
-      const ptr = this.wasmAlloc(encoded.length);
-      this.wasmWrite(ptr, encoded);
-      const rc = fn(ptr, encoded.length) as number;
-      this.wasmFree(ptr, encoded.length);
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         throw new IpcError(
-            -32000,
-            new TextDecoder().decode(errBytes) || 'invalidate failed',
-         );
-      }
-      return { ok: true };
-   }
-
-   private handleListByType(params: Record<string, unknown>): unknown {
-      const typeStr =
-         (params['sectionType'] as string | undefined) ?? '';
-      const encoded = encodeTypeFilterParam(typeStr);
-      const bytes = this.callWasmSync('worker_list_by_type', encoded);
-      return decodeSectionRecordList(bytes);
-   }
-
-   private handleListDocsByType(
-      params: Record<string, unknown>,
-   ): unknown {
-      const typeStr = (params['docType'] as string | undefined) ?? '';
-      const encoded = encodeTypeFilterParam(typeStr);
-      const bytes = this.callWasmSync(
-         'worker_list_docs_by_type',
-         encoded,
-      );
-      return decodeDocumentManifestList(bytes);
-   }
-
-   private handleRecall(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 = this.callWasmSync('worker_recall', encoded);
-      return decodeRecallResult(bytes);
-   }
-
-   // -- Zero-arg methods --
-
-   private handleInvalidateAll(): unknown {
-      this.callWasmZeroArg('worker_invalidate_all');
-      return { ok: true };
-   }
-
-   private handleDbStatus(): unknown {
-      this.callWasmZeroArg('worker_status');
-      const bytes = this.readReturnSlot();
-      const text = new TextDecoder().decode(bytes);
-      return decodeKeyValueText(text);
-   }
-
-   private handleIntegrityCheck(): unknown {
-      this.callWasmZeroArg('worker_check_integrity');
-      const bytes = this.readReturnSlot();
-      const text = new TextDecoder().decode(bytes);
-      return decodeKeyValueText(text);
-   }
-
-   private handleGc(): unknown {
-      const start = Date.now();
-      this.callWasmZeroArg('worker_garbage_collect');
-      const bytes = this.readReturnSlot();
-      const text = new TextDecoder().decode(bytes);
-      const kv = decodeKeyValueText(text);
-      const removedCount = Number(kv['removed'] ?? 0);
-      const staleSources = Number(kv['stale_sources'] ?? 0);
-      return {
-         removed_sections: removedCount,
-         removed_bytes: 0,
-         elapsed_ms: Date.now() - start,
-         stale_sources: staleSources,
-      };
-   }
-
-   private handleRebuild(): unknown {
-      const fn = this.getExport('worker_rebuild_indexes');
-      const rc = fn() as number;
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         const errMsg = new TextDecoder().decode(errBytes);
-         throw new IpcError(-32000, errMsg || 'rebuild failed');
-      }
-      const resultBytes = this.readReturnSlot();
-      const reindexed =
-         resultBytes.length >= 4
-            ? new DataView(
-                 resultBytes.buffer,
-                 resultBytes.byteOffset,
-                 resultBytes.byteLength,
-              ).getUint32(0, true)
-            : 0;
-      return { ok: true, sections_reindexed: reindexed };
-   }
-
-   // -- Export (read operation, no lock required) --
-
-   private handleExport(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 = this.callWasmSync('worker_export', encoded);
-      const elapsed = Date.now() - start;
-      const text = new TextDecoder().decode(bytes);
-      const kv = decodeKeyValueText(text);
-      return {
-         path: kv['path'] ?? targetPath,
-         sections_exported: Number(kv['sections_exported'] ?? 0),
-         documents_exported: Number(kv['documents_exported'] ?? 0),
-         elapsed_ms: elapsed,
-      };
-   }
-
-   // -- Near-duplicate detection --
-
-   private scanNearDuplicates(
-      content: string,
-      newKbid: string,
-   ): { kbid: string; similarity: number }[] {
-      const newTerms = this.extractTermSet(content);
-      if (newTerms.size === 0) return [];
-
-      const sectionsDir = join(this.targetDir, 'sections');
-      let shards: string[];
-      try {
-         shards = readdirSync(sectionsDir);
-      } catch {
-         return [];
-      }
-
-      const results: { kbid: string; similarity: number }[] = [];
-      for (const shard of shards) {
-         let files: string[];
-         try {
-            files = readdirSync(join(sectionsDir, shard));
-         } catch {
-            continue;
-         }
-         for (const file of files) {
-            if (!file.endsWith('.section')) continue;
-            const kbid = file.slice(0, -8);
-            if (kbid === newKbid) continue;
-            try {
-               const data = readFileSync(
-                  join(sectionsDir, shard, file),
-                  'utf-8',
-               );
-               const sep = data.indexOf('\n---\n');
-               const body = sep >= 0 ? data.slice(sep + 5) : data;
-               const existing = this.extractTermSet(body);
-               let intersection = 0;
-               for (const t of newTerms) {
-                  if (existing.has(t)) intersection++;
-               }
-               const union =
-                  newTerms.size + existing.size - intersection;
-               const sim = union > 0 ? intersection / union : 0;
-               if (sim >= 0.85) {
-                  results.push({
-                     kbid,
-                     similarity: Math.round(sim * 100) / 100,
-                  });
-               }
-            } catch {
-               continue;
-            }
-         }
-      }
-      return results;
-   }
-
-   private extractTermSet(text: string): Set<string> {
-      return new Set(
-         text
-            .toLowerCase()
-            .split(/\W+/)
-            .filter((w) => w.length > 2),
-      );
-   }
-
-   // -- Single-writer lock --
-
-   /**
-    * Acquires the write lock.
-    *
-    * If the lock is free it is granted immediately. If it is held the
-    * caller is queued and its promise resolves once the lock is
-    * released by the current holder.
-    */
-   private acquireWriteLock(): Promise<void> {
-      if (!this._writeLocked) {
-         this._writeLocked = true;
-         return Promise.resolve();
-      }
-      return new Promise<void>((resolve) => {
-         this._writeQueue.push({ resolve });
-      });
-   }
-
-   /**
-    * Releases the write lock.
-    *
-    * If waiters are queued the next one is granted the lock
-    * immediately. Otherwise the lock is marked free.
-    */
-   private releaseWriteLock(): void {
-      const next = this._writeQueue.shift();
-      if (next !== undefined) {
-         next.resolve();
-      } else {
-         this._writeLocked = false;
-      }
-   }
-
-   // -- WASM lifecycle --
-
-   private initWorkerContext(): void {
-      const pathBytes = new TextEncoder().encode('.');
-      this.callWasmSync('worker_init', pathBytes);
-   }
-
-   /**
-    * Runs a database integrity check immediately after context
-    * initialisation.
-    *
-    * Stores the result in `_integrityOk` and `_integrityErrors`.
-    * Logs a warning to stderr when issues are found so operators
-    * are alerted without aborting the daemon.
-    */
-   private runStartupIntegrityCheck(): void {
-      try {
-         this.callWasmZeroArg('worker_check_integrity');
-         const bytes = this.readReturnSlot();
-         const text = new TextDecoder().decode(bytes);
-         const kv = decodeKeyValueText(text);
-         this._integrityOk = kv['ok'] === 'true';
-         if (!this._integrityOk) {
-            this._integrityErrors = Object.entries(kv)
-               .filter(([k]) => k !== 'ok')
-               .map(([k, v]) => `${k}=${v}`);
-            // eslint-disable-next-line no-console
-            console.error(
-               '[kbdb-worker] startup integrity check failed:',
-               this._integrityErrors.join(', '),
-            );
-         }
-      } catch {
-         this._integrityOk = false;
-         this._integrityErrors = ['integrity_check_failed'];
-         // eslint-disable-next-line no-console
-         console.error(
-            '[kbdb-worker] startup integrity check threw an error',
-         );
-      }
-   }
-
-   // -- WASM bridge primitives --
-
-   private getExport(name: string): WasmFn {
-      if (this._wasmModules === null) {
-         throw new Error('WASM modules not loaded');
-      }
-      const fn = this._wasmModules.kbWorker.exports[name] as
-         | WasmFn
-         | undefined;
-      if (typeof fn !== 'function') {
-         throw new Error(`WASM export not found: ${name}`);
-      }
-      return fn;
-   }
-
-   private wasmAlloc(size: number): number {
-      if (size === 0) return 0;
-      const allocFn = this._wasmModules?.kbWorker.exports[
-         'kbdb_alloc'
-      ] as WasmFn | undefined;
-      if (typeof allocFn !== 'function') return 0;
-      return allocFn(size) as number;
-   }
-
-   private wasmFree(ptr: number, size: number): void {
-      if (ptr === 0 || size === 0) return;
-      const freeFn = this._wasmModules?.kbWorker.exports[
-         'kbdb_free'
-      ] as WasmFn | undefined;
-      if (typeof freeFn === 'function') {
-         freeFn(ptr, size);
-      }
-   }
-
-   private wasmWrite(ptr: number, data: Uint8Array): void {
-      if (data.length === 0) return;
-      const memory = this._wasmModules?.memory;
-      if (!memory) return;
-      const memView = new Uint8Array(memory.buffer);
-      if (ptr + data.length > memView.length) {
-         throw new Error('WASM memory overflow');
-      }
-      memView.set(data, ptr);
-   }
-
-   private readReturnSlot(): Uint8Array {
-      const getPtrFn = this._wasmModules?.kbWorker.exports[
-         'get_return_ptr'
-      ] as WasmFn | undefined;
-      const getLenFn = this._wasmModules?.kbWorker.exports[
-         'get_return_len'
-      ] as WasmFn | undefined;
-      if (
-         typeof getPtrFn !== 'function' ||
-         typeof getLenFn !== 'function'
-      ) {
-         return new Uint8Array(0);
-      }
-      const ptr = getPtrFn() as number;
-      const len = getLenFn() as number;
-      if (ptr === 0 || len === 0) {
-         return new Uint8Array(0);
-      }
-      const memory = this._wasmModules?.memory;
-      if (!memory) return new Uint8Array(0);
-      const data = new Uint8Array(memory.buffer, ptr, len).slice();
-      this.wasmFree(ptr, len);
-      return data;
-   }
-
-   private callWasmSync(
-      exportName: string,
-      input: Uint8Array,
-   ): Uint8Array {
-      const fn = this.getExport(exportName);
-      const ptr = this.wasmAlloc(input.length);
-      this.wasmWrite(ptr, input);
-      const rc = fn(ptr, input.length) as number;
-      this.wasmFree(ptr, input.length);
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         const errMsg = new TextDecoder().decode(errBytes);
-         throw new IpcError(-32000, errMsg || exportName + ' failed');
-      }
-      return this.readReturnSlot();
-   }
-
-   private callWasmZeroArg(exportName: string): void {
-      const fn = this.getExport(exportName);
-      const rc = fn() as number;
-      if (rc === -1) {
-         const errBytes = this.readReturnSlot();
-         const errMsg = new TextDecoder().decode(errBytes);
-         throw new IpcError(-32000, errMsg || exportName + ' failed');
-      }
-   }
-
-   private invokeWasmRaw(
-      exportName: string,
-      input: Uint8Array,
-   ): unknown {
-      return this.callWasmSync(exportName, input);
-   }
-
-   private handleCheckVersion(
-      params: Record<string, unknown>,
-   ): unknown {
-      const targetPath =
-         typeof params.targetPath === 'string'
-            ? params.targetPath
-            : this.targetDir;
-      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,
-      };
-   }
-
-   /** Returns a daemon config value by config method name. */
-   private handleConfigMethod(method: string): 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 this.config[prop];
-   }
-}
-
-// ---------------------------------------------------------------------------
-// Module-private helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Parses the `version` field from a minimal TOML string.
- *
- * Supports only `version = <integer>` syntax. Returns `null` if the
- * field is absent.
- */
-function parseCatalogVersion(text: string): number | null {
-   for (const line of text.split('\n')) {
-      const trimmed = line.trim();
-      if (trimmed.startsWith('#')) continue;
-      const match = /^version\s*=\s*(\d+)/.exec(trimmed);
-      if (match?.[1] !== undefined) {
-         return parseInt(match[1], 10);
-      }
-   }
-   return null;
-}