superlocalmemory 3.8.14 → 4.0.0

package/src/superlocalmemory/storage/migration_runner.py

@@ -24,15 +24,17 @@ Hard rules enforced (LLD-07 §7):
   - MIG3: a failing migration does NOT prevent the runner from attempting
     the rest, and does NOT raise to the caller — result comes through the
     returned stats dict.
+
+The private apply-engine (``Migration``, the ``migration_log`` primitives,
+``_apply_single``, and the name→module registry) lives in
+``superlocalmemory.storage._migration_internals``; this module owns the ordered
+catalogue and the public orchestration functions.
 """
 
 from __future__ import annotations
 
-import hashlib
 import logging
 import sqlite3
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
 from pathlib import Path
 
 from superlocalmemory.storage.migrations import (
@@ -129,80 +131,46 @@ from superlocalmemory.storage.migrations import (
     M032_write_coordinator_admission as _M032,
 )
 from superlocalmemory.storage.migrations import (
-    M033_learning_feedback_channel as _M033,
-)
-from superlocalmemory.storage.migrations import (
-    M034_scene_fact_members as _M034,
-)
-
-# Map migration name → module (used for the optional ``verify(conn)`` hook
-# that lets the runner detect "already applied" state when an idempotent
-# retry would otherwise trigger duplicate-column / duplicate-table errors).
-_MODULES = {
-    _M001.NAME: _M001,
-    _M002.NAME: _M002,
-    _M003.NAME: _M003,
-    _M004.NAME: _M004,
-    _M005.NAME: _M005,
-    _M006.NAME: _M006,
-    _M007.NAME: _M007,
-    _M009.NAME: _M009,
-    _M010.NAME: _M010,
-    _M011.NAME: _M011,
-    _M012.NAME: _M012,
-    _M013.NAME: _M013,
-    _M014.NAME: _M014,
-    _M015.NAME: _M015,
-    _M016.NAME: _M016,
-    _M017.NAME: _M017,
-    _M018.NAME: _M018,
-    _M019.NAME: _M019,
-    _M020.NAME: _M020,
-    _M021.NAME: _M021,
-    _M022.NAME: _M022,
-    _M023.NAME: _M023,
-    _M024.NAME: _M024,
-    _M025.NAME: _M025,
-    _M026.NAME: _M026,
-    _M027.NAME: _M027,
-    _M028.NAME: _M028,
-    _M029.NAME: _M029,
-    _M030.NAME: _M030,
-    _M031.NAME: _M031,
-    _M032.NAME: _M032,
-    _M033.NAME: _M033,
-    _M034.NAME: _M034,
-}
+    M033_projection_transactions as _M033,
+)
+from superlocalmemory.storage.migrations import (
+    M034_obligation_integrity as _M034,
+)
+from superlocalmemory.storage.migrations import (
+    M035_erasure_receipts as _M035,
+)
+from superlocalmemory.storage.migrations import (
+    M036_vector_row_map as _M036,
+)
+from superlocalmemory.storage.migrations import (
+    M037_manifest_hmac_version as _M037,
+)
+from superlocalmemory.storage.migrations import (
+    M038_learning_feedback_channel as _M038,
+)
+from superlocalmemory.storage.migrations import (
+    M039_scene_fact_members as _M039,
+)
+from superlocalmemory.storage._schema_version import (
+    SUPPORTED_SCHEMA_VERSION,
+    SchemaVersionError,
+    check_version_or_raise as _check_version_or_raise,
+    ensure_schema_version_table as _ensure_schema_version_table,
+    write_schema_version as _write_schema_version,
+)
+from superlocalmemory.storage._migration_internals import (
+    Migration,
+    _MODULES,  # noqa: F401 — re-exported for test/introspection compatibility
+    _apply_single,
+    _connect,
+    _db_for,
+    _ensure_migration_log,
+    _migration_log_exists,
+    _read_log,
+)
 
 logger = logging.getLogger(__name__)
 
-# Exact historical DDL fingerprints whose resulting schema is intentionally
-# accepted by the current migration. Unknown hashes are never reconciled.
-_KNOWN_EQUIVALENT_DDL_HASHES: dict[str, frozenset[str]] = {
-    _M002.NAME: frozenset({
-        # v3.4.21 hardened copy-forward variant.
-        "347eeb2ec8aac89f7cbf373da49ac9446be9ed150e6105c382c656cd22426d4b",
-        # v3.4.22 model_version-default variant shipped through 3.6.x.
-        "d28666fa1dfa66e6514efd288e6748363513da2255a4cee95d80f233e6728ae7",
-    }),
-    _M032.NAME: frozenset({
-        # Provisional 3.8.6 development ledger: global idempotency_key and
-        # operation_id uniqueness. Its standalone table is safely rebuilt by
-        # M032.repair() into the profile-scoped receipt contract.
-        "e45df41becba3d0c3342eca5ec3bd83aa899eef76943c819d2da73b4ca1625a7",
-    }),
-}
-
-
-@dataclass(frozen=True, slots=True)
-class Migration:
-    """Single migration definition."""
-
-    name: str
-    db_target: str  # 'learning' or 'memory'
-    ddl: str
-    dependencies: tuple[str, ...] = field(default_factory=tuple)
-
 
 # Order matters: M003 creates the log table. The runner handles M003's own
 # bootstrap (it can't record itself before it exists).
@@ -228,11 +196,6 @@ MIGRATIONS: list[Migration] = [
     # observations for ShadowTest persistence across daemon restart.
     Migration(name=_M012.NAME, db_target="learning", ddl=_M012.DDL,
               dependencies=(_M003.NAME,)),
-    # M033 adds learning_feedback.channel, which pattern_miner has always
-    # queried but which no schema ever defined. Its DDL creates the table
-    # when absent, so it needs no dependency beyond the migration log.
-    Migration(name=_M033.NAME, db_target="learning", ddl=_M033.DDL,
-              dependencies=(_M003.NAME,)),
     Migration(name=_M004.NAME, db_target="memory", ddl=_M004.DDL),
     # M007 creates pending_outcomes (memory.db, LLD-00 §1.2).
     Migration(name=_M007.NAME, db_target="memory", ddl=_M007.DDL),
@@ -249,6 +212,20 @@ MIGRATIONS: list[Migration] = [
     # M032 is standalone and must precede daemon readiness: typed writes use
     # this append-only receipt ledger for durable idempotency.
     Migration(name=_M032.NAME, db_target="memory", ddl=_M032.DDL),
+    Migration(name=_M033.NAME, db_target="memory", ddl=_M033.DDL),
+    Migration(name=_M034.NAME, db_target="memory", ddl=_M034.DDL,
+              dependencies=(_M033.NAME,)),
+    Migration(name=_M035.NAME, db_target="memory", ddl=_M035.DDL,
+              dependencies=(_M033.NAME,)),
+    Migration(name=_M036.NAME, db_target="memory", ddl=_M036.DDL,
+              dependencies=(_M033.NAME,)),
+    Migration(name=_M037.NAME, db_target="memory", ddl=_M037.DDL,
+              dependencies=(_M033.NAME, _M035.NAME)),
+    # Main-line M033 is renumbered in V4 because V4 already owns M033-M037.
+    # It repairs the legacy learning_feedback schema before any reader mines
+    # channel patterns.
+    Migration(name=_M038.NAME, db_target="learning", ddl=_M038.DDL,
+              dependencies=(_M003.NAME,)),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]
 
@@ -309,336 +286,12 @@ DEFERRED_MIGRATIONS: list[Migration] = [
     Migration(name=_M029.NAME, db_target="memory", ddl=_M029.DDL),
     # M030 bounds Entity Explorer pagination and profile-summary ranking.
     Migration(name=_M030.NAME, db_target="memory", ddl=_M030.DDL),
-    # M034 normalizes memory_scenes.fact_ids_json after engine initialization
-    # has created memory_scenes and atomic_facts.
-    Migration(name=_M034.NAME, db_target="memory", ddl=_M034.DDL),
+    # Main-line M034 is renumbered in V4. It must remain deferred because its
+    # backfill joins engine-bootstrapped memory_scenes and atomic_facts.
+    Migration(name=_M039.NAME, db_target="memory", ddl=_M039.DDL),
 ]
 
 
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _ddl_hash(ddl: str) -> str:
-    return hashlib.sha256(ddl.encode("utf-8")).hexdigest()
-
-
-def _connect(db_path: Path) -> sqlite3.Connection:
-    # isolation_level=None → we manage transactions explicitly via DDL.
-    conn = sqlite3.connect(db_path, isolation_level=None)
-    conn.execute("PRAGMA foreign_keys = OFF;")
-    return conn
-
-
-def _migration_log_exists(conn: sqlite3.Connection) -> bool:
-    row = conn.execute(
-        "SELECT name FROM sqlite_master "
-        "WHERE type='table' AND name='migration_log'"
-    ).fetchone()
-    return row is not None
-
-
-def _ensure_migration_log(conn: sqlite3.Connection) -> None:
-    """Bootstrap the migration_log table on a DB if absent.
-
-    Uses the M003 DDL verbatim so the runner treats migration_log identically
-    on both learning.db and memory.db.
-    """
-    conn.executescript(_M003.DDL)
-
-
-def _get_log_row(conn: sqlite3.Connection, name: str) -> tuple | None:
-    return conn.execute(
-        "SELECT name, applied_at, ddl_sha256, rows_affected, status "
-        "FROM migration_log WHERE name = ?",
-        (name,),
-    ).fetchone()
-
-
-def _upsert_log(
-    conn: sqlite3.Connection,
-    name: str,
-    ddl_hash: str,
-    status: str,
-    rows_affected: int = 0,
-) -> None:
-    conn.execute(
-        "INSERT INTO migration_log "
-        "(name, applied_at, ddl_sha256, rows_affected, status) "
-        "VALUES (?, ?, ?, ?, ?) "
-        "ON CONFLICT(name) DO UPDATE SET "
-        "    applied_at = excluded.applied_at, "
-        "    ddl_sha256 = excluded.ddl_sha256, "
-        "    rows_affected = excluded.rows_affected, "
-        "    status = excluded.status",
-        (name, _now_iso(), ddl_hash, rows_affected, status),
-    )
-
-
-def _delete_log(conn: sqlite3.Connection, name: str) -> None:
-    conn.execute("DELETE FROM migration_log WHERE name = ?", (name,))
-
-
-def _apply_single(
-    conn: sqlite3.Connection,
-    migration: Migration,
-    *,
-    dry_run: bool,
-) -> tuple[str, str]:
-    """Apply one migration against ``conn``.
-
-    Returns (outcome, detail) where outcome is one of:
-      - "applied"
-      - "skipped"
-      - "failed"
-    """
-    ddl_hash = _ddl_hash(migration.ddl)
-
-    # Bootstrap: if migration_log doesn't exist yet, this MUST be M003.
-    if not _migration_log_exists(conn):
-        if migration.name != _M003.NAME:
-            # Other migrations can't check state → treat as unrecoverable here.
-            return ("failed",
-                    f"migration_log missing when attempting {migration.name}")
-        if dry_run:
-            return ("skipped", "dry-run: would create migration_log")
-        try:
-            _ensure_migration_log(conn)
-            _upsert_log(conn, migration.name, ddl_hash, "complete")
-            return ("applied", "bootstrapped migration_log")
-        except sqlite3.Error as exc:  # pragma: no cover — defensive
-            logger.warning("M003 bootstrap failed: %s", exc)
-            return ("failed", f"bootstrap error: {exc}")
-
-    # M003 specifically — if log already exists, ensure M003's own row is there
-    # (records the fact that the table was bootstrapped previously).
-    existing = _get_log_row(conn, migration.name)
-
-    if existing is not None:
-        _, _, logged_hash, _, status = existing
-        if status == "complete":
-            if logged_hash != ddl_hash:
-                # v3.7.6 (#70): a complete migration whose logged DDL hash no
-                # longer matches the current text is only a real failure if the
-                # schema it guarantees is actually absent. Historically-benign
-                # DDL edits (e.g. M002's V3.4.21 <-> S9-W1 variants that build the
-                # identical end-state) would otherwise brick readiness forever on
-                # upgrade. Consult the migration's own verify(); if the schema is
-                # in place, reconcile the log to the current hash and treat as
-                # already-applied instead of failing the daemon into permanent
-                # not_ready. Absent/failing verify keeps the hard failure.
-                allowed_hashes = _KNOWN_EQUIVALENT_DDL_HASHES.get(
-                    migration.name, frozenset(),
-                )
-                mod = _MODULES.get(migration.name)
-                verify_fn = (
-                    getattr(mod, "verify", None) if mod is not None else None
-                )
-                if logged_hash in allowed_hashes and verify_fn is not None:
-                    try:
-                        if verify_fn(conn):
-                            if not dry_run:
-                                try:
-                                    _upsert_log(
-                                        conn, migration.name, ddl_hash, "complete"
-                                    )
-                                except sqlite3.Error:  # pragma: no cover
-                                    pass
-                            return (
-                                "skipped",
-                                "allowlisted historical DDL reconciled after "
-                                "full schema verification",
-                            )
-                    except sqlite3.Error:  # pragma: no cover
-                        pass
-                    if dry_run:
-                        return (
-                            "skipped",
-                            "dry-run: would repair allowlisted historical schema",
-                        )
-                    repair_fn = getattr(mod, "repair", None) if mod is not None else None
-                    if callable(repair_fn):
-                        try:
-                            repair_fn(conn)
-                            if not bool(verify_fn(conn)):
-                                return (
-                                    "failed",
-                                    f"safe repair did not restore {migration.name}",
-                                )
-                            _upsert_log(conn, migration.name, ddl_hash, "complete")
-                            return (
-                                "applied",
-                                "allowlisted historical schema repaired safely",
-                            )
-                        except sqlite3.Error as exc:
-                            return (
-                                "failed",
-                                f"safe repair failed for {migration.name}: {exc}",
-                            )
-                detail = (
-                    f"DDL drift detected for {migration.name}: "
-                    f"logged={logged_hash[:8]}... current={ddl_hash[:8]}..."
-                )
-                logger.warning(detail)
-                return ("failed", detail)
-            # A matching migration-log row is not proof that the promised
-            # schema still exists. Existing installs can retain a migration log
-            # while a partial restore drops an additive table or index.
-            #
-            # Never replay a historical migration merely because verify()
-            # fails. Some migrations rebuild tables and transform data; replay
-            # would be destructive (M002 is the canonical example). Only a
-            # module-supplied repair(conn) hook is allowed to reconcile a
-            # completed migration's end-state.
-            mod = _MODULES.get(migration.name)
-            verify_fn = (
-                getattr(mod, "verify", None) if mod is not None else None
-            )
-            if verify_fn is None:
-                return ("skipped", "already complete")
-            try:
-                schema_complete = bool(verify_fn(conn))
-            except sqlite3.Error as exc:
-                return (
-                    "failed",
-                    f"schema verification failed for {migration.name}: {exc}",
-                )
-            if schema_complete:
-                return ("skipped", "already complete (schema verified)")
-            if dry_run:
-                return (
-                    "skipped",
-                    "dry-run: would repair missing migration end-state",
-                )
-            repair_fn = (
-                getattr(mod, "repair", None) if mod is not None else None
-            )
-            if not callable(repair_fn):
-                detail = (
-                    f"schema incomplete for completed migration "
-                    f"{migration.name}; automatic replay is disabled"
-                )
-                logger.warning(detail)
-                return ("failed", detail)
-            try:
-                repair_fn(conn)
-            except sqlite3.Error as exc:
-                return (
-                    "failed",
-                    f"safe repair failed for {migration.name}: {exc}",
-                )
-            try:
-                if not bool(verify_fn(conn)):
-                    return (
-                        "failed",
-                        f"safe repair did not restore {migration.name}",
-                    )
-            except sqlite3.Error as exc:
-                return (
-                    "failed",
-                    f"post-repair verification failed for "
-                    f"{migration.name}: {exc}",
-                )
-            return ("applied", "missing end-state repaired safely")
-        # status is 'failed' or 'in_progress' → retry from scratch.
-        if dry_run:
-            return ("skipped", f"dry-run: would retry (status={status})")
-        try:
-            _delete_log(conn, migration.name)
-        except sqlite3.Error as exc:  # pragma: no cover — log table exists
-            return ("failed", f"cannot clear prior log: {exc}")
-
-    if dry_run:
-        return ("skipped", "dry-run: would apply")
-
-    # Mark in_progress, execute, update status. If DDL fails we roll our log
-    # entry to 'failed' so next attempt will retry cleanly.
-    try:
-        _upsert_log(conn, migration.name, ddl_hash, "in_progress")
-    except sqlite3.Error as exc:  # pragma: no cover
-        return ("failed", f"cannot record in_progress: {exc}")
-
-    try:
-        # A migration module may ship a custom apply(conn) for conditional logic
-        # that static DDL can't express (e.g. SQLite has no ADD COLUMN IF NOT
-        # EXISTS, and ALTER on a missing/already-altered table can't be guarded
-        # in one executescript). If present, it runs instead of the DDL string;
-        # otherwise the DDL is applied as before. Pure-DDL migrations are
-        # unaffected.
-        _mod = _MODULES.get(migration.name)
-        _apply_fn = getattr(_mod, "apply", None) if _mod is not None else None
-        if callable(_apply_fn):
-            _apply_fn(conn)
-        else:
-            conn.executescript(migration.ddl)
-    except sqlite3.Error as exc:
-        # Best-effort rollback.
-        try:
-            conn.execute("ROLLBACK")
-        except sqlite3.Error:  # pragma: no cover — best-effort
-            pass
-        # Before marking failed, check if the migration's end-state is
-        # already in place (e.g. crash-recovery retry against a DB where the
-        # columns were added in a previous partial apply). If so, this is
-        # effectively a successful idempotent re-run.
-        mod = _MODULES.get(migration.name)
-        verify_fn = getattr(mod, "verify", None) if mod is not None else None
-        if verify_fn is not None:
-            try:
-                if verify_fn(conn):
-                    try:
-                        _upsert_log(conn, migration.name, ddl_hash, "complete")
-                    except sqlite3.Error:  # pragma: no cover
-                        pass
-                    return ("applied",
-                            "already applied (verified via schema inspection)")
-            except sqlite3.Error:  # pragma: no cover
-                pass
-
-        logger.warning("Migration %s failed: %s", migration.name, exc)
-        try:
-            _upsert_log(conn, migration.name, ddl_hash, "failed")
-        except sqlite3.Error:  # pragma: no cover
-            pass
-        return ("failed", f"{type(exc).__name__}: {exc}")
-
-    # S9-W1 H-DATA-01: optional post-DDL Python hook. Runs inside the same
-    # connection (same DB file) after the DDL commits. Used by M002 to
-    # backfill ``bytes_sha256`` on rows copied forward by the new-table
-    # rename. If the hook raises, the migration is marked failed; the DDL
-    # is NOT rolled back (already committed) but the runner reports the
-    # problem so operators can intervene. Non-existent hooks are a no-op.
-    mod = _MODULES.get(migration.name)
-    post_hook = getattr(mod, "post_ddl_hook", None) if mod is not None else None
-    if post_hook is not None:
-        try:
-            post_hook(conn)
-        except Exception as exc:  # noqa: BLE001 — report + mark failed
-            logger.warning(
-                "Migration %s DDL applied but post_ddl_hook failed: %s",
-                migration.name, exc,
-            )
-            try:
-                _upsert_log(conn, migration.name, ddl_hash, "failed")
-            except sqlite3.Error:  # pragma: no cover
-                pass
-            return ("failed", f"post_ddl_hook: {type(exc).__name__}: {exc}")
-
-    try:
-        _upsert_log(conn, migration.name, ddl_hash, "complete")
-    except sqlite3.Error as exc:  # pragma: no cover
-        return ("failed", f"cannot record complete: {exc}")
-    return ("applied", "ok")
-
-
-def _db_for(target: str, learning_db: Path, memory_db: Path) -> Path:
-    if target == "learning":
-        return learning_db
-    if target == "memory":
-        return memory_db
-    raise ValueError(f"unknown db_target: {target}")  # pragma: no cover
-
-
 def _bootstrap_both_migration_logs(
     learning_db: Path, memory_db: Path, *, dry_run: bool,
 ) -> tuple[list[str], dict[str, str]]:
@@ -712,7 +365,17 @@ def apply_all(
 
     Idempotent: already-applied migrations are skipped. Non-fatal: any
     migration that fails is recorded in ``failed`` and the runner moves on.
+
+    Raises SchemaVersionError before touching any data when the learning DB
+    reports a schema_version that exceeds SUPPORTED_SCHEMA_VERSION.  This
+    prevents silent data corruption when downgrading to an older build.
     """
+    # Non-mutating version check: must run before any write. Both managed
+    # databases are validated so a downgrade is detectable regardless of which
+    # store carries the newer stamp.
+    _check_version_or_raise(learning_db)
+    _check_version_or_raise(memory_db)
+
     applied: list[str] = []
     skipped: list[str] = []
     failed: list[str] = []
@@ -736,7 +399,17 @@ def apply_all(
     failed.extend(bs_failed)
     details.update(bs_details)
 
+    blocked: set[str] = set()
     for migration in MIGRATIONS:
+        # A migration whose declared dependency did not complete must not run
+        # against a base schema that is missing that dependency's changes.
+        unmet = [d for d in migration.dependencies if d in failed or d in blocked]
+        if unmet:
+            skipped.append(migration.name)
+            blocked.add(migration.name)
+            details[migration.name] = "dependency not satisfied: " + ", ".join(unmet)
+            continue
+
         db_path = _db_for(migration.db_target, learning_db, memory_db)
         try:
             conn = _connect(db_path)
@@ -785,13 +458,32 @@ def apply_deferred(
     table is still missing, the underlying DDL raises ``no such table`` and
     the migration is recorded as ``failed`` — safe, the trainer already
     falls back to the position proxy when M006 hasn't completed.
+
+    Raises SchemaVersionError before touching any data when either managed
+    database reports a schema_version newer than SUPPORTED_SCHEMA_VERSION. This
+    path runs after engine init, so it must fail closed on a downgrade exactly
+    as ``apply_all`` does rather than write DDL an older build cannot interpret.
     """
+    # Non-mutating downgrade guard: must run before any write, mirroring
+    # apply_all. Both managed databases are validated so a newer stamp on
+    # either store halts the deferred pass.
+    _check_version_or_raise(learning_db)
+    _check_version_or_raise(memory_db)
+
     applied: list[str] = []
     skipped: list[str] = []
     failed: list[str] = []
     details: dict[str, str] = {}
 
+    blocked: set[str] = set()
     for migration in DEFERRED_MIGRATIONS:
+        unmet = [d for d in migration.dependencies if d in failed or d in blocked]
+        if unmet:
+            skipped.append(migration.name)
+            blocked.add(migration.name)
+            details[migration.name] = "dependency not satisfied: " + ", ".join(unmet)
+            continue
+
         db_path = _db_for(migration.db_target, learning_db, memory_db)
         try:
             conn = _connect(db_path)
@@ -831,6 +523,46 @@ def apply_deferred(
             except sqlite3.Error:  # pragma: no cover
                 pass
 
+    # The version ceiling is a completion certificate, not an intent marker.
+    # M039 is deferred until engine-owned tables exist, so apply_all must not
+    # stamp version 39. Stamp both stores only after every eager and deferred
+    # migration is recorded complete on its declared target.
+    if not failed and not dry_run:
+        logs = {
+            "learning": _read_log(learning_db),
+            "memory": _read_log(memory_db),
+        }
+        incomplete = [
+            migration.name
+            for migration in (*MIGRATIONS, *DEFERRED_MIGRATIONS)
+            if logs[migration.db_target].get(migration.name) != "complete"
+        ]
+        if incomplete:
+            failed.append("schema_version_stamp")
+            details["schema_version_stamp"] = (
+                "not stamped; incomplete migrations: " + ", ".join(incomplete)
+            )
+        else:
+            for _stamp_db in (learning_db, memory_db):
+                try:
+                    _stamp_conn = _connect(_stamp_db)
+                    try:
+                        _ensure_schema_version_table(_stamp_conn)
+                        _write_schema_version(
+                            _stamp_conn, SUPPORTED_SCHEMA_VERSION,
+                        )
+                    finally:
+                        try:
+                            _stamp_conn.close()
+                        except sqlite3.Error:  # pragma: no cover
+                            pass
+                except sqlite3.Error as exc:  # pragma: no cover
+                    failed.append("schema_version_stamp")
+                    details["schema_version_stamp"] = (
+                        f"cannot stamp {_stamp_db}: {exc}"
+                    )
+                    break
+
     return {
         "applied": applied,
         "skipped": skipped,
@@ -858,28 +590,12 @@ def status(learning_db: Path, memory_db: Path) -> dict[str, str]:
     return out
 
 
-def _read_log(db_path: Path) -> dict[str, str]:
-    try:
-        conn = sqlite3.connect(db_path)
-    except sqlite3.Error:  # pragma: no cover
-        return {}
-    try:
-        if not _migration_log_exists(conn):
-            return {}
-        rows = conn.execute(
-            "SELECT name, status FROM migration_log"
-        ).fetchall()
-        return {name: status for (name, status) in rows}
-    except sqlite3.Error:  # pragma: no cover
-        return {}
-    finally:
-        conn.close()
-
-
 __all__ = (
     "Migration",
     "MIGRATIONS",
     "DEFERRED_MIGRATIONS",
+    "SUPPORTED_SCHEMA_VERSION",
+    "SchemaVersionError",
     "apply_all",
     "apply_deferred",
     "status",