@polycode-projects/the-mechanical-code-talker 0.4.0 → 0.6.0

package/src/codegraph.mjs

@@ -1396,7 +1396,20 @@ export function renderHistory(graph, ind) {
 }
 
 /** Modules that call into the target's module (one hop over `calls`). */
+// Symbol-grain classes whose call graph lives on the fn/method-precise `callsSymbol`
+// edge, not the module-coarse `calls`. When the resolved target IS one of these, callers/
+// callees must read the SYMBOL node's own edges — mapping it to its enclosing module (the
+// old behaviour) both mislabels the answer with `mod:<path>` and scans the wrong edge set,
+// so "Widget.render --callsSymbol--> fnAlpha" was reported as "no recorded callers".
+const CALL_SYMBOL_CLASSES = new Set(["Function", "Method"]);
+
 export function renderCallers(graph, ind) {
+  // symbol grain: a fine symbol's callers are the SUBJECTS of callsSymbol edges into it.
+  if (CALL_SYMBOL_CLASSES.has(ind.class)) {
+    const callers = [...new Set(edgesOfKind(graph, "callsSymbol").filter((e) => e.object === ind.id).map((e) => e.subjectLabel || e.subject))];
+    if (!callers.length) return `${ind.label}: no recorded callers (fine-grained call edges are conservative — absence is not proof). Try tmct_impact for the full reverse closure.`;
+    return `${ind.label} — called by ${callers.length} symbol(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
+  }
   const modId = moduleIdOf(graph, ind);
   if (!modId) return `cannot map ${ind.label} to a module.`;
   const modLabel = graph.byId.get(modId)?.label || modId;
@@ -1405,8 +1418,15 @@ export function renderCallers(graph, ind) {
   return `${modLabel} — called by ${callers.length} module(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
 }
 
-/** Modules the target's module calls into (one hop over `calls`). */
+/** Callees of the target: the fn/method-precise callsSymbol edges when it is a fine symbol,
+ *  else the module-coarse `calls` one hop from its module. */
 export function renderCallees(graph, ind) {
+  // symbol grain: a fine symbol's callees are the OBJECTS of its callsSymbol edges.
+  if (CALL_SYMBOL_CLASSES.has(ind.class)) {
+    const callees = [...new Set(edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object))];
+    if (!callees.length) return `${ind.label}: no recorded callees (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
+    return `${ind.label} — calls into ${callees.length} symbol(s):\n  ${capJoin(callees, CALL_CAP, "\n  ")}`;
+  }
   const modId = moduleIdOf(graph, ind);
   if (!modId) return `cannot map ${ind.label} to a module.`;
   const modLabel = graph.byId.get(modId)?.label || modId;
@@ -1953,20 +1973,23 @@ export function renderCochanges(graph, ind) {
 
 const EXPORTS_CAP = 40;
 
-/** A module's public export surface: each __all__ name → the module that actually
- *  defines it (so re-export hubs like __init__ are explicit). */
+/** A module's public export surface: each exported name → the module that actually
+ *  defines it (so re-export hubs like __init__ / an index barrel are explicit). Reads the
+ *  `reexports` edge (mgx:reExports), which the extractor emits for ANY public-API construct
+ *  — Python `__all__` AND JS/TS `export` / `export { … } from …` — so the wording stays
+ *  language-neutral rather than implying a Python-only `__all__`. */
 export function renderExports(graph, ind) {
   const modId = moduleIdOf(graph, ind);
   if (!modId) return `cannot map ${ind.label} to a module.`;
   const modLabel = graph.byId.get(modId)?.label || modId;
   const edges = edgesOfKind(graph, "reexports").filter((e) => e.subject === modId);
-  if (!edges.length) return `${modLabel}: no public exports recorded (no literal __all__, or none resolved).`;
+  if (!edges.length) return `${modLabel}: no public exports recorded (no export list / __all__ found, or none resolved).`;
   const list = edges.slice(0, EXPORTS_CAP).map((e) => {
     const origin = graph.byId.get(e.object);
     const where = origin ? siteOf(origin) : null;
     const from = where ? ` ← ${where.path}` : "";
     return `${e.objectLabel || e.object}${from}`;
   });
-  return `${modLabel} — public API (${edges.length} export(s) via __all__):\n  ${list.join("\n  ")}` +
+  return `${modLabel} — public API (${edges.length} export(s)):\n  ${list.join("\n  ")}` +
     (edges.length > EXPORTS_CAP ? `\n  …+${edges.length - EXPORTS_CAP} more` : "");
 }

package/src/conformance.mjs

@@ -0,0 +1,166 @@
+// conformance.mjs — the Repository-Interface CONTRACT TEST SUITE as a reusable kit.
+//
+// PLAN_REPOSITORY_INTERFACE.md deliverable 3: an implementation is CONFORMANT iff it
+// passes `runConformance(name, makeProvider)`. tmct's own fixture + bootstrap providers
+// pass it in `npm test`; an EXTERNAL producer (seonix) imports this kit from the
+// published package and runs the SAME suite against its native provider to claim
+// conformance — conformance is the suite, not prose. It is provider-agnostic: it
+// asserts the SHAPE + the error contract; data-bearing truth is asserted by the caller
+// where its provider carries data.
+//
+// Public surface (exported here + via the package "./conformance" subpath):
+//   runConformance(name, makeProvider), assertResult, assertIndividual, assertEdge.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  INTERFACE_VERSION,
+  MISS_REASONS,
+  EDGE_KINDS,
+  SERVICES,
+  SOURCE_SERVICES,
+  isHit,
+  isMiss,
+} from "./repository-interface.mjs";
+
+const REASONS = new Set(Object.values(MISS_REASONS));
+
+// ---- Individual / Edge / Result shape validators (the shared wire types) ------
+
+export function assertIndividual(ind, where) {
+  assert.equal(typeof ind.id, "string", `${where}: Individual.id is a string`);
+  assert.equal(typeof ind.label, "string", `${where}: Individual.label is a string`);
+  assert.equal(typeof ind.class, "string", `${where}: Individual.class is a string (a tmct: class token)`);
+  assert.ok(Array.isArray(ind.attributes), `${where}: Individual.attributes is an array`);
+  for (const a of ind.attributes) {
+    assert.ok("key" in a && "value" in a && "prop" in a, `${where}: attribute has {key,value,prop}`);
+  }
+}
+
+export function assertEdge(e, where) {
+  for (const k of ["subject", "object", "predicate", "prop"]) {
+    assert.ok(k in e, `${where}: Edge carries required "${k}"`);
+  }
+  assert.equal(typeof e.subject, "string", `${where}: Edge.subject is a string`);
+  assert.equal(typeof e.object, "string", `${where}: Edge.object is a string`);
+}
+
+export function assertResult(r, where) {
+  assert.ok(r && typeof r === "object", `${where}: a Result object`);
+  assert.equal(typeof r.ok, "boolean", `${where}: Result.ok is a boolean`);
+  if (r.ok) {
+    assert.ok("value" in r, `${where}: a hit carries value`);
+  } else {
+    assert.ok(r.miss && REASONS.has(r.miss.reason), `${where}: a miss carries a CLOSED-set reason (got ${r.miss?.reason})`);
+    assert.equal(typeof r.miss.detail, "string", `${where}: miss.detail is a string`);
+  }
+}
+
+// =============================================================================
+// The provider-agnostic conformance kit. Run it against any implementation.
+// =============================================================================
+export function runConformance(name, makeProvider) {
+  test(`[${name}] advertises the full interface + version`, () => {
+    const svc = makeProvider();
+    assert.equal(svc.version, INTERFACE_VERSION, "declares the interface version");
+    for (const service of SERVICES) {
+      assert.ok(svc.capabilities.includes(service), `capability advertises "${service}"`);
+      assert.equal(typeof svc[service], "function", `implements "${service}" as a function`);
+    }
+  });
+
+  test(`[${name}] every service returns a well-formed Result (or an honest empty)`, () => {
+    const svc = makeProvider();
+    // Resolution-family with a term that certainly does not exist → a well-formed result.
+    for (const [service, args] of [
+      ["resolve", ["definitely-not-a-symbol-xyz"]],
+      ["describe", ["no:such:id"]],
+      ["members", ["no:such:id"]],
+      ["subclasses", ["no:such:id"]],
+      ["exports", ["no:such:id"]],
+      ["signature", ["no:such:id"]],
+      ["impact", ["no:such:id"]],
+      ["history", ["no:such:id"]],
+      ["snippet", ["no:such:id"]],
+      ["context", ["no-such-symbol"]],
+      ["architecture", [{}]],
+      ["untested", []],
+      ["stats", []],
+      ["search", ["", {}]],
+      ["ask", ["what is here"]],
+    ]) {
+      const r = svc[service](...args);
+      assertResult(r, `${name}.${service}`);
+    }
+  });
+
+  test(`[${name}] the error contract: a clean miss is a value, never a throw`, () => {
+    const svc = makeProvider();
+    // An unresolved term is a first-class UNRESOLVED_TERM miss on every id-taking service.
+    for (const service of ["describe", "members", "subclasses", "exports", "signature", "impact", "history"]) {
+      const r = svc[service]("no:such:id:at:all");
+      assert.ok(isMiss(r), `${service} on an absent id misses`);
+      assert.equal(r.miss.reason, MISS_REASONS.UNRESOLVED_TERM, `${service} → UNRESOLVED_TERM`);
+    }
+  });
+
+  test(`[${name}] edges: closed kind vocabulary; unknown kind is misuse (throws)`, () => {
+    const svc = makeProvider();
+    // A valid kind on a missing id misses (UNRESOLVED_TERM), never throws.
+    const r = svc.edges("no:such:id", EDGE_KINDS[0]);
+    assertResult(r, `${name}.edges`);
+    // An unknown kind is a programmer error, not a domain miss.
+    assert.throws(() => svc.edges("no:such:id", "not-a-real-kind"), TypeError);
+  });
+
+  test(`[${name}] source services answer NO_SOURCE (not a throw) when no working tree`, () => {
+    const svc = makeProvider();
+    if (svc.sourceAccess) return; // a source-capable provider is exempt from this shape
+    for (const service of SOURCE_SERVICES) {
+      // Use whatever the provider resolves; on empty graphs this is UNRESOLVED_TERM, on
+      // data-bearing graphs NO_SOURCE — both are valid closed-set misses.
+      const arg = service === "context" ? "x" : "no:such:id";
+      const r = svc[service](arg);
+      assert.ok(isMiss(r), `${service} misses without a working tree`);
+      assert.ok(
+        [MISS_REASONS.NO_SOURCE, MISS_REASONS.UNRESOLVED_TERM].includes(r.miss.reason),
+        `${service} miss reason is NO_SOURCE or UNRESOLVED_TERM (got ${r.miss.reason})`,
+      );
+    }
+  });
+
+  test(`[${name}] stats / untested / architecture never miss — empty is a hit`, () => {
+    const svc = makeProvider();
+    const stats = svc.stats();
+    assert.ok(isHit(stats), "stats is always a hit");
+    assert.equal(typeof stats.value.total, "number");
+    assert.ok(Array.isArray(stats.value.classes));
+    assert.ok(isHit(svc.untested()), "untested is always a hit");
+    assert.ok(Array.isArray(svc.untested().value.modules));
+    assert.ok(isHit(svc.architecture({})), "architecture is always a hit");
+  });
+
+  test(`[${name}] concurrent/re-entrant: two handles, interleaved reads, stable & independent`, async () => {
+    const a = makeProvider();
+    const b = makeProvider();
+    // Fire the whole read surface concurrently across two independent handles; assert
+    // every result is well-formed and that a second identical call is byte-stable.
+    const calls = [
+      () => a.stats(),
+      () => b.stats(),
+      () => a.architecture({}),
+      () => a.untested(),
+      () => b.search("", {}),
+      () => a.resolve("x"),
+      () => b.ask("anything"),
+      () => a.describe("no:such:id"),
+    ];
+    const first = await Promise.all(calls.map((c) => Promise.resolve().then(c)));
+    for (const r of first) assertResult(r, `${name}.concurrent`);
+    const second = await Promise.all(calls.map((c) => Promise.resolve().then(c)));
+    // Determinism across handles: same query, same JSON.
+    assert.equal(JSON.stringify(first.map((r) => r.ok)), JSON.stringify(second.map((r) => r.ok)));
+    // The two handles are independent objects (no shared mutable state leak).
+    assert.notEqual(a, b);
+    assert.deepEqual(a.stats().value, b.stats().value, "same graph → same stats across handles");
+  });
+}

package/src/corpus/conceptnet.mjs

@@ -31,6 +31,17 @@ const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 export const SLICE_FILE = join(PKG_ROOT, "corpus", "conceptnet", "slice.jsonl");
 export const MAP_FILE = join(PKG_ROOT, "src", "corpus", "conceptnet-map.toml");
 
+// The tier-1 curated Software-Engineering ontology (SEON). concepts.jsonl is in
+// the SAME slice shape as ConceptNet ({start, rel, end, weight}), so it loads +
+// maps through the identical loadSlice/loadMap/toFacts path — just with a
+// "corpus:seon" provenance prefix. definitions.jsonl is a separate {term,
+// definition, sense} list the chat answer layer prefers for a lexicon term's
+// "what is a <term>". tier-2 corpuses (aws/python/java) share the slice shape too.
+export const SEON_CONCEPTS_FILE = join(PKG_ROOT, "corpus", "seon", "concepts.jsonl");
+export const SEON_DEFINITIONS_FILE = join(PKG_ROOT, "corpus", "seon", "definitions.jsonl");
+export const TIER2_DIR = join(PKG_ROOT, "corpus", "tier2");
+export const TIER2_MANIFEST_FILE = join(TIER2_DIR, "manifest.json");
+
 const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
 
 /** Load the slice JSONL as a stream (never the whole file as one string) and
@@ -92,8 +103,13 @@ export const termText = (uri) => {
  *  (provenance is a STRING — exactly what src/memory/core.mjs appendFact
  *  takes; it names the corpus and the originating ConceptNet relation).
  *  Rows whose relation maps ace="none" are skipped — deliberate non-emission.
- *  A relation with NO row in the map throws: that is table drift, not data. */
-export function toFacts(assertions, map) {
+ *  A relation with NO row in the map throws: that is table drift, not data.
+ *
+ *  `provenancePrefix` names the corpus half of the provenance string; it defaults
+ *  to "corpus:conceptnet" so the ConceptNet seed stays BYTE-IDENTICAL to before.
+ *  The seon / tier-2 corpuses reuse the same slice shape, tagged "corpus:seon" or
+ *  "corpus:tier2:<id>" so a reader can tell a curated SE fact from ConceptNet noise. */
+export function toFacts(assertions, map, provenancePrefix = "corpus:conceptnet") {
   const facts = [];
   for (const a of assertions) {
     const row = map.get(a.rel);
@@ -108,7 +124,7 @@ export function toFacts(assertions, map) {
       subject,
       predicate: row.predicate,
       object,
-      provenance: `corpus:conceptnet ${a.rel}`,
+      provenance: `${provenancePrefix} ${a.rel}`,
     });
   }
   return facts;
@@ -127,10 +143,12 @@ export function toFacts(assertions, map) {
  *  Idempotent twice over: appendFact's content-hashed ids make a blind
  *  re-append an upsert, and we pre-read the store once to skip triples that
  *  are already there (so re-seeding costs one read, not N rewrites).
- *  Returns { appended, skipped, total }. */
-export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE, prefer } = {}) {
+ *  Returns { appended, skipped, total }. `provenancePrefix` is threaded through to
+ *  toFacts (default "corpus:conceptnet" → byte-identical seed) so a seon/tier-2
+ *  corpus can tag its facts "corpus:seon" / "corpus:tier2:<id>". */
+export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE, prefer, provenancePrefix } = {}) {
   const [assertions, map] = await Promise.all([loadSlice(slicePath), loadMap(mapPath)]);
-  let facts = toFacts(assertions, map);
+  let facts = toFacts(assertions, map, provenancePrefix);
   if (Array.isArray(prefer) && prefer.length) {
     const rank = new Map(prefer.map((p, i) => [p, i]));
     // stable partition: Array.prototype.sort is stable in Node, so equal-rank

package/src/grammar/lexicon-core.json

@@ -30,6 +30,14 @@
     "component": {},
     "interface": {},
     "type": {},
+    "category": {},
+    "kind": {},
+    "artifact": {},
+    "routine": {},
+    "part": {},
+    "helper": {},
+    "operation": {},
+    "change": {},
     "schema": {},
     "database": {},
     "table": {},

package/src/memory/inspect.mjs

@@ -128,6 +128,31 @@ export function renderMemory({ memory, blocks }, { verbose = false } = {}) {
     lines.push("", "blocks — none folded yet (a session folds when it ends).");
   }
 
+  // ---- explore hooks: real, runnable example queries built from what's actually
+  //      stored, so /memory is a springboard for drilling in, not just a dump ----
+  if (individuals.length) {
+    const clean = (t) => typeof t === "string" && /^[a-z][a-z0-9]+(?: [a-z0-9]{2,}){0,2}$/.test(t) && t.length <= 22 && !/^\d+$/.test(t);
+    const facts = readFactRows(memory);
+    // Rank candidate "what is a X" terms by CATEGORY SIZE (how many facts point at
+    // them) so the hooks land on rich, recognisable categories (function, class, …),
+    // not a lone ConceptNet oddity.
+    const freq = new Map();
+    for (const f of facts) if (clean(f.object)) freq.set(f.object, (freq.get(f.object) || 0) + 1);
+    const terms = [...freq.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([t]) => t)
+      .slice(0, 3);
+    const sample = facts.find((f) => clean(f.subject) && terms.includes(f.object));
+    const ex = terms.map((t) => `  what is a ${t}`);
+    if (sample) ex.push(`  is a ${sample.subject} a ${sample.object}`);
+    if (terms[0]) ex.push(`  what did i tell you about ${terms[0]}`);
+    if (ex.length) {
+      lines.push("", "explore — ask any of these (real terms from the store above):");
+      lines.push(...ex);
+      lines.push("  /memory verbose — the full store   ·   /stats — the code-graph overview");
+    }
+  }
+
   return lines.join("\n");
 }
 

package/src/server.mjs

@@ -49,9 +49,73 @@ import {
 } from "./codegraph.mjs";
 import { ask } from "./ask.mjs";
 import { createGraphService } from "./providers/graph-service.mjs";
+// Read-ONLY consumers of the conversational-memory graph (src/memory/core.mjs) — the 500
+// corpus facts live there, NOT in the code-map graph.json every tool below loads. Used by
+// the FALL-THROUGH bridge (below): when the code-map resolves NOTHING for a concept query
+// (/subclasses /describe /members /find), answer from the reified isa-family facts instead
+// of a flat "no entity". Never written here; memory writes stay owned by memory/*.
+import { loadMemory, readFactRows, normFactTerm } from "./memory/core.mjs";
 
 const SNIPPET_MAX_LINES = 200;
 
+// The reified isa-family predicates a memory Fact carries ("<subject> rdfs:subClassOf
+// <object>" / "rdf:type"): subject IS-A object. Subclasses of X = facts whose OBJECT is X;
+// superclasses of X = facts whose SUBJECT is X. (Matches chat.mjs's ISA_PREDICATES.)
+const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+const MEMORY_LIST_CAP = 40;
+
+/** Load the conversational-memory Facts as trust-bearing rows, failure-tolerant (no memory
+ *  store / unreadable → [], so the tool still returns its honest code-map miss). repoRoot is
+ *  the dir that CONTAINS .tmct/ (graphFile = <repo>/.tmct/graph.json), which is exactly the
+ *  `dir` loadMemory joins MEMORY_GRAPH_REL onto. */
+async function memoryFactRows(config) {
+  try {
+    return readFactRows(await loadMemory(dirname(dirname(config.graphFile))));
+  } catch {
+    return [];
+  }
+}
+
+/** A short provenance receipt for a set of memory rows — distinct source strings, capped. */
+function memoryProvenance(rows) {
+  const provs = [...new Set(rows.map((r) => r.provenance).filter(Boolean))];
+  if (!provs.length) return "provenance: memory/corpus facts";
+  const shown = provs.slice(0, 2).join("; ");
+  return `provenance: ${shown}${provs.length > 2 ? `, +${provs.length - 2} more source(s)` : ""}`;
+}
+
+/** FALL-THROUGH: subclasses of a concept from the reified isa-family facts (subjects of
+ *  "<subj> subClassOf <term>"). Null when the term names no such facts (so the caller can
+ *  keep the honest code-map miss). Provenance is always cited. */
+function renderMemorySubclasses(rows, term) {
+  const t = normFactTerm(term);
+  const hits = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && r.object === t);
+  if (!hits.length) return null;
+  const labels = [...new Set(hits.map((r) => r.subject))].sort();
+  const shown = labels.slice(0, MEMORY_LIST_CAP);
+  const tail = labels.length > MEMORY_LIST_CAP ? `\n  …+${labels.length - MEMORY_LIST_CAP} more` : "";
+  return `"${term}" is not a code-map entity — answering from memory/corpus facts. ` +
+    `${labels.length} known subclass(es):\n  ${shown.join("\n  ")}${tail}\n(${memoryProvenance(hits)})`;
+}
+
+/** FALL-THROUGH: a concept's DEFINITION from the isa-family facts — its superclasses ("is
+ *  a …") plus a count/sample of its known subclasses. Null when the term names no facts. */
+function renderMemoryDefinition(rows, term) {
+  const t = normFactTerm(term);
+  const isa = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && (r.subject === t || r.object === t));
+  if (!isa.length) return null;
+  const supers = [...new Set(isa.filter((r) => r.subject === t).map((r) => r.object))];
+  const subs = [...new Set(isa.filter((r) => r.object === t).map((r) => r.subject))].sort();
+  const lines = [`"${term}" is not a code-map entity — answering from memory/corpus facts.`];
+  if (supers.length) lines.push(`is a: ${supers.slice(0, MEMORY_LIST_CAP).join(", ")}`);
+  if (subs.length) {
+    const tail = subs.length > MEMORY_LIST_CAP ? `, +${subs.length - MEMORY_LIST_CAP} more` : "";
+    lines.push(`known subclasses (${subs.length}): ${subs.slice(0, MEMORY_LIST_CAP).join(", ")}${tail}`);
+  }
+  lines.push(`(${memoryProvenance(isa)})`);
+  return lines.join("\n");
+}
+
 // Tiered tool surface: the hot tools carry full descriptions/schemas in this
 // catalog; every COLD tool (describe/members/impact/history/…) is still served
 // by dispatchTool below and is reachable via the CLI `cli <tool>` route +
@@ -298,8 +362,11 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   if (name === "tmct_describe") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
-    return renderDescribe(graph, match, { candidates });
+    const { match, candidates } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderDescribe(graph, match, { candidates }); // code-map wins when present
+    const fb = renderMemoryDefinition(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "symbol"); // no code-map + no memory fact → the honest miss
   }
   if (name === "tmct_snippet") {
     const symbol = String(args?.symbol || "").trim();
@@ -347,23 +414,37 @@ export async function dispatchTool(name, args, { config, source = defaultSource
     const query = String(args?.query || "").trim();
     const kind = String(args?.kind || "").trim();
     if (!query && !kind) throw new ToolError("query is required");
-    return renderSearch(graph, query, {
+    const out = renderSearch(graph, query, {
       kind,
       decorator: String(args?.decorator || "").trim(),
       name: String(args?.name || "").trim(),
     });
+    // FALL-THROUGH: a code-map miss ("no module matches …") on a plain concept query still
+    // answers from the memory/corpus isa-family facts when the concept is known there.
+    if (!kind && /^no module matches/.test(out)) {
+      const fb = renderMemoryDefinition(await memoryFactRows(config), query);
+      if (fb) return fb;
+    }
+    return out;
   }
   if (name === "tmct_members") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const { match } = resolveOrThrow(svc, symbol, "class");
-    return renderMembers(graph, match);
+    const { match } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderMembers(graph, match); // code-map wins when present
+    // a concept's "members" in the corpus sense are its subclasses (its instances).
+    const fb = renderMemorySubclasses(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "class"); // the honest miss
   }
   if (name === "tmct_subclasses") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const { match } = resolveOrThrow(svc, symbol, "class");
-    return renderSubclasses(graph, match);
+    const { match } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderSubclasses(graph, match); // code-map wins when present
+    const fb = renderMemorySubclasses(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "class"); // no code-map subclass + no memory fact → honest miss
   }
   if (name === "tmct_architecture") {
     return renderArchitecture(graph, { pkg: String(args?.package || "").trim() });