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

package/bin/tmct.mjs

@@ -167,7 +167,7 @@ const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
  *   into a caller's prompt.
  *
  *  Two ways to say which modules: an explicit `modules` array (unchanged), or a `query` string —
- *  auto-locate + score-gap-select (R1b, the shipped default as of 2026-07-02) in one call, so a
+ *  auto-locate + score-gap-select (the shipped default) in one call, so a
  *  real caller no longer has to run `tmct_locate` and hand-pick a module themselves. `modules`
  *  wins if both are given. The header reports which modules were actually selected either way.
  *
@@ -741,8 +741,7 @@ async function main() {
     const lexiconVal = strFlag(rest, ["--lexicon"]);
     const graphFlags = repeatedFlag(rest, ["--graph"]);
 
-    // `--memory-backend <default|memory|sqlite>` (PLAN_SEED.md §6's storage-backend
-    // seam, now reachable from `tmct init`): validated BEFORE touching disk, same
+    // `--memory-backend <default|memory|sqlite>`: validated BEFORE touching disk, same
     // discipline as every other pluggable input below. Written into tmct.toml's
     // `[memory] backend` (src/services/init.mjs's renderTomlConfig); chat.mjs's
     // createSession reads it back at CLI-flag > TMCT_MEMORY_BACKEND env >
@@ -798,7 +797,7 @@ async function main() {
       personaPreset = PERSONA_PRESETS[personaName];
     }
 
-    // `--persona-size <medium|large>` (PLAN_SEED.md §3): Small/Medium/Large are
+    // `--persona-size <medium|large>`: Small/Medium/Large are
     // SIZES of the one `human` bundle, not separate corpus ids — human.jsonl
     // (Small, the default) stays exactly as-is; human-medium.jsonl/
     // human-large.jsonl hold ONLY the facts each size adds beyond the previous
@@ -1121,7 +1120,7 @@ async function main() {
   if (mode === "viz") {
     // `tmct viz` — the ledger explorer: one self-contained HTML page rendering
     // the memory graph as readable fact-sentences around a focus term, with
-    // the in-browser chat dock (PLAN_VIZ_LEDGER.md). Same repo resolution as
+    // the in-browser chat dock. Same repo resolution as
     // `memory`/`syllogise` — resolveRuntimeConfig: --repo > git root > cwd.
     // `--ledger` is accepted as a no-op: the ledger IS the viz surface now.
     const rest = process.argv.slice(3);

package/corpus/wordnet/generate.mjs

@@ -30,12 +30,11 @@
 //      emitting one row per edge (see RELATION_MAP / synonymPairs below).
 //
 // The hand-rolled `parseYaml` this file reuses (imported, not duplicated) is
-// scripts/extract-persona-sources.mjs's own tiny YAML-subset reader — already
-// proven against this exact OEWN dump shape by scripts/build-persona-tiers.mjs
-// and scripts/build-persona-examples.mjs. Reusing it (rather than adding a
-// general YAML dependency, or re-deriving a second hand-rolled parser) keeps
-// this converter self-consistent with the rest of the persona-tier tooling
-// that already reads this same source.
+// src/domain/wordnet/yaml.mjs's tiny YAML-subset reader — already proven
+// against this exact OEWN dump shape by the persona-tier tooling. Reusing it
+// (rather than adding a general YAML dependency, or re-deriving a second
+// hand-rolled parser) keeps this converter self-consistent with the rest of
+// the tooling that already reads this same source.
 //
 // Licence: Open English WordNet content is CC-BY-4.0 (Princeton WordNet +
 // Open English Wordnet team) — see LICENSE-NOTICE in this directory. The
@@ -47,7 +46,7 @@ import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { parseYaml } from "../../scripts/extract-persona-sources.mjs";
+import { parseYaml } from "../../src/domain/wordnet/yaml.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const WORDNET_OUT_DIR = HERE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -72,8 +72,19 @@
     "test": "node --test \"test/**/*.test.mjs\"",
     "test:e2e": "node --test \"e2e/**/*.test.mjs\"",
     "e2e:browsers": "playwright install chromium",
+    "check:links": "node scripts/check-links.mjs",
+    "check:pii": "node scripts/pii-lint.mjs",
+    "check:pack": "node scripts/check-pack-manifest.mjs",
+    "check:licences": "node scripts/check-licences.mjs",
+    "check:publint": "npx --no-install publint",
+    "check:tool-docs": "node scripts/generate-tool-docs.mjs --check",
+    "check:publish": "node scripts/check-publish.mjs",
+    "check:all": "npm run check:links && npm run check:pii && npm run check:licences && npm run check:publint && npm run check:tool-docs",
+    "smoke:deploy": "node scripts/post-deploy-smoke.mjs",
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
+    "chat:plain": "node bin/tmct.mjs chat --plain",
+    "chat:narrate": "node bin/tmct.mjs chat --narrate",
     "init": "node bin/tmct.mjs init",
     "init:sqlite": "node --disable-warning=ExperimentalWarning bin/tmct.mjs init --memory-backend sqlite",
     "init:persona:human": "node bin/tmct.mjs init --with-persona human",
@@ -82,19 +93,36 @@
     "init:xl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-xl",
     "init:xxl": "node bin/tmct.mjs init --persona-size large && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java && node bin/tmct.mjs import --corpus wordnet-full && node bin/tmct.mjs import --corpus namenet",
     "memory": "node bin/tmct.mjs memory",
+    "memory:verbose": "node bin/tmct.mjs memory --verbose",
     "syllogise": "node bin/tmct.mjs syllogise",
     "viz": "node bin/tmct.mjs viz",
+    "viz:term": "node bin/tmct.mjs viz --term",
+    "plan": "node bin/tmct.mjs plan",
+    "plan:json": "node bin/tmct.mjs plan --json",
+    "cli": "node bin/tmct.mjs cli",
+    "cli:digest": "node bin/tmct.mjs cli digest",
+    "import": "node bin/tmct.mjs import",
+    "extend": "node bin/tmct.mjs extend --validate",
+    "serve": "node bin/tmct.mjs serve",
+    "serve:public": "node bin/tmct.mjs serve --host 0.0.0.0 --port 8787",
     "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
     "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
     "chatbench:run": "node chatbench/run.mjs",
     "chatbench:judge": "node chatbench/judge.mjs",
-    "serve": "node bin/tmct.mjs serve",
     "agentbench:run": "node agentbench/run.mjs",
     "infbench": "node infbench/generate-cases.mjs && node infbench/run.mjs",
+    "corpus:matrix": "node scripts/corpus-matrix.mjs",
+    "corpus:matrix:gaps": "node scripts/corpus-matrix.mjs --gaps",
+    "template:coverage": "node scripts/template-coverage.mjs",
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
     "demo:build": "node scripts/build-demo-site.mjs",
     "build:ask-bundle": "node scripts/build-ask-bundle.mjs",
+    "build:demo-graph": "node scripts/build-demo-graph.mjs",
+    "build:demo-memory": "node scripts/build-demo-memory.mjs",
+    "gen:tool-docs": "node scripts/generate-tool-docs.mjs",
+    "gen:collisions": "node scripts/generate-real-word-collisions.mjs",
+    "gen:variants": "node scripts/generate-template-variants.mjs",
     "extract:facts": "node scripts/extract-facts-from-text.mjs"
   },
   "devDependencies": {

package/src/adapters/corpus/conceptnet.mjs

@@ -35,7 +35,7 @@ export const TIER2_MANIFEST_FILE = join(TIER2_DIR, "manifest.json");
 // conversion, same slice shape/loader path as tier-1/tier-2. "wordnet-xl"/"wordnet-full"
 // are wired as BUILTIN_EXTENSIONS corpus entries in src/extensions.mjs.
 export const WORDNET_DIR = join(PKG_ROOT, "corpus", "wordnet");
-export const WORDNET_MANIFEST_FILE = join(WORDNET_DIR, "manifest.json");
+const WORDNET_MANIFEST_FILE = join(WORDNET_DIR, "manifest.json");
 
 const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
 

package/src/adapters/graph-build.mjs

@@ -352,7 +352,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   const countClass = (c) => fnIndividuals.filter((i) => i.class === c).length;
   const sampleClass = (c) => fnIndividuals.filter((i) => i.class === c).slice(0, 3).map((i) => i.label);
 
-  // Second pass (PLAN_PROSE_INDEX.md) — see the returned `proseIndex` field's comment below.
+  // Second pass — see the returned `proseIndex` field's comment below.
   const allIndividuals = attachProseTokens(
     [...moduleIndividuals, ...fnIndividuals, ...commitIndividuals], { enabled: prose },
   );
@@ -361,7 +361,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   return {
     generated_at: generatedAt,
     // SEON (se-on.org, FAMIX-derived) vocabulary + our `mgx:` extension, documented
-    // for readers; the graph is JSON-label-only (no RDF store — see PLAN_SEON_RDF.md).
+    // for readers; the graph is JSON-label-only (no RDF store).
     prefixes: {
       seon: "http://se-on.org/ontologies/seon.owl#",
       mgx: "urn:tmct:mgx#",
@@ -419,7 +419,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       rel("reexports", "mgx:reExports", reExportEdges),
     ],
     individuals: allIndividuals,
-    // Second pass (PLAN_PROSE_INDEX.md): word -> [individual ids], inverted from the
+    // Second pass: word -> [individual ids], inverted from the
     // `prose_tokens` attribute attachProseTokens just attached. Disable via
     // TMCT_PROSE_INDEX=0 (indexRepository, below) — {} when off. The typed graph above
     // (individuals' core fields, all edges) is byte-identical either way.

package/src/adapters/memory/blocks.mjs

@@ -18,8 +18,8 @@ const trustFactorOf = (trust) => 0.5 + (typeof trust === "number" ? trust : SOUR
 export const BLOCKS_DIR_REL = join(".tmct", "memory", "blocks");
 const INDEX_NAME = "index.json";
 
-export const PAGERANK_DAMPING = 0.85;
-export const PAGERANK_ITERATIONS = 20;
+const PAGERANK_DAMPING = 0.85;
+const PAGERANK_ITERATIONS = 20;
 export const OVERLAP_MIN = 2;   // shared tokens for a similarity edge
 const MAX_TOKENS_PER_BLOCK = 800; // beyond tokenizeProse's per-doc cap: union over lines
 

package/src/adapters/memory/core.mjs

@@ -43,7 +43,7 @@ export const IN_REPLY_TO_PROP = "mgx:inReplyTo";
 // The provenance-link predicate family: one umbrella object property with two
 // workhorse subproperties, minted in the owned mgx: namespace to match
 // tmct-core.ttl's object-property style.
-export const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: Fact → Source|Fact
+const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: Fact → Source|Fact
 export const STATED_BY_PROP = "mgx:statedBy";              // a Source directly asserts a Fact
 export const CANONICALISED_FROM_PROP = "mgx:canonicalisedFrom"; // a canonical Fact ← its raw form
 export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (session-scoped) trust nudge on a Source, [0.5,1.5]
@@ -52,7 +52,7 @@ export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (
 // with no session-id segment. A tag that does carry one mints its own
 // per-session Source instead (`${ID}:<sessionId>`, sourceIdFor below).
 export const OPERATOR_SOURCE_ID = "src:operator-chat";
-export const TEACH_SOURCE_ID = "src:teach-chat";
+const TEACH_SOURCE_ID = "src:teach-chat";
 
 const ROLES = new Set(["visitor", "tmct"]);
 const LABEL_CAP = 48;    // utterance/fact labels stay skimmable in renders
@@ -1113,13 +1113,13 @@ export const RULE_KIND_ACTION_SIGNATURE = "action-signature";
 export const RULE_KIND_ACTION_PRECOND = "action-precond";
 export const RULE_KIND_ACTION_EFFECT = "action-effect";
 export const RULE_KIND_ACTION_CONSTRAINT = "action-constraint";
-export const RULE_KINDS = Object.freeze([
+const RULE_KINDS = Object.freeze([
   RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE,
   RULE_KIND_ACTION_SIGNATURE, RULE_KIND_ACTION_PRECOND, RULE_KIND_ACTION_EFFECT,
   RULE_KIND_ACTION_CONSTRAINT,
 ]);
 
-export const RULE_NAME_PROP = "mgx:ruleName";
+const RULE_NAME_PROP = "mgx:ruleName";
 export const RULE_KIND_PROP = "mgx:ruleKind";
 
 // Per-kind slot contract: JS slot key -> the mgx: attribute it's written under.
@@ -1514,7 +1514,7 @@ export async function removeFacts(dir, ids) {
 
 /** The trust floor a fact must clear before a differing object counts as a real
  *  contradiction (below it the fact is too weak to contradict anything). */
-export const CONTRADICTION_TRUST_FLOOR = 0.5;
+const CONTRADICTION_TRUST_FLOOR = 0.5;
 
 export const HAS_A_PREDICATE = "mgx:hasA";
 export const CAPABLE_OF_PREDICATE = "mgx:capableOf";

package/src/adapters/providers/bootstrap.mjs

@@ -13,7 +13,7 @@ import { emptyEntities } from "../source.mjs";
 import { createGraphService } from "./graph-service.mjs";
 
 /** The parsed empty bootstrap graph. */
-export function bootstrapGraph() {
+function bootstrapGraph() {
   return parseEntities(emptyEntities());
 }
 

package/src/adapters/providers/fixture.mjs

@@ -15,7 +15,7 @@ import { createGraphService } from "./graph-service.mjs";
 /** A compact but type-complete entities payload: modules, a class hierarchy
  *  (Base ← Widget ← Button), a method with a full signature, an attribute, a
  *  module global, and a commit — wired by one edge of every closed kind. */
-export const FIXTURE_ENTITIES = Object.freeze({
+const FIXTURE_ENTITIES = Object.freeze({
   generated_at: "2026-07-05T00:00:00.000Z",
   bootstrap: false,
   prefixes: { seon: "http://se-on.org/ontologies/seon.owl#", mgx: "urn:tmct:mgx#" },

package/src/adapters/wink-model.mjs

@@ -26,7 +26,7 @@ export function registerWinkModel(factory) {
 
 /** Load `{ winkNLP, model }` once, or null when wink isn't available. Prefers a
  *  registered browser factory; otherwise falls back to Node module resolution. */
-export function loadWinkModel() {
+function loadWinkModel() {
   if (cached !== undefined) return cached;
   try {
     const pair = injected ? injected() : nodeRequireWink();

package/src/adapters/wordnet-source.mjs

@@ -0,0 +1,70 @@
+// wordnet-source.mjs — reads a LOCAL Open English WordNet clone off disk and
+// indexes it. The clone is never vendored, never committed, never part of the
+// npm package: point TMCT_WORDNET_SRC at it, or keep it at the default path.
+//
+// This is the disk half of the WordNet reader. The parsing half is pure and
+// lives in src/domain/wordnet/yaml.mjs, so it is testable with no clone
+// present; everything here needs the real files.
+
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseYaml } from "../domain/wordnet/yaml.mjs";
+
+export const WORDNET_SRC = process.env.TMCT_WORDNET_SRC || join(homedir(), "projects", "globalwordnet", "english-wordnet");
+export const WORDNET_YAML_DIR = join(WORDNET_SRC, "src", "yaml");
+
+/** True iff a WordNet clone is readable at `yamlDir`. Callers use this to fail
+ *  with a one-line message rather than a stack trace: these are maintainer
+ *  tools, never a build dependency. */
+export function hasWordnetSource(yamlDir = WORDNET_YAML_DIR) {
+  return existsSync(yamlDir);
+}
+
+/** Load one or more noun.<x>/verb.<x>.yaml files into a flat synset-id -> record map. */
+export async function loadSynsets(files, yamlDir = WORDNET_YAML_DIR) {
+  const map = new Map();
+  for (const f of files) {
+    const path = join(yamlDir, f);
+    if (!existsSync(path)) continue;
+    const parsed = parseYaml(await readFile(path, "utf8"));
+    for (const [id, rec] of Object.entries(parsed)) map.set(id, rec);
+  }
+  return map;
+}
+
+/** Load the entries-<letter>.yaml files that could contain any of `words`
+ *  (only the letters actually needed — 28 files, ~1MB-3MB each, no reason to
+ *  load all 28 when a clump only needs a handful of letters). Returns
+ *  word -> { n: [{id, synset}], v: [...], a: [...] }. */
+export async function loadEntriesFor(words, yamlDir = WORDNET_YAML_DIR) {
+  const letters = new Set();
+  for (const w of words) {
+    const c = w[0].toLowerCase();
+    letters.add(/[a-z]/.test(c) ? c : "0");
+  }
+  const index = new Map();
+  for (const letter of letters) {
+    const path = join(yamlDir, `entries-${letter}.yaml`);
+    if (!existsSync(path)) continue;
+    const parsed = parseYaml(await readFile(path, "utf8"));
+    for (const [word, byPos] of Object.entries(parsed)) {
+      if (!words.has(word)) continue;
+      const senses = {};
+      for (const [pos, rec] of Object.entries(byPos || {})) {
+        if (pos === "form") continue;
+        const list = Array.isArray(rec?.sense) ? rec.sense : [];
+        senses[pos] = list.map((s) => ({ id: s.id, synset: s.synset })).filter((s) => s.synset);
+      }
+      index.set(word, senses);
+    }
+  }
+  return index;
+}
+
+/** Every noun.*.yaml synset in the clone. */
+export async function loadAllNounSynsets(yamlDir = WORDNET_YAML_DIR) {
+  const files = (await readdir(yamlDir)).filter((f) => f.startsWith("noun."));
+  return loadSynsets(files, yamlDir);
+}

package/src/domain/answer-variants.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "curation": "Hand-curated. scripts/generate-answer-variants.mjs cross-checked each pool against real Open English WordNet synsets (scripts/lib/wordnet-synonyms.mjs) where a sense fit; most of these are domain-specific code-graph connector phrases WordNet's own sense-1 convention resolves to the wrong sense for -- e.g. 'locate' -> 'turn up', 'record' -> 'enter, put down', 'module' -> 'mental faculty' -- so every entry below was accepted or rejected by hand against the exact rendered sentence it replaces, never auto-accepted from a raw synset match. See src/domain/answer-variants.mjs for how these are selected at render time.",
+  "curation": "Hand-curated, and it has to stay that way: each pool was cross-checked against real Open English WordNet synsets where a sense fit, but most of these are domain-specific code-graph connector phrases whose sense-1 convention resolves to the wrong sense -- e.g. 'locate' -> 'turn up', 'record' -> 'enter, put down', 'module' -> 'mental faculty'. So every entry below was accepted or rejected by hand against the exact rendered sentence it replaces, never auto-accepted from a raw synset match. That is why no generator reproduces this file and no drift guard can check it. See src/domain/answer-variants.mjs for how these are selected at render time.",
   "pools": {
     "defined-in": {
       "base": "defined in",

package/src/domain/ask-vocab.mjs

@@ -211,7 +211,7 @@ export function stripTrailingScopeFiller(text) {
 
 /** Trailing bare discourse tags ("how many of those then"). "too" can stack
  *  ("is UserController a validator too then"), hence the double pass below. */
-export const TRAILING_DISCOURSE_TAG = Object.freeze(["then", "though", "too"]);
+const TRAILING_DISCOURSE_TAG = Object.freeze(["then", "though", "too"]);
 
 const TRAILING_DISCOURSE_TAG_RE = new RegExp(
   `\\s+(?:${TRAILING_DISCOURSE_TAG.join("|")})\\s*[?.!]*$`, "i",
@@ -219,7 +219,7 @@ const TRAILING_DISCOURSE_TAG_RE = new RegExp(
 
 /** Trailing comma-delimited discourse clauses ("what is a class, please
  *  explain"), anchored on a literal comma so this never fires mid-phrase. */
-export const TRAILING_DISCOURSE_CLAUSE = Object.freeze(["please explain", "explain"]);
+const TRAILING_DISCOURSE_CLAUSE = Object.freeze(["please explain", "explain"]);
 
 const TRAILING_DISCOURSE_CLAUSE_RE = new RegExp(
   `,\\s*(?:${TRAILING_DISCOURSE_CLAUSE.join("|")})\\s*[?.!]*$`, "i",

package/src/domain/ask.mjs

@@ -1786,7 +1786,7 @@ function evalQualCheck(graph, ast, opts) {
 
 /** Compile any compositional AST to a result object traverse() returns for the
  *  simple path — {matches, …} plus compositeKind/compositeMiss flags render() reads. */
-export function evalComposite(graph, ast, opts = {}) {
+function evalComposite(graph, ast, opts = {}) {
   if (ast.node === "miss") return { compositeMiss: true, reason: ast.reason || null, matches: [] };
   if (ast.node === "exists") return evalExists(graph, ast);
   if (ast.node === "qualCheck") return evalQualCheck(graph, ast, opts);
@@ -1828,7 +1828,7 @@ const compositeList = (matches) => listJoin(matches.slice(0, OVERFLOW_CAP)
   + (matches.length > OVERFLOW_CAP ? `, …and ${matches.length - OVERFLOW_CAP} more` : "");
 
 /** A compositional worked example for the rephrase hint. */
-export function compositionalHint() {
+function compositionalHint() {
   return 'compositional queries also work: "which functions call X and call Y", "what calls something that imports X", "public methods of X", "list functions" / "show me the classes", "how many classes", "which module has the most imports", "find me the payment class", or (after a listing) "which of those are tested"';
 }
 
@@ -2047,7 +2047,7 @@ export function rephraseHint() {
  *  It gets a line that says what the store actually holds instead. A NULL
  *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
  *  index-shaped advice. */
-export function touchesRephraseHint(graph = null) {
+function touchesRephraseHint(graph = null) {
   if (graph && moduleCountOf(graph) === 0) {
     return "This store holds no code index, so it records no modules or commits to look through.";
   }
@@ -3516,7 +3516,7 @@ function isHelpRequest(query) {
  *                        they are content that may honestly fail to resolve.
  *    3. SYNONYM        — rewrite surviving near-canonical words to the closed vocab.
  *  Bounded (one token removed per noise iteration; hard guard) and deterministic. */
-export function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = null } = {}) {
+function relaxParse(graph, query, { nlp = undefined, contextId = null, prev = null } = {}) {
   const from = applyNegationFrames(normalizeQuery(String(query || "")));
   let tokens = splitWords(from);
   if (!tokens.length) return null;

package/src/domain/codegraph.mjs

@@ -128,11 +128,11 @@ function basename(p) {
 
 const isProvRef = (r) => /^(git|turn):/.test(String(r || ""));
 
-export function turnRefCount(ind) {
+function turnRefCount(ind) {
   return (ind?.derived_from || []).filter(isProvRef).length;
 }
 
-export function mentionTotal(ind) {
+function mentionTotal(ind) {
   const fromMentions = (ind?.mentions || []).reduce((n, m) => n + (Number(m?.count) || 0), 0);
   return fromMentions + turnRefCount(ind);
 }
@@ -1402,7 +1402,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 
 /** Map of lowercased author name → that author's Commit individuals (payload order).
  *  Tolerates both attribute-key conventions (author / commitAuthor), like commitLine. */
-export function authorIndex(graph) {
+function authorIndex(graph) {
   const idx = new Map();
   for (const ind of graph?.individuals || []) {
     if ((ind.class || "") !== "Commit") continue;

package/src/domain/corpus-matrix.mjs

@@ -0,0 +1,87 @@
+// corpus-matrix.mjs — the fold and the two gap heuristics behind the
+// capability-by-lane coverage matrix, plus the table renderer. Pure: rows in,
+// counts and text out, so the heuristics can be tested against a handful of
+// made-up rows instead of whatever test/corpus happens to hold today.
+//
+// scripts/corpus-matrix.mjs keeps the readdir, the readFile and the printing.
+
+/** A row's capability group: the first two dot-segments of its key, so
+ *  "ask.alias.two-hop" and "ask.alias.miss" are one capability. */
+export const groupOfKey = (key) => key.split(".").slice(0, 2).join(".");
+
+/** The key a row is counted under. A row with no key is still a row, and
+ *  hiding it would understate the lane. */
+export const keyOfRow = (row) => String(row.key ?? "(no key)");
+
+/** A key segment naming a miss, a guard or a negation — the row that pins what
+ *  a capability DECLINES to do, as opposed to its happy path. */
+const NEGATIVE_RE = /(honest-miss|miss|guard|negation|negative|never|decline|refus|unsolvable|unknown|hedge|no-antecedent|untouched|empty)/;
+
+export const isNegativeKey = (key) => NEGATIVE_RE.test(key);
+
+/** Fold `{ lane, row }` pairs into the two indexes every view needs: the count
+ *  per group per lane, and the full keys each group was built from. */
+export function tallyRows(entries) {
+  const counts = new Map(); // group -> Map<lane, rowCount>
+  const fullKeys = new Map(); // group -> Set<full key>
+  for (const { lane, row } of entries) {
+    const key = keyOfRow(row);
+    const group = groupOfKey(key);
+    if (!counts.has(group)) counts.set(group, new Map());
+    const perLane = counts.get(group);
+    perLane.set(lane, (perLane.get(lane) ?? 0) + 1);
+    if (!fullKeys.has(group)) fullKeys.set(group, new Set());
+    fullKeys.get(group).add(key);
+  }
+  return { counts, fullKeys };
+}
+
+/** The groups the gap heuristics judge. bench.* rows assert a rig runs rather
+ *  than pinning a capability, so "no negative row" says nothing there. */
+export const behaviourGroups = ({ counts }) =>
+  [...counts.keys()].filter((g) => !g.startsWith("bench.")).sort();
+
+const rowTotal = (counts, group) => [...counts.get(group).values()].reduce((a, b) => a + b, 0);
+
+/** Groups a single row pins end to end. A review candidate, not a hole. */
+export function thinGroups(tally) {
+  return behaviourGroups(tally).filter((g) => rowTotal(tally.counts, g) === 1);
+}
+
+/** Groups whose keys never name a miss, guard or negation — a happy path is
+ *  pinned and the decline is not. A review candidate, not a hole. */
+export function groupsWithNoNegativeRow(tally) {
+  return behaviourGroups(tally).filter((g) => ![...tally.fullKeys.get(g)].some(isNegativeKey));
+}
+
+/** The lanes a group has rows in, in the order given. */
+export const lanesOfGroup = ({ counts }, group) => [...counts.get(group).keys()];
+
+/** One row per group, one column per lane, an empty cell where a lane has no
+ *  row for that group. The header row comes first. */
+export function matrixRows({ counts }, lanes) {
+  const groups = [...counts.keys()].sort();
+  return [
+    ["key", ...lanes],
+    ...groups.map((group) => [
+      group,
+      ...lanes.map((lane) => {
+        const n = counts.get(group).get(lane);
+        return n ? String(n) : "";
+      }),
+    ]),
+  ];
+}
+
+/** `rows` (header first) as fixed-width text, with a rule under the header.
+ *  Each column is as wide as its widest cell; trailing padding is trimmed. */
+export function renderTable(rows) {
+  const [header, ...body] = rows;
+  const widths = header.map((h, col) => Math.max(h.length, ...body.map((r) => r[col].length)));
+  const renderLine = (cells) => cells.map((c, col) => c.padEnd(widths[col])).join("  ").trimEnd();
+  return [
+    renderLine(header),
+    renderLine(widths.map((w) => "-".repeat(w))),
+    ...body.map(renderLine),
+  ].join("\n");
+}

package/src/domain/grammar/ace.mjs

@@ -8,7 +8,7 @@
 // punctuation, morphology is the lexicon's suffix fold.
 //
 // parseAce(sentence, lexicon) → { pattern, triples, residue } | null
-//   pattern  one of the PATTERNS below (also exported individually).
+//   pattern  one of the PATTERNS below.
 //   triples  [{ subject, predicate, object, kind, n? }] — OWL-labelled string
 //            triples shaped for src/adapters/memory/core.mjs's appendFact (which
 //            normalizes subject/object via normFactTerm: "tmct:module" is
@@ -36,18 +36,18 @@ import {
 // singularOnly below, and lexicon.mjs's lookupNoun doc for what this prunes).
 const SINGULAR_ONLY_DET = new Set(["a", "an"]);
 
-export const PATTERN_SUB_CLASS_OF = "subClassOf";
-export const PATTERN_TYPE_ASSERTION = "typeAssertion";
-export const PATTERN_RELATION = "relation";
-export const PATTERN_SOME_VALUES_FROM = "someValuesFrom";
-export const PATTERN_CARDINALITY = "cardinality";
-export const PATTERN_DISJOINT_WITH = "disjointWith";
-export const PATTERN_POSSESSIVE = "possessive";
-export const PATTERN_ADJECTIVE = "adjective";
-export const PATTERN_CAPABILITY = "capability";
+const PATTERN_SUB_CLASS_OF = "subClassOf";
+const PATTERN_TYPE_ASSERTION = "typeAssertion";
+const PATTERN_RELATION = "relation";
+const PATTERN_SOME_VALUES_FROM = "someValuesFrom";
+const PATTERN_CARDINALITY = "cardinality";
+const PATTERN_DISJOINT_WITH = "disjointWith";
+const PATTERN_POSSESSIVE = "possessive";
+const PATTERN_ADJECTIVE = "adjective";
+const PATTERN_CAPABILITY = "capability";
 
 /** The pattern field's full domain, in the README's table order. */
-export const PATTERNS = Object.freeze([
+const PATTERNS = Object.freeze([
   PATTERN_SUB_CLASS_OF, PATTERN_TYPE_ASSERTION, PATTERN_RELATION, PATTERN_SOME_VALUES_FROM,
   PATTERN_CARDINALITY, PATTERN_DISJOINT_WITH, PATTERN_POSSESSIVE, PATTERN_ADJECTIVE,
   PATTERN_CAPABILITY,

package/src/domain/grammar/lexicon.mjs

@@ -25,7 +25,7 @@
 import coreLexiconRaw from "./lexicon-core.json" with { type: "json" };
 
 /** The CURIE namespace every tmct lexicon mints terms under. */
-export const DEFAULT_NS = "tmct:";
+const DEFAULT_NS = "tmct:";
 
 /** Determiner tokens the grammar consumes (pattern table's every/a/no…). */
 export const DETERMINERS = Object.freeze({
@@ -160,7 +160,7 @@ export function lookupNoun(lexicon, word, opts = {}) {
 /** Every lexicon entry `word` could plausibly resolve to, ranked the same as
  *  lookupNoun's top choice but without discarding a genuine alternate (e.g.
  *  die/dice returns both entries). */
-export function lookupNounCandidates(lexicon, word, opts = {}) {
+function lookupNounCandidates(lexicon, word, opts = {}) {
   const w = String(word ?? "").toLowerCase();
   const standalone = lexicon.nouns.get(w);
   const irregular = lexicon.nounPlurals.get(w);
@@ -195,7 +195,7 @@ export function lookupVerb(lexicon, word) {
 
 /** Every verb entry `word` could plausibly resolve to via foldCandidates,
  *  most-specific-fold-first — the verb sibling of lookupNounCandidates. */
-export function lookupVerbCandidates(lexicon, word) {
+function lookupVerbCandidates(lexicon, word) {
   const w = String(word ?? "").toLowerCase();
   const out = [];
   const seen = new Set();

package/src/domain/inflect.mjs

@@ -0,0 +1,67 @@
+// inflect.mjs — the regular English -s/-ed/-ing rules, applied to a lemma.
+//
+// WordNet carries lemmas only ("rest" is present, "rests" is absent), and it is
+// the inflected forms that collide with the fuzzy repair tier's targets —
+// "rests" is one edit from "tests". So the real-word collision table expands
+// every lemma through these rules before it looks for collisions.
+//
+// These are the REGULAR rules and nothing else. No irregular table, no stress
+// model: pastOf("run") is "runned" and pastOf("make") is "maked". That is the
+// intended shape. The table's job is to name words the repair tier must not
+// rewrite, and inflectionsOf is generous on purpose (see below) — an extra form
+// costs one repair we decline to make, and the sentence misses honestly, while
+// a missing form costs a real word rewritten into a different question,
+// answered with confidence. The first is the cheaper mistake.
+
+import { STOPWORDS } from "./interpret/normalize.mjs";
+import {
+  FUZZY_TARGET_WORDS, FUZZY_REPAIR_MIN_LENGTH, fuzzyMatchInSet, fuzzyBound,
+} from "./interpret/fuzzy.mjs";
+
+const VOWELS = new Set(["a", "e", "i", "o", "u"]);
+const isVowel = (c) => VOWELS.has(c);
+
+/** A single final consonant after a single vowel doubles before -ed/-ing
+ *  ("run" -> "running"). w, x and y never double. Stress is not modelled, so a
+ *  second syllable doubles too ("visit" -> "visitting"). */
+export function doublesFinalConsonant(w) {
+  const [c3, c2, c1] = [w.at(-3), w.at(-2), w.at(-1)];
+  if (!c3 || isVowel(c1) || "wxy".includes(c1)) return false;
+  return isVowel(c2) && !isVowel(c3);
+}
+
+export function pluralOf(w) {
+  if (/(?:s|x|z|ch|sh)$/.test(w)) return `${w}es`;
+  if (/[^aeiou]y$/.test(w)) return `${w.slice(0, -1)}ies`;
+  return `${w}s`;
+}
+
+export function pastOf(w) {
+  if (w.endsWith("e")) return `${w}d`;
+  if (/[^aeiou]y$/.test(w)) return `${w.slice(0, -1)}ied`;
+  if (doublesFinalConsonant(w)) return `${w}${w.at(-1)}ed`;
+  return `${w}ed`;
+}
+
+export function gerundOf(w) {
+  if (w.endsWith("ie")) return `${w.slice(0, -2)}ying`;
+  if (w.endsWith("e") && !/(?:ee|oe|ye)$/.test(w)) return `${w.slice(0, -1)}ing`;
+  if (doublesFinalConsonant(w)) return `${w}${w.at(-1)}ing`;
+  return `${w}ing`;
+}
+
+/** Every surface form of `w` the collision table counts as real English. */
+export const inflectionsOf = (w) => [w, pluralOf(w), pastOf(w), gerundOf(w)];
+
+/** The words in `realWords` that the repair tier would rewrite onto one of its
+ *  targets: long enough to reach the tier, not a stopword, not a target itself,
+ *  and within the fuzzy bound of some target. Sorted, so the table it feeds is
+ *  reproducible. */
+export function collisionsFrom(realWords) {
+  return [...realWords]
+    .filter((w) => w.length >= FUZZY_REPAIR_MIN_LENGTH)
+    .filter((w) => !STOPWORDS.has(w))
+    .filter((w) => !FUZZY_TARGET_WORDS.includes(w))
+    .filter((w) => fuzzyMatchInSet(w, FUZZY_TARGET_WORDS, fuzzyBound(w)) !== null)
+    .sort();
+}