@gettymade/roux 0.1.2 → 0.2.0

package/dist/index.js

@@ -88,7 +88,22 @@ function isNode(value) {
     return false;
   }
   const obj = value;
-  return typeof obj["id"] === "string" && typeof obj["title"] === "string" && typeof obj["content"] === "string" && Array.isArray(obj["tags"]) && obj["tags"].every((t) => typeof t === "string") && Array.isArray(obj["outgoingLinks"]) && obj["outgoingLinks"].every((l) => typeof l === "string") && typeof obj["properties"] === "object" && obj["properties"] !== null;
+  if (typeof obj["id"] !== "string" || typeof obj["title"] !== "string" || typeof obj["content"] !== "string") {
+    return false;
+  }
+  if (!Array.isArray(obj["tags"]) || !obj["tags"].every((t) => typeof t === "string")) {
+    return false;
+  }
+  if (!Array.isArray(obj["outgoingLinks"]) || !obj["outgoingLinks"].every((l) => typeof l === "string")) {
+    return false;
+  }
+  if (typeof obj["properties"] !== "object" || obj["properties"] === null || Array.isArray(obj["properties"])) {
+    return false;
+  }
+  if (obj["sourceRef"] !== void 0 && !isSourceRef(obj["sourceRef"])) {
+    return false;
+  }
+  return true;
 }
 function isSourceRef(value) {
   if (typeof value !== "object" || value === null) {
@@ -96,17 +111,68 @@ function isSourceRef(value) {
   }
   const obj = value;
   const validTypes = ["file", "api", "manual"];
-  return typeof obj["type"] === "string" && validTypes.includes(obj["type"]) && (obj["path"] === void 0 || typeof obj["path"] === "string") && (obj["lastModified"] === void 0 || obj["lastModified"] instanceof Date);
+  if (typeof obj["type"] !== "string" || !validTypes.includes(obj["type"])) {
+    return false;
+  }
+  if (obj["path"] !== void 0 && typeof obj["path"] !== "string") {
+    return false;
+  }
+  if (obj["lastModified"] !== void 0) {
+    if (!(obj["lastModified"] instanceof Date)) {
+      return false;
+    }
+    if (isNaN(obj["lastModified"].getTime())) {
+      return false;
+    }
+  }
+  return true;
 }
 
 // src/types/provider.ts
-function isVectorProvider(value) {
+function isVectorIndex(value) {
   if (value === null || typeof value !== "object") {
     return false;
   }
   const obj = value;
   return typeof obj.store === "function" && typeof obj.search === "function" && typeof obj.delete === "function" && typeof obj.getModel === "function" && typeof obj.hasEmbedding === "function";
 }
+function isStoreProvider(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const obj = value;
+  return typeof obj.id === "string" && obj.id.trim().length > 0 && typeof obj.createNode === "function" && typeof obj.updateNode === "function" && typeof obj.deleteNode === "function" && typeof obj.getNode === "function" && typeof obj.getNodes === "function" && typeof obj.getNeighbors === "function" && typeof obj.findPath === "function" && typeof obj.getHubs === "function" && typeof obj.storeEmbedding === "function" && typeof obj.searchByVector === "function" && typeof obj.searchByTags === "function" && typeof obj.getRandomNode === "function" && typeof obj.resolveTitles === "function" && typeof obj.listNodes === "function" && typeof obj.resolveNodes === "function" && typeof obj.nodesExist === "function";
+}
+function isEmbeddingProvider(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const obj = value;
+  return typeof obj.id === "string" && obj.id.trim().length > 0 && typeof obj.embed === "function" && typeof obj.embedBatch === "function" && typeof obj.dimensions === "function" && typeof obj.modelId === "function";
+}
+
+// src/types/guards.ts
+function createGuard(schema) {
+  return (value) => {
+    if (value === null || typeof value !== "object") return false;
+    const obj = value;
+    for (const [key, spec] of Object.entries(schema)) {
+      const val = obj[key];
+      if (spec.optional && val === void 0) continue;
+      if (spec.type === "array") {
+        if (!Array.isArray(val)) return false;
+      } else if (spec.type === "object") {
+        if (typeof val !== "object" || val === null) return false;
+      } else {
+        if (typeof val !== spec.type) return false;
+      }
+      if (spec.nonEmpty && spec.type === "string" && val.length === 0) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
 
 // src/types/config.ts
 var DEFAULT_CONFIG = {
@@ -129,15 +195,399 @@ var DEFAULT_CONFIG = {
 };
 
 // src/providers/docstore/index.ts
-import { readFile, writeFile, stat, readdir, mkdir, rm } from "fs/promises";
-import { join as join3, relative, dirname, resolve } from "path";
-import { watch } from "chokidar";
+import { writeFile, mkdir, rm, stat as stat2 } from "fs/promises";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join4, relative as relative2, dirname, extname as extname3 } from "path";
 
-// src/providers/docstore/cache.ts
+// src/graph/builder.ts
+import { DirectedGraph } from "graphology";
+function buildGraph(nodes) {
+  const graph = new DirectedGraph();
+  const nodeIds = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    graph.addNode(node.id);
+    nodeIds.add(node.id);
+  }
+  for (const node of nodes) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const target of node.outgoingLinks) {
+      if (!nodeIds.has(target) || seen.has(target)) {
+        continue;
+      }
+      seen.add(target);
+      graph.addDirectedEdge(node.id, target);
+    }
+  }
+  return graph;
+}
+
+// src/graph/traversal.ts
+import { bidirectional } from "graphology-shortest-path";
+
+// src/utils/heap.ts
+var MinHeap = class {
+  data = [];
+  compare;
+  constructor(comparator) {
+    this.compare = comparator;
+  }
+  size() {
+    return this.data.length;
+  }
+  peek() {
+    return this.data[0];
+  }
+  push(value) {
+    this.data.push(value);
+    this.bubbleUp(this.data.length - 1);
+  }
+  pop() {
+    if (this.data.length === 0) return void 0;
+    if (this.data.length === 1) return this.data.pop();
+    const min = this.data[0];
+    this.data[0] = this.data.pop();
+    this.bubbleDown(0);
+    return min;
+  }
+  toArray() {
+    return [...this.data];
+  }
+  bubbleUp(index) {
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      if (this.compare(this.data[index], this.data[parentIndex]) >= 0) {
+        break;
+      }
+      this.swap(index, parentIndex);
+      index = parentIndex;
+    }
+  }
+  bubbleDown(index) {
+    const length = this.data.length;
+    while (true) {
+      const leftChild = 2 * index + 1;
+      const rightChild = 2 * index + 2;
+      let smallest = index;
+      if (leftChild < length && this.compare(this.data[leftChild], this.data[smallest]) < 0) {
+        smallest = leftChild;
+      }
+      if (rightChild < length && this.compare(this.data[rightChild], this.data[smallest]) < 0) {
+        smallest = rightChild;
+      }
+      if (smallest === index) break;
+      this.swap(index, smallest);
+      index = smallest;
+    }
+  }
+  swap(i, j) {
+    const temp = this.data[i];
+    this.data[i] = this.data[j];
+    this.data[j] = temp;
+  }
+};
+
+// src/graph/traversal.ts
+function getNeighborIds(graph, id, options) {
+  if (!graph.hasNode(id)) {
+    return [];
+  }
+  const limit = options.limit;
+  if (limit !== void 0 && limit <= 0) {
+    return [];
+  }
+  const maxCount = limit ?? Infinity;
+  const direction = options.direction;
+  if (direction === "both") {
+    const neighbors2 = [];
+    for (const entry of graph.neighborEntries(id)) {
+      if (neighbors2.length >= maxCount) break;
+      neighbors2.push(entry.neighbor);
+    }
+    return neighbors2;
+  }
+  const neighbors = [];
+  const iterator = direction === "in" ? graph.inNeighborEntries(id) : graph.outNeighborEntries(id);
+  for (const entry of iterator) {
+    if (neighbors.length >= maxCount) break;
+    neighbors.push(entry.neighbor);
+  }
+  return neighbors;
+}
+function findPath(graph, source, target) {
+  if (!graph.hasNode(source) || !graph.hasNode(target)) {
+    return null;
+  }
+  if (source === target) {
+    return [source];
+  }
+  const path = bidirectional(graph, source, target);
+  return path;
+}
+function getHubs(graph, metric, limit) {
+  if (limit <= 0) {
+    return [];
+  }
+  const heap = new MinHeap((a, b) => a[1] - b[1]);
+  graph.forEachNode((id) => {
+    const score = metric === "in_degree" ? graph.inDegree(id) : graph.outDegree(id);
+    if (heap.size() < limit) {
+      heap.push([id, score]);
+    } else if (score > heap.peek()[1]) {
+      heap.pop();
+      heap.push([id, score]);
+    }
+  });
+  return heap.toArray().sort((a, b) => {
+    const scoreDiff = b[1] - a[1];
+    if (scoreDiff !== 0) return scoreDiff;
+    return a[0].localeCompare(b[0]);
+  });
+}
+
+// src/graph/analysis.ts
+function computeCentrality(graph) {
+  const result = /* @__PURE__ */ new Map();
+  graph.forEachNode((id) => {
+    result.set(id, {
+      inDegree: graph.inDegree(id),
+      outDegree: graph.outDegree(id)
+    });
+  });
+  return result;
+}
+
+// src/graph/manager.ts
+var GraphNotReadyError = class extends Error {
+  constructor() {
+    super("Graph not built. Call build() before querying.");
+    this.name = "GraphNotReadyError";
+  }
+};
+var GraphManager = class {
+  graph = null;
+  /** Build graph and return centrality metrics. Caller stores as needed. */
+  build(nodes) {
+    this.graph = buildGraph(nodes);
+    return computeCentrality(this.graph);
+  }
+  /** Throws GraphNotReadyError if not built. Returns graph for query use. */
+  assertReady() {
+    if (!this.graph) throw new GraphNotReadyError();
+    return this.graph;
+  }
+  isReady() {
+    return this.graph !== null;
+  }
+  getNeighborIds(id, options) {
+    return getNeighborIds(this.assertReady(), id, options);
+  }
+  findPath(source, target) {
+    return findPath(this.assertReady(), source, target);
+  }
+  getHubs(metric, limit) {
+    return getHubs(this.assertReady(), metric, limit);
+  }
+};
+
+// src/providers/store/resolve.ts
 var import_string_similarity = __toESM(require_src(), 1);
+function resolveNames(names, candidates, options) {
+  if (names.length === 0) return [];
+  const { strategy, threshold } = options;
+  if (candidates.length === 0) {
+    return names.map((query) => ({ query, match: null, score: 0 }));
+  }
+  const candidateTitles = candidates.map((c) => c.title.toLowerCase());
+  const titleToId = /* @__PURE__ */ new Map();
+  for (const c of candidates) {
+    titleToId.set(c.title.toLowerCase(), c.id);
+  }
+  return names.map((query) => {
+    const queryLower = query.toLowerCase();
+    if (strategy === "exact") {
+      const matchedId = titleToId.get(queryLower);
+      if (matchedId) {
+        return { query, match: matchedId, score: 1 };
+      }
+      return { query, match: null, score: 0 };
+    }
+    if (strategy === "fuzzy") {
+      const result = import_string_similarity.default.findBestMatch(queryLower, candidateTitles);
+      const bestMatch = result.bestMatch;
+      if (bestMatch.rating >= threshold) {
+        const matchedId = titleToId.get(bestMatch.target);
+        return { query, match: matchedId, score: bestMatch.rating };
+      }
+      return { query, match: null, score: 0 };
+    }
+    return { query, match: null, score: 0 };
+  });
+}
+
+// src/providers/store/index.ts
+var StoreProvider = class {
+  graphManager = new GraphManager();
+  vectorIndex;
+  constructor(options) {
+    this.vectorIndex = options?.vectorIndex ?? null;
+  }
+  // ── Graph operations (delegate to GraphManager) ────────────
+  async getNeighbors(id, options) {
+    if (!this.graphManager.isReady()) return [];
+    const neighborIds = this.graphManager.getNeighborIds(id, options);
+    return this.getNodesByIds(neighborIds);
+  }
+  async findPath(source, target) {
+    if (!this.graphManager.isReady()) return null;
+    return this.graphManager.findPath(source, target);
+  }
+  async getHubs(metric, limit) {
+    if (!this.graphManager.isReady()) return [];
+    return this.graphManager.getHubs(metric, limit);
+  }
+  // ── Vector operations (delegate to VectorIndex) ────────────
+  async storeEmbedding(id, vector, model) {
+    if (!this.vectorIndex) throw new Error("No VectorIndex configured");
+    return this.vectorIndex.store(id, vector, model);
+  }
+  async searchByVector(vector, limit) {
+    if (!this.vectorIndex) throw new Error("No VectorIndex configured");
+    return this.vectorIndex.search(vector, limit);
+  }
+  // ── Discovery ──────────────────────────────────────────────
+  async getRandomNode(tags) {
+    let candidates;
+    if (tags && tags.length > 0) {
+      candidates = await this.searchByTags(tags, "any");
+    } else {
+      candidates = await this.loadAllNodes();
+    }
+    if (candidates.length === 0) return null;
+    return candidates[Math.floor(Math.random() * candidates.length)];
+  }
+  // ── Default implementations (overridable) ──────────────────
+  async searchByTags(tags, mode, limit) {
+    const allNodes = await this.loadAllNodes();
+    const lowerTags = tags.map((t) => t.toLowerCase());
+    let results = allNodes.filter((node) => {
+      const nodeTags = node.tags.map((t) => t.toLowerCase());
+      return mode === "any" ? lowerTags.some((t) => nodeTags.includes(t)) : lowerTags.every((t) => nodeTags.includes(t));
+    });
+    if (limit !== void 0) results = results.slice(0, limit);
+    return results;
+  }
+  async listNodes(filter, options) {
+    let nodes = await this.loadAllNodes();
+    if (filter.tag) {
+      const lower = filter.tag.toLowerCase();
+      nodes = nodes.filter((n) => n.tags.some((t) => t.toLowerCase() === lower));
+    }
+    if (filter.path) {
+      const lowerPath = filter.path.toLowerCase();
+      nodes = nodes.filter((n) => n.id.startsWith(lowerPath));
+    }
+    const total = nodes.length;
+    const offset = options?.offset ?? 0;
+    const limit = Math.min(options?.limit ?? 100, 1e3);
+    const sliced = nodes.slice(offset, offset + limit);
+    return {
+      nodes: sliced.map((n) => ({ id: n.id, title: n.title })),
+      total
+    };
+  }
+  async nodesExist(ids) {
+    if (ids.length === 0) return /* @__PURE__ */ new Map();
+    const found = await this.getNodesByIds(ids);
+    const foundIds = new Set(found.map((n) => n.id));
+    const result = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      result.set(id, foundIds.has(id));
+    }
+    return result;
+  }
+  async resolveTitles(ids) {
+    if (ids.length === 0) return /* @__PURE__ */ new Map();
+    const nodes = await this.getNodesByIds(ids);
+    const result = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      result.set(node.id, node.title);
+    }
+    return result;
+  }
+  async resolveNodes(names, options) {
+    const strategy = options?.strategy ?? "fuzzy";
+    if (strategy === "semantic") {
+      return names.map((query) => ({ query, match: null, score: 0 }));
+    }
+    const allNodes = await this.loadAllNodes();
+    let candidates = allNodes.map((n) => ({ id: n.id, title: n.title }));
+    if (options?.tag) {
+      const lower = options.tag.toLowerCase();
+      const filtered = allNodes.filter((n) => n.tags.some((t) => t.toLowerCase() === lower));
+      candidates = filtered.map((n) => ({ id: n.id, title: n.title }));
+    }
+    if (options?.path) {
+      const lowerPath = options.path.toLowerCase();
+      candidates = candidates.filter((c) => c.id.startsWith(lowerPath));
+    }
+    return resolveNames(names, candidates, {
+      strategy,
+      threshold: options?.threshold ?? 0.7
+    });
+  }
+  // ── Graph lifecycle ────────────────────────────────────────
+  async syncGraph() {
+    const nodes = await this.loadAllNodes();
+    const centrality = this.graphManager.build(nodes);
+    this.onCentralityComputed(centrality);
+  }
+  onCentralityComputed(_centrality) {
+  }
+};
+
+// src/providers/docstore/cache.ts
 import Database from "better-sqlite3";
 import { join } from "path";
 import { mkdirSync } from "fs";
+
+// src/providers/docstore/cache/centrality.ts
+function initCentralitySchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS centrality (
+      node_id TEXT PRIMARY KEY,
+      pagerank REAL,
+      in_degree INTEGER,
+      out_degree INTEGER,
+      computed_at INTEGER,
+      FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
+    )
+  `);
+}
+function storeCentrality(db, nodeId, pagerank, inDegree, outDegree, computedAt) {
+  db.prepare(
+    `
+    INSERT INTO centrality (node_id, pagerank, in_degree, out_degree, computed_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(node_id) DO UPDATE SET
+      pagerank = excluded.pagerank,
+      in_degree = excluded.in_degree,
+      out_degree = excluded.out_degree,
+      computed_at = excluded.computed_at
+  `
+  ).run(nodeId, pagerank, inDegree, outDegree, computedAt);
+}
+function getCentrality(db, nodeId) {
+  const row = db.prepare("SELECT * FROM centrality WHERE node_id = ?").get(nodeId);
+  if (!row) return null;
+  return {
+    pagerank: row.pagerank,
+    inDegree: row.in_degree,
+    outDegree: row.out_degree,
+    computedAt: row.computed_at
+  };
+}
+
+// src/providers/docstore/cache.ts
 var Cache = class {
   db;
   constructor(cacheDir) {
@@ -161,24 +611,9 @@ var Cache = class {
         source_modified INTEGER
       );
 
-      CREATE TABLE IF NOT EXISTS embeddings (
-        node_id TEXT PRIMARY KEY,
-        model TEXT,
-        vector BLOB,
-        FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
-      );
-
-      CREATE TABLE IF NOT EXISTS centrality (
-        node_id TEXT PRIMARY KEY,
-        pagerank REAL,
-        in_degree INTEGER,
-        out_degree INTEGER,
-        computed_at INTEGER,
-        FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
-      );
-
       CREATE INDEX IF NOT EXISTS idx_nodes_source_path ON nodes(source_path);
     `);
+    initCentralitySchema(this.db);
     this.db.pragma("foreign_keys = ON");
   }
   getTableNames() {
@@ -238,25 +673,37 @@ var Cache = class {
     const rows = this.db.prepare("SELECT * FROM nodes").all();
     return rows.map((row) => this.rowToNode(row));
   }
-  searchByTags(tags, mode) {
+  searchByTags(tags, mode, limit) {
     if (tags.length === 0) return [];
-    const allNodes = this.getAllNodes();
     const lowerTags = tags.map((t) => t.toLowerCase());
-    return allNodes.filter((node) => {
-      const nodeTags = node.tags.map((t) => t.toLowerCase());
-      if (mode === "any") {
-        return lowerTags.some((t) => nodeTags.includes(t));
-      } else {
-        return lowerTags.every((t) => nodeTags.includes(t));
-      }
-    });
+    let query;
+    const params = [];
+    if (mode === "any") {
+      const tagConditions = lowerTags.map(
+        () => "EXISTS (SELECT 1 FROM json_each(tags) WHERE LOWER(json_each.value) = ?)"
+      ).join(" OR ");
+      query = `SELECT * FROM nodes WHERE ${tagConditions}`;
+      params.push(...lowerTags);
+    } else {
+      const tagConditions = lowerTags.map(
+        () => "EXISTS (SELECT 1 FROM json_each(tags) WHERE LOWER(json_each.value) = ?)"
+      ).join(" AND ");
+      query = `SELECT * FROM nodes WHERE ${tagConditions}`;
+      params.push(...lowerTags);
+    }
+    if (limit !== void 0) {
+      query += " LIMIT ?";
+      params.push(limit);
+    }
+    const rows = this.db.prepare(query).all(...params);
+    return rows.map((row) => this.rowToNode(row));
   }
   getModifiedTime(sourcePath) {
     const row = this.db.prepare("SELECT source_modified FROM nodes WHERE source_path = ?").get(sourcePath);
     return row?.source_modified ?? null;
   }
   getNodeByPath(sourcePath) {
-    const row = this.db.prepare("SELECT * FROM nodes WHERE source_path = ?").get(sourcePath);
+    const row = this.db.prepare("SELECT * FROM nodes WHERE LOWER(source_path) = LOWER(?)").get(sourcePath);
     if (!row) return null;
     return this.rowToNode(row);
   }
@@ -264,6 +711,13 @@ var Cache = class {
     const rows = this.db.prepare("SELECT source_path FROM nodes").all();
     return new Set(rows.map((r) => r.source_path));
   }
+  updateSourcePath(id, newPath) {
+    this.db.prepare("UPDATE nodes SET source_path = ? WHERE id = ?").run(newPath, id);
+  }
+  getIdByPath(sourcePath) {
+    const row = this.db.prepare("SELECT id FROM nodes WHERE source_path = ?").get(sourcePath);
+    return row?.id ?? null;
+  }
   resolveTitles(ids) {
     if (ids.length === 0) return /* @__PURE__ */ new Map();
     const placeholders = ids.map(() => "?").join(",");
@@ -295,7 +749,7 @@ var Cache = class {
       params.push(filter.tag);
     }
     if (filter.path) {
-      conditions.push("id LIKE ? || '%'");
+      conditions.push("LOWER(source_path) LIKE '%' || LOWER(?) || '%'");
       params.push(filter.path);
     }
     const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
@@ -315,99 +769,27 @@ var Cache = class {
     if (options?.tag) filter.tag = options.tag;
     if (options?.path) filter.path = options.path;
     const { nodes: candidates } = this.listNodes(filter, { limit: 1e3 });
-    if (candidates.length === 0) {
-      return names.map((query) => ({ query, match: null, score: 0 }));
-    }
-    const candidateTitles = candidates.map((c) => c.title.toLowerCase());
-    const titleToId = /* @__PURE__ */ new Map();
-    for (const c of candidates) {
-      titleToId.set(c.title.toLowerCase(), c.id);
-    }
-    return names.map((query) => {
-      const queryLower = query.toLowerCase();
-      if (strategy === "exact") {
-        const matchedId = titleToId.get(queryLower);
-        if (matchedId) {
-          return { query, match: matchedId, score: 1 };
-        }
-        return { query, match: null, score: 0 };
-      }
-      if (strategy === "fuzzy") {
-        const result = import_string_similarity.default.findBestMatch(queryLower, candidateTitles);
-        const bestMatch = result.bestMatch;
-        if (bestMatch.rating >= threshold) {
-          const matchedId = titleToId.get(bestMatch.target);
-          return { query, match: matchedId, score: bestMatch.rating };
-        }
-        return { query, match: null, score: 0 };
-      }
-      return { query, match: null, score: 0 };
-    });
+    return resolveNames(names, candidates, { strategy, threshold });
   }
   updateOutgoingLinks(nodeId, links) {
     this.db.prepare("UPDATE nodes SET outgoing_links = ? WHERE id = ?").run(JSON.stringify(links), nodeId);
   }
-  storeEmbedding(nodeId, vector, model) {
-    const buffer = Buffer.from(new Float32Array(vector).buffer);
-    this.db.prepare(
-      `
-      INSERT INTO embeddings (node_id, model, vector)
-      VALUES (?, ?, ?)
-      ON CONFLICT(node_id) DO UPDATE SET
-        model = excluded.model,
-        vector = excluded.vector
-    `
-    ).run(nodeId, model, buffer);
-  }
-  getEmbedding(nodeId) {
-    const row = this.db.prepare("SELECT model, vector FROM embeddings WHERE node_id = ?").get(nodeId);
-    if (!row) return null;
-    const float32 = new Float32Array(
-      row.vector.buffer,
-      row.vector.byteOffset,
-      row.vector.length / 4
-    );
-    return {
-      model: row.model,
-      vector: Array.from(float32)
-    };
-  }
   storeCentrality(nodeId, pagerank, inDegree, outDegree, computedAt) {
-    this.db.prepare(
-      `
-      INSERT INTO centrality (node_id, pagerank, in_degree, out_degree, computed_at)
-      VALUES (?, ?, ?, ?, ?)
-      ON CONFLICT(node_id) DO UPDATE SET
-        pagerank = excluded.pagerank,
-        in_degree = excluded.in_degree,
-        out_degree = excluded.out_degree,
-        computed_at = excluded.computed_at
-    `
-    ).run(nodeId, pagerank, inDegree, outDegree, computedAt);
+    storeCentrality(this.db, nodeId, pagerank, inDegree, outDegree, computedAt);
   }
   getCentrality(nodeId) {
-    const row = this.db.prepare("SELECT * FROM centrality WHERE node_id = ?").get(nodeId);
-    if (!row) return null;
-    return {
-      pagerank: row.pagerank,
-      inDegree: row.in_degree,
-      outDegree: row.out_degree,
-      computedAt: row.computed_at
-    };
+    return getCentrality(this.db, nodeId);
   }
   getStats() {
     const nodeCount = this.db.prepare("SELECT COUNT(*) as count FROM nodes").get();
-    const embeddingCount = this.db.prepare("SELECT COUNT(*) as count FROM embeddings").get();
     const edgeSum = this.db.prepare("SELECT SUM(in_degree) as total FROM centrality").get();
     return {
       nodeCount: nodeCount.count,
-      embeddingCount: embeddingCount.count,
       edgeCount: edgeSum.total ?? 0
     };
   }
   clear() {
     this.db.exec("DELETE FROM centrality");
-    this.db.exec("DELETE FROM embeddings");
     this.db.exec("DELETE FROM nodes");
   }
   close() {
@@ -434,9 +816,45 @@ var Cache = class {
 // src/providers/vector/sqlite.ts
 import Database2 from "better-sqlite3";
 import { join as join2 } from "path";
-var SqliteVectorProvider = class {
+
+// src/utils/math.ts
+function cosineSimilarity(a, b) {
+  if (a.length === 0 || b.length === 0) {
+    throw new Error("Cannot compute similarity for empty vector");
+  }
+  if (a.length !== b.length) {
+    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function cosineDistance(a, b) {
+  const similarity = cosineSimilarity(a, b);
+  if (similarity === 0 && (isZeroVector(a) || isZeroVector(b))) {
+    return 1;
+  }
+  return 1 - similarity;
+}
+function isZeroVector(v) {
+  for (let i = 0; i < v.length; i++) {
+    if (v[i] !== 0) return false;
+  }
+  return true;
+}
+
+// src/providers/vector/sqlite.ts
+var SqliteVectorIndex = class {
   db;
   ownsDb;
+  modelMismatchWarned = false;
   constructor(pathOrDb) {
     if (typeof pathOrDb === "string") {
       this.db = new Database2(join2(pathOrDb, "vectors.db"));
@@ -488,29 +906,45 @@ var SqliteVectorProvider = class {
     if (limit <= 0) {
       return [];
     }
-    const rows = this.db.prepare("SELECT id, vector FROM vectors").all();
-    if (rows.length === 0) {
-      return [];
-    }
-    const firstStoredDim = rows[0].vector.byteLength / 4;
-    if (vector.length !== firstStoredDim) {
-      throw new Error(
-        `Dimension mismatch: query has ${vector.length} dimensions, stored vectors have ${firstStoredDim}`
-      );
+    if (!this.modelMismatchWarned) {
+      const models = this.db.prepare("SELECT DISTINCT model FROM vectors").all();
+      if (models.length > 1) {
+        console.warn(
+          `Vector index contains embeddings from multiple models: ${models.map((m) => m.model).join(", ")}. Search results may be unreliable. Re-sync to re-embed all documents with current model.`
+        );
+        this.modelMismatchWarned = true;
+      }
     }
     const queryVec = new Float32Array(vector);
-    const results = [];
-    for (const row of rows) {
+    const stmt = this.db.prepare("SELECT id, vector FROM vectors");
+    const heap = new MinHeap(
+      (a, b) => b.distance - a.distance
+    );
+    let dimensionChecked = false;
+    for (const row of stmt.iterate()) {
+      if (!dimensionChecked) {
+        const storedDim = row.vector.byteLength / 4;
+        if (vector.length !== storedDim) {
+          throw new Error(
+            `Dimension mismatch: query has ${vector.length} dimensions, stored vectors have ${storedDim}`
+          );
+        }
+        dimensionChecked = true;
+      }
       const storedVec = new Float32Array(
         row.vector.buffer,
         row.vector.byteOffset,
         row.vector.byteLength / 4
       );
       const distance = cosineDistance(queryVec, storedVec);
-      results.push({ id: row.id, distance });
+      if (heap.size() < limit) {
+        heap.push({ id: row.id, distance });
+      } else if (distance < heap.peek().distance) {
+        heap.pop();
+        heap.push({ id: row.id, distance });
+      }
     }
-    results.sort((a, b) => a.distance - b.distance);
-    return results.slice(0, limit);
+    return heap.toArray().sort((a, b) => a.distance - b.distance);
   }
   async delete(id) {
     this.db.prepare("DELETE FROM vectors WHERE id = ?").run(id);
@@ -544,26 +978,30 @@ var SqliteVectorProvider = class {
     }
   }
 };
-function cosineDistance(a, b) {
-  let dotProduct = 0;
-  let magnitudeA = 0;
-  let magnitudeB = 0;
-  for (let i = 0; i < a.length; i++) {
-    dotProduct += a[i] * b[i];
-    magnitudeA += a[i] * a[i];
-    magnitudeB += b[i] * b[i];
-  }
-  magnitudeA = Math.sqrt(magnitudeA);
-  magnitudeB = Math.sqrt(magnitudeB);
-  if (magnitudeA === 0 || magnitudeB === 0) {
-    return 1;
+
+// src/providers/docstore/parser.ts
+import matter from "gray-matter";
+
+// src/providers/docstore/normalize.ts
+function hasFileExtension(path) {
+  const match = path.match(/\.([a-z0-9]{1,4})$/i);
+  if (!match?.[1]) return false;
+  return /[a-z]/i.test(match[1]);
+}
+function normalizePath(path) {
+  return path.toLowerCase().replace(/\\/g, "/");
+}
+function normalizeLinkTarget(target) {
+  let normalized = target.trim().toLowerCase().replace(/\\/g, "/");
+  if (!hasFileExtension(normalized)) {
+    normalized += ".md";
   }
-  const similarity = dotProduct / (magnitudeA * magnitudeB);
-  return 1 - similarity;
+  return normalized;
 }
 
 // src/providers/docstore/parser.ts
-import matter from "gray-matter";
+var RESERVED_FRONTMATTER_KEYS = ["id", "title", "tags"];
+var RESERVED_KEYS_SET = new Set(RESERVED_FRONTMATTER_KEYS);
 function parseMarkdown(raw) {
   let parsed;
   try {
@@ -573,10 +1011,12 @@ function parseMarkdown(raw) {
       title: void 0,
       tags: [],
       properties: {},
-      content: raw
+      content: raw,
+      rawLinks: extractWikiLinks(raw)
     };
   }
   const data = parsed.data;
+  const id = typeof data["id"] === "string" ? data["id"] : void 0;
   const title = typeof data["title"] === "string" ? data["title"] : void 0;
   let tags = [];
   if (Array.isArray(data["tags"])) {
@@ -584,16 +1024,22 @@ function parseMarkdown(raw) {
   }
   const properties = {};
   for (const [key, value] of Object.entries(data)) {
-    if (key !== "title" && key !== "tags") {
+    if (!RESERVED_KEYS_SET.has(key)) {
       properties[key] = value;
     }
   }
-  return {
+  const content = parsed.content.trim();
+  const result = {
     title,
     tags,
     properties,
-    content: parsed.content.trim()
+    content,
+    rawLinks: extractWikiLinks(content)
   };
+  if (id !== void 0) {
+    result.id = id;
+  }
+  return result;
 }
 function extractWikiLinks(content) {
   const withoutCodeBlocks = content.replace(/```[\s\S]*?```/g, "");
@@ -611,9 +1057,7 @@ function extractWikiLinks(content) {
   }
   return links;
 }
-function normalizeId(path) {
-  return path.toLowerCase().replace(/\\/g, "/");
-}
+var normalizeId = normalizePath;
 function titleFromPath(path) {
   const parts = path.split(/[/\\]/);
   const filename = parts.at(-1);
@@ -622,11 +1066,14 @@ function titleFromPath(path) {
   return spaced.split(" ").filter((w) => w.length > 0).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 function serializeToMarkdown(parsed) {
-  const hasFrontmatter = parsed.title !== void 0 || parsed.tags.length > 0 || Object.keys(parsed.properties).length > 0;
+  const hasFrontmatter = parsed.id !== void 0 || parsed.title !== void 0 || parsed.tags.length > 0 || Object.keys(parsed.properties).length > 0;
   if (!hasFrontmatter) {
     return parsed.content;
   }
   const frontmatter = {};
+  if (parsed.id !== void 0) {
+    frontmatter["id"] = parsed.id;
+  }
   if (parsed.title !== void 0) {
     frontmatter["title"] = parsed.title;
   }
@@ -639,243 +1086,586 @@ function serializeToMarkdown(parsed) {
   return matter.stringify(parsed.content, frontmatter);
 }
 
-// src/graph/builder.ts
-import { DirectedGraph } from "graphology";
-function buildGraph(nodes) {
-  const graph = new DirectedGraph();
-  const nodeIds = /* @__PURE__ */ new Set();
-  for (const node of nodes) {
-    graph.addNode(node.id);
-    nodeIds.add(node.id);
+// src/providers/docstore/watcher.ts
+import { watch } from "chokidar";
+import { relative, extname } from "path";
+
+// src/providers/docstore/constants.ts
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+  ".roux",
+  "node_modules",
+  ".git",
+  ".obsidian"
+]);
+
+// src/providers/docstore/watcher.ts
+var DEFAULT_DEBOUNCE_MS = 1e3;
+var FileWatcher = class {
+  root;
+  extensions;
+  debounceMs;
+  onBatch;
+  watcher = null;
+  debounceTimer = null;
+  pendingChanges = /* @__PURE__ */ new Map();
+  isPaused = false;
+  constructor(options) {
+    this.root = options.root;
+    this.extensions = options.extensions;
+    this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    this.onBatch = options.onBatch;
+  }
+  start() {
+    if (this.watcher) {
+      return Promise.reject(new Error("Already watching. Call stop() first."));
+    }
+    return new Promise((resolve2, reject) => {
+      let isReady = false;
+      this.watcher = watch(this.root, {
+        ignoreInitial: true,
+        ignored: [...EXCLUDED_DIRS].map((dir) => `**/${dir}/**`),
+        awaitWriteFinish: {
+          stabilityThreshold: 100
+        },
+        followSymlinks: false
+      });
+      this.watcher.on("ready", () => {
+        isReady = true;
+        resolve2();
+      }).on("add", (path) => this.queueChange(path, "add")).on("change", (path) => this.queueChange(path, "change")).on("unlink", (path) => this.queueChange(path, "unlink")).on("error", (err) => {
+        if (err.code === "EMFILE") {
+          console.error(
+            "File watcher hit file descriptor limit. Try: ulimit -n 65536 or reduce watched files."
+          );
+        }
+        if (isReady) {
+          console.error("FileWatcher error:", err);
+        } else {
+          reject(err);
+        }
+      });
+    });
+  }
+  stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.pendingChanges.clear();
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+  isWatching() {
+    return this.watcher !== null;
+  }
+  pause() {
+    this.isPaused = true;
+  }
+  resume() {
+    this.isPaused = false;
+  }
+  flush() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.pendingChanges.size === 0) {
+      return;
+    }
+    const batch = new Map(this.pendingChanges);
+    this.pendingChanges.clear();
+    try {
+      const result = this.onBatch(batch);
+      if (result && typeof result.catch === "function") {
+        result.catch((err) => {
+          console.error("FileWatcher onBatch callback threw an error:", err);
+        });
+      }
+    } catch (err) {
+      console.error("FileWatcher onBatch callback threw an error:", err);
+    }
+  }
+  queueChange(filePath, event) {
+    if (this.isPaused) return;
+    const relativePath = relative(this.root, filePath);
+    const ext = extname(filePath).toLowerCase();
+    if (!ext || !this.extensions.has(ext)) {
+      return;
+    }
+    const pathParts = relativePath.split("/");
+    for (const part of pathParts) {
+      if (EXCLUDED_DIRS.has(part)) {
+        return;
+      }
+    }
+    const id = relativePath.toLowerCase().replace(/\\/g, "/");
+    const existing = this.pendingChanges.get(id);
+    if (existing) {
+      if (existing === "add" && event === "change") {
+        return;
+      } else if (existing === "add" && event === "unlink") {
+        this.pendingChanges.delete(id);
+        if (this.pendingChanges.size === 0) {
+          if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+          }
+          return;
+        }
+      } else if (existing === "change" && event === "unlink") {
+        this.pendingChanges.set(id, "unlink");
+      } else if (existing === "change" && event === "add") {
+        this.pendingChanges.set(id, "add");
+      } else if (existing === "unlink" && event === "add") {
+        this.pendingChanges.set(id, "add");
+      } else if (existing === "unlink" && event === "change") {
+        return;
+      }
+    } else {
+      this.pendingChanges.set(id, event);
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.flush();
+    }, this.debounceMs);
   }
+};
+
+// src/providers/docstore/links.ts
+var normalizeWikiLink = normalizeLinkTarget;
+function buildFilenameIndex(nodes) {
+  const index = /* @__PURE__ */ new Map();
   for (const node of nodes) {
-    const seen = /* @__PURE__ */ new Set();
-    for (const target of node.outgoingLinks) {
-      if (!nodeIds.has(target) || seen.has(target)) {
-        continue;
+    const path = node.sourceRef?.path ?? "";
+    const titleKey = node.title.toLowerCase();
+    if (!titleKey && !path) {
+      console.warn(
+        `Node ${node.id} has no title or path \u2014 link resolution will fail`
+      );
+    }
+    if (titleKey) {
+      const existing = index.get(titleKey) ?? [];
+      existing.push(node.id);
+      index.set(titleKey, existing);
+    }
+    if (path) {
+      const filename = path.split("/").pop()?.replace(/\.[^.]+$/, "").toLowerCase();
+      if (filename && filename !== titleKey) {
+        const existing = index.get(filename) ?? [];
+        existing.push(node.id);
+        index.set(filename, existing);
       }
-      seen.add(target);
-      graph.addDirectedEdge(node.id, target);
     }
   }
-  return graph;
+  for (const ids of index.values()) {
+    ids.sort();
+  }
+  return index;
+}
+function resolveLinks(outgoingLinks, filenameIndex, validNodeIds) {
+  return outgoingLinks.map((link) => {
+    if (validNodeIds.has(link)) {
+      return link;
+    }
+    if (link.includes("/")) {
+      return link;
+    }
+    const lookupKey = link.replace(/\.md$/i, "").toLowerCase();
+    const matches = filenameIndex.get(lookupKey);
+    if (matches && matches.length > 0) {
+      return matches[0];
+    }
+    const variant = spaceDashVariant(lookupKey);
+    if (variant) {
+      const variantMatches = filenameIndex.get(variant);
+      if (variantMatches && variantMatches.length > 0) {
+        return variantMatches[0];
+      }
+    }
+    return link;
+  });
+}
+function spaceDashVariant(filename) {
+  const hasSpace = filename.includes(" ");
+  const hasDash = filename.includes("-");
+  if (hasSpace && !hasDash) {
+    return filename.replace(/ /g, "-");
+  }
+  if (hasDash && !hasSpace) {
+    return filename.replace(/-/g, " ");
+  }
+  return null;
 }
 
-// src/graph/operations.ts
-import { bidirectional } from "graphology-shortest-path";
-function getNeighborIds(graph, id, options) {
-  if (!graph.hasNode(id)) {
+// src/providers/docstore/file-operations.ts
+import { readFile, stat, readdir } from "fs/promises";
+import { join as join3, resolve, extname as extname2 } from "path";
+async function getFileMtime(filePath) {
+  const stats = await stat(filePath);
+  return stats.mtimeMs;
+}
+function validatePathWithinSource(sourceRoot, id) {
+  const resolvedPath = resolve(sourceRoot, id);
+  const resolvedRoot = resolve(sourceRoot);
+  if (!resolvedPath.startsWith(resolvedRoot + "/")) {
+    throw new Error(`Path traversal detected: ${id} resolves outside source root`);
+  }
+}
+async function collectFiles(dir, extensions) {
+  if (extensions.size === 0) {
     return [];
   }
-  let neighbors;
-  switch (options.direction) {
-    case "in":
-      neighbors = graph.inNeighbors(id);
-      break;
-    case "out":
-      neighbors = graph.outNeighbors(id);
-      break;
-    case "both":
-      neighbors = graph.neighbors(id);
-      break;
-  }
-  if (options.limit !== void 0) {
-    if (options.limit <= 0) {
-      return [];
-    }
-    if (options.limit < neighbors.length) {
-      return neighbors.slice(0, options.limit);
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join3(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) {
+        continue;
+      }
+      const nested = await collectFiles(fullPath, extensions);
+      results.push(...nested);
+    } else if (entry.isFile()) {
+      const ext = extname2(entry.name).toLowerCase();
+      if (ext && extensions.has(ext)) {
+        results.push(fullPath);
+      }
     }
   }
-  return neighbors;
+  return results;
 }
-function findPath(graph, source, target) {
-  if (!graph.hasNode(source) || !graph.hasNode(target)) {
-    return null;
+async function readFileContent(filePath) {
+  return readFile(filePath, "utf-8");
+}
+
+// src/providers/docstore/id.ts
+import { nanoid } from "nanoid";
+var NANOID_PATTERN = /^[A-Za-z0-9_-]{12}$/;
+var isValidId = (id) => NANOID_PATTERN.test(id);
+var generateId = () => nanoid(12);
+
+// src/providers/docstore/reader-registry.ts
+var ReaderRegistry = class {
+  readers = /* @__PURE__ */ new Map();
+  /**
+   * Register a reader for its declared extensions.
+   * Throws if any extension is already registered (atomic - no partial registration).
+   */
+  register(reader) {
+    for (const ext of reader.extensions) {
+      const normalizedExt = ext.toLowerCase();
+      if (this.readers.has(normalizedExt)) {
+        throw new Error(`Extension already registered: ${ext}`);
+      }
+    }
+    for (const ext of reader.extensions) {
+      const normalizedExt = ext.toLowerCase();
+      this.readers.set(normalizedExt, reader);
+    }
   }
-  if (source === target) {
-    return [source];
+  /**
+   * Get reader for an extension, or null if none registered.
+   * Case-insensitive.
+   */
+  getReader(extension) {
+    return this.readers.get(extension.toLowerCase()) ?? null;
   }
-  const path = bidirectional(graph, source, target);
-  return path;
-}
-function getHubs(graph, metric, limit) {
-  if (limit <= 0) {
-    return [];
+  /**
+   * Get all registered extensions
+   */
+  getExtensions() {
+    return new Set(this.readers.keys());
   }
-  const scores = [];
-  graph.forEachNode((id) => {
-    let score;
-    switch (metric) {
-      case "in_degree":
-        score = graph.inDegree(id);
-        break;
-      case "out_degree":
-        score = graph.outDegree(id);
-        break;
-      case "pagerank":
-        score = graph.inDegree(id);
-        break;
+  /**
+   * Check if an extension has a registered reader.
+   * Case-insensitive.
+   */
+  hasReader(extension) {
+    return this.readers.has(extension.toLowerCase());
+  }
+  /**
+   * Parse content using the appropriate reader for the file's extension.
+   * Validates frontmatter ID and signals if writeback is needed.
+   * Throws if no reader is registered for the extension.
+   *
+   * Note: Does NOT generate new IDs here - that happens in Phase 3's writeback.
+   * Files without valid frontmatter IDs keep their path-based ID for now,
+   * with needsIdWrite: true signaling that an ID should be generated and written.
+   */
+  parse(content, context) {
+    const reader = this.getReader(context.extension);
+    if (!reader) {
+      throw new Error(`No reader registered for extension: ${context.extension}`);
     }
-    scores.push([id, score]);
-  });
-  scores.sort((a, b) => b[1] - a[1]);
-  return scores.slice(0, limit);
-}
-function computeCentrality(graph) {
-  const result = /* @__PURE__ */ new Map();
-  graph.forEachNode((id) => {
-    result.set(id, {
-      inDegree: graph.inDegree(id),
-      outDegree: graph.outDegree(id)
-    });
-  });
-  return result;
-}
+    const node = reader.parse(content, context);
+    const needsIdWrite = !isValidId(node.id);
+    return { node, needsIdWrite };
+  }
+};
+
+// src/providers/docstore/readers/markdown.ts
+var MarkdownReader = class {
+  extensions = [".md", ".markdown"];
+  parse(content, context) {
+    const parsed = parseMarkdown(content);
+    const id = parsed.id ?? normalizeId(context.relativePath);
+    const title = parsed.title ?? titleFromPath(id);
+    const rawLinks = extractWikiLinks(parsed.content);
+    const outgoingLinks = rawLinks.map((link) => normalizeWikiLink(link));
+    return {
+      id,
+      title,
+      content: parsed.content,
+      tags: parsed.tags,
+      outgoingLinks,
+      properties: parsed.properties,
+      sourceRef: {
+        type: "file",
+        path: context.absolutePath,
+        lastModified: context.mtime
+      }
+    };
+  }
+};
 
 // src/providers/docstore/index.ts
-var DocStore = class _DocStore {
+function createDefaultRegistry() {
+  const registry = new ReaderRegistry();
+  registry.register(new MarkdownReader());
+  return registry;
+}
+var DocStore = class extends StoreProvider {
+  id;
   cache;
   sourceRoot;
-  graph = null;
-  vectorProvider;
-  ownsVectorProvider;
-  watcher = null;
-  debounceTimer = null;
-  pendingChanges = /* @__PURE__ */ new Map();
+  ownsVectorIndex;
+  registry;
+  fileWatcher = null;
   onChangeCallback;
-  constructor(sourceRoot, cacheDir, vectorProvider) {
+  constructor(options) {
+    const {
+      sourceRoot,
+      cacheDir,
+      id = "docstore",
+      vectorIndex,
+      registry,
+      fileWatcher
+    } = options;
+    const ownsVector = !vectorIndex;
+    if (!vectorIndex) mkdirSync2(cacheDir, { recursive: true });
+    const vi = vectorIndex ?? new SqliteVectorIndex(cacheDir);
+    super({ vectorIndex: vi });
+    this.id = id;
     this.sourceRoot = sourceRoot;
     this.cache = new Cache(cacheDir);
-    this.ownsVectorProvider = !vectorProvider;
-    this.vectorProvider = vectorProvider ?? new SqliteVectorProvider(cacheDir);
+    this.ownsVectorIndex = ownsVector;
+    this.registry = registry ?? createDefaultRegistry();
+    this.fileWatcher = fileWatcher ?? null;
   }
   async sync() {
-    const currentPaths = await this.collectMarkdownFiles(this.sourceRoot);
-    const trackedPaths = this.cache.getAllTrackedPaths();
-    for (const filePath of currentPaths) {
-      try {
-        const mtime = await this.getFileMtime(filePath);
-        const cachedMtime = this.cache.getModifiedTime(filePath);
-        if (cachedMtime === null || mtime > cachedMtime) {
-          const node = await this.fileToNode(filePath);
-          this.cache.upsertNode(node, "file", filePath, mtime);
-        }
-      } catch (err) {
-        if (err.code === "ENOENT") {
+    if (this.fileWatcher?.isWatching()) {
+      this.fileWatcher.pause();
+    }
+    try {
+      const extensions = this.registry.getExtensions();
+      const currentPaths = await collectFiles(this.sourceRoot, extensions);
+      const trackedPaths = this.cache.getAllTrackedPaths();
+      const seenIds = /* @__PURE__ */ new Map();
+      for (const filePath of currentPaths) {
+        try {
+          const mtime = await getFileMtime(filePath);
+          const cachedMtime = this.cache.getModifiedTime(filePath);
+          if (cachedMtime === null || mtime > cachedMtime) {
+            const { node, needsIdWrite, newMtime } = await this.parseAndMaybeWriteId(filePath, mtime);
+            const existingPath = seenIds.get(node.id);
+            if (existingPath) {
+              console.warn(
+                `Duplicate ID ${node.id} found in ${filePath} (first seen in ${existingPath}):`,
+                new Error("Skipping duplicate")
+              );
+              continue;
+            }
+            seenIds.set(node.id, filePath);
+            const finalMtime = needsIdWrite ? newMtime ?? mtime : mtime;
+            this.cache.upsertNode(node, "file", filePath, finalMtime);
+          } else {
+            const existingNode = this.cache.getNodeByPath(filePath);
+            if (existingNode) {
+              const existingPath = seenIds.get(existingNode.id);
+              if (existingPath) {
+                console.warn(
+                  `Duplicate ID ${existingNode.id} found in ${filePath} (first seen in ${existingPath}):`,
+                  new Error("Skipping duplicate")
+                );
+                this.cache.deleteNode(existingNode.id);
+              } else {
+                seenIds.set(existingNode.id, filePath);
+              }
+            }
+          }
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            continue;
+          }
+          console.warn(`Failed to process file ${filePath}:`, err);
           continue;
         }
-        throw err;
       }
-    }
-    const currentSet = new Set(currentPaths);
-    for (const tracked of trackedPaths) {
-      if (!currentSet.has(tracked)) {
-        const node = this.cache.getNodeByPath(tracked);
-        if (node) {
-          this.cache.deleteNode(node.id);
+      const currentSet = new Set(currentPaths);
+      for (const tracked of trackedPaths) {
+        if (!currentSet.has(tracked)) {
+          const node = this.cache.getNodeByPath(tracked);
+          if (node) {
+            this.cache.deleteNode(node.id);
+          }
         }
       }
+      this.resolveAllLinks();
+      await this.syncGraph();
+    } finally {
+      if (this.fileWatcher?.isWatching()) {
+        this.fileWatcher.resume();
+      }
     }
-    const filenameIndex = this.buildFilenameIndex();
-    this.resolveOutgoingLinks(filenameIndex);
-    this.rebuildGraph();
   }
   async createNode(node) {
-    const normalizedId = normalizeId(node.id);
-    this.validatePathWithinSource(normalizedId);
-    const existing = this.cache.getNode(normalizedId);
-    if (existing) {
-      throw new Error(`Node already exists: ${normalizedId}`);
+    const normalizedPath = normalizeId(node.id);
+    validatePathWithinSource(this.sourceRoot, normalizedPath);
+    const existingByPath = this.cache.getNodeByPath(join4(this.sourceRoot, normalizedPath));
+    if (existingByPath) {
+      throw new Error(`Node already exists: ${normalizedPath}`);
     }
-    const filePath = join3(this.sourceRoot, normalizedId);
+    const filePath = join4(this.sourceRoot, normalizedPath);
     const dir = dirname(filePath);
     await mkdir(dir, { recursive: true });
+    const stableId = generateId();
+    const rawLinks = extractWikiLinks(node.content);
     const parsed = {
+      id: stableId,
       title: node.title,
       tags: node.tags,
       properties: node.properties,
-      content: node.content
+      content: node.content,
+      rawLinks
     };
     const markdown = serializeToMarkdown(parsed);
     await writeFile(filePath, markdown, "utf-8");
-    const mtime = await this.getFileMtime(filePath);
-    const normalizedNode = { ...node, id: normalizedId };
-    this.cache.upsertNode(normalizedNode, "file", filePath, mtime);
-    this.rebuildGraph();
+    let outgoingLinks = node.outgoingLinks;
+    if (node.content && (!outgoingLinks || outgoingLinks.length === 0)) {
+      outgoingLinks = rawLinks.map((link) => normalizeWikiLink(link));
+    }
+    const mtime = await getFileMtime(filePath);
+    const createdNode = {
+      ...node,
+      id: stableId,
+      outgoingLinks,
+      sourceRef: {
+        type: "file",
+        path: filePath,
+        lastModified: new Date(mtime)
+      }
+    };
+    this.cache.upsertNode(createdNode, "file", filePath, mtime);
+    this.resolveAllLinks();
+    await this.syncGraph();
   }
   async updateNode(id, updates) {
-    const normalizedId = normalizeId(id);
-    const existing = this.cache.getNode(normalizedId);
+    let existing = this.cache.getNode(id);
     if (!existing) {
-      throw new Error(`Node not found: ${id}`);
+      const normalizedId = normalizeId(id);
+      existing = this.cache.getNode(normalizedId);
     }
-    let outgoingLinks = updates.outgoingLinks;
-    if (updates.content !== void 0 && outgoingLinks === void 0) {
-      const rawLinks = extractWikiLinks(updates.content);
-      outgoingLinks = rawLinks.map((link) => this.normalizeWikiLink(link));
+    if (!existing && (id.includes(".") || id.includes("/"))) {
+      const fullPath = join4(this.sourceRoot, normalizeId(id));
+      existing = this.cache.getNodeByPath(fullPath);
+    }
+    if (!existing) {
+      throw new Error(`Node not found: ${id}`);
     }
+    const { ...safeUpdates } = updates;
+    const contentForLinks = safeUpdates.content ?? existing.content;
+    const rawLinks = extractWikiLinks(contentForLinks);
+    const outgoingLinks = rawLinks.map((link) => normalizeWikiLink(link));
     const updated = {
       ...existing,
-      ...updates,
-      outgoingLinks: outgoingLinks ?? existing.outgoingLinks,
+      ...safeUpdates,
+      outgoingLinks,
       id: existing.id
-      // ID cannot be changed
+      // Preserve original ID
     };
-    const filePath = join3(this.sourceRoot, existing.id);
+    const filePath = existing.sourceRef?.path ?? join4(this.sourceRoot, existing.id);
     const parsed = {
+      id: existing.id,
+      // Write the stable ID back to frontmatter
       title: updated.title,
       tags: updated.tags,
       properties: updated.properties,
-      content: updated.content
+      content: updated.content,
+      rawLinks
     };
     const markdown = serializeToMarkdown(parsed);
     await writeFile(filePath, markdown, "utf-8");
-    const mtime = await this.getFileMtime(filePath);
+    const mtime = await getFileMtime(filePath);
     this.cache.upsertNode(updated, "file", filePath, mtime);
-    if (outgoingLinks !== void 0 || updates.outgoingLinks !== void 0) {
-      this.rebuildGraph();
-    }
+    this.resolveAllLinks();
+    await this.syncGraph();
   }
   async deleteNode(id) {
-    const normalizedId = normalizeId(id);
-    const existing = this.cache.getNode(normalizedId);
+    let existing = this.cache.getNode(id);
+    if (!existing) {
+      const normalizedId = normalizeId(id);
+      existing = this.cache.getNode(normalizedId);
+    }
+    if (!existing && (id.includes(".") || id.includes("/"))) {
+      const fullPath = join4(this.sourceRoot, normalizeId(id));
+      existing = this.cache.getNodeByPath(fullPath);
+    }
     if (!existing) {
       throw new Error(`Node not found: ${id}`);
     }
-    const filePath = join3(this.sourceRoot, existing.id);
+    const filePath = existing.sourceRef?.path ?? join4(this.sourceRoot, existing.id);
     await rm(filePath);
     this.cache.deleteNode(existing.id);
-    await this.vectorProvider.delete(existing.id);
-    this.rebuildGraph();
+    if (this.vectorIndex) await this.vectorIndex.delete(existing.id);
+    await this.syncGraph();
   }
   async getNode(id) {
+    let node = this.cache.getNode(id);
+    if (node) return node;
     const normalizedId = normalizeId(id);
-    return this.cache.getNode(normalizedId);
+    if (normalizedId !== id) {
+      node = this.cache.getNode(normalizedId);
+      if (node) return node;
+    }
+    if (id.includes(".") || id.includes("/")) {
+      const fullPath = join4(this.sourceRoot, normalizedId);
+      node = this.cache.getNodeByPath(fullPath);
+    }
+    return node;
   }
   async getNodes(ids) {
-    const normalizedIds = ids.map(normalizeId);
-    return this.cache.getNodes(normalizedIds);
+    const results = [];
+    for (const id of ids) {
+      const node = await this.getNode(id);
+      if (node) results.push(node);
+    }
+    return results;
   }
   async getAllNodeIds() {
     const nodes = this.cache.getAllNodes();
     return nodes.map((n) => n.id);
   }
-  async searchByTags(tags, mode) {
-    return this.cache.searchByTags(tags, mode);
-  }
-  async getRandomNode(tags) {
-    let candidates;
-    if (tags && tags.length > 0) {
-      candidates = await this.searchByTags(tags, "any");
-    } else {
-      candidates = this.cache.getAllNodes();
-    }
-    if (candidates.length === 0) {
-      return null;
-    }
-    const randomIndex = Math.floor(Math.random() * candidates.length);
-    return candidates[randomIndex];
+  async searchByTags(tags, mode, limit) {
+    return this.cache.searchByTags(tags, mode, limit);
   }
   async resolveTitles(ids) {
     return this.cache.resolveTitles(ids);
@@ -891,267 +1681,209 @@ var DocStore = class _DocStore {
     return names.map((query) => ({ query, match: null, score: 0 }));
   }
   async nodesExist(ids) {
-    const normalizedIds = ids.map(normalizeId);
-    return this.cache.nodesExist(normalizedIds);
-  }
-  async getNeighbors(id, options) {
-    this.ensureGraph();
-    const neighborIds = getNeighborIds(this.graph, id, options);
-    return this.cache.getNodes(neighborIds);
-  }
-  async findPath(source, target) {
-    this.ensureGraph();
-    return findPath(this.graph, source, target);
-  }
-  async getHubs(metric, limit) {
-    this.ensureGraph();
-    return getHubs(this.graph, metric, limit);
-  }
-  async storeEmbedding(id, vector, model) {
-    return this.vectorProvider.store(id, vector, model);
-  }
-  async searchByVector(vector, limit) {
-    return this.vectorProvider.search(vector, limit);
+    const result = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const node = await this.getNode(id);
+      result.set(normalizeId(id), node !== null);
+    }
+    return result;
   }
   hasEmbedding(id) {
-    return this.vectorProvider.hasEmbedding(id);
+    if (!this.vectorIndex) return false;
+    return this.vectorIndex.hasEmbedding(id);
   }
   close() {
     this.stopWatching();
     this.cache.close();
-    if (this.ownsVectorProvider && "close" in this.vectorProvider) {
-      this.vectorProvider.close();
+    if (this.ownsVectorIndex && this.vectorIndex && "close" in this.vectorIndex) {
+      this.vectorIndex.close();
     }
   }
+  // Lifecycle hooks
+  async onRegister() {
+    await this.sync();
+  }
+  async onUnregister() {
+    this.close();
+  }
   startWatching(onChange) {
-    if (this.watcher) {
+    if (this.fileWatcher?.isWatching()) {
       throw new Error("Already watching. Call stopWatching() first.");
     }
     this.onChangeCallback = onChange;
-    return new Promise((resolve2, reject) => {
-      this.watcher = watch(this.sourceRoot, {
-        ignoreInitial: true,
-        ignored: [..._DocStore.EXCLUDED_DIRS].map((dir) => `**/${dir}/**`),
-        awaitWriteFinish: {
-          stabilityThreshold: 100
-        },
-        followSymlinks: false
-      });
-      this.watcher.on("ready", () => resolve2()).on("add", (path) => this.queueChange(path, "add")).on("change", (path) => this.queueChange(path, "change")).on("unlink", (path) => this.queueChange(path, "unlink")).on("error", (err) => {
-        if (err.code === "EMFILE") {
-          console.error(
-            "File watcher hit file descriptor limit. Try: ulimit -n 65536 or reduce watched files."
-          );
-        }
-        reject(err);
+    if (!this.fileWatcher) {
+      this.fileWatcher = new FileWatcher({
+        root: this.sourceRoot,
+        extensions: this.registry.getExtensions(),
+        onBatch: (events) => this.handleWatcherBatch(events)
       });
-    });
+    }
+    return this.fileWatcher.start();
   }
   stopWatching() {
-    if (this.debounceTimer) {
-      clearTimeout(this.debounceTimer);
-      this.debounceTimer = null;
-    }
-    this.pendingChanges.clear();
-    if (this.watcher) {
-      this.watcher.close();
-      this.watcher = null;
+    if (this.fileWatcher) {
+      this.fileWatcher.stop();
     }
   }
   isWatching() {
-    return this.watcher !== null;
-  }
-  queueChange(filePath, event) {
-    const relativePath = relative(this.sourceRoot, filePath);
-    const id = normalizeId(relativePath);
-    if (!filePath.endsWith(".md")) {
-      return;
-    }
-    const pathParts = relativePath.split("/");
-    for (const part of pathParts) {
-      if (_DocStore.EXCLUDED_DIRS.has(part)) {
-        return;
-      }
-    }
-    const existing = this.pendingChanges.get(id);
-    if (existing) {
-      if (existing === "add" && event === "change") {
-        return;
-      } else if (existing === "add" && event === "unlink") {
-        this.pendingChanges.delete(id);
-      } else if (existing === "change" && event === "unlink") {
-        this.pendingChanges.set(id, "unlink");
-      }
-    } else {
-      this.pendingChanges.set(id, event);
-    }
-    if (this.debounceTimer) {
-      clearTimeout(this.debounceTimer);
-    }
-    this.debounceTimer = setTimeout(() => {
-      this.processQueue();
-    }, 1e3);
+    return this.fileWatcher?.isWatching() ?? false;
   }
-  async processQueue() {
-    const changes = new Map(this.pendingChanges);
-    this.pendingChanges.clear();
-    this.debounceTimer = null;
+  async handleWatcherBatch(events) {
+    this.fileWatcher?.pause();
     const processedIds = [];
-    for (const [id, event] of changes) {
-      try {
-        if (event === "unlink") {
-          const existing = this.cache.getNode(id);
-          if (existing) {
-            this.cache.deleteNode(id);
-            await this.vectorProvider.delete(id);
-            processedIds.push(id);
+    try {
+      for (const [pathId, event] of events) {
+        const filePath = join4(this.sourceRoot, pathId);
+        try {
+          if (event === "unlink") {
+            const existing = this.cache.getNodeByPath(filePath);
+            if (existing) {
+              this.cache.deleteNode(existing.id);
+              if (this.vectorIndex) {
+                try {
+                  await this.vectorIndex.delete(existing.id);
+                } catch (vectorErr) {
+                  console.warn(`Vector delete failed for ${pathId}:`, vectorErr);
+                }
+              }
+              processedIds.push(existing.id);
+            }
+          } else {
+            const mtime = await getFileMtime(filePath);
+            const { node, newMtime } = await this.parseAndMaybeWriteId(filePath, mtime);
+            const finalMtime = newMtime ?? mtime;
+            const existingByPath = this.cache.getNodeByPath(filePath);
+            if (existingByPath && existingByPath.id !== node.id) {
+              this.cache.deleteNode(existingByPath.id);
+              if (this.vectorIndex) {
+                try {
+                  await this.vectorIndex.delete(existingByPath.id);
+                } catch {
+                }
+              }
+            }
+            this.cache.upsertNode(node, "file", filePath, finalMtime);
+            processedIds.push(node.id);
           }
-        } else {
-          const filePath = join3(this.sourceRoot, id);
-          const node = await this.fileToNode(filePath);
-          const mtime = await this.getFileMtime(filePath);
-          this.cache.upsertNode(node, "file", filePath, mtime);
-          processedIds.push(id);
+        } catch (err) {
+          console.warn(`Failed to process file change for ${pathId}:`, err);
         }
-      } catch (err) {
-        console.warn(`Failed to process file change for ${id}:`, err);
       }
+      if (processedIds.length > 0) {
+        this.resolveAllLinks();
+        await this.syncGraph();
+      }
+      if (this.onChangeCallback && processedIds.length > 0) {
+        this.onChangeCallback(processedIds);
+      }
+    } finally {
+      this.fileWatcher?.resume();
     }
-    if (processedIds.length > 0) {
-      const filenameIndex = this.buildFilenameIndex();
-      this.resolveOutgoingLinks(filenameIndex);
-      this.rebuildGraph();
-    }
-    if (this.onChangeCallback && processedIds.length > 0) {
-      this.onChangeCallback(processedIds);
-    }
-  }
-  buildFilenameIndex() {
-    const index = /* @__PURE__ */ new Map();
-    for (const node of this.cache.getAllNodes()) {
-      const basename = node.id.split("/").pop();
-      const existing = index.get(basename) ?? [];
-      existing.push(node.id);
-      index.set(basename, existing);
-    }
-    for (const paths of index.values()) {
-      paths.sort();
-    }
-    return index;
   }
-  resolveOutgoingLinks(filenameIndex) {
-    const validNodeIds = /* @__PURE__ */ new Set();
-    for (const paths of filenameIndex.values()) {
-      for (const path of paths) {
-        validNodeIds.add(path);
+  resolveAllLinks() {
+    const nodes = this.cache.getAllNodes();
+    const filenameIndex = buildFilenameIndex(nodes);
+    const validNodeIds = new Set(nodes.map((n) => n.id));
+    const pathToId = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      if (node.sourceRef?.path) {
+        const relativePath = relative2(this.sourceRoot, node.sourceRef.path);
+        const normalizedPath = normalizeId(relativePath);
+        pathToId.set(normalizedPath, node.id);
       }
     }
-    for (const node of this.cache.getAllNodes()) {
-      const resolved = node.outgoingLinks.map((link) => {
+    for (const node of nodes) {
+      const resolvedIds = resolveLinks(
+        node.outgoingLinks,
+        filenameIndex,
+        validNodeIds
+      );
+      const finalIds = resolvedIds.map((link) => {
         if (validNodeIds.has(link)) {
           return link;
         }
-        if (link.includes("/")) {
-          return link;
-        }
-        const matches = filenameIndex.get(link);
-        if (matches && matches.length > 0) {
-          return matches[0];
-        }
-        return link;
+        const stableId = pathToId.get(link);
+        return stableId ?? link;
       });
-      if (resolved.some((r, i) => r !== node.outgoingLinks[i])) {
-        this.cache.updateOutgoingLinks(node.id, resolved);
+      if (finalIds.some((r, i) => r !== node.outgoingLinks[i])) {
+        this.cache.updateOutgoingLinks(node.id, finalIds);
       }
     }
   }
-  ensureGraph() {
-    if (!this.graph) {
-      this.rebuildGraph();
-    }
+  // ── Graph operations (override for path-based lookup) ─────
+  async getNeighbors(id, options) {
+    const node = await this.getNode(id);
+    if (!node) return [];
+    return super.getNeighbors(node.id, options);
   }
-  rebuildGraph() {
-    const nodes = this.cache.getAllNodes();
-    this.graph = buildGraph(nodes);
-    const centrality = computeCentrality(this.graph);
+  async findPath(source, target) {
+    const sourceNode = await this.getNode(source);
+    const targetNode = await this.getNode(target);
+    if (!sourceNode || !targetNode) return null;
+    return super.findPath(sourceNode.id, targetNode.id);
+  }
+  async getHubs(metric, limit) {
+    return super.getHubs(metric, limit);
+  }
+  // ── StoreProvider abstract method implementations ─────────
+  async loadAllNodes() {
+    return this.cache.getAllNodes();
+  }
+  async getNodesByIds(ids) {
+    return this.cache.getNodes(ids);
+  }
+  onCentralityComputed(centrality) {
     const now = Date.now();
     for (const [id, metrics] of centrality) {
       this.cache.storeCentrality(id, 0, metrics.inDegree, metrics.outDegree, now);
     }
   }
-  static EXCLUDED_DIRS = /* @__PURE__ */ new Set([".roux", "node_modules", ".git", ".obsidian"]);
-  async collectMarkdownFiles(dir) {
-    const results = [];
-    let entries;
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch {
-      return results;
-    }
-    for (const entry of entries) {
-      const fullPath = join3(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (_DocStore.EXCLUDED_DIRS.has(entry.name)) {
-          continue;
-        }
-        const nested = await this.collectMarkdownFiles(fullPath);
-        results.push(...nested);
-      } else if (entry.isFile() && entry.name.endsWith(".md")) {
-        results.push(fullPath);
-      }
+  /**
+   * Parse a file and optionally write a generated ID back if missing.
+   * Returns the node (with stable ID) and whether a write occurred.
+   */
+  async parseAndMaybeWriteId(filePath, originalMtime) {
+    const content = await readFileContent(filePath);
+    const relativePath = relative2(this.sourceRoot, filePath);
+    const ext = extname3(filePath).toLowerCase();
+    const actualMtime = new Date(originalMtime);
+    const context = {
+      absolutePath: filePath,
+      relativePath,
+      extension: ext,
+      mtime: actualMtime
+    };
+    const { node, needsIdWrite } = this.registry.parse(content, context);
+    if (!needsIdWrite) {
+      return { node, needsIdWrite: false };
     }
-    return results;
-  }
-  async getFileMtime(filePath) {
-    const stats = await stat(filePath);
-    return stats.mtimeMs;
-  }
-  async fileToNode(filePath) {
-    const raw = await readFile(filePath, "utf-8");
-    const parsed = parseMarkdown(raw);
-    const relativePath = relative(this.sourceRoot, filePath);
-    const id = normalizeId(relativePath);
-    const title = parsed.title ?? titleFromPath(id);
-    const rawLinks = extractWikiLinks(parsed.content);
-    const outgoingLinks = rawLinks.map((link) => this.normalizeWikiLink(link));
-    return {
-      id,
-      title,
-      content: parsed.content,
-      tags: parsed.tags,
-      outgoingLinks,
-      properties: parsed.properties,
-      sourceRef: {
-        type: "file",
-        path: filePath,
-        lastModified: new Date(await this.getFileMtime(filePath))
-      }
+    const newId = generateId();
+    const writebackSuccess = await this.writeIdBack(filePath, newId, originalMtime, content);
+    if (!writebackSuccess) {
+      console.warn(`File modified during sync, skipping ID writeback: ${filePath}`);
+      return { node, needsIdWrite: true };
+    }
+    const updatedNode = {
+      ...node,
+      id: newId
     };
+    const newMtime = await getFileMtime(filePath);
+    return { node: updatedNode, needsIdWrite: true, newMtime };
   }
   /**
-   * Normalize a wiki-link target to an ID.
-   * - If it has a file extension, normalize as-is
-   * - If no extension, add .md
-   * - Lowercase, forward slashes
+   * Write a generated ID back to file's frontmatter.
+   * Returns false if file was modified since originalMtime (race condition).
    */
-  normalizeWikiLink(target) {
-    let normalized = target.toLowerCase().replace(/\\/g, "/");
-    if (!this.hasFileExtension(normalized)) {
-      normalized += ".md";
-    }
-    return normalized;
-  }
-  hasFileExtension(path) {
-    const match = path.match(/\.([a-z0-9]{1,4})$/i);
-    if (!match?.[1]) return false;
-    return /[a-z]/i.test(match[1]);
-  }
-  validatePathWithinSource(id) {
-    const resolvedPath = resolve(this.sourceRoot, id);
-    const resolvedRoot = resolve(this.sourceRoot);
-    if (!resolvedPath.startsWith(resolvedRoot + "/")) {
-      throw new Error(`Path traversal detected: ${id} resolves outside source root`);
+  async writeIdBack(filePath, nodeId, originalMtime, originalContent) {
+    const currentStat = await stat2(filePath);
+    if (currentStat.mtimeMs !== originalMtime) {
+      return false;
     }
+    const parsed = parseMarkdown(originalContent);
+    parsed.id = nodeId;
+    const newContent = serializeToMarkdown(parsed);
+    await writeFile(filePath, newContent, "utf-8");
+    return true;
   }
 };
 
@@ -1159,11 +1891,18 @@ var DocStore = class _DocStore {
 import { pipeline } from "@xenova/transformers";
 var DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
 var DEFAULT_DIMENSIONS = 384;
-var TransformersEmbeddingProvider = class {
+var TransformersEmbedding = class {
+  id;
   model;
   dims;
   pipe = null;
-  constructor(model = DEFAULT_MODEL, dimensions = DEFAULT_DIMENSIONS) {
+  constructor(options = {}) {
+    const {
+      model = DEFAULT_MODEL,
+      dimensions = DEFAULT_DIMENSIONS,
+      id = "transformers-embedding"
+    } = options;
+    this.id = id;
     this.model = model;
     this.dims = dimensions;
   }
@@ -1190,33 +1929,93 @@ var TransformersEmbeddingProvider = class {
   modelId() {
     return this.model;
   }
+  // Lifecycle hooks
+  async onRegister() {
+  }
+  async onUnregister() {
+    this.pipe = null;
+  }
 };
 
 // src/core/graphcore.ts
 var GraphCoreImpl = class _GraphCoreImpl {
   store = null;
   embedding = null;
-  registerStore(provider) {
+  async registerStore(provider) {
     if (!provider) {
       throw new Error("Store provider is required");
     }
+    if (!isStoreProvider(provider)) {
+      throw new Error("Invalid Store provider: missing required methods or id");
+    }
+    if (this.store?.onUnregister) {
+      try {
+        await this.store.onUnregister();
+      } catch (err) {
+        console.warn("Error during store onUnregister:", err);
+      }
+    }
     this.store = provider;
+    if (provider.onRegister) {
+      try {
+        await provider.onRegister();
+      } catch (err) {
+        this.store = null;
+        throw err;
+      }
+    }
   }
-  registerEmbedding(provider) {
+  async registerEmbedding(provider) {
     if (!provider) {
       throw new Error("Embedding provider is required");
     }
+    if (!isEmbeddingProvider(provider)) {
+      throw new Error("Invalid Embedding provider: missing required methods or id");
+    }
+    if (this.embedding?.onUnregister) {
+      try {
+        await this.embedding.onUnregister();
+      } catch (err) {
+        console.warn("Error during embedding onUnregister:", err);
+      }
+    }
     this.embedding = provider;
+    if (provider.onRegister) {
+      try {
+        await provider.onRegister();
+      } catch (err) {
+        this.embedding = null;
+        throw err;
+      }
+    }
+  }
+  async destroy() {
+    if (this.embedding?.onUnregister) {
+      try {
+        await this.embedding.onUnregister();
+      } catch (err) {
+        console.warn("Error during embedding onUnregister in destroy:", err);
+      }
+    }
+    if (this.store?.onUnregister) {
+      try {
+        await this.store.onUnregister();
+      } catch (err) {
+        console.warn("Error during store onUnregister in destroy:", err);
+      }
+    }
+    this.embedding = null;
+    this.store = null;
   }
   requireStore() {
     if (!this.store) {
-      throw new Error("StoreProvider not registered");
+      throw new Error("Store not registered");
     }
     return this.store;
   }
   requireEmbedding() {
     if (!this.embedding) {
-      throw new Error("EmbeddingProvider not registered");
+      throw new Error("Embedding not registered");
     }
     return this.embedding;
   }
@@ -1309,11 +2108,7 @@ var GraphCoreImpl = class _GraphCoreImpl {
   }
   async searchByTags(tags, mode, limit) {
     const store = this.requireStore();
-    const results = await store.searchByTags(tags, mode);
-    if (limit !== void 0) {
-      return results.slice(0, limit);
-    }
-    return results;
+    return store.searchByTags(tags, mode, limit);
   }
   async getRandomNode(tags) {
     const store = this.requireStore();
@@ -1327,7 +2122,7 @@ var GraphCoreImpl = class _GraphCoreImpl {
     const strategy = options?.strategy ?? "fuzzy";
     if (strategy === "semantic") {
       if (!this.embedding) {
-        throw new Error("Semantic resolution requires EmbeddingProvider");
+        throw new Error("Semantic resolution requires Embedding");
       }
       const filter = {};
       if (options?.tag) filter.tag = options.tag;
@@ -1354,7 +2149,7 @@ var GraphCoreImpl = class _GraphCoreImpl {
         let bestScore = 0;
         let bestMatch = null;
         for (let cIdx = 0; cIdx < candidates.length; cIdx++) {
-          const similarity = this.cosineSimilarity(queryVector, candidateVectors[cIdx]);
+          const similarity = cosineSimilarity(queryVector, candidateVectors[cIdx]);
           if (similarity > bestScore) {
             bestScore = similarity;
             bestMatch = candidates[cIdx].id;
@@ -1368,58 +2163,53 @@ var GraphCoreImpl = class _GraphCoreImpl {
     }
     return store.resolveNodes(names, options);
   }
-  cosineSimilarity(a, b) {
-    let dotProduct = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-      dotProduct += a[i] * b[i];
-      normA += a[i] * a[i];
-      normB += b[i] * b[i];
-    }
-    if (normA === 0 || normB === 0) return 0;
-    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
-  }
-  static fromConfig(config) {
+  static async fromConfig(config) {
     if (!config.providers?.store) {
-      throw new Error("StoreProvider configuration is required");
+      throw new Error("Store configuration is required");
     }
     const core = new _GraphCoreImpl();
-    if (config.providers.store.type === "docstore") {
-      const sourcePath = config.source?.path ?? ".";
-      const cachePath = config.cache?.path ?? ".roux";
-      const store = new DocStore(sourcePath, cachePath);
-      core.registerStore(store);
-    } else {
-      throw new Error(
-        `Unsupported store provider type: ${config.providers.store.type}. Supported: docstore`
-      );
-    }
-    const embeddingConfig = config.providers.embedding;
-    if (!embeddingConfig || embeddingConfig.type === "local") {
-      const model = embeddingConfig?.model;
-      const embedding = new TransformersEmbeddingProvider(model);
-      core.registerEmbedding(embedding);
-    } else {
-      throw new Error(
-        `Unsupported embedding provider type: ${embeddingConfig.type}. Supported: local`
-      );
+    try {
+      if (config.providers.store.type === "docstore") {
+        const sourcePath = config.source?.path ?? ".";
+        const cachePath = config.cache?.path ?? ".roux";
+        const store = new DocStore({ sourceRoot: sourcePath, cacheDir: cachePath });
+        await core.registerStore(store);
+      } else {
+        throw new Error(
+          `Unsupported store provider type: ${config.providers.store.type}. Supported: docstore`
+        );
+      }
+      const embeddingConfig = config.providers.embedding;
+      if (!embeddingConfig || embeddingConfig.type === "local") {
+        const model = embeddingConfig?.model;
+        const embedding = new TransformersEmbedding(model ? { model } : {});
+        await core.registerEmbedding(embedding);
+      } else {
+        throw new Error(
+          `Unsupported embedding provider type: ${embeddingConfig.type}. Supported: local`
+        );
+      }
+      return core;
+    } catch (err) {
+      await core.destroy();
+      throw err;
     }
-    return core;
   }
 };
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.3";
 export {
   DEFAULT_CONFIG,
   DocStore,
   GraphCoreImpl,
-  SqliteVectorProvider,
-  TransformersEmbeddingProvider,
+  SqliteVectorIndex,
+  StoreProvider,
+  TransformersEmbedding,
   VERSION,
+  createGuard,
   isNode,
   isSourceRef,
-  isVectorProvider
+  isVectorIndex
 };
 //# sourceMappingURL=index.js.map