@polycode-projects/the-mechanical-code-talker 1.8.14 → 1.8.16

package/README.md

@@ -79,6 +79,12 @@ the connecting sentence itself, citing both sources. The `source: ace:chat:…`
 part is a real provenance receipt. Every fact tmct stores records where it
 came from and when (more on that below).
 
+The first `tell()` call above replies too: `noted — remembered 1 fact:
+controller rdfs:subClassOf handler (controller is a type of handler)`. The
+part in parentheses is a paraphrase. tmct generates it and checks it against
+its own inference rules before showing it, so it never just guesses at
+prose.
+
 ```
 $ tmct
 tmct> what talks to the payment module?
@@ -188,6 +194,23 @@ exactly. It checks the type itself and its subclasses first. Only if nothing
 matches there does it widen to a related type, and when it does, it says so
 plainly rather than presenting the looser match as exact.
 
+**Comparing two things.** "compare TaskController and UserController" or "how
+is TaskController different from UserController" lines up both entities'
+shared and differing edges side by side: *"Comparing TaskController and
+UserController (both Class): inherits [seon:hasSuperType]: TaskController (1)
+-> Controller; UserController (1) -> Controller"*. Every row is a real edge
+or attribute from the graph, never a hand-written diff.
+
+**Up-refining to a containing module.** A class rarely has its own
+symbol-precise commit or import record. "who touched TaskController" answers
+from its containing module's real history instead of a confident-looking but
+wrong "nothing touched it".
+
+**Following a list.** tmct remembers the last list it gave you. After
+"which modules import src/core/model.mjs", "which of those are tested" or
+"how many of those" resolves "those"/"them" against that list, not a fresh,
+unresolved pronoun.
+
 **Synonyms and everyday phrasing.** tmct matches many of the words people
 actually use for the same idea, from a curated synonym list plus a filtered
 ConceptNet slice. A slightly different word for the same concept still
@@ -242,6 +265,11 @@ longer, multi-sentence account instead of one line. Every sentence in it is
 lifted from a real graph edge, attribute, or taught fact — never generated
 free text.
 
+The wording varies a little too. A small, curated, deterministic pool swaps a
+handful of connector words, like "defined in", "located in", or "found in".
+The same fact doesn't read identically for every entity, but the same
+question against the same entity always renders the same way.
+
 ```
 $ node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral
 tmct> give me a detailed overview of how the Store works
@@ -314,8 +342,8 @@ from the environment. There's no CLI flag yet — this is a library-level
 option for now, newer and less exercised than the default backend.
 
 Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
-arbitrary fact, like "margo eats ribs", and it mints a fact you can later ask
-about directly: "what does margo eat", or "does margo eat ribs".
+arbitrary fact, like "margo really eats ribs", and it mints a fact you can
+later ask about directly: "what does margo eat", or "does margo eat ribs".
 
 New vocabulary compounds as you teach it. "redis is a cache" mints "redis" as
 a class-level concept even though it was never in the built-in lexicon, and a
@@ -326,6 +354,10 @@ to ground one side first. Quantified teaching works too: "some functions are
 risky" stores the quantifier, and a later "how many functions are risky"
 answers "A few."
 
+Once you've taught a few facts, "how many facts are there" counts them back.
+That's the same count phrasing a code graph answers "how many classes are
+there" with, just now reading tmct's own memory.
+
 ### Provenance and trust
 
 Every fact and text block records **where it came from and when**. Sources are

package/package.json

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

@@ -1977,23 +1977,33 @@ function singularizeSurface(word) {
 const SOME_A_FEW_RE = /^(some|a few)\s+([\w-]+)\s+are\s+([\w-]+)$/i;
 
 /** "(every|each|all|a|an )?X is/are (a|an )?Y" — the shape the unknown-subject
- *  fallback recognizes (group 2 = X, group 3 = Y); group 1 (when present)
+ *  fallback recognizes (group 2 = X, group 4 = Y); group 1 (when present)
  *  names the determiner, so the caller can tell a genuine "every" universal
  *  apart from a singular/specific-entity "a"/bare reading (only "every" gets a
  *  recorded quantifier here — this function's OWN caller passes it through to
  *  teachFact; assertTurn, below, records the same "every" quantifier
- *  independently for the pre-existing ACE-success path). Y (the object) is a
- *  single token, same as parseAce's own copula fragments; X (the subject) is
- *  ONE OR TWO tokens (Tier-5 playtest fix: "vulcan gizmo is a tool"/"remember
- *  vulcan gizmo is a tool" fell straight to a "teach me" nudge that offered
- *  THIS EXACT phrasing as the fix, then itself failed when tried — a
- *  single-token-only subject was too narrow for a natural 2-word noun phrase,
- *  the same class of gap OWNS_TEACH_RE's own object had before its own
- *  Tier-5 widening, above). The greedy quantifier tries the longer 2-word
- *  subject first, backtracking to 1 word only if the tail doesn't then start
- *  with is/are — the "is/are" anchor immediately after the subject removes
- *  the ambiguity a fully free-form multi-word subject would otherwise have. */
-const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(?:is|are)\s+(?:an?\s+)?([\w-]+)$/i;
+ *  independently for the pre-existing ACE-success path). Group 3 is the
+ *  copula itself (is/are) — CAPTURED (not just matched) so a caller can tell
+ *  a genuinely PLURAL subject phrasing ("all men ARE mortal") apart from a
+ *  singular one ("redis IS a cache"): singularizing the subject before
+ *  storage is only ever correct for the former (see unknownSubjectFallback's
+ *  and unknownObjectFallback's own docblocks — this is the "men"->"man" fix's
+ *  own safety gate, added after singularizing unconditionally was found live
+ *  to corrupt the pre-existing "redis is a cache" pinned case: "redis", a
+ *  proper noun that happens to end in "s", naively strips to "redi" if
+ *  singularized on an "is" sentence, where no such fold was ever needed).
+ *  Y (the object) is a single token, same as parseAce's own copula fragments;
+ *  X (the subject) is ONE OR TWO tokens (Tier-5 playtest fix: "vulcan gizmo
+ *  is a tool"/"remember vulcan gizmo is a tool" fell straight to a "teach me"
+ *  nudge that offered THIS EXACT phrasing as the fix, then itself failed when
+ *  tried — a single-token-only subject was too narrow for a natural 2-word
+ *  noun phrase, the same class of gap OWNS_TEACH_RE's own object had before
+ *  its own Tier-5 widening, above). The greedy quantifier tries the longer
+ *  2-word subject first, backtracking to 1 word only if the tail doesn't then
+ *  start with is/are — the "is/are" anchor immediately after the subject
+ *  removes the ambiguity a fully free-form multi-word subject would
+ *  otherwise have. */
+const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(is|are)\s+(?:an?\s+)?([\w-]+)$/i;
 
 /** ISA-family predicates (mirrors the private ISA_PREDICATES set defined near
  *  memoryFacts, below, at module scope — both are simple top-level consts
@@ -2092,7 +2102,7 @@ async function ungroundedPairHint(payload, lexicon, memoryDir) {
   if (!memoryDir) return "";
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return "";
-  const [, , subjectRaw, objectRaw] = m;
+  const [, , subjectRaw, , objectRaw] = m;
   const { loadLexicon } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   if (await isGroundedTerm(subjectRaw, lex, memoryDir)) return "";
@@ -2144,12 +2154,29 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
-  const [, det, subjectRaw, objectRaw] = m;
+  const [, det, subjectRaw, verb, objectRaw] = m;
   const { loadLexicon, lookupNoun, lookupAdjective, classify } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   // A known X's own ACE miss is a real miss — never silently reinterpreted here.
   if (classify(subjectRaw, lex)) return null;
   const quantifier = /^every$/i.test((det || "").trim()) ? "every" : "";
+  // Singularize the SUBJECT before storage, but ONLY on a genuinely PLURAL
+  // phrasing ("all men ARE mortal", verb "are") — mirrors SOME_A_FEW_RE's own
+  // singularizeSurface() call (above), which is safe unconditionally there
+  // only because that shape's own regex requires "are" by construction. This
+  // shape (UNKNOWN_SUBJECT_RE) also matches singular "is" sentences ("redis
+  // is a cache"), where singularizing must NEVER run — "redis" naively folds
+  // to "redi" under the same naive -s-strip, a real regression caught live by
+  // the pinned "redis is a cache" tests when this fix first applied
+  // unconditionally. So "all men are mortal" stores under "man" (matching
+  // whatever "john is a man" already typed John as), not the raw plural
+  // "men", while "redis is a cache" stores "redis" untouched. Without this,
+  // findIsaChain's 2-hop proof (john->man, man->mortal) can never join, since
+  // the second fact was keyed on a different string ("men") than the first
+  // fact's object ("man"). classify(subjectRaw, lex) above already folds
+  // plurals for the "is this a real miss" check, so singularizing only the
+  // STORED value here is safe and doesn't change that check's behavior.
+  const subject = /^are$/i.test(verb) ? singularizeSurface(subjectRaw) : subjectRaw;
   // Point 2 (mint-extension): a PRIOR turn's minted term, or a
   // GENERIC_ANCHOR_NOUNS root, grounds Y just as legitimately as a static
   // lexicon noun — both are always treated as class-level (never property),
@@ -2157,14 +2184,14 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
   if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
     || (await isGroundedByFact(objectRaw, memoryDir))) {
     return teachFact(memoryDir, sessionId, {
-      subject: subjectRaw, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
+      subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
     });
   }
   if (lookupAdjective(lex, objectRaw)) {
     // property assertions are about ONE specific entity — never a quantifier,
     // even when phrased with "every" (point 3).
     return teachFact(memoryDir, sessionId, {
-      subject: subjectRaw, predicate: HAS_PROPERTY_PREDICATE, object: objectRaw,
+      subject, predicate: HAS_PROPERTY_PREDICATE, object: objectRaw,
     });
   }
   return null; // Y unknown too — decline honestly, never guess
@@ -2245,9 +2272,9 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
-  const [, det, subjectRaw, objectRaw] = m;
+  const [, det, subjectRaw, verb, objectRaw] = m;
   if (!/^(?:every|each|all)$/i.test((det || "").trim())) return null; // class-level mint needs a real universal quantifier
-  const { loadLexicon } = await import("./grammar/lexicon.mjs");
+  const { loadLexicon, lookupNoun } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   const subjectGrounded = await isGroundedTerm(subjectRaw, lex, memoryDir);
   if (!subjectGrounded) return null; // ungrounded subject isn't this fallback's asymmetry — never a guessed mint
@@ -2255,8 +2282,32 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
   if (objectGrounded) return null; // object already known — nothing to mint
   if (await objectReadsAsNonNoun(objectRaw)) return null; // reads like an adjective/verb, not a class noun — defer to unknownAdjectiveFallback
   const quantifier = /^every$/i.test((det || "").trim()) ? "every" : "";
+  // Singularize the SUBJECT before storage, ONLY on a genuinely PLURAL
+  // phrasing (verb "are") — same bug class and same "is"-vs-"are" safety gate
+  // as unknownSubjectFallback, above (see UNKNOWN_SUBJECT_RE's own docblock).
+  // This is the fallback the canonical "all men are mortal" sentence
+  // ACTUALLY goes through: "men" is grounded here via classify's own
+  // IRREGULAR plural-fold (lexicon-core.json declares "man"/plural "men"), so
+  // unknownSubjectFallback itself already declines for it (its own
+  // classify(subjectRaw) check reads "men" as the known noun "man") and hands
+  // off to this mirror fallback instead. A naive suffix-strip
+  // (singularizeSurface — SOME_A_FEW_RE's own tool, reused as the fallback for
+  // a genuinely novel REGULAR plural not in the lexicon, e.g. "zorps") can't
+  // undo an IRREGULAR plural like "men" -> "man" — only the lexicon's own
+  // noun table (lookupNoun, already resolved by isGroundedTerm/classify to
+  // decide this subject counts as grounded in the first place) carries that
+  // mapping, so storage must consult the SAME source of truth: prefer the
+  // lexicon lemma, falling back to singularizeSurface for a subject grounded
+  // only via a PRIOR taught fact (isGroundedByFact) or a regular-plural
+  // lexicon fold. Gated on verb "are" for the identical reason
+  // unknownSubjectFallback gates it: an already-singular grounded subject
+  // that happens to end in "s" (e.g. a fact-grounded "gas") must never be
+  // naively stripped on an "is" sentence ("every gas is a chemical").
+  const subject = /^are$/i.test(verb)
+    ? (lookupNoun(lex, subjectRaw)?.lemma || singularizeSurface(subjectRaw))
+    : subjectRaw;
   return teachFact(memoryDir, sessionId, {
-    subject: subjectRaw, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
+    subject, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
   });
 }
 
@@ -2323,7 +2374,7 @@ async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
   if (!m) return null;
-  const [, , subjectRaw, objectRaw] = m;
+  const [, , subjectRaw, , objectRaw] = m;
   const { loadLexicon, lookupNoun, classify } = await import("./grammar/lexicon.mjs");
   const lex = lexicon || loadLexicon();
   // Y already a known NOUN or a fact-grounded CLASS term — a genuine class-
@@ -4879,6 +4930,34 @@ const HAS_METHOD_OPEN_RE = /^what\s+methods\s+does\s+([\w'-]+)\s+have[?.!\s]*$/i
  *  cascade/orientation nudge that already handles it. */
 const IS_ADJECTIVE_YESNO_RE = /^(?:is|are|was|were)\s+(.+?)\s+([A-Za-z][\w-]*)[?.!\s]*$/i;
 const IS_ADJECTIVE_PRONOUN_RE = /^(?:it|this|that)$/i;
+/** BENCHMARK_CONVERSATION_1.8.14.md persona-sweep (2026-07-12), highest cross-
+ *  persona signal in the run (4 independent personas): IS_ADJECTIVE_YESNO_RE's
+ *  subject capture is unbounded/unrestricted (see its own docblock above), so
+ *  a pronoun-subject IDENTITY question ("are you happy", "are you like
+ *  chatgpt", "are you secretly ChatGPT or GPT-4") backtracks the pronoun
+ *  itself (plus any trailing filler word up to the last token) into the
+ *  SUBJECT capture — factReadBack then treats "you"/"you like"/"you secretly
+ *  chatgpt or" as a literal fact subject and offers to teach a fact ABOUT the
+ *  pronoun ("remember that you is happy"), exactly the grammatical category
+ *  error TEACH_PRONOUN_RE (above, chat.mjs:2648) was already built to reject
+ *  on the teach-lane side. Same pronoun set (you|i|they|he|she|we) reused
+ *  here, checked at the START of the subject capture only (not anchored to
+ *  the whole capture — a pronoun subject can carry trailing words, "you
+ *  like"/"you secretly … or", the same way TEACH_PRONOUN_RE's own `\s+\S+`
+ *  tail allows). "it" is deliberately EXCLUDED from this set, unlike
+ *  TEACH_PRONOUN_RE — IS_ADJECTIVE_PRONOUN_RE (just above) already gives "it"
+ *  its own correct, wanted behavior (anaphoric resolution against the
+ *  session's current FOCUS, "is it deprecated" → resolves off focusLabel),
+ *  which this guard must not shadow. Every call site below is expected to
+ *  test rawSubject (post-trim, pre-lowercasing) against this BEFORE treating
+ *  the match as a fact-subject candidate, and to fall through (never offer
+ *  unknownAdjectiveOffer, never attempt a fact lookup) on a hit — the same
+ *  "decline, don't misroute" discipline the rest of this reader already
+ *  follows for an honest miss, letting the query continue to whatever
+ *  handles identity/small-talk questions (isConversational's IDENTITY_PHRASES/
+ *  AI_IDENTITY_PHRASES/FEELINGS_PHRASES closed sets, or its own ≤3-word
+ *  catch-all) instead. */
+const IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE = /^(?:you|i|they|he|she|we)\b/i;
 /** The TEACH-OFFER for a subject IS_ADJECTIVE_YESNO_RE resolved but has no
  *  fact about at all (Tier-5 playtest, cycle 2) — the offered "remember that
  *  X is Y" phrasing is verified in-state: TEACH_PROPERTY_RE's own subject
@@ -5050,7 +5129,17 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
         // already stood; "is the checkout flow deprecated" (this branch's own
         // ORIGINAL T8 target — "deprecated" has no structural meaning at all)
         // has no envelope.parsed to defer to, so it is untouched.
-        if (subject && !/^there\b/i.test(subject) && !envelope?.parsed) {
+        // Pronoun-subject guard (BENCHMARK_CONVERSATION_1.8.14.md persona-sweep,
+        // 2026-07-12) — see IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE's own docblock
+        // above IS_ADJECTIVE_YESNO_RE: "are you happy"/"are you like chatgpt"
+        // backtrack a pronoun subject in here exactly like any other adjective
+        // subject, so without this check unknownAdjectiveOffer would wrongly
+        // offer to teach a fact about the literal pronoun. Checked on rawSubject
+        // (before the IS_ADJECTIVE_PRONOUN_RE focus-resolution swap above, which
+        // only ever fires for "it"/"this"/"that" — never a personal pronoun like
+        // "you", so `subject` itself would already carry the pronoun verbatim).
+        if (subject && !/^there\b/i.test(subject) && !envelope?.parsed
+          && !IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE.test(rawSubject)) {
           return unknownAdjectiveOffer(subject, emptyIsAdj[2].trim().toLowerCase());
         }
       }
@@ -5816,7 +5905,18 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
   const isAdj = qHedge.match(IS_ADJECTIVE_YESNO_RE);
   if (isAdj) {
     const rawSubject = isAdj[1].trim();
-    const subject = IS_ADJECTIVE_PRONOUN_RE.test(rawSubject) ? (focusLabel || null) : rawSubject;
+    // Pronoun-subject guard (BENCHMARK_CONVERSATION_1.8.14.md persona-sweep,
+    // 2026-07-12) — see IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE's own docblock
+    // above IS_ADJECTIVE_YESNO_RE: "are you happy"/"are you like chatgpt"/
+    // "are you secretly ChatGPT or GPT-4" backtrack a personal-pronoun
+    // subject in here just like any other adjective subject. Forcing
+    // `subject` to null (the SAME "nothing to resolve" shape a bare "it"/
+    // "this"/"that" with no standing focus already produces just below) lets
+    // this whole reader decline HONESTLY — no fact lookup, no teach-offer —
+    // and fall through to whatever handles identity/small-talk questions
+    // instead, rather than special-casing a return here.
+    const subject = IS_ADJECTIVE_YESNO_PRONOUN_SUBJECT_RE.test(rawSubject) ? null
+      : IS_ADJECTIVE_PRONOUN_RE.test(rawSubject) ? (focusLabel || null) : rawSubject;
     const adjective = isAdj[2].trim().toLowerCase();
     if (subject) {
       const subjVariants = factTermVariants(normFactTerm, subject);
@@ -5867,6 +5967,33 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
           replace: true,
         };
       }
+      // No property hit — but a bare "is X Y" (no article) is exactly the
+      // same claim as "is X a Y" would have been had the user included the
+      // article (ISA_ASK_RE's own territory, above): SKILL_BENCHMARK_CONVERSATION.md's
+      // canonical syllogism ("john is a man" / "all men are mortal" / "is
+      // john mortal") is asked this bare way, and "mortal" was taught as a
+      // CLASS (rdfs:subClassOf), not a property — so it can only ever be
+      // found by the SAME 2-hop TAUGHT-only findIsaChain proof-chase isaAsk
+      // uses above, never by propertyMatch. Tried here as an ADDITIONAL
+      // attempt, never a replacement: on no chain either, this falls through
+      // to the ordinary property-miss handling just below, unchanged.
+      {
+        const { findIsaChain: chaseAdj, SUBCLASS_PREDICATE: SC_PREDICATE_ADJ, TYPE_PREDICATE: TYPE_PREDICATE_ADJ } = await import("./syllogise.mjs");
+        const isTaughtAdj = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+        const chainSubClassRowsAdj = rows.filter((f) => f.predicate === SC_PREDICATE_ADJ && isTaughtAdj(f));
+        const chainTypeRowsAdj = rows.filter((f) => f.predicate === TYPE_PREDICATE_ADJ && isTaughtAdj(f));
+        const chainSubClassEdgesAdj = chainSubClassRowsAdj.map((f) => [f.subject, f.object]);
+        const chainTypeEdgesAdj = chainTypeRowsAdj.map((f) => [f.subject, f.object]);
+        const factForStepAdj = (step) => (step.predicate === SC_PREDICATE_ADJ ? chainSubClassRowsAdj : chainTypeRowsAdj)
+          .find((f) => f.subject === step.subject && f.object === step.object);
+        const adjObjVariants = factTermVariants(normFactTerm, adjective);
+        for (const subj of subjVariants) {
+          const chain = chaseAdj(subj, adjObjVariants, chainTypeEdgesAdj, chainSubClassEdgesAdj, { maxHops: 2 });
+          if (!chain) continue;
+          const premises = chain.map(factForStepAdj);
+          if (premises.every(Boolean)) return { text: `yes — ${renderIsaChain(premises)}`, replace: true };
+        }
+      }
       // no hit on THIS property — never a guessed "no" (see
       // IS_ADJECTIVE_YESNO_RE's own docblock for why this stays silent on a
       // truth claim, unlike its ownership/general-verb siblings above). But a