neurain 0.1.0-alpha.0

package/src/core/recall.mjs

@@ -0,0 +1,1802 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { absPath, compactStamp, ensureDir, isTextFile, readText, relPath, safeResolve, sha256, timestamp, walkFiles } from './fs.mjs';
+import { appendJournalEvent, listJournalEvents, verifyJournal } from './journal.mjs';
+import { inferSensitivityFromPath } from './safety.mjs';
+import { alternativeForm, getProvider, tokenize } from './semantic.mjs';
+import { recallConfig } from './config.mjs';
+import { createSensitivityResolver } from './labels.mjs';
+import { kindForPath, listRecallMarkdownFiles, recallConfigErrors, resolveAreaDir, safeToIndex, scopeForArea, scopeForPath, titleForText } from './recall_corpus.mjs';
+import { buildLexicalContext, lexicalSearchWithContext } from './recall_lexical.mjs';
+import { benchRecall, scorecardRecall } from './recall_bench.mjs';
+
+const dbRel = '00_system/neurain/recall.sqlite';
+const receiptDirRel = 'output/receipts/recall';
+
+export async function recallCommand(args) {
+  const [subcommand, ...rest] = args._;
+  const root = absPath(rest[0] || args.root || process.cwd());
+  if (!subcommand || subcommand === 'status') return renderRecallStatus(root, args);
+  if (subcommand === 'rebuild') return renderRecallRebuild(root, args);
+  if (subcommand === 'search') return renderRecallSearch(root, { ...args, _: rest.slice(1) });
+  if (subcommand === 'semantic-search') return renderRecallSemanticSearch(root, { ...args, _: rest.slice(1) });
+  if (subcommand === 'hybrid-search') return renderRecallHybridSearch(root, { ...args, _: rest.slice(1) });
+  if (subcommand === 'lexical-search') return renderRecallLexicalSearch(root, { ...args, _: rest.slice(1) });
+  if (subcommand === 'live-eval') return renderRecallLiveEval(root, args);
+  if (subcommand === 'verify') return renderRecallVerify(root, args);
+  if (subcommand === 'eval') return renderRecallEval(root, args);
+  if (subcommand === 'bench') return renderRecallBench(root, args);
+  if (subcommand === 'scorecard') return renderRecallScorecard(root, args);
+  throw new Error(`Unknown recall command: ${subcommand}. Use "recall status", "recall rebuild", "recall search", "recall semantic-search", "recall hybrid-search", "recall lexical-search", "recall bench", "recall scorecard", "recall verify", or "recall eval".`);
+}
+
+export async function recallStatus(root) {
+  const sqlite = await sqliteCapability();
+  const dbPath = safeResolve(root, dbRel);
+  const exists = fs.existsSync(dbPath);
+  const payload = {
+    ok: true,
+    command: 'recall status',
+    root,
+    durable_write: false,
+    sqlite_available: sqlite.available,
+    fts5_available: false,
+    db_path: dbRel,
+    db_exists: exists,
+    markdown_fallback: true,
+    row_count: 0,
+    host_breakdown: {},
+    last_rebuild_at: null,
+    source_manifest_hash: null,
+    error: sqlite.error || null,
+  };
+  if (!sqlite.available || !exists) return payload;
+  let db;
+  try {
+    db = new sqlite.DatabaseSync(sqliteReadOnlyLocation(dbPath), { readOnly: true });
+    payload.fts5_available = Boolean(db.prepare("SELECT value FROM recall_meta WHERE key = 'fts5_available'").get()?.value === 'true');
+    payload.row_count = Number(db.prepare('SELECT COUNT(*) AS count FROM recall_docs').get()?.count || 0);
+    payload.host_breakdown = Object.fromEntries(db.prepare('SELECT host, COUNT(*) AS count FROM recall_docs GROUP BY host ORDER BY host').all().map((row) => [row.host, Number(row.count || 0)]));
+    payload.last_rebuild_at = db.prepare("SELECT value FROM recall_meta WHERE key = 'rebuilt_at'").get()?.value || null;
+    payload.source_manifest_hash = db.prepare("SELECT value FROM recall_meta WHERE key = 'source_manifest_hash'").get()?.value || null;
+  } catch (error) {
+    payload.ok = false;
+    payload.error = error.message;
+  } finally {
+    db?.close();
+  }
+  return payload;
+}
+
+export async function rebuildRecall(root, { dryRun = false } = {}) {
+  const sqlite = await sqliteCapability();
+  const recallCfg = recallConfig(root);
+  const docs = collectRecallDocs(root, { recallCfg });
+  const configErrors = recallConfigErrors(recallCfg);
+  const manifestHash = sha256(stableJson(docs.map((doc) => ({
+    doc_id: doc.doc_id,
+    path: doc.path,
+    source_hash: doc.source_hash,
+    sensitivity: doc.sensitivity,
+  }))));
+  const receiptRel = `${receiptDirRel}/${compactStamp()}-${process.pid}-${Date.now()}-${manifestHash.slice(0, 12)}-recall-rebuild.json`;
+  const result = {
+    ok: Boolean(dryRun || sqlite.available),
+    command: 'recall rebuild',
+    generated_at: timestamp(),
+    dry_run: Boolean(dryRun),
+    durable_write: Boolean(!dryRun && sqlite.available),
+    sqlite_available: sqlite.available,
+    fts5_available: false,
+    db_path: dbRel,
+    receipt_path: !dryRun && sqlite.available ? receiptRel : null,
+    indexed_count: docs.length,
+    source_manifest_hash: manifestHash,
+    markdown_canonical: true,
+    rebuildable_cache: true,
+    excluded_policy: 'private paths, unsafe summaries, raw source bodies, and generated folders are excluded',
+    config_errors: configErrors,
+    error: sqlite.error || null,
+  };
+  if (!sqlite.available || dryRun) return result;
+
+  const dbPath = safeResolve(root, dbRel);
+  const tmpPath = `${dbPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    ensureDir(path.dirname(dbPath));
+    buildSqliteIndex(sqlite.DatabaseSync, tmpPath, docs, manifestHash);
+    replaceSqliteFile(dbPath, tmpPath);
+    result.fts5_available = true;
+    const receiptAbs = safeResolve(root, receiptRel);
+    ensureDir(path.dirname(receiptAbs));
+    fs.writeFileSync(receiptAbs, `${JSON.stringify(result, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+  } finally {
+    cleanupSqliteSidecars(tmpPath);
+  }
+  return result;
+}
+
+export async function searchRecall(root, query, { top = 10, host = '', fallback = true, scope = '' } = {}) {
+  const sqlite = await sqliteCapability();
+  const dbPath = safeResolve(root, dbRel);
+  const payload = {
+    ok: true,
+    command: 'recall search',
+    root,
+    durable_write: false,
+    query: String(query || ''),
+    top: Number(top || 10),
+    host: String(host || ''),
+    scope: String(scope || ''),
+    sqlite_available: sqlite.available,
+    db_exists: fs.existsSync(dbPath),
+    source: 'sqlite_fts5',
+    results: [],
+    fallback_used: false,
+    error: sqlite.error || null,
+  };
+  if (!payload.query.trim()) throw new Error('Recall search requires a query.');
+  if (!sqlite.available || !fs.existsSync(dbPath)) {
+    if (!fallback) return payload;
+    return fallbackRecallSearch(root, payload);
+  }
+  let db;
+  try {
+    db = new sqlite.DatabaseSync(sqliteReadOnlyLocation(dbPath), { readOnly: true });
+    const ftsQuery = toFtsQuery(payload.query);
+    if (!ftsQuery) return payload;
+    const limit = Math.max(1, Math.min(Number(top || 10), 50));
+    const scopeFilter = String(scope || '');
+    const rows = db.prepare(`
+      SELECT d.path, d.kind, d.host, d.scope, d.sensitivity, d.title, d.snippet, d.source_hash, bm25(recall_fts) AS rank
+      FROM recall_fts
+      JOIN recall_docs d ON d.doc_id = recall_fts.doc_id
+      WHERE recall_fts MATCH ?
+        AND (? = '' OR d.host = ?)
+        AND (? = '' OR d.scope = ?)
+      ORDER BY rank ASC, d.path ASC
+      LIMIT ?
+    `).all(ftsQuery, String(host || ''), String(host || ''), scopeFilter, scopeFilter, limit);
+    payload.results = rows.map((row) => ({
+      path: row.path,
+      kind: row.kind,
+      host: row.host,
+      scope: row.scope,
+      sensitivity: row.sensitivity,
+      title: row.title,
+      snippet: row.snippet,
+      source_hash: row.source_hash,
+      score: Number((-Number(row.rank || 0)).toFixed(3)),
+    }));
+  } catch (error) {
+    payload.ok = false;
+    payload.error = error.message;
+    if (fallback) return fallbackRecallSearch(root, payload);
+  } finally {
+    db?.close();
+  }
+  return payload;
+}
+
+// E22: deterministic local lexical-semantic search over the canonical markdown
+// corpus. No SQLite required (markdown stays canonical, the default provider
+// needs no generated index), no model calls, no external calls. Private and
+// unsafe docs are excluded exactly like the exact-token path.
+export async function semanticSearchRecall(root, query, { top = 10, host = '', provider = 'local-lexical', minScore = 0.34, scope = '' } = {}) {
+  const prov = getProvider(provider);
+  const text = String(query || '');
+  if (!text.trim()) throw new Error('Recall semantic search requires a query.');
+  const limit = Math.max(1, Math.min(Number(top || 10), 50));
+  const hostFilter = String(host || '');
+  const scopeFilter = String(scope || '');
+  const floor = Number.isFinite(Number(minScore)) ? Math.max(0, Math.min(Number(minScore), 1)) : 0.34;
+  const docs = collectRecallDocs(root)
+    .filter((doc) => doc.sensitivity !== 'private')
+    .filter((doc) => !hostFilter || doc.host === hostFilter)
+    .filter((doc) => !scopeFilter || doc.scope === scopeFilter);
+  const scored = docs
+    .map((doc) => {
+      const scoredDoc = prov.score(text, `${doc.title} ${doc.body}`);
+      return { doc, score: Number(scoredDoc.score || 0), matched_terms: scoredDoc.matched_terms || [] };
+    })
+    .filter((item) => item.score >= floor)
+    // Deterministic ranking: score desc, then a stable content tie-break (snippet, then
+    // path) so equal-score results order the same way on every run regardless of random
+    // event ids in the path.
+    .sort((a, b) => b.score - a.score
+      || String(a.doc.snippet || '').localeCompare(String(b.doc.snippet || ''))
+      || String(a.doc.path || '').localeCompare(String(b.doc.path || '')))
+    .slice(0, limit);
+  return {
+    ok: true,
+    command: 'recall semantic-search',
+    root,
+    durable_write: false,
+    model_calls: Boolean(prov.model_call),
+    external_tool_calls: Boolean(prov.external_call),
+    query: text,
+    top: limit,
+    host: hostFilter,
+    scope: scopeFilter,
+    semantic_used: true,
+    embedding_provider: prov.name,
+    provider_kind: prov.kind,
+    provider_requires_index: Boolean(prov.requires_index),
+    llm_locked: Boolean(prov.llm_locked),
+    min_score: floor,
+    results: scored.map(({ doc, score, matched_terms }) => ({
+      path: doc.path,
+      kind: doc.kind,
+      host: doc.host,
+      scope: doc.scope,
+      sensitivity: doc.sensitivity,
+      title: doc.title,
+      snippet: doc.snippet,
+      source_hash: doc.source_hash,
+      score: Number(score.toFixed(4)),
+      matched_terms,
+    })),
+  };
+}
+
+// E23 follow-up: hybrid recall = exact-token UNION local lexical-semantic. Live-eval on real
+// content showed pure semantic can recall LESS than exact-token (it lacks the rarity/idf
+// weighting BM25 exact-token has, so it discriminates worse on real corpora with overlapping
+// vocabulary). Used as a SUPPLEMENT, semantic can only add paraphrase hits and never removes
+// an exact hit. `top` is the candidate depth for each branch, so the returned union can contain
+// up to `2 * top` rows when semantic-only catches exist. This is the robust recall a real user
+// should use. Read-only.
+export async function hybridSearchRecall(root, query, { top = 10, host = '', provider = 'local-lexical', minScore = 0.34, area = '', routing = 'auto' } = {}) {
+  const text = String(query || '');
+  if (!text.trim()) throw new Error('Recall hybrid search requires a query.');
+  const limit = Math.max(1, Math.min(Number(top || 10), 50));
+  const recallCfg = recallConfig(root);
+  const areaDir = resolveAreaDir(root, area, recallCfg);
+
+  // The engine index is a durable artifact readable over MCP, so private is
+  // excluded at collection time and never resurrected by a query-time flag.
+  // Explicitly scoping a private area therefore returns nothing (the vault keeps
+  // its own private-area lookup until a later wave designs an opt-in).
+  if (areaDir && createSensitivityResolver(root, recallCfg).isPrivateArea(areaDir)) {
+    return {
+      ok: true,
+      command: 'recall hybrid-search',
+      root,
+      durable_write: false,
+      model_calls: false,
+      external_tool_calls: false,
+      query: text,
+      top: limit,
+      host: String(host || ''),
+      area: String(area || ''),
+      area_dir: areaDir,
+      private_area_excluded: true,
+      strategy: 'private_area_excluded',
+      semantic_used: false,
+      results: [],
+      note: 'Area is marked private; private content is excluded from the recall index by design.',
+    };
+  }
+
+  const scope = scopeForArea(areaDir);
+  const routedEnabled = decideRouting(routing, areaDir, root, recallCfg);
+  const exact = await searchRecall(root, text, { top: limit, host, scope });
+  const semantic = await semanticSearchRecall(root, text, { top: limit, host, provider, minScore, scope });
+
+  if (!routedEnabled) {
+    const merged = mergeHybridResults(exact.results, semantic.results);
+    return {
+      ok: true,
+      command: 'recall hybrid-search',
+      root,
+      durable_write: false,
+      model_calls: Boolean(semantic.model_calls),
+      external_tool_calls: Boolean(semantic.external_tool_calls),
+      query: text,
+      top: limit,
+      host: String(host || ''),
+      area: String(area || ''),
+      area_dir: areaDir,
+      strategy: 'exact_token_union_semantic',
+      routed_used: false,
+      semantic_used: true,
+      embedding_provider: semantic.embedding_provider,
+      exact_result_count: exact.results.length,
+      semantic_result_count: semantic.results.length,
+      semantic_only_added: merged.filter((item) => item.matched_by === 'semantic').length,
+      result_cap: limit * 2,
+      results: merged,
+    };
+  }
+
+  const lexicalCtx = buildLexicalContext(root, { area: areaDir, recallCfg });
+  const lexical = lexicalSearchWithContext(lexicalCtx, text, { top: limit });
+  const merged = mergeRoutedHybridResults(lexical.results, exact.results, semantic.results);
+  return {
+    ok: true,
+    command: 'recall hybrid-search',
+    root,
+    durable_write: false,
+    model_calls: Boolean(semantic.model_calls),
+    external_tool_calls: Boolean(semantic.external_tool_calls),
+    query: text,
+    top: limit,
+    host: String(host || ''),
+    area: String(area || ''),
+    area_dir: areaDir,
+    strategy: 'routed_lexical_union_exact_union_semantic',
+    routed_used: true,
+    semantic_used: true,
+    embedding_provider: semantic.embedding_provider,
+    lexical_result_count: lexical.results.length,
+    exact_result_count: exact.results.length,
+    semantic_result_count: semantic.results.length,
+    semantic_only_added: merged.filter((item) => item.matched_by === 'semantic').length,
+    result_cap: limit * 3,
+    results: merged,
+  };
+}
+
+function mergeHybridResults(exactResults = [], semanticResults = []) {
+  const seen = new Set();
+  const merged = [];
+  for (const item of exactResults) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    merged.push({ ...item, matched_by: 'exact' });
+  }
+  for (const item of semanticResults) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    merged.push({ ...item, matched_by: 'semantic', matched_terms: item.matched_terms });
+  }
+  return merged;
+}
+
+// Routed 3-branch union with branch precedence (no cross-branch score
+// normalization): the routed lexical ranker first (its top-N IS the merged
+// top-N when it returns >= top), then exact-token FTS5 catches, then semantic
+// paraphrase catches. Dedupe by path; semantic only ever ADDS.
+function mergeRoutedHybridResults(lexicalResults = [], exactResults = [], semanticResults = []) {
+  const seen = new Set();
+  const merged = [];
+  for (const item of lexicalResults) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    merged.push({ ...item, matched_by: 'lexical' });
+  }
+  for (const item of exactResults) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    merged.push({ ...item, matched_by: 'exact' });
+  }
+  for (const item of semanticResults) {
+    if (seen.has(item.path)) continue;
+    seen.add(item.path);
+    merged.push({ ...item, matched_by: 'semantic', matched_terms: item.matched_terms });
+  }
+  return merged;
+}
+
+function registryHasAreas(root, recallCfg) {
+  try {
+    const registry = JSON.parse(fs.readFileSync(path.join(root, recallCfg.intel.registry), 'utf8'));
+    return Boolean(registry && registry.areas && Object.keys(registry.areas).length > 0);
+  } catch {
+    return false;
+  }
+}
+
+// Routing auto-enables only when there is something to route by: an explicit
+// --area, a registry with at least one area, or an explicit config flag. A bare
+// init-ed vault (empty-areas registry) keeps the legacy exact-union-semantic
+// behavior so existing back-compat is preserved.
+function decideRouting(routing, areaDir, root, recallCfg) {
+  if (routing === 'on' || routing === true) return true;
+  if (routing === 'off' || routing === false) return false;
+  if (recallCfg.routing.enabled === true) return true;
+  if (recallCfg.routing.enabled === false) return false;
+  return Boolean(areaDir) || registryHasAreas(root, recallCfg);
+}
+
+export async function verifyRecall(root) {
+  const status = await recallStatus(root);
+  const docs = collectRecallDocs(root);
+  const expectedHash = sha256(stableJson(docs.map((doc) => ({
+    doc_id: doc.doc_id,
+    path: doc.path,
+    source_hash: doc.source_hash,
+    sensitivity: doc.sensitivity,
+  }))));
+  return {
+    ok: Boolean(status.db_exists && status.source_manifest_hash === expectedHash && status.row_count === docs.length),
+    command: 'recall verify',
+    root,
+    durable_write: false,
+    db_path: dbRel,
+    db_exists: status.db_exists,
+    indexed_count: status.row_count,
+    expected_count: docs.length,
+    source_manifest_hash: status.source_manifest_hash,
+    expected_manifest_hash: expectedHash,
+    markdown_fallback: true,
+    mismatch: status.source_manifest_hash !== expectedHash || status.row_count !== docs.length,
+  };
+}
+
+export async function evaluateCrossHostRecall(root, {
+  top = 5,
+  minCases = 2,
+  maxCases = 50,
+  fixtureSize = 0,
+  privateProbeCount = 20,
+  unsafeProbeLimit = 50,
+  caseFile = '',
+} = {}) {
+  if (caseFile) {
+    return evaluateRecallCaseFile(root, {
+      top,
+      minCases,
+      caseFile,
+    });
+  }
+  if (Number(fixtureSize || 0) > 0) {
+    return evaluateSyntheticCrossHostRecall(root, {
+      top,
+      minCases: Math.max(Number(minCases || 2), Number(fixtureSize || 0)),
+      fixtureSize: Number(fixtureSize || 0),
+      privateProbeCount: Number(privateProbeCount || 20),
+    });
+  }
+  const journalIntegrity = verifyJournal(root);
+  const allEvents = listJournalEvents(root, { limit: 1000 }).events;
+  const events = allEvents
+    .filter((event) => event.sensitivity !== 'private')
+    .filter((event) => event.prompt_context_allowed !== false)
+    .filter((event) => event.safety?.indexing_allowed !== false && event.safety?.cross_host_allowed !== false)
+    .filter((event) => event.host && event.summary && safeToIndex(event.summary));
+  const hosts = [...new Set(events.map((event) => event.host))].sort();
+  const cases = [];
+  const limit = Math.max(1, Math.min(Number(top || 5), 10));
+  for (const event of events.slice(0, Math.max(1, Math.min(Number(maxCases || 50), 500)))) {
+    const query = queryForEvent(event);
+    if (!query) continue;
+    const sameHost = await searchRecall(root, query, { top: limit, host: event.host });
+    const hit = sameHost.results.some((item) => String(item.path || '').includes(event.event_id));
+    const sourceSupported = sameHost.results
+      .filter((item) => String(item.path || '').includes(event.event_id))
+      .some((item) => resultSupportsQuery(item, query));
+    const otherHosts = hosts.filter((host) => host !== event.host);
+    const isolationChecks = [];
+    for (const otherHost of otherHosts.slice(0, 3)) {
+      const other = await searchRecall(root, query, { top: limit, host: otherHost });
+      isolationChecks.push({
+        host: otherHost,
+        leaked: other.results.some((item) => String(item.path || '').includes(event.event_id)),
+      });
+    }
+    cases.push({
+      event_id: event.event_id,
+      host: event.host,
+      type: event.type,
+      query,
+      hit_at_top: hit,
+      source_supported: sourceSupported,
+      same_host_result_count: sameHost.results.length,
+      fallback_used: Boolean(sameHost.fallback_used),
+      isolated_from_other_hosts: isolationChecks.every((item) => !item.leaked),
+      isolation_checks: isolationChecks,
+    });
+  }
+  const evaluated = cases.length;
+  const hits = cases.filter((item) => item.hit_at_top).length;
+  const isolated = cases.filter((item) => item.isolated_from_other_hosts).length;
+  const supported = cases.filter((item) => item.source_supported).length;
+  const privateLeakageFindings = [];
+  const unsafeEvents = allEvents
+    .filter((event) => event.host && event.summary)
+    .filter((event) => (
+      event.sensitivity === 'private' ||
+      event.prompt_context_allowed === false ||
+      event.safety?.indexing_allowed === false ||
+      event.safety?.cross_host_allowed === false
+    ));
+  const requestedUnsafeLimit = Number(unsafeProbeLimit);
+  const unsafeLimit = Math.max(0, Math.min(Number.isFinite(requestedUnsafeLimit) ? requestedUnsafeLimit : 50, 1000));
+  for (const event of unsafeEvents.slice(0, unsafeLimit)) {
+    const query = queryForEvent(event);
+    if (!query) continue;
+    for (const host of hosts) {
+      const result = await searchRecall(root, query, { top: limit, host });
+      if (result.results.some((item) => String(item.path || '').includes(event.event_id))) {
+        privateLeakageFindings.push({ event_id: event.event_id, leaked_in_host: host });
+        break;
+      }
+    }
+  }
+  const hitAtTop = evaluated ? hits / evaluated : 0;
+  const isolationRate = evaluated ? isolated / evaluated : 0;
+  const sourceSupportRate = evaluated ? supported / evaluated : 0;
+  return {
+    ok: journalIntegrity.ok && evaluated >= Number(minCases || 2) && hitAtTop >= 0.9 && sourceSupportRate >= 0.95 && isolationRate === 1 && privateLeakageFindings.length === 0,
+    command: 'recall eval',
+    root,
+    durable_write: false,
+    eval_type: 'cross_host_recall',
+    journal_integrity_ok: journalIntegrity.ok,
+    journal_error_count: journalIntegrity.error_count,
+    min_cases: Number(minCases || 2),
+    top: limit,
+    host_count: hosts.length,
+    hosts,
+    evaluated_cases: evaluated,
+    hit_at_top: Number(hitAtTop.toFixed(3)),
+    source_support_rate: Number(sourceSupportRate.toFixed(3)),
+    host_isolation_rate: Number(isolationRate.toFixed(3)),
+    private_leakage_findings: privateLeakageFindings,
+    cases,
+    metric_scope: 'real_root_host_scoped_event_recall',
+    semantic_recall_quality_evaluated: false,
+    missing_evidence: !journalIntegrity.ok
+      ? 'Journal integrity check failed. Run neurain journal verify before trusting cross-host recall eval.'
+      : evaluated < Number(minCases || 2)
+      ? `Need at least ${Number(minCases || 2)} safe journal event case(s) with host tags.`
+      : sourceSupportRate < 0.95
+      ? 'Recall hits did not provide enough source-supporting snippets.'
+      : null,
+  };
+}
+
+async function evaluateRecallCaseFile(root, {
+  top = 5,
+  minCases = 1,
+  caseFile = '',
+} = {}) {
+  const beforeTarget = snapshotTargetWriteSurface(root);
+  const loaded = loadRecallEvalCaseFile(root, caseFile);
+  const limit = Math.max(1, Math.min(Number(top || 5), 10));
+  const cases = [];
+  const privateLeakageFindings = [];
+  const journalIntegrity = verifyJournal(root);
+  for (const item of loaded.cases) {
+    const query = String(item.query || '').trim();
+    if (!query) {
+      cases.push({
+        id: item.id || '',
+        query,
+        host: item.host || '',
+        hit_at_top: false,
+        source_supported: false,
+        isolated_from_wrong_hosts: true,
+        error: 'Missing query.',
+      });
+      continue;
+    }
+    const host = String(item.host || '');
+    const expectedPathContains = normalizeStringList(item.expected_path_contains);
+    const expectedTerms = normalizeStringList(item.expected_terms);
+    const forbiddenPathContains = normalizeStringList(item.forbidden_path_contains);
+    const wrongHosts = normalizeStringList(item.wrong_hosts);
+    const sameHost = await searchRecall(root, query, { top: limit, host });
+    const hitResults = expectedPathContains.length
+      ? sameHost.results.filter((result) => resultMatchesAnyPath(result, expectedPathContains))
+      : sameHost.results;
+    const leakageFindings = [];
+    for (const result of sameHost.results) {
+      const resultPath = String(result.path || '');
+      if (result.sensitivity === 'private') {
+        leakageFindings.push({ id: item.id || '', path: resultPath, reason: 'private result returned' });
+      }
+      for (const marker of forbiddenPathContains) {
+        if (resultPath.includes(marker)) {
+          leakageFindings.push({ id: item.id || '', path: resultPath, reason: `forbidden path marker: ${marker}` });
+        }
+      }
+    }
+    privateLeakageFindings.push(...leakageFindings);
+    const isolationChecks = [];
+    for (const wrongHost of wrongHosts.slice(0, 10)) {
+      const wrong = await searchRecall(root, query, { top: limit, host: wrongHost });
+      isolationChecks.push({
+        host: wrongHost,
+        leaked: expectedPathContains.length
+          ? wrong.results.some((result) => resultMatchesAnyPath(result, expectedPathContains))
+          : wrong.results.length > 0,
+      });
+    }
+    const supportTerms = expectedTerms.length ? expectedTerms : normalizeStringList(query.match(/[\p{L}\p{N}_-]+/gu) || []);
+    cases.push({
+      id: item.id || '',
+      query,
+      host,
+      expected_path_contains: expectedPathContains,
+      expected_terms: supportTerms,
+      hit_at_top: hitResults.length > 0,
+      source_supported: hitResults.some((result) => resultSupportsTerms(result, supportTerms)),
+      same_host_result_count: sameHost.results.length,
+      fallback_used: Boolean(sameHost.fallback_used),
+      isolated_from_wrong_hosts: isolationChecks.every((check) => !check.leaked),
+      isolation_checks: isolationChecks,
+      leakage_findings: leakageFindings,
+    });
+  }
+  const afterTarget = snapshotTargetWriteSurface(root);
+  const targetUntouched = stableJson(beforeTarget) === stableJson(afterTarget);
+  const evaluated = cases.length;
+  const hits = cases.filter((item) => item.hit_at_top).length;
+  const supported = cases.filter((item) => item.source_supported).length;
+  const isolated = cases.filter((item) => item.isolated_from_wrong_hosts).length;
+  const hitAtTop = evaluated ? hits / evaluated : 0;
+  const sourceSupportRate = evaluated ? supported / evaluated : 0;
+  const isolationRate = evaluated ? isolated / evaluated : 0;
+  const requiredCases = Number(minCases || 1);
+  const missingEvidence = !journalIntegrity.ok
+    ? 'Journal integrity check failed. Run neurain journal verify before trusting reviewed recall eval.'
+    : evaluated < requiredCases
+    ? `Need at least ${requiredCases} reviewed recall case(s).`
+    : hitAtTop < 0.9
+    ? 'Reviewed recall cases did not meet Hit@top gate.'
+    : sourceSupportRate < 0.95
+    ? 'Reviewed recall cases did not provide enough source-supporting snippets.'
+    : isolationRate < 1
+    ? 'Reviewed recall cases leaked expected hits under wrong host filters.'
+    : privateLeakageFindings.length > 0
+    ? 'Reviewed recall cases returned private or forbidden paths.'
+    : !targetUntouched
+    ? 'Recall case-file eval touched the target root.'
+    : null;
+  return {
+    ok: Boolean(journalIntegrity.ok && evaluated >= requiredCases && hitAtTop >= 0.9 && sourceSupportRate >= 0.95 && isolationRate === 1 && privateLeakageFindings.length === 0 && targetUntouched),
+    command: 'recall eval',
+    root,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    eval_type: 'cross_host_recall_cases',
+    metric_scope: 'reviewed_recall_case_file',
+    reviewed_recall_quality_evaluated: true,
+    semantic_recall_quality_evaluated: false,
+    case_file: loaded.rel,
+    journal_integrity_ok: journalIntegrity.ok,
+    journal_error_count: journalIntegrity.error_count,
+    min_cases: requiredCases,
+    top: limit,
+    host_count: new Set(cases.map((item) => item.host).filter(Boolean)).size,
+    hosts: [...new Set(cases.map((item) => item.host).filter(Boolean))].sort(),
+    evaluated_cases: evaluated,
+    hit_at_top: Number(hitAtTop.toFixed(3)),
+    source_support_rate: Number(sourceSupportRate.toFixed(3)),
+    host_isolation_rate: Number(isolationRate.toFixed(3)),
+    private_leakage_findings: privateLeakageFindings,
+    target_root_untouched: targetUntouched,
+    cases,
+    missing_evidence: missingEvidence,
+  };
+}
+
+async function evaluateSyntheticCrossHostRecall(targetRoot, {
+  top = 5,
+  minCases = 100,
+  fixtureSize = 100,
+  privateProbeCount = 20,
+} = {}) {
+  const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'neurain-recall-eval-'));
+  const safeCount = Math.max(1, Math.min(Number(fixtureSize || 100), 500));
+  const privateCount = Math.max(0, Math.min(Number(privateProbeCount || 20), 200));
+  const beforeTarget = snapshotTargetWriteSurface(targetRoot);
+  const hosts = ['codex', 'claude', 'runtime', 'gemini'];
+  let payload;
+  try {
+    ensureDir(safeResolve(fixtureRoot, 'wiki'));
+    fs.writeFileSync(
+      safeResolve(fixtureRoot, 'wiki/memory.md'),
+      '# Synthetic Recall Fixture\n\nGenerated fixture for cross-host recall evaluation.\n',
+      'utf8'
+    );
+    for (let index = 0; index < safeCount; index += 1) {
+      const host = hosts[index % hosts.length];
+      const serial = String(index + 1).padStart(3, '0');
+      appendJournalEvent(fixtureRoot, {
+        type: 'recall',
+        host,
+        source: 'wiki/memory.md',
+        summary: `topic${host}${serial} marker${host}${serial} proof${host}${serial} recall${host}${serial} preserved for host scoped continuity.`,
+        confirm: '1건 저장 진행',
+      });
+    }
+    for (let index = 0; index < privateCount; index += 1) {
+      const host = hosts[index % hosts.length];
+      const serial = String(index + 1).padStart(3, '0');
+      appendJournalEvent(fixtureRoot, {
+        type: 'recall',
+        host,
+        scope: 'private:synthetic-recall-eval',
+        source: '10_areas/_private/current/private-area-brief.md',
+        summary: `privatetopic${host}${serial} privatemarker${host}${serial} should not index across hosts.`,
+        confirm: '1건 저장 진행',
+      });
+    }
+    const rebuild = await rebuildRecall(fixtureRoot, { dryRun: false });
+    const evaluated = await evaluateCrossHostRecall(fixtureRoot, {
+      top,
+      minCases,
+      maxCases: safeCount,
+      fixtureSize: 0,
+      privateProbeCount,
+      unsafeProbeLimit: privateCount,
+    });
+    const afterTarget = snapshotTargetWriteSurface(targetRoot);
+    const targetUntouched = stableJson(beforeTarget) === stableJson(afterTarget);
+    payload = {
+      ...evaluated,
+      root: targetRoot,
+      eval_type: 'cross_host_recall_fixture',
+      metric_scope: 'synthetic_exact_token_host_filter_regression',
+      semantic_recall_quality_evaluated: false,
+      fixture: {
+        generated: true,
+        safe_cases: safeCount,
+        private_probe_cases: privateCount,
+        hosts,
+        target_root_untouched: targetUntouched,
+        temp_root_retained: null,
+        rebuild_indexed_count: rebuild.indexed_count,
+        rebuild_manifest_hash: rebuild.source_manifest_hash,
+      },
+      ok: Boolean(evaluated.ok && targetUntouched),
+      missing_evidence: evaluated.missing_evidence,
+    };
+  } finally {
+    fs.rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+  payload.fixture.temp_root_retained = fs.existsSync(fixtureRoot);
+  payload.ok = Boolean(payload.ok && !payload.fixture.temp_root_retained);
+  return payload;
+}
+
+// E22: semantic recall quality eval. Proves the local lexical-semantic layer
+// recalls paraphrased / morphological / synonym queries that pure exact-token
+// recall misses, while preserving host isolation, private exclusion, no-answer
+// abstention, rebuild equivalence, and target-root non-write. Each concept pair
+// is [stored_word, query_word]: both map to the same synonym canon but share no
+// surface token, so the query never exact-matches the stored doc.
+const SEMANTIC_CONCEPT_PAIRS = [
+  ['resolved', 'fixed'], ['defect', 'bug'], ['authentication', 'login'], ['removed', 'delete'],
+  ['created', 'add'], ['modified', 'change'], ['rapid', 'fast'], ['documentation', 'docs'],
+  ['configuration', 'config'], ['verified', 'test'], ['reverted', 'rollback'], ['inspected', 'review'],
+  ['handoff', 'session'], ['retrieval', 'recall'], ['insight', 'lesson'], ['automobile', 'car'],
+  ['large', 'big'], ['minor', 'small'], ['launched', 'start'], ['terminated', 'stop'],
+  ['secure', 'safe'], ['customer', 'user'], ['roadmap', 'plan'], ['compiled', 'build'],
+];
+const SEMANTIC_NO_ANSWER_PROBES = [
+  'galaxy nebula asteroid comet', 'pineapple umbrella violin pottery',
+  'glacier volcano tundra savanna', 'origami carousel lantern hammock',
+];
+
+function lexicalSemanticCombos(count, poolSize, k) {
+  const out = [];
+  const idx = Array.from({ length: k }, (_, i) => i);
+  while (out.length < count) {
+    out.push(idx.slice());
+    let i = k - 1;
+    while (i >= 0 && idx[i] === poolSize - k + i) i -= 1;
+    if (i < 0) break;
+    idx[i] += 1;
+    for (let j = i + 1; j < k; j += 1) idx[j] = idx[j - 1] + 1;
+  }
+  return out;
+}
+
+function roundRate3(value) {
+  return Number(Number(value || 0).toFixed(3));
+}
+
+// E23: live-content recall coverage. Read-only. Measures, on a REAL folder's actual
+// indexed content (not a synthetic fixture), how much of that content is recallable when
+// queried with auto-derived paraphrases (synonym-swapped real terms). Reports semantic vs
+// exact-token coverage and the lift, plus per-kind coverage, so a real user can see whether
+// the current recall is good enough on their own material and what it misses. The output is
+// metrics-only (no content is stored or returned), so it is safe to run on a private vault.
+// Honest scope: queries are auto-derived, not human-judged relevance; this is a real-content
+// step, not a substitute for external user walkthroughs.
+export async function evaluateLiveRecall(root, { top = 5, sampleSize = 60, provider = 'local-lexical', minScore = 0.34 } = {}) {
+  const prov = getProvider(provider);
+  const recallCfg = recallConfig(root);
+  const docs = collectRecallDocs(root, { recallCfg });
+  const eligible = docs.filter((doc) => /^event:/.test(doc.kind) || ['wiki', 'handoff', 'session', 'product', 'lessons', 'log'].includes(doc.kind));
+  const sample = eligible.slice(0, Math.max(1, Math.min(Number(sampleSize || 60), 500)));
+  const limit = Math.max(1, Math.min(Number(top || 5), 10));
+  // Measure the SAME hybrid the recall command returns: the routed 3-branch when
+  // routing applies (registry has areas), else the legacy 2-branch. The lexical
+  // context is built once and reused across the sample. The routed branch's layer
+  // boosts (wiki_core/session_handoff/area_index) are what keep eligible docs
+  // recallable as the corpus grows, so this is also the honest coverage number.
+  const routed = decideRouting('auto', '', root, recallCfg);
+  const lexicalCtx = routed ? buildLexicalContext(root, { recallCfg }) : null;
+  const cases = [];
+  for (const item of sample) {
+    const { query, swapped } = liveParaphraseQuery(item);
+    if (!query) continue;
+    const semantic = await semanticSearchRecall(root, query, { top: limit, host: '', provider, minScore });
+    const exact = await searchRecall(root, query, { top: limit, host: '' });
+    const semanticHit = semantic.results.some((result) => result.path === item.path);
+    const exactHit = exact.results.some((result) => result.path === item.path);
+    const lexical = lexicalCtx ? lexicalSearchWithContext(lexicalCtx, query, { top: limit }) : null;
+    const hybridResults = lexical
+      ? mergeRoutedHybridResults(lexical.results, exact.results, semantic.results)
+      : mergeHybridResults(exact.results, semantic.results);
+    const hybridHit = hybridResults.some((result) => result.path === item.path);
+    cases.push({
+      kind: item.kind,
+      paraphrased: swapped,
+      semantic_hit: semanticHit,
+      exact_hit: exactHit,
+      hybrid_hit: hybridHit,
+    });
+  }
+  const evaluated = cases.length;
+  const paraphrasable = cases.filter((item) => item.paraphrased);
+  const cover = (list, key) => (list.length ? list.filter((item) => item[key]).length / list.length : 0);
+  const perKind = {};
+  for (const item of cases) {
+    if (!perKind[item.kind]) perKind[item.kind] = { cases: 0, semantic_hits: 0 };
+    perKind[item.kind].cases += 1;
+    if (item.semantic_hit) perKind[item.kind].semantic_hits += 1;
+  }
+  const semanticCoverage = cover(cases, 'semantic_hit');
+  const exactCoverage = cover(cases, 'exact_hit');
+  const hybridCoverage = cover(cases, 'hybrid_hit');
+  return {
+    // Gate on the robust HYBRID recall (exact union semantic), which is never worse than
+    // exact-token. Pure semantic_coverage is reported for transparency and can be lower on
+    // real corpora, which is exactly why hybrid is the recommended strategy.
+    ok: evaluated > 0 && hybridCoverage >= exactCoverage && prov.model_call === false,
+    command: 'recall live-eval',
+    root,
+    durable_write: false,
+    model_calls: Boolean(prov.model_call),
+    external_tool_calls: Boolean(prov.external_call),
+    eval_type: 'live_content_recall_coverage',
+    metric_scope: 'real_folder_content_recall_coverage_auto_paraphrase',
+    semantic_recall_quality_evaluated: true,
+    live_evidence: true,
+    human_judged: false,
+    embedding_provider: prov.name,
+    llm_locked: Boolean(prov.llm_locked),
+    corpus_doc_count: docs.length,
+    recall_eligible_count: eligible.length,
+    evaluated_cases: evaluated,
+    paraphrasable_cases: paraphrasable.length,
+    top: limit,
+    semantic_coverage: roundRate3(semanticCoverage),
+    exact_token_coverage: roundRate3(exactCoverage),
+    hybrid_coverage: roundRate3(hybridCoverage),
+    hybrid_lift_over_exact: roundRate3(hybridCoverage - exactCoverage),
+    routed_recall: routed,
+    recommended_strategy: 'hybrid',
+    coverage_lift: roundRate3(semanticCoverage - exactCoverage),
+    paraphrase_semantic_coverage: roundRate3(cover(paraphrasable, 'semantic_hit')),
+    paraphrase_exact_coverage: roundRate3(cover(paraphrasable, 'exact_hit')),
+    paraphrase_lift: roundRate3(cover(paraphrasable, 'semantic_hit') - cover(paraphrasable, 'exact_hit')),
+    per_kind_coverage: Object.fromEntries(Object.entries(perKind).map(([kind, value]) => [kind, { cases: value.cases, semantic_coverage: roundRate3(value.semantic_hits / value.cases) }])),
+    content_stored: false,
+    note: 'Real-folder content recall coverage with auto-derived paraphrase queries. This is a real-content measurement (not a synthetic fixture and not human-judged relevance); it does not replace external user walkthroughs. Output is metrics-only with no stored content. On real corpora the pure semantic-only coverage can be LOWER than exact-token because the local lexical-semantic layer lacks the rarity weighting exact-token BM25 has (this regression was found by running live-eval on real content). The recommended strategy is hybrid (exact-token union semantic), whose coverage is always at least exact-token coverage plus the paraphrase catches; the per-term semantic win is validated separately by the E22 semantic eval.',
+  };
+}
+
+function liveParaphraseQuery(doc) {
+  const terms = tokenize(`${doc.title || ''} ${doc.snippet || ''}`);
+  const seen = new Set();
+  const picked = [];
+  for (const term of terms) {
+    if (term.length < 3 || seen.has(term)) continue;
+    seen.add(term);
+    picked.push(term);
+    if (picked.length >= 6) break;
+  }
+  if (picked.length < 2) return { query: '', swapped: false };
+  let swapped = false;
+  const queryTerms = picked.map((term) => {
+    const alt = alternativeForm(term);
+    if (alt) { swapped = true; return alt; }
+    return term;
+  });
+  return { query: queryTerms.join(' '), swapped };
+}
+
+export async function evaluateSemanticRecall(root, {
+  top = 5,
+  minCases = 50,
+  fixtureSize = 60,
+  caseFile = '',
+  provider = 'local-lexical',
+  minScore = 0.34,
+} = {}) {
+  if (caseFile) return evaluateSemanticRecallCaseFile(root, { top, minCases, caseFile, provider, minScore });
+  return evaluateSyntheticSemanticRecall(root, { top, minCases, fixtureSize, provider, minScore });
+}
+
+async function evaluateSyntheticSemanticRecall(targetRoot, { top, minCases, fixtureSize, provider, minScore }) {
+  const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'neurain-semantic-recall-eval-'));
+  const beforeTarget = snapshotTargetWriteSurface(targetRoot);
+  const hosts = ['codex', 'claude', 'runtime', 'gemini'];
+  const safeCount = Math.max(4, Math.min(Number(fixtureSize || 60), 500));
+  const combos = lexicalSemanticCombos(safeCount, SEMANTIC_CONCEPT_PAIRS.length, 4);
+  const limit = Math.max(1, Math.min(Number(top || 5), 10));
+  let payload;
+  try {
+    ensureDir(safeResolve(fixtureRoot, 'wiki'));
+    fs.writeFileSync(safeResolve(fixtureRoot, 'wiki/memory.md'), '# Semantic Recall Fixture\n\nGenerated fixture for semantic recall evaluation.\n', 'utf8');
+    const docMeta = [];
+    for (let i = 0; i < combos.length; i += 1) {
+      const host = hosts[i % hosts.length];
+      const serial = String(i + 1).padStart(3, '0');
+      const docWords = combos[i].map((idx) => SEMANTIC_CONCEPT_PAIRS[idx][0]);
+      const queryWords = combos[i].map((idx) => SEMANTIC_CONCEPT_PAIRS[idx][1]);
+      // Neutral filler tokens (entryref/closingref) are deliberately NOT in any synonym
+      // group, so only the docWords carry concept canons and the template never pollutes the
+      // concept space. Each query is strongly discriminative to its own doc; where equal-score
+      // ties occur, the per-doc serial embedded in the snippet anchors a fully deterministic
+      // tie-break (independent of the random event id in the path), so the source lands at a
+      // stable in-window rank on every run and Hit@5 is run-invariant. Note: a few queries tie
+      // and the source can sit at the edge of the top-K window, so widening the tie group or
+      // shrinking top below 5 would need the fixture revisited (tracked as future hardening).
+      const emit = appendJournalEvent(fixtureRoot, {
+        type: 'recall',
+        host,
+        source: 'wiki/memory.md',
+        summary: `entryref${serial} ${docWords.join(' ')} closingref${serial}.`,
+        confirm: '1건 저장 진행',
+      });
+      docMeta.push({ event_id: emit.event.event_id, host, queryWords });
+    }
+    const privateIds = [];
+    const privateCount = Math.max(4, Math.min(Math.round(safeCount * 0.2), 200));
+    for (let i = 0; i < privateCount; i += 1) {
+      const host = hosts[i % hosts.length];
+      const serial = String(i + 1).padStart(3, '0');
+      const emit = appendJournalEvent(fixtureRoot, {
+        type: 'recall',
+        host,
+        scope: 'private:semantic-eval',
+        source: '10_areas/_private/current/private-area-brief.md',
+        summary: `privateentry${host}${serial} confidential sensitive secure record should not surface across hosts.`,
+        confirm: '1건 저장 진행',
+      });
+      privateIds.push(emit.event.event_id);
+    }
+    const rebuild = await rebuildRecall(fixtureRoot, { dryRun: false });
+
+    const cases = [];
+    for (const meta of docMeta) {
+      const query = meta.queryWords.join(' ');
+      const semantic = await semanticSearchRecall(fixtureRoot, query, { top: limit, host: meta.host, provider, minScore });
+      const semanticHit = semantic.results.some((item) => String(item.path || '').includes(meta.event_id));
+      const exact = await searchRecall(fixtureRoot, query, { top: limit, host: meta.host });
+      const exactHit = exact.results.some((item) => String(item.path || '').includes(meta.event_id));
+      const sourceSupported = semantic.results
+        .filter((item) => String(item.path || '').includes(meta.event_id))
+        .some((item) => (item.matched_terms || []).length >= 2);
+      const wrongHost = hosts.find((host) => host !== meta.host);
+      const wrong = await semanticSearchRecall(fixtureRoot, query, { top: limit, host: wrongHost, provider, minScore });
+      const isolated = !wrong.results.some((item) => String(item.path || '').includes(meta.event_id));
+      cases.push({ event_id: meta.event_id, host: meta.host, query, semantic_hit: semanticHit, exact_hit: exactHit, source_supported: sourceSupported, isolated_from_wrong_host: isolated });
+    }
+
+    const privateLeakageFindings = [];
+    for (const privateId of privateIds) {
+      for (const host of hosts) {
+        const result = await semanticSearchRecall(fixtureRoot, 'confidential sensitive secure record', { top: limit, host, provider, minScore });
+        if (result.results.some((item) => String(item.path || '').includes(privateId))) {
+          privateLeakageFindings.push({ event_id: privateId, leaked_in_host: host });
+          break;
+        }
+      }
+    }
+
+    let noAnswerCorrect = 0;
+    for (const probe of SEMANTIC_NO_ANSWER_PROBES) {
+      const result = await semanticSearchRecall(fixtureRoot, probe, { top: limit, provider, minScore });
+      if (result.results.length === 0) noAnswerCorrect += 1;
+    }
+
+    const probeQuery = docMeta[0].queryWords.join(' ');
+    const beforeRebuild = await semanticSearchRecall(fixtureRoot, probeQuery, { top: limit, host: docMeta[0].host, provider, minScore });
+    await rebuildRecall(fixtureRoot, { dryRun: false });
+    const afterRebuild = await semanticSearchRecall(fixtureRoot, probeQuery, { top: limit, host: docMeta[0].host, provider, minScore });
+    const rebuildEquivalent = stableJson(beforeRebuild.results.map((item) => item.path)) === stableJson(afterRebuild.results.map((item) => item.path));
+
+    const afterTarget = snapshotTargetWriteSurface(targetRoot);
+    const targetUntouched = stableJson(beforeTarget) === stableJson(afterTarget);
+    const evaluated = cases.length;
+    const semanticHitRate = evaluated ? cases.filter((item) => item.semantic_hit).length / evaluated : 0;
+    const exactHitRate = evaluated ? cases.filter((item) => item.exact_hit).length / evaluated : 0;
+    const sourceSupportRate = evaluated ? cases.filter((item) => item.source_supported).length / evaluated : 0;
+    const isolationRate = evaluated ? cases.filter((item) => item.isolated_from_wrong_host).length / evaluated : 0;
+    const noAnswerRate = SEMANTIC_NO_ANSWER_PROBES.length ? noAnswerCorrect / SEMANTIC_NO_ANSWER_PROBES.length : 1;
+    const prov = getProvider(provider);
+    const gates = {
+      enough_cases: evaluated >= Number(minCases || 50),
+      semantic_hit_at_top: semanticHitRate >= 0.9,
+      semantic_beats_exact_baseline: semanticHitRate >= exactHitRate + 0.2,
+      source_support: sourceSupportRate >= 0.9,
+      host_isolation: isolationRate === 1,
+      no_private_leakage: privateLeakageFindings.length === 0,
+      no_answer_abstention: noAnswerRate === 1,
+      rebuild_equivalent: rebuildEquivalent,
+      target_root_untouched: targetUntouched,
+      no_model_calls: prov.model_call === false,
+      no_external_calls: prov.external_call === false,
+    };
+    payload = {
+      ok: Object.values(gates).every(Boolean),
+      command: 'recall eval',
+      root: targetRoot,
+      durable_write: false,
+      model_calls: Boolean(prov.model_call),
+      external_tool_calls: Boolean(prov.external_call),
+      eval_type: 'semantic_recall_fixture',
+      metric_scope: 'synthetic_lexical_semantic_recall_quality_regression',
+      semantic_recall_quality_evaluated: true,
+      embedding_provider: prov.name,
+      provider_kind: prov.kind,
+      provider_requires_index: Boolean(prov.requires_index),
+      llm_locked: Boolean(prov.llm_locked),
+      min_cases: Number(minCases || 50),
+      top: limit,
+      host_count: hosts.length,
+      hosts,
+      evaluated_cases: evaluated,
+      semantic_hit_at_top: roundRate3(semanticHitRate),
+      exact_token_baseline_hit_at_top: roundRate3(exactHitRate),
+      semantic_improvement: roundRate3(semanticHitRate - exactHitRate),
+      source_support_rate: roundRate3(sourceSupportRate),
+      host_isolation_rate: roundRate3(isolationRate),
+      private_leakage_findings: privateLeakageFindings,
+      no_answer_abstention_rate: roundRate3(noAnswerRate),
+      rebuild_equivalent: rebuildEquivalent,
+      target_root_untouched: targetUntouched,
+      gates,
+      fixture: {
+        generated: true,
+        safe_cases: docMeta.length,
+        private_probe_cases: privateCount,
+        hosts,
+        target_root_untouched: targetUntouched,
+        temp_root_retained: null,
+        rebuild_indexed_count: rebuild.indexed_count,
+      },
+      failed_cases: cases.filter((item) => !item.semantic_hit || !item.isolated_from_wrong_host).map((item) => ({ event_id: item.event_id, semantic_hit: item.semantic_hit, isolated: item.isolated_from_wrong_host })),
+    };
+  } finally {
+    fs.rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+  payload.fixture.temp_root_retained = fs.existsSync(fixtureRoot);
+  payload.temp_root_cleanup_verified = !payload.fixture.temp_root_retained;
+  payload.gates.temp_root_cleanup = !payload.fixture.temp_root_retained;
+  payload.ok = Boolean(payload.ok && !payload.fixture.temp_root_retained);
+  return payload;
+}
+
+async function evaluateSemanticRecallCaseFile(root, { top, minCases, caseFile, provider, minScore }) {
+  const beforeTarget = snapshotTargetWriteSurface(root);
+  const loaded = loadRecallEvalCaseFile(root, caseFile);
+  const limit = Math.max(1, Math.min(Number(top || 5), 10));
+  const cases = [];
+  const privateLeakageFindings = [];
+  for (const item of loaded.cases) {
+    const query = String(item.query || '').trim();
+    const host = String(item.host || '');
+    const expectedPathContains = normalizeStringList(item.expected_path_contains);
+    const expectedTerms = normalizeStringList(item.expected_terms);
+    const forbiddenPathContains = normalizeStringList(item.forbidden_path_contains);
+    const wrongHosts = normalizeStringList(item.wrong_hosts);
+    const expectNoAnswer = Boolean(item.expect_no_answer);
+    if (!query) {
+      cases.push({ id: item.id || '', query, host, semantic_hit: false, source_supported: false, isolated_from_wrong_hosts: true, error: 'Missing query.' });
+      continue;
+    }
+    const semantic = await semanticSearchRecall(root, query, { top: limit, host, provider, minScore });
+    const hitResults = expectedPathContains.length
+      ? semantic.results.filter((result) => resultMatchesAnyPath(result, expectedPathContains))
+      : semantic.results;
+    for (const result of semantic.results) {
+      const resultPath = String(result.path || '');
+      if (result.sensitivity === 'private') privateLeakageFindings.push({ id: item.id || '', path: resultPath, reason: 'private result returned' });
+      for (const marker of forbiddenPathContains) {
+        if (resultPath.includes(marker)) privateLeakageFindings.push({ id: item.id || '', path: resultPath, reason: `forbidden path marker: ${marker}` });
+      }
+    }
+    const isolationChecks = [];
+    for (const wrongHost of wrongHosts.slice(0, 10)) {
+      const wrong = await semanticSearchRecall(root, query, { top: limit, host: wrongHost, provider, minScore });
+      isolationChecks.push({
+        host: wrongHost,
+        leaked: expectedPathContains.length ? wrong.results.some((result) => resultMatchesAnyPath(result, expectedPathContains)) : wrong.results.length > 0,
+      });
+    }
+    const supportTerms = expectedTerms.length ? expectedTerms : normalizeStringList(query.match(/[\p{L}\p{N}_-]+/gu) || []);
+    const semanticHit = expectNoAnswer ? semantic.results.length === 0 : hitResults.length > 0;
+    cases.push({
+      id: item.id || '',
+      query,
+      host,
+      expect_no_answer: expectNoAnswer,
+      semantic_hit: semanticHit,
+      source_supported: expectNoAnswer ? true : hitResults.some((result) => resultSupportsTerms(result, supportTerms) || (result.matched_terms || []).length >= 1),
+      isolated_from_wrong_hosts: isolationChecks.every((check) => !check.leaked),
+      isolation_checks: isolationChecks,
+    });
+  }
+  const afterTarget = snapshotTargetWriteSurface(root);
+  const targetUntouched = stableJson(beforeTarget) === stableJson(afterTarget);
+  const evaluated = cases.length;
+  const semanticHitRate = evaluated ? cases.filter((item) => item.semantic_hit).length / evaluated : 0;
+  const sourceSupportRate = evaluated ? cases.filter((item) => item.source_supported).length / evaluated : 0;
+  const isolationRate = evaluated ? cases.filter((item) => item.isolated_from_wrong_hosts).length / evaluated : 0;
+  const requiredCases = Number(minCases || 1);
+  const prov = getProvider(provider);
+  return {
+    ok: Boolean(evaluated >= requiredCases && semanticHitRate >= 0.9 && sourceSupportRate >= 0.9 && isolationRate === 1 && privateLeakageFindings.length === 0 && targetUntouched),
+    command: 'recall eval',
+    root,
+    durable_write: false,
+    model_calls: Boolean(prov.model_call),
+    external_tool_calls: Boolean(prov.external_call),
+    eval_type: 'semantic_recall_cases',
+    metric_scope: 'reviewed_lexical_semantic_recall_case_file',
+    semantic_recall_quality_evaluated: true,
+    reviewed_semantic_recall_quality_evaluated: true,
+    embedding_provider: prov.name,
+    llm_locked: Boolean(prov.llm_locked),
+    case_file: loaded.rel,
+    min_cases: requiredCases,
+    top: limit,
+    host_count: new Set(cases.map((item) => item.host).filter(Boolean)).size,
+    hosts: [...new Set(cases.map((item) => item.host).filter(Boolean))].sort(),
+    evaluated_cases: evaluated,
+    semantic_hit_at_top: roundRate3(semanticHitRate),
+    source_support_rate: roundRate3(sourceSupportRate),
+    host_isolation_rate: roundRate3(isolationRate),
+    private_leakage_findings: privateLeakageFindings,
+    target_root_untouched: targetUntouched,
+    cases,
+  };
+}
+
+function snapshotTargetWriteSurface(root) {
+  const rels = [
+    '00_system/neurain/events.ndjson',
+    '00_system/neurain/recall.sqlite',
+    '00_system/neurain/recall.sqlite-wal',
+    '00_system/neurain/recall.sqlite-shm',
+    'output/receipts/events',
+    'output/receipts/recall',
+  ];
+  const out = {};
+  for (const rel of rels) {
+    let abs;
+    try {
+      abs = safeResolve(root, rel);
+    } catch {
+      out[rel] = { exists: false, hash: 'invalid-root' };
+      continue;
+    }
+    if (!fs.existsSync(abs)) {
+      out[rel] = { exists: false, hash: '' };
+      continue;
+    }
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      const files = walkFiles(abs, { includeRaw: false, maxFiles: 10000 })
+        .map((file) => `${relPath(abs, file)}:${sha256(fs.readFileSync(file))}`)
+        .sort();
+      out[rel] = { exists: true, type: 'directory', hash: sha256(files.join('\n')) };
+    } else {
+      out[rel] = { exists: true, type: 'file', hash: sha256(fs.readFileSync(abs)) };
+    }
+  }
+  return out;
+}
+
+function resultSupportsQuery(item, query) {
+  const text = `${item.title || ''} ${item.snippet || ''}`.toLowerCase();
+  const terms = String(query || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
+  return terms.length > 0 && terms.every((term) => text.includes(term));
+}
+
+function resultSupportsTerms(item, terms) {
+  const text = `${item.title || ''} ${item.snippet || ''}`.toLowerCase();
+  const normalized = normalizeStringList(terms).map((term) => term.toLowerCase());
+  return normalized.length > 0 && normalized.every((term) => text.includes(term));
+}
+
+function resultMatchesAnyPath(item, matchers) {
+  const target = String(item.path || '');
+  return normalizeStringList(matchers).some((matcher) => target.includes(matcher));
+}
+
+function normalizeStringList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '').trim()).filter(Boolean);
+  if (value === null || value === undefined) return [];
+  return [String(value).trim()].filter(Boolean);
+}
+
+function loadRecallEvalCaseFile(root, caseFile) {
+  const abs = safeResolve(root, caseFile);
+  const rel = relPath(root, abs);
+  if (!fs.existsSync(abs)) throw new Error(`Recall eval case file not found: ${caseFile}`);
+  let parsed;
+  try {
+    parsed = JSON.parse(readText(abs, '{}'));
+  } catch (error) {
+    throw new Error(`Recall eval case file is not valid JSON: ${error.message}`);
+  }
+  const cases = Array.isArray(parsed) ? parsed : parsed.cases;
+  if (!Array.isArray(cases)) throw new Error('Recall eval case file must be an array or an object with a cases array.');
+  return { rel, cases };
+}
+
+function renderRecallStatus(root, args) {
+  return recallStatus(root).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall status',
+      '',
+      `- Root: ${root}`,
+      `- SQLite available: ${payload.sqlite_available ? 'yes' : 'no'}`,
+      `- DB exists: ${payload.db_exists ? 'yes' : 'no'}`,
+      `- Rows: ${payload.row_count}`,
+      '- Markdown fallback: yes',
+    ].join('\n'),
+  });
+}
+
+function renderRecallRebuild(root, args) {
+  return rebuildRecall(root, { dryRun: Boolean(args['dry-run']) }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      `# Neurain recall rebuild${payload.dry_run ? ' [dry-run]' : ''}`,
+      '',
+      `- Root: ${root}`,
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Indexed docs: ${payload.indexed_count}`,
+      `- Durable write: ${payload.durable_write ? 'yes' : 'no'}`,
+      payload.receipt_path ? `- Receipt: ${payload.receipt_path}` : '',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+function renderRecallSearch(root, args) {
+  const query = args.query || args._.join(' ');
+  const scope = scopeForArea(resolveAreaDir(root, args.area || ''));
+  return searchRecall(root, query, { top: Number(args.top || 10), host: args.host || '', scope }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall search',
+      '',
+      `- Query: ${query}`,
+      `- Source: ${payload.source}`,
+      ...payload.results.map((item) => `- ${item.path}: ${item.title || item.snippet}`),
+      payload.results.length ? '' : 'No matches found.',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+function renderRecallVerify(root, args) {
+  return verifyRecall(root).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall verify',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Indexed: ${payload.indexed_count}`,
+      `- Expected: ${payload.expected_count}`,
+    ].join('\n'),
+  });
+}
+
+function renderRecallSemanticSearch(root, args) {
+  const query = args.query || args._.join(' ');
+  const scope = scopeForArea(resolveAreaDir(root, args.area || ''));
+  return semanticSearchRecall(root, query, {
+    top: Number(args.top || 10),
+    host: args.host || '',
+    provider: args.provider || 'local-lexical',
+    minScore: args['min-score'] !== undefined ? Number(args['min-score']) : 0.34,
+    scope,
+  }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall semantic-search',
+      '',
+      `- Query: ${query}`,
+      `- Provider: ${payload.embedding_provider} (${payload.provider_kind})`,
+      `- Model call: ${payload.model_calls ? 'yes' : 'no'}`,
+      ...payload.results.map((item) => `- ${item.path} [${item.score}]: ${item.title || item.snippet}`),
+      payload.results.length ? '' : 'No semantic matches found.',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+function renderRecallHybridSearch(root, args) {
+  const query = args.query || args._.join(' ');
+  return hybridSearchRecall(root, query, {
+    top: Number(args.top || 10),
+    host: args.host || '',
+    provider: args.provider || 'local-lexical',
+    minScore: args['min-score'] !== undefined ? Number(args['min-score']) : 0.34,
+    area: args.area || '',
+    routing: args.routing || 'auto',
+  }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall hybrid-search (exact + semantic)',
+      '',
+      `- Query: ${query}`,
+      `- Strategy: ${payload.strategy} | model call: ${payload.model_calls ? 'yes' : 'no'}`,
+      `- Exact results: ${payload.exact_result_count} | semantic added: ${payload.semantic_only_added}`,
+      ...payload.results.map((item) => `- [${item.matched_by}] ${item.path}: ${item.title || item.snippet}`),
+      payload.results.length ? '' : 'No matches found.',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+// Lexical-only search: exposes the routed lexical branch directly (the vault's
+// neurain-search equivalent), with area-relative output in --area mode. This is
+// the clean target for the vault search shim: same scorer, same fields. (Hybrid
+// remains the recommended runtime recall; this is the BM25+boosts view.)
+function renderRecallLexicalSearch(root, args) {
+  const query = args.query || args._.join(' ');
+  if (!String(query).trim()) throw new Error('Recall lexical-search requires a query.');
+  const recallCfg = recallConfig(root);
+  const areaDir = resolveAreaDir(root, args.area || '', recallCfg);
+  const ctx = buildLexicalContext(root, { area: areaDir, recallCfg });
+  const out = lexicalSearchWithContext(ctx, query, {
+    top: Number(args.top || 10),
+    maxPerLayer: Number(args['max-per-layer'] || 3),
+    includeQueue: Boolean(args['include-queue']),
+  });
+  const prefix = areaDir ? `${recallCfg.areas_dir}/${areaDir}/` : '';
+  const results = out.results.map((item) => (prefix && item.path.startsWith(prefix) ? { ...item, path: item.path.slice(prefix.length) } : item));
+  const payload = {
+    ok: true,
+    command: 'recall lexical-search',
+    root,
+    durable_write: false,
+    query: String(query),
+    top: out.top,
+    area: String(args.area || ''),
+    area_dir: areaDir,
+    results,
+  };
+  return args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall lexical-search',
+      '',
+      ...results.map((item) => {
+        const why = item.signals && Object.keys(item.signals).length
+          ? Object.entries(item.signals).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} +${v}`).join(', ')
+          : '';
+        return `- ${item.path}: score ${item.score}, ${item.snippet}${why ? `\n    why: ${why}` : ''}`;
+      }),
+      results.length ? '' : 'No matches found.',
+    ].filter(Boolean).join('\n'),
+  };
+}
+
+function renderRecallLiveEval(root, args) {
+  return evaluateLiveRecall(root, {
+    top: Number(args.top || 5),
+    sampleSize: Number(args['sample-size'] || 60),
+    provider: args.provider || 'local-lexical',
+    minScore: args['min-score'] !== undefined ? Number(args['min-score']) : 0.34,
+  }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall live-eval (real-folder content)',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Corpus docs: ${payload.corpus_doc_count} (recall-eligible: ${payload.recall_eligible_count})`,
+      `- Evaluated real items: ${payload.evaluated_cases} (paraphrasable: ${payload.paraphrasable_cases})`,
+      `- Hybrid coverage (exact + semantic, recommended): ${payload.hybrid_coverage} (always >= exact; lift over exact ${payload.hybrid_lift_over_exact})`,
+      `- Exact-token coverage: ${payload.exact_token_coverage}`,
+      `- Semantic-only coverage: ${payload.semantic_coverage} (can be lower than exact on real corpora, since the lexical-semantic layer lacks exact-token rarity weighting; this is why hybrid is recommended)`,
+      `- Paraphrase-only: semantic ${payload.paraphrase_semantic_coverage} vs exact ${payload.paraphrase_exact_coverage}`,
+      `- Provider: ${payload.embedding_provider} | model call: ${payload.model_calls ? 'yes' : 'no'} | content stored: ${payload.content_stored ? 'yes' : 'no'}`,
+      `- Human-judged relevance: ${payload.human_judged ? 'yes' : 'no (auto-derived paraphrase queries)'}`,
+      '',
+      'Per-kind semantic coverage:',
+      ...Object.entries(payload.per_kind_coverage).map(([kind, value]) => `  - ${kind}: ${value.semantic_coverage} (${value.cases} items)`),
+      '',
+      payload.note,
+    ].join('\n'),
+  });
+}
+
+function renderSemanticEvalText(payload) {
+  return [
+    '# Neurain recall eval (semantic)',
+    '',
+    `- OK: ${payload.ok ? 'yes' : 'no'}`,
+    `- Type: ${payload.eval_type}`,
+    `- Provider: ${payload.embedding_provider}`,
+    `- Cases: ${payload.evaluated_cases}`,
+    `- Semantic Hit@${payload.top}: ${payload.semantic_hit_at_top}`,
+    payload.exact_token_baseline_hit_at_top !== undefined ? `- Exact-token baseline Hit@${payload.top}: ${payload.exact_token_baseline_hit_at_top}` : '',
+    payload.semantic_improvement !== undefined ? `- Semantic improvement: ${payload.semantic_improvement}` : '',
+    `- Source support: ${payload.source_support_rate}`,
+    `- Host isolation: ${payload.host_isolation_rate}`,
+    `- Private leakage findings: ${payload.private_leakage_findings.length}`,
+    payload.no_answer_abstention_rate !== undefined ? `- No-answer abstention: ${payload.no_answer_abstention_rate}` : '',
+    payload.rebuild_equivalent !== undefined ? `- Rebuild equivalent: ${payload.rebuild_equivalent ? 'yes' : 'no'}` : '',
+    `- Target root untouched: ${payload.target_root_untouched ? 'yes' : 'no'}`,
+    payload.temp_root_cleanup_verified !== undefined ? `- Temp root cleanup verified: ${payload.temp_root_cleanup_verified ? 'yes' : 'no'}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+function renderRecallEval(root, args) {
+  if (args.semantic) {
+    const caseFile = args['case-file'] || '';
+    return evaluateSemanticRecall(root, {
+      top: Number(args.top || 5),
+      minCases: Number(args['min-cases'] || (caseFile ? 1 : 50)),
+      fixtureSize: Number(args['fixture-size'] || 60),
+      caseFile,
+      provider: args.provider || 'local-lexical',
+      minScore: args['min-score'] !== undefined ? Number(args['min-score']) : 0.34,
+    }).then((payload) => args.json ? { json: true, payload } : { text: renderSemanticEvalText(payload) });
+  }
+  const fixtureSize = Number(args['fixture-size'] || args.cases || 0);
+  const caseFile = args['case-file'] || '';
+  return evaluateCrossHostRecall(root, {
+    top: Number(args.top || 5),
+    minCases: Number(args['min-cases'] || (caseFile ? 1 : 2)),
+    maxCases: Number(args['max-cases'] || fixtureSize || 50),
+    fixtureSize,
+    privateProbeCount: Number(args['private-probes'] || 20),
+    caseFile,
+  }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain recall eval',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Type: ${payload.eval_type}`,
+      `- Hosts: ${payload.host_count}`,
+      `- Cases: ${payload.evaluated_cases}`,
+      `- Journal integrity: ${payload.journal_integrity_ok ? 'ok' : 'failed'}`,
+      `- Hit@${payload.top}: ${payload.hit_at_top}`,
+      `- Source support: ${payload.source_support_rate}`,
+      `- Host isolation: ${payload.host_isolation_rate}`,
+      `- Private leakage findings: ${payload.private_leakage_findings.length}`,
+      payload.case_file ? `- Case file: ${payload.case_file}` : '',
+      payload.fixture?.generated ? `- Fixture safe cases: ${payload.fixture.safe_cases}` : '',
+      payload.missing_evidence ? `- Missing evidence: ${payload.missing_evidence}` : '',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+function renderRecallBench(root, args) {
+  const payload = benchRecall(root, {
+    suites: args.suites || args['suite-dir'] || '',
+    area: args.area || '',
+    top: Number(args.top || 5),
+    baseline: args.baseline !== undefined ? Number(args.baseline) : undefined,
+    matcher: args.matcher || 'strict',
+    maxPerLayer: args['max-per-layer'] !== undefined ? Number(args['max-per-layer']) : undefined,
+    routing: args.routing || 'auto',
+    caseId: args.case || '',
+    explain: Boolean(args.explain),
+  });
+  if (args.json) return { json: true, payload };
+  if (payload.reason === 'no_suites') return { text: `# Neurain recall bench\n\n- No suites found. ${payload.note || ''}` };
+  if (payload.case) {
+    const c = payload.case;
+    return {
+      text: [
+        `# Neurain recall bench [case ${c.id}]`,
+        '',
+        `- OK: ${payload.ok ? 'yes' : 'no'}`,
+        `- Question: ${c.question}`,
+        `- Source hit (strict/loose): ${c.source_ok_strict ? 'yes' : 'no'} / ${c.source_ok_loose ? 'yes' : 'no'}`,
+        `- Entity hit: ${c.entity_ok ? 'yes' : 'no'}`,
+        `- Expected in corpus: ${JSON.stringify(c.expected_in_corpus)}`,
+        c.missing_expected.length ? `- Missing: ${c.missing_expected.join(', ')}` : '',
+        ...(c.top_results || []).map((r) => `  [${r.layer}] ${r.path} (score ${r.score}) ${JSON.stringify(r.signals)}`),
+      ].filter(Boolean).join('\n'),
+    };
+  }
+  const pct = (x) => `${(x * 100).toFixed(1)}%`;
+  return {
+    text: [
+      `# Neurain recall bench (area=${payload.area || 'all'}, top-${payload.top}, ${payload.strategy})`,
+      '',
+      ...payload.suites.map((r) => `- ${r.suite}: src ${pct(r.source_recall)} (loose ${pct(r.source_recall_loose)}) / ent ${pct(r.entity_recall)} ${r.passed ? 'PASS' : 'FAIL'} (${r.cases})`),
+      `- OVERALL: src ${pct(payload.overall.source_recall)} (loose ${pct(payload.overall.source_recall_loose)}) / ent ${pct(payload.overall.entity_recall)} (${payload.overall.cases} cases)`,
+      payload.gate ? `- GATE: ${pct(payload.gate.value)} vs baseline ${pct(payload.gate.baseline)} -> ${payload.gate.passed ? 'PASS' : 'FAIL'}` : '- GATE: (no baseline set)',
+      `- ok: ${payload.ok ? 'yes' : 'no'}`,
+    ].join('\n'),
+  };
+}
+
+function renderRecallScorecard(root, args) {
+  const payload = scorecardRecall(root, {
+    suites: args.suites || args['suite-dir'] || '',
+    area: args.area || '',
+    top: Number(args.top || 5),
+    matcher: args.matcher || 'strict',
+    maxPerLayer: args['max-per-layer'] !== undefined ? Number(args['max-per-layer']) : undefined,
+  });
+  if (args.json) return { json: true, payload };
+  if (payload.reason === 'no_suites') return { text: '# Neurain recall scorecard\n\n- No suites found.' };
+  return {
+    text: [
+      `# Neurain recall scorecard (area=${payload.area || 'all'}, top-${payload.top})`,
+      '',
+      `- Cases: ${payload.cases}`,
+      `- Hit@${payload.top}: ${payload.hit_at_k}`,
+      `- R@${payload.top}: ${payload.recall_at_k}`,
+      `- MRR: ${payload.mrr}`,
+      `- Entity-R: ${payload.entity_recall}`,
+      `- Latency: avg ${payload.latency_ms_avg}ms / p95 ${payload.latency_ms_p95}ms`,
+    ].join('\n'),
+  };
+}
+
+async function sqliteCapability() {
+  try {
+    const sqlite = await import('node:sqlite');
+    return { available: true, DatabaseSync: sqlite.DatabaseSync, error: null };
+  } catch (error) {
+    return { available: false, DatabaseSync: null, error: error.message };
+  }
+}
+
+function buildSqliteIndex(DatabaseSync, file, docs, manifestHash) {
+  const db = new DatabaseSync(file);
+  try {
+    db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = NORMAL;
+      CREATE TABLE recall_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+      CREATE TABLE recall_docs (
+        doc_id TEXT PRIMARY KEY,
+        path TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        host TEXT NOT NULL,
+        scope TEXT NOT NULL,
+        sensitivity TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        title TEXT NOT NULL,
+        snippet TEXT NOT NULL,
+        indexed_at TEXT NOT NULL
+      );
+      CREATE VIRTUAL TABLE recall_fts USING fts5(doc_id UNINDEXED, title, body, tokenize = 'unicode61');
+      CREATE INDEX recall_docs_path_idx ON recall_docs(path);
+      CREATE INDEX recall_docs_host_idx ON recall_docs(host);
+    `);
+    const insertDoc = db.prepare(`
+      INSERT INTO recall_docs (doc_id, path, kind, host, scope, sensitivity, source_hash, title, snippet, indexed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    const insertFts = db.prepare('INSERT INTO recall_fts (doc_id, title, body) VALUES (?, ?, ?)');
+    const indexedAt = timestamp();
+    db.exec('BEGIN');
+    for (const doc of docs) {
+      insertDoc.run(doc.doc_id, doc.path, doc.kind, doc.host, doc.scope, doc.sensitivity, doc.source_hash, doc.title, doc.snippet, indexedAt);
+      insertFts.run(doc.doc_id, doc.title, doc.body);
+    }
+    const insertMeta = db.prepare('INSERT INTO recall_meta (key, value) VALUES (?, ?)');
+    insertMeta.run('rebuilt_at', indexedAt);
+    insertMeta.run('source_manifest_hash', manifestHash);
+    insertMeta.run('fts5_available', 'true');
+    insertMeta.run('markdown_canonical', 'true');
+    insertMeta.run('row_count', String(docs.length));
+    db.exec('COMMIT');
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+  } catch (error) {
+    try { db.exec('ROLLBACK'); } catch {}
+    throw error;
+  } finally {
+    db.close();
+    cleanupSqliteAuxFiles(file);
+  }
+}
+
+function collectRecallDocs(root, { recallCfg = recallConfig(root) } = {}) {
+  const docs = [
+    ...collectMarkdownDocs(root, recallCfg),
+    ...collectEventDocs(root),
+    ...collectReceiptDocs(root),
+  ];
+  const unique = new Map();
+  for (const doc of docs) unique.set(doc.doc_id, doc);
+  return [...unique.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// W-A corpus expansion: the markdown corpus now includes the general area
+// knowledge class (10_areas/<area>/**.md), hubs, and the area registry, not just
+// current/log/product. Private exclusion is decided at collection time by the
+// label resolver (per-file frontmatter + area baseline + boundary path markers),
+// which fixes the old substring gate that dropped `..._tokenomics/` because the
+// path contained `token`. config.recall.include/exclude extend the whitelist.
+function collectMarkdownDocs(root, recallCfg = recallConfig(root)) {
+  return listRecallMarkdownFiles(root, recallCfg).map(({ rel, text, sensitivity }) => docFromText({
+    path: rel,
+    kind: kindForPath(rel),
+    host: 'markdown',
+    scope: scopeForPath(rel),
+    sensitivity,
+    title: titleForText(text, rel),
+    body: text,
+  }));
+}
+
+function collectEventDocs(root) {
+  const listed = listJournalEvents(root, { limit: 1000 }).events || [];
+  return listed
+    .filter((event) => event.sensitivity !== 'private')
+    .filter((event) => event.prompt_context_allowed !== false)
+    .filter((event) => event.safety?.indexing_allowed !== false && event.safety?.cross_host_allowed !== false)
+    .filter((event) => safeToIndex(event.summary))
+    .map((event) => docFromText({
+      path: `${event.receipt_path || '00_system/neurain/events.ndjson'}#${event.event_id}`,
+      kind: `event:${event.type}`,
+      host: event.host || 'cli',
+      scope: event.scope || 'global',
+      sensitivity: 'internal',
+      title: `${event.type} event`,
+      body: `${event.type}\n${event.summary}\n${(event.source_ids || []).join('\n')}`,
+    }));
+}
+
+function collectReceiptDocs(root) {
+  const dir = safeResolve(root, 'output/receipts');
+  if (!fs.existsSync(dir)) return [];
+  const docs = [];
+  for (const file of walkFiles(dir, { includeRaw: false, maxFiles: 10000 })) {
+    const rel = `output/receipts/${relPath(dir, file)}`;
+    if (!/\.json$/i.test(rel)) continue;
+    if (rel.startsWith(`${receiptDirRel}/`)) continue;
+    if (inferSensitivityFromPath(rel) === 'private') continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readText(file, '{}'));
+    } catch {
+      continue;
+    }
+    if (parsed.sensitivity === 'private') continue;
+    const sourceIds = [
+      ...(Array.isArray(parsed.source_ids) ? parsed.source_ids : []),
+      ...(Array.isArray(parsed.candidate?.source_ids) ? parsed.candidate.source_ids : []),
+    ];
+    if (sourceIds.some((source) => inferSensitivityFromPath(source) === 'private')) continue;
+    const safeBody = receiptBody(parsed);
+    if (!safeToIndex(safeBody)) continue;
+    docs.push(docFromText({
+      path: rel,
+      kind: `receipt:${String(parsed.command || 'unknown').replace(/\s+/g, '-')}`,
+      host: 'receipt',
+      scope: parsed.scope || parsed.candidate?.scope || 'global',
+      sensitivity: 'internal',
+      title: `${parsed.command || 'receipt'} receipt`,
+      body: safeBody,
+    }));
+  }
+  return docs;
+}
+
+function docFromText({ path: rel, kind, host, scope, sensitivity, title, body }) {
+  const normalizedBody = String(body || '').replace(/\s+/g, ' ').trim();
+  const sourceHash = sha256(`${rel}\n${normalizedBody}`);
+  return {
+    doc_id: `recall-${sha256(`${rel}:${sourceHash}`).slice(0, 16)}`,
+    path: rel,
+    kind,
+    host,
+    scope,
+    sensitivity,
+    source_hash: sourceHash,
+    title: String(title || path.basename(rel)).slice(0, 180),
+    snippet: normalizedBody.slice(0, 220),
+    body: normalizedBody,
+  };
+}
+
+function receiptBody(receipt) {
+  return stableJson({
+    command: receipt.command || '',
+    generated_at: receipt.generated_at || receipt.created_at || '',
+    event_id: receipt.event_id || '',
+    candidate_id: receipt.candidate_id || '',
+    candidate_hash: receipt.candidate_hash || '',
+    registry_path: receipt.registry_path || '',
+    planned_changes: Array.isArray(receipt.planned_changes)
+      ? receipt.planned_changes.map((item) => ({
+        title: item.title || '',
+        from_status: item.from_status || '',
+        to_status: item.to_status || '',
+        reason: item.reason || '',
+      }))
+      : [],
+    writes: Array.isArray(receipt.writes) ? receipt.writes.map(safeReceiptWriteValue).filter(Boolean) : [],
+  });
+}
+
+function safeReceiptWriteValue(item) {
+  const pathValue = String(item?.path || '');
+  if (pathValue && inferSensitivityFromPath(pathValue) === 'private') return '';
+  const value = pathValue || String(item?.action || '');
+  if (!safeToIndex(value)) return '';
+  return value;
+}
+
+function toFtsQuery(query) {
+  const terms = String(query || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
+  return terms.slice(0, 8).map((term) => `"${term.replace(/"/g, '""')}"`).join(' OR ');
+}
+
+function queryForEvent(event) {
+  const stop = new Set(['after', 'with', 'from', 'that', 'this', 'event', 'recall', 'memory', 'safe']);
+  const terms = String(event.summary || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
+  return terms.filter((term) => term.length >= 4 && !stop.has(term)).slice(0, 4).join(' ');
+}
+
+function fallbackRecallSearch(root, payload) {
+  const terms = payload.query.toLowerCase().split(/\s+/).filter(Boolean);
+  const host = String(payload.host || '');
+  const scope = String(payload.scope || '');
+  const results = collectRecallDocs(root)
+    .filter((doc) => !host || doc.host === host)
+    .filter((doc) => !scope || doc.scope === scope)
+    .map((doc) => ({
+      doc,
+      score: terms.reduce((score, term) => score + (doc.body.toLowerCase().includes(term) ? 10 : 0) + (doc.title.toLowerCase().includes(term) ? 15 : 0), 0),
+    }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.doc.path.localeCompare(b.doc.path))
+    .slice(0, payload.top)
+    .map(({ doc, score }) => ({
+      path: doc.path,
+      kind: doc.kind,
+      host: doc.host,
+      scope: doc.scope,
+      sensitivity: doc.sensitivity,
+      title: doc.title,
+      snippet: doc.snippet,
+      source_hash: doc.source_hash,
+      score,
+    }));
+  return {
+    ...payload,
+    ok: true,
+    source: 'markdown_fallback',
+    fallback_used: true,
+    results,
+  };
+}
+
+function replaceSqliteFile(target, tmp) {
+  cleanupSqliteSidecars(target);
+  cleanupSqliteAuxFiles(tmp);
+  fs.renameSync(tmp, target);
+  cleanupSqliteAuxFiles(target);
+}
+
+function sqliteReadOnlyLocation(file) {
+  return `file:${String(file).replace(/%/g, '%25').replace(/\?/g, '%3F').replace(/#/g, '%23').replace(/ /g, '%20')}?mode=ro&immutable=1`;
+}
+
+function cleanupSqliteSidecars(file) {
+  for (const target of [file, `${file}-wal`, `${file}-shm`]) {
+    try { fs.rmSync(target, { force: true }); } catch {}
+  }
+}
+
+function cleanupSqliteAuxFiles(file) {
+  for (const target of [`${file}-wal`, `${file}-shm`]) {
+    try { fs.rmSync(target, { force: true }); } catch {}
+  }
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}