@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.1

package/src/{cli-args.mjs → services/cli-args.mjs}

@@ -22,8 +22,8 @@ import { spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
-import { loadTomlConfig, normalizeConfig, mergeEffective, CONFIG_FILE } from "./toml-config.mjs";
-import { DEFAULT_GRAPH_REL } from "./config.mjs";
+import { loadTomlConfig, normalizeConfig, mergeEffective, CONFIG_FILE } from "../adapters/toml-config.mjs";
+import { DEFAULT_GRAPH_REL } from "../adapters/config.mjs";
 
 /** The git top-level for `cwd`, or null if not in a repo (or git is
  *  unavailable). A deliberate re-declaration of chat.mjs's gitToplevel (not an

package/src/services/completions.mjs

@@ -0,0 +1,55 @@
+// completions.mjs — the composition root for src/domain/completions/'s pipeline. The stages
+// there are pure: they read the memory store, the block store, the graph service and the
+// prose finisher through an explicit `store`/`finisher` handle, and import none of them. This
+// file builds the real handles from the adapters and re-exports both entry points with the
+// signatures package.json's `./generateCompletion` and `./createCompletionsGraphAdapter`
+// subpaths publish, so an external caller never passes a store of its own.
+
+import {
+  buildNeighbours, degreeOf, OVERLAP_MIN, rankBlocks, retrieveBlocks, tokenizeBlock,
+} from "../adapters/memory/blocks.mjs";
+import { loadMemory, normFactTerm, readFactRows, resolveRelationChase } from "../adapters/memory/core.mjs";
+import { createGraphService } from "../adapters/providers/graph-service.mjs";
+import { finish, grammarRules } from "./finish.mjs";
+import { generateCompletion as generateCompletionOver } from "../domain/completions/complete.mjs";
+import { createCompletionsGraphAdapter as createCompletionsGraphAdapterOver } from "../domain/completions/graph-adapter.mjs";
+
+/** Every store handle the six stages read through, in one bag: the memory store's fact
+ *  readers, the block store's retrieval/clustering/ranking helpers, and the graph service
+ *  factory graph-adapter.mjs wraps. */
+export const COMPLETIONS_STORE = {
+  loadMemory,
+  readFactRows,
+  normFactTerm,
+  resolveRelationChase,
+  retrieveBlocks,
+  buildNeighbours,
+  rankBlocks,
+  degreeOf,
+  tokenizeBlock,
+  OVERLAP_MIN,
+  createGraphService,
+};
+
+/** finish.mjs reads its grammar rules from TOML on disk, so it stays in services and reaches
+ *  the pipeline's Stage 6 through this handle. */
+export const COMPLETIONS_FINISHER = { finish, grammarRules };
+
+/**
+ * The full mechanical-text-generation pipeline over the real store. Same signature and
+ * behaviour as src/domain/completions/complete.mjs's generateCompletion(); see its docblock
+ * for the options. A caller may still override any handle through `opts.store`/`opts.finisher`.
+ */
+export function generateCompletion(dir, prompt, opts = {}) {
+  return generateCompletionOver(dir, prompt, {
+    store: COMPLETIONS_STORE, finisher: COMPLETIONS_FINISHER, ...opts,
+  });
+}
+
+/**
+ * A graphService-shaped adapter for broadSearch() over the real store. Same signature and
+ * behaviour as src/domain/completions/graph-adapter.mjs's createCompletionsGraphAdapter().
+ */
+export function createCompletionsGraphAdapter(graph, memory = null) {
+  return createCompletionsGraphAdapterOver(graph, memory, { store: COMPLETIONS_STORE });
+}

package/src/{extensions.mjs → services/extensions.mjs}

@@ -12,7 +12,7 @@
 // A `tmct.toml` `[extensions]` table-of-tables may override a recognized builtin, or
 // declare a new host entry with its own `kind` (corpus | lexicon | templates | pack |
 // ontology). A separate flat `[bias]` table (bundle-name → number) feeds
-// src/memory/bias.mjs's ranking.
+// src/domain/memory/bias.mjs's ranking.
 //
 // Entries are returned in a fixed order: `seon` first, then `conceptnet`, then the rest
 // sorted by name (so seon's curated facts win idempotency races over ConceptNet noise).
@@ -20,7 +20,7 @@
 import { isAbsolute, join, resolve, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-import { loadTomlConfig } from "./toml-config.mjs";
+import { loadTomlConfig } from "../adapters/toml-config.mjs";
 import {
   SEON_CONCEPTS_FILE,
   SLICE_FILE as CONCEPTNET_SLICE_FILE,
@@ -30,10 +30,10 @@ import {
   loadSlice,
   loadMap,
   toFacts,
-} from "./corpus/conceptnet.mjs";
+} from "../adapters/corpus/conceptnet.mjs";
 
 // corpus/namenet/generate.mjs's output — a single small top-up bundle.
-const NAMENET_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "corpus", "namenet");
+const NAMENET_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "corpus", "namenet");
 
 export const EXTENSION_KINDS = Object.freeze(["corpus", "lexicon", "templates", "pack", "ontology"]);
 
@@ -258,7 +258,7 @@ export async function resolveExtensions(repoRoot, { configFile } = {}) {
  *  recorded as `perBundle[name].error` while every other bundle still seeds normally.
  *  Returns `{ appended, skipped, total, perBundle: { name: {appended,skipped,total,error?} } }`. */
 export async function seedActiveCorpusEntries(repo, entries) {
-  const { seedMemory } = await import("./corpus/conceptnet.mjs");
+  const { seedMemory } = await import("../adapters/corpus/conceptnet.mjs");
   const perBundle = {};
   let appended = 0;
   let skipped = 0;
@@ -347,7 +347,7 @@ export async function validateExtensionPack(dir, candidate) {
   if (candidate.lexiconPath) {
     const path = abs(candidate.lexiconPath);
     try {
-      const { loadLexicon } = await import("./grammar/lexicon.mjs");
+      const { loadLexicon } = await import("../domain/grammar/lexicon.mjs");
       const raw = JSON.parse(await readFile(path, "utf8"));
       const lex = loadLexicon(raw);
       results.push({
@@ -362,7 +362,7 @@ export async function validateExtensionPack(dir, candidate) {
   if (candidate.templatesPath) {
     const path = abs(candidate.templatesPath);
     try {
-      const { loadTemplates } = await import("./corpus/templates.mjs");
+      const { loadTemplates } = await import("../adapters/corpus/templates.mjs");
       const templates = await loadTemplates(path);
       const unnamespaced = [...templates.keys()].filter((id) => !id.includes(":"));
       if (unnamespaced.length) {

package/src/{finish.mjs → services/finish.mjs}

@@ -12,13 +12,13 @@ import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
 import { parse as parseToml } from "smol-toml";
 
-import { flatten } from "./corpus/templates.mjs";
+import { flatten } from "../adapters/corpus/templates.mjs";
 
 export { flatten };
 
 const GRAMMAR_DIR = dirname(fileURLToPath(import.meta.url));
 /** The data-driven grammar-rule table. */
-export const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "data", "templates", "grammar-rules.toml");
+export const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "..", "data", "templates", "grammar-rules.toml");
 
 /** The segment type vocabulary. `prose` is the only unprotected type. */
 export const SEGMENT_TYPES = Object.freeze([

package/src/{import-file.mjs → services/import-file.mjs}

@@ -13,8 +13,8 @@ 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 { loadMemory, readFactRows, appendFact, openMemoryBackend } from "../adapters/memory/core.mjs";
+import { loadConfig } from "../adapters/config.mjs";
 import { splitSentences } from "./sentences.mjs";
 
 /**
@@ -36,7 +36,7 @@ export async function importDefinitionFile(repoRoot, filePath, { env = process.e
   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 { loadTomlConfig } = await import("../adapters/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);

package/src/{index.mjs → services/index.mjs}

@@ -1,7 +1,7 @@
 // @polycode-projects/the-mechanical-code-talker (tmct) — library entry point.
 //
 // This entry re-exports the adapter primitives a library consumer needs. The
-// movable conversational grammar lives in src/interpret/ (normalization
+// movable conversational grammar lives in src/domain/interpret/ (normalization
 // pre-pass, the registered parsing strategies, the merge rule), while
 // ask.mjs keeps the core primitives (resolveObject, traverse, render) and
 // the ask() orchestration.
@@ -10,31 +10,41 @@
 export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
 
 // Grammar / NL-over-graph primitives.
-export { ask, resolveObject } from "./ask.mjs";
+export { ask, resolveObject } from "../domain/ask.mjs";
 
 // The interpretation pipeline: normalize once, run every
 // registered strategy (grammar, keyword-spot, …) over the text, merge same-class
 // results, surround distinct-class results — no graph access; pair it with ask()
 // or the primitives to answer. `interpret(text, ctx)` returns the full record
 // ({raw, normalized, normalizationChanged, results, parsed, class, alternates}).
-export { interpret } from "./interpret/pipeline.mjs";
+export { interpret } from "../domain/interpret/pipeline.mjs";
+
+// Composition: the library entry wires the domain parser's default lemma/POS
+// adapter and the construction-grammar banks (lazy loader), same as the chat
+// and tool surfaces do for themselves.
+import { setDefaultNlpAdapter } from "../domain/interpret/nlp-registry.mjs";
+import { setConstructionBanks } from "../domain/interpret/strategies/constructions.mjs";
+import { nlpAdapter } from "../adapters/ask-nlp.mjs";
+import { readConstructionFiles } from "../adapters/corpus/construction-banks.mjs";
+setDefaultNlpAdapter(nlpAdapter);
+setConstructionBanks(readConstructionFiles);
 
 // Graph traversal primitives.
-export { relationKind, impactClosure } from "./codegraph.mjs";
+export { relationKind, impactClosure } from "../domain/codegraph.mjs";
 
 // Tool dispatch (slash-commands and CLI tool calls route through here).
-export { dispatchTool } from "./server.mjs";
+export { dispatchTool } from "../tools/server.mjs";
 
 // Conversational memory — tmct's OWN OWL-labelled graph under
 // .tmct/memory/, distinct from any provider-supplied code graph.
-export { loadMemory, appendUtterance, appendFact } from "./memory/core.mjs";
-export { retrieveBlocks, saveBlock, rankBlocks } from "./memory/blocks.mjs";
-export { foldSessionLogs } from "./memory/fold.mjs";
+export { loadMemory, appendUtterance, appendFact } from "../adapters/memory/core.mjs";
+export { retrieveBlocks, saveBlock, rankBlocks } from "../adapters/memory/blocks.mjs";
+export { foldSessionLogs } from "./fold.mjs";
 
 // The single graph-load choke point — the adapter's data-provider seam
 // (docs/adapter-contract.md): registerProvider() plugs a producer in;
 // fetchEntities() is the one read path.
-export { fetchEntities, registerProvider } from "./source.mjs";
+export { fetchEntities, registerProvider } from "../adapters/source.mjs";
 
 // `tmct init` onboarding (also reachable as the `./init` subpath export).
 // init.mjs and toml-config.mjs each export a same-named `CONFIG_FILE`
@@ -43,9 +53,8 @@ export { fetchEntities, registerProvider } from "./source.mjs";
 export { initRepo, defaultConfig, renderTomlConfig, PERSONA_PRESETS, CONFIG_FILE as INIT_CONFIG_FILE } from "./init.mjs";
 
 // tmct.toml loading (also reachable as the `./toml-config` subpath export).
-export { CONFIG_FILE as TOML_CONFIG_FILE } from "./toml-config.mjs";
+export { CONFIG_FILE as TOML_CONFIG_FILE } from "../adapters/toml-config.mjs";
 
 // The "detailed answer" completions pipeline (also reachable as the
 // `./generateCompletion` and `./createCompletionsGraphAdapter` subpath exports).
-export { generateCompletion } from "./completions/complete.mjs";
-export { createCompletionsGraphAdapter } from "./completions/graph-adapter.mjs";
+export { generateCompletion, createCompletionsGraphAdapter } from "./completions.mjs";

package/src/{init.mjs → services/init.mjs}

@@ -57,7 +57,7 @@ export const PERSONA_PRESETS = Object.freeze({
 /** Read this package's version (best-effort, for provenance). */
 async function tmctVersion() {
   try {
-    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
     const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
     return pkg.version || null;
   } catch {
@@ -92,7 +92,7 @@ export function renderTomlConfig(config = defaultConfig()) {
 graph_file = ${JSON.stringify(c.graphFile)}
 ${Array.isArray(c.graphFiles) && c.graphFiles.length ? `
 # graph_files — additional graph artifacts (multi-graph). Merged with
-# graph_file at read time (src/graph-merge.mjs); an id that collides
+# graph_file at read time (src/adapters/graph-merge.mjs); an id that collides
 # across graphs is auto-prefixed with its graph's name, everything else
 # passes through unchanged. Written by \`tmct init --graph\`/\`tmct import
 # --graph\`.
@@ -136,12 +136,12 @@ backend = ${JSON.stringify(config.memory.backend)}
   if (config.bias !== undefined) extras.bias = config.bias;
   if (!Object.keys(extras).length) return out;
   return `${out}
-# Extension packs + bias (src/extensions.mjs) — written by \`tmct init --with-persona\`
+# Extension packs + bias (src/services/extensions.mjs) — written by \`tmct init --with-persona\`
 # or a manual edit. Recognized names (human, seon, conceptnet, tier2-aws,
 # tier2-python, tier2-java, tier2-general) override the shipped defaults; any
 # other name declares a new host-supplied bundle (needs its own "kind").
 # [bias] is a flat bundle-name -> weight table consumed by
-# src/memory/bias.mjs's ranking.
+# src/domain/memory/bias.mjs's ranking.
 ${stringifyToml(extras)}`;
 }
 
@@ -168,7 +168,7 @@ function seedRequested({ optSeed, configEnabled, env }) {
  *   merged into a FRESH config only; name resolution is the caller's job (bin/tmct.mjs).
  * @param {string}  [opts.memoryBackend]  "default" | "memory" | "sqlite" — merged into a
  *   FRESH config's `[memory] backend`, and selects which backend the corpus seed writes
- *   into (via src/memory/core.mjs's openMemoryBackend).
+ *   into (via src/adapters/memory/core.mjs's openMemoryBackend).
  * @returns {Promise<{
  *   created: string[], config: object, seeded: boolean,
  *   alreadyInitialized: boolean, seedResult: (object|null), message: string
@@ -206,7 +206,7 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
   {
     const importsDir = join(paths.tmct, "imports");
     const gamesDir = join(importsDir, "games");
-    const shippedGames = join(dirname(fileURLToPath(import.meta.url)), "..", "data", "games");
+    const shippedGames = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "data", "games");
     if (!(await exists(gamesDir))) {
       await mkdir(gamesDir, { recursive: true });
       created.push(gamesDir);
@@ -277,7 +277,7 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
     if (backendChoice === "memory") {
       seedNote = "seed skipped (memory backend is in-process only — nothing would persist past this command)";
     } else {
-      const { openMemoryBackend } = await import("./memory/core.mjs");
+      const { openMemoryBackend } = await import("../adapters/memory/core.mjs");
       const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(root, backendChoice);
       try {
         const { resolveExtensions, seedActiveCorpusEntries } = await import("./extensions.mjs");
@@ -348,7 +348,7 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
  *  (toml-config.mjs) is where a bad file surfaces its error. */
 async function readWrittenConfig(tomlPath, base) {
   try {
-    const { loadTomlConfig } = await import("./toml-config.mjs");
+    const { loadTomlConfig } = await import("../adapters/toml-config.mjs");
     const raw = await loadTomlConfig(dirname(tomlPath));
     if (!raw) return base;
     const cfg = { ...base };
@@ -359,7 +359,7 @@ async function readWrittenConfig(tomlPath, base) {
       if (raw.seed.enabled !== undefined) cfg.seed.enabled = Boolean(raw.seed.enabled);
       if (raw.seed.limit !== undefined) cfg.seed.limit = Number(raw.seed.limit);
     }
-    // Sparse pass-through — src/extensions.mjs validates; this layer just carries the
+    // Sparse pass-through — src/services/extensions.mjs validates; this layer just carries the
     // raw tables through unmodified.
     if (raw.extensions !== undefined) cfg.extensions = raw.extensions;
     if (raw.bias !== undefined) cfg.bias = raw.bias;

package/src/{ledger-viz.mjs → services/ledger-viz.mjs}

@@ -10,7 +10,7 @@
 // readMemoryAskBundle() is the one extra bit of I/O renderLedgerHtml itself
 // doesn't do: it reads the checked-in chat-dock engine bundle.
 
-import { loadMemory, readFactRows, findContradictions, normFactTerm } from "./memory/core.mjs";
+import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
 import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -19,14 +19,14 @@ import { dirname, join } from "node:path";
 export const LEDGER_ROW_LIMIT_DEFAULT = 20000;
 
 /** Read the checked-in browser memory-ask-engine bundle
- *  (`src/memory-ask-browser.bundle.js`) — the real memory-graph answer engine
+ *  (`src/surfaces/web/memory-ask-browser.bundle.js`) — the real memory-graph answer engine
  *  (chat.mjs's factAnswer/factReadBack) the chat dock runs on. Returns `""`,
  *  never throws, if the bundle hasn't been built — the page then renders with
  *  an honest "chat unavailable" note instead of a dock. */
 export async function readMemoryAskBundle() {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
-    return await readFile(join(here, "memory-ask-browser.bundle.js"), "utf8");
+    return await readFile(join(here, "..", "surfaces", "web", "memory-ask-browser.bundle.js"), "utf8");
   } catch {
     return "";
   }

package/src/{plan-viz.mjs → services/plan-viz.mjs}

@@ -31,7 +31,9 @@ function darken(hex, fraction) {
 }
 
 /** Topological rank over [smaller, larger] pairs, label tiebreak; members
- *  absent from every pair are appended in label order. */
+ *  absent from every pair are appended in label order. `sized` names the members
+ *  a pair actually ordered — the appended rest carry a rank so they can be drawn,
+ *  which says nothing about their size. */
 function rankBySize(sizeOrder, members) {
   const pairs = Array.isArray(sizeOrder) ? sizeOrder : [];
   const inPairs = new Set();
@@ -62,10 +64,11 @@ function rankBySize(sizeOrder, members) {
     }
     ready.sort();
   }
+  const sized = new Set(Object.keys(ranks));
   for (const m of [...members].sort()) {
     if (!(m in ranks)) ranks[m] = next++;
   }
-  return ranks;
+  return { ranks, sized };
 }
 
 /**
@@ -106,7 +109,7 @@ export function computeBlocksLayout({ plan, rendersAs = {}, sizeOrder = [] }) {
   const anchorX = new Map(anchors.map((a) => [a.id, a.x]));
 
   const blocks = [...blockSet].sort();
-  const ranks = rankBySize(sizeOrder, blocks);
+  const { ranks, sized } = rankBySize(sizeOrder, blocks);
   const maxRank = blocks.reduce((m, b) => Math.max(m, ranks[b] ?? 0), 0);
   const blockClassOf = (label) =>
     classes.find((cls) => rendersAs[cls] === "block" && (classMembers[cls] || []).includes(label));
@@ -118,21 +121,27 @@ export function computeBlocksLayout({ plan, rendersAs = {}, sizeOrder = [] }) {
   };
 
   const snapshots = (plan?.states || []).map((rows) => {
-    const supporterOf = new Map(); // object -> subject resting on it
+    const restingOn = new Map(); // object -> every subject resting directly on it
     for (const r of [...rows].sort((a, b) => (a.subject < b.subject ? -1 : 1))) {
-      if (blockSet.has(r.subject) && !supporterOf.has(r.object)) {
-        supporterOf.set(r.object, r.subject);
-      }
+      if (!blockSet.has(r.subject)) continue;
+      if (!restingOn.has(r.object)) restingOn.set(r.object, []);
+      const above = restingOn.get(r.object);
+      if (!above.includes(r.subject)) above.push(r.subject);
     }
     const stacks = {};
     const items = anchors.map((a) => ({ ...a }));
     for (const a of anchors) {
       const stack = [];
-      let top = a.id;
-      while (supporterOf.has(top)) {
-        top = supporterOf.get(top);
-        stack.push(top);
-      }
+      const placed = new Set();
+      const pileOnto = (support) => {
+        for (const label of [...(restingOn.get(support) || [])].sort()) {
+          if (placed.has(label)) continue;
+          placed.add(label);
+          stack.push(label);
+          pileOnto(label);
+        }
+      };
+      pileOnto(a.id);
       stacks[a.id] = stack;
       stack.forEach((label, i) => {
         const w = widthOf(label);
@@ -152,16 +161,24 @@ export function computeBlocksLayout({ plan, rendersAs = {}, sizeOrder = [] }) {
     return { items, stacks };
   });
 
-  return { board: { w: BOARD_W, h: BOARD_H }, ranks, anchors, snapshots };
+  return { board: { w: BOARD_W, h: BOARD_H }, ranks, sized, anchors, snapshots };
 }
 
 /** Phase brackets from the largest block's single move: everything before it
  *  frees the piece, the move itself is the pivot, the rest rebuilds. */
-function phasesFor(actions, ranks) {
-  const ranked = Object.keys(ranks);
-  if (!ranked.length || !actions.length) return [];
-  const pivot = ranked.reduce((a, b) => (ranks[a] >= ranks[b] ? a : b));
-  const k = actions.findIndex((a) => a.subject === pivot);
+function phasesFor(actions, ranks, sized) {
+  // free-it / move-it / rebuild-on-it describes ONE shape: a puzzle whose biggest
+  // piece is declared biggest and travels once, everything before clearing its way
+  // and everything after stacking back on top. Hanoi is that shape. A puzzle that
+  // declares no sizes has no biggest piece to pivot on — rankBySize ranks its
+  // pieces by label so they can be drawn, and reading a pivot out of that ordering
+  // names an arbitrary piece. Say nothing rather than something arbitrary.
+  const ordered = [...(sized || [])];
+  if (!ordered.length || !actions.length) return [];
+  const pivot = ordered.reduce((a, b) => (ranks[a] >= ranks[b] ? a : b));
+  const moves = actions.filter((a) => a.subject === pivot);
+  if (moves.length !== 1) return []; // travels more than once — not this shape
+  const k = actions.indexOf(moves[0]);
   if (k <= 0 || k >= actions.length - 1) return [];
   return [
     { label: `free ${pivot}`, from: 0, to: k },
@@ -198,7 +215,7 @@ export function renderPlanHtml({ plan, rendersAs = {}, sizeOrder = [], title } =
     anchors: layout.anchors,
     board: layout.board,
     facts: factsPerStep,
-    phases: phasesFor(actions, layout.ranks),
+    phases: phasesFor(actions, layout.ranks, layout.sized),
   });
   const pageTitle = title || `tmct plan — ${actions.length} move${actions.length === 1 ? "" : "s"}`;
 
@@ -327,13 +344,35 @@ const PLAN = ${embedded};
       const a = posIn(before, id), b = posIn(after, id);
       return a && b && (a.x !== b.x || a.y !== b.y);
     });
-    if (reduced || movers.length !== 1) { drawState(i + 1); return; }
-    const id = movers[0], el = blockEls[id], to = posIn(after, id);
-    animating = true; el.classList.add("moving");
-    el.style.transition = "top .18s ease-in"; el.style.top = "${LIFT_Y}px"; await wait(190);
-    el.style.transition = "left .26s ease-in-out"; el.style.left = to.x + "px"; await wait(270);
-    el.style.transition = "top .18s ease-out"; el.style.top = to.y + "px"; await wait(200);
-    el.classList.remove("moving"); animating = false;
+    if (reduced || movers.length === 0) { drawState(i + 1); return; }
+    // A step can move several pieces at once (a carrier plus its passengers).
+    // Only pieces that change column actually travel; a piece whose column is
+    // unchanged is settling into the gap a departing piece left, so it drops
+    // in place rather than miming the journey.
+    const travellers = movers.filter((id) => posIn(before, id).x !== posIn(after, id).x);
+    const settlers = movers.filter((id) => posIn(before, id).x === posIn(after, id).x);
+    animating = true;
+    // Each traveller rides its own lane so pieces crossing together stay
+    // legible instead of stacking up on one another mid-air.
+    const riders = travellers.map((id, lane) => ({
+      el: blockEls[id],
+      to: posIn(after, id),
+      liftY: ${LIFT_Y} - lane * ${BLOCK_H + BLOCK_GAP},
+    }));
+    for (const r of riders) r.el.classList.add("moving");
+    for (const r of riders) { r.el.style.transition = "top .18s ease-in"; r.el.style.top = r.liftY + "px"; }
+    await wait(190);
+    for (const id of settlers) {
+      const el = blockEls[id];
+      el.style.transition = "top .2s ease-in-out"; el.style.top = posIn(after, id).y + "px";
+    }
+    for (const r of riders) { r.el.style.transition = "left .26s ease-in-out"; r.el.style.left = r.to.x + "px"; }
+    await wait(270);
+    for (const r of riders) { r.el.style.transition = "top .18s ease-out"; r.el.style.top = r.to.y + "px"; }
+    await wait(200);
+    for (const r of riders) r.el.classList.remove("moving");
+    drawState(i + 1);
+    animating = false;
   }
   const phaseFor = (i) => {
     if (i >= N) return "done";

package/src/{sentences.mjs → services/sentences.mjs}

@@ -1,7 +1,7 @@
 // sentences.mjs — sentence-boundary splitting, shared by the extract-facts
 // script, the chat one-shot CLI, and runTurn's multi-sentence pre-split.
 
-import { winkInstance } from "./wink-model.mjs";
+import { winkInstance } from "../adapters/wink-model.mjs";
 
 /** Split text into trimmed, non-empty sentences via wink-nlp's own
  *  sentence-boundary detection — never a naive regex split, matching the

package/src/{sessions.mjs → services/sessions.mjs}

@@ -18,7 +18,8 @@
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { appendUtterances, CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/core.mjs";
+import { appendUtterances, CREATED_AT_PROP, UPDATED_AT_PROP } from "../adapters/memory/core.mjs";
+import { turnKey } from "../domain/memory/session-turns.mjs";
 
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 
@@ -236,7 +237,7 @@ async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
     ended = Boolean(parseSessionJsonl(sidecar)?.ended);
   } catch { /* no sidecar — nothing to fold from */ }
   if (ended) {
-    const { foldSessionLogs } = await import("./memory/fold.mjs"); // lazy: fold imports this module
+    const { foldSessionLogs } = await import("./fold.mjs"); // lazy: fold imports this module
     await foldSessionLogs(repoDir, { sessionId: record.id });
   }
 }
@@ -277,9 +278,7 @@ export function parseSessionJsonl(text) {
 // echoed "> <query>" line (chat.mjs's logLines shape).
 const LOG_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
 
-/** Key a transcript answer by its turn: ts + query (ts alone can collide when
- *  two instant turns land in the same millisecond). */
-export const turnKey = (ts, query) => `${ts}${query}`;
+export { turnKey };
 
 /**
  * Parse a human-readable session transcript (.tmct/session-<id>.log) into a

package/src/{telemetry.mjs → services/telemetry.mjs}

@@ -12,7 +12,7 @@
 
 import { appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { uuidv7 } from "./uuid.mjs";
+import { uuidv7 } from "../adapters/uuid.mjs";
 
 /** Field names whose VALUES are (or embed) raw source and must never be logged. `body` is
  *  the Repository Interface's own field name for real source text (snippet()/context()'s

package/src/{server-http.mjs → surfaces/http/server-http.mjs}

@@ -11,29 +11,24 @@
 // Every response's `usage` is { input_tokens: 0, output_tokens: 0 } — tmct is the $0
 // floor, priced as free by the meter.
 //
-// src/server.mjs is the tool-dispatch layer, not an HTTP server; this module is the
+// src/tools/server.mjs is the tool-dispatch layer, not an HTTP server; this module is the
 // HTTP surface.
 
 import { createServer } from "node:http";
-import { runTurn, COMMANDS, asBareCommand, isConversational } from "./chat.mjs";
-import { TOOLS } from "./server.mjs";
-import { parseEntities } from "./codegraph.mjs";
-import { uuidv7 } from "./uuid.mjs";
-import * as defaultSource from "./source.mjs";
+import { runTurn, selectTool } from "../../services/chat.mjs";
+import { TOOLS } from "../../tools/server.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
+import { uuidv7 } from "../../adapters/uuid.mjs";
+import * as defaultSource from "../../adapters/source.mjs";
+
+// The shim's deterministic tool selection lives with the chat surface's own
+// command routing (selectTool in chat.mjs); re-exported here so HTTP-side
+// callers keep one import site for the whole shim seam.
+export { selectTool } from "../../services/chat.mjs";
 
 /** The zero usage every response carries — the meter prices tmct as the $0 floor. */
 const ZERO_USAGE = { input_tokens: 0, output_tokens: 0 };
 
-/** The tmct tools dispatchTool can back (the set the shim will emit a tool_use for).
- *  A declared tool outside this set is ignored for emission (the request falls
- *  through to a text answer) — the shim never emits a call it cannot ground. The
- *  COMMANDS map (chat.mjs) names the richer graph tools; TOOLS names the hot
- *  catalog. Their union is what dispatchTool serves. */
-const BACKED_TOOLS = new Set([
-  ...TOOLS.map((t) => t.name),
-  ...Object.values(COMMANDS).map((s) => s.tool),
-]);
-
 /** Flatten a message's `content` (a string OR a content-block array) into plain
  *  text — concatenating the `text` blocks. Non-text blocks are ignored here. */
 function textOfContent(content) {
@@ -74,55 +69,6 @@ function toolResultText(block) {
   try { return JSON.stringify(c); } catch { return String(c); }
 }
 
-/**
- * Decide whether a user turn maps to a DECLARED, dispatch-backed graph-query
- * tool, and bind its arguments. Deterministic, in-ethos (no NL guessing beyond
- * the chat surface's own command routing):
- *
- *   1. A slash/bare command that names a tmct tool ("describe X", "/callers X",
- *      "untested") → that tool with its argument bound from the exact arg key the
- *      dispatchTool switch reads (COMMANDS in chat.mjs). Only when the tool is
- *      declared by the caller.
- *   2. Otherwise, a non-conversational structural question → tmct_ask{query:…},
- *      when tmct_ask is declared. Small-talk (isConversational) never emits a
- *      call — it falls through to a text answer.
- *
- * Returns { name, input } or null (→ answer as text).
- */
-export function selectTool(text, declaredNames) {
-  const t = String(text || "").trim();
-  if (!t) return null;
-
-  // 1. explicit command form → a specific tool, argument bound
-  const cmdLine = t.startsWith("/") ? t : asBareCommand(t);
-  if (cmdLine) {
-    const [first, ...restTok] = cmdLine.replace(/^\//, "").split(/\s+/);
-    const spec = COMMANDS[String(first).toLowerCase()];
-    if (spec && declaredNames.has(spec.tool) && BACKED_TOOLS.has(spec.tool)) {
-      const input = {};
-      if (spec.arg) {
-        const val = restTok.join(" ").trim();
-        if (val) input[spec.arg] = val;
-        // an entity command with no argument can't bind a call — fall through
-        else if (!spec.optional) return askFallback(t, declaredNames);
-      }
-      return { name: spec.tool, input };
-    }
-  }
-
-  // 2. structural question → tmct_ask, unless it's small-talk
-  return askFallback(t, declaredNames);
-}
-
-/** The tmct_ask fallback: emit tmct_ask{query} for a non-conversational line when
- *  the caller declared tmct_ask; otherwise null (→ text answer). */
-function askFallback(text, declaredNames) {
-  if (declaredNames.has("tmct_ask") && BACKED_TOOLS.has("tmct_ask") && !isConversational(text)) {
-    return { name: "tmct_ask", input: { query: text } };
-  }
-  return null;
-}
-
 /** Build the assistant message envelope shared by every branch. */
 function assistantMessage(model, content, stopReason) {
   return {