claude-smart 0.2.48 → 0.2.50

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

@@ -0,0 +1,414 @@
+"""SQLite implementation of the durable learning-job queue (Task 3)."""
+
+import sqlite3
+import time
+import uuid
+from typing import Any
+
+from reflexio.server.services.storage.storage_base._learning_jobs import (
+    _ABSENCE_DONE_AFTER_SECONDS,
+    LearningJob,
+    LearningJobStoreABC,
+    LearningStatus,
+)
+
+from ._base import SQLiteStorageBase, _epoch_to_iso, _iso_to_epoch
+
+
+def _row_to_learning_job(row: sqlite3.Row) -> LearningJob:
+    """Convert a sqlite3.Row from learning_jobs to a LearningJob dataclass."""
+    d = dict(row)
+    ct = d.get("covers_through")
+    return LearningJob(
+        job_id=d["job_id"],
+        org_id=d["org_id"],
+        user_id=d["user_id"],
+        job_type=d["job_type"],
+        latest_request_id=d.get("latest_request_id"),
+        status=d["status"],
+        attempts=d["attempts"],
+        claim_token=d.get("claim_token"),
+        covers_through=float(_iso_to_epoch(ct)) if ct else None,
+        force_extraction=bool(d.get("force_extraction", 0)),
+        skip_aggregation=bool(d.get("skip_aggregation", 0)),
+        max_attempts=int(d.get("max_attempts", 3)),
+    )
+
+
+class SQLiteLearningJobStoreMixin(LearningJobStoreABC):
+    """SQLite implementation of the learning-job queue.
+
+    Relies on instance attributes provided by SQLiteStorageBase via MRO:
+    ``conn``, ``_lock``, ``_own_transaction``, ``org_id``.
+    """
+
+    # Type annotations for attributes/methods supplied by SQLiteStorageBase via MRO
+    _lock: Any
+    conn: sqlite3.Connection
+    org_id: str
+    _own_transaction: Any
+    _fetchall: Any
+
+    @SQLiteStorageBase.handle_exceptions
+    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 — safe to call inside a commit_scope."""
+        job_id = str(uuid.uuid4())
+        # int() truncates sub-second precision — intentional (second-precision epochs).
+        iso_covers = _epoch_to_iso(int(covers_through))
+        fe_int = int(force_extraction)
+        sa_int = int(skip_aggregation)
+        with self._lock:
+            own_txn = self._own_transaction()
+            try:
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
+                row = self.conn.execute(
+                    """
+                    INSERT INTO learning_jobs
+                        (job_id, org_id, user_id, job_type, latest_request_id,
+                         covers_through, status, force_extraction, skip_aggregation,
+                         created_at, updated_at)
+                    VALUES
+                        (?, ?, ?, ?, ?,
+                         ?, 'pending', ?, ?,
+                         strftime('%Y-%m-%dT%H:%M:%fZ','now'),
+                         strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+                    ON CONFLICT (org_id, user_id, job_type) WHERE status = 'pending'
+                    DO UPDATE SET
+                        latest_request_id = excluded.latest_request_id,
+                        covers_through = CASE
+                            WHEN learning_jobs.covers_through > excluded.covers_through
+                            THEN learning_jobs.covers_through
+                            ELSE excluded.covers_through
+                        END,
+                        force_extraction = excluded.force_extraction,
+                        skip_aggregation = excluded.skip_aggregation,
+                        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+                    RETURNING job_id
+                    """,
+                    (
+                        job_id,
+                        org_id,
+                        user_id,
+                        job_type,
+                        request_id,
+                        iso_covers,
+                        fe_int,
+                        sa_int,
+                    ),
+                ).fetchone()
+                if own_txn:
+                    self.conn.commit()
+            except Exception:
+                if own_txn:
+                    self.conn.rollback()
+                raise
+        if row is None:
+            raise RuntimeError("enqueue_learning_job RETURNING job_id returned no row")
+        return str(row["job_id"])
+
+    @SQLiteStorageBase.handle_exceptions
+    def claim_learning_jobs(
+        self,
+        *,
+        claimed_by: str,
+        limit: int,
+        lease_seconds: int,
+    ) -> list[LearningJob]:
+        """BEGIN IMMEDIATE + SELECT + UPDATE to atomically claim jobs."""
+        with self._lock:
+            own_txn = self._own_transaction()
+            try:
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
+
+                # Find candidate job_ids using DB's now() to avoid clock skew.
+                # Include 'failed' so a failed-but-not-dead job is naturally
+                # reclaimable without a manual status reset.
+                candidate_rows = self.conn.execute(
+                    """
+                    SELECT job_id FROM learning_jobs
+                    WHERE org_id = ?
+                      AND (
+                            status = 'pending'
+                            OR status = 'failed'
+                            OR (status = 'claimed'
+                                AND claim_expires_at < strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+                          )
+                    ORDER BY created_at
+                    LIMIT ?
+                    """,
+                    (self.org_id, limit),
+                ).fetchall()
+
+                claimed: list[LearningJob] = []
+                for cand in candidate_rows:
+                    job_id = cand["job_id"]
+                    claim_token = str(uuid.uuid4())
+                    updated = self.conn.execute(
+                        """
+                        UPDATE learning_jobs SET
+                            status = 'claimed',
+                            claimed_by = ?,
+                            claim_token = ?,
+                            claim_expires_at = strftime(
+                                '%Y-%m-%dT%H:%M:%fZ', 'now',
+                                ? || ' seconds'
+                            ),
+                            updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now'),
+                            attempts = attempts + 1
+                        WHERE job_id = ?
+                        RETURNING *
+                        """,
+                        (claimed_by, claim_token, str(lease_seconds), job_id),
+                    ).fetchone()
+                    if updated is not None:
+                        claimed.append(_row_to_learning_job(updated))
+
+                if own_txn:
+                    self.conn.commit()
+            except Exception:
+                if own_txn:
+                    self.conn.rollback()
+                raise
+
+        return claimed
+
+    @SQLiteStorageBase.handle_exceptions
+    def heartbeat_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        lease_seconds: int,
+    ) -> bool:
+        """Extend the lease; return True if the token is still live."""
+        with self._lock:
+            own_txn = self._own_transaction()
+            try:
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
+                cur = self.conn.execute(
+                    """
+                    UPDATE learning_jobs SET
+                        claim_expires_at = strftime(
+                            '%Y-%m-%dT%H:%M:%fZ', 'now',
+                            ? || ' seconds'
+                        ),
+                        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+                    WHERE job_id = ? AND claim_token = ? AND status = 'claimed'
+                    """,
+                    (str(lease_seconds), job_id, claim_token),
+                )
+                updated = cur.rowcount == 1
+                if own_txn:
+                    self.conn.commit()
+            except Exception:
+                if own_txn:
+                    self.conn.rollback()
+                raise
+
+        return updated
+
+    @SQLiteStorageBase.handle_exceptions
+    def complete_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+    ) -> int:
+        """Fenced completion — returns rowcount (0=superseded, 1=success).
+
+        Safe to call inside a commit_scope — no own BEGIN/COMMIT issued.
+        """
+        with self._lock:
+            own_txn = self._own_transaction()
+            try:
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
+                cur = self.conn.execute(
+                    """
+                    UPDATE learning_jobs SET
+                        status = 'done',
+                        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+                    WHERE job_id = ? AND claim_token = ? AND status = 'claimed'
+                    """,
+                    (job_id, claim_token),
+                )
+                rowcount = cur.rowcount
+                if own_txn:
+                    self.conn.commit()
+            except Exception:
+                if own_txn:
+                    self.conn.rollback()
+                raise
+
+        return rowcount
+
+    @SQLiteStorageBase.handle_exceptions
+    def fail_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        dead: bool,
+        refund_attempt: bool = False,
+    ) -> None:
+        """Fenced fail/dead transition — sets status, clears token for retry.
+
+        Does NOT increment attempts: claim_learning_jobs already incremented on
+        delivery.  attempts tracks delivery count; fail only transitions status.
+
+        ``refund_attempt=True`` (the same-user-contention requeue, F4) decrements
+        ``attempts`` by one (``MAX(attempts - 1, 0)``) so a contention cycle
+        (claim +1, contention-release -1) nets to zero and ``attempts`` stays
+        bounded regardless of how many times the job loses the per-user race.
+        Defaults to ``False`` (the ``dead`` retry path is unchanged).
+        """
+        new_status = "dead" if dead else "failed"
+        # Clear claim_token and claim_expires_at only for 'failed' so it's reclaimable.
+        # For 'dead', we keep claim_token set for auditability (won't be reclaimed anyway).
+        with self._lock:
+            own_txn = self._own_transaction()
+            try:
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
+                self.conn.execute(
+                    """
+                    UPDATE learning_jobs SET
+                        status = ?,
+                        claim_token = CASE WHEN ? THEN claim_token ELSE NULL END,
+                        claim_expires_at = CASE WHEN ? THEN claim_expires_at ELSE NULL END,
+                        attempts = CASE WHEN ? THEN MAX(attempts - 1, 0) ELSE attempts END,
+                        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
+                    WHERE job_id = ? AND claim_token = ? AND status = 'claimed'
+                    """,
+                    (new_status, dead, dead, refund_attempt, job_id, claim_token),
+                )
+                if own_txn:
+                    self.conn.commit()
+            except Exception:
+                if own_txn:
+                    self.conn.rollback()
+                raise
+
+    @SQLiteStorageBase.handle_exceptions
+    def list_org_ids_with_pending_learning_jobs(self) -> list[str]:
+        """Distinct org_ids with actionable jobs (cross-org, not org-scoped).
+
+        Uses the DB's now() for the expired-lease comparison to avoid clock skew,
+        mirroring ``claim_learning_jobs``. Index-aided by ``learning_jobs_poll``
+        (partial index narrows the scan to non-terminal rows; org_id still requires
+        a heap fetch).
+        """
+        rows = self._fetchall(
+            """
+            SELECT DISTINCT org_id FROM learning_jobs
+            WHERE status = 'pending'
+               OR status = 'failed'
+               OR (status = 'claimed'
+                   AND claim_expires_at < strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            ORDER BY org_id ASC
+            """,
+            (),
+        )
+        return [str(row["org_id"]) for row in rows]
+
+    @SQLiteStorageBase.handle_exceptions
+    def get_oldest_pending_learning_job_age_seconds(self) -> float | None:
+        """Age in seconds of the oldest pending job, or None if none pending.
+
+        Computes the age entirely in SQLite using ``strftime('%s','now')`` to
+        avoid app/DB clock skew.  The table is accessed without a schema prefix
+        (SQLite has no schema routing — the local DB file is the ref).
+        """
+        row = self._fetchall(
+            """
+            SELECT (strftime('%s', 'now') - strftime('%s', MIN(created_at))) AS age_seconds
+            FROM learning_jobs
+            WHERE status = 'pending'
+            """,
+            (),
+        )
+        return None if row[0]["age_seconds"] is None else float(row[0]["age_seconds"])
+
+    @SQLiteStorageBase.handle_exceptions
+    def count_learning_jobs_by_status(self, status: str) -> int:
+        """Count of learning jobs with the given status on this storage ref."""
+        row = self._fetchall(
+            "SELECT COUNT(*) AS cnt FROM learning_jobs WHERE status = ?",
+            (status,),
+        )
+        return int(row[0]["cnt"])
+
+    @SQLiteStorageBase.handle_exceptions
+    def get_learning_status_for_request(
+        self,
+        *,
+        user_id: str,
+        request_created_at: float,
+    ) -> LearningStatus:
+        """Coverage-based status lookup (§3.6 rule).
+
+        Converts request_created_at epoch to ISO for lexicographic comparison
+        with stored covers_through ISO strings (same format, both UTC).
+        """
+        req_iso = _epoch_to_iso(int(request_created_at))
+        rows = self._fetchall(
+            "SELECT status, covers_through FROM learning_jobs "
+            "WHERE org_id = ? AND user_id = ?",
+            (self.org_id, user_id),
+        )
+
+        has_pending = False
+        has_claimed_covering = False
+        has_dead_covering = False
+        has_failed = False
+
+        for row in rows:
+            status = row["status"]
+            ct: str | None = row["covers_through"]
+            covers = ct is not None and ct >= req_iso
+
+            if covers and status == "done":
+                return "done"
+            if covers and status == "claimed":
+                has_claimed_covering = True
+            if covers and status == "dead":
+                has_dead_covering = True
+            if status == "failed":
+                # 'failed' is reclaimable (attempts < max_attempts); treat as pending.
+                # Accumulate as a flag so a covering done row (encountered later in the
+                # iteration) is not shadowed by a failed row yielded earlier.
+                has_failed = True
+            if status == "pending":
+                has_pending = True
+            if status == "claimed":
+                # Deliberately treats any claimed job as covering, regardless of its
+                # covers_through value — it will extend the window once it completes.
+                has_claimed_covering = True
+
+        if has_claimed_covering:
+            return "processing"
+        if has_pending:
+            return "pending"
+        if has_failed:
+            return "pending"
+        if has_dead_covering:
+            return "failed"
+        # Absence semantics: terminal rows (done/dead) are GC'd after 24-72 h.
+        # Only treat absence as "done" once the request is old enough that a done
+        # row would have been reaped; a recent request with no rows is still pending.
+        if time.time() - request_created_at >= _ABSENCE_DONE_AFTER_SECONDS:
+            return "done"
+        return "pending"

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

@@ -127,6 +127,7 @@ class SQLiteLineageMixin:
     conn: sqlite3.Connection
     _lock: threading.RLock
     org_id: str
+    _own_transaction: Any
 
     def append_lineage_event(self, event: LineageEvent) -> int:
         """Append an event; idempotent on (org_id, entity_type, entity_id, op, request_id).
@@ -173,10 +174,12 @@ class SQLiteLineageMixin:
                     ),
                 ).fetchone()
                 eid = row[0] if row else None
-                self.conn.commit()
+                if self._own_transaction():
+                    self.conn.commit()
                 return int(eid) if eid is not None else 0
             last = cur.lastrowid
-            self.conn.commit()
+            if self._own_transaction():
+                self.conn.commit()
             return int(last) if last is not None else 0
 
     def get_lineage_events(
@@ -301,7 +304,8 @@ class SQLiteLineageMixin:
                 request_id=context.request_id,
                 reason=context.reason,
             )
-            self.conn.commit()
+            if self._own_transaction():
+                self.conn.commit()
 
     def supersede_record(
         self,
@@ -343,7 +347,8 @@ class SQLiteLineageMixin:
                 (Status.SUPERSEDED.value, successor_id, _epoch_now(), incumbent_id),
             )
             if cur.rowcount == 0:
-                self.conn.commit()
+                if self._own_transaction():
+                    self.conn.commit()
                 return False
             _append_event_stmt(
                 self.conn,
@@ -357,7 +362,8 @@ class SQLiteLineageMixin:
                 request_id=context.request_id,
                 reason=context.reason,
             )
-            self.conn.commit()
+            if self._own_transaction():
+                self.conn.commit()
             return True
 
     def purge_content(self, *, entity_type: EntityType, entity_id: str) -> bool:

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

@@ -32,6 +32,7 @@ class RequestMixin:
     _fetchall: Any
     _subject_ref_for_user_id: Any
     _assert_subject_writable_locked: Any
+    _own_transaction: Any
 
     # ------------------------------------------------------------------
     # Request methods
@@ -42,8 +43,10 @@ class RequestMixin:
         created_at_iso = _epoch_to_iso(request.created_at)
         subject_ref = self._subject_ref_for_user_id(request.user_id)
         with self._lock:
+            own_txn = self._own_transaction()
             try:
-                self.conn.execute("BEGIN IMMEDIATE")
+                if own_txn:
+                    self.conn.execute("BEGIN IMMEDIATE")
                 self._assert_subject_writable_locked(subject_ref)
                 self.conn.execute(
                     """INSERT OR REPLACE INTO requests
@@ -61,9 +64,11 @@ class RequestMixin:
                         subject_ref,
                     ),
                 )
-                self.conn.commit()
+                if own_txn:
+                    self.conn.commit()
             except Exception:
-                self.conn.rollback()
+                if own_txn:
+                    self.conn.rollback()
                 raise
 
     @SQLiteStorageBase.handle_exceptions

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

@@ -74,6 +74,10 @@ class ShadowVerdictsMixin:
     _fetchone: Any
     _fetchall: Any
 
+    def supports_shadow_comparison_verdicts(self) -> bool:
+        """Return whether this backend can persist shadow comparison verdicts."""
+        return True
+
     @SQLiteStorageBase.handle_exceptions
     def save_shadow_comparison_verdict(
         self, verdict: ShadowComparisonVerdict

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

@@ -46,14 +46,25 @@ class SQLiteDeletionMixin:
 
     @SQLiteStorageBase.handle_exceptions
     def _retention_select_oldest_keys(
-        self, target: RetentionTarget, count: int
+        self,
+        target: RetentionTarget,
+        count: int,
+        statuses: tuple[str, ...] | None = None,
     ) -> list[tuple[Any, ...]]:
+        if statuses is not None and not statuses:
+            return []
         id_sql = ", ".join(target.id_columns)
-        tiebreak_sql = id_sql
+        where_sql = ""
+        params: list[Any] = []
+        if statuses:
+            placeholders = ", ".join("?" for _ in statuses)
+            where_sql = f"WHERE status IN ({placeholders}) "
+            params.extend(statuses)
+        params.append(count)
         rows = self._fetchall(
-            f"SELECT {id_sql} FROM {target.table_name} "  # noqa: S608
-            f"ORDER BY {target.order_column} ASC, {tiebreak_sql} ASC LIMIT ?",
-            (count,),
+            f"SELECT {id_sql} FROM {target.table_name} {where_sql}"  # noqa: S608
+            f"ORDER BY {target.order_column} ASC, {id_sql} ASC LIMIT ?",
+            tuple(params),
         )
         return [tuple(row[col] for col in target.id_columns) for row in rows]
 

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

@@ -6,6 +6,11 @@ index sidecar update is durable. They are sqlite-only — there is no
 supabase/postgres counterpart. Composed into ``SQLiteStorage`` ahead of
 ``SQLiteStorageBase``; the boot-time ``_migrate_vec_tables`` (residual in
 ``_base.py``) resolves ``self._vec_upsert`` through the composed MRO.
+
+When a ``commit_scope`` is active (``_scope_depth > 0``), the public helpers
+buffer the operation into ``_deferred_index_ops`` for post-commit flushing;
+the ``_..._now`` variants always execute immediately and are called by
+``_flush_index_op`` after the outer commit.
 """
 
 from __future__ import annotations
@@ -23,10 +28,50 @@ class SQLiteFtsVecMixin:
     conn: sqlite3.Connection
     _fetchall: Any
     _has_sqlite_vec: bool
+    _scope_depth: int
+    _deferred_index_ops: list[tuple[str, Any]]
+
+    # ------------------------------------------------------------------
+    # Dispatcher — called by commit_scope after the outer commit
+    # ------------------------------------------------------------------
+
+    def _flush_index_op(self, kind: str, args: Any) -> None:
+        """Dispatch a buffered index op after the outer commit."""
+        if kind == "fts_upsert":
+            table, rowid, text_fields = args
+            self._fts_upsert_now(table, rowid, **text_fields)
+        elif kind == "fts_delete":
+            table, rowid = args
+            self._fts_delete_now(table, rowid)
+        elif kind == "fts_upsert_profile":
+            profile_id, content = args
+            self._fts_upsert_profile_now(profile_id, content)
+        elif kind == "fts_delete_profile":
+            (profile_id,) = args
+            self._fts_delete_profile_now(profile_id)
+        elif kind == "vec_upsert":
+            table, rowid, embedding = args
+            self._vec_upsert_now(table, rowid, embedding)
+        elif kind == "vec_delete":
+            table, rowid = args
+            self._vec_delete_now(table, rowid)
+        else:
+            raise ValueError(f"unknown index op kind: {kind!r}")
+
+    # ------------------------------------------------------------------
+    # FTS helpers — public (defer when in scope) + _now (immediate)
+    # ------------------------------------------------------------------
 
-    # FTS helpers
     def _fts_upsert(self, table: str, rowid: int, **text_fields: str | None) -> None:
         """Insert or update an FTS row.  Deletes old entry first to avoid duplicates."""
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(("fts_upsert", (table, rowid, text_fields)))
+            return
+        self._fts_upsert_now(table, rowid, **text_fields)
+
+    def _fts_upsert_now(
+        self, table: str, rowid: int, **text_fields: str | None
+    ) -> None:
         with self._lock:
             self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
             cols = list(text_fields.keys())
@@ -40,12 +85,26 @@ class SQLiteFtsVecMixin:
             self.conn.commit()
 
     def _fts_delete(self, table: str, rowid: int) -> None:
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(("fts_delete", (table, rowid)))
+            return
+        self._fts_delete_now(table, rowid)
+
+    def _fts_delete_now(self, table: str, rowid: int) -> None:
         with self._lock:
             self.conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))  # noqa: S608
             self.conn.commit()
 
     def _fts_upsert_profile(self, profile_id: str, content: str) -> None:
         """FTS for profiles uses profile_id TEXT as key column."""
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(
+                ("fts_upsert_profile", (profile_id, content))
+            )
+            return
+        self._fts_upsert_profile_now(profile_id, content)
+
+    def _fts_upsert_profile_now(self, profile_id: str, content: str) -> None:
         with self._lock:
             self.conn.execute(
                 "DELETE FROM profiles_fts WHERE profile_id = ?", (profile_id,)
@@ -57,15 +116,32 @@ class SQLiteFtsVecMixin:
             self.conn.commit()
 
     def _fts_delete_profile(self, profile_id: str) -> None:
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(("fts_delete_profile", (profile_id,)))
+            return
+        self._fts_delete_profile_now(profile_id)
+
+    def _fts_delete_profile_now(self, profile_id: str) -> None:
         with self._lock:
             self.conn.execute(
                 "DELETE FROM profiles_fts WHERE profile_id = ?", (profile_id,)
             )
             self.conn.commit()
 
-    # Vec helpers (sqlite-vec)
+    # ------------------------------------------------------------------
+    # Vec helpers (sqlite-vec) — public (defer when in scope) + _now (immediate)
+    # ------------------------------------------------------------------
+
     def _vec_upsert(self, table: str, rowid: int, embedding: list[float]) -> None:
         """Insert or update a vec table row. No-op when sqlite-vec is unavailable."""
+        if not self._has_sqlite_vec:
+            return
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(("vec_upsert", (table, rowid, embedding)))
+            return
+        self._vec_upsert_now(table, rowid, embedding)
+
+    def _vec_upsert_now(self, table: str, rowid: int, embedding: list[float]) -> None:
         if not self._has_sqlite_vec:
             return
         with self._lock:
@@ -78,6 +154,14 @@ class SQLiteFtsVecMixin:
 
     def _vec_delete(self, table: str, rowid: int) -> None:
         """Delete a vec table row. No-op when sqlite-vec is unavailable."""
+        if not self._has_sqlite_vec:
+            return
+        if self._scope_depth > 0:
+            self._deferred_index_ops.append(("vec_delete", (table, rowid)))
+            return
+        self._vec_delete_now(table, rowid)
+
+    def _vec_delete_now(self, table: str, rowid: int) -> None:
         if not self._has_sqlite_vec:
             return
         with self._lock: