@polycode-projects/seonix 0.1.0

package/src/codegraph.mjs

@@ -0,0 +1,1313 @@
+// 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
+// src/extract.mjs):
+//
+//   {
+//     generated_at, classes: [{name, count, sample[]}],
+//     objectProperties: [{predicate, prop, count, examples: [{subject, object,
+//                         subjectLabel, objectLabel}]}],
+//     individuals: [{id, label, class, derived_from: [ref], mentions: [{id, count}],
+//                    attributes?: [{prop, key, value}]}],
+//   }
+//
+// Ported ≈verbatim from marginalia seon-mcp/src/codegraph.mjs (the shipped,
+// tested typed-edge query layer). The only edits: provenance/attestation wording
+// is code-graph-generic (git:<sha> / file:line refs, not memory-node prose), and
+// a renderSearch() is added for the local, deterministic seonix_search.
+//
+// Edge inventory is read DYNAMICALLY from the payload (predicate verb + the closed
+// `prop` token like "mg:imports"); only the kind-classifier for the impact closure
+// hardcodes the relation set.
+
+// ---- payload parsing ---------------------------------------------------------
+
+export function parseEntities(payload) {
+  const individuals = Array.isArray(payload?.individuals) ? payload.individuals : [];
+  const byId = new Map();
+  for (const ind of individuals) {
+    if (ind && ind.id) byId.set(ind.id, ind);
+  }
+  const relations = (Array.isArray(payload?.objectProperties) ? payload.objectProperties : [])
+    .filter((g) => g && (g.predicate || g.prop))
+    .map((g) => {
+      const edges = (Array.isArray(g.examples) ? g.examples : []).filter((e) => e && e.subject && e.object);
+      return {
+        predicate: String(g.predicate || ""),
+        prop: g.prop || null,
+        count: Number(g.count) || edges.length,
+        edges,
+      };
+    });
+  const truncated = relations
+    .filter((g) => g.count > g.edges.length)
+    .map((g) => ({ predicate: g.predicate, count: g.count, shown: g.edges.length }));
+  return {
+    individuals,
+    byId,
+    relations,
+    truncated,
+    generatedAt: payload?.generated_at || null,
+  };
+}
+
+// ---- relation-kind classifier (for impact + tests-coverage) -------------------
+
+const KINDS = ["imports", "calls", "defines", "tests", "touches", "contains", "inherits", "callsSymbol", "touchesSymbol"];
+
+// Closed prop tokens → relation kind. Primary vocabulary is SEON (se-on.org) +
+// our `mgx:` extension; the legacy `mg:` tokens are kept so a stale artifact still
+// classifies. Lower-cased keys.
+const PROP_KIND = {
+  // v2.0 faithful tokens (SEONIX realign)
+  "mgx:importsnamespace": "imports",
+  "mgx:callscoarse": "calls",
+  "seon:declaresmethod": "defines",
+  "mgx:testscoverage": "tests",
+  "mgx:touchedbycommit": "touches",
+  "seon:containscodeentity": "contains",
+  "seon:hassupertype": "inherits",
+  "mgx:changecoupledwith": "cochange",
+  "mgx:reexports": "reexports",
+  // fine-grained symbol-level edges (Commit→symbol history, fn→fn in-repo calls).
+  // These stay SEPARATE kinds from the module-coarse "touches"/"calls" so the impact
+  // closure (module-coarse) is unchanged.
+  "mgx:touchessymbol": "touchesSymbol",
+  "mgx:callssymbol": "callsSymbol",
+  // legacy tokens (pre-realign graphs) — kept so a stale artifact still classifies
+  "seon:usescomplextype": "imports",
+  "seon:invokesmethod": "calls",
+  "seon:history": "touches",
+  "mgx:subclassof": "inherits",
+  "mg:imports": "imports",
+  "mg:calls": "calls",
+  "mg:defines": "defines",
+  "mg:tests": "tests",
+  "mg:touches": "touches",
+};
+
+export function relationKind(group) {
+  const prop = String(group?.prop || "").toLowerCase();
+  if (PROP_KIND[prop]) return PROP_KIND[prop];
+  const pred = String(group?.predicate || "").toLowerCase();
+  // symbol-granular fallbacks first, so a near-miss token name still classifies to the
+  // fine-grained kind rather than collapsing to module-coarse calls/touches.
+  if (/symbol/.test(pred)) {
+    if (/\b(call|invoke)/.test(pred)) return "callsSymbol";
+    if (/(touch|chang|modif)/.test(pred)) return "touchesSymbol";
+  }
+  if (/\bimport/.test(pred)) return "imports";
+  if (/\b(call|invoke)/.test(pred)) return "calls";
+  if (/\b(define|export|declare)/.test(pred)) return "defines";
+  if (/\b(test|cover)/.test(pred)) return "tests";
+  if (/\b(touch|chang|modif)/.test(pred)) return "touches";
+  if (/\bcontain/.test(pred)) return "contains";
+  if (/\b(inherit|subclass|extend|specializ)/.test(pred)) return "inherits";
+  return null;
+}
+
+// ---- symbol resolution (exact → normalised path → substring) ------------------
+
+function normPath(s) {
+  return String(s || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\.\//, "")
+    .replace(/^\//, "");
+}
+
+function basename(p) {
+  const parts = normPath(p).split("/");
+  return parts[parts.length - 1];
+}
+
+// Attestation: a ref prefixed `git:` (a commit that touched the entity) counts as
+// one mention, so better-attested (more-churned) entities rank/render ahead of
+// untouched ones even before per-node mention counts exist.
+const isProvRef = (r) => /^(git|turn):/.test(String(r || ""));
+
+export function turnRefCount(ind) {
+  return (ind?.derived_from || []).filter(isProvRef).length;
+}
+
+export function mentionTotal(ind) {
+  const fromMentions = (ind?.mentions || []).reduce((n, m) => n + (Number(m?.count) || 0), 0);
+  return fromMentions + turnRefCount(ind);
+}
+
+/**
+ * Rank individuals against a symbol. Tiers:
+ *   100 exact (label or id, case-insensitive)
+ *    80 normalised path (path suffix / basename / extension-stripped basename)
+ *    50 substring (label contains symbol), minus a length penalty
+ * Ties break on mention total (better-attested first), then label length.
+ * Returns { match, candidates } — candidates are the runners-up (≤4).
+ */
+export function resolveSymbol(graph, symbol) {
+  const s = normPath(symbol);
+  if (!s) return { match: null, candidates: [] };
+  const sBase = basename(s);
+  const scored = [];
+  for (const ind of graph.individuals) {
+    const label = normPath(ind.label);
+    const id = String(ind.id || "").toLowerCase();
+    let score = 0;
+    if (label === s || id === s) score = 100;
+    else if (
+      label.endsWith(`/${s}`) ||
+      basename(label) === sBase ||
+      basename(label).replace(/\.[a-z]+$/, "") === sBase
+    )
+      score = 80;
+    else if (label.includes(s)) score = Math.max(10, 50 - (label.length - s.length));
+    if (score > 0) scored.push({ ind, score });
+  }
+  scored.sort(
+    (a, b) =>
+      b.score - a.score ||
+      mentionTotal(b.ind) - mentionTotal(a.ind) ||
+      String(a.ind.label).length - String(b.ind.label).length,
+  );
+  return {
+    match: scored[0]?.ind || null,
+    candidates: scored.slice(1, 5).map((x) => x.ind),
+  };
+}
+
+// ---- source site (for seonix_snippet) -------------------------------------------
+
+/** Parse a Function/Class individual's `site` attribute ("path:start[-end]") into
+ *  {path, start, end}, or null if it has none (e.g. a Module). Pure. */
+export function siteOf(ind) {
+  const a = (ind?.attributes || []).find((x) => x.key === "site");
+  if (!a) return null;
+  const m = String(a.value).match(/^(.*):(\d+)(?:-(\d+))?$/);
+  if (!m) return null;
+  return { path: m[1], start: Number(m[2]), end: m[3] ? Number(m[3]) : Number(m[2]) };
+}
+
+// ---- describe ------------------------------------------------------------------
+
+function edgesFor(graph, id) {
+  const out = [];
+  const incoming = [];
+  for (const g of graph.relations) {
+    const outgoing = g.edges.filter((e) => e.subject === id);
+    const inbound = g.edges.filter((e) => e.object === id);
+    if (outgoing.length) out.push({ group: g, edges: outgoing });
+    if (inbound.length) incoming.push({ group: g, edges: inbound });
+  }
+  return { out, incoming };
+}
+
+function relLabel(g) {
+  return g.prop ? `${g.predicate} [${g.prop}]` : g.predicate;
+}
+
+// Bounded list rendering — token efficiency is the whole point of the graph, so
+// hub entities must never dump hundreds of edges. Show the first `n`, then a
+// "+K more" tail with the true count.
+function capJoin(items, n, sep = ", ") {
+  if (items.length <= n) return items.join(sep);
+  return items.slice(0, n).join(sep) + `, +${items.length - n} more`;
+}
+
+const DESCRIBE_EDGE_CAP = 30;
+const PROV_CAP = 8;
+
+/** Compact plain-text description of one individual — for an agent consumer. */
+export function renderDescribe(graph, ind, { candidates = [] } = {}) {
+  const lines = [];
+  lines.push(`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`);
+
+  const refs = (ind.derived_from || []).filter(isProvRef);
+  if (refs.length) lines.push(`attestation: touched by ${refs.length} commit(s)`);
+
+  for (const a of ind.attributes || []) {
+    lines.push(`attribute: ${a.key} = ${a.value}${a.prop ? ` [${a.prop}]` : ""}`);
+  }
+
+  const { out, incoming } = edgesFor(graph, ind.id);
+  if (!out.length && !incoming.length) {
+    lines.push("edges: none in the current artifact");
+  } else {
+    lines.push("edges:");
+    for (const { group, edges } of out) {
+      lines.push(`  ${relLabel(group)} (${edges.length}) → ${capJoin(edges.map((e) => e.objectLabel || e.object), DESCRIBE_EDGE_CAP)}`);
+    }
+    for (const { group, edges } of incoming) {
+      lines.push(`  ← ${relLabel(group)} (${edges.length}) by ${capJoin(edges.map((e) => e.subjectLabel || e.subject), DESCRIBE_EDGE_CAP)}`);
+    }
+  }
+
+  const prov = (ind.derived_from || []);
+  if (prov.length) {
+    lines.push(`provenance: ${capJoin(prov, PROV_CAP)}`);
+  }
+
+  if (candidates.length) {
+    lines.push(`other matches: ${candidates.map((c) => `${c.label} (${c.class})`).join(", ")}`);
+  }
+  if (graph.truncated.length) {
+    lines.push(truncationNote(graph));
+  }
+  return lines.join("\n");
+}
+
+function truncationNote(graph) {
+  const list = graph.truncated.map((t) => `${t.predicate} (${t.shown}/${t.count})`).join(", ");
+  return `note: partial edge lists for: ${list}. Counts are complete; the lists are not.`;
+}
+
+// ---- impact (transitive reverse closure over imports/calls) ---------------------
+
+/**
+ * BFS the REVERSE of imports/calls edges from `ind` — "what would break".
+ * Diamonds collapse (a node appears once, at its shortest depth); cycles
+ * terminate via the visited set. Each dependent carries the via-predicate and
+ * the test modules covering it (subjects of tests-kind edges pointing at it).
+ */
+export function impactClosure(graph, ind, { maxDepth = 8 } = {}) {
+  const dependents = new Map();
+  const coveredBy = new Map(); // moduleId → [test labels]
+  for (const g of graph.relations) {
+    const kind = relationKind(g);
+    if (kind === "imports" || kind === "calls") {
+      for (const e of g.edges) {
+        if (!dependents.has(e.object)) dependents.set(e.object, []);
+        dependents.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject, via: g.predicate });
+      }
+    } else if (kind === "tests") {
+      for (const e of g.edges) {
+        if (!coveredBy.has(e.object)) coveredBy.set(e.object, []);
+        coveredBy.get(e.object).push(e.subjectLabel || e.subject);
+      }
+    }
+  }
+
+  const levels = []; // [[{id, label, via, tests[]}], …] indexed by depth-1
+  const visited = new Set([ind.id]);
+  let frontier = [ind.id];
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    const next = [];
+    const level = [];
+    for (const id of frontier) {
+      for (const dep of dependents.get(id) || []) {
+        if (visited.has(dep.id)) continue;
+        visited.add(dep.id);
+        level.push({ ...dep, tests: coveredBy.get(dep.id) || [] });
+        next.push(dep.id);
+      }
+    }
+    if (level.length) {
+      level.sort((a, b) => String(a.label).localeCompare(String(b.label)));
+      levels.push(level);
+    }
+    frontier = next;
+  }
+  return levels;
+}
+
+const IMPACT_DEPTHS_LISTED = 2;   // list members for the first N depths; deeper = counts only
+const IMPACT_PER_DEPTH = 25;      // members listed per depth
+const IMPACT_TESTS_PER_DEP = 3;   // covering tests listed per dependent
+
+export function renderImpact(graph, ind, { maxDepth = 8 } = {}) {
+  const levels = impactClosure(graph, ind, { maxDepth });
+  const lines = [`Impact of changing ${ind.label} (reverse closure over imports/calls edges):`];
+  if (!levels.length) {
+    lines.push("no dependents found in the current artifact — nothing imports or calls it (or its edges are not in the extracted graph yet).");
+  }
+  const totalCount = levels.reduce((n, l) => n + l.length, 0);
+  // Headline first so the magnitude is clear even when the lists are capped.
+  if (levels.length) {
+    lines.push(`total: ${totalCount} dependent(s) across ${levels.length} depth level(s) (lists capped for brevity).`);
+  }
+  levels.forEach((level, i) => {
+    if (i >= IMPACT_DEPTHS_LISTED) {
+      lines.push(`depth ${i + 1}: ${level.length} more dependent(s) (not listed)`);
+      return;
+    }
+    lines.push(i === 0 ? `depth 1 (${level.length} direct dependents):` : `depth ${i + 1} (${level.length}):`);
+    for (const dep of level.slice(0, IMPACT_PER_DEPTH)) {
+      const tests = dep.tests.length
+        ? `tests: ${capJoin(dep.tests, IMPACT_TESTS_PER_DEP)}`
+        : "tests: none recorded";
+      lines.push(`  - ${dep.label} (${dep.via} it) — ${tests}`);
+    }
+    if (level.length > IMPACT_PER_DEPTH) lines.push(`  …+${level.length - IMPACT_PER_DEPTH} more at depth ${i + 1}`);
+  });
+  const truncatedStructural = graph.truncated.filter((t) => {
+    const kind = relationKind({ predicate: t.predicate });
+    return kind === "imports" || kind === "calls" || kind === "tests";
+  });
+  if (truncatedStructural.length) {
+    lines.push(
+      "warning: partial edge lists (" +
+        truncatedStructural.map((t) => `${t.predicate}: ${t.shown}/${t.count}`).join(", ") +
+        ") — this closure may be missing edges. Cross-check critical results with seonix_search.",
+    );
+  }
+  return lines.join("\n");
+}
+
+// ---- search (local, deterministic lexical lookup) ------------------------------
+
+/** Index subjectId → [defined symbol labels] from the defines relation, once. */
+function definesIndex(graph) {
+  const idx = new Map();
+  for (const g of graph.relations) {
+    if (relationKind(g) !== "defines") continue;
+    for (const e of g.edges) {
+      if (!idx.has(e.subject)) idx.set(e.subject, []);
+      idx.get(e.subject).push(e.objectLabel || e.object);
+    }
+  }
+  return idx;
+}
+
+/**
+ * Local, deterministic free-text lookup over the typed graph — the offline
+ * replacement for marginalia's LLM-backed A2A seonix_search. Finds the MODULE
+ * where code lives ("where do template filters / validators live?"): scores
+ * modules by query-token hits in the path (strong) plus the count of DEFINED
+ * SYMBOLS whose name matches a token (capped so a giant module can't dominate),
+ * with a penalty for test modules. Renders each hit compactly with the matching
+ * symbols, so the agent can jump straight to seonix_describe. No model calls.
+ */
+const SEARCH_LIMIT = 10;
+const SEARCH_SYMBOLS_SHOWN = 8;
+// B012 locate scoring — IDF-weighted, component-aware. The rig queries with the WHOLE problem
+// statement, so ubiquitous tokens (template/filter/value/text) would swamp the score; weight each
+// token by rarity across modules (inverse module-frequency) so the distinctive term decides. Match
+// identifier COMPONENTS (boundary-aware) so "text" hits utils/text.py but NOT "ci<text>". An EXACT
+// defined-symbol-name hit is the strongest "the code lives here" signal. Deterministic; no models.
+const PATH_W = 3;          // token == a path component (django/utils/<text>.py)
+const SYM_W = 2;           // token == a component of a defined symbol name
+const EXACT_W = 5;         // token == a whole defined symbol name (strongest locate signal)
+const SYM_MATCH_CAP = 4;   // only the top-K highest-IDF symbol-COMPONENT hits count, so a giant
+                           // bag-of-symbols module (e.g. db/backends features) can't accrete noise
+const PROX_FRAC = 0.2;     // import-adjacency bonus = this × the strongest matched neighbour …
+const PROX_CAP_FRAC = 0.35; //  … capped at this × the module's own score (a nudge — hubs can't run away)
+const isTestLabel = (s) => /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
+
+/** 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) {
+  return new Set(labelLc.split(/[^a-z0-9]+/).filter(Boolean));
+}
+/** Split an identifier into lowercased components across snake_case AND camelCase boundaries:
+ *  get_text_list → {get,text,list}; TruncatorLines → {truncator,lines}. */
+function identComponents(name) {
+  return new Set(String(name).replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+
+/** The shared module-ranking core behind renderSearch (text) and searchModulesRanked (path+score).
+ *  IDF-weights each query token by rarity across modules (so a whole-problem-statement query is not
+ *  swamped by ubiquitous words like template/filter/value), scores path-component + symbol-component
+ *  + 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) {
+  const defIdx = definesIndex(graph);
+  // Precompute each module's path components + defined-symbol exact/component sets, once.
+  const modules = [];
+  for (const ind of graph.individuals) {
+    if ((ind.class || "") !== "Module") continue; // "where does this live" → modules
+    const label = String(ind.label);
+    const labelLc = label.toLowerCase();
+    const defines = defIdx.get(ind.id) || [];
+    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 });
+  }
+  const N = modules.length || 1;
+  // Inverse module-frequency: a token in many modules carries little locating signal; a rare one
+  // decides. df = modules where the token appears in the path (substring — keeps "filter" matching
+  // "defaultfilters"), as a symbol component, or as an exact symbol name. A loose path substring like
+  // "text" that hits many modules therefore earns a low weight, so "ci<text>" can't beat utils/text.py.
+  // idf = log(1 + N/(1+df)) → ~0 for ubiquitous tokens, large for rare ones.
+  const idf = new Map();
+  for (const t of tokens) {
+    if (idf.has(t)) continue;
+    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)));
+  }
+  const scored = [];
+  for (const m of modules) {
+    let exactScore = 0, pathScore = 0, matchCount = 0;
+    const compWeights = []; // weak symbol-component hits, capped below so big modules can't run away
+    for (const t of tokens) {
+      const w = idf.get(t) || 0;
+      if (!w) continue;
+      if (m.symSet.has(t)) { exactScore += w * EXACT_W; matchCount++; }   // exact defined-symbol name
+      else if (m.symComps.has(t)) { compWeights.push(w); matchCount++; }  // a component of a symbol name
+      if (m.labelLc.includes(t)) pathScore += w * PATH_W;                 // path substring (IDF-tamed)
+    }
+    compWeights.sort((a, b) => b - a);
+    let symScore = 0;
+    for (let i = 0; i < Math.min(compWeights.length, SYM_MATCH_CAP); i++) symScore += compWeights[i] * SYM_W;
+    let score = exactScore + pathScore + symScore;
+    if (!score) continue;
+    if (isTestLabel(m.label.toLowerCase())) score *= 0.4; // source first; tests still discoverable
+    const matching = m.defines.filter((d) => { const dl = d.toLowerCase(); const cs = identComponents(d); return tokens.some((t) => dl === t || cs.has(t)); });
+    const density = m.defines.length ? matchCount / m.defines.length : 0;
+    scored.push({ ind: m.ind, score, defineCount: m.defines.length, matching, density });
+  }
+  // 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.
+  if (scored.length > 1) {
+    const baseById = new Map(scored.map((s) => [s.ind.id, s.score]));
+    const adj = new Map();
+    for (const e of edgesOfKind(graph, "imports")) {
+      if (!baseById.has(e.subject) && !baseById.has(e.object)) continue;
+      if (!adj.has(e.subject)) adj.set(e.subject, new Set());
+      if (!adj.has(e.object)) adj.set(e.object, new Set());
+      adj.get(e.subject).add(e.object);
+      adj.get(e.object).add(e.subject);
+    }
+    for (const s of scored) {
+      let bestNeighbor = 0;
+      for (const nid of adj.get(s.ind.id) || []) bestNeighbor = Math.max(bestNeighbor, baseById.get(nid) || 0);
+      s.score += Math.min(bestNeighbor * PROX_FRAC, s.score * PROX_CAP_FRAC);
+    }
+  }
+  // Tie-break: score → matched-symbol DENSITY (concrete, not ground truth) → fewer defines → shorter label.
+  scored.sort((a, b) => b.score - a.score || b.density - a.density || a.defineCount - b.defineCount || String(a.ind.label).length - String(b.ind.label).length);
+  return scored;
+}
+
+/** TUNING #3: the ranked module list as plain `{path, score}` (highest-first), using the SAME
+ *  ranking renderSearch uses (path + symbol + exact-symbol + import-proximity). Lets the rig
+ *  read the score GAP between rank-1 and rank-2 (which the text renderer hides) so it can keep
+ *  rank-2 only when it is close. Pure; deterministic. */
+export function searchModulesRanked(graph, query) {
+  const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+  if (!tokens.length) return [];
+  return scoreModules(graph, tokens).map((s) => ({ path: String(s.ind.label), score: s.score }));
+}
+
+export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
+  const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+  const wantKind = String(kind || "").trim().toLowerCase();
+  const decFilter = String(decorator || "").trim().toLowerCase();
+  let nameRe = null;
+  if (name) {
+    try { nameRe = new RegExp(name, "i"); } catch { return `invalid name pattern: ${name}`; }
+  }
+  // kind= switches to symbol search (functions/classes/methods/attributes); the
+  // default (no kind) keeps the module "where does this live" search unchanged.
+  if (wantKind && wantKind !== "module") {
+    return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe });
+  }
+  if (!tokens.length && !nameRe && !decFilter) return "empty query";
+  const scored = scoreModules(graph, tokens);
+  if (!scored.length) {
+    return `no module matches "${query}". Try broader keywords, or seonix_describe <path> if you know where it lives.`;
+  }
+  const hits = scored.slice(0, limit);
+  const lines = [`${scored.length} module(s) match "${query}" (top ${hits.length}):`];
+  for (const { ind, defineCount, matching } of hits) {
+    const m = matching.length ? ` — matching: ${capJoin([...new Set(matching)], SEARCH_SYMBOLS_SHOWN)}` : "";
+    lines.push(`- ${ind.label} (defines ${defineCount} symbol(s))${m}`);
+  }
+  lines.push("Then seonix_describe <path> for the full sibling list + typed edges, or seonix_impact <path> for dependents.");
+  return lines.join("\n");
+}
+
+// ---- §9 read-replacing tools (members / inheritance / architecture / coverage /
+//      history / call neighbours). Each answers ONE question in one compact call so
+//      the agent need not Read/Grep. All keep the bounded-output discipline. -------
+
+/** All edges whose relation classifies to `kind`, flattened across relation groups. */
+function edgesOfKind(graph, kind) {
+  const out = [];
+  for (const g of graph.relations) if (relationKind(g) === kind) out.push(...g.edges);
+  return out;
+}
+
+/** The module id an individual belongs to (itself if a Module; via its site span,
+ *  else parsed from an `fn:<path>#name` id). Null if it cannot be mapped. */
+function moduleIdOf(graph, ind) {
+  if ((ind?.class || "") === "Module") return ind.id;
+  const site = siteOf(ind);
+  if (site) return `mod:${site.path}`;
+  const m = String(ind?.id || "").match(/^fn:(.+)#/);
+  return m ? `mod:${m[1]}` : null;
+}
+
+function spanTag(site) {
+  if (!site) return "";
+  const s = site.end > site.start ? `${site.start}-${site.end}` : `${site.start}`;
+  return ` [${site.path}:${s}]`;
+}
+
+function decoratorOf(ind) {
+  return (ind?.attributes || []).find((a) => a.key === "decorators")?.value || "";
+}
+
+const MEMBERS_CAP = 40;
+const SUBCLASS_CAP = 40;
+const CALL_CAP = 30;
+
+/** A class's methods + attributes (with sites/decorators) in one slice — replaces
+ *  reading the class body. Uses the `contains` (seon:containsCodeEntity) relation. */
+export function renderMembers(graph, ind) {
+  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id);
+  if (!contains.length) {
+    lines.push("members: none recorded (empty class, or members not in the extracted graph). Use seonix_describe for its edges.");
+    return lines.join("\n");
+  }
+  const methods = [];
+  const attrs = [];
+  for (const e of contains) {
+    const member = graph.byId.get(e.object);
+    const where = spanTag(member ? siteOf(member) : null);
+    const dec = member ? decoratorOf(member) : "";
+    const entry = `${e.objectLabel || e.object}${where}${dec ? ` @${dec}` : ""}`;
+    ((member?.class || "") === "Attribute" ? attrs : methods).push(entry);
+  }
+  if (methods.length) lines.push(`methods (${methods.length}): ${capJoin(methods, MEMBERS_CAP)}`);
+  if (attrs.length) lines.push(`attributes (${attrs.length}): ${capJoin(attrs, MEMBERS_CAP)}`);
+  lines.push("Use seonix_snippet <Class.member> for an exact body.");
+  return lines.join("\n");
+}
+
+const attrVal = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)?.value || "";
+
+/** The mechanical-enrichment signature of a symbol in ONE compact block — params,
+ *  return annotation, raises/catches, self-fields, flags, decorators, one-line doc —
+ *  so the agent gets the API surface without reading the body. Deterministic ast facts
+ *  (kept OUT of seonix_context's lean bundle; this is the targeted tool for them). */
+export function renderSignature(graph, ind) {
+  const site = siteOf(ind);
+  const lines = [`${ind.label} — ${ind.class || "Entity"}${spanTag(site)}`];
+  const params = attrVal(ind, "params");
+  const returns = attrVal(ind, "returns");
+  if (params || returns || (ind.class || "") === "Method" || (ind.class || "") === "Function") {
+    lines.push(`signature: ${ind.label}(${params})${returns ? ` -> ${returns}` : ""}`);
+  }
+  const flags = [];
+  if (attrVal(ind, "isStatic")) flags.push("static");
+  if (attrVal(ind, "isAbstract")) flags.push("abstract");
+  if (attrVal(ind, "isConstant")) flags.push("constant");
+  const vis = attrVal(ind, "visibility");
+  if (vis) flags.push(vis);
+  if (flags.length) lines.push(`flags: ${flags.join(", ")}`);
+  const dec = decoratorOf(ind);
+  if (dec) lines.push(`decorators: @${dec.split(", ").join(", @")}`);
+  const raises = attrVal(ind, "raises");
+  if (raises) lines.push(`raises: ${raises}`);
+  const catches = attrVal(ind, "catches");
+  if (catches) lines.push(`catches: ${catches}`);
+  const fields = attrVal(ind, "self_fields");
+  if (fields) lines.push(`self fields: ${fields}`);
+  const value = attrVal(ind, "value");
+  if (value) lines.push(`value: ${value}`);
+  const doc = attrVal(ind, "doc");
+  if (doc) lines.push(`doc: ${doc}`);
+  if (lines.length === 1) lines.push("(no signature detail recorded for this symbol — likely a module or attribute; use seonix_snippet for its source.)");
+  lines.push("Use seonix_snippet for the exact body.");
+  return lines.join("\n");
+}
+
+/** Forward bases + the transitive reverse inheritance closure (who extends this) —
+ *  replaces grepping `class X(Base)` across the tree. Uses `inherits` (mgx:subclassOf). */
+export function renderSubclasses(graph, ind) {
+  const inherits = edgesOfKind(graph, "inherits");
+  const bases = inherits.filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object);
+  const childrenOf = new Map();
+  for (const e of inherits) {
+    if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
+    childrenOf.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject });
+  }
+  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  lines.push(bases.length ? `extends: ${capJoin(bases, SUBCLASS_CAP)}` : "extends: (no internal/recorded base classes)");
+  const visited = new Set([ind.id]);
+  const levels = [];
+  let frontier = [ind.id];
+  for (let depth = 1; depth <= 8 && frontier.length; depth += 1) {
+    const next = [];
+    const level = [];
+    for (const id of frontier) {
+      for (const c of childrenOf.get(id) || []) {
+        if (visited.has(c.id)) continue;
+        visited.add(c.id);
+        level.push(c.label);
+        next.push(c.id);
+      }
+    }
+    if (level.length) {
+      level.sort((a, b) => String(a).localeCompare(String(b)));
+      levels.push(level);
+    }
+    frontier = next;
+  }
+  const total = levels.reduce((n, l) => n + l.length, 0);
+  if (!total) {
+    lines.push("subclasses: none recorded — nothing extends it in the extracted graph.");
+  } else {
+    lines.push(`subclasses: ${total} total across ${levels.length} level(s).`);
+    levels.forEach((l, i) => lines.push(`  depth ${i + 1} (${l.length}): ${capJoin(l, SUBCLASS_CAP)}`));
+  }
+  return lines.join("\n");
+}
+
+const ARCH_PKG_CAP = 25;
+const ARCH_HUB_CAP = 15;
+
+/** Package/module tree + the most-imported (hub) modules — replaces reading the dir
+ *  tree and many files to learn the shape. Optional `pkg` prefix scopes it. */
+export function renderArchitecture(graph, { pkg = "" } = {}) {
+  const norm = normPath(pkg);
+  const modules = graph.individuals.filter(
+    (i) => (i.class || "") === "Module" && (!norm || normPath(i.label).startsWith(norm)),
+  );
+  if (!modules.length) return norm ? `no modules under "${pkg}".` : "no modules in the graph.";
+  const pkgCount = new Map();
+  for (const m of modules) {
+    const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
+    pkgCount.set(dir, (pkgCount.get(dir) || 0) + 1);
+  }
+  const inDeg = new Map();
+  for (const e of edgesOfKind(graph, "imports")) inDeg.set(e.object, (inDeg.get(e.object) || 0) + 1);
+  const modSet = new Set(modules.map((m) => m.id));
+  const hubs = [...inDeg.entries()]
+    .filter(([id]) => modSet.has(id))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, ARCH_HUB_CAP)
+    .map(([id, n]) => `${graph.byId.get(id)?.label || id} (${n} importers)`);
+  const pkgs = [...pkgCount.entries()].sort((a, b) => b[1] - a[1]);
+  const lines = [`Architecture${norm ? ` of ${pkg}` : ""}: ${modules.length} module(s) in ${pkgs.length} package(s).`];
+  lines.push(`packages (by module count): ${capJoin(pkgs.map(([d, n]) => `${d} (${n})`), ARCH_PKG_CAP)}`);
+  lines.push(hubs.length ? `hub modules (most imported): ${hubs.join(", ")}` : "hub modules: none (no internal imports recorded).");
+  return lines.join("\n");
+}
+
+const COVERAGE_CAP = 40;
+
+/** The test modules covering a symbol/module — from the `tests` (mgx:testsCoverage)
+ *  relation. Replaces grepping `tests/` for who imports the target. */
+export function renderTestsFor(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const tests = [...new Set(edgesOfKind(graph, "tests").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))];
+  if (!tests.length) return `${modLabel}: no covering tests recorded (no test module imports it).`;
+  return `${modLabel}: covered by ${tests.length} test module(s):\n  ${capJoin(tests, COVERAGE_CAP, "\n  ")}`;
+}
+
+/** Source modules with no covering test module — a coverage gap view. Test
+ *  modules (subjects of test edges, or test-named paths) are excluded. */
+export function renderUntested(graph) {
+  const covered = new Set();
+  const testModules = new Set();
+  for (const e of edgesOfKind(graph, "tests")) {
+    covered.add(e.object);
+    testModules.add(e.subject);
+  }
+  const untested = graph.individuals
+    .filter(
+      (i) =>
+        (i.class || "") === "Module" &&
+        !testModules.has(i.id) &&
+        !isTestLabel(String(i.label).toLowerCase()) &&
+        !covered.has(i.id),
+    )
+    .map((i) => i.label)
+    .sort();
+  if (!untested.length) return "every source module has at least one covering test module.";
+  return `${untested.length} source module(s) with no covering test module:\n  ${capJoin(untested, COVERAGE_CAP, "\n  ")}`;
+}
+
+const HISTORY_CAP = 15;
+
+/** Recent commits that touched a symbol's module — from `touches` (seon:history).
+ *  Replaces `git log -- <file>`. Commits are listed newest-first (git-log order). */
+export function renderHistory(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const commits = edgesOfKind(graph, "touches").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject);
+  if (!commits.length) return `${modLabel}: no commit history recorded (outside the git-log window or unmodified).`;
+  return `${modLabel}: touched by ${commits.length} recent commit(s): ${capJoin(commits, HISTORY_CAP)}`;
+}
+
+/** Modules that call into the target's module (one hop over `calls`). */
+export function renderCallers(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const callers = [...new Set(edgesOfKind(graph, "calls").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))];
+  if (!callers.length) return `${modLabel}: no recorded callers (calls are coarse/import-backed — absence is not proof). Try seonix_impact for the full reverse closure.`;
+  return `${modLabel} — called by ${callers.length} module(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
+}
+
+/** Modules the target's module calls into (one hop over `calls`). */
+export function renderCallees(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const callees = [...new Set(edgesOfKind(graph, "calls").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object))];
+  if (!callees.length) return `${modLabel}: no recorded callees.`;
+  return `${modLabel} — calls into ${callees.length} module(s):\n  ${capJoin(callees, CALL_CAP, "\n  ")}`;
+}
+
+// ---- fine-grained in-repo calls (fn→fn, `callsSymbol`) ---------------------------
+
+const CALL_HINT_CAP = 8;
+
+/** Format one fn→fn callee edge as `name [path:line]` (path:line from the callee's site). */
+function calleeRef(graph, e) {
+  const callee = graph.byId.get(e.object);
+  const cs = callee ? siteOf(callee) : null;
+  return `${e.objectLabel || callee?.label || e.object}${cs ? ` [${cs.path}:${cs.start}]` : ""}`;
+}
+
+/** One-line "calls in-repo: name [path:line], …" hint for a function — appended to
+ *  seonix_snippet and the seonix_context exemplar body so the agent sees the symbol's
+ *  in-repo call dependencies inline. Empty string when it calls nothing in-repo. Pure. */
+export function callHint(graph, ind) {
+  if (!ind?.id) return "";
+  const calls = edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id);
+  if (!calls.length) return "";
+  return `calls in-repo: ${capJoin(calls.map((e) => calleeRef(graph, e)), CALL_HINT_CAP)}`;
+}
+
+/** The in-repo symbols a function calls (fn→fn `callsSymbol` edges), with file:line.
+ *  Cold tool — replaces reading a body to learn its in-repo call graph. */
+export function renderCalls(graph, ind) {
+  const calls = edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id);
+  if (!calls.length) {
+    return `${ind.label} — ${ind.class || "Entity"}: no in-repo calls recorded (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
+  }
+  const items = calls.map((e) => calleeRef(graph, e));
+  return `${ind.label} — ${ind.class || "Entity"} calls ${calls.length} in-repo symbol(s):\n  ${capJoin(items, CALL_CAP, "\n  ")}`;
+}
+
+// ---- commit history with author/date/subject (Commit attributes) ----------------
+
+/** One commit rendered as "<sha> <date> <author> — <subject>", from the Commit
+ *  individual's commitAuthor/commitDate/commitMessage attributes (graceful when absent). */
+function commitLine(graph, commitId, fallbackLabel) {
+  const c = graph.byId.get(commitId);
+  const sha = c?.label || fallbackLabel || commitId;
+  // Tolerate either attribute-key convention (commitAuthor/… or the shorter author/…).
+  const date = attrVal(c, "commitDate") || attrVal(c, "date");
+  const author = attrVal(c, "commitAuthor") || attrVal(c, "author");
+  const msg = attrVal(c, "commitMessage") || attrVal(c, "message");
+  const head = [sha, date, author].filter(Boolean).join(" ");
+  return msg ? `${head} — ${msg}` : head;
+}
+
+/** File history: commits that touched a symbol's MODULE (module-coarse `touches`
+ *  edges), each with author/date/subject. Newest-first (git-log order preserved). */
+export function renderFileHistory(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const commits = edgesOfKind(graph, "touches").filter((e) => e.object === modId);
+  if (!commits.length) return `${modLabel}: no commit history recorded (outside the git-log window or unmodified).`;
+  const shown = commits.slice(0, HISTORY_CAP).map((e) => `  ${commitLine(graph, e.subject, e.subjectLabel)}`);
+  const tail = commits.length > HISTORY_CAP ? `\n  …+${commits.length - HISTORY_CAP} more` : "";
+  return `${modLabel}: touched by ${commits.length} recent commit(s):\n${shown.join("\n")}${tail}`;
+}
+
+/** Symbol-granular history: commits whose `touchesSymbol` edge points at THIS symbol's
+ *  id (method/class/function), each with author/date/subject. Used by method/class history. */
+function renderSymbolHistory(graph, ind) {
+  const commits = edgesOfKind(graph, "touchesSymbol").filter((e) => e.object === ind.id);
+  if (!commits.length) {
+    return `${ind.label} — ${ind.class || "Entity"}: no symbol-level commit history recorded (outside the git-log window, or fine-grained history is not in the extracted graph).`;
+  }
+  const shown = commits.slice(0, HISTORY_CAP).map((e) => `  ${commitLine(graph, e.subject, e.subjectLabel)}`);
+  const tail = commits.length > HISTORY_CAP ? `\n  …+${commits.length - HISTORY_CAP} more` : "";
+  return `${ind.label} — ${ind.class || "Entity"}: touched by ${commits.length} commit(s):\n${shown.join("\n")}${tail}`;
+}
+
+/** Method history — commits touching a specific method symbol (`touchesSymbol`). */
+export function renderMethodHistory(graph, ind) {
+  return renderSymbolHistory(graph, ind);
+}
+
+/** Class history — commits touching a specific class symbol (`touchesSymbol`). */
+export function renderClassHistory(graph, ind) {
+  return renderSymbolHistory(graph, ind);
+}
+
+// ---- symbol search (kind=function/class/method/attribute, with name/decorator filters)
+
+const SYMBOL_CLASSES = { function: "Function", class: "Class", method: "Method", attribute: "Attribute" };
+
+function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, nameRe }) {
+  const targetClass = SYMBOL_CLASSES[kind];
+  if (!targetClass) return `unknown kind "${kind}" (use function, class, method, attribute, or module).`;
+  const hits = [];
+  for (const ind of graph.individuals) {
+    if ((ind.class || "") !== targetClass) continue;
+    if (nameRe && !nameRe.test(ind.label)) continue;
+    if (decFilter && !decoratorOf(ind).toLowerCase().includes(decFilter)) continue;
+    const label = String(ind.label).toLowerCase();
+    let score = tokens.length ? 0 : 1;
+    for (const t of tokens) if (label.includes(t)) score += 5;
+    if (tokens.length && !score) continue;
+    hits.push({ ind, score });
+  }
+  if (!hits.length) return `no ${kind} matches the given filters.`;
+  hits.sort((a, b) => b.score - a.score || String(a.ind.label).length - String(b.ind.label).length);
+  const top = hits.slice(0, limit);
+  const lines = [`${hits.length} ${kind}(s) match (top ${top.length}):`];
+  for (const { ind } of top) lines.push(`- ${ind.label}${spanTag(siteOf(ind))}`);
+  lines.push("Then seonix_snippet <name> for the exact body, or seonix_describe for its edges.");
+  return lines.join("\n");
+}
+
+// ---- seonix_context: a one-shot "edit bundle" plan (pure; the server adds the file
+//      reads). Returns everything needed to add-a-sibling to a module in ONE call,
+//      so the agent need not search→describe→snippet→read×N (RepoGraph ego-network
+//      idea; LocAgent: structured, replacement-shaped output drives tool adoption).
+
+const CONTEXT_SIBLING_CAP = 8; // Lever 1: the bundle is re-billed every turn — keep a few most-relevant siblings, not all.
+const CLASS_MEMBER_CAP = 16;   // B007 gap (a): class-internal members shown when the anchor is a class/method.
+const COCHANGE_MID_CAP = 4;    // #13: trim the MID bundle's co-change tail (was 8) — re-billed every turn.
+const CONTEXT_TESTS_CAP = 6;   // #13: cap the covering-tests list in the bundle.
+const INSERTION_REGION_CAP = 40; // #2: contiguous tail lines shown as the "write your new sibling here" region.
+// #6 task-size thresholds (named, next to the caps above). B1/B6: widened so the COMMON
+// "add a small sibling util / register a filter" task lands at the lean TINY default (a 1-2
+// param helper with a short body), and only genuinely bigger edits top up to MID/LARGE.
+const TINY_MAX_LOC = 12;       // TINY: exemplar/anchor body ≤ this many lines …
+const TINY_MAX_ARITY = 2;      //   … AND ≤ this many params (value, arg) …
+const LARGE_CLASS_MEMBERS = 8; // LARGE: anchor is a method of a class with ≥ this many members ("big class").
+const INLINE_CALLEE_CAP = 3;   // LARGE: inline at most this many depth-1 in-repo callee bodies …
+const INLINE_CALLEE_LOC = 120; //   … up to this many total lines.
+
+const splitDecs = (s) => String(s || "").split(",").map((x) => x.trim()).filter(Boolean);
+const tokenize = (s) =>
+  String(s || "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const countParams = (p) => { const s = String(p || "").trim(); return s ? s.split(",").map((x) => x.trim()).filter(Boolean).length : 0; };
+const modeOf = (nums) => {
+  const freq = new Map();
+  let best = nums[0] ?? 0;
+  let bestN = 0;
+  for (const n of nums) { const c = (freq.get(n) || 0) + 1; freq.set(n, c); if (c > bestN) { bestN = c; best = n; } }
+  return best;
+};
+
+/** A symbol's structural profile (param count, has-returns/raises, in-repo callee set)
+ *  — the shape matched by the structural-similarity component of sibling ranking. */
+function profileOf(x) {
+  return {
+    paramCount: countParams(x?.params),
+    hasReturns: Boolean(x?.returns),
+    hasRaises: Boolean(x?.raises),
+    callees: x?.callees instanceof Set ? x.callees : new Set(),
+  };
+}
+
+/** When the anchor is a Module (no single anchor symbol), derive the dominant structural
+ *  pattern across the siblings so the exemplar can be chosen for structural closeness too. */
+function dominantProfile(siblings) {
+  if (!siblings.length) return { paramCount: 0, hasReturns: false, hasRaises: false, callees: new Set() };
+  const counts = siblings.map((s) => countParams(s.params));
+  const retYes = siblings.filter((s) => Boolean(s.returns)).length;
+  const raiseYes = siblings.filter((s) => Boolean(s.raises)).length;
+  const calleeFreq = new Map();
+  for (const s of siblings) for (const c of s.callees || []) calleeFreq.set(c, (calleeFreq.get(c) || 0) + 1);
+  const common = new Set([...calleeFreq.entries()].filter(([, n]) => n >= 2).map(([c]) => c));
+  return {
+    paramCount: modeOf(counts),
+    hasReturns: retYes * 2 >= siblings.length,
+    hasRaises: raiseYes * 2 >= siblings.length,
+    callees: common,
+  };
+}
+
+/** Structural affinity of a sibling to the target profile — bounded below name-affinity
+ *  (max 16 < the 50/token name weight), so it only breaks ties within a name/decorator tier. */
+function structuralScore(s, target) {
+  if (!target) return 0;
+  let score = Math.max(0, 4 - Math.abs(countParams(s.params) - target.paramCount));
+  if (Boolean(s.returns) === target.hasReturns) score += 2;
+  if (Boolean(s.raises) === target.hasRaises) score += 2;
+  const shared = [...(s.callees || [])].filter((c) => target.callees.has(c)).length;
+  return score + Math.min(shared, 4) * 2;
+}
+
+/** Lever 1: rank siblings by relevance to the anchor so the lean bundle shows the ones
+ *  worth copying — shared decorator (the module's registration pattern, e.g.
+ *  @register.filter) > name-affinity (shared tokens) > nearest source position. Pure;
+ *  mutates a transient `_score` only. */
+function rankSiblings(siblings, { decorators: anchorDecorators = "", label: anchorLabel = "", site: anchorSite = null } = {}, structuralTarget = null) {
+  const decCount = new Map();
+  for (const s of siblings) for (const d of splitDecs(s.decorators)) decCount.set(d, (decCount.get(d) || 0) + 1);
+  let dominant = "";
+  let bestCount = 1;
+  for (const [d, c] of decCount) if (c > bestCount) { bestCount = c; dominant = d; }
+  const anchorDecs = new Set(splitDecs(anchorDecorators));
+  const targetDecs = anchorDecs.size ? anchorDecs : new Set(dominant ? [dominant] : []);
+  const anchorTokens = new Set(tokenize(anchorLabel));
+  const anchorStart = anchorSite?.start ?? null;
+  for (const s of siblings) {
+    const decMatch = splitDecs(s.decorators).some((d) => targetDecs.has(d)) ? 1 : 0;
+    const nameAff = tokenize(s.label).filter((t) => anchorTokens.has(t)).length;
+    // #3: structural affinity (param-count / has-returns / has-raises / shared in-repo
+    // callees) sits BELOW name-affinity (max 16 < 50) — a tiebreaker within a name tier.
+    const struct = structuralScore(s, structuralTarget);
+    const pos = anchorStart != null && s.site ? 1 / (1 + Math.abs(s.site.start - anchorStart)) : 0;
+    s._score = decMatch * 1000 + nameAff * 50 + struct + pos;
+  }
+  return [...siblings].sort((a, b) => b._score - a._score || (a.site?.start || 0) - (b.site?.start || 0));
+}
+
+/** Structured edit-context for `symbol`'s module: anchor span, RANKED top-level siblings
+ *  (Function/Class) capped lean, the single closest exemplar (for its FULL body when the
+ *  anchor itself is a module), registration globals, covering tests, and the insertion line.
+ *  Pure — no fs. The server reads the module file once to flesh out the snippet + bodies. */
+export function contextPlan(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  const moduleLabel = graph.byId.get(modId)?.label || String(modId || "").replace(/^mod:/, "");
+  const defEdges = edgesOfKind(graph, "defines").filter((e) => e.subject === modId);
+  // #3: index fn→fn in-repo callees once, so siblings/anchor carry their callee set for
+  // structural ranking and the sizeBundle cross-module-call check.
+  const calleeMap = new Map();
+  for (const e of edgesOfKind(graph, "callsSymbol")) {
+    if (!calleeMap.has(e.subject)) calleeMap.set(e.subject, new Set());
+    calleeMap.get(e.subject).add(e.object);
+  }
+  let siblings = [];
+  const globals = [];
+  let insertion = 0;
+  for (const e of defEdges) {
+    const mem = graph.byId.get(e.object);
+    if (!mem) continue;
+    const cls = mem.class || "";
+    const site = siteOf(mem);
+    if (cls === "GlobalVariable") {
+      globals.push({ label: mem.label, value: (mem.attributes || []).find((a) => a.key === "value")?.value || "", site });
+      if (site) insertion = Math.max(insertion, site.end);
+    } else if (cls === "Function" || cls === "Class") {
+      // B007 gap (c): carry each sibling's `raises` + one-line doc so a validator-style
+      // task sees the error-contract without reading the body. #3 adds params/returns/callees
+      // for structural-similarity ranking.
+      siblings.push({
+        id: mem.id, label: mem.label, class: cls, site, decorators: decoratorOf(mem),
+        raises: attrVal(mem, "raises"), doc: attrVal(mem, "doc"),
+        params: attrVal(mem, "params"), returns: attrVal(mem, "returns"),
+        callees: calleeMap.get(mem.id) || new Set(),
+      });
+      if (site) insertion = Math.max(insertion, site.end);
+    }
+  }
+  const anchorSite = siteOf(ind);
+  const anchor = anchorSite && (ind.class || "") !== "Module"
+    ? {
+        id: ind.id, label: ind.label, class: ind.class || "", site: anchorSite, decorators: decoratorOf(ind),
+        raises: attrVal(ind, "raises"), params: attrVal(ind, "params"), returns: attrVal(ind, "returns"),
+        callees: calleeMap.get(ind.id) || new Set(),
+      }
+    : null;
+  const totalSiblings = siblings.length;
+  // #3: the structural target the exemplar should resemble — the anchor's own shape when
+  // there is one, else the dominant pattern across siblings (module anchor case).
+  const structuralTarget = anchor ? profileOf(anchor) : dominantProfile(siblings);
+  siblings = rankSiblings(siblings, anchor || { label: ind.label }, structuralTarget);
+  // Lever 2: when the anchor is a module (no anchor body shown), surface the single
+  // closest sibling's FULL body as the copy-this exemplar; signatures alone made the
+  // agent fall back to Read (B006). With a function/class anchor its own body suffices.
+  const exemplar = !anchor ? siblings.find((s) => s.site && s.label !== ind.label) || null : null;
+  const tests = [...new Set(edgesOfKind(graph, "tests").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))].slice(0, CONTEXT_TESTS_CAP);
+  const cochange = cochangeNeighbours(graph, modId).slice(0, COCHANGE_MID_CAP);
+  const exports = edgesOfKind(graph, "reexports").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object).slice(0, 20);
+  // B007 gap (b): the LITERAL __all__ membership (even unresolved) — the public surface a
+  // new sibling must join to be importable.
+  const allExports = attrVal(graph.byId.get(modId), "all");
+  // B007 gap (a): class-internal members. When the anchor IS a class (or a method of one),
+  // the edit often lives inside that class (e.g. add Truncator.lines), so list its
+  // members with signatures so the agent need not read/grep the class body.
+  const contains = edgesOfKind(graph, "contains");
+  let classOwnerId = null;
+  if ((ind.class || "") === "Class") classOwnerId = ind.id;
+  else if ((ind.class || "") === "Method") classOwnerId = contains.find((e) => e.object === ind.id)?.subject || null;
+  let classMembers = null;
+  if (classOwnerId) {
+    const owner = graph.byId.get(classOwnerId);
+    const members = contains.filter((e) => e.subject === classOwnerId).map((e) => {
+      const m = graph.byId.get(e.object);
+      return {
+        label: e.objectLabel || m?.label || e.object,
+        class: m?.class || "",
+        site: m ? siteOf(m) : null,
+        decorators: m ? decoratorOf(m) : "",
+        params: m ? attrVal(m, "params") : "",
+        returns: m ? attrVal(m, "returns") : "",
+        raises: m ? attrVal(m, "raises") : "",
+      };
+    }).slice(0, CLASS_MEMBER_CAP);
+    classMembers = { className: owner?.label || String(classOwnerId).replace(/^fn:.*#/, ""), members, total: contains.filter((e) => e.subject === classOwnerId).length };
+  }
+  // #2: contiguous insertion region — from the LAST top-level definition (sibling/global,
+  // or the exemplar, which is a sibling) through end-of-module. We give the start line here;
+  // the server extends `end` to the real end-of-file (capped) using the lines it reads.
+  let lastTop = null;
+  for (const s of [...siblings, ...globals]) {
+    if (s.site && (!lastTop || s.site.start > lastTop.start)) lastTop = s.site;
+  }
+  const insertionRegion = lastTop ? { start: lastTop.start, end: lastTop.end } : null;
+  // #6: the focal symbol (anchor when present, else the module's exemplar) drives both the
+  // call hint and the LARGE-tier inlined-callee bodies.
+  const focal = anchor || exemplar;
+  const focalInd = focal?.id ? graph.byId.get(focal.id) : null;
+  const callHintStr = focalInd ? callHint(graph, focalInd) : "";
+  let calleeBodies = [];
+  if (focal?.callees) {
+    for (const cid of focal.callees) {
+      const c = graph.byId.get(cid);
+      const cs = c ? siteOf(c) : null;
+      if (cs) calleeBodies.push({ label: c.label, site: cs });
+      if (calleeBodies.length >= INLINE_CALLEE_CAP) break;
+    }
+  }
+  return {
+    modId, moduleLabel, anchor, siblings, totalSiblings, exemplar, globals, tests, cochange,
+    exports, allExports, classMembers, insertion, insertionRegion, calleeBodies, callHint: callHintStr,
+    siblingCap: CONTEXT_SIBLING_CAP,
+  };
+}
+
+// ---- #6 task-size-adaptive bundle (TINY / MID / LARGE) ---------------------------
+
+/** Which bundle sections a tier emits. TINY is genuinely minimal (header + one short
+ *  exemplar body + registration + insertion region + __all__); MID is the full bundle;
+ *  LARGE adds inlined depth-1 callee bodies. FULL forces everything on. Pure. */
+export function bundleMask(tier) {
+  const all = {
+    anchor: true, exemplar: true, registration: true, insertionRegion: true, allExports: true,
+    classMembers: true, siblings: true, reexports: true, tests: true, cochange: true, inlinedCallees: false,
+  };
+  if (tier === "TINY") return { ...all, classMembers: false, siblings: false, reexports: false, tests: false, cochange: false };
+  if (tier === "LARGE" || tier === "FULL") return { ...all, inlinedCallees: true };
+  return all; // MID
+}
+
+/** B2: a TRIMMED mask for SECONDARY (related-but-not-primary) digest modules — keep the cheap,
+ *  cache-stable signal (registration globals, ranked sibling SIGNATURES, the insertion region,
+ *  __all__) but drop the expensive bodies (anchor/exemplar/inlined callees) and the variable
+ *  tails (tests/cochange/re-exports/class members). Pure. */
+export function trimBundleMask(mask) {
+  return {
+    ...mask,
+    anchor: false, exemplar: false, inlinedCallees: false,
+    classMembers: false, reexports: false, tests: false, cochange: false,
+    registration: true, siblings: true, insertionRegion: true, allExports: true,
+  };
+}
+
+/** Classify a context plan by task size and return {tier, mask, topup}. B1/B6: lean by
+ *  default — START at TINY and escalate ("top-up") one tier ONLY when the lean bundle would
+ *  omit something the edit demonstrably needs (no exemplar body, a class/method edit, or a
+ *  large/complex target → MID; a cross-module call or a big-class method → LARGE). `topup`
+ *  records whether auto-sizing escalated above TINY (surfaced in the digest header). Pure. */
+export function sizeBundle(plan, graph, { untuned = false } = {}) {
+  const focal = plan.anchor || plan.exemplar;
+  let tier = "TINY";
+  // (a) no exemplar/anchor body to copy → the agent needs the sibling list (MID).
+  const hasExemplarBody = Boolean((plan.anchor && plan.anchor.site) || (plan.exemplar && plan.exemplar.site));
+  if (!hasExemplarBody) tier = "MID";
+  // (b) the edit lives INSIDE a class (class/method anchor with members) → show members (MID).
+  if (plan.classMembers && plan.classMembers.members && plan.classMembers.members.length) tier = "MID";
+  if (focal) {
+    // (c) a large/complex target (long body, many params, or it raises) → MID.
+    const loc = focal.site ? focal.site.end - focal.site.start + 1 : Infinity;
+    const arity = countParams(focal.params);
+    // (c) a long/complex focal escalates TINY→MID. TUNING #1 (B011) gated this on an explicit
+    // symbol anchor (so a long-exemplar MODULE digest stayed TINY); BENCHMARK_011 proved that
+    // trim REGRESSED every model (the trimmed sibling/test tail was load-bearing scaffolding), so
+    // B012 REVERTS it — escalation fires on any long focal, == the B010 digest. The `untuned`
+    // param is now a no-op for sizing (kept so the seonix-b010 control arm's flag still resolves).
+    if (loc > TINY_MAX_LOC || arity > TINY_MAX_ARITY || Boolean(focal.raises)) tier = "MID";
+    // (d) LARGE — only for an EXPLICIT symbol focus (plan.anchor), where inlining the
+    // depth-1 callee bodies / the class shape is worth the tokens: a cross-module call from
+    // the anchor, OR an anchor that is a method of a big class. When the focal is merely a
+    // module-EXEMPLAR (the digest/module-anchor case), a cross-module call does NOT force
+    // LARGE — the exemplar body already shows the call, and MID's signatures suffice; this
+    // keeps the common "register a filter" module bundle lean.
+    let crossModule = false;
+    if (plan.anchor) {
+      for (const cid of focal.callees || []) {
+        const c = graph.byId.get(cid);
+        const cs = c ? siteOf(c) : null;
+        if (cs && cs.path !== plan.moduleLabel) { crossModule = true; break; }
+      }
+    }
+    const bigClassMethod = (plan.anchor?.class || "") === "Method" &&
+      Number(plan.classMembers?.total || plan.classMembers?.members?.length || 0) >= LARGE_CLASS_MEMBERS;
+    if (crossModule || bigClassMethod) tier = "LARGE";
+  } else {
+    tier = "MID"; // no focal symbol at all → not a tiny add; keep the fuller bundle.
+  }
+  return { tier, mask: bundleMask(tier), topup: tier !== "TINY" };
+}
+
+/** B2: order SECONDARY digest modules by relevance to the PRIMARY (first) module — import
+ *  adjacency (either direction, incl. coarse calls) outranks change-coupling weight; ties keep
+ *  the caller's input order (stable, deterministic). Returns the candidate labels reordered.
+ *  Pure — no fs. Falls back to the input order when the primary can't be mapped to a module. */
+export function rankModulesByProximity(graph, primaryLabel, candidateLabels) {
+  const moduleIdFor = (label) => {
+    const { match } = resolveSymbol(graph, label);
+    return match && (match.class || "") === "Module" ? match.id : null;
+  };
+  const pid = moduleIdFor(primaryLabel);
+  if (!pid) return [...candidateLabels];
+  const adjacent = new Set();
+  for (const kind of ["imports", "calls"]) {
+    for (const e of edgesOfKind(graph, kind)) {
+      if (e.subject === pid) adjacent.add(e.object);
+      if (e.object === pid) adjacent.add(e.subject);
+    }
+  }
+  const coWeight = new Map();
+  for (const e of edgesOfKind(graph, "cochange")) {
+    if (e.subject === pid) coWeight.set(e.object, (coWeight.get(e.object) || 0) + (e.weight || 0));
+    else if (e.object === pid) coWeight.set(e.subject, (coWeight.get(e.subject) || 0) + (e.weight || 0));
+  }
+  return candidateLabels
+    .map((label, i) => {
+      const id = moduleIdFor(label);
+      const score = id ? (adjacent.has(id) ? 10 : 0) + (coWeight.get(id) || 0) : 0;
+      return { label, score, i };
+    })
+    .sort((a, b) => b.score - a.score || a.i - b.i)
+    .map((s) => s.label);
+}
+
+// ---- #7 seonix_context_more: only the sections a TINY/MID bundle omits ------------
+
+/** Render ONLY the bundle sections a lean bundle omits (sibling list / class members /
+ *  re-exports / __all__ / tests / cochange) for a symbol's module. Pure (no fs). */
+export function renderContextMore(plan) {
+  const out = [`Additional context for ${plan.moduleLabel} (sections omitted from the lean bundle):`];
+  if (plan.classMembers && plan.classMembers.members.length) {
+    out.push(`\n## members of ${plan.classMembers.className}:`);
+    for (const m of plan.classMembers.members) {
+      const short = String(m.label).split(".").pop();
+      const sig = m.params != null && m.params !== "" ? `(${m.params})${m.returns ? ` -> ${m.returns}` : ""}` : "";
+      const dec = m.decorators ? `@${m.decorators} ` : "";
+      const r = m.raises ? `  raises=${m.raises}` : "";
+      out.push(`  ${m.class} ${short}${m.site ? ` :${m.site.start}` : ""}  ${dec}${short}${sig}${r}`);
+    }
+  }
+  if (plan.siblings.length) {
+    out.push(`\n## sibling symbols (most relevant first; ${plan.siblings.length} total):`);
+    for (const s of plan.siblings.slice(0, plan.siblingCap)) {
+      const dec = s.decorators ? `@${s.decorators} ` : "";
+      const r = s.raises ? `  raises=${s.raises}` : "";
+      out.push(`  ${s.class} ${s.label}${s.site ? ` :${s.site.start}` : ""}  ${dec}${r}`);
+    }
+    if (plan.siblings.length > plan.siblingCap) out.push(`  …+${plan.siblings.length - plan.siblingCap} more`);
+  }
+  if (plan.allExports) out.push(`\n## module __all__: ${plan.allExports}`);
+  if (plan.exports && plan.exports.length) out.push(`\n## re-exported symbols: ${plan.exports.join(", ")}`);
+  if (plan.tests.length) out.push(`\n## covering tests: ${plan.tests.join(", ")}`);
+  if (plan.cochange && plan.cochange.length) {
+    out.push(`\n## usually changed together: ${plan.cochange.map((c) => `${c.label} (×${c.weight})`).join(", ")}`);
+  }
+  if (out.length === 1) out.push("(no omitted sections — the lean bundle already contained everything for this symbol.)");
+  return out.join("\n");
+}
+
+// ---- #7 cold-tool catalog (written to <repo>/.seonix/TOOLS.md by the index step) --
+
+/** Markdown catalog of the COLD tools (everything except the two hot MCP tools): each
+ *  with a one-line purpose and the exact Bash invocation via the CLI `cli <tool>` route.
+ *  Pure — `cliPath` is the absolute path to bin/cli.mjs the caller wants embedded. */
+export function renderToolsCatalog(cliPath) {
+  const cold = [
+    ["seonix_describe", "Locate one symbol and list its typed edges (both directions) with provenance.", { symbol: "django/utils/text.py" }],
+    ["seonix_signature", "One symbol's API surface (params, returns, raises/catches, flags, decorators, doc) without the body.", { symbol: "Truncator.chars" }],
+    ["seonix_impact", "Transitive reverse closure over imports/calls — what breaks if a module changes, by depth, with tests.", { module: "django/utils/text.py" }],
+    ["seonix_search", "Free-text/ranked lookup over the code-map to find the right module or symbol.", { query: "template filters", kind: "function" }],
+    ["seonix_members", "A class's methods + attributes (file:line, decorators) in one slice.", { class: "Truncator" }],
+    ["seonix_subclasses", "A class's base classes plus the transitive set of classes that extend it.", { class: "Field" }],
+    ["seonix_architecture", "Package/module map + the most-imported hub modules (optionally scoped to a package).", { package: "django/template" }],
+    ["seonix_exports", "A module's public __all__ surface, each name resolved to the module that defines it.", { module: "django/db/models/__init__.py" }],
+    ["seonix_tests_for", "The test modules covering a symbol or module, from the typed test edges.", { symbol: "django/utils/text.py" }],
+    ["seonix_untested", "Source modules with no covering test module — a coverage-gap view (no arguments).", {}],
+    ["seonix_history", "Recent commits that touched a symbol's module (newest first).", { symbol: "django/utils/text.py" }],
+    ["seonix_file_history", "Commits that touched a symbol's module, each with author / date / subject.", { symbol: "django/utils/text.py" }],
+    ["seonix_method_history", "Commits that touched a specific method symbol (fine-grained), with author / date / subject.", { symbol: "Truncator.chars" }],
+    ["seonix_class_history", "Commits that touched a specific class symbol (fine-grained), with author / date / subject.", { symbol: "Truncator" }],
+    ["seonix_callers", "Modules that call into a symbol's module (one hop).", { symbol: "django/utils/text.py" }],
+    ["seonix_callees", "Modules a symbol's module calls into (one hop).", { symbol: "django/utils/text.py" }],
+    ["seonix_calls", "The in-repo symbols a function calls (fn→fn), each with file:line.", { symbol: "slugify" }],
+    ["seonix_cochanges", "Modules that historically change in the same commit as a symbol's module (git co-change).", { symbol: "django/utils/text.py" }],
+    ["seonix_context_more", "The bundle sections a lean seonix_context omitted (siblings / tests / cochange / class members / re-exports).", { symbol: "django/utils/text.py" }],
+  ];
+  const lines = [
+    "# seonix cold-tool catalog",
+    "",
+    "The two hot tools — `seonix_context` (start here to add/modify code; supports `depth: min|auto|full`) and `seonix_snippet` (exact source of one symbol) — are exposed as MCP tools.",
+    "",
+    "The cold tools below are not registered as MCP tools (to keep the surface small); invoke each via the CLI:",
+    "",
+  ];
+  for (const [name, purpose, args] of cold) {
+    lines.push(`## ${name}`);
+    lines.push(purpose);
+    lines.push("```bash");
+    lines.push(`node ${cliPath} cli ${name} '${JSON.stringify(args)}'`);
+    lines.push("```");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// ---- change-coupling (git co-change) — "what usually changes together" ----------
+
+/** [{label, weight}] modules co-changed with modId, sorted by count desc. Pure. */
+function cochangeNeighbours(graph, modId) {
+  const hits = [];
+  for (const e of edgesOfKind(graph, "cochange")) {
+    if (e.subject === modId) hits.push({ label: e.objectLabel || e.object, weight: e.weight || 0 });
+    else if (e.object === modId) hits.push({ label: e.subjectLabel || e.subject, weight: e.weight || 0 });
+  }
+  return hits.sort((a, b) => b.weight - a.weight);
+}
+
+const COCHANGE_CAP = 20;
+
+/** Modules that historically change in the same commit as the target's module. */
+export function renderCochanges(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const hits = cochangeNeighbours(graph, modId);
+  if (!hits.length) return `${modLabel}: no change-coupling recorded (rarely co-committed, or outside the git-log window).`;
+  const list = hits.slice(0, COCHANGE_CAP).map((h) => `${h.label} (×${h.weight})`);
+  return `${modLabel} — usually changes together with ${hits.length} module(s) (edit these too):\n  ${list.join("\n  ")}` +
+    (hits.length > COCHANGE_CAP ? `\n  …+${hits.length - COCHANGE_CAP} more` : "");
+}
+
+// ---- re-exports / public API (__all__) ------------------------------------------
+
+const EXPORTS_CAP = 40;
+
+/** A module's public export surface: each __all__ name → the module that actually
+ *  defines it (so re-export hubs like __init__ are explicit). */
+export function renderExports(graph, ind) {
+  const modId = moduleIdOf(graph, ind);
+  if (!modId) return `cannot map ${ind.label} to a module.`;
+  const modLabel = graph.byId.get(modId)?.label || modId;
+  const edges = edgesOfKind(graph, "reexports").filter((e) => e.subject === modId);
+  if (!edges.length) return `${modLabel}: no public exports recorded (no literal __all__, or none resolved).`;
+  const list = edges.slice(0, EXPORTS_CAP).map((e) => {
+    const origin = graph.byId.get(e.object);
+    const where = origin ? siteOf(origin) : null;
+    const from = where ? ` ← ${where.path}` : "";
+    return `${e.objectLabel || e.object}${from}`;
+  });
+  return `${modLabel} — public API (${edges.length} export(s) via __all__):\n  ${list.join("\n  ")}` +
+    (edges.length > EXPORTS_CAP ? `\n  …+${edges.length - EXPORTS_CAP} more` : "");
+}