@polycode-projects/the-mechanical-code-talker 0.3.0 → 0.5.0

package/data/templates/grammar-rules.toml

@@ -0,0 +1,97 @@
+# grammar-rules.toml — the data-driven grammar-rule table (Phase 7, lever 2)
+# (PLAN_RESPONSE_FINISHING.md, "The grammar pass (lever 2)").
+#
+# Each [[rule]] is a corrective grammar rule applied by applyGrammar() in
+# src/finish.mjs over the PROSE spans of a segmented answer — NEVER the flat
+# string, and NEVER a protected span (entity / path / number / code / provenance
+# / receipt). The engine reads STRUCTURE, never guesses from surface: an article
+# rule that would touch the word inside the following protected span refuses to
+# fire, agreement reads the following number's value, and so on.
+#
+# CONTRACT (the plan's law): a rule's NEUTRAL behaviour is BYTE-STABLE. The only
+# byte changes a rule may introduce are GENUINE fixes to defects tmct itself
+# generates ("a artifact"). `kind` selects the built-in handler; `enabled=false`
+# PARKS a rule out of the live answer path; the remaining keys are that handler's
+# applicability conditions + parameters. Rules apply in file order; the set is
+# chosen to commute so finish() is idempotent: finish(finish(x)) === finish(x).
+#
+# SEQUENCING (PLAN_RESPONSE_FINISHING.md, "one grammar rule per tuning cycle"):
+# LIVE as of cycle 005: ARTICLE-SELECTION (cycle 4), plus the two SAFE defect
+# fixes TERMINAL-PUNCTUATION and SUBJECT-VERB-AGREEMENT — each byte-stable when
+# neutral, no product-voice change. CAPITALISATION and LIST are fully implemented
+# and golden-tested IN ISOLATION but remain PARKED (enabled=false). The cycle-006
+# judged A/B was assessed and DROPPED: `capitalise` rewrites the sentence-initial
+# char, which regresses ~10 frozen v1 cases.jsonl whose case-sensitive answerMatch
+# pins lowercase openers ("can't count", "no symbol matching", "assuming you meant",
+# …) — the same sacred-case collision that reverted the voice-nit; and `list` has
+# zero 3-item "X and Y and Z" targets in the judged set (a no-op). Deferred to a
+# post-arc case-set refresh where the openers can be re-pinned deliberately. They
+# rewrite established product bytes (tmct's
+# lowercase openers and repeated "and" joins are an intentional VOICE, not a
+# grammar defect), so activating them is a per-rule tuning-cycle decision with
+# its own bench + showcase reconcile, not a blanket flip. `enabled=false` keeps
+# them inert in finish(); the goldens force-enable each rule to prove its
+# behaviour independent of the live flag.
+
+# 1. Article selection — a/an by the following word's phonetic onset. The live
+#    defect this fixes: the assert echo "every module is a artifact" -> "an
+#    artifact". Reads the next word (whether in-span or the leading token of the
+#    following protected span); refuses at a boundary it cannot read safely.
+[[rule]]
+id = "article-selection"
+kind = "article"
+enabled = true
+registers = []            # [] = every register
+description = "a/an agreement with the following word's phonetic onset"
+# Spelling-vowel words that begin with a CONSONANT sound (take 'a').
+consonant_sound_vowels = ["uni", "use", "user", "usa", "usu", "ubi", "eu", "ewe", "one", "once"]
+# Spelling-consonant words that begin with a VOWEL sound (take 'an'): silent h.
+vowel_sound_consonants = ["hour", "honest", "honour", "honor", "heir", "herb"]
+
+# 2. Subject–verb agreement — an existential copula agrees with the count that
+#    follows it ("there is 3 classes" -> "there are 3 classes"; "there are 1
+#    class" -> "there is 1 class"). Structure-driven: the plurality is READ from
+#    the following number span's value (or a protected span's explicit `plural`
+#    flag), never guessed. Neutral on already-correct agreement.
+[[rule]]
+id = "subject-verb-agreement"
+kind = "agreement"
+enabled = true    # LIVE (cycle 005) — structure-driven existential agreement, byte-stable when neutral
+registers = []
+description = "existential copula agrees with the following count/plurality"
+singular = ["is", "was", "has"]
+plural = ["are", "were", "have"]
+
+# 3. Sentence capitalisation — capitalise the first alphabetic character of a
+#    sentence-initial prose span. Never fires when the answer opens on a
+#    protected span (a path/entity opener is left exactly as grounded).
+[[rule]]
+id = "sentence-capitalisation"
+kind = "capitalise"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "capitalise the first alphabetic of a prose-initial span"
+
+# 4. List punctuation — a series joined by repeated " and " connectives becomes
+#    a comma series with a single terminal conjunction ("a and b and c" -> "a, b
+#    and c"). Operates ONLY on the prose connective spans, never the entity spans
+#    they join; a two-item list ("a and b") is already correct and untouched.
+[[rule]]
+id = "list-punctuation"
+kind = "list"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "repeated 'and' joins in a 3+ item series become a comma series"
+connective = " and "
+separator = ", "
+
+# 5. Terminal punctuation — exactly one sentence-final stop: a run of 2+ trailing
+#    stops in the final prose span collapses to one ("done.." -> "done."). Adds
+#    nothing where a fragment/list answer legitimately ends without a stop.
+[[rule]]
+id = "terminal-punctuation"
+kind = "terminal"
+enabled = true    # LIVE (cycle 005) — pure defect fix, narrowest blast radius (trailing doubled stop)
+registers = []
+description = "collapse a run of trailing sentence stops to a single stop"
+stops = [".", "!", "?"]

package/data/templates/responses.jsonl

@@ -53,3 +53,16 @@
 {"id":"nudge-precision","class":"nudge","register":"friendly","template":"The closer you get to a shape like \"{example}\", the sharper my answer gets."}
 {"id":"nudge-commands","class":"nudge","register":"friendly","template":"If prose fails you, the slash commands always work — try {command}."}
 {"id":"nudge-narrower","class":"nudge","register":"friendly","template":"That matched {count} things — too many to be useful. Narrow it with a module or class name."}
+{"id":"conversational-greeting","class":"conversational","register":"friendly","template":"Hi. Ask me about this codebase — imports, calls, definitions, history — or /help."}
+{"id":"conversational-greeting-hello-there","class":"conversational","register":"friendly","template":"Hello there. (A hollow voice says, \"fool.\") Ask me about this codebase, or /help."}
+{"id":"conversational-greeting-good-morning","class":"conversational","register":"friendly","template":"Good morning. Ask me about this codebase, or /help."}
+{"id":"conversational-greeting-good-afternoon","class":"conversational","register":"friendly","template":"Good afternoon. Ask me about this codebase, or /help."}
+{"id":"conversational-greeting-good-evening","class":"conversational","register":"friendly","template":"Good evening. Ask me about this codebase, or /help."}
+{"id":"conversational-thanks","class":"conversational","register":"friendly","template":"Any time. Ask another, or /help for what I can do."}
+{"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
+{"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import walk.mjs\n  what calls buildContextBundle\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
+{"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
+{"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
+{"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
+{"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}
+{"id":"technical-ratio","class":"count","register":"technical","template":"{subject} sustains a ratio of {count} {noun} per {unit}, placing it in the upper band for projects of comparable {scope} ({provenance})."}

package/package.json

@@ -1,12 +1,38 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
+  "keywords": [
+    "chatbot",
+    "no-llm",
+    "offline",
+    "deterministic",
+    "eliza",
+    "parry",
+    "nlp",
+    "wink-nlp",
+    "owl",
+    "rdf",
+    "ontology",
+    "controlled-natural-language",
+    "ace",
+    "knowledge-graph",
+    "provenance",
+    "code-navigation",
+    "cli"
+  ],
   "license": "MPL-2.0",
   "author": "Polycode Limited",
   "homepage": "https://polycode-projects.gitlab.io/the-mechanical-code-talker/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/polycode-projects/the-mechanical-code-talker.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/polycode-projects/the-mechanical-code-talker/-/issues"
+  },
   "engines": {
     "node": ">=24"
   },
@@ -47,7 +73,9 @@
     "test": "node --test \"test/**/*.test.mjs\"",
     "chat": "node bin/tmct.mjs",
     "chatbench:run": "node chatbench/run.mjs",
-    "chatbench:judge": "node chatbench/judge.mjs"
+    "chatbench:judge": "node chatbench/judge.mjs",
+    "audit": "npm audit --audit-level=high",
+    "audit:fix": "npm audit fix"
   },
   "devDependencies": {
     "ink-testing-library": "^4.0.0"

package/src/ask-nlp.mjs

@@ -9,13 +9,13 @@
 // the bounded edit-distance tier still work, browser and Node alike). Keeping the
 // ~1MB CJS model out of the page is the point of the split.
 //
-// wink-nlp and wink-eng-lite-web-model are CJS — loaded via createRequire, the
-// same Node-module-resolution approach viz.mjs uses to locate cytoscape (resolve
-// through the module system, never a guessed path). The require happens lazily on
-// first use and failure is cached as null: a checkout without the optional deps
-// installed answers exactly like the browser bundle, it never throws.
+// wink-nlp and wink-eng-lite-web-model are loaded through the shared leaf loader
+// src/wink-model.mjs (Node `createRequire` fallback + a browser registration seam),
+// so this file no longer carries its own Node-only load block. The load happens
+// lazily on first use and failure is cached as null: a checkout without the optional
+// deps installed answers exactly like the browser bundle, it never throws.
 
-import { createRequire } from "node:module";
+import { winkInstance } from "./wink-model.mjs";
 
 let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
 
@@ -25,10 +25,8 @@ let cached; // undefined = not tried yet; null = unavailable (tried once, honest
 export function nlpAdapter() {
   if (cached !== undefined) return cached;
   try {
-    const require = createRequire(import.meta.url);
-    const winkNLP = require("wink-nlp");
-    const model = require("wink-eng-lite-web-model");
-    const nlp = winkNLP(model);
+    const nlp = winkInstance();
+    if (!nlp) { cached = null; return cached; }
     const its = nlp.its;
     cached = {
       /** Lowercase lemma of a single token ("imported" -> "import"); the word

package/src/ask-vocab.mjs

@@ -220,6 +220,28 @@ export const MODIFIER_TO_KIND = Object.freeze({
   transitively: "transitive", indirectly: "transitive",
 });
 
+// ---- reversible-passive participles (Cycle 6, PLAN_CYCLE_4.md) — past participles ->
+// relation kind, for the agent-marked passive "X is <participle> by Y". Kept SEPARATE
+// from VERB_TO_KIND on purpose: these forms are NOT standalone active verbs in this
+// grammar ("defined" belongs to the multi-word "is defined in" and to the WHERE_MARKERS
+// location routing; bare "inherited" has no active key), so folding them into
+// VERB_TO_KIND would silently re-route "where is X defined" and other queries. This
+// table is consulted ONLY by the keyword strategy's passive path, which has already
+// confirmed a passive auxiliary AND an agent-marking "by" — so an active query is never
+// affected. Most common participles ("imported"/"tested"/"called"/"covered") already
+// reach VERB_TO_KIND via the lemma tier; this table backfills the two families the lemma
+// tier can't (defines/inherits) plus the obvious siblings, so the passive works
+// adapter-free too. ----
+export const PASSIVE_PARTICIPLE_TO_KIND = Object.freeze({
+  imported: "imports", called: "calls", used: "uses",
+  tested: "tests", covered: "tests", verified: "tests", exercised: "tests", checked: "tests",
+  defined: "defines", declared: "defines",
+  inherited: "inherits", extended: "inherits", subclassed: "inherits",
+  contained: "contains",
+  exported: "reexports", "re-exported": "reexports", exposed: "reexports",
+  touched: "touches", changed: "touches", modified: "touches", edited: "touches", updated: "touches",
+});
+
 // ---- §3.5 normalization — contractions/informal spellings that would otherwise
 // block a match, expanded BEFORE parsing (BOTH the anchored-template strategy
 // and the independent keyword-spotting strategy see the same normalized text —

package/src/ask.mjs

@@ -51,7 +51,7 @@ import {
 // grammar, split out of this file: normalization pre-pass, the two parsing
 // strategies, and the bounded-fuzzy service. Re-exported below where existing
 // callers/tests import them from here.
-import { normalizeQuery, applyNegationFrames, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { normalizeQuery, applyNegationFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -244,7 +244,9 @@ function parseSimpleClause(text, nlp) {
 function parseComposite(text, nlp) {
   const w = splitWords(text);
   const lc = w.map((x) => x.toLowerCase());
-  return parseAnaphora(w, lc, nlp)
+  return parseNegation(text, nlp, 0)
+    || parseForwardNegation(w, lc, nlp)
+    || parseAnaphora(w, lc, nlp)
     || parseAggregate(w, lc, nlp)
     || parseSuperlative(w, lc, nlp)
     || parseList(w, lc, nlp, 0)
@@ -252,11 +254,129 @@ function parseComposite(text, nlp) {
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
 
+// B1 NEGATION (Cycle 5, PLAN_CYCLE_4.md) — the SET COMPLEMENT. "which X do not <verb>
+// Y" / "X that don't <verb> Y" / "modules not importing Y" / "which X are not
+// <qualifier>" compiles to allOfClass(kind) DIFFERENCE (the positive result set),
+// reusing the EXISTING machinery: evalBoolean already folds a "difference" atom, and
+// the allOfClass node is a ready-made bounded universe of a kind. The only new work is
+// recognizing the negation marker (matchNegationSet, normalize.mjs) and assembling the
+// boolean-difference AST — no new traversal primitive. Regression guards, all tested:
+//   (1) honest-empty stays honest — an EMPTY complement ("which functions are not
+//       exported", where the only function is exported) renders the standard honest
+//       "nothing matches" miss, never invents a member and never re-trips the literal-
+//       'not' trap (the "not" is consumed here, so it can't leak into an object term);
+//   (2) BOUNDED UNIVERSE only — the universe is the queried kind within the loaded
+//       graph; the "Change" pseudo-type (ask-vocab.mjs) is a wildcard, not a stored
+//       enumerable class, so a complement over "changes" is REFUSED honestly rather
+//       than answered over an empty universe;
+//   (3) active-voice/positive queries are untouched — parseNegation returns null unless
+//       matchNegationSet finds an explicit set-negation marker.
+function complementAst(entityType, diffAtom) {
+  return {
+    node: "boolean",
+    entityType,
+    atoms: [
+      { op: "seed", kind: "set", ast: { node: "allOfClass", entityType } },
+      diffAtom,
+    ],
+  };
+}
+
+function parseNegation(text, nlp, depth = 0) {
+  const neg = matchNegationSet(text);
+  if (!neg) return null;                             // no set-negation marker → not this shape
+  const noun = entityNoun(neg.entWord);
+  // a set complement needs a CONCRETE, enumerable kind. A placeholder ("things") has no
+  // bounded universe; the "Change" pseudo-type is a wildcard over the touch traversal,
+  // never a stored class, so its complement is ill-defined and must be refused honestly.
+  if (!noun || noun.placeholder || !noun.entityType) return null;
+  const entityType = noun.entityType;
+  if (entityType === "Change") {
+    return { node: "miss", reason: `"${neg.entWord}" isn't an enumerable kind — a set complement needs a concrete kind (functions, classes, modules, …)` };
+  }
+  const predWords = splitWords(neg.predicate);
+  const predLc = predWords.map((x) => x.toLowerCase());
+  // (a) qualifier negation ("not tested" / "not exported"): difference the qualifier
+  // set off the class — equivalent to the negated qualifier, an honest empty when none.
+  if (predLc.length && predLc.every((x) => QUALIFIERS[x])) {
+    return complementAst(entityType, { op: "difference", kind: "qual", filters: predLc });
+  }
+  const vh = findPhrase(predLc, VERB_TO_KIND);
+  if (!vh) return { node: "miss", reason: "a negated set query needs a known relation verb (import, call, inherit from, test, …)" };
+  const objWords = predWords.filter((_, i) => (i < vh.start || i >= vh.end) && !STOPWORDS.has(predLc[i]) && predLc[i] !== "from");
+  // (b) existential object ("do not import anything" / "define nothing"): the complement
+  // is the class MINUS the subjects that have ANY edge of this kind.
+  if (!objWords.length) {
+    return complementAst(entityType, { op: "difference", kind: "set", ast: { node: "existsEdge", entityType, kind: vh.kind } });
+  }
+  // (c) concrete object ("do not import a.mjs"): the class MINUS the POSITIVE result
+  // set, parsed through the existing clause/relational machinery (never re-negating —
+  // the reconstructed positive text carries no "not").
+  const positive = parseSetPhrase(`which ${neg.entWord} ${neg.predicate}`, nlp, depth + 1);
+  if (!positive || positive.node === "miss") {
+    return { node: "miss", reason: (positive && positive.reason) || "the negated clause didn't parse" };
+  }
+  return complementAst(entityType, { op: "difference", kind: "set", ast: positive });
+}
+
+// B1 FORWARD NEGATION (Cycle 5, pron+neg) — the SUBJECT-side complement's mirror: "what
+// does[n't] <subj> <verb>" ("what doesn't it import", "what does app/lib/e.mjs not import")
+// is every individual of the verb's OBJECT grain that <subj> does NOT reach via that verb.
+// Distinct from parseNegation (which negates a queried KIND — "which modules do not import
+// X"): here the negation sits on a FORWARD clause whose subject is a named term or a focus
+// pronoun, so the universe is inferred from the verb's own edges (imports → Module) rather
+// than a stated kind noun. The subject is resolved LATE (at eval, through the same
+// contextId a plain "it" uses), so pronoun-binding composes with the complement for free.
+// Refused honestly (empty) when the verb's object grain is ambiguous or the subject can't
+// resolve — never a guess. Runs AFTER parseNegation, so the stated-kind form is unaffected.
+const FWD_NEG_FRAME = new Set(["what", "which", "thing", "things", "one", "ones", "stuff"]);
+function parseForwardNegation(w, lc, nlp) {
+  let i = 0;
+  while (i < lc.length && FWD_NEG_FRAME.has(lc[i])) i += 1;
+  if (!["do", "does", "did"].includes(lc[i])) return null;   // need the auxiliary lead
+  i += 1;
+  const rest = w.slice(i);
+  const restLc = lc.slice(i);
+  const notIdx = restLc.indexOf("not");
+  if (notIdx < 0) return null;                                // no negation → not this shape
+  const vh = findPhrase(restLc, VERB_TO_KIND);
+  if (!vh) return null;                                       // no relation verb → not this shape
+  // the subject term is whatever survives after removing "not", the verb phrase, "from",
+  // and question scaffolding — a bare pronoun "it" (not a stopword) survives and binds to
+  // the focus at eval time; a named module/symbol survives and resolves directly.
+  const subjTokens = rest.filter((_, j) => j !== notIdx && (j < vh.start || j >= vh.end)
+    && restLc[j] !== "from" && !STOPWORDS.has(restLc[j]));
+  const subjectTerm = subjTokens.join(" ").trim();
+  if (!subjectTerm) return null;
+  return { node: "forwardComplement", kind: vh.kind, subjectTerm };
+}
+
+/** The single OBJECT class a forward relation kind points at across the loaded graph
+ *  (imports → Module), or null when its objects span more than one class (an ambiguous
+ *  grain the complement's universe can't be pinned to). Ext: endpoints have no individual,
+ *  so they don't muddy the class vote. Used by the forwardComplement evaluator to bound
+ *  the universe it differences the positive forward set out of. */
+function kindObjectClass(graph, kind) {
+  const classes = new Set();
+  for (const k of kindsFor(kind)) {
+    for (const e of edgesOfKind(graph, k)) {
+      const o = graph.byId.get(e.object);
+      if (o && o.class) classes.add(o.class);
+    }
+  }
+  return classes.size === 1 ? [...classes][0] : null;
+}
+
 /** A set-producing sub-expression (used for nested inner clauses, boolean branches,
  *  and count restrictors): nested first, then the relational/qualifier/boolean
  *  parser, then a bare simple clause. Carries `depth` for the nesting cap. */
 function parseSetPhrase(text, nlp, depth) {
   if (depth > MAX_COMPOSE_DEPTH) return { node: "miss", reason: "too deep to resolve" };
+  // a set-negation clause can appear as a count restrictor ("how many classes are not
+  // tested"), a list filter, or a boolean branch — try the complement frame first so
+  // those compositions get the bounded-complement for free.
+  const negated = parseNegation(text, nlp, depth);
+  if (negated) return negated;
   const w = splitWords(text);
   const lc = w.map((x) => x.toLowerCase());
   const nested = parseNested(w, lc, nlp, depth);
@@ -302,12 +422,21 @@ function parseNested(w, lc, nlp, depth) {
  *  uncompilable), or null. */
 function parseAnaphora(w, lc, nlp) {
   let p = -1;
+  let viaOf = false;
   for (let i = 1; i < lc.length; i += 1) {
-    if (ANAPHORA_TRIGGERS.includes(lc[i]) && lc[i - 1] === "of") { p = i; break; }
+    if (!ANAPHORA_TRIGGERS.includes(lc[i])) continue;
+    if (lc[i - 1] === "of") { p = i; viaOf = true; break; } // "how many of those", "which of them"
+    // BARE anaphoric pronoun as the FINAL word, directly after a count/list trigger
+    // ("count them", "count those", "list them") — the discourse-reference count/list over
+    // the previous answer with no "of" (Cycle 5, disc+count). Pinned to the terminal
+    // position so a mid-sentence "these"/"those" used as a determiner ("list these
+    // functions") is left for the ordinary list/clause path, not seized as an anaphor.
+    const headSoFar = lc.slice(0, i).join(" ");
+    if (i === lc.length - 1 && (AGGREGATE_TRIGGERS.includes(headSoFar) || LIST_TRIGGERS.includes(headSoFar))) { p = i; break; }
   }
   if (p < 0) return null;
-  const head = lc.slice(0, p - 1).join(" ");
-  const mode = /^(how many|how much|count)\b/.test(head) ? "count" : "list";
+  const head = (viaOf ? lc.slice(0, p - 1) : lc.slice(0, p)).join(" ");
+  const mode = AGGREGATE_TRIGGERS.includes(head) || /^(how many|how much|count|number|quantity|total)\b/.test(head) ? "count" : "list";
   const filter = parsePredicateFilter(w.slice(p + 1), nlp);
   if (filter === undefined) return { node: "miss", reason: "the follow-up filter didn't parse" };
   return { node: "anaphora", mode, filter };
@@ -694,6 +823,23 @@ 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);
+    // 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".
+    case "existsEdge": {
+      const subs = new Set(kindsFor(ast.kind).flatMap((k) => edgesOfKind(graph, k)).map((e) => e.subject));
+      return graph.individuals.filter((i) => subs.has(i.id) && (!ast.entityType || i.class === ast.entityType));
+    }
+    // forward complement: the verb's object-grain universe MINUS what the (late-resolved,
+    // focus-bindable) subject reaches via that verb — "what doesn't it import".
+    case "forwardComplement": {
+      const r = resolveTermOrContext(graph, ast.subjectTerm, opts && opts.contextId);
+      if (!r.match) return [];                              // unresolved subject / focus-less pronoun → honest empty
+      const universeType = kindObjectClass(graph, ast.kind);
+      if (!universeType) return [];                         // ambiguous object grain → refuse honestly
+      const positive = new Set(forwardOverSet(graph, ast.kind, new Set([r.match.id])).map((x) => x.id));
+      return graph.individuals.filter((i) => i.class === universeType && !positive.has(i.id));
+    }
     case "reverseSet": {
       const ids = new Set(evalSet(graph, ast.inner, opts).map((i) => i.id));
       return reverseOverSet(graph, ast.kind, ast.entityType, ids);
@@ -1323,11 +1469,23 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
     };
   }
 
-  // reverse: "which <entityType> R <objMatch>"
+  // reverse: "which <entityType> R <objMatch>". GRAIN-AWARE (Cycle 5, lever 3): a kind
+  // that carries a symbol-grain sibling reads off the SIBLING when a fine SUBJECT grain
+  // was asked for ("which functions call X" → callsSymbol). Additionally, for `touches`
+  // specifically, when the RESOLVED OBJECT is itself a fine symbol the answer MUST read off
+  // touchesSymbol: touches is Commit→Module (module-coarse) and can NEVER point at a
+  // symbol, so "how many commits touched Widget.render" used to scan the module-grain
+  // edges and return a false 0 — the count belongs at symbol grain. This object-driven
+  // switch is scoped to touches on purpose: calls/callsSymbol already resolve a fine
+  // object through the fine-entityType branch, and a null-entityType "what calls <fn>"
+  // deliberately keeps its module-coarse `calls` receipt (the honest-empty showcase pins
+  // it), so widening the switch to calls would silently change that answer.
   const symbolKind = SYMBOL_GRAIN_SIBLING[kind];
-  if (symbolKind && FINE_ENTITY_TYPES.has(entityType)) {
+  const objIsTouchedSymbol = kind === "touches" && !!(objMatch.class && FINE_ENTITY_TYPES.has(objMatch.class));
+  if (symbolKind && (FINE_ENTITY_TYPES.has(entityType) || objIsTouchedSymbol)) {
     const edges = edgesOfKind(graph, symbolKind).filter((e) => e.object === objMatch.id);
-    const matches = edges.map((e) => graph.byId.get(e.subject)).filter((i) => i && i.class === entityType);
+    const subjects = uniqueById(edges.map((e) => graph.byId.get(e.subject)).filter(Boolean));
+    const matches = (!entityType || entityType === "Change") ? subjects : subjects.filter((i) => i.class === entityType);
     return { matches, objMatch, candidates, traversal: `${symbolKind} edges where object = ${objMatch.label}`, ambiguous, matchedVia };
   }
 
@@ -1584,6 +1742,10 @@ function renderCore(parsed, result) {
         miss: true, ambiguous: false,
       };
     }
+    // NOTE (Cycle 5): a voice-nit rephrasing ("that directly <verb>") was reverted —
+    // the frozen v1 cases.jsonl pins the "whose module directly <verb>s X" wording
+    // (hm-empty-result-calls / tf-wat-calls / ns-wondering), and the case set is
+    // append-only/sacred mid-arc, so the honest-miss phrasing stays as-is.
     const entityWord = nounFor(parsed.entityType || "Module", 2);
     return {
       content: `No ${entityWord} found whose module directly ${verbFor(parsed.kind)} ${parsed.object}. (traversal: ${result.traversal || "no traversal resolved"})`,