superlocalmemory 4.0.9 → 4.0.10

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

@@ -0,0 +1,488 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+"""M043 — take model-written summaries out of the retrieval corpus.
+
+Runs unattended on upgrade. Three steps, in this order, all idempotent:
+
+  1. PRESERVE — copy every consolidator-authored row's text into
+     ``consolidated_summaries``, the display-only table, so nothing the user
+     could see today disappears from view.
+  2. WITHHOLD — set ``atomic_facts.quarantined = 1`` on those rows. They stay
+     on disk, with their provenance, and stop being answers.
+  3. RESTORE — un-hide genuine memories whose retention row says they are
+     maximally retained but whose zone says 'archive'.
+
+WHY THIS IS A MIGRATION AND NOT A ONE-OFF SCRIPT
+------------------------------------------------
+About three quarters of this product's users are not engineers. A repair that
+requires reading a runbook, cloning a repository or running SQL is a repair
+they will not get. The store is the whole point of the product, so a defective
+store has to fix itself on the next start, whether they installed by pip, npm
+or from source.
+
+DEFERRED, NOT EAGER
+-------------------
+``atomic_facts`` is bootstrapped by ``MemoryEngine.initialize()``, which runs
+*after* ``apply_all``. Every existing migration that touches it — M011, M013,
+M015, M016 — is deferred for that reason and this one is no different. Deferred
+migrations are snapshotted: ``apply_deferred`` takes a verified backup lazily,
+immediately before the first migration that will actually apply
+(``migration_runner.py``, ``_ensure_snapshot``), using the sqlite3 backup API
+rather than a file copy, which cannot snapshot a live WAL database.
+
+WHAT IT IS REPAIRING, MEASURED
+------------------------------
+On the author's 5,089-fact store, before this ran:
+
+    rows written by the consolidator into atomic_facts     1,195
+      ...retrieval-eligible (retention zone not archive)     307
+      ...that are summaries of other summaries              353
+      ...carrying a temporal_events row                        0
+      ...violating the declared FK to memories             1,195
+    genuine memories archived by consolidation              528
+      ...archived by anything other than consolidation        0
+      ...whose retention score is 1.0 (i.e. "keep")         528
+
+Asked "what am I working on", ranks 1, 2 and 3 all read "Unfortunately, there
+is no information available about 'Gateway', 'State', 'Bounded', or 'Claude' in
+the provided text."
+
+THE THREE PREDICATES, AND WHY EACH IS EXACT
+-------------------------------------------
+**Which rows are consolidator-authored.** ``memory_id = ''`` *and* present in
+``fact_consolidations``. Verified to agree exactly on the real store: 1,195
+either way, zero rows on either difference, and zero genuine facts with a
+dangling ``memory_id`` that could be swept up by accident. Both halves are
+required so that a future fact with an empty ``memory_id`` — or a consolidation
+record pointing at a real fact — is left alone.
+
+Content matching was considered and rejected. Only 34 of the 307
+retrieval-eligible rows read as refusals; the other 273 are fluent, plausible,
+generic prose that no honest predicate separates from a real summary. Repairing
+by content would have cleared a ninth of the problem and looked finished.
+
+**Which memories to un-hide.** ``lifecycle_zone IN ('archive','forgotten')``
+together with ``retention_score > 0.8``. That combination is a contradiction on
+its own terms: ``math/ebbinghaus.py:lifecycle_zone`` maps any score above 0.8 to
+'active', so a row scoring 1.0 and filed under 'archive' was put there by
+something that did not consult the score. Consolidation was that something, but
+the predicate does not need to know it — which is what makes it safe to re-run
+forever, and self-limiting: it describes an inconsistency, so it empties itself.
+
+The restored zone is *recomputed* from the score with the same thresholds, not
+guessed. Guessing 'warm' would have quietly demoted 528 facts that the maths
+already called 'active'.
+
+**Which summaries to preserve.** All of them, including the refusals. A reader
+looking at their dashboard should see what their store actually generated;
+silently dropping the embarrassing ones would hide the problem this repair
+exists to fix. W5 renders them, and its own tests cover not showing junk as
+though it were insight.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+
+logger = logging.getLogger(__name__)
+
+NAME = "M043_quarantine_display_summaries"
+DB_TARGET = "memory"
+
+#: Kept short and STABLE. The runner hashes this text and fails a completed
+#: migration whose hash has drifted, so it must not be edited to track changes
+#: in ``apply()``. The work lives in ``apply()`` because it is conditional data
+#: movement that one DDL script cannot express.
+DDL = "-- M043: see apply(); preserve, withhold, restore"
+
+
+#: Retention thresholds, mirroring ``math/ebbinghaus.py::lifecycle_zone`` and
+#: ``ForgettingConfig`` defaults (archive_threshold 0.2, forget_threshold 0.05).
+#: A migration is SQL and cannot read the user's config, so these are the
+#: shipped defaults. That is safe here because this expression is only ever
+#: applied to rows whose score is already above 0.8 — the top branch — where no
+#: threshold below it can change the answer.
+_ZONE_FROM_SCORE = """
+    CASE
+        WHEN retention_score > 0.8  THEN 'active'
+        WHEN retention_score > 0.5  THEN 'warm'
+        WHEN retention_score > 0.2  THEN 'cold'
+        WHEN retention_score > 0.05 THEN 'archive'
+        ELSE 'forgotten'
+    END
+"""
+
+#: Rows the fact consolidator wrote directly into the retrieval corpus.
+_CONSOLIDATOR_ROWS = """
+    SELECT af.fact_id
+      FROM atomic_facts af
+     WHERE af.memory_id = ''
+       AND af.fact_id IN (
+             SELECT consolidated_fact_id FROM fact_consolidations
+           )
+"""
+
+#: A genuine memory that consolidation hid.
+#:
+#: BY PROVENANCE, NOT BY SCORE. The first version of this required
+#: ``retention_score > 0.8``, reasoning that a score above 0.8 maps to 'active'
+#: so zone 'archive' must be a contradiction. Every one of the 528 hidden
+#: memories on the author's store scored exactly 1.0, so it worked there — and
+#: that store is the LUCKY shape. Those rows scored 1.0 because they had no
+#: prior retention row and the schema default is 1.0.
+#:
+#: On a store where the forgetting scheduler has been running (the default,
+#: ``ForgettingConfig.enabled = True``) a consolidation victim carries whatever
+#: score it had drifted to — typically 0.21 to 0.80 — because
+#: ``set_fact_lifecycle_zone`` moves the zone and leaves the score alone. The
+#: score-based predicate does not see those rows at all: they stay archived,
+#: ``verify()`` returns true because it cannot see them either, and ``doctor``
+#: reports healthy while the memories remain unreachable. A repair that is
+#: silent about what it failed to repair is worse than one that fails loudly.
+#:
+#: So the test is the same one the withhold step uses: was this row a
+#: consolidation source? That is recorded, and it does not depend on a number
+#: that something else was free to change afterwards.
+#:
+#: Self-correcting rather than indiscriminate: the zone is RECOMPUTED from the
+#: score, so a source that has genuinely faded maps straight back to
+#: archive/forgotten and nothing moves. Only a row whose own score says it
+#: should be reachable becomes reachable.
+_WRONGLY_HIDDEN_BASE = """
+    SELECT r.fact_id
+      FROM fact_retention r
+      JOIN atomic_facts af ON af.fact_id = r.fact_id
+     WHERE r.lifecycle_zone IN ('archive', 'forgotten')
+       AND af.memory_id <> ''
+       AND ({extra})
+"""
+
+#: The provenance half. Only usable when the ledger exists, which is why this
+#: is composed at call time rather than being one constant: a first version
+#: baked the subquery in and ``verify()`` then raised "no such table:
+#: fact_consolidations" on a store without a ledger -- caught by the test for
+#: exactly that store shape.
+_ARCHIVED_BY_CONSOLIDATION = """
+    af.fact_id IN (
+        SELECT je.value
+          FROM fact_consolidations fc, json_each(fc.source_fact_ids) je
+         WHERE json_valid(fc.source_fact_ids)
+    )
+"""
+
+#: The score half: hidden while the retention maths says to keep.
+_SCORED_TO_KEEP = "r.retention_score > 0.8"
+
+
+def _wrongly_hidden(conn: sqlite3.Connection) -> str:
+    """The restore predicate, using whichever halves this store supports."""
+    if _table_exists(conn, "fact_consolidations"):
+        return _WRONGLY_HIDDEN_BASE.format(
+            extra=f"{_SCORED_TO_KEEP} OR {_ARCHIVED_BY_CONSOLIDATION}"
+        )
+    return _WRONGLY_HIDDEN_BASE.format(extra=_SCORED_TO_KEEP)
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Preserve, withhold, restore. Atomic, and safe to run again."""
+    if not _table_exists(conn, "atomic_facts"):
+        # Nothing to repair on a store whose corpus does not exist yet. Not an
+        # error: a fresh install reaches this migration with the table created
+        # moments earlier, and a store older than the table has no rows to fix.
+        logger.debug("M043: atomic_facts absent, nothing to repair")
+        return
+    if not _has_column(conn, "atomic_facts", "quarantined"):
+        # storage.schema.create_all_tables adds it at every engine init, so
+        # reaching here means engine init has not run against this store.
+        # Adding it is cheap and keeps the migration independent of that order.
+        conn.execute(
+            "ALTER TABLE atomic_facts ADD COLUMN quarantined "
+            "INTEGER NOT NULL DEFAULT 0"
+        )
+    if not _table_exists(conn, "consolidated_summaries"):
+        # UNCONDITIONALLY, because verify() requires it and verify() is what the
+        # runner consults on every later start.
+        #
+        # A first draft created it only inside _preserve, which is skipped when
+        # there is no provenance ledger. On a store with no ledger the migration
+        # therefore applied, recorded 'complete', and then failed verify() on
+        # the NEXT start -- and since repair() is apply(), it failed again and
+        # was reported as a failed migration forever. Two existing
+        # idempotency tests caught it. The lesson generalises: everything
+        # verify() asserts has to be produced on every path through apply(),
+        # not only on the path that happens to need it.
+        #
+        # The DDL is imported, not restated, so the two definitions cannot
+        # drift apart.
+        from superlocalmemory.storage.schema import CONSOLIDATED_SUMMARIES_DDL
+
+        conn.executescript(CONSOLIDATED_SUMMARIES_DDL)
+
+    # No provenance ledger means no consolidator-authored rows can be
+    # identified, so there is nothing to preserve or withhold. The restore step
+    # is independent of it and still runs — a store can have wrongly-hidden
+    # memories without having the ledger that explains how they got that way.
+    #
+    # Written as a skip rather than an error after the first draft raised here
+    # and broke three existing migration-runner tests, which drive
+    # apply_deferred against minimal fixtures. A repair that only works on a
+    # fully-bootstrapped store is a repair that will not run on the store that
+    # needs it most.
+    has_ledger = _table_exists(conn, "fact_consolidations")
+
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        preserved = _preserve(conn) if has_ledger else 0
+        withheld = _withhold(conn) if has_ledger else 0
+        restored = _restore(conn)
+        conn.execute("COMMIT")
+    except sqlite3.Error:
+        try:
+            conn.execute("ROLLBACK")
+        except sqlite3.Error:  # pragma: no cover — best effort
+            pass
+        raise
+
+    # INFO, not debug. This changes what the user's next recall returns, so it
+    # belongs in the log they can actually see.
+    if preserved or withheld or restored:
+        logger.info(
+            "M043 memory repair: %d summaries preserved for display, "
+            "%d withheld from recall, %d memories restored to recall",
+            preserved, withheld, restored,
+        )
+
+
+def _preserve(conn: sqlite3.Connection) -> int:
+    """Copy consolidator rows into the display table. Returns rows added."""
+    before = _count(conn, "SELECT COUNT(*) FROM consolidated_summaries")
+    # The entity a summary was written about is not recoverable from the row —
+    # entities_json holds the whole cluster's pool — so entity_id is left empty
+    # and entity_name carries the summary's own leading label when it has one.
+    # source_fact_ids comes from the provenance ledger, which does know.
+    conn.execute("""
+        INSERT INTO consolidated_summaries
+            (summary_id, profile_id, entity_id, entity_name, content,
+             source_fact_ids, source_count, char_count, generated_by,
+             scope, shared_with, source_earliest, source_latest, created_at)
+        SELECT af.fact_id,
+               af.profile_id,
+               '',
+               '',
+               af.content,
+               COALESCE(
+                   (SELECT fc.source_fact_ids FROM fact_consolidations fc
+                     WHERE fc.consolidated_fact_id = af.fact_id
+                       AND json_valid(fc.source_fact_ids)
+                     ORDER BY fc.created_at DESC LIMIT 1),
+                   '[]'
+               ),
+               -- Count only sources that are the owner's OWN memories.
+               --
+               -- Two wrong answers were tried first. evidence_count reached 450
+               -- on one row, because the old reinforce-or-insert path bumped it
+               -- every time it saw the same summary text again. The length of
+               -- the provenance array is 10, which is closer but still a lie:
+               -- 353 of these summaries are summaries OF SUMMARIES, and on the
+               -- author's store the first row's ten "sources" are all
+               -- consolidator rows written 10-20 seconds apart. Reporting that
+               -- as "10 memories summarised" tells the owner this is a digest
+               -- of ten things they said, when it is a digest of ten things the
+               -- summarizer said.
+               --
+               -- So: count the sources that have a parent memory. A
+               -- summary-of-summaries therefore reports 0, which is the honest
+               -- number, and the endpoint ranks it below one that covers real
+               -- memories.
+               -- json_valid guards every json_each in this file. Without it
+               -- ONE malformed source_fact_ids anywhere in the ledger makes
+               -- json_each raise, apply() roll back, verify() stay false, and
+               -- repair() re-raise on every start for the life of the store —
+               -- a single bad row taking the whole repair down with it.
+               (SELECT COUNT(*) FROM atomic_facts src
+                 WHERE src.memory_id <> ''
+                   AND src.fact_id IN (
+                       SELECT je.value FROM fact_consolidations fc,
+                              json_each(fc.source_fact_ids) je
+                        WHERE fc.consolidated_fact_id = af.fact_id
+                          AND json_valid(fc.source_fact_ids))),
+               LENGTH(af.content),
+               'migrated',
+               COALESCE(af.scope, 'personal'),
+               af.shared_with,
+               -- Coverage window over those same genuine sources only.
+               -- A first draft spanned every source and produced
+               -- "2026-08-18 to 2026-08-18" on a row whose sources were ten
+               -- summaries written seconds apart -- the span of a summarisation
+               -- run, presented as the stretch of work it covers. NULL when
+               -- there are no genuine sources, and the dashboard then shows no
+               -- span rather than a false one.
+               (SELECT MIN(src.created_at) FROM atomic_facts src
+                 WHERE src.memory_id <> ''
+                   AND src.fact_id IN (
+                       SELECT je.value FROM fact_consolidations fc,
+                              json_each(fc.source_fact_ids) je
+                        WHERE fc.consolidated_fact_id = af.fact_id
+                          AND json_valid(fc.source_fact_ids))),
+               (SELECT MAX(src.created_at) FROM atomic_facts src
+                 WHERE src.memory_id <> ''
+                   AND src.fact_id IN (
+                       SELECT je.value FROM fact_consolidations fc,
+                              json_each(fc.source_fact_ids) je
+                        WHERE fc.consolidated_fact_id = af.fact_id
+                          AND json_valid(fc.source_fact_ids))),
+               af.created_at
+          FROM atomic_facts af
+         WHERE af.fact_id IN (""" + _CONSOLIDATOR_ROWS + """)
+        -- UNTARGETED. `ON CONFLICT (profile_id, entity_id, content)` names one
+        -- constraint and raises on any other, and this table has two: that
+        -- unique triple, and summary_id as primary key. summary_id is the
+        -- source fact_id, so a row whose CONTENT changed between runs conflicts
+        -- on the primary key, which the targeted form does not catch --
+        -- reproduced as `IntegrityError: UNIQUE constraint failed:
+        -- consolidated_summaries.summary_id`. Because the runner calls
+        -- repair() (which is apply()) whenever verify() fails, that failure
+        -- would then repeat on every single start, forever.
+        --
+        -- Untargeted DO NOTHING absorbs both. Losing the newer text is the
+        -- right trade: this is a display copy of a row that is about to be
+        -- withheld, and the first copy taken is the one the owner has already
+        -- been shown.
+        ON CONFLICT DO NOTHING
+    """)
+    return _count(conn, "SELECT COUNT(*) FROM consolidated_summaries") - before
+
+
+def _withhold(conn: sqlite3.Connection) -> int:
+    """Mark consolidator rows quarantined. Returns rows changed."""
+    cur = conn.execute(
+        "UPDATE atomic_facts SET quarantined = 1 "
+        "WHERE COALESCE(quarantined, 0) = 0 "
+        "  AND fact_id IN (" + _CONSOLIDATOR_ROWS + ")"
+    )
+    return int(cur.rowcount or 0)
+
+
+def _restore(conn: sqlite3.Connection) -> int:
+    """Un-hide memories consolidation archived. Returns rows changed.
+
+    Needs both tables: ``fact_retention`` to hold the zone, and
+    ``fact_consolidations`` for the provenance half of the predicate. Without
+    the ledger it falls back to the score-only test, which is strictly weaker
+    but is all a store with no ledger can support.
+    """
+    if not _table_exists(conn, "fact_retention"):
+        return 0
+    cur = conn.execute(
+        "UPDATE fact_retention SET lifecycle_zone = (" + _ZONE_FROM_SCORE + ") "
+        "WHERE fact_id IN (" + _wrongly_hidden(conn) + ")"
+    )
+    changed = int(cur.rowcount or 0)
+    if changed:
+        _sync_lifecycle_mirror(conn)
+    return changed
+
+
+def _sync_lifecycle_mirror(conn: sqlite3.Connection) -> None:
+    """Bring atomic_facts.lifecycle back in line with the canonical zone.
+
+    Same mapping core/lifecycle_state.py applies: archive/forgotten map to
+    'archived', every other zone keeps its own name.
+    """
+    conn.execute("""
+        UPDATE atomic_facts
+           SET lifecycle = (
+                 SELECT CASE
+                          WHEN r.lifecycle_zone IN ('archive', 'forgotten')
+                               THEN 'archived'
+                          ELSE r.lifecycle_zone
+                        END
+                   FROM fact_retention r
+                  WHERE r.fact_id = atomic_facts.fact_id
+               )
+         WHERE lifecycle = 'archived'
+           AND fact_id IN (
+                 SELECT fact_id FROM fact_retention
+                  WHERE lifecycle_zone NOT IN ('archive', 'forgotten')
+               )
+    """)
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Whether the repair's end-state holds.
+
+    Called on every start for an already-complete migration. Returning False
+    routes to ``repair()``, which makes this a standing guard: if pollution ever
+    reappears, the next daemon start withholds it without anyone asking.
+    """
+    if not _table_exists(conn, "atomic_facts"):
+        return True
+    if not _has_column(conn, "atomic_facts", "quarantined"):
+        return False
+    if not _table_exists(conn, "consolidated_summaries"):
+        return False
+
+    if _table_exists(conn, "fact_consolidations"):
+        unwithheld = _count(
+            conn,
+            "SELECT COUNT(*) FROM atomic_facts WHERE COALESCE(quarantined, 0) = 0 "
+            "  AND fact_id IN (" + _CONSOLIDATOR_ROWS + ")",
+        )
+        if unwithheld:
+            return False
+
+        # Every withheld row must still be visible somewhere, or the repair has
+        # deleted the owner's view of it rather than moved it.
+        #
+        # BY IDENTITY *OR* CONTENT, and the "or" is what makes this an invariant
+        # rather than a trap. Matching on content alone could never become true
+        # once a row's content changed after being preserved: the display copy
+        # keeps the old text, verify stays false, repair() runs apply() again,
+        # apply() cannot change the past, and the migration is reported failed
+        # on every start for the rest of the store's life. Matching on identity
+        # alone fails the other way, because two withheld rows with identical
+        # text collapse into one display row under the unique triple, leaving the
+        # second with no row of its own id.
+        #
+        # Either match satisfies the guarantee that actually matters: nothing
+        # the owner could see has stopped being visible.
+        unpreserved = _count(conn, """
+            SELECT COUNT(*) FROM atomic_facts af
+             WHERE af.fact_id IN (""" + _CONSOLIDATOR_ROWS + """)
+               AND NOT EXISTS (
+                     SELECT 1 FROM consolidated_summaries cs
+                      WHERE cs.profile_id = af.profile_id
+                        AND (cs.summary_id = af.fact_id
+                             OR cs.content = af.content)
+                   )
+        """)
+        if unpreserved:
+            return False
+
+    if _table_exists(conn, "fact_retention"):
+        if _count(conn, "SELECT COUNT(*) FROM (" + _wrongly_hidden(conn) + ")"):
+            return False
+    return True
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Re-run the repair. It is idempotent, so this is simply apply()."""
+    apply(conn)
+
+
+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 _has_column(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    return any(
+        row[1] == column for row in conn.execute(f"PRAGMA table_info({table})")
+    )
+
+
+def _count(conn: sqlite3.Connection, sql: str) -> int:
+    row = conn.execute(sql).fetchone()
+    return int(row[0]) if row else 0

package/src/superlocalmemory/storage/schema.py

@@ -21,9 +21,12 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+import logging
 import sqlite3
 from typing import Final
 
+logger = logging.getLogger(__name__)
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -57,6 +60,7 @@ _TABLES: Final[tuple[str, ...]] = (
     "config",
     "entity_communities",
     "community_summaries",
+    "consolidated_summaries",
     "persona_summary",
 )
 
@@ -190,6 +194,11 @@ CREATE TABLE IF NOT EXISTS atomic_facts (
                             CHECK (lifecycle IN (
                                 'active', 'warm', 'cold', 'archived'
                             )),
+    -- Withheld from retrieval without being destroyed. Set by repair, never
+    -- by a normal write; enforced in exactly one place,
+    -- DatabaseManager.get_facts_by_ids, which every channel's candidates are
+    -- re-authorised through and which the engine hydrates from.
+    quarantined        INTEGER NOT NULL DEFAULT 0,
     langevin_position  TEXT,
 
     -- Emotional
@@ -842,6 +851,51 @@ CREATE INDEX IF NOT EXISTS idx_comm_summ_profile
     ON community_summaries(profile_id);
 """
 
+# Display-only consolidated summaries.
+#
+# A summary of a cluster of facts is a VIEW of memory, not a memory. Between
+# v3.6.4 and 4.0.9 the fact consolidator wrote its summaries straight into
+# atomic_facts with a raw INSERT, which put model-authored prose into the
+# retrieval corpus alongside the user's own words — where it out-ranked them,
+# because those rows carried every entity in their cluster and so had more
+# entity links than any real fact.
+#
+# This table restores the boundary. community_summaries is the precedent to
+# read it by: written by one owner, read only after retrieval has finished, and
+# named by no channel. tests/test_retrieval/test_summaries_stay_out_of_recall.py
+# fails if a retrieval module so much as mentions it.
+#
+# source_earliest / source_latest are the honest dates for a derived row. A
+# summary has no observation_date of its own — it was never observed — but the
+# span of what it summarises is real, and it is what lets the dashboard say
+# which stretch of work a summary covers.
+CONSOLIDATED_SUMMARIES_DDL: Final[str] = """
+CREATE TABLE IF NOT EXISTS consolidated_summaries (
+    summary_id       TEXT PRIMARY KEY,
+    profile_id       TEXT NOT NULL,
+    entity_id        TEXT NOT NULL DEFAULT '',
+    entity_name      TEXT NOT NULL DEFAULT '',
+    content          TEXT NOT NULL,
+    source_fact_ids  TEXT NOT NULL DEFAULT '[]',
+    source_count     INTEGER NOT NULL DEFAULT 0,
+    char_count       INTEGER NOT NULL DEFAULT 0,
+    generated_by     TEXT NOT NULL DEFAULT 'extractive'
+                        CHECK (generated_by IN (
+                            'extractive', 'ollama', 'cloud', 'migrated'
+                        )),
+    scope            TEXT NOT NULL DEFAULT 'personal',
+    shared_with      TEXT,
+    source_earliest  TEXT,
+    source_latest    TEXT,
+    created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (profile_id, entity_id, content)
+);
+CREATE INDEX IF NOT EXISTS idx_consolidated_summaries_profile
+    ON consolidated_summaries(profile_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_consolidated_summaries_entity
+    ON consolidated_summaries(profile_id, entity_id);
+"""
+
 # Wave Q3: progressive-abstraction top tier — one persona roll-up per profile
 # consuming the top community summaries (additive; safe on existing DBs).
 # Recall-gated (never auto-injected into hot recall) and size-bounded to avoid
@@ -893,6 +947,7 @@ _DDL_ORDERED: Final[tuple[str, ...]] = (
     _SQL_ENTITY_COMMUNITIES,
     # Wave Q2: community summaries (additive; safe on existing DBs)
     _SQL_COMMUNITY_SUMMARIES,
+    CONSOLIDATED_SUMMARIES_DDL,
     # Wave Q3: persona roll-up tier (additive; safe on existing DBs)
     _SQL_PERSONA_SUMMARY,
 )
@@ -902,6 +957,38 @@ _DDL_ORDERED: Final[tuple[str, ...]] = (
 # Public API
 # ---------------------------------------------------------------------------
 
+#: (table, column, column definition). Applied with ALTER TABLE ADD COLUMN,
+#: which SQLite offers no IF NOT EXISTS form of, so presence is checked first.
+_ADDITIVE_COLUMNS: Final[tuple[tuple[str, str, str], ...]] = (
+    ("atomic_facts", "quarantined", "INTEGER NOT NULL DEFAULT 0"),
+)
+
+
+def _add_missing_columns(conn: sqlite3.Connection) -> None:
+    """Add columns that upgraded databases predate. Idempotent.
+
+    A missing table is not an error: this runs inside create_all_tables, so the
+    table is created moments earlier in the same call, and a database old enough
+    to lack it entirely has nothing to alter.
+    """
+    for table, column, definition in _ADDITIVE_COLUMNS:
+        try:
+            present = any(
+                row[1] == column
+                for row in conn.execute(f"PRAGMA table_info({table})")
+            )
+            if not present:
+                conn.execute(
+                    f"ALTER TABLE {table} ADD COLUMN {column} {definition}"
+                )
+        except sqlite3.Error as exc:
+            # Never fatal. A store that cannot take the column keeps working;
+            # get_facts_by_ids checks for the column before filtering on it.
+            logger.warning(
+                "additive column %s.%s not applied: %s", table, column, exc,
+            )
+
+
 def create_all_tables(conn: sqlite3.Connection) -> None:
     """Create every table, index, trigger, and FTS virtual table.
 
@@ -921,6 +1008,17 @@ def create_all_tables(conn: sqlite3.Connection) -> None:
     for ddl in V32_DDL:
         conn.executescript(ddl)
 
+    # Additive columns on tables that predate them.
+    #
+    # CREATE TABLE IF NOT EXISTS cannot add a column to a table that already
+    # exists, so an upgraded database gets the column here rather than only from
+    # a migration. Doing it at every engine init makes the invariant "if
+    # atomic_facts exists then quarantined exists" hold even when the migration
+    # pass failed or was never reached — which matters because withholding a
+    # poisoned row from retrieval must not be contingent on a migration having
+    # succeeded.
+    _add_missing_columns(conn)
+
     # Seed schema version on first run.
     existing = conn.execute(
         "SELECT COUNT(*) AS n FROM schema_version"

package/src/superlocalmemory/summaries/base.py

@@ -62,7 +62,7 @@ class SummaryResult:
 
 # ── coverage constants ──────────────────────────────────────────────────────
 #
-# Use these strings; the acceptance gate checks for their presence
+# Use these strings; the tests check for their presence
 # and the values must be human-interpretable without this file.
 
 COVERAGE_FULL = "full"