@polycode-projects/the-mechanical-code-talker 0.8.0 → 0.8.2

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/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,92 @@ 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 - …"), 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;
+/** 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(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;
+}
+
 /** Free-text -> normalized free-text: contractions expanded, g-dropped words
- *  restored, filler/politeness words stripped. Idempotent and pure — the same
+ *  restored, closed preamble 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 +143,10 @@ 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);
   if (FILLER_WORDS.length) {
     const fillerRe = new RegExp(
       "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
@@ -136,6 +224,26 @@ export const PHRASING_FRAMES = Object.freeze([
     to: (m) => `${m[2].toLowerCase()} ${m[1].toLowerCase()}`,
   },
 
+  // BARE COVERAGE SURVEY (no entity kind) → the attributive "<qualifier> modules"
+  // the grammar already answers. Once "what is a test" opens the topic, a developer
+  // asks the survey the plainest way — "what is untested", "what's not tested",
+  // "what isn't covered", "what is covered" — with NO entity noun at all, so the
+  // predicative-qualifier frame above (which needs a KIND between what/which and
+  // are/is) can't catch it, and it fell through to a soft wall ("no module matching
+  // 'not'…" / the "I answer questions…" orientation). Default the surveyed kind to
+  // modules (the same set "which modules are not tested" / "untested modules" return)
+  // and fold the negation into the qualifier (not tested → untested, not covered →
+  // uncovered). Anchored with no object, so "what tests cover X" / "what is a test"
+  // never match here.
+  {
+    re: /^what\s+(?:is|are)\s+(not\s+)?(tested|untested|covered|uncovered)\??$/i,
+    to: (m) => {
+      const q = m[2].toLowerCase();
+      const flipped = m[1] ? (q === "tested" ? "untested" : q === "covered" ? "uncovered" : q) : q;
+      return `${flipped} modules`;
+    },
+  },
+
   // CO-CHANGE → the "co-changes with" canonical the RELATIONS table answers. The
   // cochange verb synonyms (ask-vocab.mjs) include "co-changes with" / "moves
   // together with" / "tends to change together with", but NOT the plainest form a
@@ -145,6 +253,40 @@ export const PHRASING_FRAMES = Object.freeze([
   // onto "what co-changes with X" routes them to the working change-coupling query.
   { re: /^what\s+does\s+(.+?)\s+changes?\s+together\s+with\??$/i, to: (m) => `what co-changes with ${m[1]}` },
   { re: /^what\s+changes?\s+together\s+with\s+(.+?)\??$/i, to: (m) => `what co-changes with ${m[1]}` },
+
+  // AUTHORSHIP → the "who touched X" churn query. "who touched X" now names the
+  // commit author beside the sha (the 0.8.1 commit-ref quick-win), which invites the
+  // synonyms a developer reaches for next — "who wrote X", "who authored X", "who is
+  // the author of X" — and every one of them hit the grammar wall. tmct has no
+  // 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").
+  // 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
+  // grammar wall ("no module matching 'needs'…"). Route it onto the same attributive
+  // survey the bare "what is untested" frame lands on. Closed to the tests/coverage
+  // object, so it can't swallow a general "what needs X".
+  { re: /^what\s+needs\s+(?:to\s+be\s+)?(?:a\s+)?(?:tested|tests?|testing|coverage|covering)\??$/i, to: () => "untested modules" },
 ]);
 
 /** Apply the phrasing frames (members-of-class + where-defined) — first match wins

package/src/interpret/pipeline.mjs

@@ -27,6 +27,13 @@ import { normalizeQuery, applyNegationFrames, applyPhrasingFrames } from "./norm
 import { grammarStrategy } from "./strategies/grammar.mjs";
 import { keywordSpotStrategy } from "./strategies/keywords.mjs";
 import { noiseStripStrategy } from "./strategies/noise-strip.mjs";
+// Optional Node-flavored ACE strategy — same viewer-bundle boundary as the
+// ask-nlp adapter below: the ACE grammar reaches grammar/ace.mjs -> lexicon.mjs,
+// which reads its committed JSON via Node fs, so an inlining viewer bundle strips
+// this import; the `typeof` guard where STRATEGIES is built then degrades to an
+// ace-less registry instead of throwing over an undeclared identifier. (ACE is
+// async-only anyway, so the sync parseQuery path the viewer uses never ran it.)
+import { aceStrategy } from "./strategies/ace.mjs";
 import { mergeStrategyResults } from "./merge.mjs";
 // Optional Node-only wink adapter — same viewer-bundle boundary as ask.mjs: an
 // inlining bundle strips this import and the `typeof` read below degrades to
@@ -38,9 +45,17 @@ import { nlpAdapter } from "../ask-nlp.mjs";
  *  byte-identical to the original two-way agree/disagree behavior); noise-strip
  *  is the item-10 tolerant fallback (its own class; it only fires when the
  *  anchored grammar missed the text as-given, so it can never displace an
- *  existing template parse). interpret/strategies/ace.mjs (Phase 2) will
- *  register here the same way. */
-export const STRATEGIES = [grammarStrategy, keywordSpotStrategy, noiseStripStrategy];
+ *  existing template parse). interpret/strategies/ace.mjs (Phase 2 / Stage 2) is
+ *  the ACE-OWL controlled-fragment grammar, registered here as an ADDITIVE, own-
+ *  class ("ace-fact") strategy. It is ASYNC on purpose: runStrategiesSync (the
+ *  parseQuery / CHATBENCH-facing path) SKIPS Promise-returning strategies, so ACE
+ *  adds declarative-fragment reach to interpret() while leaving the sync spine
+ *  byte-stable (see strategies/ace.mjs for the full rationale). The `typeof` guard
+ *  mirrors the nlpAdapter degradation: a stripped ACE import (viewer bundle) leaves
+ *  the identifier undeclared, so the registry is ace-less there instead of a crash. */
+// eslint-disable-next-line no-undef
+const OPTIONAL_STRATEGIES = typeof aceStrategy !== "undefined" ? [aceStrategy] : [];
+export const STRATEGIES = [grammarStrategy, keywordSpotStrategy, noiseStripStrategy, ...OPTIONAL_STRATEGIES];
 
 /** The documented normalization pre-pass: whitespace-collapse + the §3.5
  *  normalization pipeline + the closed rhetorical-frame rewrites, applied ONCE

package/src/interpret/strategies/ace.mjs

@@ -0,0 +1,49 @@
+// interpret/strategies/ace.mjs — the ACE-OWL controlled-fragment grammar wired
+// into the interpretation pipeline as an ADDITIVE strategy (Stage 2, "ACE reach").
+//
+// The ACE engine (src/grammar/ace.mjs) has existed since Phase 2, but its pipeline
+// ADAPTER was the "real and empty" seam the pipeline header names (interpret/
+// pipeline.mjs). This file fills it. The contract is strictly ADD-ONLY:
+//
+//   · Its own class, "ace-fact" — DISJOINT from the graph-query strategies, so a
+//     clean ACE parse is a distinct-class ALTERNATE ("if you mean X then …"), never
+//     a same-class competitor that could displace a graph-query winner.
+//   · It emits a candidate ONLY on a CLEAN parse (parseAce returns triples). A
+//     structural-fit-with-residue (empty triples) or a total miss returns null, so
+//     a query sentence that merely LOOKS relation-shaped ("which modules import X",
+//     whose ACE residue is the "which") contributes nothing — fitting the grammar
+//     is a strong signal; missing it is a FEATURE and the tolerant strategies win.
+//
+// WHY ASYNC — the byte-stability guarantee. ask.mjs's parseQuery (the CHATBENCH
+// chat-facing path) runs strategies through runStrategiesSync, which — by the
+// pipeline's documented contract — SKIPS any Promise-returning strategy ("an async
+// strategy can only participate via interpret()"). Registering ACE async therefore
+// makes the sync parseQuery path PROVABLY untouched (CHATBENCH neutral, byte-for-
+// byte) while interpret() — the async pipeline — gains the declarative-fragment
+// reach. The work parseAce does is synchronous; the async wrapper is deliberate,
+// the mechanical seam that keeps the chat spine frozen. (grammar/ace.mjs itself is
+// imported UNCHANGED — no chat-facing edit.)
+
+import { parseAce } from "../../grammar/ace.mjs";
+
+/** Adapter: a clean ACE parse -> one candidate in its own class; anything else
+ *  (residue-only structural fit, or a hard miss) -> null. `via:"exact"` — a
+ *  controlled-grammar fit is exact evidence, never an approximate rewrite. */
+export function runAce(text) {
+  let parsed = null;
+  try { parsed = parseAce(text); } catch { return null; }
+  if (!parsed || !Array.isArray(parsed.triples) || parsed.triples.length === 0) return null;
+  return { strategyId: "ace", class: "ace-fact", candidates: [{ parsed, confidence: 0.85, via: "exact", note: `ACE ${parsed.pattern}` }] };
+}
+
+/** Pipeline registration (interpret/pipeline.mjs). ASYNC on purpose (see file
+ *  header): it participates in interpret() but is SKIPPED by runStrategiesSync,
+ *  so parseQuery — and the CHATBENCH spine it feeds — is byte-stable. */
+export const aceStrategy = {
+  id: "ace",
+  class: "ace-fact",
+  // eslint-disable-next-line require-await
+  async run(text) {
+    return runAce(text);
+  },
+};

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;
+}