@polycode-projects/the-mechanical-code-talker 2.10.5 → 2.11.1

package/src/adapters/corpus/wikipedia-live.mjs

@@ -13,24 +13,55 @@
 // The provider seam mirrors reference-pack.mjs's: registerLiveReferenceProvider
 // swaps the whole lookup behind one async { lookup(normTerm) } contract (tests
 // and the demo page stub it); null restores the default provider below.
+//
+// The research lane rides the same provider factory against
+// simple.wikipedia.org (registerResearchProvider/getResearchProvider below),
+// adding two fan-out reads: pageByTitle (an exact linked title costs ONE
+// round trip, no opensearch) and linkedTitles (the lead section's
+// namespace-0 links, document-ordered). Requests identify themselves per
+// Wikimedia's robot etiquette (WIKIMEDIA_USER_AGENT) and carry maxlag so an
+// overloaded replica set is backed off from, not hammered.
 
 import { normFactTerm } from "../../domain/hash.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { isReferenceArticleRow, sentencesUpTo, isaOf, SUMMARY_CHAR_CAP } from "../../domain/reference-pack.mjs";
 
 export const WIKIPEDIA_LIVE_ORIGIN = "https://en.wikipedia.org";
+export const SIMPLE_WIKIPEDIA_ORIGIN = "https://simple.wikipedia.org";
+
+/** The identification string Wikimedia's robot policy asks API clients to
+ *  carry, pointing at this project's public site as the contact. Browsers
+ *  refuse to override the User-Agent request header, so the API-recognised
+ *  Api-User-Agent header carries the same string there; under Node both are
+ *  sent. */
+export const WIKIMEDIA_USER_AGENT = "the-mechanical-code-talker (+https://polycode-projects.gitlab.io/the-mechanical-code-talker/)";
 
 const DEFAULT_TIMEOUT_MS = 4000;
 const DEFAULT_MIN_INTERVAL_MS = 2000;
 const RETRY_AFTER_FLOOR_MS = 5000;
+// Action-API requests carry maxlag so an overloaded replica set answers with
+// an error we back off from instead of adding to its load (Wikimedia's own
+// recommended default for non-interactive clients).
+const MAXLAG_SECONDS = 5;
 
 /**
- * A live-lookup provider: { lookup(normTerm) -> article row | null }.
+ * A live-lookup provider: { lookup(normTerm) -> article row | null }, plus
+ * the research fan-out surface: pageByTitle(title) fetches an exact title's
+ * summary in ONE round trip (no opensearch — a linked title is already
+ * exact), and linkedTitles(title) lists the namespace-0 articles the page's
+ * LEAD section links to, in document order.
  *
  * `fetchImpl` defaults to the global fetch; `origin` to en.wikipedia.org;
  * `lexicon` (optional) feeds the isa extraction. The row shape is the shipped
  * pack's own ({ term, title, text, summary, url, revid, isa? }), validated by
  * isReferenceArticleRow before it is ever returned.
+ *
+ * Throttle posture: every public method takes one "slot" gated by the
+ * minimum interval, the single-flight guard and any open cool-off. By
+ * default a caller that asks too soon gets null (the chat's clean-miss hook
+ * must never block a turn); with `waitForSlot: true` the method WAITS for
+ * the slot instead — the research queue's posture, where a false miss would
+ * be dishonest and the caller is already paced turn-by-turn.
  */
 export function createWikipediaLiveProvider({
   fetchImpl,
@@ -38,6 +69,8 @@ export function createWikipediaLiveProvider({
   timeoutMs = DEFAULT_TIMEOUT_MS,
   minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
   lexicon = null,
+  userAgent = WIKIMEDIA_USER_AGENT,
+  waitForSlot = false,
 } = {}) {
   const doFetch = fetchImpl ?? ((...args) => globalThis.fetch(...args));
   const cache = new Map(); // key -> row | null (hits AND settled misses)
@@ -45,18 +78,43 @@ export function createWikipediaLiveProvider({
   let coolOffUntil = 0;
   let inFlight = false;
 
+  const identifyingHeaders = () => {
+    if (!userAgent) return null;
+    const headers = { "Api-User-Agent": userAgent };
+    // A browser strips User-Agent as a forbidden header; only set it where
+    // no DOM says we are one (Node ships a global `navigator` these days, so
+    // `document` is the discriminating global).
+    if (typeof document === "undefined") headers["User-Agent"] = userAgent;
+    return headers;
+  };
+
+  function openCoolOff(retryAfterSeconds) {
+    const retryAfterMs = Number(retryAfterSeconds) * 1000;
+    coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+  }
+
   async function fetchJson(url) {
     const controller = typeof AbortController === "function" ? new AbortController() : null;
     const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
     try {
-      const res = await doFetch(url, controller ? { signal: controller.signal } : {});
+      const opts = {};
+      if (controller) opts.signal = controller.signal;
+      const headers = identifyingHeaders();
+      if (headers) opts.headers = headers;
+      const res = await doFetch(url, opts);
       if (res.status === 429) {
-        const retryAfterMs = Number(res.headers?.get?.("retry-after")) * 1000;
-        coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+        openCoolOff(res.headers?.get?.("retry-after"));
         return null;
       }
       if (!res.ok) return null;
-      return await res.json();
+      const body = await res.json();
+      // A maxlag rejection arrives as HTTP 200 with an error body (and a
+      // Retry-After header) — back off exactly as a 429 asks.
+      if (body?.error?.code === "maxlag") {
+        openCoolOff(res.headers?.get?.("retry-after"));
+        return null;
+      }
+      return body;
     } catch {
       return null;
     } finally {
@@ -64,6 +122,26 @@ export function createWikipediaLiveProvider({
     }
   }
 
+  /** When the next network slot opens: past the cool-off, past the minimum
+   *  interval since the last taken slot. */
+  const slotOpensAt = () => Math.max(coolOffUntil, lastLookupAt + minIntervalMs);
+
+  /** Take the one network slot, or report it unavailable. Default posture
+   *  returns false immediately (the clean-miss hook's "null, never block");
+   *  `waitForSlot` sleeps until the slot opens instead. */
+  async function takeSlot() {
+    for (;;) {
+      const now = Date.now();
+      if (!inFlight && now >= slotOpensAt()) {
+        lastLookupAt = now;
+        inFlight = true;
+        return true;
+      }
+      if (!waitForSlot) return false;
+      await new Promise((resolve) => setTimeout(resolve, Math.max(slotOpensAt() - now, 25)));
+    }
+  }
+
   /** The opensearch title whose normFactTerm fold equals or extends the key —
    *  the topic-drift guard: "quasar" may resolve to "Quasar" or "Quasars",
    *  never to a first suggestion about something else. */
@@ -76,12 +154,7 @@ export function createWikipediaLiveProvider({
     return null;
   }
 
-  async function roundTrips(key) {
-    const search = await fetchJson(
-      `${origin}/w/api.php?action=opensearch&format=json&origin=*&search=${encodeURIComponent(key)}&limit=3`,
-    );
-    const title = search ? matchingTitle(key, search) : null;
-    if (!title) return null;
+  async function summaryRow(key, title) {
     const summary = await fetchJson(
       `${origin}/api/rest_v1/page/summary/${encodeURIComponent(title.replace(/ /g, "_"))}`,
     );
@@ -103,25 +176,77 @@ export function createWikipediaLiveProvider({
     return isReferenceArticleRow(row) ? row : null;
   }
 
+  async function roundTrips(key) {
+    const search = await fetchJson(
+      `${origin}/w/api.php?action=opensearch&format=json&origin=*&maxlag=${MAXLAG_SECONDS}&search=${encodeURIComponent(key)}&limit=3`,
+    );
+    const title = search ? matchingTitle(key, search) : null;
+    if (!title) return null;
+    return summaryRow(key, title);
+  }
+
+  /** One slot-gated, cached operation: cache first (a settled hit or miss is
+   *  never refetched), then the slot, then `work()`, with every failure
+   *  cached as null so it never costs a second round trip. */
+  async function cachedFetch(cacheKey, work) {
+    if (cache.has(cacheKey)) return cache.get(cacheKey);
+    if (!(await takeSlot())) return null;
+    let value = null;
+    try {
+      value = await work();
+    } catch {
+      value = null;
+    } finally {
+      inFlight = false;
+    }
+    cache.set(cacheKey, value);
+    return value;
+  }
+
   return {
     async lookup(normTerm) {
       const key = String(normTerm ?? "");
       if (!key) return null;
-      if (cache.has(key)) return cache.get(key);
-      const now = Date.now();
-      if (inFlight || now < coolOffUntil || now - lastLookupAt < minIntervalMs) return null;
-      lastLookupAt = now;
-      inFlight = true;
-      let row = null;
-      try {
-        row = await roundTrips(key);
-      } catch {
-        row = null;
-      } finally {
-        inFlight = false;
-      }
-      cache.set(key, row);
-      return row;
+      return cachedFetch(key, () => roundTrips(key));
+    },
+
+    /** The summary for an EXACT title — one round trip, no opensearch. The
+     *  research queue's depth-1 fetch: a linked title came from the wiki
+     *  itself, so the fuzzy title match would only waste a request. */
+    async pageByTitle(title) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      return cachedFetch(`title\0${normFactTerm(t)}`, () => summaryRow(normFactTerm(t), t));
+    },
+
+    /** The namespace-0 articles the page's LEAD section links to, in document
+     *  order, capped at `limit`. One action-API round trip
+     *  (action=parse&prop=links&section=0): the lead is the smallest payload
+     *  that still orders links by how the article introduces its topic —
+     *  a full-page prop=links listing is alphabetical, which would make the
+     *  fan-out pick by spelling instead of relevance. Null on any failure. */
+    async linkedTitles(title, { limit = 25 } = {}) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      const listed = await cachedFetch(`links\0${normFactTerm(t)}`, async () => {
+        const parsed = await fetchJson(
+          `${origin}/w/api.php?action=parse&format=json&formatversion=2&origin=*&maxlag=${MAXLAG_SECONDS}&prop=links&redirects=1&page=${encodeURIComponent(t)}&section=0`,
+        );
+        const links = parsed?.parse?.links;
+        if (!Array.isArray(links)) return null;
+        const seen = new Set();
+        const out = [];
+        for (const link of links) {
+          if (!link || link.ns !== 0 || link.exists === false) continue;
+          const linkTitle = String(link.title ?? link["*"] ?? "").trim();
+          const folded = normFactTerm(linkTitle);
+          if (!linkTitle || !folded || seen.has(folded)) continue;
+          seen.add(folded);
+          out.push(linkTitle);
+        }
+        return out;
+      });
+      return Array.isArray(listed) ? listed.slice(0, Math.max(0, limit)) : null;
     },
   };
 }
@@ -143,3 +268,34 @@ export function getLiveReferenceProvider() {
   if (!defaultProvider) defaultProvider = createWikipediaLiveProvider();
   return defaultProvider;
 }
+
+// ---- the research lane's provider: Simple English Wikipedia, waiting slots --
+
+let defaultResearchProvider = null;
+let registeredResearchProvider = null;
+
+/** Swap the research lane's lookup: provider = { lookup, pageByTitle,
+ *  linkedTitles } (tests and the demo pages stub it, same seam shape as
+ *  registerLiveReferenceProvider). Pass null to restore the default
+ *  simple.wikipedia.org provider. */
+export function registerResearchProvider(provider) {
+  registeredResearchProvider = provider && typeof provider.lookup === "function" ? provider : null;
+}
+
+/** The research lane's active provider — the registered one, else one lazily
+ *  created singleton against simple.wikipedia.org with `waitForSlot` on: the
+ *  queue is paced turn-by-turn, so a throttled step WAITS for its polite slot
+ *  rather than reporting a false miss. `minIntervalMs` (first call only —
+ *  the singleton keeps its throttle clock) can only ever RAISE the interval;
+ *  the shipped minimum stays the floor. */
+export function getResearchProvider({ minIntervalMs } = {}) {
+  if (registeredResearchProvider) return registeredResearchProvider;
+  if (!defaultResearchProvider) {
+    defaultResearchProvider = createWikipediaLiveProvider({
+      origin: SIMPLE_WIKIPEDIA_ORIGIN,
+      waitForSlot: true,
+      minIntervalMs: Math.max(DEFAULT_MIN_INTERVAL_MS, Number(minIntervalMs) || 0),
+    });
+  }
+  return defaultResearchProvider;
+}

package/src/adapters/corpus/worlds-pack.mjs

@@ -15,7 +15,7 @@ import { readFileSync } from "node:fs";
 import { gunzipSync } from "node:zlib";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { isWorldsIndexEntry, isWorldRow, isWorldFactRow, isWorldRuleRow, isWorldMetaRow } from "../../domain/worlds-pack.mjs";
+import { isWorldsIndexEntry, isWorldRow, isWorldFactRow, isWorldRuleRow, isWorldMetaRow, expandWorldDefaultContents } from "../../domain/worlds-pack.mjs";
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 
@@ -84,7 +84,13 @@ export function loadWorld(dir, worldName) {
         else if (isWorldMetaRow(row) && !meta) meta = row;
       } catch { /* tolerated: a bad line loses one row, not the world */ }
     }
-    if (facts.length || rules.length || meta) payload = { name: worldName, facts, rules, meta };
+    // Class-default contents (library -> a book, kitchen -> a pan) are
+    // materialized here, the one choke point every loader path runs through
+    // (openAdventure, the site build, the tests) — never baked into the
+    // shipped shard, which stays a byte-copy of its hand-authored source.
+    if (facts.length || rules.length || meta) {
+      payload = { name: worldName, facts: expandWorldDefaultContents(facts), rules, meta };
+    }
   }
   worldCacheByKey.set(key, payload);
   return payload;

package/src/adapters/toml-config.mjs

@@ -125,6 +125,12 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (src.games !== undefined) cfg.games = src.games;
   if (src.planning !== undefined) cfg.planning = src.planning;
 
+  // Research-lane knobs (src/services/research.mjs): sparse PASS-THROUGH,
+  // same discipline as [games.*] — the raw `[research]` table
+  // (fanout_limit / depth_limit / min_interval_ms, snake_case) rides through
+  // unmodified; clamping and default-filling is resolveResearchConfig's job.
+  if (src.research !== undefined) cfg.research = src.research;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;

package/src/domain/ask-vocab.mjs

@@ -246,6 +246,23 @@ export const VERB_TO_KIND = Object.freeze(
   ),
 );
 
+/** The bare possessive "has"/"have"/"holds"/"hold" is bucketed onto `defines`
+ *  (RELATIONS.defines.verbs above) for genuine code shapes ("what modules
+ *  does app.mjs have", "does createTask have tests") — but those reach the
+ *  grammar/keyword-spot strategies pre-rewritten onto a different verb by
+ *  normalize.mjs's PHRASING_FRAMES (has-tests -> "what tests X", members ->
+ *  "what does X contain"), and the possession/property sense of "have" over a
+ *  TAUGHT individual ("does whiskers have fur") is answered entirely by
+ *  chat.mjs's own has-a/hasProperty readers, upstream of both strategies. So
+ *  a bare have-family verb reaching either strategy's TWO-NAMED-ROLE "ask"
+ *  shape ("does X have Y", free-text subject and object, no grain check) has
+ *  no legitimate code question left to mean, and confidently framing it as
+ *  "locate what a module/class defines" is worse than an honest miss — both
+ *  grammar.mjs (T1/T2/T3) and keywords.mjs check this set to decline instead.
+ *  Shared here (rather than declared per-file) so the two strategies' bundled
+ *  builds never collide on the same top-level identifier. */
+export const HAS_FAMILY_VERBS = Object.freeze(new Set(["has", "have", "holds", "hold"]));
+
 /** "what is a kind of X" / "what is a subclass of X" collision fix: some
  *  inherits verbs are themselves phrased "is a <continuation>", which would
  *  otherwise collide with grammar.mjs's literal meta-whatis reading and

package/src/domain/ask.mjs

@@ -1236,6 +1236,29 @@ function reverseOverSet(graph, kind, entityType, objectIds) {
   return [];
 }
 
+const GIT_PROV_REF_RE = /^git:(.+)$/i;
+
+/** How many distinct commits are attested to have touched a SET of entities —
+ *  the same "touched by N commit(s)" convention renderDescribe's attestation
+ *  line already uses (codegraph.mjs's turnRefCount), not the narrower "touches
+ *  edge count" reverseOverSet(kind="touches") returns. A commit can be recorded
+ *  in an entity's own `derived_from` provenance with no full Commit individual
+ *  of its own (the ingester's touches-edge and provenance-ref writes can drift,
+ *  e.g. a truncated commit walk) — reverseOverSet alone then undercounts, or
+ *  misses entirely when NO touches edge survived. Deduped by short sha so a
+ *  provenance ref naming a commit that DOES have a touches-edge individual
+ *  isn't double-counted. */
+function commitTouchCount(graph, objectIds) {
+  const shas = new Set(reverseOverSet(graph, "touches", "Commit", objectIds).map((c) => String(c.label || "").toLowerCase()));
+  for (const id of objectIds) {
+    for (const ref of graph.byId.get(id)?.derived_from || []) {
+      const m = GIT_PROV_REF_RE.exec(String(ref || ""));
+      if (m) shas.add(m[1].toLowerCase());
+    }
+  }
+  return shas.size;
+}
+
 /** Forward traversal over a SET of subject ids (the "things {X…} call/define" step). */
 function forwardOverSet(graph, kind, subjectIds) {
   const edges = kindsFor(kind).flatMap((k) => edgesOfKind(graph, k)).filter((e) => subjectIds.has(e.subject));
@@ -1934,6 +1957,24 @@ function evalUniversal(graph, ast, opts) {
   };
 }
 
+/** The object-id set a "how many commits touched <X>" count restricts to,
+ *  covering both AST shapes that phrasing compiles to: a flat single-object
+ *  reverse clause ("how many commits touched app/lib/a.mjs") or a composed
+ *  reverseSet over a nested inner set ("… touched the module that defines
+ *  fnAlpha"). Null for every other count shape (including an unresolved or
+ *  ambiguous object), so the caller falls back to its plain evalSet(base)
+ *  count unchanged. */
+function commitTouchObjectIds(graph, base, opts) {
+  if (base.node === "reverseSet" && base.kind === "touches" && base.entityType === "Commit") {
+    return new Set(evalSet(graph, base.inner, opts).map((i) => i.id));
+  }
+  if (base.node === "clause" && base.clause?.shape === "reverse" && base.clause.kind === "touches" && base.clause.entityType === "Commit") {
+    const { objMatch, ambiguous } = traverse(graph, base.clause, opts);
+    return objMatch && !ambiguous ? new Set([objMatch.id]) : null;
+  }
+  return null;
+}
+
 /** Compile any compositional AST to a result object traverse() returns for the
  *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
 function evalComposite(graph, ast, opts = {}) {
@@ -1941,7 +1982,16 @@ function evalComposite(graph, ast, opts = {}) {
   if (ast.node === "exists") return evalExists(graph, ast);
   if (ast.node === "qualCheck") return evalQualCheck(graph, ast, opts);
   if (ast.node === "universal") return evalUniversal(graph, ast, opts);
-  if (ast.node === "count") return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
+  if (ast.node === "count") {
+    // "how many commits touched <X>" — count against provenance attestation
+    // (commitTouchCount), not the bare touches-edge set evalSet(base) would
+    // give: see commitTouchCount's own doc for why the two can disagree.
+    const commitTouchIds = commitTouchObjectIds(graph, ast.base, opts);
+    if (commitTouchIds) {
+      return { compositeKind: "count", count: commitTouchCount(graph, commitTouchIds), entityType: ast.entityType, matches: [] };
+    }
+    return { compositeKind: "count", count: evalSet(graph, ast.base, opts).length, entityType: ast.entityType, matches: [] };
+  }
   if (ast.node === "list") return { compositeKind: "list", matches: evalSet(graph, ast.base, opts), entityType: ast.entityType, scoped: ast.scoped };
   if (ast.node === "superlative") return evalSuperlative(graph, ast);
   if (ast.node === "temporal") return evalTemporal(graph, ast, opts);

package/src/domain/grammar/ace.mjs

@@ -106,7 +106,12 @@ function resolveNP(lexicon, tokensIn, { allowCompound = false } = {}) {
     if (proper) return { term: `${ns}${proper}`, individual: true, extras: [], unknown: [] };
     if (CODE_REF.test(t)) return { term: `${ns}${t}`, individual: true, extras: [], unknown: [] };
     const noun = lookupNoun(lexicon, t, { singularOnly });
-    if (noun) return { term: `${ns}${noun.lemma}`, individual: false, noun, extras: [], unknown: [] };
+    // `folded` marks a match that only exists because lookupNoun's own
+    // trailing-"-s" strip or irregular-plural table rewrote the surface word
+    // — never an exact lexicon hit. parseCopula (below) uses this to keep a
+    // proper name that happens to fold to an unrelated dictionary word
+    // ("whiskers" -> "whisker") from silently losing its spelling.
+    if (noun) return { term: `${ns}${noun.lemma}`, individual: false, noun, folded: noun.lemma.toLowerCase() !== t.toLowerCase(), extras: [], unknown: [] };
     return { term: null, individual: false, extras: [], unknown: [t] };
   }
   if (tokens.length === 2) {
@@ -161,6 +166,26 @@ function resolveNP(lexicon, tokensIn, { allowCompound = false } = {}) {
   return { term: null, individual: false, extras: [], unknown: tokens.filter((t) => !classify(t, lexicon)) };
 }
 
+/** A bare single-token subject (no determiner of its own) that resolveNP only
+ *  resolved via a fold, immediately followed by an indefinite-article object
+ *  ("whiskers is A CAT", "every whiskers is A CAT"), is the canonical
+ *  individual-naming shape ("john is a man") wearing a proper name that
+ *  happens to fold to an unrelated dictionary word ("whiskers" ->
+ *  "whisker"). Trusting the fold here silently rewrites the taught subject's
+ *  spelling; declining it and reporting the token as unknown lets the
+ *  caller's own novel-individual fallback store the literal typed word
+ *  instead — the same honest-miss-over-guess call this file's
+ *  exact/irregular-only folds already make everywhere else. Shared by
+ *  parseCopula and parseEvery, the two patterns whose subject slot can hold
+ *  a bare single token immediately followed by "a"/"an". */
+function declineFoldedBareSubject(np, subjectToks, objectHead) {
+  if (np.term != null && !np.individual && np.folded
+    && subjectToks.length === 1 && /^an?$/i.test(objectHead)) {
+    return { term: null, individual: false, extras: [], unknown: [subjectToks[0]] };
+  }
+  return np;
+}
+
 /** The shared miss result: a structural fit with undeclared words returns the
  *  pattern + residue (triples empty); a fit with only declared-but-unusable
  *  phrasing returns null — the honest fall-through either way. */
@@ -349,7 +374,16 @@ function parseEvery(lexicon, toks, lower) {
   if (isIdx <= 1 || isIdx === toks.length - 1) return null;
   const rest = toks.slice(isIdx + 1);
   const everyAdjOnly = rest.length === 1 ? lookupAdjective(lexicon, rest[0]) : null;
-  const np1 = resolveNP(lexicon, toks.slice(1, isIdx), { allowCompound: !everyAdjOnly });
+  const subjectToks = toks.slice(1, isIdx);
+  // Same fold-vs-individual ambiguity parseCopula guards against — a
+  // determiner-less "every whiskers is a cat" reaches the identical
+  // single-token resolveNP fold ("whiskers" -> "whisker") assertCandidates
+  // manufactures as a candidate phrasing whenever the bare payload has no
+  // determiner of its own, so this needs the same declineFoldedBareSubject
+  // guard or that candidate alone re-opens the bug parseCopula just closed.
+  const np1 = declineFoldedBareSubject(
+    resolveNP(lexicon, subjectToks, { allowCompound: !everyAdjOnly }), subjectToks, rest[0],
+  );
   if (everyAdjOnly) return adjectiveCopula(lexicon, PATTERN_ADJECTIVE, np1, everyAdjOnly);
   const np2 = resolveNP(lexicon, rest, { allowCompound: true });
   if (np1.term == null || np2.term == null) return missOrNull(PATTERN_SUB_CLASS_OF, [np1, np2]);
@@ -414,7 +448,13 @@ function parseOfForm(lexicon, toks, lower) {
 function parseCopula(lexicon, toks, lower, isIdx) {
   const rest = toks.slice(isIdx + 1);
   if (!rest.length) return null;
-  const np1 = resolveNP(lexicon, toks.slice(0, isIdx), { allowCompound: rest.length > 1 });
+  const subjectToks = toks.slice(0, isIdx);
+  // parseAce never reaches here for "are", only singular "is" — see
+  // declineFoldedBareSubject's own docblock for why a bare single-token
+  // subject that only resolves by folding needs this guard.
+  const np1 = declineFoldedBareSubject(
+    resolveNP(lexicon, subjectToks, { allowCompound: rest.length > 1 }), subjectToks, rest[0],
+  );
   if (rest.length === 1) {
     const adj = lookupAdjective(lexicon, rest[0]);
     if (adj) return adjectiveCopula(lexicon, PATTERN_ADJECTIVE, np1, adj);

package/src/domain/interpret/normalize.mjs

@@ -128,8 +128,12 @@ const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|yeah\s+nah|g
  *  the "thanks" word family: "thanks so much, <Q>" -> "<Q>". */
 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;
 /** Acknowledgement lead-in with a delimiter ("ok cool, <Q>"), repeating (`+`)
- *  so a stack of ack-words peels in one pass. */
-const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem)[\s,]+)+(.+)$/i;
+ *  so a stack of ack-words peels in one pass. "one more"/"another one"/"just
+ *  one more" join the ack-word alternation as the same discourse move under a
+ *  different wording — a throwaway counting aside before the real content,
+ *  never part of the content itself ("ok, one more, teach me: no server is a
+ *  client" must peel exactly as "ok cool, <Q>" already does). */
+const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem|(?:just\s+)?(?:one|another)\s+more|another\s+one)[\s,]+)+(.+)$/i;
 /** Self-orientation lead-in with a delimiter — "just poking around, <Q>",
  *  "first time using this, <Q>". */
 const BROWSING_PREAMBLE_RE = /^(?:just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)|first\s+time\s+(?:trying\s+this\s+out|using\s+this|here)|i'?m\s+new\s+(?:here|around\s+here|to\s+(?:this|all\s+this)(?:\s+(?:repo|codebase|project|app|tool|thing))?))\s*[,.—–-]\s*(.+)$/i;

package/src/domain/interpret/strategies/grammar.mjs

@@ -8,7 +8,7 @@ import {
   VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND,
   META_MEANING_VERBS, WHERE_MARKERS, MENTION_MARKERS,
   INHERITS_REVERSE_VERBS, stripTrailingScopeFiller, stripTrailingDiscourseTag,
-  ARTICLE_RELATION_CONTINUATIONS,
+  ARTICLE_RELATION_CONTINUATIONS, HAS_FAMILY_VERBS,
 } from "../../ask-vocab.mjs";
 import { escapeRegex } from "../normalize.mjs";
 
@@ -17,6 +17,11 @@ const ENTITY_ALT = Object.keys(ENTITY_TO_TYPE).sort((a, b) => b.length - a.lengt
 const MODIFIER_ALT = Object.keys(MODIFIER_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
 const META_ALT = META_MEANING_VERBS.slice().sort((a, b) => b.length - a.length).map(escapeRegex).join("|");
 
+// See ask-vocab.mjs's own HAS_FAMILY_VERBS for why a bare have-family verb
+// never resolves to `defines` in this template's "ask"/"reverse"/"forward"
+// shapes below.
+const isHasFamilyDefines = (kind, verb) => kind === "defines" && HAS_FAMILY_VERBS.has(verb);
+
 const TEMPLATES = [
   // T1 ASK: "does X import Y" -> Yes/No. REVERSE VERB SWAP: a semantically-reverse
   // verb ("superclass of") means the opposite of its forward counterpart, so
@@ -27,6 +32,7 @@ const TEMPLATES = [
     build: (m) => {
       const verb = m[2].toLowerCase();
       const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
       let subject = m[1].trim();
       let object = m[3].trim();
       if (INHERITS_REVERSE_VERBS.includes(verb)) [subject, object] = [object, subject];
@@ -37,23 +43,30 @@ const TEMPLATES = [
   {
     name: "reverse",
     re: new RegExp(`^which\\s+(${ENTITY_ALT})\\s+(?:(${MODIFIER_ALT})\\s+)?(${VERB_ALT})\\s+(.+?)\\??$`, "i"),
-    build: (m) => ({
-      shape: "reverse",
-      entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
-      modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
-      kind: VERB_TO_KIND[m[3].toLowerCase()],
-      object: m[4].trim(),
-    }),
+    build: (m) => {
+      const verb = m[3].toLowerCase();
+      const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
+      return {
+        shape: "reverse",
+        entityType: ENTITY_TO_TYPE[m[1].toLowerCase()],
+        modifier: m[2] ? MODIFIER_TO_KIND[m[2].toLowerCase()] : "direct",
+        kind,
+        object: m[4].trim(),
+      };
+    },
   },
   // T3 forward: "what does <object> <verb>" — X is given, list its R-related things.
   // "did" joins does/do for the past-tense commit forms ("what did commit <sha> touch").
   {
     name: "forward",
     re: new RegExp(`^what\\s+(?:does|do|did)\\s+(.+?)\\s+(${VERB_ALT})\\??$`, "i"),
-    build: (m) => ({
-      shape: "forward", entityType: null, modifier: "direct",
-      kind: VERB_TO_KIND[m[2].toLowerCase()], object: m[1].trim(),
-    }),
+    build: (m) => {
+      const verb = m[2].toLowerCase();
+      const kind = VERB_TO_KIND[verb];
+      if (isHasFamilyDefines(kind, verb)) return null;
+      return { shape: "forward", entityType: null, modifier: "direct", kind, object: m[1].trim() };
+    },
   },
   // T4 meta: "what does <term> mean" — a question about the graph's own vocabulary,
   // not a graph traversal. VERB_ALT and META_ALT are disjoint tables, so this never
@@ -65,16 +78,33 @@ const TEMPLATES = [
   },
   // T5 meta: "what is a/an <term>" — the bare (no-article) form is restricted to
   // the closed ENTITY_TO_TYPE vocabulary (build() -> null otherwise, falling
-  // through); the WITH-article form is unrestricted.
+  // through); the WITH-article form is unrestricted. A "the"-article form is
+  // ALSO accepted, but only for a single-token term ("the Task") — the same
+  // schema-then-code-entity lookup a bare "Task" would reach (traverse()'s
+  // shape:"meta" handling, via metaFallbackEntityAnswer). Multi-word "the …"
+  // phrases stay excluded on purpose: "what is the meaning of this codebase"/
+  // "the purpose of X" are existential framings with their own decline
+  // elsewhere, never a literal term to look up (see the out-of-grammar test
+  // this guards).
   {
     name: "meta-whatis",
-    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:(an?)\\s+)?(.+?)\\??$`, "i"),
+    re: new RegExp(`^what\\s+(?:is|are)\\s+(?:(an?|the)\\s+)?(.+?)\\??$`, "i"),
     build: (m) => {
+      const article = m[1] ? m[1].toLowerCase() : null;
       const object = stripTrailingDiscourseTag(m[2].trim());
-      if (!m[1] && !ENTITY_TO_TYPE[object.toLowerCase()]) return null; // bare form: closed-set only
-      // "what is a kind/subclass of X" is an inherits phrasing, not a term to define.
+      const isSingleToken = !/\s/.test(object);
+      if (article === "the" && !isSingleToken) return null;
+      if (!article && !ENTITY_TO_TYPE[object.toLowerCase()]) return null; // bare form: closed-set only
       const objLower = object.toLowerCase();
-      if (m[1] && ARTICLE_RELATION_CONTINUATIONS.some(
+      // "what is a kind/subclass of X" is an inherits phrasing, not a term to
+      // define — ARTICLE_RELATION_CONTINUATIONS only ever derives from the
+      // "is a/an <continuation>" verb forms, so it's checked only for those;
+      // "the"-definite reverse-inherits forms ("is the superclass of") are a
+      // separate, deliberately unfolded set (ask-vocab.mjs's own comment on
+      // INHERITS_REVERSE_VERB_LIST) — moot here since those are always
+      // multi-word and already excluded by the single-token check above, but
+      // named for the same reason ARTICLE_RELATION_CONTINUATIONS is.
+      if (article && article !== "the" && ARTICLE_RELATION_CONTINUATIONS.some(
         (c) => objLower === c || objLower.startsWith(`${c} `),
       )) return null;
       return { shape: "meta", entityType: null, modifier: "direct", kind: "meta", object: stripTrailingScopeFiller(object) };