@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.4.0

package/src/grammar/lexicon.mjs

@@ -0,0 +1,202 @@
+// grammar/lexicon.mjs — the declared lexicon behind tmct's ACE-OWL sub-fragment
+// (ROADMAP Phase 2, item 2; docs/references/schemas/ace-owl-fragment.md).
+//
+// The lexicon is LOAD-BEARING: the grammar (grammar/ace.mjs) is only
+// deterministic because every noun, verb (with any preposition), adjective
+// (with its declared type) and proper name is DECLARED — tmct never guesses a
+// word's category. Undeclared words route a sentence out of the grammar
+// strategy (a miss is a feature: the interpretation pipeline falls through to
+// the tolerant strategies).
+//
+// Data lives in lexicon-core.json (plain, diffable — the item-4/7 format
+// discipline), a starter software-domain vocabulary. Callers extend it via
+// loadLexicon(extra) with the same JSON shape; user entries win on conflict.
+//
+// Morphology is deliberately tiny and deterministic (no NLP dependency): a
+// suffix-fold for plurals/3rd-person-singular ("repositories"→repository,
+// "relies"→rely, "classes"→class, "uses"→use) plus an optional declared
+// 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");
+
+/** Determiner tokens the grammar consumes (pattern table's every/a/no…). */
+export const DETERMINERS = Object.freeze({
+  every: "universal",
+  a: "indefinite",
+  an: "indefinite",
+  the: "definite",
+  no: "negative",
+});
+
+/** The cardinality quantifier phrases (pattern 5) → the OWL term they select. */
+export const QUANTIFIERS = Object.freeze({
+  "at least": "owl:minCardinality",
+  "at most": "owl:maxCardinality",
+  exactly: "owl:cardinality",
+});
+
+const NUMBER_WORDS = Object.freeze({
+  one: 1, two: 2, three: 3, four: 4, five: 5,
+  six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+});
+
+/** Parse a cardinality count token: a digit run or a small number word. */
+export function numberOf(word) {
+  const w = String(word ?? "").trim().toLowerCase();
+  if (/^\d+$/.test(w)) return Number(w);
+  return NUMBER_WORDS[w] ?? null;
+}
+
+/** 3rd-person-singular surface form of a verb lemma — the predicate spelling
+ *  ("import"→imports, "rely"→relies, "catch"→catches, "have"→has), matching
+ *  the code graph's 3sg relation-kind convention (ask.mjs §verbs). */
+export function thirdPerson(base) {
+  const b = String(base);
+  if (b === "have") return "has";
+  if (/[^aeiou]y$/.test(b)) return `${b.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(b)) return `${b}es`;
+  return `${b}s`;
+}
+
+/** The URI-style predicate a verb entry emits: a declared override, or
+ *  tmct:<3sg lemma> with any preposition camel-appended ("depend on"→tmct:dependsOn). */
+export function predicateOf(verbEntry) {
+  if (verbEntry.predicate) return verbEntry.predicate;
+  const prep = verbEntry.prep ? verbEntry.prep[0].toUpperCase() + verbEntry.prep.slice(1) : "";
+  return `tmct:${thirdPerson(verbEntry.lemma)}${prep}`;
+}
+
+/** Deterministic singular/base-form candidates for a surface word, most
+ *  specific first: as-is, -ies→y, -(s|x|z|ch|sh)es→stem, -s→stem. The FIRST
+ *  candidate found in the relevant map wins ("classes"→class before "classe";
+ *  "uses"→"us" misses, "use" hits). */
+function foldCandidates(word) {
+  const w = String(word);
+  const out = [w];
+  if (w.length > 4 && /[a-z]ies$/.test(w)) out.push(`${w.slice(0, -3)}y`);
+  if (/(ses|xes|zes|ches|shes)$/.test(w)) out.push(w.slice(0, -2));
+  if (/[a-z]s$/.test(w) && !/ss$/.test(w)) out.push(w.slice(0, -1));
+  if (w === "has") out.push("have");
+  return out;
+}
+
+const NOUN_PROPERTY_TYPES = new Set(["data", "object"]);
+const ADJECTIVE_TYPES = new Set(["subclass", "data"]);
+
+/** Merge one raw lexicon block ({nouns, verbs, adjectives, properNames}) into
+ *  the lookup maps, validating the declared typings (bad declarations throw —
+ *  a lexicon that lies would make the grammar guess). */
+function ingest(lex, raw = {}) {
+  for (const [lemma, e] of Object.entries(raw.nouns || {})) {
+    const entry = { lemma, ...(e || {}) };
+    if (entry.property && !NOUN_PROPERTY_TYPES.has(entry.property)) {
+      throw new Error(`lexicon noun "${lemma}": property must be "data" or "object", got ${JSON.stringify(entry.property)}`);
+    }
+    lex.nouns.set(lemma, entry);
+    if (entry.plural) lex.nounPlurals.set(entry.plural, lemma);
+  }
+  for (const [lemma, e] of Object.entries(raw.verbs || {})) {
+    lex.verbs.set(lemma, { lemma, ...(e || {}) });
+  }
+  for (const [lemma, e] of Object.entries(raw.adjectives || {})) {
+    const entry = { lemma, ...(e || {}) };
+    if (!ADJECTIVE_TYPES.has(entry.type)) {
+      throw new Error(`lexicon adjective "${lemma}": type must be "subclass" or "data", got ${JSON.stringify(entry.type)}`);
+    }
+    lex.adjectives.set(lemma, entry);
+  }
+  for (const name of raw.properNames || []) {
+    lex.properNames.set(String(name).toLowerCase(), String(name));
+  }
+}
+
+let coreCache = null;
+
+/** Load the lexicon: the committed core vocabulary, optionally merged with a
+ *  caller-supplied `extra` block of the same JSON shape (extra entries win).
+ *  The no-extra result is cached (the JSON is committed, immutable at runtime). */
+export function loadLexicon(extra) {
+  if (!extra && coreCache) return coreCache;
+  const raw = JSON.parse(readFileSync(CORE_FILE, "utf8"));
+  const lex = {
+    nouns: new Map(),
+    nounPlurals: new Map(),
+    verbs: new Map(),
+    adjectives: new Map(),
+    properNames: new Map(), // lowercased → canonical spelling
+  };
+  ingest(lex, raw);
+  if (extra) {
+    ingest(lex, extra);
+    return lex;
+  }
+  coreCache = lex;
+  return lex;
+}
+
+/** Noun lookup with plural folding; returns the entry ({lemma, property?}) or null. */
+export function lookupNoun(lexicon, word) {
+  const w = String(word ?? "").toLowerCase();
+  const irregular = lexicon.nounPlurals.get(w);
+  if (irregular) return lexicon.nouns.get(irregular) ?? null;
+  for (const cand of foldCandidates(w)) {
+    const hit = lexicon.nouns.get(cand);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Verb lookup with 3sg folding; returns the entry ({lemma, prep?, predicate?}) or null. */
+export function lookupVerb(lexicon, word) {
+  const w = String(word ?? "").toLowerCase();
+  for (const cand of foldCandidates(w)) {
+    const hit = lexicon.verbs.get(cand);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Adjective lookup (exact lemma); returns {lemma, type, property?, value?} or null. */
+export function lookupAdjective(lexicon, word) {
+  return lexicon.adjectives.get(String(word ?? "").toLowerCase()) ?? null;
+}
+
+/** Proper-name lookup, case-insensitive; returns the CANONICAL spelling or null. */
+export function lookupProperName(lexicon, word) {
+  return lexicon.properNames.get(String(word ?? "").toLowerCase()) ?? null;
+}
+
+/** Classify one word (or a two-word quantifier phrase) against the lexicon.
+ *  Returns {pos, type?, …} or null for an undeclared word. Priority when a
+ *  word is declared in several categories (e.g. "test" noun+verb): closed-class
+ *  tokens, then properName > noun > verb > adjective — the grammar itself
+ *  disambiguates by position, this is the standalone answer. */
+export function classify(word, lexicon = loadLexicon()) {
+  const w = String(word ?? "").trim();
+  if (!w) return null;
+  const lower = w.toLowerCase();
+  if (DETERMINERS[lower]) return { pos: "determiner", type: DETERMINERS[lower] };
+  if (QUANTIFIERS[lower]) return { pos: "quantifier", type: QUANTIFIERS[lower] };
+  const n = numberOf(lower);
+  if (n != null) return { pos: "number", type: "cardinal", value: n };
+  const proper = lookupProperName(lexicon, w);
+  if (proper) return { pos: "properName", type: "individual", canonical: proper };
+  const noun = lookupNoun(lexicon, lower);
+  if (noun) {
+    return noun.property
+      ? { pos: "noun", type: `${noun.property}-property`, lemma: noun.lemma, property: noun.property }
+      : { pos: "noun", type: "class", lemma: noun.lemma };
+  }
+  const verb = lookupVerb(lexicon, lower);
+  if (verb) {
+    return { pos: "verb", type: "objectProperty", lemma: verb.lemma, predicate: predicateOf(verb), ...(verb.prep ? { prep: verb.prep } : {}) };
+  }
+  const adj = lookupAdjective(lexicon, lower);
+  if (adj) return { pos: "adjective", type: adj.type, lemma: adj.lemma };
+  return null;
+}

package/src/hash.mjs

@@ -0,0 +1,32 @@
+// hash.mjs — the single home for tmct's content-address hash.
+//
+// FNV-1a 32-bit is deliberately home-grown (see PLAN_DEPENDENCY_STRATEGY.md): 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. It lives here, once,
+// so the fact-id contract has exactly one definition.
+//
+// Two historical copies are reconciled here without changing a single output byte:
+//   - src/memory/core.mjs used the hex form for fact ids;
+//   - chatbench/graded.mjs used the integer form as a PRNG seed, with a redundant
+//     mid-loop `>>> 0`. That `>>> 0` was always a no-op: `^` and Math.imul both
+//     apply ToInt32 to their operands, so the 32-bit pattern is invariant between
+//     iterations whether the accumulator is stored signed or unsigned. The final
+//     `h >>> 0` therefore yields the same value either way — proven, not assumed.
+
+/** 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");
+}

package/src/index.mjs

@@ -5,9 +5,10 @@
 // shape and its green test suite; the branding throughout is now `tmct`.
 //
 // This entry re-exports the adapter primitives a library consumer needs. The
-// clean chat/primitives split — pulling the movable grammar out of ask.mjs away
-// from the core primitives it currently shares a file with — is deferred to
-// ROADMAP.md.
+// clean chat/primitives split (ROADMAP item 13) is done: the movable
+// conversational grammar lives in src/interpret/ (normalization pre-pass, the
+// registered parsing strategies, the merge rule), while ask.mjs keeps the core
+// primitives (resolveObject, traverse, render) and the ask() orchestration.
 
 // Chat surface (also reachable as the `./chat` subpath export).
 export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
@@ -15,11 +16,26 @@ export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
 // Grammar / NL-over-graph primitives.
 export { ask, resolveObject } from "./ask.mjs";
 
+// The interpretation pipeline (ROADMAP item 8): normalize once, run every
+// registered strategy (grammar, keyword-spot, …) over the text, merge same-class
+// results, surround distinct-class results — no graph access; pair it with ask()
+// or the primitives to answer. `interpret(text, ctx)` returns the full record
+// ({raw, normalized, normalizationChanged, results, parsed, class, alternates}).
+export { interpret } from "./interpret/pipeline.mjs";
+
 // Graph traversal primitives.
 export { relationKind, impactClosure } from "./codegraph.mjs";
 
 // Tool dispatch (slash-commands and CLI tool calls route through here).
 export { dispatchTool } from "./server.mjs";
 
-// The single graph-load choke point — the adapter's data-provider seam.
-export { fetchEntities } from "./source.mjs";
+// Conversational memory (ROADMAP item 9) — tmct's OWN OWL-labelled graph under
+// .tmct/memory/, distinct from any provider-supplied code graph.
+export { loadMemory, appendUtterance, appendFact } from "./memory/core.mjs";
+export { retrieveBlocks, saveBlock, rankBlocks } from "./memory/blocks.mjs";
+export { foldSessionLogs } from "./memory/fold.mjs";
+
+// The single graph-load choke point — the adapter's data-provider seam
+// (docs/adapter-contract.md): registerProvider() plugs a producer in;
+// fetchEntities() is the one read path.
+export { fetchEntities, registerProvider } from "./source.mjs";

package/src/init.mjs

@@ -0,0 +1,264 @@
+// init.mjs — `tmct init`: the interface's onboarding surface.
+//
+// One command takes a bare directory (a user's repo, or a host package such as
+// seonix) to a WORKING tmct install: it creates the `.tmct/` artifact tree,
+// writes an externalised `tmct.toml` (the seonix.toml documented-config pattern),
+// seeds the committed tier-1 corpus into memory, and records provenance of what
+// it did. See ROADMAP Phase 8 ("Distribution: tmct init") and the Phase-4
+// corpus-tiering policy.
+//
+//   initRepo(dir, { force?, seed?, env? }) → { created, config, seeded, ... }
+//
+// DESIGN RULES (load-bearing):
+//   - OFFLINE, DETERMINISTIC, $0. The seed is the tier-1 committed ConceptNet
+//     slice already in the tarball — no network, ever. The $0-offline default is
+//     inviolable (ROADMAP Phase 4); tiers 2-3 are additive config, never run here.
+//   - IDEMPOTENT and NON-DESTRUCTIVE. Safe to re-run. A benign re-init NEVER
+//     throws — it returns an honest result whose `message` says nothing changed.
+//     Existing `tmct.toml` and an existing seed are preserved unless `force`.
+//   - FAILURE-TOLERANT SEED. A missing/broken corpus degrades to an unseeded (but
+//     still initialised) repo — the directory scaffold and config always land.
+//
+// The seed marker + limit + prefer mirror src/chat.mjs's W3 bootstrap
+// (SEED_MARKER_REL / SEED_LIMIT / SEED_PREFER) ON PURPOSE: both write the same
+// `.tmct/memory/corpus-seed.json`, so whichever of `tmct init` and first-run
+// bootstrap happens first wins and the other short-circuits. They are re-declared
+// here (not imported) to keep init off chat.mjs's heavy module graph.
+
+import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CONFIG_FILE = "tmct.toml";
+export const PROVENANCE_REL = join(".tmct", "init.json");
+export const MEMORY_DIR_REL = join(".tmct", "memory");
+export const SESSIONS_DIR_REL = join(".tmct", "sessions");
+export const SEED_MARKER_REL = join(".tmct", "memory", "corpus-seed.json");
+
+/** How many corpus facts the seed writes — matches chat.mjs SEED_LIMIT so an
+ *  init-seeded repo and a bootstrap-seeded repo carry the identical slice. */
+export const SEED_LIMIT = 500;
+
+/** Predicate preference for the capped seed (definitional band first) — matches
+ *  chat.mjs SEED_PREFER so "what is a cache?" answers land in the first 500. */
+export const SEED_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:partOf", "mgx:capableOf"];
+
+/** The shipped default config — the exact shape written into `tmct.toml` and
+ *  echoed back in the result's `config`. Absent file ⇒ these values apply. */
+export function defaultConfig() {
+  return {
+    graphFile: join(".tmct", "graph.json"),
+    corpus: { tier: "tier1" },
+    seed: { enabled: true, limit: SEED_LIMIT },
+  };
+}
+
+/** Read this package's version (best-effort, for provenance). */
+async function tmctVersion() {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    return pkg.version || null;
+  } catch {
+    return null;
+  }
+}
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Render the documented, commented `tmct.toml` for a config object. Hand-written
+ *  (not smol-toml stringify) so every key ships with the prose that makes the file
+ *  a self-explaining config surface — the seonix.toml pattern. The output parses
+ *  back cleanly through toml-config.mjs's loadTomlConfig. */
+export function renderTomlConfig(config = defaultConfig()) {
+  const c = { ...defaultConfig(), ...config };
+  const corpus = { ...defaultConfig().corpus, ...(config.corpus || {}) };
+  const seed = { ...defaultConfig().seed, ...(config.seed || {}) };
+  return `# tmct.toml — the mechanical code talker, project configuration.
+# Written by \`tmct init\`. An ABSENT file means shipped defaults (this file
+# just makes them explicit and editable). Documented in the repository-interface
+# onboarding surface (ROADMAP Phase 8, "Distribution: tmct init").
+
+# Where the code-graph JSON artifact lives, relative to this file. The
+# TMCT_GRAPH_FILE environment variable overrides it at runtime.
+graph_file = ${JSON.stringify(c.graphFile)}
+
+[corpus]
+# Corpus-tiering policy (ROADMAP Phase 4). The $0-offline default is inviolable;
+# higher tiers are ADDITIVE and never required to answer.
+#   "tier1" — committed slice only. Offline, $0. The default.
+#   "tier2" — also fetch growable corpora at seed time (network, once, cached).
+#   "tier3" — also consult live sources at question time (network, per-query, opt-in).
+tier = ${JSON.stringify(corpus.tier)}
+
+[seed]
+# Seed the committed tier-1 ConceptNet slice into .tmct/memory during init.
+# Offline and deterministic. Set false, or export TMCT_NO_SEED=1, to opt out —
+# the repo still initialises, just empty of corpus facts.
+enabled = ${seed.enabled ? "true" : "false"}
+# How many facts the seed writes (definitional band first).
+limit = ${Number(seed.limit)}
+`;
+}
+
+/** Should the seed run? Explicit `opts.seed` wins; otherwise the config's
+ *  `seed.enabled`; and TMCT_NO_SEED=<non-empty> is a hard veto over both (the
+ *  documented environment opt-out, honoured even when config says enabled). */
+function seedRequested({ optSeed, configEnabled, env }) {
+  const noSeed = env && String(env.TMCT_NO_SEED || "").trim();
+  if (noSeed) return false;
+  if (optSeed !== undefined) return Boolean(optSeed);
+  return Boolean(configEnabled);
+}
+
+/**
+ * Initialise `dir` for tmct. Idempotent, non-destructive, offline.
+ *
+ * @param {string} dir  target directory (a repo root, or a host package root).
+ * @param {object} [opts]
+ * @param {boolean} [opts.force]  re-write tmct.toml + re-record provenance even
+ *   when the repo is already initialised (never deletes memory/seed data).
+ * @param {boolean} [opts.seed]   force seeding on/off, overriding tmct.toml's
+ *   `seed.enabled` (TMCT_NO_SEED still vetoes).
+ * @param {object}  [opts.env]    environment (for TMCT_NO_SEED); defaults to
+ *   process.env.
+ * @returns {Promise<{
+ *   created: string[], config: object, seeded: boolean,
+ *   alreadyInitialized: boolean, seedResult: (object|null), message: string
+ * }>} `created` lists the ABSOLUTE paths this call brought into being (empty on a
+ *   benign no-op re-init). Never throws on a benign re-init or a corpus failure.
+ */
+export async function initRepo(dir, { force = false, seed, env = process.env } = {}) {
+  const root = resolve(dir);
+  const created = [];
+  const paths = {
+    tmct: join(root, ".tmct"),
+    memory: join(root, MEMORY_DIR_REL),
+    sessions: join(root, SESSIONS_DIR_REL),
+    toml: join(root, CONFIG_FILE),
+    provenance: join(root, PROVENANCE_REL),
+    marker: join(root, SEED_MARKER_REL),
+  };
+
+  const wasInitialized = await exists(paths.provenance);
+
+  // ---- 1. The artifact directory scaffold (always idempotent) ----
+  for (const d of [paths.tmct, paths.memory, paths.sessions]) {
+    if (!(await exists(d))) {
+      await mkdir(d, { recursive: true });
+      created.push(d);
+    }
+  }
+
+  // ---- 2. The externalised config (preserve an existing file unless force) ----
+  let config = defaultConfig();
+  const tomlPresent = await exists(paths.toml);
+  if (!tomlPresent || force) {
+    await writeFile(paths.toml, renderTomlConfig(config));
+    if (!tomlPresent) created.push(paths.toml);
+  } else {
+    // Honour the user's committed tmct.toml — read its knobs back so the returned
+    // config (and the seed decision) reflect what's actually on disk.
+    config = await readWrittenConfig(paths.toml, config);
+  }
+
+  // ---- 3. Seed the tier-1 committed corpus (offline, failure-tolerant) ----
+  let seeded = false;
+  let seedResult = null;
+  let seedNote = "";
+  const wantSeed = seedRequested({ optSeed: seed, configEnabled: config.seed?.enabled, env });
+  if (!wantSeed) {
+    seedNote = env && String(env.TMCT_NO_SEED || "").trim()
+      ? "seed skipped (TMCT_NO_SEED set)"
+      : "seed skipped (disabled)";
+  } else if ((await exists(paths.marker)) && !force) {
+    seedNote = "seed skipped (already seeded — marker present)";
+  } else {
+    try {
+      const { seedMemory } = await import("./corpus/conceptnet.mjs");
+      const limit = Number(config.seed?.limit) || SEED_LIMIT;
+      seedResult = await seedMemory(root, { limit, prefer: SEED_PREFER });
+      const markerNew = !(await exists(paths.marker));
+      await mkdir(dirname(paths.marker), { recursive: true });
+      await writeFile(
+        paths.marker,
+        JSON.stringify({
+          seededAt: new Date().toISOString(),
+          limit,
+          appended: seedResult.appended,
+          skipped: seedResult.skipped,
+        }) + "\n",
+      );
+      if (markerNew) created.push(paths.marker);
+      seeded = true;
+    } catch (err) {
+      // Corpus unavailable/broken → an initialised-but-unseeded repo, not a crash.
+      seedNote = `seed skipped (corpus unavailable: ${err && err.message ? err.message : err})`;
+    }
+  }
+
+  // ---- 4. Record provenance (what was created, when, by which version) ----
+  const provenanceNew = !(await exists(paths.provenance));
+  const provenance = {
+    tool: "tmct init",
+    tmctVersion: await tmctVersion(),
+    initializedAt: new Date().toISOString(),
+    dir: root,
+    config,
+    seeded,
+    seedResult,
+    created,
+  };
+  await writeFile(paths.provenance, JSON.stringify(provenance, null, 2) + "\n");
+  if (provenanceNew) created.push(paths.provenance);
+
+  const alreadyInitialized = wasInitialized && !force;
+  const message = buildMessage({ alreadyInitialized, force, created, seeded, seedNote, seedResult });
+
+  return { created, config, seeded, alreadyInitialized, seedResult, message };
+}
+
+/** Read a present tmct.toml back into the canonical config shape (so a re-init
+ *  respects the on-disk file). Falls back to `base` on any read/parse trouble —
+ *  init must never crash on a malformed user file; the runtime loader
+ *  (toml-config.mjs) is where a bad file surfaces its error. */
+async function readWrittenConfig(tomlPath, base) {
+  try {
+    const { loadTomlConfig } = await import("./toml-config.mjs");
+    const raw = await loadTomlConfig(dirname(tomlPath));
+    if (!raw) return base;
+    const cfg = { ...base };
+    if (raw.graph_file !== undefined) cfg.graphFile = String(raw.graph_file);
+    if (raw.corpus && raw.corpus.tier !== undefined) cfg.corpus = { ...cfg.corpus, tier: raw.corpus.tier };
+    if (raw.seed) {
+      cfg.seed = { ...cfg.seed };
+      if (raw.seed.enabled !== undefined) cfg.seed.enabled = Boolean(raw.seed.enabled);
+      if (raw.seed.limit !== undefined) cfg.seed.limit = Number(raw.seed.limit);
+    }
+    return cfg;
+  } catch {
+    return base;
+  }
+}
+
+function buildMessage({ alreadyInitialized, force, created, seeded, seedNote, seedResult }) {
+  if (alreadyInitialized && created.length === 0) {
+    return `Already initialized — nothing to do (re-run with force to rewrite tmct.toml). ${seedNote || ""}`.trim();
+  }
+  const parts = [];
+  parts.push(force && alreadyInitialized ? "Re-initialized" : "Initialized");
+  parts.push(`tmct here (${created.length} path${created.length === 1 ? "" : "s"} created).`);
+  if (seeded && seedResult) {
+    parts.push(`Seeded ${seedResult.appended} corpus fact${seedResult.appended === 1 ? "" : "s"} into memory.`);
+  } else if (seedNote) {
+    parts.push(seedNote + ".");
+  }
+  return parts.join(" ");
+}

package/src/interpret/fuzzy.mjs

@@ -0,0 +1,89 @@
+// interpret/fuzzy.mjs — the bounded-edit-distance fuzzy tier (two-level fuzzy,
+// 2026-07-02), extracted MOVE-only from ask.mjs (item 13). A reusable SERVICE the
+// strategies call, not a strategy itself: the keyword-spotting strategy's tier-3
+// vocabulary rewrite and resolveObject's tier-5 label pass both read editDistance/
+// fuzzyBound from here, and the "assuming you meant …" announcement discipline
+// (a unique within-bound hit is announced, a tie is refused or surfaced as
+// ambiguity, never a silently-broken guess) is enforced by the callers off these
+// primitives. Deliberately coupled to the curated vocab tables via explicit
+// imports — the fuzzy TARGETS are a closed, curated set, same ethos as the
+// tables themselves. Pure JS, no deps.
+
+import { VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND } from "../ask-vocab.mjs";
+import { STOPWORDS } from "./normalize.mjs";
+
+// ---- bounded edit distance — hand-rolled Damerau-Levenshtein (optimal string
+// alignment: substitution/insertion/deletion + adjacent transposition), bounded
+// with an early row-minimum exit. Fires only after every exact/curated tier
+// missed, and a distance TIE is refused (keyword) or surfaced as ambiguity
+// (object), never broken by a guess. ----
+
+/** Distance between a and b, or max+1 as soon as it provably exceeds `max`. */
+export function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev2 = null;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    const cur = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) v = Math.min(v, prev2[j - 2] + cost);
+      cur[j] = v;
+      if (v < rowMin) rowMin = v;
+    }
+    if (rowMin > max) return max + 1;
+    prev2 = prev;
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** The curated distance budget: 1 edit for short tokens, 2 for longer ones. */
+export const fuzzyBound = (s) => (s.length <= 5 ? 1 : 2);
+
+/** Every single word appearing in the three parse tables — the "is this word
+ *  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)]
+    .flatMap((p) => p.split(" ")),
+);
+
+/** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only, length ≥4.
+ *  Entity nouns are deliberately excluded — real identifiers collide with them at
+ *  distance ≤2 far too easily ("myfile" is 2 edits from "file", "caller" 2 from
+ *  "calls"-family words), and entity-noun typos are already owned by the curated
+ *  MISSPELLINGS table where such calls are made deliberately. Short constituents
+ *  ("of", "to", "in", "on") are excluded for the same reason: at bound 1 half of
+ *  English is adjacent to them. */
+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),
+)];
+
+/** 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. */
+export function eligibleForCanon(w) {
+  return /^[a-z]+$/.test(w) && !STOPWORDS.has(w) && !VOCAB_WORDS.has(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). */
+export function fuzzyVocabWord(w) {
+  const bound = fuzzyBound(w);
+  let best = bound + 1;
+  let hit = null;
+  let tied = false;
+  for (const target of FUZZY_TARGET_WORDS) {
+    const d = editDistance(w, target, Math.min(best, bound));
+    if (d < best) { best = d; hit = target; tied = false; }
+    else if (d === best && d <= bound && target !== hit) tied = true;
+  }
+  return best <= bound && !tied ? hit : null;
+}