@polycode-projects/the-mechanical-code-talker 1.11.6 → 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 "";
   }
@@ -225,6 +225,38 @@ export function resolveAnsweredTerm(answerText, questionText, terms, normFn) {
   return (terms || []).some((t) => t && t.term === norm) ? norm : null;
 }
 
+/** Per-segment facet counts for the rows touching `focus`: each group's count
+ *  is computed against the OTHER groups' active filters (its own group's
+ *  selection is skipped), so a selected family narrows the provenance and
+ *  recency counts but never its own rail. `sel` holds the active multi-select
+ *  Sets ({prov, fam, rec}); `now` anchors the recency buckets. Self-contained
+ *  on purpose: its source is injected into the rendered page verbatim, so it
+ *  must close over nothing. */
+export function facetCounts(rows, focus, sel, now) {
+  const DAY = 86400000;
+  const recencyOf = (r) => {
+    const t = Date.parse(r.createdAt);
+    if (!Number.isFinite(t)) return "older";
+    const age = now - t;
+    return age < DAY ? "today" : age < 7 * DAY ? "this week" : "older";
+  };
+  const passes = (r, skip) =>
+    (skip === "prov" || !sel.prov.size || sel.prov.has(r.prov)) &&
+    (skip === "fam" || !sel.fam.size || sel.fam.has(r.family)) &&
+    (skip === "rec" || !sel.rec.size || sel.rec.has(recencyOf(r)));
+  const counts = { prov: {}, fam: {}, rec: {} };
+  for (const r of rows || []) {
+    if (!focus || (r.s !== focus && r.o !== focus)) continue;
+    if (passes(r, "prov")) counts.prov[r.prov] = (counts.prov[r.prov] || 0) + 1;
+    if (passes(r, "fam")) counts.fam[r.family] = (counts.fam[r.family] || 0) + 1;
+    if (passes(r, "rec")) {
+      const k = recencyOf(r);
+      counts.rec[k] = (counts.rec[k] || 0) + 1;
+    }
+  }
+  return counts;
+}
+
 /** One complete, self-contained document: the ledger, segment rail,
  *  worth-a-look panel, breadcrumb/search, two-hop minimap, and (when the
  *  memory-ask bundle is present) the ask-the-graph chat dock, all over the
@@ -376,6 +408,7 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
 (function () {
   "use strict";
   const DAY = 86400000;
+  const facetCounts = ${facetCounts.toString()};
   const el = (id) => document.getElementById(id);
   const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
   const FAMS = ["is-a", "has", "can", "used-for", "rests-on", "role", "other"];
@@ -418,13 +451,11 @@ ${hasMemChat ? `<script>\n${bundleStr}\n</script>` : ""}
     return b;
   }
   function renderSegs() {
-    const mine = LEDGER.rows.filter((r) => focus && touches(r, focus));
+    const counts = facetCounts(LEDGER.rows, focus, sel, Date.now());
     const put = (id, group, values, labelOf, clsOf) => {
       const box = el(id); box.innerHTML = "";
       for (const v of values) {
-        const count = mine.filter((r) => passes(r, group) &&
-          (group === "prov" ? r.prov === v : group === "fam" ? r.family === v : recOf(r) === v)).length;
-        box.appendChild(segButton(group, v, labelOf(v), count, clsOf ? clsOf(v) : null));
+        box.appendChild(segButton(group, v, labelOf(v), counts[group][v] || 0, clsOf ? clsOf(v) : null));
       }
     };
     put("segProv", "prov", PROVS.map((p) => p[0]), (v) => PROVS.find((p) => p[0] === v)[1], (v) => "c-" + provKey(v));

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