superlocalmemory 4.0.4 → 4.0.6

package/src/superlocalmemory/storage/database.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import platform
 import sqlite3
 import threading
 import time
@@ -85,6 +86,10 @@ _BUSY_TIMEOUT_MS = _env_int("SLM_DB_BUSY_TIMEOUT_MS", 10_000)   # wait for write
 _MAX_RETRIES = _env_int("SLM_DB_MAX_RETRIES", 5)                # retry on SQLITE_BUSY
 _RETRY_BASE_DELAY = _env_float("SLM_DB_RETRY_BASE_DELAY", 0.1)  # backoff base (s)
 
+# Warn once per process, not once per connection, when the WAL close-path
+# deadlock guard cannot be installed (Python < 3.12).
+_NO_CKPT_WARNED = False
+
 
 def _unbounded_facts_ceiling() -> int:
     """Hard upper bound applied when a fact fetch is called with limit=None, so
@@ -231,6 +236,37 @@ class DatabaseManager:
         conn.row_factory = sqlite3.Row
         conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
         conn.execute("PRAGMA foreign_keys=ON")
+        # wal_autocheckpoint is a PER-CONNECTION pragma and is NOT persisted in
+        # the database file (unlike journal_mode=WAL).  Setting it only on the
+        # short-lived initialisation connection left every working connection
+        # on SQLite's default of 1000 frames.  With checkpoint-on-close
+        # disabled below, autocheckpoint is the ONLY remaining checkpoint path,
+        # so the intended value must be set where the writes actually happen.
+        conn.execute("PRAGMA wal_autocheckpoint=400")
+        # Deadlock hardening (postmortem 2026-08-13, Option B): WAL close
+        # triggers a checkpoint that can wait indefinitely on reader marks
+        # pinned by another process/thread — while holding SQLite's
+        # process-global VFS mutex, which convoys every later connect().
+        # busy_timeout does NOT apply to the close path. NO_CKPT_ON_CLOSE
+        # makes close() checkpoint-free so it can never block; normal
+        # checkpointing continues via the wal_autocheckpoint set above.
+        # Available since Python 3.12 / SQLite 3.31; guarded for portability.
+        try:
+            conn.setconfig(sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, 1)  # type: ignore[attr-defined]
+        except (AttributeError, sqlite3.OperationalError):
+            # Silent degradation would hide an inactive deadlock guard on a
+            # supported interpreter (requires-python allows 3.11, which
+            # predates Connection.setconfig).  Warn once, not per connection.
+            global _NO_CKPT_WARNED
+            if not _NO_CKPT_WARNED:
+                _NO_CKPT_WARNED = True
+                logger.warning(
+                    "SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE unavailable (Python %s, "
+                    "SQLite %s); WAL close-path deadlock hardening is INACTIVE. "
+                    "Python 3.12+ is required for this protection.",
+                    platform.python_version(),
+                    sqlite3.sqlite_version,
+                )
         return conn
 
     @contextmanager
@@ -569,6 +605,62 @@ class DatabaseManager:
             created_at=d["created_at"],
         )
 
+    def insert_fact_immutable(self, fact: AtomicFact) -> str:
+        """Insert one known-new fact without content deduplication or replacement.
+
+        Reviewed correction successors require a caller-chosen immutable
+        identity.  Unlike normal remember ingestion, equal content must not
+        reinforce an existing row, and an occupied ID must abort the enclosing
+        transaction rather than overwrite history.
+        """
+        scope = getattr(fact, "scope", None) or "personal"
+        shared = _jd(getattr(fact, "shared_with", None))
+        self.execute(
+            """INSERT INTO atomic_facts
+           (fact_id, memory_id, profile_id, content, fact_type,
+            entities_json, canonical_entities_json,
+            observation_date, referenced_date, interval_start, interval_end,
+            confidence, importance, evidence_count, access_count,
+            source_turn_ids_json, session_id,
+            embedding, fisher_mean, fisher_variance,
+            lifecycle, langevin_position,
+            emotional_valence, emotional_arousal, signal_type, created_at,
+            scope, shared_with)
+           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+            (
+                fact.fact_id,
+                fact.memory_id,
+                fact.profile_id,
+                fact.content,
+                fact.fact_type.value,
+                json.dumps(fact.entities),
+                json.dumps(fact.canonical_entities),
+                fact.observation_date,
+                fact.referenced_date,
+                fact.interval_start,
+                fact.interval_end,
+                fact.confidence,
+                fact.importance,
+                fact.evidence_count,
+                fact.access_count,
+                json.dumps(fact.source_turn_ids),
+                fact.session_id,
+                _jd(fact.embedding),
+                _jd(fact.fisher_mean),
+                _jd(fact.fisher_variance),
+                fact.lifecycle.value,
+                _jd(fact.langevin_position),
+                fact.emotional_valence,
+                fact.emotional_arousal,
+                fact.signal_type.value,
+                fact.created_at,
+                scope,
+                shared,
+            ),
+        )
+        self.store_temporal_validity(fact.fact_id, fact.profile_id)
+        return fact.fact_id
+
     def set_pinned(self, fact_id: str, pinned: bool) -> None:
         """Set or clear the pinned flag on a fact (v3.4.65 core-memory)."""
         self.execute(
@@ -604,7 +696,23 @@ class DatabaseManager:
             "ORDER BY importance DESC",
             (*params,),
         )
-        return [self._row_to_fact(r) for r in rows]
+        facts = [self._row_to_fact(r) for r in rows]
+        if not facts:
+            return facts
+        try:
+            blocked = self.get_nonapplied_correction_successor_ids(
+                [fact.fact_id for fact in facts],
+                profile_id,
+                include_global=include_global,
+                include_shared=include_shared,
+            )
+        except Exception as exc:
+            logger.warning("Pinned correction admission lookup failed: %s", exc)
+            return []
+        if not isinstance(blocked, set):
+            logger.warning("Pinned correction admission returned malformed data")
+            return []
+        return [fact for fact in facts if fact.fact_id not in blocked]
 
     def _has_archive_status(self) -> bool:
         """Whether atomic_facts carries the M011 ``archive_status`` column.
@@ -1647,12 +1755,14 @@ class DatabaseManager:
     def invalidate_fact_temporal(
         self, fact_id: str, invalidated_by: str,
         invalidation_reason: str,
+        *,
+        event_valid_until: str | None = None,
     ) -> None:
         """Mark a fact as invalidated, preserving bi-temporal independence.
 
-        - valid_until (event-time): when the fact ceased to be true in the
-          real world.  Sourced from the fact's referenced_date so the
-          real-world boundary is preserved, not overwritten with wall-clock time.
+        - valid_until (event-time): changed only when a reviewer supplies an
+          independently validated real-world boundary.  Review time, source
+          timestamps, and a detector's conclusion are not a valid substitute.
         - system_expired_at (transaction-time): when the system learned the
           fact was invalid — always set to now.
 
@@ -1666,29 +1776,12 @@ class DatabaseManager:
         from datetime import datetime as _dt
         now = _dt.now(UTC).isoformat()
 
-        # Resolve the event-time boundary from the fact's referenced_date.
-        # Falls back to the current valid_until (which may already be set),
-        # and ultimately to now if neither is available.
-        fact_rows = self.execute(
-            "SELECT referenced_date FROM atomic_facts WHERE fact_id = ?",
-            (fact_id,),
-        )
-        referenced_date = dict(fact_rows[0]).get("referenced_date") if fact_rows else None
-
-        tv_rows = self.execute(
-            "SELECT valid_until FROM fact_temporal_validity WHERE fact_id = ?",
-            (fact_id,),
-        )
-        existing_valid_until = dict(tv_rows[0]).get("valid_until") if tv_rows else None
-
-        valid_until = referenced_date or existing_valid_until or now
-
         self.execute(
             "UPDATE fact_temporal_validity "
-            "SET valid_until = ?, system_expired_at = ?, "
+            "SET valid_until = COALESCE(?, valid_until), system_expired_at = ?, "
             "    invalidated_by = ?, invalidation_reason = ? "
-            "WHERE fact_id = ?",
-            (valid_until, now, invalidated_by, invalidation_reason, fact_id),
+            "WHERE fact_id = ? AND system_expired_at IS NULL",
+            (event_valid_until, now, invalidated_by, invalidation_reason, fact_id),
         )
 
     def get_valid_facts(self, profile_id: str) -> list[str]:
@@ -1804,6 +1897,119 @@ class DatabaseManager:
                 invalid.add(dict(r)["fact_id"])
         return invalid
 
+    def get_nonapplied_correction_successor_ids(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> set[str]:
+        """Return candidate successors that are not current review truth.
+
+        M042 is optional for older databases.  Its absence is safe because
+        canonical proposal never commits a successor unless the same
+        transaction also writes M042.  Once present, a read failure must reach
+        the retrieval fail-closed boundary rather than be converted to empty.
+        """
+        if not fact_ids:
+            return set()
+        present = self.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='correction_cases'"
+        )
+        if not present:
+            return set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
+        inadmissible: set[str] = set()
+        for start in range(0, len(fact_ids), 900):
+            batch = fact_ids[start:start + 900]
+            placeholders = ",".join("?" for _ in batch)
+            rows = self.execute(
+                "SELECT c.successor_fact_id FROM correction_cases c "
+                "JOIN atomic_facts f ON f.fact_id=c.successor_fact_id "
+                f"WHERE c.successor_fact_id IN ({placeholders}) AND {scope_where} "
+                "AND c.profile_id=f.profile_id "
+                "AND c.status IN ('proposed', 'rejected', 'rolled_back')",
+                (*batch, *scope_params),
+            )
+            inadmissible.update(str(row["successor_fact_id"]) for row in rows)
+        return inadmissible
+
+    def get_correction_inadmissible_fact_ids(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        as_of: str | None = None,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> set[str]:
+        """Return current-lifecycle exclusions with one bounded SQLite read.
+
+        Recall needs both sides of reviewed correction truth: an expired
+        predecessor and a successor whose case is not applied.  The older
+        public helpers preserve their focused contracts, but invoking them
+        consecutively opened two SQLite connections on every candidate stage.
+        This read-model helper uses one connection and one UNION query while
+        retaining the same profile/scope and historical ``as_of`` semantics.
+        It is intentionally read-only and does not cache lifecycle state.
+        """
+        if not fact_ids:
+            return set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
+        inadmissible: set[str] = set()
+        with self.raw_connection() as conn:
+            correction_table = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='correction_cases'"
+            ).fetchone()
+            for start in range(0, len(fact_ids), 900):
+                batch = fact_ids[start:start + 900]
+                placeholders = ",".join("?" for _ in batch)
+                temporal_conditions = (
+                    "AND tv.system_expired_at IS NOT NULL "
+                    + ("AND tv.system_expired_at <= ?" if as_of is not None else "")
+                )
+                temporal_sql = (
+                    "SELECT tv.fact_id AS fact_id "
+                    "FROM fact_temporal_validity tv "
+                    "JOIN atomic_facts f ON f.fact_id=tv.fact_id "
+                    f"WHERE tv.fact_id IN ({placeholders}) AND {scope_where} "
+                    "AND tv.profile_id=f.profile_id "
+                    f"{temporal_conditions}"
+                )
+                temporal_params: tuple[Any, ...] = (
+                    *batch,
+                    *scope_params,
+                    *((as_of,) if as_of is not None else ()),
+                )
+                if correction_table is None:
+                    rows = conn.execute(temporal_sql, temporal_params).fetchall()
+                else:
+                    correction_sql = (
+                        "SELECT c.successor_fact_id AS fact_id "
+                        "FROM correction_cases c "
+                        "JOIN atomic_facts f ON f.fact_id=c.successor_fact_id "
+                        f"WHERE c.successor_fact_id IN ({placeholders}) AND {scope_where} "
+                        "AND c.profile_id=f.profile_id "
+                        "AND c.status IN ('proposed', 'rejected', 'rolled_back')"
+                    )
+                    rows = conn.execute(
+                        f"{temporal_sql} UNION {correction_sql}",
+                        (*temporal_params, *batch, *scope_params),
+                    ).fetchall()
+                inadmissible.update(str(row["fact_id"]) for row in rows)
+        return inadmissible
+
     def get_strict_temporal_inadmissible_fact_ids(
         self,
         fact_ids: list[str],

package/src/superlocalmemory/storage/migration_runner.py

@@ -157,6 +157,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M041_external_evidence_receipts as _M041,
 )
+from superlocalmemory.storage.migrations import (
+    M042_correction_case_ledger as _M042,
+)
 from superlocalmemory.storage._schema_version import (
     SUPPORTED_SCHEMA_VERSION,
     SchemaVersionError,
@@ -239,6 +242,10 @@ MIGRATIONS: list[Migration] = [
               dependencies=(_M003.NAME,)),
     Migration(name=_M041.NAME, db_target="learning", ddl=_M041.DDL,
               dependencies=(_M040.NAME,)),
+    # Review-gated correction metadata is self-contained in memory.db. It
+    # contains identifiers only and does not alter temporal fact state.
+    Migration(name=_M042.NAME, db_target="memory", ddl=_M042.DDL,
+              dependencies=(_M032.NAME,)),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]
 

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

@@ -0,0 +1,245 @@
+"""M042 — review-gated correction cases in ``memory.db``.
+
+The ledger contains identifiers and lifecycle metadata only.  It never stores
+fact text.  The saved predecessor temporal tuple lets a reviewed rollback
+restore the exact lifecycle state without deleting fact history.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M042_correction_case_ledger"
+DB_TARGET = "memory"
+
+DDL = """
+BEGIN IMMEDIATE;
+CREATE TABLE IF NOT EXISTS correction_cases (
+    case_id TEXT PRIMARY KEY,
+    profile_id TEXT NOT NULL,
+    scope TEXT NOT NULL CHECK (scope IN ('personal', 'project', 'shared', 'global')),
+    predecessor_fact_id TEXT NOT NULL,
+    successor_fact_id TEXT NOT NULL,
+    reason_code TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('proposed', 'applied', 'rejected', 'rolled_back')),
+    version INTEGER NOT NULL CHECK (version >= 0),
+    idempotency_key TEXT NOT NULL,
+    proposed_by_actor_id TEXT NOT NULL,
+    proposed_by_actor_kind TEXT NOT NULL,
+    proposed_by_trust_tier TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    reviewed_by_actor_id TEXT,
+    reviewed_at TEXT,
+    applied_at TEXT,
+    system_effective_at TEXT,
+    event_valid_from TEXT,
+    event_valid_until TEXT,
+    predecessor_temporal_existed INTEGER,
+    predecessor_valid_from TEXT,
+    predecessor_valid_until TEXT,
+    predecessor_system_created_at TEXT,
+    predecessor_system_expired_at TEXT,
+    predecessor_invalidated_by TEXT,
+    predecessor_invalidation_reason TEXT,
+    UNIQUE (profile_id, idempotency_key),
+    FOREIGN KEY (predecessor_fact_id) REFERENCES atomic_facts(fact_id) ON DELETE RESTRICT,
+    FOREIGN KEY (successor_fact_id) REFERENCES atomic_facts(fact_id) ON DELETE RESTRICT
+);
+CREATE TABLE IF NOT EXISTS correction_events (
+    event_id TEXT PRIMARY KEY,
+    case_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL,
+    scope TEXT NOT NULL CHECK (scope IN ('personal', 'project', 'shared', 'global')),
+    event_type TEXT NOT NULL
+        CHECK (event_type IN ('proposed', 'applied', 'rejected', 'rolled_back')),
+    operation_id TEXT NOT NULL,
+    actor_id TEXT NOT NULL,
+    actor_kind TEXT NOT NULL,
+    actor_trust_tier TEXT NOT NULL,
+    expected_version INTEGER,
+    resulting_version INTEGER NOT NULL CHECK (resulting_version >= 0),
+    system_occurred_at TEXT NOT NULL,
+    event_valid_from TEXT,
+    event_valid_until TEXT,
+    UNIQUE (case_id, operation_id),
+    FOREIGN KEY (case_id) REFERENCES correction_cases(case_id) ON DELETE RESTRICT
+);
+CREATE INDEX IF NOT EXISTS idx_correction_cases_profile_status
+    ON correction_cases (profile_id, status, updated_at DESC);
+CREATE INDEX IF NOT EXISTS idx_correction_events_case_sequence
+    ON correction_events (case_id, system_occurred_at ASC);
+CREATE INDEX IF NOT EXISTS idx_correction_cases_successor_admission
+    ON correction_cases (profile_id, successor_fact_id, status);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_correction_cases_active_predecessor
+    ON correction_cases (profile_id, predecessor_fact_id)
+    WHERE status IN ('proposed', 'applied');
+COMMIT;
+"""
+
+_TABLES = frozenset({"correction_cases", "correction_events"})
+_FORBIDDEN_RAW_COLUMNS = frozenset({"content", "fact_text", "raw_text", "query"})
+_REQUIRED_CASE_COLUMNS = frozenset(
+    {
+        "case_id",
+        "profile_id",
+        "scope",
+        "predecessor_fact_id",
+        "successor_fact_id",
+        "reason_code",
+        "status",
+        "version",
+        "idempotency_key",
+        "proposed_by_actor_id",
+        "proposed_by_actor_kind",
+        "proposed_by_trust_tier",
+        "created_at",
+        "updated_at",
+        "reviewed_by_actor_id",
+        "reviewed_at",
+        "applied_at",
+        "system_effective_at",
+        "event_valid_from",
+        "event_valid_until",
+        "predecessor_temporal_existed",
+        "predecessor_valid_from",
+        "predecessor_valid_until",
+        "predecessor_system_created_at",
+        "predecessor_system_expired_at",
+        "predecessor_invalidated_by",
+        "predecessor_invalidation_reason",
+    }
+)
+_REQUIRED_EVENT_COLUMNS = frozenset(
+    {
+        "event_id",
+        "case_id",
+        "profile_id",
+        "scope",
+        "event_type",
+        "operation_id",
+        "actor_id",
+        "actor_kind",
+        "actor_trust_tier",
+        "expected_version",
+        "resulting_version",
+        "system_occurred_at",
+        "event_valid_from",
+        "event_valid_until",
+    }
+)
+_INDEX_SPECS = {
+    "idx_correction_cases_profile_status": (
+        "correction_cases",
+        ("profile_id", "status", "updated_at"),
+        False,
+        None,
+    ),
+    "idx_correction_events_case_sequence": (
+        "correction_events",
+        ("case_id", "system_occurred_at"),
+        False,
+        None,
+    ),
+    "idx_correction_cases_successor_admission": (
+        "correction_cases",
+        ("profile_id", "successor_fact_id", "status"),
+        False,
+        None,
+    ),
+    "uq_correction_cases_active_predecessor": (
+        "correction_cases",
+        ("profile_id", "predecessor_fact_id"),
+        True,
+        "wherestatusin('proposed','applied')",
+    ),
+}
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Install the additive review ledger atomically and idempotently."""
+    if any(_table_exists(conn, table) for table in _TABLES) and not verify(conn):
+        raise sqlite3.OperationalError("M042 correction ledger is malformed; refusing rebuild")
+    conn.executescript(DDL)
+    if not verify(conn):
+        raise sqlite3.OperationalError("M042 correction ledger did not reach its end-state")
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    if not all(_table_exists(conn, table) for table in _TABLES):
+        return False
+    case_columns = _columns(conn, "correction_cases")
+    event_columns = _columns(conn, "correction_events")
+    if (
+        set(case_columns) != _REQUIRED_CASE_COLUMNS
+        or set(event_columns) != _REQUIRED_EVENT_COLUMNS
+        or _FORBIDDEN_RAW_COLUMNS & (set(case_columns) | set(event_columns))
+    ):
+        return False
+    if not _required_checks_present(conn):
+        return False
+    return all(_index_matches(conn, name, *spec) for name, spec in _INDEX_SPECS.items())
+
+
+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 _columns(conn: sqlite3.Connection, table: str) -> tuple[str, ...]:
+    return tuple(row[1] for row in conn.execute(f"PRAGMA table_info({table})"))
+
+
+def _required_checks_present(conn: sqlite3.Connection) -> bool:
+    statements: dict[str, str] = {}
+    for table in ("correction_cases", "correction_events"):
+        row = conn.execute(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (table,)
+        ).fetchone()
+        if row is None or row[0] is None:
+            return False
+        statements[table] = "".join(str(row[0]).lower().split())
+    case_sql = statements["correction_cases"]
+    event_sql = statements["correction_events"]
+    scope_check = "check(scopein('personal','project','shared','global'))"
+    return (
+        scope_check in case_sql
+        and scope_check in event_sql
+        and "check(statusin('proposed','applied','rejected','rolled_back'))" in case_sql
+        and "check(event_typein('proposed','applied','rejected','rolled_back'))" in event_sql
+        and "unique(profile_id,idempotency_key)" in case_sql
+        and "unique(case_id,operation_id)" in event_sql
+    )
+
+
+def _index_matches(
+    conn: sqlite3.Connection,
+    name: str,
+    table: str,
+    columns: tuple[str, ...],
+    unique: bool,
+    where_clause: str | None,
+) -> bool:
+    """Verify an index's table, ordered columns, uniqueness, and partial predicate."""
+    row = conn.execute(
+        "SELECT tbl_name, sql FROM sqlite_master WHERE type='index' AND name=?", (name,)
+    ).fetchone()
+    if row is None or row[0] != table:
+        return False
+    index_rows = conn.execute(f"PRAGMA index_xinfo({name})").fetchall()
+    indexed_columns = tuple(
+        entry[2] for entry in index_rows if entry[5] == 1 and entry[2] is not None
+    )
+    if indexed_columns != columns:
+        return False
+    index_list = conn.execute(f"PRAGMA index_list({table})").fetchall()
+    indexed = next((entry for entry in index_list if entry[1] == name), None)
+    if indexed is None or bool(indexed[2]) is not unique:
+        return False
+    if where_clause is None:
+        return True
+    return row[1] is not None and where_clause in "".join(str(row[1]).lower().split())

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

@@ -32,6 +32,7 @@ from . import (
     M039_scene_fact_members,
     M040_agent_experience_receipts,
     M041_external_evidence_receipts,
+    M042_correction_case_ledger,
 )
 
 # ---------------------------------------------------------------------------
@@ -89,6 +90,7 @@ __all__ = (
     "M039_scene_fact_members",
     "M040_agent_experience_receipts",
     "M041_external_evidence_receipts",
+    "M042_correction_case_ledger",
     # Legacy re-exports (backward compat):
     "CURRENT_SCHEMA_VERSION",
     "get_schema_version",

package/src/superlocalmemory/storage/models.py

@@ -73,11 +73,19 @@ class SignalType(str, Enum):
 
 
 class Mode(str, Enum):
-    """Operating modes — EU AI Act alignment."""
+    """Operating modes.
+
+    A — All data stays on this device. No AI language model runs anywhere.
+        Fastest and most private.
+    B — All data stays on this device. Uses a local Ollama AI model to
+        improve recall quality. Requires Ollama to be installed and running.
+    C — Uses a cloud AI provider (OpenAI, Anthropic, …) for the best recall
+        quality. Queries leave this device; an API key is required.
+    """
 
-    A = "a"  # Local Guardian: zero LLM, EU AI Act FULL
-    B = "b"  # Smart Local: local Ollama LLM, EU AI Act FULL
-    C = "c"  # Full Power: UNRESTRICTED, best models, 90%+ target
+    A = "a"  # Local Guardian — on-device only, no LLM
+    B = "b"  # Smart Local — on-device + local Ollama LLM, no cloud
+    C = "c"  # Cloud LLM — best accuracy, queries leave device, API key needed
 
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/storage/write_coordinator.py

@@ -96,6 +96,10 @@ class CommandKind(StrEnum):
     ADMISSION = "admission"
     DELETE_FACT = "delete_fact"
     UPDATE_FACT = "update_fact"
+    PROPOSE_CORRECTION = "propose_correction"
+    APPLY_CORRECTION = "apply_correction"
+    REJECT_CORRECTION = "reject_correction"
+    ROLLBACK_CORRECTION = "rollback_correction"
     ARCHIVE_FACT = "archive_fact"
     MERGE_FACT = "merge_fact"
     SET_FACT_SCOPE = "set_fact_scope"

package/src/superlocalmemory/summaries/__init__.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory issue #113 — Personal Memory Views.
+
+Three bounded, profile-scoped, traceable summaries:
+
+  Session Summary    — what happened in a specific session (data is sparse:
+                       only ~3.9% of facts carry a session_id on a real store;
+                       coverage is always disclosed explicitly).
+  Daily Reflection   — what was recorded on a specific date.
+  Project Work Log   — what tool events and facts belong to a project,
+                       scoped by tool_events.project_path (NOT by
+                       entity_profiles.project_name, which has one distinct
+                       value across 1,148 rows and is useless for scoping).
+
+Every SummaryResult carries:
+  - source_fact_ids  for traceability (maintainer's binding constraint)
+  - profile_id       — cross-profile access is not permitted
+  - coverage         — honest assessment; never silently partial
+
+Deferred to 4.0.7: prompt-driven custom views.  They are non-deterministic,
+hard to make traceable, and a prompt-injection surface.
+"""
+
+from .base import SummaryResult
+from .daily_reflection import generate_daily_reflection
+from .project_work_log import generate_project_work_log
+from .session_summary import generate_session_summary
+
+__all__ = [
+    "SummaryResult",
+    "generate_session_summary",
+    "generate_daily_reflection",
+    "generate_project_work_log",
+]