@polycode-projects/the-mechanical-code-talker 0.9.12 → 1.0.1

package/src/concept.mjs

@@ -249,6 +249,14 @@ export const RELATION_TERM = Object.freeze({
   define: "defines", defines: "defines", defining: "defines", defined: "defines", definition: "defines", definitions: "defines", declaration: "defines",
   touch: "touches", touches: "touches", touching: "touches", touched: "touches",
   cochange: "cochange", "co-change": "cochange", "change-coupling": "cochange", coupled: "cochange",
+  // "export"/"exports" is ALSO a curated seon lexicon noun (corpus/seon/definitions.jsonl
+  // "export"), same shape as "imports" — but that meta reading only owns the "what
+  // does export mean"/"what is an export" shape; vagueTouchTermOf/relationTermOf are
+  // deliberately scoped to the NON-meta "what about X"/"tell me about X" touch (see
+  // relationTermOf's own docblock, frozen case am-meta-imports), so no conflict here.
+  export: "reexports", exports: "reexports", exporting: "reexports", exported: "reexports",
+  reexport: "reexports", reexports: "reexports", reexporting: "reexports",
+  "re-export": "reexports", "re-exports": "reexports", "re-exporting": "reexports",
 });
 
 /** concept key → the relationKind()s whose edges it enumerates. A concept can span
@@ -263,6 +271,7 @@ const RELATION_KINDS = Object.freeze({
   defines: ["defines"],
   touches: ["touches", "touchesSymbol"],
   cochange: ["cochange"],
+  reexports: ["reexports"],
 });
 
 /** concept key → the verb phrase that renders an edge as an English sentence
@@ -276,6 +285,7 @@ const RELATION_RENDER = Object.freeze({
   defines: { verb: "defines", edgeNoun: "definition" },
   touches: { verb: "touches", edgeNoun: "touch" },
   cochange: { verb: "changes together with", edgeNoun: "change-coupling" },
+  reexports: { verb: "re-exports", edgeNoun: "re-export" },
 });
 
 /** Per concept key, the candidate follow-up shapes in priority order. Each shape
@@ -316,6 +326,10 @@ const RELATION_FOLLOWUP_SHAPES = Object.freeze({
     { side: "obj", make: (x) => `where is ${x} defined` },
     { side: "subj", make: (x) => `which modules import ${x}` },
   ],
+  reexports: [
+    { side: "subj", make: (x) => `what does ${x} export` },
+    { side: "obj", make: (x) => `where is ${x} defined` },
+  ],
 });
 
 /** How many example edges the relation force shows before the remainder is held for
@@ -347,12 +361,24 @@ function buildRelationFollowups(graph, key, subjLabels, objLabels) {
 }
 
 /** Compose the three bands for a RELATION concept term, or null when it is NOT a
- *  relation-force case — the term is not a known enumerable relation, has no curated
- *  definition, or the graph has NO edges of that kind (honest miss stands, never a
- *  fabricated edge). Returns the same string-band shape composeConcept does:
+ *  relation-force case at all — the term is not a known enumerable relation, or has no
+ *  curated definition. Returns the same string-band shape composeConcept does:
  *    { definition, examples, followups, followupQueries, remainder, noun }
- *  `examples` is always non-empty when non-null (we only fire with real edges);
- *  `followups` is "" when no validated next-question exists. */
+ *  `examples` is always non-empty when non-null; `followups` is "" when no validated
+ *  next-question exists.
+ *
+ *  A known relation whose graph has ZERO edges of that kind is NOT null — it degrades
+ *  to a two-band answer (the definition + an explicit "this codebase has no X edges"
+ *  line, `examples`-shaped so the caller renders it identically). Found live (an
+ *  advisor tick on the 0.9.14 Tier-2 playtest cycle): returning null here for the
+ *  zero-edge case let the caller's OWN raw grammar attempt at the vague-touch text
+ *  ("what about exports", "tell me about reexports") stand instead — but that text was
+ *  never meant to be parsed as an object search, so on a graph with no reexports edges
+ *  (the realistic case for most repos, e.g. examples/mini-webapp) it fell through to a
+ *  garbled `no module matching "about"/"exports" found`, not an honest miss. A relation
+ *  kind the graph has NEVER SEEN AT ALL (relationKind returns nothing in RELATION_KINDS
+ *  for this graph's shape) still degrades the same way — the definition is always
+ *  worth stating; only the fabricated edge is refused. */
 export function composeRelation(graph, relTerm, { definition = null } = {}) {
   const key = RELATION_TERM[String(relTerm || "").toLowerCase()];
   if (!key || !definition) return null;
@@ -360,14 +386,29 @@ export function composeRelation(graph, relTerm, { definition = null } = {}) {
   const groups = (graph && Array.isArray(graph.relations) ? graph.relations : [])
     .filter((g) => kinds.includes(relationKind(g)));
   const edges = groups.flatMap((g) => (Array.isArray(g.edges) ? g.edges : []));
-  if (!edges.length) return null; // no edges of this kind → honest miss stands
-  const total = groups.reduce((s, g) => s + (Number(g.count) || (g.edges || []).length), 0);
-
   const { verb, edgeNoun } = RELATION_RENDER[key] || { verb: key, edgeNoun: key };
 
-  // BAND 1 — the fact (the relation defined as a verb/relationship).
+  // BAND 1 — the fact (the relation defined as a verb/relationship). Stated
+  // regardless of whether the graph has any edges of this kind — only the
+  // fabricated EXAMPLE is refused when there are none.
   const bandDefinition = leadSentence(definition);
 
+  if (!edges.length) {
+    // No fabricated edge, but an honest, ON-TOPIC miss — never the caller's raw,
+    // unrelated object-search text.
+    return {
+      definition: bandDefinition,
+      examples: `This codebase has no ${edgeNoun} edges in the index.`,
+      followups: "",
+      followupQueries: [],
+      relation: key,
+      remainder: [],
+      noun: `${edgeNoun} edges`,
+      empty: true,
+    };
+  }
+  const total = groups.reduce((s, g) => s + (Number(g.count) || (g.edges || []).length), 0);
+
   // BAND 2 — the example edges, rendered as English sentences with a count. The
   // first MAX_EDGE_EXAMPLES are shown; the remainder is held for "more" pagination.
   const rendered = edges.map((e) => `${edgeSubjectLabel(e)} ${verb} ${edgeObjectLabel(e)}`);

package/src/finish.mjs

@@ -222,7 +222,7 @@ function leadingWord(text) {
 
 /** Does `word` begin with a VOWEL SOUND? true → "an", false → "a", null → cannot
  *  tell (refuse). Spelling-vs-sound exceptions come from the rule's TOML row. */
-function beginsWithVowelSound(word, rule) {
+export function beginsWithVowelSound(word, rule) {
   const w = String(word).toLowerCase().replace(/^[^a-z]+/, "");
   if (!w) return null;
   for (const ex of rule.vowel_sound_consonants || []) if (w.startsWith(ex)) return true;

package/src/interpret/normalize.mjs

@@ -44,6 +44,19 @@ const correctionRe = (table) => new RegExp(
 const MISSPELLING_RE = correctionRe(MISSPELLINGS);
 const WRONG_WORD_RE = correctionRe(WRONG_WORDS);
 
+/** Just the curated MISSPELLINGS correction (ask-vocab.mjs), standalone — for a
+ *  caller that needs typo-tolerant ANCHOR-WORD matching (a closed regex shape
+ *  keyed on a literal "what"/"which"/"where" etc.) without running the rest of
+ *  normalizeQuery's pipeline (contractions, preamble/subordination/conditional
+ *  frame rewrites, filler-word stripping) — those can restructure the sentence
+ *  in ways a shape-matcher never expects (0.9.14 Tier-2 playtest: normalizeQuery
+ *  turns "tell me about Controller" into "about Controller", which would break
+ *  chat.mjs's OWN "^tell me about …" shape regex if fed through wholesale). Pure,
+ *  idempotent, same table as normalizeQuery's own first correction step. */
+export function correctMisspellings(text) {
+  return String(text || "").replace(MISSPELLING_RE, (m) => MISSPELLINGS[m.toLowerCase()]);
+}
+
 // ---- closed PREAMBLE frames (0.8.2 feel wave, PLAN_CHAT_FEEL item 2) — the
 // conversational wrapping a developer puts AROUND a real question: a greeting
 // lead-in with a delimiter ("hey there, quick question - …"), a thanks lead-in
@@ -88,7 +101,25 @@ const isListingRemainder = (rest) => {
  *  remainder are REQUIRED, so a bare "hey there" stays a greeting for chat's
  *  conversational lane, and "hey tmct, …" (a vocative, no delimiter after the
  *  greeting word) is left for the noise-strip tier that already owns it. */
-const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy)(?:\s+there)?\s*[,—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
+// "g'day"/"gday" (AU/NZ dialect, §3b): the same lead-in-with-delimiter shape as
+// hi/hey/howdy — 0.9.14 Tier-2 playtest §3b spot-check found "g'day, what does
+// Base contain" fell through to a bogus "'g'day Base' matches more than one
+// module" object search instead of stripping the greeting.
+// "good morning"/"good afternoon"/"good evening"/"good day"/"greetings"/
+// "salutations" (formal register, §3b) — chat.mjs's own bare-turn GREETINGS/
+// IDENTITY_PHRASES closed sets already recognize these exact phrases stand-
+// alone, but this LEAD-IN regex (a greeting fused onto a real question in the
+// same turn) didn't carry the multi-word formal forms at all: a second Tier-2
+// playtest pass (0.9.14) found "Good day, what is a method" hit the grammar
+// wall outright, and "Good morning, what about tests" fell through to a bogus
+// "no module matching 'Good morning' found" object search — the exact same
+// failure g'day had before its own fix, just for the formal register instead
+// of the AU/NZ dialect. Formal register also plausibly types the lead-in as
+// its OWN full sentence ("Good day. What is a method?") rather than a comma
+// splice — "." joins the delimiter class for exactly this reason; a bare
+// greeting alone ("hi.") still can't match since the regex also requires a
+// non-empty remainder AFTER the delimiter.
+const GREETING_PREAMBLE_RE = /^(?:hi|hiya|hello|hey|yo|howdy|g'?day|good\s+(?:morning|afternoon|evening|day)|greetings|salutations)(?:\s+there)?\s*[,.—–-]\s*(?:(?:just\s+a\s+)?quick\s+question\s*[,:—–-]?\s*)?(.+)$/i;
 /** Thanks lead-in with a delimiter (+ optional "quick question" bridge), the
  *  sibling of GREETING_PREAMBLE_RE for the "thanks" word family (Bug B2, 0.8.2
  *  follow-up): "thanks, <Q>" / "thanks so much, <Q>" -> "<Q>". chat.mjs's
@@ -107,6 +138,17 @@ const THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(
  *  passes, so "can you tell me a joke" -> "tell me a joke" -> (FILLER) "a joke"
  *  — byte-identical to what the bare form normalizes to (the hm-joke wall). */
 const MODAL_WRAPPER_RE = /^(?:can|could|would|will)\s+you\s+(?:please\s+)?(.+?)(?:[,\s]+please)?\??$/i;
+/** "explain" politeness/ESL wrapper: "explain [to me|please]* <Q>" -> "<Q>"
+ *  (0.9.13 Tier-1 playtest, §3b surface-variation axis) — a formal/ESL lead-in
+ *  around an ordinary structural question ("explain please where is it
+ *  defined") used to leave "explain"/"please" as noise words that corrupted the
+ *  object term into a bogus search ("no module matching 'explain it' found").
+ *  Anchored to an INTERROGATIVE remainder (same guard as the show/give-me
+ *  bridge below) so this frame only unwraps a real WH-question underneath —
+ *  chat.mjs's own IDENTITY_PHRASES ("explain what is this") and the bare
+ *  "explain" elaboration request (WHY set) are matched on the RAW turn text
+ *  before normalizeQuery ever runs, so neither is touched by this frame. */
+const EXPLAIN_WRAPPER_RE = /^explain\s+(?:to\s+me\s+|please\s+)*(.+?)\??$/i;
 /** show/give-me presentation bridge: "show me [the] <thing>". Three-way:
  *  a KIND-listing remainder is left untouched (the compositional list grammar
  *  owns "show me untested modules"); a remainder carrying a relation verb or an
@@ -129,6 +171,8 @@ export function applyPreambleFrames(text) {
     if (m) q = m[1].trim();
     m = q.match(MODAL_WRAPPER_RE);
     if (m) q = m[1].trim();
+    m = q.match(EXPLAIN_WRAPPER_RE);
+    if (m && INTERROGATIVE_LEAD_RE.test(m[1].trim())) q = m[1].trim();
     m = q.match(SHOW_GIVE_ME_RE);
     if (m) {
       const rest = m[1].trim();
@@ -192,6 +236,36 @@ export function applySubordinationFrames(text) {
   return q;
 }
 
+// ---- SELF-CORRECTION (found live, playtest sprint round 5, HANDOVER item 12.1): a
+// mid-sentence false start, abandoned and restarted — "what -- sorry, who inherits
+// from Record", "what is a class -- i mean, what is a module". Same species as the
+// preamble/subordination frames above (closed, delimiter-anchored, first-match-wins,
+// unmatched text passes through byte-unchanged), sized for a false-start clause
+// instead of a leading wrapper clause. The delimiter is the marker phrase "sorry" or
+// "i mean" — REQUIRED, with an optional interruption dash ("--"/"—"/"-") in front of
+// it and a required trailing separator (dash/comma/colon) after it. Deliberately does
+// NOT match on a bare dash alone with no marker word: an ordinary em-dash aside
+// ("modules — like Base — that inherit from X") is common prose, not a restart, and
+// treating every dash as a delimiter would be a guess this file's discipline forbids
+// everywhere else. ----
+const SELF_CORRECTION_RE =
+  /^.+?(?:\s*(?:--|—|-)\s*)?\b(?:sorry|i\s+mean)\b\s*(?:--|—|-|,|:)\s*(.+)$/i;
+
+/** Apply the self-correction strip to a small fixpoint (a stacked restart —
+ *  "what -- sorry, who -- sorry, what inherits from Record" — peels to the final
+ *  restart). Pure; unmatched text passes through byte-unchanged. */
+export function applySelfCorrectionFrames(text) {
+  let q = String(text || "");
+  for (let pass = 0; pass < 3; pass++) {
+    const m = q.match(SELF_CORRECTION_RE);
+    if (!m) break;
+    const next = m[1].trim();
+    if (!next || next === q) break;
+    q = next;
+  }
+  return q;
+}
+
 /** relation-verb (bare 3rd-person singular, the RELATIONS table's own primary
  *  form) -> gerund, the shape the compositional grammar's proven
  *  "<kind> <gerund> <object> and <qualifier>" pattern needs. A small, closed,
@@ -274,6 +348,12 @@ export function normalizeQuery(text) {
   // bridge) — AFTER the correction tables (a repaired "give me"/"show me" still
   // feeds the bridge) but BEFORE the filler strip erases their anchor words.
   q = applyPreambleFrames(q);
+  // self-correction (strip an abandoned false-start clause) BEFORE subordination/
+  // conditional: a false start can itself look like the OPENING of a subordination
+  // clause ("since -- sorry, which modules import X" — "since" would otherwise be
+  // read as SUBORDINATION_FRAMES_RE's own anchor), so peeling the restart first
+  // means the real remainder is all either frame ever sees.
+  q = applySelfCorrectionFrames(q);
   // subordination (strip a leading framing clause) THEN conditional (compile
   // "if …" to an existing working shape) — subordination first so a stacked
   // "since we're refactoring, if a module imports X, is it tested" peels its
@@ -342,6 +422,15 @@ export const PHRASING_FRAMES = Object.freeze([
   { re: /^what\s+(?:defined|declared)\s+(?:the\s+)?(?:function\s+|method\s+|class\s+|module\s+|variable\s+|constant\s+)?(.+?)\??$/i, to: (m) => `where is ${m[1]} defined` },
   //   "where's X defined" (the "where's" contraction is not in the contraction table)
   { re: /^where'?s\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
+  //   "were is X defined" (0.9.13 Tier-1 playtest: the missing-h typo of "where").
+  //   NOT curated as a blanket MISSPELLINGS entry — "were" is a real word already
+  //   load-bearing as the TEMPORAL_AUX auxiliary ("when were the modules last
+  //   touched"), so a global word-boundary rewrite would clobber that reading.
+  //   This frame is anchored to the WHERE-DEFINED shape specifically ("were is
+  //   … defined/declared/located/implemented"), a construction no legitimate
+  //   temporal query produces ("were" as an auxiliary never leads directly into
+  //   a bare "is").
+  { re: /^were\s+is\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
 
   // PREDICATIVE QUALIFIER → the ATTRIBUTIVE form the grammar already answers. The
   // adjective-qualifier post-filters (ask-vocab.mjs QUALIFIERS: tested/untested,

package/src/memory/core.mjs

@@ -74,6 +74,7 @@ const MEMORY_VOCABULARY = [
   { prop: "rdf:predicate", note: "reified fact: the triple's predicate term" },
   { prop: "rdf:object", note: "reified fact: the triple's object term" },
   { prop: "mgx:factProvenance", note: "LEGACY COMPAT SHIM: the ' | '-joined provenance tag string a fact came from; the source-of-truth is now the mgx:statedBy edges derived from it" },
+  { prop: "mgx:factQuantifier", note: "OPTIONAL: the quantifier word a plural class-membership teach used ('every'/'some'/'a few'), for literal recall by 'how many Xs are Ys' — never real cardinality counting" },
   { prop: CREATED_AT_PROP, note: "when an individual was FIRST written, ISO-8601 (first-write-wins on upsert); the audit 'when', the recency input to trust, the novelty signal" },
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
@@ -444,7 +445,7 @@ const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
  *  carrying rdf:subject / rdf:predicate / rdf:object (+ provenance). The
  *  Phase-2 ACE parser's write point. Same (s,p,o) → same id → upsert, never a
  *  duplicate. Returns { id }. */
-export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "" } = {}) {
+export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "", quantifier = "" } = {}) {
   const s = normFactTerm(subject);
   const p = normText(predicate);
   const o = normFactTerm(object);
@@ -452,6 +453,7 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
   const id = `fact:${fnv1aHex(`${s}${p}${o}`)}`;
   const text = `${s} ${p} ${o}`;
   const tokens = proseTokensFor({ doc: text });
+  const q = normText(quantifier);
   await mutateMemory(dir, (payload) => {
     const prior = payload.individuals.find((x) => x?.id === id);
     const priorProv = prior?.attributes?.find((a) => a?.prop === "mgx:factProvenance")?.value || "";
@@ -459,6 +461,10 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
     // still key on); the Source edges below are DERIVED from it, purely additive.
     const provs = [...new Set([...priorProv.split(" | "), normText(provenance)].filter(Boolean))];
     const createdAtVal = firstWriteCreatedAt(prior, createdAt); // first-write-wins
+    // first-write-wins for the quantifier too (a re-assert with none, e.g. a
+    // plain re-teach, never SILENTLY erases an already-recorded quantifier).
+    const priorQ = prior?.attributes?.find((a) => a?.prop === "mgx:factQuantifier")?.value || "";
+    const qVal = q || priorQ;
     upsertIndividual(payload, {
       id, label: labelOf(text), class: FACT_CLASS,
       derived_from: [], mentions: [],
@@ -470,6 +476,7 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
         { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
         ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
         ...(tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }] : []),
+        ...(qVal ? [{ prop: "mgx:factQuantifier", key: "quantifier", value: qVal }] : []),
       ],
     });
     // Derive Source individuals + statedBy edges from the provenance union and
@@ -512,6 +519,7 @@ export async function appendFacts(dir, facts) {
       tokens: proseTokensFor({ doc: text }),
       provenance: normText(f?.provenance),
       createdAt: f?.createdAt || "",
+      quantifier: normText(f?.quantifier),
     });
   }
   const ids = [];
@@ -528,6 +536,9 @@ export async function appendFacts(dir, facts) {
       // compat shim); the Source edges below are DERIVED from it, purely additive.
       const provs = [...new Set([...priorProv.split(" | "), f.provenance].filter(Boolean))];
       const createdAtVal = firstWriteCreatedAt(prior, f.createdAt); // first-write-wins
+      // first-write-wins for the quantifier too — same discipline as appendFact.
+      const priorQ = prior?.attributes?.find((a) => a?.prop === "mgx:factQuantifier")?.value || "";
+      const qVal = f.quantifier || priorQ;
       const ind = {
         id: f.id, label: labelOf(f.text), class: FACT_CLASS,
         derived_from: [], mentions: [],
@@ -539,6 +550,7 @@ export async function appendFacts(dir, facts) {
           { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
           ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
           ...(f.tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: f.tokens.join(" ") }] : []),
+          ...(qVal ? [{ prop: "mgx:factQuantifier", key: "quantifier", value: qVal }] : []),
         ],
       };
       // Upsert into BOTH the array (replace-in-place keeps order) and the index.
@@ -588,6 +600,7 @@ export function readFactRows(memory) {
       id: ind.id,
       subject: get("subject"), predicate: get("predicate"), object: get("object"),
       provenance: get("provenance"), // legacy compat string, verbatim
+      quantifier: get("quantifier"), // "" unless a plural class-membership teach set one (Feature A pt.3)
       sourceIds, sourceTypes,
       trust: Number((ind.attributes || []).find((a) => a?.prop === TRUST_SCORE_PROP)?.value) || 0,
     });