@polycode-projects/the-mechanical-code-talker 2.8.1 → 2.8.4

package/src/services/ledger-viz.mjs

@@ -170,6 +170,11 @@ export function computeLedgerDataFromPayload(payload, { focus, term, rowLimit =
     contradictions: { count: contradictions.length, firstFocusTerm: firstContra ? firstContra.s : null },
     biggestHub: terms.length ? { term: terms[0].term, degree: terms[0].degree } : null,
   };
+  // Dashboard-strip stats: always over the FULL rows/terms/contradictions —
+  // computed here, before the row-cap section below, so a huge graph's
+  // tile numbers stay the whole-graph truth even when the ledger view itself
+  // degrades to "recent + local".
+  const stats = computeLedgerStats(rows, terms, contradictions);
 
   // Row cap: the focus 2-hop neighborhood survives first (the minimap's own
   // radius, so facet counts and the map stay mutually correct), the rest by
@@ -190,7 +195,7 @@ export function computeLedgerDataFromPayload(payload, { focus, term, rowLimit =
   }
   const meta = { shown: shownRows.length, total, truncated: shownRows.length < total };
 
-  return { rows: shownRows, terms, edges, focus: focusTerm, contradictions, worthALook, payload, meta };
+  return { rows: shownRows, terms, edges, focus: focusTerm, contradictions, worthALook, payload, meta, stats };
 }
 
 /** Load the memory graph under `repoDir` and derive the ledger data. Never
@@ -261,11 +266,207 @@ export function facetCounts(rows, focus, sel, now) {
   return counts;
 }
 
+// ---- dashboard-strip stats: real counts over the FULL fact-row set --------
+// (never the row-capped view — meta.total's own honesty contract) for the
+// telemetry-style tiles atop the existing 3-column layout.
+
+const BUNDLE_TOP_N = 6;
+const PREDICATE_TOP_N = 6;
+const SPARK_MAX_POINTS = 48;
+
+/** Corpus-bundle grouping key for one fact's `src` string: the first
+ *  pipe-segment, folded to its stable source-family prefix
+ *  ("teach:chat:<session>@<ts>" -> "teach:chat", "corpus:human /r/IsA" ->
+ *  "corpus:human", "import:hanoi-3.txt" stays whole — the filename IS the
+ *  bundle). A closed table with a verbatim fallback, same posture as
+ *  phraseFor: an unrecognized tag still reads as itself. */
+export function bundleKeyFor(src) {
+  const first = String(src || "").split(" | ")[0].trim();
+  if (!first) return "unrecorded";
+  if (first.startsWith("teach:chat")) return "teach:chat";
+  if (first.startsWith("ace:chat")) return "ace:chat";
+  if (first === "operator" || first.startsWith("operator:")) return "operator";
+  if (first.startsWith("entailed")) {
+    const rule = first.slice("entailed".length).replace(/^[:\s]+/, "").split(/[\s:]/)[0];
+    return rule ? `entailed:${rule}` : "entailed";
+  }
+  if (first.startsWith("corpus:")) {
+    const name = first.slice("corpus:".length).split(" ")[0];
+    return name ? `corpus:${name}` : "corpus";
+  }
+  return first; // import:<file>, provider/reference/web sourceTypes, etc — verbatim
+}
+
+/** Human label for a bundleKeyFor() key. */
+export function bundleLabelFor(key) {
+  const k = String(key || "");
+  if (k === "teach:chat") return "taught via chat";
+  if (k === "ace:chat") return "taught (parsed)";
+  if (k === "operator") return "operator-asserted";
+  if (k === "unrecorded") return "unrecorded";
+  if (k.startsWith("corpus:")) return `corpus: ${k.slice(7)}`;
+  if (k.startsWith("import:")) return `imported: ${k.slice(7)}`;
+  if (k.startsWith("entailed:")) return `entailed: ${k.slice(9)}`;
+  if (k === "entailed") return "entailed";
+  return k;
+}
+
+/** Dashboard-strip stats over `rows` (the FULL set — pass it before any
+ *  row-cap slicing) and `terms`/`contradictions` from the same derivation.
+ *  Every number is a straight count or ratio over real rows; nothing here is
+ *  estimated or placeholder. The ingestion sparkline plots cumulative fact
+ *  count in TEACH order (oldest first), not wall-clock time — a store built
+ *  in one script run has timestamps seconds apart, so order carries the
+ *  signal the clock can't. */
+export function computeLedgerStats(rows, terms, contradictions) {
+  const list = rows || [];
+  const byProv = { taught: 0, corpus: 0, entailed: 0 };
+  const byTier = { 1: 0, 2: 0, 3: 0 };
+  const bundleCounts = new Map();
+  const predicateCounts = new Map(); // predicate -> { phrase, count }
+  for (const r of list) {
+    byProv[r.prov] = (byProv[r.prov] || 0) + 1;
+    byTier[r.trustTier] = (byTier[r.trustTier] || 0) + 1;
+    const bk = bundleKeyFor(r.src);
+    bundleCounts.set(bk, (bundleCounts.get(bk) || 0) + 1);
+    const pc = predicateCounts.get(r.p) || { phrase: r.phrase, count: 0 };
+    pc.count += 1;
+    predicateCounts.set(r.p, pc);
+  }
+  const bundles = [...bundleCounts.entries()]
+    .map(([key, count]) => ({ key, label: bundleLabelFor(key), count }))
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+    .slice(0, BUNDLE_TOP_N);
+  const predicates = [...predicateCounts.entries()]
+    .map(([predicate, v]) => ({ predicate, phrase: v.phrase, count: v.count }))
+    .sort((a, b) => b.count - a.count || a.predicate.localeCompare(b.predicate))
+    .slice(0, PREDICATE_TOP_N);
+
+  const totalDegree = (terms || []).reduce((sum, t) => sum + (t.degree || 0), 0);
+  const density = terms && terms.length ? totalDegree / terms.length : 0;
+
+  // Cumulative fact count in teach order, sampled to SPARK_MAX_POINTS for a
+  // large graph — every plotted value is a real cumulative count at a real
+  // index, never interpolated.
+  const ordered = list.filter((r) => r.createdAt).slice().reverse(); // rows sort newest-first
+  const n = ordered.length;
+  const sparkline = [];
+  if (n > 0) {
+    const stride = Math.max(1, Math.ceil(n / SPARK_MAX_POINTS));
+    for (let i = stride - 1; i < n; i += stride) sparkline.push(i + 1);
+    if (sparkline[sparkline.length - 1] !== n) sparkline.push(n);
+  }
+
+  return {
+    totalFacts: list.length,
+    totalTerms: (terms || []).length,
+    byProv, byTier, bundles, predicates, density,
+    contradictionCount: (contradictions || []).length,
+    firstLearned: n ? ordered[0].createdAt : null,
+    lastLearned: n ? ordered[n - 1].createdAt : null,
+    sparkline,
+  };
+}
+
+const pct = (n, total) => (total > 0 ? (n / total) * 100 : 0);
+
+/** The facts.by-tier tile: a proportional bar plus a counts legend, both over
+ *  the SAME three taught/corpus/entailed tokens the rest of the page already
+ *  colors provenance with. Server-rendered once; the tier split doesn't
+ *  change with the interactive segment filters below it. */
+function tierTileHtml(byProv, total) {
+  const segs = [["taught", byProv.taught || 0], ["corpus", byProv.corpus || 0], ["entail", byProv.entailed || 0]];
+  const bar = segs.map(([cls, n]) => `<span class="tseg t-${cls}" style="width:${pct(n, total).toFixed(2)}%"></span>`).join("");
+  const legend = segs.map(([cls, n]) => `<span class="tleg t-${cls}">${n} ${cls === "entail" ? "entailed" : cls}</span>`).join("");
+  return `<div class="tierbar" role="img" aria-label="${segs.map(([c, n]) => `${n} ${c === "entail" ? "entailed" : c}`).join(", ")} of ${total} facts">${bar}</div><div class="tierlegend">${legend}</div>`;
+}
+
+/** A small leaderboard bar list — bundles or predicates, each scaled to the
+ *  list's own max (not the grand total), like a top-N panel on a dashboard. */
+function microbarsHtml(items) {
+  const max = items.reduce((m, it) => Math.max(m, it.count), 0) || 1;
+  return items.map((it) =>
+    `<div class="bbar"><span class="bblabel">${escapeHtml(it.label)}</span><span class="bbtrack"><span class="bbfill" style="width:${pct(it.count, max).toFixed(1)}%"></span></span><span class="bbn">${it.count}</span></div>`,
+  ).join("");
+}
+
+/** The dashboard strip: fact/term totals, the tier bar, graph density, a data-
+ *  quality tile keyed off the SAME contradiction count worthALook surfaces,
+ *  and the corpus-bundle/predicate leaderboards. Every tile reads straight
+ *  off `stats` (computeLedgerStats) — no client-side recomputation. */
+function dashboardHtml(stats) {
+  const s = stats || {};
+  const total = s.totalFacts || 0;
+  if (!total) {
+    return `<section class="dash" aria-label="Ledger metrics"><div class="tile"><span class="tile-label">facts.total</span><span class="tile-value">0</span><span class="tile-sub">nothing taught yet</span></div></section>`;
+  }
+  const terms = s.totalTerms || 0;
+  const qualityCls = s.contradictionCount > 0 ? " tile-alert" : "";
+  const bundlesHtml = s.bundles?.length ? microbarsHtml(s.bundles) : `<span class="tile-sub">no sources recorded</span>`;
+  const predicatesHtml = s.predicates?.length
+    ? microbarsHtml(s.predicates.map((p) => ({ label: p.phrase || p.predicate, count: p.count })))
+    : `<span class="tile-sub">none yet</span>`;
+  return `<section class="dash" aria-label="Ledger metrics">
+    <div class="tile">
+      <span class="tile-label">facts.total</span>
+      <span class="tile-value">${total}</span>
+      <span class="tile-sub">${terms} term${terms === 1 ? "" : "s"} tracked</span>
+    </div>
+    <div class="tile tile-wide">
+      <span class="tile-label">facts.by-tier</span>
+      ${tierTileHtml(s.byProv || {}, total)}
+    </div>
+    <div class="tile">
+      <span class="tile-label">graph.avg-degree</span>
+      <span class="tile-value">${(s.density || 0).toFixed(1)}</span>
+      <span class="tile-sub">facts per term</span>
+    </div>
+    <div class="tile${qualityCls}">
+      <span class="tile-label">data.quality</span>
+      <span class="tile-value">${s.contradictionCount || 0}</span>
+      <span class="tile-sub">term${s.contradictionCount === 1 ? "" : "s"} with more than one answer</span>
+    </div>
+    <div class="tile tile-wide">
+      <span class="tile-label">corpus.bundles</span>
+      <div class="bundlebars">${bundlesHtml}</div>
+    </div>
+    <div class="tile tile-wide">
+      <span class="tile-label">predicate.top</span>
+      <div class="bundlebars">${predicatesHtml}</div>
+    </div>
+  </section>`;
+}
+
+/** The aside's ingestion sparkline: a real cumulative-count polyline over
+ *  `stats.sparkline` (see computeLedgerStats), server-rendered as inline SVG
+ *  so it needs no client JS and repaints for free on a theme switch via the
+ *  CSS custom properties its classes resolve against. */
+function sparklineSvg(stats) {
+  const pts = stats?.sparkline || [];
+  const W = 200, H = 44, PAD = 3;
+  if (!pts.length) return `<p class="mapnote">not enough dated facts yet</p>`;
+  if (pts.length === 1) {
+    return `<svg class="spark" viewBox="0 0 ${W} ${H}" role="img" aria-label="1 fact taught"><circle class="dot" cx="${W / 2}" cy="${H / 2}" r="2.5"></circle></svg>`;
+  }
+  const max = pts[pts.length - 1]; // cumulative and monotonic — last is the max
+  const stepX = (W - PAD * 2) / (pts.length - 1);
+  const y = (v) => H - PAD - (v / max) * (H - PAD * 2);
+  const coords = pts.map((v, i) => [PAD + i * stepX, y(v)]);
+  const line = coords.map(([x, yy], i) => `${i === 0 ? "M" : "L"}${x.toFixed(1)},${yy.toFixed(1)}`).join(" ");
+  const area = `${line} L${coords[coords.length - 1][0].toFixed(1)},${H} L${coords[0][0].toFixed(1)},${H} Z`;
+  const last = coords[coords.length - 1];
+  return `<svg class="spark" viewBox="0 0 ${W} ${H}" role="img" aria-label="${pts.length} sampled points, ${max} facts total">
+    <path class="fill" d="${area}"></path>
+    <path class="line" d="${line}"></path>
+    <circle class="dot" cx="${last[0].toFixed(1)}" cy="${last[1].toFixed(1)}" r="2.5"></circle>
+  </svg>`;
+}
+
 /** One complete, self-contained document: the ledger, segment rail,
  *  worth-a-look panel, breadcrumb/search, two-hop minimap, and (when the
  *  memory-ask bundle is present) the ask-the-graph chat dock, all over the
  *  embedded LEDGER/PAYLOAD data. */
-export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle } = {}) {
+export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, worthALook, payload, meta, memoryAskBundle, stats } = {}) {
   const ledgerJson = embedJson({ rows: rows || [], terms: terms || [], edges: edges || [], focus: focus || null, contradictions: contradictions || [], worthALook: worthALook || null, meta: meta || { shown: 0, total: 0, truncated: false } });
   const payloadJson = embedJson(payload || { individuals: [], objectProperties: [] });
   const shown = meta?.shown ?? (rows || []).length;
@@ -287,6 +488,11 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
         </form>
       </div>`
     : `<div class="chat chat-off"><p class="chatnote">chat unavailable — run <span class="mono">npm run build:ask-bundle</span> to enable the in-page ask engine.</p></div>`;
+  const sparkCaption = stats?.firstLearned && stats?.lastLearned
+    ? (stats.firstLearned.slice(0, 10) === stats.lastLearned.slice(0, 10)
+        ? `learned ${escapeHtml(stats.lastLearned.slice(0, 10))}`
+        : `first ${escapeHtml(stats.firstLearned.slice(0, 10))} &middot; last ${escapeHtml(stats.lastLearned.slice(0, 10))}`)
+    : "cumulative facts, teach order";
 
   return `<!doctype html>
 <html lang="en">
@@ -312,6 +518,30 @@ ${THEME_TOKENS_CSS}
   .search { margin-left: auto; display: flex; align-items: center; gap: .5rem; }
   .search input { font-family: ${MONO_STACK}; font-size: .78rem; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .3rem .6rem; width: 170px; }
   .search .miss { font-size: .72rem; color: var(--alert); font-family: ${MONO_STACK}; }
+  .dash { display: grid; grid-template-columns: repeat(auto-fill, minmax(148px, 1fr)); gap: .6rem; margin: 0 0 1.1rem; }
+  .tile { background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: .55rem .7rem .6rem; display: flex; flex-direction: column; gap: .15rem; min-width: 0; }
+  .tile-wide { grid-column: span 2; }
+  .tile-alert { border-color: var(--alert); }
+  .tile-label { font-family: ${MONO_STACK}; font-size: .62rem; letter-spacing: .07em; text-transform: uppercase; color: var(--muted); }
+  .tile-value { font-family: ${MONO_STACK}; font-size: 1.5rem; font-weight: 600; font-variant-numeric: tabular-nums; line-height: 1.15; }
+  .tile-alert .tile-value { color: var(--alert); }
+  .tile-sub { font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
+  .tierbar { display: flex; height: 8px; border-radius: 99px; overflow: hidden; background: var(--line); margin-top: .3rem; }
+  .tseg { height: 100%; }
+  .tseg.t-taught { background: var(--taught); } .tseg.t-corpus { background: var(--corpus); } .tseg.t-entail { background: var(--entail); }
+  .tierlegend { display: flex; flex-wrap: wrap; gap: .15rem .7rem; margin-top: .35rem; font-family: ${MONO_STACK}; font-size: .65rem; }
+  .tleg.t-taught { color: var(--taught); } .tleg.t-corpus { color: var(--corpus); } .tleg.t-entail { color: var(--entail); }
+  .bundlebars { display: flex; flex-direction: column; gap: .22rem; margin-top: .35rem; }
+  .bbar { display: grid; grid-template-columns: minmax(0,1fr) 3.4rem 1.6rem; align-items: center; gap: .4rem; font-family: ${MONO_STACK}; font-size: .68rem; }
+  .bblabel { color: var(--ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .bbtrack { background: var(--line); border-radius: 99px; height: 5px; overflow: hidden; }
+  .bbfill { display: block; height: 100%; background: var(--ink); opacity: .55; border-radius: 99px; }
+  .bbn { color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
+  .sparkwrap { margin-top: .5rem; }
+  .spark { display: block; width: 100%; height: 44px; }
+  .spark .fill { fill: var(--muted); opacity: .18; stroke: none; }
+  .spark .line { fill: none; stroke: var(--ink); stroke-width: 1.4; }
+  .spark .dot { fill: var(--ink); }
   .app { display: grid; grid-template-columns: 190px minmax(0,1fr) 230px; gap: 1.3rem; grid-template-areas: "rail ledger aside"; }
   .rail { grid-area: rail; } .ledger { grid-area: ledger; } .aside { grid-area: aside; }
   @media (max-width: 880px) { .app { grid-template-columns: 1fr; grid-template-areas: "ledger" "aside" "rail"; } .search { margin-left: 0; } }
@@ -341,7 +571,7 @@ ${THEME_TOKENS_CSS}
   .chip { font-family: ${MONO_STACK}; font-size: .76rem; padding: .05rem .45rem; border: 1px solid var(--line); border-radius: 99px; background: var(--bg); }
   button.chip:hover { border-color: var(--ink); }
   .chip.here { background: var(--ink); color: var(--bg); border-color: var(--ink); }
-  .prov { margin-left: auto; font-family: ${MONO_STACK}; font-size: .64rem; padding: .08rem .5rem; border-radius: 99px; white-space: nowrap; }
+  .prov { margin-left: auto; font-family: ${MONO_STACK}; font-size: .64rem; padding: .08rem .5rem; border-radius: 99px; max-width: 100%; overflow-wrap: anywhere; }
   .prov.p-taught { color: var(--taught); background: var(--taught-soft); }
   .prov.p-corpus { color: var(--corpus); background: var(--corpus-soft); }
   .prov.p-entail { color: var(--entail); background: var(--entail-soft); }
@@ -376,6 +606,7 @@ ${THEME_TOKENS_CSS}
 <main>
   <div class="eyebrow"><span>tmct &middot; memory ledger</span><span id="counts"></span></div>
   <h1>A graph you can read</h1>
+  ${dashboardHtml(stats)}
   <div class="topbar">
     <nav class="crumbs" id="crumbs" aria-label="Focus trail"></nav>
     <div class="search">
@@ -400,6 +631,11 @@ ${THEME_TOKENS_CSS}
         <canvas id="map" width="230" height="160" aria-label="Two-hop neighborhood minimap"></canvas>
         <p class="mapnote">dots = terms &middot; click to refocus &middot; dim = filtered out</p>
       </div>
+      <h2>ingestion</h2>
+      <div class="mapwrap sparkwrap">
+        ${sparklineSvg(stats)}
+        <p class="mapnote">${sparkCaption}</p>
+      </div>
     </aside>
   </div>
 </main>

package/src/services/plan-pddl.mjs

@@ -0,0 +1,245 @@
+// plan-pddl.mjs — a PDDL-style + OWL/RDF text rendering of a solved plan
+// (the plan-lane contract chat.mjs's planLaneAnswer returns, PLAN_GAMES_
+// UPLIFT_V3.md Part C.4 item 3): tmct's own richest textual account of what
+// findActionPath actually consulted, for the "it plans, and shows the work"
+// page's new text panel.
+//
+// Pure formatting over already-structured data (plan.actions/.states/.goal/
+// .domain) — no I/O, no new tracking. Every fact line keeps its REAL
+// predicate tag verbatim (mgx:rest-on, rdf:type, rdfs:subClassOf —
+// plan-viz.mjs's own displayPredicate strips the "mgx:" prefix for the
+// visual board; this renderer never does, on purpose: the point is showing
+// the actual reasoning surface, not decorative syntax), and every
+// :precondition/:effect block is a mechanical diff between two consecutive
+// plan.states snapshots — nothing here infers a taught rule's own guard
+// conditions that never surface as a fact-row change (e.g. "nothing may
+// rest on the target" never toggles a row when it already holds, so it
+// leaves no diff to show).
+//
+// The `rdf:type`/`rdfs:subClassOf` split for the :ontology block is read
+// straight off domain.classMembers' own one-hop shape (compileDomain, see
+// domain.mjs): a class-membership edge lands under `classMembers[object] =
+// [...subjects]` for BOTH "X is a Y" (rdf:type) and "X is a kind of Y"
+// (rdfs:subClassOf) teach frames alike, with no record of which frame taught
+// it — so the split here is a real, testable structural fact (a member that
+// is itself a declared class name is a class-to-class edge; anything else is
+// an individual-to-class edge), not a guess.
+
+const attachPrefix = (predicate) => {
+  const p = String(predicate ?? "").trim();
+  return p.includes(":") ? p : `mgx:${p}`;
+};
+
+const slug = (s) => String(s ?? "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+const factAtom = (r) => `(${r.predicate} ${r.subject} ${r.object})`;
+const factKeyOf = (r) => `${r.subject} ${r.predicate} ${r.object}`;
+
+/** Every class name domain.classMembers declares — a member that is also a
+ *  key names a class-to-class edge; anything else is a plain individual. */
+function classNamesOf(classMembers) {
+  return new Set(Object.keys(classMembers || {}));
+}
+
+/** {rdf:type, rdfs:subClassOf}-tagged edges, one per (member, class) pair,
+ *  sorted for deterministic output. */
+function ontologyEdges(classMembers) {
+  const classNames = classNamesOf(classMembers);
+  const edges = [];
+  for (const cls of Object.keys(classMembers || {}).sort()) {
+    for (const member of [...(classMembers[cls] || [])].sort()) {
+      edges.push({
+        predicate: classNames.has(member) ? "rdfs:subClassOf" : "rdf:type",
+        subject: member,
+        object: cls,
+      });
+    }
+  }
+  return edges;
+}
+
+/** `member`'s direct class (first match in sorted class-name order), or null
+ *  when `member` is itself a class name (not an individual) or untyped. */
+function directClassOf(classMembers, member) {
+  if (classNamesOf(classMembers).has(member)) return null;
+  for (const cls of Object.keys(classMembers || {}).sort()) {
+    if ((classMembers[cls] || []).includes(member)) return cls;
+  }
+  return null;
+}
+
+/** Every plain individual (a member that is never itself a class name),
+ *  sorted, deduplicated across every class it happens to appear under. */
+function individualsOf(classMembers) {
+  const classNames = classNamesOf(classMembers);
+  const out = new Set();
+  for (const members of Object.values(classMembers || {})) {
+    for (const m of members || []) if (!classNames.has(m)) out.add(m);
+  }
+  return [...out].sort();
+}
+
+/** The :objects block's lines — individuals grouped by their direct class,
+ *  PDDL's own `a b c - type` typed-list shorthand. Untyped individuals (no
+ *  direct class found) list on their own trailing line rather than being
+ *  silently dropped. */
+function objectsLines(classMembers) {
+  const byClass = new Map();
+  const untyped = [];
+  for (const member of individualsOf(classMembers)) {
+    const cls = directClassOf(classMembers, member);
+    if (!cls) { untyped.push(member); continue; }
+    if (!byClass.has(cls)) byClass.set(cls, []);
+    byClass.get(cls).push(member);
+  }
+  const lines = [...byClass.keys()].sort().map((cls) => `    ${byClass.get(cls).join(" ")} - ${cls}`);
+  if (untyped.length) lines.push(`    ${untyped.join(" ")}`);
+  return lines;
+}
+
+/** A goal spec ({universal, term, predicate, object}) expanded into concrete
+ *  ground atoms — a universal spec over every member domain.classMembers
+ *  names for `term` (compileGoal's own expansion, domain.mjs), a non-
+ *  universal spec as the single named atom. A universal term with no known
+ *  members expands to nothing (never a placeholder atom naming an unknown
+ *  member). */
+function goalAtoms(specs, classMembers) {
+  const atoms = [];
+  for (const spec of specs || []) {
+    const predicate = attachPrefix(spec.predicate);
+    const members = spec.universal ? [...(classMembers?.[spec.term] || [])].sort() : [spec.term];
+    for (const member of members) atoms.push({ subject: member, predicate, object: spec.object });
+  }
+  return atoms;
+}
+
+/** One action's :precondition/:effect block as a mechanical diff between the
+ *  before (`before`) and after (`after`) state snapshots — every fact row
+ *  present before and absent after is a precondition that stopped holding
+ *  (rendered as `(not …)` in the effect); every row absent before and
+ *  present after is newly asserted. No inference beyond the two snapshots
+ *  themselves — a rule's own guard conditions that never toggle a row (e.g.
+ *  "nothing may rest on the target") leave no diff and so render nothing
+ *  here; the taught rule's `becauseText` names them in prose instead. */
+function diffAction(before, after) {
+  const beforeByKey = new Map((before || []).map((r) => [factKeyOf(r), r]));
+  const afterByKey = new Map((after || []).map((r) => [factKeyOf(r), r]));
+  const removed = [...beforeByKey.entries()].filter(([k]) => !afterByKey.has(k)).map(([, r]) => r);
+  const added = [...afterByKey.entries()].filter(([k]) => !beforeByKey.has(k)).map(([, r]) => r);
+  const bySubjObj = (a, b) => (a.subject === b.subject ? (a.object < b.object ? -1 : 1) : a.subject < b.subject ? -1 : 1);
+  return { removed: removed.sort(bySubjObj), added: added.sort(bySubjObj) };
+}
+
+/**
+ * A PDDL-style `(define (problem …) …)` block plus one `(:action …)` per
+ * plan step, each carrying tmct's own real ontology tags — the richest
+ * textual form of a solved plan the engine can express, for a visitor to
+ * read alongside the visual block/circle render, not instead of it.
+ *
+ * `plan`: the plan-lane contract ({ actions, states, stepGoals, goal,
+ * domain: { classMembers, ordering } }) — see chat.mjs's planLaneAnswer.
+ * Returns a string; `""` for a plan with no actions and no init facts (an
+ * already-satisfied goal has nothing to narrate).
+ */
+export function planToPddl(plan, { problemName = "tmct-plan", domainName = "tmct-taught-domain" } = {}) {
+  const actions = plan?.actions || [];
+  const states = plan?.states || [];
+  const classMembers = plan?.domain?.classMembers || {};
+  const ordering = plan?.domain?.ordering || [];
+  const goalText = plan?.goal?.text || "";
+  const goal = goalAtoms(plan?.goal?.specs, classMembers);
+  const init = (states[0] || []);
+
+  const lines = [];
+  lines.push(`;; tmct plan artifact — PDDL-style action sequence + OWL/RDF ontology tags`);
+  lines.push(`;; goal: ${goalText || "(none stated)"}`);
+  if (plan?.becauseText) lines.push(`;; because: ${plan.becauseText}`);
+  lines.push("");
+  lines.push(`(define (problem ${slug(problemName) || "tmct-plan"})`);
+  lines.push(`  (:domain ${slug(domainName) || "tmct-taught-domain"})`);
+  lines.push("");
+
+  const objLines = objectsLines(classMembers);
+  if (objLines.length) {
+    lines.push("  ;; :objects — individuals grounded through the taught class hierarchy");
+    lines.push("  (:objects");
+    lines.push(...objLines);
+    lines.push("  )");
+    lines.push("");
+  }
+
+  const edges = ontologyEdges(classMembers);
+  if (edges.length) {
+    lines.push("  ;; :ontology — the real rdf:type/rdfs:subClassOf rows compileDomain folded");
+    lines.push("  ;; into domain.classMembers (rdf:type = individual->class, rdfs:subClassOf =");
+    lines.push("  ;; class->superclass)");
+    lines.push("  (:ontology");
+    for (const e of edges) lines.push(`    (${e.predicate} ${e.subject} ${e.object})`);
+    lines.push("  )");
+    lines.push("");
+  }
+
+  const orderingRows = [...ordering].sort((a, b) => (a.subject === b.subject ? (a.object < b.object ? -1 : 1) : a.subject < b.subject ? -1 : 1));
+  if (orderingRows.length) {
+    lines.push("  ;; :ordering — the real mgx:*-than facts the taught precondition consulted");
+    lines.push("  (:ordering");
+    for (const r of orderingRows) lines.push(`    ${factAtom(r)}`);
+    lines.push("  )");
+    lines.push("");
+  }
+
+  if (init.length) {
+    lines.push("  ;; :init — state@0, the taught starting board (real mgx:* predicate tags)");
+    lines.push("  (:init");
+    for (const r of [...init].sort((a, b) => (a.subject === b.subject ? (a.object < b.object ? -1 : 1) : a.subject < b.subject ? -1 : 1))) {
+      lines.push(`    ${factAtom(r)}`);
+    }
+    lines.push("  )");
+    lines.push("");
+  }
+
+  if (goal.length) {
+    lines.push("  ;; :goal");
+    lines.push("  (:goal (and");
+    for (const a of goal) lines.push(`    ${factAtom(a)}`);
+    lines.push("  ))");
+  }
+  lines.push(")");
+
+  if (actions.length) {
+    lines.push("");
+    lines.push(`;; action sequence — findActionPath's own shortest path (${actions.length} move${actions.length === 1 ? "" : "s"})`);
+    actions.forEach((action, i) => {
+      const before = states[i] || [];
+      const after = states[i + 1] || [];
+      const { removed, added } = diffAction(before, after);
+      const name = `${slug(action.name) || "move"}-step${i + 1}`;
+      lines.push("");
+      lines.push(`(:action ${name}`);
+      lines.push(`  :label "${action.label || `${action.name} ${action.subject} ${action.target}`}"`);
+      lines.push(`  :subject ${action.subject}`);
+      lines.push(`  :target ${action.target}`);
+      if (removed.length) {
+        lines.push("  :precondition (and");
+        for (const r of removed) lines.push(`    ${factAtom(r)}`);
+        lines.push("  )");
+      } else {
+        lines.push("  :precondition (and)");
+      }
+      const effectLines = [
+        ...removed.map((r) => `    (not ${factAtom(r)})`),
+        ...added.map((r) => `    ${factAtom(r)}`),
+      ];
+      if (effectLines.length) {
+        lines.push("  :effect (and");
+        lines.push(...effectLines);
+        lines.push("  )");
+      } else {
+        lines.push("  :effect (and)");
+      }
+      lines.push(")");
+    });
+  }
+
+  return `${lines.join("\n")}\n`;
+}