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

package/src/grammar/lexicon-core.json

@@ -0,0 +1,287 @@
+{
+  "comment": "tmct's starter software-domain lexicon (ROADMAP Phase 2, item 2). Every word the ACE-OWL sub-fragment parser (src/grammar/ace.mjs) is allowed to understand is DECLARED here — tmct never guesses a word's category. Nouns may declare a possessive property typing ('data' or 'object', pattern 7); adjectives MUST declare a type ('subclass' forms a class, 'data' asserts a boolean-ish datatype property, pattern 8); verbs may declare a preposition ('depend' + 'on' → dependsOn). Extend via loadLexicon(extra) with this same shape.",
+  "nouns": {
+    "module": {},
+    "class": {},
+    "function": {},
+    "method": {},
+    "attribute": {},
+    "variable": {},
+    "constant": {},
+    "test": {},
+    "suite": {},
+    "service": {},
+    "repository": {},
+    "branch": {},
+    "commit": {},
+    "tag": {},
+    "release": {},
+    "package": {},
+    "library": {},
+    "framework": {},
+    "api": {},
+    "endpoint": {},
+    "route": {},
+    "handler": {},
+    "controller": {},
+    "model": {},
+    "view": {},
+    "template": {},
+    "component": {},
+    "interface": {},
+    "type": {},
+    "schema": {},
+    "database": {},
+    "table": {},
+    "query": {},
+    "index": { "plural": "indices" },
+    "cache": {},
+    "queue": {},
+    "worker": {},
+    "job": {},
+    "task": {},
+    "bug": {},
+    "defect": {},
+    "issue": {},
+    "ticket": {},
+    "feature": {},
+    "requirement": {},
+    "specification": {},
+    "document": {},
+    "developer": {},
+    "engineer": {},
+    "user": {},
+    "visitor": {},
+    "team": {},
+    "project": {},
+    "codebase": {},
+    "file": {},
+    "directory": {},
+    "folder": {},
+    "line": {},
+    "symbol": {},
+    "identifier": {},
+    "comment": {},
+    "docstring": {},
+    "string": {},
+    "number": {},
+    "list": {},
+    "array": {},
+    "graph": {},
+    "node": {},
+    "edge": {},
+    "triple": {},
+    "fact": {},
+    "ontology": {},
+    "lexicon": {},
+    "grammar": {},
+    "sentence": {},
+    "utterance": {},
+    "session": {},
+    "response": {},
+    "request": {},
+    "question": {},
+    "answer": {},
+    "error": {},
+    "exception": {},
+    "warning": {},
+    "log": {},
+    "metric": {},
+    "benchmark": {},
+    "pipeline": {},
+    "build": {},
+    "deployment": {},
+    "environment": {},
+    "config": {},
+    "configuration": {},
+    "setting": {},
+    "option": {},
+    "flag": {},
+    "argument": {},
+    "parameter": {},
+    "value": {},
+    "result": {},
+    "output": {},
+    "input": {},
+    "server": {},
+    "client": {},
+    "protocol": {},
+    "message": {},
+    "event": {},
+    "hook": {},
+    "plugin": {},
+    "script": {},
+    "tool": {},
+    "command": {},
+    "prompt": {},
+    "token": {},
+    "parser": {},
+    "compiler": {},
+    "linter": {},
+    "formatter": {},
+    "runtime": {},
+    "process": {},
+    "thread": {},
+    "loop": {},
+    "statement": {},
+    "expression": {},
+    "keyword": {},
+    "scope": {},
+    "callback": {},
+    "promise": {},
+    "iterator": {},
+    "generator": {},
+    "unit": {},
+    "risk": {},
+    "prototype": {},
+    "milestone": {},
+    "sprint": {},
+    "backlog": {},
+    "roadmap": {},
+    "phase": {},
+    "pattern": {},
+    "smell": {},
+    "coverage": {},
+    "mock": {},
+    "stub": {},
+    "fixture": {},
+    "assertion": {},
+    "snapshot": {},
+    "regression": {},
+    "migration": {},
+    "refactor": {},
+    "review": {},
+    "merge": {},
+    "license": { "property": "data" },
+    "version": { "property": "data" },
+    "name": { "property": "data" },
+    "path": { "property": "data" },
+    "size": { "property": "data" },
+    "status": { "property": "data" },
+    "language": { "property": "data" },
+    "extension": { "property": "data" },
+    "owner": { "property": "object" },
+    "maintainer": { "property": "object" },
+    "author": { "property": "object" },
+    "reviewer": { "property": "object" },
+    "parent": { "property": "object" },
+    "dependency": { "property": "object" }
+  },
+  "verbs": {
+    "import": {},
+    "call": {},
+    "test": {},
+    "contain": {},
+    "extend": {},
+    "use": {},
+    "depend": { "prep": "on" },
+    "rely": { "prep": "on" },
+    "inherit": { "prep": "from" },
+    "belong": { "prep": "to" },
+    "point": { "prep": "to" },
+    "implement": {},
+    "override": {},
+    "export": {},
+    "define": {},
+    "declare": {},
+    "reference": {},
+    "invoke": {},
+    "wrap": {},
+    "mock": {},
+    "cover": {},
+    "document": {},
+    "describe": {},
+    "modify": {},
+    "touch": {},
+    "fix": {},
+    "break": {},
+    "introduce": {},
+    "deprecate": {},
+    "replace": {},
+    "own": {},
+    "maintain": {},
+    "review": {},
+    "merge": {},
+    "revert": {},
+    "deploy": {},
+    "run": {},
+    "execute": {},
+    "load": {},
+    "parse": {},
+    "emit": {},
+    "validate": {},
+    "log": {},
+    "throw": {},
+    "catch": {},
+    "create": {},
+    "delete": {},
+    "update": {},
+    "expose": {},
+    "consume": {},
+    "produce": {},
+    "generate": {},
+    "configure": {},
+    "install": {},
+    "publish": {},
+    "release": {},
+    "ship": {},
+    "watch": {},
+    "trigger": {},
+    "build": {},
+    "write": {},
+    "read": {},
+    "have": {}
+  },
+  "adjectives": {
+    "legacy": { "type": "subclass" },
+    "internal": { "type": "subclass" },
+    "external": { "type": "subclass" },
+    "public": { "type": "subclass" },
+    "private": { "type": "subclass" },
+    "abstract": { "type": "subclass" },
+    "static": { "type": "subclass" },
+    "async": { "type": "subclass" },
+    "experimental": { "type": "subclass" },
+    "stable": { "type": "subclass" },
+    "core": { "type": "subclass" },
+    "shared": { "type": "subclass" },
+    "global": { "type": "subclass" },
+    "local": { "type": "subclass" },
+    "generated": { "type": "subclass" },
+    "standalone": { "type": "subclass" },
+    "primary": { "type": "subclass" },
+    "secondary": { "type": "subclass" },
+    "deprecated": { "type": "data" },
+    "fast": { "type": "data" },
+    "slow": { "type": "data" },
+    "large": { "type": "data" },
+    "small": { "type": "data" },
+    "flaky": { "type": "data" },
+    "tested": { "type": "data" },
+    "documented": { "type": "data" },
+    "buggy": { "type": "data" },
+    "broken": { "type": "data" },
+    "green": { "type": "data" },
+    "deterministic": { "type": "data" },
+    "pure": { "type": "data" },
+    "empty": { "type": "data" },
+    "stale": { "type": "data" }
+  },
+  "properNames": [
+    "tmct",
+    "Node",
+    "npm",
+    "JavaScript",
+    "TypeScript",
+    "Python",
+    "Java",
+    "Git",
+    "GitHub",
+    "GitLab",
+    "ESLint",
+    "Linux",
+    "macOS",
+    "Windows",
+    "Polycode"
+  ]
+}

package/src/grammar/lexicon.mjs

@@ -0,0 +1,202 @@
+// grammar/lexicon.mjs — the declared lexicon behind tmct's ACE-OWL sub-fragment
+// (ROADMAP Phase 2, item 2; docs/references/schemas/ace-owl-fragment.md).
+//
+// The lexicon is LOAD-BEARING: the grammar (grammar/ace.mjs) is only
+// deterministic because every noun, verb (with any preposition), adjective
+// (with its declared type) and proper name is DECLARED — tmct never guesses a
+// word's category. Undeclared words route a sentence out of the grammar
+// strategy (a miss is a feature: the interpretation pipeline falls through to
+// the tolerant strategies).
+//
+// Data lives in lexicon-core.json (plain, diffable — the item-4/7 format
+// discipline), a starter software-domain vocabulary. Callers extend it via
+// loadLexicon(extra) with the same JSON shape; user entries win on conflict.
+//
+// Morphology is deliberately tiny and deterministic (no NLP dependency): a
+// suffix-fold for plurals/3rd-person-singular ("repositories"→repository,
+// "relies"→rely, "classes"→class, "uses"→use) plus an optional declared
+// irregular `plural` ("indices"). Anything the fold can't reach is simply not
+// in the lexicon — honest, not clever.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const CORE_FILE = join(dirname(fileURLToPath(import.meta.url)), "lexicon-core.json");
+
+/** Determiner tokens the grammar consumes (pattern table's every/a/no…). */
+export const DETERMINERS = Object.freeze({
+  every: "universal",
+  a: "indefinite",
+  an: "indefinite",
+  the: "definite",
+  no: "negative",
+});
+
+/** The cardinality quantifier phrases (pattern 5) → the OWL term they select. */
+export const QUANTIFIERS = Object.freeze({
+  "at least": "owl:minCardinality",
+  "at most": "owl:maxCardinality",
+  exactly: "owl:cardinality",
+});
+
+const NUMBER_WORDS = Object.freeze({
+  one: 1, two: 2, three: 3, four: 4, five: 5,
+  six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+});
+
+/** Parse a cardinality count token: a digit run or a small number word. */
+export function numberOf(word) {
+  const w = String(word ?? "").trim().toLowerCase();
+  if (/^\d+$/.test(w)) return Number(w);
+  return NUMBER_WORDS[w] ?? null;
+}
+
+/** 3rd-person-singular surface form of a verb lemma — the predicate spelling
+ *  ("import"→imports, "rely"→relies, "catch"→catches, "have"→has), matching
+ *  the code graph's 3sg relation-kind convention (ask.mjs §verbs). */
+export function thirdPerson(base) {
+  const b = String(base);
+  if (b === "have") return "has";
+  if (/[^aeiou]y$/.test(b)) return `${b.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(b)) return `${b}es`;
+  return `${b}s`;
+}
+
+/** The URI-style predicate a verb entry emits: a declared override, or
+ *  tmct:<3sg lemma> with any preposition camel-appended ("depend on"→tmct:dependsOn). */
+export function predicateOf(verbEntry) {
+  if (verbEntry.predicate) return verbEntry.predicate;
+  const prep = verbEntry.prep ? verbEntry.prep[0].toUpperCase() + verbEntry.prep.slice(1) : "";
+  return `tmct:${thirdPerson(verbEntry.lemma)}${prep}`;
+}
+
+/** Deterministic singular/base-form candidates for a surface word, most
+ *  specific first: as-is, -ies→y, -(s|x|z|ch|sh)es→stem, -s→stem. The FIRST
+ *  candidate found in the relevant map wins ("classes"→class before "classe";
+ *  "uses"→"us" misses, "use" hits). */
+function foldCandidates(word) {
+  const w = String(word);
+  const out = [w];
+  if (w.length > 4 && /[a-z]ies$/.test(w)) out.push(`${w.slice(0, -3)}y`);
+  if (/(ses|xes|zes|ches|shes)$/.test(w)) out.push(w.slice(0, -2));
+  if (/[a-z]s$/.test(w) && !/ss$/.test(w)) out.push(w.slice(0, -1));
+  if (w === "has") out.push("have");
+  return out;
+}
+
+const NOUN_PROPERTY_TYPES = new Set(["data", "object"]);
+const ADJECTIVE_TYPES = new Set(["subclass", "data"]);
+
+/** Merge one raw lexicon block ({nouns, verbs, adjectives, properNames}) into
+ *  the lookup maps, validating the declared typings (bad declarations throw —
+ *  a lexicon that lies would make the grammar guess). */
+function ingest(lex, raw = {}) {
+  for (const [lemma, e] of Object.entries(raw.nouns || {})) {
+    const entry = { lemma, ...(e || {}) };
+    if (entry.property && !NOUN_PROPERTY_TYPES.has(entry.property)) {
+      throw new Error(`lexicon noun "${lemma}": property must be "data" or "object", got ${JSON.stringify(entry.property)}`);
+    }
+    lex.nouns.set(lemma, entry);
+    if (entry.plural) lex.nounPlurals.set(entry.plural, lemma);
+  }
+  for (const [lemma, e] of Object.entries(raw.verbs || {})) {
+    lex.verbs.set(lemma, { lemma, ...(e || {}) });
+  }
+  for (const [lemma, e] of Object.entries(raw.adjectives || {})) {
+    const entry = { lemma, ...(e || {}) };
+    if (!ADJECTIVE_TYPES.has(entry.type)) {
+      throw new Error(`lexicon adjective "${lemma}": type must be "subclass" or "data", got ${JSON.stringify(entry.type)}`);
+    }
+    lex.adjectives.set(lemma, entry);
+  }
+  for (const name of raw.properNames || []) {
+    lex.properNames.set(String(name).toLowerCase(), String(name));
+  }
+}
+
+let coreCache = null;
+
+/** Load the lexicon: the committed core vocabulary, optionally merged with a
+ *  caller-supplied `extra` block of the same JSON shape (extra entries win).
+ *  The no-extra result is cached (the JSON is committed, immutable at runtime). */
+export function loadLexicon(extra) {
+  if (!extra && coreCache) return coreCache;
+  const raw = JSON.parse(readFileSync(CORE_FILE, "utf8"));
+  const lex = {
+    nouns: new Map(),
+    nounPlurals: new Map(),
+    verbs: new Map(),
+    adjectives: new Map(),
+    properNames: new Map(), // lowercased → canonical spelling
+  };
+  ingest(lex, raw);
+  if (extra) {
+    ingest(lex, extra);
+    return lex;
+  }
+  coreCache = lex;
+  return lex;
+}
+
+/** Noun lookup with plural folding; returns the entry ({lemma, property?}) or null. */
+export function lookupNoun(lexicon, word) {
+  const w = String(word ?? "").toLowerCase();
+  const irregular = lexicon.nounPlurals.get(w);
+  if (irregular) return lexicon.nouns.get(irregular) ?? null;
+  for (const cand of foldCandidates(w)) {
+    const hit = lexicon.nouns.get(cand);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Verb lookup with 3sg folding; returns the entry ({lemma, prep?, predicate?}) or null. */
+export function lookupVerb(lexicon, word) {
+  const w = String(word ?? "").toLowerCase();
+  for (const cand of foldCandidates(w)) {
+    const hit = lexicon.verbs.get(cand);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Adjective lookup (exact lemma); returns {lemma, type, property?, value?} or null. */
+export function lookupAdjective(lexicon, word) {
+  return lexicon.adjectives.get(String(word ?? "").toLowerCase()) ?? null;
+}
+
+/** Proper-name lookup, case-insensitive; returns the CANONICAL spelling or null. */
+export function lookupProperName(lexicon, word) {
+  return lexicon.properNames.get(String(word ?? "").toLowerCase()) ?? null;
+}
+
+/** Classify one word (or a two-word quantifier phrase) against the lexicon.
+ *  Returns {pos, type?, …} or null for an undeclared word. Priority when a
+ *  word is declared in several categories (e.g. "test" noun+verb): closed-class
+ *  tokens, then properName > noun > verb > adjective — the grammar itself
+ *  disambiguates by position, this is the standalone answer. */
+export function classify(word, lexicon = loadLexicon()) {
+  const w = String(word ?? "").trim();
+  if (!w) return null;
+  const lower = w.toLowerCase();
+  if (DETERMINERS[lower]) return { pos: "determiner", type: DETERMINERS[lower] };
+  if (QUANTIFIERS[lower]) return { pos: "quantifier", type: QUANTIFIERS[lower] };
+  const n = numberOf(lower);
+  if (n != null) return { pos: "number", type: "cardinal", value: n };
+  const proper = lookupProperName(lexicon, w);
+  if (proper) return { pos: "properName", type: "individual", canonical: proper };
+  const noun = lookupNoun(lexicon, lower);
+  if (noun) {
+    return noun.property
+      ? { pos: "noun", type: `${noun.property}-property`, lemma: noun.lemma, property: noun.property }
+      : { pos: "noun", type: "class", lemma: noun.lemma };
+  }
+  const verb = lookupVerb(lexicon, lower);
+  if (verb) {
+    return { pos: "verb", type: "objectProperty", lemma: verb.lemma, predicate: predicateOf(verb), ...(verb.prep ? { prep: verb.prep } : {}) };
+  }
+  const adj = lookupAdjective(lexicon, lower);
+  if (adj) return { pos: "adjective", type: adj.type, lemma: adj.lemma };
+  return null;
+}

package/src/index.mjs

@@ -5,9 +5,10 @@
 // shape and its green test suite; the branding throughout is now `tmct`.
 //
 // This entry re-exports the adapter primitives a library consumer needs. The
-// clean chat/primitives split — pulling the movable grammar out of ask.mjs away
-// from the core primitives it currently shares a file with — is deferred to
-// ROADMAP.md.
+// clean chat/primitives split (ROADMAP item 13) is done: the movable
+// conversational grammar lives in src/interpret/ (normalization pre-pass, the
+// registered parsing strategies, the merge rule), while ask.mjs keeps the core
+// primitives (resolveObject, traverse, render) and the ask() orchestration.
 
 // Chat surface (also reachable as the `./chat` subpath export).
 export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
@@ -15,11 +16,26 @@ export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
 // Grammar / NL-over-graph primitives.
 export { ask, resolveObject } from "./ask.mjs";
 
+// The interpretation pipeline (ROADMAP item 8): normalize once, run every
+// registered strategy (grammar, keyword-spot, …) over the text, merge same-class
+// results, surround distinct-class results — no graph access; pair it with ask()
+// or the primitives to answer. `interpret(text, ctx)` returns the full record
+// ({raw, normalized, normalizationChanged, results, parsed, class, alternates}).
+export { interpret } from "./interpret/pipeline.mjs";
+
 // Graph traversal primitives.
 export { relationKind, impactClosure } from "./codegraph.mjs";
 
 // Tool dispatch (slash-commands and CLI tool calls route through here).
 export { dispatchTool } from "./server.mjs";
 
-// The single graph-load choke point — the adapter's data-provider seam.
-export { fetchEntities } from "./source.mjs";
+// Conversational memory (ROADMAP item 9) — tmct's OWN OWL-labelled graph under
+// .tmct/memory/, distinct from any provider-supplied code graph.
+export { loadMemory, appendUtterance, appendFact } from "./memory/core.mjs";
+export { retrieveBlocks, saveBlock, rankBlocks } from "./memory/blocks.mjs";
+export { foldSessionLogs } from "./memory/fold.mjs";
+
+// The single graph-load choke point — the adapter's data-provider seam
+// (docs/adapter-contract.md): registerProvider() plugs a producer in;
+// fetchEntities() is the one read path.
+export { fetchEntities, registerProvider } from "./source.mjs";

package/src/interpret/fuzzy.mjs

@@ -0,0 +1,89 @@
+// interpret/fuzzy.mjs — the bounded-edit-distance fuzzy tier (two-level fuzzy,
+// 2026-07-02), extracted MOVE-only from ask.mjs (item 13). A reusable SERVICE the
+// strategies call, not a strategy itself: the keyword-spotting strategy's tier-3
+// vocabulary rewrite and resolveObject's tier-5 label pass both read editDistance/
+// fuzzyBound from here, and the "assuming you meant …" announcement discipline
+// (a unique within-bound hit is announced, a tie is refused or surfaced as
+// ambiguity, never a silently-broken guess) is enforced by the callers off these
+// primitives. Deliberately coupled to the curated vocab tables via explicit
+// imports — the fuzzy TARGETS are a closed, curated set, same ethos as the
+// tables themselves. Pure JS, no deps.
+
+import { VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND } from "../ask-vocab.mjs";
+import { STOPWORDS } from "./normalize.mjs";
+
+// ---- bounded edit distance — hand-rolled Damerau-Levenshtein (optimal string
+// alignment: substitution/insertion/deletion + adjacent transposition), bounded
+// with an early row-minimum exit. Fires only after every exact/curated tier
+// missed, and a distance TIE is refused (keyword) or surfaced as ambiguity
+// (object), never broken by a guess. ----
+
+/** Distance between a and b, or max+1 as soon as it provably exceeds `max`. */
+export function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev2 = null;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    const cur = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) v = Math.min(v, prev2[j - 2] + cost);
+      cur[j] = v;
+      if (v < rowMin) rowMin = v;
+    }
+    if (rowMin > max) return max + 1;
+    prev2 = prev;
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** The curated distance budget: 1 edit for short tokens, 2 for longer ones. */
+export const fuzzyBound = (s) => (s.length <= 5 ? 1 : 2);
+
+/** Every single word appearing in the three parse tables — the "is this word
+ *  already vocabulary?" gate for the lemma/fuzzy canonicalization passes (an
+ *  exact vocab word is NEVER rewritten: exact curated match always wins). */
+export const VOCAB_WORDS = new Set(
+  [...Object.keys(VERB_TO_KIND), ...Object.keys(ENTITY_TO_TYPE), ...Object.keys(MODIFIER_TO_KIND)]
+    .flatMap((p) => p.split(" ")),
+);
+
+/** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only, length ≥4.
+ *  Entity nouns are deliberately excluded — real identifiers collide with them at
+ *  distance ≤2 far too easily ("myfile" is 2 edits from "file", "caller" 2 from
+ *  "calls"-family words), and entity-noun typos are already owned by the curated
+ *  MISSPELLINGS table where such calls are made deliberately. Short constituents
+ *  ("of", "to", "in", "on") are excluded for the same reason: at bound 1 half of
+ *  English is adjacent to them. */
+const FUZZY_TARGET_WORDS = [...new Set(
+  [...Object.keys(VERB_TO_KIND), ...Object.keys(MODIFIER_TO_KIND)]
+    .flatMap((p) => p.split(" "))
+    .filter((w) => w.length >= 4),
+)];
+
+/** A query word may be canonicalized only if it is plain alphabetic, not a
+ *  stopword, and not already vocabulary. Dotted/digit terms (file names, shas)
+ *  are never touched. */
+export function eligibleForCanon(w) {
+  return /^[a-z]+$/.test(w) && !STOPWORDS.has(w) && !VOCAB_WORDS.has(w);
+}
+
+/** UNIQUE within-bound fuzzy vocab keyword for `w`, or null — a tie between two
+ *  distinct target words at the same distance is refused outright (the honest-miss
+ *  discipline at the vocabulary level; cf. MISSPELLINGS' curated "calss" decision). */
+export function fuzzyVocabWord(w) {
+  const bound = fuzzyBound(w);
+  let best = bound + 1;
+  let hit = null;
+  let tied = false;
+  for (const target of FUZZY_TARGET_WORDS) {
+    const d = editDistance(w, target, Math.min(best, bound));
+    if (d < best) { best = d; hit = target; tied = false; }
+    else if (d === best && d <= bound && target !== hit) tied = true;
+  }
+  return best <= bound && !tied ? hit : null;
+}