@polycode-projects/the-mechanical-code-talker 1.5.5 → 1.8.4

package/src/cli-args.mjs

@@ -0,0 +1,164 @@
+// cli-args.mjs — the ONE shared argv/config resolver for bin/tmct.mjs's
+// subcommands. Replaces four independently hand-rolled `configFor` copies
+// (bin/tmct.mjs's cli-mode and serve-mode ones, chat.mjs's own, and the richer
+// 4-tier version inlined in chat.mjs's createSession) with a single, tested
+// precedence chain — built on top of toml-config.mjs's already-tested
+// mergeEffective/normalizeConfig (arg > toml > default), not a rebuild of it.
+//
+// Three tiny flag helpers (pure, no I/O) plus the one async resolver:
+//   strFlag(rest, names, dflt)   → single value, last flag occurrence wins
+//   repeatedFlag(rest, names)    → every value for a repeatable flag (e.g. --graph)
+//   boolFlag(rest, names)        → true if any of `names` appears at all
+//   resolveRuntimeConfig({argv, cwd, env, gitRoot}) → the resolved repo/config
+//
+// Graph-path precedence (documented once, here — every subcommand shares it):
+//   1. --graph <path>   (repeatable; --graph wins outright, even over env)
+//   2. TMCT_GRAPH_FILE  (env)
+//   3. tmct.toml's `graph_file` / `graph_files`
+//   4. <repo>/.tmct/graph.json, where repo is --repo, else git root, else cwd
+//
+// Deliberately does NOT import chat.mjs (that would be circular once chat.mjs
+// itself is rewired to call resolveRuntimeConfig) — the git-root lookup below
+// is a small, self-contained copy of chat.mjs's own gitToplevel().
+
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { loadTomlConfig, normalizeConfig, mergeEffective, CONFIG_FILE } from "./toml-config.mjs";
+import { DEFAULT_GRAPH_REL } from "./config.mjs";
+
+/** The git top-level for `cwd`, or null if not in a repo (or git is
+ *  unavailable). A deliberate re-declaration of chat.mjs's gitToplevel (not an
+ *  import) — see the file docblock for why. */
+function defaultGitRoot(cwd) {
+  try {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+    if (r.status === 0) { const p = String(r.stdout || "").trim(); return p || null; }
+  } catch { /* git missing / not a repo — fall back to cwd */ }
+  return null;
+}
+
+const asList = (names) => (Array.isArray(names) ? names : [names]);
+
+/** Single-value flag, LAST occurrence wins (so `--repo a --repo b` → "b").
+ *  `names` may be a single flag string or an array of aliases. */
+export function strFlag(rest, names, dflt) {
+  const list = asList(names);
+  let val = dflt;
+  for (let i = 0; i < rest.length; i++) {
+    if (list.includes(rest[i]) && rest[i + 1] !== undefined) val = rest[i + 1];
+  }
+  return val;
+}
+
+/** Repeatable flag — every value across every occurrence, in argv order
+ *  (`--graph a --graph b` → `["a","b"]`). Empty array when absent. */
+export function repeatedFlag(rest, names) {
+  const list = asList(names);
+  const out = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (list.includes(rest[i]) && rest[i + 1] !== undefined) out.push(rest[i + 1]);
+  }
+  return out;
+}
+
+/** Presence flag — true if any of `names` appears anywhere in `rest`. */
+export function boolFlag(rest, names) {
+  const list = asList(names);
+  return rest.some((r) => list.includes(r));
+}
+
+/**
+ * Resolve one subcommand invocation's repo root, tmct.toml, and graph
+ * path(s) — the shared precedence chain every subcommand (chat/memory/init/
+ * import/syllogise/serve) now funnels through instead of re-deriving it.
+ *
+ * @param {object} opts
+ * @param {string[]} [opts.argv]   the subcommand's own argv tail (already past
+ *   `tmct <mode>` — the same slice each subcommand hand-parses today).
+ * @param {string}   [opts.cwd]
+ * @param {object}   [opts.env]
+ * @param {(cwd:string)=>string|null} [opts.gitRoot]  injectable for tests,
+ *   mirrors createSession's own `gitRoot` param.
+ * @param {object}   [opts.args]  extra already-parsed args to fold into
+ *   mergeEffective's "arg" tier (e.g. a subcommand's own flags) — optional,
+ *   defaults to {}.
+ * @returns {Promise<{
+ *   repo: string, configPath: string, toml: object,
+ *   config: {graphFile: string, graphFiles: string[]},
+ *   effective: object, sources: object,
+ * }>}
+ */
+export async function resolveRuntimeConfig({
+  argv = [],
+  cwd = process.cwd(),
+  env = process.env,
+  gitRoot = defaultGitRoot,
+  args = {},
+} = {}) {
+  const configFlag = strFlag(argv, ["--config"]);
+  const repoFlag = strFlag(argv, ["--repo"]);
+  const graphFlags = repeatedFlag(argv, ["--graph"]);
+
+  const root = typeof gitRoot === "function" ? gitRoot(cwd) : null;
+  const repo = repoFlag ? resolve(cwd, repoFlag) : (root || cwd);
+
+  // --config <path>: a file OR a directory. A directory means "look for
+  // tmct.toml under here"; a file is the tmct.toml itself, wherever it lives.
+  let configDir = repo;
+  let configFileOverride;
+  if (configFlag) {
+    const abs = resolve(cwd, configFlag);
+    let isDir = false;
+    try { isDir = (await stat(abs)).isDirectory(); } catch { /* missing path — treat as a file target */ }
+    if (isDir) configDir = abs;
+    else { configFileOverride = abs; configDir = dirname(abs); }
+  }
+
+  const raw = await loadTomlConfig(configDir, configFileOverride ? { file: configFileOverride } : {});
+  const toml = await normalizeConfig(raw, { configDir });
+
+  const defaultGraphFile = join(repo, DEFAULT_GRAPH_REL);
+  const envGraph = env && env.TMCT_GRAPH_FILE && String(env.TMCT_GRAPH_FILE).trim();
+
+  let graphFiles;
+  let graphSource; // "arg" | "env" | "tmct.toml" | "default"
+  if (graphFlags.length) {
+    graphFiles = graphFlags.map((g) => resolve(cwd, g));
+    graphSource = "arg";
+  } else if (envGraph) {
+    graphFiles = [resolve(cwd, envGraph)];
+    graphSource = "env";
+  } else if (toml.graphFiles && toml.graphFiles.length) {
+    graphFiles = toml.graphFiles;
+    graphSource = "tmct.toml";
+  } else if (toml.graphFile) {
+    graphFiles = [toml.graphFile];
+    graphSource = "tmct.toml";
+  } else {
+    graphFiles = [defaultGraphFile];
+    graphSource = "default";
+  }
+
+  // mergeEffective wires in toml-config.mjs's already-tested arg>toml>default
+  // precedence for every OTHER knob (index/tune/corpus/…); graphFile's own
+  // precedence is richer (it has an env tier mergeEffective doesn't model), so
+  // it's resolved above and folded back in below rather than re-derived here.
+  const defaults = { graphFile: defaultGraphFile };
+  const { effective, sources } = mergeEffective({ args, toml, defaults });
+  effective.graphFile = graphFiles[0];
+  sources.graphFile = graphSource;
+  if (graphFiles.length > 1) effective.graphFiles = graphFiles;
+
+  const configPath = configFileOverride || join(configDir, CONFIG_FILE);
+
+  return {
+    repo,
+    configPath,
+    toml,
+    config: { graphFile: graphFiles[0], graphFiles },
+    effective,
+    sources,
+  };
+}

package/src/codegraph.mjs

@@ -1,5 +1,9 @@
 import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
+// Single-sourced predicate strings (memory/core.mjs owns these constants) — no
+// circular-import risk: core.mjs imports trust.mjs/shacl.mjs/planning.mjs, never
+// codegraph.mjs, in either direction.
+import { CREATED_AT_PROP, UPDATED_AT_PROP } from "./memory/core.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
 // deterministic indexer writes to <repo>/.tmct/graph.json (shape produced by
@@ -91,6 +95,13 @@ const PROP_KIND = {
   "mg:defines": "defines",
   "mg:tests": "tests",
   "mg:touches": "touches",
+  // memory-graph predicates (src/memory/core.mjs, src/sessions.mjs) — each maps to
+  // itself as its own kind name (no module-rollup abbreviation needed, unlike
+  // imports/calls) so adjacencyForKinds/edgesOfKind can walk the memory graph too.
+  "mgx:saidinsession": "saidInSession",
+  "mgx:inreplyto": "inReplyTo",
+  "mgx:statedby": "statedBy",
+  "mgx:canonicalisedfrom": "canonicalisedFrom",
 };
 
 export function relationKind(group) {
@@ -579,6 +590,12 @@ const SPIRAL_DEPTH_DEFAULT = 3;
 const SPIRAL_NODE_LIMIT_DEFAULT = 12;
 const SPIRAL_Q_DEFAULT = 0.9;                 // mild hub pruning (drop only the densest 10%) — the centre point
 const SPIRAL_EXPAND_KINDS = ["imports", "calls", "callsSymbol", "inherits"]; // cochange dropped
+// The memory graph's real edge-kind inventory (traced via every objectProperties.push/.find
+// site in src/memory/*.mjs and src/sessions.mjs) — the `kinds` a memory-graph spiralExpand call
+// passes so it walks Session/Fact/Source/Utterance individuals rather than code-graph Modules.
+// NOTE: mgx:asksAbout (src/sessions.mjs) is deliberately EXCLUDED — that predicate lives in the
+// CODE graph (Session ↔ code entities a chat turn resolved/answered), not the memory graph.
+export const MEMORY_SPIRAL_EXPAND_KINDS = ["saidInSession", "inReplyTo", "statedBy", "canonicalisedFrom"];
 const SPIRAL_EMIT_FRAC = 0.5;                 // a newly-surfaced node's base score = maxSeed × this …
 const SPIRAL_HOP_DECAY = 0.6;                 //  … decayed by this per hop from the seeds (bounded < maxSeed, so a walked-in node never dominates rank 1)
 const SPIRAL_PROX_FRAC = 0.2;                 // an ALREADY-matched module the spiral re-reaches gets a bounded nudge …
@@ -623,8 +640,13 @@ function identComponents(name) {
 /** For one edge-kind group, the depth-1 successor of `fromId` reachable via any edge in `kinds`,
  *  as a Map<moduleId, neighbourModuleId> adjacency (undirected — a module's neighbours via that
  *  kind, in either edge direction). Endpoints are mapped to their containing module first (call
- *  edges live at function granularity), matching the existing E1a call-adjacency convention. */
-function adjacencyForKinds(graph, kinds) {
+ *  edges live at function granularity), matching the existing E1a call-adjacency convention.
+ *  `idNormalizer` (default null) lets a caller fold edge endpoints some OTHER way — the memory
+ *  graph has no "containing module" concept, so a memory-graph caller passes `(id) => id` to walk
+ *  its raw individual ids unchanged. Defaulting to null (rather than `moduleIdOfId` directly)
+ *  keeps the sole existing caller (`adjacencyForKinds(graph, kinds)` in beamExpand) byte-identical. */
+export function adjacencyForKinds(graph, kinds, idNormalizer = null) {
+  const norm = idNormalizer || ((id) => moduleIdOfId(graph, id));
   const adj = new Map();
   const link = (a, b) => {
     if (!a || !b || a === b) return;
@@ -635,7 +657,7 @@ function adjacencyForKinds(graph, kinds) {
   };
   for (const kind of kinds) {
     for (const e of edgesOfKind(graph, kind)) {
-      link(moduleIdOfId(graph, e.subject), moduleIdOfId(graph, e.object));
+      link(norm(e.subject), norm(e.object));
     }
   }
   return adj;
@@ -707,24 +729,55 @@ function beamExpand(graph, scored, beamWidth) {
 }
 
 /** SPIRAL expansion (opt-in; see the SPIRAL_* constants' comment above for the full design).
- *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`), popped
- *  fewest-arcs-first via a min-heap keyed (hop ASC, in-graph degree ASC, id ASC), with a
- *  degree-quantile hub gate at each expansion step. Emits up to `nodeLimit` newly-reached nodes
- *  in pop order, scoring each seed-relative and bounded so a hub can't dominate rank 1.
+ *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`, or an explicit
+ *  `seeds` override — see below), popped fewest-arcs-first via a min-heap keyed (hop ASC,
+ *  in-graph degree ASC, id ASC), with a degree-quantile hub gate at each expansion step. Emits
+ *  up to `nodeLimit` newly-reached nodes in pop order, scoring each seed-relative and bounded so
+ *  a hub can't dominate rank 1.
  *  CRITICAL vs beamExpand: it deliberately OMITS the `if (!baseScore.has) continue` guard, so it
  *  MAY push modules that had NO lexical match into `scored` — the one path to breaking the lexical
- *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules).
- *  Pure otherwise (no fs/network); deterministic total ordering throughout. */
-function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_Q_DEFAULT, nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT } = {}) {
-  if (!scored.length) return;
+ *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules)
+ *  when the score-nudge machinery is active. Pure otherwise (no fs/network); deterministic total
+ *  ordering throughout.
+ *
+ *  Generalised (2026-07-11) past its original code-graph-only, `scored`-only shape so a pure
+ *  graph-visualisation walk (no lexical match list at all) can reuse the exact same traversal:
+ *   - `scored` is now OPTIONAL (default `[]`) — a bare walk with no ranking machinery.
+ *   - `kinds` (default `SPIRAL_EXPAND_KINDS`) — the edge-kind set to walk; a memory-graph caller
+ *     passes `MEMORY_SPIRAL_EXPAND_KINDS`.
+ *   - `classPredicate` (default `(ind) => (ind.class || "") === "Module"`) — replaces the two
+ *     hardcoded `"Module"` checks below, so a memory-graph caller can pass `() => true` (every
+ *     class walkable) or any other individual filter.
+ *   - `idNormalizer` (default `null`) — threaded straight into the internal `adjacencyForKinds`
+ *     call; a memory-graph caller passes `(id) => id` (no module-folding).
+ *   - `seeds` (default derived from `scored`, as before) — an explicit id iterable, so a caller
+ *     with no `scored` list at all (e.g. `mostRecentIndividual`'s single seed) can still drive
+ *     the walk.
+ *  The score-nudge machinery (mutating `scored`/introducing newly-surfaced individuals into it)
+ *  is gated behind `scored.length > 0 && maxSeed > 0` — the exact condition the original early
+ *  return checked — so an empty `scored` degrades gracefully into a pure walk rather than erroring.
+ *  Returns `[{id, hop}]` for every node the walk actually pops (seeds included, at hop 0) — this
+ *  used to return `undefined`; safe, since the sole caller (`scoreModules`) already discards the
+ *  return value (confirmed by inspection, not assumed). */
+export function spiralExpand(graph, scored = [], {
+  depth = SPIRAL_DEPTH_DEFAULT,
+  q = SPIRAL_Q_DEFAULT,
+  nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT,
+  kinds = SPIRAL_EXPAND_KINDS,
+  classPredicate = (ind) => (ind.class || "") === "Module",
+  idNormalizer = null,
+  seeds: seedsOpt = null,
+} = {}) {
   const byId = new Map(scored.map((s) => [s.ind.id, s]));
-  const seeds = new Set(byId.keys());
   let maxSeed = 0;
   for (const s of scored) maxSeed = Math.max(maxSeed, s.score);
-  if (!(maxSeed > 0)) return;
-  // Combined undirected adjacency over the expansion kinds (cochange dropped). In-graph degree =
-  // neighbour count over these kinds — the "arcs" the frontier orders and the quantile gate reads.
-  const adj = adjacencyForKinds(graph, SPIRAL_EXPAND_KINDS);
+  const nudgeActive = scored.length > 0 && maxSeed > 0; // the original "!(maxSeed > 0) → return" guard, now a gate rather than a bail-out
+  const seeds = new Set(seedsOpt != null ? seedsOpt : byId.keys());
+  if (!seeds.size) return [];
+  // Combined undirected adjacency over the expansion kinds (cochange dropped for the code-graph
+  // default). In-graph degree = neighbour count over these kinds — the "arcs" the frontier orders
+  // and the quantile gate reads.
+  const adj = adjacencyForKinds(graph, kinds, idNormalizer);
   const degree = (id) => (adj.get(id)?.size || 0);
   // Binary min-heap over the frontier, keyed (hop ASC, degree ASC, id ASC) — pop the closest,
   // least-connected node first, so expansion fans through the sparse surroundings and fizzles at
@@ -757,35 +810,41 @@ function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_
   };
   const visited = new Set(seeds);
   for (const id of seeds) push({ id, hop: 0, deg: degree(id) });
-  const defIdx = definesIndex(graph);
+  let defIdx = null; // lazy: only the nudge-active path (newly-surfaced individuals) needs this
   let emitted = 0;
+  const results = [];
   while (heap.length && emitted < nodeLimit) {
     const node = pop();
+    results.push({ id: node.id, hop: node.hop });
     if (!seeds.has(node.id)) {
-      // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
-      const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
-      const existing = byId.get(node.id);
-      if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
-        existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
-      } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
-        const ind = graph.byId?.get?.(node.id);
-        if (ind && (ind.class || "") === "Module") {
-          const defines = defIdx.get(ind.id) || [];
-          const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
-          scored.push(entry);
-          byId.set(node.id, entry);
+      if (nudgeActive) {
+        // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
+        const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
+        const existing = byId.get(node.id);
+        if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
+          existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
+        } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
+          const ind = graph.byId?.get?.(node.id);
+          if (ind && classPredicate(ind)) {
+            if (!defIdx) defIdx = definesIndex(graph);
+            const defines = defIdx.get(ind.id) || [];
+            const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
+            scored.push(entry);
+            byId.set(node.id, entry);
+          }
         }
       }
       emitted++;
     }
     if (node.hop >= depth) continue;
-    // This step's candidate set = the popped node's unvisited MODULE neighbours; quantile-gate by
-    // degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never fewer than one.
+    // This step's candidate set = the popped node's unvisited neighbours matching classPredicate;
+    // quantile-gate by degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never
+    // fewer than one.
     const cands = [];
     for (const nid of adj.get(node.id) || []) {
       if (visited.has(nid)) continue;
       const ind = graph.byId?.get?.(nid);
-      if (!ind || (ind.class || "") !== "Module") continue; // no phantom (fn-fallback) module ids
+      if (!ind || !classPredicate(ind)) continue; // no phantom (fn-fallback) ids
       cands.push({ id: nid, deg: degree(nid) });
     }
     if (!cands.length) continue;
@@ -797,6 +856,24 @@ function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_
       push({ id: c.id, hop: node.hop + 1, deg: c.deg });
     }
   }
+  return results;
+}
+
+/** The individual with the most recent `createdAtProp` attribute — item 1's ("Traversal") seed
+ *  default: "sort memory-graph individuals by mgx:createdAt descending, seed from the single most
+ *  recent." Deterministic tie-break by id (lowest id wins) when two individuals share the exact
+ *  same timestamp — same total-order convention `spiralExpand`'s own heap uses. Null when no
+ *  individual carries the attribute at all (empty graph, or a graph that predates timestamps).
+ *  ISO-8601 timestamps compare correctly as plain strings (same zero-padded width throughout this
+ *  codebase), so no Date parsing is needed. */
+export function mostRecentIndividual(graph, createdAtProp = CREATED_AT_PROP) {
+  let best = null; // { ind, v }
+  for (const ind of graph?.individuals || []) {
+    const v = (ind?.attributes || []).find((a) => a?.prop === createdAtProp)?.value;
+    if (!v) continue;
+    if (!best || v > best.v || (v === best.v && String(ind.id) < String(best.ind.id))) best = { ind, v };
+  }
+  return best ? best.ind : null;
 }
 
 /** The shared module-ranking core behind renderSearch (text) and searchModulesRanked (path+score).
@@ -1203,6 +1280,67 @@ export function edgesOfKind(graph, kind) {
   return out;
 }
 
+/** A node's "last touched" moment, DERIVED rather than stored (PLAN_VIZ.md §2): the node's own
+ *  `updatedAtProp`/`createdAtProp` attribute, or the max `createdAt` over every edge (in
+ *  `graph.relations`, ACROSS every kind, not just classified ones) touching it as either
+ *  subject or object — whichever is newer. `""` when nothing carries a timestamp at all. Compares
+ *  ISO-8601 strings directly (correct for same-width zero-padded timestamps, no Date parsing).
+ *  Tolerates edges with no `createdAt` field (pre-dating `upsertEdge`'s own stamp, or written by
+ *  a path that bypasses `upsertEdge` entirely) by simply skipping them, never throwing. Operates
+ *  on the shared parsed-graph shape (`graph.relations`/`graph.individuals`), not memory-specific —
+ *  same reasoning `edgesOfKind`/`moduleIdOf` already document. */
+export function derivedUpdatedAt(graph, ind, { createdAtProp = CREATED_AT_PROP, updatedAtProp = UPDATED_AT_PROP } = {}) {
+  if (!ind) return "";
+  const attrs = ind.attributes || [];
+  const own = attrs.find((a) => a?.prop === updatedAtProp)?.value || attrs.find((a) => a?.prop === createdAtProp)?.value || "";
+  let best = own || "";
+  for (const g of graph?.relations || []) {
+    for (const e of g.edges || []) {
+      if (!e || (e.subject !== ind.id && e.object !== ind.id)) continue;
+      const c = e.createdAt;
+      if (!c) continue; // no timestamp on this edge — skip, never throw
+      if (!best || c > best) best = c;
+    }
+  }
+  return best;
+}
+
+/** Turn a `spiralExpand` walk (`[{id, hop}]`) into the `{nodes, edges}` shape
+ *  `tmct viz` renders — pure, no I/O, shared verbatim between the CLI
+ *  (`src/viz.mjs`'s `computeVizGraph`) and the browser bundle's client-side
+ *  re-walk/recentre (PLAN_BREADTH_FIRST_NLU.md §5 follow-on, operator
+ *  directive 2026-07-11) so both paths render byte-identically from the same
+ *  logic, never two hand-maintained copies. `nodes` enrich each walked id with
+ *  its real label/class/timestamps (`derivedUpdatedAt`, above); `edges` are
+ *  every relation-group edge connecting two walked nodes (not just the kinds
+ *  the walk itself traversed through — an incidental edge between two reached
+ *  nodes still renders), de-duped on (subject, object, predicate) across
+ *  relation groups. */
+export function buildVizNodesAndEdges(graph, walked, { createdAtProp = CREATED_AT_PROP, updatedAtProp = UPDATED_AT_PROP } = {}) {
+  const nodeIds = new Set(walked.map((w) => w.id));
+  const nodes = walked.map(({ id, hop }) => {
+    const ind = graph.byId.get(id) || null;
+    const attrs = ind?.attributes || [];
+    const createdAt = attrs.find((a) => a?.prop === createdAtProp)?.value || "";
+    return {
+      id, hop, label: ind?.label || id, class: ind?.class || "", createdAt,
+      updatedAt: derivedUpdatedAt(graph, ind, { createdAtProp, updatedAtProp }),
+    };
+  });
+  const edges = [];
+  const seen = new Set();
+  for (const group of graph.relations || []) {
+    for (const e of group.edges || []) {
+      if (!nodeIds.has(e.subject) || !nodeIds.has(e.object)) continue;
+      const key = `${e.subject} ${e.object} ${group.predicate}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({ source: e.subject, target: e.object, kind: group.predicate });
+    }
+  }
+  return { nodes, edges };
+}
+
 /** moduleIdOf by raw edge-endpoint id: resolves through byId when the individual exists,
  *  else falls back to parsing an `fn:<path>#name` id directly (callsSymbol objects may name
  *  symbols with no individual of their own). Null if it cannot be mapped. */

package/src/extensions.mjs

@@ -5,23 +5,41 @@
 //
 //   resolveExtensions(repoRoot) → { entries: Map<name, ResolvedEntry>, biasByBundle }
 //
-// BUILTIN_EXTENSIONS ships the exact two bundles chat.mjs's bootstrap has
-// always seeded — `seon` and `conceptnet`, both active — plus four shipped-
-// but-INACTIVE tier-2 bundles (`tier2-aws` / `tier2-python` / `tier2-java` /
-// `tier2-general`). Activating one is a config-only edit (`tmct init --corpus
+// BUILTIN_EXTENSIONS' DEFAULT ACTIVE BUNDLE IS `human` (PLAN_SEED.md, the
+// persona flip): a fresh repo now seeds an everyday-world vocabulary (people,
+// places, objects, nature, time/events, body/food, mind — hand-curated from
+// Open English WordNet + Schema.org) rather than the old implicit code-domain
+// default. `seon` and `conceptnet` are SHIPPED but now INACTIVE — both are
+// equally code/tech-domain-biased (conceptnet's committed slice was filtered
+// via a tech-domain seed-term match, PLAN_SEED.md §2), so BOTH flip together,
+// not just seon — a repo that wants the old behavior asks for it explicitly
+// (`tmct init --with-persona code`, or `[extensions.seon]`/`[extensions.
+// conceptnet]` `active = true`). Four more shipped-but-INACTIVE tier-2 bundles
+// (`tier2-aws` / `tier2-python` / `tier2-java` / `tier2-general`) round out the
+// catalog. Activating any of these is a config-only edit (`tmct init --corpus
 // aws`, or a `[extensions.tier2-aws] active = true` in tmct.toml) — zero code
-// change. `tier2-general` (PLAN_AGENTS.md Phase 1) is deliberately NOT a
-// language/domain bundle like the other three — everyday-knowledge concepts
-// with zero code-domain framing, the "wider general-knowledge seed set"
-// bullet made real instead of just mechanically activatable.
+// change. `tier2-general`'s own 49-fact animal/weather set (PLAN_AGENTS.md
+// Phase 1) is superseded IN DEFAULT ROLE by `human`'s much larger
+// `human-nature` clump, but stays shipped/selectable on its own for a caller
+// that wants that narrow slice without the rest of the human persona.
+//
+// `human-medium`/`human-large` (also shipped-but-INACTIVE) are SIZE TIERS of
+// the SAME `human` bundle, not separate personas (PLAN_SEED.md §3) — each
+// holds only the facts that size adds beyond the previous one. Activated
+// together via `tmct init --persona-size medium|large` (bin/tmct.mjs), which
+// resolves them through this same registry.
 //
 // A `tmct.toml` may carry a top-level `[extensions]` table-of-tables
 // (`[extensions.tier2-aws]`, …): a RECOGNIZED name (one of the builtins above)
 // may override `active`/paths/etc; an UNRECOGNIZED name declares a brand new
-// host entry and MUST carry a `kind` (corpus | lexicon | templates | pack) — a
-// `pack` entry may combine any of corpus_path/lexicon_path/templates_path/
-// phrasebook_path under one `active` flag and one provenance name, the shape a
-// third-party vocabulary package hands tmct.
+// host entry and MUST carry a `kind` (corpus | lexicon | templates | pack |
+// ontology) — a `pack` entry may combine any of corpus_path/lexicon_path/
+// templates_path/phrasebook_path under one `active` flag and one provenance
+// name, the shape a third-party vocabulary package hands tmct. `ontology` is a
+// DISTINCT, nameable kind for an ontology bundle (as opposed to a plain
+// `corpus` bundle) — its `ontology_path` key is just an alias populating the
+// SAME internal `corpusPath` field a corpus entry uses, so every downstream
+// seeder/loader needs zero branching by kind name.
 //
 // A SEPARATE top-level `[bias]` table (flat: bundle-name → number) feeds
 // src/memory/bias.mjs's ranking — never nested under `[extensions.*]`.
@@ -45,7 +63,7 @@ import {
   toFacts,
 } from "./corpus/conceptnet.mjs";
 
-export const EXTENSION_KINDS = Object.freeze(["corpus", "lexicon", "templates", "pack"]);
+export const EXTENSION_KINDS = Object.freeze(["corpus", "lexicon", "templates", "pack", "ontology"]);
 
 // The definitional-band-first predicate order chat.mjs's bootstrap has always
 // passed for the ConceptNet seed (SEED_PREFER) — re-declared here (not
@@ -57,15 +75,20 @@ const CONCEPTNET_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:pa
  *  accidentally mutate a module-level singleton. */
 function builtinExtensions() {
   return {
+    // WAS active:true (the implicit code-domain default) — now opt-in.
+    // PLAN_SEED.md §2: re-activate explicitly (`tmct init --with-persona
+    // code`, or `[extensions.seon] active = true`) for the old behavior.
     seon: {
       kind: "corpus",
-      active: true,
+      active: false,
       corpusPath: SEON_CONCEPTS_FILE,
       provenancePrefix: "corpus:seon",
     },
+    // WAS active:true — now opt-in too, not just seon (PLAN_SEED.md §2: the
+    // committed slice is itself tech-domain-filtered, equally biased).
     conceptnet: {
       kind: "corpus",
-      active: true,
+      active: false,
       corpusPath: CONCEPTNET_SLICE_FILE,
       provenancePrefix: "corpus:conceptnet",
       // matches chat.mjs's seedBootstrapMemory exactly: uncapped, definitional
@@ -73,6 +96,40 @@ function builtinExtensions() {
       limit: undefined,
       prefer: CONCEPTNET_PREFER,
     },
+    // NEW — the default active bundle (PLAN_SEED.md). Everyday-world
+    // vocabulary: people, places, objects, nature, time/events, body/food,
+    // mind, plus the human-base/human-bridge scaffolding connecting WordNet's
+    // and Schema.org's independently-built taxonomies (PLAN_SEED.md §3, §8).
+    human: {
+      kind: "corpus",
+      active: true,
+      corpusPath: join(TIER2_DIR, "human.jsonl"),
+      provenancePrefix: "corpus:human",
+    },
+    // NEW — Medium/Large SIZE tiers of the SAME `human` bundle (PLAN_SEED.md
+    // §3), not separate personas: each file holds ONLY the facts that size
+    // adds beyond the previous one (Medium beyond Small, Large beyond
+    // Medium), so activating them is purely ADDITIVE alongside `human`
+    // (never a replacement for it). Both ship INACTIVE — Small stays the
+    // unconditional default — and are activated together via `tmct init
+    // --persona-size medium|large` (bin/tmct.mjs), which resolves them
+    // through this SAME BUILTIN_EXTENSIONS lookup and the ordinary
+    // `--corpus <id>` activation seam (activatePluggableInput). "large"
+    // activates BOTH human-medium and human-large (Large's facts are
+    // Medium's plus its own — both bundles must be active to reach the
+    // full ~13,600-fact total).
+    "human-medium": {
+      kind: "corpus",
+      active: false,
+      corpusPath: join(TIER2_DIR, "human-medium.jsonl"),
+      provenancePrefix: "corpus:human-medium",
+    },
+    "human-large": {
+      kind: "corpus",
+      active: false,
+      corpusPath: join(TIER2_DIR, "human-large.jsonl"),
+      provenancePrefix: "corpus:human-large",
+    },
     "tier2-aws": {
       kind: "corpus",
       active: false,
@@ -118,6 +175,9 @@ export function validateExtensionEntry(name, entry) {
   if (entry.kind === "corpus" && !entry.corpusPath) {
     throw new Error(`extension "${name}": a "corpus" entry needs corpus_path`);
   }
+  if (entry.kind === "ontology" && !entry.corpusPath) {
+    throw new Error(`extension "${name}": an "ontology" entry needs ontology_path`);
+  }
   if (entry.kind === "lexicon" && !entry.lexiconPath) {
     throw new Error(`extension "${name}": a "lexicon" entry needs lexicon_path`);
   }
@@ -154,6 +214,7 @@ function mergeExtensionEntry(name, builtin, override, repoRoot) {
   };
   const paths = [
     ["corpus_path", "corpusPath"],
+    ["ontology_path", "corpusPath"], // alias: an "ontology" entry's own path key, same internal field as "corpus"
     ["lexicon_path", "lexiconPath"],
     ["templates_path", "templatesPath"],
     ["phrasebook_path", "phrasebookPath"],
@@ -184,9 +245,13 @@ function mergeExtensionEntry(name, builtin, override, repoRoot) {
  *     table (default {} — every bundle then ranks at bias 1, see bias.mjs).
  * No `tmct.toml` (or one with no `[extensions]`/`[bias]` tables) resolves to
  * exactly today's implicit seon+conceptnet default, byte-identical.
+ *
+ * `configFile` (optional): an explicit tmct.toml path override — `tmct extend
+ * --validate <dir> --config <path>` — read INSTEAD of `<repoRoot>/tmct.toml`;
+ * `repoRoot` still anchors every resource path (unchanged).
  */
-export async function resolveExtensions(repoRoot) {
-  const raw = repoRoot ? await loadTomlConfig(repoRoot) : null;
+export async function resolveExtensions(repoRoot, { configFile } = {}) {
+  const raw = repoRoot ? await loadTomlConfig(repoRoot, configFile ? { file: configFile } : {}) : null;
   const defs = builtinExtensions();
   const rawExtensions = (raw && raw.extensions && typeof raw.extensions === "object") ? raw.extensions : {};
   const rawBias = (raw && raw.bias && typeof raw.bias === "object") ? raw.bias : {};
@@ -216,12 +281,19 @@ export async function resolveExtensions(repoRoot) {
 
 // ---- Part 2: the unified corpus loader loop ---------------------------------
 
-/** Seed every ACTIVE `corpus`-kind entry (in the Map's own fixed order — seon,
+/** Seed every ACTIVE `corpus`/`ontology`-kind entry, plus any ACTIVE `pack`-kind
+ *  entry that declares a `corpusPath` (in the Map's own fixed order — seon,
  *  conceptnet, then the rest sorted by name) into `repo`'s memory, ONE
  *  seedMemory() call per bundle. Shared by chat.mjs's first-run bootstrap,
  *  `tmct init`'s seed step and `tmct init --corpus <id>` — so all three read
  *  the SAME loop instead of three independent hardcoded call sites.
  *
+ *  BUGFIX (this batch): a `pack`-kind entry's `corpusPath` used to be silently
+ *  skipped here despite this module's own docblock claiming pack entries
+ *  combine corpus_path/lexicon_path/etc — a pack's corpus facts never made it
+ *  into memory. Fixed by seeding any active pack entry that declares a
+ *  corpusPath, alongside corpus/ontology entries.
+ *
  *  FAILURE-TOLERANT per bundle (init.mjs's own doctrine: a missing/broken
  *  corpus degrades to "not seeded", never a crash): one bad third-party pack's
  *  seedMemory throw is CAUGHT and recorded as `perBundle[name].error` — logged
@@ -235,7 +307,16 @@ export async function seedActiveCorpusEntries(repo, entries) {
   let skipped = 0;
   let total = 0;
   for (const [name, entry] of entries instanceof Map ? entries : new Map()) {
-    if (entry.kind !== "corpus" || !entry.active) continue;
+    // PLAN_SEED.md §2 bug fix: a "pack"-kind entry with its own corpusPath
+    // combines corpus/lexicon/templates under one active flag (this module's
+    // own docblock says so) but was previously never actually seeded here —
+    // only bare `kind: "corpus"` entries were. Broadened, not narrowed: every
+    // existing `kind: "corpus"`/`kind: "ontology"` entry (seon/conceptnet/
+    // human/tier2-*) behaves identically to before; only a pack entry that
+    // DOES carry a corpusPath newly qualifies.
+    if (!entry.active) continue;
+    const seedable = entry.kind === "corpus" || entry.kind === "ontology" || (entry.kind === "pack" && entry.corpusPath);
+    if (!seedable) continue;
     try {
       const res = await seedMemory(repo, {
         slicePath: entry.corpusPath,