@polycode-projects/the-mechanical-code-talker 1.10.14 → 1.11.5

package/bin/tmct.mjs

@@ -38,6 +38,11 @@ Usage:
                                see src/graph-merge.mjs); wins over --repo/TMCT_GRAPH_FILE/tmct.toml
        [--config <path>]       an alternate tmct.toml location (a file or a directory)
        [--ephemeral]           read the graph but write nothing back (demo/read-only)
+       [--prompt "<text>"]     one-shot: run the prompt's sentences as turns and print
+                               the final answer (teach state first, trigger last)
+       [--render blocks]       with --prompt: when the final turn produced a plan,
+                               write it as a self-contained animated page
+       [--output <path>]       the rendered page's path (default plan.html)
        [--narrate]             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
@@ -77,6 +82,9 @@ Usage:
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
        [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
+       [--file <definition.txt>]  teach a plain-text definition file sentence by
+                               sentence (# lines are comments); any declined
+                               sentence exits non-zero with the sentence named
        [--memory-backend <default|memory|sqlite>]  same knob as \`tmct init\`
        [--config <path>]
   tmct extend --validate <dir>  validate a third-party extension pack's declared
@@ -85,20 +93,14 @@ Usage:
   tmct syllogise [--repo <abs>] speculative inference (offline maintenance job): forward-
        [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
-  tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
-       [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
-       [--term <word>]        timestamps. Seeds from the most recently created individual
-       [--depth <n>]          by default (--focus <id> or --term <word> override it);
-       [--limit <n>]          --output defaults to graph.html in the cwd.
-       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
-       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
-       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
-       [--config <path>]      connections, still shows it (default 40); --edge-kind =
-                               meta|relation|both (default both) — which edge kinds the
-                               walk follows (provenance-only, concept-relations-only, or
-                               both — see the page's own edge-kind toggle to change this
-                               live); --term <word> resolves to the Fact(s) whose subject/
-                               object normalizes to that word and seeds from there.
+  tmct viz [--repo <abs>]      write one self-contained HTML page: the memory graph as a
+       [--focus <term>]       readable ledger of fact-sentences around one focus term,
+       [--term <word>]        with segments, a two-hop minimap, and an in-page chat dock
+       [--limit <n>]          that answers from the embedded graph. Focuses on the newest
+       [--output <path>]      taught fact's subject by default (--focus <term> or
+       [--config <path>]      --term <word> override it); --output defaults to
+                               ledger.html in the cwd; --limit caps the embedded fact
+                               rows; --term resolves via the same normalization chat uses.
   tmct serve [--repo <abs>]    run the Anthropic Messages API-compatible endpoint
        [--host <h>] [--port <n>]  (POST /v1/messages) over the graph — a deterministic,
        [--graph <path>]        no-LLM "model" a tool-loop client can call; $0 usage.
@@ -596,6 +598,65 @@ async function main() {
     if (graphPaths.length) extra.graphPaths = graphPaths;
     if (configPath) extra.configPath = configPath;
     if (memoryBackend) extra.memoryBackend = memoryBackend;
+    // `--prompt "<text>"` — one-shot mode: each sentence of the prompt runs as
+    // its own turn (state teaches first, the goal/solve trigger last), the
+    // FINAL turn's answer prints to stdout, and the process exits. Piped stdin
+    // stays the interactive fallback.
+    const prompt = strFlag(rest, ["--prompt"]);
+    // `--render <archetype> [--output <path>]` — after a one-shot --prompt whose
+    // final turn produced a plan, write the self-contained animated plan page
+    // (src/plan-viz.mjs). Requires --prompt: interactive chat has no single
+    // final turn to render.
+    let renderArchetype;
+    try {
+      renderArchetype = enumFlag(rest, ["--render"], ["blocks"]);
+    } catch (e) {
+      process.stderr.write(`tmct: ${e?.message || e}\n`);
+      process.exit(2);
+    }
+    if (renderArchetype && !prompt) {
+      process.stderr.write("tmct: --render needs --prompt (a one-shot turn whose plan it renders)\n");
+      process.exit(1);
+    }
+    if (prompt) {
+      const { createSession } = await import("../src/chat.mjs");
+      const { splitSentences } = await import("../src/sentences.mjs");
+      const session = await createSession({ repoPath, ephemeral, narrate, ...extra });
+      let finalAnswer = "";
+      let finalPlan = null;
+      let parts;
+      try { parts = splitSentences(prompt); } catch { parts = null; }
+      const sentences = parts && parts.length ? parts : [prompt];
+      for (const s of sentences) {
+        const t = await session.turn(s);
+        finalAnswer = t?.answer ?? "";
+        finalPlan = t?.plan ?? null;
+      }
+      await session.close();
+      process.stdout.write(finalAnswer + "\n");
+      if (renderArchetype) {
+        if (!finalPlan) {
+          process.stderr.write("the final turn produced no plan — nothing to render\n");
+          process.exitCode = 1;
+          return;
+        }
+        const { renderPlanHtml } = await import("../src/plan-viz.mjs");
+        const { writeFile } = await import("node:fs/promises");
+        const { resolve: resolvePath } = await import("node:path");
+        const outPath = resolvePath(process.cwd(), strFlag(rest, ["--output", "--out"], "plan.html"));
+        const rendersAs = finalPlan.domain?.renderHints ?? {};
+        const sizeOrder = (finalPlan.domain?.ordering ?? [])
+          .filter((row) => /-than$/.test(String(row.predicate || "")))
+          .map((row) => [row.subject, row.object]);
+        const html = renderPlanHtml({
+          plan: finalPlan, rendersAs, sizeOrder,
+          title: finalPlan.goal?.text || "tmct plan",
+        });
+        await writeFile(outPath, html, "utf8");
+        process.stdout.write(`wrote ${outPath} (${finalPlan.actions.length} moves, ${finalPlan.states.length} snapshots)\n`);
+      }
+      return;
+    }
     // The shell gate: a real terminal gets the full-screen Ink TUI; `--plain` or a
     // non-TTY stream (pipes, scripts, the test suite) gets the readline shell. Both
     // drive the same createSession sink — only the drawing differs.
@@ -867,8 +928,9 @@ async function main() {
       process.exit(2);
     }
 
-    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length && !memoryBackendVal) {
-      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph/--memory-backend\n");
+    const fileVal = strFlag(rest, ["--file"]);
+    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length && !memoryBackendVal && !fileVal) {
+      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph/--memory-backend/--file\n");
       process.exit(2);
     }
 
@@ -914,6 +976,22 @@ async function main() {
         process.exit(1);
       }
     }
+
+    // `--file <definition.txt>` — teach a plain-text definition file, one
+    // sentence per turn, through the same recognizers the live chat uses.
+    // Any declined sentence exits non-zero: a half-taught game plans wrongly
+    // or not at all with no visible cause otherwise.
+    if (fileVal) {
+      const { importDefinitionFile } = await import("../src/import-file.mjs");
+      try {
+        const result = await importDefinitionFile(repoRoot, fileVal);
+        process.stdout.write(result.report + "\n");
+        if (result.declined.length > 0) process.exit(1);
+      } catch (e) {
+        process.stderr.write(`tmct import: ${e?.message || e}\n`);
+        process.exit(1);
+      }
+    }
     return;
   }
 
@@ -1006,53 +1084,50 @@ async function main() {
   }
 
   if (mode === "viz") {
-    // `tmct viz` — one self-contained, navigable HTML file rendering the
-    // memory graph (PLAN_BREADTH_FIRST_NLU.md §5, PLAN_VIZ.md's design):
-    // pan/zoom, click-a-node, a concentric ring layout keyed on hop with a
-    // depth/age falloff. Same repo resolution as `memory`/`syllogise` —
-    // resolveRuntimeConfig: --repo > git root > cwd.
+    // `tmct viz` — the ledger explorer: one self-contained HTML page rendering
+    // the memory graph as readable fact-sentences around a focus term, with
+    // the in-browser chat dock (PLAN_VIZ_LEDGER.md). Same repo resolution as
+    // `memory`/`syllogise` — resolveRuntimeConfig: --repo > git root > cwd.
+    // `--ledger` is accepted as a no-op: the ledger IS the viz surface now.
     const rest = process.argv.slice(3);
+    const retiredFlags = ["--depth", "--hub-degree", "--edge-kind"].filter((f) => rest.includes(f));
+    if (retiredFlags.length) {
+      process.stderr.write(
+        `tmct viz: ${retiredFlags.join(", ")} belonged to the retired node-link graph page and no longer exist${retiredFlags.length === 1 ? "s" : ""}.\n`
+        + "The ledger view takes: --repo <abs>, --focus <term>, --term <word>, --limit <n>, --output <path>.\n",
+      );
+      process.exitCode = 1;
+      return;
+    }
     const { strFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
-    const { computeVizGraph, renderVizHtml, readAskBundle, readMemoryAskBundle } = await import("../src/viz.mjs");
+    const { computeLedgerData, renderLedgerHtml, readMemoryAskBundle } = await import("../src/ledger-viz.mjs");
     const { writeFile } = await import("node:fs/promises");
     const { resolve } = await import("node:path");
-    const numFlag = (name) => {
-      const j = rest.indexOf(name);
-      const v = j !== -1 ? Number(rest[j + 1]) : NaN;
-      return Number.isFinite(v) ? v : undefined;
-    };
+    const limitIdx = rest.indexOf("--limit");
+    const limitRaw = limitIdx !== -1 ? Number(rest[limitIdx + 1]) : NaN;
+    const rowLimit = Number.isFinite(limitRaw) ? limitRaw : undefined;
     const focus = strFlag(rest, ["--focus"]);
-    const term = strFlag(rest, ["--term"]); // PLAN_VIZ_MEMORY.md: seed via normFactTerm-matched Fact(s), alongside --focus
-    const depth = numFlag("--depth"); // max arcs (hops) from the focus node
-    const nodeLimit = numFlag("--limit"); // spiral length: total nodes walked
-    const hubDegree = numFlag("--hub-degree"); // stop expanding THROUGH a node above N connections
-    const edgeKindModeRaw = strFlag(rest, ["--edge-kind"]);
-    const edgeKindMode = ["meta", "relation", "both"].includes(edgeKindModeRaw) ? edgeKindModeRaw : undefined;
-    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], "graph.html"));
+    const term = strFlag(rest, ["--term"]); // seeds via normFactTerm; --focus wins when both are given
+    const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], "ledger.html"));
     const { repo } = await resolveRuntimeConfig({ argv: rest });
-    const vizGraph = await computeVizGraph(repo, {
+    const data = await computeLedgerData(repo, {
       ...(focus ? { focus } : {}),
-      ...(!focus && term ? { term } : {}), // --focus takes precedence when both are given
-      ...(depth != null ? { depth } : {}),
-      ...(nodeLimit != null ? { nodeLimit } : {}),
-      ...(hubDegree != null ? { hubDegree } : {}),
-      ...(edgeKindMode ? { edgeKindMode } : {}),
+      ...(!focus && term ? { term } : {}),
+      ...(rowLimit != null ? { rowLimit } : {}),
     });
-    // The embedded "Ask the graph" chat panels — TWO real engines, bundled for
-    // the browser (scripts/build-ask-bundle.mjs's checked-in output): the
-    // code-graph ask.mjs engine, and (PLAN_VIZ_MEMORY.md Bug 1 fix) the
-    // memory-graph factAnswer engine. Neither read*AskBundle() ever throws; an
-    // empty string degrades that ONE engine gracefully rather than breaking
-    // the page (e.g. a fresh checkout before the bundles' first build).
-    const [askBundle, memoryAskBundle] = await Promise.all([readAskBundle(), readMemoryAskBundle()]);
-    const html = renderVizHtml({ ...vizGraph, askBundle, memoryAskBundle });
-    await writeFile(outPath, html, "utf8");
-    const chatNote = askBundle || memoryAskBundle
-      ? ` (with the embedded ask-the-graph chat panel${askBundle && memoryAskBundle ? "s" : ""})`
-      : " (no chat panel — run `npm run build:ask-bundle` first)";
+    // readMemoryAskBundle never throws; an empty string renders the page with
+    // an honest "chat unavailable" note instead of the dock (e.g. a fresh
+    // checkout before the bundle's first build).
+    const memoryAskBundle = await readMemoryAskBundle();
+    await writeFile(outPath, renderLedgerHtml({ ...data, memoryAskBundle }), "utf8");
     process.stdout.write(
-      `tmct viz — wrote ${vizGraph.nodes.length} node(s), ${vizGraph.edges.length} edge(s) to ${outPath}${chatNote}\n`,
+      `tmct viz — wrote ${data.meta.shown} fact row(s) around ${data.focus ? `'${data.focus}'` : "no focus"} to ${outPath}\n`,
     );
+    if (data.meta.truncated) {
+      process.stdout.write(
+        `showing ${data.meta.shown} of ${data.meta.total} rows — narrow with --focus <term> or raise --limit\n`,
+      );
+    }
     return;
   }
 
@@ -1158,7 +1233,7 @@ async function main() {
       process.stderr.write("tmct plan: needs a request, e.g. `tmct plan \"of the modules impacted by X, which are untested\"`\n");
       process.exit(2);
     }
-    const { config } = await resolveRuntimeConfig({ argv: rest });
+    const { repo, config } = await resolveRuntimeConfig({ argv: rest });
     const { buildCapabilityPlanCtx, runCapabilityPlan, declaredCapabilityNames } = await import("../src/router/drive.mjs");
     const declared = declaredCapabilityNames();
     let tools = declared;
@@ -1172,34 +1247,49 @@ async function main() {
     }
     let ctx;
     try {
-      ctx = await buildCapabilityPlanCtx({ config });
+      ctx = await buildCapabilityPlanCtx({ config, memoryDir: repo });
     } catch (e) {
       process.stderr.write(`tmct plan: could not load the graph — ${e?.message || e}\n`);
       process.exit(1);
     }
-    const result = await runCapabilityPlan(request, tools, ctx);
-    if (jsonFlag) {
-      process.stdout.write(JSON.stringify({ request, ...result }, null, 2) + "\n");
-      process.exit(result.refused ? 1 : 0);
-    }
-    process.stdout.write(`tmct plan: "${request}"\n`);
-    if (result.refused) {
-      process.stdout.write(`no plan found — ${Array.isArray(result.why) ? result.why.join("; ") : result.why}\n`);
-      if (result.c1Why) {
-        process.stdout.write(`(the direct router also declined: ${Array.isArray(result.c1Why) ? result.c1Why.join("; ") : result.c1Why})\n`);
+    // The default (no --tools) toolset is re-read AFTER the ctx build: the
+    // memory store's taught: capability records only register there, and a
+    // world goal refuses when its taught record is outside the toolset.
+    if (!toolsFlag) tools = declaredCapabilityNames();
+    try {
+      const result = await runCapabilityPlan(request, tools, ctx);
+      if (jsonFlag) {
+        process.stdout.write(JSON.stringify({ request, ...result }, null, 2) + "\n");
+        process.exit(result.refused ? 1 : 0);
       }
-      process.exit(1);
-    }
-    process.stdout.write(`driver: ${result.driver}\n\nsteps:\n`);
-    for (let i = 0; i < result.calls.length; i += 1) {
-      const c = result.calls[i];
-      let text = "";
-      try { text = await ctx.dispatch(c.name, c.input || {}).then((r) => (r.ok ? r.text : `(unresolved: ${r.error})`)); }
-      catch (e) { text = `(error: ${e?.message || e})`; }
-      process.stdout.write(`  ${i + 1}. ${c.name} ${JSON.stringify(c.input || {})}\n     ${String(text).split("\n").join("\n     ")}\n`);
-    }
-    if (result.composed !== undefined && result.composed !== null) {
-      process.stdout.write(`\ncomposed answer (${result.composed.length}): ${result.composed.length ? result.composed.join(", ") : "(empty set)"}\n`);
+      process.stdout.write(`tmct plan: "${request}"\n`);
+      if (result.refused) {
+        process.stdout.write(`no plan found — ${Array.isArray(result.why) ? result.why.join("; ") : result.why}\n`);
+        if (result.c1Why) {
+          process.stdout.write(`(the direct router also declined: ${Array.isArray(result.c1Why) ? result.c1Why.join("; ") : result.c1Why})\n`);
+        }
+        process.exit(1);
+      }
+      process.stdout.write(`driver: ${result.driver}\n\nsteps:\n`);
+      for (let i = 0; i < result.calls.length; i += 1) {
+        const c = result.calls[i];
+        let text = "";
+        // taught: records are simulated, never dispatchable — dispatching one
+        // would print a misleading "unknown tool" under an honest plan step.
+        if (c.name.startsWith("taught:")) text = "(simulated over the taught rules — execute it in chat with \"next\")";
+        else {
+          try { text = await ctx.dispatch(c.name, c.input || {}).then((r) => (r.ok ? r.text : `(unresolved: ${r.error})`)); }
+          catch (e) { text = `(error: ${e?.message || e})`; }
+        }
+        process.stdout.write(`  ${i + 1}. ${c.name} ${JSON.stringify(c.input || {})}\n     ${String(text).split("\n").join("\n     ")}\n`);
+      }
+      if (result.composed !== undefined && result.composed !== null) {
+        process.stdout.write(`\ncomposed answer (${result.composed.length}): ${result.composed.length ? result.composed.join(", ") : "(empty set)"}\n`);
+      } else if (result.observed) {
+        process.stdout.write(`\n${result.observed}\n`);
+      }
+    } finally {
+      for (const dispose of ctx.disposers || []) dispose();
     }
     return;
   }

package/data/games/crates.txt

@@ -0,0 +1,24 @@
+# crates — a second taught game, same closed frames as hanoi-3.
+# Lines starting with # are skipped by import.
+# No size order here: stacking is legal onto any clear crate or pallet, so this
+# domain exercises the comparator precondition being optional. Goals can be a
+# conjunction — teach several goal sentences before "solve it".
+#
+# After `tmct import --file crates.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   crate-c rests on crate-a. crate-a rests on pallet-1. crate-b rests on pallet-2.
+#   the goal is that crate-a rests on crate-b. the goal is that crate-b rests on pallet-2.
+#   solve it.
+#
+# (2 moves: clear crate-a, then stack it — the solver may route crate-c to
+# pallet-3 or onto crate-b; both are optimal.)
+a crate is a kind of container.
+a pallet is a kind of place.
+crate-a is a crate. crate-b is a crate. crate-c is a crate.
+pallet-1 is a pallet. pallet-2 is a pallet. pallet-3 is a pallet.
+you can stack a crate onto a pallet.
+you can stack a crate onto a crate.
+to stack a crate onto a target, nothing may rest on the crate.
+to stack a crate onto a target, nothing may rest on the target.
+stacking a crate onto a target makes the crate rest on the target.
+a crate renders as a block. a pallet renders as a slot.

package/data/games/hanoi-3.txt

@@ -0,0 +1,30 @@
+# hanoi-3 — a taught game definition. Lines starting with # are skipped by import.
+# After `tmct import --file hanoi-3.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   disk-1 rests on disk-2. disk-2 rests on disk-3. disk-3 rests on peg-a.
+#   the goal is that every disk rests on peg-c. solve it.
+#
+# Variations, each stretching a different direction:
+#   scale      — first teach: "disk-4 is a disk. disk-3 is smaller than disk-4."
+#                start all four on peg-a, same goal. 15 moves (2^4 - 1).
+#   any start  — disk-1 rests on peg-b. disk-2 rests on peg-c. disk-3 rests on peg-a.
+#                the goal is that every disk rests on peg-c. solve it.
+#   other goal — same start, "the goal is that every disk rests on peg-b. solve it."
+#   partial    — "the goal is that disk-3 rests on peg-c. solve it."
+#                (a one-fact goal; exercises the non-universal goal frame)
+#   legality   — "what moves are legal now?"  (findReachableSet, one ply, no plan)
+#   read-back  — "what rests on disk-2?" / "is disk-1 clear?"  (plain fact questions,
+#                no planning involved)
+a disk is a kind of game piece.
+a peg is a kind of place.
+disk-1 is a disk. disk-2 is a disk. disk-3 is a disk.
+peg-a is a peg. peg-b is a peg. peg-c is a peg.
+disk-1 is smaller than disk-2. disk-1 is smaller than disk-3.
+disk-2 is smaller than disk-3.
+you can move a disk onto a peg.
+you can move a disk onto a disk.
+to move a disk onto a target, nothing may rest on the disk.
+to move a disk onto a target, nothing may rest on the target.
+to move a disk onto a disk, the disk must be smaller than the target.
+moving a disk onto a target makes the disk rest on the target.
+a disk renders as a block. a peg renders as a slot.

package/data/games/river.txt

@@ -0,0 +1,33 @@
+# river — the wolf/goat/cabbage crossing, taught with the same closed frames
+# as hanoi-3 plus two new families: a co-travel effect (the farmer rides every
+# crossing) and the "may not be with ... without ..." constraint.
+# Lines starting with # are skipped by import.
+#
+# After `tmct import --file river.txt`, try this in `tmct chat` (or via --prompt):
+#
+#   wolf-1 stands on bank-east. goat-1 stands on bank-east.
+#   cabbage-1 stands on bank-east. farmer-1 stands on bank-east.
+#   the goal is that every passenger stands on bank-west. solve it.
+#
+# The classic optimum is 7 crossings: goat over, farmer back, wolf over, goat
+# back, cabbage over, farmer back, goat over. From the opening position exactly
+# 1 move is legal (ferry the goat) — every other crossing leaves the wolf with
+# the goat, or the goat with the cabbage, without the farmer.
+#
+# Other things to try:
+#   legality  — "what moves are legal now?"  (one ply, no plan; shows the
+#               constraint pruning: 1 legal move at the start)
+#   read-back — "what stands on bank-east?"  (plain fact question, no planning)
+a passenger is a kind of game piece.
+a bank is a kind of place.
+wolf-1 is a wolf. wolf-1 is a passenger.
+goat-1 is a goat. goat-1 is a passenger.
+cabbage-1 is a cabbage. cabbage-1 is a passenger.
+farmer-1 is a farmer.
+bank-east is a bank. bank-west is a bank.
+you can ferry a passenger onto a bank.
+you can ferry a farmer onto a bank.
+ferrying a passenger onto a bank makes the passenger stand on the target.
+ferrying a passenger onto a bank makes the farmer stand on the target.
+to ferry a passenger onto a bank, the wolf may not be with the goat without the farmer.
+to ferry a passenger onto a bank, the goat may not be with the cabbage without the farmer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.10.14",
+  "version": "1.11.5",
   "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.",