@dzhechkov/harness-core 0.3.50 → 0.3.54

package/src/brain.ts

@@ -15,7 +15,7 @@
  * @packageDocumentation
  */
 
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
@@ -56,6 +56,10 @@ export interface BrainSource {
   readonly corpusVersion?: string;
   readonly lang?: string;
   readonly isbn?: string;
+  /** SPDX-ish license id — carried for repo sources (§8: refuse promoting unknown-license repos). */
+  readonly license?: string;
+  /** Relative path (from the brain home) to this source's capability card, e.g. `primers/<slug>.md`. */
+  readonly primer?: string;
   readonly addedTs: string;
 }
 
@@ -133,28 +137,58 @@ interface ProjRow {
   metadata: string | null;
 }
 
-/** Read the project's lexical book KB (all rows, or one `source`). Best-effort; honest errors. */
-async function readProjectRows(
-  depsRoot: string,
-  projectDbPath: string,
-  source: string | undefined,
-): Promise<{ rows: ProjRow[] } | { error: string }> {
-  const sqlite = resolveSqlite(depsRoot);
-  if ('error' in sqlite) return { error: sqlite.error };
+/** Reconstruct a {@link BookKU} from a raw `book_knowledge` row (shared by every reader below). */
+function rowToKu(r: ProjRow): BookKU {
+  const pages = jsonPages(r.pages);
+  const meta = jsonObj(r.metadata);
+  return {
+    book: r.book,
+    kuId: r.ku_id,
+    corpusVersion: r.corpus_version,
+    type: r.type,
+    name: r.name,
+    problem: r.problem,
+    content: r.content,
+    ...(r.chapter !== null ? { chapter: r.chapter } : {}),
+    ...(pages !== undefined ? { pages } : {}),
+    ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}),
+  };
+}
+
+/**
+ * Read reconstructed KUs from ANY `books.sqlite`-format lexical store (a project store, the brain
+ * store, or a per-source slice) — the single shared reader behind {@link promoteProjectToBrain},
+ * {@link buildPrimer}, {@link exportBrainSlice}, and {@link importBrainSlice}. `source` narrows to
+ * one book; default reads all. Synchronous (native `better-sqlite3` via `createRequire`) and
+ * best-effort: an absent store or unresolved dependency returns an honest `error`, never throws.
+ */
+export function readBookKus(opts: {
+  storePath: string;
+  depsRoot?: string;
+  source?: string;
+}): { kus: BookKU[]; error?: string } {
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  if (!existsSync(opts.storePath)) return { kus: [], error: `no book store at ${opts.storePath}` };
+  let Database: new (p: string, o?: object) => NativeDb;
+  try {
+    const req = createRequire(join(depsRoot, 'package.json'));
+    Database = req('better-sqlite3') as new (p: string, o?: object) => NativeDb;
+  } catch {
+    return { kus: [], error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
+  }
   try {
-    const { default: Database } = (await import(sqlite.url)) as { default: new (p: string, o?: object) => NativeDb };
-    const db = new Database(projectDbPath, { readonly: true });
+    const db = new Database(opts.storePath, { readonly: true });
     try {
       const cols = 'book, ku_id, corpus_version, type, name, problem, content, chapter, pages, metadata';
-      const rows = (source !== undefined
-        ? db.prepare(`SELECT ${cols} FROM book_knowledge WHERE book = ?`).all(source)
+      const rows = (opts.source !== undefined
+        ? db.prepare(`SELECT ${cols} FROM book_knowledge WHERE book = ?`).all(opts.source)
         : db.prepare(`SELECT ${cols} FROM book_knowledge`).all()) as ProjRow[];
-      return { rows };
+      return { kus: rows.map(rowToKu) };
     } finally {
       db.close();
     }
   } catch (err) {
-    return { error: `read project book KB failed: ${err instanceof Error ? err.message : String(err)}` };
+    return { kus: [], error: `read book KB failed: ${err instanceof Error ? err.message : String(err)}` };
   }
 }
 
@@ -220,108 +254,471 @@ function worthScore(meta: Record<string, unknown>): number {
   }
 }
 
+// ──────────────────────────────────────── Primers ───────────────────────────────────────────
+
+/** Clamp + whitespace-collapse a one-line problem for the primer (deterministic). */
+function primerLine(s: string, max = 120): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+
 /**
- * Promote a PROJECT's digitized book KB into the durable cross-project brain (ADR-001 P0
- * `book-brain-register`). Reads the project's lexical `books.sqlite`, groups KUs by book, and for
- * each book mirrors them into the brain's lexical store ({@link putBookKnowledge}) and re-embeds
- * them into the brain's vector store ({@link indexPatternsToAgentdb}), then refreshes the registry.
- *
- * **Non-clobbering:** promoting the same book twice does not duplicate — the lexical upsert keys on
- * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ * Render a source's capability card (ADR-001 §5.4) from its registry entry + KUs — PURE and
+ * DETERMINISTIC (no clock, no query): a header (slug/kind/kuCount/corpusVersion/isbn/lang/license),
+ * a KU-TYPE histogram (count per type, count-desc then type-asc), and the top ~8 decision/framework
+ * KUs (name + one-line problem, page-anchored), ranked by declared `worth` then `kuId`.
  */
-export async function promoteProjectToBrain(opts: {
-  projectRoot: string;
+function buildPrimerMarkdown(source: BrainSource, kus: readonly BookKU[]): string {
+  const lines: string[] = [`# Primer: ${source.slug}`, ''];
+  lines.push(`- kind: ${source.kind}`);
+  lines.push(`- KUs: ${source.kuCount}`);
+  if (source.corpusVersion !== undefined && source.corpusVersion !== '') lines.push(`- corpusVersion: ${source.corpusVersion}`);
+  if (source.isbn !== undefined) lines.push(`- isbn: ${source.isbn}`);
+  if (source.lang !== undefined) lines.push(`- lang: ${source.lang}`);
+  if (source.license !== undefined) lines.push(`- license: ${source.license}`);
+  lines.push('');
+
+  // KU-type histogram — count per type, count-desc then type-asc (stable, deterministic).
+  const counts = new Map<string, number>();
+  for (const k of kus) counts.set(k.type, (counts.get(k.type) ?? 0) + 1);
+  const hist = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  lines.push('## KU types');
+  for (const [type, n] of hist) lines.push(`- ${type}: ${n}`);
+  lines.push('');
+
+  // Top decision-grade KUs — worth-desc then kuId-asc, first 8; page-anchored provenance. Match the
+  // ACTUAL KU type vocabulary (decision-framework / tradeoff-table / methodology / heuristic), not the
+  // legacy 'decision'/'framework' shorthands that never occur in real KUs (primer showed _none_).
+  const DECISION_TYPES = new Set(['decision-framework', 'tradeoff-table', 'methodology', 'heuristic', 'decision', 'framework']);
+  const top = kus
+    .filter((k) => DECISION_TYPES.has(k.type))
+    .sort((a, b) => worthScore(b.metadata ?? {}) - worthScore(a.metadata ?? {}) || a.kuId.localeCompare(b.kuId))
+    .slice(0, 8);
+  lines.push('## Top decision moments');
+  if (top.length === 0) {
+    lines.push('_none_');
+  } else {
+    top.forEach((k, i) => {
+      const ch = k.chapter !== undefined && k.chapter !== '' ? ` гл.${k.chapter}` : '';
+      const pg = k.pages !== undefined && k.pages.length > 0 ? ` с.${k.pages.join('–')}` : '';
+      lines.push(`${i + 1}. ${k.name} — ${primerLine(k.problem)}${ch}${pg}`);
+    });
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Synthesize a {@link BrainSource} for a primer when the registry has no entry yet (metadata-derived). */
+function sourceFromKus(slug: string, kus: readonly BookKU[]): BrainSource {
+  const meta0 = kus[0]?.metadata ?? {};
+  const corpusVersion = kus[0]?.corpusVersion ?? '';
+  return {
+    slug,
+    kind: 'book',
+    kuCount: kus.length,
+    addedTs: '',
+    ...(corpusVersion !== '' ? { corpusVersion } : {}),
+    ...(typeof meta0['lang'] === 'string' ? { lang: meta0['lang'] as string } : {}),
+    ...(typeof meta0['isbn'] === 'string' ? { isbn: meta0['isbn'] as string } : {}),
+    ...(typeof meta0['license'] === 'string' ? { license: meta0['license'] as string } : {}),
+  };
+}
+
+/**
+ * Build a source's capability card (ADR-001 §5.4) by reading its KUs from the brain lexical store
+ * ({@link readBookKus}) + its registry entry, then rendering {@link buildPrimerMarkdown}. Best-effort:
+ * a missing store/source returns an honest `error` with empty `markdown`, never throws.
+ */
+export async function buildPrimer(opts: {
+  brainHome?: string;
   depsRoot?: string;
+  slug: string;
+}): Promise<{ markdown: string; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  if (read.error !== undefined) return { markdown: '', error: read.error };
+  if (read.kus.length === 0) return { markdown: '', error: `no KUs for source '${opts.slug}' in brain` };
+  const source = readRegistry(home).sources[opts.slug] ?? sourceFromKus(opts.slug, read.kus);
+  return { markdown: buildPrimerMarkdown(source, read.kus) };
+}
+
+/** Write a source's primer to `<brainHome>/primers/<slug>.md` (mkdir). Best-effort; honest error. */
+export async function writePrimer(opts: {
   brainHome?: string;
-  source?: string;
-  addedTs: string;
-}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  depsRoot?: string;
+  slug: string;
+}): Promise<{ path: string; error?: string }> {
   const home = opts.brainHome ?? brainHome();
-  const depsRoot = opts.depsRoot ?? opts.projectRoot;
-  const projectDbPath = bookKbPath(opts.projectRoot);
-  if (!existsSync(projectDbPath)) return { sources: [], kus: 0, error: 'no project book KB' };
+  const path = join(home, 'primers', `${opts.slug}.md`);
+  const built = await buildPrimer(opts);
+  if (built.error !== undefined) return { path, error: built.error };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, built.markdown);
+    return { path };
+  } catch (err) {
+    return { path, error: `write primer failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
 
-  const read = await readProjectRows(depsRoot, projectDbPath, opts.source);
-  if ('error' in read) return { sources: [], kus: 0, error: read.error };
-  if (read.rows.length === 0) return { sources: [], kus: 0 };
+// ──────────────────────────────────────── Mirror ────────────────────────────────────────────
 
-  // Group rows by book (each book is one promote unit + one registry entry).
-  const byBook = new Map<string, ProjRow[]>();
-  for (const r of read.rows) {
-    const bucket = byBook.get(r.book);
-    if (bucket) bucket.push(r);
-    else byBook.set(r.book, [r]);
+/**
+ * The ONE shared "mirror KUs into the brain + register + primer" path behind
+ * {@link promoteProjectToBrain}, {@link importBrainSlice}, and {@link registerKusToBrain}. Groups
+ * the KUs by `book` and, per book: (1) lexical-mirrors via the idempotent {@link putBookKnowledge},
+ * (2) re-embeds via {@link indexPatternsToAgentdb} after pre-deleting the book's stale vectors, and
+ * (3) writes/refreshes the registry entry — then generates `primers/<slug>.md` best-effort (a primer
+ * failure never fails the mirror) and stores its relative path on the entry.
+ *
+ * **Non-clobbering:** mirroring the same book twice does not duplicate — the lexical upsert keys on
+ * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ */
+async function mirrorKusToBrain(opts: {
+  home: string;
+  depsRoot: string;
+  kus: readonly BookKU[];
+  kind: 'book' | 'repo' | 'paper';
+  addedTs: string;
+  lang?: string;
+  license?: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const { home, depsRoot } = opts;
+  if (opts.kus.length === 0) return { sources: [], kus: 0 };
+
+  // Group KUs by book (each book is one mirror unit + one registry entry).
+  const byBook = new Map<string, BookKU[]>();
+  for (const k of opts.kus) {
+    const bucket = byBook.get(k.book);
+    if (bucket) bucket.push(k);
+    else byBook.set(k.book, [k]);
   }
 
   const reg = readRegistry(home);
   const sources: Record<string, BrainSource> = { ...reg.sources };
-  const promoted: string[] = [];
+  const mirrored: string[] = [];
   let totalKus = 0;
   let firstError: string | undefined;
 
-  for (const [book, rows] of byBook) {
+  for (const [book, kus] of byBook) {
     // 1. Lexical mirror — reuse the idempotent upsert, pointed at the brain store.
-    const kus: BookKU[] = rows.map((r) => {
-      const pages = jsonPages(r.pages);
-      const meta = jsonObj(r.metadata);
-      return {
-        book: r.book,
-        kuId: r.ku_id,
-        corpusVersion: r.corpus_version,
-        type: r.type,
-        name: r.name,
-        problem: r.problem,
-        content: r.content,
-        ...(r.chapter !== null ? { chapter: r.chapter } : {}),
-        ...(pages !== undefined ? { pages } : {}),
-        ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}),
-      };
-    });
     const lex = await putBookKnowledge(depsRoot, kus, { dbPath: brainBooksPath(home) });
     if (lex.error !== undefined && firstError === undefined) firstError = lex.error;
 
     // 2. Vector re-embed — pre-delete this book's stale vectors (insert-only primitive), then index.
     await deleteBrainVectors(depsRoot, brainAgentdbPath(home), book);
-    const vecRows: AgentdbRow[] = rows.map((r) => {
-      const meta = jsonObj(r.metadata);
-      return {
-        taskType: 'book-knowledge',
-        text: `${r.name}: ${r.problem}`,
-        score: worthScore(meta),
-        tags: ['book', r.book, r.type],
-        metadata: {
-          chapter: r.chapter,
-          pages: jsonPages(r.pages) ?? null,
-          ku_id: r.ku_id,
-          corpus_version: r.corpus_version,
-        },
-      };
-    });
+    const vecRows: AgentdbRow[] = kus.map((k) => ({
+      taskType: 'book-knowledge',
+      text: `${k.name}: ${k.problem}`,
+      score: worthScore(k.metadata ?? {}),
+      tags: ['book', k.book, k.type],
+      metadata: {
+        chapter: k.chapter ?? null,
+        pages: k.pages ?? null,
+        ku_id: k.kuId,
+        corpus_version: k.corpusVersion,
+      },
+    }));
     const vec = await indexPatternsToAgentdb(depsRoot, vecRows, { dbPath: brainAgentdbPath(home) });
     if (vec.error !== undefined && firstError === undefined) firstError = vec.error;
 
-    // 3. Registry entry for this book — corpus_version/lang/isbn from the first row's metadata.
-    const meta0 = jsonObj(rows[0]!.metadata);
-    const corpusVersion = rows[0]!.corpus_version;
-    const lang = typeof meta0['lang'] === 'string' ? (meta0['lang'] as string) : undefined;
+    // 3. Registry entry — corpus_version/lang/isbn/license from opts (explicit) then first KU's metadata.
+    const meta0 = kus[0]!.metadata ?? {};
+    const corpusVersion = kus[0]!.corpusVersion;
+    const lang = opts.lang ?? (typeof meta0['lang'] === 'string' ? (meta0['lang'] as string) : undefined);
     const isbn = typeof meta0['isbn'] === 'string' ? (meta0['isbn'] as string) : undefined;
-    sources[book] = {
+    const license = opts.license ?? (typeof meta0['license'] === 'string' ? (meta0['license'] as string) : undefined);
+    const entry: BrainSource = {
       slug: book,
-      kind: 'book',
-      kuCount: rows.length,
+      kind: opts.kind,
+      kuCount: kus.length,
       addedTs: opts.addedTs,
       ...(corpusVersion !== undefined && corpusVersion !== '' ? { corpusVersion } : {}),
       ...(lang !== undefined ? { lang } : {}),
       ...(isbn !== undefined ? { isbn } : {}),
+      ...(license !== undefined ? { license } : {}),
     };
-    promoted.push(book);
-    totalKus += rows.length;
+
+    // 4. Primer — best-effort: a primer failure must not fail the mirror. Store the relative path.
+    let primerRel: string | undefined;
+    try {
+      const rel = join('primers', `${book}.md`);
+      const primerPath = join(home, rel);
+      mkdirSync(dirname(primerPath), { recursive: true });
+      writeFileSync(primerPath, buildPrimerMarkdown(entry, kus));
+      primerRel = rel;
+    } catch {
+      /* primer is advisory — never fail the mirror on it */
+    }
+
+    sources[book] = primerRel !== undefined ? { ...entry, primer: primerRel } : entry;
+    mirrored.push(book);
+    totalKus += kus.length;
   }
 
   writeRegistry(home, { version: 1, sources });
   return firstError !== undefined
-    ? { sources: promoted, kus: totalKus, error: firstError }
-    : { sources: promoted, kus: totalKus };
+    ? { sources: mirrored, kus: totalKus, error: firstError }
+    : { sources: mirrored, kus: totalKus };
+}
+
+// ──────────────────────────────────────── Promote ───────────────────────────────────────────
+
+/**
+ * Promote a PROJECT's digitized book KB into the durable cross-project brain (ADR-001 P0
+ * `book-brain-register`). Reads the project's lexical `books.sqlite` ({@link readBookKus}) and mirrors
+ * every KU into the brain via the shared {@link mirrorKusToBrain} path (lexical + vector + registry +
+ * primer). `kind: 'book'`.
+ *
+ * **Non-clobbering:** promoting the same book twice does not duplicate — the lexical upsert keys on
+ * `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
+ */
+export async function promoteProjectToBrain(opts: {
+  projectRoot: string;
+  depsRoot?: string;
+  brainHome?: string;
+  source?: string;
+  addedTs: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? opts.projectRoot;
+  const projectDbPath = bookKbPath(opts.projectRoot);
+  if (!existsSync(projectDbPath)) return { sources: [], kus: 0, error: 'no project book KB' };
+
+  const read = readBookKus({ storePath: projectDbPath, depsRoot, ...(opts.source !== undefined ? { source: opts.source } : {}) });
+  if (read.error !== undefined) return { sources: [], kus: 0, error: read.error };
+  if (read.kus.length === 0) return { sources: [], kus: 0 };
+
+  return mirrorKusToBrain({ home, depsRoot, kus: read.kus, kind: 'book', addedTs: opts.addedTs });
+}
+
+// ────────────────────────────────────────── Update ──────────────────────────────────────────
+
+/**
+ * `dz brain update <slug>` backend (ADR-001 §11 P3 — non-destructive refresh). The project has
+ * re-ingested a source's book at a NEW `corpus_version`; this re-reads that source's CURRENT KUs
+ * from the PROJECT lexical store ({@link readBookKus} at the project `bookKbPath`, `source=slug`)
+ * and re-mirrors them into the brain via the shared {@link mirrorKusToBrain} path.
+ *
+ * **Non-clobbering + non-destructive:** the per-source stale-corpus eviction inside the reused
+ * `putBookKnowledge` upsert evicts THIS source's old-corpus rows and upserts the new ones, while
+ * OTHER sources are untouched. The primer is refreshed as part of the mirror. Reports the
+ * before/after KU counts (read directly from the brain, so `after` reflects the post-eviction set)
+ * and the new `corpusVersion`.
+ *
+ * Honest failure, no partial state: an unregistered source, or a project with no KUs for it, returns
+ * an `error` before any write happens.
+ */
+export async function updateBrainSource(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  slug: string;
+  projectRoot: string;
+  addedTs: string;
+}): Promise<{ before: number; after: number; corpusVersion?: string; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? opts.projectRoot;
+
+  // Gate 1: the source must already be in the registry (update refreshes, it does not add).
+  const existing = readRegistry(home).sources[opts.slug];
+  if (existing === undefined) {
+    return { before: 0, after: 0, error: `source '${opts.slug}' is not registered in the brain (use promote/register first)` };
+  }
+
+  // `before` = the source's CURRENT row count in the brain (read directly, not the cached registry
+  // count) so the delta reflects real state.
+  const beforeRead = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  const before = beforeRead.kus.length;
+
+  // Gate 2: the project must hold the re-ingested KUs for THIS source (no partial state on failure).
+  const projectDbPath = bookKbPath(opts.projectRoot);
+  if (!existsSync(projectDbPath)) {
+    return { before, after: before, error: 'no project book KB' };
+  }
+  const read = readBookKus({ storePath: projectDbPath, depsRoot, source: opts.slug });
+  if (read.error !== undefined) return { before, after: before, error: read.error };
+  if (read.kus.length === 0) {
+    return { before, after: before, error: `project has no KUs for source '${opts.slug}'` };
+  }
+
+  // Re-mirror through the shared path — the stale-corpus eviction makes this refresh non-destructive
+  // for this source and non-clobbering for others; the primer is rewritten inside the mirror.
+  const mirror = await mirrorKusToBrain({
+    home,
+    depsRoot,
+    kus: read.kus,
+    kind: existing.kind,
+    addedTs: opts.addedTs,
+    ...(existing.lang !== undefined ? { lang: existing.lang } : {}),
+    ...(existing.license !== undefined ? { license: existing.license } : {}),
+  });
+
+  // `after` from the brain itself — proves the eviction landed (no orphan old-corpus rows).
+  const afterRead = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  const after = afterRead.kus.length;
+  const newCorpus = read.kus[0]?.corpusVersion;
+
+  const out: { before: number; after: number; corpusVersion?: string; error?: string } = { before, after };
+  if (newCorpus !== undefined && newCorpus !== '') out.corpusVersion = newCorpus;
+  if (mirror.error !== undefined) out.error = mirror.error;
+  return out;
+}
+
+// ────────────────────────────────────── Slices / ingest ─────────────────────────────────────
+
+/**
+ * Export ONE source's KUs from the brain as a STANDALONE lexical-only `books.sqlite` slice at
+ * `outPath` (ADR-001 §8.1). Reads via {@link readBookKus} and writes via {@link putBookKnowledge} —
+ * lexical only; vectors re-embed on import. This is the portable, per-book shareable unit.
+ */
+export async function exportBrainSlice(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  slug: string;
+  outPath: string;
+}): Promise<{ kuCount: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: brainBooksPath(home), depsRoot, source: opts.slug });
+  if (read.error !== undefined) return { kuCount: 0, error: read.error };
+  if (read.kus.length === 0) return { kuCount: 0, error: `no KUs for source '${opts.slug}' in brain` };
+  const put = await putBookKnowledge(depsRoot, read.kus, { dbPath: opts.outPath });
+  if (put.error !== undefined) return { kuCount: 0, error: put.error };
+  return { kuCount: read.kus.length };
+}
+
+/**
+ * Import a per-book slice ({@link exportBrainSlice} output, or a pack's `brain/<slug>.sqlite`) into
+ * the brain (ADR-001 §8.1). Reads the slice's KUs ({@link readBookKus}) and mirrors them via the same
+ * non-clobbering {@link mirrorKusToBrain} path as promote (upsert + re-embed + registry + primer).
+ */
+export async function importBrainSlice(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  slicePath: string;
+  addedTs: string;
+}): Promise<{ sources: string[]; kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: opts.slicePath, depsRoot });
+  if (read.error !== undefined) return { sources: [], kus: 0, error: read.error };
+  if (read.kus.length === 0) return { sources: [], kus: 0 };
+  return mirrorKusToBrain({ home, depsRoot, kus: read.kus, kind: 'book', addedTs: opts.addedTs });
+}
+
+/**
+ * Register an array of already-shaped KUs (from a repo deep-walk, §6, or raw JSON) into the brain via
+ * the shared {@link mirrorKusToBrain} path — the CLI `--from-kus` backend. `slug` is authoritative:
+ * every KU is registered under it (so a repo's `book` field is normalized to the source slug). The
+ * registry entry carries `kind` and, for `repo`, `license`.
+ */
+/**
+ * SPDX ids the license gate treats as clearly-permissive (auto-pass for repo ingest). Anything else
+ * — including an absent license — is refused unless `override:true`. Kept deliberately small and
+ * conservative (ADR §8: repos carry their own licenses; the brain must not silently ingest
+ * unknown/incompatible source into a redistributable slice).
+ */
+export const PERMISSIVE_LICENSES: readonly string[] = [
+  'MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'ISC', 'Unlicense', 'CC0-1.0', '0BSD', 'MIT-0',
+];
+
+export async function registerKusToBrain(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+  kus: readonly BookKU[];
+  slug: string;
+  kind: 'repo' | 'book' | 'paper';
+  addedTs: string;
+  lang?: string;
+  license?: string;
+  override?: boolean;
+}): Promise<{ kus: number; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  if (opts.kus.length === 0) return { kus: 0 };
+  // License gate (ADR §8) — repo/paper sources must declare a permissive license, else refuse unless
+  // explicitly overridden. Books promoted from a digitized pack are exempt (own CP5 flow). No writes
+  // happen before this check, so a refusal never leaves a partial brain.
+  if (opts.kind !== 'book' && opts.override !== true) {
+    const lic = opts.license;
+    if (lic === undefined || lic === '') {
+      return { kus: 0, error: `refusing to ingest '${opts.slug}' (${opts.kind}) with no --license; pass a permissive SPDX id (${PERMISSIVE_LICENSES.join(', ')}) or --override` };
+    }
+    if (!PERMISSIVE_LICENSES.includes(lic)) {
+      return { kus: 0, error: `refusing to ingest '${opts.slug}': license '${lic}' is not in the permissive allow-list (${PERMISSIVE_LICENSES.join(', ')}); pass --override to ingest anyway` };
+    }
+  }
+  // Normalize every KU under the source slug so the batch shares one `book` (putBookKnowledge's key).
+  const kus = opts.kus.map((k) => (k.book === opts.slug ? k : { ...k, book: opts.slug }));
+  const mirror = await mirrorKusToBrain({
+    home,
+    depsRoot,
+    kus,
+    kind: opts.kind,
+    addedTs: opts.addedTs,
+    ...(opts.lang !== undefined ? { lang: opts.lang } : {}),
+    ...(opts.license !== undefined ? { license: opts.license } : {}),
+  });
+  return mirror.error !== undefined ? { kus: mirror.kus, error: mirror.error } : { kus: mirror.kus };
+}
+
+// ──────────────────────────────────────── Rerank ────────────────────────────────────────────
+
+/** FTS5's default `limit` when none is passed (mirrors {@link queryBookKnowledge}). */
+const DEFAULT_QUERY_LIMIT = 10;
+
+/**
+ * Field weights for the deterministic reranker (ADR-001 §11 P3 / G3): a query term matched in a
+ * KU's `name` outranks one only in its `problem`, which outranks one only in `content`. Because a
+ * term contributes its BEST field's weight once, summing over distinct terms folds together (a)
+ * term COVERAGE — more distinct query terms present ⇒ a higher sum — and (b) FIELD WEIGHT.
+ */
+const RERANK_FIELD_WEIGHT = { name: 3, problem: 2, content: 1 } as const;
+
+/**
+ * KU types that carry a small, deterministic type PRIOR — a decision-grade unit
+ * (decision-framework / tradeoff-table / methodology) sits slightly above a bare `definition` when
+ * coverage + field weight tie. Kept below the smallest field-weight step (1) so it only breaks
+ * near-ties and never overrides a genuinely better term/field match.
+ */
+const RERANK_TYPE_PRIOR = new Set<string>(['decision-framework', 'tradeoff-table', 'methodology']);
+const RERANK_PRIOR_BONUS = 0.5;
+
+/** Over-fetch cap for the rerank pass — bounds work while leaving room for a `limit*3` window. */
+const RERANK_OVERFETCH_CAP = 200;
+
+/**
+ * A DETERMINISTIC lexical reranker (ADR-001 §11 P3 / G3) — lifts precision on the top-K without a
+ * model dependency, so the sync grounding path stays fast + offline. Scores each hit against the
+ * query's CONTENT TERMS (reusing {@link contentTerms}) by (a) term COVERAGE, (b) a FIELD WEIGHT
+ * (name > problem > content), and (c) a small type PRIOR, then returns the top-`limit` reordered.
+ * Fully deterministic: no clock, no random, stable tie-break by `kuId`.
+ *
+ * This is deliberately lexical: an ML cross-encoder reranker is OUT OF SCOPE for the sync path (it
+ * would make grounding slow + online + non-deterministic). A future model reranker is a drop-in
+ * swap BEHIND this same `(query, hits, opts) → hits` signature — callers never change.
+ */
+export function rerankHits(query: string, hits: BookKUHit[], opts?: { limit?: number }): BookKUHit[] {
+  const terms = contentTerms(query);
+  const scored = hits.map((hit, idx) => {
+    const name = hit.name.toLowerCase();
+    const problem = hit.problem.toLowerCase();
+    const content = hit.content.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      // Each distinct term contributes its BEST field's weight once (coverage × field weight).
+      if (name.includes(t)) score += RERANK_FIELD_WEIGHT.name;
+      else if (problem.includes(t)) score += RERANK_FIELD_WEIGHT.problem;
+      else if (content.includes(t)) score += RERANK_FIELD_WEIGHT.content;
+    }
+    if (RERANK_TYPE_PRIOR.has(hit.type)) score += RERANK_PRIOR_BONUS;
+    return { hit, score, idx };
+  });
+  // Deterministic order: score desc, then stable tie-break by kuId (never by input position/clock).
+  scored.sort((a, b) => b.score - a.score || a.hit.kuId.localeCompare(b.hit.kuId));
+  const limit = opts?.limit ?? hits.length;
+  return scored.slice(0, limit).map((s) => s.hit);
 }
 
 // ───────────────────────────────────────── Query ────────────────────────────────────────────
@@ -329,6 +726,9 @@ export async function promoteProjectToBrain(opts: {
 /**
  * Cross-source lexical recall over the whole brain — a thin, brain-home-scoped wrapper over
  * {@link queryBookKnowledge}. `source` narrows to one source; default is cross-source. Never throws.
+ *
+ * `rerank` (default **false** — pure FTS order stays the default so nothing regresses): when true,
+ * over-fetch (`limit*3`, capped) then {@link rerankHits} down to `limit` for on-point top-K.
  */
 export async function queryBrain(opts: {
   query: string;
@@ -337,14 +737,26 @@ export async function queryBrain(opts: {
   source?: string;
   limit?: number;
   match?: 'all' | 'any';
+  rerank?: boolean;
 }): Promise<{ hits: BookKUHit[]; error?: string }> {
   const home = opts.brainHome ?? brainHome();
   const depsRoot = opts.depsRoot ?? process.cwd();
+  const rerank = opts.rerank === true;
+  const effLimit = opts.limit ?? DEFAULT_QUERY_LIMIT;
+
   const qopts: { dbPath: string; book?: string; limit?: number; match?: 'all' | 'any' } = { dbPath: brainBooksPath(home) };
   if (opts.source !== undefined) qopts.book = opts.source;
-  if (opts.limit !== undefined) qopts.limit = opts.limit;
+  if (rerank) {
+    // Over-fetch a wider window so the reranker has real candidates to reorder, then trim to limit.
+    qopts.limit = Math.min(effLimit * 3, RERANK_OVERFETCH_CAP);
+  } else if (opts.limit !== undefined) {
+    qopts.limit = opts.limit;
+  }
   if (opts.match !== undefined) qopts.match = opts.match;
-  return queryBookKnowledge(depsRoot, opts.query, qopts);
+
+  const res = await queryBookKnowledge(depsRoot, opts.query, qopts);
+  if (!rerank || res.error !== undefined) return res;
+  return { hits: rerankHits(opts.query, res.hits, { limit: effLimit }) };
 }
 
 // ──────────────────────────────────────── Grounding ─────────────────────────────────────────
@@ -430,10 +842,12 @@ export async function groundPrompt(opts: {
     // matching topical term surfaces KUs even when other prompt terms (a verb, filler) miss — the
     // fix for real-prompt silence (AND required every term to co-occur). Rank ordering + top-K keep
     // it precise; the stopword filter keeps generic prompts silent.
-    const query: { query: string; brainHome?: string; depsRoot?: string; source?: string; limit: number; match: 'any' } = {
+    const query: { query: string; brainHome?: string; depsRoot?: string; source?: string; limit: number; match: 'any'; rerank: true } = {
       query: terms.join(' '),
       limit: opts.k ?? 5,
       match: 'any',
+      // Grounding wants the most ON-POINT citation first — pass through the deterministic reranker.
+      rerank: true,
     };
     if (opts.brainHome !== undefined) query.brainHome = opts.brainHome;
     if (opts.depsRoot !== undefined) query.depsRoot = opts.depsRoot;