@moku-labs/worker 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,960 @@
+import { n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-AjH57AmD.mjs";
+import { envPlugin, logPlugin } from "@moku-labs/common";
+import { PluginCtx, PluginInstance } from "@moku-labs/core";
+
+//#region src/plugins/bindings/index.d.ts
+/**
+ * bindings config. Flat (spec/05 §3,§6) — a complete default so omission
+ * never yields undefined.
+ *
+ * @example
+ * ```typescript
+ * { required: ["MY_KV", "DB"] }
+ * ```
+ */
+type Config$4 = {
+  required: string[];
+};
+/**
+ * The app.bindings surface — a stateless resolver over a request-supplied env.
+ *
+ * @example
+ * ```typescript
+ * const kv = app.bindings.require<KVNamespace>(env, "MY_KV");
+ * const ok = app.bindings.has(env, "DB");
+ * ```
+ */
+type BindingsApi = {
+  /**
+   * Resolve binding `name` off the request-supplied env, narrowed to T.
+   *
+   * @param env - The Cloudflare request env object.
+   * @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 nullish.
+   */
+  require<T>(env: WorkerEnv, name: string): T;
+  /**
+   * True when `name` resolves to a non-nullish value on the request-supplied env.
+   *
+   * @param env - The Cloudflare request env object.
+   * @param name - The binding name to check.
+   * @returns Whether the binding is present and non-nullish.
+   */
+  has(env: WorkerEnv, name: string): boolean;
+};
+/**
+ * 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
+ */
+declare const bindingsPlugin: import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>;
+declare namespace types_d_exports$3 {
+  export { Api$3 as Api, CompiledEndpoint, Endpoint, EndpointHandler, MatchResult, Method, PathSegment, RequestContext, RequireFn, ServerConfig, ServerCtx, ServerEvents, ServerState };
+}
+/** HTTP method an endpoint matches; "ALL" matches any verb. */
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
+/** One parsed path segment: a literal, a required `{name}`, or an optional `{name?}`. */
+type PathSegment = {
+  /** The literal text, or the param name when a param. */readonly value: string; /** Whether this segment is a `{name}` / `{name?}` parameter. */
+  readonly param: boolean; /** Whether the param is optional (`{name?}`). */
+  readonly optional: boolean;
+};
+/** A declarative endpoint produced by the pure endpoint() builder. */
+type Endpoint = {
+  /** Endpoint path, optionally with `{name}` / `{name?}` params. */readonly path: string; /** HTTP method or "ALL". */
+  readonly method: Method; /** The handler invoked on a match. */
+  readonly handler: EndpointHandler;
+};
+/** A compiled endpoint with pre-parsed segments and a specificity score. */
+type CompiledEndpoint = {
+  /** Original endpoint, returned to the dispatch site. */readonly endpoint: Endpoint; /** Pre-parsed path segments for fast matching. */
+  readonly segments: ReadonlyArray<PathSegment>; /** Specificity score — higher = more literal segments, sorted first. */
+  readonly specificity: number;
+};
+/** Server config — the declarative endpoint table. */
+type ServerConfig = {
+  /** Endpoints compiled into the matcher table. Default []. */endpoints: Endpoint[];
+};
+/** A successful endpoint match: the endpoint plus its extracted path params. */
+type MatchResult = {
+  /** The matched endpoint. */readonly endpoint: Endpoint; /** Path params extracted from the request path. */
+  readonly params: Record<string, string | undefined>;
+};
+/** Server state — the compiled matcher table, built once at onInit. */
+type ServerState = {
+  /** Endpoints sorted by specificity. Populated from config at onInit. */table: CompiledEndpoint[]; /** True once onInit has compiled the table; guards double-compilation. */
+  compiled: boolean;
+  /**
+   * Match a method + pathname against the compiled table (literal beats param,
+   * method-specific beats ALL). Returns the matched endpoint + params, or null.
+   *
+   * @param method - The request method (or "ALL" for cron dispatch).
+   * @param path - The request URL pathname (or cron string).
+   * @returns The matched endpoint and its params, or null.
+   */
+  match(method: string, path: string): MatchResult | null;
+};
+/** Any plugin instance — mirrors core's un-exported RequireFunction constraint. */
+type AnyPlugin = PluginInstance<string, any, any, any, any>;
+/**
+ * Extract a plugin instance's API type. Extracts via the `_phantom.api` slot —
+ * identical to core's un-exported `ExtractPluginApi`, so this `RequireFn` is
+ * assignable FROM core's real `ctx.require` (whose return is `ExtractPluginApi<P>`).
+ * Extracting via the `PluginInstance<…, infer A, …>` pattern would NOT unify with
+ * `ExtractPluginApi<P>` for an unresolved generic `P`.
+ */
+type ApiOf<P> = P extends {
+  readonly _phantom: {
+    readonly api: infer A;
+  };
+} ? A : never;
+/** Cross-plugin reach used inside handlers: require(plugin) returns that plugin's API. Mirrors ctx.require. */
+type RequireFn = <P extends AnyPlugin>(plugin: P) => ApiOf<P>;
+/** A request handler: receives the per-request context, returns a Response. */
+type EndpointHandler = (ctx: RequestContext) => Response | Promise<Response>;
+/** Fresh per-request object threaded to each EndpointHandler. */
+type RequestContext = {
+  /** The incoming request. */readonly request: Request; /** Per-request Cloudflare bindings — threaded on the stack, NEVER stored in state. */
+  readonly env: WorkerEnv; /** waitUntil / passThroughOnException. */
+  readonly exec: ExecutionContext; /** Path params extracted from the matched endpoint. */
+  readonly params: Record<string, string | undefined>; /** Parsed request URL. */
+  readonly url: URL; /** Cross-plugin reach for handlers (e.g. require(bindingsPlugin)). */
+  readonly require: RequireFn; /** Presence check for an optional plugin. */
+  readonly has: (name: string) => boolean;
+};
+/** Per-plugin event map merged into the server context. */
+type ServerEvents = {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+};
+/** Full server plugin context (own config + state + merged events + cross-plugin reach). */
+type ServerCtx = PluginCtx<ServerConfig, ServerState, WorkerEvents & ServerEvents> & {
+  /** Cross-plugin require threaded into each RequestContext. */require: RequireFn; /** Presence check for an optional plugin. */
+  has: (name: string) => boolean;
+};
+/** Public api surface of the server plugin. */
+type Api$3 = {
+  /**
+   * Route one HTTP request and return its Response (or 404).
+   *
+   * @param request - The incoming request.
+   * @param env - Per-request Cloudflare bindings (threaded, never stored).
+   * @param exec - waitUntil / passThroughOnException.
+   * @returns The handler's response, or 404 Not Found.
+   */
+  handle(request: Request, env: WorkerEnv, exec: ExecutionContext): Promise<Response>;
+  /**
+   * Cron entry. Dispatches the controller through the endpoint table and awaits it.
+   *
+   * @param controller - The cron controller.
+   * @param env - Per-request bindings (threaded, never stored).
+   * @param exec - waitUntil / passThroughOnException.
+   * @returns Resolves after all matched cron work completes.
+   */
+  scheduled(controller: ScheduledController, env: WorkerEnv, exec: ExecutionContext): Promise<void>;
+};
+//#endregion
+//#region src/plugins/server/helpers.d.ts
+/**
+ * Fluent builder whose verb methods each return a typed `Endpoint`.
+ *
+ * @example
+ * ```typescript
+ * const e = endpoint("/api/{id}").get(handler);
+ * ```
+ */
+type EndpointBuilder = {
+  /**
+   * Build a GET endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a GET request matches.
+   * @returns A GET `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/health").get(() => new Response("ok"));
+   * ```
+   */
+  get(handler: EndpointHandler): Endpoint;
+  /**
+   * Build a POST endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a POST request matches.
+   * @returns A POST `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/users").post(({ request }) => Response.json({ created: true }, { status: 201 }));
+   * ```
+   */
+  post(handler: EndpointHandler): Endpoint;
+  /**
+   * Build a PUT endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a PUT request matches.
+   * @returns A PUT `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/users/{id}").put(({ params }) => Response.json({ updated: params.id }));
+   * ```
+   */
+  put(handler: EndpointHandler): Endpoint;
+  /**
+   * Build a PATCH endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a PATCH request matches.
+   * @returns A PATCH `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/users/{id}").patch(({ params }) => Response.json({ patched: params.id }));
+   * ```
+   */
+  patch(handler: EndpointHandler): Endpoint;
+  /**
+   * Build a DELETE endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a DELETE request matches.
+   * @returns A DELETE `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/users/{id}").delete(() => new Response(null, { status: 204 }));
+   * ```
+   */
+  delete(handler: EndpointHandler): Endpoint;
+  /**
+   * Build a HEAD endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when a HEAD request matches.
+   * @returns A HEAD `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/health").head(() => new Response(null, { status: 200 }));
+   * ```
+   */
+  head(handler: EndpointHandler): Endpoint;
+  /**
+   * Build an OPTIONS endpoint bound to this path.
+   *
+   * @param handler - The handler invoked when an OPTIONS request matches.
+   * @returns An OPTIONS `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("/api").options(() => new Response(null, { headers: { Allow: "GET, POST" } }));
+   * ```
+   */
+  options(handler: EndpointHandler): Endpoint;
+  /**
+   * Build an ALL-method endpoint bound to this path (`method: "ALL"` — matches any verb).
+   *
+   * @param handler - The handler invoked when any request method matches.
+   * @returns An ALL-method `Endpoint`.
+   * @example
+   * ```typescript
+   * endpoint("0 * * * *").all(async () => new Response("cron done"));
+   * ```
+   */
+  all(handler: EndpointHandler): Endpoint;
+};
+/**
+ * Build a typed `Endpoint`. `{name}` → required param; `{name?}` → optional param.
+ *
+ * PURE factory (spec/03 §1): no ctx, no lifecycle, no side effects; safe to run
+ * before `createApp`. Each verb method (`get`, `post`, …, `all`) returns the
+ * truthful Endpoint value — `method: "ALL"` is never used as a `"get"` sentinel.
+ *
+ * @param path - Endpoint path, optionally with `{name}` / `{name?}` params.
+ * @returns A builder whose verb methods each return a typed `Endpoint`.
+ * @example
+ * ```typescript
+ * endpoint("/api/data/{lang?}").get(({ params }) =>
+ *   Response.json({ lang: params.lang ?? "en" })
+ * );
+ * ```
+ */
+declare const endpoint: (path: string) => EndpointBuilder;
+declare namespace types_d_exports {
+  export { Api$2 as Api, Config$3 as Config, D1Ctx, DeployManifest$2 as DeployManifest };
+}
+/**
+ * d1 plugin configuration.
+ *
+ * @example
+ * ```ts
+ * { binding: "DB", migrations: "./migrations" }
+ * ```
+ */
+type Config$3 = {
+  /** D1 binding name resolved off the per-request env. */binding: string; /** Migrations directory; deploy-time metadata only. */
+  migrations: string;
+};
+/**
+ * Deploy metadata entry for a D1 database, read by the deploy plugin.
+ *
+ * @example
+ * ```ts
+ * { kind: "d1", binding: "DB", migrations: "./migrations" }
+ * ```
+ */
+type DeployManifest$2 = {
+  /** Discriminant identifying this as a D1 resource. */kind: "d1"; /** D1 binding name. */
+  binding: string; /** Migrations directory (or "" if none). */
+  migrations: string;
+};
+/** Public api surface of the d1 plugin (thin typed wrappers over prepare().bind()). */
+type Api$2 = {
+  /**
+   * Run a statement and return all rows.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param sql - SQL with `?` placeholders.
+   * @param params - Bind parameters.
+   * @returns All rows in a D1 result.
+   */
+  query: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<D1Result<T>>;
+  /**
+   * Run a statement and return the first row or null.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param sql - SQL with `?` placeholders.
+   * @param params - Bind parameters.
+   * @returns The first row, or null if none.
+   */
+  first: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<T | null>;
+  /**
+   * Run a write/DDL statement and return its result meta.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param sql - SQL with `?` placeholders.
+   * @param params - Bind parameters.
+   * @returns Result carrying `.meta`.
+   */
+  run: (env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<D1Result>;
+  /**
+   * Execute prepared statements atomically in one round-trip.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param stmts - Caller-built prepared statements.
+   * @returns One result per statement, order preserved.
+   */
+  batch: (env: WorkerEnv, stmts: D1PreparedStatement[]) => Promise<D1Result[]>;
+  /**
+   * Resolve the request D1Database so callers can build statements for batch().
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @returns The request-resolved database handle.
+   */
+  prepare: (env: WorkerEnv) => D1Database;
+  /**
+   * Return this plugin's deploy metadata (read by the deploy plugin).
+   *
+   * @returns Deploy manifest entry `{ kind: "d1", binding, migrations }`.
+   */
+  deployManifest: () => DeployManifest$2;
+};
+/**
+ * Internal context type — own config first, no state, no d1-local events.
+ * Intersected with a narrow `require` typed to the one dependency d1 resolves.
+ */
+type D1Ctx = PluginCtx<Config$3, Record<string, never>, WorkerEvents> & {
+  /**
+   * Resolve a dependency plugin's api. d1 only ever resolves `bindingsPlugin`.
+   *
+   * @param plugin - The bindingsPlugin instance.
+   * @returns The resolved bindings api.
+   */
+  require(plugin: typeof bindingsPlugin): BindingsApi;
+};
+//#endregion
+//#region src/plugins/d1/index.d.ts
+/**
+ * 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
+ */
+declare const d1Plugin: import("@moku-labs/core").PluginInstance<"d1", Config$3, Record<string, never>, {
+  query: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<D1Result<T>>;
+  first: <T = unknown>(env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<T | null>;
+  run: (env: WorkerEnv, sql: string, ...params: unknown[]) => Promise<D1Result<Record<string, unknown>>>;
+  batch: (env: WorkerEnv, stmts: D1PreparedStatement[]) => Promise<D1Result<unknown>[]>;
+  prepare: (env: WorkerEnv) => D1Database;
+  deployManifest: () => DeployManifest$2;
+}, {}> & Record<never, never>;
+declare namespace types_d_exports$1 {
+  export { Api$1 as Api, Config$2 as Config, Ctx$1 as Ctx, DeployManifest$1 as DeployManifest };
+}
+/**
+ * durableObjects plugin configuration. Flat; complete default so omission never yields undefined.
+ *
+ * @example
+ * ```ts
+ * { bindings: { counter: "COUNTER" } }
+ * ```
+ */
+type Config$2 = {
+  /** Logical name -> Cloudflare DO binding name. A missing logical name falls back to itself. Default {}. */bindings: Record<string, string>;
+};
+/**
+ * Deploy metadata entry for Durable Objects, read by the deploy plugin.
+ *
+ * @example
+ * ```ts
+ * { kind: "do", bindings: { counter: "COUNTER" } }
+ * ```
+ */
+type DeployManifest$1 = {
+  /** Discriminant identifying this as a Durable Objects resource. */kind: "do"; /** Logical name -> Cloudflare DO binding name. */
+  bindings: Record<string, string>;
+};
+/** Public api surface of the durableObjects plugin. */
+type Api$1 = {
+  /**
+   * Resolve a DurableObjectStub off the request env (logical name -> configured binding).
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param logicalName - Logical DO name used in code.
+   * @param idName - Stable id name passed to idFromName.
+   * @returns The addressed Durable Object stub.
+   */
+  get(env: WorkerEnv, logicalName: string, idName: string): DurableObjectStub;
+  /**
+   * Return this plugin's deploy metadata (read by the deploy plugin).
+   *
+   * @returns Deploy manifest entry `{ kind: "do", bindings }`.
+   */
+  deployManifest(): DeployManifest$1;
+};
+/** Internal context type — own config first, no state, no DO events. */
+type Ctx$1 = PluginCtx<Config$2, Record<string, never>, WorkerEvents>;
+//#endregion
+//#region src/plugins/durable-objects/helpers.d.ts
+/**
+ * Constructor contract of the base class returned by `defineDurableObject`.
+ *
+ * @example
+ * ```typescript
+ * class Counter extends defineDurableObject("Counter") implements DurableObjectBase {
+ *   async fetch(): Promise<Response> { return new Response("ok"); }
+ * }
+ * ```
+ */
+interface DurableObjectBase {
+  /** Cloudflare per-object storage/alarm context. */
+  readonly ctx: DurableObjectState;
+  /** Per-object Cloudflare bindings (per-request env). */
+  readonly env: WorkerEnv;
+}
+/**
+ * Constructor type produced by `defineDurableObject`. The consumer `extends` this
+ * and exports the resulting class from `worker.ts`.
+ *
+ * @example
+ * ```typescript
+ * const Base: DurableObjectBaseConstructor = defineDurableObject("Counter");
+ * class Counter extends Base {}
+ * ```
+ */
+type DurableObjectBaseConstructor = new (ctx: DurableObjectState, env: WorkerEnv) => DurableObjectBase;
+/**
+ * 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 });
+ *   }
+ * }
+ * ```
+ */
+declare const defineDurableObject: (name: string) => DurableObjectBaseConstructor & {
+  readonly doName: string;
+};
+//#endregion
+//#region src/plugins/durable-objects/index.d.ts
+/**
+ * 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
+ */
+declare const durableObjectsPlugin: import("@moku-labs/core").PluginInstance<"durableObjects", Config$2, Record<string, never>, {
+  get: (env: WorkerEnv, logicalName: string, idName: string) => DurableObjectStub;
+  deployManifest: () => DeployManifest$1;
+}, {}> & {
+  defineDurableObject: (name: string) => DurableObjectBaseConstructor & {
+    readonly doName: string;
+  };
+};
+//#endregion
+//#region src/plugins/kv/api.d.ts
+/**
+ * The app.kv surface — env-first key/value access plus deploy metadata.
+ *
+ * @example
+ * ```typescript
+ * const value = await app.kv.get(env, "feature-flags");
+ * await app.kv.put(env, "session:1", "data", { expirationTtl: 3600 });
+ * ```
+ */
+type KvApi = {
+  /**
+   * 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.
+   */
+  get(env: WorkerEnv, key: string): Promise<string | null>;
+  /**
+   * 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.
+   */
+  put(env: WorkerEnv, key: string, value: string, opts?: KVNamespacePutOptions): Promise<void>;
+  /**
+   * 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.
+   */
+  delete(env: WorkerEnv, key: string): Promise<void>;
+  /**
+   * Lists keys in the namespace, optionally filtered/paginated.
+   *
+   * @param env - The per-request Cloudflare env.
+   * @param opts - Optional prefix / cursor / limit.
+   * @returns The list result.
+   */
+  list(env: WorkerEnv, opts?: KVNamespaceListOptions): Promise<KVNamespaceListResult<unknown, string>>;
+  /**
+   * Returns this plugin's own deploy metadata, read by the deploy plugin.
+   * Build-time only — takes no env.
+   *
+   * @returns The kv deploy descriptor.
+   */
+  deployManifest(): {
+    kind: "kv";
+    binding: string;
+  };
+};
+//#endregion
+//#region src/plugins/kv/index.d.ts
+/**
+ * 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
+ */
+declare const kvPlugin: import("@moku-labs/core").PluginInstance<"kv", {
+  binding: string;
+}, Record<string, never>, KvApi, {}> & Record<never, never>;
+declare namespace types_d_exports$2 {
+  export { Api, Config$1 as Config, Ctx, DeployManifest, QueueEvents };
+}
+/**
+ * queues plugin configuration. Flat; complete defaults so omission never yields undefined.
+ */
+type Config$1 = {
+  /** Queue names this Worker produces to; surfaced by deployManifest(). Default []. */producers: string[]; /** Declarative consumer handler — awaited once per message in consume(). Default no-op. */
+  onMessage: (message: Message, env: WorkerEnv) => Promise<void>;
+};
+/**
+ * Deploy metadata entry for a queue, read by the deploy plugin.
+ *
+ * @example
+ * ```ts
+ * { kind: "queue", producers: ["orders"] }
+ * ```
+ */
+type DeployManifest = {
+  /** Discriminant identifying this as a queue resource. */kind: "queue"; /** Queue names produced to. */
+  producers: string[];
+};
+/** Per-plugin event map for queues. */
+type QueueEvents = {
+  "queue:message": {
+    queue: string;
+    messageId: string;
+  };
+};
+/** Public api surface of the queues plugin (producer + consumer). */
+type Api = {
+  /**
+   * Enqueue a single message onto the named queue.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param queue - Target queue binding name.
+   * @param body - Message body.
+   * @returns Resolves once enqueued.
+   */
+  send(env: WorkerEnv, queue: string, body: unknown): Promise<void>;
+  /**
+   * Enqueue many messages; each element becomes one message.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param queue - Target queue binding name.
+   * @param bodies - Message bodies.
+   * @returns Resolves once enqueued.
+   */
+  sendBatch(env: WorkerEnv, queue: string, bodies: unknown[]): Promise<void>;
+  /**
+   * Consumer dispatch — the Worker's queue() export delegates here.
+   *
+   * @param batch - The incoming message batch.
+   * @param env - Per-request Cloudflare bindings.
+   * @param exec - waitUntil / passThroughOnException.
+   * @returns Resolves after all messages settle.
+   */
+  consume(batch: MessageBatch, env: WorkerEnv, exec: ExecutionContext): Promise<void>;
+  /**
+   * Return this plugin's deploy metadata (read by the deploy plugin).
+   *
+   * @returns Deploy manifest entry `{ kind: "queue", producers }`.
+   */
+  deployManifest(): DeployManifest;
+};
+/**
+ * Internal context type — own config first, no state, merged queue events.
+ *
+ * `PluginCtx` exposes only `config`/`state`/`emit`; `require` is composed in here
+ * (core's "advanced composition" note), typed to the one dependency queues resolves —
+ * `require(bindingsPlugin)` → `BindingsApi`. Core does not export `RequireFunction`.
+ */
+type Ctx = PluginCtx<Config$1, Record<string, never>, WorkerEvents & QueueEvents> & {
+  /**
+   * Resolve a dependency plugin's api. queues only ever resolves `bindingsPlugin`.
+   *
+   * @param plugin - The bindings plugin instance.
+   * @returns The resolved bindings api.
+   */
+  require(plugin: typeof bindingsPlugin): BindingsApi;
+};
+//#endregion
+//#region src/plugins/queues/index.d.ts
+/**
+ * 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
+ */
+declare const queuesPlugin: import("@moku-labs/core").PluginInstance<"queues", Config$1, Record<string, never>, {
+  send: (env: Parameters<(message: Message, env: WorkerEnv) => Promise<void>>[1], q: string, body: unknown) => Promise<void>;
+  sendBatch: (env: Parameters<(message: Message, env: WorkerEnv) => Promise<void>>[1], q: string, bodies: unknown[]) => Promise<void>;
+  consume: (batch: MessageBatch, env: Parameters<(message: Message, env: WorkerEnv) => Promise<void>>[1], _exec: ExecutionContext) => Promise<void>;
+  deployManifest: () => {
+    kind: "queue";
+    producers: string[];
+  };
+}, {
+  "queue:message": {
+    queue: string;
+    messageId: string;
+  };
+}> & Record<never, never>;
+//#endregion
+//#region src/plugins/server/index.d.ts
+/**
+ * Standard tier — HTTP routing + request/scheduled dispatch over a compiled
+ * endpoint table. Emits `server:matched` (per-plugin) plus global
+ * `request:start` / `request:end` declared in `WorkerEvents`.
+ *
+ * @see README.md
+ */
+declare const serverPlugin: import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+}> & {
+  endpoint: (path: string) => EndpointBuilder;
+};
+//#endregion
+//#region src/plugins/storage/providers/types.d.ts
+/**
+ * @file storage plugin — provider adapter seam (the StorageProvider interface).
+ *
+ * R2ListOptions / R2Object / R2ObjectBody / R2Objects are ambient globals from
+ * `@cloudflare/workers-types` (tsconfig "types") — used unqualified, never imported.
+ */
+/**
+ * The adapter seam. Both the real R2 provider and the in-memory test double
+ * implement this so api.ts is provider-agnostic.
+ *
+ * @example
+ * ```ts
+ * const provider = createMemoryProvider();
+ * await provider.put("k", "v");
+ * ```
+ */
+type StorageProvider = {
+  /** Read an object; null when absent. */get(key: string): Promise<R2ObjectBody | null>; /** Write an object. */
+  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null): Promise<R2Object>; /** Remove an object (or keys). */
+  delete(key: string | string[]): Promise<void>; /** List objects. */
+  list(opts?: R2ListOptions): Promise<R2Objects>;
+};
+declare namespace types_d_exports$4 {
+  export { StorageApi, StorageConfig, StorageCtx, StorageManifest, StorageProvider };
+}
+/**
+ * storage plugin configuration. Flat; complete defaults so omission never yields undefined.
+ *
+ * @example
+ * ```ts
+ * { upload: "./public", bucket: "ASSETS" }
+ * ```
+ */
+type StorageConfig = {
+  /** Directory uploaded to R2 at deploy (deploy metadata only). Default "". */upload: string; /** R2 bucket binding name resolved off the per-request env. Default "ASSETS". */
+  bucket: string;
+};
+/** Deploy metadata returned to the deploy plugin. */
+type StorageManifest = {
+  /** Discriminant identifying this as an R2 resource. */readonly kind: "r2"; /** R2 bucket binding name. */
+  readonly bucket: string; /** Directory uploaded to R2 at deploy. */
+  readonly upload: string;
+};
+/** Public storage API surface (env-first). */
+type StorageApi = {
+  /**
+   * Read an object; resolves null when the key is absent.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param key - Object key.
+   * @returns The object body, or null.
+   */
+  get(env: WorkerEnv, key: string): Promise<R2ObjectBody | null>;
+  /**
+   * Write an object.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param key - Object key.
+   * @param value - Object contents.
+   * @returns The written object metadata.
+   */
+  put(env: WorkerEnv, key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null): Promise<R2Object>;
+  /**
+   * Remove an object (or keys). No-op when absent.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param key - Object key or keys.
+   * @returns Resolves once removed.
+   */
+  delete(env: WorkerEnv, key: string | string[]): Promise<void>;
+  /**
+   * List objects, optionally filtered by R2ListOptions.
+   *
+   * @param env - Per-request Cloudflare bindings.
+   * @param opts - Optional prefix / limit / cursor / delimiter.
+   * @returns The list result.
+   */
+  list(env: WorkerEnv, opts?: R2ListOptions): Promise<R2Objects>;
+  /**
+   * Build-time deploy metadata for the deploy plugin.
+   *
+   * @returns Deploy manifest entry `{ kind: "r2", bucket, upload }`.
+   */
+  deployManifest(): StorageManifest;
+};
+/**
+ * Internal context type — own config first, no state, no storage events.
+ * Intersected with a narrow `require` typed to the one dependency storage
+ * resolves — mirrors the kv/api.ts pattern (PluginCtx has no `require` by
+ * default; core does not export a generic RequireFunction).
+ */
+type StorageCtx = PluginCtx<StorageConfig, Record<string, never>, WorkerEvents> & {
+  /**
+   * Resolve a dependency plugin's api. storage only ever resolves bindingsPlugin.
+   *
+   * @param plugin - The bindingsPlugin instance.
+   * @returns The resolved bindings api.
+   */
+  require(plugin: typeof bindingsPlugin): BindingsApi;
+};
+//#endregion
+//#region src/plugins/storage/index.d.ts
+/**
+ * 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
+ */
+declare const storagePlugin: import("@moku-labs/core").PluginInstance<"storage", StorageConfig, Record<string, never>, StorageApi, {}> & Record<never, never>;
+//#endregion
+//#region src/plugins/stage/index.d.ts
+/** This plugin's own config type (Nano tier — declared inline, no types.ts). */
+type Config = {
+  /**
+   * Deployment stage for this Worker.
+   * - "production"  — live deploy; isDev() === false, isProduction() === true
+   * - "development" — local `wrangler dev`; isDev() === true
+   * - "test"        — automated tests; isDev() === false, isProduction() === false
+   * Default: "production" (fail-safe — an unspecified app behaves as production).
+   */
+  stage: "production" | "development" | "test";
+};
+/** The ctx.stage accessor surface injected on every regular plugin's context. */
+type StageApi = {
+  /**
+   * 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(): boolean;
+  /**
+   * 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(): boolean;
+  /**
+   * The raw deployment stage, as the literal union (not `string`).
+   *
+   * @returns The resolved stage value.
+   * @example
+   * ```typescript
+   * ctx.log.info("startup", { stage: ctx.stage.current() });
+   * ```
+   */
+  current(): "production" | "development" | "test";
+};
+/**
+ * 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",
+ * })
+ * ```
+ */
+declare const stagePlugin: import("@moku-labs/core").CorePluginInstance<"stage", Config, Record<string, never>, {
+  /**
+   * 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: () => boolean;
+  /**
+   * 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: () => boolean;
+  /**
+   * 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: () => "production" | "development" | "test";
+}>;
+//#endregion
+//#region src/index.d.ts
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+    "server:matched": {
+      path: string;
+      method: string;
+    };
+  }> & {
+    endpoint: (path: string) => EndpointBuilder;
+  }) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+    stage: "production" | "development" | "test";
+  }, Record<string, never>, {
+    isDev: () => boolean;
+    isProduction: () => boolean;
+    current: () => "production" | "development" | "test";
+  }>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+    "server:matched": {
+      path: string;
+      method: string;
+    };
+  }> & {
+    endpoint: (path: string) => EndpointBuilder;
+  }) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+    stage: "production" | "development" | "test";
+  }, Record<string, never>, {
+    isDev: () => boolean;
+    isProduction: () => boolean;
+    current: () => "production" | "development" | "test";
+  }>]>>, createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<WorkerConfig, WorkerEvents, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+    stage: "production" | "development" | "test";
+  }, Record<string, never>, {
+    isDev: () => boolean;
+    isProduction: () => boolean;
+    current: () => "production" | "development" | "test";
+  }>]>>;
+//#endregion
+export { types_d_exports as D1, types_d_exports$1 as DurableObjects, types_d_exports$2 as Queues, types_d_exports$3 as Server, type StageApi, types_d_exports$4 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };