@polycode-projects/the-mechanical-code-talker 0.4.0 → 0.6.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/grammar-rules.toml

@@ -16,14 +16,22 @@
 # chosen to commute so finish() is idempotent: finish(finish(x)) === finish(x).
 #
 # SEQUENCING (PLAN_RESPONSE_FINISHING.md, "one grammar rule per tuning cycle"):
-# only ARTICLE-SELECTION is live this cycle — it fixes a genuine defect with a
-# narrow, safe blast radius. AGREEMENT, CAPITALISATION, LIST and TERMINAL are
-# fully implemented and golden-tested IN ISOLATION, but PARKED (enabled=false):
-# each rewrites established product bytes (tmct's lowercase openers and repeated
-# "and" joins are an intentional VOICE, not a grammar defect), so activating them
-# is a per-rule tuning-cycle decision with its own bench + showcase reconcile,
-# not a blanket flip. `enabled=false` keeps them inert in finish(); the goldens
-# force-enable each rule to prove its behaviour independent of the live flag.
+# LIVE as of cycle 005: ARTICLE-SELECTION (cycle 4), plus the two SAFE defect
+# fixes TERMINAL-PUNCTUATION and SUBJECT-VERB-AGREEMENT — each byte-stable when
+# neutral, no product-voice change. CAPITALISATION and LIST are fully implemented
+# and golden-tested IN ISOLATION but remain PARKED (enabled=false). The cycle-006
+# judged A/B was assessed and DROPPED: `capitalise` rewrites the sentence-initial
+# char, which regresses ~10 frozen v1 cases.jsonl whose case-sensitive answerMatch
+# pins lowercase openers ("can't count", "no symbol matching", "assuming you meant",
+# …) — the same sacred-case collision that reverted the voice-nit; and `list` has
+# zero 3-item "X and Y and Z" targets in the judged set (a no-op). Deferred to a
+# post-arc case-set refresh where the openers can be re-pinned deliberately. They
+# rewrite established product bytes (tmct's
+# lowercase openers and repeated "and" joins are an intentional VOICE, not a
+# grammar defect), so activating them is a per-rule tuning-cycle decision with
+# its own bench + showcase reconcile, not a blanket flip. `enabled=false` keeps
+# them inert in finish(); the goldens force-enable each rule to prove its
+# behaviour independent of the live flag.
 
 # 1. Article selection — a/an by the following word's phonetic onset. The live
 #    defect this fixes: the assert echo "every module is a artifact" -> "an
@@ -48,7 +56,7 @@ vowel_sound_consonants = ["hour", "honest", "honour", "honor", "heir", "herb"]
 [[rule]]
 id = "subject-verb-agreement"
 kind = "agreement"
-enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+enabled = true    # LIVE (cycle 005) — structure-driven existential agreement, byte-stable when neutral
 registers = []
 description = "existential copula agrees with the following count/plurality"
 singular = ["is", "was", "has"]
@@ -83,7 +91,7 @@ separator = ", "
 [[rule]]
 id = "terminal-punctuation"
 kind = "terminal"
-enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+enabled = true    # LIVE (cycle 005) — pure defect fix, narrowest blast radius (trailing doubled stop)
 registers = []
 description = "collapse a run of trailing sentence stops to a single stop"
 stops = [".", "!", "?"]

package/data/templates/responses.jsonl

@@ -62,6 +62,8 @@
 {"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 yet — point me at your code with `--repo <path>` or run `tmct init`. Meanwhile I know some general vocabulary — 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.\nPoint me at your code with `--repo <path>` or run `tmct init` to index this repo.\nI do know some general vocabulary — 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})."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.4.0",
+  "version": "0.6.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,9 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.mjs\"",
     "chat": "node bin/tmct.mjs",
+    "chat:repo": "node bin/tmct.mjs chat --repo",
+    "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp",
+    "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot",
     "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):