claude-smart 0.2.47 → 0.2.48

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/agent_run/_run_tool_dependency_store.py

@@ -0,0 +1,123 @@
+"""SQLite RunToolDependencyStore methods (the RunToolDependencyStore bucket).
+
+Extracted verbatim from ``_agent_run.py`` (the RunToolDependencyStore bucket):
+the four run-tool-dependency methods. This is the LAST bucket — the residual
+``_agent_run.py`` module is now helpers-only (it no longer defines a mixin
+class), and permanently holds the shared row/datetime helpers (``_dt_str``,
+``_row_to_run_tool_dependency`` …), which are imported here rather than
+duplicated.
+
+``consume_run_tool_dependencies`` keeps its resolved-unconsumed ``WHERE`` guard
+and ``rowcount`` return; ``count_unresolved_followup_dependencies`` keeps its
+three-table JOIN. Both are moved WHOLE, byte-identically.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+from reflexio.server.services.storage.storage_base import (
+    PendingToolCallStatus,
+    RunToolDependencyRecord,
+)
+
+from .._agent_run import _dt_str, _row_to_run_tool_dependency
+from .._base import SQLiteStorageBase
+
+
+class SQLiteRunToolDependencyStoreMixin:
+    """SQLite-backed run-tool-dependency store primitives."""
+
+    _lock: Any
+    conn: sqlite3.Connection
+    _fetchone: Any
+    _fetchall: Any
+    _current_timestamp: Any
+
+    @SQLiteStorageBase.handle_exceptions
+    def attach_run_tool_dependency(
+        self, record: RunToolDependencyRecord
+    ) -> RunToolDependencyRecord:
+        with self._lock:
+            self.conn.execute(
+                """
+                INSERT OR IGNORE INTO _run_tool_dependencies (
+                    run_id, pending_tool_call_id, dependency_kind, resolved_at,
+                    consumed_at
+                ) VALUES (?,?,?,?,?)
+                """,
+                (
+                    record.run_id,
+                    record.pending_tool_call_id,
+                    record.dependency_kind.value,
+                    _dt_str(record.resolved_at),
+                    _dt_str(record.consumed_at),
+                ),
+            )
+            self.conn.commit()
+        row = self._fetchone(
+            """
+            SELECT * FROM _run_tool_dependencies
+            WHERE run_id = ? AND pending_tool_call_id = ?
+            """,
+            (record.run_id, record.pending_tool_call_id),
+        )
+        if row is None:  # pragma: no cover
+            raise RuntimeError("Failed to attach run tool dependency")
+        return _row_to_run_tool_dependency(row)
+
+    @SQLiteStorageBase.handle_exceptions
+    def count_unresolved_followup_dependencies(
+        self,
+        *,
+        org_id: str,
+        extractor_kind: str,
+        tool_name: str,
+    ) -> int:
+        row = self._fetchone(
+            """
+            SELECT COUNT(*) AS count
+            FROM _run_tool_dependencies d
+            JOIN _agent_runs r ON r.id = d.run_id
+            JOIN _pending_tool_calls p ON p.id = d.pending_tool_call_id
+            WHERE r.org_id = ?
+              AND r.extractor_kind = ?
+              AND p.tool_name = ?
+              AND p.status = ?
+              AND d.resolved_at IS NULL
+              AND d.consumed_at IS NULL
+            """,
+            (
+                org_id,
+                extractor_kind,
+                tool_name,
+                PendingToolCallStatus.PENDING.value,
+            ),
+        )
+        return int(row["count"]) if row is not None else 0
+
+    @SQLiteStorageBase.handle_exceptions
+    def list_run_tool_dependencies(self, run_id: str) -> list[RunToolDependencyRecord]:
+        rows = self._fetchall(
+            "SELECT * FROM _run_tool_dependencies WHERE run_id = ?",
+            (run_id,),
+        )
+        return [_row_to_run_tool_dependency(row) for row in rows]
+
+    @SQLiteStorageBase.handle_exceptions
+    def consume_run_tool_dependencies(self, run_id: str) -> int:
+        consumed_at = self._current_timestamp()
+        with self._lock:
+            cur = self.conn.execute(
+                """
+                UPDATE _run_tool_dependencies
+                SET consumed_at = ?
+                WHERE run_id = ?
+                  AND resolved_at IS NOT NULL
+                  AND consumed_at IS NULL
+                """,
+                (consumed_at, run_id),
+            )
+            self.conn.commit()
+        return int(cur.rowcount)

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/base/__init__.py

@@ -0,0 +1,6 @@
+"""SQLite storage base sub-mixins (peeled from _base.py)."""
+
+from ._deletion import SQLiteDeletionMixin
+from ._fts_vec import SQLiteFtsVecMixin
+
+__all__ = ["SQLiteDeletionMixin", "SQLiteFtsVecMixin"]

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/base/_deletion.py

@@ -0,0 +1,263 @@
+"""SQLite retention-hook + chunked bulk-delete helpers.
+
+Peeled verbatim from ``_base.py`` (Tier-1 storage decomposition). Composed into
+``SQLiteStorage`` ahead of ``SQLiteStorageBase`` so the atomic
+``_retention_perform_delete`` override wins over ``RetentionMixin``'s default.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+from reflexio.server.services.storage.retention import RetentionTarget
+from reflexio.server.services.storage.retention_mixin import (
+    RETENTION_DELETE_CHUNK,
+    chunked,
+)
+
+from .._base import SQLiteStorageBase
+
+
+class SQLiteDeletionMixin:
+    """Retention-hook impls + chunked bulk-delete helpers for SQLite storage."""
+
+    # Type hints for instance attributes/methods provided by SQLiteStorageBase via MRO
+    _lock: Any
+    conn: sqlite3.Connection
+    _fetchone: Any
+    _fetchall: Any
+    _has_sqlite_vec: bool
+
+    # -- Retention hooks (see RetentionMixin) --
+
+    @SQLiteStorageBase.handle_exceptions
+    def _retention_table_exists(self, table_name: str) -> bool:
+        row = self._fetchone(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?",
+            (table_name,),
+        )
+        return row is not None
+
+    @SQLiteStorageBase.handle_exceptions
+    def _retention_count_rows(self, target: RetentionTarget) -> int:
+        row = self._fetchone(f"SELECT COUNT(*) as cnt FROM {target.table_name}")  # noqa: S608
+        return int(row["cnt"]) if row else 0
+
+    @SQLiteStorageBase.handle_exceptions
+    def _retention_select_oldest_keys(
+        self, target: RetentionTarget, count: int
+    ) -> list[tuple[Any, ...]]:
+        id_sql = ", ".join(target.id_columns)
+        tiebreak_sql = id_sql
+        rows = self._fetchall(
+            f"SELECT {id_sql} FROM {target.table_name} "  # noqa: S608
+            f"ORDER BY {target.order_column} ASC, {tiebreak_sql} ASC LIMIT ?",
+            (count,),
+        )
+        return [tuple(row[col] for col in target.id_columns) for row in rows]
+
+    @SQLiteStorageBase.handle_exceptions
+    def _retention_perform_delete(
+        self, target: RetentionTarget, keys: list[tuple[Any, ...]]
+    ) -> None:
+        # Wrap dependency + target deletes in a single critical section so
+        # concurrent writers see either both or neither.
+        with self._lock:
+            try:
+                self._retention_delete_dependencies(target, keys)
+                self._retention_delete_target_rows(target, keys)
+                self.conn.commit()
+            except Exception:
+                self.conn.rollback()
+                raise
+
+    def _retention_delete_dependencies(
+        self, target: RetentionTarget, keys: list[tuple[Any, ...]]
+    ) -> None:
+        ids = [key[0] for key in keys]
+        target_name = target.name
+        if target_name == "requests":
+            self._delete_interactions_for_request_ids([str(v) for v in ids])
+        elif target_name == "interactions":
+            self._delete_interaction_search_rows([int(v) for v in ids])
+        elif target_name == "profiles":
+            self._delete_profile_search_rows([str(v) for v in ids])
+        elif target_name == "user_playbooks":
+            self._delete_source_windows_for_user_playbook_ids([int(v) for v in ids])
+            self._delete_playbook_search_rows(
+                "user", [int(v) for v in ids], commit=False
+            )
+        elif target_name == "agent_playbooks":
+            self._delete_source_windows_for_agent_playbook_ids([int(v) for v in ids])
+            self._delete_playbook_search_rows(
+                "agent", [int(v) for v in ids], commit=False
+            )
+        elif target_name == "playbook_optimization_jobs":
+            self._delete_optimizer_rows_for_job_ids([int(v) for v in ids])
+        elif target_name == "playbook_optimization_candidates":
+            self._delete_optimizer_evaluations_for_candidate_ids([int(v) for v in ids])
+
+    def _retention_delete_target_rows(
+        self, target: RetentionTarget, keys: list[tuple[Any, ...]]
+    ) -> None:
+        if len(target.id_columns) == 1:
+            self._delete_in_chunks(
+                target.table_name,
+                target.id_columns[0],
+                [key[0] for key in keys],
+            )
+            return
+        # Composite-key delete: chunk by row to bound parameter count.
+        params_per_key = len(target.id_columns)
+        rows_per_chunk = max(1, RETENTION_DELETE_CHUNK // params_per_key)
+        for chunk in chunked(keys, rows_per_chunk):
+            where = " OR ".join(
+                "("
+                + " AND ".join(f"{column} = ?" for column in target.id_columns)
+                + ")"
+                for _ in chunk
+            )
+            params = [value for key in chunk for value in key]
+            self.conn.execute(
+                f"DELETE FROM {target.table_name} WHERE {where}",  # noqa: S608
+                params,
+            )
+
+    # -- Chunked-delete primitives shared by the cascade helpers --
+
+    def _delete_in_chunks(
+        self, table_name: str, column_name: str, values: list[Any]
+    ) -> None:
+        """Chunked ``DELETE FROM table WHERE col IN (...)``.
+
+        Chunking keeps parameter count under ``SQLITE_MAX_VARIABLE_NUMBER``
+        on older sqlite builds (default 999) and avoids degenerate plans
+        on very large IN lists.
+        """
+        if not values:
+            return
+        for chunk in chunked(values):
+            placeholders = ",".join("?" for _ in chunk)
+            self.conn.execute(
+                f"DELETE FROM {table_name} WHERE {column_name} IN ({placeholders})",  # noqa: S608
+                chunk,
+            )
+
+    def _select_in_chunks(self, sql_template: str, values: list[Any]) -> list[Any]:
+        """Run ``sql_template`` (containing ``{placeholders}``) over chunks of
+        ``values`` and aggregate the result rows."""
+        results: list[Any] = []
+        for chunk in chunked(values):
+            placeholders = ",".join("?" for _ in chunk)
+            stmt = sql_template.format(placeholders=placeholders)
+            results.extend(self.conn.execute(stmt, chunk).fetchall())
+        return results
+
+    def _delete_interactions_for_request_ids(self, request_ids: list[str]) -> None:
+        if not request_ids:
+            return
+        rows = self._select_in_chunks(
+            "SELECT interaction_id FROM interactions WHERE request_id IN ({placeholders})",
+            request_ids,
+        )
+        self._delete_interaction_search_rows(
+            [int(row["interaction_id"]) for row in rows]
+        )
+        self._delete_in_chunks("interactions", "request_id", request_ids)
+
+    def _delete_interaction_search_rows(self, interaction_ids: list[int]) -> None:
+        """Remove fts + vec index rows for the given interaction IDs.
+
+        Non-committing: participates in the caller's transaction.  Only called
+        from inside the retention atomic block (_retention_perform_delete).
+        """
+        if not interaction_ids:
+            return
+        self._delete_in_chunks("interactions_fts", "rowid", interaction_ids)
+        if self._has_sqlite_vec:
+            self._delete_in_chunks("interactions_vec", "rowid", interaction_ids)
+
+    def _delete_profile_search_rows(self, profile_ids: list[str]) -> None:
+        """Remove fts + vec index rows for the given profile IDs.
+
+        Non-committing: participates in the caller's transaction.  Only called
+        from inside the retention atomic block (_retention_perform_delete).
+        profiles_fts is keyed by profile_id (TEXT); profiles_vec by rowid (INT).
+        """
+        if not profile_ids:
+            return
+        self._delete_in_chunks("profiles_fts", "profile_id", profile_ids)
+        if self._has_sqlite_vec:
+            rows = self._select_in_chunks(
+                "SELECT rowid FROM profiles WHERE profile_id IN ({placeholders})",
+                profile_ids,
+            )
+            rowids = [row["rowid"] for row in rows]
+            if rowids:
+                self._delete_in_chunks("profiles_vec", "rowid", rowids)
+
+    def _delete_playbook_search_rows(
+        self, kind: str, ids: list[int], *, commit: bool = True
+    ) -> None:
+        """Remove fts + vec index rows for the given playbook IDs.
+
+        Args:
+            kind: ``"user"`` or ``"agent"``.
+            ids: Playbook row IDs to remove from the search indexes.
+            commit: When ``True`` (default) commits after the deletes so the
+                after-commit callers in ``_playbook.py`` get a clean, durable
+                cleanup.  Pass ``commit=False`` from inside the retention atomic
+                block so the deletes participate in the single block-level commit
+                (``_retention_perform_delete``).
+
+        Note: callers may already hold ``self._lock`` when calling this (the
+        ``commit=False`` retention/atomic-delete call sites do). The internal
+        ``with self._lock:`` re-acquire is safe ONLY because ``self._lock`` is a
+        reentrant ``threading.RLock``; a non-reentrant lock would deadlock here.
+        """
+        if not ids:
+            return
+        with self._lock:
+            self._delete_in_chunks(f"{kind}_playbooks_fts", "rowid", ids)
+            if self._has_sqlite_vec:
+                self._delete_in_chunks(f"{kind}_playbooks_vec", "rowid", ids)
+            if commit:
+                self.conn.commit()
+
+    def _delete_source_windows_for_agent_playbook_ids(
+        self, agent_playbook_ids: list[int]
+    ) -> None:
+        self._delete_in_chunks(
+            "agent_playbook_source_user_playbooks",
+            "agent_playbook_id",
+            agent_playbook_ids,
+        )
+
+    def _delete_source_windows_for_user_playbook_ids(
+        self, user_playbook_ids: list[int]
+    ) -> None:
+        self._delete_in_chunks(
+            "agent_playbook_source_user_playbooks",
+            "user_playbook_id",
+            user_playbook_ids,
+        )
+
+    def _delete_optimizer_rows_for_job_ids(self, job_ids: list[int]) -> None:
+        if not job_ids:
+            return
+        for table in (
+            "playbook_optimization_evaluations",
+            "playbook_optimization_events",
+            "playbook_optimization_candidates",
+        ):
+            self._delete_in_chunks(table, "job_id", job_ids)
+
+    def _delete_optimizer_evaluations_for_candidate_ids(
+        self, candidate_ids: list[int]
+    ) -> None:
+        self._delete_in_chunks(
+            "playbook_optimization_evaluations",
+            "candidate_id",
+            candidate_ids,
+        )

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/base/_fts_vec.py

@@ -0,0 +1,132 @@
+"""SQLite FTS5 + sqlite-vec index maintenance helpers.
+
+Peeled verbatim from ``_base.py`` (Tier-1 storage decomposition). These helpers
+are **self-committing**: each calls ``self.conn.commit()`` internally so the
+index sidecar update is durable. They are sqlite-only — there is no
+supabase/postgres counterpart. Composed into ``SQLiteStorage`` ahead of
+``SQLiteStorageBase``; the boot-time ``_migrate_vec_tables`` (residual in
+``_base.py``) resolves ``self._vec_upsert`` through the composed MRO.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any
+
+
+class SQLiteFtsVecMixin:
+    """FTS5 + sqlite-vec index-maintenance helpers for SQLite storage."""
+
+    # Type hints for instance attributes/methods provided by SQLiteStorageBase via MRO
+    _lock: Any
+    conn: sqlite3.Connection
+    _fetchall: Any
+    _has_sqlite_vec: bool
+
+    # FTS helpers
+    def _fts_upsert(self, table: str, rowid: int, **text_fields: str | None) -> None:
+        """Insert or update an FTS row.  Deletes old entry first to avoid duplicates."""
+        with self._lock:
+            self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
+            cols = list(text_fields.keys())
+            vals = [text_fields[c] or "" for c in cols]
+            placeholders = ",".join("?" for _ in cols)
+            col_str = ",".join(cols)
+            self.conn.execute(
+                f"INSERT INTO {table}(rowid, {col_str}) VALUES (?, {placeholders})",  # noqa: S608
+                [rowid, *vals],
+            )
+            self.conn.commit()
+
+    def _fts_delete(self, table: str, rowid: int) -> None:
+        with self._lock:
+            self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
+            self.conn.commit()
+
+    def _fts_upsert_profile(self, profile_id: str, content: str) -> None:
+        """FTS for profiles uses profile_id TEXT as key column."""
+        with self._lock:
+            self.conn.execute(
+                "DELETE FROM profiles_fts WHERE profile_id = ?", (profile_id,)
+            )
+            self.conn.execute(
+                "INSERT INTO profiles_fts(profile_id, content) VALUES (?, ?)",
+                (profile_id, content),
+            )
+            self.conn.commit()
+
+    def _fts_delete_profile(self, profile_id: str) -> None:
+        with self._lock:
+            self.conn.execute(
+                "DELETE FROM profiles_fts WHERE profile_id = ?", (profile_id,)
+            )
+            self.conn.commit()
+
+    # Vec helpers (sqlite-vec)
+    def _vec_upsert(self, table: str, rowid: int, embedding: list[float]) -> None:
+        """Insert or update a vec table row. No-op when sqlite-vec is unavailable."""
+        if not self._has_sqlite_vec:
+            return
+        with self._lock:
+            self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
+            self.conn.execute(
+                f"INSERT INTO {table}(rowid, embedding) VALUES (?, ?)",  # noqa: S608
+                (rowid, json.dumps(embedding)),
+            )
+            self.conn.commit()
+
+    def _vec_delete(self, table: str, rowid: int) -> None:
+        """Delete a vec table row. No-op when sqlite-vec is unavailable."""
+        if not self._has_sqlite_vec:
+            return
+        with self._lock:
+            self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
+            self.conn.commit()
+
+    def _vec_knn_search(
+        self,
+        vec_table: str,
+        main_table: str,
+        query_embedding: list[float],
+        match_count: int,
+        conditions: list[str] | None = None,
+        params: list[Any] | None = None,
+    ) -> list[sqlite3.Row]:
+        """Run a native KNN search via sqlite-vec and join back to the main table.
+
+        Over-fetches from the KNN index (5x ``match_count``) so that post-filter
+        WHERE conditions (org, user, status, etc.) don't silently reduce the
+        result set below the requested count.
+
+        Args:
+            vec_table: Name of the vec0 virtual table.
+            main_table: Name of the main data table.
+            query_embedding: Query embedding vector.
+            match_count: Number of results to return.
+            conditions: Optional WHERE conditions for the main table.
+            params: Parameters for the conditions.
+
+        Returns:
+            Up to ``match_count`` rows from the main table, ordered by vector
+            distance (ascending).
+        """
+        knn_overfetch = match_count * 5
+        where_clause = " AND ".join(conditions) if conditions else "1=1"
+        sql = f"""SELECT m.* FROM {main_table} m
+                  JOIN (
+                      SELECT rowid, distance FROM {vec_table}
+                      WHERE embedding MATCH ?
+                      ORDER BY distance
+                      LIMIT ?
+                  ) v ON m.rowid = v.rowid
+                  WHERE {where_clause}
+                  ORDER BY v.distance
+                  LIMIT ?"""  # noqa: S608
+        all_params = [
+            json.dumps(query_embedding),
+            knn_overfetch,
+            *(params or []),
+            match_count,
+        ]
+        return self._fetchall(sql, all_params)

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/governance/__init__.py

@@ -0,0 +1,13 @@
+from ._audit import AuditEventStoreMixin
+from ._erase_execution import GovernanceEraseExecutionMixin
+from ._purge import PurgeOperationStoreMixin
+from ._rebuild_hide import RebuildHideMixin
+from ._subject_barrier import SubjectBarrierMixin
+
+__all__ = [
+    "AuditEventStoreMixin",
+    "GovernanceEraseExecutionMixin",
+    "PurgeOperationStoreMixin",
+    "RebuildHideMixin",
+    "SubjectBarrierMixin",
+]

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/governance/_audit.py

@@ -0,0 +1,122 @@
+"""SQLite audit-event store methods.
+
+Extracted verbatim from ``_governance.py`` (the AuditEventStore bucket): the
+three public methods (``append_audit_event``, ``list_audit_events``,
+``gc_governance_retention``) plus the Audit-owned private
+``_append_audit_event_with_cursor`` (called cross-bucket by the residual purge /
+barrier completion methods, which reach it via MRO co-composition).
+
+The residual ``SQLiteGovernanceMixin`` stays composed alongside this mixin and
+permanently holds the shared infra (``conn``, ``_lock``, ``org_id``, ``_deps()``)
+and the module-level helpers (``_json_dumps``, ``_row_to_audit_event``), which
+are imported here rather than duplicated.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from reflexio.models.api_schema.domain.governance import AuditEvent
+from reflexio.models.config_schema import GovernanceRetentionConfig
+from reflexio.server.services.storage.governance_validation import (
+    _canonicalize_audit_event_for_persistence,
+    _epoch_now,
+    _is_successful_erase_event,
+)
+
+from .._governance import _json_dumps, _row_to_audit_event
+
+if TYPE_CHECKING:
+    from .._governance import _SQLiteGovernanceDeps
+
+
+class AuditEventStoreMixin:
+    """SQLite audit-event store primitives."""
+
+    # Type hints for instance attributes/methods provided via MRO by the
+    # co-composed residual SQLiteGovernanceMixin / SQLiteStorageBase.
+    conn: sqlite3.Connection
+    _lock: threading.RLock
+    org_id: str
+    _deps: Callable[[], _SQLiteGovernanceDeps]
+
+    def _append_audit_event_with_cursor(
+        self, cur: sqlite3.Connection | sqlite3.Cursor, event: AuditEvent
+    ) -> bool:
+        inserted = cur.execute(
+            """INSERT OR IGNORE INTO audit_events (
+                   org_id, actor_type, actor_ref, operation, entity_type, entity_id,
+                   subject_ref, request_ref, idempotency_key, status, detail, created_at
+               ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                event.org_id,
+                event.actor_type,
+                event.actor_ref,
+                event.operation,
+                event.entity_type,
+                event.entity_id,
+                event.subject_ref,
+                event.request_ref,
+                event.idempotency_key,
+                event.status,
+                _json_dumps(event.detail),
+                event.created_at,
+            ),
+        )
+        return inserted.rowcount > 0
+
+    def append_audit_event(self, event: AuditEvent) -> bool:
+        if _is_successful_erase_event(event):
+            raise ValueError(
+                "Successful ERASE audit rows may only be written by "
+                "complete_purge_operation_with_audit()"
+            )
+        if event.org_id != self.org_id:
+            raise ValueError("Audit event org_id must match storage org_id")
+        event = _canonicalize_audit_event_for_persistence(event)
+        with self._lock:
+            inserted = self._append_audit_event_with_cursor(self.conn, event)
+            self.conn.commit()
+            return inserted
+
+    def list_audit_events(
+        self, subject_ref: str | None = None, *, org_id: str | None = None
+    ) -> list[AuditEvent]:
+        deps = self._deps()
+        if org_id is not None and org_id != self.org_id:
+            raise ValueError("Audit event org_id must match storage org_id")
+        sql = "SELECT * FROM audit_events WHERE org_id = ?"
+        params: list[Any] = [self.org_id]
+        if subject_ref is not None:
+            sql += " AND subject_ref = ?"
+            params.append(subject_ref)
+        sql += " ORDER BY created_at ASC, event_id ASC"
+        rows = deps._fetchall(sql, params)
+        return [_row_to_audit_event(row) for row in rows]
+
+    def gc_governance_retention(self, *, config: GovernanceRetentionConfig) -> int:
+        if not config.audit_events_retention_enabled:
+            return 0
+        cutoff_epoch = _epoch_now() - config.audit_events_retention_days * 24 * 60 * 60
+        with self._lock:
+            cur = self.conn.execute(
+                """DELETE FROM audit_events
+                   WHERE event_id IN (
+                       SELECT event_id
+                       FROM audit_events
+                       WHERE org_id = ? AND created_at < ?
+                       ORDER BY created_at ASC, event_id ASC
+                       LIMIT ?
+                   )""",
+                (
+                    self.org_id,
+                    cutoff_epoch,
+                    config.audit_events_delete_batch_limit,
+                ),
+            )
+            deleted = int(cur.rowcount or 0)
+            self.conn.commit()
+        return deleted