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

package/src/domain/corpus-matrix.mjs

@@ -0,0 +1,87 @@
+// corpus-matrix.mjs — the fold and the two gap heuristics behind the
+// capability-by-lane coverage matrix, plus the table renderer. Pure: rows in,
+// counts and text out, so the heuristics can be tested against a handful of
+// made-up rows instead of whatever test/corpus happens to hold today.
+//
+// scripts/corpus-matrix.mjs keeps the readdir, the readFile and the printing.
+
+/** A row's capability group: the first two dot-segments of its key, so
+ *  "ask.alias.two-hop" and "ask.alias.miss" are one capability. */
+export const groupOfKey = (key) => key.split(".").slice(0, 2).join(".");
+
+/** The key a row is counted under. A row with no key is still a row, and
+ *  hiding it would understate the lane. */
+export const keyOfRow = (row) => String(row.key ?? "(no key)");
+
+/** A key segment naming a miss, a guard or a negation — the row that pins what
+ *  a capability DECLINES to do, as opposed to its happy path. */
+const NEGATIVE_RE = /(honest-miss|miss|guard|negation|negative|never|decline|refus|unsolvable|unknown|hedge|no-antecedent|untouched|empty)/;
+
+export const isNegativeKey = (key) => NEGATIVE_RE.test(key);
+
+/** Fold `{ lane, row }` pairs into the two indexes every view needs: the count
+ *  per group per lane, and the full keys each group was built from. */
+export function tallyRows(entries) {
+  const counts = new Map(); // group -> Map<lane, rowCount>
+  const fullKeys = new Map(); // group -> Set<full key>
+  for (const { lane, row } of entries) {
+    const key = keyOfRow(row);
+    const group = groupOfKey(key);
+    if (!counts.has(group)) counts.set(group, new Map());
+    const perLane = counts.get(group);
+    perLane.set(lane, (perLane.get(lane) ?? 0) + 1);
+    if (!fullKeys.has(group)) fullKeys.set(group, new Set());
+    fullKeys.get(group).add(key);
+  }
+  return { counts, fullKeys };
+}
+
+/** The groups the gap heuristics judge. bench.* rows assert a rig runs rather
+ *  than pinning a capability, so "no negative row" says nothing there. */
+export const behaviourGroups = ({ counts }) =>
+  [...counts.keys()].filter((g) => !g.startsWith("bench.")).sort();
+
+const rowTotal = (counts, group) => [...counts.get(group).values()].reduce((a, b) => a + b, 0);
+
+/** Groups a single row pins end to end. A review candidate, not a hole. */
+export function thinGroups(tally) {
+  return behaviourGroups(tally).filter((g) => rowTotal(tally.counts, g) === 1);
+}
+
+/** Groups whose keys never name a miss, guard or negation — a happy path is
+ *  pinned and the decline is not. A review candidate, not a hole. */
+export function groupsWithNoNegativeRow(tally) {
+  return behaviourGroups(tally).filter((g) => ![...tally.fullKeys.get(g)].some(isNegativeKey));
+}
+
+/** The lanes a group has rows in, in the order given. */
+export const lanesOfGroup = ({ counts }, group) => [...counts.get(group).keys()];
+
+/** One row per group, one column per lane, an empty cell where a lane has no
+ *  row for that group. The header row comes first. */
+export function matrixRows({ counts }, lanes) {
+  const groups = [...counts.keys()].sort();
+  return [
+    ["key", ...lanes],
+    ...groups.map((group) => [
+      group,
+      ...lanes.map((lane) => {
+        const n = counts.get(group).get(lane);
+        return n ? String(n) : "";
+      }),
+    ]),
+  ];
+}
+
+/** `rows` (header first) as fixed-width text, with a rule under the header.
+ *  Each column is as wide as its widest cell; trailing padding is trimmed. */
+export function renderTable(rows) {
+  const [header, ...body] = rows;
+  const widths = header.map((h, col) => Math.max(h.length, ...body.map((r) => r[col].length)));
+  const renderLine = (cells) => cells.map((c, col) => c.padEnd(widths[col])).join("  ").trimEnd();
+  return [
+    renderLine(header),
+    renderLine(widths.map((w) => "-".repeat(w))),
+    ...body.map(renderLine),
+  ].join("\n");
+}

package/src/domain/grammar/ace.mjs

@@ -8,7 +8,7 @@
 // punctuation, morphology is the lexicon's suffix fold.
 //
 // parseAce(sentence, lexicon) → { pattern, triples, residue } | null
-//   pattern  one of the PATTERNS below (also exported individually).
+//   pattern  one of the PATTERNS below.
 //   triples  [{ subject, predicate, object, kind, n? }] — OWL-labelled string
 //            triples shaped for src/adapters/memory/core.mjs's appendFact (which
 //            normalizes subject/object via normFactTerm: "tmct:module" is
@@ -36,18 +36,18 @@ import {
 // singularOnly below, and lexicon.mjs's lookupNoun doc for what this prunes).
 const SINGULAR_ONLY_DET = new Set(["a", "an"]);
 
-export const PATTERN_SUB_CLASS_OF = "subClassOf";
-export const PATTERN_TYPE_ASSERTION = "typeAssertion";
-export const PATTERN_RELATION = "relation";
-export const PATTERN_SOME_VALUES_FROM = "someValuesFrom";
-export const PATTERN_CARDINALITY = "cardinality";
-export const PATTERN_DISJOINT_WITH = "disjointWith";
-export const PATTERN_POSSESSIVE = "possessive";
-export const PATTERN_ADJECTIVE = "adjective";
-export const PATTERN_CAPABILITY = "capability";
+const PATTERN_SUB_CLASS_OF = "subClassOf";
+const PATTERN_TYPE_ASSERTION = "typeAssertion";
+const PATTERN_RELATION = "relation";
+const PATTERN_SOME_VALUES_FROM = "someValuesFrom";
+const PATTERN_CARDINALITY = "cardinality";
+const PATTERN_DISJOINT_WITH = "disjointWith";
+const PATTERN_POSSESSIVE = "possessive";
+const PATTERN_ADJECTIVE = "adjective";
+const PATTERN_CAPABILITY = "capability";
 
 /** The pattern field's full domain, in the README's table order. */
-export const PATTERNS = Object.freeze([
+const PATTERNS = Object.freeze([
   PATTERN_SUB_CLASS_OF, PATTERN_TYPE_ASSERTION, PATTERN_RELATION, PATTERN_SOME_VALUES_FROM,
   PATTERN_CARDINALITY, PATTERN_DISJOINT_WITH, PATTERN_POSSESSIVE, PATTERN_ADJECTIVE,
   PATTERN_CAPABILITY,

package/src/domain/grammar/lexicon.mjs

@@ -25,7 +25,7 @@
 import coreLexiconRaw from "./lexicon-core.json" with { type: "json" };
 
 /** The CURIE namespace every tmct lexicon mints terms under. */
-export const DEFAULT_NS = "tmct:";
+const DEFAULT_NS = "tmct:";
 
 /** Determiner tokens the grammar consumes (pattern table's every/a/no…). */
 export const DETERMINERS = Object.freeze({
@@ -160,7 +160,7 @@ export function lookupNoun(lexicon, word, opts = {}) {
 /** Every lexicon entry `word` could plausibly resolve to, ranked the same as
  *  lookupNoun's top choice but without discarding a genuine alternate (e.g.
  *  die/dice returns both entries). */
-export function lookupNounCandidates(lexicon, word, opts = {}) {
+function lookupNounCandidates(lexicon, word, opts = {}) {
   const w = String(word ?? "").toLowerCase();
   const standalone = lexicon.nouns.get(w);
   const irregular = lexicon.nounPlurals.get(w);
@@ -195,7 +195,7 @@ export function lookupVerb(lexicon, word) {
 
 /** Every verb entry `word` could plausibly resolve to via foldCandidates,
  *  most-specific-fold-first — the verb sibling of lookupNounCandidates. */
-export function lookupVerbCandidates(lexicon, word) {
+function lookupVerbCandidates(lexicon, word) {
   const w = String(word ?? "").toLowerCase();
   const out = [];
   const seen = new Set();

package/src/domain/inflect.mjs

@@ -0,0 +1,67 @@
+// inflect.mjs — the regular English -s/-ed/-ing rules, applied to a lemma.
+//
+// WordNet carries lemmas only ("rest" is present, "rests" is absent), and it is
+// the inflected forms that collide with the fuzzy repair tier's targets —
+// "rests" is one edit from "tests". So the real-word collision table expands
+// every lemma through these rules before it looks for collisions.
+//
+// These are the REGULAR rules and nothing else. No irregular table, no stress
+// model: pastOf("run") is "runned" and pastOf("make") is "maked". That is the
+// intended shape. The table's job is to name words the repair tier must not
+// rewrite, and inflectionsOf is generous on purpose (see below) — an extra form
+// costs one repair we decline to make, and the sentence misses honestly, while
+// a missing form costs a real word rewritten into a different question,
+// answered with confidence. The first is the cheaper mistake.
+
+import { STOPWORDS } from "./interpret/normalize.mjs";
+import {
+  FUZZY_TARGET_WORDS, FUZZY_REPAIR_MIN_LENGTH, fuzzyMatchInSet, fuzzyBound,
+} from "./interpret/fuzzy.mjs";
+
+const VOWELS = new Set(["a", "e", "i", "o", "u"]);
+const isVowel = (c) => VOWELS.has(c);
+
+/** A single final consonant after a single vowel doubles before -ed/-ing
+ *  ("run" -> "running"). w, x and y never double. Stress is not modelled, so a
+ *  second syllable doubles too ("visit" -> "visitting"). */
+export function doublesFinalConsonant(w) {
+  const [c3, c2, c1] = [w.at(-3), w.at(-2), w.at(-1)];
+  if (!c3 || isVowel(c1) || "wxy".includes(c1)) return false;
+  return isVowel(c2) && !isVowel(c3);
+}
+
+export function pluralOf(w) {
+  if (/(?:s|x|z|ch|sh)$/.test(w)) return `${w}es`;
+  if (/[^aeiou]y$/.test(w)) return `${w.slice(0, -1)}ies`;
+  return `${w}s`;
+}
+
+export function pastOf(w) {
+  if (w.endsWith("e")) return `${w}d`;
+  if (/[^aeiou]y$/.test(w)) return `${w.slice(0, -1)}ied`;
+  if (doublesFinalConsonant(w)) return `${w}${w.at(-1)}ed`;
+  return `${w}ed`;
+}
+
+export function gerundOf(w) {
+  if (w.endsWith("ie")) return `${w.slice(0, -2)}ying`;
+  if (w.endsWith("e") && !/(?:ee|oe|ye)$/.test(w)) return `${w.slice(0, -1)}ing`;
+  if (doublesFinalConsonant(w)) return `${w}${w.at(-1)}ing`;
+  return `${w}ing`;
+}
+
+/** Every surface form of `w` the collision table counts as real English. */
+export const inflectionsOf = (w) => [w, pluralOf(w), pastOf(w), gerundOf(w)];
+
+/** The words in `realWords` that the repair tier would rewrite onto one of its
+ *  targets: long enough to reach the tier, not a stopword, not a target itself,
+ *  and within the fuzzy bound of some target. Sorted, so the table it feeds is
+ *  reproducible. */
+export function collisionsFrom(realWords) {
+  return [...realWords]
+    .filter((w) => w.length >= FUZZY_REPAIR_MIN_LENGTH)
+    .filter((w) => !STOPWORDS.has(w))
+    .filter((w) => !FUZZY_TARGET_WORDS.includes(w))
+    .filter((w) => fuzzyMatchInSet(w, FUZZY_TARGET_WORDS, fuzzyBound(w)) !== null)
+    .sort();
+}

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/markdown-links.mjs

@@ -0,0 +1,55 @@
+// markdown-links.mjs — pull the relative link targets out of a markdown string.
+// Pure: a string in, `[{ target, line }]` out, no filesystem and no imports, so
+// the CI jobs that run without `npm ci` can reach it.
+//
+// Code is not prose. A doc that writes `[text](target)` inside backticks is
+// showing you what a link looks like, not making one, and a checker that cannot
+// tell the difference reports the example as a broken link to a file named
+// "target". So the spans are blanked before the link patterns run — blanked
+// rather than cut, because every offset behind them still has to name the right
+// line number.
+
+const blank = (line) => line.replace(/[^\n]/g, " ");
+const FENCE = /^[ \t]{0,3}(`{3,}|~{3,})/;
+
+/** Replace every fenced block and inline code span with spaces, keeping the
+ *  string's length and its newlines so later offsets still map to their line.
+ *  Fences are walked line by line: a lazy multiline regex stops at the end of
+ *  the opening fence's own line and blanks only the markers. */
+export function blankCodeSpans(markdown) {
+  let fence = null;
+  const lines = markdown.split("\n").map((line) => {
+    const marker = line.match(FENCE)?.[1];
+    if (fence) {
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+      return blank(line);
+    }
+    if (marker) fence = marker;
+    return marker ? blank(line) : line;
+  });
+  return lines.join("\n").replace(/(`+)[\s\S]*?\1/g, blank);
+}
+
+// Inline links/images: [text](target "title") — target ends at the first
+// whitespace or closing paren. Reference definitions: [label]: target.
+const INLINE_LINK = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const REFERENCE_DEF = /^\s{0,3}\[[^\]]+\]:\s+(\S+)/gm;
+
+/** Every repo-relative link target in `markdown`, with the 1-based line it sits
+ *  on. External URLs, bare #anchors and absolute paths are out of scope. */
+export function relativeTargets(markdown) {
+  const prose = blankCodeSpans(markdown);
+  const targets = [];
+  for (const regex of [INLINE_LINK, REFERENCE_DEF]) {
+    for (const match of prose.matchAll(regex)) {
+      let target = match[1];
+      if (/^(https?|mailto|ftp):/i.test(target)) continue;
+      if (target.startsWith("#") || target.startsWith("/") || target.startsWith("<")) continue;
+      target = decodeURIComponent(target.split("#")[0].split("?")[0]);
+      if (!target) continue;
+      const line = prose.slice(0, match.index).split("\n").length;
+      targets.push({ target, line });
+    }
+  }
+  return targets;
+}

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;
+}