# Entrypoints, events and the ABI

This page is the reference for the Workers RPC surface a plugin
implements and the bindings it receives: entrypoint classes, events, KV
namespaces, queues, and the methods of each capability.

## ABI (api_version = 3, object-capability Workers RPC)

Public types are **classes and streams**, not transport verbs. Chunking,
`handleId`, `readChunk`, `writeChunk`, `finalize` and `abort` aren't ABI
methods. Abort is a stream cancel, or `RpcTarget` disposal.

```ts
// Default export: triggers declared in plugin.toml.
class BookclerkEntrypoint<Env> extends WorkerEntrypoint<Env> {
  describe?(): Promise<PluginDescribe>;                 // optional refinement
  event?(batch: EventBatch): Promise<void>;             // [[events.consumers]]
  queue?(batch: QueueBatch): Promise<void>;             // [[queues.consumers]]
  job?(job: JobController): Promise<JobCompletion | void>; // [triggers] jobs
  scheduled?(controller: ScheduledController): Promise<void>; // [triggers] crons
  databaseMigrations?(binding: string): Promise<PluginMigration[]>; // [[databases]]
  shutdown?(): Promise<void>;
}

// Named entrypoints: one exported class per `entrypoints = [...]` item.
export class Storefront extends StorefrontEntrypoint<Env> { /* login, scan, fetchTitle, … */ }
export class Storage extends StorageEntrypoint<Env> { /* head, list, get, put, copy */ }
export class RemoteLibrary extends RemoteLibraryEntrypoint<Env> { /* health, diagnose, start, stop */ }
export class DatabaseAdapter extends DatabaseAdapterEntrypoint<Env> { /* openSession */ }
export class Cli extends CliEntrypoint<Env> { /* describe, invoke */ }
export class Oidc extends OidcEntrypoint<Env> { /* clients, authenticateUser */ }
export class Metadata extends MetadataEntrypoint<Env> { /* health, lookup, search, chapters */ }
export class Covers extends CoverEntrypoint<Env> { /* health, fetchCovers */ }

export default class MyPlugin extends BookclerkEntrypoint<Env> { /* … */ }
```

### On the wire

On the wire this is
`PluginWorker { describe; open(invocation, bindings) -> Entrypoints; shutdown; databaseMigrations }`.

- The trusted adapter isolate resolves each `Entrypoints` capability to
  the matching exported class, through its `PLUGIN_<ENTRYPOINT>` service
  binding.
- Before every call it merges `Bindings` (`config`, `secrets`, `events`,
  `databases`, `storage`) onto the author's `env`.
- Authors never subclass bare `WorkerEntrypoint`. The adapter-private
  `GRANTED`, `BRIDGE_TOKEN` and `PLUGIN_DESCRIBE` live only on the
  wrapper (`AdapterEnv`).

Between the launcher and the adapter isolate, every ABI method call is one
`POST /invoke`. Its body is the `<Interface>.<method>$Params` struct as
Cap'n Proto bytes, and its reply is the `$Results` struct. The launcher
reuses the host's typed Cap'n clients over an HTTP hook, and the isolate
decodes with the generated `generated-wire.ts` codecs.

- Only the control handshake (`describe`, `open`, `shutdown`) is JSON.
- Object bodies stream over dedicated routes.
- `JobController` capabilities travel as grant-token descriptors the
  isolate redeems on `GRANTED`.

Maintainer reference: [workerd bridge](/docs/internals/workerd-bridge/index.md).

### Events and jobs

`event(batch)` mirrors Workers `queue(batch)`. Each `EventMessage` records
one outcome, and the first call wins:

- `ack()`;
- `retry({ retryAt | delaySeconds, reason })`;
- `reject(reason)`;
- `deadLetter(reason)`;
- `suspend({ checkpoint, wakeAt, wakeOnEventType, wakeOnFilter })`.

Untouched messages ack when the handler returns, and retry when it
throws.

`job(job)` mirrors Workers `scheduled(controller)`:

- Returning completes the job, optionally with `{ message, bytesCopied }`.
- Throwing rejects it. `unavailable` and `deadline_exceeded` are
  retryable, and `cancelled` cancels it.
- `job.suspend({ checkpoint, wakeAt })` and
  `job.retryLater({ retryAt, reason })` record the other terminal
  outcomes.
- `job.signal` is a **locally created** `AbortSignal`, projected from the
  transport cancellation capability, because an AbortSignal doesn't
  serialize as a Workers RPC value.

`JobInvocation` is a versioned durable **command envelope**. The envelope
schema version and the payload schema version are separate.

- Idempotency keys are scoped to `(account, plugin, commandType)` until a
  terminal fenced outcome is committed. They aren't reusable across
  accounts.
- `deadlineUnixMs` is a hint to the guest. The host fence and lease are
  authoritative, and must not be outlived.
- A suspension is durable only after Bookclerk atomically commits the
  fenced outcome.

`JobController` grants `input`, `output` and `progress()` for one durable
invocation. Media flows through those streams. Progress, checkpoints,
completion, retry class and cancellation stay job state, not chunk
messages.

### Workerd is the front door

Workerd is the **control-plane** front door (invocation, policy, binding,
lifecycle, outcome) for **every** plugin.

- The host always spawns `bookclerk-workerd` through `bookclerk-jail`.
- For `runtime = "native"` it also spawns the backend as a sibling jail,
  and hands both children the inherited RPC and proxy links. The launcher
  never sees `BOOKCLERK_NATIVE_BACKEND` and never starts the guest itself.
- Isolate, native jail and a future container are backends the host
  selects from `runtime`.

For a native guest, the launcher speaks typed Cap'n Proto over the
inherited RPC link. It forwards every `Entrypoints` family (event
consumer, job runner, storefront, storage, database adapter, remote
library, CLI, OIDC) without entering JavaScript. The adapter isolate only
decides `describe` (merged against `PLUGIN_DESCRIBE`) and the `open`
policy (`POST /open` → `openInvocation`), and receives `shutdown`.

> [!IMPORTANT]
> Direct host-to-native Cap'n Proto isn't a product path. It exists only
> as `SpawnTransport::DirectNativeDiagnostic`, for tests and diagnostics.
> A missing `bookclerk-workerd` or `workerd` is a hard spawn error in
> every isolation mode. The OS jail is still required, and Windows
> `Isolation::Off` still needs `bookclerk-jail` beside the host.

### Native sockets

Native plugins must be rebuilt against this SDK.

- Production transport is the mux `fd:` or `handle:` link, and
  `PluginSocket::into_stream`.
- `into_split` and `into_unix_stream` are for Unix pathname sockets only.
  They return an unsupported-transport error on a mux link, and don't
  open a TCP socket.
- The host gives each guest a fresh challenge
  (`BOOKCLERK_SESSION_CHALLENGE`) and reads those bytes before it serves
  the proxy. An unrelated child, or another session's guest, can't
  complete that challenge. The numeric descriptor isn't the session.
- On macOS, socket and pipe creation holds a process-wide lock from
  allocation through `FD_CLOEXEC` and through in-process
  `Command::spawn`, because macOS has no `SOCK_CLOEXEC`. The SDK sets
  `FD_CLOEXEC` again when it adopts an inherited descriptor.

### Limits and negotiation

- List pagination is **opaque and bounded**. A missing or stale cursor
  returns `invalid_cursor`, never a silent restart at page one.
  Concurrent mutation is weakly consistent. Local backends don't promise a
  lexicographic walk over an unsorted folder without an index.
- Scalar RPC values are capped at **256 KiB** (`payload_too_large` if
  exceeded). List pages are clamped.
- A SQL request or result over a negotiated `DbCapabilities` cap fails
  with `limit_exceeded`. `PluginError.details` (a JSON object, empty when
  an error carries none) holds `{ "limit", "cap", "used" }`, and the
  message reads `limit exceeded: <cap> is <n>; used <m>`; the SDKs expose
  both as `err.limit`. `GuestDatabase.limits` returns the caps of the
  session so a guest can stay under them; on a host that predates the
  method it fails with `unsupported`.
- A result larger than one inline reply is read as a stream.
  `GuestDatabase.executeStreamed` (and the adapter-side
  `AdapterDatabaseSession.executeStreamed`) answer the same atomic batch
  as `ExecuteStreamFrame`s under `maxStreamedResultBytes` /
  `maxStreamedResultRows`, which are at least the inline caps; an adapter
  that advertises `0` for both does not stream and answers `unsupported`.
  The SDKs read `all()` and `iterate()` through it when the session
  streams. See [streamed results](/docs/plugins/sql-contract/v1/index.md#streamed-results)
  and [Working within database limits](/docs/plugins/database-limits/index.md).
- Integrity metadata (etag, sha256) rides on `PutResult` and
  `ReadResult`.
- Optional facilities *within* the ABI are feature flags (`rpc.streams`,
  `rpc.scalarLimits`, `storage.copy`, and the storage
  [intent operations](#intent-operations)), not a substitute for
  `apiVersion`.

Spawn **negotiates**:

- `apiVersion == 3`;
- a matching verified, provenance-qualified identity, declared
  `entrypoints` and triggers;
- the required `rpc.streams` and `rpc.scalarLimits`.

It rejects zero or unsafe limits. There is no `kind` or `supportedRoles`
on the wire, and describe rejects unsupported versions.

### Transports

Every transport has the same observable contract.

- **workerd.** The isolate keeps `RpcTarget` stubs. `bookclerk-workerd`
  serves Bookclerk Cap'n Proto on stdio, and talks HTTP/JSRPC to the
  isolate with streamed bodies (`capnpConnectHost = "plugin"` on the rpc
  socket). Author methods travel as one `POST /invoke` Cap'n `$Params`
  body.
- **native, behind workerd.** The guest SDK's `serve` serves
  `schema/plugin.capnp` (`capnp-rpc`), with windowed byte streams on
  stdin/stdout (the inherited RPC link). `bookclerk-workerd` owns the
  other end, forwards every entrypoint family typed, and serves the host
  on its own stdio. CONNECT uses the inherited mux link.
  `ExecutorIdentity.runtime_backend = "native-behind-workerd"`.
- **native, direct (diagnostic).** The same guest wire, with the host
  connected to the guest's stdio and no launcher in between. This is
  `SpawnTransport::DirectNativeDiagnostic` only
  (`runtime_backend = "native-direct"`).

FD passing and `localPath` remain native-only optimizations behind the
stream adapter, never visible to authors.

First-party destinations (`local`, `s3`) and the remaining product guests
speak the object-capability ABI. The Echo examples are `api_version = 3`
guests that export `cli` (and optional event and job triggers), not a
`kind = "integration"`.

### Coming from Cloudflare Workers

| Workers concept | Bookclerk v3 |
| --- | --- |
| `export default class extends WorkerEntrypoint` | `export default class extends BookclerkEntrypoint` (`event` / `queue` / `job` / `scheduled` triggers) |
| Named `export class` entrypoints | `entrypoints = ["storefront", …]` + matching `*Entrypoint` subclass |
| `env.DB` | `[[databases]]` → granted on `env` |
| `env.KV` | `[[kv_namespaces]]` → `get` / `getWithMetadata` / `put` / `delete` / `list` with `expiration`, `expirationTtl`, and `metadata` |
| `env.SECRETS` | `[secrets]` → granted on `env` |
| `[[queues.producers]]` / `[[queues.consumers]]` | `env.<BINDING>.send` / `sendBatch` and `queue(batch)` with per-message `ack` / `retry` |
| `[[events.consumers]]` | `event(batch)` with `ack` / `retry` / `reject` / `deadLetter` / `suspend`, and `env.EVENTS.read` to catch up on past events |
| `[[events.producers]]` | `env.EVENTS.publish` (host outbox; forced `source`) |
| `[triggers] crons` / `scheduled(controller)` | `[triggers] crons` and `scheduled(controller)`, five-field UTC schedules (see [Scheduled triggers](#scheduled-triggers)) |
| `[triggers] jobs` | `job(controller)` (durable command envelope) |
| `wrangler types` | `bookclerk-plugin types` → generated `Env` |
| Workers for Platforms / Dynamic Workers | **Not used**: local embedded workerd + OS jail only |

## Publishing events (`env.EVENTS`)

Plugins that declare `[[events.producers]]` publish domain events through
the `EVENTS` binding. It is a `Bindings.events` capability the host passes
to `PluginWorker.open(invocation, bindings)`.

There is no other guest-to-host notification path. The former
`HOST.notify` reverse channel and its `host_stub.js` and `NOTIFY` bindings
are gone.

```ts
const ok = await env.EVENTS.publish({
  eventType: "wishlist_synced",         // must be a granted [[events.producers]] type
  schemaVersion: 1,                     // defaults to 1
  deduplicationKey: `wishlist:${asin}`, // optional; see below
  payload: { asin, title },             // JSON, ≤ 64 KiB UTF-8 (MAX_EVENT_PAYLOAD_BYTES)
});
// ok: { eventId: string, duplicate: boolean }
```

The host `EventPublisher` writes straight into the library outbox
(`domain_events`), with these rules:

- **Forced provenance.** `source` is always the plugin's PluginKey, and
  `account_id` is the opening invocation's account, so a guest can't
  spoof another producer. `correlationId` and `causationId` default to the
  invocation's values when the guest leaves them empty.
- **Host-emitted types.** Some domain events belong to the host.
  `book_acquired` is one: a source plugin's acquire handler returns the
  book, then the host's acquire pipeline records it and publishes
  `book_acquired` in the same transaction as the edition's acquire state.
  Its payload names the title by the account holding that acquired it
  (`titleId`), its edition (`editionId`), `source`, `asin`, `isbn`,
  `accountId` and the written `pathKeys`.
  `edition_linked`, `edition_updated` and `holding_added` are written by
  the library model resolver in the same batch as the store listing they
  describe, `holding_removed` in the batch that deletes the holding,
  `edition_acquire_changed` with an acquire state change other than
  becoming acquired, `ingest_batch_finished` when an upload or storage
  intake batch ends, `wishlist_changed` and `listening_synced` by the
  library after a wishlist or listening write, and `playback_started`,
  `playback_progress` and `playback_finished` by the built-in player after
  a listening write. A plugin can consume them under
  `[[events.consumers]]`, but can't declare them under
  `[[events.producers]]` (`check` and load fail), and the host publisher
  refuses them even from an older grant.
- **Producer grant.** Publishing needs the manifest to declare
  `[[events.producers]]` *and* the operator grant to cover those types
  (the consent request lists them). Publishing a type outside that
  intersection fails with `forbidden`. With no consented producer and no
  consented consumer (see [Reading past events](#reading-past-events-enveventsread)),
  `env` has no `EVENTS`.
- **Payload cap.** `payload` is UTF-8 JSON of at most 64 KiB
  (`payload_too_large` otherwise). Non-JSON bytes are `invalid_params`,
  and an empty payload is stored as `{}`.
- **Deduplication.** `(account_id, source, event_type, deduplication_key)`
  is a permanent unique index on the outbox. A repeat publish returns the
  existing `eventId` with `duplicate = true`, instead of inserting a second
  row. An empty `deduplicationKey` gets a fresh UUID, so it always
  publishes.
- **Availability.** Outbox write failures surface as `unavailable`
  (retryable). The event is never half-written.

**Transports.** Native guests receive `Bindings.events` as a Cap'n Proto
capability. Under workerd:

1. The trusted adapter isolate mints a per-`open`, events-only grant token
   on the launcher's `GRANTED` channel.
2. It hands the author a `GrantedEvents` `RpcTarget`.
3. `publish()` POSTs the event to `/events/publish`. The launcher checks
   the grant again (unknown, expired or database-only grants are
   `forbidden`) and enforces the payload cap, before forwarding to the host
   publisher.

Author isolates never see `GRANTED` or the grant token.

## Reading past events (`env.EVENTS.read`)

A plugin that sleeps, or that was down, can miss deliveries: they
[expire](#retention-of-undelivered-events) after the consumer's
`message_retention_period`. Instead of a growing backlog, the plugin pulls
what it missed from the outbox when it next runs, the way a Workers
consumer re-reads its source after a gap.

```ts
let after = await env.KV.get("events-cursor") ?? undefined;
for (;;) {
  const page = await env.EVENTS.read({ after, types: ["book_acquired"], limit: 100 });
  for (const event of page.events) {
    // event.deduplicationKey is the event id; dedupe on it.
  }
  if (page.cursor) await env.KV.put("events-cursor", page.cursor);
  if (!page.more) break;
  after = page.cursor;
}
```

The `EVENTS` binding exists when a consented `[[events.producers]]` **or**
`[[events.consumers]]` row exists. `read` needs a consumer; `publish` still
needs a producer.

- **What it returns.** Events, oldest first, that the plugin's consented
  `[[events.consumers]]` rows match by type, schema version and `filter`,
  exactly as delivery matches them. `types` narrows the read to some of
  those types; an empty list means all of them, and a type outside the
  consent is `forbidden`. Queue messages are never returned.
- **Account scope.** An invocation opened for an account reads only that
  account's events. An invocation with no account reads every account, as
  its deliveries do.
- **Where it starts.** Pass at most one of `after` (a cursor from an
  earlier page) and `since` (a `Date` or Unix milliseconds; `sinceUnixMs`
  is accepted as the same field). With neither,
  the read starts at the oldest event the host keeps. Reads never go back
  further than `[events].retention_days`; `truncated` is true when the
  start was older than that, so the plugin knows it may have lost events
  for good.
- **Paging.** `limit` defaults to, and may not exceed, `MAX_LIST_PAGE`.
  Keep the `cursor` and pass it back as `after` while `more` is true. The
  cursor is opaque, at most 512 bytes (`MAX_EVENT_CURSOR_BYTES`), and a
  cursor the host did not issue is `invalid_cursor`. A page can hold fewer
  events than `limit` with `more` set: each read scans a bounded number of
  outbox rows, and the cursor then marks how far it got.
- **The last 30 seconds wait.** A read returns only events stored at least
  30 seconds ago (`EVENT_STREAM_SETTLE_SECS`). The host stamps an event's
  time before its insert commits, so a slow publication can land behind a
  newer one; holding the newest events back keeps a cursor from moving
  past an event that has not appeared yet. Newer events still arrive
  through delivery, and the next read picks them up.
- **Gap notice.** `expiredEventIds` lists the events in the page whose
  delivery to this plugin expired unhandled.
- **Not a delivery.** A read changes no delivery state and is not
  acknowledged. `deliveryAttempt` is `0` and `deduplicationKey` is the
  event id, so a plugin that also receives deliveries dedupes the two on
  the event id.

**Transports.** Native guests call `EventPublisher.read` on the
`Bindings.events` capability. Under workerd, `read()` POSTs to
`/events/read` on the same grant as `publish()`; the launcher refuses a
body over 64 KiB or one that is not a JSON request object, then the host
checks consent and bounds.

## KV namespaces

`[[kv_namespaces]]` gives a plugin Workers `KVNamespace`-shaped storage,
which the host serves from the library database (`plugin_kv`). Every row
is scoped to the plugin's PluginKey and to the namespace the manifest row
names. So the values follow the instance: a sync cursor written on one
host is what the same instance reads after it moves to another.

```toml
[[kv_namespaces]]                # env.KV, namespace "kv"

[[kv_namespaces]]
binding = "CURSORS"              # env.CURSORS
namespace = "sync.cursors"       # [a-z0-9][a-z0-9._-]*; default: binding lowercased
max_value_bytes = 4096           # default 65536, at most 1 MiB
max_keys = 500                   # default 10000, at most 1000000
```

```ts
await env.CURSORS.put(`audible:${accountId}`, nextPageToken, {
  expirationTtl: 86_400,          // or `expiration` (seconds since epoch)
  metadata: { scannedAt: Date.now() },
});
const cursor = await env.CURSORS.get(`audible:${accountId}`); // string | null
const { value, metadata } = await env.CURSORS.getWithMetadata(key, "json");
const listing = await env.KV.list({ prefix: "audible:", limit: 100 }); // { keys, list_complete, cursor? }
await env.KV.delete(key);
```

The rules:

- **Scope.** The guest never chooses the plugin key or namespace; both
  come from the manifest row and the spawned identity. Two rows are
  separate stores unless they name the same `namespace`.
- **Consent.** Declaring any row adds the `plugin_kv` binding token to the
  consent request. Without it, no `env.<BINDING>` appears.
- **Limits.** Keys are 1–512 UTF-8 bytes (`MAX_KV_KEY_BYTES`), metadata is
  JSON of at most 1 KiB (`MAX_KV_METADATA_BYTES`), and a value is at most
  the row's `max_value_bytes` (`payload_too_large` otherwise). A `put` of a
  new key into a namespace already holding `max_keys` live keys fails with
  `forbidden`. Rewriting an existing key never counts against the cap.
- **Expiry.** Expiry is lazy. An expired key reads as absent, doesn't
  count against `max_keys`, and is removed by the next write that needs
  the slot, or by the host's periodic prune.
- **Consistency.** Reads see the latest committed write (it is a library
  row, not an edge cache), so there is no Workers-style 60-second
  propagation window.
- **Transports.** Native guests receive `Bindings.kv` (`NamedKv`) as Cap'n
  Proto `KvNamespace` capabilities. Under workerd, the adapter isolate
  mints one kv-only grant token per binding, and the author's
  `env.<BINDING>` calls `POST /kv/get|put|delete|list` on the launcher's
  `GRANTED` channel. Python guests get the same surface as `KvNamespace`
  (`get`, `get_with_metadata`, `put`, `delete`, `list`).

## Queues

`[queues]` gives a plugin Workers-shaped queues on the host outbox.

- A `[[queues.producers]]` row is an `env` binding that sends to one
  queue.
- A `[[queues.consumers]]` row delivers that queue to the default export's
  `queue(batch)` trigger.
- Queue names are `[a-z0-9][a-z0-9._-]*`. The `core.` and `host.` prefixes
  are the host's (`core.events` is the domain-event bus that `[[events.*]]`
  rows bind to).
- Two plugins that name the same queue share it: one produces, the other
  consumes.

```toml
[[queues.producers]]
queue = "thumbnails"
binding = "THUMBNAILS"          # env.THUMBNAILS

[[queues.consumers]]
queue = "thumbnails"
max_batch_size = 10             # messages per queue(batch) call (≤ 100)
max_retries = 3                 # redeliveries before dead-letter
dead_letter_queue = "thumbnails-dlq"
retry_delay = 30                # seconds when retry() names no delay
message_retention_period = 3600 # seconds a due message may wait unleased (default 1 day)
```

```ts
// Producer: Workers `Queue`-shaped.
const { messageIds } = await env.THUMBNAILS.send({ bookId }, { delaySeconds: 5 });
await env.THUMBNAILS.sendBatch(
  [{ body: "plain", contentType: "text" }, { body: bytes, contentType: "bytes" }],
  { delaySeconds: 0 },
);

// Consumer: one ordered batch from one queue, one outcome per message.
export default class MyPlugin extends BookclerkEntrypoint<Env> {
  async queue(batch: QueueBatch) {
    for (const msg of batch.messages) {          // msg.id, msg.timestamp, msg.attempts, msg.source
      try {
        await handle(msg.json());                // or msg.text() / msg.body
        msg.ack();
      } catch {
        msg.retry({ delaySeconds: 60, reason: "downstream busy" });
      }
    }
  }
}
```

The rules mirror `event(batch)`:

- **Outcomes.** `ack()` marks the message delivered. `retry()` redelivers
  after `delaySeconds`, or after the consumer's `retry_delay` when none is
  given. Untouched messages ack when the handler returns, and retry when
  it throws. Delivery is at-least-once, so consume idempotently on
  `msg.id`.
- **Dead letters.** A message still retrying after `max_retries`
  redeliveries is parked as `dead_letter`. When the consumer names a
  `dead_letter_queue`, the host first copies the message there, so a
  second consumer (or an operator) can pick it up.
- **Retention.** A message that is never handed to the consumer expires
  after `message_retention_period` (see
  [Retention](#retention-of-undelivered-events)).
- **Bodies.** `contentType` is `json` (the default; the body is JSON
  text), `text` (UTF-8) or `bytes` (raw). Bodies are capped at 64 KiB
  (`MAX_EVENT_PAYLOAD_BYTES`), and a batch sends at most `MAX_LIST_PAGE`
  messages. Sends never coalesce: every `send` is a new message.
- **Forced provenance.** `source` is the sending plugin's PluginKey, and
  the account is the opening invocation's. The queue is fixed by the
  manifest row, never chosen per call.
- **Consent.** Each producer binding and each consumer queue is a grant
  token (`queue:<BINDING>`, `queue_consumer:<queue>`) in the consent
  request. A binding the operator hasn't granted is absent from `env`, and
  a queue the grant doesn't cover is never delivered. `describe()` can't
  widen either list beyond `plugin.toml`.
- **Transports.** Native guests receive producers on `Bindings.queues` as
  Cap'n Proto capabilities, and the batch on `QueueConsumer.queue`. Under
  workerd, the adapter isolate mints one queue-only grant token per
  binding and hands the author a `GrantedQueue` `RpcTarget`. `send` and
  `sendBatch` POST to `/queues/send` on the launcher's `GRANTED` channel,
  where the grant and the caps are checked again before the host producer
  writes the outbox.

Operators see queues with `bookclerk queues list` (counters and live
consumers per queue) and `bookclerk queues inspect <name>` (recent
messages and deliveries), backed by `GET /api/queues` and
`GET /api/queues/{name}`. Delivery rows are the same `event_deliveries`
that the `bookclerk events` verbs act on (`retry`, `ack`, `cancel`).

## Scheduled triggers

`[triggers] crons` runs the default export's `scheduled(controller)` on a
schedule, as Workers Cron Triggers do.

```toml
[triggers]
crons = ["*/30 * * * *", "0 3 * * MON-FRI"]
```

```ts
export default class MyPlugin extends BookclerkEntrypoint<Env> {
  async scheduled(controller: ScheduledController) {
    // controller.cron, controller.scheduledTime (UTC Unix ms),
    // controller.fireId, controller.attempt, controller.deadlineUnixMs
    await refresh(controller.scheduledTime);
  }
}
```

Python authors define `async def scheduled(self, controller)` and receive a
frozen `ScheduledController` (`cron`, `scheduled_time`, `fire_id`,
`attempt`, `deadline_unix_ms`). Native guests implement
`ScheduledHandler::scheduled` and return it from `open` as
`Entrypoints.scheduled_handler`.

- **Schedules.** Each entry has five fields (minute, hour, day of month,
  month, day of week) and is read in UTC. Fields take `*`, values, ranges,
  lists and `/step`; months and weekdays also take `JAN`–`DEC` and
  `SUN`–`SAT`, and `7` is Sunday. When both day fields are restricted, a
  day matching either one fires, as in Vixie cron. `L`, `W`, `#`, `@daily`
  style macros and seconds are rejected, and so are schedules that never
  fire or can go nine years without firing (such as `0 0 29 2 */7`,
  February 29 on a Sunday). A manifest declares at most 8 schedules of at most 128 bytes each
  (`MAX_CRON_BYTES`).
- **One fire per instance.** Each fire runs once per deployed plugin
  instance, library-wide. Every daemon checks its schedules every 15
  seconds, and a compare-and-swap on the shared `plugin_cron_cursors` row
  lets exactly one node claim a fire. The claim admits a durable
  `plugin_scheduled` job in the same batch, and the job queue routes it to
  a node that runs the instance (see
  [Job kinds](/docs/internals/jobs/index.md#job-kinds)).
- **Missed fires coalesce.** A library that was down through several fire
  times runs one late fire for the newest of them, with that time as
  `scheduledTime`. The same goes for an instance that was undeployed and
  is deployed again. A schedule seen for the first time (a new instance,
  or a schedule a new version adds) waits for its next fire.
- **Overlap.** A fire that comes due while the previous fire of the same
  schedule is still queued or running is skipped, and the daemon logs a
  warning.
- **Retries.** Returning completes the fire. Throwing retries the same
  fire (same `scheduledTime` and `fireId`) with backoff, up to 3
  attempts, so handlers should be idempotent on `fireId`.
- **Consent.** Each schedule is a grant token (`cron:<schedule>`, with the
  schedule's whitespace normalized). A schedule the grant doesn't cover
  never fires, and `describe()` can't add schedules beyond `plugin.toml`.

> [!NOTE]
> Fires run only on library nodes. An owned branch node (one that runs work
> for a single member) doesn't claim `plugin_scheduled` jobs.

## Pushed sockets (`[sockets]`)

Some services push changes over a WebSocket instead of being polled
(Audiobookshelf's Socket.io channel, for example). Holding that socket
open would keep the plugin running forever, so the host holds it instead,
as Durable Objects' hibernatable WebSockets do: the plugin opens a socket
through its binding, the host keeps the connection while the plugin
sleeps, and each real message wakes the plugin's socket handler.

```toml
[sockets]                 # env.SOCKETS; `binding = "PUSH"` renames it

[capabilities.network]
mode = "outbound"
tcp = ["abs.example.com:443"]
```

> [!NOTE]
> The host hands out the `Sockets` binding to deployed integrations (the
> family Audiobookshelf belongs to) whose grant has the `sockets` token.
> Storefront and storage deployments don't get it yet. Until a plugin uses
> it, it keeps its polling fallback.

Each SDK shapes the binding like Durable Objects' hibernatable WebSockets:
`env.SOCKETS.connect(url, options)` and `getWebSockets()` in TypeScript
(`get_web_sockets()` in Python), with messages on the default
entrypoint's `webSocketMessage(ws, message)` and closes on
`webSocketClose(ws, code, reason, wasClean)` (`web_socket_message` and
`web_socket_close` in Python). Rust plugins use the binding directly or
through `bookclerk_plugin_sdk::sockets::HostWebSocket`. SDK attachments
are UTF-8 JSON, so any SDK reads what another stored. See the
[TypeScript](/docs/plugins/sdk/typescript/index.md#pushed-sockets),
[Python](/docs/plugins/sdk/python/index.md#pushed-sockets) and
[Rust](/docs/plugins/sdk/rust/index.md#pushed-sockets) guides.

- **Binding.** `Sockets.connect` takes a `ws://` or `wss://` URL, the
  subprotocols to offer, extra request headers, up to 4 heartbeat pairs
  and an attachment, and returns the socket's id. `send`, `close`,
  `setAttachment` and `list` act on the plugin's own sockets only. An
  instance holds at most 8 sockets (`maxSocketsPerInstance`).
- **Handler.** A plugin that declares `[sockets]` may return a
  `SocketHandler` from `open`. The host calls `message` with each frame
  and the socket's attachment, and `closed` once when the socket ends,
  with the close code, the reason and whether the close was clean. A
  plugin that returns no handler gets no pushed messages.
- **Poll now.** `message` replies with `SocketMessageOk`. Setting
  `pollEvents` asks the host to call `pollEvents` right away, while the
  plugin is awake, instead of at the next scheduled poll. A remote
  library sets it when a message announces a new user, so the user gets
  a claim ticket within seconds. The host ignores it for a plugin whose
  host schedules no poll.
- **Heartbeats.** Each pair names a request frame and its reply. When an
  incoming frame equals a request exactly (same kind and bytes), the host
  sends the reply and doesn't wake the plugin, so a Socket.io ping `2`
  answered with `3` costs no start. Frames are 1 to 256 bytes.
- **Attachment.** Up to 2 KiB of plugin bytes stored with the socket and
  handed back with every message, as `serializeAttachment` is for
  Durable Objects. A plugin keeps what it needs to handle a message there
  (an account id, a library id), since it may have restarted in between.
- **Checks.** The host refuses, and the Rust SDK client checks before
  sending, a URL with credentials, a
  fragment, a percent-encoded, punycode (`xn--`) or non-canonical host
  (`127.1`, `0x7f.1`),
  or a bad port; header names the broker owns (`Host`, `Upgrade`,
  `Connection`, `Sec-WebSocket-*` and other hop-by-hop headers); control
  bytes in a header value; frames over 256 KiB
  (`maxSocketFrameBytes`); and close codes a peer may not send. Header
  values may be credentials, so errors never repeat them.
- **Consent.** Declaring `[sockets]` adds the `sockets` binding token to
  the grant, and the target of every socket is checked against the
  network grant as any other connection is.
- **Broker.** One broker per plugin instance holds its sockets: the
  front door, `bookclerk-workerd`, started in broker mode inside the
  plugin's jail under its effective network grant. A socket's host must
  be on the grant's `domains` (a WebSocket starts as an HTTP request) or
  have a `tcp` entry for its port, and the broker connects only to
  resolved addresses the grant allows, with no redirects. `wss://` is
  checked against Mozilla's root certificates. The broker sends the
  host's `User-Agent` (see [User-Agent](/docs/plugins/capabilities/index.md#user-agent)) and
  gives up on a connection after 10 seconds, a handshake after 15, a
  frame write after 10 and a close after 5.
- **Lifetime.** The host starts the broker on the plugin's first
  `connect` and stops it once the last socket closed, so an instance
  with no socket runs nothing. The broker belongs to the deployment, not
  to the plugin process: a plugin that sleeps or restarts keeps its
  sockets, and a message for a sleeping plugin starts it. A message that
  arrives while the instance is still starting waits for it rather than
  being dropped. If the broker dies, each of its sockets is reported
  closed with 1006 and the attachment the host last saw. A change to the
  plugin's grant stops the broker the same way, like any other plugin
  process; the next `connect` starts a broker under the new grant.
  Redeploying the instance starts a fresh broker, and the old one's
  sockets close with it.
- **Delivery.** Messages for one socket reach the plugin in order, one
  at a time. Up to 32 may wait while the plugin starts; past that the
  broker stops reading the socket (heartbeats included) until the plugin
  catches up, but still sends what the plugin sends on it. A socket that
  ended still counts against the 8-socket limit until the plugin has
  taken its last message and its close. `closed` comes after a socket's
  last message, with code 1009 when the server sent a message over
  256 KiB, 1005 when its close frame had no code, 1006 when the
  connection dropped without one, and 1001 when the broker itself
  stopped.

## Inbound webhooks (`[[webhooks]]`)

Some services report changes by calling a URL (Backblaze B2's event
notifications, for example). A plugin can't listen for them itself: it
sleeps, has no address, and may run on any node. So the host takes the
request on the library's public address, checks it, stores it, and the
plugin reads it later through `env.WEBHOOKS`, like a pulled Workers Queue.
The manifest rows are in [`[[webhooks]]`](/docs/plugins/manifest/index.md#webhooks-inbound-webhooks).

```ts
const url = await env.WEBHOOKS.url("b2-events"); // null without a public address
const { messages, missed } = await env.WEBHOOKS.pull("b2-events", { batchSize: 50 });
// ...handle each message.body...
await env.WEBHOOKS.ack("b2-events", { acks: messages.map((m) => m.leaseId) });
```

- **URL.** `url(name)` mints the instance's token for that row once and
  returns `<public origin>/hooks/<token>/<name>`, where the token is 43
  characters of base64url (32 random bytes) and the library keeps only its
  SHA-256 and a sealed copy. It returns no URL unless
  `integrations.public_origin` is an `https` origin on a globally reachable
  host (a public DNS name or global IP address, not `localhost`, a private
  or link-local address, or a `.local`-style name), and
  `plugins.webhooks` is `auto`. A plugin without a URL keeps its fallback,
  such as a listing.
- **Route.** `POST /hooks/<token>/<name>` is outside operator auth; the
  token is the credential. The route answers 404 for an unknown token or
  name, 405 for another method, 429 over the row's `rate_per_minute` (a
  token bucket per instance and webhook), 413 for a body over
  `max_body_bytes`, 401 for a missing or wrong signature, 400 for a kept
  header that repeats or holds a control character, and 503 while
  webhooks are off, the signing secret is unset, this node runs no guest
  for the instance, or the instance already holds 10,000 waiting requests.
  A stored request gets 204. The body of a refusal says no more than its
  status.
- **Signature.** An `hmac-sha256` row computes HMAC-SHA256 of the raw body
  under the secret setting it names and compares it in constant time with
  the signature header (after its prefix, decoded as hex or base64). The
  header must appear exactly once.
- **Stored request.** The host keeps the body as sent, `content-type` and
  the row's `headers` (lowercase), and when it arrived, for the row's
  `retention_secs`. Requests are stored in the library database in chunks
  that fit every database profile.
- **Pull.** `pull(name, { batchSize, visibilityTimeoutMs })` leases up to
  `batchSize` (1 to 100, default 10) waiting requests, oldest first, and
  hides them from other pulls for the visibility timeout (default one
  minute, at most 12 hours). A page also stops at 4 MiB of bodies. Each
  message carries `leaseId`, `timestamp`, `attempts`, `headers` and `body`
  (bytes). `missed` is true once after requests expired unread or were
  dropped at the cap, so the plugin resynchronizes another way.
- **Ack.** `ack(name, { acks, retries })` deletes acknowledged requests
  and offers retried ones to the next pull at once, up to 100 leases in
  each list; a lease can't be in both. A lease that ran out is offered
  again on its own.
- **Wake.** A plugin may also export `webhookHandler`; after a request is
  stored the host calls its `delivered(name, waiting)` on a running guest
  (`webhookDelivered` in TypeScript, `webhook_delivered` in Python) so it
  can pull at once. The host doesn't start a sleeping guest for it. A
  storage plugin's feed is read on the next destination sync pass, which
  a stored request brings forward.
- **Consent.** Declaring any row adds the `webhooks` token to the grant.
  The binding is handed only to a deployed instance whose grant has it,
  and only for the rows its manifest declares.

> [!NOTE]
> The route takes requests on a node that runs the instance. In a library
> with several nodes, point `integrations.public_origin` at one that runs
> the plugin; elsewhere the route answers 503 and the sender retries.

## Network grant (`env.NETWORK`)

Every `open` carries `Bindings.network`, the network grant in effect, so a
plugin can tell an unapproved destination from an unreachable one and
say so. It is feedback only: the host enforces the grant whatever the
plugin does with it.

| Field | Meaning |
| --- | --- |
| `outbound` | False when the network is denied |
| `domains` | Fetch entries in effect (`host`, `*.host`, `host:port`, `*`), including approved setting destinations |
| `tcp` | Raw TCP destinations as `host:port`, one per port |
| `settings` | One row per [network setting](/docs/plugins/capabilities/index.md#network-settings): `key`, `network` (`fetch` or `tcp`), `destination`, `state` (`approved`, `pending`, `unset` or `invalid`) and `error` |

TypeScript and Python read it as `env.NETWORK`; Rust reads
`Bindings::network`. No declared binding may be named `NETWORK`.

A connection the grant does not cover fails with `network_not_granted`.
`details.destination` names the `host:port`, and `details.setting` names
the network setting whose destination awaits approval, when one does:

- a refused `fetch()` answers `403` with an `x-bookclerk-error:
  network_not_granted` header and a JSON body
  `{"error": {"code", "message", "details"}}`;
- a refused `connect()` or native socket fails with that code (the native
  socket proxy answers `403` with the same body);
- a refused pushed socket (`env.SOCKETS.connect`) rejects with the typed
  error.

Tell the operator to approve the destination on the plugin's consent
form; don't retry until the grant changes.

## Entrypoint methods

The methods each capability entrypoint answers, by capability.

### Common

| Method | Purpose |
| --- | --- |
| `describe` | Identity, version, capabilities, brand (`metadataJson`) |
| `shutdown` | Graceful teardown |
| `health` | Connectivity and config check |
| `diagnose` | Human-readable CLI probe lines |
| `cliDescribe` | Declared CLI command schema (`CliSchema`) |
| `cliInvoke` | Run a declared command (`CliInvokeParams` → `CliInvokeResult`) |
| `oidcClients` | Bookclerk-as-IdP relying-party templates (`OidcClientTemplate[]`; empty when unused) |

Role contexts carry the instance's effective settings (schema defaults
under the document) as JSON: the same object the guest sees as
`env.CONFIG`.

The optional `metadataJson` field `cli` may embed the same schema as
`cliDescribe`. Prefer advertising capability `cli` and implementing both
methods.

You may also mirror the schema in `plugin.toml` under `[cli]`, so
`bookclerk plugins <id> --help` works without spawning the plugin. At
invoke time, `describe` and `cliDescribe` remain authoritative.

### Plugin CLI

Host commands that apply to every plugin stay on Bookclerk verbs
(`plugins list|info|diagnose|approve|enable|disable`, `integrations …`,
`auth …`). Plugin-specific commands are declared and invoked as:

```sh
bookclerk plugins <plugin-id> <command> [args…]
```

An example schema (JSON, `metadataJson` `cli`, or `cliDescribe`):

```json
{
  "commands": [
    {
      "name": "ping",
      "about": "Probe echo plugin",
      "args": [
        {
          "name": "message",
          "long": "message",
          "kind": "string",
          "required": false,
          "default": "hi"
        }
      ]
    }
  ]
}
```

`cliInvoke` params: `{ "command": "ping", "args": { "message": "hi" } }`.
Result: `{ "exitCode": 0, "stdout": "…", "stderr": "…", "json": … }`.

### Integration and remote-library capabilities

The handler family is derived from the declared entrypoints and triggers.
There is no `kind = "integration"`.

- Remote-library guests export `remoteLibrary` (and often `oidc` and
  `cli`).
- Event-driven guests declare `[[events.consumers]]`, and implement
  `event(batch)` on the default `BookclerkEntrypoint`.

| Surface | Notes |
| --- | --- |
| `event(batch)` | A typed `DomainEvent` batch (see below) |
| `remoteLibrary.health` / `diagnose` | Liveness and human-readable probe lines |
| `remoteLibrary.start` / `stop` | Background watchers |
| `remoteLibrary.scanLibrary` | `{ force: bool }` |
| `remoteLibrary.syncListening` | Listening progress snapshots; the host upserts them tagged with the plugin id |
| `remoteLibrary.pollEvents` | Observed external users. The host polls after `start`, and kicks off **core** workflows (such as claim tickets). The plugin stays unaware of the portal and tickets |
| `oidc.authenticateUser` | `{ username, password }` → external user (when `oidc` is exported) |
| `cli` | Declared under `[cli]` / `entrypoints = ["cli"]` |

`event(batch)` receives a typed
[`DomainEvent`](https://github.com/Bookclerk/bookclerk/blob/main/packages/plugin-sdk/src/plugin.ts) batch: `eventId`,
`eventType`, `schemaVersion`, correlation and causation, `source`,
`deduplicationKey`, `deliveryAttempt`, and a bounded payload.

- Each `EventMessage` records `ack`, `retry`, `reject`, `deadLetter` or
  `suspend`.
- A `suspend` parks a checkpoint. The next delivery copies
  `checkpointJson`, `checkpointSchemaVersion`, `invocationSequence` and
  `resumePending`.
- `wakeOnEventType` and `wakeOnFilterJson` ask the host to wake on a
  matching later event (empty means timestamp-only).
- Host delivery is at-least-once, so guests must be idempotent on
  `deduplicationKey`.

### Event consumers

Declare durable consumers in `plugin.toml`. Leave them out to receive
**no** outbox deliveries (fail closed):

```toml
[[events.consumers]]
type = "book_acquired"
schema_versions = [1]
supports_suspend = false
# resource_class = "network"   # default; the only accepted value today
# filter = { accountId = "acct" }
# max_retries = 5
# message_retention_period = 86400   # seconds; 60..=1209600, default 1 day
```

- Any `[[events.consumers]]` row needs an `event(batch)` handler on the
  default export.
- The optional `resource_class` (default `"network"`, currently the only
  accepted value) is copied onto `event_deliveries`. A typo or `cpu` is
  rejected when the manifest is checked, and skipped (fail closed) at
  dispatch.
- The optional `filter` is a host-owned JSON object. The dispatcher
  matches **payload object key equality** only (no plugin-provided code
  or CEL).
- The optional `message_retention_period` is how long, in seconds, a
  delivery may wait without being handed to the plugin before the host
  expires it (see [Retention](#retention-of-undelivered-events)).
- Echo and Audiobookshelf may leave both out (defaults).

### How events are delivered

**The subscriber catalog.**

- Each host heartbeats into `event_subscriber_nodes` the plugin instances
  its deployments run (`present` or `placed` on that node) and the
  integrations currently loaded. An instance's row is keyed by
  `(node_id, plugin instance id)`, so two instances of one plugin each get
  their own copy of an event. A plugin without an instance is keyed by its
  canonical PluginKey, not the display alias.
- The deployment decides whether an instance subscribes, not its process.
  An instance that is deployed but not running (still starting, or failing
  to spawn) keeps its enabled row, so matching events get a delivery for it
  at publish time; the delivery waits as `pending` until the instance runs.
  Subscriptions are the consented `[[events.consumers]]` and
  `[[queues.consumers]]` rows of what the deployment would run: the active
  installed version and its grant, or the discovered manifest for a
  plugin with no library install.
- The catalog key is the node id from `node-identity.json`. Nodes don't
  delete catalog rows they lack.

#### Retention of undelivered events

A delivery does not wait forever. Like a Cloudflare Queues message, it has
a retention period, so an instance that is deployed but not running stops
piling up work.

- The period is the consumer's `message_retention_period` (60 seconds to
  14 days), or one day when the consumer names none. It never exceeds
  `[events].retention_days`.
- A delivery expires when it has been due for longer than that period and
  was never handed to the plugin. Its state becomes `expired`, not
  `dead_letter`. A delivery that was leased, retried, suspended or is
  resuming does not expire; `max_retries` and dead letters govern it.
- Expiry is best effort. The hourly `maintenance.events` duty expires
  deliveries, scanning about 10 000 rows a run and resuming where it
  stopped, so a delivery can outlive its period by an hour or more and can
  still be leased until the sweep reaches it. Retention bounds a backlog;
  it is not a delivery deadline, and the lease path does not check it.
- A subscriber with no live catalog row (for example, while every node
  that runs it is down) waits the full `[events].retention_days`, since
  its declared period cannot be read.
- Expired rows stay until `[events].retention_days` passes, as the record
  of which events an instance missed. A plugin catches up after a gap with
  [`env.EVENTS.read`](#reading-past-events-enveventsread), which names
  those events in `expiredEventIds`.
- Deliveries for the host's own consumers (`host:` and node queues) never
  expire.
- A plugin is live when any heartbeating node (60 s TTL) has it enabled.
  Matching subscriptions are the union of those enabled rows.

**Dispatch.**

- The dispatcher `INSERT OR IGNORE`s deliveries for pending events, one D1
  atomic operation per `(event_id, plugin_id)`, with receipt
  `dispatch-{event_id}-{plugin_id}`.
- It **also** late-joins already-`dispatched` events through a
  missing-pair anti-join (receipt `reconcile-{event_id}-{plugin_id}`). An
  unchanged live catalog with no missing pairs does a bounded empty
  `SELECT` and zero dispatch writes.
- This node's catalog heartbeat runs **before** that reconcile, so a
  catch-up page can't starve the 60 s TTL.
- Each tick dispatches at most 32 pending outbox rows.
- A dispatch error clears the empty-reconcile skip cache. A bounded
  reconcile still runs at least every 60 s as a backstop.

**Suspend and wake.**

- After its dispatch step, each tick always runs a claimed wake slice (a
  UUID fence token, not the node id), even when undispatched rows remain.
- Accepting a wake clears `wake_event_type`, `wake_filter_json` and
  `wake_grants_json`, so a retry isn't woken again.
- A `suspended` result is accepted only when a subscription matches that
  exact `(type, schema_version)` and sets `supports_suspend = true`.
  Otherwise it is stored as a permanent reject.
- A non-empty `wakeOnEventType` must also match a declared subscription
  type.
- The host derives wake grants from those subscriptions: `schemaVersions`,
  plus the intersection of `sub.filter` and `wakeOnFilterJson`. An empty
  requested filter keeps the subscription filter, and can't broaden it.
  Waiting on an event doesn't grant a new binding.
- Publish commits `wake_pending` and returns. The dispatcher claims
  bounded wake slices, so producer latency doesn't track the number of
  sleepers.
- The wake page size follows the negotiated `maxBinds` (100 on D1), so
  `IN (…)` and the fenced sleeper UPDATE stay under the bind cap. The
  UPDATE includes `EXISTS (wake_pending ∧ lease owner)`.

**`book_acquired`.** A successful acquire writes `book_acquired` into
`domain_events` in the same transaction as the edition's acquire state
(the account holding as `titleId`, the edition, storage key, product ids;
never media bytes). The holding is also the event's correlation and
ordering key. It sets the envelope `source` to the book's storefront
plugin id.

**`edition_acquire_changed`.** Any other acquire state change of a title
(queued, downloading, failed, or reset to not acquired) writes
`edition_acquire_changed` (`editionId`, `titleId`, the account holding,
and `status`, one of `not_acquired`, `queued`, `downloading` or `error`)
in the same transaction. Its `source` is the book's storefront plugin id
too.

A write is recorded only while its holding still holds the edition: one
read before a revoke or rescan removed the holding changes nothing and
publishes no event.

**`ingest_batch_finished`.** When an [upload](/docs/server/uploads/index.md) or a
storage intake batch reaches a final state, the host writes
`ingest_batch_finished` (`batchId`; `state`, one of `done`, `failed` or
`cancelled`; `source`, `upload` or `intake`; `intakeInstance`, the storage
instance an intake batch read, else `null`; `detail`, why it failed, else
`null`) in the same transaction. Its `source` is `core.import`. Each file's
outcome stays with the batch: read `GET /api/uploads/{id}`.

**Library model events.** Recording a store listing publishes, in the same
batch as its rows:

- `edition_linked` (`editionId`, `listingId`) when a listing is first
  stored or now sells another edition (an Administrator's pin publishes it
  too, with `edition_updated` for the edition the listing left; each pin
  publishes again, even back to an edition the listing sold before);
- `edition_updated` (`editionId`) when the listing filled a missing
  subtitle, publication date or duration on its edition;
- `edition_updated` (`editionId`, `fields: ["chapters"]`) when the
  chapters an edition plays change: a new chapter claim from an acquire,
  or an Administrator's edit or pin (see
  [Chapters](/docs/server/playback/index.md#chapters));
- `holding_added` (`listingId`, `holder`, `holdingId`) when an account or
  branch library holds the listing (a title a branch shares, with holder
  `node:<node id>`), or holds it again after it was removed;
  `account_id` is the account for an account holder and empty for a
  branch.

The host publishes `holding_removed` (`listingId`, `holder`, `holdingId`)
in the batch that deletes a holding: a scan no longer lists the title (see
[Paged scans](#paged-scans)), the account is revoked, its id is remapped
(the holding moves, with `holding_removed` for the old account and
`holding_added` for the new one), or a branch no longer shares the title
(its full catalog pass no longer names it, it stopped sharing, or it
left).

Their `source` is the plugin key of the listing's store.
Each daemon's search index consumes them, with `book_acquired`, to keep its
node-local index current (see
[Search index](/docs/internals/jobs/index.md#search-index)).

**Taste events.** The library publishes these after the write they
describe, best effort (a failed publish is logged, and the write stands):

- `wishlist_changed` (`requestId`, `identityId`, `status`) when a wishlist
  entry is added or changes status (`open` or `cancelled`), or an open entry
  is removed with its user (`deleted`); `identityId` is the portal identity
  that wished, or null;
- `listening_synced` (`provider`, `identityIds`) when a listening sync
  changed a stored row's owner, matched book or work, authors, start,
  quarter or finish; its
  `source` is the integration that synced, and `identityIds` names the
  portal identities whose rows changed. A sync that changes none of these
  publishes nothing;
- `playback_started`, `playback_progress` and `playback_finished`
  (`userId`, `editionId`, `workId`, `sessionId`, `positionMs`,
  `durationMs`) from the built-in player: when someone opens a play
  session, when a session closes or progress is set outright (then with a
  null `sessionId`), and when a listener reaches the end of an edition.
  `workId` and `durationMs` can be null. The position reports of a playing
  session publish nothing.

Discover's host consumer reads them to refresh shelves (see
[Discovery design](/docs/internals/discovery/index.md#taste-events)).

**Leasing.**

An event is a fact that fans out: every subscribed instance gets its own
delivery, and subscribers never compete for one. A delivery is *leased*,
which only picks the node that runs that subscriber's copy. A job is a
command with one handler, and is *claimed* (see
[Durable job queue](/docs/internals/jobs/index.md)).

- The producer's `ordering_key` is stored on the envelope, and copied
  verbatim onto each delivery.
- Each VPS leases only deliveries for instances loaded on that process,
  **and** only events its node-local catalog matches (type, schema
  version, filter).
- The host evaluates catalog JSON filters, then compare-and-sets a
  concrete delivery id inside a generic atomic plan.
- `[events.concurrency]` (default 1) is the number of local delivery
  workers **and** the library-wide maximum of `running` deliveries per
  `(plugin_id, resource_class)` (`network` today). It is enforced at
  lease time with a portable `bookclerk_slots` row, so two VPSes can't
  over-admit under `READ COMMITTED`.
- FIFO per ordering key stays. Unrelated keys are only blocked by that
  cap.

**Running.**

- The delivery worker heartbeats the lease during `event(batch)`
  (`lease/3`).
- A fence loss or an operator `cancel_requested` cancels the in-flight RPC
  (including workerd and native).
- An expired-lease reclaim restores `resume_pending` when
  `checkpoint_json` is set.

See [Jobs](/docs/internals/jobs/index.md).

### Storefront capabilities

Export `storefront` (there is no `kind = "source"`). The typed Cap'n
methods on [`ContentSource`](https://github.com/Bookclerk/bookclerk/blob/main/packages/plugin-sdk/src/plugin.ts) and
`StorefrontEntrypoint` are:

| Method | Notes |
| --- | --- |
| `login` | Password storefronts. Params include `pluginDataDir`, marketplace, label, email and password. Result: `{ account, credentials? }`. The host seals the credentials (`provider = plugin id`) and upserts the account row |
| `loginStart` / `loginComplete` | OAuth storefronts (Audible). Start returns `{ sessionId, url }`; complete returns the login result |
| `scan` | Returns one page of one account's library (see [Paged scans](#paged-scans)). Params carry `pluginDataDir`, `accountId`, filters, that account's host-injected `credential` (`{ accountId, credentials }`, the credentials as opaque JSON bytes; **no** library database path), `cursor` and `syncToken`. The reply is a `ScanPage` of `books[]` records (see [Book records](#book-records)); the host stores them with `source` forced to the plugin id |
| `searchCatalog` | `{ query, region, limit, page, sort, field }` → `CatalogHit[]` (see [Book records](#book-records)). A `limit` of `0` means the storefront's default page of 20 hits; an empty query returns `[]` |
| `catalogDetail` | `{ productId, isbn? }` → `{ found, hit }`: the full record for one product (description, narrators, runtime, genres). The host calls it only on a store that declares `detailByProductId` (for its own product ids) or `detailByIsbn` (which also answers a bare ISBN, sent in both fields) |
| `fetchTitle` | The host injects `credentials` from `encrypted_secrets`. The plugin writes media under the work folder and returns a `PlainFetch` of **plain** files (DRM guests decrypt before returning): `mediaKind`, the carrier it fetched, which must be in its declared [`fetches`](#declaring-media); `files`, each `{ path, role, contentType?, title?, durationMs? }` with `role` `part` (ordered pieces), `whole` (the edition in one file, such as an M4B) or `cover`; `chapters`; `chapterKind`, what those markers are (`chapters` for the book's own chapters, `tracks` for track or file markers, `unknown` when the store does not say), which decides how the host ranks them against other chapter sources; and an optional `pdfUrl`. A reply lists `part`s or one `whole` file, never both, and at most one `cover`. The host acquires audio editions only today. When the store throttles the account, fail with `rate_limited` (and `details.retryAfterMs` when the store said how long): the host pauses automatic downloads on that account (see [`[acquire]`](/docs/plugins/manifest/index.md#acquire-download-pace)). A native Rust storefront whose store reports throttling only in words can test the refusal text with `bookclerk_storefront::is_throttle_reason` |
| `purchaseHint` | Purchase link and, when `withPrice` is set, the live price of one title. `null` when the store does not sell it. `lookup` says how the host names the title (see [Price lookups](#price-lookups)) |
| `purchaseHints` | The same for several titles in one call (`{ queries }`, one answer per query in order). The default in every SDK asks `purchaseHint` for each query, four at a time, those with a product id first, and stops starting lookups after 4 s, answering `null` for the rest, so the host's batch gets what the store managed; a store whose catalog prices many products per request (Audible's `products?asins=` takes fifty, Chirp's GraphQL takes aliased ids) overrides it to make one request, so a page of Discover cards costs one call per store |
| `qualityOffers` | `{ accountId, credentials?, sourceConfig, titleIds, fetch }` → `{ offers, refreshedCredentials? }`: which stream the account would download for each title today, without downloading (see [Quality offers](#quality-offers)). The host calls it only on a store that declares `catalog.qualityOffers` |

#### Price lookups

Each `purchaseHint` query carries `lookup`, which says how to find the
title:

| `lookup` | The store should |
| --- | --- |
| `product` | Answer for its own `productId` alone |
| `isbn` | Answer for that exact `isbn`, or `null`. Never a title match. Sent only to a store that declares `catalog.priceByIsbn` |
| `asin` | Answer for that exact `asin`, or `null`, as for `isbn`. Sent only to a store that declares `catalog.priceByAsin` |
| `title` | Search by `title` and `authors` and return every priced listing the search matched |
| `unspecified` | Use any field, strongest first (older hosts) |

A title search answers with records rather than a single pick: return
`{ hint, records }` (TypeScript `PurchaseHintAnswer`; a dict of the same
shape in Python; `PurchaseHintResult.records` in Rust) where each record
is `{ record, hint }`, the listing's full `CatalogHit` and its prices.
`hint` stays the store's own pick for hosts that ignore records. The host
places each record in its library model by identifiers, credits and kinds,
and keeps only the recording the card is about, so a store never has to
tell a narration from a dramatisation of the same title. A bare hint is
still accepted and carries no records.

In Rust, a storefront returns records by overriding `purchase_hint_result`
and `purchase_hints_results`. A store without a bulk price endpoint calls
`purchase_hint_results_one_by_one` from `purchase_hints_results` to get the
same four-at-a-time, 4 s default as `purchaseHints`. The default
`purchase_hint_result` wraps `purchase_hint` and returns no records.

The host asks each store the strongest way it declared: by the store's
own product when the card names one, then by exact ISBN, then by exact
ASIN, then by title (see
[Discovery](/docs/internals/discovery/index.md#store-links-and-pricing) for how
it evaluates the answers).

When the store answers **429**, return a `PluginError` with code
`rate_limited` and, when the store sent `Retry-After`, `details.retryAfterMs`
(`PluginError::rate_limited(message, retry_after)` in Rust; the TS and Python
SDKs take the same shape). The host then leaves that store's price lookups
alone for the time it said, else for a minute that doubles on each repeat
up to fifteen minutes, and shows the cards without a price meanwhile. Any
other failure of a price lookup is soft: the card simply has no price.

> [!IMPORTANT]
> Plugins must not open `library.db` or read `master.key`. Don't put
> encrypted content keys on the wire: decrypt in the guest when needed.

#### Paged scans

The host scans one account at a time and asks for its library a page at a
time, so a large library never has to fit in one reply and a stopped scan
picks up where it left off.

1. The first call has an empty `cursor`. Each later call passes back the
   `nextCursor` of the page before. A page with an empty `nextCursor` is the
   last one.
2. An empty `syncToken` asks for a **full pass**: every title the account
   holds. A non-empty one is a token the plugin returned at the end of an
   earlier pass, and asks only for what changed since then (a **delta
   pass**).
3. On the last page, set `syncToken` to the token for the next pass (empty
   when the store has no change feed) and `complete` to true when the pass
   listed every title the account holds. A delta pass is not complete.
4. List titles the store reports gone in a delta pass as product ids in
   `removed`. `storePages` counts the store requests behind the page, for
   progress and diagnostics.

A page holds at most `MAX_SCAN_PAGE_BOOKS` (500) books and as many removed
ids; `cursor` and `syncToken` are at most `MAX_SCAN_CURSOR_BYTES` (4096)
bytes. Both are opaque to the host and never shown to anyone. The host
refuses a page that breaks a limit, returns a cursor it already returned
in the same pass, carries a book for another account or a blank product id,
and fails the scan.

The host keeps where each account stands in the `account_scan_state`
table:

- It saves `nextCursor` after writing each page. A scan that stops resumes
  from that cursor, with the token the pass started with, if the cursor is
  less than 24 hours old.
- It stores the last page's `syncToken` and sends it on the next pass, but
  asks for a full pass again when no complete pass has finished in seven
  days.
- A plugin that no longer accepts a cursor or token rejects the call with
  `invalid_cursor`. The host forgets both and restarts once as a full pass.
  If the first page of a resumed pass fails for another reason, the host
  forgets the cursor and restarts that pass once from the beginning. If the
  first page of a delta pass fails for another reason, the host restarts
  once as a full pass and keeps the stored token until that pass replaces
  it.
- A pass stops with an error after 10,000 pages.

A store with no change feed returns full passes with an empty `syncToken`;
a page number makes a fine cursor. A plugin that needs more state than one
token can keep it in its own [KV namespace](#kv-namespaces) or, for one
row per title, its own database (`[[databases]]`, sized with the helpers in
[Database limits](/docs/plugins/database-limits/index.md)). The first-party Libro.fm, Chirp and
GraphicAudio plugins do the latter through the `bookclerk-scan-delta`
crate: they keep a fingerprint of each title the last pass listed in a
`SCAN_STATE` database, and a delta pass sends only new or changed titles
plus the product ids that disappeared. Without the database they return
full passes.

The host keeps the account's holdings in step with the pass:

- It removes the account's holding of each `removed` product id.
- Each page marks the account's holdings of the products it listed with
  the pass's id, kept with the cursor so a resumed pass marks the same id.
- When a full pass (no page was sent a token) ends `complete`, the host
  removes the account's holdings that no page of the pass listed.

Each removal publishes `holding_removed`. So a plugin must set `complete`
only when the pass really listed every title: a complete full pass that
lists none removes every holding of the account. The flat library rows
and acquired files stay.

Each SDK has a helper that does the paging for you: `scanPage` in
TypeScript, `scan_page` in Python and in the Rust SDK. You give it a
function that fetches one page of the store's own listing, by the store's
own cursor, and it returns the reply for the call:

```ts
import { scanPage, type ScanPage, type ScanParams } from "@bookclerk/plugin-sdk/workerd";

scan(params: ScanParams): Promise<ScanPage> {
  return scanPage(params, async (storeCursor) => {
    const page = Number(storeCursor || "1");
    const listing = await this.library(params.accountId, page);
    return {
      books: listing.items.map(toScanBook),
      next: listing.hasMore ? String(page + 1) : "",
      complete: true,
    };
  });
}
```

1. The function gets an empty store cursor for the first store page, then
   each `next` it returned. An empty `next` marks the last store page.
2. A store page may hold any number of titles and removed ids. The helper
   returns them 500 at a time, fetching that store page again for each
   slice, so the plugin keeps no state between calls.
3. Set `syncToken` and `complete` on the last store page. The helper sends
   them only with the pass's last reply.
4. The helper rejects a cursor it did not write, or a slice past the end
   of a store page that shrank mid-pass, with `invalid_cursor`, so the host
   restarts the pass. A store cursor longer than about 4 KB fails with
   `internal`.

The three SDKs write the same cursors, so a plugin can move between them
without breaking a pass in progress.

#### Quality offers

The daily [upgrade check](/docs/server/output/index.md#upgrading-to-better-files)
asks a store which file an account would download for titles it already
holds. A storefront takes part by setting `catalog.qualityOffers` in
`describe()` and answering `qualityOffers`:

1. The host sends up to `maxListPage` of the account's product ids in
   `titleIds`, with its credentials, the instance's `sourceConfig` and the
   `fetch` options an acquire would use (DRM path, quality, xHE-AAC).
2. Answer one `TitleQualityOffer` per id, in the same order. Set `found`
   and fill `offer` with the stream's `codec`, `aacProfile` (AAC only;
   `unknown` otherwise), and, when known, `bitrateKbps`, `sampleRateHz`
   and `channels`. Leave `found` false for a title you can't answer, and
   offer only streams a `fetchTitle` with the same options would deliver.
3. When the store throttles the account, fail with `rate_limited`; the
   host leaves the account alone until the next day.

The host checks the reply before comparing anything: no more answers than
titles sent, a channel count up to 32, a sample rate up to 768 kHz, a
bitrate up to 800,000 kbps, and an AAC profile only on AAC. A reply that
breaks one is refused whole. `refreshedCredentials` follows
[Refreshed credentials](#refreshed-credentials). The default in every SDK
fails with `unsupported`; Audible is the first-party store that answers it.

#### Refreshed credentials

A store may renew an account's tokens while the plugin uses them, such as
an access token that expired in the middle of a scan. The plugin hands the
renewed credentials back so the next call does not have to renew them
again:

1. Set `refreshedCredentials` on the `ScanPage`, `PlainFetch` or
   `QualityOffersResult` reply to
   the account's whole credentials, in the same JSON form the host sent
   them. Leave it empty when nothing changed.
2. The value must be one JSON object of at most
   `MAX_REFRESHED_CREDENTIAL_BYTES` (64 KiB). The host refuses a scan page
   that breaks either rule and fails the scan.
3. The host keeps the renewed credentials before it writes the page's
   titles, and sends them on the pass's later pages. A `PlainFetch` reply
   that breaks the rules keeps its title; the credentials are logged and
   dropped.

The host stores them only while the account still has the credentials it
sent the plugin. If someone signed the account in again in the meantime,
that sign-in wins and the renewed credentials are dropped. On a member's
computer that runs a job for a library it joined, the renewed credentials
go back to that library under the job's lease instead, and are never
stored on the member's computer.

The host registers the renewed values for log redaction as it receives
them. A plugin should still never log them.

#### Catalog search capabilities

Discover's catalog search merges every storefront's `searchCatalog` hits
into one list. It never names a store; a storefront takes part in ranking
and enrichment by declaring it:

- **Rank hints.** Set `rankHint` on each `searchCatalog` hit to the
  store's own 1-based rank for the requested sort, counted across pages
  (page 2 of 20-hit pages starts at 21), or to a store-wide popularity rank
  when the store has one. The relevance and popularity sorts order the
  merged list by the best rank any store gave a work, then put unranked
  works after ranked ones. Leave it `0` when the store's order means
  nothing. The Rust storefront crate's `CatalogSearchOpts::stamp_rank_hints`
  fills it from the page and limit.
- **ISBN detail lookup.** Set `catalog.detailByIsbn` in `describe()` when
  `catalogDetail` resolves any audiobook ISBN to a full record. After
  ranking a page, the host asks those stores, in `sortKey` order, to fill
  description, narrators, runtime and genres on lean rows from any store.
  A row is looked up by its ISBN, or, when the store also declares
  `detailByProductId` and listed the work itself, by its own product id.
  The first record found fills the gaps and
  adds that store's edition. The lookups share a short time budget, so a
  slow store can't hold up a search.
- **Product detail lookup.** Set `catalog.detailByProductId` in
  `describe()` when `catalogDetail` resolves the product ids your own
  search, expand and deals hits carry to a full record. The host then asks
  your store to fill the lean rows it listed (as above, but by your product
  id only), and a title dialog asks it for the editions it listed before
  any ISBN store. A store that leaves it off is never woken for a detail
  lookup.

- **Price lookup by identifier.** Set `catalog.priceByIsbn` and
  `catalog.priceByAsin` in `describe()` when `purchaseHint` prices an exact
  ISBN or ASIN (see [Price lookups](#price-lookups)). The host never sends
  an identifier lookup a store has not declared.

All default to off. The first-party storefronts declare them as follows:
Audible ranks its hits and prices exact ASINs, Libro.fm answers ISBN and
product detail lookups and prices exact ISBNs, GraphicAudio answers product
detail lookups, and Chirp declares none. All four answer title searches
with records.

#### Declaring media

Storefronts and metadata providers must declare the media they work with,
in `plugin.toml` and in `describe()`. There is no default:

```toml
[media]
works = ["book", "podcast"]   # work kinds the plugin reports
lists = ["audio"]             # carriers it reports in scans, search and records
fetches = ["audio"]           # carriers fetchTitle can deliver (storefronts only)
```

`describe()` returns the same lists as `media: { workKinds, lists,
fetches }`. The host refuses to spawn a storefront or metadata provider
whose `works` or `lists` is empty or names `unspecified`, whose `fetches`
names a carrier `lists` does not, or whose `describe()` disagrees with
`plugin.toml`. Every other plugin leaves `[media]` out. Because the
declaration is in the manifest, the host can tell what a sleeping plugin
sells without starting it.

The SDKs fill `media` from the manifest. A TypeScript or Python plugin gets
it with the rest of the manifest projection, and a Rust plugin sets
`media: manifest_media(include_str!("../plugin.toml"))?` beside
`manifest_capabilities`.

The host then checks each record against it: a scan page with a record
whose kinds are unspecified or outside the declaration is refused whole,
and such catalog hits and metadata records are dropped. The first-party
plugins declare:

| Plugin | `works` | `lists` | `fetches` |
| --- | --- | --- | --- |
| Audible | `book`, `podcast` | `audio` | `audio` |
| Libro.fm, Chirp, GraphicAudio | `book` | `audio` | `audio` |
| OpenLibrary (metadata) | `book` | `print` | none |
| Audnexus (metadata) | `book` | `audio` | none |

#### Book records

`scan` returns `ScanBook` records, and the catalog methods (`searchCatalog`,
`catalogDetail`, `expandCandidates`, `listDeals`) return `CatalogHit`
records. Both describe a title in structured fields, following the
[library data model](/docs/adr/library-data-model/index.md):

| Field | Meaning |
| --- | --- |
| `workKind` | `book` or `podcast`. A podcast record that sets `parentProductId` is an episode of that show; one without it is the show |
| `expressionKind` | `text`, `narration`, `dramatisation`, `graphic` (comics, graphic novels) or `originalAudio` (podcast episodes, lectures and other audio that reads no text). A full-cast production is a `dramatisation`. A translation is not a kind: set `language` and credit the translator |
| `mediaKind` | `audio`, `ebook` (any downloadable document: EPUB, PDF, CBZ) or `print`. Whether the host acquires an edition depends on the storefront's [`fetches`](#declaring-media) and on what the host supports, not on this field alone |
| `identifiers` | `{ scheme, value, marketplace? }` entries. `scheme` is `isbn` (ISBN-10 or ISBN-13), `asin` (set `marketplace`), `openLibraryEdition` or `openLibraryWork`. The host trims each value, upper-cases ASINs, and turns a valid ISBN-10 into its ISBN-13 |
| `credits` | `{ name, role, level }` entries in billing order, one person or body per entry. `role` is `author` (the default), `narrator`, `translator`, `editor`, `illustrator`, `publisher`, `host`, `cast` or `adaptor`. Set `level` to `roleDefault` unless the credit sits somewhere unusual: by default authors and adaptors credit the work, narrators, translators, hosts and cast the expression, and editors, illustrators and publishers the edition |
| `seriesEntries` | `{ name, position?, storeSeriesId? }` entries, one per series the work belongs to. `position` is the label as the store prints it (`1`, `2.5`, `1-3`). The host removes a trailing edition marker and the word "Series" from `name` (`King and Maxwell (abridged)` and `King & Maxwell Series` are stored as `King and Maxwell` and `King & Maxwell`), and matches series with `&` read as `and`, so send the name as the store prints it |
| `parentProductId` | The show's product id, on a podcast episode. Only podcasts keep it |
| `language`, `abridgement` | Content language, and `unknown` (the default), `unabridged` or `abridged` |
| `explicitness` | Whether the store marks the edition as explicit (adult) content: `unknown` (the default), `clean` or `explicit`. The host keeps it on the store listing, so a patron scope can hide explicit books |

Every record names all three kinds. Each kind enum starts with
`unspecified`, which is what a record that forgets the field sends, and
the host refuses such a record rather than guessing. An audiobook is
`book` + `narration` + `audio`, a podcast episode `podcast` +
`originalAudio` + `audio`, and a digital comic `book` + `graphic` +
`ebook`.

`ScanBook` also carries `publishedAt` and `purchasedAt` (RFC 3339) and
`categories`.

Fill these from the store's own data. When a store returns a list of
names, send one credit per name; split a display string such as
`"Jane Doe, John Roe"` only when that is all the store gives.

> [!NOTE]
> The host resolves each record into a listing of its work, expression and
> edition. A record that is not a valid listing is stored from its flat
> fields instead: names join by role, the first ISBN and ASIN fill the
> identifiers, and the first series entry fills the series. An episode
> with no `storeSeriesId` is filed under the show named by
> `parentProductId`. Ebook and print scan records are not stored yet, and
> records with an unspecified kind are never stored.

### Metadata providers

Export `metadata` to answer bibliographic lookups from a public catalog
(OpenLibrary, Audnexus and similar). A metadata provider only describes
what the catalog says; the host decides which library title a record
belongs to, and never lets a record name an existing row.

The typed methods on `MetadataProvider` and `MetadataEntrypoint` are:

| Method | Notes |
| --- | --- |
| `health` | Liveness and readiness |
| `lookup` | `{ identifiers, marketplace?, limit? }` → `MetadataRecord[]`. Look up the editions the identifiers name. Ignore schemes you don't serve, and return `[]` when nothing matches |
| `search` | `{ title, author?, language?, marketplace?, limit? }` → `MetadataRecord[]`, most relevant first |
| `chapters` | `{ identifiers, marketplace? }` → `MetadataChapters`: `found`, chapters in pre-order with `startMs`, `lengthMs?` and `depth` (0 for top level), `brandIntroMs?`, `brandOutroMs?`, `runtimeMs?`, and `accurate` when the offsets are exact |

A `MetadataRecord` carries the same [book record](#book-records) fields as
a `CatalogHit` (kinds, identifiers, credits, series, language,
abridgement; not `explicitness`, which comes from stores and files), plus `description`, `coverUrl`, `url`, `publisher`,
`lengthMinutes`, `publishedAt`, `categories` and an optional rating. It has
no store product id or price, because nothing is sold.

A provider that serves only some methods leaves the others to the base
class, which answers typed `unsupported`. Declare the catalog hosts you
call under `[capabilities.network]`. The guest has no other network
access, and the host never fetches on its behalf.

```ts
export class Metadata extends MetadataEntrypoint<Env> {
  async lookup(params: MetadataLookupParams): Promise<MetadataRecord[]> {
    const isbn = params.identifiers.find((id) => id.scheme === "isbn");
    // Identifier values come from library data: check them before they
    // reach a URL.
    if (!isbn || !/^[0-9X-]{10,17}$/i.test(isbn.value)) return [];
    const res = await fetch(`https://openlibrary.org/isbn/${encodeURIComponent(isbn.value)}.json`);
    if (!res.ok) return [];
    const edition = (await res.json()) as { title: string };
    return [
      {
        title: edition.title,
        abridgement: "unknown",
        workKind: "book",
        expressionKind: "text",
        mediaKind: "print",
        identifiers: [isbn],
        credits: [],
        seriesEntries: [],
      },
    ];
  }
}
```

For a complete provider, see the first-party `openlibrary` and `audnexus`
plugins under `crates/bookclerk-plugins/optional/` (`metadata-openlibrary`
and `metadata-audnexus`).

The host asks every deployed provider in turn: for Audible ASIN matching
during scans, Discover title details, the acquire chapter overlay, and
`bookclerk discover enrich-metadata`. Lookups and searches collect records
from every provider; `chapters` stops at the first layout with `found`
set. A provider that fails is logged and skipped
([integrations](/docs/server/integrations/index.md#open-library-and-audnexus)).

### Cover fetchers

Export `covers` to download cover images for the host. The host never
fetches a cover URL itself: it hands the URLs to a cover fetcher, then
checks each body's real type, decodes it with limits and re-encodes it
before it stores or serves anything.

The typed methods on `CoverFetcher` and `CoverEntrypoint` are:

| Method | Notes |
| --- | --- |
| `health` | Liveness and readiness |
| `fetchCovers` | `({ urls, maxBytes, conditions }, sink)` → `CoverImage[]`. Fetch each URL and put its body into `sink` under the key `String(i)`, where `i` is the URL's index. Answer one `CoverImage` per URL, in request order: `{ url, stored, notModified, contentType?, error?, etag?, lastModified?, cacheControl?, expires?, date?, age? }` |

- `urls` holds 1 to `MAX_COVER_URLS` (32) absolute `https` URLs, and
  `maxBytes` is at most `MAX_COVER_BYTES` (10 MiB).
- `conditions` holds the validators the host already has, by index, and
  may be shorter than `urls`. Send `conditions[i].ifNoneMatch` as
  `If-None-Match` and `conditions[i].ifModifiedSince` as
  `If-Modified-Since` when they are set. Each value is at most
  `MAX_COVER_HEADER_BYTES` (1024) bytes.
- When the server answers `304 Not Modified`, put nothing into the sink
  and answer `stored: false, notModified: true`: the host's copy is still
  current.
- Copy the server's `ETag`, `Last-Modified`, `Cache-Control`, `Expires`,
  `Date` and `Age` into the answer verbatim, for a `200` or a `304`. Leave
  out a value longer than `MAX_COVER_HEADER_BYTES`; the host refuses an
  answer that carries one, or one that is both `stored` and
  `notModified`. The values are advisory: the host parses them again with
  its own limits.
- `sink` is a host-served `Destination` that accepts only `put`, only for
  the keys `0` to `urls.length - 1`, each once. A body over `maxBytes`
  fails that `put` with `payload_too_large`; every other method is
  `unsupported`.
- Answer a failed URL with `stored: false` and an `error` such as
  `HTTP 404`. Throw only when the whole request is malformed.
- The host checks the answer: one entry per URL, the URLs as asked, and a
  body for every `stored: true`. A `stored` answer with no body becomes an
  error.

Bodies go to the sink rather than into the reply, because a reply is
capped well below one image (see the
[workerd bridge](/docs/internals/workerd-bridge/index.md#post-invoke)).

```ts
export class Covers extends CoverEntrypoint<Env> {
  async fetchCovers(params: CoverFetchParams, sink: Destination): Promise<CoverImage[]> {
    const out: CoverImage[] = [];
    for (const [i, url] of params.urls.entries()) {
      const res = await fetch(url);
      if (!res.ok || res.body === null) {
        out.push({ url, stored: false, notModified: false, error: `HTTP ${res.status}` });
        continue;
      }
      await sink.put(String(i), res.body);
      out.push({ url, stored: true, notModified: false });
    }
    return out;
  }
}
```

The first-party `covers` plugin (`crates/bookclerk-plugins/optional/covers`)
is the complete fetcher. It holds the `*`
[any public website](/docs/plugins/capabilities/index.md#network-rules) grant, because cover
art lives on every catalog's own CDN.

### Metadata file dialects

Export `metadataFiles` to read, and optionally write, the metadata files
that sit next to a book's audio: a `metadata.json` from another library
manager, an OPF, an NFO, a `desc.txt`. Sidecar parsing lives in plugins,
never in the host: the host finds the files, hands the bytes to the
plugin that declared the dialect, and checks what comes back.

Each dialect is a row under [`[metadata_files]`](/docs/plugins/manifest/index.md#metadata_files-metadata-file-dialects)
in `plugin.toml`. The row names the files it claims, the fields the
format carries and whether the plugin also writes it.

The typed methods on `MetadataFiles` and `MetadataFilesEntrypoint` are:

| Method | Notes |
| --- | --- |
| `health` | Liveness and readiness |
| `parse` | `({ dialect, fileName, bytes })` → `MetadataFileRecord`. Read one file and say what it states about its edition |
| `render` | `({ dialect, record, fields, existing, audioFiles })` → the new file's bytes (`Uint8Array`, or a string written as UTF-8). Set each field in `fields` to the record's value and keep the rest of `existing` as it was |

A `MetadataFileRecord` lists in `present` every field the file states,
including a field it states as empty. A field the file does not mention
stays out of `present`: absent means unknown, not cleared. `creditRoles`
does the same for credits: it names each role the file states, so a file
that lists only narrators says nothing about authors. `explicitness`
(`unknown`, `clean` or `explicit`) says whether the file marks the edition
as explicit content, as Audiobookshelf's `metadata.json` does with
`explicit`.

The host checks both directions:

- `dialect` is one the plugin declared, `fileName` is a plain file name
  (no path) of at most 255 bytes, and `bytes` is at most
  `MAX_METADATA_FILE_BYTES` (256 KiB). A larger file is skipped rather
  than sent. The cap keeps the whole call inside one bridge request (see
  the [workerd bridge](/docs/internals/workerd-bridge/index.md#post-invoke)).
- A parsed record lists each field at most once, carries a value only for
  a field in `present`, and states only fields and credit roles the
  dialect declares. Labels are non-blank single lines of at most
  `MAX_METADATA_FILE_TEXT_BYTES` (1024) bytes; `description` is at most
  `MAX_METADATA_FILE_DESCRIPTION_BYTES` (64 KiB); each list holds at most
  `MAX_METADATA_FILE_LIST_ENTRIES` (256) entries and `chapters` at most
  `MAX_METADATA_FILE_CHAPTERS` (2000), in start order with no depth jump
  of more than one. `publishedAt` is `YYYY`, `YYYY-MM` or `YYYY-MM-DD`.
- `render` is sent only to a dialect with `writes = true`, only for fields
  the dialect carries, and the answer is at most
  `MAX_METADATA_FILE_BYTES`. `existing` is empty when the host creates the
  file. `audioFiles` lists the edition's audio files in playback order,
  each a plain file name with its running time in milliseconds (0 when
  unknown, never past 2^53 - 1), at most `MAX_METADATA_AUDIO_FILES`
  (4096) of them; it is empty when the host does not know them. Chapter
  starts in `record` count from the start of the first file, so a format
  that names its audio, such as a CUE sheet, can place each chapter in
  its file. An empty answer means the dialect has nothing left to write; the
  host decides whether to remove the file.
- Throw `invalid_params` from `parse` for a file the dialect cannot read.
  The host records the file as unreadable and moves on. Any reply that
  breaks a rule above is refused as `internal`.

```ts
export class MetadataFiles extends MetadataFilesEntrypoint<Env> {
  async parse(params: MetadataFileParseParams): Promise<MetadataFileRecord> {
    const text = new TextDecoder("utf-8", { fatal: true }).decode(params.bytes).trim();
    if (text === "") {
      return { present: ["description"] };
    }
    return { present: ["description"], description: text };
  }

  async render(params: MetadataFileRenderParams): Promise<string> {
    return params.record.description ?? "";
  }
}
```

The first-party `metadata_files` plugin
(`crates/bookclerk-plugins/optional/metadata-files`) reads and writes OPF
package documents, Kodi `album.nfo` files and CUE sheets, and reads Libation's catalog record without writing it. A format that belongs to one tool
lives in that tool's plugin. The plugin's README lists what each record
maps to.

The host does not call the entrypoint yet beyond health probes. Finding
the files, matching them to editions and writing changes back come with
the metadata file sync work.

### Notifiers

Export `notifier` to deliver notifications to one outside service: a
chat webhook, a mail relay, a paging service. The host decides what to
send and to whom (see the [notifications ADR](/docs/adr/notifications/index.md));
a notifier only sends one message, which the host has already rendered,
to one destination. `[notifier]` in
[`plugin.toml`](/docs/plugins/manifest/index.md#notifier-notifiers) declares the destination
kinds, formats and personal address fields.

The typed methods on `Notifier` and `NotifierEntrypoint` are:

| Method | Notes |
| --- | --- |
| `health` | Liveness and readiness: can the service be reached with the current settings |
| `send` | `({ message, destination })` → `{ providerId? }`. Deliver one message; `providerId` is the service's id for it, when it gives one |
| `validateDestination` | `({ addressJson })` → `{ addressJson, label? }`. Check and normalise a personal address a patron entered; `label` is a short hint that is never a secret (`a***@example.com`). The default accepts the address as given |

A `NotificationMessage` carries `notificationId` (the same on every
destination's copy; where the service takes an idempotency key, build it
from `notificationId` and the destination's `destinationId`, so two
addresses on one service account both receive it and a retry to the same
destination reuses the same key), `notificationType`, `severity`, `title`, a plain `text` body,
optional `markdown` and `html` bodies, an optional `link` into the
library, labelled `fields`, an optional `groupKey` for threading, and an
alert action and key for services that open and close incidents. When
`sensitive` is set the body carries a secret, such as an account-mail
link: never log it. The destination is `channel` (its target lives in
the instance's settings, and `addressJson` is empty) or `personal` (its
`addressJson` is a JSON object of the declared address fields, which may
hold secrets and is never logged).

How `send` fails decides what happens next:

- `rate_limited` is retried, after `details.retryAfterMs` when the
  service said how long (capped at one hour), otherwise on the job's
  backoff;
- `unavailable`, `deadline_exceeded` (the call ran out of time) and
  `cancelled` (the host stopped it, for example on shutdown) are retried on
  the job's backoff;
- any other error fails this destination for this message.

The host checks both directions:

- A message has a printable `notificationId` of at most 128 bytes, a
  type id, a non-blank one-line title of at most
  `MAX_NOTIFICATION_TITLE_BYTES` (256), `text` and `markdown` of at most
  `MAX_NOTIFICATION_TEXT_BYTES` (16 KiB), `html` of at most
  `MAX_NOTIFICATION_HTML_BYTES` (64 KiB), at most `MAX_NOTIFICATION_FIELDS`
  (25) fields with values of at most `MAX_NOTIFICATION_FIELD_BYTES` (1 KiB),
  and an alert key exactly when the alert action is not `none`. A link
  is `https`, or `http` only to a loopback host, with no credentials.
- An address document is one JSON object of at most 16 keys, each
  `[a-z][a-z0-9_]{0,63}` and given once, with one-line string values; the
  whole text is at most `MAX_NOTIFIER_ADDRESS_BYTES` (4 KiB). A
  `validateDestination` answer that breaks these rules, or an empty
  address, is refused as `internal`.
- A provider id that is empty, longer than 1 KiB or not one line is
  dropped; the message still counts as delivered. An error's text is cut
  to one line of 512 bytes for the delivery log.

```ts
export class Notifier extends NotifierEntrypoint<Env> {
  async send({ message }: NotifySendParams): Promise<NotifySent> {
    const res = await fetch(this.env.CONFIG.webhook_url, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ text: `${message.title}\n${message.text}` }),
    });
    if (res.status === 429) {
      const seconds = Number(res.headers.get("retry-after") ?? "0");
      throw new PluginError("rate_limited", "service is busy", {
        retryAfterMs: seconds * 1000,
      });
    }
    if (res.status >= 500) throw new PluginError("unavailable", `HTTP ${res.status}`);
    if (!res.ok) throw new PluginError("invalid_params", `HTTP ${res.status}`);
    return {};
  }
}
```

The host gives `send` 30 seconds and `validateDestination` 6 seconds;
a call that runs longer is dropped and answers `unavailable`, so a send
is retried.

The host calls `send` from one `notify_send` job per delivery and
records the answer in the delivery log; see
[Notifications](/docs/server/notifications/index.md) for retries and pausing.

### Raising notifications

A plugin that declares [`[[notifications.types]]`](/docs/plugins/manifest/index.md#notificationstypes-notifications-a-plugin-raises)
gets an `env.NOTIFY` binding with one method, `raise`. The host routes
each raise by the administrators' rules and each patron's preferences;
the plugin never learns where it went.

```ts
await env.NOTIFY.raise({
  notificationType: "sync_failed",
  fields: { Account: account.name },
  linkPath: `/accounts/${account.id}`,
  alertAction: "trigger",
  alertKey: `sync:${account.id}`,
});
```

- `notificationType` is a declared type id, without the plugin prefix
  the host adds.
- `fields` are `{ name, value }` rows or a plain object, with the caps of
  a message's fields.
- `patronId` is required for a `patron` type: the patron's library
  user id in decimal (`"42"`, with no sign or leading zero), for a patron
  who holds the store account the invocation runs for.
- `linkPath` is a path inside the library (`/books/42`): it starts with
  one `/` and has no space or backslash. The host adds its public origin.
- `groupKey`, `alertAction` and `alertKey` follow the message rules.

`raise` answers the host's `notificationId`, or `invalid_params` for an
undeclared type or a malformed raise, `forbidden` for a patron outside
the scope, and `rate_limited` past the per-session raise budget.
Python authors call `env.NOTIFY.raise_(...)` with snake-case keywords.
Native guests receive the binding as `Bindings.notify`.
The binding is handed to the instance's entrypoint calls (not to
stream copies). A plugin may raise at most 30 notifications a minute per
session (one per store account the instance works for).

### Public addresses (`ingress`)

Export `ingress` to give the library a public `https` address, so patrons
and branches can reach it from outside the home network. The
[`[ingress]`](/docs/plugins/manifest/index.md#ingress-public-address) table says how: a
`relay` plugin carries requests from a provider such as a tunnel service,
and a `direct` plugin keeps an address that points at the daemon current.
The host runs at most one ingress instance at a time.

The typed methods on `Ingress` and `IngressEntrypoint` are:

| Method | Notes |
| --- | --- |
| `start` | `()` → `{ origin }`. Bring the address up and answer once it serves. `origin` is `https://` and a lowercase host name of at least two labels, with no port, path, query, user info or trailing dot or slash, at most `MAX_INGRESS_ORIGIN_BYTES` (253) bytes after the scheme. The top label starts with a letter, so nothing a URL parser reads as an IP address passes |
| `health` | `()` → `{ serving, detail }`. Whether the address serves now; `detail` tells the operator why not |
| `stop` | Take the address down. The host stops relying on it once this returns |

A relay plugin hands each request its provider delivers to the library:

```ts
export class Ingress extends IngressEntrypoint<Env> {
  async start(): Promise<IngressStarted> {
    // Connect to the provider; for each request it delivers:
    //   const response = await this.env.ORIGIN.fetch(request, {
    //     clientAddress: providerReportedClientIp,
    //   });
    return { origin: "https://lib.example.net" };
  }
}
```

`env.ORIGIN.fetch(request, { clientAddress })` sends the path and query of
`request.url`, its method, headers and body, and resolves with the
library's `Response`. Both bodies stream. The host checks each request
before the library sees it and refuses it with `invalid_params` when:

- the method is not an HTTP token of at most 32 bytes;
- the target is not a path and query (it must start with one `/`, hold
  only visible ASCII and no `#`) or is longer than
  `MAX_ORIGIN_TARGET_BYTES` (8192);
- there are more than `MAX_ORIGIN_HEADERS` (128) header fields, their names
  and values add up to more than `MAX_ORIGIN_HEADER_BYTES` (64 KiB), a name
  is not a token, a value holds a control or non-ASCII byte, or a field
  describes the connection (`connection`, `keep-alive`, `te`, `trailer`,
  `transfer-encoding`, `upgrade` and the `proxy-*` fields);
- `clientAddress` is set and is not an IP address.

The TypeScript binding drops connection fields itself. `host`,
`forwarded`, `x-forwarded-*` and `x-real-ip` are dropped rather than
refused: the library answers on its own public origin, and the client
address comes only from `clientAddress`. Take it from the provider's own
connection metadata (such as `cf-connecting-ip` on a Cloudflare relay),
never from a header the client sent. Responses follow the same header
rules, so a library response never carries a connection field.

`env.ORIGIN` is present only on a `relay` plugin while it is the active
ingress, and only in the TypeScript SDK; the Python SDK serves `direct`
plugins.

The host runs an `ingress` instance only while it is the library's
active ingress (`bookclerk ingress activate`), an Owner exists and
operator auth is on. It calls `start` once the guest is healthy, `health`
every minute, and `stop` before it retires or replaces the instance.
Every `ORIGIN` request is the `tunnel` transport: the operator's own
paths and credentials are refused, and the operator's exposure choice
decides the rest (see [Public address](/docs/server/ingress/index.md)). `ORIGIN`
carries plain HTTP requests, not WebSocket upgrades.

### Model plugins

Export `ai` to serve models: the plugin loads them, the host and other
plugins call them by name (see the [model plugins ADR](/docs/adr/ai-models/index.md)).
`[ai].serves` in [`plugin.toml`](/docs/plugins/manifest/index.md#ai-models) declares the tasks.
**Text embeddings** (`textEmbeddings`) is the only task today: a model
turns each text into a vector, and texts with similar meaning get nearby
vectors.

The typed methods on `AiModels` and `AiEntrypoint` are:

| Method | Notes |
| --- | --- |
| `health` | Liveness and readiness: can the models be loaded with the current settings |
| `models` | `()` → `{ models }`. The models served now. Must be cheap: load no model here |
| `run` | `({ model, input })` → `{ output }`. Run one model on one input; `model` is the plugin's own model id |

A listed model has a `modelId` (`[a-z0-9][a-z0-9._-]*`, at most 158
bytes), a `task`, a `revision` and, for text embeddings, `dimensions`
(numbers per vector, 1 to `MAX_AI_EMBED_DIMENSIONS`, 4096), `maxTokens`
and the `languages` it has loaded. Callers name it
`@<plugin id>/<model id>`.

> [!IMPORTANT]
> Vectors are comparable only within one revision. Change `revision`
> whenever the weights, the tokenizer or the loaded language packs change.
> The host stores it beside every vector and never compares across
> revisions.

The input of a text-embedding run is `textEmbeddings.texts`: 1 to
`MAX_AI_EMBED_TEXTS` (64) texts of at most `MAX_AI_EMBED_TEXT_BYTES`
(16 KiB), each marked `document` (stored content) or `query` (a search
query matched against documents). The output is `textEmbeddings`:

- `dimensions` and `revision`, the same as the listing;
- `vectors`: one vector per text in input order, as little-endian 32-bit
  floats, concatenated (`packEmbeddingVectors` builds it);
- `fallbacks`: ascending indexes of the texts the tokenizer could not
  cover with the loaded languages, so the host can recompute them later.

The host treats the listing and every reply as untrusted. A listing over
`MAX_AI_MODELS` (64), with a repeated or malformed id, an unprintable
revision or a missing vector length is refused whole. A reply with the
wrong number of vectors, another length or revision, or a number that is
not finite fails the run as `unavailable`; the caller never sees a partial
result.

```ts
export class Ai extends AiEntrypoint<Env> {
  async models(): Promise<AiModelList> {
    return {
      models: [
        {
          modelId: "tiny",
          task: "textEmbeddings",
          revision: "sha256:0123abcd",
          dimensions: 384,
          maxTokens: 512,
          languages: ["en"],
        },
      ],
    };
  }

  async run({ model, input }: AiRunParams): Promise<AiRunOk> {
    if (model !== "tiny") throw new PluginError("not_found", `no model ${model}`);
    const vectors = input.textEmbeddings.texts.map(({ text }) => embed(text));
    return {
      output: {
        textEmbeddings: {
          dimensions: 384,
          vectors: packEmbeddingVectors(vectors),
          revision: "sha256:0123abcd",
          fallbacks: [],
        },
      },
    };
  }
}
```

> [!NOTE]
> Bookclerk's own features do not call models yet: Discover still ranks
> with word-hash vectors. The first-party model plugin and Discover on
> model vectors come next.

### Calling models

A plugin that lists tasks under [`[ai].calls`](/docs/plugins/manifest/index.md#ai-models) gets
an `env.AI` binding with one method, `run`, shaped like the `AI` binding
of Cloudflare Workers. The host routes the run to the deployed plugin
that serves the model.

```ts
const out = await env.AI.run("@library/text-embeddings", {
  text: ["A detective in Victorian London", "Dragons and a stolen ring"],
});
// out.shape = [2, 384]; out.data[0] is the first vector
```

- The model is `@<plugin id>/<model id>`, or the alias
  `@library/text-embeddings` for the library's text-embedding model, so a
  caller need not know which plugin is installed.
- `text` is one text or a batch; `role` is `document` (the default) or
  `query`.
- The answer has `shape`, `data` (one `number[]` per text), the full
  `model` name that ran, its `revision`, and `fallbacks`. Store `model`
  and `revision` beside any vector you keep.

`run` fails with `invalid_params` for a malformed name or input,
`forbidden` for a task the plugin was not granted, `not_found` when no
plugin deployed on the node serves the model, `rate_limited` past the
budget, `deadline_exceeded` after 30 seconds, and `unavailable` when the
model plugin failed or answered wrongly. A plugin cannot call a model it
serves itself.

A plugin instance may send 240 texts a minute through `AI`. That is
enough to embed a search query or a handful of new items; work over a
whole library belongs to the host's jobs.

Python authors call `await env.AI.run(model, text=[...], role="query")`.
Native guests receive the binding as `Bindings.ai` and send `AiRunParams`.

### Storage entrypoints

Export `storage` (there is no `kind = "output"`). Guests implement
[`Destination`](https://github.com/Bookclerk/bookclerk/blob/main/packages/plugin-sdk/src/plugin.ts) and
`StorageEntrypoint`: `head`, `list` (paginated), streamed `get`, streamed
`put`, optional `copy`, and the optional
[intent operations](#intent-operations).

- The host never reassembles a large object into `Bytes`, and never writes
  the full object to guest scratch and then `put_file`. S3 guests feed the
  existing multipart sink as bytes arrive.
- Oversized scalar `put` and `get` fail closed.
- There is no public `handleId` / `readChunk` / `writeChunk` protocol.
  Destinations transfer media through `ByteSource` streams. Range,
  multipart and checkpoint work in issue #120 builds on this contract,
  without another public ABI redesign.

#### Intent operations

Beyond the required methods, a storage guest can take over operations the
host would otherwise build from `head`, `list`, `copy`, `get`, `put` and
`delete`. The host says what it wants and the guest chooses how. Each
operation is optional: the guest declares it by accepting its feature in
`rpcFeatures`, and the host runs its own fallback for every operation the
guest did not declare. The fallback gives the same result when nothing else
writes the same keys at the same time, but it may be slower (a copy and a
delete instead of a rename) and it is not atomic: a concurrent writer can
slip in between its steps. Where that matters, the guest declares the
operation, or `storage.conditionalWrite`, and enforces it natively.

| Feature | Method | What the guest does |
| --- | --- | --- |
| `storage.move` | `move(from, to, options)` | Moves one object. |
| `storage.moveMany` | `moveMany(request)` | Moves explicit pairs, or one page of every object under a prefix. |
| `storage.deleteMany` | `deleteMany(keys)` | Removes up to `maxBatchKeys` (256) objects. |
| `storage.headMany` | `headMany(keys)` | Probes up to `maxBatchKeys` objects. |
| `storage.translateKeys` | `translateKeys(keys)` | Turns up to `maxBatchKeys` host keys into the keys it stores ([Translating keys](#translating-keys)). |
| `storage.conditionalWrite` | `put` with `ifMatch` / `ifNoneMatch` | Publishes only while the precondition holds, else fails with `conflict`. |
| `storage.changes` | `changes(request)` | Returns keys changed since a cursor. |

The rules every operation follows:

- **Replies say what was honoured.** `MoveResult.atomic` and
  `MoveManyPage.atomic` say whether the move was a rename no reader could
  observe half done. A `list` page sets `signaturesIncluded` when it filled
  in the signature fields `ListOptions.withSignatures` asked for, and
  `modifiedSinceApplied` when it left out objects older than
  `ListOptions.modifiedSinceMs`; a guest that ignores a hint returns the
  unfiltered page and leaves the flag false.
- **Long operations are paged and safe to repeat.** A prefix `moveMany`
  returns at most `maxBatchKeys` outcomes and a `nextCursor`, and repeating
  a page after a restart moves nothing twice. A `move` whose source is gone
  and whose target exists succeeds with `alreadyMoved`.
- **Batches answer per key.** `moveMany` with pairs and `deleteMany` return
  one outcome per key, in the order sent; an outcome with an error code is
  that key's failure, and the rest of the batch still counts. Deleting a
  missing object is a success. `headMany` returns one probe per key, empty
  for a missing object.
- **Options only grow.** `MoveOptions`, `ListOptions` and `WriteOptions`
  gain fields at new ordinals, and a zero value always means the old
  behaviour.
- **Preconditions are never dropped.** A request whose `ifMatch`,
  `ifSourceMatch` or cursor cannot be read is refused rather than run
  without it, and a granted destination (a `put` through a capability
  handed to another plugin) refuses `ifMatch` / `ifNoneMatch` because that
  channel cannot carry them yet.
- **Prefix moves need disjoint prefixes.** The source and target of a
  prefix `moveMany` may not contain each other, after `.` and empty path
  segments are dropped and `\` is read as `/`, because a nested object could overwrite one that
  has not moved yet.

The platform `local` destination declares every operation: moves are
renames, and on a local disk `noOverwrite`
and `ifNoneMatch` publish through a hard link that fails when the target
exists. `ifMatch`, and every condition on a network or FUSE mount, is
checked just before the rename and reported as not atomic (see
[Local filesystem](/docs/server/output/index.md#local-filesystem)). Its `changes`
feed comes from a file-system watcher when the instance's `watch` setting
is on and the root is on a local disk; otherwise every page has `complete`
false (see [Watching the folder](/docs/server/output/index.md#watching-the-folder)).

The optional `s3` destination declares the same set. It cannot see its
bucket's settings when it is described, so it declares them for every store.
Its `changes` feed drains the bucket's Amazon SQS notification queue when
the instance's `notification_queue_url` setting names one, and otherwise
every page has `complete` false (see
[Following changes in the bucket](/docs/server/output/index.md#following-changes-in-the-bucket)).
It finds out once, on first use, which request kinds (plain upload,
multipart completion, copy, part copy, delete) enforce their conditions
(see
[Moves and conditional writes](/docs/server/output/index.md#moves-and-conditional-writes)).
Where every request an operation sends is enforced, conditions go to S3
with the request and the store decides them; a move is a pinned copy and a conditional delete, never
atomic. Otherwise the guest runs the host's own algorithm for that
operation and says `atomic: false`.

The host checks every reply against the request before acting on it: the
outcomes must name the keys it sent, in order, a prefix page may only name
keys under the prefix and must advance its cursor, and a `changes` page
stays within `maxChangesPage` (256) entries and a cursor of at most
`maxChangesCursorBytes` (4 KiB). A reply that breaks a rule fails the
operation with `internal`.

Listing entries and probes can carry a change **signature**: an opaque
backend-defined value (for example a local file's inode, size and times,
or an S3 ETag and version id) that stays the same while the object is
unchanged. The host uses it to skip re-reading files it already knows.
`modifiedAtMs` and `versionId` ride alongside it.

The host's own `move` fallback copies, probes the source again, and deletes
it only when the probe shows it is still the object it copied (same etag,
else same size and modification time); a source rewritten during the copy,
or one the probe cannot vouch for, is kept and the move fails with
`conflict`. Without etags the check is a heuristic: a rewrite of the same
size within the same millisecond passes it. The ABI has no delete
conditioned on an etag, so a rewrite between that probe and the delete can
still be lost too. A guest that declares `storage.move` avoids both gaps. With `noOverwrite`,
the fallback writes the target with `ifNoneMatch` when the guest declares
`storage.conditionalWrite`, and otherwise checks for the target just before
the copy (so `atomic` is false).

`changes` is a hint, not a ledger. The first call, with an empty cursor,
returns the current position and no changes. A feed drained from a queue
treats a call's cursor as the receipt for the pages up to it: their
messages are deleted then, and pages handed out after it are offered again,
so a retried cursor gets those changes once more. Such a feed has one
reader, so the host calls it from one place: the destination's sync pass,
every five minutes, on the one node holding the destination's sync lease.
It records each page before it sends that page's cursor back, and probes
(`head`) a changed key whose entry carries no size or signature. A page with `complete` false
means the guest may have missed changes since the cursor (a watcher
restarted, a queue dropped messages), and the host backs it with a full
listing. A change kind added after an SDK was built reads as `changed`. A scheduled listing stays the backstop either way.

`liveWatch` says the running guest produces the feed itself, so stopping
it would lose changes (a watcher, as opposed to a durable queue). While
the latest page has both `complete` and `liveWatch` true, the host keeps
the guest awake instead of stopping it when idle. A page without them, a
`changes` error, or the guest exiting lets it sleep again. The host
honours `liveWatch` only from the first-party storage plugins it starts on
demand, which today means the `local` destination with `watch` on (see
[decision 13](/docs/adr/event-delivery-model/index.md#decision)).

#### Translating keys

The host names every file with one **host key**: segments joined by `/`,
each non-empty, never `.` or `..`, with no `\` or control characters, at
most 1024 bytes. A destination that declares `storage.translateKeys`
receives host keys in `translateKeys(keys)` and returns, in the same order,
the key it will store each one under: a path its file system accepts, or an
object key its store can hold. The host then writes, checks for and records
that key, and never passes a translated key back through `translateKeys`.

A destination without the feature stores each host key as written, and the
host does not wake a sleeping guest to ask. The host checks every reply: it
has one key per host key, and each key is relative, at most
4 KiB, with no control characters and no empty,
`.` or `..` segment when split on `/` or `\`. A reply that breaks a rule
fails with `internal`, and the host stores host keys for that write.

Translation should be deterministic: the same host key must give the same
key on every call, because the host recomputes it to find files it wrote
earlier. The SDKs' `translateKeys` default returns the keys unchanged. The
`local` destination applies the host platform's file-name rules, and `s3`
the object-store rules and 1024-byte limit including its prefix (see
[Keys each destination stores](/docs/server/output/index.md#keys-each-destination-stores)).

The optional `r2` destination declares the same set as `s3` and shares its
implementation. Its `changes` feed pulls the bucket's event notifications
from a Cloudflare Queue's HTTP pull consumer when the instance's
`notification_queue_id` setting names one, and otherwise every page has
`complete` false (see
[Following changes in an R2 bucket](/docs/server/output/index.md#following-changes-in-an-r2-bucket)).
It is an ordinary storage guest: its settings and secrets reach it in
`CONFIG` and `SECRETS`, and its network access is its declared
`[capabilities.network]` grant.

The optional `b2` destination talks to Backblaze B2's native API. It
declares only `storage.translateKeys` (with the `s3` key rules) besides
copies: B2 has no conditional writes, so the host checks before a
conditional write and reports it as not atomic, and moves, batch deletes
and batch probes use the host's fallbacks. It has no `changes` feed yet.
Its replies are read by `bookclerk-storage::b2_api`, a fuzzed boundary.

First-party S3 ships as `bookclerk-plugin-destination-s3`
(`api_version = 3`). Its bucket, region, endpoint, prefix, naming
overrides and credentials are `[[settings]]`. The host runs it wherever
its instance has a present deployment, and has no in-process S3 backend.

A second install that reuses `id = "s3"` is a separate PluginKey with its
own instances.

### Database adapter entrypoints

Export `databaseAdapter` (there is no `kind = "database"`). Guests are
**BookclerkSQL adapters**: they implement the SeaORM proxy boundary over
Workers RPC, plus a generic atomic-plan executor.

- Guests speak only canonical BookclerkSQL. Adapters lower it at execute
  (`bookclerk-db-exec`).
- Engine connect, migrate and proxy code lives in the guest
  (`bookclerk-plugin-database-sqlite`, and the optional d1 and postgres
  guests). The host doesn't link SQL engines.
- The host owns the schema, domain SQL, proofs and Bookclerk invariants
  (see [ADR: SQL database contract](/docs/adr/sql-database-contract/index.md)).
  Guests must not import Bookclerk entities or embed application table
  names.
- The host opens the library through the external database loader (the
  guest is required; there is no in-process fallback). SQLite opens
  `library.db` at the jail-granted path (`BOOKCLERK_SQLITE_PATH` or
  `sqlitePath`) when the session opens.

> [!IMPORTANT]
> A backend that can't advertise `atomicBatch`, parameterized statements,
> and bind and statement limits at or above the host minimum is **not
> loaded** (fail closed). Non-SQL engines aren't supported.

An adapter proves it keeps this contract with the adapter conformance
suite in `bookclerk-db-testkit` (see
[A database adapter's own suite](/docs/plugins/database-limits/index.md#a-database-adapters-own-suite)),
which every first-party adapter passes.

| Method | Notes |
| --- | --- |
| `Database.openSession` | Opens the adapter session. The guest connects its engine from `DatabaseContext.config` (verified first-party guests receive host-injected connect params; SQLite: path grant; D1/Postgres: host-injected credentials) |
| `Database.dropUnit` | Physically deletes one provisioned binding unit (`unitRef` is adapter-owned: a sqlite path, a postgres database, a D1 name). Missing units are success. Adapters that can't prove deletion fail closed |
| `AdapterDatabaseSession.capabilities` | A typed control-plane call after `openSession`. Advertises the SQL contract version, execution semantics, `schemaMigrations`, backup flags and all limits. Host policy requires `schemaMigrations`. Diagnostic engine identity isn't a capability. The host must not invent these from the plugin id |
| `AdapterDatabaseSession.bootstrap` | The diagnostic engine name only (`engine`). Not part of `DbCapabilities`, and never used to admit a guest or generate SQL. Any string is valid |
| `AdapterDatabaseSession.execute` | The one typed atomic operation (`AdapterExecuteRequest` → `ExecuteReply`). The request is already-desugared canonical Bookclerk SQL (`?` placeholders) plus 1:1 hash-bound proofs. Adapters lower at execute. Guests don't interpret Bookclerk operation names. `job(job)` does **not** receive the host library on `env`: plugins that need durable SQL declare `[[databases]]` bindings, and receive physically separate units on `env.<BINDING>` |
| `AdapterDatabaseSession.executeStreamed` | The same atomic batch as `execute`, answered as `ExecuteStreamFrame`s (`ExecuteStreamReply`: `inline` bytes, a `ByteSource`, or `err`) so the result may grow to `maxStreamedResultBytes` / `maxStreamedResultRows`. The batch commits before the first frame. Adapters that do not stream advertise `0` for both caps and answer `unsupported` |
| `AdapterDatabaseSession.close` | Releases the session and its engine connection |

Some methods are host-private: never visible to plugin authors, and only
in first-party guests built with the abi `host` feature.

- `HostAdapterDatabaseSession.begin` opens a native interactive SeaORM
  transaction and returns an `AdapterTransaction` (`execute`, `commit`,
  `rollback`).
- The host records a sticky per-task fault when `begin` fails, so later
  statements can't fall back to autocommit. A failed `commit` is surfaced
  to `LibraryStore` (SeaORM's proxy hook is infallible).
- `AdapterDatabaseSession.execute` and `HostAdapterDatabaseSession.execute`
  carry the same `AdapterExecuteRequest` (canonical SQL, structured
  proofs, an optional receipt-persist hint).
- D1 keeps `begin` unsupported, and routes host `execute` through its
  native batch proxy.

The built-in ids are `sqlite`, `d1` and `postgres` (matching
`[database].plugin`).

### Isolated plugin database bindings

Plugins may declare Workers-style **named database bindings** in the
manifest:

```toml
[[databases]]
binding = "DB"

[[databases]]
binding = "CACHE"   # [A-Z][A-Z0-9_]*, unique, max 8
```

SQL bindings don't replace `[[kv_namespaces]]`. Named bindings are
**plugin-private state**, not a place to put host tables. The durable job
queue, library catalog and secrets stay in the host library database, and
`job(job)` never gets an `env` binding pointed at `library.db`.

The active adapter provisions bindings, physically separate from the
Bookclerk library and from every other plugin (close to a Cloudflare
Workers D1 binding):

- **SQLite:** one file per binding, under
  `$BOOKCLERK_FILES_DIR/plugin-databases/<plugin-key-fs-id>/<BINDING>.db`
  (the sqlite adapter jail grants that folder). The leaf is
  `PluginKey::fs_id()` (`pk-` plus 32 hex, 128 bits), not the display
  alias and not the canonical PluginKey (which isn't a valid Windows path
  component). The `plugin_databases` registry still stores the canonical
  PluginKey.
- **PostgreSQL:** one database per binding (`pb_` plus 32 hex of the
  `(plugin, binding)` digest; 35 ≤ 63 characters), created on first use
  (`CREATEDB` required). This is a separate database, not a schema on the
  library database, so plugin SQL can't see host tables.
- **Cloudflare D1:** one D1 database per binding (`bookclerk-pb-` plus the
  same 32 hex), found or created by name through the REST API. Provisioning
  fails closed with an operator-facing error when the API token can't
  create databases.
- **Third-party adapters:** advertise `DbCapabilities.pluginDatabases` and
  the backup flags they can actually provide (`consistentBackupRead`,
  `atomicUnitRestore`). The host opens plugin bindings through the active
  adapter session (`DatabaseAdapterConfig` + `provision`), and doesn't
  switch on sqlite, postgres or d1 crates. Adapters that don't advertise
  support fail the job, rather than sharing a database.

**Consent.** Each binding appears as a `database:<NAME>` grant entry, and
needs operator approval before enable, like other capabilities.

**Registry.** Provisioned units are recorded in the host
`plugin_databases` registry. An existing row wins, so re-opens never
re-target a binding.

Operators inspect and remove them with
`bookclerk plugins db list` and
`bookclerk plugins db drop <plugin> [binding]`. The drop command calls the
adapter's `Database.dropUnit`, then removes the registry row, and fails
closed if a physical delete can't be proven.

#### Schema migrations inside a binding

Inside a binding the plugin **owns its schema**. It registers a complete,
ordered history at startup (`databaseMigrations(binding)`): opaque IDs the
plugin chooses, plus already-separated BookclerkSQL `schema` and `data`
operations. Bookclerk gives those IDs no version meaning; registration
order is the forward sequence.

Registration is a bounded startup scalar:

- at most `maxListPage` migrations;
- `maxPluginMigrationOps` operations per migration;
- `maxPluginMigrationTotalOps` operations across the registration;
- each SQL at most `maxScalarBytes`;
- aggregate id and SQL UTF-8 at most
  `maxPluginMigrationRegistrationBytes`.

The host then:

1. Proves the sequence with one evolving type environment.
2. Checks that the durable `bookclerk_plugin_migrations` history is an
   exact prefix of the registration.
3. Applies only the pending suffix, one atomic receipt per registered
   migration (slot lock, operations, journal append).

Ordinary binding `execute` is query and DML only. Durable `CREATE` and
`DROP` are admitted only while the host applies that registration.
`ALTER` and `CREATE TABLE AS` stay refused.

Mixed guest `CREATE` plus `INSERT` isn't a product path: register and
apply, then DML. A same-token DML replay must not insert twice.

#### Reserved names

Inside a binding, the host reserves exactly one identifier prefix,
`bookclerk_`. All of its bookkeeping carries it:
`bookclerk_schema_migrations`, `bookclerk_plugin_migrations`,
`bookclerk_receipts`, `bookclerk_slots`, the `bookclerk_sql_*` catalog,
and the `bookclerk_src` wrap alias.

- Engine catalogs (`sqlite_*`, `pg_*`, `information_schema`) and
  schema-qualified names are reserved too.
- `REFERENCES` targets use the same reserved-name rules as `CREATE` and
  `DROP`.
- Any other name, including a framework's own `schema_migrations`, is the
  plugin's.
- The binding's own `bookclerk_receipts` and `bookclerk_plugin_migrations`
  tables stay host-owned, so retry tokens replay inside the binding and
  plugins can't edit the journal.

#### The SQL a plugin may use

The guest grammar still applies: a single statement, no `ATTACH`,
`PRAGMA` or session verbs, and no schema-qualified names. It is Bookclerk
SQL v1, not a wider SQLite dialect:

- Functions are the portable helpers, and `hex` is denied.
- Column types are `INTEGER`, `REAL`, `TEXT`, `BLOB` and `BOOLEAN`.
- `INSERT OR IGNORE` is for unique or primary-key conflicts only, and is
  lowered to `ON CONFLICT DO NOTHING` on every backend, including SQLite
  and D1. `SELECT` and `WITH` sources are wrapped as
  `SELECT * FROM (<source>) AS bookclerk_src WHERE true`.
- Helper arity and wire types are enforced, so callers needn't `CAST` for
  `round`, `sum`, `avg` or `count`.
- Canonical `LIKE` is case-sensitive (`GLOB` lowering on SQLite and D1,
  `COLLATE "C"` on Postgres).

Schema metadata is durable in the adapter-private
`bookclerk_sql_catalog`, `bookclerk_sql_schema` and `bookclerk_sql_ddl`
tables (Postgres identity is in `bookclerk_identity`). All are
guest-denied.

- Opening a binding reloads types from that catalog.
- A matching no-op `CREATE TABLE IF NOT EXISTS` doesn't rewrite the
  catalog or identity. The first admitted CREATE must persist complete
  canonical DDL, and a binding missing that catalog fails closed (reset or
  recreate it).

See the [SQL contract v1](/docs/plugins/sql-contract/v1/index.md).

#### How bindings reach the guest

`PluginWorker.open` receives the bindings as the append-only
`Bindings.databases :List(NamedDatabase)` field.

- Rust guests call
  `DatabaseBinding::take_named_from_bindings(&mut bindings, "DB")`.
- For workerd guests, the launcher mints one database-only grant token per
  binding at `open`, and carries it in the bridge context
  (`databases: { DB: <token> }`). The trusted adapter isolate turns each
  token into a granted-channel transport over `POST /db/execute` (with
  `GET /db/limits` for `limits()`; the launcher also serves
  `POST /db/execute-streamed`, the streamed read the SDK helpers adopt
  next, see the [SQL contract](/docs/plugins/sql-contract/v1/index.md#streamed-results)), and
  installs the resulting
  `env.DB` on the author's `env` for every call of that `open` (events,
  storefront, jobs, …). It is a full `DatabaseBinding`: `prepare`, `bind`,
  `run`, `all`, `first`, `raw`, `batch` and `limits()`.

Authors never see the token.

## Next steps

- [plugin.toml](/docs/plugins/manifest/index.md): declare entrypoints, triggers and bindings.
- [Capabilities and consent](/docs/plugins/capabilities/index.md): what each binding needs
  approved.
- [Jobs](/docs/internals/jobs/index.md): the durable queue behind jobs and event
  deliveries.
