doc-store-client backup methods

DocStoreClient exposes typed wrappers for the six backup commands supported by the server:

All six methods accept the optional catalog_directory. backup_run and backup_restore also accept dry_run; backup_restore accepts replace; backup_recover_catalog accepts dry_run. Omitted options remain absent from the command payload, allowing server configuration and command defaults to apply. Passing catalog_directory=None explicitly sends JSON null, which the server defines as unspecified. Boolean defaults are false on the server.

The methods return the command's data object using the corresponding public TypedDict result type. In particular, backup_points includes committed points only, backup_inspect describes the requested saved point and its chain, and backup_recover_catalog reports activated=False: catalog recovery creates a separate catalog and never switches the active catalog.

Queued commands (backup_run, backup_restore, and backup_recover_catalog) use the injected adapter's normal delivery and final-result handling. The client does not submit a second command or poll the queue a second time. Synchronous commands (backup_status, backup_points, and backup_inspect) return their result directly.

Server parameter and backup-domain errors are surfaced through the adapter response. When an error response is represented by the standard client envelope, DocStoreClientError.error contains a ServerError with its code, message, and details. Adapter transport exceptions continue to propagate from the adapter. The wrappers do not convert failures into success-shaped results.

Use DocStoreClient.call(command, params) when a caller needs to exercise invalid parameters or send a command that has no typed wrapper. The typed methods describe the valid command inputs; the server remains responsible for validating values and path relationships.

Write sessions and lock errors

The 18 raw methods document_create, document_update, document_delete, document_rebind, document_chunk, chunk_version_add, chunk_version_update, chunk_version_set_current, chunk_version_restore, chunk_version_retire, chunk_version_delete, semantic_chunk_metadata_update, entity_create, entity_update, entity_rebind_owner, entity_soft_delete, entity_undelete and entity_hard_delete, and the 15 typed wrappers create_document, update_document, delete_document, rebind_document, chunk_document, add_chunk_version, update_chunk_version, set_current_chunk_version, restore_chunk_version, retire_chunk_version, delete_chunk_version, soft_delete_entities, undelete_entities, hard_delete_entities and update_semantic_chunk_metadata, take a keyword-only session_id with default None. None is not sent; any other value is sent unchanged. The client does not check the format; the server refuses a malformed value with -32602, raised by the adapter. A raw method given session_id as a keyword and inside params raises ValueError (duplicate parameters: session_id).

DocStoreClient keeps no session, so pass session_id on every call, and repeat a CAS write-back with the same session_id. DocStoreClient.call passes a session_id inside params unchanged, the CLI takes session_id inside the --params JSON object (there is no extra flag), and OwnedDocumentCleanup.cleanup and cleanup_all take session_id and pass it to every document_delete. cleanup_all collects failures into one OwnedDocumentCleanupError; call cleanup per document to catch a typed lock error.

document_export and every other non-gated method take no session_id; a session_id sent to them through params is refused by the server with -32602.

A refused write raises one of three errors, all subclasses of DocStoreClientError and importable from doc_store_client:

error.code and the message are kept. A missing field reads as None. Values come from the data mapping in error.details, else from error.details. A refused write changes nothing on the server. A failed queued document_create or document_update job with a lock code raises the typed error as well.

The client never retries a refused write. React to each error yourself:

• FileAlreadyLockedError: another session holds the document. Do not retry blindly; use holder_idle_seconds and seconds_left_before_timeout to decide when to try again.
• SessionNotFoundError: the session is unknown or expired. Open a new CAS session and repeat the call with its id.
• LockServiceUnavailableError: CAS did not answer or answered with an error, and the write was refused. Retry later by your own decision; reason says why.

Missing target

A command whose target does not exist (a document, chapter, paragraph, chunk, entity) is answered by the server with a structured error whose code is NOT_FOUND and whose message contains the missing id. The client raises DocStoreNotFoundError, a subclass of DocStoreClientError importable from doc_store_client:

str(error) is the server message (it contains the id), so callers that read the text keep working; error.error.code is NOT_FOUND. missing_id is read from the error data, else from the id in the message, else None. entity_content_get does not raise: it reports an absent id as an item with error.code NOT_FOUND.