branchkit 0.1.0__tar.gz

branchkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BranchKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

branchkit-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: branchkit
+Version: 0.1.0
+Summary: BranchKit plugin SDK for Python
+Author: BranchKit
+License-Expression: MIT
+Project-URL: Homepage, https://branchkit.dev
+Project-URL: Repository, https://github.com/branchkit/plugin-sdk-py
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# BranchKit Plugin SDK (Python)
+
+The Python SDK for building [BranchKit](https://branchkit.dev)
+plugins — processes (run under BranchKit's managed CPython) that add
+voice commands, window management, browser integration, or anything
+else to the BranchKit platform. MIT licensed. Feature-parity with the
+Go and TypeScript SDKs, verified by a shared conformance harness.
+Stdlib-only: importing the SDK forces no third-party dependency on any
+plugin.
+
+## Start here
+
+- **[Your First Plugin](https://branchkit.dev/guide/getting-started/your-first-plugin)** —
+  working plugin in ~10 minutes
+- **[Plugin Anatomy](https://branchkit.dev/guide/getting-started/plugin-anatomy)** —
+  manifest, lifecycle, methods
+- **[Plugin API Reference](https://branchkit.dev/reference/specs/plugin-api)** —
+  every wire method, generated from the OpenRPC spec
+
+## Minimal plugin
+
+```python
+import asyncio
+import branchkit
+
+plugin = branchkit.Plugin()
+
+@plugin.handle_action("myplugin.greet")
+async def greet(req):
+    await plugin.input_type_text("Hello!")
+    return {"status": "ok"}
+
+asyncio.run(plugin.run())
+```
+
+Pair with a `plugin.json` manifest declaring the action and
+`"runtimes": ["python"]` (`run: "python3 main.py"`) — see the tutorial.
+`branchkit-gen` generates typed params (`TypedDict`) and registrars from
+your manifest's `action_types`.
+
+Handlers may be `async def` (run on the asyncio loop) or plain `def`
+(auto-offloaded to a worker thread, so a blocking body cannot freeze the
+plugin — use `plugin.call_sync(...)` there instead of `await`).
+
+## Key surfaces
+
+| Need | API |
+|---|---|
+| Handle an action | `@plugin.handle_action("prefix.name")` (alias `@plugin.action`) |
+| Handle an RPC method | `@plugin.handle("my_method")` |
+| Listen for events | `@plugin.on(EVENT_COLLECTION_UPDATED)` |
+| Call the actuator | generated wrappers (`await plugin.collection_get(...)`, 600+) or raw `plugin.call` |
+| State verbs | `plugin.get/list/put/patch/delete/replace/...` |
+| Logs (append-only) | `plugin.append/append_keyed/list_log/...` |
+| Mirrors | `plugin.mirror_collection(name)`, `plugin.settings(name)` |
+| Commands | `branchkit.command(...)` builder, `push_command_group` |
+| Leveled logging | `await plugin.info(tag, data)` (trace/debug/info/warn/error) |
+| Local listener | `branchkit.listen_local(plugin)` (serves inherited fds) |
+| Outbound HTTP | `branchkit.UpstreamClient` / `urllib.request.urlopen` (both proxy-aware) |
+| Author tests | `branchkit.harness.Harness` |
+
+## Development
+
+```sh
+python3 -m unittest discover -s tests     # the SDK's own suite
+```
+
+The cross-language conformance suite lives in the app workspace
+(`branchkit-sdk-test` against `sdk-test/testplugin-py`). Generated
+files (`*_gen.py`) are emitted by `emit-sdk` — edit the inventory, not
+the files.

branchkit-0.1.0/README.md

@@ -0,0 +1,71 @@
+# BranchKit Plugin SDK (Python)
+
+The Python SDK for building [BranchKit](https://branchkit.dev)
+plugins — processes (run under BranchKit's managed CPython) that add
+voice commands, window management, browser integration, or anything
+else to the BranchKit platform. MIT licensed. Feature-parity with the
+Go and TypeScript SDKs, verified by a shared conformance harness.
+Stdlib-only: importing the SDK forces no third-party dependency on any
+plugin.
+
+## Start here
+
+- **[Your First Plugin](https://branchkit.dev/guide/getting-started/your-first-plugin)** —
+  working plugin in ~10 minutes
+- **[Plugin Anatomy](https://branchkit.dev/guide/getting-started/plugin-anatomy)** —
+  manifest, lifecycle, methods
+- **[Plugin API Reference](https://branchkit.dev/reference/specs/plugin-api)** —
+  every wire method, generated from the OpenRPC spec
+
+## Minimal plugin
+
+```python
+import asyncio
+import branchkit
+
+plugin = branchkit.Plugin()
+
+@plugin.handle_action("myplugin.greet")
+async def greet(req):
+    await plugin.input_type_text("Hello!")
+    return {"status": "ok"}
+
+asyncio.run(plugin.run())
+```
+
+Pair with a `plugin.json` manifest declaring the action and
+`"runtimes": ["python"]` (`run: "python3 main.py"`) — see the tutorial.
+`branchkit-gen` generates typed params (`TypedDict`) and registrars from
+your manifest's `action_types`.
+
+Handlers may be `async def` (run on the asyncio loop) or plain `def`
+(auto-offloaded to a worker thread, so a blocking body cannot freeze the
+plugin — use `plugin.call_sync(...)` there instead of `await`).
+
+## Key surfaces
+
+| Need | API |
+|---|---|
+| Handle an action | `@plugin.handle_action("prefix.name")` (alias `@plugin.action`) |
+| Handle an RPC method | `@plugin.handle("my_method")` |
+| Listen for events | `@plugin.on(EVENT_COLLECTION_UPDATED)` |
+| Call the actuator | generated wrappers (`await plugin.collection_get(...)`, 600+) or raw `plugin.call` |
+| State verbs | `plugin.get/list/put/patch/delete/replace/...` |
+| Logs (append-only) | `plugin.append/append_keyed/list_log/...` |
+| Mirrors | `plugin.mirror_collection(name)`, `plugin.settings(name)` |
+| Commands | `branchkit.command(...)` builder, `push_command_group` |
+| Leveled logging | `await plugin.info(tag, data)` (trace/debug/info/warn/error) |
+| Local listener | `branchkit.listen_local(plugin)` (serves inherited fds) |
+| Outbound HTTP | `branchkit.UpstreamClient` / `urllib.request.urlopen` (both proxy-aware) |
+| Author tests | `branchkit.harness.Harness` |
+
+## Development
+
+```sh
+python3 -m unittest discover -s tests     # the SDK's own suite
+```
+
+The cross-language conformance suite lives in the app workspace
+(`branchkit-sdk-test` against `sdk-test/testplugin-py`). Generated
+files (`*_gen.py`) are emitted by `emit-sdk` — edit the inventory, not
+the files.

branchkit-0.1.0/branchkit/__init__.py

@@ -0,0 +1,87 @@
+"""BranchKit plugin SDK for Python.
+
+    import asyncio
+    import branchkit
+
+    plugin = branchkit.Plugin()
+
+    @plugin.handle("my.method")
+    async def my_method(params):
+        return {"ok": True}
+
+    asyncio.run(plugin.run())
+
+Handlers may be `async def` (run on the loop) or plain `def`
+(auto-offloaded to a thread, so a blocking body cannot freeze the
+plugin). Stdlib-only by design: importing the SDK forces no third-party
+dependency on any plugin."""
+
+from . import proxy as _proxy
+
+# Route stdlib HTTP through BRANCHKIT_PROXY when sandboxed (per-host
+# tier) — same import-time side effect as the TS SDK's entry module.
+_proxy.install_proxy_from_env()
+
+from .plugin import (
+    PluginCore,
+    RecordingDisabledError,
+    RpcCallError,
+    api_version,
+    error_kind_of,
+    models_dir,
+    plugin_data_dir,
+    plugin_dir,
+)
+from .collection import CollectionMixin, list_opts, scope_collection, scope_group
+from .collection_log import CollectionLogMixin, log_list_opts
+from .debug import DebugMixin
+from .effects import EffectsMixin
+from .hud import HudMixin
+from .log import log
+from .methods_gen import MethodsMixin
+from .mirror import CollectionMirror, MirrorMixin
+from .settings import SettingsMirror, SettingsMixin
+from .commands import (
+    CommandBuilder,
+    capture,
+    command,
+    load_commands,
+    one_of,
+    push_command_group,
+    push_command_specs,
+    push_commands,
+    text,
+    word,
+)
+from .listen import Listener, inherited_listener_count, listen_local
+from .settings_route import method_post, method_url
+from .ui import (
+    Expr,
+    args,
+    confirm_button,
+    expr,
+    input_value,
+    post_button,
+    signal_button,
+    signal_name,
+)
+from .upstream import UpstreamClient, UpstreamResponse
+from .closed_vocab_gen import *  # noqa: F401,F403 — error kinds, directives, effects
+from .contracts_gen import *  # noqa: F401,F403 — method/hook/event/tag constants
+from .log_events_gen import *  # noqa: F401,F403 — observability log-event names
+
+
+class Plugin(
+    CollectionMixin,
+    CollectionLogMixin,
+    EffectsMixin,
+    DebugMixin,
+    HudMixin,
+    MirrorMixin,
+    SettingsMixin,
+    MethodsMixin,
+    PluginCore,
+):
+    """The plugin: JSON-RPC transport plus the generated method wrappers
+    and the state/log/effects/debug/HUD/mirror/settings façades, one
+    class. See PluginCore for the transport contract."""

branchkit-0.1.0/branchkit/closed_vocab_gen.py

@@ -0,0 +1,95 @@
+# AUTO-GENERATED by emit-sdk — do not edit.
+# Run: just contracts
+
+from typing import NotRequired, TypedDict
+
+# INPUT_DIRECTIVE_* are the closed-vocabulary keys plugins may write
+# into `_platform.input.directives`. Source of truth:
+# `actuator/src/state.rs::InputDirectives::KNOWN_KEYS`.
+INPUT_DIRECTIVE_LIFT_KEYS_ON_DISPATCH = "lift_keys_on_dispatch"
+
+# EFFECT_* are the registered effect names plugins may declare in
+# `provides.effects`. Source of truth:
+# `actuator/src/effects.rs::EffectDef` inventory entries.
+EFFECT_DISABLE_SCREEN_DIM = "disable_screen_dim"
+EFFECT_MUTE_AUDIO_TO_OTHER_APPS = "mute_audio_to_other_apps"
+EFFECT_PAUSE_MICROPHONE_INDICATOR = "pause_microphone_indicator"
+EFFECT_PREVENT_FOCUS_STEAL = "prevent_focus_steal"
+EFFECT_SIGNAL_RECORDING_ACTIVE = "signal_recording_active"
+EFFECT_SUPPRESS_HUDS = "suppress_huds"
+EFFECT_SUPPRESS_KEYBINDS = "suppress_keybinds"
+EFFECT_SUPPRESS_NOTIFICATIONS = "suppress_notifications"
+
+# The full closed-vocabulary sets.
+KNOWN_INPUT_DIRECTIVES = (
+    "lift_keys_on_dispatch",
+)
+
+KNOWN_EFFECTS = (
+    "disable_screen_dim",
+    "mute_audio_to_other_apps",
+    "pause_microphone_indicator",
+    "prevent_focus_steal",
+    "signal_recording_active",
+    "suppress_huds",
+    "suppress_keybinds",
+    "suppress_notifications",
+)
+
+# ERROR_KIND_* are the closed-vocabulary `kind` values the actuator puts
+# in a JSON-RPC error's `data.kind`. Branch on RpcCallError.kind rather
+# than matching the message prose. Source of truth:
+# `actuator/src/fault.rs::ErrorKind`.
+#
+# NOTE: ErrorKind is `str`, deliberately NOT a Literal union of the
+# values below. An actuator newer than this SDK may send a kind that is
+# not listed here, and that must fall through a match rather than fail
+# to parse.
+ErrorKind = str
+ERROR_KIND_NOT_PERMITTED = "not_permitted"
+ERROR_KIND_RECORDING_DISABLED = "recording_disabled"
+ERROR_KIND_NOT_FOUND = "not_found"
+ERROR_KIND_VALIDATION = "validation"
+ERROR_KIND_FORBIDDEN = "forbidden"
+ERROR_KIND_STORAGE = "storage"
+ERROR_KIND_METHOD_NOT_FOUND = "method_not_found"
+ERROR_KIND_INVALID_PARAMS = "invalid_params"
+ERROR_KIND_INTERNAL = "internal"
+
+# ERROR_CODE_FOR maps a kind to the JSON-RPC error code the actuator
+# sends with it. Derived from the kind actuator-side.
+ERROR_CODE_FOR: dict[str, int] = {
+    "not_permitted": -32002,
+    "recording_disabled": -32006,
+    "not_found": -32001,
+    "validation": -32004,
+    "forbidden": -32003,
+    "storage": -32005,
+    "method_not_found": -32601,
+    "invalid_params": -32602,
+    "internal": -32603,
+}
+
+# KNOWN_ERROR_KINDS lists the full closed-vocabulary set.
+KNOWN_ERROR_KINDS = (
+    "not_permitted",
+    "recording_disabled",
+    "not_found",
+    "validation",
+    "forbidden",
+    "storage",
+    "method_not_found",
+    "invalid_params",
+    "internal",
+)
+
+# FaultData is the structured payload of a JSON-RPC error's `data`
+# member. Only `kind` is guaranteed; the rest are populated when they
+# apply. Source of truth: `actuator/src/fault.rs::FaultData`.
+FaultData = TypedDict("FaultData", {
+    "kind": str,
+    "collection": NotRequired[str],
+    "detail": NotRequired[str],
+    "id": NotRequired[str],
+    "op": NotRequired[str],
+})

branchkit-0.1.0/branchkit/collection.py

@@ -0,0 +1,188 @@
+"""State uniform helpers — the collection façade over the generated
+`collection.*` wrappers. Python twin of plugin-sdk-go/collection.go and
+plugin-sdk-ts/src/collection.ts."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .contracts_gen import EVENT_COLLECTION_UPDATED
+
+
+def scope_collection() -> dict:
+    """Every other record THIS PLUGIN owns in the collection is the
+    complement: after the call, the records you own here are exactly the
+    ones you passed. Other plugins' records, and any the user added through
+    Settings, are untouched and invisible to the diff."""
+    return {"kind": "collection"}
+
+
+def scope_group(group: str) -> dict:
+    """Narrows further, to this plugin's records carrying the named group
+    label — and stamps that label on every entry written. The label must be
+    non-empty; an empty one is indistinguishable from "ungrouped" and the
+    platform refuses it."""
+    return {"kind": "group", "value": group}
+
+
+def list_opts(
+    *,
+    since_ms: int | None = None,
+    until_ms: int | None = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+    writer: str | None = None,
+) -> dict:
+    """Build a ListOpts with typed scalar values. `writer` filters to
+    records owned by that writer — pair with `plugin.id` to ask for your
+    own records, the read half of a scoped write."""
+    out: dict[str, Any] = {}
+    if since_ms is not None:
+        out["since_ms"] = since_ms
+    if until_ms is not None:
+        out["until_ms"] = until_ms
+    if limit is not None:
+        out["limit"] = limit
+    if cursor is not None:
+        out["cursor"] = cursor
+    if writer is not None:
+        out["writer"] = writer
+    return out
+
+
+class CollectionMixin:
+    """The uniform state verbs. Composed into `Plugin`."""
+
+    async def get(self, name: str, id: str) -> dict | None:
+        """The record with that id, or None. On a keyed (compacted-changelog)
+        log this is the RAW entry — use `get_compacted` for the folded
+        current state."""
+        res = await self.collection_fetch(id, name)
+        rec = (res or {}).get("record")
+        return rec if isinstance(rec, dict) else None
+
+    async def get_compacted(self, name: str, key: str) -> dict | None:
+        """A keyed log's folded CURRENT state for one key — the point-read
+        half of the compacted-changelog projection (pairs with
+        `list_compacted`)."""
+        res = await self.collection_fetch_compacted(key, name)
+        rec = (res or {}).get("record")
+        return rec if isinstance(rec, dict) else None
+
+    async def list(self, name: str, opts: dict | None = None) -> list[dict]:
+        res = await self.collection_list(name, opts)
+        return (res or {}).get("records") or []
+
+    async def list_compacted(self, name: str, opts: dict | None = None) -> list[dict]:
+        """The compacted-changelog projection of a keyed log — one folded
+        record per key instead of the raw append history."""
+        merged = dict(opts or {})
+        merged["compacted"] = True
+        res = await self.collection_list(name, merged)
+        return (res or {}).get("records") or []
+
+    async def list_page(self, name: str, opts: dict | None = None) -> tuple[list[dict], int]:
+        """Like `list` but also returns the unfiltered total."""
+        res = await self.collection_list(name, opts)
+        res = res or {}
+        return res.get("records") or [], res.get("total") or 0
+
+    async def count(self, name: str) -> int:
+        res = await self.collection_count(name)
+        return (res or {}).get("count") or 0
+
+    async def put(self, name: str, id: str, payload: Any) -> None:
+        """Single-record upsert. An unregistered name auto-registers as a
+        record-keyed dynamic collection — memory-only and EPHEMERAL; declare
+        the collection in the manifest for durable storage."""
+        await self.collection_put(name, [{"id": id, "payload": payload}])
+
+    async def put_many(self, name: str, entries: list[dict]) -> int:
+        """Bulk upsert. Validation runs across all entries before any
+        commit, so a partial batch with one invalid entry leaves the
+        backend untouched."""
+        if not entries:
+            return 0
+        res = await self.collection_put(name, entries)
+        return (res or {}).get("count") or 0
+
+    async def replace(
+        self,
+        name: str,
+        entries: list[dict],
+        scope: dict,
+        *,
+        roles: dict | None = None,
+        label: str | None = None,
+    ) -> dict:
+        """Make the records in scope exactly `entries`: upsert what changed,
+        delete what is absent, skip what is byte-identical. Returns
+        ``{"put": n, "deleted": n, "skipped": n}``.
+
+        Scope is required and never inferred — pass `scope_collection()` or
+        `scope_group(...)`. See notes/DESIGN_COLLECTION_REPLACE.md."""
+        # Refused locally rather than sent: guessing between "everything I
+        # own here" and "the subset under this key space" is how a refresh
+        # silently becomes a wipe.
+        if not isinstance(scope, dict) or scope.get("kind") not in ("collection", "group"):
+            raise ValueError(
+                "replace: scope is required — use scope_collection() or scope_group(name)"
+            )
+        # No early return on empty `entries`: replacing with the empty set
+        # is how a caller CLEARS its scope.
+        res = await self.collection_replace(name, scope, entries, label, roles)
+        res = res or {}
+        return {
+            "put": res.get("put") or 0,
+            "deleted": res.get("deleted") or 0,
+            "skipped": res.get("skipped") or 0,
+        }
+
+    async def put_many_with_roles(self, name: str, entries: list[dict], roles: dict) -> int:
+        """Bulk upsert with per-payload-field display roles (field → role).
+        Roles persist on the collection — pass them on the first put to a
+        new name, then omit."""
+        return await self.put_many_with_display(name, entries, roles, "")
+
+    async def put_many_with_display(
+        self, name: str, entries: list[dict], roles: dict | None, label: str
+    ) -> int:
+        """Bulk upsert that also sets the collection's human-readable label.
+        Pass "" to leave the label unchanged; like roles, it persists."""
+        if not entries:
+            return 0
+        res = await self.collection_put(name, entries, None, label or None, roles)
+        return (res or {}).get("count") or 0
+
+    async def patch(self, name: str, id: str, fields: Any) -> None:
+        """Errors NOT_FOUND if no record with that id exists, or
+        OPERATION_NOT_PERMITTED on collections the state forbids patching."""
+        await self.collection_patch(fields, id, name)
+
+    async def delete(self, name: str, id: str) -> bool:
+        """Single-record delete. Returns whether the record existed."""
+        res = await self.collection_delete_records(name, [id])
+        return ((res or {}).get("deleted") or 0) > 0
+
+    async def delete_many(self, name: str, ids: list[str]) -> tuple[int, int]:
+        """Bulk delete. Returns (deleted, already_absent) so callers can
+        detect drift between their view and the platform's."""
+        if not ids:
+            return 0, 0
+        res = await self.collection_delete_records(name, ids)
+        res = res or {}
+        return res.get("deleted") or 0, res.get("already_absent") or 0
+
+    def subscribe(self, name: str, fn: Callable) -> None:
+        """Run `fn(evt)` whenever `_platform.collection.updated` fires for
+        this collection. The ordered pump awaits an async `fn`, so two rapid
+        updates cannot race. Subscriptions live for the process lifetime."""
+
+        async def _on_updated(params):
+            evt = params if isinstance(params, dict) else {}
+            if evt.get("collection") == name:
+                # Await, don't discard: this is what keeps wire order. Dual
+                # dispatch, same as any handler — a plain-`def` fn offloads.
+                await self._invoke(fn, evt)
+
+        self.on(EVENT_COLLECTION_UPDATED, _on_updated)

branchkit-0.1.0/branchkit/collection_log.py

@@ -0,0 +1,97 @@
+"""Helpers for log-kind collections — append-only record stores declared
+in the plugin manifest as `kind: "log"`. Sugar over the unified verbs
+(the wire surface is collection.list / collection.fetch /
+collection.delete_records; log-shaped reads are the same list with
+time-window opts). Python twin of collection_log.{go,ts}."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def log_list_opts(
+    *,
+    since_ms: int | None = None,
+    until_ms: int | None = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> dict:
+    """Build a LogListOpts with typed scalar values — field-identical to
+    the unified list opts by design."""
+    out: dict[str, Any] = {}
+    if since_ms is not None:
+        out["since_ms"] = since_ms
+    if until_ms is not None:
+        out["until_ms"] = until_ms
+    if limit is not None:
+        out["limit"] = limit
+    if cursor is not None:
+        out["cursor"] = cursor
+    return out
+
+
+def _record_to_log_entry(r: dict) -> dict:
+    """Project the unified record envelope onto the log view. Lossless: log
+    records carry their append time in timestamp_ms and owner in writer."""
+    return {
+        "id": r.get("id"),
+        "timestamp_ms": r.get("timestamp_ms"),
+        "payload": r.get("payload"),
+        "writer": r.get("writer"),
+    }
+
+
+class CollectionLogMixin:
+    async def append(self, name: str, payload: Any) -> str:
+        """Append an entry to a log-kind collection; the actuator assigns a
+        ULID and timestamp. Returns the assigned entry id. Raises
+        RecordingDisabledError if the collection's recording flag is off."""
+        entry = await self.collection_append(name, payload)
+        if not entry:
+            raise RuntimeError("collection.append: actuator returned no entry")
+        return entry["id"]
+
+    async def append_entry(self, name: str, payload: Any) -> dict:
+        """Like `append` but returns the full LogEntry."""
+        entry = await self.collection_append(name, payload)
+        if not entry:
+            raise RuntimeError("collection.append: actuator returned no entry")
+        return entry
+
+    async def append_keyed(self, name: str, key: str, payload: Any) -> None:
+        """Annotate a keyed log (`log` preset, `id_strategy: by_field`):
+        appends `payload` with `key` stamped into the key field, as a fresh
+        append; same-key appends fold. Read the merged view with
+        `list_compacted`. See notes/DESIGN_LOG_ANNOTATION_PROJECTION.md."""
+        await self.collection_append_keyed(key, name, payload)
+
+    async def list_log(self, name: str, opts: dict | None = None) -> list[dict]:
+        """List log entries newest-first."""
+        entries, _ = await self.list_log_page(name, opts)
+        return entries
+
+    async def list_log_page(self, name: str, opts: dict | None = None) -> tuple[list[dict], int]:
+        """Like `list_log` but also returns the unfiltered total."""
+        records, total = await self.list_page(name, opts)
+        return [_record_to_log_entry(r) for r in records], total
+
+    async def get_log_entry(self, name: str, id: str) -> dict | None:
+        """One entry by id, or None. The RAW entry — on a keyed log use
+        `get_compacted` for a key's current state."""
+        rec = await self.get(name, id)
+        return _record_to_log_entry(rec) if rec else None
+
+    async def delete_log_entry(self, name: str, id: str) -> bool:
+        """Delete one entry by id. Returns whether it existed."""
+        return await self.delete(name, id)
+
+    async def set_collection_recording(self, name: str, enabled: bool) -> None:
+        """Toggle the recording flag on a log-kind collection. When False,
+        subsequent `append` calls raise RecordingDisabledError."""
+        await self.privacy_set_recording(enabled, name)
+
+    async def get_collection_recording(self, name: str) -> bool:
+        """The effective recording flag — the user override if set,
+        otherwise the manifest's `default_recording_enabled`."""
+        res = await self.privacy_get_recording(name)
+        return bool((res or {}).get("enabled", False))