@polycode-projects/seonix 0.1.0 → 0.2.1

package/src/codegraph.mjs

@@ -1,3 +1,5 @@
+import { lookupByProseTokens } from "./prose.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
 // src/extract.mjs):
@@ -47,6 +49,11 @@ export function parseEntities(payload) {
     relations,
     truncated,
     generatedAt: payload?.generated_at || null,
+    // Second pass (PLAN_PROSE_INDEX.md): word -> [individual ids], passed through
+    // byte-identical from the payload so ask.mjs's resolveObject can consult it as a
+    // fallback tier without reaching back into the raw payload itself. {} when the
+    // build had prose disabled or the payload predates this field.
+    proseIndex: payload?.proseIndex || {},
   };
 }
 
@@ -265,16 +272,41 @@ function truncationNote(graph) {
  * 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).
+ *
+ * Module-coarse "calls" (`mgx:callsCoarse`, extract.mjs) is deliberately
+ * conservative — it only fires when the callee's module is ALREADY in the
+ * caller's import list ("coarse, import-backed calls", extract.mjs's own
+ * comment), so by construction every "calls" edge is a strict subset of an
+ * "imports" edge between the same pair — it never independently extends this
+ * closure's reach beyond what "imports" alone already gives it. `callsSymbol`
+ * (fn/method-granular, no import-backing requirement — same-module calls,
+ * ambiguous-name calls the coarse pass drops) is the richer signal; this
+ * closure also folds it in, coarsened to module level on read (never stored),
+ * mirroring the technique `adjacencyForKinds`/`BEAM_EDGE_GROUPS` already use
+ * for the same reason.
  */
 export function impactClosure(graph, ind, { maxDepth = 8 } = {}) {
   const dependents = new Map();
   const coveredBy = new Map(); // moduleId → [test labels]
+  const addDependent = (objectId, subjectId, subjectLabel, via) => {
+    // Self-loop guard: callsSymbol coarsens to module level, so two symbols in
+    // the SAME module calling each other must not produce a module pointing at
+    // itself (imports/calls edges are already module-to-module and can't self-loop).
+    if (!objectId || !subjectId || objectId === subjectId) return;
+    if (!dependents.has(objectId)) dependents.set(objectId, []);
+    dependents.get(objectId).push({ id: subjectId, label: subjectLabel, via });
+  };
   for (const g of graph.relations) {
     const kind = relationKind(g);
     if (kind === "imports" || kind === "calls") {
+      for (const e of g.edges) addDependent(e.object, e.subject, e.subjectLabel || e.subject, g.predicate);
+    } else if (kind === "callsSymbol") {
       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 });
+        const subjModId = moduleIdOfId(graph, e.subject);
+        const objModId = moduleIdOfId(graph, e.object);
+        if (!subjModId || !objModId) continue;
+        const subjLabel = graph.byId.get(subjModId)?.label || subjModId;
+        addDependent(objModId, subjModId, subjLabel, g.predicate);
       }
     } else if (kind === "tests") {
       for (const e of g.edges) {
@@ -313,7 +345,7 @@ 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):`];
+  const lines = [`Impact of changing ${ind.label} (reverse closure over imports/calls edges, module- and function-level):`];
   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).");
   }
@@ -338,7 +370,7 @@ export function renderImpact(graph, ind, { maxDepth = 8 } = {}) {
   });
   const truncatedStructural = graph.truncated.filter((t) => {
     const kind = relationKind({ predicate: t.predicate });
-    return kind === "imports" || kind === "calls" || kind === "tests";
+    return kind === "imports" || kind === "calls" || kind === "callsSymbol" || kind === "tests";
   });
   if (truncatedStructural.length) {
     lines.push(
@@ -376,7 +408,7 @@ function definesIndex(graph) {
  */
 const SEARCH_LIMIT = 10;
 const SEARCH_SYMBOLS_SHOWN = 8;
-// B012 locate scoring — IDF-weighted, component-aware. The rig queries with the WHOLE problem
+// 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
@@ -389,6 +421,85 @@ const SYM_MATCH_CAP = 4;   // only the top-K highest-IDF symbol-COMPONENT hits c
 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);
+// B016 R1a (opt-in via demoteNonProd): non-production paths — examples, fixtures, sample/demo
+// apps, and test-* harness packages — share path/symbol vocabulary with the production module
+// and shadow it in locate (B015: js-express injected examples/route-middleware/index.js at
+// rank 1; java-gson's TOP2 slot 2 was a test-shrinker fixture). DEMOTED, not excluded: none of
+// the B015 truths live under these paths (checked corpus/instances-*/…/spec.json 2026-07-02),
+// but a future task whose truth IS a test/example file must stay reachable.
+const NONPROD_DEMOTE = 0.15;
+const isNonProdLabel = (s) => /(^|\/)(examples?|fixtures?|samples?|demos?|benchmarks?|test-[^/]+)(\/|$)/.test(s);
+// B016 E1a (opt-in via callAdjacency): resolved-call adjacency, same bounded-nudge shape as the
+// import-proximity bonus. Python graphs carry call edges (django: 993 calls / 23,596 callsSymbol);
+// the syntax-level C#/Java extractors emit ~none today, so this flag is Python-value only.
+const CALL_PROX_FRAC = 0.2;
+const CALL_PROX_CAP_FRAC = 0.35;
+// B016 E1b (opt-in via implOfInterface): boost a module that implements an interface DEFINED
+// in a strongly-matched module (C# IBasketService→BasketService, the rank-4 case). PLAN_B016
+// §6.1 specified an `isAbstract` guard, but that field is never populated by any extractor —
+// verified empirically 2026-07-02 against django/eshoponweb/java-gson .seonix/graph.json: 0
+// individuals carry `isAbstract` in all three. The only real distinguishing signal in the data
+// is C#'s naming convention (interfaces prefixed `I<Uppercase>`, e.g. IBasketService) — and C#'s
+// `inherits` edges point at an UNRESOLVED `ext:<Name>` id rather than the interface's own
+// individual, so the object must be resolved by an exact label match against internal
+// Class-labeled individuals. SCOPED to `.cs` implementer modules only: without that scope, 11 of
+// django's 7,014 inherits edges superficially match `I[A-Z]` (IOBase, IExact, IContains, …ordinary
+// Python class names, not interfaces) and would reintroduce the over-injection E1a already showed
+// on class-heavy Python graphs. Java's `inherits` predicate resolves cleanly to real individuals
+// but carries no tag or naming convention distinguishing interface implementation from concrete
+// inheritance (TypeAdapterFactory IS an interface in Gson, no "I" prefix) — a Java-safe guard does
+// not exist without an extractor change (E1c, deferred). E1b is C#-only until then.
+const IMPL_PROX_FRAC = 0.2;
+const IMPL_PROX_CAP_FRAC = 0.35;
+const isCsModuleLabel = (s) => /\.cs$/i.test(s);
+const looksLikeCsInterface = (label) => /^I[A-Z]/.test(String(label || ""));
+
+// PLAN_PROSE_INDEX.md §6 (opt-in via proseBoost, 2026-07-02): a matched module whose lexical
+// score comes only from its path/symbol NAMES misses the case where the query's vocabulary
+// only overlaps a decomposed identifier or a doc-comment elsewhere in that module (e.g. "billing
+// calculation" never appears in `calculateTotalPrice`'s own path, only in its prose tokens).
+// Same bounded-nudge shape/magnitude as the other proximity families — a nudge onto modules that
+// ALREADY matched lexically (never a new zero-match candidate), never a replacement for the
+// lexical score. NOT wired into any bench arm and NOT a shipped default — an available lever
+// only, exactly like §5.15 beam search before it, pending its own gate/benchmark evidence.
+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 §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
+// Harpy Speech Understanding System" (Carnegie-Mellon, the paper that coined "beam search" — no
+// University of Essex 1980s/90s beam-search paper exists; searched 2026-07-02, none found, this
+// is the honest substitute). One hop of expansion = a PLY; the surviving candidate set at a ply =
+// the BEAM; beamWidth (β) caps how many survive; discarding non-survivors = PRUNING.
+//
+// Harpy's own beamwidth was a MARGIN/THRESHOLD relative to the ply's best score ("candidates
+// that fall below a threshold of acceptability are pruned"), not a fixed count — this is a
+// threshold+cap HYBRID (keep everyone within BEAM_MARGIN_FRAC of the ply's best, THEN cap at β),
+// not naive top-k. A fixed-count beam would prematurely discard exactly the kind of weak-then-
+// strong candidate E1b's own motivating case demonstrated: BasketService.cs sat at lexical rank 4
+// and was only promoted by considering impl-of-interface structure beyond the first pass — a
+// hard top-k cut at ply 0 could drop such a candidate before any later ply had a chance to
+// recover it (Russell & Norvig's "local beam search... quickly becomes concentrated in a small
+// region" failure mode, which Wikipedia's article cites for exactly this risk).
+//
+// Successors are generated PER EDGE KIND separately (not pooled then pruned once), so a dense
+// edge type (imports) cannot crowd out a sparse-but-discriminative one (inherits) — each kind's
+// survivors are computed independently, then MERGED (Harpy's own "candidate merging": two states
+// reaching the same successor collapse to one path, keeping the better score). A short overflow
+// list of near-miss pruned candidates is kept as a safety valve: if a ply's beam runs dry, the
+// overflow is reconsidered rather than the walk simply stopping.
+//
+// SAFETY SCOPE: like every proximity family above, this only re-ranks modules that ALREADY
+// matched lexically (present in `scored`) — it never introduces a zero-match candidate, so it
+// cannot regress precision/over-injection the way an unbounded multi-hop walk could.
+const BEAM_MARGIN_FRAC = 0.5;    // keep ply candidates scoring >= (ply-best * this), before the cap
+const BEAM_PROX_FRAC = 0.2;      // bounded nudge — same shape/magnitude as the other proximity families
+const BEAM_PROX_CAP_FRAC = 0.35;
+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"]];
 
 /** 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>". */
@@ -401,12 +512,100 @@ function identComponents(name) {
   return new Set(String(name).replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
 }
 
+/** For one edge-kind group, the depth-1 successor of `fromId` reachable via any edge in `kinds`,
+ *  as a Map<moduleId, neighbourModuleId> adjacency (undirected — a module's neighbours via that
+ *  kind, in either edge direction). Endpoints are mapped to their containing module first (call
+ *  edges live at function granularity), matching the existing E1a call-adjacency convention. */
+function adjacencyForKinds(graph, kinds) {
+  const adj = new Map();
+  const link = (a, b) => {
+    if (!a || !b || a === b) return;
+    if (!adj.has(a)) adj.set(a, new Set());
+    if (!adj.has(b)) adj.set(b, new Set());
+    adj.get(a).add(b);
+    adj.get(b).add(a);
+  };
+  for (const kind of kinds) {
+    for (const e of edgesOfKind(graph, kind)) {
+      link(moduleIdOfId(graph, e.subject), moduleIdOfId(graph, e.object));
+    }
+  }
+  return adj;
+}
+
+/** Beam-search-style multi-PLY expansion (PLAN_SEON_TUNING.md §5.15; see the BEAM_* constants'
+ *  comment above for the full design rationale). Mutates `s.score` in place on `scored` entries
+ *  it boosts — same bounded-nudge shape as the single-hop proximity families, just reachable over
+ *  more than one hop when a ply's beam survives that far. Pure otherwise (no fs/network). */
+function beamExpand(graph, scored, beamWidth) {
+  if (scored.length < 2) return;
+  const byId = new Map(scored.map((s) => [s.ind.id, s]));
+  const baseScore = new Map(scored.map((s) => [s.ind.id, s.score]));
+
+  // Margin+cap prune a candidate-score Map down to this ply's beam, returning [survivors, overflow].
+  const pruneToBeam = (candidates) => {
+    if (!candidates.size) return [[], []];
+    let best = 0;
+    for (const v of candidates.values()) best = Math.max(best, v);
+    const ranked = [...candidates.entries()].sort((a, b) => b[1] - a[1]);
+    const survivors = [];
+    const overflow = [];
+    for (const [id, score] of ranked) {
+      if (score >= best * BEAM_MARGIN_FRAC && survivors.length < beamWidth) survivors.push([id, score]);
+      else if (overflow.length < BEAM_OVERFLOW_CAP) overflow.push([id, score]);
+    }
+    return [survivors, overflow];
+  };
+
+  // Ply 0 beam = the current top-scoring already-matched modules (margin+cap over the whole set).
+  let [beam, overflow] = pruneToBeam(new Map(scored.map((s) => [s.ind.id, s.score])));
+  const boosted = new Set(beam.map(([id]) => id));
+
+  for (let ply = 0; ply < BEAM_PLIES && beam.length; ply++) {
+    // Per-edge-kind successor generation, scored, pruned INDEPENDENTLY per kind (so a dense kind
+    // like imports can't crowd out a sparse-but-discriminative one like inherits), then merged.
+    const merged = new Map(); // successorId -> best propagated score across all kinds this ply
+    const plyOverflow = [];
+    for (const kinds of BEAM_EDGE_GROUPS) {
+      const adj = adjacencyForKinds(graph, kinds);
+      const candidates = new Map();
+      for (const [parentId, parentScore] of beam) {
+        for (const neighbourId of adj.get(parentId) || []) {
+          if (!baseScore.has(neighbourId)) continue; // only re-rank already-matched modules
+          candidates.set(neighbourId, Math.max(candidates.get(neighbourId) || 0, parentScore));
+        }
+      }
+      const [survivors, kindOverflow] = pruneToBeam(candidates);
+      for (const [id, score] of survivors) merged.set(id, Math.max(merged.get(id) || 0, score));
+      plyOverflow.push(...kindOverflow);
+    }
+    overflow.push(...plyOverflow);
+    // Apply the bounded nudge once per module (first ply it's reached), same shape as the other
+    // proximity families — a nudge, never a replacement.
+    for (const [id, propagated] of merged) {
+      if (boosted.has(id)) continue;
+      const s = byId.get(id);
+      if (!s) continue;
+      s.score += Math.min(propagated * BEAM_PROX_FRAC, s.score * BEAM_PROX_CAP_FRAC);
+      boosted.add(id);
+    }
+    beam = [...merged.entries()];
+    // Safety valve: if this ply's beam ran dry, reconsider the near-miss overflow instead of
+    // just stopping — cheap insurance against a total pruning failure.
+    if (!beam.length && overflow.length) {
+      beam = overflow.splice(0, BEAM_OVERFLOW_CAP).filter(([id]) => !boosted.has(id));
+    }
+  }
+}
+
 /** 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) {
+function scoreModules(graph, tokens, opts = {}) {
+  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, proseBoost = false } = 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.
   const modules = [];
@@ -449,7 +648,8 @@ function scoreModules(graph, tokens) {
     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
+    if (demoteNonProd && (isTestLabel(m.labelLc) || isNonProdLabel(m.labelLc))) score *= NONPROD_DEMOTE; // B016 R1a
+    else if (isTestLabel(m.labelLc)) 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 });
@@ -473,6 +673,86 @@ function scoreModules(graph, tokens) {
       s.score += Math.min(bestNeighbor * PROX_FRAC, s.score * PROX_CAP_FRAC);
     }
   }
+  // B016 E1a (opt-in): resolved-call adjacency — a matched module CALLED BY (or calling) a
+  // stronger-matching module rises with it (initials-filter: defaultfilters.py calls into
+  // utils/text.py, whose lexical rank was 8). Call edges live at function level, so endpoints
+  // map to their containing modules first. Same bounded-nudge formula as import-proximity;
+  // only re-ranks modules that already matched.
+  if (callAdjacency && scored.length > 1) {
+    const baseById = new Map(scored.map((s) => [s.ind.id, s.score]));
+    const adj = new Map();
+    for (const kind of ["calls", "callsSymbol"]) {
+      for (const e of edgesOfKind(graph, kind)) {
+        const sm = moduleIdOfId(graph, e.subject);
+        const om = moduleIdOfId(graph, e.object);
+        if (!sm || !om || sm === om) continue;
+        if (!baseById.has(sm) && !baseById.has(om)) continue;
+        if (!adj.has(sm)) adj.set(sm, new Set());
+        if (!adj.has(om)) adj.set(om, new Set());
+        adj.get(sm).add(om);
+        adj.get(om).add(sm);
+      }
+    }
+    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 * CALL_PROX_FRAC, s.score * CALL_PROX_CAP_FRAC);
+    }
+  }
+  // B016 E1b (opt-in): impl-of-interface — a C# module implementing an interface DEFINED in a
+  // stronger-matching module rises with it (eshoponweb: IBasketService.cs rank 1, BasketService.cs
+  // rank 4). `inherits` edges point the OBJECT at an unresolved `ext:<Name>` id for C#, so resolve
+  // by exact label match against internal Class individuals. Only re-ranks modules that already
+  // matched, and only when both the implementer module is `.cs` and the base name looks like a C#
+  // interface (see the const block above for why — isAbstract does not exist in the data).
+  if (implOfInterface && scored.length > 1) {
+    const baseById = new Map(scored.map((s) => [s.ind.id, s.score]));
+    const classByLabel = new Map();
+    for (const ind of graph.individuals) {
+      if ((ind.class || "") === "Class" && ind.label) classByLabel.set(String(ind.label), ind);
+    }
+    for (const s of scored) {
+      if (!isCsModuleLabel(s.ind.label)) continue;
+      let bestNeighbor = 0;
+      for (const e of edgesOfKind(graph, "inherits")) {
+        const subjModId = moduleIdOfId(graph, e.subject);
+        if (subjModId !== s.ind.id) continue;
+        if (!looksLikeCsInterface(e.objectLabel)) continue;
+        let ifaceModId = moduleIdOfId(graph, e.object); // resolves real (non-ext:) targets
+        if (!ifaceModId) {
+          const ifaceInd = classByLabel.get(String(e.objectLabel || ""));
+          if (ifaceInd) ifaceModId = moduleIdOf(graph, ifaceInd);
+        }
+        if (ifaceModId) bestNeighbor = Math.max(bestNeighbor, baseById.get(ifaceModId) || 0);
+      }
+      s.score += Math.min(bestNeighbor * IMPL_PROX_FRAC, s.score * IMPL_PROX_CAP_FRAC);
+    }
+  }
+  // PLAN_PROSE_INDEX.md §6 (opt-in): lexical boost from decomposed-identifier/doc-comment
+  // prose tokens — see the PROSE_PROX_* comment above for the full rationale. One
+  // lookupByProseTokens call for the whole query (not per-module), then aggregated into a
+  // per-module signal via moduleIdOfId, same as the call-adjacency/impl-of-interface families.
+  // Unlike the proximity families above, this signal is absolute per-module (prose-token
+  // overlap), not relative to a stronger NEIGHBOUR in `scored` — so it applies even when
+  // only one module matched lexically (no ">1" gate needed).
+  if (proseBoost && scored.length && graph.proseIndex) {
+    const proseHits = lookupByProseTokens(graph.proseIndex, tokens.join(" "), { limit: PROSE_LOOKUP_LIMIT });
+    if (proseHits.length) {
+      const proseByModule = new Map();
+      for (const { id, score } of proseHits) {
+        const modId = moduleIdOfId(graph, id);
+        if (!modId) continue;
+        proseByModule.set(modId, (proseByModule.get(modId) || 0) + score);
+      }
+      for (const s of scored) {
+        const signal = proseByModule.get(s.ind.id) || 0;
+        if (!signal) continue;
+        s.score += Math.min(signal * PROSE_PROX_FRAC, s.score * PROSE_PROX_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.
   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;
@@ -481,11 +761,47 @@ function scoreModules(graph, tokens) {
 /** 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) {
+ *  rank-2 only when it is close. Pure; deterministic.
+ *  NOTE: scoreModules still RANKS (locate always returns modules), but the score-gap top-1
+ *  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);
   if (!tokens.length) return [];
-  return scoreModules(graph, tokens).map((s) => ({ path: String(s.ind.label), score: s.score }));
+  return scoreModules(graph, tokens, opts).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
+// B016's P1 (tuning task + a genuinely held-out task) and P2 (both eshoponweb tasks; clears the
+// ≥50%-vs-otb bar outright on order-service-total). See PLAN_B016.md §6.9. 0.6 is the exact ratio
+// tested throughout — do not drift it from bench/arms.mjs's arm values or scripts/rank-gate.mjs's
+// --gap default; all three should read this constant.
+export const DEFAULT_SCORE_GAP = 0.6;
+
+/** Score-gap-driven module selection: take the top_k ranked hits, then extend the selection to
+ *  include ranks (top_k)..2 whose score sits within `scoreGapK` of rank 1 — the near-tie case
+ *  where a second (or third) module is genuinely as relevant as the top hit, not filler. Never
+ *  resurrects a suppressed (empty) selection: a top_k of 0 stays empty regardless of scoreGapK.
+ *  Pure — the single source of truth for gap-extension, shared by the CLI/MCP product surface
+ *  (cli.mjs's query-based `digest`) and the bench rig (bench/run.mjs's selectModules).
+ *
+ *  DELIBERATELY NEUTRAL BY DEFAULT: `scoreGapK` defaults to `null` (gap-extension OFF, plain
+ *  top-`top_k`) here — the SHIPPED default of `DEFAULT_SCORE_GAP` is a product-surface policy
+ *  decision, applied explicitly by the caller (cli.mjs's digest query-mode), not baked into this
+ *  primitive. A library default of "on" would make every future caller who forgets to pass
+ *  `scoreGapK` silently inherit gap-extension — including future bench arms, breaking the
+ *  paired-arm "byte-identical when off" comparability this repo's whole measurement methodology
+ *  depends on. See test/selectRankedModules.test.mjs's "absent scoreGapK is byte-identical to
+ *  plain top-k" case. */
+export function selectRankedModules(ranked, { top_k = 2, scoreGapK = null } = {}) {
+  if (!ranked.length || top_k <= 0) return [];
+  const picked = ranked.slice(0, top_k).map((r) => r.path);
+  if (scoreGapK && picked.length >= 1 && ranked[0].score > 0) {
+    for (const r of ranked.slice(1, 3)) {
+      if (r.score / ranked[0].score >= scoreGapK && !picked.includes(r.path)) picked.push(r.path);
+    }
+  }
+  return picked;
 }
 
 export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
@@ -521,12 +837,26 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
 //      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) {
+/** All edges of a classified relation kind (imports/calls/defines/tests/touches/inherits/
+ *  cochange/reexports/callsSymbol/touchesSymbol/contains — see relationKind/PROP_KIND above),
+ *  flattened across every raw relation group that classifies to it. Exported for ask.mjs's
+ *  mechanical NL-query engine (PLAN_MECHANICAL_CHAT.md) to orchestrate rather than duplicate. */
+export function edgesOfKind(graph, kind) {
   const out = [];
   for (const g of graph.relations) if (relationKind(g) === kind) out.push(...g.edges);
   return out;
 }
 
+/** moduleIdOf by raw edge-endpoint id: resolves through byId when the individual exists,
+ *  else falls back to parsing an `fn:<path>#name` id directly (callsSymbol objects may name
+ *  symbols with no individual of their own). Null if it cannot be mapped. */
+function moduleIdOfId(graph, id) {
+  const ind = graph.byId?.get?.(id);
+  if (ind) return moduleIdOf(graph, ind);
+  const m = String(id || "").match(/^fn:(.+)#/);
+  return m ? `mod:${m[1]}` : null;
+}
+
 /** 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) {
@@ -870,7 +1200,7 @@ function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, n
 //      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 CLASS_MEMBER_CAP = 16;   // 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.
@@ -988,9 +1318,9 @@ export function contextPlan(graph, ind) {
       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.
+      // 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"),
@@ -1015,15 +1345,15 @@ export function contextPlan(graph, ind) {
   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.
+  // agent fall back to Read. 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
+  // 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),
+  // 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");
@@ -1121,11 +1451,10 @@ export function sizeBundle(plan, graph, { untuned = false } = {}) {
     // (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).
+    // (c) a long/complex focal escalates TINY→MID. Escalation fires on any long focal: gating it on
+    // an explicit symbol anchor (so a long-exemplar MODULE digest stayed TINY) regressed results,
+    // because the trimmed sibling/test tail was load-bearing scaffolding. 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

package/src/cs_treesitter.mjs

@@ -126,8 +126,8 @@ export async function extractFile(absPath, root) {
     imports: [...imports].sort(), defines, calls: collectCalls(tree.rootNode), exports: [...exports].sort() };
 }
 
-export async function ingest(root) {
-  const files = await walk(root, EXTS);
+export async function ingest(root, { ignore = null } = {}) {
+  const files = await walk(root, EXTS, ignore);
   const modules = [];
   const failures = [];
   for (const f of files) {