@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.4.0

package/src/corpus/conceptnet-map.toml

@@ -0,0 +1,251 @@
+# conceptnet-map.toml — the relation → ACE-OWL-pattern mapping table
+# (ROADMAP Phase 2, ConceptNet corpus slice).
+#
+# One row per ConceptNet relation (the canonical closed set of 34 —
+# docs/references/schemas/conceptnet-relations.md is the reference list this
+# table is drift-checked against; test/corpus-conceptnet.test.mjs fails if the
+# committed slice contains a relation with no row here).
+#
+# Fields:
+#   rel       the ConceptNet relation URI ("/r/IsA")
+#   surface   the canonical surface template, "{start}"/"{end}" slotted —
+#             the "A dog is a kind of animal" sentence shape this relation reads as
+#   ace       which ACE-OWL pattern it maps to (docs/references/schemas/
+#             ace-owl-fragment.md): subClassOf | type | ObjectProperty |
+#             someValuesFrom | disjointWith | property | none
+#   predicate the predicate URI src/corpus/conceptnet.mjs emits into memory
+#             facts (absent when ace = "none" — no fact is emitted)
+#   note      why, and what a "none" row is still good for
+#
+# Loader contract (src/corpus/conceptnet.mjs): a relation in the slice that is
+# MISSING here is an error (drift guard); a row with ace = "none" is a
+# deliberate non-emission, silently skipped by toFacts().
+
+[[relation]]
+rel = "/r/IsA"
+surface = "a {start} is a kind of {end}"
+ace = "subClassOf"
+predicate = "rdfs:subClassOf"
+note = "hyponym → hypernym; ACE pattern 1 ('every N1 is a N2')"
+
+[[relation]]
+rel = "/r/DefinedAs"
+surface = "a {start} is defined as {end}"
+ace = "subClassOf"
+predicate = "rdfs:subClassOf"
+note = "definitional IsA; also ACE pattern 1"
+
+[[relation]]
+rel = "/r/PartOf"
+surface = "a {start} is part of a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:partOf"
+note = "meronymy; ACE pattern 3 (N1 VERB N2)"
+
+[[relation]]
+rel = "/r/HasA"
+surface = "a {start} has a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasA"
+note = "possession/holonymy; plain edge today — ACE pattern 5 cardinality is a later refinement"
+
+[[relation]]
+rel = "/r/UsedFor"
+surface = "a {start} is used for {end}"
+ace = "ObjectProperty"
+predicate = "mgx:usedFor"
+note = "typical purpose; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CapableOf"
+surface = "a {start} can {end}"
+ace = "ObjectProperty"
+predicate = "mgx:capableOf"
+note = "typical capability; ACE pattern 3"
+
+[[relation]]
+rel = "/r/AtLocation"
+surface = "you are likely to find a {start} in a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:atLocation"
+note = "typical location; ACE pattern 3"
+
+[[relation]]
+rel = "/r/Causes"
+surface = "a {start} causes {end}"
+ace = "ObjectProperty"
+predicate = "mgx:causes"
+note = "causation; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasSubevent"
+surface = "when you {start}, you {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasSubevent"
+note = "event decomposition; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasFirstSubevent"
+surface = "the first thing you do when you {start} is {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasFirstSubevent"
+note = "first step; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasLastSubevent"
+surface = "the last thing you do when you {start} is {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasLastSubevent"
+note = "last step; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasPrerequisite"
+surface = "in order to {start}, you must {end}"
+ace = "ObjectProperty"
+predicate = "mgx:hasPrerequisite"
+note = "dependency; ACE pattern 3"
+
+[[relation]]
+rel = "/r/HasProperty"
+surface = "a {start} is {end}"
+ace = "property"
+predicate = "mgx:hasProperty"
+note = "attribute/adjective; ACE pattern 8 ('N1 is ADJ')"
+
+[[relation]]
+rel = "/r/MotivatedByGoal"
+surface = "you would {start} because you want to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:motivatedByGoal"
+note = "motivation; ACE pattern 3"
+
+[[relation]]
+rel = "/r/ObstructedBy"
+surface = "{start} can be prevented by {end}"
+ace = "ObjectProperty"
+predicate = "mgx:obstructedBy"
+note = "blocker; ACE pattern 3"
+
+[[relation]]
+rel = "/r/Desires"
+surface = "a {start} wants {end}"
+ace = "ObjectProperty"
+predicate = "mgx:desires"
+note = "typical desire; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CausesDesire"
+surface = "{start} makes you want to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:causesDesire"
+note = "evoked desire; ACE pattern 3"
+
+[[relation]]
+rel = "/r/CreatedBy"
+surface = "a {start} is created by a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:createdBy"
+note = "provenance; ACE pattern 3"
+
+[[relation]]
+rel = "/r/MadeOf"
+surface = "a {start} is made of {end}"
+ace = "ObjectProperty"
+predicate = "mgx:madeOf"
+note = "material; ACE pattern 3"
+
+[[relation]]
+rel = "/r/ReceivesAction"
+surface = "a {start} can be {end}"
+ace = "ObjectProperty"
+predicate = "mgx:receivesAction"
+note = "typical patient role; ACE pattern 3"
+
+[[relation]]
+rel = "/r/LocatedNear"
+surface = "a {start} is typically near a {end}"
+ace = "ObjectProperty"
+predicate = "mgx:locatedNear"
+note = "proximity; ACE pattern 3"
+
+[[relation]]
+rel = "/r/MannerOf"
+surface = "{start} is a way to {end}"
+ace = "ObjectProperty"
+predicate = "mgx:mannerOf"
+note = "verb specialization — properly rdfs:subPropertyOf between verbs; stored as a plain edge until the grammar grows verb hierarchies"
+
+[[relation]]
+rel = "/r/DistinctFrom"
+surface = "a {start} is not a {end}"
+ace = "disjointWith"
+predicate = "owl:disjointWith"
+note = "mutual exclusion; ACE pattern 6 ('no N1 is a N2')"
+
+# --- unmappable relations: no clean OWL-axiom fit; kept for other consumers ---
+
+[[relation]]
+rel = "/r/RelatedTo"
+surface = "{start} is related to {end}"
+ace = "none"
+note = "weakest, undirected association — too vague for an axiom; useful later as a fuzzy-match hint, never a fact"
+
+[[relation]]
+rel = "/r/Synonym"
+surface = "{start} means the same as {end}"
+ace = "none"
+note = "lexical alias, not an axiom — feeds the grammar lexicon / phrasebook synonym families instead"
+
+[[relation]]
+rel = "/r/Antonym"
+surface = "{start} is the opposite of {end}"
+ace = "none"
+note = "lexical opposition; OWL disjointness would over-claim (hot/cold are not disjoint classes) — DistinctFrom carries the real disjointness"
+
+[[relation]]
+rel = "/r/FormOf"
+surface = "{start} is a form of the word {end}"
+ace = "none"
+note = "inflection → root; lexicon normalization, not knowledge"
+
+[[relation]]
+rel = "/r/DerivedFrom"
+surface = "the word {start} is derived from {end}"
+ace = "none"
+note = "word derivation; lexicon material, not an axiom"
+
+[[relation]]
+rel = "/r/SymbolOf"
+surface = "{start} is a symbol of {end}"
+ace = "none"
+note = "symbolism — no OWL fit"
+
+[[relation]]
+rel = "/r/SimilarTo"
+surface = "{start} is similar to {end}"
+ace = "none"
+note = "graded similarity — no crisp OWL fit; potential fuzzy-match hint only"
+
+[[relation]]
+rel = "/r/HasContext"
+surface = "{start} is used in the context of {end}"
+ace = "none"
+note = "usage-domain tag — the slice FILTER signal (tech-domain selection), not a fact to store"
+
+[[relation]]
+rel = "/r/EtymologicallyRelatedTo"
+surface = "{start} shares an origin with {end}"
+ace = "none"
+note = "etymology — filtered out of the slice by policy"
+
+[[relation]]
+rel = "/r/EtymologicallyDerivedFrom"
+surface = "the word {start} comes from {end}"
+ace = "none"
+note = "etymology — filtered out of the slice by policy"
+
+[[relation]]
+rel = "/r/ExternalURL"
+surface = "{start} is described at {end}"
+ace = "none"
+note = "link out of the graph — filtered out of the slice (end is a URL, not an en concept)"

package/src/corpus/conceptnet.mjs

@@ -0,0 +1,167 @@
+// corpus/conceptnet.mjs — the ConceptNet slice loader + memory seeder
+// (ROADMAP Phase 2, "ConceptNet corpus slice").
+//
+//   loadSlice(path?)        stream corpus/conceptnet/slice.jsonl → assertions
+//   loadMap(path?)          src/corpus/conceptnet-map.toml → Map(rel → row)
+//   toFacts(assertions,map) assertions → appendFact-shaped triples
+//   seedMemory(dir, opts)   write them into <dir>/.tmct/memory via appendFact
+//
+// The slice is committed data (one JSON object per line: {start, rel, end,
+// surfaceText?, weight}; en→en only; CC-BY-SA 4.0 for ConceptNet-derived rows
+// — see corpus/conceptnet/LICENSE-NOTICE). The mapping table decides which
+// relations become memory facts and under which predicate URI; rows marked
+// ace = "none" are deliberate non-emissions. A slice relation MISSING from
+// the table is a drift error — loud, never guessed around.
+//
+// Seeding goes through src/memory/core.mjs appendFact() ONLY (memory is
+// import-only here): fact ids are content-hashed from (s,p,o), so re-seeding
+// is idempotent by construction. seedMemory additionally pre-loads the store
+// once and skips triples already present, so a re-seed is read-mostly instead
+// of N rewrites.
+
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { appendFact, loadMemory, normFactTerm } from "../memory/core.mjs";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const SLICE_FILE = join(PKG_ROOT, "corpus", "conceptnet", "slice.jsonl");
+export const MAP_FILE = join(PKG_ROOT, "src", "corpus", "conceptnet-map.toml");
+
+const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
+
+/** Load the slice JSONL as a stream (never the whole file as one string) and
+ *  return the parsed assertions. Every line must carry start/rel/end; bad
+ *  lines fail loudly with file:line. */
+export async function loadSlice(path = SLICE_FILE) {
+  const rl = createInterface({ input: createReadStream(path, "utf8"), crlfDelay: Infinity });
+  const assertions = [];
+  let n = 0;
+  for await (const raw of rl) {
+    n += 1;
+    const line = raw.trim();
+    if (!line) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      throw new Error(`${path}:${n}: not valid JSON: ${e.message}`);
+    }
+    for (const field of ["start", "rel", "end"]) {
+      if (typeof row[field] !== "string" || !row[field]) {
+        throw new Error(`${path}:${n}: assertion missing "${field}"`);
+      }
+    }
+    assertions.push(row);
+  }
+  return assertions;
+}
+
+/** Load the relation → ACE-OWL mapping table. Returns Map(rel → row); every
+ *  row must have a known `ace` pattern, and a mapped (non-"none") row must
+ *  name the predicate URI it emits. */
+export async function loadMap(path = MAP_FILE) {
+  const table = parseToml(await readFile(path, "utf8"));
+  const rows = table.relation || [];
+  const map = new Map();
+  for (const row of rows) {
+    if (!row.rel) throw new Error(`${path}: a [[relation]] row is missing "rel"`);
+    if (map.has(row.rel)) throw new Error(`${path}: duplicate mapping for ${row.rel}`);
+    if (!ACE_PATTERNS.has(row.ace)) {
+      throw new Error(`${path}: ${row.rel} has unknown ace pattern ${JSON.stringify(row.ace)}`);
+    }
+    if (row.ace !== "none" && !row.predicate) {
+      throw new Error(`${path}: ${row.rel} maps to ${row.ace} but names no predicate URI`);
+    }
+    map.set(row.rel, row);
+  }
+  return map;
+}
+
+/** /c/en/source_code → "source code" — the human term text a memory fact stores. */
+export const termText = (uri) => {
+  const m = /^\/c\/en\/([^/]+)/.exec(String(uri || ""));
+  return m ? m[1].replace(/_/g, " ") : null;
+};
+
+/** Map slice assertions → appendFact-shaped triples:
+ *    { subject, predicate, object, provenance }
+ *  (provenance is a STRING — exactly what src/memory/core.mjs appendFact
+ *  takes; it names the corpus and the originating ConceptNet relation).
+ *  Rows whose relation maps ace="none" are skipped — deliberate non-emission.
+ *  A relation with NO row in the map throws: that is table drift, not data. */
+export function toFacts(assertions, map) {
+  const facts = [];
+  for (const a of assertions) {
+    const row = map.get(a.rel);
+    if (!row) {
+      throw new Error(`slice/map drift: relation ${a.rel} has no row in conceptnet-map.toml`);
+    }
+    if (row.ace === "none") continue;
+    const subject = termText(a.start);
+    const object = termText(a.end);
+    if (!subject || !object) continue; // non-en endpoint slipped in — filtered, not fatal
+    facts.push({
+      subject,
+      predicate: row.predicate,
+      object,
+      provenance: `corpus:conceptnet ${a.rel}`,
+    });
+  }
+  return facts;
+}
+
+/** Seed a repo's memory graph (<dir>/.tmct/memory/graph.json) from the
+ *  committed slice. Options: limit (cap the facts written — handy for tests
+ *  and fast bootstraps), slicePath/mapPath overrides, and `prefer` — an array
+ *  of predicate URIs that STABLE-partitions the facts before the limit is
+ *  applied (facts whose predicate appears earlier in `prefer` come first;
+ *  everything else keeps slice order after them). A capped bootstrap seed
+ *  wants the DEFINITIONAL band ("a cache is a kind of buffer") ahead of the
+ *  location trivia the slice happens to open with; without `prefer` the
+ *  behavior is byte-identical to before.
+ *
+ *  Idempotent twice over: appendFact's content-hashed ids make a blind
+ *  re-append an upsert, and we pre-read the store once to skip triples that
+ *  are already there (so re-seeding costs one read, not N rewrites).
+ *  Returns { appended, skipped, total }. */
+export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE, prefer } = {}) {
+  const [assertions, map] = await Promise.all([loadSlice(slicePath), loadMap(mapPath)]);
+  let facts = toFacts(assertions, map);
+  if (Array.isArray(prefer) && prefer.length) {
+    const rank = new Map(prefer.map((p, i) => [p, i]));
+    // stable partition: Array.prototype.sort is stable in Node, so equal-rank
+    // facts keep their slice order — deterministic across runs by construction.
+    facts = facts.slice().sort((a, b) => (rank.get(a.predicate) ?? prefer.length) - (rank.get(b.predicate) ?? prefer.length));
+  }
+  if (limit !== undefined) facts = facts.slice(0, limit);
+
+  // One read up front: what does the store already reify? Keys are built with
+  // memory's own normFactTerm so they match the normalized read-back exactly
+  // (appendFact converges /c/en/foo_bar, tmct:Foo and "Foo bar" to one term).
+  const factKey = (s, p, o) => `${normFactTerm(s)} ${p} ${normFactTerm(o)}`;
+  const existing = new Set();
+  const memory = await loadMemory(dir);
+  for (const ind of memory.individuals || []) {
+    if (ind?.class !== "Fact") continue;
+    const get = (key) => (ind.attributes || []).find((x) => x.key === key)?.value;
+    existing.add(factKey(get("subject"), get("predicate"), get("object")));
+  }
+
+  let appended = 0;
+  let skipped = 0;
+  for (const fact of facts) {
+    const key = factKey(fact.subject, fact.predicate, fact.object);
+    if (existing.has(key)) {
+      skipped += 1;
+      continue;
+    }
+    await appendFact(dir, fact);
+    existing.add(key);
+    appended += 1;
+  }
+  return { appended, skipped, total: facts.length };
+}

package/src/corpus/templates.mjs

@@ -0,0 +1,188 @@
+// corpus/templates.mjs — the response-template library + SE phrase book loaders
+// (ROADMAP Phase 2, items 4+7). Plain diffable data in, strict renderers out:
+//
+//   data/templates/responses.jsonl   {id, class, template, register} rows
+//   data/phrasebook/software-phrases.txt  one phrase pattern per line
+//                                         (`#` comments, `~` synonym families)
+//
+// loadTemplates() validates the whole file (parse, required fields, unique
+// ids) and caches; render(id, slots) is then synchronous and STRICT — an
+// unknown id or a missing slot throws, it never emits a half-filled sentence.
+// The response surface (Phase 1 pipeline) fills templates from grounded data
+// only, so a thrown slot is a programming error, not a user-facing miss.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const TEMPLATES_FILE = join(PKG_ROOT, "data", "templates", "responses.jsonl");
+export const PHRASEBOOK_FILE = join(PKG_ROOT, "data", "phrasebook", "software-phrases.txt");
+
+// Registers (Phase 6, PLAN_FORMULAIC_COMPETENCE.md): `terse|friendly` are the
+// conversational bands; `technical` is the C1 / technical-paper band whose
+// templates render item-5 mechanical conclusions (count / comparison /
+// superlative + the provenance we already compute) as advanced prose. A
+// technical template is FORMULAIC COMPETENCE: it renders via:"template", so the
+// dual banding counts it in the PERFORMANCE band only, never the productive one.
+const REGISTERS = new Set(["terse", "friendly", "technical"]);
+const SLOT_RE = /\{([A-Za-z][A-Za-z0-9]*)\}/g;
+
+// Slot-lint for the technical band: a technical template may ONLY fill from the
+// mechanical values tmct actually computes (counts, comparisons, superlatives,
+// scopes, provenance) — no free-text slot can smuggle unattributable prose into
+// the C1 register. Every technical row must also carry a {provenance} fill (the
+// item-5 "+ provenance" contract: an advanced claim always shows its source).
+export const TECHNICAL_SLOTS = Object.freeze(new Set([
+  "subject", "count", "noun", "scope", "comparison", "metric", "unit",
+  "superlative", "provenance",
+]));
+
+/** The slot names a template string requires, in first-appearance order. */
+export function slotsOf(template) {
+  const out = [];
+  for (const m of String(template).matchAll(SLOT_RE)) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+
+// --- Segmentation IR (Phase 7, lever 1) -------------------------------------
+// A rendered answer is ALSO a list of typed spans: [{ type, text }, …] with
+// type ∈ prose | entity | path | number | code | provenance | receipt. The
+// invariant law is byte-exact reconstruction: flatten(segments) === render().
+// Everything except `prose` is PROTECTED — finishing (a later wave) may only
+// transform prose spans, so a grammar rule can never touch a fact.
+//
+// Slot kinds map a template hole to its protected span type. A slot fill is
+// ALWAYS protected (never prose): it is grounded data, not our wording. The
+// specific type is derived from the slot name; unknown slots fall back to the
+// conservative `entity` (protect-when-unsure). Bytes never depend on the type,
+// only on the fill, so the type is metadata layered over an exact split.
+const SLOT_KIND = {
+  count: "number",
+  when: "number",
+  location: "path",
+  commit: "path",
+  provenance: "provenance",
+};
+
+/** The protected span type for a template slot name (default: entity). */
+export function slotKind(name) {
+  return SLOT_KIND[name] || "entity";
+}
+
+/** Reconstruct the flat answer from its segments — a pure, total inverse of
+ *  segmentation: `segments.map(s => s.text).join("")`. flatten(renderSegments(
+ *  id, slots)) === render(id, slots), byte for byte. */
+export function flatten(segments) {
+  let out = "";
+  for (const s of segments) out += s.text;
+  return out;
+}
+
+/** Render template `id` as a SEGMENTED answer: the literal text between slots
+ *  becomes `prose` spans, each slot fill becomes a PROTECTED span typed by
+ *  slotKind(). Validation is identical to render() (unknown id / missing slot
+ *  throw the same messages), so render() is exactly flatten(renderSegments()). */
+export function renderSegments(id, slots = {}, templates = cache) {
+  if (!templates) throw new Error("renderSegments() before loadTemplates() — load the template library first");
+  const row = templates.get(id);
+  if (!row) throw new Error(`unknown template id "${id}"`);
+  const missing = row.slots.filter((s) => slots[s] === undefined || slots[s] === null);
+  if (missing.length) {
+    throw new Error(`template "${id}" missing slot${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`);
+  }
+  const tpl = row.template;
+  const re = new RegExp(SLOT_RE.source, "g"); // own lastIndex; never touch the shared regex
+  const segments = [];
+  let last = 0;
+  let m;
+  while ((m = re.exec(tpl)) !== null) {
+    if (m.index > last) segments.push({ type: "prose", text: tpl.slice(last, m.index) });
+    segments.push({ type: slotKind(m[1]), text: String(slots[m[1]]) });
+    last = m.index + m[0].length;
+  }
+  if (last < tpl.length) segments.push({ type: "prose", text: tpl.slice(last) });
+  return segments;
+}
+
+let cache = null; // Map<id, row> from the last loadTemplates() — render()'s source
+
+/** Load + validate the response templates. Every line must parse as JSON with
+ *  a unique `id`, a `class`, a known `register`, and a non-empty `template`
+ *  (bad data fails loudly at load, never at render time). Returns Map<id,row>
+ *  (each row gains `slots`, its required slot names) and primes render(). */
+export async function loadTemplates(path = TEMPLATES_FILE) {
+  const text = await readFile(path, "utf8");
+  const byId = new Map();
+  const lines = text.split("\n");
+  for (let n = 0; n < lines.length; n += 1) {
+    const line = lines[n].trim();
+    if (!line) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      throw new Error(`${path}:${n + 1}: not valid JSON: ${e.message}`);
+    }
+    for (const field of ["id", "class", "template", "register"]) {
+      if (typeof row[field] !== "string" || !row[field]) {
+        throw new Error(`${path}:${n + 1}: missing/empty "${field}"`);
+      }
+    }
+    if (!REGISTERS.has(row.register)) {
+      throw new Error(`${path}:${n + 1}: register must be terse|friendly|technical, got "${row.register}"`);
+    }
+    if (byId.has(row.id)) throw new Error(`${path}:${n + 1}: duplicate template id "${row.id}"`);
+    const slots = slotsOf(row.template);
+    // Technical-band slot-lint: mechanical-only fills, provenance mandatory.
+    if (row.register === "technical") {
+      const stray = slots.filter((s) => !TECHNICAL_SLOTS.has(s));
+      if (stray.length) {
+        throw new Error(`${path}:${n + 1}: technical template "${row.id}" uses non-mechanical slot${stray.length > 1 ? "s" : ""}: ${stray.join(", ")} (allowed: ${[...TECHNICAL_SLOTS].join(", ")})`);
+      }
+      if (!slots.includes("provenance")) {
+        throw new Error(`${path}:${n + 1}: technical template "${row.id}" must carry a {provenance} fill (an advanced claim always shows its source)`);
+      }
+    }
+    byId.set(row.id, { ...row, slots });
+  }
+  cache = byId;
+  return byId;
+}
+
+/** Fill template `id` with `slots` — strict: unknown id throws; ANY missing
+ *  slot throws (named), so a response is complete or not emitted at all.
+ *  Extra slots are ignored. Uses the map from loadTemplates() (pass
+ *  `templates` explicitly to bypass the module cache, e.g. in tests). */
+export function render(id, slots = {}, templates = cache) {
+  if (!templates) throw new Error("render() before loadTemplates() — load the template library first");
+  // render() IS the flattened segmentation, by construction: the byte output is
+  // provably identical to the old `.replace(SLOT_RE, …)` (test/segments.test.mjs
+  // renders every responses.jsonl row both ways and asserts equality).
+  return flatten(renderSegments(id, slots, templates));
+}
+
+/** Load + parse the SE phrase book. Returns:
+ *    patterns  [{pattern, slots}]  one per phrase line ("what calls {x}")
+ *    synonyms  [[word, …], …]      one per `~` family line (≥2 entries each)
+ *  `#`-prefixed lines and blank lines are skipped. */
+export async function loadPhrasebook(path = PHRASEBOOK_FILE) {
+  const text = await readFile(path, "utf8");
+  const patterns = [];
+  const synonyms = [];
+  const lines = text.split("\n");
+  for (let n = 0; n < lines.length; n += 1) {
+    const line = lines[n].trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("~")) {
+      const family = line.slice(1).split(",").map((w) => w.trim().toLowerCase()).filter(Boolean);
+      if (family.length < 2) throw new Error(`${path}:${n + 1}: a synonym family needs at least 2 entries`);
+      synonyms.push(family);
+      continue;
+    }
+    patterns.push({ pattern: line, slots: slotsOf(line) });
+  }
+  return { patterns, synonyms };
+}