@polycode-projects/the-mechanical-code-talker 1.8.18 → 1.9.0

package/src/chat.mjs

@@ -4044,6 +4044,11 @@ const FACT_PREDICATE_PHRASES = {
   "mgx:hasLastSubevent": "ends with",
   "mgx:hasPrerequisite": "requires",
   "mgx:ownedBy": "is owned by", // the teach lane's ownership frame ("Priya owns tasks.mjs")
+  "mgx:synonym": "means the same as",
+  "mgx:antonym": "is the opposite of",
+  "mgx:similarTo": "is similar to",
+  "mgx:relatedTo": "is related to",
+  "mgx:symbolOf": "is a symbol of",
 };
 
 /** Bug 3 (2026-07-09) point 3b: the MECHANICAL fallback for a predicate this
@@ -4138,16 +4143,26 @@ function splitMetaPredicate(term) {
 
 /** One rendered fact line. An OPERATOR-asserted fact keeps the true first-person
  *  provenance ("you told me: …"). A CORPUS fact is presented as clean DATA with its
- *  source cited — NEVER "i learned: …", which over-claims and anthropomorphises
- *  (especially when the corpus row is noise); the relation and its provenance speak
- *  for themselves. Provenance stays VERBATIM either way. */
+ *  source cited, not "i learned: …" — that phrase over-claims and anthropomorphises
+ *  a first-person experience the bot never had; the relation and its provenance
+ *  speak for themselves. A WEAK-corpus fact (memory/trust.mjs SOURCE_PRIOR.corpusWeak
+ *  — real data, low-precision relation, e.g. ConceptNet's undirected /r/RelatedTo)
+ *  still isn't "i learned" (same anthropomorphism problem), but reads identically to
+ *  a solid corpus fact loses the only reader-visible signal that it's lower-
+ *  confidence — re-examined 2026-07-12 (TOO_HARD_AUDIT.md): the prior blanket "corpus
+ *  never hedges" rule predates corpus data having any confidence spread at all, so a
+ *  distinct, honest hedge ("possibly: …") applies here instead of either extreme.
+ *  Provenance stays VERBATIM in every case. */
 function renderFactLine(f) {
   const cite = f.provenance ? ` (source: ${f.provenance})` : "";
   // ace:chat = the ACE-parsed operator assert; teach:chat = the teach lane's
   // natural frames — both are things the operator SAID, so both read first-person.
   if (f.provenance.includes("ace:chat") || f.provenance.includes("teach:chat")) return `you told me: ${factPhrase(f)}${cite}`;
-  // CORPUS facts are background DATA — present the relation plainly, cited to its
-  // source, NEVER "i learned: …" (the footgun: a first-person claim over corpus noise).
+  // WEAK corpus facts (lower trust, e.g. RelatedTo) — real, cited, but hedged as
+  // uncertain rather than either flatly stated or falsely claimed as "learned".
+  if (f.provenance.includes("corpus-weak:")) return `possibly: ${factPhrase(f)}${cite}`;
+  // SOLID corpus facts are background DATA — present the relation plainly, cited
+  // to its source, never "i learned: …" (a first-person claim over corpus data).
   if (f.provenance.includes("corpus:")) return `${factPhrase(f)}${cite}`;
   return `i learned: ${factPhrase(f)}${cite}`;
 }
@@ -4501,6 +4516,49 @@ const FACT_ANSWER_CAP = 32;
 const CAN_ASK_RE = /^(?:can|could)\s+(?:an?\s+)?([\w'-]+(?:\s+[\w'-]+)*?)\s+([a-z]+)[?.!\s]*$/i;
 const WHAT_CAN_DO_RE = /^what\s+can\s+(?:an?\s+)?(.+?)\s+do[?.!\s]*$/i;
 const WHAT_HAS_RE = /^what\s+has\s+(?:an?\s+)?(.+?)[?.!\s]*$/i;
+// "what is used for riding" / "what can be used for riding" / "what is for
+// riding" — the reverse-by-object mirror of BUG 1's forward reader ("what is
+// a tree used for"), missing until now: BUG 1 only ever filtered a KNOWN
+// subject's facts down to mgx:usedFor; nothing answered the reverse question
+// (object known, subject unknown), so it fell all the way through to the
+// code-graph miss cascade — actively misleading for a pure vocabulary query.
+const WHAT_USED_FOR_RE = /^what\s+(?:(?:can\s+be|is)\s+used\s+for|is\s+for)\s+(.+?)[?.!\s]*$/i;
+
+// Live-caught 2026-07-12 follow-up: the SAME gap as mgx:usedFor above turned
+// out to be systemic, not one-off — "what causes fire", "what is made of
+// wood", "what is found in a kitchen", "what wants food" all fell through to
+// the same misleading code-graph miss, for the same reason (no reverse-by-
+// object reader existed for these predicates either). Rather than hand-roll
+// one more one-off regex per predicate, this DERIVES a reverse-by-object
+// regex for every FACT_PREDICATE_PHRASES entry that's safe to reverse — the
+// same "derivation, not a curated subset" philosophy TRAILING_PREDICATE_MARKERS
+// already uses for the forward direction (see that const's own docblock).
+// Excluded, each for a specific reason:
+//   - rdfs:subClassOf, mgx:hasA, mgx:capableOf, mgx:usedFor — already have
+//     their own dedicated, richer reverse readers (WHAT_INHERITS_RE/
+//     WHAT_HAS_RE/WHAT_CAN_DO_RE/WHAT_USED_FOR_RE above).
+//   - mgx:ownedBy — already has its own dedicated "who owns X" reader
+//     (WHO_OWNS_RE) — a WHO question, not a WHAT question, so it would never
+//     collide, but is excluded anyway to keep exactly one reader per relation.
+//   - rdf:type ("is a") and mgx:hasProperty ("is") — too short/generic to
+//     safely anchor a reverse question: "what is X" already belongs to the
+//     meta lane's own vocabulary lookup, and reversing it here would mean
+//     guessing whether the user meant "define X" or "what has property X"
+//     from word order alone.
+//   - owl:disjointWith ("is not a") and mgx:receivesAction ("can be") — both
+//     broad enough that "what is not a X" / "what can be X" read as much more
+//     likely to be a different question shape than a genuine reverse lookup.
+const REVERSE_PREDICATE_EXCLUDE = new Set([
+  "rdfs:subClassOf", "rdf:type", "mgx:hasA", "mgx:capableOf", "mgx:usedFor",
+  "mgx:ownedBy", "owl:disjointWith", "mgx:hasProperty", "mgx:receivesAction",
+]);
+const REVERSE_PREDICATE_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
+  .filter(([predicate]) => !REVERSE_PREDICATE_EXCLUDE.has(predicate))
+  .map(([predicate, phrase]) => ({
+    predicate,
+    re: new RegExp(`^what\\s+${escapeRegex(phrase)}\\s+(.+?)[?.!\\s]*$`, "i"),
+  }))
+  .sort((a, b) => b.re.source.length - a.re.source.length); // longest phrase first
 // Widened 2026-07-11 (live-caught follow-up to the ambiguousParse fix, commit
 // 5c858bf): on the FIRST turn of a graph-less session, dispatchTool's
 // loadGraph() throws its own documented "the graph is empty... this repo
@@ -4542,12 +4600,69 @@ function uniqueFacts(rows) {
 /** W4 seam: answer (or extend) a vocabulary/definition question from the MEMORY
  *  graph's Facts. Returns { text, replace } — `replace:false` means the engine's
  *  own (schema-docs) answer stands and the fact lines are appended under it —
- *  or null when memory holds nothing relevant (misses stay unchanged). */
-async function factAnswer(memoryDir, query, envelope, miss, biasByBundle = {}) {
+ *  or null when memory holds nothing relevant (misses stay unchanged).
+ *  Exported (PLAN_VIZ_MEMORY.md Bug 1 fix) so src/memory-ask-browser-entry.mjs
+ *  can re-export it for `tmct viz`'s embedded "Ask the graph" panel — the ONLY
+ *  reason this is `export` rather than module-private; the function's own
+ *  behavior is unchanged (same signature, same logic, answers identically in
+ *  the CLI and the browser bundle). `memoryDir` may be memory/core.mjs's
+ *  Backend-B in-memory handle (`createInMemoryStore()`) as well as a real repo
+ *  path — every I/O this function does routes through `loadMemory(memoryDir)`
+ *  (via factRows/memoryFacts below), and loadMemory's own Backend-B branch
+ *  returns the handle's `payload` directly with ZERO fs calls — so a caller
+ *  that hands this a handle already carrying the embedded page's full graph
+ *  gets a pure, disk-free traversal, no bundle-time module shimming needed. */
+export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle = {}) {
   let normFactTerm;
   try { ({ normFactTerm } = await import("./memory/core.mjs")); } catch { return null; }
   const q = String(query).trim();
 
+  // (a-pre) "what is used for riding" / "what can be used for riding" / "what
+  // is for riding" — the reverse-by-OBJECT mirror of BUG 1's forward reader
+  // ("what is a tree used for", the (a) block just below). Checked BEFORE (a)
+  // deliberately: this phrasing's leading "what is …" ALSO matches (a)'s own
+  // BARE_WHATIS_RE, which would otherwise greedily treat "used for riding" as
+  // one literal term to define — a guaranteed miss, since no vocabulary term
+  // is ever named "used for riding" — and (a) always returns (hit, honest
+  // per-relation "no", or null), never falling through to a later reader. Only
+  // takes over when it finds a REAL hit; a non-match or zero-hit case falls
+  // through unchanged to (a) and beyond, so ordinary miss messaging is
+  // untouched. mgx:usedFor instead of mgx:hasA; same filter/rank/render/
+  // paginate recipe as (b4)'s WHAT_HAS_RE below.
+  const usedForQ = q.match(WHAT_USED_FOR_RE);
+  if (usedForQ) {
+    const variants = factTermVariants(normFactTerm, usedForQ[1]);
+    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === "mgx:usedFor" && variants.has(f.object));
+    if (hits.length) {
+      const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
+      const lines = ranked.map(renderFactLine);
+      const shown = lines.slice(0, FACT_ANSWER_CAP);
+      const rest = lines.slice(FACT_ANSWER_CAP);
+      const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+      return { text: shown.join("\n") + extra, replace: true, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
+    }
+  }
+
+  // (a-pre2) The generic derived cascade for every other reversible predicate
+  // (REVERSE_PREDICATE_MARKERS, see its own docblock for the exclusion list
+  // and why). Same checked-before-the-meta-lane placement and same
+  // only-take-over-on-a-real-hit discipline as (a-pre) just above — a phrase
+  // like "is found in"/"is made of" also starts with "what is …", so it must
+  // run before (a) can greedily claim the whole tail as a literal term.
+  for (const { predicate, re } of REVERSE_PREDICATE_MARKERS) {
+    const m = q.match(re);
+    if (!m) continue;
+    const variants = factTermVariants(normFactTerm, m[1]);
+    const hits = (await factRows(memoryDir)).filter((f) => f.predicate === predicate && variants.has(f.object));
+    if (!hits.length) continue; // try the next candidate marker, don't give up yet
+    const ranked = rankByBiasThenTrust(uniqueFacts(hits), biasByBundle);
+    const lines = ranked.map(renderFactLine);
+    const shown = lines.slice(0, FACT_ANSWER_CAP);
+    const rest = lines.slice(FACT_ANSWER_CAP);
+    const extra = rest.length ? `\n…and ${rest.length} more — say 'more' to see them.` : "";
+    return { text: shown.join("\n") + extra, replace: true, ...(rest.length ? { pending: { items: rest, noun: "facts" } } : {}) };
+  }
+
   // (a) meta-shaped questions ("what is a module", "what does cache mean") — the
   // parsed object term, matched against fact SUBJECTS; consulted for hits (append
   // alongside the schema-docs answer) and misses (facts answer alone) alike.
@@ -7817,8 +7932,22 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
   // further down is UNCHANGED, so a CamelCase term with no real hit still falls
   // through to its existing miss handling, never the generic orientation card.
   const isBareCamelCaseWhatisCandidate = conversationalCandidateBaseGate && isBareCamelCaseMetaQuestion(gateQuery);
+  // 2026-07-12 follow-up to the used-for/reverse-predicate fix (factAnswer's
+  // WHAT_USED_FOR_RE/REVERSE_PREDICATE_MARKERS, above): the SAME race BUG 2/
+  // Tier-5/CamelCase already fixed above hits these too, and for the shortest
+  // members of the family it's actually MORE likely to fire — "what wants
+  // happiness" is exactly 3 words, none of them in STRUCT_WORDS, so
+  // isConversational() claims it before factAnswer ever gets a turn, even
+  // though a real mgx:desires fact answers it correctly once reached (proven:
+  // the longer "what can be used for riding" already worked, since 5 words
+  // clears isConversational's <=3-word gate outright — only the short
+  // members of this family were ever actually broken). Same discipline as
+  // every sibling exemption on this gate: matching the shape alone changes
+  // nothing by itself, factAnswer below still only diverts on a REAL hit.
+  const reversePredicateShape = WHAT_USED_FOR_RE.test(gateQuery)
+    || REVERSE_PREDICATE_MARKERS.some(({ re }) => re.test(gateQuery));
   let bareMetaHit = null;
-  if ((isConversationalCandidate || isBareCamelCaseWhatisCandidate) && (bareWhatisShape || isAdjectiveShape)) {
+  if ((isConversationalCandidate || isBareCamelCaseWhatisCandidate) && (bareWhatisShape || isAdjectiveShape || reversePredicateShape)) {
     if (memoryDir) {
       bareMetaHit = (await factAnswer(memoryDir, gateQuery, envelope, miss, biasByBundle))
         ?? (await factReadBack(memoryDir, gateQuery, envelope, miss, graph, newFocus?.label, biasByBundle));
@@ -9142,9 +9271,11 @@ export async function createSession({
   // module-global state). "sqlite" selects Backend C (createSqliteMemoryStore
   // — a live node:sqlite connection kept open for the session's lifetime,
   // lazily imported only when this is actually chosen). TMCT_MEMORY_BACKEND
-  // mirrors the TMCT_EPHEMERAL/TMCT_NARRATE on/off env convention. No CLI flag
-  // wires this yet (bin/tmct.mjs's flag parsing is out of this change's
-  // scope) — a library/test caller sets the option directly for now.
+  // mirrors the TMCT_EPHEMERAL/TMCT_NARRATE on/off env convention. This
+  // parameter IS `bin/tmct.mjs`'s `tmct chat --memory-backend <...>` CLI flag
+  // (a library/test caller can still set it directly) — the full precedence
+  // (this param > TMCT_MEMORY_BACKEND env > tmct.toml's `[memory] backend` >
+  // "default") is resolved below, once `toml` is known.
   memoryBackend = null,
 } = {}) {
   // EPHEMERAL mode (--ephemeral, or TMCT_EPHEMERAL=1): read the target graph but
@@ -9185,6 +9316,13 @@ export async function createSession({
   // instead of the whole repo.
   let repo;
   let config;
+  // tmct.toml's normalized knobs (src/toml-config.mjs), captured alongside
+  // `config` in whichever branch below resolves the graph path — used further
+  // down for the memory-backend precedence (`toml.memory.backend`), so that
+  // knob is honoured the same way regardless of which graph-resolution tier
+  // fired. `null` when no branch could read a tmct.toml (never fatal — the
+  // backend precedence below just skips this tier).
+  let toml = null;
   const explicitGraphs = (graphPaths || []).filter(Boolean);
   if (explicitGraphs.length) {
     repo = repoPath || gitRoot(cwd) || cwd;
@@ -9192,6 +9330,11 @@ export async function createSession({
     config = resolvedGraphs.length > 1
       ? { graphFile: resolvedGraphs[0], graphFiles: resolvedGraphs }
       : { graphFile: resolvedGraphs[0] };
+    try {
+      const argv = ["--repo", repo];
+      if (configPath) argv.push("--config", configPath);
+      ({ toml } = await resolveRuntimeConfig({ argv, cwd, env: {}, gitRoot }));
+    } catch { toml = null; }
   } else if (repoPath) {
     repo = repoPath;
     // env is deliberately withheld from resolveRuntimeConfig here (passed as
@@ -9202,17 +9345,22 @@ export async function createSession({
     // honored too.
     const argv = ["--repo", repoPath];
     if (configPath) argv.push("--config", configPath);
-    ({ config } = await resolveRuntimeConfig({ argv, cwd, env: {}, gitRoot }));
+    ({ config, toml } = await resolveRuntimeConfig({ argv, cwd, env: {}, gitRoot }));
   } else {
     const root = gitRoot(cwd);
     repo = root || cwd;
     const envGraph = env.TMCT_GRAPH_FILE && String(env.TMCT_GRAPH_FILE).trim();
     if (envGraph) {
       config = loadConfig(env, cwd);
+      try {
+        const argv = [];
+        if (configPath) argv.push("--config", configPath);
+        ({ toml } = await resolveRuntimeConfig({ argv, cwd, env: {}, gitRoot }));
+      } catch { toml = null; }
     } else {
       const argv = [];
       if (configPath) argv.push("--config", configPath);
-      ({ config } = await resolveRuntimeConfig({ argv, cwd, env, gitRoot }));
+      ({ config, toml } = await resolveRuntimeConfig({ argv, cwd, env, gitRoot }));
     }
   }
 
@@ -9297,20 +9445,22 @@ export async function createSession({
   // `closeMemoryStore` is a no-op unless Backend C actually opened a
   // connection (Backend C's node:sqlite import is lazy — it only happens if
   // this branch is actually taken).
-  const backendChoice = String(memoryBackend || env.TMCT_MEMORY_BACKEND || "").trim().toLowerCase();
-  let memoryDir = repo;
-  let closeMemoryStore = async () => {};
-  if (backendChoice === "memory") {
-    const { createInMemoryStore } = await import("./memory/core.mjs");
-    memoryDir = createInMemoryStore();
-  } else if (backendChoice === "sqlite") {
-    const { createSqliteMemoryStore, closeSqliteMemoryStore } = await import("./memory/core.mjs");
-    const dbPath = join(repo, ".tmct", "memory", "graph.sqlite");
-    await mkdir(dirname(dbPath), { recursive: true });
-    const handle = await createSqliteMemoryStore(dbPath);
-    memoryDir = handle;
-    closeMemoryStore = async () => closeSqliteMemoryStore(handle);
-  }
+  //
+  // Precedence — CLI flag > env > tmct.toml > default — matches the graph-path
+  // precedence documented above: `memoryBackend` here is `tmct chat
+  // --memory-backend <...>`'s already-resolved value; TMCT_MEMORY_BACKEND is
+  // the env tier; `toml.memory.backend` is tmct.toml's `[memory] backend`
+  // (src/toml-config.mjs). A toml value of "default" (or anything unrecognized)
+  // falls through to Backend A below, same as an absent value always has.
+  const backendChoice = String(memoryBackend || env.TMCT_MEMORY_BACKEND || toml?.memory?.backend || "").trim().toLowerCase();
+  // openMemoryBackend (memory/core.mjs) is the ONE shared resolver for this
+  // seam — src/init.mjs's corpus seed and bin/tmct.mjs's --corpus/--ontology/
+  // --lexicon activation now call the exact same function, so a repo's
+  // seeded facts and its chat-taught facts always land in the same backend
+  // (a split-brain bug found in review: init used to always seed Backend A
+  // regardless of the configured backend).
+  const { openMemoryBackend } = await import("./memory/core.mjs");
+  const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(repo, backendChoice);
 
   const empty = graph.individuals.length === 0;
   // W3: FIRST RUN in a graph-less repo seeds a capped ConceptNet slice into

package/src/cli-args.mjs

@@ -5,10 +5,14 @@
 // precedence chain — built on top of toml-config.mjs's already-tested
 // mergeEffective/normalizeConfig (arg > toml > default), not a rebuild of it.
 //
-// Three tiny flag helpers (pure, no I/O) plus the one async resolver:
+// Four tiny flag helpers (pure, no I/O) plus the one async resolver:
 //   strFlag(rest, names, dflt)   → single value, last flag occurrence wins
 //   repeatedFlag(rest, names)    → every value for a repeatable flag (e.g. --graph)
 //   boolFlag(rest, names)        → true if any of `names` appears at all
+//   enumFlag(rest, names, choices) → strFlag, validated against a closed set
+//     (throws a clear error naming the flag + the choices — the shared shape
+//     for a closed-choice option like `--memory-backend default|memory|sqlite`,
+//     matching `--with-persona`'s own "unknown name" error style)
 //   resolveRuntimeConfig({argv, cwd, env, gitRoot}) → the resolved repo/config
 //
 // Graph-path precedence (documented once, here — every subcommand shares it):
@@ -69,6 +73,21 @@ export function boolFlag(rest, names) {
   return rest.some((r) => list.includes(r));
 }
 
+/** Closed-choice single-value flag: `strFlag` plus validation against
+ *  `choices`. Returns `undefined` when absent (never a default — the caller
+ *  decides what "absent" means, same as an omitted `strFlag` call). Throws a
+ *  clear, user-facing error naming the flag and the valid choices when a
+ *  value IS given but isn't one of them — validate-before-any-disk-write,
+ *  the same discipline `tmct init --with-persona <unknown>` already uses. */
+export function enumFlag(rest, names, choices) {
+  const val = strFlag(rest, names, undefined);
+  if (val !== undefined && !choices.includes(val)) {
+    const flagName = asList(names)[0];
+    throw new Error(`invalid ${flagName} "${val}". Choices: ${choices.join(", ")}.`);
+  }
+  return val;
+}
+
 /**
  * Resolve one subcommand invocation's repo root, tmct.toml, and graph
  * path(s) — the shared precedence chain every subcommand (chat/memory/init/