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

package/src/domain.mjs

@@ -0,0 +1,271 @@
+// domain.mjs — the generic taught-action interpreter.
+//
+// Pure functions from taught rows to planner inputs: no I/O, and no knowledge
+// of any particular game — every class, individual, predicate, and action
+// arrives as data from the memory store's fact/Rule rows. Plugs into
+// planning.mjs's findActionPath as its applyActions.
+
+const MEMBER_EDGE_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+const SNAPSHOT_RE = /^(.+)@step(\d+)$/;
+
+/** Trim a taught term defensively: some teach frames keep a sentence's
+ *  trailing punctuation in the captured object. */
+const normTerm = (value) => String(value ?? "").trim().replace(/[.!?]+$/, "");
+
+/** Predicates in Rule slots are stored bare (normFactTerm strips prefixes);
+ *  fact rows carry the prefixed form. */
+const attachPrefix = (predicate) => {
+  const p = normTerm(predicate);
+  return p.includes(":") ? p : `mgx:${p}`;
+};
+
+const rowSort = (a, b) =>
+  a.subject.localeCompare(b.subject) ||
+  a.predicate.localeCompare(b.predicate) ||
+  a.object.localeCompare(b.object);
+
+const normRow = (row) => ({
+  subject: normTerm(row.subject),
+  predicate: normTerm(row.predicate),
+  object: normTerm(row.object),
+});
+
+export class PlanBudgetError extends Error {
+  constructor(groundings, budget) {
+    super(`action grounding count ${groundings} exceeds the budget of ${budget}`);
+    this.name = "PlanBudgetError";
+    this.groundings = groundings;
+    this.budget = budget;
+  }
+}
+
+/** Compile fact + Rule rows into a planning domain:
+ *  { actions, classMembers, dynamicPredicates, ordering }. */
+export function compileDomain(factRows, ruleRows) {
+  const byName = new Map();
+  for (const rule of ruleRows || []) {
+    if (!String(rule.kind || "").startsWith("action-")) continue;
+    const name = normTerm(rule.name);
+    if (!byName.has(name)) byName.set(name, { name, signatures: [], preconds: [], effects: [] });
+    const family = byName.get(name);
+    const slots = rule.slots || {};
+    if (rule.kind === "action-signature") {
+      family.signatures.push({
+        subjectClass: normTerm(slots.subjectClass),
+        targetClass: normTerm(slots.targetClass),
+      });
+    } else if (rule.kind === "action-precond") {
+      family.preconds.push({
+        shape: normTerm(slots.shape),
+        predicate: attachPrefix(slots.predicate),
+        role: normTerm(slots.role),
+        scope: normTerm(slots.scope),
+      });
+    } else if (rule.kind === "action-effect") {
+      family.effects.push({
+        predicate: attachPrefix(slots.predicate),
+        subjectRole: normTerm(slots.subjectRole),
+        objectRole: normTerm(slots.objectRole),
+      });
+    }
+  }
+  const actions = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  for (const action of actions) {
+    action.signatures.sort((a, b) =>
+      a.subjectClass.localeCompare(b.subjectClass) || a.targetClass.localeCompare(b.targetClass));
+    action.preconds.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    action.effects.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  }
+
+  // Class membership from typing edges. A member is a subject with a typing
+  // edge into the class and no typing edge pointing at itself (a leaf).
+  const edges = (factRows || []).map(normRow).filter((r) => MEMBER_EDGE_PREDICATES.has(r.predicate));
+  const hasIncoming = new Set(edges.map((r) => r.object));
+  const classMembers = {};
+  for (const edge of edges) {
+    if (hasIncoming.has(edge.subject)) continue;
+    (classMembers[edge.object] ??= []).push(edge.subject);
+  }
+  for (const members of Object.values(classMembers)) {
+    members.sort();
+    // de-dup while keeping order
+    for (let i = members.length - 1; i > 0; i -= 1) if (members[i] === members[i - 1]) members.splice(i, 1);
+  }
+
+  const dynamicPredicates = new Set();
+  for (const action of actions) for (const effect of action.effects) dynamicPredicates.add(effect.predicate);
+
+  const ordering = (factRows || [])
+    .map(normRow)
+    .filter((r) => !dynamicPredicates.has(r.predicate) && !MEMBER_EDGE_PREDICATES.has(r.predicate))
+    .sort(rowSort);
+
+  return { actions, classMembers, dynamicPredicates, ordering };
+}
+
+const domainIndividuals = (domain) => {
+  const out = new Set();
+  for (const action of domain.actions) {
+    for (const sig of action.signatures) {
+      for (const m of domain.classMembers[sig.subjectClass] || []) out.add(m);
+      for (const m of domain.classMembers[sig.targetClass] || []) out.add(m);
+    }
+  }
+  return out;
+};
+
+/** The current state as canonical sorted rows over the domain's dynamic
+ *  predicates. Prefers the newest @stepN snapshot when one exists, so a
+ *  re-plan after per-step execution never reads the stale step-0 board. */
+export function stateFromFacts(factRows, domain) {
+  const individuals = domainIndividuals(domain);
+  const subjectClasses = new Set();
+  for (const action of domain.actions) for (const sig of action.signatures) subjectClasses.add(sig.subjectClass);
+  const subjects = new Set();
+  for (const cls of subjectClasses) for (const m of domain.classMembers[cls] || []) subjects.add(m);
+
+  const rows = (factRows || []).map(normRow).filter((r) => domain.dynamicPredicates.has(r.predicate));
+  let maxStep = -1;
+  for (const row of rows) {
+    const m = SNAPSHOT_RE.exec(row.subject);
+    if (m && individuals.has(m[1])) maxStep = Math.max(maxStep, Number(m[2]));
+  }
+  const state = [];
+  for (const row of rows) {
+    const m = SNAPSHOT_RE.exec(row.subject);
+    if (maxStep >= 0) {
+      if (!m || Number(m[2]) !== maxStep) continue;
+      const base = m[1];
+      if (subjects.has(base)) state.push({ subject: base, predicate: row.predicate, object: normTerm(row.object.replace(SNAPSHOT_RE, "$1")) });
+    } else if (!m && subjects.has(row.subject)) {
+      state.push(row);
+    }
+  }
+  state.sort(rowSort);
+  return state;
+}
+
+/** Canonical identity for a state (rows are kept sorted). NUL-joined so
+ *  multi-word terms can never collide with the separator; spelled without an
+ *  escape sequence because tooling has twice turned a source-level \\0 into a
+ *  literal NUL byte in this repo. */
+const SEP = String.fromCharCode(0);
+export function stateKeyFor(state) {
+  return state.map((r) => [r.subject, r.predicate, r.object].join(SEP)).join("\n");
+}
+
+const precondApplies = (precond, target, domain) =>
+  precond.scope === "any" || (domain.classMembers[precond.scope] || []).includes(target);
+
+function precondHolds(precond, subject, target, state, domain) {
+  const roleTerm = precond.role === "target" ? target : subject;
+  if (precond.shape === "no-incoming") {
+    return !state.some((r) => r.predicate === precond.predicate && r.object === roleTerm);
+  }
+  if (precond.shape === "comparator") {
+    const left = roleTerm;
+    const right = precond.role === "target" ? subject : target;
+    return domain.ordering.some((r) =>
+      r.subject === left && r.predicate === precond.predicate && r.object === right);
+  }
+  return false;
+}
+
+function applyEffects(effects, subject, target, state) {
+  const roleTerm = (role) => (role === "target" ? target : subject);
+  let rows = state;
+  let changed = false;
+  for (const effect of effects) {
+    const effSubject = roleTerm(effect.subjectRole);
+    const effObject = roleTerm(effect.objectRole);
+    const already = rows.some((r) =>
+      r.subject === effSubject && r.predicate === effect.predicate && r.object === effObject);
+    if (already) continue;
+    rows = rows.filter((r) => !(r.subject === effSubject && r.predicate === effect.predicate));
+    rows = [...rows, { subject: effSubject, predicate: effect.predicate, object: effObject }];
+    changed = true;
+  }
+  if (!changed) return null;
+  return [...rows].sort(rowSort);
+}
+
+/** Every legal grounded action from `state`, with its successor.
+ *  Deterministic: actions, signatures, and members are walked sorted. */
+export function movesFromRules(state, domain, { budget = 5000 } = {}) {
+  let groundings = 0;
+  for (const action of domain.actions) {
+    for (const sig of action.signatures) {
+      groundings += (domain.classMembers[sig.subjectClass] || []).length *
+        (domain.classMembers[sig.targetClass] || []).length;
+    }
+  }
+  if (groundings > budget) throw new PlanBudgetError(groundings, budget);
+
+  const out = [];
+  for (const action of domain.actions) {
+    const [verb, particle] = action.name.split(/\s+/);
+    for (const sig of action.signatures) {
+      for (const subject of domain.classMembers[sig.subjectClass] || []) {
+        for (const target of domain.classMembers[sig.targetClass] || []) {
+          if (subject === target) continue;
+          let ok = true;
+          for (const precond of action.preconds) {
+            if (!precondApplies(precond, target, domain)) continue;
+            if (!precondHolds(precond, subject, target, state, domain)) { ok = false; break; }
+          }
+          if (!ok) continue;
+          const nextState = applyEffects(action.effects, subject, target, state);
+          if (!nextState) continue;
+          out.push({
+            action: {
+              name: action.name,
+              subject,
+              target,
+              label: [verb, subject, particle, target].filter(Boolean).join(" "),
+            },
+            nextState,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Compile goal specs ({universal, term, predicate, object}) into a pure
+ *  state predicate. Satisfaction is a transitive walk along the goal
+ *  predicate: a stacked member reaches the goal object through its support
+ *  chain, which a direct row lookup cannot see. */
+export function compileGoal(goalSpecs, domain) {
+  const specs = (goalSpecs || []).map((g) => ({
+    universal: Boolean(g.universal),
+    term: normTerm(g.term),
+    predicate: attachPrefix(g.predicate),
+    object: normTerm(g.object),
+  }));
+  const checks = [];
+  for (const spec of specs) {
+    const members = spec.universal ? domain.classMembers[spec.term] || [] : [spec.term];
+    if (spec.universal && members.length === 0) {
+      throw new Error(`the goal names "${spec.term}" as a class, but it has no known members`);
+    }
+    for (const member of members) checks.push({ member, predicate: spec.predicate, object: spec.object });
+  }
+  return function isGoal(state) {
+    for (const check of checks) {
+      let current = check.member;
+      let reached = false;
+      const seen = new Set();
+      for (let hop = 0; hop <= state.length; hop += 1) {
+        if (seen.has(current)) break;
+        seen.add(current);
+        const row = state.find((r) => r.subject === current && r.predicate === check.predicate);
+        if (!row) break;
+        if (row.object === check.object) { reached = true; break; }
+        current = row.object;
+      }
+      if (!reached) return false;
+    }
+    return true;
+  };
+}

package/src/import-file.mjs

@@ -0,0 +1,86 @@
+// import-file.mjs — `tmct import --file <definition.txt>`: teach a plain-text
+// definition file, one sentence at a time, through the SAME recognizers the
+// live chat uses (runTurn) — no separate parser, no guessing.
+//
+// The report is loud on purpose: a definition file that half-teaches produces
+// a planner that finds wrong plans or no plans with no visible cause, so every
+// sentence's outcome is printed and any decline makes the caller exit non-zero.
+//
+// `#` lines are comments (skipped, counted, never "declined") — a definition
+// file carries its own example prompts this way.
+
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+import { runTurn, uuidv7 } from "./chat.mjs";
+import { loadMemory, readFactRows, appendFact, openMemoryBackend } from "./memory/core.mjs";
+import { loadConfig } from "./config.mjs";
+import { splitSentences } from "./sentences.mjs";
+
+/**
+ * Teach every sentence of `filePath` into `repoRoot`'s memory store.
+ *
+ * @returns {Promise<{
+ *   sentences: number, taught: string[], declined: {sentence: string, reason: string}[],
+ *   comments: number, report: string
+ * }>}
+ */
+export async function importDefinitionFile(repoRoot, filePath, { env = process.env } = {}) {
+  const root = resolve(repoRoot);
+  const abs = resolve(root, filePath);
+  const sourceTag = `import:${basename(abs)}`;
+  const text = await readFile(abs, "utf8");
+
+  const lines = text.split("\n");
+  const commentLines = lines.filter((l) => l.trim().startsWith("#"));
+  const body = lines.filter((l) => !l.trim().startsWith("#")).join("\n");
+  const sentences = splitSentences(body).map((s) => s.trim()).filter(Boolean);
+
+  const { loadTomlConfig } = await import("./toml-config.mjs");
+  const raw = await loadTomlConfig(root).catch(() => null);
+  const backend = String(raw?.memory?.backend || "default").trim().toLowerCase();
+  const { dir: memoryDir, close } = await openMemoryBackend(root, backend);
+  const config = loadConfig(env, root);
+
+  const taught = [];
+  const declined = [];
+  const reportLines = [`${basename(abs)} — ${sentences.length} sentence(s), ${commentLines.length} comment line(s) skipped`, ""];
+
+  try {
+    for (const sentence of sentences) {
+      const before = readFactRows(await loadMemory(memoryDir));
+      const beforeById = new Map(before.map((r) => [r.id, r.provenance]));
+      const { record } = await runTurn(sentence, { config, memoryDir, sessionId: uuidv7() });
+      const ok = record?.via === "assert" && !record?.miss;
+      if (!ok) {
+        const reason = String(record?.answer || "").split("\n")[0] || "not a recognized declarative shape";
+        declined.push({ sentence, reason });
+        reportLines.push(`  DECLINED — ${sentence} — ${reason}`);
+        continue;
+      }
+      taught.push(sentence);
+      reportLines.push(`  taught — ${sentence}`);
+      // Layer the additive audit tag onto the fact rows this sentence touched
+      // (appendFact unions provenance by id — re-import is idempotent). Rule
+      // teaches touch no fact rows; the Rule's own provenance already names
+      // the teach source.
+      const after = readFactRows(await loadMemory(memoryDir));
+      const touched = after.filter((r) => beforeById.get(r.id) !== r.provenance);
+      for (const row of touched) {
+        await appendFact(memoryDir, {
+          subject: row.subject, predicate: row.predicate, object: row.object,
+          provenance: sourceTag, quantifier: row.quantifier || "",
+        });
+      }
+    }
+  } finally {
+    await close();
+  }
+
+  reportLines.push("");
+  reportLines.push(
+    `${taught.length} taught, ${declined.length} declined, ${commentLines.length} comment line(s) skipped`
+    + (declined.length ? " — a half-taught game plans wrongly or not at all; fix the declined sentence(s) and re-import" : ""),
+  );
+  return { sentences: sentences.length, taught, declined, comments: commentLines.length, report: reportLines.join("\n") };
+}

package/src/init.mjs

@@ -13,7 +13,7 @@
 // write the same `.tmct/memory/corpus-seed.json`, so whichever runs first wins. Re-declared
 // here rather than imported, to keep init off chat.mjs's heavy module graph.
 
-import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, writeFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { stringify as stringifyToml } from "smol-toml";
@@ -197,6 +197,51 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
     }
   }
 
+  // ---- 1b. Importable starters (.tmct/imports) — game definition files a
+  // fresh repo can discover by listing a directory, plus a README naming the
+  // corpus bundle ids `tmct import` accepts. Game files are copied (import
+  // --file consumes them directly); corpus bundles are listed by id, not
+  // copied — the wordnet-scale ones are far too large to scaffold into every
+  // repo, and `tmct import --corpus <id>` resolves ids without a local copy.
+  {
+    const importsDir = join(paths.tmct, "imports");
+    const gamesDir = join(importsDir, "games");
+    const shippedGames = join(dirname(fileURLToPath(import.meta.url)), "..", "data", "games");
+    if (!(await exists(gamesDir))) {
+      await mkdir(gamesDir, { recursive: true });
+      created.push(gamesDir);
+    }
+    try {
+      for (const f of await readdir(shippedGames)) {
+        if (!f.endsWith(".txt")) continue;
+        const dest = join(gamesDir, f);
+        if (!(await exists(dest))) {
+          await copyFile(join(shippedGames, f), dest);
+          created.push(dest);
+        }
+      }
+    } catch { /* no shipped games directory — scaffold stays empty */ }
+    const readmePath = join(importsDir, "README.txt");
+    if (!(await exists(readmePath))) {
+      await writeFile(readmePath, [
+        "Importable starters for this repo.",
+        "",
+        "Game definitions (plain controlled-English sentences; # lines are comments):",
+        "  tmct import --file .tmct/imports/games/hanoi-3.txt",
+        "",
+        "Corpus bundles (activate by id — no local copy needed):",
+        "  tmct import --corpus human | human-medium | human-large",
+        "  tmct import --corpus seon | conceptnet | aws | python | java | general",
+        "  tmct import --corpus wordnet-xl | wordnet-full | namenet   (large: tens of thousands of facts)",
+        "",
+        "Ontology / lexicon resources are file paths declared as extension entries:",
+        "  tmct import --ontology <path> | --lexicon <path>",
+        "",
+      ].join("\n"));
+      created.push(readmePath);
+    }
+  }
+
   // ---- 2. The externalised config (preserve an existing file unless force) ----
   let config = defaultConfig();
   // Persona overrides apply only to a fresh write.