@polycode-projects/the-mechanical-code-talker 2.11.12 → 3.0.1

package/README.md

@@ -1150,8 +1150,10 @@ node bin/tmct.mjs cli tmct_untested '{"repo_path":"examples/mini-webapp"}'
 
 ## The repository interface
 
-tmct is not an indexer, so it consumes a graph through a typed contract any
-producer can implement. That contract is first-class: a **versioned (1.1.0),
+tmct consumes a graph through a typed contract any producer can implement —
+including its own `tmct index` command, which walks a repo's source and writes
+the graph, and any external producer (seonix, a CI indexer, a hand-written JSON
+file) feeding the same seam. That contract is first-class: a **versioned (1.1.0),
 OWL-grounded, machine-readable service definition** (`docs/repository-interface.md`
 plus a JSON schema) of every service, its arguments, result types, and error
 contract. The interface returns a miss as a normal value. It never throws to

package/bin/tmct.mjs

@@ -2,7 +2,8 @@
 // tmct — The Mechanical Code Talker. The headline entry is CHAT: a bare
 // invocation drops you into a tolerant, offline, $0 prompt that guides you
 // toward precision queries about a repository (ELIZA/PARRY-style, but obsessed
-// with software). No model calls; tmct keeps no codebase index of its own.
+// with software). No model calls; tmct indexes a repo on request (tmct index)
+// or reads a graph any other producer wrote.
 //
 //   tmct                                   → interactive chat (the headline)
 //   tmct chat [--repo <abs>] [--plain]     → same, explicit
@@ -49,7 +50,7 @@ process.on("warning", (warning) => {
 const HELP = `tmct — The Mechanical Code Talker
 
 A tolerant, offline, $0 chat that guides you toward precision queries about a
-software repository. No model calls; no codebase index of its own.
+software repository. No model calls; index a repo with \`tmct index\`, or read any producer's graph.
 
 Usage:
 ${renderUsage()}
@@ -919,6 +920,35 @@ async function main() {
     // on disk: one copy-paste Bash invocation per tool, rewritten on every init.
     process.stdout.write(`cold-tool catalog: ${await writeToolsCatalog(repoRoot)}\n`);
 
+    // `--with-persona code`: on top of the corpus-vocabulary bias `initRepo` just wrote,
+    // also run the repository INDEXER (`tmct index`'s own machinery) against this repo's
+    // real source, so one command produces a `.tmct/graph.json` backed by the repo itself —
+    // not just a bias preset. `chat --repo` already reads whatever graph is on disk; this
+    // is the onboarding path that puts one there. Failure-tolerant like the corpus seed
+    // above: a repo that can't be indexed (no supported source, or a parse error) degrades
+    // to an initialized-but-graphless repo, never a crashed init.
+    if (personaName === "code") {
+      try {
+        const { indexRepository } = await import("../src/index/index-repo.mjs");
+        const stats = await indexRepository(repoRoot);
+        for (const { pass, message } of stats.gitErrors || []) {
+          process.stderr.write(`tmct init: WARNING git history pass '${pass}' — ${message} (graph built without those edges)\n`);
+        }
+        const perLang = Object.entries(stats.perLang)
+          .map(([lang, s]) => `${lang}: ${s.modules} modules, ${s.symbols} symbols`).join("; ");
+        const kib = (stats.bytes / 1024).toFixed(1);
+        process.stdout.write(
+          `code persona: indexed the repo — wrote ${stats.graphFile} (${stats.modules} modules, ${stats.symbols} symbols; ${kib} KiB)\n`
+          + (perLang ? `${perLang}\n` : "no supported source found under the repo\n"),
+        );
+        if (stats.failures?.length) {
+          process.stderr.write(`tmct init: ${stats.failures.length} file(s) failed to parse (skipped): ${stats.failures.slice(0, 5).join(", ")}${stats.failures.length > 5 ? ", …" : ""}\n`);
+        }
+      } catch (e) {
+        process.stderr.write(`tmct init: code persona indexing skipped (${e?.message || e})\n`);
+      }
+    }
+
     // `--corpus`/`--ontology`/`--lexicon` now mean "activate this bundle and
     // PERSIST that into tmct.toml" — so a second `tmct init` (or the next chat
     // bootstrap) remembers the choice, unlike the old ad hoc path, which had
@@ -986,6 +1016,36 @@ async function main() {
     return;
   }
 
+  if (mode === "index") {
+    // `tmct index` — the code-graph PRODUCER. Walks a repo's own source, parses
+    // it (JS/TS today, via the TypeScript compiler API), reads git history, and
+    // writes <repo>/.tmct/graph.json — the same artifact chat/serve/cli read
+    // through the provider seam. This is tmct producing a graph for the first
+    // time; the seam that consumes one is unchanged.
+    const rest = process.argv.slice(3);
+    const { strFlag } = await import("../src/services/cli-args.mjs");
+    const { resolve: resolvePath } = await import("node:path");
+    const { indexRepository } = await import("../src/index/index-repo.mjs");
+    const repoFlag = strFlag(rest, ["--repo"]);
+    const repoRoot = repoFlag ? resolvePath(process.cwd(), repoFlag) : process.cwd();
+    const noHistory = rest.includes("--no-history");
+    const stats = await indexRepository(repoRoot, noHistory ? { historyDepth: 0 } : {});
+    for (const { pass, message } of stats.gitErrors || []) {
+      process.stderr.write(`tmct index: WARNING git history pass '${pass}' — ${message} (graph built without those edges)\n`);
+    }
+    const perLang = Object.entries(stats.perLang)
+      .map(([lang, s]) => `${lang}: ${s.modules} modules, ${s.symbols} symbols`).join("; ");
+    const kib = (stats.bytes / 1024).toFixed(1);
+    process.stdout.write(
+      `tmct index — wrote ${stats.graphFile} (${stats.modules} modules, ${stats.symbols} symbols; ${kib} KiB)\n`
+      + (perLang ? `${perLang}\n` : "no supported source found under the repo\n"),
+    );
+    if (stats.failures?.length) {
+      process.stderr.write(`tmct index: ${stats.failures.length} file(s) failed to parse (skipped): ${stats.failures.slice(0, 5).join(", ")}${stats.failures.length > 5 ? ", …" : ""}\n`);
+    }
+    return;
+  }
+
   if (mode === "import") {
     // `tmct import` — activate+seed into an ALREADY-initialized repo, reusing
     // the SAME resolvePluggableInput/activatePluggableInput seam `init`'s own

package/corpus/tier2/generate.mjs

@@ -173,7 +173,7 @@ export const CORPUSES = {
     ],
   },
 
-  // PLAN_AGENTS.md Phase 1's "wider general-knowledge seed set" bullet: the
+  // The wider general-knowledge seed set: the
   // three corpuses above are all code-domain-specific (a LANGUAGE or a cloud
   // DOMAIN); this one deliberately is NOT — everyday-knowledge concepts (the
   // natural world, weather, food, common objects) with zero code-domain

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.12",
+  "version": "3.0.1",
   "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.",
+  "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; indexes a repo on request (tmct index) or reads any producer's graph.",
   "keywords": [
     "chatbot",
     "no-llm",
@@ -78,6 +78,7 @@
     "ink": "^7.1.0",
     "react": "^19.2.7",
     "smol-toml": "^1.7.0",
+    "typescript": "~5.6.2",
     "wink-eng-lite-web-model": "^1.8.1",
     "wink-nlp": "^2.4.0"
   },

package/src/adapters/source.mjs

@@ -3,12 +3,14 @@
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
 //
-// This module is the PROVIDER SEAM (docs/adapter-contract.md):
-// any graph producer can feed tmct either by writing the entities-payload JSON
-// where config.graphFile points, or by registering a custom loader with
-// registerProvider() — no indexer is ever imported here. tmct only READS
-// through this seam; its own writes go to .tmct/memory/ (src/memory/), never
-// back into a provider's artifact.
+// This module is the READ SEAM (docs/adapter-contract.md): any graph producer
+// can feed tmct either by writing the entities-payload JSON where
+// config.graphFile points, or by registering a custom loader with
+// registerProvider(). The PRODUCER lives elsewhere — tmct's own `tmct index`
+// (src/index/) is one such producer, and it writes through that same file path,
+// not through this module. Keeping the reader and the producer in separate module
+// trees is deliberate: this module only READS, and tmct's own writes go to
+// .tmct/memory/ (src/memory/), never back into a provider's graph artifact.
 
 import { readFile } from "node:fs/promises";
 import { ToolError } from "./config.mjs";

package/src/adapters/toml-config.mjs

@@ -102,6 +102,14 @@ export async function normalizeConfig(raw, { configDir } = {}) {
     const arr = Array.isArray(src.graph_files) ? src.graph_files : [src.graph_files];
     cfg.graphFiles = arr.map((p) => resolve(dir, String(p)));
   }
+  // [graph] read_only — a chat session against this repo READS the graph but
+  // writes nothing back into its .tmct/: no per-turn session upsert into
+  // graph.json, no transcript/sidecar logs, no memory droppings. A committed
+  // example fixture sets it so a plain `tmct chat --repo examples/<x>` (no
+  // --ephemeral) can never rewrite the hand-stamped graph. Sparse like the
+  // rest: absent when unset, so "unset" stays distinguishable from "false".
+  const graph = src.graph || {};
+  if (graph.read_only !== undefined) cfg.graph = { readOnly: graph.read_only };
   const corpus = src.corpus || {};
   if (corpus.tier !== undefined) cfg.corpus = { tier: corpus.tier };
   const seed = src.seed || {};

package/src/domain/cli-verbs.mjs

@@ -68,6 +68,15 @@ export const CLI_VERBS = [
       { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["write tmct.toml's [memory] backend", "(same flag name as `tmct chat`) — a later `tmct chat`", "in this repo picks it up with no flag needed"] },
     ],
   },
+  {
+    mode: "index",
+    errorLabel: "index",
+    usage: "tmct index [--repo <abs>]",
+    prose: ["produce a code graph from a repo's OWN source (default: cwd):"],
+    flags: [
+      { flag: "[--no-history]", prose: ["walk the tree, parse JS/TS with the TypeScript compiler", "API, read git history, and write <repo>/.tmct/graph.json —", "the artifact chat/serve/cli then read. --no-history skips", "the git passes (no commit/touches/cochange edges)"] },
+    ],
+  },
   {
     mode: "import",
     errorLabel: "import",

package/src/domain/codeplan/graph-delta.mjs

@@ -0,0 +1,239 @@
+// graph-delta.mjs — the planning STATE for code changes and the closed
+// vocabulary of effects that move between states. Pure, no I/O.
+//
+// A code-graph snapshot is the typed entity/edge payload the repo already
+// queries (codegraph.mjs / repository-interface.mjs), reduced to the two things
+// a planner moves over: entities (id + class + title) and edges
+// (subject/predicate/object). An action's declared EFFECT is a graph delta — a
+// short list of add/del-entity, add/del-edge, retitle-entity tokens over the
+// ontology's closed classes and predicates. Plan search projects snapshots
+// without touching any base state, the way domain.mjs projects board@step
+// snapshots.
+//
+// The state KEY canonicalizes the resulting graph, not the path taken to it, so
+// two orderings of independent steps that reach the same graph are one state —
+// which is what lets findActionPath's cycle detection merge them, and what keeps
+// the representation e-class-friendly (PLAN_CODE.md §3.3).
+
+/** The entity classes an effect may add — the ontology's code-entity classes
+ *  (ontology/tmct-core.ttl; the same set codegraph.mjs's graph carries). Closed:
+ *  an effect naming a class outside this set is a programming error, not a
+ *  guess. */
+export const ENTITY_CLASSES = Object.freeze([
+  "Module", "Class", "Function", "Method", "Attribute", "GlobalVariable", "Commit", "Session",
+]);
+
+/** The edge predicates an effect may add or remove — repository-interface.mjs's
+ *  EDGE_KINDS, restated here because a domain module imports nothing outside its
+ *  own layer (test/estate/import-layers). Kept in step by
+ *  test/domain/codeplan-graph-delta: a drift between the two lists fails it. */
+export const EDGE_PREDICATES = Object.freeze([
+  "imports", "calls", "callsSymbol", "defines", "tests",
+  "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+]);
+
+/** The closed effect vocabulary — every way an operator's declared delta can
+ *  change a graph state. retitle-entity is the rename primitive: an entity keeps
+ *  its id (its stable graph identity) while its human title changes. */
+export const EFFECT_OPS = Object.freeze([
+  "add-entity", "del-entity", "add-edge", "del-edge", "retitle-entity",
+]);
+
+const ENTITY_CLASS_SET = new Set(ENTITY_CLASSES);
+const EDGE_PREDICATE_SET = new Set(EDGE_PREDICATES);
+const EFFECT_OP_SET = new Set(EFFECT_OPS);
+
+// NUL-joined identity, the same discipline as domain.mjs's stateKeyFor: a
+// multi-word title can never collide with the field separator. Spelled via
+// fromCharCode because tooling has turned a source-level escape into a literal
+// NUL byte in this repo before.
+const SEP = String.fromCharCode(0);
+
+const str = (value) => String(value ?? "");
+
+const entitySort = (a, b) =>
+  a.id.localeCompare(b.id) || a.class.localeCompare(b.class) || a.title.localeCompare(b.title);
+
+const edgeSort = (a, b) =>
+  a.subject.localeCompare(b.subject) || a.predicate.localeCompare(b.predicate) || a.object.localeCompare(b.object);
+
+const normEntity = (e) => ({ id: str(e.id), class: str(e.class), title: str(e.title) });
+const normEdge = (r) => ({ subject: str(r.subject), predicate: str(r.predicate), object: str(r.object) });
+
+const dedupSorted = (rows, keyOf) => {
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    const key = keyOf(row);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(row);
+  }
+  return out;
+};
+
+/** An empty code-graph state. */
+export const emptyGraphState = () => ({ entities: [], edges: [] });
+
+/** Canonical, sorted, de-duplicated copy of a state — the shape every function
+ *  here returns, so a state is always in one normal form. */
+export function normalizeGraphState(state) {
+  const entities = dedupSorted(
+    (state?.entities || []).map(normEntity).sort(entitySort),
+    (e) => [e.id, e.class, e.title].join(SEP),
+  );
+  const edges = dedupSorted(
+    (state?.edges || []).map(normEdge).sort(edgeSort),
+    (r) => [r.subject, r.predicate, r.object].join(SEP),
+  );
+  return { entities, edges };
+}
+
+/** Throw unless an effect is a well-formed member of the closed vocabulary,
+ *  over the closed class/predicate sets. The gate every apply/diff runs first,
+ *  so a malformed delta never silently no-ops. */
+export function validateEffect(effect) {
+  const op = str(effect?.op);
+  if (!EFFECT_OP_SET.has(op)) throw new Error(`unknown effect op ${JSON.stringify(op)} (not in EFFECT_OPS)`);
+  if (op === "add-entity") {
+    if (!str(effect.id)) throw new Error("add-entity needs an id");
+    if (!ENTITY_CLASS_SET.has(str(effect.class))) throw new Error(`add-entity class ${JSON.stringify(str(effect.class))} is not an ENTITY_CLASS`);
+  } else if (op === "del-entity") {
+    if (!str(effect.id)) throw new Error("del-entity needs an id");
+  } else if (op === "retitle-entity") {
+    if (!str(effect.id)) throw new Error("retitle-entity needs an id");
+    if (!str(effect.title)) throw new Error("retitle-entity needs a title");
+  } else {
+    // add-edge / del-edge
+    if (!str(effect.subject) || !str(effect.object)) throw new Error(`${op} needs a subject and an object`);
+    if (!EDGE_PREDICATE_SET.has(str(effect.predicate))) throw new Error(`${op} predicate ${JSON.stringify(str(effect.predicate))} is not an EDGE_PREDICATE`);
+  }
+  return op;
+}
+
+const hasEntity = (state, id) => state.entities.some((e) => e.id === id);
+const edgeIncident = (state, id) => state.edges.some((r) => r.subject === id || r.object === id);
+
+/** Apply one effect to a state, returning a NEW normalized state (the input is
+ *  never mutated). Throws on an effect that cannot apply to this state — a
+ *  duplicate add, a delete of something absent, an edge onto a missing endpoint,
+ *  or a del-entity that would leave a dangling edge. A precondition that should
+ *  have blocked the move is the caller's job (operators.mjs); this layer fails
+ *  loud rather than producing an ill-formed graph. */
+export function applyGraphEffect(state, effect) {
+  const s = normalizeGraphState(state);
+  const op = validateEffect(effect);
+  if (op === "add-entity") {
+    const id = str(effect.id);
+    if (hasEntity(s, id)) throw new Error(`add-entity: ${id} already exists`);
+    s.entities.push({ id, class: str(effect.class), title: str(effect.title) });
+  } else if (op === "del-entity") {
+    const id = str(effect.id);
+    if (!hasEntity(s, id)) throw new Error(`del-entity: ${id} does not exist`);
+    if (edgeIncident(s, id)) throw new Error(`del-entity: ${id} still has incident edges (remove them first)`);
+    s.entities = s.entities.filter((e) => e.id !== id);
+  } else if (op === "retitle-entity") {
+    const id = str(effect.id);
+    const ent = s.entities.find((e) => e.id === id);
+    if (!ent) throw new Error(`retitle-entity: ${id} does not exist`);
+    ent.title = str(effect.title);
+  } else if (op === "add-edge") {
+    const edge = normEdge(effect);
+    if (!hasEntity(s, edge.subject)) throw new Error(`add-edge: subject ${edge.subject} is not an entity`);
+    if (!hasEntity(s, edge.object)) throw new Error(`add-edge: object ${edge.object} is not an entity`);
+    s.edges.push(edge);
+  } else {
+    const edge = normEdge(effect);
+    if (!s.edges.some((r) => r.subject === edge.subject && r.predicate === edge.predicate && r.object === edge.object)) {
+      throw new Error(`del-edge: (${edge.subject} ${edge.predicate} ${edge.object}) does not exist`);
+    }
+    s.edges = s.edges.filter((r) => !(r.subject === edge.subject && r.predicate === edge.predicate && r.object === edge.object));
+  }
+  return normalizeGraphState(s);
+}
+
+/** Fold a list of effects onto a state in order. */
+export function applyGraphEffects(state, effects) {
+  let s = normalizeGraphState(state);
+  for (const effect of effects || []) s = applyGraphEffect(s, effect);
+  return s;
+}
+
+/** The canonical identity of a state: its sorted entity and edge sets, joined.
+ *  Keys the RESULTING graph, never the path — so independent-step reorderings
+ *  that land on the same graph share one key. */
+export function canonicalStateKey(state) {
+  const s = normalizeGraphState(state);
+  const eLines = s.entities.map((e) => ["E", e.id, e.class, e.title].join(SEP));
+  const rLines = s.edges.map((r) => ["R", r.subject, r.predicate, r.object].join(SEP));
+  return [...eLines, ...rLines].join("\n");
+}
+
+/** A canonical string for one effect, used to compare declared vs observed
+ *  deltas irrespective of list order (PLAN_CODE.md §3.5 tier 1). */
+export function effectKey(effect) {
+  const op = validateEffect(effect);
+  if (op === "add-entity") return [op, str(effect.id), str(effect.class), str(effect.title)].join(SEP);
+  if (op === "del-entity") return [op, str(effect.id)].join(SEP);
+  if (op === "retitle-entity") return [op, str(effect.id), str(effect.title)].join(SEP);
+  return [op, str(effect.subject), str(effect.predicate), str(effect.object)].join(SEP);
+}
+
+/** True when two effect lists describe the same delta regardless of order. */
+export function effectsEqual(a, b) {
+  const keys = (list) => (list || []).map(effectKey).sort();
+  const ka = keys(a);
+  const kb = keys(b);
+  return ka.length === kb.length && ka.every((k, i) => k === kb[i]);
+}
+
+/** The observed delta between two states, as a sorted effect list: what a
+ *  re-index would report an operator actually did. A del-entity's incident-edge
+ *  removals surface as their own del-edge tokens, so a declared delta that lists
+ *  every edge it removes matches the observed one exactly. */
+export function diffGraphStates(before, after) {
+  const a = normalizeGraphState(before);
+  const b = normalizeGraphState(after);
+  const aEnt = new Map(a.entities.map((e) => [e.id, e]));
+  const bEnt = new Map(b.entities.map((e) => [e.id, e]));
+  const effects = [];
+  for (const e of a.entities) if (!bEnt.has(e.id)) effects.push({ op: "del-entity", id: e.id });
+  for (const e of b.entities) {
+    if (!aEnt.has(e.id)) { effects.push({ op: "add-entity", id: e.id, class: e.class, title: e.title }); continue; }
+    if (aEnt.get(e.id).title !== e.title) effects.push({ op: "retitle-entity", id: e.id, title: e.title });
+  }
+  const edgeKey = (r) => [r.subject, r.predicate, r.object].join(SEP);
+  const aEdge = new Set(a.edges.map(edgeKey));
+  const bEdge = new Set(b.edges.map(edgeKey));
+  for (const r of a.edges) if (!bEdge.has(edgeKey(r))) effects.push({ op: "del-edge", ...r });
+  for (const r of b.edges) if (!aEdge.has(edgeKey(r))) effects.push({ op: "add-edge", ...r });
+  return effects.sort((x, y) => effectKey(x).localeCompare(effectKey(y)));
+}
+
+/** Build a code-graph state from a loaded graph payload (the .tmct/graph.json
+ *  shape). Reads the code individuals (skipping the schema:* meta-entities) and
+ *  every objectProperties edge over a known predicate. Pure — a test can build a
+ *  state from the committed fixture graph without touching disk logic here. */
+export function graphStateFromEntities(payload) {
+  const individuals = Array.isArray(payload?.individuals) ? payload.individuals : [];
+  const entities = [];
+  for (const ind of individuals) {
+    if (!ind?.id || typeof ind.id !== "string") continue;
+    if (ind.id.startsWith("schema:")) continue; // ontology meta-entities, not code
+    if (!ENTITY_CLASS_SET.has(str(ind.class))) continue;
+    entities.push({ id: ind.id, class: str(ind.class), title: str(ind.label) });
+  }
+  const known = new Set(entities.map((e) => e.id));
+  const groups = Array.isArray(payload?.objectProperties) ? payload.objectProperties : [];
+  const edges = [];
+  for (const group of groups) {
+    const predicate = str(group?.predicate);
+    if (!EDGE_PREDICATE_SET.has(predicate)) continue;
+    for (const ex of Array.isArray(group.examples) ? group.examples : []) {
+      if (!ex?.subject || !ex?.object) continue;
+      if (!known.has(ex.subject) || !known.has(ex.object)) continue; // never a dangling edge
+      edges.push({ subject: str(ex.subject), predicate, object: str(ex.object) });
+    }
+  }
+  return normalizeGraphState({ entities, edges });
+}

package/src/domain/codeplan/operators.mjs

@@ -0,0 +1,232 @@
+// operators.mjs — the code-transformation operator catalogue: each entry one
+// taught-action family, slot for slot (PLAN_CODE.md §3.2). A signature (the
+// graph shape it applies to), preconditions (named graph predicates from
+// graph-predicates.mjs), a declared effect (a graph delta from graph-delta.mjs),
+// and the standing constraint that every currently-covered test stays covered.
+//
+// The catalogue is DATA — authored and reviewed like any rule base, not engine
+// code. A grounded operator supplies `ground(state, context)`, which enumerates
+// its legal moves over a state given a goal-derived parameter pool; the entries
+// still pending a grounder carry their signature/precondition metadata so the
+// catalogue reads complete. No I/O.
+//
+// An entity id here is a STABLE node identity, independent of the module that
+// currently defines it — a move swaps the `defines` edge and leaves the id
+// alone, the way a graph rewrite renames a node's neighbourhood, not the node.
+// The language adaptor (§3.4) maps that stable identity onto concrete paths.
+
+import { applyGraphEffects, canonicalStateKey } from "./graph-delta.mjs";
+import {
+  moduleDefining, callersOf, importsInducedByMove, preconditionsHold,
+} from "./graph-predicates.mjs";
+
+const asSet = (classes) => new Set(Array.isArray(classes) ? classes : [classes]);
+const titleOf = (state, id) => state.entities.find((e) => e.id === id)?.title;
+const classOf = (state, id) => state.entities.find((e) => e.id === id)?.class;
+const hasEntity = (state, id) => state.entities.some((e) => e.id === id);
+
+const signatureMatches = (state, entityId, signature) => {
+  const cls = classOf(state, entityId);
+  return cls != null && asSet(signature.subjectClass).has(cls);
+};
+
+// ---- grounders ---------------------------------------------------------------
+
+/** rename: retitle an entity in place. One move per (entity matching the
+ *  signature) × (candidate title in the pool) that survives the no-collision
+ *  precondition. */
+function groundRename(operator, state, context) {
+  const out = [];
+  const titles = context?.titles || [];
+  for (const ent of state.entities) {
+    if (!signatureMatches(state, ent.id, operator.signature)) continue;
+    for (const newTitle of titles) {
+      if (newTitle === ent.title) continue;
+      const binding = { entityId: ent.id, newTitle };
+      if (!preconditionsHold(operator.preconditions, state, binding)) continue;
+      out.push({
+        name: operator.name,
+        binding,
+        effects: [{ op: "retitle-entity", id: ent.id, title: newTitle }],
+        label: `rename ${ent.title} to ${newTitle}`,
+      });
+    }
+  }
+  return out;
+}
+
+/** create-module: add a Module the plan will move a symbol into. One move per
+ *  target-module descriptor in the pool not already present. */
+function groundCreateModule(operator, state, context) {
+  const out = [];
+  for (const target of context?.moduleTargets || []) {
+    if (!target?.id || hasEntity(state, target.id)) continue;
+    out.push({
+      name: operator.name,
+      binding: { moduleId: target.id },
+      effects: [{ op: "add-entity", id: target.id, class: "Module", title: target.title || target.id }],
+      label: `create module ${target.title || target.id}`,
+    });
+  }
+  return out;
+}
+
+/** move: hand an entity to a different module — swap its `defines` edge and add
+ *  the import edges every call site now needs — without creating an import
+ *  cycle. */
+function groundMove(operator, state, context) {
+  const out = [];
+  const targets = (context?.moduleTargets || []).map((t) => t.id);
+  for (const ent of state.entities) {
+    if (!signatureMatches(state, ent.id, operator.signature)) continue;
+    const from = moduleDefining(state, ent.id);
+    if (!from) continue;
+    for (const toModuleId of targets) {
+      if (toModuleId === from || !hasEntity(state, toModuleId)) continue;
+      const binding = { entityId: ent.id, toModuleId };
+      if (!preconditionsHold(operator.preconditions, state, binding)) continue;
+      const effects = [
+        { op: "del-edge", subject: from, predicate: "defines", object: ent.id },
+        { op: "add-edge", subject: toModuleId, predicate: "defines", object: ent.id },
+        ...importsInducedByMove(state, binding).map((r) => ({ op: "add-edge", ...r })),
+      ];
+      out.push({
+        name: operator.name,
+        binding,
+        effects,
+        label: `move ${ent.title} to ${titleOf(state, toModuleId)}`,
+      });
+    }
+  }
+  return out;
+}
+
+/** delete-dead: remove an entity nothing depends on — drop its `defines` edge,
+ *  then the entity. Only entities the goal names as delete targets are offered. */
+function groundDeleteDead(operator, state, context) {
+  const out = [];
+  for (const entityId of context?.deleteTargets || []) {
+    if (!hasEntity(state, entityId)) continue;
+    if (!signatureMatches(state, entityId, operator.signature)) continue;
+    const binding = { entityId };
+    if (!preconditionsHold(operator.preconditions, state, binding)) continue;
+    const from = moduleDefining(state, entityId);
+    const effects = [
+      ...(from ? [{ op: "del-edge", subject: from, predicate: "defines", object: entityId }] : []),
+      { op: "del-entity", id: entityId },
+    ];
+    out.push({ name: operator.name, binding, effects, label: `delete ${titleOf(state, entityId)}` });
+  }
+  return out;
+}
+
+// ---- the catalogue -----------------------------------------------------------
+
+const SYMBOL = ["Function", "Method"];
+
+/** The starting operator catalogue: the refactoring literature's settled core
+ *  (Opdyke 1992; Fowler 1999). Grounded entries carry a `ground` function; the
+ *  rest declare their signature and preconditions and await one. */
+export const CODE_OPERATORS = Object.freeze([
+  {
+    name: "rename",
+    summary: "retitle an entity in place; every call site keeps resolving by id",
+    signature: { subjectClass: SYMBOL },
+    preconditions: ["no-name-collision"],
+    ground: groundRename,
+  },
+  {
+    name: "create-module",
+    summary: "add a Module a later move can hand a symbol into",
+    signature: { subjectClass: "Module" },
+    preconditions: [],
+    ground: groundCreateModule,
+  },
+  {
+    name: "move",
+    summary: "hand an entity to another module, adding the imports its callers need",
+    signature: { subjectClass: SYMBOL },
+    preconditions: ["move-introduces-no-import-cycle"],
+    ground: groundMove,
+  },
+  {
+    name: "delete-dead",
+    summary: "remove an entity with no inbound dependency edges",
+    signature: { subjectClass: SYMBOL },
+    preconditions: ["no-inbound-dependencies"],
+    ground: groundDeleteDead,
+  },
+  {
+    name: "inline",
+    summary: "replace calls with the single definition's body; the definition then deletes",
+    signature: { subjectClass: SYMBOL },
+    preconditions: ["single-definition", "no-self-recursion"],
+  },
+  {
+    name: "extract-function",
+    summary: "lift a fragment into its own function, its call taking the fragment's place",
+    signature: { subjectClass: SYMBOL },
+    preconditions: ["no-name-collision"],
+  },
+  {
+    name: "add-parameter",
+    summary: "add a parameter with a default; update every call site",
+    signature: { subjectClass: SYMBOL },
+    preconditions: [],
+  },
+  {
+    name: "wrap",
+    summary: "put a guard or decorator around a call boundary",
+    signature: { subjectClass: SYMBOL },
+    preconditions: [],
+  },
+  {
+    name: "split-module",
+    summary: "divide a module's definitions across two, importers re-pointed",
+    signature: { subjectClass: "Module" },
+    preconditions: [],
+  },
+  {
+    name: "apply-semantic-patch",
+    summary: "a taught pattern→replacement pair promoted to a first-class operator (comby/ast-grep-shaped)",
+    signature: { subjectClass: SYMBOL },
+    preconditions: [],
+  },
+]);
+
+/** The grounded subset — operators a planner can currently enumerate moves for. */
+export const groundedOperators = (catalogue = CODE_OPERATORS) => catalogue.filter((op) => typeof op.ground === "function");
+
+// A move may not drop a test-coverage edge, nor delete a module something still
+// covers — the standing "every currently-covered test stays covered" constraint,
+// applied to every grounded move regardless of which operator produced it.
+const preservesCoverage = (state, move) => {
+  const nextState = applyGraphEffects(state, move.effects);
+  const covered = new Set(state.edges.filter((r) => r.predicate === "tests").map((r) => r.object));
+  const stillCovered = new Set(nextState.edges.filter((r) => r.predicate === "tests").map((r) => r.object));
+  for (const id of covered) if (!stillCovered.has(id)) return false;
+  return true;
+};
+
+/**
+ * Every legal grounded move from `state`, given the goal-derived `context`
+ * parameter pool, as `{ action, nextState }` pairs — the `applyActions`
+ * findActionPath consumes. Deterministic: operators are walked in catalogue
+ * order and each grounder is order-stable. The coverage constraint prunes any
+ * move that would drop test coverage.
+ */
+export function codeGraphMoves(state, context, { catalogue = CODE_OPERATORS } = {}) {
+  const out = [];
+  const seen = new Set([canonicalStateKey(state)]);
+  for (const op of groundedOperators(catalogue)) {
+    for (const move of op.ground(op, state, context)) {
+      if (!preservesCoverage(state, move)) continue;
+      const nextState = applyGraphEffects(state, move.effects);
+      const key = canonicalStateKey(nextState);
+      if (seen.has(key)) continue; // a no-op or a duplicate successor
+      seen.add(key);
+      out.push({ action: move, nextState });
+    }
+  }
+  return out;
+}