trajectories 0.0.0 → 0.1.2

package/legacy/src/reader.ts

@@ -0,0 +1,1255 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { Database } from "bun:sqlite";
+import { readDiscoverySummary, readSourceCoverageSummary, type SourceCoverageSummary } from "./db.js";
+import type { DiscoverySummary } from "./discovery.js";
+import { SemanticTopK } from "./semantic-top-k.js";
+import {
+  cosineSimilarity,
+  deserializeEmbedding,
+  embed,
+  getEmbeddingProvider,
+  type EmbeddingProvider,
+} from "./embeddings.js";
+import type { GeminiEmbeddingProvider } from "./gemini_embeddings.js";
+import { SCHEMA_VERSION } from "./schema.js";
+import { classifyReadStore, formatMismatchMessage, incompleteStoreMessage } from "./schema-gate.js";
+import type {
+  CanonicalDbRecord,
+  QueryResult,
+  RecordMatchType,
+  RecordSearchHit,
+  SearchHit,
+  SearchMode,
+  SessionRecord,
+  TitleSearchHit,
+  WideningReport,
+  WideningSkipReason,
+} from "./types.js";
+
+/**
+ * The read path of one store, against any connection handle.
+ *
+ * Everything here is pure query work: it never initializes, migrates, repairs a
+ * trigger, configures FTS, or writes an embedding. `TrajectoryReader` owns the
+ * read-only connection lifecycle; `TrajectoryDb` reuses the same functions for
+ * the read methods its writer handle already offers, so lexical widening,
+ * envelope accounting, match provenance, and fusion cannot drift between the
+ * two.
+ */
+
+// Zero-hit lexical widening. Every gate below runs only after the primary query
+// returned nothing, so widening never touches the cost or the output of a
+// normal search. LEDGER_WIDEN_MAX_RECORDS=0 disables widening outright.
+//
+// The default is the bound schema v11's rebuilt FTS index earns: the production
+// store (156,801 records) sat above the old 10,000-record ceiling, so every
+// zero-hit query there refused widening as `corpus_over_ceiling`. 250,000 admits
+// it with room for growth — measured on a copy of that store, widened queries
+// over ordinary term pairs ran in 19-106 ms after the rebuild where the pre-v11
+// index measured 178-890 ms, with identical hits (both load-dependent; a warmer,
+// loaded run measured 16-40 ms: docs/research/2026-09-13-fts-rebuild.md). The
+// threshold is a record count, not a measured latency, so a store still at v10 —
+// its index has not been rebuilt — widens on the old, slower plan until a writer
+// open migrates it, and a widened query whose terms match a large share of the
+// store stays expensive either way.
+const DEFAULT_WIDEN_MAX_RECORDS = 250_000;
+const MAX_WIDEN_TOKEN_CHARS = 16;
+const MIN_WIDEN_TOKEN_ALNUM = 3;
+const MAX_WIDEN_TOKENS = 16;
+const BOOLEAN_OPERATOR_RE = /\b(AND|OR|NOT|NEAR)\b/i;
+export const FTS_SYNTAX_FALLBACK_REASON = "fts_syntax_error";
+/**
+ * Reported when a semantic or hybrid query had no vectors to search: either the
+ * store holds no compatible embeddings (a read path never backfills) or the
+ * active provider could not embed the query text.
+ */
+export const EMBEDDINGS_UNAVAILABLE_REASON = "embeddings_unavailable";
+
+/**
+ * The recency prior both lexical lanes order by. bm25 is negative and smaller
+ * means more relevant, so multiplying it by `1 + 1/(1 + age/H)` makes a newer
+ * session's hits "more negative": a session from today is ×2, one 30 days old
+ * ×1.5, one a year old ×1.08. Equal-relevance hits go to the newer session; a
+ * hit whose text relevance is more than the factor apart still wins on text.
+ * Wake multiplies its message lane and its title lane by exactly this
+ * (`crates/wake-core/src/db.rs#L1546-L1560`, tag v0.6.5, MIT), keyed on the
+ * *session's* timestamp rather than the record's, so the relative order of hits
+ * within one session is untouched — which is why Ledger's prior can read
+ * `started_at` and leave the lanes' `started_at DESC` tiebreak alone.
+ *
+ * Arithmetic, `max()` and one core date function only — no math extension — and
+ * one term in a lane's ORDER BY: no rescore pass. `unixepoch()` is the one way
+ * to an epoch from this store's ISO-8601 timestamps (no numeric time column
+ * exists), and it is a core function of the engine these queries run on —
+ * Bun's bundled SQLite 3.51.0, the same runtime C5 verified its SQLite feature
+ * set against. `COALESCE(…, 0)` puts an absent or unparsable timestamp at the
+ * epoch, the factor's neutral end (×1.0), where a NULL would sort such a hit
+ * first in both lanes. The clock is the caller's `Date.now()`, bound as the `?`
+ * Wake binds (`now_ms()`), evaluated once per query rather than once per
+ * matched row. H is spelled as a real (`${RECENCY_DECAY_MS}.0`), running text
+ * and all: SQLite divides integers with integer division, and a truncated
+ * divisor would silently make the factor ×2 for the whole corpus.
+ *
+ * `started_at` is the key, not `updated_at`: the latter is the ingest write
+ * time (`ingest.ts` stamps `new Date()`), so a backfilled store would read every
+ * ancient session as "today" (measured — all 2,613 sessions of the production
+ * store are stamped within four days). `ended_at`, the content analog of Wake's
+ * `updated_at`, moves the recency bucket of 5 of those 2,613 sessions, and the
+ * tiebreak already names the start; one timestamp per lane.
+ */
+const RECENCY_DECAY_MS = 2_592_000_000;
+const RECENCY_PRIOR_SQL =
+  `(1.0 + 1.0 / (1.0 + max(0, ? - COALESCE(unixepoch(s.started_at) * 1000, 0)) / ${RECENCY_DECAY_MS}.0))`;
+
+const COUNT_REASON_LIMIT_BOUNDED = "limit_bounded";
+const COUNT_REASON_EXACT = "all_matches_returned";
+const COUNT_REASON_EMPTY_QUERY = "empty_query";
+
+/**
+ * The tombstone filter every serving query carries: a session the user deleted
+ * is not served, whichever lane would have found it. Reads are where a deletion
+ * becomes visible — the store does not remove the rows a `suppress` tombstone
+ * covers (db.ts) — so the filter is one predicate applied to the session column
+ * of each lane rather than a rewrite of any lane.
+ *
+ * The predicate is resolved per call, and skipping it for a store that has no
+ * `session_tombstones` table is exact rather than defensive: a store without the
+ * table is one no build could have written a tombstone into. The table arrives
+ * with the migration that introduces the verb (db.ts, `migrate`), and a store
+ * written by this build is refused outright by an older build's read gate
+ * (`classifyReadStore`, user_version newer than supported), so a tombstoned
+ * store is never read unfiltered. Skipping the predicate there is the same
+ * answer as applying it to an empty set — and it is what lets this build keep
+ * serving a store written before the table existed, the same tolerance the title
+ * lane shows for a store whose format-`"3"` derivation has not run yet. The
+ * cost is one `sqlite_master` lookup per serving call; `1` keeps a caller that
+ * splices the predicate into an existing `AND` chain from having to branch.
+ */
+function tombstonePredicate(db: Database, sessionColumn: string): string {
+  const present = !!db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_tombstones' LIMIT 1;",
+    )
+    .get();
+  return present
+    ? `NOT EXISTS (SELECT 1 FROM session_tombstones t WHERE t.session_id = ${sessionColumn})`
+    : "1";
+}
+
+/** Options shared by every read query. */
+export interface ReadQueryOptions {
+  limit?: number;
+  source?: string;
+}
+
+/**
+ * Widening ceiling, read per query so operators and tests can flip it without
+ * restarting a long-lived process. Only a plain non-negative integer counts;
+ * anything else (empty, negative, `2.9`, `0x10`, `10k`, `1e3`) falls back to
+ * the default, and 0 disables widening.
+ */
+function readWidenMaxRecords(): number {
+  const raw = process.env.LEDGER_WIDEN_MAX_RECORDS?.trim();
+  if (raw === undefined || !/^\d+$/.test(raw)) return DEFAULT_WIDEN_MAX_RECORDS;
+  return Number.parseInt(raw, 10);
+}
+
+function alphanumericCount(token: string): number {
+  let count = 0;
+  for (const ch of token) {
+    if (/[A-Za-z0-9]/.test(ch)) count += 1;
+  }
+  return count;
+}
+
+/**
+ * Tokens that may become prefix terms. Over-long tokens are dropped and the
+ * query widens with the remainder; tokens holding fewer than three
+ * alphanumerics are dropped too, because a quoted zero-token phrase followed by
+ * `*` is not a no-op in FTS5 (it can match unrelated records). Duplicates
+ * collapse case-insensitively before the cap is applied.
+ */
+function widenableTokens(cleanQuery: string): string[] | { skipReason: WideningSkipReason } {
+  const sized = cleanQuery.split(/\s+/).filter((t) => t.length <= MAX_WIDEN_TOKEN_CHARS);
+  if (sized.length === 0) return { skipReason: "token_too_long" };
+  const rich = sized.filter((t) => alphanumericCount(t) >= MIN_WIDEN_TOKEN_ALNUM);
+  if (rich.length === 0) return { skipReason: "no_widenable_tokens" };
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const token of rich) {
+    const key = token.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(token);
+  }
+  if (unique.length > MAX_WIDEN_TOKENS) return { skipReason: "query_too_long" };
+  return unique;
+}
+
+/** Engine output before the envelope is attached. */
+interface RawFtsHits {
+  hits: RecordSearchHit[];
+}
+
+/**
+ * What the store *holds*, tombstones included — deliberately not what it
+ * serves. A `suppress` deletion keeps the session's rows (db.ts), so a count
+ * that subtracted them would claim the store holds less than it does and hide
+ * the very data the audit keeps; the deletion is disclosed beside these numbers
+ * instead (`ledger status`: `tombstones` and `tombstoned_records`). The other
+ * reader of this count is the widening ceiling, which bounds a query by the
+ * corpus it would scan rather than by the rows it may return.
+ */
+export function countSessions(db: Database): number {
+  const row = db.query<{ count: number }, []>("SELECT COUNT(*) AS count FROM sessions").get();
+  return row?.count ?? 0;
+}
+
+/**
+ * Whether the store holds any record at all. `EXISTS` stops at the first row
+ * (an index seek); counting instead would scan the table on every semantic or
+ * hybrid query just to answer a yes/no question.
+ */
+function hasRecords(db: Database, source?: string): boolean {
+  return !!db.query<{ present: number }, (string | number)[]>(
+    `SELECT EXISTS(SELECT 1 FROM records r JOIN sessions s ON s.id = r.session_id${source ? " WHERE s.source = ?" : ""}) AS present`,
+  ).get(...(source ? [source] : []))?.present;
+}
+
+/** Records held, tombstones included: the same holdings rule as `countSessions`. */
+export function countRecords(db: Database): number {
+  const row = db.query<{ count: number }, []>("SELECT COUNT(*) AS count FROM records").get();
+  return row?.count ?? 0;
+}
+
+/**
+ * Vectors the active provider can actually score. Embeddings written by another
+ * provider or dimension are invisible to a semantic query rather than being
+ * compared across incompatible spaces.
+ */
+export function compatibleEmbeddingCount(db: Database, source?: string): number {
+  const provider = getEmbeddingProvider();
+  return db.query<{ count: number }, (string | number)[]>(
+    `SELECT COUNT(*) AS count FROM records_embeddings e
+     JOIN records r ON r.id = e.record_id
+     JOIN sessions s ON s.id = e.session_id
+     WHERE e.provider = ? AND e.dim = ?${source ? " AND s.source = ?" : ""}`,
+  ).get(provider.name, provider.dimension, ...(source ? [source] : []))?.count ?? 0;
+}
+
+function buildFtsExpression(query: string): string {
+  // If the user already provided quotes, respect them
+  if (query.startsWith('"') && query.endsWith('"')) {
+    return query;
+  }
+  // Check if query has multiple words without boolean operators
+  const hasOperators = BOOLEAN_OPERATOR_RE.test(query);
+  if (!hasOperators && query.includes(" ")) {
+    // Match phrase or conjunct
+    const escaped = query.replace(/"/g, '""');
+    return `"${escaped}"`;
+  }
+  return query;
+}
+
+/**
+ * The escaped-term rewrite of a query whose own expression FTS5 rejected:
+ * every whitespace token as a quoted term, so punctuation cannot be read as
+ * syntax. Both lanes call this one implementation because they are handed the
+ * same expression — a query the fallback can still answer must keep whatever
+ * its titles matched, so the rewrite cannot drift between the two.
+ */
+function escapedTermExpression(cleanQuery: string): string {
+  return cleanQuery
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((t) => `"${t.replace(/"/g, '""')}"`)
+    .join(" ");
+}
+
+function executeFtsQuery(
+  db: Database,
+  ftsExpr: string,
+  limit: number,
+  now: number,
+  sourceFilter?: string,
+  matchType: RecordMatchType = "lexical",
+): RawFtsHits {
+  const sourceClause = sourceFilter ? "AND s.source = ?" : "";
+  // Parameter order follows the SQL text, and the recency prior's `?` sits in
+  // the SELECT list — ahead of the MATCH expression, the source filter and the
+  // limit.
+  const params: (string | number)[] = sourceFilter
+    ? [now, ftsExpr, sourceFilter, limit]
+    : [now, ftsExpr, limit];
+
+  const sql = `
+    SELECT
+      f.record_id,
+      f.session_id,
+      s.source,
+      s.title,
+      s.cwd,
+      s.started_at,
+      s.parent_session_id,
+      s.agent_nickname,
+      s.thread_role,
+      f.record_type,
+      f.content,
+      f.tool_name,
+      f.tool_arguments,
+      f.tool_result,
+      snippet(records_fts, 4, '«', '»', '...', 20) AS content_snippet,
+      snippet(records_fts, 6, '«', '»', '...', 20) AS args_snippet,
+      snippet(records_fts, 7, '«', '»', '...', 20) AS res_snippet,
+      bm25(records_fts) * ${RECENCY_PRIOR_SQL} AS rank
+    FROM records_fts f
+    JOIN sessions s ON s.id = f.session_id
+    WHERE records_fts MATCH ?
+    ${sourceClause}
+      AND ${tombstonePredicate(db, "s.id")}
+    ORDER BY rank ASC, s.started_at DESC
+    LIMIT ?
+  `;
+
+  interface RawHit {
+    record_id: string;
+    session_id: string;
+    source: string;
+    title: string | null;
+    cwd: string | null;
+    started_at: string | null;
+    parent_session_id: string | null;
+    agent_nickname: string | null;
+    thread_role: string | null;
+    record_type: string;
+    content: string | null;
+    tool_name: string | null;
+    tool_arguments: string | null;
+    tool_result: string | null;
+    content_snippet: string;
+    args_snippet: string;
+    res_snippet: string;
+    rank: number;
+  }
+
+  const rows = db.query<RawHit, (string | number)[]>(sql).all(...params);
+
+  const hits: RecordSearchHit[] = [];
+
+  for (const r of rows) {
+    let snippet = r.content_snippet;
+    if (!snippet || !snippet.includes("«")) {
+      if (r.args_snippet && r.args_snippet.includes("«")) {
+        snippet = r.args_snippet;
+      } else if (r.res_snippet && r.res_snippet.includes("«")) {
+        snippet = r.res_snippet;
+      } else {
+        snippet = (r.content ?? r.tool_arguments ?? r.tool_result ?? "").slice(0, 200);
+      }
+    }
+
+    hits.push({
+      session_id: r.session_id,
+      record_id: r.record_id,
+      source: r.source,
+      title: r.title,
+      cwd: r.cwd,
+      started_at: r.started_at,
+      record_type: r.record_type,
+      parent_session_id: r.parent_session_id,
+      agent_nickname: r.agent_nickname,
+      thread_role: r.thread_role,
+      content: r.content,
+      tool_name: r.tool_name,
+      tool_arguments: r.tool_arguments,
+      tool_result: r.tool_result,
+      snippet,
+      rank: r.rank,
+      match_type: matchType,
+    });
+  }
+
+  return { hits };
+}
+
+/**
+ * Prefix-OR widening for a lexical query that returned nothing. Gates: the
+ * query must not express phrase intent anywhere, must not use boolean
+ * operators or its own wildcard, must leave at least one widenable token, and
+ * the corpus must sit under the configured ceiling. Adoption requires
+ * strictly more hits than the primary query's zero.
+ */
+function widenZeroHitQuery(
+  db: Database,
+  cleanQuery: string,
+  limit: number,
+  now: number,
+  sourceFilter?: string,
+): RawFtsHits | { skipReason: WideningSkipReason } {
+  const maxRecords = readWidenMaxRecords();
+  if (maxRecords === 0) return { skipReason: "disabled" };
+  // Any quote, not just a wrapping pair: `check "a b" field` is phrase intent.
+  if (cleanQuery.includes('"')) return { skipReason: "quoted_input" };
+  if (BOOLEAN_OPERATOR_RE.test(cleanQuery)) return { skipReason: "operators_present" };
+  if (cleanQuery.includes("*")) return { skipReason: "wildcard_present" };
+
+  const tokens = widenableTokens(cleanQuery);
+  if (!Array.isArray(tokens)) return tokens;
+  // The ceiling counts every record in the store, not only those matching
+  // `--source`, so a filtered search cannot dodge the corpus-size guard.
+  if (countRecords(db) > maxRecords) return { skipReason: "corpus_over_ceiling" };
+
+  // Quoted phrase-prefix terms: equivalent to `tok*` for plain words and
+  // safe for terms whose punctuation would otherwise be read as FTS5 syntax.
+  const widenedExpr = `(${tokens.map((t) => `"${t.replace(/"/g, '""')}"*`).join(" OR ")})`;
+  let widened: RawFtsHits;
+  try {
+    widened = executeFtsQuery(db, widenedExpr, limit, now, sourceFilter, "implicit_wildcard");
+  } catch {
+    // Defensive: the token gates make an unparsable widening expression
+    // unreachable today, and the catch keeps a future change from turning
+    // that into a thrown query.
+    return { skipReason: "widened_query_failed" };
+  }
+  return widened.hits.length > 0 ? widened : { skipReason: "no_improvement" };
+}
+
+/**
+ * The title lane: one hit per session whose title matches, best first. The
+ * title is a session's own metadata, so a hit here names the session and no
+ * record (see `TitleSearchHit`).
+ *
+ * Ordered by relevance under the same recency prior the record lane applies —
+ * `bm25(titles_fts) × (1 + 1/(1 + age/H))`, then `s.started_at DESC` — which is
+ * Wake's ordering for the same lane (`crates/wake-core/src/db.rs#L1676-L1700`)
+ * and the same term the record lane's `rank` carries.
+ */
+function titlePrepass(
+  db: Database,
+  ftsExpr: string,
+  limit: number,
+  now: number,
+  sourceFilter?: string,
+): TitleSearchHit[] {
+  const sourceClause = sourceFilter ? "AND s.source = ?" : "";
+  const params: (string | number)[] = sourceFilter
+    ? [now, ftsExpr, sourceFilter, limit]
+    : [now, ftsExpr, limit];
+
+  const sql = `
+    SELECT
+      f.session_id,
+      s.source,
+      s.title,
+      s.cwd,
+      s.started_at,
+      s.parent_session_id,
+      s.agent_nickname,
+      s.thread_role,
+      highlight(titles_fts, 1, '«', '»') AS title_snippet,
+      bm25(titles_fts) * ${RECENCY_PRIOR_SQL} AS rank
+    FROM titles_fts f
+    JOIN sessions s ON s.id = f.session_id
+    WHERE titles_fts MATCH ?
+    ${sourceClause}
+      AND ${tombstonePredicate(db, "s.id")}
+    ORDER BY rank ASC, s.started_at DESC
+    LIMIT ?
+  `;
+
+  interface TitleRow {
+    session_id: string;
+    source: string;
+    title: string;
+    cwd: string | null;
+    started_at: string | null;
+    parent_session_id: string | null;
+    agent_nickname: string | null;
+    thread_role: string | null;
+    title_snippet: string;
+    rank: number;
+  }
+
+  // The whole title is the snippet — it is short by construction (the
+  // normalizer cuts a first-user-message title at 120 chars) and truncating it
+  // to a window around the match would hide the session's own name from the
+  // answer that matched it.
+  return db
+    .query<TitleRow, (string | number)[]>(sql)
+    .all(...params)
+    .map((row) => ({
+      session_id: row.session_id,
+      record_id: null,
+      source: row.source,
+      title: row.title,
+      cwd: row.cwd,
+      started_at: row.started_at,
+      record_type: "title",
+      content: null,
+      tool_name: null,
+      tool_arguments: null,
+      tool_result: null,
+      snippet: row.title_snippet.slice(0, 240),
+      rank: row.rank,
+      parent_session_id: row.parent_session_id,
+      agent_nickname: row.agent_nickname,
+      thread_role: row.thread_role,
+      match_type: "title",
+    }));
+}
+
+function buildQueryResult(
+  query: string,
+  hits: SearchHit[],
+  mode: SearchMode,
+  limit: number,
+  startedAt: number,
+  extras: {
+    fallbackReason?: string | null;
+    widened?: WideningReport | null;
+    countReason?: string;
+    /** The mode the caller asked for when `mode` is the engine that answered. */
+    requestedMode?: SearchMode;
+  } = {},
+): QueryResult {
+  const bounded = hits.length >= limit;
+  const sessions = new Set<string>();
+  for (const hit of hits) sessions.add(hit.session_id);
+  return {
+    query,
+    totalHits: hits.length,
+    sessionsCount: sessions.size,
+    hits,
+    meta: {
+      count_precision: bounded ? "lower_bound" : "exact",
+      count_reason: extras.countReason ?? (bounded ? COUNT_REASON_LIMIT_BOUNDED : COUNT_REASON_EXACT),
+      elapsed_ms: Math.round((performance.now() - startedAt) * 1000) / 1000,
+      search_mode: mode,
+      // Equal except when an engine fell back, which is exactly when an agent
+      // must not have to infer which one answered the query.
+      requested_search_mode: extras.requestedMode ?? mode,
+      fallback_reason: extras.fallbackReason ?? null,
+      widened: extras.widened ?? null,
+    },
+  };
+}
+
+export function queryLexical(
+  db: Database,
+  queryText: string,
+  options: ReadQueryOptions = {},
+): QueryResult {
+  const startedAt = performance.now();
+  const limit = options.limit ?? 50;
+  const cleanQuery = queryText.trim();
+  if (!cleanQuery) {
+    return buildQueryResult(queryText, [], "lexical", limit, startedAt, {
+      countReason: COUNT_REASON_EMPTY_QUERY,
+    });
+  }
+
+  const ftsExpr = buildFtsExpression(cleanQuery);
+
+  // One clock for both lanes: the recency prior weights a title hit and a
+  // record hit of the same session identically, and a query cannot read two
+  // different "now"s (Wake's `now_ms()`, `db.rs#L1553`).
+  const now = Date.now();
+
+  // The title lane runs first and its hits are emitted ahead of the record
+  // lane's: a word in a session's title is the strongest relevance signal a
+  // session-level search has, and the session's *name* is what a human is
+  // usually quoting (Wake orders the same way, db.rs#L1676-L1700). It costs
+  // nothing when the store has no title index — a store whose format-`"3"`
+  // derivation has not run yet — and a title that cannot be read must not turn
+  // a query the record lane can still answer into a thrown one.
+  const titlesIndexed = !!db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'titles_fts' LIMIT 1;",
+    )
+    .get();
+  const titleLane = (expr: string): TitleSearchHit[] => {
+    if (!titlesIndexed) return [];
+    try {
+      return titlePrepass(db, expr, limit, now, options.source);
+    } catch {
+      // The record lane decides whether this expression parses; whatever its
+      // answer is, the title lane gets no vote.
+      return [];
+    }
+  };
+
+  let titles = titleLane(ftsExpr);
+
+  // The result as a whole is bounded by the limit, so the title hits come out
+  // of the record lane's budget rather than on top of it: `totalHits` has to
+  // stay what `meta.count_precision` describes.
+  let raw: RawFtsHits;
+  let fallbackReason: string | null = null;
+  if (titles.length >= limit) {
+    raw = { hits: [] };
+  } else {
+    try {
+      raw = executeFtsQuery(db, ftsExpr, limit - titles.length, now, options.source);
+    } catch {
+      // Fallback: search with escaped individual terms — and re-ask the title
+      // lane with them, so both lanes answer one query rather than two.
+      fallbackReason = FTS_SYNTAX_FALLBACK_REASON;
+      const fallbackExpr = escapedTermExpression(cleanQuery);
+      titles = titleLane(fallbackExpr);
+      raw = executeFtsQuery(db, fallbackExpr, limit - titles.length, now, options.source);
+    }
+  }
+
+  let hits: SearchHit[] = [...titles, ...raw.hits];
+
+  // Widening is a zero-hit recovery of the *query*, so it runs only when both
+  // lanes found nothing: it neither costs nor changes anything on the happy
+  // path, which is why the corpus-size probe only runs below.
+  let widened: WideningReport | null = null;
+  if (hits.length === 0) {
+    const attempt = widenZeroHitQuery(db, cleanQuery, limit, now, options.source);
+    if ("hits" in attempt) {
+      hits = attempt.hits;
+      widened = { applied: true, original_hits: 0, widened_hits: attempt.hits.length };
+    } else {
+      widened = { applied: false, skip_reason: attempt.skipReason };
+    }
+  }
+
+  return buildQueryResult(cleanQuery, hits, "lexical", limit, startedAt, {
+    fallbackReason,
+    widened,
+  });
+}
+
+/**
+ * Rewrite a lexical result as the honest answer of a query whose vector leg
+ * could not run: the hits come from the lexical engine, so the envelope says
+ * that, names the mode that was requested, and reports the reason. The lexical
+ * answer includes its title lane — the fallback *is* that engine, so its
+ * session-level hits stay in it.
+ */
+function lexicalFallback(
+  result: QueryResult,
+  limit: number,
+  requested: SearchMode,
+  startedAt: number,
+): QueryResult {
+  const hits = result.hits.slice(0, limit);
+  return buildQueryResult(result.query, hits, "lexical", limit, startedAt, {
+    requestedMode: requested,
+    fallbackReason: EMBEDDINGS_UNAVAILABLE_REASON,
+    widened: result.meta.widened,
+  });
+}
+
+/**
+ * Embed one query string with the given provider. Gemini needs its query-mode
+ * formatting, which is a per-call concern of this path rather than a rewritten
+ * provider: the flag is put back even when embedding fails.
+ */
+async function embedQueryVector(
+  provider: EmbeddingProvider,
+  text: string,
+): Promise<Float32Array | undefined> {
+  const isGemini = "queryMode" in provider;
+  if (isGemini) {
+    (provider as GeminiEmbeddingProvider).queryMode = true;
+  }
+  try {
+    const [vector] = await embed([text]);
+    return vector;
+  } finally {
+    if (isGemini) {
+      (provider as GeminiEmbeddingProvider).queryMode = false;
+    }
+  }
+}
+
+/** The vector leg's answer before the envelope is attached. */
+interface RawVectorHits {
+  hits: RecordSearchHit[];
+}
+
+/**
+ * Vector search over the embeddings already in the store, or null when the leg
+ * cannot run. A read path never backfills: with no compatible vectors, or a
+ * provider that cannot embed the query (no key, no model files, a failing
+ * endpoint), the caller answers lexically and says so instead of returning an
+ * empty result that looks like a miss.
+ */
+async function vectorSearch(
+  db: Database,
+  cleanQuery: string,
+  options: { limit: number; source?: string },
+): Promise<RawVectorHits | null> {
+  const { limit } = options;
+  const provider = getEmbeddingProvider();
+  if (compatibleEmbeddingCount(db, options.source) === 0) return null;
+
+  let queryVec: Float32Array | undefined;
+  try {
+    queryVec = await embedQueryVector(provider, cleanQuery);
+  } catch {
+    return null;
+  }
+  // A provider that hands back a vector of a different length than it
+  // advertises cannot score the stored vectors: every comparison would read as
+  // zero similarity, which is a silent miss rather than an answer.
+  if (!queryVec || queryVec.length !== provider.dimension) return null;
+
+  const conditions: string[] = ["e.provider = ?", "e.dim = ?"];
+  const params: unknown[] = [provider.name, provider.dimension];
+  if (options.source) {
+    conditions.push("s.source = ?");
+    params.push(options.source);
+  }
+  // The vector lane carries the same tombstone filter as the lexical lanes: a
+  // retained vector of a deleted session is not an answer (and a store whose
+  // vectors are all tombstoned answers with no hits in this mode rather than
+  // falling back, so the envelope keeps naming the engine that ran).
+  conditions.push(tombstonePredicate(db, "s.id"));
+  const sourceClause = `WHERE ${conditions.join(" AND ")}`;
+
+  interface EmbeddingRow {
+    record_id: string;
+    session_id: string;
+    source: string;
+    title: string | null;
+    cwd: string | null;
+    started_at: string | null;
+    parent_session_id: string | null;
+    agent_nickname: string | null;
+    thread_role: string | null;
+    record_type: string;
+    content: string | null;
+    tool_name: string | null;
+    tool_arguments_json: string | null;
+    tool_result_json: string | null;
+    embedding: Uint8Array;
+  }
+
+  const sql = `
+    SELECT
+      e.record_id,
+      e.session_id,
+      s.source,
+      s.title,
+      s.cwd,
+      s.started_at,
+      s.parent_session_id,
+      s.agent_nickname,
+      s.thread_role,
+      r.record_type,
+      r.content,
+      r.tool_name,
+      r.tool_arguments_json,
+      r.tool_result_json,
+      e.embedding
+    FROM records_embeddings e
+    JOIN sessions s ON s.id = e.session_id
+    JOIN records r ON r.id = e.record_id
+    ${sourceClause}
+  `;
+
+  // Pure cosine, deliberately: the recency prior is the lexical lanes' (a
+  // multiplier on bm25, above). Cosine is a bounded, dense similarity whose
+  // whole top-50 span measures 1.8–2.6× on this store's own text (shipped
+  // MiniLM, 300 real records: r1/r50 = 2.19/1.77/2.60), so the same ×1–×2
+  // factor would order semantic hits by age nearly regardless of their text;
+  // and a fused hit already takes its recency from the lexical leg's position,
+  // which is what RRF reads. The lane's reported `rank` stays a cosine.
+  //
+  // A deferred snapshot keeps scoring and winner hydration coherent while a
+  // writer commits. Query embedding above awaits outside this transaction.
+  // Exact top-K distinct sessions: one hit per session (its best-scoring
+  // record). Without this, a single long session crowds out the whole top-N
+  // with near-identical records. Space is O(K); scoring remains exhaustive.
+  const topHits = db.transaction(() => {
+    const top = new SemanticTopK(limit);
+    let ordinal = 0;
+    const rows = db.query<{ record_id: string; session_id: string; embedding: Uint8Array }, (string | number)[]>(`
+      SELECT e.record_id, e.session_id, e.embedding
+      FROM records_embeddings e
+      JOIN sessions s ON s.id = e.session_id
+      JOIN records r ON r.id = e.record_id
+      ${sourceClause}
+    `).iterate(...(params as (string | number)[]));
+    for (const row of rows) {
+      const vector = deserializeEmbedding(row.embedding);
+      if (vector.length !== provider.dimension) continue;
+      top.offer({ record_id: row.record_id, session_id: row.session_id,
+        score: cosineSimilarity(queryVec!, vector), ordinal: ordinal++ });
+    }
+    // Only the winning K records bring transcript bodies into memory. Scoring
+    // remains exhaustive O(N * dimension); --limit bounds state, not CPU work.
+    const hydrate = db.query<EmbeddingRow, (string | number)[]>(sql + " AND e.record_id = ?");
+    return top.sorted().map(candidate => {
+      const row = hydrate.get(...(params as (string | number)[]), candidate.record_id);
+      if (!row) throw new Error("Semantic winner disappeared within its read snapshot");
+      return { row, score: candidate.score };
+    });
+  }).deferred();
+  const hits: RecordSearchHit[] = [];
+
+  for (const { row, score } of topHits) {
+    const snippet = (
+      row.content ??
+      row.tool_arguments_json ??
+      row.tool_result_json ??
+      ""
+    ).slice(0, 240);
+    hits.push({
+      session_id: row.session_id,
+      record_id: row.record_id,
+      source: row.source,
+      title: row.title,
+      cwd: row.cwd,
+      started_at: row.started_at,
+      record_type: row.record_type,
+      content: row.content,
+      tool_name: row.tool_name,
+      tool_arguments: row.tool_arguments_json,
+      tool_result: row.tool_result_json,
+      snippet,
+      rank: score,
+      parent_session_id: row.parent_session_id,
+      agent_nickname: row.agent_nickname,
+      thread_role: row.thread_role,
+      match_type: "semantic",
+    });
+  }
+
+  return { hits };
+}
+
+/**
+ * Semantic search: the vector leg when it can run, the lexical engine plus an
+ * `embeddings_unavailable` report when it cannot.
+ */
+export async function querySemantic(
+  db: Database,
+  queryText: string,
+  options: ReadQueryOptions = {},
+): Promise<QueryResult> {
+  const startedAt = performance.now();
+  const limit = options.limit ?? 20;
+  const cleanQuery = queryText.trim();
+  if (!cleanQuery) {
+    return buildQueryResult(queryText, [], "semantic", limit, startedAt, {
+      countReason: COUNT_REASON_EMPTY_QUERY,
+    });
+  }
+
+  // Nothing stored means nothing fell back: the vector leg is not missing
+  // coverage, the corpus is empty.
+  if (!hasRecords(db, options.source)) {
+    return buildQueryResult(cleanQuery, [], "semantic", limit, startedAt);
+  }
+
+  const vector = await vectorSearch(db, cleanQuery, { limit, source: options.source });
+  if (!vector) {
+    return lexicalFallback(
+      queryLexical(db, cleanQuery, { limit, source: options.source }),
+      limit,
+      "semantic",
+      startedAt,
+    );
+  }
+  return buildQueryResult(cleanQuery, vector.hits, "semantic", limit, startedAt);
+}
+
+/**
+ * Reciprocal-Rank fusion of the lexical and vector legs. When the vector leg
+ * cannot run, fusion has nothing to add: the lexical answer is returned with
+ * the envelope naming the requested mode and the reason, so `--hybrid` never
+ * pretends two engines ran.
+ */
+export async function queryHybrid(
+  db: Database,
+  queryText: string,
+  options: ReadQueryOptions = {},
+): Promise<QueryResult> {
+  const startedAt = performance.now();
+  const limit = options.limit ?? 20;
+  const cleanQuery = queryText.trim();
+  if (!cleanQuery) {
+    return buildQueryResult(queryText, [], "hybrid", limit, startedAt, {
+      countReason: COUNT_REASON_EMPTY_QUERY,
+    });
+  }
+
+  const candidateLimit = Math.max(limit * 3, 60);
+
+  // Nothing stored means nothing fell back: the vector leg is not missing
+  // coverage, the corpus is empty.
+  if (!hasRecords(db, options.source)) {
+    return buildQueryResult(cleanQuery, [], "hybrid", limit, startedAt);
+  }
+
+  const lexicalResult = queryLexical(db, cleanQuery, {
+    limit: candidateLimit,
+    source: options.source,
+  });
+
+  const vector = await vectorSearch(db, cleanQuery, {
+    limit: candidateLimit,
+    source: options.source,
+  });
+
+  if (!vector) {
+    return lexicalFallback(lexicalResult, limit, "hybrid", startedAt);
+  }
+
+  // The title lane precedes the fusion instead of entering it: a title hit is
+  // session-level and has no record id to be keyed by, and the lane it comes
+  // from is not an engine the fusion combines but the lexical engine's own
+  // first pass. The fused hits fill what the titles leave of the limit, so the
+  // result stays bounded by it.
+  const isTitleHit = (hit: SearchHit): hit is TitleSearchHit => hit.match_type === "title";
+  const isRecordHit = (hit: SearchHit): hit is RecordSearchHit => hit.match_type !== "title";
+  const titles = lexicalResult.hits.filter(isTitleHit).slice(0, limit);
+  const recordHits = lexicalResult.hits.filter(isRecordHit);
+
+  const RRF_K = 60;
+  const scoredMap = new Map<
+    string,
+    {
+      hit: RecordSearchHit;
+      rrfScore: number;
+      lexicalRank?: number;
+      semanticRank?: number;
+    }
+  >();
+
+  // The record leg keeps the ranks the lexical lane gave its records. The
+  // title hits it emitted first shift every one of them by the same offset, so
+  // the order within the leg — which is all RRF reads — is unchanged.
+  for (let i = 0; i < recordHits.length; i++) {
+    const hit = recordHits[i];
+    const rank = i + 1;
+    const rrf = 1 / (RRF_K + rank);
+    scoredMap.set(hit.record_id, {
+      hit,
+      rrfScore: rrf,
+      lexicalRank: rank,
+    });
+  }
+
+  for (let i = 0; i < vector.hits.length; i++) {
+    const hit = vector.hits[i];
+    const rank = i + 1;
+    const rrf = 1 / (RRF_K + rank);
+    const existing = scoredMap.get(hit.record_id);
+    if (existing) {
+      existing.rrfScore += rrf;
+      existing.semanticRank = rank;
+    } else {
+      scoredMap.set(hit.record_id, {
+        hit,
+        rrfScore: rrf,
+        semanticRank: rank,
+      });
+    }
+  }
+
+  const combined = Array.from(scoredMap.values());
+  combined.sort((a, b) => b.rrfScore - a.rrfScore);
+
+  const topCombined = combined.slice(0, limit - titles.length);
+  const hits: SearchHit[] = [...titles];
+
+  for (const item of topCombined) {
+    hits.push({
+      ...item.hit,
+      rank: item.rrfScore,
+    });
+  }
+
+  return buildQueryResult(cleanQuery, hits, "hybrid", limit, startedAt, {
+    // The lexical leg of the fusion may have widened a zero-hit candidate
+    // set or fallen back to escaped terms; report both rather than hiding
+    // them behind the hybrid label.
+    fallbackReason: lexicalResult.meta.fallback_reason,
+    widened: lexicalResult.meta.widened,
+  });
+}
+
+/**
+ * The session-level serving reads: a deleted session is not found, not listed,
+ * and offers no records, while its rows stay exactly where the store keeps them
+ * (`sessions`, `records` and every derived artifact — db.ts's `tombstoneSession`).
+ * The predicate is the lanes' own, so a session cannot be invisible to search
+ * while `ledger recent`, a parent-title lookup, or a record walk still shows it.
+ */
+export function sessionById(db: Database, id: string): SessionRecord | null {
+  return (
+    db
+      .query<SessionRecord, [string]>(
+        `SELECT * FROM sessions WHERE id = ? AND ${tombstonePredicate(db, "sessions.id")} LIMIT 1`,
+      )
+      .get(id) ?? null
+  );
+}
+
+export function allSessions(db: Database): SessionRecord[] {
+  return db
+    .query<SessionRecord, []>(
+      `SELECT * FROM sessions WHERE ${tombstonePredicate(db, "sessions.id")}
+       ORDER BY started_at DESC, id ASC`,
+    )
+    .all();
+}
+
+export function lastSessions(
+  db: Database,
+  options: { limit?: number; source?: string } = {},
+): SessionRecord[] {
+  const limit = options.limit ?? 20;
+  if (options.source) {
+    return db
+      .query<SessionRecord, [string, number]>(
+        `SELECT * FROM sessions WHERE source = ? AND ${tombstonePredicate(db, "sessions.id")}
+         ORDER BY updated_at DESC, started_at DESC, id ASC LIMIT ?`,
+      )
+      .all(options.source, limit);
+  }
+  return db
+    .query<SessionRecord, [number]>(
+      `SELECT * FROM sessions WHERE ${tombstonePredicate(db, "sessions.id")}
+       ORDER BY updated_at DESC, started_at DESC, id ASC LIMIT ?`,
+    )
+    .all(limit);
+}
+
+export function sessionRecords(db: Database, sessionId: string): CanonicalDbRecord[] {
+  return db
+    .query<CanonicalDbRecord, [string]>(
+      `SELECT * FROM records WHERE session_id = ? AND ${tombstonePredicate(db, "records.session_id")}
+       ORDER BY source_order_id ASC, component_index ASC`,
+    )
+    .all(sessionId);
+}
+
+/**
+ * Why a store could not be read: missing or empty, newer than this build
+ * (schema or derived index), not a Ledger store, or missing the read schema.
+ */
+export type ReaderErrorCode =
+  | "STORE_NOT_INITIALIZED"
+  | "SCHEMA_MISMATCH"
+  | "FORMAT_MISMATCH"
+  | "STORE_UNREADABLE"
+  | "STORE_SCHEMA_INCOMPLETE";
+
+/**
+ * Typed read refusal. The message always names the path and the remedy: a read
+ * verb never silently creates, upgrades, or repairs a store, and an operator
+ * should not have to decode a raw SQLite error to learn that.
+ */
+export class ReaderError extends Error {
+  readonly code: ReaderErrorCode;
+
+  constructor(code: ReaderErrorCode, message: string) {
+    super(message);
+    this.name = "ReaderError";
+    this.code = code;
+  }
+}
+
+/**
+ * The SQLite header records the journal mode at bytes 18-19: write version 2 is
+ * WAL. A WAL store needs its `-wal`/`-shm` sidecars before any connection may
+ * open it read-only — unlike a writable open, a read-only one may not create
+ * them — so the failure is diagnosed here instead of surfacing as a bare
+ * "unable to open database file" or "disk I/O error".
+ */
+function walStoreWithoutSidecars(dbPath: string): boolean {
+  if (existsSync(`${dbPath}-wal`) && existsSync(`${dbPath}-shm`)) return false;
+  let fd: number | undefined;
+  try {
+    fd = openSync(dbPath, "r");
+    const header = Buffer.alloc(20);
+    if (readSync(fd, header, 0, 20, 0) < 20) return false;
+    return header.toString("latin1", 0, 15) === "SQLite format 3" && header[18] === 2;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * The store-status wording, plus the one diagnosis that is specific to opening
+ * a store read-only: a WAL database whose sidecars are gone cannot be opened
+ * until a writer recreates them.
+ */
+function unreadableMessage(dbPath: string, detail: string, phase: "open" | "read"): string {
+  if (walStoreWithoutSidecars(dbPath)) {
+    return `Cannot open database at ${dbPath}: ${detail}. The store is a WAL database missing its -wal/-shm sidecars;` +
+      " a read-only reader cannot create them — run `trajectories sync` (or restore the sidecars).";
+  }
+  return phase === "open"
+    ? `Cannot open database at ${dbPath}: ${detail}.`
+    : `Cannot read database at ${dbPath}: ${detail}. The file may be corrupt or not a SQLite database.`;
+}
+
+/**
+ * Open `dbPath` read-only in the engine's own sense: the connection flag is
+ * irreversible and enforced by SQLite, so no statement on it can write, create
+ * a table, or migrate a schema. `PRAGMA query_only` is deliberately not used —
+ * it is reversible per connection and still permits file creation.
+ *
+ * Every failure is typed, and every refusal comes from the shared read gate
+ * (`classifyReadStore`), so this and `readStoreStatus` cannot disagree about
+ * what a store is. A store whose schema is older than this build keeps serving
+ * reads (`status` semantics) while it carries the read schema, and a store with
+ * a pending index re-derivation — or one derived by an *older* rule set — is
+ * read as written: the index is stale, not unreadable. A missing or empty
+ * store, a store this build cannot read, a store written by a newer schema, a
+ * store whose derived index a newer build's rules produced, and a store without
+ * the read schema are refused.
+ *
+ * Exported for `TrajectoryReader`, for the package's own `delete` verb — which
+ * must classify a store without initializing or adopting one — and for the
+ * read-path tests, which pin the engine-level flag by writing through the handle
+ * it returns. It is not part of the package's public surface (`index.ts` exports
+ * the class, not this).
+ */
+export function openReadOnlyStore(dbPath: string): Database {
+  const store = classifyReadStore(dbPath);
+  switch (store.state) {
+    case "ok":
+      return store.db;
+    case "not_initialized":
+      throw new ReaderError(
+        "STORE_NOT_INITIALIZED",
+        store.reason === "missing"
+          ? `Database not found at ${dbPath}. Run \`trajectories sync\` or \`trajectories build\` first.`
+          : `Database at ${dbPath} exists but is empty (zero bytes), so there is no store to read.` +
+            " Run `trajectories sync` or `trajectories build` first.",
+      );
+    case "foreign":
+      throw new ReaderError(
+        "STORE_UNREADABLE",
+        `Database at ${dbPath} exists but is not an initialized Ledger store (no sessions table).`,
+      );
+    case "unreadable":
+      throw new ReaderError("STORE_UNREADABLE", unreadableMessage(dbPath, store.detail, store.phase));
+    case "schema_mismatch":
+      throw new ReaderError(
+        "SCHEMA_MISMATCH",
+        `Database schema version ${store.schemaVersion} at ${dbPath} is newer than supported schema version ${SCHEMA_VERSION}.`,
+      );
+    case "format_mismatch":
+      throw new ReaderError("FORMAT_MISMATCH", formatMismatchMessage(dbPath, store));
+    case "incomplete":
+      throw new ReaderError("STORE_SCHEMA_INCOMPLETE", incompleteStoreMessage(dbPath, store.firstGap, store.schemaVersion));
+  }
+}
+
+/**
+ * Read-only view of one Ledger store for one verb invocation.
+ *
+ * Short-lived by design: a reader is created per CLI verb and closed, so a
+ * replaced store leaves no stranded handle or index behind. Reads never take
+ * the writer lease, never create or upgrade the store, and never backfill
+ * embeddings — `--semantic`/`--hybrid` answer lexically when the store holds no
+ * vectors the active provider can use (see `SearchMeta.fallback_reason`).
+ */
+export class TrajectoryReader {
+  private db: Database;
+  readonly path: string;
+
+  constructor(path: string = "ledger.sqlite") {
+    this.path = path;
+    this.db = openReadOnlyStore(path);
+  }
+
+  query(
+    queryText: string,
+    options?: { limit?: number; source?: string; mode?: "lexical" },
+  ): QueryResult;
+  query(
+    queryText: string,
+    options: { limit?: number; source?: string; mode: "semantic" | "hybrid" },
+  ): Promise<QueryResult>;
+  query(
+    queryText: string,
+    options?: { limit?: number; source?: string; mode?: "lexical" | "semantic" | "hybrid" },
+  ): QueryResult | Promise<QueryResult>;
+  query(
+    queryText: string,
+    options: { limit?: number; source?: string; mode?: "lexical" | "semantic" | "hybrid" } = {},
+  ): QueryResult | Promise<QueryResult> {
+    if (options.mode === "semantic") {
+      return this.querySemantic(queryText, options);
+    }
+    if (options.mode === "hybrid") {
+      return this.queryHybrid(queryText, options);
+    }
+    return this.queryLexical(queryText, options);
+  }
+
+  queryLexical(queryText: string, options: ReadQueryOptions = {}): QueryResult {
+    return queryLexical(this.db, queryText, options);
+  }
+
+  querySemantic(queryText: string, options: ReadQueryOptions = {}): Promise<QueryResult> {
+    return querySemantic(this.db, queryText, options);
+  }
+
+  queryHybrid(queryText: string, options: ReadQueryOptions = {}): Promise<QueryResult> {
+    return queryHybrid(this.db, queryText, options);
+  }
+
+  getSession(id: string): SessionRecord | null {
+    return sessionById(this.db, id);
+  }
+
+  getAllSessions(): SessionRecord[] {
+    return allSessions(this.db);
+  }
+
+  getLastSessions(options?: { limit?: number; source?: string }): SessionRecord[] {
+    return lastSessions(this.db, options);
+  }
+
+  getSessionRecords(sessionId: string): CanonicalDbRecord[] {
+    return sessionRecords(this.db, sessionId);
+  }
+
+  getSessionCount(): number {
+    return countSessions(this.db);
+  }
+
+  getRecordCount(): number {
+    return countRecords(this.db);
+  }
+
+  /** Compact durable coverage signal for robot envelopes; null when no pass
+   * has recorded coverage (the field is then simply omitted). */
+  getSourceCoverageSummary(): SourceCoverageSummary | null {
+    const hasTable = !!this.db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='source_coverage' LIMIT 1;",
+      )
+      .get();
+    return hasTable ? readSourceCoverageSummary(this.db) : null;
+  }
+
+  getDiscoverySummary(): DiscoverySummary | null { return readDiscoverySummary(this.db); }
+
+  getSchemaVersion(): number {
+    return (
+      this.db
+        .query<{ user_version: number }, []>("PRAGMA user_version;")
+        .get()?.user_version ?? 0
+    );
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}