agenr 0.6.15 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.7.1] - 2026-02-20
+
+### Added
+- feat(init): new `agenr init` command to auto-wire project instructions, MCP config, and `.agenr/config.json` with project slug/platform/projectDir
+- feat(init): `--depends-on` support for dependency-aware project recall scope in `.agenr/config.json`
+
+### Changed
+- feat(mcp): default `agenr_recall` scope now reads `AGENR_PROJECT_DIR` + `.agenr/config.json` per call and auto-includes direct dependencies when `project` is omitted
+- feat(mcp): `project="*"` now bypasses configured project scope, while explicit `project` values stay strict (no dependency expansion)
+- feat(mcp): default `agenr_store` project now comes from configured project scope when caller omits `project`
+- docs: corrected setup guidance in `docs/guides/scenarios.md` and aligned MCP examples in `docs/MCP.md` with current init output
+
+### Removed
+- perf(mcp): removed public `since_seq` parameter/handler from `agenr_recall`
+- perf(plugin): removed redundant OpenClaw `writeAgenrMd` write path (session-start context is still injected via `prependContext`)
+- perf(signals): removed extra `agenr_recall` footer from signal notifications for lower token overhead
+
+## [0.7.0] - 2026-02-19
+
+### Added
+- feat(signals): mid-session signal delivery via `before_prompt_build` hook - notifies agents of new high-importance entries (imp >= 7) with compact 50-100 token notifications
+- feat(signals): `signal_watermarks` table for per-consumer rowid-based watermark tracking
+- feat(mcp): `since_seq` parameter on `agenr_recall` for watermark-based incremental recall without embedding cost
+- feat(plugin): `signalsEnabled`, `signalMinImportance`, `signalMaxPerSignal`, and `dbPath` plugin config options
+
+### Changed
+- refactor(plugin): plugin now opens a direct DB connection for sub-ms signal queries (vs CLI spawn)
+- refactor(plugin/types): expanded `PluginApi` and `AgenrPluginConfig` types for signal support
+
 ## [0.6.15] - 2026-02-19
 
 ### Changed

package/dist/chunk-TW7FHRVW.js

@@ -0,0 +1,586 @@
+// src/version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var APP_VERSION = (() => {
+  try {
+    const raw = require2("../package.json");
+    if (typeof raw.version === "string" && raw.version.trim().length > 0) {
+      return raw.version.trim();
+    }
+  } catch {
+  }
+  const fromEnv = process.env.npm_package_version;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return fromEnv.trim();
+  }
+  return "0.0.0";
+})();
+
+// src/db/client.ts
+import { createClient } from "@libsql/client";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+
+// src/db/schema.ts
+var CREATE_IDX_ENTRIES_EMBEDDING_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_entries_embedding ON entries (
+    libsql_vector_idx(embedding, 'metric=cosine', 'compress_neighbors=float8', 'max_neighbors=50')
+  )
+`;
+var CREATE_ENTRIES_FTS_TABLE_SQL = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+    content, subject, content=entries, content_rowid=rowid
+  )
+`;
+var CREATE_ENTRIES_FTS_TRIGGER_AI_SQL = `
+  CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+    INSERT INTO entries_fts(rowid, content, subject) VALUES (new.rowid, new.content, new.subject);
+  END
+`;
+var CREATE_ENTRIES_FTS_TRIGGER_AD_SQL = `
+  CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+    INSERT INTO entries_fts(entries_fts, rowid, content, subject) VALUES ('delete', old.rowid, old.content, old.subject);
+  END
+`;
+var CREATE_ENTRIES_FTS_TRIGGER_AU_SQL = `
+  CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+    INSERT INTO entries_fts(entries_fts, rowid, content, subject) VALUES ('delete', old.rowid, old.content, old.subject);
+    INSERT INTO entries_fts(rowid, content, subject) VALUES (new.rowid, new.content, new.subject);
+  END
+`;
+var REBUILD_ENTRIES_FTS_SQL = "INSERT INTO entries_fts(entries_fts) VALUES ('rebuild')";
+var LEGACY_IMPORTANCE_BACKFILL_META_KEY = "legacy_importance_backfill_from_confidence_v1";
+var CREATE_TABLE_AND_TRIGGER_STATEMENTS = [
+  `
+  CREATE TABLE IF NOT EXISTS _meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS entries (
+    id TEXT PRIMARY KEY,
+    type TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    canonical_key TEXT,
+    content TEXT NOT NULL,
+    importance INTEGER NOT NULL,
+    expiry TEXT NOT NULL,
+    scope TEXT DEFAULT 'private',
+    platform TEXT DEFAULT NULL,
+    project TEXT DEFAULT NULL,
+    source_file TEXT,
+    source_context TEXT,
+    embedding F32_BLOB(1024),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_recalled_at TEXT,
+    recall_count INTEGER DEFAULT 0,
+    confirmations INTEGER DEFAULT 0,
+    contradictions INTEGER DEFAULT 0,
+    superseded_by TEXT,
+    content_hash TEXT,
+    merged_from INTEGER DEFAULT 0,
+    consolidated_at TEXT,
+    retired INTEGER NOT NULL DEFAULT 0,
+    retired_at TEXT,
+    retired_reason TEXT,
+    suppressed_contexts TEXT,
+    FOREIGN KEY (superseded_by) REFERENCES entries(id)
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS tags (
+    entry_id TEXT NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (entry_id, tag),
+    FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS relations (
+    id TEXT PRIMARY KEY,
+    source_id TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    relation_type TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (source_id) REFERENCES entries(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_id) REFERENCES entries(id) ON DELETE CASCADE
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS ingest_log (
+    id TEXT PRIMARY KEY,
+    file_path TEXT NOT NULL,
+    ingested_at TEXT NOT NULL,
+    entries_added INTEGER NOT NULL,
+    entries_updated INTEGER NOT NULL,
+    entries_skipped INTEGER NOT NULL,
+    duration_ms INTEGER NOT NULL,
+    content_hash TEXT,
+    entries_superseded INTEGER NOT NULL DEFAULT 0,
+    dedup_llm_calls INTEGER NOT NULL DEFAULT 0
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS entry_sources (
+    merged_entry_id TEXT NOT NULL REFERENCES entries(id),
+    source_entry_id TEXT NOT NULL REFERENCES entries(id),
+    original_confirmations INTEGER NOT NULL DEFAULT 0,
+    original_recall_count INTEGER NOT NULL DEFAULT 0,
+    original_created_at TEXT,
+    PRIMARY KEY (merged_entry_id, source_entry_id)
+  )
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS signal_watermarks (
+    consumer_id TEXT PRIMARY KEY,
+    last_received_seq INTEGER NOT NULL DEFAULT 0,
+    updated_at TEXT NOT NULL
+  )
+  `,
+  CREATE_ENTRIES_FTS_TABLE_SQL,
+  CREATE_ENTRIES_FTS_TRIGGER_AI_SQL,
+  CREATE_ENTRIES_FTS_TRIGGER_AD_SQL,
+  CREATE_ENTRIES_FTS_TRIGGER_AU_SQL
+];
+var CREATE_INDEX_STATEMENTS = [
+  CREATE_IDX_ENTRIES_EMBEDDING_SQL,
+  "CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(type)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_type_canonical_key ON entries(type, canonical_key)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_expiry ON entries(expiry)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_scope ON entries(scope)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_platform ON entries(platform)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_project ON entries(project)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_created ON entries(created_at)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_superseded ON entries(superseded_by)",
+  "CREATE INDEX IF NOT EXISTS idx_entries_content_hash ON entries(content_hash)",
+  "CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag)",
+  "CREATE INDEX IF NOT EXISTS idx_relations_source ON relations(source_id)",
+  "CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target_id)",
+  "CREATE UNIQUE INDEX IF NOT EXISTS idx_ingest_log_file_hash ON ingest_log(file_path, content_hash)"
+];
+var COLUMN_MIGRATIONS = [
+  {
+    table: "entries",
+    column: "importance",
+    sql: "ALTER TABLE entries ADD COLUMN importance INTEGER NOT NULL DEFAULT 5"
+  },
+  {
+    table: "entries",
+    column: "canonical_key",
+    sql: "ALTER TABLE entries ADD COLUMN canonical_key TEXT"
+  },
+  {
+    table: "entries",
+    column: "scope",
+    sql: "ALTER TABLE entries ADD COLUMN scope TEXT DEFAULT 'private'"
+  },
+  {
+    table: "entries",
+    column: "content_hash",
+    sql: "ALTER TABLE entries ADD COLUMN content_hash TEXT"
+  },
+  {
+    table: "entries",
+    column: "merged_from",
+    sql: "ALTER TABLE entries ADD COLUMN merged_from INTEGER DEFAULT 0"
+  },
+  {
+    table: "entries",
+    column: "consolidated_at",
+    sql: "ALTER TABLE entries ADD COLUMN consolidated_at TEXT"
+  },
+  {
+    table: "entries",
+    column: "platform",
+    sql: "ALTER TABLE entries ADD COLUMN platform TEXT DEFAULT NULL"
+  },
+  {
+    table: "entries",
+    column: "project",
+    sql: "ALTER TABLE entries ADD COLUMN project TEXT DEFAULT NULL"
+  },
+  {
+    table: "entries",
+    column: "retired",
+    sql: "ALTER TABLE entries ADD COLUMN retired INTEGER NOT NULL DEFAULT 0"
+  },
+  {
+    table: "entries",
+    column: "idx_entries_retired",
+    sql: "CREATE INDEX IF NOT EXISTS idx_entries_retired ON entries (retired) WHERE retired = 0",
+    isIndex: true
+  },
+  {
+    table: "entries",
+    column: "retired_at",
+    sql: "ALTER TABLE entries ADD COLUMN retired_at TEXT"
+  },
+  {
+    table: "entries",
+    column: "retired_reason",
+    sql: "ALTER TABLE entries ADD COLUMN retired_reason TEXT"
+  },
+  {
+    table: "entries",
+    column: "suppressed_contexts",
+    sql: "ALTER TABLE entries ADD COLUMN suppressed_contexts TEXT"
+  },
+  {
+    table: "ingest_log",
+    column: "content_hash",
+    sql: "ALTER TABLE ingest_log ADD COLUMN content_hash TEXT"
+  },
+  {
+    table: "ingest_log",
+    column: "entries_superseded",
+    sql: "ALTER TABLE ingest_log ADD COLUMN entries_superseded INTEGER NOT NULL DEFAULT 0"
+  },
+  {
+    table: "ingest_log",
+    column: "dedup_llm_calls",
+    sql: "ALTER TABLE ingest_log ADD COLUMN dedup_llm_calls INTEGER NOT NULL DEFAULT 0"
+  },
+  {
+    table: "entry_sources",
+    column: "original_created_at",
+    sql: "ALTER TABLE entry_sources ADD COLUMN original_created_at TEXT"
+  },
+  {
+    table: "entries",
+    column: "recall_intervals",
+    sql: "ALTER TABLE entries ADD COLUMN recall_intervals TEXT DEFAULT NULL"
+  }
+];
+async function initSchema(client) {
+  for (const statement of CREATE_TABLE_AND_TRIGGER_STATEMENTS) {
+    await client.execute(statement);
+  }
+  let willRunLegacyBackfill = false;
+  try {
+    const earlyEntriesInfo = await client.execute("PRAGMA table_info(entries)");
+    const earlyColumns = new Set(earlyEntriesInfo.rows.map((row) => String(row.name)));
+    if (earlyColumns.has("confidence")) {
+      const sentinel = await client.execute({
+        sql: "SELECT 1 AS found FROM _meta WHERE key = ? LIMIT 1",
+        args: [LEGACY_IMPORTANCE_BACKFILL_META_KEY]
+      });
+      const alreadyBackfilled = sentinel.rows.length > 0;
+      willRunLegacyBackfill = !alreadyBackfilled;
+    }
+  } catch {
+  }
+  try {
+    const entriesCountResult = await client.execute("SELECT COUNT(*) AS count FROM entries");
+    const entriesCount = Number(entriesCountResult.rows[0]?.count ?? 0);
+    const ftsCountResult = await client.execute("SELECT COUNT(*) AS count FROM entries_fts");
+    const ftsCount = Number(ftsCountResult.rows[0]?.count ?? 0);
+    if (entriesCount > 0 && ftsCount === 0 && !willRunLegacyBackfill) {
+      await client.execute(REBUILD_ENTRIES_FTS_SQL);
+    }
+  } catch {
+  }
+  for (const migration of COLUMN_MIGRATIONS) {
+    if (migration.isIndex) {
+      const existingIndex = await client.execute({
+        sql: "SELECT name FROM sqlite_master WHERE type='index' AND name=?",
+        args: [migration.column]
+      });
+      if (existingIndex.rows.length > 0) {
+        continue;
+      }
+      await client.execute(migration.sql);
+      continue;
+    }
+    const info = await client.execute(`PRAGMA table_info(${migration.table})`);
+    const hasColumn = info.rows.some((row) => String(row.name) === migration.column);
+    if (!hasColumn) {
+      await client.execute(migration.sql);
+    }
+  }
+  const entriesInfo = await client.execute("PRAGMA table_info(entries)");
+  const entryColumns = new Set(entriesInfo.rows.map((row) => String(row.name)));
+  const backfillSentinel = await client.execute({
+    sql: "SELECT 1 AS found FROM _meta WHERE key = ? LIMIT 1",
+    args: [LEGACY_IMPORTANCE_BACKFILL_META_KEY]
+  });
+  const legacyBackfillDone = backfillSentinel.rows.length > 0;
+  if (entryColumns.has("confidence") && entryColumns.has("importance") && !legacyBackfillDone) {
+    try {
+      await client.execute("DROP TRIGGER IF EXISTS entries_ai");
+      await client.execute("DROP TRIGGER IF EXISTS entries_ad");
+      await client.execute("DROP TRIGGER IF EXISTS entries_au");
+      await client.execute("DROP TABLE IF EXISTS entries_fts");
+    } catch {
+    }
+    await client.execute(`
+      UPDATE entries
+      SET importance = CASE lower(trim(confidence))
+        WHEN 'low' THEN 3
+        WHEN 'medium' THEN 6
+        WHEN 'high' THEN 8
+        ELSE
+          CASE
+            WHEN CAST(confidence AS INTEGER) BETWEEN 1 AND 10 THEN CAST(confidence AS INTEGER)
+            ELSE 5
+          END
+      END
+      WHERE importance = 5
+    `);
+    try {
+      await client.execute(CREATE_ENTRIES_FTS_TABLE_SQL);
+      await client.execute(CREATE_ENTRIES_FTS_TRIGGER_AI_SQL);
+      await client.execute(CREATE_ENTRIES_FTS_TRIGGER_AD_SQL);
+      await client.execute(CREATE_ENTRIES_FTS_TRIGGER_AU_SQL);
+      await client.execute(REBUILD_ENTRIES_FTS_SQL);
+    } catch {
+    }
+    try {
+      await client.execute({
+        sql: `
+          INSERT INTO _meta (key, value, updated_at)
+          VALUES (?, datetime('now'), datetime('now'))
+          ON CONFLICT(key) DO NOTHING
+        `,
+        args: [LEGACY_IMPORTANCE_BACKFILL_META_KEY]
+      });
+    } catch {
+    }
+  }
+  for (const statement of CREATE_INDEX_STATEMENTS) {
+    await client.execute(statement);
+  }
+  await client.execute({
+    sql: `
+      INSERT INTO _meta (key, value, updated_at)
+      VALUES ('db_created_at', datetime('now'), datetime('now'))
+      ON CONFLICT(key) DO NOTHING
+    `,
+    args: []
+  });
+  await client.execute({
+    sql: `
+      INSERT INTO _meta (key, value, updated_at)
+      VALUES ('schema_version', ?, datetime('now'))
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+    `,
+    args: [APP_VERSION]
+  });
+}
+async function resetDb(db) {
+  const foreignKeysResult = await db.execute("PRAGMA foreign_keys");
+  const foreignKeysRow = foreignKeysResult.rows[0];
+  const previousForeignKeys = Number(foreignKeysRow?.foreign_keys ?? (foreignKeysRow ? Object.values(foreignKeysRow)[0] : 1)) === 0 ? 0 : 1;
+  await db.execute("PRAGMA foreign_keys=OFF");
+  try {
+    const schemaObjects = await db.execute(`
+      SELECT type, name
+      FROM sqlite_master
+      WHERE name NOT LIKE 'sqlite_%'
+      ORDER BY
+        CASE type
+          WHEN 'trigger' THEN 1
+          WHEN 'index' THEN 2
+          WHEN 'table' THEN 3
+          ELSE 4
+        END,
+        name
+    `);
+    for (const row of schemaObjects.rows) {
+      const type = String(row.type ?? "");
+      const name = String(row.name ?? "");
+      if (!type || !name) {
+        continue;
+      }
+      const safeName = name.replace(/"/g, '""');
+      if (type === "trigger") {
+        await db.execute(`DROP TRIGGER IF EXISTS "${safeName}"`);
+        continue;
+      }
+      if (type === "index") {
+        await db.execute(`DROP INDEX IF EXISTS "${safeName}"`);
+        continue;
+      }
+      if (type === "table") {
+        await db.execute(`DROP TABLE IF EXISTS "${safeName}"`);
+      }
+    }
+    await initSchema(db);
+  } finally {
+    await db.execute(`PRAGMA foreign_keys=${previousForeignKeys === 0 ? "OFF" : "ON"}`);
+  }
+}
+
+// src/db/client.ts
+var DEFAULT_DB_PATH = path.join(os.homedir(), ".agenr", "knowledge.db");
+var walInitByClient = /* @__PURE__ */ new WeakMap();
+var didWarnVectorIndexCorruption = false;
+var WAL_CHECKPOINT_MAX_ATTEMPTS = 5;
+var WAL_CHECKPOINT_RETRY_MS = 50;
+function resolveUserPath(inputPath) {
+  if (!inputPath.startsWith("~")) {
+    return inputPath;
+  }
+  return path.join(os.homedir(), inputPath.slice(1));
+}
+function resolveDbPath(dbPath) {
+  if (dbPath === ":memory:") {
+    return dbPath;
+  }
+  return resolveUserPath(dbPath);
+}
+function normalizeBackupSourcePath(dbPath) {
+  const strippedDbPath = dbPath.startsWith("file:") ? dbPath.slice("file:".length) : dbPath;
+  return path.resolve(resolveDbPath(strippedDbPath));
+}
+function isErrnoCode(error, code) {
+  return error?.code === code;
+}
+async function copySidecarIfPresent(sourcePath, targetPath) {
+  try {
+    await fs.copyFile(sourcePath, targetPath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) {
+      return;
+    }
+    throw error;
+  }
+}
+function buildBackupPath(dbPath) {
+  const resolvedDbPath = normalizeBackupSourcePath(dbPath);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").replace(/Z$/, "");
+  return path.join(
+    path.dirname(resolvedDbPath),
+    `${path.basename(resolvedDbPath)}.backup-pre-reset-${timestamp}Z`
+  );
+}
+function getDb(dbPath) {
+  const rawPath = dbPath?.trim() ? dbPath.trim() : DEFAULT_DB_PATH;
+  if (rawPath === ":memory:") {
+    return createClient({ url: ":memory:" });
+  }
+  if (rawPath.startsWith("file:")) {
+    const client2 = createClient({ url: rawPath });
+    walInitByClient.set(
+      client2,
+      client2.execute("PRAGMA journal_mode=WAL").then(() => client2.execute("PRAGMA busy_timeout=3000")).then(() => void 0)
+    );
+    return client2;
+  }
+  const resolvedPath = resolveDbPath(rawPath);
+  const client = createClient({ url: `file:${resolvedPath}` });
+  walInitByClient.set(
+    client,
+    client.execute("PRAGMA journal_mode=WAL").then(() => client.execute("PRAGMA busy_timeout=3000")).then(() => void 0)
+  );
+  return client;
+}
+async function initDb(client) {
+  const walInit = walInitByClient.get(client);
+  if (walInit) {
+    await walInit;
+    await client.execute("PRAGMA wal_autocheckpoint=1000");
+  }
+  await initSchema(client);
+  try {
+    const hasEntries = await client.execute(
+      "SELECT 1 FROM entries WHERE embedding IS NOT NULL LIMIT 1"
+    );
+    if (hasEntries.rows.length > 0) {
+      await client.execute(`
+        SELECT count(*) FROM vector_top_k(
+          'idx_entries_embedding',
+          (SELECT embedding FROM entries WHERE embedding IS NOT NULL LIMIT 1),
+          1
+        )
+      `);
+    }
+  } catch {
+    if (!didWarnVectorIndexCorruption) {
+      didWarnVectorIndexCorruption = true;
+      process.stderr.write(
+        "\n\u26A0\uFE0F  Vector index may be corrupted. Run `agenr db rebuild-index` to fix.\n\n"
+      );
+    }
+  }
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function extractBusyFromCheckpointRow(row) {
+  if (!row || typeof row !== "object") {
+    return null;
+  }
+  const record = row;
+  const busyValue = record.busy ?? Object.values(record)[0];
+  return toFiniteNumber(busyValue);
+}
+async function validatedWalCheckpoint(client) {
+  for (let attempt = 1; attempt <= WAL_CHECKPOINT_MAX_ATTEMPTS; attempt += 1) {
+    const result = await client.execute("PRAGMA wal_checkpoint(TRUNCATE)");
+    const busy = extractBusyFromCheckpointRow(result.rows[0]);
+    if (busy === null) {
+      throw new Error("WAL checkpoint returned an unexpected result and could not be validated.");
+    }
+    if (busy === 0) {
+      return;
+    }
+    if (attempt < WAL_CHECKPOINT_MAX_ATTEMPTS) {
+      await new Promise((resolve) => setTimeout(resolve, WAL_CHECKPOINT_RETRY_MS * attempt));
+      continue;
+    }
+    throw new Error(
+      `WAL checkpoint did not finish (busy=${busy}). Active readers are blocking backup safety.`
+    );
+  }
+}
+async function walCheckpoint(client) {
+  await validatedWalCheckpoint(client);
+}
+async function backupDb(dbPath) {
+  if (dbPath === ":memory:") {
+    throw new Error("Cannot back up in-memory databases.");
+  }
+  const checkpointClient = getDb(dbPath);
+  try {
+    await walCheckpoint(checkpointClient);
+  } finally {
+    closeDb(checkpointClient);
+  }
+  const resolvedDbPath = normalizeBackupSourcePath(dbPath);
+  const backupPath = buildBackupPath(dbPath);
+  await fs.copyFile(resolvedDbPath, backupPath);
+  await copySidecarIfPresent(`${resolvedDbPath}-wal`, `${backupPath}-wal`);
+  await copySidecarIfPresent(`${resolvedDbPath}-shm`, `${backupPath}-shm`);
+  return backupPath;
+}
+function closeDb(client) {
+  client.close();
+}
+
+export {
+  APP_VERSION,
+  CREATE_IDX_ENTRIES_EMBEDDING_SQL,
+  initSchema,
+  resetDb,
+  DEFAULT_DB_PATH,
+  buildBackupPath,
+  getDb,
+  initDb,
+  walCheckpoint,
+  backupDb,
+  closeDb
+};