@polycode-projects/the-mechanical-code-talker 1.11.0 → 1.11.6

package/src/codegraph.mjs

@@ -1,4 +1,4 @@
-import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
+import { lookupByProseTokens, proseLayerHits, splitIdentifierWords } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
 import { CREATED_AT_PROP, UPDATED_AT_PROP, provenanceTagToSource } from "./memory/core.mjs";
 
@@ -204,6 +204,19 @@ function relLabel(g) {
   return g.prop ? `${g.predicate} [${g.prop}]` : g.predicate;
 }
 
+/** A class enum in a rendered heading: a multi-word enum reads as words
+ *  ("GlobalVariable" -> "Global Variable"); a single-word enum stays verbatim,
+ *  keeping the long-standing Module/Function/Entity headings byte-identical.
+ *  Title-cased (unlike ask.mjs's lowercase classDisplayName) because these
+ *  sites use the enum as a heading label, not mid-sentence prose — and ask.mjs
+ *  already imports this module, so reusing its formatter here would be a cycle. */
+function classHeading(cls) {
+  const c = cls || "Entity";
+  const words = splitIdentifierWords(c);
+  if (words.length < 2) return c;
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}
+
 // Show the first `n` items, then a "+K more" tail with the true count.
 function capJoin(items, n, sep = ", ") {
   if (items.length <= n) return items.join(sep);
@@ -216,7 +229,7 @@ const PROV_CAP = 8;
 /** Compact plain-text description of one individual — for an agent consumer. */
 export function renderDescribe(graph, ind, { candidates = [] } = {}) {
   const lines = [];
-  lines.push(`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`);
+  lines.push(`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`);
 
   const refs = (ind.derived_from || []).filter(isProvRef);
   if (refs.length) lines.push(`attestation: touched by ${refs.length} commit(s)`);
@@ -244,7 +257,7 @@ export function renderDescribe(graph, ind, { candidates = [] } = {}) {
   }
 
   if (candidates.length) {
-    lines.push(`other matches: ${candidates.map((c) => `${c.label} (${c.class})`).join(", ")}`);
+    lines.push(`other matches: ${candidates.map((c) => `${c.label} (${classHeading(c.class)})`).join(", ")}`);
   }
   if (graph.truncated.length) {
     lines.push(truncationNote(graph));
@@ -286,7 +299,7 @@ export function renderCompare(graph, indA, indB) {
   const klass = indA.class || "Entity";
   if ((indB.class || "Entity") !== klass) return null;
 
-  const lines = [`Comparing ${indA.label} and ${indB.label} (both ${klass}):`];
+  const lines = [`Comparing ${indA.label} and ${indB.label} (both ${classHeading(klass)}):`];
   const a = edgesFor(graph, indA.id);
   const b = edgesFor(graph, indB.id);
   const outByPred = pairByPredicate(a.out, b.out);
@@ -1382,7 +1395,7 @@ const CALL_CAP = 30;
 /** A class's methods + attributes (with sites/decorators) in one slice — replaces
  *  reading the class body. Uses the `contains` (seon:containsCodeEntity) relation. */
 export function renderMembers(graph, ind) {
-  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   const contains = edgesOfKind(graph, "contains").filter((e) => e.subject === ind.id);
   if (!contains.length) {
     lines.push("members: none recorded (empty class, or members not in the extracted graph). Use tmct_describe for its edges.");
@@ -1411,7 +1424,7 @@ const attrVal = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)
  *  (kept OUT of tmct_context's lean bundle; this is the targeted tool for them). */
 export function renderSignature(graph, ind) {
   const site = siteOf(ind);
-  const lines = [`${ind.label} — ${ind.class || "Entity"}${spanTag(site)}`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)}${spanTag(site)}`];
   const params = attrVal(ind, "params");
   const returns = attrVal(ind, "returns");
   if (params || returns || (ind.class || "") === "Method" || (ind.class || "") === "Function") {
@@ -1451,7 +1464,7 @@ export function renderSubclasses(graph, ind) {
     if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
     childrenOf.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject });
   }
-  const lines = [`${ind.label} — ${ind.class || "Entity"} (id: ${ind.id})`];
+  const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   lines.push(bases.length ? `extends: ${capJoin(bases, SUBCLASS_CAP)}` : "extends: (no internal/recorded base classes)");
   const visited = new Set([ind.id]);
   const levels = [];
@@ -1625,10 +1638,10 @@ export function callHint(graph, ind) {
 export function renderCalls(graph, ind) {
   const calls = edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id);
   if (!calls.length) {
-    return `${ind.label} — ${ind.class || "Entity"}: no in-repo calls recorded (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
+    return `${ind.label} — ${classHeading(ind.class)}: no in-repo calls recorded (calls only stdlib/external, or fine-grained call edges are not in the extracted graph).`;
   }
   const items = calls.map((e) => calleeRef(graph, e));
-  return `${ind.label} — ${ind.class || "Entity"} calls ${calls.length} in-repo symbol(s):\n  ${capJoin(items, CALL_CAP, "\n  ")}`;
+  return `${ind.label} — ${classHeading(ind.class)} calls ${calls.length} in-repo symbol(s):\n  ${capJoin(items, CALL_CAP, "\n  ")}`;
 }
 
 // ---- commit history with author/date/subject (Commit attributes) ----------------
@@ -1664,11 +1677,11 @@ export function renderFileHistory(graph, ind) {
 function renderSymbolHistory(graph, ind) {
   const commits = edgesOfKind(graph, "touchesSymbol").filter((e) => e.object === ind.id);
   if (!commits.length) {
-    return `${ind.label} — ${ind.class || "Entity"}: no symbol-level commit history recorded (outside the git-log window, or fine-grained history is not in the extracted graph).`;
+    return `${ind.label} — ${classHeading(ind.class)}: no symbol-level commit history recorded (outside the git-log window, or fine-grained history is not in the extracted graph).`;
   }
   const shown = commits.slice(0, HISTORY_CAP).map((e) => `  ${commitLine(graph, e.subject, e.subjectLabel)}`);
   const tail = commits.length > HISTORY_CAP ? `\n  …+${commits.length - HISTORY_CAP} more` : "";
-  return `${ind.label} — ${ind.class || "Entity"}: touched by ${commits.length} commit(s):\n${shown.join("\n")}${tail}`;
+  return `${ind.label} — ${classHeading(ind.class)}: touched by ${commits.length} commit(s):\n${shown.join("\n")}${tail}`;
 }
 
 /** Method history — commits touching a specific method symbol (`touchesSymbol`). */

package/src/domain.mjs

@@ -46,7 +46,7 @@ export function compileDomain(factRows, ruleRows) {
   for (const rule of ruleRows || []) {
     if (!String(rule.kind || "").startsWith("action-")) continue;
     const name = normTerm(rule.name);
-    if (!byName.has(name)) byName.set(name, { name, signatures: [], preconds: [], effects: [] });
+    if (!byName.has(name)) byName.set(name, { name, signatures: [], preconds: [], effects: [], constraints: [] });
     const family = byName.get(name);
     const slots = rule.slots || {};
     if (rule.kind === "action-signature") {
@@ -67,6 +67,12 @@ export function compileDomain(factRows, ruleRows) {
         subjectRole: normTerm(slots.subjectRole),
         objectRole: normTerm(slots.objectRole),
       });
+    } else if (rule.kind === "action-constraint") {
+      family.constraints.push({
+        left: normTerm(slots.left),
+        right: normTerm(slots.right),
+        guard: normTerm(slots.guard),
+      });
     }
   }
   const actions = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
@@ -75,6 +81,7 @@ export function compileDomain(factRows, ruleRows) {
       a.subjectClass.localeCompare(b.subjectClass) || a.targetClass.localeCompare(b.targetClass));
     action.preconds.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
     action.effects.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    action.constraints.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
   }
 
   // Class membership from typing edges. A member is a subject with a typing
@@ -92,6 +99,29 @@ export function compileDomain(factRows, ruleRows) {
     for (let i = members.length - 1; i > 0; i -= 1) if (members[i] === members[i - 1]) members.splice(i, 1);
   }
 
+  // A class-bound word (an effect role or constraint term that is neither
+  // "subject" nor "target") is substituted by its class's sole member at
+  // grounding time. With 0 or 2+ members that substitution would be a silent
+  // guess, so an ill-bound family fails loudly here instead.
+  const requireSoleMember = (word, where) => {
+    const count = (classMembers[word] || []).length;
+    if (count !== 1) {
+      throw new Error(`${where} names "${word}", which must be a class with exactly one member (it has ${count})`);
+    }
+  };
+  for (const action of actions) {
+    for (const effect of action.effects) {
+      for (const role of [effect.subjectRole, effect.objectRole]) {
+        if (role !== "subject" && role !== "target") requireSoleMember(role, `an effect role of "${action.name}"`);
+      }
+    }
+    for (const constraint of action.constraints) {
+      for (const word of [constraint.left, constraint.right, constraint.guard]) {
+        requireSoleMember(word, `a constraint term of "${action.name}"`);
+      }
+    }
+  }
+
   const dynamicPredicates = new Set();
   for (const action of actions) for (const effect of action.effects) dynamicPredicates.add(effect.predicate);
 
@@ -171,13 +201,24 @@ function precondHolds(precond, subject, target, state, domain) {
   return false;
 }
 
-function applyEffects(effects, subject, target, state) {
-  const roleTerm = (role) => (role === "target" ? target : subject);
+/** Ground an effect/constraint role word: "subject"/"target" bind the
+ *  grounding pair; any other word is class-bound and binds the class's sole
+ *  member — its companion semantics (compileDomain guarantees exactly one). */
+const roleBinding = (role, subject, target, domain) => {
+  if (role === "subject") return subject;
+  if (role === "target") return target;
+  return (domain.classMembers[role] || [])[0];
+};
+
+const positionIn = (rows, term, predicate) =>
+  rows.find((r) => r.subject === term && r.predicate === predicate)?.object;
+
+function applyEffects(effects, subject, target, state, domain) {
   let rows = state;
   let changed = false;
   for (const effect of effects) {
-    const effSubject = roleTerm(effect.subjectRole);
-    const effObject = roleTerm(effect.objectRole);
+    const effSubject = roleBinding(effect.subjectRole, subject, target, domain);
+    const effObject = roleBinding(effect.objectRole, subject, target, domain);
     const already = rows.some((r) =>
       r.subject === effSubject && r.predicate === effect.predicate && r.object === effObject);
     if (already) continue;
@@ -189,6 +230,42 @@ function applyEffects(effects, subject, target, state) {
   return [...rows].sort(rowSort);
 }
 
+/** True when `state` still permits every companion (class-bound effect
+ *  subject) to move WITH the grounded subject. Co-location is a derived
+ *  precondition, not a taught one: the taught effect says the companion ends
+ *  up at the target, and applying that from a state where the companion
+ *  stands elsewhere would teleport it instead of carrying it. Trivially true
+ *  when the subject is its own companion. */
+function companionsCoLocated(action, subject, target, state, domain) {
+  for (const effect of action.effects) {
+    if (effect.subjectRole === "subject" || effect.subjectRole === "target") continue;
+    const companion = roleBinding(effect.subjectRole, subject, target, domain);
+    if (companion === subject) continue;
+    const subjectAt = positionIn(state, subject, effect.predicate);
+    if (!subjectAt || positionIn(state, companion, effect.predicate) !== subjectAt) return false;
+  }
+  return true;
+}
+
+/** True when a successor state breaks one of the action's constraints: the
+ *  left and right members sharing a position under one of the action's
+ *  effect predicates while the guard member stands elsewhere. */
+function constraintViolated(action, nextState, domain) {
+  if (!action.constraints.length) return false;
+  const predicates = [...new Set(action.effects.map((e) => e.predicate))];
+  for (const constraint of action.constraints) {
+    const left = (domain.classMembers[constraint.left] || [])[0];
+    const right = (domain.classMembers[constraint.right] || [])[0];
+    const guard = (domain.classMembers[constraint.guard] || [])[0];
+    for (const predicate of predicates) {
+      const leftAt = positionIn(nextState, left, predicate);
+      if (!leftAt || positionIn(nextState, right, predicate) !== leftAt) continue;
+      if (positionIn(nextState, guard, predicate) !== leftAt) return true;
+    }
+  }
+  return false;
+}
+
 /** Every legal grounded action from `state`, with its successor.
  *  Deterministic: actions, signatures, and members are walked sorted. */
 export function movesFromRules(state, domain, { budget = 5000 } = {}) {
@@ -214,8 +291,10 @@ export function movesFromRules(state, domain, { budget = 5000 } = {}) {
             if (!precondHolds(precond, subject, target, state, domain)) { ok = false; break; }
           }
           if (!ok) continue;
-          const nextState = applyEffects(action.effects, subject, target, state);
+          if (!companionsCoLocated(action, subject, target, state, domain)) continue;
+          const nextState = applyEffects(action.effects, subject, target, state, domain);
           if (!nextState) continue;
+          if (constraintViolated(action, nextState, domain)) continue;
           out.push({
             action: {
               name: action.name,

package/src/interpret/normalize.mjs

@@ -8,6 +8,7 @@
 import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
   NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, VERB_TO_KIND, ENTITY_TO_TYPE,
+  TRAILING_SCOPE_FILLER,
 } from "../ask-vocab.mjs";
 
 export function escapeRegex(s) {
@@ -146,6 +147,21 @@ const EXPLAIN_WRAPPER_RE = /^explain\s+(?:to\s+me\s+|please\s+)*(.+?)\??$/i;
 /** "tell me <Q>" (bare, no "about") -> "<Q>"; "tell me about X" is a
  *  different, untouched territory (chat.mjs's vagueTouchTermOf). */
 const TELL_ME_WRAPPER_RE = /^tell\s+me\s+(.+?)\??$/i;
+/** "do you know <Q>" -> "<Q>", gated on an interrogative remainder — so
+ *  "do you know anything about movies" (small-talk, no embedded question)
+ *  passes through untouched. */
+const KNOW_WRAPPER_RE = /^do\s+you\s+know\s+(.+?)\??$/i;
+/** "i'd like to know <Q>" / "i want to know <Q>" -> "<Q>", same
+ *  interrogative-remainder gate as KNOW_WRAPPER_RE. */
+const WANT_KNOW_WRAPPER_RE = /^i(?:'d|\s+would)?\s+(?:like|want|need)\s+to\s+know\s+(.+?)\??$/i;
+/** EMBEDDED-QUESTION DE-INVERSION: the wrappers above unwrap "could you
+ *  tell me what a dog is" down to the embedded clause "what a dog is",
+ *  which keeps declarative word order — nothing downstream parses it. Fold
+ *  it back to the direct question the meta lane already owns. Deliberately
+ *  closed to a short (≤3-word) subject so an ordinary relative clause
+ *  ("what the parser does with X …") is never re-inverted. */
+const EMBEDDED_WHATIS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2})\s+(is|are)\??$/i;
+const EMBEDDED_MEANS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2})\s+means\??$/i;
 /** show/give-me presentation bridge: a kind-listing remainder is left
  *  untouched, a relation/interrogative remainder unwraps to itself, anything
  *  else bridges to "describe <thing>". */
@@ -194,6 +210,14 @@ export function applyPreambleFrames(text) {
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(TELL_ME_WRAPPER_RE);
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(KNOW_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(WANT_KNOW_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(EMBEDDED_WHATIS_RE);
+    if (m) q = `what ${m[2].toLowerCase()} ${m[1].trim()}`;
+    m = q.match(EMBEDDED_MEANS_RE);
+    if (m) q = `what does ${m[1].trim()} mean`;
     m = q.match(SHOW_GIVE_ME_RE);
     if (m) {
       const rest = m[1].trim();
@@ -387,6 +411,28 @@ export const PHRASING_FRAMES = Object.freeze([
   //   a bare "is").
   { re: /^were\s+is\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
 
+  // DESCRIBE PARAPHRASES ("what is the purpose of X", "what does X do in
+  // this codebase") → the meta/whatis shape ("what is a <term>"), which
+  // already answers a unique code entity via metaFallbackEntityAnswer. The
+  // term slot refuses an a/an article or a pronoun lead so the vocabulary
+  // phrasings ("what is the purpose of a horse", "what does it do here")
+  // pass through untouched to their own memory-facts and context readers,
+  // which read the raw text and must keep their turn. A leading "the" is
+  // entity-term noise (mirrors resolveObject's own article strip). The
+  // sibling "what is X for" paraphrase is deliberately NOT a frame: chat's
+  // module-overview lane owns that phrasing and gates on an ask() miss, so
+  // it lives as ask()'s own miss-gated fallback (WHATIS_FOR_FALLBACK_RE)
+  // instead, adopted only when the meta reading actually answers.
+  { re: /^what\s+is\s+the\s+purpose\s+of\s+(?:the\s+)?(?!(?:an?|it|this|that|these|those)\s)(.+?)\??$/i, to: (m) => `what is a ${m[1]}` },
+  // Scoped form only: bare "what does X do" stays unrewritten — the chat
+  // surface's module-grain overview lane owns it and only gets its turn when
+  // ask() misses, so claiming it here would swap that richer answer for the
+  // one-line meta fallback.
+  {
+    re: new RegExp(`^what\\s+does\\s+(?:the\\s+)?(?!(?:an?|it|this|that|these|those)\\s)(.+?)\\s+do\\s+(?:${TRAILING_SCOPE_FILLER.map(escapeRegex).join("|")})\\??$`, "i"),
+    to: (m) => `what is a ${m[1]}`,
+  },
+
   // PREDICATIVE QUALIFIER ("which modules are untested") → the ATTRIBUTIVE form
   // ("untested modules") the grammar already answers. The QUALIFIER must sit
   // immediately after are/is, so "…are NOT tested" keeps its own set-complement handler.

package/src/interpret/strategies/keywords.mjs

@@ -92,13 +92,14 @@ export function parseKeywordSpot(text, nlp = null) {
     verbHit = findPhrase(lemmaWords, VERB_TO_KIND);
     if (verbHit) canonWords = lemmaWords;
   }
+  let fuzzyVerb = false;
   if (!verbHit) {
     // tier 3: bounded-edit-distance rewrite toward verb/modifier keywords only
     // ("impotr" -> "import"); ≥4-char words only — below that the bound covers
     // half of English (and "and" is 1 edit from the "land in" constituent).
     const fuzzyWords = lcWords.map((w) => (w.length >= 4 && eligibleForCanon(w) ? fuzzyVocabWord(w) || w : w));
     verbHit = findPhrase(fuzzyWords, VERB_TO_KIND);
-    if (verbHit) canonWords = fuzzyWords;
+    if (verbHit) { canonWords = fuzzyWords; fuzzyVerb = true; }
   }
   if (!verbHit && lcWords.includes("by")) {
     // A participle with no active verb entry still marks a passive when a passive
@@ -109,6 +110,9 @@ export function parseKeywordSpot(text, nlp = null) {
     }
   }
   if (!verbHit) return null;
+  // A tier-3 verb is a REPAIR, not a reading — downstream consumers (the teach
+  // lane's canonical receipt) need to know the difference, so it rides the AST.
+  const stamp = (ast) => (fuzzyVerb ? { ...ast, fuzzyVerb: true } : ast);
   // POS rescue (Node-side only): a relation word used as a NOUN in a "the
   // <imports> of <term>" frame would otherwise misparse; only fires inside this
   // exact det+NOUN+"of" shape, since the same word tags NOUN in genuine verb use too.
@@ -119,7 +123,7 @@ export function parseKeywordSpot(text, nlp = null) {
       const tags = nlp.posTags(words);
       if (tags[i] === "NOUN") {
         const objText = words.slice(i + 2).filter((w, j) => !STOPWORDS.has(lcWords[i + 2 + j])).join(" ").trim();
-        if (objText) return { shape: "forward", entityType: null, modifier: "direct", kind: verbHit.kind, object: objText };
+        if (objText) return stamp({ shape: "forward", entityType: null, modifier: "direct", kind: verbHit.kind, object: objText });
       }
     }
   }
@@ -154,7 +158,7 @@ export function parseKeywordSpot(text, nlp = null) {
   // "when" turns a touches decomposition temporal; other verbs fall through.
   if (kind === "touches" && lcWords.includes("when")) {
     const objText = beforeText || afterText;
-    if (objText) return { shape: "when", entityType: null, modifier: "direct", kind: "touches", object: objText };
+    if (objText) return stamp({ shape: "when", entityType: null, modifier: "direct", kind: "touches", object: objText });
   }
 
   // "who last touched X" would otherwise list every touching commit's author,
@@ -162,7 +166,7 @@ export function parseKeywordSpot(text, nlp = null) {
   // stopwords and wouldn't survive into beforeText/afterText.
   if (kind === "touches" && lcWords.includes("who") && lcWords.includes("last")) {
     const objText = beforeText || afterText;
-    if (objText) return { shape: "whoLast", entityType: null, modifier: "direct", kind: "touches", object: objText };
+    if (objText) return stamp({ shape: "whoLast", entityType: null, modifier: "direct", kind: "touches", object: objText });
   }
 
   // Reversible passive ("PATIENT is VERBed BY AGENT"): a passive auxiliary plus a
@@ -190,7 +194,7 @@ export function parseKeywordSpot(text, nlp = null) {
         nextAfterBy = lcWords[i]; break;
       }
       const agentNamed = nextAfterBy != null && !WH_WORDS.has(nextAfterBy) && !ENTITY_TO_TYPE[nextAfterBy];
-      return { shape: agentNamed ? "forward" : "reverse", entityType, modifier, kind, object };
+      return stamp({ shape: agentNamed ? "forward" : "reverse", entityType, modifier, kind, object });
     }
   }
 
@@ -201,19 +205,19 @@ export function parseKeywordSpot(text, nlp = null) {
     let subject = beforeText;
     let object = afterText;
     if (INHERITS_REVERSE_VERBS.includes(verbPhrase)) [subject, object] = [object, subject];
-    return { shape: "ask", entityType: null, modifier: "direct", kind, subject, object };
+    return stamp({ shape: "ask", entityType: null, modifier: "direct", kind, subject, object });
   }
-  if (afterText) return { shape: "reverse", entityType, modifier, kind, object: afterText };
+  if (afterText) return stamp({ shape: "reverse", entityType, modifier, kind, object: afterText });
   // "what is a kind of class": when the object is itself an entity-type noun, the
   // entity match swallows the whole post-verb span as a grain qualifier, leaving
   // afterText empty — re-read that span as the object instead.
   if (kind === "inherits" && !beforeText && entityHit && entityHit.start === verbHit.end) {
     const entityText = canonWords.slice(entityHit.start, entityHit.end).join(" ");
-    if (entityText) return { shape: "reverse", entityType: null, modifier, kind, object: entityText };
+    if (entityText) return stamp({ shape: "reverse", entityType: null, modifier, kind, object: entityText });
   }
   // forward keeps the spotted entityType (traverse()'s commit-as-subject grain
   // selection); modifier stays hardcoded since no forward closure traversal exists.
-  if (beforeText) return { shape: "forward", entityType, modifier: "direct", kind, object: beforeText };
+  if (beforeText) return stamp({ shape: "forward", entityType, modifier: "direct", kind, object: beforeText });
   return null;
 }
 

package/src/ledger-viz.mjs

@@ -1,18 +1,37 @@
-// ledger-viz.mjs — `tmct viz --ledger`: the memory graph as a readable ledger
-// of fact-sentences around one focus term (PLAN_VIZ_LEDGER.md phase 1).
+// ledger-viz.mjs — `tmct viz`: the memory graph as a readable ledger of
+// fact-sentences around one focus term, with the in-page chat dock
+// (PLAN_VIZ_LEDGER.md).
 //
-// Same three-piece factoring as viz.mjs:
+// Three pure/impure-separated pieces:
 //   - computeLedgerData(repoDir, opts)      — I/O (loadMemory) + derivation
 //   - computeLedgerDataFromPayload(payload) — the pure derivation half
 //   - renderLedgerHtml(data)                — pure string builder, one
 //     self-contained document, no external requests.
+// readMemoryAskBundle() is the one extra bit of I/O renderLedgerHtml itself
+// doesn't do: it reads the checked-in chat-dock engine bundle.
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "./memory/core.mjs";
-import { escapeHtml, embedJson } from "./viz.mjs";
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 export const LEDGER_ROW_LIMIT_DEFAULT = 20000;
 
+/** Read the checked-in browser memory-ask-engine bundle
+ *  (`src/memory-ask-browser.bundle.js`) — the real memory-graph answer engine
+ *  (chat.mjs's factAnswer/factReadBack) the chat dock runs on. Returns `""`,
+ *  never throws, if the bundle hasn't been built — the page then renders with
+ *  an honest "chat unavailable" note instead of a dock. */
+export async function readMemoryAskBundle() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return await readFile(join(here, "memory-ask-browser.bundle.js"), "utf8");
+  } catch {
+    return "";
+  }
+}
+
 // Predicate rendering + family grouping. A closed table with a verbatim
 // fallback: an unknown predicate still reads as itself, never breaks the page.
 const PHRASES = new Map([
@@ -122,7 +141,7 @@ export function computeLedgerDataFromPayload(payload, { focus, term, rowLimit =
 
   // Focus: the asked term when it resolves; otherwise the newest taught
   // row's subject, then the highest-degree term. A miss never seeds a
-  // phantom term (viz.mjs's own --term rule).
+  // phantom term.
   let focusTerm = null;
   const asked = focus || term;
   if (asked) {
@@ -177,8 +196,7 @@ export async function computeLedgerData(repoDir, opts = {}) {
   return computeLedgerDataFromPayload(payload, opts);
 }
 
-/** The chat dock's answer-to-focus resolver (viz.mjs's findAnsweredTermIds,
- *  retargeted at the ledger term index). Pass 1: earliest term label (≥3
+/** The chat dock's answer-to-focus resolver. Pass 1: earliest term label (≥3
  *  chars, space-boundary) appearing in the ANSWER text. Pass 2: strip the
  *  QUESTION's crust and try the remainder as one normalized term. Returns a
  *  term string or null. Self-contained on purpose: its source is injected
@@ -309,6 +327,7 @@ ${THEME_TOKENS_CSS}
   .chatlog .u::before { content: "tmct> "; color: var(--taught); }
   .chatlog .a { font-size: .9rem; line-height: 1.45; }
   .chatlog .a.miss { color: var(--muted); }
+  .chatlog .a.goal { font-family: ${MONO_STACK}; font-size: .72rem; color: var(--muted); }
   .chatask { display: flex; align-items: center; gap: .5rem; }
   .chatlog:not(:empty) + .chatask { border-top: 1px solid var(--line); margin-top: .55rem; padding-top: .55rem; }
   .chatask .prompt { color: var(--taught); font-size: .78rem; }
@@ -424,7 +443,7 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
   }
   function renderLedger() {
     const box = el("ledger");
-    if (!focus) { box.innerHTML = '<div class="empty">Nothing in memory yet. Teach a fact in chat, then re-run tmct viz --ledger.</div>'; return; }
+    if (!focus) { box.innerHTML = '<div class="empty">Nothing in memory yet. Teach a fact in chat, then re-run tmct viz.</div>'; return; }
     const all = LEDGER.rows.filter((r) => touches(r, focus));
     const mine = all.filter((r) => passes(r, null));
     const srcs = new Set(all.map((r) => r.src.split(" | ")[0]));
@@ -585,6 +604,9 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
         }
         if (fact && fact.text) {
           addLine("a", esc(fact.text).replace(/\\n/g, "<br>"));
+          // Same formatting contract as chat's withGoalLine: capitalized,
+          // full-stop-terminated, rendered only when the engine deduced one.
+          if (fact.goal) addLine("a goal", "Goal (inferred): " + esc(fact.goal.charAt(0).toUpperCase() + fact.goal.slice(1)) + ".");
           const hit = resolveAnsweredTerm(fact.text, q, LEDGER.terms, tmctMemoryAsk.normFactTerm);
           if (hit) refocusWithLabel(hit, q);
         } else {

package/src/memory/core.mjs

@@ -1173,9 +1173,11 @@ export const RULE_KIND_RECURSIVE = "recursive";
 export const RULE_KIND_ACTION_SIGNATURE = "action-signature";
 export const RULE_KIND_ACTION_PRECOND = "action-precond";
 export const RULE_KIND_ACTION_EFFECT = "action-effect";
+export const RULE_KIND_ACTION_CONSTRAINT = "action-constraint";
 export const RULE_KINDS = Object.freeze([
   RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE,
   RULE_KIND_ACTION_SIGNATURE, RULE_KIND_ACTION_PRECOND, RULE_KIND_ACTION_EFFECT,
+  RULE_KIND_ACTION_CONSTRAINT,
 ]);
 
 export const RULE_NAME_PROP = "mgx:ruleName";
@@ -1203,6 +1205,12 @@ const RULE_SLOT_SPEC = {
     ["predicate", "mgx:ruleActionEffectPredicate"], ["subjectRole", "mgx:ruleActionEffectSubject"],
     ["objectRole", "mgx:ruleActionEffectObject"],
   ],
+  // "the <left> may not be with the <right> without the <guard>" — each slot
+  // names a class whose sole member src/domain.mjs resolves at compile time.
+  [RULE_KIND_ACTION_CONSTRAINT]: [
+    ["left", "mgx:ruleActionConstraintLeft"], ["right", "mgx:ruleActionConstraintRight"],
+    ["guard", "mgx:ruleActionConstraintGuard"],
+  ],
 };
 
 // Content-addressed over (kind, name, ...slots in RULE_SLOT_SPEC order),
@@ -1568,13 +1576,24 @@ export async function removeFacts(dir, ids) {
  *  contradiction (below it the fact is too weak to contradict anything). */
 export const CONTRADICTION_TRUST_FLOOR = 0.5;
 
+export const HAS_A_PREDICATE = "mgx:hasA";
+export const CAPABLE_OF_PREDICATE = "mgx:capableOf";
+
+/** Predicates whose real-world semantics allow many objects at once ("a dog
+ *  has legs" AND "a dog has a tail"; "a bird can fly" AND "a bird can sing"),
+ *  so a second object is a second fact, never a disagreement. A closed list:
+ *  every predicate outside it keeps the full contradiction contract. */
+export const MULTI_VALUED_PREDICATES = new Set([HAS_A_PREDICATE, CAPABLE_OF_PREDICATE]);
+
 /** Facts that CONTRADICT: same (subject, predicate), different object, each
  *  above the trust floor. Returns groups (trust-desc) so callers surface both,
- *  never silently pick one. Same (s,p,o) is corroboration, not contradiction. */
+ *  never silently pick one. Same (s,p,o) is corroboration, not contradiction,
+ *  and a MULTI_VALUED_PREDICATES predicate never contradicts on object count. */
 export function findContradictions(memory, { floor = CONTRADICTION_TRUST_FLOOR } = {}) {
   const rows = readFactRows(memory).filter((r) => r.trust >= floor);
   const byKey = new Map();
   for (const r of rows) {
+    if (MULTI_VALUED_PREDICATES.has(r.predicate)) continue;
     const key = `${r.subject} ${r.predicate}`;
     if (!byKey.has(key)) byKey.set(key, []);
     byKey.get(key).push(r);

package/src/memory/shacl.mjs

@@ -8,7 +8,7 @@
 const MEMORY_CLASSES = new Set(["Utterance", "Fact", "Session", "Source", "Rule"]);
 const RULE_KINDS = new Set([
   "compose2", "filter", "recursive",
-  "action-signature", "action-precond", "action-effect",
+  "action-signature", "action-precond", "action-effect", "action-constraint",
 ]);
 
 // Mirrors core.mjs's own (unexported) RULE_SLOT_SPEC exactly — the single
@@ -26,6 +26,9 @@ const RULE_SLOT_PROPS = {
   "action-effect": [
     "mgx:ruleActionEffectPredicate", "mgx:ruleActionEffectSubject", "mgx:ruleActionEffectObject",
   ],
+  "action-constraint": [
+    "mgx:ruleActionConstraintLeft", "mgx:ruleActionConstraintRight", "mgx:ruleActionConstraintGuard",
+  ],
 };
 
 function attrValue(ind, prop) {

package/src/memory-ask-browser-entry.mjs

@@ -1,15 +1,15 @@
-// memory-ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded
-// "Ask the graph" panel's memory-graph engine.
+// memory-ask-browser-entry.mjs — the esbuild entry for the ledger page's
+// chat dock (`tmct viz`, src/ledger-viz.mjs).
 //
 // Re-exports `factAnswer` (src/chat.mjs) and `createInMemoryStore`
-// (src/memory/core.mjs), which lets the panel hand `factAnswer` the page's
+// (src/memory/core.mjs), which lets the dock hand `factAnswer` the page's
 // already-embedded payload with zero fs I/O. Called with `envelope: null,
 // miss: true` to arm factAnswer's bare-question regex fallbacks directly,
-// bypassing the structural-graph parse pipeline this panel has no use for.
+// bypassing the structural-graph parse pipeline this dock has no use for.
 import { factAnswer, factReadBack } from "./chat.mjs";
 import { createInMemoryStore, normFactTerm } from "./memory/core.mjs";
 
-// normFactTerm is re-exported too, for viz.mjs's client-side term normalization.
+// normFactTerm is re-exported too, for the page's client-side term normalization.
 // factReadBack carries the taught-relation chases (grandfather-style questions)
 // that factAnswer's own lanes don't reach.
 globalThis.tmctMemoryAsk = { factAnswer, factReadBack, createInMemoryStore, normFactTerm };