@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.2

package/src/{completions → domain/completions}/infer.mjs

@@ -1,5 +1,5 @@
-// completions/infer.mjs — Stage 3 ("inference between groups"): applies resolveRelationChase
-// (src/memory/core.mjs) to relationships BETWEEN retrieved text groups, not just graph facts.
+// completions/infer.mjs — Stage 3 ("inference between groups"): applies the injected
+// resolveRelationChase to relationships BETWEEN retrieved text groups, not just graph facts.
 // Four relations (supports/contradicts/elaborates/exemplifies), each with its own named
 // licensing test — see the four test*() functions below. A relation is asserted only when its
 // test concretely licenses it, never from prose similarity.
@@ -7,18 +7,18 @@
 // 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 { normFactTerm, readFactRows, resolveRelationChase } from "../memory/core.mjs";
-import { tokenizeBlock } from "../memory/blocks.mjs";
 import { splitSentences } from "./rank.mjs";
 import { STOPWORDS } 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 contentTokens(text) {
-  return tokenizeBlock(text).filter(isContentToken);
+function makeContentTokens(tokenizeBlock) {
+  return (text) => tokenizeBlock(text).filter(isContentToken);
 }
 
 // Local copy of chat.mjs's private HAS_PROPERTY_PREDICATE constant — not exported, so callers
@@ -46,7 +46,7 @@ function sentenceIsNegated(sentence) {
 
 /** Union of contentTokens() over every member's text — a group's own content-token
  *  vocabulary, deduped. */
-function groupContentTokenSet(group) {
+function groupContentTokenSet(group, { contentTokens }) {
   const set = new Set();
   for (const m of group?.members || []) {
     for (const t of contentTokens(m?.text || "")) set.add(t);
@@ -57,7 +57,7 @@ function groupContentTokenSet(group) {
 /** Every sentence across a group's members, pre-split (rank.mjs's own splitSentences — 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) {
+function sentencesOf(group, { contentTokens }) {
   const out = [];
   for (const m of group?.members || []) {
     for (const sentence of splitSentences(m?.text || "")) {
@@ -69,7 +69,7 @@ function sentencesOf(group) {
 
 /** Every normFactTerm-normalized term that appears as SOME fact's subject or object in the
  *  loaded memory — the "graph-known term" universe entities are grounded against. */
-function buildGraphTerms(rows) {
+function buildGraphTerms(rows, normFactTerm) {
   const set = new Set();
   for (const r of rows) {
     const s = normFactTerm(r.subject);
@@ -81,8 +81,8 @@ function buildGraphTerms(rows) {
 }
 
 /** A group's GRAPH-GROUNDED entities: content tokens narrowed to graph-known terms, sorted. */
-function entitiesOf(group, graphTerms) {
-  return [...groupContentTokenSet(group)].filter((t) => graphTerms.has(t)).sort();
+function entitiesOf(group, grounding) {
+  return [...groupContentTokenSet(group, grounding)].filter((t) => grounding.graphTerms.has(t)).sort();
 }
 
 /** A minimal relationFactsFor(name): direct-predicate match only (`mgx:${name}`), no
@@ -104,6 +104,8 @@ function makeHelpers(rows) {
     byTrust: (a, b) => (b.trust ?? 0) - (a.trust ?? 0),
     rows,
     HAS_PROPERTY_PREDICATE,
+    findActionPath,
+    findReachableSet,
   };
 }
 
@@ -122,9 +124,10 @@ function relationNameCandidates(rows) {
 /** SUPPORTS — groups A/B share >=2 graph-grounded entities AND a taught relation fact
  *  connects two of them. Tries every (subject, object) pair against every candidate relation
  *  name in fixed sorted order; first hit wins. Returns `{ licensingTest, evidence }` or null. */
-async function testSupports(a, b, memory, helpers, relationNames, graphTerms) {
-  const entitiesA = entitiesOf(a, graphTerms);
-  const entitiesB = entitiesOf(b, graphTerms);
+async function testSupports(a, b, grounding) {
+  const { memory, helpers, relationNames, resolveRelationChase } = grounding;
+  const entitiesA = entitiesOf(a, grounding);
+  const entitiesB = entitiesOf(b, grounding);
   const shared = entitiesA.filter((e) => entitiesB.includes(e));
   if (shared.length < 2) return null;
   for (const subjectTerm of shared) {
@@ -148,18 +151,18 @@ async function testSupports(a, b, memory, helpers, relationNames, graphTerms) {
 /** CONTRADICTS — groups A/B share a graph-grounded entity plus a second co-occurring token
  *  ("aspect"), and one side's matching sentence is negated while the other's isn't. Returns
  *  `{ licensingTest, evidence }` or null. */
-function testContradicts(a, b, graphTerms) {
-  const entitiesA = entitiesOf(a, graphTerms);
-  const entitiesB = entitiesOf(b, graphTerms);
+function testContradicts(a, b, grounding) {
+  const entitiesA = entitiesOf(a, grounding);
+  const entitiesB = entitiesOf(b, grounding);
   const sharedEntities = entitiesA.filter((e) => entitiesB.includes(e));
   if (!sharedEntities.length) return null;
 
-  const tokensA = groupContentTokenSet(a);
-  const tokensB = groupContentTokenSet(b);
+  const tokensA = groupContentTokenSet(a, grounding);
+  const tokensB = groupContentTokenSet(b, grounding);
   const sharedTokens = [...tokensA].filter((t) => tokensB.has(t)).sort();
 
-  const sentencesA = sentencesOf(a);
-  const sentencesB = sentencesOf(b);
+  const sentencesA = sentencesOf(a, grounding);
+  const sentencesB = sentencesOf(b, grounding);
 
   for (const entity of sharedEntities) {
     for (const aspect of sharedTokens) {
@@ -205,9 +208,9 @@ function isProperSubset(small, big) {
 /** ELABORATES — one group's graph-grounded entity set is a PROPER SUBSET of the other's; the
  *  wider group elaborates the narrower one. Equal sets never count. Returns
  *  `{ wider: "a"|"b", licensingTest, evidence }` or null. */
-function testElaborates(a, b, graphTerms) {
-  const entitiesA = new Set(entitiesOf(a, graphTerms));
-  const entitiesB = new Set(entitiesOf(b, graphTerms));
+function testElaborates(a, b, grounding) {
+  const entitiesA = new Set(entitiesOf(a, grounding));
+  const entitiesB = new Set(entitiesOf(b, grounding));
   if (!entitiesA.size || !entitiesB.size) return null;
   if (isProperSubset(entitiesB, entitiesA)) {
     return {
@@ -230,9 +233,10 @@ function testElaborates(a, b, graphTerms) {
  *  `instance` names an entity taught to BE one directly. Asymmetric: callers probe both
  *  directions by calling this twice with groups swapped (see inferRelations below). Returns
  *  `{ licensingTest, evidence }` or null. */
-function testExemplifies(general, instance, rows, graphTerms) {
-  const generalEntities = entitiesOf(general, graphTerms);
-  const instanceEntities = entitiesOf(instance, graphTerms);
+function testExemplifies(general, instance, grounding) {
+  const { rows, normFactTerm } = grounding;
+  const generalEntities = entitiesOf(general, grounding);
+  const instanceEntities = entitiesOf(instance, grounding);
   for (const gA of generalEntities) {
     const isClass = rows.some((r) => ISA_PREDICATES.has(r.predicate) && normFactTerm(r.object) === gA);
     if (!isClass) continue;
@@ -257,20 +261,34 @@ function testExemplifies(general, instance, rows, graphTerms) {
  * closed relations and includes a hit only when its test function fires.
  *
  * @param {Array<{id:string, members:Array<{id:string,text:string}>}>} groups
- * @param {object} memory  an already-loaded memory/core.mjs loadMemory() payload
- * @param {object} [opts]  reserved for future tuning; unused today
+ * @param {object} memory  an already-loaded loadMemory() payload
+ * @param {object} [opts]
+ * @param {object} opts.store  REQUIRED — the memory store's `{ readFactRows, normFactTerm,
+ *   resolveRelationChase }` readers plus the block store's `{ tokenizeBlock }` helper
  * @returns {Promise<Array<{from:string, to:string, relation:"supports"|"contradicts"|"elaborates"|"exemplifies", licensingTest:string, evidence:object}>>}
  *   deterministic: id-sorted pairwise order, stable-sorted by (from, to, relation).
  */
-// eslint-disable-next-line no-unused-vars -- opts reserved, see docblock
-export async function inferRelations(groups, memory, opts = {}) {
+export async function inferRelations(groups, memory, { store } = {}) {
+  const { readFactRows, normFactTerm, resolveRelationChase, tokenizeBlock } = requireInjected(
+    store, ["readFactRows", "normFactTerm", "resolveRelationChase", "tokenizeBlock"],
+    { caller: "inferRelations", option: "store" },
+  );
   const list = Array.isArray(groups) ? groups.filter((g) => g && g.id && Array.isArray(g.members)) : [];
   if (list.length < 2) return [];
 
   const rows = readFactRows(memory);
-  const graphTerms = buildGraphTerms(rows);
-  const helpers = makeHelpers(rows);
-  const relationNames = relationNameCandidates(rows);
+  // Everything the four licensing tests read, resolved once per call: the injected store
+  // handles, the loaded fact rows, and the indexes derived from them.
+  const grounding = {
+    memory,
+    rows,
+    normFactTerm,
+    resolveRelationChase,
+    contentTokens: makeContentTokens(tokenizeBlock),
+    graphTerms: buildGraphTerms(rows, normFactTerm),
+    helpers: makeHelpers(rows),
+    relationNames: relationNameCandidates(rows),
+  };
 
   const sorted = list.slice().sort((x, y) => x.id.localeCompare(y.id));
   const out = [];
@@ -281,13 +299,13 @@ export async function inferRelations(groups, memory, opts = {}) {
       const B = sorted[j];
 
       // eslint-disable-next-line no-await-in-loop -- deterministic fixed-order pairwise search
-      const sup = await testSupports(A, B, memory, helpers, relationNames, graphTerms);
+      const sup = await testSupports(A, B, grounding);
       if (sup) out.push({ from: A.id, to: B.id, relation: "supports", licensingTest: sup.licensingTest, evidence: sup.evidence });
 
-      const con = testContradicts(A, B, graphTerms);
+      const con = testContradicts(A, B, grounding);
       if (con) out.push({ from: A.id, to: B.id, relation: "contradicts", licensingTest: con.licensingTest, evidence: con.evidence });
 
-      const ela = testElaborates(A, B, graphTerms);
+      const ela = testElaborates(A, B, grounding);
       if (ela) {
         const from = ela.wider === "a" ? A.id : B.id;
         const to = ela.wider === "a" ? B.id : A.id;
@@ -295,9 +313,9 @@ export async function inferRelations(groups, memory, opts = {}) {
       }
 
       // Both directions probed independently — different claims, each its own test.
-      const bExemplifiesA = testExemplifies(A, B, rows, graphTerms);
+      const bExemplifiesA = testExemplifies(A, B, grounding);
       if (bExemplifiesA) out.push({ from: B.id, to: A.id, relation: "exemplifies", licensingTest: bExemplifiesA.licensingTest, evidence: bExemplifiesA.evidence });
-      const aExemplifiesB = testExemplifies(B, A, rows, graphTerms);
+      const aExemplifiesB = testExemplifies(B, A, grounding);
       if (aExemplifiesB) out.push({ from: A.id, to: B.id, relation: "exemplifies", licensingTest: aExemplifiesB.licensingTest, evidence: aExemplifiesB.evidence });
     }
   }

package/src/domain/completions/injected.mjs

@@ -0,0 +1,21 @@
+// completions/injected.mjs — the construction check every stage in this directory runs on
+// the handles its caller passes in. The stages are pure: they read the memory store and the
+// prose finisher through an explicit options bag, never by importing either. A missing
+// handle is a loud construction error, never a silent no-op stage.
+
+/**
+ * @param {object} bag  the caller-supplied handle bag (e.g. opts.store)
+ * @param {string[]} needed  the names the caller must supply
+ * @param {{caller: string, option: string}} where  the stage's name, and the option the bag
+ *   arrives on — both quoted back in the error so a miswired call names itself
+ * @returns {object} `bag`, once every name is present
+ */
+export function requireInjected(bag, needed, { caller, option }) {
+  const missing = needed.filter((name) => bag?.[name] === undefined);
+  if (missing.length) {
+    throw new TypeError(
+      `${caller} needs a \`${option}\` option carrying { ${needed.join(", ")} } — missing ${missing.join(", ")}`,
+    );
+  }
+  return bag;
+}

package/src/{completions → domain/completions}/rank.mjs

@@ -4,15 +4,15 @@
 // way retrieveBlocks() fuses relevance/centrality/hub-dampening into one score.
 // splitSentences() is a simple regex splitter.
 
-import { degreeOf, rankBlocks, tokenizeBlock, OVERLAP_MIN } from "../memory/blocks.mjs";
 import { STOPWORDS } from "../prose.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 contentTokens(text) {
-  return tokenizeBlock(text).filter(isContentToken);
+function makeContentTokens(tokenizeBlock) {
+  return (text) => tokenizeBlock(text).filter(isContentToken);
 }
 
 // Sentence boundary: a run of [.!?] followed by whitespace and an uppercase letter or digit
@@ -46,13 +46,20 @@ export function splitSentences(text) {
  *
  * @param {{members: Array<{id:string, text:string}>}} group  a group.mjs groupHits() entry
  * @param {object} [opts]
- * @param {number} [opts.overlapMin=OVERLAP_MIN]  shared content-token threshold for a
- *   sentence-similarity edge
+ * @param {number} [opts.overlapMin]  shared content-token threshold for a sentence-similarity
+ *   edge; defaults to the store's own OVERLAP_MIN
  * @param {string|null} [opts.query=null]  optional query text to focus ranking on
+ * @param {object} opts.store  REQUIRED — the block store's `{ degreeOf, rankBlocks,
+ *   tokenizeBlock, OVERLAP_MIN }` ranking handles
  * @returns {Array<{sentence:string, score:number, sourceBlockId:string}>} best-first;
  *   deterministic tiebreak (sourceBlockId, then sentence text) on equal score.
  */
-export function rankSentences(group, { overlapMin = OVERLAP_MIN, query = null } = {}) {
+export function rankSentences(group, { overlapMin, query = null, store } = {}) {
+  const { degreeOf, rankBlocks, tokenizeBlock, OVERLAP_MIN } = requireInjected(
+    store, ["degreeOf", "rankBlocks", "tokenizeBlock", "OVERLAP_MIN"], { caller: "rankSentences", option: "store" },
+  );
+  const contentTokens = makeContentTokens(tokenizeBlock);
+  const edgeThreshold = overlapMin ?? OVERLAP_MIN;
   const members = Array.isArray(group?.members) ? group.members : [];
   if (!members.length) return [];
 
@@ -69,8 +76,8 @@ export function rankSentences(group, { overlapMin = OVERLAP_MIN, query = null }
   const tokensById = {};
   for (const s of sentences) tokensById[s.id] = contentTokens(s.sentence);
 
-  const ranks = rankBlocks(tokensById, { overlapMin });
-  const degrees = degreeOf(tokensById, { overlapMin });
+  const ranks = rankBlocks(tokensById, { overlapMin: edgeThreshold });
+  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);

package/src/{completions → domain/completions}/search.mjs

@@ -2,7 +2,7 @@
 // and the graph search()/ask() services, asking both sources more widely than a single-answer
 // query. Returns whole-block/whole-result hits only — no sub-block span segmentation.
 
-import { retrieveBlocks } from "../memory/blocks.mjs";
+import { requireInjected } from "./injected.mjs";
 
 const DEFAULT_BLOCK_K = 8;   // "broad" > chat's narrow single-answer k (typically 3)
 const DEFAULT_GRAPH_LIMIT = 8;
@@ -20,14 +20,16 @@ const DEFAULT_GRAPH_LIMIT = 8;
  *   (e.g. createGraphService(graph)). When supplied, its search() and ask() are queried too;
  *   omitted -> block-only search.
  * @param {number} [opts.graphLimit=8]  graph search()'s result limit
+ * @param {object} opts.store  REQUIRED — the block store's `{ retrieveBlocks }` reader
  * @returns {Promise<Array<{source:"block"|"graph-search"|"graph-ask", id:string, text:string, score:number}>>}
  *   best-first within each source; blocks first, then graph-search, then graph-ask (never
  *   shuffled/merged by score across sources — block scores and graph relevance aren't
  *   comparable).
  */
 export async function broadSearch(dir, query, {
-  blockK = DEFAULT_BLOCK_K, graphService = null, graphLimit = DEFAULT_GRAPH_LIMIT,
+  blockK = DEFAULT_BLOCK_K, graphService = null, graphLimit = DEFAULT_GRAPH_LIMIT, store,
 } = {}) {
+  const { retrieveBlocks } = requireInjected(store, ["retrieveBlocks"], { caller: "broadSearch", option: "store" });
   const q = String(query || "").trim();
   if (!q) return [];
 

package/src/{grammar → domain/grammar}/ace.mjs

@@ -3,14 +3,14 @@
 // docs/references/schemas/ace-owl-fragment.md and nothing more: fitting the
 // grammar is a strong signal, missing it is a FEATURE — parseAce returns null
 // (or an empty-triples result carrying the unknown words as `residue`) and the
-// interpretation pipeline (src/interpret/) falls through to the tolerant
+// interpretation pipeline (src/domain/interpret/) falls through to the tolerant
 // strategies. No NLP dependency: tokenization is whitespace + trailing
 // punctuation, morphology is the lexicon's suffix fold.
 //
 // parseAce(sentence, lexicon) → { pattern, triples, residue } | null
 //   pattern  one of the PATTERNS below (also exported individually).
 //   triples  [{ subject, predicate, object, kind, n? }] — OWL-labelled string
-//            triples shaped for src/memory/core.mjs's appendFact (which
+//            triples shaped for src/adapters/memory/core.mjs's appendFact (which
 //            normalizes subject/object via normFactTerm: "tmct:module" is
 //            stored as "module"; the predicate keeps its vocabulary casing).
 //   residue  [] on a clean parse; the unknown tokens when the sentence FITS a
@@ -56,7 +56,7 @@ export const PATTERNS = Object.freeze([
 const DET = new Set(["a", "an", "the"]);
 // A token SHAPED like a code reference (a path, file, symbol or CURIE) is an
 // individual by form — a deterministic tokenizer rule, not a guess: declared
-// proper names cover words; this covers chat.mjs, src/ask.mjs, Foo#bar.
+// proper names cover words; this covers chat.mjs, src/domain/ask.mjs, Foo#bar.
 const CODE_REF = /[./\\#:@]/;
 
 /** Whitespace tokenizer: curly quotes normalized, commas/semicolons dropped,

package/src/{grammar → domain/grammar}/assert.mjs

@@ -1,6 +1,7 @@
 // grammar/assert.mjs — the grammar→memory bridge: parseAce a sentence and land
-// every emitted triple in tmct's OWN memory graph via memory/core.mjs's
-// appendFact.
+// every emitted triple in tmct's OWN memory graph via an INJECTED appendFact
+// (memory/core.mjs's, in the live wiring — the grammar never imports the
+// store).
 //
 // appendFact normalizes each triple's subject/object through normFactTerm
 // (tmct:Legacy-module → "legacy-module"; the predicate keeps its vocabulary
@@ -10,7 +11,6 @@
 // ("ace:chat:<sessionId>@<ts>"); core.mjs unions tags "|"-joined when several
 // writers assert the same fact.
 
-import { appendFact } from "../memory/core.mjs";
 import { parseAce } from "./ace.mjs";
 import { loadLexicon } from "./lexicon.mjs";
 
@@ -21,11 +21,15 @@ export function provenanceTag({ source = "chat", sessionId = "", ts = "" } = {})
 }
 
 /** Parse `sentence` against the ACE-OWL sub-fragment and append every emitted
- *  triple to the memory graph under `dir`. Returns the parse result extended
- *  with `ids` (one fact id per triple, same order) and the provenance tag —
- *  or null (grammar miss, nothing written), or the residue parse (unknown
- *  words: triples empty, ids empty, nothing written). */
-export async function assertSentence(dir, sentence, { lexicon, provenance } = {}) {
+ *  triple to the memory graph under `dir`, via the REQUIRED injected
+ *  `appendFact` (memory/core.mjs's, in the live wiring). Returns the parse
+ *  result extended with `ids` (one fact id per triple, same order) and the
+ *  provenance tag — or null (grammar miss, nothing written), or the residue
+ *  parse (unknown words: triples empty, ids empty, nothing written). */
+export async function assertSentence(dir, sentence, { lexicon, provenance, appendFact } = {}) {
+  if (typeof appendFact !== "function") {
+    throw new TypeError("assertSentence needs an appendFact option (memory/core.mjs's writer) — the grammar never imports the store");
+  }
   const parse = parseAce(sentence, lexicon ?? loadLexicon());
   if (!parse) return null;
   const tag = provenanceTag(provenance);

package/src/{grammar → 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/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 (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.",
   "nouns": {
     "module": {},
     "class": {},

package/src/{grammar → domain/grammar}/lexicon.mjs

@@ -20,11 +20,9 @@
 // irregular `plural` ("indices"). Anything the fold can't reach is simply not
 // in the lexicon — honest, not clever.
 
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const CORE_FILE = join(dirname(fileURLToPath(import.meta.url)), "lexicon-core.json");
+// The core vocabulary rides in as a JSON module — declarative data, no
+// filesystem read at import or call time, and the browser bundler inlines it.
+import coreLexiconRaw from "./lexicon-core.json" with { type: "json" };
 
 /** The CURIE namespace every tmct lexicon mints terms under. */
 export const DEFAULT_NS = "tmct:";
@@ -133,7 +131,7 @@ const coreCacheByNs = new Map();
  *  cached per-ns (the JSON is committed, immutable at runtime). */
 export function loadLexicon(extra, ns = DEFAULT_NS) {
   if (!extra && coreCacheByNs.has(ns)) return coreCacheByNs.get(ns);
-  const raw = JSON.parse(readFileSync(CORE_FILE, "utf8"));
+  const raw = coreLexiconRaw;
   const lex = {
     nouns: new Map(),
     nounPlurals: new Map(),

package/src/domain/hash.mjs

@@ -0,0 +1,147 @@
+// 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.
+//
+// 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.
+
+/** FNV-1a 32-bit. Returns the unsigned 32-bit integer (0 … 2^32−1). */
+export function fnv1a32(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** 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. */
+export function fnv1aHex(str) {
+  return fnv1a32(str).toString(16).padStart(8, "0");
+}
+
+// SHA-256 (FIPS 180-4), home-grown for the same reasons FNV-1a is: it must be
+// synchronous, browser-safe, dependency-free, and cross-version stable —
+// answer-variant selection is keyed on digest bytes, so the digest is part of
+// the answer-text contract. Pinned byte-identical to node:crypto by
+// test/adapters/hash-digest.test.mjs.
+const SHA256_K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+/** SHA-256 of a string (UTF-8), as a 32-byte Uint8Array. */
+export function sha256Bytes(str) {
+  const data = new TextEncoder().encode(String(str));
+  const bitLen = data.length * 8;
+  const padded = new Uint8Array((((data.length + 8) >> 6) + 1) << 6);
+  padded.set(data);
+  padded[data.length] = 0x80;
+  const dv = new DataView(padded.buffer);
+  dv.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+  dv.setUint32(padded.length - 4, bitLen >>> 0);
+
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const w = new Uint32Array(64);
+  const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = dv.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i += 1) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i += 1) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + SHA256_K[i] + w[i]) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      hh = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0; h[1] = (h[1] + b) >>> 0; h[2] = (h[2] + c) >>> 0; h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0; h[5] = (h[5] + f) >>> 0; h[6] = (h[6] + g) >>> 0; h[7] = (h[7] + hh) >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const ov = new DataView(out.buffer);
+  for (let i = 0; i < 8; i += 1) ov.setUint32(i * 4, h[i]);
+  return out;
+}
+
+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
+ *  feeds the fact-id hash uses THIS normalization, so id identity never depends
+ *  on which module did the writing. */
+export const normText = (t) => String(t ?? "").replace(/\s+/g, " ").trim().slice(0, TEXT_CAP);
+
+/** Normalize a fact TERM (subject/object) so every writer converges on one
+ *  spelling: ConceptNet's /c/en/foo_bar, tmct:Foo_bar, and bare "Foo bar" all
+ *  become "foo bar". Also strips a leading "the"/"a"/"an" (idempotent — safe
+ *  for storage too). The predicate is never normalized this way — its casing
+ *  is meaningful controlled vocabulary. */
+export function normFactTerm(t) {
+  let s = normText(t);
+  s = s.replace(/^\/c\/[a-z]{2,3}\//i, "");
+  s = s.replace(/^[a-z][\w.-]*:/i, "");
+  s = s.replace(/_/g, " ").replace(/\s+/g, " ").trim();
+  s = s.replace(/^(?:the|an?)\s+/i, "");
+  return s.toLowerCase();
+}
+
+/** The closed taught→corpus predicate table. The teach lane mints a predicate
+ *  from the verb's LEMMA ("fire causes smoke" → mgx:cause), while the corpus
+ *  vocabulary spells the same relation in its curated form (mgx:causes). Left
+ *  apart, a taught fact and the corpus fact for the same triple are two facts
+ *  with two ids, and neither reader finds the other's. Each row below folds a
+ *  minted lemma onto the curated predicate that means the SAME thing in the
+ *  SAME direction, so both spellings converge on one fact id.
+ *
+ *  Closed on purpose — a table, not an inflection rule. Entries are added when
+ *  a curated predicate's surface phrase is a plain verb ("causes", "wants",
+ *  "requires", "involves") whose lemma the teach lane would otherwise mint
+ *  unrelated. Relations that invert their arguments (mgx:ownedBy,
+ *  mgx:createdBy) are absent: "X owns Y" and "X is owned by Y" are not the
+ *  same fact, so folding them would store a lie. */
+const CANONICAL_FACT_PREDICATE = new Map([
+  ["mgx:cause", "mgx:causes"],
+  ["mgx:desire", "mgx:desires"],
+  ["mgx:want", "mgx:desires"],
+  ["mgx:require", "mgx:hasPrerequisite"],
+  ["mgx:involve", "mgx:hasSubevent"],
+]);
+
+/** Normalize a fact PREDICATE: whitespace-collapse + cap (normText's storage
+ *  contract), then fold a minted lemma onto its curated corpus spelling. Casing
+ *  is left alone — a predicate is controlled vocabulary, not a term. */
+export function normFactPredicate(p) {
+  const t = normText(p);
+  return CANONICAL_FACT_PREDICATE.get(t) ?? t;
+}
+
+/** 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}`)}`;
+
+/** Content-address a fact's id from (subject, predicate, object) without
+ *  writing it — same contract as factIdFor. Lets a caller (e.g.
+ *  syllogise.mjs's retraction machinery) name a not-yet-written fact's id
+ *  deterministically, without an extra read. Pure, no I/O. */
+export function factIdForTriple(subject, predicate, object) {
+  return factIdFor(normFactTerm(subject), normFactPredicate(predicate), normFactTerm(object));
+}

package/src/{interpret → domain/interpret}/fuzzy.mjs

@@ -3,6 +3,16 @@
 // refused or surfaced as ambiguity, never broken by a guess.
 
 import { VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND } from "../ask-vocab.mjs";
+import collisionData from "../real-word-collisions.json" with { type: "json" };
+
+/** Words the LEMMA pass must leave alone even though no parse table spells them.
+ *  "used" reads as vocabulary, not as a relation: "what is it used for" asks the
+ *  corpus what a thing is FOR, and the lemma tier would otherwise walk it through
+ *  "use" to the graph verb "uses" and answer a question about imports and calls
+ *  instead. The active verb table deliberately has no bare "used" for the same
+ *  reason. The fuzzy tier reaches "used" too, by one edit, and the collision
+ *  table below holds it off there — "used" is real English, so no repair applies. */
+const NEVER_CANONICALIZE = ["used"];
 import { STOPWORDS } from "./normalize.mjs";
 
 // ---- bounded edit distance — hand-rolled Damerau-Levenshtein, bounded with an
@@ -38,19 +48,40 @@ export const fuzzyBound = (s) => (s.length <= 5 ? 1 : 2);
  *  already vocabulary?" gate for the lemma/fuzzy canonicalization passes (an
  *  exact vocab word is NEVER rewritten: exact curated match always wins). */
 export const VOCAB_WORDS = new Set(
-  [...Object.keys(VERB_TO_KIND), ...Object.keys(ENTITY_TO_TYPE), ...Object.keys(MODIFIER_TO_KIND)]
+  [...Object.keys(VERB_TO_KIND), ...Object.keys(ENTITY_TO_TYPE), ...Object.keys(MODIFIER_TO_KIND),
+    ...NEVER_CANONICALIZE]
     .flatMap((p) => p.split(" ")),
 );
 
+/** Below this length the edit budget covers half of English, so the repair tier
+ *  ignores shorter words entirely ("and" is one edit from the "land in"
+ *  constituent). Shared with the generator that builds the collision table, so
+ *  both agree on which words the tier can ever reach. */
+export const FUZZY_REPAIR_MIN_LENGTH = 4;
+
 /** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only,
  *  length ≥4. Entity nouns and short words are excluded — real identifiers
  *  collide with them too easily at this distance bound. */
-const FUZZY_TARGET_WORDS = [...new Set(
+export const FUZZY_TARGET_WORDS = [...new Set(
   [...Object.keys(VERB_TO_KIND), ...Object.keys(MODIFIER_TO_KIND)]
     .flatMap((p) => p.split(" "))
-    .filter((w) => w.length >= 4),
+    .filter((w) => w.length >= FUZZY_REPAIR_MIN_LENGTH),
 )];
 
+/** Real English words the repair tier would otherwise rewrite onto a graph verb
+ *  ("rest" -> "test", "during" -> "using", "bigger" -> "trigger"). Generated
+ *  offline from this repo's own WordNet corpus by
+ *  scripts/generate-real-word-collisions.mjs and committed, so the check is a
+ *  closed table lookup with no dictionary to carry at runtime. */
+const REAL_WORD_COLLISIONS = new Set(collisionData.words);
+
+/** Is `w` a real English word that the repair tier attracts? A word already in
+ *  the language is not a typo, so no repair applies to it — the sentence means
+ *  what it says, and if we don't record that relation the honest answer is a
+ *  miss. Only the words the tier could actually reach are tabled; anything else
+ *  never gets this far. */
+export const isRealEnglishWord = (w) => REAL_WORD_COLLISIONS.has(w);
+
 /** A query word may be canonicalized only if it is plain alphabetic, not a
  *  stopword, and not already vocabulary. Dotted/digit terms (file names, shas)
  *  are never touched. */
@@ -60,8 +91,15 @@ export function eligibleForCanon(w) {
 
 /** UNIQUE within-bound fuzzy vocab keyword for `w`, or null — a tie between two
  *  distinct target words at the same distance is refused outright (the honest-miss
- *  discipline at the vocabulary level; cf. MISSPELLINGS' curated "calss" decision). */
+ *  discipline at the vocabulary level; cf. MISSPELLINGS' curated "calss" decision).
+ *
+ *  This tier repairs TYPOS. A word that is already real English is not a typo,
+ *  so it is refused before the distance is even measured: "does store.mjs rest
+ *  on app.mjs" asks about resting, and rewriting it to "tests" answers a
+ *  question nobody asked. A word outside the language ("impotr") has no such
+ *  claim, and the repair is the whole point. */
 export function fuzzyVocabWord(w) {
+  if (isRealEnglishWord(w)) return null;
   return fuzzyMatchInSet(w, FUZZY_TARGET_WORDS, fuzzyBound(w));
 }