@polycode-projects/the-mechanical-code-talker 3.0.5 → 3.0.7

package/src/domain/ask.mjs

@@ -15,7 +15,7 @@
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
 // (mgx:touchedByCommit / mgx:changeCoupledWith).
 
-import { relationKind, impactClosure, moduleCountOf, normPath, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP } from "./codegraph.mjs";
 import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
@@ -84,6 +84,7 @@ const PLURAL_FORMS = {
   Attribute: ["attribute", "attributes"], GlobalVariable: ["variable", "variables"],
   Commit: ["commit", "commits"],
   Change: ["change", "changes"],
+  Package: ["package", "packages"],
   Fact: ["fact", "facts"], Utterance: ["utterance", "utterances"],
   Session: ["session", "sessions"], Source: ["source", "sources"], Rule: ["rule", "rules"],
 };
@@ -92,6 +93,23 @@ function nounFor(entityType, n) {
   return n === 1 ? s : p;
 }
 
+/** A discourse `set` referent for a class-homogeneous result list — the typed
+ *  content a listing/filter answer establishes, so a later "which of those …"
+ *  binds it (see evalCommitFilter for the shape the session layer registers).
+ *  Returns an empty array when nothing typed can be registered: no member
+ *  class, or an empty result. `extra` carries a lane's own sibling flags (the
+ *  anaphora lane's `bound: true`). */
+function setReferentsFor(cls, matches, lane, extra = {}) {
+  if (!cls || !matches.length) return [];
+  return [{
+    kind: "set", class: cls,
+    label: `${matches.length} ${nounFor(cls, matches.length)}`,
+    ids: matches.map((m) => m.id),
+    attrs: { count: matches.length },
+    lane, ...extra,
+  }];
+}
+
 /** A class enum rendered as prose words ("GlobalVariable" -> "global
  *  variable"), lowercase to match nounFor's own convention. For the render
  *  sites that must name the enum itself rather than a curated PLURAL_FORMS
@@ -834,7 +852,7 @@ function parseAggregate(w, lc, nlp) {
 
 const LIST_SKIP = new Set(["the", "a", "an", "all", "me", "us"]);
 const LIST_TRIGGERS_SORTED = [...LIST_TRIGGERS].sort((a, b) => b.split(" ").length - a.split(" ").length);
-const LISTABLE_KINDS = "functions, classes, methods, modules, attributes, variables, or commits";
+const LISTABLE_KINDS = "functions, classes, methods, modules, packages, attributes, variables, or commits";
 // A leading "in"/"inside"/"under" right after the entity noun is an
 // unambiguous location-scope tail, never a reverse-clause predicate object.
 const SCOPE_PREPOSITIONS = new Set(["in", "inside", "under"]);
@@ -1621,11 +1639,25 @@ function computeFind(graph, entityType, term) {
   return { narrow: [], broad: sortFindHits([...broadHits.values()]) };
 }
 
+/** The graph's packages as list/count-shaped individuals. Packages are derived
+ *  from module labels rather than stored as nodes (see codegraph.mjs's
+ *  packageCounts), so these carry a `pkg:` id of their own and resolve to
+ *  nothing in graph.byId — a follow-up that tries to traverse one gets an
+ *  empty result, never a wrong one. Ordered by module count, the same order
+ *  the architecture map prints, so the two surfaces agree. */
+function packageIndividuals(graph) {
+  return [...packageCounts(modulesOf(graph)).entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([dir]) => ({ id: `pkg:${dir}`, label: dir, class: "Package" }));
+}
+
 /** Compile a set-producing AST into an array of individuals. */
 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);
+    case "allOfClass":
+      if (ast.entityType === "Package") return packageIndividuals(graph);
+      return graph.individuals.filter((i) => i.class === ast.entityType);
     // Predicate-find as a set atom: the narrow-then-broaden cascade's result,
     // transparently flattened ("related, not exact" is a render concern).
     case "find": {
@@ -1806,7 +1838,13 @@ function evalAnaphora(graph, ast, opts) {
   const emptyClass = f && f.type === "entity" ? f.entityType : sameClass(baseItems);
   const common = items.length ? sameClass(items) : emptyClass;
   if (ast.mode === "count") return { compositeKind: "count", count: items.length, entityType: common, matches: [] };
-  return { compositeKind: "set", matches: items, entityType: common };
+  // A narrowed, class-homogeneous result registers as a NEW set referent so
+  // the narrowing survives a later count and binds a further "which of those".
+  // It rides `bound: true` (a follow-up derived FROM the standing set), so the
+  // session layer's register() does not evict the set on the class change a
+  // narrowing produces.
+  const referents = setReferentsFor(common, items, "anaphora", { bound: true });
+  return { compositeKind: "set", matches: items, entityType: common, referents };
 }
 
 // Structural kinds counted for "most-connected" (total degree). Symbol-grain and
@@ -1923,7 +1961,17 @@ function evalSuperlative(graph, ast) {
   if (!scored.length) return { compositeKind: "superlative", entityType: ast.entityType, matches: [] };
   const best = scored[0].score;
   const winners = scored.filter((s) => s.score === best).map((s) => s.ind);
-  return { compositeKind: "superlative", entityType: ast.entityType, metricNoun: ast.metricNoun, extreme: ast.extreme, score: best, matches: winners };
+  // What the ranking established, as discourse referents (see evalCommitFilter
+  // for the shape the session layer registers). A lone winner is one entity a
+  // later "it"/"this"/"that" can bind; a metric tie (two winners on the same
+  // score) is a set instead, since no singular form should silently pick one.
+  // The score itself is always a measure referent, so "is that bigger than X"
+  // binds the number the ranking produced rather than re-deriving it.
+  const referents = winners.length >= 2
+    ? setReferentsFor(ast.entityType, winners, "superlative")
+    : [{ kind: "entity", class: ast.entityType, label: winners[0].label, ids: [winners[0].id], attrs: {}, lane: "superlative" }];
+  referents.push({ kind: "measure", label: `${best} ${ast.metricNoun}`, ids: [], attrs: { metric: best }, lane: "superlative" });
+  return { compositeKind: "superlative", entityType: ast.entityType, metricNoun: ast.metricNoun, extreme: ast.extreme, score: best, matches: winners, referents };
 }
 
 /** Top-level "<kind> of/in <owner>" membership eval, covering both a bare
@@ -1938,6 +1986,9 @@ function evalMembershipComposite(graph, ast, opts) {
   const filterFn = qualNode
     ? (ind) => qualNode.filters.every((f) => qualHolds(graph, ind, QUALIFIERS[f]))
     : null;
+  // A class-typed membership result registers as a discourse set referent (see
+  // evalCommitFilter) so a later "which of those …" binds it.
+  const membershipReferents = (list) => setReferentsFor(entityType, list, "membership");
   const owner = resolveMembershipOwner(graph, memNode.term, opts && opts.contextId);
   if (owner.kind === "dir") {
     let objs;
@@ -1947,14 +1998,16 @@ function evalMembershipComposite(graph, ast, opts) {
       objs = uniqueById(MEMBERSHIP_KINDS.flatMap((k) => forwardOverSet(graph, k, ids))).filter((o) => o.class === entityType);
     }
     if (filterFn) objs = objs.filter(filterFn);
-    return { compositeKind: "set", matches: objs, entityType };
+    return { compositeKind: "set", matches: objs, entityType, referents: membershipReferents(objs) };
   }
   if (owner.kind === "miss") return { compositeKind: "set", matches: [], entityType };
   const { own, inherited, viaLabel } = computeMembership(graph, owner.id, owner.entityClass, entityType, filterFn);
   const inheritedNotOwn = !own.length && inherited.length > 0;
+  const finalMatches = inheritedNotOwn ? inherited : own;
   return {
-    compositeKind: "membership", entityType, matches: inheritedNotOwn ? inherited : own,
+    compositeKind: "membership", entityType, matches: finalMatches,
     inheritedNotOwn, viaLabel, ownerLabel: owner.label,
+    referents: membershipReferents(finalMatches),
   };
 }
 
@@ -2019,7 +2072,11 @@ function evalQualCheck(graph, ast, opts) {
   }
   const rawHolds = qualHolds(graph, r.match, QUALIFIERS[qualifier]);
   const holds = negated ? !rawHolds : rawHolds;
-  return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match] };
+  // The subject the check resolved is a discourse referent either way — the
+  // answer being "no" does not make the entity any less bindable by a
+  // follow-up (see evalCommitFilter for the registration shape).
+  const referents = [{ kind: "entity", class: r.match.class, label: r.match.label, ids: [r.match.id], attrs: {}, lane: "qualCheck" }];
+  return { compositeKind: "qualCheck", subject: r.match, qualifier, negated, holds, matches: [r.match], referents };
 }
 
 /** Universal-over-a-set: the object is grounded first (an unknown one is an
@@ -2102,7 +2159,14 @@ function evalComposite(graph, ast, opts = {}) {
     && !(Array.isArray(opts.prev) && opts.prev.length)) {
     return { compositeMiss: true, reason: "no-prev", matches: [] };
   }
-  return { compositeKind: "set", matches: evalSet(graph, ast, opts), entityType: ast.entityType || null };
+  const matches = evalSet(graph, ast, opts);
+  const entityType = ast.entityType || null;
+  // A resolved, class-typed listing/filter set registers as a discourse
+  // referent (see evalCommitFilter) so a later "which of those …" binds it. A
+  // qualifier listing ("which modules are tested") registers the same way, just
+  // under its own lane name.
+  const referents = setReferentsFor(entityType, matches, ast.node === "qualifier" ? "qualifierListing" : "compositeSet");
+  return { compositeKind: "set", matches, entityType, referents };
 }
 
 // ---- compositional render: templated, same "honest miss vs cited hit"
@@ -2200,7 +2264,7 @@ function renderComposite(parsed, result, graph) {
     }
     // Kinds that don't live in a module (or have no module-scope parse at
     // all, like memory-graph classes) get no narrow-by-module hint.
-    const scopeable = !["Module", "Commit", "Fact", "Utterance", "Session", "Source", "Rule"].includes(result.entityType);
+    const scopeable = !["Module", "Package", "Commit", "Fact", "Utterance", "Session", "Source", "Rule"].includes(result.entityType);
     const hint = (!result.scoped && scopeable && result.matches.length > OVERFLOW_CAP)
       ? ` — narrow with "${nounFor(result.entityType, 2)} in <module>"`
       : "";
@@ -3111,8 +3175,15 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       }
       commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
     }
+    // The dated commit this answer named is a discourse `event` referent, so a
+    // later "was that before X was touched" binds it (see evalCommitFilter).
+    // Only when a dated commit resolved — an undated one is the render's honest
+    // miss, and a referent with no date could not feed the comparison lane.
+    const referents = commits.length && dateOf(commits[0])
+      ? [{ kind: "event", class: "Commit", label: commits[0].label, ids: [commits[0].id], attrs: { date: dateOf(commits[0]).slice(0, 10) }, lane: "when" }]
+      : [];
     return {
-      matches: commits, objMatch, candidates, ambiguous, matchedVia, whenShape: true,
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whenShape: true, referents,
       traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit date first`,
     };
   }
@@ -3135,8 +3206,14 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
       if (c && c.class === "Commit") commits.push(c);
     }
     commits.sort((a, b) => dateOf(b).localeCompare(dateOf(a)));
+    // The dated commit behind the "who last touched X" answer is the same
+    // `event` referent the when-shape registers, so either phrasing feeds a
+    // later temporal comparison. Registered only when the commit carries a date.
+    const referents = commits.length && dateOf(commits[0])
+      ? [{ kind: "event", class: "Commit", label: commits[0].label, ids: [commits[0].id], attrs: { date: dateOf(commits[0]).slice(0, 10) }, lane: "whoLast" }]
+      : [];
     return {
-      matches: commits, objMatch, candidates, ambiguous, matchedVia, whoLastShape: true,
+      matches: commits, objMatch, candidates, ambiguous, matchedVia, whoLastShape: true, referents,
       traversal: `touches+touchesSymbol edges where object = ${objMatch.label}, newest commit's author`,
     };
   }
@@ -4409,6 +4486,18 @@ export function ask(graph, query, { contextId = null, nlp = undefined, prev = nu
       content = `${content}\n(answering for ${result.objMatch.label} — ${others.length} other match${others.length === 1 ? "" : "es"}: ${list})`;
     }
   }
+  // A plain relation LISTING ("which modules import X", "which functions call
+  // X") resolves through the simple traverse path, not evalComposite, so it
+  // registers its class-typed result here — the same set referent the
+  // composite listing lanes emit, so a later "which of those …" binds it. Only
+  // a real, non-empty, class-homogeneous answer no lane already registered
+  // (the composite lanes set result.referents themselves).
+  if (!Array.isArray(result.referents) && !rendered.miss && !rendered.ambiguous
+    && (parsed?.shape === "reverse" || parsed?.shape === "forward")
+    && parsed.entityType && Array.isArray(result.matches) && result.matches.length
+    && result.matches.every((m) => m && m.class === parsed.entityType)) {
+    result = { ...result, referents: setReferentsFor(parsed.entityType, result.matches, "relationListing") };
+  }
   return {
     content,
     tmct_ask: {

package/src/domain/codegraph.mjs

@@ -1277,19 +1277,36 @@ export function renderSubclasses(graph, ind) {
 const ARCH_PKG_CAP = 25;
 const ARCH_HUB_CAP = 15;
 
+/** The directories that group a set of modules, each mapped to how many
+ *  modules it holds. A package is not a node class — no individual is ever
+ *  stored with class "Package" — so every surface that reports packages
+ *  (the architecture map, ask()'s package list and count) derives them from
+ *  module labels, and this is the one place that derivation lives. A module
+ *  at the repo root has no directory, so it groups under "(root)". */
+export function packageCounts(modules) {
+  const counts = new Map();
+  for (const m of modules) {
+    const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
+    counts.set(dir, (counts.get(dir) || 0) + 1);
+  }
+  return counts;
+}
+
+/** Every module in the graph, optionally scoped to a path prefix. */
+export function modulesOf(graph, prefix = "") {
+  const norm = normPath(prefix);
+  return graph.individuals.filter(
+    (i) => (i.class || "") === "Module" && (!norm || normPath(i.label).startsWith(norm)),
+  );
+}
+
 /** Package/module tree + the most-imported (hub) modules — replaces reading the dir
  *  tree and many files to learn the shape. Optional `pkg` prefix scopes it. */
 export function renderArchitecture(graph, { pkg = "" } = {}) {
   const norm = normPath(pkg);
-  const modules = graph.individuals.filter(
-    (i) => (i.class || "") === "Module" && (!norm || normPath(i.label).startsWith(norm)),
-  );
+  const modules = modulesOf(graph, pkg);
   if (!modules.length) return norm ? `no modules under "${pkg}".` : "no modules in the graph.";
-  const pkgCount = new Map();
-  for (const m of modules) {
-    const dir = m.label.includes("/") ? m.label.slice(0, m.label.lastIndexOf("/")) : "(root)";
-    pkgCount.set(dir, (pkgCount.get(dir) || 0) + 1);
-  }
+  const pkgCount = packageCounts(modules);
   const inDeg = new Map();
   for (const e of edgesOfKind(graph, "imports")) inDeg.set(e.object, (inDeg.get(e.object) || 0) + 1);
   const modSet = new Set(modules.map((m) => m.id));

package/src/domain/digest/compose.mjs

@@ -8,6 +8,7 @@
 import { renderStructure } from "./structures.mjs";
 import { FAMILY_PRIORITY } from "./select.mjs";
 import { articleFor, capitalizeFirst } from "./words.mjs";
+import DEFAULT_CONFIG from "./config.json" with { type: "json" };
 
 const DESCRIPTION_FAMILIES = FAMILY_PRIORITY.filter((f) => f !== "isa" && f !== "other");
 
@@ -22,6 +23,137 @@ function rowsByFamily(selected) {
   return by;
 }
 
+/** Split `rows` into runs of at most `size`, keeping order. Never returns an
+ *  empty run; a size below 1 is treated as 1. */
+export function chunk(rows, size) {
+  const n = Math.max(1, Math.trunc(size) || 1);
+  const out = [];
+  for (let i = 0; i < (rows || []).length; i += n) out.push(rows.slice(i, i + n));
+  return out;
+}
+
+/** Bucket isa rows by their object's immediate ancestor (`chains[object][1]`),
+ *  so facts that share a parent class can be named in one coherent sentence.
+ *  A parent with two or more rows is a real group; a parent with only one row,
+ *  and any row whose object has no recorded ancestry, fold into one shared
+ *  leftover pool. Groups come first in the order their earliest member ranked;
+ *  the leftover pool, in rank order, comes last. Returns
+ *  `[{ parent, rows }, …]` where `parent` is null for the leftover pool. */
+export function groupIsaByParent(rows, chains) {
+  const parentOf = (row) => (chains?.[row.object] || [])[1] || null;
+  const counts = new Map();
+  for (const row of rows || []) {
+    const p = parentOf(row);
+    if (p) counts.set(p, (counts.get(p) || 0) + 1);
+  }
+  const groupRows = new Map();
+  const order = [];
+  const leftover = [];
+  for (const row of rows || []) {
+    const p = parentOf(row);
+    if (p && counts.get(p) >= 2) {
+      if (!groupRows.has(p)) { groupRows.set(p, []); order.push(p); }
+      groupRows.get(p).push(row);
+    } else {
+      leftover.push(row);
+    }
+  }
+  const groups = order.map((parent) => ({ parent, rows: groupRows.get(parent) }));
+  if (leftover.length) groups.push({ parent: null, rows: leftover });
+  return groups;
+}
+
+/** The highest-level ontology roots the spoken isa objects reach: for each row,
+ *  the last (most general) node its ancestry chain walked. Roots rank by how
+ *  many chains reach them (ties broken alphabetically for determinism); the top
+ *  `count` are kept. Returns `{ roots, rows }` — `roots` names the concepts a
+ *  closer sentence renders, `rows` are the real backing isa facts so the closer
+ *  keeps its provenance without ever synthesising a row. */
+export function closerRootsFor(chains, usedRows, count) {
+  const rootCount = new Map();
+  const rootRows = new Map();
+  for (const row of usedRows || []) {
+    const chain = chains?.[row.object];
+    if (!Array.isArray(chain) || chain.length < 2) continue;
+    const root = chain[chain.length - 1];
+    if (!root || root === row.object) continue;
+    rootCount.set(root, (rootCount.get(root) || 0) + 1);
+    if (!rootRows.has(root)) rootRows.set(root, []);
+    rootRows.get(root).push(row);
+  }
+  const roots = [...rootCount.keys()]
+    .sort((a, b) => (rootCount.get(b) - rootCount.get(a)) || a.localeCompare(b))
+    .slice(0, Math.max(0, count));
+  const rows = [];
+  const seen = new Set();
+  for (const root of roots) for (const r of rootRows.get(root) || []) {
+    if (!seen.has(r.id)) { seen.add(r.id); rows.push(r); }
+  }
+  return { roots, rows };
+}
+
+/** Compose the isa (definition) sentences. Gated purely on how many isa facts
+ *  survived selection: none says nothing; one renders the single or chained
+ *  form; a handful (up to the split threshold) merges into one clause. Past the
+ *  threshold the run-on breaks apart — an opener names the top concepts, body
+ *  sentences group the rest by shared parent, and a closer names the roots they
+ *  all sit under. Returns tagged sentence objects, or an empty list. */
+function composeIsaSection(isaRows, chains, term, table, config) {
+  const out = [];
+  if (!isaRows.length) return out;
+
+  if (isaRows.length === 1) {
+    const chain = chains[isaRows[0].object];
+    const form = chain && chain.length > 1 ? "chained" : "single";
+    const s = renderStructure(table, "isa", isaRows, { term, form, chain });
+    if (s) out.push({ ...s, role: "names-term", paragraph: "definition" });
+    return out;
+  }
+
+  if (isaRows.length <= config.groupSplitThreshold) {
+    const s = renderStructure(table, "isa", isaRows, { term, form: "several" });
+    if (s) out.push({ ...s, role: "names-term", paragraph: "definition" });
+    return out;
+  }
+
+  const openerRows = isaRows.slice(0, config.openerConceptCount);
+  const restRows = isaRows.slice(config.openerConceptCount);
+  const opener = renderStructure(table, "isa", openerRows, {
+    term, form: openerRows.length > 1 ? "several" : "single", variantSeed: term,
+  });
+  if (opener) out.push({ ...opener, role: "names-term", paragraph: "definition" });
+
+  let units = [];
+  for (const g of groupIsaByParent(restRows, chains)) {
+    for (const c of chunk(g.rows, config.maxObjectsPerBodySentence)) units.push({ parent: g.parent, rows: c });
+  }
+  // Cap the sentence count. Overflow folds into the last sentence rather than
+  // drop a selected fact — the merged sentence loses its single-parent coherence,
+  // so it renders as a plain "several" clause.
+  if (units.length > config.maxBodySentences) {
+    const kept = units.slice(0, config.maxBodySentences);
+    const last = kept[kept.length - 1];
+    for (const o of units.slice(config.maxBodySentences)) last.rows = last.rows.concat(o.rows);
+    last.parent = null;
+    units = kept;
+  }
+  for (const u of units) {
+    const s = u.parent
+      ? renderStructure(table, "isa", u.rows, { term, form: "group", parent: u.parent, variantSeed: u.parent })
+      : renderStructure(table, "isa", u.rows, { term, form: "several", variantSeed: term });
+    if (s) out.push({ ...s, role: "describes-isa", paragraph: "definition" });
+  }
+
+  const { roots, rows: closerRows } = closerRootsFor(chains, isaRows, config.closerRootCount);
+  if (roots.length) {
+    const s = renderStructure(table, "isa", closerRows.length ? closerRows : isaRows, {
+      term, form: "closer", objectsOverride: roots, variantSeed: term,
+    });
+    if (s) out.push({ ...s, role: "closes-isa", paragraph: "definition" });
+  }
+  return out;
+}
+
 /** The first sentence must introduce the term. When no isa fact led (so the
  *  first sentence opens with a bare "It"), rewrite that pronoun into the term's
  *  own noun phrase so the pronoun has an antecedent. */
@@ -59,8 +191,11 @@ function paragraphsFrom(sentences, cap) {
  *
  * opts:
  *   - chains: { object -> [object, parent, …] } ancestry chains, so a lone isa
- *     fact can render as a chain ("a mammal, and so an animal") when one exists.
+ *     fact can render as a chain ("a mammal, and so an animal") when one exists,
+ *     and a many-fact term can split into opener, grouped body and closer.
  *   - maxSentencesPerParagraph: the sentence cap (default 3).
+ *   - config: digest tuning overrides (the group split threshold and the
+ *     per-sentence / per-digest caps), defaulting to config.json.
  *
  * Returns { term, sentences, paragraphs, provenanceRows }. Every sentence in
  * `sentences` carries { text, rows, family, role, paragraph }; `paragraphs`
@@ -71,22 +206,19 @@ export function composeTermDigest(selection, table, opts = {}) {
   const term = selection?.term || "";
   const cap = Number.isInteger(opts.maxSentencesPerParagraph) ? opts.maxSentencesPerParagraph : 3;
   const chains = opts.chains || {};
+  const config = { ...DEFAULT_CONFIG, ...(opts.config || {}) };
   const byFamily = rowsByFamily(selection?.selected || []);
   const sentences = [];
 
-  const isaRows = byFamily.get("isa") || [];
-  if (isaRows.length) {
-    const chain = isaRows.length === 1 ? chains[isaRows[0].object] : null;
-    const form = chain && chain.length > 1 ? "chained" : (isaRows.length > 1 ? "several" : "single");
-    const s = renderStructure(table, "isa", isaRows, { term, form, chain });
-    if (s) sentences.push({ ...s, role: "names-term", paragraph: "definition" });
-  }
+  for (const s of composeIsaSection(byFamily.get("isa") || [], chains, term, table, config)) sentences.push(s);
 
   for (const family of DESCRIPTION_FAMILIES) {
     const rows = byFamily.get(family);
     if (!rows || !rows.length) continue;
-    const s = renderStructure(table, family, rows, { term });
-    if (s) sentences.push({ ...s, role: "describes", paragraph: "description" });
+    for (const c of chunk(rows, config.maxObjectsPerBodySentence)) {
+      const s = renderStructure(table, family, c, { term });
+      if (s) sentences.push({ ...s, role: "describes", paragraph: "description" });
+    }
   }
 
   ensureFirstNamesTerm(sentences, term);

package/src/domain/digest/config.json

@@ -4,6 +4,11 @@
   "entailedDepthPenalty": 0.2,
   "minoritySensePenalty": 0.5,
   "minScore": 0.05,
+  "groupSplitThreshold": 4,
+  "openerConceptCount": 2,
+  "maxObjectsPerBodySentence": 4,
+  "maxBodySentences": 4,
+  "closerRootCount": 2,
   "budget": {
     "chatReply": 5,
     "researchPanel": 10,

package/src/domain/digest/structures.mjs

@@ -6,9 +6,10 @@
 // sibling word helpers.
 
 import { articleFor, pluralOf, capitalizeFirst, series } from "./words.mjs";
+import { fnv1a32 } from "../hash.mjs";
 
 const VALID_FAMILIES = new Set(["isa", "location", "partOf", "capableOf", "usedFor"]);
-const VALID_FORMS = new Set(["single", "several", "chained"]);
+const VALID_FORMS = new Set(["single", "several", "chained", "group", "closer"]);
 
 const keyFor = (family, form) => `${family}:${form}`;
 
@@ -16,8 +17,10 @@ const keyFor = (family, form) => `${family}:${form}`;
  * Validate and index the raw [[structure]] rows into a Map keyed by
  * `family:form`. Closed-vocabulary discipline, same as the construction banks:
  * an unknown family or form, or a missing template, drops the row rather than
- * coercing it. First occurrence of a (family, form) wins; a later duplicate is
- * ignored.
+ * coercing it. Every valid row for a (family, form) is collected into that
+ * key's `templates` list, so the renderer can pick one deterministically from
+ * the pool; an exact-string duplicate is folded, but a second distinct wording
+ * is kept as another variant.
  */
 export function buildStructureTable(structures) {
   const table = new Map();
@@ -26,8 +29,9 @@ export function buildStructureTable(structures) {
     if (typeof s.form !== "string" || !VALID_FORMS.has(s.form)) continue;
     if (typeof s.template !== "string" || !s.template.trim()) continue;
     const key = keyFor(s.family, s.form);
-    if (table.has(key)) continue;
-    table.set(key, { family: s.family, form: s.form, template: s.template });
+    if (!table.has(key)) table.set(key, { family: s.family, form: s.form, templates: [] });
+    const entry = table.get(key);
+    if (!entry.templates.includes(s.template)) entry.templates.push(s.template);
   }
   return table;
 }
@@ -44,12 +48,15 @@ function renderChain(chain) {
   return `${head}, and so ${series(rest.map(withArticle))}`;
 }
 
-/** The slot values for one render, derived from the term, its objects and an
- *  optional ancestry chain. A placeholder with no derived value renders empty. */
-function slotsFor(term, objects, chain) {
+/** The slot values for one render, derived from the term, its objects, an
+ *  optional ancestry chain and an optional parent class (the shared immediate
+ *  ancestor a `group` sentence hangs off). A placeholder with no derived value
+ *  renders empty. */
+function slotsFor(term, objects, chain, parent) {
   const t = String(term || "").trim();
   const objs = (objects || []).map((o) => String(o || "").trim()).filter(Boolean);
   const first = objs[0] || "";
+  const p = String(parent || "").trim();
   return {
     TERM: t,
     TERM_CAP: capitalizeFirst(t),
@@ -59,6 +66,8 @@ function slotsFor(term, objects, chain) {
     TERMS_CAP: capitalizeFirst(pluralOf(t)),
     PRONOUN: "it",
     PRONOUN_CAP: "It",
+    PARENT: p,
+    A_PARENT: p ? withArticle(p) : "",
     OBJECT: first,
     A_OBJECT: first ? withArticle(first) : "",
     OBJECTS_A: series(objs.map(withArticle)),
@@ -82,9 +91,22 @@ function fill(template, slots) {
  * Render one clause for `facts` (all of one family) using the structure the
  * table holds for (family, form). `form` defaults by fact count — one fact is
  * "single", more is "several" — unless the caller names a form (e.g. "chained"
- * with an ancestry chain). Returns { text, rows, family, form } so the sentence
- * traces to the exact fact rows behind it, or null when no structure matches or
- * there are no facts.
+ * with an ancestry chain, or "group"/"closer" for the multi-sentence isa body).
+ *
+ * When a key holds more than one wording, the one that renders is picked by a
+ * deterministic FNV-1a hash of `term|family|form|variantSeed` — the same
+ * paraphrase-pool tool answer-variants.mjs uses — so the choice is stable across
+ * runs but varies by term (and by `variantSeed`, e.g. the shared parent, so two
+ * group sentences under one term can read differently). A single-wording key
+ * always resolves to that one wording.
+ *
+ * `opts.objectsOverride` renders words other than the raw fact objects (a closer
+ * sentence names root concepts, not the facts) while the returned `rows` stays
+ * the real backing facts, so provenance survives. `opts.parent` fills the
+ * `{PARENT}`/`{A_PARENT}` slots a group sentence hangs off.
+ *
+ * Returns { text, rows, family, form } so the sentence traces to the exact fact
+ * rows behind it, or null when no structure matches or there are no facts.
  */
 export function renderStructure(table, family, facts, opts = {}) {
   const rows = (facts || []).filter(Boolean);
@@ -92,9 +114,12 @@ export function renderStructure(table, family, facts, opts = {}) {
   const term = opts.term ?? rows[0].subject ?? "";
   const form = opts.form || (rows.length > 1 ? "several" : "single");
   const entry = table instanceof Map ? table.get(keyFor(family, form)) : null;
-  if (!entry) return null;
-  const objects = rows.map((r) => r.object);
-  const text = fill(entry.template, slotsFor(term, objects, opts.chain));
+  const templates = entry ? entry.templates : null;
+  if (!templates || !templates.length) return null;
+  const variantSeed = opts.variantSeed ?? "";
+  const idx = fnv1a32(`${term}|${family}|${form}|${variantSeed}`) % templates.length;
+  const objects = opts.objectsOverride || rows.map((r) => r.object);
+  const text = fill(templates[idx], slotsFor(term, objects, opts.chain, opts.parent));
   if (!text) return null;
   return { text, rows, family, form };
 }

package/src/domain/interpret/normalize.mjs

@@ -110,10 +110,10 @@ const INTERROGATIVE_LEAD_RE = /^(?:which|what|who|whose|where|when|why|how)\b/i;
  *  untouched so that working path keeps it. Two shapes: a plural kind noun in
  *  tail position, or a bare (det +) singular kind noun and nothing else. */
 const LISTING_TAIL_KINDS = new Set([
-  "modules", "files", "functions", "methods", "classes", "attributes", "fields",
+  "modules", "files", "packages", "functions", "methods", "classes", "attributes", "fields",
   "properties", "variables", "globals", "commits", "changes", "tests", "members",
 ]);
-const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
+const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|package|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
 const isListingRemainder = (rest) => {
   if (BARE_KIND_RE.test(rest)) return true;
   const words = rest.replace(/\?+\s*$/, "").trim().split(/\s+/);

package/src/domain/reference-pack.mjs

@@ -12,6 +12,10 @@ import { RELATION_TERM } from "./concept.mjs";
 export const REFERENCE_PACK_NAME = "simplewiki";
 export const REFERENCE_SHARD_COUNT = 64;
 
+/** The grain cue every encyclopedia-grounded answer carries: this is a word's
+ *  general meaning, not something read out of the graph the session is about. */
+export const GENERAL_VOCABULARY_CUE = "General vocabulary, not from this codebase.";
+
 /** The shard a term's article row lives in: FNV-1a first byte mod 64, as the
  *  file basename "ref-00" … "ref-3f". Part of the pack's on-disk contract —
  *  the build script shards with THIS function, so the reader never scans. */
@@ -43,10 +47,14 @@ export function isReferenceArticleRow(row) {
 }
 
 /** The cited answer for a clean miss the pack could ground: the article's
- *  summary with its title, licence and revision-pinned URL always visible. */
+ *  summary with its title, licence and revision-pinned URL always visible,
+ *  then the grain cue. Without the cue a reader has to recognize the source
+ *  name to tell this apart from a fact read out of their own graph — both
+ *  answer the same "what is X" question in the same voice. */
 export function renderReferenceAnswer(term, article) {
   return `${term} — ${article.summary} (source: reference article "${article.title}", `
-    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`
+    + ` ${GENERAL_VOCABULARY_CUE}`;
 }
 
 /** The provenance tag a fact stored from a pack article carries —
@@ -88,7 +96,8 @@ export function liveProvenanceTag(article) {
  *  the revision-pinned URL always visible. */
 export function renderLiveReferenceAnswer(term, article) {
   return `${term} — ${article.summary} (source: live Wikipedia article "${article.title}", `
-    + `English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+    + `English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`
+    + ` ${GENERAL_VOCABULARY_CUE}`;
 }
 
 /** The pure half of the LIVE clean-miss gate — same fold, shape check and

package/src/domain/router/call-validator.mjs

@@ -1,6 +1,6 @@
 // src/domain/router/call-validator.mjs — pure registry validators shared by the
 // product router (resolver / goal-reasoner) + the bench grader
-// (agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
+// (test-benchmarks/agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
 // bench code — so the product←bench dependency stays inverted: the bench
 // imports the product, never the other way round. No I/O, no Date.now, no LLM.
 

package/src/domain/router/drive.mjs

@@ -243,8 +243,8 @@ export async function runTaughtPlan(request, tools, ctx) {
 /** The full drive: resolver/planner first; a refusal there falls through to
  *  the taught world-goal lane (runTaughtPlan, above), and only a request that
  *  is not a world goal escalates to the closed-world goal-reasoner. Mirrors
- *  agentbench's driver-resolver.mjs + driver-goal.mjs composition, with no
- *  agentbench/ dependency (agentbench/ is dev-only, never shipped). Returns a
+ *  test-benchmarks/agentbench's driver-resolver.mjs + driver-goal.mjs composition, with no
+ *  test-benchmarks/agentbench/ dependency (test-benchmarks/agentbench/ is dev-only, never shipped). Returns a
  *  loopResult:
  *  `{ calls, refused, terminated, proof, why, driver, composed?, observed?, candidateResults? }`.
  *