@polycode-projects/the-mechanical-code-talker 1.9.2 → 1.10.1

package/src/completions/complete.mjs

@@ -1,34 +1,6 @@
-// completions/complete.mjs — the full PLAN_COMPLETIONS.md pipeline, wired end to end:
-// broadSearch (Stage 1) -> groupHits (Stage 2) -> rankSentences per group + inferRelations
-// across groups (Stage 3+4) -> pruneCompletion's keep/drop (Stage 5) -> assemble the kept
-// sentences into prose -> finish()'s grammar/voice pass (Stage 6). §4's staging table, row 3:
-// "Stage 5+6 — pruning + grammar/voice pass wired end to end... Stage 6 reuses finish.mjs
-// directly... Exit criterion: A full end-to-end completion reads as one consistent voice and
-// every sentence traces to a source span."
-//
-// Extractive, by construction (PLAN_COMPLETIONS.md §3's honest ceiling): the assembled text is
-// the KEPT sentences, in order, joined by a single space — never paraphrased, never reordered
-// beyond what pruning's own group/rank order already decided, never smoothed over a genuine
-// disjointedness in the source material. Stage 6 fixes CAPITALISATION and PUNCTUATION at every
-// sentence boundary (this dispatch's own generalisation of src/finish.mjs's ruleCapitalise/
-// ruleTerminal); it does not invent, reorder, or merge any sentence's WORDS. Where the source
-// material simply doesn't chain into a fluent read, the output reads disjointedly and stays
-// honest about it — that is the plan's own accepted, documented limit, not a bug this module
-// tries to paper over.
-//
-// Traceability: `sourceSpans` is built directly from pruneCompletion()'s own `kept` list (which
-// already carries sourceBlockId + groupId per sentence) BEFORE the grammar pass runs, and the
-// grammar pass never reorders, drops, or merges sentences (only mutates casing/punctuation of
-// prose text) — so sourceSpans stays index-aligned with "one entry per output sentence" even
-// though the FINAL text is produced by finish(), not directly from `kept`. `relations` is
-// infer.mjs's own output, untouched by pruning (relations are never pruned, only the sentences
-// that anchor them are decided) — every relation still carries its own `licensingTest`/
-// `evidence` per infer.mjs's contract.
-//
-// Determinism: every stage this module chains is already deterministic (broadSearch, groupHits,
-// rankSentences, inferRelations, pruneCompletion, finish() are all pure/deterministic functions
-// over their inputs); this module adds no randomness of its own. See
-// test/completions-complete.test.mjs's own double-run diff.
+// completions/complete.mjs — the mechanical-text-generation pipeline: broadSearch ->
+// groupHits -> rankSentences + inferRelations -> pruneCompletion -> assemble -> finish()'s
+// grammar pass. Extractive only: output is the kept sentences, joined, never paraphrased.
 
 import { broadSearch } from "./search.mjs";
 import { groupHits } from "./group.mjs";
@@ -38,15 +10,9 @@ import { pruneCompletion } from "./prune.mjs";
 import { loadMemory } from "../memory/core.mjs";
 import { finish, grammarRules } from "../finish.mjs";
 
-/** grammarRules() with sentence-capitalisation FORCE-ENABLED, everything else exactly as the
- *  live table has it. sentence-capitalisation stays PARKED (enabled=false) in the live chat
- *  table (grammar-rules.toml's own cycle-006 note: it regresses case-sensitive single-answer
- *  goldens pinning lowercase openers) — that is a CHAT-voice decision, not a limitation of the
- *  rule itself. A genuinely multi-sentence extractive completion has no such single-opener
- *  voice to protect and NEEDS every internal sentence boundary capitalised to read as one
- *  consistent voice (this pipeline's own exit criterion) — so this module's own Stage 6 call
- *  overrides just that one rule's enabled flag, via finish()'s ctx.rules seam, without touching
- *  the cached global table or any other caller's behaviour. */
+/** 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() {
   return grammarRules().map((r) => (r.id === "sentence-capitalisation" ? { ...r, enabled: true } : r));
 }
@@ -65,16 +31,13 @@ const DEFAULT_MAX_SENTENCES_PER_GROUP = 3; // see prune.mjs's own file header fo
  *   passed straight through to broadSearch (see search.mjs)
  * @param {number} [opts.graphLimit]  broadSearch's graph search() limit
  * @param {number} [opts.overlapMin]  groupHits' shared-token edge threshold
- * @param {object} [opts.memory]  an already-loaded memory/core.mjs loadMemory() payload; when
- *   omitted, this module loads it itself via loadMemory(dir) (a fresh/empty memory is a
- *   perfectly valid, honest input — inferRelations() simply asserts nothing over it)
- * @param {string} [opts.query]  the query rankSentences()/pruning focus on; defaults to `prompt`
- *   itself (query-focused summarization, PLAN_COMPLETIONS.md §1.4's own literature framing) —
- *   pass `null` explicitly to fall back to self-weighted (LexRank-style) ranking instead
+ * @param {object} [opts.memory]  an already-loaded memory/core.mjs loadMemory() payload;
+ *   defaults to loadMemory(dir)
+ * @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)
- *   handed to finish()'s maskSegments so known entity labels inside the assembled text are
- *   protected during the grammar pass — the same ctx.graph existing finish() call sites pass
+ *   handed to finish()'s maskSegments to protect known entity labels during the grammar pass
  * @returns {Promise<{
  *   text: string,
  *   sourceSpans: Array<{sourceBlockId:string, groupId:string, sentence:string}>,
@@ -97,8 +60,7 @@ export async function generateCompletion(dir, prompt, opts = {}) {
   // Stage 2 — grouping
   const groups = groupHits(hits, { overlapMin });
 
-  // Stage 3 — cross-group inference (needs a loaded memory; a fresh/empty one is honest and
-  // simply asserts nothing, never fabricates something to compensate)
+  // Stage 3 — cross-group inference
   const memory = memoryOpt || await loadMemory(dir);
   const relations = groups.length >= 2 ? await inferRelations(groups, memory) : [];
 
@@ -113,25 +75,19 @@ export async function generateCompletion(dir, prompt, opts = {}) {
   );
 
   if (!kept.length) {
-    // Honest decline (PLAN_COMPLETIONS.md §3): nothing cleared the pruning bar for this prompt
-    // over this corpus — never fabricate a completion to fill the gap.
+    // Honest decline: nothing cleared the pruning bar for this prompt over this corpus — never
+    // fabricate a completion to fill the gap.
     return { text: "", sourceSpans: [], relations, dropped, declined: true, reason: "no source span cleared the pruning bar for this prompt" };
   }
 
-  // Assemble: kept sentences, in pruneCompletion's own (group-id, rank-order) order, joined by a
-  // single space — purely extractive, no reordering/paraphrasing beyond that (§3's honest
-  // ceiling; see file header).
+  // Assemble: kept sentences, in pruneCompletion's own order, joined by a single space.
   const rawText = kept.map((k) => k.sentence).join(" ");
 
-  // Stage 6 — grammar/voice pass. Reuses finish() verbatim (its maskSegments() masker still
-  // protects any known entity/path/number/receipt/provenance span WITHIN the assembled text,
-  // exactly as it does for a single-answer composed answer); only the rule table differs
-  // (sentence-capitalisation force-enabled — see completionGrammarRules() above).
+  // Stage 6 — grammar/voice pass (reuses finish() verbatim; see completionGrammarRules() above).
   const finished = finish({ answer: rawText, via: "completion" }, { graph, rules: completionGrammarRules() });
 
-  // sourceSpans traces every OUTPUT sentence back to its block id + group id — built from
-  // `kept` (pre-grammar-pass), which stays index-aligned with the final text because finish()'s
-  // grammar rules only mutate casing/punctuation of prose, never reorder/drop/merge sentences.
+  // 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.
   const sourceSpans = kept.map((k) => ({ sourceBlockId: k.sourceBlockId, groupId: k.groupId, sentence: k.sentence }));
 
   return { text: finished.answer, sourceSpans, relations, dropped };

package/src/completions/graph-adapter.mjs

@@ -1,61 +1,20 @@
-// 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.
+// completions/graph-adapter.mjs — a graphService-shaped adapter for broadSearch(), wrapping
+// two already-loaded stores (graph, memory) without re-loading either from disk.
 //
-// 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).
+// .ask(q) does not delegate to createGraphService(graph).ask(): that expects a natural-
+// language question, but broadSearch calls .ask() with a bare term, which would only produce
+// a "couldn't parse" rephrase-hint. Instead it builds sentences from resolveSymbol/
+// 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";
 
-/** 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. */
+/** 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
+ *  complete.mjs joins kept sentences with a single space, so two adjacent lines without
+ *  a period between them would otherwise read as one run-on clause. */
 function withTerminalPunctuation(text) {
   return String(text || "")
     .split("\n")
@@ -66,14 +25,9 @@ function withTerminalPunctuation(text) {
 }
 
 /**
- * @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.
+ * @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
+ * @returns {{search: Function, ask: Function}} a Repository-Interface-shaped graphService
  */
 export function createCompletionsGraphAdapter(graph, memory = null) {
   const svc = graph ? createGraphService(graph) : null;

package/src/completions/group.mjs

@@ -1,59 +1,15 @@
-// completions/group.mjs — Stage 2 ("grouping") of PLAN_COMPLETIONS.md's six-stage
-// mechanical-text-generation pipeline. Stage-0 scope ONLY per the plan's own §4 staging
-// table: cluster search.mjs's broadSearch() hits into topical groups; no cross-group
-// inference (Stage 3), summarization (Stage 4), pruning (Stage 5), or voice pass (Stage 6)
-// happens here.
-//
-// Genuinely greenfield, as the plan's own prior research established: PLAN_COMPLETIONS.md's
-// citation of "insights-panel tag clustering" as prior art turned out to be a different,
-// sibling project's capability, not tmct's — there was no clustering/tag-grouping code
-// anywhere in this repo before this file.
-//
-// Granularity: this module clusters at BLOCK granularity — the exact unit search.mjs's
-// broadSearch() hands it (one node per whole retrieveBlocks hit, or one node per whole
-// graph-search/ask result). PLAN_COMPLETIONS.md's own prose loosely says "spans"; that is
-// resolved explicitly here rather than silently assumed: no sub-block span segmentation is
-// attempted in this build. A finer-grained span-level increment, if the pipeline ever needs
-// it, is future work, out of scope for Stage 0.
-//
-// Algorithm: CONNECTED COMPONENTS over the block-similarity graph (shared-token-overlap
-// edges), reusing memory/blocks.mjs's buildNeighbours()/OVERLAP_MIN — the exact adjacency
-// rankBlocks()/degreeOf() already build for PageRank, exported from blocks.mjs for this
-// purpose rather than re-derived. This is the strategy-advisor's explicit Stage-0
-// recommendation: "the cheapest deterministic starting point" for grouping — genuinely
-// CoRank-adjacent (CoRank = "clustering cum graph ranking", PLAN_COMPLETIONS.md §1.2) since
-// it clusters over the same graph-ranking substrate blocks.mjs's PageRank runs on, and fully
-// deterministic/auditable, unlike any softer/fuzzier clustering. Richer ranking WITHIN a
-// cluster (e.g. running rankBlocks per component, or a true joint clustering+ranking pass)
-// is a future increment if the pipeline needs it later — not attempted here.
-//
-// Labeling: each group carries its member ids AND a human-inspectable label — its top
-// shared-IDF tokens. The only term-frequency machinery this repo ships is the
-// idf = log(1 + N/(1+df)) formula memory/blocks.mjs's retrieveBlocks() already computes
-// inline (there is no standalone exported idf() to import — it lives inline in
-// retrieveBlocks, scoped to a single query's tokens); that exact formula is replicated here,
-// scoped instead to df/N over the hit set passed into groupHits(), rather than inventing a
-// new weighting scheme.
-//
-// Determinism: no randomness anywhere. Same hits in (same ids, same text, same order) ->
-// same groups out (same partition, same member order, same label) — this is exactly what
-// test/completions-stage0.test.mjs's double-run diff asserts as Stage 0's exit criterion.
+// completions/group.mjs — Stage 2 ("grouping"): clusters search.mjs's broadSearch() hits
+// into topical groups via connected components over a shared-token-overlap graph (reusing
+// 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";
 
 const LABEL_TOKEN_COUNT = 5;
 
-// tokenizeBlock unions tokenizeProse(line) (stopword-filtered, punctuation-stripped) with
-// splitIdentifierWords(line) (NOT stopword-filtered — it's built for code identifiers, where
-// a stopword-shaped fragment is rare, and it doesn't strip trailing sentence punctuation
-// either). For prose-similarity clustering that union re-admits filler ("the", "and", "is",
-// "q:", "a:", "do?", …) as if it were real overlap signal — harmless for retrieveBlocks'
-// IDF-weighted single-query scoring (rare query tokens still dominate), but fatal for
-// unweighted shared-token-overlap clustering: almost any two English sentences share ≥2
-// stopwords, which would collapse everything into one giant component. isContentToken()
-// closes that gap for THIS module's own adjacency/labeling use, without changing
-// tokenizeBlock's shipped behavior (still exactly what retrieveBlocks/rankBlocks use).
+// tokenizeBlock's raw output re-admits stopwords, which would collapse almost any two
+// sentences into one giant component under unweighted overlap clustering; filter them here.
 const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
 
 /** tokenizeBlock(text), narrowed to real content tokens (see isContentToken above) — the
@@ -85,24 +41,17 @@ 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 — defaults to the exact value memory/blocks.mjs's own PageRank graph uses, so
- *   grouping and ranking agree on what "related" means unless the caller deliberately
- *   overrides it.
+ * @param {number} [opts.overlapMin=OVERLAP_MIN]  shared-token threshold for a similarity edge
  * @returns {Array<{ id: string, members: Array<{id:string, text:string}>, memberIds: string[],
  *   tokens: string[], label: string }>}
- *   One entry per connected component (a singleton hit that shares no edge with anything
- *   else is still a valid, if lonely, one-member group — never dropped). Deterministic
- *   order: groups sorted by their lowest member id; members within a group sorted by id.
- *   `id` is the group's own stable id (`"g:" + memberIds[0]`, deterministic from content).
+ *   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 } = {}) {
   const list = Array.isArray(hits) ? hits.filter((h) => h && h.id != null) : [];
   if (!list.length) return [];
 
-  // dedupe by id — a hit can legitimately appear from more than one source (e.g. a block
-  // and a graph-ask answer both id-tagged distinctly, but a caller re-running broadSearch
-  // for an overlapping prompt set could still hand duplicate ids); first occurrence wins.
+  // dedupe by id — first occurrence wins.
   const seen = new Set();
   const deduped = [];
   for (const h of list) {
@@ -128,9 +77,7 @@ export function groupHits(hits, { overlapMin = OVERLAP_MIN } = {}) {
     componentIdx.get(root).push(i);
   }
 
-  // IDF over THIS hit set (df/N here, not the whole corpus) — grouping is scoped to what
-  // Stage 1 actually retrieved for this prompt, same discipline retrieveBlocks applies to a
-  // single query's tokens.
+  // IDF over THIS hit set (df/N), not the whole corpus.
   const N = ids.length;
   const df = new Map();
   for (const id of ids) {
@@ -145,10 +92,7 @@ export function groupHits(hits, { overlapMin = OVERLAP_MIN } = {}) {
       .sort((a, b) => a.id.localeCompare(b.id));
     const memberIds = members.map((m) => m.id);
 
-    // label tokens: rank by (a) how many members share the token — full coverage first, so
-    // a group's label prefers what its members have IN COMMON over what one member merely
-    // contains a lot of — then (b) IDF (rarer across the hit set wins ties), then (c) token
-    // text for a fully deterministic order.
+    // label tokens: rank by member coverage, then IDF, then token text (deterministic).
     const coverage = new Map();
     for (const i of memberIdx) {
       for (const t of new Set(tokensById[ids[i]])) coverage.set(t, (coverage.get(t) || 0) + 1);

package/src/completions/infer.mjs

@@ -1,56 +1,19 @@
-// completions/infer.mjs — Stage 3 ("inference between groups") of PLAN_COMPLETIONS.md's
-// six-stage mechanical-text-generation pipeline. §4's staging table: "cross-group inference
-// wired to the existing entailment/rule-chase machinery, closed inference-relation
-// vocabulary... Reuses syllogise.mjs/resolveRelationChase, no new engine... Every asserted
-// inference cites a concrete licensing test, zero fabricated relationships on a hand-labeled
-// set" — this file, plus test/completions-infer.test.mjs's hand-labeled fixture, is that exit
-// criterion made concrete.
+// completions/infer.mjs — Stage 3 ("inference between groups"): applies resolveRelationChase
+// (src/memory/core.mjs) to relationships BETWEEN retrieved text groups, not just graph facts.
+// Four relations (supports/contradicts/elaborates/exemplifies), each with its own named
+// licensing test — see the four test*() functions below. A relation is asserted only when its
+// test concretely licenses it, never from prose similarity.
 //
-// "Apply tmct's existing entailment machinery... not just to graph facts, but to
-// relationships BETWEEN retrieved text groups... a closed, small inference-relation
-// vocabulary, deliberately mirroring marginalia's own TYPED_EDGES closed set... A relationship
-// between two groups is only asserted when a concrete, named test licenses it... never
-// inferred by prose similarity alone" (PLAN_COMPLETIONS.md §1.3). Four relations, each with
-// its own mechanical, named licensing test — see the four test*() functions below, one per
-// relation, each documented at its own definition:
-//
-//   supports    — resolveRelationChase (src/memory/core.mjs, PLAN_COMPLETIONS.md Stage 1's
-//                 own prerequisite extraction) confirms a taught relation fact between two
-//                 entities both groups' text share.
-//   contradicts — the two groups' text carry OPPOSITE negation polarity around the SAME
-//                 shared graph-known entity + shared content token (token-level, closed
-//                 negation-marker set — no graph fact required).
-//   elaborates  — one group's graph-known entity set is a PROPER SUBSET of the other's (the
-//                 wider group elaborates the narrower one).
-//   exemplifies — one group names a class-level term (something else is taught
-//                 rdfs:subClassOf/rdf:type it — checkable via the SAME memory/core.mjs-loaded
-//                 fact rows), and the other group names a taught INSTANCE of that class.
-//
-// "Entity" grounding: a group's raw content tokens (tokenizeBlock, the same tokenizer
-// group.mjs/rank.mjs use, filtered the same isContentToken way those two files already
-// establish) are narrowed to GRAPH-KNOWN terms only — tokens that normFactTerm-match some
-// fact's subject or object in the loaded memory. This is the concrete grounding that keeps
-// "group A and group B share an entity" a checkable graph fact, not a prose-similarity guess:
-// two groups merely using the same English word never licenses anything on its own unless
-// that word is itself a taught term.
-//
-// Determinism: no randomness anywhere. Groups are processed in a fixed (id-sorted) pairwise
-// order; every internal token/entity set is turned into a sorted array before use; every
-// per-relation test returns at most one hit per (group pair, relation), picked by that fixed
-// order — never "first of an unordered Set/Map iteration". See
-// test/completions-infer.test.mjs's own double-run diff test, the same discipline
-// test/completions-stage0.test.mjs and test/completions-stage2.test.mjs already apply to
-// search+group and to sentence ranking.
+// Entities are a group's content tokens narrowed to graph-known terms (normFactTerm-matched
+// against loaded facts) — sharing an English word alone never licenses a relation.
 
 import { normFactTerm, readFactRows, resolveRelationChase } from "../memory/core.mjs";
 import { tokenizeBlock } from "../memory/blocks.mjs";
 import { splitSentences } from "./rank.mjs";
 import { STOPWORDS } from "../prose.mjs";
 
-// Same content-token filter group.mjs/rank.mjs each apply to their own adjacency/ranking (not
-// exported from either, so replicated here rather than reached across files — see either
-// file's own header for why raw tokenizeBlock output, which re-admits stopword-shaped filler,
-// is unsuitable for unweighted set operations like the ones this file runs).
+// Same content-token filter group.mjs/rank.mjs apply to their own adjacency/ranking; not
+// exported from either, so replicated here rather than reached across files.
 const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
 
 /** tokenizeBlock(text), narrowed to real content tokens — see isContentToken above. */
@@ -58,25 +21,15 @@ function contentTokens(text) {
   return tokenizeBlock(text).filter(isContentToken);
 }
 
-// This file's own local copy of chat.mjs's private HAS_PROPERTY_PREDICATE constant (same
-// literal string, "mgx:hasProperty") — not exported from memory/core.mjs or chat.mjs, so
-// resolveRelationChase's own unit tests (test/memory-core.test.mjs) establish the precedent of
-// a caller supplying its own minimal, self-contained copy in its `helpers` bag rather than
-// reaching into chat.mjs (out of scope for this dispatch) for the shared constant.
+// Local copy of chat.mjs's private HAS_PROPERTY_PREDICATE constant — not exported, so callers
+// supply their own copy in the `helpers` bag resolveRelationChase expects.
 const HAS_PROPERTY_PREDICATE = "mgx:hasProperty";
 
-// The taught ISA-family predicates (chat.mjs's own MINT_ISA_PREDICATES/ISA_PREDICATES sets
-// this same pair, elsewhere) — the exemplifies test's "checkable via the taught IsA/subClassOf
-// graph" per PLAN_COMPLETIONS.md §1.3, read directly off readFactRows() rows rather than via
-// syllogise.mjs's fuller OWL 2 RL machinery (out of scope for this dispatch; this file only
-// needs the STORED isa edges, not their transitive closure).
+// The taught ISA-family predicates (stored edges only, not their transitive closure).
 const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
 
-// The contradicts test's closed negation-marker vocabulary (PLAN_COMPLETIONS.md §1.3's own
-// suggestion: "a simpler token-level polarity check... a small closed negation-word set").
-// Deliberately checked against the RAW sentence text, not contentTokens()'s output — prose.mjs's
-// STOPWORDS (which isContentToken filters through) already strips "not"/"no" as filler for
-// clustering/ranking purposes, which would silently erase the exact signal this test needs.
+// The contradicts test's closed negation-marker vocabulary, checked against RAW sentence
+// text (contentTokens() strips "not"/"no" as stopword filler, which would erase this signal).
 const NEGATION_MARKERS = new Set([
   "not", "no", "never", "cannot", "none", "nobody", "nothing", "neither", "nor", "without",
 ]);
@@ -127,30 +80,21 @@ function buildGraphTerms(rows) {
   return set;
 }
 
-/** A group's GRAPH-GROUNDED entities: its own content-token vocabulary, narrowed to tokens
- *  that are themselves graph-known terms (buildGraphTerms' universe) — sorted for determinism.
- *  This is the concrete grounding test/completions-infer.test.mjs's fixture exercises: two
- *  groups merely sharing an English word (e.g. both saying "abstraction") never counts unless
- *  that word is itself a taught fact term. */
+/** A group's GRAPH-GROUNDED entities: content tokens narrowed to graph-known terms, sorted. */
 function entitiesOf(group, graphTerms) {
   return [...groupContentTokenSet(group)].filter((t) => graphTerms.has(t)).sort();
 }
 
-/** A minimal, self-contained relationFactsFor(name) — direct-predicate match only
- *  (`mgx:${name}`), no alias/subClassOf-over-relation-names chase. Mirrors
- *  test/memory-core.test.mjs's own testRelationFactsFor precedent exactly: resolveRelationChase
- *  never calls the alias substrate itself, that lives entirely inside whatever relationFactsFor
- *  the caller supplies, and a direct-only implementation is an honest, valid, simpler one — no
- *  alias-chase claim is made or needed for the supports test's own licensing standard. */
+/** A minimal relationFactsFor(name): direct-predicate match only (`mgx:${name}`), no
+ *  alias/subClassOf chase — sufficient for this test's licensing standard. */
 function makeRelationFactsFor(rows) {
   return (name) => rows
     .filter((f) => f.predicate === `mgx:${name}`)
     .map((f) => ({ fact: f, aliasFacts: [] }));
 }
 
-/** The resolveRelationChase/resolveRelationChaseReverse `helpers` bag this file supplies —
- *  same shape test/memory-core.test.mjs's own direct unit tests use, built once per
- *  inferRelations() call over the loaded memory's fact rows. */
+/** The resolveRelationChase/resolveRelationChaseReverse `helpers` bag this file supplies,
+ *  built once per inferRelations() call over the loaded memory's fact rows. */
 function makeHelpers(rows) {
   return {
     relationFactsFor: makeRelationFactsFor(rows),
@@ -163,10 +107,8 @@ function makeHelpers(rows) {
   };
 }
 
-/** Every distinct relation NAME resolveRelationChase can plausibly be asked about: every
- *  `mgx:<name>` predicate actually present among the loaded facts, minus HAS_PROPERTY_PREDICATE
- *  (a property-literal marker, not a relation name) — a closed, corpus-derived candidate list,
- *  never an open-ended guess at what "a relation" might be named. Sorted for determinism. */
+/** Every distinct relation NAME present among the loaded facts (`mgx:<name>` predicates,
+ *  minus HAS_PROPERTY_PREDICATE, a property marker not a relation name). Sorted. */
 function relationNameCandidates(rows) {
   const names = new Set();
   for (const r of rows) {
@@ -177,15 +119,9 @@ function relationNameCandidates(rows) {
   return [...names].sort();
 }
 
-/**
- * SUPPORTS — group A and group B share at least two graph-grounded entities, AND a taught
- * relation fact (resolveRelationChase, src/memory/core.mjs — this file's direct tie-in to
- * PLAN_COMPLETIONS.md Stage 1's own prerequisite extraction) confirms a claim connecting two of
- * those shared entities. Tries every (subject, object) ordered pair drawn from the shared
- * entity set, against every candidate relation name, in fixed sorted order; the first hit
- * (deterministic given fixed inputs) is the one asserted. Returns
- * `{ licensingTest, evidence }` or null.
- */
+/** SUPPORTS — groups A/B share >=2 graph-grounded entities AND a taught relation fact
+ *  connects two of them. Tries every (subject, object) pair against every candidate relation
+ *  name in fixed sorted order; first hit wins. Returns `{ licensingTest, evidence }` or null. */
 async function testSupports(a, b, memory, helpers, relationNames, graphTerms) {
   const entitiesA = entitiesOf(a, graphTerms);
   const entitiesB = entitiesOf(b, graphTerms);
@@ -209,14 +145,9 @@ async function testSupports(a, b, memory, helpers, relationNames, graphTerms) {
   return null;
 }
 
-/**
- * CONTRADICTS — group A and group B both mention the SAME graph-grounded entity, plus a
- * second shared content token ("predicate"/aspect) that co-occurs with the entity in at least
- * one sentence on each side — and one side's co-occurring sentence carries a closed-set
- * negation marker while the other side's does not (opposite polarity about the same claim,
- * PLAN_COMPLETIONS.md §1.3's own "simpler token-level polarity check"). Returns
- * `{ licensingTest, evidence }` or null.
- */
+/** CONTRADICTS — groups A/B share a graph-grounded entity plus a second co-occurring token
+ *  ("aspect"), and one side's matching sentence is negated while the other's isn't. Returns
+ *  `{ licensingTest, evidence }` or null. */
 function testContradicts(a, b, graphTerms) {
   const entitiesA = entitiesOf(a, graphTerms);
   const entitiesB = entitiesOf(b, graphTerms);
@@ -271,14 +202,9 @@ function isProperSubset(small, big) {
   return small.size > 0 && small.size < big.size && [...small].every((t) => big.has(t));
 }
 
-/**
- * ELABORATES — one group's graph-grounded entity set is a PROPER SUBSET of the other's: the
- * WIDER group (the superset) elaborates the NARROWER one (the subset) — it covers everything
- * the narrower group's entities do, plus more. Equal entity sets never count (neither is a
- * *proper* subset of the other) — two groups about exactly the same entities are not in an
- * elaboration relationship by this test. Returns `{ wider: "a"|"b", licensingTest, evidence }`
- * or null.
- */
+/** ELABORATES — one group's graph-grounded entity set is a PROPER SUBSET of the other's; the
+ *  wider group elaborates the narrower one. Equal sets never count. Returns
+ *  `{ wider: "a"|"b", licensingTest, evidence }` or null. */
 function testElaborates(a, b, graphTerms) {
   const entitiesA = new Set(entitiesOf(a, graphTerms));
   const entitiesB = new Set(entitiesOf(b, graphTerms));
@@ -300,15 +226,10 @@ function testElaborates(a, b, graphTerms) {
   return null;
 }
 
-/**
- * EXEMPLIFIES — `general` names a class-level term (some taught fact has it as the OBJECT of
- * an ISA_PREDICATES edge — i.e. something else is taught to BE one of it), and `instance`
- * names a graph-grounded entity taught to BE one, directly (ISA_PREDICATES edge: instance ->
- * general). Asymmetric and directional by construction: `instance`'s group exemplifies
- * `general`'s group, never the reverse in the same call — callers probe both directions by
- * calling this twice with the groups swapped (see inferRelations below). Returns
- * `{ licensingTest, evidence }` or null.
- */
+/** EXEMPLIFIES — `general` names a class-level term (object of an ISA_PREDICATES edge), and
+ *  `instance` names an entity taught to BE one directly. Asymmetric: callers probe both
+ *  directions by calling this twice with groups swapped (see inferRelations below). Returns
+ *  `{ licensingTest, evidence }` or null. */
 function testExemplifies(general, instance, rows, graphTerms) {
   const generalEntities = entitiesOf(general, graphTerms);
   const instanceEntities = entitiesOf(instance, graphTerms);
@@ -332,22 +253,14 @@ function testExemplifies(general, instance, rows, graphTerms) {
 }
 
 /**
- * Stage 3 — cross-group inference. For every unordered pair of groups (group.mjs's groupHits()
- * output, or any `{ id, members: [{id, text}] }` array), tests each of the four closed
- * relations (supports/contradicts/elaborates/exemplifies) via its own concrete, named,
- * mechanical licensing test — never prose similarity. A relation only appears in the output
- * when its own test function returns a hit; every hit carries `licensingTest` (a human-
- * readable description of exactly what fired) and `evidence` (the concrete facts/tokens cited)
- * — PLAN_COMPLETIONS.md §2's auditability bar ("every cross-group claim must cite the
- * two-or-more groups and the inference kind that licensed it").
+ * Stage 3 — cross-group inference. For every unordered pair of groups, tests each of the four
+ * closed relations and includes a hit only when its test function fires.
  *
  * @param {Array<{id:string, members:Array<{id:string,text:string}>}>} groups
  * @param {object} memory  an already-loaded memory/core.mjs loadMemory() payload
  * @param {object} [opts]  reserved for future tuning; unused today
  * @returns {Promise<Array<{from:string, to:string, relation:"supports"|"contradicts"|"elaborates"|"exemplifies", licensingTest:string, evidence:object}>>}
- *   deterministic: groups are processed in id-sorted pairwise order, and the final list is
- *   additionally stable-sorted by (from, to, relation) so output order never depends on
- *   incidental iteration order anywhere upstream.
+ *   deterministic: id-sorted pairwise order, stable-sorted by (from, to, relation).
  */
 // eslint-disable-next-line no-unused-vars -- opts reserved, see docblock
 export async function inferRelations(groups, memory, opts = {}) {
@@ -381,8 +294,7 @@ export async function inferRelations(groups, memory, opts = {}) {
         out.push({ from, to, relation: "elaborates", licensingTest: ela.licensingTest, evidence: ela.evidence });
       }
 
-      // Both directions probed independently — "A exemplifies B" and "B exemplifies A" are
-      // genuinely different claims, each licensed (or not) by its own class/instance test.
+      // Both directions probed independently — different claims, each its own test.
       const bExemplifiesA = testExemplifies(A, B, rows, graphTerms);
       if (bExemplifiesA) out.push({ from: B.id, to: A.id, relation: "exemplifies", licensingTest: bExemplifiesA.licensingTest, evidence: bExemplifiesA.evidence });
       const aExemplifiesB = testExemplifies(B, A, rows, graphTerms);