@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.4.0

package/bin/tmct.mjs

@@ -5,15 +5,26 @@
 // with software). No model calls; tmct keeps no codebase index of its own.
 //
 //   tmct                                   → interactive chat (the headline)
-//   tmct chat [--repo <abs>]               → same, explicit
+//   tmct chat [--repo <abs>] [--plain]     → same, explicit
 //   tmct cli <tool> '{…json}'              → invoke a graph tool directly (de-emphasized carry-over)
+//   tmct cli digest '{…json}'              → architecture map + per-module context bundles
 //   tmct --help                            → this help
 //
+// On a real terminal, chat is the full-screen Ink TUI (src/tui/app.mjs);
+// `--plain` — or a non-TTY stdin/stdout (pipes, scripts, the test suite) —
+// gets the classic readline shell. BOTH run the same session sink
+// (src/chat.mjs createSession), so logs, sidecars and graph memory are
+// identical either way.
+//
+// The `cli` arms (digest / tmct_locate / any-tool fallback) are the carried,
+// de-emphasized non-chat modes, folded in here from the former bin/cli.mjs.
+// The graph artifact lives at <repo_path>/.tmct/graph.json; the tools (run
+// with cwd = that repo) load it by default. No flags, no config files.
+//
 // tmct began as a whole-package lift of an earlier chat surface (see README
 // provenance): internal module filenames and symbols were kept to preserve the
-// shape and the green test suite. The non-chat modes are carried but
-// de-emphasized — see README.md for what tmct is and deliberately is NOT, and
-// ROADMAP.md for where it is going.
+// shape and the green test suite. See README.md for what tmct is and
+// deliberately is NOT, and ROADMAP.md for where it is going.
 
 const HELP = `tmct — The Mechanical Code Talker
 
@@ -23,25 +34,310 @@ software repository. No model calls; no codebase index of its own.
 Usage:
   tmct                         interactive chat (the headline surface)
   tmct chat [--repo <abs>]     chat over a specific repo's graph
+       [--plain]               force the plain readline shell (the default when
+                               stdin/stdout is not a terminal)
+  tmct memory [--repo <abs>]   what tmct remembers: facts, utterances, sessions,
+       [--verbose]             folded blocks (the /memory chat command, from the shell)
+  tmct init [--force]          initialize the current directory for tmct: .tmct/,
+                               tmct.toml, tier-1 corpus seed, provenance record
+  tmct syllogise [--repo <abs>] speculative inference (offline maintenance job): forward-
+       [--depth <n>] [--budget <n>]  chain the memory's rdfs:subClassOf closure, materialising
+                               bounded, low-trust, retractable entailed facts (never on the chat path)
   tmct cli <tool> '{…}'        invoke a graph tool directly (carry-over, de-emphasized)
+  tmct cli digest '{…}'        architecture map + per-module context bundles
   tmct --help                  show this help
 
+On a terminal, chat opens the full-screen TUI; piped input gets the plain shell.
 In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.log.
 `;
 
-const args = process.argv.slice(2);
+const argv = process.argv.slice(2);
 
-if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
   process.stdout.write(HELP);
   process.exit(0);
 }
 
-// Headline behaviour: a bare invocation is CHAT. We rewrite argv so the carried
-// dispatcher (bin/cli.mjs, kept verbatim for the test suite) sees `chat`, then
-// hand off to it. Any explicit mode passes straight through unchanged.
-if (args.length === 0) {
+// Headline behaviour: a bare invocation is CHAT. We rewrite argv so the mode
+// dispatch below (and anything downstream reading process.argv) sees `chat`.
+if (argv.length === 0) {
   process.argv.splice(2, 0, "chat");
 }
 
-// Delegate to the carried dispatcher. It runs its own main() on import.
-await import("./cli.mjs");
+/** Parse the trailing JSON payload of a `cli` sub-command (best-effort). */
+function parsePayload(payload) {
+  if (!payload) return {};
+  try { return JSON.parse(payload); }
+  catch { return null; }
+}
+
+const DIGEST_MODULE_CAP = 12;   // bound the digest — a handful of changed modules
+const DIGEST_SECONDARY_CAP = 2; // B2: at most this many SECONDARY modules get a (trimmed) bundle
+const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
+
+/** `cli digest` — print a machine-readable header + a repo architecture map + the
+ *  tmct_context edit bundle for each requested module to stdout (reuses the server's exact
+ *  renderer via buildContextBundle, so no render logic is duplicated). This stdout is injected
+ *   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
+ *  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.
+ *
+ *  B2: the FIRST (primary) module gets a full size-adaptive bundle; the remaining modules are
+ *  RANKED by import/cochange proximity to the primary and only the top few get a TRIMMED
+ *  (signatures + insertion region) bundle — so a 2-module task no longer pays for two full
+ *  bundles. The leading header line lets the rig record tier/topup telemetry. */
+async function runDigest(args, { dispatchTool, buildContextBundle, source, configFor, codegraph }) {
+  const { parseEntities, rankModulesByProximity, searchModulesRanked, selectRankedModules, DEFAULT_SCORE_GAP } = codegraph;
+  const repoPath = args.repo_path;
+  if (!repoPath) { process.stderr.write("tmct: digest requires repo_path\n"); process.exit(2); }
+  let modules = Array.isArray(args.modules) ? args.modules.slice(0, DIGEST_MODULE_CAP) : [];
+  let autoSelected = null; // for the header, when `query` drove selection
+  if (!modules.length && args.query) {
+    const graph = parseEntities(await source.fetchEntities(configFor(repoPath)));
+    // SHIPPED DEFAULT (0.5.0): the digest's query-mode auto-locate resolves literal-mention ON
+    // (a fresh invocation with no tmct.toml), disable-able via `literal_mention:false`. Kept in
+    // lockstep with the `tmct_locate` handler so `cli digest '{query}'` ≡ `cli tmct_locate` for the
+    // same query. A strict no-op unless the query carries a ≥3-component dotted path / repo-relative
+    // path; searchModulesRanked derives rawQuery from the query when literalMention is on.
+    const ranked = searchModulesRanked(graph, args.query, { literalMention: args.literal_mention !== false });
+    const scoreGapK = args.score_gap === false ? null : (Number.isFinite(args.score_gap) ? args.score_gap : DEFAULT_SCORE_GAP);
+    modules = selectRankedModules(ranked, { top_k: Number.isFinite(args.top_k) ? args.top_k : 2, scoreGapK }).slice(0, DIGEST_MODULE_CAP);
+    autoSelected = modules;
+    if (!modules.length) process.stderr.write(`tmct: digest query "${args.query}" matched no modules — empty digest\n`);
+  }
+  // Tuning-flag contract (threaded to buildContextBundle → sizeBundle): `min` → leanest TINY/no
+  // top-up; `untuned` → the earlier escalation. Neither → the tuned default. The digest header still
+  // reports the EFFECTIVE tier/topup returned per module, so rig telemetry stays correct.
+  const min = Boolean(args.min);
+  const untuned = Boolean(args.untuned);
+  // tmct-max: the injection CEILING — every requested module gets a FULL (untrimmed) bundle,
+  // not just the primary + 2 trimmed secondaries. Tests whether maximal injection re-bloats.
+  const max = Boolean(args.max);
+  const secondaryCap = max ? modules.length : DIGEST_SECONDARY_CAP;
+  const config = configFor(repoPath);
+  const body = [];
+  let effTier = "NONE"; // largest tier emitted across all modules
+  let topup = false;    // whether any module's auto-sizing escalated above TINY
+  let emitted = 0;      // module bundles actually emitted (primary + trimmed secondaries)
+
+  try {
+    body.push("# Repository architecture\n" + (await dispatchTool("tmct_architecture", {}, { config })));
+  } catch (e) {
+    body.push(`# Repository architecture\n(unavailable: ${e?.message || e})`);
+  }
+
+  const emit = async (m, trim) => {
+    try {
+      const { text, tier, topup: t } = await buildContextBundle({ symbol: m, min, untuned, max }, { config, source, trim });
+      body.push(`\n# Context bundle: ${m}${trim ? " (secondary, trimmed)" : ""}\n` + text);
+      if ((TIER_RANK[tier] || 0) > (TIER_RANK[effTier] || 0)) effTier = tier;
+      if (t) topup = true;
+      emitted += 1;
+    } catch (e) {
+      body.push(`\n# Context bundle: ${m}\n(no bundle: ${e?.message || e})`);
+    }
+  };
+
+  if (modules.length) {
+    const [primary, ...rest] = modules;
+    // rank the secondaries by proximity to the primary (best-effort: keep input order on error)
+    let ranked = rest;
+    if (rest.length) {
+      try { ranked = rankModulesByProximity(parseEntities(await source.fetchEntities(config)), primary, rest); }
+      catch { ranked = rest; }
+    }
+    const secondaries = ranked.slice(0, secondaryCap);
+    const overflow = ranked.slice(secondaryCap);
+    await emit(primary, false);
+    for (const m of secondaries) await emit(m, max ? false : true);
+    if (overflow.length) body.push(`\n# Related modules (not expanded; query tmct_context if needed): ${overflow.join(", ")}`);
+  }
+
+  // HARD CONTRACT: first line is the machine-readable digest header the rig greps. Fields are
+  // append-only — `selected=` is new (query mode only) and never changes the existing ones the
+  // rig's own parser depends on.
+  const header = `# tmct-digest tier=${effTier} topup=${topup} modules=${emitted}`
+    + (autoSelected ? ` selected=${autoSelected.join(",") || "(none)"}` : "");
+  process.stdout.write([header, ...body].join("\n") + "\n");
+}
+
+/** The carried `cli` dispatcher (digest / tmct_locate / any-tool fallback).
+ *  Imports are lazy so `tmct --help` and chat startup never pay for the tool
+ *  stack. */
+async function runCliMode() {
+  const [, sub, payload] = process.argv.slice(2);
+  const { join } = await import("node:path");
+  const { dispatchTool, buildContextBundle } = await import("../src/server.mjs");
+  const { loadConfig, DEFAULT_GRAPH_REL } = await import("../src/config.mjs");
+  const source = await import("../src/source.mjs");
+  const codegraph = await import("../src/codegraph.mjs");
+  const { parseEntities, searchModulesRanked } = codegraph;
+
+  /** Build a config pointed at a specific repo's artifact (for `cli` sub-commands that
+   *  take a repo_path), or fall back to the cwd-derived default. */
+  const configFor = (repoPath) =>
+    repoPath ? { graphFile: join(repoPath, DEFAULT_GRAPH_REL) } : loadConfig();
+
+  // digest mode: architecture map + per-module context bundles → stdout
+  if (sub === "digest") {
+    const args = parsePayload(payload);
+    if (args === null) {
+      process.stderr.write("tmct: digest expects a JSON arg, e.g. '{\"repo_path\":\"/abs\",\"modules\":[…]}'\n");
+      process.exit(2);
+    }
+    await runDigest(args, { dispatchTool, buildContextBundle, source, configFor, codegraph });
+    return;
+  }
+
+  // locate mode (TUNING #3): `cli tmct_locate '{"query":"…","repo_path":"<abs>"}'` emits the
+  // ranked modules as `<relpath>\t<score>`, one per line (highest first), using renderSearch's
+  // exact ranking. The rig keeps rank-1 always and rank-2 only when score2/score1 is close — it
+  // needs the raw scores, which the text renderer hides. Independent of the tuning flags.
+  if (sub === "tmct_locate") {
+    const args = parsePayload(payload);
+    if (args === null) {
+      process.stderr.write("tmct: tmct_locate expects a JSON arg, e.g. '{\"query\":\"…\",\"repo_path\":\"/abs\"}'\n");
+      process.exit(2);
+    }
+    const config = configFor(args.repo_path);
+    try {
+      const graph = parseEntities(await source.fetchEntities(config));
+      // B016 recall-lever flags (LOCATE-phase, per-arm; output byte-identical when absent).
+      const ranked = searchModulesRanked(graph, args.query || "", {
+        demoteNonProd: !!args.demote_nonprod, // R1a: demote examples//fixtures//test-* paths
+        callAdjacency: !!args.call_adjacency, // E1a: resolved-call adjacency bonus
+        implOfInterface: !!args.impl_of_interface, // E1b: C# impl-of-interface boost
+        beamSearch: !!args.beam_search, // §5.15: multi-ply discriminative expansion
+        ...(Number.isFinite(Number(args.beam_width)) ? { beamWidth: Number(args.beam_width) } : {}),
+        // B018 §8.1.3 literal-mention lever: match verbatim dotted-name/path mentions in the RAW
+        // query (which the locate tokenizer destroys). searchModulesRanked derives rawQuery from the
+        // query arg when literalMention is on; the rig passes the raw problem as the query, so literal
+        // matching keys off the untokenized text. raw_query is forwarded too for callers that normalize
+        // the query arg separately from the raw problem text.
+        // SHIPPED DEFAULT (0.5.0): literal-mention is ON for a fresh invocation (no arg, no
+        // tmct.toml) — pass `literal_mention:false` to disable. It is a strict no-op on queries
+        // with no ≥3-component dotted path / repo-relative path, so it never perturbs the cells the
+        // headline B018 numbers were measured on. The low-level scoreModules default (codegraph.mjs)
+        // stays literalMention=false; the product surface opts in explicitly, right here.
+        literalMention: args.literal_mention !== false,
+        ...(args.raw_query != null ? { rawQuery: String(args.raw_query) } : {}),
+      });
+      process.stdout.write(ranked.map((r) => `${r.path}\t${r.score}`).join("\n") + "\n");
+    } catch (e) {
+      process.stderr.write(`tmct: ${e?.message || e}\n`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // tool-query fallback: any other `cli <toolName> '{…}'` routes to dispatchTool,
+  // so "cold" tools are invokable from Bash directly.
+  if (sub) {
+    const args = parsePayload(payload);
+    if (args === null) {
+      process.stderr.write(`tmct: ${sub} expects a JSON arg, e.g. '{"symbol":"<name>"}'\n`);
+      process.exit(2);
+    }
+    const config = configFor(args.repo_path);
+    try {
+      const text = await dispatchTool(sub, args, { config });
+      process.stdout.write(text + "\n");
+    } catch (e) {
+      process.stderr.write(`tmct: ${e?.message || e}\n`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  process.stderr.write("tmct: `cli` needs a sub-command (digest | <toolName>)\n");
+  process.exit(2);
+}
+
+async function main() {
+  const mode = process.argv[2];
+
+  if (mode === "chat") {
+    const rest = process.argv.slice(3);
+    const i = rest.indexOf("--repo");
+    const repoPath = i !== -1 ? rest[i + 1] : undefined;
+    // The shell gate: a real terminal gets the full-screen Ink TUI; `--plain` or a
+    // non-TTY stream (pipes, scripts, the test suite) gets the readline shell. Both
+    // drive the same createSession sink — only the drawing differs.
+    const plain = rest.includes("--plain") || !process.stdin.isTTY || !process.stdout.isTTY;
+    if (plain) {
+      const { runChat } = await import("../src/chat.mjs");
+      await runChat({ repoPath });
+    } else {
+      const { runTui } = await import("../src/tui/app.mjs");
+      await runTui({ repoPath });
+    }
+    return;
+  }
+
+  if (mode === "memory") {
+    // `tmct memory` — the /memory chat command from the shell: same renderer
+    // (src/memory/inspect.mjs), same repo resolution as chat (git root default).
+    const rest = process.argv.slice(3);
+    const i = rest.indexOf("--repo");
+    const repoPath = i !== -1 ? rest[i + 1] : undefined;
+    const verbose = rest.includes("--verbose") || rest.includes("-v");
+    const { gitToplevel } = await import("../src/chat.mjs");
+    const { inspectMemory } = await import("../src/memory/inspect.mjs");
+    const repo = repoPath || gitToplevel(process.cwd()) || process.cwd();
+    process.stdout.write(await inspectMemory(repo, { verbose }) + "\n");
+    return;
+  }
+
+  if (mode === "init") {
+    // `tmct init` — the Repository-Interface onboarding surface: scaffold .tmct/,
+    // write tmct.toml, seed the tier-1 corpus (offline, opt-out via TMCT_NO_SEED),
+    // and record provenance. Idempotent; --force rewrites config + re-records.
+    const rest = process.argv.slice(3);
+    const { initRepo } = await import("../src/init.mjs");
+    const res = await initRepo(process.cwd(), { force: rest.includes("--force") });
+    process.stdout.write(res.message + "\n");
+    return;
+  }
+
+  if (mode === "syllogise") {
+    // `tmct syllogise` — the explicit speculative-inference batch (never on the chat
+    // hot path): forward-chain the memory's rdfs:subClassOf closure into bounded,
+    // low-trust, retractable entailed facts. Same repo resolution as `memory`.
+    const rest = process.argv.slice(3);
+    const i = rest.indexOf("--repo");
+    const repoPath = i !== -1 ? rest[i + 1] : undefined;
+    const numFlag = (name, dflt) => {
+      const j = rest.indexOf(name);
+      const v = j !== -1 ? Number(rest[j + 1]) : NaN;
+      return Number.isFinite(v) ? v : dflt;
+    };
+    const { gitToplevel } = await import("../src/chat.mjs");
+    const { syllogise } = await import("../src/syllogise.mjs");
+    const repo = repoPath || gitToplevel(process.cwd()) || process.cwd();
+    const res = await syllogise(repo, { depth: numFlag("--depth", 32), budget: numFlag("--budget", 50) });
+    process.stdout.write(
+      `tmct syllogise — derived ${res.count} entailed fact(s) (subClassOf closure, depth ${res.depth}, budget ${res.budget})`
+      + (res.truncated ? " — budget reached, more available" : "") + "\n",
+    );
+    return;
+  }
+
+  if (mode === "cli") {
+    await runCliMode();
+    return;
+  }
+
+  // An unknown mode gets the instructive usage line and exit 2. (A bare invocation
+  // never lands here — the argv splice above rewrote it to `chat`.)
+  process.stderr.write(`tmct: unknown invocation "${process.argv.slice(2).join(" ")}". ` +
+    "Use `cli digest …`, `cli <tool> …`, `memory`, or `chat`.\n");
+  process.exit(2);
+}
+
+main().catch((e) => {
+  process.stderr.write(`tmct: ${e?.message || e}\n`);
+  process.exit(1);
+});

package/corpus/README.md

@@ -0,0 +1,52 @@
+# corpus/ — committed corpus data
+
+The corpuses tmct ships so that an **empty** tmct still has a vocabulary
+(ROADMAP Phase 2). Everything here is plain, diffable data; the loaders live
+in `src/corpus/`. Related committed data lives in `data/` (response templates
++ the SE phrase book — items 4+7).
+
+## What's here
+
+| Path | What | Size | Licence |
+|---|---|---|---|
+| `conceptnet/slice.jsonl` | filtered English/tech-domain ConceptNet 5.7 slice (one assertion per line) | ~1.4 MB | **CC-BY-SA 4.0** (see `conceptnet/LICENSE-NOTICE`) |
+| `conceptnet/fetch-slice.mjs` | regeneration tool — the ConceptNet **API** route (polite, ~1 req/s) | — | MPL-2.0 |
+| `conceptnet/filter-dump.mjs` | regeneration tool — the ConceptNet **dump** route (produced the committed slice; the API was down) | — | MPL-2.0 |
+| `conceptnet/README.md` | provenance, retrieval date, seed terms, filter rules, row counts | — | — |
+
+And alongside (same phase, different directory because it is tmct-original
+data, not a derived corpus):
+
+| Path | What | Licence |
+|---|---|---|
+| `../data/templates/responses.jsonl` | ~56 response templates ({id, class, template, register}) | MPL-2.0 |
+| `../data/phrasebook/software-phrases.txt` | ~170 SE phrase patterns + 31 synonym families | MPL-2.0 |
+
+## How seeding works
+
+`src/corpus/conceptnet.mjs` turns the slice into tmct memory facts:
+
+```js
+import { seedMemory } from "./src/corpus/conceptnet.mjs";
+await seedMemory(repoDir);            // writes <repoDir>/.tmct/memory/graph.json
+await seedMemory(repoDir, { limit: 500 }); // capped (fast bootstrap)
+```
+
+- Each assertion whose relation maps to an ACE-OWL pattern
+  (`src/corpus/conceptnet-map.toml`, `ace != "none"`) becomes one reified
+  fact via `src/memory/core.mjs` `appendFact`:
+  `{subject:"software bug", predicate:"rdfs:subClassOf", object:"error",
+  provenance:"corpus:conceptnet /r/IsA"}`.
+- **Idempotent**: fact ids are content-hashed from the normalized triple, and
+  `seedMemory` pre-reads the store once and skips triples already present —
+  re-seeding costs one read, not N rewrites. Provenance from different
+  writers of the same triple is unioned, never overwritten.
+- `ace = "none"` relations (RelatedTo, Synonym, FormOf, …) are deliberately
+  NOT seeded — they are kept in the slice for future lexicon/fuzzy-match use.
+
+## How to regenerate / extend
+
+See `conceptnet/README.md` — one command per route (API vs dump), plus the
+seed-term list to extend. The test suite (`test/corpus-conceptnet.test.mjs`,
+`test/corpus-templates.test.mjs`) guards the contracts: slice/mapping drift,
+en→en shape, the ≤ 1.5 MB budget, template ids/slots, and end-to-end seeding.

package/corpus/conceptnet/LICENSE-NOTICE

@@ -0,0 +1,37 @@
+LICENSE NOTICE — corpus/conceptnet/slice.jsonl
+==============================================
+
+The file slice.jsonl in this directory is a filtered excerpt of ConceptNet 5.7,
+and is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License (CC-BY-SA 4.0), NOT under this repository's MPL-2.0.
+
+  https://creativecommons.org/licenses/by-sa/4.0/
+
+Attribution
+-----------
+
+This work includes data from ConceptNet 5, which was compiled by the
+Commonsense Computing Initiative. ConceptNet 5 is freely available under the
+Creative Commons Attribution-ShareAlike license (CC-BY-SA 4.0) from
+https://conceptnet.io. The included data was created by contributors to
+Commonsense Computing projects, contributors to Wikimedia projects, Games
+with a Purpose, Princeton University's WordNet, DBPedia, OpenCyc, and Umbel.
+
+Source
+------
+
+- Dataset: ConceptNet 5.7.0 assertions dump
+  https://s3.amazonaws.com/conceptnet/downloads/2019/edges/conceptnet-assertions-5.7.0.csv.gz
+  (dump published 2019-07-03; retrieved and filtered 2026-07-04)
+- Project: https://conceptnet.io / https://github.com/commonsense/conceptnet5
+- The filtering applied (English-only, tech-domain seed terms, canonical
+  relations, size budget) is described in README.md in this directory and is
+  reproducible via filter-dump.mjs.
+
+Share-alike
+-----------
+
+If you redistribute slice.jsonl (modified or not), you must do so under
+CC-BY-SA 4.0 with this attribution. The code in this directory
+(fetch-slice.mjs, filter-dump.mjs) is tmct code under the repository's
+MPL-2.0; only the data file carries CC-BY-SA 4.0.

package/corpus/conceptnet/README.md

@@ -0,0 +1,103 @@
+# corpus/conceptnet — the committed tech-domain ConceptNet slice
+
+`slice.jsonl` is a filtered excerpt of **real ConceptNet 5.7.0 data** — one
+assertion per line:
+
+```json
+{"start":"/c/en/bug","rel":"/r/IsA","end":"/c/en/insect","weight":6.32,"surfaceText":"[[a bug]] is [[an insect]]"}
+```
+
+**Licence: CC-BY-SA 4.0** (ConceptNet-derived data; NOT this repo's MPL-2.0) —
+see `LICENSE-NOTICE` in this directory for the full attribution.
+
+## Provenance and retrieval
+
+- **Source:** ConceptNet 5.7.0 assertions dump,
+  `https://s3.amazonaws.com/conceptnet/downloads/2019/edges/conceptnet-assertions-5.7.0.csv.gz`
+  (published 2019-07-03).
+- **Retrieved + filtered:** 2026-07-04.
+- **Why the dump, not the API:** the public API (`api.conceptnet.io`) was
+  hard-down (HTTP 502 from its nginx front-end on every request across ~15
+  attempts over 10+ minutes on 2026-07-04), so the slice was stream-filtered
+  from the published dump instead — same data, same licence. `fetch-slice.mjs`
+  (the API route) is kept for when the API is healthy; `filter-dump.mjs` is
+  the route that actually produced the committed slice.
+
+## Filter rules
+
+1. **English only**: `start` AND `end` are `/c/en/…` concepts; word-sense
+   suffixes are stripped (`/c/en/bug/n` → `/c/en/bug`); self-loops after
+   stripping are dropped.
+2. **Canonical relations only**: the closed set of 34 relations (the same set
+   mapped in `src/corpus/conceptnet-map.toml`), minus three filtered by
+   policy: `/r/EtymologicallyRelatedTo`, `/r/EtymologicallyDerivedFrom`,
+   `/r/ExternalURL` (etymology noise and link-outs — no consumer in tmct).
+3. **Tech-domain seed terms**: at least one endpoint's bare term is in the
+   90-term software/tech seed list exported as `SEED_TERMS` from
+   `fetch-slice.mjs` (software, computer, program, code, module, function,
+   database, server, network, bug, test, file, memory, algorithm, keyboard,
+   programmer, repository, commit, …).
+4. **Dedupe** by `(start, rel, end)`, keeping the higher weight.
+5. **Size budget** (committed slice ≤ 1.5 MB; target ~1.4 MB), **two-tier**:
+   assertions whose relation maps to an ACE-OWL pattern (`ace != "none"` in
+   `conceptnet-map.toml`) are kept first, weight-descending; `ace = "none"`
+   relations (`RelatedTo`, `Synonym`, …) fill the remaining budget — they
+   are kept for future lexicon/fuzzy-match use but never crowd out seedable
+   facts.
+6. Deterministic output order: `(rel, start, end)`.
+
+## Row counts (committed slice, 2026-07-04)
+
+**14,258 assertions, 1,399,979 bytes** (34,074,917 dump lines scanned;
+28,802 unique en→en seed assertions matched = 4,170 mappable + 24,632
+`ace="none"`; ALL 4,170 mappable kept, 10,088 none-rows fill the budget).
+29 of the 31 non-filtered canonical relations are present:
+
+| Relation | Rows | | Relation | Rows |
+|---|---|---|---|---|
+| `/r/RelatedTo` | 4911 | | `/r/HasA` | 39 |
+| `/r/HasContext` | 2634 | | `/r/HasProperty` | 27 |
+| `/r/IsA` | 2594 | | `/r/Antonym` | 25 |
+| `/r/DerivedFrom` | 1906 | | `/r/MotivatedByGoal` | 25 |
+| `/r/AtLocation` | 459 | | `/r/SimilarTo` | 20 |
+| `/r/Synonym` | 368 | | `/r/DistinctFrom` | 19 |
+| `/r/UsedFor` | 312 | | `/r/DefinedAs` | 16 |
+| `/r/FormOf` | 224 | | `/r/MadeOf` | 14 |
+| `/r/CapableOf` | 164 | | `/r/CausesDesire` | 12 |
+| `/r/MannerOf` | 141 | | `/r/HasLastSubevent` | 12 |
+| `/r/PartOf` | 115 | | `/r/Causes` | 11 |
+| `/r/HasPrerequisite` | 103 | | `/r/CreatedBy` | 10 |
+| `/r/HasSubevent` | 42 | | `/r/Desires` | 7 |
+| `/r/ReceivesAction` | 40 | | `/r/HasFirstSubevent` | 7 |
+| | | | `/r/LocatedNear` | 1 |
+
+Absent from the slice (nothing matched the seed terms): `/r/ObstructedBy`,
+`/r/SymbolOf` — both still have mapping rows, so a regenerated slice that
+surfaces them stays covered.
+
+## How to regenerate / extend
+
+```bash
+# preferred when api.conceptnet.io is healthy (polite, ~1 req/s, several minutes):
+node corpus/conceptnet/fetch-slice.mjs corpus/conceptnet/slice.jsonl
+
+# the dump route (used for the committed slice; ~500 MB streamed, nothing stored):
+curl -s https://s3.amazonaws.com/conceptnet/downloads/2019/edges/conceptnet-assertions-5.7.0.csv.gz \
+  | gunzip -c \
+  | node corpus/conceptnet/filter-dump.mjs > corpus/conceptnet/slice.jsonl
+```
+
+To extend the domain, add seed terms to `SEED_TERMS` in `fetch-slice.mjs` and
+re-run. `npm test` guards the contract: every relation present in the slice
+must have a row in `src/corpus/conceptnet-map.toml` (drift guard), en→en shape
+and the ≤ 1.5 MB budget are asserted, and the seeding path is exercised
+end-to-end.
+
+## Consumers
+
+- `src/corpus/conceptnet.mjs` — `loadSlice()` / `toFacts()` / `seedMemory()`:
+  maps mappable assertions onto memory facts
+  (`{subject, predicate, object, provenance:"corpus:conceptnet /r/…"}`)
+  and seeds `.tmct/memory/` via `appendFact` (idempotent).
+- `src/corpus/conceptnet-map.toml` — the relation → ACE-OWL pattern table
+  deciding which relations emit facts and under which predicate URI.