beaver-db 2.4.0__tar.gz → 2.4.2__tar.gz

{beaver_db-2.4.0 → beaver_db-2.4.2}/.github/workflows/ci.yml

@@ -25,3 +25,6 @@ jobs:
 
       - name: Run CI (format-check + unit tests)
         run: make ci
+
+      - name: Check the snippets on the product page
+        run: uv run python site/check_snippets.py

beaver_db-2.4.2/.github/workflows/pages.yml

@@ -0,0 +1,62 @@
+name: pages
+# beaver.syalia.com: the product page in site/ at the root, the Quarto docs
+# under /docs/, and a redirect page for each old docs URL. One artifact,
+# assembled by site/build.py. Pull requests build it; main deploys it.
+on:
+  push:
+    branches: [main]
+    paths: ["site/**", "docs/**", "pyproject.toml", ".github/workflows/pages.yml"]
+  pull_request:
+    branches: [main]
+    paths: ["site/**", "docs/**", "pyproject.toml", ".github/workflows/pages.yml"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      build_type: ${{ steps.pages.outputs.build_type }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: 1.9.37
+      - name: Render the docs
+        run: quarto render docs
+      - name: Assemble the site
+        run: python site/build.py public
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+      # Deploying needs the repository's Pages source set to "GitHub Actions".
+      # While it is still the gh-pages branch, the deploy job is skipped and
+      # the old site stays up; re-run this workflow after switching.
+      - id: pages
+        name: Read the Pages source
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          build_type=$(gh api "repos/${{ github.repository }}/pages" --jq .build_type || echo none)
+          echo "build_type=$build_type" >> "$GITHUB_OUTPUT"
+          if [ "$build_type" != workflow ]; then
+            echo "::notice::Pages source is '$build_type', not 'workflow': the deploy job will be skipped."
+          fi
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && needs.build.outputs.build_type == 'workflow'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v4

{beaver_db-2.4.0 → beaver_db-2.4.2}/.gitignore

@@ -14,3 +14,4 @@ wheels/
 .coverage
 _site
 benchmark
+public/

{beaver_db-2.4.0 → beaver_db-2.4.2}/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to beaver-db will be recorded here.
 
+## 2.4.2 — 2026-10-30
+
+### Fixed
+
+- **`db.lock()` could admit two waiters at once (#38).** The queue was ordered by a timestamp taken before the waiter's insert, so a waiter that stamped first and inserted second sorted ahead of the holder. The queue is now ordered by `rowid`, the order of arrival. A read-increment-write loop under the lock, 24 increments from 8 threads over two objects on one file, gave a duplicate in 2 of 30 runs on 2.4.1 and in 0 of 100 on 2.4.2.
+- **Indexing documents in several batches was quadratic (#40).** Each document's delete scanned the whole FTS5 table. It now finds the rows through a `MATCH` on the id. Three batches of 5,000 short documents took 0.3 s, 25.7 s and 50.4 s on 2.4.1, and about 0.3 s each on 2.4.2. Ids with no tokens, such as `___`, still take the scan.
+- **An expired `dict` key was not removed when read.** The delete ran inside the transaction that the `KeyError` rolled back, so the row stayed until it was overwritten.
+
+### Changed
+
+- **Reads no longer write.** `dict.get`, `list.get`, `queue.peek`, `docs.get`, `vectors.get`, `blob.get` and `blob.fetch` took the manager's internal lock, which writes a row to acquire and another to release. They now take only a transaction. `dict.get` went from about 200 to about 700 calls per second through `BeaverDB`.
+- **Several processes writing to one manager wait less.** The internal lock polls every 5 ms instead of every 100 ms. Two processes writing to one `dict` went from 22 to 156 writes per second, and four from 21 to 34.
+
+### Corrected
+
+- The 2.4.0 entry said Starlette and uvicorn cancel a request task whenever a client disconnects. In our measurement 12,800 client aborts against a fast plain handler caused no cancellation, while a streaming response was cancelled on every disconnect. The fix stands, and what started the 2026-08-10 outage is not known.
+
+## 2.4.1 — 2026-08-10
+
+### Fixed
+
+- **2.4.0's cleanup could itself hang, and could roll back the wrong
+  transaction.** Both were found by exercising a real service over HTTP rather
+  than in a unit test, and both come from the same fact: aiosqlite serialises
+  every statement onto one worker thread.
+
+  * *The hang.* When a **separate connection** holds the write lock, the
+    worker thread is parked inside SQLite's busy handler with `BEGIN
+    IMMEDIATE` still running. 2.4.0 *awaited* its cleanup rollback, which
+    queued behind that stuck statement — so a caller's 1.5 s deadline became a
+    30 s wait for SQLite's busy-timeout. Measured on warden's `/healthz`: curl
+    sat through the full 10 s of its `--max-time` and returned nothing.
+  * *The wrong rollback.* Merely scheduling it instead is not enough. An
+    uncontended `asyncio.Lock.acquire()` does not yield, so the next
+    transaction in the same task enqueues its `BEGIN` **ahead** of the pending
+    `ROLLBACK` — which then rolls back that innocent transaction, silently
+    committing its writes in autocommit.
+
+  Cleanup now runs in a background task that **holds the transaction lock
+  until the rollback has landed**. The caller returns immediately, and
+  ordering comes from mutual exclusion rather than from scheduling order.
+  Waiters are bounded by the same `connection_timeout` as before.
+
+- **Reclaiming an orphaned transaction awaits its rollback**, for the same
+  ordering reason — that path continues straight to `BEGIN` without yielding.
+  Bounded, and a timeout there raises `TransactionTimeoutError`.
+
 ## 2.4.0 — 2026-08-10
 
 ### Fixed — availability class

{beaver_db-2.4.0 → beaver_db-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: beaver-db
-Version: 2.4.0
+Version: 2.4.2
 Summary: Fast, async-native, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -61,13 +61,6 @@ Install the core library:
 pip install beaver-db
 ```
 
-> **Note:** `beaver-db 2.0` is currently in release-candidate cycle. The
-> CLI (`beaver` command), REST API server (`beaver serve`), `BeaverClient`
-> remote, and the published Docker image are all **landing in 2.0 final**
-> (target: June 2026). Today the library is consumed as a Python API only.
-> Track progress at `vault/Atlas/Architecture/2026-05-15-beaver-v2-release-plan.md`
-> in the workspace, or watch the `2.0` issues on GitHub.
-
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
@@ -113,14 +106,14 @@ db.close()
   * [**Persistent Priority Queue**](https://syalia.com/beaver/guide-queues.html): A high-performance, persistent priority queue perfect for task orchestration across multiple processes.
   * [**Probabilistic Sketches:**]() Track cardinality and membership for millions of items in constant space using HyperLogLog and Bloom Filters.
   * [**Document Collections**](https://syalia.com/beaver/guide-collections.html): Store rich documents combining a vector embedding and Pydantic-based metadata.
-  * [**Vector Search**](https://syalia.com/beaver/guide-collections.html%23vector-search): Fast, multi-process-safe linear vector search using an in-memory `numpy`-based index.
-  * [**Full-Text & Fuzzy Search**](https://syalia.com/beaver/guide-collections.html%23full-text-fuzzy-search): Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
-  * [**Knowledge Graph**](https://syalia.com/beaver/guide-collections.html%23knowledge-graph): Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
+  * [**Vector Search**](https://syalia.com/beaver/guide-collections.html#vector-search-semantic): Fast, multi-process-safe linear vector search using an in-memory `numpy`-based index.
+  * [**Full-Text & Fuzzy Search**](https://syalia.com/beaver/guide-collections.html#full-text-search-fts): Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
+  * [**Knowledge Graph**](https://syalia.com/beaver/guide-collections.html#graph-relationships): Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
   * [**Pub/Sub System**](https://syalia.com/beaver/guide-channels.html): A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture.
   * [**Time-Indexed Logs**](https://syalia.com/beaver/guide-logs.html): A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view.
   * [**Event-Driven Callbacks**](https://syalia.com/beaver/guide-channels.html): Listen for database changes in real-time. Subscribe to events on specific managers to trigger workflows or update UIs.
   * [**Inter-Process Locking**](https://syalia.com/beaver/guide-locks.html): Robust, deadlock-proof locks. Use `db.lock('task_name')` to coordinate arbitrary scripts, or `with db.list('my_list') as l:` to perform atomic, multi-step operations.
-  * [**Pydantic Support**](https://syalia.com/beaver/dev-architecture.html%23type-safe-models): Optionally associate `pydantic.BaseModel`s with any data structure for automatic, recursive data validation and (de)serialization.
+  * [**Pydantic Support**](https://syalia.com/beaver/guide.html#type-safe-models-with-pydantic): Optionally associate `pydantic.BaseModel`s with any data structure for automatic, recursive data validation and (de)serialization.
   * **Data Export**: Dump most data structures to a portable JSON file with a single `.dump()` command. (Full backup/restore symmetry — `.load()` across all managers, plus the `beaver` CLI and REST server — lands in `2.0` final; tracked in issues #15, #18, #36.)
 
 ## Documentation

{beaver_db-2.4.0 → beaver_db-2.4.2}/README.md

@@ -34,13 +34,6 @@ Install the core library:
 pip install beaver-db
 ```
 
-> **Note:** `beaver-db 2.0` is currently in release-candidate cycle. The
-> CLI (`beaver` command), REST API server (`beaver serve`), `BeaverClient`
-> remote, and the published Docker image are all **landing in 2.0 final**
-> (target: June 2026). Today the library is consumed as a Python API only.
-> Track progress at `vault/Atlas/Architecture/2026-05-15-beaver-v2-release-plan.md`
-> in the workspace, or watch the `2.0` issues on GitHub.
-
 ## Quickstart
 
 Get up and running in 30 seconds. This example showcases a dictionary, a list, and full-text search in a single script.
@@ -86,14 +79,14 @@ db.close()
   * [**Persistent Priority Queue**](https://syalia.com/beaver/guide-queues.html): A high-performance, persistent priority queue perfect for task orchestration across multiple processes.
   * [**Probabilistic Sketches:**]() Track cardinality and membership for millions of items in constant space using HyperLogLog and Bloom Filters.
   * [**Document Collections**](https://syalia.com/beaver/guide-collections.html): Store rich documents combining a vector embedding and Pydantic-based metadata.
-  * [**Vector Search**](https://syalia.com/beaver/guide-collections.html%23vector-search): Fast, multi-process-safe linear vector search using an in-memory `numpy`-based index.
-  * [**Full-Text & Fuzzy Search**](https://syalia.com/beaver/guide-collections.html%23full-text-fuzzy-search): Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
-  * [**Knowledge Graph**](https://syalia.com/beaver/guide-collections.html%23knowledge-graph): Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
+  * [**Vector Search**](https://syalia.com/beaver/guide-collections.html#vector-search-semantic): Fast, multi-process-safe linear vector search using an in-memory `numpy`-based index.
+  * [**Full-Text & Fuzzy Search**](https://syalia.com/beaver/guide-collections.html#full-text-search-fts): Automatically index and search through document metadata using SQLite's FTS5 engine, with optional fuzzy search for typo-tolerant matching.
+  * [**Knowledge Graph**](https://syalia.com/beaver/guide-collections.html#graph-relationships): Create directed, labeled relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
   * [**Pub/Sub System**](https://syalia.com/beaver/guide-channels.html): A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture.
   * [**Time-Indexed Logs**](https://syalia.com/beaver/guide-logs.html): A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view.
   * [**Event-Driven Callbacks**](https://syalia.com/beaver/guide-channels.html): Listen for database changes in real-time. Subscribe to events on specific managers to trigger workflows or update UIs.
   * [**Inter-Process Locking**](https://syalia.com/beaver/guide-locks.html): Robust, deadlock-proof locks. Use `db.lock('task_name')` to coordinate arbitrary scripts, or `with db.list('my_list') as l:` to perform atomic, multi-step operations.
-  * [**Pydantic Support**](https://syalia.com/beaver/dev-architecture.html%23type-safe-models): Optionally associate `pydantic.BaseModel`s with any data structure for automatic, recursive data validation and (de)serialization.
+  * [**Pydantic Support**](https://syalia.com/beaver/guide.html#type-safe-models-with-pydantic): Optionally associate `pydantic.BaseModel`s with any data structure for automatic, recursive data validation and (de)serialization.
   * **Data Export**: Dump most data structures to a portable JSON file with a single `.dump()` command. (Full backup/restore symmetry — `.load()` across all managers, plus the `beaver` CLI and REST server — lands in `2.0` final; tracked in issues #15, #18, #36.)
 
 ## Documentation

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/__init__.py

@@ -11,7 +11,7 @@ from .queries import q
 from .security import Secret
 from .errors import BeaverRemoteError, LocalOnlyError
 
-__version__ = "2.4.0"
+__version__ = "2.4.2"
 
 
 def connect(source: str, *, sync: bool = True, api_key: str | None = None):

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/blobs.py

@@ -7,7 +7,7 @@ from typing import (
 
 from pydantic import BaseModel
 
-from .manager import AsyncBeaverBase, atomic, emits
+from .manager import AsyncBeaverBase, atomic, read_atomic, emits
 from .interfaces import IAsyncBeaverBlob, BlobItem
 
 
@@ -75,7 +75,7 @@ class AsyncBeaverBlob[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverBlob[T]):
             (self._name, key, data, meta_json),
         )
 
-    @atomic
+    @read_atomic
     async def fetch(self, key: str) -> BlobItem:
         """
         Retrieves the full BlobItem (data + metadata).
@@ -93,7 +93,7 @@ class AsyncBeaverBlob[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverBlob[T]):
         meta = json.loads(row["metadata"]) if row["metadata"] else None
         return BlobItem(key=key, data=row["data"], metadata=meta)
 
-    @atomic
+    @read_atomic
     async def get(self, key: str) -> bytes:
         """
         Retrieves just the binary data for a key.

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/core.py

@@ -137,10 +137,7 @@ class Transaction:
         try:
             await self.db.connection.execute("BEGIN IMMEDIATE")
         except BaseException:
-            try:
-                await self._rollback_quietly()
-            finally:
-                self.db._tx_lock.release()
+            self._clean_up_in_the_background()
             raise
 
         self.db._tx_owner_task = current_task
@@ -206,28 +203,81 @@ class Transaction:
             self.db._db_path,
             owner.get_name(),
         )
-        await self._rollback_quietly()
         self.db._tx_owner_task = None
+
+        # Awaited, unlike the cleanup on the failure path below. There, the
+        # release()/wake-up of the next waiter is itself scheduled *after* the
+        # rollback task, so the queue order works out on its own. Here the same
+        # coroutine goes straight on to BEGIN IMMEDIATE without yielding, so a
+        # merely-scheduled rollback would land behind it — and SQLite refuses
+        # to begin a transaction inside one.
+        #
+        # Bounded, because the orphan's own transaction did complete its BEGIN,
+        # so the worker thread should be free; if it is not, something worse is
+        # wrong and the caller deserves to hear about it rather than wait.
+        try:
+            async with asyncio.timeout(self._timeout):
+                await self.db.connection.rollback()
+        except TimeoutError:
+            self.db._tx_lock.release()
+            raise TransactionTimeoutError(
+                f"could not roll back an orphaned transaction on "
+                f"{self.db._db_path!r} within {self._timeout:g}s — the "
+                f"connection is not responding"
+            ) from None
+        except Exception:
+            pass  # nothing was open after all; the lock is ours either way
         return True
 
-    async def _rollback_quietly(self) -> None:
-        """Undo a BEGIN that may have taken effect even though its await did not.
+    def _clean_up_in_the_background(self) -> None:
+        """Undo a BEGIN that failed, and release the lock once it is undone.
+
+        A BEGIN can fail two ways, and they need opposite things:
+
+        * **It raised.** Nothing began; the rollback is a formality.
+        * **Its await was cancelled.** `connection.execute("BEGIN IMMEDIATE")`
+          is two things — the statement running on aiosqlite's worker thread,
+          and the future we wait on. Cancelling the wait does not un-run the
+          statement, so SQLite's write lock may now be held with nothing left
+          to release it. That is the whole outage this class exists to prevent.
+
+        We cannot tell which happened, so we always roll back. What we must not
+        do is **await** it here: the worker thread may be parked inside
+        SQLite's busy handler because another *connection* holds the write
+        lock, and aiosqlite serialises one queue onto that thread — so the
+        rollback would sit behind the very statement that is stuck, turning a
+        caller's 1.5 s deadline into a 30 s hang. (Measured: warden's /healthz
+        sat through the full 10 s of curl's `--max-time` exactly this way.)
+
+        So the caller leaves immediately and a background task finishes the
+        job. **It holds `_tx_lock` until the rollback lands**, which is what
+        makes the ordering safe: without that, an uncontended `Lock.acquire()`
+        does not yield, so the very next transaction in this task would enqueue
+        its BEGIN *ahead* of our pending ROLLBACK — and get rolled back by it.
+        Mutual exclusion orders the two; scheduling luck does not. Anyone
+        waiting meanwhile is bounded by `_acquire`, and a store this wedged
+        genuinely is unavailable.
+        """
 
-        `await connection.execute("BEGIN IMMEDIATE")` is two things: the
-        statement running on aiosqlite's worker thread, and the future we wait
-        on. Cancelling the wait does not un-run the statement — so a cancelled
-        BEGIN can leave SQLite's write lock held with nothing left to release
-        it. That is the whole outage.
+        async def clean_up():
+            try:
+                await self.db.connection.rollback()
+            except Exception as exc:
+                # Expected when the BEGIN never took: there is no transaction
+                # to undo. The caller already has its own exception.
+                _log.debug("rollback of an abandoned transaction failed: %r", exc)
+            finally:
+                self.db._tx_lock.release()
 
-        Shielded, because the rollback has to survive the very cancellation
-        that made it necessary. Errors are swallowed: this runs while another
-        exception is already propagating, and `rollback()` is a no-op when no
-        transaction turned out to be open.
-        """
         try:
-            await asyncio.shield(self.db.connection.rollback())
-        except Exception:
-            pass
+            task = asyncio.ensure_future(clean_up())
+        except RuntimeError:  # no running loop left to clean up on
+            self.db._tx_lock.release()
+            return
+        # Hold a reference: a bare ensure_future() can be garbage-collected
+        # mid-flight, and this one is holding the write lock.
+        self.db._pending_rollbacks.add(task)
+        task.add_done_callback(self.db._pending_rollbacks.discard)
 
     async def __aexit__(self, exc_type, exc, tb):
         # Only the root transaction performs the Commit/Rollback and Release
@@ -280,6 +330,9 @@ class AsyncBeaverDB:
         # Locking Primitives
         self._tx_lock = asyncio.Lock()
         self._tx_owner_task: asyncio.Task | None = None  # Track owner for reentrancy
+        # In-flight cleanup rollbacks (see Transaction._rollback_quietly), held
+        # only so the event loop cannot garbage-collect them mid-flight.
+        self._pending_rollbacks: set[asyncio.Task] = set()
 
         # Manager Singleton Cache
         self._manager_cache: dict[tuple[type, str], Any] = {}

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/dicts.py

@@ -210,17 +210,17 @@ class AsyncBeaverDict[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverDict[T]):
     @expose(
         path="/{key}", method="GET", cli_name="get", cli_help="Get the value for a key."
     )
-    @atomic
     async def get(self, key: str) -> T:
         """Retrieves a value for a key. Raises KeyError if missing or expired."""
         if self._secret_arg and not self._cipher:
             await self._setup_security(self._secret_arg)
 
-        cursor = await self.connection.execute(
-            "SELECT value, expires_at FROM __beaver_dicts__ WHERE dict_name = ? AND key = ?",
-            (self._name, key),
-        )
-        result = await cursor.fetchone()
+        async with self._db.transaction():
+            cursor = await self.connection.execute(
+                "SELECT value, expires_at FROM __beaver_dicts__ WHERE dict_name = ? AND key = ?",
+                (self._name, key),
+            )
+            result = await cursor.fetchone()
 
         if result is None:
             raise KeyError(f"Key '{key}' not found in dictionary '{self._name}'")
@@ -228,16 +228,21 @@ class AsyncBeaverDict[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverDict[T]):
         raw_value, expires_at = result["value"], result["expires_at"]
 
         if expires_at is not None and time.time() > expires_at:
-            await self.connection.execute(
-                "DELETE FROM __beaver_dicts__ WHERE dict_name = ? AND key = ?",
-                (self._name, key),
-            )
+            # Outside the read's transaction: the KeyError would roll this back.
+            await self._delete_expired(key)
             raise KeyError(
                 f"Key '{key}' not found in dictionary '{self._name}' (expired)"
             )
 
         return self._deserialize(raw_value)
 
+    @atomic
+    async def _delete_expired(self, key: str):
+        await self.connection.execute(
+            "DELETE FROM __beaver_dicts__ WHERE dict_name = ? AND key = ? AND expires_at < ?",
+            (self._name, key, time.time()),
+        )
+
     @expose(path="/{key}", method="DELETE", cli_name="delete", cli_help="Delete a key.")
     @emits("del", payload=lambda key, *args, **kwargs: dict(key=key))
     @atomic

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/docs.py

@@ -13,7 +13,7 @@ from pydantic import BaseModel
 
 from . import indexing
 from .queries import Filter
-from .manager import AsyncBeaverBase, atomic, emits
+from .manager import AsyncBeaverBase, atomic, read_atomic, emits
 from .interfaces import Document, ScoredDocument, IDocumentQuery
 
 
@@ -106,6 +106,41 @@ class DocumentQuery[T: BaseModel](IDocumentQuery[T]):
             yield doc
 
 
+def _fts_id_filter(item_id: str) -> str | None:
+    """The FTS5 query that finds an id's rows, or None if it has no tokens."""
+    if not any(c.isalnum() for c in item_id):
+        return None
+    return 'item_id:"' + item_id.replace('"', '""') + '"'
+
+
+async def _delete_fts_rows(conn, collection: str, item_ids: list[str]) -> None:
+    """Delete the FTS rows of these ids.
+
+    FTS5 cannot use an index for `item_id = ?`, so that filter alone scans the whole
+    table for every id. MATCH finds the candidates through the index, and the
+    equality then drops other ids that tokenize alike. An id with no tokens cannot
+    be found by MATCH and takes the scan.
+    """
+    matched, scanned = [], []
+    for item_id in item_ids:
+        query = _fts_id_filter(item_id)
+        if query is None:
+            scanned.append((collection, item_id))
+        else:
+            matched.append((query, collection, item_id))
+    await conn.executemany(
+        """
+        DELETE FROM __beaver_fts_index__
+        WHERE __beaver_fts_index__ MATCH ? AND collection = ? AND item_id = ?
+        """,
+        matched,
+    )
+    await conn.executemany(
+        "DELETE FROM __beaver_fts_index__ WHERE collection = ? AND item_id = ?",
+        scanned,
+    )
+
+
 class AsyncDocumentsBatch[T: BaseModel]:
     """Async context manager for buffered bulk document indexing.
 
@@ -144,7 +179,7 @@ class AsyncDocumentsBatch[T: BaseModel]:
             return
 
         doc_rows: list[tuple[str, str, str]] = []
-        fts_delete_ids: list[tuple[str, str]] = []
+        fts_delete_ids: list[str] = []
         fts_rows: list[tuple[str, str, str, str]] = []
         trigram_delete_ids: list[tuple[str, str]] = []
         trigram_rows: list[tuple[str, str, str]] = []
@@ -158,7 +193,7 @@ class AsyncDocumentsBatch[T: BaseModel]:
 
             # Always clear stale FTS / trigram rows for this id (mirrors the
             # non-batched path so re-indexing the same id is consistent).
-            fts_delete_ids.append((self._manager._name, doc.id))
+            fts_delete_ids.append(doc.id)
             trigram_delete_ids.append((self._manager._name, doc.id))
 
             flat = list(_flatten_document(doc.body))
@@ -186,10 +221,7 @@ class AsyncDocumentsBatch[T: BaseModel]:
                     """,
                     doc_rows,
                 )
-                await conn.executemany(
-                    "DELETE FROM __beaver_fts_index__ WHERE collection = ? AND item_id = ?",
-                    fts_delete_ids,
-                )
+                await _delete_fts_rows(conn, self._manager._name, fts_delete_ids)
                 if fts_rows:
                     await conn.executemany(
                         """
@@ -270,10 +302,7 @@ class AsyncBeaverDocuments[T: BaseModel](AsyncBeaverBase[T]):
         )
 
         # 2. FTS Update (Flatten -> Delete Old -> Insert New)
-        await self.connection.execute(
-            "DELETE FROM __beaver_fts_index__ WHERE collection = ? AND item_id = ?",
-            (self._name, doc.id),
-        )
+        await _delete_fts_rows(self.connection, self._name, [doc.id])
 
         fts_rows = []
         for field_path, content in _flatten_document(doc.body):
@@ -323,7 +352,7 @@ class AsyncBeaverDocuments[T: BaseModel](AsyncBeaverBase[T]):
                 [(self._name, item_id, t) for t in trigrams],
             )
 
-    @atomic
+    @read_atomic
     async def get(self, id: str) -> Document[T]:
         """Retrieves a document by ID."""
         cursor = await self.connection.execute(
@@ -369,10 +398,7 @@ class AsyncBeaverDocuments[T: BaseModel](AsyncBeaverBase[T]):
             "DELETE FROM __beaver_documents__ WHERE collection = ? AND item_id = ?",
             (self._name, doc_id),
         )
-        await self.connection.execute(
-            "DELETE FROM __beaver_fts_index__ WHERE collection = ? AND item_id = ?",
-            (self._name, doc_id),
-        )
+        await _delete_fts_rows(self.connection, self._name, [doc_id])
         await self.connection.execute(
             "DELETE FROM __beaver_trigrams__ WHERE collection = ? AND item_id = ?",
             (self._name, doc_id),

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/lists.py

@@ -8,7 +8,7 @@ from datetime import datetime, timezone
 from pydantic import BaseModel
 
 from .api import expose, local_only
-from .manager import AsyncBeaverBase, atomic, emits
+from .manager import AsyncBeaverBase, atomic, read_atomic, emits
 from .interfaces import IAsyncBeaverList
 from ._fracdex import key_between
 
@@ -201,7 +201,7 @@ class AsyncBeaverList[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverList[T]):
         cli_name="get",
         cli_help="Retrieve an item at an index.",
     )
-    @atomic
+    @read_atomic
     async def get(self, index: Union[int, slice]) -> T | list[T]:
         """
         Retrieves an item or slice from the list.

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/locks.py

@@ -102,7 +102,7 @@ class AsyncBeaverLock(IAsyncBeaverLock):
                         """
                         SELECT waiter_id FROM __beaver_lock_waiters__
                         WHERE lock_name = ?
-                        ORDER BY requested_at ASC, rowid ASC
+                        ORDER BY rowid ASC
                         LIMIT 1
                         """,
                         (self._lock_name,),

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/manager.py

@@ -59,6 +59,7 @@ class AsyncBeaverBase[T: BaseModel]:
             internal_lock_name,
             timeout=5.0,  # Short timeout for internal operations
             lock_ttl=5.0,  # Short TTL to clear crashes
+            poll_interval=0.005,  # Held for milliseconds, so wait about as long
         )
 
     @property
@@ -173,6 +174,23 @@ def atomic(func):
     return wrapper
 
 
+def read_atomic(func):
+    """
+    A decorator to run a read in a database transaction.
+
+    The transaction keeps it from seeing another task's uncommitted writes on the
+    shared connection. It takes no manager lock: that lock writes a row to acquire
+    and another to release, which would make every read a write.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(self: AsyncBeaverBase, *args, **kwargs):
+        async with self._db.transaction():
+            return await func(self, *args, **kwargs)
+
+    return wrapper
+
+
 def emits(event: str | None = None, payload: Callable | None = None):
     """
     A decorator to emit an event after a manager method completes.

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/queues.py

@@ -9,7 +9,7 @@ from typing import (
 from pydantic import BaseModel
 
 from .api import expose, local_only
-from .manager import AsyncBeaverBase, atomic, emits
+from .manager import AsyncBeaverBase, atomic, read_atomic, emits
 from .interfaces import QueueItem, IAsyncBeaverQueue
 
 
@@ -76,7 +76,7 @@ class AsyncBeaverQueue[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverQueue[T]):
     @expose(
         path="/peek", method="GET", cli_name="peek", cli_help="Peek at the next item."
     )
-    @atomic
+    @read_atomic
     async def peek(self) -> QueueItem[T] | None:
         """
         Retrieves the first item of the queue without removing it.

{beaver_db-2.4.0 → beaver_db-2.4.2}/beaver/vectors.py

@@ -9,7 +9,7 @@ from typing import (
 
 from pydantic import BaseModel
 
-from .manager import AsyncBeaverBase, atomic, emits
+from .manager import AsyncBeaverBase, atomic, read_atomic, emits
 from .interfaces import IAsyncBeaverVectors, VectorItem
 from .queries import Filter
 
@@ -169,7 +169,7 @@ class AsyncBeaverVectors[T: BaseModel](AsyncBeaverBase[T], IAsyncBeaverVectors[T
             (self._name, bucket_id, id),
         )
 
-    @atomic
+    @read_atomic
     async def get(self, id: str) -> VectorItem[T]:
         cursor = await self.connection.execute(
             "SELECT vector, metadata FROM __beaver_vectors__ WHERE collection = ? AND item_id = ?",