@agfpd/iapeer-memory-core 0.1.1

package/src/db.ts

@@ -0,0 +1,550 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Database } from "bun:sqlite";
+// sqlite-vec ships its own .d.ts; runtime API is just `load(db)`.
+import * as sqliteVec from "sqlite-vec";
+import type { CoreConfig } from "./config.js";
+import { prepareSqliteRuntime } from "./sqlite-loader.js";
+import { fromJson, toJson } from "./utils.js";
+
+export type CoreDb = Database & {
+  /**
+   * True if `sqlite-vec` virtual-table is available on this connection. When
+   * false, `vec_chunks` does not exist and `vectorSearch` must fall back to
+   * the brute-force `SELECT embedding FROM chunks` path. Set once at
+   * `openDatabase` time based on the process-wide sqlite runtime.
+   */
+  vecAvailable: boolean;
+};
+
+export type IndexedDocumentRow = {
+  path: string;
+  title: string;
+  type: string | null;
+  status: string | null;
+  tags: string[];
+  contentHash: string;
+  frontmatter: Record<string, unknown>;
+  created: string | null;
+  updated: string | null;
+  indexedAt: string;
+};
+
+export type SearchRow = {
+  path: string;
+  title: string;
+  score: number;
+  snippet: string;
+};
+
+export type OpenDatabaseOptions = {
+  /**
+   * Writer-only. When a `vec_chunks` table already exists at a dimension that
+   * differs from `config.embedding.dimensions` (the embedder was swapped for
+   * one with a different output width — e.g. Qwen3-Embedding-8B@4096 →
+   * Qwen3-Embedding-4B@2560), DROP it so the CREATE below rebuilds it at the
+   * new dimension. `CREATE VIRTUAL TABLE IF NOT EXISTS` alone keeps the stale
+   * dimension forever, and every embedding INSERT then fails with
+   * "Dimension mismatch ... Expected N ... received M", crash-looping the
+   * writer's vault scan. Embeddings are invalidated on the same swap
+   * (`checkEmbeddingModelChanged` nulls `chunks.embedding`), so dropping the
+   * vec mirror loses nothing — the re-embed pass repopulates both tables.
+   *
+   * Defaults to false so read-only MCP frontends (`src/server.ts`) never
+   * mutate the table: the single writer daemon owns this migration. A reader
+   * that opened during the swap window just sees an empty/stale vec_chunks and
+   * degrades to BM25 until the writer finishes re-embedding.
+   */
+  migrateVecDimension?: boolean;
+};
+
+export function openDatabase(config: CoreConfig, options: OpenDatabaseOptions = {}): CoreDb {
+  fs.mkdirSync(path.dirname(config.index.dbPath), { recursive: true });
+
+  // Process-wide: swap bun's stripped sqlite for one that supports extension
+  // loading (homebrew on macOS, distro libsqlite3 on Linux). Idempotent —
+  // safe to call from every openDatabase, the helper caches the decision.
+  const runtime = prepareSqliteRuntime();
+
+  // strict: true — bind named params (`@a`, `$a`, `:a`) by key without prefix.
+  // Without strict mode bun silently inserts NULL for `VALUES (@a) RUN { a: "x" }`.
+  const db = new Database(config.index.dbPath, { create: true, strict: true }) as CoreDb;
+  db.vecAvailable = false;
+  // The DB stores verbatim chunks of private vault content. On shared systems
+  // (multi-user macOS, misconfigured VPS) the default mode (typically 0644)
+  // would expose the whole vault to other local users. Lock it down.
+  // WAL/SHM siblings get the same treatment as soon as they appear.
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      fs.chmodSync(config.index.dbPath + suffix, 0o600);
+    } catch {
+      // Best effort — file may not exist yet (sidecars appear on first write)
+      // or the filesystem may not support chmod (FAT32, some network mounts).
+    }
+  }
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA foreign_keys = ON");
+
+  // Schema migration: prior versions carried `source` / `agent_id` columns
+  // for a diary channel that was never wired in the MCP build. The fields
+  // were removed in v0.7. Old databases keep working because SQLite ignores
+  // extra columns on INSERT only if they're NULLable — but `source` was
+  // NOT NULL, so a plain start against the legacy schema fails. Detect the
+  // legacy column and drop the four content tables; `fullScanOnStartup`
+  // (default true) will rebuild them. `meta` is preserved so embedding /
+  // parser fingerprints survive and don't force a needless re-embed sweep
+  // on every upgrade — they're invalidated separately by content changes.
+  const docCols = db.prepare("PRAGMA table_info(documents)").all() as Array<{ name: string }>;
+  const hasLegacyDiary = docCols.some((c) => c.name === "source" || c.name === "agent_id");
+  if (hasLegacyDiary) {
+    db.exec(`
+      DROP TABLE IF EXISTS documents;
+      DROP TABLE IF EXISTS chunk_fts;
+      DROP TABLE IF EXISTS chunks;
+      DROP TABLE IF EXISTS edges;
+    `);
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS documents (
+      path TEXT PRIMARY KEY,
+      title TEXT,
+      type TEXT,
+      status TEXT,
+      tags TEXT,
+      content_hash TEXT,
+      frontmatter TEXT,
+      created TEXT,
+      updated TEXT,
+      indexed_at TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS chunk_fts USING fts5(
+      chunk_text,
+      doc_path UNINDEXED,
+      chunk_index UNINDEXED,
+      tokenize='porter unicode61'
+    );
+
+    CREATE TABLE IF NOT EXISTS chunks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      doc_path TEXT NOT NULL,
+      chunk_index INTEGER NOT NULL,
+      chunk_text TEXT NOT NULL,
+      embedding BLOB,
+      UNIQUE(doc_path, chunk_index)
+    );
+
+    CREATE TABLE IF NOT EXISTS edges (
+      source_path TEXT NOT NULL,
+      target_path TEXT NOT NULL,
+      context_snippet TEXT,
+      PRIMARY KEY (source_path, target_path)
+    );
+
+    -- Wikilinks that could not be resolved to a real note. Kept first-class
+    -- instead of being silently dropped from edges: a missing/ambiguous link
+    -- is a vault health signal (surfaced via vault_map orphan_wikilinks +
+    -- the Index nightly health-check). reason ∈ 'missing' | 'ambiguous'.
+    CREATE TABLE IF NOT EXISTS unresolved_links (
+      source_path TEXT NOT NULL,
+      raw_target TEXT NOT NULL,
+      reason TEXT NOT NULL,
+      context_snippet TEXT,
+      PRIMARY KEY (source_path, raw_target)
+    );
+
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    );
+  `);
+
+  // ---- sqlite-vec: KNN-capable mirror of `chunks.embedding` ----
+  //
+  // `vec_chunks.rowid` == `chunks.id`, so JOINs are cheap and dedup-by-path
+  // still uses the chunks table. We store cosine-distance vectors because
+  // the legacy `vectorSearch` used JS-side cosineSimilarity; switching the
+  // metric here would change ranking semantics. Dimension comes from the
+  // embedding config — must match what TEI returns or the INSERT fails.
+  //
+  // If the runtime SQLite has no extension support (no homebrew sqlite, or
+  // OMIT_LOAD_EXTENSION compiled in), we skip the virtual table entirely
+  // and search.ts falls back to the brute-force path. That keeps the plugin
+  // usable on machines that haven't installed a non-stripped libsqlite3.
+  if (runtime.available && config.embedding) {
+    try {
+      sqliteVec.load(db);
+      const dim = config.embedding.dimensions;
+      // Writer-only: if an existing vec_chunks was created at a different
+      // dimension (embedder swapped), DROP it first — IF NOT EXISTS would
+      // otherwise keep the old width and every INSERT fails (see
+      // OpenDatabaseOptions.migrateVecDimension). Must run with sqlite-vec
+      // loaded: DROP TABLE on a vec0 virtual table needs the module resolvable
+      // (a plain sqlite3 CLI without the extension errors "no such module:
+      // vec0"), which is exactly why this lives in code, not a CLI one-liner.
+      if (options.migrateVecDimension && dropVecChunksIfDimensionMismatch(db, dim)) {
+        process.stderr.write(
+          `[iapeer-memory] vec_chunks dimension changed → float[${dim}]; dropped stale table, ` +
+            `re-embed will repopulate it\n`,
+        );
+      }
+      db.exec(
+        `CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}] distance_metric=cosine)`,
+      );
+      db.vecAvailable = true;
+    } catch (err) {
+      // Best effort — degraded BM25-only path still works.
+      // Logging goes through callers' own loggers (we don't take a logger here
+      // to keep openDatabase signature stable for callers/tests).
+      process.stderr.write(
+        `[iapeer-memory] sqlite-vec load failed: ${String(err)} — vector search falls back to brute-force\n`,
+      );
+    }
+  }
+
+  return db;
+}
+
+/**
+ * Dimension a `vec_chunks` table was created with, parsed from its stored
+ * CREATE statement (`...float[N]...`) in sqlite_master. Returns null if the
+ * table doesn't exist or the width can't be parsed. The reflected table
+ * definition is the source of truth — the dimension is deliberately NOT tracked
+ * in `meta` as well, so it can never drift from the actual column width.
+ */
+export function vecChunksDimension(db: Database): number | null {
+  const row = db
+    .prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='vec_chunks'")
+    .get() as { sql?: string } | null;
+  if (!row?.sql) return null;
+  const m = row.sql.match(/float\[(\d+)\]/);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * DROP `vec_chunks` when its on-disk dimension differs from `dim`. vec0 tables
+ * carry shadow tables (`vec_chunks_chunks`, `vec_chunks_rowids`, …); DROP TABLE
+ * on the virtual table cascades to them via vec0's xDestroy, so this is a
+ * complete reset. Caller MUST have `sqliteVec.load(db)`'d first (DROP needs the
+ * vec0 module resolvable). Returns true iff a stale table was dropped; no-op
+ * (returns false) when the dimension already matches or the table is absent.
+ */
+function dropVecChunksIfDimensionMismatch(db: CoreDb, dim: number): boolean {
+  const existing = vecChunksDimension(db);
+  if (existing !== null && existing !== dim) {
+    db.exec("DROP TABLE IF EXISTS vec_chunks");
+    return true;
+  }
+  return false;
+}
+
+export function getMeta(db: CoreDb, key: string): string | null {
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value?: string } | null;
+  return row?.value ?? null;
+}
+
+export function setMeta(db: CoreDb, key: string, value: string): void {
+  db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+
+/**
+ * Check if embedding model changed since last indexation.
+ * If changed — clear all embeddings and update stored model info.
+ * Returns true if embeddings were invalidated.
+ */
+export function checkEmbeddingModelChanged(db: CoreDb, config: { model: string; dimensions: number } | null): boolean {
+  if (!config) return false;
+
+  const fingerprint = `${config.model}:${config.dimensions}`;
+  const stored = getMeta(db, "embedding_fingerprint");
+
+  if (stored === fingerprint) return false;
+
+  // Model changed (or first run) — clear all embeddings
+  db.prepare("UPDATE chunks SET embedding = NULL").run();
+  setMeta(db, "embedding_fingerprint", fingerprint);
+
+  return stored !== null; // true = invalidated old embeddings, false = first run
+}
+
+/**
+ * Check if the parser fingerprint changed since last indexation.
+ *
+ * Bumped manually when the chunking algorithm changes in a way that affects
+ * what's stored on disk — e.g. adding a title prefix to chunk[0]. Changing
+ * this version forces the next startup to re-parse every note: we set
+ * content_hash = NULL on all documents, so indexFile's "skip if hash matches"
+ * short-circuit no longer fires and the parser runs on each file.
+ *
+ * Returns true if invalidation occurred (existing index was dropped).
+ */
+export function checkParserChanged(db: CoreDb, version: string): boolean {
+  const stored = getMeta(db, "parser_fingerprint");
+  if (stored === version) return false;
+
+  db.prepare("UPDATE documents SET content_hash = NULL").run();
+  setMeta(db, "parser_fingerprint", version);
+
+  return stored !== null;
+}
+
+export function getStoredHash(db: CoreDb, docPath: string): string | null {
+  const row = db.prepare("SELECT content_hash FROM documents WHERE path = ?").get(docPath) as { content_hash?: string } | null;
+  return row?.content_hash ?? null;
+}
+
+/**
+ * Drop all vec_chunks rows owned by a document. Used when a document is
+ * about to be re-chunked (upsert) or deleted entirely. No-op if vec is not
+ * loaded on this connection.
+ *
+ * vec_chunks is rowid-only — it has no doc_path column — so we join through
+ * `chunks` to find which rowids to delete. This is the only place that
+ * pre-existing chunks.id values are used as a deletion key, so we must
+ * resolve them BEFORE the chunks rows themselves are deleted.
+ */
+function deleteVecChunksByDoc(db: CoreDb, docPath: string): void {
+  if (!db.vecAvailable) return;
+  const rows = db.prepare("SELECT id FROM chunks WHERE doc_path = ?").all(docPath) as Array<{ id: number }>;
+  if (rows.length === 0) return;
+  const stmt = db.prepare("DELETE FROM vec_chunks WHERE rowid = ?");
+  for (const r of rows) stmt.run(r.id);
+}
+
+export function upsertDocument(db: CoreDb, row: IndexedDocumentRow, chunks: { chunkIndex: number; text: string }[], links: { target: string; contextSnippet: string }[]): void {
+  const tx = db.transaction(() => {
+    // vec_chunks rowids referenced by this doc's old chunks must die BEFORE
+    // we delete the chunks rows themselves — once `chunks.id` is gone we
+    // can't recover the rowid mapping.
+    deleteVecChunksByDoc(db, row.path);
+    db.prepare(
+      `INSERT INTO documents (
+        path, title, type, status, tags, content_hash, frontmatter, created, updated, indexed_at
+      ) VALUES (
+        @path, @title, @type, @status, @tags, @contentHash, @frontmatter, @created, @updated, @indexedAt
+      )
+      ON CONFLICT(path) DO UPDATE SET
+        title=excluded.title,
+        type=excluded.type,
+        status=excluded.status,
+        tags=excluded.tags,
+        content_hash=excluded.content_hash,
+        frontmatter=excluded.frontmatter,
+        created=excluded.created,
+        updated=excluded.updated,
+        indexed_at=excluded.indexed_at`
+    ).run({
+      path: row.path,
+      title: row.title,
+      type: row.type,
+      status: row.status,
+      tags: toJson(row.tags),
+      contentHash: row.contentHash,
+      frontmatter: toJson(row.frontmatter),
+      created: row.created,
+      updated: row.updated,
+      indexedAt: row.indexedAt,
+    });
+
+    db.prepare("DELETE FROM chunk_fts WHERE doc_path = ?").run(row.path);
+    db.prepare("DELETE FROM chunks WHERE doc_path = ?").run(row.path);
+    db.prepare("DELETE FROM edges WHERE source_path = ?").run(row.path);
+    db.prepare("DELETE FROM unresolved_links WHERE source_path = ?").run(row.path);
+
+    const insertChunkFts = db.prepare("INSERT INTO chunk_fts (chunk_text, doc_path, chunk_index) VALUES (?, ?, ?)");
+    const insertChunk = db.prepare("INSERT INTO chunks (doc_path, chunk_index, chunk_text) VALUES (?, ?, ?)");
+    for (const chunk of chunks) {
+      insertChunkFts.run(chunk.text, row.path, chunk.chunkIndex);
+      insertChunk.run(row.path, chunk.chunkIndex, chunk.text);
+    }
+
+    const insertEdge = db.prepare("INSERT OR IGNORE INTO edges (source_path, target_path, context_snippet) VALUES (?, ?, ?)");
+    for (const link of links) {
+      insertEdge.run(row.path, link.target, link.contextSnippet);
+    }
+  });
+
+  tx();
+}
+
+export function deleteMissingDocuments(db: CoreDb, existingPaths: Set<string>): number {
+  const rows = db.prepare("SELECT path FROM documents").all() as Array<{ path: string }>;
+  const stale = rows.map((row) => row.path).filter((docPath) => !existingPaths.has(docPath));
+  if (stale.length === 0) return 0;
+
+  const tx = db.transaction(() => {
+    const deleteDoc = db.prepare("DELETE FROM documents WHERE path = ?");
+    const deleteFts = db.prepare("DELETE FROM chunk_fts WHERE doc_path = ?");
+    const deleteOutgoing = db.prepare("DELETE FROM edges WHERE source_path = ?");
+    const deleteIncoming = db.prepare("DELETE FROM edges WHERE target_path = ?");
+    const deleteUnresolved = db.prepare("DELETE FROM unresolved_links WHERE source_path = ?");
+    const deleteChunks = db.prepare("DELETE FROM chunks WHERE doc_path = ?");
+    for (const docPath of stale) {
+      // vec_chunks first — drops the rowids before the chunks rows that own them go away.
+      deleteVecChunksByDoc(db, docPath);
+      deleteDoc.run(docPath);
+      deleteFts.run(docPath);
+      deleteOutgoing.run(docPath);
+      deleteIncoming.run(docPath);
+      deleteUnresolved.run(docPath);
+      deleteChunks.run(docPath);
+    }
+  });
+
+  tx();
+  return stale.length;
+}
+
+export function searchDocuments(db: CoreDb, params: { query: string; limit: number }): SearchRow[] {
+  const stmt = db.prepare(`
+    SELECT
+      d.path as path,
+      d.title as title,
+      rank as score,
+      snippet(chunk_fts, 0, '[', ']', ' … ', 18) as snippet
+    FROM chunk_fts
+    JOIN documents d ON d.path = chunk_fts.doc_path
+    WHERE chunk_fts MATCH ?
+    ORDER BY rank ASC
+    LIMIT ?
+  `);
+
+  // FTS5 rank is per-row, not per-document. We deduplicate by path, keeping the best score.
+  const rows = stmt.all(params.query, params.limit * 3) as SearchRow[];
+  const seen = new Map<string, SearchRow>();
+  for (const row of rows) {
+    const existing = seen.get(row.path);
+    if (!existing || row.score < existing.score) {
+      seen.set(row.path, row);
+    }
+  }
+  return [...seen.values()]
+    .sort((a, b) => a.score - b.score)
+    .slice(0, params.limit);
+}
+
+export function getDocumentMeta(db: CoreDb, docPath: string): {
+  path: string;
+  title: string;
+  type: string | null;
+  status: string | null;
+  tags: string[];
+  frontmatter: Record<string, unknown>;
+  created: string | null;
+  updated: string | null;
+} | null {
+  const row = db.prepare(`SELECT path, title, type, status, tags, frontmatter, created, updated FROM documents WHERE path = ?`).get(docPath) as Record<string, unknown> | null;
+  if (!row) return null;
+  return {
+    path: String(row.path),
+    title: String(row.title ?? ""),
+    type: (row.type as string | null) ?? null,
+    status: (row.status as string | null) ?? null,
+    tags: fromJson<string[]>(typeof row.tags === "string" ? row.tags : null, []),
+    frontmatter: fromJson<Record<string, unknown>>(typeof row.frontmatter === "string" ? row.frontmatter : null, {}),
+    created: (row.created as string | null) ?? null,
+    updated: (row.updated as string | null) ?? null,
+  };
+}
+
+export function getRelatedPaths(db: CoreDb, docPath: string, limit = 5): string[] {
+  const rows = db.prepare(`
+    SELECT target_path as path FROM edges WHERE source_path = ?
+    UNION
+    SELECT source_path as path FROM edges WHERE target_path = ?
+    LIMIT ?
+  `).all(docPath, docPath, limit) as Array<{ path: string }>;
+  return rows.map((row) => row.path);
+}
+
+export function getChunkTexts(db: CoreDb, docPath: string): string[] {
+  const rows = db.prepare("SELECT chunk_text FROM chunks WHERE doc_path = ? ORDER BY chunk_index").all(docPath) as Array<{ chunk_text: string }>;
+  return rows.map((r) => r.chunk_text);
+}
+
+export function getChunksWithoutEmbeddings(db: CoreDb, limit: number): Array<{ id: number; docPath: string; chunkText: string }> {
+  return db.prepare(
+    "SELECT id, doc_path as docPath, chunk_text as chunkText FROM chunks WHERE embedding IS NULL LIMIT ?"
+  ).all(limit) as Array<{ id: number; docPath: string; chunkText: string }>;
+}
+
+export function storeChunkEmbeddings(db: CoreDb, updates: Array<{ id: number; embedding: Buffer }>): void {
+  const stmt = db.prepare("UPDATE chunks SET embedding = ? WHERE id = ?");
+  // vec_chunks mirrors the same buffer keyed by rowid == chunks.id. INSERT OR
+  // REPLACE because on re-index the chunks row gets a new id but a deleted
+  // doc may briefly reuse one — REPLACE keeps the vec table consistent
+  // without needing a separate "is this a new id?" check.
+  const vecStmt = db.vecAvailable
+    ? db.prepare("INSERT OR REPLACE INTO vec_chunks(rowid, embedding) VALUES (?, ?)")
+    : null;
+  const tx = db.transaction(() => {
+    for (const u of updates) {
+      stmt.run(u.embedding, u.id);
+      if (vecStmt) vecStmt.run(u.id, u.embedding);
+    }
+  });
+  tx();
+}
+
+/**
+ * Backfill `vec_chunks` from `chunks.embedding` BLOBs. Called once at writer
+ * startup when vec is available: existing DBs predate vec_chunks and have all
+ * their embeddings only in the legacy column. After this pass vec_chunks
+ * mirrors chunks and stays in sync via storeChunkEmbeddings / upsertDocument
+ * / deleteMissingDocuments.
+ *
+ * Idempotent: if vec_chunks already covers every chunk, the streaming pass
+ * just produces zero work via INSERT OR REPLACE. Streams in batches to keep
+ * heap bounded — full vault has ~1500 chunks × 16KB embedding = ~24 MB.
+ */
+export function backfillVecChunks(db: CoreDb, batchSize = 200): number {
+  if (!db.vecAvailable) return 0;
+  // Only chunks NOT already in vec_chunks. NOT EXISTS lets sqlite skip the
+  // join when vec_chunks is fully populated.
+  const selectMissing = db.prepare(
+    `SELECT c.id, c.embedding
+     FROM chunks c
+     WHERE c.embedding IS NOT NULL
+       AND NOT EXISTS (SELECT 1 FROM vec_chunks v WHERE v.rowid = c.id)
+     LIMIT ?`,
+  );
+  const insert = db.prepare(
+    "INSERT OR REPLACE INTO vec_chunks(rowid, embedding) VALUES (?, ?)",
+  );
+  let total = 0;
+  while (true) {
+    const rows = selectMissing.all(batchSize) as Array<{ id: number; embedding: Buffer }>;
+    if (rows.length === 0) break;
+    const tx = db.transaction(() => {
+      for (const r of rows) insert.run(r.id, r.embedding);
+    });
+    tx();
+    total += rows.length;
+    if (rows.length < batchSize) break;
+  }
+  return total;
+}
+
+export function getBacklinks(db: CoreDb, docPath: string): Array<{ path: string; contextSnippet: string | null }> {
+  return db.prepare(`SELECT source_path as path, context_snippet as contextSnippet FROM edges WHERE target_path = ? ORDER BY source_path ASC`).all(docPath) as Array<{ path: string; contextSnippet: string | null }>;
+}
+
+export function documentExists(db: CoreDb, docPath: string): boolean {
+  return db.prepare("SELECT 1 FROM documents WHERE path = ? LIMIT 1").get(docPath) != null;
+}
+
+/**
+ * Unresolved wikilinks (missing target / ambiguous basename across folders).
+ * First-class health signal — surfaced through vault_map's opt-in
+ * `orphan_wikilinks` part and the Index nightly health-check.
+ */
+export function getUnresolvedLinks(
+  db: CoreDb,
+): Array<{ source: string; target: string; reason: string }> {
+  return db
+    .prepare(
+      "SELECT source_path as source, raw_target as target, reason FROM unresolved_links ORDER BY source_path ASC, raw_target ASC",
+    )
+    .all() as Array<{ source: string; target: string; reason: string }>;
+}