traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/governance/observer.py

@@ -0,0 +1,276 @@
+"""TraceforgeObserver protocol + concrete GovernanceObserver adapter.
+
+``TraceforgeObserver`` is the integration point host frameworks call around tool
+calls and session lifecycle. ``GovernanceObserver`` is the concrete
+implementation: it runs governance enrichment **synchronously** inside each hook
+(so it can return real ``SessionMeta`` to the host, and so ``observe_event`` — the
+single writer that advances the tool-call budget — runs exactly once per event),
+then hands the enriched record to an :class:`~traceforge.governance.emitter.EnrichedEmitter`
+for asynchronous, backpressure-bounded audit fan-out to sinks.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from traceforge.governance.emitter import DEFAULT_CAPACITY, EnrichedEmitter
+from traceforge.governance.pipeline import SessionMeta
+
+if TYPE_CHECKING:
+    from traceforge.classify.core import Classification
+    from traceforge.governance.pipeline import GovernancePipeline
+    from traceforge.sinks.base import StorageSink
+    from traceforge.types import SessionEvent
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AgentContext:
+    """Context provided by the host framework on session lifecycle events."""
+
+    session_id: str
+    agent_model: str | None = None
+    repo: str | None = None
+    project_root: str | None = None
+
+
+@runtime_checkable
+class TraceforgeObserver(Protocol):
+    """Protocol for observing agent tool calls with governance enrichment.
+
+    Implementations receive pre/post tool call events and session lifecycle events.
+    Each method returns SessionMeta with full governance analysis.
+    """
+
+    async def on_pre_tool_call(self, tool_name: str, args: dict) -> SessionMeta:
+        """Primary classification point."""
+        ...
+
+    async def on_post_tool_call(self, tool_name: str, result: dict) -> SessionMeta:
+        """IFC propagation, integrity checks, PII scan of output."""
+        ...
+
+    async def on_session_start(self, context: AgentContext) -> SessionMeta:
+        """Called when a new agent session begins."""
+        ...
+
+    async def on_session_end(self, context: AgentContext) -> SessionMeta:
+        """Called when an agent session ends."""
+        ...
+
+
+class GovernanceObserver:
+    """Concrete :class:`TraceforgeObserver`: sync single-writer enrichment in the
+    hooks, async audit emission via :class:`EnrichedEmitter`.
+
+    **Session-scoped.** Construct one per agent session (or let
+    :meth:`on_session_start` set the session id). A monotonic per-session sequence
+    is stamped on ``metadata.sequence`` so dropped events can be summarized in a
+    :class:`~traceforge.governance.envelope.ContextGapEvent`.
+
+    **Enrichment cardinality** (the load-bearing invariant):
+
+    * ``on_session_start`` / ``on_session_end`` → ``observe_event`` routes to
+      ``process_lifecycle`` (Phase 1 only; does **not** advance the tool-call
+      budget). Stamped + submitted for audit.
+    * ``on_pre_tool_call`` → ``score_tool_call_event`` — a **read-only** preflight
+      preview (transient state copy; does **not** advance the budget). Its
+      ``SessionMeta`` is **returned to the host** for immediate
+      classification/enforcement but is **not** emitted to sinks (avoids doubling
+      audit output per tool call).
+    * ``on_post_tool_call`` → ``observe_event`` routes to ``process_event`` — the
+      **single writer** that advances the tool-call budget **exactly once**.
+      Stamped + submitted for audit.
+
+    So across a full ``start → pre → post → end`` cycle the budget advances
+    exactly once (at ``post``).
+    """
+
+    def __init__(
+        self,
+        governance: "GovernancePipeline",
+        emitter: EnrichedEmitter,
+        *,
+        session_id: str | None = None,
+        project_root: str | None = None,
+    ) -> None:
+        self._governance = governance
+        self._emitter = emitter
+        self._session_id = session_id
+        self._project_root = project_root
+        self._sequence = 0
+        # Positional pre→post argument correlation: the post hook receives only a
+        # result, but building the completed event's payload (and shell command
+        # analysis) needs the original args. Agents call tools sequentially per
+        # session, so a per-tool FIFO of pending args pairs them up.
+        self._pending_args: dict[str, deque] = defaultdict(deque)
+
+    # ── internals ──────────────────────────────────────────────────────────────
+
+    def _next_sequence(self) -> int:
+        self._sequence += 1
+        return self._sequence
+
+    def _require_session(self) -> str:
+        if not self._session_id:
+            raise RuntimeError(
+                "GovernanceObserver has no session_id; call on_session_start first "
+                "or pass session_id to the constructor."
+            )
+        return self._session_id
+
+    def _classify(
+        self, tool_name: str, arguments: dict, server_namespace: str | None
+    ) -> "Classification | None":
+        """Reuse the blessed self-classifying governance path so the observed
+        event carries a real ``Classification`` rather than the UNKNOWN fallback
+        ``from_session_event`` would otherwise apply."""
+        from traceforge.governance.types import ToolCallEvent
+
+        gov_event = ToolCallEvent.from_dict(
+            {
+                "tool_name": tool_name,
+                "session_id": self._session_id,
+                "tool_input": arguments if isinstance(arguments, dict) else {},
+                "server_namespace": server_namespace,
+            }
+        )
+        try:
+            return self._governance.enrich_event(gov_event).base_classification
+        except Exception as exc:  # classification is best-effort; never break the hook
+            logger.error("governance classification failed for tool %s: %s", tool_name, exc)
+            return None
+
+    def _build_event(
+        self, kind: str, payload: dict, *, classification: "Classification | None" = None
+    ) -> "SessionEvent":
+        from traceforge.types import EventMetadata, SessionEvent
+
+        metadata = EventMetadata(sequence=self._next_sequence(), classification=classification)
+        return SessionEvent(
+            kind=kind,
+            session_id=self._require_session(),
+            timestamp=datetime.now(timezone.utc),
+            payload=payload,
+            metadata=metadata,
+        )
+
+    @staticmethod
+    def _stamp(event: "SessionEvent", meta: SessionMeta) -> "SessionEvent":
+        """Return a copy of ``event`` carrying ``meta`` under ``metadata.governance``.
+
+        Stamping keeps the backward-compat sink path correct: a sink that only
+        implements ``on_event`` still receives governance (the base
+        ``on_enriched_event`` forwards the stamped event to ``on_event``)."""
+        stamped_meta = event.metadata.model_copy(update={"governance": meta})
+        return event.model_copy(update={"metadata": stamped_meta})
+
+    def _empty_meta(self) -> SessionMeta:
+        return SessionMeta(classification=None, risk_assessment=None)
+
+    # ── TraceforgeObserver hooks ─────────────────────────────────────────────────
+
+    async def on_session_start(self, context: AgentContext) -> SessionMeta:
+        self._session_id = context.session_id
+        if context.project_root:
+            self._project_root = context.project_root
+        from traceforge.types import EventKind
+
+        event = self._build_event(
+            EventKind.SESSION_STARTED,
+            {"agent_model": context.agent_model, "repo": context.repo},
+        )
+        meta = self._governance.observe_event(event) or self._empty_meta()
+        self._emitter.submit(self._stamp(event, meta), meta)
+        return meta
+
+    async def on_session_end(self, context: AgentContext) -> SessionMeta:
+        if context.session_id:
+            self._session_id = context.session_id
+        if context.project_root:
+            self._project_root = context.project_root
+        from traceforge.types import EventKind
+
+        event = self._build_event(
+            EventKind.SESSION_ENDED,
+            {"agent_model": context.agent_model, "repo": context.repo},
+        )
+        meta = self._governance.observe_event(event) or self._empty_meta()
+        self._emitter.submit(self._stamp(event, meta), meta)
+        return meta
+
+    async def on_pre_tool_call(self, tool_name: str, args: dict) -> SessionMeta:
+        self._require_session()
+        from traceforge.types import EventKind
+
+        server_namespace = args.get("server_namespace") if isinstance(args, dict) else None
+        classification = self._classify(tool_name, args, server_namespace)
+        event = self._build_event(
+            EventKind.TOOL_CALL_STARTED,
+            {"tool_name": tool_name, "arguments": args, "server_namespace": server_namespace},
+            classification=classification,
+        )
+        # Remember args so the paired post hook can rebuild the completed event.
+        self._pending_args[tool_name].append(args)
+        # Read-only preflight preview — advances no budget, returned to host only.
+        return self._governance.score_tool_call_event(event)
+
+    async def on_post_tool_call(self, tool_name: str, result: dict) -> SessionMeta:
+        self._require_session()
+        from traceforge.types import EventKind
+
+        pending = self._pending_args.get(tool_name)
+        args = pending.popleft() if pending else {}
+        server_namespace = args.get("server_namespace") if isinstance(args, dict) else None
+        classification = self._classify(tool_name, args, server_namespace)
+        event = self._build_event(
+            EventKind.TOOL_CALL_COMPLETED,
+            {
+                "tool_name": tool_name,
+                "arguments": args,
+                "server_namespace": server_namespace,
+                "result": result,
+            },
+            classification=classification,
+        )
+        # Single writer: advances the tool-call budget exactly once.
+        meta = self._governance.observe_event(event) or self._empty_meta()
+        self._emitter.submit(self._stamp(event, meta), meta)
+        return meta
+
+
+def create_observer(
+    governance: "GovernancePipeline",
+    sinks: "list[StorageSink]",
+    *,
+    capacity: int = DEFAULT_CAPACITY,
+    session_id: str | None = None,
+    project_root: str | None = None,
+) -> "tuple[GovernanceObserver, EnrichedEmitter]":
+    """Wire a :class:`GovernanceObserver` + :class:`EnrichedEmitter` against a
+    governance pipeline and sinks.
+
+    The emitter's ``record_drop`` is bound to durable session state so a
+    backpressure drop is persisted (``SessionState._dropped_events``) via the
+    existing raw-SQLite write-through — no new migration needed.
+
+    The returned emitter is **not** started; the caller owns its lifecycle and
+    must ``await emitter.start()`` inside the event loop that will drive the
+    observer, and ``await emitter.aclose()`` at shutdown.
+    """
+
+    def _record_drop(sid: str, n: int) -> None:
+        state = governance.get_or_create_state(sid)
+        state.record_drop(n)
+        state.persist()
+
+    emitter = EnrichedEmitter(sinks, capacity=capacity, record_drop=_record_drop)
+    observer = GovernanceObserver(
+        governance, emitter, session_id=session_id, project_root=project_root
+    )
+    return observer, emitter

traceforge/governance/persistence.py

@@ -0,0 +1,401 @@
+"""SQLite persistence layer for governance session state.
+
+Schema is managed by Alembic migrations (src/traceforge/migrations/).
+On initialization, SystemStore runs ``alembic upgrade head`` to apply
+any pending migrations, creating the full normalized schema on a fresh
+database.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+_LRU_CACHE_SIZE = 10_000
+
+
+def _run_alembic(conn: sqlite3.Connection) -> None:
+    """Apply pending Alembic migrations using a SQLAlchemy connection wrapper.
+
+    Skips the heavy SQLAlchemy/Alembic import if the database is already at
+    the latest known revision (fast path for the common case).
+    """
+    from traceforge.migrations.versions import LATEST_REVISION
+
+    # Fast path: check if already at head without importing SQLAlchemy
+    try:
+        cursor = conn.execute("SELECT version_num FROM alembic_version LIMIT 1")
+        row = cursor.fetchone()
+        if row and row[0] == LATEST_REVISION:
+            return  # Already at HEAD, skip heavy imports
+    except sqlite3.OperationalError:
+        pass  # Table doesn't exist yet — need full migration
+
+    # Slow path: need to run migrations
+    from sqlalchemy import create_engine, event, pool
+
+    from traceforge.migrations.runner import run_migrations
+
+    # Wrap the existing sqlite3 connection in a SQLAlchemy engine so Alembic
+    # can drive the migration context without opening a second connection.
+    engine = create_engine(
+        "sqlite://",
+        creator=lambda: conn,
+        poolclass=pool.StaticPool,
+    )
+    # Disable pysqlite's implicit transaction handling so Alembic controls it.
+    # We must restore the original isolation_level afterward — otherwise the
+    # raw connection is left in permanent autocommit mode, breaking the
+    # pipeline's atomic commit/rollback patterns.
+    original_isolation_level = conn.isolation_level
+
+    @event.listens_for(engine, "connect")
+    def _set_raw_connection(dbapi_conn, connection_record):
+        dbapi_conn.isolation_level = None
+
+    try:
+        with engine.connect() as sa_conn:
+            run_migrations(sa_conn)
+    finally:
+        conn.isolation_level = original_isolation_level
+
+
+class SystemStore:
+    """SQLite-backed persistence for governance state.
+
+    On construction, runs Alembic migrations to ensure the schema is at HEAD.
+
+    Single-writer guarantee
+    -----------------------
+    The store is a *synchronous* durability layer over a single ``sqlite3``
+    connection opened with ``check_same_thread=False``. The pipeline is asyncio
+    single-threaded and offloads store writes to a worker thread (via
+    ``asyncio.to_thread``), so writes can originate on *different* OS threads even
+    though they are never logically concurrent per session. An ``asyncio.Queue``
+    or ``asyncio.Lock`` cannot serialize work that runs off-loop on arbitrary
+    threads, so the correct primitive for this sync store is a
+    :class:`threading.Lock` — not a second, async concurrency primitive.
+
+    Every mutation is serialized by :attr:`_lock`. Single-statement writes take
+    the lock around ``execute`` + ``commit``. Multi-statement transactions MUST
+    go through :meth:`write_transaction`, which holds the lock for the *entire*
+    transaction (not just the terminal ``commit``), guaranteeing that no two
+    writers ever interleave statements on the shared connection. This is the one
+    and only write-serialization mechanism; callers must never open a second one.
+    """
+
+    def __init__(self, db_path: str | Path) -> None:
+        self._db_path = Path(db_path) if str(db_path) != ":memory:" else Path(":memory:")
+        if str(db_path) != ":memory:":
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(db_path), check_same_thread=False)
+        self._lock = threading.Lock()
+        self._processed_cache: dict[str, str | None] = {}
+
+        # Apply WAL and pragmas before migrations
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA busy_timeout = 5000")
+        self._conn.execute("PRAGMA synchronous = NORMAL")
+
+        # Run migrations to HEAD
+        _run_alembic(self._conn)
+
+    @property
+    def connection(self) -> sqlite3.Connection:
+        return self._conn
+
+    @property
+    def lock(self):
+        """Threading lock for callers needing multi-statement transactions."""
+        return self._lock
+
+    @contextmanager
+    def write_transaction(self) -> "Iterator[sqlite3.Connection]":
+        """Serialize a full multi-statement write transaction under the writer lock.
+
+        This is the formal single-writer entry point for any write that spans more
+        than one statement (state persist + idempotency reservation, deferred MCP
+        writes + finalization, etc.). It:
+
+        * acquires :attr:`_lock` for the whole transaction — every statement the
+          body issues on the connection is covered, not merely the final commit —
+          so concurrent writers can never interleave on the shared connection;
+        * commits on clean exit; and
+        * rolls back and re-raises on *any* exception, leaving no dangling
+          transaction behind.
+
+        The body MUST issue its statements without re-acquiring the lock (use
+        :meth:`execute_in_transaction` / the ``*_no_commit`` helpers, which do not
+        lock). ``_lock`` is a non-reentrant :class:`threading.Lock`, so calling a
+        self-locking method (e.g. :meth:`commit`) from inside the body would
+        deadlock.
+        """
+        with self._lock:
+            try:
+                yield self._conn
+            except BaseException:
+                self._conn.rollback()
+                raise
+            else:
+                self._conn.commit()
+
+    def is_duplicate(self, source_event_key: str) -> str | None:
+        """Check if event was already processed. Returns cached meta JSON or None."""
+        if source_event_key in self._processed_cache:
+            return self._processed_cache[source_event_key]
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT session_meta_json FROM processed_events WHERE source_event_key = ?",
+                (source_event_key,),
+            ).fetchone()
+        if row:
+            self._processed_cache[source_event_key] = row[0]
+            self._evict_cache()
+            return row[0]
+        return None
+
+    def record_processed(
+        self, source_event_key: str, session_id: str, meta_json: str, processed_at: str
+    ) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR IGNORE INTO processed_events (source_event_key, session_id, session_meta_json, processed_at) VALUES (?, ?, ?, ?)",
+                (source_event_key, session_id, meta_json, processed_at),
+            )
+            self._conn.commit()
+        self._processed_cache[source_event_key] = meta_json
+        self._evict_cache()
+
+    def reserve_event(self, source_event_key: str, session_id: str, processed_at: str) -> None:
+        """Reserve an event key before state mutation to prevent double-processing on crash."""
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR IGNORE INTO processed_events (source_event_key, session_id, session_meta_json, processed_at) VALUES (?, ?, ?, ?)",
+                (source_event_key, session_id, '{"reserved":true}', processed_at),
+            )
+            self._conn.commit()
+        # Mark as reserved in cache (will be overwritten by finalize)
+        self._processed_cache[source_event_key] = '{"reserved":true}'
+        self._evict_cache()
+
+    def finalize_processed(self, source_event_key: str, meta_json: str) -> None:
+        """Update reserved event with full meta after Phase 3 completes."""
+        with self._lock:
+            self._conn.execute(
+                "UPDATE processed_events SET session_meta_json = ? WHERE source_event_key = ?",
+                (meta_json, source_event_key),
+            )
+            self._conn.commit()
+        self._processed_cache[source_event_key] = meta_json
+
+    def get_mcp_profile(self, server: str, tool_name: str) -> dict | None:
+        """Read an MCP tool profile from the normalized tables.
+
+        Returns the scalar fingerprint fields plus ``role``/``capability``/
+        ``scope`` as sorted lists reconstructed from ``mcp_profile_attributes``,
+        or ``None`` when the tool has never been registered.
+        """
+        with self._lock:
+            row = self._conn.execute(
+                """SELECT server, tool_name, description_hash, schema_hash, registered_effect,
+                          clearance, first_seen, last_seen
+                   FROM mcp_profiles WHERE server = ? AND tool_name = ?""",
+                (server, tool_name),
+            ).fetchone()
+            if not row:
+                return None
+            attr_rows = self._conn.execute(
+                "SELECT attr_type, attr_value FROM mcp_profile_attributes "
+                "WHERE server = ? AND tool_name = ?",
+                (server, tool_name),
+            ).fetchall()
+        attributes: dict[str, list[str]] = {"role": [], "capability": [], "scope": []}
+        for attr_type, attr_value in attr_rows:
+            attributes.setdefault(attr_type, []).append(attr_value)
+        return {
+            "server": row[0],
+            "tool_name": row[1],
+            "description_hash": row[2],
+            "schema_hash": row[3],
+            "registered_effect": row[4],
+            "clearance": row[5],
+            "first_seen": row[6],
+            "last_seen": row[7],
+            "role": sorted(attributes["role"]),
+            "capability": sorted(attributes["capability"]),
+            "scope": sorted(attributes["scope"]),
+        }
+
+    def upsert_mcp_profile(self, server: str, tool_name: str, profile: dict) -> None:
+        """Insert MCP profile only if not already registered (preserves first-seen baseline)."""
+        with self._lock:
+            self.write_mcp_profile_no_commit(server, tool_name, profile)
+            self._conn.commit()
+
+    def write_mcp_profile_no_commit(self, server: str, tool_name: str, profile: dict) -> None:
+        """Write an MCP profile within the caller's transaction (no lock, no commit).
+
+        Writes the scalar ``mcp_profiles`` row plus one ``mcp_profile_attributes``
+        row per role/capability/scope value. ``INSERT OR IGNORE`` on every table
+        preserves the first-seen baseline (a re-registration of an existing tool
+        is a no-op).
+        """
+        self._conn.execute(
+            """INSERT OR IGNORE INTO mcp_profiles
+               (server, tool_name, description_hash, schema_hash, registered_effect,
+                clearance, first_seen, last_seen)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                server,
+                tool_name,
+                profile["description_hash"],
+                profile["schema_hash"],
+                profile.get("registered_effect"),
+                profile.get("clearance"),
+                profile["first_seen"],
+                profile["last_seen"],
+            ),
+        )
+        for attr_type in ("role", "capability", "scope"):
+            for value in profile.get(attr_type) or ():
+                self._conn.execute(
+                    """INSERT OR IGNORE INTO mcp_profile_attributes
+                       (server, tool_name, attr_type, attr_value) VALUES (?, ?, ?, ?)""",
+                    (server, tool_name, attr_type, value),
+                )
+
+    def update_mcp_last_seen(self, server: str, tool_name: str, last_seen: str) -> None:
+        """Update only last_seen timestamp — preserves registered baseline."""
+        with self._lock:
+            self.write_mcp_last_seen_no_commit(server, tool_name, last_seen)
+            self._conn.commit()
+
+    def write_mcp_last_seen_no_commit(self, server: str, tool_name: str, last_seen: str) -> None:
+        """Bump last_seen on the profile within the caller's transaction."""
+        self._conn.execute(
+            "UPDATE mcp_profiles SET last_seen = ? WHERE server = ? AND tool_name = ?",
+            (last_seen, server, tool_name),
+        )
+
+    def get_budget_counters(self, session_id: str) -> dict[str, dict[str, int]]:
+        """Read a session's normalized dimensional budget counters.
+
+        Returns ``{dimension: {key: count}}`` reconstructed from
+        ``budget_counters``. The atomic scalar budget fields (total_tool_calls,
+        etc.) are columns on ``session_state``, not part of this projection.
+        """
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT dimension, key, count FROM budget_counters WHERE session_id = ?",
+                (session_id,),
+            ).fetchall()
+        counters: dict[str, dict[str, int]] = {}
+        for dimension, key, count in rows:
+            counters.setdefault(dimension, {})[key] = count
+        return counters
+
+    def get_taint_entries(self, session_id: str) -> list[dict]:
+        """Read a session's normalized taint ledger, ordered by append ordinal."""
+        with self._lock:
+            rows = self._conn.execute(
+                """SELECT event_id, source_event_key, clearance, source, payload_pointer
+                   FROM taint_entries WHERE session_id = ? ORDER BY ordinal""",
+                (session_id,),
+            ).fetchall()
+        return [
+            {
+                "event_id": r[0],
+                "source_event_key": r[1],
+                "clearance": r[2],
+                "source": r[3],
+                "payload_pointer": r[4],
+            }
+            for r in rows
+        ]
+
+    def get_content_hash(self, repo: str, file_path: str) -> str | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT sha256 FROM content_hashes WHERE repo = ? AND file_path = ?",
+                (repo, file_path),
+            ).fetchone()
+        return row[0] if row else None
+
+    def store_content_hash_no_commit(
+        self, repo: str, file_path: str, sha256: str, session_id: str, updated_at: str
+    ) -> None:
+        """Upsert a content-hash baseline within the caller's transaction (no commit).
+
+        Participates in the caller's open transaction, matching
+        :meth:`execute_in_transaction`. Used by the monitor's finalization commit so a
+        content-integrity baseline update lands atomically with the idempotency record.
+        """
+        self._conn.execute(
+            """INSERT OR REPLACE INTO content_hashes (repo, file_path, sha256, updated_at, updated_by_session)
+               VALUES (?, ?, ?, ?, ?)""",
+            (repo, file_path, sha256, updated_at, session_id),
+        )
+
+    def store_content_hash(
+        self, repo: str, file_path: str, sha256: str, session_id: str, updated_at: str
+    ) -> None:
+        with self._lock:
+            self.store_content_hash_no_commit(repo, file_path, sha256, session_id, updated_at)
+            self._conn.commit()
+
+    def get_drift_baseline(self, agent_model: str, repo: str) -> dict | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT phase_counts_json, total_events FROM drift_baselines WHERE agent_model = ? AND repo = ?",
+                (agent_model, repo),
+            ).fetchone()
+        if not row:
+            return None
+        return {"phase_counts": json.loads(row[0]), "total_events": row[1]}
+
+    def execute_in_transaction(self, sql: str, params: tuple = ()) -> None:
+        """Execute SQL within the current transaction (no auto-commit). Caller must hold lock."""
+        self._conn.execute(sql, params)
+
+    def commit(self) -> None:
+        """Commit the current transaction."""
+        with self._lock:
+            self._conn.commit()
+
+    def rollback(self) -> None:
+        """Rollback the current transaction."""
+        with self._lock:
+            self._conn.rollback()
+
+    def cache_processed(self, source_event_key: str, meta_json: str | None) -> None:
+        """Add entry to processed events cache."""
+        self._processed_cache[source_event_key] = meta_json
+        self._evict_cache()
+
+    def commit_deferred_mcp_writes(self, writes: "tuple") -> None:
+        """Commit deferred MCP profile writes after pipeline finalization.
+
+        Accepts tuple[MCPDeferredWrite, ...] from MCPScanResult.
+        """
+        for write in writes:
+            if write.kind == "upsert":
+                self.upsert_mcp_profile(write.server, write.tool_name, json.loads(write.payload))
+            elif write.kind == "last_seen":
+                self.update_mcp_last_seen(write.server, write.tool_name, write.payload)
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def _evict_cache(self) -> None:
+        if len(self._processed_cache) > _LRU_CACHE_SIZE:
+            # Simple eviction: remove oldest half
+            keys = list(self._processed_cache.keys())
+            for k in keys[: len(keys) // 2]:
+                del self._processed_cache[k]