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.notifysections ofplugin-workers-rpc-workerd.md(api_version = 2). Isolation, jail, network consent, workerd pin, and distribution-tier decisions in that ADR remain in force.
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,
envbindings, 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 — seesql-database-contract.md).
-
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 nokind,methods.list, orsupportedRoles. 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 includestype,schema_versions,supports_suspend, andfilter(what the plugin receives). Operational knobsresource_classandmax_retriesare 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/0legacy JSON; they do not inherit the manifest.authority_revisionincludes consumers, jobs, and operator-controlled resource budgets. -
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.BindingscarriesEVENTS(EventPublisher), named[[databases]], config, secrets, and optionalWORK_FS. Per-jobinput/output/progress/canceltravel onJobController, not on open. -
Typed Cap'n Proto everywhere. Storefront, CLI, OIDC, remote-library, event, and job method payloads are Cap'n structs (generated TS interfaces / Python TypedDicts +
@internalcodecs). JSON remains only for plugin-specific extensible config and event payloads (bounded). In-band errors useresultunions (ok/err) withPluginErrorCodewire strings. -
SDK idioms mirror Workers. Authors extend
BookclerkEntrypoint(default export) with optionalevent(batch)/job(controller)triggers and export named*Entrypointclasses.EventMessagerecordsack/retry/reject/deadLetter/suspend.bookclerk-plugin typesgeneratesEnvfromplugin.toml. Native Rust guests implementPluginWorker+serveon stdio Cap'n RPC. -
env.EVENTS.publishreplacesHOST.notify. The hostEventPublisherforcessource= plugin id, intersects producers with the operator grant, requires / synthesizes dedup keys, caps payload size, and writes the library outbox. Consume is typedEventConsumer.eventwith at-least-once delivery; guests must be idempotent ondeduplicationKey. -
Workerd is the mandatory front door. The host spawns every plugin through
bookclerk-workerd. Isolate vs native-jail is a backend the launcher selects fromruntime. OnePOST /invokecarries Cap'n$Paramsbytes (headers name interface / method / bridge context / cap table); the trusted adapter dispatches to author classes or the native broker. Broker fast paths (AdapterDatabaseSession, byteSource) never enter JavaScript. Direct host↔native Cap'n Proto isSpawnTransport::DirectNativeDiagnosticonly (tests / diagnostics). -
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
databaseAdapteron native-behind-workerd). Path (b)'s OS confinement is the siblingNetPolicy::Denyjail the host starts next to the gateway (the launcher never nestsbookclerk-jail). Shared helpers incrates/bookclerk-workerd/tests/conformance.rsplusbookclerk-workerd-native-fixturekeep the transports honest. -
One network policy engine.
fetch(), workerdconnect(), and the native-behind-workerd socket proxy consume the sameEgressPolicy: fetch hosts, TCPhost+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 underNetPolicy::Denyand must use the SDK socket capability over an inheritedfd:/handle:mux; the launcher jail isLocalIpc(no IP socket; its egress leaves as host-checked tunnels). Grant mutation is live:plugin-grants.jsonchanges fence running vats immediately (vat shutdown + kill child + drop the socket proxy and granted channels), including CLI writes observed bybookclerkd. Idle mediated TCP is interrupted on the fence; enforcement does not wait for the next host RPC.grant_revision(persisted operator consent) is distinct fromauthority_revision(effective runtime grant after host overlays and clamped budgets) and fromconfiguration_revision(manifest / host-config hash). The grant watcher compares grant revisions only and retries malformed files without mass-fencing. -
Provenance-qualified identity. Durable consent, sessions, plugin state, and grants key on
PluginKey(canonical provenance + package + manifest id). Version and content hashes areArtifactIdentity, not the logical key. A bareid = "sqlite"confers no privilege; platform defaults require host-stamped provenance plus matching content hashes. -
No in-process product plugins.
bookclerk/bookclerkd/bookclerk-plugin-hostnever link ordinary plugin implementation crates, includingbookclerk-plugin-database-*. Database adapters own physical lowering behinddatabaseAdapter(openSession,dropUnit). Direct host↔native Cap'n Proto remainsDirectNativeDiagnosticonly. CI (scripts/check-plugin-architecture.sh) enforces this.
- Daemon / CLI / UI group plugins by handler family, not
PluginKind. - Echo examples and product guests are
api_version = 3only. - 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.mdis the author/operator handbook. - Every surface a guest can reach with bytes of its own is fuzzed per
Untrusted-input fuzzing: 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 indocs/contributing/fuzzing.md; a new entrypoint family or channel adds its target in the same change.
- Dual-stack support for
api_version = 2role factories orHOST.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).
Source: docs/adr/plugin-capabilities-v3.md at main · View as Markdown