@polycode-projects/the-mechanical-code-talker 0.5.0 → 0.7.0

package/corpus/tier2/generate.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// corpus/tier2/generate.mjs — the TIER-2 specialised-corpus generator + manifest
+// writer. NOT part of the product path — a maintainer tool. Offline, $0.
+//
+// Tier-2 corpuses are LANGUAGE- or DOMAIN-specific fact sets (aws, python,
+// java, …) that tmct fetches/generates into `.tmct/` at init time so it can
+// "expand into a concept for an applicable codebase". They are NOT shipped in
+// the npm package the way the tier-1 ConceptNet slice is — they are opt-in,
+// selected per repo. See ../README.md for the full tier-1/2/3 policy.
+//
+// Every tier-2 corpus is written in the EXACT tier-1 fact shape
+// (corpus/conceptnet/slice.jsonl): one JSON object per line,
+//   {"start":"/c/en/<term>","rel":"/r/<Rel>","end":"/c/en/<concept>","weight":N,"surfaceText":"…"}
+// with `rel` drawn ONLY from the mapped relations in
+// src/corpus/conceptnet-map.toml, so a tier-2 file loads through the very same
+// loadSlice()/toFacts() path as the tier-1 slice (this file's --verify proves
+// it). The Wave-2 tier-2 SEEDER (see ../README.md) is what stamps the right
+// provenance (`corpus:tier2:<id> /r/…`) instead of the conceptnet default.
+//
+//   node corpus/tier2/generate.mjs            # (re)write every <id>.jsonl + manifest.json
+//   node corpus/tier2/generate.mjs --verify   # generate + assert each file loads & seeds cleanly
+//
+// To ADD a specialised corpus: add an entry to CORPUSES below (a list of
+// [subject, relation, concept] triples, optionally [.., surfaceText]) and
+// re-run. Curated sets are authored here so they stay reviewable and diffable;
+// a corpus too large to curate by hand is a `fetch` manifest entry instead
+// (network, opt-in — see fetchCorpus() and ../README.md).
+
+import { readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// A curated triple is [subject, rel, concept] or [subject, rel, concept, weight].
+// `rel` MUST be a mapped (ace != "none") relation in conceptnet-map.toml so the
+// fact actually seeds. Terms are lowercase snake_case; the loader's termText()
+// turns "/c/en/hash_table" into "hash table". Keep terms <= 3 words (the tier-1
+// quality-filter rule) — curated data is clean by construction.
+export const CORPUSES = {
+  aws: {
+    kind: "domain",
+    description: "Amazon Web Services core services and primitives (S3, Lambda, DynamoDB, EC2, IAM, SQS) mapped to general cloud/CS concepts.",
+    facts: [
+      ["aws", "/r/IsA", "cloud_platform"],
+      ["aws", "/r/IsA", "cloud"],
+      ["aws", "/r/CapableOf", "host_applications"],
+      // S3
+      ["s3", "/r/IsA", "object_storage"],
+      ["s3", "/r/IsA", "storage_service"],
+      ["s3", "/r/PartOf", "aws"],
+      ["s3", "/r/HasA", "bucket"],
+      ["s3", "/r/UsedFor", "storing_files"],
+      ["s3", "/r/CapableOf", "store_objects"],
+      ["bucket", "/r/IsA", "container"],
+      ["bucket", "/r/PartOf", "s3"],
+      ["bucket", "/r/UsedFor", "storing_objects"],
+      // Lambda
+      ["lambda", "/r/IsA", "compute_service"],
+      ["lambda", "/r/IsA", "function"],
+      ["lambda", "/r/PartOf", "aws"],
+      ["lambda", "/r/UsedFor", "running_code"],
+      ["lambda", "/r/CapableOf", "run_code"],
+      ["lambda", "/r/HasProperty", "serverless"],
+      // DynamoDB
+      ["dynamodb", "/r/IsA", "database"],
+      ["dynamodb", "/r/IsA", "nosql_database"],
+      ["dynamodb", "/r/PartOf", "aws"],
+      ["dynamodb", "/r/HasA", "table"],
+      ["dynamodb", "/r/UsedFor", "storing_data"],
+      ["dynamodb", "/r/HasProperty", "managed"],
+      // EC2
+      ["ec2", "/r/IsA", "compute_service"],
+      ["ec2", "/r/IsA", "virtual_machine"],
+      ["ec2", "/r/PartOf", "aws"],
+      ["ec2", "/r/HasA", "instance"],
+      ["ec2", "/r/UsedFor", "running_servers"],
+      // IAM
+      ["iam", "/r/IsA", "access_control"],
+      ["iam", "/r/PartOf", "aws"],
+      ["iam", "/r/UsedFor", "managing_permissions"],
+      ["iam", "/r/HasA", "role"],
+      ["iam", "/r/HasA", "policy"],
+      // SQS + queue
+      ["sqs", "/r/IsA", "message_queue"],
+      ["sqs", "/r/IsA", "queue"],
+      ["sqs", "/r/PartOf", "aws"],
+      ["sqs", "/r/UsedFor", "decoupling_services"],
+      ["queue", "/r/IsA", "data_structure"],
+    ],
+  },
+
+  python: {
+    kind: "language",
+    description: "Python language constructs and stdlib types mapped to the shared CS concept vocabulary (list->array, dict->hash table, …).",
+    facts: [
+      ["python", "/r/IsA", "programming_language"],
+      ["python", "/r/HasProperty", "interpreted"],
+      ["python", "/r/HasProperty", "dynamically_typed"],
+      ["python", "/r/UsedFor", "scripting"],
+      // built-in types → shared concepts
+      ["list", "/r/IsA", "array"],
+      ["list", "/r/IsA", "sequence"],
+      ["list", "/r/IsA", "data_structure"],
+      ["dict", "/r/IsA", "hash_table"],
+      ["dict", "/r/IsA", "dictionary"],
+      ["dict", "/r/IsA", "mapping"],
+      ["tuple", "/r/IsA", "sequence"],
+      ["tuple", "/r/HasProperty", "immutable"],
+      ["set", "/r/IsA", "collection"],
+      ["set", "/r/HasProperty", "unordered"],
+      ["str", "/r/IsA", "string"],
+      // language constructs
+      ["decorator", "/r/IsA", "function"],
+      ["decorator", "/r/UsedFor", "modifying_functions"],
+      ["generator", "/r/IsA", "iterator"],
+      ["generator", "/r/UsedFor", "lazy_evaluation"],
+      ["comprehension", "/r/IsA", "expression"],
+      ["comprehension", "/r/UsedFor", "building_collections"],
+      ["exception", "/r/IsA", "error"],
+      ["module", "/r/IsA", "file"],
+      ["package", "/r/IsA", "module"],
+      ["method", "/r/IsA", "function"],
+      // tooling / runtime
+      ["pip", "/r/IsA", "package_manager"],
+      ["pip", "/r/UsedFor", "installing_packages"],
+      ["gil", "/r/IsA", "lock"],
+      ["gil", "/r/PartOf", "interpreter"],
+      ["cpython", "/r/IsA", "interpreter"],
+    ],
+  },
+
+  java: {
+    kind: "language",
+    description: "Java language and JVM constructs mapped to the shared CS concept vocabulary (ArrayList->list, HashMap->hash table, …).",
+    facts: [
+      ["java", "/r/IsA", "programming_language"],
+      ["java", "/r/HasProperty", "compiled"],
+      ["java", "/r/HasProperty", "statically_typed"],
+      ["java", "/r/UsedFor", "building_applications"],
+      // types → shared concepts
+      ["arraylist", "/r/IsA", "list"],
+      ["arraylist", "/r/IsA", "data_structure"],
+      ["hashmap", "/r/IsA", "hash_table"],
+      ["hashmap", "/r/IsA", "dictionary"],
+      ["hashmap", "/r/IsA", "map"],
+      ["interface", "/r/IsA", "type"],
+      ["interface", "/r/IsA", "contract"],
+      ["class", "/r/IsA", "type"],
+      ["object", "/r/IsA", "instance"],
+      // JVM / runtime
+      ["jvm", "/r/IsA", "virtual_machine"],
+      ["jvm", "/r/UsedFor", "running_bytecode"],
+      ["jvm", "/r/CapableOf", "execute_bytecode"],
+      ["bytecode", "/r/IsA", "code"],
+      ["garbage_collector", "/r/PartOf", "jvm"],
+      ["garbage_collector", "/r/UsedFor", "freeing_memory"],
+      // packaging / tooling
+      ["jar", "/r/IsA", "archive"],
+      ["jar", "/r/IsA", "file"],
+      ["jar", "/r/UsedFor", "packaging_classes"],
+      ["maven", "/r/IsA", "build_tool"],
+      ["maven", "/r/IsA", "package_manager"],
+      ["gradle", "/r/IsA", "build_tool"],
+      // language features
+      ["thread", "/r/IsA", "process"],
+      ["thread", "/r/UsedFor", "concurrency"],
+      ["generics", "/r/UsedFor", "type_safety"],
+      ["annotation", "/r/IsA", "metadata"],
+      ["exception", "/r/IsA", "error"],
+      ["method", "/r/IsA", "function"],
+    ],
+  },
+};
+
+const conceptUri = (term) => `/c/en/${term}`;
+const humanize = (term) => term.replace(/_/g, " ");
+
+/** One curated triple → a tier-1-shaped slice row. */
+export function toRow([subject, rel, concept, weight = 1]) {
+  return {
+    start: conceptUri(subject),
+    rel,
+    end: conceptUri(concept),
+    weight,
+    surfaceText: `[[${humanize(subject)}]] ${rel.replace("/r/", "")} [[${humanize(concept)}]]`,
+  };
+}
+
+/** Curated corpus id → its JSONL text (deterministic order = authored order). */
+export function corpusJsonl(id) {
+  return CORPUSES[id].facts.map((f) => JSON.stringify(toRow(f))).join("\n") + "\n";
+}
+
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+// ---- network-fetch path (opt-in, offline-by-default) -----------------------
+// A tier-2 corpus too large to curate by hand is declared in the manifest with
+// { "source": { "kind": "fetch", "url": "...", "sha256": "..." } } and pulled by
+// a Wave-2 fetch step. This helper is the reference implementation — it is NEVER
+// called without an explicit --allow-network flag (the product default is $0,
+// offline). No sample corpus uses it; the three samples are all `curated`.
+export async function fetchCorpus(url, expectedSha) {
+  const res = await fetch(url, { headers: { accept: "application/x-ndjson,application/jsonl" } });
+  if (!res.ok) throw new Error(`fetch ${url}: HTTP ${res.status}`);
+  const text = await res.text();
+  const got = sha256(text);
+  if (expectedSha && got !== expectedSha) throw new Error(`checksum mismatch for ${url}: ${got} != ${expectedSha}`);
+  return text;
+}
+
+async function main() {
+  const verify = process.argv.includes("--verify");
+  const manifest = { version: 1, generated: "by corpus/tier2/generate.mjs", corpuses: [] };
+
+  for (const [id, spec] of Object.entries(CORPUSES)) {
+    const text = corpusJsonl(id);
+    await writeFile(join(HERE, `${id}.jsonl`), text);
+    manifest.corpuses.push({
+      id,
+      kind: spec.kind,
+      description: spec.description,
+      source: { kind: "curated", tool: "corpus/tier2/generate.mjs" },
+      file: `${id}.jsonl`,
+      facts: spec.facts.length,
+      bytes: Buffer.byteLength(text),
+      sha256: sha256(text),
+      license: "MPL-2.0",
+    });
+    console.error(`  ${id}: ${spec.facts.length} facts, ${Buffer.byteLength(text)} bytes`);
+  }
+
+  const manifestText = JSON.stringify(manifest, null, 2) + "\n";
+  await writeFile(join(HERE, "manifest.json"), manifestText);
+  console.error(`wrote manifest.json (${manifest.corpuses.length} corpuses)`);
+
+  if (verify) {
+    const { loadSlice, loadMap, toFacts } = await import("../../src/corpus/conceptnet.mjs");
+    const map = await loadMap();
+    for (const c of manifest.corpuses) {
+      const assertions = await loadSlice(join(HERE, c.file));
+      const facts = toFacts(assertions, map); // throws on any unmapped rel
+      if (assertions.length !== c.facts) throw new Error(`${c.id}: loadSlice count ${assertions.length} != ${c.facts}`);
+      if (facts.length !== c.facts) throw new Error(`${c.id}: ${c.facts - facts.length} fact(s) did not seed (ace=none rel?)`);
+      console.error(`  verify ${c.id}: ${assertions.length} assertions load, all ${facts.length} seed cleanly`);
+    }
+    console.error("verify: OK — every tier-2 corpus loads and seeds through the tier-1 path");
+  }
+}
+
+const isMain = process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isMain) await main();

package/corpus/tier2/java.jsonl

@@ -0,0 +1,31 @@
+{"start":"/c/en/java","rel":"/r/IsA","end":"/c/en/programming_language","weight":1,"surfaceText":"[[java]] IsA [[programming language]]"}
+{"start":"/c/en/java","rel":"/r/HasProperty","end":"/c/en/compiled","weight":1,"surfaceText":"[[java]] HasProperty [[compiled]]"}
+{"start":"/c/en/java","rel":"/r/HasProperty","end":"/c/en/statically_typed","weight":1,"surfaceText":"[[java]] HasProperty [[statically typed]]"}
+{"start":"/c/en/java","rel":"/r/UsedFor","end":"/c/en/building_applications","weight":1,"surfaceText":"[[java]] UsedFor [[building applications]]"}
+{"start":"/c/en/arraylist","rel":"/r/IsA","end":"/c/en/list","weight":1,"surfaceText":"[[arraylist]] IsA [[list]]"}
+{"start":"/c/en/arraylist","rel":"/r/IsA","end":"/c/en/data_structure","weight":1,"surfaceText":"[[arraylist]] IsA [[data structure]]"}
+{"start":"/c/en/hashmap","rel":"/r/IsA","end":"/c/en/hash_table","weight":1,"surfaceText":"[[hashmap]] IsA [[hash table]]"}
+{"start":"/c/en/hashmap","rel":"/r/IsA","end":"/c/en/dictionary","weight":1,"surfaceText":"[[hashmap]] IsA [[dictionary]]"}
+{"start":"/c/en/hashmap","rel":"/r/IsA","end":"/c/en/map","weight":1,"surfaceText":"[[hashmap]] IsA [[map]]"}
+{"start":"/c/en/interface","rel":"/r/IsA","end":"/c/en/type","weight":1,"surfaceText":"[[interface]] IsA [[type]]"}
+{"start":"/c/en/interface","rel":"/r/IsA","end":"/c/en/contract","weight":1,"surfaceText":"[[interface]] IsA [[contract]]"}
+{"start":"/c/en/class","rel":"/r/IsA","end":"/c/en/type","weight":1,"surfaceText":"[[class]] IsA [[type]]"}
+{"start":"/c/en/object","rel":"/r/IsA","end":"/c/en/instance","weight":1,"surfaceText":"[[object]] IsA [[instance]]"}
+{"start":"/c/en/jvm","rel":"/r/IsA","end":"/c/en/virtual_machine","weight":1,"surfaceText":"[[jvm]] IsA [[virtual machine]]"}
+{"start":"/c/en/jvm","rel":"/r/UsedFor","end":"/c/en/running_bytecode","weight":1,"surfaceText":"[[jvm]] UsedFor [[running bytecode]]"}
+{"start":"/c/en/jvm","rel":"/r/CapableOf","end":"/c/en/execute_bytecode","weight":1,"surfaceText":"[[jvm]] CapableOf [[execute bytecode]]"}
+{"start":"/c/en/bytecode","rel":"/r/IsA","end":"/c/en/code","weight":1,"surfaceText":"[[bytecode]] IsA [[code]]"}
+{"start":"/c/en/garbage_collector","rel":"/r/PartOf","end":"/c/en/jvm","weight":1,"surfaceText":"[[garbage collector]] PartOf [[jvm]]"}
+{"start":"/c/en/garbage_collector","rel":"/r/UsedFor","end":"/c/en/freeing_memory","weight":1,"surfaceText":"[[garbage collector]] UsedFor [[freeing memory]]"}
+{"start":"/c/en/jar","rel":"/r/IsA","end":"/c/en/archive","weight":1,"surfaceText":"[[jar]] IsA [[archive]]"}
+{"start":"/c/en/jar","rel":"/r/IsA","end":"/c/en/file","weight":1,"surfaceText":"[[jar]] IsA [[file]]"}
+{"start":"/c/en/jar","rel":"/r/UsedFor","end":"/c/en/packaging_classes","weight":1,"surfaceText":"[[jar]] UsedFor [[packaging classes]]"}
+{"start":"/c/en/maven","rel":"/r/IsA","end":"/c/en/build_tool","weight":1,"surfaceText":"[[maven]] IsA [[build tool]]"}
+{"start":"/c/en/maven","rel":"/r/IsA","end":"/c/en/package_manager","weight":1,"surfaceText":"[[maven]] IsA [[package manager]]"}
+{"start":"/c/en/gradle","rel":"/r/IsA","end":"/c/en/build_tool","weight":1,"surfaceText":"[[gradle]] IsA [[build tool]]"}
+{"start":"/c/en/thread","rel":"/r/IsA","end":"/c/en/process","weight":1,"surfaceText":"[[thread]] IsA [[process]]"}
+{"start":"/c/en/thread","rel":"/r/UsedFor","end":"/c/en/concurrency","weight":1,"surfaceText":"[[thread]] UsedFor [[concurrency]]"}
+{"start":"/c/en/generics","rel":"/r/UsedFor","end":"/c/en/type_safety","weight":1,"surfaceText":"[[generics]] UsedFor [[type safety]]"}
+{"start":"/c/en/annotation","rel":"/r/IsA","end":"/c/en/metadata","weight":1,"surfaceText":"[[annotation]] IsA [[metadata]]"}
+{"start":"/c/en/exception","rel":"/r/IsA","end":"/c/en/error","weight":1,"surfaceText":"[[exception]] IsA [[error]]"}
+{"start":"/c/en/method","rel":"/r/IsA","end":"/c/en/function","weight":1,"surfaceText":"[[method]] IsA [[function]]"}

package/corpus/tier2/manifest.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "generated": "by corpus/tier2/generate.mjs",
+  "corpuses": [
+    {
+      "id": "aws",
+      "kind": "domain",
+      "description": "Amazon Web Services core services and primitives (S3, Lambda, DynamoDB, EC2, IAM, SQS) mapped to general cloud/CS concepts.",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "aws.jsonl",
+      "facts": 39,
+      "bytes": 4802,
+      "sha256": "7ab3e656bc4bc717be3c50d97af030e8592d6597cde182b15390a1dfaca9755a",
+      "license": "MPL-2.0"
+    },
+    {
+      "id": "python",
+      "kind": "language",
+      "description": "Python language constructs and stdlib types mapped to the shared CS concept vocabulary (list->array, dict->hash table, …).",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "python.jsonl",
+      "facts": 30,
+      "bytes": 3794,
+      "sha256": "009245d024357bc4285e967fba486e32349ccec8fbe2796ba13011cb2be4c19c",
+      "license": "MPL-2.0"
+    },
+    {
+      "id": "java",
+      "kind": "language",
+      "description": "Java language and JVM constructs mapped to the shared CS concept vocabulary (ArrayList->list, HashMap->hash table, …).",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "java.jsonl",
+      "facts": 31,
+      "bytes": 3920,
+      "sha256": "d089426833c393f6f1574fe75c4ac94a1483ee80f72f79bd7fd32aaaa24a6e44",
+      "license": "MPL-2.0"
+    }
+  ]
+}

package/corpus/tier2/python.jsonl

@@ -0,0 +1,30 @@
+{"start":"/c/en/python","rel":"/r/IsA","end":"/c/en/programming_language","weight":1,"surfaceText":"[[python]] IsA [[programming language]]"}
+{"start":"/c/en/python","rel":"/r/HasProperty","end":"/c/en/interpreted","weight":1,"surfaceText":"[[python]] HasProperty [[interpreted]]"}
+{"start":"/c/en/python","rel":"/r/HasProperty","end":"/c/en/dynamically_typed","weight":1,"surfaceText":"[[python]] HasProperty [[dynamically typed]]"}
+{"start":"/c/en/python","rel":"/r/UsedFor","end":"/c/en/scripting","weight":1,"surfaceText":"[[python]] UsedFor [[scripting]]"}
+{"start":"/c/en/list","rel":"/r/IsA","end":"/c/en/array","weight":1,"surfaceText":"[[list]] IsA [[array]]"}
+{"start":"/c/en/list","rel":"/r/IsA","end":"/c/en/sequence","weight":1,"surfaceText":"[[list]] IsA [[sequence]]"}
+{"start":"/c/en/list","rel":"/r/IsA","end":"/c/en/data_structure","weight":1,"surfaceText":"[[list]] IsA [[data structure]]"}
+{"start":"/c/en/dict","rel":"/r/IsA","end":"/c/en/hash_table","weight":1,"surfaceText":"[[dict]] IsA [[hash table]]"}
+{"start":"/c/en/dict","rel":"/r/IsA","end":"/c/en/dictionary","weight":1,"surfaceText":"[[dict]] IsA [[dictionary]]"}
+{"start":"/c/en/dict","rel":"/r/IsA","end":"/c/en/mapping","weight":1,"surfaceText":"[[dict]] IsA [[mapping]]"}
+{"start":"/c/en/tuple","rel":"/r/IsA","end":"/c/en/sequence","weight":1,"surfaceText":"[[tuple]] IsA [[sequence]]"}
+{"start":"/c/en/tuple","rel":"/r/HasProperty","end":"/c/en/immutable","weight":1,"surfaceText":"[[tuple]] HasProperty [[immutable]]"}
+{"start":"/c/en/set","rel":"/r/IsA","end":"/c/en/collection","weight":1,"surfaceText":"[[set]] IsA [[collection]]"}
+{"start":"/c/en/set","rel":"/r/HasProperty","end":"/c/en/unordered","weight":1,"surfaceText":"[[set]] HasProperty [[unordered]]"}
+{"start":"/c/en/str","rel":"/r/IsA","end":"/c/en/string","weight":1,"surfaceText":"[[str]] IsA [[string]]"}
+{"start":"/c/en/decorator","rel":"/r/IsA","end":"/c/en/function","weight":1,"surfaceText":"[[decorator]] IsA [[function]]"}
+{"start":"/c/en/decorator","rel":"/r/UsedFor","end":"/c/en/modifying_functions","weight":1,"surfaceText":"[[decorator]] UsedFor [[modifying functions]]"}
+{"start":"/c/en/generator","rel":"/r/IsA","end":"/c/en/iterator","weight":1,"surfaceText":"[[generator]] IsA [[iterator]]"}
+{"start":"/c/en/generator","rel":"/r/UsedFor","end":"/c/en/lazy_evaluation","weight":1,"surfaceText":"[[generator]] UsedFor [[lazy evaluation]]"}
+{"start":"/c/en/comprehension","rel":"/r/IsA","end":"/c/en/expression","weight":1,"surfaceText":"[[comprehension]] IsA [[expression]]"}
+{"start":"/c/en/comprehension","rel":"/r/UsedFor","end":"/c/en/building_collections","weight":1,"surfaceText":"[[comprehension]] UsedFor [[building collections]]"}
+{"start":"/c/en/exception","rel":"/r/IsA","end":"/c/en/error","weight":1,"surfaceText":"[[exception]] IsA [[error]]"}
+{"start":"/c/en/module","rel":"/r/IsA","end":"/c/en/file","weight":1,"surfaceText":"[[module]] IsA [[file]]"}
+{"start":"/c/en/package","rel":"/r/IsA","end":"/c/en/module","weight":1,"surfaceText":"[[package]] IsA [[module]]"}
+{"start":"/c/en/method","rel":"/r/IsA","end":"/c/en/function","weight":1,"surfaceText":"[[method]] IsA [[function]]"}
+{"start":"/c/en/pip","rel":"/r/IsA","end":"/c/en/package_manager","weight":1,"surfaceText":"[[pip]] IsA [[package manager]]"}
+{"start":"/c/en/pip","rel":"/r/UsedFor","end":"/c/en/installing_packages","weight":1,"surfaceText":"[[pip]] UsedFor [[installing packages]]"}
+{"start":"/c/en/gil","rel":"/r/IsA","end":"/c/en/lock","weight":1,"surfaceText":"[[gil]] IsA [[lock]]"}
+{"start":"/c/en/gil","rel":"/r/PartOf","end":"/c/en/interpreter","weight":1,"surfaceText":"[[gil]] PartOf [[interpreter]]"}
+{"start":"/c/en/cpython","rel":"/r/IsA","end":"/c/en/interpreter","weight":1,"surfaceText":"[[cpython]] IsA [[interpreter]]"}

package/data/templates/responses.jsonl

@@ -62,7 +62,10 @@
 {"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
 {"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import walk.mjs\n  what calls buildContextBundle\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
 {"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
+{"id":"conversational-greeting-empty","class":"conversational","register":"friendly","template":"Hi. There's no code graph loaded here — for code structure (imports, calls, definitions) I need a `.tmct/graph.json`: point me at one with `--repo <path>`, or try the shipped example `npm run example:mini`. (tmct reads graphs; it doesn't index code itself.) For general vocabulary, `tmct init` seeds concepts — try \"what is a cache\". /help for commands."}
+{"id":"orientation-empty","class":"orientation","register":"friendly","template":"There's no code graph loaded here, so I can't answer structure questions (imports, calls, definitions) yet.\nFor those I need a `.tmct/graph.json` produced by a graph producer — point me at one with `--repo <path>`, or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself.\nFor general vocabulary, `tmct init` seeds concepts — try \"what is a cache\". /help for commands, /memory for what I remember."}
 {"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
 {"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
 {"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}
 {"id":"technical-ratio","class":"count","register":"technical","template":"{subject} sustains a ratio of {count} {noun} per {unit}, placing it in the upper band for projects of comparable {scope} ({provenance})."}
+{"id":"concept-force","class":"concept","register":"friendly","template":"{definition}\n{examples}{followups}"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.5.0",
+  "version": "0.7.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.",
@@ -48,7 +48,12 @@
     "./relationKind": "./src/codegraph.mjs",
     "./impactClosure": "./src/codegraph.mjs",
     "./dispatchTool": "./src/server.mjs",
-    "./fetchEntities": "./src/source.mjs"
+    "./fetchEntities": "./src/source.mjs",
+    "./repository-interface": "./src/repository-interface.mjs",
+    "./graph-service": "./src/providers/graph-service.mjs",
+    "./providers/fixture": "./src/providers/fixture.mjs",
+    "./providers/bootstrap": "./src/providers/bootstrap.mjs",
+    "./conformance": "./src/conformance.mjs"
   },
   "files": [
     "bin/",
@@ -72,6 +77,12 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.mjs\"",
     "chat": "node bin/tmct.mjs",
+    "chat:repo": "node bin/tmct.mjs chat --repo",
+    "init": "node bin/tmct.mjs init",
+    "memory": "node bin/tmct.mjs memory",
+    "syllogise": "node bin/tmct.mjs syllogise",
+    "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",
     "audit": "npm audit --audit-level=high",

package/src/ask-vocab.mjs

@@ -529,7 +529,14 @@ export const AGGREGATE_TRIGGERS = Object.freeze([
   // CONTENT_VOCAB and blocks the article's own noise-strip)
   "how many", "how much", "how many of", "number of",
   "total number of", "quantity of",
-  // neutral / imperative
+  // "<measure> of <kind>" cardinality forms (widened net, cycle W2P): count = sum = total
+  // = tally = number of. The bare single words (sum/total/tally) stay CASCADE_SYNONYMS-
+  // mapped to "count" (identifier-fragment risk without the "of" anchor — see that table's
+  // note); the multi-word "of" forms are safe to promote to direct triggers because the
+  // trailing "of <kind>" pins them to a cardinality question, not a stray identifier.
+  "tally of", "sum of", "total of", "amount of",
+  // neutral / imperative (bare "tally"/"sum"/"total" stay CASCADE_SYNONYMS-mapped so the
+  // "tally the classes" relaxation path — pinned by a cascade test — is preserved).
   "count", "count up", "count of", "tot up",
 ]);
 
@@ -593,6 +600,17 @@ export const EDGE_NOUN_TO_METRIC = Object.freeze({
   connections: { kind: "*", dir: "both" },
   edges: { kind: "*", dir: "both" },
   connected: { kind: "*", dir: "both" },
+  // participle degree-nouns (widened net, cycle W2P): "the most imported / most
+  // depended-on / most used <module>" ranks by IN-degree — how many things import/depend
+  // on/use it — the ARGMAX-by-degree intent a developer expresses with a passive
+  // participle rather than the noun ("importers"). "depended" catches "depended-on" /
+  // "depended on" (both tokenize to a bare "depended"); "used" folds the symbol-grain
+  // callsSymbol callers in alongside importers so "most used" reads as most-relied-upon.
+  imported: { kind: "imports", dir: "in" },
+  "depended-on": { kind: "imports", dir: "in" },
+  depended: { kind: "imports", dir: "in" },
+  used: { kind: "imports", dir: "in", sibling: "callsSymbol" },
+  called: { kind: "calls", dir: "in", sibling: "callsSymbol" },
 });
 
 /** Anaphora triggers over the PREVIOUS result set (ask()'s `prev` id array):

package/src/ask.mjs

@@ -51,7 +51,7 @@ import {
 // grammar, split out of this file: normalization pre-pass, the two parsing
 // strategies, and the bounded-fuzzy service. Re-exported below where existing
 // callers/tests import them from here.
-import { normalizeQuery, applyNegationFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { normalizeQuery, applyNegationFrames, applyPhrasingFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -168,7 +168,7 @@ export function parseQuery(query, { nlp = undefined } = {}) {
   const adapter = nlp === undefined ? defaultNlp() : nlp;
   const raw = String(query || "").trim().replace(/\s+/g, " ");
   if (!raw) return null;
-  const text = applyNegationFrames(normalizeQuery(raw));
+  const text = applyPhrasingFrames(applyNegationFrames(normalizeQuery(raw)));
   if (!text) return null;
   // COMPOSITIONAL PARSE PATH (PLAN §5.16 P3) — the new PRIMARY layer: a recursive
   // descent over CLAUSES for the compositional shapes (nested/relative, boolean,
@@ -1471,18 +1471,18 @@ export function traverse(graph, parsed, { contextId = null, prev = null } = {})
 
   // reverse: "which <entityType> R <objMatch>". GRAIN-AWARE (Cycle 5, lever 3): a kind
   // that carries a symbol-grain sibling reads off the SIBLING when a fine SUBJECT grain
-  // was asked for ("which functions call X" → callsSymbol). Additionally, for `touches`
-  // specifically, when the RESOLVED OBJECT is itself a fine symbol the answer MUST read off
-  // touchesSymbol: touches is Commit→Module (module-coarse) and can NEVER point at a
-  // symbol, so "how many commits touched Widget.render" used to scan the module-grain
-  // edges and return a false 0 — the count belongs at symbol grain. This object-driven
-  // switch is scoped to touches on purpose: calls/callsSymbol already resolve a fine
-  // object through the fine-entityType branch, and a null-entityType "what calls <fn>"
-  // deliberately keeps its module-coarse `calls` receipt (the honest-empty showcase pins
-  // it), so widening the switch to calls would silently change that answer.
+  // was asked for ("which functions call X" → callsSymbol). It ALSO reads off the sibling
+  // when the RESOLVED OBJECT is itself a fine symbol, for EVERY kind with a sibling — not
+  // only touches: the module-coarse edge (calls Module→Module, touches Commit→Module) can
+  // NEVER point at a function/method, so a bare "what calls fnAlpha" scanning the coarse
+  // `calls` edges returned a FALSE empty ("No modules found …") while the graph records a
+  // real symbol-level caller (Widget.render --callsSymbol--> fnAlpha). The honest answer
+  // reads off callsSymbol at symbol grain; a truly-uncalled symbol still renders the
+  // honest empty, now with the accurate callsSymbol receipt. (Previously scoped to touches
+  // only, which left this exact callsSymbol caller invisible — a genuine correctness bug.)
   const symbolKind = SYMBOL_GRAIN_SIBLING[kind];
-  const objIsTouchedSymbol = kind === "touches" && !!(objMatch.class && FINE_ENTITY_TYPES.has(objMatch.class));
-  if (symbolKind && (FINE_ENTITY_TYPES.has(entityType) || objIsTouchedSymbol)) {
+  const objIsFineSymbol = !!(objMatch.class && FINE_ENTITY_TYPES.has(objMatch.class));
+  if (symbolKind && (FINE_ENTITY_TYPES.has(entityType) || objIsFineSymbol)) {
     const edges = edgesOfKind(graph, symbolKind).filter((e) => e.object === objMatch.id);
     const subjects = uniqueById(edges.map((e) => graph.byId.get(e.subject)).filter(Boolean));
     const matches = (!entityType || entityType === "Change") ? subjects : subjects.filter((i) => i.class === entityType);