@polycode-projects/the-mechanical-code-talker 3.1.0 → 3.1.2

package/README.md

@@ -1135,6 +1135,8 @@ The `<where-marker>` slot takes any of *defined*, *declared*, *located*, *implem
 - **touches** — *touched*, *touches*, *changed*, *change*, and more
 - **cochange** — *changed with*, *co-changes with*, *co-change with*, *changes alongside*, and more
 - **reexports** — *exports*, *export*, *re-exports*, *re-export*, and more
+- **serves** — *serves*, *serve*, *serving*, and more
+- **denotes** — *denotes*, *denote*, *denoting*, and more
 
 Every question in that table runs against the example graph:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "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; indexes a repo on request (tmct index) or reads any producer's graph.",
@@ -46,6 +46,8 @@
     "./generateCompletion": "./src/services/completions.mjs",
     "./createCompletionsGraphAdapter": "./src/services/completions.mjs",
     "./ingest": "./src/services/extract-facts.mjs",
+    "./digest": "./src/adapters/corpus/digest-bank.mjs",
+    "./memory": "./src/adapters/memory/core.mjs",
     "./repository-interface": "./src/adapters/repository-interface.mjs",
     "./conformance": "./src/tools/conformance.mjs",
     "./ask-browser": "./src/surfaces/web/graph-ask-browser-entry.mjs"

package/src/domain/ask-vocab.mjs

@@ -164,6 +164,29 @@ export const RELATIONS = {
       "exporting",
     ],
   },
+  // serves/denotes classify edges a PROVIDER declares (mgx:serves / mgx:denotes).
+  // tmct's own indexer emits neither, so they are absent from a graph it built
+  // and answer honestly empty there; a provider graph that carries them gets the
+  // same one-hop traversal every other kind gets, instead of only /describe's
+  // kind-agnostic edge walk.
+  serves: {
+    bare: "serve",
+    comment: "subject provides or backs the object — a handler serving a route, a module serving a surface (mgx:serves).",
+    verbs: [
+      "serves", "serve",
+      // gerund (g-drop normalization)
+      "serving",
+    ],
+  },
+  denotes: {
+    bare: "denote",
+    comment: "subject names the object — a glossary/lexicon term denoting a code entity (mgx:denotes).",
+    verbs: [
+      "denotes", "denote",
+      // gerund (g-drop normalization)
+      "denoting",
+    ],
+  },
 };
 
 /** The closed set of reverse `inherits` verb phrasings a strategy checks to

package/src/domain/ask.mjs

@@ -35,6 +35,7 @@ import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mj
 import { runStrategiesSync } from "./interpret/pipeline.mjs";
 import { mergeStrategyResults, alternateLines } from "./interpret/merge.mjs";
 import { lookupByProseTokens, splitIdentifierWords } from "./prose.mjs";
+import { articleFor } from "./digest/words.mjs";
 import { pickPhrase } from "./answer-variants.mjs";
 
 // Normalization stays importable from its original site (tests + chat surface).
@@ -137,7 +138,7 @@ function verbFor(kind) {
 const PLURAL_SUBJECT_VERB = {
   imports: "import", calls: "call", callsSymbol: "call", inherits: "inherit from",
   contains: "contain", tests: "test", touches: "touch", cochange: "cochange",
-  reexports: "export", uses: "use",
+  reexports: "export", uses: "use", serves: "serve", denotes: "denote",
 };
 const pluralVerbFor = (kind) => PLURAL_SUBJECT_VERB[kind] || verbFor(kind);
 
@@ -2187,7 +2188,28 @@ 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;
+  return mod ? `${label} in ${mod}` : label;
+}
+
+/** Does any branch of a compositional AST filter on test coverage? Keyed off
+ *  QUALIFIERS' own `via` field, so a new coverage adjective in the vocabulary
+ *  is picked up here without a second list to keep in step. */
+function filtersOnCoverage(node) {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some(filtersOnCoverage);
+  if (Array.isArray(node.filters)
+    && node.filters.some((f) => QUALIFIERS[String(f).toLowerCase()]?.via === "tested")) return true;
+  return Object.values(node).some(filtersOnCoverage);
+}
+
+/** An empty coverage-filtered set over symbols is a grain mismatch, not an
+ *  absent answer: `tests` edges are recorded module to module, so no
+ *  function-grain coverage exists to filter on. Say that instead of the
+ *  generic rephrase nudge, which would send the reader somewhere unrelated. */
+function coverageGrainNote(parsed, entityType) {
+  if (!["Function", "Method"].includes(entityType)) return null;
+  if (!filtersOnCoverage(parsed)) return null;
+  return "This index records tests edges module to module, so it holds no function-grain coverage to filter on — ask whether the module a function lives in is tested instead.";
 }
 
 function renderComposite(parsed, result, graph) {
@@ -2210,7 +2232,7 @@ function renderComposite(parsed, result, graph) {
       }
       const hit = result.matches[0];
       const modLabel = moduleLabelOf(hit);
-      const definedIn = hit.class === "Module" ? "" : (modLabel && modLabel !== "(unknown module)" ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "");
+      const definedIn = hit.class === "Module" ? "" : (modLabel ? `, ${pickPhrase("defined-in", hit.id, "defined in")} ${modLabel}` : "");
       return { content: `Yes — ${hit.label} is a ${kindSingular}${definedIn}.`, miss: false, ambiguous: false, matches: result.matches };
     }
     if (!result.matches.length) {
@@ -2386,7 +2408,8 @@ function renderComposite(parsed, result, graph) {
   }
   // set-producing
   if (!result.matches.length) {
-    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${touchesRephraseHint(graph)}`, miss: true, ambiguous: false, matches: [] };
+    const hint = coverageGrainNote(parsed, result.entityType) || touchesRephraseHint(graph);
+    return { content: `nothing in the index matches that${result.entityType ? ` (${nounFor(result.entityType, 2)})` : ""}. ${hint}`, miss: true, ambiguous: false, matches: [] };
   }
   return { content: `${compositeList(result.matches)}.`, miss: false, ambiguous: false, matches: result.matches };
 }
@@ -2963,6 +2986,25 @@ function modifierIsWired(shape, kind, entityType) {
 }
 const TRANSITIVE_MAX_DEPTH = 8; // matches renderImpact's own default (codegraph.mjs)
 
+/** A graph's own vocabulary nodes carry their definition text under this
+ *  property. A code entity's docstring rides `seon:hasDoc` and shares the
+ *  plain `doc` key, so the PROP is what separates the two. */
+const SCHEMA_DOC_PROP = "mgx:schemaDoc";
+
+/** The definition text an individual publishes about itself, or null. Reading
+ *  the meta lane off this attribute rather than a fixed class-name list lets a
+ *  graph declare its own documented individual class (a glossary term, say)
+ *  and have "what is X" answer for it like any other vocabulary node. */
+function schemaDefinitionOf(ind) {
+  return (ind?.attributes || []).find((a) => a.prop === SCHEMA_DOC_PROP)?.value || null;
+}
+
+function schemaKindWordFor(cls) {
+  if (cls === "SchemaClass") return "a class in the graph's schema";
+  if (cls === "SchemaPredicate") return "a predicate (relation) in the graph's schema";
+  return `${articleFor(cls)} ${cls} in this graph's vocabulary`;
+}
+
 /** Compile a parsed query into a graph lookup. Pure given (graph, parsed, opts).
  *  `opts.contextId` resolves a context pronoun ("this"/"it"/…) when the parse
  *  needed one. Returns {matches, objMatch, candidates, traversal, ambiguous,
@@ -2992,7 +3034,7 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     const term = String(parsed.object || "").trim();
     const termLc = term.toLowerCase();
     const match = (graph.individuals || []).find((i) => {
-      if (i.class !== "SchemaClass" && i.class !== "SchemaPredicate") return false;
+      if (!schemaDefinitionOf(i)) return false;
       if (String(i.label).toLowerCase() === termLc) return true;
       const token = (i.attributes || []).find((a) => a.key === "token")?.value;
       return token && String(token).toLowerCase() === termLc;
@@ -3435,12 +3477,15 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
 // ---- templated renderer: string interpolation + grouping/pluralization/
 // overflow rules, never generation. ----
 
+/** The module an individual lives in, or null when the index places it in
+ *  none — a graph can carry individuals that are not code (a glossary term,
+ *  a schema node), and naming a module for those would be a fabrication. */
 function moduleLabelOf(ind) {
   if (ind.class === "Module") return ind.label;
   const site = (ind.attributes || []).find((a) => a.key === "site")?.value;
   if (site) return String(site).split(":")[0];
   const m = String(ind.id || "").match(/^fn:(.+)#/);
-  return m ? m[1] : "(unknown module)";
+  return m ? m[1] : null;
 }
 
 function symbolLabelOf(ind) {
@@ -3653,9 +3698,8 @@ function renderCore(parsed, result, graph) {
     if (result.metaCodeClass) {
       return { content: result.metaFallbackText, miss: false, ambiguous: false, matches: result.matches };
     }
-    const doc = (result.objMatch.attributes || []).find((a) => a.key === "doc")?.value || "";
-    const kindWord = result.objMatch.class === "SchemaClass" ? "a class in the graph's schema" : "a predicate (relation) in the graph's schema";
-    return { content: `${result.objMatch.label} is ${kindWord}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
+    const doc = schemaDefinitionOf(result.objMatch) || "";
+    return { content: `${result.objMatch.label} is ${schemaKindWordFor(result.objMatch.class)}: ${doc}`, miss: false, ambiguous: false, matches: result.matches };
   }
   // mentions: the prose surface — checked before the generic objMatch-null miss
   // below, because a mentions result deliberately carries no resolved object
@@ -3810,8 +3854,15 @@ function renderCore(parsed, result, graph) {
       const lines = m[3] && m[3] !== m[2] ? `lines ${m[2]}-${m[3]}` : `line ${m[2]}`;
       return { content: `${symbolLabelOf(ind)} is defined in ${m[1]} at ${lines}.`, miss: false, ambiguous: false, matches: result.matches };
     }
+    const mod = moduleLabelOf(ind);
+    if (!mod) {
+      return {
+        content: `${ind.label} has no recorded code location in this index — it carries no source site, and nothing places it in a module.`,
+        miss: true, ambiguous: false,
+      };
+    }
     return {
-      content: `${symbolLabelOf(ind)} is defined in ${moduleLabelOf(ind)} (no line span recorded in this index).`,
+      content: `${symbolLabelOf(ind)} is defined in ${mod} (no line span recorded in this index).`,
       miss: false, ambiguous: false, matches: result.matches,
     };
   }
@@ -3974,7 +4025,7 @@ function renderCore(parsed, result, graph) {
   // "there is … in {module}" (module trails, not leads).
   const byModule = new Map();
   for (const m of result.matches.slice(0, OVERFLOW_CAP)) {
-    const mod = moduleLabelOf(m);
+    const mod = moduleLabelOf(m) || "no recorded module";
     if (!byModule.has(mod)) byModule.set(mod, []);
     byModule.get(mod).push(symbolLabelOf(m));
   }
@@ -4066,8 +4117,7 @@ function fuzzyCascadeWord(w) {
  *  question. Exact/substring/prose matches are untouched. */
 function schemaTypoTrap(resolution, term) {
   if (!resolution?.match || resolution.matchedVia !== "fuzzy" || resolution.ambiguous) return false;
-  const cls = resolution.match.class;
-  if (cls !== "SchemaClass" && cls !== "SchemaPredicate") return false;
+  if (!schemaDefinitionOf(resolution.match)) return false;
   const lc = String(term || "").trim().toLowerCase();
   const kindNoun = fuzzyCascadeWord(lc);
   return !!kindNoun && kindNoun !== lc && !!ENTITY_TO_TYPE[kindNoun];

package/src/domain/codegraph.mjs

@@ -75,6 +75,10 @@ const PROP_KIND = {
   "seon:hassupertype": "inherits",
   "mgx:changecoupledwith": "cochange",
   "mgx:reexports": "reexports",
+  // provider-declared edges: tmct's own indexer emits neither, so these classify
+  // only in a graph supplied through the provider seam
+  "mgx:serves": "serves",
+  "mgx:denotes": "denotes",
   // symbol-level edges stay separate kinds so the module-coarse impact closure is unchanged
   "mgx:touchessymbol": "touchesSymbol",
   "mgx:callssymbol": "callsSymbol",
@@ -152,6 +156,11 @@ export function resolveSymbol(graph, symbol) {
   const s = normPath(symbol);
   if (!s) return { match: null, candidates: [] };
   const sBase = basename(s);
+  // A bare filename (no "/") legitimately fuzzy-matches on basename alone. A
+  // multi-segment input reads as a repo-relative path the caller believes exists;
+  // matching it against an unrelated file that merely shares a basename would
+  // fabricate a hit, so those only match via an exact path suffix, never basename alone.
+  const isBareFilename = !s.includes("/");
   const scored = [];
   for (const ind of graph.individuals) {
     const label = normPath(ind.label);
@@ -160,8 +169,7 @@ export function resolveSymbol(graph, symbol) {
     if (label === s || id === s) score = 100;
     else if (
       label.endsWith(`/${s}`) ||
-      basename(label) === sBase ||
-      basename(label).replace(/\.[a-z]+$/, "") === sBase
+      (isBareFilename && (basename(label) === sBase || basename(label).replace(/\.[a-z]+$/, "") === sBase))
     )
       score = 80;
     else if (label.includes(s)) score = Math.max(10, 50 - (label.length - s.length));
@@ -1090,7 +1098,7 @@ export function compileNameFilter(name, { now = Date.now } = {}) {
   };
 }
 
-export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
+export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "", toolNamePrefix = "tmct_" } = {}) {
   const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   const wantKind = String(kind || "").trim().toLowerCase();
   const decFilter = String(decorator || "").trim().toLowerCase();
@@ -1104,7 +1112,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
   // default (no kind) keeps the module "where does this live" search unchanged.
   if (wantKind && wantKind !== "module") {
     try {
-      return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe });
+      return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe, toolNamePrefix });
     } catch (e) {
       if (e instanceof NameFilterBudgetExceeded) return e.message;
       throw e;
@@ -1113,7 +1121,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
   if (!tokens.length && !nameRe && !decFilter) return "empty query";
   const scored = scoreModules(graph, tokens);
   if (!scored.length) {
-    return `no module matches "${query}". Try broader keywords, or tmct_describe <path> if you know where it lives.`;
+    return `no module matches "${query}". Try broader keywords, or ${toolNamePrefix}describe <path> if you know where it lives.`;
   }
   const hits = scored.slice(0, limit);
   const lines = [`${scored.length} module(s) match "${query}" (top ${hits.length}):`];
@@ -1121,7 +1129,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
     const m = matching.length ? ` — matching: ${capJoin([...new Set(matching)], SEARCH_SYMBOLS_SHOWN)}` : "";
     lines.push(`- ${ind.label} (defines ${defineCount} symbol(s))${m}`);
   }
-  lines.push("Then tmct_describe <path> for the full sibling list + typed edges, or tmct_impact <path> for dependents.");
+  lines.push(`Then ${toolNamePrefix}describe <path> for the full sibling list + typed edges, or ${toolNamePrefix}impact <path> for dependents.`);
   return lines.join("\n");
 }
 
@@ -1187,11 +1195,11 @@ const CALL_CAP = 30;
 
 /** A class's methods + attributes (with sites/decorators) in one slice — replaces
  *  reading the class body. Uses the `contains` (seon:containsCodeEntity) relation. */
-export function renderMembers(graph, ind) {
+export function renderMembers(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id);
   if (!contains.length) {
-    lines.push("members: none recorded (empty class, or members not in the extracted graph). Use tmct_describe for its edges.");
+    lines.push(`members: none recorded (empty class, or members not in the extracted graph). Use ${toolNamePrefix}describe for its edges.`);
     return lines.join("\n");
   }
   const methods = [];
@@ -1205,7 +1213,7 @@ export function renderMembers(graph, ind) {
   }
   if (methods.length) lines.push(`methods (${methods.length}): ${capJoin(methods, MEMBERS_CAP)}`);
   if (attrs.length) lines.push(`attributes (${attrs.length}): ${capJoin(attrs, MEMBERS_CAP)}`);
-  lines.push("Use tmct_snippet <Class.member> for an exact body.");
+  lines.push(`Use ${toolNamePrefix}snippet <Class.member> for an exact body.`);
   return lines.join("\n");
 }
 
@@ -1215,7 +1223,7 @@ const attrVal = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)
  *  return annotation, raises/catches, self-fields, flags, decorators, one-line doc —
  *  so the agent gets the API surface without reading the body. Deterministic ast facts
  *  (kept OUT of tmct_context's lean bundle; this is the targeted tool for them). */
-export function renderSignature(graph, ind) {
+export function renderSignature(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   const site = siteOf(ind);
   const lines = [`${ind.label} — ${classHeading(ind.class)}${spanTag(site)}`];
   const params = attrVal(ind, "params");
@@ -1242,8 +1250,8 @@ export function renderSignature(graph, ind) {
   if (value) lines.push(`value: ${value}`);
   const doc = attrVal(ind, "doc");
   if (doc) lines.push(`doc: ${doc}`);
-  if (lines.length === 1) lines.push("(no signature detail recorded for this symbol — likely a module or attribute; use tmct_snippet for its source.)");
-  lines.push("Use tmct_snippet for the exact body.");
+  if (lines.length === 1) lines.push(`(no signature detail recorded for this symbol — likely a module or attribute; use ${toolNamePrefix}snippet for its source.)`);
+  lines.push(`Use ${toolNamePrefix}snippet for the exact body.`);
   return lines.join("\n");
 }
 
@@ -1391,18 +1399,18 @@ export function renderHistory(graph, ind) {
 // classes whose call graph lives on the fn/method-precise callsSymbol edge, not module-coarse calls
 const CALL_SYMBOL_CLASSES = new Set(["Function", "Method"]);
 
-export function renderCallers(graph, ind) {
+export function renderCallers(graph, ind, { toolNamePrefix = "tmct_" } = {}) {
   // 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.`;
+    if (!callers.length) return `${ind.label}: no recorded callers (fine-grained call edges are conservative — absence is not proof). Try ${toolNamePrefix}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;
   const callers = [...new Set(edgesOfKind(graph, "calls").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))];
-  if (!callers.length) return `${modLabel}: no recorded callers (calls are coarse/import-backed — absence is not proof). Try tmct_impact for the full reverse closure.`;
+  if (!callers.length) return `${modLabel}: no recorded callers (calls are coarse/import-backed — absence is not proof). Try ${toolNamePrefix}impact for the full reverse closure.`;
   return `${modLabel} — called by ${callers.length} module(s):\n  ${capJoin(callers, CALL_CAP, "\n  ")}`;
 }
 
@@ -1632,7 +1640,7 @@ export function scoreSymbolsRanked(graph, tokens, { kind, decFilter = "", nameRe
   return hits;
 }
 
-function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, nameRe }) {
+function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, nameRe, toolNamePrefix = "tmct_" }) {
   const targetClass = SYMBOL_CLASSES[kind];
   if (!targetClass) return `unknown kind "${kind}" (use function, class, method, attribute, or module).`;
   const hits = scoreSymbolsRanked(graph, tokens, { kind, decFilter, nameRe });
@@ -1640,7 +1648,7 @@ function searchSymbols(graph, tokens, { limit = SEARCH_LIMIT, kind, decFilter, n
   const top = hits.slice(0, limit);
   const lines = [`${hits.length} ${kind}(s) match (top ${top.length}):`];
   for (const { ind } of top) lines.push(`- ${ind.label}${spanTag(siteOf(ind))}`);
-  lines.push("Then tmct_snippet <name> for the exact body, or tmct_describe for its edges.");
+  lines.push(`Then ${toolNamePrefix}snippet <name> for the exact body, or ${toolNamePrefix}describe for its edges.`);
   return lines.join("\n");
 }
 

package/src/domain/interpret/normalize.mjs

@@ -196,6 +196,12 @@ const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
  *  noise-strip layer never drops. */
 const LEADING_CONNECTIVE_RE = /^(?:and|also|so|then|now|but)\s+(.+)$/i;
 const QUESTION_AUX_LEAD_RE = /^(?:does|do|did|is|are|was|were|has|have|had|can|could|will|would|should)\b/i;
+/** A bare relative-clause remainder ("the tests that cover it"), the shape an
+ *  anaphoric follow-up takes when it names a thing instead of asking outright.
+ *  Anchored on a determiner and a short head noun so a mid-clause boolean
+ *  branch ("and are tested", "and call Y") never reaches it. */
+const RELATIVE_CLAUSE_LEAD_RE =
+  /^(?:the|its|their|his|her|our|my)\s+[\w'-]+(?:\s+[\w'-]+){0,2}\s+(?:that|which|who)\s+\S/i;
 
 /** A topic-switch/self-interruption preamble ("actually never mind, <Q>"),
  *  repeating so a stack of markers peels in one pass. Distinct from
@@ -261,6 +267,7 @@ export function applyPreambleFrames(text) {
         INTERROGATIVE_LEAD_RE.test(rest) || QUESTION_AUX_LEAD_RE.test(rest)
         || TOPIC_SWITCH_PREAMBLE_RE.test(rest) || ACK_PREAMBLE_RE.test(rest)
         || HEDGE_ADVERB_PREAMBLE_RE.test(rest) || BROWSING_PREAMBLE_RE.test(rest)
+        || RELATIVE_CLAUSE_LEAD_RE.test(rest)
       ) q = rest;
     }
     if (q === before) break;

package/src/domain/paraphrase-ing8.mjs

@@ -0,0 +1,195 @@
+// paraphrase-ing8.mjs — the deterministic ING-8 equivalence checker: the harder
+// whole-document paraphrase shapes ING-7's own checker (verifySubClassParaphrase,
+// ./paraphrase.mjs) doesn't cover — non-isa relations (has/creates/capableOf),
+// multi-sentence documents, and synonym substitution over that closed relation
+// vocabulary.
+//
+// Strategy, mirroring verifySubClassParaphrase's own pattern: wherever the
+// predicate space allows exact re-derivation (a single isa fact on both sides),
+// reuse ING-7's own closure re-derivation directly. Everywhere else — every
+// non-isa relation, and every multi-sentence document — there is no entailment
+// closure to re-derive over, so the fallback is normalization + a closed
+// synonym-template table per relation, recognized and compared as an exact set.
+// A document holding a sentence outside the closed template set is reported
+// unverified, never guessed — the same "verified, never instead of the
+// original" discipline paraphrase.mjs itself states for the isa case.
+
+import { recoverSubClassTriple, verifySubClassParaphrase } from "./paraphrase.mjs";
+import { normFactTerm, fnv1aHex } from "./hash.mjs";
+
+const articleFor = (word) => (/^[aeiou]/i.test(String(word || "")) ? "an" : "a");
+
+// Every template reads "SUBJECT verb OBJECT" left to right, same discipline as
+// paraphrase.mjs's SUBCLASS_TEMPLATES — no passive/reordered form, since that's
+// the shape most likely to invert subject/object under a naive recognizer.
+const HAS_TEMPLATES = [
+  (s, o) => `${s} has ${articleFor(o)} ${o}`,
+  (s, o) => `${s} possesses ${articleFor(o)} ${o}`,
+  (s, o) => `${s} owns ${articleFor(o)} ${o}`,
+  (s, o) => `${s} carries ${articleFor(o)} ${o}`,
+];
+const HAS_RECOGNIZERS = [
+  /^(.+?)\s+has\s+an?\s+(.+)$/i,
+  /^(.+?)\s+possesses\s+an?\s+(.+)$/i,
+  /^(.+?)\s+owns\s+an?\s+(.+)$/i,
+  /^(.+?)\s+carries\s+an?\s+(.+)$/i,
+];
+
+const CREATES_TEMPLATES = [
+  (s, o) => `${s} creates ${o}`,
+  (s, o) => `${s} produces ${o}`,
+  (s, o) => `${s} generates ${o}`,
+  (s, o) => `${s} causes ${o}`,
+];
+const CREATES_RECOGNIZERS = [
+  /^(.+?)\s+creates\s+(.+)$/i,
+  /^(.+?)\s+produces\s+(.+)$/i,
+  /^(.+?)\s+generates\s+(.+)$/i,
+  /^(.+?)\s+causes\s+(.+)$/i,
+];
+
+const CAPABLEOF_TEMPLATES = [
+  (s, o) => `${s} can ${o}`,
+  (s, o) => `${s} is able to ${o}`,
+  (s, o) => `${s} knows how to ${o}`,
+];
+const CAPABLEOF_RECOGNIZERS = [
+  /^(.+?)\s+can\s+(.+)$/i,
+  /^(.+?)\s+is\s+able\s+to\s+(.+)$/i,
+  /^(.+?)\s+knows\s+how\s+to\s+(.+)$/i,
+];
+
+// The closed non-isa relation vocabulary this checker recognizes. Each family
+// pairs its templates and recognizers by index, same convention as isa.
+const RELATION_FAMILIES = {
+  has: { templates: HAS_TEMPLATES, recognizers: HAS_RECOGNIZERS },
+  creates: { templates: CREATES_TEMPLATES, recognizers: CREATES_RECOGNIZERS },
+  capableOf: { templates: CAPABLEOF_TEMPLATES, recognizers: CAPABLEOF_RECOGNIZERS },
+};
+export const RELATION_FAMILY_IDS = Object.keys(RELATION_FAMILIES);
+
+/** Deterministic template pick — same (subject, object) always picks the same
+ *  template, spread across the table by a pure hash (paraphrase.mjs's own
+ *  pickTemplateIndex pattern). `variantIndex`, when given, overrides the hash
+ *  pick (a corpus generator wanting two DIFFERENT closed phrasings for the same
+ *  fact passes distinct indices explicitly rather than relying on the hash). */
+function pickTemplateIndex(subject, object, templateCount, variantIndex) {
+  if (variantIndex !== null && variantIndex !== undefined) {
+    return ((variantIndex % templateCount) + templateCount) % templateCount;
+  }
+  const h = fnv1aHex(`${subject}\0${object}`);
+  return parseInt(h.slice(0, 8), 16) % templateCount;
+}
+
+/** Generate a closed-template phrasing of `subject <family> object` — never
+ *  null, always one of RELATION_FAMILIES[family]'s templates. Rule/template-
+ *  based only, no LLM, matching paraphrase.mjs's paraphraseSubClass. */
+export function paraphraseRelation(family, subject, object, variantIndex = null) {
+  const def = RELATION_FAMILIES[family];
+  if (!def) throw new Error(`paraphrase-ing8: unknown relation family "${family}"`);
+  const idx = pickTemplateIndex(subject, object, def.templates.length, variantIndex);
+  return def.templates[idx](subject, object);
+}
+
+/** Recover {subject, object} from text matching one of `family`'s closed
+ *  recognizers — null if it matches none of them. A plain closed-set regex
+ *  match, never a fuzzy/NLP parse, the exact inverse of paraphraseRelation. */
+export function recoverRelationTriple(family, text) {
+  const def = RELATION_FAMILIES[family];
+  if (!def) return null;
+  const s = String(text || "").trim();
+  for (const re of def.recognizers) {
+    const m = s.match(re);
+    if (m) return { subject: m[1].trim(), object: m[2].trim() };
+  }
+  return null;
+}
+
+/** Verify one relation-family paraphrase (mirrors verifySubClassParaphrase's
+ *  single-fact contract, but for a non-isa relation): the paraphrase text must
+ *  recover to the SAME (subject, object) under `family`'s closed recognizers.
+ *  No closure to re-derive over for a non-isa relation, so this is a direct
+ *  normalized compare, never a fuzzy one. */
+export function verifyRelationParaphrase(family, subject, object, paraphraseText) {
+  const recovered = recoverRelationTriple(family, paraphraseText);
+  if (!recovered) return { verified: false };
+  const verified = normFactTerm(recovered.subject) === normFactTerm(subject)
+    && normFactTerm(recovered.object) === normFactTerm(object);
+  return { verified };
+}
+
+// ---- whole-document recognition: isa + every relation family above ----
+
+/** Recover a single (family, subject, object) triple from one sentence: isa
+ *  first (paraphrase.mjs's closed subclass templates), then every relation
+ *  family in RELATION_FAMILY_IDS order — null if the sentence matches none of
+ *  the closed templates. Family keywords ("is a kind of" vs "has" vs "creates"
+ *  vs "can" …) don't overlap, so recognition order never resolves a genuine
+ *  ambiguity, only which closed family a sentence belongs to. */
+export function recoverAnyTriple(sentence) {
+  const isaHit = recoverSubClassTriple(sentence);
+  if (isaHit) return { family: "isa", subject: isaHit.subject, object: isaHit.object };
+  for (const family of RELATION_FAMILY_IDS) {
+    const hit = recoverRelationTriple(family, sentence);
+    if (hit) return { family, subject: hit.subject, object: hit.object };
+  }
+  return null;
+}
+
+function splitSentences(text) {
+  return String(text || "")
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+const tripleKey = (t) => `${t.family}\0${normFactTerm(t.subject)}\0${normFactTerm(t.object)}`;
+
+/** Recover EVERY sentence of a document as a closed-template triple — null (the
+ *  whole document unrecognized) the moment any sentence fails to match, never a
+ *  partial list standing in for the whole. */
+export function recoverDocumentTriples(text) {
+  const sentences = splitSentences(text);
+  if (!sentences.length) return null;
+  const triples = [];
+  for (const sentence of sentences) {
+    const t = recoverAnyTriple(sentence.replace(/\.+$/, ""));
+    if (!t) return null;
+    triples.push(t);
+  }
+  return triples;
+}
+
+/** Verify a whole-document ING-8 paraphrase pair: does `restatementText` say
+ *  exactly what `inputText` says, no more and no less? A single isa fact on
+ *  both sides re-derives the subclass closure directly through
+ *  verifySubClassParaphrase (ING-7's own exact-re-derivation strategy).
+ *  Everything else — a non-isa relation, or more than one sentence on either
+ *  side — recovers every sentence of both texts against the closed template
+ *  set above and requires the exact same (family, subject, object) SET, order
+ *  irrelevant. Never verified when either side holds a sentence outside the
+ *  closed templates, or when the two recovered sets differ in size or content
+ *  (a dropped fact and an invented fact both fail this the same way — the
+ *  checker declines rather than guesses which). */
+export function verifyIng8Paraphrase(inputText, restatementText) {
+  const inputTriples = recoverDocumentTriples(inputText);
+  const restatementTriples = recoverDocumentTriples(restatementText);
+  if (!inputTriples || !restatementTriples) {
+    return { verified: false, reason: "unrecognized", inputTriples, restatementTriples };
+  }
+  const bothSingleIsa = inputTriples.length === 1 && restatementTriples.length === 1
+    && inputTriples[0].family === "isa" && restatementTriples[0].family === "isa";
+  if (bothSingleIsa) {
+    const { subject, object } = inputTriples[0];
+    const restatementSentence = splitSentences(restatementText)[0].replace(/\.+$/, "");
+    const { verified } = verifySubClassParaphrase(subject, object, restatementSentence);
+    return { verified, method: "isa-closure", inputTriples, restatementTriples };
+  }
+  if (inputTriples.length !== restatementTriples.length) {
+    return { verified: false, reason: "fact count mismatch", inputTriples, restatementTriples };
+  }
+  const inputKeys = inputTriples.map(tripleKey).sort();
+  const restatementKeys = restatementTriples.map(tripleKey).sort();
+  const verified = inputKeys.every((k, i) => k === restatementKeys[i]);
+  return { verified, method: "closed-template-set", inputTriples, restatementTriples };
+}