@polycode-projects/seonix 0.2.0 → 0.3.0

package/src/embed.mjs

@@ -0,0 +1,191 @@
+// embed.mjs — deterministic static-embedding lookup (model2vec potion-base-8M).
+// PLAN_SEON_TUNING.md §7.6(5b), 2026-07-02 library-leverage review.
+//
+// The honest "near-LLM" locate lever: a STATIC per-token embedding table (model2vec's
+// potion-base-8M, MIT — 29,528 WordPiece subwords × 256 fp32 dims, ~30 MB) read straight
+// from its safetensors export, mean-pooled and L2-normalised. No ONNX runtime, no model
+// calls, no network after the one-time fetch — pure table lookup + float arithmetic, so
+// the same text always embeds to the same vector ($0, deterministic, offline).
+//
+// Dependency choice (documented per the review): the safetensors format is an 8-byte LE
+// header length + JSON header + raw little-endian tensor bytes, and the tokenizer is a
+// plain Bert-style WordPiece (tokenizer.json: BertNormalizer lowercase + BertPreTokenizer
+// + greedy longest-match with "##" continuations) — both are small enough to hand-roll
+// with node built-ins, so neither the @yarflam/potion-base-8m fallback package nor an HF
+// tokenizer dependency is taken. Numerical intent follows model2vec's own encode (subword
+// ids WITHOUT the [CLS]/[SEP] template, mean pool, normalize per config.json) — exact
+// float parity with the Python lib is not claimed; determinism and rank usefulness are.
+//
+// The weights are NEVER committed and NEVER in the npm package: they live in the
+// gitignored vendor/ tree (fetched by scripts/fetch-embeddings.mjs, `npm run
+// refs:embeddings`, SHA-256-pinned like the repo's other binary artefacts). Everything
+// here degrades gracefully — loadEmbedder() returns null when the weights dir is absent,
+// and callers (codegraph.mjs's opt-in embedRank, scripts/rank-gate.mjs) no-op with a
+// clear note instead of failing, so CI/tests never require the 30 MB download.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MODEL_FILE = "model.safetensors";
+const TOKENIZER_FILE = "tokenizer.json";
+const CONFIG_FILE = "config.json";
+
+/** Default artifact dir: $SEONIX_EMBED_DIR, else <repo>/vendor/embeddings/potion-base-8M
+ *  (gitignored via vendor/ — the location scripts/fetch-embeddings.mjs writes). */
+export function defaultEmbeddingsDir() {
+  if (process.env.SEONIX_EMBED_DIR) return process.env.SEONIX_EMBED_DIR;
+  const here = dirname(fileURLToPath(import.meta.url)); // packages/seonix/src
+  return join(here, "..", "..", "..", "vendor", "embeddings", "potion-base-8M");
+}
+
+// ---- safetensors (hand-rolled: u64le header length + JSON header + raw tensors) -------
+
+/** Read the single 2-D F32 embedding tensor from a safetensors file →
+ *  { matrix: Float32Array (row-major), rows, dim }. model2vec exports exactly one
+ *  tensor named "embeddings"; any lone 2-D F32 tensor is accepted for test fixtures. */
+function readSafetensors(file) {
+  const buf = readFileSync(file);
+  const headerLen = Number(buf.readBigUInt64LE(0));
+  const header = JSON.parse(buf.subarray(8, 8 + headerLen).toString("utf8"));
+  const name = header.embeddings
+    ? "embeddings"
+    : Object.keys(header).find((k) => k !== "__metadata__" && header[k]?.shape?.length === 2);
+  const t = name && header[name];
+  if (!t) throw new Error(`no 2-D tensor in ${file}`);
+  if (t.dtype !== "F32") throw new Error(`unsupported dtype ${t.dtype} in ${file} (only F32)`);
+  const [rows, dim] = t.shape;
+  const [start, end] = t.data_offsets;
+  const bytes = buf.subarray(8 + headerLen + start, 8 + headerLen + end);
+  if (bytes.byteLength !== rows * dim * 4) throw new Error(`tensor size mismatch in ${file}`);
+  // Copy into a fresh ArrayBuffer: the slice's byteOffset inside the file buffer is not
+  // guaranteed 4-byte aligned, and Float32Array requires alignment.
+  const matrix = new Float32Array(rows * dim);
+  new Uint8Array(matrix.buffer).set(bytes);
+  return { matrix, rows, dim };
+}
+
+// ---- Bert-style WordPiece tokenizer (from tokenizer.json) -----------------------------
+
+const isPunct = (ch) => {
+  const c = ch.codePointAt(0);
+  // ASCII punctuation ranges (Bert treats these as standalone tokens) + general unicode P/S.
+  return (c >= 33 && c <= 47) || (c >= 58 && c <= 64) || (c >= 91 && c <= 96) || (c >= 123 && c <= 126) ||
+    /[\p{P}\p{S}]/u.test(ch);
+};
+const isCjk = (ch) => {
+  const c = ch.codePointAt(0);
+  return (c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) ||
+    (c >= 0xf900 && c <= 0xfaff) || (c >= 0x20000 && c <= 0x2ffff);
+};
+
+function makeTokenizer(spec) {
+  if (spec?.model?.type !== "WordPiece") {
+    throw new Error(`unsupported tokenizer model "${spec?.model?.type}" (only WordPiece)`);
+  }
+  const vocab = spec.model.vocab; // token -> id
+  const contPrefix = spec.model.continuing_subword_prefix ?? "##";
+  const maxChars = spec.model.max_input_chars_per_word ?? 100;
+  const unkId = vocab[spec.model.unk_token] ?? null;
+  const lowercase = spec.normalizer?.lowercase !== false;
+
+  // BertNormalizer: clean control chars, pad CJK, lowercase (+ strip accents when lowercasing).
+  const normalize = (text) => {
+    let s = String(text).replace(/[\u0000\ufffd]/g, "").replace(/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
+    s = [...s].map((ch) => (isCjk(ch) ? ` ${ch} ` : ch)).join("");
+    if (lowercase) s = s.toLowerCase().normalize("NFD").replace(/\p{Mn}/gu, "");
+    return s;
+  };
+  // BertPreTokenizer: split on whitespace; every punctuation char is its own word.
+  const preTokenize = (s) => {
+    const words = [];
+    for (const chunk of s.split(/\s+/)) {
+      if (!chunk) continue;
+      let cur = "";
+      for (const ch of chunk) {
+        if (isPunct(ch)) {
+          if (cur) { words.push(cur); cur = ""; }
+          words.push(ch);
+        } else cur += ch;
+      }
+      if (cur) words.push(cur);
+    }
+    return words;
+  };
+  // Greedy longest-match WordPiece per word; a word with no valid segmentation → [UNK].
+  const wordPiece = (word) => {
+    if (word.length > maxChars) return unkId == null ? [] : [unkId];
+    const ids = [];
+    let start = 0;
+    while (start < word.length) {
+      let end = word.length;
+      let id = null;
+      while (end > start) {
+        const piece = (start > 0 ? contPrefix : "") + word.slice(start, end);
+        if (vocab[piece] !== undefined) { id = vocab[piece]; break; }
+        end--;
+      }
+      if (id == null) return unkId == null ? [] : [unkId];
+      ids.push(id);
+      start = end;
+    }
+    return ids;
+  };
+  // No [CLS]/[SEP] template — model2vec pools content subwords only.
+  return (text) => preTokenize(normalize(text)).flatMap(wordPiece);
+}
+
+// ---- embedder ---------------------------------------------------------------------------
+
+const LOADED = new Map(); // dir -> embedder | null (per-process cache; weights load once)
+
+/** Load tokenizer + embedding matrix from `dir` (default: defaultEmbeddingsDir()).
+ *  Returns null — silently — when the artifacts are absent (the one-time
+ *  `npm run refs:embeddings` fetch has not run): callers no-op, never fail.
+ *  The returned embedder is { dim, dir, embed(text) → L2-normalised Float32Array }. */
+export function loadEmbedder({ dir = defaultEmbeddingsDir() } = {}) {
+  if (LOADED.has(dir)) return LOADED.get(dir);
+  const modelFile = join(dir, MODEL_FILE);
+  const tokFile = join(dir, TOKENIZER_FILE);
+  if (!existsSync(modelFile) || !existsSync(tokFile)) {
+    LOADED.set(dir, null);
+    return null;
+  }
+  const { matrix, rows, dim } = readSafetensors(modelFile);
+  const tokenize = makeTokenizer(JSON.parse(readFileSync(tokFile, "utf8")));
+  let cfg = {};
+  try { cfg = JSON.parse(readFileSync(join(dir, CONFIG_FILE), "utf8")); } catch { /* optional */ }
+  const doNormalize = cfg.normalize !== false;
+
+  const embed = (text) => {
+    const ids = tokenize(text);
+    const v = new Float32Array(dim);
+    if (!ids.length) return v; // zero vector: cosine 0 against everything
+    for (const id of ids) {
+      if (id < 0 || id >= rows) continue;
+      const off = id * dim;
+      for (let j = 0; j < dim; j++) v[j] += matrix[off + j];
+    }
+    for (let j = 0; j < dim; j++) v[j] /= ids.length; // mean pool
+    if (doNormalize) {
+      let norm = 0;
+      for (let j = 0; j < dim; j++) norm += v[j] * v[j];
+      norm = Math.sqrt(norm);
+      if (norm > 0) for (let j = 0; j < dim; j++) v[j] /= norm;
+    }
+    return v;
+  };
+  const embedder = { dim, dir, embed };
+  LOADED.set(dir, embedder);
+  return embedder;
+}
+
+/** Cosine similarity. Over L2-normalised vectors this is just the dot product, but the
+ *  full form is kept so unnormalised test fixtures behave. 0 when either vector is zero. */
+export function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/src/extract.mjs

@@ -18,14 +18,15 @@
 //   mgx:subclassOf          Class  → Class    (inheritance; internal base resolved, else ext:)
 
 import { spawn } from "node:child_process";
-import { writeFile, mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { basename, dirname, join, parse, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as codegraph from "./codegraph.mjs"; // optional renderToolsCatalog (other agent owns this file)
 import { ingestRepo, LANG_EXTS } from "./extract_lang.mjs";
 import { loadIgnores } from "./walk.mjs";
 import { attachProseTokens, buildProseIndex } from "./prose.mjs";
 import { ingestSchemaDocs } from "./schema-docs.mjs";
+import { foldInSessions, readSessionRecords } from "./sessions.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const AST_SCRIPT = join(here, "extract_ast.py");
@@ -194,16 +195,36 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   for (const m of modules) {
     for (const d of m.defines || []) {
       if (d.kind === "method" || d.kind === "attribute" || d.kind === "global") continue; // not standalone call targets
-      if (!nameToPaths.has(d.name)) nameToPaths.set(d.name, new Set());
-      nameToPaths.get(d.name).add(m.path);
-      if (!nameToSymbolIds.has(d.name)) nameToSymbolIds.set(d.name, new Set());
-      nameToSymbolIds.get(d.name).add(fnId(m.path, d.name));
-      if (d.kind === "class") {
-        if (!classToPaths.has(d.name)) classToPaths.set(d.name, new Set());
-        classToPaths.get(d.name).add(m.path);
+      const register = (name) => {
+        if (!nameToPaths.has(name)) nameToPaths.set(name, new Set());
+        nameToPaths.get(name).add(m.path);
+        if (!nameToSymbolIds.has(name)) nameToSymbolIds.set(name, new Set());
+        nameToSymbolIds.get(name).add(fnId(m.path, d.name));
+        if (d.kind === "class") {
+          if (!classToPaths.has(name)) classToPaths.set(name, new Set());
+          classToPaths.get(name).add(m.path);
+        }
+      };
+      register(d.name);
+      // Nested types (Java/C#) define dotted names like Outer.Inner — ALSO register the
+      // simple name so `new Inner()` / `extends Inner` still resolve. Same Set semantics:
+      // a second definition of the simple name makes it ambiguous → dropped, honest.
+      if (d.kind === "class" && d.name.includes(".")) {
+        const simple = lastIdent(d.name);
+        if (simple && simple !== d.name) register(simple);
       }
     }
   }
+  // Resolve a class SIMPLE name at a path to the id of its (possibly nested, dotted)
+  // define — nameToSymbolIds keeps full ids, so a unique in-path match wins; an exact
+  // plain define beats a nested one; else fall back to the literal id (pre-nesting shape).
+  const classIdAt = (path, ident) => {
+    const pre = `fn:${path}#`;
+    const exact = `${pre}${ident}`;
+    const ids = [...(nameToSymbolIds.get(ident) || [])].filter((i) => i.startsWith(pre));
+    if (ids.includes(exact) || ids.length !== 1) return exact;
+    return ids[0];
+  };
 
   // resolve a module's import candidates to internal module paths
   const internalImports = (m) => {
@@ -270,6 +291,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
         if (d.raises?.length) attrs.push({ prop: "seon:throwsException", key: "raises", value: list(d.raises) });
         if (d.catches?.length) attrs.push({ prop: "seon:catchesException", key: "catches", value: list(d.catches) });
         if (d.self_fields?.length) attrs.push({ prop: "seon:accessesField", key: "self_fields", value: list(d.self_fields) });
+        if (d.subkind) attrs.push({ prop: "seon:subKind", key: "subkind", value: String(d.subkind) });
         if (d.is_static) attrs.push({ prop: "seon:isStatic", key: "isStatic", value: "true" });
         if (d.is_abstract) attrs.push({ prop: "seon:isAbstract", key: "isAbstract", value: "true" });
         if (d.is_constant) attrs.push({ prop: "seon:isConstant", key: "isConstant", value: "true" });
@@ -305,10 +327,10 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
           const defs = classToPaths.get(ident);
           let object = `ext:${ident}`;
           if (defs && defs.has(m.path)) {
-            object = fnId(m.path, ident); // same-module base wins (local name scoping), even if the name is globally ambiguous
+            object = classIdAt(m.path, ident); // same-module base wins (local name scoping), even if the name is globally ambiguous
           } else if (defs && defs.size === 1) {
             const targetPath = [...defs][0];
-            if (imports.has(targetPath)) object = fnId(targetPath, ident);
+            if (imports.has(targetPath)) object = classIdAt(targetPath, ident);
           }
           const ikey = `${oid}>${object}`;
           if (seenInherits.has(ikey) || object === oid) continue;
@@ -376,7 +398,9 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       touchedBy.get(f).push(`git:${short}`);
       touchedAny = true;
     }
-    if (touchedAny) {
+    // !commitIds.has: a merged multi-repo commit list CAN repeat a sha (two clones of
+    // the same project indexed under different names) — one Commit individual per sha.
+    if (touchedAny && !commitIds.has(c.sha)) {
       commitIds.add(c.sha);
       commitIndividuals.push(commitInd(c.sha, short, c));
     }
@@ -514,6 +538,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       { prop: "seon:isStatic", note: "@staticmethod/@classmethod" },
       { prop: "seon:isAbstract", note: "@abstractmethod/@abstractproperty" },
       { prop: "seon:isConstant", note: "ALL_CAPS module global" },
+      { prop: "seon:subKind", note: "type flavour on a Class define when not a plain class (interface/enum/struct/record); kind stays class" },
       { prop: "seon:hasAccessModifier", note: "visibility from leading underscore (private/protected); public omitted" },
       { prop: "seon:hasDoc", note: "first docstring line (capped) — one-line purpose without the body" },
     ],
@@ -591,17 +616,13 @@ function localToolsCatalog(cliPath) {
   return lines.join("\n");
 }
 
-/**
- * Index a repository: parse (ast) + git log → entities → write <repo>/.seonix/graph.json
- * (+ a TOOLS.md catalog of the cold tools). Times the base extraction vs the added
- * symbol-history (line-range) pass so the latter can be kept within the ≤10% budget.
- * @returns {Promise<{graphFile, counts}>}
- */
-export async function indexRepository(repoPath, { python = process.env.SEONIX_PYTHON || process.env.SEON_PYTHON || "python3", generatedAt = "", ignores = true } = {}) {
+const DEFAULT_PYTHON = () => process.env.SEONIX_PYTHON || process.env.SEON_PYTHON || "python3";
+
+/** One repo's raw extraction — parsers + git, NO graph assembly. Both index modes
+ *  build on this; multi-repo runs it repo-by-repo so only one repo's raw source
+ *  (parser/git-log output) is in memory at a time. */
+async function extractRepo(repoPath, { python = DEFAULT_PYTHON(), ignores = true } = {}) {
   const t0 = Date.now();
-  // Second pass (PLAN_PROSE_INDEX.md): on by default; SEONIX_PROSE_INDEX=0 disables it
-  // (mirrors SEONIX_HISTORY_SYMBOL_DEPTH=0's disable convention above).
-  const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
   // `.seonixignore` (opt-out: `ignores:false`, the benchmark rig's flag). The matcher
   // prunes the in-process walkers (extract_lang) at parse time; the module filter below
   // is the AUTHORITATIVE cut — it also covers extractors that walk on their own
@@ -625,14 +646,24 @@ export async function indexRepository(repoPath, { python = process.env.SEONIX_PY
   const tHist = Date.now();
   const symbolHistory = await runGitLogHunks(repoPath, historySymbolDepth());
   const historyMs = Date.now() - tHist;
+  return { modules, perLang: langResult.perLang, commits, symbolHistory, baseMs, historyMs };
+}
 
+/** Assemble entities from (possibly merged) extractions and write the artifacts
+ *  (<rootDir>/.seonix/graph.json + TOOLS.md). Shared by both index modes. */
+async function assembleAndWrite(rootDir, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions = [] }) {
   const entities = buildEntities(modules, commits, { generatedAt, symbolHistory, prose: proseEnabled });
   // Schema self-documentation (schema-docs.mjs): static, repo-independent — merges in
   // SchemaClass/SchemaPredicate individuals + backfills entities.classes[].description
   // and entities.vocabulary[].note, so "what does cochange mean" is answerable by the
   // same graph traversal as any other question. Fixed-size, ~0ms marginal cost.
   ingestSchemaDocs(entities);
-  const graphFile = join(repoPath, ".seonix", "graph.json");
+  // Chat sessions (sessions.mjs): sessions are runtime observations, not source
+  // derivations — they are re-attached AFTER the source-derived build, each recorded
+  // entity id re-resolved against the fresh graph (unresolvable → edge dropped and
+  // counted on the Session node, never guessed). No sessions → byte-identical output.
+  if (sessions.length) foldInSessions(entities, sessions);
+  const graphFile = join(rootDir, ".seonix", "graph.json");
   await mkdir(dirname(graphFile), { recursive: true });
   await writeFile(graphFile, JSON.stringify(entities));
 
@@ -641,27 +672,177 @@ export async function indexRepository(repoPath, { python = process.env.SEONIX_PY
   const toolsMd = typeof codegraph.renderToolsCatalog === "function"
     ? codegraph.renderToolsCatalog(CLI_SCRIPT)
     : localToolsCatalog(CLI_SCRIPT);
-  await writeFile(join(repoPath, ".seonix", "TOOLS.md"), toolsMd);
+  await writeFile(join(rootDir, ".seonix", "TOOLS.md"), toolsMd);
+  return { entities, graphFile };
+}
 
+function buildCounts(entities, { modules, languages, commits, proseEnabled, baseMs, historyMs }) {
   const propCount = (prop) => entities.objectProperties.find((g) => g.prop === prop)?.count ?? 0;
   // history budget: the symbol pass should add ≤10% over base extraction time.
   const historyPct = baseMs > 0 ? Math.round((historyMs / baseMs) * 1000) / 10 : 0;
+  return {
+    modules,
+    languages,
+    functions: entities.classes.find((c) => c.name === "Function")?.count ?? 0,
+    commits,
+    edges: entities.objectProperties.reduce((n, g) => n + g.count, 0),
+    callsSymbol: propCount("mgx:callsSymbol"),
+    touchesSymbol: propCount("mgx:touchesSymbol"),
+    historySymbolDepth: historySymbolDepth(),
+    proseEnabled,
+    proseWords: Object.keys(entities.proseIndex || {}).length,
+    baseMs,
+    historyMs,
+    historyPct,
+  };
+}
+
+/**
+ * Index a repository: parse (ast) + git log → entities → write <repo>/.seonix/graph.json
+ * (+ a TOOLS.md catalog of the cold tools). Times the base extraction vs the added
+ * symbol-history (line-range) pass so the latter can be kept within the ≤10% budget.
+ * @returns {Promise<{graphFile, counts}>}
+ */
+export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true } = {}) {
+  // Second pass (PLAN_PROSE_INDEX.md): on by default; SEONIX_PROSE_INDEX=0 disables it
+  // (mirrors SEONIX_HISTORY_SYMBOL_DEPTH=0's disable convention above).
+  const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
+  const { modules, perLang, commits, symbolHistory, baseMs, historyMs } = await extractRepo(repoPath, { python, ignores });
+  const sessions = await readSessionRecords(repoPath); // recorded chat sessions (.seonix/sessions/*.jsonl), [] when none
+  const { entities, graphFile } = await assembleAndWrite(repoPath, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions });
   return {
     graphFile,
-    counts: {
-      modules: modules.length,
-      languages: langResult.perLang,
-      functions: entities.classes.find((c) => c.name === "Function")?.count ?? 0,
-      commits: commits.length,
-      edges: entities.objectProperties.reduce((n, g) => n + g.count, 0),
-      callsSymbol: propCount("mgx:callsSymbol"),
-      touchesSymbol: propCount("mgx:touchesSymbol"),
-      historySymbolDepth: historySymbolDepth(),
-      proseEnabled,
-      proseWords: Object.keys(entities.proseIndex || {}).length,
-      baseMs,
-      historyMs,
-      historyPct,
-    },
+    counts: buildCounts(entities, { modules: modules.length, languages: perLang, commits: commits.length, proseEnabled, baseMs, historyMs }),
+  };
+}
+
+// ── multi-repository indexing ────────────────────────────────────────────────
+// n repos → ONE merged graph at <out_root>/.seonix/. Single-path mode above is
+// untouched (no prefix, artifacts in the repo — golden-compat guarded by
+// test/multi-repo.test.mjs). In multi mode every module id/label/dotted gets the
+// repo's directory basename as a leading component, so ids never collide and a
+// reader can tell repos apart. Cross-repo callsSymbol edges arise only where a
+// symbol name resolves uniquely across the whole merged registry (the existing
+// Set-semantics drop ambiguous names — nothing cross-repo-special is done).
+
+/** Deterministic repo-name prefixes for a set of (resolved, deduped) repo paths:
+ *  the directory basename; when two repos share a basename the FIRST in path sort
+ *  order keeps the bare name and later ones get `-2`, `-3`, … appended. */
+export function assignRepoPrefixes(repoPaths) {
+  const map = new Map();
+  const used = new Set();
+  for (const rp of [...repoPaths].sort()) {
+    const base = basename(rp) || rp;
+    let name = base;
+    for (let n = 2; used.has(name); n += 1) name = `${base}-${n}`;
+    used.add(name);
+    map.set(rp, name);
+  }
+  return map;
+}
+
+/** Prefix one repo's raw extraction in place: module path/dotted/imports, commit
+ *  file lists and symbol-history range keys all gain the repo name as a leading
+ *  component (`mod:<repoName>/<relpath>`, dotted `<repoName>.<dotted>`). Imports
+ *  are prefixed IDENTICALLY to dotted names so intra-repo import resolution is
+ *  unchanged and two repos' equal dotted names can never cross-resolve. Commit
+ *  ids (shas) stay as-is — history edges point at the prefixed module ids. */
+export function applyRepoPrefix({ modules, commits, symbolHistory }, prefix) {
+  for (const m of modules) {
+    m.path = `${prefix}/${m.path}`;
+    if (m.dotted) m.dotted = `${prefix}.${m.dotted}`;
+    if (m.imports?.length) m.imports = m.imports.map((i) => `${prefix}.${i}`);
+  }
+  for (const c of commits) c.files = (c.files || []).map((f) => `${prefix}/${f}`);
+  for (const c of symbolHistory) {
+    c.ranges = Object.fromEntries(Object.entries(c.ranges || {}).map(([p, r]) => [`${prefix}/${p}`, r]));
+  }
+}
+
+/** Default merged-artifact root: the deepest common ancestor DIRECTORY of the repo
+ *  paths (segment-wise, so /x/foo and /x/foobar meet at /x, not /x/foo). Falls back
+ *  to `cwd` when the ancestor is the filesystem root. */
+export function defaultOutRoot(repoPaths, cwd = process.cwd()) {
+  const segs = repoPaths.map((p) => resolve(p).split(sep));
+  const first = segs[0];
+  let depth = Math.min(...segs.map((s) => s.length));
+  let i = 0;
+  while (i < depth && segs.every((s) => s[i] === first[i])) i += 1;
+  const ancestor = first.slice(0, i).join(sep) || sep;
+  return ancestor === parse(ancestor).root ? cwd : ancestor;
+}
+
+/** Discovery for the estate case: every immediate child directory of `multiRoot`
+ *  that carries a `.git` (dir OR file — worktrees/submodules have .git files) is a
+ *  repo. Dot-dirs are ignored outright; plain child dirs without .git are returned
+ *  as `skipped` so the caller can log them. */
+export async function discoverRepos(multiRoot) {
+  const root = resolve(multiRoot);
+  const entries = await readdir(root, { withFileTypes: true });
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const repos = [];
+  const skipped = [];
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".")) continue;
+    try {
+      await stat(join(root, e.name, ".git"));
+      repos.push(join(root, e.name));
+    } catch {
+      skipped.push(e.name);
+    }
+  }
+  return { repos, skipped };
+}
+
+/**
+ * Index n repositories into ONE merged graph at <outRoot>/.seonix/. Repos are
+ * extracted sequentially (only one repo's raw parser/git output held at a time;
+ * the accumulated PARSED module list is small) and merged through a single
+ * buildEntities pass, so the unique-name registry spans all repos.
+ * `log` (optional) receives one progress line per repo.
+ * @returns {Promise<{graphFile, outRoot, repos, counts}>}
+ */
+export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, outRoot = "", log = () => {} } = {}) {
+  const paths = [...new Set((repoPaths || []).map((p) => resolve(p)))];
+  if (!paths.length) throw new Error("indexRepositories requires at least one repo path");
+  const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
+  const prefixes = assignRepoPrefixes(paths);
+  const root = outRoot ? resolve(outRoot) : defaultOutRoot(paths);
+
+  const allModules = [];
+  const allCommits = [];
+  const allSymbolHistory = [];
+  const languages = {};
+  const repos = [];
+  let baseMs = 0;
+  let historyMs = 0;
+  for (const rp of paths) {
+    const prefix = prefixes.get(rp);
+    const r = await extractRepo(rp, { python, ignores });
+    applyRepoPrefix(r, prefix);
+    allModules.push(...r.modules);
+    allCommits.push(...r.commits);
+    allSymbolHistory.push(...r.symbolHistory);
+    baseMs += r.baseMs;
+    historyMs += r.historyMs;
+    for (const [lang, s] of Object.entries(r.perLang)) {
+      const agg = languages[lang] || (languages[lang] = { lib: s.lib, files: 0, modules: 0, symbols: 0, failures: 0, ms: 0 });
+      agg.files += s.files; agg.modules += s.modules; agg.symbols += s.symbols; agg.failures += s.failures; agg.ms += s.ms;
+    }
+    repos.push({ path: rp, prefix, modules: r.modules.length, commits: r.commits.length });
+    log(`indexed ${prefix} (${rp}): ${r.modules.length} modules, ${r.commits.length} commits in ${r.baseMs + r.historyMs}ms`);
+  }
+
+  // TODO(sessions): multi-repo merges don't fold in the member repos' .seonix/sessions
+  // yet — their recorded ids would need the same repo-name prefixing as modules to
+  // re-resolve against the merged graph. Deferred; single-path fold-in is the contract.
+  const { entities, graphFile } = await assembleAndWrite(root, {
+    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled,
+  });
+  return {
+    graphFile,
+    outRoot: root,
+    repos,
+    counts: buildCounts(entities, { modules: allModules.length, languages, commits: allCommits.length, proseEnabled, baseMs, historyMs }),
   };
 }