@velajs/cloudflare 1.24.0 → 1.29.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { C as durableObjectRoomName, T as roomToDurableId, _ as readDoPitrBookmark, a as durableObjectLive, b as assertCloudflareEnvironment, c as liveInvalidateToRoom, g as isDoPitrUnavailable, h as armDoPitr, i as durableObjectCursorLog, m as DoPitrUnavailableError, n as isValidExpiry, p as WsServerHolder, r as DoCursorLog, t as isCanonicalBoundedText, v as __decorate, x as registerCloudflareEnvironment, y as resolveCloudflareRoot } from "./nonce-validation-Bcqf3FvY.js";
+import { C as durableObjectRoomName, T as roomToDurableId, a as armDoPitr, b as assertCloudflareEnvironment, c as __decorate, d as durableObjectLive, h as warnWorkerLocalLive, i as DoPitrUnavailableError, l as DoCursorLog, m as liveInvalidateToRoom, n as isValidExpiry, o as isDoPitrUnavailable, r as WsServerHolder, s as readDoPitrBookmark, t as isCanonicalBoundedText, u as durableObjectCursorLog, x as registerCloudflareEnvironment } from "./nonce-validation-Dy8z05A9.js";
 import { getConnInfo } from "hono/cloudflare-workers";
-import { CRON_METADATA, ConfigurableModuleBuilder, Controller, Get, Inject, Injectable, InjectionToken, Module, PipelineRunner, Req, VelaFactory, buildEntrypointExecutionContext, createParamDecorator, defineMetadata, defineProvider, getEntrypointModuleId, getMetadata, getTrustedRequestIdentity, parseCron, registerEntrypointKind, resolveEntrypoint, resolveErrorReporter, resolveScopedComponentsAsync, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
-import { ConnectedSocket, DEFAULT_WS_MAX_FRAME_BYTES, MessageBody, SubscribeMessage, WS_GATEWAY_METADATA, WS_SERVER, WebSocketGateway, WebSocketServer, WsDispatcher, WsException, assertBroadcastCommandFits, authenticateWebSocketUpgrade, readWsEntrypointMeta, resolveGatewayRoomId, resolveGatewayRoomParam, resolveMaxFrameBytes } from "@velajs/vela/websocket";
+import { ConfigurableModuleBuilder, Controller, Get, Inject, Injectable, InjectionToken, Module, PipelineRunner, Req, SCHEDULE_INVOCATION_SEED, Scope, VelaFactory, buildEntrypointExecutionContext, cronDialectAmbiguity, defineMetadata, defineProvider, getEntrypointModuleId, getMetadata, getTrustedRequestIdentity, invokeScheduledJob, parseCronMetadata, parseIntervalMetadata, registerEntrypointKind, resolveEntrypoint, resolveErrorReporter, resolveScopedComponentsAsync, runInEntrypointScope, scheduledJobComponents, shouldFilterCatch } from "@velajs/vela";
+import { ConnectedSocket, DEFAULT_WS_MAX_FRAME_BYTES, MessageBody, SubscribeMessage, WS_GATEWAY_METADATA, WS_SERVER, WebSocketGateway, WebSocketServer, WsDispatcher, WsException, assertBroadcastCommandFits, createWebSocketUpgradeGate, readWsEntrypointMeta, resolveGatewayRoomId, resolveGatewayRoomParam, resolveMaxFrameBytes } from "@velajs/vela/websocket";
 import { STORAGE_SIGNED_URL_PURPOSE, joinStoragePath, signUrl, verifySignedUrl } from "@velajs/vela/storage";
 //#region src/websocket/websocket-routing.ts
 const MAX_IDENTITY_FIELD_BYTES = 2048;
@@ -33,64 +33,80 @@ function combineIdentities(requestIdentity, upgradeIdentity) {
 		expiresAtMs: Math.min(requestIdentity.expiresAtMs, upgradeIdentity.expiresAtMs)
 	};
 }
-/** Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted gateways only). */
-function collectWsGatewayRoutes(instance) {
+/** An instance's constructor is the class token its module registered. */
+function isClass(value) {
+	return typeof value === "function";
+}
+/**
+* Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted
+* gateways only). The application container names the module that declares the
+* gateway when exactly one module registers it.
+*/
+function collectWsGatewayRoutes(instance, container) {
 	const options = getMetadata(WS_GATEWAY_METADATA, instance.constructor);
 	if (!options?.path || !options?.binding) return [];
 	resolveGatewayRoomParam(options);
 	resolveMaxFrameBytes(options);
+	const gateway = instance.constructor;
+	const owners = isClass(gateway) ? container.getOwnerModuleIds(gateway) : [];
 	return [{
 		path: options.path,
 		binding: options.binding,
-		options: { ...options }
+		options: { ...options },
+		...owners.length === 1 ? { moduleId: owners[0] } : {}
 	}];
 }
 /**
 * 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.
+* the `Upgrade` header, authenticates through the gateway's authenticator
+* (resolved once from `container`, the application's DI container), 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 headers = new Headers(c.req.raw.headers);
-		headers.delete("x-vela-room");
-		headers.delete("x-vela-path");
-		headers.delete("x-vela-user");
-		headers.delete("x-vela-expires-at");
-		headers.delete("x-vela-expires-at-ms");
-		headers.delete("x-vela-issuer");
-		headers.delete("x-vela-subject");
-		headers.delete("x-vela-principal-type");
-		headers.delete("x-vela-tenant");
-		const sanitizedRequest = new Request(c.req.raw, { headers });
-		let roomId;
-		try {
-			roomId = resolveGatewayRoomId(route.options, (name) => c.req.param(name));
-		} catch {
-			return c.text("Invalid WebSocket room", 400);
-		}
-		const upgrade = await authenticateWebSocketUpgrade(route.options, sanitizedRequest, roomId);
-		if (upgrade === false) return c.text("WebSocket upgrade forbidden", 403);
-		const requestIdentity = accessIdentity(c);
-		if (requestIdentity === null) return c.text("Invalid WebSocket identity", 403);
-		const identity = combineIdentities(requestIdentity, upgrade.identity);
-		if (identity === null) return c.text("Conflicting WebSocket identities", 403);
-		if (identity && identity.expiresAtMs <= Date.now()) return c.text("WebSocket identity expired", 403);
-		const forwardHeaders = new Headers(upgrade.request.headers);
-		forwardHeaders.set("x-vela-room", roomId);
-		forwardHeaders.set("x-vela-path", route.path);
-		if (identity) {
-			forwardHeaders.set("x-vela-user", identity.principal.subject);
-			forwardHeaders.set("x-vela-issuer", identity.principal.issuer);
-			forwardHeaders.set("x-vela-subject", identity.principal.subject);
-			forwardHeaders.set("x-vela-principal-type", identity.principal.principalType);
-			forwardHeaders.set("x-vela-tenant", identity.tenantId);
-			forwardHeaders.set("x-vela-expires-at-ms", String(identity.expiresAtMs));
-		}
-		return forwardToRoom(c.env, route.binding, route.path, roomId, new Request(upgrade.request, { headers: forwardHeaders }));
-	});
+function registerWebSocketRoutes(hono, routes, container) {
+	for (const route of routes) {
+		const authenticate = createWebSocketUpgradeGate(container, route);
+		hono.get(route.path, async (c) => {
+			if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return c.text("Expected WebSocket upgrade", 426);
+			const headers = new Headers(c.req.raw.headers);
+			headers.delete("x-vela-room");
+			headers.delete("x-vela-path");
+			headers.delete("x-vela-user");
+			headers.delete("x-vela-expires-at");
+			headers.delete("x-vela-expires-at-ms");
+			headers.delete("x-vela-issuer");
+			headers.delete("x-vela-subject");
+			headers.delete("x-vela-principal-type");
+			headers.delete("x-vela-tenant");
+			const sanitizedRequest = new Request(c.req.raw, { headers });
+			let roomId;
+			try {
+				roomId = resolveGatewayRoomId(route.options, (name) => c.req.param(name));
+			} catch {
+				return c.text("Invalid WebSocket room", 400);
+			}
+			const upgrade = await authenticate(sanitizedRequest, roomId);
+			if (upgrade === false) return c.text("WebSocket upgrade forbidden", 403);
+			const requestIdentity = accessIdentity(c);
+			if (requestIdentity === null) return c.text("Invalid WebSocket identity", 403);
+			const identity = combineIdentities(requestIdentity, upgrade.identity);
+			if (identity === null) return c.text("Conflicting WebSocket identities", 403);
+			if (identity && identity.expiresAtMs <= Date.now()) return c.text("WebSocket identity expired", 403);
+			const forwardHeaders = new Headers(upgrade.request.headers);
+			forwardHeaders.set("x-vela-room", roomId);
+			forwardHeaders.set("x-vela-path", route.path);
+			if (identity) {
+				forwardHeaders.set("x-vela-user", identity.principal.subject);
+				forwardHeaders.set("x-vela-issuer", identity.principal.issuer);
+				forwardHeaders.set("x-vela-subject", identity.principal.subject);
+				forwardHeaders.set("x-vela-principal-type", identity.principal.principalType);
+				forwardHeaders.set("x-vela-tenant", identity.tenantId);
+				forwardHeaders.set("x-vela-expires-at-ms", String(identity.expiresAtMs));
+			}
+			return forwardToRoom(c.env, route.binding, route.path, roomId, new Request(upgrade.request, { headers: forwardHeaders }));
+		});
+	}
 }
 /**
 * Gateway metadata contains a runtime binding name, so the native type is
@@ -114,12 +130,70 @@ async function forwardToRoom(env, binding, path, room, request) {
 	return response;
 }
 //#endregion
-//#region src/cloudflare-application.ts
-registerEntrypointKind({
-	kind: "cf:vela-cron",
-	metaKey: CRON_METADATA,
-	level: "method"
+//#region src/scheduled-event.ts
+/**
+* Request-scoped Cloudflare view of the scheduled trigger, seeded into each
+* `@Cron` job's invocation scope by the Cloudflare adapter. Inject it where a
+* job needs platform controls such as `noRetry()`; the job's argument stays
+* the portable `ScheduleInvocation`. It resolves only inside a scheduled
+* invocation; resolving it anywhere else throws. A cron job fired on demand
+* (Studio's run-now) receives a synthetic event: `cron` is the job's
+* expression and `noRetry()` does nothing.
+*
+* The token provides itself as request-scoped in every container, so a class
+* that injects it is request-scoped wherever the graph boots (a Worker, a
+* Durable Object, the CLI or a testing module) and is built only for an
+* invocation, never at bootstrap.
+*
+* @example
+* ```ts
+* @Injectable({ scope: Scope.REQUEST })
+* class Reports {
+*   constructor(@Inject(CLOUDFLARE_SCHEDULED_EVENT) private readonly trigger: CloudflareScheduledEvent) {}
+*
+*   @Cron('0 3 * * *', { dialect: 'cloudflare' })
+*   async nightly(tick: CronInvocation) {
+*     if (!(await this.upstreamAvailable(tick.signal))) this.trigger.noRetry();
+*   }
+* }
+* ```
+*/
+const CLOUDFLARE_SCHEDULED_EVENT = new InjectionToken("@velajs/cloudflare:scheduled-event", {
+	scope: Scope.REQUEST,
+	factory: () => {
+		throw new Error("CLOUDFLARE_SCHEDULED_EVENT can only be resolved inside a scheduled invocation: the Cloudflare adapter seeds it into each @Cron job scope for a cron trigger.");
+	}
 });
+/** @internal Freeze the injected view; `noRetry` keeps the native receiver. */
+function cloudflareScheduledEvent(event, scheduledTime) {
+	return Object.freeze({
+		cron: event.cron,
+		scheduledTime,
+		noRetry: () => {
+			event.noRetry?.();
+		}
+	});
+}
+/**
+* Seeds a cron job fired outside a trigger (Studio's run-now) the way a
+* trigger would: a synthetic event whose `cron` is the invocation's
+* expression, with its `scheduledTime` and a `noRetry()` that does nothing.
+* Interval jobs never run from Workers triggers, so they get no event.
+*/
+const seedScheduledEvent = (scope, invocation) => {
+	if (invocation.kind !== "cron") return;
+	scope.setRequestInstance(CLOUDFLARE_SCHEDULED_EVENT, cloudflareScheduledEvent({ cron: invocation.expression }, invocation.scheduledTime));
+};
+/**
+* @internal Provide `SCHEDULE_INVOCATION_SEED`, so jobs fired on demand get a
+* synthetic event. Each trigger seeds the real event into its jobs' scopes.
+*/
+function registerScheduledEventSeed(container) {
+	container.register(defineProvider(SCHEDULE_INVOCATION_SEED, { useValue: seedScheduledEvent }));
+	container.markGlobalToken(SCHEDULE_INVOCATION_SEED);
+}
+//#endregion
+//#region src/cloudflare-application.ts
 function invoke(instance, methodName, args) {
 	const method = Reflect.get(instance, methodName);
 	if (typeof method !== "function") throw new Error(`Method '${String(methodName)}' is not a function on ${instance.constructor.name}`);
@@ -131,6 +205,20 @@ function entrypointString(meta, property) {
 	if (typeof value !== "string") throw new Error(`Invalid entrypoint metadata: ${property} must be a string.`);
 	return value;
 }
+/**
+* `QueueModule`'s native consumer reports each failure of a batch once itself
+* (processor failures where they ran, transport failures on settlement), so
+* its rejection is not reported again here.
+*/
+const SELF_REPORTING_KINDS = /* @__PURE__ */ new Set(["cf:queue:module"]);
+const warnedRawJobs = /* @__PURE__ */ new Set();
+/** The logical queue of a Vela job envelope, without importing the queue subsystem. */
+function envelopeQueue(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	const queue = Reflect.get(body, "queue");
+	if (typeof queue !== "string" || typeof Reflect.get(body, "id") !== "string" || typeof Reflect.get(body, "name") !== "string" || !("data" in body)) return;
+	return queue;
+}
 /** Wait for every matching handler, even when one fails before its siblings. */
 async function settleEntrypoints(work) {
 	const errors = (await Promise.allSettled(work)).flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason] : []);
@@ -140,15 +228,16 @@ async function settleEntrypoints(work) {
 /**
 * 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)
+* - `scheduled` — Cron trigger handler (runs the `@Cron()` jobs whose
+*                 expression is the trigger's exact string)
+* - `queue` — Queue consumer handler (`@QueueConsumer()` by physical queue,
+*             then `QueueModule`'s native consumer)
 * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
 *                    the underlying Hono app
 *
 * @example
 * ```ts
-* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+* const app = await createCloudflareApp(AppModule, { env });
 * export default {
 *   fetch: app.fetch,
 *   scheduled: app.scheduled.bind(app),
@@ -159,7 +248,7 @@ async function settleEntrypoints(work) {
 * @example
 * ```ts
 * // Serve OpenAPI docs alongside your routes
-* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+* const app = await createCloudflareApp(AppModule, { env });
 * const document = createOpenApiDocument(AppModule);
 * app.mountOpenApi({ document, ui: 'scalar' });
 * // GET /openapi.json -> JSON document
@@ -170,6 +259,8 @@ var CloudflareApplication = class {
 	env;
 	#wsGatewayRoutes = [];
 	#app;
+	/** Scheduled triggers in flight; close() aborts their signals and awaits them. */
+	#scheduled = /* @__PURE__ */ new Map();
 	constructor(app, env) {
 		this.env = env;
 		this.#app = app;
@@ -190,7 +281,7 @@ var CloudflareApplication = class {
 	*
 	* @example
 	* ```ts
-	* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+	* const app = await createCloudflareApp(AppModule, { env });
 	* const auth = app.get(BetterAuthService);
 	* ```
 	*/
@@ -209,7 +300,7 @@ var CloudflareApplication = class {
 	* ```ts
 	* import { createOpenApiDocument } from '@velajs/vela';
 	*
-	* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+	* const app = await createCloudflareApp(AppModule, { env });
 	* const document = createOpenApiDocument(AppModule, {
 	*   info: { title: 'My API', version: '1.0.0' },
 	* });
@@ -235,12 +326,14 @@ var CloudflareApplication = class {
 			if (meta.options.binding) routes.set(meta.path, {
 				path: meta.path,
 				binding: meta.options.binding,
-				options: { ...meta.options }
+				options: { ...meta.options },
+				moduleId: meta.moduleId
 			});
 		}
+		const container = this.#app.getContainer();
 		for (const instance of instances) {
 			if (!instance || typeof instance !== "object") continue;
-			for (const route of collectWsGatewayRoutes(instance)) if (!routes.has(route.path)) routes.set(route.path, route);
+			for (const route of collectWsGatewayRoutes(instance, container)) if (!routes.has(route.path)) routes.set(route.path, route);
 		}
 		this.#wsGatewayRoutes.splice(0, this.#wsGatewayRoutes.length, ...routes.values());
 	}
@@ -249,28 +342,45 @@ var CloudflareApplication = class {
 		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).
+	* Handle a Cloudflare cron trigger. Runs every core `@Cron()` job whose
+	* expression is exactly `event.cron` (the trigger string is compared as
+	* delivered, never re-evaluated) through `invokeScheduledJob`, the dispatch
+	* primitive every runtime shares. Each job receives only its
+	* `ScheduleInvocation`, runs in a fresh invocation scope seeded with
+	* {@link CLOUDFLARE_SCHEDULED_EVENT}, and honors signed `ScheduleModule`
+	* dispatch. The trigger settles after every matching job and its managed
+	* work (`EXECUTION_LIFETIME.waitUntil`/`defer`) settle; failures reject it.
 	*/
-	async scheduled(event, env, ctx) {
+	async scheduled(event, env, _ctx) {
 		assertCloudflareEnvironment(this.env, env);
-		await settleEntrypoints([...this.#app.entrypoints.ofKind("cf:scheduled").map((ep) => ({
-			ep,
-			cron: entrypointString(ep.meta, "cron")
-		})), ...this.#app.entrypoints.ofKind("cf:vela-cron").map((ep) => ({
-			ep,
-			cron: entrypointString(ep.meta, "expression")
-		}))].filter((h) => h.cron === event.cron).map(({ ep }) => this.dispatchEntrypoint(ep, event, env, ctx)));
+		const jobs = this.#app.entrypoints.ofKind("schedule:cron", parseCronMetadata).filter((entry) => entry.meta.expression === event.cron);
+		if (jobs.length === 0) return;
+		const controller = new AbortController();
+		const scheduledTime = event.scheduledTime ?? Date.now();
+		const invocation = Object.freeze({
+			kind: "cron",
+			expression: event.cron,
+			scheduledTime,
+			signal: controller.signal
+		});
+		const trigger = cloudflareScheduledEvent(event, scheduledTime);
+		const container = this.#app.getContainer();
+		const running = settleEntrypoints(jobs.map((entry) => invokeScheduledJob(container, entry, invocation, { seed: (scope) => scope.setRequestInstance(CLOUDFLARE_SCHEDULED_EVENT, trigger) })));
+		this.#scheduled.set(running, controller);
+		try {
+			await running;
+		} finally {
+			this.#scheduled.delete(running);
+		}
 	}
 	/**
-	* Run one entrypoint handler inside a fresh request scope, through the
-	* shared guard → interceptor pipeline (components declared with
+	* Run one queue consumer 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.
+	* guard has no business rejecting a queue batch. Unclaimed errors are
+	* reported once (`QueueModule`'s consumer reports its own) and rethrow so
+	* the platform's retry semantics stay intact.
 	*/
 	async dispatchEntrypoint(ep, payload, env, platformContext) {
 		const targetClass = ep.token;
@@ -278,10 +388,11 @@ var CloudflareApplication = class {
 		if (ep.methodName === void 0) throw new Error("Entrypoint must declare a handler method.");
 		const methodName = ep.methodName;
 		const reportContext = {
-			edge: ep.kind === "cf:queue" ? "queue" : "schedule",
+			edge: "queue",
 			source: `${targetClass.name}.${String(methodName)}`
 		};
 		let reported;
+		let delegated;
 		try {
 			await runInEntrypointScope(this.#app.getContainer(), async (scope, lifetime) => {
 				const moduleId = getEntrypointModuleId(scope, ep);
@@ -307,11 +418,16 @@ var CloudflareApplication = class {
 						invoke: async (args) => {
 							const instance = await resolveEntrypoint(scope, ep);
 							if (typeof instance !== "object" || instance === null) throw new Error("Entrypoint must resolve to an object.");
-							return invoke(instance, methodName, args);
+							try {
+								return await invoke(instance, methodName, args);
+							} catch (error) {
+								if (SELF_REPORTING_KINDS.has(ep.kind)) delegated = { error };
+								throw error;
+							}
 						}
 					});
 				} catch (error) {
-					resolveErrorReporter(scope).report(error, reportContext);
+					if (delegated?.error !== error) resolveErrorReporter(scope).report(error, reportContext);
 					for (const filter of filters) if (shouldFilterCatch(filter, error)) {
 						await filter.catch(error, context);
 						return;
@@ -329,58 +445,173 @@ var CloudflareApplication = class {
 		}
 	}
 	/**
-	* 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).
+	* Handle Cloudflare Queue consumer events. `@QueueConsumer()` handlers read
+	* from `app.entrypoints` claim a batch by its physical queue name and
+	* receive it whole. A batch no handler claims goes to `QueueModule`'s native
+	* consumer (`cloudflareQueues()` from `@velajs/cloudflare/queues`), which
+	* routes each job by its logical queue. Each dispatch runs inside a fresh
+	* request-scoped child (request-scoped providers rebuild per batch — no
+	* boot-time captives). A batch nothing claims rejects: resolving would let
+	* Cloudflare acknowledge every message implicitly.
 	*/
 	async queue(batch, env, ctx) {
 		assertCloudflareEnvironment(this.env, env);
-		await settleEntrypoints(this.#app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue).map((ep) => this.dispatchEntrypoint(ep, batch, env, ctx)));
+		const raw = this.#app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue);
+		if (raw.length > 0) this.warnRawJobs(batch);
+		const handlers = raw.length > 0 ? raw : this.#app.entrypoints.ofKind("cf:queue:module");
+		if (handlers.length === 0) throw new Error(`No consumer claims queue '${batch.queue}'. Add @QueueConsumer('${batch.queue}') to a provider, or deliver it through QueueModule.forRoot({ driver: cloudflareQueues() }) with a QueueModule.registerQueue() for each queue it carries. The batch is rejected unacknowledged, so Cloudflare retries it and then routes it to the configured dead-letter queue.`);
+		await settleEntrypoints(handlers.map((ep) => this.dispatchEntrypoint(ep, batch, env, ctx)));
 	}
+	/**
+	* A raw `@QueueConsumer` owns its physical queue's batches and must not carry
+	* jobs of a queue registered with `QueueModule`: those reach their
+	* `@Processor` only if the raw handler dispatches them itself, while
+	* `cloudflareQueues()` delivers registered queues. Warn once per physical and
+	* logical queue (unless diagnostics are silent); the raw consumer still
+	* receives and settles the batch.
+	*/
+	warnRawJobs(batch) {
+		if (this.#app.getContainer().getDiagnostics() === "silent") return;
+		const registered = new Set(this.#app.entrypoints.ofKind("queue:registration").map((entry) => typeof entry.meta === "object" && entry.meta !== null ? Reflect.get(entry.meta, "name") : void 0));
+		if (registered.size === 0) return;
+		for (const message of batch.messages) {
+			const queue = envelopeQueue(typeof message === "object" && message !== null ? Reflect.get(message, "body") : void 0);
+			if (queue === void 0 || !registered.has(queue)) continue;
+			const warning = `[vela] @QueueConsumer('${batch.queue}') received jobs of registered queue '${queue}'. The raw consumer owns '${batch.queue}' and must not carry jobs of registered queues: they reach @Processor('${queue}') only if the raw handler dispatches them itself. Deliver '${queue}' through cloudflareQueues() instead: send it to a physical queue that no @QueueConsumer claims.`;
+			if (warnedRawJobs.has(warning)) continue;
+			warnedRawJobs.add(warning);
+			console.warn(warning);
+		}
+	}
+	/**
+	* Abort the signals of scheduled jobs still running, wait for them and their
+	* managed work to settle, then close the application.
+	*/
 	async close(signal) {
+		for (const controller of this.#scheduled.values()) controller.abort();
+		await Promise.allSettled(this.#scheduled.keys());
 		return this.#app.close(signal);
 	}
 };
 //#endregion
+//#region src/schedule-diagnostics.ts
+const reported = /* @__PURE__ */ new Set();
+/** `'throw'` fails the caller, `'log'` warns once per message in this isolate. */
+function reportScheduleDiagnostic(container, message) {
+	const mode = container.getDiagnostics();
+	if (mode === "silent") return;
+	if (mode === "throw") throw new Error(message);
+	if (reported.has(message)) return;
+	reported.add(message);
+	console.warn(message);
+}
+function jobName(entry) {
+	return `${typeof entry.token === "function" ? entry.token.name : String(entry.token)}.${entry.meta.methodName}`;
+}
+/**
+* Guards, interceptors and filters declared for a job never run on its
+* trigger, and a direct job that declares guards is refused on every trigger.
+*/
+function reportComponents(container, label, entry) {
+	const decorators = scheduledJobComponents(container, entry);
+	if (decorators.length === 0) return;
+	reportScheduleDiagnostic(container, `[vela] ${label} declares ${decorators.length > 1 ? `${decorators.slice(0, -1).join(", ")} and ${decorators.at(-1)}` : decorators.join("")}, which do not run for scheduled jobs: a direct job runs no guards, interceptors or filters${decorators.includes("@UseGuards") ? ", and one that declares guards refuses to run" : ""}. Use signed ScheduleModule dispatch and declare them on the signed route to run the job through the request pipeline.`);
+}
+/**
+* Report schedule declarations a Workers cron trigger cannot honor as written:
+* a dialect-ambiguous `@Cron`, `dialect: 'unix'`, `timeZone: 'local'`,
+* `@Interval` jobs, and guards, interceptors or filters declared for a job
+* (a direct job that declares guards is refused when it fires).
+* The container's diagnostics policy applies: `'throw'` fails bootstrap and the
+* default `'log'` warns once per declaration, so the first event of a Worker
+* (which bootstraps the application) never fails because of these checks.
+* `vela deploy check` rejects the cron declarations, `@Interval` jobs and
+* guarded direct jobs before deployment (`ambiguous-cron-dialect`,
+* `incompatible-cron-options`, `unsupported-interval`, `scheduled-job-guards`).
+*/
+function reportCloudflareScheduleDiagnostics(container, entrypoints) {
+	for (const entry of entrypoints.ofKind("schedule:cron", parseCronMetadata)) {
+		const cron = `@Cron('${entry.meta.expression}') on ${jobName(entry)}`;
+		const ambiguity = cronDialectAmbiguity(entry.meta);
+		if (ambiguity) reportScheduleDiagnostic(container, `[vela] ${cron} declares no dialect, and ${ambiguity}. Workers deliver the trigger with Cloudflare semantics while Node reads it with Vela's unix dialect; declare { dialect: 'cloudflare' } so it fires on the same days on every runtime.`);
+		if (entry.meta.dialect === "unix") reportScheduleDiagnostic(container, `[vela] ${cron} declares dialect 'unix', but Cloudflare delivers its trigger with Cloudflare cron semantics (weekdays 1 = Sunday through 7 = Saturday). Declare { dialect: 'cloudflare' } and write the expression for Cloudflare.`);
+		if (entry.meta.timeZone === "local") reportScheduleDiagnostic(container, `[vela] ${cron} declares timeZone 'local', but Cloudflare cron triggers run in UTC. Remove timeZone or set it to 'UTC'.`);
+		reportComponents(container, cron, entry);
+	}
+	for (const entry of entrypoints.ofKind("schedule:interval", parseIntervalMetadata)) reportScheduleDiagnostic(container, `[vela] @Interval(${entry.meta.ms}) on ${jobName(entry)} never runs on Workers: cron triggers drive only @Cron jobs. Replace it with a @Cron job and a Wrangler trigger, or run it under ScheduleNodeModule on Node.`);
+}
+//#endregion
 //#region src/cloudflare-factory.ts
-/** Bind an application to one environment before provider factories and lifecycle hooks. */
+function readStrings(meta, property) {
+	const value = typeof meta === "object" && meta !== null ? Reflect.get(meta, property) : void 0;
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value;
+	throw new TypeError(`Invalid queue consumer metadata: ${property}.`);
+}
+/**
+* `@QueueConsumer` handlers own their physical queue. A `QueueModule`
+* registration that pins the same physical queue with `consumer` would never
+* see its batches, so bootstrap rejects the overlap.
+*/
+function assertQueueConsumerOwnership(entrypoints) {
+	const pinned = new Set(entrypoints.ofKind("cf:queue:module").flatMap((entry) => readStrings(entry.meta, "consumers")));
+	for (const entry of entrypoints.ofKind("cf:queue")) {
+		const [queue] = readStrings(entry.meta, "queueName");
+		if (queue !== void 0 && pinned.has(queue)) throw new Error(`Ambiguous consumer ownership for queue '${queue}': @QueueConsumer('${queue}') and a QueueModule.registerQueue({ consumer: '${queue}' }) both claim it. Keep one owner.`);
+	}
+}
+/**
+* Bind an application to one environment: seeded as the global ENV before
+* provider factories and lifecycle hooks, and asserted on every request. The
+* adapter also supplies the `InternalDispatcher` transport, so signed queue and
+* schedule dispatch re-enter this application's routes, and reports schedule
+* declarations a cron trigger cannot honor through the diagnostics policy.
+*/
 function cloudflareAdapter(options) {
+	const { env } = options;
 	return {
 		name: "cloudflare",
 		requestMiddleware: [async (context, next) => {
-			assertCloudflareEnvironment(options.env, context.env);
+			assertCloudflareEnvironment(env, context.env);
 			await next();
 		}],
-		invocationTransport: ({ app }) => (request) => Promise.resolve(app.fetch(request, options.env)),
+		invocationTransport: ({ app }) => (request) => Promise.resolve(app.fetch(request, env)),
 		getClientIp: (c) => getConnInfo(c).remote.address ?? null,
 		configureContainer: (container) => {
-			registerCloudflareEnvironment(container, {
-				token: options.envToken,
-				env: options.env
-			});
+			registerCloudflareEnvironment(container, env);
+			registerScheduledEventSeed(container);
+		},
+		onBootstrap: async ({ app, container }) => {
+			assertQueueConsumerOwnership(app.entrypoints);
+			reportCloudflareScheduleDiagnostics(container, app.entrypoints);
+			await warnWorkerLocalLive(container);
 		}
 	};
 }
-/** Build an application for one native Workers environment. Call inside a platform event. */
+/**
+* Build an application for one native Workers environment. Call inside a platform event.
+* The root is static: a module class or a `DynamicModule` declared at module scope.
+* Read bindings in providers (`@InjectEnv()`) and module factories
+* (`forRootAsync({ inject: [ENV], useFactory })`), which run for each application.
+*/
 async function createCloudflareApp(rootModule, options) {
-	const velaApp = await VelaFactory.create(resolveCloudflareRoot(rootModule, options.env), {
+	const velaApp = await VelaFactory.create(rootModule, {
 		globalPrefix: options.globalPrefix,
 		security: options.security,
 		middleware: options.middleware?.(options.env),
-		adapters: [cloudflareAdapter(options)]
+		adapters: [cloudflareAdapter(options), ...options.adapters ?? []]
 	});
 	const app = new CloudflareApplication(velaApp, options.env);
 	app.scanInstances(velaApp.getInstances());
-	registerWebSocketRoutes(app.getHonoApp(), app.getWsGatewayRoutes());
+	registerWebSocketRoutes(app.getHonoApp(), app.getWsGatewayRoutes(), velaApp.getContainer());
 	return app;
 }
 /**
-* Worker entrypoint with one bootstrap per environment identity. Weak keys let
-* obsolete environments and secrets be collected. Concurrent cold events share
-* construction; failed construction is evicted so the next event can retry.
+* Worker entrypoint with one bootstrap per environment identity. Concurrent cold
+* events share construction; failed construction is evicted so the next event
+* can retry. Weak keys stop this cache from retaining a replaced environment.
 */
-function createCloudflareWorker(rootModule, options) {
+function createCloudflareWorker(rootModule, options = {}) {
 	const applications = /* @__PURE__ */ new WeakMap();
 	const application = (env) => {
 		const existing = applications.get(env);
@@ -893,75 +1124,6 @@ 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: WorkerEnv) { ... }
-*
-* @Get()
-* handle(@Env('MY_KV') kv: KVNamespace) { ... }
-* ```
-*/
-const Env = createParamDecorator((bindingName, ctx) => {
-	const env = ctx.getContext().env;
-	if (typeof env !== "object" || env === null) return void 0;
-	return bindingName ? Reflect.get(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"
-});
-function parseScheduledMetadata(value) {
-	if (typeof value !== "object" || value === null || !("cron" in value) || typeof value.cron !== "string" || !("methodName" in value) || typeof value.methodName !== "string" || !parseCron(value.cron, { dialect: "cloudflare" })) throw new TypeError("Invalid Cloudflare scheduled metadata");
-	return {
-		cron: value.cron,
-		methodName: value.methodName
-	};
-}
-/**
-* Marks a method as a scheduled (cron) handler.
-*
-* @example
-* ```ts
-* @Injectable()
-* class WorkerService {
-*   @Scheduled('0 * * * *')
-*   async hourlyCron() {
-*     console.log('Running hourly');
-*   }
-* }
-* ```
-*/
-function Scheduled(cron) {
-	if (!parseCron(cron, { dialect: "cloudflare" })) throw new TypeError(`Invalid Cloudflare cron expression: ${cron}`);
-	return (target, propertyKey, _descriptor) => {
-		const existing = getScheduledMetadata(target);
-		existing.push({
-			cron,
-			methodName: String(propertyKey)
-		});
-		defineMetadata(SCHEDULED_METADATA_KEY, existing, target.constructor);
-	};
-}
-function getScheduledMetadata(target) {
-	const ctor = typeof target === "function" ? target : target.constructor;
-	const value = getMetadata(SCHEDULED_METADATA_KEY, ctor);
-	if (value === void 0) return [];
-	if (!Array.isArray(value)) throw new TypeError("Invalid Cloudflare scheduled metadata list");
-	return value.map(parseScheduledMetadata);
-}
-//#endregion
 //#region src/decorators/queue-consumer.ts
 const QUEUE_CONSUMER_METADATA_KEY = "cloudflare:queue-consumer";
 registerEntrypointKind({
@@ -1109,6 +1271,6 @@ function durableObjectNonceStore(options) {
 	} };
 }
 //#endregion
-export { CloudflareApplication, CloudflareWebSocketModule, ConnectedSocket, DoCursorLog, DoPitrUnavailableError, Env, FlagshipFlagDriver, KVCacheInvalidationStore, KVCacheStore, KvFlagDriver, MessageBody, QueueConsumer, R2StorageDriver, STORAGE_OPTIONS, Scheduled, StorageController, StorageManagerService, StorageModule, StorageService, SubscribeMessage, WebSocketGateway, WebSocketServer, WsException, armDoPitr, broadcastToRoom, cloudflareAdapter, cloudflareRateLimitStore, createCloudflareApp, createCloudflareWorker, durableObjectCursorLog, durableObjectLive, durableObjectNonceStore, durableObjectRoomName, flagshipFlagDriver, isDoPitrUnavailable, kvFlagDriver, liveInvalidateToRoom, parseScheduledMetadata, readDoPitrBookmark };
+export { CLOUDFLARE_SCHEDULED_EVENT, CloudflareApplication, CloudflareWebSocketModule, ConnectedSocket, DoCursorLog, DoPitrUnavailableError, FlagshipFlagDriver, KVCacheInvalidationStore, KVCacheStore, KvFlagDriver, MessageBody, QueueConsumer, R2StorageDriver, STORAGE_OPTIONS, StorageController, StorageManagerService, StorageModule, StorageService, SubscribeMessage, WebSocketGateway, WebSocketServer, WsException, armDoPitr, broadcastToRoom, cloudflareAdapter, cloudflareRateLimitStore, createCloudflareApp, createCloudflareWorker, durableObjectCursorLog, durableObjectLive, durableObjectNonceStore, durableObjectRoomName, flagshipFlagDriver, isDoPitrUnavailable, kvFlagDriver, liveInvalidateToRoom, readDoPitrBookmark };
 
 //# sourceMappingURL=index.js.map