# Rust plugin SDK

This page shows how to write a Bookclerk plugin in Rust with
`bookclerk-plugin-sdk` (`api_version = 3`). A Rust plugin is a native
guest, a binary the host runs in its own jail, or a workerd guest when
compiled to Wasm with the SDK's `workerd` glue. Depend on this crate
alone, never on `bookclerk-plugin-host`, which pulls in the host's
internals.

## Install

```toml
[dependencies]
bookclerk-plugin-sdk = { git = "https://github.com/Bookclerk/bookclerk", package = "bookclerk-plugin-sdk" }
# Database guests also need:
# bookclerk-plugin-sdk = { …, features = ["db"] }
```

| Feature | Purpose |
| --- | --- |
| *(default)* | The Cap'n Proto guest runner, fetch and upload path helpers, the callback tunnel, and the ABI re-exports |
| `db` | SeaORM to Workers RPC DTO helpers for database guests |
| `http` | Native HTTPS through the workerd socket proxy |

## Author model

A native guest implements `PluginWorker` (`describe`, and
`open(invocation, bindings) -> Entrypoints`) and calls `serve`, the
stdin and stdout Cap'n Proto runner. The entrypoints it returns are the
same named entrypoints the other SDKs export as classes: storefront,
storage, remote library, database adapter, CLI, OIDC, metadata, covers,
metadata files, notifier and model plugin (`ai`). The
crate root re-exports the DTOs and helpers a guest needs; prefer
`use bookclerk_plugin_sdk::…` over reaching into submodules.

Identity (`apiVersion`, `id`, capabilities) comes from `plugin.toml`;
`describe` only refines `displayName` and similar fields.

A `[[databases]]` binding is taken from the `open` bindings with
`DatabaseBinding::take_named_from_bindings` and used as on D1
(`prepare`, `bind`, `all`, `first`, `batch`). Its `limits()` returns the
session's `DbCapabilities`; `all()` reads through the session's streamed
budget when it advertises one, `iterate()` walks the same read one row at
a time without holding the whole result, `chunk()` splits a long statement list
into batches that each fit one request, and `write_chunks()` commits those
batches resumably. Any cap that is hit is a
`PluginError` with `PluginErrorCode::LimitExceeded` and a typed `limit()`;
see [Working within database limits](/docs/plugins/database-limits/index.md). A guest's
tests open the same binding with `bookclerk_db_testkit::BindingDatabase`
under `bookclerk_db_testkit::selected_profile()`, so `bookclerk-plugin test .`
runs them under every profile (see
[Testing against the limits](/docs/plugins/database-limits/index.md#testing-against-the-limits)).
A storefront's `scan` can hand its paging to `scan_page(&params, fetch)`,
which slices the store's own pages into replies the host accepts; see
[Paged scans](/docs/plugins/abi/index.md#paged-scans).
[`examples/plugins-echo-native-rust`](https://github.com/Bookclerk/bookclerk/blob/main/examples/plugins-echo-native-rust)
does all of this end to end in its `notes` table.

## The socket proxy

A native guest has no ambient network. It receives an inherited link
(`fd:<n>` on Unix, `handle:<n>` on Windows) in `BOOKCLERK_SOCKET_PROXY`
and multiplexes CONNECT streams over it with the `mux` module; `net`
opens mediated TCP sockets, the equivalent of Workers `connect()`, and
the `http` feature puts an HTTPS client on top. Only hosts the plugin's
`[capabilities.network]` grants name are reachable.

### Large downloads

A storefront that writes a title into the `fetchTitle` work folder should
download it with `bookclerk_plugin_sdk::download::Download` (feature
`http`) rather than reading the body into memory. It streams the body to
`<dest>.part` and, when the connection drops, stalls (no data for the idle
timeout, 60 seconds by default) or the CDN answers `408`, `429` or `5xx`,
asks again for only the missing bytes with `Range`, and `If-Range` when
the CDN sent an `ETag` or `Last-Modified`. A CDN that ignores the range
gets the whole file again; an answer for another range or a changed
length starts over, so bytes are never spliced from two versions.

```rust
use bookclerk_plugin_sdk::download::Download;

let done = Download::new()
    .expected_size(store_size) // when the store states it
    .to_file(&work_dir.join("book.m4b"), || http.get(&url))
    .await?;
```

The closure builds a fresh request for each attempt (URL, auth, cookies);
the download adds the range headers. `DownloadError::is_transient` tells a
failure worth another `fetchTitle` from a refusal. The decisions
themselves are the sans-IO functions in `bookclerk_plugin_sdk::resume`,
which a guest with its own HTTP stack can reuse.

> [!NOTE]
> The host clears the work folder after every `fetchTitle`, so a download
> resumes within one call. A partial kept across failed attempts or a
> host restart is not supported yet.

Older SDKs that only opened a pathname or named-pipe proxy cannot reach
the host and fail closed; rebuild guests against this SDK. Pathname,
`abstract:` and `\\.\pipe\` forms remain for tests.

## Pushed sockets

A plugin that declares `[sockets]` (see
[Pushed sockets](/docs/plugins/abi/index.md#pushed-sockets-sockets)) receives `Sockets`
on `Bindings::sockets` in `open` and may return a `SocketHandler` on
`Entrypoints::socket_handler`. The host holds each connection, answers the
declared heartbeats and calls the handler once per message, so the plugin
process may sleep in between. The `sockets` module wraps one socket id
in `HostWebSocket` (`send_text`, `close`, `serialize_attachment`,
`deserialize_attachment`), the same surface the TypeScript and Python
SDKs give their handlers, and `text_heartbeat("2", "3")` builds a
heartbeat pair. Attachments are JSON of at most 2 KiB, so a socket reads
the same from every SDK. `SocketHandler::message` returns a `SocketMessageOk`; a remote
library sets `poll_events` when a message announced a new user, and the
host calls `poll_events` right away instead of at its next scheduled
poll. The Audiobookshelf plugin, written in TypeScript, is a worked
example of the same conversation
(`crates/bookclerk-plugins/optional/integration-audiobookshelf/src/push.ts`).

## Inbound webhooks

A plugin that declares `[[webhooks]]` (see
[Inbound webhooks](/docs/plugins/abi/index.md#inbound-webhooks-webhooks)) receives
`Webhooks` on `Bindings::webhooks` in `open` (`url`, `pull` and `ack`,
with `WebhookPullRequest` and `WebhookAckRequest`), and may return a
`WebhookHandler` on `Entrypoints::webhook_handler`, whose `delivered` the
host calls on a running guest once a request is stored.
`bookclerk_plugin_abi::webhooks` has the checks the host applies, so a
plugin can validate a pull before sending it.

## Author tools

The `bookclerk-plugin` author CLI (`check`, `fmt`, `sync-embed`,
`package`, `smoke` and `test`) lives in the separate `bookclerk-plugin-tools`
crate, so a guest that depends on this SDK never links
`bookclerk-workerd`. Install it once, then run it from the plugin's
directory:

```bash
cargo install --git https://github.com/Bookclerk/bookclerk bookclerk-plugin-tools
cargo install --git https://github.com/Bookclerk/bookclerk bookclerk-db-testkit  # the kit `test` serves
bookclerk-plugin check .
bookclerk-plugin smoke .
bookclerk-plugin test .    # the plugin's suite under every database profile
```

Inside a Bookclerk checkout, `cargo plugin -- check <dir>` is an alias
for the same binary (`.cargo/config.toml`).

## Next steps

- [plugin.toml](/docs/plugins/manifest/index.md): declare the entrypoints the guest
  serves.
- [Entrypoints, events and the ABI](/docs/plugins/abi/index.md): every method and
  event in detail.
- [`bookclerk_plugin_abi`](/docs/internals/crates/bookclerk_plugin_abi/index.md)
  and [`bookclerk_plugin_manifest`](/docs/internals/crates/bookclerk_plugin_manifest/index.md):
  the ABI and manifest crates the SDK re-exports.
- [Try the Echo example](/docs/plugins/index.md#try-the-echo-example): complete
  native and workerd Rust plugins under `examples/`.

## Reference

The sections below are generated from the crate's source: the crate
root, with its items and re-exports, and one page per public module.

Guest-only Bookclerk plugin SDK.

For third-party Rust plugin authors of native and workerd plugins
(`api_version = 3`). Depend on this crate from a standalone plugin
workspace, not on the host `bookclerk-plugin-host` crate. The Rust SDK
guide (`docs/plugins/sdk/rust/README.md`, published with this reference)
covers the author model, the socket proxy and the author CLI; the entry
points are:

| Need | Entry point |
| --- | --- |
| Native guest (`runtime = "native"`) | [`PluginWorker`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginworker) / [`serve`](#serve) (`api_version = 3`) |
| Fetch / upload work paths | [`fetch_work_dir`](#fetch_work_dir), [`upload_file_path`](#upload_file_path) |
| Mediated TCP sockets | [`connect_socket`](/docs/plugins/sdk/rust/net/index.md#connect) / [`net`](/docs/plugins/sdk/rust/net/index.md) (Workers `connect()` equivalent) |
| Host-held WebSockets that let the plugin sleep (`[sockets]`) | [`sockets`](/docs/plugins/sdk/rust/sockets/index.md) / [`HostWebSocket`](/docs/plugins/sdk/rust/sockets/index.md#hostwebsocket) |
| Native HTTPS through the socket proxy | feature `http` → `http::Client` |
| Resumable large downloads (store audio, archives) | feature `http` → `download::Download`; decisions in [`resume`](/docs/plugins/sdk/rust/resume/index.md) |
| OAuth callback without guest listen | [`callback_tunnel`](/docs/plugins/sdk/rust/callback_tunnel/index.md) |
| Workerd / Wasm guests | [`workerd`](/docs/plugins/sdk/rust/workerd/index.md) + npm `@bookclerk/plugin-sdk` |
| ABI DTOs / method names | [`protocol`](/docs/plugins/sdk/rust/protocol/index.md) (re-exports `bookclerk-plugin-abi`) |
| Database guest session / atomic execution | feature `db` → [`database_adapter`](/docs/plugins/sdk/rust/database_adapter/index.md) |
| Author CLI (`check` / `fmt` / `sync-embed` / `package` / `smoke`) | separate crate `bookclerk-plugin-tools` (`cargo plugin`) |

Crate-root `pub use` items are the stable import surface for guests
(describe-metadata DTOs, [`PluginError`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#pluginerror), fetch path helpers, tunnel
types). Prefer `use bookclerk_plugin_sdk::…` over reaching into
submodules unless you need module-level docs.

| Item | Kind | Summary |
| --- | --- | --- |
| [`ChunkCaps`](#chunkcaps) | struct | Caps `DatabaseBinding::chunk` splits a batch by when the session's limits are not to be used. |
| [`D1ExecResult`](#d1execresult) | struct | Cloudflare `D1ExecResult`. |
| [`D1Meta`](#d1meta) | struct | Cloudflare `D1Result::meta` shape. |
| [`D1Result`](#d1result) | struct | Cloudflare `D1Result` projection. |
| [`DatabaseBinding`](#databasebinding) | struct | Host-mediated typed SQL surface for plugin guests. |
| [`DatabaseBindingOptions`](#databasebindingoptions) | struct | Options for `DatabaseBinding`. |
| [`PreparedStatement`](#preparedstatement) | struct | Cloudflare-style prepared statement. |
| [`RetryToken`](#retrytoken) | struct | Explicit retry identity: reuse both `operationId` and `requestHash`. |
| [`RowStream`](#rowstream) | struct | Rows of one read, handed out one at a time (`PreparedStatement::iterate`). |
| [`WriteChunksError`](#writechunkserror) | struct | A `DatabaseBinding::write_chunks` run that failed part way. |
| [`WriteProgress`](#writeprogress) | struct | Where a `DatabaseBinding::write_chunks` run stands. |
| [`FetchWorkDir`](#fetchworkdir) | struct | An open fetch work directory received from the host for one `fetchTitle` call. |
| [`UploadFile`](#uploadfile) | struct | An open upload file received from the host for one `putFile` call. |
| [`StorePage`](#storepage) | struct | One page of a storefront's own library listing, as the plugin fetched it. |
| [`SdkError`](#sdkerror) | enum | Errors from the guest stdio loop and SDK helpers (not plugin business logic). |
| [`db_value_from_sea`](#db_value_from_sea) | function | Fallible SeaORM → `bookclerk_plugin_abi::DbValue` bridge. |
| [`proxy_rows_from_typed`](#proxy_rows_from_typed) | function | Builds SeaORM proxy rows from a typed statement result. |
| [`chunk_indexes`](#chunk_indexes) | function | Greedy split of `typed` into index runs that each fit one request. |
| [`execute_reply_to_d1_results`](#execute_reply_to_d1_results) | function | Maps a typed execute reply to Cloudflare `D1Result` per statement. |
| [`statement_result_to_d1_result`](#statement_result_to_d1_result) | function | Maps one typed statement result to Cloudflare `D1Result`. |
| [`write_chunks_operation_id`](#write_chunks_operation_id) | function | The operation id `DatabaseBinding::write_chunks` sends for the batch that starts at `offset` of the write named `key`. |
| [`fetch_work_dir`](#fetch_work_dir) | function | Resolves the directory a `fetchTitle` call should write into. |
| [`upload_file_path`](#upload_file_path) | function | Resolves the local file path for a `putFile` call. |
| [`decode_json`](#decode_json) | function | Deserialize a role-method JSON argument. |
| [`encode_json`](#encode_json) | function | Serialize a role-method JSON result. |
| [`encode_atomic_result`](#encode_atomic_result) | function | Encodes an atomic result; an oversized scalar after commit is `unavailable`. |
| [`page_rows`](#page_rows) | function | Page a JSON array of rows. `limit == 0` means `MAX_LIST_PAGE`. |
| [`manifest_capabilities`](#manifest_capabilities) | function | Parses `plugin.toml` source and returns the `PluginCapabilities` a guest must advertise from `describe()`. |
| [`manifest_media`](#manifest_media) | function | Parses `plugin.toml` source and returns the `MediaSupport` a guest must advertise from `describe()`. |
| [`fd_proc_path`](#fd_proc_path) | function | Builds the OS path that refers to an open descriptor by number. |
| [`recv_passed_fd`](#recv_passed_fd) | function | Receives one file descriptor from the host side channel (SCM_RIGHTS). |
| [`scan_page`](#scan_page) | function | Answers one `scan` call from the storefront's own pages. |
| [`serve`](#serve) | function | Serves a `PluginWorker` on stdin/stdout (Cap'n Proto RPC). |
| [`Result`](#result) | type alias | Result alias for guest helpers that fail with `SdkError`. |
| [`MAX_WRITE_KEY_BYTES`](#max_write_key_bytes) | constant | Longest `key` `DatabaseBinding::write_chunks` accepts, in bytes. |
| [`PLUGIN_FD_CHANNEL`](#plugin_fd_channel) | constant | Fixed descriptor number the host leaves open for the plugin side channel. |
| [`PLUGIN_FD_CHANNEL_ENV`](#plugin_fd_channel_env) | constant | Environment variable the host *would* set to the decimal form of `PLUGIN_FD_CHANNEL`. |

## Re-exports

- [`callback_tunnel::TunnelGuest`](/docs/plugins/sdk/rust/callback_tunnel/index.md#tunnelguest)
- [`callback_tunnel::TunnelHost`](/docs/plugins/sdk/rust/callback_tunnel/index.md#tunnelhost)
- [`callback_tunnel::TunnelStream`](/docs/plugins/sdk/rust/callback_tunnel/index.md#tunnelstream)
- [`net::connect` as `connect_socket`](/docs/plugins/sdk/rust/net/index.md#connect)
- [`net::nested_native_jail_requested`](/docs/plugins/sdk/rust/net/index.md#nested_native_jail_requested)
- [`net::ConnectOptions`](/docs/plugins/sdk/rust/net/index.md#connectoptions)
- [`net::PluginSocket`](/docs/plugins/sdk/rust/net/index.md#pluginsocket)
- [`net::SecureTransport`](/docs/plugins/sdk/rust/net/index.md#securetransport)
- [`net::SocketAddress`](/docs/plugins/sdk/rust/net/index.md#socketaddress)
- [`net::GUEST_IPC_DIR_ENV`](/docs/plugins/sdk/rust/net/index.md#guest_ipc_dir_env)
- [`net::NESTED_NATIVE_JAIL_ENV`](/docs/plugins/sdk/rust/net/index.md#nested_native_jail_env)
- [`net::OWN_USER_AGENT_HOSTS_ENV`](/docs/plugins/sdk/rust/net/index.md#own_user_agent_hosts_env)
- [`net::SESSION_CHALLENGE_ENV`](/docs/plugins/sdk/rust/net/index.md#session_challenge_env)
- [`net::SESSION_CHALLENGE_LEN`](/docs/plugins/sdk/rust/net/index.md#session_challenge_len)
- [`net::SOCKET_PROXY_ABSTRACT_PREFIX`](/docs/plugins/sdk/rust/net/index.md#socket_proxy_abstract_prefix)
- [`net::SOCKET_PROXY_ENV`](/docs/plugins/sdk/rust/net/index.md#socket_proxy_env)
- [`net::SOCKET_PROXY_WRITE_ENV`](/docs/plugins/sdk/rust/net/index.md#socket_proxy_write_env)
- [`net::TEST_EXTRA_CANDIDATE_ENV`](/docs/plugins/sdk/rust/net/index.md#test_extra_candidate_env)
- [`net::TEST_EXTRA_CANDIDATE_WRITE_ENV`](/docs/plugins/sdk/rust/net/index.md#test_extra_candidate_write_env)
- [`net::TEST_EXTRA_ENDPOINT_ENV`](/docs/plugins/sdk/rust/net/index.md#test_extra_endpoint_env)
- [`net::TEST_EXTRA_ENDPOINT_WRITE_ENV`](/docs/plugins/sdk/rust/net/index.md#test_extra_endpoint_write_env)
- [`net::USER_AGENT_ENV`](/docs/plugins/sdk/rust/net/index.md#user_agent_env)
- [`protocol::Abridgement`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#abridgement)
- [`protocol::AccountCredential`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#accountcredential)
- [`protocol::AuthenticateUserParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#authenticateuserparams)
- [`protocol::Brand`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#brand)
- [`protocol::CatalogCapabilities`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#catalogcapabilities)
- [`protocol::CatalogDetail`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#catalogdetail)
- [`protocol::CatalogDetailParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#catalogdetailparams)
- [`protocol::CatalogField`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#catalogfield)
- [`protocol::CatalogHit`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cataloghit)
- [`protocol::CatalogHits`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cataloghits)
- [`protocol::CatalogSort`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#catalogsort)
- [`protocol::ChapterKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#chapterkind)
- [`protocol::ChapterMarker`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#chaptermarker)
- [`protocol::CliArg`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cliarg)
- [`protocol::CliArgKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cliargkind)
- [`protocol::CliArgSpec`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cliargspec)
- [`protocol::CliCommandSpec`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#clicommandspec)
- [`protocol::CliInvokeParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cliinvokeparams)
- [`protocol::CliInvokeResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#cliinvokeresult)
- [`protocol::CliSchema`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#clischema)
- [`protocol::ConfigOption`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#configoption)
- [`protocol::ConfigOptionValue`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#configoptionvalue)
- [`protocol::Credit`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#credit)
- [`protocol::CreditLevel`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#creditlevel)
- [`protocol::CreditRole`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#creditrole)
- [`protocol::EventPollResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#eventpollresult)
- [`protocol::ExpandCandidatesParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#expandcandidatesparams)
- [`protocol::Explicitness`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#explicitness)
- [`protocol::ExpressionKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#expressionkind)
- [`protocol::ExternalUser`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#externaluser)
- [`protocol::FetchOptions`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#fetchoptions)
- [`protocol::FetchTitleParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#fetchtitleparams)
- [`protocol::FetchedFile`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#fetchedfile)
- [`protocol::FetchedFileRole`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#fetchedfilerole)
- [`protocol::Identifier`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#identifier)
- [`protocol::IdentifierScheme`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#identifierscheme)
- [`protocol::ListDealsParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#listdealsparams)
- [`protocol::ListeningProgress`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#listeningprogress)
- [`protocol::LoginCompleteParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#logincompleteparams)
- [`protocol::LoginParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#loginparams)
- [`protocol::LoginResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#loginresult)
- [`protocol::LoginStartResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#loginstartresult)
- [`protocol::MediaKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#mediakind)
- [`protocol::MediaSupport`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#mediasupport)
- [`protocol::OfferedAacProfile`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#offeredaacprofile)
- [`protocol::OfferedCodec`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#offeredcodec)
- [`protocol::OutputLocalContextDto`](/docs/internals/crates/bookclerk_plugin_abi/kind/index.md#outputlocalcontextdto)
- [`protocol::OutputS3ContextDto`](/docs/internals/crates/bookclerk_plugin_abi/kind/index.md#outputs3contextdto)
- [`protocol::PlainFetch`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#plainfetch)
- [`protocol::PortalAuthMode`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#portalauthmode)
- [`protocol::PurchaseHint`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#purchasehint)
- [`protocol::PurchaseHintParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#purchasehintparams)
- [`protocol::PurchaseHintResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#purchasehintresult)
- [`protocol::PurchaseHintsParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#purchasehintsparams)
- [`protocol::PurchaseHintsResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#purchasehintsresult)
- [`protocol::QualityOffer`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#qualityoffer)
- [`protocol::QualityOffersParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#qualityoffersparams)
- [`protocol::QualityOffersResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#qualityoffersresult)
- [`protocol::RevokeAccountParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#revokeaccountparams)
- [`protocol::S3CredentialsDto`](/docs/internals/crates/bookclerk_plugin_abi/kind/index.md#s3credentialsdto)
- [`protocol::ScanBook`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#scanbook)
- [`protocol::ScanLibraryParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#scanlibraryparams)
- [`protocol::ScanPage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#scanpage)
- [`protocol::ScanParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#scanparams)
- [`protocol::SearchCatalogParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#searchcatalogparams)
- [`protocol::SeriesEntry`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#seriesentry)
- [`protocol::SourceAccount`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#sourceaccount)
- [`protocol::SourceAccounts`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#sourceaccounts)
- [`protocol::SyncListeningResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#synclisteningresult)
- [`protocol::TitleQualityOffer`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#titlequalityoffer)
- [`protocol::WorkKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#workkind)
- [`protocol::MAX_RPC_LINE_BYTES`](/docs/plugins/sdk/rust/protocol/index.md#max_rpc_line_bytes)
- [`protocol::PROTOCOL_NAME`](/docs/plugins/sdk/rust/protocol/index.md#protocol_name)
- [`sockets::HostWebSocket`](/docs/plugins/sdk/rust/sockets/index.md#hostwebsocket)
- [`sockets::SocketAutoResponse`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketautoresponse)
- [`sockets::SocketClosed`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketclosed)
- [`sockets::SocketConnectRequest`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketconnectrequest)
- [`sockets::SocketFrame`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketframe)
- [`sockets::SocketHandler`](/docs/internals/crates/bookclerk_plugin_abi/index.md#sockethandler)
- [`sockets::SocketHeader`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketheader)
- [`sockets::SocketInfo`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketinfo)
- [`sockets::SocketMessage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#socketmessage)
- [`sockets::Sockets`](/docs/internals/crates/bookclerk_plugin_abi/index.md#sockets)
- [`bookclerk_plugin_abi::ai`](/docs/internals/crates/bookclerk_plugin_abi/ai/index.md)
- [`bookclerk_plugin_abi::byte_source_from_async_read`](/docs/internals/crates/bookclerk_plugin_abi/index.md#byte_source_from_async_read)
- [`bookclerk_plugin_abi::canonical_execute_request_hash`](/docs/internals/crates/bookclerk_plugin_abi/index.md#canonical_execute_request_hash)
- [`bookclerk_plugin_abi::connect_plugin`](/docs/internals/crates/bookclerk_plugin_abi/index.md#connect_plugin)
- [`bookclerk_plugin_abi::database_adapter_config_from_bindings`](/docs/internals/crates/bookclerk_plugin_abi/db/index.md#database_adapter_config_from_bindings)
- [`bookclerk_plugin_abi::decode_db_value_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#decode_db_value_bytes)
- [`bookclerk_plugin_abi::decode_execute_request_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#decode_execute_request_bytes)
- [`bookclerk_plugin_abi::decode_execute_result_reply_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#decode_execute_result_reply_bytes)
- [`bookclerk_plugin_abi::encoded_db_value_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#encoded_db_value_bytes)
- [`bookclerk_plugin_abi::encoded_execute_reply_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#encoded_execute_reply_bytes)
- [`bookclerk_plugin_abi::encoded_execute_request_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#encoded_execute_request_bytes)
- [`bookclerk_plugin_abi::encoded_execute_result_reply_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#encoded_execute_result_reply_bytes)
- [`bookclerk_plugin_abi::encoded_statement_result_bytes`](/docs/internals/crates/bookclerk_plugin_abi/index.md#encoded_statement_result_bytes)
- [`bookclerk_plugin_abi::hint_result`](/docs/internals/crates/bookclerk_plugin_abi/index.md#hint_result)
- [`bookclerk_plugin_abi::negotiate_rpc_features`](/docs/internals/crates/bookclerk_plugin_abi/index.md#negotiate_rpc_features)
- [`bookclerk_plugin_abi::pull_byte_source_to_writer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pull_byte_source_to_writer)
- [`bookclerk_plugin_abi::purchase_hint_results_one_by_one`](/docs/internals/crates/bookclerk_plugin_abi/index.md#purchase_hint_results_one_by_one)
- [`bookclerk_plugin_abi::require_plugin_migration_registration`](/docs/internals/crates/bookclerk_plugin_abi/index.md#require_plugin_migration_registration)
- [`bookclerk_plugin_abi::serve_plugin`](/docs/internals/crates/bookclerk_plugin_abi/index.md#serve_plugin)
- [`bookclerk_plugin_abi::serve_plugin_stdio`](/docs/internals/crates/bookclerk_plugin_abi/index.md#serve_plugin_stdio)
- [`bookclerk_plugin_abi::sql_payload_bytes`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#sql_payload_bytes)
- [`bookclerk_plugin_abi::sql_payload_exceeds`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#sql_payload_exceeds)
- [`bookclerk_plugin_abi::stream_copy_keys`](/docs/internals/crates/bookclerk_plugin_abi/index.md#stream_copy_keys)
- [`bookclerk_plugin_abi::AdapterBackupOps`](/docs/internals/crates/bookclerk_plugin_abi/backup_ops/index.md#adapterbackupops)
- [`bookclerk_plugin_abi::AdapterDatabaseSession`](/docs/internals/crates/bookclerk_plugin_abi/index.md#adapterdatabasesession)
- [`bookclerk_plugin_abi::AdapterExecuteRequest`](/docs/internals/crates/bookclerk_plugin_abi/index.md#adapterexecuterequest)
- [`bookclerk_plugin_abi::BindingValues`](/docs/internals/crates/bookclerk_plugin_abi/index.md#bindingvalues)
- [`bookclerk_plugin_abi::Bindings`](/docs/internals/crates/bookclerk_plugin_abi/index.md#bindings)
- [`bookclerk_plugin_abi::ByteRange`](/docs/internals/crates/bookclerk_plugin_abi/index.md#byterange)
- [`bookclerk_plugin_abi::Cancellation`](/docs/internals/crates/bookclerk_plugin_abi/index.md#cancellation)
- [`bookclerk_plugin_abi::ChangesPage`](/docs/internals/crates/bookclerk_plugin_abi/index.md#changespage)
- [`bookclerk_plugin_abi::ChangesRequest`](/docs/internals/crates/bookclerk_plugin_abi/index.md#changesrequest)
- [`bookclerk_plugin_abi::ContentSource`](/docs/internals/crates/bookclerk_plugin_abi/index.md#contentsource)
- [`bookclerk_plugin_abi::ContentSourceClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#contentsourceclient)
- [`bookclerk_plugin_abi::CopyResult`](/docs/internals/crates/bookclerk_plugin_abi/index.md#copyresult)
- [`bookclerk_plugin_abi::CoverFetchParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#coverfetchparams)
- [`bookclerk_plugin_abi::CoverFetcher`](/docs/internals/crates/bookclerk_plugin_abi/index.md#coverfetcher)
- [`bookclerk_plugin_abi::CoverFetcherClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#coverfetcherclient)
- [`bookclerk_plugin_abi::CoverImage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#coverimage)
- [`bookclerk_plugin_abi::CoverImages`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#coverimages)
- [`bookclerk_plugin_abi::Database`](/docs/internals/crates/bookclerk_plugin_abi/index.md#database)
- [`bookclerk_plugin_abi::DatabaseAdapterConfig`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#databaseadapterconfig)
- [`bookclerk_plugin_abi::DatabaseClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#databaseclient)
- [`bookclerk_plugin_abi::DbBootstrap`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbbootstrap)
- [`bookclerk_plugin_abi::DbCapabilities`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbcapabilities)
- [`bookclerk_plugin_abi::DbColumn`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbcolumn)
- [`bookclerk_plugin_abi::DbIdentityHighWater`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbidentityhighwater)
- [`bookclerk_plugin_abi::DbPlanStatementKind`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbplanstatementkind)
- [`bookclerk_plugin_abi::DbResultSelection`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbresultselection)
- [`bookclerk_plugin_abi::DbRow`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbrow)
- [`bookclerk_plugin_abi::DbTiming`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#dbtiming)
- [`bookclerk_plugin_abi::DbType`](/docs/internals/crates/bookclerk_plugin_abi/db_value/index.md#dbtype)
- [`bookclerk_plugin_abi::DbValue`](/docs/internals/crates/bookclerk_plugin_abi/db_value/index.md#dbvalue)
- [`bookclerk_plugin_abi::Destination`](/docs/internals/crates/bookclerk_plugin_abi/index.md#destination)
- [`bookclerk_plugin_abi::DestinationClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#destinationclient)
- [`bookclerk_plugin_abi::DestinationServer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#destinationserver)
- [`bookclerk_plugin_abi::DiagnoseResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#diagnoseresult)
- [`bookclerk_plugin_abi::DomainEvent`](/docs/internals/crates/bookclerk_plugin_abi/index.md#domainevent)
- [`bookclerk_plugin_abi::Entrypoints`](/docs/internals/crates/bookclerk_plugin_abi/index.md#entrypoints)
- [`bookclerk_plugin_abi::EventConsumer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#eventconsumer)
- [`bookclerk_plugin_abi::EventConsumerClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#eventconsumerclient)
- [`bookclerk_plugin_abi::EventPublisher`](/docs/internals/crates/bookclerk_plugin_abi/index.md#eventpublisher)
- [`bookclerk_plugin_abi::EventPublisherClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#eventpublisherclient)
- [`bookclerk_plugin_abi::EventReadPage`](/docs/internals/crates/bookclerk_plugin_abi/event_read/index.md#eventreadpage)
- [`bookclerk_plugin_abi::EventReadRequest`](/docs/internals/crates/bookclerk_plugin_abi/event_read/index.md#eventreadrequest)
- [`bookclerk_plugin_abi::EventResult`](/docs/internals/crates/bookclerk_plugin_abi/index.md#eventresult)
- [`bookclerk_plugin_abi::ExecuteReply`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#executereply)
- [`bookclerk_plugin_abi::ExecuteRequest`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#executerequest)
- [`bookclerk_plugin_abi::ExecuteStream`](/docs/internals/crates/bookclerk_plugin_abi/db_stream/index.md#executestream)
- [`bookclerk_plugin_abi::ExecuteStreamLimits`](/docs/internals/crates/bookclerk_plugin_abi/db_stream/index.md#executestreamlimits)
- [`bookclerk_plugin_abi::ExtensibleConfig`](/docs/internals/crates/bookclerk_plugin_abi/index.md#extensibleconfig)
- [`bookclerk_plugin_abi::GuestDatabase`](/docs/internals/crates/bookclerk_plugin_abi/index.md#guestdatabase)
- [`bookclerk_plugin_abi::HealthOk`](/docs/internals/crates/bookclerk_plugin_abi/index.md#healthok)
- [`bookclerk_plugin_abi::HostBindings`](/docs/internals/crates/bookclerk_plugin_abi/index.md#hostbindings)
- [`bookclerk_plugin_abi::Invocation`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#invocation)
- [`bookclerk_plugin_abi::IsolationReq`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#isolationreq)
- [`bookclerk_plugin_abi::JobCheckpoint`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobcheckpoint)
- [`bookclerk_plugin_abi::JobController`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobcontroller)
- [`bookclerk_plugin_abi::JobInvocation`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobinvocation)
- [`bookclerk_plugin_abi::JobInvocationLease`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobinvocationlease)
- [`bookclerk_plugin_abi::JobOutcome`](/docs/internals/crates/bookclerk_plugin_abi/index.md#joboutcome)
- [`bookclerk_plugin_abi::JobRunner`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobrunner)
- [`bookclerk_plugin_abi::JobRunnerClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#jobrunnerclient)
- [`bookclerk_plugin_abi::KeyOutcome`](/docs/internals/crates/bookclerk_plugin_abi/index.md#keyoutcome)
- [`bookclerk_plugin_abi::KeyPair`](/docs/internals/crates/bookclerk_plugin_abi/index.md#keypair)
- [`bookclerk_plugin_abi::KvDeleteOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvdeleteok)
- [`bookclerk_plugin_abi::KvGetOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvgetok)
- [`bookclerk_plugin_abi::KvListKey`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvlistkey)
- [`bookclerk_plugin_abi::KvListOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvlistok)
- [`bookclerk_plugin_abi::KvListOptions`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvlistoptions)
- [`bookclerk_plugin_abi::KvNamespace`](/docs/internals/crates/bookclerk_plugin_abi/index.md#kvnamespace)
- [`bookclerk_plugin_abi::KvNamespaceClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#kvnamespaceclient)
- [`bookclerk_plugin_abi::KvPutOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvputok)
- [`bookclerk_plugin_abi::KvPutOptions`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#kvputoptions)
- [`bookclerk_plugin_abi::LimitExceeded`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#limitexceeded)
- [`bookclerk_plugin_abi::ListOptions`](/docs/internals/crates/bookclerk_plugin_abi/index.md#listoptions)
- [`bookclerk_plugin_abi::ListPage`](/docs/internals/crates/bookclerk_plugin_abi/index.md#listpage)
- [`bookclerk_plugin_abi::MetadataChapter`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatachapter)
- [`bookclerk_plugin_abi::MetadataChapters`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatachapters)
- [`bookclerk_plugin_abi::MetadataChaptersParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatachaptersparams)
- [`bookclerk_plugin_abi::MetadataField`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafield)
- [`bookclerk_plugin_abi::MetadataFileParseParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafileparseparams)
- [`bookclerk_plugin_abi::MetadataFileParsed`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafileparsed)
- [`bookclerk_plugin_abi::MetadataFileRecord`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafilerecord)
- [`bookclerk_plugin_abi::MetadataFileRenderParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafilerenderparams)
- [`bookclerk_plugin_abi::MetadataFileRendered`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatafilerendered)
- [`bookclerk_plugin_abi::MetadataFiles`](/docs/internals/crates/bookclerk_plugin_abi/index.md#metadatafiles)
- [`bookclerk_plugin_abi::MetadataFilesClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#metadatafilesclient)
- [`bookclerk_plugin_abi::MetadataLookupParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatalookupparams)
- [`bookclerk_plugin_abi::MetadataProvider`](/docs/internals/crates/bookclerk_plugin_abi/index.md#metadataprovider)
- [`bookclerk_plugin_abi::MetadataProviderClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#metadataproviderclient)
- [`bookclerk_plugin_abi::MetadataRecord`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatarecord)
- [`bookclerk_plugin_abi::MetadataSearchParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#metadatasearchparams)
- [`bookclerk_plugin_abi::MoveManyPage`](/docs/internals/crates/bookclerk_plugin_abi/index.md#movemanypage)
- [`bookclerk_plugin_abi::MoveManyRequest`](/docs/internals/crates/bookclerk_plugin_abi/index.md#movemanyrequest)
- [`bookclerk_plugin_abi::MoveManyTarget`](/docs/internals/crates/bookclerk_plugin_abi/index.md#movemanytarget)
- [`bookclerk_plugin_abi::MoveOptions`](/docs/internals/crates/bookclerk_plugin_abi/index.md#moveoptions)
- [`bookclerk_plugin_abi::MoveResult`](/docs/internals/crates/bookclerk_plugin_abi/index.md#moveresult)
- [`bookclerk_plugin_abi::NamedKvBinding`](/docs/internals/crates/bookclerk_plugin_abi/index.md#namedkvbinding)
- [`bookclerk_plugin_abi::NamedQueueBinding`](/docs/internals/crates/bookclerk_plugin_abi/index.md#namedqueuebinding)
- [`bookclerk_plugin_abi::NeverCancel`](/docs/internals/crates/bookclerk_plugin_abi/index.md#nevercancel)
- [`bookclerk_plugin_abi::NotificationAlertAction`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notificationalertaction)
- [`bookclerk_plugin_abi::NotificationAudience`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notificationaudience)
- [`bookclerk_plugin_abi::NotificationField`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notificationfield)
- [`bookclerk_plugin_abi::NotificationMessage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notificationmessage)
- [`bookclerk_plugin_abi::NotificationRaiser`](/docs/internals/crates/bookclerk_plugin_abi/index.md#notificationraiser)
- [`bookclerk_plugin_abi::NotificationRaiserClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#notificationraiserclient)
- [`bookclerk_plugin_abi::NotificationSeverity`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notificationseverity)
- [`bookclerk_plugin_abi::Notifier`](/docs/internals/crates/bookclerk_plugin_abi/index.md#notifier)
- [`bookclerk_plugin_abi::NotifierClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#notifierclient)
- [`bookclerk_plugin_abi::NotifyDestination`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifydestination)
- [`bookclerk_plugin_abi::NotifyDestinationKind`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifydestinationkind)
- [`bookclerk_plugin_abi::NotifyRaiseParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifyraiseparams)
- [`bookclerk_plugin_abi::NotifyRaised`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifyraised)
- [`bookclerk_plugin_abi::NotifySendParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifysendparams)
- [`bookclerk_plugin_abi::NotifySent`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifysent)
- [`bookclerk_plugin_abi::NotifyValidateParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifyvalidateparams)
- [`bookclerk_plugin_abi::NotifyValidated`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#notifyvalidated)
- [`bookclerk_plugin_abi::ObjectChange`](/docs/internals/crates/bookclerk_plugin_abi/index.md#objectchange)
- [`bookclerk_plugin_abi::ObjectChangeKind`](/docs/internals/crates/bookclerk_plugin_abi/index.md#objectchangekind)
- [`bookclerk_plugin_abi::ObjectInfo`](/docs/internals/crates/bookclerk_plugin_abi/index.md#objectinfo)
- [`bookclerk_plugin_abi::ObjectMetadata`](/docs/internals/crates/bookclerk_plugin_abi/index.md#objectmetadata)
- [`bookclerk_plugin_abi::Oidc`](/docs/internals/crates/bookclerk_plugin_abi/index.md#oidc)
- [`bookclerk_plugin_abi::OidcClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#oidcclient)
- [`bookclerk_plugin_abi::OidcClientTemplate`](/docs/internals/crates/bookclerk_plugin_abi/index.md#oidcclienttemplate)
- [`bookclerk_plugin_abi::OpenedEntrypoints`](/docs/internals/crates/bookclerk_plugin_abi/index.md#openedentrypoints)
- [`bookclerk_plugin_abi::PluginCli`](/docs/internals/crates/bookclerk_plugin_abi/index.md#plugincli)
- [`bookclerk_plugin_abi::PluginCliClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#plugincliclient)
- [`bookclerk_plugin_abi::PluginClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginclient)
- [`bookclerk_plugin_abi::PluginDescribe`](/docs/internals/crates/bookclerk_plugin_abi/index.md#plugindescribe)
- [`bookclerk_plugin_abi::PluginError`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#pluginerror)
- [`bookclerk_plugin_abi::PluginErrorCode`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#pluginerrorcode)
- [`bookclerk_plugin_abi::PluginEvent`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#pluginevent)
- [`bookclerk_plugin_abi::PluginMigration`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginmigration)
- [`bookclerk_plugin_abi::PluginMigrationOp`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginmigrationop)
- [`bookclerk_plugin_abi::PluginServer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginserver)
- [`bookclerk_plugin_abi::PluginWorker`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginworker)
- [`bookclerk_plugin_abi::ProgressSink`](/docs/internals/crates/bookclerk_plugin_abi/index.md#progresssink)
- [`bookclerk_plugin_abi::PublishOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#publishok)
- [`bookclerk_plugin_abi::PutResult`](/docs/internals/crates/bookclerk_plugin_abi/index.md#putresult)
- [`bookclerk_plugin_abi::QueryPage`](/docs/internals/crates/bookclerk_plugin_abi/index.md#querypage)
- [`bookclerk_plugin_abi::QueueBatch`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queuebatch)
- [`bookclerk_plugin_abi::QueueConsumer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#queueconsumer)
- [`bookclerk_plugin_abi::QueueConsumerClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#queueconsumerclient)
- [`bookclerk_plugin_abi::QueueMessage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queuemessage)
- [`bookclerk_plugin_abi::QueueProducer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#queueproducer)
- [`bookclerk_plugin_abi::QueueResult`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queueresult)
- [`bookclerk_plugin_abi::QueueRetry`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queueretry)
- [`bookclerk_plugin_abi::QueueSendMessage`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queuesendmessage)
- [`bookclerk_plugin_abi::QueueSendOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#queuesendok)
- [`bookclerk_plugin_abi::ReadResult`](/docs/internals/crates/bookclerk_plugin_abi/index.md#readresult)
- [`bookclerk_plugin_abi::RemoteLibrary`](/docs/internals/crates/bookclerk_plugin_abi/index.md#remotelibrary)
- [`bookclerk_plugin_abi::RemoteLibraryClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#remotelibraryclient)
- [`bookclerk_plugin_abi::ScalarLimits`](/docs/internals/crates/bookclerk_plugin_abi/index.md#scalarlimits)
- [`bookclerk_plugin_abi::Source`](/docs/internals/crates/bookclerk_plugin_abi/index.md#source)
- [`bookclerk_plugin_abi::SourceClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#sourceclient)
- [`bookclerk_plugin_abi::SourceServer`](/docs/internals/crates/bookclerk_plugin_abi/index.md#sourceserver)
- [`bookclerk_plugin_abi::StatementResult`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#statementresult)
- [`bookclerk_plugin_abi::StreamCopyHandler`](/docs/internals/crates/bookclerk_plugin_abi/index.md#streamcopyhandler)
- [`bookclerk_plugin_abi::StreamCopySpec`](/docs/internals/crates/bookclerk_plugin_abi/index.md#streamcopyspec)
- [`bookclerk_plugin_abi::TypedDbStatement`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#typeddbstatement)
- [`bookclerk_plugin_abi::WriteOptions`](/docs/internals/crates/bookclerk_plugin_abi/index.md#writeoptions)
- [`bookclerk_plugin_abi::FEATURE_SCALAR_LIMITS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_scalar_limits)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_CHANGES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_changes)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_CONDITIONAL_WRITE`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_conditional_write)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_COPY`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_copy)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_DELETE_MANY`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_delete_many)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_HEAD_MANY`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_head_many)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_MOVE`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_move)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_MOVE_MANY`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_move_many)
- [`bookclerk_plugin_abi::FEATURE_STORAGE_TRANSLATE_KEYS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_storage_translate_keys)
- [`bookclerk_plugin_abi::FEATURE_STREAMS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#feature_streams)
- [`bookclerk_plugin_abi::MAX_BATCH_KEYS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_batch_keys)
- [`bookclerk_plugin_abi::MAX_CHANGES_CURSOR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_changes_cursor_bytes)
- [`bookclerk_plugin_abi::MAX_CHANGES_PAGE`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_changes_page)
- [`bookclerk_plugin_abi::MAX_EVENT_CURSOR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_event_cursor_bytes)
- [`bookclerk_plugin_abi::MAX_KV_KEY_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_kv_key_bytes)
- [`bookclerk_plugin_abi::MAX_KV_METADATA_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_kv_metadata_bytes)
- [`bookclerk_plugin_abi::MAX_KV_VALUE_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_kv_value_bytes)
- [`bookclerk_plugin_abi::MAX_LIST_PAGE`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_list_page)
- [`bookclerk_plugin_abi::MAX_METADATA_FILE_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_metadata_file_bytes)
- [`bookclerk_plugin_abi::MAX_METADATA_FILE_CHAPTERS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_metadata_file_chapters)
- [`bookclerk_plugin_abi::MAX_METADATA_FILE_DESCRIPTION_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_metadata_file_description_bytes)
- [`bookclerk_plugin_abi::MAX_METADATA_FILE_LIST_ENTRIES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_metadata_file_list_entries)
- [`bookclerk_plugin_abi::MAX_METADATA_FILE_TEXT_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_metadata_file_text_bytes)
- [`bookclerk_plugin_abi::MAX_NOTIFICATION_FIELDS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notification_fields)
- [`bookclerk_plugin_abi::MAX_NOTIFICATION_FIELD_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notification_field_bytes)
- [`bookclerk_plugin_abi::MAX_NOTIFICATION_HTML_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notification_html_bytes)
- [`bookclerk_plugin_abi::MAX_NOTIFICATION_TEXT_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notification_text_bytes)
- [`bookclerk_plugin_abi::MAX_NOTIFICATION_TITLE_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notification_title_bytes)
- [`bookclerk_plugin_abi::MAX_NOTIFIER_ADDRESS_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_notifier_address_bytes)
- [`bookclerk_plugin_abi::MAX_PLUGIN_MIGRATION_OPS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_plugin_migration_ops)
- [`bookclerk_plugin_abi::MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_plugin_migration_registration_bytes)
- [`bookclerk_plugin_abi::MAX_PLUGIN_MIGRATION_TOTAL_OPS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_plugin_migration_total_ops)
- [`bookclerk_plugin_abi::MAX_REFRESHED_CREDENTIAL_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_refreshed_credential_bytes)
- [`bookclerk_plugin_abi::MAX_SCALAR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scalar_bytes)
- [`bookclerk_plugin_abi::MAX_SCAN_CURSOR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scan_cursor_bytes)
- [`bookclerk_plugin_abi::MAX_SCAN_PAGE_BOOKS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scan_page_books)
- [`bookclerk_plugin_abi::MAX_STREAM_WINDOW_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_stream_window_bytes)
- [`bookclerk_plugin_abi::PRODUCT_API_VERSION`](/docs/internals/crates/bookclerk_plugin_abi/index.md#product_api_version)
- [`bookclerk_plugin_abi::SQL_CONTRACT_VERSION`](/docs/internals/crates/bookclerk_plugin_abi/db_execute/index.md#sql_contract_version)
- [`bookclerk_plugin_abi::STORAGE_OPERATION_FEATURES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#storage_operation_features)
- [`bookclerk_plugin_abi::AiEmbedText`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aiembedtext)
- [`bookclerk_plugin_abi::AiInput`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aiinput)
- [`bookclerk_plugin_abi::AiModel`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aimodel)
- [`bookclerk_plugin_abi::AiModelList`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aimodellist)
- [`bookclerk_plugin_abi::AiModels`](/docs/internals/crates/bookclerk_plugin_abi/index.md#aimodels)
- [`bookclerk_plugin_abi::AiModelsClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#aimodelsclient)
- [`bookclerk_plugin_abi::AiOutput`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aioutput)
- [`bookclerk_plugin_abi::AiRunOk`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#airunok)
- [`bookclerk_plugin_abi::AiRunParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#airunparams)
- [`bookclerk_plugin_abi::AiRunner`](/docs/internals/crates/bookclerk_plugin_abi/index.md#airunner)
- [`bookclerk_plugin_abi::AiRunnerClient`](/docs/internals/crates/bookclerk_plugin_abi/index.md#airunnerclient)
- [`bookclerk_plugin_abi::AiTask`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aitask)
- [`bookclerk_plugin_abi::AiTextEmbeddingsInput`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aitextembeddingsinput)
- [`bookclerk_plugin_abi::AiTextEmbeddingsOutput`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aitextembeddingsoutput)
- [`bookclerk_plugin_abi::AiTextRole`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#aitextrole)
- [`bookclerk_plugin_abi::MAX_AI_EMBED_DIMENSIONS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_embed_dimensions)
- [`bookclerk_plugin_abi::MAX_AI_EMBED_TEXTS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_embed_texts)
- [`bookclerk_plugin_abi::MAX_AI_EMBED_TEXT_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_embed_text_bytes)
- [`bookclerk_plugin_abi::MAX_AI_LANGUAGES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_languages)
- [`bookclerk_plugin_abi::MAX_AI_MODELS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_models)
- [`bookclerk_plugin_abi::MAX_AI_MODEL_NAME_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_ai_model_name_bytes)

## Modules

- [`callback_tunnel`](/docs/plugins/sdk/rust/callback_tunnel/index.md): Multiplexed byte tunnel for host-owned OAuth callback listeners.
- [`database_adapter`](/docs/plugins/sdk/rust/database_adapter/index.md): Database adapter helpers for third-party database plugin authors.
- [`download`](/docs/plugins/sdk/rust/download/index.md): Resumable downloads to a file for native guests.
- [`http`](/docs/plugins/sdk/rust/http/index.md): Native guest HTTP through the workerd socket proxy.
- [`mux`](/docs/plugins/sdk/rust/mux/index.md): Bidirectional multiplexed byte streams with per-stream credit windows.
- [`net`](/docs/plugins/sdk/rust/net/index.md): Mediated TCP sockets for native guests (Workers `connect()` equivalent).
- [`protocol`](/docs/plugins/sdk/rust/protocol/index.md): Shared role method names and typed method payloads.
- [`resume`](/docs/plugins/sdk/rust/resume/index.md): Sans-IO decisions for resuming an interrupted HTTP download.
- [`sockets`](/docs/plugins/sdk/rust/sockets/index.md): Host-brokered WebSockets (`[sockets]`) for native guests.
- [`workerd`](/docs/plugins/sdk/rust/workerd/index.md): Workerd guest bridge — same `crate::PluginWorker` contract as native.
- [`methods`](/docs/plugins/sdk/rust/methods/index.md): Role capability method name constants (camelCase wire strings).

## Structs

### ChunkCaps

```rust
pub struct ChunkCaps {
    pub max_statements: u32,
    pub max_request_bytes: u32,
}
```

Caps [`DatabaseBinding::chunk`](#databasebindingchunk) splits a batch by when the session's
limits are not to be used.

**Fields**

- `max_statements`: Statements per request (`0` = no cap).
- `max_request_bytes`: Encoded request bytes per request (`0` = no cap).

Implements: `Clone`, `Copy`, `Debug`, `Default`, `Eq`, `PartialEq`

### D1ExecResult

```rust
pub struct D1ExecResult {
    pub count: u32,
    pub duration: f64,
}
```

Cloudflare [`D1ExecResult`](https://developers.cloudflare.com/d1/worker-api/return-object/).

**Fields**

- `count`: Number of statements executed (one per non-empty `exec` line).
- `duration`: Total duration in milliseconds.

Implements: `Clone`, `Debug`, `PartialEq`

### D1Meta

```rust
pub struct D1Meta {
    pub duration: f64,
    pub changes: u64,
    pub last_row_id: i64,
    pub changed_db: bool,
    pub rows_read: u32,
    pub rows_written: u64,
}
```

Cloudflare [`D1Result::meta`](https://developers.cloudflare.com/d1/worker-api/return-object/) shape.

**Fields**

- `duration`: Engine-reported SQL duration in milliseconds.
- `changes`: Rows changed by the statement (`rowsAffected`).
- `last_row_id`: Last inserted row id when the adapter exposes it (else `0`).
- `changed_db`: `true` when `changes > 0`.
- `rows_read`: Rows returned to the guest for this statement.
- `rows_written`: Rows written (`changes` for DML).

Implements: `Clone`, `Debug`, `PartialEq`

### D1Result

```rust
pub struct D1Result {
    pub success: bool,
    pub results: Option<Vec<HashMap<String, DbValue>>>,
    pub meta: D1Meta,
}
```

Cloudflare [`D1Result`](https://developers.cloudflare.com/d1/worker-api/return-object/) projection.

**Fields**

- `success`: Always `true` on success; errors are returned as `Result::Err`.
- `results`: Row maps for selects; `None` when not applicable (DML).
- `meta`: Cloudflare-shaped timing and change metadata.

Implements: `Clone`, `Debug`, `PartialEq`

### DatabaseBinding

```rust
pub struct DatabaseBinding {
    /* private fields */
}
```

Host-mediated typed SQL surface for plugin guests.

Row-returning reads go through `GuestDatabase.executeStreamed` whenever
the session advertises a streamed budget (`limits()`, fetched once per
binding), so a result past the inline caps still arrives whole; sessions
that do not stream, or answer `unsupported`, are read inline.

#### DatabaseBinding::from_session

```rust
pub fn from_session(session: Arc<dyn GuestDatabase>) -> Self
```

Wraps a host-granted [`GuestDatabase`](/docs/internals/crates/bookclerk_plugin_abi/index.md#guestdatabase).

#### DatabaseBinding::from_session_with

```rust
pub fn from_session_with(
    session: Arc<dyn GuestDatabase>,
    options: DatabaseBindingOptions,
) -> Self
```

Wraps a host-granted session with request-budget knobs.

#### DatabaseBinding::take_named_from_bindings

```rust
pub fn take_named_from_bindings(bindings: &mut Bindings, name: &str) -> Option<Self>
```

Takes the named plugin database binding `name` from the `open`
[`Bindings`](/docs/internals/crates/bookclerk_plugin_abi/index.md#bindings).

Named bindings come from `plugin.toml` `[[databases]]` after operator
approval: each is an isolated plugin-owned database (full DML plus
idempotent `CREATE`/`DROP` `TABLE`/`INDEX` with `IF [NOT] EXISTS`),
physically separate from the Bookclerk library and from every other
plugin. Production invocations never inject the host library.

#### DatabaseBinding::limits

```rust
pub async fn limits(&self) -> Result<DbCapabilities>
```

The negotiated limits of the granted session (`DbCapabilities`).

Use it to size a batch or a read before sending: `max_request_bytes`,
`max_statements`, `max_result_bytes`, `max_result_rows` and the rest.

##### Errors

Returns `unsupported` when the host session predates
`GuestDatabase.limits`.

#### DatabaseBinding::chunk

```rust
pub async fn chunk(
    &self,
    statements: Vec<PreparedStatement>,
    caps: Option<ChunkCaps>,
) -> Result<Vec<Vec<PreparedStatement>>>
```

Splits `statements` into batches that each fit one request.

`for batch in db.chunk(stmts, None).await? { db.batch(batch, None).await?; }`.
Each batch is atomic; the loop is not. The caps come from the
session's limits (`max_statements`, and the tighter of the session's
and the binding's `max_request_bytes`) unless `caps` is given; zero
caps given explicitly mean one batch. A single statement larger than
the request cap is yielded alone, so [`Self::batch`](#databasebindingbatch) reports the
typed error. Batches are sized with the UUID-shaped retry id the
binding mints; a caller-chosen retry id that is longer leaves that
much less room.

##### Errors

Returns `unsupported` when neither the session's limits nor `caps`
are available, and `PluginError::invalid_params` when a statement
is missing terminal intent.

#### DatabaseBinding::write_chunks

```rust
pub async fn write_chunks(
    &self,
    statements: Vec<PreparedStatement>,
    from: usize,
    key: &str,
    caps: Option<ChunkCaps>,
    stop: impl FnMut(usize) -> bool,
) -> Result<WriteProgress, WriteChunksError>
```

Writes `statements` in batches that fit one request, resumably.

The batches are the ones [`Self::chunk`](#databasebindingchunk) would yield for
`statements[from..]`, each committed with [`Self::batch`](#databasebindingbatch) under an
operation id derived from `key` and the batch's offset (see
[`write_chunks_operation_id`](#write_chunks_operation_id)). Store the returned `next` (for
example in a job checkpoint) and call again with the same list, the
same `key` and `from = next` to carry on: a batch whose reply was
lost is resent under the same id and the host replays its receipt.
Receipts are kept for 24 hours; a batch resent later runs again, so
a write that may pause that long uses statements safe to repeat.

`stop` is asked before each batch with the number of statements
committed so far; returning `true` pauses the run there (a time
budget, a cancellation flag). The list and the caps must not change
between calls with one `key`, or a resent batch no longer matches its
receipt and the host answers `conflict`.

##### Arguments

* `statements` - The whole list, the same on every call.
* `from` - Statements already committed; `0` on the first call.
* `key` - Names this write, stable across resumes (a job id plus a
  step name); at most [`MAX_WRITE_KEY_BYTES`](#max_write_key_bytes) bytes.
* `caps` - As for [`Self::chunk`](#databasebindingchunk); `None` uses the session's limits.
* `stop` - Asked before each batch whether to pause.

##### Errors

Returns a [`WriteChunksError`](#writechunkserror) whose `next` is the statements
committed so far: `invalid_params` when `key` is empty or too long or
`from` is past the list, the error [`Self::chunk`](#databasebindingchunk) returns, or the
error of the batch that failed.

#### DatabaseBinding::prepare

```rust
pub fn prepare(&self, sql: impl Into<String>) -> PreparedStatement
```

Prepare one canonical-SQL statement (`?` placeholders).

#### DatabaseBinding::batch

```rust
pub async fn batch(
    &self,
    statements: Vec<PreparedStatement>,
    retry: Option<RetryToken>,
) -> Result<Vec<D1Result>>
```

Run prepared statements as one typed atomic batch.

##### Errors

Returns when a statement is missing terminal intent, the encoded
request exceeds `maxRequestBytes`, or `execute` fails.

#### DatabaseBinding::exec

```rust
pub async fn exec(
    &self,
    query: impl Into<String>,
    retry: Option<RetryToken>,
) -> Result<D1ExecResult>
```

Execute raw SQL without bind parameters (Cloudflare `D1Database::exec`).

Bookclerk accepts one or more newline-separated statements like D1.
Each non-empty line is executed as one prepared statement in a single
typed atomic batch.

##### Errors

Returns when the query is empty or `batch` fails.

#### DatabaseBinding::execute

```rust
pub async fn execute(
    &self,
    batch: Vec<TypedDbStatement>,
    retry: Option<RetryToken>,
) -> Result<ExecuteReply>
```

Internal typed-batch transport. Prefer [`Self::prepare`](#databasebindingprepare).

##### Errors

Returns when the batch is empty, the encoded request exceeds the
negotiated cap, or `execute` fails.

Implements: `Clone`

### DatabaseBindingOptions

```rust
pub struct DatabaseBindingOptions {
    pub max_request_bytes: u32,
    pub max_result_rows: u32,
    pub retry: Option<RetryToken>,
    pub deadline_unix_ms: u64,
}
```

Options for [`DatabaseBinding`](#databasebinding).

**Fields**

- `max_request_bytes`: Negotiated `maxRequestBytes` (`0` = unlimited).
- `max_result_rows`: Default `maxRows` for [`PreparedStatement::all`](#preparedstatementall) (`0` = host adapter cap).
- `retry`: Default retry token.
- `deadline_unix_ms`: Guest-visible deadline (unix ms).

Implements: `Clone`, `Debug`, `Default`

### PreparedStatement

```rust
pub struct PreparedStatement {
    /* private fields */
}
```

Cloudflare-style prepared statement.

#### PreparedStatement::bind

```rust
pub fn bind(self, values: Vec<DbValue>) -> Self
```

Replace bound parameters.

#### PreparedStatement::as_run

```rust
pub fn as_run(self) -> Self
```

Mark DML intent for [`DatabaseBinding::batch`](#databasebindingbatch).

#### PreparedStatement::as_first

```rust
pub fn as_first(self) -> Self
```

Mark `maxRows = 1` row intent for [`DatabaseBinding::batch`](#databasebindingbatch).

Preserves the caller SQL; the host enforces the one-row bound at execution.

#### PreparedStatement::as_all

```rust
pub fn as_all(self) -> Self
```

Mark row-returning intent for [`DatabaseBinding::batch`](#databasebindingbatch).

#### PreparedStatement::run

```rust
pub async fn run(self, retry: Option<RetryToken>) -> Result<D1Result>
```

Execute as Cloudflare `run()` (functionally equivalent to [`Self::all`](#preparedstatementall)).

##### Errors

Returns when `execute` fails.

#### PreparedStatement::first

```rust
pub async fn first(
    self,
    retry: Option<RetryToken>,
) -> Result<Option<Vec<(String, DbValue)>>>
```

First row as a name→value map, or `None` (Cloudflare `first()` without `colName`).

##### Errors

Returns when `execute` fails.

#### PreparedStatement::first_column

```rust
pub async fn first_column(
    self,
    col_name: &str,
    retry: Option<RetryToken>,
) -> Result<Option<DbValue>>
```

One column from the first row, or `None` when no row exists.

##### Errors

Returns when `execute` fails or the named column is absent from the row
(Cloudflare `first(colName)` throws `D1_ERROR` in that case).

#### PreparedStatement::raw

```rust
pub async fn raw(self, retry: Option<RetryToken>) -> Result<Vec<Vec<DbValue>>>
```

Positional cell values per row (Cloudflare `raw()`).

##### Errors

Returns when `execute` fails.

#### PreparedStatement::all

```rust
pub async fn all(self, retry: Option<RetryToken>) -> Result<D1Result>
```

Execute as a row-returning query. Returns a Cloudflare-shaped [`D1Result`](#d1result).

##### Errors

Returns when `execute` fails.

#### PreparedStatement::iterate

```rust
pub fn iterate(self, retry: Option<RetryToken>) -> RowStream
```

Rows one at a time from the same single-snapshot streamed read as
[`Self::all`](#preparedstatementall), without holding the whole result.

```rust
let mut rows = db.prepare("SELECT id, path FROM edition_files").iterate(None);
while let Some(row) = rows.next().await {
    let row = row?;
    // ...
}
```

Nothing is sent until the first [`RowStream::next`](#rowstreamnext). On a session
that streams, rows are decoded as their frames arrive and each is
handed out once, so memory stays near one frame however large
the result is. The read still fails closed (`limit_exceeded`) past
the session's streamed budget, after the rows that fit were handed
out. On a session that does not stream, or answers `unsupported`
before any row arrived, the rows come from one inline read like
[`Self::all`](#preparedstatementall). Dropping the stream stops reading it.

Implements: `Clone`

### RetryToken

```rust
pub struct RetryToken {
    pub operation_id: String,
    pub request_hash: String,
}
```

Explicit retry identity: reuse both `operationId` and `requestHash`.

**Fields**

- `operation_id`: Caller-chosen idempotency key.
- `request_hash`: Canonical Cap'n request hash stamped by the host.

Implements: `Clone`, `Debug`, `Eq`, `PartialEq`

### RowStream

```rust
pub struct RowStream {
    /* private fields */
}
```

Rows of one read, handed out one at a time
([`PreparedStatement::iterate`](#preparedstatementiterate)).

Each row is a column name → value map, the shape [`D1Result::results`](#d1result)
holds. The stream ends (`None`) after the last row, or after the first
error it yields.

#### RowStream::next

```rust
pub async fn next(&mut self) -> Option<Result<HashMap<String, DbValue>>>
```

The next row, `None` once the read is over.

##### Errors

Yields (once, then `None`) the error the read fails with: a typed
`limit_exceeded` past the session's budget, the adapter's error, an
`unavailable` when the stream breaks off, or `invalid_params` when
the reply does not answer the request or carries more rows than the
statement's `max_rows`.

Implements: `Debug`

### WriteChunksError

```rust
pub struct WriteChunksError {
    pub next: usize,
    pub error: PluginError,
}
```

A [`DatabaseBinding::write_chunks`](#databasebindingwrite_chunks) run that failed part way.

**Fields**

- `next`: Statements committed before the failure; resume with `from = next`.
  The failed batch may have committed with its reply lost: resuming
  resends it under the same operation id, so the host replays its
  receipt instead of writing it twice.
- `error`: Why the batch at `next` failed.

Implements: `Debug`, `Display`, `Error`

### WriteProgress

```rust
pub struct WriteProgress {
    pub next: usize,
    pub done: bool,
}
```

Where a [`DatabaseBinding::write_chunks`](#databasebindingwrite_chunks) run stands.

**Fields**

- `next`: Statements committed from the start of the list; pass it back as
  `from` to resume. Always a batch boundary.
- `done`: True when every statement is committed; false when `stop` paused the
  run between batches.

Implements: `Clone`, `Copy`, `Debug`, `Eq`, `PartialEq`

### FetchWorkDir

```rust
pub struct FetchWorkDir {
    /* private fields */
}
```

An open fetch work directory received from the host for one `fetchTitle` call.

Holds the descriptor open for its lifetime so `/proc/self/fd/N` (or
`/dev/fd/N`) stays valid for the duration of the call. When the side channel
is not armed, falls back to the `cache_dir` field on
[`FetchTitleParams`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#fetchtitleparams) from the RPC params (absolute path string the host
already prepared inside the guest jail).

#### FetchWorkDir::open

```rust
pub fn open(params: &FetchTitleParams) -> Result<Self>
```

Resolves the directory a `fetchTitle` call should write downloaded audio into.

Uses the `cache_dir` field on `params` (hosts pass a jail-granted
directory under the guest `TMPDIR`). When [`PLUGIN_FD_CHANNEL_ENV`](#plugin_fd_channel_env) is
set, receives one SCM_RIGHTS directory FD instead — hosts do not set
this env; do not arm it without a matching host send.

##### Arguments

* `params` - Host `fetchTitle` params; `cache_dir` is the work directory
  unless the unused FD side channel is armed.

##### Returns

A [`FetchWorkDir`](#fetchworkdir) whose [`Self::path`](#fetchworkdirpath) is valid for the rest of the RPC.

##### Errors

Returns [`SdkError`](#sdkerror) when the side channel env is set but
[`recv_passed_fd`](#recv_passed_fd) fails, or when FD → path mapping fails on this OS.

#### FetchWorkDir::path

```rust
pub fn path(&self) -> &Path
```

Absolute filesystem path of the fetch work directory.

On Unix with a passed FD this is typically `/proc/self/fd/N` (Linux) or
`/dev/fd/N` (macOS/BSD). Keep `self` alive while writing under this path.

Implements: `Deref`

### UploadFile

```rust
pub struct UploadFile {
    /* private fields */
}
```

An open upload file received from the host for one `putFile` call.

Same FD-lifetime rules as [`FetchWorkDir`]: keep the value alive while
reading the path so the `/proc/self/fd/N` symlink remains valid.

#### UploadFile::open

```rust
pub fn open(local_path: Option<&str>) -> Result<Self>
```

Resolves the local file path for a `putFile` upload.

Uses `local_path` from the RPC params. When [`PLUGIN_FD_CHANNEL_ENV`](#plugin_fd_channel_env) is
set, receives one SCM_RIGHTS file FD instead — hosts do not set this
env (destinations stream bytes). Do not arm it without a matching send.

##### Arguments

* `local_path` - Optional absolute path from host params; ignored when
  the FD channel is active. Must be `Some` and non-empty when the
  channel is inactive.

##### Returns

An [`UploadFile`](#uploadfile) whose [`Self::path`](#uploadfilepath) points at the bytes to upload.

##### Errors

Returns [`SdkError`](#sdkerror) when neither an FD nor a usable `local_path` is
available, or when receiving/mapping the FD fails.

#### UploadFile::path

```rust
pub fn path(&self) -> &Path
```

Absolute filesystem path of the file the host wants uploaded.

Keep `self` alive for the duration of the read so a passed FD path stays
valid.

Implements: `Deref`

### StorePage

```rust
pub struct StorePage {
    pub books: Vec<ScanBook>,
    pub removed: Vec<String>,
    pub next: String,
    pub sync_token: String,
    pub complete: bool,
    pub store_pages: Option<u32>,
}
```

One page of a storefront's own library listing, as the plugin fetched it.

**Fields**

- `books`: Titles on this store page, in the store's order; any number of them.
- `removed`: Product ids gone from the account since `ScanParams::sync_token`, on a
  delta pass only; any number of them.
- `next`: The storefront's own cursor for the store page after this one; empty
  when this is the last store page.
- `sync_token`: On the last store page: the token the host sends as
  `ScanParams::sync_token` on the account's next pass. Ignored on
  earlier pages.
- `complete`: On the last store page: whether the pass listed every title the
  account holds (a full pass). Ignored on earlier pages.
- `store_pages`: Storefront requests this fetch took; `None` counts one.

Implements: `Clone`, `Debug`, `Default`, `Eq`, `PartialEq`

## Enums

### SdkError

```rust
pub enum SdkError {
    Message(String),
    Io(Error),
    Json(Error),
}
```

Errors from the guest stdio loop and SDK helpers (not plugin business logic).

Prefer mapping operator-visible failures into
[`bookclerk_plugin_abi::PluginError`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#pluginerror) inside [`crate::PluginWorker`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginworker)
methods. Use [`SdkError`](#sdkerror) for framing, JSON, and filesystem problems in the
SDK itself.

**Variants**

- `Message`: Operator-facing or diagnostic text with no structured ABI error code.
  
  Built via [`SdkError::message`](#sdkerrormessage). Typical sources: oversize RPC frames,
  missing side-channel descriptors, or authoring-tool validation failures.
- `Io`: Underlying OS I/O failure (stdio, files, sockets) while running SDK helpers.
- `Json`: JSON serialize/deserialize failure for Workers RPC request or response lines.

#### SdkError::message

```rust
pub fn message(msg: impl Into<String>) -> Self
```

Builds a [`SdkError::Message`](#sdkerror) from any displayable string.

##### Arguments

* `msg` - Human-readable explanation (no secret values).

##### Returns

An [`SdkError`](#sdkerror) suitable for helper APIs returning [`Result`](#result).

Implements: `Debug`, `Display`, `Error`, `From<Error>`, `From<SdkError>`

## Functions

### db_value_from_sea

```rust
pub fn db_value_from_sea(v: &Value) -> Result<DbValue, String>
```

Fallible SeaORM → [`bookclerk_plugin_abi::DbValue`](/docs/internals/crates/bookclerk_plugin_abi/db_value/index.md#dbvalue) bridge.

#### Errors

Returns a static reason when the SeaORM value is outside the universal
domain, or TEXT contains U+0000.

### proxy_rows_from_typed

```rust
pub fn proxy_rows_from_typed(stmt: &StatementResult) -> Result<Vec<ProxyRow>, String>
```

Builds SeaORM proxy rows from a typed statement result.

#### Errors

Returns when the result is not positional.

### chunk_indexes

```rust
pub fn chunk_indexes(
    typed: &[TypedDbStatement],
    max_statements: u32,
    max_request_bytes: u32,
) -> Result<Vec<Vec<usize>>>
```

Greedy split of `typed` into index runs that each fit one request.

Sizes are estimated per statement against one probe statement and each
run is verified by one exact encode; a run the estimate let through is
halved until it fits, and a lone statement over the cap is yielded on
its own. `0` lifts a cap.

#### Errors

Returns when a statement cannot be encoded (U+0000 in SQL or TEXT).

### execute_reply_to_d1_results

```rust
pub fn execute_reply_to_d1_results(reply: &ExecuteReply) -> Vec<D1Result>
```

Maps a typed execute reply to Cloudflare [`D1Result`](#d1result) per statement.

### statement_result_to_d1_result

```rust
pub fn statement_result_to_d1_result(
    stmt: &StatementResult,
    timing: &DbTiming,
) -> D1Result
```

Maps one typed statement result to Cloudflare [`D1Result`](#d1result).

### write_chunks_operation_id

```rust
pub fn write_chunks_operation_id(key: &str, offset: usize) -> String
```

The operation id [`DatabaseBinding::write_chunks`](#databasebindingwrite_chunks) sends for the batch
that starts at `offset` of the write named `key`.

It is UUID-shaped, so [`DatabaseBinding::chunk`](#databasebindingchunk) sizes the batches for
it: the first 16 bytes of SHA-256 over
`"bookclerk-write-chunks\0" + key + "\0" + offset` (decimal), as
lowercase hex grouped 8-4-4-4-12. The TypeScript and Python SDKs derive
the same id, so a write resumed from another SDK replays the same
receipts.

### fetch_work_dir

```rust
pub fn fetch_work_dir(params: &FetchTitleParams) -> Result<FetchWorkDir>
```

Resolves the directory a `fetchTitle` call should write into.

Thin wrapper around [`FetchWorkDir::open`](#fetchworkdiropen).

#### Arguments

* `params` - Host `fetchTitle` params (see [`FetchWorkDir::open`](#fetchworkdiropen)).

#### Returns

Open work directory for this RPC.

#### Errors

Propagates [`FetchWorkDir::open`](#fetchworkdiropen) failures.

### upload_file_path

```rust
pub fn upload_file_path(local_path: Option<&str>) -> Result<UploadFile>
```

Resolves the local file path for a `putFile` call.

Thin wrapper around [`UploadFile::open`](#uploadfileopen).

#### Arguments

* `local_path` - Optional path from host params (see [`UploadFile::open`](#uploadfileopen)).

#### Returns

Open upload file handle for this RPC.

#### Errors

Propagates [`UploadFile::open`](#uploadfileopen) failures.

### decode_json

```rust
pub fn decode_json<T: DeserializeOwned>(json: &str) -> Result<T, PluginError>
```

Deserialize a role-method JSON argument.

Empty input is treated as `{}`.

#### Errors

Returns `PluginError::invalid_params` when the payload is not valid JSON for `T`.

### encode_json

```rust
pub fn encode_json<T: Serialize>(value: T) -> Result<String, PluginError>
```

Serialize a role-method JSON result.

#### Errors

Returns `PluginError::invalid_params` when serialization fails, or
`PluginError::payload_too_large` when the encoded size exceeds
[`MAX_SCALAR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scalar_bytes).

### encode_atomic_result

```rust
pub fn encode_atomic_result<T: Serialize>(value: T) -> Result<String, PluginError>
```

Encodes an atomic result; an oversized scalar after commit is `unavailable`.

#### Errors

Returns `PluginError::payload_too_large` mapped to
`PluginError::unavailable` so the host retries the same `operationId`.

### page_rows

```rust
pub fn page_rows<T: Serialize>(
    rows: &[T],
    cursor: &str,
    limit: u32,
) -> Result<QueryPage, PluginError>
```

Page a JSON array of rows. `limit == 0` means [`MAX_LIST_PAGE`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_list_page).

#### Errors

Returns `PluginError::invalid_cursor` for a non-numeric cursor, or
`PluginError::payload_too_large` when the page exceeds [`MAX_SCALAR_BYTES`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scalar_bytes).

### manifest_capabilities

```rust
pub fn manifest_capabilities(
    manifest_toml: &str,
) -> Result<PluginCapabilities, PluginError>
```

Parses `plugin.toml` source and returns the [`PluginCapabilities`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#plugincapabilities) a guest
must advertise from `describe()`.

Keeping the manifest as the single source of truth means the host's
widening check (manifest vs describe vs operator grant) cannot drift: the
guest embeds the same file the host installed.

#### Arguments

* `manifest_toml` - Contents of the plugin's `plugin.toml`, typically
  `include_str!("../plugin.toml")`.

#### Returns

The typed capability declaration in manifest order.

#### Errors

Returns `PluginErrorCode::Internal` when the manifest does not parse or
fails validation — a build defect, not a runtime condition.

#### Examples

```rust
use bookclerk_plugin_sdk::manifest_capabilities;

let caps = manifest_capabilities(r#"
api_version = 3
id = "echo"
runtime = "native"
command = "./echo"
entrypoints = ["cli"]

[capabilities.network]
mode = "deny"
"#).unwrap();
assert_eq!(caps.entrypoints.len(), 1);
```

### manifest_media

```rust
pub fn manifest_media(manifest_toml: &str) -> Result<MediaSupport, PluginError>
```

Parses `plugin.toml` source and returns the [`MediaSupport`](/docs/internals/crates/bookclerk_plugin_abi/generated/index.md#mediasupport) a guest must
advertise from `describe()`.

The host refuses a storefront or metadata provider whose described media
differs from its manifest's `[media]` table, so deriving it from the
embedded manifest keeps the two equal.

#### Arguments

* `manifest_toml` - Contents of the plugin's `plugin.toml`, typically
  `include_str!("../plugin.toml")`.

#### Returns

The `[media]` declaration in its wire shape; empty lists for a plugin
without the table.

#### Errors

Returns `PluginErrorCode::Internal` when the manifest does not parse or
fails validation (including a storefront without `[media]`).

### fd_proc_path

```rust
pub fn fd_proc_path(fd: i32) -> PathBuf
```

Builds the OS path that refers to an open descriptor by number.

Linux uses `/proc/self/fd/{fd}`; macOS and other Unix use `/dev/fd/{fd}`.
The path is only valid while the descriptor remains open in this process.

#### Arguments

* `fd` - Open raw file descriptor previously received from the host.

#### Returns

PathBuf that can be passed to std / tokio filesystem APIs for as long as
`fd` stays open.

### recv_passed_fd

```rust
pub fn recv_passed_fd() -> Result<i32>
```

Receives one file descriptor from the host side channel (SCM_RIGHTS).

Blocks until the host sends a control message on [`PLUGIN_FD_CHANNEL`](#plugin_fd_channel).
Hosts do not send; prefer path strings unless you are implementing a
native shortcut that actually `sendmsg`s.

#### Returns

Raw OS file descriptor owned by the caller. Prefer wrapping it immediately
(see [`crate::FetchWorkDir`](#fetchworkdir) / [`crate::UploadFile`](#uploadfile)) so Drop closes it.

#### Errors

Returns [`SdkError`](#sdkerror) when [`PLUGIN_FD_CHANNEL_ENV`](#plugin_fd_channel_env) is unset or not equal to
[`PLUGIN_FD_CHANNEL`](#plugin_fd_channel), when `recvmsg` fails, or when the platform does not
support the side channel (non-Unix).

### scan_page

```rust
pub async fn scan_page<F, Fut>(
    params: &ScanParams,
    fetch: F,
) -> Result<ScanPage, PluginError>
where
    F: FnOnce(String, &ScanParams) -> Fut,
    Fut: Future<Output = Result<StorePage, PluginError>>,
```

Answers one `scan` call from the storefront's own pages.

Fetches the store page `params.cursor` names and returns at most
[`MAX_SCAN_PAGE_BOOKS`](/docs/internals/crates/bookclerk_plugin_abi/index.md#max_scan_page_books) of its titles and removed ids. A larger store page
is returned over several calls, each fetching it again. The pass ends on
the last slice of the store page whose [`StorePage::next`](#storepage) is empty, which
carries that page's `sync_token` and `complete`.

#### Arguments

* `params` - The scan call's params.
* `fetch` - Fetches the store page a storefront cursor names (empty for
  the first), given the call's params.

#### Returns

The reply for this call.

#### Errors

Returns the fetch's error unchanged; an `invalid_cursor` [`PluginError`](/docs/internals/crates/bookclerk_plugin_abi/error/index.md#pluginerror)
when the cursor was not written by this helper or no longer fits the store
page (the store changed mid-pass), so the host restarts the pass; and an
`internal` one when a store cursor is too long for a scan cursor.

### serve

```rust
pub async fn serve(plugin: impl PluginWorker) -> Result<()>
```

Serves a [`PluginWorker`](/docs/internals/crates/bookclerk_plugin_abi/index.md#pluginworker) on stdin/stdout (Cap'n Proto RPC).

Must run on a current-thread tokio runtime inside a `LocalSet` (this helper
creates the `LocalSet`). Abort is capability drop / stream cancel.

#### Errors

Returns [`SdkError`](#sdkerror) when the vat fails.

## Type aliases

### Result

```rust
pub type Result<T> = Result<T, SdkError>;
```

Result alias for guest helpers that fail with [`SdkError`](#sdkerror).

## Constants

### MAX_WRITE_KEY_BYTES

```rust
pub const MAX_WRITE_KEY_BYTES: usize = 256;
```

Longest `key` [`DatabaseBinding::write_chunks`](#databasebindingwrite_chunks) accepts, in bytes.

### PLUGIN_FD_CHANNEL

```rust
pub const PLUGIN_FD_CHANNEL: i32 = 3;
```

Fixed descriptor number the host leaves open for the plugin side channel.

Always `3` (after stdin/stdout/stderr). Guests must not close or reuse this
FD for other purposes while the channel is active.

### PLUGIN_FD_CHANNEL_ENV

```rust
pub const PLUGIN_FD_CHANNEL_ENV: &str = "BOOKCLERK_PLUGIN_FD_CHANNEL";
```

Environment variable the host *would* set to the decimal form of [`PLUGIN_FD_CHANNEL`](#plugin_fd_channel).

Hosts do **not** set this. Presence still arms [`crate::FetchWorkDir::open`](#fetchworkdiropen)
/ [`crate::UploadFile::open`](#uploadfileopen) to call [`recv_passed_fd`](#recv_passed_fd) instead of path
strings — only set it when the host is actually sending an FD.
