superlocalmemory 3.8.3 → 3.8.5

package/src/superlocalmemory/storage/deferred_writes.py

@@ -0,0 +1,153 @@
+# 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 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()
+
+
+def _bg_run() -> None:
+    while True:
+        fn = _bg_queue.get()
+        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_started
+    if _bg_started:
+        return
+    with _bg_start_lock:
+        if _bg_started:
+            return
+        threading.Thread(
+            target=_bg_run, name="slm-bg-writer", daemon=True
+        ).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
+
+
+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._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()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self.flush()
+
+
+_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:
+            writer = DeferredLastSeen(db)
+            _registry[key] = writer
+        return writer
+
+
+__all__ = [
+    "DeferredLastSeen",
+    "get_deferred_last_seen",
+    "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,119 @@
+# 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 — but they
+still get ``busy_timeout`` for robustness during the 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.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 read-only-usage connection with ``busy_timeout`` (no write lock).
+
+    WAL permits concurrent readers, so this deliberately does NOT take the
+    write lock.  ``busy_timeout`` still applies so a read issued during the
+    brief WAL checkpoint window waits rather than erroring.
+    """
+    ms = _busy_timeout_ms()
+    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
+    finally:
+        conn.close()
+
+
+__all__ = ["memory_write", "memory_read"]

package/src/superlocalmemory/storage/migration_runner.py

@@ -122,6 +122,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M030_entity_explorer_indexes as _M030,
 )
+from superlocalmemory.storage.migrations import (
+    M031_dead_letter_operations as _M031,
+)
 
 # Map migration name → module (used for the optional ``verify(conn)`` hook
 # that lets the runner detect "already applied" state when an idempotent
@@ -156,6 +159,7 @@ _MODULES = {
     _M028.NAME: _M028,
     _M029.NAME: _M029,
     _M030.NAME: _M030,
+    _M031.NAME: _M031,
 }
 
 logger = logging.getLogger(__name__)
@@ -216,6 +220,9 @@ MIGRATIONS: list[Migration] = [
     Migration(name=_M024.NAME, db_target="memory", ddl=_M024.DDL),
     Migration(name=_M019.NAME, db_target="memory", ddl=_M019.DDL,
               dependencies=(_M018.NAME,)),
+    # M031 creates dead_letter_operations — standalone table, no FK to engine-
+    # bootstrapped tables, so it can run during apply_all (before engine init).
+    Migration(name=_M031.NAME, db_target="memory", ddl=_M031.DDL),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]
 

package/src/superlocalmemory/storage/migrations/M028_fact_entity_associations.py

@@ -101,17 +101,30 @@ def _now() -> str:
     return datetime.now(UTC).isoformat()
 
 
-def _connect(db_path: Path) -> sqlite3.Connection:
-    conn = sqlite3.connect(str(db_path), timeout=5)
+def _connect_read(db_path: Path) -> sqlite3.Connection:
+    """Read-only connection with system-default busy_timeout.
+
+    Concurrency fix (v3.8.4): busy_timeout raised from 5 s to match the
+    system default (10 s, env SLM_DB_BUSY_TIMEOUT_MS).  Timeout raised from
+    5 s to 10 s for the same reason.  Write connections now go through
+    memory_write() so they acquire get_write_lock() and never use this helper.
+    """
+    import os
+
+    try:
+        ms = max(0, int(os.environ.get("SLM_DB_BUSY_TIMEOUT_MS", "10000")))
+    except (TypeError, ValueError):
+        ms = 10000
+    conn = sqlite3.connect(str(db_path), timeout=ms / 1000.0)
     conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA busy_timeout=5000")
+    conn.execute(f"PRAGMA busy_timeout={ms}")
     conn.execute("PRAGMA foreign_keys=ON")
     return conn
 
 
 def get_repair_status(db_path: Path) -> dict[str, int | str]:
     """Read durable backfill progress without inferring it from schema."""
-    conn = _connect(Path(db_path))
+    conn = _connect_read(Path(db_path))
     try:
         row = conn.execute(
             "SELECT state,target_fact_rowid,last_fact_rowid,scanned,inserted,"
@@ -142,58 +155,70 @@ def _entity_ids(raw: object) -> tuple[str, ...]:
 
 
 def _repair_batch(conn: sqlite3.Connection, batch_size: int) -> dict[str, int | bool]:
-    conn.execute("BEGIN IMMEDIATE")
-    try:
-        status = conn.execute(
-            "SELECT last_fact_rowid,target_fact_rowid "
-            "FROM fact_entity_association_repair_state "
-            "WHERE repair_key='historical-backfill'"
-        ).fetchone()
-        cursor = int(status["last_fact_rowid"] or 0)
-        target = int(status["target_fact_rowid"])
-        rows = conn.execute(
-            "SELECT rowid,fact_id,profile_id,canonical_entities_json "
-            "FROM atomic_facts WHERE rowid>? AND rowid<=? "
-            "ORDER BY rowid LIMIT ?",
-            (cursor, target, batch_size),
-        ).fetchall()
-        if not rows:
-            conn.execute(
-                "UPDATE fact_entity_association_repair_state "
-                "SET state='complete',last_error='',updated_at=? "
-                "WHERE repair_key='historical-backfill'",
-                (_now(),),
-            )
-            conn.commit()
-            return {"scanned": 0, "inserted": 0, "complete": True}
-        inserted = 0
-        for row in rows:
-            for entity_id in _entity_ids(row["canonical_entities_json"]):
-                result = conn.execute(
-                    "INSERT OR IGNORE INTO fact_entity_associations "
-                    "(profile_id,fact_id,entity_id,first_operation_id,"
-                    "count_applied) "
-                    "SELECT ?,?,?,?,? FROM canonical_entities "
-                    "WHERE profile_id=? AND entity_id=?",
-                    (
-                        row["profile_id"], row["fact_id"], entity_id,
-                        "migration-backfill", 0,
-                        row["profile_id"], entity_id,
-                    ),
-                )
-                inserted += max(0, result.rowcount)
+    """Execute one backfill batch on *conn*.
+
+    Concurrency fix (v3.8.4): caller MUST hold the write lock via
+    memory_write() before calling this function.  The explicit
+    ``conn.execute("BEGIN IMMEDIATE")`` has been removed because:
+
+    * memory_write() already acquired get_write_lock() (Python-level
+      serialisation) — no other in-process writer can start.
+    * SQLite's implicit deferred transaction is promoted to a write
+      transaction on the first INSERT, which is equivalent to BEGIN
+      IMMEDIATE for in-process serialisation.
+    * The explicit BEGIN IMMEDIATE previously bypassed get_write_lock()
+      and would retry at the SQLite layer only (busy_timeout=5 s, now
+      10 s) without respecting the Python-level write lock order.
+
+    Transaction boundary (commit/rollback) is managed by memory_write().
+    """
+    status = conn.execute(
+        "SELECT last_fact_rowid,target_fact_rowid "
+        "FROM fact_entity_association_repair_state "
+        "WHERE repair_key='historical-backfill'"
+    ).fetchone()
+    if status is None:
+        return {"scanned": 0, "inserted": 0, "complete": True}
+    cursor = int(status["last_fact_rowid"] or 0)
+    target = int(status["target_fact_rowid"])
+    rows = conn.execute(
+        "SELECT rowid,fact_id,profile_id,canonical_entities_json "
+        "FROM atomic_facts WHERE rowid>? AND rowid<=? "
+        "ORDER BY rowid LIMIT ?",
+        (cursor, target, batch_size),
+    ).fetchall()
+    if not rows:
         conn.execute(
-            "UPDATE fact_entity_association_repair_state SET "
-            "state='running',last_fact_rowid=?,scanned=scanned+?,"
-            "inserted=inserted+?,last_error='',updated_at=? "
+            "UPDATE fact_entity_association_repair_state "
+            "SET state='complete',last_error='',updated_at=? "
             "WHERE repair_key='historical-backfill'",
-            (int(rows[-1]["rowid"]), len(rows), inserted, _now()),
+            (_now(),),
         )
-        conn.commit()
-        return {"scanned": len(rows), "inserted": inserted, "complete": False}
-    except Exception:
-        conn.rollback()
-        raise
+        return {"scanned": 0, "inserted": 0, "complete": True}
+    inserted = 0
+    for row in rows:
+        for entity_id in _entity_ids(row["canonical_entities_json"]):
+            result = conn.execute(
+                "INSERT OR IGNORE INTO fact_entity_associations "
+                "(profile_id,fact_id,entity_id,first_operation_id,"
+                "count_applied) "
+                "SELECT ?,?,?,?,? FROM canonical_entities "
+                "WHERE profile_id=? AND entity_id=?",
+                (
+                    row["profile_id"], row["fact_id"], entity_id,
+                    "migration-backfill", 0,
+                    row["profile_id"], entity_id,
+                ),
+            )
+            inserted += max(0, result.rowcount)
+    conn.execute(
+        "UPDATE fact_entity_association_repair_state SET "
+        "state='running',last_fact_rowid=?,scanned=scanned+?,"
+        "inserted=inserted+?,last_error='',updated_at=? "
+        "WHERE repair_key='historical-backfill'",
+        (int(rows[-1]["rowid"]), len(rows), inserted, _now()),
+    )
+    return {"scanned": len(rows), "inserted": inserted, "complete": False}
 
 
 def repair_fact_entity_associations(
@@ -202,34 +227,44 @@ def repair_fact_entity_associations(
     batch_size: int = 250,
     max_batches: int = 1,
 ) -> dict[str, int | bool]:
-    """Run bounded, restartable short-transaction backfill batches."""
+    """Run bounded, restartable short-transaction backfill batches.
+
+    Concurrency fix (v3.8.4): each batch is now wrapped in memory_write()
+    which acquires get_write_lock() (process-level write serialisation) and
+    sets the system-default busy_timeout (10 s) before opening the SQLite
+    connection.  Previously the loop used a single raw _connect() (timeout=5,
+    busy_timeout=5000) without get_write_lock(), which bypassed in-process
+    write serialisation and could cause SQLITE_BUSY after only 5 s.
+    """
+    from superlocalmemory.storage.memory_write import memory_write
+
     if batch_size < 1 or max_batches < 1:
         raise ValueError("batch_size and max_batches must be positive")
-    totals = {"scanned": 0, "inserted": 0, "complete": False}
-    conn = _connect(Path(db_path))
-    try:
-        for _ in range(max_batches):
-            result = _repair_batch(conn, batch_size)
-            totals["scanned"] += int(result["scanned"])
-            totals["inserted"] += int(result["inserted"])
-            totals["complete"] = bool(result["complete"])
-            if totals["complete"]:
-                break
-        return totals
-    except sqlite3.Error as exc:
+    totals: dict[str, int | bool] = {"scanned": 0, "inserted": 0, "complete": False}
+    for _ in range(max_batches):
         try:
-            conn.execute(
-                "UPDATE fact_entity_association_repair_state SET "
-                "state='retrying',last_error=?,updated_at=? "
-                "WHERE repair_key='historical-backfill'",
-                (type(exc).__name__, _now()),
-            )
-            conn.commit()
-        except sqlite3.Error:
-            pass
-        raise
-    finally:
-        conn.close()
+            with memory_write(Path(db_path)) as conn:
+                conn.execute("PRAGMA foreign_keys=ON")
+                result = _repair_batch(conn, batch_size)
+                totals["scanned"] += int(result["scanned"])
+                totals["inserted"] += int(result["inserted"])
+                totals["complete"] = bool(result["complete"])
+        except sqlite3.Error as exc:
+            # On error, record the retrying state in a separate short write.
+            try:
+                with memory_write(Path(db_path)) as econn:
+                    econn.execute(
+                        "UPDATE fact_entity_association_repair_state SET "
+                        "state='retrying',last_error=?,updated_at=? "
+                        "WHERE repair_key='historical-backfill'",
+                        (type(exc).__name__, _now()),
+                    )
+            except sqlite3.Error:
+                pass
+            raise
+        if totals["complete"]:
+            break
+    return totals
 
 
 def verify(conn: sqlite3.Connection) -> bool:

package/src/superlocalmemory/storage/migrations/M031_dead_letter_operations.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""M031 — dead-letter queue for exhausted ingestion operations (Fix E, issue #77).
+
+Additive migration: creates dead_letter_operations if not present.
+Existing rows in ingestion_operations are unaffected.
+
+When an M018 ingestion operation exhausts _MAX_AUTOMATIC_MATERIALIZATION_ATTEMPTS
+(10) it previously remained silently in FAILED state — invisible to operators and
+unreachable by the materialiser.  This table gives operators a persistent,
+inspectable record of every poisoned operation: original content, error, attempt
+count, timestamps, and profile scope.
+
+Schema design:
+  - original_op_id references ingestion_operations.operation_id (soft ref — no FK
+    so that dead-lettered rows survive if the source row is later cleaned up).
+  - profile_id allows per-profile DLQ dashboards.
+  - dead_lettered_at defaults to the current epoch for point-in-time auditing.
+  - No TTL/expiry here — retention policy belongs to a future maintenance sweep.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M031_dead_letter_operations"
+DB_TARGET = "memory"
+
+DDL = """
+CREATE TABLE IF NOT EXISTS dead_letter_operations (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+    original_op_id      TEXT NOT NULL,
+    operation_type      TEXT NOT NULL DEFAULT 'M018',
+    content             TEXT,
+    metadata_json       TEXT,
+    error               TEXT,
+    attempt_count       INTEGER,
+    first_attempt_at    REAL,
+    dead_lettered_at    REAL NOT NULL DEFAULT (unixepoch('now')),
+    profile_id          TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_dlq_profile
+    ON dead_letter_operations (profile_id);
+CREATE INDEX IF NOT EXISTS idx_dlq_op_id
+    ON dead_letter_operations (original_op_id);
+"""
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Create the dead_letter_operations table and indexes idempotently."""
+    conn.executescript(DDL)
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True only when the complete M031 contract is present."""
+    table = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' "
+        "AND name='dead_letter_operations'"
+    ).fetchone()
+    if table is None:
+        return False
+    columns = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA table_info(dead_letter_operations)"
+        ).fetchall()
+    }
+    required = {
+        "id",
+        "original_op_id",
+        "operation_type",
+        "content",
+        "error",
+        "attempt_count",
+        "dead_lettered_at",
+        "profile_id",
+    }
+    return required <= columns