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

package/src/domain/interpret/fuzzy.mjs

@@ -80,7 +80,7 @@ const REAL_WORD_COLLISIONS = new Set(collisionData.words);
  *  what it says, and if we don't record that relation the honest answer is a
  *  miss. Only the words the tier could actually reach are tabled; anything else
  *  never gets this far. */
-export const isRealEnglishWord = (w) => REAL_WORD_COLLISIONS.has(w);
+const isRealEnglishWord = (w) => REAL_WORD_COLLISIONS.has(w);
 
 /** A query word may be canonicalized only if it is plain alphabetic, not a
  *  stopword, and not already vocabulary. Dotted/digit terms (file names, shas)

package/src/domain/interpret/merge.mjs

@@ -123,7 +123,7 @@ export function mergeStrategyResults(results) {
  *  for alternateLines. Template only, reads straight off the parsed fields (the
  *  same discipline as ask.mjs's describeParse; callers with richer noun tables
  *  may pass their own describe). */
-export function describeAlternate(p) {
+function describeAlternate(p) {
   if (!p) return "something else";
   if (p.ambiguousParse) return "one of several readings";
   const obj = p.object ?? p.subject ?? "?";

package/src/domain/interpret/normalize.mjs

@@ -404,7 +404,7 @@ export function applyNegationFrames(text) {
 // Phrasing frames: route natural phrasings of a members-of-class or
 // where-defined question onto the canonical shape the grammar answers.
 // First match wins; run after applyNegationFrames.
-export const PHRASING_FRAMES = Object.freeze([
+const PHRASING_FRAMES = Object.freeze([
   // MEMBERS-of-class → "what does X contain".
   { re: /^what\s+(?:functions?|methods?|members?|attributes?|fields?|properties)\s+(?:are|is)\s+(?:in|inside|within)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `what does ${m[1]} contain` },
   { re: /^what\s+(?:functions?|methods?|members?|attributes?|fields?|properties)\s+(?:does|do)\s+(.+?)\s+have\??$/i, to: (m) => `what does ${m[1]} contain` },

package/src/domain/licences.mjs

@@ -0,0 +1,68 @@
+// licences.mjs — the allowlist, the SPDX expression rule, and the two pure
+// reads the licence check needs. Pure: objects and strings in, verdicts out, so
+// the rule that gates CI can be tested without an installed node_modules tree.
+//
+// The check itself (scripts/check-licences.mjs) shells out to `npm ls` and
+// reads each package's package.json off disk. That is the disk half. This is
+// the deciding half, and the deciding half is where the edge cases are.
+
+export const ALLOWED = new Set([
+  "MIT",
+  "ISC",
+  "BSD-2-Clause",
+  "BSD-3-Clause",
+  "Apache-2.0",
+  "MPL-2.0",
+  "0BSD",
+  "CC0-1.0",
+  "Unlicense",
+]);
+
+/** The licence `pkg` declares, across the three shapes npm has used: the
+ *  current string, the legacy `{ type }` object, and the legacy `licenses[]`
+ *  array (read as a choice, so it joins with OR). */
+export function licenseFromPackageJson(pkg) {
+  if (typeof pkg.license === "string") return pkg.license;
+  if (pkg.license && typeof pkg.license.type === "string") return pkg.license.type;
+  if (Array.isArray(pkg.licenses)) return pkg.licenses.map((l) => l.type).join(" OR ");
+  return "(none declared)";
+}
+
+/** True iff `license` is inside the allowlist.
+ *
+ *  A flat OR expression passes when any part is allowlisted, because OR is a
+ *  choice and we can take the allowlisted one. A flat AND expression needs
+ *  every part. Everything else — nesting, a WITH exception, an OR and an AND in
+ *  the same expression, even a redundantly parenthesised single licence like
+ *  "(MIT)" — returns false and gets reviewed by hand. Those are rare enough
+ *  that a parser would be more code than the reviews it saves, and false is the
+ *  safe direction: it stops CI and asks a human, rather than waving through an
+ *  expression it only half understood. */
+export function isAllowed(license) {
+  if (ALLOWED.has(license)) return true;
+  const inner = license.replace(/^\(/, "").replace(/\)$/, "");
+  if (/[()]|\bWITH\b/.test(inner)) return false;
+  if (inner.includes(" OR ") && !inner.includes(" AND ")) {
+    return inner.split(" OR ").some((part) => ALLOWED.has(part.trim()));
+  }
+  if (inner.includes(" AND ") && !inner.includes(" OR ")) {
+    return inner.split(" AND ").every((part) => ALLOWED.has(part.trim()));
+  }
+  return false;
+}
+
+/** Every installed package in an `npm ls --json` dependency tree, deduped by
+ *  name@version and sorted by name. A node with no `path` is a peer or optional
+ *  dependency that was never installed, so it cannot ship and is skipped. */
+export function installedPackages(deps) {
+  const seen = new Map();
+  (function walk(level) {
+    for (const [name, node] of Object.entries(level ?? {})) {
+      if (node && node.path && node.version) {
+        seen.set(`${name}@${node.version}`, { name, version: node.version, path: node.path });
+      }
+      if (node) walk(node.dependencies);
+    }
+  })(deps);
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/domain/memory/capability.mjs

@@ -55,7 +55,7 @@ export const NEG_CAPABLE_OF_PREDICATE = negatedPredicate(CAPABLE_OF_PREDICATE);
  *  order it lists them in. One constant each, in one place, so the verbosity of
  *  every case-4 answer is tuned by editing two lines. */
 export const CAPABILITY_REPORT_CAP = 6;
-export const byTrustThenName = (a, b) => (b.trust || 0) - (a.trust || 0) || String(a.subject).localeCompare(String(b.subject));
+const byTrustThenName = (a, b) => (b.trust || 0) - (a.trust || 0) || String(a.subject).localeCompare(String(b.subject));
 
 const asSet = (v) => (v instanceof Set ? v : new Set(Array.isArray(v) ? v : [v]));
 

package/src/domain/memory/trust.mjs

@@ -69,7 +69,7 @@ export const SOURCE_PRIOR = Object.freeze({
   entailed: 0.3,
 });
 
-export const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 export const RECENCY_FLOOR = 0.9; // recency multiplier stays within [0.9, 1.0]
 
 // Actor-level (session-scoped) trust — a bounded nudge on a Source's type
@@ -156,7 +156,7 @@ export function computeTrust(fact, sourcesById = {}, opts = {}) {
 
 // Laplace/"add-k" pseudo-count: without it a single data point would saturate
 // mgx:sourceReliability to the bare max/min immediately.
-export const RELIABILITY_CONFIDENCE_PSEUDOCOUNT = 19;
+const RELIABILITY_CONFIDENCE_PSEUDOCOUNT = 19;
 
 /** Pure actor-level reliability from a session's asserted-vs-contradicted
  *  track record (findContradictions, core.mjs), confidence-scaled by sample

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