@dzhechkov/memory 0.2.19 → 0.2.20

package/src/sqlite-backend.ts

@@ -13,6 +13,8 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 import type { MemoryBackend, MemoryQuery, MemoryRecord } from './backend.js';
+import { openSqliteReadOnly, SqliteReadOnlyStore } from './sqlite-readonly.js';
+import type { OpenReadOnlyOptions, ReadOnlyStore } from './sqlite-readonly.js';
 
 const require = createRequire(import.meta.url);
 
@@ -117,14 +119,14 @@ const FTS5_SQL = `
 `;
 
 /** FTS5 query — matching records with their relevance rank (lower = better). */
-const FTS5_SEARCH_SQL = `
+export const FTS5_SEARCH_SQL = `
   SELECT mr.*, fts.rank AS _rank FROM memory_fts fts
   JOIN memory_records mr ON mr.rowid = fts.rowid
   WHERE memory_fts MATCH ?
   ORDER BY fts.rank
 `;
 
-const FTS5_SEARCH_SKILL_SQL = `
+export const FTS5_SEARCH_SKILL_SQL = `
   SELECT mr.*, fts.rank AS _rank FROM memory_fts fts
   JOIN memory_records mr ON mr.rowid = fts.rowid
   WHERE memory_fts MATCH ? AND mr.skill_id = ?
@@ -138,9 +140,94 @@ const UPSERT_SQL = `
 
 const DELETE_SQL = 'DELETE FROM memory_records WHERE id = ?';
 
-const ALL_SQL = 'SELECT * FROM memory_records';
-const COUNT_SQL = 'SELECT COUNT(*) as cnt FROM memory_records';
-const BY_SKILL_SQL = 'SELECT * FROM memory_records WHERE skill_id = ?';
+export const ALL_SQL = 'SELECT * FROM memory_records';
+export const COUNT_SQL = 'SELECT COUNT(*) as cnt FROM memory_records';
+export const BY_SKILL_SQL = 'SELECT * FROM memory_records WHERE skill_id = ?';
+
+/**
+ * The FTS5-ranked / keyword-overlap search decision, extracted from `querySync` so a
+ * read-only backend (which prepares the same statements but never runs `INIT_SQL`/`FTS5_SQL`)
+ * can share it byte-for-byte instead of forking its own copy. A forked copy is exactly the
+ * class of bug documented above (lines 24-29): a reader whose ranking diverges from the
+ * writer's silently regresses recall. Behaviorally IDENTICAL to the body it replaced — same
+ * sort order, same `stemOf` prefixes, same `relevance > 0` filter, same `terms.length > 0`
+ * branch. `@internal` — exported only so `sqlite-readonly.ts` can call it; not part of the
+ * package's public surface (see `index.ts`, which does not re-export it).
+ *
+ * @internal
+ */
+export function searchPreparedRecords(
+  stmts: { fts?: any; ftsSkill?: any; all: any; bySkill: any },
+  hasFts5: boolean,
+  query: MemoryQuery,
+): MemoryRecord[] {
+  const limit = query.limit ?? DEFAULT_LIMIT;
+
+  // FTS5 path — use SQLite full-text search when available and text query provided
+  if (hasFts5 && query.text !== undefined && query.text.trim().length > 0) {
+    try {
+      // FTS5 query syntax: simple terms joined by spaces (implicit AND → OR with ranking)
+      // Each token also contributes its prefix-stem as `stem*` (see stemOf): the exact word and
+      // its inflections all match, and a row holding the exact token matches BOTH disjuncts, so
+      // bm25 ranks it at or above a prefix-only row. Tokens are \p{L}\p{N}-only — safe to
+      // interpolate; the star is appended HERE, never taken from user text.
+      const ftsQuery = tokenize(query.text)
+        .flatMap((t) => {
+          const stem = stemOf(t);
+          return stem === null ? [t] : [t, stem + '*'];
+        })
+        .join(' OR ');
+      if (ftsQuery.length > 0) {
+        let rows: any[];
+        if (query.skillId !== undefined) {
+          rows = stmts.ftsSkill!.all(ftsQuery, query.skillId);
+        } else {
+          rows = stmts.fts!.all(ftsQuery);
+        }
+        // Rank by FTS5 relevance FIRST (lower rank = better match), with score
+        // then timestamp as a true tiebreak between equally-relevant rows. Score
+        // must NOT be primary — that would discard FTS5's relevance signal and
+        // diverge from the JSON backend (which also ranks relevance-primary).
+        const ranked = rows
+          .map((row) => ({ record: rowToRecord(row), rank: row._rank as number }))
+          .sort(
+            (a, b) =>
+              a.rank - b.rank ||
+              b.record.score - a.record.score ||
+              b.record.timestamp.localeCompare(a.record.timestamp),
+          );
+        return ranked.slice(0, limit).map((entry) => entry.record);
+      }
+    } catch {
+      // FTS5 query failed (e.g., special chars) — fall through to keyword approach
+    }
+  }
+
+  // Keyword overlap fallback
+  const terms = query.text !== undefined ? tokenize(query.text) : [];
+  let rows: any[];
+  if (query.skillId !== undefined) {
+    rows = stmts.bySkill.all(query.skillId);
+  } else {
+    rows = stmts.all.all();
+  }
+
+  const records = rows.map(rowToRecord);
+  const ranked = records
+    .map((record) => ({ record, relevance: relevanceOf(record, terms) }))
+    .sort(
+      (a, b) =>
+        b.relevance - a.relevance ||
+        b.record.score - a.record.score ||
+        b.record.timestamp.localeCompare(a.record.timestamp),
+    );
+  // The SAME guard the JSON backend applies, so a store's answers never depend on which backend is
+  // installed. This is the keyword FALLBACK; the FTS5 path above already returns zero honestly and
+  // is untouched. With no usable terms there was nothing to match on, so the store still comes back
+  // ranked by confidence — that distinction is the whole decision (ADR-001).
+  const filtered = terms.length > 0 ? ranked.filter((entry) => entry.relevance > 0) : ranked;
+  return filtered.slice(0, limit).map((entry) => entry.record);
+}
 
 /** Options for SqliteBackend. */
 export interface SqliteBackendOptions {
@@ -204,6 +291,32 @@ export class SqliteBackend implements MemoryBackend {
     return new SqliteBackend(db);
   }
 
+  /**
+   * Open a SQLite database for READING ONLY (ADR-001, Решение 2). Never runs `INIT_SQL`,
+   * `FTS5_SQL`, or the FTS rebuild — the writer's `constructor` above stays untouched byte
+   * for byte. Presence of the FTS5 table is discovered by reading `sqlite_master`, not by
+   * attempting to (re)create it. `put`/`putMany`/`remove`/`removeSync` on the returned store
+   * throw `read-only backend: <method> is not available`.
+   */
+  static openReadOnly(filePath: string, opts?: OpenReadOnlyOptions): ReadOnlyStore {
+    const handle = openSqliteReadOnly(filePath, opts);
+    try {
+      return new SqliteReadOnlyStore(handle);
+    } catch (err) {
+      // The constructor prepares statements (`sqlite_master` lookup, ALL/COUNT/BY_SKILL) against
+      // an ALREADY-OPEN handle — if any of that throws (e.g. a valid SQLite file missing
+      // `memory_records`), the handle must not leak: close the connection and remove a tmp-copy
+      // before rethrowing (fix round 1, HIGH #2).
+      try {
+        handle.db.close();
+      } catch {
+        // already failing on the caller's side — a close failure here must not mask the real cause
+      }
+      handle.cleanup();
+      throw err;
+    }
+  }
+
   put(record: MemoryRecord): Promise<void> {
     this.upsertStmt.run(
       record.id,
@@ -227,72 +340,11 @@ export class SqliteBackend implements MemoryBackend {
    * path (a recommender / `dz recall`) can query the store without an async ripple.
    */
   querySync(query: MemoryQuery): MemoryRecord[] {
-    const limit = query.limit ?? DEFAULT_LIMIT;
-
-    // FTS5 path — use SQLite full-text search when available and text query provided
-    if (this.hasFts5 && query.text !== undefined && query.text.trim().length > 0) {
-      try {
-        // FTS5 query syntax: simple terms joined by spaces (implicit AND → OR with ranking)
-        // Each token also contributes its prefix-stem as `stem*` (see stemOf): the exact word and
-        // its inflections all match, and a row holding the exact token matches BOTH disjuncts, so
-        // bm25 ranks it at or above a prefix-only row. Tokens are \p{L}\p{N}-only — safe to
-        // interpolate; the star is appended HERE, never taken from user text.
-        const ftsQuery = tokenize(query.text)
-          .flatMap((t) => {
-            const stem = stemOf(t);
-            return stem === null ? [t] : [t, stem + '*'];
-          })
-          .join(' OR ');
-        if (ftsQuery.length > 0) {
-          let rows: any[];
-          if (query.skillId !== undefined) {
-            rows = this.ftsSearchSkillStmt!.all(ftsQuery, query.skillId);
-          } else {
-            rows = this.ftsSearchStmt!.all(ftsQuery);
-          }
-          // Rank by FTS5 relevance FIRST (lower rank = better match), with score
-          // then timestamp as a true tiebreak between equally-relevant rows. Score
-          // must NOT be primary — that would discard FTS5's relevance signal and
-          // diverge from the JSON backend (which also ranks relevance-primary).
-          const ranked = rows
-            .map((row) => ({ record: rowToRecord(row), rank: row._rank as number }))
-            .sort(
-              (a, b) =>
-                a.rank - b.rank ||
-                b.record.score - a.record.score ||
-                b.record.timestamp.localeCompare(a.record.timestamp),
-            );
-          return ranked.slice(0, limit).map((entry) => entry.record);
-        }
-      } catch {
-        // FTS5 query failed (e.g., special chars) — fall through to keyword approach
-      }
-    }
-
-    // Keyword overlap fallback
-    const terms = query.text !== undefined ? tokenize(query.text) : [];
-    let rows: any[];
-    if (query.skillId !== undefined) {
-      rows = this.bySkillStmt.all(query.skillId);
-    } else {
-      rows = this.allStmt.all();
-    }
-
-    const records = rows.map(rowToRecord);
-    const ranked = records
-      .map((record) => ({ record, relevance: relevanceOf(record, terms) }))
-      .sort(
-        (a, b) =>
-          b.relevance - a.relevance ||
-          b.record.score - a.record.score ||
-          b.record.timestamp.localeCompare(a.record.timestamp),
-      );
-    // The SAME guard the JSON backend applies, so a store's answers never depend on which backend is
-    // installed. This is the keyword FALLBACK; the FTS5 path above already returns zero honestly and
-    // is untouched. With no usable terms there was nothing to match on, so the store still comes back
-    // ranked by confidence — that distinction is the whole decision (ADR-001).
-    const filtered = terms.length > 0 ? ranked.filter((entry) => entry.relevance > 0) : ranked;
-    return filtered.slice(0, limit).map((entry) => entry.record);
+    return searchPreparedRecords(
+      { fts: this.ftsSearchStmt, ftsSkill: this.ftsSearchSkillStmt, all: this.allStmt, bySkill: this.bySkillStmt },
+      this.hasFts5,
+      query,
+    );
   }
 
   all(): Promise<MemoryRecord[]> {
@@ -343,7 +395,7 @@ export class SqliteBackend implements MemoryBackend {
 }
 
 /** Convert a raw SQLite row to a MemoryRecord. */
-function rowToRecord(row: any): MemoryRecord {
+export function rowToRecord(row: any): MemoryRecord {
   return {
     id: row.id,
     skillId: row.skill_id,

package/src/sqlite-readonly.ts

@@ -0,0 +1,244 @@
+/**
+ * A single, shared opener for READ-ONLY SQLite access (ADR-001,
+ * `features/store-readonly-reads/03_adr/001-read-opener-ladder-in-place-then-tmp-copy.md`).
+ *
+ * `{ readonly: true }` alone does not read a WAL database on a directory that cannot be written
+ * to: the wal-mode reader still needs to create (or find) `-shm`/`-wal` next to the file, and on
+ * a read-only-mounted directory that create fails with `unable to open database file` — MEASURED
+ * 2026-09-12 against better-sqlite3 11.10.0 / SQLite 3.49.2 (`chattr +i` on a `/var/tmp`
+ * directory holding a checkpointed WAL database). `openSqliteReadOnly` climbs a three-step ladder
+ * instead of assuming step 1 always works:
+ *
+ *   1. **In place.** `{ readonly: true, fileMustExist: true }`, then a real read (the WAL error
+ *      surfaces on the first query, not on open) — this is what a live writer on the same host
+ *      gets: it sees uncheckpointed rows too.
+ *   2. **Copy.** Only on `SQLITE_CANTOPEN` / "unable to open database file": copy the database
+ *      (+ its `-wal`, if any — never `-shm`, which is derived and recreated) into a fresh
+ *      `mkdtemp` directory and open THAT read-only.
+ *   3. **Honest failure.** Any other error, or step 2 itself failing, throws — naming the path
+ *      and the original cause. Never a swallowed `{ hits: [] }`.
+ *
+ * @packageDocumentation
+ */
+
+import { createRequire } from 'node:module';
+import { existsSync, copyFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+import type { MemoryQuery, MemoryRecord } from './backend.js';
+import {
+  searchPreparedRecords,
+  FTS5_SEARCH_SQL,
+  FTS5_SEARCH_SKILL_SQL,
+  ALL_SQL,
+  COUNT_SQL,
+  BY_SKILL_SQL,
+  rowToRecord,
+} from './sqlite-backend.js';
+
+const require = createRequire(import.meta.url);
+
+/** Constructor shape `openSqliteReadOnly` needs from `better-sqlite3` (or a caller-supplied one). */
+type DatabaseCtor = new (p: string, o?: { readonly?: boolean; fileMustExist?: boolean }) => any;
+
+/** The handle returned by {@link openSqliteReadOnly}. */
+export interface ReadOnlyHandle {
+  /** better-sqlite3 `Database`, opened read-only. */
+  readonly db: any;
+  /** Which rung of the ladder answered: the file itself, or a temporary copy of it. */
+  readonly source: 'in-place' | 'tmp-copy';
+  /** Removes the temporary copy's directory. No-op for `'in-place'`. Idempotent — safe to call more than once. */
+  readonly cleanup: () => void;
+}
+
+/** Options for {@link openSqliteReadOnly}. */
+export interface OpenReadOnlyOptions {
+  /**
+   * The `better-sqlite3` constructor to use. Callers that resolve their own copy of the native
+   * module (`book-kb.ts`, `agentdb-index.ts` — both resolve from the TARGET project, not from
+   * this package) MUST pass it here rather than let this opener resolve its own: a silently
+   * different native-module instance is the same class of bug as "the tool in PATH decides the
+   * verdict". Omitted only by callers that are fine with the memory package's own resolution
+   * (`SqliteBackend.openReadOnly`, which resolves via `createRequire(import.meta.url)` — the same
+   * resolution `SqliteBackend.open` already uses).
+   */
+  readonly Database?: DatabaseCtor;
+}
+
+function defaultDatabaseCtor(): DatabaseCtor {
+  // Dynamic require — better-sqlite3 must be available at runtime, same discipline as
+  // `SqliteBackend.open` (sqlite-backend.ts).
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return require('better-sqlite3');
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Step-1 → step-2 trigger: ONLY a can't-open-the-file failure retries as a copy. */
+function isCantOpenError(err: unknown): boolean {
+  const code = (err as { code?: string } | undefined)?.code;
+  const msg = errorMessage(err);
+  return code === 'SQLITE_CANTOPEN' || /unable to open database file/i.test(msg);
+}
+
+/** A cheap, real read — the WAL "can't create -shm/-wal here" failure surfaces on a query, not on open. */
+function probe(db: any): void {
+  db.prepare('SELECT count(*) AS n FROM sqlite_master').get();
+}
+
+function closeQuietly(db: any): void {
+  try {
+    db.close();
+  } catch {
+    // already failing on the caller's side — a close failure here must not mask the real cause
+  }
+}
+
+function removeQuietly(dir: string): void {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best-effort — the honest-failure path below still reports the real cause
+  }
+}
+
+/**
+ * Open `filePath` for reading only, climbing the ladder described above.
+ *
+ * Deliberately does NOT: `mkdirSync` any directory, run any DDL/DML, set `journal_mode` or
+ * `synchronous`, or check `existsSync` itself (FR-5 keeps that check with the caller, before this
+ * is called — `fileMustExist: true` below is only the second line of defence against a race).
+ */
+export function openSqliteReadOnly(filePath: string, opts?: OpenReadOnlyOptions): ReadOnlyHandle {
+  const Database = opts?.Database ?? defaultDatabaseCtor();
+
+  // Step 1 — in place.
+  let inPlaceDb: any | undefined;
+  try {
+    inPlaceDb = new Database(filePath, { readonly: true, fileMustExist: true });
+    probe(inPlaceDb);
+    return { db: inPlaceDb, source: 'in-place', cleanup: () => {} };
+  } catch (stepOneErr) {
+    if (inPlaceDb !== undefined) closeQuietly(inPlaceDb);
+    if (!isCantOpenError(stepOneErr)) {
+      throw new Error(`failed to open ${filePath} for reading: ${errorMessage(stepOneErr)}`);
+    }
+
+    // Step 2 — copy into a fresh tmp directory.
+    let tmpDir: string | undefined;
+    let copyDb: any | undefined;
+    try {
+      tmpDir = mkdtempSync(join(tmpdir(), 'dz-ro-'));
+      const dest = join(tmpDir, basename(filePath));
+      copyFileSync(filePath, dest);
+      const walSource = `${filePath}-wal`;
+      if (existsSync(walSource)) {
+        copyFileSync(walSource, `${dest}-wal`);
+      }
+      // `-shm` is intentionally NOT copied — it is derived and SQLite recreates it; a stale one
+      // next to a fresh copy is worse than none (ADR-001, Решение 1, ступень 2).
+      copyDb = new Database(dest, { readonly: true, fileMustExist: true });
+      probe(copyDb);
+      const dir = tmpDir;
+      return {
+        db: copyDb,
+        source: 'tmp-copy',
+        cleanup: () => removeQuietly(dir),
+      };
+    } catch (stepTwoErr) {
+      // `copyDb` may have opened successfully and THEN failed in `probe()` — an unclosed handle
+      // here leaks a file descriptor and, on a platform that refuses to delete an open file,
+      // leaves the tmp directory behind too. Close before removing (fix round 1, HIGH #1).
+      if (copyDb !== undefined) closeQuietly(copyDb);
+      if (tmpDir !== undefined) removeQuietly(tmpDir);
+      throw new Error(`failed to open ${filePath} for reading: ${errorMessage(stepTwoErr)}`);
+    }
+  }
+}
+
+/** The read-only surface a caller gets back from {@link openSqliteReadOnly} + the search logic. */
+export interface ReadOnlyStore {
+  querySync(query: MemoryQuery): MemoryRecord[];
+  allSync(): MemoryRecord[];
+  countSync(): number;
+  close(): void;
+}
+
+/** `sqlite_master` lookup used to discover FTS5 presence WITHOUT attempting to (re)create it. */
+const FTS5_TABLE_PRESENT_SQL = `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_fts'`;
+
+/**
+ * `ReadOnlyStore` over a {@link ReadOnlyHandle}. Prepares the SAME statement text
+ * `SqliteBackend`'s writer constructor prepares (imported, not forked) and shares its search
+ * logic via `searchPreparedRecords` — so a reader can never rank differently than the writer.
+ * Runs NO `INIT_SQL`, NO `FTS5_SQL`, NO FTS rebuild; discovers FTS5 by reading `sqlite_master`.
+ * Mutating methods throw — this store has no `put`/`remove` sibling by construction, not by
+ * convention.
+ */
+export class SqliteReadOnlyStore implements ReadOnlyStore {
+  private readonly handle: ReadOnlyHandle;
+  private readonly hasFts5: boolean;
+  private readonly ftsSearchStmt: any | undefined;
+  private readonly ftsSearchSkillStmt: any | undefined;
+  private readonly allStmt: any;
+  private readonly countStmt: any;
+  private readonly bySkillStmt: any;
+
+  constructor(handle: ReadOnlyHandle) {
+    this.handle = handle;
+    const db = handle.db;
+    const ftsRow = db.prepare(FTS5_TABLE_PRESENT_SQL).get() as { name?: string } | undefined;
+    this.hasFts5 = ftsRow?.name === 'memory_fts';
+    if (this.hasFts5) {
+      this.ftsSearchStmt = db.prepare(FTS5_SEARCH_SQL);
+      this.ftsSearchSkillStmt = db.prepare(FTS5_SEARCH_SKILL_SQL);
+    }
+    this.allStmt = db.prepare(ALL_SQL);
+    this.countStmt = db.prepare(COUNT_SQL);
+    this.bySkillStmt = db.prepare(BY_SKILL_SQL);
+  }
+
+  querySync(query: MemoryQuery): MemoryRecord[] {
+    return searchPreparedRecords(
+      { fts: this.ftsSearchStmt, ftsSkill: this.ftsSearchSkillStmt, all: this.allStmt, bySkill: this.bySkillStmt },
+      this.hasFts5,
+      query,
+    );
+  }
+
+  allSync(): MemoryRecord[] {
+    return this.allStmt.all().map(rowToRecord);
+  }
+
+  countSync(): number {
+    return this.countStmt.get().cnt as number;
+  }
+
+  /** `db.close()` first, THEN `handle.cleanup()` in `finally` — the tmp-copy must be removed even if `close()` throws. */
+  close(): void {
+    try {
+      this.handle.db.close();
+    } finally {
+      this.handle.cleanup();
+    }
+  }
+
+  put(): never {
+    throw new Error('read-only backend: put is not available');
+  }
+
+  putMany(): never {
+    throw new Error('read-only backend: putMany is not available');
+  }
+
+  remove(): never {
+    throw new Error('read-only backend: remove is not available');
+  }
+
+  removeSync(): never {
+    throw new Error('read-only backend: removeSync is not available');
+  }
+}