@polycode-projects/the-mechanical-code-talker 1.10.4 → 1.10.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.10.4",
+  "version": "1.10.7",
   "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();
@@ -4341,12 +4348,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 +5392,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) {
@@ -5503,7 +5563,42 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
         }
       }
     }
-    return null; // no remembered fact — the honest miss stands (never a guessed "no")
+    // Every yes-chase and the disjoint "no" above missed. The old
+    // unconditional decline here fell through to the structural "couldn't
+    // parse this as a graph question" wall — actively misleading for a KNOWN
+    // subject, twice over: the question DID parse, and the wall's hint
+    // suggests the exact shape the user just typed. When the subject has
+    // remembered isa-family facts, answer with an honest, specific miss that
+    // cites what IS remembered instead. An unknown subject still declines to
+    // the standing wall/teach-hint path — and this never guesses a "no".
+    // The SUBJECT'S OWN variants only — subjCandidates was augmented above
+    // with the graph entity's class noun (the CLASS↔INSTANCE bridge), and
+    // filtering on it here would cite facts about that noun ("class ⊑
+    // component") as if they were facts about the asked subject ("Widget").
+    const directSubjVariants = factTermVariants(normFactTerm, isaAsk[1]);
+    const knownSubjectIsa = isa.filter((f) => directSubjVariants.has(f.subject)).sort(byTrust);
+    const subjectWord = isaAsk[1].trim();
+    const kindWord = stripTrailingDiscourseTag(isaAsk[2]).trim();
+    if (knownSubjectIsa.length) {
+      const shown = knownSubjectIsa.slice(0, 3).map(renderFactLine).join("; ");
+      return {
+        text: `I can't confirm that — nothing I remember says ${subjectWord} is a ${kindWord}. I do know: ${shown}. If it's true, teach me: "${subjectWord} is a kind of ${kindWord}".`,
+        replace: true,
+        miss: true, // still a MISS in the turn record — honest wording, not an answer
+      };
+    }
+    // Subject with NO isa facts: only divert when it's mentioned NOWHERE at
+    // all (no fact row on either side, no code entity by id OR class noun) —
+    // a subject known via OTHER predicates ("ahab is male") or the code graph
+    // keeps the old decline, so nothing downstream is ever shadowed.
+    if (!ent && !noun && !rows.some((f) => subjCandidates.has(f.subject) || subjCandidates.has(f.object))) {
+      return {
+        text: `I can't confirm that — I don't know "${subjectWord}" at all yet. If it's true, teach me: "${subjectWord} is a kind of ${kindWord}".`,
+        replace: true,
+        miss: true,
+      };
+    }
+    return null; // the honest miss stands (never a guessed "no")
   }
 
   // (a1c-i) CARDINALITY MONOTONICITY — "does every X have at least N Y" over
@@ -7105,6 +7200,7 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     if (memoryDir) {
       bareMetaHit = (await factAnswer(memoryDir, gateQuery, envelope, miss, biasByBundle, cache))
         ?? (await factReadBack(memoryDir, gateQuery, envelope, miss, graph, newFocus?.label, biasByBundle, cache));
+      if (bareMetaHit?.miss) bareMetaHit = null; // an honest-miss return never diverts the gate
       // A bare "what is X" with NO taught fact but a KNOWN curated corpus term
       // ("what is cache", no article) needs the same "only diverts on a REAL
       // hit" treatment — curatedDefinitionAnswer otherwise only ever runs once
@@ -7175,8 +7271,14 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       ?? (await factReadBack(memoryDir, query, envelope, miss, graph, newFocus?.label, biasByBundle, cache));
     if (fact) {
       answer = fact.replace ? fact.text : `${answer}\n${fact.text}`;
-      via = "fact";
-      recordMiss = false;
+      // A fact-lane return flagged `miss` is an HONEST MISS in better words
+      // (the isa ladder's "I can't confirm that" closers) — the turn record
+      // keeps miss=true and via stays untouched, so miss-rate metrics and
+      // recall's own miss-gated lanes see it exactly like the wall it replaced.
+      if (!fact.miss) {
+        via = "fact";
+        recordMiss = false;
+      }
       if (fact.pending) factPending = fact.pending; // a truncated fact list → paginable remainder
       if (typeof fact.trust === "number") entailedTrust = fact.trust; // live-chase trust (see the `entailedTrust` declaration above)
       note(trace, `lane: (3) memory facts — factAnswer/factReadBack matched (memoryDir=${memoryDir})`);

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