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

package/src/completions/prune.mjs

@@ -1,57 +1,14 @@
-// completions/prune.mjs — Stage 5 ("drop non-contributing elements") of PLAN_COMPLETIONS.md's
-// six-stage mechanical-text-generation pipeline. §4's staging table (row 3, "Stage 5+6"): "any
-// retrieved span that ends up in no surviving group, feeds no asserted inference, and is not
-// selected by Stage 4's ranking gets cut, explicitly, with the drop recorded (not silently
-// discarded) so the pipeline's own working set is auditable end to end" (§1.5).
-//
-// Reading the plan's own sentence precisely: the three conditions are joined by AND, so a span
-// is dropped only when ALL three hold — equivalently, a span is KEPT when ANY of the three is
-// false: it IS in a surviving group, OR it DOES feed an asserted inference, OR it IS selected by
-// ranking. This module implements that OR exactly, at SENTENCE granularity (rank.mjs's own
-// ranking unit — the thing that actually composes into the assembled prose), with a "hit never
-// grouped" defensive check underneath it for the coarser block/hit granularity search.mjs hands
-// group.mjs (group.mjs's own contract is that every hit lands in SOME group, so this branch is
-// a guard against that invariant breaking silently, not an expected live path today).
-//
-// Inputs are the pipeline's own already-computed intermediate state — this module computes
-// NOTHING new about relevance; it only DECIDES keep/drop from what search.mjs/group.mjs/
-// infer.mjs/rank.mjs already produced, and records why. `rankedByGroup` is deliberately an
-// INPUT (rank.mjs's own rankSentences() output per group), not recomputed here — pruning is a
-// pure decision layer over ranking's output, not a second ranker.
-//
-// THRESHOLD + REASONING (the plan's own "your call on a sensible cutoff, document your
-// reasoning"):
-//   - top-K per group (default 3, `opts.maxSentencesPerGroup`): rankSentences() is already
-//     best-first per group; keeping only the top K bounds the assembled completion's size in a
-//     VISIBLE, documented, override-able way. An unbounded "keep everything with any positive
-//     score" would make the completion grow without limit as a group's member count grows —
-//     that is itself a silent, unaudited cap in the opposite direction (nothing stops it from
-//     ballooning to the size of the whole retrieved corpus for a broad-enough prompt); a small
-//     explicit K is the "no silent caps" discipline applied honestly — the cap is visible in the
-//     signature, in this comment, and in every drop log entry it produces.
-//   - positive score (`score > 0`): rankSentences()'s own scoring is 0 exactly when a sentence
-//     shares no informative (or, under query-focus, no query-overlapping) token with anything —
-//     rank.mjs's own "never a guessed match" discipline. A zero-information sentence contributes
-//     nothing to the completion's content by rankSentences()'s own definition, so it never
-//     qualifies on ranking grounds alone, however small K is set.
-//   - relation-anchor salvage: a group that feeds an asserted cross-group inference (infer.mjs)
-//     but produces ZERO ranking-qualified sentences (every one of its sentences is either
-//     outside top-K or zero-scored) is not silenced outright — its single top-ranked sentence is
-//     kept as the group's extractive anchor, so a cross-group claim this pipeline actually
-//     ASSERTS (with cited licensing evidence) always has at least one real, traceable sentence
-//     behind it in the assembled text. This is the concrete realisation of the plan's OR: the
-//     three drop conditions must ALL hold, and "feeds no asserted inference" is one of them.
-//
-// Determinism: no randomness anywhere. Groups are processed in a fixed (id-sorted) order;
-// rankedByGroup's own sentence order (rank.mjs's own deterministic tiebreak) is preserved
-// exactly; the output kept/dropped lists are therefore fully deterministic given deterministic
-// inputs — see test/completions-prune.test.mjs's own double-run diff.
+// completions/prune.mjs — Stage 5 ("drop non-contributing elements"), at SENTENCE
+// granularity: a sentence is kept if it's in a surviving group AND (feeds an asserted
+// inference OR clears the per-group top-K/positive-score ranking cutoff); otherwise it's
+// dropped with a recorded reason. A group that feeds an inference but has no ranking-
+// qualified sentence still keeps its top-ranked sentence as an extractive anchor, so every
+// asserted relation traces to a real sentence. Pure decision layer — computes nothing new
+// about relevance, only reads what search/group/infer/rank already produced.
 
 const DEFAULT_MAX_SENTENCES_PER_GROUP = 3;
 
-/** Every group id referenced as either side of an asserted relation (infer.mjs's inferRelations()
- *  output) — the "feeds an asserted inference" test, at group granularity (the granularity
- *  relations are actually asserted at). */
+/** Every group id referenced as either side of an asserted relation. */
 function relatedGroupIdsOf(relations) {
   const set = new Set();
   for (const r of relations) {
@@ -62,30 +19,22 @@ function relatedGroupIdsOf(relations) {
 }
 
 /**
- * Stage 5 — pruning. Decides, per sentence, KEEP or DROP, from the pipeline's own already-
- * computed intermediate state — never recomputing relevance itself.
+ * Stage 5 — pruning. Decides, per sentence, KEEP or DROP.
  *
  * @param {object} state
- * @param {Array<{id:string, text?:string}>} [state.hits] search.mjs's broadSearch() output (used
- *   only for the defensive "never grouped" check below — group.mjs's own contract is that this
- *   branch should never actually fire today).
+ * @param {Array<{id:string, text?:string}>} [state.hits] search.mjs's broadSearch() output
  * @param {Array<{id:string, memberIds:string[], label?:string}>} [state.groups] group.mjs's
- *   groupHits() output.
+ *   groupHits() output
  * @param {Array<{from:string, to:string, relation:string}>} [state.relations] infer.mjs's
- *   inferRelations() output.
+ *   inferRelations() output
  * @param {Object<string, Array<{sentence:string, score:number, sourceBlockId:string}>>}
- *   [state.rankedByGroup] rank.mjs's rankSentences() output, ONE ENTRY PER GROUP, keyed by
- *   group id — an INPUT to this module, not recomputed here (see file header).
+ *   [state.rankedByGroup] rank.mjs's rankSentences() output, keyed by group id
  * @param {object} [opts]
- * @param {number} [opts.maxSentencesPerGroup=3] the top-K-per-group ranking cutoff (see file
- *   header for the reasoning behind the default).
+ * @param {number} [opts.maxSentencesPerGroup=3] the top-K-per-group ranking cutoff
  * @returns {{
  *   kept: Array<{sentence:string, score:number, sourceBlockId:string, groupId:string, groupLabel:string}>,
  *   dropped: Array<{item:object, reason:string}>
- * }} `kept` is sentence-granular, ordered by (group id, rank order within the group) — a stable,
- *   deterministic order the caller can assemble directly. `dropped` is itemized, one entry per
- *   dropped hit/sentence, each carrying a human-readable `reason` (never a silent discard —
- *   PLAN_COMPLETIONS.md §1.5/§2's own auditability bar).
+ * }} `kept` is ordered by (group id, rank order); `dropped` carries a human-readable `reason`.
  */
 export function pruneCompletion(state = {}, { maxSentencesPerGroup = DEFAULT_MAX_SENTENCES_PER_GROUP } = {}) {
   const hits = Array.isArray(state.hits) ? state.hits : [];
@@ -96,8 +45,7 @@ export function pruneCompletion(state = {}, { maxSentencesPerGroup = DEFAULT_MAX
   const kept = [];
   const dropped = [];
 
-  // "never grouped" — defensive: every hit should land in SOME group (group.mjs never drops a
-  // hit), so this guards the invariant explicitly rather than silently assuming it holds.
+  // "never grouped" — defensive: group.mjs's contract is every hit lands in some group.
   const groupedHitIds = new Set();
   for (const g of groups) for (const id of g.memberIds || []) groupedHitIds.add(id);
   for (const h of hits) {
@@ -124,8 +72,7 @@ export function pruneCompletion(state = {}, { maxSentencesPerGroup = DEFAULT_MAX
 
     let anchor = null;
     if (!qualifying.length && groupFeedsInference && ranked.length) {
-      // salvage: the group's own single top-ranked sentence, kept as the extractive anchor for
-      // its asserted cross-group relation even though it didn't clear the ranking cutoff alone.
+      // salvage: keep the group's top-ranked sentence as the extractive anchor.
       anchor = ranked[0];
       qualifying.push(anchor);
       const idx = rest.indexOf(anchor);

package/src/completions/rank.mjs

@@ -1,40 +1,13 @@
-// completions/rank.mjs — Stage 4 ("mechanical summarization") of PLAN_COMPLETIONS.md's
-// six-stage mechanical-text-generation pipeline. Stage-2-of-staging scope per the plan's own
-// §4 table: extractive SENTENCE ranking within a group.mjs group — no cross-group inference
-// (Stage 3, §1.3 — separately scoped), pruning (Stage 5), or voice pass (Stage 6) happens
-// here.
-//
-// "Extractive sentence selection over the grouped-and-inferred material, not abstractive
-// rewriting... query-focused multi-document summarization (feature-fusion sentence
-// selection, graph-ranking approaches in the LexRank/TextRank family, clustering-cum-ranking
-// as in CoRank)" — PLAN_COMPLETIONS.md §1.4/§4. The graph-ranking machinery this stage needs
-// already exists and ships: memory/blocks.mjs's rankBlocks() (PageRank, d=0.85, 20
-// iterations, over the shared-token block-similarity graph) and degreeOf() (hub dampening),
-// both generic over any `{ id: tokens[] }` map — NOT block-specific despite the module name.
-// This file reuses rankBlocks()/degreeOf() VERBATIM at sentence granularity (no PageRank
-// reimplementation), combined with the same idf = log(1 + N/(1+df)) formula group.mjs already
-// replicates for group-scoped (not whole-corpus-scoped) weighting, and the same
-// idfSum * (1+rank) / sqrt(1+degree) combination retrieveBlocks() uses to fuse relevance,
-// centrality, and hub-dampening into one score.
-//
-// New in this file: splitSentences() (no sentence-splitter existed anywhere in this repo —
-// grepped for "sentence" across src/ and found none; a simple regex splitter is intentional
-// here per the dispatch's own instruction not to pull in an NLP dependency for this) and the
-// sentence-level id/token/scoring wiring that adapts rankBlocks/degreeOf from block to
-// sentence granularity.
-//
-// Determinism: no randomness anywhere. Same group in (same members, same text, same order)
-// -> same ranked sentence list out (stable score-descending sort with a deterministic
-// sourceBlockId/sentence-text tiebreak) — see test/completions-stage2.test.mjs's double-run
-// diff, the exact discipline test/completions-stage0.test.mjs established for search+group.
+// completions/rank.mjs — Stage 4 ("mechanical summarization"): extractive SENTENCE ranking
+// within a group.mjs group. Reuses memory/blocks.mjs's rankBlocks() (PageRank) and degreeOf()
+// (hub dampening) verbatim at sentence granularity, combined with group-scoped IDF the same
+// way retrieveBlocks() fuses relevance/centrality/hub-dampening into one score.
+// splitSentences() is a simple regex splitter — deliberately not an NLP dependency.
 
 import { degreeOf, rankBlocks, tokenizeBlock, OVERLAP_MIN } from "../memory/blocks.mjs";
 import { STOPWORDS } from "../prose.mjs";
 
-// Same content-token filter group.mjs applies to its own adjacency/labeling (not exported
-// from group.mjs, so replicated here rather than reached across files — group.mjs's own
-// header explains why raw tokenizeBlock output is unsuitable for unweighted overlap: it
-// re-admits stopwords/filler that would collapse unrelated sentences into false edges).
+// Same content-token filter group.mjs applies (not exported, so replicated here).
 const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
 
 /** tokenizeBlock(text), narrowed to real content tokens — see isContentToken above. */
@@ -43,16 +16,11 @@ function contentTokens(text) {
 }
 
 // Sentence boundary: a run of [.!?] followed by whitespace and an uppercase letter or digit —
-// deliberately simple (no abbreviation dictionary, no NLP dependency, per the dispatch's own
-// instruction). Applied per-line (a block's own "Q: ...\nA: ..." shape already gives clean
-// boundaries at the newline; this regex further splits any line that itself holds more than
-// one sentence).
+// deliberately simple (no abbreviation dictionary, no NLP dependency).
 const SENTENCE_SPLIT_RE = /(?<=[.!?])\s+(?=[A-Z0-9])/;
 
 /**
- * Split raw block text into trimmed, non-empty sentences (order-preserving, no dedup —
- * dedup, if ever needed, is the caller's call). Splits on blank lines first (a block's own
- * natural line structure), then on sentence-ending punctuation within each line.
+ * Split raw block text into trimmed, non-empty sentences (order-preserving, no dedup).
  *
  * @param {string} text
  * @returns {string[]}
@@ -71,26 +39,16 @@ export function splitSentences(text) {
 }
 
 /**
- * Stage 4 — extractive sentence ranking within one group.mjs group. Splits every member's
- * text into sentences, builds a sentence-level shared-token-overlap similarity graph (the
- * exact adjacency buildNeighbours/rankBlocks/degreeOf already establish, just re-keyed to
- * sentence ids instead of block ids), runs the same PageRank (rankBlocks) and hub-dampening
- * (degreeOf) over it, and combines with group-scoped IDF the same way retrieveBlocks() fuses
- * relevance × centrality × hub-dampening — self-weighted (LexRank-style: a sentence's own
- * rare/informative tokens) unless `opts.query` is supplied, in which case only tokens
- * overlapping the query are IDF-summed (query-focused summarization, PLAN_COMPLETIONS.md's
- * own literature framing) — a sentence with zero query overlap honestly scores 0 rather than
- * silently falling back to self-weighting, the same "never a guessed match" discipline
- * retrieveBlocks() applies when idfSum <= 0.
+ * Stage 4 — extractive sentence ranking within one group.mjs group: splits every member's
+ * text into sentences, ranks them by PageRank + hub-dampening + IDF (self-weighted, or
+ * query-focused when `opts.query` is given — a sentence with zero query overlap scores 0
+ * rather than falling back to self-weighting).
  *
  * @param {{members: Array<{id:string, text:string}>}} group  a group.mjs groupHits() entry
- *   (or any object shaped `{ members: [{id, text}, ...] }`)
  * @param {object} [opts]
  * @param {number} [opts.overlapMin=OVERLAP_MIN]  shared content-token threshold for a
- *   sentence-similarity edge — defaults to the same value group.mjs/blocks.mjs use, so
- *   grouping, block-ranking, and sentence-ranking all agree on what "related" means unless
- *   the caller deliberately overrides it.
- * @param {string|null} [opts.query=null]  optional query text to focus ranking on (see above)
+ *   sentence-similarity edge
+ * @param {string|null} [opts.query=null]  optional query text to focus ranking on
  * @returns {Array<{sentence:string, score:number, sourceBlockId:string}>} best-first;
  *   deterministic tiebreak (sourceBlockId, then sentence text) on equal score.
  */
@@ -98,10 +56,7 @@ export function rankSentences(group, { overlapMin = OVERLAP_MIN, query = null }
   const members = Array.isArray(group?.members) ? group.members : [];
   if (!members.length) return [];
 
-  // One entry per sentence: a stable id ("<blockId>#<index>") so PageRank/degree/IDF can be
-  // keyed exactly like rankBlocks/degreeOf already key blocks — deterministic since it's
-  // derived purely from member order (group.mjs's members are already id-sorted) and each
-  // block's own sentence order.
+  // One entry per sentence, with a stable id for PageRank/degree/IDF keying.
   const sentences = [];
   for (const m of members) {
     const parts = splitSentences(m?.text || "");
@@ -114,13 +69,10 @@ export function rankSentences(group, { overlapMin = OVERLAP_MIN, query = null }
   const tokensById = {};
   for (const s of sentences) tokensById[s.id] = contentTokens(s.sentence);
 
-  // Reused verbatim — the exact PageRank/hub-dampening machinery rankBlocks()/degreeOf()
-  // already run for block-level ranking, generic over any id->tokens map.
   const ranks = rankBlocks(tokensById, { overlapMin });
   const degrees = degreeOf(tokensById, { overlapMin });
 
-  // IDF scoped to THIS group's sentence set (df/N here, not the whole corpus) — the same
-  // scoping discipline group.mjs applies to its own label tokens.
+  // IDF scoped to THIS group's sentence set (df/N), not the whole corpus.
   const ids = Object.keys(tokensById);
   const N = ids.length;
   const df = new Map();
@@ -138,11 +90,6 @@ export function rankSentences(group, { overlapMin = OVERLAP_MIN, query = null }
     for (const t of idfTokens) idfSum += idf(t);
     const rank = ranks[s.id] ?? 0;
     const degree = degrees[s.id] ?? 0;
-    // idfSum * (1 + rank) / sqrt(1 + degree) — retrieveBlocks()'s own combination formula
-    // (memory/blocks.mjs), reused at sentence granularity: IDF-weighted informativeness
-    // decides content, PageRank centrality breaks ties toward well-connected (consensus)
-    // sentences, and the degree divisor dampens a sentence that merely shares vocabulary
-    // with disproportionately many others from winning on inflated rank alone.
     const score = (idfSum * (1 + rank)) / Math.sqrt(1 + degree);
     return { sentence: s.sentence, score, sourceBlockId: s.sourceBlockId };
   });

package/src/completions/search.mjs

@@ -1,25 +1,6 @@
-// completions/search.mjs — Stage 1 ("broad search") of PLAN_COMPLETIONS.md's six-stage
-// mechanical-text-generation pipeline. This is Stage-0 scope ONLY per the plan's own §4
-// staging table (Stage 1 + Stage 2, no inference/summarization/pruning/voice-pass yet — see
-// group.mjs for Stage 2).
-//
-// Near-total reuse, as the plan's own prior research established: this is a thin composition
-// of retrieveBlocks (src/memory/blocks.mjs's best-first block ranker) and the graph
-// search()/ask() services (src/providers/graph-service.mjs, contracted by
-// src/repository-interface.mjs's SERVICE_GROUPS.search) — a WIDER query shape ("broad
-// search": more hits per source, both sources asked) rather than any new retrieval
-// machinery. Nothing here re-implements ranking, tokenizing, or graph traversal.
-//
-// Granularity note (explicit, per the strategy-advisor's Stage-0 correction): retrieveBlocks
-// only ever returns whole BLOCK text — one node per ~800-token document/transcript chunk, the
-// unit memory/blocks.mjs's index actually stores. PLAN_COMPLETIONS.md's own prose loosely
-// says "spans"; this module does NOT invent sub-block span segmentation. Every hit this
-// module returns is whole-block (or a whole graph-search/ask result) granularity. Finer-grain
-// spans, if the pipeline ever needs them, are a real future increment, out of scope here.
-//
-// Determinism: retrieveBlocks is already deterministic (stable sort with an id tiebreak);
-// the graph service's search()/ask() are pure functions over a fixed graph. Given the same
-// dir/query/graphService, broadSearch() always returns the same array in the same order.
+// completions/search.mjs — Stage 1 ("broad search"): a thin composition of retrieveBlocks
+// and the graph search()/ask() services, asking both sources more widely than a single-answer
+// query. Returns whole-block/whole-result hits only — no sub-block span segmentation.
 
 import { retrieveBlocks } from "../memory/blocks.mjs";
 
@@ -36,17 +17,13 @@ const DEFAULT_GRAPH_LIMIT = 8;
  * @param {object} [opts]
  * @param {number} [opts.blockK=8]  retrieveBlocks' k (how many blocks to pull)
  * @param {object|null} [opts.graphService=null]  an optional Repository-Interface service
- *   (e.g. createGraphService(graph) from src/providers/graph-service.mjs, or any provider
- *   satisfying SERVICE_GROUPS.search's `search`/`ask`). When supplied, its search() and
- *   ask() services are queried too. Omitted -> block-only search (still a valid, honest
- *   broad search; graph access is opt-in, not required — this module never constructs a
- *   graph service itself, it only calls one it's handed).
+ *   (e.g. createGraphService(graph)). When supplied, its search() and ask() are queried too;
+ *   omitted -> block-only search.
  * @param {number} [opts.graphLimit=8]  graph search()'s result limit
  * @returns {Promise<Array<{source:"block"|"graph-search"|"graph-ask", id:string, text:string, score:number}>>}
- *   best-first within each source; blocks first, then graph-search, then graph-ask (stable,
- *   deterministic order — never shuffled/merged by score across sources, since block scores
- *   and graph relevance are not on a comparable scale; Stage 2's grouping doesn't need them
- *   to be).
+ *   best-first within each source; blocks first, then graph-search, then graph-ask (never
+ *   shuffled/merged by score across sources — block scores and graph relevance aren't
+ *   comparable).
  */
 export async function broadSearch(dir, query, {
   blockK = DEFAULT_BLOCK_K, graphService = null, graphLimit = DEFAULT_GRAPH_LIMIT,

package/src/concept.mjs

@@ -1,30 +1,15 @@
-// concept.mjs — "the concept force": compose a THREE-BAND answer to a vague
-// "what is a X" touch, when tmct KNOWS the concept X (a curated definition) AND
-// HAS instances of it (individuals in the code graph and/or remembered isa facts).
-//
-//   1. THE FACT   — the definition of X (lead clause of the corpus/seon entry).
-//   2. THE EXAMPLES — real instances of X: code-graph individuals whose class maps
-//      to X (capped ~3, stable graph order, each a real node), plus any remembered
-//      "A is a X" facts.
-//   3. THE GUIDED FOLLOW-UP — 2-3 concrete, RUNNABLE next questions built from the
-//      real instances × the query shapes valid for that kind, EACH PRE-CHECKED by
-//      actually running it through ask() so a suggestion can never miss.
-//
-// PURE given (graph, term, {definition, factRows}) — the follow-up validator calls
-// ask() (deterministic, no model), so the whole composition is reproducible. The
-// caller (chat.mjs) owns the async edges: loading corpus/seon/definitions.jsonl and
-// the memory fact rows, and rendering through the response template. This module
-// never fabricates: every example is a real individual/fact and every follow-up is
-// validated against the same graph before it is offered.
+// concept.mjs — "the concept force": compose a three-band answer (fact,
+// examples, guided follow-up) to a vague "what is a X" touch when X is a
+// known, instantiated concept. Pure given (graph, term, {definition,
+// factRows}); never fabricates — every example is a real individual/fact and
+// every follow-up is pre-validated by actually running it through ask().
 
 import { ask } from "./ask.mjs";
 import { relationKind } from "./codegraph.mjs";
 
-/** A vague concept term (normalized, singular — normFactTerm's output) → the graph
- *  individual `class` it enumerates. The closed set of code-structure concepts the
- *  seon lexicon + the graph both understand; anything outside it is not a "concept
- *  force" touch (a general-vocabulary term like "cache" has a definition but no
- *  enumerable graph class, so it falls back to the ordinary definition surface). */
+/** A vague concept term (normalized, singular) → the graph individual `class`
+ *  it enumerates. Outside this closed set (e.g. "cache"), the term falls back
+ *  to the ordinary definition surface instead. */
 export const CONCEPT_CLASS = Object.freeze({
   class: "Class",
   module: "Module",
@@ -52,11 +37,8 @@ const CLASS_NOUN = Object.freeze({
  *  instance, so it never contributes an example. */
 const ISA_INSTANCE_PREDICATES = new Set(["rdf:type"]);
 
-/** Per graph-class, the candidate follow-up shapes in priority order. Each builder
- *  takes ONE real instance label and returns a query string; the builder is offered
- *  only after the query VALIDATES against the live graph, so a shape that can't
- *  resolve for any instance is silently dropped. Shapes are curated to be exactly
- *  the ones ask.mjs's grammar answers for that kind. */
+/** Per graph-class, the candidate follow-up shapes in priority order — each
+ *  offered only once its query validates against the live graph. */
 const FOLLOWUP_SHAPES = Object.freeze({
   Class: [
     (x) => `which classes inherit from ${x}`,
@@ -125,11 +107,8 @@ function resolves(graph, query) {
   }
 }
 
-/** Build up to MAX_FOLLOWUPS validated follow-ups for a class's instances. For each
- *  shape in priority order, find the instances whose query resolves and offer it for
- *  the first such instance NOT already used by an earlier follow-up (so the set
- *  showcases DIFFERENT real nodes where possible); a shape no instance satisfies is
- *  dropped entirely. Deterministic (graph order in, first-fit out). */
+/** Up to MAX_FOLLOWUPS validated follow-ups: first-fit over shapes in
+ *  priority order, preferring an instance not already used. */
 function buildFollowups(graph, cls, instanceLabels) {
   const shapes = FOLLOWUP_SHAPES[cls] || [];
   const used = new Set();
@@ -145,14 +124,8 @@ function buildFollowups(graph, cls, instanceLabels) {
   return out;
 }
 
-/** Compose the three bands for a concept term, or null when it is NOT a concept-force
- *  case — the term is not a known enumerable concept, has no curated definition, or
- *  has NO instances anywhere (code graph and memory both empty). Returns the pieces as
- *  strings so the caller can render them through a data template:
- *    { definition, examples, followups, instances:[{id,label,type,module}] }
- *  `examples` is always non-empty when non-null (we only fire with real instances);
- *  `followups` is "" when no validated next-question exists, else a "\nWant to go
- *  deeper? Try:\n  • …" block. */
+/** Compose the three bands for a concept term, or null when it's not a known
+ *  enumerable concept, has no curated definition, or has no instances anywhere. */
 export function composeConcept(graph, term, { definition = null, factRows = [] } = {}) {
   const cls = CONCEPT_CLASS[term];
   if (!cls || !definition) return null;
@@ -225,20 +198,12 @@ export function composeConcept(graph, term, { definition = null, factRows = [] }
   };
 }
 
-// ============================================================================
-// THE RELATION CONCEPT FORCE — the same three-band shape (definition + real
-// example EDGES + validated follow-ups) for a vague touch on a RELATION/edge kind
-// ("what about imports", "what are the calls", "tell me about contains"). Where
-// composeConcept enumerates INDIVIDUALS of a class, composeRelation enumerates the
-// EDGES of a relation kind, and seeds its follow-ups from real edge endpoints.
-// PURE given (graph, relTerm, {definition}); every example is a real edge and every
-// follow-up is validated via resolves() before it is offered. Never fabricates.
-// ============================================================================
-
-/** A vague relation term (lower-cased) → the internal concept key it enumerates.
- *  The closed set of edge-kind concepts the seon relation table + the graph both
- *  understand; a term outside it is not a relation-force touch. Nouns, gerunds and
- *  a couple of synonyms all collapse to one key. */
+// ---- THE RELATION CONCEPT FORCE — same three bands, but for a vague touch on
+// a RELATION/edge kind ("what about imports"): composeConcept enumerates
+// INDIVIDUALS, composeRelation enumerates EDGES. ----
+
+/** A vague relation term (lower-cased) → the internal concept key it
+ *  enumerates. Nouns, gerunds and synonyms all collapse to one key. */
 export const RELATION_TERM = Object.freeze({
   import: "imports", imports: "imports", importing: "imports", imported: "imports",
   call: "calls", calls: "calls", calling: "calls", called: "calls", invoke: "calls", invokes: "calls", invoking: "calls",
@@ -249,11 +214,8 @@ export const RELATION_TERM = Object.freeze({
   define: "defines", defines: "defines", defining: "defines", defined: "defines", definition: "defines", definitions: "defines", declaration: "defines",
   touch: "touches", touches: "touches", touching: "touches", touched: "touches",
   cochange: "cochange", "co-change": "cochange", "change-coupling": "cochange", coupled: "cochange",
-  // "export"/"exports" is ALSO a curated seon lexicon noun (corpus/seon/definitions.jsonl
-  // "export"), same shape as "imports" — but that meta reading only owns the "what
-  // does export mean"/"what is an export" shape; vagueTouchTermOf/relationTermOf are
-  // deliberately scoped to the NON-meta "what about X"/"tell me about X" touch (see
-  // relationTermOf's own docblock, frozen case am-meta-imports), so no conflict here.
+  // "export"/"exports" is also a curated seon lexicon noun, but that meta reading
+  // only owns "what does export mean" — no conflict with this vague-touch table.
   export: "reexports", exports: "reexports", exporting: "reexports", exported: "reexports",
   reexport: "reexports", reexports: "reexports", reexporting: "reexports",
   "re-export": "reexports", "re-exports": "reexports", "re-exporting": "reexports",
@@ -288,11 +250,9 @@ const RELATION_RENDER = Object.freeze({
   reexports: { verb: "re-exports", edgeNoun: "re-export" },
 });
 
-/** Per concept key, the candidate follow-up shapes in priority order. Each shape
- *  draws a real endpoint from one SIDE of the edges (subject or object) and builds a
- *  query; a shape is offered only once the query VALIDATES against the live graph
- *  (resolves()), so a shape no endpoint satisfies is silently dropped. Curated to be
- *  exactly the shapes ask.mjs answers for that kind. */
+/** Per concept key, the candidate follow-up shapes in priority order — each
+ *  draws an endpoint from one side of the edges and is offered only once its
+ *  query validates against the live graph. */
 const RELATION_FOLLOWUP_SHAPES = Object.freeze({
   imports: [
     { side: "obj", make: (x) => `which modules import ${x}` },
@@ -340,10 +300,8 @@ const MAX_EDGE_EXAMPLES = 3;
 const edgeSubjectLabel = (e) => String(e.subjectLabel || e.subject);
 const edgeObjectLabel = (e) => String(e.objectLabel || e.object);
 
-/** Build up to MAX_FOLLOWUPS validated follow-ups for a relation's edges. Same
- *  first-fit discipline as buildFollowups: for each shape in priority order, find the
- *  endpoints (of that shape's side) whose query resolves and offer it for the first
- *  such endpoint not already used, so the set showcases DIFFERENT real nodes. */
+/** Up to MAX_FOLLOWUPS validated follow-ups for a relation's edges — same
+ *  first-fit discipline as buildFollowups. */
 function buildRelationFollowups(graph, key, subjLabels, objLabels) {
   const shapes = RELATION_FOLLOWUP_SHAPES[key] || [];
   const used = new Set();
@@ -360,25 +318,11 @@ function buildRelationFollowups(graph, key, subjLabels, objLabels) {
   return out;
 }
 
-/** Compose the three bands for a RELATION concept term, or null when it is NOT a
- *  relation-force case at all — the term is not a known enumerable relation, or has no
- *  curated definition. Returns the same string-band shape composeConcept does:
- *    { definition, examples, followups, followupQueries, remainder, noun }
- *  `examples` is always non-empty when non-null; `followups` is "" when no validated
- *  next-question exists.
- *
- *  A known relation whose graph has ZERO edges of that kind is NOT null — it degrades
- *  to a two-band answer (the definition + an explicit "this codebase has no X edges"
- *  line, `examples`-shaped so the caller renders it identically). Found live (an
- *  advisor tick on the 0.9.14 Tier-2 playtest cycle): returning null here for the
- *  zero-edge case let the caller's OWN raw grammar attempt at the vague-touch text
- *  ("what about exports", "tell me about reexports") stand instead — but that text was
- *  never meant to be parsed as an object search, so on a graph with no reexports edges
- *  (the realistic case for most repos, e.g. examples/mini-webapp) it fell through to a
- *  garbled `no module matching "about"/"exports" found`, not an honest miss. A relation
- *  kind the graph has NEVER SEEN AT ALL (relationKind returns nothing in RELATION_KINDS
- *  for this graph's shape) still degrades the same way — the definition is always
- *  worth stating; only the fabricated edge is refused. */
+/** Compose the three bands for a RELATION concept term, or null when it's not
+ *  a known enumerable relation or has no curated definition. A known relation
+ *  with ZERO edges is NOT null — it degrades to a two-band "no X edges"
+ *  answer, since returning null here would fall through to a garbled raw
+ *  grammar miss instead of an honest one. */
 export function composeRelation(graph, relTerm, { definition = null } = {}) {
   const key = RELATION_TERM[String(relTerm || "").toLowerCase()];
   if (!key || !definition) return null;

package/src/conformance.mjs

@@ -1,15 +1,11 @@
 // conformance.mjs — the Repository-Interface CONTRACT TEST SUITE as a reusable kit.
 //
-// archive/PLAN_REPOSITORY_INTERFACE.md deliverable 3: an implementation is CONFORMANT iff it
-// passes `runConformance(name, makeProvider)`. tmct's own fixture + bootstrap providers
-// pass it in `npm test`; an EXTERNAL producer (seonix) imports this kit from the
-// published package and runs the SAME suite against its native provider to claim
-// conformance — conformance is the suite, not prose. It is provider-agnostic: it
-// asserts the SHAPE + the error contract; data-bearing truth is asserted by the caller
-// where its provider carries data.
+// An implementation is CONFORMANT iff it passes `runConformance(name, makeProvider)`.
+// Provider-agnostic: it asserts the shape + error contract; data-bearing truth is
+// asserted by the caller where its provider carries data.
 //
-// Public surface (exported here + via the package "./conformance" subpath):
-//   runConformance(name, makeProvider), assertResult, assertIndividual, assertEdge.
+// Public surface: runConformance(name, makeProvider), assertResult, assertIndividual,
+// assertEdge.
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
@@ -114,8 +110,8 @@ export function runConformance(name, makeProvider) {
     assert.throws(() => svc.edges("no:such:id", "not-a-real-kind"), TypeError);
   });
 
-  // snippet: UNCHANGED by INTERFACE_VERSION 1.1.0 — it has nothing useful without fs, so it
-  // still honestly misses NO_SOURCE (or UNRESOLVED_TERM on an empty graph) with no working tree.
+  // snippet has nothing useful without fs, so it honestly misses NO_SOURCE (or
+  // UNRESOLVED_TERM on an empty graph) with no working tree.
   test(`[${name}] snippet answers NO_SOURCE (not a throw) when no working tree`, async () => {
     const svc = makeProvider();
     if (svc.sourceAccess) return; // covered by the source-capable branch below instead
@@ -129,10 +125,10 @@ export function runConformance(name, makeProvider) {
     );
   });
 
-  // context: NARROWED by INTERFACE_VERSION 1.1.0 — contextPlan/sizeBundle/renderGraphOnlyBundle
-  // are pure graph queries, so a graph-only provider (no working tree) now returns a REAL HIT
-  // for any resolvable symbol; only an unresolvable symbol still misses (UNRESOLVED_TERM). See
-  // repository-interface.mjs's context service entry for the full rationale.
+  // context: contextPlan/sizeBundle/renderGraphOnlyBundle are pure graph queries, so a
+  // graph-only provider (no working tree) returns a REAL HIT for any resolvable symbol;
+  // only an unresolvable symbol still misses (UNRESOLVED_TERM). See repository-interface.mjs's
+  // context service entry for the full rationale.
   test(`[${name}] context returns a graph-only HIT for a resolvable symbol, even with no working tree`, async () => {
     const svc = makeProvider();
     if (svc.sourceAccess) return; // covered by the source-capable branch below instead