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

package/src/tools/graph-load.mjs

@@ -11,10 +11,16 @@ export async function loadGraph(config, source) {
   if (!graph.individuals.length) {
     // Honest miss, never a stack: a fresh repo simply has no graph yet (the chat
     // session itself creates one as the conversation folds in).
-    throw new ToolError(
+    const e = new ToolError(
       `the graph at ${config.graphFile} is empty — no entities to answer from yet ` +
         "(this repo starts with no graph; the chat session folds the conversation into one).",
     );
+    // An empty CODE graph is not an empty world: a caller that can still answer
+    // from the lexicon, the corpus or taught memory reads this flag and carries
+    // on, rather than reporting the graph's emptiness to someone who never
+    // asked a structural question.
+    e.emptyGraph = true;
+    throw e;
   }
   return graph;
 }

package/src/tools/readme-docs.mjs

@@ -0,0 +1,113 @@
+// Render README.md's tool section from the tool definitions (src/tools/definitions.mjs),
+// which are the only place a tool's name, schema, purpose or example is written down.
+// scripts/generate-tool-docs.mjs reads and writes the README around this;
+// test/estate/tool-docs.test.mjs runs the same comparison, so a definition edited
+// without regenerating turns the suite red.
+import { HOT_TOOLS, COLD_TOOLS, TOOL_DEFINITIONS, askLexicon, toolByName } from "./definitions.mjs";
+
+export const BEGIN_MARKER = "<!-- generated by scripts/generate-tool-docs.mjs from src/tools/definitions.mjs — do not edit by hand -->";
+export const END_MARKER = "<!-- end generated tool section -->";
+
+/** An argument list read off a tool's schema: "`symbol` (required), `depth`". */
+function argsOf({ inputSchema }) {
+  const required = new Set(inputSchema.required || []);
+  const names = Object.keys(inputSchema.properties || {});
+  if (!names.length) return "none";
+  return names.map((n) => `\`${n}\`${required.has(n) ? " (required)" : ""}`).join(", ");
+}
+
+/** The README's tool section, rendered. Pure — the definitions are the only input. */
+export function renderToolDocs() {
+  const ask = toolByName("tmct_ask");
+  const out = [];
+
+  out.push("## The tool surface");
+  out.push("");
+  out.push(
+    `Everything above runs on the same ${TOOL_DEFINITIONS.length} tools. Each one is read-only, ` +
+      "answers one question in a single call, and returns bounded output. None of them " +
+      "calls a model. A tool that cannot ground an answer says so — the same honest miss " +
+      "you get everywhere else in tmct.",
+  );
+  out.push("");
+  out.push(
+    `Three of them are **hot**: their schemas stay resident, so an agent driving tmct sees ` +
+      "them every turn and reaches for one call instead of a Read/Grep loop.",
+  );
+  out.push("");
+  for (const t of HOT_TOOLS) {
+    out.push(`- **\`${t.name}\`** — ${t.summary}`);
+    out.push(`  Arguments: ${argsOf(t)}.`);
+  }
+  out.push("");
+
+  // ---- the chat-facing tool: its grammar, its lexicon, and worked examples ----
+  out.push("### Asking in plain English");
+  out.push("");
+  out.push(
+    "`tmct_ask` is the chat-facing tool. It takes a structural question as you would type " +
+      "it and resolves it to a real traversal. These are the shapes it reads:",
+  );
+  out.push("");
+  out.push("| you type | it answers with |");
+  out.push("| --- | --- |");
+  for (const g of ask.chat.grammar) out.push(`| ${g.example} | ${g.answers} |`);
+  out.push("");
+  out.push(
+    `The \`<where-marker>\` slot takes any of ${ask.chat.whereMarkers.map((m) => `*${m}*`).join(", ")}. ` +
+      "The relation verb is the part that carries the meaning, and each relation has its own " +
+      "vocabulary rather than one blessed keyword:",
+  );
+  out.push("");
+  for (const { kind, verbs } of askLexicon()) {
+    out.push(`- **${kind}** — ${verbs.map((v) => `*${v}*`).join(", ")}, and more`);
+  }
+  out.push("");
+  out.push("Every question in that table runs against the example graph:");
+  out.push("");
+  out.push("```bash cwd=repo");
+  for (const g of ask.chat.grammar) {
+    out.push(
+      `node bin/tmct.mjs cli tmct_ask '${JSON.stringify({ query: g.example, repo_path: ask.chat.exampleRepo })}'`,
+    );
+  }
+  out.push("```");
+  out.push("");
+
+  // ---- the cold tools ----
+  out.push("### The rest of the tools");
+  out.push("");
+  out.push(
+    "The remaining tools are **cold**: still served, but not billed to an agent every turn. " +
+      "Reach one through `tmct cli <tool>`, passing its arguments as JSON:",
+  );
+  out.push("");
+  out.push("| tool | what it answers | arguments |");
+  out.push("| --- | --- | --- |");
+  for (const t of COLD_TOOLS) out.push(`| \`${t.name}\` | ${t.summary} | ${argsOf(t)} |`);
+  out.push("");
+  out.push(
+    "Add `repo_path` to any of them to point at a repository other than the working " +
+      "directory. `tmct init` also writes this catalog, with a worked invocation per tool, " +
+      "to `.tmct/TOOLS.md` inside the repo it indexed.",
+  );
+  out.push("");
+  out.push("```bash cwd=repo");
+  out.push(`node bin/tmct.mjs cli tmct_untested '${JSON.stringify({ repo_path: "examples/mini-webapp" })}'`);
+  out.push("```");
+
+  return out.join("\n");
+}
+
+/** Splice the rendered section between the markers in `readme`. Throws when the
+ *  markers are missing, so a lost section fails loudly rather than appending a copy. */
+export function spliceToolDocs(readme, rendered) {
+  const begin = readme.indexOf(BEGIN_MARKER);
+  const end = readme.indexOf(END_MARKER);
+  if (begin === -1 || end === -1 || end < begin) {
+    throw new Error(`README.md is missing the generated tool-section markers (${BEGIN_MARKER})`);
+  }
+  const head = readme.slice(0, begin + BEGIN_MARKER.length);
+  const tail = readme.slice(end);
+  return `${head}\n\n${rendered}\n\n${tail}`;
+}

package/src/tools/schema-docs.mjs

@@ -154,10 +154,10 @@ export const PREDICATE_DOCS = Object.freeze([
   { prop: "seon:isConstant", kind: "attribute", description:
     "An ALL_CAPS module-level GlobalVariable — a naming-convention signal, not enforced " +
     "immutability." },
-  { prop: "seon:subKind", kind: "attribute", description:
+  { prop: "mgx:subKind", kind: "attribute", description:
     "The flavour of a Class define when it is not a plain class: interface, enum, struct " +
     "or record. The graph keeps kind=class for every type declaration; this attribute " +
-    "carries the distinction." },
+    "carries the distinction. A tmct extension — SEON has no subKind property." },
   { prop: "seon:hasAccessModifier", kind: "attribute", description:
     "Visibility inferred from a leading underscore (private/protected); a public member " +
     "carries no value for this attribute." },

package/ROADMAP.md

@@ -1,129 +0,0 @@
-# ROADMAP — tmct's current shape and what's next
-
-Forward-looking at a **feature level**: what tmct is capable of right now, and what's planned next.
-No session narrative, no dated diary, no "shipped/DONE" history — that's what git log and the
-`archive/`/`BENCHMARK_*.md`/`CAPABILITIES_*.md` records are for. For **task-level** pickup (specific
-open items, session-scoped), see `HANDOVER.md` instead — this file doesn't duplicate that list.
-
-## What tmct is
-
-A tolerant, ELIZA/PARRY-style chat surface over a codebase, obsessed with software the way PARRY was
-obsessed with the mafia — deterministic, zero-cost, **no LLM anywhere in the product path**. Guides a
-user toward precision queries rather than guessing; every answer is grounded, restates every genuine
-reading it finds in full, or is an honest miss when nothing grounds it at all. Its visual surfaces —
-the ledger explorer with its in-browser chat (`tmct viz`), the animated plan page
-(`chat --prompt … --render blocks`), and the Pages homepage hero — are the same graph read out loud:
-same engine, same provenance, no LLM.
-
-## Ambition
-
-Declared, forward-looking goals — not yet achieved, stated here so they steer future work instead of
-getting silently traded away by inherited caution:
-
-- **Reach for Llama-3-level natural language fluency.** by growing rich
-  template/surface-realization variety, so an answer shape has many valid phrasings instead of one
-  fixed slot-fill.
-- **Resolve ambiguity breadth-first, always.** Every genuinely valid reading gets its own real answer
-  restated in full, never a bare "could mean X or Y — try rephrasing" punt, bounded only by existing
-  clipping/pagination limits. L
-- **Paraphrase alongside the original, verified, never instead of it.** A surface-realization variant
-  sits next to the literal grounded answer, never replacing it, and its accuracy is checked, not
-  assumed — by running tmct's own deterministic inference/consistency machinery (`src/domain/syllogise.mjs`)
-  against both the original and the paraphrase: they must entail the same conclusions, and neither may
-  contradict the other sentence-by-sentence..
-
-
-## What's next (feature-shaped — see `HANDOVER.md` for the current task-level list)
-
-- **`PLAN_ADVENTURE.md`** — a text-adventure architectural stretch. Its world-state and
-  actions-as-data substrate shipped generically with the planning lane (action rule kinds,
-  per-step board snapshots, legal-move enumeration); what remains its own is the imperative
-  command grammar ("go north", "take the key"), the NPC turn scheduler, the Ashcombe Hall
-  corpus, and the room-look digest.
-- **`PLAN_SYLLOGIST.md`** — the reasoning engine's research horizon. The single-justification
-  retraction slice shipped (`retractSubClassOf`, justification persistence and cascade across all
-  five rules); still open there: the ATMS generalization (alternate justification sets per fact),
-  incremental matching (§2), and relevance under budget (§4).
-- **`PLAN_GUESS_NUMBER.md`** — closed-loop planning over hidden state (belief-interval bisection,
-  thinker-mode secret commitment, observation folding) on top of the shipped planner substrate.
-  Design-only.
-- **`PLAN_CODE.md`** — small JS-function and HTML/CSS-fragment synthesis, plus goal-directed
-  program repair (tests as the goal state, mutation templates as planning actions), via a sandboxed
-  headless browser (Track 1, rule/frame synthesis, already shipped). Blocked on a sandbox
-  dependency decision.
-- **`PLAN_AGENTS.md`** — the governing plan for tmct's broader multi-repo arc (marginalia, seonix,
-  a pluggable LLM rung for Claude Code/Bedrock/Copilot). Check its own sequencing table for current
-  phase status, not this file.
-
-
-## Research horizon
-
-*(2026-07-08 research pass — a direction recorded so it isn't re-discovered from scratch, not a
-committed build plan. Nothing below is scheduled.)*
-
-**Before the horizon — known-how, no research risk**, just scheduling: `PLAN_CODE.md` Tracks 2-4
-(mutation search/repair, JS/HTML/CSS synthesis — APR and CEGIS are established techniques);
-RETE/incremental forward-chaining (`PLAN_SYLLOGIST.md` §2 — Forgy 1982, a citable algorithm not yet
-ported); contingent/conformant planning under initial-state uncertainty (Bonet & Geffner 2000,
-Hoffmann & Brafman 2006, Petrick & Bacchus 2002 all have working algorithms, none yet applied here).
-
-**After the horizon — genuinely unsolved in the field**, named as real research targets with
-citations, not stop signs:
-- **The frame problem / relevance realization** (open-world planning boundary). McCarthy & Hayes
-  1969 named it; Jaeger, Riedl, Djedovic, Vervaeke & Walsh (2024) argue it may not be algorithmically
-  solvable in the general case. Speculative angle: bounded (N+1) goal recognition — recognize
-  declared goal 1..N, or reject to an explicit "escalate" class, via parse-shape membership.
-- **Bounded, incremental, trust-tiered, retraction-safe justification tracking** — `PLAN_SYLLOGIST.md`
-  §3. Doyle's JTMS (1979) and de Kleer's ATMS (1986) solve retraction; DRed/RDFox's Backward-Forward
-  solve incremental Datalog maintenance; nobody's published the combination with tmct's
-  multi-trust-tier, hard-budget requirement. The JTMS-lite slice shipped (one persisted
-  justification per entailed fact, VERIFY-backed retraction, all five rules); the open piece is the
-  ATMS generalization — alternate justification SETS per fact (see that doc's 2026-07-15 addendum).
-- **A shared ~2M-word cross-domain ontology** (general-English + technical/scientific/programming).
-  Merging collides senses of lexically-shared words (`class`, `cache`, `thread`, `field`, `state`)
-  across registers; knowledge-based WSD is real but weaker than supervised/neural WSD (Lesk 1986;
-  Raganato, Camacho-Collados & Navigli, EACL 2017). BabelNet proves cross-resource sense merging is
-  achievable at scale but solves the cross-*lingual*, not cross-*domain*, axis, and carries a
-  non-commercial licence. Speculative angle: mutual disambiguation from already-resolved neighbouring
-  terms in tmct's own closed graph (a bounded reading of Gale/Church/Yarowsky's "one sense per
-  discourse" regularity) — not published anywhere found for this application. Fresh live instance
-  (2026-07-11): `"tail"` (Unix process vs. animal body part) collides under `normFactTerm`'s
-  cross-corpus flattening, `src/adapters/memory/core.mjs:1109-1134`.
-
-**Tier-4: learn-on-miss acquisition**. The strongest
-miss signal tmct can emit: lexicon term recognized, query built cleanly, zero matches anywhere — the
-question was well-formed and the knowledge is simply absent. Web search on the resolved term → clean
-the fetched text into the ACE-OWL controlled grammar → store with source provenance → answer the
-original question, citing what was just learned. Strictly opt-in, offline default inviolable.
-Prerequisites: the provenance-trust policy must extend to `via:"learned:web"`, never silently
-blending web-sourced facts with graph/operator facts.
-
-## Design docs
-
-Every substantial design lives in its own `PLAN_*.md` at the repo root; `archive/` holds the shipped
-and closed ones. This file points to them, it doesn't repeat their content. Each plan states its own
-status in its opening lines — read it there, because a status quoted here would rot.
-
-| Plan | What it's for |
-| --- | --- |
-| [PLAN_ADVENTURE.md](PLAN_ADVENTURE.md) | a text adventure as an architectural stretch: imperative command grammar, NPC turn scheduler, room-look digest |
-| [PLAN_AGENTS.md](PLAN_AGENTS.md) | the governing plan for the multi-repo arc (marginalia, seonix, a pluggable LLM rung), with its own phase sequencing |
-| [PLAN_CHILD_CORPUS.md](PLAN_CHILD_CORPUS.md) | a wider default seed corpus, chosen by age of acquisition |
-| [PLAN_CLASS_QUERY.md](PLAN_CLASS_QUERY.md) | "list/count all X of class Y", reconciled against what already shipped |
-| [PLAN_CODE.md](PLAN_CODE.md) | program synthesis over tmct's closed DSLs, plus JS/HTML/CSS fragments and goal-directed program repair |
-| [PLAN_CONSISTENCY_CHECK.md](PLAN_CONSISTENCY_CHECK.md) | tmct as a consistency service for an LLM tool loop |
-| [PLAN_EMBEDDINGS.md](PLAN_EMBEDDINGS.md) | the semantic-similarity axis, and the way back to it |
-| [PLAN_GRAPH_SCAN.md](PLAN_GRAPH_SCAN.md) | seed and query cost at `init:xl`/`init:xxl` corpus scale |
-| [PLAN_GUESS_NUMBER.md](PLAN_GUESS_NUMBER.md) | closed-loop planning over hidden state, via belief-interval bisection |
-| [PLAN_MUD.md](PLAN_MUD.md) | persistent, shared tmct worlds over a `server:` memory backend |
-| [PLAN_NLU_BENCHMARKS.md](PLAN_NLU_BENCHMARKS.md) | scoring tmct on the CLINC150 and HWU64 intent sets |
-| [PLAN_OPEN_ITEMS.md](PLAN_OPEN_ITEMS.md) | the build order closing the backlog `HANDOVER.md` carries |
-| [PLAN_PARAPHRASE_VERIFICATION.md](PLAN_PARAPHRASE_VERIFICATION.md) | checking a paraphrase against the graph before it prints |
-| [PLAN_PURGE.md](PLAN_PURGE.md) | promote the load-bearing code, delete the dead weight |
-| [PLAN_REPO_INDEX.md](PLAN_REPO_INDEX.md) | tmct grows its own code parsers, ported from seonix |
-| [PLAN_SYLLOGIST.md](PLAN_SYLLOGIST.md) | the reasoning engine's incrementality and retraction horizon |
-| [PLAN_SYLLOGIST_EL_DL.md](PLAN_SYLLOGIST_EL_DL.md) | beyond OWL 2 RL: an EL classifier, then a DL tableau prover |
-
-`SKILL_*.md` docs specify the repeatable measurement and build cycles (the benchmarks, the capability
-audit, the background strategy advisor, plain-prose writing). `HANDOVER.md` is the single
-current-open-items list.

package/corpus/namenet/generate.mjs

@@ -1,309 +0,0 @@
-#!/usr/bin/env node
-// corpus/namenet/generate.mjs — converts THREE reviewed CSVs from a LOCAL
-// Open English Namenet checkout into ConceptNet-shape fact rows. Mirrors
-// corpus/wordnet/generate.mjs's structure/conventions exactly (same
-// maintainer-tool framing, same deterministic sorted JSONL + manifest.json
-// output shape) — smaller scope, OPTIONAL top-up, not load-bearing.
-//
-//   node corpus/namenet/generate.mjs [namenetDir]
-//   TMCT_NAMENET_DIR=/path/to/english-namenet node corpus/namenet/generate.mjs
-//
-// Input: `~/projects/globalwordnet/english-namenet/` by default (a LOCAL
-// clone, never vendored/committed) — three reviewed CSVs, each a
-// human/algorithm-curated LINKING TABLE between a name/label and an Open
-// English WordNet (OEWN) synset or lemma set:
-//   - species_reviewed.csv        (5,101 rows) — Scientific Name -> SSID
-//   - taxon2common_reviewed.csv   (2,368 rows) — SSID 1/Lemmas 1 -> SSID 2/Lemmas 2
-//   - linked_occupations_reviewed.csv (2,193 rows) — Wikidata Labels -> SSID/Lemma
-// Every one of the three, once you read real rows (not just the header),
-// turns out to be the SAME shape underneath: two name-lists that denote the
-// SAME real-world thing (a species, a folk-taxonomic category, an
-// occupation), reviewed/accepted by a human as a correct link — never a
-// hierarchy (broader/narrower) or capability claim. That is why every fact
-// this converter emits uses ONE relation, /r/Synonym ("X means the same as
-// Y") — confirmed against conceptnet-map.toml (ace != "none", Phase 1's
-// 2026-07-12 widening) rather than invented here (this task's own scope
-// boundary: conversion only, reuse what Phase 1 already mapped, never add a
-// new relation row).
-//
-// Why NOT /r/IsA or /r/CapableOf (the task brief's own initial guesses,
-// before real rows were read):
-//   - species_reviewed.csv: real rows show the "Scientific Name" is almost
-//     always ALREADY one of the target SSID's own WordNet members (4,885 of
-//     4,897 accepted rows resolve to a real synset; of those, 4,881 have the
-//     scientific name as a literal member string) — this is a same-referent
-//     alias table (which of several ambiguous WordNet senses a Wikidata
-//     taxon QID actually means), not a species/kind subclass relation.
-//   - linked_occupations_reviewed.csv: despite the CSV's name, each row
-//     links a WIKIDATA OCCUPATION ENTITY's labels to a WORDNET OCCUPATION
-//     SYNSET's lemmas (e.g. "politician, political leader" <-> "pol,
-//     political leader, politician, politico") — it is NOT a person linked
-//     to their job (no person names anywhere in this file), so /r/CapableOf
-//     ("a person can politician") would be nonsensical. It is the same
-//     alias-table shape as the other two.
-//
-// species_reviewed.csv needs a SECOND local checkout to resolve: its SSID
-// column has no lemma text of its own (unlike the other two, which carry
-// "Lemmas N" columns directly), so this converter reuses
-// corpus/wordnet/generate.mjs's already-proven `loadAllSynsets`/
-// `DEFAULT_YAML_DIR`/`encodeTerm`/`humanize` (imported, never duplicated —
-// same discipline that file's own header comment describes for its
-// hand-rolled YAML reader) to resolve SSID -> representative lemma.
-// corpus/wordnet/generate.mjs itself is never modified (task scope
-// boundary) — only its exported pure functions are called.
-//
-// NOT part of the product path — a maintainer tool, run by hand, offline,
-// $0; its OUTPUT (corpus/namenet/namenet.jsonl + manifest.json) is what gets
-// committed, never the source CSVs themselves.
-//
-// Licence: see LICENSE-NOTICE in this directory — the source repository
-// (globalwordnet/english-namenet) declares NO explicit license of its own
-// (confirmed via GitHub repo metadata, 2026-07-12: `license: null`, no
-// LICENSE file, no license statement in README.md); this bundle is
-// distributed under CC-BY-4.0 as a conservative match to the Open English
-// WordNet data it is built from and links against, pending clarification
-// from the GlobalWordNet team. The code in this file is tmct code under the
-// repository's MPL-2.0; only the generated data
-// (corpus/namenet/namenet.jsonl) carries that CC-BY-4.0 label.
-
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { homedir } from "node:os";
-import { createHash } from "node:crypto";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { loadAllSynsets, DEFAULT_YAML_DIR, resolveYamlDir, encodeTerm, humanize } from "../wordnet/generate.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-export const NAMENET_OUT_DIR = HERE;
-
-export const DEFAULT_NAMENET_DIR = join(homedir(), "projects", "globalwordnet", "english-namenet");
-
-/** Resolve the input namenet directory: CLI positional arg > env var >
- *  default. Pure (argv/env injectable), mirrors wordnet's resolveYamlDir. */
-export function resolveNamenetDir(argv = process.argv.slice(2), env = process.env) {
-  return argv[0] || env.TMCT_NAMENET_DIR || DEFAULT_NAMENET_DIR;
-}
-
-// ---- CSV parsing (pure, unit-tested) ---------------------------------------
-// A small hand-rolled RFC4180-ish reader — no dependency added, same house
-// style as corpus/wordnet/generate.mjs reusing a hand-rolled YAML reader
-// rather than pulling in a general parsing library. Handles quoted fields
-// (commas/newlines inside quotes, "" as an escaped literal quote) and both
-// CRLF and LF line endings — all three source CSVs use quoted fields for any
-// value containing a comma (e.g. `"species, by Garsault, 1764..."`), so a
-// naive `.split(",")` silently misaligns columns on those rows.
-
-/** Parse CSV text into an array of records (arrays of string fields). */
-export function parseCsvRecords(text) {
-  const records = [];
-  let row = [];
-  let field = "";
-  let inQuotes = false;
-  const pushField = () => { row.push(field); field = ""; };
-  const pushRow = () => { pushField(); records.push(row); row = []; };
-  const src = String(text ?? "");
-  for (let i = 0; i < src.length; i++) {
-    const c = src[i];
-    if (inQuotes) {
-      if (c === '"') {
-        if (src[i + 1] === '"') { field += '"'; i++; }
-        else inQuotes = false;
-      } else {
-        field += c;
-      }
-      continue;
-    }
-    if (c === '"') { inQuotes = true; continue; }
-    if (c === ",") { pushField(); continue; }
-    if (c === "\r") continue; // CRLF -> swallow, \n below ends the row
-    if (c === "\n") { pushRow(); continue; }
-    field += c;
-  }
-  // final field/row, if the text didn't end with a newline
-  if (field !== "" || row.length) pushRow();
-  // drop a single trailing wholly-empty record (trailing newline artifact)
-  if (records.length && records[records.length - 1].every((f) => f === "")) records.pop();
-  return records;
-}
-
-/** Parse CSV text into an array of row objects keyed by the header row. */
-export function parseCsv(text) {
-  const records = parseCsvRecords(text);
-  if (!records.length) return [];
-  const header = records[0].map((h) => h.trim());
-  return records.slice(1).map((rec) => {
-    const obj = {};
-    for (let i = 0; i < header.length; i++) obj[header[i]] = rec[i] ?? "";
-    return obj;
-  });
-}
-
-/** "Plantae, kingdom Plantae, plant kingdom" -> "Plantae" — the first
- *  candidate in a comma-separated lemma/label list, the same "first member is
- *  representative" convention corpus/wordnet/generate.mjs's repTerm() uses. */
-export function firstOf(commaList) {
-  const s = String(commaList ?? "").trim();
-  if (!s) return null;
-  const first = s.split(",")[0].trim();
-  return first || null;
-}
-
-// ---- shared row builder (pure) ---------------------------------------------
-// Same dedupe-by-key + self-loop-skip discipline as corpus/wordnet/
-// generate.mjs's makeRowBuilder — re-declared locally (not imported; that
-// function isn't exported, and this is a small enough shape to keep local
-// rather than widen wordnet/generate.mjs's exports for a five-line helper).
-
-function makeRowBuilder() {
-  const rows = new Map();
-  const add = (rawSubject, rel, rawObject) => {
-    const start = encodeTerm(rawSubject);
-    const end = encodeTerm(rawObject);
-    if (!start || !end || start === end) return; // self-loop / empty term — noise, not a fact
-    const key = `${rel} ${start} ${end}`;
-    if (rows.has(key)) return;
-    rows.set(key, {
-      start,
-      rel,
-      end,
-      weight: 1,
-      surfaceText: `[[${humanize(rawSubject)}]] ${rel.replace("/r/", "")} [[${humanize(rawObject)}]]`,
-    });
-  };
-  return { rows, add };
-}
-
-const sortRows = (rows) => rows.slice().sort((a, b) => (
-  a.rel !== b.rel ? (a.rel < b.rel ? -1 : 1)
-    : a.start !== b.start ? (a.start < b.start ? -1 : 1)
-      : a.end < b.end ? -1 : a.end > b.end ? 1 : 0
-));
-
-// ---- per-source mappers (pure, unit-tested) --------------------------------
-
-/** species_reviewed.csv: accepted rows only; the Scientific Name and the
- *  SSID's representative WordNet lemma denote the same species -> /r/Synonym.
- *  `bySynset` is the same `Map<synsetId, {members}>` shape
- *  corpus/wordnet/generate.mjs's loadAllSynsets returns (or a small fixture
- *  Map in tests) — a row whose SSID isn't in the map is skipped, not thrown. */
-export function buildSpeciesFacts(rows, bySynset) {
-  const { rows: out, add } = makeRowBuilder();
-  for (const row of rows) {
-    if (row.Accept !== "TRUE") continue;
-    const sciName = row["Scientific Name"];
-    const ssid = row.SSID;
-    if (!sciName || !ssid) continue;
-    const synset = bySynset.get(ssid);
-    const members = Array.isArray(synset?.members) ? synset.members : [];
-    if (!members.length) continue; // unresolved SSID — skip, don't throw
-    add(sciName, "/r/Synonym", members[0]);
-  }
-  return sortRows([...out.values()]);
-}
-
-/** taxon2common_reviewed.csv: accepted rows only; the first lemma of each
- *  side's "Lemmas N" list denotes the same taxonomic/folk category ->
- *  /r/Synonym. No cross-reference needed — both lemma lists are already
- *  columns in this CSV. */
-export function buildTaxon2CommonFacts(rows) {
-  const { rows: out, add } = makeRowBuilder();
-  for (const row of rows) {
-    if (row.Accept !== "TRUE") continue;
-    const a = firstOf(row["Lemmas 1"]);
-    const b = firstOf(row["Lemmas 2"]);
-    if (!a || !b) continue;
-    add(a, "/r/Synonym", b);
-  }
-  return sortRows([...out.values()]);
-}
-
-/** linked_occupations_reviewed.csv: accepted, genuine-occupation rows only
- *  (`Accept === "TRUE"` AND `"Not an occupation" !== "TRUE"`); the first
- *  Wikidata label and the first WordNet lemma denote the same occupation ->
- *  /r/Synonym. */
-export function buildOccupationFacts(rows) {
-  const { rows: out, add } = makeRowBuilder();
-  for (const row of rows) {
-    if (row.Accept !== "TRUE") continue;
-    if (row["Not an occupation"] === "TRUE") continue;
-    const label = firstOf(row.Labels);
-    const lemma = firstOf(row.Lemma);
-    if (!label || !lemma) continue;
-    add(label, "/r/Synonym", lemma);
-  }
-  return sortRows([...out.values()]);
-}
-
-/** Merge the three per-source fact sets into one deduped, sorted set — the
- *  namenet.jsonl content. A pair already emitted by one source (e.g. the
- *  same scientific-name/common-name pair surfacing via both
- *  species_reviewed.csv and taxon2common_reviewed.csv) is kept once. */
-export function mergeFacts(...factLists) {
-  const { rows, add } = makeRowBuilder();
-  for (const list of factLists) {
-    for (const f of list) add(humanize(f.start.replace(/^\/c\/en\//, "")), f.rel, humanize(f.end.replace(/^\/c\/en\//, "")));
-  }
-  return sortRows([...rows.values()]);
-}
-
-// ---- output ------------------------------------------------------------
-
-const toJsonl = (rows) => rows.map((r) => JSON.stringify(r)).join("\n") + "\n";
-const sha256 = (text) => createHash("sha256").update(text).digest("hex");
-
-async function readCsv(dir, name) {
-  const text = await readFile(join(dir, name), "utf8");
-  return parseCsv(text);
-}
-
-async function main() {
-  const namenetDir = resolveNamenetDir();
-  const yamlDir = resolveYamlDir([], process.env) || DEFAULT_YAML_DIR;
-  process.stderr.write(`corpus/namenet/generate.mjs: reading ${namenetDir}\n`);
-  process.stderr.write(`  (species_reviewed.csv also needs OEWN synsets from ${yamlDir})\n`);
-
-  const [speciesRows, taxonRows, occupationRows] = await Promise.all([
-    readCsv(namenetDir, "species_reviewed.csv"),
-    readCsv(namenetDir, "taxon2common_reviewed.csv"),
-    readCsv(namenetDir, "linked_occupations_reviewed.csv"),
-  ]);
-  const { bySynset } = await loadAllSynsets(yamlDir);
-
-  const speciesFacts = buildSpeciesFacts(speciesRows, bySynset);
-  const taxonFacts = buildTaxon2CommonFacts(taxonRows);
-  const occupationFacts = buildOccupationFacts(occupationRows);
-  const merged = mergeFacts(speciesFacts, taxonFacts, occupationFacts);
-
-  process.stderr.write(`  species_reviewed.csv:            ${speciesRows.length} rows -> ${speciesFacts.length} facts\n`);
-  process.stderr.write(`  taxon2common_reviewed.csv:        ${taxonRows.length} rows -> ${taxonFacts.length} facts\n`);
-  process.stderr.write(`  linked_occupations_reviewed.csv:  ${occupationRows.length} rows -> ${occupationFacts.length} facts\n`);
-  process.stderr.write(`  namenet (merged, deduped):        ${merged.length} facts\n`);
-
-  await mkdir(NAMENET_OUT_DIR, { recursive: true });
-  const outText = toJsonl(merged);
-  await writeFile(join(NAMENET_OUT_DIR, "namenet.jsonl"), outText);
-
-  const manifest = {
-    version: 1,
-    generated: "by corpus/namenet/generate.mjs",
-    corpuses: [
-      {
-        id: "namenet",
-        kind: "language",
-        description: "Scientific-name/common-name and Wikidata-label/WordNet-lemma synonym pairs, mechanically derived from three human-reviewed Open English Namenet linking tables (species, taxon-to-common-name, occupations). A small top-up bundle, not a primary corpus.",
-        source: { kind: "curated", tool: "corpus/namenet/generate.mjs" },
-        file: "namenet.jsonl",
-        facts: merged.length,
-        bytes: Buffer.byteLength(outText),
-        sha256: sha256(outText),
-        license: "CC-BY-4.0 (source repo declares no explicit license; see LICENSE-NOTICE)",
-      },
-    ],
-  };
-  const manifestText = JSON.stringify(manifest, null, 2) + "\n";
-  await writeFile(join(NAMENET_OUT_DIR, "manifest.json"), manifestText);
-  process.stderr.write(`wrote corpus/namenet/manifest.json (${manifest.corpuses.length} corpuses)\n`);
-}
-
-const isMain = process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href;
-if (isMain) await main();