@lambdot/host-cloudflare 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [[`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7), [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7)]:
+  - @lambdot/core@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+- Updated dependencies [[`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355)]:
+  - @lambdot/core@0.1.1
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/host-cloudflare-v0.0.1...host-cloudflare-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,157 @@
+# @lambdot/host-cloudflare
+
+A Cloudflare host integration: it embeds a composition into a worker by
+turning the worker's `env` — named KV namespaces, D1 databases, R2 buckets,
+Durable Object namespaces, and plain environment variables — into typed
+namespace values that feature plugins consume through the composition's
+visible context, plus state bridges that serve a `StateBackend` from a KV
+namespace or a Durable Object's own storage, and a server-side websocket hub
+for Durable Objects. The package is dependency-free (only
+`@lambdot/core`): the binding types are structural subsets of
+`@cloudflare/workers-types`, so real bindings from a worker's `env` are
+assignable as-is, and anything Cloudflare adds beyond them stays available
+through the consumer's own types.
+
+## Bindings as namespaces
+
+Cloudflare bindings are named — a worker binds several KV namespaces, D1
+databases, R2 buckets, and Durable Object namespaces under distinct names —
+so each provider factory takes its name as a parameter and instances
+multiply: compose `kvNamespace("sessions")` and `kvNamespace("cache")` side
+by side, exactly like `wsTransport` in `@lambdot/websocket`. Wiring a
+consumer before the provider it consumes is a compile error (the `mapping`
+parameter is typed as the namespaces visible so far), and `ctx.<name>` reads
+back typed with no casts. The config is just the binding as it arrives on
+the fetch handler's `env` argument, passed via `option`:
+`{ binding: env.SESSIONS }`.
+
+`envVars` is the Cloudflare counterpart of `envVars` in `@lambdot/env` —
+workers have no `process.env`, so plain vars and secrets arrive on `env`
+next to the resource bindings. Its config is `{ source: env }`; it reads
+the listed keys and emits them as a `Readonly<Record<TKey, string>>` under
+the name. A missing, empty, or non-string variable throws at start, so a
+misconfigured deployment surfaces before any consumer activates.
+
+## The KV state bridge
+
+`kvState(name)` bridges a KV namespace provided by `kvNamespace` into the
+framework's pluggable state shape: it consumes `{ kv: KVNamespace }` (wire
+it through a `mapping` from the `kvNamespace` namespace), wraps the
+namespace in a `StateBackend`, and emits it — typically under `"state"`, so
+feature plugins reach it by declaring `{ state: StateBackend }` in their
+input and building a typed view with `createStateAccessor(backend, name)`.
+Values are stored as JSON under `<plugin-namespace>:<key>`. KV expiries are
+whole seconds with a 60-second minimum, so a plugin's `ttlMs` is rounded up
+and clamped to that floor.
+
+## Durable Objects
+
+Three pieces cover Durable Objects, one per place the runtime surfaces
+them:
+
+- `durableObjectNamespace(name)` is the binding provider for the worker
+  side: `{ binding: env.ROOM }` via `option`, emitted under `name` exactly
+  like the KV/D1/R2 providers. Routing to an instance stays in the fetch
+  handler — `ctx.rooms.get(ctx.rooms.idFromName(name)).fetch(request)`.
+- `doState()` is the per-instance counterpart of `kvState`: a Durable
+  Object's transactional storage arrives on its constructor state rather
+  than on `env` (and each instance has exactly one), so it is passed to the
+  composition as config — `.bind(doState(), { option: { storage } })` — and
+  emitted under `"state"`, so feature plugins reach it by declaring
+  `{ state: StateBackend }` in their input (identity wiring). Values are
+  structured-cloneable (no JSON round trip) and there is no TTL, since
+  Durable Object storage has no expiry mechanism.
+- `wsHub(name)` is the server-side mirror of `wsTransport` in
+  `@lambdot/websocket`: instead of dialing out, the Durable Object accepts
+  incoming sockets. It returns a bundle — the hub the fetch handler accepts
+  `WebSocketPair` server ends into, and the plugin emitting that hub under
+  `name` — with the exact `WsConnection` shape, so the generic
+  `wsInput`/`wsOutput` halves (a `wsPlatform` bundle minus its transport)
+  drive it unchanged, wired by `mapping: (ctx) => ({ connection: ctx.room })`.
+  Where the transport owns one client socket, the hub
+  fans out: `send` broadcasts to every accepted socket, `onMessage`
+  receives from any of them. Create the hub per Durable Object instance,
+  never at module level — it keeps sockets and listeners in closures, and
+  co-resident instances share the isolate's module scope, so module-level
+  instances would cross-wire two rooms. Hold the hub in instance state and
+  boot the composition lazily in `fetch()` with `request.url`.
+
+## Usage
+
+From a worker's fetch handler — boot the composition once per isolate and
+reuse it (`start` is idempotent):
+
+```ts
+import type { StateBackend } from "@lambdot/core";
+import { createKernel, createStateAccessor, definePlugin } from "@lambdot/core";
+import type { KVNamespace } from "@lambdot/host-cloudflare";
+import { envVars, kvNamespace, kvState } from "@lambdot/host-cloudflare";
+
+// Declared as a `type` (not an `interface`) so the whole object stays
+// assignable to EnvVarsConfig["source"] — interfaces get no implicit
+// index signature.
+type Env = {
+    readonly PING_DEFAULT_MESSAGE: string;
+    readonly PINGS: KVNamespace;
+};
+
+const pingPong = definePlugin({
+    name: "ping-pong",
+    apply(input: { state: StateBackend }) {
+        const state = createStateAccessor<{ count: number }>(input.state, "ping-pong");
+        // ...
+    },
+});
+
+function createBot(env: Env) {
+    return (
+        createKernel()
+            .use(envVars("bot-env", ["PING_DEFAULT_MESSAGE"]), { option: { source: env } })
+            .bind(kvNamespace("pings"), { option: { binding: env.PINGS } })
+            .bind(kvState("state"), { mapping: (ctx) => ({ kv: ctx.pings }) })
+            // identity wiring: the bound "state" namespace feeds ping-pong
+            .use(pingPong)
+    );
+}
+```
+
+Consumers read `bot.ctx["bot-env"].PING_DEFAULT_MESSAGE` and
+`bot.ctx["ping-pong"]` typed through the composition; `bind` keeps the KV
+binding and the state backend internal to the chain (visible to `mapping`s,
+absent from the final `ctx`).
+
+## API
+
+Providers — each emits the binding (or snapshot) under its name:
+
+| Export                         | Config                         | Emits                                 |
+| ------------------------------ | ------------------------------ | ------------------------------------- |
+| `kvNamespace(name)`            | `KVNamespaceConfig`            | `KVNamespace` under `name`            |
+| `d1Database(name)`             | `D1DatabaseConfig`             | `D1Database` under `name`             |
+| `r2Bucket(name)`               | `R2BucketConfig`               | `R2Bucket` under `name`               |
+| `envVars(name, keys)`          | `EnvVarsConfig`                | `Readonly<Record<TKey, string>>`      |
+| `durableObjectNamespace(name)` | `DurableObjectNamespaceConfig` | `DurableObjectNamespace` under `name` |
+| `kvState(name)`                | none                           | `StateBackend` under `name`           |
+| `doState()`                    | `DoStorageConfig`              | `StateBackend` under `"state"`        |
+| `wsHub(name)`                  | `WsHubConfig`                  | `WebSocketHub` under `name`           |
+
+All configs are `{ binding: env.X }`-style (`EnvVarsConfig` is
+`{ source: env }`, `DoStorageConfig` is `{ storage }`) and are passed via
+`option`, which is required since the config types are non-void. `kvState`
+takes no config but declares `{ kv: KVNamespace }` as its input — wire it
+with a `mapping`. `wsHub` additionally returns the `hub` control face the
+fetch handler accepts sockets into.
+
+Binding types (`KVNamespace`, `D1Database`, `R2Bucket`,
+`DurableObjectNamespace`, `DurableObjectState` and their result/option
+types) are re-exported from `src/bindings.ts`.
+
+See [examples/cloudflare-bot](../../../examples/cloudflare-bot) for a
+complete worker — hono + a KV-backed counter running under miniflare — and
+[examples/durable-object-bot](../../../examples/durable-object-bot) for the
+Durable Object half: a websocket chat room per DO instance, driven by
+`wsHub` + `doState` under miniflare.
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,14 +1,19 @@
 {
-    "name": "@lambdot/host-cloudflare",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@lambdot/core": "workspace:*"
-    }
-}
+  "name": "@lambdot/host-cloudflare",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/host/cloudflare"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lambdot/core": "0.2.0"
+  }
+}

package/src/bindings.ts

@@ -136,3 +136,40 @@ export interface R2Bucket {
     delete(keys: string | readonly string[]): Promise<void>;
     list(options?: R2ListOptions): Promise<R2Objects>;
 }
+
+/* ---------------------------- Durable Objects ---------------------------- */
+
+/** A Durable Object id, minted by a {@link DurableObjectNamespace}. */
+export interface DurableObjectId {
+    toString(): string;
+    equals(other: DurableObjectId): boolean;
+}
+
+/** A stub talking to one Durable Object instance: the fetch entry only. */
+export interface DurableObjectStub {
+    fetch(request: Request): Promise<Response>;
+}
+
+/**
+ * The fundamental slice of a Durable Object namespace binding: name an
+ * instance, then talk to it through its stub.
+ */
+export interface DurableObjectNamespace {
+    idFromName(name: string): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStub;
+}
+
+/**
+ * The fundamental slice of a Durable Object's transactional storage:
+ * per-instance, structured-cloneable values, no JSON round trip needed.
+ */
+export interface DurableObjectStorage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+
+/** The slice of a Durable Object's constructor state the framework builds on. */
+export interface DurableObjectState {
+    readonly storage: DurableObjectStorage;
+}

package/src/durable-object.ts

@@ -0,0 +1,197 @@
+import type { Disposer, Plugin, StateBackend } from "@lambdot/core";
+import { definePlugin } from "@lambdot/core";
+
+import type { DurableObjectNamespace, DurableObjectStorage } from "./bindings.ts";
+
+/** Config for {@link durableObjectNamespace}: the binding as it arrives on the worker's `env`. */
+export interface DurableObjectNamespaceConfig {
+    readonly binding: DurableObjectNamespace;
+}
+
+/**
+ * Emit one named Durable Object namespace binding as the plugin's namespace
+ * value. Instances multiply by name, exactly like `kvNamespace`. Routing to
+ * an instance stays in the worker's fetch handler — read the namespace back
+ * from the composition's ctx:
+ *
+ * ```ts
+ * createKernel().use(durableObjectNamespace("rooms"), { option: { binding: env.ROOM } });
+ * // ctx.rooms.get(ctx.rooms.idFromName(name)).fetch(request)
+ * ```
+ */
+export function durableObjectNamespace<const TCap extends string>(
+    capability: TCap,
+): Plugin<void, DurableObjectNamespace, DurableObjectNamespaceConfig, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(_input, _scope, config) {
+            return config.binding;
+        },
+    });
+}
+
+/** Config for {@link doState}: the instance's storage, from the Durable Object's constructor state. */
+export interface DoStorageConfig {
+    readonly storage: DurableObjectStorage;
+}
+
+/**
+ * Bridge a Durable Object's own transactional storage into a pluggable
+ * `StateBackend` — the per-instance counterpart of `kvState`. The storage
+ * arrives on the Durable Object's constructor state rather than on `env`, so
+ * it is passed straight as config (each instance has exactly one). Emitted
+ * under `"state"`, so feature plugins reach it by declaring
+ * `{ state: StateBackend }` in their input (identity wiring):
+ *
+ * ```ts
+ * class Room extends DurableObject {
+ *     boot() {
+ *         return createKernel().bind(doState(), { option: { storage: this.ctx.storage } });
+ *     }
+ * }
+ * ```
+ *
+ * Keys are namespaced `<plugin-namespace>:<key>`. Values are
+ * structured-cloneable, so no JSON round trip is needed, and there is no
+ * TTL — Durable Object storage has no expiry mechanism. State is scoped to
+ * the instance: two names on one namespace never share a value.
+ */
+export function doState(): Plugin<void, StateBackend, DoStorageConfig, "state"> {
+    return definePlugin({
+        name: "state",
+        apply(_input, _scope, config) {
+            const backend: StateBackend = {
+                get: (ns, key) => config.storage.get(`${ns}:${key}`),
+                set: (ns, key, value) => config.storage.put(`${ns}:${key}`, value),
+                async delete(ns, key) {
+                    await config.storage.delete(`${ns}:${key}`);
+                },
+            };
+            return backend;
+        },
+    });
+}
+
+/**
+ * A server-side websocket hub: the exact shape of `WsConnection` in
+ * `@lambdot/websocket` (declared locally so the package keeps its single
+ * `@lambdot/core` dependency), so the generic `wsInput`/`wsOutput` factories
+ * consume it as-is through their `{ connection }` input. Where `wsTransport`
+ * owns one client socket, the hub fans out over every socket a Durable
+ * Object has accepted: `send` broadcasts, `onMessage` receives from any of
+ * them.
+ */
+export interface WebSocketHub {
+    readonly url: string;
+    /** Send a text frame to every accepted socket. */
+    send(data: string): void;
+    /** Subscribe to incoming text frames from any accepted socket. */
+    onMessage(listener: (data: string) => void): Disposer;
+}
+
+/**
+ * The handler face of a {@link wsHub} bundle, held by the Durable Object
+ * class: everything {@link WebSocketHub} exposes to plugins, plus the
+ * server-side `accept` the fetch handler calls with the server end of a
+ * `WebSocketPair`.
+ */
+export interface WebSocketHubControl extends WebSocketHub {
+    accept(socket: WebSocket): void;
+}
+
+/** Config for a {@link wsHub} plugin: the URL the hub serves, reported as `WsConnection["url"]`. */
+export interface WsHubConfig {
+    readonly url: string;
+}
+
+/** A {@link wsHub} bundle: the hub the Durable Object accepts sockets into, and the plugin emitting it. */
+export interface WsHub<TCap extends string> {
+    readonly hub: WebSocketHubControl;
+    readonly plugin: Plugin<void, WebSocketHub, WsHubConfig, TCap>;
+}
+
+/**
+ * The server-side mirror of `wsTransport`: instead of dialing out, a Durable
+ * Object accepts incoming sockets. `wsHub` returns the two halves of that —
+ * the hub the Durable Object's fetch handler accepts `WebSocketPair` server
+ * ends into, and the plugin that emits the hub as its namespace value, so
+ * the generic `wsInput`/`wsOutput` halves (a `wsPlatform` bundle minus its
+ * transport) drive it unchanged:
+ *
+ * ```ts
+ * class ChatRoom extends DurableObject {
+ *     private readonly room = wsHub("room");
+ *     private kernel: ReturnType<typeof createRoomKernel> | undefined;
+ *
+ *     async fetch(request: Request) {
+ *         this.kernel ??= createRoomKernel(this.room, request.url);
+ *         await this.kernel.start(); // `start` is idempotent
+ *         const pair = new WebSocketPair();
+ *         this.room.hub.accept(pair[1]);
+ *         return new Response(null, { status: 101, webSocket: pair[0] });
+ *     }
+ * }
+ *
+ * function createRoomKernel(room: WsHub<"room">, url: string) {
+ *     const chat = wsPlatform("dochat", chatSpec);
+ *     return createKernel()
+ *         .bind(room.plugin, { option: { url } })
+ *         .use(chat.input, { mapping: (ctx) => ({ connection: ctx.room }) })
+ *         .bind(chat.output, {
+ *             mapping: (ctx) => ({ connection: ctx.room, commands: ctx.reply }),
+ *         });
+ * }
+ * ```
+ *
+ * Create the hub **per Durable Object instance**, never at module level: it
+ * keeps sockets and listeners in closures, and co-resident instances share
+ * the isolate's module scope, so module-level instances would cross-wire two
+ * rooms (one room's broadcasts leaking into another's sockets). The
+ * instance's URL is only known per request, so hold the hub in instance
+ * state and boot the composition lazily in `fetch()` with `request.url`.
+ */
+export function wsHub<const TCap extends string>(capability: TCap): WsHub<TCap> {
+    const sockets = new Set<WebSocket>();
+    const listeners = new Set<(data: string) => void>();
+
+    // `url` is only known once the plugin activates with its config, so the
+    // hub object stays mutable behind the readonly connection face.
+    const hub = {
+        url: "",
+        send(data: string) {
+            for (const socket of sockets) socket.send(data);
+        },
+        onMessage(listener: (data: string) => void): Disposer {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        accept(socket: WebSocket) {
+            // `accept()` is the server-side workers extension: the global
+            // `WebSocket` type this package compiles against is the
+            // client-side one, so pin the call down structurally.
+            (socket as WebSocket & { accept(): void }).accept();
+            sockets.add(socket);
+            socket.addEventListener("message", (event) => {
+                if (typeof event.data === "string")
+                    for (const listener of listeners) listener(event.data);
+            });
+            const drop = () => {
+                sockets.delete(socket);
+            };
+            socket.addEventListener("close", drop);
+            socket.addEventListener("error", drop);
+        },
+    };
+
+    const plugin = definePlugin({
+        name: capability,
+        apply(_input, _scope, config: WsHubConfig) {
+            hub.url = config.url;
+            return hub as WebSocketHub;
+        },
+    });
+
+    return { hub, plugin };
+}

package/src/index.ts

@@ -1,4 +1,5 @@
-import type { Disposer, FeaturePlugin, StateBackend } from "@lambdot/core";
+import type { Plugin, StateBackend } from "@lambdot/core";
+import { definePlugin } from "@lambdot/core";
 
 import type { D1Database, KVNamespace, KVPutOptions, R2Bucket } from "./bindings.ts";
 
@@ -7,6 +8,11 @@ export type {
     D1ExecResult,
     D1PreparedStatement,
     D1Result,
+    DurableObjectId,
+    DurableObjectNamespace,
+    DurableObjectState,
+    DurableObjectStorage,
+    DurableObjectStub,
     KVListKey,
     KVListOptions,
     KVListResult,
@@ -20,30 +26,15 @@ export type {
     R2PutOptions,
     R2PutValue,
 } from "./bindings.ts";
-
-/**
- * The typed capability contracts shared by a binding provider and its
- * consumers, parameterized by capability name: the provider declares it as
- * `TProvides`, consumers as `TInjects`. Cloudflare bindings are named — a
- * worker binds several KV namespaces, D1 databases, and R2 buckets under
- * distinct names — so each provider instance takes its own capability name
- * and distinct names fold side by side
- * (`KVCapability<"sessions"> & KVCapability<"cache">`), exactly like
- * `WsCapability` in `@lambdot/websocket`.
- */
-export type KVCapability<TCap extends string> = { readonly [K in TCap]: KVNamespace };
-export type D1Capability<TCap extends string> = { readonly [K in TCap]: D1Database };
-export type R2Capability<TCap extends string> = { readonly [K in TCap]: R2Bucket };
-
-/**
- * The typed capability contract shared by an environment provider and its
- * consumers — the same shape as `EnvCapability` in `@lambdot/env`, declared
- * locally so the package stays dependency-free. The two are structurally
- * identical, so a consumer typed against either accepts both providers.
- */
-export type EnvCapability<TCap extends string, TKey extends string> = {
-    readonly [K in TCap]: Readonly<Record<TKey, string>>;
-};
+export type {
+    DoStorageConfig,
+    DurableObjectNamespaceConfig,
+    WebSocketHub,
+    WebSocketHubControl,
+    WsHub,
+    WsHubConfig,
+} from "./durable-object.ts";
+export { doState, durableObjectNamespace, wsHub } from "./durable-object.ts";
 
 /** Config for {@link kvNamespace}: the binding as it arrives on the worker's `env`. */
 export interface KVNamespaceConfig {
@@ -70,151 +61,129 @@ export interface EnvVarsConfig {
 }
 
 /**
- * Provide one named Workers KV namespace as a typed capability. Instances
- * multiply by capability name: register `kvNamespace("sessions")` and
- * `kvNamespace("cache")` side by side, and each consumer injects its own.
+ * Emit one named Workers KV namespace as the plugin's namespace value.
+ * Instances multiply by name: compose `kvNamespace("sessions")` and
+ * `kvNamespace("cache")` side by side, and each consumer wires its own
+ * through its mapping.
  *
  * ```ts
  * createKernel()
- *     .use(kvNamespace("sessions"), { binding: env.SESSIONS })
- *     .use(kvNamespace("cache"), { binding: env.CACHE });
+ *     .use(kvNamespace("sessions"), { option: { binding: env.SESSIONS } })
+ *     .use(kvNamespace("cache"), { option: { binding: env.CACHE } });
  * // ctx.sessions: KVNamespace, ctx.cache: KVNamespace
  * ```
  */
-export function kvNamespace<TCap extends string>(
+export function kvNamespace<const TCap extends string>(
     capability: TCap,
-): FeaturePlugin<{}, {}, undefined, KVNamespaceConfig, `kv:${TCap}`, KVCapability<TCap>> {
-    return {
-        name: `kv:${capability}`,
-        apply(ctx, config) {
-            // The kernel's `provide` keeps its value parameter behind a
-            // conditional type that stays deferred for a generic capability
-            // name; `KVCapability<TCap>` already ties this name to
-            // `KVNamespace`, so pin the call down here.
-            return (ctx.provide as (name: TCap, value: KVNamespace) => Disposer).call(
-                ctx,
-                capability,
-                config.binding,
-            );
+): Plugin<void, KVNamespace, KVNamespaceConfig, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(_input, _scope, config) {
+            return config.binding;
         },
-    };
+    });
 }
 
 /**
- * Provide one named D1 database as a typed capability. Instances multiply
- * by capability name, exactly like {@link kvNamespace}.
+ * Emit one named D1 database as the plugin's namespace value. Instances
+ * multiply by name, exactly like {@link kvNamespace}.
  *
  * ```ts
- * createKernel().use(d1Database("db"), { binding: env.DB });
+ * createKernel().use(d1Database("db"), { option: { binding: env.DB } });
  * // ctx.db: D1Database
  * ```
  */
-export function d1Database<TCap extends string>(
+export function d1Database<const TCap extends string>(
     capability: TCap,
-): FeaturePlugin<{}, {}, undefined, D1DatabaseConfig, `d1:${TCap}`, D1Capability<TCap>> {
-    return {
-        name: `d1:${capability}`,
-        apply(ctx, config) {
-            // See `kvNamespace` for why `provide` is pinned here.
-            return (ctx.provide as (name: TCap, value: D1Database) => Disposer).call(
-                ctx,
-                capability,
-                config.binding,
-            );
+): Plugin<void, D1Database, D1DatabaseConfig, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(_input, _scope, config) {
+            return config.binding;
         },
-    };
+    });
 }
 
 /**
- * Provide one named R2 bucket as a typed capability. Instances multiply by
- * capability name, exactly like {@link kvNamespace}.
+ * Emit one named R2 bucket as the plugin's namespace value. Instances
+ * multiply by name, exactly like {@link kvNamespace}.
  *
  * ```ts
- * createKernel().use(r2Bucket("uploads"), { binding: env.UPLOADS });
+ * createKernel().use(r2Bucket("uploads"), { option: { binding: env.UPLOADS } });
  * // ctx.uploads: R2Bucket
  * ```
  */
-export function r2Bucket<TCap extends string>(
+export function r2Bucket<const TCap extends string>(
     capability: TCap,
-): FeaturePlugin<{}, {}, undefined, R2BucketConfig, `r2:${TCap}`, R2Capability<TCap>> {
-    return {
-        name: `r2:${capability}`,
-        apply(ctx, config) {
-            // See `kvNamespace` for why `provide` is pinned here.
-            return (ctx.provide as (name: TCap, value: R2Bucket) => Disposer).call(
-                ctx,
-                capability,
-                config.binding,
-            );
+): Plugin<void, R2Bucket, R2BucketConfig, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(_input, _scope, config) {
+            return config.binding;
         },
-    };
+    });
 }
 
 /**
- * Read variables from a worker's bindings object and provide them as a
- * typed capability — the Cloudflare counterpart of `envVars` in
+ * Read variables from a worker's bindings object and emit them as the
+ * plugin's namespace value — the Cloudflare counterpart of `envVars` in
  * `@lambdot/env`: workers have no `process.env`, so plain vars and secrets
  * arrive on `env` next to the resource bindings. A missing, empty, or
- * non-string variable fails activation loudly at kernel start, so a
- * misconfigured deployment surfaces before any consumer activates.
+ * non-string variable fails activation loudly at start, so a misconfigured
+ * deployment surfaces before any consumer activates.
  *
  * ```ts
- * createKernel().use(envVars("bot-env", ["BOT_TOKEN"]), { source: env });
+ * createKernel().use(envVars("bot-env", ["BOT_TOKEN"]), { option: { source: env } });
  * // ctx["bot-env"].BOT_TOKEN: string
  * ```
  */
-export function envVars<TCap extends string, TKey extends string>(
+export function envVars<const TCap extends string, const TKey extends string>(
     capability: TCap,
     keys: readonly TKey[],
-): FeaturePlugin<{}, {}, undefined, EnvVarsConfig, `env:${TCap}`, EnvCapability<TCap, TKey>> {
-    return {
-        name: `env:${capability}`,
-        apply(ctx, config) {
+): Plugin<void, Readonly<Record<TKey, string>>, EnvVarsConfig, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(_input, _scope, config) {
             const values: Record<string, string> = {};
             for (const key of keys) {
                 const value = config.source[key];
                 if (typeof value !== "string" || value === "")
                     throw new Error(
-                        `env:${capability}: required environment variable "${key}" is not set`,
+                        `${capability}: required environment variable "${key}" is not set`,
                     );
                 values[key] = value;
             }
-            // See `kvNamespace` for why `provide` is pinned here.
-            return (
-                ctx.provide as (name: TCap, value: Readonly<Record<TKey, string>>) => Disposer
-            ).call(ctx, capability, values as Readonly<Record<TKey, string>>);
+            return values as Readonly<Record<TKey, string>>;
         },
-    };
+    });
 }
 
 /**
- * Bridge a named Workers KV namespace into the framework's pluggable state
- * slot, so feature plugins reach it through `ctx.state`. Injects the
- * capability provided by {@link kvNamespace} — the fold enforces
- * registration order at compile time:
+ * Bridge a Workers KV namespace into a pluggable `StateBackend`, so stateful
+ * features can build typed accessors with `createStateAccessor`. Wire the KV
+ * binding through the mapping:
  *
  * ```ts
  * createKernel()
- *     .use(kvNamespace("kv"), { binding: env.BOT_KV })
- *     .use(kvState("kv"))
- *     .use(myStatefulFeature);
+ *     .bind(kvNamespace("pings"), { option: { binding: env.PINGS } })
+ *     .use(kvState("state"), { mapping: (ctx) => ({ kv: ctx.pings }) })
+ *     .use(myStatefulFeature); // declares { state: StateBackend } — identity wiring
  * ```
  *
  * Values are stored as JSON under `<plugin-namespace>:<key>`. KV expiries
  * are whole seconds with a 60-second minimum, so `ttlMs` is rounded up and
  * clamped to that floor.
  */
-export function kvState<TCap extends string>(
+export function kvState<const TCap extends string>(
     capability: TCap,
-): FeaturePlugin<{}, {}, undefined, void, `state-kv:${TCap}`, {}, KVCapability<TCap>> {
-    return {
-        name: `state-kv:${capability}`,
-        inject: [capability],
-        apply(ctx) {
-            const binding = ctx[capability];
+): Plugin<{ kv: KVNamespace }, StateBackend, void, TCap> {
+    return definePlugin({
+        name: capability,
+        apply(input) {
+            const { kv } = input;
             const backend: StateBackend = {
                 async get(ns, key) {
-                    const value = await binding.get(`${ns}:${key}`, { type: "json" });
+                    const value = await kv.get(`${ns}:${key}`, { type: "json" });
                     return value === null ? undefined : value;
                 },
                 async set(ns, key, value, ttlMs) {
@@ -222,13 +191,13 @@ export function kvState<TCap extends string>(
                         ttlMs === undefined
                             ? {}
                             : { expirationTtl: Math.max(60, Math.ceil(ttlMs / 1000)) };
-                    await binding.put(`${ns}:${key}`, JSON.stringify(value), options);
+                    await kv.put(`${ns}:${key}`, JSON.stringify(value), options);
                 },
                 async delete(ns, key) {
-                    await binding.delete(`${ns}:${key}`);
+                    await kv.delete(`${ns}:${key}`);
                 },
             };
-            return ctx.provide("state", backend);
+            return backend;
         },
-    };
+    });
 }