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

package/bin/tmct.mjs

@@ -920,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "3.0.0",
+  "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; indexes a repo on request (tmct index) or reads any producer's graph.",

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/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;
+}

package/src/domain/codeplan/planner.mjs

@@ -0,0 +1,87 @@
+// planner.mjs — bounded BFS to a graph-predicate goal (PLAN_CODE.md §3.3). The
+// goal is a set of predicates over graph shape, the same species as
+// domain.mjs's compileGoal specs: "entity X is titled parseRow; X lives in
+// module M; every former call site imports M." findActionPath searches operator
+// applications (operators.mjs's codeGraphMoves) over projected graph snapshots,
+// keyed by the path-independent canonicalStateKey, shortest plan first, honest
+// miss on exhaustion. No new search engine, no I/O.
+
+import { findActionPath } from "../planning.mjs";
+import { canonicalStateKey } from "./graph-delta.mjs";
+import { moduleDefining } from "./graph-predicates.mjs";
+import { CODE_OPERATORS, codeGraphMoves } from "./operators.mjs";
+
+const str = (value) => String(value ?? "");
+
+const titleOf = (state, id) => state.entities.find((e) => e.id === id)?.title;
+const hasEntity = (state, id) => state.entities.some((e) => e.id === id);
+const hasEdge = (state, { subject, predicate, object }) =>
+  state.edges.some((r) => r.subject === subject && r.predicate === predicate && r.object === object);
+
+/** The closed goal-predicate vocabulary: one checker per `kind`, each a pure
+ *  boolean over a state. A goal spec outside this set is a programming error. */
+export const GOAL_PREDICATES = Object.freeze({
+  "entity-titled": (state, g) => titleOf(state, g.id) === str(g.title),
+  "entity-in-module": (state, g) => moduleDefining(state, g.id) === str(g.moduleId),
+  "entity-absent": (state, g) => !hasEntity(state, g.id),
+  "edge-present": (state, g) => hasEdge(state, { subject: str(g.subject), predicate: str(g.predicate), object: str(g.object) }),
+  "edge-absent": (state, g) => !hasEdge(state, { subject: str(g.subject), predicate: str(g.predicate), object: str(g.object) }),
+});
+
+/** Compile goal specs into a single state predicate — the conjunction of every
+ *  spec's checker. Throws on an unknown `kind`. */
+export function compileCodeGoal(goalSpecs) {
+  const specs = goalSpecs || [];
+  for (const g of specs) {
+    if (!GOAL_PREDICATES[str(g.kind)]) throw new Error(`unknown goal predicate kind ${JSON.stringify(str(g.kind))}`);
+  }
+  return function isGoal(state) {
+    return specs.every((g) => GOAL_PREDICATES[str(g.kind)](state, g));
+  };
+}
+
+/** Derive the grounders' parameter pool from the goal (operators.mjs's
+ *  `context`): rename titles from entity-titled specs, move/create-module target
+ *  modules from entity-in-module specs, delete targets from entity-absent specs.
+ *  A goal-directed pool keeps operator enumeration bounded — the planner only
+ *  proposes renames/moves the goal actually calls for. A target module carries a
+ *  title (spec `moduleTitle`, else its id with the `mod:` prefix stripped) so
+ *  create-module can mint it. */
+export function deriveContext(goalSpecs) {
+  const titles = new Set();
+  const moduleTargets = new Map();
+  const deleteTargets = new Set();
+  for (const g of goalSpecs || []) {
+    if (g.kind === "entity-titled") titles.add(str(g.title));
+    else if (g.kind === "entity-in-module") {
+      const id = str(g.moduleId);
+      if (!moduleTargets.has(id)) moduleTargets.set(id, { id, title: str(g.moduleTitle) || id.replace(/^mod:/, "") });
+    } else if (g.kind === "entity-absent") deleteTargets.add(str(g.id));
+  }
+  return { titles: [...titles], moduleTargets: [...moduleTargets.values()], deleteTargets: [...deleteTargets] };
+}
+
+/**
+ * Plan a code change: search catalogue-operator applications from `startState`
+ * to a state satisfying `goalSpecs`. Returns `{ actions, states, plan }` — the
+ * ordered moves, the snapshots between them, and a per-step receipt (operator,
+ * binding, declared effect) — or `null` on an honest miss (no plan within
+ * `maxDepth`). Deterministic: the same fixture, catalogue and goal always yield
+ * the same plan.
+ */
+export function planCodeChange(startState, goalSpecs, { catalogue = CODE_OPERATORS, maxDepth = 12 } = {}) {
+  const isGoal = compileCodeGoal(goalSpecs);
+  const context = deriveContext(goalSpecs);
+  const applyActions = (state) => codeGraphMoves(state, context, { catalogue });
+  const found = findActionPath(startState, isGoal, applyActions, { maxDepth, stateKey: canonicalStateKey });
+  if (!found) return null;
+  const plan = found.actions.map((action, i) => ({
+    operator: action.name,
+    binding: action.binding,
+    effects: action.effects,
+    label: action.label,
+    before: found.states[i],
+    after: found.states[i + 1],
+  }));
+  return { actions: found.actions, states: found.states, plan };
+}

package/src/services/chat-session.mjs

@@ -209,6 +209,13 @@ export async function createSession({
   // the flag/env tiers above stay authoritative when set.
   if (toml?.corpus?.tier === "tier3") liveReferenceOn = true;
 
+  // tmct.toml's [graph] read_only turns any session against this repo into a
+  // read-only one, exactly as --ephemeral does: the graph is read for
+  // structure but nothing (upsert, logs, memory) is written back into the
+  // repo's .tmct/. Committed example fixtures carry it so a plain
+  // `tmct chat --repo examples/<x>` never mutates the hand-stamped graph.
+  if (toml?.graph?.readOnly) ephemeral = true;
+
   // Ephemeral: keep config.graphFile pointing at the READ graph, but divert the
   // write base (repo → logs/memory/sessions) to a throwaway temp dir. The committed
   // target is never touched; the demo's memory simply doesn't persist across runs.

package/src/services/sessions.mjs

@@ -48,7 +48,9 @@ function labelFromId(id) {
  *  reader never sees a torn graph.json and a crash never destroys the old one. */
 async function atomicWriteJson(file, obj) {
   const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
-  await writeFile(tmp, JSON.stringify(obj));
+  // 2-space indent: a legitimate session upsert into a hand-formatted graph
+  // reflows to the same pretty shape a producer wrote, not one compact line.
+  await writeFile(tmp, JSON.stringify(obj, null, 2));
   await rename(tmp, file);
 }