@polycode-projects/seonix 0.2.1 → 0.4.0

package/src/codegraph.mjs

@@ -1,4 +1,5 @@
-import { lookupByProseTokens } from "./prose.mjs";
+import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
+import { cosine } from "./embed.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
 // deterministic indexer writes to <repo>/.seonix/graph.json (shape produced by
@@ -466,6 +467,67 @@ const PROSE_PROX_FRAC = 0.2;
 const PROSE_PROX_CAP_FRAC = 0.35;
 const PROSE_LOOKUP_LIMIT = 50; // bounds lookupByProseTokens' scan; the CAP_FRAC bounds the nudge regardless
 
+// Layered prose normalisation (opt-in via proseLayers, 2026-07-02): the prose index now carries
+// NORMALISED layers (spell-corrected / canonical-schema-term / stem / lemma) under
+// proseIndex["seonix:layers"] (built by the prose pre-pass; consumed read-only via prose.mjs's
+// proseLayerHits). Today the locate scorer matches query tokens against a module's path/symbol
+// text VERBATIM, so a task-text word that only reaches a module via its stem/lemma/canonical form
+// scores nothing. With the flag on, a query token that does NOT already match a module lexically,
+// but DOES resolve to one of that module's individuals through a normalised layer, contributes a
+// bounded, DISCOUNTED signal — weaker evidence than a verbatim match by construction (halved, then
+// the shared FRAC/CAP nudge), and, like every proximity family, it only re-ranks modules ALREADY
+// in `scored` — it never invents a zero-match candidate and never overrides an exact hit. NOT a
+// shipped default and NOT wired into any bench arm — an available lever pending its own gate
+// evidence, exactly like proseBoost/beamSearch before it.
+const PROSE_LAYER_FRAC = 0.2;      // bounded nudge — same shape/magnitude as the other proximity families …
+const PROSE_LAYER_CAP_FRAC = 0.35; //  … capped at this × the module's own base score (a nudge; hubs can't run away)
+const PROSE_LAYER_DISCOUNT = 0.5;  // a normalised-layer hit is WEAKER evidence than an exact/component token
+                                   // match — halved before the FRAC/CAP nudge, so a layer hit can never rival
+                                   // a verbatim lexical match (the "a miss beats a guess" discipline).
+
+// PLAN_SEON_TUNING.md §7.5 finding 1 / §7.6(5a) (opt-in via literalMention, 2026-07-02): the query
+// tokenizer split(/[^a-z0-9_]+/) DESTROYS a literal dotted module reference present verbatim in
+// task text — "django.utils.http" scatters into {django,utils,http}, tokens so common across
+// 2,931 modules that utils/http.py ranked 41 on B016's domain-filter — while every Module
+// individual carries an unread `dotted` attribute. The lever scans the RAW query (threaded through
+// as opts.rawQuery by searchModulesRanked) for whole, boundary-checked occurrences of each
+// module's `dotted` name and repo-relative path (label). Boundary rule: a match flanked by an
+// identifier/dotted/path continuation char ([a-z0-9_./]) does not count — which is also
+// longest-match-wins for free: a package __init__'s dotted prefix ("django.utils" inside
+// "django.utils.http") is followed by ".", so only the full module's own name fires (the two
+// __init__.py prefix artifacts the 2026-07-02 review flagged). Specificity floor: a candidate
+// with fewer than LIT_MIN_COMPONENTS dot/slash components never fires (a bare "utils" — or
+// "django.utils" — must not). A hit adds a bounded BASE-score component weighted like the
+// exact-symbol channel (LIT_W = EXACT_W per component IDF, top-LIT_COMP_CAP components like
+// SYM_MATCH_CAP), then capped at LIT_CAP_FRAC × the strongest base score — the FRAC/CAP shape of
+// the proximity families, anchored to the query's own best lexical evidence: a verbatim mention
+// can lift a module INTO the top ranks but can never become an unbounded override. Applied
+// BEFORE the proximity families so a mentioned module also donates adjacency like any other
+// strong match. Only modules that already matched lexically are eligible (a mentioned module
+// always is — its path components are query tokens by construction), preserving the levers'
+// shared no-new-candidates safety scope.
+const LIT_W = EXACT_W;         // per-component weight — a verbatim module mention is the strongest locate signal
+const LIT_MIN_COMPONENTS = 3;  // "django.utils.http" fires; "django.utils"/"utils" never do
+const LIT_COMP_CAP = 4;        // like SYM_MATCH_CAP: only the top-K highest-IDF components accrue
+const LIT_FRAC = 1.0;          // bonus = min(litWeight × this, maxBase × LIT_CAP_FRAC)
+const LIT_CAP_FRAC = 0.9;      //  … so a mention approaches — never dwarfs — the best lexical score
+
+// PLAN_SEON_TUNING.md §7.6(5b) (opt-in via embedRank + an injected embedder, 2026-07-02): static-
+// embedding re-rank — the deterministic "near-LLM" lever. The caller loads embed.mjs's
+// potion-base-8M table (loadEmbedder(); null when the one-time-fetch weights are absent) and
+// passes it as opts.embedder, keeping this module pure (no fs here; the flag no-ops with a
+// one-time stderr note when the embedder is missing, so CI never needs the 30 MB artifact).
+// Per-module text = path components + defined symbol names + doc first-lines — all read from the
+// graph, never from source — embedded lazily and cached per process (EMB_CACHE, WeakMap-keyed on
+// the graph). Cosine(query, module) becomes the same bounded FRAC/CAP nudge as the proximity
+// families: only re-ranks modules that ALREADY matched lexically, never introduces a candidate.
+const EMB_FRAC = 0.2;
+const EMB_CAP_FRAC = 0.35;
+const EMB_TEXT_SYMBOL_CAP = 64; // bound the per-module text: top defines …
+const EMB_TEXT_DOC_CAP = 12;    //  … and doc first-lines (a giant module can't grow an unbounded text)
+const EMB_CACHE = new WeakMap(); // graph -> { embedder, texts, vecs: Map<moduleId, Float32Array> }
+let embedWarned = false;
+
 // PLAN_SEON_TUNING.md §5.15 "discriminative multi-hop expansion" (opt-in via beamSearch):
 // generalizes the R1a/E1a/E1b family's single fixed-type, single-hop nudge into an adaptive,
 // multi-PLY expansion. Terminology follows Wikipedia's "Beam search" and Lowerre & Reddy, "The
@@ -501,6 +563,31 @@ const BEAM_OVERFLOW_CAP = 4;     // near-miss safety valve size
 const BEAM_PLIES = 2;            // hops of expansion
 const BEAM_EDGE_GROUPS = [["imports"], ["calls", "callsSymbol"], ["inherits"], ["cochange"]];
 
+/** embedRank: per-module embeddable text — path components + defined symbol names + doc
+ *  first-lines, ALL already in the graph (never re-reads source), bounded by the EMB_TEXT_*
+ *  caps. Built once per graph and cached alongside the vectors in EMB_CACHE. */
+function moduleEmbedTexts(graph) {
+  const texts = new Map(); // moduleId -> text
+  const defIdx = definesIndex(graph);
+  const docs = new Map();  // moduleId -> [doc first-lines]
+  for (const ind of graph.individuals) {
+    const doc = (ind.attributes || []).find((a) => a.key === "doc")?.value;
+    if (!doc) continue;
+    const modId = (ind.class || "") === "Module" ? ind.id : moduleIdOf(graph, ind);
+    if (!modId) continue;
+    let arr = docs.get(modId);
+    if (!arr) docs.set(modId, (arr = []));
+    if (arr.length < EMB_TEXT_DOC_CAP) arr.push(String(doc).split("\n")[0]);
+  }
+  for (const ind of graph.individuals) {
+    if ((ind.class || "") !== "Module") continue;
+    const parts = String(ind.label).split(/[^a-zA-Z0-9_]+/).filter(Boolean);
+    const syms = (defIdx.get(ind.id) || []).slice(0, EMB_TEXT_SYMBOL_CAP);
+    texts.set(ind.id, [...parts, ...syms, ...(docs.get(ind.id) || [])].join(" "));
+  }
+  return texts;
+}
+
 /** Split a lowercased path label into boundary components: django/utils/text.py →
  *  {django,utils,text,py}. Component equality (not substring) stops "text" matching "ci<text>". */
 function pathComponents(labelLc) {
@@ -604,7 +691,7 @@ function beamExpand(graph, scored, beamWidth) {
  *  + EXACT-symbol matches, re-ranks with a bounded import-proximity bonus, and breaks ties by
  *  matched-symbol DENSITY (a concrete signal — never ground truth). Pure; deterministic. */
 function scoreModules(graph, tokens, opts = {}) {
-  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, proseBoost = false } = opts;
+  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, proseBoost = false, proseLayers = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
   const beamWidth = Number.isFinite(opts.beamWidth) && opts.beamWidth > 0 ? opts.beamWidth : 8;
   const defIdx = definesIndex(graph);
   // Precompute each module's path components + defined-symbol exact/component sets, once.
@@ -617,7 +704,12 @@ function scoreModules(graph, tokens, opts = {}) {
     const symSet = new Set(defines.map((d) => d.toLowerCase())); // exact symbol names
     const symComps = new Set();
     for (const d of defines) for (const c of identComponents(d)) symComps.add(c);
-    modules.push({ ind, label, labelLc, defines, symSet, symComps });
+    // literalMention only: the Module's `dotted` attribute (mgx:dotted) — the verbatim form a
+    // task statement uses ("django.utils.http"); "" when absent. Gated so OFF does zero work.
+    const dotted = literalMention
+      ? String((ind.attributes || []).find((a) => a.key === "dotted")?.value || "").toLowerCase()
+      : "";
+    modules.push({ ind, label, labelLc, defines, symSet, symComps, dotted });
   }
   const N = modules.length || 1;
   // Inverse module-frequency: a token in many modules carries little locating signal; a rare one
@@ -654,6 +746,50 @@ function scoreModules(graph, tokens, opts = {}) {
     const density = m.defines.length ? matchCount / m.defines.length : 0;
     scored.push({ ind: m.ind, score, defineCount: m.defines.length, matching, density });
   }
+  // §7.5/§7.6(5a) literalMention (opt-in): verbatim dotted-name/path mentions in the RAW query —
+  // see the LIT_* constants' comment above for the full design. Runs before the proximity
+  // families so a mentioned module donates adjacency like any other strong match.
+  if (literalMention && rawQuery && scored.length) {
+    const rawLc = String(rawQuery).toLowerCase();
+    const continues = (ch) => ch != null && /[a-z0-9_./]/.test(ch);
+    // Whole, boundary-checked occurrence of `cand` in the raw query (see boundary rule above).
+    const mentioned = (cand) => {
+      for (let i = rawLc.indexOf(cand); i !== -1; i = rawLc.indexOf(cand, i + 1)) {
+        if (!continues(rawLc[i - 1]) && !continues(rawLc[i + cand.length])) return true;
+      }
+      return false;
+    };
+    // IDF for a candidate's components: normally already in the map (they are query tokens by
+    // construction when tokens came from this same raw query); computed-and-cached otherwise
+    // (a caller passing mismatched tokens/rawQuery must not crash or skew).
+    const idfOf = (t) => {
+      if (!idf.has(t)) {
+        let df = 0;
+        for (const m of modules) if (m.labelLc.includes(t) || m.symComps.has(t) || m.symSet.has(t)) df++;
+        idf.set(t, Math.log(1 + N / (1 + df)));
+      }
+      return idf.get(t);
+    };
+    const byModId = new Map(modules.map((m) => [m.ind.id, m]));
+    let maxBase = 0;
+    for (const s of scored) maxBase = Math.max(maxBase, s.score);
+    for (const s of scored) {
+      const m = byModId.get(s.ind.id);
+      if (!m) continue;
+      let litWeight = 0; // best single matched candidate (dotted vs path share components anyway)
+      for (const cand of new Set([m.dotted, m.labelLc])) {
+        if (!cand) continue;
+        if (cand.split(/[./]+/).filter(Boolean).length < LIT_MIN_COMPONENTS) continue; // specificity floor
+        if (!mentioned(cand)) continue;
+        // IDF-weight the candidate's tokens (same tokenizer as the query), highest first.
+        const weights = [...new Set(cand.split(/[^a-z0-9_]+/).filter(Boolean))].map(idfOf).sort((a, b) => b - a);
+        let w = 0;
+        for (let i = 0; i < Math.min(weights.length, LIT_COMP_CAP); i++) w += weights[i] * LIT_W;
+        litWeight = Math.max(litWeight, w);
+      }
+      if (litWeight) s.score += Math.min(litWeight * LIT_FRAC, maxBase * LIT_CAP_FRAC);
+    }
+  }
   // Import-graph proximity (rescaled): a matched module that imports / is imported by a
   // STRONGER-matching module gets a bonus proportional to that neighbour, so a genuine 2nd module
   // (truncatelines' text.py) rises with its sibling. Only re-ranks modules that ALREADY matched.
@@ -751,6 +887,73 @@ function scoreModules(graph, tokens, opts = {}) {
       }
     }
   }
+  // Layered prose normalisation (opt-in): a query token that did NOT match a module lexically but
+  // resolves to one of its individuals through a NORMALISED prose layer (stem/lemma/canonical/spell)
+  // adds a bounded, discounted signal — see the PROSE_LAYER_* comment above. One proseLayerHits call
+  // per DISTINCT query token, ids folded to their containing module via moduleIdOfId (same as the
+  // proseBoost/call-adjacency families). Only tokens NOT already matching a module lexically count
+  // for that module (a layer hit is purely ADDITIVE evidence for otherwise-missed words — never
+  // double-counting a token the base score already saw), weighted by the token's own IDF (so a
+  // ubiquitous word contributes almost nothing) and halved (PROSE_LAYER_DISCOUNT: weaker than a
+  // verbatim match), then the shared FRAC/CAP nudge. Only re-ranks modules already in `scored`.
+  if (proseLayers && scored.length && graph.proseIndex) {
+    const scoredById = new Map(scored.map((s) => [s.ind.id, s]));
+    const modById = new Map(modules.map((m) => [m.ind.id, m]));
+    const layerSignal = new Map(); // moduleId -> accumulated discounted, IDF-weighted layer signal
+    for (const t of new Set(tokens)) {
+      const w = idf.get(t) || 0;
+      if (!w) continue;
+      const { ids } = proseLayerHits(graph.proseIndex, t);
+      if (!ids.length) continue;
+      const hitMods = new Set();
+      for (const id of ids) {
+        const modId = moduleIdOfId(graph, id);
+        if (!modId || hitMods.has(modId)) continue;
+        hitMods.add(modId);
+        if (!scoredById.has(modId)) continue;              // never a new zero-match candidate
+        const m = modById.get(modId);
+        if (m && (m.symSet.has(t) || m.symComps.has(t) || m.labelLc.includes(t))) continue; // already matched lexically → not additive
+        layerSignal.set(modId, (layerSignal.get(modId) || 0) + w * PROSE_LAYER_DISCOUNT);
+      }
+    }
+    for (const s of scored) {
+      const signal = layerSignal.get(s.ind.id) || 0;
+      if (!signal) continue;
+      s.score += Math.min(signal * PROSE_LAYER_FRAC, s.score * PROSE_LAYER_CAP_FRAC);
+    }
+  }
+  // §7.6(5b) embedRank (opt-in): static-embedding cosine re-rank — see the EMB_* constants'
+  // comment above. The embedder is INJECTED (opts.embedder, from embed.mjs's loadEmbedder) so
+  // this module stays fs-free; absent embedder → no-op with a one-time stderr note, never a
+  // failure (the 30 MB weights are a local opt-in fetch, not a test/CI dependency).
+  if (embedRank) {
+    if (!opts.embedder) {
+      if (!embedWarned) {
+        embedWarned = true;
+        process.stderr.write("seonix: embedRank requested but no embedder available (weights not fetched? see `npm run refs:embeddings`) — flag is a no-op\n");
+      }
+    } else if (scored.length) {
+      const embedder = opts.embedder;
+      let cache = EMB_CACHE.get(graph);
+      if (!cache || cache.embedder !== embedder) {
+        cache = { embedder, texts: moduleEmbedTexts(graph), vecs: new Map() };
+        EMB_CACHE.set(graph, cache);
+      }
+      const qv = embedder.embed(rawQuery || tokens.join(" "));
+      let maxBase = 0;
+      for (const s of scored) maxBase = Math.max(maxBase, s.score);
+      for (const s of scored) {
+        let v = cache.vecs.get(s.ind.id);
+        if (!v) {
+          v = embedder.embed(cache.texts.get(s.ind.id) || String(s.ind.label));
+          cache.vecs.set(s.ind.id, v);
+        }
+        const sim = Math.max(0, cosine(qv, v)); // negative similarity never penalises
+        if (!sim) continue;
+        s.score += Math.min(sim * maxBase * EMB_FRAC, s.score * EMB_CAP_FRAC);
+      }
+    }
+  }
   // §5.15 beam search (opt-in): multi-ply generalization of the single-hop families above.
   if (beamSearch && scored.length > 1) beamExpand(graph, scored, beamWidth);
   // Tie-break: score → matched-symbol DENSITY (concrete, not ground truth) → fewer defines → shorter label.
@@ -766,9 +969,14 @@ function scoreModules(graph, tokens, opts = {}) {
  *  SELECTION that consumes this gap is OFF by default in run.mjs/selectModules — it over-injected
  *  on some tasks. The shipped default takes the top-2 instead. */
 export function searchModulesRanked(graph, query, opts = {}) {
-  const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+  const raw = String(query || "");
+  const tokens = raw.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   if (!tokens.length) return [];
-  return scoreModules(graph, tokens, opts).map((s) => ({ path: String(s.ind.label), score: s.score }));
+  // literalMention needs the query BEFORE tokenization (the tokenizer destroys the dotted refs
+  // it matches on) and embedRank embeds the raw phrasing; threaded only when a flag that
+  // consumes it is on, so the OFF path is provably unchanged.
+  const effOpts = (opts.literalMention || opts.embedRank) ? { ...opts, rawQuery: raw } : opts;
+  return scoreModules(graph, tokens, effOpts).map((s) => ({ path: String(s.ind.label), score: s.score }));
 }
 
 // B016 R1b, promoted to the shipped default (2026-07-02): positive in every measured cell across

package/src/cs_treesitter.mjs

@@ -32,6 +32,7 @@ const endLine = (n) => n.endPosition.row + 1;
 const fieldText = (n, f) => n.childForFieldName(f)?.text || "";
 
 const TYPE_DECLS = new Set(["class_declaration", "interface_declaration", "struct_declaration", "record_declaration", "enum_declaration"]);
+const SUBKIND = { interface_declaration: "interface", struct_declaration: "struct", record_declaration: "record", enum_declaration: "enum" };
 
 function collectCalls(node) {
   const out = new Set();
@@ -41,6 +42,12 @@ function collectCalls(node) {
     if (n.type === "invocation_expression") {
       const fn = n.childForFieldName("function");
       if (fn) out.add(fn.text.replace(/\s+/g, "").slice(0, 80));
+    } else if (n.type === "object_creation_expression") {
+      // `new X(...)` → bare "X" (generics/qualifiers stripped); implicit `new(...)`
+      // is a different node type and stays excluded (matches the Roslyn backend).
+      const t = n.childForFieldName("type");
+      const nm = t ? t.text.replace(/\s+/g, "").replace(/<.*$/s, "").split(".").pop() : "";
+      if (nm) out.add(nm.slice(0, 80));
     }
     for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
   }
@@ -58,6 +65,50 @@ function modifiersText(node) {
 }
 const visFrom = (mods) => mods.includes("private") ? "private" : mods.includes("protected") ? "protected" : "";
 
+/** Emit one type declaration (and, recursively, its nested types as Outer.Inner —
+ *  matching the Roslyn backend's qualified names). kind stays "class"; the flavour
+ *  (interface/struct/record/enum) lands in `subkind`. */
+function emitType(n, prefix, defines, exports) {
+  const simple = fieldText(n, "name");
+  if (!simple) return;
+  const cname = prefix ? `${prefix}.${simple}` : simple;
+  const mods = modifiersText(n);
+  const bases = [];
+  const baseList = n.childForFieldName("bases") || n.namedChildren.find((c) => c.type === "base_list");
+  if (baseList) for (let i = 0; i < baseList.namedChildCount; i++) bases.push(baseList.namedChild(i).text.slice(0, 80));
+  defines.push({ name: cname, kind: "class", lineno: line(n), end_lineno: endLine(n), bases, decorators: [],
+    ...(SUBKIND[n.type] ? { subkind: SUBKIND[n.type] } : {}),
+    ...(visFrom(mods) ? { visibility: visFrom(mods) } : {}) });
+  if (mods.includes("public")) exports.add(cname);
+  const body = n.childForFieldName("body");
+  if (!body) return;
+  for (let i = 0; i < body.namedChildCount; i++) {
+    const mem = body.namedChild(i);
+    if (TYPE_DECLS.has(mem.type)) {
+      emitType(mem, cname, defines, exports); // nested type → Outer.Inner
+    } else if (mem.type === "enum_member_declaration") {
+      const mn = fieldText(mem, "name") || mem.text;
+      if (mn) defines.push({ name: `${cname}.${mn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [], is_constant: true });
+    } else if (mem.type === "method_declaration" || mem.type === "constructor_declaration" || mem.type === "local_function_statement") {
+      const mn = fieldText(mem, "name") || cname;
+      const mmods = modifiersText(mem);
+      const params = (mem.childForFieldName("parameters")?.text || "").replace(/\s+/g, " ").replace(/^\(|\)$/g, "").slice(0, 160);
+      const returns = (mem.childForFieldName("returns") || mem.childForFieldName("type"))?.text?.slice(0, 80) || "";
+      defines.push({ name: `${cname}.${mn}`, kind: "method", lineno: line(mem), end_lineno: endLine(mem),
+        decorators: [], params, returns, calls: collectCalls(mem),
+        ...(mmods.includes("static") ? { is_static: true } : {}),
+        ...(visFrom(mmods) ? { visibility: visFrom(mmods) } : {}) });
+    } else if (mem.type === "property_declaration") {
+      const mn = fieldText(mem, "name");
+      if (mn) defines.push({ name: `${cname}.${mn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [] });
+    } else if (mem.type === "field_declaration") {
+      const v = mem.descendantsOfType?.("variable_declarator")?.[0];
+      const mn = v ? fieldText(v, "name") || v.text : "";
+      if (mn) defines.push({ name: `${cname}.${mn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [] });
+    }
+  }
+}
+
 export async function extractFile(absPath, root) {
   const text = await readFile(absPath, "utf8").catch(() => null);
   const path = relPath(root, absPath);
@@ -84,41 +135,9 @@ export async function extractFile(absPath, root) {
     } else if ((n.type === "namespace_declaration" || n.type === "file_scoped_namespace_declaration") && !primaryNs) {
       primaryNs = fieldText(n, "name");
     } else if (TYPE_DECLS.has(n.type)) {
-      const cname = fieldText(n, "name");
-      if (cname) {
-        const mods = modifiersText(n);
-        const bases = [];
-        const baseList = n.childForFieldName("bases") || n.namedChildren.find((c) => c.type === "base_list");
-        if (baseList) for (let i = 0; i < baseList.namedChildCount; i++) bases.push(baseList.namedChild(i).text.slice(0, 80));
-        defines.push({ name: cname, kind: "class", lineno: line(n), end_lineno: endLine(n), bases, decorators: [],
-          ...(visFrom(mods) ? { visibility: visFrom(mods) } : {}) });
-        if (mods.includes("public")) exports.add(cname);
-        const body = n.childForFieldName("body");
-        if (body) {
-          for (let i = 0; i < body.namedChildCount; i++) {
-            const mem = body.namedChild(i);
-            if (mem.type === "method_declaration" || mem.type === "constructor_declaration" || mem.type === "local_function_statement") {
-              const mn = fieldText(mem, "name") || cname;
-              const mmods = modifiersText(mem);
-              const params = (mem.childForFieldName("parameters")?.text || "").replace(/\s+/g, " ").replace(/^\(|\)$/g, "").slice(0, 160);
-              const returns = (mem.childForFieldName("returns") || mem.childForFieldName("type"))?.text?.slice(0, 80) || "";
-              defines.push({ name: `${cname}.${mn}`, kind: "method", lineno: line(mem), end_lineno: endLine(mem),
-                decorators: [], params, returns, calls: collectCalls(mem),
-                ...(mmods.includes("static") ? { is_static: true } : {}),
-                ...(visFrom(mmods) ? { visibility: visFrom(mmods) } : {}) });
-            } else if (mem.type === "property_declaration") {
-              const mn = fieldText(mem, "name");
-              if (mn) defines.push({ name: `${cname}.${mn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [] });
-            } else if (mem.type === "field_declaration") {
-              const v = mem.descendantsOfType?.("variable_declarator")?.[0];
-              const mn = v ? fieldText(v, "name") || v.text : "";
-              if (mn) defines.push({ name: `${cname}.${mn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [] });
-            }
-          }
-        }
-        // don't descend into the type body again for nested types beyond members
-      }
+      emitType(n, "", defines, exports);
     }
+    // descend, but not back into a type body (emitType recurses for nested types)
     if (!TYPE_DECLS.has(n.type)) for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
   }
 
@@ -137,4 +156,8 @@ export async function ingest(root, { ignore = null } = {}) {
   return { modules, failures, fileCount: files.length };
 }
 
+export function toolAvailable() {
+  try { loadTreeSitter(); return true; } catch { return false; }
+}
+
 export const meta = { id: "treesitter-cs", language: "c#", lib: "tree-sitter-c-sharp", exts: EXTS };

package/src/embed.mjs

@@ -0,0 +1,191 @@
+// embed.mjs — deterministic static-embedding lookup (model2vec potion-base-8M).
+// PLAN_SEON_TUNING.md §7.6(5b), 2026-07-02 library-leverage review.
+//
+// The honest "near-LLM" locate lever: a STATIC per-token embedding table (model2vec's
+// potion-base-8M, MIT — 29,528 WordPiece subwords × 256 fp32 dims, ~30 MB) read straight
+// from its safetensors export, mean-pooled and L2-normalised. No ONNX runtime, no model
+// calls, no network after the one-time fetch — pure table lookup + float arithmetic, so
+// the same text always embeds to the same vector ($0, deterministic, offline).
+//
+// Dependency choice (documented per the review): the safetensors format is an 8-byte LE
+// header length + JSON header + raw little-endian tensor bytes, and the tokenizer is a
+// plain Bert-style WordPiece (tokenizer.json: BertNormalizer lowercase + BertPreTokenizer
+// + greedy longest-match with "##" continuations) — both are small enough to hand-roll
+// with node built-ins, so neither the @yarflam/potion-base-8m fallback package nor an HF
+// tokenizer dependency is taken. Numerical intent follows model2vec's own encode (subword
+// ids WITHOUT the [CLS]/[SEP] template, mean pool, normalize per config.json) — exact
+// float parity with the Python lib is not claimed; determinism and rank usefulness are.
+//
+// The weights are NEVER committed and NEVER in the npm package: they live in the
+// gitignored vendor/ tree (fetched by scripts/fetch-embeddings.mjs, `npm run
+// refs:embeddings`, SHA-256-pinned like the repo's other binary artefacts). Everything
+// here degrades gracefully — loadEmbedder() returns null when the weights dir is absent,
+// and callers (codegraph.mjs's opt-in embedRank, scripts/rank-gate.mjs) no-op with a
+// clear note instead of failing, so CI/tests never require the 30 MB download.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MODEL_FILE = "model.safetensors";
+const TOKENIZER_FILE = "tokenizer.json";
+const CONFIG_FILE = "config.json";
+
+/** Default artifact dir: $SEONIX_EMBED_DIR, else <repo>/vendor/embeddings/potion-base-8M
+ *  (gitignored via vendor/ — the location scripts/fetch-embeddings.mjs writes). */
+export function defaultEmbeddingsDir() {
+  if (process.env.SEONIX_EMBED_DIR) return process.env.SEONIX_EMBED_DIR;
+  const here = dirname(fileURLToPath(import.meta.url)); // packages/seonix/src
+  return join(here, "..", "..", "..", "vendor", "embeddings", "potion-base-8M");
+}
+
+// ---- safetensors (hand-rolled: u64le header length + JSON header + raw tensors) -------
+
+/** Read the single 2-D F32 embedding tensor from a safetensors file →
+ *  { matrix: Float32Array (row-major), rows, dim }. model2vec exports exactly one
+ *  tensor named "embeddings"; any lone 2-D F32 tensor is accepted for test fixtures. */
+function readSafetensors(file) {
+  const buf = readFileSync(file);
+  const headerLen = Number(buf.readBigUInt64LE(0));
+  const header = JSON.parse(buf.subarray(8, 8 + headerLen).toString("utf8"));
+  const name = header.embeddings
+    ? "embeddings"
+    : Object.keys(header).find((k) => k !== "__metadata__" && header[k]?.shape?.length === 2);
+  const t = name && header[name];
+  if (!t) throw new Error(`no 2-D tensor in ${file}`);
+  if (t.dtype !== "F32") throw new Error(`unsupported dtype ${t.dtype} in ${file} (only F32)`);
+  const [rows, dim] = t.shape;
+  const [start, end] = t.data_offsets;
+  const bytes = buf.subarray(8 + headerLen + start, 8 + headerLen + end);
+  if (bytes.byteLength !== rows * dim * 4) throw new Error(`tensor size mismatch in ${file}`);
+  // Copy into a fresh ArrayBuffer: the slice's byteOffset inside the file buffer is not
+  // guaranteed 4-byte aligned, and Float32Array requires alignment.
+  const matrix = new Float32Array(rows * dim);
+  new Uint8Array(matrix.buffer).set(bytes);
+  return { matrix, rows, dim };
+}
+
+// ---- Bert-style WordPiece tokenizer (from tokenizer.json) -----------------------------
+
+const isPunct = (ch) => {
+  const c = ch.codePointAt(0);
+  // ASCII punctuation ranges (Bert treats these as standalone tokens) + general unicode P/S.
+  return (c >= 33 && c <= 47) || (c >= 58 && c <= 64) || (c >= 91 && c <= 96) || (c >= 123 && c <= 126) ||
+    /[\p{P}\p{S}]/u.test(ch);
+};
+const isCjk = (ch) => {
+  const c = ch.codePointAt(0);
+  return (c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) ||
+    (c >= 0xf900 && c <= 0xfaff) || (c >= 0x20000 && c <= 0x2ffff);
+};
+
+function makeTokenizer(spec) {
+  if (spec?.model?.type !== "WordPiece") {
+    throw new Error(`unsupported tokenizer model "${spec?.model?.type}" (only WordPiece)`);
+  }
+  const vocab = spec.model.vocab; // token -> id
+  const contPrefix = spec.model.continuing_subword_prefix ?? "##";
+  const maxChars = spec.model.max_input_chars_per_word ?? 100;
+  const unkId = vocab[spec.model.unk_token] ?? null;
+  const lowercase = spec.normalizer?.lowercase !== false;
+
+  // BertNormalizer: clean control chars, pad CJK, lowercase (+ strip accents when lowercasing).
+  const normalize = (text) => {
+    let s = String(text).replace(/[\u0000\ufffd]/g, "").replace(/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
+    s = [...s].map((ch) => (isCjk(ch) ? ` ${ch} ` : ch)).join("");
+    if (lowercase) s = s.toLowerCase().normalize("NFD").replace(/\p{Mn}/gu, "");
+    return s;
+  };
+  // BertPreTokenizer: split on whitespace; every punctuation char is its own word.
+  const preTokenize = (s) => {
+    const words = [];
+    for (const chunk of s.split(/\s+/)) {
+      if (!chunk) continue;
+      let cur = "";
+      for (const ch of chunk) {
+        if (isPunct(ch)) {
+          if (cur) { words.push(cur); cur = ""; }
+          words.push(ch);
+        } else cur += ch;
+      }
+      if (cur) words.push(cur);
+    }
+    return words;
+  };
+  // Greedy longest-match WordPiece per word; a word with no valid segmentation → [UNK].
+  const wordPiece = (word) => {
+    if (word.length > maxChars) return unkId == null ? [] : [unkId];
+    const ids = [];
+    let start = 0;
+    while (start < word.length) {
+      let end = word.length;
+      let id = null;
+      while (end > start) {
+        const piece = (start > 0 ? contPrefix : "") + word.slice(start, end);
+        if (vocab[piece] !== undefined) { id = vocab[piece]; break; }
+        end--;
+      }
+      if (id == null) return unkId == null ? [] : [unkId];
+      ids.push(id);
+      start = end;
+    }
+    return ids;
+  };
+  // No [CLS]/[SEP] template — model2vec pools content subwords only.
+  return (text) => preTokenize(normalize(text)).flatMap(wordPiece);
+}
+
+// ---- embedder ---------------------------------------------------------------------------
+
+const LOADED = new Map(); // dir -> embedder | null (per-process cache; weights load once)
+
+/** Load tokenizer + embedding matrix from `dir` (default: defaultEmbeddingsDir()).
+ *  Returns null — silently — when the artifacts are absent (the one-time
+ *  `npm run refs:embeddings` fetch has not run): callers no-op, never fail.
+ *  The returned embedder is { dim, dir, embed(text) → L2-normalised Float32Array }. */
+export function loadEmbedder({ dir = defaultEmbeddingsDir() } = {}) {
+  if (LOADED.has(dir)) return LOADED.get(dir);
+  const modelFile = join(dir, MODEL_FILE);
+  const tokFile = join(dir, TOKENIZER_FILE);
+  if (!existsSync(modelFile) || !existsSync(tokFile)) {
+    LOADED.set(dir, null);
+    return null;
+  }
+  const { matrix, rows, dim } = readSafetensors(modelFile);
+  const tokenize = makeTokenizer(JSON.parse(readFileSync(tokFile, "utf8")));
+  let cfg = {};
+  try { cfg = JSON.parse(readFileSync(join(dir, CONFIG_FILE), "utf8")); } catch { /* optional */ }
+  const doNormalize = cfg.normalize !== false;
+
+  const embed = (text) => {
+    const ids = tokenize(text);
+    const v = new Float32Array(dim);
+    if (!ids.length) return v; // zero vector: cosine 0 against everything
+    for (const id of ids) {
+      if (id < 0 || id >= rows) continue;
+      const off = id * dim;
+      for (let j = 0; j < dim; j++) v[j] += matrix[off + j];
+    }
+    for (let j = 0; j < dim; j++) v[j] /= ids.length; // mean pool
+    if (doNormalize) {
+      let norm = 0;
+      for (let j = 0; j < dim; j++) norm += v[j] * v[j];
+      norm = Math.sqrt(norm);
+      if (norm > 0) for (let j = 0; j < dim; j++) v[j] /= norm;
+    }
+    return v;
+  };
+  const embedder = { dim, dir, embed };
+  LOADED.set(dir, embedder);
+  return embedder;
+}
+
+/** Cosine similarity. Over L2-normalised vectors this is just the dot product, but the
+ *  full form is kept so unnormalised test fixtures behave. 0 when either vector is zero. */
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}