@davesheffer/hunch 0.1.0

package/dist/store/embedder.js

@@ -0,0 +1,133 @@
+/**
+ * Pluggable embedder for the semantic-search READ path (DESIGN.md §6 — the
+ * "add embeddings once keyword search proves insufficient" upgrade).
+ *
+ * Embeddings are LOCAL and FREE. Anthropic has no embeddings endpoint and the
+ * project is subscription-only (see synthesis/provider.ts), so we run a small
+ * sentence-transformer locally via transformers.js. That library is an OPTIONAL
+ * dependency, dynamically imported — if it isn't installed, `selectEmbedder()`
+ * returns null and the whole feature degrades to pure FTS (the lean-install
+ * default). This mirrors the synthesis provider: an interface so callers never
+ * know which implementation ran, plus a deterministic stub for tests.
+ *
+ * Vectors are L2-NORMALIZED, so cosine similarity == dot product downstream.
+ */
+import { createRequire } from "node:module";
+// The transformers.js package was renamed @xenova → @huggingface at v3. Probe both.
+const PACKAGES = ["@huggingface/transformers", "@xenova/transformers"];
+const HF_MODEL = "Xenova/all-MiniLM-L6-v2"; // 384-dim MiniLM; quantized ~23MB
+/** Is one of the transformers packages resolvable WITHOUT executing it? Cheap
+ *  availability probe (no onnxruntime init) so `selectEmbedder()` can return null
+ *  fast on the lean install. */
+function installedPackage() {
+    const req = createRequire(import.meta.url);
+    for (const p of PACKAGES) {
+        try {
+            req.resolve(p);
+            return p;
+        }
+        catch {
+            /* not installed — try next */
+        }
+    }
+    return null;
+}
+/** Run `fn` with stray stdout writes rerouted to stderr. transformers.js / its
+ *  backends may log during model load; on the MCP stdio channel a single stray
+ *  byte on stdout corrupts JSON-RPC. The guard is active only for the duration of
+ *  `fn` (model load), which is the only noisy phase. */
+async function withStdoutGuarded(fn) {
+    const orig = process.stdout.write.bind(process.stdout);
+    const toErr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = toErr;
+    try {
+        return await fn();
+    }
+    finally {
+        process.stdout.write = orig;
+    }
+}
+export class TransformersEmbedder {
+    dim = 384;
+    id = "all-MiniLM-L6-v2";
+    extractor = null;
+    load() {
+        if (!this.extractor) {
+            this.extractor = withStdoutGuarded(async () => {
+                const pkg = installedPackage();
+                if (!pkg)
+                    throw new Error("transformers.js not installed");
+                // String var (not a literal) so tsc doesn't require the optional dep to be
+                // present to typecheck/build, and the import resolves at runtime when it is.
+                const mod = (await import(pkg));
+                return (await mod.pipeline("feature-extraction", HF_MODEL));
+            });
+        }
+        return this.extractor;
+    }
+    async embed(texts) {
+        if (!texts.length)
+            return [];
+        const extractor = await this.load();
+        // pooling:mean + normalize:true → a [n, dim] tensor; .data is one flat
+        // Float32Array of length n*dim. Slice per row to a TIGHT copy (the tensor
+        // backing buffer is shared — a subarray view would alias it).
+        const res = await extractor(texts, { pooling: "mean", normalize: true });
+        const out = [];
+        for (let i = 0; i < texts.length; i++) {
+            out.push(res.data.slice(i * this.dim, (i + 1) * this.dim));
+        }
+        return out;
+    }
+}
+/** Deterministic, dependency-free embedder for tests (no model download).
+ *  Bag-of-token-hashes → L2-normalized vector: shared tokens ⇒ similar vectors,
+ *  enough to exercise hybrid ranking without semantics. Intentionally returns
+ *  SUBARRAY VIEWS into one backing buffer, so any caller that fails to copy
+ *  tightly before persisting will corrupt data — that keeps the BLOB round-trip
+ *  honest. */
+export class StubEmbedder {
+    dim;
+    id = "stub-v1";
+    constructor(dim = 32) {
+        this.dim = dim;
+    }
+    async embed(texts) {
+        const backing = new Float32Array(texts.length * this.dim);
+        const out = [];
+        texts.forEach((t, row) => {
+            const off = row * this.dim;
+            for (const tok of t.toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+                let h = 2166136261;
+                for (let i = 0; i < tok.length; i++) {
+                    h ^= tok.charCodeAt(i);
+                    h = Math.imul(h, 16777619);
+                }
+                const idx = off + ((h >>> 0) % this.dim);
+                backing[idx] = (backing[idx] ?? 0) + 1;
+            }
+            let norm = 0;
+            for (let i = 0; i < this.dim; i++)
+                norm += (backing[off + i] ?? 0) ** 2;
+            norm = Math.sqrt(norm) || 1;
+            for (let i = 0; i < this.dim; i++)
+                backing[off + i] = (backing[off + i] ?? 0) / norm;
+            out.push(backing.subarray(off, off + this.dim)); // view, not copy (on purpose)
+        });
+        return out;
+    }
+}
+/** Choose an embedder, or null to signal "no semantic search → use pure FTS".
+ *  Never throws. `HUNCH_EMBEDDER=stub` forces the test stub; `=none` forces the
+ *  null (FTS-only) path; otherwise use the local model iff its optional dep is
+ *  installed. */
+export async function selectEmbedder() {
+    switch (process.env.HUNCH_EMBEDDER) {
+        case "stub":
+            return new StubEmbedder();
+        case "none":
+            return null;
+    }
+    return installedPackage() ? new TransformersEmbedder() : null;
+}
+//# sourceMappingURL=embedder.js.map

package/dist/store/hunchStore.js

@@ -0,0 +1,469 @@
+import { ENTITY_KINDS } from "../core/types.js";
+import { openDb } from "./db.js";
+import { RESET_SQL, embedHash } from "./schema.js";
+import { selectEmbedder } from "./embedder.js";
+import { JsonStore } from "./jsonStore.js";
+import { pathMatchesGlob } from "../core/glob.js";
+export class HunchStore {
+    paths;
+    json;
+    _db = null;
+    constructor(paths) {
+        this.paths = paths;
+        this.json = new JsonStore(paths);
+    }
+    get db() {
+        if (!this._db)
+            this._db = openDb(this.paths.sqlite);
+        return this._db;
+    }
+    close() {
+        this._db?.close();
+        this._db = null;
+    }
+    // ---- write path ---------------------------------------------------------
+    /** Rebuild the entire SQLite index + FTS from the JSON source of truth. */
+    reindex() {
+        const db = this.db;
+        const counts = {};
+        const tx = db.transaction(() => {
+            db.exec(RESET_SQL);
+            const j = (s) => s; // readability marker for JSON-encoded columns
+            const comps = this.json.loadAll("components");
+            const insComp = db.prepare(`INSERT INTO components VALUES (@id,@kind,@name,@responsibility,@paths,@status,@owners,@fragility,@ps,@pc,@pe,@created_at,@updated_at)`);
+            for (const c of comps) {
+                insComp.run({
+                    id: c.id, kind: c.kind, name: c.name, responsibility: c.responsibility,
+                    paths: JSON.stringify(c.paths), status: c.status, owners: JSON.stringify(c.owners),
+                    fragility: c.fragility, ps: c.provenance.source, pc: c.provenance.confidence,
+                    pe: JSON.stringify(c.provenance.evidence), created_at: c.created_at, updated_at: c.updated_at,
+                });
+                this.fts(db, c.id, "components", c.name, `${c.responsibility} ${c.paths.join(" ")}`);
+            }
+            counts.components = comps.length;
+            const edges = this.json.loadAll("edges");
+            const insEdge = db.prepare(`INSERT INTO edges VALUES (@id,@from,@to,@type,@reason,@strength,@ps,@pc,@pe)`);
+            for (const e of edges) {
+                insEdge.run({ id: e.id, from: e.from, to: e.to, type: e.type, reason: e.reason, strength: e.strength,
+                    ps: e.provenance.source, pc: e.provenance.confidence, pe: JSON.stringify(e.provenance.evidence) });
+            }
+            counts.edges = edges.length;
+            const syms = this.json.loadAll("symbols");
+            const insSym = db.prepare(`INSERT INTO symbols VALUES (@id,@file,@name,@kind,@sh,@calls,@called_by,@loc,@churn,@bug,@fanin,@fanout,@last)`);
+            for (const s of syms) {
+                insSym.run({ id: s.id, file: s.file, name: s.name, kind: s.kind, sh: s.signature_hash,
+                    calls: JSON.stringify(s.calls), called_by: JSON.stringify(s.called_by),
+                    loc: s.metrics.loc, churn: s.metrics.churn_90d, bug: s.metrics.bug_count,
+                    fanin: s.metrics.fan_in, fanout: s.metrics.fan_out, last: s.last_changed });
+                this.fts(db, s.id, "symbols", `${s.name} (${s.kind})`, s.file);
+            }
+            counts.symbols = syms.length;
+            const decs = this.json.loadAll("decisions");
+            const insDec = db.prepare(`INSERT INTO decisions VALUES (@id,@title,@status,@context,@decision,@cons,@alts,@rc,@rf,@sup,@cbb,@commit,@ps,@pc,@pe,@date)`);
+            for (const d of decs) {
+                insDec.run({ id: d.id, title: d.title, status: d.status, context: d.context, decision: d.decision,
+                    cons: JSON.stringify(d.consequences), alts: JSON.stringify(d.alternatives_rejected),
+                    rc: JSON.stringify(d.related_components), rf: JSON.stringify(d.related_files),
+                    sup: d.supersedes, cbb: d.caused_by_bug, commit: d.commit,
+                    ps: d.provenance.source, pc: d.provenance.confidence, pe: JSON.stringify(d.provenance.evidence), date: d.date });
+                this.fts(db, d.id, "decisions", d.title, `${d.context} ${d.decision} ${d.consequences.join(" ")}`);
+            }
+            counts.decisions = decs.length;
+            const bugs = this.json.loadAll("bugs");
+            const insBug = db.prepare(`INSERT INTO bugs VALUES (@id,@title,@symptom,@rc,@sev,@status,@af,@as,@lin,@ps,@pc,@pe)`);
+            for (const b of bugs) {
+                insBug.run({ id: b.id, title: b.title, symptom: b.symptom, rc: b.root_cause, sev: b.severity, status: b.status,
+                    af: JSON.stringify(b.affected_files), as: JSON.stringify(b.affected_symbols), lin: JSON.stringify(b.lineage),
+                    ps: b.provenance.source, pc: b.provenance.confidence, pe: JSON.stringify(b.provenance.evidence) });
+                this.fts(db, b.id, "bugs", b.title, `${b.symptom} ${b.root_cause}`);
+            }
+            counts.bugs = bugs.length;
+            const cons = this.json.loadAll("constraints");
+            const insCon = db.prepare(`INSERT INTO constraints VALUES (@id,@type,@statement,@scope,@sev,@enf,@rat,@sd,@viol,@ps,@pc,@pe)`);
+            for (const c of cons) {
+                insCon.run({ id: c.id, type: c.type, statement: c.statement, scope: JSON.stringify(c.scope),
+                    sev: c.severity, enf: c.enforcement, rat: c.rationale, sd: c.source_decision, viol: JSON.stringify(c.violations),
+                    ps: c.provenance.source, pc: c.provenance.confidence, pe: JSON.stringify(c.provenance.evidence) });
+                this.fts(db, c.id, "constraints", c.statement, `${c.rationale} ${c.scope.join(" ")}`);
+            }
+            counts.constraints = cons.length;
+            void j;
+        });
+        tx();
+        // Reconcile embeddings AFTER the FTS rebuild (model-free): drop vectors whose
+        // source doc vanished or whose text changed. Embeddings are NOT in RESET_SQL,
+        // so this is what keeps them coherent across the many reindex() call sites.
+        this.pruneStaleEmbeddings();
+        return { counts };
+    }
+    fts(db, ref, kind, title, body) {
+        db.prepare(`INSERT INTO search (ref, kind, title, body) VALUES (?,?,?,?)`).run(ref, kind, title, body ?? "");
+    }
+    // ---- read path ----------------------------------------------------------
+    /** FTS5 ranked search (hunch_query). Falls back to LIKE if the query has no
+     *  FTS-tokenizable terms. */
+    search(query, limit = 12) {
+        const match = toFtsQuery(query);
+        // No FTS-tokenizable terms (e.g. a CJK-only query) — degrade to LIKE rather
+        // than silently returning nothing (the documented fallback).
+        if (!match)
+            return this.likeSearch(query, limit);
+        try {
+            const rows = this.db.prepare(`SELECT ref, kind, title, snippet(search, 3, '[', ']', '…', 12) AS snip, bm25(search) AS score
+         FROM search WHERE search MATCH ? ORDER BY score LIMIT ?`).all(match, limit);
+            return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score }));
+        }
+        catch {
+            // Malformed FTS expression — degrade to a LIKE scan over titles/bodies.
+            return this.likeSearch(query, limit);
+        }
+    }
+    /** Substring fallback over titles/bodies (handles non-ASCII / malformed FTS). */
+    likeSearch(query, limit) {
+        const like = `%${query.replace(/[%_]/g, "")}%`;
+        const rows = this.db.prepare(`SELECT ref, kind, title, substr(body,1,120) AS snip FROM search
+       WHERE title LIKE ? OR body LIKE ? LIMIT ?`).all(like, like, limit);
+        return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: 0 }));
+    }
+    // ---- semantic search (opt-in embeddings) --------------------------------
+    /** The exact (ref, kind, title, body) docs that feed FTS — and thus embeddings.
+     *  A single source so FTS, the doc_hash, and the stored vectors never disagree. */
+    searchDocs() {
+        return this.db.prepare(`SELECT ref, kind, title, body FROM search`).all();
+    }
+    /** Delete embedding rows whose source doc was removed or whose text changed
+     *  (doc_hash mismatch). Model-free and cheap; run at the end of every reindex()
+     *  so vectors track the JSON truth without ever being reset. Returns the count. */
+    pruneStaleEmbeddings() {
+        const live = new Map(); // ref -> current doc_hash
+        for (const d of this.searchDocs())
+            live.set(d.ref, embedHash(d.title, d.body));
+        const rows = this.db.prepare(`SELECT ref, doc_hash FROM embeddings`).all();
+        const del = this.db.prepare(`DELETE FROM embeddings WHERE ref = ?`);
+        let pruned = 0;
+        const tx = this.db.transaction(() => {
+            for (const r of rows)
+                if (live.get(r.ref) !== r.doc_hash) {
+                    del.run(r.ref);
+                    pruned++;
+                }
+        });
+        tx();
+        return pruned;
+    }
+    /** Embedding coverage for a model: up-to-date vectors vs total docs (doctor). */
+    embeddingStats(model) {
+        const total = this.db.prepare(`SELECT count(*) c FROM search`).get().c;
+        const embedded = this.db.prepare(`SELECT count(*) c FROM embeddings WHERE model = ?`).get(model).c;
+        return { embedded, total };
+    }
+    /** Generate/refresh embeddings for every doc missing an up-to-date vector for
+     *  this embedder's model. Batched + flushed per batch so a Ctrl-C leaves a
+     *  coherent partial index that a re-run resumes. Assumes reindex() ran first. */
+    async embedAll(embedder, opts = {}) {
+        const model = embedder.id;
+        const current = new Map(); // ref -> stored doc_hash for this model
+        for (const r of this.db.prepare(`SELECT ref, doc_hash FROM embeddings WHERE model = ?`).all(model)) {
+            current.set(r.ref, r.doc_hash);
+        }
+        const docs = this.searchDocs().map((d) => ({ ...d, hash: embedHash(d.title, d.body) }));
+        const todo = docs.filter((d) => current.get(d.ref) !== d.hash);
+        const ins = this.db.prepare(`INSERT OR REPLACE INTO embeddings (ref, kind, model, dim, doc_hash, vec) VALUES (?,?,?,?,?,?)`);
+        const batchSize = opts.batch ?? 32;
+        let done = 0;
+        for (let i = 0; i < todo.length; i += batchSize) {
+            const slice = todo.slice(i, i + batchSize);
+            const vecs = await embedder.embed(slice.map((d) => `${d.title}\n${d.body}`));
+            const tx = this.db.transaction(() => {
+                slice.forEach((d, j) => {
+                    const v = vecs[j];
+                    if (v)
+                        ins.run(d.ref, d.kind, model, embedder.dim, d.hash, vecToBlob(v));
+                });
+            });
+            tx();
+            done += slice.length;
+            opts.onProgress?.(done, todo.length);
+        }
+        return { embedded: todo.length, skipped: docs.length - todo.length, total: docs.length };
+    }
+    /** Hybrid search (hunch_query / `hunch query --semantic`): FTS bm25 fused with
+     *  cosine over stored embeddings via Reciprocal Rank Fusion. Degrades to pure
+     *  sync FTS (zero added latency) when there's no embedder or no vectors yet, so
+     *  the lean install and fallback regressions are unaffected. Pass
+     *  `embedder: null` to FORCE FTS-only without auto-selecting. */
+    async hybridSearch(query, limit = 12, opts = {}) {
+        const embedder = opts.embedder !== undefined ? opts.embedder : await selectEmbedder();
+        if (!embedder)
+            return this.search(query, limit);
+        const count = this.db.prepare(`SELECT count(*) c FROM embeddings WHERE model = ?`).get(embedder.id).c;
+        if (count === 0)
+            return this.search(query, limit);
+        const fts = this.search(query, Math.max(limit, 50));
+        let qvec;
+        try {
+            [qvec] = await embedder.embed([query]);
+        }
+        catch {
+            return fts.slice(0, limit); // embedding failed at query time → lexical only
+        }
+        if (!qvec)
+            return fts.slice(0, limit);
+        const sem = this.cosineRank(qvec, embedder.id, 50);
+        return this.rrfFuse(fts, sem, limit);
+    }
+    /** Brute-force exact cosine top-n over stored vectors for one model. Vectors are
+     *  pre-normalized, so cosine == dot product. */
+    cosineRank(qvec, model, n) {
+        const rows = this.db.prepare(`SELECT ref, kind, vec FROM embeddings WHERE model = ?`).all(model);
+        const dim = qvec.length;
+        const scored = rows.map((r) => {
+            const v = blobToVec(r.vec, dim);
+            let dot = 0;
+            for (let i = 0; i < dim; i++)
+                dot += qvec[i] * v[i];
+            return { ref: r.ref, kind: r.kind, score: dot };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, n).map((s) => {
+            const row = this.db.prepare(`SELECT title, body FROM search WHERE ref = ?`).get(s.ref);
+            return { ref: s.ref, kind: s.kind, title: row?.title ?? s.ref, snippet: (row?.body ?? "").slice(0, 120), score: s.score };
+        });
+    }
+    /** Rank-based Reciprocal Rank Fusion of the FTS and semantic lists. Ranks (not
+     *  raw scores) erase the bm25-vs-cosine scale mismatch; a small lexical weight
+     *  keeps exact symbol/path matches from being displaced by paraphrase hits. */
+    rrfFuse(fts, sem, limit) {
+        const acc = new Map();
+        const add = (list, weight) => list.forEach((hit, i) => {
+            const e = acc.get(hit.ref) ?? { hit, score: 0 };
+            e.score += weight / (RRF_K + i + 1);
+            acc.set(hit.ref, e);
+        });
+        add(fts, RRF_W_FTS);
+        add(sem, RRF_W_SEM);
+        return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
+    }
+    /** All decisions/bugs/constraints/symbols/components touching a file path or
+     *  symbol name (hunch_why). */
+    why(target) {
+        const decisions = this.json.loadAll("decisions");
+        const bugs = this.json.loadAll("bugs");
+        const constraints = this.json.loadAll("constraints");
+        const symbols = this.json.loadAll("symbols");
+        const components = this.json.loadAll("components");
+        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
+        const symIds = new Set(matchedSymbols.map((s) => s.id));
+        const fileSet = new Set(matchedSymbols.map((s) => s.file));
+        const isPath = target.includes("/") || target.includes(".");
+        const fileMatch = (files) => files.some((f) => f === target || (isPath && (f.endsWith(target) || target.endsWith(f))) || fileSet.has(f));
+        return {
+            target,
+            decisions: decisions.filter((d) => fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths)))),
+            bugs: bugs.filter((b) => fileMatch(b.affected_files) || b.affected_symbols.some((s) => symIds.has(s))),
+            constraints: constraints.filter((c) => c.scope.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+            symbols: matchedSymbols,
+            components: components.filter((c) => c.paths.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+        };
+    }
+    /** Transitive blast radius: every symbol/component that (in)directly depends on
+     *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
+     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
+    getDependents(id, maxDepth = 6) {
+        const rows = this.db.prepare(
+        /* sql */ `
+      WITH RECURSIVE up(node, depth) AS (
+        SELECT ?, 0
+        UNION
+        SELECT e."from", up.depth + 1
+        FROM edges e JOIN up ON e."to" = up.node
+        WHERE e.type IN ('calls','depends_on','imports','contains') AND up.depth < ?
+      )
+      SELECT DISTINCT up.node AS id, MIN(up.depth) AS depth FROM up
+      WHERE up.node <> ? GROUP BY up.node ORDER BY depth, id`).all(id, maxDepth, id);
+        return rows.map((r) => ({ id: r.id, depth: r.depth, via: this.labelFor(r.id) }));
+    }
+    /** Symbols/components this id depends ON (forward walk) — used for refactor blast radius. */
+    getDependencies(id, maxDepth = 6) {
+        const rows = this.db.prepare(
+        /* sql */ `
+      WITH RECURSIVE down(node, depth) AS (
+        SELECT ?, 0
+        UNION
+        SELECT e."to", down.depth + 1
+        FROM edges e JOIN down ON e."from" = down.node
+        WHERE e.type IN ('calls','depends_on','imports','contains') AND down.depth < ?
+      )
+      SELECT DISTINCT down.node AS id, MIN(down.depth) AS depth FROM down
+      WHERE down.node <> ? GROUP BY down.node ORDER BY depth, id`).all(id, maxDepth, id);
+        return rows.map((r) => ({ id: r.id, depth: r.depth, via: this.labelFor(r.id) }));
+    }
+    labelFor(id) {
+        if (id.startsWith("sym_")) {
+            const r = this.db.prepare(`SELECT name, file FROM symbols WHERE id=?`).get(id);
+            return r ? `${r.name} @ ${r.file}` : id;
+        }
+        if (id.startsWith("cmp_")) {
+            const r = this.db.prepare(`SELECT name FROM components WHERE id=?`).get(id);
+            return r ? r.name : id;
+        }
+        return id;
+    }
+    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints). */
+    checkConstraints(scope) {
+        const all = this.json.loadAll("constraints");
+        return all
+            .filter((c) => c.scope.some((g) => pathMatchesGlob(scope, g) || pathMatchesGlob(g, scope) || g === scope))
+            .sort((a, b) => sev(b.severity) - sev(a.severity));
+    }
+    /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
+    bugLineage(symptomOrSymbol) {
+        const bugs = this.json.loadAll("bugs");
+        const direct = bugs.filter((b) => b.affected_symbols.includes(symptomOrSymbol) || b.affected_files.includes(symptomOrSymbol));
+        if (direct.length)
+            return direct;
+        // fall back to fts over bug titles/symptoms
+        const hits = this.search(symptomOrSymbol).filter((h) => h.kind === "bugs").map((h) => h.ref);
+        const byHit = bugs.filter((b) => hits.includes(b.id));
+        if (byHit.length)
+            return byHit;
+        // last resort: naive substring over symptom/root_cause
+        const q = symptomOrSymbol.toLowerCase();
+        return bugs.filter((b) => `${b.title} ${b.symptom} ${b.root_cause}`.toLowerCase().includes(q));
+    }
+    /** Ranked fragility report (hunch fragile). fragility = weighted churn + bugs + fan-in. */
+    fragility(limit = 15) {
+        const syms = this.json.loadAll("symbols");
+        const bugs = this.json.loadAll("bugs");
+        // bug counts per symbol from actual bug records (authoritative over stale metric)
+        const bugBySym = new Map();
+        for (const b of bugs)
+            for (const s of b.affected_symbols)
+                bugBySym.set(s, (bugBySym.get(s) ?? 0) + 1);
+        const maxChurn = Math.max(1, ...syms.map((s) => s.metrics.churn_90d));
+        const maxFanIn = Math.max(1, ...syms.map((s) => s.metrics.fan_in));
+        const scored = syms.map((s) => {
+            const bugCount = Math.max(s.metrics.bug_count, bugBySym.get(s.id) ?? 0);
+            const churnN = s.metrics.churn_90d / maxChurn;
+            const fanInN = s.metrics.fan_in / maxFanIn;
+            // weighted: bugs dominate, then churn, then centrality
+            const score = 0.5 * Math.min(1, bugCount / 3) + 0.3 * churnN + 0.2 * fanInN;
+            const evidence = [];
+            if (bugCount)
+                evidence.push(`${bugCount} bug(s)`);
+            if (s.metrics.churn_90d)
+                evidence.push(`churn ${s.metrics.churn_90d}/90d`);
+            if (s.metrics.fan_in)
+                evidence.push(`fan-in ${s.metrics.fan_in}`);
+            return { id: s.id, file: s.file, name: s.name, score: round(score), churn_90d: s.metrics.churn_90d,
+                bug_count: bugCount, fan_in: s.metrics.fan_in, evidence };
+        });
+        return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /** Convenience: load a single entity from JSON by id (any kind). */
+    resolve(id) {
+        for (const kind of ENTITY_KINDS) {
+            const rec = this.json.get(kind, id);
+            if (rec)
+                return { kind, record: rec };
+        }
+        return undefined;
+    }
+    /** All edges (for graph export). */
+    allEdges() {
+        return this.json.loadAll("edges");
+    }
+    /** Drift detection (DESIGN §9 "staleness kills trust"): a decision/constraint
+     *  is STALE when a file in its scope changed AFTER it was last verified. The
+     *  caller supplies `lastChange(file) -> ISO date | ""` (git-backed). */
+    staleness(lastChange) {
+        const out = [];
+        const check = (kind, id, files, verified) => {
+            if (!verified)
+                return; // never verified → not flagged as drift (it's just new)
+            const vt = Date.parse(verified);
+            if (Number.isNaN(vt))
+                return;
+            let newest = "";
+            for (const f of files) {
+                const d = lastChange(f);
+                if (d && Date.parse(d) > vt && d > newest)
+                    newest = d;
+            }
+            if (newest)
+                out.push({ kind, id, last_verified: verified, changed_at: newest, files: files.slice(0, 8) });
+        };
+        for (const d of this.json.loadAll("decisions"))
+            check("decision", d.id, d.related_files, d.provenance.last_verified);
+        for (const c of this.json.loadAll("constraints"))
+            check("constraint", c.id, c.scope, c.provenance.last_verified);
+        return out.sort((a, b) => b.changed_at.localeCompare(a.changed_at));
+    }
+    /** The Context Assembler (DESIGN §2.1/§6): the MINIMAL relevant Hunch slice for
+     *  a task on `target`, ordered by what matters most — invariants first, then the
+     *  why, then blast radius and bug history — trimmed to a rough token budget. */
+    assembleContext(target, budget = 1500) {
+        const w = this.why(target);
+        const symIds = w.symbols.map((s) => s.id);
+        const blast = new Map();
+        for (const id of symIds) {
+            for (const d of this.getDependents(id)) {
+                const prev = blast.get(d.id);
+                if (!prev || d.depth < prev.depth)
+                    blast.set(d.id, d); // keep the MIN depth across start symbols
+            }
+        }
+        const bugs = w.bugs.length ? w.bugs : this.bugLineage(target);
+        const ctx = {
+            target,
+            constraints: w.constraints.sort((a, b) => sev(b.severity) - sev(a.severity)),
+            decisions: w.decisions.sort((a, b) => (b.provenance.confidence ?? 0) - (a.provenance.confidence ?? 0)),
+            bugs,
+            blast_radius: [...blast.values()].sort((a, b) => a.depth - b.depth).slice(0, 12),
+            components: w.components,
+            budget_tokens: budget,
+        };
+        return ctx;
+    }
+}
+function sev(s) {
+    return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+// --- semantic-search helpers ---------------------------------------------
+/** RRF tuning (env-overridable). Lexical weight ≥ semantic so exact matches win
+ *  ties while semantic adds paraphrase recall. */
+const RRF_K = numEnv("HUNCH_RRF_K", 60);
+const RRF_W_FTS = numEnv("HUNCH_RRF_W_FTS", 1);
+const RRF_W_SEM = numEnv("HUNCH_RRF_W_SEM", 0.7);
+function numEnv(name, dflt) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : dflt;
+}
+/** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
+ *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.
+ *  better-sqlite3 copies on bind, so the returned view never aliases the row. */
+function vecToBlob(v) {
+    return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+/** Decode a stored BLOB into an ALIGNED Float32Array — copy bytes into a fresh
+ *  ArrayBuffer rather than viewing the (possibly mis-aligned, pooled) Buffer,
+ *  which would throw RangeError on a non-4-multiple byteOffset. */
+function blobToVec(buf, dim) {
+    const ab = new ArrayBuffer(dim * 4);
+    new Uint8Array(ab).set(new Uint8Array(buf.buffer, buf.byteOffset, dim * 4));
+    return new Float32Array(ab);
+}
+/** Turn a free-text question into a tolerant FTS5 MATCH expression: split on
+ *  non-word chars, OR the terms with prefix matching. Returns null if empty. */
+function toFtsQuery(q) {
+    // Unicode word chars so accented/non-Latin terms still tokenize for FTS.
+    const terms = q.toLowerCase().match(/[\p{L}\p{N}_]+/gu);
+    if (!terms || terms.length === 0)
+        return null;
+    // quote each term and add prefix '*' for partial matches; OR them so recall is high
+    return terms.map((t) => `"${t}"*`).join(" OR ");
+}
+//# sourceMappingURL=hunchStore.js.map