@dikolab/kbdb 0.4.0 → 0.4.3

package/dist/worker.mjs

@@ -6,14 +6,18 @@ import {
   DEFAULT_TIMEOUT_MS,
   WORKER_TOML_FILENAME,
   computeSha256,
+  configureLog,
   getArgs,
   getIpcPath,
   isRemoteUrl,
   joinPath,
+  log,
+  parseLogLevel,
   parseWorkerToml,
   resolveBaseDir,
+  resolveLogLevel,
   resolveWasmDir
-} from "./chunk-BJPSPNGX.mjs";
+} from "./chunk-BJXEVALU.mjs";
 
 // src/worker.ts
 import { existsSync as existsSync5 } from "node:fs";
@@ -91,6 +95,7 @@ var nullAllocator = { alloc: null };
 function createHostImports(contextPath, memoryRef = nullMemory, fs = nodeFsAdapter, allocator = nullAllocator) {
   function getBuffer() {
     if (!memoryRef.memory) {
+      log("WASM memory not initialized", 3 /* ERROR */);
       throw new Error("WASM memory not initialized");
     }
     return memoryRef.memory.buffer;
@@ -259,6 +264,7 @@ async function loadWasmModules(config, wasmDir2) {
     void 0,
     allocator
   );
+  log("loading WASM module: kb-worker", 0 /* DEBUG */);
   const wkPath = joinPath(wasmDir2, "kb-worker", "kbdb_worker_bg.wasm");
   const wkBytes = await readWasmFile(wkPath, "kb-worker");
   let wkModule;
@@ -282,7 +288,20 @@ async function loadWasmModules(config, wasmDir2) {
     if (typeof fn_ !== "function") return 0;
     return fn_(size);
   };
-  return { memory, kbWorker };
+  const embPath = joinPath(
+    wasmDir2,
+    "default-embedding",
+    "kbdb_default_embedding_bg.wasm"
+  );
+  let embedding;
+  try {
+    const embBytes = await readWasmFile(embPath, "default-embedding");
+    const embModule = await WebAssembly.compile(embBytes);
+    embedding = await WebAssembly.instantiate(embModule, {});
+  } catch {
+  }
+  log("all WASM modules loaded", 1 /* INFO */);
+  return { memory, kbWorker, embedding };
 }
 async function readWasmFile(path, label) {
   try {
@@ -308,7 +327,7 @@ function rethrow(stage, label, err, path) {
   const detail = err instanceof Error ? err.message : String(err);
   const suffix = path ? ` (path: ${path})` : "";
   const message = `failed to ${stage} ${label} WASM: ${detail}${suffix}`;
-  console.error(`kbdb-worker: ${message}`);
+  log(`kbdb-worker: ${message}`, 3 /* ERROR */);
   throw new Error(message, { cause: err });
 }
 
@@ -319,9 +338,14 @@ var KEEPALIVE_MS = 3e4;
 function createIpcServer(socketPath, handler) {
   const server = createServer((socket) => {
     socket.setKeepAlive(true, KEEPALIVE_MS);
+    log("ipc: connection accepted", 0 /* DEBUG */);
     let buffer = "";
     let processingQueue = Promise.resolve();
     socket.on("data", (chunk) => {
+      log(
+        "ipc: data received bytes=" + String(chunk.length),
+        0 /* DEBUG */
+      );
       buffer += chunk.toString();
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
@@ -333,8 +357,9 @@ function createIpcServer(socketPath, handler) {
       }
     });
     socket.on("error", (err) => {
-      console.error(
-        `kbdb-worker: ipc connection error: ${err.message}`
+      log(
+        `kbdb-worker: ipc connection error: ${err.message}`,
+        2 /* WARNING */
       );
     });
   });
@@ -345,8 +370,9 @@ function createIpcServer(socketPath, handler) {
       () => {
         server.removeListener("error", reject);
         server.on("error", (err) => {
-          console.error(
-            `kbdb-worker: ipc server error: ${err.message}`
+          log(
+            `kbdb-worker: ipc server error: ${err.message}`,
+            3 /* ERROR */
           );
         });
         resolve2(server);
@@ -361,8 +387,13 @@ async function handleLine(line, handler, socket) {
   let response;
   try {
     const request = JSON.parse(line);
+    log(
+      "ipc: request parsed method=" + request.method + " id=" + String(request.id),
+      0 /* DEBUG */
+    );
     response = await handler(request);
   } catch {
+    log("ipc: parse error on malformed request", 0 /* DEBUG */);
     response = {
       jsonrpc: "2.0",
       id: 0,
@@ -372,7 +403,12 @@ async function handleLine(line, handler, socket) {
       }
     };
   }
-  socket.write(JSON.stringify(response, bigintReplacer) + "\n");
+  const encoded = JSON.stringify(response, bigintReplacer) + "\n";
+  log(
+    "ipc: response sent bytes=" + String(encoded.length),
+    0 /* DEBUG */
+  );
+  socket.write(encoded);
 }
 
 // src/shared/embedding/classes/null-embedding-provider.class.ts
@@ -416,6 +452,7 @@ var OnnxEmbeddingProvider = class {
    *   dependency not yet wired
    */
   embed(_texts) {
+    log("embed called on OnnxEmbeddingProvider", 0 /* DEBUG */);
     return Promise.reject(
       new Error(
         "ONNX Runtime not available; install onnxruntime-node"
@@ -435,6 +472,7 @@ var OnnxEmbeddingProvider = class {
 // src/shared/embedding/functions/parse-api-embedding-response.function.ts
 function parseApiEmbeddingResponse(raw) {
   if (!isEmbeddingApiResponse(raw)) {
+    log("Unexpected embedding API response shape", 3 /* ERROR */);
     throw new Error("Unexpected embedding API response shape");
   }
   return raw.data.map((entry) => new Float32Array(entry.embedding));
@@ -488,9 +526,9 @@ var ApiEmbeddingProvider = class {
       body: JSON.stringify({ input: texts, model: this.model })
     });
     if (!response.ok) {
-      throw new Error(
-        `Embedding API error: ${String(response.status)}`
-      );
+      const msg = `Embedding API error: ${String(response.status)}`;
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
     const json = await response.json();
     return parseApiEmbeddingResponse(json);
@@ -505,17 +543,89 @@ var ApiEmbeddingProvider = class {
   }
 };
 
+// src/shared/embedding/constants/tfidf-defaults.constant.ts
+var TFIDF_DIMENSIONS = 256;
+var TFIDF_MODEL_NAME = "tfidf-v1";
+
+// src/shared/embedding/classes/tfidf-embedding-provider.class.ts
+var TfidfEmbeddingProvider = class {
+  _alloc;
+  _batch;
+  _retPtr;
+  _memory;
+  /** @param wasm - instantiated `kbdb-default-embedding` WASM module */
+  constructor(wasm) {
+    const ex = wasm.exports;
+    this._memory = ex["memory"];
+    this._alloc = ex["kbdb_alloc"];
+    this._batch = ex["embedding_tfidf_batch"];
+    this._retPtr = ex["get_return_ptr"];
+  }
+  /**
+   * Embeds a batch of texts using TF-IDF computation in WASM.
+   *
+   * @param texts - input strings to embed
+   * @returns one 256-dimension `Float32Array` per input text
+   */
+  embed(texts) {
+    log(
+      "embed called on TfidfEmbeddingProvider: " + texts.length.toString() + " texts",
+      0 /* DEBUG */
+    );
+    const input = texts.join("\n");
+    const encoded = new TextEncoder().encode(input);
+    const ptr = this._alloc(encoded.byteLength);
+    const view = new Uint8Array(this._memory.buffer);
+    view.set(encoded, ptr);
+    this._batch(ptr, encoded.byteLength);
+    const outPtr = this._retPtr();
+    const dv = new DataView(this._memory.buffer);
+    const count = dv.getUint32(outPtr, true);
+    const results = [];
+    let offset = outPtr + 4;
+    for (let i = 0; i < count; i++) {
+      const vec = new Float32Array(TFIDF_DIMENSIONS);
+      for (let d = 0; d < TFIDF_DIMENSIONS; d++) {
+        vec[d] = dv.getFloat32(offset, true);
+        offset += 4;
+      }
+      results.push(vec);
+    }
+    return Promise.resolve(results);
+  }
+  /** Returns 256 -- the fixed dimension count for TF-IDF vectors. */
+  dimensions() {
+    return TFIDF_DIMENSIONS;
+  }
+  /** Returns `'tfidf-v1'`. */
+  modelName() {
+    return TFIDF_MODEL_NAME;
+  }
+};
+
 // src/shared/embedding/functions/create-embedding-provider.function.ts
-function createEmbeddingProvider(config) {
-  if (!config || config.provider === "none") {
+function createEmbeddingProvider(config, wasmInstance) {
+  log("creating embedding provider", 0 /* DEBUG */);
+  if (!config) {
+    if (wasmInstance) {
+      log("using TfidfEmbeddingProvider", 0 /* DEBUG */);
+      return new TfidfEmbeddingProvider(wasmInstance);
+    }
+    log("using NullEmbeddingProvider", 0 /* DEBUG */);
+    return new NullEmbeddingProvider();
+  }
+  if (config.provider === "none") {
+    log("using NullEmbeddingProvider", 0 /* DEBUG */);
     return new NullEmbeddingProvider();
   }
   if (config.provider === "onnx") {
+    log("using OnnxEmbeddingProvider", 0 /* DEBUG */);
     return new OnnxEmbeddingProvider(
       config.model ?? "",
       config.dimensions ?? 0
     );
   }
+  log("using ApiEmbeddingProvider", 0 /* DEBUG */);
   return new ApiEmbeddingProvider(
     config.endpoint ?? "",
     config.dimensions ?? 0,
@@ -552,6 +662,7 @@ function cosineSimilarity(a, b) {
 var HEADER_SIZE = 32;
 var KBID_WIDTH = 64;
 function searchVectors(filePath, queryVector, topN) {
+  log("searching vectors", 0 /* DEBUG */);
   const buf = readFileSync4(filePath);
   if (buf.length < HEADER_SIZE) {
     return [];
@@ -607,6 +718,7 @@ var IpcError = class extends Error {
 
 // src/shared/worker-daemon/functions/handle-hybrid-search.function.ts
 async function fuseSearchResults(lexical, algo, query, provider, targetDir) {
+  log("handling hybrid search", 0 /* DEBUG */);
   if (algo === "lexical") {
     return {
       ...lexical,
@@ -633,10 +745,9 @@ async function fuseSearchResults(lexical, algo, query, provider, targetDir) {
 }
 function assertProvider(provider) {
   if (!provider || provider.dimensions() === 0) {
-    throw new IpcError(
-      -32e3,
-      "embedding provider not configured; set [embedding] in worker.toml"
-    );
+    const embeddingErrMsg = "embedding provider not configured; set [embedding] in worker.toml";
+    log(embeddingErrMsg, 3 /* ERROR */);
+    throw new IpcError(-32e3, embeddingErrMsg);
   }
 }
 function buildVectorOnly(vectorResults, lexical) {
@@ -739,6 +850,7 @@ function writeRecord(buf, offset, entry, dimensions, encoder3) {
   }
 }
 function buildVectorIndex(dirPath, modelName, dimensions, entries) {
+  log("building vector index", 0 /* DEBUG */);
   const encoder3 = new TextEncoder();
   const modelBytes = encoder3.encode(modelName);
   const modelLen = modelBytes.length;
@@ -797,6 +909,7 @@ function collectSections(sectionsDir) {
   return result;
 }
 async function rebuildVectors(targetDir, provider) {
+  log("rebuilding vectors", 0 /* DEBUG */);
   if (provider.dimensions() === 0) {
     return 0;
   }
@@ -820,6 +933,10 @@ async function rebuildVectors(targetDir, provider) {
     provider.dimensions(),
     entries
   );
+  log(
+    "rebuilt " + sections.length.toString() + " vectors",
+    1 /* INFO */
+  );
   return sections.length;
 }
 
@@ -1677,6 +1794,7 @@ var WorkerDaemon = class {
   _idleAt = 0;
   _idleTimer = null;
   _server = null;
+  _sockets = /* @__PURE__ */ new Set();
   _wasmDir;
   /** Queue of waiters for the single-writer lock. */
   _writeQueue = [];
@@ -1713,6 +1831,10 @@ var WorkerDaemon = class {
    */
   checkPreconditions() {
     if (!existsSync4(this.targetDir)) {
+      log(
+        `database directory not found: ${this.targetDir}`,
+        3 /* ERROR */
+      );
       throw new Error(
         `database directory not found: ${this.targetDir}`
       );
@@ -1723,9 +1845,9 @@ var WorkerDaemon = class {
         constants.R_OK | constants.W_OK
       );
     } catch {
-      throw new Error(
-        `cannot access database directory: ${this.targetDir} -- permission denied`
-      );
+      const msg = `cannot access database directory: ${this.targetDir} -- permission denied`;
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
     this.checkCatalogVersion();
   }
@@ -1741,18 +1863,34 @@ var WorkerDaemon = class {
    *   be created
    */
   async start() {
+    log(
+      "start: loading wasm modules ctx=" + this.ctx,
+      0 /* DEBUG */
+    );
     const wasmModules = await loadWasmModules(
       this.config,
       this._wasmDir
     );
     this._wasmModules = wasmModules;
+    log("start: wasm modules loaded", 0 /* DEBUG */);
     this._embeddingProvider = createEmbeddingProvider(
-      this.config.embedding
+      this.config.embedding,
+      wasmModules.embedding
+    );
+    log(
+      "start: embedding provider created embedding=" + (this.config.embedding?.provider ?? "none"),
+      0 /* DEBUG */
     );
     this.initWorkerContext();
+    log("start: worker context initialized", 0 /* DEBUG */);
     this.runStartupIntegrityCheck();
+    log(
+      "start: integrity check done ok=" + String(this._integrityOk),
+      0 /* DEBUG */
+    );
     const ipcPath = getIpcPath(this.ctx);
     if (existsSync4(ipcPath)) {
+      log("start: removing stale socket " + ipcPath, 0 /* DEBUG */);
       try {
         unlinkSync2(ipcPath);
       } catch {
@@ -1760,18 +1898,34 @@ var WorkerDaemon = class {
     }
     const handler = (req) => this.handleRequest(req);
     this._server = await createIpcServer(ipcPath, handler);
-    this._server.on("connection", () => {
+    log("IPC server listening on " + ipcPath, 1 /* INFO */);
+    this._server.on("connection", (socket) => {
+      this._sockets.add(socket);
       this.incrementConnections();
       this.resetIdleTimer();
-    });
-    this._server.on("close", () => {
-      this.decrementConnections();
-      if (this._connectionCount === 0) {
-        this.resetIdleTimer();
-      }
+      log(
+        "client connected (count: " + String(this._connectionCount) + ")",
+        0 /* DEBUG */
+      );
+      socket.on("close", () => {
+        this._sockets.delete(socket);
+        this.decrementConnections();
+        log(
+          "client disconnected (count: " + String(this._connectionCount) + ")",
+          0 /* DEBUG */
+        );
+        if (this._connectionCount === 0) {
+          this.resetIdleTimer();
+        }
+      });
     });
     const pidPath = join6(tmpdir(), `kbdb-${this.ctx}.pid`);
     writeFileSync3(pidPath, process.pid.toString());
+    log(
+      "start: pid file written pid=" + String(process.pid),
+      0 /* DEBUG */
+    );
+    log("start: daemon ready ctx=" + this.ctx, 0 /* DEBUG */);
     this.resetIdleTimer();
   }
   /**
@@ -1782,23 +1936,36 @@ var WorkerDaemon = class {
    * the process.
    */
   stop() {
+    log(
+      "stop: entry sockets=" + String(this._sockets.size),
+      0 /* DEBUG */
+    );
+    log("shutting down", 1 /* INFO */);
     if (this._idleTimer !== null) {
       clearTimeout(this._idleTimer);
       this._idleTimer = null;
     }
+    for (const socket of this._sockets) {
+      socket.destroy();
+    }
+    this._sockets.clear();
     if (this._server !== null) {
       this._server.close();
       this._server = null;
+      log("stop: server closed", 0 /* DEBUG */);
     }
     this._wasmModules = null;
+    log("stop: wasm resources released", 0 /* DEBUG */);
     const pidPath = join6(tmpdir(), `kbdb-${this.ctx}.pid`);
     try {
       unlinkSync2(pidPath);
+      log("stop: pid file removed", 0 /* DEBUG */);
     } catch {
     }
     const ipcPath = getIpcPath(this.ctx);
     try {
       unlinkSync2(ipcPath);
+      log("stop: socket file removed", 0 /* DEBUG */);
     } catch {
     }
     const crashPath = join6(tmpdir(), `kbdb-${this.ctx}.crash`);
@@ -1806,6 +1973,7 @@ var WorkerDaemon = class {
       unlinkSync2(crashPath);
     } catch {
     }
+    log("stop: daemon exiting", 0 /* DEBUG */);
     process.exit(0);
   }
   /**
@@ -1819,8 +1987,16 @@ var WorkerDaemon = class {
    * @returns the JSON-RPC response
    */
   async handleRequest(request) {
+    log(
+      "handle-request: method=" + request.method + " id=" + String(request.id),
+      0 /* DEBUG */
+    );
     const params = request.params;
     if (params === void 0 || params.ctx !== this.ctx) {
+      log(
+        "handle-request: context mismatch id=" + String(request.id),
+        0 /* DEBUG */
+      );
       return this.errorResponse(
         request.id,
         -32001,
@@ -1831,6 +2007,10 @@ var WorkerDaemon = class {
     try {
       const result = await this.dispatch(request.method, params);
       this._idleAt = Math.floor(Date.now() / 1e3);
+      log(
+        "handle-request: success method=" + request.method + " id=" + String(request.id),
+        0 /* DEBUG */
+      );
       return {
         jsonrpc: "2.0",
         id: request.id,
@@ -1839,6 +2019,10 @@ var WorkerDaemon = class {
     } catch (err) {
       this._idleAt = Math.floor(Date.now() / 1e3);
       if (err instanceof IpcError2) {
+        log(
+          "handle-request: ipc error method=" + request.method + " id=" + String(request.id) + " code=" + String(err.code),
+          0 /* DEBUG */
+        );
         return this.errorResponse(
           request.id,
           err.code,
@@ -1846,6 +2030,10 @@ var WorkerDaemon = class {
         );
       }
       const message = err instanceof Error ? err.message : String(err);
+      log(
+        "handle-request: error method=" + request.method + " id=" + String(request.id),
+        0 /* DEBUG */
+      );
       return this.errorResponse(request.id, -32e3, message);
     }
   }
@@ -1889,7 +2077,15 @@ var WorkerDaemon = class {
       clearTimeout(this._idleTimer);
     }
     if (this._connectionCount === 0) {
+      log(
+        "idle timer started (" + String(this.config.timeoutMs) + "ms)",
+        0 /* DEBUG */
+      );
       this._idleTimer = setTimeout(() => {
+        log(
+          "idle timer fired: shutting down ctx=" + this.ctx,
+          0 /* DEBUG */
+        );
         this.stop();
       }, this.config.timeoutMs);
     }
@@ -1901,25 +2097,25 @@ var WorkerDaemon = class {
     try {
       text = readFileSync6(catalogPath, "utf-8");
     } catch {
-      throw new Error(
-        `cannot read database directory: ${this.targetDir} -- permission denied`
-      );
+      const msg = `cannot read database directory: ${this.targetDir} -- permission denied`;
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
     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"
-      );
+      const msg = "database version 0 requires migration to version " + String(DB_FORMAT_VERSION) + " -- run `kbdb --migrate` before starting the daemon";
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
     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"
-      );
+      const msg = "database version " + String(version) + " is newer than kbdb version " + String(DB_FORMAT_VERSION) + " -- upgrade kbdb to open this database";
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
     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"
-      );
+      const msg = "database version " + String(version) + " requires migration to version " + String(DB_FORMAT_VERSION) + " -- run `kbdb --migrate` before starting the daemon";
+      log(msg, 3 /* ERROR */);
+      throw new Error(msg);
     }
   }
   /** Builds a JSON-RPC error response. */
@@ -2435,8 +2631,13 @@ var WorkerDaemon = class {
   acquireWriteLock() {
     if (!this._writeLocked) {
       this._writeLocked = true;
+      log("write-lock: acquired", 0 /* DEBUG */);
       return Promise.resolve();
     }
+    log(
+      "write-lock: queued depth=" + String(this._writeQueue.length + 1),
+      0 /* DEBUG */
+    );
     return new Promise((resolve2) => {
       this._writeQueue.push({ resolve: resolve2 });
     });
@@ -2450,9 +2651,14 @@ var WorkerDaemon = class {
   releaseWriteLock() {
     const next = this._writeQueue.shift();
     if (next !== void 0) {
+      log(
+        "write-lock: released to next waiter depth=" + String(this._writeQueue.length),
+        0 /* DEBUG */
+      );
       next.resolve();
     } else {
       this._writeLocked = false;
+      log("write-lock: released", 0 /* DEBUG */);
     }
   }
   // -- WASM lifecycle --
@@ -2477,26 +2683,29 @@ var WorkerDaemon = class {
       this._integrityOk = kv["ok"] === "true";
       if (!this._integrityOk) {
         this._integrityErrors = Object.entries(kv).filter(([k]) => k !== "ok").map(([k, v]) => `${k}=${v}`);
-        console.error(
-          "[kbdb-worker] startup integrity check failed:",
-          this._integrityErrors.join(", ")
+        log(
+          "[kbdb-worker] startup integrity check failed: " + this._integrityErrors.join(", "),
+          2 /* WARNING */
         );
       }
     } catch {
       this._integrityOk = false;
       this._integrityErrors = ["integrity_check_failed"];
-      console.error(
-        "[kbdb-worker] startup integrity check threw an error"
+      log(
+        "[kbdb-worker] startup integrity check threw an error",
+        2 /* WARNING */
       );
     }
   }
   // -- WASM bridge primitives --
   getExport(name) {
     if (this._wasmModules === null) {
+      log("WASM modules not loaded", 3 /* ERROR */);
       throw new Error("WASM modules not loaded");
     }
     const fn = this._wasmModules.kbWorker.exports[name];
     if (typeof fn !== "function") {
+      log(`WASM export not found: ${name}`, 3 /* ERROR */);
       throw new Error(`WASM export not found: ${name}`);
     }
     return fn;
@@ -2520,6 +2729,7 @@ var WorkerDaemon = class {
     if (!memory) return;
     const memView = new Uint8Array(memory.buffer);
     if (ptr + data.length > memView.length) {
+      log("WASM memory overflow", 3 /* ERROR */);
       throw new Error("WASM memory overflow");
     }
     memView.set(data, ptr);
@@ -2631,9 +2841,18 @@ function parseCatalogVersion(text) {
 
 // src/shared/worker-daemon/functions/start-daemon.function.ts
 async function startDaemon(contextPath, wasmDir2) {
+  log(
+    "start-daemon: entry contextPath=" + contextPath,
+    0 /* DEBUG */
+  );
   const config = readConfig(contextPath);
+  log(
+    "start-daemon: config loaded timeoutMs=" + String(config.timeoutMs) + " embedding=" + (config.embedding?.provider ?? "none"),
+    0 /* DEBUG */
+  );
   const hash = await computeSha256(contextPath);
   const contextId = hash.slice(0, 16);
+  log("start-daemon: contextId=" + contextId, 0 /* DEBUG */);
   const daemon = new WorkerDaemon(
     contextId,
     contextPath,
@@ -2644,22 +2863,30 @@ async function startDaemon(contextPath, wasmDir2) {
     daemon.checkPreconditions();
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`kbdb-worker: ${message}`);
+    log(`kbdb-worker: ${message}`, 3 /* ERROR */);
     writeCrashLog(contextId, message);
     process.exit(1);
   }
+  log("preconditions passed", 0 /* DEBUG */);
   try {
     await daemon.start();
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`kbdb-worker: ${message}`);
+    log(`kbdb-worker: ${message}`, 3 /* ERROR */);
     writeCrashLog(contextId, message);
     process.exit(1);
   }
+  log("daemon started", 1 /* INFO */);
+  log(
+    "start-daemon: registering SIGTERM/SIGINT handlers",
+    0 /* DEBUG */
+  );
   process.on("SIGTERM", () => {
+    log("start-daemon: SIGTERM received", 0 /* DEBUG */);
     daemon.stop();
   });
   process.on("SIGINT", () => {
+    log("start-daemon: SIGINT received", 0 /* DEBUG */);
     daemon.stop();
   });
 }
@@ -2677,11 +2904,11 @@ function writeCrashLog(contextId, message) {
 
 // src/shared/worker-daemon/functions/run-worker.function.ts
 import { resolve } from "node:path";
-async function runWorker(argv, deps) {
-  const contextPath = argv[0];
+async function runWorker(argv2, deps) {
+  const { contextPath, logLevel } = parseWorkerArgs(argv2);
   if (!contextPath) {
     return {
-      error: "usage: kbdb-worker <context-path>",
+      error: "usage: kbdb-worker <context-path> [--log-level <level>]",
       exitCode: 1
     };
   }
@@ -2693,27 +2920,52 @@ async function runWorker(argv, deps) {
     };
   }
   await deps.startDaemon(resolved, deps.wasmDir);
-  return { exitCode: 0 };
+  return { exitCode: 0, logLevel };
+}
+function parseWorkerArgs(argv2) {
+  let contextPath;
+  let logLevel;
+  for (let i = 0; i < argv2.length; i++) {
+    if (argv2[i] === "--log-level" && argv2[i + 1]) {
+      logLevel = parseLogLevel(argv2[++i]);
+    } else if (!contextPath) {
+      contextPath = argv2[i];
+    }
+  }
+  return { contextPath, logLevel };
 }
 
 // src/worker.ts
 var baseDir = resolveBaseDir(import.meta.url, import.meta.dirname);
 var wasmDir = resolveWasmDir(baseDir.scriptDir);
+var argv = getArgs();
+var cliLogLevel = extractLogLevel(argv);
+configureLog({ level: resolveLogLevel(cliLogLevel) });
+log("daemon process starting", 0 /* DEBUG */);
 async function main() {
-  const result = await runWorker(getArgs(), {
+  const result = await runWorker(argv, {
     existsSync: existsSync5,
     startDaemon,
     wasmDir
   });
   if (result.error) {
-    console.error(result.error);
+    log(result.error, 3 /* ERROR */);
   }
   if (result.exitCode !== 0) {
     process.exitCode = result.exitCode;
   }
 }
 main().catch((err) => {
-  console.error(err);
+  const msg = err instanceof Error ? err.message : String(err);
+  log(msg, 3 /* ERROR */);
   process.exitCode = 1;
 });
+function extractLogLevel(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--log-level" && args[i + 1]) {
+      return parseLogLevel(args[i + 1]);
+    }
+  }
+  return void 0;
+}
 //# sourceMappingURL=worker.mjs.map