@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/chunk-UQNQZXHY.js

@@ -0,0 +1,711 @@
+import {
+  selectSampleFiles
+} from "./chunk-QLK6ED4Q.js";
+import {
+  BrainDatabase
+} from "./chunk-QKTRECYS.js";
+
+// src/brain/brain-index-health.ts
+import * as fs from "fs";
+import * as crypto from "crypto";
+async function runIndexHealthCheck(projectId, options = {}) {
+  const rawDb = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  const diskScan = options.diskScan ?? "sample";
+  const checks = [];
+  checks.push(await checkByteBounds(rawDb, projectId));
+  checks.push(await checkLineBounds(rawDb, projectId));
+  checks.push(await checkOrphanTargets(rawDb, projectId));
+  checks.push(await checkDanglingSources(rawDb, projectId));
+  checks.push(...await checkOrphanOwners(rawDb, projectId));
+  const preResolved = options.preResolved && options.preResolved.total === totalFiles(rawDb, projectId) ? options.preResolved : null;
+  const drift = await checkHashDrift(rawDb, projectId, diskScan, preResolved);
+  checks.push(drift.check);
+  checks.push(await checkMissingFiles(rawDb, projectId, diskScan, preResolved));
+  const deferredEmbeddingCoverage = options.deferEmbeddingCoverage === true;
+  if (!deferredEmbeddingCoverage) checks.push(await checkEmbeddingCoverage(rawDb, projectId));
+  checks.push(await checkSyntaxErrorFiles(rawDb, projectId));
+  checks.push(await checkWalSize(rawDb, projectId));
+  checks.push(await checkEmptyFiles(rawDb, projectId));
+  checks.push(await checkRelationshipRatio(rawDb, projectId));
+  const completeness = checkIndexCompleteness(rawDb, projectId);
+  checks.push(completeness.check);
+  const staleness = drift.classification;
+  const scored = checks.filter((c) => c.kind !== "informational");
+  const informational = checks.filter((c) => c.kind === "informational");
+  const ok = scored.filter((c) => c.status === "ok").length;
+  const warn = scored.filter((c) => c.status === "warn").length;
+  const error = scored.filter((c) => c.status === "error").length;
+  const overallHealth = Math.round(ok / Math.max(scored.length, 1) * 100);
+  const populated = staleness.total > 0 || completeness.totalSymbols > 0;
+  const verdict = !populated ? "empty" : error > 0 ? "broken" : warn > 0 ? "degraded" : "healthy";
+  return {
+    projectId,
+    timestamp: Date.now(),
+    overallHealth,
+    deferredEmbeddingCoverage,
+    verdict,
+    indexStatus: completeness.indexStatus,
+    staleness,
+    checks,
+    summary: { ok, warn, error, total: checks.length, scored: scored.length, informational: informational.length }
+  };
+}
+function checkIndexCompleteness(rawDb, projectId) {
+  const stored = rawDb.prepare(`
+    SELECT status, total_files, indexed_files
+    FROM brain_index_status WHERE project_id = ?
+  `).get(projectId);
+  const totalSymbols = rawDb.prepare(`SELECT COUNT(*) as count FROM brain_symbol WHERE project_id = ?`).get(projectId)?.count ?? 0;
+  const status = typeof stored?.status === "string" ? stored.status : null;
+  const totalFilesRecorded = typeof stored?.total_files === "number" ? stored.total_files : null;
+  const indexedFilesRecorded = typeof stored?.indexed_files === "number" ? stored.indexed_files : null;
+  const shortfall = totalFilesRecorded !== null && indexedFilesRecorded !== null && indexedFilesRecorded < totalFilesRecorded ? totalFilesRecorded - indexedFilesRecorded : null;
+  const indexStatus = {
+    status,
+    totalFiles: totalFilesRecorded,
+    indexedFiles: indexedFilesRecorded,
+    shortfall,
+    recorded: !!stored
+  };
+  const parts = [];
+  let status_ = "ok";
+  const errNote = indexedErrorsNote(rawDb, projectId);
+  if (!stored) {
+    status_ = "warn";
+    parts.push(
+      "No brain_index_status row exists for this project, so how complete the index is was never recorded. UNRECORDED is not the same as complete \u2014 it cannot be checked, and a reader who treats it as a pass is reading an absence as a measurement."
+    );
+  } else {
+    if (status === "partial") {
+      status_ = "error";
+      parts.push(
+        `The indexer recorded this run's status as "partial"${errNote}. An index marked partial is INCOMPLETE, and every count this report makes describes only the part that was written.`
+      );
+    } else if (status && status !== "complete") {
+      status_ = "warn";
+      parts.push(`The indexer recorded this run's status as "${status}", not "complete".`);
+    }
+    if (shortfall !== null && shortfall > 0) {
+      status_ = "error";
+      parts.push(
+        `${shortfall} of ${totalFilesRecorded} discovered files were never written (${indexedFilesRecorded} of ${totalFilesRecorded} indexed), so the index does not cover the project` + // The status field and the counts can disagree, and when they do the
+        // user needs to know which one to believe. health-provider.ts already
+        // detects this ("INCOMPLETE even though the status field says
+        // complete"); saying it here too keeps the two reports consistent.
+        (status === "complete" ? ` \u2014 note the status field says "complete" while the counts say otherwise; the counts are the measurement.` : ".")
+      );
+    }
+  }
+  if (parts.length === 0) {
+    parts.push(
+      `The indexer recorded this run as "${status ?? "complete"}" with ${indexedFilesRecorded ?? "?"} of ${totalFilesRecorded ?? "?"} discovered files written.`
+    );
+  }
+  return {
+    check: {
+      name: "Index Completeness",
+      status: status_,
+      value: shortfall ?? 0,
+      total: totalFilesRecorded ?? 0,
+      threshold: { warn: 0, error: 1 },
+      description: parts.join(" "),
+      remediation: status_ === "ok" ? void 0 : `Re-index from the project root: bb index --force (full rebuild), then bb index --post if a derived phase is what failed. If the shortfall persists on a clean rebuild, this is an indexer bug \u2014 report it with the numbers above.`
+    },
+    indexStatus,
+    totalSymbols
+  };
+}
+function indexedErrorsNote(rawDb, projectId) {
+  try {
+    const raw = rawDb.prepare(`SELECT indexing_errors FROM brain_index_status WHERE project_id = ?`).get(projectId);
+    const parsed = raw?.indexing_errors ? JSON.parse(String(raw.indexing_errors)) : null;
+    const n = Array.isArray(parsed) ? parsed.length : null;
+    return n ? ` \u2014 ${n} file(s) errored during the run` : "";
+  } catch {
+  }
+  return "";
+}
+function stalenessFromReasons(total, reasons) {
+  const fresh = (reasons["metadata-fast-path"] ?? 0) + (reasons["hash-match"] ?? 0);
+  return {
+    fresh,
+    stale: reasons["hash-differs"] ?? 0,
+    missing: (reasons["file-gone"] ?? 0) + (reasons["unreadable"] ?? 0),
+    unclassified: reasons["no-row"] ?? 0,
+    sampleSize: fresh + (reasons["hash-differs"] ?? 0) + (reasons["file-gone"] ?? 0) + (reasons["unreadable"] ?? 0) + (reasons["no-row"] ?? 0),
+    total,
+    complete: true,
+    basis: "exact",
+    verifiedByContent: reasons["hash-match"] ?? 0
+  };
+}
+async function checkByteBounds(rawDb, projectId) {
+  const row = rawDb.prepare(`
+    SELECT
+      COUNT(*) as total,
+      SUM(CASE WHEN byte_start IS NULL OR byte_end IS NULL THEN 1 ELSE 0 END) as null_count
+    FROM brain_symbol WHERE project_id = ?
+  `).get(projectId);
+  const total = row?.total ?? 0;
+  const nullCount = row?.null_count ?? 0;
+  const pct = total > 0 ? nullCount / total * 100 : 0;
+  let sample = [];
+  if (nullCount > 0) {
+    const rows = rawDb.prepare(`
+      SELECT name, file_id FROM brain_symbol
+      WHERE project_id = ? AND (byte_start IS NULL OR byte_end IS NULL)
+      LIMIT 5
+    `).all(projectId);
+    sample = rows.map((r) => `${r.name} (${r.file_id})`);
+  }
+  return {
+    name: "Byte Bounds Coverage",
+    status: pct > 5 ? "error" : pct > 1 ? "warn" : "ok",
+    value: nullCount,
+    total,
+    percentage: Math.round((100 - pct) * 10) / 10,
+    threshold: { warn: 1, error: 5 },
+    description: `${nullCount} of ${total} symbols have NULL byte bounds. Without byte bounds, bb_edit cannot safely mutate these symbols.`,
+    remediation: nullCount > 0 ? "Run bb_health with refresh=true and force=true to reindex affected files." : void 0,
+    sample: sample.length > 0 ? sample : void 0
+  };
+}
+async function checkLineBounds(rawDb, projectId) {
+  const row = rawDb.prepare(`
+    SELECT
+      COUNT(*) as total,
+      SUM(CASE WHEN line_start IS NULL THEN 1 ELSE 0 END) as null_count
+    FROM brain_symbol WHERE project_id = ?
+  `).get(projectId);
+  const total = row?.total ?? 0;
+  const nullCount = row?.null_count ?? 0;
+  const pct = total > 0 ? nullCount / total * 100 : 0;
+  return {
+    name: "Line Bounds Coverage",
+    status: pct > 10 ? "error" : pct > 2 ? "warn" : "ok",
+    value: nullCount,
+    total,
+    percentage: Math.round((100 - pct) * 10) / 10,
+    threshold: { warn: 2, error: 10 },
+    description: `${nullCount} symbols have NULL line_start. Tools fall back to file-level operations for these.`,
+    remediation: nullCount > 0 ? "These are typically top-level or auto-generated symbols. Generally safe." : void 0
+  };
+}
+async function checkOrphanTargets(rawDb, projectId) {
+  const row = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_relationship r
+    WHERE r.project_id = ?
+      AND r.target_symbol_id IS NOT NULL
+      AND r.target_symbol_id != ''
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol s WHERE s.id = r.target_symbol_id AND s.project_id = r.project_id)
+  `).get(projectId);
+  const orphanCount = row?.count ?? 0;
+  let sample = [];
+  if (orphanCount > 0) {
+    const rows = rawDb.prepare(`
+      SELECT r.id, r.target_symbol_id, r.source_symbol_id FROM brain_relationship r
+      WHERE r.project_id = ?
+        AND r.target_symbol_id IS NOT NULL
+        AND r.target_symbol_id != ''
+        AND NOT EXISTS (SELECT 1 FROM brain_symbol s WHERE s.id = r.target_symbol_id AND s.project_id = r.project_id)
+      LIMIT 5
+    `).all(projectId);
+    sample = rows.map((r) => `rel ${r.id}: target ${r.target_symbol_id} (from ${r.source_symbol_id})`);
+  }
+  return {
+    name: "Orphan Target Relationships",
+    status: orphanCount > 100 ? "error" : orphanCount > 10 ? "warn" : "ok",
+    value: orphanCount,
+    threshold: { warn: 10, error: 100 },
+    description: `${orphanCount} relationships point to symbols that no longer exist. These inflate bb_analyze graph results but lead nowhere.`,
+    remediation: orphanCount > 0 ? "Run bb_health with refresh=true and force=true to rebuild the index." : void 0,
+    sample: sample.length > 0 ? sample : void 0
+  };
+}
+async function checkDanglingSources(rawDb, projectId) {
+  const row = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_relationship r
+    WHERE r.project_id = ?
+      AND r.source_symbol_id IS NOT NULL AND r.source_symbol_id != ''
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol s WHERE s.id = r.source_symbol_id AND s.project_id = r.project_id)
+  `).get(projectId);
+  const danglingCount = row?.count ?? 0;
+  return {
+    name: "Dangling Source Relationships",
+    status: danglingCount > 100 ? "error" : danglingCount > 10 ? "warn" : "ok",
+    value: danglingCount,
+    threshold: { warn: 10, error: 100 },
+    description: `${danglingCount} relationships have a non-empty source_symbol_id that matches no stored symbol. These are dead edges in the call graph. (External-source edges with a NULL source_symbol_id are legitimate and not counted.)`,
+    remediation: danglingCount > 0 ? "Re-index the affected files (`bb index <dir>`) so edges are written against stored symbols. A --force rebuild only helps if the danglers came from an older indexer version; if they persist on a fresh index, this is an indexer bug \u2014 report it with the sample ids." : void 0
+  };
+}
+async function checkOrphanOwners(rawDb, projectId) {
+  const genuine = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_symbol s
+    WHERE s.project_id = ?
+      AND s.owner_symbol_id IS NOT NULL
+      AND s.owner_symbol_id != ''
+      AND s.owner_symbol_id NOT LIKE '%:0'
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol p WHERE p.id = s.owner_symbol_id AND p.project_id = s.project_id)
+  `).get(projectId);
+  const synthetic = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_symbol s
+    WHERE s.project_id = ?
+      AND s.owner_symbol_id IS NOT NULL
+      AND s.owner_symbol_id != ''
+      AND s.owner_symbol_id LIKE '%:0'
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol p WHERE p.id = s.owner_symbol_id AND p.project_id = s.project_id)
+  `).get(projectId);
+  const samples = rawDb.prepare(`
+    SELECT s.owner_symbol_id as oid, COUNT(*) as c FROM brain_symbol s
+    WHERE s.project_id = ?
+      AND s.owner_symbol_id IS NOT NULL AND s.owner_symbol_id != ''
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol p WHERE p.id = s.owner_symbol_id AND p.project_id = s.project_id)
+    GROUP BY s.owner_symbol_id ORDER BY c DESC LIMIT 5
+  `).all(projectId);
+  const genuineCount = genuine?.count ?? 0;
+  const syntheticCount = synthetic?.count ?? 0;
+  const sample = samples.map((r) => `${r.c}x ${String(r.oid).slice(-60)}`);
+  return [
+    {
+      name: "Orphan Owner References",
+      status: genuineCount > 100 ? "error" : genuineCount > 10 ? "warn" : "ok",
+      value: genuineCount,
+      threshold: { warn: 10, error: 100 },
+      description: `${genuineCount} symbols reference an owner_symbol_id that is not a synthetic container and matches no stored symbol. This breaks containment chains in bb_trace and the LSP document tree.`,
+      remediation: genuineCount > 0 ? "Re-index the affected files (`bb index <dir>`); if the count does not drop to zero on a fresh index, this is an indexer bug \u2014 report it with the sample ids. A --force rebuild is NOT guaranteed to fix this." : void 0,
+      sample: sample.length > 0 ? sample : void 0
+    },
+    {
+      name: "Synthetic Container References",
+      status: "ok",
+      // M64.I3: informational. This population is by-design and its status does
+      // not depend on the data, so scoring it added a constant +7.7 points to
+      // every project's overallHealth and put a floor under the score that no
+      // number of real failures could cross.
+      kind: "informational",
+      value: syntheticCount,
+      threshold: { warn: 1e7, error: 1e7 },
+      description: `${syntheticCount} symbols carry owner ids of the form <file>:<name>:0 \u2014 module/synthetic containers the pre-M51 indexer wrote as an owner fallback. By design they never resolve (no stored row has line 0) and every consumer JOINs on owner_symbol_id, so they are invisible to reads. Informational, not a defect, and excluded from overallHealth.`,
+      remediation: syntheticCount > 0 ? "Optional: re-run `bb index` \u2014 rows written by pre-M51 indexers are rewritten with a resolvable owner (or NULL) and this count drops to 0." : void 0,
+      sample: sample.length > 0 ? sample : void 0
+    }
+  ];
+}
+function totalFiles(rawDb, projectId) {
+  return rawDb.prepare(`SELECT COUNT(*) as count FROM brain_file WHERE project_id = ?`).get(projectId)?.count ?? 0;
+}
+async function checkHashDrift(rawDb, projectId, diskScan, preResolved) {
+  const total = totalFiles(rawDb, projectId);
+  if (preResolved) {
+    const drift = preResolved.reasons["hash-differs"] ?? 0;
+    const byContent = preResolved.reasons["hash-match"] ?? 0;
+    const pctAll = total > 0 ? drift / total * 100 : 0;
+    return {
+      check: {
+        name: "Hash Drift (Stale Files)",
+        status: pctAll > 10 ? "error" : pctAll > 3 ? "warn" : "ok",
+        value: drift,
+        total,
+        percentage: Math.round((100 - pctAll) * 10) / 10,
+        threshold: { warn: 3, error: 10 },
+        description: `${drift} of ${total} indexed files have changed on disk since indexing. EXACT: every indexed file was resolved against disk, and these verdicts are the SAME ones bb_health's own freshness scan just produced \u2014 this check reads no files of its own, so the two can never disagree and the corpus is not hashed twice. ${byContent} file(s) were verified by content hash; the rest by mtime+size.`,
+        remediation: drift > 0 ? "Run bb_health with refresh=true to reindex changed files." : void 0
+      },
+      classification: stalenessFromReasons(total, preResolved.reasons)
+    };
+  }
+  const allFiles = rawDb.prepare(`
+    SELECT id, path, relative_path, file_hash FROM brain_file WHERE project_id = ?
+  `).all(projectId);
+  const files = diskScan === "complete" ? selectSampleFiles(allFiles, Number.MAX_SAFE_INTEGER) : selectSampleFiles(allFiles, 200);
+  let driftCount = 0;
+  let freshCount = 0;
+  let goneCount = 0;
+  let unreadableCount = 0;
+  const driftSamples = [];
+  for (const f of files) {
+    let buf;
+    try {
+      buf = fs.readFileSync(f.path);
+    } catch (e) {
+      if (e?.code === "ENOENT") goneCount++;
+      else unreadableCount++;
+      continue;
+    }
+    const hash = crypto.createHash("sha256").update(buf).digest("hex").slice(0, 16);
+    if (hash === f.file_hash) {
+      freshCount++;
+      continue;
+    }
+    driftCount++;
+    if (driftSamples.length < 5) driftSamples.push(f.relative_path);
+  }
+  const sampleSize = files.length;
+  const pct = sampleSize > 0 ? driftCount / sampleSize * 100 : 0;
+  const isCompleteScan = sampleSize >= total;
+  const estimatedTotal = isCompleteScan ? driftCount : total > 0 ? Math.round(driftCount / Math.max(sampleSize, 1) * total) : 0;
+  return {
+    check: {
+      name: "Hash Drift (Stale Files)",
+      status: pct > 10 ? "error" : pct > 3 ? "warn" : "ok",
+      value: driftCount,
+      total: sampleSize,
+      percentage: Math.round((100 - pct) * 10) / 10,
+      threshold: { warn: 3, error: 10 },
+      description: isCompleteScan ? `${driftCount} of ${sampleSize} indexed files have changed on disk since indexing. EXACT: every indexed file was content-hashed, so this is the project's drift count and this status is a measurement, not an estimate.` : `${driftCount} of ${sampleSize} sampled files have changed on disk since indexing (estimated ${estimatedTotal} total). ESTIMATE: a deterministic unbiased sample of every indexed file \u2014 reproducible and independent of file ordering, but the rate and therefore this status carry sampling error. bb_health integrity=true runs this as a complete scan.`,
+      remediation: driftCount > 0 ? "Run bb_health with refresh=true to reindex changed files." : void 0,
+      sample: driftSamples.length > 0 ? driftSamples : void 0
+    },
+    classification: {
+      fresh: freshCount,
+      stale: driftCount,
+      missing: goneCount + unreadableCount,
+      unclassified: 0,
+      sampleSize,
+      total,
+      complete: isCompleteScan,
+      basis: isCompleteScan ? "exact" : "sample",
+      verifiedByContent: freshCount + driftCount
+    }
+  };
+}
+async function checkMissingFiles(rawDb, projectId, diskScan, preResolved) {
+  const total = totalFiles(rawDb, projectId);
+  if (preResolved) {
+    const gone = preResolved.reasons["file-gone"] ?? 0;
+    const denied = preResolved.reasons["unreadable"] ?? 0;
+    const missing2 = gone + denied;
+    return {
+      name: "Files Missing from Disk",
+      status: missing2 > 10 ? "error" : missing2 > 2 ? "warn" : "ok",
+      value: missing2,
+      total,
+      percentage: total > 0 ? Math.round((1 - missing2 / total) * 1e3) / 10 : 100,
+      threshold: { warn: 2, error: 10 },
+      description: `${missing2} of ${total} indexed files no longer exist on disk. EXACT: ${gone} deleted, ${denied} unreadable, both from the freshness scan this report already ran. Tools will fail when trying to read these.`,
+      remediation: missing2 > 0 ? "Run bb_health with refresh=true to remove deleted files from the index." : void 0
+    };
+  }
+  const allFiles = rawDb.prepare(`
+    SELECT id, path, relative_path FROM brain_file WHERE project_id = ?
+  `).all(projectId);
+  const files = diskScan === "complete" ? selectSampleFiles(allFiles, Number.MAX_SAFE_INTEGER) : selectSampleFiles(allFiles, 100);
+  let missing = 0;
+  const missingSamples = [];
+  for (const f of files) {
+    if (!fs.existsSync(f.path)) {
+      missing++;
+      if (missingSamples.length < 5) missingSamples.push(f.path);
+    }
+  }
+  const isCompleteScan = files.length >= total;
+  const estimatedMissing = isCompleteScan ? missing : total > 0 ? Math.round(missing / Math.min(files.length, total) * total) : 0;
+  return {
+    name: "Files Missing from Disk",
+    status: missing > 10 ? "error" : missing > 2 ? "warn" : "ok",
+    value: missing,
+    total: files.length,
+    percentage: files.length > 0 ? Math.round((1 - missing / files.length) * 1e3) / 10 : 100,
+    threshold: { warn: 2, error: 10 },
+    description: isCompleteScan ? `${missing} of ${files.length} indexed files no longer exist on disk. EXACT: every indexed file was checked. Tools will fail when trying to read these.` : `${missing} of ${files.length} sampled files no longer exist on disk. Estimated ${estimatedMissing} total missing. ESTIMATE: a deterministic unbiased sample of every indexed file (reproducible; independent of file ordering). bb_health integrity=true runs this as a complete scan.`,
+    remediation: missing > 0 ? "Run bb_health with refresh=true to remove deleted files from the index." : void 0,
+    sample: missingSamples.length > 0 ? missingSamples : void 0
+  };
+}
+async function checkEmbeddingCoverage(rawDb, projectId) {
+  const hasTable = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name='brain_semantic_embedding'
+  `).get();
+  if (!hasTable?.count) {
+    return {
+      name: "Embedding Coverage",
+      status: "warn",
+      value: 0,
+      total: 0,
+      percentage: 0,
+      threshold: { warn: 50, error: 20 },
+      description: "Semantic embedding table does not exist. Semantic search is keyword-only.",
+      // M64.I4: this said `bb2 brain --post`. There is no `bb2` binary and no
+      // `brain` subcommand — the CLI registers tool/index/setup/show/doctor/
+      // stats/status/projects/search/health/onboard/mcp/version, so the advice
+      // sent a user to a command that cannot be typed. The real interface is
+      // the bb_index tool's post mode, which re-runs the derived phases.
+      remediation: 'Generate embeddings with the bb_index tool: { path: "<project path>", mode: "post" } (CLI: bb index "<project path>").'
+    };
+  }
+  const totalRow = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_symbol WHERE project_id = ?
+  `).get(projectId);
+  const totalSymbols = totalRow?.count ?? 0;
+  const embedRow = rawDb.prepare(`
+    SELECT COUNT(DISTINCT entity_id) as count FROM brain_semantic_embedding WHERE project_id = ?
+  `).get(projectId);
+  const embedded = embedRow?.count ?? 0;
+  const targetKinds = rawDb.prepare(`
+    SELECT entity_type AS kind, COUNT(DISTINCT entity_id) AS c FROM brain_semantic_embedding
+    WHERE project_id = ? GROUP BY entity_type ORDER BY c DESC
+  `).all(projectId);
+  let targetSymbols = 0;
+  if (targetKinds.length > 0) {
+    const placeholders = targetKinds.map(() => "?").join(",");
+    const targetRow = rawDb.prepare(
+      `SELECT COUNT(*) as count FROM brain_symbol WHERE project_id = ? AND symbol_type IN (${placeholders})`
+    ).get(projectId, ...targetKinds.map((k) => String(k.kind)));
+    targetSymbols = targetRow?.count ?? 0;
+  }
+  const pct = targetSymbols > 0 ? embedded / targetSymbols * 100 : 0;
+  const overallShare = totalSymbols > 0 ? embedded / totalSymbols * 100 : 0;
+  const kindDesc = targetKinds.map((k) => `${k.kind}=${k.c}`).join(" ");
+  if (embedded === 0) {
+    return {
+      name: "Embedding Coverage",
+      status: "error",
+      value: 0,
+      total: targetSymbols,
+      percentage: 0,
+      threshold: { warn: 50, error: 20 },
+      description: `The embedding table exists for this project but holds no vectors, so semantic search is keyword-only. ${totalSymbols} symbols are indexed.`,
+      remediation: 'Generate embeddings with the bb_index tool: { path: "<project path>", mode: "post" } (CLI: bb index "<project path>").'
+    };
+  }
+  const models = rawDb.prepare(`
+    SELECT embedding_model, COUNT(*) as count FROM brain_semantic_embedding
+    WHERE project_id = ?
+    GROUP BY embedding_model
+  `).all(projectId);
+  const modelDesc = models.map((m) => `${m.embedding_model}: ${m.count}`).join(", ");
+  return {
+    name: "Embedding Coverage",
+    status: pct < 20 ? "error" : pct < 50 ? "warn" : "ok",
+    // M64.I4: `value`/`total` are now the TARGETED population (distinct
+    // embedded entities over the symbols of the kinds the embedder reaches),
+    // so the check's own numbers are the actionable ones. The all-symbols share
+    // is carried in the description rather than folded into the verdict.
+    value: embedded,
+    total: targetSymbols,
+    percentage: Math.round(pct * 10) / 10,
+    threshold: { warn: 50, error: 20 },
+    description: `${embedded} of ${targetSymbols} embeddable symbols have vectors (${Math.round(overallShare * 10) / 10}% of all ${totalSymbols} symbols; ${kindDesc || "no kinds embedded"}). Counts DISTINCT entities, not rows, so a symbol embedded by several models counts once. Kinds absent from the embedding table are never attempted \u2014 that share of the gap is not a coverage failure. Models: ${modelDesc || "none"}.`,
+    remediation: pct < 50 ? `Generate embeddings with the bb_index tool: { path: "<project path>", mode: "post" } (CLI: bb index "<project path>"). This closes the gap over the kinds already targeted; kinds that never appear in the embedding table need an analyzer that emits a snippet for them, not a reindex.` : void 0
+  };
+}
+async function checkSyntaxErrorFiles(rawDb, projectId) {
+  const totalRow = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_file WHERE project_id = ?
+  `).get(projectId);
+  const total = totalRow?.count ?? 0;
+  const errorRow = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_file WHERE project_id = ? AND has_syntax_errors = 1
+  `).get(projectId);
+  const errorCount = errorRow?.count ?? 0;
+  let sample = [];
+  if (errorCount > 0) {
+    const rows = rawDb.prepare(`
+      SELECT relative_path, language FROM brain_file
+      WHERE project_id = ? AND has_syntax_errors = 1
+      LIMIT 5
+    `).all(projectId);
+    sample = rows.map((r) => `${r.relative_path} (${r.language})`);
+  }
+  return {
+    name: "Syntax Error Files",
+    status: errorCount > total * 0.1 ? "error" : errorCount > total * 0.02 ? "warn" : "ok",
+    value: errorCount,
+    total,
+    percentage: total > 0 ? Math.round((1 - errorCount / total) * 1e3) / 10 : 100,
+    threshold: { warn: 2, error: 10 },
+    description: `${errorCount} files have recorded syntax errors. Tools operating on these files may produce incorrect byte bounds and garbled ASTs.`,
+    remediation: errorCount > 0 ? "These files were parsed with errors. If they are hand-written code (not generated), fix the syntax errors. Otherwise, tools should check has_syntax_errors before operating." : void 0,
+    sample: sample.length > 0 ? sample : void 0
+  };
+}
+async function checkWalSize(rawDb, projectId) {
+  try {
+    const pageCount = rawDb.prepare("PRAGMA page_count").get()?.page_count ?? 0;
+    const pageSize = rawDb.prepare("PRAGMA page_size").get()?.page_size ?? 4096;
+    const dbSizeBytes = pageCount * pageSize;
+    const { BrainDatabase: BDB } = await import("./database-76RP44JG.js");
+    const rawPath = BDB.getPath(projectId);
+    const walPath = rawPath + "-wal";
+    let walSizeBytes = 0;
+    try {
+      walSizeBytes = fs.statSync(walPath).size;
+    } catch {
+      walSizeBytes = 0;
+    }
+    const walMB = Math.round(walSizeBytes / (1024 * 1024) * 10) / 10;
+    return {
+      name: "WAL Size",
+      status: walMB > 500 ? "error" : walMB > 100 ? "warn" : "ok",
+      value: walSizeBytes,
+      total: dbSizeBytes,
+      percentage: dbSizeBytes > 0 ? Math.round((1 - walSizeBytes / (dbSizeBytes + walSizeBytes)) * 1e3) / 10 : 100,
+      threshold: { warn: 100, error: 500 },
+      description: `WAL file is ${walMB} MB (DB is ${Math.round(dbSizeBytes / (1024 * 1024) * 10) / 10} MB). Large WAL files slow down read queries.`,
+      remediation: walMB > 200 ? "WAL will auto-checkpoint. If this persists, restart the brain service." : void 0
+    };
+  } catch (e) {
+    return {
+      name: "WAL Size",
+      status: "warn",
+      value: 0,
+      threshold: { warn: 100, error: 500 },
+      description: `WAL size was NOT MEASURED (${e instanceof Error ? e.message : String(e)}). This check neither passed nor failed; it did not run.`
+    };
+  }
+}
+async function checkEmptyFiles(rawDb, projectId) {
+  const row = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_file f
+    WHERE f.project_id = ?
+      AND NOT EXISTS (SELECT 1 FROM brain_symbol s WHERE s.file_id = f.id AND s.project_id = f.project_id)
+      AND f.language IS NOT NULL
+      AND f.language != 'unknown'
+  `).get(projectId);
+  const emptyCount = row?.count ?? 0;
+  let sample = [];
+  if (emptyCount > 0) {
+    const rows = rawDb.prepare(`
+      SELECT f.relative_path, f.language FROM brain_file f
+      WHERE f.project_id = ?
+        AND NOT EXISTS (SELECT 1 FROM brain_symbol s WHERE s.file_id = f.id AND s.project_id = f.project_id)
+        AND f.language IS NOT NULL AND f.language != 'unknown'
+      LIMIT 5
+    `).all(projectId);
+    sample = rows.map((r) => `${r.relative_path} (${r.language})`);
+  }
+  return {
+    name: "Files with Zero Symbols",
+    status: emptyCount > 1e3 ? "error" : emptyCount > 100 ? "warn" : "ok",
+    value: emptyCount,
+    threshold: { warn: 100, error: 1e3 },
+    description: `${emptyCount} indexed files have zero extracted symbols. These may be empty files, config files, or files the parser couldn't understand.`,
+    remediation: emptyCount > 500 ? "These are likely config, documentation, or generated files \u2014 generally expected. Investigate if code files are affected." : void 0,
+    sample: sample.length > 0 ? sample : void 0
+  };
+}
+async function checkRelationshipRatio(rawDb, projectId) {
+  const symbolRow = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_symbol WHERE project_id = ?
+  `).get(projectId);
+  const totalSymbols = symbolRow?.count ?? 0;
+  const relRow = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_relationship WHERE project_id = ?
+  `).get(projectId);
+  const totalRels = relRow?.count ?? 0;
+  const ratio = totalSymbols > 0 ? totalRels / totalSymbols : 0;
+  const status = totalSymbols === 0 ? "ok" : ratio < 0.1 ? "error" : ratio < 0.5 ? "warn" : "ok";
+  return {
+    name: "Relationship Density",
+    status,
+    value: totalRels,
+    total: totalSymbols,
+    percentage: Math.round(ratio * 100) / 100,
+    threshold: { warn: 0.5, error: 0.1 },
+    description: `${ratio.toFixed(2)} relationships per symbol. Below 0.5 may indicate relationship extraction issues (some language analyzers may not produce relationships). Below 0.1 indicates a likely indexing failure.`,
+    remediation: ratio < 0.3 ? "Check if the project's primary language has relationship extraction support. Some languages (CSS, JSON, YAML) naturally have low relationship density." : void 0
+  };
+}
+async function preFlightCheck(projectId, context) {
+  const rawDb = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+  const warnings = [];
+  const fixes = [];
+  if (context.fileId) {
+    const syntaxRow = rawDb.prepare(`
+      SELECT has_syntax_errors FROM brain_file WHERE id = ? AND project_id = ?
+    `).get(context.fileId, projectId);
+    if (syntaxRow?.has_syntax_errors) {
+      warnings.push("Target file has recorded syntax errors. Byte bounds may be incorrect.");
+      fixes.push("Use bb_search mode=symbol to manually review the file. Avoid bb_edit on this file.");
+    }
+  }
+  if (context.symbolName && context.fileId) {
+    const boundsRow = rawDb.prepare(`
+      SELECT byte_start, byte_end FROM brain_symbol
+      WHERE file_id = ? AND name = ? AND project_id = ?
+      LIMIT 1
+    `).get(context.fileId, context.symbolName, projectId);
+    if (boundsRow && (boundsRow.byte_start === null || boundsRow.byte_end === null)) {
+      warnings.push(`Symbol "${context.symbolName}" has NULL byte bounds. Edits may be imprecise.`);
+      fixes.push("Run bb_health with refresh=true and wait=true to reindex this file, or use line-based editing.");
+    }
+  }
+  const symbolCount = rawDb.prepare(`
+    SELECT COUNT(*) as count FROM brain_symbol WHERE project_id = ?
+  `).get(projectId)?.count ?? 0;
+  if (symbolCount < 100) {
+    warnings.push("Brain index is nearly empty. Most tools will return no results.");
+    fixes.push("Run bb_health with refresh=true to index the project first.");
+  }
+  return {
+    ok: warnings.length === 0,
+    warnings,
+    fixes
+  };
+}
+function formatHealthReport(report) {
+  const barLen = 20;
+  const filled = Math.round(report.overallHealth / 100 * barLen);
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
+  const verdictWord = {
+    healthy: "HEALTHY",
+    degraded: "DEGRADED",
+    broken: "BROKEN",
+    empty: "EMPTY \u2014 nothing is indexed"
+  };
+  let output = `INDEX HEALTH: ${report.overallHealth}%  [${bar}]  ${verdictWord[report.verdict]}
+`;
+  if (report.verdict === "empty") {
+    output += `  \u2191 the score above counts checks that pass because there is NO DATA to be malformed.
+`;
+    output += `    It is not a measure of an index's quality. Run: bb index "<project path>"
+`;
+  }
+  output += `Project: ${report.projectId}
+`;
+  output += `Time: ${new Date(report.timestamp).toISOString()}
+`;
+  output += `Status: ${report.summary.ok} OK / ${report.summary.warn} WARN / ${report.summary.error} ERROR (${report.summary.scored} scored + ${report.summary.informational} informational)
+`;
+  const s = report.staleness;
+  const stalenessScope = s.complete ? `all ${s.total} indexed files` : `a ${s.sampleSize}-file sample of ${s.total} \u2014 a LOWER BOUND, not a total`;
+  output += `Staleness (${s.basis}): ${s.fresh} fresh | ${s.stale} stale | ${s.missing} missing | ${s.unclassified} unclassified \u2014 ${stalenessScope}${s.verifiedByContent > 0 ? `, ${s.verifiedByContent} verified by content` : ""}
+`;
+  if (!report.indexStatus.recorded) {
+    output += `Index status: UNRECORDED \u2014 this project has no brain_index_status row, so completeness is not knowable from the index.
+`;
+  } else {
+    const i = report.indexStatus;
+    output += `Index status: recorded=${i.status ?? "null"} indexed=${i.indexedFiles ?? "?"}/${i.totalFiles ?? "?"}${i.shortfall ? ` \u2014 INCOMPLETE, ${i.shortfall} file(s) never written` : ""}
+`;
+  }
+  output += "\n";
+  const icon = (s2) => s2 === "ok" ? "\u2705" : s2 === "warn" ? "\u26A0\uFE0F" : "\u274C";
+  for (const check of report.checks) {
+    const pctStr = check.percentage !== void 0 ? ` (${check.percentage}%)` : "";
+    const mark = check.kind === "informational" ? "\u2139\uFE0F " : icon(check.status);
+    const scope = check.kind === "informational" ? " [informational \u2014 not scored]" : "";
+    output += `${mark} ${check.name}: ${check.value.toLocaleString()}${check.total ? ` / ${check.total.toLocaleString()}` : ""}${pctStr}${scope}
+`;
+    output += `   ${check.description}
+`;
+    if (check.remediation) {
+      output += `   \u{1F527} ${check.remediation}
+`;
+    }
+    if (check.sample && check.sample.length > 0) {
+      output += `   Sample: ${check.sample.slice(0, 3).join(", ")}
+`;
+    }
+    output += "\n";
+  }
+  return output;
+}
+
+export {
+  runIndexHealthCheck,
+  checkEmbeddingCoverage,
+  preFlightCheck,
+  formatHealthReport
+};