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

package/src/{codegraph.mjs → domain/codegraph.mjs}

@@ -1,10 +1,10 @@
 import { lookupByProseTokens, proseLayerHits, splitIdentifierWords } from "./prose.mjs";
-import { cosine } from "./embed.mjs";
-import { CREATED_AT_PROP, UPDATED_AT_PROP, provenanceTagToSource } from "./memory/core.mjs";
+import { cosine } from "./vector.mjs";
+import { CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/trust.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
-// src/graph-build.mjs):
+// src/adapters/graph-build.mjs):
 //
 //   {
 //     generated_at, classes: [{name, count, sample[]}],
@@ -47,6 +47,14 @@ export function parseEntities(payload) {
   };
 }
 
+/** Code entities (Modules) in the loaded graph — the "is there a code graph here"
+ *  test. 0 means a graph-less bootstrap OR a graph.json with no code entities (the
+ *  degenerate trap); both orient rather than over-promise. */
+export function moduleCountOf(graph) {
+  if (!graph || !Array.isArray(graph.individuals)) return 0;
+  return graph.individuals.filter((i) => (i.class || "") === "Module").length;
+}
+
 // ---- relation-kind classifier (for impact + tests-coverage) -------------------
 
 const KINDS = ["imports", "calls", "defines", "tests", "touches", "contains", "inherits", "callsSymbol", "touchesSymbol"];
@@ -83,16 +91,11 @@ const PROP_KIND = {
   "mgx:inreplyto": "inReplyTo",
   "mgx:statedby": "statedBy",
   "mgx:canonicalisedfrom": "canonicalisedFrom",
-  // structural links deriveFactTermGraph synthesizes on every Fact (Fact -> its own subject/object Term)
-  "mgx:factsubjectterm": "factSubjectTerm",
-  "mgx:factobjectterm": "factObjectTerm",
 };
 
 export function relationKind(group) {
   const prop = String(group?.prop || "").toLowerCase();
   if (PROP_KIND[prop]) return PROP_KIND[prop];
-  // deriveFactTermGraph namespaces taught predicates as "factrel:<predicate>"
-  if (prop.startsWith("factrel:")) return group.predicate || null;
   const pred = String(group?.predicate || "").toLowerCase();
   // symbol-granular fallbacks first, so a near-miss still classifies fine-grained
   if (/symbol/.test(pred)) {
@@ -536,9 +539,6 @@ const SPIRAL_DEPTH_DEFAULT = 3;
 const SPIRAL_NODE_LIMIT_DEFAULT = 12;
 const SPIRAL_Q_DEFAULT = 0.9; // keep only the least-connected 90% at each step
 const SPIRAL_EXPAND_KINDS = ["imports", "calls", "callsSymbol", "inherits"]; // cochange dropped
-// The memory graph's edge-kind inventory a memory-graph spiralExpand call walks
-// instead of code-graph Modules. mgx:asksAbout is excluded — it lives in the code graph.
-export const MEMORY_SPIRAL_EXPAND_KINDS = ["saidInSession", "inReplyTo", "statedBy", "canonicalisedFrom"];
 const SPIRAL_EMIT_FRAC = 0.5;
 const SPIRAL_HOP_DECAY = 0.6;
 const SPIRAL_PROX_FRAC = 0.2;
@@ -769,19 +769,6 @@ export function spiralExpand(graph, scored = [], {
   return results;
 }
 
-/** The individual with the most recent `createdAtProp` attribute (ties break
- *  on lowest id); null if none carry the attribute. ISO-8601 timestamps
- *  compare correctly as plain strings, 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;
-}
-
 /** Shared module-ranking core behind renderSearch and searchModulesRanked.
  *  IDF-weights each query token, scores path/symbol/exact-symbol matches, and
  *  re-ranks with a bounded import-proximity bonus. Pure; deterministic. */
@@ -1117,247 +1104,6 @@ export function edgesOfKind(graph, kind) {
   return out;
 }
 
-/** A node's "last touched" moment: its own updatedAt/createdAt attribute, or
- *  the max `createdAt` over every edge touching it, whichever is newer. ""
- *  when nothing carries a timestamp. Skips edges with no `createdAt` rather than throwing. */
-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 into the `{nodes, edges}` shape `tmct viz`
- *  renders, shared between the CLI and the browser bundle's client-side
- *  re-walk. `edges` includes any relation-group edge connecting two walked
- *  nodes, not just kinds the walk itself traversed, de-duped on (subject, object, predicate). */
-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 };
-}
-
-const MEMORY_FACT_CLASS = "Fact";
-const MEMORY_TERM_CLASS = "Term";
-
-/** Derive a term-relation view of a memory graph's reified Facts (never
- *  mutates `graph`, viz-only). A Fact stores subject/predicate/object as
- *  plain string attributes, so the concept structure is invisible to a walk
- *  over `graph.relations` as-is; this synthesizes one Term individual per
- *  distinct subject/object string, one relation group per distinct fact
- *  predicate, and two fixed Fact->Term link groups so a walk seeded on a Fact
- *  can reach the term graph at all. Returns `{ graph: <augmented graph>,
- *  factRelationKinds: [<predicate>, …] }`; a graph with no Facts is a no-op. */
-export function deriveFactTermGraph(graph) {
-  const termById = new Map(); // term:<t> -> individual
-  const groupByPredicate = new Map(); // predicate -> relation group
-  const subjectLinks = []; // Fact -> its subject Term
-  const objectLinks = [];  // Fact -> its object Term
-  const termId = (t) => `term:${t}`;
-  const ensureTerm = (t) => {
-    const id = termId(t);
-    if (!termById.has(id)) termById.set(id, { id, label: t, class: MEMORY_TERM_CLASS, attributes: [] });
-    return id;
-  };
-
-  for (const ind of graph?.individuals || []) {
-    if ((ind?.class || "") !== MEMORY_FACT_CLASS) continue;
-    const attrs = ind.attributes || [];
-    const s = attrs.find((a) => a?.prop === "rdf:subject")?.value;
-    const p = attrs.find((a) => a?.prop === "rdf:predicate")?.value;
-    const o = attrs.find((a) => a?.prop === "rdf:object")?.value;
-    if (!s || !p || !o) continue; // a malformed/legacy Fact — skip, never throw
-    const subjectTermId = ensureTerm(s);
-    const objectTermId = ensureTerm(o);
-    let group = groupByPredicate.get(p);
-    if (!group) {
-      group = { predicate: p, prop: `factrel:${p}`, count: 0, edges: [] };
-      groupByPredicate.set(p, group);
-    }
-    group.edges.push({ subject: subjectTermId, object: objectTermId, subjectLabel: s, objectLabel: o });
-    group.count = group.edges.length;
-    subjectLinks.push({ subject: ind.id, object: subjectTermId, subjectLabel: ind.label, objectLabel: s });
-    objectLinks.push({ subject: ind.id, object: objectTermId, subjectLabel: ind.label, objectLabel: o });
-  }
-
-  if (!termById.size) return { graph, factRelationKinds: [] };
-
-  const individuals = [...(graph.individuals || []), ...termById.values()];
-  const byId = new Map(graph.byId);
-  for (const term of termById.values()) byId.set(term.id, term);
-  const relations = [
-    ...(graph.relations || []),
-    ...groupByPredicate.values(),
-    { predicate: "factSubjectTerm", prop: "mgx:factSubjectTerm", count: subjectLinks.length, edges: subjectLinks },
-    { predicate: "factObjectTerm", prop: "mgx:factObjectTerm", count: objectLinks.length, edges: objectLinks },
-  ];
-
-  return {
-    graph: { ...graph, individuals, byId, relations },
-    factRelationKinds: [...groupByPredicate.keys()],
-  };
-}
-
-/** The two fixed structural link kinds `deriveFactTermGraph` always emits.
- *  Bundled into the "relation" (concept) walk, not "meta" (provenance), so a
- *  user toggling to meta-only still gets the provenance-only view. */
-export const MEMORY_FACT_LINK_KINDS = ["factSubjectTerm", "factObjectTerm"];
-
-/** The combined kinds list a memory-graph walk uses for a given edge-kind
- *  mode: "meta" (provenance-only), "relation" (concept view), or "both"
- *  (default). Lives here, not viz.mjs, so the CLI and the browser bundle's
- *  client-side re-walk share the same function (viz.mjs does real fs I/O and
- *  can't be bundled for the browser). */
-export function edgeKindsFor(mode, factRelationKinds) {
-  const relationKinds = [...factRelationKinds, ...MEMORY_FACT_LINK_KINDS];
-  if (mode === "meta") return [...MEMORY_SPIRAL_EXPAND_KINDS];
-  if (mode === "relation") return relationKinds;
-  return [...MEMORY_SPIRAL_EXPAND_KINDS, ...relationKinds]; // "both" (default)
-}
-
-const LEGEND_MAX_BUCKETS = 20; // too many chips to be usable
-const LEGEND_MIN_BUCKETS = 2;  // nothing to filter with only one bucket
-const LEGEND_COLLAPSE_TOP_N = 15; // "top 15 by count, rest grouped as Other" — stays under the max
-
-/** Normalized Shannon entropy (`H / log2(k)`, `k` = bucket count) of a
- *  {value, count} bucket list — 1.0 for a perfectly even split, ~0 for one
- *  dominant bucket swallowing everything, undefined (returns 0) for k<2. */
-function normalizedEntropy(buckets) {
-  const k = buckets.length;
-  if (k < 2) return 0;
-  const total = buckets.reduce((sum, b) => sum + b.count, 0);
-  if (!total) return 0;
-  let h = 0;
-  for (const b of buckets) {
-    if (!b.count) continue;
-    const p = b.count / total;
-    h -= p * Math.log2(p);
-  }
-  return h / Math.log2(k);
-}
-
-/** Collapse a raw {value,count} bucket list down to at most LEGEND_MAX_BUCKETS
- *  entries: keep the top LEGEND_COLLAPSE_TOP_N by count, fold the rest into a
- *  single "Other" bucket, applied generically (not predicate-only) so
- *  any dimension that happens to be high-cardinality degrades the same way.
- *  A no-op (returns `buckets` unchanged, same array) when already <= the cap.
- *  Exported (not just used internally by pickLegendDimension) so the browser
- *  bundle's client-side legend (live per-view recomputation, viz.mjs's own
- *  computeLegendBuckets) collapses high-cardinality dimensions the SAME way,
- *  never a second hand-rolled copy that could drift. */
-export function collapseToTopN(buckets) {
-  if (buckets.length <= LEGEND_MAX_BUCKETS) return buckets;
-  const sorted = [...buckets].sort((a, b) => b.count - a.count || (a.value < b.value ? -1 : 1));
-  const kept = sorted.slice(0, LEGEND_COLLAPSE_TOP_N);
-  const restCount = sorted.slice(LEGEND_COLLAPSE_TOP_N).reduce((sum, b) => sum + b.count, 0);
-  return restCount ? [...kept, { value: "Other", count: restCount }] : kept;
-}
-
-function bucketCounts(values) {
-  const counts = new Map();
-  for (const v of values) {
-    if (v == null || v === "") continue;
-    counts.set(v, (counts.get(v) || 0) + 1);
-  }
-  return [...counts.entries()].map(([value, count]) => ({ value, count }));
-}
-
-/** The normalized provenance-prefix label for a Fact's FIRST recorded
- *  provenance tag (a Fact may carry a " | "-joined union of several; the
- *  legend buckets on the primary/first-recorded one, not a multiset) —
- *  reuses memory/core.mjs's own provenanceTagToSource parser (the SAME
- *  collapse-the-session-id/timestamp-suffix, keep-the-corpus/source-name
- *  logic the trust layer already relies on) rather than re-deriving it.
- *  Null when the Fact carries no provenance tag at all (a legacy/malformed
- *  row) or the tag doesn't parse to a known Source kind. */
-function provenanceBucketLabel(rawTag) {
-  const tag = String(rawTag || "").split(" | ")[0].trim();
-  if (!tag) return null;
-  const src = provenanceTagToSource(tag);
-  if (!src) return null;
-  if (src.kind === "corpus" || src.kind === "corpusWeak") {
-    return `${src.kind === "corpusWeak" ? "corpus-weak" : "corpus"}:${src.name || "unknown"}`;
-  }
-  if (src.kind === "extracted") return `extracted:${src.name || "unknown"}`;
-  if (src.kind === "entailed") return `entailed:${src.rule || "unknown"}`;
-  if (src.kind === "operator") return "ace:chat";
-  if (src.kind === "teach") return "teach:chat";
-  if (src.kind === "web") return "web";
-  return src.kind;
-}
-
-/** A single walked node's bucket value under one legend dimension. `"class"`
- *  reads every node; `"predicate"`/`"provenance"` only return non-null for a
- *  Fact-class node. */
-export function legendValueFor(graph, node, dimension) {
-  if (dimension === "class") return node?.class || "(none)";
-  if (!node || node.class !== MEMORY_FACT_CLASS) return null;
-  const attrs = graph?.byId?.get?.(node.id)?.attributes || [];
-  if (dimension === "predicate") return attrs.find((a) => a?.prop === "rdf:predicate")?.value || null;
-  if (dimension === "provenance") return provenanceBucketLabel(attrs.find((a) => a?.prop === "mgx:factProvenance")?.value);
-  return null;
-}
-
-/** Auto-pick the filter/legend dimension: since Fact dominates class-based
- *  legends once real memory-graph data is seeded, this scores class/predicate/
- *  provenance by normalized Shannon entropy over their bucket distribution
- *  and picks the best-scoring qualifying one (LEGEND_MIN_BUCKETS..MAX_BUCKETS).
- *  Falls back to "class" when nothing qualifies. Returns `{ primary,
- *  dimensions: { class, predicate, provenance } }`. */
-export function pickLegendDimension(graph, nodes) {
-  const classBuckets = bucketCounts((nodes || []).map((n) => legendValueFor(graph, n, "class")));
-  const predicateBuckets = bucketCounts((nodes || []).map((n) => legendValueFor(graph, n, "predicate")));
-  const provenanceBuckets = bucketCounts((nodes || []).map((n) => legendValueFor(graph, n, "provenance")));
-
-  const score = (rawBuckets) => {
-    const buckets = collapseToTopN(rawBuckets);
-    const qualifies = buckets.length >= LEGEND_MIN_BUCKETS && buckets.length <= LEGEND_MAX_BUCKETS;
-    return { score: normalizedEntropy(buckets), qualifies, buckets };
-  };
-
-  const dimensions = {
-    class: score(classBuckets),
-    predicate: score(predicateBuckets),
-    provenance: score(provenanceBuckets),
-  };
-
-  let primary = "class";
-  let bestScore = -1;
-  for (const [name, d] of Object.entries(dimensions)) {
-    if (!d.qualifies) continue;
-    if (d.score > bestScore) { bestScore = d.score; primary = name; }
-  }
-  return { primary, dimensions };
-}
-
 /** 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. */
@@ -1528,16 +1274,32 @@ export function renderArchitecture(graph, { pkg = "" } = {}) {
 }
 
 const COVERAGE_CAP = 40;
+const TESTS_GRAIN_NOTE = "tests edges are recorded module to module, so this is module-grain coverage.";
 
 /** The test modules covering a symbol/module — from the `tests` (mgx:testsCoverage)
- *  relation. Replaces grepping `tests/` for who imports the target. */
+ *  relation. Replaces grepping `tests/` for who imports the target.
+ *
+ *  `tests` edges run module to module, so a FUNCTION has no coverage of its
+ *  own to report and the answer is its defining module's. Asked about a
+ *  function, say both: which module the question hopped to, and that the
+ *  coverage is module-grain. Without that the answer names a module the user
+ *  never mentioned and silently passes off module coverage as the function's.
+ *  The grain note sits outside the indented list on purpose — indented, it
+ *  reads as one more test module. */
 export function renderTestsFor(graph, ind) {
   const modId = moduleIdOf(graph, ind);
   if (!modId) return `cannot map ${ind.label} to a module.`;
-  const modLabel = graph.byId.get(modId)?.label || modId;
+  // A symbol's module id is derived from its own recorded site, so it can name
+  // a module the index doesn't carry an individual for. The site's path is
+  // then the only honest spelling of it — never the raw id.
+  const modLabel = graph.byId.get(modId)?.label || siteOf(ind)?.path || modId;
   const tests = [...new Set(edgesOfKind(graph, "tests").filter((e) => e.object === modId).map((e) => e.subjectLabel || e.subject))];
-  if (!tests.length) return `${modLabel}: no covering tests recorded (no test module imports it).`;
-  return `${modLabel}: covered by ${tests.length} test module(s):\n  ${capJoin(tests, COVERAGE_CAP, "\n  ")}`;
+  const covered = tests.length > 0;
+  const verdict = covered
+    ? `covered by ${tests.length} test module(s):\n  ${capJoin(tests, COVERAGE_CAP, "\n  ")}`
+    : "no covering tests recorded (no test module imports it).";
+  if (modId === ind.id) return `${modLabel}: ${verdict}`;
+  return `${ind.label} is defined in ${modLabel}, which ${covered ? "is" : "has"} ${verdict}\n${TESTS_GRAIN_NOTE}`;
 }
 
 /** Source modules with no covering test module — a coverage gap view. Test
@@ -2217,52 +1979,6 @@ export function renderGraphOnlyBundle(plan, mask) {
   return out.join("\n");
 }
 
-// ---- cold-tool catalog (written to <repo>/.tmct/TOOLS.md by the index step) -----
-
-/** Markdown catalog of the COLD tools (everything except the hot catalog tools): each
- *  with a one-line purpose and the exact Bash invocation via the CLI `cli <tool>` route.
- *  Pure — `cliPath` is the absolute path to bin/cli.mjs the caller wants embedded. */
-export function renderToolsCatalog(cliPath) {
-  const cold = [
-    ["tmct_describe", "Locate one symbol and list its typed edges (both directions) with provenance.", { symbol: "django/utils/text.py" }],
-    ["tmct_signature", "One symbol's API surface (params, returns, raises/catches, flags, decorators, doc) without the body.", { symbol: "Truncator.chars" }],
-    ["tmct_impact", "Transitive reverse closure over imports/calls — what breaks if a module changes, by depth, with tests.", { module: "django/utils/text.py" }],
-    ["tmct_search", "Free-text/ranked lookup over the code-map to find the right module or symbol.", { query: "template filters", kind: "function" }],
-    ["tmct_members", "A class's methods + attributes (file:line, decorators) in one slice.", { class: "Truncator" }],
-    ["tmct_subclasses", "A class's base classes plus the transitive set of classes that extend it.", { class: "Field" }],
-    ["tmct_architecture", "Package/module map + the most-imported hub modules (optionally scoped to a package).", { package: "django/template" }],
-    ["tmct_exports", "A module's public __all__ surface, each name resolved to the module that defines it.", { module: "django/db/models/__init__.py" }],
-    ["tmct_tests_for", "The test modules covering a symbol or module, from the typed test edges.", { symbol: "django/utils/text.py" }],
-    ["tmct_untested", "Source modules with no covering test module — a coverage-gap view (no arguments).", {}],
-    ["tmct_history", "Recent commits that touched a symbol's module (newest first).", { symbol: "django/utils/text.py" }],
-    ["tmct_file_history", "Commits that touched a symbol's module, each with author / date / subject.", { symbol: "django/utils/text.py" }],
-    ["tmct_method_history", "Commits that touched a specific method symbol (fine-grained), with author / date / subject.", { symbol: "Truncator.chars" }],
-    ["tmct_class_history", "Commits that touched a specific class symbol (fine-grained), with author / date / subject.", { symbol: "Truncator" }],
-    ["tmct_callers", "Modules that call into a symbol's module (one hop).", { symbol: "django/utils/text.py" }],
-    ["tmct_callees", "Modules a symbol's module calls into (one hop).", { symbol: "django/utils/text.py" }],
-    ["tmct_calls", "The in-repo symbols a function calls (fn→fn), each with file:line.", { symbol: "slugify" }],
-    ["tmct_cochanges", "Modules that historically change in the same commit as a symbol's module (git co-change).", { symbol: "django/utils/text.py" }],
-    ["tmct_context_more", "The bundle sections a lean tmct_context omitted (siblings / tests / cochange / class members / re-exports).", { symbol: "django/utils/text.py" }],
-  ];
-  const lines = [
-    "# tmct cold-tool catalog",
-    "",
-    "The hot tools — `tmct_context` (start here to add/modify code; supports `depth: min|auto|full`) and `tmct_snippet` (exact source of one symbol) — carry full schemas in the TOOLS catalog.",
-    "",
-    "The cold tools below invoke via the CLI:",
-    "",
-  ];
-  for (const [name, purpose, args] of cold) {
-    lines.push(`## ${name}`);
-    lines.push(purpose);
-    lines.push("```bash");
-    lines.push(`node ${cliPath} cli ${name} '${JSON.stringify(args)}'`);
-    lines.push("```");
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
 // ---- change-coupling (git co-change) — "what usually changes together" ----------
 
 /** [{label, weight}] modules co-changed with modId, sorted by count desc. Pure. */

package/src/{completions → domain/completions}/complete.mjs

@@ -7,13 +7,12 @@ import { groupHits } from "./group.mjs";
 import { rankSentences } from "./rank.mjs";
 import { inferRelations } from "./infer.mjs";
 import { pruneCompletion } from "./prune.mjs";
-import { loadMemory } from "../memory/core.mjs";
-import { finish, grammarRules } from "../finish.mjs";
+import { requireInjected } from "./injected.mjs";
 
 /** grammarRules() with sentence-capitalisation force-enabled (disabled in live chat only to
  *  protect single-answer lowercase-opener goldens, which don't apply to a multi-sentence
  *  completion). */
-function completionGrammarRules() {
+function completionGrammarRules(grammarRules) {
   return grammarRules().map((r) => (r.id === "sentence-capitalisation" ? { ...r, enabled: true } : r));
 }
 
@@ -36,8 +35,11 @@ const DEFAULT_MAX_SENTENCES_PER_GROUP = 3; // see prune.mjs's own file header fo
  * @param {string} [opts.query]  the query rankSentences()/pruning focus on; defaults to `prompt`;
  *   pass `null` for self-weighted (LexRank-style) ranking instead
  * @param {number} [opts.maxSentencesPerGroup=3]  prune.mjs's top-K-per-group cutoff
- * @param {object} [opts.graph]  optional loaded graph (src/codegraph.mjs parseEntities() shape)
+ * @param {object} [opts.graph]  optional loaded graph (src/domain/codegraph.mjs parseEntities() shape)
  *   handed to finish()'s maskSegments to protect known entity labels during the grammar pass
+ * @param {object} opts.store  REQUIRED — the memory/block store handles this pipeline reads
+ *   through; `loadMemory` here, plus whatever each stage below requires of its own
+ * @param {object} opts.finisher  REQUIRED — the prose finisher's `{ finish, grammarRules }`
  * @returns {Promise<{
  *   text: string,
  *   sourceSpans: Array<{sourceBlockId:string, groupId:string, sentence:string}>,
@@ -51,22 +53,26 @@ export async function generateCompletion(dir, prompt, opts = {}) {
   const {
     blockK, graphService = null, graphLimit, overlapMin,
     memory: memoryOpt, query = prompt, maxSentencesPerGroup = DEFAULT_MAX_SENTENCES_PER_GROUP,
-    graph,
+    graph, store, finisher,
   } = opts;
+  const { loadMemory } = requireInjected(store, ["loadMemory"], { caller: "generateCompletion", option: "store" });
+  const { finish, grammarRules } = requireInjected(
+    finisher, ["finish", "grammarRules"], { caller: "generateCompletion", option: "finisher" },
+  );
 
   // Stage 1 — broad search
-  const hits = await broadSearch(dir, prompt, { blockK, graphService, graphLimit });
+  const hits = await broadSearch(dir, prompt, { blockK, graphService, graphLimit, store });
 
   // Stage 2 — grouping
-  const groups = groupHits(hits, { overlapMin });
+  const groups = groupHits(hits, { overlapMin, store });
 
   // Stage 3 — cross-group inference
   const memory = memoryOpt || await loadMemory(dir);
-  const relations = groups.length >= 2 ? await inferRelations(groups, memory) : [];
+  const relations = groups.length >= 2 ? await inferRelations(groups, memory, { store }) : [];
 
   // Stage 4 — extractive sentence ranking, per group (query-focused unless the caller opted out)
   const rankedByGroup = {};
-  for (const g of groups) rankedByGroup[g.id] = rankSentences(g, { query });
+  for (const g of groups) rankedByGroup[g.id] = rankSentences(g, { query, store });
 
   // Stage 5 — pruning: decide keep/drop, with an itemized, auditable drop log
   const { kept, dropped } = pruneCompletion(
@@ -84,7 +90,7 @@ export async function generateCompletion(dir, prompt, opts = {}) {
   const rawText = kept.map((k) => k.sentence).join(" ");
 
   // Stage 6 — grammar/voice pass (reuses finish() verbatim; see completionGrammarRules() above).
-  const finished = finish({ answer: rawText, via: "completion" }, { graph, rules: completionGrammarRules() });
+  const finished = finish({ answer: rawText, via: "completion" }, { graph, rules: completionGrammarRules(grammarRules) });
 
   // sourceSpans traces every output sentence back to its block id + group id, from `kept`
   // (pre-grammar-pass) — stays index-aligned since finish() only mutates casing/punctuation.

package/src/{completions → domain/completions}/graph-adapter.mjs

@@ -7,9 +7,9 @@
 // renderDescribe and readFactRows(memory), falling back to svc.ask() only when it genuinely
 // parsed the term.
 
-import { createGraphService } from "../providers/graph-service.mjs";
 import { resolveSymbol, renderDescribe } from "../codegraph.mjs";
-import { readFactRows } from "../memory/core.mjs";
+import { ask } from "../ask.mjs";
+import { requireInjected } from "./injected.mjs";
 
 /** renderDescribe() renders one line per fact with no terminal punctuation of its own;
  *  rank.mjs's splitSentences() treats each line as its own candidate sentence, and
@@ -27,10 +27,16 @@ function withTerminalPunctuation(text) {
 /**
  * @param {object|null} graph   a parseEntities() result, or null when no code graph is loaded
  * @param {object|null} [memory=null]  a loadMemory() payload, or null when there's no Fact store
+ * @param {object} [opts]
+ * @param {object} opts.store  REQUIRED — the `{ createGraphService, readFactRows }` handles
+ *   this adapter builds its two sentence sources from
  * @returns {{search: Function, ask: Function}} a Repository-Interface-shaped graphService
  */
-export function createCompletionsGraphAdapter(graph, memory = null) {
-  const svc = graph ? createGraphService(graph) : null;
+export function createCompletionsGraphAdapter(graph, memory = null, { store } = {}) {
+  const { createGraphService, readFactRows } = requireInjected(
+    store, ["createGraphService", "readFactRows"], { caller: "createCompletionsGraphAdapter", option: "store" },
+  );
+  const svc = graph ? createGraphService(graph, { ask }) : null;
 
   return {
     search(q, { limit } = {}) {

package/src/{completions → domain/completions}/group.mjs

@@ -3,8 +3,8 @@
 // memory/blocks.mjs's buildNeighbours()/OVERLAP_MIN). Block granularity, no sub-block spans.
 // Each group's label is its top shared-IDF tokens (df/N over the hit set, not the corpus).
 
-import { buildNeighbours, OVERLAP_MIN, tokenizeBlock } from "../memory/blocks.mjs";
 import { STOPWORDS } from "../prose.mjs";
+import { requireInjected } from "./injected.mjs";
 
 const LABEL_TOKEN_COUNT = 5;
 
@@ -14,8 +14,8 @@ const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
 
 /** tokenizeBlock(text), narrowed to real content tokens (see isContentToken above) — the
  *  token set this module actually clusters and labels on. */
-function contentTokens(text) {
-  return tokenizeBlock(text).filter(isContentToken);
+function makeContentTokens(tokenizeBlock) {
+  return (text) => tokenizeBlock(text).filter(isContentToken);
 }
 
 /** Plain union-find (path halving, union-by-index) — small N here (a single broad search's
@@ -41,13 +41,21 @@ function unionFind(n) {
  *
  * @param {Array<{id:string, text:string}>} hits
  * @param {object} [opts]
- * @param {number} [opts.overlapMin=OVERLAP_MIN]  shared-token threshold for a similarity edge
+ * @param {number} [opts.overlapMin]  shared-token threshold for a similarity edge; defaults to
+ *   the store's own OVERLAP_MIN
+ * @param {object} opts.store  REQUIRED — the block store's `{ buildNeighbours, tokenizeBlock,
+ *   OVERLAP_MIN }` clustering handles
  * @returns {Array<{ id: string, members: Array<{id:string, text:string}>, memberIds: string[],
  *   tokens: string[], label: string }>}
  *   One entry per connected component (a singleton hit is still a one-member group).
  *   Deterministic order: groups by lowest member id; members within a group by id.
  */
-export function groupHits(hits, { overlapMin = OVERLAP_MIN } = {}) {
+export function groupHits(hits, { overlapMin, store } = {}) {
+  const { buildNeighbours, tokenizeBlock, OVERLAP_MIN } = requireInjected(
+    store, ["buildNeighbours", "tokenizeBlock", "OVERLAP_MIN"], { caller: "groupHits", option: "store" },
+  );
+  const contentTokens = makeContentTokens(tokenizeBlock);
+  const edgeThreshold = overlapMin ?? OVERLAP_MIN;
   const list = Array.isArray(hits) ? hits.filter((h) => h && h.id != null) : [];
   if (!list.length) return [];
 
@@ -63,7 +71,7 @@ export function groupHits(hits, { overlapMin = OVERLAP_MIN } = {}) {
   const tokensById = {};
   for (const h of deduped) tokensById[h.id] = contentTokens(h.text || "");
 
-  const { ids, neighbours } = buildNeighbours(tokensById, overlapMin);
+  const { ids, neighbours } = buildNeighbours(tokensById, edgeThreshold);
   const { find, union } = unionFind(ids.length);
   for (let i = 0; i < ids.length; i += 1) {
     for (const j of neighbours[i]) union(i, j);