citadeldb-langgraph 1.15.0__tar.gz

citadeldb_langgraph-1.15.0/.gitignore

@@ -0,0 +1,16 @@
+/target
+**/*.rs.bk
+*.swp
+*.swo
+*~
+.DS_Store
+site/public/
+site/static/wasm/*.wasm
+site/static/wasm/*.js
+/notes/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+/dist/
+packaging/*/dist/

citadeldb_langgraph-1.15.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: citadeldb-langgraph
+Version: 1.15.0
+Summary: LangGraph store backed by Citadel: encrypted at rest, semantic search, cryptographic deletes
+Project-URL: Homepage, https://citadeldb.dev
+Project-URL: Repository, https://github.com/yp3y5akh0v/citadel
+Author: Yuriy Peysakhov
+License-Expression: Apache-2.0
+Keywords: agent,encryption,langchain,langgraph,memory,store
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: citadeldb>=1.14
+Requires-Dist: langgraph>=0.2
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# citadeldb-langgraph
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) `BaseStore` backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and deletes
+that destroy the key rather than the row.
+
+```
+pip install citadeldb-langgraph
+```
+
+```python
+from citadeldb_langgraph import CitadelStore
+
+store = CitadelStore("memory.cdl", key="your-passphrase")
+
+store.put(("users", "alice"), "profile", {"city": "Berlin", "pet": "Mochi"})
+print(store.get(("users", "alice"), "profile").value)
+# {'city': 'Berlin', 'pet': 'Mochi'}
+```
+
+Pass it to a graph the same way as any other store:
+
+```python
+graph = builder.compile(store=store)
+```
+
+## Search is semantic
+
+`search` runs Citadel's hybrid recall (vector + keyword + recency), not a `LIKE`. The query
+below shares no words with the document it finds:
+
+```python
+store.put(("notes",), "n1", {"text": "the deployment failed because the disk was full"})
+store.put(("notes",), "n2", {"text": "lunch plans for friday"})
+
+store.search(("notes",), query="why did the release break?", limit=1)
+# [SearchItem(value={'text': 'the deployment failed because the disk was full'}, ...)]
+```
+
+## Deletes destroy the key
+
+Every value is sealed under its own key. Deleting destroys that key, so the bytes on disk
+stay unreadable instead of being marked deleted and living on in backups.
+
+```python
+store.delete(("users", "alice"), "profile")
+```
+
+`forget_namespace` does the same for a whole subtree, which is what a data-deletion request
+usually needs:
+
+```python
+store.forget_namespace(("users", "alice"))   # returns the number of values erased
+```
+
+## TTL
+
+```python
+store.put(("session",), "token", {"v": 1}, ttl=60.0)     # minutes
+store.get(("session",), "token", refresh_ttl=True)       # extends the lifetime
+```
+
+A refresh preserves both `created_at` and `updated_at`, so reading never looks like a write.
+
+## Notes
+
+Citadel is embedded and takes an exclusive lock on the file, so build **one** store per
+database and share it. Separate concerns with namespaces rather than with a second store.
+
+`MockEmbedder` is the default and needs no download, which is enough to build and test a
+graph. For production recall quality pass a real embedder:
+
+```python
+import citadeldb
+store = CitadelStore(
+    "memory.cdl",
+    key="your-passphrase",
+    embedder=citadeldb.CandleEmbedder("/path/to/e5-large", preset="e5_large"),
+)
+```
+
+## License
+
+Apache-2.0

citadeldb_langgraph-1.15.0/README.md

@@ -0,0 +1,84 @@
+# citadeldb-langgraph
+
+A [LangGraph](https://github.com/langchain-ai/langgraph) `BaseStore` backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and deletes
+that destroy the key rather than the row.
+
+```
+pip install citadeldb-langgraph
+```
+
+```python
+from citadeldb_langgraph import CitadelStore
+
+store = CitadelStore("memory.cdl", key="your-passphrase")
+
+store.put(("users", "alice"), "profile", {"city": "Berlin", "pet": "Mochi"})
+print(store.get(("users", "alice"), "profile").value)
+# {'city': 'Berlin', 'pet': 'Mochi'}
+```
+
+Pass it to a graph the same way as any other store:
+
+```python
+graph = builder.compile(store=store)
+```
+
+## Search is semantic
+
+`search` runs Citadel's hybrid recall (vector + keyword + recency), not a `LIKE`. The query
+below shares no words with the document it finds:
+
+```python
+store.put(("notes",), "n1", {"text": "the deployment failed because the disk was full"})
+store.put(("notes",), "n2", {"text": "lunch plans for friday"})
+
+store.search(("notes",), query="why did the release break?", limit=1)
+# [SearchItem(value={'text': 'the deployment failed because the disk was full'}, ...)]
+```
+
+## Deletes destroy the key
+
+Every value is sealed under its own key. Deleting destroys that key, so the bytes on disk
+stay unreadable instead of being marked deleted and living on in backups.
+
+```python
+store.delete(("users", "alice"), "profile")
+```
+
+`forget_namespace` does the same for a whole subtree, which is what a data-deletion request
+usually needs:
+
+```python
+store.forget_namespace(("users", "alice"))   # returns the number of values erased
+```
+
+## TTL
+
+```python
+store.put(("session",), "token", {"v": 1}, ttl=60.0)     # minutes
+store.get(("session",), "token", refresh_ttl=True)       # extends the lifetime
+```
+
+A refresh preserves both `created_at` and `updated_at`, so reading never looks like a write.
+
+## Notes
+
+Citadel is embedded and takes an exclusive lock on the file, so build **one** store per
+database and share it. Separate concerns with namespaces rather than with a second store.
+
+`MockEmbedder` is the default and needs no download, which is enough to build and test a
+graph. For production recall quality pass a real embedder:
+
+```python
+import citadeldb
+store = CitadelStore(
+    "memory.cdl",
+    key="your-passphrase",
+    embedder=citadeldb.CandleEmbedder("/path/to/e5-large", preset="e5_large"),
+)
+```
+
+## License
+
+Apache-2.0

citadeldb_langgraph-1.15.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "citadeldb-langgraph"
+dynamic = ["version"]
+description = "LangGraph store backed by Citadel: encrypted at rest, semantic search, cryptographic deletes"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Yuriy Peysakhov" }]
+keywords = ["langgraph", "langchain", "memory", "agent", "store", "encryption"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Database",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["citadeldb>=1.14", "langgraph>=0.2"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://citadeldb.dev"
+Repository = "https://github.com/yp3y5akh0v/citadel"
+
+# The version comes from the release tag, so it tracks the workspace with nothing to bump.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../..", tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$' }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citadeldb_langgraph"]

citadeldb_langgraph-1.15.0/src/citadeldb_langgraph/__init__.py

@@ -0,0 +1,12 @@
+"""A LangGraph store backed by Citadel: encrypted at rest, semantic search, real deletes."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .store import CitadelStore
+
+__all__ = ["CitadelStore", "__version__"]
+
+try:
+    __version__ = version("citadeldb-langgraph")
+except PackageNotFoundError:  # running from a source tree, never installed
+    __version__ = "0+unknown"

citadeldb_langgraph-1.15.0/src/citadeldb_langgraph/store.py

@@ -0,0 +1,330 @@
+"""CitadelStore: LangGraph's BaseStore over an encrypted Citadel region.
+
+`batch` and `abatch` are the only abstract methods; put/get/delete/search/list_namespaces are
+concrete helpers that build Ops and dispatch through them. A PutOp carrying `value=None` is
+LangGraph's delete.
+
+Two operations behave differently here than in any other store:
+  SearchOp with a query   hybrid vector + keyword recall rather than a SQL LIKE.
+  PutOp with value=None   the atom's key is destroyed, leaving unreadable ciphertext instead
+                          of a removed row.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+import citadeldb
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    Item,
+    ListNamespacesOp,
+    Op,
+    PutOp,
+    SearchItem,
+    SearchOp,
+    TTLConfig,
+)
+
+KIND = "kv"
+NS_KIND = "ns"
+_SEP = "\x1f"  # unit separator: illegal in a namespace element, so joins stay reversible
+
+
+def _join(namespace: tuple[str, ...]) -> str:
+    return _SEP.join(namespace)
+
+
+def _split(joined: str) -> tuple[str, ...]:
+    return tuple(joined.split(_SEP)) if joined else ()
+
+
+def _ancestors(namespace: tuple[str, ...]) -> list[str]:
+    """Every prefix of `namespace`, itself included.
+
+    JSONB containment tests array membership, so storing the prefixes makes
+    "everything under this namespace" an indexed lookup instead of a scan.
+    """
+    return [_join(namespace[: i + 1]) for i in range(len(namespace))]
+
+
+def _now() -> int:
+    return int(time.time() * 1_000_000)
+
+
+def _when(micros: int | None) -> datetime | None:
+    return datetime.fromtimestamp(micros / 1_000_000, tz=timezone.utc) if micros else None
+
+
+class CitadelStore(BaseStore):
+    """LangGraph store over one encrypted Citadel region.
+
+    Namespaces live in the atom payload rather than in separate regions, so a search can span
+    a namespace prefix in a single recall. Payload lookups ride Citadel's GIN index on
+    `payload`, so key access is indexed rather than scanned.
+    """
+
+    supports_ttl = True
+    ttl_config = TTLConfig(refresh_on_read=True, omit_expired=True)
+
+    def __init__(
+        self,
+        path: str,
+        key: str,
+        *,
+        region: str = "store",
+        embedder: Any | None = None,
+    ) -> None:
+        try:
+            self._db = citadeldb.connect(path, key=key, region_keys=True)
+        except citadeldb.OperationalError as e:
+            if "locked" not in str(e):
+                raise
+            raise RuntimeError(
+                f"{path} is already open in this process or another one. Citadel is embedded, "
+                f"so one handle owns the file: build a single CitadelStore and share it, and "
+                f"separate concerns with namespaces rather than with a second store."
+            ) from e
+        self._mem = self._db.memory()
+        self._region = region
+        try:
+            self._mem.create_encrypted_region(
+                region, embedder or citadeldb.MockEmbedder(dim=64)
+            )
+        except citadeldb.CitadelError:
+            pass  # region already exists from an earlier open
+
+    # ---- storage helpers --------------------------------------------------
+
+    def _find(self, namespace: tuple[str, ...], key: str):
+        """The atom holding (namespace, key). Served by the payload GIN index."""
+        hits = self._mem.fetch(
+            self._region,
+            KIND,
+            payload_filter={"ns": _join(namespace), "key": key},
+            limit=1,
+        )
+        return hits[0] if hits else None
+
+    def _namespace_has_keys(self, joined: str) -> bool:
+        return bool(
+            self._mem.fetch(self._region, KIND, payload_filter={"ns": joined}, limit=1)
+        )
+
+    def _register_namespace(self, joined: str) -> None:
+        """One marker atom per distinct namespace, so listing is O(namespaces)."""
+        if self._mem.fetch(
+            self._region, NS_KIND, payload_filter={"ns": joined}, limit=1
+        ):
+            return
+        self._mem.remember(
+            self._region, {"kind": NS_KIND, "text": joined or "/", "payload": {"ns": joined}}
+        )
+
+    def _retire_namespace(self, joined: str) -> None:
+        """Drop the marker once the namespace holds no keys."""
+        if self._namespace_has_keys(joined):
+            return
+        stale = self._mem.fetch(
+            self._region, NS_KIND, payload_filter={"ns": joined}, limit=8
+        )
+        if stale:
+            self._mem.forget(self._region, [h.id for h in stale])
+
+    def _write(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        value: dict[str, Any],
+        ttl: float | None,
+        created_at: int,
+        updated_at: int,
+    ) -> None:
+        joined = _join(namespace)
+        atom: dict[str, Any] = {
+            "kind": KIND,
+            # The value is the searchable text; keys and namespaces are not content.
+            "text": " ".join(str(v) for v in value.values()) or json.dumps(value),
+            "payload": {
+                "ns": joined,
+                # Prefix erasure and prefix search both filter on this.
+                "anc": _ancestors(namespace),
+                "key": key,
+                "value": value,
+                "created_at": created_at,
+                "updated_at": updated_at,
+                # Kept so a read can re-apply the same lifetime on refresh.
+                "ttl": ttl,
+            },
+        }
+        if ttl is not None:
+            atom["expires_at"] = int(time.time() * 1_000_000 + ttl * 60_000_000)
+        self._mem.remember(self._region, atom)
+        self._register_namespace(joined)
+
+    def _refresh_ttl(self, hit) -> None:
+        """Re-apply the stored lifetime. Expiry cannot be moved in place, so the atom is
+        rewritten; both timestamps are carried over because a read must not look like a write.
+        """
+        p = hit.payload
+        if p.get("ttl") is None:
+            return
+        self._mem.forget(self._region, [hit.id])
+        self._write(
+            _split(p["ns"]),
+            p["key"],
+            p["value"],
+            p["ttl"],
+            p["created_at"],
+            p["updated_at"],
+        )
+
+    # ---- projection -------------------------------------------------------
+
+    @staticmethod
+    def _item(hit) -> Item:
+        p = hit.payload
+        return Item(
+            value=p["value"],
+            key=p["key"],
+            namespace=_split(p["ns"]),
+            created_at=_when(p.get("created_at")),
+            updated_at=_when(p.get("updated_at")),
+        )
+
+    @staticmethod
+    def _search_item(hit) -> SearchItem:
+        p = hit.payload
+        return SearchItem(
+            namespace=_split(p["ns"]),
+            key=p["key"],
+            value=p["value"],
+            created_at=_when(p.get("created_at")),
+            updated_at=_when(p.get("updated_at")),
+            score=getattr(hit, "score", None),
+        )
+
+    @staticmethod
+    def _matches(ns: tuple[str, ...], conditions) -> bool:
+        for c in conditions or ():
+            path = tuple(c.path)
+            if c.match_type == "prefix":
+                seg = ns[: len(path)]
+            else:
+                seg = ns[-len(path) :] if len(path) <= len(ns) else ns
+            if len(seg) != len(path):
+                return False
+            # "*" matches any single element.
+            if any(p != "*" and p != s for p, s in zip(path, seg)):
+                return False
+        return True
+
+    def _under(self, ns: str, prefix: str) -> bool:
+        return not prefix or ns == prefix or ns.startswith(prefix + _SEP)
+
+    # ---- the abstract surface --------------------------------------------
+
+    def batch(self, ops: Iterable[Op]) -> list[Any]:
+        results: list[Any] = []
+        for op in ops:
+            if isinstance(op, GetOp):
+                hit = self._find(op.namespace, op.key)
+                if hit and op.refresh_ttl:
+                    self._refresh_ttl(hit)
+                results.append(self._item(hit) if hit else None)
+
+            elif isinstance(op, PutOp):
+                existing = self._find(op.namespace, op.key)
+                joined = _join(op.namespace)
+                if op.value is None:
+                    if existing:
+                        self._mem.forget(self._region, [existing.id])
+                        self._retire_namespace(joined)
+                    results.append(None)
+                    continue
+                now = _now()
+                created = existing.payload["created_at"] if existing else now
+                if existing:
+                    self._mem.forget(self._region, [existing.id])
+                self._write(op.namespace, op.key, op.value, op.ttl, created, now)
+                results.append(None)
+
+            elif isinstance(op, SearchOp):
+                prefix = _join(op.namespace_prefix)
+                want = op.limit + op.offset
+                if op.query:
+                    # Recall ranks the whole region, so the namespace pass happens below;
+                    # over-fetch because that pass and the filter both discard rows.
+                    hits = self._mem.recall(
+                        self._region, text=op.query, k=max(want * 4, 32), kinds=[KIND]
+                    )
+                else:
+                    # No query: the index can do the namespace restriction directly.
+                    hits = self._mem.fetch(
+                        self._region,
+                        KIND,
+                        payload_filter={"anc": [prefix]} if prefix else None,
+                        limit=max(want * 4, 32),
+                    )
+                out: list[SearchItem] = []
+                for h in hits:
+                    p = h.payload
+                    if not self._under(p["ns"], prefix):
+                        continue
+                    if op.filter and any(
+                        p["value"].get(k) != v for k, v in op.filter.items()
+                    ):
+                        continue
+                    if op.refresh_ttl:
+                        self._refresh_ttl(h)
+                    out.append(self._search_item(h))
+                results.append(out[op.offset : op.offset + op.limit])
+
+            elif isinstance(op, ListNamespacesOp):
+                seen: set[tuple[str, ...]] = set()
+                # Marker atoms only, so this is O(namespaces) rather than O(keys). Each is
+                # verified against a live key, so a crash mid-delete self-heals on read.
+                for marker in self._mem.fetch(self._region, NS_KIND, limit=100_000):
+                    joined = marker.payload["ns"]
+                    if not self._namespace_has_keys(joined):
+                        continue
+                    ns = _split(joined)
+                    if not self._matches(ns, op.match_conditions):
+                        continue
+                    seen.add(ns[: op.max_depth] if op.max_depth is not None else ns)
+                ordered = sorted(seen)
+                results.append(ordered[op.offset : op.offset + op.limit])
+
+            else:
+                raise NotImplementedError(f"unsupported op: {type(op).__name__}")
+        return results
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Any]:
+        # The bindings are sync; a worker thread keeps the event loop free.
+        return await asyncio.to_thread(self.batch, list(ops))
+
+    # ---- beyond BaseStore -------------------------------------------------
+
+    def forget_namespace(self, namespace: tuple[str, ...], *, prefix: bool = True) -> int:
+        """Destroy every key under `namespace`, returning the number of atoms erased.
+
+        The point of a per-user namespace: one call makes that user's memories unreadable
+        rather than merely unlisted. Selection rides the payload index in both modes.
+        """
+        joined = _join(namespace)
+        # Containment on the ancestor array selects the whole subtree; on `ns` it selects
+        # exactly one namespace. Either way the index does the work.
+        criterion = {"anc": [joined]} if prefix else {"ns": joined}
+        doomed = self._mem.fetch(
+            self._region, KIND, payload_filter=criterion, limit=100_000
+        )
+        if not doomed:
+            return 0
+        erased = self._mem.forget(self._region, [h.id for h in doomed]).erased_count
+        for gone in {h.payload["ns"] for h in doomed}:
+            self._retire_namespace(gone)
+        return erased

citadeldb_langgraph-1.15.0/tests/test_store.py

@@ -0,0 +1,170 @@
+import time
+
+import pytest
+from langgraph.store.base import ListNamespacesOp, MatchCondition
+
+from citadeldb_langgraph import CitadelStore
+
+
+@pytest.fixture(scope="module")
+def store(tmp_path_factory):
+    # Citadel takes an exclusive lock, so the whole module shares one handle.
+    path = tmp_path_factory.mktemp("store") / "s.cdl"
+    return CitadelStore(str(path), key="test-passphrase")
+
+
+def test_put_get_roundtrip(store):
+    store.put(("users", "alice"), "profile", {"city": "Berlin", "pet": "Mochi"})
+    item = store.get(("users", "alice"), "profile")
+    assert item.value == {"city": "Berlin", "pet": "Mochi"}
+    assert item.namespace == ("users", "alice")
+    assert item.key == "profile"
+    assert item.created_at is not None
+
+
+def test_missing_key_is_none(store):
+    assert store.get(("users", "nobody"), "profile") is None
+
+
+def test_overwrite_preserves_created_at(store):
+    store.put(("ow",), "k", {"n": 1})
+    first = store.get(("ow",), "k")
+    time.sleep(0.01)
+    store.put(("ow",), "k", {"n": 2})
+    second = store.get(("ow",), "k")
+    assert second.value == {"n": 2}
+    assert second.created_at == first.created_at
+    assert second.updated_at >= first.updated_at
+
+
+def test_overwrite_does_not_duplicate(store):
+    store.put(("dup",), "k", {"n": 1})
+    store.put(("dup",), "k", {"n": 2})
+    assert len(store.search(("dup",), limit=10)) == 1
+
+
+def test_search_is_semantic(store):
+    store.put(("notes",), "n1", {"text": "the deployment failed because the disk was full"})
+    store.put(("notes",), "n2", {"text": "lunch plans for friday"})
+    # The query shares no words with the match, so a LIKE would return nothing.
+    hits = store.search(("notes",), query="why did the release break?", limit=2)
+    assert hits[0].value["text"].startswith("the deployment failed")
+
+
+def test_search_descends_into_child_namespaces(store):
+    store.put(("tree",), "a", {"v": 1})
+    store.put(("tree", "child"), "b", {"v": 2})
+    assert len(store.search(("tree",), limit=10)) == 2
+    assert len(store.search(("tree", "child"), limit=10)) == 1
+
+
+def test_search_prefix_is_not_a_string_prefix(store):
+    """('org',) must not match 'orgX', which a string-prefix filter would."""
+    store.put(("org", "acme"), "k", {"v": 1})
+    store.put(("orgX",), "k", {"v": 2})
+    found = {h.namespace for h in store.search(("org",), limit=10)}
+    assert ("org", "acme") in found
+    assert ("orgX",) not in found
+
+
+def test_search_filter(store):
+    store.put(("filt",), "a", {"kind": "x", "n": 1})
+    store.put(("filt",), "b", {"kind": "y", "n": 2})
+    hits = store.search(("filt",), filter={"kind": "y"}, limit=5)
+    assert [h.value["n"] for h in hits] == [2]
+
+
+def test_namespace_element_may_contain_a_slash(store):
+    store.put(("a/b",), "k", {"v": "slash"})
+    assert store.get(("a/b",), "k").value["v"] == "slash"
+    assert store.get(("a", "b"), "k") is None
+
+
+def test_list_namespaces(store):
+    store.put(("ln", "x"), "k", {"v": 1})
+    assert ("ln", "x") in store.list_namespaces()
+    assert ("ln",) in store.list_namespaces(max_depth=1)
+
+
+def test_list_namespaces_prefix_match(store):
+    store.put(("mc", "one"), "k", {"v": 1})
+    got = store.batch(
+        [
+            ListNamespacesOp(
+                match_conditions=(MatchCondition(match_type="prefix", path=("mc",)),),
+                max_depth=None,
+                limit=10,
+                offset=0,
+            )
+        ]
+    )[0]
+    assert got and all(ns[0] == "mc" for ns in got)
+
+
+def test_delete_removes_only_its_key(store):
+    store.put(("del", "keep"), "k", {"v": 1})
+    store.put(("del", "drop"), "k", {"v": 2})
+    store.delete(("del", "drop"), "k")
+    assert store.get(("del", "drop"), "k") is None
+    assert store.get(("del", "keep"), "k") is not None
+
+
+def test_emptied_namespace_stops_being_listed(store):
+    store.put(("gone",), "k", {"v": 1})
+    assert ("gone",) in store.list_namespaces()
+    store.delete(("gone",), "k")
+    assert ("gone",) not in store.list_namespaces()
+
+
+def test_ttl_refresh_is_not_a_write(store):
+    store.put(("ttl",), "k", {"v": 1}, ttl=60.0)
+    before = store.get(("ttl",), "k")
+    time.sleep(0.02)
+    after = store.get(("ttl",), "k", refresh_ttl=True)
+    assert after.created_at == before.created_at
+    assert after.updated_at == before.updated_at
+    assert after.value == {"v": 1}
+
+
+def test_ttl_config_declares_refresh(store):
+    assert CitadelStore.supports_ttl is True
+    assert CitadelStore.ttl_config["refresh_on_read"] is True
+
+
+def test_forget_namespace_erases_the_subtree(store):
+    store.put(("gdpr", "u9"), "a", {"v": 1})
+    store.put(("gdpr", "u9"), "b", {"v": 2})
+    store.put(("gdpr", "u8"), "a", {"v": 3})
+    assert store.forget_namespace(("gdpr", "u9")) == 2
+    assert store.get(("gdpr", "u9"), "a") is None
+    assert store.get(("gdpr", "u8"), "a") is not None
+    assert ("gdpr", "u9") not in store.list_namespaces()
+
+
+def test_forget_namespace_exact_spares_children(store):
+    store.put(("ex",), "a", {"v": 1})
+    store.put(("ex", "child"), "b", {"v": 2})
+    assert store.forget_namespace(("ex",), prefix=False) == 1
+    assert store.get(("ex", "child"), "b") is not None
+
+
+def test_second_handle_explains_the_lock(store, tmp_path):
+    path = str(tmp_path / "locked.cdl")
+    first = CitadelStore(path, key="pw")
+    with pytest.raises(RuntimeError, match="one handle owns the file"):
+        CitadelStore(path, key="pw")
+    assert first is not None
+
+
+def test_async_surface(store):
+    """abatch runs the sync batch on a worker thread, so the loop is never blocked."""
+    import asyncio
+
+    async def main():
+        await store.aput(("async",), "k", {"v": 1})
+        assert (await store.aget(("async",), "k")).value == {"v": 1}
+        assert len(await store.asearch(("async",), query="v", limit=1)) == 1
+        await store.adelete(("async",), "k")
+        assert await store.aget(("async",), "k") is None
+
+    asyncio.run(main())