@polycode-projects/the-mechanical-code-talker 1.5.4 → 1.8.3

package/src/cli-args.mjs

@@ -0,0 +1,164 @@
+// cli-args.mjs — the ONE shared argv/config resolver for bin/tmct.mjs's
+// subcommands. Replaces four independently hand-rolled `configFor` copies
+// (bin/tmct.mjs's cli-mode and serve-mode ones, chat.mjs's own, and the richer
+// 4-tier version inlined in chat.mjs's createSession) with a single, tested
+// precedence chain — built on top of toml-config.mjs's already-tested
+// mergeEffective/normalizeConfig (arg > toml > default), not a rebuild of it.
+//
+// Three tiny flag helpers (pure, no I/O) plus the one async resolver:
+//   strFlag(rest, names, dflt)   → single value, last flag occurrence wins
+//   repeatedFlag(rest, names)    → every value for a repeatable flag (e.g. --graph)
+//   boolFlag(rest, names)        → true if any of `names` appears at all
+//   resolveRuntimeConfig({argv, cwd, env, gitRoot}) → the resolved repo/config
+//
+// Graph-path precedence (documented once, here — every subcommand shares it):
+//   1. --graph <path>   (repeatable; --graph wins outright, even over env)
+//   2. TMCT_GRAPH_FILE  (env)
+//   3. tmct.toml's `graph_file` / `graph_files`
+//   4. <repo>/.tmct/graph.json, where repo is --repo, else git root, else cwd
+//
+// Deliberately does NOT import chat.mjs (that would be circular once chat.mjs
+// itself is rewired to call resolveRuntimeConfig) — the git-root lookup below
+// is a small, self-contained copy of chat.mjs's own gitToplevel().
+
+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";
+
+/** 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
+ *  import) — see the file docblock for why. */
+function defaultGitRoot(cwd) {
+  try {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+    if (r.status === 0) { const p = String(r.stdout || "").trim(); return p || null; }
+  } catch { /* git missing / not a repo — fall back to cwd */ }
+  return null;
+}
+
+const asList = (names) => (Array.isArray(names) ? names : [names]);
+
+/** Single-value flag, LAST occurrence wins (so `--repo a --repo b` → "b").
+ *  `names` may be a single flag string or an array of aliases. */
+export function strFlag(rest, names, dflt) {
+  const list = asList(names);
+  let val = dflt;
+  for (let i = 0; i < rest.length; i++) {
+    if (list.includes(rest[i]) && rest[i + 1] !== undefined) val = rest[i + 1];
+  }
+  return val;
+}
+
+/** Repeatable flag — every value across every occurrence, in argv order
+ *  (`--graph a --graph b` → `["a","b"]`). Empty array when absent. */
+export function repeatedFlag(rest, names) {
+  const list = asList(names);
+  const out = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (list.includes(rest[i]) && rest[i + 1] !== undefined) out.push(rest[i + 1]);
+  }
+  return out;
+}
+
+/** Presence flag — true if any of `names` appears anywhere in `rest`. */
+export function boolFlag(rest, names) {
+  const list = asList(names);
+  return rest.some((r) => list.includes(r));
+}
+
+/**
+ * Resolve one subcommand invocation's repo root, tmct.toml, and graph
+ * path(s) — the shared precedence chain every subcommand (chat/memory/init/
+ * import/syllogise/serve) now funnels through instead of re-deriving it.
+ *
+ * @param {object} opts
+ * @param {string[]} [opts.argv]   the subcommand's own argv tail (already past
+ *   `tmct <mode>` — the same slice each subcommand hand-parses today).
+ * @param {string}   [opts.cwd]
+ * @param {object}   [opts.env]
+ * @param {(cwd:string)=>string|null} [opts.gitRoot]  injectable for tests,
+ *   mirrors createSession's own `gitRoot` param.
+ * @param {object}   [opts.args]  extra already-parsed args to fold into
+ *   mergeEffective's "arg" tier (e.g. a subcommand's own flags) — optional,
+ *   defaults to {}.
+ * @returns {Promise<{
+ *   repo: string, configPath: string, toml: object,
+ *   config: {graphFile: string, graphFiles: string[]},
+ *   effective: object, sources: object,
+ * }>}
+ */
+export async function resolveRuntimeConfig({
+  argv = [],
+  cwd = process.cwd(),
+  env = process.env,
+  gitRoot = defaultGitRoot,
+  args = {},
+} = {}) {
+  const configFlag = strFlag(argv, ["--config"]);
+  const repoFlag = strFlag(argv, ["--repo"]);
+  const graphFlags = repeatedFlag(argv, ["--graph"]);
+
+  const root = typeof gitRoot === "function" ? gitRoot(cwd) : null;
+  const repo = repoFlag ? resolve(cwd, repoFlag) : (root || cwd);
+
+  // --config <path>: a file OR a directory. A directory means "look for
+  // tmct.toml under here"; a file is the tmct.toml itself, wherever it lives.
+  let configDir = repo;
+  let configFileOverride;
+  if (configFlag) {
+    const abs = resolve(cwd, configFlag);
+    let isDir = false;
+    try { isDir = (await stat(abs)).isDirectory(); } catch { /* missing path — treat as a file target */ }
+    if (isDir) configDir = abs;
+    else { configFileOverride = abs; configDir = dirname(abs); }
+  }
+
+  const raw = await loadTomlConfig(configDir, configFileOverride ? { file: configFileOverride } : {});
+  const toml = await normalizeConfig(raw, { configDir });
+
+  const defaultGraphFile = join(repo, DEFAULT_GRAPH_REL);
+  const envGraph = env && env.TMCT_GRAPH_FILE && String(env.TMCT_GRAPH_FILE).trim();
+
+  let graphFiles;
+  let graphSource; // "arg" | "env" | "tmct.toml" | "default"
+  if (graphFlags.length) {
+    graphFiles = graphFlags.map((g) => resolve(cwd, g));
+    graphSource = "arg";
+  } else if (envGraph) {
+    graphFiles = [resolve(cwd, envGraph)];
+    graphSource = "env";
+  } else if (toml.graphFiles && toml.graphFiles.length) {
+    graphFiles = toml.graphFiles;
+    graphSource = "tmct.toml";
+  } else if (toml.graphFile) {
+    graphFiles = [toml.graphFile];
+    graphSource = "tmct.toml";
+  } else {
+    graphFiles = [defaultGraphFile];
+    graphSource = "default";
+  }
+
+  // mergeEffective wires in toml-config.mjs's already-tested arg>toml>default
+  // precedence for every OTHER knob (index/tune/corpus/…); graphFile's own
+  // precedence is richer (it has an env tier mergeEffective doesn't model), so
+  // it's resolved above and folded back in below rather than re-derived here.
+  const defaults = { graphFile: defaultGraphFile };
+  const { effective, sources } = mergeEffective({ args, toml, defaults });
+  effective.graphFile = graphFiles[0];
+  sources.graphFile = graphSource;
+  if (graphFiles.length > 1) effective.graphFiles = graphFiles;
+
+  const configPath = configFileOverride || join(configDir, CONFIG_FILE);
+
+  return {
+    repo,
+    configPath,
+    toml,
+    config: { graphFile: graphFiles[0], graphFiles },
+    effective,
+    sources,
+  };
+}

package/src/codegraph.mjs

@@ -1,5 +1,9 @@
 import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
+// Single-sourced predicate strings (memory/core.mjs owns these constants) — no
+// circular-import risk: core.mjs imports trust.mjs/shacl.mjs/planning.mjs, never
+// codegraph.mjs, in either direction.
+import { CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/core.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
 // deterministic indexer writes to <repo>/.tmct/graph.json (shape produced by
@@ -91,6 +95,13 @@ const PROP_KIND = {
   "mg:defines": "defines",
   "mg:tests": "tests",
   "mg:touches": "touches",
+  // memory-graph predicates (src/memory/core.mjs, src/sessions.mjs) — each maps to
+  // itself as its own kind name (no module-rollup abbreviation needed, unlike
+  // imports/calls) so adjacencyForKinds/edgesOfKind can walk the memory graph too.
+  "mgx:saidinsession": "saidInSession",
+  "mgx:inreplyto": "inReplyTo",
+  "mgx:statedby": "statedBy",
+  "mgx:canonicalisedfrom": "canonicalisedFrom",
 };
 
 export function relationKind(group) {
@@ -579,6 +590,12 @@ const SPIRAL_DEPTH_DEFAULT = 3;
 const SPIRAL_NODE_LIMIT_DEFAULT = 12;
 const SPIRAL_Q_DEFAULT = 0.9;                 // mild hub pruning (drop only the densest 10%) — the centre point
 const SPIRAL_EXPAND_KINDS = ["imports", "calls", "callsSymbol", "inherits"]; // cochange dropped
+// The memory graph's real edge-kind inventory (traced via every objectProperties.push/.find
+// site in src/memory/*.mjs and src/sessions.mjs) — the `kinds` a memory-graph spiralExpand call
+// passes so it walks Session/Fact/Source/Utterance individuals rather than code-graph Modules.
+// NOTE: mgx:asksAbout (src/sessions.mjs) is deliberately EXCLUDED — that predicate lives in the
+// CODE graph (Session ↔ code entities a chat turn resolved/answered), not the memory graph.
+export const MEMORY_SPIRAL_EXPAND_KINDS = ["saidInSession", "inReplyTo", "statedBy", "canonicalisedFrom"];
 const SPIRAL_EMIT_FRAC = 0.5;                 // a newly-surfaced node's base score = maxSeed × this …
 const SPIRAL_HOP_DECAY = 0.6;                 //  … decayed by this per hop from the seeds (bounded < maxSeed, so a walked-in node never dominates rank 1)
 const SPIRAL_PROX_FRAC = 0.2;                 // an ALREADY-matched module the spiral re-reaches gets a bounded nudge …
@@ -623,8 +640,13 @@ function identComponents(name) {
 /** For one edge-kind group, the depth-1 successor of `fromId` reachable via any edge in `kinds`,
  *  as a Map<moduleId, neighbourModuleId> adjacency (undirected — a module's neighbours via that
  *  kind, in either edge direction). Endpoints are mapped to their containing module first (call
- *  edges live at function granularity), matching the existing E1a call-adjacency convention. */
-function adjacencyForKinds(graph, kinds) {
+ *  edges live at function granularity), matching the existing E1a call-adjacency convention.
+ *  `idNormalizer` (default null) lets a caller fold edge endpoints some OTHER way — the memory
+ *  graph has no "containing module" concept, so a memory-graph caller passes `(id) => id` to walk
+ *  its raw individual ids unchanged. Defaulting to null (rather than `moduleIdOfId` directly)
+ *  keeps the sole existing caller (`adjacencyForKinds(graph, kinds)` in beamExpand) byte-identical. */
+export function adjacencyForKinds(graph, kinds, idNormalizer = null) {
+  const norm = idNormalizer || ((id) => moduleIdOfId(graph, id));
   const adj = new Map();
   const link = (a, b) => {
     if (!a || !b || a === b) return;
@@ -635,7 +657,7 @@ function adjacencyForKinds(graph, kinds) {
   };
   for (const kind of kinds) {
     for (const e of edgesOfKind(graph, kind)) {
-      link(moduleIdOfId(graph, e.subject), moduleIdOfId(graph, e.object));
+      link(norm(e.subject), norm(e.object));
     }
   }
   return adj;
@@ -707,24 +729,55 @@ function beamExpand(graph, scored, beamWidth) {
 }
 
 /** SPIRAL expansion (opt-in; see the SPIRAL_* constants' comment above for the full design).
- *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`), popped
- *  fewest-arcs-first via a min-heap keyed (hop ASC, in-graph degree ASC, id ASC), with a
- *  degree-quantile hub gate at each expansion step. Emits up to `nodeLimit` newly-reached nodes
- *  in pop order, scoring each seed-relative and bounded so a hub can't dominate rank 1.
+ *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`, or an explicit
+ *  `seeds` override — see below), popped fewest-arcs-first via a min-heap keyed (hop ASC,
+ *  in-graph degree ASC, id ASC), with a degree-quantile hub gate at each expansion step. Emits
+ *  up to `nodeLimit` newly-reached nodes in pop order, scoring each seed-relative and bounded so
+ *  a hub can't dominate rank 1.
  *  CRITICAL vs beamExpand: it deliberately OMITS the `if (!baseScore.has) continue` guard, so it
  *  MAY push modules that had NO lexical match into `scored` — the one path to breaking the lexical
- *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules).
- *  Pure otherwise (no fs/network); deterministic total ordering throughout. */
-function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_Q_DEFAULT, nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT } = {}) {
-  if (!scored.length) return;
+ *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules)
+ *  when the score-nudge machinery is active. Pure otherwise (no fs/network); deterministic total
+ *  ordering throughout.
+ *
+ *  Generalised (2026-07-11) past its original code-graph-only, `scored`-only shape so a pure
+ *  graph-visualisation walk (no lexical match list at all) can reuse the exact same traversal:
+ *   - `scored` is now OPTIONAL (default `[]`) — a bare walk with no ranking machinery.
+ *   - `kinds` (default `SPIRAL_EXPAND_KINDS`) — the edge-kind set to walk; a memory-graph caller
+ *     passes `MEMORY_SPIRAL_EXPAND_KINDS`.
+ *   - `classPredicate` (default `(ind) => (ind.class || "") === "Module"`) — replaces the two
+ *     hardcoded `"Module"` checks below, so a memory-graph caller can pass `() => true` (every
+ *     class walkable) or any other individual filter.
+ *   - `idNormalizer` (default `null`) — threaded straight into the internal `adjacencyForKinds`
+ *     call; a memory-graph caller passes `(id) => id` (no module-folding).
+ *   - `seeds` (default derived from `scored`, as before) — an explicit id iterable, so a caller
+ *     with no `scored` list at all (e.g. `mostRecentIndividual`'s single seed) can still drive
+ *     the walk.
+ *  The score-nudge machinery (mutating `scored`/introducing newly-surfaced individuals into it)
+ *  is gated behind `scored.length > 0 && maxSeed > 0` — the exact condition the original early
+ *  return checked — so an empty `scored` degrades gracefully into a pure walk rather than erroring.
+ *  Returns `[{id, hop}]` for every node the walk actually pops (seeds included, at hop 0) — this
+ *  used to return `undefined`; safe, since the sole caller (`scoreModules`) already discards the
+ *  return value (confirmed by inspection, not assumed). */
+export function spiralExpand(graph, scored = [], {
+  depth = SPIRAL_DEPTH_DEFAULT,
+  q = SPIRAL_Q_DEFAULT,
+  nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT,
+  kinds = SPIRAL_EXPAND_KINDS,
+  classPredicate = (ind) => (ind.class || "") === "Module",
+  idNormalizer = null,
+  seeds: seedsOpt = null,
+} = {}) {
   const byId = new Map(scored.map((s) => [s.ind.id, s]));
-  const seeds = new Set(byId.keys());
   let maxSeed = 0;
   for (const s of scored) maxSeed = Math.max(maxSeed, s.score);
-  if (!(maxSeed > 0)) return;
-  // Combined undirected adjacency over the expansion kinds (cochange dropped). In-graph degree =
-  // neighbour count over these kinds — the "arcs" the frontier orders and the quantile gate reads.
-  const adj = adjacencyForKinds(graph, SPIRAL_EXPAND_KINDS);
+  const nudgeActive = scored.length > 0 && maxSeed > 0; // the original "!(maxSeed > 0) → return" guard, now a gate rather than a bail-out
+  const seeds = new Set(seedsOpt != null ? seedsOpt : byId.keys());
+  if (!seeds.size) return [];
+  // Combined undirected adjacency over the expansion kinds (cochange dropped for the code-graph
+  // default). In-graph degree = neighbour count over these kinds — the "arcs" the frontier orders
+  // and the quantile gate reads.
+  const adj = adjacencyForKinds(graph, kinds, idNormalizer);
   const degree = (id) => (adj.get(id)?.size || 0);
   // Binary min-heap over the frontier, keyed (hop ASC, degree ASC, id ASC) — pop the closest,
   // least-connected node first, so expansion fans through the sparse surroundings and fizzles at
@@ -757,35 +810,41 @@ function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_
   };
   const visited = new Set(seeds);
   for (const id of seeds) push({ id, hop: 0, deg: degree(id) });
-  const defIdx = definesIndex(graph);
+  let defIdx = null; // lazy: only the nudge-active path (newly-surfaced individuals) needs this
   let emitted = 0;
+  const results = [];
   while (heap.length && emitted < nodeLimit) {
     const node = pop();
+    results.push({ id: node.id, hop: node.hop });
     if (!seeds.has(node.id)) {
-      // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
-      const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
-      const existing = byId.get(node.id);
-      if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
-        existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
-      } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
-        const ind = graph.byId?.get?.(node.id);
-        if (ind && (ind.class || "") === "Module") {
-          const defines = defIdx.get(ind.id) || [];
-          const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
-          scored.push(entry);
-          byId.set(node.id, entry);
+      if (nudgeActive) {
+        // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
+        const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
+        const existing = byId.get(node.id);
+        if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
+          existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
+        } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
+          const ind = graph.byId?.get?.(node.id);
+          if (ind && classPredicate(ind)) {
+            if (!defIdx) defIdx = definesIndex(graph);
+            const defines = defIdx.get(ind.id) || [];
+            const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
+            scored.push(entry);
+            byId.set(node.id, entry);
+          }
         }
       }
       emitted++;
     }
     if (node.hop >= depth) continue;
-    // This step's candidate set = the popped node's unvisited MODULE neighbours; quantile-gate by
-    // degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never fewer than one.
+    // This step's candidate set = the popped node's unvisited neighbours matching classPredicate;
+    // quantile-gate by degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never
+    // fewer than one.
     const cands = [];
     for (const nid of adj.get(node.id) || []) {
       if (visited.has(nid)) continue;
       const ind = graph.byId?.get?.(nid);
-      if (!ind || (ind.class || "") !== "Module") continue; // no phantom (fn-fallback) module ids
+      if (!ind || !classPredicate(ind)) continue; // no phantom (fn-fallback) ids
       cands.push({ id: nid, deg: degree(nid) });
     }
     if (!cands.length) continue;
@@ -797,6 +856,24 @@ function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_
       push({ id: c.id, hop: node.hop + 1, deg: c.deg });
     }
   }
+  return results;
+}
+
+/** The individual with the most recent `createdAtProp` attribute — item 1's ("Traversal") seed
+ *  default: "sort memory-graph individuals by mgx:createdAt descending, seed from the single most
+ *  recent." Deterministic tie-break by id (lowest id wins) when two individuals share the exact
+ *  same timestamp — same total-order convention `spiralExpand`'s own heap uses. Null when no
+ *  individual carries the attribute at all (empty graph, or a graph that predates timestamps).
+ *  ISO-8601 timestamps compare correctly as plain strings (same zero-padded width throughout this
+ *  codebase), so no Date parsing is needed. */
+export function mostRecentIndividual(graph, createdAtProp = CREATED_AT_PROP) {
+  let best = null; // { ind, v }
+  for (const ind of graph?.individuals || []) {
+    const v = (ind?.attributes || []).find((a) => a?.prop === createdAtProp)?.value;
+    if (!v) continue;
+    if (!best || v > best.v || (v === best.v && String(ind.id) < String(best.ind.id))) best = { ind, v };
+  }
+  return best ? best.ind : null;
 }
 
 /** The shared module-ranking core behind renderSearch (text) and searchModulesRanked (path+score).
@@ -1203,6 +1280,67 @@ export function edgesOfKind(graph, kind) {
   return out;
 }
 
+/** A node's "last touched" moment, DERIVED rather than stored (PLAN_VIZ.md §2): the node's own
+ *  `updatedAtProp`/`createdAtProp` attribute, or the max `createdAt` over every edge (in
+ *  `graph.relations`, ACROSS every kind, not just classified ones) touching it as either
+ *  subject or object — whichever is newer. `""` when nothing carries a timestamp at all. Compares
+ *  ISO-8601 strings directly (correct for same-width zero-padded timestamps, no Date parsing).
+ *  Tolerates edges with no `createdAt` field (pre-dating `upsertEdge`'s own stamp, or written by
+ *  a path that bypasses `upsertEdge` entirely) by simply skipping them, never throwing. Operates
+ *  on the shared parsed-graph shape (`graph.relations`/`graph.individuals`), not memory-specific —
+ *  same reasoning `edgesOfKind`/`moduleIdOf` already document. */
+export function derivedUpdatedAt(graph, ind, { createdAtProp = CREATED_AT_PROP, updatedAtProp = UPDATED_AT_PROP } = {}) {
+  if (!ind) return "";
+  const attrs = ind.attributes || [];
+  const own = attrs.find((a) => a?.prop === updatedAtProp)?.value || attrs.find((a) => a?.prop === createdAtProp)?.value || "";
+  let best = own || "";
+  for (const g of graph?.relations || []) {
+    for (const e of g.edges || []) {
+      if (!e || (e.subject !== ind.id && e.object !== ind.id)) continue;
+      const c = e.createdAt;
+      if (!c) continue; // no timestamp on this edge — skip, never throw
+      if (!best || c > best) best = c;
+    }
+  }
+  return best;
+}
+
+/** Turn a `spiralExpand` walk (`[{id, hop}]`) into the `{nodes, edges}` shape
+ *  `tmct viz` renders — pure, no I/O, shared verbatim between the CLI
+ *  (`src/viz.mjs`'s `computeVizGraph`) and the browser bundle's client-side
+ *  re-walk/recentre (PLAN_BREADTH_FIRST_NLU.md §5 follow-on, operator
+ *  directive 2026-07-11) so both paths render byte-identically from the same
+ *  logic, never two hand-maintained copies. `nodes` enrich each walked id with
+ *  its real label/class/timestamps (`derivedUpdatedAt`, above); `edges` are
+ *  every relation-group edge connecting two walked nodes (not just the kinds
+ *  the walk itself traversed through — an incidental edge between two reached
+ *  nodes still renders), de-duped on (subject, object, predicate) across
+ *  relation groups. */
+export function buildVizNodesAndEdges(graph, walked, { createdAtProp = CREATED_AT_PROP, updatedAtProp = UPDATED_AT_PROP } = {}) {
+  const nodeIds = new Set(walked.map((w) => w.id));
+  const nodes = walked.map(({ id, hop }) => {
+    const ind = graph.byId.get(id) || null;
+    const attrs = ind?.attributes || [];
+    const createdAt = attrs.find((a) => a?.prop === createdAtProp)?.value || "";
+    return {
+      id, hop, label: ind?.label || id, class: ind?.class || "", createdAt,
+      updatedAt: derivedUpdatedAt(graph, ind, { createdAtProp, updatedAtProp }),
+    };
+  });
+  const edges = [];
+  const seen = new Set();
+  for (const group of graph.relations || []) {
+    for (const e of group.edges || []) {
+      if (!nodeIds.has(e.subject) || !nodeIds.has(e.object)) continue;
+      const key = `${e.subject} ${e.object} ${group.predicate}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({ source: e.subject, target: e.object, kind: group.predicate });
+    }
+  }
+  return { nodes, edges };
+}
+
 /** moduleIdOf by raw edge-endpoint id: resolves through byId when the individual exists,
  *  else falls back to parsing an `fn:<path>#name` id directly (callsSymbol objects may name
  *  symbols with no individual of their own). Null if it cannot be mapped. */

package/src/completions/graph-adapter.mjs

@@ -0,0 +1,118 @@
+// completions/graph-adapter.mjs — HANDOVER.md item 1: the graphService-shaped adapter
+// src/completions/search.mjs's broadSearch() was always built to accept — its own
+// docblock names createGraphService(graph) (src/providers/graph-service.mjs) as the
+// reference shape — but until now nothing in live chat ever constructed and passed one
+// through (src/chat.mjs's completionsRescueAnswer called generateCompletion() with no
+// `graphService` at all). Without it, broadSearch could only ever see memory BLOCKS
+// saved via an explicit saveBlock() call — never the already-loaded code graph, and
+// never a taught Fact — so "give me a detailed summary of how X works" declined for any
+// subject on its first real mention in a session, no matter how much the graph or
+// taught Facts actually knew about it.
+//
+// createCompletionsGraphAdapter(graph, memory) wraps TWO already-loaded stores (never
+// re-loads either from disk — both are handed in by the caller, exactly as loaded for
+// this turn):
+//
+//   - .search(q, {limit}) delegates straight to createGraphService(graph).search() —
+//     the same ranked lexical module/symbol search every other Repository-Interface
+//     consumer uses (src/codegraph.mjs's searchModulesRanked/scoreSymbolsRanked under
+//     the hood). No new search machinery.
+//
+//   - .ask(q) does NOT delegate to createGraphService(graph).ask() (src/ask.mjs) —
+//     that engine is a mechanical NATURAL-LANGUAGE QUESTION grammar ("which functions
+//     call X", "what does X import"), and broadSearch always calls .ask() with the
+//     bare SUBJECT TERM itself ("TaskController"), not a question. Tried live: that
+//     produces an honest but useless "couldn't parse this as a graph question"
+//     rephrase-hint every time — real text, but not about the subject, and it would
+//     pollute the completion with noise. Instead .ask() here builds real sentences
+//     from two sources that a bare term CAN resolve against directly:
+//       1. resolveSymbol + renderDescribe (src/codegraph.mjs) — the SAME graph-only
+//          renderer src/server.mjs's own tmct_describe tool uses: real facts (defining
+//          module, contains, inherits, calls, tests, attributes, …), never invented.
+//       2. readFactRows(memory) (src/memory/core.mjs) — any TAUGHT Fact whose subject
+//          or object mentions the term. This is the one source the pipeline had NO
+//          path to before at all: Stage 3 (inferRelations) only ever augments groups
+//          that already exist from Stage 1's hits, so a subject with real taught Facts
+//          but zero blocks/code-graph hits still surfaced nothing.
+//     svc.ask() is still tried last, but its content is kept ONLY when it genuinely
+//     parsed (tmct_ask.miss === false) — e.g. the rare case where the bare term happens
+//     to also be a real registered question shape — never its own rephrase-hint noise.
+//
+// Every sentence this adapter returns traces to a real graph edge/attribute or a real
+// taught Fact — never invented, matching src/completions/'s extractive-only discipline
+// (see complete.mjs's own file header).
+
+import { createGraphService } from "../providers/graph-service.mjs";
+import { resolveSymbol, renderDescribe } from "../codegraph.mjs";
+import { readFactRows } from "../memory/core.mjs";
+
+/** renderDescribe() renders one LINE per fact (label header, each attribute, each edge
+ *  group) with no terminal punctuation of its own — fine for its own "compact plain-text
+ *  description for an agent consumer" purpose, but src/completions/rank.mjs's
+ *  splitSentences() treats each line as its own candidate sentence, and complete.mjs
+ *  joins kept sentences with a single space — so two adjacent kept lines without a
+ *  period between them would otherwise read as one run-on clause. Ensuring every line
+ *  ends in terminal punctuation here (never rewording/reordering the line itself) is
+ *  the cheapest fix that stays entirely inside this adapter, touching neither
+ *  renderDescribe() (server.mjs's tmct_describe tool relies on its current line shape)
+ *  nor rank.mjs/complete.mjs's own join logic. */
+function withTerminalPunctuation(text) {
+  return String(text || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => (/[.!?]$/.test(line) ? line : `${line}.`))
+    .join("\n");
+}
+
+/**
+ * @param {object|null} graph   a parseEntities() result (src/codegraph.mjs), or null
+ *   when no code graph is loaded — search()/the describe-half of ask() then honestly
+ *   contribute nothing, rather than throwing.
+ * @param {object|null} [memory=null]  a loadMemory() payload (src/memory/core.mjs), or
+ *   null when there's no Fact store to search — the Fact-half of ask() then honestly
+ *   contributes nothing.
+ * @returns {{search: Function, ask: Function}} a Repository-Interface-shaped
+ *   graphService satisfying src/completions/search.mjs's broadSearch() contract.
+ */
+export function createCompletionsGraphAdapter(graph, memory = null) {
+  const svc = graph ? createGraphService(graph) : null;
+
+  return {
+    search(q, { limit } = {}) {
+      if (!svc) return { ok: true, value: { results: [] } };
+      return svc.search(q, { limit });
+    },
+
+    ask(q) {
+      const term = String(q || "").trim();
+      if (!term) return { ok: true, value: { content: "" } };
+      const sentences = [];
+
+      if (svc) {
+        const { match, candidates } = resolveSymbol(graph, term);
+        if (match) sentences.push(withTerminalPunctuation(renderDescribe(graph, match, { candidates })));
+      }
+
+      if (memory) {
+        const needle = term.toLowerCase();
+        for (const row of readFactRows(memory)) {
+          if (!row.subject || !row.predicate || !row.object) continue;
+          const haystack = `${row.subject} ${row.object}`.toLowerCase();
+          if (!haystack.includes(needle)) continue;
+          sentences.push(`${row.subject} ${row.predicate} ${row.object}.`.trim());
+        }
+      }
+
+      if (svc) {
+        const res = svc.ask(term);
+        if (res?.ok && res.value?.tmct_ask?.miss === false && res.value.content) {
+          sentences.push(res.value.content);
+        }
+      }
+
+      if (!sentences.length) return { ok: true, value: { content: "" } };
+      return { ok: true, value: { content: sentences.join(" ") } };
+    },
+  };
+}