trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/ask/graphrank.js

@@ -0,0 +1,130 @@
+import { WALK_RELATIONS } from "../graph/relations.js";
+const emptyTopology = () => ({
+    ids: new Set(),
+    adjacency: new Map(),
+});
+const link = (adjacency, source, target) => {
+    const neighbours = adjacency.get(source);
+    if (neighbours)
+        neighbours.push(target);
+    else
+        adjacency.set(source, [target]);
+};
+/** Build independent PageRank topologies in one node pass and one edge pass.
+ * Edges crossing partitions are excluded, exactly like applying a nodeFilter
+ * for each partition independently. Returning `undefined` omits a node. */
+export function preparePageRankPartitions(graph, partitionOfId) {
+    const partitionById = new Map();
+    const mutable = new Map();
+    for (const node of graph.nodes) {
+        const partition = partitionOfId(node.id);
+        if (partition === undefined)
+            continue;
+        partitionById.set(node.id, partition);
+        const topology = mutable.get(partition);
+        if (topology)
+            topology.ids.add(node.id);
+        else
+            mutable.set(partition, { ids: new Set([node.id]), adjacency: new Map() });
+    }
+    for (const edge of graph.edges) {
+        if (!WALK_RELATIONS.has(edge.relation))
+            continue;
+        const partition = partitionById.get(edge.source);
+        if (partition === undefined || partitionById.get(edge.target) !== partition)
+            continue;
+        const topology = mutable.get(partition);
+        link(topology.adjacency, edge.source, edge.target);
+        link(topology.adjacency, edge.target, edge.source);
+    }
+    return new Map(mutable);
+}
+/** Prepare one optionally filtered topology. Kept public for callers/tests that
+ * reuse the same graph across multiple seed sets. */
+export function preparePageRankTopology(graph, nodeFilter) {
+    const ids = new Set(graph.nodes.map((node) => node.id).filter((id) => !nodeFilter || nodeFilter(id)));
+    if (ids.size === 0)
+        return emptyTopology();
+    const adjacency = new Map();
+    for (const edge of graph.edges) {
+        if (!WALK_RELATIONS.has(edge.relation))
+            continue;
+        if (!ids.has(edge.source) || !ids.has(edge.target))
+            continue;
+        link(adjacency, edge.source, edge.target);
+        link(adjacency, edge.target, edge.source);
+    }
+    return { ids, adjacency };
+}
+/**
+ * Personalized PageRank over the wiring graph.
+ *
+ * `seeds` maps node id → restart weight (a node's lexical score; only positive
+ * weights matter). The graph is treated as UNDIRECTED — for "understand this
+ * area" a callee is as relevant as a caller. Returns a score per node
+ * normalized so the top node is 1; nodes untouched by the walk are absent.
+ *
+ * Edges whose endpoints aren't both real nodes (e.g. an unresolved import
+ * module string) are ignored, so only genuine symbol-to-symbol wiring counts.
+ */
+export function personalizedPageRank(graph, seeds, opts = {}) {
+    return personalizedPageRankPrepared(preparePageRankTopology(graph, opts.nodeFilter), seeds, opts);
+}
+/** Run PageRank on an already prepared topology. This is numerically identical
+ * to {@link personalizedPageRank}; it only removes repeated topology scans. */
+export function personalizedPageRankPrepared(topology, seeds, opts = {}) {
+    const alpha = opts.alpha ?? 0.25;
+    const iters = opts.iters ?? 25;
+    const ids = topology.ids;
+    const adjacency = topology.adjacency;
+    // Restart distribution: seed weights, restricted to real nodes, normalized.
+    let seedTotal = 0;
+    for (const [id, w] of seeds)
+        if (ids.has(id) && w > 0)
+            seedTotal += w;
+    if (seedTotal <= 0)
+        return new Map();
+    const restart = new Map();
+    for (const [id, w] of seeds)
+        if (ids.has(id) && w > 0)
+            restart.set(id, w / seedTotal);
+    // Power iteration from the restart distribution.
+    let rank = new Map(restart);
+    for (let i = 0; i < iters; i++) {
+        const next = new Map();
+        // Teleport: every step, alpha of the mass returns to the seed set.
+        for (const [id, r] of restart)
+            next.set(id, alpha * r);
+        // Dangling mass (nodes with no walk edges) is pooled and returned to the
+        // seed set ONCE per iteration — same math as redistributing per node, but
+        // O(nodes + seeds) instead of O(dangling × seeds).
+        let dangling = 0;
+        for (const [id, mass] of rank) {
+            const nbrs = adjacency.get(id);
+            if (!nbrs || nbrs.length === 0) {
+                dangling += mass;
+                continue;
+            }
+            const share = ((1 - alpha) * mass) / nbrs.length;
+            for (const nb of nbrs)
+                next.set(nb, (next.get(nb) ?? 0) + share);
+        }
+        if (dangling > 0) {
+            const dm = (1 - alpha) * dangling;
+            for (const [sid, r] of restart)
+                next.set(sid, (next.get(sid) ?? 0) + dm * r);
+        }
+        rank = next;
+    }
+    let max = 0;
+    for (const v of rank.values())
+        if (v > max)
+            max = v;
+    if (max <= 0)
+        return new Map();
+    const out = new Map();
+    for (const [id, v] of rank)
+        out.set(id, v / max);
+    return out;
+}
+//# sourceMappingURL=graphrank.js.map

package/dist/ask/graphrank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphrank.js","sourceRoot":"","sources":["../../src/ask/graphrank.ts"],"names":[],"mappings":"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"}

package/dist/ask/index-file.d.ts

@@ -0,0 +1,44 @@
+import type { GraphV1 } from "../graph/types.js";
+/** Split prose + identifiers into lowercased subword tokens (camelCase, snake, kebab).
+ * The single source of truth for tokenization — shared by build-time indexing
+ * (this file) and query-time fallback (`ask.ts`) so the sidecar is a provably
+ * exact cache of the live path. */
+export declare function tokenize(text: string): string[];
+/** Term-frequency count map. */
+export declare function counts(tokens: string[]): Map<string, number>;
+/** One node's token bags, JSON-friendly (`Map` → sorted `[token, count][]`). */
+export interface AskIndexDoc {
+    id: string;
+    name: [string, number][];
+    path: [string, number][];
+    body: [string, number][];
+}
+/** The build-time sidecar. `df`/`docCount` cover symbol+file nodes only (no
+ * concepts — see module docstring); `avgBodyLen` is the BM25 corpus average. */
+export interface AskIndex {
+    version: 1;
+    avgBodyLen: number;
+    df: [string, number][];
+    docCount: number;
+    docs: AskIndexDoc[];
+}
+export declare const ASK_INDEX_FILE = "ask-index.json";
+/** Absolute path to the ask sidecar for a context dir: `<dir>/.cache/ask-index.json`.
+ * `.cache/` is the established uncommitted-cache location — this sidecar is a
+ * derived, regenerate-anytime cache, not checked-in graph data. */
+export declare function askIndexPath(outDir: string): string;
+/**
+ * Tokenize every node in `graph` (exactly as `ask.ts`'s lexical pass does) and
+ * write the resulting bags + document frequencies to
+ * `<outDir>/.cache/ask-index.json`. Returns the path written. Deterministic:
+ * nodes are indexed in id order, so an unchanged graph produces a
+ * byte-identical sidecar.
+ */
+export declare function writeAskIndex(outDir: string, graph: GraphV1): string;
+/** Read the ask sidecar. Returns null on a missing file, unparseable JSON, an
+ * unrecognized shape, an unknown `version`, or a `docCount` that doesn't match
+ * the number of docs actually stored (a corrupted/truncated sidecar would
+ * otherwise silently skew IDF) — any of which means the caller should fall
+ * back to live tokenization, never crash or trust bad data. */
+export declare function readAskIndex(outDir: string): AskIndex | null;
+//# sourceMappingURL=index-file.d.ts.map

package/dist/ask/index-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-file.d.ts","sourceRoot":"","sources":["../../src/ask/index-file.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAUjD;;;mCAGmC;AACnC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C;AAED,gCAAgC;AAChC,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAI5D;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC1B;AAED;gFACgF;AAChF,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,WAAW,EAAE,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C;;mEAEmE;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAaD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAiCpE;AAED;;;;+DAI+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqB5D"}

package/dist/ask/index-file.js

@@ -0,0 +1,128 @@
+/**
+ * Build-time sidecar for `graft ask` — `<outDir>/.cache/ask-index.json`.
+ *
+ * `ask`'s lexical pass tokenizes every symbol node's name/path/body on every
+ * query; at 32k nodes that re-tokenization is ~45% of query time (profiled).
+ * `graft build` writes this sidecar once, with the token→count bags per node
+ * plus the corpus-wide document frequencies, so a query just reads counts
+ * instead of re-splitting every node's text. It's a derived cache, not
+ * checked-in graph data, so it lives under the gitignored `.cache/` dir
+ * (see `CACHE_DIR` in `context/node-file.ts`) rather than `.graph/`.
+ *
+ * `tokenize`/`counts` live here (not duplicated in `ask.ts`) so build-time and
+ * query-time text-splitting are provably the same function — the sidecar can
+ * only be a correct cache of `ask.ts`'s own math if both sides call the same
+ * code. `ask.ts` imports both back from here.
+ *
+ * Concept (markdown) docs are NOT part of this sidecar — there are only dozens
+ * of them, they're still tokenized live at query time, and their doc-frequency
+ * contribution is folded into the stored `df` at query time (see `ask.ts`),
+ * which is why `df` here counts symbol/file nodes only.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CACHE_DIR } from "../context/node-file.js";
+/** Words too common/short to carry query intent — dropped before scoring. */
+const STOP = new Set([
+    "the", "a", "an", "of", "to", "in", "is", "are", "how", "does", "do", "what",
+    "where", "which", "that", "this", "it", "for", "on", "and", "or", "with",
+    "i", "we", "get", "set", "use", "used", "using", "when", "why", "can",
+]);
+/** Split prose + identifiers into lowercased subword tokens (camelCase, snake, kebab).
+ * The single source of truth for tokenization — shared by build-time indexing
+ * (this file) and query-time fallback (`ask.ts`) so the sidecar is a provably
+ * exact cache of the live path. */
+export function tokenize(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // camelCase → camel Case
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOP.has(t));
+}
+/** Term-frequency count map. */
+export function counts(tokens) {
+    const m = new Map();
+    for (const t of tokens)
+        m.set(t, (m.get(t) ?? 0) + 1);
+    return m;
+}
+export const ASK_INDEX_FILE = "ask-index.json";
+/** Absolute path to the ask sidecar for a context dir: `<dir>/.cache/ask-index.json`.
+ * `.cache/` is the established uncommitted-cache location — this sidecar is a
+ * derived, regenerate-anytime cache, not checked-in graph data. */
+export function askIndexPath(outDir) {
+    return join(outDir, CACHE_DIR, ASK_INDEX_FILE);
+}
+function pairs(m) {
+    return [...m.entries()];
+}
+/** Sum of a token→count bag's counts (a document's field length). */
+function bagLen(p) {
+    let s = 0;
+    for (const [, c] of p)
+        s += c;
+    return s;
+}
+/**
+ * Tokenize every node in `graph` (exactly as `ask.ts`'s lexical pass does) and
+ * write the resulting bags + document frequencies to
+ * `<outDir>/.cache/ask-index.json`. Returns the path written. Deterministic:
+ * nodes are indexed in id order, so an unchanged graph produces a
+ * byte-identical sidecar.
+ */
+export function writeAskIndex(outDir, graph) {
+    const nodes = [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id));
+    const docs = [];
+    const df = new Map();
+    for (const n of nodes) {
+        const name = counts(tokenize(n.name));
+        const path = counts(tokenize(n.path));
+        const body = counts(tokenize(`${n.signature ?? ""} ${n.summary ?? ""} ${n.body_text ?? ""}`));
+        docs.push({ id: n.id, name: pairs(name), path: pairs(path), body: pairs(body) });
+        const bag = new Set([...name.keys(), ...path.keys(), ...body.keys()]);
+        for (const t of bag)
+            df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    const avgBodyLen = docs.length
+        ? docs.reduce((a, d) => a + bagLen(d.body), 0) / docs.length
+        : 0;
+    const index = {
+        version: 1,
+        avgBodyLen,
+        df: pairs(df),
+        docCount: nodes.length,
+        docs,
+    };
+    const outPath = askIndexPath(outDir);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, JSON.stringify(index) + "\n");
+    return outPath;
+}
+/** Read the ask sidecar. Returns null on a missing file, unparseable JSON, an
+ * unrecognized shape, an unknown `version`, or a `docCount` that doesn't match
+ * the number of docs actually stored (a corrupted/truncated sidecar would
+ * otherwise silently skew IDF) — any of which means the caller should fall
+ * back to live tokenization, never crash or trust bad data. */
+export function readAskIndex(outDir) {
+    const path = askIndexPath(outDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!raw ||
+            typeof raw !== "object" ||
+            raw.version !== 1 ||
+            typeof raw.docCount !== "number" ||
+            typeof raw.avgBodyLen !== "number" ||
+            !Array.isArray(raw.df) ||
+            !Array.isArray(raw.docs) ||
+            raw.docCount !== raw.docs.length) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=index-file.js.map

package/dist/ask/index-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-file.js","sourceRoot":"","sources":["../../src/ask/index-file.ts"],"names":[],"mappings":"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"}

package/dist/ask/semantic.d.ts

@@ -0,0 +1,42 @@
+import type { NodeV1 } from '../graph/types.js';
+export interface SemanticHit {
+    node_id: string;
+    file_path: string;
+    symbol: string;
+    score: number;
+    snippet: string;
+}
+/** The embedding model used. Changing this invalidates all existing DBs (different dimensions). */
+export declare const EMBED_MODEL = "Xenova/all-mpnet-base-v2";
+/** Vector dimensions for the current model. MiniLM-L6=384, mpnet-base=768. */
+export declare const EMBED_DIM = 768;
+/**
+ * Inject a fake embedder for tests — bypasses the 87 MB model download.
+ * Call with `null` to restore the real pipeline.
+ */
+export declare function _setEmbedderForTest(fn: ((text: string) => Float32Array) | null): void;
+/**
+ * Embed all nodes in `nodes` and store them in the sqlite-vec database at
+ * `dbPath`. Idempotent: if the DB already contains rows, the function returns
+ * immediately without re-embedding.
+ *
+ * Called from the `graft_search_semantic` MCP tool handler (and optionally
+ * from the build pipeline) to pre-populate the vector store.
+ */
+/**
+ * Embed nodes and store them in the sqlite-vec database at `dbPath`.
+ *
+ * Incremental: compares each node's `body_hash` against what is already stored.
+ * Only new or changed nodes are re-embedded; deleted nodes are removed.
+ * Unchanged nodes are left untouched, making repeated calls cheap.
+ */
+export declare function embedNodes(nodes: NodeV1[], dbPath: string): Promise<void>;
+/**
+ * Embed `query`, find the top-`limit` nearest nodes in the vector store, and
+ * return them with cosine similarity scores.
+ *
+ * Throws if the DB does not exist or contains no embeddings (call `embedNodes`
+ * first, or use the MCP tool which calls it automatically).
+ */
+export declare function searchSemantic(query: string, dbPath: string, limit?: number): Promise<SemanticHit[]>;
+//# sourceMappingURL=semantic.d.ts.map

package/dist/ask/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/ask/semantic.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAShD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AA8BD,mGAAmG;AACnG,eAAO,MAAM,WAAW,6BAA6B,CAAC;AACtD,8EAA8E;AAC9E,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC,GAAG,IAAI,GAAG,IAAI,CAIrF;AA0FD;;;;;;;GAOG;AACH;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4H/E;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,SAAI,GACR,OAAO,CAAC,WAAW,EAAE,CAAC,CAqDxB"}

package/dist/ask/semantic.js

@@ -0,0 +1,293 @@
+/**
+ * Semantic search over the code graph using @huggingface/transformers embeddings
+ * and sqlite-vec for approximate nearest-neighbour retrieval.
+ *
+ * Spike 003 — Trail-Code fork integration.
+ * Validated building blocks: Spike 001 (embeddings) + Spike 002 (sqlite-vec).
+ */
+import { createRequire } from 'node:module';
+import { mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+// Use createRequire so CJS native modules load cleanly from this ESM file.
+const _require = createRequire(import.meta.url);
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+/** Normalise a Float32Array to unit length (required for cosine sim via L2). */
+function normalize(vec) {
+    let sum = 0;
+    for (const v of vec)
+        sum += v * v;
+    const norm = Math.sqrt(sum);
+    if (norm === 0)
+        return vec;
+    const out = new Float32Array(vec.length);
+    for (let i = 0; i < vec.length; i++)
+        out[i] = vec[i] / norm;
+    return out;
+}
+/** Convert Float32Array → Buffer so better-sqlite3 accepts it as a blob. */
+function vecToBuffer(arr) {
+    return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+// Module-level pipeline cache — one warm-up per process.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _extractor = null;
+// Test-only override: replaces the real pipeline with a fake embedder.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _testEmbedder = null;
+/** The embedding model used. Changing this invalidates all existing DBs (different dimensions). */
+export const EMBED_MODEL = 'Xenova/all-mpnet-base-v2';
+/** Vector dimensions for the current model. MiniLM-L6=384, mpnet-base=768. */
+export const EMBED_DIM = 768;
+/**
+ * Inject a fake embedder for tests — bypasses the 87 MB model download.
+ * Call with `null` to restore the real pipeline.
+ */
+export function _setEmbedderForTest(fn) {
+    _testEmbedder = fn;
+    // Also reset the cached extractor so it re-evaluates on the next call.
+    _extractor = null;
+}
+async function getExtractor() {
+    if (_testEmbedder)
+        return _testEmbedder;
+    if (_extractor)
+        return _extractor;
+    // Dynamic import keeps @huggingface/transformers tree-shakeable and avoids
+    // loading ONNX during non-semantic code paths.
+    const { pipeline, env } = await import('@huggingface/transformers');
+    // Point the model cache at a stable location outside node_modules so it
+    // survives npm ci / reinstalls (matches Spike 001 recommendation).
+    const home = process.env['USERPROFILE'] ?? process.env['HOME'] ?? '.';
+    env.cacheDir = `${home}/.cache/huggingface/transformers`;
+    _extractor = await pipeline('feature-extraction', EMBED_MODEL, { dtype: 'fp32' });
+    return _extractor;
+}
+/** Embed a batch of texts → unit-normalised float32 vectors (EMBED_DIM dimensions). */
+async function embedTexts(texts) {
+    const extractor = await getExtractor();
+    const results = [];
+    for (const text of texts) {
+        if (_testEmbedder) {
+            // Test path: call the fake embedder directly and normalize.
+            results.push(normalize((_testEmbedder)(text)));
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const output = await extractor(text, { pooling: 'mean', normalize: false });
+            results.push(normalize(output.data));
+        }
+    }
+    return results;
+}
+/** Open (or create) the SQLite db file and load the sqlite-vec extension. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function openDb(dbPath) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const Database = _require('better-sqlite3');
+    const sqliteVec = _require('sqlite-vec');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const db = new Database(dbPath);
+    sqliteVec.load(db);
+    return db;
+}
+/** Idempotent schema setup (IF NOT EXISTS on every statement). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embed_nodes (
+      rowid  INTEGER PRIMARY KEY,
+      node_id   TEXT NOT NULL,
+      file_path TEXT NOT NULL,
+      symbol    TEXT NOT NULL,
+      snippet   TEXT NOT NULL,
+      body_hash TEXT
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS vss_nodes
+    USING vec0(embedding float[${EMBED_DIM}]);
+    CREATE TABLE IF NOT EXISTS embed_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+    // Migrate older DBs that lack body_hash column (ALTER TABLE is safe if column exists).
+    try {
+        db.exec(`ALTER TABLE embed_nodes ADD COLUMN body_hash TEXT`);
+    }
+    catch { /* already exists */ }
+    // Detect model change: if stored model differs OR is absent with existing embeddings, wipe and rebuild.
+    const storedModel = db.prepare("SELECT value FROM embed_meta WHERE key = 'embed_model'").get()?.value;
+    const { c: existingCount } = db.prepare('SELECT COUNT(*) AS c FROM embed_nodes').get();
+    if (storedModel !== EMBED_MODEL && existingCount > 0) {
+        const reason = storedModel ? `${storedModel} → ${EMBED_MODEL}` : `migrating to ${EMBED_MODEL}`;
+        process.stderr.write(`[semantic] model changed (${reason}) — will rebuild\n`);
+        return true; // signal caller to delete and reopen
+    }
+    // Always store current model name.
+    db.prepare("INSERT INTO embed_meta (key, value) VALUES ('embed_model', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(EMBED_MODEL);
+    return false;
+}
+/** Compute a stable SHA-256 hash over all node IDs (sorted). */
+function graphHash(nodes) {
+    const sorted = nodes.map(n => n.id).sort().join(',');
+    return createHash('sha256').update(sorted).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Embed all nodes in `nodes` and store them in the sqlite-vec database at
+ * `dbPath`. Idempotent: if the DB already contains rows, the function returns
+ * immediately without re-embedding.
+ *
+ * Called from the `graft_search_semantic` MCP tool handler (and optionally
+ * from the build pipeline) to pre-populate the vector store.
+ */
+/**
+ * Embed nodes and store them in the sqlite-vec database at `dbPath`.
+ *
+ * Incremental: compares each node's `body_hash` against what is already stored.
+ * Only new or changed nodes are re-embedded; deleted nodes are removed.
+ * Unchanged nodes are left untouched, making repeated calls cheap.
+ */
+export async function embedNodes(nodes, dbPath) {
+    let db = openDb(dbPath);
+    const needsRebuild = initSchema(db);
+    if (needsRebuild) {
+        // Model changed — delete DB file and recreate fresh (safest way to change vss_nodes dimensions).
+        db.close();
+        const { unlinkSync } = await import('node:fs');
+        unlinkSync(dbPath);
+        db = openDb(dbPath);
+        initSchema(db);
+    }
+    // Guard: nothing to embed — skip silently (0 nodes is valid for .md-only repos
+    // that haven't enabled --include-md, or empty workspace children like openspec/).
+    if (nodes.length === 0) {
+        db.close();
+        return;
+    }
+    const currentHash = graphHash(nodes);
+    // Fast path: graph hash unchanged → index is fresh.
+    const stored = db.prepare("SELECT value FROM embed_meta WHERE key = 'graph_hash'").get();
+    if (stored?.value === currentHash) {
+        const { c } = db.prepare('SELECT COUNT(*) AS c FROM embed_nodes').get();
+        process.stderr.write(`[semantic] ${c} embeddings already in DB, fresh (hash match) — skipping re-embed\n`);
+        db.close();
+        return;
+    }
+    // Incremental path: compute per-node diff using body_hash.
+    const existingRows = db.prepare('SELECT node_id, body_hash FROM embed_nodes').all();
+    const existingMap = new Map(existingRows.map(r => [r.node_id, r.body_hash ?? '']));
+    const incomingSet = new Set(nodes.map(n => n.id));
+    // Nodes to remove: in DB but not in the new graph.
+    const toDelete = existingRows.filter(r => !incomingSet.has(r.node_id)).map(r => r.node_id);
+    // Nodes to add or update: new or body_hash changed.
+    const toEmbed = nodes.filter(n => {
+        const nodeHash = n.body_hash ?? n.id;
+        return existingMap.get(n.id) !== nodeHash;
+    });
+    const added = toEmbed.filter(n => !existingMap.has(n.id)).length;
+    const updated = toEmbed.length - added;
+    process.stderr.write(`[semantic] incremental update — +${added} new, ~${updated} changed, -${toDelete.length} removed` +
+        ` of ${nodes.length} total\n`);
+    // Delete removed nodes.
+    if (toDelete.length > 0) {
+        const delMeta = db.prepare('DELETE FROM embed_nodes WHERE node_id = ?');
+        const delVec = db.prepare('DELETE FROM vss_nodes WHERE rowid = (SELECT rowid FROM embed_nodes WHERE node_id = ?)');
+        const delBatch = db.transaction(() => {
+            for (const id of toDelete) {
+                delVec.run(id);
+                delMeta.run(id);
+            }
+        });
+        delBatch();
+    }
+    // Embed and insert/update changed nodes.
+    if (toEmbed.length > 0) {
+        const texts = toEmbed.map(n => [n.id, n.signature ?? '', n.body_text ?? ''].filter(Boolean).join(' '));
+        const vecs = await embedTexts(texts);
+        const { maxId } = db.prepare('SELECT COALESCE(MAX(rowid), 0) AS maxId FROM embed_nodes').get();
+        let nextRowid = maxId + 1;
+        // Regular table: UPSERT ok.
+        const upsertMeta = db.prepare(`
+      INSERT INTO embed_nodes (rowid, node_id, file_path, symbol, snippet, body_hash)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(rowid) DO UPDATE SET
+        node_id = excluded.node_id,
+        file_path = excluded.file_path,
+        symbol = excluded.symbol,
+        snippet = excluded.snippet,
+        body_hash = excluded.body_hash
+    `);
+        // Virtual table (sqlite-vec): no UPSERT support → DELETE then INSERT.
+        const deleteVec = db.prepare('DELETE FROM vss_nodes WHERE rowid = ?');
+        const insertVec = db.prepare('INSERT INTO vss_nodes (rowid, embedding) VALUES (?, ?)');
+        const getRowid = db.prepare('SELECT rowid FROM embed_nodes WHERE node_id = ?');
+        const upsertBatch = db.transaction(() => {
+            for (let i = 0; i < toEmbed.length; i++) {
+                const n = toEmbed[i];
+                const v = vecs[i];
+                const nodeHash = n.body_hash ?? n.id;
+                const snippet = n.summary ?? n.signature ?? n.id;
+                const existing = getRowid.get(n.id);
+                const rowid = existing ? BigInt(existing.rowid) : BigInt(nextRowid++);
+                // For updated nodes: remove old vector before inserting new one.
+                if (existing)
+                    deleteVec.run(rowid);
+                upsertMeta.run(Number(rowid), n.id, n.path, n.name, snippet ?? '', nodeHash);
+                insertVec.run(rowid, vecToBuffer(v));
+            }
+        });
+        upsertBatch();
+    }
+    // Update the graph hash.
+    db.prepare("INSERT INTO embed_meta (key, value) VALUES ('graph_hash', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(currentHash);
+    process.stderr.write(`[semantic] Done — ${nodes.length} nodes indexed at ${dbPath}\n`);
+    db.close();
+}
+/**
+ * Embed `query`, find the top-`limit` nearest nodes in the vector store, and
+ * return them with cosine similarity scores.
+ *
+ * Throws if the DB does not exist or contains no embeddings (call `embedNodes`
+ * first, or use the MCP tool which calls it automatically).
+ */
+export async function searchSemantic(query, dbPath, limit = 5) {
+    if (!existsSync(dbPath)) {
+        throw new Error(`Embeddings DB not found: ${dbPath} — run \`graft build\` or call the MCP tool once first`);
+    }
+    const db = openDb(dbPath);
+    initSchema(db);
+    const { c } = db.prepare('SELECT COUNT(*) AS c FROM embed_nodes').get();
+    if (c === 0) {
+        db.close();
+        throw new Error('[semantic] Vector index is empty — run `trail build` to populate it');
+    }
+    const [queryVec] = await embedTexts([query]);
+    const buf = vecToBuffer(queryVec);
+    const rows = db.prepare(`
+    SELECT
+      m.node_id,
+      m.file_path,
+      m.symbol,
+      m.snippet,
+      v.distance
+    FROM vss_nodes v
+    JOIN embed_nodes m ON m.rowid = v.rowid
+    WHERE v.embedding MATCH ?
+      AND k = ?
+    ORDER BY v.distance
+  `).all(buf, limit);
+    db.close();
+    return rows.map(r => ({
+        node_id: r.node_id,
+        file_path: r.file_path,
+        symbol: r.symbol,
+        score: +(1 - (r.distance * r.distance) / 2).toFixed(4),
+        snippet: r.snippet ?? '',
+    }));
+}
+//# sourceMappingURL=semantic.js.map