@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/chunk-BQ3OVQ3P.js

@@ -0,0 +1,125 @@
+// src/cli/terminal-style.ts
+var CODES = {
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m",
+  reset: "\x1B[0m"
+};
+function colorEnabled(ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+  if (env.FORCE_COLOR === "1" || env.FORCE_COLOR === "true") return true;
+  return ctx.isTTY === true;
+}
+function style(text, kinds, enabled) {
+  if (!enabled || text.length === 0) return text;
+  let prefix = "";
+  for (const kind of kinds) prefix += CODES[kind] ?? "";
+  if (prefix.length === 0) return text;
+  return `${prefix}${text}${CODES.reset}`;
+}
+function bold(text, enabled) {
+  return style(text, ["bold"], enabled);
+}
+function dim(text, enabled) {
+  return style(text, ["dim"], enabled);
+}
+function cyan(text, enabled) {
+  return style(text, ["cyan"], enabled);
+}
+function green(text, enabled) {
+  return style(text, ["green"], enabled);
+}
+function yellow(text, enabled) {
+  return style(text, ["yellow"], enabled);
+}
+function red(text, enabled) {
+  return style(text, ["red"], enabled);
+}
+
+// src/util/log.ts
+var LEVEL_LABELS = {
+  [0 /* TRACE */]: "TRACE",
+  [1 /* DEBUG */]: "DEBUG",
+  [2 /* INFO */]: "INFO",
+  [3 /* WARN */]: "WARN",
+  [4 /* ERROR */]: "ERROR",
+  [5 /* SILENT */]: "SILENT"
+};
+var globalLevel = 2 /* INFO */;
+if (process.env.BB_LOG_LEVEL) {
+  const parsed = Number(process.env.BB_LOG_LEVEL);
+  const byName = LEVEL_LABELS[process.env.BB_LOG_LEVEL.toUpperCase()];
+  if (byName !== void 0) {
+    globalLevel = byName;
+  } else if (!Number.isNaN(parsed) && parsed >= 0 /* TRACE */ && parsed <= 5 /* SILENT */) {
+    globalLevel = parsed;
+  }
+}
+function setLogLevel(level) {
+  globalLevel = level;
+}
+function formatMessage(level, module, msg, context) {
+  const now = /* @__PURE__ */ new Date();
+  const time = `${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}:${String(now.getSeconds()).padStart(2, "0")}`;
+  const label = LEVEL_LABELS[level];
+  const ctx = context && Object.keys(context).length > 0 ? ` ${JSON.stringify(context)}` : "";
+  const useColor = colorEnabled({ isTTY: process.stderr.isTTY === true });
+  if (!useColor) return `[${label}] [${time}] [${module}] ${msg}${ctx}`;
+  const head = `[${label}] [${time}] [${module}]`;
+  const headColored = level === 4 /* ERROR */ ? red(head, true) : level === 3 /* WARN */ ? yellow(head, true) : dim(head, true);
+  const msgColored = level === 4 /* ERROR */ ? red(msg, true) : level === 3 /* WARN */ ? yellow(msg, true) : msg;
+  const ctxColored = ctx ? dim(ctx, true) : "";
+  return `${headColored} ${msgColored}${ctxColored}`;
+}
+function createLogger(module) {
+  return {
+    trace(msg, context) {
+      if (globalLevel <= 0 /* TRACE */) {
+        process.stderr.write(formatMessage(0 /* TRACE */, module, msg, context) + "\n");
+      }
+    },
+    debug(msg, context) {
+      if (globalLevel <= 1 /* DEBUG */) {
+        process.stderr.write(formatMessage(1 /* DEBUG */, module, msg, context) + "\n");
+      }
+    },
+    info(msg, context) {
+      if (globalLevel <= 2 /* INFO */) {
+        process.stderr.write(formatMessage(2 /* INFO */, module, msg, context) + "\n");
+      }
+    },
+    warn(msg, context) {
+      if (globalLevel <= 3 /* WARN */) {
+        process.stderr.write(formatMessage(3 /* WARN */, module, msg, context) + "\n");
+      }
+    },
+    error(msg, context) {
+      if (globalLevel <= 4 /* ERROR */) {
+        process.stderr.write(formatMessage(4 /* ERROR */, module, msg, context) + "\n");
+      }
+    }
+  };
+}
+
+// src/tool/brain-log.ts
+var logger = createLogger("brain");
+function create(tags) {
+  const service = tags?.service ?? "brain";
+  return createLogger(service);
+}
+
+export {
+  colorEnabled,
+  bold,
+  dim,
+  cyan,
+  green,
+  yellow,
+  red,
+  setLogLevel,
+  create
+};

package/dist/chunk-D2Q4Y47A.js

@@ -0,0 +1,53 @@
+// src/ast/scoped-path.ts
+import { existsSync, realpathSync, statSync } from "fs";
+import path from "path";
+function canonicalProjectRoot(projectPath) {
+  const resolved = path.resolve(projectPath);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function isInsideProject(absolute, projectRoot) {
+  if (absolute === projectRoot) return true;
+  return absolute.startsWith(projectRoot + path.sep);
+}
+function resolveScopedProjectFile(projectPath, input) {
+  const projectRoot = canonicalProjectRoot(projectPath);
+  const raw = typeof input === "string" ? input.trim() : "";
+  if (raw.length === 0) return { ok: false, reason: "empty-path", resolved: projectRoot, projectRoot };
+  const lexical = path.resolve(projectRoot, raw);
+  if (!isInsideProject(lexical, projectRoot)) {
+    return { ok: false, reason: "outside-project", resolved: lexical, projectRoot };
+  }
+  let canonical = lexical;
+  try {
+    canonical = realpathSync.native(lexical);
+  } catch {
+    return { ok: false, reason: "not-found", resolved: lexical, projectRoot };
+  }
+  if (!isInsideProject(canonical, projectRoot)) {
+    return { ok: false, reason: "outside-project", resolved: canonical, projectRoot };
+  }
+  try {
+    if (!statSync(canonical).isFile()) return { ok: false, reason: "not-a-file", resolved: canonical, projectRoot };
+  } catch {
+    return { ok: false, reason: "not-found", resolved: canonical, projectRoot };
+  }
+  if (!existsSync(canonical)) return { ok: false, reason: "not-found", resolved: canonical, projectRoot };
+  return { ok: true, absolute: canonical };
+}
+function describeScopedPathRefusal(result) {
+  const where = `(resolved against ${result.projectRoot})`;
+  if (result.reason === "empty-path") return `--file path is empty ${where}`;
+  if (result.reason === "not-found") return `--file not found: ${result.resolved} ${where}`;
+  if (result.reason === "not-a-file") return `--file is not a file: ${result.resolved} ${where}`;
+  return `--file is outside the project: ${result.resolved}; the project root is ${result.projectRoot}`;
+}
+
+export {
+  canonicalProjectRoot,
+  resolveScopedProjectFile,
+  describeScopedPathRefusal
+};

package/dist/chunk-DIYAGQJL.js

@@ -0,0 +1,34 @@
+import {
+  bbProjectsDir
+} from "./chunk-2BSKD7O3.js";
+
+// src/util/project-id.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, realpathSync, renameSync } from "fs";
+import path from "path";
+function getProjectId(projectPath) {
+  const resolved = path.resolve(projectPath);
+  let canonical = resolved;
+  try {
+    canonical = realpathSync.native(resolved);
+  } catch {
+  }
+  const canonicalId = createHash("sha1").update(canonical).digest("hex").substring(0, 40);
+  if (canonical !== resolved) {
+    const legacyId = createHash("sha1").update(resolved).digest("hex").substring(0, 40);
+    const legacyDir = path.join(bbProjectsDir(), legacyId);
+    const canonicalDir = path.join(bbProjectsDir(), canonicalId);
+    if (existsSync(legacyDir) && !existsSync(canonicalDir)) {
+      mkdirSync(bbProjectsDir(), { recursive: true });
+      try {
+        renameSync(legacyDir, canonicalDir);
+      } catch {
+      }
+    }
+  }
+  return canonicalId;
+}
+
+export {
+  getProjectId
+};

package/dist/chunk-DWKXZ6IF.js

@@ -0,0 +1,336 @@
+import {
+  fingerprintKey
+} from "./chunk-2RRBMNBQ.js";
+import {
+  SemanticEngine,
+  assessEndpoint,
+  classifyStatus,
+  describeEmbeddingSetup,
+  isEmbeddingDisabled,
+  observedEmbeddingFailures,
+  parseEndpoint,
+  probeEmbeddingEndpoint,
+  readRuntimeOptions
+} from "./chunk-B5GEAAYF.js";
+import {
+  LOCAL_VECTOR_DIMENSION
+} from "./chunk-7AN7U5IZ.js";
+import {
+  bbDataDir
+} from "./chunk-2BSKD7O3.js";
+import {
+  __export
+} from "./chunk-MLKGABMK.js";
+
+// src/setup/setup-show.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import path from "path";
+
+// src/brain/semantic/embedding-diagnosis.ts
+var embedding_diagnosis_exports = {};
+__export(embedding_diagnosis_exports, {
+  LOCAL_DIMENSION: () => LOCAL_DIMENSION,
+  buildEmbeddingChain: () => buildEmbeddingChain,
+  buildEmbeddingDiagnosis: () => buildEmbeddingDiagnosis,
+  embeddingChainVerdict: () => embeddingChainVerdict,
+  probeEmbeddingDiagnosis: () => probeEmbeddingDiagnosis,
+  renderChainSummary: () => renderChainSummary,
+  severityOf: () => severityOf
+});
+var LOCAL_LABEL_HINT = SemanticEngine.LOCAL_MODEL_LABEL;
+function sourceLabel(tier, field) {
+  return tier === "env" ? `env:BB_EMBEDDING_${field}` : `file:${tier}`;
+}
+function buildEmbeddingChain(state, env = process.env) {
+  const options = readRuntimeOptions(env);
+  const layers = [];
+  const winner = state.tiers.find((t) => t.tier === state.winner && t.complete);
+  if (isEmbeddingDisabled(env)) {
+    layers.push({
+      order: 0,
+      role: "disabled",
+      label: "embeddings disabled",
+      endpoint: "none",
+      model: "none",
+      keyState: "not-required",
+      source: "env:BB_EMBEDDING_DISABLED",
+      active: true,
+      problems: []
+    });
+  }
+  if (state.configured && winner) {
+    const hasKey = typeof winner.keyFingerprint === "string" && winner.keyFingerprint.length > 0;
+    const readiness = assessEndpoint(
+      winner.baseURL ?? "",
+      hasKey ? sourceLabel(winner.tier, "API_KEY") : "none",
+      hasKey ? sourceLabel(winner.tier, "API_KEY") : "none"
+    );
+    layers.push({
+      order: layers.length,
+      role: "primary",
+      label: `primary provider (${winner.tier})`,
+      endpoint: winner.baseURL ?? "",
+      model: winner.model ?? "",
+      keyState: readiness.hasKey ? "present" : readiness.loopback ? "not-required" : "absent",
+      source: `url ${sourceLabel(winner.tier, "BASE_URL")} \xB7 model ${sourceLabel(winner.tier, "MODEL")} \xB7 key ${hasKey ? sourceLabel(winner.tier, "API_KEY") : "none"}`,
+      active: !options.disabled,
+      problems: readiness.problems
+    });
+  }
+  if (options.fallback) {
+    const fbKeySource = options.fallback.apiKey ? "env:BB_EMBEDDING_API_KEY" : "none";
+    const readiness = assessEndpoint(options.fallback.baseURL, fbKeySource, "env:BB_EMBEDDING_FALLBACK_API_KEY");
+    layers.push({
+      order: layers.length,
+      role: "fallback",
+      label: "fallback provider",
+      endpoint: options.fallback.baseURL,
+      model: options.fallback.model,
+      keyState: readiness.hasKey ? "present" : readiness.loopback ? "not-required" : "absent",
+      source: `url env:BB_EMBEDDING_FALLBACK_BASE_URL \xB7 model env:BB_EMBEDDING_FALLBACK_MODEL \xB7 key ${options.fallback.apiKey ? "env:BB_EMBEDDING_FALLBACK_API_KEY" : "none"}`,
+      active: !options.disabled && state.configured,
+      problems: readiness.problems
+    });
+  }
+  layers.push({
+    order: layers.length,
+    role: "local",
+    label: "local word vectors",
+    endpoint: "offline",
+    model: LOCAL_LABEL_HINT,
+    keyState: "not-required",
+    source: "built in",
+    active: true,
+    problems: []
+  });
+  return layers;
+}
+function detectTierOrderDisagreement(state, env) {
+  if (state.winner !== "global") return null;
+  const project = state.tiers.find((t) => t.tier === "project");
+  if (!project?.complete) return null;
+  const explicit = (env.BB_CONFIG_FILE ?? "").trim();
+  return {
+    reported: state.winner,
+    actual: explicit ? "BB_CONFIG_FILE" : "project",
+    detail: `bb setup show and bb doctor report the global tier as the winner, but the runtime merges the file tiers project-last (bb.json overrides ~/.bb/config.json), so indexing actually uses ${explicit ? "BB_CONFIG_FILE" : "the project's bb.json"}` + (project.model ? ` (model ${project.model})` : "") + `.`
+  };
+}
+function reconstructSources(state) {
+  const firstWith = (field, pick, fallback) => {
+    for (const tier of state.tiers) {
+      const value = pick(tier);
+      if (typeof value === "string" && value.length > 0) return sourceLabel(tier.tier, field);
+    }
+    return fallback;
+  };
+  return {
+    baseURL: firstWith("BASE_URL", (t) => t.baseURL, "default"),
+    model: firstWith("MODEL", (t) => t.model, "default"),
+    apiKey: firstWith("API_KEY", (t) => t.keyFingerprint, "none")
+  };
+}
+function buildEmbeddingDiagnosis(opts) {
+  const env = opts.env ?? process.env;
+  const state = opts.state;
+  const chain = buildEmbeddingChain(state, env);
+  const winner = state.tiers.find((t) => t.tier === state.winner && t.complete);
+  const sources = reconstructSources(state);
+  const setup = describeEmbeddingSetup(
+    { baseURL: winner?.baseURL ?? "", model: winner?.model ?? "", configured: state.configured, sources },
+    env
+  );
+  const observed = opts.observedFailures ?? observedEmbeddingFailures().map((f) => ({ ...f, latched: true }));
+  return {
+    disabled: isEmbeddingDisabled(env),
+    configured: state.configured,
+    remoteReady: setup.remoteReady && !isEmbeddingDisabled(env),
+    fallbackConfigured: chain.some((l) => l.role === "fallback"),
+    primaryLayer: chain.find((l) => l.role === "primary") ?? null,
+    chain,
+    problems: setup.problems,
+    observedFailures: observed,
+    probe: null,
+    tierOrderDisagreement: detectTierOrderDisagreement(state, env)
+  };
+}
+async function probeEmbeddingDiagnosis(diagnosis, env = process.env) {
+  const layer = diagnosis.primaryLayer;
+  if (!layer || diagnosis.disabled) return { ...diagnosis, probe: null };
+  const endpoint = parseEndpoint(layer.endpoint);
+  const key = readApiKeyForProbe(layer, env);
+  const result = await probeEmbeddingEndpoint(
+    { baseURL: layer.endpoint, apiKey: key, model: layer.model },
+    { timeoutMs: Math.min(readRuntimeOptions(env).timeoutMs, 15e3) }
+  );
+  return {
+    ...diagnosis,
+    probe: {
+      ok: result.ok,
+      elapsedMs: result.elapsedMs,
+      endpoint: layer.endpoint,
+      model: layer.model,
+      dimension: result.dimension,
+      status: result.status,
+      kind: result.kind ?? (result.ok ? void 0 : classifyStatus(result.status ?? 0)),
+      advice: result.advice,
+      message: result.message
+    }
+  };
+}
+function readApiKeyForProbe(layer, env) {
+  if (layer.keyState === "absent") return "";
+  if (layer.source.startsWith("env:")) return env.BB_EMBEDDING_API_KEY ?? "";
+  return "";
+}
+function severityOf(problem) {
+  return problem.severity;
+}
+function renderChainSummary(diagnosis) {
+  return diagnosis.chain.map((l) => {
+    const mark = l.active ? "\u2192" : " ";
+    const target = l.role === "local" ? `${l.endpoint} \xB7 ${LOCAL_VECTOR_DIMENSION}-dim` : `${l.endpoint} \xB7 ${l.model}`;
+    const key = l.role === "local" || l.role === "disabled" ? "" : ` \xB7 key ${l.keyState}`;
+    return `  ${mark} ${l.order + 1}. ${l.label}: ${target}${key}  [${l.source}]`;
+  });
+}
+function embeddingChainVerdict(diagnosis) {
+  if (diagnosis.disabled) return "disabled (BB_EMBEDDING_DISABLED) \u2014 local word vectors only";
+  if (diagnosis.remoteReady) return diagnosis.fallbackConfigured ? "remote ready (primary + fallback)" : "remote ready";
+  return "remote NOT usable \u2014 semantic search degrades to local word vectors";
+}
+var LOCAL_DIMENSION = LOCAL_VECTOR_DIMENSION;
+
+// src/setup/setup-show.ts
+function readJsonSafe(p) {
+  try {
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function fileMode(p) {
+  try {
+    return statSync(p).mode & 511;
+  } catch {
+    return void 0;
+  }
+}
+function completeTier(tier, baseURL, model, key, file, skippedMarker) {
+  const present = baseURL !== void 0 || model !== void 0 || key !== void 0 || skippedMarker === true;
+  const complete = typeof baseURL === "string" && baseURL.length > 0 && typeof model === "string" && model.length > 0;
+  const missing = [];
+  if (!baseURL) missing.push("base URL");
+  if (!model) missing.push("model");
+  return {
+    tier,
+    present,
+    complete,
+    baseURL: typeof baseURL === "string" ? baseURL : void 0,
+    model: typeof model === "string" ? model : void 0,
+    keyFingerprint: typeof key === "string" && key.length > 0 ? fingerprintKey(key) : void 0,
+    file,
+    fileMode: file ? fileMode(file) : void 0,
+    incompleteReason: present && !complete ? `missing: ${missing.join(" + ")}` : void 0
+  };
+}
+function describeEmbeddingConfig(cwd = process.cwd(), env = process.env, dataDir = bbDataDir()) {
+  const globalFile = path.join(dataDir, "config.json");
+  const global = readJsonSafe(globalFile);
+  const projectFile = path.join(cwd, "bb.json");
+  const project = readJsonSafe(projectFile);
+  const envTier = completeTier(
+    "env",
+    env.BB_EMBEDDING_BASE_URL,
+    env.BB_EMBEDDING_MODEL,
+    env.BB_EMBEDDING_API_KEY
+  );
+  const globalTier = completeTier(
+    "global",
+    global?.embedding_base_url,
+    global?.embedding_model,
+    global?.embedding_api_key,
+    globalFile,
+    global?.setup_skipped === true
+  );
+  if (global && global.setup_skipped === true) globalTier.skippedMarker = true;
+  const projectTier = completeTier(
+    "project",
+    project?.embedding_base_url,
+    project?.embedding_model,
+    project?.embedding_api_key,
+    projectFile
+  );
+  const tiers = [envTier, globalTier, projectTier];
+  const winningTier = tiers.find((t) => t.complete);
+  const state = {
+    winner: winningTier?.tier ?? "none",
+    configured: Boolean(winningTier),
+    tiers
+  };
+  state.diagnosis = buildEmbeddingDiagnosis({ state, env });
+  return state;
+}
+function renderSetupShow(state) {
+  const lines = [];
+  lines.push("bb \u2014 embedding configuration");
+  lines.push("Precedence: env > ~/.bb/config.json > bb.json");
+  lines.push("");
+  const tierLabel = { env: "env", global: "global", project: "project" };
+  for (const t of state.tiers) {
+    const label = tierLabel[t.tier].padEnd(7);
+    if (!t.present) {
+      lines.push(`${label}: \u2014 (not set)`);
+      continue;
+    }
+    if (!t.complete) {
+      const key2 = t.keyFingerprint ? ` (key: \u2022\u2022\u2022\u2022${t.keyFingerprint})` : "";
+      const skipped = t.skippedMarker ? " \xB7 wizard skipped" : "";
+      lines.push(`${label}: \u2717 ${t.incompleteReason ?? "incomplete"}${key2}${skipped}`);
+      continue;
+    }
+    const key = t.keyFingerprint ? `key: \u2022\u2022\u2022\u2022${t.keyFingerprint}` : "key: none";
+    let line = `${label}: \u2713 ${t.baseURL} \xB7 ${t.model} \xB7 ${key}`;
+    if (t.fileMode !== void 0 && t.fileMode !== 384) {
+      line += ` \xB7 mode: ${t.fileMode.toString(8)} (expected: 600 \u2014 fix with bb doctor)`;
+    } else if (t.fileMode !== void 0) {
+      line += ` \xB7 mode: 600`;
+    }
+    if (t.skippedMarker) line += " \xB7 wizard skipped";
+    lines.push(line);
+  }
+  lines.push("");
+  if (state.configured) {
+    const w = state.winner;
+    lines.push(`Winner: ${tierLabel[w]}`);
+  } else {
+    lines.push("Winner: none \u2014 semantic search will use local vectors (weaker). Setup: bb setup");
+  }
+  const diagnosis = state.diagnosis;
+  if (diagnosis) {
+    lines.push("");
+    lines.push(`Chain: ${embeddingChainVerdict(diagnosis)}`);
+    for (const line of renderChainSummary(diagnosis)) lines.push(line);
+    const problems = diagnosis.problems.filter((p) => !/^No embedding provider is configured/.test(p.message));
+    for (const p of problems) {
+      const varName = p.envVar ? `${p.envVar}: ` : "";
+      lines.push(`  ! ${varName}${p.message}`);
+    }
+    for (const f of diagnosis.observedFailures) {
+      lines.push(`  \u2717 ${f.status} ${f.kind} from ${f.baseURL} \u2014 ${f.advice}`);
+    }
+    if (diagnosis.tierOrderDisagreement) {
+      lines.push(`  ! ${diagnosis.tierOrderDisagreement.detail}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+export {
+  buildEmbeddingDiagnosis,
+  renderChainSummary,
+  embedding_diagnosis_exports,
+  describeEmbeddingConfig,
+  renderSetupShow
+};

package/dist/chunk-DYM4FQEE.js

@@ -0,0 +1,90 @@
+// src/ast/index-space.ts
+import { statSync } from "fs";
+function runPragma(rawDb, body) {
+  const driver = rawDb?.native ?? rawDb;
+  if (typeof driver?.pragma === "function") return driver.pragma(body);
+  if (typeof driver?.prepare === "function") {
+    const stmt = driver.prepare(`PRAGMA ${body}`);
+    if (typeof stmt?.all === "function") {
+      const rows = stmt.all();
+      return Array.isArray(rows) ? rows : [rows];
+    }
+  }
+  return void 0;
+}
+function checkpointWal(rawDb) {
+  try {
+    const result = runPragma(rawDb, "wal_checkpoint(TRUNCATE)");
+    const row = Array.isArray(result) ? result[0] : result;
+    if (row && typeof row === "object" && "busy" in row) return Number(row.busy) === 0;
+    return true;
+  } catch {
+    return false;
+  }
+}
+function spaceReport(rawDb, dbPath) {
+  let dbBytes = 0;
+  let walBytes = 0;
+  try {
+    dbBytes = statSync(dbPath).size;
+  } catch {
+  }
+  try {
+    walBytes = statSync(`${dbPath}-wal`).size;
+  } catch {
+  }
+  let freelistBytes = 0;
+  let freeRatio = 0;
+  try {
+    const freeRow = runPragma(rawDb, "freelist_count");
+    const pageRow = runPragma(rawDb, "page_size");
+    const first = (row, key) => Array.isArray(row) ? row[0]?.[key] : row?.[key];
+    const free = Number(first(freeRow, "freelist_count") ?? 0);
+    const pageSize = Number(first(pageRow, "page_size") ?? 0);
+    freelistBytes = free * pageSize;
+    freeRatio = dbBytes > 0 ? freelistBytes / dbBytes : 0;
+  } catch {
+  }
+  return { dbBytes, walBytes, freelistBytes, freeRatio, checkpointed: false, vacuumed: false, vacuumMs: null };
+}
+function shouldVacuumAfterWipe(input) {
+  const minBytes = input.minBytes ?? 256 * 1024 * 1024;
+  return input.rowsDeleted > 0 && input.dbBytes >= minBytes;
+}
+function reclaimSpace(rawDb, dbPath, opts = {}) {
+  const checkpointed = checkpointWal(rawDb);
+  const before = spaceReport(rawDb, dbPath);
+  const ratioFloor = opts.vacuumAboveRatio ?? 0.25;
+  const byteFloor = opts.vacuumAboveBytes ?? 64 * 1024 * 1024;
+  const wantVacuum = opts.vacuum === true && before.freelistBytes >= byteFloor && before.freeRatio >= ratioFloor;
+  let vacuumed = false;
+  let vacuumMs = null;
+  if (wantVacuum && process.env.BB_INDEX_VACUUM !== "0") {
+    const started = Date.now();
+    try {
+      rawDb.exec("VACUUM");
+      vacuumed = true;
+    } catch (e) {
+      opts.log?.("VACUUM skipped", { error: String(e?.message ?? e) });
+    }
+    vacuumMs = Date.now() - started;
+    if (vacuumed) checkpointWal(rawDb);
+  }
+  const after = spaceReport(rawDb, dbPath);
+  return { ...after, checkpointed, vacuumed, vacuumMs };
+}
+function formatSpace(report) {
+  const mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;
+  const parts = [`db ${mb(report.dbBytes)}`, `wal ${mb(report.walBytes)}`];
+  if (report.freeRatio > 0) parts.push(`${(report.freeRatio * 100).toFixed(0)}% free`);
+  if (report.vacuumed && report.vacuumMs !== null) parts.push(`vacuumed in ${(report.vacuumMs / 1e3).toFixed(1)}s`);
+  return parts.join(", ");
+}
+
+export {
+  checkpointWal,
+  spaceReport,
+  shouldVacuumAfterWipe,
+  reclaimSpace,
+  formatSpace
+};