superlocalmemory 3.7.8 → 3.8.0

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

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

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

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

package/src/superlocalmemory/storage/models.py

@@ -440,3 +440,7 @@ class RecallResponse:
     # be mistaken for a reranked response.
     reranker_applied: bool = False
     reranker_status: str = "not_configured"
+    # Wave Q2b: precomputed community summary for the cluster the top results
+    # fall into (thematic context). None unless results cluster into one
+    # community above threshold. Additive — backward compatible.
+    community_context: dict | None = None

package/src/superlocalmemory/storage/schema.py

@@ -52,10 +52,14 @@ _TABLES: Final[tuple[str, ...]] = (
     "compliance_audit",
     "bm25_tokens",
     "config",
+    "entity_communities",
+    "community_summaries",
+    "persona_summary",
 )
 
 _FTS_TABLES: Final[tuple[str, ...]] = (
     "atomic_facts_fts",
+    "fact_expansion_fts",
 )
 
 
@@ -281,6 +285,24 @@ END;
 """
 
 
+# ---------------------------------------------------------------------------
+# Fact expansion FTS (Phase 4, T3b — fact-augmented key expansion)
+# ---------------------------------------------------------------------------
+# Standalone (NOT external-content) FTS5 holding per-fact alternate keys
+# (entity aliases + paraphrases). Kept separate from atomic_facts_fts so the
+# proven content index and its triggers are never touched. Populated by
+# core.key_expander on store (and backfilled), queried as an additive UNION in
+# the BM25 channel. fact_id is stored so results can be scope-JOINed to
+# atomic_facts.
+_SQL_FACT_EXPANSION_FTS: Final[str] = """
+CREATE VIRTUAL TABLE IF NOT EXISTS fact_expansion_fts
+    USING fts5(
+        fact_id UNINDEXED,
+        alt_keys
+    );
+"""
+
+
 # ---------------------------------------------------------------------------
 # Canonical entities
 # ---------------------------------------------------------------------------
@@ -316,6 +338,7 @@ CREATE INDEX IF NOT EXISTS idx_entities_type
 _SQL_ENTITY_ALIASES: Final[str] = """
 CREATE TABLE IF NOT EXISTS entity_aliases (
     alias_id    TEXT PRIMARY KEY,
+    profile_id  TEXT NOT NULL DEFAULT 'default',
     entity_id   TEXT NOT NULL,
     alias       TEXT NOT NULL,
     confidence  REAL NOT NULL DEFAULT 1.0,
@@ -329,6 +352,10 @@ CREATE INDEX IF NOT EXISTS idx_aliases_entity
     ON entity_aliases (entity_id);
 CREATE INDEX IF NOT EXISTS idx_aliases_lookup
     ON entity_aliases (alias COLLATE NOCASE);
+-- NOTE: the (profile_id, entity_id) index is created by migration M022, NOT
+-- here. On an upgrading DB this DDL runs at engine init BEFORE the deferred
+-- M022 adds the profile_id column, so referencing it here would fail engine
+-- init with "no such column: profile_id".
 """
 
 
@@ -663,6 +690,58 @@ CREATE TABLE IF NOT EXISTS config (
 );
 """
 
+# Wave Q: entity-community backbone (additive; safe on existing DBs).
+# One row per (profile, entity) mapping to the community it belongs to,
+# computed by Louvain over the entity co-occurrence graph in the background.
+# Shared spine for Q2 community summaries and Q3 progressive abstraction.
+_SQL_ENTITY_COMMUNITIES: Final[str] = """
+CREATE TABLE IF NOT EXISTS entity_communities (
+    profile_id  TEXT    NOT NULL,
+    entity_id   TEXT    NOT NULL,
+    community_id INTEGER NOT NULL,
+    computed_at TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (profile_id, entity_id)
+);
+CREATE INDEX IF NOT EXISTS idx_entity_comm_profile
+    ON entity_communities(profile_id);
+CREATE INDEX IF NOT EXISTS idx_entity_comm_cid
+    ON entity_communities(profile_id, community_id);
+"""
+
+# Wave Q2: one synthesized report per entity community (additive; safe on
+# existing DBs). Generated in the background after entity_communities; the
+# summary excludes superseded facts. member_fact_ids enables drill-down.
+_SQL_COMMUNITY_SUMMARIES: Final[str] = """
+CREATE TABLE IF NOT EXISTS community_summaries (
+    profile_id      TEXT    NOT NULL,
+    community_id    INTEGER NOT NULL,
+    summary         TEXT    NOT NULL DEFAULT '',
+    keywords        TEXT    NOT NULL DEFAULT '',
+    entity_ids_json TEXT    NOT NULL DEFAULT '[]',
+    fact_ids_json   TEXT    NOT NULL DEFAULT '[]',
+    fact_count      INTEGER NOT NULL DEFAULT 0,
+    computed_at     TEXT    NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (profile_id, community_id)
+);
+CREATE INDEX IF NOT EXISTS idx_comm_summ_profile
+    ON community_summaries(profile_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
+# the V3.4.40 summary-pollution regression. Drill-down: community_ids_json →
+# communities → their member facts.
+_SQL_PERSONA_SUMMARY: Final[str] = """
+CREATE TABLE IF NOT EXISTS persona_summary (
+    profile_id         TEXT PRIMARY KEY,
+    summary            TEXT NOT NULL DEFAULT '',
+    keywords           TEXT NOT NULL DEFAULT '',
+    community_ids_json TEXT NOT NULL DEFAULT '[]',
+    computed_at        TEXT NOT NULL DEFAULT (datetime('now'))
+);
+"""
+
 # ---------------------------------------------------------------------------
 # Ordered DDL list (tables before FTS, respects FK order)
 # ---------------------------------------------------------------------------
@@ -691,6 +770,14 @@ _DDL_ORDERED: Final[tuple[str, ...]] = (
     _SQL_V2_MIGRATION_CLEANUP,
     # FTS5 must come after atomic_facts (content table) AND after cleanup
     _SQL_ATOMIC_FACTS_FTS,
+    # T3b: standalone expansion FTS (additive; safe on existing DBs)
+    _SQL_FACT_EXPANSION_FTS,
+    # Wave Q: entity-community backbone (additive; safe on existing DBs)
+    _SQL_ENTITY_COMMUNITIES,
+    # Wave Q2: community summaries (additive; safe on existing DBs)
+    _SQL_COMMUNITY_SUMMARIES,
+    # Wave Q3: persona roll-up tier (additive; safe on existing DBs)
+    _SQL_PERSONA_SUMMARY,
 )
 
 

package/src/superlocalmemory/storage/schema_v343.py

@@ -43,7 +43,7 @@ V343_TABLES: Final[tuple[str, ...]] = (
 # ---------------------------------------------------------------------------
 
 _MESH_DDL = """
--- Mesh Peers
+-- Mesh Peers  (profile_id = tenant boundary; see M023)
 CREATE TABLE IF NOT EXISTS mesh_peers (
     peer_id TEXT PRIMARY KEY,
     session_id TEXT NOT NULL,
@@ -52,7 +52,8 @@ CREATE TABLE IF NOT EXISTS mesh_peers (
     host TEXT DEFAULT '127.0.0.1',
     port INTEGER DEFAULT 0,
     registered_at TEXT NOT NULL,
-    last_heartbeat TEXT NOT NULL
+    last_heartbeat TEXT NOT NULL,
+    profile_id TEXT NOT NULL DEFAULT 'default'
 );
 
 -- Mesh Messages
@@ -63,23 +64,28 @@ CREATE TABLE IF NOT EXISTS mesh_messages (
     msg_type TEXT DEFAULT 'text',
     content TEXT NOT NULL,
     read INTEGER DEFAULT 0,
-    created_at TEXT NOT NULL
+    created_at TEXT NOT NULL,
+    profile_id TEXT NOT NULL DEFAULT 'default'
 );
 
--- Mesh State (shared key-value store)
+-- Mesh State (shared key-value store, per tenant)
 CREATE TABLE IF NOT EXISTS mesh_state (
-    key TEXT PRIMARY KEY,
+    profile_id TEXT NOT NULL DEFAULT 'default',
+    key TEXT NOT NULL,
     value TEXT NOT NULL,
     set_by TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, key)
 );
 
--- Mesh Locks (file-level locks for coordination)
+-- Mesh Locks (file-level locks for coordination, per tenant)
 CREATE TABLE IF NOT EXISTS mesh_locks (
-    file_path TEXT PRIMARY KEY,
+    profile_id TEXT NOT NULL DEFAULT 'default',
+    file_path TEXT NOT NULL,
     locked_by TEXT NOT NULL,
     locked_at TEXT NOT NULL,
-    expires_at TEXT NOT NULL DEFAULT '9999-12-31T23:59:59Z'
+    expires_at TEXT NOT NULL DEFAULT '9999-12-31T23:59:59Z',
+    PRIMARY KEY (profile_id, file_path)
 );
 
 -- Mesh Events (audit log)
@@ -88,9 +94,14 @@ CREATE TABLE IF NOT EXISTS mesh_events (
     event_type TEXT NOT NULL,
     payload TEXT DEFAULT '{}',
     emitted_by TEXT NOT NULL,
-    created_at TEXT NOT NULL
+    created_at TEXT NOT NULL,
+    profile_id TEXT NOT NULL DEFAULT 'default'
 );
 
+-- NOTE: profile-leading indexes live in migration M023, never here — on an
+-- upgrade the profile_id column does not exist when this DDL runs (the old
+-- table already exists, so CREATE TABLE IF NOT EXISTS no-ops), and a
+-- CREATE INDEX on the missing column would abort engine init.
 CREATE INDEX IF NOT EXISTS idx_mesh_messages_to
     ON mesh_messages(to_peer, read);
 CREATE INDEX IF NOT EXISTS idx_mesh_events_type
@@ -123,16 +134,17 @@ CREATE INDEX IF NOT EXISTS idx_entity_profiles_project
 _INGESTION_DDL = """
 CREATE TABLE IF NOT EXISTS ingestion_log (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id TEXT NOT NULL DEFAULT 'default',
     source_type TEXT NOT NULL,
     dedup_key TEXT NOT NULL,
     fact_ids TEXT DEFAULT '[]',
     metadata TEXT DEFAULT '{}',
     status TEXT DEFAULT 'ingested',
     ingested_at TEXT NOT NULL,
-    UNIQUE(source_type, dedup_key)
+    UNIQUE(profile_id, source_type, dedup_key)
 );
 CREATE INDEX IF NOT EXISTS idx_ingestion_dedup
-    ON ingestion_log(source_type, dedup_key);
+    ON ingestion_log(profile_id, source_type, dedup_key);
 """
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/trust/gate.py

@@ -13,6 +13,7 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import logging
+import os
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -21,6 +22,26 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _env_threshold(name: str, default: float) -> float:
+    """Read a [0,1] threshold from the environment, falling back on parse/range error."""
+    try:
+        value = float(os.environ.get(name, ""))
+    except (TypeError, ValueError):
+        return default
+    return value if 0.0 <= value <= 1.0 else default
+
+
+# M-02/M-03 (3.7.9): thresholds are operator-tunable so multi-agent deployments
+# can tighten the write gate and opt into a read gate. Defaults are unchanged —
+# the audit's "raise write_threshold to 0.7" would block every new agent (a new
+# agent scores 0.5, Beta(1,1)); loopback callers bypass the gate entirely, so
+# this only affects remote credentialed agents. Read gate is OFF by default.
+_DEFAULT_WRITE_THRESHOLD = _env_threshold("SLM_TRUST_WRITE_THRESHOLD", 0.3)
+_DEFAULT_DELETE_THRESHOLD = _env_threshold("SLM_TRUST_DELETE_THRESHOLD", 0.5)
+_DEFAULT_READ_THRESHOLD = _env_threshold("SLM_TRUST_READ_THRESHOLD", 0.1)
+_READ_GATE_ENABLED = os.environ.get("SLM_TRUST_READ_GATE") == "1"
+
+
 class TrustError(PermissionError):
     """Raised when an agent fails a trust check.
 
@@ -62,17 +83,23 @@ class TrustGate:
     def __init__(
         self,
         scorer: TrustScorer,
-        write_threshold: float = 0.3,
-        delete_threshold: float = 0.5,
+        write_threshold: float = _DEFAULT_WRITE_THRESHOLD,
+        delete_threshold: float = _DEFAULT_DELETE_THRESHOLD,
+        read_threshold: float = _DEFAULT_READ_THRESHOLD,
+        read_gate_enabled: bool = _READ_GATE_ENABLED,
     ) -> None:
         if write_threshold < 0 or write_threshold > 1:
             raise ValueError("write_threshold must be in [0, 1]")
         if delete_threshold < 0 or delete_threshold > 1:
             raise ValueError("delete_threshold must be in [0, 1]")
+        if read_threshold < 0 or read_threshold > 1:
+            raise ValueError("read_threshold must be in [0, 1]")
 
         self._scorer = scorer
         self._write_threshold = write_threshold
         self._delete_threshold = delete_threshold
+        self._read_threshold = read_threshold
+        self._read_gate_enabled = read_gate_enabled
 
     @property
     def write_threshold(self) -> float:
@@ -116,15 +143,29 @@ class TrustGate:
                 agent_id, score, self._delete_threshold, "delete"
             )
 
+    @property
+    def read_threshold(self) -> float:
+        return self._read_threshold
+
+    @property
+    def read_gate_enabled(self) -> bool:
+        return self._read_gate_enabled
+
     def check_read(self, agent_id: str, profile_id: str) -> None:
-        """Read check — always passes. Logged for audit trail.
+        """Read check. Passes by default; logged for the audit trail.
 
-        Reads are never blocked because denying read access could break
-        agent functionality. However, logging read access enables
-        anomaly detection and compliance auditing.
+        M-03 (3.7.9): reads are unblocked by default because denying read access
+        could break agent functionality. Operators who need to stop a
+        compromised agent from exfiltrating the store can set
+        ``SLM_TRUST_READ_GATE=1`` (optionally with ``SLM_TRUST_READ_THRESHOLD``)
+        to enforce a minimum trust for reads too.
         """
         score = self._scorer.get_agent_trust(agent_id, profile_id)
         logger.debug(
-            "trust gate read (always pass): agent=%s trust=%.3f",
-            agent_id, score,
+            "trust gate read: agent=%s trust=%.3f gate=%s",
+            agent_id, score, self._read_gate_enabled,
         )
+        if self._read_gate_enabled and score < self._read_threshold:
+            raise TrustError(
+                agent_id, score, self._read_threshold, "read"
+            )