claude-smart 0.2.49 → 0.2.50

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/profiles/_interaction_store.py

@@ -27,6 +27,16 @@ from .._base import (
 logger = logging.getLogger(__name__)
 
 
+def _embed_text_for_interaction(content: str | None, action_desc: str | None) -> str:
+    """Derive the text embedded for an interaction.
+
+    Kept byte-for-byte identical to the ingest path
+    (``add_user_interactions_bulk`` / ``prepare_interaction_embeddings``) so a
+    backfilled vector matches a freshly-ingested one.
+    """
+    return "\n".join([content or "", action_desc or ""])
+
+
 class InteractionStoreMixin:
     """Mixin providing interaction-store CRUD for SQLite storage."""
 
@@ -72,6 +82,12 @@ class InteractionStoreMixin:
 
     @SQLiteStorageBase.handle_exceptions
     def add_user_interaction(self, user_id: str, interaction: Interaction) -> None:  # noqa: ARG002
+        # NOTE: distinct from the bulk/backfill derivation
+        # (_embed_text_for_interaction). This legacy single-insert path embeds via
+        # the purpose-prefixed _get_embedding ("search_document: ...") and its own
+        # f-string, so it is intentionally NOT routed through the shared helper —
+        # aligning it would silently change stored embedding values (e.g. null ->
+        # literal "None"). The real bulk ingest + backfill share the helper.
         embedding = self._get_embedding(
             f"{interaction.content}\n{interaction.user_action_description}"
         )
@@ -93,8 +109,9 @@ class InteractionStoreMixin:
                            (interaction_id, user_id, content, request_id, created_at,
                             role, user_action, user_action_description,
                             interacted_image_url, image_encoding, shadow_content,
-                            expert_content, tools_used, citations, embedding, governance_subject_ref)
-                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                            expert_content, tools_used, citations, retrieved_learnings,
+                            embedding, governance_subject_ref)
+                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
                         (
                             interaction.interaction_id,
                             interaction.user_id,
@@ -114,6 +131,12 @@ class InteractionStoreMixin:
                             _json_dumps(
                                 [c.model_dump() for c in interaction.citations]
                             ),
+                            _json_dumps(
+                                [
+                                    c.model_dump()
+                                    for c in interaction.retrieved_learnings
+                                ]
+                            ),
                             _json_dumps(interaction.embedding),
                             subject_ref,
                         ),
@@ -125,8 +148,9 @@ class InteractionStoreMixin:
                            (user_id, content, request_id, created_at,
                             role, user_action, user_action_description,
                             interacted_image_url, image_encoding, shadow_content,
-                            expert_content, tools_used, citations, embedding, governance_subject_ref)
-                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                            expert_content, tools_used, citations, retrieved_learnings,
+                            embedding, governance_subject_ref)
+                           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
                         (
                             interaction.user_id,
                             interaction.content,
@@ -145,6 +169,12 @@ class InteractionStoreMixin:
                             _json_dumps(
                                 [c.model_dump() for c in interaction.citations]
                             ),
+                            _json_dumps(
+                                [
+                                    c.model_dump()
+                                    for c in interaction.retrieved_learnings
+                                ]
+                            ),
                             _json_dumps(interaction.embedding),
                             subject_ref,
                         ),
@@ -186,7 +216,7 @@ class InteractionStoreMixin:
             to_embed = [i for i in interactions if not i.embedding]
             if to_embed:
                 texts = [
-                    "\n".join([i.content or "", i.user_action_description or ""])
+                    _embed_text_for_interaction(i.content, i.user_action_description)
                     for i in to_embed
                 ]
                 try:
@@ -218,7 +248,7 @@ class InteractionStoreMixin:
         if not to_embed:
             return
         texts = [
-            "\n".join([i.content or "", i.user_action_description or ""])
+            _embed_text_for_interaction(i.content, i.user_action_description)
             for i in to_embed
         ]
         try:
@@ -235,6 +265,116 @@ class InteractionStoreMixin:
         for interaction, embedding in zip(to_embed, embeddings, strict=False):
             interaction.embedding = embedding
 
+    # ------------------------------------------------------------------
+    # Missing-vector backfill (durability sweep)
+    # ------------------------------------------------------------------
+
+    @SQLiteStorageBase.handle_exceptions
+    def iter_interactions_missing_vectors(self, limit: int) -> list[tuple[int, str]]:
+        """Enumerate interactions whose embedding was never persisted.
+
+        A degraded/failed embedding leaves the ``embedding`` column empty
+        (``'[]'`` or NULL) and writes no ``interactions_vec`` row — equivalent
+        conditions on the write path. Detecting on the ``embedding`` column is
+        both the root-cause signal and portable across backends (the column
+        exists everywhere; ``interactions_vec`` is a SQLite-vec detail).
+
+        Args:
+            limit: Maximum number of interactions to return.
+
+        Returns:
+            list[tuple[int, str]]: ``(interaction_id, embed_text)`` pairs, at
+            most ``limit`` long, ordered by ``interaction_id`` for stable paging.
+        """
+        if limit <= 0:
+            return []
+        rows = self._fetchall(
+            """SELECT interaction_id, content, user_action_description
+               FROM interactions
+               WHERE embedding IS NULL OR embedding = '[]'
+               ORDER BY interaction_id
+               LIMIT ?""",
+            (limit,),
+        )
+        return [
+            (
+                r["interaction_id"],
+                _embed_text_for_interaction(r["content"], r["user_action_description"]),
+            )
+            for r in rows
+        ]
+
+    @SQLiteStorageBase.handle_exceptions
+    def backfill_missing_interaction_vectors(self, limit: int) -> int:
+        """Re-embed and persist vectors for interactions missing them.
+
+        Bounded by ``limit`` and idempotent: once the ``embedding`` column and
+        ``interactions_vec`` row are written, the row no longer matches
+        detection and is skipped next time. Embeds via the same batch call and
+        text derivation the ingest path uses so backfilled vectors match
+        freshly-ingested ones.
+
+        Fail-safe: if the embedder is unavailable the batch call raises
+        ``EmbeddingUnavailableError``; we log a single bounded WARN and return 0,
+        leaving the rows for the next tick rather than crashing the caller or
+        hot-looping a down embedder.
+
+        Args:
+            limit: Maximum number of interactions to re-embed this call.
+
+        Returns:
+            int: Number of interactions whose vector was backfilled.
+        """
+        if limit <= 0:
+            return 0
+        pairs = self.iter_interactions_missing_vectors(limit)
+        if not pairs:
+            return 0
+        texts = [text for _, text in pairs]
+        try:
+            embeddings = self.llm_client.get_embeddings(
+                texts, self.embedding_model_name, self.embedding_dimensions
+            )
+        except EmbeddingUnavailableError as exc:
+            logger.warning(
+                "Embedding unavailable during missing-vector backfill; leaving "
+                "%d interaction(s) for the next tick: %s",
+                len(pairs),
+                exc,
+            )
+            return 0
+        backfilled = 0
+        for (iid, _text), embedding in zip(pairs, embeddings, strict=False):
+            if not embedding:
+                # Embedder returned empty for this row — leave it for next tick.
+                continue
+            self._persist_backfilled_vector(iid, embedding)
+            backfilled += 1
+        return backfilled
+
+    def _persist_backfilled_vector(
+        self, interaction_id: int, embedding: list[float]
+    ) -> None:
+        """Write a re-embedded vector for one interaction (column + vec row).
+
+        Updates the ``embedding`` TEXT column (read by the Python vector-rank
+        search path) and upserts the ``interactions_vec`` row via the same
+        ``_vec_upsert`` helper the insert path uses.
+
+        Only commits when it owns the transaction (mirroring ``_insert_interaction``)
+        so it can never flush a partial outer transaction if ever called inside an
+        open ``commit_scope``; ``_vec_upsert`` likewise defers under an open scope.
+        """
+        with self._lock:
+            own_txn = self._own_transaction()
+            self.conn.execute(
+                "UPDATE interactions SET embedding = ? WHERE interaction_id = ?",
+                (_json_dumps(embedding), interaction_id),
+            )
+            if own_txn:
+                self.conn.commit()
+        self._vec_upsert("interactions_vec", interaction_id, embedding)
+
     @SQLiteStorageBase.handle_exceptions
     def delete_user_interaction(self, request: DeleteUserInteractionRequest) -> None:
         with self._lock:

package/plugin/vendor/reflexio/reflexio/server/services/storage/sqlite_storage/profiles/_profile_store.py

@@ -16,6 +16,9 @@ from reflexio.models.api_schema.service_schemas import (
     Status,
     UserProfile,
 )
+from reflexio.server.services.storage.lifecycle_filters import (
+    validate_include_inactive,
+)
 
 from .._base import (
     _PROFILE_TOMBSTONE_STATUS_VALUES,
@@ -208,12 +211,14 @@ class ProfileStoreMixin:
         sql = f"SELECT * FROM profiles WHERE {' AND '.join(conditions)}"
         return [_row_to_profile(r) for r in self._fetchall(sql, all_params)]
 
-    @SQLiteStorageBase.handle_exceptions
-    def add_user_profile(self, user_id: str, user_profiles: list[UserProfile]) -> None:  # noqa: ARG002
-        for profile in user_profiles:
-            subject_ref = self._subject_ref_for_user_id(profile.user_id)
-            with self._lock:
-                self._assert_subject_writable_locked(subject_ref)
+    def precompute_profile_embeddings(self, profiles: list[UserProfile]) -> None:
+        """Populate ``.embedding`` / ``.expanded_terms`` in place; no DB write.
+
+        Extracted verbatim from the former ``add_user_profile`` prelude so the
+        durable compute/persist split can embed outside the writer transaction
+        and then persist with ``skip_embedding=True``.
+        """
+        for profile in profiles:
             embedding_text = "\n".join([profile.content, str(profile.custom_features)])
             if self._should_expand_documents():
                 with ThreadPoolExecutor(max_workers=2) as executor:
@@ -223,6 +228,25 @@ class ProfileStoreMixin:
                     profile.expanded_terms = exp_future.result(timeout=15)
             else:
                 profile.embedding = self._get_embedding(embedding_text)
+
+    @SQLiteStorageBase.handle_exceptions
+    def add_user_profile(
+        self,
+        user_id: str,  # noqa: ARG002
+        user_profiles: list[UserProfile],
+        *,
+        skip_embedding: bool = False,
+    ) -> None:
+        for profile in user_profiles:
+            subject_ref = self._subject_ref_for_user_id(profile.user_id)
+            with self._lock:
+                self._assert_subject_writable_locked(subject_ref)
+            # Default (skip_embedding=False) recomputes unconditionally, exactly
+            # as before — model_copy callers that change content while keeping
+            # the old embedding depend on this. The durable persist path opts
+            # out (embedding already set by precompute_profile_embeddings).
+            if not skip_embedding:
+                self.precompute_profile_embeddings([profile])
             embedding = profile.embedding
             with self._lock:
                 own_txn = self._own_transaction()
@@ -639,14 +663,25 @@ class ProfileStoreMixin:
         user_id: str,
         profile_ids: list[str],
         status_filter: list[Status | None] | None = None,
+        *,
+        include_inactive: bool = False,
     ) -> list[UserProfile]:
+        validate_include_inactive(
+            include_inactive=include_inactive, status_filter=status_filter
+        )
         if not profile_ids:
             return []
+        ph = ",".join("?" for _ in profile_ids)
+        if include_inactive:
+            rows = self._fetchall(
+                f"SELECT * FROM profiles WHERE user_id = ? AND profile_id IN ({ph})",
+                (user_id, *profile_ids),
+            )
+            return [_row_to_profile(r) for r in rows]
         if status_filter is None:
             status_filter = [None]
         current_ts = _epoch_now()
         frag, sparams = _build_status_sql(status_filter)
-        ph = ",".join("?" for _ in profile_ids)
         sql = (
             f"SELECT * FROM profiles "
             f"WHERE user_id = ? AND profile_id IN ({ph}) "

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/__init__.py

@@ -1,6 +1,5 @@
 from reflexio.models.api_schema.domain.enums import Status
 
-from ._learning_jobs import LearningJob, LearningJobStatus, LearningJobStoreABC
 from ._agent_run import (
     NOT_APPLICABLE_ANSWER,
     AgentBinding,
@@ -25,6 +24,7 @@ from ._agent_run import (
 from ._base import BaseStorageCore, matches_status_filter
 from ._commit_scope import CommitScopeMixin
 from ._extras import ExtrasMixin
+from ._learning_jobs import LearningJob, LearningJobStatus, LearningJobStoreABC
 from ._lineage import EntityType, LineageEventMixin
 from ._operations import OperationMixin
 from ._requests import RequestMixin

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_extras.py

@@ -1,13 +1,20 @@
 from abc import abstractmethod
+from typing import cast
 
 from reflexio.models.api_schema.braintrust_schema import (
     BraintrustConnection,
     ImportedScore,
 )
 from reflexio.models.api_schema.domain import (
+    CitationKind,
     Interaction,
 )
 from reflexio.models.api_schema.internal_schema import SessionCitation
+
+# Stored citation dicts are untyped JSON; only these kinds are valid.
+CITATION_KINDS: frozenset[str] = frozenset(
+    {"playbook", "profile", "user_playbook", "agent_playbook"}
+)
 from reflexio.models.api_schema.retriever_schema import PlaybookApplicationStat
 
 
@@ -142,12 +149,12 @@ class ExtrasMixin:
                         kind = getattr(cite, "kind", None)
                         real_id = getattr(cite, "real_id", None)
                         title = getattr(cite, "title", "") or ""
-                    if kind and real_id:
+                    if str(kind) in CITATION_KINDS and real_id:
                         out.append(
                             SessionCitation(
                                 user_id="",
                                 session_id=session_id,
-                                kind=str(kind),
+                                kind=cast("CitationKind", str(kind)),
                                 real_id=str(real_id),
                                 title=str(title),
                             )

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_learning_jobs.py

@@ -145,6 +145,7 @@ class LearningJobStoreABC(ABC):
         job_id: str,
         claim_token: str,
         dead: bool,
+        refund_attempt: bool = False,
     ) -> None:
         """Fenced fail/dead transition — sets status, does NOT increment attempts.
 
@@ -157,6 +158,25 @@ class LearningJobStoreABC(ABC):
         worker's dead-gate (``job.attempts >= max_attempts``) depends on that
         single-increment-per-claim invariant.  Incrementing here would
         double-count and misfire the dead transition.
+
+        ``refund_attempt`` (default ``False``): when ``True``, decrement
+        ``attempts`` by one (floored at 0) as part of this transition. This is
+        the same-user-contention requeue path (F4): the worker claimed the job
+        (``claim_learning_jobs`` did ``attempts += 1``) but could not run because
+        another same-user job holds the per-user lock, so it releases the job
+        WITHOUT having done any real work. Refunding the claim's increment makes
+        a contention cycle (claim +1, contention-release -1) net to zero, so a
+        job that loses the same-user race repeatedly (every ~2s poll while the
+        holder runs its ~60s compute) does NOT inflate ``attempts`` past
+        ``max_attempts`` and dead-letter with zero real retries. It is a no-op
+        unless ``refund_attempt=True``, so the ``dead`` retry path is unchanged.
+
+        # TASK 10: the enterprise Supabase (``reflexio_ext/server/services/
+        # storage/supabase_storage/_learning_jobs.py``) and native-Postgres
+        # ``fail_learning_job`` impls (and their ``claim_learning_jobs`` SQL
+        # functions) need this same ``refund_attempt`` decrement. The param is
+        # optional with a default so this base signature stays back-compatible
+        # until they are updated.
         """
         raise NotImplementedError
 
@@ -179,6 +199,36 @@ class LearningJobStoreABC(ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    def get_oldest_pending_learning_job_age_seconds(self) -> float | None:
+        """Age in seconds of the oldest ``status='pending'`` job on this storage ref.
+
+        Returns:
+            The age in seconds (``now - created_at``) of the oldest pending job,
+            or ``None`` if there are no pending jobs.
+
+        Resolves the table via the same placement resolver used by
+        ``list_org_ids_with_pending_learning_jobs`` — never hardcodes
+        ``public.`` or ``reflexio_ops.``.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def count_learning_jobs_by_status(self, status: str) -> int:
+        """Count of learning jobs with the given ``status`` on this storage ref.
+
+        Args:
+            status: One of ``'pending'``, ``'claimed'``, ``'done'``,
+                ``'failed'``, or ``'dead'``.
+
+        Returns:
+            The integer count of matching rows (0 if none).
+
+        Resolves the table via the same placement resolver used by the other
+        query methods — never hardcodes schema prefix.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     def get_learning_status_for_request(
         self,

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_operations.py

@@ -146,6 +146,10 @@ class OperationMixin:
            the current holder) are dropped to keep the queue idempotent under
            publish retries.
 
+        ``request_id`` is the intentional storage-boundary name here. Higher
+        layers may call the same value ``lock_request_id``, but persisted lock
+        rows and queued entries still use the legacy ``request_id`` key.
+
         The queue is a FIFO drained one entry at a time when the holder
         releases the lock. It replaces the older single-slot
         ``pending_request_id`` field, which silently dropped earlier blocked
@@ -178,6 +182,9 @@ class OperationMixin:
     ) -> bool:
         """Atomically clear an in-progress lock only if ``request_id`` still owns it.
 
+        The storage boundary keeps the legacy ``request_id`` naming for the
+        persisted lock holder even when callers use clearer local names.
+
         Args:
             state_key: Operation-state row key for the lock.
             request_id: Request attempting to release the lock.

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_retrieval_log.py

@@ -7,7 +7,9 @@ class RetrievalLogMixin:
     These methods are optional retrieval-capture storage hooks. They are
     intentionally concrete (not ``@abstractmethod``) so concrete storage classes
     remain instantiable; each raises ``NotImplementedError`` until a backend
-    provides a real implementation.
+    provides a real implementation. Stored item rows may use either the legacy
+    ``agent_playbook_id`` field or the explicit ``target_kind`` / ``target_id``
+    pair; readers should preserve backward compatibility for both.
     """
 
     def save_playbook_retrieval_log(self, log: PlaybookRetrievalLog) -> int:

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_shadow_verdicts.py

@@ -34,6 +34,10 @@ class ShadowVerdictsMixin:
     clear error message naming the backend rather than ``AttributeError``.
     """
 
+    def supports_shadow_comparison_verdicts(self) -> bool:
+        """Return whether this backend can persist shadow comparison verdicts."""
+        return False
+
     def save_shadow_comparison_verdict(
         self, verdict: ShadowComparisonVerdict
     ) -> ShadowComparisonVerdict:

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/agent_run/_models.py

@@ -44,7 +44,12 @@ class RunToolDependencyKind(StrEnum):
 
 @dataclass(frozen=True)
 class AgentBinding:
-    """Logical run binding flattened into `_agent_runs` storage columns."""
+    """Logical run binding flattened into `_agent_runs` storage columns.
+
+    ``request_id`` remains the persisted provenance field name at this storage
+    boundary even when higher-level helpers refer to the same value as a
+    generation request id.
+    """
 
     org_id: str
     extractor_kind: str
@@ -60,6 +65,12 @@ class AgentBinding:
 
 @dataclass(frozen=True)
 class AgentRunRecord:
+    """Durable agent run row plus snapshots used for resume/finalization.
+
+    ``generation_request_snapshot`` intentionally keeps a legacy ``request_id``
+    key for stored provenance.
+    """
+
     id: str
     binding: AgentBinding
     status: AgentRunStatus

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/evaluation_state_keys.py

@@ -0,0 +1,78 @@
+"""Single source of truth for evaluation ``_operation_state`` key formats.
+
+Three evaluation namespaces store per-session state in ``_operation_state``:
+
+1. ``agent_success_group_eval`` — the runner's "evaluated" marker.
+2. ``grade_on_demand`` — the 24h on-demand grading cache.
+3. ``retrieved_learning_eval`` — retrieved-learning generation/completion
+   state (see ``retrieved_learning_state.build_retrieved_learning_state_key``).
+
+Governance erasure must scrub all three for an erased user's sessions, so the
+key builders live here where both the producers (runner / evaluation route)
+and the erasers (sqlite + supabase governance) can import them without
+layering cycles.
+"""
+
+from __future__ import annotations
+
+AGENT_SUCCESS_MARKER_PREFIX = "agent_success_group_eval"
+GRADE_ON_DEMAND_CACHE_PREFIX = "grade_on_demand"
+
+
+def build_agent_success_marker_key(org_id: str, user_id: str, session_id: str) -> str:
+    """Build the agent-success "evaluated" marker key for a session.
+
+    Historical plain ``::`` join — kept byte-identical so existing markers
+    stay addressable.
+
+    Args:
+        org_id (str): Organization ID.
+        user_id (str): Session owner.
+        session_id (str): Evaluated session.
+
+    Returns:
+        str: The marker key.
+    """
+    return f"{AGENT_SUCCESS_MARKER_PREFIX}::{org_id}::{user_id}::{session_id}"
+
+
+def build_grade_on_demand_cache_key(
+    org_id: str, session_id: str, agent_version: str, evaluation_name: str
+) -> str:
+    """Build the grade-on-demand cache key (length-prefixed components).
+
+    Length-prefixing each free-form component keeps the join injective even
+    when a component contains the ``::`` delimiter.
+
+    Args:
+        org_id (str): Organization ID.
+        session_id (str): Target session.
+        agent_version (str): Agent version filter.
+        evaluation_name (str): Evaluator/result namespace.
+
+    Returns:
+        str: The cache key.
+    """
+    parts = "::".join(
+        f"{len(s)}:{s}" for s in (org_id, session_id, agent_version, evaluation_name)
+    )
+    return f"{GRADE_ON_DEMAND_CACHE_PREFIX}::{parts}"
+
+
+def build_grade_on_demand_session_prefix(org_id: str, session_id: str) -> str:
+    """Prefix matching every grade-on-demand cache key for one session.
+
+    Used by governance erasure to find a session's cache rows regardless of
+    agent_version / evaluation_name.
+
+    Args:
+        org_id (str): Organization ID.
+        session_id (str): Target session.
+
+    Returns:
+        str: The per-session key prefix (ends with ``::``).
+    """
+    return (
+        f"{GRADE_ON_DEMAND_CACHE_PREFIX}"
+        f"::{len(org_id)}:{org_id}::{len(session_id)}:{session_id}::"
+    )

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/playbook/_agent.py

@@ -161,6 +161,44 @@ class AgentPlaybookStoreMixin:
         """
         raise NotImplementedError
 
+    @abstractmethod
+    def get_agent_playbooks_by_ids(
+        self,
+        agent_playbook_ids: list[int],
+        *,
+        status_filter: list[Status | None] | None = None,
+        playbook_status_filter: list[PlaybookStatus] | None = None,
+        include_inactive: bool = False,
+    ) -> list[AgentPlaybook]:
+        """Fetch agent playbooks in bulk with lifecycle filters.
+
+        Args:
+            agent_playbook_ids (list[int]): Playbook ids to fetch. Empty list
+                returns ``[]`` without hitting storage.
+            status_filter (list[Status | None] | None): Lifecycle statuses to
+                include. ``None`` (default) means CURRENT only.
+            playbook_status_filter (list[PlaybookStatus] | None): Approval
+                statuses to include. ``None`` (default) means no approval filter.
+            include_inactive (bool): Return every matching row regardless of
+                lifecycle status *or* approval status. This is the *historical
+                resolution* mode (see ``RetrievedLearningEvaluator``): it answers
+                "what did this id point at", not "what is retrievable now", so an
+                archived or never-approved playbook that was actually served is
+                still returned. It is a strict superset of ``include_tombstones``
+                on ``get_agent_playbook_by_id``, which only unhides
+                MERGED/SUPERSEDED for lineage walks. The default preserves
+                retrieval behavior.
+
+        Returns:
+            list[AgentPlaybook]: Matching playbooks. Order is unspecified.
+
+        Raises:
+            StorageError: If ``include_inactive`` is combined with an explicit
+                ``status_filter`` or ``playbook_status_filter`` — the two are
+                contradictory.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     def delete_all_agent_playbooks(self) -> None:
         """Delete all agent playbooks from storage."""