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

{beaver_db-2.4.1 → 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.1 → beaver_db-2.4.2}/.gitignore

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

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

@@ -2,6 +2,23 @@
 
 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

{beaver_db-2.4.1 → 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.1
+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.1 → 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.1 → 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.1"
+__version__ = "2.4.2"
 
 
 def connect(source: str, *, sync: bool = True, api_key: str | None = None):

{beaver_db-2.4.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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 = ?",

{beaver_db-2.4.1 → beaver_db-2.4.2}/docs/_quarto.yml

@@ -2,23 +2,29 @@
 project:
   type: website
   output-dir: _site
+  # Internal design notes stay in the repo, not on the published docs.
+  render:
+    - "*.md"
+    - "!superpowers/"
 
 # Website-level metadata
 website:
   title: "BeaverDB"
+  site-url: https://beaver.syalia.com/docs/
   # author: "SYALIA S.R.L."
   # license: "CC BY-NC-SA 4.0"
 
 
   # --- Navigation Bar ---
   navbar:
-    logo: "logo.png"
+    logo: "img/beaver.webp"
     pinned: true
     search: true
     left:
-      - href: index.html
+      # The product page sits one level up, at the site root.
+      - href: ../index.html
         text: Home
-      - href: intro.md
+      - href: index.md
         text: Introduction
       - href: quickstart.md
         text: Quickstart
@@ -77,13 +83,14 @@ website:
 format:
   html:
     theme:
-      light: cosmo
+      light: [cosmo, beaver.scss]
       # dark:
     toc: true
     toc-depth: 3
     code-fold: true
     code-copy: true
-    mainfont: "Inter"
+    # Plain math keeps the docs free of CDN scripts; the docs only write $T$.
+    html-math-method: plain
 
 # # --- PDF Output Format (Optional) ---
 # # This format can still be used to generate a PDF of individual pages

beaver_db-2.4.2/docs/beaver.scss

@@ -0,0 +1,29 @@
+/*-- scss:defaults --*/
+// Beaver's colours from logo.png on top of cosmo, so the docs match the
+// product page. No web font import: the fonts come from the site itself.
+$web-font-path: false;
+$navy: #1a2757;
+$fur: #cc722d;
+$paper: #fbf6ee;
+$primary: $navy;
+$body-bg: $paper;
+$body-color: $navy;
+$link-color: #a85a1f;
+$navbar-bg: #fffdf9;
+$navbar-fg: $navy;
+$font-family-sans-serif: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
+$font-family-monospace: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+$headings-font-family: "Nunito", "Inter", system-ui, sans-serif;
+$headings-font-weight: 800;
+
+/*-- scss:rules --*/
+// Paths are relative to docs/: Quarto copies the files from site/fonts/
+// into the rendered docs, so they work wherever the docs are served.
+@font-face { font-family: "Nunito"; font-weight: 800; font-display: swap; src: url("../site/fonts/nunito-800.woff2") format("woff2"); }
+@font-face { font-family: "Inter"; font-weight: 400; font-display: swap; src: url("../site/fonts/inter-400.woff2") format("woff2"); }
+@font-face { font-family: "Inter"; font-weight: 600; font-display: swap; src: url("../site/fonts/inter-600.woff2") format("woff2"); }
+@font-face { font-family: "JetBrains Mono"; font-weight: 400; font-display: swap; src: url("../site/fonts/jbmono-400.woff2") format("woff2"); }
+
+.navbar { border-bottom: 2px solid $navy; }
+.navbar-brand .navbar-title { font-family: "Nunito", "Inter", sans-serif; font-weight: 800; }
+.navbar-logo { border-radius: 8px; }

{beaver_db-2.4.1 → beaver_db-2.4.2}/docs/dev-concurrency.md

@@ -22,30 +22,13 @@ In **WAL mode**:
 
 This allows BeaverDB to handle high-throughput scenarios (e.g., a logger writing events while an API server queries them) without lock contention errors.
 
-## Thread Safety (`threading.local`)
+## Thread Safety (one connection)
 
-SQLite connections cannot be shared across threads. If two threads try to write to the same `sqlite3.Connection` object, the application will crash or corrupt memory.
+`AsyncBeaverDB` opens **one** aiosqlite connection, and aiosqlite runs every statement on one worker thread. `BeaverDB`, the synchronous facade, runs that engine on a reactor thread and sends each call there, so any number of threads can share one instance.
 
-BeaverDB manages this automatically using **Thread-Local Storage**.
+Every statement in a process therefore runs in turn: a slow query delays all the others, including reads of unrelated data. A second `BeaverDB` on the same file opens its own connection, and SQLite's file locking mediates between them.
 
-```python
-# Internal Logic
-class BeaverDB:
-    def __init__(self):
-        self._thread_local = threading.local()
-
-    @property
-    def connection(self):
-        # If this thread has never asked for a connection, open one.
-        if not hasattr(self._thread_local, "conn"):
-            self._thread_local.conn = sqlite3.connect(...)
-
-        return self._thread_local.conn
-```
-
-  * When Thread A calls `db.dict("x")`, it gets a connection dedicated to Thread A.
-  * When Thread B calls `db.dict("x")`, it gets a different connection dedicated to Thread B.
-  * Both connections talk to the same file, mediated by SQLite's file locking.
+Reads that take a transaction (`dict.get`, `list.get`, `docs.get` and others) do so to avoid seeing another task's uncommitted writes on the shared connection. They do not take the manager's lock, whose acquire and release each write a row.
 
 ## The in-process write lock (`Transaction`)
 

{beaver_db-2.4.1 → beaver_db-2.4.2}/makefile

@@ -6,7 +6,17 @@ sync:
 
 .PHONY: docs
 docs:
-	cd docs && quarto publish gh-pages
+	quarto preview docs
+
+# The Pages artifact, built as .github/workflows/pages.yml builds it.
+.PHONY: site
+site:
+	quarto render docs
+	uv run python site/build.py public
+
+.PHONY: check-snippets
+check-snippets:
+	uv run python site/check_snippets.py
 
 .PHONY: bugfix
 bugfix:

{beaver_db-2.4.1 → beaver_db-2.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beaver-db"
-version = "2.4.1"
+version = "2.4.2"
 description = "Fast, async-native, embedded, and multi-modal DB based on SQLite for AI-powered applications."
 readme = "README.md"
 requires-python = ">=3.12"