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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.5.3",
+  "version": "2.5.4",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

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

@@ -101,7 +101,13 @@ export function registerReferencePackProvider(provider) {
   registeredProvider = provider && typeof provider.lookup === "function" ? provider : null;
 }
 
-/** The active provider — the registered one, else the lazy fs loader. */
-export function getReferencePackProvider() {
-  return registeredProvider ?? fsProvider;
+/** The active provider — the registered one, else the lazy fs loader. An
+ *  explicit `env` bag (a chat turn's own env, which may carry
+ *  TMCT_REFERENCE_PACK_DIR) makes the fs loader resolve the pack dir from
+ *  that bag instead of process.env; with no argument the behavior is
+ *  unchanged. */
+export function getReferencePackProvider(env) {
+  if (registeredProvider) return registeredProvider;
+  if (env === undefined) return fsProvider;
+  return { lookup: async (normTerm) => loadReferenceArticle(referencePackDir(env), normTerm) };
 }

package/src/domain/dialogue-acts.mjs

@@ -142,6 +142,11 @@ export const LANE_DIALOGUE_ACTS = Object.freeze({
   greeting: "initialGreeting",
   thanks: "thanking",
   help: "inform",
+  // The guessing game's turns are task-dimension: a reply that discharges
+  // the other side's move (a hint, a win, a rebuttal) is an answer; tmct
+  // stating its own move (an opening, its next guess) is an inform.
+  "game-answer": "answer",
+  "game-inform": "inform",
 });
 
 /** The dialogue act a router lane resolves to, with its dimension — or null

package/src/services/chat.mjs

@@ -46,6 +46,10 @@ import { readConstructionFiles } from "../adapters/corpus/construction-banks.mjs
 import { fuzzyMatchInSet, fuzzyBound } from "../domain/interpret/fuzzy.mjs";
 import { loadLexicon, lookupNoun } from "../domain/grammar/lexicon.mjs";
 import { pickPhrase } from "../domain/answer-variants.mjs";
+import { REFERENCE_PACK_NAME, cleanMissReferenceTerm, renderReferenceAnswer, referenceProvenanceTag } from "../domain/reference-pack.mjs";
+import { getReferencePackProvider } from "../adapters/corpus/reference-pack.mjs";
+import { dialogueActForLane } from "../domain/dialogue-acts.mjs";
+import { relatedForTerm } from "../domain/skos-view.mjs";
 
 // Composition: the chat surface supplies the domain parser's default lemma/POS
 // adapter (the browser bundle's ask-nlp stub carries no factory, so this is a
@@ -149,6 +153,47 @@ function deduceGoalFromParsed(parsed) {
   return "understand a graph relationship";
 }
 
+// ---- dialogue acts (ISO 24617-2): a lookup over the lane decision ----
+// A turn result may carry a `lane` string naming the router lane that
+// answered it; withLast (and conversationalTurn's own mk) resolve it through
+// dialogueActForLane and stamp `record.dialogueAct` — a fixed lookup over a
+// decision already made, never a classifier. The honest miss is the row that
+// must never drift: autoNegative in the autoFeedback dimension, tmct
+// reporting its OWN processing failed, not a task answer.
+
+/** Stamp the record with the lane's dialogue act (a no-op for an unmapped or
+ *  absent lane) and put the label in the narrate trace. */
+function attachDialogueAct(result, trace) {
+  const act = dialogueActForLane(result?.lane);
+  if (act && result?.record) {
+    result.record.dialogueAct = act;
+    note(trace, `dialogue act: ${act.act} (${act.dimension} dimension, ISO 24617-2)`);
+  }
+  return result;
+}
+
+const PROPOSITIONAL_NODES = new Set(["boolean", "qualifier"]);
+const PROPOSITIONAL_LEAD_RE = /^(?:is|are|am|was|were|does|do|did|can|could|will|would|shall|should|has|have|had|must)\b/i;
+const SET_QUESTION_LEAD_RE = /^(?:what|which|who|whose|where|when|why|how|tell|show|list|define|describe|find|count|name)\b/i;
+
+/** The dialogue-act lane for a runAsk turn. A recorded miss is ALWAYS the
+ *  honest-miss lane, whatever the query shape — feedback about tmct's own
+ *  processing. An answered turn is labelled by its question shape (yes/no
+ *  vs set), from the parsed AST when one stood, else the lead word. Null
+ *  when the turn is neither — the record simply carries no act. */
+function askDialogueLane(parsed, query, recordMiss) {
+  if (recordMiss) return "honest-miss";
+  if (parsed) {
+    if (parsed.node) return PROPOSITIONAL_NODES.has(parsed.node) ? "ask-propositional" : "ask-set";
+    if (parsed.shape === "ask") return "ask-propositional";
+    if (parsed.shape) return "ask-set";
+  }
+  const q = String(query).trim();
+  if (PROPOSITIONAL_LEAD_RE.test(q)) return "ask-propositional";
+  if (SET_QUESTION_LEAD_RE.test(q)) return "ask-set";
+  return null;
+}
+
 /** Split the collected trace into buckets by its own leading category tag, so
  *  renderNarration can group like with like while the trace array itself stays
  *  a flat, chronological narrative — no structured side-channel to keep in
@@ -1444,16 +1489,17 @@ function conversationalTurn(line, ctx) {
   const raw = String(line);
   const q = raw.toLowerCase().replace(/[.!?]+$/, "").replace(/\s+/g, " ").trim();
   const t = (id, slots = {}) => tRender(ctx.templates, id, slots) ?? TEMPLATES_UNAVAILABLE;
-  const mk = (answer, { end = false, miss = false, via = "template" } = {}) => {
+  const mk = (answer, { end = false, miss = false, via = "template", lane = null } = {}) => {
     const ts = new Date().toISOString();
-    return {
+    return attachDialogueAct({
       answer,
       logLines: [ts, `> ${raw}`, answer, ""],
       record: { type: "turn", ts, query: raw, conversational: true, via, resolvedIds: [], answeredIds: [], miss },
       focus: ctx.focus,
       last: ctx.last, // a conversational turn never overwrites the last real answer
+      lane,
       ...(end ? { end: true } : {}),
-    };
+    }, ctx.trace);
   };
   if (foldedBye(q)) {
     note(ctx.trace, "goal: casual/social — ending the session (no graph intent)");
@@ -1475,7 +1521,7 @@ function conversationalTurn(line, ctx) {
     if (signal === "thanks") {
       note(ctx.trace, "goal: casual/social — acknowledgement, no graph intent");
       note(ctx.trace, "lane: conversational — thanks (multi-clause phrase-shape match)");
-      return mk(t(T_THANKS));
+      return mk(t(T_THANKS), { lane: "thanks" });
     }
   }
   if (WHY.has(q)) {
@@ -1504,7 +1550,7 @@ function conversationalTurn(line, ctx) {
       // morning, hello there) keep their wording; only the default greeting swaps.
       const id = (!T_GREETING_BY_PHRASE[greetHit] && noCodeGraph(ctx.graph)) ? T_GREETING_EMPTY : (T_GREETING_BY_PHRASE[greetHit] || T_GREETING);
       note(ctx.trace, `pattern: template "${id}" (data/templates/responses.jsonl)`);
-      return mk(t(id, { vocabHint: ctx.vocabHint }));
+      return mk(t(id, { vocabHint: ctx.vocabHint }), { lane: "greeting" });
     }
   }
   {
@@ -1513,23 +1559,23 @@ function conversationalTurn(line, ctx) {
       note(ctx.trace, "goal: casual/social — acknowledgement, no graph intent");
       note(ctx.trace, `lane: conversational — thanks/acknowledgement (${OK_ACK.has(q) ? "OK_ACK" : "THANKS"} closed set${thanksHit === q ? "" : ", elongation-collapsed"})`);
       note(ctx.trace, `pattern: template "${T_THANKS}" (data/templates/responses.jsonl)`);
-      return mk(t(T_THANKS));
+      return mk(t(T_THANKS), { lane: "thanks" });
     }
   }
   if (aiIdentityMatch(raw)) {
     note(ctx.trace, "goal: identity — is tmct an AI/LLM (a very likely first question)");
     note(ctx.trace, "lane: conversational — identity/AI (AI_IDENTITY_PHRASES closed set)");
-    return mk(t(T_IDENTITY_NOT_LLM));
+    return mk(t(T_IDENTITY_NOT_LLM), { lane: "help" });
   }
   if (FEELINGS_PHRASES.some((re) => re.test(raw))) {
     note(ctx.trace, "goal: identity — does tmct have feelings/consciousness (small-talk persona finding)");
     note(ctx.trace, "lane: conversational — identity/feelings (FEELINGS_PHRASES closed set)");
-    return mk(t(T_IDENTITY_NO_FEELINGS));
+    return mk(t(T_IDENTITY_NO_FEELINGS), { lane: "help" });
   }
   if (IDENTITY_PHRASES.some((re) => re.test(raw))) {
     note(ctx.trace, "goal: identity — who/what tmct is, not a capability listing");
     note(ctx.trace, "lane: conversational — identity (IDENTITY_PHRASES closed set)");
-    return mk(t(T_IDENTITY_SELF));
+    return mk(t(T_IDENTITY_SELF), { lane: "help" });
   }
   // CAPABILITY_PHRASES' vague-opener entries are self-contained closed
   // regexes, but a preamble ahead of one ("right, can you walk me through
@@ -1541,7 +1587,7 @@ function conversationalTurn(line, ctx) {
     || CAPABILITY_PHRASES.some((re) => re.test(applyPreambleFrames(raw))) || ORIENT_OPENERS.has(q)) {
     note(ctx.trace, "goal: get oriented — what can tmct answer, how do I start");
     note(ctx.trace, "lane: conversational — help/orientation (CAPABILITY_PHRASES/ORIENT_OPENERS / bare help / ?)");
-    return mk(orientationAnswer(ctx.templates, ctx.graph, ctx.vocabHint));
+    return mk(orientationAnswer(ctx.templates, ctx.graph, ctx.vocabHint), { lane: "help" });
   }
   // Fuzzy-typo fallback (A4): every exact/collapsed closed-set lookup above missed —
   // try a bounded edit-distance match against the flattened conversational phrase
@@ -1554,11 +1600,11 @@ function conversationalTurn(line, ctx) {
       note(ctx.trace, `goal: casual/social or orientation — fuzzy-typo match "${raw}" → "${fuzzyHit}"`);
       note(ctx.trace, `lane: conversational — fuzzy typo tolerance (${bucket})`);
       if (bucket === "bye") return mk(t(T_FAREWELL), { end: true });
-      if (bucket === "thanks") return mk(t(T_THANKS));
-      if (bucket === "identity") return mk(t(T_IDENTITY_SELF));
-      if (bucket === "capability") return mk(orientationAnswer(ctx.templates, ctx.graph, ctx.vocabHint));
+      if (bucket === "thanks") return mk(t(T_THANKS), { lane: "thanks" });
+      if (bucket === "identity") return mk(t(T_IDENTITY_SELF), { lane: "help" });
+      if (bucket === "capability") return mk(orientationAnswer(ctx.templates, ctx.graph, ctx.vocabHint), { lane: "help" });
       const id = (!T_GREETING_BY_PHRASE[fuzzyHit] && noCodeGraph(ctx.graph)) ? T_GREETING_EMPTY : (T_GREETING_BY_PHRASE[fuzzyHit] || T_GREETING);
-      return mk(t(id, { vocabHint: ctx.vocabHint }));
+      return mk(t(id, { vocabHint: ctx.vocabHint }), { lane: "greeting" });
     }
   }
   return null;
@@ -8783,6 +8829,46 @@ async function curatedDefinitionAnswer(query, envelope, { memoryDir, lexicon })
   return { text: `${def} (source: corpus/seon)`, term };
 }
 
+// ---- learn-on-miss: the shipped reference pack behind the cleanest miss ----
+
+/** The learn-on-miss gate, shared by the articled miss hook and the bare-form
+ *  fallback so the two can never disagree. Fires only on the CLEANEST miss: a
+ *  definition-shaped term the lexicon knows, resolving to no graph entity and
+ *  no remembered fact — then, and only then, the pack provider is consulted.
+ *  Null means the turn proceeds byte-identically to a pack-less run. */
+async function referencePackMissAnswer(term, { graph, memoryDir, lexicon, env, cache }) {
+  if (!term || !memoryDir) return null;
+  let key = null;
+  try { key = cleanMissReferenceTerm(term, lexicon ?? undefined); } catch { key = null; }
+  if (!key) return null;
+  if (await resolveEntity(graph, term)) return null;
+  let normFactTerm;
+  try { ({ normFactTerm } = await import("../adapters/memory/core.mjs")); } catch { return null; }
+  const variants = factTermVariants(normFactTerm, term);
+  variants.add(key);
+  const rows = await factRows(memoryDir, cache);
+  if (rows.some((f) => variants.has(f.subject) || variants.has(f.object))) return null;
+  let article = null;
+  try { article = await getReferencePackProvider(env).lookup(key); } catch { article = null; }
+  if (!article) return null;
+  return { key, article, text: renderReferenceAnswer(key, article) };
+}
+
+/** Store the article's first-sentence isa as a subClassOf fact carrying
+ *  reference provenance — AFTER the cited answer composed, and failure-
+ *  tolerated: the answer stands whether or not the fact lands. */
+async function appendReferenceIsaFact(memoryDir, key, article, cache) {
+  if (!article?.isa) return;
+  try {
+    const { appendFact } = await import("../adapters/memory/core.mjs");
+    await appendFact(memoryDir, {
+      subject: key, predicate: "rdfs:subClassOf", object: article.isa,
+      provenance: referenceProvenanceTag(article),
+    });
+    if (cache) cache.rows = null;
+  } catch { /* tolerated — the cited answer is already composed */ }
+}
+
 /** The concept term a vague "what is a X" / "tell me about X" / "what does X mean" /
  *  "define X" asks about — metaTermOf's forms plus the "tell me about …" opener that
  *  the graph parser reads as a count. Null when the line isn't such a touch. The
@@ -9473,7 +9559,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", })
     const n = heldGoals.length;
     return {
       text: `${added ? "noted" : "already noted"} — the goal is that ${tails.join(" and ")}.${n > 1 ? ` (${n} goals held)` : ""} Say "solve it" when the state is taught.`,
-      via: "plan", deduced: "record the goal state for a later plan",
+      via: "plan", lane: "goal", deduced: "record the goal state for a later plan",
       note: added
         ? `GOAL frame — ${added === 1 ? "goal spec" : `${added} goal specs`} accumulated on the session plan slot`
         : "GOAL frame — the same goal spec was already held, so it folded onto the existing one",
@@ -9613,7 +9699,7 @@ async function planLaneAnswer(query, { memoryDir, planHolder, sessionId = "", })
       `${ordering.length ? ` and ${ordering.length} ordering fact${ordering.length === 1 ? "" : "s"}` : ""}. ` +
       `Say "next" to make move 1, or ask "what moves are legal now".${assumptionNote}`;
   return {
-    text, via: "plan",
+    text, via: "plan", lane: "imperative",
     deduced: `plan a move sequence from the current state to the goal (${n} move${n === 1 ? "" : "s"})`,
     note: "plan lane — compileDomain + findActionPath over the taught rules; plan held on the session slot",
     plan,
@@ -9982,6 +10068,10 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // facts/recall (a fact EXTENDS a non-miss schema hit too — NOT miss-gated),
   // (4) TEACH lane (would-miss), (5) the short tailored miss (would-miss).
   let handled = false;
+  // The dialogue-act lane, when a lane below knows better than the final
+  // question-shape lookup (a plan frame is a request/instruct, a stored
+  // teach is an inform, whatever the surface punctuation looked like).
+  let dialogueLaneOverride = null;
   // (0) "what else is X" — recognized off the RAW query text, before every
   // other lane below (all of which read `envelope`, already relaxed/reparsed
   // by ask()'s noise-strip cascade, which silently drops "else"). via is set
@@ -10021,6 +10111,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const planLane = await planLaneAnswer(query, { memoryDir, planHolder, sessionId });
     if (planLane) {
       answer = planLane.text; via = planLane.via; recordMiss = false; handled = true;
+      if (planLane.lane) dialogueLaneOverride = planLane.lane;
       if (planLane.plan) planResult = planLane.plan;
       if (planLane.deduced) {
         deduced = planLane.deduced;
@@ -10214,6 +10305,14 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
         const def = await curatedDefinitionAnswer(gateQuery, envelope, { memoryDir, lexicon });
         if (def) bareMetaHit = { text: def.text, replace: true };
       }
+      // The reference pack's bare-form fallback, beside the curated one and
+      // under the IDENTICAL clean-miss gate the articled hook (4h) applies —
+      // "what is otter" reaches the pack exactly as "what is an otter" does.
+      if (!bareMetaHit) {
+        const refTerm = metaTermOf(gateQuery, envelope);
+        const ref = refTerm ? await referencePackMissAnswer(refTerm, { graph, memoryDir, lexicon, env, cache }) : null;
+        if (ref) bareMetaHit = { text: ref.text, replace: true, reference: ref };
+      }
     }
     // A bare "what is X" naming a REAL code-graph entity (not a taught fact,
     // not a curated corpus term) needs the SAME race fixed too.
@@ -10249,7 +10348,18 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     if (fallback) bareMetaHit = { text: fallback.text, replace: true };
   }
   const coldPronounDecline = focus?.label ? null : coldPronounDeclineText(query);
-  if (bareMetaHit) {
+  if (bareMetaHit?.reference) {
+    // The bare-form reference hit mirrors (4h): the cited answer replaces the
+    // miss, the turn is no longer recorded as one, and the article's isa is
+    // stored after the answer composes.
+    answer = bareMetaHit.text;
+    via = "reference";
+    recordMiss = false;
+    handled = true;
+    note(trace, "lane: (2b) REFERENCE PACK — a bare \"what is X\" clean miss answered from the shipped reference pack, cited");
+    note(trace, `source: reference pack ${REFERENCE_PACK_NAME} — article "${bareMetaHit.reference.article.title}" (revid ${bareMetaHit.reference.article.revid})`);
+    await appendReferenceIsaFact(memoryDir, bareMetaHit.reference.key, bareMetaHit.reference.article, cache);
+  } else if (bareMetaHit) {
     answer = bareMetaHit.replace ? bareMetaHit.text : `${answer}\n${bareMetaHit.text}`;
     // Same discipline as lane (3): a fact-lane return flagged `miss` is an
     // honest miss in better words — the turn record keeps miss=true and via
@@ -10459,6 +10569,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const taught = await teachLane(query, { memoryDir, sessionId, lexicon, cache });
     if (taught) {
       answer = taught.text; via = taught.via; recordMiss = taught.miss;
+      if (!taught.miss) dialogueLaneOverride = "teach";
       note(trace, `lane: (4) TEACH — TEACH_RE/OWNS_TEACH_RE/BARE_DECLARATIVE_RE matched, ${taught.miss ? "but the payload could not be stored" : "reified into .tmct/memory"}`);
       // `deduced` was computed straight off envelope.parsed alone, but the
       // structural grammar has no business parsing a teach-shaped sentence at
@@ -10603,6 +10714,24 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       note(trace, `lane: (4g) FUZZY-VERB DECLINE — "${from}" only became a verb through the edit-distance repair tier ("${to}"), and the two words are different verbs, so the repaired sentence's graph answer is dropped rather than shown as an answer to what was typed`);
     }
   }
+  // (4h) REFERENCE PACK — the cleanest miss consults the shipped reference
+  // pack: a definition-shaped term the lexicon knows, no graph entity, no
+  // remembered fact. A hit answers with the article's summary, always cited;
+  // a null from any gate leaves the turn byte-identical. After the answer
+  // composes, the article's first-sentence isa is stored as a subClassOf fact
+  // with reference provenance, so the NEXT ask answers from memory.
+  if (miss && recordMiss && via === "composed" && memoryDir) {
+    const refTerm = metaTermOf(query, envelope);
+    const ref = refTerm ? await referencePackMissAnswer(refTerm, { graph, memoryDir, lexicon, env, cache }) : null;
+    if (ref) {
+      answer = ref.text;
+      via = "reference";
+      recordMiss = false;
+      note(trace, "lane: (4h) REFERENCE PACK — a clean miss on a lexicon term answered from the shipped reference pack, cited");
+      note(trace, `source: reference pack ${REFERENCE_PACK_NAME} — article "${ref.article.title}" (revid ${ref.article.revid})`);
+      await appendReferenceIsaFact(memoryDir, ref.key, ref.article, cache);
+    }
+  }
   // (5) #1 SHORT TAILORED MISS — replace ONLY the engine's full grammar cheat-sheet
   // wall (WALL_MISS_RE). Receipt-bearing misses keep their specific wording.
   // WALL KINDNESS: a second consecutive wall collapses to a one-liner whose
@@ -10733,7 +10862,10 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // `goal`: the SAME deduced string the debug trace's own "goal:" line
   // carries. Only runAsk ever sets this field, so the always-on goal line is
   // scoped to real ask-engine turns by construction.
-  return { answer, logLines, record, focus: newFocus, detail, effectiveQuery, goal: deduced, ...(planResult ? { plan: planResult } : {}) };
+  // `lane`: the dialogue-act lane — a lane's own override, else the
+  // question-shape lookup — resolved to an ISO act by runTurn's withLast.
+  const lane = dialogueLaneOverride ?? askDialogueLane(envelope?.parsed, query, recordMiss);
+  return { answer, logLines, record, focus: newFocus, detail, effectiveQuery, goal: deduced, lane, ...(planResult ? { plan: planResult } : {}) };
 }
 
 /** A non-ask, non-dispatch chat turn (count answer, /stats) — the same
@@ -11287,6 +11419,251 @@ function morePage(query, { last, focus }) {
   return turn;
 }
 
+// ---- the SKOS view: synonym/related-word questions over the store ----
+// "another word for X" / "synonyms of X" / "what is related to X" read the
+// store's mgx:synonym / mgx:relatedTo / mgx:similarTo facts through
+// buildSkosConceptView's minted concepts (relatedForTerm). Routed ahead of
+// the generic parse, which reads these phrasings as something else entirely.
+// A term that mints no concept — unknown, or with no synonym/related facts —
+// misses honestly, naming the term, never a guessed neighbour.
+const SKOS_SYNONYM_RE = /^(?:another\s+word\s+for|other\s+words\s+for|synonyms?\s+(?:of|for)|what\s+is\s+a\s+synonym\s+(?:of|for))\s+(?:an?\s+|the\s+)?(.+?)[?.!\s]*$/i;
+const SKOS_RELATED_RE = /^(?:what\s+is\s+related\s+to|what\s+relates\s+to|what\s+words\s+are\s+related\s+to)\s+(?:an?\s+|the\s+)?(.+?)[?.!\s]*$/i;
+
+/** The SKOS-view answer for a synonym/related question, or null when the
+ *  line is not one. A matched line always answers — a hit lists the group's
+ *  other labels and the related concepts; anything else is the honest miss. */
+async function skosRelatedAnswer(memoryDir, query, cache) {
+  if (!memoryDir) return null;
+  const q = expandContractions(String(query).trim());
+  const syn = q.match(SKOS_SYNONYM_RE);
+  const rel = syn ? null : q.match(SKOS_RELATED_RE);
+  if (!syn && !rel) return null;
+  const term = (syn ?? rel)[1].trim();
+  let hood = null;
+  try { hood = relatedForTerm(await factRows(memoryDir, cache), term); } catch { hood = null; }
+  const parts = [];
+  if (hood?.synonyms?.length) parts.push(`another word for ${term}: ${joinList(hood.synonyms)}`);
+  const relatedLabels = (hood?.related ?? []).map((c) => c.prefLabel);
+  if (relatedLabels.length) parts.push(`related: ${joinList(relatedLabels)}`);
+  if (!parts.length) {
+    return { term, miss: true, text: `I don't know any synonyms or related words for "${term}" yet.` };
+  }
+  return { term, miss: false, text: `${parts.join("; ")} (source: remembered synonym/related facts, read as SKOS)` };
+}
+
+// ---- guess-the-number: a closed-loop game over hidden state ----
+// Two modes on one mechanism. In GUESSER mode the human holds a secret and
+// tmct searches: a belief interval {lo, hi} narrowed by bisection, one
+// observation ("higher"/"lower"/"correct") folded in per turn. In THINKER
+// mode tmct commits a secret up front and each turn is a stateless
+// comparison against it. The game payload rides the session's plan slot as
+// a tagged sub-object ({ game: {...} }), so a plan frame and a game never
+// share the slot — each declines to start while the other is active.
+
+/** "between A and B" / "up to N" anywhere in an opening line. Loose token
+ *  captures (\S+) so a non-numeric bound is SEEN and declined rather than
+ *  silently defaulted. */
+const GAME_BOUNDS_CLAUSE_RE = /\b(?:between\s+(\S+)\s+and\s+(\S+)|up\s+to\s+(\S+))\b/i;
+const GAME_BOUND_MAX = 1_000_000_000;
+
+/** The bounds an opening line states — { lo, hi } (default 1–100), or
+ *  { problem } naming why the stated range is unplayable. */
+function parseGameBounds(text) {
+  const m = String(text).match(GAME_BOUNDS_CLAUSE_RE);
+  if (!m) return { lo: 1, hi: 100 };
+  const tokens = (m[3] !== undefined ? ["1", m[3]] : [m[1], m[2]])
+    .map((t) => String(t).replace(/[,.?!]+$/, ""));
+  if (!tokens.every((t) => /^-?\d+$/.test(t))) {
+    return { problem: 'I can only play with whole-number bounds — say "between 1 and 100".' };
+  }
+  const lo = Number(tokens[0]);
+  const hi = Number(tokens[1]);
+  if (Math.abs(lo) > GAME_BOUND_MAX || Math.abs(hi) > GAME_BOUND_MAX) {
+    return { problem: `that range is too big for a fair game — keep both bounds within ${GAME_BOUND_MAX.toLocaleString("en-US")}.` };
+  }
+  if (hi < lo) return { problem: `no number is between ${lo} and ${hi} — that range is empty. Put the smaller bound first.` };
+  if (hi === lo) return { problem: `between ${lo} and ${hi} leaves exactly one number, so there is nothing to guess. Pick a wider range.` };
+  return { lo, hi };
+}
+
+// Opening moves, both modes, as closed-set leads + a tail that may only carry
+// the bounds clause and the closing invitation words — any other tail is a
+// real sentence and falls through to the ordinary lanes.
+const GUESSER_OPEN_LEAD_RE = /^(?:i\s*(?:'m|am)\s+thinking\s+of\s+a\s+number|guess\s+my\s+number|guess\s+the\s+number\s+i\s*(?:'m|am)\s+thinking\s+of|guess\s+a\s+number\s+(?:between\s+\S+\s+and\s+\S+\s+|up\s+to\s+\S+\s+)?and\s+i\s*(?:'ll|\s+will)\s+tell\s+you\s+(?:if\s+it\s*(?:'s|\s+is)\s+)?higher\s+or\s+lower)\b(.*)$/i;
+const THINKER_OPEN_LEAD_RE = /^(?:think\s+of\s+a\s+number)\b(.*)$/i;
+const GUESSER_OPEN_TAIL_RE = /^[\s,.!?—-]*(?:and\s+)?(?:you\s+)?(?:can\s+|have\s+to\s+|try\s+to\s+)?(?:guess(?:\s+it|\s+what\s+it\s+is)?)?[\s,.!?—-]*$/i;
+const THINKER_OPEN_TAIL_RE = /^[\s,.!?—-]*(?:and\s+)?(?:i\s*(?:'ll|\s+will)\s+(?:try\s+to\s+)?guess(?:\s+it)?|i\s+guess)?[\s,.!?—-]*$/i;
+
+/** An opening move — { mode, bounds } — or null. */
+function matchGameOpening(line) {
+  const l = String(line).trim();
+  const guesser = l.match(GUESSER_OPEN_LEAD_RE);
+  if (guesser && GUESSER_OPEN_TAIL_RE.test(guesser[1].replace(GAME_BOUNDS_CLAUSE_RE, " "))) {
+    return { mode: "guesser", bounds: parseGameBounds(l) };
+  }
+  const thinker = l.match(THINKER_OPEN_LEAD_RE);
+  if (thinker && THINKER_OPEN_TAIL_RE.test(thinker[1].replace(GAME_BOUNDS_CLAUSE_RE, " "))) {
+    return { mode: "thinker", bounds: parseGameBounds(l) };
+  }
+  return null;
+}
+
+// Continuation replies, gated STRICTLY on an active game (the same discipline
+// MORE_RE applies to a held pending remainder): with no game standing none of
+// these are ever consulted, and mid-game any line that matches none of them
+// is an ordinary aside — answered by the normal lanes, game untouched.
+const GAME_STOP_RE = /^(?:ok[,\s]+)?(?:i\s+give\s+up|give\s+up|i\s+quit(?:\s+the\s+game)?|stop\s+(?:the\s+game|playing)|end\s+the\s+game)[.!?\s]*$/i;
+const GAME_REVEAL_RE = /^(?:just\s+tell\s+me|(?:just\s+)?tell\s+me\s+the\s+(?:number|answer)|what(?:'s|\s+is)\s+(?:the|your)\s+(?:secret\s+)?number|reveal\s+(?:it|the\s+number)|show\s+me\s+the\s+number)[.!?\s]*$/i;
+const GAME_OBS_HIGHER_RE = /^(?:no[,\s]+)?(?:higher|too\s+low|too\s+small|bigger|greater|go\s+higher|it(?:'s|\s+is)\s+higher)[.!?\s]*$/i;
+const GAME_OBS_LOWER_RE = /^(?:no[,\s]+)?(?:lower|too\s+high|too\s+big|smaller|less|go\s+lower|it(?:'s|\s+is)\s+lower)[.!?\s]*$/i;
+const GAME_OBS_CORRECT_RE = /^(?:yes|yep|yeah|correct|you\s+got\s+it|you\s+guessed\s+it|that(?:'s|\s+is)\s+it|that(?:'s|\s+is)\s+right|got\s+it|spot\s+on)[.!?\s]*$/i;
+const GAME_GUESS_RE = /^(?:is\s+it\s+)?(-?\d{1,12})\s*\??[.!?\s]*$/;
+const GAME_FALSE_CORRECT_RE = /^(?:but\s+)?you\s+(?:already\s+)?said\s+(?:it\s+was\s+)?(?:correct|right)\b/i;
+
+/** A natural-language plan frame — the shapes planLaneAnswer owns. Mid-game
+ *  these get the one-at-a-time decline instead of clobbering the slot. */
+function isPlanFrameLine(line) {
+  return GOAL_TEACH_RE.test(line) || GOAL_TEACH_INFINITIVE_RE.test(line)
+    || GOAL_TEACH_VERBLESS_RE.test(line) || GOAL_TEACH_NP_RE.test(line)
+    || GOAL_TEACH_IMPERATIVE_RE.test(line) || GOAL_TEACH_CONJUNCTION_RE.test(line)
+    || PLAN_SOLVE_RE.test(line) || LEGAL_MOVES_RE.test(line);
+}
+
+/** The per-turn goal line, table-driven off the live game state. */
+function gameGoal(game) {
+  if (game.mode === "guesser") return `narrow down your number — currently between ${game.lo} and ${game.hi}`;
+  if (!game.lastHint) return "let you find my secret number I've committed to";
+  return `let you find my secret number — said "${game.lastHint}" so it's ${game.lastHint === "higher" ? "above" : "below"} your last guess`;
+}
+
+/** One guesser-mode observation folded into the belief interval, or a
+ *  thinker-mode guess compared against the secret. Mutates planHolder.state
+ *  (the same slot the plan lane owns) and returns { text, goal?, lane, note },
+ *  or null when the line is not a game reply. */
+function gameContinuationAnswer(line, game, planHolder) {
+  const endGame = () => { planHolder.state = null; };
+  if (game.mode === "guesser") {
+    if (GAME_STOP_RE.test(line)) {
+      endGame();
+      return { text: 'OK, stopping — I never found it. Say "guess my number" any time to play again.', lane: "game-inform", note: "GAME — the game ended on request; the belief interval is discarded" };
+    }
+    if (GAME_OBS_CORRECT_RE.test(line)) {
+      const { guess, guesses } = game;
+      endGame();
+      return { text: `Got it — your number is ${guess}, found in ${guesses} guess${guesses === 1 ? "" : "es"}. Want to play again?`, lane: "game-answer", note: "GAME — the guess was confirmed; game over, won" };
+    }
+    const higher = GAME_OBS_HIGHER_RE.test(line);
+    const lower = !higher && GAME_OBS_LOWER_RE.test(line);
+    if (!higher && !lower) return null;
+    const prior = game.guess;
+    const next = { ...game };
+    if (higher) { next.lo = prior + 1; next.loSetBy = { guess: prior }; }
+    else { next.hi = prior - 1; next.hiSetBy = { guess: prior }; }
+    if (next.lo > next.hi) {
+      // The interval is EMPTY: no number satisfies every observation given,
+      // so name the two observations that cannot both hold and stop guessing
+      // — never a fabricated next guess over a premise known to be false.
+      endGame();
+      const earlier = higher
+        ? (game.hiSetBy ? `lower than ${game.hiSetBy.guess}` : `it's between ${game.lo0} and ${game.hi0}`)
+        : (game.loSetBy ? `higher than ${game.loSetBy.guess}` : `it's between ${game.lo0} and ${game.hi0}`);
+      const now = `${higher ? "higher" : "lower"} than ${prior}`;
+      return {
+        text: `That's not possible — you said ${earlier}, and now ${now}, but no number can be both. One of those answers must be wrong. Say "guess my number" to restart.`,
+        lane: "game-answer",
+        note: "GAME — the observations emptied the belief interval; refused to keep guessing under a false premise",
+      };
+    }
+    next.guess = Math.floor((next.lo + next.hi) / 2);
+    next.guesses = game.guesses + 1;
+    planHolder.state = { game: next };
+    return {
+      text: `My guess: ${next.guess}. Say higher, lower, or correct.`,
+      goal: gameGoal(next),
+      lane: "game-inform",
+      note: `GAME — folded "${higher ? "higher" : "lower"}" into the interval and bisected it again`,
+    };
+  }
+  // Thinker mode: tmct holds the ground truth, so every reply is a plain
+  // comparison — and the hint record is authoritative against false claims.
+  if (GAME_STOP_RE.test(line) || GAME_REVEAL_RE.test(line)) {
+    const { secret } = game;
+    endGame();
+    return { text: `The number was ${secret}. Want to play again?`, lane: "game-answer", note: "GAME — revealed the secret on request; game over" };
+  }
+  if (GAME_FALSE_CORRECT_RE.test(line)) {
+    const record = game.lastHint
+      ? `my last hint was "${game.lastHint}", after your guess of ${game.lastGuess}`
+      : "you haven't guessed yet";
+    return { text: `I haven't said "correct" yet — ${record}. Keep guessing.`, goal: gameGoal(game), lane: "game-answer", note: "GAME — rebutted a false \"you said correct\" from the game's own hint record" };
+  }
+  const m = String(line).trim().match(GAME_GUESS_RE);
+  if (!m) return null;
+  const guess = Number.parseInt(m[1], 10);
+  if (guess < game.lo0 || guess > game.hi0) {
+    return { text: `${guess} is outside the ${game.lo0} to ${game.hi0} range we agreed — try a number in range.`, goal: gameGoal(game), lane: "game-answer", note: "GAME — an out-of-range guess; declined rather than comparing outside the agreed bounds" };
+  }
+  const next = { ...game, guesses: game.guesses + 1, lastGuess: guess };
+  if (guess === game.secret) {
+    endGame();
+    return { text: `Correct — you got it in ${next.guesses} guess${next.guesses === 1 ? "" : "es"}! The number was ${guess}. Want to play again?`, lane: "game-answer", note: "GAME — the guess matched the secret; game over, won" };
+  }
+  next.lastHint = guess < game.secret ? "higher" : "lower";
+  planHolder.state = { game: next };
+  return { text: `${next.lastHint} — guess again.`, goal: gameGoal(next), lane: "game-answer", note: `GAME — compared the guess against the committed secret: ${next.lastHint}` };
+}
+
+/** The whole game lane for one turn: continuations first (active game only),
+ *  then opening moves, with the one-at-a-time declines both ways across the
+ *  shared plan slot. Null when the turn is not the game's to answer. */
+function guessNumberTurn(line, { planHolder, env }) {
+  const state = planHolder?.state ?? null;
+  const game = state?.game ?? null;
+  const opening = matchGameOpening(line);
+  if (game) {
+    const continuation = gameContinuationAnswer(line, game, planHolder);
+    if (continuation) return continuation;
+    if (opening) {
+      return { text: `we're already playing — I'm ${game.mode === "guesser" ? "guessing your number" : "holding a secret number"}. Say "I give up" to end this game first.`, lane: "game-inform", note: "GAME — an opening arrived mid-game; declined, the running game stands" };
+    }
+    if (isPlanFrameLine(line)) {
+      return { text: 'a guess-the-number game is active — say "I give up" to end it, then set your goal.', lane: "game-inform", note: "GAME — a plan frame arrived mid-game; the slot holds one thing at a time" };
+    }
+    return null;
+  }
+  if (!opening) return null;
+  const planActive = state && !state.done
+    && ((Array.isArray(state.goals) && state.goals.length) || (Array.isArray(state.actions) && state.actions.length));
+  if (planActive) {
+    return { text: "a plan is in progress — finish it or start a fresh goal before we play guess-the-number.", lane: "game-inform", note: "GAME — an opening arrived while a plan frame is active; the slot holds one thing at a time" };
+  }
+  if (opening.bounds.problem) {
+    return { text: opening.bounds.problem, lane: "game-inform", note: "GAME — the opening stated an unplayable range; declined honestly" };
+  }
+  const { lo, hi } = opening.bounds;
+  if (opening.mode === "guesser") {
+    const guess = Math.floor((lo + hi) / 2);
+    planHolder.state = { game: { mode: "guesser", lo0: lo, hi0: hi, lo, hi, guess, guesses: 1, loSetBy: null, hiSetBy: null } };
+    return {
+      text: `OK — you're thinking of a number between ${lo} and ${hi}; I'll guess it. My guess: ${guess}. Say higher, lower, or correct.`,
+      goal: `narrow down your number — currently between ${lo} and ${hi}`,
+      lane: "game-inform",
+      note: "GAME — guesser mode opened; the belief interval starts at the agreed bounds and the first guess is its midpoint",
+    };
+  }
+  const envSecret = Number.parseInt(String(env?.TMCT_GAME_SECRET ?? ""), 10);
+  const secret = Number.isSafeInteger(envSecret) && envSecret >= lo && envSecret <= hi
+    ? envSecret
+    : lo + Math.floor(Math.random() * (hi - lo + 1));
+  planHolder.state = { game: { mode: "thinker", lo0: lo, hi0: hi, secret, guesses: 0, lastHint: null, lastGuess: null } };
+  return {
+    text: `Done — I've thought of a number between ${lo} and ${hi}. Guess it, and I'll say higher, lower, or correct.`,
+    goal: "let you find my secret number I've committed to",
+    lane: "game-inform",
+    note: "GAME — thinker mode opened; the secret is committed for the whole game",
+  };
+}
+
 // "I want you to search for Widget" / "I'd like you to search for Widget" —
 // a closed-set indirect-request wrapper, checked VERY early. Without this it
 // is mis-swallowed by GENERAL_VERB_TEACH_RE as a bare teach triple (subject
@@ -11501,7 +11878,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   // what the shell prints. The narrate block is applied AFTER `last` is
   // captured from the PRE-narration finished result.
   const withLast = (result, fallbackGoal = "unclear — no goal signal for this turn type") => {
-    const finished = finish(result, { graph });
+    const finished = attachDialogueAct(finish(result, { graph }), trace);
     // Every dispatch path below built its own record off `workingLine` (the
     // indirect-request wrapper stripped and/or the discontiguous-frame
     // rewrite applied) — restore the ORIGINAL raw `line` into record.query
@@ -11541,6 +11918,26 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   const bareCmd = asBareCommand(workingLine);
   if (bareCmd) return withLast(await runCommand(bareCmd, ctx), "use a specific tool/command directly");
 
+  // GUESS-THE-NUMBER — opening moves, and (with a game standing) the
+  // closed-set continuation replies. Checked before the conversational layer
+  // because the guesser-mode observations ("yes", "got it") share words with
+  // the acknowledgement sets, and before assertTurn/runAsk because an opening
+  // line would otherwise read as a declarative to remember. A mid-game line
+  // matching no game shape returns null here and the game stands untouched.
+  {
+    const gameTurn = guessNumberTurn(workingLine, { planHolder, env });
+    if (gameTurn) {
+      note(trace, `lane: ${gameTurn.note}`);
+      if (gameTurn.goal) note(trace, `goal: ${gameTurn.goal}`);
+      const result = plainTurn(workingLine, gameTurn.text, { via: "game", focus });
+      if (gameTurn.goal) result.goal = gameTurn.goal;
+      result.lane = gameTurn.lane;
+      const rec = withLast(result, gameTurn.goal ?? "play the guessing game");
+      rec.planState = planHolder.state;
+      return rec;
+    }
+  }
+
   // Conversational layer next (greetings, thanks, help, bye, why/say-more) — these
   // resolve no entity and carry their own preserved `last`. Bypasses withLast (a
   // conversational turn is never finish()'d / never becomes a new `last`), so the
@@ -11558,7 +11955,9 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     const step = await executePlanStep(planHolder, { memoryDir, sessionId });
     note(trace, `goal: ${step.deduced}`);
     note(trace, "lane: PLAN NEXT — executed the active plan's next move as an @stepK snapshot write");
-    const rec = withLast(plainTurn(workingLine, step.text, { via: "plan", focus }), step.deduced);
+    const stepTurn = plainTurn(workingLine, step.text, { via: "plan", focus });
+    stepTurn.lane = "imperative";
+    const rec = withLast(stepTurn, step.deduced);
     rec.planState = planHolder.state;
     return rec;
   }
@@ -11669,6 +12068,7 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     if (asserted) {
       note(trace, "goal: teach/remember a new fact (declarative ACE sentence)");
       note(trace, "lane: assertTurn — grammar/ace.mjs parseAce matched a full triple with no residue");
+      asserted.lane = "teach";
       return withLast(asserted, "teach/remember a new fact");
     }
     // Bare declarative taxonomy (hyphenated-instance membership, article-led
@@ -11678,7 +12078,26 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     if (taxonomy) {
       note(trace, "goal: teach/remember a new fact (bare declarative taxonomy)");
       note(trace, "lane: bareTaxonomyTeach — hyphenated-instance or article-led kind-of declarative, stored before the ask engine could parse it as a question");
-      return withLast(plainTurn(workingLine, taxonomy.text, { via: taxonomy.via, miss: taxonomy.miss, focus }), "teach/remember a new fact");
+      const taxonomyTurn = plainTurn(workingLine, taxonomy.text, { via: taxonomy.via, miss: taxonomy.miss, focus });
+      if (!taxonomy.miss) taxonomyTurn.lane = "teach";
+      return withLast(taxonomyTurn, "teach/remember a new fact");
+    }
+  }
+  // Synonym/related-word questions read the store through the SKOS view.
+  // Routed before the ask engine: the generic parse reads "another word for
+  // X" as a bare object search and "what is related to X" through
+  // BARE_WHATIS_RE, both wrong lanes for this question.
+  if (memoryDir) {
+    const skos = await skosRelatedAnswer(memoryDir, workingLine, factRowsCache);
+    if (skos) {
+      const goal = `surface the remembered synonym/related-word neighbourhood of "${skos.term}"`;
+      note(trace, `goal: ${goal}`);
+      note(trace, `lane: SKOS VIEW — a synonym/related question ${skos.miss ? "matched but the store holds no such facts (honest miss)" : "answered from the store's relation facts"}`);
+      if (!skos.miss) note(trace, "source: .tmct/memory Facts (mgx:synonym/mgx:relatedTo/mgx:similarTo, read as skos:altLabel/skos:related)");
+      const skosTurn = plainTurn(workingLine, skos.text, { via: skos.miss ? "miss" : "fact", miss: skos.miss, focus });
+      if (!skos.miss) skosTurn.goal = goal;
+      skosTurn.lane = skos.miss ? "honest-miss" : "ask-set";
+      return withLast(skosTurn, goal);
     }
   }
   // MEMORY-STORE counts first ("how many facts / utterances do you know") — the

package/src/services/index.mjs

@@ -7,7 +7,10 @@
 // the ask() orchestration.
 
 // Chat surface (also reachable as the `./chat` subpath export).
-export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
+// createSession is the library's session sink — the same focus/last/planState
+// threading and memory-backend seam every shell shares; runTurn is the pure
+// single-turn engine underneath it.
+export { runChat, createSession, runTurn, COMMANDS, answerCount, renderStats } from "./chat.mjs";
 
 // Grammar / NL-over-graph primitives.
 export { ask, resolveObject } from "../domain/ask.mjs";

package/src/surfaces/web/memory-ask-browser.bundle.js

@@ -21376,6 +21376,189 @@ ${codeblock}`, options);
     }
   });
 
+  // src/domain/concept.mjs
+  var CONCEPT_CLASS, CLASS_NOUN, FOLLOWUP_SHAPES, RELATION_TERM, RELATION_KINDS, RELATION_RENDER, RELATION_FOLLOWUP_SHAPES;
+  var init_concept = __esm({
+    "src/domain/concept.mjs"() {
+      init_ask();
+      init_codegraph();
+      CONCEPT_CLASS = Object.freeze({
+        class: "Class",
+        module: "Module",
+        function: "Function",
+        method: "Method",
+        attribute: "Attribute",
+        variable: "GlobalVariable",
+        constant: "GlobalVariable",
+        commit: "Commit"
+      });
+      CLASS_NOUN = Object.freeze({
+        Class: ["class", "classes"],
+        Module: ["module", "modules"],
+        Function: ["function", "functions"],
+        Method: ["method", "methods"],
+        Attribute: ["attribute", "attributes"],
+        GlobalVariable: ["variable", "variables"],
+        Commit: ["commit", "commits"]
+      });
+      FOLLOWUP_SHAPES = Object.freeze({
+        Class: [
+          (x) => `which classes inherit from ${x}`,
+          (x) => `what does ${x} contain`,
+          (x) => `where is ${x} defined`
+        ],
+        Module: [
+          (x) => `what does ${x} import`,
+          (x) => `which modules import ${x}`,
+          (x) => `where is ${x} defined`
+        ],
+        Function: [
+          (x) => `what calls ${x}`,
+          (x) => `what does ${x} call`,
+          (x) => `where is ${x} defined`
+        ],
+        Method: [
+          (x) => `which class contains ${x}`,
+          (x) => `what calls ${x}`,
+          (x) => `where is ${x} defined`
+        ],
+        Attribute: [
+          (x) => `which class contains ${x}`,
+          (x) => `where is ${x} defined`
+        ],
+        GlobalVariable: [
+          (x) => `where is ${x} defined`,
+          (x) => `where is ${x} mentioned`
+        ],
+        Commit: [
+          (x) => `what did commit ${x} touch`,
+          (x) => `when did ${x} change`
+        ]
+      });
+      RELATION_TERM = Object.freeze({
+        import: "imports",
+        imports: "imports",
+        importing: "imports",
+        imported: "imports",
+        call: "calls",
+        calls: "calls",
+        calling: "calls",
+        called: "calls",
+        invoke: "calls",
+        invokes: "calls",
+        invoking: "calls",
+        contain: "contains",
+        contains: "contains",
+        containing: "contains",
+        containment: "contains",
+        member: "contains",
+        members: "contains",
+        inherit: "inherits",
+        inherits: "inherits",
+        inheriting: "inherits",
+        inheritance: "inherits",
+        extend: "inherits",
+        extends: "inherits",
+        extending: "inherits",
+        subclass: "inherits",
+        subclasses: "inherits",
+        subclassing: "inherits",
+        test: "tests",
+        tests: "tests",
+        testing: "tests",
+        tested: "tests",
+        coverage: "tests",
+        define: "defines",
+        defines: "defines",
+        defining: "defines",
+        defined: "defines",
+        definition: "defines",
+        definitions: "defines",
+        declaration: "defines",
+        touch: "touches",
+        touches: "touches",
+        touching: "touches",
+        touched: "touches",
+        cochange: "cochange",
+        "co-change": "cochange",
+        "change-coupling": "cochange",
+        coupled: "cochange",
+        // "export"/"exports" is also a curated seon lexicon noun, but that meta reading
+        // only owns "what does export mean" — no conflict with this vague-touch table.
+        export: "reexports",
+        exports: "reexports",
+        exporting: "reexports",
+        exported: "reexports",
+        reexport: "reexports",
+        reexports: "reexports",
+        reexporting: "reexports",
+        "re-export": "reexports",
+        "re-exports": "reexports",
+        "re-exporting": "reexports"
+      });
+      RELATION_KINDS = Object.freeze({
+        imports: ["imports"],
+        calls: ["calls", "callsSymbol"],
+        contains: ["contains"],
+        inherits: ["inherits"],
+        tests: ["tests"],
+        defines: ["defines"],
+        touches: ["touches", "touchesSymbol"],
+        cochange: ["cochange"],
+        reexports: ["reexports"]
+      });
+      RELATION_RENDER = Object.freeze({
+        imports: { verb: "imports", edgeNoun: "import" },
+        calls: { verb: "calls", edgeNoun: "call" },
+        contains: { verb: "contains", edgeNoun: "containment" },
+        inherits: { verb: "inherits from", edgeNoun: "inheritance" },
+        tests: { verb: "tests", edgeNoun: "test" },
+        defines: { verb: "defines", edgeNoun: "definition" },
+        touches: { verb: "touches", edgeNoun: "touch" },
+        cochange: { verb: "changes together with", edgeNoun: "change-coupling" },
+        reexports: { verb: "re-exports", edgeNoun: "re-export" }
+      });
+      RELATION_FOLLOWUP_SHAPES = Object.freeze({
+        imports: [
+          { side: "obj", make: (x) => `which modules import ${x}` },
+          { side: "subj", make: (x) => `what does ${x} import` }
+        ],
+        calls: [
+          { side: "obj", make: (x) => `what calls ${x}` },
+          { side: "subj", make: (x) => `what does ${x} call` }
+        ],
+        contains: [
+          { side: "subj", make: (x) => `what does ${x} contain` },
+          { side: "obj", make: (x) => `which class contains ${x}` }
+        ],
+        inherits: [
+          { side: "obj", make: (x) => `which classes inherit from ${x}` },
+          { side: "subj", make: (x) => `where is ${x} defined` }
+        ],
+        tests: [
+          { side: "obj", make: (x) => `what tests ${x}` },
+          { side: "obj", make: (x) => `where is ${x} defined` }
+        ],
+        defines: [
+          { side: "obj", make: (x) => `where is ${x} defined` },
+          { side: "subj", make: (x) => `what does ${x} contain` }
+        ],
+        touches: [
+          { side: "obj", make: (x) => `when did ${x} change` },
+          { side: "subj", make: (x) => `what did commit ${x} touch` }
+        ],
+        cochange: [
+          { side: "obj", make: (x) => `where is ${x} defined` },
+          { side: "subj", make: (x) => `which modules import ${x}` }
+        ],
+        reexports: [
+          { side: "subj", make: (x) => `what does ${x} export` },
+          { side: "obj", make: (x) => `where is ${x} defined` }
+        ]
+      });
+    }
+  });
+
   // src/adapters/toml-config.mjs
   var init_toml_config = __esm({
     "src/adapters/toml-config.mjs"() {
@@ -21432,7 +21615,7 @@ ${codeblock}`, options);
   });
 
   // src/adapters/corpus/conceptnet.mjs
-  var import_meta4, PKG_ROOT2, SLICE_FILE, MAP_FILE, SEON_CONCEPTS_FILE, SEON_DEFINITIONS_FILE, TIER2_DIR, TIER2_MANIFEST_FILE, WORDNET_DIR, WORDNET_MANIFEST_FILE;
+  var import_meta5, PKG_ROOT3, SLICE_FILE, MAP_FILE, SEON_CONCEPTS_FILE, SEON_DEFINITIONS_FILE, TIER2_DIR, TIER2_MANIFEST_FILE, WORDNET_DIR, WORDNET_MANIFEST_FILE;
   var init_conceptnet = __esm({
     "src/adapters/corpus/conceptnet.mjs"() {
       init_node_fs();
@@ -21442,15 +21625,15 @@ ${codeblock}`, options);
       init_node_path();
       init_dist();
       init_core();
-      import_meta4 = {};
-      PKG_ROOT2 = join(dirname(fileURLToPath2(import_meta4.url)), "..", "..", "..");
-      SLICE_FILE = join(PKG_ROOT2, "corpus", "conceptnet", "slice.jsonl");
-      MAP_FILE = join(PKG_ROOT2, "src", "adapters", "corpus", "conceptnet-map.toml");
-      SEON_CONCEPTS_FILE = join(PKG_ROOT2, "corpus", "seon", "concepts.jsonl");
-      SEON_DEFINITIONS_FILE = join(PKG_ROOT2, "corpus", "seon", "definitions.jsonl");
-      TIER2_DIR = join(PKG_ROOT2, "corpus", "tier2");
+      import_meta5 = {};
+      PKG_ROOT3 = join(dirname(fileURLToPath2(import_meta5.url)), "..", "..", "..");
+      SLICE_FILE = join(PKG_ROOT3, "corpus", "conceptnet", "slice.jsonl");
+      MAP_FILE = join(PKG_ROOT3, "src", "adapters", "corpus", "conceptnet-map.toml");
+      SEON_CONCEPTS_FILE = join(PKG_ROOT3, "corpus", "seon", "concepts.jsonl");
+      SEON_DEFINITIONS_FILE = join(PKG_ROOT3, "corpus", "seon", "definitions.jsonl");
+      TIER2_DIR = join(PKG_ROOT3, "corpus", "tier2");
       TIER2_MANIFEST_FILE = join(TIER2_DIR, "manifest.json");
-      WORDNET_DIR = join(PKG_ROOT2, "corpus", "wordnet");
+      WORDNET_DIR = join(PKG_ROOT3, "corpus", "wordnet");
       WORDNET_MANIFEST_FILE = join(WORDNET_DIR, "manifest.json");
     }
   });
@@ -21544,7 +21727,7 @@ ${codeblock}`, options);
       }
     };
   }
-  var import_meta5, NAMENET_DIR, EXTENSION_KINDS, CONCEPTNET_PREFER, BUILTIN_EXTENSIONS;
+  var import_meta6, NAMENET_DIR, EXTENSION_KINDS, CONCEPTNET_PREFER, BUILTIN_EXTENSIONS;
   var init_extensions = __esm({
     "src/services/extensions.mjs"() {
       init_node_path();
@@ -21552,8 +21735,8 @@ ${codeblock}`, options);
       init_node_url();
       init_toml_config();
       init_conceptnet();
-      import_meta5 = {};
-      NAMENET_DIR = join(dirname(fileURLToPath2(import_meta5.url)), "..", "..", "corpus", "namenet");
+      import_meta6 = {};
+      NAMENET_DIR = join(dirname(fileURLToPath2(import_meta6.url)), "..", "..", "corpus", "namenet");
       EXTENSION_KINDS = Object.freeze(["corpus", "lexicon", "templates", "pack", "ontology"]);
       CONCEPTNET_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:partOf", "mgx:capableOf"];
       BUILTIN_EXTENSIONS = Object.freeze(builtinExtensions());
@@ -22633,6 +22816,134 @@ ${JSON.stringify(envelope, null, 2)}`;
   init_fuzzy();
   init_lexicon();
 
+  // src/domain/reference-pack.mjs
+  init_hash();
+  init_lexicon();
+  init_concept();
+
+  // src/adapters/corpus/reference-pack.mjs
+  init_node_fs();
+  init_node_url();
+  init_node_path();
+  var import_meta4 = {};
+  var PKG_ROOT2 = join(dirname(fileURLToPath2(import_meta4.url)), "..", "..", "..");
+
+  // src/domain/dialogue-acts.mjs
+  var DIALOGUE_ACT_DIMENSIONS = Object.freeze([
+    "task",
+    "autoFeedback",
+    "alloFeedback",
+    "turnManagement",
+    "timeManagement",
+    "discourseStructuring",
+    "ownCommunicationManagement",
+    "partnerCommunicationManagement",
+    "socialObligationsManagement",
+    "contactManagement"
+  ]);
+  var DIALOGUE_ACTS = Object.freeze({
+    propositionalQuestion: Object.freeze({
+      dimension: "task",
+      gloss: "a yes/no question about whether a proposition holds ('does X import Y?')"
+    }),
+    checkQuestion: Object.freeze({
+      dimension: "task",
+      gloss: "a yes/no question whose asker already expects the answer yes ('..., right?')"
+    }),
+    setQuestion: Object.freeze({
+      dimension: "task",
+      gloss: "a wh-question asking for the members of a set ('what does X import?')"
+    }),
+    choiceQuestion: Object.freeze({
+      dimension: "task",
+      gloss: "a question asking which of the listed alternatives holds ('is X a module or a class?')"
+    }),
+    inform: Object.freeze({
+      dimension: "task",
+      gloss: "a declarative telling the addressee something (a teach turn; also tmct explaining its own function)"
+    }),
+    answer: Object.freeze({
+      dimension: "task",
+      gloss: "an inform that discharges a question just asked (an answer grounded in the graph)"
+    }),
+    confirm: Object.freeze({
+      dimension: "task",
+      gloss: "an answer 'yes' to a check question"
+    }),
+    disconfirm: Object.freeze({
+      dimension: "task",
+      gloss: "an answer 'no' to a check question"
+    }),
+    agreement: Object.freeze({
+      dimension: "task",
+      gloss: "an inform stating that the speaker holds what the addressee just stated to be true"
+    }),
+    disagreement: Object.freeze({
+      dimension: "task",
+      gloss: "an inform stating that the speaker holds what the addressee just stated to be false"
+    }),
+    correction: Object.freeze({
+      dimension: "task",
+      gloss: "a disagreement that also supplies the replacement ('no, I meant Y')"
+    }),
+    request: Object.freeze({
+      dimension: "task",
+      gloss: "asks the addressee to perform an action ('solve it' \u2014 a goal turn)"
+    }),
+    instruct: Object.freeze({
+      dimension: "task",
+      gloss: "a request the addressee is expected to carry out without negotiation (a bare imperative)"
+    }),
+    suggestion: Object.freeze({
+      dimension: "task",
+      gloss: "puts an action forward as advisable without claiming authority over the addressee"
+    }),
+    offer: Object.freeze({
+      dimension: "task",
+      gloss: "commits the speaker to an action, conditional on the addressee wanting it"
+    }),
+    autoPositive: Object.freeze({
+      dimension: "autoFeedback",
+      gloss: "the sender reports its own processing of the previous turn succeeded (an acknowledgement)"
+    }),
+    autoNegative: Object.freeze({
+      dimension: "autoFeedback",
+      gloss: "the sender reports its own processing of the previous turn failed \u2014 tmct's honest miss"
+    }),
+    initialGreeting: Object.freeze({
+      dimension: "socialObligationsManagement",
+      gloss: "opens an exchange of greetings ('hi')"
+    }),
+    returnGreeting: Object.freeze({
+      dimension: "socialObligationsManagement",
+      gloss: "answers a greeting with a greeting"
+    }),
+    thanking: Object.freeze({
+      dimension: "socialObligationsManagement",
+      gloss: "expresses gratitude for something the addressee did"
+    }),
+    apology: Object.freeze({
+      dimension: "socialObligationsManagement",
+      gloss: "expresses regret for something the speaker did"
+    })
+  });
+  var LANE_DIALOGUE_ACTS = Object.freeze({
+    teach: "inform",
+    "ask-set": "setQuestion",
+    "ask-propositional": "propositionalQuestion",
+    goal: "request",
+    imperative: "instruct",
+    "honest-miss": "autoNegative",
+    greeting: "initialGreeting",
+    thanks: "thanking",
+    help: "inform",
+    // The guessing game's turns are task-dimension: a reply that discharges
+    // the other side's move (a hint, a win, a rebuttal) is an answer; tmct
+    // stating its own move (an opening, its next guess) is an inform.
+    "game-answer": "answer",
+    "game-inform": "inform"
+  });
+
   // src/services/chat-session.mjs
   init_node_path();
   init_node_fs();