@davesheffer/hunch 0.21.0 → 0.22.0

package/dist/core/types.js

@@ -79,7 +79,7 @@ export const RetiredSignalSchema = z.object({
  *  existed in code, so its prose is turned into a testable set/regex. Carries its
  *  OWN provenance, separate from the decision's: an LLM may DRAFT a tripwire
  *  (advisory only); only a `human_confirmed` tripwire may BLOCK a commit — for every
- *  tier. One predictable rule (dec_a466655539). See docs/veto.md. */
+ *  tier. One predictable rule (dec_a466655539). */
 export const RejectedTripwireSchema = z.object({
     alternative: z.string().describe("the rejected approach's human text — printed verbatim in the receipt"),
     scope: z.array(z.string()).default([]).describe("glob(s) it applies to, e.g. vscode-extension/**"),

package/dist/mcp/server.js

@@ -288,9 +288,13 @@ export function buildServer(root) {
             else
                 store.json.put("decisions", rec);
             // Invalidate, don't delete: closing the superseded decision's valid-time window
-            // (+ a supersedes edge) preserves the why-it-changed trail. Supersede operates on
-            // the public store, so skip it for a private record (a v1 limitation, not a leak).
-            const superseded = decision.supersedes && !decision.private ? store.supersede(decision.supersedes, rec) : null;
+            // (+ a supersedes edge) preserves the why-it-changed trail. Route the close to the
+            // same store the new record landed in — a private decision supersedes within the
+            // private overlay; a public one in the committed store. A private write never
+            // mutates the public store.
+            const superseded = decision.supersedes
+                ? (decision.private ? store.supersedePrivate(decision.supersedes, rec) : store.supersede(decision.supersedes, rec))
+                : null;
             store.reindex();
             // Auto-flush the private repo when configured (hunch private --auto-commit), so a
             // record made via MCP between public commits is committed+pushed immediately.

package/dist/store/hunchStore.js

@@ -296,23 +296,32 @@ export class HunchStore {
      *  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 (!this.semanticReady(embedder))
+        // Explicit `embedder: null` forces pure FTS-only (no semantic, no graph) — the
+        // documented escape hatch and the lean-fallback regression guard.
+        if (opts.embedder === null)
             return this.search(query, limit);
+        const embedder = opts.embedder !== undefined ? opts.embedder : await selectEmbedder();
         const fts = this.search(query, Math.max(limit, 50));
-        try {
-            // The whole semantic leg (query embedding + decode + cosine + fuse) is guarded:
-            // any failure — model load, a corrupt/dim-mismatched vector — degrades to the
-            // lexical results rather than failing the query.
-            const [qvec] = await embedder.embed([query]);
-            if (!qvec)
-                return fts.slice(0, limit);
-            const sem = this.cosineRank(qvec, embedder.id, 50);
-            return this.rrfFuse(fts, sem, limit);
+        let sem = [];
+        if (embedder && this.semanticReady(embedder)) {
+            try {
+                // The semantic leg (query embedding + decode + cosine) is guarded: any failure —
+                // model load, a corrupt/dim-mismatched vector — degrades to lexical + graph.
+                const [qvec] = await embedder.embed([query]);
+                if (qvec)
+                    sem = this.cosineRank(qvec, embedder.id, 50);
+            }
+            catch {
+                sem = [];
+            }
         }
-        catch {
+        // The graph stream is model-free, so it contributes even on a lean (no-embeddings)
+        // install. With neither semantic nor graph signal, return pure FTS so the
+        // zero-fusion-overhead fast path is preserved.
+        const graph = this.graphExpand([...fts, ...sem], 50);
+        if (!sem.length && !graph.length)
             return fts.slice(0, limit);
-        }
+        return this.rrfFuse(fts, sem, graph, limit);
     }
     /** Brute-force exact cosine top-n over stored vectors for one model. Vectors are
      *  pre-normalized, so cosine == dot product. Scoped to `dim = qvec.length` so a
@@ -347,10 +356,12 @@ export class HunchStore {
             return { ref: s.ref, kind: s.kind, title: m?.title ?? s.ref, snippet: (m?.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) {
+    /** Rank-based Reciprocal Rank Fusion of the FTS, semantic, and graph lists. Ranks
+     *  (not raw scores) erase the bm25-vs-cosine-vs-graph scale mismatch; a small lexical
+     *  weight keeps exact symbol/path matches from being displaced by paraphrase or
+     *  neighbor hits. An empty list contributes nothing, so 2-stream behavior is exactly
+     *  preserved when graph (or sem) is absent. */
+    rrfFuse(fts, sem, graph, limit) {
         const acc = new Map();
         const add = (list, weight) => list.forEach((hit, i) => {
             const e = acc.get(hit.ref) ?? { hit, score: 0 };
@@ -359,8 +370,51 @@ export class HunchStore {
         });
         add(fts, RRF_W_FTS);
         add(sem, RRF_W_SEM);
+        add(graph, RRF_W_GRAPH);
         return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
     }
+    /** Graph retrieval stream (roadmap #1): 1-hop expansion over the dependency graph
+     *  from the lexical/semantic seed hits. For each seed SYMBOL, surface its direct
+     *  neighbors (callers/callees, importers/imported, container) — the cross-file
+     *  evidence a "why" question needs but that neither bm25 nor cosine reaches. Each
+     *  neighbor accrues GAMMA-decayed support per linking seed (one pulled in by several
+     *  top seeds ranks higher); seeds themselves are excluded, so this only ADDS context.
+     *  Deterministic, model-free (runs on a lean install too), one indexed query per seed. */
+    graphExpand(seeds, n) {
+        if (RRF_W_GRAPH <= 0)
+            return [];
+        const symSeeds = seeds.filter((h) => h.ref.startsWith("sym_"));
+        if (!symSeeds.length)
+            return [];
+        const seen = new Set(seeds.map((h) => h.ref)); // never re-surface a seed
+        const nbStmt = this.db.prepare(
+        /* sql */ `
+      SELECT e."to"   AS nb FROM edges e WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains')
+      UNION
+      SELECT e."from" AS nb FROM edges e WHERE e."to"   = ? AND e.type IN ('calls','depends_on','imports','contains')`);
+        const score = new Map();
+        symSeeds.forEach((h, i) => {
+            const contrib = GRAPH_GAMMA / (RRF_K + i + 1);
+            for (const r of nbStmt.all(h.ref, h.ref)) {
+                if (seen.has(r.nb))
+                    continue;
+                score.set(r.nb, (score.get(r.nb) ?? 0) + contrib);
+            }
+        });
+        if (!score.size)
+            return [];
+        const top = [...score.entries()].sort((a, b) => b[1] - a[1]).slice(0, n);
+        // Hydrate title/snippet from the FTS table in ONE query (mirrors cosineRank).
+        const placeholders = top.map(() => "?").join(",");
+        const meta = new Map();
+        for (const row of this.db.prepare(`SELECT ref, title, body FROM search WHERE ref IN (${placeholders})`).all(...top.map(([ref]) => ref))) {
+            meta.set(row.ref, { title: row.title, body: row.body });
+        }
+        return top.map(([ref, s]) => {
+            const m = meta.get(ref);
+            return { ref, kind: ref.startsWith("cmp_") ? "component" : "symbol", title: m?.title ?? ref, snippet: (m?.body ?? "").slice(0, 120), score: s };
+        });
+    }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
      *  return only decisions/constraints whose valid-time window contained that
@@ -615,7 +669,22 @@ export class HunchStore {
      *  and write a `supersedes` edge. Returns the updated old decision, or null if it
      *  doesn't exist. All writes are atomic via json.put (con_902759b3dc). */
     supersede(oldId, by) {
-        const old = this.json.get("decisions", oldId);
+        return this.supersedeIn(this.json, oldId, by);
+    }
+    /** Private-overlay counterpart of `supersede`: close + link the old decision inside
+     *  the HUNCH_PRIVATE_DIR store, so a PRIVATE decision can supersede another private
+     *  one (the MCP record path is private→private). A private write never mutates the
+     *  committed public store. Returns null if no private store is configured or the old
+     *  record isn't in it. */
+    supersedePrivate(oldId, by) {
+        if (!this.privateJson)
+            return null;
+        this.privateJson.ensureDirs();
+        return this.supersedeIn(this.privateJson, oldId, by);
+    }
+    /** Shared body for supersede / supersedePrivate against a specific store. */
+    supersedeIn(json, oldId, by) {
+        const old = json.get("decisions", oldId);
         if (!old || old.id === by.id)
             return null;
         const closed = {
@@ -624,7 +693,7 @@ export class HunchStore {
             superseded_by: by.id,
             valid_to: old.valid_to ?? by.valid_from ?? null,
         };
-        this.json.put("decisions", closed);
+        json.put("decisions", closed);
         const edge = {
             id: edgeId(by.id, oldId, "supersedes"),
             from: by.id,
@@ -634,7 +703,7 @@ export class HunchStore {
             strength: 1,
             provenance: { source: "derived", confidence: 1, evidence: [by.id, oldId] },
         };
-        this.json.put("edges", edge);
+        json.put("edges", edge);
         return closed;
     }
     /** Regression Guard: detect a change RE-INTRODUCING something an in-force
@@ -690,7 +759,7 @@ export class HunchStore {
      *  never did. Precision-first ladder (dep > symbol > pattern); the semantic tier is
      *  advisory and lives elsewhere. A hit `blocks` only when isVetoBlocker passes (a
      *  human-confirmed tripwire on an in-force, non-stale decision — dec_a466655539).
-     *  Read-only; shared by buildCheckReport. See docs/veto.md. */
+     *  Read-only; shared by buildCheckReport. */
     vetoHits(an, files, staleDecisions = new Set()) {
         const addedDeps = new Set(an.addedDeps);
         const out = [];
@@ -956,11 +1025,17 @@ 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. */
+/** RRF tuning (env-overridable). Lexical weight ≥ semantic ≥ graph: exact matches
+ *  win ties, semantic adds paraphrase recall, and the graph stream adds the
+ *  dependency-neighbor evidence a "why" question needs across files. The graph
+ *  weight is conservative + measurement-gated (set HUNCH_RRF_W_GRAPH=0 to disable);
+ *  GAMMA only decays a neighbor's cross-seed support, so its absolute value is
+ *  normalized away by the rank-based fusion. */
 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);
+const RRF_W_GRAPH = numEnv("HUNCH_RRF_W_GRAPH", 0.5);
+const GRAPH_GAMMA = numEnv("HUNCH_GRAPH_GAMMA", 0.25);
 function numEnv(name, dflt) {
     const v = Number(process.env[name]);
     return Number.isFinite(v) && v > 0 ? v : dflt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",