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

package/src/chat.mjs

@@ -1,6 +1,6 @@
 // chat.mjs — `tmct chat`: a full interactive client over the tmct code-graph.
 // Any BARE line is a plain-English question dispatched through the mechanical
-// tmct_ask engine (the EXACT path bin/cli.mjs's `cli tmct_ask` fallback uses),
+// tmct_ask engine (the EXACT path bin/tmct.mjs's `cli tmct_ask` fallback uses),
 // so chat is the same zero-model engine with a readline shell around it, plus:
 //
 //   - SLASH-COMMANDS to reach every richer tool dispatchTool (server.mjs) serves —
@@ -31,6 +31,11 @@
 // focus }) so tests exercise it directly; every ask.mjs import is LAZY and
 // failure-tolerated, so concurrent evolution of the engine can never crash a turn
 // (worst case a turn records fewer ids / an honest miss hint, never wrong data).
+//
+// createSession(…) is the SESSION SINK every shell shares: it owns the artifact
+// files, the per-turn writeLog → writeSidecar → upsertGraph sequencing (order is
+// load-bearing — see its docblock), telemetry, and the close. runChat is the
+// readline shell over it; src/tui/app.mjs is the Ink shell over the same sink.
 
 import { join } from "node:path";
 import { createWriteStream } from "node:fs";
@@ -315,7 +320,7 @@ export function gitToplevel(cwd = process.cwd()) {
   return null;
 }
 
-/** Mirror bin/cli.mjs's configFor: an explicit repo pins the artifact path; no
+/** Mirror bin/tmct.mjs's configFor: an explicit repo pins the artifact path; no
  *  repo falls back to the cwd/env-derived default. */
 function configFor(repoPath) {
   return repoPath ? { graphFile: join(repoPath, DEFAULT_GRAPH_REL) } : loadConfig();
@@ -475,6 +480,34 @@ async function runCommand(line, { config, source, graph, focus }) {
   return mk(answer);
 }
 
+/** A declarative ACE-grammar sentence → assert into memory + confirm; null on
+ *  any grammar miss / residue / import failure so the query engine keeps first
+ *  refusal on everything else. Lazy imports + catch-all: the grammar layer can
+ *  never crash a turn (chat.mjs ethos). Writes ONLY under memoryDir/.tmct/memory. */
+async function assertTurn(line, { memoryDir, sessionId, focus }) {
+  try {
+    const { parseAce } = await import("./grammar/ace.mjs");
+    const { loadLexicon } = await import("./grammar/lexicon.mjs");
+    const parse = parseAce(line, loadLexicon());
+    if (!parse || !parse.triples?.length || parse.residue?.length) return null;
+    const { assertSentence } = await import("./grammar/assert.mjs");
+    const { normFactTerm } = await import("./memory/core.mjs");
+    const ts = new Date().toISOString();
+    const res = await assertSentence(memoryDir, line, {
+      provenance: { source: "chat", sessionId, ts },
+    });
+    if (!res || !res.ids?.length) return null;
+    const shown = res.triples
+      .map((t) => `${normFactTerm(t.subject)} ${t.predicate} ${normFactTerm(t.object)}`)
+      .join("; ");
+    const n = res.ids.length;
+    const answer = `noted — remembered ${n} fact${n === 1 ? "" : "s"}: ${shown}`;
+    return plainTurn(line, answer, { command: "assert", focus });
+  } catch {
+    return null; // grammar unavailable / write failed — fall through to the engine
+  }
+}
+
 /**
  * One chat turn: input → { answer, logLines, record, focus }. Pure of any
  * TTY/stream concerns so tests exercise it directly. A leading `/` routes to a
@@ -489,9 +522,9 @@ async function runCommand(line, { config, source, graph, focus }) {
  * subject), `answeredIds` the entity ids an ask answer cited; a slash-command turn
  * also carries its `command` name. Both drive the mgx:asksAbout graph append.
  */
-export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null } = {}) {
+export async function runTurn(input, { config, source = defaultSource, graph = null, focus = null, last = null, memoryDir = null, sessionId = "" } = {}) {
   const line = String(input ?? "").trim();
-  const ctx = { config, source, graph, focus, last };
+  const ctx = { config, source, graph, focus, last, memoryDir, sessionId };
   // A DISPATCHED turn (count / slash-command / ask) becomes the new "last answer"
   // that why/say-more re-renders; a conversational turn does not (it preserves it).
   const withLast = (result) => ({ ...result, last: { query: line, answer: result.answer, detail: result.detail ?? null } });
@@ -502,6 +535,14 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
   if (convo) return convo;
 
   if (line.startsWith("/")) return withLast(await runCommand(line, ctx));
+  // Declarative ACE sentences ("every module is a artifact") ASSERT into tmct's
+  // own memory and confirm — they are statements to remember, not graph queries.
+  // Gated on memoryDir: only a session shell provides a write target, so a bare
+  // runTurn (tests, library callers) stays pure and falls through to the engine.
+  if (memoryDir) {
+    const asserted = await assertTurn(line, ctx);
+    if (asserted) return withLast(asserted);
+  }
   // Aggregate/count questions are answered mechanically off the loaded graph header,
   // BEFORE falling through to the ask engine (focus unchanged — a count names no entity).
   const count = answerCount(graph, line);
@@ -514,16 +555,28 @@ const shortLabel = (l) => { const s = String(l); return s.length > 40 ? "…" +
 const promptFor = (focus) => (focus ? `tmct(${shortLabel(focus.label)})> ` : PROMPT);
 
 /**
- * The interactive shell. Streams are injectable so tests run scripted sessions
- * without a TTY. A repo with NO graph artifact is not an error: the session
- * starts from the empty bootstrap graph (the banner says so honestly) and the
- * first turn's fold-in creates .tmct/graph.json from the conversation itself.
- * Returns { logFile, sidecarFile, turns } once the session ends.
+ * The SESSION SINK — everything a chat shell (readline below, the Ink TUI, any
+ * future surface) must share so the on-disk session contract stays identical no
+ * matter what draws the screen:
+ *
+ *   - repo/config resolution (git root default, --repo override) + the one-time
+ *     graph load and banner strings;
+ *   - the transcript log + structured sidecar file creation and per-turn
+ *     writeLog → writeSidecar → upsertGraph sequencing. THE ORDER IS LOAD-BEARING:
+ *     the memory side-write (sessions.mjs) recovers each turn's ANSWER text by
+ *     re-reading the transcript keyed by turnKey(record.ts, query), so the log
+ *     line must be flushed before the graph upsert runs, and logLines[0] must be
+ *     the record's ts (runTurn guarantees that);
+ *   - opt-in telemetry and the end-of-session close (end lines, final upsert,
+ *     stream flush).
+ *
+ * Returns { repo, config, graph, moduleCount, version, sessionId, logFile,
+ * sidecarFile, bannerLines, empty, focus, turns, promptFor(), turn(line), close() }.
+ * `turn(line)` runs one dispatched turn through runTurn and the full sink
+ * sequencing, returning { answer, end, prompt }; `close()` is idempotent.
  */
-export async function runChat({
+export async function createSession({
   repoPath,
-  input = process.stdin,
-  output = process.stdout,
   source = defaultSource,
   env = process.env,
   cwd = process.cwd(),
@@ -548,7 +601,7 @@ export async function runChat({
   const moduleCount = graph.individuals.filter((i) => (i.class || "") === "Module").length;
   const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 
-  // Opt-in telemetry (default OFF → null → the loop's `tel?.record` is a no-op, and
+  // Opt-in telemetry (default OFF → null → the sink's `tel?.record` is a no-op, and
   // nothing is written). The conversational session log + sidecar above stay the
   // authoritative chat record; this is the machine-readable query telemetry.
   const tel = createTelemetry({ env, config, surface: "chat" });
@@ -562,7 +615,7 @@ export async function runChat({
   const sidecarFile = join(sessionsDir, `session-${sessionId}.jsonl`);
   const stream = createWriteStream(logFile, { flags: "a" });
   const sidecar = createWriteStream(sidecarFile, { flags: "a" });
-  // Awaited writes: each chunk is handed to the OS before the loop continues, so a
+  // Awaited writes: each chunk is handed to the OS before the turn completes, so a
   // killed session keeps everything up to the last completed turn — in both files.
   const flush = (s, text) =>
     new Promise((resolve, reject) => s.write(text, (e) => (e ? reject(e) : resolve())));
@@ -584,35 +637,36 @@ export async function runChat({
     catch { /* best-effort — see above */ }
   };
 
-  const dim = (s) => (env.NO_COLOR || !output.isTTY ? s : `\x1b[2m${s}\x1b[0m`);
-  if (graph.individuals.length === 0) {
-    // Empty-graph bootstrap: honest-miss messaging, never an error before the prompt.
-    output.write(dim(`tmct chat — ${repo} — no graph loaded — starting empty; ` +
-      `the conversation is remembered to ${DEFAULT_GRAPH_REL} — log ${logFile}`) + "\n");
-  } else {
-    output.write(dim(`tmct chat — ${repo} — ${moduleCount} module(s) — log ${logFile}`) + "\n");
-  }
-  output.write(dim("pass --repo <path> to target a different repo") + "\n");
-  output.write(dim("ask a question, or /help for commands (/stats for an overview) — /exit to leave") + "\n");
-
-  const rl = createInterface({ input, output, prompt: PROMPT });
-  rl.on("SIGINT", () => rl.close()); // Ctrl+C behaves like /exit (clean close, log flushed)
-  let closed = false;
-  rl.on("close", () => { closed = true; });
-  const prompt = () => { if (!closed) rl.prompt(); }; // input may end while a turn is in flight
+  const empty = graph.individuals.length === 0;
+  const bannerLines = [
+    empty
+      // Empty-graph bootstrap: honest-miss messaging, never an error before the prompt.
+      ? `tmct chat — ${repo} — no graph loaded — starting empty; ` +
+        `the conversation is remembered to ${DEFAULT_GRAPH_REL} — log ${logFile}`
+      : `tmct chat — ${repo} — ${moduleCount} module(s) — log ${logFile}`,
+    "pass --repo <path> to target a different repo",
+    "ask a question, or /help for commands (/stats for an overview) — /exit to leave",
+  ];
 
   let turns = 0;
   let focus = null; // the current focus entity ({id,label}) — threaded turn to turn
   let last = null;  // the last dispatched answer ({query,answer,detail}) — why/say-more re-renders it
-  prompt();
-  for await (const raw of rl) { // Ctrl+D / closed stdin ends the iteration cleanly
-    const line = raw.trim();
-    if (line === "/exit") break;
-    if (line) {
-      const { answer, logLines, record, focus: nextFocus, last: nextLast, end } = await runTurn(line, { config, source, graph, focus, last });
+  let closed = false;
+
+  return {
+    repo, config, graph, moduleCount, version, sessionId, logFile, sidecarFile,
+    bannerLines, empty,
+    get focus() { return focus; },
+    get turns() { return turns; },
+    promptFor: () => promptFor(focus),
+
+    /** One dispatched turn through the FULL sink sequencing (writeLog → writeSidecar
+     *  → telemetry → upsertGraph, in that exact order). Returns { answer, end, prompt }. */
+    async turn(line) {
+      const { answer, logLines, record, focus: nextFocus, last: nextLast, end } =
+        await runTurn(line, { config, source, graph, focus, last, memoryDir: repo, sessionId });
       focus = nextFocus;
       last = nextLast;
-      output.write(answer + "\n");
       await writeLog(logLines.join("\n") + "\n");
       await writeSidecar(record);
       turnRecords.push(record);
@@ -625,18 +679,66 @@ export async function runChat({
       });
       await upsertGraph(record.ts);
       turns += 1;
-      rl.setPrompt(promptFor(focus));
+      return { answer, end: Boolean(end), prompt: promptFor(focus) };
+    },
+
+    /** End-of-session close: end lines in both artifacts, the final graph upsert
+     *  (which also triggers the memory fold), stream flush. Idempotent. */
+    async close() {
+      if (closed) return;
+      closed = true;
+      const endIso = new Date().toISOString();
+      await writeLog(`${endIso}\n> /exit\nsession end ${endIso}\n`);
+      await writeSidecar({ type: "end", ts: endIso });
+      await upsertGraph(endIso);
+      await new Promise((resolve) => stream.end(resolve));
+      await new Promise((resolve) => sidecar.end(resolve));
+    },
+  };
+}
+
+/**
+ * The interactive readline shell over createSession — the `--plain` surface and
+ * the scripted-test surface. Streams are injectable so tests run sessions
+ * without a TTY. A repo with NO graph artifact is not an error: the session
+ * starts from the empty bootstrap graph (the banner says so honestly) and the
+ * first turn's fold-in creates .tmct/graph.json from the conversation itself.
+ * Returns { logFile, sidecarFile, turns } once the session ends.
+ */
+export async function runChat({
+  repoPath,
+  input = process.stdin,
+  output = process.stdout,
+  source = defaultSource,
+  env = process.env,
+  cwd = process.cwd(),
+  gitRoot = gitToplevel,
+} = {}) {
+  const session = await createSession({ repoPath, source, env, cwd, gitRoot });
+
+  const dim = (s) => (env.NO_COLOR || !output.isTTY ? s : `\x1b[2m${s}\x1b[0m`);
+  for (const line of session.bannerLines) output.write(dim(line) + "\n");
+
+  const rl = createInterface({ input, output, prompt: PROMPT });
+  rl.on("SIGINT", () => rl.close()); // Ctrl+C behaves like /exit (clean close, log flushed)
+  let closed = false;
+  rl.on("close", () => { closed = true; });
+  const prompt = () => { if (!closed) rl.prompt(); }; // input may end while a turn is in flight
+
+  prompt();
+  for await (const raw of rl) { // Ctrl+D / closed stdin ends the iteration cleanly
+    const line = raw.trim();
+    if (line === "/exit") break;
+    if (line) {
+      const { answer, end, prompt: nextPrompt } = await session.turn(line);
+      output.write(answer + "\n");
+      rl.setPrompt(nextPrompt);
       if (end) break; // a conversational "bye"/"goodbye" — clean end, same as /exit
     }
     prompt();
   }
   rl.close();
 
-  const endIso = new Date().toISOString();
-  await writeLog(`${endIso}\n> /exit\nsession end ${endIso}\n`);
-  await writeSidecar({ type: "end", ts: endIso });
-  await upsertGraph(endIso);
-  await new Promise((resolve) => stream.end(resolve));
-  await new Promise((resolve) => sidecar.end(resolve));
-  return { logFile, sidecarFile, turns };
+  await session.close();
+  return { logFile: session.logFile, sidecarFile: session.sidecarFile, turns: session.turns };
 }

package/src/corpus/conceptnet-map.toml

@@ -0,0 +1,251 @@
+# conceptnet-map.toml — the relation → ACE-OWL-pattern mapping table
+# (ROADMAP Phase 2, ConceptNet corpus slice).
+#
+# One row per ConceptNet relation (the canonical closed set of 34 —
+# docs/references/schemas/conceptnet-relations.md is the reference list this
+# table is drift-checked against; test/corpus-conceptnet.test.mjs fails if the
+# committed slice contains a relation with no row here).
+#
+# Fields:
+#   rel       the ConceptNet relation URI ("/r/IsA")
+#   surface   the canonical surface template, "{start}"/"{end}" slotted —
+#             the "A dog is a kind of animal" sentence shape this relation reads as
+#   ace       which ACE-OWL pattern it maps to (docs/references/schemas/
+#             ace-owl-fragment.md): subClassOf | type | ObjectProperty |
+#             someValuesFrom | disjointWith | property | none
+#   predicate the predicate URI src/corpus/conceptnet.mjs emits into memory
+#             facts (absent when ace = "none" — no fact is emitted)
+#   note      why, and what a "none" row is still good for
+#
+# Loader contract (src/corpus/conceptnet.mjs): a relation in the slice that is
+# MISSING here is an error (drift guard); a row with ace = "none" is a
+# deliberate non-emission, silently skipped by toFacts().
+
+[[relation]]
+rel = "/r/IsA"
+surface = "a {start} is a kind of {end}"
+ace = "subClassOf"
+predicate = "rdfs:subClassOf"
+note = "hyponym → hypernym; ACE pattern 1 ('every N1 is a N2')"
+
+[[relation]]
+rel = "/r/DefinedAs"
+surface = "a {start} is defined as {end}"
+ace = "subClassOf"
+predicate = "rdfs:subClassOf"
+note = "definitional IsA; also ACE pattern 1"
+
+[[relation]]
+rel = "/r/PartOf"
+surface = "a {start} is part of a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:partOf"
+note = "meronymy; ACE pattern 3 (N1 VERB N2)"
+
+[[relation]]
+rel = "/r/HasA"
+surface = "a {start} has a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasA"
+note = "possession/holonymy; plain edge today — ACE pattern 5 cardinality is a later refinement"
+
+[[relation]]
+rel = "/r/UsedFor"
+surface = "a {start} is used for {end}"
+ace = "ObjectProperty"
+predicate = "mgx:usedFor"
+note = "typical purpose; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CapableOf"
+surface = "a {start} can {end}"
+ace = "ObjectProperty"
+predicate = "mgx:capableOf"
+note = "typical capability; ACE pattern 3"
+
+[[relation]]
+rel = "/r/AtLocation"
+surface = "you are likely to find a {start} in a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:atLocation"
+note = "typical location; ACE pattern 3"
+
+[[relation]]
+rel = "/r/Causes"
+surface = "a {start} causes {end}"
+ace = "ObjectProperty"
+predicate = "mgx:causes"
+note = "causation; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasSubevent"
+surface = "when you {start}, you {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasSubevent"
+note = "event decomposition; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasFirstSubevent"
+surface = "the first thing you do when you {start} is {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasFirstSubevent"
+note = "first step; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasLastSubevent"
+surface = "the last thing you do when you {start} is {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasLastSubevent"
+note = "last step; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasPrerequisite"
+surface = "in order to {start}, you must {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasPrerequisite"
+note = "dependency; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasProperty"
+surface = "a {start} is {end}"
+ace = "property"
+predicate = "mgx:hasProperty"
+note = "attribute/adjective; ACE pattern 8 ('N1 is ADJ')"
+
+[[relation]]
+rel = "/r/MotivatedByGoal"
+surface = "you would {start} because you want to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:motivatedByGoal"
+note = "motivation; ACE pattern 3"
+
+[[relation]]
+rel = "/r/ObstructedBy"
+surface = "{start} can be prevented by {end}"
+ace = "ObjectProperty"
+predicate = "mgx:obstructedBy"
+note = "blocker; ACE pattern 3"
+
+[[relation]]
+rel = "/r/Desires"
+surface = "a {start} wants {end}"
+ace = "ObjectProperty"
+predicate = "mgx:desires"
+note = "typical desire; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CausesDesire"
+surface = "{start} makes you want to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:causesDesire"
+note = "evoked desire; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CreatedBy"
+surface = "a {start} is created by a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:createdBy"
+note = "provenance; ACE pattern 3"
+
+[[relation]]
+rel = "/r/MadeOf"
+surface = "a {start} is made of {end}"
+ace = "ObjectProperty"
+predicate = "mgx:madeOf"
+note = "material; ACE pattern 3"
+
+[[relation]]
+rel = "/r/ReceivesAction"
+surface = "a {start} can be {end}"
+ace = "ObjectProperty"
+predicate = "mgx:receivesAction"
+note = "typical patient role; ACE pattern 3"
+
+[[relation]]
+rel = "/r/LocatedNear"
+surface = "a {start} is typically near a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:locatedNear"
+note = "proximity; ACE pattern 3"
+
+[[relation]]
+rel = "/r/MannerOf"
+surface = "{start} is a way to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:mannerOf"
+note = "verb specialization — properly rdfs:subPropertyOf between verbs; stored as a plain edge until the grammar grows verb hierarchies"
+
+[[relation]]
+rel = "/r/DistinctFrom"
+surface = "a {start} is not a {end}"
+ace = "disjointWith"
+predicate = "owl:disjointWith"
+note = "mutual exclusion; ACE pattern 6 ('no N1 is a N2')"
+
+# --- unmappable relations: no clean OWL-axiom fit; kept for other consumers ---
+
+[[relation]]
+rel = "/r/RelatedTo"
+surface = "{start} is related to {end}"
+ace = "none"
+note = "weakest, undirected association — too vague for an axiom; useful later as a fuzzy-match hint, never a fact"
+
+[[relation]]
+rel = "/r/Synonym"
+surface = "{start} means the same as {end}"
+ace = "none"
+note = "lexical alias, not an axiom — feeds the grammar lexicon / phrasebook synonym families instead"
+
+[[relation]]
+rel = "/r/Antonym"
+surface = "{start} is the opposite of {end}"
+ace = "none"
+note = "lexical opposition; OWL disjointness would over-claim (hot/cold are not disjoint classes) — DistinctFrom carries the real disjointness"
+
+[[relation]]
+rel = "/r/FormOf"
+surface = "{start} is a form of the word {end}"
+ace = "none"
+note = "inflection → root; lexicon normalization, not knowledge"
+
+[[relation]]
+rel = "/r/DerivedFrom"
+surface = "the word {start} is derived from {end}"
+ace = "none"
+note = "word derivation; lexicon material, not an axiom"
+
+[[relation]]
+rel = "/r/SymbolOf"
+surface = "{start} is a symbol of {end}"
+ace = "none"
+note = "symbolism — no OWL fit"
+
+[[relation]]
+rel = "/r/SimilarTo"
+surface = "{start} is similar to {end}"
+ace = "none"
+note = "graded similarity — no crisp OWL fit; potential fuzzy-match hint only"
+
+[[relation]]
+rel = "/r/HasContext"
+surface = "{start} is used in the context of {end}"
+ace = "none"
+note = "usage-domain tag — the slice FILTER signal (tech-domain selection), not a fact to store"
+
+[[relation]]
+rel = "/r/EtymologicallyRelatedTo"
+surface = "{start} shares an origin with {end}"
+ace = "none"
+note = "etymology — filtered out of the slice by policy"
+
+[[relation]]
+rel = "/r/EtymologicallyDerivedFrom"
+surface = "the word {start} comes from {end}"
+ace = "none"
+note = "etymology — filtered out of the slice by policy"
+
+[[relation]]
+rel = "/r/ExternalURL"
+surface = "{start} is described at {end}"
+ace = "none"
+note = "link out of the graph — filtered out of the slice (end is a URL, not an en concept)"