@moku-labs/worker 0.1.0

package/dist/storage-BaQ6BBtl.cjs

@@ -0,0 +1,990 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let _moku_labs_common = require("@moku-labs/common");
+let _moku_labs_core = require("@moku-labs/core");
+/**
+* stage core plugin — deployment-stage / dev-mode detection, flat-injected on
+* every regular plugin's context as `ctx.stage` (spec/02 §6). No state, no
+* events, no depends, no lifecycle hooks.
+*
+* @see README.md
+* @example
+* ```typescript
+* // Inside any regular plugin's api factory:
+* api: (ctx) => ({
+*   errorBody: (e: Error) =>
+*     ctx.stage.isDev() ? e.stack ?? e.message : "Internal Error",
+* })
+* ```
+*/
+const stagePlugin = (0, _moku_labs_core.createCorePlugin)("stage", {
+	config: { stage: "production" },
+	/**
+	* Builds the stage accessor surface from the resolved stage.
+	*
+	* @param ctx - Core plugin context (spec/02 §6 — `{ config, state }` only;
+	*   no `global`, `emit`, or `require`). `state` is unused by this plugin.
+	* @param ctx.config - The resolved plugin config containing the deployment stage.
+	* @returns The `ctx.stage` API: `isDev`, `isProduction`, `current`.
+	* @example
+	* ```typescript
+	* const api = stagePlugin.spec.api({ config: { stage: "development" }, state: {} });
+	* api.isDev(); // true
+	* ```
+	*/
+	api: ({ config }) => ({
+		/**
+		* Whether this Worker runs in the development stage.
+		*
+		* @returns True iff `stage === "development"`.
+		* @example
+		* ```typescript
+		* if (ctx.stage.isDev()) return Response.json({ stack: err.stack });
+		* ```
+		*/
+		isDev: () => config.stage === "development",
+		/**
+		* Whether this Worker runs in the production stage. Note: false in "test".
+		*
+		* @returns True iff `stage === "production"`.
+		* @example
+		* ```typescript
+		* const cc = ctx.stage.isProduction() ? "public, max-age=31536000" : "no-store";
+		* ```
+		*/
+		isProduction: () => config.stage === "production",
+		/**
+		* The raw deployment stage, as the literal union (not `string`).
+		*
+		* @returns The resolved stage.
+		* @example
+		* ```typescript
+		* ctx.log.info("startup", { stage: ctx.stage.current() });
+		* ```
+		*/
+		current: () => config.stage
+	})
+});
+const coreConfig = (0, _moku_labs_core.createCoreConfig)("moku-worker", {
+	config: {
+		stage: "production",
+		name: "moku-worker",
+		compatibilityDate: ""
+	},
+	plugins: [
+		_moku_labs_common.logPlugin,
+		_moku_labs_common.envPlugin,
+		stagePlugin
+	]
+});
+const { createPlugin, createCore } = coreConfig;
+//#endregion
+//#region src/plugins/bindings/index.ts
+/**
+* Checks whether a value read from an env object is nullish (null or undefined).
+* Cloudflare supplies either form when a binding is absent, so both must be caught.
+*
+* @param value - The value read from the env object.
+* @returns True when the value is null or undefined.
+* @example
+* ```typescript
+* isNullish(undefined); // true
+* isNullish(0);         // false — falsy but bound
+* ```
+*/
+const isNullish = (value) => value === void 0 || value === null;
+/**
+* Resolves binding `name` off a request-supplied env object, narrowed to T.
+* Throws a `[moku-worker]`-prefixed error when the binding is nullish.
+* The env argument is read but never retained.
+*
+* @param env - The Cloudflare request env object passed to fetch/scheduled/queue.
+* @param name - The binding name to resolve.
+* @returns The binding value narrowed to T.
+* @throws {Error} With a `[moku-worker]` prefix when the binding is null or undefined.
+* @example
+* ```typescript
+* const kv = requireBinding<KVNamespace>(env, "MY_KV");
+* ```
+*/
+const requireBinding = (env, name) => {
+	const value = env[name];
+	if (isNullish(value)) throw new Error(`[moku-worker] binding "${name}" is not bound.\n  Declare it in wrangler config and pass it in via the request env.`);
+	return value;
+};
+/**
+* Returns true when `name` resolves to a non-nullish value on the request env.
+* Never throws. Use for optional-binding branching without forcing an error.
+*
+* @param env - The Cloudflare request env object passed to fetch/scheduled/queue.
+* @param name - The binding name to check.
+* @returns Whether the binding is present and non-nullish.
+* @example
+* ```typescript
+* const ok = hasBinding(env, "DB"); // false if DB is not bound
+* ```
+*/
+const hasBinding = (env, name) => !isNullish(env[name]);
+/**
+* Builds the app.bindings API surface. The factory receives a context but does
+* not use it — bindings holds no state (F4) and all resolution is argument-local.
+*
+* @param _ctx - Plugin context (unused; bindings is stateless — F4).
+* @returns BindingsApi with `require` and `has` methods.
+* @example
+* ```typescript
+* const api = createBindingsApi(ctx);
+* const kv = api.require<KVNamespace>(env, "MY_KV");
+* ```
+*/
+const createBindingsApi = (_ctx) => ({
+	require: requireBinding,
+	has: hasBinding
+});
+/**
+* Micro-tier stateless resolver — the binding-family dependency root.
+*
+* Exposes `require<T>(env, name)` and `has(env, name)` off a per-request env
+* object. Regular plugin so downstream binding plugins can declare
+* `depends: [bindingsPlugin]` and reach it via `ctx.require(bindingsPlugin)`.
+*
+* @see README.md
+*/
+const bindingsPlugin = createPlugin("bindings", {
+	config: { required: [] },
+	api: createBindingsApi
+});
+//#endregion
+//#region src/plugins/d1/api.ts
+/**
+* Create the d1 api. Each method resolves the D1Database off the request
+* `env` via the bindings plugin, then forwards to the native D1 call. The
+* binding is never cached, so concurrent requests stay isolated (SB4).
+*
+* The return is intentionally NOT annotated `: Api`. Annotating it would
+* collapse the per-method call-site generic `<T>` on `query`/`first` to
+* `unknown`; instead the implementation forwards `<T>` to `all<T>()` /
+* `first<T>()` and `types.ts#Api` remains the public-surface source of truth.
+*
+* @param {D1Ctx} ctx - Plugin context (own config + require).
+* @returns {object} The d1 public api (query, first, run, batch, prepare, deployManifest).
+* @example
+* ```typescript
+* const api = createD1Api(ctx);
+* const { results } = await api.query<Product>(env, "SELECT * FROM products");
+* ```
+*/
+const createD1Api = (ctx) => {
+	const db = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	return {
+		/**
+		* Run a statement and return all rows. Forwards the call-site generic to
+		* `all<T>()` so the result type is not widened to `unknown`.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<D1Result<T>>} All rows (`.results` is `T[]`).
+		* @example
+		* ```typescript
+		* const { results } = await api.query<Product>(env, "SELECT * FROM products WHERE active = ?", 1);
+		* ```
+		*/
+		query: (env, sql, ...params) => db(env).prepare(sql).bind(...params).all(),
+		/**
+		* Run a statement and return the first row, or `null` if there are none.
+		* Forwards the call-site generic to `first<T>()`.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<T | null>} The first row, or `null` if none matched.
+		* @example
+		* ```typescript
+		* const row = await api.first<Product>(env, "SELECT * FROM products WHERE id = ?", id);
+		* ```
+		*/
+		first: (env, sql, ...params) => db(env).prepare(sql).bind(...params).first(),
+		/**
+		* Run a write/DDL statement (INSERT/UPDATE/DELETE/DDL) and return the
+		* D1 result carrying `.meta` (e.g. `rows_written`, `last_row_id`).
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<D1Result>} Result carrying `.meta`.
+		* @example
+		* ```typescript
+		* const res = await api.run(env, "INSERT INTO products (name) VALUES (?)", name);
+		* const id = res.meta.last_row_id;
+		* ```
+		*/
+		run: (env, sql, ...params) => db(env).prepare(sql).bind(...params).run(),
+		/**
+		* Execute caller-built prepared statements atomically in one round-trip,
+		* returning one result per statement in order.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {D1PreparedStatement[]} stmts - Statements built from prepare(env).
+		* @returns {Promise<D1Result[]>} One result per statement, order preserved.
+		* @example
+		* ```typescript
+		* const handle = api.prepare(env);
+		* await api.batch(env, [handle.prepare("INSERT INTO a VALUES (1)").bind()]);
+		* ```
+		*/
+		batch: (env, stmts) => db(env).batch(stmts),
+		/**
+		* Resolve the request-scoped D1Database so callers can build prepared
+		* statements for batch(). Issues no query itself.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @returns {D1Database} The request-resolved database handle.
+		* @example
+		* ```typescript
+		* const handle = api.prepare(env);
+		* const stmt = handle.prepare("SELECT * FROM t").bind();
+		* ```
+		*/
+		prepare: (env) => db(env),
+		/**
+		* Return this plugin's deploy metadata for the deploy plugin to read.
+		* Build-time only — takes no `env`. The return is typed `DeployManifest`
+		* (from types.ts), which pins `kind` to the literal `"d1"` without an
+		* inline `as` assertion.
+		*
+		* @returns {DeployManifest} Deploy manifest entry `{ kind: "d1", binding, migrations }`.
+		* @example
+		* ```typescript
+		* const m = api.deployManifest();
+		* // => { kind: "d1", binding: "DB", migrations: "./migrations" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "d1",
+			binding: ctx.config.binding,
+			migrations: ctx.config.migrations
+		})
+	};
+};
+/**
+* Standard tier — Cloudflare D1 SQL access (thin typed wrappers, not an ORM).
+*
+* Exposes `query`, `first`, `run`, `batch`, `prepare`, and `deployManifest`.
+* Resolves the D1 binding off the per-request `env` via the bindings plugin.
+* No state, no events, no lifecycle hooks (request-scoped, spec/06 §3).
+*
+* @see README.md
+*/
+const d1Plugin = createPlugin("d1", {
+	depends: [bindingsPlugin],
+	config: {
+		binding: "DB",
+		migrations: ""
+	},
+	api: (ctx) => createD1Api(ctx)
+});
+//#endregion
+//#region src/plugins/durable-objects/api.ts
+/**
+* Builds the `app.durableObjects` API surface — `get` and `deployManifest`.
+*
+* All namespace resolution uses the per-call `env` argument: `env` is threaded, never
+* stored (SB4 / design §1a). The config bindings map is frozen and read-only. No state
+* is held on the plugin between calls (stateless — `Record<string, never>`).
+*
+* @param ctx - Plugin context with `config.bindings`, `require(bindingsPlugin)`, and core APIs.
+* @returns The durableObjects API: `{ get, deployManifest }`.
+* @example
+* ```typescript
+* const api = createDoApi(ctx);
+* const stub = api.get(env, "counter", "room-42");
+* const manifest = api.deployManifest(); // { kind: "do", bindings: { counter: "COUNTER" } }
+* ```
+*/
+const createDoApi = (ctx) => ({
+	/**
+	* Resolves a `DurableObjectStub` off the per-request env.
+	*
+	* Maps `logicalName` → `config.bindings[logicalName]` (falling back to `logicalName`
+	* itself when unmapped), derives a deterministic id via `namespace.idFromName(idName)`,
+	* and returns the addressed stub. Synchronous — returns a stub, not a Promise.
+	* Throws (via the bindings resolver) when the binding is not present on `env`.
+	*
+	* @param env - Per-request Cloudflare bindings object (Worker fetch/queue/scheduled env).
+	* @param logicalName - Logical DO name used in code (e.g. `"counter"`).
+	* @param idName - Stable id name passed to `idFromName` (e.g. `"room-42"`).
+	* @returns The addressed `DurableObjectStub`.
+	* @throws {Error} With `[moku-worker]` prefix when the binding is not bound on `env`.
+	* @example
+	* ```typescript
+	* const stub = app.durableObjects.get(env, "counter", "room-42");
+	* const res = await stub.fetch("https://do/increment");
+	* ```
+	*/
+	get: (env, logicalName, idName) => {
+		const binding = ctx.config.bindings[logicalName] ?? logicalName;
+		const ns = ctx.require(bindingsPlugin).require(env, binding);
+		return ns.get(ns.idFromName(idName));
+	},
+	/**
+	* Returns this plugin's deploy metadata — read by the `deploy` plugin via
+	* `ctx.require(durableObjectsPlugin)`. Never reads sibling `pluginConfigs` (F6;
+	* spec/08 §5, §7). Pure synchronous read of `ctx.config.bindings`.
+	*
+	* @returns `{ kind: "do", bindings }` reflecting the frozen plugin config.
+	* @example
+	* ```typescript
+	* const manifest = app.durableObjects.deployManifest();
+	* // → { kind: "do", bindings: { counter: "COUNTER" } }
+	* ```
+	*/
+	deployManifest: () => ({
+		kind: "do",
+		bindings: ctx.config.bindings
+	})
+});
+//#endregion
+//#region src/plugins/durable-objects/helpers.ts
+/**
+* Returns a base class the consumer extends and exports from `worker.ts`.
+*
+* PURE (spec/03 §1): takes no `ctx`, has no side effects, and may be called before
+* `createApp`. The static `doName` property captures `name` for diagnostics and
+* binding correlation. The constructor stores `(state, env)` as `this.ctx` / `this.env`,
+* satisfying the Cloudflare Durable Object constructor contract. The plugin NEVER
+* generates the final exported class — the consumer owns that class.
+*
+* @param name - Logical DO name; captured as `static doName` for diagnostics.
+* @returns A base class (constructor) the consumer extends.
+* @example
+* ```typescript
+* // src/counter.ts
+* import { defineDurableObject } from "@moku-labs/worker";
+*
+* export class Counter extends defineDurableObject("Counter") {
+*   async fetch(): Promise<Response> {
+*     const n = ((await this.ctx.storage.get<number>("n")) ?? 0) + 1;
+*     await this.ctx.storage.put("n", n);
+*     return Response.json({ n });
+*   }
+* }
+* ```
+*/
+const defineDurableObject = (name) => {
+	/**
+	* Base implementation of the Cloudflare Durable Object constructor contract.
+	* Stores `(ctx, env)` as readonly properties for consumer subclasses to use.
+	*/
+	class DurableObjectBaseImpl {
+		/**
+		* Cloudflare per-object storage/alarm context (DurableObjectState).
+		* Use `this.ctx.storage` to read/write durable storage and `this.ctx.id` to inspect the DO id.
+		*/
+		ctx;
+		/**
+		* Per-object Cloudflare bindings (per-request WorkerEnv).
+		* Mirrors the env passed at construction time; never cached across requests.
+		*/
+		env;
+		/**
+		* Logical DO name captured from `defineDurableObject(name)`.
+		* Used for diagnostics and binding correlation.
+		*/
+		static doName = name;
+		/**
+		* Constructs the base Durable Object with Cloudflare's required signature.
+		*
+		* @param ctx - Cloudflare DurableObjectState (storage, id, blockConcurrencyWhile, …).
+		* @param env - Per-request Cloudflare bindings object (WorkerEnv).
+		* @example
+		* ```typescript
+		* class Counter extends Base {
+		*   constructor(ctx: DurableObjectState, env: WorkerEnv) { super(ctx, env); }
+		* }
+		* ```
+		*/
+		constructor(ctx, env) {
+			this.ctx = ctx;
+			this.env = env;
+		}
+	}
+	return DurableObjectBaseImpl;
+};
+/**
+* Cloudflare Durable Objects plugin — Standard tier.
+*
+* Exposes `get(env, logicalName, idName)` (synchronous stub accessor, threaded env) and
+* `deployManifest()` (build-time metadata). Depends on `bindingsPlugin` for namespace
+* resolution. The `defineDurableObject` helper is mounted under `helpers` and re-exported
+* at the top level for consumer use.
+*
+* @example
+* ```typescript
+* // Consumer endpoint handler:
+* const stub = app.durableObjects.get(env, "counter", params.room!);
+* const res = await stub.fetch("https://do/increment");
+* // Consumer DO class:
+* export class Counter extends defineDurableObject("Counter") {
+*   async fetch(): Promise<Response> { return new Response("ok"); }
+* }
+* ```
+* @see README.md
+*/
+const durableObjectsPlugin = createPlugin("durableObjects", {
+	depends: [bindingsPlugin],
+	config: { bindings: {} },
+	api: createDoApi,
+	helpers: { defineDurableObject }
+});
+//#endregion
+//#region src/plugins/kv/api.ts
+/**
+* Builds the app.kv.* api. Resolves the KV namespace off the REQUEST-SUPPLIED env
+* on every call — env is threaded, never stored (design §1a / SB4).
+*
+* @param ctx - The kv plugin context (own config + merged events).
+* @returns The app.kv api: get / put / delete / list / deployManifest.
+* @example
+* ```typescript
+* const api = createKvApi(ctx);
+* const value = await api.get(env, "key");
+* ```
+*/
+const createKvApi = (ctx) => {
+	const ns = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	return {
+		/**
+		* Reads a value by key from the KV namespace. Returns null when absent.
+		*
+		* @param env - The per-request Cloudflare env (threaded, never stored).
+		* @param key - The key to read.
+		* @returns The stored value, or null when absent.
+		* @example
+		* ```typescript
+		* const value = await api.get(env, "feature-flags");
+		* ```
+		*/
+		get: async (env, key) => ns(env).get(key),
+		/**
+		* Writes a string value under a key, optionally with KV put options.
+		*
+		* @param env - The per-request Cloudflare env.
+		* @param key - The key to write.
+		* @param value - The string value to store.
+		* @param opts - Optional expiration / metadata.
+		* @returns Resolves once the write is acknowledged.
+		* @example
+		* ```typescript
+		* await api.put(env, "session:1", "data", { expirationTtl: 3600 });
+		* ```
+		*/
+		put: async (env, key, value, opts) => ns(env).put(key, value, opts),
+		/**
+		* Removes a key from the namespace (no-op if absent).
+		*
+		* @param env - The per-request Cloudflare env.
+		* @param key - The key to delete.
+		* @returns Resolves once the delete is acknowledged.
+		* @example
+		* ```typescript
+		* await api.delete(env, "session:expired");
+		* ```
+		*/
+		delete: async (env, key) => ns(env).delete(key),
+		/**
+		* Lists keys in the namespace, optionally filtered/paginated via opts.
+		*
+		* @param env - The per-request Cloudflare env.
+		* @param opts - Optional prefix / cursor / limit.
+		* @returns The list result from the KV namespace.
+		* @example
+		* ```typescript
+		* const { keys } = await api.list(env, { prefix: "session:" });
+		* ```
+		*/
+		list: async (env, opts) => ns(env).list(opts),
+		/**
+		* Returns this plugin's own deploy metadata, read by the deploy plugin via
+		* require (design §6 / F6). Build-time only — takes no env.
+		*
+		* @returns The kv deploy descriptor with kind literal and binding name.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // { kind: "kv", binding: "KV" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "kv",
+			binding: ctx.config.binding
+		})
+	};
+};
+/**
+* Micro tier — thin env-first wrapper over a Cloudflare KV namespace.
+*
+* Resolves the KV namespace per request via `ctx.require(bindingsPlugin)`;
+* never stores env in state (design §1a / SB4). No lifecycle hooks —
+* request-scoped; nothing to open or close.
+*
+* @see README.md
+*/
+const kvPlugin = createPlugin("kv", {
+	depends: [bindingsPlugin],
+	config: { binding: "KV" },
+	api: createKvApi
+});
+//#endregion
+//#region src/plugins/queues/api.ts
+/**
+* @file queues plugin — API factory (send, sendBatch, consume, deployManifest).
+*
+* All binding-resolving methods take the per-request `env` as the first argument
+* and resolve the `Queue` via `ctx.require(bindingsPlugin).require<Queue>(env, name)`.
+* The `env` is never stored (SB4 / design §1a) — resolved fresh on every call.
+*/
+/**
+* Builds app.queues.* — read by worker.ts queue() delegation (design §1d; spec/02 §7).
+*
+* Resolves Queue bindings off the request env per call (never stored — SB4).
+* Emits `queue:message` for observability after each consumed message (F8).
+*
+* @param ctx - Plugin context (own config + require + emit).
+* @returns The queues API surface: send, sendBatch, consume, deployManifest.
+* @example
+* ```ts
+* // Worker entry (design §1d)
+* export default {
+*   queue: (b, e, c) => app.queues.consume(b, e, c),
+* };
+* ```
+*/
+const createQueuesApi = (ctx) => {
+	/**
+	* Resolves a named Queue binding from the per-request env.
+	* Throws a [moku-worker]-prefixed error when the binding is absent.
+	*
+	* @param env - Per-request Cloudflare bindings.
+	* @param name - Queue binding name.
+	* @returns The resolved Queue instance.
+	* @example
+	* ```ts
+	* const q = queue(env, "ORDERS");
+	* ```
+	*/
+	const queue = (env, name) => ctx.require(bindingsPlugin).require(env, name);
+	return {
+		/**
+		* Enqueue a single message onto the named queue.
+		*
+		* Resolves the Queue binding fresh from `env` on every call (SB4).
+		* Request/response work → api method, never emit (F8).
+		*
+		* @param env - Per-request Cloudflare bindings object.
+		* @param q - Target queue binding name in `env`.
+		* @param body - Message body to enqueue.
+		* @returns Resolves once the message is enqueued.
+		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
+		* @example
+		* ```ts
+		* await app.queues.send(env, "ORDERS", { orderId: "123" });
+		* ```
+		*/
+		send: async (env, q, body) => {
+			await queue(env, q).send(body);
+		},
+		/**
+		* Enqueue many messages in one call; each element becomes one message.
+		*
+		* Maps each body to `{ body }` before calling `Queue.sendBatch` (design §4.3).
+		*
+		* @param env - Per-request Cloudflare bindings object.
+		* @param q - Target queue binding name in `env`.
+		* @param bodies - Array of message bodies; each becomes one message.
+		* @returns Resolves once all messages are enqueued.
+		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
+		* @example
+		* ```ts
+		* await app.queues.sendBatch(env, "ORDERS", orders);
+		* ```
+		*/
+		sendBatch: async (env, q, bodies) => {
+			await queue(env, q).sendBatch(bodies.map((body) => ({ body })));
+		},
+		/**
+		* Consumer dispatch — the Worker's `queue()` export delegates here.
+		*
+		* Iterates `batch.messages`, **awaits** `config.onMessage(message, env)` per message
+		* (so Cloudflare gets a settled promise and the handler controls ack/retry; F8,
+		* spec/07 §3 — never emit for awaited work), then fire-and-forget emits `queue:message`
+		* for observability. Returns a promise the Worker **must** await so the isolate is not
+		* killed mid-batch.
+		*
+		* @param batch - The incoming message batch from Cloudflare.
+		* @param env - Per-request Cloudflare bindings object.
+		* @param _exec - waitUntil / passThroughOnException (reserved for future use).
+		* @returns Resolves after all messages in the batch are processed.
+		* @throws {Error} Re-throws any error from `config.onMessage` so Cloudflare can retry.
+		* @example
+		* ```ts
+		* // Worker entry
+		* queue: (b, e, c) => app.queues.consume(b, e, c),
+		* ```
+		*/
+		consume: async (batch, env, _exec) => {
+			for (const m of batch.messages) {
+				await ctx.config.onMessage(m, env);
+				ctx.emit("queue:message", {
+					queue: batch.queue,
+					messageId: m.id
+				});
+			}
+		},
+		/**
+		* Returns this plugin's deploy metadata, read by the deploy plugin via
+		* `ctx.require(queuesPlugin).deployManifest()` (F6 — never reads sibling config).
+		*
+		* @returns Deploy manifest entry `{ kind: "queue", producers }`.
+		* @example
+		* ```ts
+		* const manifest = ctx.require(queuesPlugin).deployManifest();
+		* // → { kind: "queue", producers: ["orders"] }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "queue",
+			producers: ctx.config.producers
+		})
+	};
+};
+/**
+* Standard tier — Cloudflare Queues producer + consumer dispatch.
+*
+* `events` is declared first and via `register.map<QueueEvents>` so the plugin's own events infer
+* into the factory context; the api wiring is therefore arrow-wrapped (contextually typed).
+*
+* @see README.md
+*/
+const queuesPlugin = createPlugin("queues", {
+	events: (register) => register.map({ "queue:message": "A queue message was processed" }),
+	depends: [bindingsPlugin],
+	config: {
+		producers: [],
+		onMessage: async () => {}
+	},
+	api: (ctx) => createQueuesApi(ctx)
+});
+//#endregion
+//#region src/plugins/storage/providers/r2.ts
+/**
+* Build a StorageProvider backed by the real R2Bucket resolved off the
+* per-request env via the bindings plugin. The bucket is resolved fresh on
+* EVERY method call — never cached, so concurrent requests stay isolated
+* (worker-api-design SB4; spec/08 §6).
+*
+* Each method is `async` so that synchronous throws from `bindings.require`
+* (e.g. missing binding) are automatically wrapped in rejected Promises —
+* callers can always use `await` / `.catch` instead of `try/catch`.
+*
+* @param bindings - The bindings plugin API (provides `require<T>`).
+* @param env - The per-request Cloudflare bindings object.
+* @param bucket - The R2 bucket binding name (e.g. "ASSETS").
+* @returns {StorageProvider} A provider that delegates to the resolved R2Bucket.
+* @example
+* ```typescript
+* const provider = resolveR2Provider(ctx.require(bindingsPlugin), env, ctx.config.bucket);
+* const body = await provider.get("my-object");
+* ```
+*/
+const resolveR2Provider = (bindings, env, bucket) => {
+	/**
+	* Resolve the R2Bucket for this request's env. Throws on missing binding.
+	*
+	* @returns {R2Bucket} The resolved R2Bucket binding.
+	* @example
+	* ```typescript
+	* const bucket = b();
+	* ```
+	*/
+	const b = () => bindings.require(env, bucket);
+	return {
+		/**
+		* Read an object from the bucket.
+		*
+		* @param key - The object key.
+		* @returns {Promise<R2ObjectBody | null>} The R2ObjectBody, or null if the key is absent.
+		* @example
+		* ```typescript
+		* const body = await provider.get("assets/logo.png");
+		* ```
+		*/
+		async get(key) {
+			return b().get(key);
+		},
+		/**
+		* Write an object to the bucket.
+		*
+		* @param key - The object key.
+		* @param value - The object contents (any R2-accepted type).
+		* @returns {Promise<R2Object>} The R2Object metadata for the written object.
+		* @example
+		* ```typescript
+		* const obj = await provider.put("assets/logo.png", buffer);
+		* ```
+		*/
+		async put(key, value) {
+			return b().put(key, value);
+		},
+		/**
+		* Remove one or more objects from the bucket. No-op when a key is absent.
+		*
+		* @param key - A single key or array of keys to remove.
+		* @returns {Promise<void>} Resolves once removed.
+		* @example
+		* ```typescript
+		* await provider.delete("assets/old.png");
+		* ```
+		*/
+		async delete(key) {
+			return b().delete(key);
+		},
+		/**
+		* List objects, optionally filtered by R2ListOptions.
+		*
+		* @param opts - Optional list options (prefix, limit, cursor, delimiter).
+		* @returns {Promise<R2Objects>} The R2Objects list result.
+		* @example
+		* ```typescript
+		* const { objects } = await provider.list({ prefix: "images/" });
+		* ```
+		*/
+		async list(opts) {
+			return b().list(opts);
+		}
+	};
+};
+//#endregion
+//#region src/plugins/storage/api.ts
+/**
+* Build the env-first storage API. Each runtime method resolves the bucket
+* provider fresh from the per-request `env` — nothing is stored, so concurrent
+* requests stay isolated (worker-api-design SB4; spec/08 §6,§7).
+*
+* The `deployManifest()` method is build-time only: it reads from `ctx.config`
+* and never touches `env` or R2.
+*
+* @param ctx - Plugin context (config + require for bindings resolution).
+* @returns {StorageApi} The env-first storage API surface.
+* @example
+* ```typescript
+* const api = createStorageApi(ctx);
+* const body = await api.get(env, "my-object");
+* ```
+*/
+const createStorageApi = (ctx) => {
+	/**
+	* Resolve the StorageProvider for the given per-request env. Called on every
+	* method invocation — the bucket binding is never cached across calls.
+	*
+	* @param env - The per-request Cloudflare bindings object.
+	* @returns {StorageProvider} A StorageProvider delegating to the resolved R2Bucket.
+	* @example
+	* ```typescript
+	* const p = provider(env);
+	* const body = await p.get("key");
+	* ```
+	*/
+	const provider = (env) => resolveR2Provider(ctx.require(bindingsPlugin), env, ctx.config.bucket);
+	return {
+		/**
+		* Read an object from the bucket; resolves null when the key is absent.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key.
+		* @returns {Promise<R2ObjectBody | null>} The R2ObjectBody, or null.
+		* @example
+		* ```typescript
+		* const body = await api.get(env, "assets/logo.png");
+		* ```
+		*/
+		get: (env, key) => provider(env).get(key),
+		/**
+		* Write an object to the bucket.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key.
+		* @param value - Object contents (ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null).
+		* @returns {Promise<R2Object>} The R2Object metadata for the written object.
+		* @example
+		* ```typescript
+		* const obj = await api.put(env, "assets/logo.png", buffer);
+		* ```
+		*/
+		put: (env, key, value) => provider(env).put(key, value),
+		/**
+		* Remove an object (or array of keys) from the bucket. No-op when absent.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key or array of keys.
+		* @returns {Promise<void>} Resolves once removed.
+		* @example
+		* ```typescript
+		* await api.delete(env, "assets/old.png");
+		* ```
+		*/
+		delete: (env, key) => provider(env).delete(key),
+		/**
+		* List objects, optionally filtered by R2ListOptions.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param opts - Optional R2ListOptions (prefix, limit, cursor, delimiter).
+		* @returns {Promise<R2Objects>} The R2Objects list result.
+		* @example
+		* ```typescript
+		* const { objects } = await api.list(env, { prefix: "images/" });
+		* ```
+		*/
+		list: (env, opts) => provider(env).list(opts),
+		/**
+		* Return this plugin's deploy metadata. Build-time only — does not touch
+		* `env` or R2. The deploy plugin reads this via `ctx.require(storagePlugin).deployManifest()`.
+		*
+		* @returns {StorageManifest} Deploy manifest entry `{ kind: "r2", bucket, upload }`.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest();
+		* // { kind: "r2", bucket: "ASSETS", upload: "./public" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "r2",
+			bucket: ctx.config.bucket,
+			upload: ctx.config.upload
+		})
+	};
+};
+/**
+* Complex tier — Cloudflare R2 object storage behind a provider adapter seam.
+*
+* Exposes `get`, `put`, `delete`, `list` (all env-first) and `deployManifest()`
+* (build-time). Depends on `bindingsPlugin` to resolve the `R2Bucket` binding
+* per request. No state, no events, no lifecycle hooks.
+*
+* @see README.md
+*/
+const storagePlugin = createPlugin("storage", {
+	depends: [bindingsPlugin],
+	config: {
+		upload: "",
+		bucket: "ASSETS"
+	},
+	api: createStorageApi
+});
+//#endregion
+Object.defineProperty(exports, "__exportAll", {
+	enumerable: true,
+	get: function() {
+		return __exportAll;
+	}
+});
+Object.defineProperty(exports, "__toESM", {
+	enumerable: true,
+	get: function() {
+		return __toESM;
+	}
+});
+Object.defineProperty(exports, "bindingsPlugin", {
+	enumerable: true,
+	get: function() {
+		return bindingsPlugin;
+	}
+});
+Object.defineProperty(exports, "coreConfig", {
+	enumerable: true,
+	get: function() {
+		return coreConfig;
+	}
+});
+Object.defineProperty(exports, "createCore", {
+	enumerable: true,
+	get: function() {
+		return createCore;
+	}
+});
+Object.defineProperty(exports, "createPlugin", {
+	enumerable: true,
+	get: function() {
+		return createPlugin;
+	}
+});
+Object.defineProperty(exports, "d1Plugin", {
+	enumerable: true,
+	get: function() {
+		return d1Plugin;
+	}
+});
+Object.defineProperty(exports, "defineDurableObject", {
+	enumerable: true,
+	get: function() {
+		return defineDurableObject;
+	}
+});
+Object.defineProperty(exports, "durableObjectsPlugin", {
+	enumerable: true,
+	get: function() {
+		return durableObjectsPlugin;
+	}
+});
+Object.defineProperty(exports, "kvPlugin", {
+	enumerable: true,
+	get: function() {
+		return kvPlugin;
+	}
+});
+Object.defineProperty(exports, "queuesPlugin", {
+	enumerable: true,
+	get: function() {
+		return queuesPlugin;
+	}
+});
+Object.defineProperty(exports, "stagePlugin", {
+	enumerable: true,
+	get: function() {
+		return stagePlugin;
+	}
+});
+Object.defineProperty(exports, "storagePlugin", {
+	enumerable: true,
+	get: function() {
+		return storagePlugin;
+	}
+});