@polycode-projects/the-mechanical-code-talker 2.0.3 → 2.3.0

package/src/domain/persona/tiers.mjs

@@ -0,0 +1,270 @@
+// tiers.mjs — the curation rules that build the Medium/Large persona tiers out
+// of real WordNet structure. No invented facts: every hop and every meronym is
+// a pointer WordNet already declares.
+//
+// Pure throughout — these read in-memory maps a caller loaded from disk, so
+// they are testable with no WordNet clone present. The loading lives in
+// src/adapters/wordnet-source.mjs, the fact targets and the run itself in
+// scripts/build-persona-tiers.mjs.
+
+// human-base's own category roots, plus every hypernym TARGET term Small's
+// curation already established as a "root" word (generate.mjs's own comment:
+// "category-root nouns used as a hypernym TARGET") — a real hypernym chain
+// walk stops here rather than continuing on to WordNet's ultra-abstract
+// "entity"/"abstraction"/"physical_entity" tops, which would add depth
+// without adding anything a plain-English question would ever ask about.
+export const STOP_SET = new Set([
+  "person", "place", "object", "event", "time", "quantity", "organization", "group",
+  "animal", "plant", "furniture", "vehicle", "insect", "emotion", "metal", "liquid",
+  "weather", "planet", "jewelry", "cutlery", "government", "material", "artifact",
+  "location", "structure", "food", "drink", "clothing", "body", "language", "mind",
+  "family", "meal", "season", "number", "entity", "abstraction", "physical_entity",
+  "attribute", "state", "act", "communication", "cognition", "measure", "unit",
+]);
+
+export const BLOCKLIST_RE = /\b(archaic|obsolete|offensive|derogatory|informal|slang|dialect|euphemism|hypothetical|imaginary|mythical|mythology|extraterrestrial|fictional|taxonomic genus|genus of|family [A-Z]|nonstandard|vulgar|disparaging|obscene|coarse|genital|ethnic slur|ethnic epithet|excrement|contemptuous|insulting|trade name|street name|controlled substance|illegal|sexual assault|monoclonal antibody|chemical compound|chemical formula|proprietary name)\b/i;
+
+// A short, explicit denylist for specific words WordNet's own definitions
+// don't reliably self-tag (the blocklist regex above misses some — e.g. the
+// "female genitals" sense of a common word is tagged only "obscene terms
+// for…", but the word itself has an unrelated clean sense too, so it isn't
+// caught by filtering on OTHER senses' definitions). Checked directly
+// against candidate headwords, not definitions.
+export const WORD_DENYLIST = new Set([
+  "cunt", "pussy", "dick", "cock", "prick", "twat", "boob", "tit", "tits",
+  "fuck", "shit", "piss", "bitch", "whore", "slut", "fag", "faggot", "nigger",
+  "nigga", "spic", "chink", "kike", "wetback", "retard", "cripple",
+  "asshole", "poop", "rape", "bastard",
+  // deictic/function words that happen to carry a marginal WordNet noun
+  // sense ("here" = "this place") — technically real, pragmatically not
+  // something a plain-English question would ever ask "what is X" about.
+  "here", "there", "somewhere", "elsewhere", "nowhere", "anywhere", "everywhere",
+  // Real, live test-fixture collisions (test/fixtures/entities.fixture.json's
+  // code-graph class/individual names double as ordinary WordNet-common
+  // words) — found by actually running the test suite against the first
+  // draft of this batch, not guessed in advance. "base"/"button" are
+  // exactly the kind of everyday-but-also-a-common-class-name word that
+  // will keep recurring as the persona vocabulary grows; excluded rather
+  // than editing the shared fixture (many other tests depend on its exact
+  // shape). "john" is also excluded on its own merits — WordNet's sense
+  // for it (a prostitute's customer) is exactly the "obscure/informal
+  // long-tail" this batch's curation is meant to skip, its own definition
+  // just doesn't happen to carry one of the blocklist's tag words.
+  "base", "button", "register", "john", "store",
+]);
+
+const WORD_RE = /^[a-z]+$/;
+
+const humanize = (term) => String(term).replace(/_/g, " ");
+
+/** Definition text of a synset (first line only — enough for the blocklist). */
+export function defOf(synset) {
+  return Array.isArray(synset?.definition) ? synset.definition[0] : synset?.definition || "";
+}
+
+/** Every word the lexicon already declares, across ALL THREE parts of speech,
+ *  plus the previous tier's own nouns.
+ *
+ *  Adjectives and verbs count, not just nouns: a word already declared as an
+ *  adjective (e.g. "male") must never ALSO become a noun. That was a real bug,
+ *  caught only by running the suite — the first pass added "male" as a noun
+ *  since WordNet legitimately has that sense too, which made ACE reclassify
+ *  "ahab is male" as class-membership (rdfs:subClassOf) instead of the intended
+ *  property fact (mgx:hasProperty), silently breaking every filter-rule test
+ *  built on "who is male". Nouns/verbs/adjectives are independent lookup maps
+ *  and a word CAN legitimately sit in two ("cook", "love" already do, noun +
+ *  verb), but a NEW second classification for an EXISTING word is never
+ *  introduced — only the word's original part of speech is authoritative. */
+export function declaredWords(lex, previousTierNouns = []) {
+  return new Set([
+    ...Object.keys(lex.nouns).map((w) => w.toLowerCase()),
+    ...Object.keys(lex.verbs).map((w) => w.toLowerCase()),
+    ...Object.keys(lex.adjectives).map((w) => w.toLowerCase()),
+    ...[...previousTierNouns].map((w) => w.toLowerCase()),
+  ]);
+}
+
+/** Walk UP a synset's hypernym chain from `synsetId`, resolving each
+ *  ancestor's member[0] term, to check membership of a "building-like" root
+ *  set (human-places' artifact-subtree filter) — up to 8 hops, memoized. */
+export function makeAncestorRootCheck(synsetMap, rootWords) {
+  const memo = new Map();
+  function isUnderRoot(id, depth = 0) {
+    if (depth > 8 || !id) return false;
+    if (memo.has(id)) return memo.get(id);
+    const s = synsetMap.get(id);
+    if (!s) { memo.set(id, false); return false; }
+    const members = (s.members || []).map((m) => m.toLowerCase());
+    if (members.some((m) => rootWords.has(m))) { memo.set(id, true); return true; }
+    const hyperId = Array.isArray(s.hypernym) ? s.hypernym[0] : null;
+    const result = hyperId ? isUnderRoot(hyperId, depth + 1) : false;
+    memo.set(id, result);
+    return result;
+  }
+  return isUnderRoot;
+}
+
+// A candidate is only accepted for a clump if the synset we found it in is
+// among the word's own TOP senses overall (its sense-rank in the entries
+// reverse index, 0-based) — otherwise a common, highly polysemous word
+// (e.g. "run", "light", "draw", "back") gets swept in via some rare/slang
+// sense that just happens to live in this domain ("light" = a friend,
+// "draw" = an entertainer), which is a genuinely obscure long-tail sense —
+// just obscure at the SENSE level rather than the word level. Top-3 senses
+// (rank <= 2) gives real latitude (a word's domain-relevant meaning is very
+// often sense 2 or 3, not always sense 1) while still excluding deep-tail
+// marginal senses.
+export const MAX_SENSE_RANK = 2;
+
+export function senseRank(word, synsetId, entriesIdx) {
+  const nounSenses = entriesIdx.get(word)?.senses?.n;
+  if (!nounSenses) return -1;
+  return nounSenses.findIndex((s) => s.synset === synsetId);
+}
+
+/** Candidate headwords from a set of synsets: up to 2 qualifying members per
+ *  synset (real WordNet synonyms, not invented) — word regex, length bound,
+ *  not blocklisted, not already used, and the synset must be among the
+ *  word's own top senses (see senseRank above). */
+export function collectCandidates(synsetEntries, usedWords, entriesIdx) {
+  const candidates = new Map(); // word -> first-seen synsetId (existence only)
+  for (const [id, synset] of synsetEntries) {
+    if (BLOCKLIST_RE.test(defOf(synset))) continue;
+    const members = synset.members || [];
+    let taken = 0;
+    for (const m of members) {
+      if (taken >= 2) break;
+      const w = String(m).toLowerCase();
+      if (!WORD_RE.test(w) || w.length < 2 || w.length > 16 || WORD_DENYLIST.has(w)) continue;
+      if (usedWords.has(w) || candidates.has(w)) continue;
+      const rank = senseRank(w, id, entriesIdx);
+      if (rank < 0 || rank > MAX_SENSE_RANK) continue;
+      candidates.set(w, id);
+      taken += 1;
+    }
+  }
+  return candidates;
+}
+
+/** Resolve a word to the SPECIFIC synset it was discovered under in the
+ *  clump's own source file(s) — deliberately NOT the entries index's
+ *  sense-1 (a word's globally-most-frequent sense across ALL of WordNet is
+ *  routinely a completely different domain than the clump it was found in —
+ *  e.g. "run" turning up as a noun.group.yaml member resolves, via a global
+ *  sense-1 lookup, to a baseball score, not anything group-related). The
+ *  entries index is used ONLY for the sense-count ranking heuristic
+ *  (rankCandidates), never for resolution. */
+export function resolveSynset(word, candidateSynsetId, synsetMap) {
+  const synset = synsetMap.get(candidateSynsetId);
+  if (!synset) return null;
+  return { synsetId: candidateSynsetId, synset };
+}
+
+// Chemical/pharmaceutical trade names (e.g. "methylenedioxymethamphetamine",
+// "infliximab") are almost always a single very long unbroken word with no
+// spaces — real everyday concepts, even multi-word ones ("medium of
+// exchange"), never have an individual token this long. A cheap, effective
+// shape filter: reject any candidate/hypernym/meronym TERM with a token over
+// 15 characters, independent of the definition-text blocklist (which these
+// technical entries routinely don't trip, since their definitions are
+// clinically neutral — "a monoclonal antibody used to treat…" carries none
+// of the archaic/slang/offensive keywords above).
+export const looksLikeCommonTerm = (term) => String(term).split(" ").every((tok) => tok.length <= 15);
+
+/** One real hypernym hop: [subjectTerm, "/r/IsA", hypernymTerm], plus the
+ *  next synset to continue from (or null at a stop/dead end/blocklisted
+ *  ancestor — a chain never walks INTO an obscure/archaic/mythical/technical
+ *  concept, even if the word that started the chain was clean). */
+export function nextHop(term, synsetId, synsetMap) {
+  const s = synsetMap.get(synsetId);
+  const hyperId = Array.isArray(s?.hypernym) ? s.hypernym[0] : null;
+  if (!hyperId) return null;
+  const hyper = synsetMap.get(hyperId);
+  if (BLOCKLIST_RE.test(defOf(hyper))) return null;
+  const hyperTerm = Array.isArray(hyper?.members) ? humanize(hyper.members[0]).toLowerCase() : null;
+  if (!hyperTerm || hyperTerm === term || !looksLikeCommonTerm(hyperTerm)) return null;
+  return { fact: [term, "/r/IsA", hyperTerm], nextSynsetId: hyperId, nextTerm: hyperTerm };
+}
+
+/** A real meronym-derived secondary fact for `synset`, preferring
+ *  mero_part > mero_member > mero_substance (word HasA part / HasA member /
+ *  MadeOf substance) — real WordNet pointers, never invented. */
+export function meronymFact(word, synset, synsetMap) {
+  const pick = (key, rel) => {
+    const ids = synset[key];
+    if (!Array.isArray(ids) || !ids.length) return null;
+    const target = synsetMap.get(ids[0]);
+    if (BLOCKLIST_RE.test(defOf(target))) return null;
+    const term = Array.isArray(target?.members) ? humanize(target.members[0]).toLowerCase() : null;
+    if (!term || term === word || !looksLikeCommonTerm(term)) return null;
+    return [word, rel, term];
+  };
+  return pick("mero_part", "/r/HasA") || pick("mero_member", "/r/HasA") || pick("mero_substance", "/r/MadeOf");
+}
+
+// Sense-count score, tie-broken by shorter word then alphabetically —
+// deterministic across re-runs (same inputs -> same output, no Math.random).
+export function rankCandidates(words, entriesIdx) {
+  return [...words].sort((a, b) => {
+    const sa = entriesIdx.get(a)?.total || 0;
+    const sb = entriesIdx.get(b)?.total || 0;
+    if (sb !== sa) return sb - sa;
+    if (a.length !== b.length) return a.length - b.length;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+/** Build one tier's incremental facts + new-noun list for one clump.
+ *  `candidatesMap` is word -> the SPECIFIC synset id it was discovered under
+ *  (from collectCandidates) — the actual resolution source (see
+ *  resolveSynset's doc comment); `entriesIdx` is used only for ranking. */
+export function buildClump(clumpId, candidatesMap, entriesIdx, synsetMap, target, usedWords, seenTriples, opts) {
+  const { maxHops } = opts;
+  const ranked = rankCandidates(candidatesMap.keys(), entriesIdx);
+  const facts = [];
+  const newNouns = [];
+  for (const word of ranked) {
+    if (facts.length >= target) break;
+    if (usedWords.has(word)) continue;
+    const resolved = resolveSynset(word, candidatesMap.get(word), synsetMap);
+    if (!resolved) continue;
+    const wordFacts = [];
+    let curTerm = word;
+    let curSynsetId = resolved.synsetId;
+    for (let hop = 0; hop < maxHops; hop += 1) {
+      const h = nextHop(curTerm, curSynsetId, synsetMap);
+      if (!h) break;
+      const key = `${h.fact[0]}|${h.fact[1]}|${h.fact[2]}`;
+      if (!seenTriples.has(key)) { wordFacts.push(h.fact); seenTriples.add(key); }
+      if (STOP_SET.has(h.nextTerm)) break;
+      curTerm = h.nextTerm;
+      curSynsetId = h.nextSynsetId;
+    }
+    const mero = meronymFact(word, resolved.synset, synsetMap);
+    if (mero) {
+      const key = `${mero[0]}|${mero[1]}|${mero[2]}`;
+      if (!seenTriples.has(key)) { wordFacts.push(mero); seenTriples.add(key); }
+    }
+    if (!wordFacts.length) continue; // every candidate hop/mero fact was already present elsewhere — skip
+    facts.push(...wordFacts);
+    newNouns.push(word);
+    usedWords.add(word);
+  }
+  return { facts, newNouns, clumpId, requested: target, got: facts.length };
+}
+
+/** Final safety net: a denylisted word (see WORD_DENYLIST) can still reach a
+ *  fact as a HYPERNYM/MERONYM TARGET (nextHop/meronymFact only check the
+ *  definition-text blocklist + the shape filter, not the explicit word list —
+ *  that list is deliberately checked here, once, against every final fact's
+ *  subject AND object, rather than duplicated at every resolution call site).
+ *  Drops the fact outright and prunes any newNoun left with no remaining
+ *  supporting fact (mirrors generate.mjs's own verifyLexiconAlignment
+ *  "orphaned metadata" check). */
+export function stripDenylisted(result) {
+  const hasDenied = (term) => term.split(" ").some((tok) => WORD_DENYLIST.has(tok));
+  const facts = result.facts.filter((f) => !hasDenied(f[0]) && !hasDenied(f[2]));
+  const survivingTerms = new Set(facts.flatMap((f) => [f[0], f[2]]));
+  const newNouns = result.newNouns.filter((w) => survivingTerms.has(w));
+  return { ...result, facts, newNouns, got: facts.length };
+}

package/src/domain/publish-gate.mjs

@@ -0,0 +1,41 @@
+// publish-gate.mjs — should this commit publish to npm? Pure: two version
+// strings in, a decision and a reason out, no imports, so CI can ask without
+// npm ci.
+//
+// CI asked this with `[ "$PUBLISHED" = "$LOCAL" ]`, which only answers "same".
+// A local version BELOW what npm already has — a revert, a bad merge, a branch
+// landing behind — reads as "different" and goes to `npm publish`, where the
+// registry rejects it and the job fails on a confusing error instead of a clear
+// skip. Equality cannot tell "ahead" from "behind"; comparing can.
+
+const CORE = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
+/** [major, minor, patch] for a semver string, or null if it isn't one. */
+function core(version) {
+  const found = CORE.exec(String(version ?? "").trim());
+  return found ? [Number(found[1]), Number(found[2]), Number(found[3])] : null;
+}
+
+/** -1 | 0 | 1 comparing the release cores of `a` and `b`. Pre-release and build
+ *  metadata are ignored: this gate decides whether a release moved, and 2.2.0
+ *  and 2.2.0-rc.1 are the same release for that purpose. */
+export function compareVersions(a, b) {
+  const [x, y] = [core(a), core(b)];
+  if (!x || !y) throw new Error(`not a comparable version: "${!x ? a : b}"`);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+/** Should `local` publish, given the registry currently serves `published`?
+ *  `published` is "none" when the package has never been published.
+ *  Returns { publish, reason } — the reason is what CI prints either way. */
+export function shouldPublish(local, published) {
+  if (!core(local)) throw new Error(`not a publishable version: "${local}"`);
+  if (published === "none" || published == null || published === "") {
+    return { publish: true, reason: `publishing ${local} (nothing published yet)` };
+  }
+  const order = compareVersions(local, published);
+  if (order === 0) return { publish: false, reason: `npm already has ${local} — no version bump in this push, skipping publish` };
+  if (order < 0) return { publish: false, reason: `local ${local} is BEHIND npm's ${published} — refusing to publish; the registry would reject it` };
+  return { publish: true, reason: `publishing ${local} (npm currently has ${published})` };
+}

package/src/domain/router/call-validator.mjs

@@ -1,5 +1,5 @@
 // src/domain/router/call-validator.mjs — pure registry validators shared by the
-// product router (resolver / guardrail / goal-reasoner) + the bench grader
+// product router (resolver / goal-reasoner) + the bench grader
 // (agentbench/grade.mjs re-exports these). Depends ONLY on registry.mjs — no
 // bench code — so the product←bench dependency stays inverted: the bench
 // imports the product, never the other way round. No I/O, no Date.now, no LLM.

package/src/domain/router/drive.mjs

@@ -1,7 +1,7 @@
 // src/domain/router/drive.mjs — the product-facing drive of the capability router: the
 // piece that turns a real English request into a real, executed answer over a
-// real repo graph. registry/resolver/planner/guardrail/goal-reasoner/
-// call-validator are all pure, deterministic decision machinery — this module
+// real repo graph. registry/resolver/planner/goal-reasoner/call-validator
+// are all pure, deterministic decision machinery — this module
 // is the thin, stateful shell around them that a CLI or chat surface calls:
 // build a { dispatch, resolve, graph } context against the repo's actual code
 // graph, then run a request through resolver -> planner -> goal-reasoner.
@@ -162,8 +162,7 @@ const WORLD_GOAL_RE = new RegExp(
  *  ground the move sequence by pure simulation over the taught rules
  *  (compileDomain + stateFromFacts + compileGoal + findActionPath — all
  *  read-only). Returned calls are NEVER dispatched: taught records carry
- *  readOnly:false / dispatchable:false, so the plan is simulated and chat's
- *  "next" executes move 1. Returns a loopResult, or null when the request is
+ *  readOnly:false, so the plan is simulated and chat's "next" executes move 1. Returns a loopResult, or null when the request is
  *  not a world-goal shape (the caller falls through to the goal-reasoner). */
 export async function runTaughtPlan(request, tools, ctx) {
   const m = WORLD_GOAL_RE.exec(String(request || "").trim());

package/src/domain/router/registry.mjs

@@ -1,15 +1,15 @@
 // src/domain/router/registry.mjs — the capability registry.
 //
 // 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; resolver.mjs backward-chains from
-// a goal to a capability whose add-list achieves it.
+// typed `Parameter`s, `Precondition`s, and `Effect`s (add-list/delete-list). resolver.mjs
+// backward-chains from a goal to a capability whose add-list achieves it, and proves the
+// preconditions bind before the call fires.
 //
 // Plain data + pure accessors, no I/O. Tool names + parameter arg keys are the
 // exact ones src/tools/server.mjs `dispatchTool` reads, so a bound call this registry validates is
 // directly dispatchable.
 
-export const PREFIXES = Object.freeze({
+const PREFIXES = Object.freeze({
   cap: "urn:tmct:cap#", // the capability/operator vocabulary (this module)
   mgx: "urn:tmct:mgx#", // tmct's code-graph predicates (imports/calls/tests/…)
   seon: "http://se-on.org/ontologies/seon.owl#", // software-evolution ontology classes
@@ -25,7 +25,7 @@ export const VOCAB = Object.freeze({
 
 // Parameter entity-KINDS — the seon/mgx classes a slot ranges over. `Query` and
 // `Kind`/`Package` are free-text / enum slots (no graph resolution); the rest
-// name a graph entity the guardrail must prove RESOLVES before the call fires.
+// name a graph entity the resolver must prove RESOLVES before the call fires.
 export const KINDS = Object.freeze({
   Symbol: "seon:CodeEntity", // any code symbol: function/method/class/module/attribute
   Module: "seon:Module",
@@ -196,11 +196,10 @@ function deepFreeze(value) {
 }
 
 /** Register a capability at runtime (e.g. a taught action family bridged in by
- *  src/domain/router/taught.mjs). `readOnly` must be an explicit boolean; a
- *  `readOnly: false` record is forced `dispatchable: false` — the guardrail's
- *  candidate enrichment re-dispatches a tool once per tied candidate, which is
- *  only safe when dispatch performs no writes. Returns an `unregister()`
- *  disposer. */
+ *  src/domain/router/taught.mjs). `readOnly` must be an explicit boolean: it is
+ *  what resolver.mjs's dispatch gate reads, and a `readOnly: false` record is
+ *  never dispatched. `dispatchable` is derived from it for callers that want the
+ *  record to state the conclusion. Returns an `unregister()` disposer. */
 export function registerCapability(cap) {
   const name = cap && typeof cap.name === "string" ? cap.name.trim() : "";
   if (!name) throw new Error("registerCapability: a non-empty name is required");
@@ -260,14 +259,14 @@ export function isCapability(n) { return Boolean(byName[n]); }
 /** The parameter slots of capability `n` (empty array if unknown/no-arg). */
 export function parametersOf(n) { return byName[n]?.parameters ?? []; }
 
-/** The preconditions of capability `n` (the safety gate the guardrail checks). */
+/** The preconditions of capability `n` (the safety gate the resolver checks). */
 export function preconditionsOf(n) { return byName[n]?.preconditions ?? []; }
 
 /** The effects of capability `n` — `{ add, del }` (the proof-chain contribution). */
 export function effectsOf(n) { return byName[n]?.effects ?? { add: [], del: [] }; }
 
-/** The set of arg keys capability `n` accepts (for the guardrail's unknown-arg
- *  check). Returns a Set of strings. */
+/** The set of arg keys capability `n` accepts (for call-validator.mjs's
+ *  unknown-arg check). Returns a Set of strings. */
 export function argKeysOf(n) {
   return new Set(parametersOf(n).map((p) => p.arg));
 }

package/src/domain/router/resolver.mjs

@@ -200,7 +200,7 @@ export function commandCapability(request, declaredNames, selectTool) {
 
 /** Build the glass-box proof chain for a grounded single call: its preconditions then the
  *  epistemic add-effect. Dispatch has succeeded, so `resolves` steps are ok. */
-export function proofFor(name, input) {
+function proofFor(name, input) {
   const steps = [];
   for (const pre of preconditionsOf(name)) {
     if (pre.pred === PRECOND.graphLoaded) steps.push({ step: "precondition", pred: pre.pred, ok: true });
@@ -213,11 +213,21 @@ export function proofFor(name, input) {
 
 const REFUSE = (why, extra) => ({ selected: null, refused: true, reason: why, ...(extra || {}) });
 
-/** Breadth-first ambiguity: dispatches the SAME tool once per tied candidate (safe since
- *  every registered capability is read-only). Returns `[{candidate, result}, ...]`, or
- *  undefined when there is no dispatcher to run it with. */
+/** The gate both dispatch sites below go through. Dispatching is an OBSERVATION, so it
+ *  may only ever run a capability whose own record says it performs no writes. A
+ *  world-mutating record (the ones src/domain/router/taught.mjs registers carry
+ *  `readOnly: false`) is planned over and simulated, never fired here. */
+function dispatchPerformsNoWrites(capName) {
+  return capabilityByName(capName)?.readOnly === true;
+}
+
+/** Breadth-first ambiguity: dispatches the SAME tool once per tied candidate, which only
+ *  stays safe while the tool writes nothing. Returns `[{candidate, result}, ...]`, or
+ *  undefined when there is no dispatcher to run it with — or when the capability is not
+ *  read-only. */
 async function dispatchEachCandidate(pool, capName, arg, ctx, execute) {
   if (!execute || !ctx.dispatch) return undefined;
+  if (!dispatchPerformsNoWrites(capName)) return undefined;
   const results = [];
   for (const c of pool) {
     const res = await ctx.dispatch(capName, { [arg]: c.label });
@@ -283,6 +293,9 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
   if (problems.length) return REFUSE(`bound call did not validate: ${problems.map((p) => p.reason).join(",")}`);
 
   if (execute && ctx.dispatch) {
+    if (!dispatchPerformsNoWrites(pick.name)) {
+      return REFUSE(`${pick.name} is not read-only; the resolver observes, it never fires a world-mutating capability`);
+    }
     const res = await ctx.dispatch(pick.name, input);
     if (!res.ok) return REFUSE(`unresolvable at dispatch: ${res.error}`);
     return { selected: call, proof: proofFor(pick.name, input), why, resolved: res.resolved ?? resolved, observed: String(res.text ?? "").slice(0, 240) };
@@ -293,7 +306,7 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
 // ---- reachability (used by the bidirectional conformance test + docs) ---------
 
 /** The epistemic topics some NL intent or imperative frame can reach. */
-export function nlReachableTopics() {
+function nlReachableTopics() {
   const topics = new Set();
   for (const v of Object.values(NL_INTENTS)) topics.add(v.topic);
   for (const f of FRAMES) topics.add(f.topic);

package/src/domain/router/results.mjs

@@ -147,7 +147,7 @@ export function callersLabels(graph, ind) {
 }
 
 /** Callees of a symbol (mirrors renderCallees). */
-export function calleesLabels(graph, ind) {
+function calleesLabels(graph, ind) {
   if (CALL_SYMBOL_CLASSES.has(ind.class)) {
     return uniqSort(edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object));
   }
@@ -157,7 +157,7 @@ export function calleesLabels(graph, ind) {
 }
 
 /** Subclasses (transitive) of a class (mirrors renderSubclasses closure). */
-export function subclassesLabels(graph, ind) {
+function subclassesLabels(graph, ind) {
   const inherits = edgesOfKind(graph, "inherits");
   const childrenOf = new Map();
   for (const e of inherits) {
@@ -198,7 +198,7 @@ export function cochangesLabels(graph, ind) {
 }
 
 /** A module's public exports (mirrors renderExports — the `reexports` edge). */
-export function exportsLabels(graph, ind) {
+function exportsLabels(graph, ind) {
   const modId = moduleIdOf(graph, ind);
   if (!modId) return [];
   return uniqSort(edgesOfKind(graph, "reexports").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object));

package/src/domain/router/taught.mjs

@@ -3,9 +3,10 @@
 // A taught game action ("you can move a disk onto a peg" + its preconditions
 // and effect) becomes a registered capability record so the router's operator
 // model covers taught actions and built-in query tools alike. Registered
-// records carry readOnly: false, so the guardrail never dispatches them — the
-// resolver also never selects them on its own, because it backward-chains over
-// `knows` add-effects and these records carry world-triple effects instead.
+// records carry readOnly: false, so the resolver's dispatch gate refuses to
+// fire them — and it never selects one on its own anyway, because it
+// backward-chains over `knows` add-effects and these carry world-triple
+// effects instead. They are planned over and simulated.
 
 import { capabilityByName, registerCapability } from "./registry.mjs";
 

package/src/domain/schemaorg/turtle.mjs

@@ -0,0 +1,25 @@
+// turtle.mjs — a very small Turtle reader for schema.ttl's OWN regular shape:
+// each class is one `:Name a rdfs:Class ;` block terminated by a line ending
+// in ` .`, with `rdfs:label`/`rdfs:comment`/`rdfs:subClassOf` as `;`-separated
+// predicate lines. Not a general Turtle parser — schema.ttl's own generator
+// emits a single, very regular style (confirmed by direct inspection).
+//
+// Pure: text in, Map out, no imports.
+
+/** Every rdfs:Class in `text`, as name -> { name, label, comment, subClassOf }.
+ *  A class with no rdfs:label falls back to its own name; no rdfs:comment
+ *  yields "". Blocks that are not classes (properties, say) are skipped. */
+export function parseSchemaClasses(text) {
+  const classes = new Map();
+  const blocks = text.split(/\n(?=:[A-Za-z])/); // each class/property starts a new top-level block
+  for (const block of blocks) {
+    const head = /^:([A-Za-z0-9_]+)\s+a\s+rdfs:Class\s*;/.exec(block);
+    if (!head) continue;
+    const name = head[1];
+    const label = /rdfs:label\s+"([^"]*)"/.exec(block)?.[1] || name;
+    const comment = /rdfs:comment\s+"([^"]*)"/.exec(block)?.[1] || "";
+    const subClassOf = [...block.matchAll(/rdfs:subClassOf\s+:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+    classes.set(name, { name, label, comment, subClassOf });
+  }
+  return classes;
+}

package/src/domain/semcor/parse.mjs

@@ -0,0 +1,87 @@
+// parse.mjs — a targeted reader for SemCor's own regular YAML shape:
+// flow-style lemmas/pos arrays and a folded single-quoted `text` scalar, one
+// record per sentence. Not a general YAML parser (this repo has no YAML
+// dependency), and not the same shape as the WordNet dump's reader in
+// src/domain/wordnet/yaml.mjs — SemCor's flow style is JSON-compatible once
+// isolated, which the WordNet subset never is.
+//
+// Pure: text in, arrays/strings out, no imports, so it runs with no SemCor
+// clone present.
+
+/** Split a SemCor YAML file into per-sentence record blocks (top-level
+ *  "<key>:" lines, skipping the leading "_meta:" schema block). */
+export function splitRecords(text) {
+  const lines = text.split("\n");
+  const blocks = [];
+  let i = 0;
+  while (i < lines.length && lines[i] !== "_meta:") i++;
+  i += 1;
+  while (i < lines.length && (lines[i].startsWith(" ") || lines[i].trim() === "")) i++; // skip rest of _meta
+  while (i < lines.length) {
+    if (/^[A-Za-z0-9_]+:$/.test(lines[i])) {
+      let j = i + 1;
+      const block = [];
+      while (j < lines.length && !/^[A-Za-z0-9_]+:$/.test(lines[j])) {
+        block.push(lines[j]);
+        j += 1;
+      }
+      blocks.push(block.join("\n"));
+      i = j;
+    } else {
+      i += 1;
+    }
+  }
+  return blocks;
+}
+
+/** Extract a flow-style JSON-compatible array value for `key` from one
+ *  record block (lemmas/pos are double-quoted string arrays — valid JSON
+ *  once isolated), balancing brackets across a line wrap if one occurs. */
+export function extractArray(block, key) {
+  const re = new RegExp(`^\\s*${key}:\\s*(\\[.*)$`, "m");
+  const m = re.exec(block);
+  if (!m) return null;
+  let buf = m[1];
+  let depth = (buf.match(/\[/g) || []).length - (buf.match(/\]/g) || []).length;
+  const afterIdx = block.indexOf(m[0]) + m[0].length;
+  const rest = block.slice(afterIdx).split("\n");
+  let ri = 0;
+  while (depth > 0 && ri < rest.length) {
+    buf += `\n${rest[ri]}`;
+    depth += (rest[ri].match(/\[/g) || []).length - (rest[ri].match(/\]/g) || []).length;
+    ri += 1;
+  }
+  try { return JSON.parse(buf); } catch { return null; }
+}
+
+/** Extract the `text:` folded single-quoted scalar (YAML's own `''` ->
+ *  literal `'` escape; line breaks folded to spaces). */
+export function extractText(block) {
+  const m = /^\s*text:\s*'/m.exec(block);
+  if (!m) return null;
+  const start = block.indexOf("'", m.index);
+  let i = start + 1;
+  let raw = "";
+  while (i < block.length) {
+    if (block[i] === "'") {
+      if (block[i + 1] === "'") { raw += "'"; i += 2; continue; }
+      break;
+    }
+    raw += block[i];
+    i += 1;
+  }
+  return raw.replace(/\s+/g, " ").trim();
+}
+
+export const NOUN_POS = new Set(["NN", "NNS"]);
+
+/** Simple-grammar filter: short, no semicolons/colons, no embedded quotes
+ *  (which signal reported speech), no more than one comma — a rough proxy for
+ *  "no complex embedded clauses". */
+export function isSimpleSentence(text, wordCount) {
+  if (wordCount > 18) return false;
+  if (/[;:]/.test(text)) return false;
+  if ((text.match(/,/g) || []).length > 1) return false;
+  if (/"/.test(text)) return false;
+  return true;
+}