@polycode-projects/the-mechanical-code-talker 5.0.12 → 5.0.14

package/corpus/tier2/generate.mjs

@@ -14071,8 +14071,11 @@ export const CORPUSES = {
       ["humanistic discipline", "/r/IsA", "discipline"],
       ["nub", "/r/IsA", "content"],
       ["vow", "/r/IsA", "assurance"],
-      ["beta", "/r/IsA", "letter"],
-      ["letter", "/r/IsA", "character"],
+      ["beta", "/r/IsA", "greek letter"],
+      ["letter of the alphabet", "/r/IsA", "character"],
+      ["greek letter", "/r/IsA", "letter of the alphabet"],
+      ["alpha", "/r/IsA", "greek letter"],
+      ["letter", "/r/RelatedTo", "letter of the alphabet"],
       ["written symbol", "/r/IsA", "symbol"],
       ["brag", "/r/IsA", "boast"],
       ["boast", "/r/IsA", "speech act"],
@@ -14119,7 +14122,7 @@ export const CORPUSES = {
       ["dynamical system", "/r/IsA", "phase space"],
       ["phase space", "/r/IsA", "space"],
       ["conga", "/r/IsA", "dance music"],
-      ["delta", "/r/IsA", "letter"],
+      ["delta", "/r/IsA", "greek letter"],
       ["demur", "/r/IsA", "objection"],
       ["dread", "/r/IsA", "fear"],
       ["fable", "/r/IsA", "story"],
@@ -14265,7 +14268,7 @@ export const CORPUSES = {
       ["gradual", "/r/IsA", "antiphon"],
       ["antiphon", "/r/IsA", "religious music"],
       ["gravity", "/r/IsA", "feeling"],
-      ["initial", "/r/IsA", "letter"],
+      ["initial", "/r/IsA", "letter of the alphabet"],
       ["inquiry", "/r/IsA", "questioning"],
       ["lingual", "/r/IsA", "consonant"],
       ["loyalty", "/r/IsA", "love"],
@@ -14725,8 +14728,8 @@ export const CORPUSES = {
       ["description", "/r/IsA", "speech act"],
       ["predetermination", "/r/IsA", "decision"],
       ["decision", "/r/IsA", "judgment"],
-      ["pi", "/r/IsA", "letter"],
-      ["xi", "/r/IsA", "letter"],
+      ["pi", "/r/IsA", "greek letter"],
+      ["xi", "/r/IsA", "greek letter"],
       ["boo", "/r/IsA", "cry"],
       ["bye", "/r/IsA", "concession"],
       ["concession", "/r/IsA", "assent"],
@@ -14738,7 +14741,7 @@ export const CORPUSES = {
       ["nay", "/r/IsA", "negative"],
       ["pic", "/r/IsA", "product"],
       ["pic", "/r/HasA", "sequence"],
-      ["psi", "/r/IsA", "letter"],
+      ["psi", "/r/IsA", "greek letter"],
       ["pun", "/r/IsA", "fun"],
       ["wai", "/r/IsA", "gesture"],
       ["woe", "/r/IsA", "mournfulness"],
@@ -14754,7 +14757,7 @@ export const CORPUSES = {
       ["grin", "/r/IsA", "facial expression"],
       ["heed", "/r/IsA", "attention"],
       ["idyl", "/r/IsA", "musical composition"],
-      ["iota", "/r/IsA", "letter"],
+      ["iota", "/r/IsA", "greek letter"],
       ["jive", "/r/IsA", "jazz"],
       ["moan", "/r/IsA", "utterance"],
       ["muse", "/r/IsA", "source"],
@@ -14812,7 +14815,7 @@ export const CORPUSES = {
       ["emotional arousal", "/r/IsA", "arousal"],
       ["arousal", "/r/IsA", "physical condition"],
       ["frown", "/r/IsA", "facial expression"],
-      ["gamma", "/r/IsA", "letter"],
+      ["gamma", "/r/IsA", "greek letter"],
       ["gamut", "/r/IsA", "scale"],
       ["scale", "/r/IsA", "musical notation"],
       ["grief", "/r/IsA", "negative stimulus"],
@@ -14824,7 +14827,7 @@ export const CORPUSES = {
       ["macro", "/r/IsA", "instruction"],
       ["instruction", "/r/IsA", "code"],
       ["odour", "/r/IsA", "sensation"],
-      ["omega", "/r/IsA", "letter"],
+      ["omega", "/r/IsA", "greek letter"],
       ["paean", "/r/IsA", "hymn"],
       ["pavan", "/r/IsA", "dance music"],
       ["peeve", "/r/IsA", "temper"],

package/corpus/tier2/human-large.jsonl

@@ -11223,8 +11223,11 @@
 {"start":"/c/en/humanistic discipline","rel":"/r/IsA","end":"/c/en/discipline","weight":1,"surfaceText":"[[humanistic discipline]] IsA [[discipline]]"}
 {"start":"/c/en/nub","rel":"/r/IsA","end":"/c/en/content","weight":1,"surfaceText":"[[nub]] IsA [[content]]"}
 {"start":"/c/en/vow","rel":"/r/IsA","end":"/c/en/assurance","weight":1,"surfaceText":"[[vow]] IsA [[assurance]]"}
-{"start":"/c/en/beta","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[beta]] IsA [[letter]]"}
-{"start":"/c/en/letter","rel":"/r/IsA","end":"/c/en/character","weight":1,"surfaceText":"[[letter]] IsA [[character]]"}
+{"start":"/c/en/beta","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[beta]] IsA [[greek letter]]"}
+{"start":"/c/en/letter of the alphabet","rel":"/r/IsA","end":"/c/en/character","weight":1,"surfaceText":"[[letter of the alphabet]] IsA [[character]]"}
+{"start":"/c/en/greek letter","rel":"/r/IsA","end":"/c/en/letter of the alphabet","weight":1,"surfaceText":"[[greek letter]] IsA [[letter of the alphabet]]"}
+{"start":"/c/en/alpha","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[alpha]] IsA [[greek letter]]"}
+{"start":"/c/en/letter","rel":"/r/RelatedTo","end":"/c/en/letter of the alphabet","weight":1,"surfaceText":"[[letter]] RelatedTo [[letter of the alphabet]]"}
 {"start":"/c/en/written symbol","rel":"/r/IsA","end":"/c/en/symbol","weight":1,"surfaceText":"[[written symbol]] IsA [[symbol]]"}
 {"start":"/c/en/brag","rel":"/r/IsA","end":"/c/en/boast","weight":1,"surfaceText":"[[brag]] IsA [[boast]]"}
 {"start":"/c/en/boast","rel":"/r/IsA","end":"/c/en/speech act","weight":1,"surfaceText":"[[boast]] IsA [[speech act]]"}
@@ -11271,7 +11274,7 @@
 {"start":"/c/en/dynamical system","rel":"/r/IsA","end":"/c/en/phase space","weight":1,"surfaceText":"[[dynamical system]] IsA [[phase space]]"}
 {"start":"/c/en/phase space","rel":"/r/IsA","end":"/c/en/space","weight":1,"surfaceText":"[[phase space]] IsA [[space]]"}
 {"start":"/c/en/conga","rel":"/r/IsA","end":"/c/en/dance music","weight":1,"surfaceText":"[[conga]] IsA [[dance music]]"}
-{"start":"/c/en/delta","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[delta]] IsA [[letter]]"}
+{"start":"/c/en/delta","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[delta]] IsA [[greek letter]]"}
 {"start":"/c/en/demur","rel":"/r/IsA","end":"/c/en/objection","weight":1,"surfaceText":"[[demur]] IsA [[objection]]"}
 {"start":"/c/en/dread","rel":"/r/IsA","end":"/c/en/fear","weight":1,"surfaceText":"[[dread]] IsA [[fear]]"}
 {"start":"/c/en/fable","rel":"/r/IsA","end":"/c/en/story","weight":1,"surfaceText":"[[fable]] IsA [[story]]"}
@@ -11417,7 +11420,7 @@
 {"start":"/c/en/gradual","rel":"/r/IsA","end":"/c/en/antiphon","weight":1,"surfaceText":"[[gradual]] IsA [[antiphon]]"}
 {"start":"/c/en/antiphon","rel":"/r/IsA","end":"/c/en/religious music","weight":1,"surfaceText":"[[antiphon]] IsA [[religious music]]"}
 {"start":"/c/en/gravity","rel":"/r/IsA","end":"/c/en/feeling","weight":1,"surfaceText":"[[gravity]] IsA [[feeling]]"}
-{"start":"/c/en/initial","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[initial]] IsA [[letter]]"}
+{"start":"/c/en/initial","rel":"/r/IsA","end":"/c/en/letter of the alphabet","weight":1,"surfaceText":"[[initial]] IsA [[letter of the alphabet]]"}
 {"start":"/c/en/inquiry","rel":"/r/IsA","end":"/c/en/questioning","weight":1,"surfaceText":"[[inquiry]] IsA [[questioning]]"}
 {"start":"/c/en/lingual","rel":"/r/IsA","end":"/c/en/consonant","weight":1,"surfaceText":"[[lingual]] IsA [[consonant]]"}
 {"start":"/c/en/loyalty","rel":"/r/IsA","end":"/c/en/love","weight":1,"surfaceText":"[[loyalty]] IsA [[love]]"}
@@ -11877,8 +11880,8 @@
 {"start":"/c/en/description","rel":"/r/IsA","end":"/c/en/speech act","weight":1,"surfaceText":"[[description]] IsA [[speech act]]"}
 {"start":"/c/en/predetermination","rel":"/r/IsA","end":"/c/en/decision","weight":1,"surfaceText":"[[predetermination]] IsA [[decision]]"}
 {"start":"/c/en/decision","rel":"/r/IsA","end":"/c/en/judgment","weight":1,"surfaceText":"[[decision]] IsA [[judgment]]"}
-{"start":"/c/en/pi","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[pi]] IsA [[letter]]"}
-{"start":"/c/en/xi","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[xi]] IsA [[letter]]"}
+{"start":"/c/en/pi","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[pi]] IsA [[greek letter]]"}
+{"start":"/c/en/xi","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[xi]] IsA [[greek letter]]"}
 {"start":"/c/en/boo","rel":"/r/IsA","end":"/c/en/cry","weight":1,"surfaceText":"[[boo]] IsA [[cry]]"}
 {"start":"/c/en/bye","rel":"/r/IsA","end":"/c/en/concession","weight":1,"surfaceText":"[[bye]] IsA [[concession]]"}
 {"start":"/c/en/concession","rel":"/r/IsA","end":"/c/en/assent","weight":1,"surfaceText":"[[concession]] IsA [[assent]]"}
@@ -11890,7 +11893,7 @@
 {"start":"/c/en/nay","rel":"/r/IsA","end":"/c/en/negative","weight":1,"surfaceText":"[[nay]] IsA [[negative]]"}
 {"start":"/c/en/pic","rel":"/r/IsA","end":"/c/en/product","weight":1,"surfaceText":"[[pic]] IsA [[product]]"}
 {"start":"/c/en/pic","rel":"/r/HasA","end":"/c/en/sequence","weight":1,"surfaceText":"[[pic]] HasA [[sequence]]"}
-{"start":"/c/en/psi","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[psi]] IsA [[letter]]"}
+{"start":"/c/en/psi","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[psi]] IsA [[greek letter]]"}
 {"start":"/c/en/pun","rel":"/r/IsA","end":"/c/en/fun","weight":1,"surfaceText":"[[pun]] IsA [[fun]]"}
 {"start":"/c/en/wai","rel":"/r/IsA","end":"/c/en/gesture","weight":1,"surfaceText":"[[wai]] IsA [[gesture]]"}
 {"start":"/c/en/woe","rel":"/r/IsA","end":"/c/en/mournfulness","weight":1,"surfaceText":"[[woe]] IsA [[mournfulness]]"}
@@ -11906,7 +11909,7 @@
 {"start":"/c/en/grin","rel":"/r/IsA","end":"/c/en/facial expression","weight":1,"surfaceText":"[[grin]] IsA [[facial expression]]"}
 {"start":"/c/en/heed","rel":"/r/IsA","end":"/c/en/attention","weight":1,"surfaceText":"[[heed]] IsA [[attention]]"}
 {"start":"/c/en/idyl","rel":"/r/IsA","end":"/c/en/musical composition","weight":1,"surfaceText":"[[idyl]] IsA [[musical composition]]"}
-{"start":"/c/en/iota","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[iota]] IsA [[letter]]"}
+{"start":"/c/en/iota","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[iota]] IsA [[greek letter]]"}
 {"start":"/c/en/jive","rel":"/r/IsA","end":"/c/en/jazz","weight":1,"surfaceText":"[[jive]] IsA [[jazz]]"}
 {"start":"/c/en/moan","rel":"/r/IsA","end":"/c/en/utterance","weight":1,"surfaceText":"[[moan]] IsA [[utterance]]"}
 {"start":"/c/en/muse","rel":"/r/IsA","end":"/c/en/source","weight":1,"surfaceText":"[[muse]] IsA [[source]]"}
@@ -11964,7 +11967,7 @@
 {"start":"/c/en/emotional arousal","rel":"/r/IsA","end":"/c/en/arousal","weight":1,"surfaceText":"[[emotional arousal]] IsA [[arousal]]"}
 {"start":"/c/en/arousal","rel":"/r/IsA","end":"/c/en/physical condition","weight":1,"surfaceText":"[[arousal]] IsA [[physical condition]]"}
 {"start":"/c/en/frown","rel":"/r/IsA","end":"/c/en/facial expression","weight":1,"surfaceText":"[[frown]] IsA [[facial expression]]"}
-{"start":"/c/en/gamma","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[gamma]] IsA [[letter]]"}
+{"start":"/c/en/gamma","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[gamma]] IsA [[greek letter]]"}
 {"start":"/c/en/gamut","rel":"/r/IsA","end":"/c/en/scale","weight":1,"surfaceText":"[[gamut]] IsA [[scale]]"}
 {"start":"/c/en/scale","rel":"/r/IsA","end":"/c/en/musical notation","weight":1,"surfaceText":"[[scale]] IsA [[musical notation]]"}
 {"start":"/c/en/grief","rel":"/r/IsA","end":"/c/en/negative stimulus","weight":1,"surfaceText":"[[grief]] IsA [[negative stimulus]]"}
@@ -11976,7 +11979,7 @@
 {"start":"/c/en/macro","rel":"/r/IsA","end":"/c/en/instruction","weight":1,"surfaceText":"[[macro]] IsA [[instruction]]"}
 {"start":"/c/en/instruction","rel":"/r/IsA","end":"/c/en/code","weight":1,"surfaceText":"[[instruction]] IsA [[code]]"}
 {"start":"/c/en/odour","rel":"/r/IsA","end":"/c/en/sensation","weight":1,"surfaceText":"[[odour]] IsA [[sensation]]"}
-{"start":"/c/en/omega","rel":"/r/IsA","end":"/c/en/letter","weight":1,"surfaceText":"[[omega]] IsA [[letter]]"}
+{"start":"/c/en/omega","rel":"/r/IsA","end":"/c/en/greek letter","weight":1,"surfaceText":"[[omega]] IsA [[greek letter]]"}
 {"start":"/c/en/paean","rel":"/r/IsA","end":"/c/en/hymn","weight":1,"surfaceText":"[[paean]] IsA [[hymn]]"}
 {"start":"/c/en/pavan","rel":"/r/IsA","end":"/c/en/dance music","weight":1,"surfaceText":"[[pavan]] IsA [[dance music]]"}
 {"start":"/c/en/peeve","rel":"/r/IsA","end":"/c/en/temper","weight":1,"surfaceText":"[[peeve]] IsA [[temper]]"}

package/corpus/tier2/manifest.json

@@ -95,9 +95,9 @@
         "tool": "corpus/tier2/generate.mjs"
       },
       "file": "human-large.jsonl",
-      "facts": 11999,
-      "bytes": 1464616,
-      "sha256": "fbbe8135d4915f2bc041bf577e7b0bd1a8fd1c1bab804c8215b1d05e39db27f9",
+      "facts": 12002,
+      "bytes": 1465216,
+      "sha256": "ac35618d54ae98092220f601f7d73736863d56ed1a5bd44a7cfbde252ec5ea2f",
       "license": "MPL-2.0"
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "5.0.12",
+  "version": "5.0.14",
   "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.",

package/src/domain/digest/store-stats.mjs

@@ -12,6 +12,7 @@
 // the selector stays a function of its inputs.
 
 import { subClassParents, ancestryChain } from "../sense-split.mjs";
+import { ANSWER_STOP_SET } from "../hub-terms.mjs";
 
 // The predicates the digest groups under the isa family (kept in step with
 // select.mjs's FAMILY_OF): a subclass edge and a type edge both name a class
@@ -56,7 +57,7 @@ export function chainsForObjects(subClassEdges, objects, cap = 6) {
   const chains = {};
   for (const obj of objects || []) {
     if (obj in chains) continue;
-    const chain = ancestryChain(obj, parents, { cap });
+    const chain = ancestryChain(obj, parents, { cap, stopAt: ANSWER_STOP_SET });
     if (chain.length > 1) chains[obj] = chain;
   }
   return chains;

package/src/domain/hub-terms.mjs

@@ -0,0 +1,29 @@
+// hub-terms.mjs — the class-hierarchy terms too abstract for a plain-English
+// answer to climb into, whichever caller is walking a superclass chain. A
+// leaf module (no imports) so both the persona-tier curator (a corpus build
+// script, heavy WordNet-walking logic that has no business in a browser
+// bundle) and sense-split.mjs's runtime chain walker (bundled client-side by
+// the digest layer) can depend on the same set without either pulling in
+// the other's weight.
+
+// human-base's own category roots, plus every hypernym TARGET term Small's
+// curation already established as a "root" word (generate.mjs's own comment:
+// "category-root nouns used as a hypernym TARGET") — a real hypernym chain
+// walk stops here rather than continuing on to WordNet's ultra-abstract
+// "entity"/"abstraction"/"physical_entity" tops, which would add depth
+// without adding anything a plain-English question would ever ask about.
+export const STOP_SET = new Set([
+  "person", "place", "object", "event", "time", "quantity", "organization", "group",
+  "animal", "plant", "furniture", "vehicle", "insect", "emotion", "metal", "liquid",
+  "weather", "planet", "jewelry", "cutlery", "government", "material", "artifact",
+  "location", "structure", "food", "drink", "clothing", "body", "language", "mind",
+  "family", "meal", "season", "number", "entity", "abstraction", "physical_entity",
+  "attribute", "state", "act", "communication", "cognition", "measure", "unit",
+]);
+
+// A wider hub set for a chat ANSWER's own chain rendering, where the climb
+// walks further than the persona-tier corpus curation ever needs to: without
+// it a plain "what is a letter" chain runs on past "character" into
+// "property → concept → idea → content", each step less concrete than the
+// last. STOP_SET itself stays exactly as the persona-tier curator reads it.
+export const ANSWER_STOP_SET = new Set([...STOP_SET, "property", "concept", "idea", "content"]);

package/src/domain/persona/tiers.mjs

@@ -7,20 +7,13 @@
 // scripts/lib/wordnet-source.mjs, the fact targets and the run itself in
 // scripts/build-persona-tiers.mjs.
 
-// human-base's own category roots, plus every hypernym TARGET term Small's
-// curation already established as a "root" word (generate.mjs's own comment:
-// "category-root nouns used as a hypernym TARGET") — a real hypernym chain
-// walk stops here rather than continuing on to WordNet's ultra-abstract
-// "entity"/"abstraction"/"physical_entity" tops, which would add depth
-// without adding anything a plain-English question would ever ask about.
-export const STOP_SET = new Set([
-  "person", "place", "object", "event", "time", "quantity", "organization", "group",
-  "animal", "plant", "furniture", "vehicle", "insect", "emotion", "metal", "liquid",
-  "weather", "planet", "jewelry", "cutlery", "government", "material", "artifact",
-  "location", "structure", "food", "drink", "clothing", "body", "language", "mind",
-  "family", "meal", "season", "number", "entity", "abstraction", "physical_entity",
-  "attribute", "state", "act", "communication", "cognition", "measure", "unit",
-]);
+// The hub-word stop set lives in ../hub-terms.mjs (re-exported here for every
+// existing caller of this module) so sense-split.mjs's runtime chain walker
+// can share it without importing this whole build-time curation module —
+// this file's other exports (buildClump, stripDenylisted, …) are WordNet-walk
+// logic with no business in the browser bundle the digest layer links into.
+import { STOP_SET } from "../hub-terms.mjs";
+export { STOP_SET };
 
 export const BLOCKLIST_RE = /\b(archaic|obsolete|offensive|derogatory|informal|slang|dialect|euphemism|hypothetical|imaginary|mythical|mythology|extraterrestrial|fictional|taxonomic genus|genus of|family [A-Z]|nonstandard|vulgar|disparaging|obscene|coarse|genital|ethnic slur|ethnic epithet|excrement|contemptuous|insulting|trade name|street name|controlled substance|illegal|sexual assault|monoclonal antibody|chemical compound|chemical formula|proprietary name)\b/i;
 

package/src/domain/sense-split.mjs

@@ -16,6 +16,9 @@
 //   5. otherwise                     -> not distinct.
 
 import { SUBCLASS_PREDICATE } from "./syllogise.mjs";
+import { STOP_SET } from "./hub-terms.mjs";
+
+export { STOP_SET };
 
 /** child term -> Set of its direct superclasses, from `[child, parent]` edges.
  *  Self-loops and blank endpoints are dropped. */
@@ -29,20 +32,82 @@ export function subClassParents(subClassEdges) {
   return parents;
 }
 
+/** Codepoint string order. Deliberately not localeCompare: the walks below
+ *  must return the same set on any machine and any ICU version. */
+const compareStrings = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** parent term -> Set of its direct subclasses, from `[child, parent]` edges.
+ *  The mirror of subClassParents. Self-loops and blank endpoints are dropped. */
+export function subClassChildren(subClassEdges) {
+  const children = new Map();
+  for (const [child, parent] of subClassEdges || []) {
+    if (!child || !parent || child === parent) continue;
+    if (!children.has(parent)) children.set(parent, new Set());
+    children.get(parent).add(child);
+  }
+  return children;
+}
+
+/** Every class reachable BELOW `seeds` through subClassOf edges, including the
+ *  seeds themselves. `seeds` is a string or an iterable of strings.
+ *  Level-ordered BFS with a sorted frontier, so the `cap` truncation is a pure
+ *  function of the edge set rather than of the order the edges arrived in.
+ *  Cycle-safe. */
+export function descendantSet(seeds, children, { cap = 20000 } = {}) {
+  const seen = new Set();
+  let frontier = [...(typeof seeds === "string" ? [seeds] : (seeds || []))]
+    .filter(Boolean).sort(compareStrings);
+  for (const s of frontier) seen.add(s);
+  while (frontier.length && seen.size < cap) {
+    const next = [];
+    for (const node of frontier) for (const c of children.get(node) || []) if (!seen.has(c)) next.push(c);
+    next.sort(compareStrings);
+    frontier = [];
+    for (const c of next) {
+      if (seen.has(c) || seen.size >= cap) continue;
+      seen.add(c);
+      frontier.push(c);
+    }
+  }
+  return seen;
+}
+
 /** The single rendering chain above `term` — `[term, parent, grandparent, …]`
  *  — following one deterministic (lowest-sorted) parent per hop, capped at
  *  `cap` nodes, cycle-safe. A branch point still yields one readable line;
- *  the full-ancestor-set comparisons below never rely on this single path. */
-export function ancestryChain(term, parents, { cap = 6 } = {}) {
+ *  the full-ancestor-set comparisons below never rely on this single path.
+ *
+ *  `stopAt` (e.g. hub-terms.mjs's STOP_SET) names ancestors too abstract for
+ *  a plain-English chain to climb into — "letter → character → property →
+ *  concept" reads fine, "…→ cognition" doesn't. The walk halts BEFORE
+ *  appending a later hub ancestor, so a hub never shows up mid-chain with
+ *  more abstraction stacked past it. The direct first parent is the one
+ *  exception: it is always shown even when it is itself a hub, so a term
+ *  whose only real parent is a hub still renders that one direct parent
+ *  (matching the plain "term is a kind of parent" sentence already stated)
+ *  rather than an empty chain — the walk then still stops right there.
+ *
+ *  `toward` steers which parent the walk follows at a branch point: among a
+ *  node's parents, one that actually reaches `toward` is preferred over the
+ *  lowest-sorted one, so a class with two parents still renders a chain that
+ *  reaches the class the reader asked about. `stopAt` and `toward` compose —
+ *  `toward` only changes which parent is picked, `stopAt` still decides where
+ *  the picked path halts. */
+export function ancestryChain(term, parents, { cap = 6, stopAt = null, toward = null } = {}) {
   const chain = [term];
   const seen = new Set([term]);
   let node = term;
   while (chain.length < cap) {
-    const ups = [...(parents.get(node) || [])].filter((p) => !seen.has(p)).sort();
+    if (toward && node === toward) break;
+    const ups = [...(parents.get(node) || [])].filter((p) => !seen.has(p)).sort(compareStrings);
     if (!ups.length) break;
-    node = ups[0];
+    const onPath = toward ? ups.filter((p) => p === toward || ancestorSet(p, parents).has(toward)) : [];
+    node = (onPath.length ? onPath : ups)[0];
+    const isHub = stopAt && stopAt.has(node);
+    if (isHub && chain.length > 1) break;
     seen.add(node);
     chain.push(node);
+    if (isHub) break;
   }
   return chain;
 }

package/src/services/chat-page-viz.mjs

@@ -80,8 +80,14 @@ function provKey(tier) {
  *
  * Multiple citations (a multi-step proof chain) resolve by the same
  * taught-over-entailed-over-corpus precedence provBucketFor's own header
- * documents for one fact's sourceTypes, applied across citations instead:
- * a chain resting on any taught premise reads as "taught" overall.
+ * documents for one fact's sourceTypes, applied across citations instead —
+ * but only on a real teach turn (`record.via === "assert"`), where the
+ * user's own action IS the taught premise the chip announces. A READ turn
+ * (a question answered by citing stored facts) only earns the "taught" chip
+ * when EVERY citation is taught: one taught fact among otherwise-corpus or
+ * entailed citations is the query resting on background data, not the user
+ * teaching anything, so it falls through to the same entailed-over-corpus
+ * choice a wholly non-taught answer gets.
  *
  * Self-contained (no outer refs beyond the injected `bucketFor`),
  * `.toString()`-splice safe.
@@ -91,7 +97,8 @@ export function provenanceChipFor(answer, record, bucketFor) {
   const cites = [...String(answer || "").matchAll(/\(source: ([^)]+)\)/g)].map((m) => m[1]);
   if (!cites.length) return record.via === "assert" ? "taught" : null;
   const buckets = cites.map((c) => bucketFor([], c));
-  if (buckets.includes("taught")) return "taught";
+  const allTaught = buckets.every((b) => b === "taught");
+  if (buckets.includes("taught") && (record.via === "assert" || allTaught)) return "taught";
   if (buckets.includes("entailed")) return "entailed";
   return "corpus";
 }
@@ -2439,7 +2446,7 @@ ${shareOverlayHtml({ withTape: true })}
       } catch { /* best-effort seeding only — a fresh session has none to seed */ }
     }
     renderResearchedPanel();
-    inputEl.placeholder = seedPayload ? 'try "what is a dog" or "list facts"' : window.tmct.page.vocabExampleHint(false);
+    inputEl.placeholder = seedPayload ? 'try "what is a dog" or "list animals"' : window.tmct.page.vocabExampleHint(false);
     renderStatus();
     setBusy(false);
     inputEl.focus();