simplevecdb 2.5.0__tar.gz → 2.6.1__tar.gz

simplevecdb-2.6.1/.bandit

@@ -0,0 +1,9 @@
+exclude_dirs:
+
+- /tests
+- /examples
+
+skips:
+
+- B104  # 0.0.0.0 binding: SERVER_HOST defaults to 127.0.0.1; bandit can't see runtime defaults, so the warning is a false positive on this codebase. Keep it skipped only because the default is safe — if anyone introduces a hardcoded "0.0.0.0", remove this skip.
+- B608  # SQL injection false positive: table names are validated via _validate_table_name()

simplevecdb-2.6.1/.github/FUNDING.yml

@@ -0,0 +1,5 @@
+github: [coderdayton]
+custom:
+  [
+    "https://ko-fi.com/xbbvii",
+  ]

simplevecdb-2.6.1/.gitignore

@@ -0,0 +1,70 @@
+# Python / uv
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.tox/
+.nox/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.cache/
+.hypothesis/
+cython_debug/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+htmlcov/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment / secrets
+.env
+.envrc
+.direnv/
+
+# Databases (SimpleVecDB writes WAL/SHM sidecars)
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Editor / IDE
+.vscode/
+.idea/
+.history/
+*.iml
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Docs build
+site/
+
+# Agentic CLI tools (per-developer state)
+.opencode/
+opencode.json
+.claude/
+.codex
+
+# Project-specific scratch
+simplevecdb_plan.md
+AGENTS.md
+NEXT_UPDATES.md
+pro_pack/

{simplevecdb-2.5.0 → simplevecdb-2.6.1}/CHANGELOG.md

@@ -5,6 +5,220 @@ All notable changes to SimpleVecDB will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.1] - 2026-05-10
+
+### Storage, mutation, and eventing improvements
+
+This release closes ten long-standing gaps in the catalog layer with a coherent
+set of additive primitives. No public API breaks; existing 2.6.0 databases
+upgrade transparently (the new tables are created on first open).
+
+#### New features
+
+- **Native vector update via pending buffer** — `collection.update_embedding(id, vector)`
+  writes a row to a per-collection `_pending_vectors` overlay inside one SQL
+  transaction; the new vector becomes visible to reads immediately and is
+  promoted to the HNSW index on `collection.pending.flush()`. Removes the
+  HNSW remove+re-add churn previously required for in-place updates.
+- **Bulk vector math** — `collection.pending.update_many([(id, vec), …])` and
+  `collection.pending.blend_toward(ids, centroid, alpha)` for batched edits.
+- **Atomic transaction boundary** — `with db.transaction() as tx: …` and
+  `with collection.tx(): …` wrap a SAVEPOINT around catalog writes
+  (metadata, counters, edges, events, TTL, and `update_embedding`'s
+  pending overlay) so a raised exception rolls all SQL writes back.
+  Coarse vector mutations (`add_texts`, `delete`) are NOT rolled back —
+  use `update_embedding` + `pending.flush()` for vector changes that
+  must be commit-gated. Nested contexts share a single savepoint stack
+  via the new `_TxState` helper.
+- **Weighted directed edges** — new `collection.edges` namespace with
+  `add_edge / get_edges / update_edge / delete_edge / prune` over a
+  per-collection `_edges` table. Numeric columns (`weight`, `bonus`, `hits`,
+  `last_touch`) are addressable by the new range-filter grammar; deltas
+  (`dweight=+0.02, dhits=+1`) compile to a single atomic SQL UPDATE.
+- **Atomic counter increments** — `collection.increment_metadata(id, {"hits": 1, "drift": 0.02})`
+  applies a dict of numeric deltas to JSON metadata in one statement using
+  chained `json_set(... json_extract + ?)` calls. WAL-atomic; safe under
+  concurrent writers.
+- **Mongo-style range filters** — `filter={"score": {"$gt": 0.5, "$lte": 0.9}}`
+  on `similarity_search`, `keyword_search`, `hybrid_search`, `edges.get_edges`,
+  and `events.read`. Supported operators: `$eq $ne $gt $gte $lt $lte $in $nin
+  $exists $between`. Tuple shorthand (`("range", lo, hi)`, `(">", x)`) is
+  normalised into the operator-dict form.
+- **Append-only change feed** — every mutating method now appends one row to
+  a per-collection `_events` table (kind, doc_id, payload, monotonic seq).
+  `collection.events.read(since=, kind=, limit=)`,
+  `collection.events.subscribe(since=, poll_interval=)`, and
+  `collection.events.prune(before_seq=)` expose the feed; cross-process
+  visibility comes from the existing WAL mode.
+- **TTL / expiry hooks** — `collection.ttl.set(id, seconds=…, on_expire="delete"|"callback")`,
+  `collection.ttl.clear(id)`, and `collection.ttl.sweep()` over a
+  `_ttl` table; `start_background(interval=…)` runs the sweep in a daemon
+  thread (off by default).
+- **Incremental rebuild scheduler** — `collection.maintenance.rebuild_if_needed(max_pending=, max_deleted=)`
+  triggers a full `rebuild_index()` only when the configured pending /
+  tombstone / wall-time thresholds are crossed.
+- **Multi-process write safety** — added `PRAGMA busy_timeout=5000` and
+  `PRAGMA foreign_keys=ON` at every connection-open site (encrypted and
+  unencrypted). The native 5 s wait window reduces `DatabaseLockedError`
+  pressure under contention; foreign keys cascade-delete pending /
+  edges / TTL rows when a doc is deleted. The events table is
+  intentionally FK-less so the audit trail survives deletions.
+- **Async wrappers** — `AsyncVectorCollection` gains async equivalents of the
+  new methods (`update_embedding`, `flush_pending`, `increment_metadata`,
+  `add_edge`, `update_edge`, `delete_edge`, `get_edges`, `set_ttl`,
+  `clear_ttl`, `sweep_ttl`, `read_events`, `last_event_seq`,
+  `rebuild_if_needed`).
+
+#### New types & constants
+
+- `simplevecdb.types`: `Edge`, `Event`, `TTLEntry` frozen dataclasses.
+- `simplevecdb.constants`: `PENDING_FLUSH_DEFAULT_BATCH=1000`,
+  `EVENTS_POLL_INTERVAL_S=0.1`, `EVENTS_RETENTION_LIMIT=100_000`,
+  `TTL_SWEEP_DEFAULT_INTERVAL_S=60.0`, `REBUILD_PENDING_THRESHOLD=5_000`,
+  `REBUILD_TOMBSTONE_THRESHOLD=5_000`, `REBUILD_MIN_INTERVAL_S=3600.0`,
+  `SQLITE_BUSY_TIMEOUT_MS=5000`.
+
+#### Test coverage
+
+- `tests/unit/test_v26_1_features.py` — 25 tests covering the five must-have
+  primitives end-to-end: `update_embedding` + pending buffer + flush; edges
+  CRUD with atomic deltas, range filtering, and prune; `increment_metadata`
+  under 800-thread contention (exact total preserved); transaction rollback
+  and commit semantics; Mongo-style and tuple-shorthand range filters in
+  `similarity_search`; events append on every mutation; TTL sweep with
+  `delete` and `callback` paths; threshold-driven rebuild scheduler.
+
+#### Removed
+
+- **`sqlite-vec` dependency** dropped from `pyproject.toml`. The package was
+  never imported and the v1.x → v2.0 auto-migration code path could not have
+  worked without explicitly loading the extension at connection time.
+- **`MigrationRequiredError`**, **`VectorDB.check_migration()`**, and the
+  **`auto_migrate=`** constructor flag have been removed. Databases written
+  by `simplevecdb < 2.0.0` (sqlite-vec backend) are no longer auto-migrated
+  on open. To upgrade a v1.x database, dump the rows with a v1.x install and
+  re-ingest them through the v2 API; or stay on the last release that shipped
+  the migration path (anything ≤ v2.6.1's predecessor).
+- The catalog helpers `check_legacy_sqlite_vec`, `get_legacy_vectors`, and
+  `drop_legacy_vec_table` are gone alongside the migration entry point.
+
+#### Out of scope
+
+- No external pub/sub for events — polling only.
+- No multi-master writer support; single-writer + many readers remains the
+  recommended topology.
+
+## [2.6.0] - 2026-05-06
+
+### Review pass 3 — final correctness/security pass before tag
+
+#### Critical fixes
+
+- **`UsearchIndex.save` lost-update race** — the `_dirty = False` clear was outside the `file_lock` window, so a concurrent `add()` between `os.replace()` and the dirty-flag clear could be silently overwritten. Moved inside `file_lock`.
+- **`UsearchIndex.save` data fsync on `O_RDONLY` fd** — `fsync(2)` on a read-only file descriptor has implementation-defined behavior on Linux (some kernels return `EBADF`, swallowed by the warning branch). Switched to `O_RDWR` so the data fsync is guaranteed.
+- **`_rebuild_index_locked` bare `conn.execute`** — replaced the bare `self.conn.execute("SELECT id FROM ...")` with the new `CatalogManager.list_all_ids()`, which routes the read through `self._lock` instead of relying on RLock re-entrancy from a single caller.
+- **PBKDF2 iteration bump** — raised from 480 000 → 600 000 to match the OWASP 2024 minimum for PBKDF2-HMAC-SHA256.
+- **AES-GCM AAD now binds the v1 header** — `encrypt_file` / `decrypt_file` pass the magic+version bytes as `associated_data`, so any tampering with the header (including downgrade attempts) fails authentication instead of silently succeeding.
+- **Bounded normalize-key cache** — `_NORMALIZE_KEY_CACHE` is now an LRU capped at 64 entries, serialized by a `threading.Lock`. Long-running multi-tenant processes no longer leak derived key material indefinitely.
+- **LlamaIndex `delete()` no longer swallows `sqlite3.DatabaseError`** — narrowed the exception in the metadata-fallback path to `(TypeError, NotImplementedError)`. A locked DB, closed connection, or schema mismatch now propagates to the caller instead of becoming a silent no-op.
+- **Hybrid-search RRF rank symmetry** — vector candidates now use the original HNSW position as their RRF rank (via `enumerate(vector_keys_list)`), matching how keyword candidates use raw BM25 position. Previously, a metadata filter that rejected vector candidates inflated surviving vector scores relative to keyword scores, corrupting result ordering.
+- **`add_documents` FTS sentinel guard** — added a defense-in-depth check that raises `RuntimeError` if any `-1` sentinel rowid remains in `real_ids` before the FTS upsert. Prevents a hypothetical retry-loop interaction from corrupting the FTS index with rowid `-1`.
+
+#### Important fixes
+
+- **`delete_collection` TOCTOU** — moved the `list_collections()` existence check inside the `with self._lock:` block so two concurrent `delete_collection(name)` calls cannot both pass the check; the second now sees a clean `KeyError` instead of a SQLite error.
+- **Salt sidecar `O_EXCL` guard** — `_resolve_salt(create_if_missing=True)` now creates the sidecar with `O_CREAT | O_EXCL`. If two processes race, the loser reads the winner's salt; if a sidecar already exists out-of-band, it is preserved instead of being clobbered (which would have rendered an existing DB unreadable).
+- **`encrypt_index_file` v0→v1 sidecar migration** — re-encrypting a legacy v0 blob (no sidecar) now creates a fresh sidecar, completing the migration path to per-DB salts. Previously, `is_first_encryption` was keyed on `.enc` presence rather than `.salt` presence.
+- **LlamaIndex legacy-collection warning** — `SimpleVecDBLlamaStore.__init__` now emits a one-shot `DeprecationWarning` when it detects rows lacking `_simplevecdb_node_id`, telling the operator to call `migrate_node_id_metadata()` and noting the inherent limitation that pre-2.6 rows can only be stamped with `str(doc_id)` (the original LlamaIndex node ids were never persisted).
+- **INT8 quantization range break softened** — instead of raising `ValueError` on `max(|x|) > 1.0 + 1e-5`, the strategy now emits a one-shot `DeprecationWarning` and clips. Restores backwards compatibility for callers that relied on the prior silent-clip behavior.
+- **`scripts/check_version_sync.py` now validates `CHANGELOG.md`** — the hook fails if the latest CHANGELOG entry header does not match `pyproject.toml`'s version, preventing a release from shipping with a stale changelog.
+
+#### Test coverage added (review pass 3 gaps)
+
+- `tests/unit/test_v26_review_pass_3.py` — covers parent-directory fsync on save, `.tmp` cleanup on save failure, `db._lock is catalog._lock` shared-RLock identity, adversarial inputs to `_validate_table_name`, hybrid-search RRF rank symmetry under filter, and same-text-different-id deduplication.
+- `tests/unit/test_v26_encryption_review_pass_3.py` — covers nonce uniqueness across saves, wrong-key decrypt does not create the output file, AAD-bound header tampering fails authentication, salt sidecar O_EXCL preservation, and v0→v1 migration round-trip.
+- `tests/unit/integrations/test_llamaindex_review_pass_3.py` — covers the `add → query` round-trip preserving the original LlamaIndex node id, end-to-end migration-then-delete on v2.5-shaped data, the legacy-collection `DeprecationWarning` at `__init__` time, and that `sqlite3.DatabaseError` from the metadata-fallback path now propagates instead of being swallowed.
+
+### Fixed (concurrency & durability)
+
+- **Atomic `UsearchIndex.save`** — now writes to a sibling `.tmp`, fsyncs, then `os.replace()`s onto the live path and fsyncs the parent directory. A crash mid-save can no longer corrupt the only copy of the index. Also moved the `_dirty` short-circuit inside `_write_lock` so a concurrent `add` cannot have its dirty flag silently cleared.
+- **Atomic `rebuild_index`** — builds the new index at a sibling `.rebuild` path and atomically swaps it onto the live path; the old index remains the canonical copy until the swap succeeds.
+- **Atomic encrypted save** — `encrypt_file` / `decrypt_file` now write to a sibling `.tmp`, fsync, set mode `0o600`, then `os.replace()`. `encrypt_index_file` only unlinks the plaintext after the encrypted output is durably on disk. A torn write can no longer leave the index unrecoverable.
+- **`VectorDB`-level `RLock`** — a single re-entrant lock now serializes the `_collections` cache (no more check-then-insert TOCTOU on `collection()`) and is shared with every `CatalogManager` so all `with self.conn:` blocks across collections cannot interleave on the shared `sqlite3.Connection`. Reads remain lock-free at the SQLite level via WAL.
+- **`AsyncVectorDB.close` drains** — switched from `executor.shutdown(wait=False)` to `wait=True` so in-flight pool tasks finish their cursors before the SQLite connection is closed. Pending (not-yet-started) work is still cancelled.
+- **`set_parent` cycle check is transactional** — descendant lookup and parent UPDATE now run inside the same `with self._lock, self.conn:` block, closing a TOCTOU window where a concurrent edge could form a cycle.
+- **Cluster persistence** — `_ensure_cluster_table`, `save_cluster_state`, `delete_cluster_state` now use `with self._lock, self.conn:` instead of bare `conn.commit()`; an exception during the execute is properly rolled back.
+- **`add_documents` ID recovery is correct under upsert** — replaced the `last_insert_rowid()` arithmetic (which silently returned wrong IDs for batches mixing explicit and `None` IDs because UPSERTs do not advance the auto-increment counter) with a single `INSERT … RETURNING id` for the auto-ID rows. Explicit-ID rows still take the upsert path.
+- **`delete_collection` closes cached indexes first** — any `VectorCollection` instances cached for the deleted name have their `UsearchIndex` closed before the file is unlinked, so a stale mmap view cannot race the unlink.
+
+### Changed
+
+- **`upsert_fts_rows` / `delete_fts_rows` are now `_upsert_fts_rows` / `_delete_fts_rows`** (private). The FTS shadow table must be updated inside the same transaction as the main table or it can desync on crash; the rename signals the contract.
+- **`get_legacy_vectors`, `drop_legacy_vec_table`** now validate the supplied table name via `_validate_table_name` before interpolating into SQL.
+
+### Added
+
+- **Declared `python-dotenv` dependency** — `simplevecdb.config` already imported and called `load_dotenv` at package import; the missing dependency would `ImportError` on a clean install of the base package without optional extras.
+
+### Fixed (correctness & quality)
+
+- **RRF deduplication keys by document ID, not text** — `hybrid_search` previously deduped by `doc.page_content`, silently merging two distinct documents that happened to share text into one inflated-score result.
+- **NaN/Inf guard at insert** — `add_texts` and `add_texts_streaming` reject non-finite vectors instead of feeding them to HNSW, which would produce undefined neighbours and could corrupt the graph.
+- **`normalize_l2` handles subnormals** — replaced the exact `norm == 0` compare with a `< 1e-12` check (matching the existing usearch_index guard); subnormal floats no longer produce wildly large normalized vectors.
+- **Silhouette score samples on large collections** — `silhouette_score` is O(n²); now caps the evaluation sample at `SILHOUETTE_MAX_SAMPLE = 10_000`. Large collections no longer OOM.
+- **MMR maintains the selected matrix incrementally** — replaced per-iteration `np.stack(selected_embs)` with `np.vstack` of a running matrix. O(k²·d) wasted allocations dropped to O(k·d).
+- **`_parse_bool_env` treats `KEY=` as unset** — empty strings now fall through to the default; previously they were truthy because `"".strip()` is not in the falsey set.
+- **LangChain async methods use `asyncio.to_thread`** — `aadd_texts` / `asimilarity_search` / `amax_marginal_relevance_search` no longer block the event loop.
+- **LlamaIndex `delete()` survives a process restart** — node IDs are persisted into document metadata under `_simplevecdb_node_id`; `delete()` falls back to a metadata query when the in-memory `_id_map` is empty.
+- **LlamaIndex query results carry stable node IDs** — replaced `str(hash(page_content))` (process-randomized, collision-prone) with the persisted `_simplevecdb_node_id`.
+- **`AsyncVectorDB.collection` accepts `store_embeddings`** — async callers can now enable embedding storage (required for `rebuild_index()`); previously they had no way to set it.
+
+### Security
+
+- **API key comparison uses `hmac.compare_digest`** — the prior `token not in allowed_keys` short-circuit leaked key prefixes via response time.
+- **SQLCipher PRAGMA key always uses the `x'hex'` form** — every key path now goes through `_normalize_key` first, eliminating string interpolation of user-supplied passphrase characters into a quoted PRAGMA argument.
+- **`is_database_encrypted` rejects zero-byte files** — previously a missing/empty DB looked like an unencrypted DB because `sqlite3.connect` would create a fresh one.
+
+### Changed (tooling)
+
+- **Ruff and mypy targets aligned with `requires-python>=3.10`** — both were `py312`, hiding 3.10/3.11 incompatibilities. Cleaned three resulting `F401` unused-import warnings (`signal` in models.py, `_batched` and `constants` re-imports).
+- **Pre-commit version-sync hook** — `__init__.py` derives `__version__` dynamically via `importlib.metadata`, so `check_version_sync.py` was failing on every commit looking for a literal `__version__ = "x.y.z"` line that does not exist. The hook now validates only `pyproject.toml`'s version field. `bump_version.py` similarly stops trying to rewrite `__init__.py` and uses an anchored regex to update only the canonical version field.
+
+### Security (2.6.0 final)
+
+- **Per-DB random PBKDF2 salt** — encrypted databases and index files now generate a random 16-byte salt at creation time, written to a `<resource>.salt` sidecar with mode `0o600`. The previous fixed `b"simplevecdb-sqlcipher-key"` salt let an attacker precompute one rainbow table that broke every simplevecdb installation with the same passphrase. Pre-2.6.0 encrypted resources keep working unchanged: when no sidecar exists, the loader falls back to the legacy fixed salt automatically.
+- **HuggingFace `repo_id` allowlist + `trust_remote_code=False`** — the embeddings server validates model names against a strict regex (`namespace/name` with `[A-Za-z0-9_.-]` only) before passing them to `snapshot_download` / `SentenceTransformer`, blocking path traversal and local-filesystem inputs. `SentenceTransformer` is constructed with `trust_remote_code=False` so a malicious model card cannot trigger arbitrary downloaded Python on load.
+- **CORS is opt-in** — the server no longer adds CORS middleware unless `EMBEDDING_SERVER_CORS_ORIGINS` is set. When the operator does set wildcard origins (`["*"]`), `allow_credentials` is forced off so the spec-violating wildcard-with-credentials combo can't be produced.
+
+### Migration helpers
+
+- **`SimpleVecDBLlamaStore.migrate_node_id_metadata()`** — backfills `_simplevecdb_node_id` for documents inserted before 2.6.0. Pre-2.6.0 versions did not persist the LlamaIndex node_id into metadata, so `delete()` could not find the right row after a process restart. Idempotent — already-stamped rows are skipped.
+
+### Added (hygiene & polish)
+
+- **`ClusterResult` and `ClusterTagCallback` exported from `simplevecdb`** — they were return/argument types of public methods but had no public import path; users had to reach into `simplevecdb.types`.
+- **`NullHandler` attached to the package's root logger** at import time, per the Python logging HOWTO. Idempotent — duplicate calls do not stack handlers.
+- **`SimpleVecDBLlamaStore.delete_nodes` raises `NotImplementedError`** when called with `filters`, instead of silently dropping the filter portion and pretending the deletion succeeded.
+- **Recursive CTE depth bound as a parameter** in `get_descendants` / `get_ancestors`. The previous f-string interpolation was safe due to `int()` coercion but is now one less line away from injection on a future refactor.
+- **`Config.from_env()` documented** as returning the import-time-frozen instance; setting env vars after import does not refresh.
+- **`ModelRegistry(allow_unlisted=...)` defaults to `False`** to match the secure-by-default config setting; programmatic instantiations no longer get an open registry by accident.
+- **`/v1/usage` returns aggregated totals when auth is disabled** instead of leaking the per-IP buckets to anyone who hits the endpoint.
+- **Server validates `EMBEDDING_SERVER_MAX_REQUEST_ITEMS <= _MAX_ENCODE_BATCH` at startup** so an out-of-range env var fails fast at boot rather than per request.
+- **`pyproject.toml` gains `[project.urls]`, `classifiers`, and `keywords`** for a useful PyPI listing.
+- **`.bandit` documents the B104 skip** and warns that any future `0.0.0.0` binding requires removing the skip.
+- **Encrypted file format now carries a 3-byte header** (`'SV' + version`) so future format changes are detectable. `decrypt_file` accepts both the new v1 format and the v0 (pre-2.6.0) format, so existing encrypted indexes still load without re-encryption.
+
+### Fixed (review pass 2)
+
+- **NaN/Inf rejection no longer leaves orphan catalog rows** — `add_texts` and `_process_streaming_batch` now validate vectors *before* the SQLite insert. Previously the catalog row committed first and a non-finite vector then raised, leaving rows visible via `get_documents_by_ids` but unreachable through similarity search.
+- **`VectorCollection.__repr__` no longer issues SQL** — the previous `count()` call would raise `ProgrammingError` after `close()`, breaking debuggers and exception formatters that auto-stringify objects. The 2.6.0 fix only covered `VectorDB.__repr__`.
+- **`EMBEDDING_SERVER_MAX_REQUEST_ITEMS` validation runs at module import** — the guard was previously inside `run_server()` and was bypassed under any non-CLI ASGI deployment (gunicorn, programmatic uvicorn).
+- **LlamaIndex empty-`node_id` path is atomic** — `SimpleVecDBLlamaStore.add` now generates a UUID for nodes that arrive without a `node_id` and stamps it into metadata *before* the row insert, so the metadata commit is in the same SQLite transaction as the catalog row. Previously a separate `UPDATE` followed `add_texts`; a crash in the gap left rows un-stampable and cross-restart `delete()` silently no-op'd.
+- **Catalog read paths serialize on `self._lock`** — `get_documents_by_ids`, `get_embeddings_by_ids`, `get_documents_and_embeddings_by_ids`, `find_ids_by_texts`, `find_ids_by_filter`, `keyword_search`, `count`, `get_all_docs_with_text`, `check_legacy_sqlite_vec`, `get_legacy_vectors`, `get_children`, `get_parent`, `get_descendants`, `get_ancestors`, `load_cluster_state`, `list_cluster_states`, and `VectorDB.list_collections` now acquire the connection-level lock around `conn.execute`. `sqlite3.Connection` is not safe for concurrent statement execution from multiple threads even under WAL.
+- **`rebuild_index` is fully serialized** — the entire fetch + build + swap now runs inside `with self._lock:` so concurrent `add` / `delete` cannot mutate the catalog mid-rebuild and produce a stale snapshot.
+- **`_ensure_cluster_table` double-checked under lock** — the `_cluster_table_ready` flag is now re-checked inside the lock and set inside the `with` block. Concurrent first-callers no longer both run the DDL.
+- **`utils.file_lock` opens via `os.open(O_CREAT | O_RDWR, 0o600)`** — no truncation of stale lock files from a crashed prior run, restricted permissions on the lock sentinel.
+
 ## [2.5.0] - 2026-04-07
 
 ### Added