superlocalmemory 3.7.8 → 3.8.1

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

@@ -0,0 +1,90 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 — performance indexes
+
+"""M025 — hot-path indexes confirmed missing by EXPLAIN QUERY PLAN.
+
+* atomic_facts(profile_id, content) — the store_fact dedup check runs on every
+  ingest; without this it scans all profile facts for a lifecycle match.
+* mesh_events(created_at) — the 7-day cleanup range-scanned the whole table.
+* mesh_peers(status, last_heartbeat) — stale-peer cleanup full-scanned.
+* mesh_peers(profile_id, last_heartbeat) — list_peers sorted in a temp b-tree.
+
+All additive CREATE INDEX IF NOT EXISTS — idempotent, no data change. Deferred
+so the target tables (mesh_* via schema_v343, atomic_facts via engine init)
+exist first.
+
+Author: Varun Pratap Bhardwaj / Qualixar
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M025_perf_indexes"
+DB_TARGET = "memory"
+
+DDL = (
+    "CREATE INDEX IF NOT EXISTS idx_facts_content_dedup "
+    "ON atomic_facts(profile_id, content);"
+    "CREATE INDEX IF NOT EXISTS idx_mesh_events_created_at ON mesh_events(created_at);"
+    "CREATE INDEX IF NOT EXISTS idx_mesh_peers_status_heartbeat "
+    "ON mesh_peers(status, last_heartbeat);"
+    "CREATE INDEX IF NOT EXISTS idx_mesh_peers_profile_heartbeat "
+    "ON mesh_peers(profile_id, last_heartbeat);"
+)
+
+
+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 _cols(conn: sqlite3.Connection, table: str) -> set[str]:
+    return {r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()}
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Create the perf indexes, each guarded so a non-standard schema cannot
+    abort the migration (and leave verify() falsely reporting done)."""
+    if _table_exists(conn, "atomic_facts") and {"profile_id", "content"} <= _cols(conn, "atomic_facts"):
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_facts_content_dedup "
+            "ON atomic_facts(profile_id, content)"
+        )
+    if _table_exists(conn, "mesh_events") and "created_at" in _cols(conn, "mesh_events"):
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_mesh_events_created_at "
+            "ON mesh_events(created_at)"
+        )
+    if _table_exists(conn, "mesh_peers"):
+        pc = _cols(conn, "mesh_peers")
+        if {"status", "last_heartbeat"} <= pc:
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_mesh_peers_status_heartbeat "
+                "ON mesh_peers(status, last_heartbeat)"
+            )
+        if {"profile_id", "last_heartbeat"} <= pc:
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_mesh_peers_profile_heartbeat "
+                "ON mesh_peers(profile_id, last_heartbeat)"
+            )
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Applied once the two always-creatable indexes exist (mesh_peers/events
+    are always present via schema_v343; atomic_facts always via engine init)."""
+    names = {
+        r[0] for r in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='index'"
+        ).fetchall()
+    }
+    required = {"idx_facts_content_dedup", "idx_mesh_events_created_at"}
+    # Only require indexes whose tables exist (fresh vs partial installs).
+    ok = True
+    if _table_exists(conn, "atomic_facts"):
+        ok = ok and "idx_facts_content_dedup" in names
+    if _table_exists(conn, "mesh_events"):
+        ok = ok and "idx_mesh_events_created_at" in names
+    return ok

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

@@ -0,0 +1,136 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 — RBAC hardening (SEC-H-01, audit-02)
+
+"""M026 — add FK on rbac_memberships → profiles ON DELETE CASCADE (memory.db).
+
+SEC-H-01: ``rbac_memberships`` (created by M024) had no foreign key to
+``profiles``. Deleting a profile therefore left its role grants behind; a
+profile later recreated with the same ``profile_id`` silently re-inherited
+them — a privilege-persistence bug.
+
+The runtime path (``delete_profile_from_db``) already purges memberships
+explicitly. This migration is the *defense-in-depth* half: a real FK with
+``ON DELETE CASCADE`` so that ANY path deleting a ``profiles`` row — not just
+that one helper — cannot leave orphaned grants.
+
+SQLite cannot add a constraint in place, so the table is rebuilt (the
+recommended safe-alter dance): rename → create canonical table with the FK →
+copy rows → drop old → recreate the user index. Wrapped in BEGIN IMMEDIATE /
+COMMIT for atomicity; the runner connects with ``foreign_keys = OFF`` so the
+rename/copy/drop never trips a constraint action mid-rebuild.
+
+Idempotent: skips when the FK is already present (fresh installs still get the
+FK because this always rebuilds M024's FK-less table on first run). Tolerant of
+a missing table (nothing to migrate).
+
+Deferred because the FK target ``profiles`` is created at engine init
+(``storage.schema``), after ``apply_all`` runs — same ordering constraint as
+M021 / M023.
+
+Author: Varun Pratap Bhardwaj / Qualixar
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M026_rbac_memberships_fk"
+DB_TARGET = "memory"
+
+# Documentation + drift-hash fingerprint. apply() below is the authoritative
+# executor (a static DDL string cannot express the conditional rebuild).
+DDL = (
+    "-- rebuild rbac_memberships with "
+    "FOREIGN KEY (profile_id) REFERENCES profiles(profile_id) ON DELETE CASCADE"
+)
+
+# Canonical rebuilt table. Column set is byte-identical to M024's, plus the FK.
+# The index is created separately AFTER the old table is dropped: RENAME keeps
+# the old index's name, so an inline/early CREATE INDEX would collide.
+_NEW_TABLE = """
+CREATE TABLE rbac_memberships (
+    profile_id TEXT NOT NULL,
+    user_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    added_at TEXT NOT NULL,
+    added_by TEXT DEFAULT 'owner',
+    PRIMARY KEY (profile_id, user_id),
+    FOREIGN KEY (profile_id) REFERENCES profiles(profile_id) ON DELETE CASCADE
+)
+"""
+
+
+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 _cols(conn: sqlite3.Connection, table: str) -> set[str]:
+    return {r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()}
+
+
+def _has_profiles_fk(conn: sqlite3.Connection, table: str) -> bool:
+    """True when ``table`` already declares a foreign key onto ``profiles``."""
+    try:
+        rows = conn.execute(f"PRAGMA foreign_key_list({table})").fetchall()
+    except sqlite3.OperationalError:  # pragma: no cover — table absent
+        return False
+    # PRAGMA foreign_key_list row layout: (id, seq, table, from, to, ...).
+    return any(r[2] == "profiles" for r in rows)
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Rebuild rbac_memberships with the profiles FK.
+
+    No-op when the table is absent (nothing to migrate) or the FK already
+    exists (idempotent re-run). Existing grants are preserved verbatim.
+    """
+    if not _table_exists(conn, "rbac_memberships"):
+        return
+    if _has_profiles_fk(conn, "rbac_memberships"):
+        return
+
+    has_added_by = "added_by" in _cols(conn, "rbac_memberships")
+
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        conn.execute("ALTER TABLE rbac_memberships RENAME TO _rbac_memberships_old")
+        # NB: single statement via execute(), not executescript() — the latter
+        # force-commits the pending transaction, breaking our BEGIN/COMMIT.
+        conn.execute(_NEW_TABLE)
+        if has_added_by:
+            conn.execute(
+                "INSERT INTO rbac_memberships "
+                "(profile_id, user_id, role, added_at, added_by) "
+                "SELECT profile_id, user_id, role, added_at, added_by "
+                "FROM _rbac_memberships_old"
+            )
+        else:  # exotic/older install missing the column — default it
+            conn.execute(
+                "INSERT INTO rbac_memberships "
+                "(profile_id, user_id, role, added_at) "
+                "SELECT profile_id, user_id, role, added_at "
+                "FROM _rbac_memberships_old"
+            )
+        # Dropping the old table also drops its index, freeing the name.
+        conn.execute("DROP TABLE _rbac_memberships_old")
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_rbac_memberships_user "
+            "ON rbac_memberships(user_id)"
+        )
+        conn.execute("COMMIT")
+    except sqlite3.Error:
+        try:
+            conn.execute("ROLLBACK")
+        except sqlite3.Error:  # pragma: no cover — best-effort
+            pass
+        raise
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Applied once rbac_memberships carries the profiles FK (or is absent)."""
+    if not _table_exists(conn, "rbac_memberships"):
+        return True  # nothing to migrate; fresh install rebuilds it on apply
+    return _has_profiles_fk(conn, "rbac_memberships")

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

@@ -0,0 +1,163 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 — isolation correctness (H-01, cycle-3 audit)
+
+"""M027 — add profile_id to transferable_patterns + rebuild UNIQUE constraint (learning.db).
+
+H-01: ``transferable_patterns`` had no ``profile_id`` column; every profile's
+consolidation wrote to the same (pattern_type, key) row.  The last writer won,
+so any profile's ``get_preferences()`` call returned patterns contaminated by
+other profiles' consolidation runs.
+
+Fix:
+  1. Add ``profile_id TEXT NOT NULL DEFAULT 'default'`` to the table.
+  2. Change the UNIQUE constraint from ``(pattern_type, key)`` to
+     ``(profile_id, pattern_type, key)`` so each profile owns its own rows.
+  3. Backfill existing rows to ``profile_id = 'default'`` (the only valid value
+     before this migration — they are legacy/unattributed patterns).
+
+SQLite cannot ALTER a UNIQUE constraint in place; the table must be rebuilt
+(rename → create canonical form → copy → drop old).  Wrapped in
+``BEGIN IMMEDIATE / COMMIT`` for atomicity.
+
+Idempotent:
+  * If ``profile_id`` already exists with the correct UNIQUE constraint
+    (fresh install after the code change), ``apply()`` is a no-op.
+  * If the table is absent entirely (CrossProjectAggregator was never run
+    against learning.db), ``apply()`` is a no-op — the new _SCHEMA in
+    cross_project.py will create it in its canonical form on first use.
+
+DB target: ``learning`` — CrossProjectAggregator is under the learning/
+package and is expected to share the learning database.
+
+Author: Varun Pratap Bhardwaj / Qualixar
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M027_transferable_patterns_profile"
+DB_TARGET = "learning"
+
+DDL = (
+    "-- rebuild transferable_patterns with "
+    "profile_id TEXT NOT NULL DEFAULT 'default' "
+    "and UNIQUE(profile_id, pattern_type, key)"
+)
+
+_NEW_TABLE = """
+CREATE TABLE transferable_patterns (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id TEXT NOT NULL DEFAULT 'default',
+    pattern_type TEXT NOT NULL DEFAULT 'preference',
+    key TEXT NOT NULL,
+    value TEXT NOT NULL,
+    confidence REAL DEFAULT 0.0,
+    evidence_count INTEGER DEFAULT 0,
+    profiles_seen INTEGER DEFAULT 1,
+    decay_factor REAL DEFAULT 1.0,
+    contradictions TEXT DEFAULT '[]',
+    first_seen TEXT,
+    last_seen TEXT,
+    UNIQUE(profile_id, pattern_type, key)
+)
+"""
+
+
+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 _cols(conn: sqlite3.Connection, table: str) -> set[str]:
+    return {r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()}
+
+
+def _unique_index_covers_profile(conn: sqlite3.Connection) -> bool:
+    """True when transferable_patterns already has the UNIQUE(profile_id, …) constraint."""
+    indexes = conn.execute(
+        "SELECT name, sql FROM sqlite_master "
+        "WHERE type='index' AND tbl_name='transferable_patterns'"
+    ).fetchall()
+    for idx in indexes:
+        sql = (idx[1] or "").lower()
+        if "profile_id" in sql and "pattern_type" in sql and "key" in sql:
+            return True
+    # SQLite stores the UNIQUE constraint on the CREATE TABLE statement as well.
+    tbl_sql = conn.execute(
+        "SELECT sql FROM sqlite_master "
+        "WHERE type='table' AND name='transferable_patterns'"
+    ).fetchone()
+    if tbl_sql:
+        sql = (tbl_sql[0] or "").lower()
+        if "unique(profile_id" in sql or "unique (profile_id" in sql:
+            return True
+    return False
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Rebuild transferable_patterns with profile_id column and correct UNIQUE constraint.
+
+    No-op when the table is absent or already in canonical form.
+    Existing data is preserved; legacy rows get profile_id = 'default'.
+    """
+    if not _table_exists(conn, "transferable_patterns"):
+        return  # Table was never created against this DB — fresh install handles it.
+
+    if (
+        "profile_id" in _cols(conn, "transferable_patterns")
+        and _unique_index_covers_profile(conn)
+    ):
+        return  # Already in canonical form.
+
+    has_profile_col = "profile_id" in _cols(conn, "transferable_patterns")
+
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        conn.execute(
+            "ALTER TABLE transferable_patterns RENAME TO _tp_old"
+        )
+        conn.execute(_NEW_TABLE)
+
+        if has_profile_col:
+            # Column exists but UNIQUE constraint is wrong — copy as-is.
+            conn.execute(
+                "INSERT INTO transferable_patterns "
+                "(profile_id, pattern_type, key, value, confidence, evidence_count, "
+                " profiles_seen, decay_factor, contradictions, first_seen, last_seen) "
+                "SELECT profile_id, pattern_type, key, value, confidence, evidence_count, "
+                "       profiles_seen, decay_factor, contradictions, first_seen, last_seen "
+                "FROM _tp_old"
+            )
+        else:
+            # No profile_id yet — backfill legacy rows to 'default'.
+            conn.execute(
+                "INSERT INTO transferable_patterns "
+                "(profile_id, pattern_type, key, value, confidence, evidence_count, "
+                " profiles_seen, decay_factor, contradictions, first_seen, last_seen) "
+                "SELECT 'default', pattern_type, key, value, confidence, evidence_count, "
+                "       profiles_seen, decay_factor, contradictions, first_seen, last_seen "
+                "FROM _tp_old"
+            )
+
+        conn.execute("DROP TABLE _tp_old")
+        conn.execute("COMMIT")
+    except sqlite3.Error:
+        try:
+            conn.execute("ROLLBACK")
+        except sqlite3.Error:
+            pass
+        raise
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """True when transferable_patterns has profile_id with the correct UNIQUE,
+    or when the table is absent (fresh install will create it correctly).
+    """
+    if not _table_exists(conn, "transferable_patterns"):
+        return True  # absent — first run of _ensure_schema creates canonical form
+    if "profile_id" not in _cols(conn, "transferable_patterns"):
+        return False
+    return _unique_index_covers_profile(conn)

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)