kirograph 0.19.0 → 0.20.1

package/dist/vectors/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * KiroGraph Vector Manager
  *
- * Semantic search using nomic-ai/nomic-embed-text-v1.5 via @xenova/transformers.
+ * Semantic search via configurable local embedding models using @huggingface/transformers v3.
  * Mirrors CodeGraph src/vectors/ (embedder.ts + manager.ts) adapted for KiroGraph:
  *   - Cache dir: ~/.kirograph/models/ (not ~/.codegraph/models/)
  *   - Embeddings stored in the `vectors` SQLite table
@@ -35,7 +35,7 @@ export declare class VectorManager {
      * Fails silently so callers can continue without semantic search.
      * When config.useVecIndex is true, also initializes the sqlite-vec ANN index.
      */
-    initialize(): Promise<void>;
+    initialize(onProgress?: (file: string, loaded: number, total: number, done: boolean) => void): Promise<void>;
     /**
      * Embed a single node and persist to the vectors table.
      * Skips silently when disabled; logs on failure without throwing.
@@ -52,7 +52,15 @@ export declare class VectorManager {
     deleteEmbeddings(nodeIds: string[]): Promise<void>;
     /**
      * Embed all eligible nodes in the database that don't yet have embeddings.
-     * Processes in batches of BATCH_SIZE.
+     * Streams nodes in pages to avoid loading the entire node set into memory —
+     * critical for large codebases (100K+ symbols) where a single getAllNodes()
+     * call can exhaust the Node.js heap or the WASM linear memory.
+     *
+     * Uses dynamic batch sizing: starts at BATCH_SIZE, halves on OOM errors,
+     * and recovers back to full size after successful batches.
+     *
+     * Emits a pre-flight warning via onProgress when the embeddable node count
+     * exceeds LARGE_CODEBASE_THRESHOLD so the CLI can surface it to the user.
      */
     embedAll(onProgress?: (current: number, total: number) => void): Promise<number>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAuEpD,qBAAa,aAAa;IAYtB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAb/B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,eAAe,CAAuB;gBAG3B,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,eAAe,EACvB,WAAW,CAAC,EAAE,MAAM,YAAA;IAGvC,aAAa,IAAI,OAAO;IAIxB,2FAA2F;IAC3F,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+HjC;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B1C,sFAAsF;IAChF,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAUtC;;;;;OAKG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD;;;OAGG;IACG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAyEtF;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAmDvD,iEAAiE;IACjE,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAiFpD,qBAAa,aAAa;IAYtB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAb/B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,eAAe,CAAuB;gBAG3B,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,eAAe,EACvB,WAAW,CAAC,EAAE,MAAM,YAAA;IAGvC,aAAa,IAAI,OAAO;IAIxB,2FAA2F;IAC3F,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACG,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA8IlH;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B1C,sFAAsF;IAChF,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAUtC;;;;;OAKG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IA6JtF;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAmDvD,iEAAiE;IACjE,KAAK,IAAI,IAAI;CAId"}

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

@@ -46,12 +46,19 @@ export declare class QdrantIndex {
     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 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.
      */
     upsert(node: Node, embedding: Float32Array): Promise<void>;
     /**
-     * Remove a point from the collection.
+     * 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.
+     */
+    bulkUpsert(nodes: Node[], embeddings: Float32Array[]): Promise<void>;
+    /**
+     * Remove a point from the collection with retry logic.
      */
     delete(nodeId: string): Promise<void>;
     /**

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

@@ -1 +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"}
+{"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;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BhE;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B1E;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB3C;;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/turboquant-index.js

@@ -0,0 +1,261 @@
+"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 turboquant_index_exports = {};
+__export(turboquant_index_exports, {
+  TurboQuantIndex: () => TurboQuantIndex,
+  readTurboQuantStats: () => readTurboQuantStats,
+  writeTurboQuantStats: () => writeTurboQuantStats
+});
+module.exports = __toCommonJS(turboquant_index_exports);
+var path = __toESM(require("path"));
+var fs = __toESM(require("fs"));
+var import_errors = require("../errors");
+const STATS_FILE = "turboquant-stats.json";
+function readTurboQuantStats(kirographDir) {
+  try {
+    const p = path.join(kirographDir, STATS_FILE);
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeTurboQuantStats(kirographDir, patch) {
+  const p = path.join(kirographDir, STATS_FILE);
+  const tmp = p + ".tmp";
+  try {
+    const existing = readTurboQuantStats(kirographDir) ?? {
+      count: 0,
+      dim: 768,
+      bits: 3,
+      compressionRatio: 1,
+      actualBytes: 0,
+      rawBytes: 0,
+      savedBytes: 0,
+      memEnabled: false,
+      memCount: 0,
+      memActualBytes: 0,
+      memRawBytes: 0,
+      docsEnabled: false,
+      docsCount: 0,
+      docsActualBytes: 0,
+      docsRawBytes: 0,
+      updatedAt: 0
+    };
+    const updated = { ...existing, ...patch, updatedAt: Math.floor(Date.now() / 1e3) };
+    fs.writeFileSync(tmp, JSON.stringify(updated, null, 2));
+    fs.renameSync(tmp, p);
+  } catch (err) {
+    (0, import_errors.logWarn)("TurboQuantIndex: failed to write stats file", { error: String(err) });
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+    }
+  }
+}
+class TurboQuantIndex {
+  constructor(kirographDir, binName, dim, bits = 3) {
+    this.kirographDir = kirographDir;
+    this.binName = binName;
+    this.dim = dim;
+    this.bits = bits;
+    this.index = null;
+    this._available = false;
+  }
+  isAvailable() {
+    return this._available;
+  }
+  /**
+   * Load turboquant-js and restore index from disk if the .bin file exists.
+   * Silent no-op when the optional dependency is missing.
+   */
+  async initialize() {
+    if (this._available) return;
+    let TQModule;
+    try {
+      TQModule = require("turboquant-js");
+    } catch {
+      (0, import_errors.logDebug)("TurboQuantIndex: turboquant-js not installed \u2014 turboquant engine unavailable");
+      return;
+    }
+    const VectorIndex = TQModule?.VectorIndex ?? TQModule?.default?.VectorIndex ?? (typeof TQModule === "function" ? TQModule : null);
+    if (!VectorIndex || typeof VectorIndex !== "function") {
+      (0, import_errors.logWarn)("TurboQuantIndex: unrecognised turboquant-js module shape \u2014 turboquant engine unavailable");
+      return;
+    }
+    const binPath = path.join(this.kirographDir, this.binName);
+    try {
+      if (fs.existsSync(binPath) && typeof VectorIndex.fromBuffer === "function") {
+        const nodeBuf = fs.readFileSync(binPath);
+        const ab = nodeBuf.buffer.slice(nodeBuf.byteOffset, nodeBuf.byteOffset + nodeBuf.byteLength);
+        this.index = VectorIndex.fromBuffer(ab, { dimension: this.dim, bits: this.bits });
+        (0, import_errors.logDebug)("TurboQuantIndex: restored from disk", { binPath });
+      } else {
+        this.index = new VectorIndex({ dimension: this.dim, bits: this.bits });
+        (0, import_errors.logDebug)("TurboQuantIndex: new index", { dim: this.dim, bits: this.bits });
+      }
+      this._available = true;
+    } catch (err) {
+      (0, import_errors.logError)("TurboQuantIndex: initialization failed", { error: String(err) });
+      this._available = false;
+      this.index = null;
+    }
+  }
+  /** Add or update an embedding (turboquant-js compresses at index time). */
+  upsert(id, vec) {
+    if (!this._available || !this.index) return;
+    try {
+      this.index.add(id, vec);
+    } catch (err) {
+      (0, import_errors.logWarn)("TurboQuantIndex: upsert failed", { id, error: String(err) });
+    }
+  }
+  /** Remove an entry from the index (permanent via turboquant-js remove()). */
+  delete(id) {
+    if (!this._available || !this.index) return;
+    try {
+      this.index.remove(id);
+    } catch (err) {
+      (0, import_errors.logWarn)("TurboQuantIndex: delete failed", { id, error: String(err) });
+    }
+  }
+  /** ANN search: returns IDs sorted by descending similarity. */
+  search(queryVec, topN = 10) {
+    return this.searchWithScores(queryVec, topN).map((r) => r.id);
+  }
+  /**
+   * ANN search: returns [{id, score}] sorted by descending similarity.
+   * Used by MemoryVectorManager and DocsVectorManager to preserve scores for
+   * hybrid merge.
+   */
+  searchWithScores(queryVec, topN = 10) {
+    if (!this._available || !this.index) return [];
+    try {
+      const raw = this.index.search(queryVec, topN);
+      return this._normaliseSearchResults(raw).slice(0, topN);
+    } catch (err) {
+      (0, import_errors.logWarn)("TurboQuantIndex: search failed", { error: String(err) });
+      return [];
+    }
+  }
+  /**
+   * Persist the compressed index to disk atomically.
+   * Called once at the end of `kirograph index` — not on every upsert.
+   */
+  async save() {
+    if (!this._available || !this.index) return;
+    if (typeof this.index.toBuffer !== "function") {
+      (0, import_errors.logDebug)("TurboQuantIndex: toBuffer() not available \u2014 index not persisted");
+      return;
+    }
+    const binPath = path.join(this.kirographDir, this.binName);
+    const tmp = binPath + ".tmp";
+    try {
+      const raw = this.index.toBuffer();
+      const buf = raw instanceof ArrayBuffer ? Buffer.from(raw) : raw;
+      fs.writeFileSync(tmp, buf);
+      fs.renameSync(tmp, binPath);
+      (0, import_errors.logDebug)("TurboQuantIndex: saved", { binPath, bytes: buf.length });
+    } catch (err) {
+      (0, import_errors.logWarn)("TurboQuantIndex: save failed", { error: String(err) });
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Memory usage stats from the compressed index.
+   * Falls back to a formula-based estimate when memoryUsage is unavailable.
+   */
+  memoryStats() {
+    if (this._available && this.index?.memoryUsage) {
+      return this.index.memoryUsage;
+    }
+    const n = this.count();
+    const rawBytes = n * this.dim * 4;
+    const actualBytes = Math.ceil(n * this.dim * this.bits / 8);
+    return {
+      totalBits: actualBytes * 8,
+      bitsPerVector: this.bits * this.dim,
+      compressionRatio: actualBytes > 0 ? rawBytes / actualBytes : 1,
+      actualBytes
+    };
+  }
+  count() {
+    if (!this._available || !this.index) return 0;
+    try {
+      if (this.index.idToIndex instanceof Map) return this.index.idToIndex.size;
+      if (typeof this.index.size === "number") return this.index.size;
+    } catch {
+    }
+    return 0;
+  }
+  /** All IDs currently in the index. */
+  getEmbeddedIds() {
+    if (!this._available || !this.index) return [];
+    try {
+      if (this.index.idToIndex instanceof Map) {
+        return [...this.index.idToIndex.keys()];
+      }
+    } catch {
+    }
+    return [];
+  }
+  close() {
+    this.index = null;
+    this._available = false;
+  }
+  // ── Private ────────────────────────────────────────────────────────────────
+  _normaliseSearchResults(raw) {
+    if (!Array.isArray(raw)) return [];
+    return raw.map((item, rank) => {
+      if (item && typeof item === "object" && !Array.isArray(item)) {
+        const obj = item;
+        const id = obj["id"] ?? obj["key"] ?? "";
+        const score = obj["score"] ?? obj["similarity"] ?? obj["distance"] ?? 1 - rank / raw.length;
+        return { id, score: typeof score === "number" ? score : 1 - rank / raw.length };
+      }
+      if (Array.isArray(item) && item.length >= 2) {
+        return { id: String(item[0]), score: typeof item[1] === "number" ? item[1] : 1 - rank / raw.length };
+      }
+      if (typeof item === "string") {
+        return { id: item, score: 1 - rank / raw.length };
+      }
+      return null;
+    }).filter((r) => r !== null && r.id.length > 0);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TurboQuantIndex,
+  readTurboQuantStats,
+  writeTurboQuantStats
+});
+//# sourceMappingURL=turboquant-index.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/vectors/turboquant-index.ts"],
+  "sourcesContent": ["/**\n * KiroGraph TurboQuant ANN Index\n *\n * Wraps turboquant-js (Google TurboQuant algorithm) as a drop-in ANN index.\n * Compresses embeddings at index time via Walsh-Hadamard rotation + Lloyd-Max\n * scalar quantization \u2014 zero native dependencies.\n *\n * Optional dep: npm install turboquant-js\n *\n * Algorithm: https://research.google/blog/turboquant-redefining-ai-efficiency-with-extreme-compression/\n * Implementation: https://github.com/danilodevhub/turboquant-js (by Danilo Dev)\n *\n * Falls back silently to cosine if turboquant-js is not installed.\n *\n * Compression at 3 bits (default):\n *   768-dim Float32 (3,072 bytes) \u2192 ~120 bytes (\u224825\u00D7 smaller)\n *   10K vectors: ~30 MB raw \u2192 ~1.2 MB compressed\n */\n\nimport * as path from 'path';\nimport * as fs from 'fs';\nimport { logDebug, logWarn, logError } from '../errors';\n\n// \u2500\u2500 TurboQuantStats \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 interface TurboQuantStats {\n  count: number;\n  dim: number;\n  bits: number;\n  compressionRatio: number;\n  actualBytes: number;\n  rawBytes: number;\n  savedBytes: number;\n  memEnabled: boolean;\n  memCount: number;\n  memActualBytes: number;\n  memRawBytes: number;\n  docsEnabled: boolean;\n  docsCount: number;\n  docsActualBytes: number;\n  docsRawBytes: number;\n  updatedAt: number;\n}\n\nconst STATS_FILE = 'turboquant-stats.json';\n\nexport function readTurboQuantStats(kirographDir: string): TurboQuantStats | null {\n  try {\n    const p = path.join(kirographDir, STATS_FILE);\n    if (!fs.existsSync(p)) return null;\n    return JSON.parse(fs.readFileSync(p, 'utf8')) as TurboQuantStats;\n  } catch {\n    return null;\n  }\n}\n\nexport function writeTurboQuantStats(kirographDir: string, patch: Partial<TurboQuantStats>): void {\n  const p = path.join(kirographDir, STATS_FILE);\n  const tmp = p + '.tmp';\n  try {\n    const existing = readTurboQuantStats(kirographDir) ?? {\n      count: 0, dim: 768, bits: 3,\n      compressionRatio: 1, actualBytes: 0, rawBytes: 0, savedBytes: 0,\n      memEnabled: false, memCount: 0, memActualBytes: 0, memRawBytes: 0,\n      docsEnabled: false, docsCount: 0, docsActualBytes: 0, docsRawBytes: 0,\n      updatedAt: 0,\n    };\n    const updated: TurboQuantStats = { ...existing, ...patch, updatedAt: Math.floor(Date.now() / 1000) };\n    fs.writeFileSync(tmp, JSON.stringify(updated, null, 2));\n    fs.renameSync(tmp, p);\n  } catch (err) {\n    logWarn('TurboQuantIndex: failed to write stats file', { error: String(err) });\n    try { fs.unlinkSync(tmp); } catch { /* ignore */ }\n  }\n}\n\n// \u2500\u2500 TurboQuantIndex \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 TurboQuantIndex {\n  private index: any = null;\n  private _available = false;\n\n  constructor(\n    private readonly kirographDir: string,\n    private readonly binName: string,   // 'turboquant.bin' | 'turboquant-mem.bin' | 'turboquant-doc.bin'\n    private readonly dim: number,\n    private readonly bits: number = 3,\n  ) {}\n\n  isAvailable(): boolean {\n    return this._available;\n  }\n\n  /**\n   * Load turboquant-js and restore index from disk if the .bin file exists.\n   * Silent no-op when the optional dependency is missing.\n   */\n  async initialize(): Promise<void> {\n    if (this._available) return;\n\n    let TQModule: any;\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-require-imports\n      TQModule = require('turboquant-js');\n    } catch {\n      logDebug('TurboQuantIndex: turboquant-js not installed \u2014 turboquant engine unavailable');\n      return;\n    }\n\n    // Handle various export shapes (default export, named export, CJS wrapper)\n    const VectorIndex =\n      TQModule?.VectorIndex ??\n      TQModule?.default?.VectorIndex ??\n      (typeof TQModule === 'function' ? TQModule : null);\n\n    if (!VectorIndex || typeof VectorIndex !== 'function') {\n      logWarn('TurboQuantIndex: unrecognised turboquant-js module shape \u2014 turboquant engine unavailable');\n      return;\n    }\n\n    const binPath = path.join(this.kirographDir, this.binName);\n\n    try {\n      if (fs.existsSync(binPath) && typeof VectorIndex.fromBuffer === 'function') {\n        const nodeBuf = fs.readFileSync(binPath);\n        // fromBuffer() requires a pure ArrayBuffer, not a Node Buffer/Uint8Array\n        const ab = nodeBuf.buffer.slice(nodeBuf.byteOffset, nodeBuf.byteOffset + nodeBuf.byteLength);\n        this.index = VectorIndex.fromBuffer(ab, { dimension: this.dim, bits: this.bits });\n        logDebug('TurboQuantIndex: restored from disk', { binPath });\n      } else {\n        this.index = new VectorIndex({ dimension: this.dim, bits: this.bits });\n        logDebug('TurboQuantIndex: new index', { dim: this.dim, bits: this.bits });\n      }\n      this._available = true;\n    } catch (err) {\n      logError('TurboQuantIndex: initialization failed', { error: String(err) });\n      this._available = false;\n      this.index = null;\n    }\n  }\n\n  /** Add or update an embedding (turboquant-js compresses at index time). */\n  upsert(id: string, vec: Float32Array): void {\n    if (!this._available || !this.index) return;\n    try {\n      this.index.add(id, vec);\n    } catch (err) {\n      logWarn('TurboQuantIndex: upsert failed', { id, error: String(err) });\n    }\n  }\n\n  /** Remove an entry from the index (permanent via turboquant-js remove()). */\n  delete(id: string): void {\n    if (!this._available || !this.index) return;\n    try {\n      this.index.remove(id);\n    } catch (err) {\n      logWarn('TurboQuantIndex: delete failed', { id, error: String(err) });\n    }\n  }\n\n  /** ANN search: returns IDs sorted by descending similarity. */\n  search(queryVec: Float32Array, topN = 10): string[] {\n    return this.searchWithScores(queryVec, topN).map(r => r.id);\n  }\n\n  /**\n   * ANN search: returns [{id, score}] sorted by descending similarity.\n   * Used by MemoryVectorManager and DocsVectorManager to preserve scores for\n   * hybrid merge.\n   */\n  searchWithScores(queryVec: Float32Array, topN = 10): Array<{ id: string; score: number }> {\n    if (!this._available || !this.index) return [];\n    try {\n      const raw: unknown = this.index.search(queryVec, topN);\n      return this._normaliseSearchResults(raw).slice(0, topN);\n    } catch (err) {\n      logWarn('TurboQuantIndex: search failed', { error: String(err) });\n      return [];\n    }\n  }\n\n  /**\n   * Persist the compressed index to disk atomically.\n   * Called once at the end of `kirograph index` \u2014 not on every upsert.\n   */\n  async save(): Promise<void> {\n    if (!this._available || !this.index) return;\n    if (typeof this.index.toBuffer !== 'function') {\n      logDebug('TurboQuantIndex: toBuffer() not available \u2014 index not persisted');\n      return;\n    }\n\n    const binPath = path.join(this.kirographDir, this.binName);\n    const tmp = binPath + '.tmp';\n    try {\n      const raw = this.index.toBuffer();\n      // toBuffer() may return ArrayBuffer \u2014 Node fs requires Buffer/TypedArray\n      const buf = raw instanceof ArrayBuffer ? Buffer.from(raw) : (raw as Buffer);\n      fs.writeFileSync(tmp, buf);\n      fs.renameSync(tmp, binPath);\n      logDebug('TurboQuantIndex: saved', { binPath, bytes: buf.length });\n    } catch (err) {\n      logWarn('TurboQuantIndex: save failed', { error: String(err) });\n      try { fs.unlinkSync(tmp); } catch { /* ignore */ }\n    }\n  }\n\n  /**\n   * Memory usage stats from the compressed index.\n   * Falls back to a formula-based estimate when memoryUsage is unavailable.\n   */\n  memoryStats(): { totalBits: number; bitsPerVector: number; compressionRatio: number; actualBytes: number } {\n    if (this._available && this.index?.memoryUsage) {\n      return this.index.memoryUsage as { totalBits: number; bitsPerVector: number; compressionRatio: number; actualBytes: number };\n    }\n    const n = this.count();\n    const rawBytes = n * this.dim * 4;\n    const actualBytes = Math.ceil(n * this.dim * this.bits / 8);\n    return {\n      totalBits: actualBytes * 8,\n      bitsPerVector: this.bits * this.dim,\n      compressionRatio: actualBytes > 0 ? rawBytes / actualBytes : 1,\n      actualBytes,\n    };\n  }\n\n  count(): number {\n    if (!this._available || !this.index) return 0;\n    try {\n      // idToIndex is an internal Map \u2014 reliable count that survives remove()\n      if (this.index.idToIndex instanceof Map) return this.index.idToIndex.size;\n      if (typeof this.index.size === 'number') return this.index.size;\n    } catch { /* ignore */ }\n    return 0;\n  }\n\n  /** All IDs currently in the index. */\n  getEmbeddedIds(): string[] {\n    if (!this._available || !this.index) return [];\n    try {\n      if (this.index.idToIndex instanceof Map) {\n        return [...this.index.idToIndex.keys()];\n      }\n    } catch { /* ignore */ }\n    return [];\n  }\n\n  close(): void {\n    this.index = null;\n    this._available = false;\n  }\n\n  // \u2500\u2500 Private \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\n  private _normaliseSearchResults(raw: unknown): Array<{ id: string; score: number }> {\n    if (!Array.isArray(raw)) return [];\n\n    return raw\n      .map((item: unknown, rank: number) => {\n        if (item && typeof item === 'object' && !Array.isArray(item)) {\n          const obj = item as Record<string, unknown>;\n          const id = (obj['id'] ?? obj['key'] ?? '') as string;\n          const score = (obj['score'] ?? obj['similarity'] ?? obj['distance'] ?? (1 - rank / raw.length)) as number;\n          return { id, score: typeof score === 'number' ? score : 1 - rank / raw.length };\n        }\n        if (Array.isArray(item) && item.length >= 2) {\n          return { id: String(item[0]), score: typeof item[1] === 'number' ? item[1] : 1 - rank / raw.length };\n        }\n        if (typeof item === 'string') {\n          return { id: item, score: 1 - rank / raw.length };\n        }\n        return null;\n      })\n      .filter((r): r is { id: string; score: number } => r !== null && r.id.length > 0);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -1 +1 @@
-{"version":3,"file":"typesense-index.d.ts","sourceRoot":"","sources":["../../src/vectors/typesense-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAyLrC,qBAAa,cAAc;IAUvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAW;gBAGT,YAAY,EAAE,MAAM,EACpB,GAAG,SAAc;IAMpC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;IAItB,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAkInB,gBAAgB;IAiB9B;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1E;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3C;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0BlE;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAwB7C,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAY9B;;;OAGG;IACH,KAAK,IAAI,IAAI;CAKd"}
+{"version":3,"file":"typesense-index.d.ts","sourceRoot":"","sources":["../../src/vectors/typesense-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AA4HrC,qBAAa,cAAc;IAUvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAW;gBAGT,YAAY,EAAE,MAAM,EACpB,GAAG,SAAc;IAMpC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;IAItB,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAkInB,gBAAgB;IAiB9B;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1E;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3C;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0BlE;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAwB7C,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAY9B;;;OAGG;IACH,KAAK,IAAI,IAAI;CAKd"}

package/dist/watchmen/index.js

@@ -0,0 +1,83 @@
+"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 watchmen_exports = {};
+__export(watchmen_exports, {
+  WatchmenChecker: () => WatchmenChecker
+});
+module.exports = __toCommonJS(watchmen_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+const TARGET_ENTRIES = [
+  { detect: (root) => fs.existsSync(path.join(root, ".kiro")), target: ".kiro/steering/kirograph-watchmen.md" },
+  { detect: (root) => fs.existsSync(path.join(root, "CLAUDE.md")), target: "CLAUDE.md" },
+  { detect: (root) => fs.existsSync(path.join(root, "GEMINI.md")), target: "GEMINI.md" },
+  { detect: (root) => fs.existsSync(path.join(root, "CONVENTIONS.md")), target: "CONVENTIONS.md" },
+  { detect: (root) => fs.existsSync(path.join(root, "augment-guidelines.md")), target: "augment-guidelines.md" },
+  { detect: (root) => fs.existsSync(path.join(root, "AGENTS.md")), target: "AGENTS.md" }
+];
+class WatchmenChecker {
+  constructor(threshold) {
+    this.threshold = threshold;
+  }
+  shouldSynthesize(memDb) {
+    const pendingCount = memDb.countSinceLastSummary();
+    return { ready: pendingCount >= this.threshold, pendingCount };
+  }
+  buildReadyResponse(id, pendingCount, projectRoot) {
+    const targetFiles = this.resolveTargetFiles(projectRoot);
+    const hasKiro = fs.existsSync(path.join(projectRoot, ".kiro"));
+    const skillTargetDir = hasKiro ? ".kiro/steering" : void 0;
+    const skillInstructions = skillTargetDir ? `For each recurring procedure (appearing in 3+ observations): write a separate \`.kiro/steering/watchmen-<slug>.md\` file with \`inclusion: manual\` frontmatter, a short title, trigger phrases (when to load this skill), and numbered steps. Use \`watchmen-\` prefix so auto-generated skills are distinguishable. Delete any \`.kiro/steering/watchmen-*.md\` files from previous runs that no longer reflect current patterns.` : `Embed a ## Recurring Procedures section in each file in targetFiles listing each identified recurring procedure with trigger context and numbered steps.`;
+    return {
+      id,
+      watchmenReady: true,
+      pendingCount,
+      message: `${pendingCount} new observations since last synthesis. Synthesize now: (1) call kirograph_mem_search for each kind (decision, error, pattern, architecture, note) with limit 20, (2) write or update the workspace brief (## KiroGraph Watchmen section) in each file in targetFiles covering decisions, errors, patterns, and architecture notes, (3) identify recurring procedures: ${skillInstructions} (4) store a kind='summary' observation to mark completion.`,
+      targetFiles,
+      ...skillTargetDir !== void 0 ? { skillTargetDir } : {}
+    };
+  }
+  resolveTargetFiles(projectRoot) {
+    const files = [];
+    for (const entry of TARGET_ENTRIES) {
+      if (entry.detect(projectRoot)) {
+        files.push(entry.target);
+      }
+    }
+    if (files.length === 0) {
+      files.push("AGENTS.md");
+    }
+    return files;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WatchmenChecker
+});
+//# sourceMappingURL=index.js.map

package/dist/watchmen/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/watchmen/index.ts"],
+  "sourcesContent": ["/**\n * KiroGraph Watchmen \u2014 threshold checker and target file resolver\n *\n * No state file. The watermark is the last kind='summary' observation.\n * Counting observations since that timestamp tells us when to synthesize.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { MemoryDatabase } from '../memory/database';\nimport type { WatchmenReadyResult } from '../memory/types';\n\n// \u2500\u2500 Target file detection \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 TARGET_ENTRIES: Array<{ detect: (root: string) => boolean; target: string }> = [\n  { detect: root => fs.existsSync(path.join(root, '.kiro')),                  target: '.kiro/steering/kirograph-watchmen.md' },\n  { detect: root => fs.existsSync(path.join(root, 'CLAUDE.md')),              target: 'CLAUDE.md' },\n  { detect: root => fs.existsSync(path.join(root, 'GEMINI.md')),              target: 'GEMINI.md' },\n  { detect: root => fs.existsSync(path.join(root, 'CONVENTIONS.md')),         target: 'CONVENTIONS.md' },\n  { detect: root => fs.existsSync(path.join(root, 'augment-guidelines.md')), target: 'augment-guidelines.md' },\n  { detect: root => fs.existsSync(path.join(root, 'AGENTS.md')),              target: 'AGENTS.md' },\n];\n\n// \u2500\u2500 WatchmenChecker \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 WatchmenChecker {\n  constructor(private readonly threshold: number) {}\n\n  shouldSynthesize(memDb: MemoryDatabase): { ready: boolean; pendingCount: number } {\n    const pendingCount = memDb.countSinceLastSummary();\n    return { ready: pendingCount >= this.threshold, pendingCount };\n  }\n\n  buildReadyResponse(id: string, pendingCount: number, projectRoot: string): WatchmenReadyResult {\n    const targetFiles = this.resolveTargetFiles(projectRoot);\n    const hasKiro = fs.existsSync(path.join(projectRoot, '.kiro'));\n    const skillTargetDir = hasKiro ? '.kiro/steering' : undefined;\n\n    const skillInstructions = skillTargetDir\n      ? `For each recurring procedure (appearing in 3+ observations): write a separate ` +\n        `\\`.kiro/steering/watchmen-<slug>.md\\` file with \\`inclusion: manual\\` frontmatter, ` +\n        `a short title, trigger phrases (when to load this skill), and numbered steps. ` +\n        `Use \\`watchmen-\\` prefix so auto-generated skills are distinguishable. ` +\n        `Delete any \\`.kiro/steering/watchmen-*.md\\` files from previous runs that no ` +\n        `longer reflect current patterns.`\n      : `Embed a ## Recurring Procedures section in each file in targetFiles listing ` +\n        `each identified recurring procedure with trigger context and numbered steps.`;\n\n    return {\n      id,\n      watchmenReady: true,\n      pendingCount,\n      message:\n        `${pendingCount} new observations since last synthesis. ` +\n        `Synthesize now: (1) call kirograph_mem_search for each kind ` +\n        `(decision, error, pattern, architecture, note) with limit 20, ` +\n        `(2) write or update the workspace brief (## KiroGraph Watchmen section) ` +\n        `in each file in targetFiles covering decisions, errors, patterns, and ` +\n        `architecture notes, (3) identify recurring procedures: ${skillInstructions} ` +\n        `(4) store a kind='summary' observation to mark completion.`,\n      targetFiles,\n      ...(skillTargetDir !== undefined ? { skillTargetDir } : {}),\n    };\n  }\n\n  private resolveTargetFiles(projectRoot: string): string[] {\n    const files: string[] = [];\n    for (const entry of TARGET_ENTRIES) {\n      if (entry.detect(projectRoot)) {\n        files.push(entry.target);\n      }\n    }\n    // Last-resort fallback for tools with no recognized project memory file\n    if (files.length === 0) {\n      files.push('AGENTS.md');\n    }\n    return files;\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,SAAoB;AACpB,WAAsB;AAMtB,MAAM,iBAA+E;AAAA,EACnF,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,OAAO,CAAC,GAAoB,QAAQ,uCAAuC;AAAA,EAC3H,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,WAAW,CAAC,GAAgB,QAAQ,YAAY;AAAA,EAChG,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,WAAW,CAAC,GAAgB,QAAQ,YAAY;AAAA,EAChG,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,gBAAgB,CAAC,GAAW,QAAQ,iBAAiB;AAAA,EACrG,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,uBAAuB,CAAC,GAAG,QAAQ,wBAAwB;AAAA,EAC3G,EAAE,QAAQ,UAAQ,GAAG,WAAW,KAAK,KAAK,MAAM,WAAW,CAAC,GAAgB,QAAQ,YAAY;AAClG;AAIO,MAAM,gBAAgB;AAAA,EAC3B,YAA6B,WAAmB;AAAnB;AAAA,EAAoB;AAAA,EAEjD,iBAAiB,OAAiE;AAChF,UAAM,eAAe,MAAM,sBAAsB;AACjD,WAAO,EAAE,OAAO,gBAAgB,KAAK,WAAW,aAAa;AAAA,EAC/D;AAAA,EAEA,mBAAmB,IAAY,cAAsB,aAA0C;AAC7F,UAAM,cAAc,KAAK,mBAAmB,WAAW;AACvD,UAAM,UAAU,GAAG,WAAW,KAAK,KAAK,aAAa,OAAO,CAAC;AAC7D,UAAM,iBAAiB,UAAU,mBAAmB;AAEpD,UAAM,oBAAoB,iBACtB,waAMA;AAGJ,WAAO;AAAA,MACL;AAAA,MACA,eAAe;AAAA,MACf;AAAA,MACA,SACE,GAAG,YAAY,0WAK2C,iBAAiB;AAAA,MAE7E;AAAA,MACA,GAAI,mBAAmB,SAAY,EAAE,eAAe,IAAI,CAAC;AAAA,IAC3D;AAAA,EACF;AAAA,EAEQ,mBAAmB,aAA+B;AACxD,UAAM,QAAkB,CAAC;AACzB,eAAW,SAAS,gBAAgB;AAClC,UAAI,MAAM,OAAO,WAAW,GAAG;AAC7B,cAAM,KAAK,MAAM,MAAM;AAAA,MACzB;AAAA,IACF;AAEA,QAAI,MAAM,WAAW,GAAG;AACtB,YAAM,KAAK,WAAW;AAAA,IACxB;AACA,WAAO;AAAA,EACT;AACF;",
+  "names": []
+}