@esneiderbravo/speclaw 0.3.13 → 1.0.0

package/dist/modules/compass/db.js

@@ -1,6 +1,7 @@
 import { DatabaseSync } from "node:sqlite";
 import fs from "node:fs";
 import path from "node:path";
+import { contentHashFor, defaultEmbedText } from "./embed-input.js";
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS meta (
   key TEXT PRIMARY KEY,
@@ -12,7 +13,9 @@ CREATE TABLE IF NOT EXISTS files (
   hash TEXT NOT NULL,
   lang TEXT NOT NULL,
   is_test INTEGER NOT NULL DEFAULT 0,
-  module TEXT NOT NULL DEFAULT ''
+  module TEXT NOT NULL DEFAULT '',
+  mtime_ms INTEGER,
+  size INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_files_is_test ON files(is_test);
 -- nodes: the definitions in the codebase (functions, classes, methods, types).
@@ -28,11 +31,13 @@ CREATE TABLE IF NOT EXISTS nodes (
   parent_id INTEGER,
   signature TEXT,
   body_hash TEXT,
-  norm_hash TEXT
+  norm_hash TEXT,
+  content_hash TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
 CREATE INDEX IF NOT EXISTS idx_nodes_norm_hash ON nodes(norm_hash);
+CREATE INDEX IF NOT EXISTS idx_nodes_content_hash ON nodes(content_hash);
 -- node_metrics: AST health frames (LOC / nesting / branches) per definition.
 CREATE TABLE IF NOT EXISTS node_metrics (
   node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
@@ -53,12 +58,23 @@ CREATE TABLE IF NOT EXISTS edges (
 CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_name);
 CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src_node_id);
 CREATE INDEX IF NOT EXISTS idx_edges_dstid ON edges(dst_node_id);
--- node_embeddings: the local vector store (one embedding per node).
-CREATE TABLE IF NOT EXISTS node_embeddings (
-  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
-  dim INTEGER NOT NULL,
+-- embedding_cache: vectors keyed by embedder-input content hash (survives reindex).
+CREATE TABLE IF NOT EXISTS embedding_cache (
+  content_hash TEXT NOT NULL,
   model TEXT NOT NULL,
-  vec BLOB NOT NULL
+  dim INTEGER NOT NULL,
+  vec BLOB NOT NULL,
+  created_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  PRIMARY KEY (content_hash, model)
+);
+CREATE INDEX IF NOT EXISTS idx_embedding_cache_seen ON embedding_cache(last_seen_at);
+-- dir_hashes: Merkle tree of indexed directories ("" = project root).
+CREATE TABLE IF NOT EXISTS dir_hashes (
+  path TEXT PRIMARY KEY,
+  hash TEXT NOT NULL,
+  n_files INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
 );
 -- git_history_cache: memoized results of the expensive git-history scans
 -- (churn, co-change), keyed by query and invalidated when HEAD moves.
@@ -109,9 +125,104 @@ CREATE TABLE IF NOT EXISTS spec_anchors (
 CREATE INDEX IF NOT EXISTS idx_anchors_capability ON spec_anchors(capability);
 CREATE INDEX IF NOT EXISTS idx_anchors_symbol ON spec_anchors(symbol_name);
 CREATE INDEX IF NOT EXISTS idx_anchors_node ON spec_anchors(node_id);
+-- node_text: searchable name/subtokens/signature/doc (FTS content source).
+CREATE TABLE IF NOT EXISTS node_text (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  subtokens TEXT NOT NULL DEFAULT '',
+  signature TEXT NOT NULL DEFAULT '',
+  doc TEXT NOT NULL DEFAULT ''
+);
+-- pagerank: global (non-personalized) scores recomputed at index time.
+CREATE TABLE IF NOT EXISTS pagerank (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  score REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pagerank_score ON pagerank(score DESC);
 `;
+const FTS_DDL = `
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  name, subtokens, signature, doc,
+  content='node_text', content_rowid='node_id',
+  tokenize="unicode61 remove_diacritics 0 tokenchars '_$'",
+  prefix='2 3'
+);
+CREATE TRIGGER IF NOT EXISTS node_text_ai AFTER INSERT ON node_text BEGIN
+  INSERT INTO nodes_fts(rowid, name, subtokens, signature, doc)
+  VALUES (new.node_id, new.name, new.subtokens, new.signature, new.doc);
+END;
+CREATE TRIGGER IF NOT EXISTS node_text_ad AFTER DELETE ON node_text BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name, subtokens, signature, doc)
+  VALUES ('delete', old.node_id, old.name, old.subtokens, old.signature, old.doc);
+END;
+CREATE TRIGGER IF NOT EXISTS node_text_au AFTER UPDATE ON node_text BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name, subtokens, signature, doc)
+  VALUES ('delete', old.node_id, old.name, old.subtokens, old.signature, old.doc);
+  INSERT INTO nodes_fts(rowid, name, subtokens, signature, doc)
+  VALUES (new.node_id, new.name, new.subtokens, new.signature, new.doc);
+END;
+`;
+/** Ensure node_embeddings is a VIEW over embedding_cache (idempotent). */
+function ensureEmbeddingsView(db) {
+    const row = db
+        .prepare("SELECT type FROM sqlite_master WHERE name = 'node_embeddings' LIMIT 1")
+        .get();
+    if (row?.type === "view")
+        return;
+    if (row?.type === "table") {
+        db.exec("DROP TABLE node_embeddings");
+    }
+    db.exec(`
+    CREATE VIEW node_embeddings AS
+      SELECT n.id AS node_id, ec.dim AS dim, ec.model AS model, ec.vec AS vec
+      FROM nodes n
+      JOIN embedding_cache ec ON ec.content_hash = n.content_hash
+  `);
+}
+/**
+ * Try to create the FTS5 virtual table + sync triggers. Soft-degrades when the
+ * Node SQLite build lacks FTS5 (pre-22.16).
+ *
+ * @returns Whether FTS5 is usable after this call.
+ */
+export function ensureFts(db) {
+    const existing = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'nodes_fts' LIMIT 1").get();
+    if (existing) {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return true;
+    }
+    try {
+        db.exec(FTS_DDL);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return true;
+    }
+    catch {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '0') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return false;
+    }
+}
+/** Whether the open database has a usable FTS5 index. */
+export function ftsAvailable(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'fts5'").get();
+    if (row?.value === "0")
+        return false;
+    const tbl = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'nodes_fts' LIMIT 1").get();
+    return Boolean(tbl);
+}
+/** Probe whether this Node build can create an FTS5 virtual table. */
+export function probeFts5Support() {
+    try {
+        const mem = new DatabaseSync(":memory:");
+        mem.exec("CREATE VIRTUAL TABLE t USING fts5(x)");
+        mem.close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "8";
+export const SCHEMA_VERSION = "10";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -124,10 +235,7 @@ function readSchemaVersion(db) {
 }
 /**
  * Decide whether an existing database is from an incompatible schema and must be
- * rebuilt. A fresh database (no tables) needs no reset — the schema will create
- * them. An existing one is stale if its stamped version differs from the current
- * one, or if the `edges` table is missing a column the current code writes to
- * (guards against past schema changes that weren't version-bumped).
+ * rebuilt. Schema 8→9 and 9→10 are handled by migrators instead of a wipe.
  */
 function isStale(db) {
     const hasEdges = db
@@ -135,7 +243,10 @@ function isStale(db) {
         .get();
     if (!hasEdges)
         return false;
-    if (readSchemaVersion(db) !== SCHEMA_VERSION)
+    const ver = readSchemaVersion(db);
+    if (ver === "8" || ver === "9")
+        return false; // migrate in openDb
+    if (ver !== SCHEMA_VERSION)
         return true;
     const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
     if (!edgeCols.includes("src_node_id") || !edgeCols.includes("dst_node_id"))
@@ -151,10 +262,18 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP VIEW IF EXISTS node_embeddings;
+    DROP TRIGGER IF EXISTS node_text_ai;
+    DROP TRIGGER IF EXISTS node_text_ad;
+    DROP TRIGGER IF EXISTS node_text_au;
+    DROP TABLE IF EXISTS nodes_fts;
+    DROP TABLE IF EXISTS pagerank;
+    DROP TABLE IF EXISTS node_text;
     DROP TABLE IF EXISTS spec_anchors;
     DROP TABLE IF EXISTS coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
-    DROP TABLE IF EXISTS node_embeddings;
+    DROP TABLE IF EXISTS embedding_cache;
+    DROP TABLE IF EXISTS dir_hashes;
     DROP TABLE IF EXISTS edges;
     DROP TABLE IF EXISTS node_metrics;
     DROP TABLE IF EXISTS nodes;
@@ -162,14 +281,131 @@ function resetSchema(db) {
     DROP TABLE IF EXISTS meta;
   `);
 }
+/**
+ * Migrate schema 8 → 9: embedding_cache, dir_hashes, mtime/size, content_hash,
+ * preserve vectors into the cache, replace node_embeddings table with a view.
+ *
+ * @param db - Open connection already at schema 8.
+ * @param projectPath - Project root for backfilling content hashes from disk.
+ */
+export function migrate8to9(db, projectPath) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS embedding_cache (
+        content_hash TEXT NOT NULL,
+        model TEXT NOT NULL,
+        dim INTEGER NOT NULL,
+        vec BLOB NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        PRIMARY KEY (content_hash, model)
+      );
+      CREATE INDEX IF NOT EXISTS idx_embedding_cache_seen ON embedding_cache(last_seen_at);
+      CREATE TABLE IF NOT EXISTS dir_hashes (
+        path TEXT PRIMARY KEY,
+        hash TEXT NOT NULL,
+        n_files INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+        const fileCols = db.prepare("PRAGMA table_info(files)").all().map((c) => c.name);
+        if (!fileCols.includes("mtime_ms"))
+            db.exec("ALTER TABLE files ADD COLUMN mtime_ms INTEGER");
+        if (!fileCols.includes("size"))
+            db.exec("ALTER TABLE files ADD COLUMN size INTEGER");
+        const nodeCols = db.prepare("PRAGMA table_info(nodes)").all().map((c) => c.name);
+        if (!nodeCols.includes("content_hash")) {
+            db.exec("ALTER TABLE nodes ADD COLUMN content_hash TEXT");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_nodes_content_hash ON nodes(content_hash)");
+        }
+        const upd = db.prepare("UPDATE nodes SET content_hash = ? WHERE id = ?");
+        const rows = db
+            .prepare(`SELECT n.id, n.kind, n.name, n.signature, f.lang
+         FROM nodes n JOIN files f ON f.id = n.file_id`)
+            .all();
+        for (const r of rows) {
+            const embedText = defaultEmbedText(r.kind, r.name, r.signature);
+            upd.run(contentHashFor({
+                lang: r.lang,
+                kind: r.kind,
+                name: r.name,
+                signature: r.signature,
+                embedText,
+            }), r.id);
+        }
+        void projectPath;
+        const now = Date.now();
+        const embType = db
+            .prepare("SELECT type FROM sqlite_master WHERE name = 'node_embeddings' LIMIT 1")
+            .get();
+        if (embType?.type === "table") {
+            db.prepare(`INSERT OR IGNORE INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
+         SELECT n.content_hash, ne.model, ne.dim, ne.vec, ?, ?
+         FROM node_embeddings ne
+         JOIN nodes n ON n.id = ne.node_id
+         WHERE n.content_hash IS NOT NULL`).run(now, now);
+            db.exec("DROP TABLE node_embeddings");
+        }
+        ensureEmbeddingsView(db);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("9");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 8→9 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
+    }
+}
+/**
+ * Migrate schema 9 → 10: `node_text`, optional FTS5, `pagerank`. Embedding cache
+ * is left intact; a reindex is required to populate text rows.
+ *
+ * @param db - Open connection already at schema 9.
+ */
+export function migrate9to10(db) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS node_text (
+        node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+        name TEXT NOT NULL,
+        subtokens TEXT NOT NULL DEFAULT '',
+        signature TEXT NOT NULL DEFAULT '',
+        doc TEXT NOT NULL DEFAULT ''
+      );
+      CREATE TABLE IF NOT EXISTS pagerank (
+        node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+        score REAL NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_pagerank_score ON pagerank(score DESC);
+    `);
+        ensureFts(db);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("10");
+        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        db.prepare("INSERT INTO meta(key, value) VALUES ('reindex_reason', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("schema 10 adds full-text index (names, subtokens, signatures, docs); reindex required");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 9→10 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
+    }
+}
 /**
  * Open (creating if needed) the index database at `<projectPath>/.speclaw/index.db`.
  *
  * Ensures the `.speclaw` directory exists, enables WAL journaling and foreign
- * keys, and applies the schema. If an existing database is from an incompatible
- * schema (e.g. after a speclaw upgrade), it is dropped and rebuilt — `.speclaw`
- * is fully regenerable, so the next index just repopulates it. The schema
- * version is stamped on a fresh (or freshly reset) database.
+ * keys, and applies the schema. Schema 8→9 and 9→10 migrate in place
+ * (embeddings preserved). Other incompatible schemas are wiped and rebuilt.
  *
  * @param projectPath - Absolute path to the project root.
  * @returns An open connection to the index database.
@@ -178,19 +414,43 @@ export function openDb(projectPath) {
     const dir = path.join(projectPath, ".speclaw");
     fs.mkdirSync(dir, { recursive: true });
     const db = new DatabaseSync(path.join(dir, "index.db"));
-    db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-    const wiped = isStale(db);
-    if (wiped)
-        resetSchema(db);
-    db.exec(SCHEMA);
-    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
-    if (!row) {
-        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
-    }
-    if (wiped) {
-        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+    db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+    const ver = (() => {
+        try {
+            return readSchemaVersion(db);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (ver === "8") {
+        migrate8to9(db, projectPath);
+        migrate9to10(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+    }
+    else if (ver === "9") {
+        migrate9to10(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+    }
+    else {
+        const wiped = isStale(db);
+        if (wiped)
+            resetSchema(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+        const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+        if (!row) {
+            db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
+        }
+        if (wiped) {
+            db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        }
     }
-    // Projection from committed JSON — safe even when nodes are empty (node_id null).
     rehydrateAnchors(db, projectPath);
     return db;
 }

package/dist/modules/compass/diff-context.js

@@ -0,0 +1,134 @@
+import { isGitRepo, changedFiles, worktreeChangedFiles } from "../../shared/git.js";
+import { openDb, indexExists } from "./db.js";
+import { impact } from "./query.js";
+import { affectedTests } from "./affected.js";
+import { hotspots } from "./hotspots.js";
+import { summarizeImpact } from "./impact-summary.js";
+import { applyTextBudget, } from "../../shared/output-budget.js";
+function listWorktreeChanges(projectPath) {
+    const wt = worktreeChangedFiles(projectPath);
+    if (wt.length > 0)
+        return wt;
+    for (const base of ["main", "master"]) {
+        const files = changedFiles(projectPath, base);
+        if (files.length > 0)
+            return files;
+    }
+    return [];
+}
+function symbolsForFiles(projectPath, files, overestimate) {
+    if (!indexExists(projectPath))
+        return [];
+    const db = openDb(projectPath);
+    try {
+        const out = [];
+        for (const file of files) {
+            const nodes = db
+                .prepare(`SELECT n.name, n.kind, n.start_line AS line, f.path AS file
+           FROM nodes n JOIN files f ON f.id = n.file_id
+           WHERE f.path = ?`)
+                .all(file);
+            if (overestimate || nodes.length === 0) {
+                for (const n of nodes)
+                    out.push(n);
+            }
+            else {
+                for (const n of nodes)
+                    out.push(n);
+            }
+        }
+        return out;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Graph context for a set of changed files (git rev, working tree, or explicit paths).
+ *
+ * @param query - Diff scope and output mode.
+ */
+export function diffContext(query) {
+    const mode = query.mode ?? "brief";
+    const truncated = [];
+    let files = [...(query.paths ?? [])];
+    let message;
+    if (files.length === 0) {
+        if (!isGitRepo(query.projectPath)) {
+            throw new Error("not a git repository — pass `paths` explicitly to compass_diff_context");
+        }
+        files =
+            query.rev && query.rev !== "WORKTREE"
+                ? changedFiles(query.projectPath, query.rev)
+                : listWorktreeChanges(query.projectPath);
+    }
+    if (files.length === 0) {
+        return {
+            changedFiles: [],
+            changedSymbols: [],
+            message: "no changed files in scope",
+            truncated,
+        };
+    }
+    if (files.length > 50) {
+        message = `diff touches ${files.length} files — returning aggregated blast radius only; pass paths to narrow`;
+        files = files.slice(0, 50);
+    }
+    const overestimate = Boolean(query.paths?.length && !query.rev);
+    if (overestimate) {
+        message = "symbol set is an overestimate (paths without hunks — all nodes in those files)";
+    }
+    const changedSymbols = symbolsForFiles(query.projectPath, files, overestimate);
+    const result = { changedFiles: files, changedSymbols, truncated, message };
+    try {
+        const imp = impact(query.projectPath, {
+            files,
+            maxDepth: query.maxDepth ?? 4,
+            format: "grouped",
+        });
+        result.blastRadius = summarizeImpact(imp);
+    }
+    catch {
+        /* no index */
+    }
+    try {
+        const at = affectedTests(query.projectPath, {
+            files,
+            fromDiff: query.rev === "WORKTREE" || !query.rev ? "WORKTREE" : query.rev,
+            maxDepth: query.maxDepth ?? 6,
+        });
+        result.affectedTests = {
+            tests: at.tests,
+            command: at.command,
+            mode: at.mode,
+            reason: at.reason,
+        };
+    }
+    catch {
+        /* degrade */
+    }
+    try {
+        const hs = hotspots(query.projectPath, { sortBy: "combined", limit: 200 });
+        const touched = hs.hotspots.filter((h) => files.includes(h.file));
+        result.hotspotsTouched = touched.slice(0, 10).map((h) => ({
+            file: h.file,
+            combinedScore: h.combinedScore,
+        }));
+    }
+    catch {
+        /* degrade */
+    }
+    const json = applyTextBudget(JSON.stringify(result, null, 2), mode);
+    if (json.truncated) {
+        truncated.push({
+            field: "response",
+            omitted: json.omittedChars,
+            hint: 'use mode:"full" or pass explicit paths',
+        });
+    }
+    return result;
+}
+/** Format diff context with output budget. */
+export function formatDiffContext(result, mode = "brief") {
+    return applyTextBudget(JSON.stringify(result, null, 2), mode).text;
+}

package/dist/modules/compass/embed-input.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+/**
+ * Bump when the text (or metadata) fed to the embedder changes shape.
+ * Combined into LexicalEmbedder.id so stale cache rows never match.
+ */
+export const EMBED_INPUT_VERSION = "in2";
+/**
+ * Content-addressable key for `embedding_cache`: hash of the embedder recipe,
+ * not the file path and not solely `body_hash` (drift uses a different recipe).
+ *
+ * @param input - Language, kind, name, optional signature, and embedder text.
+ */
+export function contentHashFor(input) {
+    return createHash("sha256")
+        .update([
+        EMBED_INPUT_VERSION,
+        input.lang,
+        input.kind,
+        input.name,
+        input.signature ?? "",
+        input.embedText,
+    ].join("\0"))
+        .digest("hex");
+}
+/** Default embedder text for a symbol (matches historical indexer behaviour). */
+export function defaultEmbedText(kind, name, signature) {
+    return `${kind} ${name} ${signature ?? ""}`;
+}

package/dist/modules/compass/embedder.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { EMBED_INPUT_VERSION } from "./embed-input.js";
 /**
  * Split identifiers into lowercase subtokens.
  *
@@ -23,7 +24,8 @@ export function tokenize(text) {
  */
 export class LexicalEmbedder {
     dim;
-    id = "lexical-hash-v1";
+    /** Identity includes embed-input recipe version so cache invalidates on bump. */
+    id = `lexical-hash-v1+${EMBED_INPUT_VERSION}`;
     constructor(dim = 256) {
         this.dim = dim;
     }