@polycode-projects/the-mechanical-code-talker 1.10.14 → 1.11.5

package/src/router/registry.mjs

@@ -179,10 +179,54 @@ const CAPABILITIES = Object.freeze([
   }),
 ]);
 
-// A frozen name→capability index (built once).
-const BY_NAME = Object.freeze(
-  CAPABILITIES.reduce((m, c) => { m[c.name] = c; return m; }, Object.create(null)),
+// The live capability set: the built-in frozen array is the seed; registration
+// rebuilds `list`/`byName` wholesale so every accessor stays a plain read.
+const buildIndex = (caps) => Object.freeze(
+  caps.reduce((m, c) => { m[c.name] = c; return m; }, Object.create(null)),
 );
+let list = CAPABILITIES;
+let byName = buildIndex(list);
+
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const k of Object.keys(value)) deepFreeze(value[k]);
+  }
+  return value;
+}
+
+/** Register a capability at runtime (e.g. a taught action family bridged in by
+ *  src/router/taught.mjs). `readOnly` must be an explicit boolean; a
+ *  `readOnly: false` record is forced `dispatchable: false` — the guardrail's
+ *  candidate enrichment re-dispatches a tool once per tied candidate, which is
+ *  only safe when dispatch performs no writes. Returns an `unregister()`
+ *  disposer. */
+export function registerCapability(cap) {
+  const name = cap && typeof cap.name === "string" ? cap.name.trim() : "";
+  if (!name) throw new Error("registerCapability: a non-empty name is required");
+  if (byName[name]) throw new Error(`registerCapability: "${name}" is already registered`);
+  if (!Array.isArray(cap.parameters) || !Array.isArray(cap.preconditions)) {
+    throw new Error(`registerCapability: "${name}" needs parameters[] and preconditions[]`);
+  }
+  if (!cap.effects || !Array.isArray(cap.effects.add) || !Array.isArray(cap.effects.del)) {
+    throw new Error(`registerCapability: "${name}" needs effects {add: [], del: []}`);
+  }
+  if (typeof cap.readOnly !== "boolean") {
+    throw new Error(`registerCapability: "${name}" needs an explicit boolean readOnly`);
+  }
+  const rec = deepFreeze({
+    type: VOCAB.Capability,
+    ...cap,
+    name,
+    dispatchable: cap.readOnly === true ? cap.dispatchable !== false : false,
+  });
+  list = Object.freeze([...list, rec]);
+  byName = buildIndex(list);
+  return function unregister() {
+    list = Object.freeze(list.filter((c) => c !== rec));
+    byName = buildIndex(list);
+  };
+}
 
 // ---- unregistered dispatch tools ---------------------------------------------
 // Dispatch tools not yet registered; each names the precondition work it needs first.
@@ -199,28 +243,28 @@ export const REGISTRY = Object.freeze({
   vocab: VOCAB,
   kinds: KINDS,
   precond: PRECOND,
-  capabilities: CAPABILITIES,
+  get capabilities() { return list; },
 });
 
 // ---- pure accessors ---------------------------------------------------------
 
-/** All declared capabilities (the operator set). */
-export function capabilities() { return CAPABILITIES; }
+/** All declared capabilities (the operator set, plus any registered at runtime). */
+export function capabilities() { return list; }
 
 /** The capability named `n`, or undefined. */
-export function capabilityByName(n) { return BY_NAME[n]; }
+export function capabilityByName(n) { return byName[n]; }
 
 /** True iff `n` names a declared capability. */
-export function isCapability(n) { return Boolean(BY_NAME[n]); }
+export function isCapability(n) { return Boolean(byName[n]); }
 
 /** The parameter slots of capability `n` (empty array if unknown/no-arg). */
-export function parametersOf(n) { return BY_NAME[n]?.parameters ?? []; }
+export function parametersOf(n) { return byName[n]?.parameters ?? []; }
 
 /** The preconditions of capability `n` (the safety gate the guardrail checks). */
-export function preconditionsOf(n) { return BY_NAME[n]?.preconditions ?? []; }
+export function preconditionsOf(n) { return byName[n]?.preconditions ?? []; }
 
 /** The effects of capability `n` — `{ add, del }` (the proof-chain contribution). */
-export function effectsOf(n) { return BY_NAME[n]?.effects ?? { add: [], del: [] }; }
+export function effectsOf(n) { return byName[n]?.effects ?? { add: [], del: [] }; }
 
 /** The set of arg keys capability `n` accepts (for the guardrail's unknown-arg
  *  check). Returns a Set of strings. */

package/src/router/resolver.mjs

@@ -94,6 +94,19 @@ export function backwardChain(topic) {
   return null;
 }
 
+/** Backward-chain a WORLD goal — a state predicate like "rest-on" that a
+ *  taught action's effect establishes — to the registered record whose
+ *  add-list carries the matching taught:world-effect (the bridge
+ *  src/router/taught.mjs registers). Pure over the registry; null when no
+ *  taught record achieves the predicate. The sibling of backwardChain above,
+ *  which only ever matches epistemic `knows` effects. */
+export function backwardChainWorld(predicate) {
+  for (const cap of capabilities()) {
+    if (effectsOf(cap.name).add.some((e) => e.pred === "taught:world-effect" && e.predicate === predicate)) return cap;
+  }
+  return null;
+}
+
 // Stopwords for the imperative-frame entity extractor. Deliberately generous: a wrong
 // pick is caught by the resolveObject miss -> honest refuse, never emitted.
 const STOP = new Set([

package/src/router/taught.mjs

@@ -0,0 +1,84 @@
+// taught.mjs — bridge taught action-Rule families into the capability registry.
+//
+// A taught game action ("you can move a disk onto a peg" + its preconditions
+// and effect) becomes a registered capability record so the router's operator
+// model covers taught actions and built-in query tools alike. Registered
+// records carry readOnly: false, so the guardrail never dispatches them — the
+// resolver also never selects them on its own, because it backward-chains over
+// `knows` add-effects and these records carry world-triple effects instead.
+
+import { readRuleRows } from "../memory/core.mjs";
+import { capabilityByName, registerCapability } from "./registry.mjs";
+
+const ACTION_KINDS = new Set(["action-signature", "action-precond", "action-effect", "action-constraint"]);
+
+/** Group a memory payload's action-family rule rows by rule name. */
+export function actionFamilies(memory) {
+  const families = new Map();
+  for (const row of readRuleRows(memory)) {
+    if (!ACTION_KINDS.has(row.kind)) continue;
+    if (!families.has(row.name)) families.set(row.name, []);
+    families.get(row.name).push(row);
+  }
+  return families;
+}
+
+/** Map one action family to a registrable capability record. */
+export function capabilityFromActionRules(name, family) {
+  const signatures = family.filter((r) => r.kind === "action-signature");
+  const preconds = family.filter((r) => r.kind === "action-precond");
+  const effects = family.filter((r) => r.kind === "action-effect");
+  const constraints = family.filter((r) => r.kind === "action-constraint");
+  return {
+    name: `taught:${name}`,
+    label: name,
+    question: `apply the taught action "${name}" to the world state`,
+    readOnly: false,
+    parameters: [
+      { name: "subject", classes: [...new Set(signatures.map((s) => s.slots.subjectClass))].sort() },
+      { name: "target", classes: [...new Set(signatures.map((s) => s.slots.targetClass))].sort() },
+    ],
+    preconditions: [
+      ...preconds.map((p) => ({
+        pred: "taught:world-precond",
+        shape: p.slots.shape,
+        predicate: p.slots.predicate,
+        role: p.slots.role,
+        scope: p.slots.scope,
+      })),
+      // A constraint is a precondition on the SUCCESSOR state; it rides the
+      // record's precondition list so a bridged family stays complete.
+      ...constraints.map((c) => ({
+        pred: "taught:world-constraint",
+        left: c.slots.left,
+        right: c.slots.right,
+        guard: c.slots.guard,
+      })),
+    ],
+    effects: {
+      add: effects.map((e) => ({
+        pred: "taught:world-effect",
+        predicate: e.slots.predicate,
+        subjectRole: e.slots.subjectRole,
+        objectRole: e.slots.objectRole,
+      })),
+      del: effects.map((e) => ({
+        pred: "taught:world-effect-replaced",
+        predicate: e.slots.predicate,
+        subjectRole: e.slots.subjectRole,
+      })),
+    },
+  };
+}
+
+/** Register every taught action family in `memory`, idempotently (a name that
+ *  is already registered is skipped). Returns the new registrations'
+ *  unregister disposers. */
+export function registerTaughtActions(memory) {
+  const disposers = [];
+  for (const [name, family] of actionFamilies(memory)) {
+    if (capabilityByName(`taught:${name}`)) continue;
+    disposers.push(registerCapability(capabilityFromActionRules(name, family)));
+  }
+  return disposers;
+}

package/src/sentences.mjs

@@ -0,0 +1,19 @@
+// sentences.mjs — sentence-boundary splitting, shared by the extract-facts
+// script, the chat one-shot CLI, and runTurn's multi-sentence pre-split.
+
+import { winkInstance } from "./wink-model.mjs";
+
+/** Split text into trimmed, non-empty sentences via wink-nlp's own
+ *  sentence-boundary detection — never a naive regex split, matching the
+ *  ONE way every other adapter in this repo reaches wink (wink-model.mjs).
+ *  Returns [] (never throws) when wink isn't available or the text is
+ *  blank — the same honest-degrade idiom every wink-model.mjs consumer
+ *  already uses. */
+export function splitSentences(text) {
+  const nlp = winkInstance();
+  if (!nlp) return [];
+  const raw = String(text ?? "");
+  if (!raw.trim()) return [];
+  const doc = nlp.readDoc(raw);
+  return doc.sentences().out().map((s) => s.trim()).filter(Boolean);
+}

package/src/syllogise.mjs

@@ -694,6 +694,7 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
   const trustByTriple = new Map();
   for (const r of rows) trustByTriple.set(`${r.subject}${SEP}${r.predicate}${SEP}${r.object}`, r.trust);
   const premiseTrust = (s, p, o) => trustByTriple.get(`${s}${SEP}${p}${SEP}${o}`);
+  const hasTriple = (s, p, o) => trustByTriple.has(`${s}${SEP}${p}${SEP}${o}`);
   const numericOnly = (arr) => arr.filter((t) => typeof t === "number");
 
   const scmDerived = deriveSubClassClosure(subClassEdges, { depth, budget, focus: normalizedFocus });
@@ -732,11 +733,12 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
     ...scmDerived.map((d) => ({
       subject: d.subject, predicate: SUBCLASS_PREDICATE, object: d.object,
       provenance: ENTAILED_PROVENANCE,
-      // Persisted justification, scm-sco only: the two premise fact ids this
-      // conclusion rode (a⊑b, b⊑c) — content-addressed ids work even when a
-      // premise is itself an entailment this same pass just derived. Read
-      // back by retractSubClassOf (below) to find every entailment a
-      // retracted premise could have supported.
+      // Persisted justification: the premise fact ids this conclusion rode
+      // (a⊑b, b⊑c) — content-addressed ids work even when a premise is
+      // itself an entailment this same pass just derived. Read back by
+      // retractSubClassOf (below) to find every entailment a retracted
+      // premise could have supported. All five rules persist one, each
+      // citing its own premise shape.
       justification: [
         factIdForTriple(d.subject, SUBCLASS_PREDICATE, d.via),
         factIdForTriple(d.via, SUBCLASS_PREDICATE, d.object),
@@ -745,15 +747,24 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
     ...caxDerived.map((d) => ({
       subject: d.subject, predicate: TYPE_PREDICATE, object: d.object,
       provenance: ENTAILED_TYPE_PROVENANCE,
+      // The ⊑ premise is cited as the DIRECT via⊑object edge even when the
+      // taught chain is multi-hop: scm-sco materializes that edge (this same
+      // pass or an earlier one), and retraction re-VERIFIES every candidate
+      // anyway, so a citation left dangling by budget truncation is inert.
+      justification: [
+        factIdForTriple(d.subject, TYPE_PREDICATE, d.via),
+        factIdForTriple(d.via, SUBCLASS_PREDICATE, d.object),
+      ],
     })),
     ...dwDerived.map((d) => {
       // disjointWith is symmetric, taught as ONE direction — the premise row
-      // could be stored either (viaClass, disjointWith, object) or its mirror.
-      const dwTrust = premiseTrust(d.viaClass, DISJOINT_PREDICATE, d.object)
-        ?? premiseTrust(d.object, DISJOINT_PREDICATE, d.viaClass);
+      // could be stored either (viaClass, disjointWith, object) or its
+      // mirror; resolve which, so the justification cites a real stored id.
+      const dwStoredForward = hasTriple(d.viaClass, DISJOINT_PREDICATE, d.object);
+      const [dwS, dwO] = dwStoredForward ? [d.viaClass, d.object] : [d.object, d.viaClass];
       const premiseTrusts = numericOnly([
         premiseTrust(d.subject, TYPE_PREDICATE, d.viaType),
-        dwTrust,
+        premiseTrust(dwS, DISJOINT_PREDICATE, dwO),
         // the ⊑-lift premise only exists when this IS a lift (viaClass !==
         // viaType) — a direct hit has no extra subClassOf premise to price in.
         ...(d.viaClass !== d.viaType ? [premiseTrust(d.viaType, SUBCLASS_PREDICATE, d.viaClass)] : []),
@@ -761,6 +772,11 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
       return {
         subject: d.subject, predicate: DISJOINT_PREDICATE, object: d.object,
         provenance: ENTAILED_DISJOINT_PROVENANCE,
+        justification: [
+          factIdForTriple(d.subject, TYPE_PREDICATE, d.viaType),
+          factIdForTriple(dwS, DISJOINT_PREDICATE, dwO),
+          ...(d.viaClass !== d.viaType ? [factIdForTriple(d.viaType, SUBCLASS_PREDICATE, d.viaClass)] : []),
+        ],
         ...(premiseTrusts.length ? { premiseTrusts, ruleConfidence: CAX_DW_RULE_CONFIDENCE } : {}),
       };
     }),
@@ -777,6 +793,13 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
       return {
         subject: d.subject, predicate: TYPE_PREDICATE, object: d.object,
         provenance: ENTAILED_SVF1_PROVENANCE,
+        justification: [
+          factIdForTriple(d.subject, d.viaProperty, d.viaValue),
+          factIdForTriple(d.viaValue, TYPE_PREDICATE, d.viaType),
+          factIdForTriple(d.object, ON_PROPERTY_PREDICATE, d.viaPropertyKey),
+          factIdForTriple(d.object, SOME_VALUES_FROM_PREDICATE, d.viaTarget),
+          ...(d.viaType !== d.viaTarget ? [factIdForTriple(d.viaType, SUBCLASS_PREDICATE, d.viaTarget)] : []),
+        ],
         // same sub-1 discount as cax-dw, same reason (see CAX_DW_RULE_CONFIDENCE).
         ...(premiseTrusts.length ? { premiseTrusts, ruleConfidence: CLS_SVF1_RULE_CONFIDENCE } : {}),
       };
@@ -794,6 +817,13 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
       return {
         subject: d.subject, predicate: SUBCLASS_PREDICATE, object: d.object,
         provenance: ENTAILED_SCM_SVF_PROVENANCE,
+        justification: [
+          ...(r1 ? [factIdForTriple(d.subject, ON_PROPERTY_PREDICATE, r1.property)] : []),
+          factIdForTriple(d.subject, SOME_VALUES_FROM_PREDICATE, d.viaY1),
+          ...(r2 ? [factIdForTriple(d.object, ON_PROPERTY_PREDICATE, r2.property)] : []),
+          factIdForTriple(d.object, SOME_VALUES_FROM_PREDICATE, d.viaY2),
+          factIdForTriple(d.viaY1, SUBCLASS_PREDICATE, d.viaY2),
+        ],
         // same sub-1 discount as cax-dw/cls-svf1, same reason (see CAX_DW_RULE_CONFIDENCE).
         ...(premiseTrusts.length ? { premiseTrusts, ruleConfidence: SCM_SVF_RULE_CONFIDENCE } : {}),
       };
@@ -838,21 +868,112 @@ function isPurelyEntailed(provenance) {
   return tags.length > 0 && tags.every((t) => t.startsWith("entailed:"));
 }
 
+/** Builds the per-round VERIFY oracle for retraction: given ONLY the
+ *  surviving fact rows, returns `stillDerivable(row)` — true when the row's
+ *  (s,p,o) conclusion is re-derivable from survivors by the rule family that
+ *  owns its predicate (scm-sco/scm-svf1 for subClassOf, cax-sco/cls-svf1 for
+ *  rdf:type, cax-dw for disjointWith). One shared ancestor closure plus small
+ *  indexes per round, joining exactly what each derive kernel joins. Pure,
+ *  no I/O. */
+function buildSurvivorDerivabilityCheck(rows) {
+  const subClassEdges = [];
+  const typesOf = new Map();          // x -> Set(surviving direct type classes)
+  const disjointOf = new Map();       // term -> Set(disjoint partners), symmetric
+  const onPropertyOf = new Map();     // restriction -> owl:onProperty's object
+  const someValuesFromOf = new Map(); // restriction -> owl:someValuesFrom's object
+  const propertyEdgesOf = new Map();  // x -> [[normalized predicate, y], …]
+  for (const r of rows) {
+    const pLower = String(r.predicate || "").trim().toLowerCase();
+    if (isSubClassOf(r.predicate)) subClassEdges.push([r.subject, r.object]);
+    else if (isType(r.predicate)) {
+      if (!typesOf.has(r.subject)) typesOf.set(r.subject, new Set());
+      typesOf.get(r.subject).add(r.object);
+    } else if (isDisjoint(r.predicate)) {
+      if (!disjointOf.has(r.subject)) disjointOf.set(r.subject, new Set());
+      disjointOf.get(r.subject).add(r.object);
+      if (!disjointOf.has(r.object)) disjointOf.set(r.object, new Set());
+      disjointOf.get(r.object).add(r.subject);
+    } else if (isOnProperty(r.predicate)) onPropertyOf.set(r.subject, r.object);
+    else if (isSomeValuesFrom(r.predicate)) someValuesFromOf.set(r.subject, r.object);
+    else if (!RESERVED_PREDICATES.has(pLower)) {
+      if (!propertyEdgesOf.has(r.subject)) propertyEdgesOf.set(r.subject, []);
+      propertyEdgesOf.get(r.subject).push([normFactTerm(r.predicate), r.object]);
+    }
+  }
+  const ancestorsOf = buildAncestorCloser(subClassEdges);
+  const reaches = (a, b) => a !== b && ancestorsOf(a).has(b);
+  const restrictionOf = (node) => {
+    const property = onPropertyOf.get(node);
+    const target = someValuesFromOf.get(node);
+    return property && target ? { property: normFactTerm(property), target } : null;
+  };
+
+  return (row) => {
+    if (isSubClassOf(row.predicate)) {
+      // scm-sco: some surviving ⊑-path still connects subject to object.
+      if (reaches(row.subject, row.object)) return true;
+      // scm-svf1: both ends still declared restrictions over the SAME
+      // property, with strictly ⊑-related fillers (kernel-faithful).
+      const r1 = restrictionOf(row.subject);
+      const r2 = restrictionOf(row.object);
+      return Boolean(r1 && r2 && r1.property === r2.property && reaches(r1.target, r2.target));
+    }
+    if (isType(row.predicate)) {
+      // cax-sco: a surviving direct type whose ⊑-closure reaches the class.
+      for (const c of typesOf.get(row.subject) || []) {
+        if (reaches(c, row.object)) return true;
+      }
+      // cls-svf1: the class is a still-declared restriction node — a
+      // surviving property edge whose value's type (⊑-lifted) satisfies it.
+      const rec = restrictionOf(row.object);
+      if (rec) {
+        for (const [pKey, y] of propertyEdgesOf.get(row.subject) || []) {
+          if (pKey !== rec.property) continue;
+          for (const c of typesOf.get(y) || []) {
+            if (c === rec.target || reaches(c, rec.target)) return true;
+          }
+        }
+      }
+      return false;
+    }
+    if (isDisjoint(row.predicate)) {
+      // cax-dw: a surviving type whose ⊑-closure meets a surviving
+      // disjointWith partner equal to the conclusion's object.
+      for (const c of typesOf.get(row.subject) || []) {
+        for (const d of [c, ...ancestorsOf(c)]) {
+          if (disjointOf.get(d)?.has(row.object)) return true;
+        }
+      }
+      return false;
+    }
+    // An entailed predicate no rule family here owns: nothing can re-check
+    // it, so it is never removed on a stale citation alone.
+    return true;
+  };
+}
+
 /**
- * A scoped retraction slice: JTMS-style dependency-directed removal, for
- * scm-sco ONLY. Retracting `subject ⊑ object` removes the fact, then cascades
- * to any purely-entailed scm-sco fact whose persisted justification cites a
- * removed id — but each candidate is VERIFIED (re-derivable over the
- * surviving subClassOf edge set, not just "cited a removed id") before it is
+ * A scoped retraction slice: JTMS-style dependency-directed removal.
+ * Retracting `subject ⊑ object` removes the fact, then cascades to any
+ * purely-entailed fact — across all five rules' conclusions — whose persisted
+ * justification cites a removed id. Each candidate is VERIFIED (re-derivable
+ * from the surviving facts, not just "cited a removed id") before it is
  * actually removed, since a fact can have a second, independent derivation
  * path (a⊑b⊑d AND a⊑c⊑d both license a⊑d) that a bare delete-by-justification
  * walk would wrongly discard. Repeats in rounds — a removed mid-chain link
  * can ripple — bounded by `budget` (max facts examined+removed) and `depth`
  * (max cascade rounds).
  *
- * Scope limit: only scm-sco persists a justification today, so a
- * type/disjointWith/someValuesFrom conclusion that also went stale is not
- * cascaded here (mechanical to extend, not attempted in this slice).
+ * The entry point stays subClassOf-rooted because chat's recognized
+ * retraction phrasings ("X is not a Y", "forget that X is a kind of Y",
+ * chat.mjs's teach lane) retract subClassOf facts; the cascade itself follows
+ * justifications into every rule's conclusions (transitive ⊑, propagated
+ * types, disjointness violations, restriction membership and subsumption).
+ *
+ * A survivor keeps its stale, still-single justification as-is; a later
+ * retraction of its OTHER supporting path therefore won't re-examine it.
+ * Re-grounding survivors — or tracking every alternate justification set —
+ * is the ATMS horizon (PLAN_SYLLOGIST.md §3), not this bounded slice.
  *
  * Returns { retracted, count, budget, depth, truncated, found } — `found` is
  * false when `subject ⊑ object` was never a stored fact.
@@ -866,43 +987,38 @@ export async function retractSubClassOf(repoDir, subject, object, { budget = 50,
   const byId = new Map(rows.map((r) => [r.id, r]));
   if (!byId.has(targetId)) return { retracted: [], count: 0, budget, depth, truncated: false, found: false };
 
-  // The FULL current subClassOf edge set (stated + every prior entailment) —
-  // the working graph this function's VERIFY step walks each round; a
-  // removed id's own edge is excluded from that round's walk onward.
-  const scRows = rows.filter((r) => isSubClassOf(r.predicate));
-  const edgeOf = new Map(scRows.map((r) => [r.id, [r.subject, r.object]]));
-  // Only a purely-entailed scm-sco fact ever carries a walkable justification.
-  const entailedScRows = scRows.filter((r) => r.justification.length && isPurelyEntailed(r.provenance));
+  // Only a purely-entailed fact ever carries a walkable justification —
+  // a fact later independently taught is never a cascade candidate at all.
+  const entailedRows = rows.filter((r) => r.justification.length && isPurelyEntailed(r.provenance));
 
   const removed = new Set([targetId]);
   const order = [targetId]; // deterministic report order: target first, then removal order
   let truncated = false;
   let round = 0;
   for (; round < depth; round += 1) {
-    const candidates = entailedScRows
+    const candidates = entailedRows
       .filter((r) => !removed.has(r.id) && r.justification.some((j) => removed.has(j)))
-      .sort((a, b) => a.subject.localeCompare(b.subject) || a.object.localeCompare(b.object));
+      .sort((a, b) => a.subject.localeCompare(b.subject) || a.predicate.localeCompare(b.predicate) || a.object.localeCompare(b.object));
     if (!candidates.length) break; // fixpoint — nothing left to (re-)check
 
-    // The surviving edge set for THIS round's verify walk excludes every
-    // candidate's own edge too, not just `removed` — otherwise a candidate
+    // The surviving fact set for THIS round's verify walk excludes every
+    // candidate's own row too, not just `removed` — otherwise a candidate
     // could trivially "reach itself" through its own not-yet-deleted edge, or
     // lean on a sibling candidate standing on the same broken premise.
     const candidateIds = new Set(candidates.map((c) => c.id));
-    const survivingEdges = [...edgeOf.entries()]
-      .filter(([id]) => !removed.has(id) && !candidateIds.has(id))
-      .map(([, e]) => e);
-    const ancestorsOf = buildAncestorCloser(survivingEdges);
+    const stillDerivable = buildSurvivorDerivabilityCheck(
+      rows.filter((r) => !removed.has(r.id) && !candidateIds.has(r.id)),
+    );
 
     let progressed = false;
     let hitBudget = false;
     for (const c of candidates) {
       if (removed.size >= budget) { hitBudget = true; break; }
-      // does subject⊑object still hold WITHOUT the retracted premise, via ANY
-      // surviving path (not just the one this fact was originally derived
-      // through)? A survivor keeps its (now possibly re-groundable, still
-      // TRUE) fact and is never re-examined again this call.
-      if (ancestorsOf(c.subject).has(c.object)) continue; // a second, independent path still supports it — keep
+      // does the conclusion still hold WITHOUT the retracted premise, via ANY
+      // surviving derivation (not just the one this fact was originally
+      // derived through)? A survivor keeps its (now possibly re-groundable,
+      // still TRUE) fact and is never re-examined again this call.
+      if (stillDerivable(c)) continue; // a second, independent derivation still supports it — keep
       removed.add(c.id);
       order.push(c.id);
       progressed = true;
@@ -913,7 +1029,7 @@ export async function retractSubClassOf(repoDir, subject, object, { budget = 50,
   if (!truncated && round >= depth) {
     // depth exhausted, not a natural fixpoint — honestly flag it if a
     // pending candidate would still have been checked next round.
-    truncated = entailedScRows.some((r) => !removed.has(r.id) && r.justification.some((j) => removed.has(j)));
+    truncated = entailedRows.some((r) => !removed.has(r.id) && r.justification.some((j) => removed.has(j)));
   }
 
   const { removed: actuallyRemoved } = await removeFacts(repoDir, order);

package/src/viz-theme.mjs

@@ -0,0 +1,66 @@
+// viz-theme.mjs — the shared assets for tmct's generated HTML pages
+// (the ledger explorer and the plan player): the visual token table
+// (PLAN_VIZ_LEDGER.md's reference values) plus the escaping helpers every
+// page builder needs.
+//
+// Trust tiers are precomputed rgba() values per provenance color so pages
+// render identically on browsers without color-mix() support.
+
+export const SERIF_STACK = `"Charter", "Bitstream Charter", Georgia, "Times New Roman", serif`;
+export const MONO_STACK = `ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`;
+
+/** Escape untrusted text for safe placement inside HTML content/attributes. */
+export function escapeHtml(s) {
+  return String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+
+/** JSON-embed page data into a `<script>` tag safely — escape `</` so a
+ *  label/id containing "</script>" can't break out of the tag, and escape
+ *  U+2028/U+2029 (valid in JSON strings, invalid unescaped in JS source). */
+export function embedJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/** hex "#RRGGBB" -> "rgba(r, g, b, a)" */
+function rgba(hex, alpha) {
+  const n = parseInt(hex.slice(1), 16);
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
+}
+
+export const TOKENS = Object.freeze({
+  light: Object.freeze({
+    bg: "#F7F6F2", ink: "#23272B", muted: "#6E7168", line: "#DDD9D0", card: "#FFFFFF",
+    taught: "#2E7D4F", corpus: "#5A80AC", entail: "#B07C2E", alert: "#B0503F",
+  }),
+  dark: Object.freeze({
+    bg: "#15181C", ink: "#E7E5DF", muted: "#9A9E95", line: "#2B3036", card: "#1C2126",
+    taught: "#5FBE8B", corpus: "#6C93BF", entail: "#D9A554", alert: "#D08070",
+  }),
+});
+
+const TIER_ALPHA = [0.35, 0.65, 1.0]; // trust tiers 1..3
+
+function tokenBlock(t) {
+  const tiers = (name) =>
+    TIER_ALPHA.map((a, i) => `--${name}-t${i + 1}: ${rgba(t[name], a)};`).join(" ");
+  return [
+    `--bg: ${t.bg}; --ink: ${t.ink}; --muted: ${t.muted}; --line: ${t.line}; --card: ${t.card};`,
+    `--taught: ${t.taught}; --corpus: ${t.corpus}; --entail: ${t.entail}; --alert: ${t.alert};`,
+    tiers("taught"), tiers("corpus"), tiers("entail"),
+    `--taught-soft: ${rgba(t.taught, 0.12)}; --corpus-soft: ${rgba(t.corpus, 0.12)};`,
+    `--entail-soft: ${rgba(t.entail, 0.14)}; --alert-soft: ${rgba(t.alert, 0.12)};`,
+  ].join(" ");
+}
+
+/** The token table as CSS custom properties: light by default, dark via the
+ *  OS preference, and explicit data-theme overrides winning in both
+ *  directions (the viewer's toggle stamps data-theme on the root). */
+export const THEME_TOKENS_CSS = `
+  :root { color-scheme: light dark; ${tokenBlock(TOKENS.light)} }
+  @media (prefers-color-scheme: dark) { :root { ${tokenBlock(TOKENS.dark)} } }
+  :root[data-theme="dark"] { ${tokenBlock(TOKENS.dark)} }
+  :root[data-theme="light"] { ${tokenBlock(TOKENS.light)} }
+`;

package/src/wink-model.mjs

@@ -21,6 +21,7 @@ let cached; // undefined = not tried yet; null = unavailable (tried once, honest
 export function registerWinkModel(factory) {
   injected = factory;
   cached = undefined;
+  instance = undefined;
 }
 
 /** Load `{ winkNLP, model }` once, or null when wink isn't available. Prefers a
@@ -46,15 +47,20 @@ function nodeRequireWink() {
   };
 }
 
-/** Convenience: the constructed `nlp` instance (`winkNLP(model)`) or null. Both
- *  adapters want exactly this. Not cached here — the adapters cache their own
- *  higher-level object; constructing `nlp` is cheap next to loading the model. */
+let instance; // undefined = not built yet; null = construction failed once
+
+/** Convenience: the constructed `nlp` instance (`winkNLP(model)`) or null.
+ *  Cached: repeated `winkNLP(model)` construction accumulates module-level
+ *  state inside the model package until V8 throws "Invalid string length",
+ *  after which every later construction fails for the life of the process. */
 export function winkInstance() {
+  if (instance !== undefined) return instance;
   const loaded = loadWinkModel();
-  if (!loaded) return null;
+  if (!loaded) { instance = null; return null; }
   try {
-    return loaded.winkNLP(loaded.model);
+    instance = loaded.winkNLP(loaded.model);
   } catch {
-    return null;
+    instance = null;
   }
+  return instance;
 }

package/src/ask-browser-entry.mjs

@@ -1,19 +0,0 @@
-// ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded "Ask the
-// graph" chat panel: a real NL chat running client-side against the embedded
-// graph, via tmct's own JS engine (esbuild + a Node-builtin stub plugin
-// bundles tmct's real ask() into a single browser IIFE).
-//
-import { ask, parseQuery } from "./ask.mjs";
-import {
-  parseEntities, spiralExpand, mostRecentIndividual, derivedUpdatedAt, MEMORY_SPIRAL_EXPAND_KINDS,
-  MEMORY_FACT_LINK_KINDS, buildVizNodesAndEdges, deriveFactTermGraph, pickLegendDimension, legendValueFor,
-  edgeKindsFor, collapseToTopN,
-} from "./codegraph.mjs";
-
-// Exported so the viewer page's client-side recentre/edge-kind-toggle/
-// dimension-switcher reuses the same computation as the CLI, not a second copy.
-globalThis.tmctViz = {
-  ask, parseQuery, parseEntities, spiralExpand, mostRecentIndividual, derivedUpdatedAt,
-  MEMORY_SPIRAL_EXPAND_KINDS, MEMORY_FACT_LINK_KINDS, buildVizNodesAndEdges,
-  deriveFactTermGraph, pickLegendDimension, legendValueFor, edgeKindsFor, collapseToTopN,
-};