@polycode-projects/the-mechanical-code-talker 2.2.0 → 2.3.0

package/src/domain/router/registry.mjs

@@ -1,15 +1,15 @@
 // src/domain/router/registry.mjs — the capability registry.
 //
 // Each tmct tool is modelled as a STRIPS/PDDL operator declared as DATA: a `Capability` with
-// typed `Parameter`s, `Precondition`s, and `Effect`s (add-list/delete-list). Preconditions are
-// the safety gate guardrail.mjs checks before a call fires; resolver.mjs backward-chains from
-// a goal to a capability whose add-list achieves it.
+// typed `Parameter`s, `Precondition`s, and `Effect`s (add-list/delete-list). resolver.mjs
+// backward-chains from a goal to a capability whose add-list achieves it, and proves the
+// preconditions bind before the call fires.
 //
 // Plain data + pure accessors, no I/O. Tool names + parameter arg keys are the
 // exact ones src/tools/server.mjs `dispatchTool` reads, so a bound call this registry validates is
 // directly dispatchable.
 
-export const PREFIXES = Object.freeze({
+const PREFIXES = Object.freeze({
   cap: "urn:tmct:cap#", // the capability/operator vocabulary (this module)
   mgx: "urn:tmct:mgx#", // tmct's code-graph predicates (imports/calls/tests/…)
   seon: "http://se-on.org/ontologies/seon.owl#", // software-evolution ontology classes
@@ -25,7 +25,7 @@ export const VOCAB = Object.freeze({
 
 // Parameter entity-KINDS — the seon/mgx classes a slot ranges over. `Query` and
 // `Kind`/`Package` are free-text / enum slots (no graph resolution); the rest
-// name a graph entity the guardrail must prove RESOLVES before the call fires.
+// name a graph entity the resolver must prove RESOLVES before the call fires.
 export const KINDS = Object.freeze({
   Symbol: "seon:CodeEntity", // any code symbol: function/method/class/module/attribute
   Module: "seon:Module",
@@ -196,11 +196,10 @@ function deepFreeze(value) {
 }
 
 /** Register a capability at runtime (e.g. a taught action family bridged in by
- *  src/domain/router/taught.mjs). `readOnly` must be an explicit boolean; a
- *  `readOnly: false` record is forced `dispatchable: false` — the guardrail's
- *  candidate enrichment re-dispatches a tool once per tied candidate, which is
- *  only safe when dispatch performs no writes. Returns an `unregister()`
- *  disposer. */
+ *  src/domain/router/taught.mjs). `readOnly` must be an explicit boolean: it is
+ *  what resolver.mjs's dispatch gate reads, and a `readOnly: false` record is
+ *  never dispatched. `dispatchable` is derived from it for callers that want the
+ *  record to state the conclusion. Returns an `unregister()` disposer. */
 export function registerCapability(cap) {
   const name = cap && typeof cap.name === "string" ? cap.name.trim() : "";
   if (!name) throw new Error("registerCapability: a non-empty name is required");
@@ -260,14 +259,14 @@ export function isCapability(n) { return Boolean(byName[n]); }
 /** The parameter slots of capability `n` (empty array if unknown/no-arg). */
 export function parametersOf(n) { return byName[n]?.parameters ?? []; }
 
-/** The preconditions of capability `n` (the safety gate the guardrail checks). */
+/** The preconditions of capability `n` (the safety gate the resolver checks). */
 export function preconditionsOf(n) { return byName[n]?.preconditions ?? []; }
 
 /** The effects of capability `n` — `{ add, del }` (the proof-chain contribution). */
 export function effectsOf(n) { return byName[n]?.effects ?? { add: [], del: [] }; }
 
-/** The set of arg keys capability `n` accepts (for the guardrail's unknown-arg
- *  check). Returns a Set of strings. */
+/** The set of arg keys capability `n` accepts (for call-validator.mjs's
+ *  unknown-arg check). Returns a Set of strings. */
 export function argKeysOf(n) {
   return new Set(parametersOf(n).map((p) => p.arg));
 }

package/src/domain/router/resolver.mjs

@@ -200,7 +200,7 @@ export function commandCapability(request, declaredNames, selectTool) {
 
 /** Build the glass-box proof chain for a grounded single call: its preconditions then the
  *  epistemic add-effect. Dispatch has succeeded, so `resolves` steps are ok. */
-export function proofFor(name, input) {
+function proofFor(name, input) {
   const steps = [];
   for (const pre of preconditionsOf(name)) {
     if (pre.pred === PRECOND.graphLoaded) steps.push({ step: "precondition", pred: pre.pred, ok: true });
@@ -213,11 +213,21 @@ export function proofFor(name, input) {
 
 const REFUSE = (why, extra) => ({ selected: null, refused: true, reason: why, ...(extra || {}) });
 
-/** Breadth-first ambiguity: dispatches the SAME tool once per tied candidate (safe since
- *  every registered capability is read-only). Returns `[{candidate, result}, ...]`, or
- *  undefined when there is no dispatcher to run it with. */
+/** The gate both dispatch sites below go through. Dispatching is an OBSERVATION, so it
+ *  may only ever run a capability whose own record says it performs no writes. A
+ *  world-mutating record (the ones src/domain/router/taught.mjs registers carry
+ *  `readOnly: false`) is planned over and simulated, never fired here. */
+function dispatchPerformsNoWrites(capName) {
+  return capabilityByName(capName)?.readOnly === true;
+}
+
+/** Breadth-first ambiguity: dispatches the SAME tool once per tied candidate, which only
+ *  stays safe while the tool writes nothing. Returns `[{candidate, result}, ...]`, or
+ *  undefined when there is no dispatcher to run it with — or when the capability is not
+ *  read-only. */
 async function dispatchEachCandidate(pool, capName, arg, ctx, execute) {
   if (!execute || !ctx.dispatch) return undefined;
+  if (!dispatchPerformsNoWrites(capName)) return undefined;
   const results = [];
   for (const c of pool) {
     const res = await ctx.dispatch(capName, { [arg]: c.label });
@@ -283,6 +293,9 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
   if (problems.length) return REFUSE(`bound call did not validate: ${problems.map((p) => p.reason).join(",")}`);
 
   if (execute && ctx.dispatch) {
+    if (!dispatchPerformsNoWrites(pick.name)) {
+      return REFUSE(`${pick.name} is not read-only; the resolver observes, it never fires a world-mutating capability`);
+    }
     const res = await ctx.dispatch(pick.name, input);
     if (!res.ok) return REFUSE(`unresolvable at dispatch: ${res.error}`);
     return { selected: call, proof: proofFor(pick.name, input), why, resolved: res.resolved ?? resolved, observed: String(res.text ?? "").slice(0, 240) };
@@ -293,7 +306,7 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
 // ---- reachability (used by the bidirectional conformance test + docs) ---------
 
 /** The epistemic topics some NL intent or imperative frame can reach. */
-export function nlReachableTopics() {
+function nlReachableTopics() {
   const topics = new Set();
   for (const v of Object.values(NL_INTENTS)) topics.add(v.topic);
   for (const f of FRAMES) topics.add(f.topic);

package/src/domain/router/results.mjs

@@ -147,7 +147,7 @@ export function callersLabels(graph, ind) {
 }
 
 /** Callees of a symbol (mirrors renderCallees). */
-export function calleesLabels(graph, ind) {
+function calleesLabels(graph, ind) {
   if (CALL_SYMBOL_CLASSES.has(ind.class)) {
     return uniqSort(edgesOfKind(graph, "callsSymbol").filter((e) => e.subject === ind.id).map((e) => e.objectLabel || e.object));
   }
@@ -157,7 +157,7 @@ export function calleesLabels(graph, ind) {
 }
 
 /** Subclasses (transitive) of a class (mirrors renderSubclasses closure). */
-export function subclassesLabels(graph, ind) {
+function subclassesLabels(graph, ind) {
   const inherits = edgesOfKind(graph, "inherits");
   const childrenOf = new Map();
   for (const e of inherits) {
@@ -198,7 +198,7 @@ export function cochangesLabels(graph, ind) {
 }
 
 /** A module's public exports (mirrors renderExports — the `reexports` edge). */
-export function exportsLabels(graph, ind) {
+function exportsLabels(graph, ind) {
   const modId = moduleIdOf(graph, ind);
   if (!modId) return [];
   return uniqSort(edgesOfKind(graph, "reexports").filter((e) => e.subject === modId).map((e) => e.objectLabel || e.object));

package/src/domain/router/taught.mjs

@@ -3,9 +3,10 @@
 // A taught game action ("you can move a disk onto a peg" + its preconditions
 // and effect) becomes a registered capability record so the router's operator
 // model covers taught actions and built-in query tools alike. Registered
-// records carry readOnly: false, so the guardrail never dispatches them — the
-// resolver also never selects them on its own, because it backward-chains over
-// `knows` add-effects and these records carry world-triple effects instead.
+// records carry readOnly: false, so the resolver's dispatch gate refuses to
+// fire them — and it never selects one on its own anyway, because it
+// backward-chains over `knows` add-effects and these carry world-triple
+// effects instead. They are planned over and simulated.
 
 import { capabilityByName, registerCapability } from "./registry.mjs";
 

package/src/domain/schemaorg/turtle.mjs

@@ -0,0 +1,25 @@
+// turtle.mjs — a very small Turtle reader for schema.ttl's OWN regular shape:
+// each class is one `:Name a rdfs:Class ;` block terminated by a line ending
+// in ` .`, with `rdfs:label`/`rdfs:comment`/`rdfs:subClassOf` as `;`-separated
+// predicate lines. Not a general Turtle parser — schema.ttl's own generator
+// emits a single, very regular style (confirmed by direct inspection).
+//
+// Pure: text in, Map out, no imports.
+
+/** Every rdfs:Class in `text`, as name -> { name, label, comment, subClassOf }.
+ *  A class with no rdfs:label falls back to its own name; no rdfs:comment
+ *  yields "". Blocks that are not classes (properties, say) are skipped. */
+export function parseSchemaClasses(text) {
+  const classes = new Map();
+  const blocks = text.split(/\n(?=:[A-Za-z])/); // each class/property starts a new top-level block
+  for (const block of blocks) {
+    const head = /^:([A-Za-z0-9_]+)\s+a\s+rdfs:Class\s*;/.exec(block);
+    if (!head) continue;
+    const name = head[1];
+    const label = /rdfs:label\s+"([^"]*)"/.exec(block)?.[1] || name;
+    const comment = /rdfs:comment\s+"([^"]*)"/.exec(block)?.[1] || "";
+    const subClassOf = [...block.matchAll(/rdfs:subClassOf\s+:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+    classes.set(name, { name, label, comment, subClassOf });
+  }
+  return classes;
+}

package/src/domain/semcor/parse.mjs

@@ -0,0 +1,87 @@
+// parse.mjs — a targeted reader for SemCor's own regular YAML shape:
+// flow-style lemmas/pos arrays and a folded single-quoted `text` scalar, one
+// record per sentence. Not a general YAML parser (this repo has no YAML
+// dependency), and not the same shape as the WordNet dump's reader in
+// src/domain/wordnet/yaml.mjs — SemCor's flow style is JSON-compatible once
+// isolated, which the WordNet subset never is.
+//
+// Pure: text in, arrays/strings out, no imports, so it runs with no SemCor
+// clone present.
+
+/** Split a SemCor YAML file into per-sentence record blocks (top-level
+ *  "<key>:" lines, skipping the leading "_meta:" schema block). */
+export function splitRecords(text) {
+  const lines = text.split("\n");
+  const blocks = [];
+  let i = 0;
+  while (i < lines.length && lines[i] !== "_meta:") i++;
+  i += 1;
+  while (i < lines.length && (lines[i].startsWith(" ") || lines[i].trim() === "")) i++; // skip rest of _meta
+  while (i < lines.length) {
+    if (/^[A-Za-z0-9_]+:$/.test(lines[i])) {
+      let j = i + 1;
+      const block = [];
+      while (j < lines.length && !/^[A-Za-z0-9_]+:$/.test(lines[j])) {
+        block.push(lines[j]);
+        j += 1;
+      }
+      blocks.push(block.join("\n"));
+      i = j;
+    } else {
+      i += 1;
+    }
+  }
+  return blocks;
+}
+
+/** Extract a flow-style JSON-compatible array value for `key` from one
+ *  record block (lemmas/pos are double-quoted string arrays — valid JSON
+ *  once isolated), balancing brackets across a line wrap if one occurs. */
+export function extractArray(block, key) {
+  const re = new RegExp(`^\\s*${key}:\\s*(\\[.*)$`, "m");
+  const m = re.exec(block);
+  if (!m) return null;
+  let buf = m[1];
+  let depth = (buf.match(/\[/g) || []).length - (buf.match(/\]/g) || []).length;
+  const afterIdx = block.indexOf(m[0]) + m[0].length;
+  const rest = block.slice(afterIdx).split("\n");
+  let ri = 0;
+  while (depth > 0 && ri < rest.length) {
+    buf += `\n${rest[ri]}`;
+    depth += (rest[ri].match(/\[/g) || []).length - (rest[ri].match(/\]/g) || []).length;
+    ri += 1;
+  }
+  try { return JSON.parse(buf); } catch { return null; }
+}
+
+/** Extract the `text:` folded single-quoted scalar (YAML's own `''` ->
+ *  literal `'` escape; line breaks folded to spaces). */
+export function extractText(block) {
+  const m = /^\s*text:\s*'/m.exec(block);
+  if (!m) return null;
+  const start = block.indexOf("'", m.index);
+  let i = start + 1;
+  let raw = "";
+  while (i < block.length) {
+    if (block[i] === "'") {
+      if (block[i + 1] === "'") { raw += "'"; i += 2; continue; }
+      break;
+    }
+    raw += block[i];
+    i += 1;
+  }
+  return raw.replace(/\s+/g, " ").trim();
+}
+
+export const NOUN_POS = new Set(["NN", "NNS"]);
+
+/** Simple-grammar filter: short, no semicolons/colons, no embedded quotes
+ *  (which signal reported speech), no more than one comma — a rough proxy for
+ *  "no complex embedded clauses". */
+export function isSimpleSentence(text, wordCount) {
+  if (wordCount > 18) return false;
+  if (/[;:]/.test(text)) return false;
+  if ((text.match(/,/g) || []).length > 1) return false;
+  if (/"/.test(text)) return false;
+  return true;
+}

package/src/domain/syllogise.mjs

@@ -42,13 +42,13 @@ function requireStore(store, needed, caller) {
 /** scm-sco: the subClassOf-transitivity rule, and the provenance tag its
  *  conclusions carry. */
 export const SUBCLASS_PREDICATE = "rdfs:subClassOf";
-export const SYLLOGISE_RULE = "subClassOf";
+const SYLLOGISE_RULE = "subClassOf";
 export const ENTAILED_PROVENANCE = `entailed:${SYLLOGISE_RULE}`;
 
 /** cax-sco: the type-propagation rule, and the provenance tag its conclusions
  *  carry. */
 export const TYPE_PREDICATE = "rdf:type";
-export const CAX_SCO_RULE = "type";
+const CAX_SCO_RULE = "type";
 export const ENTAILED_TYPE_PROVENANCE = `entailed:${CAX_SCO_RULE}`;
 
 /** cax-dw: x rdf:type C1, C1 owl:disjointWith C2 |= x is NOT of type C2 — a
@@ -396,7 +396,7 @@ export function deriveSomeValuesFromApplication(propertyEdges, typeEdges, subCla
 // deriveSomeValuesFromApplication reconstructs someValuesFrom restrictions.
 const HAS_PROPERTY_KEY = "has"; // synthetic marker parseCardinality always mints, never a real taught verb
 const CARDINALITY_KIND_OF = { "owl:cardinality": "exactly", "owl:mincardinality": "min", "owl:maxcardinality": "max" };
-export const ON_CLASS_PREDICATE = "owl:onClass";
+const ON_CLASS_PREDICATE = "owl:onClass";
 
 /** Reconstructs pattern-5 cardinality restriction records from raw stored
  *  rows touching a restriction node. A restriction is only admitted when its
@@ -525,7 +525,7 @@ function findOwnCardinalityRestriction(subClassEdges, cardinalityRestrictionEdge
 }
 
 // ---- cardinality monotonicity (outside OWL 2 RL's own decidable profile) ----
-export const SCM_CARD_RULE = "cardinalityMonotonicity";
+const SCM_CARD_RULE = "cardinalityMonotonicity";
 /** Same sub-1 discount as CAX_DW_RULE_CONFIDENCE. No `syllogise()` call site
  *  (this rule is query-rooted, never an enumerable Fact) — defined anyway so
  *  chat.mjs's live proof chase can attach an auditable confidence figure
@@ -557,7 +557,7 @@ export function proveCardinalityAtLeast(subClassEdges, cardinalityRestrictionEdg
 // generalization — see this file's header comment; `cax-` prefix per this
 // ladder's "produces a provable no" naming convention, same epistemic status
 // as cax-dw) ----
-export const CAX_MAXC0_RULE = "maxCardinalityZero";
+const CAX_MAXC0_RULE = "maxCardinalityZero";
 /** Same sub-1 discount and query-rooted caveat as CARDINALITY_RULE_CONFIDENCE. */
 export const CAX_MAXC0_RULE_CONFIDENCE = 0.95;
 
@@ -989,7 +989,7 @@ function buildSurvivorDerivabilityCheck(rows) {
  * A survivor keeps its stale, still-single justification as-is; a later
  * retraction of its OTHER supporting path therefore won't re-examine it.
  * Re-grounding survivors — or tracking every alternate justification set —
- * is the ATMS horizon (PLAN_SYLLOGIST.md §3), not this bounded slice.
+ * is the ATMS horizon, not this bounded slice.
  *
  * Returns { retracted, count, budget, depth, truncated, found } — `found` is
  * false when `subject ⊑ object` was never a stored fact.

package/src/domain/version-stamp.mjs

@@ -0,0 +1,36 @@
+// version-stamp.mjs — the home page's #pkg-version element, written and read
+// from one place. Pure: strings in, strings out, no imports, so the deploy
+// smoke check can reach it without npm ci.
+//
+// This existed three times and the copies had already drifted: the writer
+// matched [^<]*, the smoke check demanded \d+\.\d+\.\d+, and the estate test
+// accepted [^<\s]*. A writer that accepts what its reader rejects is a green
+// build and a failed deploy, so the pattern lives here and all three call it.
+
+/** The element that carries the version, and the value inside it. */
+const STAMP = /(id="pkg-version"[^>]*>)\s*v?([^<]*?)\s*(<)/;
+
+/** A semver core, which is what the deploy smoke check is entitled to expect. */
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** True iff `html` carries an element the stamp can be written into. */
+export function hasVersionStamp(html) {
+  return STAMP.test(html);
+}
+
+/** The version `html` displays, or null when the element is absent or holds
+ *  something that is not a semver core (an unstamped placeholder, say). */
+export function parseVersionStamp(html) {
+  const found = STAMP.exec(html);
+  if (!found) return null;
+  const value = found[2].trim();
+  return SEMVER.test(value) ? value : null;
+}
+
+/** `html` with the stamp set to `version`. Throws when there is nothing to
+ *  stamp — a page that lost its element would otherwise publish blank. */
+export function stampVersion(html, version) {
+  if (!SEMVER.test(version)) throw new Error(`not a stampable version: "${version}"`);
+  if (!hasVersionStamp(html)) throw new Error("no #pkg-version element to stamp");
+  return html.replace(STAMP, `$1${version}$3`);
+}

package/src/domain/wordnet/yaml.mjs

@@ -0,0 +1,133 @@
+// yaml.mjs — a reader for the small YAML subset the Open English WordNet dump
+// uses: 2-space-indented block mappings/sequences, quoted or bare scalars, and
+// long scalar list-items that simply WRAP onto a further-indented continuation
+// line. No block scalars, no anchors, no flow style — confirmed by direct
+// inspection of the dump. This reads exactly that subset; it is not a general
+// YAML parser.
+//
+// Pure: text in, object out, no imports, so it is testable without the WordNet
+// clone the scripts that call it need.
+
+/** Non-greedy key group so a MULTI-WORD entry key ("M-1 rifle", "ice cream")
+ *  still matches — the first ": "/end-of-line colon wins, exactly as real
+ *  YAML's block-mapping key/value split works. A plain wrapped scalar
+ *  continuation line (a definition/example fragment) only coincidentally
+ *  matches this if it ALSO happens to contain a bare "word: " sequence — rare
+ *  in this corpus's prose, and this feeds a maintainer worksheet whose output
+ *  is hand-reviewed, not a correctness-critical parser. */
+const KEY_RE = /^(.+?):(\s+(.*)|)$/;
+
+const isDash = (t) => t === "-" || t.startsWith("- ");
+
+function parseScalar(s) {
+  const t = s.trim();
+  if ((t.startsWith("'") && t.endsWith("'") && t.length >= 2) || (t.startsWith('"') && t.endsWith('"') && t.length >= 2)) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+export function parseYaml(text) {
+  const rawLines = text.split("\n");
+  const lines = [];
+  for (const line of rawLines) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    lines.push({ indent, text: line.trimStart() });
+  }
+  let pos = 0;
+
+  // A scalar that may continue on subsequent MORE-indented lines with no
+  // "key:"/"- " marker of their own (WordNet's definition-wrapping style). A
+  // QUOTED scalar ('...' or "...") is handled separately: WordNet definitions
+  // routinely contain a literal ": " inside the quoted text itself (e.g. "…
+  // Matthew, Mark, Luke, and John" split across a line boundary right after a
+  // colon) — the bare-scalar heuristic below would misread that continuation
+  // line as a new "key:" line and truncate the string. Once inside an open
+  // quote, EVERY line is a continuation until one ends with the matching
+  // closing quote, full stop — the key/dash heuristic never applies inside it.
+  function parseScalarOrContinue(first, minContinIndent) {
+    const trimmed = first.trim();
+    const quote = trimmed[0] === "'" || trimmed[0] === '"' ? trimmed[0] : null;
+    if (quote) {
+      const closes = (s) => s.length >= 2 && s.endsWith(quote);
+      let buf = trimmed;
+      while (!closes(buf) && pos < lines.length && lines[pos].indent >= minContinIndent) {
+        buf += " " + lines[pos].text.trim();
+        pos += 1;
+      }
+      return closes(buf) ? buf.slice(1, -1) : buf;
+    }
+    let s = parseScalar(first);
+    while (pos < lines.length && lines[pos].indent >= minContinIndent
+      && !isDash(lines[pos].text) && !KEY_RE.test(lines[pos].text)) {
+      s += " " + lines[pos].text.trim();
+      pos += 1;
+    }
+    return s;
+  }
+
+  /** The value that follows a "key:" (bare, no inline scalar) — peeks at the
+   *  next line to decide whether it's a nested sequence (which YAML allows to
+   *  sit at the SAME indent as the key itself, not just deeper) or a nested
+   *  mapping (which must be deeper) or simply absent (null). `parentIndent`
+   *  is the indent of the "key:" line whose value this resolves. */
+  function parseValue(parentIndent) {
+    if (pos >= lines.length || lines[pos].indent < parentIndent) return null;
+    const line = lines[pos];
+    if (isDash(line.text)) return parseSeq(line.indent);
+    if (line.indent > parentIndent && KEY_RE.test(line.text)) return parseMap(line.indent);
+    return null;
+  }
+
+  function parseSeq(indent) {
+    const arr = [];
+    while (pos < lines.length && lines[pos].indent === indent && isDash(lines[pos].text)) {
+      const dashIndent = indent;
+      const rest = lines[pos].text === "-" ? "" : lines[pos].text.slice(2);
+      pos += 1;
+      if (rest === "") {
+        arr.push(parseValue(dashIndent));
+        continue;
+      }
+      // A quoted scalar is classified FIRST, unconditionally — WordNet
+      // definitions routinely contain a literal ": " (or a colon at the very
+      // end of a wrapped line, e.g. "…including:\n  whales, …") inside quoted
+      // prose, which KEY_RE would otherwise misread as an inline "- key:"
+      // mapping. Only an UNQUOTED rest is even considered for that shape.
+      const quoted = rest[0] === "'" || rest[0] === '"';
+      const m = quoted ? null : KEY_RE.exec(rest);
+      if (m) {
+        // "- key: value" or "- key:" — an inline mapping for this list item;
+        // sibling keys of the SAME item are indented +2 from the dash.
+        const obj = {};
+        obj[m[1]] = m[3] !== undefined && m[3] !== "" ? parseScalarOrContinue(m[3], dashIndent + 2) : parseValue(dashIndent + 2);
+        while (pos < lines.length && lines[pos].indent === dashIndent + 2 && KEY_RE.test(lines[pos].text)) {
+          const mm = KEY_RE.exec(lines[pos].text);
+          pos += 1;
+          obj[mm[1]] = mm[3] !== undefined && mm[3] !== "" ? parseScalarOrContinue(mm[3], dashIndent + 4) : parseValue(dashIndent + 2);
+        }
+        arr.push(obj);
+      } else {
+        // a plain (or quoted) scalar list item — may wrap onto continuation lines
+        arr.push(parseScalarOrContinue(rest, dashIndent + 2));
+      }
+    }
+    return arr;
+  }
+
+  function parseMap(indent) {
+    const obj = {};
+    while (pos < lines.length && lines[pos].indent === indent && KEY_RE.test(lines[pos].text)) {
+      const m = KEY_RE.exec(lines[pos].text);
+      const key = parseScalar(m[1]);
+      pos += 1;
+      obj[key] = m[3] !== undefined && m[3] !== "" ? parseScalarOrContinue(m[3], indent + 2) : parseValue(indent);
+      // (parseValue(indent) — not indent+2 — so a same-indent sequence value
+      // is recognized; parseValue itself accepts child indent >= indent.)
+    }
+    return obj;
+  }
+
+  return parseMap(0);
+}

package/src/services/chat-session.mjs

@@ -9,8 +9,8 @@
 //
 // createSession(…) is the SESSION SINK every shell shares (runChat's
 // readline loop below, src/surfaces/tui/app.mjs's Ink shell). chat.mjs re-exports
-// createSession/runChat/gitToplevel and the session constants so existing
-// import sites keep working.
+// createSession/runChat and the session constants so existing import sites
+// keep working.
 
 import { join, resolve } from "node:path";
 import { createWriteStream } from "node:fs";

package/src/services/chat.mjs

@@ -62,8 +62,8 @@ export { uuidv7 };
 // in the session layer so runTurn and the fact engine below stay free of
 // node:fs/child_process/os/readline. Re-exported here (services → services) so
 // every existing import site — bin, tui, server-http, index, tests — keeps
-// importing createSession/runChat/gitToplevel/SESSION_LOG_DIR/PROMPT from chat.mjs.
-export { createSession, runChat, gitToplevel, SESSION_LOG_DIR, PROMPT } from "./chat-session.mjs";
+// importing createSession/runChat/SESSION_LOG_DIR/PROMPT from chat.mjs.
+export { createSession, runChat, SESSION_LOG_DIR, PROMPT } from "./chat-session.mjs";
 
 /** dispatchTool("tmct_ask", …) returns the prose answer plus a delimited
  *  machine-readable envelope; the TUI shows the prose only. Reused verbatim

package/src/services/cli-args.mjs

@@ -15,8 +15,8 @@
 //   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 (would be circular) — the git-root lookup below
-// is a small, self-contained copy of chat.mjs's own gitToplevel().
+// Deliberately does NOT import chat-session.mjs (would be circular) — the git-root lookup
+// below is a small, self-contained copy of chat-session.mjs's own gitToplevel().
 
 import { spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
@@ -26,8 +26,8 @@ import { loadTomlConfig, normalizeConfig, mergeEffective, CONFIG_FILE } from "..
 import { DEFAULT_GRAPH_REL } from "../adapters/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. */
+ *  unavailable). A deliberate re-declaration of chat-session.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" });

package/src/services/finish.mjs

@@ -18,7 +18,7 @@ export { flatten };
 
 const GRAMMAR_DIR = dirname(fileURLToPath(import.meta.url));
 /** The data-driven grammar-rule table. */
-export const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "..", "data", "templates", "grammar-rules.toml");
+const GRAMMAR_RULES_FILE = join(GRAMMAR_DIR, "..", "..", "data", "templates", "grammar-rules.toml");
 
 /** The segment type vocabulary. `prose` is the only unprotected type. */
 export const SEGMENT_TYPES = Object.freeze([

package/src/services/ledger-viz.mjs

@@ -1,6 +1,5 @@
 // ledger-viz.mjs — `tmct viz`: the memory graph as a readable ledger of
-// fact-sentences around one focus term, with the in-page chat dock
-// (PLAN_VIZ_LEDGER.md).
+// fact-sentences around one focus term, with the in-page chat dock.
 //
 // Three pure/impure-separated pieces:
 //   - computeLedgerData(repoDir, opts)      — I/O (loadMemory) + derivation
@@ -16,7 +15,7 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
-export const LEDGER_ROW_LIMIT_DEFAULT = 20000;
+const LEDGER_ROW_LIMIT_DEFAULT = 20000;
 
 /** Read the checked-in browser memory-ask-engine bundle
  *  (`src/surfaces/web/memory-ask-browser.bundle.js`) — the real memory-graph answer engine

package/src/services/sessions.mjs

@@ -24,7 +24,7 @@ import { turnKey } from "../domain/memory/session-turns.mjs";
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 
 export const SESSION_CLASS = "Session";
-export const ASKS_ABOUT_PREDICATE = "asksAbout";
+const ASKS_ABOUT_PREDICATE = "asksAbout";
 export const ASKS_ABOUT_PROP = "mgx:asksAbout";
 
 const QUERIES_ATTR_CAP = 500; // joined-queries attribute cap (mirrors commitMessage's cap idea)
@@ -111,9 +111,9 @@ export function upsertSession(entities, record) {
     attributes: [
       // referenced via the imported constant (single-sourced from memory/core.mjs)
       { prop: CREATED_AT_PROP, key: "createdAt", value: priorCreatedAt || started || new Date().toISOString() },
-      // this IS a genuinely-mutated individual (re-written every chat turn, PLAN_VIZ.md §2's
-      // concrete "Session" case) — stamp updatedAt explicitly since the derived "max over edges"
-      // rule can't see an own-attribute rewrite that touches no edge.
+      // a Session really is mutated — re-written every chat turn — so stamp updatedAt
+      // explicitly: the derived "max over edges" rule cannot see an own-attribute rewrite
+      // that touches no edge.
       { prop: UPDATED_AT_PROP, key: "updatedAt", value: new Date().toISOString() },
       { prop: "mgx:sessionStarted", key: "started", value: started },
       { prop: "mgx:sessionEnded", key: "ended", value: ended },

package/src/services/viz-theme.mjs

@@ -1,7 +1,6 @@
 // viz-theme.mjs — the shared assets for tmct's generated HTML pages
-// (the ledger explorer and the plan player): the visual token table
-// (PLAN_VIZ_LEDGER.md's reference values) plus the escaping helpers every
-// page builder needs.
+// (the ledger explorer and the plan player): the visual token table plus the
+// escaping helpers every page builder needs.
 //
 // Trust tiers are precomputed rgba() values per provenance color so pages
 // render identically on browsers without color-mix() support.
@@ -30,7 +29,7 @@ function rgba(hex, alpha) {
   return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
 }
 
-export const TOKENS = Object.freeze({
+const TOKENS = Object.freeze({
   light: Object.freeze({
     bg: "#F7F6F2", ink: "#23272B", muted: "#6E7168", line: "#DDD9D0", card: "#FFFFFF",
     taught: "#2E7D4F", corpus: "#5A80AC", entail: "#B07C2E", alert: "#B0503F",