@polycode-projects/the-mechanical-code-talker 1.10.6 → 1.10.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.10.6",
+  "version": "1.10.8",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/chat.mjs

@@ -81,7 +81,7 @@ function note(trace, text) { if (trace) trace.push(text); }
 
 /** relation `kind` (ask-vocab.mjs RELATIONS) -> a short, deterministic
  *  statement of what a person asking that KIND of question is probably after.
- *  Deliberately a small, honest bucket lookup over the query SHAPE the engine
+ *  A small bucket lookup over the query SHAPE the engine
  *  already computed — tmct is no-LLM, so goal deduction is table-driven, never
  *  free-text generation. A kind/shape this table doesn't recognise falls
  *  through to a generic line in deduceGoalFromParsed, never a fabricated guess. */
@@ -417,8 +417,7 @@ const ANAPHORA_COUNT_RE = /\b(?:how many|how much|count|number of)\s+(?:of\s+)?(
  *  filter on) is untouched. */
 const IMPLICIT_ANAPHORA_COUNT_RE = /^(?:(?:and|so|then|also)\s+)?how many (?:are|is|were|was)\s+(?!there\b)(\S.*)$/i;
 
-/** "have"/"has"/"holds"/"hold" are excluded from RESTRICTOR_VERB_RE below —
- *  deliberately treated as non-restrictor cues, not a bug fix skipped.
+/** "have"/"has"/"holds"/"hold" are excluded from RESTRICTOR_VERB_RE below.
  *  Ask-vocab's VERB_TO_KIND maps them to "defines" unconditionally, but the
  *  graph's actual "have" semantics are subject-type-dependent (a Module "has"
  *  things it defines; a Class "has" things it contains) — ask.mjs's own
@@ -797,8 +796,8 @@ const AI_IDENTITY_PHRASES = [
  *  two-sentence turn like "are you an AI? like chatgpt?" could never match
  *  the whole raw string even though its first clause alone is an exact "are
  *  you an AI" hit. Used ONLY by aiIdentityMatch below — every OTHER
- *  closed-set match in this file stays whole-string, on purpose (deliberately
- *  narrow to the one family that's shown up broken this way). */
+ *  closed-set match in this file stays whole-string (scoped to the one
+ *  family that's shown up broken this way). */
 function splitClauses(text) {
   return String(text).split(/[?!.]+\s*/).map((c) => c.trim()).filter(Boolean);
 }
@@ -1848,11 +1847,10 @@ const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|a\s+|an\s+)?([\w-]+(?:\s+[
 const MINT_ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
 
 /** Small CLOSED set of generic English root nouns that count as always-
- *  grounded anchor terms for the mint-fallbacks below (operator refinement,
- *  2026-07-09) — deliberately NOT added to lexicon-core.json itself (that
- *  file stays the curated ~180-word CODE vocabulary; these are ordinary-
- *  English root nouns with no code meaning at all, confirmed absent from it
- *  today). Their only job is to give a user who hits the "both sides
+ *  grounded anchor terms for the mint-fallbacks below — not in
+ *  lexicon-core.json (these are ordinary-English root nouns with no code
+ *  meaning, absent from that code vocabulary). Their only job is to give a
+ *  user who hits the "both sides
  *  ungrounded" decline (groundingSuggestionMiss, below) an honest, guessable
  *  way in: ground one brand-new term via one of THESE words first ("every
  *  zorp is a thing"), then chain the other new term off the now-grounded one. */
@@ -2314,6 +2312,11 @@ const GENERAL_VERB_NOT_A_VERB_RE = new RegExp(
 async function generalVerbPredicate(verb) {
   const v = String(verb || "").toLowerCase();
   if (v === "has" || v === "have") return HAS_A_PREDICATE;
+  // The modal maps onto the corpus's own capability predicate — "dog can
+  // swim" is a capability claim, not a transitive "to can" — so a taught
+  // capability reads back interoperably with /r/CapableOf data and the
+  // "can a X <verb>" reader finds it (same reasoning as HAS_A above).
+  if (v === "can") return "mgx:capableOf";
   try {
     const { proseLemma } = await import("./prose-nlp.mjs");
     const lemma = proseLemma();
@@ -2345,6 +2348,10 @@ async function generalVerbTeach(payload) {
   const verb = verbRaw.toLowerCase();
   if (GENERAL_VERB_EXCLUDE_RE.test(verb)) return null; // owned by a more specific frame above
   if (GENERAL_VERB_NOT_A_VERB_RE.test(verb)) return null; // a closed-class word can never be the real verb
+  // "cannot" would mint a nonsense mgx:cannot fact whose read-back silently
+  // INVERTS the taught meaning — the vocabulary has no negative-capability
+  // predicate, so an honest decline is the only correct move.
+  if (verb === "cannot") return null;
   if (GENERAL_VERB_DETERMINER_RE.test(subjectRaw)) return null; // not a bare-name subject
   const subject = subjectRaw.trim();
   const object = objectRaw.replace(/^an?\s+/i, "").trim();
@@ -4159,6 +4166,42 @@ const REVERSE_PREDICATE_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
     re: new RegExp(`^what\\s+${escapeRegex(phrase)}\\s+(.+?)[?.!\\s]*$`, "i"),
   }))
   .sort((a, b) => b.re.source.length - a.re.source.length); // longest phrase first
+
+// The FORWARD yes/no mirror of REVERSE_PREDICATE_MARKERS: one derived
+// "is/are X <phrase> Y" (copula phrases), "can X be Y" (receivesAction), or
+// "does/do X <base-verb> Y" (verb phrases, naive de-3sg fold) reader per
+// FACT_PREDICATE_PHRASES entry — so every relation the table can RENDER can
+// also be ASKED as a forward yes/no, instead of each one needing its own
+// hand-written lane. Excluded: the isa family and hasProperty (ISA_ASK_RE /
+// IS_ADJECTIVE_YESNO_RE territory), hasA and capableOf (their dedicated
+// readers above carry teach hints these derived ones deliberately don't —
+// no derived hint is emitted because no teach phrasing for these relations
+// is verified to round-trip).
+const FORWARD_YESNO_EXCLUDE = new Set([
+  "rdfs:subClassOf", "rdf:type", "owl:disjointWith", "mgx:hasProperty",
+  "mgx:hasA", "mgx:capableOf",
+  // ownership's dedicated reader (OWNS_YESNO_RE) answers a confident
+  // closed-world "no" — a stronger contract than the derived "can't
+  // confirm", so the derived reader must never intercept it.
+  "mgx:ownedBy",
+]);
+const FORWARD_YESNO_MARKERS = Object.entries(FACT_PREDICATE_PHRASES)
+  .filter(([predicate]) => !FORWARD_YESNO_EXCLUDE.has(predicate))
+  .map(([predicate, phrase]) => {
+    let re;
+    if (phrase === "can be") {
+      re = new RegExp("^can\\s+(?:an?\\s+|the\\s+)?(.+?)\\s+be\\s+(.+?)[?.!\\s]*$", "i");
+    } else if (phrase.startsWith("is ")) {
+      const rest = escapeRegex(phrase.slice(3));
+      re = new RegExp(`^(?:is|are)\\s+(?:an?\\s+|the\\s+)?(.+?)\\s+${rest}\\s+(?:an?\\s+|the\\s+)?(.+?)[?.!\\s]*$`, "i");
+    } else {
+      const [head, ...tail] = phrase.split(" ");
+      const base = [head.replace(/s$/, ""), ...tail].map(escapeRegex).join("\\s+");
+      re = new RegExp(`^(?:does|do)\\s+(?:an?\\s+|the\\s+)?(.+?)\\s+${base}\\s+(?:an?\\s+|the\\s+)?(.+?)[?.!\\s]*$`, "i");
+    }
+    return { predicate, phrase, re };
+  })
+  .sort((a, b) => b.re.source.length - a.re.source.length); // longest phrase first
 // On the FIRST turn of a graph-less session, `envelope` stays null for the
 // whole turn (dispatchTool's loadGraph() throws its own documented empty-graph
 // ToolError, self-correcting from turn 2 on), so this regex is the ONLY path
@@ -4323,6 +4366,42 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   }
   if (!miss) return null;
 
+  // (b0) Derived forward yes/no readers — FORWARD_YESNO_MARKERS, one per
+  // renderable relation. Runs BEFORE the isa lane because ISA_ASK_RE's lazy
+  // subject otherwise swallows these shapes whole ("is a wheel part of a
+  // car" reads as subject "wheel part of") and ends the cascade. A real fact
+  // answers yes; a subject known under the SAME relation gets an honest miss
+  // citing those facts; a subject known at all (with no structural parse
+  // standing) gets a bare honest miss; anything else leaves the standing
+  // miss text alone — so a code-shaped query with a real parse is never
+  // hijacked.
+  for (const { predicate, phrase, re } of FORWARD_YESNO_MARKERS) {
+    const m = q.match(re);
+    if (!m) continue;
+    const facts = await memoryFacts(memoryDir);
+    const subj = factTermVariants(normFactTerm, m[1]);
+    const obj = factTermVariants(normFactTerm, m[2]);
+    const hit = facts.find((f) => f.predicate === predicate && subj.has(f.subject) && obj.has(f.object));
+    if (hit) return { text: `yes — ${renderFactLine(hit)}`, replace: true };
+    const sameRelation = facts.filter((f) => f.predicate === predicate && subj.has(f.subject));
+    if (sameRelation.length) {
+      const shown = sameRelation.slice(0, 3).map(renderFactLine).join("; ");
+      return {
+        text: `I can't confirm that — nothing I remember says ${m[1]} ${phrase} ${m[2]}. I do know: ${shown}.`,
+        replace: true,
+        miss: true,
+      };
+    }
+    if (!envelope?.parsed && facts.some((f) => subj.has(f.subject))) {
+      return {
+        text: `I can't confirm that — nothing I remember says ${m[1]} ${phrase} ${m[2]}.`,
+        replace: true,
+        miss: true,
+      };
+    }
+    break; // shape matched, nothing honest to add — the standing miss stands
+  }
+
   // (b) "is a module a component" — yes iff a remembered isa-family fact says so.
   // Also accepts "why is X a Y" / "explain how you know X is Y" — see matchWhyIsa.
   const isa = q.match(ISA_ASK_RE) || matchWhyIsa(q);
@@ -4341,12 +4420,27 @@ export async function factAnswer(memoryDir, query, envelope, miss, biasByBundle
   // single-hit lookup, same "never a guessed no" discipline).
   const can = q.match(CAN_ASK_RE);
   if (can) {
+    const facts = await memoryFacts(memoryDir);
     const subj = factTermVariants(normFactTerm, can[1]);
     const obj = factTermVariants(normFactTerm, can[2]);
-    const hit = (await memoryFacts(memoryDir)).find(
+    const hit = facts.find(
       (f) => f.predicate === "mgx:capableOf" && subj.has(f.subject) && obj.has(f.object),
     );
     if (hit) return { text: `yes — ${renderFactLine(hit)}`, replace: true };
+    // A KNOWN subject with capability facts, none matching: an honest,
+    // specific miss citing what it CAN do — the same closer the is-a ladder
+    // answers with, instead of the misleading structural parse wall. An
+    // unknown subject still declines. Never a guessed "no": absence of a
+    // capableOf fact proves nothing.
+    const knownCan = facts.filter((f) => f.predicate === "mgx:capableOf" && subj.has(f.subject));
+    if (knownCan.length) {
+      const shown = knownCan.slice(0, 3).map(renderFactLine).join("; ");
+      return {
+        text: `I can't confirm that — nothing I remember says ${can[1]} can ${can[2]}. I do know: ${shown}. If it's true, teach me: "a ${can[1]} can ${can[2]}".`,
+        replace: true,
+        miss: true,
+      };
+    }
     return null;
   }
 
@@ -5370,7 +5464,45 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
     // to the honest miss below, never a guessed "no".
     const { deriveDisjointViolations, DISJOINT_PREDICATE } = await import("./syllogise.mjs");
     const disjointRows = rows.filter((f) => f.predicate === DISJOINT_PREDICATE && isTaught(f));
+    // NEGATED membership — "is a dog not a cat". ISA_ASK_RE captures the
+    // subject as "dog not" (the "not" glues onto the subject because the
+    // article anchors the kind), so without this the negated question walks
+    // the positive ladder with a garbage subject and lands on a nonsense
+    // teach hint. Strip the "not", then answer INVERTED: a positive isa fact
+    // refutes it ("no — dog is a kind of cat"), a taught disjointness
+    // confirms it ("yes — dog is not a cat"), anything else is an honest
+    // can't-confirm pointing at the already-supported "no X is a Y" teach
+    // shape. Deliberately shallow — no chain chases on the negated side; a
+    // negative proved through a multi-hop positive chain stays an honest
+    // miss rather than a guess.
+    const negSubject = isaAsk[1].match(/^(.*\S)\s+not$/i);
+    if (negSubject) {
+      const negSubjVariants = factTermVariants(normFactTerm, negSubject[1]);
+      const negObjVariants = objVariants;
+      const posHit = isa
+        .filter((f) => negSubjVariants.has(f.subject) && negObjVariants.has(f.object))
+        .sort(byTrust)[0];
+      if (posHit) return { text: `no — ${renderFactLine(posHit)}`, replace: true };
+      const negDisjoint = disjointRows.find((f) => (negSubjVariants.has(f.subject) && negObjVariants.has(f.object))
+        || (negSubjVariants.has(f.object) && negObjVariants.has(f.subject)));
+      if (negDisjoint) return { text: `yes — ${renderFactLine(negDisjoint)}`, replace: true };
+      const negSubjectWord = negSubject[1].trim();
+      const negKindWord = stripTrailingDiscourseTag(isaAsk[2]).trim();
+      return {
+        text: `I can't confirm that either way — nothing I remember links ${negSubjectWord} and ${negKindWord}. If no ${negSubjectWord} is a ${negKindWord}, teach me: "no ${negSubjectWord} is a ${negKindWord}".`,
+        replace: true,
+        miss: true,
+      };
+    }
     if (disjointRows.length) {
+      // A DIRECT taught disjointness between the asked subject and kind is a
+      // provable "no" on its own — deriveDisjointViolations only ever fires
+      // through a taught rdf:type premise, so without this check "no dog is
+      // a cat" followed by "is a dog a cat" fell through to the can't-confirm
+      // closer instead of the honest no.
+      const directDisjoint = disjointRows.find((f) => (subjCandidates.has(f.subject) && objVariants.has(f.object))
+        || (subjCandidates.has(f.object) && objVariants.has(f.subject)));
+      if (directDisjoint) return { text: `no — ${renderFactLine(directDisjoint)}`, replace: true };
       const disjointEdges = disjointRows.map((f) => [f.subject, f.object]);
       const violations = deriveDisjointViolations(chainTypeEdges, chainSubClassEdges, disjointEdges, { budget: 10 });
       for (const subj of subjCandidates) {

package/src/completions/group.mjs

@@ -19,7 +19,7 @@ function contentTokens(text) {
 }
 
 /** Plain union-find (path halving, union-by-index) — small N here (a single broad search's
- *  hit count), so this is deliberately the simplest correct structure, not a fancy one. */
+ *  hit count). */
 function unionFind(n) {
   const parent = Array.from({ length: n }, (_, i) => i);
   function find(x) {

package/src/completions/rank.mjs

@@ -2,7 +2,7 @@
 // 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.
+// splitSentences() is a simple regex splitter.
 
 import { degreeOf, rankBlocks, tokenizeBlock, OVERLAP_MIN } from "../memory/blocks.mjs";
 import { STOPWORDS } from "../prose.mjs";
@@ -15,8 +15,8 @@ function contentTokens(text) {
   return tokenizeBlock(text).filter(isContentToken);
 }
 
-// Sentence boundary: a run of [.!?] followed by whitespace and an uppercase letter or digit —
-// deliberately simple (no abbreviation dictionary, no NLP dependency).
+// Sentence boundary: a run of [.!?] followed by whitespace and an uppercase letter or digit
+// (no abbreviation dictionary).
 const SENTENCE_SPLIT_RE = /(?<=[.!?])\s+(?=[A-Z0-9])/;
 
 /**

package/src/corpus/unknown-ingest.mjs

@@ -9,7 +9,7 @@
 // `mgx:contextPassage` fact (the passage it was found in — ConceptNet's own surfaceText,
 // or the map's `surface` template) and `mgx:coOccursWith` links to its row's other
 // endpoint plus any already-known terms recognizable in the same passage (bounded) —
-// deliberately closed-vocabulary co-occurrence, not distributional/embedding inference.
+// closed-vocabulary co-occurrence.
 //
 // Wired as an opt-in `captureUnknownContext: true` on seedMemory (conceptnet.mjs),
 // dynamically imported to avoid a load-time cycle with conceptnet.mjs.

package/src/finish.mjs

@@ -251,7 +251,7 @@ function ruleArticle(segments, rule) {
   return out;
 }
 
-// Rule 2 — subject–verb agreement. STRUCTURE-DRIVEN and deliberately narrow:
+// Rule 2 — subject–verb agreement. STRUCTURE-DRIVEN:
 // (i) an existential "there is/are/was/were" agrees with the FOLLOWING number
 //     span's value (the number is genuinely the subject there);
 // (ii) any listed copula agrees with a following span that carries an explicit

package/src/grammar/ace.mjs

@@ -1,5 +1,5 @@
 // grammar/ace.mjs — tmct's deterministic ACE-OWL sub-fragment parser.
-// Implements the 8 controlled-English sentence patterns of
+// Implements the 9 controlled-English sentence patterns of
 // docs/references/schemas/ace-owl-fragment.md and nothing more: fitting the
 // grammar is a strong signal, missing it is a FEATURE — parseAce returns null
 // (or an empty-triples result carrying the unknown words as `residue`) and the
@@ -44,11 +44,13 @@ export const PATTERN_CARDINALITY = "cardinality";
 export const PATTERN_DISJOINT_WITH = "disjointWith";
 export const PATTERN_POSSESSIVE = "possessive";
 export const PATTERN_ADJECTIVE = "adjective";
+export const PATTERN_CAPABILITY = "capability";
 
 /** The pattern field's full domain, in the README's table order. */
 export const PATTERNS = Object.freeze([
   PATTERN_SUB_CLASS_OF, PATTERN_TYPE_ASSERTION, PATTERN_RELATION, PATTERN_SOME_VALUES_FROM,
   PATTERN_CARDINALITY, PATTERN_DISJOINT_WITH, PATTERN_POSSESSIVE, PATTERN_ADJECTIVE,
+  PATTERN_CAPABILITY,
 ]);
 
 const DET = new Set(["a", "an", "the"]);
@@ -413,7 +415,7 @@ function parseCopula(lexicon, toks, lower, isIdx) {
   ]);
 }
 
-/** Parse one sentence against the 8-pattern ACE-OWL sub-fragment. See the file
+/** Parse one sentence against the 9-pattern ACE-OWL sub-fragment. See the file
  *  header for the result contract; `lexicon` defaults to the committed core
  *  under the library's own neutral DEFAULT_NS ("ex:") when the caller doesn't
  *  supply one. */
@@ -429,5 +431,32 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
   }
   const isIdx = lower.indexOf("is");
   if (isIdx > 0) return parseCopula(lexicon, toks, lower, isIdx);
+  const canIdx = lower.indexOf("can");
+  if (canIdx > 0 && canIdx < toks.length - 1) {
+    const cap = parseCapability(lexicon, toks, canIdx);
+    if (cap) return cap;
+  }
   return parseRelation(lexicon, toks, lower);
 }
+
+/** Pattern 9 — "N can VERB" → mgx:capableOf. The modal is not a relation
+ *  verb: without this, parseRelation reads "can" through lookupVerb and
+ *  asserts a generic object property ("dog cans swim") that no capability
+ *  reader ever finds. Returns null (never a miss record) unless BOTH sides
+ *  resolve, so a noun "can" ("trash can holds garbage") still falls through
+ *  to parseRelation. "cannot"/"can't" stays unparsed — the fact vocabulary
+ *  has no negative-capability predicate, and a silently dropped negation
+ *  would invert the taught meaning. */
+function parseCapability(lexicon, toks, canIdx) {
+  const np1 = resolveNP(lexicon, toks.slice(0, canIdx));
+  if (np1.term == null) return null;
+  // The capability's object is a VERB ("swim"), not a lexicon noun, so
+  // resolveNP is the wrong resolver for it: accept exactly one bare word,
+  // stored as a plain term — the same grain the corpus's own CapableOf
+  // objects ("bark", "run") already use.
+  const rest = toks.slice(canIdx + 1);
+  if (rest.length !== 1 || !/^[a-z][a-z-]*$/i.test(rest[0])) return null;
+  return hit(PATTERN_CAPABILITY, [np1], [
+    { subject: np1.term, predicate: "mgx:capableOf", object: `${lexicon.ns}${rest[0].toLowerCase()}`, kind: "mgx:capableOf" },
+  ]);
+}

package/src/grammar/lexicon.mjs

@@ -14,7 +14,7 @@
 // Namespace: every lexicon carries a `.ns` field (the CURIE prefix ace.mjs
 // stamps onto every term it mints) — always "tmct:" here (DEFAULT_NS).
 //
-// Morphology is deliberately tiny and deterministic (no NLP dependency): a
+// Morphology is deterministic (no NLP dependency): a
 // suffix-fold for plurals/3rd-person-singular ("repositories"→repository,
 // "relies"→rely, "classes"→class, "uses"→use) plus an optional declared
 // irregular `plural` ("indices"). Anything the fold can't reach is simply not

package/src/init.mjs

@@ -47,8 +47,7 @@ export function defaultConfig() {
 /** `tmct init --with-persona <name>` presets: a named bundle of `extensions`/`bias`
  *  overrides written into tmct.toml. `human` makes the implicit default explicit; `code`
  *  re-activates the software-domain `seon`+`conceptnet` bundles; `empty` deactivates
- *  `human`, leaving a repo genuinely empty of corpus facts. Kept minimal on purpose —
- *  the persona seam, not a curated library of presets. */
+ *  `human`, leaving a repo genuinely empty of corpus facts. */
 export const PERSONA_PRESETS = Object.freeze({
   human: { extensions: {}, bias: { human: 1.0 } },
   code: { extensions: { seon: { active: true }, conceptnet: { active: true } }, bias: { seon: 1.0, conceptnet: 1.0 } },

package/src/interpret/normalize.mjs

@@ -239,7 +239,7 @@ export function applySubordinationFrames(text) {
  *  delimiter are both required — an ordinary em-dash aside is common prose,
  *  not a restart, and treating every dash as a delimiter would be a guess.
  *  The trailing delimiter also means an object-only restart with no comma
- *  after "i mean" isn't rescued here; that's a narrower, accepted ceiling. */
+ *  after "i mean" isn't rescued here. */
 const SELF_CORRECTION_RE =
   /^.+?(?:\s*(?:--|—|-)\s*)?\b(?:sorry|i\s+mean)\b\s*(?:--|—|-|,|:)\s*(.+)$/i;
 

package/src/router/guardrail.mjs

@@ -1,6 +1,5 @@
 // src/router/guardrail.mjs — the guardrail. Validate an
-// EXTERNALLY-proposed `tool_use` against the registry's declared preconditions, and
-// DEFAULT-DENY anything outside the declared, registered envelope.
+// EXTERNALLY-proposed `tool_use` against the registry's declared preconditions.
 //
 // Proves RESOLVABILITY (the tool is registered/declared, args are well-formed, every
 // `resolves(param, as)` precondition binds to a real graph entity) — NOT antecedent
@@ -14,8 +13,8 @@ import { capabilityByName, preconditionsOf, PRECOND } from "./registry.mjs";
 import { hallucinationsIn } from "./call-validator.mjs";
 
 /** The same read-only breadth-first enrichment as resolver.mjs's `dispatchEachCandidate`:
- *  every registered capability is `readOnly:true` with an empty delete-list, so dispatching
- *  the SAME tool once per tied candidate is safe. Returns `[{candidate, result}, ...]`, or
+ *  dispatching the SAME tool once per tied candidate is safe for `readOnly` capabilities
+ *  (dispatch performs no writes). Returns `[{candidate, result}, ...]`, or
  *  undefined when there is no dispatcher to run it with. */
 async function dispatchEachCandidate(pool, capName, arg, ctx) {
   if (!ctx.dispatch) return undefined;

package/src/router/registry.mjs

@@ -2,11 +2,10 @@
 //
 // Each tmct tool is modelled as a STRIPS/PDDL operator declared as DATA: a `Capability` with
 // typed `Parameter`s, `Precondition`s, and `Effect`s (add-list/delete-list). Preconditions are
-// the safety gate guardrail.mjs checks before a call fires; effects are epistemic
-// (a read-only query "knows" a topic, never mutates) — resolver.mjs backward-chains
-// from a goal `(knows <topic> ?x)` to the capability whose add-list achieves it.
+// the safety gate guardrail.mjs checks before a call fires; resolver.mjs backward-chains from
+// a goal to a capability whose add-list achieves it.
 //
-// Pure: plain frozen data + pure accessors, no I/O. Tool names + parameter arg keys are the
+// Plain data + pure accessors, no I/O. Tool names + parameter arg keys are the
 // exact ones src/server.mjs `dispatchTool` reads, so a bound call this registry validates is
 // directly dispatchable.
 
@@ -45,7 +44,7 @@ export const PRECOND = Object.freeze({
 
 // ---- capability builder (returns PLAIN FROZEN data) -------------------------
 
-/** A parameter slot. `arg` is the EXACT dispatchTool key (never invented). */
+/** A parameter slot. `arg` is the exact key src/server.mjs `dispatchTool` reads. */
 const param = (name, kind, { arg = name, required = true, note = "" } = {}) =>
   Object.freeze({ type: VOCAB.Parameter, name, kind, arg, required, note });
 
@@ -58,31 +57,29 @@ const resolves = (paramName, as) =>
 const anyPresent = (params) =>
   Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.anyPresent, params: Object.freeze([...params]) });
 
-/** An epistemic add-effect: after the call the agent KNOWS `topic` about `?of`. */
+/** Add-effect: after the call the agent knows `topic` about `?of`. */
 const knows = (topic, ofParam = null) =>
   Object.freeze({ type: VOCAB.Effect, pred: "cap:knows", topic, of: ofParam ? `?${ofParam}` : null });
 
-/** Declare one capability as frozen STRIPS data. Read-only query tools pass an
- *  empty delete-list (`del: []`) — the closed-world "queries mutate nothing". */
+/** Declare one capability as STRIPS data. */
 function capability({ name, label, question, params = [], preconditions = [], add = [], del = [] }) {
   return Object.freeze({
     type: VOCAB.Capability,
     name, // the dispatchTool tool name — directly callable
     label, // human label (the slash-command verb)
     question, // one-line "what question does this answer"
-    readOnly: true, // every capability here is query-only
+    readOnly: true, // dispatching this capability performs no writes
     parameters: Object.freeze(params),
     preconditions: Object.freeze(preconditions),
     effects: Object.freeze({ add: Object.freeze(add), del: Object.freeze(del) }),
   });
 }
 
-// ---- the registry — the read-only graph-query tools as operators ------------
-// Enumerated from src/server.mjs `dispatchTool` (the query-only, bounded-output
-// slice). Arg keys verified against the switch: describe/callers/callees/tests/
-// history/… take `symbol`; impact/exports take `module`; members/subclasses take
-// `class`; search takes `query` (+ optional kind/name/decorator); architecture
-// takes an optional `package`; untested takes nothing.
+// ---- the declared capabilities -----------------------------------------------
+// Arg keys verified against src/server.mjs `dispatchTool`'s switch: describe/callers/
+// callees/tests/history/… take `symbol`; impact/exports take `module`; members/
+// subclasses take `class`; search takes `query` (+ optional kind/name/decorator);
+// architecture takes an optional `package`; untested takes nothing.
 
 const CAPABILITIES = Object.freeze([
   capability({
@@ -187,12 +184,8 @@ const BY_NAME = Object.freeze(
   CAPABILITIES.reduce((m, c) => { m[c.name] = c; return m; }, Object.create(null)),
 );
 
-// ---- closed-world / DEFAULT-DENY --------------------------------------------
-// The registry is a strict subset of src/server.mjs's `dispatchTool` switch: a tool name
-// not registered here is treated as unknown/hallucinated, never dispatchable.
-//
-// The following dispatch tools are INTENTIONALLY UNREGISTERED — they emit unbounded raw
-// output, the most hallucination-prone surface, not a clean bounded-epistemic-effect query.
+// ---- unregistered dispatch tools ---------------------------------------------
+// Dispatch tools not yet registered; each names the precondition work it needs first.
 export const EXCLUDED_FROM_REGISTRY = Object.freeze({
   tmct_context: "unbounded edit-context bundle (multi-file); needs a size/budget precondition",
   tmct_context_more: "unbounded context continuation; same as tmct_context",

package/src/router/resolver.mjs

@@ -45,7 +45,7 @@ export const NL_INTENTS = Object.freeze({
   "reverse:cochange": { topic: "cochanges", arg: "symbol" },
 });
 
-// ---- ask-vocab RELATION kinds with NO capability — the HONEST ceiling --------
+// ---- ask-vocab RELATION kinds with NO capability ------------------------------
 // Every ask-vocab.mjs RELATIONS key must be either mapped (above) or listed here with a
 // reason (the conformance test enforces the partition). Refuse rather than mis-route.
 export const UNMAPPED_KINDS = Object.freeze({

package/src/source-slice.mjs

@@ -1,7 +1,7 @@
 // Shared, safe source-span slicing for the tool layer (src/server.mjs) and the
 // source-capable Repository Interface provider (src/providers/graph-service.mjs).
 //
-// Two halves, deliberately split:
+// Two halves:
 //   - sliceSpan   — PURE. Given an in-memory `lines` array, extracts + line-numbers
 //                   one span. No fs, no path logic.
 //   - readSpanSafe — the fs-touching half. Resolves `join(repoRoot, path)` with Node's