@polycode-projects/the-mechanical-code-talker 2.3.1 → 2.5.2

package/src/domain/codegraph.mjs

@@ -1,5 +1,8 @@
 import { lookupByProseTokens, proseLayerHits, splitIdentifierWords } from "./prose.mjs";
 import { CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/trust.mjs";
+import { isTestPath } from "./module-paths.mjs";
+import { idfWeight } from "./text-stats.mjs";
+import { bfsLevels } from "./planning.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
 // deterministic indexer writes to <repo>/.tmct/graph.json (shape produced by
@@ -369,24 +372,12 @@ export function impactClosure(graph, ind, { maxDepth = 8 } = {}) {
   }
 
   const levels = []; // [[{id, label, via, tests[]}], …] indexed by depth-1
-  const visited = new Set([ind.id]);
-  let frontier = [ind.id];
-  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
-    const next = [];
-    const level = [];
-    for (const id of frontier) {
-      for (const dep of dependents.get(id) || []) {
-        if (visited.has(dep.id)) continue;
-        visited.add(dep.id);
-        level.push({ ...dep, tests: coveredBy.get(dep.id) || [] });
-        next.push(dep.id);
-      }
-    }
-    if (level.length) {
-      level.sort((a, b) => String(a.label).localeCompare(String(b.label)));
-      levels.push(level);
-    }
-    frontier = next;
+  for (const level of bfsLevels(ind.id, (id) => dependents.get(id) || [], { maxDepth, keyOf: (dep) => dep.id })) {
+    if (!level.length) continue;
+    const withTests = level
+      .map((dep) => ({ ...dep, tests: coveredBy.get(dep.id) || [] }))
+      .sort((a, b) => String(a.label).localeCompare(String(b.label)));
+    levels.push(withTests);
   }
   return levels;
 }
@@ -470,7 +461,6 @@ const EXACT_W = 5;         // token == a whole defined symbol name
 const SYM_MATCH_CAP = 4;   // only the top-K highest-IDF symbol-component hits count
 const PROX_FRAC = 0.2;     // import-adjacency bonus = this × the strongest matched neighbour
 const PROX_CAP_FRAC = 0.35; // capped at this × the module's own score
-const isTestLabel = (s) => /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
 // opt-in via demoteNonProd: demote (not exclude) example/fixture/sample/demo/test-*
 // paths, which share vocabulary with production modules and would otherwise shadow them
 const NONPROD_DEMOTE = 0.15;
@@ -758,14 +748,20 @@ function scoreModules(graph, tokens, opts = {}) {
     modules.push({ ind, label, labelLc, defines, symSet, symComps, dotted });
   }
   const N = modules.length || 1;
-  // idf = log(1 + N/(1+df)): near-zero for ubiquitous tokens, large for rare ones
+  // idf = log(1 + N/(1+df)): near-zero for ubiquitous tokens, large for rare ones.
+  // Memoized so the literalMention pass below can price candidate tokens the query
+  // tokenizer never produced without recomputing document frequency for the rest.
   const idf = new Map();
-  for (const t of tokens) {
-    if (idf.has(t)) continue;
+  const documentFrequencyOf = (t) => {
     let df = 0;
     for (const m of modules) if (m.labelLc.includes(t) || m.symComps.has(t) || m.symSet.has(t)) df++;
-    idf.set(t, Math.log(1 + N / (1 + df)));
-  }
+    return df;
+  };
+  const idfOf = (t) => {
+    if (!idf.has(t)) idf.set(t, idfWeight(N, documentFrequencyOf(t)));
+    return idf.get(t);
+  };
+  for (const t of tokens) idfOf(t);
   const scored = [];
   for (const m of modules) {
     let exactScore = 0, pathScore = 0, matchCount = 0;
@@ -782,8 +778,8 @@ function scoreModules(graph, tokens, opts = {}) {
     for (let i = 0; i < Math.min(compWeights.length, SYM_MATCH_CAP); i++) symScore += compWeights[i] * SYM_W;
     let score = exactScore + pathScore + symScore;
     if (!score) continue;
-    if (demoteNonProd && (isTestLabel(m.labelLc) || isNonProdLabel(m.labelLc))) score *= NONPROD_DEMOTE;
-    else if (isTestLabel(m.labelLc)) score *= 0.4; // source first; tests still discoverable
+    if (demoteNonProd && (isTestPath(m.labelLc) || isNonProdLabel(m.labelLc))) score *= NONPROD_DEMOTE;
+    else if (isTestPath(m.labelLc)) score *= 0.4; // source first; tests still discoverable
     const matching = m.defines.filter((d) => { const dl = d.toLowerCase(); const cs = identComponents(d); return tokens.some((t) => dl === t || cs.has(t)); });
     const density = m.defines.length ? matchCount / m.defines.length : 0;
     scored.push({ ind: m.ind, score, defineCount: m.defines.length, matching, density });
@@ -798,14 +794,6 @@ function scoreModules(graph, tokens, opts = {}) {
       }
       return false;
     };
-    const idfOf = (t) => {
-      if (!idf.has(t)) {
-        let df = 0;
-        for (const m of modules) if (m.labelLc.includes(t) || m.symComps.has(t) || m.symSet.has(t)) df++;
-        idf.set(t, Math.log(1 + N / (1 + df)));
-      }
-      return idf.get(t);
-    };
     const byModId = new Map(modules.map((m) => [m.ind.id, m]));
     let maxBase = 0;
     for (const s of scored) maxBase = Math.max(maxBase, s.score);
@@ -986,18 +974,131 @@ export function selectRankedModules(ranked, { top_k = 2, scoreGapK = null } = {}
   return picked;
 }
 
+// ---- the `name` filter: caller text compiled to a regex, under a work bound ----
+
+/* A backtracking engine can be made to run for minutes on one short label, and
+   `name` arrives from a tool call, so the pattern is compiled under bounds
+   rather than trusted. Two independent shapes cost real time, and measurement
+   is the only way to tell them apart:
+
+     (a+)+$        vs 30 characters   — over 30s   (a quantified group backtracks
+                                                    exponentially in label length)
+     a*a*a*a*a*$   vs 128 characters  — 101s       (no group at all; every extra
+                                                    quantifier raises the degree
+                                                    of a polynomial in the same
+                                                    length)
+
+   So the pattern gate refuses a quantified group and a back-reference, which is
+   what exponential backtracking needs, and caps the quantifier count, which
+   bounds the polynomial's degree. Capping the tested label length bounds its
+   base. The budget then backstops the pair: a static gate is exactly the kind of
+   thing that can miss a case, and the budget bounds the damage when it does. */
+const NAME_PATTERN_MAX_LENGTH = 128;
+const NAME_PATTERN_MAX_QUANTIFIERS = 4;
+const NAME_MATCH_MAX_LABEL = 64;      // the longest label measured across real graphs is 27
+const NAME_MATCH_BUDGET_MS = 250;
+
+class NameFilterBudgetExceeded extends Error {}
+
+/** Classifies the backtracking hazards in `pattern`: how many quantifiers it
+ *  applies, whether any of them quantifies a group, and whether it back-refers.
+ *  Escapes and character-class interiors are inert, `(?` opens a group rather
+ *  than quantifying, and a `?` right after a quantifier only marks it lazy.
+ *  @returns {{quantifiers: number, quantifiedGroup: boolean, backreference: boolean}} */
+export function scanNamePattern(pattern) {
+  let quantifiers = 0;
+  let quantifiedGroup = false;
+  let backreference = false;
+  let inClass = false;
+  let prev = "";
+  let prevWasQuantifier = false;
+  const countQuantifier = () => {
+    quantifiers += 1;
+    if (prev === ")") quantifiedGroup = true;
+    prevWasQuantifier = true;
+  };
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "\\") {
+      const next = pattern[i + 1] || "";
+      if (!inClass && next >= "1" && next <= "9") backreference = true;
+      i += 1;
+      prev = "";
+      prevWasQuantifier = false;
+      continue;
+    }
+    if (inClass) {
+      if (ch === "]") { inClass = false; prev = "]"; prevWasQuantifier = false; }
+      continue;
+    }
+    if (ch === "[") { inClass = true; prev = "["; prevWasQuantifier = false; continue; }
+    if (ch === "?" && (prev === "(" || prevWasQuantifier)) { prev = "?"; prevWasQuantifier = false; continue; }
+    if (ch === "*" || ch === "+" || ch === "?") { countQuantifier(); prev = ch; continue; }
+    if (ch === "{") {
+      const close = pattern.indexOf("}", i);
+      const body = close === -1 ? "" : pattern.slice(i + 1, close);
+      if (close !== -1 && /^\d+(,\d*)?$/.test(body)) { countQuantifier(); i = close; prev = "}"; continue; }
+      prev = "{";
+      prevWasQuantifier = false;
+      continue;
+    }
+    prev = ch;
+    prevWasQuantifier = false;
+  }
+  return { quantifiers, quantifiedGroup, backreference };
+}
+
+/** Compiles the `name` filter into a label matcher whose total work is bounded.
+ *  `now` is injectable so a test can drive the budget without waiting on it.
+ *  @returns {{test: (label: string) => boolean}|{error: string}} */
+export function compileNameFilter(name, { now = Date.now } = {}) {
+  const pattern = String(name);
+  if (pattern.length > NAME_PATTERN_MAX_LENGTH) {
+    return { error: `name pattern is ${pattern.length} characters; the limit is ${NAME_PATTERN_MAX_LENGTH}.` };
+  }
+  const { quantifiers, quantifiedGroup, backreference } = scanNamePattern(pattern);
+  if (quantifiedGroup) {
+    return { error: `name pattern "${pattern}" quantifies a group, which can backtrack for minutes on one label. Quantify a character or a class instead.` };
+  }
+  if (backreference) {
+    return { error: `name pattern "${pattern}" uses a back-reference, which can backtrack for minutes on one label.` };
+  }
+  if (quantifiers > NAME_PATTERN_MAX_QUANTIFIERS) {
+    return { error: `name pattern "${pattern}" has ${quantifiers} quantifiers; the limit is ${NAME_PATTERN_MAX_QUANTIFIERS}.` };
+  }
+  let re;
+  try { re = new RegExp(pattern, "i"); } catch { return { error: `invalid name pattern: ${pattern}` }; }
+  let deadline = null;
+  return {
+    test(label) {
+      if (deadline === null) deadline = now() + NAME_MATCH_BUDGET_MS;
+      else if (now() > deadline) {
+        throw new NameFilterBudgetExceeded(`name pattern "${pattern}" exceeded its ${NAME_MATCH_BUDGET_MS}ms matching budget.`);
+      }
+      return re.test(String(label).slice(0, NAME_MATCH_MAX_LABEL));
+    },
+  };
+}
+
 export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
   const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   const wantKind = String(kind || "").trim().toLowerCase();
   const decFilter = String(decorator || "").trim().toLowerCase();
   let nameRe = null;
   if (name) {
-    try { nameRe = new RegExp(name, "i"); } catch { return `invalid name pattern: ${name}`; }
+    const compiled = compileNameFilter(name);
+    if (compiled.error) return compiled.error;
+    nameRe = compiled;
   }
   // kind= switches to symbol search (functions/classes/methods/attributes); the
   // default (no kind) keeps the module "where does this live" search unchanged.
   if (wantKind && wantKind !== "module") {
-    return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe });
+    try {
+      return searchSymbols(graph, tokens, { limit, kind: wantKind, decFilter, nameRe });
+    } catch (e) {
+      if (e instanceof NameFilterBudgetExceeded) return e.message;
+      throw e;
+    }
   }
   if (!tokens.length && !nameRe && !decFilter) return "empty query";
   const scored = scoreModules(graph, tokens);
@@ -1137,7 +1238,7 @@ export function renderSignature(graph, ind) {
 }
 
 /** Forward bases + the transitive reverse inheritance closure (who extends this) —
- *  replaces grepping `class X(Base)` across the tree. Uses `inherits` (mgx:subclassOf). */
+ *  replaces grepping `class X(Base)` across the tree. Uses `inherits` (seon:hasSuperType). */
 export function renderSubclasses(graph, ind) {
   const inherits = edgesOfKind(graph, "inherits");
   const bases = inherits.filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object);
@@ -1148,25 +1249,10 @@ export function renderSubclasses(graph, ind) {
   }
   const lines = [`${ind.label} — ${classHeading(ind.class)} (id: ${ind.id})`];
   lines.push(bases.length ? `extends: ${capJoin(bases, SUBCLASS_CAP)}` : "extends: (no internal/recorded base classes)");
-  const visited = new Set([ind.id]);
   const levels = [];
-  let frontier = [ind.id];
-  for (let depth = 1; depth <= 8 && frontier.length; depth += 1) {
-    const next = [];
-    const level = [];
-    for (const id of frontier) {
-      for (const c of childrenOf.get(id) || []) {
-        if (visited.has(c.id)) continue;
-        visited.add(c.id);
-        level.push(c.label);
-        next.push(c.id);
-      }
-    }
-    if (level.length) {
-      level.sort((a, b) => String(a).localeCompare(String(b)));
-      levels.push(level);
-    }
-    frontier = next;
+  for (const level of bfsLevels(ind.id, (id) => childrenOf.get(id) || [], { maxDepth: 8, keyOf: (c) => c.id })) {
+    if (!level.length) continue;
+    levels.push(level.map((c) => c.label).sort((a, b) => String(a).localeCompare(String(b))));
   }
   const total = levels.reduce((n, l) => n + l.length, 0);
   if (!total) {
@@ -1252,7 +1338,7 @@ export function renderUntested(graph) {
       (i) =>
         (i.class || "") === "Module" &&
         !testModules.has(i.id) &&
-        !isTestLabel(String(i.label).toLowerCase()) &&
+        !isTestPath(String(i.label).toLowerCase()) &&
         !covered.has(i.id),
     )
     .map((i) => i.label)

package/src/domain/completions/graph-adapter.mjs

@@ -12,7 +12,7 @@ import { ask } from "../ask.mjs";
 import { requireInjected } from "./injected.mjs";
 
 /** renderDescribe() renders one line per fact with no terminal punctuation of its own;
- *  rank.mjs's splitSentences() treats each line as its own candidate sentence, and
+ *  rank.mjs's splitBlockSentences() treats each line as its own candidate sentence, and
  *  complete.mjs joins kept sentences with a single space, so two adjacent lines without
  *  a period between them would otherwise read as one run-on clause. */
 function withTerminalPunctuation(text) {

package/src/domain/completions/group.mjs

@@ -3,21 +3,12 @@
 // memory/blocks.mjs's buildNeighbours()/OVERLAP_MIN). Block granularity, no sub-block spans.
 // Each group's label is its top shared-IDF tokens (df/N over the hit set, not the corpus).
 
-import { STOPWORDS } from "../prose.mjs";
+import { makeContentTokens } from "../prose.mjs";
+import { idfOver } from "../text-stats.mjs";
 import { requireInjected } from "./injected.mjs";
 
 const LABEL_TOKEN_COUNT = 5;
 
-// tokenizeBlock's raw output re-admits stopwords, which would collapse almost any two
-// sentences into one giant component under unweighted overlap clustering; filter them here.
-const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
-
-/** tokenizeBlock(text), narrowed to real content tokens (see isContentToken above) — the
- *  token set this module actually clusters and labels on. */
-function makeContentTokens(tokenizeBlock) {
-  return (text) => tokenizeBlock(text).filter(isContentToken);
-}
-
 /** Plain union-find (path halving, union-by-index) — small N here (a single broad search's
  *  hit count). */
 function unionFind(n) {
@@ -86,12 +77,7 @@ export function groupHits(hits, { overlapMin, store } = {}) {
   }
 
   // IDF over THIS hit set (df/N), not the whole corpus.
-  const N = ids.length;
-  const df = new Map();
-  for (const id of ids) {
-    for (const t of new Set(tokensById[id])) df.set(t, (df.get(t) || 0) + 1);
-  }
-  const idf = (t) => Math.log(1 + N / (1 + (df.get(t) || 0)));
+  const { idf } = idfOver(tokensById);
 
   const groups = [];
   for (const memberIdx of componentIdx.values()) {

package/src/domain/completions/infer.mjs

@@ -7,20 +7,11 @@
 // Entities are a group's content tokens narrowed to graph-known terms (normFactTerm-matched
 // against loaded facts) — sharing an English word alone never licenses a relation.
 
-import { splitSentences } from "./rank.mjs";
-import { STOPWORDS } from "../prose.mjs";
+import { splitBlockSentences } from "./rank.mjs";
+import { makeContentTokens } from "../prose.mjs";
 import { findActionPath, findReachableSet } from "../planning.mjs";
 import { requireInjected } from "./injected.mjs";
 
-// Same content-token filter group.mjs/rank.mjs apply to their own adjacency/ranking; not
-// exported from either, so replicated here rather than reached across files.
-const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
-
-/** tokenizeBlock(text), narrowed to real content tokens — see isContentToken above. */
-function makeContentTokens(tokenizeBlock) {
-  return (text) => tokenizeBlock(text).filter(isContentToken);
-}
-
 // Local copy of chat.mjs's private HAS_PROPERTY_PREDICATE constant — not exported, so callers
 // supply their own copy in the `helpers` bag resolveRelationChase expects.
 const HAS_PROPERTY_PREDICATE = "mgx:hasProperty";
@@ -54,13 +45,13 @@ function groupContentTokenSet(group, { contentTokens }) {
   return set;
 }
 
-/** Every sentence across a group's members, pre-split (rank.mjs's own splitSentences — reused
+/** Every sentence across a group's members, pre-split (rank.mjs's own splitBlockSentences — reused
  *  verbatim, no re-implementation), each carrying its own content-token set and negation flag
  *  — the exact per-sentence facts the contradicts test needs. */
 function sentencesOf(group, { contentTokens }) {
   const out = [];
   for (const m of group?.members || []) {
-    for (const sentence of splitSentences(m?.text || "")) {
+    for (const sentence of splitBlockSentences(m?.text || "")) {
       out.push({ sentence, tokens: new Set(contentTokens(sentence)), negated: sentenceIsNegated(sentence) });
     }
   }

package/src/domain/completions/rank.mjs

@@ -2,19 +2,12 @@
 // within a group.mjs group. Reuses memory/blocks.mjs's rankBlocks() (PageRank) and degreeOf()
 // (hub dampening) verbatim at sentence granularity, combined with group-scoped IDF the same
 // way retrieveBlocks() fuses relevance/centrality/hub-dampening into one score.
-// splitSentences() is a simple regex splitter.
+// splitBlockSentences() is a simple regex splitter.
 
-import { STOPWORDS } from "../prose.mjs";
+import { makeContentTokens } from "../prose.mjs";
+import { idfOver } from "../text-stats.mjs";
 import { requireInjected } from "./injected.mjs";
 
-// Same content-token filter group.mjs applies (not exported, so replicated here).
-const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
-
-/** tokenizeBlock(text), narrowed to real content tokens — see isContentToken above. */
-function makeContentTokens(tokenizeBlock) {
-  return (text) => tokenizeBlock(text).filter(isContentToken);
-}
-
 // Sentence boundary: a run of [.!?] followed by whitespace and an uppercase letter or digit
 // (no abbreviation dictionary).
 const SENTENCE_SPLIT_RE = /(?<=[.!?])\s+(?=[A-Z0-9])/;
@@ -25,7 +18,7 @@ const SENTENCE_SPLIT_RE = /(?<=[.!?])\s+(?=[A-Z0-9])/;
  * @param {string} text
  * @returns {string[]}
  */
-export function splitSentences(text) {
+export function splitBlockSentences(text) {
   const out = [];
   for (const rawLine of String(text || "").split("\n")) {
     const line = rawLine.trim();
@@ -66,7 +59,7 @@ export function rankSentences(group, { overlapMin, query = null, store } = {}) {
   // One entry per sentence, with a stable id for PageRank/degree/IDF keying.
   const sentences = [];
   for (const m of members) {
-    const parts = splitSentences(m?.text || "");
+    const parts = splitBlockSentences(m?.text || "");
     parts.forEach((sentence, i) => {
       sentences.push({ id: `${m.id}#${i}`, sentence, sourceBlockId: m.id });
     });
@@ -80,13 +73,7 @@ export function rankSentences(group, { overlapMin, query = null, store } = {}) {
   const degrees = degreeOf(tokensById, { overlapMin: edgeThreshold });
 
   // IDF scoped to THIS group's sentence set (df/N), not the whole corpus.
-  const ids = Object.keys(tokensById);
-  const N = ids.length;
-  const df = new Map();
-  for (const id of ids) {
-    for (const t of new Set(tokensById[id])) df.set(t, (df.get(t) || 0) + 1);
-  }
-  const idf = (t) => Math.log(1 + N / (1 + (df.get(t) || 0)));
+  const { idf } = idfOver(tokensById);
 
   const queryTokens = query ? new Set(contentTokens(query)) : null;
 

package/src/domain/grammar/lexicon-core.json

@@ -1,5 +1,5 @@
 {
-  "comment": "tmct's starter lexicon (ROADMAP Phase 2, item 2), now covering BOTH the original software domain and (PLAN_SEED.md, the default 'human-world' persona) everyday people/places/objects/nature/time/body/mind vocabulary. Every word the ACE-OWL sub-fragment parser (src/domain/grammar/ace.mjs) is allowed to understand is DECLARED here — tmct never guesses a word's category. Nouns may declare a possessive property typing ('data' or 'object', pattern 7) or an irregular 'plural' (WordNet-sourced human nouns like 'man'/'child' need this — the morphology fold only handles regular -s/-ies/-es endings); adjectives MUST declare a type ('subclass' forms a class, 'data' asserts a boolean-ish datatype property, pattern 8); verbs may declare a preposition ('depend' + 'on' → dependsOn). The human-domain additions are flat and simple (breadth over depth — no gender/kinship taxonomy, no formal role hierarchy), matching corpus/tier2/generate.mjs's CORPUSES.human.lexicon sub-key, which --verify drift-checks against. Extend via loadLexicon(extra) with this same shape.",
+  "comment": "tmct's starter lexicon, now covering BOTH the original software domain and the default 'human-world' persona's everyday people/places/objects/nature/time/body/mind vocabulary. Every word the ACE-OWL sub-fragment parser (src/domain/grammar/ace.mjs) is allowed to understand is DECLARED here — tmct never guesses a word's category. Nouns may declare a possessive property typing ('data' or 'object', pattern 7) or an irregular 'plural' (WordNet-sourced human nouns like 'man'/'child' need this — the morphology fold only handles regular -s/-ies/-es endings); adjectives MUST declare a type ('subclass' forms a class, 'data' asserts a boolean-ish datatype property, pattern 8); verbs may declare a preposition ('depend' + 'on' → dependsOn). The human-domain additions are flat and simple (breadth over depth — no gender/kinship taxonomy, no formal role hierarchy), matching corpus/tier2/generate.mjs's CORPUSES.human.lexicon sub-key, which --verify drift-checks against. Extend via loadLexicon(extra) with this same shape.",
   "nouns": {
     "module": {},
     "class": {},

package/src/domain/hash.mjs

@@ -1,13 +1,17 @@
-// hash.mjs — the single home for tmct's content-address contract: the FNV-1a
-// hash, the fact-term/predicate normalization, and the fact-id derivation.
+// hash.mjs — the single home for tmct's content-address contract: the hashes,
+// the fact-term/predicate normalization, and the fact-id derivation.
 //
-// FNV-1a 32-bit is deliberately home-grown: it must be synchronous, browser-safe,
-// dependency-free, and — critically — CROSS-VERSION STABLE, because fact ids are
-// content-addressed by it and a fact's id is its identity across the whole memory
-// graph. Every library candidate fails at least one of those; this eight-line
-// function fails none. Normalization lives beside it because it is PART of that
-// identity: the same (s, p, o) must normalize and hash to the same id from every
-// writer, so the whole contract has exactly one definition.
+// A fact's id is its identity across the whole memory graph, so its hash must be
+// synchronous, browser-safe, dependency-free, CROSS-VERSION STABLE, and wide
+// enough that two different facts do not land on one id. factIdFor derives the id
+// from a 64-bit truncation of SHA-256 (sha256Bytes below) for the width; 32-bit
+// FNV-1a is far too narrow for a graph of tens of thousands of facts. FNV-1a stays
+// home-grown for the narrower content addresses that do not need that width (the
+// paraphrase and answer-variant pools, per-URL web-Source ids, corpus dedupe).
+// Every library candidate fails at least one of the stability constraints; these
+// hand-rolled functions fail none. Normalization lives beside them because it is
+// PART of that identity: the same (s, p, o) must normalize and hash to the same id
+// from every writer, so the whole contract has exactly one definition.
 
 /** FNV-1a 32-bit. Returns the unsigned 32-bit integer (0 … 2^32−1). */
 export function fnv1a32(str) {
@@ -20,7 +24,8 @@ export function fnv1a32(str) {
 }
 
 /** FNV-1a 32-bit as a zero-padded 8-char hex string — the stable content-address
- *  used for fact ids (`fact:<hex>`). Same (s,p,o) → same id → upsert, never a dup. */
+ *  for the narrow, non-fact-id pools (paraphrase, per-URL web Source, corpus
+ *  dedupe). Fact ids use factIdFor's wider SHA-256 truncation, not this. */
 export function fnv1aHex(str) {
   return fnv1a32(str).toString(16).padStart(8, "0");
 }
@@ -82,6 +87,16 @@ export function sha256Bytes(str) {
   return out;
 }
 
+/** SHA-256 of a string truncated to `nBytes` leading bytes, as lowercase hex.
+ *  A fact id takes 8 bytes (64 bits): at 100,000 facts the chance of any two
+ *  colliding is ~2.7e-10, against ~100% for 32-bit FNV at the same size. */
+function sha256Hex(str, nBytes) {
+  const bytes = sha256Bytes(str);
+  let hex = "";
+  for (let i = 0; i < nBytes; i += 1) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
+
 const TEXT_CAP = 2000;   // an utterance's stored text (a whole answer fits; a pasted book doesn't)
 
 /** Whitespace-collapse + cap a stored text/predicate string. Every writer that
@@ -134,9 +149,17 @@ export function normFactPredicate(p) {
 }
 
 /** A Fact is content-addressed by its NUL-delimited (s, p, o) — NUL never
- *  occurs in a normalized term/predicate, so it's collision-proof unlike a
- *  space. Takes ALREADY-normalized parts; factIdForTriple normalizes first. */
-export const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
+ *  occurs in a normalized term/predicate, so the delimiter never collides
+ *  unlike a space. The hash is a 64-bit SHA-256 truncation (16 hex chars),
+ *  wide enough that distinct triples do not share an id at real corpus sizes.
+ *  Takes ALREADY-normalized parts; factIdForTriple normalizes first. */
+export const factIdFor = (s, p, o) => `fact:${sha256Hex(`${s}\0${p}\0${o}`, 8)}`;
+
+/** The pre-widening 32-bit fact id (FNV-1a, 8 hex). A store written before
+ *  factIdFor widened keys its Facts and their statedBy/derivedFrom edges by
+ *  this; adapters/memory/core.mjs recognises the old shape and migrates each
+ *  Fact onto its current factIdFor id on load. */
+export const legacyFactIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
 
 /** Content-address a fact's id from (subject, predicate, object) without
  *  writing it — same contract as factIdFor. Lets a caller (e.g.

package/src/domain/interpret/fuzzy.mjs

@@ -15,8 +15,13 @@ import collisionData from "../real-word-collisions.json" with { type: "json" };
 const NEVER_CANONICALIZE = ["used"];
 import { STOPWORDS } from "./normalize.mjs";
 
-// ---- bounded edit distance — hand-rolled Damerau-Levenshtein, bounded with an
-// early row-minimum exit ----
+// ---- bounded edit distance — Optimal String Alignment (a restricted
+// Damerau-Levenshtein: it allows adjacent transpositions but forbids editing any
+// substring twice, so editDistance("CA","ABC")=3 where true Damerau-Levenshtein
+// gives 2). The two-previous-rows recurrence (prev2) is OSA's; true DL needs a
+// full last-seen-position table. OSA is NOT a metric — it can violate the
+// triangle inequality. Bounded with an early row-minimum exit.
+// Damerau 1964 (CACM 7(3)); Levenshtein 1966 (Soviet Physics Doklady 10(8)). ----
 
 /** Distance between a and b, or max+1 as soon as it provably exceeds `max`. */
 export function editDistance(a, b, max) {

package/src/domain/interpret/normalize.mjs

@@ -154,6 +154,13 @@ const KNOW_WRAPPER_RE = /^do\s+you\s+know\s+(.+?)\??$/i;
 /** "i'd like to know <Q>" / "i want to know <Q>" -> "<Q>", same
  *  interrogative-remainder gate as KNOW_WRAPPER_RE. */
 const WANT_KNOW_WRAPPER_RE = /^i(?:'d|\s+would)?\s+(?:like|want|need)\s+to\s+know\s+(.+?)\??$/i;
+/** "i was wondering <Q>" / "i wondered <Q>" / "i'm curious <Q>" -> "<Q>", the
+ *  same wrapper family and the same interrogative-remainder gate. The modal
+ *  form ("could you tell me what a dog is") was already unwrapped; this one
+ *  states the wish rather than asking, which is how it fell through every
+ *  frame. The optional "if"/"whether"/"about" tail carries the same clause
+ *  MODAL_WRAPPER_RE's own remainder does. */
+const WONDERING_WRAPPER_RE = /^i(?:\s+was|\s+am|'m)?\s+(?:just\s+)?(?:wonder(?:ing|ed)|curious)(?:\s+(?:if|whether|about))?\s+(.+?)\??$/i;
 /** EMBEDDED-QUESTION DE-INVERSION: the wrappers above unwrap "could you
  *  tell me what a dog is" down to the embedded clause "what a dog is",
  *  which keeps declarative word order — nothing downstream parses it. Fold
@@ -214,6 +221,8 @@ export function applyPreambleFrames(text) {
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(WANT_KNOW_WRAPPER_RE);
     if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
+    m = q.match(WONDERING_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(EMBEDDED_WHATIS_RE);
     if (m) q = `what ${m[2].toLowerCase()} ${m[1].trim()}`;
     m = q.match(EMBEDDED_MEANS_RE);

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

@@ -177,14 +177,23 @@ export function parseKeywordSpot(text, nlp = null) {
     if (objText) return stamp({ shape: "whoLast", entityType: null, modifier: "direct", kind: "touches", object: objText });
   }
 
-  // Reversible passive ("PATIENT is VERBed BY AGENT"): a passive auxiliary plus a
-  // standalone agent-marking "by" (not already swallowed into a multi-word verb
-  // phrase) splits the sentence into a patient before "by" and an agent after it.
-  // How many of the two the sentence actually names picks the shape: both named
-  // is the yes/no ask, agent alone reads forward from the agent, patient alone
-  // reads reverse over the patient.
+  // Reversible passive: a passive auxiliary plus a standalone agent-marking "by"
+  // (not already swallowed into a multi-word verb phrase) splits the sentence
+  // into a patient role and an agent role. How many of the two the sentence
+  // actually names picks the shape: both named is the yes/no ask, agent alone
+  // reads forward from the agent, patient alone reads reverse over the patient.
+  //
+  // The auxiliary's side of "by" says which role sits where. "X is imported BY
+  // Y" postposes the agent, so the aux comes first and the patient leads. "BY
+  // which modules is X imported" fronts it, so "by" comes first and the roles
+  // are mirrored: the agent runs from "by" up to the auxiliary, and the patient
+  // follows. Reading a fronted sentence on the postposed partition finds nothing
+  // before "by", takes the patient for the agent, and answers the reverse of the
+  // question asked.
   const byIdx = lcWords.indexOf("by");
-  const hasPassiveAux = lcWords.slice(0, verbHit.start).some((w) => PASSIVE_AUX.has(w));
+  const passiveAuxIdx = lcWords.slice(0, verbHit.start).findIndex((w) => PASSIVE_AUX.has(w));
+  const hasPassiveAux = passiveAuxIdx >= 0;
+  const agentIsFronted = hasPassiveAux && passiveAuxIdx > byIdx;
   if (byIdx >= 0 && !consumed.has(byIdx) && hasPassiveAux) {
     const roleText = (from, to) => words
       .slice(from, to)
@@ -196,8 +205,9 @@ export function parseKeywordSpot(text, nlp = null) {
       })
       .join(" ")
       .trim();
-    const patient = roleText(0, byIdx);
-    const agent = roleText(byIdx + 1, words.length);
+    const [patient, agent] = agentIsFronted
+      ? [roleText(passiveAuxIdx + 1, words.length), roleText(byIdx + 1, passiveAuxIdx)]
+      : [roleText(0, byIdx), roleText(byIdx + 1, words.length)];
     if (patient && agent) return stamp({ shape: "ask", entityType: null, modifier: "direct", kind, subject: agent, object: patient });
     if (agent) return stamp({ shape: "forward", entityType, modifier, kind, object: agent });
     if (patient) return stamp({ shape: "reverse", entityType, modifier, kind, object: patient });

package/src/domain/memory/capability.mjs

@@ -29,19 +29,38 @@ import { findIsaChain, SUBCLASS_PREDICATE, TYPE_PREDICATE } from "../syllogise.m
 export const NEG_PREDICATE_PREFIX = "mgxneg:";
 const POSITIVE_PREDICATE_PREFIX = "mgx:";
 
-/** Swap an mgx: predicate onto its negative twin. Applied AFTER the preposition
+/** The negative twin of rdfs:subClassOf ("john is not a man"). The polarity
+ *  prefix is tmct's; the term it negates is RDFS's, so this pair cannot be
+ *  minted by the prefix swap below and is stated instead.
+ *
+ *  Why a coined mgxneg: term and not owl:disjointWith: disjointness is a
+ *  class-class axiom ("no man is a stone"), and the ask ladder already reads it
+ *  that way. "john is not a man" denies ONE membership and says nothing about
+ *  any other john, so storing it as disjointness would over-claim. */
+export const NEG_SUBCLASS_PREDICATE = "mgxneg:subClassOf";
+const EXPLICIT_NEGATIVE_TWINS = new Map([[SUBCLASS_PREDICATE, NEG_SUBCLASS_PREDICATE]]);
+const EXPLICIT_POSITIVE_TWINS = new Map([...EXPLICIT_NEGATIVE_TWINS].map(([pos, neg]) => [neg, pos]));
+
+/** Swap a predicate onto its negative twin. Applied AFTER the preposition
  *  fold, so mgx:rest-on becomes mgxneg:rest-on and the object keeps nothing
- *  meaning-bearing inside it. */
+ *  meaning-bearing inside it. A predicate with no negative twin returns
+ *  unchanged. */
 export function negatedPredicate(predicate) {
   const p = String(predicate || "");
+  const stated = EXPLICIT_NEGATIVE_TWINS.get(p);
+  if (stated) return stated;
   if (!p.startsWith(POSITIVE_PREDICATE_PREFIX)) return p;
   return NEG_PREDICATE_PREFIX + p.slice(POSITIVE_PREDICATE_PREFIX.length);
 }
 
 /** The inverse: mgxneg:capableOf -> mgx:capableOf, or null for any predicate
- *  that isn't negative at all. */
+ *  that isn't negative at all. The stated twins invert by lookup — a prefix
+ *  swap would read mgxneg:subClassOf back as "mgx:subClassOf", a term that
+ *  exists nowhere. */
 export function positivePredicate(predicate) {
   const p = String(predicate || "");
+  const stated = EXPLICIT_POSITIVE_TWINS.get(p);
+  if (stated) return stated;
   if (!p.startsWith(NEG_PREDICATE_PREFIX)) return null;
   return POSITIVE_PREDICATE_PREFIX + p.slice(NEG_PREDICATE_PREFIX.length);
 }