@polycode-projects/the-mechanical-code-talker 1.9.2 → 1.10.1

package/src/memory/inspect.mjs

@@ -1,19 +1,7 @@
-// memory/inspect.mjs — seeing into the memory as TEXT (ROADMAP Phase 4,
-// "Memory inspection"). One renderer serves both surfaces — the `/memory` chat
-// command and the `tmct memory` CLI — in a terse (default) and a verbose form:
-//
-//   - the memory graph grouped by OWL superclass (Fact / Utterance / Session,
-//     plus any other class present), counts with BALANCED samples scaled
-//     log-wise to class size (a 10,000-fact class shows ~8 exemplars, a
-//     3-session class shows all 3);
-//   - top facts ranked by PROVENANCE BREADTH (a fact the corpus AND the chat
-//     both asserted outranks a single-writer fact), provenance verbatim;
-//   - recent Q→A utterance pairs (read off the mgx:inReplyTo edges);
-//   - the block-index summary (blocks, indexed tokens, top PageRank blocks).
-//
-// Pure renderers over loaded payloads + one thin I/O wrapper (inspectMemory).
-// Everything degrades honestly: an empty memory renders as the empty story,
-// never an error.
+// memory/inspect.mjs — seeing into the memory as TEXT: one renderer serves
+// both the `/memory` chat command and the `tmct memory` CLI, terse or
+// verbose. Pure renderers + one thin I/O wrapper (inspectMemory); an empty
+// memory renders as the empty story, never an error.
 
 import { loadMemory, UTTERANCE_CLASS, IN_REPLY_TO_PROP, readFactRows, findContradictions } from "./core.mjs";
 import { loadBlockIndex } from "./blocks.mjs";
@@ -67,10 +55,7 @@ export function renderMemory({ memory, blocks }, { verbose = false } = {}) {
       for (const ind of balancedSample(of, k)) lines.push(`  ${truncate(ind.label, textCap)}`);
     }
 
-    // ---- top facts by COMPUTED TRUST (upgraded from raw provenance breadth) ----
-    // Trust folds source-type prior + corroboration + recency, so a corroborated
-    // operator-stated fact outranks a lone web scrape by construction; provenance
-    // rides along (verbatim in verbose) for the audit trail.
+    // ---- top facts by computed trust (source prior + corroboration + recency) ----
     const ranked = readFactRows(memory)
       .filter((r) => r.sourceIds.length || r.provenance)
       .sort((a, b) => b.trust - a.trust
@@ -128,14 +113,11 @@ export function renderMemory({ memory, blocks }, { verbose = false } = {}) {
     lines.push("", "blocks — none folded yet (a session folds when it ends).");
   }
 
-  // ---- explore hooks: real, runnable example queries built from what's actually
-  //      stored, so /memory is a springboard for drilling in, not just a dump ----
+  // ---- explore hooks: runnable example queries built from what's stored ----
   if (individuals.length) {
     const clean = (t) => typeof t === "string" && /^[a-z][a-z0-9]+(?: [a-z0-9]{2,}){0,2}$/.test(t) && t.length <= 22 && !/^\d+$/.test(t);
     const facts = readFactRows(memory);
-    // Rank candidate "what is a X" terms by CATEGORY SIZE (how many facts point at
-    // them) so the hooks land on rich, recognisable categories (function, class, …),
-    // not a lone ConceptNet oddity.
+    // Rank "what is a X" candidates by category size (how many facts point at them).
     const freq = new Map();
     for (const f of facts) if (clean(f.object)) freq.set(f.object, (freq.get(f.object) || 0) + 1);
     const terms = [...freq.entries()]

package/src/memory/shacl.mjs

@@ -1,37 +1,9 @@
-// memory/shacl.mjs — the declarative SHACL-STYLE ingest gate for tmct's own
-// memory graph (PLAN_AGENTS.md §2.1 "Declarative SHACL ingest gate (c)").
-//
-// ontology/memory-shapes.ttl is the canonical, standards-based (SHACL/
-// Turtle) declarative SPEC for these three shapes — written first, kept as
-// the human-readable/auditable contract, modelled on marginalia's own
-// app/ontology/shapes.ttl. This file is a small, HAND-ROLLED validator that
-// implements exactly what that spec describes, in plain JS, against
-// memory/core.mjs's own {id, label, class, attributes} individual shape.
-//
-// Deliberately NOT wired to a real SHACL/RDF-JS engine. `shacl-engine` +
-// `rdf-ext` were tried first (the plan's named tooling, matching
-// marginalia's own choice) and rejected on measurement: shacl-engine
-// transitively pulls in `@comunica/query-sparql-rdfjs-lite` — a full
-// federated SPARQL query engine — across 560+ packages (~7700 added
-// package-lock.json lines), wildly disproportionate to tmct's "pure-JS,
-// minimal-deps" floor (5 runtime deps before this) and to what three closed,
-// bounded shapes actually need. `src/conformance.mjs` already proves this
-// project is comfortable with imperative shape assertions instead of a
-// general engine (a Repository-Interface contract-test suite, not a memory
-// gate — a DIFFERENT thing from this file, see its own header); this module
-// is the same discipline applied to memory-write validation. Keep
-// ontology/memory-shapes.ttl and this file in sync BY HAND when either shape
-// changes — the .ttl is documentation here, not machine-read.
-//
-// Every shape below is PERMISSIVE beyond memory/core.mjs's own existing
-// structural floor (appendFact/appendRule already throw before ever reaching
-// mutateMemory if subject/predicate/object or name/kind/slots are missing —
-// this gate mirrors, not tightens, that floor) and treats every OPTIONAL
-// attribute (provenance chief among them — appendFact's own signature
-// defaults `provenance` to `""`, and real call sites/tests legitimately omit
-// it, e.g. re-writing createdAt without re-asserting provenance) as OPTIONAL
-// here too: a violation only fires on genuine structural malformation, never
-// on a legitimately sparse-but-valid write or upsert of existing data.
+// memory/shacl.mjs — SHACL-style ingest gate for tmct's own memory graph.
+// Hand-rolled validator mirroring ontology/memory-shapes.ttl (kept in sync by
+// hand) against memory/core.mjs's {id, label, class, attributes} shape — not
+// wired to a real SHACL/RDF-JS engine (disproportionate deps for three closed
+// shapes). Permissive beyond core.mjs's own structural floor: a violation
+// only fires on genuine malformation, never a sparse-but-valid write.
 
 const MEMORY_CLASSES = new Set(["Utterance", "Fact", "Session", "Source", "Rule"]);
 const RULE_KINDS = new Set(["compose2", "filter", "recursive"]);
@@ -62,8 +34,8 @@ function checkIndividual(ind, violations) {
 
 /** FactShape (mgx:FactShape): the reified subject/predicate/object, each
  *  present and non-empty; mgx:factProvenance, WHEN PRESENT, must be
- *  non-empty (optional at this gate — see file header on why: appendFact's
- *  own API allows an empty/omitted provenance). */
+ *  non-empty (optional at this gate — appendFact's own API allows an
+ *  empty/omitted provenance). */
 function checkFact(ind, violations) {
   for (const prop of ["rdf:subject", "rdf:predicate", "rdf:object"]) {
     if (!nonEmpty(attrValue(ind, prop))) violations.push(`a Fact needs a non-empty ${prop}`);
@@ -101,9 +73,8 @@ export function validateIndividual(ind) {
 
 /** The ingest gate: throw a clear, aggregated error if `ind` violates the
  *  shape contract, so a malformed Fact/Rule never reaches mutateMemory's
- *  write. Synchronous (no engine/file I/O) — safe to `await` regardless (a
- *  synchronous throw inside an async caller's body still rejects that
- *  caller's promise correctly; a non-throwing sync return awaits to itself). */
+ *  write. Synchronous, but safe to `await` — a sync throw inside an async
+ *  caller still rejects its promise correctly. */
 export function assertIndividualValid(ind) {
   const r = validateIndividual(ind);
   if (!r.ok) {

package/src/memory/trust.mjs

@@ -1,64 +1,15 @@
-// memory/trust.mjs — deterministic, explainable, auditable trust over a Fact's
-// Sources (PLAN_PROVENANCE_TRUST step (c)).
-//
-// Trust is a COMPUTED attribute of a Fact — never hand-set — a pure function of
-// its Source edges, those Sources' types, and its mgx:createdAt. Three inputs
-// combine:
-//   - a Source-TYPE PRIOR (operator > teach > provider > corpus > corpusWeak >
-//     extracted > web > entailed);
-//   - CORROBORATION over the fact's distinct Sources by noisy-OR
-//     (1 − Π(1 − wᵢ), capped at 1) — two independent web sources (0.4) reach
-//     0.64, a lone operator fact is already 1.0;
-//   - a bounded RECENCY nudge in [0.9, 1.0] from createdAt, half-life decayed —
-//     the codegraph "capped nudge" philosophy, so recency breaks ties and
-//     freshens but never flips a source-type ordering by itself.
-//
-// A fourth, per-Source bounded nudge folds into the type-prior term above (not a
-// separate multiplicative stage): each Source may carry mgx:sourceReliability in
-// [0.5, 1.5] (neutral 1.0 when absent, true of every Source until a session's
-// actor-level trust — sessionReliabilityFrom, core.mjs's recomputeSourceReliability —
-// starts writing it), so a session with a track record of corroborated facts
-// nudges its own Source's contribution up, one contradicted repeatedly nudges it
-// down — additive and safe: absent, every existing score is byte-identical.
-//
-// For ENTAILED facts (tier-5): trust = min(premise trusts) × rule-confidence — a
-// conclusion is only as trustworthy as its weakest premise. Premises may be
-// absent for now, so this is a documented HOOK: pass opts.premiseTrusts (and
-// opts.ruleConfidence) and it engages; otherwise an entailed fact scores off its
-// bare 0.3 prior like any other Source.
-//
-// This module is PURE and import-free of core.mjs (no cycle): it reads Source
-// individuals by their attribute props and returns { score, inputs }. core.mjs
-// materialises the score onto the Fact (mgx:trustScore) plus the inputs it was
-// computed from (mgx:trustInputs), so every score is reproducible and auditable.
+// memory/trust.mjs — deterministic, explainable, auditable trust over a
+// Fact's Sources. Trust = f(source-type prior, noisy-OR corroboration,
+// recency decay), nudged by each Source's mgx:sourceReliability (neutral 1.0
+// when absent). Entailed facts: min(premise trusts) × rule-confidence when
+// premises are supplied, else the bare entailed prior. Pure, import-free of
+// core.mjs; core.mjs materialises the result onto the Fact.
 
 export const TRUST_SCORE_PROP = "mgx:trustScore";
 export const TRUST_INPUTS_PROP = "mgx:trustInputs";
 
-/** Source-type priors — the ordering operator > teach > provider-graph >
- *  curated-corpus > weak-corpus > extracted-document > web > unverified-
- *  entailment. `teach` is the chat teach lane's natural-frame writes
- *  ("remember that …", "<Name> owns <X>") — still operator speech, but
- *  through a looser recognizer than the ACE-parsed operator assert, so it
- *  sits just below the operator prior. The entailed value is a FLOOR before
- *  premise adjustment (see the entailed hook below).
- *
- *  `corpusWeak` is for corpus-sourced facts whose underlying relation is real
- *  but low-precision (ConceptNet's /r/RelatedTo — ambiguous, undirected
- *  association, unlike the specific typed relations the plain `corpus` prior
- *  covers) — still a curated, committed dataset (above `web`), just not
- *  asserting the same strength of claim (below `corpus`).
- *
- *  `extracted` is scripts/extract-facts-from-text.mjs's batch reader: it runs
- *  the SAME deterministic teach/assert recognizer as `teach`/`operator`, but
- *  unattended over an arbitrary document nobody in-session vetted sentence by
- *  sentence — the recognizer is exact/closed-set (no guessing), but the
- *  SOURCE DOCUMENT is unreviewed, so it sits just above `web` (also an
- *  unreviewed external source) and below `corpusWeak`/`corpus` (curated,
- *  committed datasets) and `teach` (a human typing into the live chat).
- *
- *  Both are computed from the Source's type exactly like every other tier —
- *  never hand-set on a Fact directly. */
+/** Source-type priors — computed from the Source's type only, never hand-set
+ *  on a Fact directly. */
 export const SOURCE_PRIOR = Object.freeze({
   operator: 1.0,
   teach: 0.95,
@@ -73,14 +24,9 @@ export const SOURCE_PRIOR = Object.freeze({
 export const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 export const RECENCY_FLOOR = 0.9; // recency multiplier stays within [0.9, 1.0]
 
-// Actor-level (session-scoped) trust — a bounded NUDGE on top of a Source's
-// type prior, read off the same already-passed Source individual a fact's
-// corroboration already resolves via sourceTypeOf. `mgx:sourceReliability`
-// lives in [SOURCE_RELIABILITY_MIN, SOURCE_RELIABILITY_MAX], NEUTRAL (1.0,
-// exactly — no rounding drift) when absent, which is true of every Source
-// until core.mjs's recomputeSourceReliability starts writing it. Neutral-when-
-// absent makes this safely additive: every existing score is byte-identical
-// until something actually writes the attribute.
+// Actor-level (session-scoped) trust — a bounded nudge on a Source's type
+// prior. Neutral (1.0) until core.mjs's recomputeSourceReliability writes it,
+// so this stays additive-safe.
 export const SOURCE_RELIABILITY_MIN = 0.5;
 export const SOURCE_RELIABILITY_MAX = 1.5;
 export const SOURCE_RELIABILITY_NEUTRAL = 1.0;
@@ -88,10 +34,8 @@ export const SOURCE_RELIABILITY_NEUTRAL = 1.0;
 const round = (n, p = 6) => Number(n.toFixed(p));
 const sourceTypeOf = (s) => (s?.attributes || []).find((a) => a.prop === "mgx:sourceType")?.value || "";
 
-/** A Source's reliability multiplier: the raw mgx:sourceReliability attribute,
- *  clamped into [SOURCE_RELIABILITY_MIN, SOURCE_RELIABILITY_MAX] (a corrupt or
- *  out-of-range stored value is defended against, never trusted blindly), or
- *  the neutral 1.0 when the attribute is absent/unparseable. */
+/** A Source's reliability multiplier: raw mgx:sourceReliability, clamped to
+ *  [SOURCE_RELIABILITY_MIN, MAX], or neutral 1.0 when absent/unparseable. */
 function sourceReliabilityOf(s) {
   const raw = (s?.attributes || []).find((a) => a.prop === "mgx:sourceReliability")?.value;
   if (raw === undefined) return SOURCE_RELIABILITY_NEUTRAL;
@@ -100,12 +44,8 @@ function sourceReliabilityOf(s) {
   return Math.max(SOURCE_RELIABILITY_MIN, Math.min(SOURCE_RELIABILITY_MAX, n));
 }
 
-/**
- * Bounded recency multiplier in [RECENCY_FLOOR, 1] from an ISO-8601 createdAt.
- * A half-life decay: freshly written ≈ 1.0, ancient → RECENCY_FLOOR. An unknown
- * or unparseable timestamp yields 1.0 (no penalty) — recency only ever nudges
- * down from a full score, it never invents one.
- */
+/** Bounded recency multiplier in [RECENCY_FLOOR, 1], half-life decayed from
+ *  createdAt. An unparseable timestamp yields 1.0 (no penalty). */
 export function recencyNudge(createdAt, now = Date.now(), halfLifeMs = RECENCY_HALF_LIFE_MS) {
   const t = Date.parse(createdAt);
   if (!Number.isFinite(t)) return 1;
@@ -115,31 +55,18 @@ export function recencyNudge(createdAt, now = Date.now(), halfLifeMs = RECENCY_H
 
 /**
  * Pure trust for one Fact. `fact` supplies `{ sourceIds: [...], createdAt }`;
- * the Source individuals are resolved from `sourcesById` (a plain { id: Source }
- * map — exactly what a memory payload's Source individuals key into). Distinct
+ * Source individuals resolve from `sourcesById` ({ id: Source }). Distinct
  * sources are corroborated by noisy-OR over their type priors and nudged by
  * recency. Deterministic given the same inputs and `opts.now`.
  *
- * opts:
- *   - now            (ms) reference time for recency; default Date.now()
- *   - halfLifeMs     recency half-life override
- *   - premiseTrusts  entailed hook: [trusts] of the conclusion's premise Facts
- *   - ruleConfidence entailed hook: the rule's confidence in [0,1] (default 1)
- *
- * Returns { score, inputs } — `inputs` (the source-type multiset, corroboration
- * count, createdAt and the recency multiplier) is stored alongside the score so
- * "why does this rank high?" is answerable from the record.
+ * opts: now, halfLifeMs, premiseTrusts/ruleConfidence (entailed hook).
+ * Returns { score, inputs } — inputs recorded for audit.
  */
 export function computeTrust(fact, sourcesById = {}, opts = {}) {
   const now = typeof opts.now === "number" ? opts.now : Date.now();
   const ids = Array.isArray(fact?.sourceIds) ? fact.sourceIds : [];
 
-  // distinct sources → their type priors, nudged by each Source's own
-  // mgx:sourceReliability (neutral 1.0 when absent — see sourceReliabilityOf).
-  // `types` stays the plain type multiset (the audit-trail shape callers/tests
-  // already read off `inputs.sourceTypes` is unchanged); `priors` is the
-  // per-source EFFECTIVE prior (type prior × reliability, clamped to [0,1])
-  // the noisy-OR below actually corroborates over.
+  // distinct sources -> type priors × mgx:sourceReliability, clamped to [0,1]
   const seen = new Set();
   const types = [];
   const priors = [];
@@ -179,43 +106,15 @@ export function computeTrust(fact, sourcesById = {}, opts = {}) {
   return { score, inputs };
 }
 
-// How many facts a session needs to have amassed before its track record can
-// swing mgx:sourceReliability with full confidence toward an extreme. Without
-// this, a SINGLE data point saturates the score immediately (asserted=1,
-// contradicted=0 → the bare max 1.5) — measured in practice, this broke the
-// standing invariant that a lone, uncontradicted teach-sourced fact must
-// still score below the operator prior (0.95 × 1.5 clamps past 1.0). This
-// pseudo-count keeps a thin track record close to NEUTRAL and only lets a
-// session earn a confident nudge once it has a real history — the classic
-// Bayesian-smoothing shape (Laplace/"add-k" pseudo-count) for small-sample
-// rates.
+// Laplace/"add-k" pseudo-count: without it a single data point would saturate
+// mgx:sourceReliability to the bare max/min immediately.
 export const RELIABILITY_CONFIDENCE_PSEUDOCOUNT = 19;
 
-/**
- * Pure actor-level (session-scoped) reliability from one session's track
- * record: how many facts it asserted vs. how many of those later turned out
- * to be CONTRADICTED (findContradictions, core.mjs). Bounded to
- * [SOURCE_RELIABILITY_MIN, SOURCE_RELIABILITY_MAX] — the same range
- * mgx:sourceReliability lives in (B1 above), so the result of this function is
- * exactly what a caller materialises onto a session's Source individual.
- *
- * Monotonic in the right direction: more uncontradicted assertions → closer to
- * the max (1.5); more contradicted ones → closer to the min (0.5) — but
- * CONFIDENCE-SCALED by sample size, so a session with only one or two
- * assertions stays close to neutral (1.0) either way, and only a real track
- * record (many assertions) earns a confident swing toward an extreme. Zero
- * assertions is exactly neutral (1.0) — no track record, no opinion, matching
- * the neutral default a Source without this attribute at all already gets
- * (sourceReliabilityOf above). The shape:
- *   net        = clamp[-1,1]((asserted − 2×contradicted) / max(1, asserted))
- *   confidence = asserted / (asserted + RELIABILITY_CONFIDENCE_PSEUDOCOUNT)
- *   ratio      = (net × confidence + 1) / 2         → [0, 1], 0.5 at confidence 0
- *   reliability = MIN + (MAX − MIN) × ratio
- * Each contradicted fact costs DOUBLE an asserted fact's worth of `net` (the
- * `2×` term), so a session that is right twice and wrong once nets a positive
- * but reduced score rather than a wash — corroboration should count for less
- * than the reputational cost of a contradiction. Deterministic, no I/O.
- */
+/** Pure actor-level reliability from a session's asserted-vs-contradicted
+ *  track record (findContradictions, core.mjs), confidence-scaled by sample
+ *  size so a thin record stays near neutral (1.0). Bounded to
+ *  [SOURCE_RELIABILITY_MIN, MAX]. A contradicted fact costs double an
+ *  asserted one's weight. */
 export function sessionReliabilityFrom({ factsAsserted = 0, factsContradicted = 0 } = {}) {
   const asserted = Math.max(0, Number(factsAsserted) || 0);
   const contradicted = Math.max(0, Number(factsContradicted) || 0);

package/src/memory-ask-browser-entry.mjs

@@ -1,36 +1,13 @@
 // memory-ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded
-// "Ask the graph" panel's MEMORY-graph engine (PLAN_VIZ_MEMORY.md Bug 1 fix).
+// "Ask the graph" panel's memory-graph engine.
 //
-// Bug 1: the panel bundled ONLY ask.mjs — tmct's code-graph query engine
-// ("which modules import X"), which has no concept of Facts/corpus data at
-// all, so a memory-graph question like "what is a dog" always missed even
-// though the page's own embedded payload had the answer. This is the SECOND,
-// narrow browser entry point src/ask-browser-entry.mjs's own doc comment
-// anticipates: re-exports just `factAnswer` (src/chat.mjs) — tmct's REAL
-// memory-graph answer engine, the same one `npm run chat` uses — plus
-// `createInMemoryStore` (src/memory/core.mjs), which is how the panel hands
-// `factAnswer` the page's already-embedded PAYLOAD with ZERO fs I/O: a
-// Backend-B handle's `loadMemory` branch returns `handle.payload` directly, no
-// bundle-time module shimming needed (see factAnswer's own doc comment,
-// src/chat.mjs, for the full reasoning — a simpler, more robust mechanism than
-// intercepting loadMemory at bundle time, since it reuses machinery the
-// codebase already ships and tests, rather than a new esbuild-only code path
-// that could drift from the real one).
-//
-// `factAnswer` is called with `envelope: null, miss: true` — the exact,
-// already-documented "no envelope available" bootstrap path (chat.mjs's own
-// comments: "the FIRST turn of a graph-less session... leaves `envelope` null
-// for the rest of THIS turn's processing" — a real, tested code path, not a
-// hack) — which arms factAnswer's own bare-question regex fallbacks
-// (BARE_WHATIS_RE and friends) to parse the query directly, with no
-// dependency on the much larger structural-graph parse pipeline
-// (dispatchTool/loadGraph, server.mjs) that pipeline needs a real --repo code
-// index for and this panel has no use for.
+// Re-exports `factAnswer` (src/chat.mjs) and `createInMemoryStore`
+// (src/memory/core.mjs), which lets the panel hand `factAnswer` the page's
+// already-embedded payload with zero fs I/O. Called with `envelope: null,
+// miss: true` to arm factAnswer's bare-question regex fallbacks directly,
+// bypassing the structural-graph parse pipeline this panel has no use for.
 import { factAnswer } from "./chat.mjs";
 import { createInMemoryStore, normFactTerm } from "./memory/core.mjs";
 
-// normFactTerm is re-exported too — viz.mjs's client-side "focus follows the
-// memory-engine's answer" heuristic (guessTermIdFromQuery) needs the SAME
-// term normalization the CLI's own `--term` seed flag and factAnswer's own
-// subject/object matching use, never a second hand-rolled copy.
+// normFactTerm is re-exported too, for viz.mjs's client-side term normalization.
 globalThis.tmctMemoryAsk = { factAnswer, createInMemoryStore, normFactTerm };

package/src/memory-ask-browser.bundle.js

@@ -2630,7 +2630,7 @@ CREATE INDEX IF NOT EXISTS edges_by_prop ON edges(prop);
         //   (neither recognizes the bare "is in" idiom once "else" sits in front of it).
         //   The only rescue was the relaxation cascade's drop-unmatched layer — but that
         //   layer refuses to accept a relaxed reading that still renders an honest EMPTY
-        //   (by design: relaxation must turn a miss into a real answer, never into
+        //   (: relaxation must turn a miss into a real answer, never into
         //   another kind of miss), so a genuinely empty class ("what else is in
         //   Task.complete" — a method, no members) bottomed out at the bare grammar
         //   wall instead of the specific "no contains edges" receipt. Routing this

package/src/paraphrase.mjs

@@ -1,48 +1,23 @@
-// 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.
+// paraphrase.mjs — a surface-realization variant of an isa-family
+// (`rdfs:subClassOf`) teach confirmation, shown alongside the original, never
+// replacing it, and only when verified against tmct's own inference engine
+// (src/syllogise.mjs). Scoped to isa-family facts only — the one predicate
+// family deriveSubClassClosure reasons over.
 //
-// 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.
+// Verification: re-derive the rdfs:subClassOf closure once from the original
+// triple and once from the triple recovered by parsing the paraphrase back —
+// over the same existing taught edges, the two closures must be identical.
+// This catches a generator bug that silently swapped subject/object, since a
+// swap changes the closure's roles as soon as any other edge touches either
+// term.
 
 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.
+// form, since that's the shape most likely to invert subject/object under a
+// naive regex recognizer.
 const articleFor = (word) => (/^[aeiou]/i.test(String(word || "")) ? "an" : "a");
 const SUBCLASS_TEMPLATES = [
   (s, o) => `${s} is a kind of ${o}`,
@@ -51,10 +26,8 @@ const SUBCLASS_TEMPLATES = [
   (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).
+// One regex per template above, in the SAME order (paired by index, not
+// derived from the generator).
 const SUBCLASS_RECOGNIZERS = [
   /^(.+?)\s+is\s+a\s+kind\s+of\s+(.+)$/i,
   /^(.+?)\s+is\s+a\s+type\s+of\s+(.+)$/i,
@@ -92,17 +65,11 @@ export function recoverSubClassTriple(text) {
   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. */
+/** Verify: re-derive the rdfs:subClassOf closure from the original triple and
+ *  from the paraphrase's recovered triple, over the same existing taught
+ *  edges. Returns `{verified, closure}` — `verified` is false if the
+ *  paraphrase doesn't reparse, doesn't match the original (subject, object),
+ *  or derives a different closure. */
 export function verifySubClassParaphrase(subject, object, paraphraseText, existingEdges = []) {
   const origSubj = normFactTerm(subject);
   const origObj = normFactTerm(object);