claude-smart 0.2.48 → 0.2.50

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

@@ -0,0 +1,269 @@
+"""ABC, dataclass, and enum for the durable learning-job queue (Task 3)."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal
+
+# Upper bound of the done-row retention window.
+# Shared by all backends so the value cannot drift between implementations.
+# Err toward "not done" until we are sure a done row would have been GC'd.
+_ABSENCE_DONE_AFTER_SECONDS = 72 * 3600
+
+# Coverage-based status reported for a single request (§3.6). This is a
+# collapsed view of the raw job statuses (e.g. claimed -> processing,
+# reclaimable failed -> pending) and matches LearningStatusResponse.status.
+LearningStatus = Literal["pending", "processing", "done", "failed"]
+
+
+class LearningJobStatus(StrEnum):
+    PENDING = "pending"
+    CLAIMED = "claimed"
+    DONE = "done"
+    FAILED = "failed"
+    DEAD = "dead"
+
+
+@dataclass(frozen=True)
+class LearningJob:
+    job_id: str
+    org_id: str
+    user_id: str
+    job_type: str
+    latest_request_id: str | None
+    status: str
+    attempts: int
+    claim_token: str | None
+    covers_through: (
+        float | None
+    )  # epoch seconds (converted from stored ISO/timestamptz)
+    force_extraction: bool = False
+    skip_aggregation: bool = False
+    max_attempts: int = 3
+
+
+class LearningJobStoreABC(ABC):
+    """Abstract interface for durable learning-job queue operations.
+
+    All methods are scoped to the storage instance's own org (``self.org_id``).
+    ``enqueue_learning_job`` and ``complete_learning_job`` are safe to call
+    inside a ``commit_scope`` — they issue plain SQL on the scope's connection
+    without owning a separate BEGIN/COMMIT.
+    """
+
+    @abstractmethod
+    def enqueue_learning_job(
+        self,
+        *,
+        org_id: str,
+        user_id: str,
+        request_id: str,
+        covers_through: float,
+        job_type: str = "learning",
+        force_extraction: bool = False,
+        skip_aggregation: bool = False,
+    ) -> str:
+        """Coalescing upsert into the learning_jobs queue.
+
+        If a pending job for ``(org_id, user_id, job_type)`` already exists,
+        update its ``latest_request_id`` and keep the max ``covers_through``;
+        otherwise insert a new ``pending`` row.  Returns the ``job_id`` of the
+        pending row (existing or newly inserted).
+
+        Safe to call inside a ``commit_scope`` — no own BEGIN/COMMIT issued.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def claim_learning_jobs(
+        self,
+        *,
+        claimed_by: str,
+        limit: int,
+        lease_seconds: int,
+    ) -> list[LearningJob]:
+        """Atomically claim up to ``limit`` of this org's claimable jobs.
+
+        A job is claimable when it is ``pending``, ``failed`` (reclaimable —
+        attempts < max_attempts), OR (``claimed`` AND
+        ``claim_expires_at < now``).  Each claimed job receives a fresh
+        ``claim_token``, ``claimed_by``, and ``claim_expires_at``.
+
+        Postgres/Supabase: uses ``FOR UPDATE SKIP LOCKED`` via the
+        ``claim_learning_jobs`` SQL function.  SQLite: ``BEGIN IMMEDIATE``.
+        The claim predicate uses the DB's ``now()`` to avoid app/DB clock skew.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def heartbeat_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        lease_seconds: int,
+    ) -> bool:
+        """Extend the lease on a claimed job.
+
+        Updates ``claim_expires_at = now + lease_seconds`` only when
+        ``claim_token`` matches and status is still ``claimed``.
+
+        Returns:
+            True if the lease was extended (rowcount == 1), False if the token
+            was superseded or the job is no longer claimed.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def complete_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+    ) -> int:
+        """Fenced transition to ``done``.
+
+        Executes::
+
+            UPDATE learning_jobs
+               SET status='done', updated_at=now()
+             WHERE job_id=:job_id AND claim_token=:claim_token AND status='claimed'
+
+        Returns:
+            rowcount — 0 if the token was superseded or the job is already
+            done/dead/failed; 1 on success.  Callers MUST raise on 0 to roll
+            back the enclosing ``commit_scope``.
+
+        Safe to call inside a ``commit_scope`` — no own BEGIN/COMMIT issued.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def fail_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        dead: bool,
+        refund_attempt: bool = False,
+    ) -> None:
+        """Fenced fail/dead transition — sets status, does NOT increment attempts.
+
+        Fenced on ``claim_token`` and ``status='claimed'``.  Sets
+        ``status='dead'`` when ``dead=True``, else ``status='failed'`` (and
+        clears ``claim_token``/``claim_expires_at`` so the job is reclaimable).
+
+        ``attempts`` is intentionally NOT incremented here.  It is incremented
+        once per delivery attempt exclusively by ``claim_learning_jobs``; the
+        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
+
+    @abstractmethod
+    def list_org_ids_with_pending_learning_jobs(self) -> list[str]:
+        """Return distinct org_ids that have actionable learning jobs.
+
+        Cross-org discovery query for the :class:`DurableLearningScheduler`:
+        surfaces every org with at least one job that is ``pending``, ``failed``
+        (reclaimable), or ``claimed`` with an expired lease (a stolen/abandoned
+        claim). Terminal ``done``/``dead`` rows and live claims are excluded.
+
+        Mirrors ``list_resumable_work_org_ids``: NOT scoped to ``self.org_id`` —
+        on the shared global table (Postgres ``public.learning_jobs``, or a
+        SQLite DB shared across orgs) it returns every org with work in one
+        query so the scheduler need not enumerate all orgs.
+
+        Returns:
+            list[str]: Distinct org_ids with actionable work, ordered ascending.
+        """
+        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,
+        *,
+        user_id: str,
+        request_created_at: float,
+    ) -> LearningStatus:
+        """Coverage-based status for a single request (§3.6 rule).
+
+        Returns one of ``"done" | "processing" | "pending" | "failed"``.
+
+        Coverage rule (evaluated in priority order):
+
+        1. Any ``done`` job with ``covers_through >= request_created_at``
+           → ``"done"`` (correct even for zero-yield windows).
+        2. Any ``claimed`` job (any ``covers_through``)
+           → ``"processing"``.
+        3. Any ``pending`` job for this user
+           → ``"pending"``.
+        4. Any ``failed`` (reclaimable) job
+           → ``"pending"``.
+        5. Any ``dead`` job with ``covers_through >= request_created_at``
+           → ``"failed"``.
+        6. No rows AND ``now - request_created_at >= 72 h`` (retention window)
+           → ``"done"`` (done row would have been GC'd by now).
+        7. No rows AND request is recent
+           → ``"pending"`` (err toward not-done until retention window passes).
+        """
+        raise NotImplementedError
+
+
+__all__ = [
+    "_ABSENCE_DONE_AFTER_SECONDS",
+    "LearningJob",
+    "LearningJobStatus",
+    "LearningStatus",
+    "LearningJobStoreABC",
+]

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."""

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

@@ -1,9 +1,17 @@
 """Abstract agent success evaluation result store declarations."""
 
 from abc import abstractmethod
+from typing import Any
 
 from reflexio.models.api_schema.domain import (
     AgentSuccessEvaluationResult,
+    RetrievedLearningEvaluationResult,
+)
+
+from ..retrieved_learning_state import (
+    DEFAULT_TRANSCRIPT_CHAR_LIMIT,
+    BoundedRetrievedLearningSnapshot,
+    RetrievedLearningCommitResult,
 )
 
 
@@ -122,3 +130,166 @@ class AgentEvaluationResultStoreMixin:
             int: Number of rows deleted.
         """
         raise NotImplementedError
+
+    # ==============================
+    # Retrieved-learning evaluation methods
+    # ==============================
+    #
+    # Concurrency contract (see storage_base/retrieved_learning_state.py):
+    # generation fencing + session-fingerprint CAS recomputed under the
+    # replacement transaction's lock. No interaction write/delete path is
+    # instrumented.
+
+    @abstractmethod
+    def begin_retrieved_learning_evaluation_run(
+        self, user_id: str, session_id: str
+    ) -> int:
+        """Allocate the next evaluation generation for one session.
+
+        Atomically increments (creating on first use) the ``generation``
+        counter in the session's ``_operation_state`` row after asserting the
+        governance subject is writable. Concurrent callers receive distinct
+        generations.
+
+        Args:
+            user_id (str): Session owner.
+            session_id (str): Evaluated session.
+
+        Returns:
+            int: The allocated generation (monotonically increasing per
+            session).
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def load_bounded_retrieved_learning_snapshot(
+        self,
+        user_id: str,
+        session_id: str,
+        raw_ref_limit: int = 5_000,
+        transcript_char_limit: int = DEFAULT_TRANSCRIPT_CHAR_LIMIT,
+    ) -> BoundedRetrievedLearningSnapshot:
+        """Load the bounded session projection for evaluation.
+
+        Streams interaction rows (no ``Interaction`` objects, no embeddings or
+        image encodings) and counts raw attachment occurrences before
+        appending; on occurrence ``raw_ref_limit + 1`` the scan aborts with
+        ``attachment_limit_exceeded=True``.
+
+        Args:
+            user_id (str): Session owner.
+            session_id (str): Evaluated session.
+            raw_ref_limit (int): Maximum raw attachment occurrences to parse.
+            transcript_char_limit (int): Maximum transcript characters retained.
+
+        Returns:
+            BoundedRetrievedLearningSnapshot: The bounded projection.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_matching_retrieved_learning_terminal_state(
+        self, user_id: str, session_id: str, session_fingerprint: str
+    ) -> dict[str, Any] | None:
+        """Return the session's terminal evaluation state if still fresh.
+
+        Implementations must use a writer transaction and recompute the live
+        session fingerprint in that transaction. A match requires terminal
+        status and equality among the supplied, persisted, and live
+        fingerprints.
+
+        Args:
+            user_id (str): Session owner.
+            session_id (str): Evaluated session.
+            session_fingerprint (str): Fingerprint of the current session.
+
+        Returns:
+            dict | None: The persisted state JSON on a match, else None.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def replace_retrieved_learning_evaluation_results(
+        self,
+        user_id: str,
+        session_id: str,
+        generation: int,
+        session_fingerprint: str,
+        proposed_status: str,
+        diagnostics: dict[str, Any],
+        results: list[RetrievedLearningEvaluationResult],
+    ) -> RetrievedLearningCommitResult:
+        """Atomically replace one session's evaluation result set.
+
+        In one transaction: locks the session's state row, requires the
+        current generation to equal ``generation`` (else ``superseded``),
+        recomputes the session fingerprint from live rows and requires it to
+        equal ``session_fingerprint`` (else ``stale``), rechecks every
+        result's source row for retrieval eligibility (ineligible rows are
+        dropped), then deletes the prior session set, inserts the filtered
+        set, and persists completion state — all or nothing.
+
+        When commit-time eligibility removes every candidate, prior rows are
+        cleared and the final status is ``not_applicable`` regardless of
+        ``proposed_status``.
+
+        Args:
+            user_id (str): Session owner.
+            session_id (str): Evaluated session.
+            generation (int): Generation allocated by
+                :meth:`begin_retrieved_learning_evaluation_run`.
+            session_fingerprint (str): Fingerprint of the judged snapshot.
+            proposed_status (str): ``"complete"`` or ``"degraded"``.
+            diagnostics (dict): Sanitized counters/timestamps persisted in
+                operation state (never prompt content or raw exception text).
+            results (list[RetrievedLearningEvaluationResult]): Proposed rows.
+
+        Returns:
+            RetrievedLearningCommitResult: Disposition plus authoritative
+            final status/count when applied.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def finish_retrieved_learning_evaluation_run(
+        self,
+        user_id: str,
+        session_id: str,
+        generation: int,
+        status: str,
+        diagnostics: dict[str, Any],
+    ) -> None:
+        """Record a non-applied run outcome (``failed`` or ``pending``).
+
+        Generation-guarded CAS: updates state only while ``generation`` is
+        still current, so an older failure cannot overwrite a newer run.
+        Result rows are never touched.
+
+        Args:
+            user_id (str): Session owner.
+            session_id (str): Evaluated session.
+            generation (int): Generation of the finishing run.
+            status (str): ``"failed"`` or ``"pending"``.
+            diagnostics (dict): Sanitized counters and error type.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_retrieved_learning_evaluation_results(
+        self,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        limit: int = 100,
+    ) -> list[RetrievedLearningEvaluationResult]:
+        """Read persisted per-learning verdicts.
+
+        Args:
+            user_id (str, optional): Filter by session owner.
+            session_id (str, optional): Filter by session.
+            limit (int): Maximum rows, ordered by
+                ``created_at DESC, result_id DESC``.
+
+        Returns:
+            list[RetrievedLearningEvaluationResult]: Matching rows.
+        """
+        raise NotImplementedError