@polycode-projects/seonix 0.2.1 → 0.3.0

package/src/browser.mjs

@@ -305,8 +305,10 @@ export function buildTemporalGraph(raw, orderShas, { scope = "product", parentsB
  *  the page's whole view state already round-trips through the URL (P1) — a plain
  *  reload on HEAD change is enough to pick up a re-index without losing the cursor,
  *  selection, or query. */
-export function buildBrowserData(tg, { repoUrl = "", repoRef = "main", siteNav = false, live = false, gitHead = "" } = {}) {
-  return { ...tg, repoUrl: String(repoUrl).replace(/\/+$/, ""), repoRef, siteNav: !!siteNav, live: !!live, gitHead };
+export function buildBrowserData(tg, { repoUrl = "", repoRef = "main", siteNav = false, live = false, gitHead = "", nav = null } = {}) {
+  // `nav` ({name: href}) rebuilds the page's #sitenav; `siteNav` is the legacy
+  // flag — stale deployed data keeps its absolute links.
+  return { ...tg, repoUrl: String(repoUrl).replace(/\/+$/, ""), repoRef, siteNav: !!siteNav, ...(nav ? { nav } : {}), live: !!live, gitHead };
 }
 
 /** The tested temporal core, ready to inline into the page (exports stripped). */
@@ -430,7 +432,8 @@ function init(tg){
   for(const n of tg.nodes)S.byId.set(n.id,n);
   document.title='seon chronograph — '+(tg.meta&&tg.meta.scope||'');
   $('scopelabel').textContent=(tg.meta&&tg.meta.scope?'· '+tg.meta.scope:'')+' · '+tg.commits.length+' commits · '+tg.nodes.length+' nodes'+(tg.live?' · live':'');
-  if(tg.siteNav)$('sitenav').hidden=false;
+  if(tg.nav){$('sitenav').innerHTML=Object.entries(tg.nav).map(([k,h])=>'<a href="'+esc(h)+'">'+esc(k)+'</a>').join('');$('sitenav').hidden=false;}
+  else if(tg.siteNav)$('sitenav').hidden=false;
   // ---- URL state in (query-as-URL: the whole view is the link) ----
   const st=decodeViewState(location.search);
   if(st.q){S.q=st.q;$('q').value=st.q;S.qSet=matchQuery(tg,st.q);}
@@ -477,9 +480,12 @@ function syncUrl(){
   const full=(keep?'data='+encodeURIComponent(keep)+(qs?'&':''):'')+qs;
   history.replaceState(null,'',full?('?'+full):location.pathname);
 }
+// Legend chips per type GROUP — Function/Method share one chip (legend-only
+// merge; node fills stay distinct), counts summed across the group.
+const GROUPS=[['Module'],['Class'],['Function','Method'],['Attribute'],['GlobalVariable'],['Commit']];
 function buildChips(){
-  $('legend').innerHTML=TYPES.map(t=>'<label class="lg" title="show/hide '+t+' nodes"><input type="checkbox" class="typechk" data-cls="'+t+'"'+(S.enabled.has(t)?' checked':'')+'><i style="background:'+COLORS[t]+'"></i>'+t+'<span class="cnt" data-cnt="'+t+'"></span></label>').join(' ');
-  document.querySelectorAll('.typechk').forEach(c=>c.addEventListener('change',()=>{c.checked?S.enabled.add(c.dataset.cls):S.enabled.delete(c.dataset.cls);render();}));
+  $('legend').innerHTML=GROUPS.map(g=>'<label class="lg" title="show/hide '+g.join('/')+' nodes"><input type="checkbox" class="typechk" data-cls="'+g.join(',')+'"'+(g.every(t=>S.enabled.has(t))?' checked':'')+'>'+g.map(t=>'<i style="background:'+COLORS[t]+'"></i>').join('')+g.join('/')+'<span class="cnt" data-cnt="'+g.join(',')+'"></span></label>').join(' ');
+  document.querySelectorAll('.typechk').forEach(c=>c.addEventListener('change',()=>{c.dataset.cls.split(',').forEach(t=>c.checked?S.enabled.add(t):S.enabled.delete(t));render();}));
 }
 function buildCy(tg){
   const els=[];
@@ -562,7 +568,7 @@ function render(){
   const vis={},tot={};
   S.tg.nodes.forEach(n=>{tot[n.type]=(tot[n.type]||0)+1;});
   cy.nodes().forEach(cn=>{if(cn.style('display')==='element'){const t=cn.data('type');vis[t]=(vis[t]||0)+1;}});
-  document.querySelectorAll('.cnt').forEach(sp=>{const k=sp.dataset.cnt;sp.textContent=(vis[k]||0)+'/'+(tot[k]||0);});
+  document.querySelectorAll('.cnt').forEach(sp=>{const ks=sp.dataset.cnt.split(',');sp.textContent=ks.reduce((a,k)=>a+(vis[k]||0),0)+'/'+ks.reduce((a,k)=>a+(tot[k]||0),0);});
   // narration: single cursor = the commit's story; two cursors = the range's story
   $('narr').textContent=cmp?narrateRange(S.tg,lo,hi):narrateCommit(S.tg,idx);
   $('qnote').style.display=(S.qSet&&S.qSet.size===0)?'block':'none';

package/src/chat.mjs

@@ -0,0 +1,188 @@
+// chat.mjs — `seonix chat`: an interactive prompt over the mechanical seonix_ask
+// engine (PLAN_MECHANICAL_CHAT.md). Every non-`/exit` line is a query dispatched
+// through dispatchTool("seonix_ask", …) — the EXACT path bin/cli.mjs's `cli
+// <toolName>` fallback already exposes — so chat is the same engine as
+// `seonix cli seonix_ask '{"query":"…"}'` with a readline shell around it, zero
+// new coupling to ask.mjs internals.
+//
+// Sessions are logged to <repo>/SESSION_LOG_DIR/session-<uuidv7>.log, appended
+// and flushed per turn so a killed session keeps everything up to its last turn.
+// Alongside it, a STRUCTURED sidecar (.seonix/sessions/session-<uuidv7>.jsonl,
+// sessions.mjs) records each turn's resolved/answered entity ids, and the session
+// is upserted into graph.json per turn as a first-class `Session` individual with
+// mgx:asksAbout edges — chat sessions are temporal graph data, like commits.
+//
+// Future work (deliberately NOT wired for v1): the ask engine's structured
+// envelope carries selected-node context hooks (the viewer's contextId); chat is
+// single-shot stateless queries only — no cross-turn state, no context id.
+
+import { join } from "node:path";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { randomBytes } from "node:crypto";
+import { dispatchTool } from "./server.mjs";
+import { loadConfig, DEFAULT_GRAPH_REL } from "./config.mjs";
+import { parseEntities } from "./codegraph.mjs";
+import { SESSIONS_DIR_REL, appendSessionToGraph } from "./sessions.mjs";
+import * as defaultSource from "./source.mjs";
+
+/** Where session logs live, relative to the target repo. `.seonix/` is the repo's
+ *  one artifact directory (gitignored, machine-local) — flip this single constant
+ *  if the operator prefers a different location. */
+export const SESSION_LOG_DIR = ".seonix";
+
+export const PROMPT = "seon> ";
+
+/** dispatchTool("seonix_ask", …) returns the prose answer plus a delimited
+ *  machine-readable envelope (server.mjs §6.2); the TUI shows the prose only. */
+const ASK_ENVELOPE_DELIM = "\n\n---seonix_ask---\n";
+
+/** UUID v7 (RFC 9562): 48-bit big-endian unix-ms timestamp, then version/variant
+ *  bits over crypto-random tail — time-sortable, unlike crypto.randomUUID()'s v4. */
+export function uuidv7(now = Date.now()) {
+  const b = randomBytes(16);
+  b.writeUIntBE(now, 0, 6); // 48-bit unix-ms timestamp, big-endian
+  b[6] = (b[6] & 0x0f) | 0x70; // version 7
+  b[8] = (b[8] & 0x3f) | 0x80; // variant 10xx
+  const h = b.toString("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+/** Mirror bin/cli.mjs's configFor: an explicit repo pins the artifact path; no
+ *  repo falls back to the cwd/env-derived default. */
+function configFor(repoPath) {
+  return repoPath ? { graphFile: join(repoPath, DEFAULT_GRAPH_REL) } : loadConfig();
+}
+
+/**
+ * One chat turn: query → { answer, logLines, record }. Pure of any TTY/stream
+ * concerns so tests exercise it directly. A grammar miss is a normal answer (the
+ * engine's own hint text); a thrown ToolError becomes the answer too — a turn
+ * never crashes the session.
+ *
+ * `record` is the structured sidecar entry (sessions.mjs): `answeredIds` are the
+ * entity ids the answer cited, straight from the engine's machine envelope;
+ * `resolvedIds` is the engine's own resolveObject hit for the parsed object term
+ * (public ask.mjs surface, lazily imported and failure-tolerated so concurrent
+ * evolution of the engine can never crash a turn — worst case the sidecar records
+ * fewer ids, never wrong ones).
+ */
+export async function runTurn(query, { config, source = defaultSource, graph = null } = {}) {
+  let answer;
+  let envelope = null;
+  try {
+    const text = await dispatchTool("seonix_ask", { query }, { config, source });
+    const [content, envJson] = text.split(ASK_ENVELOPE_DELIM);
+    answer = content;
+    if (envJson) { try { envelope = JSON.parse(envJson); } catch { envelope = null; } }
+  } catch (e) {
+    answer = String(e?.message || e);
+  }
+  // A grammar miss has parsed:null → stays []. An empty-RESULT query (object resolved,
+  // no edges) still records the resolved subject — that IS the asksAbout signal.
+  let resolvedIds = [];
+  if (graph && envelope?.parsed?.object) {
+    try {
+      const { resolveObject } = await import("./ask.mjs");
+      const r = resolveObject(graph, envelope.parsed.object);
+      if (r?.match?.id && !r.ambiguous) resolvedIds = [r.match.id];
+    } catch { /* tolerated — see docblock */ }
+  }
+  const answeredIds = (envelope?.matches || []).map((m) => m?.id).filter(Boolean);
+  const ts = new Date().toISOString();
+  const record = { type: "turn", ts, query, resolvedIds, answeredIds, miss: envelope ? !!envelope.miss : true };
+  const logLines = [ts, `> ${query}`, answer, ""];
+  return { answer, logLines, record };
+}
+
+/**
+ * The interactive shell. Streams are injectable so tests run scripted sessions
+ * without a TTY. Throws the source layer's own ToolError (pointing at
+ * `seonix cli index_repository`) when the repo has no graph artifact.
+ * Returns { logFile, sidecarFile, turns } once the session ends.
+ */
+export async function runChat({
+  repoPath,
+  input = process.stdin,
+  output = process.stdout,
+  source = defaultSource,
+  env = process.env,
+} = {}) {
+  const repo = repoPath || process.cwd();
+  const config = configFor(repoPath);
+
+  // Load the graph once up front — the banner needs the module count, and a
+  // missing/empty artifact should fail HERE with the server's own helpful error,
+  // not on the first question.
+  const graph = parseEntities(await source.fetchEntities(config));
+  const moduleCount = graph.individuals.filter((i) => (i.class || "") === "Module").length;
+  const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+
+  const sessionId = uuidv7();
+  const logDir = join(repo, SESSION_LOG_DIR);
+  const sessionsDir = join(repo, SESSIONS_DIR_REL);
+  await mkdir(logDir, { recursive: true });
+  await mkdir(sessionsDir, { recursive: true });
+  const logFile = join(logDir, `session-${sessionId}.log`);
+  const sidecarFile = join(sessionsDir, `session-${sessionId}.jsonl`);
+  const stream = createWriteStream(logFile, { flags: "a" });
+  const sidecar = createWriteStream(sidecarFile, { flags: "a" });
+  // Awaited writes: each chunk is handed to the OS before the loop continues, so a
+  // killed session keeps everything up to the last completed turn — in both files.
+  const flush = (s, text) =>
+    new Promise((resolve, reject) => s.write(text, (e) => (e ? reject(e) : resolve())));
+  const writeLog = (text) => flush(stream, text);
+  const writeSidecar = (obj) => flush(sidecar, JSON.stringify(obj) + "\n");
+
+  const startIso = new Date().toISOString();
+  await writeLog(`# seonix chat ${version} — session started ${startIso} — repo ${repo}\n\n`);
+  await writeSidecar({ type: "session", id: sessionId, started: startIso, repo, seonixVersion: version });
+
+  // Read-time graph upsert (sessions.mjs): after every turn, the session becomes /
+  // stays a first-class Session individual in graph.json (crash-safe: turn n is in
+  // the graph before turn n+1 runs). Best-effort by design — a re-index or vanished
+  // artifact mid-session must degrade the recording, never kill the chat.
+  const turnRecords = [];
+  const upsertGraph = async (ended) => {
+    if (!turnRecords.length) return; // a zero-turn session never pollutes the graph
+    try { await appendSessionToGraph(config.graphFile, { id: sessionId, started: startIso, ended, turns: turnRecords }); }
+    catch { /* best-effort — see above */ }
+  };
+
+  const dim = (s) => (env.NO_COLOR || !output.isTTY ? s : `\x1b[2m${s}\x1b[0m`);
+  output.write(dim(`seonix chat — ${repo} — ${moduleCount} module(s) — log ${logFile}`) + "\n");
+  output.write(dim("ask a question about this codebase — /exit to leave") + "\n");
+
+  const rl = createInterface({ input, output, prompt: PROMPT });
+  rl.on("SIGINT", () => rl.close()); // Ctrl+C behaves like /exit (clean close, log flushed)
+  let closed = false;
+  rl.on("close", () => { closed = true; });
+  const prompt = () => { if (!closed) rl.prompt(); }; // input may end while a turn is in flight
+
+  let turns = 0;
+  prompt();
+  for await (const raw of rl) { // Ctrl+D / closed stdin ends the iteration cleanly
+    const line = raw.trim();
+    if (line === "/exit") break;
+    if (line) {
+      const { answer, logLines, record } = await runTurn(line, { config, source, graph });
+      output.write(answer + "\n");
+      await writeLog(logLines.join("\n") + "\n");
+      await writeSidecar(record);
+      turnRecords.push(record);
+      await upsertGraph(record.ts);
+      turns += 1;
+    }
+    prompt();
+  }
+  rl.close();
+
+  const endIso = new Date().toISOString();
+  await writeLog(`${endIso}\n> /exit\nsession end ${endIso}\n`);
+  await writeSidecar({ type: "end", ts: endIso });
+  await upsertGraph(endIso);
+  await new Promise((resolve) => stream.end(resolve));
+  await new Promise((resolve) => sidecar.end(resolve));
+  return { logFile, sidecarFile, turns };
+}

package/src/codegraph.mjs

@@ -1,4 +1,5 @@
 import { lookupByProseTokens } 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,49 @@ 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
 
+// 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 +545,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 +673,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, 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 +686,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 +728,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 +869,38 @@ function scoreModules(graph, tokens, opts = {}) {
       }
     }
   }
+  // §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 +916,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 };