@polycode-projects/the-mechanical-code-talker 2.2.0 → 2.3.1

package/src/domain/persona/codegen.mjs

@@ -0,0 +1,123 @@
+// codegen.mjs — renders a reviewed persona-tier worksheet as JS source, ready
+// to splice into corpus/tier2/generate.mjs's CORPUSES object, and as the
+// lexicon-core.json noun entries those facts need.
+//
+// Pure: worksheet in, source text out, no imports.
+
+export const CLUMP_ORDER = [
+  "human-core", "human-places", "human-objects", "human-nature",
+  "human-time-events", "human-body-food", "human-mind",
+];
+
+export const CLUMP_LABEL = {
+  "human-core": "people, family, common roles",
+  "human-places": "places",
+  "human-objects": "objects, clothing, tools",
+  "human-nature": "animals, plants, substances",
+  "human-time-events": "time and events",
+  "human-body-food": "body and food",
+  "human-mind": "communication, cognition, feeling",
+};
+
+// The irregular plurals among the words these batches introduce (Latin/Greek-
+// derived cognition/body/nature vocabulary especially). A word absent from this
+// map gets `{}` and relies on the regular -s/-es/-ies suffix fold at LOOKUP
+// time (src/domain/grammar/lexicon.mjs's foldCandidates), same as the vast
+// majority of Small tier's own additions. So this map is not a pluralizer: it
+// is the list of exceptions that folding cannot recover, and declaring a
+// regular plural here would be redundant.
+//
+// This is deliberately NOT src/domain/inflect.mjs's pluralOf, and the two must
+// not be merged. They answer opposite questions. pluralOf GENERATES candidate
+// surface forms for the real-word collision table, where over-generating is the
+// cheap mistake and its own header commits to regular rules only — it wants
+// "foots", because a form it fails to generate is a real word the repair tier
+// may rewrite into a different question. This map DECLARES the one correct
+// plural for a lexicon entry, where "foots" would simply be a lie the grammar
+// then trusts. Teaching pluralOf about "feet" would cost the collision table
+// "foots"; deriving this map from pluralOf would put "foots" in the lexicon.
+export const IRREGULAR_PLURALS = {
+  foot: "feet", tooth: "teeth", goose: "geese", ox: "oxen", die: "dice",
+  louse: "lice", mouse: "mice", crisis: "crises", analysis: "analyses",
+  hypothesis: "hypotheses", thesis: "theses", axis: "axes", basis: "bases",
+  oasis: "oases", criterion: "criteria", phenomenon: "phenomena",
+  alumnus: "alumni", cactus: "cacti", focus: "foci", radius: "radii",
+  fungus: "fungi", nucleus: "nuclei", stimulus: "stimuli", larva: "larvae",
+  alga: "algae", vertebra: "vertebrae", antenna: "antennae",
+  formula: "formulae", datum: "data", medium: "media", index: "indices",
+  matrix: "matrices", appendix: "appendices", curriculum: "curricula",
+  memorandum: "memoranda", millennium: "millennia", bacterium: "bacteria",
+  stratum: "strata", genus: "genera", species: "species", series: "series",
+  sheep: "sheep", deer: "deer", moose: "moose", salmon: "salmon",
+  trout: "trout", swine: "swine", offspring: "offspring", spacecraft: "spacecraft",
+  aircraft: "aircraft", scissors: "scissors", knife: "knives", wife: "wives",
+  life: "lives", leaf: "leaves", loaf: "loaves", thief: "thieves",
+  shelf: "shelves", elf: "elves", calf: "calves", half: "halves",
+  wolf: "wolves", self: "selves", woman: "women", man: "men",
+  child: "children", person: "people", tempo: "tempi",
+};
+
+/** One noun's lexicon-core.json entry: an explicit plural only where folding
+ *  could not recover it. */
+export function lexiconNounEntry(word) {
+  const plural = IRREGULAR_PLURALS[word];
+  return plural ? { plural } : {};
+}
+
+/** One clump's facts as indented JS array-literal source lines. */
+export function factsBlock(facts) {
+  return facts.map(([s, r, o]) => `      ["${s}", "${r}", "${o}"],`).join("\n");
+}
+
+/** A noun list wrapped at ~8 words/line, matching Small tier's own
+ *  lexicon-list style. */
+export function nounsListBlock(words) {
+  const lines = [];
+  for (let i = 0; i < words.length; i += 8) {
+    lines.push(`        ${words.slice(i, i + 8).map((w) => `"${w}"`).join(", ")},`);
+  }
+  return lines.join("\n");
+}
+
+/** One CORPUSES entry as JS source, for `id` ("human-medium"/"human-large")
+ *  from `byClump`, the reviewed worksheet's per-clump {facts, newNouns}. */
+export function buildCorpusEntry(id, tierLabel, byClump) {
+  const nounsSrc = CLUMP_ORDER.map((c) => `        // ${c} (+${byClump[c].newNouns.length} words: ${CLUMP_LABEL[c]})\n${nounsListBlock(byClump[c].newNouns)}`).join("\n");
+  const factsSrc = CLUMP_ORDER.map((c) => `      // ---- ${c} (+${byClump[c].facts.length} facts, ${tierLabel}) ----\n${factsBlock(byClump[c].facts)}`).join("\n\n");
+
+  return `
+  // ${tierLabel} tier — INCREMENTAL facts beyond ${id === "human-medium" ? "Small (corpus/tier2/human.jsonl)" : "Medium (corpus/tier2/human-medium.jsonl)"} only
+  // (PLAN_SEED.md §3's tier-selection design: Small/Medium/Large are SIZES of
+  // one bundle, not separate corpus ids — this file holds only what ${tierLabel}
+  // ADDS beyond the previous tier). Built by scripts/build-persona-tiers.mjs
+  // from the same two locally-cloned WordNet source files as Small
+  // (~/projects/globalwordnet/english-wordnet/src/yaml/), automatically
+  // curated: candidate words ranked by WordNet sense-count (a commonness
+  // proxy, PLAN_SEED.md §12), restricted to each word's own TOP senses (not
+  // some rare/slang meaning that happens to live in this domain), obscure/
+  // archaic/offensive/pharmaceutical content excluded via a definition-text
+  // blocklist plus an explicit word denylist, reviewed by hand before being
+  // spliced in here (scripts/apply-persona-tiers.mjs). ${id === "human-large" ? "Large's own facts walk real multi-hop hypernym chains (up to 4 hops, PLAN_SEED.md §3's own \"surgeon ⊑ doctor ⊑ … ⊑ person\" example) wherever WordNet's real structure supports it, not a flat one-hop-per-word cap." : "Medium stays flat, one hop per word, same style as Small."}
+  "${id}": {
+    kind: "domain",
+    description: "The ${tierLabel} tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond ${id === "human-medium" ? "Small" : "Medium"} only — activated alongside \\"human\\" via --persona-size ${id === "human-medium" ? "medium" : "large"}, never active by default.",
+    lexicon: {
+      nouns: [
+${nounsSrc}
+      ],
+    },
+    facts: [
+${factsSrc}
+    ],
+  },
+`;
+}
+
+/** The CORPUSES source with `entries` spliced in before its closing brace.
+ *  Throws when the anchor is absent rather than writing a mangled file. */
+export function spliceCorpusEntries(generateSrc, entries) {
+  const anchor = "\n};\n\nconst conceptUri = ";
+  const idx = generateSrc.indexOf(anchor);
+  if (idx === -1) throw new Error("apply-persona-tiers: could not find CORPUSES closing anchor in generate.mjs");
+  return generateSrc.slice(0, idx) + entries.join("") + generateSrc.slice(idx + 1);
+}

package/src/domain/persona/examples.mjs

@@ -0,0 +1,26 @@
+// examples.mjs — the two rules that decide whether a WordNet `example:` field
+// can serve as a persona example sentence, and what its text actually is.
+//
+// Pure: values in, values out, no imports.
+
+/** A handful of WordNet examples are cross-reference stubs ("see table 1"),
+ *  not real sentences. Filtering them keeps a re-run reproducing the committed
+ *  corpus/tier2/human-examples.jsonl exactly — this was the one candidate
+ *  dropped by hand when that file was first curated. */
+export const isRealSentence = (s) => !/^see\s+\w+\s*\d*\.?$/i.test(String(s).trim());
+
+/** A WordNet `example:` is usually a plain string, but a few are an ATTRIBUTED
+ *  LITERARY QUOTE — a `{source, text}` mapping, e.g. "ecstasy"'s example is
+ *  `{source: "Charles Dickens", text: "listening to sweet music…"}`. That shape
+ *  is real and was found live while extending coverage past Small tier's own
+ *  665-word list; none of Small's words happened to hit it, so it went uncaught
+ *  until Medium/Large's much wider coverage.
+ *
+ *  Returns the plain sentence text, or null for any other shape. The literary
+ *  source is real but this corpus wants a plain example sentence, not a
+ *  citation index. */
+export function normalizeExample(example) {
+  if (typeof example === "string") return example;
+  if (example && typeof example === "object" && typeof example.text === "string") return example.text;
+  return null;
+}

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));