doc-store-client-dev 0.1.185__py3-none-any.whl

doc_store_client/client.py

@@ -0,0 +1,1509 @@
+"""Thin typed facade over an injected ``mcp-proxy-adapter`` client."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import is_dataclass, replace
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeVar, cast
+
+from chunk_metadata_adapter import ChunkQuery
+
+from .models import (
+    BackupEmergencyResult,
+    BackupInspectResult,
+    BackupPointsResult,
+    BackupRecoverCatalogResult,
+    BackupRestoreResult,
+    BackupRunResult,
+    BackupStatusResult,
+    ChapterGetRequest,
+    ChapterGetResult,
+    ChapterTextGetRequest,
+    DocumentChunkRequest,
+    DocumentChunkResult,
+    DocumentCreateRequest,
+    DocumentCreateResult,
+    DocumentDeleteRequest,
+    DocumentDeleteResult,
+    DocumentGetRequest,
+    DocumentGetResult,
+    DocumentRebindRequest,
+    DocumentRebindResult,
+    DocumentUpdateRequest,
+    DocumentUpdateResult,
+    EntityGetRequest,
+    EntityGetResult,
+    EntityTextGetRequest,
+    EntityTextGetResult,
+    EntityIdsRequest,
+    EntityLifecycleResult,
+    EntityListRequest,
+    EntityListResult,
+    EntityOwnerTreeRequest,
+    EntityOwnerTreeResult,
+    EntityReferencesRequest,
+    EntityReferencesResult,
+    ParagraphGetByNumberRequest,
+    ParagraphGetByNumberResult,
+    ParagraphGetRequest,
+    ParagraphGetResult,
+    ProcessingStatusRequest,
+    ProcessingStatusResult,
+    SearchResult,
+    ServerError,
+    SemanticChunkMetadataUpdateRequest,
+    SemanticChunkMetadataUpdateResult,
+    SourceFileReconstructRequest,
+    TextReconstructionResult,
+)
+
+if TYPE_CHECKING:
+    from .models import (
+        ChunkHistoryRequest,
+        ChunkHistoryResult,
+        ChunkVersionAddRequest,
+        ChunkVersionAddResult,
+        ChunkVersionDeleteRequest,
+        ChunkVersionDeleteResult,
+        ChunkVersionDiffRequest,
+        ChunkVersionDiffResult,
+        ChunkVersionGetRequest,
+        ChunkVersionGetResult,
+        ChunkVersionListRequest,
+        ChunkVersionListResult,
+        ChunkVersionRestoreRequest,
+        ChunkVersionRestoreResult,
+        ChunkVersionRetireRequest,
+        ChunkVersionRetireResult,
+        ChunkVersionSetCurrentRequest,
+        ChunkVersionSetCurrentResult,
+        ChunkVersionUpdateRequest,
+        ChunkVersionUpdateResult,
+    )
+
+DOC_STORE_COMMANDS: tuple[str, ...] = (
+    "echo",
+    "long_task",
+    "job_status",
+    "queue_add_job",
+    "queue_start_job",
+    "queue_stop_job",
+    "queue_delete_job",
+    "queue_get_job_status",
+    "queue_get_job_logs",
+    "queue_list_jobs",
+    "queue_health",
+    "health",
+    "info",
+    "uuid4",
+    "document_get",
+    "chapter_get",
+    "paragraph_get",
+    "paragraph_get_by_number",
+    "document_create",
+    "document_update",
+    "document_chunk",
+    "document_export",
+    "chapter_text_get",
+    "source_file_reconstruct",
+    "chunk_version_list",
+    "chunk_history",
+    "chunk_version_get",
+    "chunk_version_add",
+    "chunk_version_update",
+    "chunk_version_set_current",
+    "chunk_version_restore",
+    "chunk_version_retire",
+    "chunk_version_diff",
+    "chunk_version_delete",
+    "document_rebind",
+    "processing_status",
+    "document_delete",
+    "entity_create",
+    "entity_list",
+    "entity_get",
+    "entity_text_get",
+    "entity_content_get",
+    "entity_update",
+    "entity_rebind_owner",
+    "entity_owner_tree",
+    "entity_soft_delete",
+    "entity_undelete",
+    "entity_hard_delete",
+    "entity_references",
+    "chunk_query_search",
+    "semantic_relations",
+    "semantic_chunk_metadata_update",
+    "corpus_audit",
+    "embeddings_rebuild",
+    "help",
+    "config",
+    "reload",
+    "settings",
+    "load",
+    "unload",
+    "plugins",
+    "transport_management",
+    "proxy_registration",
+    "roletest",
+    "transfer_upload_begin",
+    "transfer_upload_status",
+    "transfer_upload_complete",
+    "transfer_download_begin",
+    "transfer_download_status",
+    "backup_run",
+    "backup_emergency",
+    "backup_status",
+    "backup_points",
+    "backup_inspect",
+    "backup_restore",
+    "backup_recover_catalog",
+)
+
+
+class _Omitted:
+    """Sentinel that distinguishes an omitted field from an explicit JSON null."""
+
+
+_OMITTED = _Omitted()
+
+
+class JsonRpcClientLike(Protocol):
+    """Minimal adapter surface used by the typed facade."""
+
+    async def execute_command_unified(self, command: str, params: Mapping[str, Any]) -> Any:
+        """Execute a doc-store command through the adapter."""
+
+
+class TransferClientLike(JsonRpcClientLike, Protocol):
+    """Adapter surface when file-transfer ingestion is used."""
+
+    async def upload_file(
+        self,
+        source_path: str,
+        *,
+        filename: str | None = None,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Any = None,
+    ) -> Any:
+        """Delegate file transfer to the adapter implementation."""
+
+
+T = TypeVar("T")
+
+
+class DocStoreClientError(RuntimeError):
+    """Raised when the adapter or server returns a structured command error."""
+
+    def __init__(self, error: ServerError) -> None:
+        self.error = error
+        super().__init__(error.message)
+
+
+_LOCK_ERROR_CODES = ("FILE_ALREADY_LOCKED", "SESSION_NOT_FOUND", "LOCK_SERVICE_UNAVAILABLE")
+
+
+def _lock_field(error: ServerError, name: str) -> Any:
+    """Read a lock data field: ``details['data']`` when it is a mapping, else ``details``."""
+
+    details = error.details
+    if not isinstance(details, Mapping):
+        return None
+    data = details.get("data")
+    source = data if isinstance(data, Mapping) else details
+    return source.get(name)
+
+
+class FileAlreadyLockedError(DocStoreClientError):
+    """The write was refused because another session holds the document."""
+
+    @property
+    def document_id(self) -> Any:
+        return _lock_field(self.error, "document_id")
+
+    @property
+    def holder_session_id(self) -> Any:
+        return _lock_field(self.error, "holder_session_id")
+
+    @property
+    def holder_idle_seconds(self) -> Any:
+        return _lock_field(self.error, "holder_idle_seconds")
+
+    @property
+    def seconds_left_before_timeout(self) -> Any:
+        return _lock_field(self.error, "seconds_left_before_timeout")
+
+
+class SessionNotFoundError(DocStoreClientError):
+    """The write was refused because the CAS session is unknown or expired."""
+
+    @property
+    def session_id(self) -> Any:
+        return _lock_field(self.error, "session_id")
+
+
+class LockServiceUnavailableError(DocStoreClientError):
+    """The write was refused because the lock check could not be made."""
+
+    @property
+    def reason(self) -> Any:
+        return _lock_field(self.error, "reason")
+
+
+_LOCK_ERROR_CLASSES: dict[str, type[DocStoreClientError]] = {
+    "FILE_ALREADY_LOCKED": FileAlreadyLockedError,
+    "SESSION_NOT_FOUND": SessionNotFoundError,
+    "LOCK_SERVICE_UNAVAILABLE": LockServiceUnavailableError,
+}
+
+
+def _lock_code(error: ServerError) -> str | None:
+    """The lock code of ``error``: ``error.code``, else the code carried in its data."""
+
+    if error.code in _LOCK_ERROR_CODES:
+        return str(error.code)
+    details = error.details
+    if isinstance(details, Mapping):
+        data = details.get("data")
+        for source in (data, details):
+            if isinstance(source, Mapping) and source.get("code") in _LOCK_ERROR_CODES:
+                return str(source["code"])
+    return None
+
+
+_NOT_FOUND = "NOT_FOUND"
+_UUID_IN_TEXT = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
+
+
+class DocStoreNotFoundError(DocStoreClientError):
+    """The requested target does not exist (server code ``NOT_FOUND``).
+
+    ``code`` is always ``"NOT_FOUND"``. ``missing_id`` is the id of the absent target when the
+    server named it (in the error data or in the message), else ``None``. ``str()`` keeps the
+    server message, so callers that read the text keep working.
+    """
+
+    code: str = _NOT_FOUND
+
+    @property
+    def missing_id(self) -> str | None:
+        details = self.error.details
+        if isinstance(details, Mapping):
+            data = details.get("data")
+            for source in (data, details):
+                if not isinstance(source, Mapping):
+                    continue
+                for key in ("missing_id", "document_id", "chapter_id", "paragraph_id", "chunk_id", "entity_id", "id"):
+                    value = source.get(key)
+                    if isinstance(value, str) and value:
+                        return value
+        match = _UUID_IN_TEXT.search(self.error.message)
+        return match.group(0) if match else None
+
+
+def _is_not_found(error: ServerError) -> bool:
+    if error.code == _NOT_FOUND:
+        return True
+    details = error.details
+    if isinstance(details, Mapping):
+        data = details.get("data")
+        for source in (data, details):
+            if isinstance(source, Mapping) and source.get("code") == _NOT_FOUND:
+                return True
+    return False
+
+
+def _client_error(error: ServerError) -> DocStoreClientError:
+    """The typed lock or not-found error for its code, else the plain ``DocStoreClientError``."""
+
+    code = _lock_code(error)
+    if code is not None:
+        return _LOCK_ERROR_CLASSES[code](error)
+    if _is_not_found(error):
+        if error.code != _NOT_FOUND:
+            error = replace(error, code=_NOT_FOUND)
+        return DocStoreNotFoundError(error)
+    return DocStoreClientError(error)
+
+
+class DocStoreClient:
+    """Typed doc-store operations backed by an injected adapter client."""
+
+    commands: ClassVar[tuple[str, ...]] = DOC_STORE_COMMANDS
+
+    def __init__(
+        self,
+        adapter_client: JsonRpcClientLike,
+        *,
+        event_callback: Callable[[Mapping[str, Any]], Awaitable[None] | None] | None = None,
+    ) -> None:
+        self._adapter_client = adapter_client
+        self._event_callback = event_callback
+
+    async def call(
+        self,
+        command: str,
+        params: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute any server command through the injected adapter client.
+
+        The adapter owns networking, TLS/mTLS, authentication, queue delivery, and
+        retries.  This method only gives callers a stable command-level facade.
+        """
+
+        command_name = command.strip()
+        if not command_name:
+            raise ValueError("command must be non-empty")
+        return _unwrap_response(
+            await self._dispatch(command_name, _merge_params(params, kwargs))
+        )
+
+    async def echo(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("echo", params, **kwargs)
+
+    async def long_task(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("long_task", params, **kwargs)
+
+    async def job_status(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("job_status", params, **kwargs)
+
+    async def queue_add_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_add_job", params, **kwargs)
+
+    async def queue_start_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_start_job", params, **kwargs)
+
+    async def queue_stop_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_stop_job", params, **kwargs)
+
+    async def queue_delete_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_delete_job", params, **kwargs)
+
+    async def queue_get_job_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_get_job_status", params, **kwargs)
+
+    async def queue_get_job_logs(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_get_job_logs", params, **kwargs)
+
+    async def queue_list_jobs(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_list_jobs", params, **kwargs)
+
+    async def queue_health(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_health", params, **kwargs)
+
+    async def document_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_get", params, **kwargs)
+
+    async def chapter_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chapter_get", params, **kwargs)
+
+    async def paragraph_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("paragraph_get", params, **kwargs)
+
+    async def paragraph_get_by_number(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("paragraph_get_by_number", params, **kwargs)
+
+    async def document_create(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("document_create", params, **kwargs, **_session_kwargs(session_id))
+
+    async def document_update(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("document_update", params, **kwargs, **_session_kwargs(session_id))
+
+    async def document_chunk(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("document_chunk", params, **kwargs, **_session_kwargs(session_id))
+
+    async def document_export(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_export", params, **kwargs)
+
+    async def chapter_text_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chapter_text_get", params, **kwargs)
+
+    async def source_file_reconstruct(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("source_file_reconstruct", params, **kwargs)
+
+    async def chunk_version_list(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_version_list", params, **kwargs)
+
+    async def chunk_history(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_history", params, **kwargs)
+
+    async def chunk_version_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_version_get", params, **kwargs)
+
+    async def chunk_version_add(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_add", params, **kwargs, **_session_kwargs(session_id))
+
+    async def chunk_version_update(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_update", params, **kwargs, **_session_kwargs(session_id))
+
+    async def chunk_version_set_current(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_set_current", params, **kwargs, **_session_kwargs(session_id))
+
+    async def chunk_version_restore(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_restore", params, **kwargs, **_session_kwargs(session_id))
+
+    async def chunk_version_retire(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_retire", params, **kwargs, **_session_kwargs(session_id))
+
+    async def chunk_version_diff(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_version_diff", params, **kwargs)
+
+    async def chunk_version_delete(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("chunk_version_delete", params, **kwargs, **_session_kwargs(session_id))
+
+    async def document_rebind(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("document_rebind", params, **kwargs, **_session_kwargs(session_id))
+
+    async def processing_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("processing_status", params, **kwargs)
+
+    async def document_delete(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("document_delete", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_create(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_create", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_list(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_list", params, **kwargs)
+
+    async def entity_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_get", params, **kwargs)
+
+    async def entity_update(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_update", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_text_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> EntityTextGetResult:
+        """Raw public invocation preserving scalar or list text results."""
+        return await self.call("entity_text_get", params, **kwargs)
+
+    async def entity_content_get(
+        self, ids: list[str], as_file: bool = False, **kwargs: Any
+    ) -> Any:
+        return await self.call(
+            "entity_content_get", {"ids": list(ids), "as_file": as_file}, **kwargs
+        )
+
+    async def entity_content_get_download(
+        self, receipt: Mapping[str, Any], **kwargs: Any
+    ) -> Any:
+        return await self.transfer_download_begin(receipt["download"], **kwargs)
+
+    async def entity_rebind_owner(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_rebind_owner", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_owner_tree(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_owner_tree", params, **kwargs)
+
+    async def entity_soft_delete(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_soft_delete", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_undelete(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_undelete", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_hard_delete(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("entity_hard_delete", params, **kwargs, **_session_kwargs(session_id))
+
+    async def entity_references(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_references", params, **kwargs)
+
+    async def chunk_query_search(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_query_search", params, **kwargs)
+
+    async def semantic_relations(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("semantic_relations", params, **kwargs)
+
+    async def semantic_chunk_metadata_update(
+        self,
+        params: Mapping[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        return await self.call("semantic_chunk_metadata_update", params, **kwargs, **_session_kwargs(session_id))
+
+    async def corpus_audit(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("corpus_audit", params, **kwargs)
+
+    async def embeddings_rebuild(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("embeddings_rebuild", params, **kwargs)
+
+    async def help(
+        self,
+        cmdname: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        request = _merge_params(params, kwargs)
+        if cmdname is not None:
+            if "cmdname" in request:
+                raise ValueError("cmdname supplied twice")
+            request["cmdname"] = cmdname
+        return await self.call("help", request)
+
+    async def health(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("health", params, **kwargs)
+
+    async def info(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("info", params, **kwargs)
+
+    async def uuid4(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("uuid4", params, **kwargs)
+
+    async def config(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("config", params, **kwargs)
+
+    async def reload(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("reload", params, **kwargs)
+
+    async def settings(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("settings", params, **kwargs)
+
+    async def load(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("load", params, **kwargs)
+
+    async def unload(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("unload", params, **kwargs)
+
+    async def plugins(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("plugins", params, **kwargs)
+
+    async def transport_management(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transport_management", params, **kwargs)
+
+    async def proxy_registration(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("proxy_registration", params, **kwargs)
+
+    async def roletest(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("roletest", params, **kwargs)
+
+    async def transfer_upload_begin(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_begin", params, **kwargs)
+
+    async def transfer_upload_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_status", params, **kwargs)
+
+    async def transfer_upload_complete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_complete", params, **kwargs)
+
+    async def transfer_download_begin(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_download_begin", params, **kwargs)
+
+    async def transfer_download_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_download_status", params, **kwargs)
+
+    async def backup_emergency(self) -> BackupEmergencyResult:
+        """Save an explicit independent FULL salvage archive and await its final result."""
+        return cast(BackupEmergencyResult, await self.call("backup_emergency", {}))
+
+    async def backup_run(
+        self,
+        *,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+        dry_run: bool | _Omitted = _OMITTED,
+    ) -> BackupRunResult:
+        """Create or preview a backup using the configured repository.
+
+        Omitted options stay off the wire, so server configuration and the
+        command's ``dry_run=False`` default remain authoritative. Explicit
+        ``catalog_directory=None`` is sent as JSON null, which also means the
+        configured catalog directory. Queued delivery is handled by the
+        adapter exactly once.
+        """
+
+        result = await self.call(
+            "backup_run",
+            _provided_params(
+                catalog_directory=catalog_directory,
+                dry_run=dry_run,
+            ),
+        )
+        return cast(BackupRunResult, result)
+
+    async def backup_status(
+        self,
+        *,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+    ) -> BackupStatusResult:
+        """Read backup configuration, worker state, and journal progress."""
+
+        result = await self.call(
+            "backup_status",
+            _provided_params(catalog_directory=catalog_directory),
+        )
+        return cast(BackupStatusResult, result)
+
+    async def backup_points(
+        self,
+        *,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+    ) -> BackupPointsResult:
+        """List committed saved points in package order."""
+
+        result = await self.call(
+            "backup_points",
+            _provided_params(catalog_directory=catalog_directory),
+        )
+        return cast(BackupPointsResult, result)
+
+    async def backup_inspect(
+        self,
+        *,
+        point: str,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+    ) -> BackupInspectResult:
+        """Inspect a saved point's chain, files, and restorable state."""
+
+        result = await self.call(
+            "backup_inspect",
+            _provided_params(
+                point=point,
+                catalog_directory=catalog_directory,
+            ),
+        )
+        return cast(BackupInspectResult, result)
+
+    async def backup_restore(
+        self,
+        *,
+        point: str,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+        dry_run: bool | _Omitted = _OMITTED,
+        replace: bool | _Omitted = _OMITTED,
+    ) -> BackupRestoreResult:
+        """Restore a saved point, or preview the restore when ``dry_run`` is true.
+
+        Omitted booleans preserve the server's false defaults. The adapter
+        owns queued delivery and final-result polling.
+        """
+
+        result = await self.call(
+            "backup_restore",
+            _provided_params(
+                point=point,
+                catalog_directory=catalog_directory,
+                dry_run=dry_run,
+                replace=replace,
+            ),
+        )
+        return cast(BackupRestoreResult, result)
+
+    async def backup_recover_catalog(
+        self,
+        *,
+        destination: str,
+        catalog_copy: str,
+        catalog_directory: str | None | _Omitted = _OMITTED,
+        dry_run: bool | _Omitted = _OMITTED,
+    ) -> BackupRecoverCatalogResult:
+        """Recover a catalog copy to a new destination without activating it.
+
+        Omitted options preserve the configured catalog and server default.
+        The adapter owns queued delivery and final-result polling.
+        """
+
+        result = await self.call(
+            "backup_recover_catalog",
+            _provided_params(
+                destination=destination,
+                catalog_copy=catalog_copy,
+                catalog_directory=catalog_directory,
+                dry_run=dry_run,
+            ),
+        )
+        return cast(BackupRecoverCatalogResult, result)
+
+    async def create_document(
+        self,
+        request: DocumentCreateRequest,
+        *,
+        source_path: str | None = None,
+        filename: str | None = None,
+        session_id: str | None = None,
+    ) -> DocumentCreateResult:
+        params = await self._write_params(request, source_path=source_path, filename=filename)
+        return await self._execute("document_create", _with_session(params, session_id), DocumentCreateResult)
+
+    async def update_document(
+        self,
+        request: DocumentUpdateRequest,
+        *,
+        source_path: str | None = None,
+        filename: str | None = None,
+        session_id: str | None = None,
+    ) -> DocumentUpdateResult:
+        params = await self._write_params(request, source_path=source_path, filename=filename)
+        return await self._execute("document_update", _with_session(params, session_id), DocumentUpdateResult)
+
+    async def chunk_document(
+        self, request: DocumentChunkRequest, *, session_id: str | None = None
+    ) -> DocumentChunkResult:
+        return await self._execute("document_chunk", _with_session(request.to_params(), session_id), DocumentChunkResult)
+
+    async def rebind_document(
+        self, request: DocumentRebindRequest, *, session_id: str | None = None
+    ) -> DocumentRebindResult:
+        return await self._execute(
+            "document_rebind", _with_session(request.to_params(), session_id), DocumentRebindResult
+        )
+
+    async def get_processing_status(
+        self, request: ProcessingStatusRequest
+    ) -> ProcessingStatusResult:
+        return await self._execute(
+            "processing_status", request.to_params(), ProcessingStatusResult
+        )
+
+    async def get_document(self, request: DocumentGetRequest) -> DocumentGetResult:
+        return await self._execute("document_get", request.to_params(), DocumentGetResult)
+
+    async def get_chapter(self, request: ChapterGetRequest) -> ChapterGetResult:
+        return await self._execute("chapter_get", request.to_params(), ChapterGetResult)
+
+    async def get_chapter_text(
+        self,
+        request: ChapterTextGetRequest,
+    ) -> TextReconstructionResult:
+        """Reconstruct chapter text (chapter_text_get).
+
+        The request field text_offset (0 to 1000000000, default absent means 0) selects the
+        start in unicode code points. The result attributes total_chars, total_sha256,
+        text_offset and next_text_offset allow continuation: repeat the call with
+        text_offset=next_text_offset until next_text_offset is None.
+        """
+        return await self._execute(
+            "chapter_text_get",
+            request.to_params(),
+            TextReconstructionResult,
+        )
+
+    async def reconstruct_source_file(
+        self,
+        request: SourceFileReconstructRequest,
+    ) -> TextReconstructionResult:
+        """Reconstruct stored source text (source_file_reconstruct).
+
+        The request field text_offset (0 to 1000000000, default absent means 0) selects the
+        start in unicode code points. The result attributes total_chars, total_sha256,
+        text_offset and next_text_offset allow continuation: repeat the call with
+        text_offset=next_text_offset until next_text_offset is None.
+        """
+        return await self._execute(
+            "source_file_reconstruct",
+            request.to_params(),
+            TextReconstructionResult,
+        )
+
+    async def list_chunk_versions(
+        self,
+        request: "ChunkVersionListRequest",
+    ) -> "ChunkVersionListResult":
+        return await self._execute(
+            "chunk_version_list",
+            request.to_params(),
+            _model_type("ChunkVersionListResult"),
+        )
+
+    async def get_chunk_history(
+        self,
+        request: "ChunkHistoryRequest",
+    ) -> "ChunkHistoryResult":
+        return await self._execute(
+            "chunk_history",
+            request.to_params(),
+            _model_type("ChunkHistoryResult"),
+        )
+
+    async def get_chunk_version(
+        self,
+        request: "ChunkVersionGetRequest",
+    ) -> "ChunkVersionGetResult":
+        return await self._execute(
+            "chunk_version_get",
+            request.to_params(),
+            _model_type("ChunkVersionGetResult"),
+        )
+
+    async def add_chunk_version(
+        self,
+        request: "ChunkVersionAddRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionAddResult":
+        return await self._execute(
+            "chunk_version_add",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionAddResult"),
+        )
+
+    async def update_chunk_version(
+        self,
+        request: "ChunkVersionUpdateRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionUpdateResult":
+        return await self._execute(
+            "chunk_version_update",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionUpdateResult"),
+        )
+
+    async def set_current_chunk_version(
+        self,
+        request: "ChunkVersionSetCurrentRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionSetCurrentResult":
+        return await self._execute(
+            "chunk_version_set_current",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionSetCurrentResult"),
+        )
+
+    async def restore_chunk_version(
+        self,
+        request: "ChunkVersionRestoreRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionRestoreResult":
+        return await self._execute(
+            "chunk_version_restore",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionRestoreResult"),
+        )
+
+    async def retire_chunk_version(
+        self,
+        request: "ChunkVersionRetireRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionRetireResult":
+        return await self._execute(
+            "chunk_version_retire",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionRetireResult"),
+        )
+
+    async def diff_chunk_versions(
+        self,
+        request: "ChunkVersionDiffRequest",
+    ) -> "ChunkVersionDiffResult":
+        return await self._execute(
+            "chunk_version_diff",
+            request.to_params(),
+            _model_type("ChunkVersionDiffResult"),
+        )
+
+    async def delete_chunk_version(
+        self,
+        request: "ChunkVersionDeleteRequest",
+        *,
+        session_id: str | None = None,
+    ) -> "ChunkVersionDeleteResult":
+        return await self._execute(
+            "chunk_version_delete",
+            _with_session(request.to_params(), session_id),
+            _model_type("ChunkVersionDeleteResult"),
+        )
+
+    async def get_paragraph(self, request: ParagraphGetRequest) -> ParagraphGetResult:
+        return await self._execute("paragraph_get", request.to_params(), ParagraphGetResult)
+
+    async def get_paragraph_by_number(
+        self,
+        request: ParagraphGetByNumberRequest,
+    ) -> ParagraphGetByNumberResult:
+        return await self._execute(
+            "paragraph_get_by_number",
+            request.to_params(),
+            ParagraphGetByNumberResult,
+        )
+
+    async def delete_document(
+        self, request: DocumentDeleteRequest, *, session_id: str | None = None
+    ) -> DocumentDeleteResult:
+        return await self._execute("document_delete", _with_session(request.to_params(), session_id), DocumentDeleteResult)
+
+    async def list_entities(self, request: EntityListRequest) -> EntityListResult:
+        return await self._execute("entity_list", request.to_params(), EntityListResult)
+
+    async def get_entity(self, request: EntityGetRequest) -> EntityGetResult:
+        return await self._execute("entity_get", request.to_params(), EntityGetResult)
+
+    async def get_entity_text(self, request: EntityTextGetRequest) -> EntityTextGetResult:
+        """Return canonical text, preserving scalar/list shape, order and duplicates."""
+        result = await self.call("entity_text_get", request.to_params())
+        batch = isinstance(request.entity_id, list) or "," in request.entity_id
+        if batch:
+            count = len(request.entity_id) if isinstance(request.entity_id, list) else len(request.entity_id.split(","))
+            if not isinstance(result, list) or len(result) != count or any(not isinstance(item, str) for item in result):
+                raise TypeError("entity_text_get batch result must be an ordered list of strings matching the request count")
+        elif not isinstance(result, str):
+            raise TypeError("entity_text_get scalar result must be a string")
+        return result
+
+    async def soft_delete_entities(
+        self, request: EntityIdsRequest, *, session_id: str | None = None
+    ) -> EntityLifecycleResult:
+        return await self._execute("entity_soft_delete", _with_session(request.to_params(), session_id), EntityLifecycleResult)
+
+    async def undelete_entities(
+        self, request: EntityIdsRequest, *, session_id: str | None = None
+    ) -> EntityLifecycleResult:
+        return await self._execute("entity_undelete", _with_session(request.to_params(), session_id), EntityLifecycleResult)
+
+    async def hard_delete_entities(
+        self, request: EntityIdsRequest, *, session_id: str | None = None
+    ) -> EntityLifecycleResult:
+        return await self._execute("entity_hard_delete", _with_session(request.to_params(), session_id), EntityLifecycleResult)
+
+    async def get_entity_references(self, request: EntityReferencesRequest) -> EntityReferencesResult:
+        return await self._execute("entity_references", request.to_params(), EntityReferencesResult)
+
+    async def get_entity_owner_tree(self, request: EntityOwnerTreeRequest) -> EntityOwnerTreeResult:
+        return await self._execute("entity_owner_tree", request.to_params(), EntityOwnerTreeResult)
+
+    async def update_semantic_chunk_metadata(
+        self,
+        request: SemanticChunkMetadataUpdateRequest,
+        *,
+        session_id: str | None = None,
+    ) -> SemanticChunkMetadataUpdateResult:
+        return await self._execute(
+            "semantic_chunk_metadata_update",
+            _with_session(request.to_params(), session_id),
+            SemanticChunkMetadataUpdateResult,
+        )
+
+    async def search(self, query: ChunkQuery) -> SearchResult:
+        return await self._execute("chunk_query_search", {"query": _dump_query(query)}, SearchResult)
+
+    async def upload_file(
+        self,
+        source_path: str,
+        *,
+        filename: str | None = None,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Any = None,
+    ) -> Mapping[str, Any]:
+        """Upload a file through the injected adapter and return a transfer reference."""
+
+        upload = getattr(self._adapter_client, "upload_file", None)
+        if upload is None:
+            raise TypeError("adapter client does not expose upload_file")
+        receipt = await upload(
+            source_path,
+            filename=filename,
+            compression=compression,
+            chunk_size=chunk_size,
+            on_progress=on_progress,
+        )
+        return _completed_transfer_reference(receipt)
+
+    async def _write_params(
+        self,
+        request: DocumentCreateRequest | DocumentUpdateRequest,
+        *,
+        source_path: str | None,
+        filename: str | None,
+    ) -> dict[str, Any]:
+        if source_path is None:
+            if request.raw_text is None and request.transferred_file is None:
+                raise ValueError("raw_text, transferred_file, or source_path is required")
+            return request.to_params()
+        transfer_ref = await self.upload_file(source_path, filename=filename)
+        params = request.to_params()
+        params.pop("raw_text", None)
+        params["transferred_file"] = transfer_ref
+        return params
+
+    async def _execute(
+        self, command: str, params: Mapping[str, Any], result_type: type[T]
+    ) -> T:
+        response = await self._dispatch(command, dict(params))
+        payload = _unwrap_response(response, expect_mapping=True)
+        if hasattr(result_type, "from_payload"):
+            return result_type.from_payload(payload)  # type: ignore[attr-defined,no-any-return]
+        return result_type(**payload)  # type: ignore[call-arg]
+
+    async def _dispatch(self, command: str, params: Mapping[str, Any]) -> Any:
+        """Detach accepted writes, observe their jobs, and fetch the final RPC result."""
+        dispatch = self._adapter_client.execute_command_unified
+        try:
+            signature = inspect.signature(dispatch)
+            supports_manual = "manual_event_handling" in signature.parameters or any(
+                parameter.kind is inspect.Parameter.VAR_KEYWORD
+                for parameter in signature.parameters.values()
+            )
+        except (TypeError, ValueError):
+            supports_manual = False
+        if (
+            command not in {"document_create", "document_update", "document_import"}
+            or not supports_manual
+        ):
+            return await dispatch(command, dict(params))
+
+        admission = await dispatch(
+            command,
+            dict(params),
+            expect_queue=True,
+            auto_poll=False,
+            timeout=30.0,
+            status_hook=self._event_callback,
+            manual_event_handling=False,
+        )
+        if not isinstance(admission, Mapping) or admission.get("mode") != "queued":
+            return admission
+        job_id = str(admission.get("job_id") or "")
+        if not job_id:
+            raise RuntimeError(f"queued command {command!r} returned no job_id")
+        terminal: Mapping[str, Any]
+        try:
+            try:
+                waiter = getattr(self._adapter_client, "wait_for_job", None)
+                if waiter is None:
+                    terminal = await self._recover_job(job_id)
+                else:
+                    terminal = await waiter(
+                        job_id, timeout=0, on_event=self._event_callback
+                    )
+            except Exception as first_error:
+                try:
+                    terminal = await self._recover_job(job_id)
+                except Exception as recovery_error:
+                    raise RuntimeError(
+                        f"queued command {command!r} lost WebSocket for job {job_id}; "
+                        f"recovery failed: {recovery_error}"
+                    ) from first_error
+        except asyncio.CancelledError:
+            # Explicit caller cancellation stops the job; observer loss never does.
+            await self.queue_stop_job(job_id=job_id)
+            raise
+        event_name = str(terminal.get("event", "")).lower()
+        status = str(terminal.get("status", "")).lower()
+        if event_name not in {"command_completed", "job_completed"} and status != "completed":
+            fetch_error: Exception | None = None
+            try:
+                failed = await self._fetch_job_result(job_id)
+            except Exception as exc:
+                fetch_error = exc
+            else:
+                if isinstance(failed, Mapping) and failed.get("success") is False:
+                    typed = _error_from_payload(failed)
+                    if _lock_code(typed) is not None:
+                        raise _client_error(typed)
+            raise RuntimeError(
+                f"queued command {command!r} failed for job {job_id}: {dict(terminal)!r}"
+            ) from fetch_error
+        result = await self._fetch_job_result(job_id)
+        return {
+            "mode": "queued",
+            "job_id": job_id,
+            "command": command,
+            "result": result,
+        }
+
+    async def _recover_job(self, job_id: str) -> Mapping[str, Any]:
+        waiter = getattr(self._adapter_client, "wait_for_job", None)
+        status_getter = getattr(self._adapter_client, "queue_get_job_status", None)
+        if waiter is not None:
+            try:
+                return await waiter(job_id, timeout=0, on_event=self._event_callback)
+            except Exception:
+                if status_getter is None:
+                    raise
+        if status_getter is None:
+            raise RuntimeError("adapter exposes neither wait_for_job nor queue_get_job_status")
+        while True:
+            status = await status_getter(job_id)
+            payload = status.get("data", status) if isinstance(status, Mapping) else status
+            if isinstance(payload, Mapping):
+                state = str(payload.get("status", "")).lower()
+                if state in {"completed", "failed", "stopped", "cancelled"}:
+                    return {
+                        "event": "job_completed" if state == "completed" else "job_failed",
+                        "status": state,
+                        "job_id": job_id,
+                    }
+            await asyncio.sleep(1.0)
+
+    async def _fetch_job_result(self, job_id: str) -> Any:
+        fetcher = getattr(self._adapter_client, "fetch_command_session_result", None)
+        if fetcher is not None:
+            return _final_result_payload(await fetcher(job_id))
+        getter = getattr(self._adapter_client, "queue_get_job_status", None)
+        if getter is None:
+            raise RuntimeError(f"adapter cannot fetch final result for job {job_id}")
+        return _final_result_payload(await getter(job_id))
+
+
+def _merge_params(
+    params: Mapping[str, Any] | None,
+    kwargs: Mapping[str, Any],
+) -> dict[str, Any]:
+    if params is None:
+        result: dict[str, Any] = {}
+    elif isinstance(params, Mapping):
+        result = dict(params)
+    else:
+        raise TypeError("params must be a mapping")
+    duplicate = sorted(set(result).intersection(kwargs))
+    if duplicate:
+        raise ValueError(f"duplicate parameters: {', '.join(duplicate)}")
+    result.update(kwargs)
+    return result
+
+
+def _session_kwargs(session_id: str | None) -> dict[str, Any]:
+    """The keyword carrying ``session_id``; only ``None`` is omitted, nothing is validated."""
+
+    return {} if session_id is None else {"session_id": session_id}
+
+
+def _with_session(params: Mapping[str, Any], session_id: str | None) -> dict[str, Any]:
+    """Copy of ``params`` with ``session_id`` added unchanged when it is not ``None``."""
+
+    result = dict(params)
+    if session_id is not None:
+        result["session_id"] = session_id
+    return result
+
+
+def _provided_params(**values: Any) -> dict[str, Any]:
+    """Build a command payload while preserving explicit ``None`` values."""
+
+    return {name: value for name, value in values.items() if not isinstance(value, _Omitted)}
+
+
+def _final_result_payload(value: Any) -> Any:
+    """Normalize queue status wrappers while retaining the server result."""
+    if isinstance(value, Mapping) and "result" in value:
+        value = value["result"]
+    if isinstance(value, Mapping) and isinstance(value.get("data"), Mapping):
+        return value["data"]
+    return value
+
+
+def _model_type(name: str) -> type[Any]:
+    """Resolve concurrently added public models without importing them eagerly."""
+
+    from . import models
+
+    return getattr(models, name)
+
+
+def _unwrap_response(response: Any, *, expect_mapping: bool = False) -> Any:
+    if isinstance(response, Mapping):
+        if _is_jsonrpc_envelope(response):
+            if "error" in response:
+                return _unwrap_response(
+                    {"success": False, "error": response["error"]},
+                    expect_mapping=expect_mapping,
+                )
+            return _unwrap_response(response["result"], expect_mapping=expect_mapping)
+        if _is_adapter_envelope(response):
+            return _unwrap_response(response["result"], expect_mapping=expect_mapping)
+        if _is_queue_status_payload(response):
+            return _unwrap_response(response["result"], expect_mapping=expect_mapping)
+        if response.get("success") is False:
+            raise _client_error(_error_from_payload(response))
+        data = response.get("data", response)
+        if isinstance(data, Mapping) or not expect_mapping:
+            return data
+    data = getattr(response, "data", response)
+    success = getattr(response, "success", True)
+    if success is False:
+        raise _client_error(
+            ServerError(
+                code=str(getattr(response, "code", "SERVER_ERROR")),
+                message=str(getattr(response, "error", "command failed")),
+                details=getattr(response, "details", None),
+            )
+        )
+    if isinstance(data, Mapping) or not expect_mapping:
+        return data
+    raise TypeError("adapter response data must be an object")
+
+
+def _is_adapter_envelope(response: Mapping[str, Any]) -> bool:
+    return "mode" in response and "result" in response
+
+
+def _is_jsonrpc_envelope(response: Mapping[str, Any]) -> bool:
+    return response.get("jsonrpc") == "2.0" and (
+        "result" in response or "error" in response
+    )
+
+
+def _is_queue_status_payload(response: Mapping[str, Any]) -> bool:
+    result = response.get("result")
+    return (
+        "job_id" in response
+        and "command" in response
+        and isinstance(result, Mapping)
+    )
+
+
+def _error_from_payload(payload: Mapping[str, Any]) -> ServerError:
+    details = payload.get("details")
+    error = payload.get("error")
+    if isinstance(error, Mapping):
+        values = dict(error)
+        values.setdefault("code", str(payload.get("code", "SERVER_ERROR")))
+        values.setdefault("message", str(values.get("message", "command failed")))
+        return ServerError.from_payload(values)
+    return ServerError(
+        code=str(payload.get("code", "SERVER_ERROR")),
+        message=str(error or "command failed"),
+        details=details if isinstance(details, Mapping) else None,
+    )
+
+
+def _completed_transfer_reference(receipt: Any) -> Mapping[str, Any]:
+    completed = (
+        receipt.get("completed")
+        if isinstance(receipt, Mapping)
+        else getattr(receipt, "completed", False)
+    )
+    if completed is not True:
+        raise DocStoreClientError(
+            ServerError(code="TRANSFER_INCOMPLETE", message="file transfer did not complete")
+        )
+    if isinstance(receipt, Mapping):
+        transfer_id = receipt.get("transfer_id") or receipt.get("id")
+        values = dict(receipt)
+    else:
+        transfer_id = getattr(receipt, "transfer_id", None) or getattr(receipt, "id", None)
+        values = {
+            key: getattr(receipt, key, None)
+            for key in (
+                "transfer_id",
+                "id",
+                "filename",
+                "path",
+                "size_bytes",
+                "checksum_algorithm",
+                "checksum_value",
+                "compression",
+                "chunk_size",
+                "status",
+                "plaintext_size_bytes",
+            )
+        }
+    values["transfer_id"] = transfer_id
+    result = {
+        key: value
+        for key, value in values.items()
+        if key != "completed" and value is not None and key != "id"
+    }
+    if not result:
+        raise DocStoreClientError(
+            ServerError(code="TRANSFER_REFERENCE_MISSING", message="file transfer reference is missing")
+        )
+    return result
+
+
+def _dump_query(query: ChunkQuery) -> Mapping[str, Any]:
+    if hasattr(query, "model_dump"):
+        return query.model_dump(mode="python", exclude_none=True, exclude_unset=True)
+    if is_dataclass(query):
+        return {
+            key: value
+            for key, value in query.__dict__.items()
+            if value is not None
+        }
+    if isinstance(query, Mapping):
+        return dict(query)
+    raise TypeError("query must be a chunk_metadata_adapter.ChunkQuery")
+
+
+__all__ = [
+    "DOC_STORE_COMMANDS",
+    "DocStoreClient",
+    "DocStoreClientError",
+    "DocStoreNotFoundError",
+    "FileAlreadyLockedError",
+    "JsonRpcClientLike",
+    "LockServiceUnavailableError",
+    "SessionNotFoundError",
+    "TransferClientLike",
+]