@dzhechkov/harness-core 0.3.50 → 0.3.54

package/dist/brain.js

@@ -14,7 +14,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';
@@ -82,27 +82,57 @@ function resolveSqlite(depsRoot) {
         return { error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
     }
 }
-/** Read the project's lexical book KB (all rows, or one `source`). Best-effort; honest errors. */
-async function readProjectRows(depsRoot, projectDbPath, source) {
-    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) {
+    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) {
+    const depsRoot = opts.depsRoot ?? process.cwd();
+    if (!existsSync(opts.storePath))
+        return { kus: [], error: `no book store at ${opts.storePath}` };
+    let Database;
     try {
-        const { default: Database } = (await import(sqlite.url));
-        const db = new Database(projectDbPath, { readonly: true });
+        const req = createRequire(join(depsRoot, 'package.json'));
+        Database = req('better-sqlite3');
+    }
+    catch {
+        return { kus: [], error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
+    }
+    try {
+        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());
-            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)}` };
     }
 }
 /**
@@ -168,119 +198,446 @@ function worthScore(meta) {
             return 0.5;
     }
 }
+// ──────────────────────────────────────── Primers ───────────────────────────────────────────
+/** Clamp + whitespace-collapse a one-line problem for the primer (deterministic). */
+function primerLine(s, max = 120) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+/**
+ * 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`.
+ */
+function buildPrimerMarkdown(source, kus) {
+    const lines = [`# 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();
+    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, kus) {
+    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'] } : {}),
+        ...(typeof meta0['isbn'] === 'string' ? { isbn: meta0['isbn'] } : {}),
+        ...(typeof meta0['license'] === 'string' ? { license: meta0['license'] } : {}),
+    };
+}
 /**
- * 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.
+ * 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) {
+    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) {
+    const home = opts.brainHome ?? brainHome();
+    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)}` };
+    }
+}
+// ──────────────────────────────────────── Mirror ────────────────────────────────────────────
+/**
+ * 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:** promoting the same book twice does not duplicate — the lexical upsert keys on
+ * **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.
  */
-export async function promoteProjectToBrain(opts) {
-    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 = await readProjectRows(depsRoot, projectDbPath, opts.source);
-    if ('error' in read)
-        return { sources: [], kus: 0, error: read.error };
-    if (read.rows.length === 0)
+async function mirrorKusToBrain(opts) {
+    const { home, depsRoot } = opts;
+    if (opts.kus.length === 0)
         return { sources: [], kus: 0 };
-    // Group rows by book (each book is one promote unit + one registry entry).
+    // Group KUs by book (each book is one mirror unit + one registry entry).
     const byBook = new Map();
-    for (const r of read.rows) {
-        const bucket = byBook.get(r.book);
+    for (const k of opts.kus) {
+        const bucket = byBook.get(k.book);
         if (bucket)
-            bucket.push(r);
+            bucket.push(k);
         else
-            byBook.set(r.book, [r]);
+            byBook.set(k.book, [k]);
     }
     const reg = readRegistry(home);
     const sources = { ...reg.sources };
-    const promoted = [];
+    const mirrored = [];
     let totalKus = 0;
     let firstError;
-    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 = 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 = 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 = 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'] : 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'] : undefined);
         const isbn = typeof meta0['isbn'] === 'string' ? meta0['isbn'] : undefined;
-        sources[book] = {
+        const license = opts.license ?? (typeof meta0['license'] === 'string' ? meta0['license'] : undefined);
+        const entry = {
             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;
+        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) {
+    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) {
+    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, 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) {
+    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) {
+    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 = [
+    'MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 'ISC', 'Unlicense', 'CC0-1.0', '0BSD', 'MIT-0',
+];
+export async function registerKusToBrain(opts) {
+    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 };
+/**
+ * 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(['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, hits, opts) {
+    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 ────────────────────────────────────────────
 /**
  * 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) {
     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: brainBooksPath(home) };
     if (opts.source !== undefined)
         qopts.book = opts.source;
-    if (opts.limit !== undefined)
+    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 ─────────────────────────────────────────
 /**
@@ -360,6 +717,8 @@ export async function groundPrompt(opts) {
             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;