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

package/src/index.mjs

@@ -0,0 +1,25 @@
+// @polycode-projects/the-mechanical-code-talker (tmct) — library entry point.
+//
+// tmct began as a whole-package lift of an earlier chat surface (see README
+// provenance). Internal module filenames and symbols were kept to preserve the
+// 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.
+
+// Chat surface (also reachable as the `./chat` subpath export).
+export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
+
+// Grammar / NL-over-graph primitives.
+export { ask, resolveObject } from "./ask.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";

package/src/prose-nlp.mjs

@@ -0,0 +1,52 @@
+// prose-nlp.mjs — the OPTIONAL wink-nlp lemma loader behind prose.mjs's LEMMA layer.
+//
+// Deliberately a SEPARATE loader from ask-nlp.mjs (same createRequire pattern, same
+// deps) rather than an import of it: ask-nlp.mjs belongs to the ask-engine surface
+// and is under active concurrent work — the prose pre-pass must not couple its
+// index-build path to that file's export shape. The ~20 duplicated lines are the
+// decoupling fee; the wink model itself is loaded lazily and at most once per
+// process either way.
+//
+// BOUNDARY (same as ask-nlp.mjs, hard): Node-only, never inlined into the viewer
+// bundle. prose.mjs is itself never inlined by viz.mjs's askSource(), so nothing
+// browser-side can reach this module. wink-nlp + wink-eng-lite-web-model are CJS —
+// loaded via createRequire, lazily, with failure cached as null: a checkout without
+// the optional deps simply builds no lemma layer (honestly absent), it never throws.
+//
+// Determinism: wink's lemmatiser is a fixed trained model with no sampling — the
+// same token always yields the same lemma across runs and processes, which is what
+// lets the lemma layer meet the "byte-identical proseIndex across builds" contract.
+
+import { createRequire } from "node:module";
+
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Lazily build a `lemma(word) -> string` function, or null when wink isn't loadable.
+ *  Results are memoized per token: the layer build lemmatises each unique vocabulary
+ *  token once, not once per posting. */
+export function proseLemma() {
+  if (cached !== undefined) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    const winkNLP = require("wink-nlp");
+    const model = require("wink-eng-lite-web-model");
+    const nlp = winkNLP(model);
+    const its = nlp.its;
+    const memo = new Map();
+    cached = (word) => {
+      const w = String(word || "");
+      if (memo.has(w)) return memo.get(w);
+      let out;
+      try {
+        out = String(nlp.readDoc(w).tokens().out(its.lemma)[0] || w).toLowerCase();
+      } catch {
+        out = w.toLowerCase();
+      }
+      memo.set(w, out);
+      return out;
+    };
+  } catch {
+    cached = null;
+  }
+  return cached;
+}

package/src/prose.mjs

@@ -0,0 +1,187 @@
+// prose.mjs — the second-pass prose extraction + cross-reference index (PLAN_PROSE_INDEX.md).
+//
+// Deterministic, zero-model-calls, zero dependencies: pure string transforms + a plain-object
+// inverted index over data graph-build.mjs's typed pass has already produced (identifier names,
+// captured doc text). Two token sources, one combined set per individual:
+//   1. identifier decomposition — names are often literal sentence fragments
+//      ("calculateTotalPriceIncludingTax" -> calculate/total/price/including/tax); splitting
+//      them turns every symbol/module name into free-text search surface for zero extra cost.
+//   2. prose literals — docstrings/doc-comments already captured as the `doc` attribute.
+//      Python (extract_ast.py) and JS/TS (jsts_tsc.mjs's firstDocLine) already populate this;
+//      C#/Java's PRIMARY extractors (cs_roslyn.mjs, java_javaparser.mjs) shell out to compiled
+//      Roslyn/JavaParser binaries — adding doc capture there means modifying and rebuilding
+//      external .NET/JVM tooling, not a JS-side change. Deliberately deferred (PLAN_PROSE_INDEX.md
+//      backlog); this pass consumes whatever `doc` is already present, regardless of source
+//      language, so C#/Java modules still get identifier-decomposition tokens today.
+//
+// Tokenizer pattern (stopwords, length bounds, per-doc token cap) mirrors marginalia's
+// app/lib/text-index.mjs — a proven lexical-inverted-index tokenizer for the same "search by
+// keyword, no embeddings, no stemmer dependency" problem, adapted for code identifiers.
+//
+// Storage: (a) a `prose_tokens` attribute (space-joined, deduped, sorted) on each individual —
+// the graph stays self-describing, works if a consumer only has one individual in hand; AND
+// (b) a real inverted index (word -> [individual ids]) built from those same tokens and
+// attached as `entities.proseIndex` — an O(1) word lookup for consumers (resolveObject-style
+// fuzzy object-term resolution, scoreModules-style lexical boosting) instead of scanning every
+// individual's attributes. Both are derived from the identical token set, so they can never
+// disagree; (b) is just (a) inverted once, cheaply, at build time.
+
+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 " +
+    "yes if then else than so such can will would should could may might about into over " +
+    "under out up down off again more most some any all what which who whom whose when " +
+    "where why how").split(/\s+/),
+);
+
+const MAX_TOKEN_LEN = 40;    // drops hash-like/garbage tokens (marginalia text-index.mjs)
+const MAX_TOKENS_PER_DOC = 120; // bounds cost on a pathologically long docstring/name
+
+/** Split an identifier or a path-like name into lowercase word tokens.
+ *  Handles camelCase, PascalCase, snake_case, kebab-case, dotted names, path
+ *  separators, and acronym runs ("HTTPSConnection" -> https/connection,
+ *  "parseXML" -> parse/xml). Filters single-character tokens (loop-variable noise). */
+export function splitIdentifierWords(raw) {
+  if (!raw) return [];
+  let s = String(raw).replace(/\.[A-Za-z0-9]+$/, ""); // strip a trailing file extension only
+  s = s
+    .replace(/[/\\]/g, " ")            // path separators
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")     // camelCase / word|Digit boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")  // acronym run -> TitleCase (HTTPSConnection)
+    .replace(/([A-Za-z])([0-9])/g, "$1 $2")
+    .replace(/([0-9])([A-Za-z])/g, "$1 $2")
+    .replace(/[_\-.]+/g, " ");
+  return s.split(/\s+/).map((w) => w.toLowerCase()).filter((w) => w.length > 1 && w.length <= MAX_TOKEN_LEN);
+}
+
+/** Tokenize free prose (a docstring/doc-comment) — lowercase words, punctuation stripped,
+ *  common stopwords and single-/over-length tokens dropped, capped at MAX_TOKENS_PER_DOC. */
+export function tokenizeProse(text) {
+  if (!text) return [];
+  const out = [];
+  const seen = new Set();
+  for (const raw of String(text).toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < 2 || raw.length > MAX_TOKEN_LEN || STOPWORDS.has(raw)) continue;
+    if (seen.has(raw)) continue;
+    seen.add(raw);
+    out.push(raw);
+    if (out.length >= MAX_TOKENS_PER_DOC) break;
+  }
+  return out;
+}
+
+/** The combined, deduped, sorted token set for one individual: its (decomposed) name
+ *  plus any captured doc text. Returns [] if there's nothing to index (never null). */
+export function proseTokensFor({ name, doc } = {}) {
+  const set = new Set([...splitIdentifierWords(name), ...tokenizeProse(doc)]);
+  return [...set].sort();
+}
+
+/** Second pass (PLAN_PROSE_INDEX.md): attach a `prose_tokens` attribute to every
+ *  individual in `individuals`, deriving tokens from its name and captured prose text.
+ *  Class-aware source selection: Module/Function/Method/Class/Attribute/GlobalVariable use
+ *  `label` (a real identifier/path — decomposable, e.g. "calculateTotalPrice") + a `doc`
+ *  attribute if present (docstring/doc-comment). Commit is different: its `label` is a
+ *  truncated SHA (hex noise if decomposed, e.g. "e6a9419567f7" -> "9419567" garbage) — skip
+ *  decomposing it and tokenize its `message` attribute instead, which is the real prose
+ *  (commit messages are often the richest free text in the whole graph). Mutates and
+ *  returns the same array — safe to call once after the typed individuals are built.
+ *  `enabled=false` is a no-op (the disable path `TMCT_PROSE_INDEX=0` in a graph writer), so
+ *  the core typed graph is never affected by turning this pass off. */
+export function attachProseTokens(individuals, { enabled = true } = {}) {
+  if (!enabled) return individuals;
+  for (const ind of individuals) {
+    const attrs = ind.attributes || [];
+    const isCommit = ind.class === "Commit";
+    const name = isCommit ? null : ind.label;
+    const doc = isCommit
+      ? attrs.find((a) => a.key === "message")?.value
+      : attrs.find((a) => a.key === "doc")?.value;
+    const tokens = proseTokensFor({ name, doc });
+    if (tokens.length) {
+      ind.attributes = [...(ind.attributes || []), { prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }];
+    }
+  }
+  return individuals;
+}
+
+/** Build the inverted index (word -> sorted, deduped [individual ids]) from individuals
+ *  that already carry a `prose_tokens` attribute (i.e. after attachProseTokens ran).
+ *  Plain object, JSON-serializable — this is what lands as `entities.proseIndex`. */
+export function buildProseIndex(individuals) {
+  const index = Object.create(null);
+  for (const ind of individuals) {
+    const tokAttr = (ind.attributes || []).find((a) => a.key === "prose_tokens");
+    if (!tokAttr?.value) continue;
+    for (const word of tokAttr.value.split(" ")) {
+      if (!index[word]) index[word] = [];
+      index[word].push(ind.id);
+    }
+  }
+  for (const word of Object.keys(index)) index[word].sort();
+  return index;
+}
+
+/** Consumer-facing lookup: individual ids whose prose tokens overlap `query` (free text,
+ *  tokenized the same way as a docstring), ranked by overlap count (most shared words
+ *  first). This is the integration point for ask.mjs's resolveObject (fuzzy object-term
+ *  resolution beyond exact/substring match) and codegraph.mjs's scoreModules (a lexical
+ *  boost source) — see PLAN_PROSE_INDEX.md for the exact call-site recommendation; not
+ *  wired into either file here to avoid colliding with concurrent work on them.
+ *  `proseIndex` is `entities.proseIndex` (buildProseIndex's output). */
+export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
+  const queryTokens = [...new Set([...splitIdentifierWords(query), ...tokenizeProse(query)])];
+  if (!queryTokens.length) return [];
+  const scoreById = new Map();
+  for (const word of queryTokens) {
+    for (const id of proseIndex?.[word] || []) {
+      scoreById.set(id, (scoreById.get(id) || 0) + 1);
+    }
+  }
+  return [...scoreById.entries()]
+    .sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([id, score]) => ({ id, score }));
+}
+
+/** OPT-IN read accessor for codegraph.mjs's `proseLayers` locate signal (this file's index
+ *  build is unchanged — this only READS the layers the pre-pass already wrote). Given a query
+ *  `token`, return the individual ids reachable through the NORMALISED prose layers
+ *  (spell-corrected / canonical-schema-term / stem / lemma) stored under
+ *  `proseIndex["tmct:layers"]` — the same normalised layers ask.mjs's resolveObject consults,
+ *  here surfaced for the locate SCORER so a task-text word that only overlaps a module via a
+ *  normalised form still resolves.
+ *
+ *  Layer shape consumed (an inverted index keyed by the NORMALISED token, mirroring the verbatim
+ *  top level, just normalised):
+ *    proseIndex["tmct:layers"] = { <layerName>: { <normalisedToken>: [id, …] }, … }
+ *  A posting may be a plain id array or `{ ids: [...] }` — both are tolerated. The raw query
+ *  token is looked up directly against every layer's keys, so a token whose surface form is
+ *  already a canonical/stem/lemma/spell-corrected key hits; the accessor never itself normalises
+ *  the query (it owns no normaliser — those live in the concurrent ask/prose-nlp surface), so it
+ *  can never disagree with the build's normalisation, only under-fire safely.
+ *
+ *  Returns { ids, via }: `ids` a deduped, sorted (stable/deterministic) id list; `via` the
+ *  sorted layer names that produced them, joined with "+", for a scorer's provenance — or null
+ *  when nothing hit. Absent / malformed / pre-layers `proseIndex` → { ids: [], via: null }: a
+ *  safe no-op, so the opt-in flag degrades to nothing on a graph indexed before layers existed.
+ *  Accepts either a `proseIndex` object or a parsed graph (reads its `.proseIndex`). */
+export function proseLayerHits(proseIndex, token) {
+  const src = proseIndex && (proseIndex["tmct:layers"] ? proseIndex : proseIndex.proseIndex);
+  const layers = src && src["tmct:layers"];
+  const t = String(token || "").toLowerCase();
+  const empty = { ids: [], via: null };
+  if (!t || !layers || typeof layers !== "object") return empty;
+  const ids = new Set();
+  const via = new Set();
+  for (const name of Object.keys(layers)) {
+    const layer = layers[name];
+    if (!layer || typeof layer !== "object") continue;
+    const posting = layer[t];
+    const list = Array.isArray(posting) ? posting : Array.isArray(posting?.ids) ? posting.ids : null;
+    if (!list?.length) continue;
+    for (const id of list) ids.add(id);
+    via.add(name);
+  }
+  return ids.size ? { ids: [...ids].sort(), via: [...via].sort().join("+") } : empty;
+}

package/src/schema-docs.mjs

@@ -0,0 +1,254 @@
+// schema-docs.mjs — the single source of truth for tmct's own ontology documentation.
+//
+// tmct's typed graph (src/graph-build.mjs's buildEntities, queried by codegraph.mjs)
+// has had its schema documented since day one, but only in scattered code comments
+// (graph-build.mjs's header, the `note` fields on some — not all — of the `vocabulary`
+// array entries it emits) — readable by a human editing the source, invisible to anything
+// that only sees graph.json. This file completes that documentation (every entity class,
+// every predicate actually emitted — verified against real `prop:`/`class:` literals in
+// graph-build.mjs, not just what the existing vocabulary array already claimed) and
+// `ingestSchemaDocs()` (called by a graph writer after buildEntities) merges it
+// into a graph build so a question like "what does cochange mean" or "what is a
+// Commit" is answerable by querying the SAME graph the same way any other question is —
+// not via separate hardcoded documentation logic.
+//
+// GLOBAL, NOT PER-REPO: this documentation does not vary by repository — "Module" means
+// the same thing indexing Django or a JS library — so it is static, committed data
+// (this file), never recomputed at index time. Ingesting it is a fixed-size merge, not a
+// computation (see the ~0ms measured delta in schema-docs.test.mjs).
+//
+// Mirrors the pattern in marginalia's app/lib/vocab.mjs (a `comment`/description per
+// schema term, single-sourced) minus the RDF/OWL external-alignment machinery, which
+// doesn't apply here — tmct's schema is code-relationship-specific, not general-domain.
+
+// ---- entity classes (7 — verified against every `class: "X"` individual literal in
+// graph-build.mjs) -----------------------------------------------------------------------
+export const CLASS_DOCS = Object.freeze([
+  { name: "Module", description:
+    "A source file — one importable unit within the indexed repository (a .py/.mjs/.ts/" +
+    ".cs/.java file, etc). The coarsest unit tmct ranks, locates, and injects as a " +
+    "digest; every other entity class belongs to exactly one Module." },
+  { name: "Class", description:
+    "A class definition inside a Module. Contains Methods and Attributes (seon:" +
+    "containsCodeEntity) and may declare a base class (seon:hasSuperType)." },
+  { name: "Function", description:
+    "A top-level, module-scope function definition — not a method (methods belong to a " +
+    "Class and are their own entity class)." },
+  { name: "Method", description:
+    "A function defined inside a Class — an instance, static, or class method. Distinct " +
+    "from Function so class membership (seon:containsCodeEntity) and free functions " +
+    "never get confused." },
+  { name: "Attribute", description:
+    "A field or property belonging to a Class — either a class-level assignment or a " +
+    "self-scoped instance field seen in a method body (self.<name> =). Distinct from a " +
+    "module-level GlobalVariable." },
+  { name: "GlobalVariable", description:
+    "A module-level variable or constant assignment that belongs to no Class or " +
+    "function — a name defined directly in a Module's top-level scope." },
+  { name: "Commit", description:
+    "A single recorded git commit. Carries author/date/message attributes and connects " +
+    "to the Modules it touched (mgx:touchedByCommit) and, more precisely, the specific " +
+    "symbols whose current source span its changed lines intersect (mgx:touchesSymbol)." },
+  { name: "Session", description:
+    "One recorded `tmct chat` session — a runtime observation, not a source " +
+    "derivation. Carries started/ended timestamps (temporal ordering, like a Commit's " +
+    "date), a turn count and the queries asked, and connects to the entities its turns " +
+    "resolved or answered with (mgx:asksAbout). Recorded under .tmct/sessions/ and " +
+    "re-attached on every re-index (sessions.mjs)." },
+]);
+
+// ---- predicates / attributes (every `prop:` token actually emitted by buildEntities,
+// verified by grep against graph-build.mjs — not just what the pre-existing `vocabulary`
+// array already documented; three real gaps found this way: seon:startsAt, mgx:value,
+// mgx:dotted, plus the prose second-pass's mgx:hasProseTokens) ------------------------
+export const PREDICATE_DOCS = Object.freeze([
+  // ---- object properties (edges between individuals) ----
+  { prop: "mgx:importsNamespace", kind: "imports", description:
+    "Module → Module. The subject module has a top-level import statement that resolves " +
+    "to a module already present in this repository's index. External/unresolved " +
+    "imports are dropped, never guessed." },
+  { prop: "mgx:callsCoarse", kind: "calls", description:
+    "Module → Module. An import-backed, module-granular \"this file calls into that " +
+    "file\" edge — not resolved to a specific symbol (see callsSymbol for that)." },
+  { prop: "mgx:callsSymbol", kind: "callsSymbol", description:
+    "Function/Method → Function/Class. A call site resolved to exactly one same-named " +
+    "definition in the repository — unambiguous names only; an ambiguous or external " +
+    "call is dropped rather than guessed (no wrong edge)." },
+  { prop: "seon:declaresMethod", kind: "defines", description:
+    "Module → Function/Class/Method/Attribute/GlobalVariable. What a module's top-level " +
+    "scope actually declares." },
+  { prop: "seon:containsCodeEntity", kind: "contains", description:
+    "Class → Method/Attribute. Class membership — which methods and fields belong to " +
+    "which class." },
+  { prop: "mgx:touchedByCommit", kind: "touches", description:
+    "Commit → Module. From `git log --name-only`, restricted to modules already in the " +
+    "index — which files a commit's diff lists, at file granularity." },
+  { prop: "mgx:touchesSymbol", kind: "touchesSymbol", description:
+    "Commit → Function/Method/Class/Attribute. A commit's changed-line-range intersected " +
+    "with a symbol's current source span — WHICH specific function or class a commit " +
+    "actually edited, not just which file it touched." },
+  { prop: "mgx:testsCoverage", kind: "tests", description:
+    "Module → Module. A test module's own internal imports — a lightweight \"this test " +
+    "file exercises that source file\" signal, not line-level coverage-tool data." },
+  { prop: "seon:hasSuperType", kind: "inherits", description:
+    "Class → Class. A class's base class, resolved to an internal Class when the name " +
+    "matches one defined in the repo; otherwise recorded as an external `ext:` reference." },
+  { prop: "mgx:changeCoupledWith", kind: "cochange", description:
+    "Module ↔ Module. Two modules frequently committed together, independent of any " +
+    "import or call relationship — surfaces coupling that static analysis alone misses " +
+    "(e.g. a module and its test file, or two files that always change together for a " +
+    "reason no import edge captures)." },
+  { prop: "mgx:reExports", kind: "reexports", description:
+    "Module → Function/Class. A module's public-API (`__all__`) entry that re-exports a " +
+    "symbol defined or imported elsewhere — answers \"where is X importable from,\" not " +
+    "just \"where is X defined.\"" },
+  { prop: "mgx:asksAbout", kind: "asksAbout", description:
+    "Session → any entity. A chat session's turn resolved this entity as its subject " +
+    "or cited it in the answer — which parts of the codebase a human actually asked " +
+    "about. A runtime observation (owned term, no SEON equivalent); references that no " +
+    "longer resolve after a re-index are dropped and counted, never guessed." },
+  { prop: "mgx:hasProseTokens", kind: "prose", description:
+    "Individual → word tokens (an attribute, not a between-individuals edge). The " +
+    "decomposed word sequence extracted from an identifier's name (camelCase/snake_case " +
+    "split) and any doc-comment prose, used by the second-pass prose-to-symbol " +
+    "cross-reference index (PLAN_PROSE_INDEX.md) to resolve free-text object terms that " +
+    "don't exact-match an identifier." },
+
+  // ---- attributes (individual-scoped facts, not edges) ----
+  { prop: "seon:startsAt", kind: "attribute", description:
+    "The `path:line` or `path:start-end` source location of a Function/Method/Class/" +
+    "Attribute/GlobalVariable — where in its Module the definition actually lives." },
+  { prop: "mgx:dotted", kind: "attribute", description:
+    "A Module's dotted import name (e.g. `pkg.sub.mod` for Python), when the language " +
+    "has one — used to resolve import statements to internal modules." },
+  { prop: "mgx:exportsAll", kind: "attribute", description:
+    "A Module's literal `__all__` membership list, stored even for entries that don't " +
+    "resolve to a real symbol — so the digest can always tell an agent \"this module has " +
+    "an __all__, add your new symbol to it.\"" },
+  { prop: "mgx:decorator", kind: "attribute", description:
+    "Python/framework decorators applied to a Function/Method/Class definition (e.g. " +
+    "`@property`, `@app.route(...)`), as written." },
+  { prop: "mgx:value", kind: "attribute", description:
+    "The literal right-hand-side value of a GlobalVariable's assignment, when the AST " +
+    "extractor could capture one cheaply (a constant or simple literal)." },
+  { prop: "mgx:sessionStarted", kind: "attribute", description:
+    "A chat Session's start time, ISO-8601 — the timestamp the session enters the " +
+    "timeline at (the Session analogue of a Commit's date)." },
+  { prop: "mgx:sessionEnded", kind: "attribute", description:
+    "A chat Session's end time, ISO-8601 (the /exit, EOF, or last recorded turn)." },
+  { prop: "mgx:sessionTurns", kind: "attribute", description:
+    "How many query turns a chat Session ran (non-empty, non-/exit inputs)." },
+  { prop: "mgx:sessionQueries", kind: "attribute", description:
+    "The queries a chat Session asked, ' | '-joined and length-capped — what the " +
+    "human wanted to know, in their own words." },
+  { prop: "mgx:sessionDroppedEdges", kind: "attribute", description:
+    "How many of a Session's recorded entity references could not be re-resolved " +
+    "against the current graph (renamed/removed code) — those edges are dropped, " +
+    "never guessed, and this attribute keeps the loss honest and visible." },
+  { prop: "mgx:commitAuthor", kind: "attribute", description: "A Commit's author name (git %an)." },
+  { prop: "mgx:commitDate", kind: "attribute", description:
+    "A Commit's author date, ISO-8601 (git %aI)." },
+  { prop: "mgx:commitMessage", kind: "attribute", description:
+    "A Commit's subject line (git %s), capped to 120 characters." },
+  { prop: "seon:hasParameter", kind: "attribute", description:
+    "A Function/Method's formal parameter list, as a signature string (the AST's " +
+    "unparsed argument list — not resolved types)." },
+  { prop: "seon:hasReturnType", kind: "attribute", description:
+    "A Function/Method's return type ANNOTATION exactly as written — not an inferred or " +
+    "resolved type." },
+  { prop: "seon:throwsException", kind: "attribute", description:
+    "Exception class names literally named in a `raise` statement inside the definition — " +
+    "not resolved to their own Class individuals." },
+  { prop: "seon:catchesException", kind: "attribute", description:
+    "Exception type names literally named in an `except` handler inside the definition." },
+  { prop: "seon:accessesField", kind: "attribute", description:
+    "`self.<field>` names a Method reads or writes — self-scoped only (an honest, " +
+    "narrow signal, not general data-flow analysis)." },
+  { prop: "seon:isStatic", kind: "attribute", description:
+    "The definition is decorated `@staticmethod` or `@classmethod`." },
+  { prop: "seon:isAbstract", kind: "attribute", description:
+    "The definition is decorated `@abstractmethod` or `@abstractproperty`." },
+  { prop: "seon:isConstant", kind: "attribute", description:
+    "An ALL_CAPS module-level GlobalVariable — a naming-convention signal, not enforced " +
+    "immutability." },
+  { prop: "seon:subKind", kind: "attribute", description:
+    "The flavour of a Class define when it is not a plain class: interface, enum, struct " +
+    "or record. The graph keeps kind=class for every type declaration; this attribute " +
+    "carries the distinction." },
+  { prop: "seon:hasAccessModifier", kind: "attribute", description:
+    "Visibility inferred from a leading underscore (private/protected); a public member " +
+    "carries no value for this attribute." },
+  { prop: "seon:hasDoc", kind: "attribute", description:
+    "The first line of a docstring, length-capped — a one-line purpose summary without " +
+    "the full docstring body." },
+]);
+
+const classDocByName = new Map(CLASS_DOCS.map((c) => [c.name, c]));
+const predicateDocByProp = new Map(PREDICATE_DOCS.map((p) => [p.prop, p]));
+
+/** Meta-individual ids are namespaced (`schema:class:`/`schema:predicate:`) so they can
+ *  never collide with a real code entity's id (`mod:`/`fn:`/`commit:`) and are trivially
+ *  filterable out of normal code-entity queries by anything that cares to. */
+const classIndividual = ({ name, description }) => ({
+  id: `schema:class:${name}`,
+  label: name,
+  class: "SchemaClass",
+  derived_from: [],
+  mentions: [],
+  attributes: [{ prop: "mgx:schemaDoc", key: "doc", value: description }],
+});
+
+const predicateIndividual = ({ prop, kind, description }) => ({
+  id: `schema:predicate:${prop}`,
+  // The label is the human-facing relation name (what a user would actually type — "what
+  // does cochange mean" — matching ask-vocab.mjs's VERB_TO_KIND/kind vocabulary), not the
+  // raw prop token; the token is kept as a separate attribute for exact lookup.
+  label: kind,
+  class: "SchemaPredicate",
+  derived_from: [],
+  mentions: [],
+  attributes: [
+    { prop: "mgx:schemaDoc", key: "doc", value: description },
+    { prop: "mgx:schemaToken", key: "token", value: prop },
+  ],
+});
+
+/** Merge the static schema documentation into a just-built `entities` payload (the
+ *  object `buildEntities` returns, before it's serialized to graph.json):
+ *   - `entities.classes[].description` filled in for every known class,
+ *   - `entities.vocabulary[].note` backfilled wherever it was missing (existing notes
+ *     are left as-is — this only fills gaps, it doesn't overwrite a human's wording),
+ *   - `entities.individuals` gains one SchemaClass + one SchemaPredicate individual per
+ *     documented term, so the SAME graph traversal that answers "what calls X" can also
+ *     answer "what is a Commit" or "what does cochange mean".
+ *  Mutates and returns `entities`. Idempotent (safe to call more than once — individuals
+ *  are only appended if not already present by id). Pure w.r.t. repo content: the output
+ *  is identical regardless of what was indexed. */
+export function ingestSchemaDocs(entities) {
+  if (!entities || typeof entities !== "object") return entities;
+
+  if (Array.isArray(entities.classes)) {
+    for (const c of entities.classes) {
+      const doc = classDocByName.get(c.name);
+      if (doc && c.description === undefined) c.description = doc.description;
+    }
+  }
+  if (Array.isArray(entities.vocabulary)) {
+    for (const v of entities.vocabulary) {
+      const doc = predicateDocByProp.get(v.prop);
+      if (doc && !v.note) v.note = doc.description;
+    }
+  }
+
+  entities.individuals ||= [];
+  const existingIds = new Set(entities.individuals.map((i) => i?.id));
+  for (const c of CLASS_DOCS) {
+    const ind = classIndividual(c);
+    if (!existingIds.has(ind.id)) { entities.individuals.push(ind); existingIds.add(ind.id); }
+  }
+  for (const p of PREDICATE_DOCS) {
+    const ind = predicateIndividual(p);
+    if (!existingIds.has(ind.id)) { entities.individuals.push(ind); existingIds.add(ind.id); }
+  }
+  return entities;
+}