reactifact 0.15.2__tar.gz → 0.16.0__tar.gz

{reactifact-0.15.2/reactifact.egg-info → reactifact-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.15.2
+Version: 0.16.0
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact
@@ -323,6 +323,23 @@ by hand. Run it yourself: `uv run python -m examples.ledger.main`.
 - **Viz & CLI** — Mermaid `blueprint`/`context_to_mermaid`/`trace_to_mermaid`;
   `reactifact` with `graph`/`context`/`trace`/`replay`/`branch`.
 
+## Agent Skills
+
+reactifact ships official **Agent Skills** — reusable instructions that teach a
+coding agent (Claude Code, Cursor, Codex, Copilot, …) how to build *with*
+reactifact. They're bundled with the package, so they always match your version:
+
+```bash
+python -m reactifact skills list                    # what is available
+python -m reactifact skills install                 # -> .agents/skills/
+python -m reactifact skills install --target both    # + .claude/skills/
+```
+
+Skills: `reactifact` (mental model), `reactifact-agents`, `reactifact-llm`,
+`reactifact-rag`, `reactifact-testing`, `reactifact-eval`,
+`reactifact-observability`, `reactifact-from-langchain` — see
+[Agent skills](docs/en/skills.md).
+
 ## Run a demo
 
 Offline-capable, no API keys required (deterministic fallbacks):

{reactifact-0.15.2 → reactifact-0.16.0}/README.md

@@ -277,6 +277,23 @@ by hand. Run it yourself: `uv run python -m examples.ledger.main`.
 - **Viz & CLI** — Mermaid `blueprint`/`context_to_mermaid`/`trace_to_mermaid`;
   `reactifact` with `graph`/`context`/`trace`/`replay`/`branch`.
 
+## Agent Skills
+
+reactifact ships official **Agent Skills** — reusable instructions that teach a
+coding agent (Claude Code, Cursor, Codex, Copilot, …) how to build *with*
+reactifact. They're bundled with the package, so they always match your version:
+
+```bash
+python -m reactifact skills list                    # what is available
+python -m reactifact skills install                 # -> .agents/skills/
+python -m reactifact skills install --target both    # + .claude/skills/
+```
+
+Skills: `reactifact` (mental model), `reactifact-agents`, `reactifact-llm`,
+`reactifact-rag`, `reactifact-testing`, `reactifact-eval`,
+`reactifact-observability`, `reactifact-from-langchain` — see
+[Agent skills](docs/en/skills.md).
+
 ## Run a demo
 
 Offline-capable, no API keys required (deterministic fallbacks):

{reactifact-0.15.2 → reactifact-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.15.2"
+version = "0.16.0"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/__init__.py

@@ -47,11 +47,11 @@ from .request import current_request
 from .resources import ResourceKey, ResourceScope, RuntimeResources
 from .runtime import Runtime
 from .session import Session, SessionStore
-from .tools import FunctionTool, Tool, ToolOutput, tool
+from .tools import FunctionTool, Tool, ToolError, ToolOutput, tool
 from .triggers import Trigger
 from .types import register as register_type
 
-__version__ = "0.15.2"
+__version__ = "0.16.0"
 
 __all__ = [
     "Agent",
@@ -92,6 +92,7 @@ __all__ = [
     "Session",
     "SessionStore",
     "Tool",
+    "ToolError",
     "ToolOutput",
     "Trigger",
     "Unlink",

reactifact-0.16.0/reactifact/_persistence.py

@@ -0,0 +1,78 @@
+"""Internal: append-only persistence helpers shared by session/branch stores.
+
+Not public API — `SessionStore`/`BranchStore` use these when the backend
+implements `AppendBackend` (SQLite/Postgres). A save writes a full snapshot on
+the first save, after a compaction, or after a rollback; otherwise it appends
+only the new commits plus the current pending-event queue.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .checkpoints import AppendBackend
+from .commit import Commit
+from .context import Context
+from .events import Event
+
+#: Default number of appended saves before a snapshot rewrite. Bounds load
+#: replay (and log size) for long-lived sessions without an explicit
+#: `context.compact()`.
+DEFAULT_COMPACT_EVERY = 100
+
+
+async def save_append(
+    backend: AppendBackend,
+    key: str,
+    context: Context,
+    *,
+    compact_every: int | None = DEFAULT_COMPACT_EVERY,
+) -> None:
+    persisted, persisted_compacted = context.persisted_state(key)
+    needs_snapshot = (
+        persisted < 0
+        or persisted > context.version
+        or context.compacted_at > persisted_compacted
+        or await backend.get(key) is None
+    )
+    if (
+        not needs_snapshot
+        and compact_every is not None
+        and await backend.entry_count(key) + 1 >= compact_every
+    ):
+        needs_snapshot = True
+    if needs_snapshot:
+        await backend.set(key, cast(dict[str, Any], context.to_dict()))
+        await backend.clear_entries(key)
+        context.mark_persisted(key=key)
+        return
+    new_commits = [
+        commit.to_dict()
+        for commit in context.commit_log()
+        if (commit.context_version or 0) > persisted
+    ]
+    await backend.append(
+        key,
+        {
+            "commits": new_commits,
+            "events": [event.to_dict() for event in context.pending_events()],
+        },
+    )
+    context.mark_persisted(key=key)
+
+
+async def load_append(backend: AppendBackend, key: str) -> Context | None:
+    snapshot = await backend.get(key)
+    if snapshot is None:
+        return None
+    context = Context.from_dict(snapshot)
+    for entry in await backend.entries(key):
+        for commit_dict in entry.get("commits", []):
+            context.apply_commit(Commit.from_dict(commit_dict), reindex=False)
+        if "events" in entry:
+            context.replace_events(
+                [Event.from_dict(event) for event in entry["events"]]
+            )
+    context.rebuild_indices()
+    context.mark_persisted(key=key)
+    return context

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/agents.py

@@ -13,6 +13,7 @@ from .effects import current_effects
 from .events import Event, EventType
 from .patches import Patch
 from .produce import Produce, ProduceCall
+from .tools import reset_current_produce, set_current_produce
 from .triggers import Trigger
 
 #: Per-task log of the produces that ran for the current agent execution:
@@ -190,9 +191,11 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
             call = ProduceCall(
                 context=context, inputs=inputs, event=event, trigger=trigger
             )
+            produce_token = set_current_produce(p.name)
             try:
                 await p.produce(call)
             finally:
+                reset_current_produce(produce_token)
                 # Record the produce even when it raises — a failing produce is
                 # exactly what a trace should show (the span is then the error
                 # span, with this produce's partial operations/latency).

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/audit.py

@@ -47,10 +47,30 @@ DEFAULT_RELATIONS: tuple[str, ...] = (
 )
 
 
+def _transient_fields(model: type[BaseModel]) -> set[str]:
+    """Field names a model declares as transactional *envelope*, not state.
+
+    A model lists them as ``transient_fields: ClassVar[frozenset[str]]``
+    (e.g. `PendingAction.dispatched_at`, `PendingQuestion.resolved_at`).
+    Wall-clock transitions are excluded from the content hash so an otherwise
+    identical state doesn't hash differently run to run — the *fact* of the
+    transition stays hashed (`status`/`resolution`); only its timestamp drops.
+    """
+    names = getattr(model, "transient_fields", ())
+    return set(names) if names else set()
+
+
 def _canonical(value: Any) -> str:
-    """Canonical JSON for hashing (sorted keys; pydantic models dumped)."""
+    """Canonical JSON for hashing (sorted keys; pydantic models dumped).
+
+    A model's `transient_fields` are dropped before hashing — envelope, not
+    state. Everything else is serialized exactly as before, so a state with no
+    transient fields hashes the same as it always did.
+    """
     if isinstance(value, BaseModel):
-        payload: Any = value.model_dump(mode="json")
+        payload: Any = value.model_dump(
+            mode="json", exclude=_transient_fields(type(value)) or None
+        )
     else:
         payload = value
     return json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str)

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/branching.py

@@ -29,8 +29,9 @@ from typing import Any
 
 from pydantic import BaseModel
 
+from ._persistence import DEFAULT_COMPACT_EVERY, load_append, save_append
 from .artifacts import Artifact
-from .checkpoints import KVBackend
+from .checkpoints import AppendBackend, KVBackend
 from .commit import Commit
 from .context import Context
 from .interrupt import PendingAction
@@ -242,10 +243,22 @@ def merge_contexts(
 
 
 class BranchStore:
-    """Persists named branches (`branch:<session>:<name>`) over a KV backend."""
+    """Persists named branches (`branch:<session>:<name>`) over a KV backend.
 
-    def __init__(self, backend: KVBackend):
+    With an `AppendBackend` (SQLite/Postgres) branches use the same
+    snapshot + append-only commit log as sessions, keyed per branch name.
+    """
+
+    def __init__(
+        self,
+        backend: KVBackend,
+        *,
+        compact_every: int | None = DEFAULT_COMPACT_EVERY,
+    ):
+        if compact_every is not None and compact_every < 1:
+            raise ValueError("compact_every must be >= 1 or None")
         self.backend = backend
+        self.compact_every = compact_every
 
     @staticmethod
     def _key(session_id: str, name: str) -> str:
@@ -255,11 +268,21 @@ class BranchStore:
         self, context: Context, *, session_id: str, name: str
     ) -> None:
         """Saves a branch (including its fork base snapshot, §40)."""
-        await context.to_kv(self.backend, self._key(session_id, name))
+        key = self._key(session_id, name)
+        if isinstance(self.backend, AppendBackend):
+            await save_append(
+                self.backend, key, context, compact_every=self.compact_every
+            )
+            return
+        await context.to_kv(self.backend, key)
+        context.mark_persisted(key=key)
 
     async def load_branch(self, session_id: str, name: str) -> Context | None:
         """Loads a branch, or None if it does not exist."""
-        return await Context.from_kv(self.backend, self._key(session_id, name))
+        key = self._key(session_id, name)
+        if isinstance(self.backend, AppendBackend):
+            return await load_append(self.backend, key)
+        return await Context.from_kv(self.backend, key)
 
     async def list_branches(self, session_id: str) -> list[str]:
         prefix = f"branch:{session_id}:"

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/chat.py

@@ -37,6 +37,7 @@ from .budget import Budget
 from .consume import Consume
 from .context import Context
 from .events import Event
+from .request import reset_request, set_request
 from .resources import RuntimeResources
 from .runtime import Dispatcher, DispatchErrorHandler, Runtime
 from .session import Session, SessionStore
@@ -101,8 +102,12 @@ async def run_message(
     (devops-style clarify) pass their own. Also accepts the 3-arg shape
     `create_message(ctx, text, session_id) -> msg_id` for a hook that needs
     the current turn's `session_id` (e.g. to stamp it onto the created
-    artifact) — detected from the callable's own arity, so the 2-arg shape
-    keeps working unchanged.
+    artifact) and the 4-arg shape `create_message(ctx, text, session_id,
+    request) -> msg_id` for per-request metadata (a category, tenant, user)
+    — detected from the callable's own arity, so the 2-arg shape keeps
+    working unchanged. During the hook `ctx.request` is the same mapping
+    passed as `request=`, so a 2/3-arg hook can read it too without a
+    `ContextVar` of its own.
 
     `status_kinds` selects which progress event kinds are forwarded as `status`
     frames (default: only `status`; e.g. tool-announcing demos also forward
@@ -115,10 +120,17 @@ async def run_message(
     forwarded = set(status_kinds)
     ctx = runtime.context
     try:
-        if create_message is not None:
-            msg_id = _call_create_message(create_message, ctx, text, session_id)
-        else:
-            msg_id = ctx.create(user_message(text=text, session_id=session_id)).id
+        token = set_request(request) if request is not None else None
+        try:
+            if create_message is not None:
+                msg_id = _call_create_message(
+                    create_message, ctx, text, session_id, request
+                )
+            else:
+                msg_id = ctx.create(user_message(text=text, session_id=session_id)).id
+        finally:
+            if token is not None:
+                reset_request(token)
     except Exception:
         logger.exception("chat.run_message: failed to enter the turn")
         yield ChatEvent(
@@ -217,11 +229,20 @@ def _resolve_with_session(value: Any, session_id: str) -> Any:
 
 
 def _call_create_message(
-    create_message: Callable[..., str], ctx: Context, text: str, session_id: str
+    create_message: Callable[..., str],
+    ctx: Context,
+    text: str,
+    session_id: str,
+    request: Mapping[str, Any] | None = None,
 ) -> str:
-    """Calls `create_message` with `session_id` appended when it declares a
-    third parameter for it (`(ctx, text, session_id) -> msg_id`), alongside
-    the pre-existing two-arg shape (`(ctx, text) -> msg_id`)."""
+    """Calls `create_message` with the widest shape it declares.
+
+    Four params get `(ctx, text, session_id, request)`, three get
+    `(ctx, text, session_id)`, and the pre-existing two-arg shape gets
+    `(ctx, text)`. Detected from arity so old hooks keep working unchanged.
+    """
+    if _accepts_arg(create_message, 4):
+        return create_message(ctx, text, session_id, request)
     if _accepts_arg(create_message, 3):
         return create_message(ctx, text, session_id)
     return create_message(ctx, text)
@@ -274,9 +295,16 @@ class ChatMemory:
     `message_type` (needed for `keep`/`summarize`) is any model with
     `role`/`text`; for compaction-only it isn't needed at all, so
     `ChatMemory(compact_commits=…)` is a complete policy on its own.
+
+    `message_types` (or a sequence passed as `message_type`) bounds a
+    heterogeneous conversation — the natural `UserQuery`/`Answer` pair, or a
+    marker base like `ChatMessage` whose concrete types inherit from it. The
+    memory agent wakes on every listed type (and, for a marker base, on its
+    subclasses), so one window covers the whole thread.
     """
 
-    message_type: type[BaseModel] | None = None
+    message_type: type[BaseModel] | Sequence[type[BaseModel]] | None = None
+    message_types: Sequence[type[BaseModel]] | None = None
     keep: int | None = None
     summarize: Callable[[Context, str, list[Any]], Awaitable[str | None]] | None = None
     summary_type: type[BaseModel] | None = None
@@ -284,6 +312,20 @@ class ChatMemory:
     digest_id: str = "digest"
     compact_commits: int | None = None
 
+    def resolved_message_types(self) -> tuple[type[BaseModel], ...]:
+        """The message types to bound, normalized from the two fields."""
+        if self.message_types is not None:
+            types = tuple(self.message_types)
+        elif self.message_type is None:
+            return ()
+        elif isinstance(self.message_type, type):
+            types = (self.message_type,)
+        else:
+            types = tuple(self.message_type)
+        if not types:
+            raise ValueError("message_type must name at least one artifact type")
+        return types
+
 
 class ChatAssistant:
     """Session-persisted chat over the runtime, for the canonical contract.
@@ -298,7 +340,9 @@ class ChatAssistant:
     its provider's HTTP client doesn't leak. Pass a plain `RuntimeResources`
     instance instead when you want one shared, long-lived provider across
     turns/sessions — that instance is never closed automatically; close it
-    yourself at real shutdown.
+    yourself at real shutdown. It is safe to share: the runtime installs
+    per-turn budget/tracing wrappers on a shallow copy, so concurrent turns do
+    not mutate the shared instance.
 
     `session_save_policy=` passes straight through to `Runtime` — `"per_turn"`
     trades finer crash-resilience granularity (a save at every generation
@@ -434,12 +478,17 @@ class ChatAssistant:
 
         produce: Any
         if memory.summarize is not None:
-            if memory.message_type is None or memory.summary_type is None:
+            if memory.summary_type is None:
+                raise ValueError(
+                    "ChatMemory.summarize needs message_type and summary_type"
+                )
+            message_types = memory.resolved_message_types()
+            if not message_types:
                 raise ValueError(
                     "ChatMemory.summarize needs message_type and summary_type"
                 )
             produce = RollingDigestSummarizer(
-                message_type=memory.message_type,
+                message_type=message_types,
                 artifact_type=memory.summary_type,
                 summarize=memory.summarize,
                 build=_digest_build(memory.summary_type, memory.build_summary),
@@ -447,15 +496,16 @@ class ChatAssistant:
                 digest_id=memory.digest_id,
             )
         elif memory.keep is not None:
-            if memory.message_type is None:
+            message_types = memory.resolved_message_types()
+            if not message_types:
                 raise ValueError("ChatMemory.keep needs message_type")
-            produce = WindowPruner(memory.message_type, keep=memory.keep)
+            produce = WindowPruner(message_types, keep=memory.keep)
         else:
             return []  # compaction-only: no message-level memory agent
         return [
             create_agent(
                 "memory",
-                consumes=[Consume(memory.message_type)],
+                consumes=[Consume.by_base(t) for t in message_types],
                 produces=[produce],
             )
         ]

{reactifact-0.15.2 → reactifact-0.16.0}/reactifact/checkpoints.py

@@ -48,6 +48,36 @@ class KVBackend(ABC):
         """Releases held resources (a pooled connection, ...). No-op by default."""
 
 
+class AppendBackend(KVBackend):
+    """KV backend that can append commit entries without rewriting the snapshot.
+
+    `SessionStore` uses this when available to persist a session as
+    *snapshot + append-only commit log* instead of rewriting the whole Context
+    on every commit. Backends without it keep the full-blob behavior.
+
+    Entries are opaque JSON dicts; `SessionStore` writes one per save with the
+    new commits and the current pending-event queue. `clear_entries` is used
+    when the snapshot is rewritten (first save, compaction, rollback).
+    """
+
+    @abstractmethod
+    async def append(self, key: str, entry: dict[str, Any]) -> None: ...
+
+    @abstractmethod
+    async def entries(self, key: str) -> list[dict[str, Any]]: ...
+
+    @abstractmethod
+    async def clear_entries(self, key: str) -> None: ...
+
+    async def entry_count(self, key: str) -> int:
+        """Number of appended entries for `key`.
+
+        Backends with a native `COUNT(*)` should override this; the default
+        loads the entries and counts them.
+        """
+        return len(await self.entries(key))
+
+
 class InMemoryKVBackend(KVBackend):
     """Dict-backed KV store — no files, no external service.
 
@@ -178,9 +208,9 @@ class _AsyncSQLite:
     writers across processes via the database file).
     """
 
-    def __init__(self, db_path: str, init_sql: str):
+    def __init__(self, db_path: str, init_sql: str | tuple[str, ...]):
         self.db_path = db_path
-        self._init_sql = init_sql
+        self._init_sql = (init_sql,) if isinstance(init_sql, str) else init_sql
         self._conn: sqlite3.Connection | None = None
         self._lock = asyncio.Lock()
 
@@ -197,7 +227,8 @@ class _AsyncSQLite:
             try:
                 conn.execute("PRAGMA journal_mode=WAL")
                 conn.execute("PRAGMA busy_timeout=5000")
-                conn.execute(self._init_sql)
+                for statement in self._init_sql:
+                    conn.execute(statement)
                 conn.commit()
                 return conn
             except sqlite3.OperationalError:
@@ -227,15 +258,23 @@ class _AsyncSQLite:
                 self._conn = None
 
 
-class SQLiteKVBackend(KVBackend):
-    """SQLite KV backend: table kv_entries(key PRIMARY KEY, data JSON)."""
+class SQLiteKVBackend(AppendBackend):
+    """SQLite KV backend: snapshot in `kv_entries`, commit log in
+    `append_entries` (snapshot + append-only commits for sessions)."""
 
     def __init__(self, db_path: str):
         self.db_path = db_path
         self._sql = _AsyncSQLite(
             db_path,
-            "CREATE TABLE IF NOT EXISTS kv_entries "
-            "(key TEXT PRIMARY KEY, data TEXT NOT NULL)",
+            (
+                "CREATE TABLE IF NOT EXISTS kv_entries "
+                "(key TEXT PRIMARY KEY, data TEXT NOT NULL)",
+                "CREATE TABLE IF NOT EXISTS append_entries "
+                "(seq INTEGER PRIMARY KEY AUTOINCREMENT, "
+                "key TEXT NOT NULL, data TEXT NOT NULL)",
+                "CREATE INDEX IF NOT EXISTS idx_append_entries_key "
+                "ON append_entries(key, seq)",
+            ),
         )
 
     async def set(self, key: str, data: dict[str, Any]) -> None:
@@ -252,11 +291,33 @@ class SQLiteKVBackend(KVBackend):
 
     async def delete(self, key: str) -> None:
         await self._sql.execute("DELETE FROM kv_entries WHERE key = ?", (key,))
+        await self._sql.execute("DELETE FROM append_entries WHERE key = ?", (key,))
 
     async def keys(self) -> list[str]:
         rows = await self._sql.execute("SELECT key FROM kv_entries")
         return [cast(str, r[0]) for r in rows]
 
+    async def append(self, key: str, entry: dict[str, Any]) -> None:
+        await self._sql.execute(
+            "INSERT INTO append_entries (key, data) VALUES (?, ?)",
+            (key, json.dumps(entry)),
+        )
+
+    async def entries(self, key: str) -> list[dict[str, Any]]:
+        rows = await self._sql.execute(
+            "SELECT data FROM append_entries WHERE key = ? ORDER BY seq", (key,)
+        )
+        return [cast(dict[str, Any], json.loads(r[0])) for r in rows]
+
+    async def clear_entries(self, key: str) -> None:
+        await self._sql.execute("DELETE FROM append_entries WHERE key = ?", (key,))
+
+    async def entry_count(self, key: str) -> int:
+        rows = await self._sql.execute(
+            "SELECT COUNT(*) FROM append_entries WHERE key = ?", (key,)
+        )
+        return int(rows[0][0]) if rows else 0
+
     async def aclose(self) -> None:
         await self._sql.aclose()
 
@@ -288,7 +349,7 @@ class SQLiteBackend(CheckpointBackend):
         await self._sql.aclose()
 
 
-class PostgreSQLKVBackend(KVBackend):
+class PostgreSQLKVBackend(AppendBackend):
     """PostgreSQL KV backend (`kv_entries(key, data)`) — behind the `pg` extra.
 
     Like the SQLite KV backend, but shared across processes: a natural store
@@ -327,6 +388,15 @@ class PostgreSQLKVBackend(KVBackend):
                     "CREATE TABLE IF NOT EXISTS kv_entries "
                     "(key TEXT PRIMARY KEY, data TEXT NOT NULL)"
                 )
+                await cur.execute(
+                    "CREATE TABLE IF NOT EXISTS append_entries "
+                    "(seq BIGSERIAL PRIMARY KEY, "
+                    "key TEXT NOT NULL, data TEXT NOT NULL)"
+                )
+                await cur.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_append_entries_key "
+                    "ON append_entries(key, seq)"
+                )
             await conn.commit()
             self._conn = conn
         return conn
@@ -384,11 +454,37 @@ class PostgreSQLKVBackend(KVBackend):
 
     async def delete(self, key: str) -> None:
         await self._run("DELETE FROM kv_entries WHERE key = %s", (key,))
+        await self._run("DELETE FROM append_entries WHERE key = %s", (key,))
 
     async def keys(self) -> list[str]:
         rows = await self._run("SELECT key FROM kv_entries", fetch="fetchall")
         return [cast(str, r[0]) for r in rows]
 
+    async def append(self, key: str, entry: dict[str, Any]) -> None:
+        await self._run(
+            "INSERT INTO append_entries (key, data) VALUES (%s, %s)",
+            (key, json.dumps(entry)),
+        )
+
+    async def entries(self, key: str) -> list[dict[str, Any]]:
+        rows = await self._run(
+            "SELECT data FROM append_entries WHERE key = %s ORDER BY seq",
+            (key,),
+            fetch="fetchall",
+        )
+        return [cast(dict[str, Any], json.loads(r[0])) for r in rows]
+
+    async def clear_entries(self, key: str) -> None:
+        await self._run("DELETE FROM append_entries WHERE key = %s", (key,))
+
+    async def entry_count(self, key: str) -> int:
+        row = await self._run(
+            "SELECT COUNT(*) FROM append_entries WHERE key = %s",
+            (key,),
+            fetch="fetchone",
+        )
+        return int(row[0]) if row is not None else 0
+
     async def aclose(self) -> None:
         async with self._lock:
             await self._reset()