@polycode-projects/the-mechanical-code-talker 1.8.12 → 1.8.15

package/src/interpret/normalize.mjs

@@ -152,6 +152,50 @@ export function correctMisspellings(text) {
   return String(text || "").replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
 }
 
+/** FILLER_WORDS (ask-vocab.mjs), pre-built into one alternation once at module
+ *  load — same "build the regex from the table once, reuse it" discipline as
+ *  every other closed-vocabulary regex in this file (CONTRACTION_RE,
+ *  MISSPELLING_RE, …), rather than rebuilding it inside stripFillerWords on
+ *  every call. */
+const FILLER_RE = FILLER_WORDS.length
+  ? new RegExp(
+      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b\\s*,?",
+      "gi",
+    )
+  : null;
+
+/** Just the filler/politeness-word strip (ask-vocab.mjs's FILLER_WORDS),
+ *  standalone — the same "one piece of the pipeline, not the whole thing"
+ *  need correctMisspellings above exists for: a caller with its own
+ *  closed anchor regex (chat.mjs's moduleOrientLane matches "^what does …
+ *  do$" itself) wants leading/embedded filler cleared WITHOUT running
+ *  normalizeQuery's other, more invasive rewrites (contraction expansion,
+ *  preamble/subordination/conditional frame rewrites) that can restructure
+ *  the sentence in ways its own shape-matcher never expects — the exact
+ *  risk correctMisspellings' own docblock describes for the same reason.
+ *
+ *  A comma trailing the filler word/phrase itself (across any whitespace,
+ *  e.g. "um, like," or "quickly,") is swallowed WITH it — leading
+ *  conversational filler is routinely comma-spliced onto the real question
+ *  ("so um, like, what does X do exactly?"), and stripping only the word
+ *  leaves the comma stranded as parse-corrupting punctuation debris (a
+ *  leading "," defeats every `^`-anchored template downstream, both parse
+ *  strategies and lane-local regexes alike) — the same species of
+ *  leftover-debris bug the preamble frames elsewhere in this file
+ *  (GREETING_PREAMBLE_RE et al.) already avoid by consuming their own
+ *  delimiter. The trailing `,?` is safe to make unconditional (unlike the
+ *  preamble frames, no delimiter-required gate is needed): it only ever
+ *  fires immediately after a MATCHED filler word, so it can only ever eat a
+ *  comma that was already glued to filler, never a comma separating real
+ *  content ("the modules, and the classes" — that comma sits after the
+ *  content word "modules", not after any filler word). Pure, idempotent;
+ *  unmatched text passes through byte-unchanged. */
+export function stripFillerWords(text) {
+  let q = String(text || "");
+  if (FILLER_RE) q = q.replace(FILLER_RE, " ");
+  return q.replace(/\s+/g, " ").trim();
+}
+
 // ---- closed PREAMBLE frames (0.8.2 feel wave, PLAN_CHAT_FEEL item 2) — the
 // conversational wrapping a developer puts AROUND a real question: a greeting
 // lead-in with a delimiter ("hey there, quick question - …"), a thanks lead-in
@@ -634,13 +678,7 @@ export function normalizeQuery(text) {
   // leaving punctuation/clause debris that poisons the parse.
   q = applySubordinationFrames(q);
   q = applyConditionalFrames(q);
-  if (FILLER_WORDS.length) {
-    const fillerRe = new RegExp(
-      "\\b(" + [...FILLER_WORDS].sort((a, b) => b.length - a.length).map(escapeRegex).join("|") + ")\\b",
-      "gi",
-    );
-    q = q.replace(fillerRe, " ");
-  }
+  q = stripFillerWords(q);
   // emphatic trailing punctuation (item 10): a run of terminal "?" collapses to
   // one — the anchored templates consume exactly one optional trailing "?", so
   // "…walk.mjs??" otherwise leaks a stray "?" into the captured object term (the

package/src/memory/core.mjs

@@ -1162,6 +1162,18 @@ export function normFactTerm(t) {
 // every seeded fact — the golden-equivalence test pins the two paths together.
 const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
 
+/** Content-address a fact's id from its (subject, predicate, object) WITHOUT
+ *  writing it — the SAME normalize+NUL-join+hash contract appendFact/
+ *  appendFacts use internally (factIdFor, above). Exposed so a caller that
+ *  needs to name a premise's or a not-yet-written conclusion's id (e.g.
+ *  syllogise.mjs's justification-tracking retraction machinery, PLAN_SYLLOGIST.md
+ *  §3) can compute it deterministically without an extra read — ids are
+ *  content-addressed, never sequence-assigned, so this is safe to call
+ *  before, instead of, or in place of an actual append. Pure, no I/O. */
+export function factIdForTriple(subject, predicate, object) {
+  return factIdFor(normFactTerm(subject), normText(predicate), normFactTerm(object));
+}
+
 /** Append one grammar-derived OWL triple, RDF-reified: a `Fact` individual
  *  carrying rdf:subject / rdf:predicate / rdf:object (+ provenance). The
  *  Phase-2 ACE parser's write point. Same (s,p,o) → same id → upsert, never a
@@ -1238,6 +1250,14 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
  *  appendFact's own entailed-hook passthrough, batched: syllogise.mjs's
  *  materializing pass is this function's main caller, so this is the write
  *  path a rule's conclusion trust actually rides (recomputeFactTrust, above).
+ *  A fact may also carry `justification` (optional, array of premise fact
+ *  ids — PLAN_SYLLOGIST.md §3's persisted-justification step): stored
+ *  verbatim as `mgx:factJustification` (space-joined; fact ids never contain
+ *  a space), last-write-wins per id (a re-derivation via a DIFFERENT premise
+ *  pair, after the original was retracted and this fact re-earned its place
+ *  some other way, should overwrite the stale justification, not keep it) —
+ *  never written at all for a plain taught/asserted fact (`justification`
+ *  omitted), which stays byte-identical to before this field existed.
  *  Returns { ids, appended, skipped } — ids one per applied fact (in order),
  *  appended = ids.length, skipped = malformed count. */
 export async function appendFacts(dir, facts) {
@@ -1258,6 +1278,7 @@ export async function appendFacts(dir, facts) {
       quantifier: normText(f?.quantifier),
       premiseTrusts: Array.isArray(f?.premiseTrusts) ? f.premiseTrusts : undefined,
       ruleConfidence: typeof f?.ruleConfidence === "number" ? f.ruleConfidence : undefined,
+      justification: Array.isArray(f?.justification) ? f.justification.filter(Boolean) : undefined,
     });
   }
   const ids = [];
@@ -1290,6 +1311,7 @@ export async function appendFacts(dir, facts) {
           ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
           ...(f.tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: f.tokens.join(" ") }] : []),
           ...(qVal ? [{ prop: "mgx:factQuantifier", key: "quantifier", value: qVal }] : []),
+          ...(f.justification && f.justification.length ? [{ prop: "mgx:factJustification", key: "justification", value: f.justification.join(" ") }] : []),
         ],
       };
       // Upsert into BOTH the array (replace-in-place keeps order) and the index.
@@ -1664,6 +1686,7 @@ export function readFactRows(memory) {
     const sourceTypes = sourceIds
       .map((id) => (sourcesById.get(id)?.attributes || []).find((a) => a?.prop === "mgx:sourceType")?.value)
       .filter(Boolean);
+    const justificationRaw = get("justification");
     rows.push({
       id: ind.id,
       subject: get("subject"), predicate: get("predicate"), object: get("object"),
@@ -1671,11 +1694,51 @@ export function readFactRows(memory) {
       quantifier: get("quantifier"), // "" unless a plural class-membership teach set one (Feature A pt.3)
       sourceIds, sourceTypes,
       trust: Number((ind.attributes || []).find((a) => a?.prop === TRUST_SCORE_PROP)?.value) || 0,
+      // [] unless a rule persisted its premise fact ids (PLAN_SYLLOGIST.md §3's
+      // justification-tracking step — scm-sco only, today; see syllogise.mjs).
+      justification: justificationRaw ? justificationRaw.split(" ").filter(Boolean) : [],
     });
   }
   return rows;
 }
 
+/**
+ * Retract Fact individuals by id — a real DELETE, the mechanism `syllogise.mjs`'s
+ * own header comment has always PROMISED ("fully RETRACTABLE by provenance when
+ * the source graph moves") but that, until PLAN_SYLLOGIST.md §3's retraction
+ * build, nothing in this file actually implemented: un-believing something used
+ * to mean re-running the whole batch pass and hoping dedup naturally sorted it
+ * out, with no targeted removal at all. Drops each matching Fact individual and
+ * scrubs any edge group (`statedBy`, etc.) that referenced it as subject OR
+ * object, so no dangling edge survives the delete — then recounts classes once.
+ * A Source left with zero remaining statedBy edges is NOT itself deleted (an
+ * orphaned Source individual is harmless — it materialises nothing and costs
+ * nothing to leave — so this stays a pure, minimal retraction, not a GC pass).
+ * Ids that don't resolve to a live Fact are silently skipped (an idempotent,
+ * honest no-op — never an error: a caller may retry a retraction against a
+ * concurrently-mutated store). Returns { removed } — the ids ACTUALLY deleted,
+ * a possibly-smaller set than the input. */
+export async function removeFacts(dir, ids) {
+  const idSet = new Set((ids || []).filter(Boolean));
+  const removed = [];
+  if (!idSet.size) return { removed };
+  await mutateMemory(dir, (payload) => {
+    payload.individuals = (payload.individuals || []).filter((ind) => {
+      if (ind?.class === FACT_CLASS && idSet.has(ind.id)) { removed.push(ind.id); return false; }
+      return true;
+    });
+    if (!removed.length) return; // honest no-op — nothing matched, no write needed beyond this
+    const removedSet = new Set(removed);
+    for (const group of payload.objectProperties || []) {
+      const before = group.examples || [];
+      group.examples = before.filter((e) => !removedSet.has(e?.subject) && !removedSet.has(e?.object));
+      group.count = group.examples.length;
+    }
+    recountClasses(payload);
+  });
+  return { removed };
+}
+
 /** The trust floor a fact must clear before a differing object counts as a real
  *  contradiction (below it the fact is too weak to contradict anything). */
 export const CONTRADICTION_TRUST_FLOOR = 0.5;

package/src/paraphrase.mjs

@@ -0,0 +1,131 @@
+// paraphrase.mjs — PLAN_BREADTH_FIRST_NLU.md (c) / ROADMAP.md "Ambition":
+// "Paraphrase alongside the original, verified, never instead of it." A
+// surface-realization variant of an isa-family (`rdfs:subClassOf`) teach
+// confirmation, shown NEXT TO the original literal confirmation, never
+// replacing it — and never shown at all unless its accuracy is checked by
+// running tmct's OWN deterministic inference machinery (`src/syllogise.mjs`)
+// against both the original and the paraphrase.
+//
+// Scope, deliberately narrow: isa-family (`rdfs:subClassOf`) facts only — the
+// one predicate family `syllogise.mjs`'s `deriveSubClassClosure` actually
+// reasons over. tmct's other taught predicate families (someValuesFrom,
+// disjointWith, cardinality) have their own entailment rules in syllogise.mjs
+// too, but this pass covers the single most common teach shape ("X is a kind
+// of Y") the plan's own worked example (ROADMAP.md's Ambition section, the
+// `PLAN_BREADTH_FIRST_NLU.md` §8 canonical example) already anchors on;
+// widening to the other predicate families is a natural, separately-scoped
+// follow-on once this shape is proven live.
+//
+// The generator and the recognizer are a MATCHED PAIR by construction — every
+// template `paraphraseSubClass` can produce has a corresponding branch in
+// `recoverSubClassTriple` that parses it back to exactly the same
+// {subject, object} pair. This is a CLOSED set (never open-ended NLP), so
+// recognition is exact, not fuzzy. "Verified" means: re-derive the
+// `rdfs:subClassOf` transitive closure (the real conclusions this fact would
+// license, via `deriveSubClassClosure`) once seeded with the ORIGINAL triple
+// and once seeded with the triple RECOVERED FROM the paraphrase, over the
+// SAME existing taught edges — the two closures must be identical (both
+// derived edge SETS byte-for-byte equal). A generator bug that silently
+// swapped subject/object (a real risk for a passive-voice template) would be
+// caught here even in a graph with no other taught facts at all, because a
+// swapped pair changes the closure's own subject/object roles the moment any
+// OTHER edge touches either term — exactly the "must entail the same
+// conclusions, neither may contradict the other" check the Ambition asks for,
+// not a shallower string-equality stand-in for it.
+
+import { deriveSubClassClosure } from "./syllogise.mjs";
+import { normFactTerm } from "./memory/core.mjs";
+import { fnv1aHex } from "./hash.mjs";
+
+// Every template reads "SUBJECT ⊑ OBJECT" left to right — no passive/reordered
+// form is offered, since a reordered form is exactly the shape most likely to
+// invert subject/object under a naive regex recognizer; keeping the pair's
+// left-to-right order fixed across every template keeps the recognizer trivial
+// AND correct by construction, rather than needing the closure check to catch
+// a bug the generator could have avoided entirely.
+const articleFor = (word) => (/^[aeiou]/i.test(String(word || "")) ? "an" : "a");
+const SUBCLASS_TEMPLATES = [
+  (s, o) => `${s} is a kind of ${o}`,
+  (s, o) => `${s} is a type of ${o}`,
+  (s, o) => `every ${s} is ${articleFor(o)} ${o}`,
+  (s, o) => `${s} counts as ${articleFor(o)} ${o}`,
+];
+
+// One regex per template above, in the SAME order — deliberately paired by
+// index rather than derived/inverted from the generator, so a change to one
+// side can never silently desync from the other without a test catching it
+// (see paraphrase.test.mjs's own round-trip check over every template).
+const SUBCLASS_RECOGNIZERS = [
+  /^(.+?)\s+is\s+a\s+kind\s+of\s+(.+)$/i,
+  /^(.+?)\s+is\s+a\s+type\s+of\s+(.+)$/i,
+  /^every\s+(.+?)\s+is\s+an?\s+(.+)$/i,
+  /^(.+?)\s+counts\s+as\s+an?\s+(.+)$/i,
+];
+
+/** Deterministic template pick — same (subject, object) always picks the same
+ *  template (pinnable in tests), spread across the table by a pure hash, never
+ *  Math.random/Date.now (same discipline as answer-variants.mjs's pickPhrase). */
+function pickTemplateIndex(subject, object) {
+  const h = fnv1aHex(`${subject}\0${object}`);
+  return parseInt(h.slice(0, 8), 16) % SUBCLASS_TEMPLATES.length;
+}
+
+/** Generate a paraphrase of the `rdfs:subClassOf` confirmation "SUBJECT is a
+ *  kind of OBJECT" for the given (already-normalized-or-not) subject/object —
+ *  never null, always one of the closed templates. Rule/template-based only,
+ *  no LLM, matching every other generator in this product. */
+export function paraphraseSubClass(subject, object) {
+  const idx = pickTemplateIndex(subject, object);
+  return SUBCLASS_TEMPLATES[idx](subject, object);
+}
+
+/** Recover {subject, object} from a paraphrase this module itself generated
+ *  (or any text matching one of the closed templates) — null if it matches
+ *  none of them. Never a fuzzy/NLP parse; a plain closed-set regex match, the
+ *  exact inverse of paraphraseSubClass by construction. */
+export function recoverSubClassTriple(text) {
+  const s = String(text || "").trim();
+  for (const re of SUBCLASS_RECOGNIZERS) {
+    const m = s.match(re);
+    if (m) return { subject: m[1].trim(), object: m[2].trim() };
+  }
+  return null;
+}
+
+/** The actual verification step: does re-deriving the rdfs:subClassOf closure
+ *  from the paraphrase's own recovered triple produce the SAME entailed edge
+ *  set as deriving it from the original triple, over the same pre-existing
+ *  taught edges? `existingEdges` is `[[a,b], …]` — the SAME already-normalized
+ *  pair-list shape `deriveSubClassClosure` itself takes (subClassEdges read
+ *  straight off taught Fact rows elsewhere in this codebase). Returns
+ *  `{verified, closure}` — `closure` is the original triple's own derived
+ *  conclusions (handed back so a caller can show/log them), `verified` is
+ *  false when the paraphrase's recovered triple doesn't reparse, doesn't match
+ *  the original's normalized (subject, object), or derives a different
+ *  closure — any one of those means the paraphrase must NOT be shown. */
+export function verifySubClassParaphrase(subject, object, paraphraseText, existingEdges = []) {
+  const origSubj = normFactTerm(subject);
+  const origObj = normFactTerm(object);
+  const recovered = recoverSubClassTriple(paraphraseText);
+  const closureOf = (a, b) => deriveSubClassClosure([...existingEdges, [a, b]]);
+  const keyOf = (edges) => edges.map((e) => `${e.subject}\0${e.object}`).sort().join("|");
+  const closure = closureOf(origSubj, origObj);
+  if (!recovered) return { verified: false, closure };
+  const recSubj = normFactTerm(recovered.subject);
+  const recObj = normFactTerm(recovered.object);
+  if (recSubj !== origSubj || recObj !== origObj) return { verified: false, closure };
+  const paraphraseClosure = closureOf(recSubj, recObj);
+  const verified = keyOf(closure) === keyOf(paraphraseClosure);
+  return { verified, closure };
+}
+
+/** Top-level convenience: generate + verify in one call. Returns the
+ *  paraphrase text ONLY when verified (never an unverified paraphrase);
+ *  `null` otherwise — the caller shows nothing extra rather than something
+ *  unchecked, keeping "verified, never instead of the original" strict even
+ *  on a genuine (unexpected) verification failure. */
+export function paraphraseVerifiedSubClass(subject, object, existingEdges = []) {
+  const text = paraphraseSubClass(subject, object);
+  const { verified } = verifySubClassParaphrase(subject, object, text, existingEdges);
+  return verified ? text : null;
+}

package/src/router/planner.mjs

@@ -25,10 +25,6 @@
 //     chain. Bounded depth + a hard step counter GUARANTEE termination — no
 //     unbounded search can ever wedge the caller (the harness also caps us).
 //
-// THE OPEN-WORLD BOUNDARY, named honestly: novelty the declared methods + operators
-// do not cover (a sub-goal that resolves to nothing, a connective we do not model)
-// is REFUSED/ESCALATED, not guessed. Sound/complete is claimed only INSIDE the
-// declared world.
 
 import { resolveOne, extractEntity } from "./resolver.mjs";
 

package/src/server.mjs

@@ -162,7 +162,14 @@ export const TOOLS = [
   },
 ];
 
-async function loadGraph(config, source) {
+// Exported (was module-private) so chat.mjs's compare lane can load the SAME
+// graph dispatchTool's own tools load — no new loading path, just direct reuse
+// of the existing config -> source.fetchEntities -> parseEntities chain, for
+// the case where runAsk's own `graph` param is null (the common case; it's
+// only preloaded when a caller already has one in hand — see runAsk's own
+// `if (graph && ...)` / dispatchTool("tmct_ask", …) split just above the
+// compare lane's call site for the existing precedent).
+export async function loadGraph(config, source) {
   const payload = await source.fetchEntities(config);
   const graph = parseEntities(payload);
   if (!graph.individuals.length) {

package/src/source-slice.mjs

@@ -54,8 +54,7 @@ export async function readSpanSafe({ readFile, repoRoot, path, start, end, maxLi
   // Normalize repoRoot to absolute here too (defense in depth) — resolve(repoRoot, path)
   // is always absolute, so comparing it against a RELATIVE repoRoot would make this guard
   // reject every read, not just traversal attempts (the actual bug this normalization
-  // fixes; callers should already pass an absolute repoRoot via src/config.mjs, but this
-  // function is the real security boundary and must not depend on that).
+  // fixes; callers should already pass an absolute repoRoot via src/config.mjs.
   const root = resolve(repoRoot);
   const resolved = resolve(root, path);
   if (resolved !== root && !resolved.startsWith(root + sep)) {

package/src/syllogise.mjs

@@ -101,7 +101,7 @@
 //     exist, so a general "no" is provable without needing one
 //     (`proveMaxCardinalityZeroDenial`).
 
-import { loadMemory, appendFacts, readFactRows, normFactTerm } from "./memory/core.mjs";
+import { loadMemory, appendFacts, readFactRows, normFactTerm, factIdForTriple, removeFacts } from "./memory/core.mjs";
 
 /** scm-sco: the subClassOf-transitivity rule, and the provenance tag its
  *  conclusions carry. */
@@ -1035,6 +1035,18 @@ 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,
+      // PLAN_SYLLOGIST.md §3's persisted-justification step, scm-sco only: the
+      // two premise fact ids THIS conclusion actually rode (a⊑b, b⊑c) — ids
+      // are content-addressed (factIdForTriple/memory/core.mjs), so this works
+      // whether the premise is a stated fact or another entailment this SAME
+      // pass just derived a round earlier (its id is predictable before it's
+      // even written). Read back by retractSubClassOf (below) to find every
+      // entailment a retracted premise could have supported, without a
+      // whole-graph re-scan.
+      justification: [
+        factIdForTriple(d.subject, SUBCLASS_PREDICATE, d.via),
+        factIdForTriple(d.via, SUBCLASS_PREDICATE, d.object),
+      ],
     })),
     ...caxDerived.map((d) => ({
       subject: d.subject, predicate: TYPE_PREDICATE, object: d.object,
@@ -1137,6 +1149,153 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
   return { derived: written, count: written.length, budget, depth, truncated: written.length >= budget };
 }
 
+/** True when EVERY provenance tag on a fact's (possibly " | "-joined) union is
+ *  an `entailed:*` tag — i.e. the fact has never been independently stated or
+ *  taught, only ever derived. A fact first entailed, then LATER also directly
+ *  taught (same (s,p,o) → same id → provenance union, appendFact's own upsert
+ *  contract), is NOT purely entailed any more — `retractSubClassOf`'s cascade
+ *  must never delete it just because its now-stale justification broke; the
+ *  taught half is a real, independent reason to keep believing it (the trust-
+ *  tier concern PLAN_SYLLOGIST.md §3 names: "must never touch a higher-trust
+ *  taught-only derivation"). */
+function isPurelyEntailed(provenance) {
+  const tags = String(provenance || "").split(" | ").filter(Boolean);
+  return tags.length > 0 && tags.every((t) => t.startsWith("entailed:"));
+}
+
+/**
+ * PLAN_SYLLOGIST.md §3's first real, scoped retraction slice: JTMS-style
+ * dependency-directed removal, for scm-sco ONLY (subClassOf transitivity —
+ * this file's simplest rule, and §3's own worked example: "a premise later
+ * disappears, what else must be un-believed?"). Deliberately NOT the fuller
+ * ATMS §3 also sketches (tracking every alternate premise-SET per fact, "a
+ * further, NOT-currently-planned step") — this tracks exactly ONE
+ * justification per entailed fact (the premise pair it actually rode, set at
+ * write time — syllogise()'s own toWrite mapping, above): the JTMS-shaped
+ * step §3 names as missing today ("a JTMS-shaped single justification per
+ * fact in spirit, though not yet a persisted, walkable one").
+ *
+ * Retracting `subject ⊑ object` (a STATED or a previously-ENTAILED fact —
+ * either may be retracted) proceeds in bounded rounds:
+ *   1. Remove the named fact.
+ *   2. Scan stored entailed scm-sco facts (purely-entailed ones only —
+ *      `isPurelyEntailed`, above) for any whose persisted justification cites
+ *      an id removed so far — candidates.
+ *   3. VERIFY, never assume: a candidate is removed only if `subject ⊑
+ *      object` is NO LONGER reachable over the SURVIVING subClassOf edge set
+ *      (a full ⊑-ancestor walk, `buildAncestorCloser` — the SAME shared
+ *      machinery `deriveTypePropagation`/`deriveDisjointViolations` already
+ *      reuse, not reimplemented here). A fact with a SECOND, independent
+ *      derivation path survives — a real possibility scm-sco's transitive
+ *      closure allows (a⊑b⊑d AND a⊑c⊑d both license a⊑d) — exactly the
+ *      failure mode a bare "delete anything citing the retracted id" JTMS
+ *      walk gets wrong, and precisely why de Kleer's ATMS exists at all (§3's
+ *      own citation). This VERIFY step is this slice's cheap, bounded answer
+ *      to that known JTMS over-retraction limitation: one local graph walk
+ *      per candidate, never a full alternate-justification enumeration.
+ *   4. Repeat: a fact confirmed-removed this round becomes a new cascade
+ *      source for the next round (removing a mid-chain link can ripple).
+ *
+ * Bounded by `budget` (max facts examined+removed, default 50 — the SAME
+ * default every other rule in this file uses) and `depth` (max cascade
+ * rounds, default 32, mirroring `deriveSubClassClosure`'s own fixpoint cap).
+ * `truncated` flags the cascade may have been cut short before reaching a
+ * fixpoint (candidates still pending when budget/depth ran out) — the SAME
+ * honest-signal discipline `syllogise()`'s own `truncated` flag follows: a
+ * caller must not read a truncated cascade's survivors as "provably still
+ * consistent," only as "not yet shown inconsistent within budget."
+ *
+ * Known, DELIBERATE scope limit (not a bug): this only ever touches scm-sco's
+ * own entailed subClassOf facts. The other four rules (cax-sco/cax-dw/
+ * cls-svf1/scm-svf1) do not yet persist a justification (none call
+ * `factIdForTriple`/write `justification` — only `syllogise()`'s scmDerived
+ * mapping does, above), so a type/disjointWith/someValuesFrom conclusion that
+ * ALSO went stale when this same premise was retracted is not cascaded here.
+ * Extending justification-tracking to the other four rules is mechanical
+ * (each already computes a `via`/`viaX` pivot) but is a separate follow-up,
+ * not attempted in this slice.
+ *
+ * Returns { retracted, count, budget, depth, truncated, found } — `retracted`
+ * is every id actually removed (target first, then cascade order); `found`
+ * is false (nothing else meaningful) when `subject ⊑ object` was never a
+ * stored fact at all — an honest no-op, matching this module's "never guess"
+ * discipline. No I/O beyond the one `removeFacts` call (skipped entirely when
+ * `found` is false).
+ */
+export async function retractSubClassOf(repoDir, subject, object, { budget = 50, depth = 32 } = {}) {
+  const s = normFactTerm(subject);
+  const o = normFactTerm(object);
+  const targetId = factIdForTriple(s, SUBCLASS_PREDICATE, o);
+  const memory = await loadMemory(repoDir);
+  const rows = readFactRows(memory);
+  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
+  // (see syllogise()'s toWrite mapping + isPurelyEntailed, above) — every
+  // other row's justification is [] (or the fact is also independently
+  // taught, so it is EXCLUDED here even if it happens to carry a stale one),
+  // so this candidate pool is naturally, correctly scoped.
+  const entailedScRows = scRows.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
+      .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));
+    if (!candidates.length) break; // fixpoint — nothing left to (re-)check
+
+    // The surviving edge set for THIS round's verify walk — DRed's own
+    // "delete a superset, then selectively rederive" discipline (§3's own
+    // citation, Gupta/Mumick/Subrahmanian 1993): every candidate's OWN edge
+    // is excluded too, alongside every OTHER candidate under suspicion this
+    // SAME round, not just `removed` — otherwise a candidate would trivially
+    // "reach itself" through its own not-yet-deleted edge (or lean on a
+    // sibling candidate that is itself only standing on the same broken
+    // premise), understating what actually still needs re-verifying. A
+    // candidate that reaches its target through some OTHER, untouched edge
+    // (a genuinely independent derivation path this fact's single persisted
+    // justification never recorded) correctly survives.
+    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);
+
+    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
+      removed.add(c.id);
+      order.push(c.id);
+      progressed = true;
+    }
+    if (hitBudget) { truncated = true; break; }
+    if (!progressed) break; // every candidate this round survived verification — fixpoint
+  }
+  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)));
+  }
+
+  const { removed: actuallyRemoved } = await removeFacts(repoDir, order);
+  return { retracted: actuallyRemoved, count: actuallyRemoved.length, budget, depth, truncated, found: true };
+}
+
 /**
  * PROOF SEARCH (not a third rule — a bounded ROOTED chase that composes the
  * two rules above for a single "does `subj` reach one of `targets`?" query,