@polycode-projects/the-mechanical-code-talker 2.9.0 → 2.9.4

package/corpus/worlds/manifest.json

@@ -3,7 +3,7 @@
   "generated": "by scripts/build-worlds-pack.mjs from corpus/worlds/src/",
   "counts": {
     "worlds": 2,
-    "facts": 528,
+    "facts": 548,
     "rules": 19
   },
   "budgets": {
@@ -14,13 +14,13 @@
   "sources": [
     {
       "file": "src/ashcombe-hall.jsonl",
-      "bytes": 8458,
-      "sha256": "79332b0700a8c8289ca4d8b5a9cf3dcff4c869fb1b45a72dd291617f61bdd184"
+      "bytes": 8795,
+      "sha256": "771ed4e7a5e9046235e8dc193b2696f83e6ef92a556ca1ca126dd070927912ce"
     },
     {
       "file": "src/spider-fly.jsonl",
-      "bytes": 51706,
-      "sha256": "b641936dec8fb3526dcab766268c25942c0e82ff9025bb853dad5f971bf8c029"
+      "bytes": 53693,
+      "sha256": "879c45652d0636c27f937e809e9883d0039b20fdc11032ac2040894d08c6a0a4"
     }
   ],
   "files": [
@@ -31,13 +31,13 @@
     },
     {
       "file": "shards/ashcombe-hall.jsonl.gz",
-      "bytes": 963,
-      "sha256": "d44e229d8f30dc43e8801443d426c315b43a6758adb11ad332c84e7108268746"
+      "bytes": 1020,
+      "sha256": "1255ea52149c3941fafd4ee462239bae8e10175c8e7db2e54c2c2dc1a2e0d924"
     },
     {
       "file": "shards/spider-fly.jsonl.gz",
-      "bytes": 2829,
-      "sha256": "dd9f1ac66b26da2cea350fdeab17e1fe0f27d583823356e3bc189c131e3adb86"
+      "bytes": 3156,
+      "sha256": "3e55614801471186b06a9514d5534ac14050663ec00e27dc0618eb97319d516f"
     }
   ]
 }

package/corpus/worlds/src/ashcombe-hall.jsonl

@@ -51,6 +51,9 @@
 {"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:works-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:works-in","object":"drawing-room"}
 {"world":"ashcombe-hall","kind":"fact","subject":"gardener","predicate":"mgx:works-in","object":"garden"}
+{"world":"ashcombe-hall","kind":"fact","subject":"ashcombe hall","predicate":"mgx:hasA","object":"6 rooms"}
+{"world":"ashcombe-hall","kind":"fact","subject":"player","predicate":"mgx:hasA","object":"satchel"}
+{"world":"ashcombe-hall","kind":"fact","subject":"satchel","predicate":"mgx:usedFor","object":"carrying what the player takes"}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-signature","slots":{"subjectClass":"adventurer","targetClass":"room"}}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-signature","slots":{"subjectClass":"person","targetClass":"room"}}
 {"world":"ashcombe-hall","kind":"rule","name":"go","ruleKind":"action-effect","slots":{"predicate":"currently-in","subjectRole":"subject","objectRole":"target"}}

package/corpus/worlds/src/spider-fly.jsonl

@@ -475,5 +475,22 @@
 {"world":"spider-fly","kind":"fact","subject":"arachnid","predicate":"rdfs:subClassOf","object":"animal"}
 {"world":"spider-fly","kind":"fact","subject":"fly","predicate":"rdfs:subClassOf","object":"insect"}
 {"world":"spider-fly","kind":"fact","subject":"insect","predicate":"rdfs:subClassOf","object":"animal"}
+{"world":"spider-fly","kind":"fact","subject":"board","predicate":"rdf:type","object":"grid"}
+{"world":"spider-fly","kind":"fact","subject":"board","predicate":"mgx:hasA","object":"10 rows"}
+{"world":"spider-fly","kind":"fact","subject":"board","predicate":"mgx:hasA","object":"10 columns"}
+{"world":"spider-fly","kind":"fact","subject":"board","predicate":"mgx:hasA","object":"100 cells"}
+{"world":"spider-fly","kind":"fact","subject":"web","predicate":"mgx:cover","object":"9 cells around cell-2-2"}
+{"world":"spider-fly","kind":"fact","subject":"web","predicate":"mgx:last-for","object":"10 turns by default when a spider builds one"}
+{"world":"spider-fly","kind":"fact","subject":"spider","predicate":"mgx:hasA","object":"vision radius of 4 cells by default"}
+{"world":"spider-fly","kind":"fact","subject":"spider","predicate":"mgx:start-with","object":"mass 15 by default"}
+{"world":"spider-fly","kind":"fact","subject":"spider","predicate":"mgx:lose","object":"0.5 mass per turn by default"}
+{"world":"spider-fly","kind":"fact","subject":"spider","predicate":"mgx:lay","object":"one egg at mass 25 by default"}
+{"world":"spider-fly","kind":"fact","subject":"fly","predicate":"mgx:hasA","object":"vision radius of 4 cells by default"}
+{"world":"spider-fly","kind":"fact","subject":"fly","predicate":"mgx:start-with","object":"mass 10 by default"}
+{"world":"spider-fly","kind":"fact","subject":"fly","predicate":"mgx:lose","object":"1 mass per turn by default"}
+{"world":"spider-fly","kind":"fact","subject":"fly","predicate":"mgx:arrive","object":"every 3 turns at the edge of the board by default"}
+{"world":"spider-fly","kind":"fact","subject":"egg","predicate":"mgx:hatch-after","object":"3 turns by default"}
+{"world":"spider-fly","kind":"fact","subject":"egg","predicate":"mgx:hatch-into","object":"2 spiders by default"}
+{"world":"spider-fly","kind":"fact","subject":"vision radius","predicate":"mgx:hasProperty","object":"4 cells for both the spider and the fly by default"}
 {"world":"spider-fly","kind":"rule","name":"go","ruleKind":"action-signature","slots":{"subjectClass":"spider","targetClass":"cell"}}
 {"world":"spider-fly","kind":"rule","name":"go","ruleKind":"action-effect","slots":{"predicate":"currently-in","subjectRole":"subject","objectRole":"target"}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.9.0",
+  "version": "2.9.4",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -81,11 +81,11 @@
     "wink-nlp": "^2.4.0"
   },
   "scripts": {
-    "help": "node bin/tmct.mjs --help",
-    "test": "node --test --test-concurrency=8 \"test/**/*.test.mjs\"",
-    "test:smoke": "node --test test/smoke/*.test.mjs",
-    "test:fast": "node --test --test-concurrency=8 test/smoke/*.test.mjs test/fast/*.test.mjs test/tools/ask.test.mjs test/tools/server.test.mjs test/estate/import-layers.test.mjs",
-    "test:e2e": "node --test \"e2e/**/*.test.mjs\"",
+    "help": "node --disable-warning=ExperimentalWarning bin/tmct.mjs --help",
+    "test": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 \"test/**/*.test.mjs\"",
+    "test:smoke": "node --disable-warning=ExperimentalWarning --test test/smoke/*.test.mjs",
+    "test:fast": "node --disable-warning=ExperimentalWarning --test --test-concurrency=8 test/smoke/*.test.mjs test/fast/*.test.mjs test/tools/ask.test.mjs test/tools/server.test.mjs test/estate/import-layers.test.mjs",
+    "test:e2e": "node --disable-warning=ExperimentalWarning --test \"e2e/**/*.test.mjs\"",
     "e2e:browsers": "playwright install chromium",
     "check:links": "node scripts/check-links.mjs",
     "check:pii": "node scripts/pii-lint.mjs",
@@ -97,32 +97,32 @@
     "check:publish": "node scripts/check-publish.mjs",
     "check:all": "npm run check:links && npm run check:pii && npm run check:licences && npm run check:publint && npm run check:tool-docs && npm run check:budgets",
     "smoke:deploy": "node scripts/post-deploy-smoke.mjs",
-    "chat": "node bin/tmct.mjs",
-    "chat:repo": "node bin/tmct.mjs chat --repo",
-    "chat:plain": "node bin/tmct.mjs chat --plain",
-    "chat:narrate": "node bin/tmct.mjs chat --narrate",
-    "init": "node bin/tmct.mjs init",
-    "init:sqlite": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --memory-backend sqlite",
-    "init:persona:human": "node bin/tmct.mjs init --with-persona human",
-    "init:persona:empty": "node bin/tmct.mjs init --with-persona empty",
-    "init:large": "node bin/tmct.mjs init && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java",
-    "init:xl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-xl",
-    "init:xxl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-full && node bin/tmct.mjs import --corpus namenet",
-    "memory": "node bin/tmct.mjs memory",
-    "memory:verbose": "node bin/tmct.mjs memory --verbose",
-    "syllogise": "node bin/tmct.mjs syllogise",
-    "viz": "node bin/tmct.mjs viz",
-    "viz:term": "node bin/tmct.mjs viz --term",
-    "plan": "node bin/tmct.mjs plan",
-    "plan:json": "node bin/tmct.mjs plan --json",
-    "cli": "node bin/tmct.mjs cli",
-    "cli:digest": "node bin/tmct.mjs cli digest",
-    "import": "node bin/tmct.mjs import",
-    "extend": "node bin/tmct.mjs extend --validate",
-    "serve": "node bin/tmct.mjs serve",
-    "serve:public": "node bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
-    "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
-    "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
+    "chat": "node --disable-warning=ExperimentalWarning bin/tmct.mjs",
+    "chat:repo": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo",
+    "chat:plain": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --plain",
+    "chat:narrate": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --narrate",
+    "init": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init",
+    "init:sqlite": "npm run init",
+    "init:persona:human": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --with-persona human",
+    "init:persona:empty": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --with-persona empty",
+    "init:large": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus seon && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus conceptnet && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus aws && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus python && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus java",
+    "init:xl": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --persona-size large && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus seon && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus conceptnet && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus aws && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus python && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus java && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus wordnet-xl",
+    "init:xxl": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --persona-size large && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus seon && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus conceptnet && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus aws && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus python && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus java && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus wordnet-full && node --disable-warning=ExperimentalWarning bin/tmct.mjs import --corpus namenet",
+    "memory": "node --disable-warning=ExperimentalWarning bin/tmct.mjs memory",
+    "memory:verbose": "node --disable-warning=ExperimentalWarning bin/tmct.mjs memory --verbose",
+    "syllogise": "node --disable-warning=ExperimentalWarning bin/tmct.mjs syllogise",
+    "viz": "node --disable-warning=ExperimentalWarning bin/tmct.mjs viz",
+    "viz:term": "node --disable-warning=ExperimentalWarning bin/tmct.mjs viz --term",
+    "plan": "node --disable-warning=ExperimentalWarning bin/tmct.mjs plan",
+    "plan:json": "node --disable-warning=ExperimentalWarning bin/tmct.mjs plan --json",
+    "cli": "node --disable-warning=ExperimentalWarning bin/tmct.mjs cli",
+    "cli:digest": "node --disable-warning=ExperimentalWarning bin/tmct.mjs cli digest",
+    "import": "node --disable-warning=ExperimentalWarning bin/tmct.mjs import",
+    "extend": "node --disable-warning=ExperimentalWarning bin/tmct.mjs extend --validate",
+    "serve": "node --disable-warning=ExperimentalWarning bin/tmct.mjs serve",
+    "serve:public": "node --disable-warning=ExperimentalWarning bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
+    "example:mini": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
+    "example:polyglot": "node --disable-warning=ExperimentalWarning bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
     "chatbench:run": "node chatbench/run.mjs",
     "chatbench:judge": "node chatbench/judge.mjs",
     "agentbench:run": "node agentbench/run.mjs",
@@ -139,11 +139,14 @@
     "build:spider-fly-bundle": "node scripts/build-spider-fly-bundle.mjs",
     "build:plan-bundle": "node scripts/build-plan-bundle.mjs",
     "build:ledger-bundle": "node scripts/build-ledger-bundle.mjs",
+    "build:sprites-bundle": "node scripts/build-sprites-bundle.mjs",
+    "build:wink-vendor": "node scripts/build-wink-vendor.mjs",
     "build:chat-seed": "node scripts/build-chat-seed.mjs",
     "build:demo-graph": "node scripts/build-demo-graph.mjs",
     "build:demo-pack": "node scripts/build-demo-pack.mjs",
     "build:demo-sprites-pack": "node scripts/build-demo-sprites-pack.mjs",
     "build:demo-memory": "node scripts/build-demo-memory.mjs",
+    "gen:sprite-facts": "node scripts/gen-sprite-facts.mjs",
     "gen:tool-docs": "node scripts/generate-tool-docs.mjs",
     "gen:collisions": "node scripts/generate-real-word-collisions.mjs",
     "gen:prose-corpus": "node scripts/fetch-prose-corpus.mjs",
@@ -152,8 +155,8 @@
     "measure:child-corpus": "node scripts/measure-child-corpus.mjs",
     "gen:variants": "node scripts/generate-template-variants.mjs",
     "gen:worlds-pack": "node scripts/build-worlds-pack.mjs",
-    "extract": "node bin/tmct.mjs extract",
-    "extract:facts": "node bin/tmct.mjs extract"
+    "extract": "node --disable-warning=ExperimentalWarning bin/tmct.mjs extract",
+    "extract:facts": "node --disable-warning=ExperimentalWarning bin/tmct.mjs extract"
   },
   "devDependencies": {
     "esbuild": "0.28.1",

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

@@ -0,0 +1,145 @@
+// corpus/wikipedia-live.mjs — the OPT-IN live Wikipedia lookup behind the
+// clean-miss gate: two small GET round trips against en.wikipedia.org (an
+// opensearch title match, then the REST page summary), mapped into the same
+// article-row shape the shipped reference pack uses. No node builtins — this
+// module ships in the browser bundle unchanged; the only I/O is fetch.
+//
+// Courtesy is structural, not advisory: one in-flight lookup at a time, a
+// minimum interval between network round trips, a 429 cool-off honouring
+// Retry-After, an abort timeout on every fetch, and a cache that keeps hits
+// AND misses so a term is never asked twice. Every failure of any kind reads
+// as null — the caller's honest miss stands byte-identical.
+//
+// The provider seam mirrors reference-pack.mjs's: registerLiveReferenceProvider
+// swaps the whole lookup behind one async { lookup(normTerm) } contract (tests
+// and the demo page stub it); null restores the default provider below.
+
+import { normFactTerm } from "../../domain/hash.mjs";
+import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
+import { isReferenceArticleRow, sentencesUpTo, isaOf, SUMMARY_CHAR_CAP } from "../../domain/reference-pack.mjs";
+
+export const WIKIPEDIA_LIVE_ORIGIN = "https://en.wikipedia.org";
+
+const DEFAULT_TIMEOUT_MS = 4000;
+const DEFAULT_MIN_INTERVAL_MS = 2000;
+const RETRY_AFTER_FLOOR_MS = 5000;
+
+/**
+ * A live-lookup provider: { lookup(normTerm) -> article row | null }.
+ *
+ * `fetchImpl` defaults to the global fetch; `origin` to en.wikipedia.org;
+ * `lexicon` (optional) feeds the isa extraction. The row shape is the shipped
+ * pack's own ({ term, title, text, summary, url, revid, isa? }), validated by
+ * isReferenceArticleRow before it is ever returned.
+ */
+export function createWikipediaLiveProvider({
+  fetchImpl,
+  origin = WIKIPEDIA_LIVE_ORIGIN,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
+  lexicon = null,
+} = {}) {
+  const doFetch = fetchImpl ?? ((...args) => globalThis.fetch(...args));
+  const cache = new Map(); // key -> row | null (hits AND settled misses)
+  let lastLookupAt = 0;
+  let coolOffUntil = 0;
+  let inFlight = false;
+
+  async function fetchJson(url) {
+    const controller = typeof AbortController === "function" ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+    try {
+      const res = await doFetch(url, controller ? { signal: controller.signal } : {});
+      if (res.status === 429) {
+        const retryAfterMs = Number(res.headers?.get?.("retry-after")) * 1000;
+        coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+        return null;
+      }
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    } finally {
+      if (timer !== null) clearTimeout(timer);
+    }
+  }
+
+  /** The opensearch title whose normFactTerm fold equals or extends the key —
+   *  the topic-drift guard: "quasar" may resolve to "Quasar" or "Quasars",
+   *  never to a first suggestion about something else. */
+  function matchingTitle(key, searchResult) {
+    const titles = Array.isArray(searchResult?.[1]) ? searchResult[1] : [];
+    for (const title of titles) {
+      const folded = normFactTerm(title);
+      if (folded === key || folded.startsWith(key)) return String(title);
+    }
+    return null;
+  }
+
+  async function roundTrips(key) {
+    const search = await fetchJson(
+      `${origin}/w/api.php?action=opensearch&format=json&origin=*&search=${encodeURIComponent(key)}&limit=3`,
+    );
+    const title = search ? matchingTitle(key, search) : null;
+    if (!title) return null;
+    const summary = await fetchJson(
+      `${origin}/api/rest_v1/page/summary/${encodeURIComponent(title.replace(/ /g, "_"))}`,
+    );
+    if (!summary) return null;
+    const extract = String(summary.extract ?? "");
+    const revid = Number(summary.revision);
+    const row = {
+      term: key,
+      title: String(summary.title ?? title),
+      text: extract,
+      summary: sentencesUpTo(extract, SUMMARY_CHAR_CAP),
+      url: String(summary.content_urls?.desktop?.page ?? `${origin}/wiki/${encodeURIComponent(title.replace(/ /g, "_"))}`),
+      revid,
+    };
+    let lex = lexicon;
+    if (!lex) { try { lex = loadLexicon(); } catch { lex = null; } }
+    const isa = lex ? isaOf(extract, lex) : null;
+    if (isa) row.isa = isa;
+    return isReferenceArticleRow(row) ? row : null;
+  }
+
+  return {
+    async lookup(normTerm) {
+      const key = String(normTerm ?? "");
+      if (!key) return null;
+      if (cache.has(key)) return cache.get(key);
+      const now = Date.now();
+      if (inFlight || now < coolOffUntil || now - lastLookupAt < minIntervalMs) return null;
+      lastLookupAt = now;
+      inFlight = true;
+      let row = null;
+      try {
+        row = await roundTrips(key);
+      } catch {
+        row = null;
+      } finally {
+        inFlight = false;
+      }
+      cache.set(key, row);
+      return row;
+    },
+  };
+}
+
+let defaultProvider = null;
+let registeredProvider = null;
+
+/** Swap the live lookup: provider = { lookup: async (normTerm) => row|null }.
+ *  Pass null to restore the default en.wikipedia.org provider. */
+export function registerLiveReferenceProvider(provider) {
+  registeredProvider = provider && typeof provider.lookup === "function" ? provider : null;
+}
+
+/** The active provider — the registered one, else one lazily created default
+ *  provider shared by every caller (its cache and throttle are what make the
+ *  lookup polite, so it must be a singleton). */
+export function getLiveReferenceProvider() {
+  if (registeredProvider) return registeredProvider;
+  if (!defaultProvider) defaultProvider = createWikipediaLiveProvider();
+  return defaultProvider;
+}

package/src/adapters/memory/core.mjs

@@ -1,6 +1,8 @@
 // memory/core.mjs — tmct's OWN conversational memory graph: a dedicated
-// OWL-labelled store at <repo>/.tmct/memory/graph.json, distinct from any
-// provider-supplied code graph. Utterances, Facts (reified RDF triples via
+// OWL-labelled store (routed default: the SQLite file at
+// <repo>/.tmct/memory/graph.sqlite; "memory" keeps it in-process; the
+// flat-JSON read/write path survives for callers holding a plain dir),
+// distinct from any provider-supplied code graph. Utterances, Facts (reified RDF triples via
 // appendFact), and Sessions are all typed twice — payload `class` and an
 // `rdf:type` attribute. Every append is crash-safe and idempotent (utterance
 // ids are deterministic, fact ids hash the triple).
@@ -12,7 +14,7 @@
 // systems toward triple terms) but does not deprecate. See
 // docs/references/schemas/rdf-reification-and-rdf-star.md.
 
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { proseTokensFor, buildProseIndex } from "../../domain/prose.mjs";
 import { fnv1aHex, normText, normFactTerm, normFactPredicate, factIdFor, factIdForTriple } from "../../domain/hash.mjs";
@@ -187,11 +189,29 @@ CREATE INDEX IF NOT EXISTS edges_by_prop ON edges(prop);
 // Edge keys with dedicated columns; any other key round-trips via `extra`.
 const STD_EDGE_KEYS = new Set(["subject", "object", "subjectLabel", "objectLabel"]);
 
+// node:sqlite still emits an ExperimentalWarning on first import. Using it is
+// this module's deliberate choice, so the warning is pure noise for every
+// consumer (library embedders, examples, bare `node` scripts) — swallow that
+// one warning here, once, and re-emit everything else untouched.
+let sqliteWarningFilterInstalled = false;
+function installSqliteWarningFilter() {
+  if (sqliteWarningFilterInstalled) return;
+  sqliteWarningFilterInstalled = true;
+  const prior = process.listeners("warning").slice();
+  process.removeAllListeners("warning");
+  process.on("warning", (warning) => {
+    if (warning?.name === "ExperimentalWarning" && /sqlite/i.test(String(warning?.message))) return;
+    if (prior.length) for (const l of prior) l(warning);
+    else console.error(warning.stack || String(warning));
+  });
+}
+
 /** Open (creating if absent) a resident node:sqlite connection: a Backend C
  *  handle `{ backend: "sqlite", db, dbPath }`. `node:sqlite` is imported
  *  lazily — only opting into this backend ever loads it. Meant to be opened
  *  once per session; close via closeSqliteMemoryStore at session end. */
 export async function createSqliteMemoryStore(dbPath) {
+  installSqliteWarningFilter();
   const { DatabaseSync } = await import("node:sqlite");
   const db = new DatabaseSync(dbPath);
   db.exec("PRAGMA journal_mode = WAL");
@@ -210,18 +230,37 @@ export function closeSqliteMemoryStore(handle) {
 /** Resolve a backend token ("memory" | "sqlite" | anything else) into
  *  `{ dir, close }` — the ONE shared resolver, so every entry point (init's
  *  corpus seed, bin/tmct.mjs, chat) picks the same backend for a repo rather
- *  than silently splitting its memory across two stores. */
+ *  than silently splitting its memory across two stores. The empty/"default"
+ *  token routes to the sqlite store: the flat-file Backend A is retired from
+ *  routing (loadMemory/persistMemory still honour a plain dir string for
+ *  callers that hold one directly). */
 export async function openMemoryBackend(repoRoot, backendChoice) {
   if (backendChoice === BACKEND_MEMORY) {
     return { dir: createInMemoryStore(), close: async () => {} };
   }
-  if (backendChoice === BACKEND_SQLITE) {
-    const dbPath = join(repoRoot, ".tmct", "memory", "graph.sqlite");
-    await mkdir(dirname(dbPath), { recursive: true });
-    const handle = await createSqliteMemoryStore(dbPath);
-    return { dir: handle, close: async () => closeSqliteMemoryStore(handle) };
+  const dbPath = join(repoRoot, ".tmct", "memory", "graph.sqlite");
+  const exists = (p) => access(p).then(() => true, () => false);
+  if (!(await exists(dbPath)) && (await exists(join(repoRoot, MEMORY_GRAPH_REL)))) {
+    process.stderr.write("found .tmct/memory/graph.json — the flat-file memory backend is retired; starting a fresh sqlite store (the old file is left untouched)\n");
+  }
+  await mkdir(dirname(dbPath), { recursive: true });
+  const handle = await createSqliteMemoryStore(dbPath);
+  return { dir: handle, close: async () => closeSqliteMemoryStore(handle) };
+}
+
+/** openMemoryBackend for an entry point that holds only a repo path and has no
+ *  CLI-flag tier (the fold's idle pass, `tmct import --file`): resolve the
+ *  backend token the way the chat path does minus the flag —
+ *  TMCT_MEMORY_BACKEND env > tmct.toml's [memory] backend > the default. */
+export async function openConfiguredMemoryBackend(repoRoot, env = process.env) {
+  let backend = String(env?.TMCT_MEMORY_BACKEND || "").trim().toLowerCase();
+  if (!backend) {
+    try {
+      const { loadTomlConfig } = await import("../toml-config.mjs");
+      backend = String((await loadTomlConfig(repoRoot))?.memory?.backend || "").trim().toLowerCase();
+    } catch { backend = ""; }
   }
-  return { dir: repoRoot, close: async () => {} };
+  return openMemoryBackend(repoRoot, backend);
 }
 
 /** Deep-clone a JSON-safe value — keeps every cache read/write from aliasing
@@ -230,9 +269,20 @@ const cloneJson = (v) => (v === undefined ? v : structuredClone(v));
 
 /** The loadMemory-equivalent read for Backend C: reconstructs from SQL once
  *  per handle (or after a failed write invalidates the cache), then returns a
- *  clone of `handle.cachedPayload` with zero SQL. */
+ *  clone of `handle.cachedPayload` with zero SQL.
+ *
+ *  PRAGMA data_version guards the cache across CONNECTIONS: it ticks when any
+ *  other connection commits to the same file (never for this connection's own
+ *  writes, which the cache already mirrors in lockstep). Without the check, a
+ *  second writer's rows would be invisible here — and this handle's next
+ *  persist would delete them as absent-from-payload. */
 function readSqlitePayload(handle) {
-  if (!handle.cachedPayload) handle.cachedPayload = buildSqlitePayloadFromRows(handle);
+  const dataVersion = handle.db.prepare("PRAGMA data_version").get()?.data_version;
+  if (handle.cachedPayload && handle.cachedDataVersion !== dataVersion) handle.cachedPayload = null;
+  if (!handle.cachedPayload) {
+    handle.cachedPayload = buildSqlitePayloadFromRows(handle);
+    handle.cachedDataVersion = dataVersion;
+  }
   return cloneJson(handle.cachedPayload);
 }
 
@@ -1081,6 +1131,21 @@ export async function appendUtterances(dir, utterances) {
   return { ids };
 }
 
+/** Append mgx:canonicalisedFrom edges (canonical Fact → as-spoken Utterance),
+ *  deduped by (subject, object) via upsertEdge — the fold's canonise-link
+ *  write, routed through the same backend-dispatched mutate path as every
+ *  other append so it lands in whichever store the repo actually uses. */
+export async function appendCanonicalisedFromEdges(dir, links) {
+  if (!links?.length) return;
+  await mutateMemory(dir, (payload) => {
+    for (const l of links) {
+      upsertEdge(payload, { predicate: "canonicalisedFrom", prop: CANONICALISED_FROM_PROP }, {
+        subject: l.factId, object: l.uttId, subjectLabel: l.factLabel, objectLabel: l.uttLabel,
+      });
+    }
+  });
+}
+
 /** Append one grammar-derived OWL triple, RDF-reified as a `Fact` individual.
  *  Same (s,p,o) -> same id -> upsert, never a duplicate. `premiseTrusts`/
  *  `ruleConfidence` optionally engage trust.mjs's entailed hook. Validated

package/src/adapters/toml-config.mjs

@@ -169,11 +169,12 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   // (snapshotMemory), not injected here.
   //
   // [memory] backend — the storage-backend seam (createSession's
-  // `memoryBackend` option / TMCT_MEMORY_BACKEND env): "default" (the flat
-  // OWL-labelled JSON file under .tmct/memory/), "memory" (in-process only,
-  // nothing on disk), or "sqlite" (a local SQLite file). Written by `tmct init
-  // --memory-backend <...>`; read by chat.mjs's createSession at CLI-flag > env >
-  // tmct.toml > default precedence, same order as everything else in this file.
+  // `memoryBackend` option / TMCT_MEMORY_BACKEND env): "sqlite" (a local
+  // SQLite file at .tmct/memory/graph.sqlite — also what "default"/unset
+  // resolves to), or "memory" (in-process only, nothing on disk). Written by
+  // `tmct init --memory-backend <...>`; read by chat.mjs's createSession at
+  // CLI-flag > env > tmct.toml > default precedence, same order as everything
+  // else in this file.
   const mem = src.memory || {};
   const memory = {};
   if (mem.retention_versions !== undefined) memory.retentionVersions = mem.retention_versions;

package/src/domain/cli-verbs.mjs

@@ -31,10 +31,12 @@ export const CLI_VERBS = [
       { flag: "[--ephemeral]", prose: ["read the graph but write nothing back (demo/read-only)"] },
       { flag: "[--prompt \"<text>\"]", prose: ["one-shot: run the prompt's sentences as turns and print", "the final answer (teach state first, trigger last)"] },
       { flag: "[--render blocks]", prose: ["with --prompt: when the final turn produced a plan,", "write it as a self-contained animated page"] },
-      { flag: "[--output <path>]", prose: ["the rendered page's path (default plan.html)"] },
+      { flag: "[--render spider-fly|adventure|sprites]", prose: ["write that demo view as one self-contained", "page (no --prompt; the game pages inline their engine)"] },
+      { flag: "[--output <path>]", prose: ["the rendered page's path (default plan.html for", "blocks, <archetype>.html for the views)"] },
       { flag: "[--narrate]", prose: ["start with narrate mode on — a verbose, developer-facing", "trace of decision points/matched pattern/results/goal per", "turn, appended under a \"--- narrate ---\" marker (also", "TMCT_NARRATE=1; toggle mid-session with /narrate on|off)"] },
+      { flag: "[--live-wikipedia]", prose: ["start with the live Wikipedia supplement on — a question", "nothing local can answer also tries en.wikipedia.org,", "cited (network; also TMCT_LIVE_WIKIPEDIA=1 or tmct.toml", "corpus tier3; toggle mid-session with /wiki on|off)"] },
       { flag: "[--plain]", prose: ["force the plain readline shell (the default when", "stdin/stdout is not a terminal)"] },
-      { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["storage backend for taught facts this", "session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's", "[memory] backend > \"default\", the flat .tmct/ JSON file)"] },
+      { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["storage backend for taught facts this", "session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's", "[memory] backend > sqlite, .tmct/memory/graph.sqlite)"] },
     ],
   },
   {

package/src/domain/hanoi-lesson.mjs

@@ -17,6 +17,14 @@
 // relation is stored as given and never chased transitively (see the
 // "scale" variation documented in hanoi-3.txt itself), so a partial pairing
 // would leave some disks with no legal move.
+//
+// On top of hanoi-3.txt's own content, the lesson teaches two puzzle-
+// inventory facts ("puzzle has N disks." / "puzzle has 3 pegs.") so the
+// page's dock can answer "what is the puzzle?" / "does the puzzle have N
+// disks?" about the very control the page displays. The subject is bare
+// ("puzzle", no article) because that is the shape the has-teach frame
+// stores; the disk fact regenerates with the disk-count control, so it
+// tracks N instead of going stale.
 
 /** The taught lesson for an N-disk puzzle: the class/individual/ordering
  *  facts, the action rule, the render hints, the starting stack (largest at
@@ -33,6 +41,8 @@ export function hanoiLessonSentences(diskCount = 3, { goalPeg = "peg-c" } = {})
   sentences.push("a peg is a kind of place.");
   for (const d of disks) sentences.push(`${d} is a disk.`);
   for (const p of pegs) sentences.push(`${p} is a peg.`);
+  sentences.push(`puzzle has ${n} disk${n === 1 ? "" : "s"}.`);
+  sentences.push("puzzle has 3 pegs.");
   for (let i = 0; i < n; i += 1) {
     for (let j = i + 1; j < n; j += 1) sentences.push(`${disks[i]} is smaller than ${disks[j]}.`);
   }