hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/taint.py

@@ -0,0 +1,832 @@
+"""
+Connector-content taint guard.
+
+Vaughn's rule: "connector-sourced content can never enter any training,
+corpus, eval-data or self-improvement proposal path." The reason is Google's
+Limited Use policy for Google user data; the same rule is applied to every
+connector (Slack, GitLab, Telegram messages from other people, documents,
+web pages, iMessage).
+
+Three parts:
+
+- **Producers** wrap what a connector read returns in ``TaintedText`` (a
+  ``str`` that carries ``origin`` and ``connector_id``) with ``mark()`` or
+  the ``@source(...)`` decorator. Every tainted read is also recorded in the
+  conversation's ``TaintLedger``.
+- **TaintLedger** (one per conversation/session): the 64-character shingles
+  (hashed) of every tainted read, and PER-MESSAGE provenance: which message
+  (turn) read which connector (rc5, HC-038). The conversation's "tainted"
+  flag is derived from it (some message in it read connector content).
+  Shingles catch connector text after it has lost its type tag (sliced,
+  concatenated, JSON-encoded, quoted in a model's summary). The ledger is
+  persisted in ``$HYPERCLAW_ROOT/taint/taint.sqlite3`` (hashes only, never the
+  text), so a reloaded conversation is re-flagged.
+- **Sinks**: ``@training_sink(name)`` on every writer to a learning, memory,
+  skills, self-improvement, knowledge-graph, civilization, corpus or eval
+  store. A sink refuses tainted input by raising ``TaintedInput``, writes an
+  activity-log row ("refused: connector content") and never truncates or
+  drops anything silently.
+
+What a sink refuses:
+1. a ``TaintedText`` anywhere in its arguments (type tag);
+2. any argument text that shares a 64-character shingle with a tainted read
+   (or equals a short tainted string) in a loaded ledger;
+3. any call made while the active conversation is tainted, unless the sink is
+   ``own_words=True``. Own-words sinks are the user-directed memory stores
+   (``memory_store``, ``MemoryManager.remember``): a memory the user asks for
+   in their own words still saves in a conversation that read email, while
+   connector text itself (rules 1 and 2) is still refused there.
+
+Memory (rc5): ``memory_decision`` decides, per message, whether a
+``memory_store`` call is the person's own words (saved without a prompt) or
+something learned from email, pages or other people (it waits for the
+person's tap on an approval card that names the source). The message counts,
+not the conversation: an email read three messages ago no longer puts a tap
+on a memory the person states in their own words now. Limit (documented by a
+test): a PARAPHRASE of connector content shares no 64-character shingle with
+it, so rules 1-2 do not catch it; the per-message check and the own-words
+overlap are what put it in front of the person.
+
+``tests/unit/test_taint_guard.py`` holds an AST scan that fails the build on
+any undecorated writer to these stores (see ``SCAN_ALLOWLIST`` there).
+"""
+from __future__ import annotations
+
+import contextvars
+import dataclasses
+import functools
+import hashlib
+import inspect
+import logging
+import os
+import re
+import sqlite3
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, Iterator, Optional, Set, Tuple
+
+log = logging.getLogger("hyperclaw.taint")
+
+SHINGLE = 64          # characters per shingle (normalised text)
+MIN_EXACT = 24        # shorter tainted strings are matched whole, not by shingle
+BACKGROUND = "background"   # reads outside any conversation (scheduled brief/digest)
+MAX_DEPTH = 8
+
+# origin -> how the user knows that source
+LABELS = {
+    "gmail": "Gmail", "google_calendar": "Google Calendar", "google_docs": "Google Docs",
+    "google_sheets": "Google Sheets", "google_drive": "Google Drive", "slack": "Slack",
+    "gitlab": "GitLab", "telegram": "Telegram", "imessage": "iMessage", "web": "web",
+    "document": "document", "email": "email", "gdrive": "Google Drive", "google": "Google",
+    "notion": "Notion", "confluence": "Confluence", "google_slides": "Google Slides",
+    "google_meet": "Google Meet",
+}
+GOOGLE_ORIGINS = {"gmail", "google_calendar", "google_docs", "google_sheets", "google_drive",
+                  "gdrive", "google", "google_slides", "google_meet"}
+# `source=` names that mean the content came from a connector (civilization sync).
+CONNECTOR_SOURCES = {"gdrive", "google_drive", "gmail", "google", "notion", "confluence",
+                     "slack", "gitlab", "telegram", "imessage", "jira", "hubspot",
+                     "salesforce", "dropbox", "box"}
+
+
+# ───────────────────────── the type tag ─────────────────────────
+
+class TaintedText(str):
+    """A str read from a connector. Slicing or joining returns a plain str;
+    the ledger's shingles still recognise it."""
+
+    def __new__(cls, value: str = "", origin: str = "connector", connector_id: str = ""):
+        obj = super().__new__(cls, value)
+        obj.origin = origin
+        obj.connector_id = connector_id
+        return obj
+
+    def __reduce__(self):
+        return (TaintedText, (str(self), self.origin, self.connector_id))
+
+    def __repr__(self) -> str:
+        return f"TaintedText({str.__repr__(self)}, origin={self.origin!r})"
+
+
+class TaintedInput(Exception):
+    """A training/corpus/eval/self-improvement sink was given connector content."""
+
+    def __init__(self, sink: str, reason: str, origin: str = "", conversation: str = ""):
+        self.sink = sink
+        self.reason = reason            # "tagged" | "shingle" | "conversation" | "unavailable"
+        self.origin = origin or "connector"
+        self.conversation = conversation
+        super().__init__(self.user_message)
+
+    @property
+    def label(self) -> str:
+        return LABELS.get(self.origin, self.origin.replace("_", " "))
+
+    @property
+    def user_message(self) -> str:
+        policy = ("Google's Limited Use policy for Google data, and HyperAgents applies the same "
+                  "rule to every connected account" if self.origin in GOOGLE_ORIGINS else
+                  "HyperAgents' Limited Use rule for every connected account, the same rule "
+                  "Google sets for Google data")
+        if self.reason == "conversation":
+            return (f"Not done ({self.sink}): this conversation includes content read from "
+                    f"{self.label}, so it is not used for learning, reflections, skill proposals "
+                    f"or any training or evaluation data ({policy}). Nothing was saved. Start a "
+                    f"new conversation (/reset) to turn these back on.")
+        if self.reason == "unavailable":
+            return (f"Not saved ({self.sink}): the connector-content check could not run, so "
+                    f"nothing was saved. Try again; if it keeps failing, check the HyperAgents "
+                    f"data folder.")
+        return (f"Not saved: this is content from {self.label}. Connector content is never kept "
+                f"in memory, learning, training or evaluation data ({policy}). Keep it in the "
+                f"source email or document instead; I can read it from there whenever you ask. "
+                f"I can still remember things you tell me in your own words.")
+
+
+# ───────────────────────── shingles ─────────────────────────
+
+_ESCAPES = re.compile(r"\\u[0-9a-fA-F]{4}|\\[nrtbf\"'\\/]")
+_NON_WORD = re.compile(r"[\W_]+", re.UNICODE)
+
+
+def normalize(text: str) -> str:
+    """Lower case, JSON escapes and punctuation/whitespace runs -> one space,
+    so a shingle survives re-wrapping, markdown and JSON encoding."""
+    t = _ESCAPES.sub(" ", str(text))
+    return _NON_WORD.sub(" ", t.lower()).strip()
+
+
+def _hash(s: str) -> int:
+    return int.from_bytes(hashlib.blake2b(s.encode("utf-8"), digest_size=8).digest(),
+                          "big", signed=True)
+
+
+def shingles(text: str) -> Set[int]:
+    n = normalize(text)
+    if len(n) < SHINGLE:
+        return set()
+    return {_hash(n[i:i + SHINGLE]) for i in range(len(n) - SHINGLE + 1)}
+
+
+def candidate_hashes(text: str) -> Set[int]:
+    """Every shingle of `text`, plus its whole-text hash when it is short."""
+    out = shingles(text)
+    ex = _exact(text)
+    if ex is not None:
+        out.add(ex)
+    return out
+
+
+def _exact(text: str) -> Optional[int]:
+    n = normalize(text)
+    if MIN_EXACT <= len(n) < SHINGLE:
+        return _hash("=" + n)
+    return None
+
+
+# ───────────────────────── the ledger ─────────────────────────
+
+def taint_dir() -> Path:
+    explicit = os.environ.get("HYPERCLAW_TAINT_DIR")
+    if explicit:
+        return Path(explicit).expanduser()
+    root = Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")).expanduser()
+    return root / "taint"
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS taint_sessions (
+    session    TEXT PRIMARY KEY,
+    tainted    INTEGER NOT NULL DEFAULT 0,
+    origins    TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS taint_shingles (
+    session    TEXT NOT NULL,
+    h          INTEGER NOT NULL,
+    PRIMARY KEY (session, h)
+) WITHOUT ROWID;
+CREATE TABLE IF NOT EXISTS taint_messages (
+    session    TEXT NOT NULL,
+    msg        TEXT NOT NULL,
+    origin     TEXT NOT NULL,
+    connector  TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (session, msg, origin, connector)
+) WITHOUT ROWID;
+"""
+# Reads with no message id (scheduled jobs, direct calls) are recorded under
+# this id: they count for the conversation, never for a specific message.
+UNSCOPED = "*"
+
+
+class _Store:
+    """Hashes only (never the text), one SQLite file per HYPERCLAW_ROOT."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._ready = False
+        self._lock = threading.Lock()
+
+    def connect(self) -> sqlite3.Connection:
+        if not self._ready:
+            with self._lock:
+                if not self._ready:
+                    self.path.parent.mkdir(parents=True, exist_ok=True)
+                    try:
+                        os.chmod(self.path.parent, 0o700)
+                    except OSError:
+                        pass
+                    con = sqlite3.connect(self.path, timeout=10)
+                    try:
+                        con.executescript(_SCHEMA)
+                    finally:
+                        con.close()
+                    try:
+                        os.chmod(self.path, 0o600)
+                    except OSError:
+                        pass
+                    self._ready = True
+        return sqlite3.connect(self.path, timeout=10)
+
+
+class TaintLedger:
+    """Per-conversation record of tainted reads: shingle hashes, short-string
+    hashes, the tainted flag and which sources were read."""
+
+    def __init__(self, session: str, store: Optional[_Store] = None):
+        self.session = session
+        self.hashes: Set[int] = set()
+        self.tainted = False
+        self.origins: Set[Tuple[str, str]] = set()
+        # message id -> {(origin, connector_id)}: which message read what.
+        self.messages: Dict[str, Set[Tuple[str, str]]] = {}
+        self._store = store
+        self._lock = threading.Lock()
+
+    # persistence
+    def load(self) -> "TaintLedger":
+        """Read this conversation's record. A store that cannot be read is
+        logged and the ledger works in memory (reads are never blocked)."""
+        if self._store is None:
+            return self
+        try:
+            self._load()
+        except (sqlite3.Error, OSError) as e:
+            log.warning("taint ledger for %s not loaded (%s); in memory only", self.session, e)
+        return self
+
+    def _load(self) -> None:
+        con = self._store.connect()
+        try:
+            row = con.execute("SELECT tainted, origins FROM taint_sessions WHERE session=?",
+                              (self.session,)).fetchone()
+            if row:
+                self.tainted = bool(row[0])
+                self.origins = {tuple(o.split("|", 1)) if "|" in o else (o, "")
+                                for o in (row[1] or "").split(",") if o}
+            self.hashes = {r[0] for r in con.execute(
+                "SELECT h FROM taint_shingles WHERE session=?", (self.session,))}
+            for msg, origin, cid in con.execute(
+                    "SELECT msg, origin, connector FROM taint_messages WHERE session=?",
+                    (self.session,)):
+                self.messages.setdefault(msg, set()).add((origin, cid))
+        finally:
+            con.close()
+
+    def _persist(self, new: Iterable[int], msg: Optional[Tuple[str, str, str]] = None) -> None:
+        if self._store is None:
+            return
+        try:
+            self._write(new, msg)
+        except (sqlite3.Error, OSError) as e:   # the in-memory record still applies
+            log.warning("taint ledger for %s not saved (%s); in memory only", self.session, e)
+
+    def _write(self, new: Iterable[int], msg: Optional[Tuple[str, str, str]] = None) -> None:
+        con = self._store.connect()
+        try:
+            with con:
+                con.execute("INSERT INTO taint_sessions (session, tainted, origins) VALUES (?,?,?) "
+                            "ON CONFLICT (session) DO UPDATE SET tainted=excluded.tainted, "
+                            "origins=excluded.origins",
+                            (self.session, int(self.tainted),
+                             ",".join(sorted(f"{o}|{c}" for o, c in self.origins))))
+                con.executemany("INSERT OR IGNORE INTO taint_shingles (session, h) VALUES (?, ?)",
+                                ((self.session, h) for h in new))
+                if msg is not None:
+                    con.execute("INSERT OR IGNORE INTO taint_messages (session, msg, origin, "
+                                "connector) VALUES (?,?,?,?)", (self.session,) + msg)
+        finally:
+            con.close()
+
+    def _note_message(self, origin: str, connector_id: str,
+                      message: Optional[str]) -> Optional[Tuple[str, str, str]]:
+        msg = str(message or current_message() or UNSCOPED)
+        seen = self.messages.setdefault(msg, set())
+        if (origin, connector_id) in seen:
+            return None
+        seen.add((origin, connector_id))
+        return (msg, origin, connector_id)
+
+    def add(self, text: str, origin: str, connector_id: str = "",
+            message: Optional[str] = None) -> None:
+        new = candidate_hashes(text)
+        with self._lock:
+            fresh = new - self.hashes
+            mrow = self._note_message(origin, connector_id, message)
+            changed = bool(fresh) or not self.tainted or \
+                (origin, connector_id) not in self.origins or mrow is not None
+            self.hashes |= fresh
+            self.tainted = True
+            self.origins.add((origin, connector_id))
+            if changed:
+                self._persist(fresh, mrow)
+
+    def flag(self, origin: str, connector_id: str = "", message: Optional[str] = None) -> None:
+        with self._lock:
+            mrow = self._note_message(origin, connector_id, message)
+            if self.tainted and (origin, connector_id) in self.origins and mrow is None:
+                return
+            self.tainted = True
+            self.origins.add((origin, connector_id))
+            self._persist((), mrow)
+
+    def message_origins(self, message: Optional[str]) -> Set[str]:
+        """The connectors read in this one message (turn)."""
+        if not message:
+            return set()
+        return {o for o, _ in self.messages.get(str(message), set())}
+
+    def matches(self, text: str) -> bool:
+        return bool(self.hashes) and not self.hashes.isdisjoint(candidate_hashes(text))
+
+    def first_origin(self) -> str:
+        return sorted(self.origins)[0][0] if self.origins else "connector"
+
+    def clear(self) -> None:
+        with self._lock:
+            self.hashes.clear()
+            self.tainted = False
+            self.origins.clear()
+            self.messages.clear()
+            if self._store is None:
+                return
+            try:
+                con = self._store.connect()
+                try:
+                    with con:
+                        con.execute("DELETE FROM taint_sessions WHERE session=?", (self.session,))
+                        con.execute("DELETE FROM taint_shingles WHERE session=?", (self.session,))
+                        con.execute("DELETE FROM taint_messages WHERE session=?", (self.session,))
+                finally:
+                    con.close()
+            except (sqlite3.Error, OSError) as e:
+                log.warning("taint ledger for %s not cleared on disk (%s)", self.session, e)
+
+
+# ───────────────────────── process registry + active conversation ─────────────────────────
+
+_LOCK = threading.RLock()
+_STORES: Dict[str, _Store] = {}
+_LEDGERS: Dict[Tuple[str, str], TaintLedger] = {}
+_ACTIVE: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_taint_conversation",
+                                                         default=None)
+# The message (turn) a read belongs to: the TurnGuard's turn id, set by the
+# registry around every tool call.
+_MESSAGE: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_taint_message",
+                                                          default=None)
+
+
+def current_message() -> Optional[str]:
+    return _MESSAGE.get()
+
+
+@contextmanager
+def message(msg_id: Optional[str]):
+    """Run a block as part of one message (turn): reads inside are recorded
+    against it (per-message provenance)."""
+    if not msg_id:
+        yield
+        return
+    token = _MESSAGE.set(str(msg_id))
+    try:
+        yield
+    finally:
+        _MESSAGE.reset(token)
+
+
+def _store() -> _Store:
+    p = str(taint_dir() / "taint.sqlite3")
+    with _LOCK:
+        if p not in _STORES:
+            _STORES[p] = _Store(Path(p))
+        return _STORES[p]
+
+
+def ledger(session: Optional[str] = None) -> TaintLedger:
+    """The ledger for `session` (default: the active conversation, else the
+    background ledger), loaded from disk on first use in this process."""
+    sid = session or active() or BACKGROUND
+    st = _store()
+    key = (str(st.path), sid)
+    with _LOCK:
+        led = _LEDGERS.get(key)
+        if led is None:
+            led = TaintLedger(sid, st).load()
+            _LEDGERS[key] = led
+        return led
+
+
+def _loaded() -> Iterator[TaintLedger]:
+    st = str(_store().path)
+    with _LOCK:
+        items = [led for (p, _), led in _LEDGERS.items() if p == st]
+    return iter(items)
+
+
+def active() -> Optional[str]:
+    return _ACTIVE.get()
+
+
+@contextmanager
+def conversation(session: Optional[str]):
+    """Run a block as part of conversation `session`: reads made inside are
+    recorded in its ledger and sinks check its flag."""
+    if not session:
+        yield
+        return
+    token = _ACTIVE.set(str(session))
+    try:
+        yield
+    finally:
+        _ACTIVE.reset(token)
+
+
+def is_tainted(session: Optional[str] = None) -> bool:
+    sid = session or active()
+    if not sid:
+        return False
+    return ledger(sid).tainted
+
+
+def clear(session: str) -> None:
+    """Forget a conversation's taint: only when its history is cleared
+    (/reset, /clear), since the content is then gone from it."""
+    ledger(session).clear()
+
+
+def reset_process_state() -> None:
+    """Drop the in-memory ledgers (tests; a restarted process). The on-disk
+    store is untouched, so a reloaded conversation is re-flagged."""
+    with _LOCK:
+        _LEDGERS.clear()
+        _STORES.clear()
+
+
+# ───────────────────────── producers ─────────────────────────
+
+def mark(value: Any, origin: str, connector_id: str = "",
+         session: Optional[str] = None, message: Optional[str] = None) -> Any:
+    """Wrap every string in `value` (str, dict values, lists, tuples) in
+    TaintedText and record it in the conversation's ledger, against the
+    message (turn) that read it. Returns the wrapped value (dicts and lists
+    are copied, never mutated)."""
+    led = ledger(session)
+    out = _wrap(value, origin, connector_id or origin, led, 0, message)
+    led.flag(origin, connector_id or origin, message)
+    return out
+
+
+def _wrap(value: Any, origin: str, cid: str, led: TaintLedger, depth: int,
+          msg: Optional[str] = None) -> Any:
+    if depth > MAX_DEPTH or value is None:
+        return value
+    if isinstance(value, str):
+        if value:
+            led.add(value, origin, cid, msg)
+        if isinstance(value, TaintedText):
+            return value
+        return TaintedText(value, origin, cid)
+    if isinstance(value, dict):
+        return {k: _wrap(v, origin, cid, led, depth + 1, msg) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_wrap(v, origin, cid, led, depth + 1, msg) for v in value]
+    if isinstance(value, tuple) and not hasattr(value, "_fields"):
+        return tuple(_wrap(v, origin, cid, led, depth + 1, msg) for v in value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        for f in dataclasses.fields(value):
+            try:
+                object.__setattr__(value, f.name,
+                                   _wrap(getattr(value, f.name), origin, cid, led, depth + 1,
+                                         msg))
+            except Exception:  # an exotic field: its text is still in the ledger
+                pass
+        return value
+    return value
+
+
+def source(origin: str, connector_id: str = "") -> Callable:
+    """Decorator for a connector read: its return value is marked."""
+    def deco(fn: Callable) -> Callable:
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*a, **kw):
+                return mark(await fn(*a, **kw), origin, connector_id)
+            awrapper.__taint_source__ = origin
+            return awrapper
+
+        @functools.wraps(fn)
+        def wrapper(*a, **kw):
+            return mark(fn(*a, **kw), origin, connector_id)
+        wrapper.__taint_source__ = origin
+        return wrapper
+    return deco
+
+
+# Tool-result envelopes: model tools whose OK result is connector content.
+CONNECTOR_TOOLS = {
+    "email_read": "gmail", "email_search": "gmail", "calendar_read": "google_calendar",
+    "imessage_read": "imessage", "web_fetch": "web", "document_read": "document",
+    "pdf_read": "document", "gitlab_review_queue": "gitlab",
+    # Google Workspace tools (hyperclaw/google_workspace/tools.py ORIGIN)
+    "gmail_search": "gmail", "gmail_read_thread": "gmail", "gmail_read_attachment": "gmail",
+    "calendar_list_events": "google_calendar", "calendar_freebusy": "google_calendar",
+    "drive_search": "google_drive", "drive_read": "google_drive", "docs_read": "google_docs",
+    "sheets_read": "google_sheets", "slides_read": "google_slides",
+    "meet_list_records": "google_meet", "meet_read_transcript": "google_meet",
+}
+
+
+def mark_tool_result(tool: str, env: Any, session: Optional[str],
+                     message: Optional[str] = None) -> None:
+    """Record a connector tool's envelope (data and message) in the
+    conversation's ledger, against the message (turn) that read it. The
+    envelope itself is not changed."""
+    origin = CONNECTOR_TOOLS.get(tool)
+    if origin is None:
+        return
+    led = ledger(session)
+    for part in (getattr(env, "data", None), getattr(env, "message", None)):
+        _wrap(part, origin, tool, led, 0, message)
+    led.flag(origin, tool, message)
+
+
+# ───────────────────────── sinks ─────────────────────────
+
+SINKS: Dict[str, str] = {}        # sink name -> module.qualname
+
+
+def _origin_of(value: Any, depth: int = 0) -> Optional[str]:
+    """origin of the first TaintedText found in value."""
+    if depth > MAX_DEPTH or value is None:
+        return None
+    if isinstance(value, TaintedText):
+        return value.origin
+    for v in _children(value):
+        o = _origin_of(v, depth + 1)
+        if o:
+            return o
+    return None
+
+
+def _children(value: Any) -> Iterable[Any]:
+    if isinstance(value, (str, bytes, bytearray, int, float, bool)) or value is None:
+        return ()
+    if isinstance(value, dict):
+        return list(value.keys()) + list(value.values())
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return list(value)
+    dump = getattr(value, "model_dump", None)
+    if callable(dump) and not isinstance(value, type):
+        try:
+            return [dump(mode="python")]
+        except Exception:
+            return list(getattr(value, "__dict__", {}).values())
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return [getattr(value, f.name, None) for f in dataclasses.fields(value)]
+    return ()
+
+
+def _strings(value: Any, depth: int = 0) -> Iterator[str]:
+    if depth > MAX_DEPTH or value is None:
+        return
+    if isinstance(value, str):
+        yield value
+        return
+    for v in _children(value):
+        yield from _strings(v, depth + 1)
+
+
+def check(sink: str, values: Iterable[Any], *, session: Optional[str] = None,
+          own_words: bool = False) -> None:
+    """Raise TaintedInput (after logging it) if `values` carry connector
+    content or, for a non-own-words sink, the conversation is tainted."""
+    sid = session or active()
+    values = list(values)
+    try:
+        origin = _origin_of(values)
+        if origin:
+            _refuse(sink, "tagged", origin, sid)
+        texts = [t for t in _strings(values) if len(t) >= MIN_EXACT]
+        if texts:
+            ledgers = list(_loaded())
+            if sid:
+                ledgers.append(ledger(sid))
+            ledgers.append(ledger(BACKGROUND))
+            cands = [candidate_hashes(t) for t in texts]
+            for led in {id(x): x for x in ledgers}.values():
+                if led.hashes and any(not led.hashes.isdisjoint(c) for c in cands):
+                    _refuse(sink, "shingle", led.first_origin(), sid)
+        if sid and not own_words:
+            led = ledger(sid)
+            if led.tainted:
+                _refuse(sink, "conversation", led.first_origin(), sid)
+    except TaintedInput:
+        raise
+    except Exception as e:  # fail closed: an unchecked write could carry connector text
+        log.warning("taint check for %s could not run: %s", sink, e, exc_info=True)
+        _refuse(sink, "unavailable", "", sid)
+
+
+def refuse_connector_source(sink: str, source_name: Optional[str]) -> None:
+    """Raise TaintedInput when a writer is told its input came from a connector."""
+    name = str(source_name or "").strip().lower()
+    if name in CONNECTOR_SOURCES:
+        _refuse(sink, "tagged", name, active())
+
+
+def _refuse(sink: str, reason: str, origin: str, sid: Optional[str]) -> None:
+    exc = TaintedInput(sink, reason, origin, sid or "")
+    log.warning("training sink %s refused connector content (%s, origin=%s, conversation=%s)",
+                sink, reason, origin or "-", sid or "-")
+    try:
+        from hyperclaw.tools.ledger import get_ledger
+        get_ledger().record(conversation=sid or "taint_guard", turn=None, surface="taint_guard",
+                            tool=f"training_sink:{sink}", effect="write",
+                            target=f"training_sink:{sink}", key=None, status="refused",
+                            message=f"refused: connector content ({reason}, "
+                                    f"origin {origin or 'unknown'})")
+    except Exception as e:
+        log.warning("taint guard: could not write the activity log: %s", e)
+    raise exc
+
+
+def training_sink(name: str, *, own_words: bool = False,
+                  session: Optional[Callable[[dict], Optional[str]]] = None,
+                  own_words_unless: Optional[Callable[[dict], bool]] = None) -> Callable:
+    """Register a writer to a training, corpus, eval, memory or
+    self-improvement store. Every call is checked before the writer runs.
+
+    own_words: a user-directed memory sink (see module docstring).
+    own_words_unless(bound_args): the call is NOT own-words (e.g. remember()
+    with source="auto_store").
+    session(bound_args): the conversation id when the writer names it in its
+    arguments (else the active conversation)."""
+    def deco(fn: Callable) -> Callable:
+        sig = inspect.signature(fn)
+
+        def _check(a, kw):
+            try:
+                bound = sig.bind_partial(*a, **kw).arguments
+            except TypeError:
+                bound = {"args": a, "kwargs": kw}
+            values = [v for k, v in bound.items() if k not in ("self", "cls")]
+            sid = session(bound) if session else None
+            ow = own_words and not (own_words_unless and own_words_unless(bound))
+            check(name, values, session=sid, own_words=ow)
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*a, **kw):
+                _check(a, kw)
+                return await fn(*a, **kw)
+            wrapper = awrapper
+        else:
+            @functools.wraps(fn)
+            def swrapper(*a, **kw):
+                _check(a, kw)
+                return fn(*a, **kw)
+            wrapper = swrapper
+        wrapper.__training_sink__ = name
+        SINKS[name] = f"{fn.__module__}.{fn.__qualname__}"
+        return wrapper
+    return deco
+
+
+# Model tools that write to a sink: refused before an approval card is shown.
+TOOL_SINKS = {
+    "memory_store": ("memory.vector_memory.memory_store", ("content", "domain", "source"), True),
+    "learning_log": ("learning.log_interaction", ("action", "detail", "feedback"), False),
+    "learning_feedback": ("learning.log_feedback", ("feedback",), False),
+    "learning_reflect": ("learning.reflect", ("period",), False),
+}
+
+
+def check_tool_call(tool: str, args: dict, session: Optional[str]) -> Optional[TaintedInput]:
+    """The refusal for a sink tool call, or None. Never raises."""
+    spec = TOOL_SINKS.get(tool)
+    if spec is None:
+        return None
+    sink, fields, own = spec
+    try:
+        check(sink, [args.get(f) for f in fields if isinstance(args, dict)],
+              session=session, own_words=own)
+    except TaintedInput as e:
+        return e
+    return None
+
+
+# ───────────────────────── memory: own words vs learned (per message) ─────────────────────────
+
+# Memory tools whose save is decided per message (rc5): own words save
+# without a prompt; anything learned waits for the person's tap.
+MEMORY_TOOLS = frozenset({"memory_store"})
+# Reads whose result is other people's words (pages, documents, feeds): a
+# memory saved in the same message waits for a tap. Reading the person's own
+# memory or files does not.
+PAGE_TOOLS = frozenset({"web_search", "web_fetch", "wikipedia", "news", "reddit", "hackernews",
+                        "arxiv", "youtube", "wayback", "pdf_read", "document_read",
+                        "team_delegate", "gitlab_review_queue"})
+# Share of the memory's words (3+ letters) that must appear in the person's
+# own words for it to count as theirs.
+OWN_WORDS_MIN_SHARE = 0.6
+
+
+def _content_words(text: str) -> list:
+    return [w for w in normalize(text).split() if len(w) >= 3]
+
+
+def own_words_share(content: str, provenance: Iterable[str]) -> float:
+    """How much of `content` is in the person's own words (0..1)."""
+    words = _content_words(content)
+    if not words:
+        return 0.0
+    said = set()
+    for p in provenance or ():
+        if isinstance(p, str):
+            said.update(_content_words(p))
+    return sum(1 for w in words if w in said) / len(words)
+
+
+def _labels(origins: Iterable[str]) -> str:
+    names = sorted({LABELS.get(o, o.replace("_", " ")) for o in origins if o})
+    return ", ".join(names) or "a connected account"
+
+
+def memory_decision(content: str, *, session: Optional[str], message: Optional[str],
+                    provenance: Iterable[str] = (), read_untrusted: bool = False
+                    ) -> Optional[str]:
+    """None when a memory is the person's own words (save it without a
+    prompt). Otherwise the reason it needs the person's tap, naming the source.
+
+    Per message: what THIS message (turn) read decides, not everything the
+    conversation ever read. Verbatim connector text never gets here: the
+    sink check (rules 1-2) refuses it first."""
+    led = ledger(session) if session else None
+    here = led.message_origins(message) if led is not None else set()
+    if here:
+        return (f"it was learned in a message that read {_labels(here)}; check it is what you "
+                f"want kept")
+    if read_untrusted:
+        return "it was learned in a message that read a web page or document"
+    if own_words_share(content, provenance) >= OWN_WORDS_MIN_SHARE:
+        return None
+    if led is not None and led.origins:
+        return (f"it is not in your own words, and this conversation read "
+                f"{_labels(o for o, _ in led.origins)}")
+    return "it is not in your own words"
+
+
+# ───────────────────────── session files ─────────────────────────
+
+TAINT_KEY = "taint_origin"
+
+
+def tag_messages(messages: list) -> list:
+    """Copies of `messages` with TAINT_KEY set on each message whose content
+    is connector content (for a session file)."""
+    out = []
+    for m in messages:
+        if isinstance(m, dict):
+            o = _origin_of(m.get("content"))
+            if o is None and isinstance(m.get("content"), str) and _matches_any(m["content"]):
+                o = "connector"
+            if o:
+                m = {**m, TAINT_KEY: o}
+        out.append(m)
+    return out
+
+
+def _matches_any(text: str) -> bool:
+    return any(led.matches(text) for led in _loaded())
+
+
+def restore_messages(session: str, messages: list) -> list:
+    """After loading a session file: re-mark tagged messages (TaintedText +
+    ledger) so the reloaded conversation is flagged again, even on an
+    install whose taint store does not have it."""
+    out = []
+    for m in messages:
+        if isinstance(m, dict) and m.get(TAINT_KEY):
+            m = {**m, "content": mark(m.get("content"), str(m[TAINT_KEY]), session=session)}
+        out.append(m)
+    return out