@polycode-projects/the-mechanical-code-talker 0.8.1 → 0.9.0

package/src/codegraph.mjs

@@ -1173,7 +1173,13 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
  *  mechanical NL-query engine (PLAN_MECHANICAL_CHAT.md) to orchestrate rather than duplicate. */
 export function edgesOfKind(graph, kind) {
   const out = [];
-  for (const g of graph.relations) if (relationKind(g) === kind) out.push(...g.edges);
+  // Plain-loop append, NOT out.push(...g.edges): argument spread materialises every
+  // element as a call argument and overflows the stack past ~100k edges (live report:
+  // 27,770-module repo, "list modules in <dir>" → "Maximum call stack size exceeded").
+  for (const g of graph.relations) {
+    if (relationKind(g) !== kind) continue;
+    for (const e of g.edges) out.push(e);
+  }
   return out;
 }
 
@@ -1517,6 +1523,108 @@ export function renderClassHistory(graph, ind) {
   return renderSymbolHistory(graph, ind);
 }
 
+// ---- author identity (0.8.2 WS4): the Commit "author" attribute answered as a
+//      person — "who is <Name>", "what did <Name> touch". Author is an ATTRIBUTE
+//      (key "author"/mgx:commitAuthor), never an individual, so these read the
+//      attribute off every Commit and aggregate. All renderers return null on an
+//      unknown name — the chat lane falls through to the ordinary honest miss. ----
+
+const AUTHOR_TOUCH_CAP = 15;
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** Map of lowercased author name → that author's Commit individuals (payload order).
+ *  Tolerates both attribute-key conventions (author / commitAuthor), like commitLine. */
+export function authorIndex(graph) {
+  const idx = new Map();
+  for (const ind of graph?.individuals || []) {
+    if ((ind.class || "") !== "Commit") continue;
+    const author = String(attrVal(ind, "author") || attrVal(ind, "commitAuthor")).trim();
+    if (!author) continue;
+    const key = author.toLowerCase();
+    if (!idx.has(key)) idx.set(key, []);
+    idx.get(key).push(ind);
+  }
+  return idx;
+}
+
+/** "May–Jun 2026"-style range over the commits' date attributes ("" when undated). */
+function commitDateRange(commits) {
+  const dates = commits
+    .map((c) => new Date(attrVal(c, "date") || attrVal(c, "commitDate")))
+    .filter((d) => !Number.isNaN(d.getTime()))
+    .sort((a, b) => a - b);
+  if (!dates.length) return "";
+  const fmt = (d) => `${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+  const lo = fmt(dates[0]);
+  const hi = fmt(dates[dates.length - 1]);
+  if (lo === hi) return lo;
+  if (dates[0].getUTCFullYear() === dates[dates.length - 1].getUTCFullYear()) {
+    return `${MONTHS[dates[0].getUTCMonth()]}–${hi}`;
+  }
+  return `${lo}–${hi}`;
+}
+
+/** The deduped labels of everything an author's commits touched (touches +
+ *  touchesSymbol edge OBJECTS), in edge order. [] on an unknown author. */
+function authorTouchedLabels(graph, commits) {
+  const ids = new Set(commits.map((c) => c.id));
+  const labels = [];
+  const seen = new Set();
+  for (const kind of ["touches", "touchesSymbol"]) {
+    for (const e of edgesOfKind(graph, kind)) {
+      if (!ids.has(e.subject)) continue;
+      const label = e.objectLabel || graph.byId?.get?.(e.object)?.label || e.object;
+      if (seen.has(label)) continue;
+      seen.add(label);
+      labels.push(label);
+    }
+  }
+  return labels;
+}
+
+/** Identity card for an author name — "Grace Hopper — 2 commits in this index
+ *  (May–Jun 2026), touching: <labels, capped>". Null on an unknown name. */
+export function renderAuthorCard(graph, name) {
+  const commits = authorIndex(graph).get(String(name || "").trim().toLowerCase());
+  if (!commits?.length) return null;
+  const display = String(attrVal(commits[0], "author") || attrVal(commits[0], "commitAuthor")).trim();
+  const range = commitDateRange(commits);
+  const touched = authorTouchedLabels(graph, commits);
+  const touching = touched.length ? `, touching: ${capJoin(touched, AUTHOR_TOUCH_CAP)}` : "";
+  return `${display} — ${commits.length} commit${commits.length === 1 ? "" : "s"} in this index${range ? ` (${range})` : ""}${touching}.`;
+}
+
+/** What an author touched — the deduped entity list off her commits' touches/
+ *  touchesSymbol edges, capped like the other bounded renders. Null on an unknown
+ *  name; an honest "no touch edges" line when the commits carry none. */
+export function renderAuthorTouches(graph, name) {
+  const commits = authorIndex(graph).get(String(name || "").trim().toLowerCase());
+  if (!commits?.length) return null;
+  const display = String(attrVal(commits[0], "author") || attrVal(commits[0], "commitAuthor")).trim();
+  const touched = authorTouchedLabels(graph, commits);
+  if (!touched.length) return `${display}: ${commits.length} commit${commits.length === 1 ? "" : "s"} in this index, but no touch edges recorded for them.`;
+  return `${display} touched ${touched.length} entit${touched.length === 1 ? "y" : "ies"} across ${commits.length} commit${commits.length === 1 ? "" : "s"}:\n  ${capJoin(touched, AUTHOR_TOUCH_CAP, "\n  ")}`;
+}
+
+/** "authored by <author> (<date>)" for a commit named by sha (7-40 hex chars; the
+ *  graph label and the typed sha may each be a prefix of the other). Null when the
+ *  sha matches no commit or more than one — never a guess. */
+export function renderCommitAuthor(graph, sha) {
+  const s = String(sha || "").trim().toLowerCase();
+  if (!/^[0-9a-f]{7,40}$/.test(s)) return null;
+  const hits = (graph?.individuals || []).filter((i) => {
+    if ((i.class || "") !== "Commit") return false;
+    const label = String(i.label || "").toLowerCase();
+    return label.startsWith(s) || s.startsWith(label);
+  });
+  if (hits.length !== 1) return null;
+  const c = hits[0];
+  const author = String(attrVal(c, "author") || attrVal(c, "commitAuthor")).trim();
+  if (!author) return null;
+  const date = attrVal(c, "date") || attrVal(c, "commitDate");
+  return `${c.label}: authored by ${author}${date ? ` (${date})` : ""}.`;
+}
+
 // ---- symbol search (kind=function/class/method/attribute, with name/decorator filters)
 
 const SYMBOL_CLASSES = { function: "Function", class: "Class", method: "Method", attribute: "Attribute" };

package/src/grammar/lexicon-core.json

@@ -168,6 +168,13 @@
     "status": { "property": "data" },
     "language": { "property": "data" },
     "extension": { "property": "data" },
+    "churn": { "property": "data" },
+    "impact": { "property": "data" },
+    "complexity": { "property": "data" },
+    "latency": { "property": "data" },
+    "duration": { "property": "data" },
+    "frequency": { "property": "data" },
+    "severity": { "property": "data" },
     "owner": { "property": "object" },
     "maintainer": { "property": "object" },
     "author": { "property": "object" },

package/src/interpret/merge.mjs

@@ -25,7 +25,18 @@ const DEFAULT_CONFIDENCE = 0.5;
 // commit-sha tier strips the noun — the anchored strategy captures the noun inside
 // its object span while keyword-spot consumes it as the entity keyword, so without
 // this the two strategies would "disagree" over a word that names no different thing.
-const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ").replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");
+// A leading DETERMINER is the same kind of non-difference (0.8.2 feel wave): the
+// anchored grammar captures "the logger" while keyword-spot captures "logger", and
+// the resulting "ambiguity" asked the user to choose between identical readings.
+const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ")
+  .replace(/^(?:the|a|an)\s+/, "")
+  .replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");
+
+// Leading-determiner probe over a parse's term slots — the dedupe below keeps the
+// det-LESS twin so downstream term resolution sees the bare object ("logger",
+// never "the logger").
+const LEADING_DET_RE = /^\s*(?:the|a|an)\s+/i;
+const detCount = (p) => [p?.subject, p?.object].filter((t) => LEADING_DET_RE.test(String(t || ""))).length;
 
 /** Do two independently-produced parses mean the same graph query? Same
  *  shape, same relation kind, and matching term(s) (both subject and object
@@ -99,6 +110,10 @@ export function mergeStrategyResults(results) {
       if (dup) {
         dup.agreed += 1;
         dup.confidence = Math.max(dup.confidence, c.confidence);
+        // determiner-insensitive collapse: when the agreeing parses differ only
+        // by a leading determiner, the det-less reading's parse survives (the
+        // representative's strategy/confidence standing is unchanged).
+        if (detCount(c.parsed) < detCount(dup.parsed)) dup.parsed = c.parsed;
         continue;
       }
       distinct.push({ ...c, agreed: 1 });

package/src/interpret/normalize.mjs

@@ -13,7 +13,7 @@
 
 import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
-  NEGATION_FRAMES, COMMIT_CONTENT_FRAMES,
+  NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, VERB_TO_KIND,
 } from "../ask-vocab.mjs";
 
 export function escapeRegex(s) {
@@ -44,8 +44,219 @@ const correctionRe = (table) => new RegExp(
 const MISSPELLING_RE = correctionRe(MISSPELLINGS);
 const WRONG_WORD_RE = correctionRe(WRONG_WORDS);
 
+// ---- closed PREAMBLE frames (0.8.2 feel wave, PLAN_CHAT_FEEL item 2) — the
+// conversational wrapping a developer puts AROUND a real question: a greeting
+// lead-in with a delimiter ("hey there, quick question - …"), a thanks lead-in
+// with a delimiter ("thanks so much, …" — Bug B2, 0.8.2 follow-up), the modal
+// politeness wrapper ("can you … please"), and the show/give-me presentation
+// bridge. These are DELIMITER- and PHRASE-anchored, so they must run BEFORE the
+// FILLER-strip pass below: FILLER_WORDS strips "hey"/"can you" as bare words, so
+// after that pass the frames' anchors are gone while the punctuation debris
+// ("there, quick question -") still poisons the parse (the playtest wall).
+// Applied inside normalizeQuery — the one seam BOTH composition sites (ask.mjs
+// parseQuery and interpret/pipeline.mjs normalizeInput) run first — AFTER the
+// word-restoring correction tables (so "gimme"/"shwo me" are already "give me"/
+// "show me") and BEFORE the filler strip. Closed patterns, applied in order to a
+// small fixpoint; unmatched text passes through byte-unchanged. ----
+
+/** Any relation verb phrase from the shared vocabulary — the show/give-me
+ *  bridge's "this remainder is a real relation query" probe. */
+const RELATION_VERB_RE = new RegExp(
+  "\\b(?:" + Object.keys(VERB_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
+  "i",
+);
+/** A remainder that opens interrogatively is already a question — unwrap it. */
+const INTERROGATIVE_LEAD_RE = /^(?:which|what|who|whose|where|when|why|how)\b/i;
+/** A remainder that is a KIND listing ("show me [the] untested modules", "show
+ *  me the tests") already belongs to the compositional list/qualifier grammar,
+ *  whose LIST_TRIGGERS include "show me"/"give me" — leave the WHOLE text
+ *  untouched so that working path keeps it. Two shapes: a plural kind noun in
+ *  tail position, or a bare (det +) singular kind noun and nothing else. */
+const LISTING_TAIL_KINDS = new Set([
+  "modules", "files", "functions", "methods", "classes", "attributes", "fields",
+  "properties", "variables", "globals", "commits", "changes", "tests", "members",
+]);
+const BARE_KIND_RE = /^(?:all\s+|the\s+)?(?:module|file|function|method|class|attribute|field|property|variable|global|commit|change|test|member)\??$/i;
+const isListingRemainder = (rest) => {
+  if (BARE_KIND_RE.test(rest)) return true;
+  const words = rest.replace(/\?+\s*$/, "").trim().split(/\s+/);
+  return LISTING_TAIL_KINDS.has((words[words.length - 1] || "").toLowerCase());
+};
+
+/** Greeting lead-in with a delimiter (+ optional "quick question" bridge):
+ *  "hey there, quick question - <Q>" -> "<Q>". The delimiter and the non-empty
+ *  remainder are REQUIRED, so a bare "hey there" stays a greeting for chat's
+ *  conversational lane, and "hey tmct, …" (a vocative, no delimiter after the
+ *  greeting word) is left for the noise-strip tier that already owns it. */
+const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy)(?:\s+there)?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+/** Thanks lead-in with a delimiter (+ optional "quick question" bridge), the
+ *  sibling of GREETING_PREAMBLE_RE for the "thanks" word family (Bug B2, 0.8.2
+ *  follow-up): "thanks, <Q>" / "thanks so much, <Q>" -> "<Q>". chat.mjs's
+ *  GREETINGS set already treats a BARE "thanks"/"thank you"/"cheers" as
+ *  small-talk, and noise-strip.mjs's CASCADE_NOISE strips a single bare
+ *  token — but a multi-word lead-in ("thanks so much, X", "thanks a lot, X")
+ *  left "so"/"much"/"a"/"lot" debris after the noise strip that corrupted
+ *  re-parse (the object term inherited the debris). Same delimiter- and
+ *  non-empty-remainder-REQUIRED discipline as the greeting frame, so a bare
+ *  "thanks so much" (no delimiter, no question) stays small-talk. */
+const THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(?:\s+(?:so\s+much|a\s+lot|very\s+much|a\s+bunch))?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+/** Modal politeness wrapper: "can/could/would/will you [please] <Q>[, please][?]"
+ *  -> "<Q>". FILLER_WORDS already ate "can you"/"please" as words; this frame
+ *  removes them as a WRAPPER so the ", please" comma never survives into the
+ *  parsed object term. The unwrapped remainder flows on through the ordinary
+ *  passes, so "can you tell me a joke" -> "tell me a joke" -> (FILLER) "a joke"
+ *  — byte-identical to what the bare form normalizes to (the hm-joke wall). */
+const MODAL_WRAPPER_RE = /^(?:can|could|would|will)\s+you\s+(?:please\s+)?(.+?)(?:[,\s]+please)?\??$/i;
+/** show/give-me presentation bridge: "show me [the] <thing>". Three-way:
+ *  a KIND-listing remainder is left untouched (the compositional list grammar
+ *  owns "show me untested modules"); a remainder carrying a relation verb or an
+ *  interrogative lead is a real query merely presented — unwrap to it ("show me
+ *  which modules import X" -> "which modules import X"); anything else is an
+ *  entity presentation — bridge to the describe surface ("show me the store
+ *  module" -> "describe store module"). */
+const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
+
+/** Apply the closed preamble frames in order (greeting -> modal -> show/give-me),
+ *  repeated to a small fixpoint so stacked wrappers ("hey, can you show me X
+ *  please") peel fully. Pure and idempotent; unmatched text passes through. */
+export function applyPreambleFrames(text) {
+  let q = String(text || "");
+  for (let pass = 0; pass < 3; pass++) {
+    const before = q;
+    let m = q.match(GREETING_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(THANKS_PREAMBLE_RE);
+    if (m) q = m[1].trim();
+    m = q.match(MODAL_WRAPPER_RE);
+    if (m) q = m[1].trim();
+    m = q.match(SHOW_GIVE_ME_RE);
+    if (m) {
+      const rest = m[1].trim();
+      if (!isListingRemainder(rest)) {
+        q = (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest)) ? rest : `describe ${rest}`;
+      }
+    }
+    if (q === before) break;
+  }
+  return q;
+}
+
+// ---- ADVANCED_GRAMMAR track (a) (PLAN_ADVANCED_GRAMMAR.md §2): closed-frame
+// subordination + conditionals — the proven 0.8.2 preamble-frame method (closed,
+// delimiter-anchored, first-match-wins, unmatched text passes through
+// byte-unchanged) at its next size up. Two families:
+//   SUBORDINATION_FRAMES  strippable leading framing clauses ("since we're
+//     refactoring, which modules import x?" -> "which modules import x?") —
+//     the clause carries no query content, it's conversational scaffolding
+//     around a real question, same species as the greeting/thanks preambles.
+//   CONDITIONAL frames    "if <clause>, is it <qualifier>?" compiles to the
+//     EXISTING compositional boolean-qualifier shape the grammar already
+//     answers ("<kind> <relation-gerund> <object> and <qualifier>" — proven by
+//     test/ask-compositional.test.mjs's "classes inheriting from Base and
+//     tested"), and the counterfactual "if X were deleted, what would break"
+//     compiles to the existing transitive-modifier reverse-dependency closure
+//     ("which modules transitively import X" — proven by
+//     test/ask.test.mjs's transitive-modifier suite). Both frame families are
+//     wired INSIDE normalizeQuery (not as a separate call site) because this
+//     agent's scope is normalize.mjs only — ask.mjs/interpret/pipeline.mjs
+//     call normalizeQuery already, so embedding here reaches every strategy
+//     for free, with no new call site required. A conditional shape NOT
+//     covered by these two closed patterns is deliberately left unmatched —
+//     the honest-miss discipline PLAN_ADVANCED_GRAMMAR §2a states explicitly
+//     ("refuse any conditional whose consequent isn't a computable
+//     traversal"): only rewrite to a shape independently verified correct,
+//     never a plausible-looking guess. ----
+
+/** Strippable leading framing clause: "since/although/though/while/because/
+ *  whereas/given that/now that <clause>, <Q>" -> "<Q>". Delimiter- (comma-)
+ *  anchored and non-empty-remainder-required, same discipline as
+ *  GREETING_PREAMBLE_RE — a bare "since when do you know that" (no comma
+ *  splitting a framing clause from a real question) is NOT a subordination
+ *  wrapper and is left alone; "since" as an ordinary temporal content word
+ *  ("modules changed since last week", no leading comma-delimited clause)
+ *  never matches either. */
+const SUBORDINATION_FRAMES_RE =
+  /^(?:since|although|though|while|because|whereas|given\s+that|now\s+that)\s+.+?,\s*(.+)$/i;
+
+/** Apply the subordination-frame strip to a small fixpoint (a doubly-wrapped
+ *  "well, since X, although Y, <Q>" peels fully — rare, but the same
+ *  discipline applyPreambleFrames already uses). Pure; unmatched text passes
+ *  through byte-unchanged. */
+export function applySubordinationFrames(text) {
+  let q = String(text || "");
+  for (let pass = 0; pass < 3; pass++) {
+    const m = q.match(SUBORDINATION_FRAMES_RE);
+    if (!m) break;
+    q = m[1].trim();
+  }
+  return q;
+}
+
+/** relation-verb (bare 3rd-person singular, the RELATIONS table's own primary
+ *  form) -> gerund, the shape the compositional grammar's proven
+ *  "<kind> <gerund> <object> and <qualifier>" pattern needs. A small, closed,
+ *  hand-curated table (not a generic morphological rule) — the same
+ *  "no guessing" discipline as every other closed vocabulary in this file. */
+const CONDITIONAL_VERB_GERUND = Object.freeze({
+  imports: "importing", calls: "calling", touches: "touching", tests: "testing",
+  exports: "exporting", contains: "containing", defines: "defining", uses: "using",
+  "inherits from": "inheriting from",
+});
+/** entity kind noun (singular) -> plural, the LISTABLE_KINDS the compositional
+ *  grammar's subject slot takes. Regular English pluralization covers every
+ *  entry (no irregulars in this closed set), so a flat table beats a
+ *  morphological rule for the same "no guessing" reason as the verb table. */
+const CONDITIONAL_KIND_PLURAL = Object.freeze({
+  module: "modules", class: "classes", function: "functions", method: "methods",
+  attribute: "attributes", variable: "variables", commit: "commits", file: "files",
+});
+const CONDITIONAL_QUALIFIER_SRC =
+  "public|private|protected|static|abstract|constant|re-?exported|exported|tested|covered|untested|uncovered";
+/** "if a/the <kind> <relation-verb> <object>, is/are it/that/they/this
+ *  <qualifier>?" -> "<kind plural> <relation-gerund> <object> and <qualifier>".
+ *  Closed to the two small tables above (both ends validated), so an
+ *  unrecognized kind/verb/qualifier simply doesn't match — falls through to
+ *  the ordinary grammar, which honestly misses on the untransformed "if …"
+ *  text rather than risk a wrong composition. */
+const CONDITIONAL_QUALIFIER_RE = new RegExp(
+  "^if\\s+(?:a|an|the)?\\s*(" + Object.keys(CONDITIONAL_KIND_PLURAL).join("|") + ")\\s+"
+  + "(" + Object.keys(CONDITIONAL_VERB_GERUND).join("|") + ")\\s+"
+  + "(.+?),\\s*(?:is|are)\\s+(?:it|that|they|this)\\s+"
+  + "(" + CONDITIONAL_QUALIFIER_SRC + ")\\??$",
+  "i",
+);
+
+/** Counterfactual deletion: "if <X> were/was deleted/removed(,)? what
+ *  would/might break/fail/be affected?" -> "which modules transitively import
+ *  <X>" — the EXISTING reverse-dependency closure (impactClosure via the
+ *  transitive modifier, ask.mjs/codegraph.mjs), proven correct by
+ *  test/ask.test.mjs's transitive-modifier suite. Exported so chat.mjs can
+ *  independently recognize the SAME raw query shape and prepend a
+ *  hypothetical marker to the rendered answer (a hypothetical consequent must
+ *  never be presented as an unqualified fact) — normalize.mjs only rewrites
+ *  the QUESTION text, it never touches the answer. */
+export const COUNTERFACTUAL_RE =
+  /^if\s+(.+?)\s+(?:were|was)\s+(?:deleted|removed),?\s*what\s+(?:would|might|could)\s+(?:break|fail|be\s+affected)\??$/i;
+
+/** Apply the two closed CONDITIONAL frames, first-match-wins (qualifier
+ *  composition tried first — it is the more specific shape). Pure; unmatched
+ *  text passes through byte-unchanged. */
+export function applyConditionalFrames(text) {
+  const q = String(text || "");
+  const qual = q.match(CONDITIONAL_QUALIFIER_RE);
+  if (qual) {
+    const kind = CONDITIONAL_KIND_PLURAL[qual[1].toLowerCase()];
+    const gerund = CONDITIONAL_VERB_GERUND[qual[2].toLowerCase()];
+    return `${kind} ${gerund} ${qual[3].trim()} and ${qual[4].toLowerCase()}`;
+  }
+  const cf = q.match(COUNTERFACTUAL_RE);
+  if (cf) return `which modules transitively import ${cf[1].trim()}`;
+  return q;
+}
+
 /** Free-text -> normalized free-text: contractions expanded, g-dropped words
- *  restored, filler/politeness words stripped. Idempotent and pure — the same
+ *  restored, closed preamble/subordination/conditional frames peeled, filler/
+ *  politeness words stripped. Idempotent and pure — the same
  *  input always normalizes the same way, so both parsing strategies see
  *  identical text and their outputs are directly comparable. Deliberately
  *  does NOT force lowercase: object/subject terms (module names like
@@ -59,6 +270,19 @@ export function normalizeQuery(text) {
   q = q.replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
   q = q.replace(WRONG_WORD_RE, (m) => WRONG_WORDS[m.toLowerCase()]);
   q = q.replace(G_DROP, "$1ing");
+  // closed preamble frames (greeting lead-in, modal wrapper, show/give-me
+  // bridge) — AFTER the correction tables (a repaired "give me"/"show me" still
+  // feeds the bridge) but BEFORE the filler strip erases their anchor words.
+  q = applyPreambleFrames(q);
+  // subordination (strip a leading framing clause) THEN conditional (compile
+  // "if …" to an existing working shape) — subordination first so a stacked
+  // "since we're refactoring, if a module imports X, is it tested" peels its
+  // outer wrapper before the conditional frame ever sees it. Both run BEFORE
+  // the filler strip for the same reason the preamble frames do: their
+  // anchors ("since", "if", "is it") would otherwise be eaten as bare words,
+  // leaving punctuation/clause debris that poisons the parse.
+  q = applySubordinationFrames(q);
+  q = applyConditionalFrames(q);
   if (FILLER_WORDS.length) {
     const fillerRe = new RegExp(
       "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
@@ -173,8 +397,25 @@ export const PHRASING_FRAMES = Object.freeze([
   // separate authorship edge; "touched" IS the authorship signal (the churn commits
   // carry the author), so these are true synonyms of "who touched X", not a new
   // capability. Anaphora rides through untouched ("who wrote it" → "who touched it").
-  { re: /^who\s+(?:wrote|authored)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
-  { re: /^who\s+is\s+the\s+authors?\s+of\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+  // SHA GUARD (0.8.2 feel wave): a COMMIT object is NOT a synonym — "who is the
+  // author of abc1234" rewritten to "who touched abc1234" dumps the commit's
+  // touch-SET instead of naming its author. The negative lookahead refuses the
+  // rewrite when the object is a bare (optionally "commit "-prefixed) 7-40 char
+  // hex sha, leaving the un-rewritten form for the author lane to consume;
+  // file/symbol objects (anything non-sha, e.g. "deadbeef.mjs") keep the rewrite.
+  { re: /^who\s+(?:wrote|authored)\s+(?:the\s+)?(?!(?:commit\s+)?[0-9a-f]{7,40}\??$)(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+  { re: /^who\s+is\s+the\s+authors?\s+of\s+(?:the\s+)?(?!(?:commit\s+)?[0-9a-f]{7,40}\??$)(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },
+
+  // HAS-TESTS → the coverage question the RELATIONS table answers. "does X have
+  // tests" parses "have" as a defines-verb (VERB_TO_KIND), producing the garbled
+  // "No — no defines edge found from X to <whatever resolves>" receipt; "is X
+  // tested" traverses tests edges from the WRONG side (subject = X). Both mean
+  // the coverage question "what tests X" — rewrite onto it. Closed to a
+  // tests/coverage object ("does X have methods/members" stays the members
+  // family) and refuses any "not" in the subject span, so the set-complement
+  // negations ("is X not tested") keep their own handler downstream.
+  { re: /^(?:does|do)\s+(?!.*\bnot\b)(.+?)\s+have\s+(?:any\s+)?(?:tests?|test\s+coverage|coverage)\??$/i, to: (m) => `what tests ${m[1]}` },
+  { re: /^(?:is|are)\s+(?!.*\bnot\b)(.+?)\s+tested\??$/i, to: (m) => `what tests ${m[1]}` },
 
   // NEEDS-TESTS → the untested-module survey. "what needs tests" / "what needs
   // testing" is the plainest way to ask which modules are uncovered, and it hit the

package/src/memory/core.mjs

@@ -78,7 +78,7 @@ const MEMORY_VOCABULARY = [
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
   { prop: CANONICALISED_FROM_PROP, predicate: "canonicalisedFrom", note: "subPropertyOf derivedFrom: a canonical Fact cleaned from a raw Block/Source, never replacing it" },
-  { prop: "mgx:sourceType", note: "a Source's kind: operator | provider | corpus | web | entailed (the trust-prior key)" },
+  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | web | entailed (the trust-prior key)" },
   { prop: "mgx:sourceUrl", note: "a web Source's URL" },
   { prop: "mgx:sourceRule", note: "an entailed Source's rule id" },
   { prop: TRUST_SCORE_PROP, note: "materialised trust cache in [0,1] — pure function of a fact's Sources + createdAt (memory/trust.mjs); invalidated when a statedBy edge is added" },
@@ -171,6 +171,7 @@ function setAttr(ind, prop, key, value) {
 function sourceIdFor(desc) {
   switch (desc?.kind) {
     case "operator": return { id: OPERATOR_SOURCE_ID, type: "operator" };
+    case "teach": return { id: "src:teach-chat", type: "teach" };
     case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
     case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
     case "web": return { id: `src:learned:web:${fnv1aHex(String(desc.url || ""))}`, type: "web", url: String(desc.url || "") };
@@ -209,6 +210,7 @@ function upsertSource(payload, desc, createdAtCandidate) {
  * through. The tag formats are exactly what the writers produce:
  *   corpus:conceptnet /r/IsA   → { kind:"corpus",   name:"conceptnet" }
  *   ace:chat:<session>@<ts>    → { kind:"operator",  createdAt:<ts> }
+ *   teach:chat:<session>@<ts>  → { kind:"teach",     createdAt:<ts> }
  *   web:<url> | url:<url>      → { kind:"web",       url:<url> }
  *   entailed:<rule>            → { kind:"entailed",  rule:<rule> }
  * chat:/session: refs map to the operator; an unknown tag → null (no Source).
@@ -222,6 +224,11 @@ export function provenanceTagToSource(tag) {
     const at = head.indexOf("@");
     return { kind: "operator", createdAt: at >= 0 ? head.slice(at + 1) : "" };
   }
+  if (head.startsWith("teach:")) {
+    // the chat teach lane's natural frames — chat.mjs's teachProvenanceTag
+    const at = head.indexOf("@");
+    return { kind: "teach", createdAt: at >= 0 ? head.slice(at + 1) : "" };
+  }
   if (head.startsWith("web:")) return { kind: "web", url: head.slice("web:".length) };
   if (head.startsWith("url:")) return { kind: "web", url: head.slice("url:".length) };
   if (head.startsWith("entailed:")) return { kind: "entailed", rule: head.slice("entailed:".length) };

package/src/memory/trust.mjs

@@ -4,7 +4,7 @@
 // Trust is a COMPUTED attribute of a Fact — never hand-set — a pure function of
 // its Source edges, those Sources' types, and its mgx:createdAt. Three inputs
 // combine:
-//   - a Source-TYPE PRIOR (operator > provider > corpus > web > entailed);
+//   - a Source-TYPE PRIOR (operator > teach > provider > corpus > web > entailed);
 //   - CORROBORATION over the fact's distinct Sources by noisy-OR
 //     (1 − Π(1 − wᵢ), capped at 1) — two independent web sources (0.4) reach
 //     0.64, a lone operator fact is already 1.0;
@@ -26,11 +26,15 @@
 export const TRUST_SCORE_PROP = "mgx:trustScore";
 export const TRUST_INPUTS_PROP = "mgx:trustInputs";
 
-/** Source-type priors — the ordering operator > provider-graph > curated-corpus
- *  > web > unverified-entailment. The entailed value is a FLOOR before premise
- *  adjustment (see the entailed hook below). */
+/** Source-type priors — the ordering operator > teach > provider-graph >
+ *  curated-corpus > web > unverified-entailment. `teach` is the chat teach
+ *  lane's natural-frame writes ("remember that …", "<Name> owns <X>") — still
+ *  operator speech, but through a looser recognizer than the ACE-parsed
+ *  operator assert, so it sits just below the operator prior. The entailed
+ *  value is a FLOOR before premise adjustment (see the entailed hook below). */
 export const SOURCE_PRIOR = Object.freeze({
   operator: 1.0,
+  teach: 0.95,
   provider: 0.9,
   corpus: 0.7,
   web: 0.4,

package/src/router/call-validator.mjs

@@ -0,0 +1,45 @@
+// src/router/call-validator.mjs — pure registry validators shared by the
+// product router (resolver / guardrail / goal-reasoner) + the bench grader
+// (agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
+// bench code — so the product←bench dependency stays inverted: the bench
+// imports the product, never the other way round. No I/O, no Date.now, no LLM.
+
+import { isCapability, argKeysOf, requiredArgsOf, preconditionsOf, PRECOND } from "./registry.mjs";
+
+/** Every way a single produced call can be a HALLUCINATION — the one thing a
+ *  deterministic router must never do. Returns [] for a clean call, else a list
+ *  of { reason, detail }:
+ *    - "undeclared"  — name is not in the case's declared toolset
+ *    - "unknown-tool"— name is not a registry capability at all
+ *    - "unknown-arg" — an input key the capability does not accept
+ *    - "missing-arg" — a required arg absent (and no any-present precond covers it)
+ *  Any nonempty result = AUTOMATIC FAIL for the case. */
+export function hallucinationsIn(call, declaredTools) {
+  const problems = [];
+  const name = call?.name;
+  if (typeof name !== "string" || !name) return [{ reason: "unknown-tool", detail: "no tool name" }];
+  if (!isCapability(name)) return [{ reason: "unknown-tool", detail: name }];
+  if (!declaredTools.includes(name)) problems.push({ reason: "undeclared", detail: name });
+  const input = call.input && typeof call.input === "object" ? call.input : {};
+  const accepted = argKeysOf(name);
+  for (const key of Object.keys(input)) {
+    if (!accepted.has(key)) problems.push({ reason: "unknown-arg", detail: `${name}.${key}` });
+  }
+  // required-arg presence, honoring an any-present disjunction (search: query|kind)
+  const anyGroups = preconditionsOf(name)
+    .filter((p) => p.pred === PRECOND.anyPresent)
+    .map((p) => p.params);
+  const present = (k) => input[k] !== undefined && input[k] !== null && String(input[k]).trim() !== "";
+  for (const req of requiredArgsOf(name)) {
+    if (!present(req)) problems.push({ reason: "missing-arg", detail: `${name}.${req}` });
+  }
+  for (const group of anyGroups) {
+    if (!group.some(present)) problems.push({ reason: "missing-arg", detail: `${name} needs one of ${group.join("|")}` });
+  }
+  return problems;
+}
+
+/** True iff a produced call is dispatchable-shaped (no hallucination). */
+export function isCallWellFormed(call, declaredTools) {
+  return hallucinationsIn(call, declaredTools).length === 0;
+}