superlocalmemory 3.8.3 → 3.8.6

package/src/superlocalmemory/storage/database.py

@@ -18,6 +18,7 @@ from pathlib import Path
 from types import ModuleType
 from typing import Any, Generator
 
+from superlocalmemory.storage.write_lock import get_write_lock
 from superlocalmemory.storage.models import (
     AtomicFact, CanonicalEntity, ConsolidationAction, ConsolidationActionType,
     EdgeType, EntityAlias, EntityProfile, FactType, GraphEdge,
@@ -140,7 +141,17 @@ class DatabaseManager:
     def __init__(self, db_path: str | Path) -> None:
         self.db_path = Path(db_path)
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
-        self._lock = threading.Lock()
+        # Shared write-serialisation lock for this db_path.
+        # get_write_lock() returns the SAME RLock for every caller that
+        # passes the same resolved path, so DatabaseManager, VectorStore,
+        # adapter_base, consolidation, and all other in-process writers
+        # all share ONE lock → zero cross-connection SQLite WAL contention.
+        #
+        # RLock (re-entrant) is required: the self-heal backfill pattern
+        #   with db._lock:        # acquires write lock (count: 1→2)
+        #       vs.upsert(...)    # re-acquires same lock (count: 2→3)
+        # is safe because the same thread re-enters the RLock.
+        self._lock = get_write_lock(self.db_path)
         # Transaction connections are thread-affine in sqlite3. A manager is
         # shared across HTTP, materializer, and worker threads, so a process-
         # global connection slot lets another thread accidentally execute on
@@ -155,6 +166,20 @@ class DatabaseManager:
             conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")  # FIRST — so WAL pragma below uses configured timeout
             conn.execute("PRAGMA journal_mode=WAL")
             conn.execute("PRAGMA foreign_keys=ON")
+            # Fix D: synchronous=NORMAL is safe under WAL — the WAL ensures
+            # atomicity independently of the fsync level.  Removing the
+            # fsync-on-every-commit penalty halves write latency under the
+            # 14 000+ edge-write bursts the materialiser produces per pass.
+            # Trade-off: on a power loss between COMMIT and WAL-checkpoint
+            # the last committed write to memory.db may be lost.  Acceptable
+            # for an LLM memory system; NOT acceptable for financial records.
+            conn.execute("PRAGMA synchronous=NORMAL")
+            # Fix D: reduce WAL auto-checkpoint from the default 1000 to 400
+            # frames.  Smaller checkpoints run more frequently and complete
+            # faster, preventing the WAL file growing unboundedly during
+            # high-ingestion bursts (which triggered checkpoint-starvation
+            # amplifying the lock storm).
+            conn.execute("PRAGMA wal_autocheckpoint=400")
             conn.commit()
         finally:
             conn.close()
@@ -193,9 +218,62 @@ class DatabaseManager:
         conn.execute("PRAGMA foreign_keys=ON")
         return conn
 
+    @contextmanager
+    def _bind_coordinator_connection(
+        self,
+        conn: sqlite3.Connection,
+        capability: Any,
+    ) -> Generator[None, None, None]:
+        """Reuse the coordinator's sole writable connection for one handler.
+
+        This deliberately stays internal: only ``WriteCoordinator`` can issue
+        a capability, and that capability is valid only for its worker thread
+        and the exact resolved database path.  While bound, ``transaction``
+        and ``raw_connection`` become no-op ownership scopes: they may yield
+        the connection, but they must never commit, rollback, or close it.
+        The coordinator owns the enclosing ``BEGIN IMMEDIATE`` and final
+        commit/rollback together with the command receipt.
+        """
+        from superlocalmemory.storage.write_coordinator import WriteCoordinatorError
+
+        if not isinstance(conn, sqlite3.Connection):
+            raise WriteCoordinatorError("coordinator binding requires a sqlite3 connection")
+        validate = getattr(capability, "_validate", None)
+        if not callable(validate):
+            raise WriteCoordinatorError("untrusted coordinator capability")
+        try:
+            validate(self.db_path.expanduser().resolve())
+        except Exception as exc:
+            # Import lazily so the storage manager retains its legacy import
+            # surface when the coordinator is not used.
+            if isinstance(exc, WriteCoordinatorError):
+                raise
+            raise WriteCoordinatorError("untrusted coordinator capability") from exc
+
+        attached = conn.execute("PRAGMA database_list").fetchall()
+        main_path = next((row[2] for row in attached if row[1] == "main"), "")
+        expected_path = self.db_path.expanduser().resolve()
+        if not main_path or Path(main_path).expanduser().resolve() != expected_path:
+            raise WriteCoordinatorError("coordinator connection targets a different database")
+        if getattr(self._txn_state, "conn", None) is not None:
+            raise WriteCoordinatorError("database manager is already bound to a transaction")
+
+        self._txn_state.conn = conn
+        self._txn_state.coordinator_bound = True
+        try:
+            yield
+        finally:
+            self._txn_state.conn = None
+            self._txn_state.coordinator_bound = False
+
     @contextmanager
     def transaction(self) -> Generator[None, None, None]:
         """Atomic transaction. All writes commit or rollback together."""
+        if getattr(self._txn_state, "coordinator_bound", False):
+            # The coordinator has already issued BEGIN IMMEDIATE.  Do not
+            # create a nested transaction or steal its commit/close lifecycle.
+            yield
+            return
         with self._lock:
             conn = self._connect()
             self._txn_state.conn = conn
@@ -218,6 +296,12 @@ class DatabaseManager:
         error, and always closes — mirroring transaction(). This is the public
         way to obtain a connection; there is no `.conn` attribute.
         """
+        coordinator_conn = getattr(self._txn_state, "conn", None)
+        if getattr(self._txn_state, "coordinator_bound", False):
+            if coordinator_conn is None:  # pragma: no cover - binding invariant
+                raise RuntimeError("coordinator binding has no active connection")
+            yield coordinator_conn
+            return
         with self._lock:
             conn = self._connect()
             self._txn_state.conn = conn
@@ -231,15 +315,21 @@ class DatabaseManager:
                 self._txn_state.conn = None
                 conn.close()
 
-    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
-        """Execute SQL with automatic retry on SQLITE_BUSY.
+    # DML prefixes that require the single-writer lock when executed outside
+    # a transaction() context.  Checked case-insensitively against the first
+    # word of the stripped SQL statement.
+    _DML_PREFIXES: frozenset[str] = frozenset({
+        "INSERT", "UPDATE", "DELETE", "REPLACE", "UPSERT",
+        "CREATE", "DROP", "ALTER",
+    })
 
-        Uses shared conn inside transaction, else per-call with retry.
-        """
-        transaction_conn = getattr(self._txn_state, "conn", None)
-        if transaction_conn is not None:
-            return transaction_conn.execute(sql, params).fetchall()
+    def _execute_one(self, sql: str, params: tuple[Any, ...]) -> list[sqlite3.Row]:
+        """Open a per-call connection, execute, commit, close — with retry.
 
+        Never called when inside a transaction() context (that path uses the
+        context's existing connection directly).  Factored out of execute() so
+        the RLock acquisition logic stays in one place.
+        """
         last_error: Exception | None = None
         for attempt in range(_MAX_RETRIES):
             conn = self._connect()
@@ -264,6 +354,42 @@ class DatabaseManager:
         logger.warning("DB operation failed after %d retries: %s", _MAX_RETRIES, last_error)
         raise last_error  # type: ignore[misc]
 
+    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
+        """Execute SQL with automatic retry on SQLITE_BUSY.
+
+        Fix B — single-writer serialisation:
+        • Inside a transaction(): uses the existing connection directly (no
+          lock acquisition — the transaction() context manager already holds
+          _lock for the duration of the whole transaction).
+        • Outside a transaction(), for DML (INSERT/UPDATE/DELETE/…): acquires
+          _lock before opening a per-call connection.  This ensures that
+          concurrent callers — including background workers that bypass
+          transaction() entirely — do not race at the SQLite WAL layer.
+        • Outside a transaction(), for SELECTs: no lock needed — WAL mode
+          allows concurrent readers without stalling writers.
+
+        ORDERING INVARIANT: the _txn_state.conn check MUST come before the
+        lock acquisition.  Reversing the order would deadlock threads that
+        call execute() from inside transaction() because threading.RLock is
+        re-entrant per-thread but a re-entering thread inside transaction()
+        would still try to re-acquire here (lock is already held by the same
+        thread, so RLock re-enters safely — but the old threading.Lock would
+        have deadlocked; that is exactly why we changed to RLock).
+        """
+        # Fast path: already inside a transaction — use its connection directly.
+        transaction_conn = getattr(self._txn_state, "conn", None)
+        if transaction_conn is not None:
+            return transaction_conn.execute(sql, params).fetchall()
+
+        # Determine if this is a write operation that needs serialisation.
+        first_word = sql.strip().upper().split(None, 1)[0] if sql.strip() else ""
+        if first_word in self._DML_PREFIXES:
+            with self._lock:
+                return self._execute_one(sql, params)
+        else:
+            # Read-only path: concurrent reads are safe in WAL mode.
+            return self._execute_one(sql, params)
+
     def store_memory(self, record: MemoryRecord) -> str:
         """Persist a raw memory record. Returns memory_id."""
         _scope = getattr(record, 'scope', None) or 'personal'
@@ -1306,17 +1432,40 @@ class DatabaseManager:
         )
         return [dict(r) for r in rows]
 
-    def cleanup_activation_cache(self) -> int:
-        """Delete expired cache entries. Returns count deleted."""
-        before = self.execute(
-            "SELECT COUNT(*) AS c FROM activation_cache "
-            "WHERE expires_at < datetime('now')"
-        )
-        count = int(before[0]["c"]) if before else 0
-        self.execute(
-            "DELETE FROM activation_cache WHERE expires_at < datetime('now')"
-        )
-        return count
+    def cleanup_activation_cache(
+        self, batch_size: int = 5000, max_batches: int = 500,
+    ) -> int:
+        """Delete expired activation_cache rows in bounded batches.
+
+        Wired into MaintenanceScheduler.  Historically NEITHER cleanup path was
+        ever called, so activation_cache grew without bound — observed 83,518
+        rows on a real DB, all expired, oldest ~3.5 months old.  That bloats the
+        table and its ``idx_actcache_expires`` index and slows every cache
+        INSERT OR REPLACE / lookup.
+
+        Batched so clearing a large backlog never holds the write lock for one
+        long DELETE: each batch commits and yields, letting remember/materialize
+        writers interleave.  ``idx_actcache_expires`` makes the predicate
+        index-backed.  Steady state (30-min cycle) deletes only one cycle's
+        worth, so the loop exits after a single small batch.
+        """
+        total_deleted = 0
+        for _ in range(max_batches):
+            remaining = self.execute(
+                "SELECT COUNT(*) AS c FROM activation_cache "
+                "WHERE expires_at < datetime('now')"
+            )
+            n = int(remaining[0]["c"]) if remaining else 0
+            if n <= 0:
+                break
+            self.execute(
+                "DELETE FROM activation_cache WHERE cache_id IN ("
+                "  SELECT cache_id FROM activation_cache "
+                "  WHERE expires_at < datetime('now') LIMIT ?)",
+                (batch_size,),
+            )
+            total_deleted += min(n, batch_size)
+        return total_deleted
 
     def store_fact_importance(self, entry: dict) -> None:
         """Persist fact importance scores."""

package/src/superlocalmemory/storage/deferred_writes.py

@@ -0,0 +1,209 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com
+
+"""Best-effort, coalesced deferred writes that must NOT block a read path.
+
+Recall must be read-only on its hot path.  Historically the entity resolver
+stamped ``canonical_entities.last_seen`` inline during recall (an ``UPDATE``
+that takes the write lock), so recall waited behind writers — the root of the
+"recall is 8 s" regression.  ``last_seen`` is consumed ONLY by the dashboard
+(entities / graph "last seen" columns); it never feeds recall ranking, so it
+can be written a moment later with zero quality loss.
+
+This module records such touches in memory (instant, lock-free for the caller)
+and flushes them from a single background thread in small coalesced batches.
+Bursts for the same entity collapse to one UPDATE per flush.  Failures are
+swallowed — bookkeeping must never raise into a recall/ingest caller.
+
+This is deliberately small and self-contained; it is the seed of the wider
+single-writer queue (see WRITE-QUEUE-PLAN.md).
+"""
+from __future__ import annotations
+
+import atexit
+import queue
+import threading
+
+_FLUSH_INTERVAL_S = 2.0
+
+
+# ---------------------------------------------------------------------------
+# General best-effort background writer (seed of the single-writer queue).
+# For NON-ESSENTIAL bookkeeping writes that must never block a read/recall
+# path (access logging, activation-cache warming, etc.). Fire-and-forget:
+# jobs are dropped under extreme backpressure rather than blocking a caller.
+# Substantive/durable writes (remember, materialize) do NOT use this — they
+# get the durable single-writer queue (see WRITE-QUEUE-PLAN.md Stage 3).
+# ---------------------------------------------------------------------------
+
+_BG_MAXSIZE = 20000
+_bg_queue: "queue.Queue" = queue.Queue(maxsize=_BG_MAXSIZE)
+_bg_started = False
+_bg_start_lock = threading.Lock()
+_bg_stop = threading.Event()
+_bg_thread: threading.Thread | None = None
+
+
+def _bg_run(work_queue: "queue.Queue", stop: threading.Event) -> None:
+    while not stop.is_set():
+        try:
+            fn = work_queue.get(timeout=0.1)
+        except queue.Empty:
+            continue
+        try:
+            fn()
+        except Exception:
+            # Best-effort: bookkeeping must never crash the writer thread.
+            pass
+        finally:
+            _bg_queue.task_done()
+
+
+def _ensure_bg_thread() -> None:
+    global _bg_queue, _bg_started, _bg_stop, _bg_thread
+    if _bg_thread is not None and _bg_thread.is_alive():
+        return
+    with _bg_start_lock:
+        if _bg_thread is not None and _bg_thread.is_alive():
+            return
+        _bg_queue = queue.Queue(maxsize=_BG_MAXSIZE)
+        _bg_stop = threading.Event()
+        _bg_thread = threading.Thread(
+            target=_bg_run,
+            args=(_bg_queue, _bg_stop),
+            name="slm-bg-writer",
+            daemon=True,
+        )
+        _bg_thread.start()
+        _bg_started = True
+
+
+def submit_background(fn) -> None:
+    """Run *fn* on the shared background writer. Fire-and-forget, best-effort.
+
+    Recall/read paths call this instead of writing inline, so they never wait
+    on the write lock.  Under extreme backpressure the job is dropped (the
+    write was non-essential bookkeeping).
+    """
+    _ensure_bg_thread()
+    try:
+        _bg_queue.put_nowait(fn)
+    except queue.Full:
+        pass
+
+
+def _shutdown_background_writer(timeout: float) -> None:
+    """Stop the shared bookkeeping worker and wait for its thread to exit."""
+    global _bg_started, _bg_thread
+    with _bg_start_lock:
+        thread = _bg_thread
+        if thread is None:
+            return
+        _bg_stop.set()
+    if thread is not threading.current_thread():
+        thread.join(timeout=timeout)
+    if not thread.is_alive():
+        with _bg_start_lock:
+            if _bg_thread is thread:
+                _bg_thread = None
+                _bg_started = False
+
+
+class DeferredLastSeen:
+    """Coalescing background flusher for canonical_entities.last_seen."""
+
+    def __init__(self, db, interval_s: float = _FLUSH_INTERVAL_S) -> None:
+        self._db = db
+        self._interval = interval_s
+        self._pending: dict[tuple[str, str], str] = {}
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._stopped = False
+        self._thread = threading.Thread(
+            target=self._run, name="slm-deferred-lastseen", daemon=True
+        )
+        self._thread.start()
+
+    def touch(self, entity_id: str, profile_id: str, ts: str) -> None:
+        """Record a last_seen update. Instant, coalesced, never blocks."""
+        with self._lock:
+            self._pending[(entity_id, profile_id)] = ts
+
+    def flush(self) -> int:
+        """Write all pending updates now. Returns count. Best-effort."""
+        with self._lock:
+            if not self._pending:
+                return 0
+            batch = self._pending
+            self._pending = {}
+        try:
+            # One transaction => one write-lock acquisition for the whole
+            # batch, off the recall/ingest thread.
+            with self._db.transaction():
+                for (entity_id, profile_id), ts in batch.items():
+                    self._db.execute(
+                        "UPDATE canonical_entities SET last_seen = ? "
+                        "WHERE entity_id = ? AND profile_id = ?",
+                        (ts, entity_id, profile_id),
+                    )
+            return len(batch)
+        except Exception:
+            # Best-effort: drop this batch rather than raise into a caller.
+            return 0
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._interval):
+            self.flush()
+
+    @property
+    def is_stopped(self) -> bool:
+        return self._stopped
+
+    def stop(self, timeout: float = 3.0) -> None:
+        """Flush then join the owner thread so it cannot outlive its database."""
+        self._stop.set()
+        self.flush()
+        if self._thread is not threading.current_thread():
+            self._thread.join(timeout=timeout)
+        self._stopped = not self._thread.is_alive()
+
+
+_registry: dict[int, DeferredLastSeen] = {}
+_registry_lock = threading.Lock()
+
+
+def get_deferred_last_seen(db) -> DeferredLastSeen:
+    """Return the process-wide DeferredLastSeen flusher for *db* (lazy singleton)."""
+    key = id(db)
+    with _registry_lock:
+        writer = _registry.get(key)
+        if writer is None or writer.is_stopped:
+            writer = DeferredLastSeen(db)
+            _registry[key] = writer
+        return writer
+
+
+def shutdown_deferred_writes(timeout: float = 3.0) -> None:
+    """Stop every deferred-write worker owned by this process.
+
+    This is intentionally idempotent: service shutdown and pytest cleanup can
+    both call it, and a later caller can lazily create fresh workers.
+    """
+    with _registry_lock:
+        writers = list(_registry.values())
+        _registry.clear()
+    for writer in writers:
+        writer.stop(timeout=timeout)
+    _shutdown_background_writer(timeout)
+
+
+atexit.register(shutdown_deferred_writes)
+
+
+__all__ = [
+    "DeferredLastSeen",
+    "get_deferred_last_seen",
+    "shutdown_deferred_writes",
+    "submit_background",
+]

package/src/superlocalmemory/storage/embedding_migrator.py

@@ -18,6 +18,8 @@ from __future__ import annotations
 
 import json
 import logging
+import os as _os
+import time
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -33,6 +35,16 @@ logger = logging.getLogger(__name__)
 #: Default batch size for backfill_missing_embeddings.
 _BACKFILL_BATCH_SIZE = 50
 
+#: Cooperative yield between per-fact writes in backfill_missing_embeddings.
+#: After every fact's UPDATE + INSERT pair, the write-back loop releases
+#: db._lock for this many seconds, giving concurrent user writes a guaranteed
+#: acquisition window.  Tunable via SLM_SELFHEAL_WRITE_DELAY_S; set to 0 to
+#: disable (only do this on single-user dev databases with no concurrency).
+#: Default 5 ms is imperceptible for humans but visible to the OS scheduler.
+_SELFHEAL_WRITE_DELAY_S: float = float(
+    _os.environ.get("SLM_SELFHEAL_WRITE_DELAY_S", "0.005")
+)
+
 #: Max characters embedded per fact during backfill. The embedding model
 #: (nomic-embed-text-v1.5) truncates at ~8192 tokens anyway, but a raw
 #: oversized document (observed up to 107 KB on a real DB) makes the shared
@@ -394,6 +406,13 @@ def backfill_missing_embeddings(
                     (fid, pid, current_model, current_dim),
                 )
                 embedded += 1
+                # Cooperative yield: release db._lock briefly so concurrent
+                # user writes can acquire it between facts.  Without this,
+                # the write-back loop holds db._lock in rapid succession
+                # (Python RLock has no fairness guarantee), potentially
+                # starving user POST /remember writes for seconds on large DBs.
+                if _SELFHEAL_WRITE_DELAY_S > 0:
+                    time.sleep(_SELFHEAL_WRITE_DELAY_S)
             except Exception as exc:
                 logger.warning(
                     "backfill: failed to write fact %s: %s", fid[:16], exc

package/src/superlocalmemory/storage/memory_write.py

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com
+
+"""Canonical short-lived WRITE / READ connections for memory.db.
+
+Why this exists
+---------------
+memory.db is a WAL SQLite database with exactly one writer allowed at any
+instant.  Historically many subsystems opened their own bare
+``sqlite3.connect(...)`` and wrote without any coordination, which produced
+two failure modes under real multi-agent load:
+
+1. **In-process races** — daemon worker threads racing each other at the WAL
+   layer, retrying ``SQLITE_BUSY`` until they time out.
+2. **Cross-process races** — Claude Code hooks and the ``slm ingest`` CLI run
+   as *separate OS processes* and write memory.db directly.  An in-process
+   ``threading`` lock cannot serialise those; only SQLite's own
+   ``PRAGMA busy_timeout`` makes them WAIT for the writer instead of erroring.
+
+``memory_write()`` closes BOTH gaps with one helper that every writer uses:
+
+* Acquires the process-level :func:`get_write_lock` (the OUTERMOST lock — see
+  ``write_lock.py``) so in-process writers serialise cleanly with **no**
+  ``SQLITE_BUSY`` spin.
+* Opens the connection with ``PRAGMA busy_timeout`` so that a *different
+  process* (hook / CLI) writing at the same instant WAITS rather than failing.
+* Commits on success, rolls back on error, always closes — a short critical
+  section.
+
+The single hard rule for callers
+---------------------------------
+**Never hold this connection across a slow operation** — no embedding /
+network call / large unbounded transaction inside the ``with`` block.  Do the
+slow work first, then open ``memory_write()`` only for the fast INSERT/UPDATE.
+Holding the writer across a multi-second op is exactly what starves everyone
+else (SQLITE_BUSY after retries).  Batch large writes into bounded chunks that
+each commit quickly.
+
+Reads
+-----
+Use :func:`memory_read` for read-only access.  WAL allows concurrent readers
+without blocking the writer, so reads do NOT take the write lock.  The helper
+opens SQLite with ``mode=ro`` and ``PRAGMA query_only=ON``; it uses the
+3.8.6 read-path budget of at most 250ms during a brief checkpoint window.
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator
+
+from superlocalmemory.storage.read_connection import ReadConnectionFactory
+from superlocalmemory.storage.write_lock import get_write_lock
+
+
+def _busy_timeout_ms() -> int:
+    """Busy-timeout in ms, env-overridable, matching DatabaseManager's default.
+
+    Kept in sync with ``storage/database.py::_BUSY_TIMEOUT_MS`` (env
+    ``SLM_DB_BUSY_TIMEOUT_MS``, default 10_000) so every memory.db connection
+    in the process — and in hook/CLI child processes that import this — waits
+    the same amount for the single writer.
+    """
+    try:
+        return max(0, int(os.environ.get("SLM_DB_BUSY_TIMEOUT_MS", "10000")))
+    except (TypeError, ValueError):
+        return 10000
+
+
+@contextmanager
+def memory_write(db_path: str | Path) -> Generator[sqlite3.Connection, None, None]:
+    """Yield a serialised, busy-timeout-guarded WRITE connection to memory.db.
+
+    Acquires the process write lock (outermost), opens a short-lived
+    connection with ``busy_timeout``, commits on success / rolls back on
+    error, and always closes.
+
+    HARD RULE: keep the ``with`` block short — never embed / call the network /
+    run an unbounded transaction while holding it.
+    """
+    ms = _busy_timeout_ms()
+    lock = get_write_lock(db_path)
+    with lock:
+        conn = sqlite3.connect(str(db_path), timeout=ms / 1000.0)
+        try:
+            conn.execute(f"PRAGMA busy_timeout={ms}")
+            conn.row_factory = sqlite3.Row
+            yield conn
+            conn.commit()
+        except Exception:
+            try:
+                conn.rollback()
+            except Exception:
+                pass
+            raise
+        finally:
+            conn.close()
+
+
+@contextmanager
+def memory_read(db_path: str | Path) -> Generator[sqlite3.Connection, None, None]:
+    """Yield a physically read-only connection with no write lock.
+
+    WAL permits concurrent readers, so this deliberately does NOT take the
+    write lock.  A 250ms bounded wait protects the query path from a brief
+    checkpoint without converting a dashboard recall into a long hang.
+    """
+    with ReadConnectionFactory(db_path, timeout_ms=min(_busy_timeout_ms(), 250)).snapshot() as conn:
+        yield conn
+
+
+__all__ = ["memory_write", "memory_read"]