@velajs/cloudflare 1.9.0 → 1.10.1

package/dist/index.js

@@ -1,37 +1,1645 @@
-// Factory & Application
-export { cloudflareAdapter, createCloudflareApp } from "./cloudflare-factory.js";
-export { CloudflareApplication } from "./cloudflare-application.js";
-// Modules
-export { KVModule } from "./modules/kv.module.js";
-export { D1Module } from "./modules/d1.module.js";
-export { R2Module } from "./modules/r2.module.js";
-export { QueueModule } from "./modules/queue.module.js";
-export { DurableObjectModule } from "./modules/durable-object.module.js";
-export { AIModule } from "./modules/ai.module.js";
-export { VectorizeModule } from "./modules/vectorize.module.js";
-export { HyperdriveModule } from "./modules/hyperdrive.module.js";
-export { EnvModule } from "./modules/env.module.js";
-// Storage (multi-disk over R2 + presign proxy)
-export { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS } from "./storage/index.js";
-// Services
-export { KVService } from "./services/kv.service.js";
-export { KVCacheStore } from "./services/kv-cache.store.js";
-export { D1Service } from "./services/d1.service.js";
-export { R2Service } from "./services/r2.service.js";
-export { QueueService } from "./services/queue.service.js";
-export { DurableObjectService } from "./services/durable-object.service.js";
-export { AIService } from "./services/ai.service.js";
-export { VectorizeService } from "./services/vectorize.service.js";
-export { HyperdriveService } from "./services/hyperdrive.service.js";
-export { EnvService } from "./services/env.service.js";
-// Feature-flag drivers (implement @velajs/feature-flags' FeatureFlagDriver contract)
-export { FlagshipFlagDriver, flagshipFlagDriver } from "./services/flagship-flag.driver.js";
-export { KvFlagDriver, kvFlagDriver } from "./services/kv-flag.driver.js";
-// Decorators
-export { Env } from "./decorators/env.js";
-export { Scheduled } from "./decorators/scheduled.js";
-export { QueueConsumer } from "./decorators/queue-consumer.js";
-// WebSocket (Durable Object transport for the Vela WebSocketModule)
-export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom } from "./websocket/index.js";
-// Re-export the core gateway API so a Cloudflare app can import it from one place.
-export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException } from "@velajs/vela/websocket";
+import { CRON_METADATA, ConfigurableModuleBuilder, Controller, Get, Inject, Injectable, InjectionToken, Module, PipelineRunner, Req, VelaApplication, VelaFactory, bootstrap, buildEntrypointExecutionContext, createParamDecorator, defineConfigurableModule, defineMetadata, getMetadata, registerEntrypointKind, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
+import { ComponentManager } from "@velajs/vela/internal";
+import { ConnectedSocket, MessageBody, SubscribeMessage, WS_GATEWAY_METADATA, WS_SERVER, WebSocketGateway, WebSocketServer, WsDispatcher, WsException, WsServerImpl, local } from "@velajs/vela/websocket";
+import { LIVE_CURSOR_LOG, LIVE_DRIVER, readPersistedLiveSubscriptions } from "@velajs/vela/live";
+import { joinStoragePath, signUrl, verifySignedUrl } from "@velajs/vela/storage";
+import { DurableObject } from "cloudflare:workers";
+//#region src/binding-ref.ts
+var BindingRef = class {
+	bindingName;
+	_value;
+	constructor(bindingName) {
+		this.bindingName = bindingName;
+	}
+	get value() {
+		if (this._value === void 0) throw new Error(`Cloudflare binding '${this.bindingName}' not initialized. Ensure createCloudflareApp() is used and a request has been made.`);
+		return this._value;
+	}
+	/** @internal — called by createCloudflareApp middleware */
+	_initialize(value) {
+		this._value = value;
+	}
+};
+//#endregion
+//#region src/websocket/room-id.ts
+/** Hibernation tag marking a socket's hub room (set at accept; immutable after). */
+function roomTag(roomId) {
+	return `room:${roomId}`;
+}
+/** Hibernation tag addressing one connection directly. */
+function connTag(connId) {
+	return `conn:${connId}`;
+}
+/** One Durable Object instance per room, addressed by name. */
+function roomToDurableId(ns, roomId) {
+	return ns.idFromName(roomId);
+}
+//#endregion
+//#region src/websocket/websocket-routing.ts
+/** Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted gateways only). */
+function collectWsGatewayRoutes(instance) {
+	const options = getMetadata(WS_GATEWAY_METADATA, instance.constructor);
+	if (!options?.path || !options?.binding) return [];
+	return [{
+		path: options.path,
+		binding: options.binding
+	}];
+}
+/**
+* Registers the upgrade routes on the Worker's Hono app. Each route validates
+* the `Upgrade` header, resolves the room's Durable Object, and forwards the raw
+* request — injecting spoof-safe `x-vela-*` headers the DO reads. The DO returns
+* the `101` with the client socket.
+*/
+function registerWebSocketRoutes(hono, routes) {
+	for (const route of routes) hono.get(route.path, async (c) => {
+		if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return c.text("Expected WebSocket upgrade", 426);
+		const ns = c.env[route.binding];
+		if (!ns) return c.text(`Durable Object binding '${route.binding}' is not configured`, 500);
+		const roomId = c.req.param("id") ?? route.path;
+		const stub = ns.get(roomToDurableId(ns, roomId));
+		const headers = new Headers(c.req.raw.headers);
+		headers.delete("x-vela-room");
+		headers.delete("x-vela-path");
+		headers.delete("x-vela-user");
+		headers.set("x-vela-room", roomId);
+		headers.set("x-vela-path", route.path);
+		const userId = c.get("userId");
+		if (userId) headers.set("x-vela-user", String(userId));
+		return stub.fetch(new Request(c.req.raw, { headers }));
+	});
+}
+//#endregion
+//#region src/cloudflare-application.ts
+registerEntrypointKind({
+	kind: "cf:vela-cron",
+	metaKey: CRON_METADATA,
+	level: "method"
+});
+function invoke(instance, methodName, args) {
+	const method = instance[methodName];
+	if (typeof method !== "function") throw new Error(`Method '${methodName}' is not a function on ${instance.constructor.name}`);
+	return method.apply(instance, args);
+}
+/**
+* Wraps VelaApplication with Cloudflare-specific handlers:
+* - `fetch` — HTTP request handler (from Hono)
+* - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
+*                 AND vela's own `@Cron()` jobs)
+* - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+* - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+*                    the underlying Hono app
+*
+* @example
+* ```ts
+* const app = await createCloudflareApp(AppModule);
+* export default {
+*   fetch: app.fetch,
+*   scheduled: app.scheduled.bind(app),
+*   queue: app.queue.bind(app),
+* };
+* ```
+*
+* @example
+* ```ts
+* // Serve OpenAPI docs alongside your routes
+* const app = await createCloudflareApp(AppModule);
+* const document = createOpenApiDocument(AppModule);
+* app.mountOpenApi({ document, ui: 'scalar' });
+* // GET /openapi.json -> JSON document
+* // GET /scalar       -> Scalar UI (loads from CDN)
+* ```
+*/
+var CloudflareApplication = class {
+	app;
+	wsGatewayRoutes = [];
+	constructor(app) {
+		this.app = app;
+	}
+	get fetch() {
+		return this.app.fetch;
+	}
+	getHonoApp() {
+		return this.app.getHonoApp();
+	}
+	/**
+	* Resolve a provider from the application's DI container (delegates to
+	* `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+	* to use inside `createCloudflareApp({ middleware: [...] })` request middleware,
+	* which runs outside the DI request pipeline.
+	*
+	* @example
+	* ```ts
+	* const app = await createCloudflareApp(AppModule);
+	* const auth = app.get<BetterAuthService>(BetterAuthService);
+	* ```
+	*/
+	get(token) {
+		return this.app.get(token);
+	}
+	/**
+	* Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+	* underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+	* so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when
+	* opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from
+	* a CDN at runtime, nothing is bundled server-side.
+	*
+	* @example
+	* ```ts
+	* import { createOpenApiDocument } from '@velajs/vela';
+	*
+	* const app = await createCloudflareApp(AppModule);
+	* const document = createOpenApiDocument(AppModule, {
+	*   info: { title: 'My API', version: '1.0.0' },
+	* });
+	* app.mountOpenApi({ document, ui: 'scalar' });
+	* // GET /openapi.json -> { openapi: '3.1.0', ... }
+	* // GET /scalar       -> Scalar UI HTML
+	* ```
+	*/
+	mountOpenApi(options) {
+		this.app.mountOpenApi(options);
+		return this;
+	}
+	/**
+	* @internal — scans instances for `@WebSocketGateway({ path, binding })`
+	* upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+	* come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+	* kinds) at dispatch time.
+	*/
+	scanInstances(instances) {
+		for (const instance of instances) {
+			if (!instance || typeof instance !== "object") continue;
+			this.wsGatewayRoutes.push(...collectWsGatewayRoutes(instance));
+		}
+	}
+	/** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+	getWsGatewayRoutes() {
+		return this.wsGatewayRoutes;
+	}
+	/**
+	* Handle Cloudflare scheduled (cron) events.
+	* Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+	* handlers read from `app.entrypoints`; each handler runs inside a fresh
+	* request-scoped child (request-scoped providers rebuild per tick).
+	*/
+	async scheduled(event, env, ctx) {
+		const handlers = [...this.app.entrypoints.ofKind("cf:scheduled").map((ep) => ({
+			ep,
+			cron: ep.meta.cron
+		})), ...this.app.entrypoints.ofKind("cf:vela-cron").map((ep) => ({
+			ep,
+			cron: ep.meta.expression
+		}))].filter((h) => h.cron === event.cron);
+		await Promise.all(handlers.map(({ ep }) => this.dispatchEntrypoint(ep, [
+			event,
+			env,
+			ctx
+		])));
+	}
+	/**
+	* Run one entrypoint handler inside a fresh request scope, through the
+	* shared guard → interceptor pipeline (components declared with
+	* `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+	* method). HTTP-global components deliberately do NOT apply — an HTTP auth
+	* guard has no business rejecting a queue batch. Unclaimed errors rethrow
+	* so the platform's retry semantics stay intact.
+	*/
+	async dispatchEntrypoint(ep, args) {
+		const targetClass = ep.token;
+		const methodName = String(ep.methodName);
+		const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, args[0]);
+		await runInEntrypointScope(this.app.getContainer(), async (scope) => {
+			const instance = scope.resolve(ep.token);
+			const guards = ComponentManager.resolveGuards(ComponentManager.getScopedComponents("guard", targetClass, methodName), scope);
+			const interceptors = ComponentManager.resolveInterceptors(ComponentManager.getScopedComponents("interceptor", targetClass, methodName), scope);
+			const filters = ComponentManager.resolveFilters([...ComponentManager.getScopedComponents("filter", targetClass, methodName)].reverse(), scope);
+			try {
+				await PipelineRunner.run({
+					context,
+					guards,
+					interceptors,
+					resolveArgs: async () => args,
+					invoke: async (resolved) => invoke(instance, methodName, resolved)
+				});
+			} catch (error) {
+				for (const filter of filters) if (shouldFilterCatch(filter, error)) {
+					await filter.catch(error, context);
+					return;
+				}
+				throw error;
+			}
+		});
+	}
+	/**
+	* Handle Cloudflare Queue consumer events.
+	* Matches the batch queue name to `@QueueConsumer()` handlers read from
+	* `app.entrypoints`; each batch is processed inside a fresh request-scoped
+	* child (request-scoped providers rebuild per batch — no boot-time captives).
+	*/
+	async queue(batch, env, ctx) {
+		const handlers = this.app.entrypoints.ofKind("cf:queue").filter((ep) => ep.meta.queueName === batch.queue);
+		await Promise.all(handlers.map((ep) => this.dispatchEntrypoint(ep, [
+			batch,
+			env,
+			ctx
+		])));
+	}
+	async close(signal) {
+		return this.app.close(signal);
+	}
+};
+//#endregion
+//#region src/env-ref.ts
+const ENV_SENTINEL = "__cf_env__";
+/**
+* Holds the entire Cloudflare Worker `env` record (bindings + vars/secrets),
+* not a single binding. Subclasses {@link BindingRef} so createCloudflareApp's
+* binding-init middleware collects and initializes it through the same path;
+* the factory special-cases it to pass the full `env` instead of one binding.
+*/
+var EnvRef = class extends BindingRef {
+	constructor() {
+		super(ENV_SENTINEL);
+	}
+};
+//#endregion
+//#region src/websocket/cf-ws-client.ts
+const MAX_ATTACHMENT_BYTES = 16384;
+const encoder = new TextEncoder();
+const EMPTY = {
+	connId: "",
+	path: "",
+	rooms: [],
+	data: {}
+};
+/**
+* Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.
+* Per-connection state lives in the hibernation attachment (survives eviction),
+* so a fresh `CfWsClient` is reconstructed per message with no in-memory state.
+*/
+var CfWsClient = class {
+	ctx;
+	ws;
+	attachment;
+	constructor(ctx, ws) {
+		this.ctx = ctx;
+		this.ws = ws;
+		const raw = ws.deserializeAttachment();
+		this.attachment = raw ?? {
+			...EMPTY,
+			data: {}
+		};
+	}
+	get id() {
+		return this.attachment.connId;
+	}
+	/** The gateway route path this socket connected on (used to route messages). */
+	get path() {
+		return this.attachment.path;
+	}
+	get rooms() {
+		return new Set(this.attachment.rooms);
+	}
+	get data() {
+		return this.attachment.data;
+	}
+	set data(value) {
+		this.attachment.data = value;
+	}
+	get raw() {
+		return this.ws;
+	}
+	send(event, data, id) {
+		this.ws.send(JSON.stringify(id !== void 0 ? {
+			id,
+			event,
+			data
+		} : {
+			event,
+			data
+		}));
+	}
+	sendRaw(payload) {
+		this.ws.send(payload);
+	}
+	join(room) {
+		if (!this.attachment.rooms.includes(room)) {
+			this.attachment.rooms.push(room);
+			this.persist();
+		}
+	}
+	leave(room) {
+		const next = this.attachment.rooms.filter((r) => r !== room);
+		if (next.length !== this.attachment.rooms.length) {
+			this.attachment.rooms = next;
+			this.persist();
+		}
+	}
+	/** Persist `data`/room mutations to the hibernation attachment. */
+	commit() {
+		this.persist();
+	}
+	close(code, reason) {
+		this.ws.close(code, reason);
+	}
+	persist() {
+		const serialized = JSON.stringify(this.attachment);
+		if (encoder.encode(serialized).length > MAX_ATTACHMENT_BYTES) throw new Error("WebSocket attachment exceeds the 16 KiB Cloudflare limit. Store large per-connection state in Durable Object storage keyed by connId instead.");
+		this.ws.serializeAttachment(this.attachment);
+	}
+};
+//#endregion
+//#region src/websocket/do-live.ts
+const DEFAULT_ROOM = "default";
+const DEFAULT_MAX_LOG_ROWS = 4096;
+/**
+* The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+* SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+* `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+* read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+* client whose gap the log still covers gets a tiny `resume` instead of a
+* re-run — the real-resume half of the live protocol.
+*
+* Constructed un-initialized at module-composition time (the same app module
+* bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+* handle inside the DO. In the Worker isolate it stays un-initialized — and is
+* never consulted there, because `durableObjectLive()` routes every
+* invalidation to the room DO's log (one log scope per room, exactly the
+* protocol's model).
+*/
+var DoCursorLog = class {
+	maxRows;
+	sql;
+	epoch;
+	constructor(maxRows = DEFAULT_MAX_LOG_ROWS) {
+		this.maxRows = maxRows;
+	}
+	/** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */
+	_initialize(sql) {
+		this.sql = sql;
+		sql.exec("CREATE TABLE IF NOT EXISTS __vela_live_log (seq INTEGER PRIMARY KEY AUTOINCREMENT, ts REAL NOT NULL, tags TEXT NOT NULL)");
+		sql.exec("CREATE TABLE IF NOT EXISTS __vela_live_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)");
+		const row = sql.exec("SELECT v FROM __vela_live_meta WHERE k = 'epoch'").toArray()[0];
+		if (row && typeof row.v === "string") this.epoch = row.v;
+		else {
+			this.epoch = crypto.randomUUID();
+			sql.exec("INSERT INTO __vela_live_meta (k, v) VALUES ('epoch', ?)", this.epoch);
+		}
+	}
+	append(tags) {
+		const sql = this.assertReady();
+		sql.exec("INSERT INTO __vela_live_log (ts, tags) VALUES (?, ?)", Date.now(), JSON.stringify(tags));
+		const stamp = this.current();
+		if (stamp.cursor > this.maxRows) sql.exec("DELETE FROM __vela_live_log WHERE seq <= ?", stamp.cursor - this.maxRows);
+		return stamp;
+	}
+	current() {
+		const sql = this.assertReady();
+		let cursor = 0;
+		try {
+			const row = sql.exec("SELECT seq FROM sqlite_sequence WHERE name = '__vela_live_log'").toArray()[0];
+			cursor = typeof row?.seq === "number" ? row.seq : Number(row?.seq ?? 0);
+		} catch {
+			cursor = 0;
+		}
+		return {
+			cursor,
+			epoch: this.epoch
+		};
+	}
+	evaluateResume(sinceCursor, sinceEpoch, subscriptionTags) {
+		const sql = this.assertReady();
+		const { cursor, epoch } = this.current();
+		if (sinceEpoch !== epoch) return "snapshot";
+		if (sinceCursor > cursor) return "snapshot";
+		if (sinceCursor === cursor) return "resume";
+		const minRow = sql.exec("SELECT MIN(seq) AS m FROM __vela_live_log").toArray()[0];
+		const min = minRow?.m == null ? void 0 : Number(minRow.m);
+		if (min === void 0 || min > sinceCursor + 1) return "snapshot";
+		const subTags = new Set(subscriptionTags);
+		for (const row of sql.exec("SELECT tags FROM __vela_live_log WHERE seq > ?", sinceCursor).toArray()) {
+			let tags;
+			try {
+				tags = JSON.parse(String(row.tags));
+			} catch {
+				return "snapshot";
+			}
+			if (Array.isArray(tags) && tags.some((tag) => subTags.has(tag))) return "rerun";
+		}
+		return "resume";
+	}
+	assertReady() {
+		if (!this.sql) throw new Error("DoCursorLog is not initialized. It only runs inside a SQLite-backed Durable Object (wrangler: new_sqlite_classes) — Worker-side invalidations must go through durableObjectLive(), which routes them to the room DO's log.");
+		return this.sql;
+	}
+};
+/**
+* The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+* bootstraps in both isolates:
+*
+* - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+*   the room's Durable Object over the `invalidate` RPC — the same canonical
+*   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+*   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+*   must carry).
+* - **DO** (writes issued from inside the object): apply to the local engine.
+*/
+function durableObjectLive(options) {
+	let sink;
+	let env;
+	let localMode = false;
+	return {
+		kind: "durable-object",
+		bind(boundSink) {
+			sink = boundSink;
+		},
+		_initializeEnv(capturedEnv) {
+			env = capturedEnv;
+		},
+		_setLocalMode() {
+			localMode = true;
+		},
+		dispatch(cmd) {
+			if (localMode) return sink?.applyInvalidation(cmd);
+			const namespace = env?.[options.binding];
+			if (!namespace) throw new Error(`durableObjectLive: binding '${options.binding}' is not available. In a Worker, createCloudflareApp() captures env on the first request; check the wrangler binding name.`);
+			const room = cmd.room ?? options.defaultRoom ?? DEFAULT_ROOM;
+			return namespace.get(roomToDurableId(namespace, room)).invalidate({
+				...cmd,
+				room
+			});
+		}
+	};
+}
+const isCfLiveDriver = (value) => typeof value === "object" && value !== null && typeof value._setLocalMode === "function" && typeof value._initializeEnv === "function";
+/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */
+function initializeWorkerLive(container, env) {
+	let driver;
+	try {
+		driver = container.resolve(LIVE_DRIVER);
+	} catch {
+		return;
+	}
+	if (isCfLiveDriver(driver)) driver._initializeEnv(env);
+}
+/**
+* DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
+* log, flip the driver to local mode, and replay every hibernation-persisted
+* subscription into the (fresh) engine so an eviction is invisible to
+* subscribers. Returns the engine for the `invalidate` RPC, or undefined when
+* the app doesn't use LiveModule.
+*/
+function initDoLive(app, container, ctx) {
+	const entry = app.entrypoints.ofKind("live")[0];
+	if (!entry) return void 0;
+	const engine = entry.meta.engine;
+	try {
+		const log = container.resolve(LIVE_CURSOR_LOG);
+		if (log instanceof DoCursorLog) {
+			const sql = ctx.storage?.sql;
+			if (!sql) throw new Error("DoCursorLog requires a SQLite-backed Durable Object: add this class to wrangler's `migrations[].new_sqlite_classes`. Falling back is not possible — either enable SQLite or drop the `log: durableObjectCursorLog()` option (snapshot-on-reconnect semantics).");
+			log._initialize(sql);
+		}
+	} catch (err) {
+		if (err instanceof Error && err.message.includes("new_sqlite_classes")) throw err;
+	}
+	try {
+		const driver = container.resolve(LIVE_DRIVER);
+		if (isCfLiveDriver(driver)) driver._setLocalMode();
+	} catch {}
+	for (const ws of ctx.getWebSockets()) {
+		const client = new CfWsClient(ctx, ws);
+		for (const record of readPersistedLiveSubscriptions(client)) engine.restoreSubscription(client.path, client, record);
+	}
+	return engine;
+}
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */
+function durableObjectCursorLog(maxRows) {
+	return new DoCursorLog(maxRows);
+}
+/**
+* Invalidate live tags in a room from a Worker (controller / cron / queue
+* consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+* scope's commit stamp for `Vela-Commit-Cursor` stamping.
+*/
+async function liveInvalidateToRoom(ns, room, tags) {
+	return ns.get(roomToDurableId(ns, room)).invalidate({
+		room,
+		tags
+	});
+}
+//#endregion
+//#region src/cloudflare-factory.ts
+function collectBindingRefs(container) {
+	const refs = [];
+	for (const value of container.getUseValues()) if (value instanceof BindingRef) refs.push(value);
+	return refs;
+}
+/**
+* Create a Cloudflare Workers application.
+*
+* Sets up a one-time Hono middleware that captures `c.env` on the first
+* request and initializes all configured binding refs. Optional
+* {@link CreateCloudflareAppOptions} are forwarded to the underlying
+* `VelaFactory.create` so consumers don't have to wrap the resulting
+* application in an outer Hono just to set a `globalPrefix` or attach
+* extra request middleware.
+*
+* @example
+* ```ts
+* // Minimal — backwards compatible
+* const app = await createCloudflareApp(AppModule);
+* export default app; // has .fetch, .scheduled, .queue
+* ```
+*
+* @example
+* ```ts
+* // With a global prefix and outer middleware
+* const app = await createCloudflareApp(AppModule, {
+*   globalPrefix: '/v1',
+*   middleware: [
+*     async (c, next) => {
+*       c.set('tenantId', c.req.header('x-tenant-id') ?? 'public');
+*       await next();
+*     },
+*   ],
+* });
+* ```
+*/
+/**
+* The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+* request middleware captures `c.env` on the first request and initializes
+* every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+* can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+* `VelaFactory.create`, so user middleware can safely read binding refs.
+*
+* Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+*
+* ```ts
+* const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+* ```
+*/
+function cloudflareAdapter() {
+	let initialized = false;
+	let refs = [];
+	let liveContainer;
+	return {
+		name: "cloudflare",
+		requestMiddleware: [async (c, next) => {
+			if (!initialized) {
+				initialized = true;
+				const env = c.env ?? {};
+				for (const ref of refs) if (ref instanceof EnvRef) ref._initialize(env);
+				else ref._initialize(env[ref.bindingName]);
+				if (liveContainer) initializeWorkerLive(liveContainer, env);
+			}
+			await next();
+		}],
+		onBootstrap: ({ container }) => {
+			liveContainer = container;
+			refs = collectBindingRefs(container);
+		}
+	};
+}
+async function createCloudflareApp(rootModule, options = {}) {
+	const velaApp = await VelaFactory.create(rootModule, {
+		globalPrefix: options.globalPrefix,
+		middleware: options.middleware,
+		adapters: [cloudflareAdapter()]
+	});
+	const cfApp = new CloudflareApplication(velaApp);
+	cfApp.scanInstances(velaApp.getInstances());
+	registerWebSocketRoutes(cfApp.getHonoApp(), cfApp.getWsGatewayRoutes());
+	return cfApp;
+}
+//#endregion
+//#region src/tokens.ts
+const KV_BINDING_REF = new InjectionToken("CF_KV_BINDING_REF");
+const D1_BINDING_REF = new InjectionToken("CF_D1_BINDING_REF");
+const R2_BINDING_REF = new InjectionToken("CF_R2_BINDING_REF");
+const QUEUE_BINDING_REF = new InjectionToken("CF_QUEUE_BINDING_REF");
+const DO_BINDING_REF = new InjectionToken("CF_DO_BINDING_REF");
+const AI_BINDING_REF = new InjectionToken("CF_AI_BINDING_REF");
+const VECTORIZE_BINDING_REF = new InjectionToken("CF_VECTORIZE_BINDING_REF");
+const HYPERDRIVE_BINDING_REF = new InjectionToken("CF_HYPERDRIVE_BINDING_REF");
+const ENV_REF = new InjectionToken("CF_ENV_REF");
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/services/kv.service.ts
+let KVService = class KVService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get namespace() {
+		return this.ref.value;
+	}
+};
+KVService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(KV_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], KVService);
+//#endregion
+//#region src/modules/create-binding-module.ts
+function createBindingModule(opts) {
+	const className = `${opts.name}Module`;
+	const moduleClass = { [className]: class {} }[className];
+	return defineConfigurableModule({
+		module: moduleClass,
+		methodName: "forRoot",
+		keyFrom: ({ binding }) => binding,
+		providers: ({ binding }) => [{
+			provide: opts.bindingRefToken,
+			useValue: new BindingRef(binding)
+		}, opts.serviceClass],
+		exports: [opts.serviceClass, opts.bindingRefToken]
+	});
+}
+//#endregion
+//#region src/modules/kv.module.ts
+const KVModule = createBindingModule({
+	name: "KV",
+	serviceClass: KVService,
+	bindingRefToken: KV_BINDING_REF
+});
+//#endregion
+//#region src/services/d1.service.ts
+let D1Service = class D1Service {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get database() {
+		return this.ref.value;
+	}
+};
+D1Service = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(D1_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], D1Service);
+//#endregion
+//#region src/modules/d1.module.ts
+const D1Module = createBindingModule({
+	name: "D1",
+	serviceClass: D1Service,
+	bindingRefToken: D1_BINDING_REF
+});
+//#endregion
+//#region src/services/r2.service.ts
+let R2Service = class R2Service {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get bucket() {
+		return this.ref.value;
+	}
+};
+R2Service = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(R2_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], R2Service);
+//#endregion
+//#region src/modules/r2.module.ts
+const R2Module = createBindingModule({
+	name: "R2",
+	serviceClass: R2Service,
+	bindingRefToken: R2_BINDING_REF
+});
+//#endregion
+//#region src/services/queue.service.ts
+let QueueService = class QueueService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get queue() {
+		return this.ref.value;
+	}
+};
+QueueService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(QUEUE_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], QueueService);
+//#endregion
+//#region src/modules/queue.module.ts
+const QueueModule = createBindingModule({
+	name: "Queue",
+	serviceClass: QueueService,
+	bindingRefToken: QUEUE_BINDING_REF
+});
+//#endregion
+//#region src/services/durable-object.service.ts
+let DurableObjectService = class DurableObjectService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get namespace() {
+		return this.ref.value;
+	}
+};
+DurableObjectService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(DO_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], DurableObjectService);
+//#endregion
+//#region src/modules/durable-object.module.ts
+const DurableObjectModule = createBindingModule({
+	name: "DurableObject",
+	serviceClass: DurableObjectService,
+	bindingRefToken: DO_BINDING_REF
+});
+//#endregion
+//#region src/services/ai.service.ts
+let AIService = class AIService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get binding() {
+		return this.ref.value;
+	}
+};
+AIService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(AI_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], AIService);
+//#endregion
+//#region src/modules/ai.module.ts
+const AIModule = createBindingModule({
+	name: "AI",
+	serviceClass: AIService,
+	bindingRefToken: AI_BINDING_REF
+});
+//#endregion
+//#region src/services/vectorize.service.ts
+let VectorizeService = class VectorizeService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get index() {
+		return this.ref.value;
+	}
+};
+VectorizeService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(VECTORIZE_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], VectorizeService);
+//#endregion
+//#region src/modules/vectorize.module.ts
+const VectorizeModule = createBindingModule({
+	name: "Vectorize",
+	serviceClass: VectorizeService,
+	bindingRefToken: VECTORIZE_BINDING_REF
+});
+//#endregion
+//#region src/services/hyperdrive.service.ts
+let HyperdriveService = class HyperdriveService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get binding() {
+		return this.ref.value;
+	}
+	get connectionString() {
+		return this.binding.connectionString;
+	}
+	get host() {
+		return this.binding.host;
+	}
+	get port() {
+		return this.binding.port;
+	}
+	get user() {
+		return this.binding.user;
+	}
+	get password() {
+		return this.binding.password;
+	}
+	get database() {
+		return this.binding.database;
+	}
+};
+HyperdriveService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(HYPERDRIVE_BINDING_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], HyperdriveService);
+//#endregion
+//#region src/modules/hyperdrive.module.ts
+const HyperdriveModule = createBindingModule({
+	name: "Hyperdrive",
+	serviceClass: HyperdriveService,
+	bindingRefToken: HYPERDRIVE_BINDING_REF
+});
+//#endregion
+//#region src/services/env.service.ts
+let EnvService = class EnvService {
+	ref;
+	constructor(ref) {
+		this.ref = ref;
+	}
+	/** The full env record. Throws if read before the first request. */
+	get env() {
+		return this.ref.value;
+	}
+	/** Read a single env entry (binding, var, or secret) by name. */
+	get(key) {
+		return this.ref.value[key];
+	}
+};
+EnvService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(ENV_REF)),
+	__decorateMetadata("design:paramtypes", [Object])
+], EnvService);
+//#endregion
+//#region src/modules/env.module.ts
+/**
+* Provides {@link EnvService} GLOBALLY so any module's provider factories can
+* `inject: [EnvService]`. Register once on the root module:
+*
+* ```ts
+* @Module({ imports: [EnvModule.forRoot(), AuthModule.forRootAsync({ ... })] })
+* class AppModule {}
+* ```
+*
+* The {@link EnvRef} it provides is collected and initialized by
+* createCloudflareApp's binding-init middleware on the first request (the
+* factory passes it the full `env`, not a single binding).
+*/
+var EnvModule = class EnvModule {
+	static forRoot() {
+		const ref = new EnvRef();
+		return {
+			module: EnvModule,
+			global: true,
+			providers: [{
+				provide: ENV_REF,
+				useValue: ref
+			}, EnvService],
+			exports: [EnvService, ENV_REF]
+		};
+	}
+};
+//#endregion
+//#region src/storage/r2-storage.driver.ts
+/** Base path of the StorageController presign-proxy route. */
+const STORAGE_ROUTE_BASE = "/storage";
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+var R2StorageDriver = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	async upload(body, path, options) {
+		await this.config.bucket.put(path, body, {
+			httpMetadata: options.mimeType ? { contentType: options.mimeType } : void 0,
+			customMetadata: options.metadata
+		});
+		return {
+			path,
+			disk: this.config.disk,
+			size: options.size,
+			mimeType: options.mimeType ?? "application/octet-stream",
+			uploadedAt: /* @__PURE__ */ new Date()
+		};
+	}
+	async download(path) {
+		const obj = await this.config.bucket.get(path);
+		if (!obj) throw new Error(`Storage object not found at "${path}".`);
+		return {
+			toStream: () => obj.body,
+			toArrayBuffer: () => obj.arrayBuffer(),
+			toText: () => obj.text(),
+			contentType: obj.httpMetadata?.contentType ?? "application/octet-stream",
+			size: obj.size,
+			metadata: obj.customMetadata
+		};
+	}
+	async delete(path) {
+		await this.config.bucket.delete(path);
+	}
+	async exists(path) {
+		return await this.config.bucket.head(path) !== null;
+	}
+	async getPresignedUrl(path, method, expiresIn) {
+		if (!this.config.secret) throw new Error("A signing secret is required for presigned URLs (set APP_SECRET).");
+		if (!Number.isFinite(expiresIn) || expiresIn <= 0) throw new Error(`Invalid presigned URL expiry: ${expiresIn}s (must be a positive number).`);
+		return {
+			url: await signUrl(`${`${STORAGE_ROUTE_BASE}/${this.config.disk}/${path}`}?method=${method}`, this.config.secret, { expiresIn }),
+			method,
+			expiresIn,
+			expiresAt: new Date(Date.now() + expiresIn * 1e3)
+		};
+	}
+};
+//#endregion
+//#region src/storage/storage.tokens.ts
+const STORAGE_OPTIONS = new InjectionToken("STORAGE_OPTIONS");
+//#endregion
+//#region src/storage/storage-manager.service.ts
+let StorageManagerService = class StorageManagerService {
+	options;
+	env;
+	constructor(options, env) {
+		this.options = options;
+		this.env = env;
+	}
+	hasDisk(disk) {
+		return this.options.disks.some((d) => d.disk === disk);
+	}
+	getDiskConfig(disk) {
+		const config = this.options.disks.find((d) => d.disk === disk);
+		if (!config) throw new Error(`Storage disk "${disk}" is not configured.`);
+		return config;
+	}
+	getDriver(disk) {
+		const config = this.getDiskConfig(disk);
+		const bucket = this.env.get(config.binding);
+		if (!bucket) throw new Error(`R2 binding "${config.binding}" for disk "${disk}" was not found in env.`);
+		return new R2StorageDriver({
+			disk,
+			bucket,
+			secret: this.env.get("APP_SECRET")
+		});
+	}
+};
+StorageManagerService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(STORAGE_OPTIONS)),
+	__decorateParam(1, Inject(EnvService)),
+	__decorateMetadata("design:paramtypes", [Object, typeof EnvService === "undefined" ? Object : EnvService])
+], StorageManagerService);
+//#endregion
+//#region src/storage/storage.controller.ts
+let StorageController = class StorageController {
+	manager;
+	env;
+	constructor(manager, env) {
+		this.manager = manager;
+		this.env = env;
+	}
+	async download(c) {
+		const secret = this.env.get("APP_SECRET");
+		if (!secret) return new Response("Storage signing is not configured", { status: 500 });
+		const disk = c.req.param("disk");
+		if (!disk || !this.manager.hasDisk(disk)) return new Response("Unknown disk", { status: 404 });
+		if (!await verifySignedUrl(c.req.url, secret)) return new Response("Invalid or expired URL", { status: 403 });
+		const url = new URL(c.req.url);
+		if ((url.searchParams.get("method") ?? "GET") !== "GET") return new Response("URL is not scoped for reads", { status: 403 });
+		const { pathname } = url;
+		const prefix = `/storage/${disk}/`;
+		const idx = pathname.indexOf(prefix);
+		const fullPath = idx >= 0 ? decodeURIComponent(pathname.slice(idx + prefix.length)) : "";
+		try {
+			const result = await this.manager.getDriver(disk).download(fullPath);
+			return new Response(result.toStream(), { headers: { "content-type": result.contentType } });
+		} catch {
+			return new Response("Not found", { status: 404 });
+		}
+	}
+};
+__decorate([
+	Get("/:disk/*"),
+	__decorateParam(0, Req()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], StorageController.prototype, "download", null);
+StorageController = __decorate([
+	Controller("storage"),
+	__decorateParam(0, Inject(StorageManagerService)),
+	__decorateParam(1, Inject(EnvService)),
+	__decorateMetadata("design:paramtypes", [typeof StorageManagerService === "undefined" ? Object : StorageManagerService, typeof EnvService === "undefined" ? Object : EnvService])
+], StorageController);
+//#endregion
+//#region src/storage/storage.service.ts
+const DEFAULT_PRESIGN = {
+	defaultExpiry: 3600,
+	maxExpiry: 86400
+};
+let StorageService = class StorageService {
+	options;
+	manager;
+	constructor(options, manager) {
+		this.options = options;
+		this.manager = manager;
+	}
+	put(relativePath, body, options = {}, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).upload(body, this.fullPath(relativePath, name), options);
+	}
+	get(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).download(this.fullPath(relativePath, name));
+	}
+	delete(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).delete(this.fullPath(relativePath, name));
+	}
+	exists(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).exists(this.fullPath(relativePath, name));
+	}
+	url(relativePath, method = "GET", expiresIn, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).getPresignedUrl(this.fullPath(relativePath, name), method, this.validateExpiry(expiresIn));
+	}
+	resolveDisk(disk) {
+		const name = disk ?? this.options.defaultDisk;
+		if (!this.manager.hasDisk(name)) throw new Error(`Storage disk "${name}" is not configured.`);
+		return name;
+	}
+	fullPath(relativePath, disk) {
+		return joinStoragePath(this.manager.getDiskConfig(disk).root, relativePath);
+	}
+	validateExpiry(expiresIn) {
+		const cfg = this.options.presignedUrl ?? DEFAULT_PRESIGN;
+		const value = expiresIn ?? cfg.defaultExpiry;
+		if (!Number.isFinite(value) || value < 1 || value > cfg.maxExpiry) throw new Error(`Presigned URL expiry ${value}s is out of range (1–${cfg.maxExpiry}s).`);
+		return value;
+	}
+};
+StorageService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(STORAGE_OPTIONS)),
+	__decorateParam(1, Inject(StorageManagerService)),
+	__decorateMetadata("design:paramtypes", [Object, typeof StorageManagerService === "undefined" ? Object : StorageManagerService])
+], StorageService);
+//#endregion
+//#region src/storage/storage.module.ts
+const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
+	moduleName: "Storage",
+	optionsInjectionToken: STORAGE_OPTIONS
+}).build();
+let StorageModule = class StorageModule extends ConfigurableModuleClass {};
+StorageModule = __decorate([Module({
+	imports: [EnvModule.forRoot()],
+	providers: [StorageManagerService, StorageService],
+	controllers: [StorageController],
+	exports: [
+		StorageService,
+		StorageManagerService,
+		STORAGE_OPTIONS
+	]
+})], StorageModule);
+//#endregion
+//#region src/services/kv-cache.store.ts
+let KVCacheStore = class KVCacheStore {
+	kv;
+	constructor(kv) {
+		this.kv = kv;
+	}
+	get ns() {
+		return this.kv.namespace;
+	}
+	async get(key) {
+		const value = await this.ns.get(key, "json");
+		return value === null ? void 0 : value;
+	}
+	async set(key, value, ttl) {
+		const options = ttl !== void 0 ? { expirationTtl: Math.max(60, Math.floor(ttl)) } : void 0;
+		await this.ns.put(key, JSON.stringify(value), options);
+	}
+	async del(key) {
+		await this.ns.delete(key);
+	}
+	async clear() {
+		let cursor;
+		do {
+			const list = await this.ns.list(cursor ? { cursor } : void 0);
+			await Promise.all(list.keys.map((entry) => this.ns.delete(entry.name)));
+			cursor = list.list_complete ? void 0 : list.cursor;
+		} while (cursor);
+	}
+};
+KVCacheStore = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(KVService)),
+	__decorateMetadata("design:paramtypes", [typeof KVService === "undefined" ? Object : KVService])
+], KVCacheStore);
+//#endregion
+//#region src/services/flagship-flag.driver.ts
+/**
+* {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+*
+* A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+* corresponding value method, forwarding the caller's `fallback` (the binding's
+* `defaultValue`) and evaluation context. The binding resolves the fallback on
+* evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+* dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+* the never-throw guarantee.
+*
+* The binding only exists per request in a Worker, so pass a lazy accessor when
+* wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+* deferred); a resolved binding may be passed directly in tests.
+*
+* ```ts
+* FeatureFlagsModule.forRootAsync({
+*   inject: [EnvService],
+*   useFactory: (env: EnvService) => ({
+*     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+*   }),
+* });
+* ```
+*
+* Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+* Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+* bare driver.
+*/
+var FlagshipFlagDriver = class {
+	name;
+	resolve;
+	constructor(binding, options = {}) {
+		this.resolve = typeof binding === "function" ? binding : () => binding;
+		this.name = options.name ?? "flagship";
+	}
+	getBoolean(key, fallback, ctx) {
+		return this.resolve().getBooleanValue(key, fallback, ctx);
+	}
+	getString(key, fallback, ctx) {
+		return this.resolve().getStringValue(key, fallback, ctx);
+	}
+	getNumber(key, fallback, ctx) {
+		return this.resolve().getNumberValue(key, fallback, ctx);
+	}
+	getObject(key, fallback, ctx) {
+		return this.resolve().getObjectValue(key, fallback, ctx);
+	}
+};
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+function flagshipFlagDriver(binding, options) {
+	return new FlagshipFlagDriver(binding, options);
+}
+//#endregion
+//#region src/services/kv-flag.driver.ts
+let KvFlagDriver = class KvFlagDriver {
+	kv;
+	name;
+	prefix;
+	constructor(kv, options = {}) {
+		this.kv = kv;
+		this.name = options.name ?? "kv";
+		this.prefix = options.prefix ?? "";
+	}
+	get ns() {
+		return this.kv.namespace;
+	}
+	getBoolean(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "boolean");
+	}
+	getString(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "string");
+	}
+	getNumber(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "number");
+	}
+	getObject(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "object" && v !== null);
+	}
+	/**
+	* Reads and JSON-parses the (prefixed) key, returning the parsed value only
+	* when `matches` accepts its type; otherwise the caller's fallback. A missing
+	* key reads as `null` → fallback. Read/parse errors are left to propagate.
+	*/
+	async read(key, fallback, matches) {
+		const value = await this.ns.get(this.prefix + key, "json");
+		if (value === null || value === void 0) return fallback;
+		return matches(value) ? value : fallback;
+	}
+};
+KvFlagDriver = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(KVService)),
+	__decorateMetadata("design:paramtypes", [typeof KVService === "undefined" ? Object : KVService, Object])
+], KvFlagDriver);
+/** Convenience factory for {@link KvFlagDriver}. */
+function kvFlagDriver(kv, options) {
+	return new KvFlagDriver(kv, options);
+}
+//#endregion
+//#region src/decorators/env.ts
+/**
+* Parameter decorator to inject Cloudflare environment bindings.
+*
+* Without arguments, returns the entire `env` object.
+* With a binding name, returns that specific binding.
+*
+* @example
+* ```ts
+* @Get()
+* handle(@Env() env: CloudflareEnv) { ... }
+*
+* @Get()
+* handle(@Env('MY_KV') kv: KVNamespace) { ... }
+* ```
+*/
+const Env = createParamDecorator((bindingName, ctx) => {
+	const env = ctx.getContext().env;
+	if (!env) return void 0;
+	return bindingName ? env[bindingName] : env;
+});
+//#endregion
+//#region src/decorators/scheduled.ts
+const SCHEDULED_METADATA_KEY = "cloudflare:scheduled";
+registerEntrypointKind({
+	kind: "cf:scheduled",
+	metaKey: SCHEDULED_METADATA_KEY,
+	level: "method"
+});
+/**
+* Marks a method as a scheduled (cron) handler.
+*
+* @example
+* ```ts
+* @Injectable()
+* class WorkerService {
+*   @Scheduled('0 * * * *')
+*   async hourlyCron() {
+*     console.log('Running hourly');
+*   }
+* }
+* ```
+*/
+function Scheduled(cron) {
+	return (target, propertyKey, _descriptor) => {
+		const existing = getMetadata(SCHEDULED_METADATA_KEY, target.constructor) ?? [];
+		existing.push({
+			cron,
+			methodName: String(propertyKey)
+		});
+		defineMetadata(SCHEDULED_METADATA_KEY, existing, target.constructor);
+	};
+}
+//#endregion
+//#region src/decorators/queue-consumer.ts
+const QUEUE_CONSUMER_METADATA_KEY = "cloudflare:queue-consumer";
+registerEntrypointKind({
+	kind: "cf:queue",
+	metaKey: QUEUE_CONSUMER_METADATA_KEY,
+	level: "method"
+});
+/**
+* Marks a method as a queue consumer handler.
+*
+* @example
+* ```ts
+* @Injectable()
+* class WorkerService {
+*   @QueueConsumer('email-queue')
+*   async processEmails(batch: MessageBatch) {
+*     for (const msg of batch.messages) {
+*       console.log('Processing:', msg.body);
+*       msg.ack();
+*     }
+*   }
+* }
+* ```
+*/
+function QueueConsumer(queueName) {
+	return (target, propertyKey, _descriptor) => {
+		const existing = getMetadata(QUEUE_CONSUMER_METADATA_KEY, target.constructor) ?? [];
+		existing.push({
+			queueName,
+			methodName: String(propertyKey)
+		});
+		defineMetadata(QUEUE_CONSUMER_METADATA_KEY, existing, target.constructor);
+	};
+}
+//#endregion
+//#region src/websocket/cf-room-registry.ts
+/**
+* Core `RoomRegistry` backed by a Durable Object's hibernatable sockets. Room
+* membership lives in tags (hub room, set at accept) + the attachment (dynamic
+* `join()`), never in DO instance fields — so it survives hibernation with zero
+* rehydration.
+*/
+var CfRoomRegistry = class {
+	ctx;
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	register(_client) {}
+	leaveAll(_client) {}
+	join(client, room) {
+		return client.join(room);
+	}
+	leave(client, room) {
+		return client.leave(room);
+	}
+	localIdsInRoom(room) {
+		return this.socketsForRoom(room).map((ws) => this.attachmentOf(ws).connId);
+	}
+	deliverLocal(cmd) {
+		const excludeIds = new Set(cmd.exceptIds ?? []);
+		const excludeRooms = cmd.exceptRooms ?? [];
+		const targets = cmd.rooms.length === 0 ? this.ctx.getWebSockets() : this.collectRooms(cmd.rooms);
+		const seen = /* @__PURE__ */ new Set();
+		for (const ws of targets) {
+			const att = this.attachmentOf(ws);
+			if (seen.has(att.connId)) continue;
+			seen.add(att.connId);
+			if (excludeIds.has(att.connId)) continue;
+			if (excludeRooms.some((r) => att.rooms.includes(r))) continue;
+			ws.send(cmd.frame);
+		}
+	}
+	collectRooms(rooms) {
+		const set = /* @__PURE__ */ new Set();
+		for (const room of rooms) for (const ws of this.socketsForRoom(room)) set.add(ws);
+		return [...set];
+	}
+	socketsForRoom(room) {
+		return this.ctx.getWebSockets().filter((ws) => this.attachmentOf(ws).rooms.includes(room));
+	}
+	attachmentOf(ws) {
+		return ws.deserializeAttachment() ?? {
+			connId: "",
+			path: "",
+			rooms: [],
+			data: {}
+		};
+	}
+	/** Reconstruct a `WsClient` for a raw socket (e.g. inside gateway lifecycle scans). */
+	clientFor(ws) {
+		return new CfWsClient(this.ctx, ws);
+	}
+};
+//#endregion
+//#region src/websocket/ws-server-holder.ts
+let WsServerHolder = class WsServerHolder {
+	target;
+	setTarget(server) {
+		this.target = server;
+	}
+	get resolved() {
+		if (!this.target) throw new Error("WebSocket server is only available inside a WebSocket Durable Object. To push from a Worker HTTP handler, use broadcastToRoom(namespace, room, ...).");
+		return this.target;
+	}
+	emit(event, data) {
+		return this.resolved.emit(event, data);
+	}
+	to(room) {
+		return this.resolved.to(room);
+	}
+	in(room) {
+		return this.resolved.in(room);
+	}
+	except(room) {
+		return this.resolved.except(room);
+	}
+};
+WsServerHolder = __decorate([Injectable()], WsServerHolder);
+//#endregion
+//#region src/websocket/do-bootstrap.ts
+/**
+* Slim DI bootstrap for the Durable Object isolate: wires the container and runs
+* `OnModuleInit`/`OnApplicationBootstrap` (so `WsDispatcher` discovers gateways)
+* WITHOUT building the Hono app/routes the DO never serves. Cloudflare binding
+* refs are initialized straight from the DO's `env`, and the ctx-backed server
+* is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
+*/
+async function buildDoRuntime(rootModule, ctx, env) {
+	const { container, routeManager, loader } = await bootstrap(rootModule);
+	for (const value of container.getUseValues()) if (value instanceof EnvRef) value._initialize(env);
+	else if (value instanceof BindingRef) value._initialize(env[value.bindingName]);
+	const registry = new CfRoomRegistry(ctx);
+	const driver = local();
+	driver.bind(registry);
+	const server = new WsServerImpl(driver);
+	try {
+		const holder = container.resolve(WS_SERVER);
+		if (holder instanceof WsServerHolder) holder.setTarget(server);
+	} catch {}
+	const app = new VelaApplication(container, routeManager);
+	app.setInstances(await loader.resolveAllInstances());
+	await app.callOnModuleInit();
+	await app.callOnApplicationBootstrap();
+	const wsEntrypoints = app.entrypoints.ofKind("websocket");
+	const live = initDoLive(app, container, ctx);
+	return {
+		dispatcher: wsEntrypoints[0]?.meta.dispatcher ?? app.get(WsDispatcher),
+		registry,
+		server,
+		gatewayPaths: wsEntrypoints.map((ep) => ep.meta.path),
+		live,
+		close: (signal) => app.close(signal)
+	};
+}
+//#endregion
+//#region src/websocket/do-websocket-host.ts
+/**
+* The socket lifecycle inside a WebSocket Durable Object, decoupled from the
+* `cloudflare:workers` base class so it is unit-testable with fakes. The thin
+* `VelaWebSocketDurableObject` shell forwards its hibernation callbacks here.
+*/
+var DoWebSocketHost = class {
+	ctx;
+	dispatcher;
+	registry;
+	gatewayPaths;
+	constructor(ctx, dispatcher, registry, gatewayPaths = []) {
+		this.ctx = ctx;
+		this.dispatcher = dispatcher;
+		this.registry = registry;
+		this.gatewayPaths = gatewayPaths;
+	}
+	/** The single registered gateway's path — a fallback when the Worker didn't forward `x-vela-path`. */
+	defaultPath() {
+		return this.gatewayPaths[0];
+	}
+	/**
+	* Accept a hibernatable socket: tag it with its hub room + connection id,
+	* persist the attachment, then fire `OnGatewayConnection` WITHOUT blocking the
+	* 101 response (the caller returns it immediately).
+	*/
+	accept(ws, path, roomId, userId) {
+		const connId = crypto.randomUUID();
+		this.ctx.acceptWebSocket(ws, [roomTag(roomId), connTag(connId)]);
+		const attachment = {
+			connId,
+			userId,
+			path,
+			rooms: [roomId],
+			data: userId ? { userId } : {}
+		};
+		ws.serializeAttachment(attachment);
+		Promise.resolve(this.dispatcher.handleOpen(path, new CfWsClient(this.ctx, ws))).catch((err) => console.warn("[vela] websocket handleConnection failed:", err));
+	}
+	async onMessage(ws, message) {
+		const client = new CfWsClient(this.ctx, ws);
+		await this.dispatcher.dispatchMessage(client.path, client, message);
+	}
+	async onClose(ws, code, reason) {
+		const client = new CfWsClient(this.ctx, ws);
+		await this.dispatcher.handleClose(client.path, client, code, reason);
+		try {
+			if (code === 1e3 || code >= 3e3 && code <= 4999) ws.close(code, reason);
+			else ws.close();
+		} catch {}
+	}
+	async onError(ws, err) {
+		const client = new CfWsClient(this.ctx, ws);
+		await this.dispatcher.handleError(client.path, client, err);
+	}
+	/** Deliver a broadcast command to this DO's local sockets (RPC entry point). */
+	broadcast(cmd) {
+		this.registry.deliverLocal(cmd);
+	}
+};
+//#endregion
+//#region src/websocket/websocket.durable-object.ts
+const PING = "{\"event\":\"ping\"}";
+const PONG = "{\"event\":\"pong\"}";
+/**
+* Base class for the WebSocket Durable Object. The user exports a named subclass
+* (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+*
+* ```ts
+* export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
+* ```
+*
+* It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
+* bridge DO hibernation) and forwards every event into the runtime-agnostic
+* `WsDispatcher` via {@link DoWebSocketHost}.
+*/
+function VelaWebSocketDurableObject(rootModule) {
+	return class VelaWsDurableObject extends DurableObject {
+		host;
+		liveEngine;
+		ready;
+		constructor(ctx, env) {
+			super(ctx, env);
+			try {
+				ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair(PING, PONG));
+			} catch {}
+			this.ready = ctx.blockConcurrencyWhile(async () => {
+				const runtime = await buildDoRuntime(rootModule, ctx, env);
+				this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry, runtime.gatewayPaths);
+				this.liveEngine = runtime.live;
+			});
+		}
+		async fetch(request) {
+			await this.ready;
+			if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") return new Response("Expected WebSocket upgrade", { status: 426 });
+			const { 0: client, 1: server } = new WebSocketPair();
+			const url = new URL(request.url);
+			const roomId = request.headers.get("x-vela-room") ?? this.ctx.id.name ?? url.pathname;
+			const path = request.headers.get("x-vela-path") ?? this.host.defaultPath() ?? url.pathname;
+			const userId = request.headers.get("x-vela-user") || void 0;
+			this.host.accept(server, path, roomId, userId);
+			return new Response(null, {
+				status: 101,
+				webSocket: client
+			});
+		}
+		async webSocketMessage(ws, message) {
+			await this.ready;
+			await this.host.onMessage(ws, message);
+		}
+		async webSocketClose(ws, code, reason) {
+			await this.ready;
+			await this.host.onClose(ws, code, reason);
+		}
+		async webSocketError(ws, error) {
+			await this.ready;
+			await this.host.onError(ws, error);
+		}
+		/** DO RPC — server-initiated broadcast forwarded from a Worker (see `broadcastToRoom`). */
+		async broadcast(cmd) {
+			await this.ready;
+			this.host.broadcast(cmd);
+		}
+		/**
+		* DO RPC — live tag invalidation forwarded from a Worker (durableObjectLive /
+		* liveInvalidateToRoom). Appends to THIS log scope's cursor log and returns
+		* the commit stamp (what `Vela-Commit-Cursor` carries); the subscription
+		* refreshes fan out asynchronously.
+		*/
+		async invalidate(cmd) {
+			await this.ready;
+			return this.liveEngine?.applyInvalidation(cmd);
+		}
+	};
+}
+//#endregion
+//#region src/websocket/cloudflare-websocket.module.ts
+/**
+* Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
+* your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
+* `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
+* ctx-backed server per instance. `useClass` ensures a fresh holder per DI
+* container so colocated DO instances never share a server.
+*/
+var CloudflareWebSocketModule = class CloudflareWebSocketModule {
+	static forRoot() {
+		return {
+			module: CloudflareWebSocketModule,
+			providers: [{
+				provide: WS_SERVER,
+				useClass: WsServerHolder
+			}, WsDispatcher],
+			exports: [WS_SERVER, WsDispatcher]
+		};
+	}
+};
+//#endregion
+//#region src/websocket/broadcast.ts
+/**
+* Push to a room from a Worker HTTP handler / cron / queue consumer (server-
+* initiated emit). Resolves the room's Durable Object and calls its `broadcast`
+* RPC method — the same canonical room→DO mapping the upgrade route uses, so it
+* always reaches the DO holding those sockets.
+*
+* @example
+* ```ts
+* // In a controller — ns from DurableObjectService.namespace
+* await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
+* ```
+*/
+async function broadcastToRoom(ns, room, event, data, options) {
+	const cmd = {
+		rooms: [room],
+		exceptIds: options?.exceptIds,
+		frame: JSON.stringify({
+			event,
+			data
+		})
+	};
+	await ns.get(roomToDurableId(ns, room)).broadcast(cmd);
+}
+//#endregion
+export { AIModule, AIService, CloudflareApplication, CloudflareWebSocketModule, ConnectedSocket, D1Module, D1Service, DoCursorLog, DurableObjectModule, DurableObjectService, Env, EnvModule, EnvService, FlagshipFlagDriver, HyperdriveModule, HyperdriveService, KVCacheStore, KVModule, KVService, KvFlagDriver, MessageBody, QueueConsumer, QueueModule, QueueService, R2Module, R2Service, R2StorageDriver, STORAGE_OPTIONS, Scheduled, StorageController, StorageManagerService, StorageModule, StorageService, SubscribeMessage, VectorizeModule, VectorizeService, VelaWebSocketDurableObject, WebSocketGateway, WebSocketServer, WsException, broadcastToRoom, cloudflareAdapter, createCloudflareApp, durableObjectCursorLog, durableObjectLive, flagshipFlagDriver, kvFlagDriver, liveInvalidateToRoom };
+
+//# sourceMappingURL=index.js.map