superlocalmemory 3.8.0 → 3.8.2

package/src/superlocalmemory/storage/embedding_migrator.py

@@ -26,6 +26,23 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# Backfill constants
+# ---------------------------------------------------------------------------
+
+#: Default batch size for backfill_missing_embeddings.
+_BACKFILL_BATCH_SIZE = 50
+
+#: 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
+#: single-worker embedder busy for 15-20s on ONE fact — starving foreground
+#: recall during a self-heal pass. Bounding the input keeps every fact's embed
+#: fast and the worker responsive; the leading slice captures the fact's gist
+#: for semantic recall. Facts this large are documents that were almost
+#: certainly NULL because they failed to embed at ingestion for the same reason.
+_MAX_EMBED_CHARS = 8000
+
 # Sentinel stored in config.json when no model has been set yet.
 _NO_MODEL = ""
 
@@ -44,6 +61,24 @@ def _model_signature(config: SLMConfig) -> str:
     return f"{emb.model_name}::{emb.dimension}"
 
 
+def _normalize_signature(signature: str) -> str:
+    """Normalize a signature for equivalence comparison.
+
+    v3.8.2 self-healing: the SAME embedding model has been recorded under
+    different name strings across releases — notably the HuggingFace org
+    prefix drifted (``nomic-ai/nomic-embed-text-v1.5`` vs the bare
+    ``nomic-embed-text-v1.5``). A prefix-only difference does NOT change the
+    embedding vector space, so it must not trigger a full multi-hour re-embed
+    when a non-technical user upgrades. This collapses the model name to its
+    basename (segment after the last ``/``) while keeping the ``::dimension``
+    suffix — a genuine model change (different basename OR dimension) still
+    differs and still triggers migration.
+    """
+    model, sep, dim = signature.partition("::")
+    model = model.rsplit("/", 1)[-1].strip()
+    return f"{model}{sep}{dim}" if sep else model
+
+
 def _read_stored_signature(config_dir: Path) -> str:
     """Read the last-used embedding model signature from config.json."""
     config_path = config_dir / "config.json"
@@ -88,6 +123,19 @@ def check_embedding_migration(config: SLMConfig) -> bool:
     if stored_sig == current_sig:
         return False
 
+    # v3.8.2 self-healing: a prefix-only model-name drift (e.g. the nomic-ai/
+    # org prefix appearing/disappearing between releases) is the SAME vector
+    # space — absorb the transition by refreshing the stored signature to the
+    # current form, with NO re-embed. This spares non-technical users a
+    # multi-hour full re-index on a cosmetic upgrade.
+    if _normalize_signature(stored_sig) == _normalize_signature(current_sig):
+        _write_stored_signature(config.base_dir, current_sig)
+        logger.info(
+            "Embedding signature normalized (no re-embed): %s ~= %s",
+            stored_sig, current_sig,
+        )
+        return False
+
     logger.warning(
         "Embedding model changed: %s -> %s. Re-indexing required.",
         stored_sig, current_sig,
@@ -177,3 +225,190 @@ def run_embedding_migration(
         reindexed, total,
     )
     return reindexed
+
+
+# ---------------------------------------------------------------------------
+# Backfill: embed facts that were NEVER embedded (embedding IS NULL)
+# ---------------------------------------------------------------------------
+
+def _count_null_embeddings(
+    db: Any,
+    profile_id: str,
+    all_profiles: bool,
+) -> int:
+    """Return count of atomic_facts rows with NULL embedding."""
+    if all_profiles:
+        rows = db.execute(
+            "SELECT count(*) AS c FROM atomic_facts WHERE embedding IS NULL",
+        )
+    else:
+        rows = db.execute(
+            "SELECT count(*) AS c FROM atomic_facts "
+            "WHERE embedding IS NULL AND profile_id = ?",
+            (profile_id,),
+        )
+    return int(rows[0]["c"]) if rows else 0
+
+
+def backfill_missing_embeddings(
+    config: "SLMConfig",
+    db: Any,
+    embedder: Any,
+    batch_size: int = _BACKFILL_BATCH_SIZE,
+    limit: int | None = None,
+    all_profiles: bool = False,
+) -> dict[str, int]:
+    """Embed atomic_facts rows whose ``embedding`` column is NULL.
+
+    Unlike :func:`run_embedding_migration` (which re-embeds on model-signature
+    change), this function handles facts that were *never* embedded — for
+    example facts stored while the embedder was unavailable.
+
+    Resumable and idempotent: re-running after a partial run only processes
+    the remaining NULLs.  Fail-open per-fact: a single bad fact logs a warning
+    and is skipped; the batch continues.
+
+    Writes mirror :func:`run_embedding_migration` exactly:
+    * ``atomic_facts.embedding`` ← ``json.dumps(vector)``
+    * ``embedding_metadata`` ← upserted row with current model name + dimension
+
+    Args:
+        config: Active SLMConfig (provides profile_id, model name, dimension).
+        db: DatabaseManager (or duck-compatible object with ``.execute()``).
+        embedder: Object implementing ``embed_batch(texts) -> list[vec|None]``
+            and (optionally) ``embed(text) -> vec|None``.  Pass ``None`` to
+            make this a no-op (returns zero counts).
+        batch_size: Facts per embed_batch() call.  Defaults to 50.
+        limit: Maximum facts to embed in this call.  ``None`` means no cap —
+            all NULL-embedding facts are processed.  Use a bounded limit for
+            the maintenance self-healing path so each pass is quick.
+        all_profiles: When ``True``, processes facts from every profile in the
+            database.  When ``False`` (default), scopes to
+            ``config.active_profile``.
+
+    Returns:
+        ``{"scanned": int, "embedded": int, "remaining_null": int}``
+
+        *scanned*: total NULL-embedding facts found before applying *limit*.
+        *embedded*: facts successfully written in this call.
+        *remaining_null*: NULL count after the call (includes facts not yet
+            reached because of *limit*).
+    """
+    profile_id = config.active_profile
+
+    if embedder is None:
+        logger.warning(
+            "backfill_missing_embeddings: no embedder available — skipping."
+        )
+        return {"scanned": 0, "embedded": 0, "remaining_null": 0}
+
+    # ------------------------------------------------------------------
+    # 1. Fetch all NULL-embedding facts (cheap query; only reads IDs + content)
+    # ------------------------------------------------------------------
+    if all_profiles:
+        rows = db.execute(
+            "SELECT fact_id, content, profile_id FROM atomic_facts "
+            "WHERE embedding IS NULL ORDER BY created_at",
+        )
+    else:
+        rows = db.execute(
+            "SELECT fact_id, content, profile_id FROM atomic_facts "
+            "WHERE embedding IS NULL AND profile_id = ? ORDER BY created_at",
+            (profile_id,),
+        )
+
+    facts: list[tuple[str, str, str]] = [
+        (dict(r)["fact_id"], dict(r)["content"], dict(r)["profile_id"])
+        for r in rows
+    ]
+    scanned = len(facts)
+
+    if scanned == 0:
+        return {"scanned": 0, "embedded": 0, "remaining_null": 0}
+
+    # Apply call-level limit (resumability: next call picks up where this left off)
+    if limit is not None:
+        facts = facts[:limit]
+
+    current_model = config.embedding.model_name
+    current_dim = config.embedding.dimension
+    embedded = 0
+
+    # ------------------------------------------------------------------
+    # 2. Batch embed and write back
+    # ------------------------------------------------------------------
+    for batch_start in range(0, len(facts), batch_size):
+        batch = facts[batch_start : batch_start + batch_size]
+        # Bound per-fact input so an oversized document doesn't monopolize the
+        # shared embedding worker (starving foreground recall during self-heal).
+        texts = [(content or "")[:_MAX_EMBED_CHARS] for _, content, _ in batch]
+        fact_ids = [fid for fid, _, _ in batch]
+        prof_ids = [pid for _, _, pid in batch]
+
+        # Attempt batch embed; fall back to per-fact on batch failure.
+        try:
+            vectors: list[Any] = embedder.embed_batch(texts)
+        except Exception as exc:
+            logger.warning(
+                "backfill: batch embed failed for facts %d-%d: %s — "
+                "retrying per-fact.",
+                batch_start,
+                batch_start + len(batch),
+                exc,
+            )
+            vectors = []
+            for text in texts:
+                try:
+                    vec = embedder.embed(text)
+                    vectors.append(vec)
+                except Exception as per_fact_exc:
+                    logger.warning(
+                        "backfill: per-fact embed failed for '%s...': %s",
+                        text[:40],
+                        per_fact_exc,
+                    )
+                    vectors.append(None)
+
+        # Write each successfully-embedded fact back to the DB.
+        for fid, vec, pid in zip(fact_ids, vectors, prof_ids):
+            if vec is None:
+                logger.warning(
+                    "backfill: null vector for fact %s — skipping.", fid[:16]
+                )
+                continue
+            try:
+                embedding_json = json.dumps(vec)
+                # Mirror run_embedding_migration's write path exactly.
+                db.execute(
+                    "UPDATE atomic_facts SET embedding = ? WHERE fact_id = ?",
+                    (embedding_json, fid),
+                )
+                # Upsert embedding_metadata.  NULL-embedding facts have no row
+                # here yet, so we INSERT; if a row somehow exists, update it.
+                db.execute(
+                    "INSERT INTO embedding_metadata"
+                    "    (fact_id, profile_id, model_name, dimension)"
+                    " VALUES (?, ?, ?, ?)"
+                    " ON CONFLICT(fact_id) DO UPDATE SET"
+                    "    model_name = excluded.model_name",
+                    (fid, pid, current_model, current_dim),
+                )
+                embedded += 1
+            except Exception as exc:
+                logger.warning(
+                    "backfill: failed to write fact %s: %s", fid[:16], exc
+                )
+
+    # ------------------------------------------------------------------
+    # 3. Count remaining NULLs (accounts for the limit; tells caller how
+    #    many passes remain before full convergence).
+    # ------------------------------------------------------------------
+    remaining = _count_null_embeddings(db, profile_id, all_profiles)
+
+    logger.info(
+        "Embedding backfill: %d/%d facts embedded, %d remaining NULL.",
+        embedded,
+        scanned,
+        remaining,
+    )
+    return {"scanned": scanned, "embedded": embedded, "remaining_null": remaining}

package/src/superlocalmemory/storage/migration_runner.py

@@ -113,6 +113,15 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M027_transferable_patterns_profile as _M027,
 )
+from superlocalmemory.storage.migrations import (
+    M028_fact_entity_associations as _M028,
+)
+from superlocalmemory.storage.migrations import (
+    M029_behavioral_history_indexes as _M029,
+)
+from superlocalmemory.storage.migrations import (
+    M030_entity_explorer_indexes as _M030,
+)
 
 # Map migration name → module (used for the optional ``verify(conn)`` hook
 # that lets the runner detect "already applied" state when an idempotent
@@ -144,6 +153,9 @@ _MODULES = {
     _M025.NAME: _M025,
     _M026.NAME: _M026,
     _M027.NAME: _M027,
+    _M028.NAME: _M028,
+    _M029.NAME: _M029,
+    _M030.NAME: _M030,
 }
 
 logger = logging.getLogger(__name__)
@@ -218,6 +230,10 @@ MIGRATIONS: list[Migration] = [
 # position proxy when the column is absent, so a failed deferred apply never
 # crashes the trainer — it just keeps the old label path.
 DEFERRED_MIGRATIONS: list[Migration] = [
+    # M028 captures an atomic_facts rowid high-water mark before readiness.
+    # atomic_facts/canonical_entities are bootstrapped by MemoryEngine.
+    Migration(name=_M028.NAME, db_target="memory", ddl=_M028.DDL,
+              dependencies=(_M018.NAME,)),
     Migration(name=_M006.NAME, db_target="memory", ddl=_M006.DDL),
     # M011 extends atomic_facts + creates memory_archive / memory_merge_log.
     # atomic_facts is bootstrapped at engine init, so M011 defers alongside M006.
@@ -256,6 +272,10 @@ DEFERRED_MIGRATIONS: list[Migration] = [
     # consolidation run, not during engine init or apply_all. apply() is a no-op
     # when the table is absent (first install after the schema change).
     Migration(name=_M027.NAME, db_target="learning", ddl=_M027.DDL),
+    # M029 indexes behavioral tables bootstrapped during engine initialization.
+    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),
 ]
 
 
@@ -401,7 +421,65 @@ def _apply_single(
                 )
                 logger.warning(detail)
                 return ("failed", detail)
-            return ("skipped", "already complete")
+            # 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})")

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

@@ -50,6 +50,11 @@ def verify(conn: sqlite3.Connection) -> bool:
     return _REQUIRED_TABLES.issubset(names)
 
 
+def repair(conn: sqlite3.Connection) -> None:
+    """Restore additive Skill Evolution tables without replaying other migrations."""
+    conn.executescript(DDL)
+
+
 DDL = """
 CREATE TABLE IF NOT EXISTS evolution_config (
     profile_id        TEXT PRIMARY KEY,

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

@@ -0,0 +1,270 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+
+"""M028 — normalized fact/entity associations for O(1) ingest effects.
+
+The table is both an association index and an idempotency ledger.  Its
+composite primary key means a fact can contribute to an entity's ``fact_count``
+once, regardless of ingestion retries or how many operations converge on the
+same consolidated fact.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+NAME = "M028_fact_entity_associations"
+DB_TARGET = "memory"
+
+DDL = """
+CREATE TABLE IF NOT EXISTS fact_entity_associations (
+    profile_id TEXT NOT NULL,
+    fact_id TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    first_operation_id TEXT NOT NULL DEFAULT '',
+    count_applied INTEGER NOT NULL DEFAULT 0
+        CHECK (count_applied IN (0, 1)),
+    created_at TEXT NOT NULL DEFAULT (
+        strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    ),
+    PRIMARY KEY (profile_id, fact_id, entity_id),
+    FOREIGN KEY (fact_id) REFERENCES atomic_facts(fact_id) ON DELETE CASCADE,
+    FOREIGN KEY (entity_id)
+        REFERENCES canonical_entities(entity_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_fact_entity_associations_entity
+    ON fact_entity_associations(profile_id, entity_id, fact_id);
+CREATE TABLE IF NOT EXISTS fact_entity_association_repair_state (
+    repair_key TEXT PRIMARY KEY,
+    state TEXT NOT NULL DEFAULT 'pending'
+        CHECK (state IN ('pending', 'running', 'retrying', 'complete')),
+    target_fact_rowid INTEGER NOT NULL DEFAULT -1,
+    last_fact_rowid INTEGER NOT NULL DEFAULT 0,
+    scanned INTEGER NOT NULL DEFAULT 0,
+    inserted INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT NOT NULL DEFAULT '',
+    updated_at TEXT NOT NULL
+);
+"""
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
+        (table,),
+    ).fetchone() is not None
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Install schema and capture a constant-time historical rowid boundary."""
+    conn.executescript(DDL)
+    association_columns = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA table_info(fact_entity_associations)"
+        ).fetchall()
+    }
+    if "count_applied" not in association_columns:
+        conn.execute(
+            "ALTER TABLE fact_entity_associations "
+            "ADD COLUMN count_applied INTEGER NOT NULL DEFAULT 0 "
+            "CHECK (count_applied IN (0, 1))"
+        )
+    repair_columns = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA table_info(fact_entity_association_repair_state)"
+        ).fetchall()
+    }
+    if "target_fact_rowid" not in repair_columns:
+        conn.execute(
+            "ALTER TABLE fact_entity_association_repair_state "
+            "ADD COLUMN target_fact_rowid INTEGER NOT NULL DEFAULT -1"
+        )
+    target = int(conn.execute(
+        "SELECT COALESCE(MAX(rowid), 0) FROM atomic_facts"
+    ).fetchone()[0])
+    conn.executescript(
+        "INSERT OR IGNORE INTO fact_entity_association_repair_state "
+        "(repair_key,state,target_fact_rowid,updated_at) "
+        f"VALUES ('historical-backfill','pending',{target},'');"
+        "UPDATE fact_entity_association_repair_state "
+        f"SET target_fact_rowid={target} "
+        "WHERE repair_key='historical-backfill' AND target_fact_rowid < 0;"
+    )
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(str(db_path), timeout=5)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA busy_timeout=5000")
+    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))
+    try:
+        row = conn.execute(
+            "SELECT state,target_fact_rowid,last_fact_rowid,scanned,inserted,"
+            "last_error,updated_at "
+            "FROM fact_entity_association_repair_state "
+            "WHERE repair_key='historical-backfill'"
+        ).fetchone()
+        if row is None:
+            return {
+                "state": "pending", "target_fact_rowid": 0,
+                "last_fact_rowid": 0,
+                "scanned": 0, "inserted": 0,
+                "last_error": "", "updated_at": "",
+            }
+        return dict(row)
+    finally:
+        conn.close()
+
+
+def _entity_ids(raw: object) -> tuple[str, ...]:
+    try:
+        values = json.loads(str(raw or "[]"))
+    except (TypeError, ValueError):
+        return ()
+    if not isinstance(values, list):
+        return ()
+    return tuple(dict.fromkeys(str(value) for value in values if value))
+
+
+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)
+        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()),
+        )
+        conn.commit()
+        return {"scanned": len(rows), "inserted": inserted, "complete": False}
+    except Exception:
+        conn.rollback()
+        raise
+
+
+def repair_fact_entity_associations(
+    db_path: Path,
+    *,
+    batch_size: int = 250,
+    max_batches: int = 1,
+) -> dict[str, int | bool]:
+    """Run bounded, restartable short-transaction backfill batches."""
+    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:
+        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()
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return true when the normalized association contract is indexed."""
+    if not (
+        _table_exists(conn, "fact_entity_associations")
+        and _table_exists(conn, "fact_entity_association_repair_state")
+    ):
+        return False
+    association_columns = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA table_info(fact_entity_associations)"
+        ).fetchall()
+    }
+    repair_columns = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA table_info(fact_entity_association_repair_state)"
+        ).fetchall()
+    }
+    if (
+        "count_applied" not in association_columns
+        or "target_fact_rowid" not in repair_columns
+    ):
+        return False
+    indexes = {
+        row[1]
+        for row in conn.execute(
+            "PRAGMA index_list(fact_entity_associations)"
+        ).fetchall()
+    }
+    return "idx_fact_entity_associations_entity" in indexes
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Restore additive M028 schema without recapturing its high-water mark."""
+    apply(conn)