mlx-bun 0.4.0 → 1.0.0

package/src/memory/pipeline.ts

@@ -1,275 +0,0 @@
-// mlx-bun memory — synthesis pipeline orchestrator (P6-T4).
-//
-// Ties the stage modules into the cold-start DAG:
-//   ingest → SEGMENT → ENTITY-EXTRACT → ROUTE → CREATE → NORMALIZE → commitVault.
-//
-// `ingest` + `SEGMENT` already populated the corpus (conversations / messages /
-// chunks live in the MemoryStore), so for an already-chunked conversation
-// SEGMENT is a no-op and the pipeline operates on the existing chunks. The model
-// stages reuse the existing modules verbatim:
-//   - ENTITY-EXTRACT — entity.ts `extractEntities` (one chunk per call, persists
-//     chunk_entities + a candidate entities/aliases row via the variant resolver).
-//   - ROUTE — route.ts `RouteAccumulator` over the persisted chunk_entities
-//     (the deterministic canonical join + the B8/P1-T5 CREATE gate); the optional
-//     model substantive-engagement gate promotes thin-but-owned candidates.
-//   - CREATE/NORMALIZE/commit — synthesize.ts `synthesizeCreate` (sub-cluster →
-//     OUTLINE → per-section DRAFT → INFOBOX → assemble → NORMALIZE → gate → write
-//     + ledger), with a single `commitVault` at the end of the run.
-//
-// `runSynthesis` keeps the M1 event/summary contract `src/cli.ts` drives; it now
-// runs the real DAG over the default store + vault. The FULL-corpus bootstrap is
-// USER-ACTION (P6-T5) — the agent never starts it; `scripts/experiments`
-// drives a bounded handful of conversations through `runPipeline` directly.
-
-import type { ChunkCall } from "./chunk";
-import type { SectionCall } from "./cluster";
-import { runLinkStage } from "./crosslink";
-import { MemoryStore } from "./db";
-import type { ExtractCall } from "./entity";
-import {
-  buildEntityMeta,
-  chronoChunkIds,
-  runExtractStage,
-  runRouteStage,
-  runSegmentStage,
-  runSynthesizeStage,
-  selectCreateTargets,
-  type EntityMeta,
-  type PipelineCreated,
-  type PipelinePatched,
-  type RouteDecision,
-} from "./stages";
-import type { SynthesisCall } from "./synthesize";
-import { vaultRoot } from "./vault";
-import { wikifyVault } from "./wikify";
-
-// Re-export the factored-out pure helpers + types so existing importers (tests,
-// scripts) keep their `from "./pipeline"` entry points.
-export { buildEntityMeta, selectCreateTargets };
-export type { EntityMeta, PipelineCreated, PipelinePatched, RouteDecision };
-
-// ---- stage / event contract (consumed by src/cli.ts) -----------------------
-
-export type SynthesisStage =
-  | "ingest"
-  | "segment"
-  | "chunk"
-  | "extract"
-  | "route"
-  | "create"
-  | "section-route"
-  | "patch"
-  | "reconcile"
-  | "link"
-  | "wikify"
-  | "commit";
-
-export interface SynthesisEvent {
-  type: "stage" | "log" | "done";
-  stage?: SynthesisStage;
-  message: string;
-}
-
-export interface SynthesisOptions {
-  /** Only synthesize conversations newer than this (ISO date / conv cursor). */
-  since?: string;
-  /** Override the synthesis model (default e4b). Reserved — the stages resolve
-   *  their own per-stage adapter via model.ts. */
-  model?: string;
-  /** Plan only — never write the vault (deterministic, no model). */
-  dryRun?: boolean;
-}
-
-export interface SynthesisSummary {
-  implemented: boolean;
-  stages: SynthesisStage[];
-  note: string;
-}
-
-const STAGES: SynthesisStage[] = [
-  "ingest",
-  "segment",
-  "extract",
-  "route",
-  "create",
-  "section-route",
-  "patch",
-  "link",
-  "wikify",
-  "commit",
-];
-
-// ---- pipeline run ----------------------------------------------------------
-
-export interface PipelineOptions {
-  /** Restrict the run to these conversation ids; default every conversation. */
-  convIds?: string[];
-  /** Vault root (honors MLX_BUN_WIKI); defaults to `vaultRoot()`. */
-  root?: string;
-  /** Max articles to CREATE this run (bounds a smoke's GPU cost). */
-  articleCap?: number;
-  /** Entities to force into the CREATE set when they earn a `create`. */
-  mustCreate?: string[];
-  /** Model-call seam for SEGMENT (the `chunk` stage — our e4b-chunk-300 /
-   *  `memory-chunk` adapter). Defaults to `callLocal("chunk", …)` inside
-   *  chunkConversations; tests inject a fake to avoid a real model load. */
-  segmentCall?: ChunkCall;
-  /** Model-call seam for the CREATE drafting AND the steady-state PATCH (both run
-   *  the `synthesis` stage). Tests inject a fake. */
-  call?: SynthesisCall;
-  /** Model-call seam for ENTITY-EXTRACT (the `entity` stage). Tests inject a fake. */
-  extractCall?: ExtractCall;
-  /** Model-call seam for SECTION-ROUTE (the `section` stage binary/name calls).
-   *  Tests inject a fake. */
-  sectionCall?: SectionCall;
-  /** Run the subject-engagement model gate to promote a thin (single-chunk)
-   *  genuine-subject candidate to a `create` stub. Off by default (a recurring
-   *  subject already creates). */
-  useSubjectGate?: boolean;
-  /** Skip the final git commit (tests). */
-  commit?: boolean;
-  now?: number;
-  onEvent?: (e: SynthesisEvent) => void;
-}
-
-export interface PipelineResult {
-  convs: number;
-  chunks: number;
-  /** Distinct resolved entities seen across the routed chunks. */
-  entities: number;
-  created: PipelineCreated[];
-  /** Sections of existing articles patched this run (the self-healing folds). */
-  patched: PipelinePatched[];
-  skippedByGate: string[];
-  /** Subjects captured (not yet articled) — still retrievable by search. */
-  captured: string[];
-}
-
-/**
- * Run the cold-start synthesis DAG over a bounded set of conversations.
- *
- * This is now a thin ORCHESTRATOR: it drives the four INDEPENDENT, chronological,
- * resumable stage workers (`stages.ts`) in sequence — SEGMENT → ENTITY-EXTRACT →
- * ROUTE → SYNTHESIZE (CREATE + SECTION-ROUTE/PATCH) — so the full DAG behaves as
- * before while each stage is also separately runnable (`mlx-bun memory
- * segment|extract|route|synthesize`). Returns a structured report; SYNTHESIZE
- * commits once at the end via `commitVault`.
- */
-export async function runPipeline(
-  store: MemoryStore,
-  opts: PipelineOptions = {},
-): Promise<PipelineResult> {
-  const root = opts.root ?? vaultRoot();
-  const cap = opts.articleCap ?? 20;
-  const emit = opts.onEvent ?? (() => {});
-
-  emit({ type: "stage", stage: "ingest", message: `ingest: corpus already in the store` });
-
-  // SEGMENT — (re)chunk every in-scope conversation whose chunked_at is NULL or
-  // stale, oldest-first, then proceed on the fresh chunks. A re-run is a no-op
-  // (watermark). We do NOT reuse any external chunks.
-  await runSegmentStage(store, { convIds: opts.convIds, call: opts.segmentCall, onEvent: opts.onEvent });
-
-  // Chronological run scope (oldest conversation first) for the result counts.
-  const { convs, chunkIds } = chronoChunkIds(store, opts.convIds);
-  emit({ type: "log", message: `operating on ${convs} conversation(s), ${chunkIds.length} chunk(s)` });
-
-  // ENTITY-EXTRACT — every not-yet-extracted chunk, chronological + resumable.
-  await runExtractStage(store, { convIds: opts.convIds, call: opts.extractCall, onEvent: opts.onEvent });
-
-  // ROUTE — deterministic create/capture over chunk_entities + CREATE gate;
-  // persists notable + captures thin subjects into _captured (still searchable)
-  // so SYNTHESIZE reads the decision back.
-  const route = await runRouteStage(store, {
-    convIds: opts.convIds,
-    useSubjectGate: opts.useSubjectGate,
-    onEvent: opts.onEvent,
-  });
-
-  // SYNTHESIZE — chronological CREATE (oldest entity first, oldest chunk first so
-  // the latest statement dominates) + SECTION-ROUTE → PATCH self-healing fold.
-  const synth = await runSynthesizeStage(store, {
-    root,
-    limit: cap,
-    convIds: opts.convIds,
-    mustCreate: opts.mustCreate,
-    call: opts.call,
-    sectionCall: opts.sectionCall,
-    commit: opts.commit,
-    now: opts.now,
-    onEvent: opts.onEvent,
-  });
-
-  // CROSS-LINK — build the EDGES synthesis (bounded to one article) cannot:
-  // inline-link first mentions of other articles + rebuild each ## See also from
-  // mentions + co-occurrence. Deterministic (no model) and idempotent.
-  await runLinkStage(store, { root, commit: opts.commit, onEvent: (e) => emit({ type: e.type, message: e.message }) });
-
-  emit({
-    type: "done",
-    message: `synthesis done — ${synth.created.length} created, ${synth.patched.length} patched, ${synth.skippedByGate.length} gated, ${route.captured.length} captured.`,
-  });
-
-  return {
-    convs,
-    chunks: chunkIds.length,
-    entities: route.decisions.length,
-    created: synth.created,
-    patched: synth.patched,
-    skippedByGate: synth.skippedByGate,
-    captured: route.captured,
-  };
-}
-
-// ---- cli entry: the M1 contract src/cli.ts drives --------------------------
-
-/**
- * Run the synthesis pipeline over the default store + vault — the `mlx-bun
- * memory synthesize` path. Keeps the {@link SynthesisSummary} shape the CLI
- * prints. The FULL-corpus run is a long GPU job (USER-ACTION, P6-T5); this entry
- * exists so the wiring is complete — the agent never starts it.
- */
-export async function runSynthesis(
-  opts: SynthesisOptions = {},
-  onEvent?: (e: SynthesisEvent) => void,
-): Promise<SynthesisSummary> {
-  if (opts.dryRun) {
-    onEvent?.({ type: "log", message: "dry-run — no model calls, nothing will be written." });
-    for (const stage of STAGES) onEvent?.({ type: "stage", stage, message: `${stage}: planned (dry-run)` });
-    onEvent?.({ type: "done", message: "dry-run complete — no articles written." });
-    return { implemented: true, stages: STAGES, note: "dry-run: DAG wired; no model calls made." };
-  }
-
-  const store = new MemoryStore();
-  try {
-    // WRITE branch: ingest → segment → extract → route → create → commit.
-    const result = await runPipeline(store, { onEvent });
-
-    // WIKIFY branch: the periodic editorial sweep over EVERY article (P8). Runs
-    // after the write branch so freshly-created and patched articles are tightened
-    // + infobox-refreshed in the same nightly pass; each article commits its own
-    // change (or NO-OPs) behind the same conservative gate. Best-effort: a wikify
-    // defect must not lose the create-branch work already committed above.
-    onEvent?.({ type: "stage", stage: "wikify", message: "wikify: editorial sweep over every article" });
-    let editedCount = 0;
-    try {
-      const sweep = await wikifyVault({ root: vaultRoot() });
-      editedCount = sweep.edited.length;
-      onEvent?.({ type: "log", message: `  wikify edited ${editedCount}/${sweep.results.length} article(s)` });
-    } catch (err) {
-      onEvent?.({ type: "log", message: `  wikify sweep skipped (error: ${String(err)})` });
-    }
-    onEvent?.({
-      type: "done",
-      message: `synthesis done — ${result.created.length} created, ${result.patched.length} patched, ${editedCount} wikified.`,
-    });
-
-    return {
-      implemented: true,
-      stages: STAGES,
-      note: `synthesis wired — ${result.created.length} created, ${result.patched.length} patched, ${editedCount} wikified from ${result.convs} conversations.`,
-    };
-  } finally {
-    store.close();
-  }
-}

package/src/memory/prompts.ts

@@ -1,65 +0,0 @@
-// mlx-bun memory — per-stage synthesis prompts.  ⚠️ M1 STUBS.
-//
-// Each stage's prompt is the seam where a future specialized memory LoRA plugs
-// in (today: base model + prompt; later: adapterScoped per stage). Editorial
-// conventions are NOT duplicated here — they live in the vault's Meta/ pages
-// (Editorial_Guidelines.md, Article_Conventions.md, Buckets.md,
-// Topics_to_Ignore.md) and are read in at synthesis time so the system governs
-// itself in its own substrate.
-//
-// See docs/design/dreaming-nightly-pipeline.md → "Synthesis runs on the local model".
-
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { vaultRoot } from "./vault";
-
-export const CHUNK_PROMPT = `TODO(M1): segment a conversation transcript into topic-coherent chunks.`;
-
-export const CLUSTER_PROMPT = `TODO(M1): assign a chunk to an existing bucket from Meta/Buckets.md, or propose a new bucket.`;
-
-export const SYNTHESIZE_PROMPT = `TODO(M1): integrate new chunks into the bucket's article. Preserve prose and every conv: citation; integrate, don't overwrite; respect the ≥70% word-count floor and the editorial gate.`;
-
-/** Placeholder registry so the pipeline can reference prompts by stage name. */
-export const STAGE_PROMPTS: Record<string, string> = {
-  chunk: CHUNK_PROMPT,
-  cluster: CLUSTER_PROMPT,
-  synthesize: SYNTHESIZE_PROMPT,
-};
-
-// ---- meta-policy inlining (ported from lucien scripts/meta-inline.ts) ------
-//
-// Editorial policy lives in the vault's Meta/ pages, not in code. Rather than
-// telling the model to Read those pages at synthesis time (which turns every
-// pipeline call into an agent loop whose context accumulates — a 34k-char
-// conversation was observed ballooning to a 105k-token prefill on the local
-// server), we inline the requested pages directly into the prompt. Calls stay
-// single-turn: one bounded prefill, one bounded generation. The policy is
-// edit-in-the-vault: change a Meta page on disk and the next run reflects it
-// with zero code change.
-
-/**
- * Read the named Meta policy pages from the vault's Meta/ dir and concatenate
- * them for inlining into a stage prompt. Each `name` addresses
- * `<vault>/Meta/<name>.md` (a trailing `.md` is accepted and normalized).
- *
- * The vault root honors the MLX_BUN_WIKI override (see {@link vaultRoot}).
- *
- * @throws {Error} If a requested Meta page does not exist on disk, naming it.
- */
-export function loadMetaPolicy(names: string[]): string {
-  const metaDir = join(vaultRoot(), "Meta");
-  const sections: string[] = [];
-  for (const name of names) {
-    const stem = name.trim().endsWith(".md") ? name.trim().slice(0, -3) : name.trim();
-    const path = join(metaDir, `${stem}.md`);
-    let text: string;
-    try {
-      text = readFileSync(path, "utf8");
-    } catch {
-      throw new Error(`Meta policy page not found: ${path}`);
-    }
-    sections.push(`--- Meta/${stem}.md ---\n\n${text.trim()}`);
-  }
-  return sections.join("\n\n");
-}

package/src/memory/query.ts

@@ -1,334 +0,0 @@
-// mlx-bun memory — the read-side navigation index + primitives.
-//
-// The read path FINDS an article deterministically — by category membership, by
-// name/alias, or by following the [[wikilink]] graph — then hands the agent off
-// to the read tools (TOC → section). It NEVER ranks by a vector and NEVER filters
-// on an infobox field: the infobox is CONTENT the model reads, not a query
-// target. There is deliberately no `byInfoboxField`, no numeric facet, no
-// `gte/lte` here. Every lookup below touches only indexed names/categories/links;
-// the embedding tripwire (src/embed.ts) MUST stay at zero across this module.
-//
-// `buildMemoryIndex` mirrors the same facts the reindex derives into the DB
-// (aliases, categories, series, kind/type, infobox, lead, link graph) into plain
-// in-memory maps, so the primitives are pure functions over a snapshot with no
-// DB round-trip. The build is mtime-incremental: each file is parsed at most once
-// per (path, mtime), so a rebuild after touching one article re-parses only that
-// file and is otherwise byte-identical to the prior build.
-
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-
-import {
-  deriveCategories,
-  infoboxAliases,
-  infoboxFieldValues,
-  parseInfobox,
-  parseLead,
-  parseSeriesBanner,
-  type EntityKind,
-  type Infobox,
-} from "./article";
-import { EntityResolver, nearNameMatch } from "./resolve";
-import { articlesDir, extractWikilinkTargets, resolveWikilinkToStem, vaultRoot } from "./vault";
-
-// ---- normalization (mirrors reindex.ts so resolveName agrees exactly) -
-
-/** Casefold + collapse whitespace/underscores so title, stem, and alias forms of
- *  the same surface text key the alias index identically. */
-function normalizeAlias(s: string): string {
-  return s.trim().toLowerCase().replace(/_/g, " ").replace(/\s+/g, " ").trim();
-}
-
-const LEADING_ARTICLE_RE = /^(?:the|a|an)\s+/;
-const WIKILINK_RE = /\[\[([^\]]+)\]\]/;
-
-/** The inner target of a `[[wikilink]]` value, before any `|alias`/`#anchor`. */
-function wikilinkInner(value: string): string {
-  const m = WIKILINK_RE.exec(value);
-  if (!m) return "";
-  return m[1]!.split("|")[0]!.split("#")[0]!.trim();
-}
-
-// ---- per-article parse + the index ------------------------------------
-
-/** One article's structured facts, parsed once and cached by (path, mtime). */
-interface IndexedArticle {
-  stem: string;
-  infobox: Infobox | null;
-  lead: string | null;
-  categories: string[];
-  series: string | null;
-  kind: EntityKind;
-  type: string | null;
-  /** Normalized alias surfaces (stem, spaced stem, infobox aliases). */
-  aliases: string[];
-  /** Resolved outbound link targets (existing article stems only, deduped). */
-  outbound: string[];
-}
-
-export interface MemoryIndex {
-  root: string;
-  /** normalized alias → stem (first writer in sorted-stem order wins). */
-  aliasToStem: Map<string, string>;
-  /** category name → member stems (sorted). */
-  categoryToStems: Map<string, string[]>;
-  /** series name → member stems (sorted). */
-  seriesToStems: Map<string, string[]>;
-  /** entity kind → stems (sorted). */
-  kindToStems: Map<string, string[]>;
-  /** emergent `type:` label → stems (sorted). */
-  typeToStems: Map<string, string[]>;
-  /** stem → parsed infobox (null when the article has none). */
-  infoboxByStem: Map<string, Infobox | null>;
-  /** stem → lead abstract (null when absent). */
-  leadByStem: Map<string, string | null>;
-  /** stem → resolved outbound article stems (the link graph). */
-  outboundByStem: Map<string, string[]>;
-  /** Stems (re)parsed on the most recent build (mtime miss). */
-  parsed: string[];
-  /** Stems served from the parse cache on the most recent build (mtime hit). */
-  reused: string[];
-}
-
-interface CacheEntry {
-  mtimeMs: number;
-  article: IndexedArticle;
-}
-
-/** Module-level parse cache keyed by absolute file path. Memoizes per-file
- *  PARSING only (keyed by mtime); the aggregate maps are rebuilt every call so
- *  they always reflect the current file set. */
-const ARTICLE_CACHE = new Map<string, CacheEntry>();
-
-/** Drop the parse cache. A cold rebuild after this yields maps byte-identical to
- *  a warm one (the cache is a pure speedup, never a source of truth). */
-export function resetMemoryIndexCache(): void {
-  ARTICLE_CACHE.clear();
-}
-
-/** Sorted article stems under `<root>/articles/` (`*.md`, no hidden files). */
-function listArticleStems(root: string): string[] {
-  let names: string[];
-  try {
-    names = readdirSync(articlesDir(root));
-  } catch {
-    return [];
-  }
-  return names
-    .filter((n) => n.endsWith(".md") && !n.startsWith("."))
-    .map((n) => n.slice(0, -3))
-    .sort((a, b) => a.localeCompare(b));
-}
-
-/** Parse one article's markdown into its indexed facts (no I/O). */
-function parseArticle(stem: string, md: string, stems: Set<string>): IndexedArticle {
-  const box = parseInfobox(md);
-
-  const aliasSet = new Set<string>();
-  for (const a of [stem, stem.replace(/_/g, " "), ...(box ? infoboxAliases(box) : [])]) {
-    const norm = normalizeAlias(a);
-    if (norm) aliasSet.add(norm);
-  }
-
-  // Outbound graph edges: prose [[links]] + infobox entity-link values + series
-  // banner, each resolved to an EXISTING article stem (red links are dropped,
-  // matching getArticleLinks). Self-edges excluded.
-  const outbound = new Set<string>();
-  const addEdge = (raw: string): void => {
-    const r = resolveWikilinkToStem(raw, stems);
-    if (r && r !== stem) outbound.add(r);
-  };
-  for (const t of extractWikilinkTargets(md)) addEdge(t);
-  if (box) {
-    for (const field of box.fields) {
-      for (const value of infoboxFieldValues(field)) {
-        if (WIKILINK_RE.test(value)) addEdge(wikilinkInner(value));
-      }
-    }
-  }
-  const series = parseSeriesBanner(md);
-  if (series) addEdge(series);
-
-  return {
-    stem,
-    infobox: box,
-    lead: parseLead(md),
-    categories: deriveCategories(md, stem).categories,
-    series,
-    kind: box ? box.entityKind : "thing",
-    type: box ? box.type : null,
-    aliases: [...aliasSet].sort((a, b) => a.localeCompare(b)),
-    outbound: [...outbound].sort((a, b) => a.localeCompare(b)),
-  };
-}
-
-/**
- * Build the read-side navigation index for a vault. mtime-incremental: each
- * article is parsed at most once per (path, mtime), so a rebuild after touching
- * one file re-parses ONLY that file. Deterministic: stems are visited in sorted
- * order and every map array is sorted, so two builds of the same vault produce
- * byte-identical maps. Makes ZERO embedding calls.
- */
-export function buildMemoryIndex(root: string = vaultRoot()): MemoryIndex {
-  const stems = listArticleStems(root);
-  const stemSet = new Set(stems);
-  const dir = articlesDir(root);
-
-  const parsed: string[] = [];
-  const reused: string[] = [];
-  const articles: IndexedArticle[] = [];
-
-  for (const stem of stems) {
-    const path = join(dir, `${stem}.md`);
-    let mtimeMs: number;
-    try {
-      mtimeMs = statSync(path).mtimeMs;
-    } catch {
-      continue; // raced/deleted between listing and stat
-    }
-    const cached = ARTICLE_CACHE.get(path);
-    if (cached && cached.mtimeMs === mtimeMs) {
-      reused.push(stem);
-      articles.push(cached.article);
-      continue;
-    }
-    let md: string;
-    try {
-      md = readFileSync(path, "utf8");
-    } catch {
-      continue;
-    }
-    const article = parseArticle(stem, md, stemSet);
-    ARTICLE_CACHE.set(path, { mtimeMs, article });
-    parsed.push(stem);
-    articles.push(article);
-  }
-
-  const index: MemoryIndex = {
-    root,
-    aliasToStem: new Map(),
-    categoryToStems: new Map(),
-    seriesToStems: new Map(),
-    kindToStems: new Map(),
-    typeToStems: new Map(),
-    infoboxByStem: new Map(),
-    leadByStem: new Map(),
-    outboundByStem: new Map(),
-    parsed,
-    reused,
-  };
-
-  const pushInto = (map: Map<string, string[]>, key: string, stem: string): void => {
-    const list = map.get(key);
-    if (list) list.push(stem);
-    else map.set(key, [stem]);
-  };
-
-  for (const a of articles) {
-    for (const alias of a.aliases) {
-      if (!index.aliasToStem.has(alias)) index.aliasToStem.set(alias, a.stem); // first (sorted) writer wins
-    }
-    for (const cat of a.categories) pushInto(index.categoryToStems, cat, a.stem);
-    if (a.series) pushInto(index.seriesToStems, a.series, a.stem);
-    pushInto(index.kindToStems, a.kind, a.stem);
-    if (a.type) pushInto(index.typeToStems, a.type, a.stem);
-    index.infoboxByStem.set(a.stem, a.infobox);
-    index.leadByStem.set(a.stem, a.lead);
-    index.outboundByStem.set(a.stem, a.outbound);
-  }
-
-  return index;
-}
-
-// ---- navigation primitives (find + resolve + links) -------------------
-
-/**
- * Article stems that DECLARED `[[Category:<category>]]` — the only "articles
- * about X" mechanism (zero substring false positives). Returns a sorted copy.
- */
-export function articlesInCategory(index: MemoryIndex, category: string): string[] {
-  return [...(index.categoryToStems.get(category) ?? [])];
-}
-
-/** Lazily-built near-name resolver per index (token-subset fuzzy over the alias
- *  map). Keyed by index identity; a fresh `buildMemoryIndex` yields a new object,
- *  so stale resolvers fall out of the WeakMap with their index. */
-const NEAR_RESOLVER = new WeakMap<MemoryIndex, EntityResolver>();
-
-function nearResolver(index: MemoryIndex): EntityResolver {
-  let r = NEAR_RESOLVER.get(index);
-  if (!r) {
-    r = EntityResolver.fromAliasMap(index.aliasToStem);
-    NEAR_RESOLVER.set(index, r);
-  }
-  return r;
-}
-
-/**
- * Resolve an entity name or alias to its article stem via the alias index.
- * Normalizes the query the same way aliases are stored (casefold, ws-collapse)
- * and also retries with a leading article word ("the"/"a"/"an") stripped, so
- * a "<the brand model>" surface and a "<model>" short form both reach the same stem.
- *
- * On an exact-alias miss, falls back to a conservative NEAR-NAME match
- * ({@link nearNameMatch}) so a discussed sub-concept that is plainly the same
- * subject as an existing article — the article title minus a generic suffix
- * ("<subject>" for an "<subject> Theory" article) — still resolves to it, while a
- * distinct subject or a purely-generic query does not. No model, no embedding.
- */
-export function resolveName(index: MemoryIndex, nameOrAlias: string): string | null {
-  const q = normalizeAlias(nameOrAlias);
-  for (const c of [q, q.replace(LEADING_ARTICLE_RE, "")]) {
-    if (!c) continue;
-    const stem = index.aliasToStem.get(c);
-    if (stem) return stem;
-  }
-  return nearNameMatch(nearResolver(index), q);
-}
-
-export interface Neighbors {
-  outbound: string[];
-  inbound: string[];
-}
-
-/**
- * The article's resolved [[wikilink]] neighbors: `outbound` it points at,
- * `inbound` that point at it — including infobox entity-link edges (e.g. an
- * entity's `<entity_key>: [[Linked Entity]]`), which is the navigation hop the read
- * path rides. Both lists are sorted; computed entirely from the in-memory graph.
- */
-export function neighbors(index: MemoryIndex, stem: string): Neighbors {
-  const outbound = [...(index.outboundByStem.get(stem) ?? [])];
-  const inbound: string[] = [];
-  for (const [from, targets] of index.outboundByStem) {
-    if (from !== stem && targets.includes(stem)) inbound.push(from);
-  }
-  inbound.sort((a, b) => a.localeCompare(b));
-  return { outbound, inbound };
-}
-
-// ---- deterministic snapshot (for tests / cache-equivalence checks) ----
-
-/** A stable JSON serialization of the index maps (sorted keys), so a warm and a
- *  cold rebuild can be asserted byte-identical. Excludes the build accounting
- *  (`parsed`/`reused`), which is per-build by design. */
-export function serializeMemoryIndex(index: MemoryIndex): string {
-  const dumpStringMap = (m: Map<string, string>): [string, string][] =>
-    [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-  const dumpListMap = (m: Map<string, string[]>): [string, string[]][] =>
-    [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-  const dumpInfobox = (m: Map<string, Infobox | null>): [string, Infobox | null][] =>
-    [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-  const dumpLeadMap = (m: Map<string, string | null>): [string, string | null][] =>
-    [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-  return JSON.stringify({
-    aliasToStem: dumpStringMap(index.aliasToStem),
-    categoryToStems: dumpListMap(index.categoryToStems),
-    seriesToStems: dumpListMap(index.seriesToStems),
-    kindToStems: dumpListMap(index.kindToStems),
-    typeToStems: dumpListMap(index.typeToStems),
-    infoboxByStem: dumpInfobox(index.infoboxByStem),
-    leadByStem: dumpLeadMap(index.leadByStem),
-    outboundByStem: dumpListMap(index.outboundByStem),
-  });
-}