superlocalmemory 4.0.1 → 4.0.2

package/src/superlocalmemory/storage/database.py

@@ -489,11 +489,19 @@ class DatabaseManager:
                 # writes target the canonical fact (idempotent), not an
                 # orphaned id that was never inserted.
                 fact.fact_id = canonical_id
+                # Repair the only recoverable interrupted-write state from an
+                # early 4.0.2 attempt: a durable fact without its mandatory
+                # knowledge-time anchor. Do not manufacture a historical
+                # timestamp from ``created_at``; this retry is the earliest
+                # trustworthy observation that the anchor was missing.
+                if self.get_temporal_validity(canonical_id, fact.profile_id) is None:
+                    self.store_temporal_validity(canonical_id, fact.profile_id)
                 return canonical_id
         _scope = getattr(fact, 'scope', None) or 'personal'
         _shared = _jd(getattr(fact, 'shared_with', None))
-        self.execute(
-            """INSERT OR REPLACE INTO atomic_facts
+        def _insert_with_knowledge_anchor() -> None:
+            self.execute(
+                """INSERT OR REPLACE 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,
@@ -504,18 +512,30 @@ class DatabaseManager:
                 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),
-        )
+                (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),
+            )
+            # Every fact written after 4.0.2 has an explicit transaction-time
+            # anchor. Absence deliberately represents pre-4.0.2
+            # ``legacy_unknown``; never backfill it from ``created_at``.
+            self.store_temporal_validity(fact.fact_id, fact.profile_id)
+
+        # The fact and its transaction-time anchor are one logical write. Do
+        # not open a nested transaction when an owner already holds one.
+        if getattr(self._txn_state, "conn", None) is not None:
+            _insert_with_knowledge_anchor()
+        else:
+            with self.transaction():
+                _insert_with_knowledge_anchor()
         return fact.fact_id
 
     def _row_to_fact(self, row: sqlite3.Row) -> AtomicFact:
@@ -561,14 +581,26 @@ class DatabaseManager:
         include_global: bool = False,
         include_shared: bool = False,
     ) -> list[AtomicFact]:
-        """Return all pinned facts for a profile, highest-importance first."""
+        """Return currently admissible pinned facts, highest-importance first.
+
+        Pins are injection priority, not an override for a later correction.
+        A system-invalidated fact remains durable and historically queryable,
+        but it must not be inserted into the current session context.
+        """
         where, params = _scope_where(
             profile_id,
             include_global=include_global,
             include_shared=include_shared,
+            prefix="f",
         )
         rows = self.execute(
-            f"SELECT * FROM atomic_facts WHERE {where} AND pinned = 1 "
+            f"SELECT f.* FROM atomic_facts f WHERE {where} AND f.pinned = 1 "
+            "AND NOT EXISTS ("
+            "    SELECT 1 FROM fact_temporal_validity tv "
+            "    WHERE tv.fact_id = f.fact_id "
+            "      AND tv.profile_id = f.profile_id "
+            "      AND tv.system_expired_at IS NOT NULL"
+            ") "
             "ORDER BY importance DESC",
             (*params,),
         )
@@ -1566,13 +1598,29 @@ class DatabaseManager:
         valid_from: str | None = None,
         valid_until: str | None = None,
     ) -> None:
-        """Create temporal validity record for a fact."""
+        """Create or enrich the temporal record for a fact.
+
+        The 4.0.2 fact writer creates the record immediately to anchor
+        transaction time. A later temporal extraction may add event-time bounds;
+        it must not be discarded merely because the anchor already exists.
+        """
+        from datetime import UTC
+        from datetime import datetime as _dt
+        system_created_at = _dt.now(UTC).isoformat()
         self.execute(
             "INSERT OR IGNORE INTO fact_temporal_validity "
-            "(fact_id, profile_id, valid_from, valid_until) "
-            "VALUES (?, ?, ?, ?)",
-            (fact_id, profile_id, valid_from, valid_until),
+            "(fact_id, profile_id, valid_from, valid_until, system_created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (fact_id, profile_id, valid_from, valid_until, system_created_at),
         )
+        if valid_from is not None or valid_until is not None:
+            self.execute(
+                "UPDATE fact_temporal_validity "
+                "SET valid_from = COALESCE(?, valid_from), "
+                "    valid_until = COALESCE(?, valid_until) "
+                "WHERE fact_id = ? AND profile_id = ?",
+                (valid_from, valid_until, fact_id, profile_id),
+            )
 
     def get_temporal_validity(self, fact_id: str, profile_id: str | None = None) -> dict | None:
         """Get temporal validity record for a fact (C4: optionally tenant-scoped)."""
@@ -1674,6 +1722,9 @@ class DatabaseManager:
         fact_ids: list[str],
         profile_id: str,
         as_of: str | None = None,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
     ) -> set[str]:
         """Return the subset of ``fact_ids`` that are system-invalidated.
 
@@ -1700,9 +1751,12 @@ class DatabaseManager:
         Bounded + indexed: only the supplied candidate ids are queried (never a
         full-table scan), keyed on the ``fact_id`` PK with the
         ``idx_temporal_system_expired`` index covering the predicate. Chunked to
-        stay well under SQLite's ~999 bound-parameter limit. Facts with no
-        temporal record — or a record whose ``system_expired_at`` is NULL — are
-        NOT returned (treated as valid), so existing DBs need no backfill.
+        stay well under SQLite's ~999 bound-parameter limit. The visibility
+        predicate is evaluated on the fact owner's row, so an opted-in global or
+        shared fact is checked against *its owner's* temporal record rather than
+        incorrectly against the requesting profile. Facts with no temporal
+        record — or a record whose ``system_expired_at`` is NULL — are NOT
+        returned (treated as valid), so existing DBs need no backfill.
 
         Event-time expiry (``valid_until`` in the past) is intentionally NOT
         applied here: it is query-scoped (historical queries legitimately want
@@ -1712,6 +1766,12 @@ class DatabaseManager:
         if not fact_ids:
             return set()
         invalid: set[str] = set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
         chunk = 900
         for start in range(0, len(fact_ids), chunk):
             batch = fact_ids[start:start + chunk]
@@ -1721,25 +1781,120 @@ class DatabaseManager:
                 # occurred AT OR BEFORE as_of contribute to invalidation.
                 # Supersessions after as_of are invisible at this query point.
                 rows = self.execute(
-                    f"SELECT fact_id FROM fact_temporal_validity "
-                    f"WHERE fact_id IN ({placeholders}) "
-                    f"  AND profile_id = ? "
-                    f"  AND system_expired_at IS NOT NULL "
-                    f"  AND system_expired_at <= ?",
-                    (*batch, profile_id, as_of),
+                    f"SELECT tv.fact_id FROM fact_temporal_validity tv "
+                    f"JOIN atomic_facts f ON f.fact_id = tv.fact_id "
+                    f"WHERE tv.fact_id IN ({placeholders}) "
+                    f"  AND {scope_where} "
+                    f"  AND tv.profile_id = f.profile_id "
+                    f"  AND tv.system_expired_at IS NOT NULL "
+                    f"  AND tv.system_expired_at <= ?",
+                    (*batch, *scope_params, as_of),
                 )
             else:
                 rows = self.execute(
-                    f"SELECT fact_id FROM fact_temporal_validity "
-                    f"WHERE fact_id IN ({placeholders}) "
-                    f"  AND profile_id = ? "
-                    f"  AND system_expired_at IS NOT NULL",
-                    (*batch, profile_id),
+                    f"SELECT tv.fact_id FROM fact_temporal_validity tv "
+                    f"JOIN atomic_facts f ON f.fact_id = tv.fact_id "
+                    f"WHERE tv.fact_id IN ({placeholders}) "
+                    f"  AND {scope_where} "
+                    f"  AND tv.profile_id = f.profile_id "
+                    f"  AND tv.system_expired_at IS NOT NULL",
+                    (*batch, *scope_params),
                 )
             for r in rows:
                 invalid.add(dict(r)["fact_id"])
         return invalid
 
+    def get_strict_temporal_inadmissible_fact_ids(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        *,
+        known_as_of: str | None = None,
+        valid_at: str | None = None,
+        include_unknown: bool = False,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> set[str]:
+        """Return candidates excluded by an explicit two-clock query.
+
+        ``known_as_of`` is transaction time: it asks what this SLM instance had
+        learned by a timestamp. ``valid_at`` is event time: it asks what was
+        true at a timestamp according to the requested knowledge state. The
+        axes are independent and may be supplied separately or together.
+
+        A fact with no temporal row predates the 4.0.2 write invariant and is
+        ``legacy_unknown``. Strict time-travel excludes it unless the caller
+        explicitly asks to include unknown history. This is intentionally
+        bounded to the already-retrieved candidate pool.
+        """
+        if not fact_ids or (known_as_of is None and valid_at is None):
+            return set()
+        from datetime import datetime as _dt
+        from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+
+        def _parse_timestamp(value: object) -> _dt | None:
+            normalized = normalize_as_of(value)
+            return _dt.fromisoformat(normalized) if normalized is not None else None
+
+        known_boundary = _parse_timestamp(known_as_of) if known_as_of is not None else None
+        valid_boundary = _parse_timestamp(valid_at) if valid_at is not None else None
+        inadmissible: set[str] = set()
+        scope_where, scope_params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="f",
+        )
+        chunk = 900
+        for start in range(0, len(fact_ids), chunk):
+            batch = fact_ids[start:start + chunk]
+            placeholders = ",".join("?" for _ in batch)
+            rows = self.execute(
+                f"SELECT f.fact_id, tv.fact_id AS temporal_fact_id, "
+                f"tv.system_created_at, tv.system_expired_at, "
+                f"tv.valid_from, tv.valid_until FROM atomic_facts f "
+                f"LEFT JOIN fact_temporal_validity tv "
+                f"  ON tv.fact_id = f.fact_id AND tv.profile_id = f.profile_id "
+                f"WHERE f.fact_id IN ({placeholders}) "
+                f"  AND {scope_where}",
+                (*batch, *scope_params),
+            )
+            for row in rows:
+                values = dict(row)
+                has_temporal_record = values["temporal_fact_id"] is not None
+                if not has_temporal_record:
+                    if not include_unknown:
+                        inadmissible.add(values["fact_id"])
+                    continue
+                unknown = False
+                if known_boundary is not None:
+                    created = _parse_timestamp(values["system_created_at"])
+                    expired = _parse_timestamp(values["system_expired_at"])
+                    if created is None:
+                        unknown = True
+                    elif created > known_boundary:
+                        inadmissible.add(values["fact_id"])
+                        continue
+                    elif expired is not None and expired <= known_boundary:
+                        inadmissible.add(values["fact_id"])
+                        continue
+                if valid_boundary is not None:
+                    valid_from = _parse_timestamp(values["valid_from"])
+                    valid_until = _parse_timestamp(values["valid_until"])
+                    if values["valid_from"] is not None and valid_from is None:
+                        unknown = True
+                    elif valid_from is not None and valid_from > valid_boundary:
+                        inadmissible.add(values["fact_id"])
+                        continue
+                    if values["valid_until"] is not None and valid_until is None:
+                        unknown = True
+                    elif valid_until is not None and valid_until <= valid_boundary:
+                        inadmissible.add(values["fact_id"])
+                        continue
+                if unknown and not include_unknown:
+                    inadmissible.add(values["fact_id"])
+        return inadmissible
+
     def get_event_time_expired_fact_ids(
         self,
         fact_ids: list[str],

package/src/superlocalmemory/storage/migration_runner.py

@@ -151,6 +151,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M039_scene_fact_members as _M039,
 )
+from superlocalmemory.storage.migrations import (
+    M040_agent_experience_receipts as _M040,
+)
 from superlocalmemory.storage._schema_version import (
     SUPPORTED_SCHEMA_VERSION,
     SchemaVersionError,
@@ -226,6 +229,11 @@ MIGRATIONS: list[Migration] = [
     # channel patterns.
     Migration(name=_M038.NAME, db_target="learning", ddl=_M038.DDL,
               dependencies=(_M003.NAME,)),
+    # Receipt writes are a learning-plane concern and must never share the
+    # memory.db recall lock domain.  The tables are self-contained: profile
+    # lifecycle performs explicit cross-store erasure rather than an FK.
+    Migration(name=_M040.NAME, db_target="learning", ddl=_M040.DDL,
+              dependencies=(_M003.NAME,)),
     # M006 + M011 are deliberately NOT here — see DEFERRED_MIGRATIONS below.
 ]
 

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

@@ -38,3 +38,21 @@ CREATE INDEX IF NOT EXISTS idx_facts_pinned
     ON atomic_facts(profile_id, pinned);
 COMMIT;
 """
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Apply M015 safely when a fresh schema already contains ``pinned``.
+
+    New installations are created from the current base schema, whereas
+    upgrades need the additive ALTER. SQLite has no ``ADD COLUMN IF NOT
+    EXISTS``, so the old static migration failed on fresh databases.
+    """
+    cols = {row[1] for row in conn.execute("PRAGMA table_info(atomic_facts)")}
+    if "pinned" not in cols:
+        conn.execute(
+            "ALTER TABLE atomic_facts ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0"
+        )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_facts_pinned "
+        "ON atomic_facts(profile_id, pinned)"
+    )

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

@@ -0,0 +1,254 @@
+"""M040 — profile-scoped Agent Experience receipts in ``learning.db``.
+
+The receipt plane deliberately has no foreign keys into ``memory.db``.  It is
+therefore not part of recall's lock domain: profile lifecycle coordinates its
+cross-store erasure as a retryable saga instead of using ``ATTACH``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M040_agent_experience_receipts"
+DB_TARGET = "learning"
+
+DDL = """
+BEGIN IMMEDIATE;
+CREATE TABLE IF NOT EXISTS agent_experiences (
+    profile_id TEXT NOT NULL,
+    experience_id TEXT NOT NULL,
+    occurred_at TEXT NOT NULL,
+    task_class TEXT NOT NULL,
+    project_scope TEXT NOT NULL,
+    route_json TEXT NOT NULL,
+    verification_authority TEXT NOT NULL,
+    verification_digest TEXT NOT NULL,
+    verification_reference TEXT,
+    producer_claim TEXT NOT NULL,
+    terminal_status TEXT NOT NULL,
+    failure_class TEXT,
+    human_intervention INTEGER CHECK (human_intervention IN (0, 1)),
+    lessons TEXT,
+    receipt_digest TEXT,
+    artifact_digests_json TEXT NOT NULL,
+    payload_sha256 TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, experience_id)
+);
+CREATE TABLE IF NOT EXISTS cognitive_turn_receipts (
+    profile_id TEXT NOT NULL,
+    receipt_id TEXT NOT NULL,
+    task_id TEXT NOT NULL,
+    project_scope TEXT NOT NULL,
+    query_digest TEXT NOT NULL,
+    fact_decisions_json TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('open', 'finalized', 'abandoned', 'reconciled')),
+    outcome_json TEXT,
+    payload_sha256 TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, receipt_id)
+);
+CREATE TABLE IF NOT EXISTS agent_receipt_profile_closures (
+    profile_id TEXT PRIMARY KEY,
+    closed_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agent_experiences_profile_occurred
+    ON agent_experiences (profile_id, occurred_at DESC);
+CREATE INDEX IF NOT EXISTS idx_agent_experiences_profile_project_occurred
+    ON agent_experiences (profile_id, project_scope, occurred_at DESC);
+CREATE INDEX IF NOT EXISTS idx_cognitive_turns_profile_task_updated
+    ON cognitive_turn_receipts (profile_id, task_id, updated_at DESC);
+CREATE INDEX IF NOT EXISTS idx_cognitive_turns_profile_state_updated
+    ON cognitive_turn_receipts (profile_id, state, updated_at DESC);
+COMMIT;
+"""
+
+_TABLE_COLUMNS = {
+    "agent_experiences": (
+        "profile_id",
+        "experience_id",
+        "occurred_at",
+        "task_class",
+        "project_scope",
+        "route_json",
+        "verification_authority",
+        "verification_digest",
+        "verification_reference",
+        "producer_claim",
+        "terminal_status",
+        "failure_class",
+        "human_intervention",
+        "lessons",
+        "receipt_digest",
+        "artifact_digests_json",
+        "payload_sha256",
+        "created_at",
+    ),
+    "cognitive_turn_receipts": (
+        "profile_id",
+        "receipt_id",
+        "task_id",
+        "project_scope",
+        "query_digest",
+        "fact_decisions_json",
+        "state",
+        "outcome_json",
+        "payload_sha256",
+        "created_at",
+        "updated_at",
+    ),
+    "agent_receipt_profile_closures": ("profile_id", "closed_at"),
+}
+_PRIMARY_KEYS = {
+    "agent_experiences": ("profile_id", "experience_id"),
+    "cognitive_turn_receipts": ("profile_id", "receipt_id"),
+    "agent_receipt_profile_closures": ("profile_id",),
+}
+_COLUMN_TYPES = {
+    "agent_experiences": (
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "INTEGER",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+        "TEXT",
+    ),
+    "cognitive_turn_receipts": ("TEXT",) * len(_TABLE_COLUMNS["cognitive_turn_receipts"]),
+    "agent_receipt_profile_closures": ("TEXT", "TEXT"),
+}
+_REQUIRED_NOT_NULL = {
+    "agent_experiences": frozenset(_TABLE_COLUMNS["agent_experiences"])
+    - {
+        "verification_reference",
+        "failure_class",
+        "human_intervention",
+        "lessons",
+        "receipt_digest",
+    },
+    "cognitive_turn_receipts": frozenset(_TABLE_COLUMNS["cognitive_turn_receipts"])
+    - {"outcome_json"},
+    "agent_receipt_profile_closures": frozenset(_TABLE_COLUMNS["agent_receipt_profile_closures"]),
+}
+_INDEXES = {
+    "idx_agent_experiences_profile_occurred": ("agent_experiences", ("profile_id", "occurred_at")),
+    "idx_agent_experiences_profile_project_occurred": (
+        "agent_experiences",
+        ("profile_id", "project_scope", "occurred_at"),
+    ),
+    "idx_cognitive_turns_profile_task_updated": (
+        "cognitive_turn_receipts",
+        ("profile_id", "task_id", "updated_at"),
+    ),
+    "idx_cognitive_turns_profile_state_updated": (
+        "cognitive_turn_receipts",
+        ("profile_id", "state", "updated_at"),
+    ),
+}
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Atomically install M040 or leave the learning DB unchanged."""
+    if verify(conn):
+        return
+    if _tables_are_malformed(conn):
+        raise sqlite3.OperationalError("M040 receipt tables are malformed; refusing rebuild")
+    if all(name in _tables(conn) for name in _TABLE_COLUMNS):
+        repair(conn)
+        return
+    conn.executescript(DDL)
+    if not verify(conn):
+        # A pre-existing same-named index can make CREATE INDEX IF NOT EXISTS
+        # a no-op even though that index belongs to another table. Rebuild the
+        # derived index set transactionally after all required tables exist.
+        repair(conn)
+    if not verify(conn):
+        raise sqlite3.OperationalError("M040 schema did not reach its required end-state")
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Restore missing/wrong indexes only; never rebuild user evidence."""
+    if _tables_are_malformed(conn):
+        raise sqlite3.OperationalError("M040 receipt tables are malformed; refusing rebuild")
+    if not all(name in _tables(conn) for name in _TABLE_COLUMNS):
+        apply(conn)
+        return
+    drops = "\n".join(f"DROP INDEX IF EXISTS {name};" for name in _INDEXES)
+    creates = "\n".join(
+        f"CREATE INDEX {name} ON {table} ({', '.join(columns)});"
+        for name, (table, columns) in _INDEXES.items()
+    )
+    conn.executescript(f"BEGIN IMMEDIATE;\n{drops}\n{creates}\nCOMMIT;")
+    if not verify(conn):
+        raise sqlite3.OperationalError("M040 index repair did not restore required end-state")
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    return not _tables_are_malformed(conn) and all(
+        _index_columns(conn, name) == columns for name, (_, columns) in _INDEXES.items()
+    )
+
+
+def _tables_are_malformed(conn: sqlite3.Connection) -> bool:
+    tables = _tables(conn)
+    for table, columns in _TABLE_COLUMNS.items():
+        if table not in tables:
+            continue
+        info = conn.execute(f"PRAGMA table_info({table})").fetchall()
+        actual = tuple(row[1] for row in info)
+        types = tuple(str(row[2]).upper() for row in info)
+        primary_key = tuple(row[1] for row in sorted(info, key=lambda row: row[5]) if row[5])
+        not_null = {row[1] for row in info if row[3] or row[5]}
+        if (
+            actual != columns
+            or types != _COLUMN_TYPES[table]
+            or primary_key != _PRIMARY_KEYS[table]
+            or not_null != _REQUIRED_NOT_NULL[table]
+            or not _required_checks_present(conn, table)
+        ):
+            return True
+        if conn.execute(f"PRAGMA foreign_key_list({table})").fetchone() is not None:
+            return True
+    return False
+
+
+def _tables(conn: sqlite3.Connection) -> set[str]:
+    return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+
+
+def _index_columns(conn: sqlite3.Connection, name: str) -> tuple[str, ...] | None:
+    row = conn.execute(
+        "SELECT tbl_name FROM sqlite_master WHERE type='index' AND name=?", (name,)
+    ).fetchone()
+    expected = _INDEXES.get(name)
+    if row is None or expected is None or row[0] != expected[0]:
+        return None
+    return tuple(
+        row[2]
+        for row in conn.execute(f"PRAGMA index_xinfo({name})")
+        if row[5] and row[2] is not None
+    )
+
+
+def _required_checks_present(conn: sqlite3.Connection, table: str) -> bool:
+    sql_row = conn.execute(
+        "SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone()
+    sql = "" if sql_row is None or sql_row[0] is None else "".join(str(sql_row[0]).lower().split())
+    if table == "agent_experiences":
+        return "check(human_interventionin(0,1))" in sql
+    if table == "cognitive_turn_receipts":
+        return "check(statein('open','finalized','abandoned','reconciled'))" in sql
+    return True

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

@@ -30,6 +30,7 @@ from . import (
     M030_entity_explorer_indexes,
     M038_learning_feedback_channel,
     M039_scene_fact_members,
+    M040_agent_experience_receipts,
 )
 
 # ---------------------------------------------------------------------------
@@ -85,6 +86,7 @@ __all__ = (
     "M030_entity_explorer_indexes",
     "M038_learning_feedback_channel",
     "M039_scene_fact_members",
+    "M040_agent_experience_receipts",
     # Legacy re-exports (backward compat):
     "CURRENT_SCHEMA_VERSION",
     "get_schema_version",

package/src/superlocalmemory/storage/schema.py

@@ -171,6 +171,8 @@ CREATE TABLE IF NOT EXISTS atomic_facts (
     importance         REAL NOT NULL DEFAULT 0.5,
     evidence_count     INTEGER NOT NULL DEFAULT 1,
     access_count       INTEGER NOT NULL DEFAULT 0,
+    -- Core-memory injection priority (M015 on upgraded databases)
+    pinned             INTEGER NOT NULL DEFAULT 0,
 
     -- Source tracing
     source_turn_ids_json TEXT NOT NULL DEFAULT '[]',
@@ -213,6 +215,8 @@ CREATE INDEX IF NOT EXISTS idx_facts_type
     ON atomic_facts (profile_id, fact_type);
 CREATE INDEX IF NOT EXISTS idx_facts_lifecycle
     ON atomic_facts (profile_id, lifecycle);
+CREATE INDEX IF NOT EXISTS idx_facts_pinned
+    ON atomic_facts (profile_id, pinned);
 CREATE INDEX IF NOT EXISTS idx_facts_session
     ON atomic_facts (profile_id, session_id);
 CREATE INDEX IF NOT EXISTS idx_facts_referenced_date