@polycode-projects/the-mechanical-code-talker 3.0.0 → 3.0.2

package/src/domain/digest/compose.mjs

@@ -0,0 +1,103 @@
+// digest/compose.mjs — stage 3 of the digest layer: order the selected facts
+// into sentences and group them into paragraphs. Pure and deterministic; the
+// prose quality lives here — the lead sentence names the term, every sentence
+// after it refers back with a pronoun, and a paragraph never runs past its
+// sentence cap. Each sentence keeps the fact rows behind it, so provenance
+// survives composition into the article stage.
+
+import { renderStructure } from "./structures.mjs";
+import { FAMILY_PRIORITY } from "./select.mjs";
+import { articleFor, capitalizeFirst } from "./words.mjs";
+
+const DESCRIPTION_FAMILIES = FAMILY_PRIORITY.filter((f) => f !== "isa" && f !== "other");
+
+/** Group the selector's `selected` items by family, preserving each item's
+ *  ranked order, and return `{ family -> rows[] }` over the fact rows. */
+function rowsByFamily(selected) {
+  const by = new Map();
+  for (const item of selected || []) {
+    if (!by.has(item.family)) by.set(item.family, []);
+    by.get(item.family).push(item.row);
+  }
+  return by;
+}
+
+/** The first sentence must introduce the term. When no isa fact led (so the
+ *  first sentence opens with a bare "It"), rewrite that pronoun into the term's
+ *  own noun phrase so the pronoun has an antecedent. */
+function ensureFirstNamesTerm(sentences, term) {
+  if (!sentences.length) return;
+  const first = sentences[0];
+  if (/\bnames-term\b/.test(first.role)) return;
+  const phrase = capitalizeFirst(`${articleFor(term)} ${term}`);
+  first.text = first.text.replace(/^It\b/, phrase);
+  first.role = "names-term";
+}
+
+/** Split a flat sentence list into paragraphs of at most `cap` sentences,
+ *  respecting the caller's paragraph boundaries (a sentence's `paragraph` tag). */
+function paragraphsFrom(sentences, cap) {
+  const groups = [];
+  let current = null;
+  let currentTag = null;
+  for (const s of sentences) {
+    if (!current || s.paragraph !== currentTag || current.length >= cap) {
+      current = [];
+      currentTag = s.paragraph;
+      groups.push(current);
+    }
+    current.push(s);
+  }
+  return groups.map((sentences) => ({
+    sentences,
+    text: sentences.map((s) => s.text).join(" "),
+  }));
+}
+
+/**
+ * Compose the term digest from a selector result and a structure table.
+ *
+ * opts:
+ *   - chains: { object -> [object, parent, …] } ancestry chains, so a lone isa
+ *     fact can render as a chain ("a mammal, and so an animal") when one exists.
+ *   - maxSentencesPerParagraph: the sentence cap (default 3).
+ *
+ * Returns { term, sentences, paragraphs, provenanceRows }. Every sentence in
+ * `sentences` carries { text, rows, family, role, paragraph }; `paragraphs`
+ * joins them for rendering; `provenanceRows` is every fact row the digest used,
+ * deduped by id.
+ */
+export function composeTermDigest(selection, table, opts = {}) {
+  const term = selection?.term || "";
+  const cap = Number.isInteger(opts.maxSentencesPerParagraph) ? opts.maxSentencesPerParagraph : 3;
+  const chains = opts.chains || {};
+  const byFamily = rowsByFamily(selection?.selected || []);
+  const sentences = [];
+
+  const isaRows = byFamily.get("isa") || [];
+  if (isaRows.length) {
+    const chain = isaRows.length === 1 ? chains[isaRows[0].object] : null;
+    const form = chain && chain.length > 1 ? "chained" : (isaRows.length > 1 ? "several" : "single");
+    const s = renderStructure(table, "isa", isaRows, { term, form, chain });
+    if (s) sentences.push({ ...s, role: "names-term", paragraph: "definition" });
+  }
+
+  for (const family of DESCRIPTION_FAMILIES) {
+    const rows = byFamily.get(family);
+    if (!rows || !rows.length) continue;
+    const s = renderStructure(table, family, rows, { term });
+    if (s) sentences.push({ ...s, role: "describes", paragraph: "description" });
+  }
+
+  ensureFirstNamesTerm(sentences, term);
+
+  const provenanceById = new Map();
+  for (const s of sentences) for (const r of s.rows) if (!provenanceById.has(r.id)) provenanceById.set(r.id, r);
+
+  return {
+    term,
+    sentences,
+    paragraphs: paragraphsFrom(sentences, cap),
+    provenanceRows: [...provenanceById.values()],
+  };
+}

package/src/domain/digest/config.json

@@ -0,0 +1,13 @@
+{
+  "uninformativeClassMaxShare": 0.35,
+  "uninformativeClassMinSubjects": 12,
+  "entailedDepthPenalty": 0.2,
+  "minoritySensePenalty": 0.5,
+  "minScore": 0.05,
+  "budget": {
+    "chatReply": 5,
+    "researchPanel": 10,
+    "cliDigest": 12,
+    "ledgerTerm": 8
+  }
+}

package/src/domain/digest/index.mjs

@@ -0,0 +1,38 @@
+// digest/index.mjs — the digest layer's public seam: run the pure pipeline
+// (select -> structures -> compose -> article) end to end. Stage 5 (the chat
+// term answer, the research panel, `tmct digest`) becomes thin wiring over
+// this: build the fact rows and the store statistics from the graph it already
+// holds, hand them in, and render the returned article shape.
+//
+// Everything here is pure and deterministic. The structure table arrives
+// pre-parsed (the same injection posture the construction banks use), so this
+// module — and the whole layer — imports nothing outside src/domain.
+
+import { selectFacts, FAMILY_OF, FAMILY_PRIORITY } from "./select.mjs";
+import { buildStructureTable, renderStructure } from "./structures.mjs";
+import { composeTermDigest } from "./compose.mjs";
+import { termArticle, researchRunArticle, sessionDigestArticle } from "./article.mjs";
+
+export { selectFacts, FAMILY_OF, FAMILY_PRIORITY };
+export { buildStructureTable, renderStructure };
+export { composeTermDigest };
+export { termArticle, researchRunArticle, sessionDigestArticle };
+
+/**
+ * Digest one term end to end.
+ *
+ * @param term    the normalized term the digest is about.
+ * @param rows    its candidate fact rows (readFactRows() rows with subject===term).
+ * @param store   the store-relative statistics selectFacts() needs
+ *                ({ classSubjectCounts, totalSubjects, subClassEdges, disjointEdges }).
+ * @param table   a structure table (buildStructureTable() over the parsed bank).
+ * @param opts    { budget, config, chains, maxSentencesPerParagraph } — threaded
+ *                to the stages that use them.
+ * @returns the term-article shape, carrying the narrative, its sources, and the
+ *          full fact list behind the "show the facts" escape.
+ */
+export function digestTerm(term, rows, store = {}, table = new Map(), opts = {}) {
+  const selection = selectFacts(term, rows, store, opts);
+  const composed = composeTermDigest(selection, table, opts);
+  return termArticle(selection, composed, opts);
+}

package/src/domain/digest/select.mjs

@@ -0,0 +1,233 @@
+// digest/select.mjs — stage 1 of the digest layer: score the candidate fact
+// rows for one term and cut them to a budget. Pure and deterministic over the
+// rows and a store-relative statistics bundle the caller supplies; imports only
+// its sibling domain modules (the trust priors and the sense-split machinery),
+// never the filesystem or the store adapter.
+//
+// The scoring signals, all already present on a readFactRows() row or cheaply
+// derivable from a store scan:
+//   - provenance tier: a researched or taught fact outranks an entailed one,
+//     read from the row's source-type priors (memory/trust.mjs).
+//   - chain depth: a stated fact outranks one the closure derived (a row with a
+//     non-empty premise environment is entailed, and demoted).
+//   - informativeness: a class nearly every subject in the store shares carries
+//     almost no information about THIS term. A store-relative frequency share
+//     over a committed threshold CUTS the row — this is what removes "a kind of
+//     entity" without a hand-maintained stoplist.
+//   - relation coverage: the cut prefers breadth — one good isa, one partOf and
+//     one capableOf beat four isa chains — by filling families round-robin.
+//   - sense agreement: an isa object whose sense cluster disagrees with the
+//     term's dominant sense is demoted (the "medium"/"software" branch the
+//     specimen shows), scored through sense-split.mjs's own clustering.
+//
+// Nothing is destroyed. Every row the budget or a cut removes is returned in
+// `cut` with a reason, so "show the facts" downstream reaches the full list and
+// the ranking stays auditable.
+
+import { SOURCE_PRIOR } from "../memory/trust.mjs";
+import { clusterSenses } from "../sense-split.mjs";
+import DEFAULT_CONFIG from "./config.json" with { type: "json" };
+
+// A relation predicate -> the sentence-family key the digest groups it under.
+// Deliberately small: the families stage 2 authors structures for today. A
+// predicate with no entry lands in "other" — still selectable, still carried
+// into the detail, but never leading the narrative.
+// Each family is VERB-COHERENT: the predicates inside it share one sentence
+// frame, so stage 2 can author one structure per family without the object
+// preposition guessing which verb it belongs to. A predicate with no entry
+// lands in "other" — still selectable, still carried into the detail, but never
+// leading the narrative.
+export const FAMILY_OF = Object.freeze({
+  "rdfs:subClassOf": "isa",
+  "rdf:type": "isa",
+  "mgx:atLocation": "location",
+  "mgx:locatedNear": "location",
+  "mgx:partOf": "partOf",
+  "mgx:capableOf": "capableOf",
+  "mgx:usedFor": "usedFor",
+});
+
+// The order families lead the digest in: the definition (isa) first, then where
+// it sits, what it belongs to, what it can do, what it is used for, then
+// anything else. The round-robin cut pulls from families in this order, so a tie
+// in score never makes the ordering non-deterministic.
+export const FAMILY_PRIORITY = Object.freeze(["isa", "location", "partOf", "capableOf", "usedFor", "other"]);
+
+const familyOf = (predicate) => FAMILY_OF[predicate] || "other";
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+
+/** The provenance component of a row's score: the strongest source-type prior
+ *  the row carries (a taught fact's 0.95 beats an entailed fact's 0.3), falling
+ *  back to the row's materialised trust, then to the entailed floor. */
+function provenanceScore(row) {
+  const priors = (row.sourceTypes || []).map((t) => SOURCE_PRIOR[t] ?? 0);
+  if (priors.length) return Math.max(...priors);
+  if (typeof row.trust === "number" && row.trust > 0) return row.trust;
+  return SOURCE_PRIOR.entailed;
+}
+
+/** A row the closure derived rather than a source stated: it carries a premise
+ *  environment, or an entailed source type. */
+function isEntailed(row) {
+  if (Array.isArray(row.environments) && row.environments.length) return true;
+  return (row.sourceTypes || []).includes("entailed");
+}
+
+/** The store-relative share of subjects that carry this class as an isa target.
+ *  Above the committed threshold (in a store large enough for the share to
+ *  mean anything) the class is uninformative and its row is cut. */
+function classShare(object, store) {
+  const total = Number(store?.totalSubjects) || 0;
+  if (total <= 0) return 0;
+  const count = Number(store?.classSubjectCounts?.[object]) || 0;
+  return count / total;
+}
+
+/**
+ * Select the digest-worthy facts for `term` from its candidate `rows`.
+ *
+ * `store` supplies the store-relative signals the scoring needs, all derivable
+ * from one pass over the graph the caller already holds:
+ *   - classSubjectCounts: { class -> number of distinct subjects that are isa it }
+ *   - totalSubjects:      number of distinct isa subjects in the store
+ *   - subClassEdges:      [[child, parent], …] for the sense clustering
+ *   - disjointEdges:      [[a, b], …] stored owl:disjointWith pairs (optional)
+ *
+ * `opts`: { budget (default config.budget.chatReply), config (threshold data) }.
+ *
+ * Returns { term, selected, cut, senses }:
+ *   - selected: up to `budget` items { row, family, score, reasons }, ranked,
+ *     breadth-first across families. Each carries its fact row, so every
+ *     downstream sentence traces back to stored provenance.
+ *   - cut: every other row { row, reason } — nothing is discarded silently.
+ *   - senses: the sense-split verdict over the term's isa objects.
+ */
+export function selectFacts(term, rows, store = {}, opts = {}) {
+  const config = { ...DEFAULT_CONFIG, ...(opts.config || {}) };
+  const budget = Number.isInteger(opts.budget) ? opts.budget : config.budget.chatReply;
+  const candidates = (rows || []).filter((r) => r && r.object && r.object !== term);
+  const cut = [];
+
+  // The uninformative-class cut runs FIRST, before sense clustering. A class
+  // nearly every subject shares carries no information about this term — and,
+  // just as important, a bare uninformative class with no recorded ancestry
+  // would act as a union bridge in the clustering below, collapsing genuinely
+  // distinct senses into one. Removing it first keeps the sense signal clean.
+  const bigEnough = (Number(store?.totalSubjects) || 0) >= config.uninformativeClassMinSubjects;
+  const informative = [];
+  for (const row of candidates) {
+    if (familyOf(row.predicate) === "isa") {
+      const share = classShare(row.object, store);
+      if (bigEnough && share > config.uninformativeClassMaxShare) {
+        cut.push({ row, family: "isa", reason: "uninformative-class", share });
+        continue;
+      }
+    }
+    informative.push(row);
+  }
+
+  // Sense clustering over the SURVIVING isa objects — the dominant sense is the
+  // cluster whose objects carry the most provenance weight; objects outside it
+  // are the demoted branch (the specimen's "medium"/"software" fan-out).
+  const isaObjects = informative.filter((r) => familyOf(r.predicate) === "isa").map((r) => r.object);
+  const senses = clusterSenses(isaObjects, {
+    subClassEdges: store.subClassEdges || [],
+    disjointEdges: store.disjointEdges || [],
+  });
+  const clusterWeight = new Map(); // label -> summed provenance of its objects
+  const labelOfObject = new Map(); // object -> its cluster label
+  for (const cluster of senses.clusters) {
+    let weight = 0;
+    for (const obj of cluster.objects) {
+      labelOfObject.set(obj, cluster.label);
+      const row = informative.find((r) => r.object === obj && familyOf(r.predicate) === "isa");
+      weight += row ? provenanceScore(row) : 0;
+    }
+    clusterWeight.set(cluster.label, weight);
+  }
+  let dominantLabel = null;
+  let bestWeight = -1;
+  for (const [label, weight] of [...clusterWeight].sort((a, b) => a[0].localeCompare(b[0]))) {
+    if (weight > bestWeight) { bestWeight = weight; dominantLabel = label; }
+  }
+
+  const scored = [];
+  for (const row of informative) {
+    const family = familyOf(row.predicate);
+    let score = provenanceScore(row);
+    const reasons = { provenance: score };
+    if (isEntailed(row)) { score -= config.entailedDepthPenalty; reasons.entailed = true; }
+    if (family === "isa") {
+      const share = classShare(row.object, store);
+      // A bounded weight in [0.6, 1.0]: a rarer class says more about the term
+      // and ranks higher, but a common one is only demoted, never zeroed — the
+      // hard removal of a truly uninformative class is the cut above, not this.
+      const informativeness = 0.6 + 0.4 * (1 - share);
+      score *= informativeness;
+      reasons.informativeness = informativeness;
+      const label = labelOfObject.get(row.object);
+      if (dominantLabel && label && label !== dominantLabel) {
+        score -= config.minoritySensePenalty;
+        reasons.minoritySense = label;
+      }
+    }
+    score = clamp01(score);
+    scored.push({ row, family, score, reasons });
+  }
+
+  // A row scored below the floor (a demoted minority sense, a weak entailed
+  // chain) is cut, not held for backfill — the budget stays unfilled rather than
+  // padding the narrative with a fact that barely earned a place. Nothing is
+  // lost: it is still returned in `cut`, still reachable through the escape.
+  const eligible = [];
+  for (const item of scored) {
+    if (item.score < config.minScore) cut.push({ row: item.row, family: item.family, reason: "below-floor", score: item.score });
+    else eligible.push(item);
+  }
+
+  // Breadth-first cut to budget: each family sorted by score (tie broken by
+  // object label for determinism), then pulled round-robin in family priority
+  // order so the digest covers relations before it repeats one.
+  const byFamily = new Map();
+  for (const item of eligible) {
+    if (!byFamily.has(item.family)) byFamily.set(item.family, []);
+    byFamily.get(item.family).push(item);
+  }
+  for (const list of byFamily.values()) {
+    list.sort((a, b) => b.score - a.score || a.row.object.localeCompare(b.row.object));
+  }
+  const orderedFamilies = FAMILY_PRIORITY.filter((f) => byFamily.has(f))
+    .concat([...byFamily.keys()].filter((f) => !FAMILY_PRIORITY.includes(f)).sort());
+  const selected = [];
+  let drained = false;
+  while (selected.length < budget && !drained) {
+    drained = true;
+    for (const family of orderedFamilies) {
+      const list = byFamily.get(family);
+      if (list && list.length) {
+        selected.push(list.shift());
+        drained = false;
+        if (selected.length >= budget) break;
+      }
+    }
+  }
+  // Whatever the round-robin left over is ranked detail, not noise — returned
+  // as budget-cut, still carrying its score, so the escape reaches it in order.
+  for (const family of orderedFamilies) {
+    for (const item of byFamily.get(family) || []) {
+      cut.push({ row: item.row, family: item.family, reason: "over-budget", score: item.score });
+    }
+  }
+  selected.sort((a, b) => {
+    const fa = FAMILY_PRIORITY.indexOf(a.family);
+    const fb = FAMILY_PRIORITY.indexOf(b.family);
+    return (fa - fb) || (b.score - a.score) || a.row.object.localeCompare(b.row.object);
+  });
+
+  return {
+    term,
+    selected,
+    cut,
+    senses: { split: senses.split, clusters: senses.clusters, dominantLabel },
+  };
+}

package/src/domain/digest/store-stats.mjs

@@ -0,0 +1,77 @@
+// digest/store-stats.mjs — the store-relative statistics the selector needs,
+// derived in one pass over the fact rows a caller already holds. Pure and
+// deterministic; imports only its sibling sense-split helpers, so it links into
+// a browser bundle the same way the rest of the digest layer does (the pages
+// digest client-side from an embedded structure table).
+//
+// selectFacts() scores an isa row partly by how many subjects across the store
+// share its object as a class: a class nearly everything is cut as
+// uninformative. That count, the total isa-subject population, and the
+// subClassOf/disjointWith edges the sense clustering walks are all one scan of
+// the rows away — this module is that scan, kept out of the pure selector so
+// the selector stays a function of its inputs.
+
+import { subClassParents, ancestryChain } from "../sense-split.mjs";
+
+// The predicates the digest groups under the isa family (kept in step with
+// select.mjs's FAMILY_OF): a subclass edge and a type edge both name a class
+// the subject belongs to.
+const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+
+/**
+ * The store-relative statistics selectFacts() reads, from one pass over `rows`:
+ *   - classSubjectCounts: { class -> distinct subjects that are isa it }
+ *   - totalSubjects:      distinct subjects that carry any isa fact
+ *   - subClassEdges:      [[child, parent], …] for the sense clustering
+ *   - disjointEdges:      [[a, b], …] stored owl:disjointWith pairs
+ */
+export function digestStoreStats(rows) {
+  const classSubjects = new Map(); // class -> Set(subject)
+  const isaSubjects = new Set();
+  const subClassEdges = [];
+  const disjointEdges = [];
+  for (const r of rows || []) {
+    if (!r || !r.predicate) continue;
+    if (ISA_PREDICATES.has(r.predicate)) {
+      isaSubjects.add(r.subject);
+      if (!classSubjects.has(r.object)) classSubjects.set(r.object, new Set());
+      classSubjects.get(r.object).add(r.subject);
+      subClassEdges.push([r.subject, r.object]);
+    } else if (r.predicate === "owl:disjointWith") {
+      disjointEdges.push([r.subject, r.object]);
+    }
+  }
+  const classSubjectCounts = {};
+  for (const [cls, subs] of classSubjects) classSubjectCounts[cls] = subs.size;
+  return { classSubjectCounts, totalSubjects: isaSubjects.size, subClassEdges, disjointEdges };
+}
+
+/**
+ * Ancestry chains for a set of isa objects, keyed object -> [object, parent, …],
+ * so a lone isa fact can render as "a mammal, and so an animal". Built from the
+ * store's subClassOf edges; an object with no recorded parent is omitted.
+ */
+export function chainsForObjects(subClassEdges, objects, cap = 6) {
+  const parents = subClassParents(subClassEdges || []);
+  const chains = {};
+  for (const obj of objects || []) {
+    if (obj in chains) continue;
+    const chain = ancestryChain(obj, parents, { cap });
+    if (chain.length > 1) chains[obj] = chain;
+  }
+  return chains;
+}
+
+/** The isa objects among a term's rows, first-seen order — the set worth an
+ *  ancestry chain. */
+export function isaObjectsOf(rows) {
+  const out = [];
+  const seen = new Set();
+  for (const r of rows || []) {
+    if (!r || !ISA_PREDICATES.has(r.predicate)) continue;
+    if (seen.has(r.object)) continue;
+    seen.add(r.object);
+    out.push(r.object);
+  }
+  return out;
+}

package/src/domain/digest/structures.mjs

@@ -0,0 +1,100 @@
+// digest/structures.mjs — stage 2 of the digest layer: validate the
+// hand-authored sentence-structure bank and render one clause from a set of
+// facts of a single relation family. Pure and deterministic; the raw parsed
+// TOML rides in from a composition point exactly the way the construction banks
+// do (the strategy never reads the filesystem), so this module imports only its
+// sibling word helpers.
+
+import { articleFor, pluralOf, capitalizeFirst, series } from "./words.mjs";
+
+const VALID_FAMILIES = new Set(["isa", "location", "partOf", "capableOf", "usedFor"]);
+const VALID_FORMS = new Set(["single", "several", "chained"]);
+
+const keyFor = (family, form) => `${family}:${form}`;
+
+/**
+ * Validate and index the raw [[structure]] rows into a Map keyed by
+ * `family:form`. Closed-vocabulary discipline, same as the construction banks:
+ * an unknown family or form, or a missing template, drops the row rather than
+ * coercing it. First occurrence of a (family, form) wins; a later duplicate is
+ * ignored.
+ */
+export function buildStructureTable(structures) {
+  const table = new Map();
+  for (const s of structures || []) {
+    if (!s || typeof s.family !== "string" || !VALID_FAMILIES.has(s.family)) continue;
+    if (typeof s.form !== "string" || !VALID_FORMS.has(s.form)) continue;
+    if (typeof s.template !== "string" || !s.template.trim()) continue;
+    const key = keyFor(s.family, s.form);
+    if (table.has(key)) continue;
+    table.set(key, { family: s.family, form: s.form, template: s.template });
+  }
+  return table;
+}
+
+const withArticle = (word) => `${articleFor(word)} ${word}`;
+
+/** Render "a mammal, and so an animal" from an ancestry chain [mammal, animal, …]. */
+function renderChain(chain) {
+  const parts = (chain || []).map((c) => String(c || "").trim()).filter(Boolean);
+  if (!parts.length) return "";
+  const head = withArticle(parts[0]);
+  const rest = parts.slice(1);
+  if (!rest.length) return head;
+  return `${head}, and so ${series(rest.map(withArticle))}`;
+}
+
+/** The slot values for one render, derived from the term, its objects and an
+ *  optional ancestry chain. A placeholder with no derived value renders empty. */
+function slotsFor(term, objects, chain) {
+  const t = String(term || "").trim();
+  const objs = (objects || []).map((o) => String(o || "").trim()).filter(Boolean);
+  const first = objs[0] || "";
+  return {
+    TERM: t,
+    TERM_CAP: capitalizeFirst(t),
+    A_TERM: withArticle(t),
+    A_TERM_CAP: capitalizeFirst(withArticle(t)),
+    TERMS: pluralOf(t),
+    TERMS_CAP: capitalizeFirst(pluralOf(t)),
+    PRONOUN: "it",
+    PRONOUN_CAP: "It",
+    OBJECT: first,
+    A_OBJECT: first ? withArticle(first) : "",
+    OBJECTS_A: series(objs.map(withArticle)),
+    OBJECTS_PLURAL: series(objs.map(pluralOf)),
+    OBJECTS_RAW: series(objs),
+    CHAIN: renderChain(chain && chain.length ? chain : objs.slice(0, 1)),
+  };
+}
+
+/** Substitute every `{SLOT}` in `template` with its value (empty when absent),
+ *  then collapse any doubled spaces the empty slots left. */
+function fill(template, slots) {
+  return String(template)
+    .replace(/\{([A-Z_]+)\}/g, (_, name) => (name in slots ? slots[name] : ""))
+    .replace(/\s+/g, " ")
+    .replace(/\s+([.,;])/g, "$1")
+    .trim();
+}
+
+/**
+ * Render one clause for `facts` (all of one family) using the structure the
+ * table holds for (family, form). `form` defaults by fact count — one fact is
+ * "single", more is "several" — unless the caller names a form (e.g. "chained"
+ * with an ancestry chain). Returns { text, rows, family, form } so the sentence
+ * traces to the exact fact rows behind it, or null when no structure matches or
+ * there are no facts.
+ */
+export function renderStructure(table, family, facts, opts = {}) {
+  const rows = (facts || []).filter(Boolean);
+  if (!rows.length) return null;
+  const term = opts.term ?? rows[0].subject ?? "";
+  const form = opts.form || (rows.length > 1 ? "several" : "single");
+  const entry = table instanceof Map ? table.get(keyFor(family, form)) : null;
+  if (!entry) return null;
+  const objects = rows.map((r) => r.object);
+  const text = fill(entry.template, slotsFor(term, objects, opts.chain));
+  if (!text) return null;
+  return { text, rows, family, form };
+}

package/src/domain/digest/words.mjs

@@ -0,0 +1,40 @@
+// digest/words.mjs — the small, self-contained English surface helpers the
+// digest layer needs to turn a bare class label into a readable noun phrase:
+// the indefinite article, a regular plural, and first-letter casing. Kept
+// local (not imported from inflect.mjs) so the whole digest layer ships as one
+// self-contained unit — inflect.mjs is excluded from the published package.
+
+const VOWEL_START = /^[aeiou]/i;
+
+/** "a" or "an" for the following word, by its leading letter. A blank word
+ *  yields "a" (the caller never renders a phrase around an empty label). */
+export function articleFor(word) {
+  return VOWEL_START.test(String(word || "").trim()) ? "an" : "a";
+}
+
+/** The regular English plural of a lemma — the same -s/-es/-ies rules the rest
+ *  of the codebase uses, no irregular table. */
+export function pluralOf(word) {
+  const w = String(word || "").trim();
+  if (!w) return 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`;
+}
+
+/** Upper-case the first character only, leaving the rest of the phrase as-is
+ *  (so "aardvark" -> "Aardvark", but "DNA sequence" keeps its inner caps). */
+export function capitalizeFirst(text) {
+  const t = String(text || "");
+  return t ? t[0].toUpperCase() + t.slice(1) : t;
+}
+
+/** Join a list of phrases as an English series: "a", "a and b",
+ *  "a, b, and c" (Oxford comma, deterministic). */
+export function series(items) {
+  const parts = (items || []).map((s) => String(s || "").trim()).filter(Boolean);
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+  return `${parts.slice(0, -1).join(", ")}, and ${parts[parts.length - 1]}`;
+}

package/src/services/chat-session.mjs

@@ -28,6 +28,7 @@ import * as defaultSource from "../adapters/source.mjs";
 import { resolveExtensions, mergedLexiconExtra } from "./extensions.mjs";
 import { runTurn, hasSeededVocabulary, vocabExampleHint } from "./chat.mjs";
 import { resolveGameConfig } from "../domain/game-config.mjs";
+import { emptyRecord, resolveDiscourseConfig } from "../domain/discourse.mjs";
 import { resolveResearchConfig } from "./research.mjs";
 import { sessionLogHeaderMarkdown, sessionLogTurnMarkdown, sessionLogEndMarkdown } from "./session-log-format.mjs";
 
@@ -209,6 +210,13 @@ export async function createSession({
   // the flag/env tiers above stay authoritative when set.
   if (toml?.corpus?.tier === "tier3") liveReferenceOn = true;
 
+  // tmct.toml's [graph] read_only turns any session against this repo into a
+  // read-only one, exactly as --ephemeral does: the graph is read for
+  // structure but nothing (upsert, logs, memory) is written back into the
+  // repo's .tmct/. Committed example fixtures carry it so a plain
+  // `tmct chat --repo examples/<x>` never mutates the hand-stamped graph.
+  if (toml?.graph?.readOnly) ephemeral = true;
+
   // Ephemeral: keep config.graphFile pointing at the READ graph, but divert the
   // write base (repo → logs/memory/sessions) to a throwaway temp dir. The committed
   // target is never touched; the demo's memory simply doesn't persist across runs.
@@ -344,6 +352,9 @@ export async function createSession({
   let last = null;  // the last dispatched answer ({query,answer,detail}) — why/say-more re-renders it
   let planState = null; // the in-progress plan (goals/moves/cursor) — cleared by completion or a fresh goal, never by an aside
   let researchState = null; // the in-progress research queue — advanced by "research next", cleared by completion or "research stop"
+  // The typed discourse record ([discourse] max_referents caps it) — session-scoped
+  // like the focus, threaded turn to turn, never persisted.
+  let discourseRecord = emptyRecord(resolveDiscourseConfig(toml));
   let closed = false;
 
   return {
@@ -368,7 +379,7 @@ export async function createSession({
     async turn(line) {
       let result;
       try {
-        result = await runTurn(line, { config, source, graph, focus, last, memoryDir, sessionId, env, lexicon, narrate: narrateOn, liveReference: liveReferenceOn, vocabHint, tel, biasByBundle, planState, gameConfig, researchState, researchConfig });
+        result = await runTurn(line, { config, source, graph, focus, last, memoryDir, sessionId, env, lexicon, narrate: narrateOn, liveReference: liveReferenceOn, vocabHint, tel, biasByBundle, planState, gameConfig, researchState, researchConfig, discourse: discourseRecord });
       } catch (e) {
         const ts = new Date().toISOString();
         const message = e instanceof Error ? e.message : String(e);
@@ -384,6 +395,7 @@ export async function createSession({
       last = nextLast;
       if ("planState" in result) planState = result.planState;
       if ("researchState" in result) researchState = result.researchState;
+      if ("discourse" in result) discourseRecord = result.discourse;
       // /narrate on|off and /wiki on|off (runCommand) ride the turn RESULT the
       // same way a focus update does — apply them to this handle's
       // session-scoped state.