@polycode-projects/the-mechanical-code-talker 2.5.0 → 2.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.5.0",
+  "version": "2.5.3",
   "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.",
@@ -63,7 +63,6 @@
     "!src/domain/schemaorg/turtle.mjs",
     "!src/domain/version-stamp.mjs",
     "README.md",
-    "ROADMAP.md",
     "LICENSE",
     "corpus/",
     "!corpus/wordnet/generate.mjs",
@@ -133,19 +132,24 @@
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
     "demo:build": "node scripts/build-demo-site.mjs",
+    "roll": "node scripts/roll.mjs",
     "build:ask-bundle": "node scripts/build-ask-bundle.mjs",
+    "build:chat-bundle": "node scripts/build-chat-bundle.mjs",
+    "build:chat-seed": "node scripts/build-chat-seed.mjs",
     "build:demo-graph": "node scripts/build-demo-graph.mjs",
+    "build:demo-pack": "node scripts/build-demo-pack.mjs",
     "build:demo-memory": "node scripts/build-demo-memory.mjs",
     "gen:tool-docs": "node scripts/generate-tool-docs.mjs",
     "gen:collisions": "node scripts/generate-real-word-collisions.mjs",
     "gen:prose-corpus": "node scripts/fetch-prose-corpus.mjs",
+    "gen:reference-pack": "node scripts/fetch-reference-pack.mjs",
     "gen:variants": "node scripts/generate-template-variants.mjs",
     "extract": "node bin/tmct.mjs extract",
     "extract:facts": "node bin/tmct.mjs extract"
   },
   "devDependencies": {
-    "esbuild": "^0.28.1",
-    "ink-testing-library": "^4.0.0",
+    "esbuild": "0.28.1",
+    "ink-testing-library": "4.0.0",
     "playwright": "1.61.1",
     "publint": "0.3.21",
     "yaml": "2.9.0"

package/src/adapters/corpus/reference-pack.mjs

@@ -0,0 +1,107 @@
+// corpus/reference-pack.mjs — lazy, failure-tolerated loader for the shipped
+// reference pack (corpus/reference/): a gzipped term index consulted first,
+// then exactly one gzipped JSONL shard per hit. Nothing here ever throws at a
+// caller — an absent, truncated or corrupt pack reads as null, and a null is
+// the ordinary honest miss.
+//
+// The provider seam: registerReferencePackProvider swaps the whole lookup
+// behind one async `{ lookup(normTerm) }` contract. It exists because the
+// browser demo cannot read this filesystem layout — the web surface registers
+// a fetch-backed provider over public/reference-pack/ instead, and chat code
+// never knows which one it is talking to. No provider registered = the fs
+// loader below.
+
+import { readFileSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { isReferenceArticleRow, isReferenceIndexEntry } from "../../domain/reference-pack.mjs";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+/** The pack directory: TMCT_REFERENCE_PACK_DIR when set, else the package's
+ *  own corpus/reference/. */
+export function referencePackDir(env = process.env) {
+  return env?.TMCT_REFERENCE_PACK_DIR || join(PKG_ROOT, "corpus", "reference");
+}
+
+const indexCacheByDir = new Map();   // dir -> { term: {s, t, r} } | null
+const shardCacheByKey = new Map();   // `${dir}\0${shard}` -> Map(term -> row) | null
+
+/** Drop every cached index/shard — for tests that mutate a pack dir. */
+export function clearReferencePackCache() {
+  indexCacheByDir.clear();
+  shardCacheByKey.clear();
+}
+
+function readGunzipped(file) {
+  try {
+    return gunzipSync(readFileSync(file));
+  } catch {
+    return null;
+  }
+}
+
+/** The pack's term index, lazily read and cached per dir; null (cached) when
+ *  the pack is absent or unreadable. Never throws. */
+export function loadReferenceIndex(dir) {
+  if (indexCacheByDir.has(dir)) return indexCacheByDir.get(dir);
+  let index = null;
+  const body = readGunzipped(join(dir, "index.json.gz"));
+  if (body) {
+    try {
+      const parsed = JSON.parse(body.toString("utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) index = parsed;
+    } catch { /* tolerated: a corrupt index is an absent pack */ }
+  }
+  indexCacheByDir.set(dir, index);
+  return index;
+}
+
+function loadShard(dir, shardName) {
+  const key = `${dir}\0${shardName}`;
+  if (shardCacheByKey.has(key)) return shardCacheByKey.get(key);
+  let rows = null;
+  const body = readGunzipped(join(dir, "shards", `${shardName}.jsonl.gz`));
+  if (body) {
+    rows = new Map();
+    for (const line of body.toString("utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (isReferenceArticleRow(row)) rows.set(row.term, row);
+      } catch { /* tolerated: a bad line loses one row, not the shard */ }
+    }
+  }
+  shardCacheByKey.set(key, rows);
+  return rows;
+}
+
+/** One article by its normalised term: index hit -> the one shard the index
+ *  names (cached) -> the row. Null on an index miss, so an unknown term never
+ *  costs a shard read. Never throws. */
+export function loadReferenceArticle(dir, term) {
+  const index = loadReferenceIndex(dir);
+  if (!index) return null;
+  const entry = index[String(term ?? "")];
+  if (!isReferenceIndexEntry(entry)) return null;
+  const rows = loadShard(dir, entry.s);
+  return rows?.get(entry.t) ?? null;
+}
+
+const fsProvider = {
+  lookup: async (normTerm) => loadReferenceArticle(referencePackDir(), normTerm),
+};
+
+let registeredProvider = null;
+
+/** Swap the pack lookup: provider = { lookup: async (normTerm) => row|null }.
+ *  Pass null to restore the default fs loader. */
+export function registerReferencePackProvider(provider) {
+  registeredProvider = provider && typeof provider.lookup === "function" ? provider : null;
+}
+
+/** The active provider — the registered one, else the lazy fs loader. */
+export function getReferencePackProvider() {
+  return registeredProvider ?? fsProvider;
+}

package/src/adapters/memory/core.mjs

@@ -79,6 +79,7 @@ const MEMORY_VOCABULARY = [
   { prop: "rdf:object", note: "reified fact: the triple's object term" },
   { prop: "mgx:factProvenance", note: "LEGACY COMPAT SHIM: the ' | '-joined provenance tag string a fact came from; the source-of-truth is now the mgx:statedBy edges derived from it" },
   { prop: "mgx:factQuantifier", note: "OPTIONAL: the quantifier word a plural class-membership teach used ('every'/'some'/'a few'), for literal recall by 'how many Xs are Ys' — never real cardinality counting" },
+  { prop: "mgx:factJustification", note: "an entailed Fact's supporting premise fact ids: ' | '-separated environments, one space-separated premise-id list per independent derivation, capped by syllogise's maxEnvironments knob; a value with no ' | ' is a single environment" },
   { prop: "mgx:ruleName", note: "a taught Rule's own name (e.g. 'grandparent') — the query-dispatcher's lookup key, PLAN_TAUGHT_RELATIONS.md §2/§3" },
   { prop: "mgx:ruleKind", note: "a taught Rule's SHAPE tag — the closed vocabulary compose2 | filter | recursive (structural, like 'Fact'/'Rule' themselves, never a domain word)" },
   { prop: "mgx:ruleBase1", note: "compose2: the first hop's base relation name; filter: the base rule/relation being filtered (same 'base relation' role in both kinds, so the name is shared)" },
@@ -91,7 +92,7 @@ const MEMORY_VOCABULARY = [
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
   { prop: CANONICALISED_FROM_PROP, predicate: "canonicalisedFrom", note: "subPropertyOf derivedFrom: a canonical Fact cleaned from a raw Block/Source, never replacing it" },
-  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | corpusWeak | extracted | web | entailed (the trust-prior key)" },
+  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | corpusWeak | reference | extracted | web | entailed (the trust-prior key)" },
   { prop: "mgx:sourceUrl", note: "a web Source's URL" },
   { prop: "mgx:sourceRule", note: "an entailed Source's rule id" },
   { prop: "mgx:sourceReliability", note: "actor-level (session-scoped) trust nudge in [0.5,1.5], neutral 1.0 when absent — materialised by recomputeSourceReliability from a session's asserted-vs-contradicted track record (memory/trust.mjs's sessionReliabilityFrom); folds into computeTrust's per-source prior" },
@@ -576,7 +577,14 @@ function migrateLegacyFactIds(payload) {
   for (const ind of payload.individuals) {
     if (Array.isArray(ind?.derived_from) && ind.derived_from.length) ind.derived_from = ind.derived_from.map(remapId);
     const just = (ind?.attributes || []).find((a) => a?.prop === "mgx:factJustification");
-    if (just?.value) just.value = just.value.split(" ").filter(Boolean).map(remapId).join(" ");
+    if (just?.value) {
+      // Environment-aware: the value is ' | '-separated premise-id lists, one
+      // per independent derivation — remap the ids inside each, keep the shape.
+      just.value = just.value.split(" | ")
+        .map((env) => env.split(" ").filter(Boolean).map(remapId).join(" "))
+        .filter(Boolean)
+        .join(" | ");
+    }
   }
   return payload;
 }
@@ -591,6 +599,43 @@ async function persistMemory(dir, payload) {
   await atomicWriteJson(memoryGraphFile(dir), payload);
 }
 
+// ---- Syllogise watermark state: a small backend-dispatched sidecar ---------
+// { version, factIds, completedAt } — the fact ids at the end of the last
+// COMPLETE syllogise pass. syllogise() diffs it against the live store to
+// pick delta or full evaluation; a missing/removed-id state means full.
+
+export const SYLLOGISE_STATE_REL = join(MEMORY_DIR_REL, "syllogise-state.json");
+const SQLITE_SYLLOGISE_STATE_KEY = "syllogiseState";
+
+/** Load the syllogise watermark for a repo dir OR a Backend B/C handle.
+ *  Null when no complete pass has recorded one. */
+export async function loadSyllogiseState(dir) {
+  if (isMemoryHandle(dir)) return dir.syllogiseState ? structuredClone(dir.syllogiseState) : null;
+  if (isSqliteHandle(dir)) {
+    const row = dir.db.prepare("SELECT v FROM meta WHERE k = ?").get(SQLITE_SYLLOGISE_STATE_KEY);
+    return row?.v ? JSON.parse(row.v) : null;
+  }
+  try {
+    return JSON.parse(await readFile(join(dir, SYLLOGISE_STATE_REL), "utf8"));
+  } catch (e) {
+    if (e?.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+/** Persist the syllogise watermark — atomic file write (Backend A), a cloned
+ *  handle field (Backend B), or a meta-table row (Backend C). */
+export async function saveSyllogiseState(dir, state) {
+  if (isMemoryHandle(dir)) { dir.syllogiseState = structuredClone(state); return; }
+  if (isSqliteHandle(dir)) {
+    dir.db.prepare("INSERT OR REPLACE INTO meta(k, v) VALUES (?, ?)").run(SQLITE_SYLLOGISE_STATE_KEY, JSON.stringify(state));
+    return;
+  }
+  const file = join(dir, SYLLOGISE_STATE_REL);
+  await mkdir(dirname(file), { recursive: true });
+  await atomicWriteJson(file, state);
+}
+
 /** Fresh read -> mutate -> atomic write. Serialized per call; every public
  *  append goes through here, including the lazy legacy-provenance migration
  *  and actor-level Source reliability recompute. `fn` may be async (the
@@ -667,6 +712,9 @@ function sourceIdFor(desc) {
     case "teach": return { id: desc.sessionId ? `${TEACH_SOURCE_ID}:${desc.sessionId}` : TEACH_SOURCE_ID, type: "teach" };
     case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
     case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
+    // One Source per pack article (the @revid stays in the article segment),
+    // so two facts from the same article corroborate nothing extra.
+    case "reference": return { id: `src:reference:${desc.pack}:${desc.article}`, type: "reference" };
     // One Source per source-file basename, not per extraction run.
     case "extracted": return { id: `src:extracted:${desc.name}`, type: "extracted" };
     case "web": return { id: `src:learned:web:${fnv1aHex(String(desc.url || ""))}`, type: "web", url: String(desc.url || "") };
@@ -688,6 +736,7 @@ const PROV_CLASS_BY_SOURCE_TYPE = Object.freeze({
   provider: { subClass: "tmct:AgentSource", prov: "prov:Agent" },
   corpus: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   corpusWeak: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
+  reference: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   web: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   extracted: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   entailed: { subClass: "tmct:ActivitySource", prov: "prov:Activity" },
@@ -1074,13 +1123,38 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
   return { id };
 }
 
+/** Normalize appendFacts' `justification` input — either a flat premise-id
+ *  list (one derivation) or a list of premise-id lists (one per independent
+ *  derivation) — into the string[][] environment shape: empty/non-string ids
+ *  dropped, environments deduped by canonical key (sorted-id join) with
+ *  within-environment citation order preserved. Undefined when nothing
+ *  storable remains. */
+function normalizeJustificationEnvironments(justification) {
+  if (!Array.isArray(justification)) return undefined;
+  const rawEnvs = justification.some(Array.isArray)
+    ? justification.filter(Array.isArray)
+    : [justification];
+  const envs = [];
+  const seen = new Set();
+  for (const raw of rawEnvs) {
+    const env = raw.filter((id) => typeof id === "string" && id);
+    if (!env.length) continue;
+    const key = [...env].sort().join(" ");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    envs.push(env);
+  }
+  return envs.length ? envs : undefined;
+}
+
 /** Batch append of grammar/corpus-derived triples — ONE read-modify-write for
  *  a whole seed, collapsing looping appendFact's O(N²) I/O to a single
  *  mutate (same resulting ids/provenance/trust). Malformed facts are skipped,
  *  not thrown. Optional per-fact `premiseTrusts`/`ruleConfidence` (batched
- *  entailed-hook passthrough) and `justification` (premise fact ids, stored
- *  as mgx:factJustification, last-write-wins). Returns
- *  { ids, appended, skipped }. */
+ *  entailed-hook passthrough) and `justification` (premise fact ids — a flat
+ *  list, or a list of lists for multiple independent derivations — stored as
+ *  mgx:factJustification's ' | '-separated environments, last-write-wins).
+ *  Returns { ids, appended, skipped }. */
 export async function appendFacts(dir, facts) {
   const prepared = [];
   let skipped = 0;
@@ -1099,7 +1173,7 @@ export async function appendFacts(dir, facts) {
       quantifier: normText(f?.quantifier),
       premiseTrusts: Array.isArray(f?.premiseTrusts) ? f.premiseTrusts : undefined,
       ruleConfidence: typeof f?.ruleConfidence === "number" ? f.ruleConfidence : undefined,
-      justification: Array.isArray(f?.justification) ? f.justification.filter(Boolean) : undefined,
+      environments: normalizeJustificationEnvironments(f?.justification),
     });
   }
   const ids = [];
@@ -1138,7 +1212,7 @@ export async function appendFacts(dir, facts) {
           ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
           ...(f.tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: f.tokens.join(" ") }] : []),
           ...(qVal ? [{ prop: "mgx:factQuantifier", key: "quantifier", value: qVal }] : []),
-          ...(f.justification && f.justification.length ? [{ prop: "mgx:factJustification", key: "justification", value: f.justification.join(" ") }] : []),
+          ...(f.environments ? [{ prop: "mgx:factJustification", key: "justification", value: f.environments.map((e) => e.join(" ")).join(" | ") }] : []),
         ],
       };
       // Upsert via the shared helper — O(1) via the index (Object.assign in
@@ -1545,6 +1619,24 @@ export function readFactRows(memory) {
       .map((id) => (sourcesById.get(id)?.attributes || []).find((a) => a?.prop === "mgx:sourceType")?.value)
       .filter(Boolean);
     const justificationRaw = get("justification");
+    // ' | '-separated environments, one premise-id list per independent
+    // derivation; a legacy value with no ' | ' parses as one environment.
+    const environments = [];
+    if (justificationRaw) {
+      for (const chunk of justificationRaw.split(" | ")) {
+        const env = chunk.split(" ").filter(Boolean);
+        if (env.length) environments.push(env);
+      }
+    }
+    const justification = [];
+    const seenPremise = new Set();
+    for (const env of environments) {
+      for (const id of env) {
+        if (seenPremise.has(id)) continue;
+        seenPremise.add(id);
+        justification.push(id);
+      }
+    }
     rows.push({
       id: ind.id,
       subject: get("subject"), predicate: get("predicate"), object: get("object"),
@@ -1552,9 +1644,11 @@ export function readFactRows(memory) {
       quantifier: get("quantifier"), // "" unless a plural class-membership teach set one
       sourceIds, sourceTypes,
       trust: Number((ind.attributes || []).find((a) => a?.prop === TRUST_SCORE_PROP)?.value) || 0,
-      // [] unless a rule persisted its premise fact ids (justification-tracking,
-      // scm-sco only today; see syllogise.mjs).
-      justification: justificationRaw ? justificationRaw.split(" ").filter(Boolean) : [],
+      // `environments`: every persisted premise set (empty unless entailed);
+      // `justification`: their deduped union in first-occurrence order, for
+      // readers that only need "which premises does this fact cite at all".
+      environments,
+      justification,
     });
   }
   return rows;

package/src/domain/ask.mjs

@@ -74,6 +74,7 @@ const FINE_CLASS_SIBLING = { Function: "Method", Method: "Function" };
 // + calls together).
 const KIND_UNIONS = { uses: ["imports", "calls", "callsSymbol"] };
 const kindsFor = (kind) => KIND_UNIONS[kind] || [kind];
+const SYMBOL_GRAIN_KINDS = new Set(Object.values(SYMBOL_GRAIN_SIBLING));
 
 const OVERFLOW_CAP = 12;
 
@@ -377,9 +378,17 @@ function classesForKinds(graph, kinds) {
 /** 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). Used by the forwardComplement
- *  evaluator to bound the universe it differences the positive forward set out of. */
+ *  evaluator to bound the universe it differences the positive forward set out of.
+ *
+ *  A union kind's symbol-grain member (callsSymbol) points at symbols by design —
+ *  the fine view, served by its own reverse branch. The union's canonical object
+ *  grain is defined by its coarse members, so the vote excludes the symbol-grain
+ *  siblings; without this "uses" collapses to null and a Class-resolved object
+ *  never up-refines to its containing module. */
 function kindObjectClass(graph, kind) {
-  const classes = classesForKinds(graph, kindsFor(kind));
+  const kinds = kindsFor(kind);
+  const coarse = kinds.filter((k) => !SYMBOL_GRAIN_KINDS.has(k));
+  const classes = classesForKinds(graph, coarse.length ? coarse : kinds);
   return classes.size === 1 ? [...classes][0] : null;
 }
 
@@ -886,7 +895,14 @@ function parseSuperlative(w, lc, nlp) {
     if (!entityType) return { node: "miss", reason: "a superlative needs an entity kind (module, class, function, …)" };
   }
   if (!metric) return { node: "miss", reason: "name what to rank by (imports, callers, methods, tests, or connections)" };
-  return { node: "superlative", entityType, metric, metricNoun, extreme: ext };
+  // A need/lack verb measures the ABSENCE of the metric, so it inverts the
+  // ranking direction: "what most needs a test" asks for the FEWEST tests,
+  // and answering the most-tested module is the exact inverse of the question.
+  const NEED_LACK_WORDS = ["needs", "need", "needing", "lacks", "lack", "lacking", "misses", "missing"];
+  const extreme = lc.some((x) => NEED_LACK_WORDS.includes(x))
+    ? (ext === "most" ? "fewest" : "most")
+    : ext;
+  return { node: "superlative", entityType, metric, metricNoun, extreme };
 }
 
 // Predicate-find: "find me the payment class" (trailing-type) or "find the
@@ -2536,9 +2552,27 @@ function unplacedTermWords(term, label) {
  *
  *  Tier 3 only: the prose and fuzzy tiers resolve BY not matching the label
  *  (doc-comment words, a typo'd spelling), and announce themselves in the
- *  answer where tier 3 says nothing. */
+ *  answer where tier 3 says nothing.
+ *
+ *  The AMBIGUOUS case is the same failure with several candidates instead of
+ *  one: a tie spread over candidates that ALL leave the same words unread is
+ *  not a real ambiguity between readings of the question — it is the question
+ *  not matching, several ways at once, and enumerating every candidate would
+ *  answer each of them to a question none of them is. A word placed by ANY
+ *  candidate keeps the honest ambiguity (that candidate may be the one meant). */
 function declineOnUnplacedWords(result, term) {
-  if (!result?.match || result.ambiguous || result.tier !== 3 || result.matchedVia) return result;
+  if (!result?.match || result.tier !== 3 || result.matchedVia) return result;
+  if (result.ambiguous) {
+    const pool = [result.match, ...(result.candidates || [])];
+    const shared = pool
+      .map((m) => new Set(unplacedTermWords(term, m.label)))
+      .reduce((acc, s) => acc.filter((w) => s.has(w)), unplacedTermWords(term, pool[0].label));
+    if (!shared.length) return result;
+    return {
+      match: null, candidates: [], tier: null, ambiguous: false,
+      unplacedWords: shared, nearestLabel: listJoin(pool.slice(0, 4).map((m) => m.label)),
+    };
+  }
   const unplaced = unplacedTermWords(term, result.match.label);
   if (!unplaced.length) return result;
   return {
@@ -2998,8 +3032,11 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
   // symbol-grain sibling reads off the sibling when a fine subject grain was
   // asked for, or when the resolved object is itself a fine symbol — the
   // module-coarse edge can never point at a function/method, so a bare "what
-  // calls fnAlpha" would otherwise return a false empty.
-  const symbolKind = SYMBOL_GRAIN_SIBLING[kind];
+  // calls fnAlpha" would otherwise return a false empty. A union kind's own
+  // symbol-grain member ("uses" carries callsSymbol) plays the same sibling
+  // role here, so "what uses <symbol>" walks the same grain ladder as "what
+  // calls <symbol>" instead of skipping it.
+  const symbolKind = SYMBOL_GRAIN_SIBLING[kind] || kindsFor(kind).find((k) => SYMBOL_GRAIN_KINDS.has(k)) || null;
   const objIsFineSymbol = !!(objMatch.class && FINE_ENTITY_TYPES.has(objMatch.class));
   if (symbolKind && (FINE_ENTITY_TYPES.has(entityType) || objIsFineSymbol)) {
     const edges = edgesOfKind(graph, symbolKind).filter((e) => e.object === objMatch.id);
@@ -3022,7 +3059,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     // rather than a confident-looking-but-wrong "nothing touched/calls it".
     // Not widened to Function/Method — symbol-level counting precision there
     // is a separate, deliberate guarantee this must not erode.
-    const upRefineEligible = (kind === "touches" || kind === "calls") && objMatch.class === "Class"
+    const upRefineEligible = (kind === "touches" || kind === "calls" || kind === "uses") && objMatch.class === "Class"
       && !edgesOfKind(graph, "contains").some((e) => e.subject === objMatch.id);
     const upRefineModule = upRefineEligible ? graph.byId.get(moduleIdOf(graph, objMatch) || "") : null;
     if (matches.length || !(upRefineEligible && upRefineModule)) {
@@ -3538,6 +3575,20 @@ function renderCore(parsed, result, graph) {
     // Forward: parsed.object is the given subject, not a search target, so it
     // gets its own subject-first phrasing rather than reverse's template.
     if (parsed.shape === "forward") {
+      // The index stores membership on either contains (Class -> member) or
+      // defines (Module -> symbol), and MEMBERSHIP_KINDS declares the two
+      // equivalent for a members-of question — so before reporting "no
+      // contains edges" for a subject whose members live on defines, the
+      // sibling kind is consulted over the SAME resolved subject. Adopted
+      // only on a real match; anything else keeps the honest empty.
+      if (MEMBERSHIP_KINDS.includes(parsed.kind) && graph && result.objMatch) {
+        for (const alt of MEMBERSHIP_KINDS) {
+          if (alt === parsed.kind) continue;
+          const altParsed = { ...parsed, kind: alt };
+          const altResult = traverse(graph, altParsed, { pinnedObjMatch: result.objMatch });
+          if (altResult?.matches?.length && !altResult.ambiguous) return renderCore(altParsed, altResult, graph);
+        }
+      }
       return {
         content: `${result.objMatch.label} has no ${verbFor(parsed.kind)} edges in the index.`,
         miss: true, ambiguous: false,
@@ -3636,6 +3687,12 @@ const CASCADE_FUZZY_TARGETS = [...new Set([
   ...TRIGGER_FUZZY_WORDS,
 ])].filter((wd) => /^[a-z]+$/.test(wd) && wd.length >= 4 && !STOPWORDS.has(wd));
 
+/** Real words that carry their own intent and are never a typo of the closed
+ *  vocabulary: the corrector must not rewrite them at all. "impact" sits two
+ *  edits from "import", and rewriting it answers the reverse question in the
+ *  asker's own words — an unrecognised impact phrasing must decline instead. */
+const CASCADE_FUZZY_REAL_WORDS = new Set(["impact", "impacts", "impacted"]);
+
 /** Unique within-bound fuzzy correction of `w` toward CASCADE_FUZZY_TARGETS,
  *  or null — a distance tie between two distinct targets is refused. The
  *  4-char floor holds on the word being corrected as well as on the targets:
@@ -3643,7 +3700,7 @@ const CASCADE_FUZZY_TARGETS = [...new Set([
  *  were never a typo of it ("old" -> "hold"), and the correction is announced
  *  as though the asker had typed it. */
 function fuzzyCascadeWord(w) {
-  if (w.length < 4) return null;
+  if (w.length < 4 || CASCADE_FUZZY_REAL_WORDS.has(w)) return null;
   const bound = fuzzyBound(w);
   let best = bound + 1; let hit = null; let tied = false;
   for (const target of CASCADE_FUZZY_TARGETS) {

package/src/domain/cli-verbs.mjs

@@ -104,10 +104,10 @@ export const CLI_VERBS = [
     mode: "syllogise",
     errorLabel: "syllogise",
     usage: "tmct syllogise [--repo <abs>]",
-    prose: ["speculative inference (offline maintenance job): forward-"],
+    prose: ["speculative inference (offline maintenance job): a deterministic"],
     flags: [
-      { flag: "[--depth <n>] [--budget <n>]", prose: ["chain the memory's rdfs:subClassOf closure, materialising"] },
-      { flag: "[--config <path>]", prose: ["bounded, low-trust, retractable entailed facts (never on the chat path)"] },
+      { flag: "[--depth <n>] [--budget <n>]", prose: ["forward-chaining materialisation over OWL 2 RL rule kernels"] },
+      { flag: "[--config <path>]", prose: ["(the classical syllogism among them), writing bounded, low-trust,", "retractable entailed facts (never on the chat path)"] },
     ],
   },
   {

package/src/domain/codegraph.mjs

@@ -362,6 +362,12 @@ export function impactClosure(graph, ind, { maxDepth = 8 } = {}) {
         if (!subjModId || !objModId) continue;
         const subjLabel = graph.byId.get(subjModId)?.label || subjModId;
         addDependent(objModId, subjModId, subjLabel, g.predicate);
+        // Keyed under the callee's SYMBOL id too: an impact query resolving a
+        // function name seeds the BFS from the symbol, and the module-coarse
+        // key above is invisible from there — the caller's module was a real
+        // dependent that read back as "no dependents found". Same-module
+        // calls stay skipped, mirroring the self-skip on the coarse key.
+        if (subjModId !== objModId) addDependent(e.object, subjModId, subjLabel, g.predicate);
       }
     } else if (kind === "tests") {
       for (const e of g.edges) {