# ADR: Capability-driven plugin ABI v3

- **Status:** Accepted
- **Date:** 2026-09-10
- **Updated:** 2026-09-25 (native-behind-workerd is a host-spawned sibling
  jail, not a nested child of `bookclerk-workerd`)
- **Supersedes:** role / factory / `HOST.notify` sections of
  [`plugin-workers-rpc-workerd.md`](/docs/adr/plugin-workers-rpc-workerd/index.md)
  (`api_version = 2`). Isolation, jail, network consent, workerd pin, and
  distribution-tier decisions in that ADR remain in force.

## Context

`api_version = 2` froze an object-capability Workers RPC with **role factories**
(`BookclerkPlugin`, `Destination`, `Source`, `JobHandler`, …), JSON method
payloads for several storefront / integration surfaces, and a reverse
`HOST.notify` channel. That model fought the direction of the product:

- Authors already think in Workers terms (default export + named entrypoints,
  `env` bindings, queue/scheduled triggers).
- The host needs one control-plane front door (`bookclerk-workerd`) for every
  guest, including native storefronts and database adapters.
- Domain events belong in a durable outbox with typed consume/publish, not a
  guest→host notify stub.
- Database guests must stay engine-agnostic and isolated from host bookkeeping
  (`bookclerk_` prefix — see [`sql-database-contract.md`](/docs/adr/sql-database-contract/index.md)).

## Decision

1. **Product `api_version = 3`.** Manifests are wrangler-shaped:
   `main` / `[workerd]`, `entrypoints = [...]`, `[[events.consumers]]` /
   `[[events.producers]]`, `[[databases]]`, `[vars]` / `[secrets]`, optional
   `[triggers] jobs`, `[cli]`, `[[oidc.clients]]`. There is **no** `kind`,
   `methods.list`, or `supportedRoles`. Handler family is derived from
   declared entrypoints and triggers. Consent is by entrypoint + binding +
   producer + **event consumer** + **job trigger** (+ network), not by role
   string. Event-consumer identity includes `type`, `schema_versions`,
   `supports_suspend`, and `filter` (what the plugin receives). Operational
   knobs `resource_class` and `max_retries` are not authority. Operators may
   narrow structural capabilities; they may not invent ones the package did
   not declare. Adding a consumer or job on a same-PluginKey upgrade leaves
   the existing approval usable for the previously granted subset; the new
   capability stays pending until the operator consents. Empty structural
   sets mean “approve none” for every grant schema version, including
   omitted/`0` legacy JSON; they do not inherit the manifest.
   `authority_revision` includes consumers, jobs,
   and operator-controlled resource budgets.

2. **`PluginWorker.open(invocation, bindings) -> Entrypoints`.** One open per
   invocation returns typed capabilities (`eventConsumer`, `jobRunner`,
   `storefront`, `storage`, `databaseAdapter`, `remoteLibrary`, `cli`,
   `oidc`); absent families are null. Role factories are deleted. `Bindings`
   carries `EVENTS` (`EventPublisher`), named `[[databases]]`, config,
   secrets, and optional `WORK_FS`. Per-job `input` / `output` / `progress` /
   `cancel` travel on `JobController`, not on open.

3. **Typed Cap'n Proto everywhere.** Storefront, CLI, OIDC, remote-library,
   event, and job method payloads are Cap'n structs (generated TS interfaces /
   Python TypedDicts + `@internal` codecs). JSON remains only for
   plugin-specific extensible config and event payloads (bounded). In-band
   errors use `result` unions (`ok` / `err`) with `PluginErrorCode` wire
   strings.

4. **SDK idioms mirror Workers.** Authors extend `BookclerkEntrypoint`
   (default export) with optional `event(batch)` / `job(controller)` triggers
   and export named `*Entrypoint` classes. `EventMessage` records
   `ack` / `retry` / `reject` / `deadLetter` / `suspend`. `bookclerk-plugin
   types` generates `Env` from `plugin.toml`. Native Rust guests implement
   `PluginWorker` + `serve` on stdio Cap'n RPC.

5. **`env.EVENTS.publish` replaces `HOST.notify`.** The host
   `EventPublisher` forces `source` = plugin id, intersects producers with the
   operator grant, requires / synthesizes dedup keys, caps payload size, and
   writes the library outbox. Consume is typed `EventConsumer.event` with
   at-least-once delivery; guests must be idempotent on `deduplicationKey`.

6. **Workerd is the mandatory front door.** The host spawns every plugin
   through `bookclerk-workerd`. Isolate vs native-jail is a backend the
   launcher selects from `runtime`. One `POST /invoke` carries Cap'n
   `$Params` bytes (headers name interface / method / bridge context / cap
   table); the trusted adapter dispatches to author classes or the native
   broker. Broker fast paths (`AdapterDatabaseSession`, byte `Source`) never
   enter JavaScript. Direct host↔native Cap'n Proto is
   `SpawnTransport::DirectNativeDiagnostic` only (tests / diagnostics).

7. **Three-path conformance.** Shared vectors run against (a) workerd
   author fixtures, (b) workerd → broker → host-spawned sibling-jailed
   native backend, and (c) diagnostic direct Cap'n Proto — **for every
   surface those fixtures support** (storefront/CLI and jobs on all three
   paths; events and named-database binding vectors on workerd author
   fixtures; product sqlite `databaseAdapter` on native-behind-workerd).
   Path (b)'s OS confinement is the sibling `NetPolicy::Deny` jail the host
   starts next to the gateway (the launcher never nests `bookclerk-jail`).
   Shared helpers in `crates/bookclerk-workerd/tests/conformance.rs` plus
   `bookclerk-workerd-native-fixture` keep the transports honest.

8. **One network policy engine.** `fetch()`, workerd `connect()`, and the
   native-behind-workerd socket proxy consume the same `EgressPolicy`:
   fetch hosts, TCP `host+ports`, redirect consent, and CIDR address-space
   grants. Fetch does not imply TCP. Default address space is public
   Internet only. Native guests are sibling-jailed under `NetPolicy::Deny`
   and must use the SDK socket capability over an inherited `fd:` /
   `handle:` mux; the launcher jail is `LocalIpc` (no IP socket; its
   egress leaves as host-checked tunnels). Grant mutation is live: `plugin-grants.json` changes
   fence running vats immediately (vat shutdown + kill child + drop the
   socket proxy and granted channels), including CLI writes observed by
   `bookclerkd`. Idle mediated TCP is interrupted on the fence; enforcement
   does not wait for the next host RPC. `grant_revision` (persisted operator
   consent) is distinct from `authority_revision` (effective runtime grant
   after host overlays and clamped budgets) and from
   `configuration_revision` (manifest / host-config hash). The grant
   watcher compares grant revisions only and retries malformed files
   without mass-fencing.

9. **Provenance-qualified identity.** Durable consent, sessions, plugin
   state, and grants key on `PluginKey` (canonical provenance + package +
   manifest id). Version and content hashes are `ArtifactIdentity`, not the
   logical key. A bare `id = "sqlite"` confers no privilege; platform
   defaults require host-stamped provenance plus matching content hashes.

10. **No in-process product plugins.** `bookclerk` / `bookclerkd` /
    `bookclerk-plugin-host` never link ordinary plugin implementation crates,
    including `bookclerk-plugin-database-*`. Database adapters own physical
    lowering behind `databaseAdapter` (`openSession`, `dropUnit`). Direct
    host↔native Cap'n Proto remains `DirectNativeDiagnostic` only. CI
    (`scripts/check-plugin-architecture.sh`) enforces this.

## Consequences

- Daemon / CLI / UI group plugins by handler family, not `PluginKind`.
- Echo examples and product guests are `api_version = 3` only.
- CI fails on Cap'n schema drift (`scripts/gen-plugin-abi.py --check`),
  author-surface leakage (`tools/author-surface-check`), workerd pin /
  bridge mirror drift (`scripts/sync-workerd-pin.py --check`), store-free
  hosts (`scripts/check-store-free-hosts.sh`), and architecture lints
  (`scripts/check-plugin-architecture.sh`).
- Docs: this ADR is the v3 decision record; [`plugins.md`](/docs/plugins/index.md)
  is the author/operator handbook.
- Every surface a guest can reach with bytes of its own is fuzzed per
  [Untrusted-input fuzzing](/docs/adr/untrusted-input-fuzzing/index.md): the typed Cap'n
  Proto replies, the granted HTTP channel, the egress policy, the socket
  proxy mux (`mux_peer`) and guest-SQL authorization (`guest_sql_authz`)
  have targets, listed in [`docs/contributing/fuzzing.md`](/docs/contributing/fuzzing/index.md); a new
  entrypoint family or channel adds its target in the same change.

## Non-goals

- Dual-stack support for `api_version = 2` role factories or `HOST.notify`.
- Cloudflare-hosted Dynamic Workers for operator plugin execution.
- Marketing workerd alone as the security boundary (OS jail remains
  mandatory — unchanged from the v2 ADR).
