@polycode-projects/the-mechanical-code-talker 2.3.0 → 2.5.0

package/src/domain/memory/touched-facts.mjs

@@ -0,0 +1,17 @@
+/**
+ * The Fact rows one write touched — created, or re-asserted with a new
+ * provenance entry — diffed by (id → provenance) across a before/after pair of
+ * readFactRows() snapshots.
+ *
+ * Provenance is the key because a re-assertion of a fact that is already stored
+ * changes nothing else about the row: appendFact unions the new provenance in
+ * by id, so a row whose provenance string moved is a row this write reached.
+ *
+ * Not every write produces a touched row, and that is the honest answer rather
+ * than a gap: the rule-teach shapes (compose2/filter/recursive) store a Rule,
+ * not a Fact, so they touch no Fact row and are correctly reported as none.
+ */
+export function touchedFactRows(before, after) {
+  const provenanceBefore = new Map(before.map((r) => [r.id, r.provenance]));
+  return after.filter((r) => provenanceBefore.get(r.id) !== r.provenance);
+}

package/src/domain/module-paths.mjs

@@ -0,0 +1,9 @@
+// module-paths.mjs — classifying a module by its path, for the graph builders and
+// the rankers that read what they build.
+
+/** Does this module path (or a lowercased path-shaped label) belong to test code?
+ *  Covers `test/` and `tests/` segments, Python's `test_*.py` convention, and
+ *  .NET's `*.Tests` assembly suffix. Case-sensitive: callers holding mixed-case
+ *  paths lowercase first. */
+export const isTestPath = (p) =>
+  /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p);

package/src/domain/persona/tiers.mjs

@@ -4,7 +4,7 @@
 //
 // Pure throughout — these read in-memory maps a caller loaded from disk, so
 // they are testable with no WordNet clone present. The loading lives in
-// src/adapters/wordnet-source.mjs, the fact targets and the run itself in
+// scripts/lib/wordnet-source.mjs, the fact targets and the run itself in
 // scripts/build-persona-tiers.mjs.
 
 // human-base's own category roots, plus every hypernym TARGET term Small's

package/src/domain/planning.mjs

@@ -83,3 +83,40 @@ export function findReachableSet(startState, applyActions, { maxDepth = 50, stat
   }
   return results;
 }
+
+/**
+ * Bounded, cycle-safe breadth-first walk that yields one array of newly-visited
+ * successor items per depth level (depths 1..maxDepth), starting from `start`
+ * which is pre-marked visited and never yielded. `successorsOf(id)` returns the
+ * successor items of a node id; `keyOf(item)` is the identity used to dedup and
+ * to seed the next frontier (default: the item itself is its own key).
+ *
+ * Each yielded level is in discovery order; a caller that needs a stable order
+ * sorts it. Empty levels are yielded too (the walk stops once a frontier is
+ * empty), so a caller collecting per-depth batches should skip empty ones.
+ *
+ * @template T
+ * @param {*} start
+ * @param {(id: *) => Iterable<T>} successorsOf
+ * @param {{ maxDepth?: number, keyOf?: (item: T) => * }} [opts]
+ * @returns {Generator<T[]>}
+ */
+export function* bfsLevels(start, successorsOf, { maxDepth = 8, keyOf = (x) => x } = {}) {
+  const visited = new Set([start]);
+  let frontier = [start];
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    const level = [];
+    const nextFrontier = [];
+    for (const id of frontier) {
+      for (const item of successorsOf(id) || []) {
+        const key = keyOf(item);
+        if (visited.has(key)) continue;
+        visited.add(key);
+        level.push(item);
+        nextFrontier.push(key);
+      }
+    }
+    frontier = nextFrontier;
+    yield level;
+  }
+}

package/src/domain/prose.mjs

@@ -4,8 +4,6 @@
 // `prose_tokens` attribute (self-describing) and inverted into
 // `entities.proseIndex` (word -> ids) for O(1) lookup.
 
-// Exported so src/domain/completions/group.mjs can filter splitIdentifierWords'
-// output (which doesn't apply this list itself) down to real content words.
 export const STOPWORDS = new Set(
   ("a an and or but the of to in on at for with from by as is are was were be been being " +
     "it its this that these those i you he she they we me my your our do does did not no " +
@@ -57,6 +55,16 @@ export function proseTokensFor({ name, doc } = {}) {
   return [...set].sort();
 }
 
+/** A real content word: plain alphanumerics, no stopword. Tokenizers that re-admit
+ *  stopwords (splitIdentifierWords, tokenizeBlock) narrow their output through this —
+ *  unfiltered, shared stopwords alone would relate or cluster almost any two texts. */
+export const isContentToken = (t) => /^[a-z0-9]+$/.test(t) && !STOPWORDS.has(t);
+
+/** Wrap a block tokenizer so it yields only content tokens. */
+export function makeContentTokens(tokenizeBlock) {
+  return (text) => tokenizeBlock(text).filter(isContentToken);
+}
+
 /** Attach a `prose_tokens` attribute to every individual, from its (decomposed)
  *  name and captured doc text — except Commit, whose `label` is a truncated
  *  SHA, not a decomposable identifier: it tokenizes `message` instead. Mutates

package/src/domain/relative-specifiers.mjs

@@ -0,0 +1,12 @@
+// The relative import/export specifiers in a module's source text, unique and
+// in first-seen order. Relative only: bare specifiers (wink-nlp) and node
+// builtins are somebody else's concern — an import map, a shim. Covers the
+// three forms a specifier arrives in: after a from keyword (static import and
+// re-export), a dynamic import call, and a bare side-effect import.
+const RELATIVE_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)["'](\.[^"']*)["']/g;
+
+export function relativeSpecifiers(text) {
+  const specs = new Set();
+  for (const [, specifier] of text.matchAll(RELATIVE_SPECIFIER)) specs.add(specifier);
+  return [...specs];
+}

package/src/domain/router/registry.mjs

@@ -11,6 +11,7 @@
 
 const PREFIXES = Object.freeze({
   cap: "urn:tmct:cap#", // the capability/operator vocabulary (this module)
+  taught: "urn:tmct:taught#", // taught-action operators + their world-state predicates (taught.mjs)
   mgx: "urn:tmct:mgx#", // tmct's code-graph predicates (imports/calls/tests/…)
   seon: "http://se-on.org/ontologies/seon.owl#", // software-evolution ontology classes
 });
@@ -28,8 +29,8 @@ export const VOCAB = Object.freeze({
 // name a graph entity the resolver must prove RESOLVES before the call fires.
 export const KINDS = Object.freeze({
   Symbol: "seon:CodeEntity", // any code symbol: function/method/class/module/attribute
-  Module: "seon:Module",
-  Class: "seon:ClassDefinition",
+  Module: "mgx:Module", // SEON has no JS-module class (its nearest are Namespace/main:File); owned
+  Class: "seon:ClassType", // SEON's real class for a class definition
   Query: "cap:FreeText", // lexical search string — no resolution precondition
   Kind: "cap:KindFilter", // enum: function|class|method|… (search filter)
   Package: "cap:PackageName", // optional architecture-scope filter

package/src/domain/router/results.mjs

@@ -27,11 +27,9 @@
 // dispatchTool render* functions edge-for-edge.
 
 import { impactClosure, edgesOfKind, siteOf } from "../codegraph.mjs";
+import { bfsLevels } from "../planning.mjs";
 import { uniqSort } from "./set-algebra.mjs";
-
-// A test-path label, mirroring codegraph.mjs's private isTestLabel (untested view).
-const isTestLabel = (s) =>
-  /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
+import { isTestPath } from "../module-paths.mjs";
 
 /** The module id an individual belongs to — a Module is itself; a fine symbol maps
  *  through its site span (`mod:<path>`), else an `fn:<path>#name` id. Mirrors the
@@ -56,7 +54,7 @@ export function untestedModules(graph) {
     graph.individuals
       .filter((i) => (i.class || "") === "Module"
         && !testModules.has(i.id)
-        && !isTestLabel(String(i.label).toLowerCase())
+        && !isTestPath(String(i.label).toLowerCase())
         && !covered.has(i.id))
       .map((i) => i.label),
   );
@@ -165,19 +163,8 @@ function subclassesLabels(graph, ind) {
     childrenOf.get(e.object).push({ id: e.subject, label: e.subjectLabel || e.subject });
   }
   const labels = [];
-  const visited = new Set([ind.id]);
-  let frontier = [ind.id];
-  for (let depth = 1; depth <= 8 && frontier.length; depth += 1) {
-    const next = [];
-    for (const id of frontier) {
-      for (const c of childrenOf.get(id) || []) {
-        if (visited.has(c.id)) continue;
-        visited.add(c.id);
-        labels.push(c.label);
-        next.push(c.id);
-      }
-    }
-    frontier = next;
+  for (const level of bfsLevels(ind.id, (id) => childrenOf.get(id) || [], { maxDepth: 8, keyOf: (c) => c.id })) {
+    for (const c of level) labels.push(c.label);
   }
   return uniqSort(labels);
 }

package/src/domain/seeded-random.mjs

@@ -0,0 +1,33 @@
+// seeded-random.mjs — the single home for tmct's seedable, platform-stable
+// pseudo-randomness: a mulberry32 generator and a Fisher-Yates shuffle driven by
+// it. Both are pure arithmetic (no I/O, no imports), so a seed reproduces the
+// same sequence on every machine and every run.
+//
+// The bench case generators (infbench, chatbench's graded pool) draw their
+// committed fixtures through these, so the byte sequence they produce is part of
+// those artifacts' identity: two callers on one seed must shuffle identically or
+// the committed cases.jsonl / graded pool drift. That is the same reason the
+// content-address hashes live once in hash.mjs beside this file — a deterministic
+// primitive shared across writers has exactly one definition.
+
+/** mulberry32 PRNG — small, seedable, deterministic across platforms. */
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Fisher-Yates over a copy, driven by the supplied rng. */
+export function seededShuffle(arr, rng) {
+  const out = [...arr];
+  for (let i = out.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rng() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}

package/src/domain/syllogise.mjs

@@ -1,7 +1,7 @@
 // syllogise.mjs — tmct's speculative-inference engine, growing toward
 // tier-5 "the Syllogist". Offline, deterministic: forward-chains entailments
 // over the OWL-labelled memory graph so a future query-time MISS becomes a
-// lookup. `syllogise()` (the materializing pass) only runs as the explicit
+// lookup. `syllogise()` (the materialising pass) only runs as the explicit
 // `npx tmct syllogise` batch job; the pure kernels below may also be reused
 // for a small, bounded, read-only live check without writing anything.
 //
@@ -61,7 +61,7 @@ export const ENTAILED_DISJOINT_PROVENANCE = `entailed:${CAX_DW_RULE}`;
 export const CAX_DW_RULE_CONFIDENCE = 0.95;
 
 /** cls-svf1: x P y, y rdf:type C2, R owl:onProperty P, R owl:someValuesFrom
- *  C2 |= x rdf:type R (OWL 2 RL Table 8). `owl:onProperty`'s stored value and
+ *  C2 |= x rdf:type R (OWL 2 RL Table 6). `owl:onProperty`'s stored value and
  *  a taught property edge's predicate differ in casing (normFactTerm'd vs.
  *  raw vocabulary spelling), so the kernel below normalizes both before
  *  comparing. */
@@ -311,7 +311,7 @@ export function deriveDisjointViolations(typeEdges, subClassEdges, disjointEdges
 
 /**
  * PURE cls-svf1: x P y, y rdf:type C2, R owl:onProperty P, R
- * owl:someValuesFrom C2 |= x rdf:type R (OWL 2 RL Table 8). `propertyEdges`
+ * owl:someValuesFrom C2 |= x rdf:type R (OWL 2 RL Table 6). `propertyEdges`
  * is every taught/prior-entailed object-property assertion (raw predicate
  * spelling); `restrictionEdges` is each restriction node's (property, target)
  * declaration. `y`'s type is lifted through its full ⊑-ancestor closure, so
@@ -659,7 +659,7 @@ export function findConsistencyViolations(typeEdges, subClassEdges, disjointEdge
  * Run one bounded speculative pass over the memory graph under `repoDir`.
  * Forward-chains the five rules in order — scm-sco, cax-sco, cax-dw,
  * cls-svf1, scm-svf1 — each seeing the prior rules' conclusions from this
- * same pass, and materializes each new conclusion via `appendFacts` with its
+ * same pass, and materialises each new conclusion via `appendFacts` with its
  * `entailed:*` provenance. Trust rides the entailed hook
  * (`min(premiseTrusts) x ruleConfidence`) when premises are resolvable in the
  * pre-pass snapshot, else falls back to the bare entailed prior.
@@ -764,7 +764,7 @@ export async function syllogise(repoDir, { depth = 32, budget = 50, focus = null
       subject: d.subject, predicate: TYPE_PREDICATE, object: d.object,
       provenance: ENTAILED_TYPE_PROVENANCE,
       // The ⊑ premise is cited as the DIRECT via⊑object edge even when the
-      // taught chain is multi-hop: scm-sco materializes that edge (this same
+      // taught chain is multi-hop: scm-sco materialises that edge (this same
       // pass or an earlier one), and retraction re-VERIFIES every candidate
       // anyway, so a citation left dangling by budget truncation is inert.
       justification: [
@@ -969,14 +969,17 @@ function buildSurvivorDerivabilityCheck(rows) {
 }
 
 /**
- * A scoped retraction slice: JTMS-style dependency-directed removal.
+ * A scoped retraction slice: DRed (delete-and-rederive; Gupta, Mumick &
+ * Subrahmanian, SIGMOD 1993), NOT JTMS. It recomputes the MATERIALISATION —
+ * where a JTMS would recompute belief labels — so a store that moves rows is
+ * DRed by construction.
  * Retracting `subject ⊑ object` removes the fact, then cascades to any
  * purely-entailed fact — across all five rules' conclusions — whose persisted
  * justification cites a removed id. Each candidate is VERIFIED (re-derivable
  * from the surviving facts, not just "cited a removed id") before it is
  * actually removed, since a fact can have a second, independent derivation
  * path (a⊑b⊑d AND a⊑c⊑d both license a⊑d) that a bare delete-by-justification
- * walk would wrongly discard. Repeats in rounds — a removed mid-chain link
+ * walk would wrongly discard. This over-delete-then-re-verify IS DRed's shape. Repeats in rounds — a removed mid-chain link
  * can ripple — bounded by `budget` (max facts examined+removed) and `depth`
  * (max cascade rounds).
  *

package/src/domain/text-stats.mjs

@@ -0,0 +1,31 @@
+// text-stats.mjs — pure token-frequency statistics shared by the ranking tiers.
+// Deterministic, no model calls. The IDF weight log(1 + N/(1+df)) is near-zero
+// for tokens present in almost every document and grows for rare ones.
+
+/**
+ * Inverse-document-frequency weight for a token seen in `df` of `N` documents.
+ * @param {number} N   document count
+ * @param {number} df  document frequency of the token
+ * @returns {number}
+ */
+export function idfWeight(N, df) {
+  return Math.log(1 + N / (1 + df));
+}
+
+/**
+ * IDF over a document set given as an `id -> tokens` map. Document frequency
+ * counts each document once per distinct token; N is the document count.
+ *
+ * @param {Record<string, string[]>} idsToTokens
+ * @returns {{ N: number, df: Map<string, number>, idf: (t: string) => number }}
+ */
+export function idfOver(idsToTokens) {
+  const ids = Object.keys(idsToTokens || {});
+  const N = ids.length;
+  const df = new Map();
+  for (const id of ids) {
+    for (const t of new Set(idsToTokens[id])) df.set(t, (df.get(t) || 0) + 1);
+  }
+  const idf = (t) => idfWeight(N, df.get(t) || 0);
+  return { N, df, idf };
+}