@polycode-projects/the-mechanical-code-talker 2.10.3 → 2.11.0

package/src/adapters/corpus/wikipedia-live.mjs

@@ -13,24 +13,55 @@
 // The provider seam mirrors reference-pack.mjs's: registerLiveReferenceProvider
 // swaps the whole lookup behind one async { lookup(normTerm) } contract (tests
 // and the demo page stub it); null restores the default provider below.
+//
+// The research lane rides the same provider factory against
+// simple.wikipedia.org (registerResearchProvider/getResearchProvider below),
+// adding two fan-out reads: pageByTitle (an exact linked title costs ONE
+// round trip, no opensearch) and linkedTitles (the lead section's
+// namespace-0 links, document-ordered). Requests identify themselves per
+// Wikimedia's robot etiquette (WIKIMEDIA_USER_AGENT) and carry maxlag so an
+// overloaded replica set is backed off from, not hammered.
 
 import { normFactTerm } from "../../domain/hash.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { isReferenceArticleRow, sentencesUpTo, isaOf, SUMMARY_CHAR_CAP } from "../../domain/reference-pack.mjs";
 
 export const WIKIPEDIA_LIVE_ORIGIN = "https://en.wikipedia.org";
+export const SIMPLE_WIKIPEDIA_ORIGIN = "https://simple.wikipedia.org";
+
+/** The identification string Wikimedia's robot policy asks API clients to
+ *  carry, pointing at this project's public site as the contact. Browsers
+ *  refuse to override the User-Agent request header, so the API-recognised
+ *  Api-User-Agent header carries the same string there; under Node both are
+ *  sent. */
+export const WIKIMEDIA_USER_AGENT = "the-mechanical-code-talker (+https://polycode-projects.gitlab.io/the-mechanical-code-talker/)";
 
 const DEFAULT_TIMEOUT_MS = 4000;
 const DEFAULT_MIN_INTERVAL_MS = 2000;
 const RETRY_AFTER_FLOOR_MS = 5000;
+// Action-API requests carry maxlag so an overloaded replica set answers with
+// an error we back off from instead of adding to its load (Wikimedia's own
+// recommended default for non-interactive clients).
+const MAXLAG_SECONDS = 5;
 
 /**
- * A live-lookup provider: { lookup(normTerm) -> article row | null }.
+ * A live-lookup provider: { lookup(normTerm) -> article row | null }, plus
+ * the research fan-out surface: pageByTitle(title) fetches an exact title's
+ * summary in ONE round trip (no opensearch — a linked title is already
+ * exact), and linkedTitles(title) lists the namespace-0 articles the page's
+ * LEAD section links to, in document order.
  *
  * `fetchImpl` defaults to the global fetch; `origin` to en.wikipedia.org;
  * `lexicon` (optional) feeds the isa extraction. The row shape is the shipped
  * pack's own ({ term, title, text, summary, url, revid, isa? }), validated by
  * isReferenceArticleRow before it is ever returned.
+ *
+ * Throttle posture: every public method takes one "slot" gated by the
+ * minimum interval, the single-flight guard and any open cool-off. By
+ * default a caller that asks too soon gets null (the chat's clean-miss hook
+ * must never block a turn); with `waitForSlot: true` the method WAITS for
+ * the slot instead — the research queue's posture, where a false miss would
+ * be dishonest and the caller is already paced turn-by-turn.
  */
 export function createWikipediaLiveProvider({
   fetchImpl,
@@ -38,6 +69,8 @@ export function createWikipediaLiveProvider({
   timeoutMs = DEFAULT_TIMEOUT_MS,
   minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
   lexicon = null,
+  userAgent = WIKIMEDIA_USER_AGENT,
+  waitForSlot = false,
 } = {}) {
   const doFetch = fetchImpl ?? ((...args) => globalThis.fetch(...args));
   const cache = new Map(); // key -> row | null (hits AND settled misses)
@@ -45,18 +78,43 @@ export function createWikipediaLiveProvider({
   let coolOffUntil = 0;
   let inFlight = false;
 
+  const identifyingHeaders = () => {
+    if (!userAgent) return null;
+    const headers = { "Api-User-Agent": userAgent };
+    // A browser strips User-Agent as a forbidden header; only set it where
+    // no DOM says we are one (Node ships a global `navigator` these days, so
+    // `document` is the discriminating global).
+    if (typeof document === "undefined") headers["User-Agent"] = userAgent;
+    return headers;
+  };
+
+  function openCoolOff(retryAfterSeconds) {
+    const retryAfterMs = Number(retryAfterSeconds) * 1000;
+    coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+  }
+
   async function fetchJson(url) {
     const controller = typeof AbortController === "function" ? new AbortController() : null;
     const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
     try {
-      const res = await doFetch(url, controller ? { signal: controller.signal } : {});
+      const opts = {};
+      if (controller) opts.signal = controller.signal;
+      const headers = identifyingHeaders();
+      if (headers) opts.headers = headers;
+      const res = await doFetch(url, opts);
       if (res.status === 429) {
-        const retryAfterMs = Number(res.headers?.get?.("retry-after")) * 1000;
-        coolOffUntil = Date.now() + Math.max(retryAfterMs || 0, RETRY_AFTER_FLOOR_MS);
+        openCoolOff(res.headers?.get?.("retry-after"));
         return null;
       }
       if (!res.ok) return null;
-      return await res.json();
+      const body = await res.json();
+      // A maxlag rejection arrives as HTTP 200 with an error body (and a
+      // Retry-After header) — back off exactly as a 429 asks.
+      if (body?.error?.code === "maxlag") {
+        openCoolOff(res.headers?.get?.("retry-after"));
+        return null;
+      }
+      return body;
     } catch {
       return null;
     } finally {
@@ -64,6 +122,26 @@ export function createWikipediaLiveProvider({
     }
   }
 
+  /** When the next network slot opens: past the cool-off, past the minimum
+   *  interval since the last taken slot. */
+  const slotOpensAt = () => Math.max(coolOffUntil, lastLookupAt + minIntervalMs);
+
+  /** Take the one network slot, or report it unavailable. Default posture
+   *  returns false immediately (the clean-miss hook's "null, never block");
+   *  `waitForSlot` sleeps until the slot opens instead. */
+  async function takeSlot() {
+    for (;;) {
+      const now = Date.now();
+      if (!inFlight && now >= slotOpensAt()) {
+        lastLookupAt = now;
+        inFlight = true;
+        return true;
+      }
+      if (!waitForSlot) return false;
+      await new Promise((resolve) => setTimeout(resolve, Math.max(slotOpensAt() - now, 25)));
+    }
+  }
+
   /** The opensearch title whose normFactTerm fold equals or extends the key —
    *  the topic-drift guard: "quasar" may resolve to "Quasar" or "Quasars",
    *  never to a first suggestion about something else. */
@@ -76,12 +154,7 @@ export function createWikipediaLiveProvider({
     return null;
   }
 
-  async function roundTrips(key) {
-    const search = await fetchJson(
-      `${origin}/w/api.php?action=opensearch&format=json&origin=*&search=${encodeURIComponent(key)}&limit=3`,
-    );
-    const title = search ? matchingTitle(key, search) : null;
-    if (!title) return null;
+  async function summaryRow(key, title) {
     const summary = await fetchJson(
       `${origin}/api/rest_v1/page/summary/${encodeURIComponent(title.replace(/ /g, "_"))}`,
     );
@@ -103,25 +176,77 @@ export function createWikipediaLiveProvider({
     return isReferenceArticleRow(row) ? row : null;
   }
 
+  async function roundTrips(key) {
+    const search = await fetchJson(
+      `${origin}/w/api.php?action=opensearch&format=json&origin=*&maxlag=${MAXLAG_SECONDS}&search=${encodeURIComponent(key)}&limit=3`,
+    );
+    const title = search ? matchingTitle(key, search) : null;
+    if (!title) return null;
+    return summaryRow(key, title);
+  }
+
+  /** One slot-gated, cached operation: cache first (a settled hit or miss is
+   *  never refetched), then the slot, then `work()`, with every failure
+   *  cached as null so it never costs a second round trip. */
+  async function cachedFetch(cacheKey, work) {
+    if (cache.has(cacheKey)) return cache.get(cacheKey);
+    if (!(await takeSlot())) return null;
+    let value = null;
+    try {
+      value = await work();
+    } catch {
+      value = null;
+    } finally {
+      inFlight = false;
+    }
+    cache.set(cacheKey, value);
+    return value;
+  }
+
   return {
     async lookup(normTerm) {
       const key = String(normTerm ?? "");
       if (!key) return null;
-      if (cache.has(key)) return cache.get(key);
-      const now = Date.now();
-      if (inFlight || now < coolOffUntil || now - lastLookupAt < minIntervalMs) return null;
-      lastLookupAt = now;
-      inFlight = true;
-      let row = null;
-      try {
-        row = await roundTrips(key);
-      } catch {
-        row = null;
-      } finally {
-        inFlight = false;
-      }
-      cache.set(key, row);
-      return row;
+      return cachedFetch(key, () => roundTrips(key));
+    },
+
+    /** The summary for an EXACT title — one round trip, no opensearch. The
+     *  research queue's depth-1 fetch: a linked title came from the wiki
+     *  itself, so the fuzzy title match would only waste a request. */
+    async pageByTitle(title) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      return cachedFetch(`title\0${normFactTerm(t)}`, () => summaryRow(normFactTerm(t), t));
+    },
+
+    /** The namespace-0 articles the page's LEAD section links to, in document
+     *  order, capped at `limit`. One action-API round trip
+     *  (action=parse&prop=links&section=0): the lead is the smallest payload
+     *  that still orders links by how the article introduces its topic —
+     *  a full-page prop=links listing is alphabetical, which would make the
+     *  fan-out pick by spelling instead of relevance. Null on any failure. */
+    async linkedTitles(title, { limit = 25 } = {}) {
+      const t = String(title ?? "").trim();
+      if (!t) return null;
+      const listed = await cachedFetch(`links\0${normFactTerm(t)}`, async () => {
+        const parsed = await fetchJson(
+          `${origin}/w/api.php?action=parse&format=json&formatversion=2&origin=*&maxlag=${MAXLAG_SECONDS}&prop=links&redirects=1&page=${encodeURIComponent(t)}&section=0`,
+        );
+        const links = parsed?.parse?.links;
+        if (!Array.isArray(links)) return null;
+        const seen = new Set();
+        const out = [];
+        for (const link of links) {
+          if (!link || link.ns !== 0 || link.exists === false) continue;
+          const linkTitle = String(link.title ?? link["*"] ?? "").trim();
+          const folded = normFactTerm(linkTitle);
+          if (!linkTitle || !folded || seen.has(folded)) continue;
+          seen.add(folded);
+          out.push(linkTitle);
+        }
+        return out;
+      });
+      return Array.isArray(listed) ? listed.slice(0, Math.max(0, limit)) : null;
     },
   };
 }
@@ -143,3 +268,34 @@ export function getLiveReferenceProvider() {
   if (!defaultProvider) defaultProvider = createWikipediaLiveProvider();
   return defaultProvider;
 }
+
+// ---- the research lane's provider: Simple English Wikipedia, waiting slots --
+
+let defaultResearchProvider = null;
+let registeredResearchProvider = null;
+
+/** Swap the research lane's lookup: provider = { lookup, pageByTitle,
+ *  linkedTitles } (tests and the demo pages stub it, same seam shape as
+ *  registerLiveReferenceProvider). Pass null to restore the default
+ *  simple.wikipedia.org provider. */
+export function registerResearchProvider(provider) {
+  registeredResearchProvider = provider && typeof provider.lookup === "function" ? provider : null;
+}
+
+/** The research lane's active provider — the registered one, else one lazily
+ *  created singleton against simple.wikipedia.org with `waitForSlot` on: the
+ *  queue is paced turn-by-turn, so a throttled step WAITS for its polite slot
+ *  rather than reporting a false miss. `minIntervalMs` (first call only —
+ *  the singleton keeps its throttle clock) can only ever RAISE the interval;
+ *  the shipped minimum stays the floor. */
+export function getResearchProvider({ minIntervalMs } = {}) {
+  if (registeredResearchProvider) return registeredResearchProvider;
+  if (!defaultResearchProvider) {
+    defaultResearchProvider = createWikipediaLiveProvider({
+      origin: SIMPLE_WIKIPEDIA_ORIGIN,
+      waitForSlot: true,
+      minIntervalMs: Math.max(DEFAULT_MIN_INTERVAL_MS, Number(minIntervalMs) || 0),
+    });
+  }
+  return defaultResearchProvider;
+}

package/src/adapters/corpus/worlds-pack.mjs

@@ -15,7 +15,7 @@ import { readFileSync } from "node:fs";
 import { gunzipSync } from "node:zlib";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { isWorldsIndexEntry, isWorldRow, isWorldFactRow, isWorldRuleRow, isWorldMetaRow } from "../../domain/worlds-pack.mjs";
+import { isWorldsIndexEntry, isWorldRow, isWorldFactRow, isWorldRuleRow, isWorldMetaRow, expandWorldDefaultContents } from "../../domain/worlds-pack.mjs";
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 
@@ -84,7 +84,13 @@ export function loadWorld(dir, worldName) {
         else if (isWorldMetaRow(row) && !meta) meta = row;
       } catch { /* tolerated: a bad line loses one row, not the world */ }
     }
-    if (facts.length || rules.length || meta) payload = { name: worldName, facts, rules, meta };
+    // Class-default contents (library -> a book, kitchen -> a pan) are
+    // materialized here, the one choke point every loader path runs through
+    // (openAdventure, the site build, the tests) — never baked into the
+    // shipped shard, which stays a byte-copy of its hand-authored source.
+    if (facts.length || rules.length || meta) {
+      payload = { name: worldName, facts: expandWorldDefaultContents(facts), rules, meta };
+    }
   }
   worldCacheByKey.set(key, payload);
   return payload;

package/src/adapters/memory/core.mjs

@@ -94,7 +94,7 @@ const MEMORY_VOCABULARY = [
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
   { prop: CANONICALISED_FROM_PROP, predicate: "canonicalisedFrom", note: "subPropertyOf derivedFrom: a canonical Fact cleaned from a raw Block/Source, never replacing it" },
-  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | corpusWeak | reference | extracted | web | entailed (the trust-prior key)" },
+  { prop: "mgx:sourceType", note: "a Source's kind: operator | teach | provider | corpus | corpusWeak | reference | referenceLive | extracted | optimisticExtract | web | entailed (the trust-prior key)" },
   { prop: "mgx:sourceUrl", note: "a web Source's URL" },
   { prop: "mgx:sourceRule", note: "an entailed Source's rule id" },
   { prop: "mgx:sourceReliability", note: "actor-level (session-scoped) trust nudge in [0.5,1.5], neutral 1.0 when absent — materialised by recomputeSourceReliability from a session's asserted-vs-contradicted track record (memory/trust.mjs's sessionReliabilityFrom); folds into computeTrust's per-source prior" },
@@ -772,8 +772,13 @@ function sourceIdFor(desc) {
     // One Source per pack article (the @revid stays in the article segment),
     // so two facts from the same article corroborate nothing extra.
     case "reference": return { id: `src:reference:${desc.pack}:${desc.article}`, type: "reference" };
+    // The live-Wikipedia pack: same per-article Source id, but a lower trust
+    // type so a live lookup ranks below the curated revision-pinned pack.
+    case "referenceLive": return { id: `src:reference:${desc.pack}:${desc.article}`, type: "referenceLive" };
     // One Source per source-file basename, not per extraction run.
     case "extracted": return { id: `src:extracted:${desc.name}`, type: "extracted" };
+    // The fuzzy tier's candidates: one low-trust Source per source label.
+    case "optimisticExtract": return { id: `src:optimistic-extract:${desc.name}`, type: "optimisticExtract" };
     case "web": return { id: `src:learned:web:${fnv1aHex(String(desc.url || ""))}`, type: "web", url: String(desc.url || "") };
     case "entailed": return { id: `src:entailed:${desc.rule}`, type: "entailed", rule: String(desc.rule || "") };
     default: return null;
@@ -794,8 +799,10 @@ const PROV_CLASS_BY_SOURCE_TYPE = Object.freeze({
   corpus: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   corpusWeak: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   reference: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
+  referenceLive: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   web: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   extracted: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
+  optimisticExtract: { subClass: "tmct:DocumentSource", prov: "prov:Entity" },
   entailed: { subClass: "tmct:ActivitySource", prov: "prov:Activity" },
 });
 

package/src/adapters/toml-config.mjs

@@ -125,6 +125,12 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (src.games !== undefined) cfg.games = src.games;
   if (src.planning !== undefined) cfg.planning = src.planning;
 
+  // Research-lane knobs (src/services/research.mjs): sparse PASS-THROUGH,
+  // same discipline as [games.*] — the raw `[research]` table
+  // (fanout_limit / depth_limit / min_interval_ms, snake_case) rides through
+  // unmodified; clamping and default-filling is resolveResearchConfig's job.
+  if (src.research !== undefined) cfg.research = src.research;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;

package/src/domain/cli-verbs.mjs

@@ -92,6 +92,8 @@ export const CLI_VERBS = [
       { flag: "[--file <text-file>]", prose: ["teach recognizer and keep the facts it grounds; every", "other sentence is skipped and counted, never paraphrased"] },
       { flag: "[--repo <abs>]", prose: ["write the facts into that repo's own tmct memory; without", "it nothing on disk is mutated and the facts print as JSONL"] },
       { flag: "[--out <file.jsonl>]", prose: ["write that JSONL to a file instead of stdout"] },
+      { flag: "[--optimistic]", prose: ["also run a lower-trust fuzzy tier over the sentences the", "strict recognizer skips; candidates rank below every curated pack"] },
+      { flag: "[--canonical]", prose: ["print each grounded fact as a triple linked into the store"] },
     ],
   },
   {

package/src/domain/memory/trust.mjs

@@ -46,10 +46,25 @@ function parseChatTagRest(rest) {
  *   reference:<pack>:<article>[@revid] -> { kind:"reference", pack, article }
  *     (split on the first two colons only; the article keeps any @revid and
  *      any spaces — "reference:simplewiki:Polar bear@912" stays one article)
+ *     EXCEPT the live-Wikipedia pack: reference:wikipedia-live:<article> parses
+ *      as kind "referenceLive", which scores below the curated revision-pinned
+ *      pack, so a live lookup never outranks the shipped article on the same term.
  *   extracted:<file-basename>  -> { kind:"extracted", name:<file-basename> }
+ *   optimistic-extract:<file-basename> -> { kind:"optimisticExtract", name }
+ *     (the fuzzy tier of `tmct extract --optimistic`: a candidate the strict
+ *      recognizer skipped, stored under its OWN low prior so it never
+ *      corroborates a curated pack — no operator/teach tag rides alongside)
  *   entailed:<rule>            -> { kind:"entailed",  rule:<rule> }
  * chat:/session: refs map to the operator; an unknown tag -> null (no Source).
  */
+// The one reference pack whose content is fetched live at query time rather
+// than shipped revision-pinned. Its facts score at the referenceLive prior
+// (below curated `reference`), so a live lookup never outranks the shipped pack.
+// Must equal reference-pack.mjs's LIVE_PACK_NAME; kept as a local literal so
+// trust.mjs stays import-free of the lexicon-loading pack module.
+const LIVE_REFERENCE_PACK = "wikipedia-live";
+const referenceKindFor = (pack) => (pack === LIVE_REFERENCE_PACK ? "referenceLive" : "reference");
+
 export function provenanceTagToSource(tag) {
   const t = String(tag || "").trim();
   if (!t) return null;
@@ -59,7 +74,19 @@ export function provenanceTagToSource(tag) {
     const rest = t.slice("reference:".length);
     const colon = rest.indexOf(":");
     if (colon < 0) return { kind: "reference", pack: rest || "unknown", article: "" };
-    return { kind: "reference", pack: rest.slice(0, colon) || "unknown", article: rest.slice(colon + 1) };
+    const pack = rest.slice(0, colon) || "unknown";
+    return { kind: referenceKindFor(pack), pack, article: rest.slice(colon + 1) };
+  }
+  // research:<topic>@<depth> — the research lane's Simple English Wikipedia
+  // loads. Live-fetched at query time like the wikipedia-live pack, so it
+  // scores at the same referenceLive prior, below every curated pack. Parsed
+  // from the FULL tag (a topic may contain spaces); the depth segment records
+  // how far the fan-out reached and is not part of the Source identity.
+  if (t.startsWith("research:")) {
+    const rest = t.slice("research:".length);
+    const at = rest.lastIndexOf("@");
+    const topic = (at >= 0 ? rest.slice(0, at) : rest).trim();
+    return { kind: "referenceLive", pack: "research", article: topic || "unknown" };
   }
   const head = t.split(/\s+/)[0]; // drop trailing " /r/IsA" etc.
   if (head.startsWith("corpus-weak:")) return { kind: "corpusWeak", name: head.slice("corpus-weak:".length) || "unknown" };
@@ -78,6 +105,7 @@ export function provenanceTagToSource(tag) {
   }
   if (head.startsWith("web:")) return { kind: "web", url: head.slice("web:".length) };
   if (head.startsWith("url:")) return { kind: "web", url: head.slice("url:".length) };
+  if (head.startsWith("optimistic-extract:")) return { kind: "optimisticExtract", name: head.slice("optimistic-extract:".length) || "unknown" };
   if (head.startsWith("extracted:")) return { kind: "extracted", name: head.slice("extracted:".length) || "unknown" };
   if (head.startsWith("entailed:")) return { kind: "entailed", rule: head.slice("entailed:".length) };
   if (head.startsWith("chat:") || head.startsWith("session:") || head.startsWith("operator")) return { kind: "operator" };
@@ -93,8 +121,10 @@ export const SOURCE_PRIOR = Object.freeze({
   corpus: 0.7,
   reference: 0.6,
   corpusWeak: 0.55,
-  web: 0.4,
+  referenceLive: 0.5,
   extracted: 0.45,
+  web: 0.4,
+  optimisticExtract: 0.35,
   entailed: 0.3,
 });
 

package/src/domain/sense-split.mjs

@@ -0,0 +1,203 @@
+// sense-split.mjs — word-sense discrimination over a taught/stored class
+// hierarchy. When one label carries two is-a facts ("rover is a kind of dog",
+// "rover is a kind of scout"), their superclass ancestries decide whether the
+// two end classes name the same concept or two different ones. The verdict is
+// an implicit owl:differentFrom between the senses; the mechanism is pure and
+// deterministic over the stored subClassOf closure and any stored
+// owl:disjointWith pairs — never a model.
+//
+// The distinctness test, in order:
+//   1. one class subsumes the other  -> same lineage, not distinct.
+//   2. any ancestor pair is disjoint -> distinct (the cax-dw ⊑-lift, read-only).
+//   3. ancestries never meet below ⊤ -> distinct (wholly non-intersecting).
+//   4. the least common subsumer is a root, or scores below threshold on a
+//      Wu-Palmer depth ratio (or a supplied Resnik information-content map)
+//                                    -> distinct.
+//   5. otherwise                     -> not distinct.
+
+import { SUBCLASS_PREDICATE } from "./syllogise.mjs";
+
+/** child term -> Set of its direct superclasses, from `[child, parent]` edges.
+ *  Self-loops and blank endpoints are dropped. */
+export function subClassParents(subClassEdges) {
+  const parents = new Map();
+  for (const [child, parent] of subClassEdges || []) {
+    if (!child || !parent || child === parent) continue;
+    if (!parents.has(child)) parents.set(child, new Set());
+    parents.get(child).add(parent);
+  }
+  return parents;
+}
+
+/** The single rendering chain above `term` — `[term, parent, grandparent, …]`
+ *  — following one deterministic (lowest-sorted) parent per hop, capped at
+ *  `cap` nodes, cycle-safe. A branch point still yields one readable line;
+ *  the full-ancestor-set comparisons below never rely on this single path. */
+export function ancestryChain(term, parents, { cap = 6 } = {}) {
+  const chain = [term];
+  const seen = new Set([term]);
+  let node = term;
+  while (chain.length < cap) {
+    const ups = [...(parents.get(node) || [])].filter((p) => !seen.has(p)).sort();
+    if (!ups.length) break;
+    node = ups[0];
+    seen.add(node);
+    chain.push(node);
+  }
+  return chain;
+}
+
+/** Every ancestor of `term`, including `term` itself, as a Set. Cycle-safe,
+ *  bounded by the reachable set. */
+export function ancestorSet(term, parents, { cap = 64 } = {}) {
+  const seen = new Set([term]);
+  const queue = [term];
+  while (queue.length && seen.size < cap) {
+    const node = queue.shift();
+    for (const p of parents.get(node) || []) {
+      if (!seen.has(p)) { seen.add(p); queue.push(p); }
+    }
+  }
+  return seen;
+}
+
+/** Depth from a root, measured as the LONGEST upward chain length: a root
+ *  (no parents) is depth 1, its children depth 2, and so on. Deterministic and
+ *  cycle-safe; used for the Wu-Palmer ratio and to pick the deepest common
+ *  subsumer as the least common subsumer. */
+function depthFrom(term, parents, memo, stack) {
+  if (memo.has(term)) return memo.get(term);
+  if (stack.has(term)) return 1; // cycle guard — treat the re-entry as a root
+  stack.add(term);
+  const ups = parents.get(term);
+  let depth = 1;
+  if (ups && ups.size) {
+    let deepest = 0;
+    for (const p of ups) deepest = Math.max(deepest, depthFrom(p, parents, memo, stack));
+    depth = deepest + 1;
+  }
+  stack.delete(term);
+  memo.set(term, depth);
+  return depth;
+}
+
+/** A symmetric lookup "is A disjoint with B" over stored owl:disjointWith
+ *  pairs. Both directions of every pair are indexed. */
+function disjointIndex(disjointEdges) {
+  const of = new Map();
+  for (const [a, b] of disjointEdges || []) {
+    if (!a || !b) continue;
+    if (!of.has(a)) of.set(a, new Set());
+    of.get(a).add(b);
+    if (!of.has(b)) of.set(b, new Set());
+    of.get(b).add(a);
+  }
+  return of;
+}
+
+/** Decide whether classes `a` and `b` name distinct concepts, given the parent
+ *  index, the disjointness index, a depth memo, and the scoring options.
+ *  Returns `{ distinct, reason, lcs }`. */
+function pairVerdict(a, b, parents, disjointOf, depthMemo, { threshold, rootDepth, icByTerm }) {
+  const ancA = ancestorSet(a, parents);
+  const ancB = ancestorSet(b, parents);
+  if (ancA.has(b) || ancB.has(a)) return { distinct: false, reason: "subsumes", lcs: ancA.has(b) ? b : a };
+
+  if (disjointOf.size) {
+    for (const x of ancA) {
+      const partners = disjointOf.get(x);
+      if (!partners) continue;
+      for (const y of ancB) if (partners.has(y)) return { distinct: true, reason: "disjoint", lcs: null };
+    }
+  }
+
+  const common = [...ancA].filter((x) => ancB.has(x));
+  if (!common.length) {
+    // Non-intersection only means "distinct" when both sides carry real
+    // ancestry evidence. A bare class with no recorded superclass tells us
+    // nothing about its sense — a sparse taxonomy that simply never linked
+    // two storage classes must not read as two concepts. Inconclusive keeps
+    // the flat list.
+    if (ancA.size < 2 || ancB.size < 2) return { distinct: false, reason: "inconclusive", lcs: null };
+    return { distinct: true, reason: "non-intersecting", lcs: null };
+  }
+
+  const depth = (t) => depthFrom(t, parents, depthMemo, new Set());
+  let lcs = common[0];
+  let lcsDepth = depth(lcs);
+  for (const c of common) {
+    const d = depth(c);
+    if (d > lcsDepth || (d === lcsDepth && c < lcs)) { lcs = c; lcsDepth = d; }
+  }
+
+  if (lcsDepth <= rootDepth) return { distinct: true, reason: "root-subsumer", lcs };
+
+  if (icByTerm) {
+    const ic = icByTerm.get(lcs);
+    if (typeof ic === "number" && ic < threshold) return { distinct: true, reason: "low-ic", lcs };
+    return { distinct: false, reason: "shared-lineage", lcs };
+  }
+
+  const wuPalmer = (2 * lcsDepth) / (depth(a) + depth(b));
+  if (wuPalmer < threshold) return { distinct: true, reason: "shallow-subsumer", lcs };
+  return { distinct: false, reason: "shared-lineage", lcs };
+}
+
+/** Cluster same-predicate end classes into senses. Two classes join the same
+ *  sense when they are NOT distinct (union-find over the pairwise verdicts);
+ *  the answer splits when more than one cluster survives.
+ *
+ *  Options:
+ *   - subClassEdges / parents: the taxonomy (`parents` wins if both given).
+ *   - disjointEdges: stored owl:disjointWith pairs.
+ *   - threshold: Wu-Palmer ratio (or Resnik IC) below which a shared subsumer
+ *     still reads as two senses. Default 0.5.
+ *   - rootDepth: a subsumer at or above this shallow depth is treated as ⊤.
+ *     Default 1 (only the very root).
+ *   - icByTerm: an optional term->information-content map; when supplied the
+ *     LCS is scored by Resnik IC instead of the Wu-Palmer depth ratio.
+ *
+ *  Returns `{ split, clusters, pairs }`. Each cluster is
+ *  `{ objects, label }` where `label` is the cluster's most specific class.
+ *  `pairs` records every pairwise verdict for inspection/tests. */
+export function clusterSenses(objects, {
+  subClassEdges = [], parents: parentsIn = null, disjointEdges = [],
+  threshold = 0.5, rootDepth = 1, icByTerm = null,
+} = {}) {
+  const unique = [...new Set((objects || []).filter(Boolean))];
+  const parents = parentsIn || subClassParents(subClassEdges);
+  const disjointOf = disjointIndex(disjointEdges);
+  const depthMemo = new Map();
+
+  const parent = new Map(unique.map((o) => [o, o]));
+  const find = (x) => { while (parent.get(x) !== x) { parent.set(x, parent.get(parent.get(x))); x = parent.get(x); } return x; };
+  const union = (a, b) => { const ra = find(a), rb = find(b); if (ra !== rb) parent.set(ra < rb ? rb : ra, ra < rb ? ra : rb); };
+
+  const pairs = [];
+  for (let i = 0; i < unique.length; i += 1) {
+    for (let j = i + 1; j < unique.length; j += 1) {
+      const v = pairVerdict(unique[i], unique[j], parents, disjointOf, depthMemo, { threshold, rootDepth, icByTerm });
+      pairs.push({ a: unique[i], b: unique[j], ...v });
+      if (!v.distinct) union(unique[i], unique[j]);
+    }
+  }
+
+  const byRoot = new Map();
+  for (const o of unique) {
+    const r = find(o);
+    if (!byRoot.has(r)) byRoot.set(r, []);
+    byRoot.get(r).push(o);
+  }
+  const depth = (t) => depthFrom(t, parents, depthMemo, new Set());
+  const clusters = [...byRoot.values()].map((members) => {
+    const sorted = [...members].sort();
+    let label = sorted[0];
+    let best = depth(label);
+    for (const m of sorted) { const d = depth(m); if (d > best) { best = d; label = m; } }
+    return { objects: sorted, label };
+  }).sort((x, y) => x.label.localeCompare(y.label));
+
+  return { split: clusters.length > 1, clusters, pairs };
+}
+
+export { SUBCLASS_PREDICATE };