claude-smart 0.2.46 → 0.2.47

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/_playbook.py

@@ -1,54 +1,9 @@
 """Playbook CRUD + search methods for SQLite storage."""
 
-import json
-import logging
 import sqlite3
-import uuid
-from collections.abc import Sequence
-from concurrent.futures import ThreadPoolExecutor
 from typing import Any
 
-logger = logging.getLogger(__name__)
-
-from reflexio.models.api_schema.common import BlockingIssue
-from reflexio.models.api_schema.retriever_schema import (
-    SearchAgentPlaybookRequest,
-    SearchUserPlaybookRequest,
-)
-from reflexio.models.api_schema.service_schemas import (
-    AgentPlaybook,
-    AgentPlaybookSourceWindow,
-    AgentSuccessEvaluationResult,
-    PlaybookOptimizationCandidate,
-    PlaybookOptimizationEvaluation,
-    PlaybookOptimizationEvent,
-    PlaybookOptimizationJob,
-    PlaybookStatus,
-    Status,
-    UserPlaybook,
-)
-from reflexio.models.config_schema import SearchMode, SearchOptions
-from reflexio.server.services.storage.storage_base._playbook import (
-    AGGREGATE_REASON_PREFIX,
-)
-
-from ._base import (
-    _TOMBSTONE_STATUS_VALUES,
-    SQLiteStorageBase,
-    _build_status_sql,
-    _effective_search_mode,
-    _epoch_now,
-    _epoch_to_iso,
-    _json_dumps,
-    _json_loads,
-    _row_to_agent_playbook,
-    _row_to_eval_result,
-    _row_to_user_playbook,
-    _sanitize_fts_query,
-    _true_rrf_merge,
-    _vector_rank_rows,
-)
-from ._lineage import _GC_ELIGIBLE_STATUSES, _append_event_stmt
+from ._lineage import _append_event_stmt
 
 
 def _emit_hard_delete_playbook(
@@ -75,96 +30,6 @@ def _emit_hard_delete_playbook(
     )
 
 
-def _emit_supersede_playbook(
-    conn: sqlite3.Connection,
-    *,
-    org_id: str,
-    entity_id: str,
-    old_status: str | None,
-    request_id: str,
-) -> None:
-    """Emit a single status_change->superseded lineage event for an agent playbook."""
-    _append_event_stmt(
-        conn,
-        org_id=org_id,
-        entity_type="agent_playbook",
-        entity_id=entity_id,
-        op="status_change",
-        prov="wasInvalidatedBy",
-        source_ids=[],
-        actor="aggregator",
-        request_id=request_id,
-        reason=f"{old_status or 'None'}->superseded",
-        from_status=old_status,
-        to_status=Status.SUPERSEDED.value,
-        status_namespace="lifecycle_status",
-    )
-
-
-def _emit_supersede_user_playbook(
-    conn: sqlite3.Connection,
-    *,
-    org_id: str,
-    entity_id: str,
-    old_status: str | None,
-    request_id: str,
-) -> None:
-    """Emit a single status_change->superseded lineage event for a user playbook."""
-    _append_event_stmt(
-        conn,
-        org_id=org_id,
-        entity_type="user_playbook",
-        entity_id=entity_id,
-        op="status_change",
-        prov="wasInvalidatedBy",
-        source_ids=[],
-        actor="consolidator",
-        request_id=request_id,
-        reason=f"{old_status or 'None'}->superseded",
-        from_status=old_status,
-        to_status=Status.SUPERSEDED.value,
-        status_namespace="lifecycle_status",
-    )
-
-
-def _row_to_playbook_optimization_candidate(
-    row: sqlite3.Row,
-) -> PlaybookOptimizationCandidate:
-    return PlaybookOptimizationCandidate(
-        candidate_id=row["candidate_id"],
-        job_id=row["job_id"],
-        candidate_index=row["candidate_index"],
-        content=row["content"],
-        parent_candidate_ids=_json_loads(row["parent_candidate_ids"]) or [],
-        aggregate_score=row["aggregate_score"],
-        is_winner=bool(row["is_winner"]),
-        metadata_json=row["metadata_json"] or "{}",
-        created_at=row["created_at"],
-    )
-
-
-def _row_to_playbook_optimization_evaluation(
-    row: sqlite3.Row,
-) -> PlaybookOptimizationEvaluation:
-    return PlaybookOptimizationEvaluation(
-        evaluation_id=row["evaluation_id"],
-        job_id=row["job_id"],
-        candidate_id=row["candidate_id"],
-        target_kind=row["target_kind"],
-        target_id=row["target_id"],
-        scenario_user_playbook_id=row["scenario_user_playbook_id"],
-        source_interaction_ids=_json_loads(row["source_interaction_ids"]) or [],
-        score=row["score"],
-        verdict=row["verdict"],
-        likert=row["likert"],
-        rationale=row["rationale"],
-        asi_json=row["asi_json"],
-        incumbent_rollout_json=row["incumbent_rollout_json"],
-        candidate_rollout_json=row["candidate_rollout_json"],
-        created_at=row["created_at"],
-    )
-
-
 def _build_tags_sql(alias: str, tags: list[str] | None) -> tuple[str, list[Any]]:
     if not tags:
         return "", []
@@ -173,2000 +38,3 @@ def _build_tags_sql(alias: str, tags: list[str] | None) -> tuple[str, list[Any]]
         f"EXISTS (SELECT 1 FROM json_each({alias}.tags) WHERE value IN ({placeholders}))",
         list(tags),
     )
-
-
-class PlaybookMixin:
-    """Mixin providing user playbook, agent playbook, and evaluation CRUD + search."""
-
-    # Type hints for instance attributes/methods provided by SQLiteStorageBase via MRO
-    _lock: Any
-    conn: sqlite3.Connection
-    org_id: str
-    _execute: Any
-    _fetchone: Any
-    _fetchall: Any
-    _get_embedding: Any
-    _should_expand_documents: Any
-    _expand_document: Any
-    _fts_upsert: Any
-    _fts_delete: Any
-    _vec_upsert: Any
-    _vec_delete: Any
-    _delete_playbook_search_rows: Any
-    _has_sqlite_vec: bool
-
-    # ------------------------------------------------------------------
-    # User Playbook methods
-    # ------------------------------------------------------------------
-
-    @SQLiteStorageBase.handle_exceptions
-    def save_user_playbooks(self, user_playbooks: list[UserPlaybook]) -> None:
-        for up in user_playbooks:
-            embedding_text = up.trigger or up.content
-            if embedding_text:
-                if self._should_expand_documents():
-                    with ThreadPoolExecutor(max_workers=2) as executor:
-                        emb_future = executor.submit(
-                            self._get_embedding, embedding_text
-                        )
-                        exp_future = executor.submit(
-                            self._expand_document, embedding_text
-                        )
-                        up.embedding = emb_future.result(timeout=15)
-                        up.expanded_terms = exp_future.result(timeout=15)
-                else:
-                    up.embedding = self._get_embedding(embedding_text)
-
-            created_at_iso = _epoch_to_iso(up.created_at)
-            with self._lock:
-                cur = self.conn.execute(
-                    """INSERT INTO user_playbooks
-                       (user_id, playbook_name, created_at, request_id, agent_version,
-                        content, trigger, rationale, blocking_issue,
-                        source_interaction_ids,
-                        status, source, embedding, expanded_terms,
-                        source_span, notes, reader_angle, tags,
-                        merged_into, superseded_by)
-                       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
-                    (
-                        up.user_id,
-                        up.playbook_name,
-                        created_at_iso,
-                        up.request_id,
-                        up.agent_version,
-                        up.content,
-                        up.trigger,
-                        up.rationale,
-                        json.dumps(up.blocking_issue.model_dump())
-                        if up.blocking_issue
-                        else None,
-                        _json_dumps(up.source_interaction_ids or None),
-                        up.status.value if up.status else None,
-                        up.source,
-                        _json_dumps(up.embedding),
-                        up.expanded_terms,
-                        up.source_span,
-                        up.notes,
-                        up.reader_angle,
-                        _json_dumps(up.tags),
-                        up.merged_into,
-                        up.superseded_by,
-                    ),
-                )
-                upid = cur.lastrowid or 0
-                up.user_playbook_id = upid
-                self.conn.commit()
-
-            fts_parts = [up.trigger or "", up.content or ""]
-            if up.expanded_terms:
-                fts_parts.append(up.expanded_terms)
-            self._fts_upsert(
-                "user_playbooks_fts",
-                upid,
-                search_text=" ".join(p for p in fts_parts if p) or "",
-            )
-            if up.embedding:
-                self._vec_upsert("user_playbooks_vec", upid, up.embedding)
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_user_playbooks(
-        self,
-        limit: int = 100,
-        user_id: str | None = None,
-        playbook_name: str | None = None,
-        agent_version: str | None = None,
-        status_filter: list[Status | None] | None = None,
-        start_time: int | None = None,
-        end_time: int | None = None,
-        include_embedding: bool = False,
-        tags: list[str] | None = None,
-    ) -> list[UserPlaybook]:
-        sql = "SELECT * FROM user_playbooks WHERE 1=1"
-        params: list[Any] = []
-
-        if user_id is not None:
-            sql += " AND user_id = ?"
-            params.append(user_id)
-        if playbook_name:
-            sql += " AND playbook_name = ?"
-            params.append(playbook_name)
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        if start_time is not None:
-            sql += " AND created_at >= ?"
-            params.append(_epoch_to_iso(start_time))
-        if end_time is not None:
-            sql += " AND created_at <= ?"
-            params.append(_epoch_to_iso(end_time))
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            sql += f" AND {frag}"
-            params.extend(sparams)
-        else:
-            # Default: exclude tombstone statuses (MERGED/SUPERSEDED)
-            sql += " AND (status IS NULL OR status NOT IN (?, ?))"
-            params.extend(_TOMBSTONE_STATUS_VALUES)
-        tag_frag, tag_params = _build_tags_sql("user_playbooks", tags)
-        if tag_frag:
-            sql += f" AND {tag_frag}"
-            params.extend(tag_params)
-
-        sql += " ORDER BY created_at DESC LIMIT ?"
-        params.append(limit)
-        rows = self._fetchall(sql, params)
-        return [
-            _row_to_user_playbook(r, include_embedding=include_embedding) for r in rows
-        ]
-
-    @SQLiteStorageBase.handle_exceptions
-    def count_user_playbooks(
-        self,
-        user_id: str | None = None,
-        playbook_name: str | None = None,
-        min_user_playbook_id: int | None = None,
-        agent_version: str | None = None,
-        status_filter: list[Status | None] | None = None,
-    ) -> int:
-        sql = "SELECT COUNT(*) as cnt FROM user_playbooks WHERE 1=1"
-        params: list[Any] = []
-
-        if user_id is not None:
-            sql += " AND user_id = ?"
-            params.append(user_id)
-        if playbook_name:
-            sql += " AND playbook_name = ?"
-            params.append(playbook_name)
-        if min_user_playbook_id is not None:
-            sql += " AND user_playbook_id > ?"
-            params.append(min_user_playbook_id)
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            sql += f" AND {frag}"
-            params.extend(sparams)
-        else:
-            # Default: exclude tombstone statuses (MERGED/SUPERSEDED)
-            sql += " AND (status IS NULL OR status NOT IN (?, ?))"
-            params.extend(_TOMBSTONE_STATUS_VALUES)
-
-        row = self._fetchone(sql, params)
-        return row["cnt"] if row else 0
-
-    @SQLiteStorageBase.handle_exceptions
-    def count_user_playbooks_by_session(self, session_id: str) -> int:
-        row = self._fetchone(
-            """SELECT COUNT(*) as cnt FROM user_playbooks up
-               JOIN requests r ON up.request_id = r.request_id
-               WHERE r.session_id = ?
-                 AND (up.status IS NULL OR up.status NOT IN (?, ?))""",
-            (session_id, *_TOMBSTONE_STATUS_VALUES),
-        )
-        return row["cnt"] if row else 0
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_user_playbooks(self) -> None:
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            ids = [
-                r["user_playbook_id"]
-                for r in self.conn.execute(
-                    "SELECT user_playbook_id FROM user_playbooks"
-                ).fetchall()
-            ]
-            self.conn.execute("DELETE FROM user_playbooks")
-            for upid in ids:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="user_playbook",
-                    entity_id=str(upid),
-                    request_id=batch_request_id,
-                )
-            self.conn.commit()
-        self._delete_playbook_search_rows("user", ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_user_playbook(self, user_playbook_id: int) -> None:
-        with self._lock:
-            cur = self.conn.execute(
-                "DELETE FROM user_playbooks WHERE user_playbook_id = ?",
-                (user_playbook_id,),
-            )
-            if cur.rowcount > 0:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="user_playbook",
-                    entity_id=str(user_playbook_id),
-                    request_id=uuid.uuid4().hex,
-                )
-            self._delete_playbook_search_rows("user", [user_playbook_id], commit=False)
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_user_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None = None
-    ) -> None:
-        sql = "SELECT user_playbook_id FROM user_playbooks WHERE playbook_name = ?"
-        params: list[Any] = [playbook_name]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            ids = [
-                r["user_playbook_id"] for r in self.conn.execute(sql, params).fetchall()
-            ]
-            if not ids:
-                return
-            ph = ",".join("?" for _ in ids)
-            self.conn.execute(
-                f"DELETE FROM user_playbooks WHERE user_playbook_id IN ({ph})", ids
-            )
-            for upid in ids:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="user_playbook",
-                    entity_id=str(upid),
-                    request_id=batch_request_id,
-                )
-            self.conn.commit()
-        self._delete_playbook_search_rows("user", ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_user_playbooks_by_ids(
-        self, user_playbook_ids: list[int], *, emit_hard_delete: bool = True
-    ) -> int:
-        if not user_playbook_ids:
-            return 0
-        ph = ",".join("?" for _ in user_playbook_ids)
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            existing = [
-                r["user_playbook_id"]
-                for r in self.conn.execute(
-                    f"SELECT user_playbook_id FROM user_playbooks WHERE user_playbook_id IN ({ph})",
-                    user_playbook_ids,
-                ).fetchall()
-            ]
-            cur = self.conn.execute(
-                f"DELETE FROM user_playbooks WHERE user_playbook_id IN ({ph})",
-                user_playbook_ids,
-            )
-            if emit_hard_delete:
-                for upid in existing:
-                    _emit_hard_delete_playbook(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_type="user_playbook",
-                        entity_id=str(upid),
-                        request_id=batch_request_id,
-                        actor="system",
-                    )
-            self.conn.commit()
-        self._delete_playbook_search_rows("user", user_playbook_ids)
-        return cur.rowcount
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_all_user_playbooks_status(
-        self,
-        old_status: Status | None,
-        new_status: Status | None,
-        agent_version: str | None = None,
-        playbook_name: str | None = None,
-    ) -> int:
-        new_val = new_status.value if new_status else None
-        now_ts = _epoch_now()
-        old_val_str = old_status.value if old_status else "None"
-        new_val_str = new_status.value if new_status else "None"
-        reason = f"{old_val_str}->{new_val_str}"
-
-        if old_status is None or (
-            hasattr(old_status, "value") and old_status.value is None
-        ):
-            where = "status IS NULL"
-            select_params: list[Any] = []
-        else:
-            where = "status = ?"
-            select_params = [old_status.value]
-
-        extra_params: list[Any] = []
-        if agent_version is not None:
-            where += " AND agent_version = ?"
-            extra_params.append(agent_version)
-        if playbook_name is not None:
-            where += " AND playbook_name = ?"
-            extra_params.append(playbook_name)
-
-        # Set retired_at = now when transitioning to a GC-eligible status; clear to NULL otherwise.
-        retired_at_val = now_ts if new_val in _GC_ELIGIBLE_STATUSES else None
-
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            affected = [
-                r["user_playbook_id"]
-                for r in self.conn.execute(
-                    f"SELECT user_playbook_id FROM user_playbooks WHERE {where}",
-                    select_params + extra_params,
-                ).fetchall()
-            ]
-            cur = self.conn.execute(
-                f"UPDATE user_playbooks SET status = ?, retired_at = ? WHERE {where}",
-                [new_val, retired_at_val] + select_params + extra_params,
-            )
-            from_val = old_status.value if old_status else None
-            to_val = new_status.value if new_status else None
-            for upid in affected:
-                _append_event_stmt(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="user_playbook",
-                    entity_id=str(upid),
-                    op="status_change",
-                    prov="wasInvalidatedBy",
-                    source_ids=[],
-                    actor="api",
-                    request_id=batch_request_id,
-                    reason=reason,
-                    from_status=from_val,
-                    to_status=to_val,
-                    status_namespace="lifecycle_status",
-                )
-            self.conn.commit()
-        return cur.rowcount
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_user_playbooks_by_status(
-        self,
-        status: Status,
-        agent_version: str | None = None,
-        playbook_name: str | None = None,
-    ) -> int:
-        # Bulk delete-by-status emits no hard_delete lineage events (parity with
-        # the Supabase backend, which routes this through _hard_delete_and_log with
-        # emit_hard_delete=False). Accepts any status: the upgrade flow legitimately
-        # deletes old ARCHIVED playbooks via _delete_items_by_status(Status.ARCHIVED).
-        where = "status = ?"
-        params: list[Any] = [status.value]
-        if agent_version is not None:
-            where += " AND agent_version = ?"
-            params.append(agent_version)
-        if playbook_name is not None:
-            where += " AND playbook_name = ?"
-            params.append(playbook_name)
-
-        with self._lock:
-            ids = [
-                r["user_playbook_id"]
-                for r in self.conn.execute(
-                    f"SELECT user_playbook_id FROM user_playbooks WHERE {where}",
-                    params,  # noqa: S608
-                ).fetchall()
-            ]
-            if not ids:
-                return 0
-            ph = ",".join("?" for _ in ids)
-            cur = self.conn.execute(
-                f"DELETE FROM user_playbooks WHERE user_playbook_id IN ({ph})",  # noqa: S608
-                ids,
-            )
-            self._delete_playbook_search_rows("user", ids, commit=False)
-            self.conn.commit()
-        return cur.rowcount
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_user_playbooks_by_ids(
-        self,
-        user_id: str,
-        user_playbook_ids: list[int],
-        status_filter: list[Status | None] | None = None,
-    ) -> list[UserPlaybook]:
-        if not user_playbook_ids:
-            return []
-        if status_filter is None:
-            status_filter = [None]
-        frag, sparams = _build_status_sql(status_filter)
-        ph = ",".join("?" for _ in user_playbook_ids)
-        sql = (
-            f"SELECT * FROM user_playbooks "
-            f"WHERE user_id = ? AND user_playbook_id IN ({ph}) AND {frag}"
-        )
-        params: list[Any] = [user_id, *user_playbook_ids, *sparams]
-        return [_row_to_user_playbook(r) for r in self._fetchall(sql, params)]
-
-    @SQLiteStorageBase.handle_exceptions
-    def archive_user_playbook_by_id(self, user_id: str, user_playbook_id: int) -> bool:
-        cur = self._execute(
-            "UPDATE user_playbooks SET status = ?, retired_at = ? "
-            "WHERE user_playbook_id = ? AND user_id = ? AND status IS NULL",
-            (Status.ARCHIVED.value, _epoch_now(), user_playbook_id, user_id),
-        )
-        return cur.rowcount > 0
-
-    @SQLiteStorageBase.handle_exceptions
-    def has_user_playbooks_with_status(
-        self,
-        status: Status | None,
-        agent_version: str | None = None,
-        playbook_name: str | None = None,
-    ) -> bool:
-        sql = "SELECT 1 FROM user_playbooks WHERE "
-        params: list[Any] = []
-
-        if status is None or (hasattr(status, "value") and status.value is None):
-            sql += "status IS NULL"
-        else:
-            sql += "status = ?"
-            params.append(status.value)
-
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        if playbook_name is not None:
-            sql += " AND playbook_name = ?"
-            params.append(playbook_name)
-
-        sql += " LIMIT 1"
-        row = self._fetchone(sql, params)
-        return row is not None
-
-    @SQLiteStorageBase.handle_exceptions
-    def search_user_playbooks(  # noqa: C901
-        self,
-        request: SearchUserPlaybookRequest,
-        options: SearchOptions | None = None,
-    ) -> list[UserPlaybook]:
-        query = request.query
-        user_id = request.user_id
-        agent_version = request.agent_version
-        playbook_name = request.playbook_name
-        start_time = int(request.start_time.timestamp()) if request.start_time else None
-        end_time = int(request.end_time.timestamp()) if request.end_time else None
-        status_filter = request.status_filter
-        match_count = request.top_k or 10
-        query_embedding = options.query_embedding if options else None
-        mode = _effective_search_mode(
-            request.search_mode, query_embedding, request.query
-        )
-        rrf_k = options.rrf_k if options else 60
-        vector_weight = options.vector_weight if options else 1.0
-        fts_weight = options.fts_weight if options else 1.0
-
-        conditions: list[str] = []
-        params: list[Any] = []
-
-        if user_id:
-            conditions.append("up.user_id = ?")
-            params.append(user_id)
-        if agent_version:
-            conditions.append("up.agent_version = ?")
-            params.append(agent_version)
-        if playbook_name:
-            conditions.append("up.playbook_name = ?")
-            params.append(playbook_name)
-        if start_time:
-            conditions.append("up.created_at >= ?")
-            params.append(_epoch_to_iso(start_time))
-        if end_time:
-            conditions.append("up.created_at <= ?")
-            params.append(_epoch_to_iso(end_time))
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            conditions.append(frag)
-            params.extend(sparams)
-        else:
-            # Default: exclude tombstone statuses (MERGED/SUPERSEDED)
-            conditions.append("(up.status IS NULL OR up.status NOT IN (?, ?))")
-            params.extend(_TOMBSTONE_STATUS_VALUES)
-        tag_frag, tag_params = _build_tags_sql("up", request.tags)
-        if tag_frag:
-            conditions.append(tag_frag)
-            params.extend(tag_params)
-
-        where_extra = (" AND " + " AND ".join(conditions)) if conditions else ""
-        overfetch = match_count * 5 if mode != SearchMode.FTS else match_count
-
-        # Pure vector search: fetch all candidates, rank by cosine similarity
-        if mode == SearchMode.VECTOR and query_embedding:
-            base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-            sql = f"""SELECT * FROM user_playbooks up
-                      {base_where}
-                      ORDER BY up.created_at DESC"""
-            rows = self._fetchall(sql, params)
-            rows = _vector_rank_rows(rows, query_embedding, match_count)
-            return [_row_to_user_playbook(r) for r in rows]
-
-        if query:
-            fts_query = _sanitize_fts_query(query)
-            sql = f"""SELECT up.* FROM user_playbooks up
-                      JOIN user_playbooks_fts f ON up.user_playbook_id = f.rowid
-                      WHERE user_playbooks_fts MATCH ?{where_extra}
-                      ORDER BY bm25(user_playbooks_fts, 1.0)
-                      LIMIT ?"""
-            fts_rows = self._fetchall(sql, [fts_query, *params, overfetch])
-
-            if mode == SearchMode.HYBRID and query_embedding:
-                base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-                vec_limit = match_count * 10
-                vec_sql = f"""SELECT * FROM user_playbooks up
-                              {base_where}
-                              ORDER BY up.created_at DESC
-                              LIMIT ?"""
-                vec_candidates = self._fetchall(vec_sql, [*params, vec_limit])
-                vec_rows = _vector_rank_rows(vec_candidates, query_embedding, overfetch)
-                rows = _true_rrf_merge(
-                    fts_rows,
-                    vec_rows,
-                    "user_playbook_id",
-                    match_count,
-                    rrf_k,
-                    vector_weight,
-                    fts_weight,
-                )
-                return [_row_to_user_playbook(r) for r in rows]
-            return [_row_to_user_playbook(r) for r in fts_rows[:match_count]]
-
-        # HYBRID without query text: rank by embedding only
-        if query_embedding:
-            base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-            sql = f"""SELECT * FROM user_playbooks up
-                      {base_where}
-                      ORDER BY up.created_at DESC"""
-            rows = self._fetchall(sql, params)
-            rows = _vector_rank_rows(rows, query_embedding, match_count)
-            return [_row_to_user_playbook(r) for r in rows]
-
-        # No query text, no embedding -- recency fallback
-        base_where = "WHERE " + " AND ".join(conditions) if conditions else "WHERE 1=1"
-        sql = f"""SELECT * FROM user_playbooks up
-                  {base_where}
-                  ORDER BY up.created_at DESC LIMIT ?"""
-        params.append(match_count)
-        rows = self._fetchall(sql, params)
-        return [_row_to_user_playbook(r) for r in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_user_playbook_by_id(
-        self, user_playbook_id: int, *, include_tombstones: bool = False
-    ) -> UserPlaybook | None:
-        sql = "SELECT * FROM user_playbooks WHERE user_playbook_id = ?"
-        if not include_tombstones:
-            sql += " AND (status IS NULL OR status NOT IN (?, ?))"
-            row = self._fetchone(sql, (user_playbook_id, *_TOMBSTONE_STATUS_VALUES))
-        else:
-            row = self._fetchone(sql, (user_playbook_id,))
-        return _row_to_user_playbook(row) if row else None
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_user_playbooks_by_ids_any_user(
-        self,
-        user_playbook_ids: list[int],
-        status_filter: list[Status | None] | None = None,
-    ) -> list[UserPlaybook]:
-        if not user_playbook_ids:
-            return []
-        ph = ",".join("?" for _ in user_playbook_ids)
-        sql = f"SELECT * FROM user_playbooks WHERE user_playbook_id IN ({ph})"  # noqa: S608
-        params: list[Any] = list(user_playbook_ids)
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            sql += f" AND {frag}"
-            params.extend(sparams)
-        rows = self._fetchall(sql, params)
-        by_id = {
-            _row_to_user_playbook(row).user_playbook_id: _row_to_user_playbook(row)
-            for row in rows
-        }
-        return [by_id[upid] for upid in user_playbook_ids if upid in by_id]
-
-    # ------------------------------------------------------------------
-    # Agent Playbook methods
-    # ------------------------------------------------------------------
-
-    def _index_agent_playbook_fts_vec(self, ap: AgentPlaybook) -> None:
-        """Update the FTS and vector indexes for a single agent playbook row.
-
-        Must be called AFTER the row's transaction has been committed.  The FTS
-        and vec helpers self-commit, so they must never be interleaved inside a
-        transaction that still has pending mutations.
-
-        Args:
-            ap (AgentPlaybook): The already-saved playbook (``agent_playbook_id``
-                must be set).
-        """
-        fts_parts = [ap.trigger or "", ap.content or ""]
-        if ap.expanded_terms:
-            fts_parts.append(ap.expanded_terms)
-        self._fts_upsert(
-            "agent_playbooks_fts",
-            ap.agent_playbook_id,
-            search_text=" ".join(p for p in fts_parts if p) or "",
-        )
-        if ap.embedding:
-            self._vec_upsert("agent_playbooks_vec", ap.agent_playbook_id, ap.embedding)
-
-    def _insert_agent_playbook_row(
-        self, conn: "sqlite3.Connection", ap: AgentPlaybook, created_at_iso: str
-    ) -> "sqlite3.Cursor":
-        """Execute the agent_playbooks INSERT and populate ``ap.agent_playbook_id``.
-
-        Runs the INSERT inside the caller's connection context; does NOT commit.
-        The caller is responsible for committing (or rolling back) the transaction.
-
-        Args:
-            conn: The open SQLite connection to execute against.
-            ap: The playbook to insert; ``agent_playbook_id`` is set on return.
-            created_at_iso: ISO-8601 timestamp string for ``created_at``.
-
-        Returns:
-            sqlite3.Cursor: The cursor from the INSERT (``lastrowid`` is the new PK).
-        """
-        cur = conn.execute(
-            """INSERT INTO agent_playbooks
-               (playbook_name, created_at, agent_version, content,
-                trigger, rationale, blocking_issue,
-                playbook_status, playbook_metadata, embedding,
-                expanded_terms, tags, status,
-                merged_into, superseded_by)
-               VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
-            (
-                ap.playbook_name,
-                created_at_iso,
-                ap.agent_version,
-                ap.content,
-                ap.trigger,
-                ap.rationale,
-                json.dumps(ap.blocking_issue.model_dump())
-                if ap.blocking_issue
-                else None,
-                ap.playbook_status.value
-                if isinstance(ap.playbook_status, PlaybookStatus)
-                else ap.playbook_status,
-                ap.playbook_metadata,
-                _json_dumps(ap.embedding),
-                ap.expanded_terms,
-                _json_dumps(ap.tags),
-                ap.status.value if ap.status else None,
-                ap.merged_into,
-                ap.superseded_by,
-            ),
-        )
-        ap.agent_playbook_id = cur.lastrowid or 0
-        return cur
-
-    @SQLiteStorageBase.handle_exceptions
-    def save_agent_playbooks(
-        self, agent_playbooks: list[AgentPlaybook]
-    ) -> list[AgentPlaybook]:
-        saved: list[AgentPlaybook] = []
-        for ap in agent_playbooks:
-            embedding_text = ap.trigger or ap.content
-            if self._should_expand_documents():
-                with ThreadPoolExecutor(max_workers=2) as executor:
-                    emb_future = executor.submit(self._get_embedding, embedding_text)
-                    exp_future = executor.submit(self._expand_document, embedding_text)
-                    ap.embedding = emb_future.result(timeout=15)
-                    ap.expanded_terms = exp_future.result(timeout=15)
-            else:
-                ap.embedding = self._get_embedding(embedding_text)
-
-            created_at_iso = _epoch_to_iso(ap.created_at)
-            with self._lock:
-                self._insert_agent_playbook_row(self.conn, ap, created_at_iso)
-                self.conn.commit()
-
-            self._index_agent_playbook_fts_vec(ap)
-            saved.append(ap)
-        return saved
-
-    @SQLiteStorageBase.handle_exceptions
-    def save_agent_playbook_with_aggregate_event(
-        self,
-        agent_playbook: AgentPlaybook,
-        *,
-        source_ids: list[str],
-        request_id: str,
-        run_mode: str,
-    ) -> AgentPlaybook:
-        """Persist an agent playbook AND its ``op=aggregate`` lineage event atomically.
-
-        The INSERT and the event are committed in a single transaction — if either
-        fails, both roll back.  The event is the sole record of the run->playbook
-        membership for reconstruction, so atomicity is critical.
-
-        Args:
-            agent_playbook (AgentPlaybook): The playbook to persist.
-            source_ids (list[str]): IDs of the source entities that produced this playbook.
-            request_id (str): The aggregation run ID.
-            run_mode (str): Aggregation run mode (e.g. ``full_archive`` or ``incremental``).
-
-        Returns:
-            AgentPlaybook: The saved playbook with ``agent_playbook_id`` populated.
-
-        Raises:
-            ValueError: If ``request_id`` is empty (would produce an unreconstructable event).
-        """
-        if not request_id or not request_id.strip():
-            raise ValueError(
-                "save_agent_playbook_with_aggregate_event requires a non-empty request_id"
-            )
-        ap = agent_playbook
-        embedding_text = ap.trigger or ap.content
-        if self._should_expand_documents():
-            with ThreadPoolExecutor(max_workers=2) as executor:
-                emb_future = executor.submit(self._get_embedding, embedding_text)
-                exp_future = executor.submit(self._expand_document, embedding_text)
-                ap.embedding = emb_future.result(timeout=15)
-                ap.expanded_terms = exp_future.result(timeout=15)
-        else:
-            ap.embedding = self._get_embedding(embedding_text)
-
-        created_at_iso = _epoch_to_iso(ap.created_at)
-        with self._lock:
-            try:
-                self._insert_agent_playbook_row(self.conn, ap, created_at_iso)
-                _append_event_stmt(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(ap.agent_playbook_id),
-                    op="aggregate",
-                    prov="wasDerivedFrom",
-                    source_ids=source_ids,
-                    actor="aggregator",
-                    request_id=request_id,
-                    reason=f"{AGGREGATE_REASON_PREFIX}{run_mode}",
-                )
-                self.conn.commit()
-            except Exception:
-                self.conn.rollback()
-                raise
-
-        # FTS/vec indexing AFTER commit — these helpers self-commit and must
-        # not be interleaved inside the atomic transaction above.
-        # Index failure does NOT invalidate the committed row+event; the index
-        # is reconstructable from the authoritative row.
-        try:
-            self._index_agent_playbook_fts_vec(ap)
-        except Exception:
-            logger.exception(
-                "FTS/vec indexing failed for agent_playbook %s (row committed, index skipped)",
-                ap.agent_playbook_id,
-            )
-        return ap
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_agent_playbooks(
-        self,
-        limit: int = 100,
-        playbook_name: str | None = None,
-        agent_version: str | None = None,
-        status_filter: list[Status | None] | None = None,
-        playbook_status_filter: list[PlaybookStatus] | None = None,
-        tags: list[str] | None = None,
-    ) -> list[AgentPlaybook]:
-        sql = "SELECT * FROM agent_playbooks WHERE 1=1"
-        params: list[Any] = []
-
-        if playbook_name:
-            sql += " AND playbook_name = ?"
-            params.append(playbook_name)
-
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            sql += f" AND {frag}"
-            params.extend(sparams)
-        else:
-            sql += " AND status IS NULL"
-
-        if playbook_status_filter:
-            ph = ",".join("?" for _ in playbook_status_filter)
-            sql += f" AND playbook_status IN ({ph})"
-            params.extend(ps.value for ps in playbook_status_filter)
-        tag_frag, tag_params = _build_tags_sql("agent_playbooks", tags)
-        if tag_frag:
-            sql += f" AND {tag_frag}"
-            params.extend(tag_params)
-
-        sql += " ORDER BY created_at DESC LIMIT ?"
-        params.append(limit)
-        rows = self._fetchall(sql, params)
-        return [_row_to_agent_playbook(r) for r in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_agent_playbook_by_id(
-        self, agent_playbook_id: int, *, include_tombstones: bool = False
-    ) -> AgentPlaybook | None:
-        sql = "SELECT * FROM agent_playbooks WHERE agent_playbook_id = ?"
-        if not include_tombstones:
-            sql += " AND (status IS NULL OR status NOT IN (?, ?))"
-            row = self._fetchone(sql, (agent_playbook_id, *_TOMBSTONE_STATUS_VALUES))
-        else:
-            row = self._fetchone(sql, (agent_playbook_id,))
-        return _row_to_agent_playbook(row) if row else None
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_agent_playbooks(self) -> None:
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            ids = [
-                r["agent_playbook_id"]
-                for r in self.conn.execute(
-                    "SELECT agent_playbook_id FROM agent_playbooks"
-                ).fetchall()
-            ]
-            self.conn.execute("DELETE FROM agent_playbooks")
-            for apid in ids:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(apid),
-                    request_id=batch_request_id,
-                )
-            self.conn.commit()
-        self._delete_playbook_search_rows("agent", ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_agent_playbook(self, agent_playbook_id: int) -> None:
-        with self._lock:
-            cur = self.conn.execute(
-                "DELETE FROM agent_playbooks WHERE agent_playbook_id = ?",
-                (agent_playbook_id,),
-            )
-            if cur.rowcount > 0:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(agent_playbook_id),
-                    request_id=uuid.uuid4().hex,
-                )
-            self._delete_playbook_search_rows(
-                "agent", [agent_playbook_id], commit=False
-            )
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_agent_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None = None
-    ) -> None:
-        sql = "SELECT agent_playbook_id FROM agent_playbooks WHERE playbook_name = ?"
-        params: list[Any] = [playbook_name]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            ids = [
-                r["agent_playbook_id"]
-                for r in self.conn.execute(sql, params).fetchall()
-            ]
-            if not ids:
-                return
-            ph = ",".join("?" for _ in ids)
-            self.conn.execute(
-                f"DELETE FROM agent_playbooks WHERE agent_playbook_id IN ({ph})", ids
-            )
-            for apid in ids:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(apid),
-                    request_id=batch_request_id,
-                )
-            self.conn.commit()
-        self._delete_playbook_search_rows("agent", ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_agent_playbooks_by_ids(
-        self, agent_playbook_ids: list[int], *, emit_hard_delete: bool = True
-    ) -> None:
-        if not agent_playbook_ids:
-            return
-        ph = ",".join("?" for _ in agent_playbook_ids)
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            existing = [
-                r["agent_playbook_id"]
-                for r in self.conn.execute(
-                    f"SELECT agent_playbook_id FROM agent_playbooks WHERE agent_playbook_id IN ({ph})",
-                    agent_playbook_ids,
-                ).fetchall()
-            ]
-            self.conn.execute(
-                f"DELETE FROM agent_playbooks WHERE agent_playbook_id IN ({ph})",
-                agent_playbook_ids,
-            )
-            if emit_hard_delete:
-                for apid in existing:
-                    _emit_hard_delete_playbook(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_type="agent_playbook",
-                        entity_id=str(apid),
-                        request_id=batch_request_id,
-                        actor="system",
-                    )
-            self.conn.commit()
-        self._delete_playbook_search_rows("agent", agent_playbook_ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_agent_playbook_status(
-        self, agent_playbook_id: int, playbook_status: PlaybookStatus
-    ) -> None:
-        """Update an agent playbook's status and emit a status_change lineage event.
-
-        Each call generates a fresh request_id so every status change is recorded as
-        a distinct audit event (not collapsed by the idempotency key).
-        """
-        with self._lock:
-            row = self.conn.execute(
-                "SELECT playbook_status FROM agent_playbooks WHERE agent_playbook_id = ?",
-                (agent_playbook_id,),
-            ).fetchone()
-            if not row:
-                raise ValueError(
-                    f"Agent playbook with ID {agent_playbook_id} not found"
-                )
-            prior_playbook_status = row["playbook_status"]
-            old_status = prior_playbook_status or "None"
-            cur = self.conn.execute(
-                "UPDATE agent_playbooks SET playbook_status = ? WHERE agent_playbook_id = ?",
-                (playbook_status.value, agent_playbook_id),
-            )
-            if cur.rowcount > 0:
-                _append_event_stmt(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(agent_playbook_id),
-                    op="status_change",
-                    prov="wasInvalidatedBy",
-                    source_ids=[],
-                    actor="api",
-                    request_id=uuid.uuid4().hex,
-                    reason=f"{old_status}->{playbook_status.value}",
-                    from_status=prior_playbook_status,
-                    to_status=playbook_status.value,
-                    status_namespace="playbook_status",
-                )
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_agent_playbook(
-        self,
-        agent_playbook_id: int,
-        playbook_name: str | None = None,
-        content: str | None = None,
-        trigger: str | None = None,
-        rationale: str | None = None,
-        blocking_issue: BlockingIssue | None = None,
-        playbook_status: PlaybookStatus | None = None,
-        tags: list[str] | None = None,
-    ) -> None:
-        updates: list[str] = []
-        params: list[Any] = []
-        if playbook_name is not None:
-            updates.append("playbook_name = ?")
-            params.append(playbook_name)
-        if content is not None:
-            updates.append("content = ?")
-            params.append(content)
-        if trigger is not None:
-            updates.append("trigger = ?")
-            params.append(trigger)
-        if rationale is not None:
-            updates.append("rationale = ?")
-            params.append(rationale)
-        if blocking_issue is not None:
-            updates.append("blocking_issue = ?")
-            params.append(json.dumps(blocking_issue.model_dump()))
-        if playbook_status is not None:
-            updates.append("playbook_status = ?")
-            params.append(playbook_status.value)
-        if tags is not None:
-            updates.append("tags = ?")
-            params.append(_json_dumps(tags))
-        if updates:
-            params.append(agent_playbook_id)
-            op = "revise" if content is not None else "status_change"
-            prov = "wasRevisionOf" if op == "revise" else "wasInvalidatedBy"
-            with self._lock:
-                prior_row = self.conn.execute(
-                    "SELECT playbook_status FROM agent_playbooks WHERE agent_playbook_id = ?",
-                    (agent_playbook_id,),
-                ).fetchone()
-                if not prior_row:
-                    raise ValueError(
-                        f"Agent playbook with ID {agent_playbook_id} not found"
-                    )
-                prior_playbook_status = prior_row["playbook_status"]
-                cur = self.conn.execute(
-                    f"UPDATE agent_playbooks SET {', '.join(updates)} WHERE agent_playbook_id = ?",
-                    tuple(params),
-                )
-                if cur.rowcount > 0:
-                    # Populate structured status fields only when playbook_status is
-                    # among the updated fields and the op is status_change (not revise).
-                    if op == "status_change" and playbook_status is not None:
-                        from_status = prior_playbook_status
-                        to_status = playbook_status.value
-                        status_namespace: str | None = "playbook_status"
-                    else:
-                        from_status = None
-                        to_status = None
-                        status_namespace = None
-                    _append_event_stmt(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_type="agent_playbook",
-                        entity_id=str(agent_playbook_id),
-                        op=op,
-                        prov=prov,
-                        source_ids=[],
-                        actor="api",
-                        request_id=uuid.uuid4().hex,
-                        reason="in-place update",
-                        from_status=from_status,
-                        to_status=to_status,
-                        status_namespace=status_namespace,
-                    )
-                self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_user_playbook(
-        self,
-        user_playbook_id: int,
-        playbook_name: str | None = None,
-        content: str | None = None,
-        trigger: str | None = None,
-        rationale: str | None = None,
-        blocking_issue: BlockingIssue | None = None,
-        tags: list[str] | None = None,
-    ) -> None:
-        updates: list[str] = []
-        params: list[Any] = []
-        if playbook_name is not None:
-            updates.append("playbook_name = ?")
-            params.append(playbook_name)
-        if content is not None:
-            updates.append("content = ?")
-            params.append(content)
-        if trigger is not None:
-            updates.append("trigger = ?")
-            params.append(trigger)
-        if rationale is not None:
-            updates.append("rationale = ?")
-            params.append(rationale)
-        if blocking_issue is not None:
-            updates.append("blocking_issue = ?")
-            params.append(json.dumps(blocking_issue.model_dump()))
-        if tags is not None:
-            updates.append("tags = ?")
-            params.append(_json_dumps(tags))
-        if updates:
-            params.append(user_playbook_id)
-            semantic_change = any(
-                value is not None for value in (content, trigger, rationale)
-            )
-            op = "revise" if semantic_change else "status_change"
-            prov = "wasRevisionOf" if op == "revise" else "wasInvalidatedBy"
-            with self._lock:
-                cur = self.conn.execute(
-                    f"UPDATE user_playbooks SET {', '.join(updates)} WHERE user_playbook_id = ?",
-                    tuple(params),
-                )
-                if cur.rowcount > 0:
-                    _append_event_stmt(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_type="user_playbook",
-                        entity_id=str(user_playbook_id),
-                        op=op,
-                        prov=prov,
-                        source_ids=[],
-                        actor="api",
-                        request_id=uuid.uuid4().hex,
-                        reason="in-place update",
-                        from_status=None,
-                        to_status=None,
-                        status_namespace=None,
-                    )
-                self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def supersede_user_playbooks_by_ids(
-        self, user_playbook_ids: list[int], request_id: str
-    ) -> int:
-        """Soft-delete user playbooks by setting status to SUPERSEDED.
-
-        Preserves the row content for strict point-in-time attribution reads.
-        Eligible rows are any non-tombstoned status (CURRENT / PENDING /
-        ARCHIVED). Atomic: all updates and lineage events commit together.
-        """
-        if not user_playbook_ids:
-            return 0
-        if not request_id:
-            raise ValueError("request_id must be non-empty for supersede")
-        now_ts = _epoch_now()
-        updated = 0
-        with self._lock:
-            for upid in user_playbook_ids:
-                row = self.conn.execute(
-                    "SELECT status FROM user_playbooks WHERE user_playbook_id = ?",
-                    (upid,),
-                ).fetchone()
-                if row is None:
-                    continue
-                old_status = row["status"]
-                cur = self.conn.execute(
-                    "UPDATE user_playbooks SET status = ?, retired_at = ?"
-                    " WHERE user_playbook_id = ?"
-                    " AND (status IS NULL OR status NOT IN (?, ?))",
-                    (
-                        Status.SUPERSEDED.value,
-                        now_ts,
-                        upid,
-                        *_TOMBSTONE_STATUS_VALUES,
-                    ),
-                )
-                if cur.rowcount > 0:
-                    _emit_supersede_user_playbook(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_id=str(upid),
-                        old_status=old_status,
-                        request_id=request_id,
-                    )
-                    updated += 1
-            self.conn.commit()
-        return updated
-
-    @SQLiteStorageBase.handle_exceptions
-    def archive_agent_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None = None
-    ) -> None:
-        where = (
-            "playbook_name = ? AND playbook_status != ?"
-            " AND (status IS NULL OR status != 'archived')"
-        )
-        params: list[Any] = [playbook_name, PlaybookStatus.APPROVED.value]
-        if agent_version is not None:
-            where += " AND agent_version = ?"
-            params.append(agent_version)
-        now_ts = _epoch_now()
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            affected = self.conn.execute(
-                f"SELECT agent_playbook_id, status FROM agent_playbooks WHERE {where}",
-                params,
-            ).fetchall()
-            self.conn.execute(
-                f"UPDATE agent_playbooks SET status = 'archived', retired_at = ? WHERE {where}",
-                [now_ts, *params],
-            )
-            for row in affected:
-                prior = row["status"] or "None"
-                _append_event_stmt(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(row["agent_playbook_id"]),
-                    op="status_change",
-                    prov="wasInvalidatedBy",
-                    source_ids=[],
-                    actor="api",
-                    request_id=batch_request_id,
-                    reason=f"{prior}->archived",
-                    from_status=row["status"],
-                    to_status="archived",
-                    status_namespace="lifecycle_status",
-                )
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def archive_agent_playbooks_by_ids(self, agent_playbook_ids: list[int]) -> None:
-        if not agent_playbook_ids:
-            return
-        ph = ",".join("?" for _ in agent_playbook_ids)
-        now_ts = _epoch_now()
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            affected = self.conn.execute(
-                f"SELECT agent_playbook_id, status FROM agent_playbooks"
-                f" WHERE agent_playbook_id IN ({ph}) AND playbook_status != ?"
-                f" AND (status IS NULL OR status != 'archived')",
-                [*agent_playbook_ids, PlaybookStatus.APPROVED.value],
-            ).fetchall()
-            self.conn.execute(
-                f"UPDATE agent_playbooks SET status = 'archived', retired_at = ?"
-                f" WHERE agent_playbook_id IN ({ph}) AND playbook_status != ?"
-                f" AND (status IS NULL OR status != 'archived')",
-                [now_ts, *agent_playbook_ids, PlaybookStatus.APPROVED.value],
-            )
-            for row in affected:
-                prior = row["status"] or "None"
-                _append_event_stmt(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(row["agent_playbook_id"]),
-                    op="status_change",
-                    prov="wasInvalidatedBy",
-                    source_ids=[],
-                    actor="api",
-                    request_id=batch_request_id,
-                    reason=f"{prior}->archived",
-                    from_status=row["status"],
-                    to_status="archived",
-                    status_namespace="lifecycle_status",
-                )
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def supersede_agent_playbooks_by_ids(
-        self, agent_playbook_ids: list[int], request_id: str
-    ) -> int:
-        """Soft-delete agent playbooks by setting status to SUPERSEDED, emitting set-based lineage.
-
-        For each eligible id (not APPROVED, not already tombstoned), updates status to
-        SUPERSEDED and emits one ``status_change`` event under the shared ``request_id``.
-        Atomic: one ``conn.commit()`` at the end, guarded on rowcount per id.
-        FTS/vec rows are NOT removed — reads exclude tombstones by status filter.
-
-        Args:
-            agent_playbook_ids (list[int]): Agent playbook ids to supersede.
-            request_id (str): Shared request id for all emitted lineage events.
-
-        Returns:
-            int: Number of agent playbooks actually updated.
-        """
-        if not agent_playbook_ids:
-            return 0
-        if not request_id:
-            raise ValueError("request_id must be non-empty for supersede")
-        now_ts = _epoch_now()
-        updated = 0
-        with self._lock:
-            for apid in agent_playbook_ids:
-                row = self.conn.execute(
-                    "SELECT status FROM agent_playbooks WHERE agent_playbook_id = ?",
-                    (apid,),
-                ).fetchone()
-                if row is None:
-                    continue
-                old_status = row["status"]
-                # NOTE (M3): The model supersede_profiles_by_ids adds an eligible-check
-                # `if old_status_val not in eligible: continue` before the UPDATE. For
-                # agent_playbooks the ineligible condition spans two columns (status in
-                # _TOMBSTONE_STATUS_VALUES OR playbook_status == APPROVED), so aligning
-                # would require adding playbook_status to the SELECT. The UPDATE WHERE
-                # clause already excludes those rows atomically; the extra continue here
-                # would be a no-op and not worth the added complexity.
-                cur = self.conn.execute(
-                    "UPDATE agent_playbooks SET status = ?, retired_at = ?"
-                    " WHERE agent_playbook_id = ? AND playbook_status != ?"
-                    " AND (status IS NULL OR status NOT IN (?, ?))",
-                    (
-                        Status.SUPERSEDED.value,
-                        now_ts,
-                        apid,
-                        PlaybookStatus.APPROVED.value,
-                        *_TOMBSTONE_STATUS_VALUES,
-                    ),
-                )
-                if cur.rowcount > 0:
-                    _emit_supersede_playbook(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_id=str(apid),
-                        old_status=old_status,
-                        request_id=request_id,
-                    )
-                    updated += 1
-            self.conn.commit()
-        return updated
-
-    @SQLiteStorageBase.handle_exceptions
-    def supersede_agent_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None, request_id: str
-    ) -> int:
-        """Soft-delete archived agent playbooks by name/version via SUPERSEDED status.
-
-        Mirrors ``delete_archived_agent_playbooks_by_playbook_name`` but converts
-        the hard-delete to a soft-supersede with status_change lineage events.
-        Atomic: one ``conn.commit()`` at the end.
-        FTS/vec rows are NOT removed.
-
-        Args:
-            playbook_name (str): Playbook name to supersede.
-            agent_version (str | None): Agent version filter. None matches all versions.
-            request_id (str): Shared request id for all emitted lineage events.
-
-        Returns:
-            int: Number of agent playbooks actually updated.
-        """
-        if not request_id:
-            raise ValueError("request_id must be non-empty for supersede")
-        sql = (
-            "SELECT agent_playbook_id, status FROM agent_playbooks"
-            " WHERE playbook_name = ? AND status = 'archived'"
-        )
-        params: list[Any] = [playbook_name]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        updated = 0
-        with self._lock:
-            rows = self.conn.execute(sql, params).fetchall()
-            if not rows:
-                return 0
-            now_ts = _epoch_now()
-            for row in rows:
-                apid = row["agent_playbook_id"]
-                old_status = row["status"]
-                cur = self.conn.execute(
-                    "UPDATE agent_playbooks SET status = ?, retired_at = ?"
-                    " WHERE agent_playbook_id = ? AND playbook_status != ?"
-                    " AND status = 'archived'",
-                    (
-                        Status.SUPERSEDED.value,
-                        now_ts,
-                        apid,
-                        PlaybookStatus.APPROVED.value,
-                    ),
-                )
-                if cur.rowcount > 0:
-                    _emit_supersede_playbook(
-                        self.conn,
-                        org_id=self.org_id,
-                        entity_id=str(apid),
-                        old_status=old_status,
-                        request_id=request_id,
-                    )
-                    updated += 1
-            self.conn.commit()
-        return updated
-
-    @SQLiteStorageBase.handle_exceptions
-    def restore_archived_agent_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None = None
-    ) -> None:
-        sql = "UPDATE agent_playbooks SET status = NULL, retired_at = NULL WHERE playbook_name = ? AND status = 'archived'"
-        params: list[Any] = [playbook_name]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        self._execute(sql, params)
-
-    @SQLiteStorageBase.handle_exceptions
-    def restore_archived_agent_playbooks_by_ids(
-        self, agent_playbook_ids: list[int]
-    ) -> None:
-        if not agent_playbook_ids:
-            return
-        ph = ",".join("?" for _ in agent_playbook_ids)
-        self._execute(
-            f"UPDATE agent_playbooks SET status = NULL, retired_at = NULL WHERE agent_playbook_id IN ({ph}) AND status = 'archived'",
-            agent_playbook_ids,
-        )
-
-    # ------------------------------------------------------------------
-    # Playbook optimizer methods
-    # ------------------------------------------------------------------
-
-    @SQLiteStorageBase.handle_exceptions
-    def set_source_user_playbook_ids_for_agent_playbook(
-        self, agent_playbook_id: int, user_playbook_ids: list[int]
-    ) -> None:
-        self.set_source_windows_for_agent_playbook(
-            agent_playbook_id,
-            [
-                AgentPlaybookSourceWindow(
-                    user_playbook_id=upid, source_interaction_ids=[]
-                )
-                for upid in user_playbook_ids
-            ],
-        )
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_source_user_playbook_ids_for_agent_playbook(
-        self, agent_playbook_id: int
-    ) -> list[int]:
-        return [
-            window.user_playbook_id
-            for window in self.get_source_windows_for_agent_playbook(agent_playbook_id)
-        ]
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_source_user_playbook_ids_for_agent_playbooks(
-        self, agent_playbook_ids: Sequence[int]
-    ) -> dict[int, list[int]]:
-        if not agent_playbook_ids:
-            return {}
-        unique_ids = list(dict.fromkeys(int(apid) for apid in agent_playbook_ids))
-        ph = ",".join("?" for _ in unique_ids)
-        rows = self._fetchall(
-            f"""SELECT agent_playbook_id, user_playbook_id
-                FROM agent_playbook_source_user_playbooks
-                WHERE agent_playbook_id IN ({ph})
-                ORDER BY agent_playbook_id ASC, user_playbook_id ASC""",
-            unique_ids,
-        )
-        by_agent_id: dict[int, list[int]] = {apid: [] for apid in unique_ids}
-        seen_by_agent_id: dict[int, set[int]] = {apid: set() for apid in unique_ids}
-        for row in rows:
-            agent_playbook_id = int(row["agent_playbook_id"])
-            user_playbook_id = int(row["user_playbook_id"])
-            seen = seen_by_agent_id.setdefault(agent_playbook_id, set())
-            if user_playbook_id not in seen:
-                by_agent_id.setdefault(agent_playbook_id, []).append(user_playbook_id)
-                seen.add(user_playbook_id)
-        return by_agent_id
-
-    @SQLiteStorageBase.handle_exceptions
-    def set_source_windows_for_agent_playbook(
-        self,
-        agent_playbook_id: int,
-        source_windows: list[AgentPlaybookSourceWindow],
-    ) -> None:
-        by_id: dict[int, list[int]] = {}
-        for window in source_windows:
-            ids = by_id.setdefault(window.user_playbook_id, [])
-            seen = set(ids)
-            for source_id in window.source_interaction_ids:
-                if source_id not in seen:
-                    ids.append(source_id)
-                    seen.add(source_id)
-        with self._lock:
-            self.conn.execute(
-                "DELETE FROM agent_playbook_source_user_playbooks WHERE agent_playbook_id = ?",
-                (agent_playbook_id,),
-            )
-            self.conn.executemany(
-                """INSERT OR IGNORE INTO agent_playbook_source_user_playbooks
-                   (agent_playbook_id, user_playbook_id, source_interaction_ids)
-                   VALUES (?, ?, ?)""",
-                [
-                    (
-                        agent_playbook_id,
-                        upid,
-                        _json_dumps(source_interaction_ids) or "[]",
-                    )
-                    for upid, source_interaction_ids in by_id.items()
-                ],
-            )
-            self.conn.commit()
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_source_windows_for_agent_playbook(
-        self, agent_playbook_id: int
-    ) -> list[AgentPlaybookSourceWindow]:
-        rows = self._fetchall(
-            """SELECT user_playbook_id, source_interaction_ids
-               FROM agent_playbook_source_user_playbooks
-               WHERE agent_playbook_id = ?
-               ORDER BY user_playbook_id ASC""",
-            (agent_playbook_id,),
-        )
-        return [
-            AgentPlaybookSourceWindow(
-                user_playbook_id=int(row["user_playbook_id"]),
-                source_interaction_ids=_json_loads(row["source_interaction_ids"]) or [],
-            )
-            for row in rows
-        ]
-
-    @SQLiteStorageBase.handle_exceptions
-    def create_playbook_optimization_job(
-        self, job: PlaybookOptimizationJob
-    ) -> PlaybookOptimizationJob:
-        with self._lock:
-            cur = self.conn.execute(
-                """INSERT INTO playbook_optimization_jobs
-                   (target_kind, target_id, status, best_candidate_id,
-                    successor_target_id, decision_reason, metadata_json,
-                    created_at, updated_at)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-                (
-                    job.target_kind,
-                    job.target_id,
-                    job.status,
-                    job.best_candidate_id,
-                    job.successor_target_id,
-                    job.decision_reason,
-                    job.metadata_json,
-                    job.created_at,
-                    job.updated_at,
-                ),
-            )
-            job.job_id = cur.lastrowid or 0
-            self.conn.commit()
-        return job
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_playbook_optimization_job(
-        self,
-        job_id: int,
-        *,
-        status: str | None = None,
-        best_candidate_id: int | None = None,
-        successor_target_id: int | None = None,
-        decision_reason: str | None = None,
-        metadata_json: str | None = None,
-    ) -> None:
-        updates: list[str] = ["updated_at = strftime('%s','now')"]
-        params: list[Any] = []
-        if status is not None:
-            updates.append("status = ?")
-            params.append(status)
-        if best_candidate_id is not None:
-            updates.append("best_candidate_id = ?")
-            params.append(best_candidate_id)
-        if successor_target_id is not None:
-            updates.append("successor_target_id = ?")
-            params.append(successor_target_id)
-        if decision_reason is not None:
-            updates.append("decision_reason = ?")
-            params.append(decision_reason)
-        if metadata_json is not None:
-            updates.append("metadata_json = ?")
-            params.append(metadata_json)
-        params.append(job_id)
-        self._execute(
-            f"UPDATE playbook_optimization_jobs SET {', '.join(updates)} WHERE job_id = ?",  # noqa: S608
-            tuple(params),
-        )
-
-    @SQLiteStorageBase.handle_exceptions
-    def insert_playbook_optimization_candidate(
-        self, candidate: PlaybookOptimizationCandidate
-    ) -> PlaybookOptimizationCandidate:
-        with self._lock:
-            cur = self.conn.execute(
-                """INSERT INTO playbook_optimization_candidates
-                   (job_id, candidate_index, content, parent_candidate_ids,
-                    aggregate_score, is_winner, metadata_json, created_at)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
-                (
-                    candidate.job_id,
-                    candidate.candidate_index,
-                    candidate.content,
-                    _json_dumps(candidate.parent_candidate_ids) or "[]",
-                    candidate.aggregate_score,
-                    1 if candidate.is_winner else 0,
-                    candidate.metadata_json,
-                    candidate.created_at,
-                ),
-            )
-            candidate.candidate_id = cur.lastrowid or 0
-            self.conn.commit()
-        return candidate
-
-    @SQLiteStorageBase.handle_exceptions
-    def list_playbook_optimization_candidates(
-        self, job_id: int
-    ) -> list[PlaybookOptimizationCandidate]:
-        rows = self._fetchall(
-            "SELECT * FROM playbook_optimization_candidates WHERE job_id = ? ORDER BY candidate_id ASC",
-            (job_id,),
-        )
-        return [_row_to_playbook_optimization_candidate(row) for row in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def update_playbook_optimization_candidate(
-        self,
-        candidate_id: int,
-        *,
-        aggregate_score: float | None = None,
-        is_winner: bool | None = None,
-    ) -> None:
-        updates: list[str] = []
-        params: list[Any] = []
-        if aggregate_score is not None:
-            updates.append("aggregate_score = ?")
-            params.append(aggregate_score)
-        if is_winner is not None:
-            updates.append("is_winner = ?")
-            params.append(1 if is_winner else 0)
-        if not updates:
-            return
-        params.append(candidate_id)
-        self._execute(
-            f"UPDATE playbook_optimization_candidates SET {', '.join(updates)} WHERE candidate_id = ?",  # noqa: S608
-            tuple(params),
-        )
-
-    @SQLiteStorageBase.handle_exceptions
-    def insert_playbook_optimization_evaluation(
-        self, evaluation: PlaybookOptimizationEvaluation
-    ) -> PlaybookOptimizationEvaluation:
-        with self._lock:
-            cur = self.conn.execute(
-                """INSERT INTO playbook_optimization_evaluations
-                   (job_id, candidate_id, target_kind, target_id,
-                    scenario_user_playbook_id, source_interaction_ids, score,
-                    verdict, likert, rationale, asi_json, incumbent_rollout_json,
-                    candidate_rollout_json, created_at)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-                (
-                    evaluation.job_id,
-                    evaluation.candidate_id,
-                    evaluation.target_kind,
-                    evaluation.target_id,
-                    evaluation.scenario_user_playbook_id,
-                    _json_dumps(evaluation.source_interaction_ids) or "[]",
-                    evaluation.score,
-                    evaluation.verdict,
-                    evaluation.likert,
-                    evaluation.rationale,
-                    evaluation.asi_json,
-                    evaluation.incumbent_rollout_json,
-                    evaluation.candidate_rollout_json,
-                    evaluation.created_at,
-                ),
-            )
-            evaluation.evaluation_id = cur.lastrowid or 0
-            self.conn.commit()
-        return evaluation
-
-    @SQLiteStorageBase.handle_exceptions
-    def list_playbook_optimization_evaluations(
-        self, job_id: int
-    ) -> list[PlaybookOptimizationEvaluation]:
-        rows = self._fetchall(
-            "SELECT * FROM playbook_optimization_evaluations WHERE job_id = ? ORDER BY evaluation_id ASC",
-            (job_id,),
-        )
-        return [_row_to_playbook_optimization_evaluation(row) for row in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def insert_playbook_optimization_event(
-        self, event: PlaybookOptimizationEvent
-    ) -> PlaybookOptimizationEvent:
-        with self._lock:
-            cur = self.conn.execute(
-                """INSERT INTO playbook_optimization_events
-                   (job_id, event_type, payload_json, created_at)
-                   VALUES (?, ?, ?, ?)""",
-                (event.job_id, event.event_type, event.payload_json, event.created_at),
-            )
-            event.event_id = cur.lastrowid or 0
-            self.conn.commit()
-        return event
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_archived_agent_playbooks_by_playbook_name(
-        self, playbook_name: str, agent_version: str | None = None
-    ) -> None:
-        sql = "SELECT agent_playbook_id FROM agent_playbooks WHERE playbook_name = ? AND status = 'archived'"
-        params: list[Any] = [playbook_name]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        batch_request_id = uuid.uuid4().hex
-        with self._lock:
-            ids = [
-                r["agent_playbook_id"]
-                for r in self.conn.execute(sql, params).fetchall()
-            ]
-            if not ids:
-                return
-            ph = ",".join("?" for _ in ids)
-            self.conn.execute(
-                f"DELETE FROM agent_playbooks WHERE agent_playbook_id IN ({ph})", ids
-            )
-            for apid in ids:
-                _emit_hard_delete_playbook(
-                    self.conn,
-                    org_id=self.org_id,
-                    entity_type="agent_playbook",
-                    entity_id=str(apid),
-                    request_id=batch_request_id,
-                )
-            self.conn.commit()
-        self._delete_playbook_search_rows("agent", ids)
-
-    @SQLiteStorageBase.handle_exceptions
-    def search_agent_playbooks(  # noqa: C901
-        self,
-        request: SearchAgentPlaybookRequest,
-        options: SearchOptions | None = None,
-    ) -> list[AgentPlaybook]:
-        query = request.query
-        agent_version = request.agent_version
-        playbook_name = request.playbook_name
-        start_time = int(request.start_time.timestamp()) if request.start_time else None
-        end_time = int(request.end_time.timestamp()) if request.end_time else None
-        status_filter = request.status_filter
-        playbook_status_filter = request.playbook_status_filter
-        match_count = request.top_k or 10
-        query_embedding = options.query_embedding if options else None
-        mode = _effective_search_mode(
-            request.search_mode, query_embedding, request.query
-        )
-        rrf_k = options.rrf_k if options else 60
-        vector_weight = options.vector_weight if options else 1.0
-        fts_weight = options.fts_weight if options else 1.0
-
-        conditions: list[str] = []
-        params: list[Any] = []
-
-        if agent_version:
-            conditions.append("ap.agent_version = ?")
-            params.append(agent_version)
-        if playbook_name:
-            conditions.append("ap.playbook_name = ?")
-            params.append(playbook_name)
-        if start_time:
-            conditions.append("ap.created_at >= ?")
-            params.append(_epoch_to_iso(start_time))
-        if end_time:
-            conditions.append("ap.created_at <= ?")
-            params.append(_epoch_to_iso(end_time))
-        if playbook_status_filter is not None:
-            if isinstance(playbook_status_filter, list):
-                if not playbook_status_filter:
-                    conditions.append("1=0")
-                else:
-                    placeholders = ",".join("?" for _ in playbook_status_filter)
-                    conditions.append(f"ap.playbook_status IN ({placeholders})")
-                    params.extend(s.value for s in playbook_status_filter)
-            else:
-                conditions.append("ap.playbook_status = ?")
-                params.append(playbook_status_filter.value)
-        if status_filter is not None:
-            frag, sparams = _build_status_sql(status_filter)
-            conditions.append(frag)
-            params.extend(sparams)
-        else:
-            # Default: exclude tombstone statuses (MERGED/SUPERSEDED)
-            conditions.append("(ap.status IS NULL OR ap.status NOT IN (?, ?))")
-            params.extend(_TOMBSTONE_STATUS_VALUES)
-        tag_frag, tag_params = _build_tags_sql("ap", request.tags)
-        if tag_frag:
-            conditions.append(tag_frag)
-            params.extend(tag_params)
-
-        where_extra = (" AND " + " AND ".join(conditions)) if conditions else ""
-        overfetch = match_count * 5 if mode != SearchMode.FTS else match_count
-
-        # Pure vector search: fetch all candidates, rank by cosine similarity
-        if mode == SearchMode.VECTOR and query_embedding:
-            base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-            sql = f"""SELECT * FROM agent_playbooks ap
-                      {base_where}
-                      ORDER BY ap.created_at DESC"""
-            rows = self._fetchall(sql, params)
-            rows = _vector_rank_rows(rows, query_embedding, match_count)
-            return [_row_to_agent_playbook(r) for r in rows]
-
-        if query:
-            fts_query = _sanitize_fts_query(query)
-            sql = f"""SELECT ap.* FROM agent_playbooks ap
-                      JOIN agent_playbooks_fts f ON ap.agent_playbook_id = f.rowid
-                      WHERE agent_playbooks_fts MATCH ?{where_extra}
-                      ORDER BY bm25(agent_playbooks_fts, 1.0)
-                      LIMIT ?"""
-            fts_rows = self._fetchall(sql, [fts_query, *params, overfetch])
-
-            if mode == SearchMode.HYBRID and query_embedding:
-                base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-                vec_limit = match_count * 10
-                vec_sql = f"""SELECT * FROM agent_playbooks ap
-                              {base_where}
-                              ORDER BY ap.created_at DESC
-                              LIMIT ?"""
-                vec_candidates = self._fetchall(vec_sql, [*params, vec_limit])
-                vec_rows = _vector_rank_rows(vec_candidates, query_embedding, overfetch)
-                rows = _true_rrf_merge(
-                    fts_rows,
-                    vec_rows,
-                    "agent_playbook_id",
-                    match_count,
-                    rrf_k,
-                    vector_weight,
-                    fts_weight,
-                )
-                return [_row_to_agent_playbook(r) for r in rows]
-            return [_row_to_agent_playbook(r) for r in fts_rows[:match_count]]
-
-        # HYBRID without query text: rank by embedding only
-        if query_embedding:
-            base_where = "WHERE " + " AND ".join(conditions) if conditions else ""
-            sql = f"""SELECT * FROM agent_playbooks ap
-                      {base_where}
-                      ORDER BY ap.created_at DESC"""
-            rows = self._fetchall(sql, params)
-            rows = _vector_rank_rows(rows, query_embedding, match_count)
-            return [_row_to_agent_playbook(r) for r in rows]
-
-        # No query text, no embedding -- recency fallback
-        base_where = "WHERE " + " AND ".join(conditions) if conditions else "WHERE 1=1"
-        sql = f"""SELECT * FROM agent_playbooks ap
-                  {base_where}
-                  ORDER BY ap.created_at DESC LIMIT ?"""
-        params.append(match_count)
-        rows = self._fetchall(sql, params)
-        return [_row_to_agent_playbook(r) for r in rows]
-
-    # ------------------------------------------------------------------
-    # Agent Success Evaluation methods
-    # ------------------------------------------------------------------
-
-    @SQLiteStorageBase.handle_exceptions
-    def save_agent_success_evaluation_results(
-        self, results: list[AgentSuccessEvaluationResult]
-    ) -> None:
-        for result in results:
-            embedding_text = f"{result.failure_type} {result.failure_reason}"
-            if embedding_text.strip():
-                result.embedding = self._get_embedding(embedding_text)
-            else:
-                result.embedding = []
-
-            created_at_iso = _epoch_to_iso(result.created_at)
-            self._execute(
-                """INSERT INTO agent_success_evaluation_result
-                   (user_id, session_id, agent_version, evaluation_name, is_success,
-                    failure_type, failure_reason, regular_vs_shadow,
-                    number_of_correction_per_session, user_turns_to_resolution,
-                    is_escalated, embedding, created_at)
-                   VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)""",
-                (
-                    result.user_id,
-                    result.session_id,
-                    result.agent_version,
-                    result.evaluation_name,
-                    int(result.is_success),
-                    result.failure_type,
-                    result.failure_reason,
-                    result.regular_vs_shadow.value
-                    if result.regular_vs_shadow
-                    else None,
-                    result.number_of_correction_per_session,
-                    result.user_turns_to_resolution,
-                    int(result.is_escalated),
-                    _json_dumps(result.embedding) if result.embedding else None,
-                    created_at_iso,
-                ),
-            )
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_agent_success_evaluation_results(
-        self, limit: int = 100, agent_version: str | None = None
-    ) -> list[AgentSuccessEvaluationResult]:
-        sql = "SELECT * FROM agent_success_evaluation_result"
-        params: list[Any] = []
-        if agent_version is not None:
-            sql += " WHERE agent_version = ?"
-            params.append(agent_version)
-        sql += " ORDER BY created_at DESC LIMIT ?"
-        params.append(limit)
-        rows = self._fetchall(sql, params)
-        return [_row_to_eval_result(r) for r in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_agent_success_evaluation_results_in_window(
-        self,
-        from_ts: int,
-        to_ts: int,
-        agent_version: str | None = None,
-        limit: int | None = None,
-    ) -> list[AgentSuccessEvaluationResult]:
-        sql = """SELECT * FROM agent_success_evaluation_result
-                 WHERE created_at >= ? AND created_at <= ?"""
-        params: list[Any] = [_epoch_to_iso(from_ts), _epoch_to_iso(to_ts)]
-        if agent_version is not None:
-            sql += " AND agent_version = ?"
-            params.append(agent_version)
-        sql += " ORDER BY created_at DESC"
-        if limit is not None:
-            sql += " LIMIT ?"
-            params.append(limit)
-        rows = self._fetchall(sql, params)
-        return [_row_to_eval_result(r) for r in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def get_agent_success_evaluation_result_ids(
-        self,
-        user_id: str,
-        session_id: str,
-        evaluation_name: str,
-        agent_version: str,
-    ) -> list[int]:
-        rows = self._fetchall(
-            """SELECT result_id FROM agent_success_evaluation_result
-               WHERE user_id = ?
-                 AND session_id = ?
-                 AND evaluation_name = ?
-                 AND agent_version = ?
-               ORDER BY created_at DESC""",
-            (user_id, session_id, evaluation_name, agent_version),
-        )
-        return [int(r["result_id"]) for r in rows]
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_all_agent_success_evaluation_results(self) -> None:
-        self._execute("DELETE FROM agent_success_evaluation_result")
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_agent_success_evaluation_results_for_session(
-        self,
-        user_id: str,
-        session_id: str,
-        evaluation_name: str,
-        agent_version: str,
-    ) -> int:
-        """Delete results scoped to (user_id, session_id, evaluation_name, agent_version).
-
-        Args:
-            user_id (str): User whose session results to clear.
-            session_id (str): Session whose results to clear.
-            evaluation_name (str): Which evaluator's results to clear.
-            agent_version (str): Agent version scope.
-
-        Returns:
-            int: Number of rows deleted.
-        """
-        cur = self._execute(
-            """DELETE FROM agent_success_evaluation_result
-               WHERE user_id = ?
-                 AND session_id = ?
-                 AND evaluation_name = ?
-                 AND agent_version = ?""",
-            (user_id, session_id, evaluation_name, agent_version),
-        )
-        return cur.rowcount
-
-    @SQLiteStorageBase.handle_exceptions
-    def delete_agent_success_evaluation_results_by_ids(
-        self, result_ids: list[int]
-    ) -> int:
-        """Delete agent success eval result rows by primary key.
-
-        Args:
-            result_ids (list[int]): Primary-key result_ids to delete. An empty
-                list is a no-op that returns 0.
-
-        Returns:
-            int: Number of rows actually deleted (ignores non-existent ids).
-        """
-        if not result_ids:
-            return 0
-        placeholders = ",".join(["?"] * len(result_ids))
-        cur = self._execute(
-            f"DELETE FROM agent_success_evaluation_result WHERE result_id IN ({placeholders})",
-            list(result_ids),
-        )
-        return cur.rowcount