kirograph 0.12.1

package/dist/vectors/pglite-index.js

@@ -0,0 +1,194 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pglite_index_exports = {};
+__export(pglite_index_exports, {
+  PGliteIndex: () => PGliteIndex
+});
+module.exports = __toCommonJS(pglite_index_exports);
+var path = __toESM(require("path"));
+var import_errors = require("../errors");
+const DEFAULT_DIM = 768;
+const DB_DIR = "pglite";
+const VECTOR_WEIGHT = 0.7;
+const FTS_WEIGHT = 0.3;
+class PGliteIndex {
+  constructor(kirographDir, dim = DEFAULT_DIM) {
+    this.kirographDir = kirographDir;
+    this.dim = dim;
+    this.db = null;
+    this._available = false;
+    this.dbPath = path.join(kirographDir, DB_DIR);
+  }
+  isAvailable() {
+    return this._available;
+  }
+  /**
+   * Load @electric-sql/pglite, open the file-persisted database, enable pgvector,
+   * and apply the schema (idempotent — safe to call on every startup).
+   * Silent no-op when the optional dep is missing.
+   */
+  async initialize() {
+    if (this._available) return;
+    let PGlite;
+    let vector;
+    try {
+      const mod = require("@electric-sql/pglite");
+      PGlite = mod.PGlite;
+    } catch {
+      (0, import_errors.logDebug)("PGliteIndex: @electric-sql/pglite not installed \u2014 PGlite engine unavailable");
+      return;
+    }
+    try {
+      const vectorMod = require("@electric-sql/pglite/vector");
+      vector = vectorMod.vector ?? vectorMod;
+    } catch {
+      (0, import_errors.logDebug)("PGliteIndex: @electric-sql/pglite/vector not available \u2014 PGlite engine unavailable");
+      return;
+    }
+    try {
+      this.db = new PGlite(`file://${this.dbPath}`, { extensions: { vector } });
+      await this.db.waitReady;
+      await this.db.exec(`
+        CREATE EXTENSION IF NOT EXISTS vector;
+
+        CREATE TABLE IF NOT EXISTS kg_nodes (
+          node_id   TEXT PRIMARY KEY,
+          name      TEXT NOT NULL DEFAULT '',
+          kind      TEXT NOT NULL DEFAULT '',
+          file_path TEXT NOT NULL DEFAULT '',
+          signature TEXT NOT NULL DEFAULT '',
+          embedding vector(${this.dim}) NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS kg_nodes_hnsw_idx
+          ON kg_nodes USING hnsw (embedding vector_cosine_ops);
+
+        CREATE INDEX IF NOT EXISTS kg_nodes_name_idx
+          ON kg_nodes USING GIN (to_tsvector('english', name || ' ' || signature));
+      `);
+      this._available = true;
+      (0, import_errors.logDebug)("PGliteIndex: ready", { path: this.dbPath, dim: this.dim });
+    } catch (err) {
+      (0, import_errors.logError)("PGliteIndex: initialization failed", { error: String(err) });
+    }
+  }
+  /**
+   * Insert or update a node's record using PostgreSQL's native ON CONFLICT upsert.
+   */
+  async upsert(node, embedding) {
+    if (!this._available || !this.db) return;
+    try {
+      await this.db.query(
+        `INSERT INTO kg_nodes (node_id, name, kind, file_path, signature, embedding)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         ON CONFLICT (node_id) DO UPDATE SET
+           name      = EXCLUDED.name,
+           kind      = EXCLUDED.kind,
+           file_path = EXCLUDED.file_path,
+           signature = EXCLUDED.signature,
+           embedding = EXCLUDED.embedding`,
+        [
+          node.id,
+          node.name,
+          node.kind,
+          node.filePath,
+          node.signature ?? "",
+          `[${Array.from(embedding).join(",")}]`
+        ]
+      );
+    } catch (err) {
+      (0, import_errors.logWarn)("PGliteIndex: upsert failed", { nodeId: node.id, error: String(err) });
+    }
+  }
+  /**
+   * Remove a node's record from the index.
+   */
+  async delete(nodeId) {
+    if (!this._available || !this.db) return;
+    try {
+      await this.db.query("DELETE FROM kg_nodes WHERE node_id = $1", [nodeId]);
+    } catch (err) {
+      (0, import_errors.logWarn)("PGliteIndex: delete failed", { nodeId, error: String(err) });
+    }
+  }
+  /**
+   * Hybrid search: combines pgvector cosine distance with PostgreSQL full-text
+   * ranking in a single SQL query. Returns node IDs ordered by combined score.
+   *
+   * Score = VECTOR_WEIGHT × (1 - cosine_distance) + FTS_WEIGHT × ts_rank
+   */
+  async search(queryText, queryVec, topN = 10) {
+    if (!this._available || !this.db) return [];
+    try {
+      const vecLiteral = `[${Array.from(queryVec).join(",")}]`;
+      const result = await this.db.query(
+        `SELECT node_id,
+                (${VECTOR_WEIGHT} * (1 - (embedding <=> $1::vector))
+                 + ${FTS_WEIGHT}  * ts_rank(
+                     to_tsvector('english', name || ' ' || signature),
+                     plainto_tsquery('english', $2)
+                   )
+                ) AS score
+         FROM kg_nodes
+         ORDER BY score DESC
+         LIMIT $3`,
+        [vecLiteral, queryText, topN]
+      );
+      return (result.rows ?? []).map((row) => row.node_id);
+    } catch (err) {
+      (0, import_errors.logWarn)("PGliteIndex: search failed", { error: String(err) });
+      return [];
+    }
+  }
+  /** Return all node IDs currently stored in the index. */
+  async getEmbeddedNodeIds() {
+    if (!this._available || !this.db) return [];
+    try {
+      const result = await this.db.query("SELECT node_id FROM kg_nodes");
+      return (result.rows ?? []).map((row) => row.node_id);
+    } catch {
+      return [];
+    }
+  }
+  /** Number of documents currently in the index. */
+  async count() {
+    if (!this._available || !this.db) return 0;
+    try {
+      const result = await this.db.query("SELECT COUNT(*) AS count FROM kg_nodes");
+      return parseInt(result.rows[0]?.count ?? "0", 10);
+    } catch {
+      return 0;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PGliteIndex
+});
+//# sourceMappingURL=pglite-index.js.map

package/dist/vectors/pglite-index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/vectors/pglite-index.ts"],
+  "sourcesContent": ["/**\n * KiroGraph PGLite Index\n *\n * Hybrid search (full-text + exact vector) backed by @electric-sql/pglite + pgvector.\n * The database is persisted to .kirograph/pglite/ (PGLite's WAL-based file storage).\n *\n * Opt-in: set config.semanticEngine = 'pglite'\n * Required optional dependency (not installed by default):\n *   npm install @electric-sql/pglite\n *\n * Key advantages over other engines:\n *   - Pure WASM, no native compilation required (unlike sqlite-vec)\n *   - Exact nearest-neighbour search (deterministic, unlike ANN approximation)\n *   - Native SQL upsert via ON CONFLICT \u2014 no remove+insert dance (unlike Orama)\n *   - HNSW index for fast approximate search when the table grows large\n *   - Full-text search via PostgreSQL tsvector + ts_rank combined in one query\n */\n\nimport * as path from 'path';\nimport { logDebug, logWarn, logError } from '../errors';\nimport type { Node } from '../types';\n\n// \u2500\u2500 Constants \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst DEFAULT_DIM = 768;\nconst DB_DIR      = 'pglite';\n\n// Weight for vector score vs full-text score in hybrid ranking (must sum to 1.0)\nconst VECTOR_WEIGHT = 0.7;\nconst FTS_WEIGHT    = 0.3;\n\n// \u2500\u2500 PGliteIndex \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport class PGliteIndex {\n  private db: any = null;\n  private _available = false;\n  private dbPath: string;\n\n  constructor(\n    private readonly kirographDir: string,\n    private readonly dim = DEFAULT_DIM,\n  ) {\n    this.dbPath = path.join(kirographDir, DB_DIR);\n  }\n\n  isAvailable(): boolean {\n    return this._available;\n  }\n\n  /**\n   * Load @electric-sql/pglite, open the file-persisted database, enable pgvector,\n   * and apply the schema (idempotent \u2014 safe to call on every startup).\n   * Silent no-op when the optional dep is missing.\n   */\n  async initialize(): Promise<void> {\n    if (this._available) return;\n\n    let PGlite: any;\n    let vector: any;\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-require-imports\n      const mod = require('@electric-sql/pglite');\n      PGlite = mod.PGlite;\n    } catch {\n      logDebug('PGliteIndex: @electric-sql/pglite not installed \u2014 PGlite engine unavailable');\n      return;\n    }\n\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-require-imports\n      const vectorMod = require('@electric-sql/pglite/vector');\n      vector = vectorMod.vector ?? vectorMod;\n    } catch {\n      logDebug('PGliteIndex: @electric-sql/pglite/vector not available \u2014 PGlite engine unavailable');\n      return;\n    }\n\n    try {\n      this.db = new PGlite(`file://${this.dbPath}`, { extensions: { vector } });\n      await this.db.waitReady;\n\n      await this.db.exec(`\n        CREATE EXTENSION IF NOT EXISTS vector;\n\n        CREATE TABLE IF NOT EXISTS kg_nodes (\n          node_id   TEXT PRIMARY KEY,\n          name      TEXT NOT NULL DEFAULT '',\n          kind      TEXT NOT NULL DEFAULT '',\n          file_path TEXT NOT NULL DEFAULT '',\n          signature TEXT NOT NULL DEFAULT '',\n          embedding vector(${this.dim}) NOT NULL\n        );\n\n        CREATE INDEX IF NOT EXISTS kg_nodes_hnsw_idx\n          ON kg_nodes USING hnsw (embedding vector_cosine_ops);\n\n        CREATE INDEX IF NOT EXISTS kg_nodes_name_idx\n          ON kg_nodes USING GIN (to_tsvector('english', name || ' ' || signature));\n      `);\n\n      this._available = true;\n      logDebug('PGliteIndex: ready', { path: this.dbPath, dim: this.dim });\n    } catch (err) {\n      logError('PGliteIndex: initialization failed', { error: String(err) });\n    }\n  }\n\n  /**\n   * Insert or update a node's record using PostgreSQL's native ON CONFLICT upsert.\n   */\n  async upsert(node: Node, embedding: Float32Array): Promise<void> {\n    if (!this._available || !this.db) return;\n\n    try {\n      await this.db.query(\n        `INSERT INTO kg_nodes (node_id, name, kind, file_path, signature, embedding)\n         VALUES ($1, $2, $3, $4, $5, $6)\n         ON CONFLICT (node_id) DO UPDATE SET\n           name      = EXCLUDED.name,\n           kind      = EXCLUDED.kind,\n           file_path = EXCLUDED.file_path,\n           signature = EXCLUDED.signature,\n           embedding = EXCLUDED.embedding`,\n        [\n          node.id,\n          node.name,\n          node.kind,\n          node.filePath,\n          node.signature ?? '',\n          `[${Array.from(embedding).join(',')}]`,\n        ],\n      );\n    } catch (err) {\n      logWarn('PGliteIndex: upsert failed', { nodeId: node.id, error: String(err) });\n    }\n  }\n\n  /**\n   * Remove a node's record from the index.\n   */\n  async delete(nodeId: string): Promise<void> {\n    if (!this._available || !this.db) return;\n\n    try {\n      await this.db.query('DELETE FROM kg_nodes WHERE node_id = $1', [nodeId]);\n    } catch (err) {\n      logWarn('PGliteIndex: delete failed', { nodeId, error: String(err) });\n    }\n  }\n\n  /**\n   * Hybrid search: combines pgvector cosine distance with PostgreSQL full-text\n   * ranking in a single SQL query. Returns node IDs ordered by combined score.\n   *\n   * Score = VECTOR_WEIGHT \u00D7 (1 - cosine_distance) + FTS_WEIGHT \u00D7 ts_rank\n   */\n  async search(queryText: string, queryVec: Float32Array, topN = 10): Promise<string[]> {\n    if (!this._available || !this.db) return [];\n\n    try {\n      const vecLiteral = `[${Array.from(queryVec).join(',')}]`;\n      const result = await this.db.query(\n        `SELECT node_id,\n                (${VECTOR_WEIGHT} * (1 - (embedding <=> $1::vector))\n                 + ${FTS_WEIGHT}  * ts_rank(\n                     to_tsvector('english', name || ' ' || signature),\n                     plainto_tsquery('english', $2)\n                   )\n                ) AS score\n         FROM kg_nodes\n         ORDER BY score DESC\n         LIMIT $3`,\n        [vecLiteral, queryText, topN],\n      );\n\n      return (result.rows ?? []).map((row: any) => row.node_id as string);\n    } catch (err) {\n      logWarn('PGliteIndex: search failed', { error: String(err) });\n      return [];\n    }\n  }\n\n  /** Return all node IDs currently stored in the index. */\n  async getEmbeddedNodeIds(): Promise<string[]> {\n    if (!this._available || !this.db) return [];\n    try {\n      const result = await this.db.query('SELECT node_id FROM kg_nodes');\n      return (result.rows ?? []).map((row: any) => row.node_id as string);\n    } catch {\n      return [];\n    }\n  }\n\n  /** Number of documents currently in the index. */\n  async count(): Promise<number> {\n    if (!this._available || !this.db) return 0;\n    try {\n      const result = await this.db.query('SELECT COUNT(*) AS count FROM kg_nodes');\n      return parseInt(result.rows[0]?.count ?? '0', 10);\n    } catch {\n      return 0;\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/vectors/qdrant-index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * KiroGraph Qdrant Index
+ *
+ * ANN vector search backed by Qdrant running in embedded mode.
+ * The engine spawns the Qdrant binary as a managed child process, persisting
+ * data to .kirograph/qdrant/ via QDRANT__STORAGE__STORAGE_PATH.
+ *
+ * Opt-in: set config.semanticEngine = 'qdrant'
+ * Required optional dependency (not installed by default):
+ *   npm install qdrant-local
+ *
+ * Uses @qdrant/qdrant-js (QdrantClient) for the REST API — available as a
+ * transitive dependency of qdrant-local.
+ *
+ * Key characteristics:
+ *   - Full Qdrant feature set: filtering, payload indexing, HNSW ANN search
+ *   - Data persisted to disk across restarts
+ *   - Async startup check via /readyz (no blocking sleep)
+ *   - Cosine distance metric
+ *   - Node IDs stored in payload; deterministic UUIDs used as Qdrant point IDs
+ */
+import type { Node } from '../types';
+export declare const DASHBOARD_SUBDIR = "qdrant/dashboard";
+export declare class QdrantIndex {
+    private readonly kirographDir;
+    private readonly dim;
+    private client;
+    private child;
+    private _available;
+    private _ownedProcess;
+    private storagePath;
+    private stateFile;
+    constructor(kirographDir: string, dim?: number);
+    isAvailable(): boolean;
+    private readState;
+    private writeState;
+    private clearState;
+    private isProcessAlive;
+    /** The HTTP port of the running server, or null if not available. */
+    getPort(): number | null;
+    /**
+     * Locate the Qdrant binary (via qdrant-local), spawn it with a project-scoped
+     * storage path, wait until /readyz responds, then ensure the collection exists.
+     * Silent no-op when qdrant-local is not installed.
+     */
+    initialize(): Promise<void>;
+    private ensureCollection;
+    /**
+     * Upsert a node's embedding. Qdrant's upsert is idempotent — the same point
+     * ID is overwritten if it already exists.
+     */
+    upsert(node: Node, embedding: Float32Array): Promise<void>;
+    /**
+     * Remove a point from the collection.
+     */
+    delete(nodeId: string): Promise<void>;
+    /**
+     * ANN vector search. Returns node IDs ordered by cosine similarity (descending).
+     */
+    search(queryVec: Float32Array, topN?: number): Promise<string[]>;
+    /**
+     * Return all node IDs currently stored in the collection (paginated scroll).
+     */
+    getEmbeddedNodeIds(): Promise<string[]>;
+    /** Disconnect the client. The Qdrant server keeps running as a daemon. */
+    close(): void;
+    /** Number of points currently in the collection. */
+    count(): Promise<number>;
+}
+//# sourceMappingURL=qdrant-index.d.ts.map

package/dist/vectors/qdrant-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-index.d.ts","sourceRoot":"","sources":["../../src/vectors/qdrant-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAUrC,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAgDnD,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,SAAS,CAAgB;gBAGd,YAAY,EAAE,MAAM,EACpB,GAAG,SAAc;IAMpC,WAAW,IAAI,OAAO;IAEtB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IAGlB,OAAO,CAAC,UAAU;IAGlB,OAAO,CAAC,cAAc;IAItB,qEAAqE;IACrE,OAAO,IAAI,MAAM,GAAG,IAAI;IAUxB;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAiGnB,gBAAgB;IAU9B;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhE;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3C;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBlE;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B7C,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAMb,oDAAoD;IAC9C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAS/B"}

package/dist/vectors/qdrant-index.js

@@ -0,0 +1,364 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var qdrant_index_exports = {};
+__export(qdrant_index_exports, {
+  DASHBOARD_SUBDIR: () => DASHBOARD_SUBDIR,
+  QdrantIndex: () => QdrantIndex
+});
+module.exports = __toCommonJS(qdrant_index_exports);
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+var http = __toESM(require("http"));
+var fs = __toESM(require("fs"));
+var import_errors = require("../errors");
+const DEFAULT_DIM = 768;
+const STORAGE_DIR = "qdrant";
+const COLLECTION = "kg_nodes";
+const READYZ_TIMEOUT_MS = 1e4;
+const READYZ_POLL_MS = 100;
+const SERVER_STATE_FILE = "qdrant-server.json";
+const DASHBOARD_SUBDIR = "qdrant/dashboard";
+function toUuid(nodeId) {
+  const h = crypto.createHash("md5").update(nodeId).digest("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer().listen(0, "127.0.0.1", () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+    srv.on("error", reject);
+  });
+}
+function waitReady(port, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    function check() {
+      const req = http.get(`http://127.0.0.1:${port}/readyz`, (res) => {
+        if (res.statusCode === 200) return resolve();
+        scheduleRetry();
+      });
+      req.on("error", scheduleRetry);
+      req.setTimeout(200, () => {
+        req.destroy();
+        scheduleRetry();
+      });
+    }
+    function scheduleRetry() {
+      if (Date.now() >= deadline) return reject(new Error("Qdrant readyz timeout"));
+      setTimeout(check, READYZ_POLL_MS);
+    }
+    check();
+  });
+}
+class QdrantIndex {
+  constructor(kirographDir, dim = DEFAULT_DIM) {
+    this.kirographDir = kirographDir;
+    this.dim = dim;
+    this.client = null;
+    this.child = null;
+    this._available = false;
+    this._ownedProcess = false;
+    this.storagePath = path.join(kirographDir, STORAGE_DIR);
+    this.stateFile = path.join(kirographDir, SERVER_STATE_FILE);
+  }
+  isAvailable() {
+    return this._available;
+  }
+  readState() {
+    try {
+      return JSON.parse(fs.readFileSync(this.stateFile, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  writeState(s) {
+    try {
+      fs.writeFileSync(this.stateFile, JSON.stringify(s));
+    } catch {
+    }
+  }
+  clearState() {
+    try {
+      fs.unlinkSync(this.stateFile);
+    } catch {
+    }
+  }
+  isProcessAlive(pid) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** The HTTP port of the running server, or null if not available. */
+  getPort() {
+    if (this._available) {
+      const s2 = this.readState();
+      return s2?.port ?? null;
+    }
+    const s = this.readState();
+    if (s && this.isProcessAlive(s.pid)) return s.port;
+    return null;
+  }
+  /**
+   * Locate the Qdrant binary (via qdrant-local), spawn it with a project-scoped
+   * storage path, wait until /readyz responds, then ensure the collection exists.
+   * Silent no-op when qdrant-local is not installed.
+   */
+  async initialize() {
+    if (this._available) return;
+    let binPath;
+    try {
+      const pkgPath = require.resolve("qdrant-local/package.json");
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      const { directory, name } = pkg.qdrantBinary;
+      const exeName = ["win32", "cygwin"].includes(process.platform) ? `${name}.exe` : name;
+      binPath = path.join(path.dirname(pkgPath), directory, exeName);
+      if (!fs.existsSync(binPath)) {
+        (0, import_errors.logDebug)("QdrantIndex: qdrant binary not found \u2014 run: npm install qdrant-local");
+        return;
+      }
+    } catch {
+      (0, import_errors.logDebug)("QdrantIndex: qdrant-local not installed \u2014 Qdrant engine unavailable");
+      return;
+    }
+    let QdrantClient;
+    try {
+      QdrantClient = require("@qdrant/qdrant-js").QdrantClient;
+    } catch {
+      (0, import_errors.logDebug)("QdrantIndex: @qdrant/qdrant-js not available \u2014 Qdrant engine unavailable");
+      return;
+    }
+    const saved = this.readState();
+    if (saved) {
+      if (this.isProcessAlive(saved.pid)) {
+        try {
+          await waitReady(saved.port, 3e3);
+          this.client = new QdrantClient({ host: "127.0.0.1", port: saved.port, checkCompatibility: false });
+          await this.ensureCollection();
+          this._available = true;
+          this._ownedProcess = false;
+          (0, import_errors.logDebug)("QdrantIndex: reused running server", { pid: saved.pid, port: saved.port });
+          return;
+        } catch {
+          try {
+            process.kill(saved.pid, "SIGKILL");
+          } catch {
+          }
+          await new Promise((r) => setTimeout(r, 300));
+        }
+      }
+      this.clearState();
+    }
+    try {
+      fs.mkdirSync(this.storagePath, { recursive: true });
+      const port = await getFreePort();
+      const dashboardDir = path.join(this.kirographDir, DASHBOARD_SUBDIR);
+      const staticEnv = fs.existsSync(dashboardDir) ? { QDRANT__SERVICE__STATIC_CONTENT_DIR: dashboardDir } : {};
+      const { spawn } = require("child_process");
+      this.child = spawn(binPath, [], {
+        stdio: "ignore",
+        env: {
+          ...process.env,
+          QDRANT__SERVICE__HTTP_PORT: String(port),
+          QDRANT__STORAGE__STORAGE_PATH: this.storagePath,
+          QDRANT__LOG_LEVEL: "WARN",
+          ...staticEnv
+        }
+      });
+      this.child.unref();
+      await waitReady(port, READYZ_TIMEOUT_MS);
+      this.writeState({ pid: this.child.pid, port });
+      this.client = new QdrantClient({ host: "127.0.0.1", port, checkCompatibility: false });
+      await this.ensureCollection();
+      this._available = true;
+      this._ownedProcess = true;
+      (0, import_errors.logDebug)("QdrantIndex: ready", { storagePath: this.storagePath, port, dim: this.dim });
+    } catch (err) {
+      (0, import_errors.logError)("QdrantIndex: initialization failed", { error: String(err) });
+    }
+  }
+  async ensureCollection() {
+    const existsResult = await this.client.collectionExists(COLLECTION);
+    const exists = typeof existsResult === "object" ? existsResult.exists : existsResult;
+    if (!exists) {
+      await this.client.createCollection(COLLECTION, {
+        vectors: { size: this.dim, distance: "Cosine" }
+      });
+    }
+  }
+  /**
+   * Upsert a node's embedding with retry logic.
+   * Qdrant's upsert is idempotent — the same point ID is overwritten if it already exists.
+   * Retries up to 3 times with exponential backoff to handle transient connection failures.
+   */
+  async upsert(node, embedding) {
+    if (!this._available || !this.client) return;
+    const point = {
+      id: toUuid(node.id),
+      vector: Array.from(embedding),
+      payload: {
+        node_id: node.id,
+        name: node.name,
+        kind: node.kind,
+        file_path: node.filePath,
+        signature: node.signature ?? ""
+      }
+    };
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        await this.client.upsert(COLLECTION, { points: [point] });
+        return;
+      } catch (err) {
+        if (attempt < 2) {
+          await new Promise((r) => setTimeout(r, 100 * (attempt + 1)));
+        } else {
+          (0, import_errors.logWarn)("QdrantIndex: upsert failed", { nodeId: node.id, error: String(err) });
+        }
+      }
+    }
+  }
+  /**
+   * Batch upsert multiple nodes' embeddings in a single HTTP request.
+   * Much more efficient than individual upserts for bulk indexing.
+   * Retries up to 3 times with exponential backoff.
+   */
+  async bulkUpsert(nodes, embeddings) {
+    if (!this._available || !this.client) return;
+    if (nodes.length === 0) return;
+    const points = nodes.map((node, i) => ({
+      id: toUuid(node.id),
+      vector: Array.from(embeddings[i]),
+      payload: {
+        node_id: node.id,
+        name: node.name,
+        kind: node.kind,
+        file_path: node.filePath,
+        signature: node.signature ?? ""
+      }
+    }));
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        await this.client.upsert(COLLECTION, { points });
+        return;
+      } catch (err) {
+        if (attempt < 2) {
+          await new Promise((r) => setTimeout(r, 200 * (attempt + 1)));
+        } else {
+          (0, import_errors.logWarn)("QdrantIndex: bulk upsert failed", { count: nodes.length, error: String(err) });
+        }
+      }
+    }
+  }
+  /**
+   * Remove a point from the collection with retry logic.
+   */
+  async delete(nodeId) {
+    if (!this._available || !this.client) return;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        await this.client.delete(COLLECTION, { points: [toUuid(nodeId)] });
+        return;
+      } catch (err) {
+        if (attempt < 2) {
+          await new Promise((r) => setTimeout(r, 100 * (attempt + 1)));
+        } else {
+          (0, import_errors.logWarn)("QdrantIndex: delete failed", { nodeId, error: String(err) });
+        }
+      }
+    }
+  }
+  /**
+   * ANN vector search. Returns node IDs ordered by cosine similarity (descending).
+   */
+  async search(queryVec, topN = 10) {
+    if (!this._available || !this.client) return [];
+    try {
+      const results = await this.client.search(COLLECTION, {
+        vector: Array.from(queryVec),
+        limit: topN,
+        with_payload: ["node_id"]
+      });
+      return results.map((r) => r.payload.node_id);
+    } catch (err) {
+      (0, import_errors.logWarn)("QdrantIndex: search failed", { error: String(err) });
+      return [];
+    }
+  }
+  /**
+   * Return all node IDs currently stored in the collection (paginated scroll).
+   */
+  async getEmbeddedNodeIds() {
+    if (!this._available || !this.client) return [];
+    const ids = [];
+    let offset = null;
+    try {
+      do {
+        const page = await this.client.scroll(COLLECTION, {
+          with_payload: ["node_id"],
+          with_vector: false,
+          limit: 1e3,
+          ...offset !== null ? { offset } : {}
+        });
+        for (const pt of page.points) {
+          if (pt.payload?.node_id) ids.push(pt.payload.node_id);
+        }
+        offset = page.next_page_offset ?? null;
+      } while (offset !== null);
+    } catch {
+      return ids;
+    }
+    return ids;
+  }
+  /** Disconnect the client. The Qdrant server keeps running as a daemon. */
+  close() {
+    this._available = false;
+    this.child = null;
+    this.client = null;
+  }
+  /** Number of points currently in the collection. */
+  async count() {
+    if (!this._available || !this.client) return 0;
+    try {
+      const result = await this.client.count(COLLECTION, { exact: true });
+      return result.count;
+    } catch {
+      return 0;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DASHBOARD_SUBDIR,
+  QdrantIndex
+});
+//# sourceMappingURL=qdrant-index.js.map