superlocalmemory 4.0.10 → 4.1.2

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

@@ -0,0 +1,127 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""M044 — a bandit play records which memories it actually showed.
+
+WHY
+---
+A play is settled later, from evidence: did anything downstream reference one of
+the memories this query surfaced? ``reward_proxy`` answered "which memories" by
+reading ``learning_signals`` for the same ``query_id`` — rows written by the
+recall path's ``enqueue(SignalBatch(...))``.
+
+That enqueue is off, deliberately. It writes twenty exposure rows per query, it
+was the source of a 2,675x inflation in the ranking-phase counter, and the code
+comment gives a second reason: *"even a non-blocking enqueue eventually writes
+canonical/learning state and turns dashboard polling into contention."*
+
+So the evidence lookup had no evidence to read, and every settlement fell
+through to the 120-second default of 0.5. Measured on a live production store::
+
+    SUM(alpha) = SUM(beta) = 867.5 = 165 priors + 1,405 plays x 0.5
+
+An exact match on both sides across 165 arms: every one of 1,405 settlements
+applied the neutral prior. Thompson sampling on Beta(a, a) is a coin flip, so
+retrieval strategy was being chosen at random.
+
+The fix is for the play to carry its own evidence. One column, written once per
+recorded play, holding the handful of fact_ids that were actually shown — rather
+than reinstating twenty rows per query in a table that gates a phase counter.
+
+WHY A COLUMN AND NOT A TABLE
+----------------------------
+This is one small JSON array per play, read exactly once by the settler and
+then dead. A child table would need its own index, its own retention sweep, and
+its own profile_id for erasure. The column is deleted with its play by the
+existing ``retention_sweep``, which is the behaviour we want and get for free.
+
+BACK-COMPATIBILITY
+------------------
+Existing rows keep NULL. The settler falls back to the ``learning_signals``
+lookup when the column is empty, so plays recorded before this migration settle
+exactly as they did before — and installs that still run the enqueue keep
+working unchanged.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M044_play_carries_its_own_evidence"
+DB_TARGET = "learning"
+
+_TABLE = "bandit_plays"
+_COLUMN = "shown_fact_ids"
+
+#: Recorded for the runner's DDL hash. SQLite has no ``ADD COLUMN IF NOT
+#: EXISTS``, so ``apply()`` below runs instead of this string; it is kept
+#: accurate because the hash is what detects a migration being edited after it
+#: has shipped.
+DDL = """
+ALTER TABLE bandit_plays ADD COLUMN shown_fact_ids TEXT;
+"""
+
+
+def _columns(conn: sqlite3.Connection) -> set[str]:
+    try:
+        return {
+            row[1] for row in conn.execute(f"PRAGMA table_info({_TABLE})")
+        }
+    except sqlite3.Error:
+        return set()
+
+
+def _table_exists(conn: sqlite3.Connection) -> bool:
+    try:
+        return conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (_TABLE,),
+        ).fetchone() is not None
+    except sqlite3.Error:
+        return False
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """End state: the column exists.
+
+    Everything ``verify`` asserts must be produced by every path through
+    ``apply`` — including the path where the table is absent. 4.0.10 shipped an
+    M043 whose ``verify`` required a table its ``apply`` created only
+    conditionally, which made the migration fail permanently on stores that
+    lacked it. Hence the branch below: no table means M005 has not run, this
+    migration has nothing to do, and saying so is the end state.
+    """
+    if not _table_exists(conn):
+        return True
+    return _COLUMN in _columns(conn)
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Add the column if it is missing. Idempotent.
+
+    Runs instead of ``DDL`` (the runner prefers a module-level ``apply``)
+    because ``ALTER TABLE ... ADD COLUMN`` raises when the column is already
+    there, and SQLite cannot guard that inside one script.
+    """
+    if not _table_exists(conn):
+        # M005 owns bandit_plays and is a declared dependency, so this means a
+        # store where the bandit tables were never created. Nothing to alter.
+        return
+    if _COLUMN in _columns(conn):
+        return
+    conn.execute(f"ALTER TABLE {_TABLE} ADD COLUMN {_COLUMN} TEXT")
+    if not verify(conn):  # pragma: no cover — defensive
+        raise sqlite3.OperationalError(
+            f"M044: {_TABLE}.{_COLUMN} absent after ALTER"
+        )
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Identical to ``apply`` — and that is safe only because it is additive.
+
+    ``repair`` == ``apply`` is a trap in general: if ``verify`` can return a
+    false negative, the runner retries forever. Here ``verify`` reads
+    ``PRAGMA table_info``, which is the same fact ``apply`` establishes, so a
+    false negative would require the ALTER to have silently not happened.
+    """
+    apply(conn)

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

@@ -0,0 +1,158 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""M045 — per-fact outcome score (PCOS), so ranking can use what worked.
+
+WHY
+---
+Ranking scores a memory by how much it *looks like* the query. Nothing in the
+pipeline knows whether a memory has ever actually helped. This table holds one
+number per (fact, profile): an exponentially-weighted average of the rewards of
+the settlements it took part in.
+
+WHY IT LIVES IN memory.db
+-------------------------
+Beside ``atomic_facts`` and ``action_outcomes``, the backfill source, so the
+whole thing stays in one file. SQLite cannot join across databases without
+ATTACH, and taking an ATTACH on the recall path to reach a single REAL would
+cost more than the number is worth.
+
+The ranker reads it with one batched keyed lookup rather than a LEFT JOIN into
+fact hydration: ``_row_to_fact`` builds ``AtomicFact`` from named columns and
+silently drops any it does not declare, so a JOIN would mean adding fields to a
+model used across the whole codebase to carry a value only the ranker reads.
+
+profile_id IS PART OF THE PRIMARY KEY, AND THAT IS NOT COSMETIC
+---------------------------------------------------------------
+A learned per-fact score is derived personal data. If it had no ``profile_id``,
+``forget_profile()`` would run, report success, and leave the erased user's
+learned outcome history behind — which is the same defect already
+known in ``fact_expansion_fts``. Creating a second table with the same defect
+in the same release would be indefensible. ``compliance/gdpr.py`` deletes from
+this table; a test asserts one profile's erasure leaves another's rows intact.
+
+THE BACKFILL, AND A CORRECTION TO THE PLAN
+------------------------------------------
+An earlier design's backfill read ``SELECT fact_id, profile_id, AVG(reward) FROM
+action_outcomes GROUP BY fact_id, profile_id``. **There is no ``fact_id`` column
+on that table** — it stores ``fact_ids_json``, a JSON array, because one outcome
+covers the set of memories an answer used. So the backfill expands the array with
+``json_each``, guarded by ``json_valid`` (an unguarded ``json_each`` raises on the
+first malformed row and takes the whole migration with it).
+
+On a live store this initialises every touched fact at 0.5 from 162 rows
+that are all 0.5 — which is the neutral prior, so the backfill adds no bias. Its
+only job is to avoid a cold start looking like a penalty.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M045_fact_outcome_score"
+DB_TARGET = "memory"
+
+_TABLE = "fact_outcome_score"
+
+DDL = """
+BEGIN IMMEDIATE;
+CREATE TABLE IF NOT EXISTS fact_outcome_score (
+    fact_id     TEXT NOT NULL,
+    profile_id  TEXT NOT NULL DEFAULT 'default',
+    score       REAL NOT NULL DEFAULT 0.5,
+    play_count  INTEGER NOT NULL DEFAULT 0,
+    updated_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (fact_id, profile_id)
+);
+CREATE INDEX IF NOT EXISTS idx_fos_profile
+    ON fact_outcome_score (profile_id, fact_id);
+COMMIT;
+"""
+
+#: Expand ``fact_ids_json`` and average the reward per (fact, profile).
+#:
+#: ``INSERT OR IGNORE`` names no conflict target on purpose: the table has one
+#: unique constraint today, and a targeted ``ON CONFLICT`` silently stops
+#: covering a row the moment a second constraint is added.
+_BACKFILL = """
+INSERT OR IGNORE INTO fact_outcome_score
+    (fact_id, profile_id, score, play_count, updated_at)
+SELECT
+    j.value AS fact_id,
+    o.profile_id,
+    AVG(o.reward),
+    COUNT(*),
+    datetime('now')
+FROM action_outcomes AS o, json_each(o.fact_ids_json) AS j
+WHERE o.reward IS NOT NULL
+  AND json_valid(o.fact_ids_json)
+  AND o.fact_ids_json IS NOT NULL
+  AND j.value IS NOT NULL AND j.value != ''
+GROUP BY j.value, o.profile_id
+"""
+
+
+def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
+    try:
+        return conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (name,),
+        ).fetchone() is not None
+    except sqlite3.Error:
+        return False
+
+
+def _columns(conn: sqlite3.Connection, table: str) -> set[str]:
+    try:
+        return {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
+    except sqlite3.Error:
+        return set()
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """End state: the table exists with profile_id in it.
+
+    Deliberately does NOT assert anything about backfilled rows. The backfill
+    depends on ``action_outcomes``, which is bootstrapped at engine init and may
+    hold nothing at all — so asserting rows would make ``verify`` fail forever
+    on a fresh install. Everything asserted here is produced by every path
+    through ``apply``; that is the M043 lesson, learned the hard way.
+    """
+    if not _table_exists(conn, _TABLE):
+        return False
+    cols = _columns(conn, _TABLE)
+    return {"fact_id", "profile_id", "score", "play_count"} <= cols
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Create the table, then backfill from reported outcomes if any exist."""
+    conn.executescript(DDL)
+    if not verify(conn):  # pragma: no cover — defensive
+        raise sqlite3.OperationalError(
+            "M045 fact_outcome_score did not reach its end-state"
+        )
+    _backfill(conn)
+
+
+def _backfill(conn: sqlite3.Connection) -> int:
+    """Seed from ``action_outcomes``. Never fatal — the table is what matters.
+
+    A failure here means facts start at the cold-start default of 0.5, which is
+    the same value the backfill would have written on this store anyway. Losing
+    the migration over that would be the wrong trade.
+    """
+    if not _table_exists(conn, "action_outcomes"):
+        return 0
+    if "reward" not in _columns(conn, "action_outcomes"):
+        # reward arrives with M006, which is deferred. Nothing to average yet.
+        return 0
+    try:
+        cur = conn.execute(_BACKFILL)
+        return int(cur.rowcount or 0)
+    except sqlite3.Error:
+        return 0
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Re-run apply. Safe: the DDL is IF NOT EXISTS and the backfill IGNOREs."""
+    apply(conn)