@polycode-projects/seonix 0.10.7 → 0.10.10

package/bin/cli.mjs

@@ -22,6 +22,10 @@
 //   seonix cli index_repository '{"multi_root":"<abs-dir>"}' → estate discovery: every immediate
 //     child directory carrying a .git (dir or file) is indexed as a repo, merged into
 //     <multi_root>/.seonix/ (discovered/skipped counts logged to stderr)
+//   seonix cli index_repository --multi-root [path]           → same, flag form — no JSON
+//     quoting needed; a bare `--multi-root` (no path) defaults to cwd, e.g. `cd <estate> &&
+//     npx seonix cli index_repository --multi-root`. `--repo-path [path]` and `--out-root
+//     <path>` (always needs a value) are the flag forms of the other two path args.
 //   seonix cli sync '{"multi_root":"<abs-dir>"}' → incrementally re-index the estate: fingerprint
 //     every child repo (git/gitparent/plain), re-extract ONLY the changed ones (per-repo cache in
 //     .seonix/cache/), one union rebuild = exact full-re-index. Unchanged-everything = byte-stable
@@ -54,7 +58,7 @@
 
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, writeFile, readdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { startServer } from "../src/server.mjs";
 import { dispatchTool, buildContextBundle, TOOLS } from "../src/server.mjs";
@@ -80,6 +84,32 @@ function parsePayload(payload) {
   catch { return null; }
 }
 
+const INDEX_FLAG_KEYS = { "--multi-root": "multi_root", "--repo-path": "repo_path", "--out-root": "out_root" };
+
+/** Flag-style alternative to index_repository's JSON payload — `--multi-root [path]` /
+ *  `--repo-path [path]` (also `--flag=path`), so `npx seonix cli index_repository
+ *  --multi-root` works without JSON-quoting a path. A bare `--multi-root`/`--repo-path`
+ *  (no path following, or the payload ends there) defaults to cwd, matching the JSON form's
+ *  own cwd-default convention. `--out-root` always needs an explicit value — there's no
+ *  sensible cwd default for it. Returns an args object shaped like the JSON payload, or
+ *  null if the first token isn't a recognised flag (falls back to JSON parsing). */
+function parseIndexFlags(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    const eq = tok.indexOf("=");
+    const flag = eq === -1 ? tok : tok.slice(0, eq);
+    const key = INDEX_FLAG_KEYS[flag];
+    if (!key) return null;
+    if (eq !== -1) { args[key] = tok.slice(eq + 1); continue; }
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) { args[key] = next; i++; }
+    else if (key === "multi_root" || key === "repo_path") { args[key] = process.cwd(); }
+    else return null;
+  }
+  return Object.keys(args).length ? args : null;
+}
+
 /** Nearest ancestor of `startDir` (itself first) containing a .seonix/ directory, or null. */
 function findIndexRoot(startDir = process.cwd()) {
   let dir = startDir;
@@ -113,6 +143,36 @@ function defaultRepoPath(args, { mustExist = true } = {}) {
   return args;
 }
 
+/** Single-mode index_repository against a directory that (a) isn't itself a git repo and
+ *  (b) has ≥2 immediate child directories that ARE — the exact signature of an estate root
+ *  mistaken for one flat repo (the `multi_root` docs' own warning: "repo_path would index it
+ *  as one flat repo"). Silent consequence: git history extraction fails against the non-repo
+ *  root (0 commits, no error the caller necessarily notices among the rest of the index
+ *  output), module ids aren't per-repo-prefixed, and every sub-repo gets flattened together.
+ *  Best-effort (readdir failure just means no warning, never a crash) — this only ADDS a
+ *  warning in a case that previously silently mis-indexed, so it can't change any existing
+ *  single-repo index's output. */
+async function warnIfLooksLikeEstateRoot(repoPath) {
+  if (existsSync(join(repoPath, ".git"))) return;
+  let entries;
+  try { entries = await readdir(repoPath, { withFileTypes: true }); }
+  catch { return; }
+  let childRepoCount = 0;
+  for (const e of entries) {
+    if (e.isDirectory() && existsSync(join(repoPath, e.name, ".git"))) childRepoCount++;
+    if (childRepoCount >= 2) break;
+  }
+  if (childRepoCount >= 2) {
+    process.stderr.write(
+      `seonix: WARNING — ${repoPath} has no .git of its own, but multiple child directories do. ` +
+        "This looks like a multi-repo estate root, not a single repo — indexing it this way flattens " +
+        "every sub-repo together with NO git history (git log fails against a non-repo root) and no " +
+        "per-repo module-id prefixing. If that's not what you want, re-run with " +
+        `'{"multi_root":"${repoPath}"}' instead, which discovers each child repo and indexes it properly.\n`,
+    );
+  }
+}
+
 // Hot tools (server.mjs's TOOLS) carry an inputSchema but no example value, so their
 // example-args + primary-arg-key aren't derivable the way COLD_TOOLS' are — hand-maintained
 // here, right next to COLD_TOOLS' import, so a new hot tool is a one-line addition in both places.
@@ -482,9 +542,13 @@ async function main() {
     // '{"repo_paths":[…],"out_root":"<abs>"}' (explicit n-repo merge) or
     // '{"multi_root":"<abs>"}' (discover child repos, merge into <multi_root>/.seonix/).
     if (sub === "index_repository") {
-      const args = parsePayload(payload);
+      const isFlagForm = payload !== undefined && payload.startsWith("--");
+      const args = isFlagForm ? parseIndexFlags(process.argv.slice(4)) : parsePayload(payload);
       if (args === null) {
-        process.stderr.write("seonix: index_repository expects a JSON arg, e.g. '{\"repo_path\":\"/abs\"}'\n");
+        process.stderr.write(
+          "seonix: index_repository expects a JSON arg, e.g. '{\"repo_path\":\"/abs\"}', " +
+            "or a flag: --multi-root [path], --repo-path [path], --out-root <path>\n",
+        );
         process.exit(2);
       }
       const given = ["repo_path", "repo_paths", "multi_root"].filter((k) => args[k] !== undefined);
@@ -557,6 +621,7 @@ async function main() {
       };
 
       if (args.repo_path) {
+        await warnIfLooksLikeEstateRoot(args.repo_path);
         const { graphFile, counts, summary } = await indexRepository(args.repo_path, { ignores: args.ignores !== false, historyDepth, extraIgnores, languages: tomlLanguages, interfaces: tomlInterfaces });
         emitSummary(graphFile, counts, "");
         // A1: the human summary MD goes to STDOUT (bench ignores index stdout — safe;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.10.7",
+  "version": "0.10.10",
   "private": false,
   "type": "module",
   "description": "SEONIX — a deterministic, offline, $0 code-graph tool that makes a cheap coding agent edit like an expensive one. Indexes a repo with Python ast + git (zero model calls) and renders a bounded edit-digest.",
@@ -65,11 +65,12 @@
     "verify:query": "node scripts/verify-query.mjs",
     "verify:review": "node scripts/verify-review.mjs",
     "verify:loop": "node scripts/verify-loop.mjs",
+    "verify:shipped": "node scripts/verify-shipped.mjs",
     "refs": "node scripts/fetch-references.mjs",
     "refs:embeddings": "node scripts/fetch-embeddings.mjs",
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
-    "test:root": "node --test \"test/**/*.test.mjs\"",
+    "test:root": "GIT_CONFIG_GLOBAL=\"$PWD/test/fixtures/global-gitconfig\" node --test \"test/**/*.test.mjs\"",
     "test": "npm run test:root && npm run chrono:test",
     "chrono:build": "node chronograph/build.mjs",
     "chrono:serve": "node chronograph/serve.mjs",
@@ -87,7 +88,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@polycode-projects/the-mechanical-code-talker": "^0.9.5",
+    "@polycode-projects/the-mechanical-code-talker": "^0.9.10",
     "cytoscape": "^3.30.0",
     "smol-toml": "^1.7.0",
     "tree-sitter": "^0.21.1",

package/src/ask-browser.bundle.js

@@ -108,6 +108,9 @@
     if (/\b(inherit|subclass|extend|specializ)/.test(pred)) return "inherits";
     return null;
   }
+  function normPath(s) {
+    return String(s || "").trim().toLowerCase().replace(/^\.\//, "").replace(/^\//, "");
+  }
   function siteOf(ind) {
     const a = (ind?.attributes || []).find((x) => x.key === "site");
     if (!a) return null;
@@ -413,7 +416,15 @@
         "tends to change together with",
         "tend to change together with",
         "moves together with",
-        "move together with"
+        "move together with",
+        // Track-1 trio (temporal lever): the bare "changed/change together with" form
+        // (no "tends to"/"tend to" prefix) was missing outright — "which modules
+        // changed together with X" fell through to the "touch(ed)" verb instead (a
+        // Commit->Module kind, structurally unable to match a Module subject), always
+        // producing a confidently-empty answer regardless of real cochange data.
+        "changed together with",
+        "change together with",
+        "changes together with"
       ]
     },
     reexports: {
@@ -672,7 +683,9 @@
     "quickly",
     "real quick",
     "kinda",
-    "sorta"
+    "sorta",
+    "btw",
+    "by the way"
   ]);
   var CONTEXT_PRONOUNS = Object.freeze(["this", "it", "that", "here", "this one", "that one"]);
   var NEGATION_FRAMES = Object.freeze([
@@ -980,6 +993,7 @@
     return LISTING_TAIL_KINDS.has((words[words.length - 1] || "").toLowerCase());
   };
   var GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy)(?:\s+there)?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+  var THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(?:\s+(?:so\s+much|a\s+lot|very\s+much|a\s+bunch))?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
   var MODAL_WRAPPER_RE = /^(?:can|could|would|will)\s+you\s+(?:please\s+)?(.+?)(?:[,\s]+please)?\??$/i;
   var SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
   function applyPreambleFrames(text) {
@@ -988,6 +1002,8 @@
       const before = q;
       let m = q.match(GREETING_PREAMBLE_RE);
       if (m) q = m[1].trim();
+      m = q.match(THANKS_PREAMBLE_RE);
+      if (m) q = m[1].trim();
       m = q.match(MODAL_WRAPPER_RE);
       if (m) q = m[1].trim();
       m = q.match(SHOW_GIVE_ME_RE);
@@ -1001,6 +1017,55 @@
     }
     return q;
   }
+  var SUBORDINATION_FRAMES_RE = /^(?:since|although|though|while|because|whereas|given\s+that|now\s+that)\s+.+?,\s*(.+)$/i;
+  function applySubordinationFrames(text) {
+    let q = String(text || "");
+    for (let pass = 0; pass < 3; pass++) {
+      const m = q.match(SUBORDINATION_FRAMES_RE);
+      if (!m) break;
+      q = m[1].trim();
+    }
+    return q;
+  }
+  var CONDITIONAL_VERB_GERUND = Object.freeze({
+    imports: "importing",
+    calls: "calling",
+    touches: "touching",
+    tests: "testing",
+    exports: "exporting",
+    contains: "containing",
+    defines: "defining",
+    uses: "using",
+    "inherits from": "inheriting from"
+  });
+  var CONDITIONAL_KIND_PLURAL = Object.freeze({
+    module: "modules",
+    class: "classes",
+    function: "functions",
+    method: "methods",
+    attribute: "attributes",
+    variable: "variables",
+    commit: "commits",
+    file: "files"
+  });
+  var CONDITIONAL_QUALIFIER_SRC = "public|private|protected|static|abstract|constant|re-?exported|exported|tested|covered|untested|uncovered";
+  var CONDITIONAL_QUALIFIER_RE = new RegExp(
+    "^if\\s+(?:a|an|the)?\\s*(" + Object.keys(CONDITIONAL_KIND_PLURAL).join("|") + ")\\s+(" + Object.keys(CONDITIONAL_VERB_GERUND).join("|") + ")\\s+(.+?),\\s*(?:is|are)\\s+(?:it|that|they|this)\\s+(" + CONDITIONAL_QUALIFIER_SRC + ")\\??$",
+    "i"
+  );
+  var COUNTERFACTUAL_RE = /^if\s+(.+?)\s+(?:were|was)\s+(?:deleted|removed),?\s*what\s+(?:would|might|could)\s+(?:break|fail|be\s+affected)\??$/i;
+  function applyConditionalFrames(text) {
+    const q = String(text || "");
+    const qual = q.match(CONDITIONAL_QUALIFIER_RE);
+    if (qual) {
+      const kind = CONDITIONAL_KIND_PLURAL[qual[1].toLowerCase()];
+      const gerund = CONDITIONAL_VERB_GERUND[qual[2].toLowerCase()];
+      return `${kind} ${gerund} ${qual[3].trim()} and ${qual[4].toLowerCase()}`;
+    }
+    const cf = q.match(COUNTERFACTUAL_RE);
+    if (cf) return `which modules transitively import ${cf[1].trim()}`;
+    return q;
+  }
   function normalizeQuery(text) {
     let q = String(text || "");
     q = q.replace(CONTRACTION_RE, (m) => CONTRACTIONS[m.toLowerCase()]);
@@ -1008,6 +1073,8 @@
     q = q.replace(WRONG_WORD_RE, (m) => WRONG_WORDS[m.toLowerCase()]);
     q = q.replace(G_DROP, "$1ing");
     q = applyPreambleFrames(q);
+    q = applySubordinationFrames(q);
+    q = applyConditionalFrames(q);
     if (FILLER_WORDS.length) {
       const fillerRe = new RegExp(
         "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
@@ -1173,7 +1240,33 @@
     // temporal filler in when-questions ("when was X last touched") — a symbol
     // literally named "last" would be the accepted residual cost, same trade as
     // every other stopword.
-    "last"
+    "last",
+    // frequency-adverb filler ("what does X usually change together with", "what does
+    // X typically call") — found live: "usually" glued onto the object term instead of
+    // being stripped, corrupting resolution ("src/core/store.mjs usually" instead of
+    // the module alone). Same trade as every other stopword: a symbol literally named
+    // "usually" would be the accepted residual cost.
+    "usually",
+    "typically",
+    "generally",
+    "normally",
+    "often",
+    "commonly",
+    "mostly",
+    // modal auxiliaries ("what SHOULD i look at first") — found live: with no modal in
+    // this set, "should" reached the cascade's bounded fuzzy-correction step and landed
+    // within edit distance of the unrelated closed-vocab word "hold" ("defines" synonym,
+    // ask-vocab.mjs), corrupting the whole query into "what hold i at". Same trade as
+    // every other stopword: a symbol literally named "should" would be the accepted
+    // residual cost.
+    "should",
+    "would",
+    "could",
+    "can",
+    "will",
+    "shall",
+    "might",
+    "must"
   ]);
   var splitWords = (text) => String(text).replace(/\?+\s*$/, "").replace(/,/g, " ").split(/\s+/).filter(Boolean);
   var wordsOf = (arr) => arr.flatMap((p) => String(p).toLowerCase().split(" "));
@@ -1412,6 +1505,15 @@
       if (hit2) for (let i = hit2.start; i < hit2.end; i += 1) consumed.add(i);
     };
     mark(verbHit);
+    for (const [phrase, kind2] of Object.entries(VERB_TO_KIND)) {
+      if (kind2 !== verbHit.kind) continue;
+      const pWords = phrase.split(" ");
+      const start = verbHit.end;
+      if (pWords.every((w, j) => canonWords[start + j] === w)) {
+        mark({ start, end: start + pWords.length });
+        break;
+      }
+    }
     const entityHit = findPhrase(canonWords, ENTITY_TO_TYPE, consumed);
     mark(entityHit);
     const modifierHit = findPhrase(canonWords, MODIFIER_TO_KIND, consumed);
@@ -2116,12 +2218,21 @@
   }
 
   // node_modules/@polycode-projects/the-mechanical-code-talker/src/ask.mjs
+  var askEdgesOfKindCache = /* @__PURE__ */ new WeakMap();
   function edgesOfKind(graph, kind) {
+    let byKind = askEdgesOfKindCache.get(graph);
+    if (!byKind) {
+      byKind = /* @__PURE__ */ new Map();
+      askEdgesOfKindCache.set(graph, byKind);
+    }
+    const cached3 = byKind.get(kind);
+    if (cached3) return cached3;
     const out = [];
     for (const g of graph.relations) {
       if (relationKind(g) !== kind) continue;
       for (const e of g.edges) out.push(e);
     }
+    byKind.set(kind, out);
     return out;
   }
   var SYMBOL_GRAIN_SIBLING = { calls: "callsSymbol", touches: "touchesSymbol" };
@@ -2146,7 +2257,7 @@
     const [s, p] = PLURAL_FORMS[entityType] || ["result", "results"];
     return n === 1 ? s : p;
   }
-  var REVERSE_MISS_VERB = { cochange: "cochanges" };
+  var REVERSE_MISS_VERB = { cochange: "cochanges", reexports: "export" };
   function verbFor(kind) {
     return REVERSE_MISS_VERB[kind] || kind;
   }
@@ -2180,7 +2291,7 @@
   function parseComposite(text, nlp) {
     const w = splitWords(text);
     const lc = w.map((x) => x.toLowerCase());
-    return parseNegation(text, nlp, 0) || parseForwardNegation(w, lc, nlp) || parseTemporal(w, lc, nlp, 0) || parseAnaphora(w, lc, nlp) || parseAggregate(w, lc, nlp) || parseSuperlative(w, lc, nlp) || parseList(w, lc, nlp, 0) || parseNested(w, lc, nlp, 0) || parseRelationalOrQualified(w, lc, nlp, 0);
+    return parseNegation(text, nlp, 0) || parseForwardNegation(w, lc, nlp) || parseTemporal(w, lc, nlp, 0) || parseAnaphora(w, lc, nlp) || parseAggregate(w, lc, nlp) || parseSuperlative(w, lc, nlp) || parseFind(w, lc, nlp, 0) || parseList(w, lc, nlp, 0) || parseNested(w, lc, nlp, 0) || parseRelationalOrQualified(w, lc, nlp, 0);
   }
   function complementAst(entityType, diffAtom) {
     return {
@@ -2509,7 +2620,84 @@
     }
     return { node: "superlative", entityType, metric, metricNoun, extreme: ext };
   }
+  var FIND_LINKERS = /* @__PURE__ */ new Set(["called", "named", "about", "like", "containing", "matching", "with"]);
+  function parseFind(w, lc, nlp, depth) {
+    if (lc[0] !== "find") return null;
+    let i = 1;
+    while (i < lc.length && LIST_SKIP.has(lc[i])) i += 1;
+    if (i >= lc.length) return null;
+    const leadNoun = entityNoun(lc[i]);
+    if (leadNoun && !leadNoun.placeholder && leadNoun.entityType !== "Change" && i + 1 < lc.length && FIND_LINKERS.has(lc[i + 1])) {
+      const term = w.slice(i + 2).join(" ").trim();
+      if (term) return { node: "find", entityType: leadNoun.entityType, term };
+    }
+    const lastNoun = entityNoun(lc[lc.length - 1]);
+    if (lastNoun && !lastNoun.placeholder && lastNoun.entityType !== "Change") {
+      const term = w.slice(i, lc.length - 1).join(" ").trim();
+      if (term) return { node: "find", entityType: lastNoun.entityType, term };
+    }
+    if (lc.some((t) => RELATIVE_PRONOUNS.includes(t))) return null;
+    if (i === lc.length - 1 && /^[a-z]+$/.test(lc[i]) && !VERB_TO_KIND[lc[i]] && !PLACEHOLDER_NOUNS.includes(lc[i])) {
+      return { node: "miss", reason: `"${lc[i]}" isn't a listable kind \u2014 try ${LISTABLE_KINDS}` };
+    }
+    return null;
+  }
+  function parseFindPredicateHead(w, lc) {
+    if (lc[0] !== "find") return null;
+    let i = 1;
+    while (i < lc.length && LIST_SKIP.has(lc[i])) i += 1;
+    let r = -1;
+    for (let k = i + 1; k < lc.length; k += 1) {
+      if (RELATIVE_PRONOUNS.includes(lc[k])) {
+        r = k;
+        break;
+      }
+    }
+    if (r < 0) return null;
+    const noun = entityNoun(lc[r - 1]);
+    if (!noun || noun.placeholder || noun.entityType === "Change") return null;
+    const term = w.slice(i, r - 1).join(" ").trim();
+    if (!term) return null;
+    return { entityType: noun.entityType, term, relIdx: r };
+  }
+  function buildPredicateAtoms(entityType, subjPrefix, predLc, predWords, nlp, depth) {
+    const { branches, ops } = splitBoolean(predLc, predWords);
+    let prevVerb = null;
+    const atoms = [];
+    for (let b = 0; b < branches.length; b += 1) {
+      const bw = branches[b];
+      const blc = bw.map((x) => x.toLowerCase());
+      const op = b === 0 ? "intersection" : ops[b - 1];
+      if (bw.length && blc.every((x) => QUALIFIERS[x])) {
+        atoms.push({ op, kind: "qual", filters: blc });
+        continue;
+      }
+      if (blc[0] === "of" || blc[0] === "in") {
+        atoms.push({ op, kind: "set", ast: { node: "membership", entityType, term: bw.slice(1).join(" ") } });
+        continue;
+      }
+      let phrase = bw;
+      const vh = findPhrase(blc, VERB_TO_KIND);
+      if (vh) prevVerb = bw.slice(vh.start, vh.end);
+      else if (prevVerb) phrase = [...prevVerb, ...bw];
+      const ast = parseBranchAst(`${subjPrefix} ${phrase.join(" ")}`, nlp, depth);
+      if (!ast || ast.node === "miss") return { miss: ast && ast.reason || "a clause in the combination didn't parse" };
+      atoms.push({ op, kind: "set", ast });
+    }
+    return { atoms };
+  }
   function parseRelationalOrQualified(w, lc, nlp, depth) {
+    const findHead = parseFindPredicateHead(w, lc);
+    if (findHead) {
+      const { entityType: entityType2, term, relIdx } = findHead;
+      const predLc2 = lc.slice(relIdx + 1);
+      const predWords2 = w.slice(relIdx + 1);
+      if (!predLc2.length) return { node: "miss", reason: `a relative clause needs a predicate after "${lc[relIdx]}"` };
+      const built = buildPredicateAtoms(entityType2, `which ${lc[relIdx - 1]}`, predLc2, predWords2, nlp, depth + 1);
+      if (built.miss) return { node: "miss", reason: built.miss };
+      const atoms2 = [{ op: "seed", kind: "set", ast: { node: "find", entityType: entityType2, term } }, ...built.atoms];
+      return atoms2.length === 1 ? atoms2[0].ast : { node: "boolean", entityType: entityType2, atoms: atoms2 };
+    }
     let i = 0;
     while (i < lc.length && FRAME_WORDS.has(lc[i])) i += 1;
     const framed = i > 0;
@@ -2520,8 +2708,9 @@
     }
     const noun = i < lc.length ? entityNoun(lc[i]) : null;
     if (!noun) {
-      if ((framed || quals.length) && i + 1 < lc.length && /^[a-z]+$/.test(lc[i]) && !VERB_TO_KIND[lc[i]] && !STOPWORDS2.has(lc[i]) && entityNoun(lc[i + 1])) {
-        return { node: "miss", reason: `unknown qualifier "${lc[i]}" \u2014 supported: ${Object.keys(QUALIFIERS).join(", ")}` };
+      const nextNoun = i + 1 < lc.length ? entityNoun(lc[i + 1]) : null;
+      if ((framed || quals.length) && nextNoun && /^[a-z]+$/.test(lc[i]) && !VERB_TO_KIND[lc[i]] && !STOPWORDS2.has(lc[i])) {
+        return { node: "find", entityType: nextNoun.entityType, term: w[i] };
       }
       return null;
     }
@@ -2646,6 +2835,12 @@
     }
     return out;
   }
+  function directoryScopeModules(graph, term) {
+    const norm = normPath(term);
+    if (!norm) return [];
+    const prefix = `${norm}/`;
+    return graph.individuals.filter((i) => i.class === "Module" && normPath(i.label).startsWith(prefix));
+  }
   var qualCache = /* @__PURE__ */ new WeakMap();
   function qualSets(graph) {
     let c = qualCache.get(graph);
@@ -2689,12 +2884,127 @@
         return false;
     }
   }
+  function inheritsEdges(graph) {
+    return edgesOfKind(graph, "inherits");
+  }
+  function directChildrenOf(graph, id) {
+    return inheritsEdges(graph).filter((e) => e.object === id).map((e) => e.subject);
+  }
+  function directParentsOf(graph, id) {
+    return inheritsEdges(graph).filter((e) => e.subject === id).map((e) => e.object);
+  }
+  function descendantsOf(graph, id) {
+    const out = /* @__PURE__ */ new Set();
+    const queue = [...directChildrenOf(graph, id)];
+    while (queue.length) {
+      const next = queue.shift();
+      if (out.has(next)) continue;
+      out.add(next);
+      for (const c of directChildrenOf(graph, next)) if (!out.has(c)) queue.push(c);
+    }
+    return out;
+  }
+  function ancestorsOf(graph, id) {
+    const out = /* @__PURE__ */ new Set();
+    const queue = [...directParentsOf(graph, id)];
+    while (queue.length) {
+      const next = queue.shift();
+      if (out.has(next)) continue;
+      out.add(next);
+      for (const p of directParentsOf(graph, next)) if (!out.has(p)) queue.push(p);
+    }
+    return out;
+  }
+  var inheritsApplicableCache = /* @__PURE__ */ new WeakMap();
+  function inheritsApplicable(graph, entityType) {
+    let byType = inheritsApplicableCache.get(graph);
+    if (!byType) {
+      byType = /* @__PURE__ */ new Map();
+      inheritsApplicableCache.set(graph, byType);
+    }
+    if (byType.has(entityType)) return byType.get(entityType);
+    const ok = inheritsEdges(graph).some((e) => {
+      const s = graph.byId.get(e.subject);
+      const o = graph.byId.get(e.object);
+      return !!s && !!o && s.class === entityType && o.class === entityType;
+    });
+    byType.set(entityType, ok);
+    return ok;
+  }
+  function ownSurfaceHit(ind, termTokens) {
+    const labelLc = String(ind.label || "").toLowerCase();
+    if (termTokens.every((tok) => labelLc.includes(tok))) return "label";
+    const attrs = (ind.attributes || []).map((a) => String(a.value ?? "").toLowerCase());
+    if (termTokens.every((tok) => attrs.some((v) => v.includes(tok)))) return "attr";
+    return null;
+  }
+  var FIND_TIER = { label: 3, chain: 2, attr: 1 };
+  function sortFindHits(hits) {
+    return hits.slice().sort((a, b) => FIND_TIER[b.via] - FIND_TIER[a.via] || String(a.ind.label).length - String(b.ind.label).length).map((h) => h.ind);
+  }
+  function fuzzyFindHit(ind, term) {
+    const tLc = String(term || "").trim().toLowerCase();
+    if (tLc.length < 4) return false;
+    const bound = fuzzyBound(tLc);
+    if (editDistance(String(ind.label || "").toLowerCase(), tLc, bound) <= bound) return true;
+    for (const comp of componentSet(ind.label)) {
+      if (editDistance(comp, tLc, bound) <= bound) return true;
+    }
+    return false;
+  }
+  function computeFind(graph, entityType, term) {
+    const pool = graph.individuals.filter((i) => i.class === entityType);
+    const termTokens = [...componentSet(term)];
+    if (!termTokens.length || !pool.length) return { narrow: [], broad: [] };
+    const cascade = inheritsApplicable(graph, entityType);
+    const narrowHits = [];
+    for (const ind of pool) {
+      const own = ownSurfaceHit(ind, termTokens);
+      if (own) {
+        narrowHits.push({ ind, via: own });
+        continue;
+      }
+      if (!cascade) continue;
+      const viaChain = [...descendantsOf(graph, ind.id)].some((did) => {
+        const d = graph.byId.get(did);
+        return !!d && !!ownSurfaceHit(d, termTokens);
+      });
+      if (viaChain) narrowHits.push({ ind, via: "chain" });
+    }
+    if (narrowHits.length || !cascade) return { narrow: sortFindHits(narrowHits), broad: [] };
+    const broadHits = /* @__PURE__ */ new Map();
+    for (const ind of pool) {
+      for (const ancId of ancestorsOf(graph, ind.id)) {
+        if (!broadHits.has(ancId)) {
+          const anc = graph.byId.get(ancId);
+          if (anc && anc.class === entityType && fuzzyFindHit(anc, term)) {
+            broadHits.set(ancId, { ind: anc, via: "chain" });
+          }
+        }
+        for (const sibId of directChildrenOf(graph, ancId)) {
+          if (sibId === ind.id || broadHits.has(sibId)) continue;
+          const sib = graph.byId.get(sibId);
+          if (sib && sib.class === entityType && fuzzyFindHit(sib, term)) broadHits.set(sibId, { ind: sib, via: "chain" });
+        }
+      }
+    }
+    return { narrow: [], broad: sortFindHits([...broadHits.values()]) };
+  }
   function evalSet(graph, ast, opts) {
     switch (ast.node) {
       case "clause":
         return traverse(graph, ast.clause, opts).matches || [];
       case "allOfClass":
         return graph.individuals.filter((i) => i.class === ast.entityType);
+      // predicate-find (Workstream 2), embedded as a set atom (§6 generalization —
+      // a find-seed inside a boolean/qualifier fold): the narrow-then-broaden
+      // cascade's result, transparently flattened (the "related, not exact" framing
+      // is a top-level RENDER concern — evalComposite's dedicated "find" handling
+      // below, not this generic embedding).
+      case "find": {
+        const { narrow, broad } = computeFind(graph, ast.entityType, ast.term);
+        return narrow.length ? narrow : broad;
+      }
       // the SUBJECTS that have ANY edge of a kind (the existential "modules that import
       // anything") — the positive set an existential negation ("do not import anything")
       // differences off allOfClass to yield "modules that import nothing".
@@ -2722,6 +3032,15 @@
       }
       case "membership": {
         const r = resolveObject(graph, ast.term);
+        if (!(r.match && r.tier === 1)) {
+          const dirMods = directoryScopeModules(graph, ast.term);
+          if (dirMods.length) {
+            if (!ast.entityType || ast.entityType === "Module") return dirMods;
+            const ids2 = new Set(dirMods.map((m) => m.id));
+            const objs2 = uniqueById(MEMBERSHIP_KINDS.flatMap((k) => forwardOverSet(graph, k, ids2)));
+            return objs2.filter((o) => o.class === ast.entityType);
+          }
+        }
         if (!r.match) return [];
         const ids = /* @__PURE__ */ new Set([r.match.id]);
         const objs = uniqueById(MEMBERSHIP_KINDS.flatMap((k) => forwardOverSet(graph, k, ids)));
@@ -2827,11 +3146,27 @@
     if (ast.node === "superlative") return evalSuperlative(graph, ast);
     if (ast.node === "temporal") return evalTemporal(graph, ast, opts);
     if (ast.node === "anaphora") return evalAnaphora(graph, ast, opts);
+    if (ast.node === "find") {
+      const { narrow, broad } = computeFind(graph, ast.entityType, ast.term);
+      return {
+        compositeKind: "find",
+        entityType: ast.entityType,
+        term: ast.term,
+        matches: narrow.length ? narrow : broad,
+        broad: !narrow.length && broad.length > 0
+      };
+    }
     return { compositeKind: "set", matches: evalSet(graph, ast, opts), entityType: ast.entityType || null };
   }
   var compositeList = (matches) => listJoin(matches.slice(0, OVERFLOW_CAP).map((m) => ["Function", "Method"].includes(m.class) ? `${m.label}()` : m.label)) + (matches.length > OVERFLOW_CAP ? `, \u2026and ${matches.length - OVERFLOW_CAP} more` : "");
   function compositionalHint() {
-    return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "list functions" / "show me the classes", "how many classes", "which module has the most imports", or (after a listing) "which of those are tested"';
+    return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "list functions" / "show me the classes", "how many classes", "which module has the most imports", "find me the payment class", or (after a listing) "which of those are tested"';
+  }
+  function describeFindHit(ind) {
+    const label = ["Function", "Method"].includes(ind.class) ? `${ind.label}()` : ind.label;
+    if (ind.class === "Module") return label;
+    const mod = moduleLabelOf(ind);
+    return mod && mod !== "(unknown module)" ? `${label} in ${mod}` : label;
   }
   function renderComposite(parsed, result) {
     if (result.compositeMiss) {
@@ -2852,6 +3187,23 @@
       const hint = !result.scoped && scopeable && result.matches.length > OVERFLOW_CAP ? ` \u2014 narrow with "${nounFor(result.entityType, 2)} in <module>"` : "";
       return { content: `${compositeList(result.matches)}${hint}.`, miss: false, ambiguous: false, matches: result.matches };
     }
+    if (result.compositeKind === "find") {
+      const typeNoun = nounFor(result.entityType, 1);
+      if (!result.matches.length) {
+        return { content: `no ${nounFor(result.entityType, 2)} found matching "${result.term}".`, miss: true, ambiguous: false, matches: [] };
+      }
+      const cited = result.matches.length === 1 ? describeFindHit(result.matches[0]) : compositeList(result.matches);
+      if (result.broad) {
+        return {
+          content: `no exact ${typeNoun} named "${result.term}", but found a related ${result.matches.length === 1 ? typeNoun : nounFor(result.entityType, 2)}: ${cited}.`,
+          miss: false,
+          ambiguous: false,
+          matches: result.matches,
+          relatedNotExact: true
+        };
+      }
+      return { content: `${cited}.`, miss: false, ambiguous: false, matches: result.matches };
+    }
     if (result.compositeKind === "superlative") {
       if (!result.matches.length) return { content: `no ${nounFor(result.entityType, 2)} to rank in this index.`, miss: true, ambiguous: false };
       const lead = result.extreme === "most" ? "the most" : "the fewest";
@@ -2899,11 +3251,11 @@
   function componentSet(s) {
     return new Set(String(s).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
   }
-  function resolveObject(graph, term) {
+  function resolveObject(graph, term, { expectedClass = null } = {}) {
     const t = String(term || "").trim();
     if (!t) return { match: null, candidates: [], tier: null, ambiguous: false };
     const tLc = t.toLowerCase();
-    const pool = graph.individuals;
+    const pool = expectedClass ? graph.individuals.filter((i) => i.class === expectedClass) : graph.individuals;
     const shaTerm = tLc.match(/^(commit[:\s])?([0-9a-f]{7,40})$/);
     if (shaTerm) {
       const sha = shaTerm[2];
@@ -2924,7 +3276,7 @@
         }
       }
     }
-    if (extId) return { match: { id: extId, label: t, class: null }, candidates: [], tier: 2, ambiguous: false };
+    if (extId && !expectedClass) return { match: { id: extId, label: t, class: null }, candidates: [], tier: 2, ambiguous: false };
     const scored = [];
     const dotted = !tLc.includes("/") && /^[\w$]+(\.[\w$]+)+$/.test(tLc);
     if (dotted) {
@@ -2963,7 +3315,7 @@
       };
     }
     let proseResult = null;
-    const proseHits = !dotted && typeof lookupByProseTokens === "function" ? lookupByProseTokens(graph.proseIndex, t) : [];
+    const proseHits = !dotted && typeof lookupByProseTokens === "function" ? lookupByProseTokens(graph.proseIndex, t).filter((h) => !expectedClass || graph.byId.get(h.id)?.class === expectedClass) : [];
     if (proseHits.length) {
       const [best, ...rest] = proseHits;
       const bestInd = graph.byId.get(best.id);
@@ -3221,10 +3573,59 @@
       }
       return { matches: matches2, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}${widenNote}`, ambiguous, matchedVia };
     }
-    let edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === objMatch.id);
+    let gObjMatch = objMatch;
+    let gCandidates = candidates;
+    let gAmbiguous = ambiguous;
+    let gMatchedVia = matchedVia;
+    let grainRefinedNote = "";
+    const wantClass = kindObjectClass(graph, kind);
+    if (wantClass && gObjMatch.class && gObjMatch.class !== wantClass) {
+      const retry = resolveObject(graph, parsed.object, { expectedClass: wantClass });
+      if (retry.match && !retry.ambiguous) {
+        gObjMatch = retry.match;
+        gCandidates = retry.candidates;
+        gAmbiguous = retry.ambiguous;
+        gMatchedVia = retry.matchedVia;
+      } else if ((kind === "tests" || kind === "cochange") && gObjMatch.class !== "Module") {
+        const mid = moduleIdOf2(graph, gObjMatch);
+        const mod = mid && graph.byId.get(mid);
+        if (mod) {
+          grainRefinedNote = `, refined from ${gObjMatch.label} to its containing module`;
+          gObjMatch = mod;
+        } else {
+          return {
+            matches: [],
+            objMatch: gObjMatch,
+            candidates: gCandidates,
+            ambiguous: gAmbiguous,
+            matchedVia: gMatchedVia,
+            wrongGrainMiss: true,
+            wantClass,
+            traversal: `"${parsed.object}" resolved to ${gObjMatch.class} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${wantClass}, and no containing module could be found to refine to)`
+          };
+        }
+      } else {
+        return {
+          matches: [],
+          objMatch: gObjMatch,
+          candidates: gCandidates,
+          ambiguous: gAmbiguous,
+          matchedVia: gMatchedVia,
+          wrongGrainMiss: true,
+          wantClass,
+          traversal: `"${parsed.object}" resolved to ${gObjMatch.class} ${gObjMatch.label} (grain mismatch: this "${kind}" question needs a ${wantClass})`
+        };
+      }
+    }
+    let edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.object === gObjMatch.id);
+    if (kind === "cochange") {
+      edges = edges.concat(
+        kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => e.subject === gObjMatch.id).map((e) => ({ ...e, subject: e.object, object: e.subject }))
+      );
+    }
     let extNote = "";
-    if (!edges.length && objMatch.class) {
-      const extId = `ext:${String(objMatch.label).toLowerCase()}`;
+    if (!edges.length && gObjMatch.class) {
+      const extId = `ext:${String(gObjMatch.label).toLowerCase()}`;
       edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => String(e.object).toLowerCase() === extId);
       if (edges.length) extNote = ` (by name, via unresolved ${extId} references)`;
     }
@@ -3252,7 +3653,14 @@
         matches = [];
       }
     }
-    return { matches, objMatch, candidates, traversal: `${kindsFor(kind).join("+")} edges where object = ${objMatch.label}${extNote}${grainNote}`, ambiguous, matchedVia };
+    return {
+      matches,
+      objMatch: gObjMatch,
+      candidates: gCandidates,
+      traversal: `${kindsFor(kind).join("+")} edges where object = ${gObjMatch.label}${extNote}${grainNote}${grainRefinedNote}`,
+      ambiguous: gAmbiguous,
+      matchedVia: gMatchedVia
+    };
   }
   function moduleLabelOf(ind) {
     if (ind.class === "Module") return ind.label;
@@ -3313,6 +3721,15 @@
         ambiguous: false
       };
     }
+    if (result.wrongGrainMiss) {
+      const gotNoun = result.objMatch.class ? nounFor(result.objMatch.class, 1) : "term";
+      const wantNoun = nounFor(result.wantClass, 1);
+      return {
+        content: `"${parsed.object}" resolved to the ${gotNoun} ${result.objMatch.label}, but this question needs a ${wantNoun} \u2014 no ${wantNoun} named "${parsed.object}" was found in the index.`,
+        miss: true,
+        ambiguous: false
+      };
+    }
     if (parsed.shape === "meta") {
       if (!result.objMatch) {
         return {
@@ -3365,8 +3782,10 @@
     if (result.ambiguous) {
       const pool = [result.objMatch, ...result.candidates || []].filter(Boolean);
       const noun = pool.length && pool.every((i) => i.class === "Commit") ? "commit" : "module";
+      const shown = pool.slice(0, OVERFLOW_CAP).map((i) => i.label);
+      const extra2 = pool.length > OVERFLOW_CAP ? `, \u2026and ${pool.length - OVERFLOW_CAP} more` : "";
       return {
-        content: `"${parsed.object}" matches more than one ${noun} ambiguously \u2014 please narrow the term.`,
+        content: `"${parsed.object}" matches more than one ${noun} ambiguously \u2014 did you mean ${listJoin(shown)}${extra2}? Try one of those.`,
         miss: false,
         ambiguous: true,
         candidates: pool.map((i) => i.label)
@@ -3451,7 +3870,7 @@
     if (!result.matches.length) {
       if (parsed.shape === "forward") {
         return {
-          content: `${result.objMatch.label} has no ${parsed.kind} edges in the index.`,
+          content: `${result.objMatch.label} has no ${verbFor(parsed.kind)} edges in the index.`,
           miss: true,
           ambiguous: false
         };

package/src/ask-browser.bundle.version

@@ -0,0 +1 @@
+0.9.10