@velajs/cloudflare 1.22.1 → 1.24.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { a as DoPitrId, c as DoPitrUnavailableError, d as isDoPitrUnavailable, f as readDoPitrBookmark, i as DoPitrBookmarkRead, l as VelaDoPitrRpc, n as DoPitrArmOptions, o as DoPitrNamespace, p as CloudflareRoot, r as DoPitrArmResult, s as DoPitrStorage, t as VelaNonceDurableObject, u as armDoPitr } from "./nonce.durable-object-Df3_42Sy.js";
-import { AsyncCacheStore, DynamicModule, InjectionToken, NonceStore, RuntimeAdapter, ThrottlerStore, Type, VelaApplication, VelaMiddlewareHandler, VelaSecurityOptions } from "@velajs/vela";
-import { BroadcastCommand, ConnectedSocket, MessageBody, OnGatewayConnection, OnGatewayDisconnect, OnGatewayInit, SubscribeMessage, WebSocketGateway, WebSocketGatewayOptions, WebSocketServer, WsClient, WsDispatcher, WsException, WsMessage, WsResponse, WsServer } from "@velajs/vela/websocket";
+import { AsyncCacheStore, CacheEntry, CacheEntryReader, CacheEntryWriter, CacheInvalidationStore, DynamicModule, InjectionToken, NonceStore, RuntimeAdapter, ThrottlerStore, Type, VelaApplication, VelaMiddlewareHandler, VelaSecurityOptions } from "@velajs/vela";
+import { BroadcastCommand, ConnectedSocket, MessageBody, OnGatewayConnection, OnGatewayDisconnect, OnGatewayInit, SubscribeMessage, WebSocketGateway, WebSocketGatewayOptions, WebSocketSendGate, WebSocketServer, WsClient, WsDispatcher, WsException, WsMessage, WsResponse, WsServer } from "@velajs/vela/websocket";
 import { DownloadResult, PresignMethod, PresignedUrlResult, StorageBody, StorageDriver, UploadOptions, UploadResult } from "@velajs/vela/storage";
 import { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveEngine, LiveInvalidationSink, ResumeVerdict } from "@velajs/vela/live";
 import { Context, ExecutionContext } from "hono";
@@ -55,9 +55,8 @@ type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
  * ```
  */
 export declare class CloudflareApplication<T extends object = object> {
-  private app;
+  #private;
   readonly env: T;
-  private wsGatewayRoutes;
   constructor(app: VelaApplication, env: T);
   readonly fetch: (request: Request, env: T, ctx?: ExecutionContext) => Promise<Response>;
   getHonoApp(): ReturnType<VelaApplication['getHonoApp']>;
@@ -97,13 +96,12 @@ export declare class CloudflareApplication<T extends object = object> {
    */
   mountOpenApi(options: MountOpenApiOptions): 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.
+   * @internal Upgrade routes come from validated gateway entrypoints, including
+   * request-scoped gateways without a bootstrap instance. Retain the instance
+   * scan for legacy applications that only declare forwarding metadata.
    */
   scanInstances(instances: unknown[]): void;
-  /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+  /** @internal — upgrade routes discovered from the application's gateways. */
   getWsGatewayRoutes(): WsGatewayRoute[];
   /**
    * Handle Cloudflare scheduled (cron) events.
@@ -273,22 +271,36 @@ export declare const STORAGE_OPTIONS: InjectionToken<StorageModuleOptions>;
 //#endregion
 //#region src/services/kv-cache.store.d.ts
 /**
- * Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
- * the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
- * standalone from a typed environment factory: `new KVCacheStore(env.CACHE)`.
- * Reads return unknown JSON; validate values at the consuming boundary.
- *
- * Note: Cloudflare KV requires `expirationTtl >= 60s`, so sub-minute TTLs are
- * clamped up. Keep short TTLs on the memory tier; use KV for longer-lived entries.
+ * Native KV JSON value store. Metadata retains logical expiry even when KV's
+ * physical retention rounds up to its 60-second minimum. Legacy values without
+ * metadata remain readable, but cannot safely backfill another tier.
  */
-export declare class KVCacheStore implements AsyncCacheStore {
+export declare class KVCacheStore implements AsyncCacheStore, CacheEntryReader, CacheEntryWriter {
   private readonly ns;
   constructor(ns: KVNamespace);
   get(key: string): Promise<unknown>;
+  getEntry(key: string): Promise<{
+    value: unknown;
+    expiresAt?: number;
+  } | undefined>;
   set(key: string, value: unknown, ttl?: number): Promise<void>;
+  setEntry(key: string, entry: CacheEntry): Promise<void>;
   del(key: string): Promise<void>;
+  /** Namespace-wide, best effort. Use a dedicated value namespace; never use for scoped invalidation. */
   clear(): Promise<void>;
 }
+/**
+ * Optional, eventually consistent generation store. Use a dedicated KV namespace
+ * without TTL/lifecycle cleanup. Never delete/reset generations while entries can
+ * survive. Concurrent writes and cached/negative reads prevent strong invalidation;
+ * this is unsuitable for strict read-after-write or authorization revocation.
+ */
+export declare class KVCacheInvalidationStore implements CacheInvalidationStore {
+  private readonly ns;
+  constructor(ns: KVNamespace);
+  getVersion(key: string): Promise<string>;
+  invalidate(key: string): Promise<void>;
+}
 //#endregion
 //#region src/services/flagship-flag.driver.d.ts
 /**
@@ -414,6 +426,21 @@ interface ScheduledMetadata {
   cron: string;
   methodName: string;
 }
+/** Compatible with the existing programmatic scheduled() entrypoint. */
+interface ScheduledEvent {
+  readonly cron: string;
+  readonly scheduledTime?: number;
+}
+/** Native controller passed unchanged to a Worker handler. Call noRetry on its receiver. */
+interface ScheduledController extends ScheduledEvent {
+  readonly scheduledTime: number;
+  noRetry(): void;
+}
+interface ScheduledContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+type ScheduledHandler<Env extends object = object> = (controller: ScheduledController, env: Env, context: ScheduledContext) => void | Promise<void>;
+export declare function parseScheduledMetadata(value: unknown): ScheduledMetadata;
 /**
  * Marks a method as a scheduled (cron) handler.
  *
@@ -618,5 +645,5 @@ interface DurableObjectNonceStoreOptions {
  */
 export declare function durableObjectNonceStore(options: DurableObjectNonceStoreOptions): NonceStore;
 //#endregion
-export { type BroadcastNamespace, type CfLiveDriver, type CloudflareRateLimitBinding, type CloudflareRateLimitStoreOptions, type CloudflareRoot, type CloudflareWorkerOptions, ConnectedSocket, type CreateCloudflareAppOptions, type DiskConfig, type DoPitrArmOptions, type DoPitrArmResult, type DoPitrBookmarkRead, type DoPitrId, type DoPitrNamespace, type DoPitrStorage, DoPitrUnavailableError, type DurableObjectLiveOptions, type DurableObjectNonceNamespace, type DurableObjectNonceStoreOptions, type FlagshipBinding, type FlagshipFlagDriverOptions, type KvFlagDriverOptions, type LiveNamespace, MessageBody, type MountOpenApiOptions, type OnGatewayConnection, type OnGatewayDisconnect, type OnGatewayInit, type PresignedUrlConfig, type QueueConsumerMetadata, type ScheduledMetadata, type StorageModuleOptions, SubscribeMessage, type VelaDoPitrRpc, WebSocketGateway, WebSocketServer, type WsClient, WsException, type WsGatewayRoute, type WsMessage, type WsResponse, type WsServer, armDoPitr, isDoPitrUnavailable, readDoPitrBookmark };
+export { type BroadcastNamespace, type CfLiveDriver, type CloudflareRateLimitBinding, type CloudflareRateLimitStoreOptions, type CloudflareRoot, type CloudflareWorkerOptions, ConnectedSocket, type CreateCloudflareAppOptions, type DiskConfig, type DoPitrArmOptions, type DoPitrArmResult, type DoPitrBookmarkRead, type DoPitrId, type DoPitrNamespace, type DoPitrStorage, DoPitrUnavailableError, type DurableObjectLiveOptions, type DurableObjectNonceNamespace, type DurableObjectNonceStoreOptions, type FlagshipBinding, type FlagshipFlagDriverOptions, type KvFlagDriverOptions, type LiveNamespace, MessageBody, type MountOpenApiOptions, type OnGatewayConnection, type OnGatewayDisconnect, type OnGatewayInit, type PresignedUrlConfig, type QueueConsumerMetadata, type ScheduledContext, type ScheduledController, type ScheduledEvent, type ScheduledHandler, type ScheduledMetadata, type StorageModuleOptions, SubscribeMessage, type VelaDoPitrRpc, WebSocketGateway, WebSocketServer, type WsClient, WsException, type WsGatewayRoute, type WsMessage, type WsResponse, type WsServer, armDoPitr, isDoPitrUnavailable, readDoPitrBookmark };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,7 @@
-import { C as roomToDurableId, _ as resolveCloudflareRoot, a as durableObjectLive, c as liveInvalidateToRoom, d as WsServerHolder, f as DoPitrUnavailableError, g as __decorate, h as readDoPitrBookmark, i as durableObjectCursorLog, m as isDoPitrUnavailable, n as isValidExpiry, p as armDoPitr, r as DoCursorLog, t as isCanonicalBoundedText, v as assertCloudflareEnvironment, x as durableObjectRoomName, y as registerCloudflareEnvironment } from "./nonce-validation-LE0vFk-7.js";
+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 { getConnInfo } from "hono/cloudflare-workers";
-import { CRON_METADATA, ConfigurableModuleBuilder, Controller, Get, Inject, Injectable, InjectionToken, Module, PipelineRunner, Req, VelaFactory, buildEntrypointExecutionContext, createParamDecorator, defineMetadata, defineProvider, getMetadata, getTrustedRequestIdentity, registerEntrypointKind, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
-import { ComponentManager } from "@velajs/vela/internal";
-import { ConnectedSocket, DEFAULT_WS_MAX_FRAME_BYTES, MessageBody, SubscribeMessage, WS_GATEWAY_METADATA, WS_SERVER, WebSocketGateway, WebSocketServer, WsDispatcher, WsException, assertBroadcastCommandFits, authenticateWebSocketUpgrade, resolveGatewayRoomId, resolveGatewayRoomParam, resolveMaxFrameBytes } from "@velajs/vela/websocket";
+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 { STORAGE_SIGNED_URL_PURPOSE, joinStoragePath, signUrl, verifySignedUrl } from "@velajs/vela/storage";
 //#region src/websocket/websocket-routing.ts
 const MAX_IDENTITY_FIELD_BYTES = 2048;
@@ -123,7 +122,7 @@ registerEntrypointKind({
 });
 function invoke(instance, methodName, args) {
 	const method = Reflect.get(instance, methodName);
-	if (typeof method !== "function") throw new Error(`Method '${methodName}' is not a function on ${instance.constructor.name}`);
+	if (typeof method !== "function") throw new Error(`Method '${String(methodName)}' is not a function on ${instance.constructor.name}`);
 	return Reflect.apply(method, instance, args);
 }
 function entrypointString(meta, property) {
@@ -132,6 +131,12 @@ function entrypointString(meta, property) {
 	if (typeof value !== "string") throw new Error(`Invalid entrypoint metadata: ${property} must be a string.`);
 	return value;
 }
+/** 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] : []);
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Multiple entrypoint handlers failed.");
+}
 /**
 * Wraps VelaApplication with Cloudflare-specific handlers:
 * - `fetch` — HTTP request handler (from Hono)
@@ -162,20 +167,20 @@ function entrypointString(meta, property) {
 * ```
 */
 var CloudflareApplication = class {
-	app;
 	env;
-	wsGatewayRoutes = [];
+	#wsGatewayRoutes = [];
+	#app;
 	constructor(app, env) {
-		this.app = app;
 		this.env = env;
+		this.#app = app;
 		this.get = app.get.bind(app);
 	}
 	fetch = async (request, env, ctx) => {
 		assertCloudflareEnvironment(this.env, env);
-		return this.app.fetch(request, env, ctx);
+		return this.#app.fetch(request, env, ctx);
 	};
 	getHonoApp() {
-		return this.app.getHonoApp();
+		return this.#app.getHonoApp();
 	}
 	/**
 	* Resolve a provider from the application's DI container (delegates to
@@ -191,7 +196,7 @@ var CloudflareApplication = class {
 	*/
 	get;
 	get entrypoints() {
-		return this.app.entrypoints;
+		return this.#app.entrypoints;
 	}
 	/**
 	* Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
@@ -214,24 +219,34 @@ var CloudflareApplication = class {
 	* ```
 	*/
 	mountOpenApi(options) {
-		this.app.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.
+	* @internal Upgrade routes come from validated gateway entrypoints, including
+	* request-scoped gateways without a bootstrap instance. Retain the instance
+	* scan for legacy applications that only declare forwarding metadata.
 	*/
 	scanInstances(instances) {
+		const routes = /* @__PURE__ */ new Map();
+		for (const ep of this.#app.entrypoints.ofKind("websocket")) {
+			if (typeof ep.meta !== "object" || ep.meta === null || !("dispatcher" in ep.meta)) continue;
+			const meta = readWsEntrypointMeta(ep.meta);
+			if (meta.options.binding) routes.set(meta.path, {
+				path: meta.path,
+				binding: meta.options.binding,
+				options: { ...meta.options }
+			});
+		}
 		for (const instance of instances) {
 			if (!instance || typeof instance !== "object") continue;
-			this.wsGatewayRoutes.push(...collectWsGatewayRoutes(instance));
+			for (const route of collectWsGatewayRoutes(instance)) if (!routes.has(route.path)) routes.set(route.path, route);
 		}
+		this.#wsGatewayRoutes.splice(0, this.#wsGatewayRoutes.length, ...routes.values());
 	}
-	/** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+	/** @internal — upgrade routes discovered from the application's gateways. */
 	getWsGatewayRoutes() {
-		return this.wsGatewayRoutes;
+		return [...this.#wsGatewayRoutes];
 	}
 	/**
 	* Handle Cloudflare scheduled (cron) events.
@@ -241,18 +256,13 @@ var CloudflareApplication = class {
 	*/
 	async scheduled(event, env, ctx) {
 		assertCloudflareEnvironment(this.env, env);
-		const handlers = [...this.app.entrypoints.ofKind("cf:scheduled").map((ep) => ({
+		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) => ({
+		})), ...this.#app.entrypoints.ofKind("cf:vela-cron").map((ep) => ({
 			ep,
 			cron: entrypointString(ep.meta, "expression")
-		}))].filter((h) => h.cron === event.cron);
-		await Promise.all(handlers.map(({ ep }) => this.dispatchEntrypoint(ep, [
-			event,
-			env,
-			ctx
-		])));
+		}))].filter((h) => h.cron === event.cron).map(({ ep }) => this.dispatchEntrypoint(ep, event, env, ctx)));
 	}
 	/**
 	* Run one entrypoint handler inside a fresh request scope, through the
@@ -262,33 +272,61 @@ var CloudflareApplication = class {
 	* guard has no business rejecting a queue batch. Unclaimed errors rethrow
 	* so the platform's retry semantics stay intact.
 	*/
-	async dispatchEntrypoint(ep, args) {
+	async dispatchEntrypoint(ep, payload, env, platformContext) {
 		const targetClass = ep.token;
 		if (typeof targetClass !== "function") throw new Error("Entrypoint token must be a class.");
-		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);
-			if (typeof instance !== "object" || instance === null) throw new Error("Entrypoint must resolve to an object.");
-			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;
+		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",
+			source: `${targetClass.name}.${String(methodName)}`
+		};
+		let reported;
+		try {
+			await runInEntrypointScope(this.#app.getContainer(), async (scope, lifetime) => {
+				const moduleId = getEntrypointModuleId(scope, ep);
+				const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, payload, moduleId, scope);
+				const invocationContext = { waitUntil(promise) {
+					lifetime.waitUntil(promise);
+					platformContext.waitUntil(promise);
+				} };
+				let filters = [];
+				try {
+					filters = (await resolveScopedComponentsAsync("filter", targetClass, methodName, scope, moduleId)).toReversed();
+					const guards = await resolveScopedComponentsAsync("guard", targetClass, methodName, scope, moduleId);
+					const interceptors = await resolveScopedComponentsAsync("interceptor", targetClass, methodName, scope, moduleId);
+					await PipelineRunner.run({
+						context,
+						guards,
+						interceptors,
+						resolveArgs: async () => [
+							payload,
+							env,
+							invocationContext
+						],
+						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);
+						}
+					});
+				} catch (error) {
+					resolveErrorReporter(scope).report(error, reportContext);
+					for (const filter of filters) if (shouldFilterCatch(filter, error)) {
+						await filter.catch(error, context);
+						return;
+					}
+					reported = { error };
+					throw error;
 				}
-				throw error;
+			});
+		} catch (error) {
+			if (!reported || reported.error !== error) {
+				const completionError = reported && error instanceof AggregateError && error.errors[0] === reported.error ? error.errors[1] : error;
+				resolveErrorReporter(this.#app.getContainer()).report(completionError, reportContext);
 			}
-		});
+			throw error;
+		}
 	}
 	/**
 	* Handle Cloudflare Queue consumer events.
@@ -298,15 +336,10 @@ var CloudflareApplication = class {
 	*/
 	async queue(batch, env, ctx) {
 		assertCloudflareEnvironment(this.env, env);
-		const handlers = this.app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue);
-		await Promise.all(handlers.map((ep) => this.dispatchEntrypoint(ep, [
-			batch,
-			env,
-			ctx
-		])));
+		await settleEntrypoints(this.#app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue).map((ep) => this.dispatchEntrypoint(ep, batch, env, ctx)));
 	}
 	async close(signal) {
-		return this.app.close(signal);
+		return this.#app.close(signal);
 	}
 };
 //#endregion
@@ -675,13 +708,9 @@ StorageModule = __decorate([Module({
 //#endregion
 //#region src/services/kv-cache.store.ts
 /**
-* Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
-* the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
-* standalone from a typed environment factory: `new KVCacheStore(env.CACHE)`.
-* Reads return unknown JSON; validate values at the consuming boundary.
-*
-* Note: Cloudflare KV requires `expirationTtl >= 60s`, so sub-minute TTLs are
-* clamped up. Keep short TTLs on the memory tier; use KV for longer-lived entries.
+* Native KV JSON value store. Metadata retains logical expiry even when KV's
+* physical retention rounds up to its 60-second minimum. Legacy values without
+* metadata remain readable, but cannot safely backfill another tier.
 */
 var KVCacheStore = class {
 	ns;
@@ -689,16 +718,42 @@ var KVCacheStore = class {
 		this.ns = ns;
 	}
 	async get(key) {
-		const value = await this.ns.get(key, "json");
-		return value === null ? void 0 : value;
+		return (await this.getEntry(key))?.value;
+	}
+	async getEntry(key) {
+		const { value, metadata } = await this.ns.getWithMetadata(key, "json");
+		if (value === null) return void 0;
+		if (typeof metadata === "object" && metadata !== null && "velaCacheExpiresAt" in metadata) {
+			const expiresAt = metadata.velaCacheExpiresAt;
+			if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= Date.now()) return void 0;
+			return {
+				value,
+				expiresAt
+			};
+		}
+		return { 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);
+		if (ttl !== void 0 && (!Number.isFinite(ttl) || ttl < 0)) throw new TypeError("Cache TTL must be finite and nonnegative.");
+		if (ttl !== void 0) return this.setEntry(key, {
+			value,
+			expiresAt: Date.now() + ttl * 1e3
+		});
+		await this.ns.put(key, JSON.stringify(value));
+	}
+	async setEntry(key, entry) {
+		if (!Number.isFinite(entry.expiresAt)) throw new TypeError("Cache expiry must be finite.");
+		const remaining = (entry.expiresAt - Date.now()) / 1e3;
+		if (remaining <= 0) return this.del(key);
+		await this.ns.put(key, JSON.stringify(entry.value), {
+			expirationTtl: Math.max(60, Math.ceil(remaining)),
+			metadata: { velaCacheExpiresAt: entry.expiresAt }
+		});
 	}
 	async del(key) {
 		await this.ns.delete(key);
 	}
+	/** Namespace-wide, best effort. Use a dedicated value namespace; never use for scoped invalidation. */
 	async clear() {
 		let cursor;
 		do {
@@ -708,6 +763,27 @@ var KVCacheStore = class {
 		} while (cursor);
 	}
 };
+/**
+* Optional, eventually consistent generation store. Use a dedicated KV namespace
+* without TTL/lifecycle cleanup. Never delete/reset generations while entries can
+* survive. Concurrent writes and cached/negative reads prevent strong invalidation;
+* this is unsuitable for strict read-after-write or authorization revocation.
+*/
+var KVCacheInvalidationStore = class {
+	ns;
+	constructor(ns) {
+		this.ns = ns;
+	}
+	async getVersion(key) {
+		const value = await this.ns.get(key, "json");
+		if (value === null) return "initial";
+		if (typeof value !== "string" || value.length === 0 || value.length > 2048) throw new TypeError("Invalid cache generation.");
+		return value;
+	}
+	async invalidate(key) {
+		await this.ns.put(key, JSON.stringify(crypto.randomUUID()));
+	}
+};
 //#endregion
 //#region src/services/flagship-flag.driver.ts
 /**
@@ -846,6 +922,13 @@ registerEntrypointKind({
 	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.
 *
@@ -861,8 +944,9 @@ registerEntrypointKind({
 * ```
 */
 function Scheduled(cron) {
+	if (!parseCron(cron, { dialect: "cloudflare" })) throw new TypeError(`Invalid Cloudflare cron expression: ${cron}`);
 	return (target, propertyKey, _descriptor) => {
-		const existing = getMetadata(SCHEDULED_METADATA_KEY, target.constructor) ?? [];
+		const existing = getScheduledMetadata(target);
 		existing.push({
 			cron,
 			methodName: String(propertyKey)
@@ -870,6 +954,13 @@ function Scheduled(cron) {
 		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";
@@ -1018,6 +1109,6 @@ function durableObjectNonceStore(options) {
 	} };
 }
 //#endregion
-export { CloudflareApplication, CloudflareWebSocketModule, ConnectedSocket, DoCursorLog, DoPitrUnavailableError, Env, FlagshipFlagDriver, 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, readDoPitrBookmark };
+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 };
 
 //# sourceMappingURL=index.js.map